@theholocron/astromech 4.7.0 → 4.9.0

package/README.md

@@ -91,8 +91,15 @@ const astromech = createAstromech({ cwd, config, orgContext: { org, domain } });
 astromech.thinCallers(); // Map<"<name>.yml", yaml>  — one per templated, ci-enabled task
 astromech.packageScripts(); // { holocron: "holocron", lint: "holocron run lint", … }
 astromech.requiredChecks(); // ["Lint / Conclusion", "codecov/patch", …]  — branch-protection contexts
+astromech.ci({ scope: "required" }); // CiReport — run the gating checks locally, in CI order
 ```
 
+`ci()` runs every `required: true` task (else every `ci: true` task) through the
+same resolution as `run()`, in `CI_ORDER`, and returns `{ status, jobs }`. A
+`required` task whose local runner can't run is a failure; `local: null` tasks
+(`audit` / `codeql` / `deploy`) are reported skipped. `holocron ci` sets the
+process exit code from `status`.
+
 `thinCallers()` returns the raw `.github/workflows/*.yml` content (no
 generated-by header — the caller prefixes its own). `deploy` with
 `preview:` shorthand produces the combined push-to-Pages / PR-to-preview

package/dist/index.d.mts

@@ -10,7 +10,8 @@ import { r as TasksConfig } from "./schema-uPSn69gZ.mjs";
  *   2. package.json has a `<task>` script     → `<pm> run <task>`
  *      (unless it's the `holocron run …` thin caller — that recurses)
  *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
- *   4. known task, nothing to run             → "no <task> task" (exit 0, or 1 with --required)
+ *   4. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
+ *   4b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
  *   5. unknown task                           → "unknown task" (exit 1)
  *
  * `lint` runs the resolved linter set (`config.tasks` `linters`, else
@@ -58,6 +59,8 @@ interface RunTaskInput extends RunDeps {
   required?: boolean;
   /** The `lint` task's explicit linter list from `config.tasks`, if any. */
   linters?: string[];
+  /** `turbo --filter=<pkg>` passthrough (monorepo). Ignored when the repo has no `turbo.json`. */
+  filter?: string;
 }
 interface RunTaskReport {
   status: "ok" | "fail" | "skip" | "dry-run" | "unknown";
@@ -67,6 +70,35 @@ interface RunTaskReport {
 }
 declare function runTask(input: RunTaskInput): RunTaskReport;
 //#endregion
+//#region src/ci.d.ts
+interface CiOptions {
+  /** Print the plan without running anything. */
+  dryRun?: boolean;
+  /** `turbo --filter=<pkg>` passthrough (monorepo). */
+  filter?: string;
+  /** `"required"` (default) or `"all"` (every `ci: true` task). */
+  scope?: "required" | "all";
+}
+interface CiJobReport {
+  task: string;
+  /** The branch-protection check context, or `null` for a non-gating task. */
+  checkContext: string | null;
+  status: "ok" | "fail" | "skip" | "dry-run";
+  command?: string;
+  message?: string;
+}
+interface CiReport {
+  status: "ok" | "fail";
+  jobs: CiJobReport[];
+}
+interface CiInput extends RunDeps, CiOptions {
+  cwd: string;
+  config: TasksConfig;
+  /** Explicit linter list for the `lint` task (the config's lint entry `linters`). */
+  linters?: string[];
+}
+declare function runCi(input: CiInput): CiReport;
+//#endregion
 //#region src/super-linter.d.ts
 /**
  * `superLinterConfig()` — turn the resolved linter set into the exact
@@ -264,10 +296,18 @@ interface RunOptions {
   dryRun?: boolean;
   /** Fail (exit 1) instead of skipping when the repo has no such task. */
   required?: boolean;
+  /** `turbo --filter=<pkg>` passthrough (monorepo). */
+  filter?: string;
 }
 interface Astromech {
   /** Run one task locally. */
   run(task: string, opts?: RunOptions): RunTaskReport;
+  /**
+   * Run the merge-gating checks locally, in CI order — "will CI pass?".
+   * Default scope: `required: true` tasks (falls back to every `ci: true`
+   * task when nothing is marked required). Exit non-zero on any failure.
+   */
+  ci(opts?: CiOptions): CiReport;
   /**
    * The `.github/workflows/*.yml` thin callers for this repo's manifest —
    * `filename` → YAML content (no generated-by header; the caller adds it).
@@ -395,8 +435,11 @@ interface LocalRunner {
 }
 interface TaskDef {
   /**
-   * `null` — no local equivalent (CodeQL, deploys). `holocron ci` reports
-   * it as skipped; `holocron run` treats it as "nothing to do".
+   * `null` — the registry has no built-in runner (CodeQL, deploys, audit's
+   * server / baseline jobs). An explicit turbo task or `package.json` script
+   * still runs (resolution steps 1–2); with neither, `holocron run` does
+   * nothing and `holocron ci` skips it — never a failure, even when the task
+   * is `required` (a CI-only check isn't a local one).
    */
   local: LocalRunner | null;
   /** Sub-jobs, keyed by slug — `holocron run audit performance`. */
@@ -427,4 +470,4 @@ declare const CI_ORDER: string[];
 /** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
 declare function requiredChecks(config: TasksConfig): string[];
 //#endregion
-export { type Astromech, type AstromechOptions, CI_ORDER, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, runTask, superLinterConfig };
+export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, type SuperLinterConfig, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, runCi, runTask, superLinterConfig };

package/dist/index.mjs

@@ -67,297 +67,6 @@ const CI_ORDER = [
 	"deploy"
 ];
 //#endregion
-//#region src/thin-callers.ts
-/**
-* Workflow templates + thin-caller generation.
-*
-* `WORKFLOW_TEMPLATES` holds each reusable `.github/workflows/<name>.yml`
-* (synced to `theholocron/.github`); `generateThinCallerContent` wraps one
-* into the thin caller `holocron setup` / `holocron sync` write locally.
-*/
-const WORKFLOW_TEMPLATES = {
-	lint: "name: Lint\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: lint-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: write\n  issues: write\n  statuses: write\n\njobs:\n  lint:\n    name: Lint\n    uses: theholocron/.github/.github/workflows/lint.yml@main\n    secrets: inherit\n",
-	test: "name: Test\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: test-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  id-token: write\n  statuses: write\n\njobs:\n  test:\n    name: Test\n    uses: theholocron/.github/.github/workflows/test.yml@main\n    with:\n      run-unit: true\n    secrets: inherit\n",
-	typecheck: "name: Typecheck\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: typecheck-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n\njobs:\n  typecheck:\n    name: Typecheck\n    uses: theholocron/.github/.github/workflows/typecheck.yml@main\n    secrets: inherit\n",
-	security: "name: Security\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches:\n      - main\n  pull_request:\n    branches:\n      - main\n  schedule:\n    - cron: \"0 0 * * 1\"\n\npermissions:\n  actions: read\n  contents: read\n  security-events: write\n\njobs:\n  security:\n    uses: theholocron/.github/.github/workflows/security.yml@main\n    secrets: inherit\n",
-	preview: "name: Preview\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: preview-${{ github.event.pull_request.number }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  deployments: write\n  pull-requests: write\n\njobs:\n  preview:\n    name: Preview\n    uses: theholocron/.github/.github/workflows/preview.yml@main\n    secrets: inherit\n",
-	review: "name: Review\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\nconcurrency:\n  group: review-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  checks: write\n  pull-requests: write\n\njobs:\n  review:\n    name: Review\n    uses: theholocron/.github/.github/workflows/review.yml@main\n    secrets: inherit\n",
-	release: "name: Release\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches:\n      - main\n      - alpha\n  workflow_dispatch:\n    inputs:\n      dry_run:\n        description: >\n          Dry run — analyze commits and preview the release without git writes\n          or publish. Push-triggered runs always run fully; this only applies\n          to manual workflow_dispatch triggers.\n        required: false\n        default: true\n        type: boolean\n\npermissions:\n  contents: write\n  id-token: write\n  issues: write\n  pull-requests: write\n\nconcurrency:\n  group: ${{ github.workflow }}-${{ github.ref }}\n  cancel-in-progress: false\n\njobs:\n  release:\n    uses: theholocron/.github/.github/workflows/release.yml@main\n    with:\n      dry-run: ${{ inputs.dry_run == true }}\n    secrets: inherit\n",
-	stale: "name: Stale\n\non: # yamllint disable-line rule:truthy\n  schedule:\n    - cron: \"30 1 * * *\"\n\npermissions:\n  contents: write\n  issues: write\n  pull-requests: write\n\njobs:\n  stale:\n    uses: theholocron/.github/.github/workflows/stale.yml@main\n    with:\n      exempt-issue-labels: \"in-progress,wip\"\n      exempt-all-issue-milestones: true\n      exempt-all-issue-projects: true\n      exempt-all-pr-projects: true\n    secrets: inherit\n",
-	sync: "name: Sync\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n    paths:\n      - holocron.config.ts\n      - package.json\n      - pnpm-workspace.yaml\n  workflow_dispatch:\n    inputs:\n      steps:\n        description: \"Sync steps to run (default: all)\"\n        type: string\n        required: false\n\nconcurrency:\n  group: sync-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  sync:\n    name: Sync\n    uses: theholocron/.github/.github/workflows/sync.yml@main\n    with:\n      steps: ${{ inputs.steps }}\n    secrets: inherit\n",
-	greetings: "name: Greetings\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n  issues:\n\npermissions:\n  issues: write\n  pull-requests: write\n\njobs:\n  greetings:\n    uses: theholocron/.github/.github/workflows/greetings.yml@main\n    secrets: inherit\n",
-	dependencies: "name: Dependencies\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  dependencies:\n    uses: theholocron/.github/.github/workflows/dependencies.yml@main\n    secrets: inherit\n",
-	bookkeeping: "name: Bookkeeping\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n    types:\n      - opened\n      - edited\n\npermissions:\n  contents: read\n  issues: write\n  pull-requests: write\n\njobs:\n  bookkeeping:\n    uses: theholocron/.github/.github/workflows/bookkeeping.yml@main\n    secrets: inherit\n",
-	audit: "name: Audit\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  audit:\n    uses: theholocron/.github/.github/workflows/audit.yml@main\n    secrets: inherit\n",
-	deploy: "name: Deploy\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  workflow_dispatch:\n\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\njobs:\n  deploy:\n    name: Deploy\n    uses: theholocron/.github/.github/workflows/deploy.yml@main\n    secrets: inherit\n",
-	wiki: "name: Wiki\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: ${{ github.event_name == 'pull_request' && format('wiki-preview-{0}', github.event.pull_request.number) || 'wiki' }}\n  cancel-in-progress: ${{ github.event_name == 'pull_request' }}\n\npermissions:\n  contents: read\n  deployments: write\n\njobs:\n  publish:\n    name: Publish\n    if: ${{ github.event_name != 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    secrets: inherit\n\n  preview:\n    name: Preview\n    if: ${{ github.event_name == 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    with:\n      preview: true\n      preview-id: pr-${{ github.event.pull_request.number }}\n    secrets: inherit\n"
-};
-const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
-/**
-* The GitHub status-check context a `required` task contributes to branch
-* protection. Format: `"{workflow name} / {job name}"`.
-*
-* These name the **aggregate `Conclusion` job** (fan-in, `if: always()`), not
-* an individual inner job — `test` has several conditionally-run sub-jobs, so
-* `"Test / Conclusion"` is the only stable gate. Only merge-gating workflows
-* are listed. `astro.requiredChecks()` reads this for every `required` task.
-*/
-const WORKFLOW_CHECK_CONTEXTS = {
-	lint: "Lint / Conclusion",
-	test: "Test / Conclusion",
-	typecheck: "Typecheck / Conclusion",
-	audit: "audit / Conclusion"
-};
-/**
-* Generate the thin caller content for a workflow, optionally injecting or
-* merging `with:` overrides into the jobs block.
-*
-* Two strategies are used depending on the template:
-* - Templates that already have a `with:` block (e.g. lint):
-*   the override entries are merged in, replacing existing keys and appending
-*   new ones.
-* - Templates that end with `    secrets: inherit`: a new `with:` block is
-*   injected immediately before `secrets: inherit`.
-* If neither pattern matches the template, a warning is emitted and the
-* base template is returned unchanged.
-*/
-function generateThinCallerContent(name, withOverrides, additionalPaths, logger, comments) {
-	const base = WORKFLOW_TEMPLATES[name];
-	if (!base) return "";
-	const yamlScalar = (v) => {
-		if (v === true) return "true";
-		if (v === false) return "false";
-		const s = String(v);
-		return s.startsWith("[") || s.startsWith("{") ? `'${s}'` : s;
-	};
-	const fmt = (k, v) => {
-		const line = `      ${k}: ${yamlScalar(v)}`;
-		return comments?.[k] ? `      # ${comments[k]}\n${line}` : line;
-	};
-	let result = base;
-	if (additionalPaths && additionalPaths.length > 0) {
-		const pathsBlockRe = /( {4}paths:\n)((?:[ ]{6}- [^\n]+\n)+)/;
-		if (pathsBlockRe.test(result)) result = result.replace(pathsBlockRe, (_, header, existing) => {
-			const existingPaths = new Set([...existing.matchAll(/- (.+)/g)].map((m) => m[1]));
-			const newEntries = additionalPaths.filter((p) => !existingPaths.has(p)).map((p) => `      - ${p}\n`).join("");
-			return header + existing + newEntries;
-		});
-		else {
-			const pathsBlock = `    paths:\n${additionalPaths.map((p) => `      - ${p}\n`).join("")}`;
-			result = result.replace(/( {4}branches: \[main\]\n)/, `$1${pathsBlock}`);
-		}
-	}
-	if (!withOverrides || Object.keys(withOverrides).length === 0) return result;
-	const withBlockRe = /( {4}with:\n)((?:[ ]{6}[^\n]+\n)*)/;
-	const existingMatch = result.match(withBlockRe);
-	if (existingMatch) {
-		const existingEntries = new Map(existingMatch[2].split("\n").filter(Boolean).filter((line) => !line.trim().startsWith("#")).map((line) => {
-			const m = line.match(/^ {6}([^:]+):\s*(.*)/);
-			return m ? [m[1].trim(), m[2].trim()] : null;
-		}).filter((e) => e !== null));
-		for (const [k, v] of Object.entries(withOverrides)) existingEntries.set(k, yamlScalar(v));
-		const merged = [...existingEntries.entries()].map(([k, v]) => `      ${k}: ${v}`).join("\n");
-		return result.replace(withBlockRe, `    with:\n${merged}\n`);
-	}
-	const withBlock = Object.entries(withOverrides).map(([k, v]) => fmt(k, v)).join("\n");
-	const injected = result.replace(/ {4}secrets: inherit\n$/, `    with:\n${withBlock}\n    secrets: inherit\n`);
-	if (injected === result) logger?.warn({ template: name }, "generateThinCallerContent: could not inject `with:` overrides");
-	return injected;
-}
-/**
-* Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
-*
-* Accepts three forms:
-* - `preview: true` — derive both project and domain from org context
-* - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
-* - `preview: { project: "...", domain: "..." }` — fully explicit
-*
-* Returns null when `preview:` is absent, false, or can't be resolved.
-*/
-function extractPreviewConfig(raw, ctx = {}) {
-	const preview = raw["preview"];
-	if (!preview) return null;
-	if (preview === true) {
-		const project = ctx.org ? `${ctx.org}-preview` : null;
-		const domain = ctx.domain ? `preview.${ctx.domain}` : void 0;
-		if (!project) return null;
-		return {
-			project,
-			...domain ? { domain } : {}
-		};
-	}
-	if (typeof preview !== "object") return null;
-	const p = preview;
-	const project = typeof p["project"] === "string" && p["project"] ? p["project"] : ctx.org ? `${ctx.org}-preview` : null;
-	if (!project) return null;
-	const domain = typeof p["domain"] === "string" && p["domain"] ? p["domain"] : ctx.domain ? `preview.${ctx.domain}` : void 0;
-	return {
-		project,
-		...domain ? { domain } : {}
-	};
-}
-/**
-* Generate the full thin-caller YAML for a `deploy.yml` that handles both
-* production (push to main → GitHub Pages) and preview (pull_request →
-* Cloudflare Pages) in a single file.
-*
-* Both jobs receive the same docs/storybook `with:` inputs. If the per-repo
-* config supplies `cloudflare-project` it is forwarded; otherwise the reusable
-* falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
-* all repos with a `deploy` workflow get previews without per-repo config.
-*/
-function generateCombinedDeployContent(deployWith, paths, preview) {
-	const yamlScalar = (v) => {
-		if (v === true) return "true";
-		if (v === false) return "false";
-		const s = String(v);
-		return s.startsWith("[") || s.startsWith("{") ? `'${s}'` : s;
-	};
-	const withLines = (entries) => Object.entries(entries).map(([k, v]) => `      ${k}: ${yamlScalar(v)}`).join("\n");
-	const pathsBlock = paths.length > 0 ? `    paths:\n${paths.map((p) => `      - ${p}\n`).join("")}` : "";
-	const previewWith = {
-		...deployWith,
-		"cloudflare-project": preview.project
-	};
-	const deployWithBlock = Object.keys(deployWith).length > 0 ? `    with:\n${withLines(deployWith)}\n` : "";
-	const previewWithBlock = `    with:\n${withLines(previewWith)}\n`;
-	return [
-		`name: Deploy`,
-		``,
-		`on: # yamllint disable-line rule:truthy`,
-		`  push:`,
-		`    branches: [main]`,
-		...pathsBlock ? [`${pathsBlock}`] : [],
-		`  pull_request:`,
-		`    branches: [main]`,
-		`    types: [opened, synchronize, reopened, closed]`,
-		...pathsBlock ? [`${pathsBlock}`] : [],
-		`  workflow_dispatch:`,
-		``,
-		`concurrency:`,
-		`  group: $\{{ github.event_name == 'pull_request' && format('preview-{0}', github.event.pull_request.number) || 'pages' }}`,
-		`  cancel-in-progress: $\{{ github.event_name == 'pull_request' && github.event.action != 'closed' }}`,
-		``,
-		`permissions:`,
-		`  contents: read`,
-		`  deployments: write`,
-		`  pages: write`,
-		`  id-token: write`,
-		`  pull-requests: write`,
-		``,
-		`jobs:`,
-		`  deploy:`,
-		`    name: Deploy`,
-		`    if: \${{ github.event_name != 'pull_request' }}`,
-		`    uses: theholocron/.github/.github/workflows/deploy.yml@main`,
-		...deployWithBlock ? [deployWithBlock.trimEnd()] : [],
-		`    secrets: inherit`,
-		``,
-		`  preview:`,
-		`    name: Preview`,
-		`    if: \${{ github.event_name == 'pull_request' }}`,
-		`    uses: theholocron/.github/.github/workflows/preview.yml@main`,
-		previewWithBlock.trimEnd(),
-		`    secrets: inherit`,
-		``
-	].join("\n");
-}
-/**
-* Expand structured with-values to flat GitHub Actions inputs before
-* generating the thin caller. Handles:
-*   - deploy shorthand: docs/storybook → type + storybook-projects
-*   - preview: stripped (handled separately via extractPreviewConfig)
-*   - run-chromatic object → run-chromatic: true + chromatic-projects
-*   - plain arrays → JSON-stringified for YAML scalar quoting
-*
-* Used by both `holocron setup` and `sync-workflow-templates`.
-*/
-function normalizeWorkflowWith(raw) {
-	const result = { ...raw };
-	delete result["preview"];
-	const hasDocs = raw["docs"] === true || raw["docs"] !== null && typeof raw["docs"] === "object";
-	const storybookProjects = raw["storybook"];
-	if (hasDocs) {
-		result["type"] = "docs";
-		delete result["docs"];
-	}
-	if (Array.isArray(storybookProjects)) {
-		if (!hasDocs) result["type"] = "storybook";
-		result["storybook-projects"] = JSON.stringify(storybookProjects.map(({ name, path = "." }) => ({
-			name,
-			workingDir: path
-		})));
-		delete result["storybook"];
-	}
-	const runChromatic = raw["run-chromatic"];
-	if (runChromatic !== null && typeof runChromatic === "object" && "projects" in runChromatic) {
-		result["run-chromatic"] = true;
-		const projects = runChromatic.projects.map((p) => ({
-			...p,
-			...Array.isArray(p.untraced) ? { untraced: p.untraced.join("\n") } : {}
-		}));
-		result["chromatic-projects"] = JSON.stringify(projects);
-	}
-	for (const [k, v] of Object.entries(result)) if (Array.isArray(v)) result[k] = JSON.stringify(v);
-	return result;
-}
-/**
-* Derive on.push.paths entries from the deploy with: shorthand.
-* Used by both `holocron setup` and `sync-workflow-templates`.
-*/
-function deriveDeployPaths(raw) {
-	const paths = [];
-	const docs = raw["docs"];
-	if (docs === true) {
-		paths.push("docs/**");
-		paths.push("astro.config.ts");
-		paths.push("pnpm-workspace.yaml");
-		paths.push("pnpm-lock.yaml");
-	} else if (docs !== null && typeof docs === "object" && "path" in docs) {
-		const p = docs.path;
-		if (p && p !== ".") paths.push(`${p}/**`);
-	}
-	const storybookProjects = raw["storybook"];
-	if (Array.isArray(storybookProjects)) for (const s of storybookProjects) {
-		const p = s.path || ".";
-		if (p === ".") {
-			paths.push("src/**");
-			paths.push(".storybook/**");
-		} else paths.push(`${p}/**`);
-	}
-	return paths;
-}
-//#endregion
-//#region src/required-checks.ts
-/**
-* `requiredChecks(config)` — the branch-protection required-status-check list,
-* derived from the task manifest. Every `required: true` task contributes its
-* {@link WORKFLOW_CHECK_CONTEXTS} entry; `config.extraRequiredChecks` adds
-* contexts not backed by a task (codecov, DCO is prepended by the caller).
-*
-* `@theholocron/cli`'s `holocron setup` calls this instead of the old
-* hand-maintained `repo.requiredChecks` array. Policy-free — it only knows the
-* manifest.
-*/
-/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
-function requiredChecks(config) {
-	const entries = (config.tasks ?? []).map(normalizeTaskEntry);
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const name of CI_ORDER) {
-		const context = entries.some((e) => e.name === name && e.required === true) ? WORKFLOW_CHECK_CONTEXTS[name] : void 0;
-		if (context && !seen.has(context)) {
-			seen.add(context);
-			out.push(context);
-		}
-	}
-	for (const context of config.extraRequiredChecks ?? []) if (!seen.has(context)) {
-		seen.add(context);
-		out.push(context);
-	}
-	return out;
-}
-//#endregion
 //#region src/linters.ts
 /**
 * Known linters, in execution order. `always` entries are the current
@@ -476,258 +185,636 @@ function resolveLinters(opts) {
 			def: LINTERS[name]
 		}));
 	}
-	const present = new Set(opts.rootFiles);
-	return order.filter((name) => {
-		const def = LINTERS[name];
-		return def.always === true || def.detect.some((f) => present.has(f));
-	}).map((name) => ({
-		name,
-		def: LINTERS[name]
-	}));
+	const present = new Set(opts.rootFiles);
+	return order.filter((name) => {
+		const def = LINTERS[name];
+		return def.always === true || def.detect.some((f) => present.has(f));
+	}).map((name) => ({
+		name,
+		def: LINTERS[name]
+	}));
+}
+//#endregion
+//#region src/run.ts
+/**
+* `holocron run <task> [-- <passthrough>]` — run a registry task locally.
+*
+* Resolution:
+*
+*   0. task === "lint"                        → the linter aggregate (see below)
+*   1. turbo.json defines the task            → `turbo run <task>`
+*   2. package.json has a `<task>` script     → `<pm> run <task>`
+*      (unless it's the `holocron run …` thin caller — that recurses)
+*   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
+*   4. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
+*   4b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
+*   5. unknown task                           → "unknown task" (exit 1)
+*
+* `lint` runs the resolved linter set (`config.tasks` `linters`, else
+* auto-detected): the eslint slot goes through the standard turbo / script /
+* `eslint .` resolution (so turbo caching is kept); every other linter runs
+* its `localBin` when found on PATH. Missing tools are flagged; the exit code
+* is the worst of the lot.
+*/
+/** The per-command runner — `runTask` and `runLintAggregate` share it. */
+function makeRunOne(input) {
+	const { print, logger, exec, task, cwd } = input;
+	const dryRun = input.dryRun ?? false;
+	return (cmd, args) => {
+		const command = [cmd, ...args].join(" ");
+		if (dryRun) {
+			print(`would run: ${command}`);
+			logger.debug({
+				task,
+				command,
+				status: "dry-run"
+			}, `run: ${task}`);
+			return {
+				status: "dry-run",
+				command
+			};
+		}
+		print(`→ ${command}`);
+		const { exitCode } = exec(cmd, args, { cwd });
+		const status = exitCode === 0 ? "ok" : "fail";
+		logger[status === "fail" ? "warn" : "debug"]({
+			task,
+			command,
+			exitCode,
+			status
+		}, `run: ${task}`);
+		return {
+			status,
+			command,
+			...status === "fail" ? { message: `\`${command}\` exited ${exitCode}` } : {}
+		};
+	};
+}
+function runTask(input) {
+	const { print, logger, readFile, fileExists, listDir, task, cwd } = input;
+	const passthrough = input.passthrough ?? [];
+	const run = makeRunOne(input);
+	if (task === "lint") return runLintAggregate(input);
+	if (turboDefinesTask(cwd, task, readFile, fileExists)) {
+		const args = [
+			"run",
+			task,
+			...input.filter ? [`--filter=${input.filter}`] : [],
+			...passthrough.length ? ["--", ...passthrough] : []
+		];
+		return run(resolveBin(cwd, "turbo", fileExists), args);
+	}
+	const def = TASKS[task];
+	const script = packageJsonScript(cwd, task, readFile, fileExists);
+	if (script && !/^holocron run\b/.test(script.trim())) return run(packageManager(cwd, readFile, fileExists), [
+		"run",
+		task,
+		...passthrough.length ? ["--", ...passthrough] : []
+	]);
+	if (def?.local) {
+		if (def.local.command) return run(process.execPath, [
+			process.argv[1],
+			def.local.command,
+			...passthrough
+		]);
+		const runner = resolveRunner(def.local, cwd, listDir);
+		if (runner) {
+			const flags = def.flags?.[runner.tool] ?? [];
+			return run(resolveBin(cwd, runner.tool, fileExists), [
+				...runner.args,
+				...flags,
+				...passthrough
+			]);
+		}
+	}
+	if (def?.local === null) {
+		const msg = `no local equivalent for ${task} — enforced in CI`;
+		print(`· ${msg}`);
+		logger.debug({
+			task,
+			status: "skip"
+		}, `run: ${task}`);
+		return {
+			status: "skip",
+			message: msg
+		};
+	}
+	if (KNOWN_TASKS.has(task)) {
+		const msg = `no ${task} task for this repo`;
+		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
+		logger[input.required ? "warn" : "debug"]({
+			task,
+			status: input.required ? "fail" : "skip"
+		}, `run: ${task}`);
+		return {
+			status: input.required ? "fail" : "skip",
+			message: msg
+		};
+	}
+	print(`✗ unknown task "${task}"`);
+	logger.warn({
+		task,
+		status: "unknown"
+	}, `run: ${task}`);
+	return {
+		status: "unknown",
+		message: `unknown task "${task}"`
+	};
+}
+/**
+* `holocron run lint` — the resolved linter set, run natively. The eslint
+* slot reuses turbo / the `lint` script / `eslint .`; the rest run their
+* `localBin` when it resolves on PATH. Worst exit code wins.
+*/
+function runLintAggregate(input) {
+	const { print, logger, readFile, fileExists, listDir, lookPath, cwd } = input;
+	const passthrough = input.passthrough ?? [];
+	const dryRun = input.dryRun ?? false;
+	const runOne = makeRunOne(input);
+	const pass = passthrough.length ? ["--", ...passthrough] : [];
+	let rootFiles;
+	try {
+		rootFiles = listDir(cwd);
+	} catch {
+		rootFiles = [];
+	}
+	const resolved = resolveLinters({
+		explicit: input.linters,
+		rootFiles
+	});
+	const reports = [];
+	/** Run one linter's `localBin` natively, or flag it. */
+	const runLinter = (name, bin, args, hint) => {
+		if (!bin) {
+			print(`· ${name} (CI only)`);
+			return;
+		}
+		const found = lookPath(cwd, bin);
+		if (!found) {
+			print(`! ${name} — ${bin} not on PATH${hint ? `. ${hint}` : ""} (enforced in CI)`);
+			return;
+		}
+		reports.push(runOne(found, [...args, ...passthrough]));
+	};
+	if (resolved.some((r) => r.name === "eslint")) {
+		const script = packageJsonScript(cwd, "lint", readFile, fileExists);
+		const filterArg = input.filter ? [`--filter=${input.filter}`] : [];
+		if (turboDefinesTask(cwd, "lint", readFile, fileExists)) reports.push(runOne(resolveBin(cwd, "turbo", fileExists), [
+			"run",
+			"lint",
+			...filterArg,
+			...pass
+		]));
+		else if (script && !/^holocron run\b/.test(script.trim())) reports.push(runOne(packageManager(cwd, readFile, fileExists), [
+			"run",
+			"lint",
+			...pass
+		]));
+		else runLinter("eslint", "eslint", ["."]);
+	}
+	for (const { name, def } of resolved) {
+		if (name === "eslint") continue;
+		runLinter(name, def.localBin, def.localArgs ?? [], def.installHint);
+	}
+	if (reports.length === 0) {
+		const msg = "no lint tooling available locally — every resolved linter is CI-only here";
+		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
+		logger[input.required ? "warn" : "debug"]({
+			task: "lint",
+			status: input.required ? "fail" : "skip"
+		}, "run: lint");
+		return {
+			status: input.required ? "fail" : "skip",
+			message: msg
+		};
+	}
+	const command = reports.map((r) => r.command).filter((c) => Boolean(c)).join(" && ");
+	if (dryRun) return {
+		status: "dry-run",
+		command
+	};
+	return reports.some((r) => r.status === "fail") ? {
+		status: "fail",
+		command,
+		message: "one or more linters failed"
+	} : {
+		status: "ok",
+		command
+	};
+}
+const mkRunner = (tool, args = []) => ({
+	tool,
+	args
+});
+/**
+* Resolve `{ tool, args }` for a runner, applying `detect[]` against repo
+* files. Only called for `tool` / `detect` runners — the caller handles
+* `command` runners itself, so `local.detect` is present whenever
+* `local.tool` is not.
+*/
+function resolveRunner(local, cwd, listDir) {
+	if (local.tool) return mkRunner(local.tool, local.args);
+	let files;
+	try {
+		files = listDir(cwd);
+	} catch {
+		return;
+	}
+	for (const candidate of local.detect) if (files.some((f) => candidate.when.test(f))) return mkRunner(candidate.tool, candidate.args);
+}
+function resolveBin(cwd, tool, fileExists) {
+	const local = join(cwd, "node_modules", ".bin", tool);
+	return fileExists(local) ? local : tool;
+}
+function packageManager(cwd, readFile, fileExists) {
+	try {
+		const pkg = JSON.parse(readFile(join(cwd, "package.json")));
+		if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
+	} catch {}
+	if (fileExists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (fileExists(join(cwd, "bun.lockb"))) return "bun";
+	if (fileExists(join(cwd, "yarn.lock"))) return "yarn";
+	if (fileExists(join(cwd, "package-lock.json"))) return "npm";
+	return "pnpm";
+}
+function turboDefinesTask(cwd, task, readFile, fileExists) {
+	if (!fileExists(join(cwd, "turbo.json"))) return false;
+	try {
+		const turbo = JSON.parse(readFile(join(cwd, "turbo.json")));
+		return Boolean(turbo.tasks?.[task] ?? turbo.pipeline?.[task]);
+	} catch {
+		return false;
+	}
+}
+function packageJsonScript(cwd, task, readFile, fileExists) {
+	if (!fileExists(join(cwd, "package.json"))) return void 0;
+	try {
+		return JSON.parse(readFile(join(cwd, "package.json"))).scripts?.[task];
+	} catch {
+		return;
+	}
 }
 //#endregion
-//#region src/run.ts
+//#region src/thin-callers.ts
 /**
-* `holocron run <task> [-- <passthrough>]` — run a registry task locally.
+* Workflow templates + thin-caller generation.
 *
-* Resolution:
+* `WORKFLOW_TEMPLATES` holds each reusable `.github/workflows/<name>.yml`
+* (synced to `theholocron/.github`); `generateThinCallerContent` wraps one
+* into the thin caller `holocron setup` / `holocron sync` write locally.
+*/
+const WORKFLOW_TEMPLATES = {
+	lint: "name: Lint\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: lint-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: write\n  issues: write\n  statuses: write\n\njobs:\n  lint:\n    name: Lint\n    uses: theholocron/.github/.github/workflows/lint.yml@main\n    secrets: inherit\n",
+	test: "name: Test\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: test-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  id-token: write\n  statuses: write\n\njobs:\n  test:\n    name: Test\n    uses: theholocron/.github/.github/workflows/test.yml@main\n    with:\n      run-unit: true\n    secrets: inherit\n",
+	typecheck: "name: Typecheck\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\nconcurrency:\n  group: typecheck-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n\njobs:\n  typecheck:\n    name: Typecheck\n    uses: theholocron/.github/.github/workflows/typecheck.yml@main\n    secrets: inherit\n",
+	security: "name: Security\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches:\n      - main\n  pull_request:\n    branches:\n      - main\n  schedule:\n    - cron: \"0 0 * * 1\"\n\npermissions:\n  actions: read\n  contents: read\n  security-events: write\n\njobs:\n  security:\n    uses: theholocron/.github/.github/workflows/security.yml@main\n    secrets: inherit\n",
+	preview: "name: Preview\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: preview-${{ github.event.pull_request.number }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  deployments: write\n  pull-requests: write\n\njobs:\n  preview:\n    name: Preview\n    uses: theholocron/.github/.github/workflows/preview.yml@main\n    secrets: inherit\n",
+	review: "name: Review\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\nconcurrency:\n  group: review-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  checks: write\n  pull-requests: write\n\njobs:\n  review:\n    name: Review\n    uses: theholocron/.github/.github/workflows/review.yml@main\n    secrets: inherit\n",
+	release: "name: Release\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches:\n      - main\n      - alpha\n  workflow_dispatch:\n    inputs:\n      dry_run:\n        description: >\n          Dry run — analyze commits and preview the release without git writes\n          or publish. Push-triggered runs always run fully; this only applies\n          to manual workflow_dispatch triggers.\n        required: false\n        default: true\n        type: boolean\n\npermissions:\n  contents: write\n  id-token: write\n  issues: write\n  pull-requests: write\n\nconcurrency:\n  group: ${{ github.workflow }}-${{ github.ref }}\n  cancel-in-progress: false\n\njobs:\n  release:\n    uses: theholocron/.github/.github/workflows/release.yml@main\n    with:\n      dry-run: ${{ inputs.dry_run == true }}\n    secrets: inherit\n",
+	stale: "name: Stale\n\non: # yamllint disable-line rule:truthy\n  schedule:\n    - cron: \"30 1 * * *\"\n\npermissions:\n  contents: write\n  issues: write\n  pull-requests: write\n\njobs:\n  stale:\n    uses: theholocron/.github/.github/workflows/stale.yml@main\n    with:\n      exempt-issue-labels: \"in-progress,wip\"\n      exempt-all-issue-milestones: true\n      exempt-all-issue-projects: true\n      exempt-all-pr-projects: true\n    secrets: inherit\n",
+	sync: "name: Sync\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n    paths:\n      - holocron.config.ts\n      - package.json\n      - pnpm-workspace.yaml\n  workflow_dispatch:\n    inputs:\n      steps:\n        description: \"Sync steps to run (default: all)\"\n        type: string\n        required: false\n\nconcurrency:\n  group: sync-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  sync:\n    name: Sync\n    uses: theholocron/.github/.github/workflows/sync.yml@main\n    with:\n      steps: ${{ inputs.steps }}\n    secrets: inherit\n",
+	greetings: "name: Greetings\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n  issues:\n\npermissions:\n  issues: write\n  pull-requests: write\n\njobs:\n  greetings:\n    uses: theholocron/.github/.github/workflows/greetings.yml@main\n    secrets: inherit\n",
+	dependencies: "name: Dependencies\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  dependencies:\n    uses: theholocron/.github/.github/workflows/dependencies.yml@main\n    secrets: inherit\n",
+	bookkeeping: "name: Bookkeeping\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n    types:\n      - opened\n      - edited\n\npermissions:\n  contents: read\n  issues: write\n  pull-requests: write\n\njobs:\n  bookkeeping:\n    uses: theholocron/.github/.github/workflows/bookkeeping.yml@main\n    secrets: inherit\n",
+	audit: "name: Audit\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  audit:\n    uses: theholocron/.github/.github/workflows/audit.yml@main\n    secrets: inherit\n",
+	deploy: "name: Deploy\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  workflow_dispatch:\n\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\njobs:\n  deploy:\n    name: Deploy\n    uses: theholocron/.github/.github/workflows/deploy.yml@main\n    secrets: inherit\n",
+	wiki: "name: Wiki\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: ${{ github.event_name == 'pull_request' && format('wiki-preview-{0}', github.event.pull_request.number) || 'wiki' }}\n  cancel-in-progress: ${{ github.event_name == 'pull_request' }}\n\npermissions:\n  contents: read\n  deployments: write\n\njobs:\n  publish:\n    name: Publish\n    if: ${{ github.event_name != 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    secrets: inherit\n\n  preview:\n    name: Preview\n    if: ${{ github.event_name == 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/wiki.yml@main\n    with:\n      preview: true\n      preview-id: pr-${{ github.event.pull_request.number }}\n    secrets: inherit\n"
+};
+const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
+/**
+* The GitHub status-check context a `required` task contributes to branch
+* protection. Format: `"{workflow name} / {job name}"`.
 *
-*   0. task === "lint"                        → the linter aggregate (see below)
-*   1. turbo.json defines the task            → `turbo run <task>`
-*   2. package.json has a `<task>` script     → `<pm> run <task>`
-*      (unless it's the `holocron run …` thin caller — that recurses)
-*   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
-*   4. known task, nothing to run             → "no <task> task" (exit 0, or 1 with --required)
-*   5. unknown task                           → "unknown task" (exit 1)
+* These name the **aggregate `Conclusion` job** (fan-in, `if: always()`), not
+* an individual inner job — `test` has several conditionally-run sub-jobs, so
+* `"Test / Conclusion"` is the only stable gate. Only merge-gating workflows
+* are listed. `astro.requiredChecks()` reads this for every `required` task.
+*/
+const WORKFLOW_CHECK_CONTEXTS = {
+	lint: "Lint / Conclusion",
+	test: "Test / Conclusion",
+	typecheck: "Typecheck / Conclusion",
+	audit: "audit / Conclusion"
+};
+/**
+* Generate the thin caller content for a workflow, optionally injecting or
+* merging `with:` overrides into the jobs block.
 *
-* `lint` runs the resolved linter set (`config.tasks` `linters`, else
-* auto-detected): the eslint slot goes through the standard turbo / script /
-* `eslint .` resolution (so turbo caching is kept); every other linter runs
-* its `localBin` when found on PATH. Missing tools are flagged; the exit code
-* is the worst of the lot.
+* Two strategies are used depending on the template:
+* - Templates that already have a `with:` block (e.g. lint):
+*   the override entries are merged in, replacing existing keys and appending
+*   new ones.
+* - Templates that end with `    secrets: inherit`: a new `with:` block is
+*   injected immediately before `secrets: inherit`.
+* If neither pattern matches the template, a warning is emitted and the
+* base template is returned unchanged.
 */
-/** The per-command runner — `runTask` and `runLintAggregate` share it. */
-function makeRunOne(input) {
-	const { print, logger, exec, task, cwd } = input;
-	const dryRun = input.dryRun ?? false;
-	return (cmd, args) => {
-		const command = [cmd, ...args].join(" ");
-		if (dryRun) {
-			print(`would run: ${command}`);
-			logger.debug({
-				task,
-				command,
-				status: "dry-run"
-			}, `run: ${task}`);
-			return {
-				status: "dry-run",
-				command
-			};
-		}
-		print(`→ ${command}`);
-		const { exitCode } = exec(cmd, args, { cwd });
-		const status = exitCode === 0 ? "ok" : "fail";
-		logger[status === "fail" ? "warn" : "debug"]({
-			task,
-			command,
-			exitCode,
-			status
-		}, `run: ${task}`);
-		return {
-			status,
-			command,
-			...status === "fail" ? { message: `\`${command}\` exited ${exitCode}` } : {}
-		};
+function generateThinCallerContent(name, withOverrides, additionalPaths, logger, comments) {
+	const base = WORKFLOW_TEMPLATES[name];
+	if (!base) return "";
+	const yamlScalar = (v) => {
+		if (v === true) return "true";
+		if (v === false) return "false";
+		const s = String(v);
+		return s.startsWith("[") || s.startsWith("{") ? `'${s}'` : s;
 	};
-}
-function runTask(input) {
-	const { print, logger, readFile, fileExists, listDir, task, cwd } = input;
-	const passthrough = input.passthrough ?? [];
-	const run = makeRunOne(input);
-	if (task === "lint") return runLintAggregate(input);
-	if (turboDefinesTask(cwd, task, readFile, fileExists)) {
-		const args = [
-			"run",
-			task,
-			...passthrough.length ? ["--", ...passthrough] : []
-		];
-		return run(resolveBin(cwd, "turbo", fileExists), args);
-	}
-	const def = TASKS[task];
-	const script = packageJsonScript(cwd, task, readFile, fileExists);
-	if (script && !/^holocron run\b/.test(script.trim())) return run(packageManager(cwd, readFile, fileExists), [
-		"run",
-		task,
-		...passthrough.length ? ["--", ...passthrough] : []
-	]);
-	if (def?.local) {
-		if (def.local.command) return run(process.execPath, [
-			process.argv[1],
-			def.local.command,
-			...passthrough
-		]);
-		const runner = resolveRunner(def.local, cwd, listDir);
-		if (runner) {
-			const flags = def.flags?.[runner.tool] ?? [];
-			return run(resolveBin(cwd, runner.tool, fileExists), [
-				...runner.args,
-				...flags,
-				...passthrough
-			]);
+	const fmt = (k, v) => {
+		const line = `      ${k}: ${yamlScalar(v)}`;
+		return comments?.[k] ? `      # ${comments[k]}\n${line}` : line;
+	};
+	let result = base;
+	if (additionalPaths && additionalPaths.length > 0) {
+		const pathsBlockRe = /( {4}paths:\n)((?:[ ]{6}- [^\n]+\n)+)/;
+		if (pathsBlockRe.test(result)) result = result.replace(pathsBlockRe, (_, header, existing) => {
+			const existingPaths = new Set([...existing.matchAll(/- (.+)/g)].map((m) => m[1]));
+			const newEntries = additionalPaths.filter((p) => !existingPaths.has(p)).map((p) => `      - ${p}\n`).join("");
+			return header + existing + newEntries;
+		});
+		else {
+			const pathsBlock = `    paths:\n${additionalPaths.map((p) => `      - ${p}\n`).join("")}`;
+			result = result.replace(/( {4}branches: \[main\]\n)/, `$1${pathsBlock}`);
 		}
 	}
-	if (KNOWN_TASKS.has(task) || def?.local === null) {
-		const msg = `no ${task} task for this repo`;
-		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
-		logger[input.required ? "warn" : "debug"]({
-			task,
-			status: input.required ? "fail" : "skip"
-		}, `run: ${task}`);
+	if (!withOverrides || Object.keys(withOverrides).length === 0) return result;
+	const withBlockRe = /( {4}with:\n)((?:[ ]{6}[^\n]+\n)*)/;
+	const existingMatch = result.match(withBlockRe);
+	if (existingMatch) {
+		const existingEntries = new Map(existingMatch[2].split("\n").filter(Boolean).filter((line) => !line.trim().startsWith("#")).map((line) => {
+			const m = line.match(/^ {6}([^:]+):\s*(.*)/);
+			return m ? [m[1].trim(), m[2].trim()] : null;
+		}).filter((e) => e !== null));
+		for (const [k, v] of Object.entries(withOverrides)) existingEntries.set(k, yamlScalar(v));
+		const merged = [...existingEntries.entries()].map(([k, v]) => `      ${k}: ${v}`).join("\n");
+		return result.replace(withBlockRe, `    with:\n${merged}\n`);
+	}
+	const withBlock = Object.entries(withOverrides).map(([k, v]) => fmt(k, v)).join("\n");
+	const injected = result.replace(/ {4}secrets: inherit\n$/, `    with:\n${withBlock}\n    secrets: inherit\n`);
+	if (injected === result) logger?.warn({ template: name }, "generateThinCallerContent: could not inject `with:` overrides");
+	return injected;
+}
+/**
+* Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
+*
+* Accepts three forms:
+* - `preview: true` — derive both project and domain from org context
+* - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
+* - `preview: { project: "...", domain: "..." }` — fully explicit
+*
+* Returns null when `preview:` is absent, false, or can't be resolved.
+*/
+function extractPreviewConfig(raw, ctx = {}) {
+	const preview = raw["preview"];
+	if (!preview) return null;
+	if (preview === true) {
+		const project = ctx.org ? `${ctx.org}-preview` : null;
+		const domain = ctx.domain ? `preview.${ctx.domain}` : void 0;
+		if (!project) return null;
 		return {
-			status: input.required ? "fail" : "skip",
-			message: msg
+			project,
+			...domain ? { domain } : {}
 		};
 	}
-	print(`✗ unknown task "${task}"`);
-	logger.warn({
-		task,
-		status: "unknown"
-	}, `run: ${task}`);
+	if (typeof preview !== "object") return null;
+	const p = preview;
+	const project = typeof p["project"] === "string" && p["project"] ? p["project"] : ctx.org ? `${ctx.org}-preview` : null;
+	if (!project) return null;
+	const domain = typeof p["domain"] === "string" && p["domain"] ? p["domain"] : ctx.domain ? `preview.${ctx.domain}` : void 0;
 	return {
-		status: "unknown",
-		message: `unknown task "${task}"`
+		project,
+		...domain ? { domain } : {}
+	};
+}
+/**
+* Generate the full thin-caller YAML for a `deploy.yml` that handles both
+* production (push to main → GitHub Pages) and preview (pull_request →
+* Cloudflare Pages) in a single file.
+*
+* Both jobs receive the same docs/storybook `with:` inputs. If the per-repo
+* config supplies `cloudflare-project` it is forwarded; otherwise the reusable
+* falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
+* all repos with a `deploy` workflow get previews without per-repo config.
+*/
+function generateCombinedDeployContent(deployWith, paths, preview) {
+	const yamlScalar = (v) => {
+		if (v === true) return "true";
+		if (v === false) return "false";
+		const s = String(v);
+		return s.startsWith("[") || s.startsWith("{") ? `'${s}'` : s;
+	};
+	const withLines = (entries) => Object.entries(entries).map(([k, v]) => `      ${k}: ${yamlScalar(v)}`).join("\n");
+	const pathsBlock = paths.length > 0 ? `    paths:\n${paths.map((p) => `      - ${p}\n`).join("")}` : "";
+	const previewWith = {
+		...deployWith,
+		"cloudflare-project": preview.project
 	};
+	const deployWithBlock = Object.keys(deployWith).length > 0 ? `    with:\n${withLines(deployWith)}\n` : "";
+	const previewWithBlock = `    with:\n${withLines(previewWith)}\n`;
+	return [
+		`name: Deploy`,
+		``,
+		`on: # yamllint disable-line rule:truthy`,
+		`  push:`,
+		`    branches: [main]`,
+		...pathsBlock ? [`${pathsBlock}`] : [],
+		`  pull_request:`,
+		`    branches: [main]`,
+		`    types: [opened, synchronize, reopened, closed]`,
+		...pathsBlock ? [`${pathsBlock}`] : [],
+		`  workflow_dispatch:`,
+		``,
+		`concurrency:`,
+		`  group: $\{{ github.event_name == 'pull_request' && format('preview-{0}', github.event.pull_request.number) || 'pages' }}`,
+		`  cancel-in-progress: $\{{ github.event_name == 'pull_request' && github.event.action != 'closed' }}`,
+		``,
+		`permissions:`,
+		`  contents: read`,
+		`  deployments: write`,
+		`  pages: write`,
+		`  id-token: write`,
+		`  pull-requests: write`,
+		``,
+		`jobs:`,
+		`  deploy:`,
+		`    name: Deploy`,
+		`    if: \${{ github.event_name != 'pull_request' }}`,
+		`    uses: theholocron/.github/.github/workflows/deploy.yml@main`,
+		...deployWithBlock ? [deployWithBlock.trimEnd()] : [],
+		`    secrets: inherit`,
+		``,
+		`  preview:`,
+		`    name: Preview`,
+		`    if: \${{ github.event_name == 'pull_request' }}`,
+		`    uses: theholocron/.github/.github/workflows/preview.yml@main`,
+		previewWithBlock.trimEnd(),
+		`    secrets: inherit`,
+		``
+	].join("\n");
 }
 /**
-* `holocron run lint` — the resolved linter set, run natively. The eslint
-* slot reuses turbo / the `lint` script / `eslint .`; the rest run their
-* `localBin` when it resolves on PATH. Worst exit code wins.
+* Expand structured with-values to flat GitHub Actions inputs before
+* generating the thin caller. Handles:
+*   - deploy shorthand: docs/storybook → type + storybook-projects
+*   - preview: stripped (handled separately via extractPreviewConfig)
+*   - run-chromatic object → run-chromatic: true + chromatic-projects
+*   - plain arrays → JSON-stringified for YAML scalar quoting
+*
+* Used by both `holocron setup` and `sync-workflow-templates`.
 */
-function runLintAggregate(input) {
-	const { print, logger, readFile, fileExists, listDir, lookPath, cwd } = input;
-	const passthrough = input.passthrough ?? [];
-	const dryRun = input.dryRun ?? false;
-	const runOne = makeRunOne(input);
-	const pass = passthrough.length ? ["--", ...passthrough] : [];
-	let rootFiles;
-	try {
-		rootFiles = listDir(cwd);
-	} catch {
-		rootFiles = [];
-	}
-	const resolved = resolveLinters({
-		explicit: input.linters,
-		rootFiles
-	});
-	const reports = [];
-	/** Run one linter's `localBin` natively, or flag it. */
-	const runLinter = (name, bin, args, hint) => {
-		if (!bin) {
-			print(`· ${name} (CI only)`);
-			return;
-		}
-		const found = lookPath(cwd, bin);
-		if (!found) {
-			print(`! ${name} — ${bin} not on PATH${hint ? `. ${hint}` : ""} (enforced in CI)`);
-			return;
-		}
-		reports.push(runOne(found, [...args, ...passthrough]));
-	};
-	if (resolved.some((r) => r.name === "eslint")) {
-		const script = packageJsonScript(cwd, "lint", readFile, fileExists);
-		if (turboDefinesTask(cwd, "lint", readFile, fileExists)) reports.push(runOne(resolveBin(cwd, "turbo", fileExists), [
-			"run",
-			"lint",
-			...pass
-		]));
-		else if (script && !/^holocron run\b/.test(script.trim())) reports.push(runOne(packageManager(cwd, readFile, fileExists), [
-			"run",
-			"lint",
-			...pass
-		]));
-		else runLinter("eslint", "eslint", ["."]);
+function normalizeWorkflowWith(raw) {
+	const result = { ...raw };
+	delete result["preview"];
+	const hasDocs = raw["docs"] === true || raw["docs"] !== null && typeof raw["docs"] === "object";
+	const storybookProjects = raw["storybook"];
+	if (hasDocs) {
+		result["type"] = "docs";
+		delete result["docs"];
 	}
-	for (const { name, def } of resolved) {
-		if (name === "eslint") continue;
-		runLinter(name, def.localBin, def.localArgs ?? [], def.installHint);
+	if (Array.isArray(storybookProjects)) {
+		if (!hasDocs) result["type"] = "storybook";
+		result["storybook-projects"] = JSON.stringify(storybookProjects.map(({ name, path = "." }) => ({
+			name,
+			workingDir: path
+		})));
+		delete result["storybook"];
 	}
-	if (reports.length === 0) {
-		const msg = "no lint tooling available locally — every resolved linter is CI-only here";
-		print(input.required ? `✗ ${msg} (required)` : `· ${msg}`);
-		logger[input.required ? "warn" : "debug"]({
-			task: "lint",
-			status: input.required ? "fail" : "skip"
-		}, "run: lint");
-		return {
-			status: input.required ? "fail" : "skip",
-			message: msg
-		};
+	const runChromatic = raw["run-chromatic"];
+	if (runChromatic !== null && typeof runChromatic === "object" && "projects" in runChromatic) {
+		result["run-chromatic"] = true;
+		const projects = runChromatic.projects.map((p) => ({
+			...p,
+			...Array.isArray(p.untraced) ? { untraced: p.untraced.join("\n") } : {}
+		}));
+		result["chromatic-projects"] = JSON.stringify(projects);
 	}
-	const command = reports.map((r) => r.command).filter((c) => Boolean(c)).join(" && ");
-	if (dryRun) return {
-		status: "dry-run",
-		command
-	};
-	return reports.some((r) => r.status === "fail") ? {
-		status: "fail",
-		command,
-		message: "one or more linters failed"
-	} : {
-		status: "ok",
-		command
-	};
+	for (const [k, v] of Object.entries(result)) if (Array.isArray(v)) result[k] = JSON.stringify(v);
+	return result;
 }
-const mkRunner = (tool, args = []) => ({
-	tool,
-	args
-});
 /**
-* Resolve `{ tool, args }` for a runner, applying `detect[]` against repo
-* files. Only called for `tool` / `detect` runners — the caller handles
-* `command` runners itself, so `local.detect` is present whenever
-* `local.tool` is not.
+* Derive on.push.paths entries from the deploy with: shorthand.
+* Used by both `holocron setup` and `sync-workflow-templates`.
 */
-function resolveRunner(local, cwd, listDir) {
-	if (local.tool) return mkRunner(local.tool, local.args);
-	let files;
-	try {
-		files = listDir(cwd);
-	} catch {
-		return;
+function deriveDeployPaths(raw) {
+	const paths = [];
+	const docs = raw["docs"];
+	if (docs === true) {
+		paths.push("docs/**");
+		paths.push("astro.config.ts");
+		paths.push("pnpm-workspace.yaml");
+		paths.push("pnpm-lock.yaml");
+	} else if (docs !== null && typeof docs === "object" && "path" in docs) {
+		const p = docs.path;
+		if (p && p !== ".") paths.push(`${p}/**`);
 	}
-	for (const candidate of local.detect) if (files.some((f) => candidate.when.test(f))) return mkRunner(candidate.tool, candidate.args);
+	const storybookProjects = raw["storybook"];
+	if (Array.isArray(storybookProjects)) for (const s of storybookProjects) {
+		const p = s.path || ".";
+		if (p === ".") {
+			paths.push("src/**");
+			paths.push(".storybook/**");
+		} else paths.push(`${p}/**`);
+	}
+	return paths;
 }
-function resolveBin(cwd, tool, fileExists) {
-	const local = join(cwd, "node_modules", ".bin", tool);
-	return fileExists(local) ? local : tool;
+//#endregion
+//#region src/ci.ts
+/**
+* `holocron ci` / `astro.ci()` — run the merge-gating checks locally, in CI
+* order, and exit non-zero on the first failure. The "will CI pass?" command a
+* `pre-push` hook and the agent skills point at.
+*
+* Default scope: every `required: true` task. If the manifest marks nothing
+* required (an un-migrated repo), fall back to every `ci: true` task. `--all`
+* forces the full set. Each task runs through {@link runTask}: a `required`
+* task whose local runner can't run is a failure; a `local: null` task with
+* no turbo task / `package.json` script is skipped, never failed — even when
+* `required` (it's a CI-only check, not a local one).
+*/
+function runCi(input) {
+	const { print } = input;
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of input.config?.tasks ?? []) byName.set(taskName(item), normalizeTaskEntry(item));
+	const gating = [...byName.values()].filter((e) => CI_ORDER.includes(e.name));
+	const all = gating.filter((e) => e.ci !== false);
+	const required = gating.filter((e) => e.required === true);
+	let selected = input.scope === "all" ? all : required;
+	const fellBack = input.scope !== "all" && selected.length === 0 && all.length > 0;
+	if (fellBack) selected = all;
+	const ordered = [...selected].sort((a, b) => CI_ORDER.indexOf(a.name) - CI_ORDER.indexOf(b.name));
+	print(`holocron ci — ${input.scope === "all" ? "all CI checks" : "required checks"} (${ordered.length})`);
+	if (fellBack) print("  (no required tasks in the manifest — running every CI task)");
+	print("");
+	const jobs = [];
+	for (const entry of ordered) {
+		const context = WORKFLOW_CHECK_CONTEXTS[entry.name] ?? null;
+		print(`▶ ${context ?? entry.name}`);
+		const r = runTask({
+			print: (line) => print(`  ${line}`),
+			logger: input.logger,
+			exec: input.exec,
+			readFile: input.readFile,
+			fileExists: input.fileExists,
+			listDir: input.listDir,
+			lookPath: input.lookPath,
+			task: entry.name,
+			cwd: input.cwd,
+			dryRun: input.dryRun ?? false,
+			required: entry.required === true,
+			...input.filter ? { filter: input.filter } : {},
+			...entry.name === "lint" ? { linters: input.linters } : {}
+		});
+		const status = r.status;
+		jobs.push({
+			task: entry.name,
+			checkContext: context,
+			status,
+			command: r.command,
+			message: r.message
+		});
+	}
+	const failed = jobs.filter((j) => j.status === "fail").length;
+	const passed = jobs.filter((j) => j.status === "ok" || j.status === "dry-run").length;
+	const skipped = jobs.filter((j) => j.status === "skip").length;
+	print("");
+	if (ordered.length === 0) print("holocron ci — nothing to run");
+	else if (failed > 0) print(`✗ ${failed} failed, ${passed} passed${skipped ? `, ${skipped} skipped` : ""}`);
+	else print(`✓ ${passed} passed${skipped ? `, ${skipped} skipped` : ""}${input.dryRun ? " (plan only)" : ""}`);
+	return {
+		status: failed > 0 ? "fail" : "ok",
+		jobs
+	};
 }
-function packageManager(cwd, readFile, fileExists) {
-	try {
-		const pkg = JSON.parse(readFile(join(cwd, "package.json")));
-		if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
-	} catch {}
-	if (fileExists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (fileExists(join(cwd, "bun.lockb"))) return "bun";
-	if (fileExists(join(cwd, "yarn.lock"))) return "yarn";
-	if (fileExists(join(cwd, "package-lock.json"))) return "npm";
-	return "pnpm";
+function taskName(item) {
+	return typeof item === "string" ? item : item.name;
 }
-function turboDefinesTask(cwd, task, readFile, fileExists) {
-	if (!fileExists(join(cwd, "turbo.json"))) return false;
-	try {
-		const turbo = JSON.parse(readFile(join(cwd, "turbo.json")));
-		return Boolean(turbo.tasks?.[task] ?? turbo.pipeline?.[task]);
-	} catch {
-		return false;
+//#endregion
+//#region src/required-checks.ts
+/**
+* `requiredChecks(config)` — the branch-protection required-status-check list,
+* derived from the task manifest. Every `required: true` task contributes its
+* {@link WORKFLOW_CHECK_CONTEXTS} entry; `config.extraRequiredChecks` adds
+* contexts not backed by a task (codecov, DCO is prepended by the caller).
+*
+* `@theholocron/cli`'s `holocron setup` calls this instead of the old
+* hand-maintained `repo.requiredChecks` array. Policy-free — it only knows the
+* manifest.
+*/
+/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
+function requiredChecks(config) {
+	const entries = (config.tasks ?? []).map(normalizeTaskEntry);
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const name of CI_ORDER) {
+		const context = entries.some((e) => e.name === name && e.required === true) ? WORKFLOW_CHECK_CONTEXTS[name] : void 0;
+		if (context && !seen.has(context)) {
+			seen.add(context);
+			out.push(context);
+		}
 	}
-}
-function packageJsonScript(cwd, task, readFile, fileExists) {
-	if (!fileExists(join(cwd, "package.json"))) return void 0;
-	try {
-		return JSON.parse(readFile(join(cwd, "package.json"))).scripts?.[task];
-	} catch {
-		return;
+	for (const context of config.extraRequiredChecks ?? []) if (!seen.has(context)) {
+		seen.add(context);
+		out.push(context);
 	}
+	return out;
 }
 //#endregion
 //#region src/super-linter.ts
@@ -848,8 +935,16 @@ function createAstromech(options) {
 			passthrough: opts.passthrough ?? [],
 			dryRun: opts.dryRun ?? false,
 			required: opts.required ?? false,
+			...opts.filter ? { filter: opts.filter } : {},
 			...task === "lint" ? { linters: lintEntry()?.linters } : {}
 		}),
+		ci: (opts = {}) => runCi({
+			...deps,
+			cwd: options.cwd,
+			config: options.config ?? {},
+			linters: lintEntry()?.linters,
+			...opts
+		}),
 		thinCallers: () => {
 			const orgCtx = options.orgContext ?? {};
 			const out = /* @__PURE__ */ new Map();
@@ -900,4 +995,4 @@ function createAstromech(options) {
 	};
 }
 //#endregion
-export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, runTask, superLinterConfig };
+export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, requiredChecks, resolveLinters, runCi, runTask, superLinterConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astromech",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "The Holocron task runner — one task manifest drives `holocron run`, `holocron ci`, the CI workflows, package.json scripts, linters, and required checks.",
   "keywords": [
     "ci",
@@ -37,7 +37,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/datapad": "4.7.0"
+    "@theholocron/datapad": "4.9.0"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.0.0",
@@ -53,7 +53,7 @@
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/rollup-plugin-transform-template": "4.7.0"
+    "@theholocron/rollup-plugin-transform-template": "4.9.0"
   },
   "engines": {
     "node": ">=22"