@kitschpatrol/repo-config

# @kitschpatrol/repo-config   [![NPM Package @kitschpatrol/repo-config](https://img.shields.io/npm/v/@kitschpatrol/repo-config.svg)](https://npmjs.com/package/@kitschpatrol/repo-config) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/)   **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`](https://pnpm.io/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) - `.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`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@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: ```sh 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: ```sh pnpm add -D @kitschpatrol/repo-config ``` 2. If / when you need to regenerate the repo config files, you can run the bundled script: ```sh 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](https://github.com/settings/tokens?type=beta) 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](https://cli.github.com/) and a credential manager like [1Password CLI](https://developer.1password.com/docs/cli/get-started/): ```sh 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](https://github.com/bullrich/generate-release-changelog) | [kitschpatrol/github-action-release-changelog](https://github.com/kitschpatrol/github-action-release-changelog) | ❌ | | [softprops/action-gh-release](https://github.com/softprops/action-gh-release) | [kitschpatrol/github-action-release](https://github.com/kitschpatrol/github-action-release) | ❌ | | [kbrashears5/github-action-repo-sync](https://github.com/kbrashears5/github-action-repo-sync) | [kitschpatrol/github-action-repo-sync](https://github.com/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: ```txt 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: ```txt 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: ```txt ksc-repo lint ``` | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--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: ```txt ksc-repo fix ``` | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--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: ```txt ksc-repo print-config ``` | Option | Description | Type | | ------------------- | ------------------- | --------- | | `--help` `-h` | Show help | `boolean` | | `--version` `-v` | Show version number | `boolean` |   ## License [MIT](license.txt) © [Eric Mika](https://ericmika.com)