@theholocron/cli 4.3.0 → 4.5.0

package/README.md

@@ -93,6 +93,21 @@ Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one
 `"<task>": "holocron run <task>"` per runnable task. `syncScripts: false`
 opts out entirely.
 
+### Lint parity
+
+The `lint` task takes an optional `linters` array — one list that drives
+**both** the CI `lint` job (super-linter's `VALIDATE_*` env, baked into the
+generated `.github/workflows/lint.yml` thin caller as a `super-linter-env`
+input) **and** `holocron run lint` locally. Omitted → auto-detected from the
+config files present plus the org always-on set.
+
+```ts
+export default defineConfig({
+  tasks: [{ name: "lint", linters: ["eslint", "prettier", "yamllint", "actionlint", "gitleaks"] }],
+  providers: { source: "github" },
+});
+```
+
 ### Skills installer
 
 `holocron setup` can install shared skills from `@theholocron/skills` into the local repo:

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
 import { checkbox, input, select } from "@inquirer/prompts";
-import { KNOWN_WORKFLOWS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith } from "@theholocron/astromech";
+import { KNOWN_WORKFLOWS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith } from "@theholocron/astromech";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1, createRestClient } from "@theholocron/http-client";
@@ -4371,10 +4371,21 @@ async function runSetup(input) {
 			const name = typeof entry === "string" ? entry : entry.name;
 			const rawWith = typeof entry === "object" ? entry.with : void 0;
 			const normalized = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
-			const withOverrides = name === "lint" ? {
-				"enable-auto-commit": true,
-				...normalized ?? {}
-			} : normalized;
+			let withOverrides = normalized;
+			let comments;
+			if (name === "lint") {
+				let rootFiles = [];
+				try {
+					rootFiles = readdirSync(input.context.repoRoot);
+				} catch {}
+				const lint = lintThinCallerWith({
+					explicit: typeof entry === "object" ? entry.linters : void 0,
+					rootFiles,
+					extra: normalized
+				});
+				withOverrides = lint.withOverrides;
+				comments = lint.comments;
+			}
 			const additionalPaths = (typeof entry === "object" ? entry.paths : void 0) ?? (name === "deploy" && rawWith ? deriveDeployPaths(rawWith) : void 0);
 			if (name === "test" && withOverrides) {
 				const runUnit = withOverrides["run-unit"];
@@ -4406,7 +4417,7 @@ async function runSetup(input) {
 				}
 			}
 			steps.push(await runStep("source", `write workflow ${name}`, dryRun, async () => {
-				await source.writeWorkflowFile(`${name}.yml`, `${workflowHeader$2()}${generateThinCallerContent(name, withOverrides, additionalPaths)}`);
+				await source.writeWorkflowFile(`${name}.yml`, `${workflowHeader$2()}${generateThinCallerContent(name, withOverrides, additionalPaths, void 0, comments)}`);
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5580,10 +5591,17 @@ async function runSync(input) {
 				const name = typeof entry === "string" ? entry : entry.name;
 				const rawWith = typeof entry === "object" ? entry.with : void 0;
 				const normalized = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
-				const withOverrides = name === "lint" ? {
-					"enable-auto-commit": true,
-					...normalized ?? {}
-				} : normalized;
+				let withOverrides = normalized;
+				let comments;
+				if (name === "lint") {
+					const lint = lintThinCallerWith({
+						explicit: typeof entry === "object" ? entry.linters : void 0,
+						rootFiles: safeReaddir(input.context.repoRoot),
+						extra: normalized
+					});
+					withOverrides = lint.withOverrides;
+					comments = lint.comments;
+				}
 				const additionalPaths = (typeof entry === "object" ? entry.paths : void 0) ?? (name === "deploy" && rawWith ? deriveDeployPaths(rawWith) : void 0);
 				if (!KNOWN_WORKFLOWS.has(name)) {
 					steps.push({
@@ -5610,7 +5628,7 @@ async function runSync(input) {
 					}
 				}
 				steps.push(await runSyncStep("local", `sync workflow ${name}`, dryRun, async () => {
-					const content = `${workflowHeader$1()}${generateThinCallerContent(name, withOverrides, additionalPaths)}`;
+					const content = `${workflowHeader$1()}${generateThinCallerContent(name, withOverrides, additionalPaths, void 0, comments)}`;
 					await writeWorkflowFile(input.context.repoRoot, `${name}.yml`, content);
 				}));
 				print(formatSyncStep(steps[steps.length - 1]));
@@ -5703,6 +5721,14 @@ function formatSyncStep(step) {
 	const detail = step.message ? `  (${step.message})` : "";
 	return `    ${icon} ${step.step}${detail}`;
 }
+/** Repo-root filenames for linter auto-detection; `[]` when the dir is unreadable. */
+function safeReaddir(dir) {
+	try {
+		return readdirSync(dir);
+	} catch {
+		return [];
+	}
+}
 async function writePackageJsonField(repoRoot, field, value) {
 	const pkgPath = join(repoRoot, "package.json");
 	let content;
@@ -5962,7 +5988,7 @@ var deploy_default = "name: Deploy\n\non: # yamllint disable-line rule:truthy\n
 var greetings_default = "name: Greetings\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n\njobs:\n  greeting:\n    name: Greet first-time contributors\n    permissions:\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 5\n    # Group by the issue/PR number so duplicate events don't race each other.\n    steps:\n      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n        name: Greet on first contribution\n        with:\n          script: |\n            // Only greet on the initial open — ignore synchronize, reopened, etc.\n            if (context.payload.action !== 'opened') return;\n\n            const actor = context.actor;\n            const { owner, repo } = context.repo;\n\n            // Payload inspection is more reliable than context.eventName for detecting\n            // whether this is an issue vs. PR event — works regardless of how GitHub\n            // propagates event names through workflow_call chains.\n            const isIssue = !!context.payload.issue && !context.payload.pull_request;\n            // listForRepo returns both issues and PRs (GitHub treats PRs as issues),\n            // sorted newest-first. Filter by type to track first-issue and first-PR\n            // independently, and avoid search-index eventual-consistency lag.\n            const { data: recent } = await github.rest.issues.listForRepo({\n              owner, repo,\n              creator: actor,\n              state: 'all',\n              per_page: 100\n            });\n\n            const sameType = recent.filter(item =>\n              isIssue ? !item.pull_request : !!item.pull_request\n            );\n\n            if (sameType.length !== 1) return;\n            const body = isIssue\n              ? `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.`\n              : `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.`;\n\n            await github.rest.issues.createComment({\n              owner,\n              repo,\n              issue_number: context.issue.number,\n              body\n            });\n";
 //#endregion
 //#region src/templates/workflows/lint.yml
-var lint_default = "name: Lint\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      eslint-config:\n        description: >\n          Filename for the ESLint flat config used by super-linter for\n          JavaScript, JSX, TSX, and TypeScript (ES) files. Defaults to\n          eslint.config.ts (the org standard). Note: ESLint 9 requires\n          --flag unstable_ts_config to load .ts configs; if super-linter\n          cannot load it, override with eslint.config.mjs or eslint.config.js.\n        type: string\n        required: false\n        default: eslint.config.ts\n      prettier-config:\n        description: >\n          Filename for the Prettier config. Defaults to prettier.config.ts\n          (the org standard). Prettier 3.x loads .ts configs natively.\n        type: string\n        required: false\n        default: prettier.config.ts\n      yaml-config:\n        description: >\n          Filename for the yamllint config. Defaults to yamllint.config.yml.\n        type: string\n        required: false\n        default: yamllint.config.yml\n      enable-auto-commit:\n        description: >\n          Auto-commit super-linter fixes as a verified commit via a GitHub App.\n          Requires SUPER_LINTER_APP_ID and SUPER_LINTER_PRIVATE_KEY secrets.\n        type: boolean\n        required: false\n        default: false\n    secrets:\n      SUPER_LINTER_APP_ID:\n        required: false\n      SUPER_LINTER_PRIVATE_KEY:\n        required: false\n\njobs:\n  super-lint:\n    name: Lint entire codebase\n    permissions:\n      contents: write\n      issues: write\n      statuses: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    env:\n      APP_ID_SET: ${{ secrets.SUPER_LINTER_APP_ID != '' }}\n    steps:\n      - name: Generate GitHub App token\n        id: app-token\n        # Runs before checkout so the token is used as the checkout credential,\n        # which makes the subsequent push go through the App and produce a\n        # Verified commit. Skipped when auto-commit is disabled or secrets unset.\n        if: >\n          inputs.enable-auto-commit == true &&\n          github.event.pull_request != null &&\n          github.event.pull_request.head.repo.full_name == github.repository &&\n          github.ref_name != github.event.repository.default_branch &&\n          env.APP_ID_SET == 'true'\n        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0\n        with:\n          app-id: ${{ secrets.SUPER_LINTER_APP_ID }}\n          private-key: ${{ secrets.SUPER_LINTER_PRIVATE_KEY }}\n\n      - name: Resolve App bot identity\n        id: app-bot\n        # GitHub marks commits as Verified when the author email matches the\n        # App bot's noreply address (<numeric-id>+<slug>[bot]@users.noreply.github.com).\n        # The numeric ID must be fetched via the API — it differs from the App ID.\n        # app-slug is passed via env rather than interpolated into the script to\n        # prevent code injection (CWE-78).\n        if: steps.app-token.conclusion == 'success'\n        run: |\n          BOT_SLUG=\"${APP_SLUG}[bot]\"\n          BOT_ID=$(gh api \"/users/${BOT_SLUG}\" --jq .id)\n          echo \"name=${BOT_SLUG}\" >> \"$GITHUB_OUTPUT\"\n          echo \"email=${BOT_ID}+${BOT_SLUG}@users.noreply.github.com\" >> \"$GITHUB_OUTPUT\"\n        env:\n          GH_TOKEN: ${{ steps.app-token.outputs.token }}\n          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}\n\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n          # Use the App token when available so the push credential is the App\n          # bot — GitHub marks those commits as Verified automatically.\n          token: ${{ steps.app-token.outputs.token || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n        if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n\n      - name: Detect project features\n        # Writes VALIDATE_*/FIX_* to GITHUB_ENV only when the feature exists.\n        # Also writes step outputs for values referenced in expression context\n        # (GITHUB_ENV is not readable via steps.*.outputs — they need GITHUB_OUTPUT).\n        # All values written are hardcoded 'true' — no user input in the script.\n        # Config file paths (inputs.*) stay in GH Actions expression context in\n        # the super-linter env: block below, never shell-evaluated (CWE-78).\n        id: detect\n        run: |\n          has() { find . -not -path '*/node_modules/*' -name \"$1\" -print -quit 2>/dev/null | grep -q .; }\n\n          if { has 'eslint.config.ts' || has 'eslint.config.mjs' || has 'eslint.config.js' || has '.eslintrc.json' || has '.eslintrc.yml'; }; then\n            {\n              echo \"VALIDATE_JAVASCRIPT_ES=true\"\n              echo \"VALIDATE_TYPESCRIPT_ES=true\"\n            } >> \"$GITHUB_ENV\"\n            echo \"eslint=true\" >> \"$GITHUB_OUTPUT\"\n          fi\n\n          if { has '*.js' || has '*.jsx' || has '*.mjs' || has '*.cjs' || has '*.ts' || has '*.tsx'; }; then\n            {\n              echo \"VALIDATE_JAVASCRIPT_PRETTIER=true\"\n              echo \"VALIDATE_JSX_PRETTIER=true\"\n              echo \"VALIDATE_TYPESCRIPT_PRETTIER=true\"\n              echo \"VALIDATE_TSX=true\"\n              echo \"FIX_JAVASCRIPT_PRETTIER=true\"\n              echo \"FIX_JSX_PRETTIER=true\"\n              echo \"FIX_TYPESCRIPT_PRETTIER=true\"\n              echo \"FIX_TSX=true\"\n            } >> \"$GITHUB_ENV\"\n          fi\n\n          if { has '*.css' || has '*.scss' || has 'stylelint.config.ts' || has 'stylelint.config.mjs' || has 'stylelint.config.js'; }; then\n            {\n              echo \"VALIDATE_CSS=true\"\n              echo \"STYLELINT_CONFIG_FILE=stylelint.config.ts\"\n            } >> \"$GITHUB_ENV\"\n          fi\n\n          if { has '*.graphql' || has '*.gql'; }; then\n            {\n              echo \"VALIDATE_GRAPHQL_PRETTIER=true\"\n              echo \"FIX_GRAPHQL_PRETTIER=true\"\n            } >> \"$GITHUB_ENV\"\n          fi\n\n          if { has '*.html' || has '*.htm'; }; then\n            {\n              echo \"VALIDATE_HTML_PRETTIER=true\"\n              echo \"FIX_HTML_PRETTIER=true\"\n            } >> \"$GITHUB_ENV\"\n          fi\n\n          if { has '.env' || has '.env.example' || has '.env.local'; }; then\n            {\n              echo \"VALIDATE_ENV=true\"\n              echo \"FIX_ENV=true\"\n            } >> \"$GITHUB_ENV\"\n          fi\n\n          if { has 'Dockerfile' || has '*.Dockerfile'; }; then\n            echo \"VALIDATE_DOCKERFILE=true\" >> \"$GITHUB_ENV\"\n          fi\n\n      - uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0\n        name: Run Super Linter\n        env:\n          GITHUB_TOKEN: ${{ github.token }}\n          DEFAULT_BRANCH: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }}\n          ANNOTATE_ONLY: true\n          DISABLE_COMMENTS: false\n          IGNORE_GITIGNORED_FILES: true\n          LINTER_RULES_PATH: /\n          EDITORCONFIG_FILE_NAME: \".editorconfig-checker.json\"\n          # Config file paths — inputs stay in expression context, never shell-evaluated.\n          # When VALIDATE_JAVASCRIPT_ES is not set by detect, ESLint doesn't run so\n          # the empty-string fallback (→ eslint.config.mjs in container) is safe.\n          JAVASCRIPT_ES_CONFIG_FILE: ${{ steps.detect.outputs.eslint == 'true' && inputs.eslint-config || '' }}\n          TYPESCRIPT_ES_CONFIG_FILE: ${{ steps.detect.outputs.eslint == 'true' && inputs.eslint-config || '' }}\n          PRETTIER_CONFIG: ${{ inputs.prettier-config }}\n          YAML_CONFIG_FILE: ${{ inputs.yaml-config }}\n          # Always-on linters\n          FIX_MARKDOWN_PRETTIER: true\n          VALIDATE_EDITORCONFIG: true\n          VALIDATE_GIT_COMMITLINT: true\n          VALIDATE_GIT_MERGE_CONFLICT_MARKERS: true\n          VALIDATE_GITHUB_ACTIONS: true\n          VALIDATE_GITLEAKS: true\n          VALIDATE_MARKDOWN_PRETTIER: true\n          VALIDATE_YAML: true\n\n      - name: Validate ADR and spec frontmatter\n        if: hashFiles('scripts/validate-adrs.mjs') != ''\n        run: |\n          mapfile -t changed < <(git diff --name-only \"$BASE_SHA\" HEAD -- \\\n            'docs/decisions/*.md' '.notes/*.spec.md' \\\n            'docs/wiki/specifications/*.spec.md' 2>/dev/null || true)\n          if [ \"${#changed[@]}\" -eq 0 ]; then\n            node scripts/validate-adrs.mjs\n          else\n            node scripts/validate-adrs.mjs \"${changed[@]}\"\n          fi\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}\n\n      - name: Validate registry consistency\n        if: hashFiles('scripts/validate-registry.mjs') != ''\n        run: node scripts/validate-registry.mjs\n\n      - name: Validate docs presence for new packages\n        if: hashFiles('scripts/validate-docs-presence.mjs') != ''\n        run: node scripts/validate-docs-presence.mjs\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}\n\n      - uses: theholocron/.github/.github/actions/auto-commit@main\n        name: Commit and push linting fixes\n        if: >\n          inputs.enable-auto-commit == true &&\n          github.event.pull_request != null &&\n          github.event.pull_request.head.repo.full_name == github.repository &&\n          github.ref_name != github.event.repository.default_branch &&\n          env.APP_ID_SET == 'true'\n        with:\n          token: ${{ steps.app-token.outputs.token }}\n          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}\n          commit-message: \"chore: fix linting issues\\n\\nSigned-off-by: ${{ steps.app-bot.outputs.name }} <${{ steps.app-bot.outputs.email }}>\"\n          commit-options: \"--no-verify\"\n          commit-user-name: ${{ steps.app-bot.outputs.name }}\n          commit-user-email: ${{ steps.app-bot.outputs.email }}\n          commit-author: \"${{ steps.app-bot.outputs.name }} <${{ steps.app-bot.outputs.email }}>\"\n\n  conclusion:\n    name: Conclusion\n    runs-on: ubuntu-latest\n    if: always()\n    needs: [super-lint]\n    steps:\n      - name: Check job statuses\n        run: |\n          if [[ \"$RESULTS\" == *\"failure\"* ]] || [[ \"$RESULTS\" == *\"cancelled\"* ]]; then\n            exit 1\n          fi\n        env:\n          RESULTS: ${{ join(needs.*.result, ',') }}\n";
+var lint_default = "name: Lint\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      eslint-config:\n        description: >\n          Filename for the ESLint flat config used by super-linter for\n          JavaScript, JSX, TSX, and TypeScript (ES) files. Defaults to\n          eslint.config.ts (the org standard). Note: ESLint 9 requires\n          --flag unstable_ts_config to load .ts configs; if super-linter\n          cannot load it, override with eslint.config.mjs or eslint.config.js.\n        type: string\n        required: false\n        default: eslint.config.ts\n      prettier-config:\n        description: >\n          Filename for the Prettier config. Defaults to prettier.config.ts\n          (the org standard). Prettier 3.x loads .ts configs natively.\n        type: string\n        required: false\n        default: prettier.config.ts\n      yaml-config:\n        description: >\n          Filename for the yamllint config. Defaults to yamllint.config.yml.\n        type: string\n        required: false\n        default: yamllint.config.yml\n      enable-auto-commit:\n        description: >\n          Auto-commit super-linter fixes as a verified commit via a GitHub App.\n          Requires SUPER_LINTER_APP_ID and SUPER_LINTER_PRIVATE_KEY secrets.\n        type: boolean\n        required: false\n        default: false\n      super-linter-env:\n        description: >\n          JSON object of super-linter VALIDATE_*/FIX_* keys to enable, produced\n          by @theholocron/astromech superLinterConfig() and written into each\n          repo's generated lint thin caller. Replaces file-based feature\n          detection. The default is the org always-on baseline, so a thin caller\n          that has not been re-synced behaves exactly as before. Never empty —\n          an empty object would put super-linter in run-everything mode.\n        type: string\n        required: false\n        default: >-\n          {\"VALIDATE_JAVASCRIPT_PRETTIER\":\"true\",\"VALIDATE_JSX_PRETTIER\":\"true\",\n          \"VALIDATE_TYPESCRIPT_PRETTIER\":\"true\",\"VALIDATE_TSX\":\"true\",\n          \"VALIDATE_MARKDOWN_PRETTIER\":\"true\",\"FIX_JAVASCRIPT_PRETTIER\":\"true\",\n          \"FIX_JSX_PRETTIER\":\"true\",\"FIX_TYPESCRIPT_PRETTIER\":\"true\",\n          \"FIX_TSX\":\"true\",\"FIX_MARKDOWN_PRETTIER\":\"true\",\"VALIDATE_YAML\":\"true\",\n          \"VALIDATE_GITHUB_ACTIONS\":\"true\",\"VALIDATE_GITLEAKS\":\"true\",\n          \"VALIDATE_EDITORCONFIG\":\"true\",\"VALIDATE_GIT_COMMITLINT\":\"true\",\n          \"VALIDATE_GIT_MERGE_CONFLICT_MARKERS\":\"true\"}\n    secrets:\n      SUPER_LINTER_APP_ID:\n        required: false\n      SUPER_LINTER_PRIVATE_KEY:\n        required: false\n\njobs:\n  super-lint:\n    name: Lint entire codebase\n    permissions:\n      contents: write\n      issues: write\n      statuses: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    env:\n      APP_ID_SET: ${{ secrets.SUPER_LINTER_APP_ID != '' }}\n    steps:\n      - name: Generate GitHub App token\n        id: app-token\n        # Runs before checkout so the token is used as the checkout credential,\n        # which makes the subsequent push go through the App and produce a\n        # Verified commit. Skipped when auto-commit is disabled or secrets unset.\n        if: >\n          inputs.enable-auto-commit == true &&\n          github.event.pull_request != null &&\n          github.event.pull_request.head.repo.full_name == github.repository &&\n          github.ref_name != github.event.repository.default_branch &&\n          env.APP_ID_SET == 'true'\n        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0\n        with:\n          app-id: ${{ secrets.SUPER_LINTER_APP_ID }}\n          private-key: ${{ secrets.SUPER_LINTER_PRIVATE_KEY }}\n\n      - name: Resolve App bot identity\n        id: app-bot\n        # GitHub marks commits as Verified when the author email matches the\n        # App bot's noreply address (<numeric-id>+<slug>[bot]@users.noreply.github.com).\n        # The numeric ID must be fetched via the API — it differs from the App ID.\n        # app-slug is passed via env rather than interpolated into the script to\n        # prevent code injection (CWE-78).\n        if: steps.app-token.conclusion == 'success'\n        run: |\n          BOT_SLUG=\"${APP_SLUG}[bot]\"\n          BOT_ID=$(gh api \"/users/${BOT_SLUG}\" --jq .id)\n          echo \"name=${BOT_SLUG}\" >> \"$GITHUB_OUTPUT\"\n          echo \"email=${BOT_ID}+${BOT_SLUG}@users.noreply.github.com\" >> \"$GITHUB_OUTPUT\"\n        env:\n          GH_TOKEN: ${{ steps.app-token.outputs.token }}\n          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}\n\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n          # Use the App token when available so the push credential is the App\n          # bot — GitHub marks those commits as Verified automatically.\n          token: ${{ steps.app-token.outputs.token || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n        if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n\n      - name: Expand linter matrix\n        # The enabled super-linter VALIDATE_*/FIX_* set comes from\n        # `inputs.super-linter-env` — a JSON object produced by\n        # @theholocron/astromech and written into this repo's lint thin caller.\n        # SL_ENV is read via the env: block, never interpolated into the script\n        # (CWE-78). jq / find take no user input.\n        id: linters\n        env:\n          SL_ENV: ${{ inputs.super-linter-env }}\n        run: |\n          printf '%s' \"$SL_ENV\" | jq -r 'to_entries[] | \"\\(.key)=\\(.value)\"' >> \"$GITHUB_ENV\"\n\n          # eslint output feeds the *_ES_CONFIG_FILE passthrough below. When the\n          # manifest set it explicitly, honor that; otherwise (thin caller not\n          # yet re-synced with an explicit linter list) fall back to today's\n          # \"eslint runs iff an eslint config is present\" behavior.\n          eslint=false\n          if printf '%s' \"$SL_ENV\" | jq -e 'has(\"VALIDATE_JAVASCRIPT_ES\")' >/dev/null; then\n            eslint=true\n          elif find . -not -path '*/node_modules/*' \\\n            \\( -name 'eslint.config.*' -o -name '.eslintrc*' \\) -print -quit | grep -q .; then\n            {\n              echo \"VALIDATE_JAVASCRIPT_ES=true\"\n              echo \"VALIDATE_TYPESCRIPT_ES=true\"\n            } >> \"$GITHUB_ENV\"\n            eslint=true\n          fi\n          echo \"eslint=$eslint\" >> \"$GITHUB_OUTPUT\"\n\n      - uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0\n        name: Run Super Linter\n        env:\n          GITHUB_TOKEN: ${{ github.token }}\n          DEFAULT_BRANCH: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }}\n          ANNOTATE_ONLY: true\n          DISABLE_COMMENTS: false\n          IGNORE_GITIGNORED_FILES: true\n          LINTER_RULES_PATH: /\n          EDITORCONFIG_FILE_NAME: \".editorconfig-checker.json\"\n          # Config file paths — inputs stay in expression context, never shell-evaluated.\n          # When VALIDATE_JAVASCRIPT_ES is not enabled, ESLint doesn't run so the\n          # empty-string fallback (→ eslint.config.mjs in container) is safe.\n          JAVASCRIPT_ES_CONFIG_FILE: ${{ steps.linters.outputs.eslint == 'true' && inputs.eslint-config || '' }}\n          TYPESCRIPT_ES_CONFIG_FILE: ${{ steps.linters.outputs.eslint == 'true' && inputs.eslint-config || '' }}\n          PRETTIER_CONFIG: ${{ inputs.prettier-config }}\n          YAML_CONFIG_FILE: ${{ inputs.yaml-config }}\n          # The VALIDATE_*/FIX_* set is written to $GITHUB_ENV by the\n          # \"Expand linter matrix\" step above, from inputs.super-linter-env.\n\n      - name: Validate ADR and spec frontmatter\n        if: hashFiles('scripts/validate-adrs.mjs') != ''\n        run: |\n          mapfile -t changed < <(git diff --name-only \"$BASE_SHA\" HEAD -- \\\n            'docs/decisions/*.md' '.notes/*.spec.md' \\\n            'docs/wiki/specifications/*.spec.md' 2>/dev/null || true)\n          if [ \"${#changed[@]}\" -eq 0 ]; then\n            node scripts/validate-adrs.mjs\n          else\n            node scripts/validate-adrs.mjs \"${changed[@]}\"\n          fi\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}\n\n      - name: Validate registry consistency\n        if: hashFiles('scripts/validate-registry.mjs') != ''\n        run: node scripts/validate-registry.mjs\n\n      - name: Validate docs presence for new packages\n        if: hashFiles('scripts/validate-docs-presence.mjs') != ''\n        run: node scripts/validate-docs-presence.mjs\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}\n\n      - uses: theholocron/.github/.github/actions/auto-commit@main\n        name: Commit and push linting fixes\n        if: >\n          inputs.enable-auto-commit == true &&\n          github.event.pull_request != null &&\n          github.event.pull_request.head.repo.full_name == github.repository &&\n          github.ref_name != github.event.repository.default_branch &&\n          env.APP_ID_SET == 'true'\n        with:\n          token: ${{ steps.app-token.outputs.token }}\n          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}\n          commit-message: \"chore: fix linting issues\\n\\nSigned-off-by: ${{ steps.app-bot.outputs.name }} <${{ steps.app-bot.outputs.email }}>\"\n          commit-options: \"--no-verify\"\n          commit-user-name: ${{ steps.app-bot.outputs.name }}\n          commit-user-email: ${{ steps.app-bot.outputs.email }}\n          commit-author: \"${{ steps.app-bot.outputs.name }} <${{ steps.app-bot.outputs.email }}>\"\n\n  conclusion:\n    name: Conclusion\n    runs-on: ubuntu-latest\n    if: always()\n    needs: [super-lint]\n    steps:\n      - name: Check job statuses\n        run: |\n          if [[ \"$RESULTS\" == *\"failure\"* ]] || [[ \"$RESULTS\" == *\"cancelled\"* ]]; then\n            exit 1\n          fi\n        env:\n          RESULTS: ${{ join(needs.*.result, ',') }}\n";
 //#endregion
 //#region src/templates/workflows/preview.yml
 var preview_default = "name: Preview\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      type:\n        description: \"Type of deployment: docs or storybook\"\n        required: true\n        type: string\n      name:\n        description: Repo name prefix used to filter the docs site package (<name>-site); omit to run pnpm -C docs build\n        required: false\n        type: string\n        default: \"\"\n      storybook-projects:\n        description: >\n          JSON array of { \"name\"?, \"workingDir\", \"outputDir\"? } objects for storybook deploys.\n          Each is built via `pnpm -C <workingDir> build:storybook`. If \"name\" is provided the\n          output is placed under `sandbox/<name>/`; omit \"name\" for single-repo deploys and the\n          output lands directly in `sandbox/`.\n        type: string\n        required: false\n        default: \"[]\"\n      build-script:\n        description: pnpm script that builds the Storybook static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: build:storybook\n      output-dir:\n        description: Directory where Storybook writes its static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: storybook-static\n      cloudflare-project:\n        description: >\n          Cloudflare Pages project name. Falls back to the CLOUDFLARE_PAGES_PROJECT\n          org variable when omitted — set that variable once and all repos get previews\n          without per-repo config.\n        required: false\n        type: string\n        default: \"\"\n\njobs:\n  deploy-preview:\n    name: Preview\n    if: ${{ github.event.action != 'closed' }}\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      deployments: write\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name != '' }}\n        env:\n          SITE_NAME: ${{ inputs.name }}\n        run: pnpm --filter @theholocron/\"$SITE_NAME\"-site build\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name == '' }}\n        run: pnpm -C docs build\n\n      - name: Build Storybook projects\n        if: ${{ inputs.storybook-projects != '[]' }}\n        env:\n          PROJECTS: ${{ inputs.storybook-projects }}\n        run: |\n          echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n            workingDir=$(echo \"$project\" | jq -r '.workingDir')\n            pnpm -C \"$workingDir\" build:storybook\n          done\n\n      - name: Build Storybook\n        if: ${{ inputs.type == 'storybook' && inputs.storybook-projects == '[]' }}\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n        run: pnpm run \"$BUILD_SCRIPT\"\n\n      - name: Assemble site\n        env:\n          DEPLOY_TYPE: ${{ inputs.type }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECTS: ${{ inputs.storybook-projects }}\n          STORYBOOK_OUTPUT_DIR: ${{ inputs.output-dir }}\n        run: |\n          mkdir -p _site\n          if [ \"$DEPLOY_TYPE\" = \"docs\" ]; then\n            if [ -n \"$SITE_NAME\" ]; then\n              # Site built with base: /<name>/ — nest under _site/<name>/ so asset\n              # paths match (/name/_astro/... → served at /name/_astro/...).\n              mkdir -p \"_site/${SITE_NAME}\"\n              cp -r docs/dist/. \"_site/${SITE_NAME}/\"\n              # Redirect root to the base path so the preview URL lands correctly.\n              printf \"/ /%s/ 301\\n\" \"$SITE_NAME\" > _site/_redirects\n            else\n              cp -r docs/dist/. _site/\n            fi\n          fi\n          if [ \"$PROJECTS\" != \"[]\" ]; then\n            echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n              name=$(echo \"$project\" | jq -r '.name // \"\"')\n              workingDir=$(echo \"$project\" | jq -r '.workingDir')\n              outputDir=$(echo \"$project\" | jq -r '.outputDir // \"storybook-static\"')\n              if [ -n \"$name\" ]; then\n                target=\"_site/sandbox/${name}\"\n              else\n                target=\"_site/sandbox\"\n              fi\n              mkdir -p \"$target\"\n              cp -r \"${workingDir}/${outputDir}/.\" \"$target/\"\n            done\n          elif [ \"$DEPLOY_TYPE\" = \"storybook\" ]; then\n            mkdir -p _site/sandbox\n            cp -r \"${STORYBOOK_OUTPUT_DIR}/.\" _site/sandbox/\n          fi\n\n      - name: Install Wrangler\n        # The action's install step runs npm/pnpm in the repo root; pnpm fails\n        # because it rejects adding to a workspace root without -w, and npm fails\n        # because package.json contains pnpm catalog: references it cannot parse.\n        # Pre-installing from /tmp (no package.json) lets the action find wrangler\n        # already on PATH and skip its own install entirely.\n        working-directory: /tmp\n        run: npm install -g wrangler@4\n\n      - uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0\n        id: deploy\n        name: Deploy to Cloudflare Pages\n        # Skip when neither the per-repo input nor the org variable is set.\n        if: ${{ inputs.cloudflare-project != '' || vars.CLOUDFLARE_PAGES_PROJECT != '' }}\n        with:\n          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}\n          packageManager: npm\n          command: >-\n            pages deploy _site\n            --project-name ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n            --branch ${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}\n            --commit-dirty=true\n\n      - name: Report preview URL\n        if: ${{ steps.deploy.outputs.pages-deployment-alias-url != '' }}\n        env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          ALIAS: ${{ steps.deploy.outputs.pages-deployment-alias-url }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECT: ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n        run: |\n          PREVIEW_URL=\"${ALIAS%/}${SITE_NAME:+/${SITE_NAME}}/\"\n          # GITHUB_HEAD_REF is the PR branch name — links the deployment to this PR's sidebar widget.\n          PAYLOAD=$(printf '{\"ref\":\"%s\",\"environment\":\"%s\",\"description\":\"Cloudflare Pages\",\"production_environment\":false,\"auto_merge\":false,\"required_contexts\":[]}' \\\n            \"$GITHUB_HEAD_REF\" \"${PROJECT} (Preview)\")\n          DEPLOY_ID=$(echo \"$PAYLOAD\" | gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            --method POST --input - | jq -r '.id')\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments/${DEPLOY_ID}/statuses\" \\\n            --method POST --field state=success --field environment_url=\"${PREVIEW_URL}\"\n\n  cleanup:\n    name: Clean up Preview\n    if: ${{ github.event.action == 'closed' }}\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      deployments: write\n      pull-requests: write\n    steps:\n      - name: Delete Cloudflare Pages deployments for branch\n        if: ${{ inputs.cloudflare-project != '' || vars.CLOUDFLARE_PAGES_PROJECT != '' }}\n        env:\n          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}\n          PROJECT: ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n          BRANCH: ${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n        run: |\n          DEPLOYMENTS=$(curl -s \\\n            \"https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/${PROJECT}/deployments\" \\\n            -H \"Authorization: Bearer ${CLOUDFLARE_API_TOKEN}\" \\\n            | jq -r --arg b \"$BRANCH\" \\\n              '.result[] | select(.deployment_trigger.metadata.branch == $b) | .id')\n\n          if [ -z \"$DEPLOYMENTS\" ]; then\n            echo \"No deployments found for branch ${BRANCH} — nothing to clean up.\"\n            exit 0\n          fi\n\n          for id in $DEPLOYMENTS; do\n            echo \"Deleting CF Pages deployment: $id\"\n            curl -s -X DELETE \\\n              \"https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/${PROJECT}/deployments/${id}?force=true\" \\\n              -H \"Authorization: Bearer ${CLOUDFLARE_API_TOKEN}\" | jq -r 'if .success then \"  ✓ deleted\" else \"  ✗ \\(.errors[0].message)\" end'\n          done\n\n          # Mark the GitHub Deployment environment as inactive.\n          ENV_NAME=\"${PROJECT} (Preview)\"\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            | jq -r \".[] | select(.environment == \\\"${ENV_NAME}\\\") | .id\" \\\n            | while read -r deploy_id; do\n                gh api \"repos/${GITHUB_REPOSITORY}/deployments/${deploy_id}/statuses\" \\\n                  --method POST --field state=inactive 2>/dev/null || true\n              done\n";