@theholocron/astromech 4.6.0 → 4.7.0

package/README.md

@@ -90,6 +90,7 @@ 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
 ```
 
 `thinCallers()` returns the raw `.github/workflows/*.yml` content (no
@@ -101,6 +102,16 @@ per runnable task; it skips `local: false` entries and tasks with no local
 runner (`codeql`, `deploy`), and returns `{}` when `syncScripts: false` or
 there is no config.
 
+### Required checks
+
+`requiredChecks()` derives the branch-protection required-status-check list
+from the manifest: every `{ required: true }` task's check context (the
+`… / Conclusion` aggregate job, from `WORKFLOW_CHECK_CONTEXTS`), ordered by
+`CI_ORDER`, then `config.extraRequiredChecks` (codecov gates, the
+bundle-build check, …), de-duplicated. `holocron setup` prepends `"DCO"` and
+applies the list for `protection: "strict"` repos. Policy-free — manifest
+only.
+
 `holocron run` itself does not read the config yet — that (and
 `holocron ci`) come in later phases (epic #581).
 

package/dist/config/index.d.mts

@@ -1,4 +1,4 @@
-import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskConfigItem } from "../schema-DbpiBZCP.mjs";
+import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskConfigItem } from "../schema-uPSn69gZ.mjs";
 //#region src/config/define.d.ts
 /**
  * Typed identity helper for `astromech.config.ts`:

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { r as TasksConfig } from "./schema-DbpiBZCP.mjs";
+import { r as TasksConfig } from "./schema-uPSn69gZ.mjs";
 //#region src/run.d.ts
 /**
  * `holocron run <task> [-- <passthrough>]` — run a registry task locally.
@@ -135,12 +135,13 @@ declare function lintThinCallerWith(opts: {
 declare const WORKFLOW_TEMPLATES: Record<string, string>;
 declare const KNOWN_WORKFLOWS: Set<string>;
 /**
- * GitHub check context name each CI workflow produces on a PR.
+ * The GitHub status-check context a `required` task contributes to branch
+ * protection. Format: `"{workflow name} / {job name}"`.
  *
- * The format is "{caller-workflow-name} / {reusable-job-name}". The caller
- * job's own `name:` field does NOT appear in the external check name — only
- * the calling workflow's top-level `name:` and the inner reusable-workflow
- * job name matter. Only workflows that gate merges are listed here.
+ * 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.
  */
 declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
 /**
@@ -290,6 +291,13 @@ interface Astromech {
    * `linters` list, else auto-detection from the repo's config files.
    */
   superLinterConfig(): SuperLinterConfig;
+  /**
+   * The branch-protection required-status-check contexts for this repo —
+   * every `required: true` task's check context plus `extraRequiredChecks`,
+   * ordered and de-duplicated. `holocron setup` prepends `"DCO"` and applies
+   * the list; this method is policy-free (manifest only).
+   */
+  requiredChecks(): string[];
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
@@ -407,5 +415,16 @@ interface TaskDef {
 declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
 declare const KNOWN_TASKS: Set<string>;
+/**
+ * The order `holocron ci` runs tasks in — cheapest / fastest signal first, so
+ * an agent or a `pre-push` hook fails early. Tasks not listed here run last, in
+ * manifest order. (The generated thin callers carry no `needs:` — cross-workflow
+ * ordering lives in `theholocron/.github` — so `holocron ci` declares its own.)
+ */
+declare const CI_ORDER: string[];
+//#endregion
+//#region src/required-checks.d.ts
+/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
+declare function requiredChecks(config: TasksConfig): string[];
 //#endregion
-export { type Astromech, type AstromechOptions, 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, resolveLinters, runTask, superLinterConfig };
+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 };

package/dist/index.mjs

@@ -45,11 +45,318 @@ const TASKS = {
 	] } },
 	sync: { local: { command: "sync" } },
 	wiki: { local: { command: "sync-wiki" } },
+	audit: { local: null },
 	codeql: { local: null },
 	deploy: { local: null }
 };
 /** Every task name the registry knows. */
 const KNOWN_TASKS = new Set(Object.keys(TASKS));
+/**
+* The order `holocron ci` runs tasks in — cheapest / fastest signal first, so
+* an agent or a `pre-push` hook fails early. Tasks not listed here run last, in
+* manifest order. (The generated thin callers carry no `needs:` — cross-workflow
+* ordering lives in `theholocron/.github` — so `holocron ci` declares its own.)
+*/
+const CI_ORDER = [
+	"typecheck",
+	"lint",
+	"test",
+	"build",
+	"audit",
+	"codeql",
+	"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
 /**
@@ -491,265 +798,6 @@ function lintThinCallerWith(opts) {
 	};
 }
 //#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));
-/**
-* GitHub check context name each CI workflow produces on a PR.
-*
-* The format is "{caller-workflow-name} / {reusable-job-name}". The caller
-* job's own `name:` field does NOT appear in the external check name — only
-* the calling workflow's top-level `name:` and the inner reusable-workflow
-* job name matter. Only workflows that gate merges are listed here.
-*/
-const WORKFLOW_CHECK_CONTEXTS = {
-	lint: "Lint / Lint entire codebase",
-	test: "Test / Run tests and collect coverage",
-	typecheck: "Typecheck / tsc --noEmit"
-};
-/**
-* 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/astromech.ts
 /**
 * `createAstromech(options)` — the self-contained task runner.
@@ -847,8 +895,9 @@ function createAstromech(options) {
 		superLinterConfig: () => superLinterConfig({
 			explicit: lintEntry()?.linters,
 			rootFiles: rootFiles()
-		})
+		}),
+		requiredChecks: () => requiredChecks(options.config ?? {})
 	};
 }
 //#endregion
-export { KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, lintThinCallerWith, normalizeWorkflowWith, 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, runTask, superLinterConfig };

package/dist/{schema-DbpiBZCP.d.mts → schema-uPSn69gZ.d.mts}

@@ -22,8 +22,9 @@ interface TaskEntry {
    */
   local?: boolean;
   /**
-   * The task's CI check context is a required status check (branch
-   * protection) and part of `holocron ci`'s default run.
+   * The task's CI check context (from `WORKFLOW_CHECK_CONTEXTS`) is a
+   * required status check in branch protection (`astro.requiredChecks()`)
+   * and part of `holocron ci`'s default run.
    */
   required?: boolean;
   /** Per-repo overrides on the same channel the reusable workflow reads. */
@@ -51,8 +52,9 @@ interface TasksConfig {
    */
   holocronScript?: string;
   /**
-   * Required status-check contexts not backed by a task — DCO, semantic
-   * PR title, …
+   * Required status-check contexts not backed by a task — codecov gates,
+   * a bundle-build check, … Appended to `astro.requiredChecks()` after the
+   * `required`-task contexts. (`DCO` is prepended by `holocron setup` itself.)
    */
   extraRequiredChecks?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astromech",
-  "version": "4.6.0",
+  "version": "4.7.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.6.0"
+    "@theholocron/datapad": "4.7.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.6.0"
+    "@theholocron/rollup-plugin-transform-template": "4.7.0"
   },
   "engines": {
     "node": ">=22"