readme.md

@kitschpatrol/repo-config

Repository configuration and GitHub workflows for @kitschpatrol/shared-config.

Overview

It's a pnpm-flavored shared config with some essential files for a fresh repo, plus automated linting and fixing via a bundled CLI tool named ksc-repo.

The lint and fix commands check and correct:

• License year: Ensures the copyright year in license.txt matches the current year.
• Node.js version: Ensures engines.node and devEngines.runtime in package.json reflect the minimum Node.js versions actually required by your dependency tree (derived from the pnpm lockfile). If dev dependencies require a higher Node.js version than production dependencies, a separate devEngines.runtime entry is managed automatically.

This includes the following:

• pnpm-workspace.yaml with hoisting patterns for ksc tool access and trusted dependency installation scripts.
• .gitignore with typical patterns
• .vscode extension recommendations (additional settings and recommendations come from other @kitschpatrol/shared-config packages)
• .vscode/tasks.json with ksc-repo lint and ksc-repo fix tasks that run the checks above in --format machine mode and feed reported issues into VS Code's Problems panel via a problem matcher. (The other @kitschpatrol/shared-config packages contribute tasks for their own tools the same way.) If a tasks.json already exists, init merges by task label, leaving your own tasks untouched.
• .github folder with workflows:
  • github-release.yml Automates turning turning vX.X.X tags on main into GitHub releases with changelogs
  • set-github-metadata.yml Populates GitHub repo metadata from package.json
  • ci.yml Basic cross-platform CI action

In order to work around some hoisting issues related to plugin resolution in the other @kitschpatrol/shared-config packages, it's critical that it is applied before any other @kitschpatrol/shared-config packages are installed.

Important

You can use this package on its own, but it's recommended to use @kitschpatrol/shared-config instead for a single-dependency and single-package approach to linting and fixing your project.

This package is included as a dependency in @kitschpatrol/shared-config, which also automatically invokes the command line functionality in this package via its ksc command

Setup

Run-once approach

If you just need to set up your basic repository configuration files in anticipation of installing another @kitschpatrol shared configuration dependency, you can run the script via dlx to copy them to your project's root:

pnpm --package=@kitschpatrol/repo-config dlx ksc-repo init

Installation approach

Optionally, you can install the package if you think you'll ever want to regenerate the repo config files.

1. Add the package:

   pnpm add -D @kitschpatrol/repo-config

2. If / when you need to regenerate the repo config files, you can run the bundled script:

   pnpm exec ksc-repo init

GitHub Configuration

There are two options for authenticating the release workflow action:

GitHub Token

1. Ensure that read / write permissions are set for actions on the repository under Settings → Actions → General → Workflow permissions.

Personal Access token

If you want releases to come from your account instead of github_actions, then:

1. Create a fine-grained personal access token in your GitHub account with the following permissions:

   Permission	Access
   Administration	Read and write
   Contents	Read and write
   Metadata	Read-only

2. Add the token as a secret to your new GitHub repository.

   You can do this through the GitHub website under the Settings → Secrets and variables → Actions page under the key PERSONAL_ACCESS_TOKEN.

   Alternately, you can do this locally with the GitHub CLI and a credential manager like 1Password CLI:

   gh secret set PERSONAL_ACCESS_TOKEN --app actions --body $(op read 'op://Personal/GitHub Mika/PERSONAL_ACCESS_TOKEN')

GitHub Actions

Note: Action dependencies have been forked.

Original	Fork	Modifications
bullrich/generate-release-changelog	kitschpatrol/github-action-release-changelog	❌
softprops/action-gh-release	kitschpatrol/github-action-release	❌
kbrashears5/github-action-repo-sync	kitschpatrol/github-action-repo-sync	✅

Usage

CLI

Command: ksc-repo

Kitschpatrol's repository-related shared configuration tools.

This section lists top-level commands for ksc-repo.

Usage:

ksc-repo <command>

Command	Description
init	Initialize by copying starter config files to your project root.
lint	Check the repo for common issues. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.
fix	Fix common issues like outdated copyright years in license files. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.
print-config	Print minimum Node.js version constraints from the pnpm lockfile.

Option	Description	Type
--help -h	Show help	boolean
--version -v	Show version number	boolean

See the sections below for more information on each subcommand.

Subcommand: ksc-repo init

Initialize by copying starter config files to your project root.

Usage:

ksc-repo init

Option	Description	Type
--help -h	Show help	boolean
--version -v	Show version number	boolean

Subcommand: ksc-repo lint

Check the repo for common issues. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.

Usage:

ksc-repo lint

Option	Description	Type	Default
--format	Output format: "native" streams each tool's own output, "machine" prints one parseable line per issue for editor problem matchers, "json" prints an aggregate report.	"json" "machine" "native"	"native"
--cache	Use tool-native caches stored below node_modules/.cache/ksc at the workspace root. Disable with --no-cache.	boolean	true
--help -h	Show help	boolean
--version -v	Show version number	boolean

Subcommand: ksc-repo fix

Fix common issues like outdated copyright years in license files. Package-scoped. In a monorepo, it will also run in all packages below the current working directory.

Usage:

ksc-repo fix

Option	Description	Type	Default
--format	Output format: "native" streams each tool's own output, "machine" prints one parseable line per issue for editor problem matchers, "json" prints an aggregate report.	"json" "machine" "native"	"native"
--cache	Use tool-native caches stored below node_modules/.cache/ksc at the workspace root. Disable with --no-cache.	boolean	true
--help -h	Show help	boolean
--version -v	Show version number	boolean

Subcommand: ksc-repo print-config

Print minimum Node.js version constraints from the pnpm lockfile.

Usage:

ksc-repo print-config

Option	Description	Type
--help -h	Show help	boolean
--version -v	Show version number	boolean

VS Code tasks

ksc-repo init adds a .vscode/tasks.json with two tasks:

• ksc-repo lint runs ksc-repo lint --format machine across the whole project
• ksc-repo fix runs ksc-repo fix --format machine, applying auto-fixes and reporting whatever couldn't be fixed

If you're using the complete @kitschpatrol/shared-config package, you'd more likely want to run:

• ksc lint runs ksc lint --format machine, which runs all ksc lint tools across the whole project
• ksc fix runs ksc fix --format machine, which applies all ksc fix auto-fixes and reports anything unfixable

Run them via the Tasks: Run Task command (or the Terminal → Run Task… menu item).

Each task's problem matcher parses the machine-format output and populates VS Code's Problems panel with every reported issue, pointing to the offending file, line, and column.

The tasks share a problem matcher owner with the other @kitschpatrol/shared-config tasks, so the panel reflects the most recent run rather than stacking duplicates.

If your project already has a .vscode/tasks.json, init merges by task label: your own tasks are left alone, and same-label tasks are replaced with the latest definitions.

License

MIT © Eric Mika