@theholocron/cli 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/cli.mjs

@@ -446,6 +446,1201 @@ async function runNpmBumpVersions(input) {
 	};
 }
 //#endregion
+//#region src/templates/index.ts
+/**
+* All reusable workflow and composite action content bundled as string
+* constants so the CLI can push them to theholocron/.github without
+* needing filesystem access at runtime.
+*
+* These are the sources of truth — the YAML files in this directory
+* have been removed in favour of these constants.
+*/
+const ACTIONS = {
+	"setup/action": `\
+name: Setup
+description: Prepare the environment and install project dependencies.
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: false
+    default: "22.x"
+
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10"
+
+runs:
+  using: composite
+
+  steps:
+    - uses: ./.github/actions/setup-node
+      with:
+        node-version: \${{ inputs.node-version }}
+        pnpm-version: \${{ inputs.pnpm-version }}
+
+    - uses: ./.github/actions/install
+`,
+	"install/action": `\
+name: Install dependencies
+description: Install project dependencies with pnpm frozen lockfile.
+
+runs:
+  using: composite
+
+  steps:
+    - name: Install dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile
+`,
+	"setup-node/action": `\
+name: Setup Node
+description: Install pnpm and Node.js with pnpm dependency caching.
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: false
+    default: "22.x"
+
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10"
+
+runs:
+  using: composite
+
+  steps:
+    - name: Setup pnpm
+      uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      with:
+        version: \${{ inputs.pnpm-version }}
+
+    - name: Setup Node.js
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: \${{ inputs.node-version }}
+        cache: pnpm
+`
+};
+const REUSABLE_WORKFLOWS = {
+	audit: `\
+name: Audit
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      build-script:
+        description: Script to build before analyzing bundle size
+        type: string
+        required: false
+        default: pnpm build
+    secrets:
+      BUNDLEWATCH_GITHUB_TOKEN:
+        required: true
+
+jobs:
+  bundle-size:
+    name: Audit the bundle size
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    concurrency:
+      group: audit-\${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - uses: jackyef/bundlewatch-gh-action@01f51133d3580a6daa046ca83eb233d79735e1c1 # 0.3.0
+        name: Analyze using BundleWatch
+        with:
+          build-script: \${{ inputs.build-script }}
+          bundlewatch-github-token: \${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
+`,
+	"bookkeeping-pr": `\
+name: PR Bookkeeping
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      configuration-path:
+        description: Path to the labeler configuration file in the calling repo
+        type: string
+        required: false
+        default: .github/labeler.yml
+
+jobs:
+  label:
+    name: Add Labels to PRs
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: bookkeeping-pr-\${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - uses: github/issue-labeler@c1b0f9f52a63158c4adc09425e858e87b32e9685 # v3.4
+        with:
+          # Fall back to default path when triggered directly (not via workflow_call)
+          # because inputs.* defaults only apply on workflow_call events.
+          configuration-path: \${{ inputs.configuration-path || '.github/labeler.yml' }}
+          include-title: 1
+          include-body: 0
+          sync-labels: 1
+          enable-versioned-regex: 0
+          repo-token: \${{ github.token }}
+`,
+	codeql: `\
+name: CodeQL
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      language:
+        description: CodeQL language to analyze
+        type: string
+        required: false
+        default: javascript-typescript
+
+jobs:
+  analyze:
+    name: Analyze (\${{ inputs.language }})
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    # Do not cancel in-progress security scans.
+    concurrency:
+      group: codeql-\${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: github/codeql-action/init@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Initialize CodeQL
+        with:
+          languages: \${{ inputs.language }}
+
+      - uses: github/codeql-action/autobuild@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Autobuild
+
+      - uses: github/codeql-action/analyze@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Analyze
+        with:
+          category: /language:\${{ inputs.language }}
+`,
+	dependencies: `\
+name: Dependencies
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    secrets:
+      merge-token:
+        description: >
+          Optional privileged token for auto-merge. Falls back to GITHUB_TOKEN.
+          Required when branch protection enforces required reviews — GITHUB_TOKEN
+          cannot approve its own PRs.
+        required: false
+
+jobs:
+  dependabot:
+    name: Update the dependencies
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: dependencies-\${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a # v2
+        name: Fetch Dependabot metadata
+        id: metadata
+
+      - run: gh pr merge --auto --squash "$PR_URL"
+        # --squash is intentional: repoPolicy sets allow_merge_commit: false,
+        # so --merge would fail on any repo using the standard preset.
+        name: Enable auto-merge for Dependabot PRs
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        env:
+          PR_URL: \${{ github.event.pull_request.html_url }}
+          GH_TOKEN: \${{ secrets.merge-token || github.token }}
+`,
+	greetings: `\
+name: Greetings
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+jobs:
+  greeting:
+    name: Greet first-time contributors
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Group by the issue/PR number so duplicate events don't race each other.
+    concurrency:
+      group: greetings-\${{ github.event.issue.number || github.event.pull_request.number }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        name: Greet on first contribution
+        with:
+          script: |
+            // Only greet on the initial open — ignore synchronize, reopened, etc.
+            if (context.payload.action !== 'opened') return;
+
+            const actor = context.actor;
+            const { owner, repo } = context.repo;
+
+            // Payload inspection is more reliable than context.eventName for detecting
+            // whether this is an issue vs. PR event — works regardless of how GitHub
+            // propagates event names through workflow_call chains.
+            const isIssue = !!context.payload.issue && !context.payload.pull_request;
+            // listForRepo returns both issues and PRs (GitHub treats PRs as issues),
+            // sorted newest-first. Filter by type to track first-issue and first-PR
+            // independently, and avoid search-index eventual-consistency lag.
+            const { data: recent } = await github.rest.issues.listForRepo({
+              owner, repo,
+              creator: actor,
+              state: 'all',
+              per_page: 100
+            });
+
+            const sameType = recent.filter(item =>
+              isIssue ? !item.pull_request : !!item.pull_request
+            );
+
+            if (sameType.length !== 1) return;
+            const body = isIssue
+              ? \`Hey @\${actor}!\\n\\nWe really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.\`
+              : \`Hey @\${actor}!\\n\\nWe really appreciate you taking the time to help out with this PR. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.\`;
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: context.issue.number,
+              body
+            });
+`,
+	lint: `\
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      prettier-config:
+        type: string
+        required: false
+        default: prettier.config.js
+      yaml-config:
+        type: string
+        required: false
+        default: yamllint.config.yml
+      enable-auto-commit:
+        description: Auto-commit super-linter fixes via GPG-signed commit
+        type: boolean
+        required: false
+        default: false
+    secrets:
+      SUPER_LINTER_GPG_PRIVATE_KEY:
+        required: false
+      SUPER_LINTER_GPG_PASSPHRASE:
+        required: false
+
+jobs:
+  super-lint:
+    name: Lint entire codebase
+    permissions:
+      contents: write
+      statuses: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+          token: \${{ github.token }}
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - uses: super-linter/super-linter/slim@b92721f792f381cedc002ecdbb9847a15ece5bb8 # v7.1.0
+        name: Run Super Linter
+        env:
+          GITHUB_TOKEN: \${{ github.token }}
+          ANNOTATE_ONLY: true
+          DISABLE_COMMENTS: false
+          IGNORE_GITIGNORED_FILES: true
+          LINTER_RULES_PATH: /
+          EDITORCONFIG_FILE_NAME: ".editorconfig-checker.json"
+          FIX_ENV: true
+          FIX_GRAPHQL_PRETTIER: true
+          FIX_HTML_PRETTIER: true
+          FIX_JAVASCRIPT_PRETTIER: true
+          FIX_JSX_PRETTIER: true
+          FIX_MARKDOWN_PRETTIER: true
+          FIX_TSX: true
+          FIX_TYPESCRIPT_PRETTIER: true
+          PRETTIER_CONFIG: \${{ inputs.prettier-config }}
+          VALIDATE_DOCKERFILE: true
+          VALIDATE_EDITORCONFIG: true
+          VALIDATE_ENV: true
+          VALIDATE_GIT_COMMITLINT: true
+          VALIDATE_GIT_MERGE_CONFLICT_MARKERS: true
+          VALIDATE_GITHUB_ACTIONS: true
+          VALIDATE_GITLEAKS: true
+          VALIDATE_GRAPHQL_PRETTIER: true
+          VALIDATE_HTML_PRETTIER: true
+          VALIDATE_JAVASCRIPT_PRETTIER: true
+          VALIDATE_JSX_PRETTIER: true
+          VALIDATE_MARKDOWN_PRETTIER: true
+          VALIDATE_TSX: true
+          VALIDATE_TYPESCRIPT_PRETTIER: true
+          VALIDATE_YAML: true
+          YAML_CONFIG_FILE: \${{ inputs.yaml-config }}
+
+      - uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6
+        name: Import GPG Key
+        # Conditions mirror auto-commit exactly — no point importing GPG if the
+        # commit step will be skipped (fork PR, default branch, or secret unset).
+        if: >
+          inputs.enable-auto-commit == true &&
+          github.event.pull_request != null &&
+          github.event.pull_request.head.repo.full_name == github.repository &&
+          github.ref_name != github.event.repository.default_branch &&
+          secrets.SUPER_LINTER_GPG_PRIVATE_KEY != ''
+        with:
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+          GPG_PRIVATE_KEY: \${{ secrets.SUPER_LINTER_GPG_PRIVATE_KEY }}
+          PASSPHRASE: \${{ secrets.SUPER_LINTER_GPG_PASSPHRASE }}
+
+      - uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5
+        name: Commit and push linting fixes
+        if: >
+          inputs.enable-auto-commit == true &&
+          github.event.pull_request != null &&
+          github.event.pull_request.head.repo.full_name == github.repository &&
+          github.ref_name != github.event.repository.default_branch &&
+          secrets.SUPER_LINTER_GPG_PRIVATE_KEY != ''
+        with:
+          branch: \${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
+          commit_message: "chore: fix linting issues"
+          commit_options: "--no-verify --signoff"
+          commit_user_name: super-linter
+          commit_user_email: super-linter@super-linter.dev
+`,
+	release: `\
+name: Release
+
+# Semantic-release with OIDC Trusted Publishing — no NPM_TOKEN required.
+# The calling repo must have a .releaserc.json that configures branches,
+# plugins, and any publish options. npm@11+ is installed to support OIDC.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      run-build:
+        description: Run \`pnpm build\` before releasing
+        type: boolean
+        required: false
+        default: true
+
+jobs:
+  release:
+    name: Semantic release
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    # Do not cancel in-progress releases — a partial release is worse than a slow one.
+    concurrency:
+      group: release-\${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+          token: \${{ github.token }}
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: npm install -g npm@11 sigstore
+        name: Upgrade npm for OIDC support
+        # sigstore is required by libnpmpublish/provenance.js at module parse
+        # time — before any config takes effect. Some npm 11.x builds stopped
+        # bundling it; installing it globally into the same prefix ensures it
+        # resolves regardless of npm version. (Discovered 2026-07-09.)
+
+      - run: pnpm build
+        name: Build
+        if: \${{ inputs.run-build == true }}
+
+      - run: npx semantic-release
+        name: Release
+        env:
+          GITHUB_TOKEN: \${{ github.token }}
+          NPM_CONFIG_PROVENANCE: true
+`,
+	review: `\
+name: Review
+
+# ReviewDog is the annotation layer — posts inline PR diff annotations.
+# Runs on pull_request only: inline annotations require PR context,
+# and branch protection ensures all changes go through PRs anyway.
+# super-linter (lint.yml) is the CI gate covering push + PR events.
+# Gitleaks and YAML are intentionally duplicated: super-linter gates
+# merges; ReviewDog surfaces exact line annotations in the PR diff.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+concurrency:
+  group: review-\${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  reviewdog:
+    name: Review PRs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup
+        if: \${{ hashFiles('pnpm-lock.yaml') != '' }}
+        uses: theholocron/.github/.github/actions/setup@main
+
+      - name: Install ReviewDog
+        uses: reviewdog/action-setup@d8a7baabd7f3e8544ee4dbde3ee41d0011c3a93f # v1
+        with:
+          reviewdog_version: latest
+
+      #
+      # Always applicable
+      #
+
+      - name: Gitleaks (secrets)
+        uses: reviewdog/action-gitleaks@2b7b5685e3e3eecddab5d30cfa04f18123031421 # v1
+        with:
+          reporter: github-pr-check
+
+      - name: YamlLint
+        uses: reviewdog/action-yamllint@b5f7217d8c815ae374d1d55840d5e569d82f01f0 # v1
+        with:
+          reporter: github-pr-check
+          yamllint_flags: >-
+            \${{ hashFiles('yamllint.config.yml') != ''
+                && format('-c {0}/yamllint.config.yml {0}', github.workspace)
+                || github.workspace }}
+
+      - name: ActionLint (GitHub Actions)
+        if: \${{ hashFiles('.github/workflows/*.yml', '.github/workflows/*.yaml') != '' }}
+        uses: reviewdog/action-actionlint@6fb7acc99f4a1008869fa8a0f09cfca740837d9d # v1
+        with:
+          reporter: github-pr-check
+
+      #
+      # TypeScript / JavaScript
+      #
+
+      - name: ESLint
+        if: >-
+          \${{
+            hashFiles(
+              '**/eslint.config.js',
+              '**/eslint.config.mjs',
+              '**/eslint.config.cjs',
+              '**/eslint.config.ts',
+              '**/.eslintrc',
+              '**/.eslintrc.js',
+              '**/.eslintrc.cjs',
+              '**/.eslintrc.json',
+              '**/.eslintrc.yaml',
+              '**/.eslintrc.yml'
+            ) != ''
+          }}
+        uses: reviewdog/action-eslint@556a3fdaf8b4201d4d74d406013386aa4f7dab96 # v1
+        with:
+          reporter: github-pr-check
+          eslint_flags: .
+
+      - name: TypeScript
+        if: \${{ hashFiles('**/tsconfig.json') != '' }}
+        uses: EPMatt/reviewdog-action-tsc@63d923a3c5b4497671940b8874f58a404e2351b5 # v1
+        with:
+          reporter: github-pr-check
+
+      #
+      # Shell
+      #
+
+      - name: ShellCheck
+        if: \${{ hashFiles('**/*.sh') != '' }}
+        uses: reviewdog/action-shellcheck@4c07458293ac342d477251099501a718ae5ef86e # v1
+        with:
+          reporter: github-pr-check
+          fail_level: none
+
+      #
+      # Docker
+      #
+
+      - name: Hadolint
+        if: >-
+          \${{
+            hashFiles(
+              '**/Dockerfile',
+              '**/*.Dockerfile',
+              '**/Containerfile'
+            ) != ''
+          }}
+        uses: reviewdog/action-hadolint@1b2cfa6ba72072ad35158d7ff3aa49bbdc03506d # v1
+        with:
+          reporter: github-pr-check
+          fail_level: none
+
+      #
+      # Environment files
+      #
+
+      - name: dotenv-linter
+        if: \${{ hashFiles('**/.env*') != '' }}
+        uses: dotenv-linter/action-dotenv-linter@21287e2624aaf2dc8da5dd8ccfe8e49c63501116 # v2
+        with:
+          reporter: github-code-suggestions
+
+      #
+      # Documentation
+      #
+
+      - name: Alex (inclusive language)
+        if: \${{ hashFiles('**/*.md') != '' }}
+        uses: reviewdog/action-alex@347481655add010a2ae302df34b57c9bcfa0d6e4 # v1
+        with:
+          reporter: github-pr-check
+`,
+	stale: `\
+name: Stale
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      days-before-stale:
+        description: Days of inactivity before an issue is marked stale
+        type: number
+        required: false
+        default: 30
+      days-before-close:
+        description: Days of inactivity after stale label before closing
+        type: number
+        required: false
+        default: 5
+
+jobs:
+  stale:
+    name: Mark stale issues and pull requests
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9
+        name: Run Stale
+        with:
+          close-issue-message: >
+            This issue was closed because it has been stalled for
+            \${{ inputs.days-before-close }} days with no activity.
+          days-before-close: \${{ inputs.days-before-close }}
+          days-before-stale: \${{ inputs.days-before-stale }}
+          exempt-all-pr-milestones: true
+          stale-issue-label: wontfix
+          stale-issue-message: >
+            This issue is stale because it has been open \${{ inputs.days-before-stale }}
+            days with no activity. Remove the stale label or comment, or this will be
+            closed in \${{ inputs.days-before-close }} days.
+          stale-pr-label: wontfix
+          stale-pr-message: >
+            This PR is stale because it has been open \${{ inputs.days-before-stale }}
+            days with no activity. Remove the stale label or comment, or this will be
+            closed in \${{ inputs.days-before-close }} days.
+`,
+	test: `\
+name: Test
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+jobs:
+  unit:
+    name: Run tests and collect coverage
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm test -- --coverage
+        name: Run tests with coverage
+
+      - uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
+        name: Upload results to Codecov
+        with:
+          token: \${{ secrets.CODECOV_TOKEN }}
+`,
+	"sync-github": `\
+name: Sync GitHub Templates
+
+# Builds the holocron CLI from source and pushes updated workflow templates
+# and composite actions to downstream .github repos. Runs whenever the
+# template source files change on main or alpha.
+#
+# Secrets required:
+#   SYNC_TOKEN — fine-grained PAT or GitHub App token with Contents write
+#                access to the primary and secondary repos.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      primary-repo:
+        description: >
+          Primary .github repo — receives composite actions, reusable workflows,
+          and thin-caller templates. Requires a PR (branch protection assumed).
+        type: string
+        required: false
+        default: theholocron/.github
+      secondary-repos:
+        description: >
+          Space-separated list of secondary repos (reusable workflows + thin
+          callers only, no composite actions). Pushed directly to main.
+        type: string
+        required: false
+        default: ""
+      sync-branch:
+        description: Branch name used for the primary-repo PR
+        type: string
+        required: false
+        default: chore/sync-templates
+    secrets:
+      SYNC_TOKEN:
+        required: true
+
+jobs:
+  sync:
+    name: Sync templates
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm build
+        name: Build CLI
+
+      - name: Sync primary repo (PR)
+        run: >
+          node packages/cli/dist/cli.mjs sync-github
+          --repo \${{ inputs.primary-repo }}
+          --branch \${{ inputs.sync-branch }}
+          --pr
+        env:
+          GITHUB_TOKEN: \${{ secrets.SYNC_TOKEN }}
+
+      - name: Sync secondary repos (direct push)
+        if: \${{ inputs.secondary-repos != '' }}
+        run: |
+          for repo in \${{ inputs.secondary-repos }}; do
+            node packages/cli/dist/cli.mjs sync-github --repo "$repo"
+          done
+        env:
+          GITHUB_TOKEN: \${{ secrets.SYNC_TOKEN }}
+`,
+	typecheck: `\
+name: Typecheck
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+jobs:
+  typecheck:
+    name: tsc --noEmit
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm typecheck
+        name: Type check
+`
+};
+//#endregion
+//#region src/commands/setup-workflows.ts
+/**
+* Thin workflow wrapper templates for `holocron setup`.
+*
+* Each entry is a complete `.github/workflows/<name>.yml` that delegates
+* to the corresponding reusable `ci-<name>.yml` in `theholocron/.github`.
+* Files are overwritten on each setup run — they are generated artifacts.
+*/
+const WORKFLOW_REPO = "theholocron/.github";
+const WORKFLOW_REF = "main";
+function ref(name) {
+	return `${WORKFLOW_REPO}/.github/workflows/${name}.yml@${WORKFLOW_REF}`;
+}
+/** Header prepended when holocron setup writes a thin caller to a repo. */
+const WORKFLOW_HEADER = `\
+# AUTO-GENERATED by holocron — do not edit directly.
+# Source: theholocron/holocron · packages/cli/src/commands/setup-workflows.ts
+# Run \`holocron setup\` to regenerate.
+
+`;
+const WORKFLOW_TEMPLATES = {
+	lint: `\
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: lint-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  statuses: write
+
+jobs:
+  lint:
+    name: Lint
+    uses: ${ref("lint")}
+    secrets: inherit
+    with:
+      enable-auto-commit: true
+`,
+	test: `\
+name: Test
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: test-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    uses: ${ref("test")}
+    secrets: inherit
+`,
+	typecheck: `\
+name: Typecheck
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: typecheck-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Typecheck
+    uses: ${ref("typecheck")}
+    secrets: inherit
+`,
+	codeql: `\
+name: CodeQL
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    uses: ${ref("codeql")}
+    secrets: inherit
+`,
+	review: `\
+name: Review
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+concurrency:
+  group: review-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  review:
+    name: Review
+    uses: ${ref("review")}
+    secrets: inherit
+`,
+	release: `\
+name: Release
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+      - alpha
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    uses: ${ref("release")}
+    secrets: inherit
+`,
+	stale: `\
+name: Stale
+
+on: # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "30 1 * * *"
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    uses: ${ref("stale")}
+    secrets: inherit
+`,
+	greetings: `\
+name: Greetings
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+  issues:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  greetings:
+    uses: ${ref("greetings")}
+    secrets: inherit
+`,
+	dependencies: `\
+name: Dependencies
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependencies:
+    uses: ${ref("dependencies")}
+    secrets: inherit
+`,
+	"bookkeeping-pr": `\
+name: PR Bookkeeping
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+    types:
+      - opened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  bookkeeping:
+    uses: ${ref("bookkeeping-pr")}
+    secrets: inherit
+`,
+	audit: `\
+name: Audit
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    uses: ${ref("audit")}
+    secrets: inherit
+`,
+	"sync-github": `\
+name: Sync GitHub Templates
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+    paths:
+      - packages/cli/src/templates/index.ts
+      - packages/cli/src/commands/setup-workflows.ts
+
+concurrency:
+  group: sync-github-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    name: Sync
+    uses: ${ref("sync-github")}
+    with:
+      secondary-repos: theholocron/.github-private
+    secrets:
+      SYNC_TOKEN: \${{ secrets.SYNC_TOKEN }}
+`
+};
+const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
+//#endregion
+//#region src/commands/sync-github.ts
+const DEFAULT_REPO = "theholocron/.github";
+const API_BASE = "https://api.github.com";
+function reusableHeader(source) {
+	return [
+		`# AUTO-GENERATED — do not edit in theholocron/.github directly.`,
+		`# Source:  theholocron/holocron · ${source}`,
+		`# Synced:  ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`# Tool:    holocron sync-github`,
+		`# Changes: edit source in theholocron/holocron and push to alpha or main.`,
+		``
+	].join("\n");
+}
+function thinCallerHeader() {
+	return [
+		`# AUTO-GENERATED — do not edit in theholocron/.github directly.`,
+		`# Source:  theholocron/holocron · packages/cli/src/commands/setup-workflows.ts`,
+		`# Synced:  ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`# Tool:    holocron sync-github`,
+		`# Changes: edit setup-workflows.ts in theholocron/holocron and push.`,
+		``
+	].join("\n");
+}
+function buildBatch(repo) {
+	const files = [];
+	if (repo === DEFAULT_REPO) for (const [name, content] of Object.entries(ACTIONS)) files.push({
+		path: `.github/actions/${name}.yml`,
+		content: reusableHeader(`packages/cli/src/templates/index.ts`) + content
+	});
+	for (const [name, content] of Object.entries(REUSABLE_WORKFLOWS)) files.push({
+		path: `.github/workflows/${name}.yml`,
+		content: reusableHeader(`packages/cli/src/templates/index.ts`) + content
+	});
+	for (const [name, content] of Object.entries(WORKFLOW_TEMPLATES)) files.push({
+		path: `workflow-templates/${name}.yml`,
+		content: thinCallerHeader() + content
+	});
+	return files;
+}
+async function runSyncGithub(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const repo = input.repo ?? DEFAULT_REPO;
+	const [owner, repoName] = repo.split("/");
+	const { token, dryRun = false, branch, createPr = false } = input;
+	const message = input.message ?? `chore: sync from theholocron/holocron`;
+	const fetchFn = input.fetch ?? globalThis.fetch;
+	const headers = {
+		Authorization: `Bearer ${token}`,
+		Accept: "application/vnd.github+json",
+		"Content-Type": "application/json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+	print(`holocron sync-github${dryRun ? " (dry-run)" : ""}`);
+	print(`  repo:   ${repo}`);
+	if (branch) print(`  branch: ${branch}`);
+	print("");
+	const batch = buildBatch(repo);
+	let created = 0;
+	let updated = 0;
+	let unchanged = 0;
+	for (const file of batch) {
+		const ref = branch ? `?ref=${encodeURIComponent(branch)}` : "";
+		const url = `${API_BASE}/repos/${owner}/${repoName}/contents/${file.path}`;
+		const newContent = Buffer.from(file.content, "utf8").toString("base64");
+		let existingSha;
+		let existingContent;
+		try {
+			const getRes = await fetchFn(`${url}${ref}`, { headers });
+			if (getRes.ok) {
+				const data = await getRes.json();
+				existingSha = data.sha;
+				existingContent = data.content.replace(/\n/g, "");
+			}
+		} catch {}
+		if (existingContent === newContent) {
+			print(`  · unchanged  ${file.path}`);
+			unchanged++;
+			continue;
+		}
+		const verb = existingSha ? "updated " : "created ";
+		if (dryRun) {
+			print(`  ~ ${verb} ${file.path}`);
+			if (existingSha) updated++;
+			else created++;
+			continue;
+		}
+		const body = {
+			message,
+			content: newContent
+		};
+		if (existingSha) body.sha = existingSha;
+		if (branch) body.branch = branch;
+		const putRes = await fetchFn(url, {
+			method: "PUT",
+			headers,
+			body: JSON.stringify(body)
+		});
+		if (!putRes.ok) {
+			const err = await putRes.json();
+			const msg = `failed to push ${file.path}: ${err.message ?? putRes.status}`;
+			print(`  ✗ ${msg}`);
+			return {
+				status: "fail",
+				created,
+				updated,
+				unchanged,
+				message: msg
+			};
+		}
+		print(`  ✓ ${verb} ${file.path}`);
+		if (existingSha) updated++;
+		else created++;
+	}
+	const changed = created + updated;
+	print("");
+	print(`  ${created} created, ${updated} updated, ${unchanged} unchanged`);
+	let prUrl;
+	if (branch && createPr && changed > 0 && !dryRun) {
+		const prRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/pulls`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				title: message,
+				head: branch,
+				base: "main",
+				body: "Auto-generated by `holocron sync-github`. Review and merge to apply template updates."
+			})
+		});
+		if (prRes.ok) {
+			prUrl = (await prRes.json()).html_url;
+			print(`  → PR opened: ${prUrl}`);
+		} else {
+			const err = await prRes.json();
+			if (err.errors?.some((e) => e.message.includes("already exists"))) print(`  → PR already open for ${branch} — branch updated, ready to merge`);
+			else print(`  ⚠ PR creation failed: ${err.message ?? prRes.status}`);
+		}
+	}
+	return {
+		status: dryRun ? "dry-run" : "ok",
+		created,
+		updated,
+		unchanged,
+		prUrl
+	};
+}
+//#endregion
 //#region src/commands/npm-publish-initial.ts
 /**
 * `holocron npm publish-initial` — bottles up the chicken-and-egg
@@ -1865,241 +3060,6 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
-//#region src/commands/setup-workflows.ts
-/**
-* Thin workflow wrapper templates for `holocron setup`.
-*
-* Each entry is a complete `.github/workflows/<name>.yml` that delegates
-* to the corresponding reusable `ci-<name>.yml` in `theholocron/.github`.
-* Files are overwritten on each setup run — they are generated artifacts.
-*/
-const WORKFLOW_REPO = "theholocron/.github";
-const WORKFLOW_REF = "main";
-function ref(name) {
-	return `${WORKFLOW_REPO}/.github/workflows/${name}.yml@${WORKFLOW_REF}`;
-}
-/** Header prepended when holocron setup writes a thin caller to a repo. */
-const WORKFLOW_HEADER = `\
-# AUTO-GENERATED by holocron — do not edit directly.
-# Source: theholocron/holocron · packages/cli/src/commands/setup-workflows.ts
-# Run \`holocron setup\` to regenerate.
-
-`;
-const WORKFLOW_TEMPLATES = {
-	lint: `\
-name: Lint
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches: [main, alpha]
-  pull_request:
-
-concurrency:
-  group: lint-\${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  statuses: write
-
-jobs:
-  lint:
-    name: Lint
-    uses: ${ref("lint")}
-    secrets: inherit
-    with:
-      enable-auto-commit: true
-`,
-	test: `\
-name: Test
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches: [main, alpha]
-  pull_request:
-
-concurrency:
-  group: test-\${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    name: Test
-    uses: ${ref("test")}
-    secrets: inherit
-`,
-	typecheck: `\
-name: Typecheck
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches: [main, alpha]
-  pull_request:
-
-concurrency:
-  group: typecheck-\${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  typecheck:
-    name: Typecheck
-    uses: ${ref("typecheck")}
-    secrets: inherit
-`,
-	codeql: `\
-name: CodeQL
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  schedule:
-    - cron: "0 0 * * 1"
-
-permissions:
-  actions: read
-  contents: read
-  security-events: write
-
-jobs:
-  codeql:
-    uses: ${ref("codeql")}
-    secrets: inherit
-`,
-	review: `\
-name: Review
-
-on: # yamllint disable-line rule:truthy
-  pull_request:
-
-concurrency:
-  group: review-\${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-  checks: write
-  pull-requests: write
-
-jobs:
-  review:
-    name: Review
-    uses: ${ref("review")}
-    secrets: inherit
-`,
-	release: `\
-name: Release
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: write
-  id-token: write
-  issues: write
-  pull-requests: write
-
-jobs:
-  release:
-    uses: ${ref("release")}
-    secrets: inherit
-`,
-	stale: `\
-name: Stale
-
-on: # yamllint disable-line rule:truthy
-  schedule:
-    - cron: "30 1 * * *"
-
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-
-jobs:
-  stale:
-    uses: ${ref("stale")}
-    secrets: inherit
-`,
-	greetings: `\
-name: Greetings
-
-on: # yamllint disable-line rule:truthy
-  pull_request:
-  issues:
-
-permissions:
-  issues: write
-  pull-requests: write
-
-jobs:
-  greetings:
-    uses: ${ref("greetings")}
-    secrets: inherit
-`,
-	dependencies: `\
-name: Dependencies
-
-on: # yamllint disable-line rule:truthy
-  pull_request:
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  dependencies:
-    uses: ${ref("dependencies")}
-    secrets: inherit
-`,
-	"bookkeeping-pr": `\
-name: PR Bookkeeping
-
-on: # yamllint disable-line rule:truthy
-  pull_request:
-    types:
-      - opened
-      - edited
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  bookkeeping:
-    uses: ${ref("bookkeeping-pr")}
-    secrets: inherit
-`,
-	audit: `\
-name: Audit
-
-on: # yamllint disable-line rule:truthy
-  push:
-    branches: [main, alpha]
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  audit:
-    uses: ${ref("audit")}
-    secrets: inherit
-`
-};
-const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
-//#endregion
 //#region src/commands/setup.ts
 const DEPENDABOT_CONFIG = `\
 # AUTO-GENERATED by holocron — run \`holocron setup\` to regenerate.
@@ -2653,7 +3613,36 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		dryRun: argv.dryRun,
 		...argv.otp ? { otp: argv.otp } : {}
 	})).status === "fail") process.exitCode = 1;
-}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
+}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github via the GitHub API", (y) => y.option("repo", {
+	type: "string",
+	default: "theholocron/.github",
+	describe: "Target org/repo (default: theholocron/.github)"
+}).option("branch", {
+	type: "string",
+	describe: "Push to this branch instead of the default branch (enables PR-based workflow for protected repos)"
+}).option("pr", {
+	type: "boolean",
+	default: false,
+	describe: "Open a PR after pushing to --branch (no-op without --branch)"
+}).option("message", {
+	type: "string",
+	describe: "Commit message (default: chore: sync from theholocron/holocron)"
+}), async (argv) => {
+	const token = argv.token ?? process.env.GITHUB_TOKEN ?? process.env.HOLOCRON_GITHUB_TOKEN;
+	if (!token) {
+		console.error("sync-github: GitHub token required — pass --token or set GITHUB_TOKEN");
+		process.exitCode = 1;
+		return;
+	}
+	if ((await runSyncGithub({
+		token,
+		repo: argv.repo,
+		dryRun: argv.dryRun,
+		...argv.branch ? { branch: argv.branch } : {},
+		...argv.pr ? { createPr: true } : {},
+		...argv.message ? { message: argv.message } : {}
+	})).status === "fail") process.exitCode = 1;
+}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
 	const loaded = await loadConfig(argv.cwd);
 	console.log(JSON.stringify(loaded.resolved, null, 2));
 }).command("plugin create <slug> <vendor>", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {