@mrcointreau/shared-config 11.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrcointreau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,328 @@
+# @mrcointreau/shared-config
+
+Reusable GitHub Actions workflows and shared configurations for Node.js and Python projects.
+
+[![npm](https://img.shields.io/npm/v/@mrcointreau/shared-config.svg)](https://www.npmjs.com/package/@mrcointreau/shared-config)
+[![npm@beta](https://img.shields.io/npm/v/@mrcointreau/shared-config/main.svg?label=npm@beta)](https://www.npmjs.com/package/@mrcointreau/shared-config)
+
+## Overview
+
+This repository provides a collection of reusable GitHub Actions workflows and composite actions designed to standardize CI/CD pipelines across Node.js and Python projects. It also includes shareable ESLint and Prettier configurations for TypeScript projects.
+
+The workflows handle common tasks like linting, testing, building, security audits, semantic releases with OIDC trusted publishing (or token fallback), and documentation generation. All actions use pinned versions with commit SHAs for enhanced security.
+
+## Features
+
+- **Unified CI pipeline** for Node.js (npm) and Python (uv) projects
+- **Automated releases** with semantic-release and OIDC trusted publishing (or token fallback) to npm/PyPI
+- **Documentation generation** with TypeDoc (Node.js) and Sphinx (Python)
+- **Conventional commit enforcement** with commitlint
+- **Security audits** using npm audit and pip-audit
+- **Shareable configs** for ESLint and Prettier
+
+## How It Works
+
+This repository is built around reusable GitHub Actions workflows that delegate the real work to composite actions. You consume the workflows from your repo, and they call the composite actions in `actions/` with sensible defaults.
+
+- **Reusable workflows** live in `.github/workflows/` and are referenced with `uses: mrcointreau/shared-config/.github/workflows/<workflow>.yml@main`.
+- **Composite actions** live in `actions/` and implement the actual steps for CI, release, docs, and utilities.
+- **Pinned action versions** are used throughout to reduce supply-chain risk.
+
+Release behavior is intentionally branch-based:
+
+- **`main`**: Beta (prerelease) versions are published automatically on push.
+- **`release`**: Stable versions are published manually via `workflow_dispatch`.
+- Branch rules are defined in the semantic-release config (default action config), and can be overridden via `config-path`.
+
+Documentation behavior is consistent across languages:
+
+- Node uses TypeDoc, Python uses Sphinx.
+- The docs workflow can build only, or build + publish to GitHub Pages.
+
+## Workflows And Actions
+
+### Reusable Workflows
+
+- **`ci.yml`**: Runs audit, lint, test, and build for Node or Python. Delegates to `actions/ci/node` or `actions/ci/python`.
+- **`pr.yml`**: Runs CI plus conventional commit linting using `actions/utils/commitlint`.
+- **`release.yml`**: Runs semantic-release for versioning, tagging, and changelog generation via `actions/release/node` or `actions/release/python`. Use `auto-publish: true` to chain publishing.
+- **`publish.yml`**: Builds and publishes packages to npm/PyPI via `actions/publish/node` or `actions/publish/python`. Can be chained from release.yml or used standalone.
+- **`docs.yml`**: Generates docs (TypeDoc or Sphinx) and optionally publishes to GitHub Pages using `actions/docs/*`.
+
+### Composite Actions
+
+- **`actions/ci/node`**: npm-based audit/lint/test/build with configurable commands.
+- **`actions/ci/python`**: uv-based audit/lint/test/build with configurable commands.
+- **`actions/release/node`**: semantic-release for Node (versioning, tagging, changelog).
+- **`actions/release/python`**: semantic-release for Python (versioning, tagging, changelog).
+- **`actions/publish/node`**: Builds and publishes Node.js packages to npm with OIDC or token-based auth.
+- **`actions/publish/python`**: Builds and publishes Python packages to PyPI with OIDC or token-based auth.
+- **`actions/docs/typedoc`**: Generates TypeDoc output.
+- **`actions/docs/sphinx`**: Builds Sphinx documentation.
+- **`actions/docs/publish`**: Publishes built docs to GitHub Pages.
+- **`actions/utils/bot-token`**: Generates a GitHub App token for releases.
+- **`actions/utils/commitlint`**: Enforces conventional commit messages.
+
+### Internal Workflow
+
+`_release.yml` is used only by this repository to trigger releases and is not intended for reuse. It calls `release.yml` as a thin wrapper with this repo's defaults and enforces OIDC trusted publishing (publish tokens are not passed).
+
+## Getting Started
+
+### Using Workflows
+
+Reference workflows directly in your GitHub Actions:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: mrcointreau/shared-config/.github/workflows/ci.yml@main
+    with:
+      project-type: node # or 'python'
+```
+
+Set `project-type` to `node` or `python` and optionally override the runtime version (`node-version` or `python-version`).
+
+### Using ESLint/Prettier Configs
+
+Install the package:
+
+```bash
+npm install --save-dev @mrcointreau/shared-config
+```
+
+Install peer dependencies:
+
+```bash
+npm install --save-dev @eslint/js eslint eslint-config-prettier eslint-plugin-unused-imports prettier typescript-eslint
+```
+
+## Usage
+
+### CI Workflow
+
+The CI workflow runs audit, lint, test, and build steps.
+
+```yaml
+jobs:
+  ci:
+    uses: mrcointreau/shared-config/.github/workflows/ci.yml@main
+    with:
+      project-type: node
+      node-version: "22"
+      skip-audit: false
+      audit-level: moderate
+      skip-lint: false
+      skip-test: false
+      skip-build: false
+      lint-command: "npm run lint"
+      test-command: "npm test"
+      build-command: "npm run build"
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### PR Workflow
+
+The PR workflow runs CI plus conventional commit linting.
+
+```yaml
+jobs:
+  pr:
+    uses: mrcointreau/shared-config/.github/workflows/pr.yml@main
+    with:
+      project-type: node
+      run-commit-lint: true
+```
+
+### Release Workflow
+
+The Release workflow handles versioning, tagging, and changelog generation using semantic-release.
+Beta releases are published automatically from `main`. Stable releases require merging `main` into `release` and triggering `workflow_dispatch` manually.
+Use `auto-publish: true` to chain the publish workflow after a successful release.
+Use `back-merge: true` to automatically merge the release branch back to `main` after a stable release, keeping version files in sync.
+
+```yaml
+jobs:
+  release:
+    uses: mrcointreau/shared-config/.github/workflows/release.yml@main
+    with:
+      project-type: node
+      auto-publish: true # Chain publish after release
+      back-merge: true
+    secrets:
+      BOT_ID: ${{ secrets.BOT_ID }}
+      BOT_SK: ${{ secrets.BOT_SK }}
+```
+
+### Publish Workflow
+
+The Publish workflow builds and publishes packages to npm/PyPI with OIDC trusted publishing (or token fallback).
+It can be chained from `release.yml` via `auto-publish: true`, or used standalone for manual publishes.
+
+```yaml
+jobs:
+  publish:
+    uses: mrcointreau/shared-config/.github/workflows/publish.yml@main
+    with:
+      project-type: node
+      version: "1.0.0"
+```
+
+### Documentation Workflow
+
+The Docs workflow generates and publishes documentation to GitHub Pages.
+
+```yaml
+jobs:
+  docs:
+    uses: mrcointreau/shared-config/.github/workflows/docs.yml@main
+    with:
+      project-type: node
+      docs-path: docs
+      publish: true
+```
+
+### ESLint Configuration
+
+```javascript
+// eslint.config.mjs
+import config from "@mrcointreau/shared-config/eslint";
+
+export default config;
+```
+
+### Prettier Configuration
+
+```javascript
+// prettier.config.cjs
+module.exports = require("@mrcointreau/shared-config/prettier");
+```
+
+## Configuration
+
+### CI Workflow Inputs
+
+| Input               | Type    | Default    | Description                                                           |
+| ------------------- | ------- | ---------- | --------------------------------------------------------------------- |
+| `project-type`      | string  | _required_ | Project type: `node` or `python`                                      |
+| `working-directory` | string  | `.`        | Working directory                                                     |
+| `node-version`      | string  | `22`       | Node.js version (Node.js projects)                                    |
+| `python-version`    | string  | `3.12`     | Python version (Python projects)                                      |
+| `skip-audit`        | boolean | `false`    | Skip security audit step                                              |
+| `audit-level`       | string  | `moderate` | Minimum vulnerability severity: `low`, `moderate`, `high`, `critical` |
+| `skip-lint`         | boolean | `false`    | Skip linting step                                                     |
+| `skip-test`         | boolean | `false`    | Skip test step                                                        |
+| `skip-build`        | boolean | `false`    | Skip build step                                                       |
+| `pre-test-script`   | string  | `""`       | Script to run before tests                                            |
+| `lint-command`      | string  | _auto_     | Custom lint command                                                   |
+| `test-command`      | string  | _auto_     | Custom test command                                                   |
+| `build-command`     | string  | _auto_     | Custom build command                                                  |
+
+### Release Workflow Inputs
+
+| Input               | Type    | Default    | Description                                       |
+| ------------------- | ------- | ---------- | ------------------------------------------------- |
+| `project-type`      | string  | _required_ | Project type: `node` or `python`                  |
+| `working-directory` | string  | `.`        | Working directory                                 |
+| `node-version`      | string  | `22`       | Node.js version (Node.js projects)                |
+| `python-version`    | string  | `3.12`     | Python version (Python projects)                  |
+| `dry-run`           | boolean | `false`    | Run in dry-run mode                               |
+| `config-path`       | string  | `""`       | Custom semantic-release config path               |
+| `back-merge`        | boolean | `false`    | Merge release branch back to main after release   |
+| `auto-publish`      | boolean | `false`    | Chain publish workflow after successful release   |
+| `use-oidc`          | boolean | `true`     | Use OIDC trusted publishing (set to false to use tokens) |
+
+### Publish Workflow Inputs
+
+| Input               | Type   | Default    | Description                    |
+| ------------------- | ------ | ---------- | ------------------------------ |
+| `project-type`      | string | _required_ | Project type: `node` or `python` |
+| `version`           | string | _required_ | Version to publish (without v prefix) |
+| `working-directory` | string | `.`        | Working directory              |
+| `node-version`      | string | `22`       | Node.js version                |
+| `python-version`    | string | `3.12`     | Python version                 |
+| `use-oidc`          | boolean | `true`   | Use OIDC trusted publishing (set to false to use tokens) |
+
+### Release Workflow Secrets
+
+| Secret       | Required | Description                                        |
+| ------------ | -------- | -------------------------------------------------- |
+| `BOT_ID`     | Yes      | GitHub App ID for bot token generation             |
+| `BOT_SK`     | Yes      | GitHub App private key                             |
+| `NPM_TOKEN`  | No       | npm token (optional with OIDC trusted publishing)  |
+| `PYPI_TOKEN` | No       | PyPI token (optional with OIDC trusted publishing) |
+
+## Project Structure
+
+```
+.
+├── .github/workflows/     # Reusable GitHub Actions workflows
+│   ├── ci.yml             # CI workflow (audit, lint, test, build)
+│   ├── pr.yml             # PR workflow (CI + commit lint)
+│   ├── release.yml        # Release workflow (semantic-release)
+│   ├── publish.yml        # Publish workflow (build + npm/pypi)
+│   └── docs.yml           # Documentation workflow
+├── actions/               # Composite GitHub Actions
+│   ├── ci/                # CI actions
+│   │   ├── node/          # Node.js CI action
+│   │   └── python/        # Python CI action
+│   ├── release/           # Release actions
+│   │   ├── node/          # Node.js release action
+│   │   └── python/        # Python release action
+│   ├── publish/           # Publish actions
+│   │   ├── node/          # Node.js publish action
+│   │   └── python/        # Python publish action
+│   ├── docs/              # Documentation actions
+│   │   ├── typedoc/       # TypeDoc generation
+│   │   ├── sphinx/        # Sphinx generation
+│   │   └── publish/       # GitHub Pages publishing
+│   └── utils/             # Utility actions
+│       ├── bot-token/     # GitHub App token generation
+│       └── commitlint/    # Conventional commit linting
+└── configs/               # Shared configurations
+    ├── eslint.config.mjs  # ESLint config for TypeScript
+    └── prettier.config.cjs # Prettier config
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/mrcointreau/shared-config.git
+cd shared-config
+npm install
+```
+
+### Testing Workflows
+
+Test workflow changes by referencing your fork:
+
+```yaml
+jobs:
+  test:
+    uses: mrcointreau/shared-config/.github/workflows/ci.yml@main
+    with:
+      project-type: node
+```
+
+### Testing Composite Actions
+
+```yaml
+steps:
+  - uses: mrcointreau/shared-config/actions/ci/node@main
+    with:
+      node-version: "22"
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/configs/eslint.config.mjs

@@ -0,0 +1,47 @@
+/**
+ * Shared ESLint configuration for TypeScript projects.
+ * Uses TypeScript-ESLint recommended rules, unused imports detection,
+ * and Prettier integration.
+ */
+import { defineConfig } from 'eslint/config'
+import eslint from '@eslint/js'
+import prettier from 'eslint-config-prettier'
+import unusedImports from 'eslint-plugin-unused-imports'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  {
+    ignores: ['.eslintrc.js', 'node_modules/**', 'dist/**', 'build/**', 'coverage/**', '**/generated/**', '.idea/**', '.vscode/**'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.ts'],
+    plugins: {
+      'unused-imports': unusedImports,
+    },
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        projectService: true,
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-console': 'warn',
+      '@typescript-eslint/no-unused-vars': 'off',
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': ['warn', { ignoreRestSiblings: true, argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-unused-expressions': 'off',
+      'prefer-template': 'error',
+    },
+  },
+  {
+    files: ['**/*.spec.ts', '**/*.test.ts'],
+    rules: {
+      'no-restricted-syntax': 'off',
+    },
+  },
+  prettier,
+])

package/configs/prettier.config.cjs

@@ -0,0 +1,14 @@
+/**
+ * Shared Prettier configuration.
+ * Single quotes, no semicolons, 140 char line width, trailing commas.
+ */
+module.exports = {
+  singleQuote: true,
+  jsxSingleQuote: false,
+  semi: false,
+  tabWidth: 2,
+  trailingComma: 'all',
+  printWidth: 140,
+  endOfLine: 'lf',
+  arrowParens: 'always',
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mrcointreau/shared-config",
+  "version": "11.0.0",
+  "description": "Reusable GitHub Actions workflows and shared configurations for Node.js and Python projects",
+  "author": "mrcointreau",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrcointreau/shared-config.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrcointreau/shared-config/issues"
+  },
+  "homepage": "https://github.com/mrcointreau/shared-config#readme",
+  "keywords": [
+    "github-actions",
+    "ci-cd",
+    "eslint",
+    "prettier",
+    "shared-config",
+    "reusable-workflows"
+  ],
+  "exports": {
+    "./eslint": "./configs/eslint.config.mjs",
+    "./prettier": "./configs/prettier.config.cjs"
+  },
+  "files": [
+    "configs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@eslint/js": ">=9",
+    "eslint": ">=9",
+    "eslint-config-prettier": ">=9",
+    "eslint-plugin-unused-imports": ">=4",
+    "prettier": ">=3",
+    "typescript-eslint": ">=8"
+  }
+}