@envsa/repo-config/readme.md

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

<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->

<!-- title -->

# @envsa/repo-config

<!-- /title -->

<!-- badges -->

[![NPM Package @envsa/repo-config](https://img.shields.io/npm/v/@envsa/repo-config.svg)](https://npmjs.com/package/@envsa/repo-config)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- /badges -->

<!-- description -->

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

<!-- /description -->

## Overview

It's a `pnpm`-flavored shared config with some essential files for a fresh repo, plus automated linting for things like copyright notice dates, all accessible via a bundled command like tool named `envsa-repo`.

This includes the following:

- [`.npmrc`](https://pnpm.io/npmrc) with hoisting patterns for `shared-config` tool access
- `.gitignore` with typical patterns
- `.editorconfig` for basic code style settings
- `.vscode` extension recommendations (additional settings and recommendations come from other `shared-config` packages)
- `.github` folder with workflows:
  - `github-release.yml` Automates turning turning vX.X.X tags on main into GitHub releases with changelogs
  - `sync-metadata.yml` Populates GitHub repo metadata from package.json

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

<!-- recommendation -->

> [!IMPORTANT]
>
> **You can use this package on its own, but it's recommended to use [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/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 [`@envsa/shared-config`](https://www.npmjs.com/package/@envsa/shared-config), which also automatically invokes the command line functionality in this package via its `envsa` command

<!-- /recommendation -->

## Setup

### Run-once approach

If you just need to set up your `.npmrc` in anticipation of installing another shared config, you can run the script via `dlx` to copy the `.npmrc` to your home folder:

```sh
pnpm dlx @envsa/repo-config 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 @envsa/repo-config
   ```

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

   ```sh
   pnpm exec envsa-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/PERSONAL_ACCESS_TOKEN_ACTIONS')
   ```

### 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)                 | ✅            |

### Notes

Tailwind class regex

```jsonc
{
  "tailwindCSS.experimental.classRegex": [
    // Matches JavaScript classList API methods (add, remove, toggle)
    // Example: element.classList.add('px-4 py-2')
    ["classList.(?:add|remove|toggle)\\(([^)]*)\\)", "(?:'|\"|`)([^\"'`]*)(?:'|\"|`)"],

    // Matches Twig variable assignments ending with "class" or "classes" (case insensitive)
    // Example: {% set buttonClasses = "bg-blue-500 hover:bg-blue-700" %}
    ["{%\\s+set\\s+.*[Cc]lass(?:es)?\\s+=\\s+['\"](.*)['\"]\\s+%}"],

    // Matches properties ending with "class" or "classes" (case insensitive) in objects/configs
    // Example: buttonClass: "text-white font-bold"
    ["[a-zA-Z0-9]*[Cc]lass(?:es)?:\\s*['\"](.*)['\"]"],

    // Matches class definitions within a "classes" object structure
    // Example: classes: { root: "flex items-center", item: "px-4" }
    ["classes:\\s*{([^}]*?)}", ":\\s*['\"]([^'\"]*)['\"]"],

    // Matches class strings within twMerge() function calls
    // Example: twMerge("flex items-center p-4")
    ["twMerge\\(['\"]([^'\"]*)['\"]", "([^']*)"],

    // Matches PHP-style class assignments (single or array)
    // Examples:
    // 'class' => 'text-sm font-medium'
    // 'classes' => ['bg-red-500', 'text-white']
    ["['\"](?:class|classes)['\"]\\s*=>\\s*(?:['\"]([^'\"]*)['\"]|\\[([^\\]]*)\\])"],

    // Extracts individual strings from class arrays in PHP-style syntax
    // Example: 'classes' => ['bg-red-500', 'text-white']
    ["['\"](?:class|classes)['\"]\\s*=>\\s*\\[([^\\]]*)\\]", "['\"]([^'\"]*)['\"]"],
  ],
}
```

## Usage

### CLI

<!-- cli-help -->

#### Command: `envsa-repo`

Envsa's repository-related shared configuration tools.

This section lists top-level commands for `envsa-repo`.

Usage:

```txt
envsa-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. |

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

_See the sections below for more information on each subcommand._

#### Subcommand: `envsa-repo init`

Initialize by copying starter config files to your project root.

Usage:

```txt
envsa-repo init
```

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

#### Subcommand: `envsa-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
envsa-repo lint
```

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

#### Subcommand: `envsa-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
envsa-repo fix
```

| Option              | Description         | Type      |
| ------------------- | ------------------- | --------- |
| `--help`<br>`-h`    | Show help           | `boolean` |
| `--version`<br>`-v` | Show version number | `boolean` |

<!-- /cli-help -->

## Credits

[Eric Mika](https://github.com/kitschpatrol) is the author of the original [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) project on which this is based.

<!-- license -->

## License

[MIT](license.txt) © Liam Rella

<!-- /license -->