@theholocron/astromech 4.6.0 → 4.8.0

package/README.md

@@ -90,8 +90,16 @@ 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
@@ -101,6 +109,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.
@@ -10,7 +10,8 @@ import { r as TasksConfig } from "./schema-DbpiBZCP.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
@@ -135,12 +167,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>>;
 /**
@@ -263,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).
@@ -290,6 +331,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
@@ -387,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`. */
@@ -407,5 +458,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 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

@@ -45,11 +45,27 @@ 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/linters.ts
 /**
@@ -190,7 +206,8 @@ function resolveLinters(opts) {
 *   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
@@ -242,6 +259,7 @@ function runTask(input) {
 		const args = [
 			"run",
 			task,
+			...input.filter ? [`--filter=${input.filter}`] : [],
 			...passthrough.length ? ["--", ...passthrough] : []
 		];
 		return run(resolveBin(cwd, "turbo", fileExists), args);
@@ -269,7 +287,19 @@ function runTask(input) {
 			]);
 		}
 	}
-	if (KNOWN_TASKS.has(task) || def?.local === null) {
+	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"]({
@@ -328,9 +358,11 @@ function runLintAggregate(input) {
 	};
 	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), [
@@ -423,74 +455,6 @@ function packageJsonScript(cwd, task, readFile, fileExists) {
 	}
 }
 //#endregion
-//#region src/super-linter.ts
-/**
-* `superLinterConfig()` — turn the resolved linter set into the exact
-* super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
-* serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
-* on each repo's generated `lint` thin caller; the reusable workflow
-* expands it verbatim. This is the CI half of "lint parity" — the local
-* half is the `holocron run lint` aggregate, driven by the same
-* {@link resolveLinters}.
-*/
-/**
-* Resolve the super-linter env for a repo's `lint` task.
-*
-* @param opts.explicit  the task's `linters` list, if any (else auto-detect)
-* @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
-* @param opts.includeFix  emit `FIX_*` keys too (default `true`)
-*/
-function superLinterConfig(opts) {
-	const includeFix = opts.includeFix ?? true;
-	const resolved = resolveLinters({
-		explicit: opts.explicit,
-		rootFiles: opts.rootFiles
-	});
-	const env = {};
-	const configInputs = {};
-	for (const { def } of resolved) {
-		for (const key of def.validate) env[key] = "true";
-		if (includeFix) for (const key of def.fix ?? []) env[key] = "true";
-		if (def.configInput) configInputs[def.configInput] = true;
-	}
-	return {
-		env,
-		linters: resolved.map((r) => r.name),
-		configInputs
-	};
-}
-/**
-* The always-on baseline env — every `always` linter, no detection. This is
-* what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
-* repo whose thin caller has not been re-synced yet behaves exactly as before.
-*/
-function baselineSuperLinterEnv() {
-	return superLinterConfig({ rootFiles: [] }).env;
-}
-/**
-* The `lint` thin caller's `with:` overrides + the `# linters: …` comment,
-* from the resolved linter set. Shared by `createAstromech().thinCallers()`
-* and the CLI's `sync` / `setup` workflow writers so the three stay in step.
-*
-* @param opts.explicit  the `lint` task's `linters` list, if any
-* @param opts.rootFiles  repo-root filenames (auto-detect fallback)
-* @param opts.extra  per-repo `with:` overrides that win over the defaults
-*/
-function lintThinCallerWith(opts) {
-	const sl = superLinterConfig({
-		explicit: opts.explicit,
-		rootFiles: opts.rootFiles
-	});
-	return {
-		withOverrides: {
-			"enable-auto-commit": true,
-			"super-linter-env": JSON.stringify(sl.env),
-			...opts.extra ?? {}
-		},
-		comments: { "super-linter-env": `linters: ${sl.linters.join(", ")}` }
-	};
-}
-//#endregion
 //#region src/thin-callers.ts
 /**
 * Workflow templates + thin-caller generation.
@@ -518,17 +482,19 @@ const WORKFLOW_TEMPLATES = {
 };
 const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
 /**
-* 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.
 */
 const WORKFLOW_CHECK_CONTEXTS = {
-	lint: "Lint / Lint entire codebase",
-	test: "Test / Run tests and collect coverage",
-	typecheck: "Typecheck / tsc --noEmit"
+	lint: "Lint / Conclusion",
+	test: "Test / Conclusion",
+	typecheck: "Typecheck / Conclusion",
+	audit: "audit / Conclusion"
 };
 /**
 * Generate the thin caller content for a workflow, optionally injecting or
@@ -750,6 +716,175 @@ function deriveDeployPaths(raw) {
 	return paths;
 }
 //#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 taskName(item) {
+	return typeof item === "string" ? item : item.name;
+}
+//#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/super-linter.ts
+/**
+* `superLinterConfig()` — turn the resolved linter set into the exact
+* super-linter `VALIDATE_*` / `FIX_*` env the CI `lint` job needs. The CLI
+* serializes {@link SuperLinterConfig.env} as the `super-linter-env` input
+* on each repo's generated `lint` thin caller; the reusable workflow
+* expands it verbatim. This is the CI half of "lint parity" — the local
+* half is the `holocron run lint` aggregate, driven by the same
+* {@link resolveLinters}.
+*/
+/**
+* Resolve the super-linter env for a repo's `lint` task.
+*
+* @param opts.explicit  the task's `linters` list, if any (else auto-detect)
+* @param opts.rootFiles  repo-root filenames (from `listDir(cwd)`)
+* @param opts.includeFix  emit `FIX_*` keys too (default `true`)
+*/
+function superLinterConfig(opts) {
+	const includeFix = opts.includeFix ?? true;
+	const resolved = resolveLinters({
+		explicit: opts.explicit,
+		rootFiles: opts.rootFiles
+	});
+	const env = {};
+	const configInputs = {};
+	for (const { def } of resolved) {
+		for (const key of def.validate) env[key] = "true";
+		if (includeFix) for (const key of def.fix ?? []) env[key] = "true";
+		if (def.configInput) configInputs[def.configInput] = true;
+	}
+	return {
+		env,
+		linters: resolved.map((r) => r.name),
+		configInputs
+	};
+}
+/**
+* The always-on baseline env — every `always` linter, no detection. This is
+* what the reusable `lint.yml`'s `super-linter-env` input defaults to, so a
+* repo whose thin caller has not been re-synced yet behaves exactly as before.
+*/
+function baselineSuperLinterEnv() {
+	return superLinterConfig({ rootFiles: [] }).env;
+}
+/**
+* The `lint` thin caller's `with:` overrides + the `# linters: …` comment,
+* from the resolved linter set. Shared by `createAstromech().thinCallers()`
+* and the CLI's `sync` / `setup` workflow writers so the three stay in step.
+*
+* @param opts.explicit  the `lint` task's `linters` list, if any
+* @param opts.rootFiles  repo-root filenames (auto-detect fallback)
+* @param opts.extra  per-repo `with:` overrides that win over the defaults
+*/
+function lintThinCallerWith(opts) {
+	const sl = superLinterConfig({
+		explicit: opts.explicit,
+		rootFiles: opts.rootFiles
+	});
+	return {
+		withOverrides: {
+			"enable-auto-commit": true,
+			"super-linter-env": JSON.stringify(sl.env),
+			...opts.extra ?? {}
+		},
+		comments: { "super-linter-env": `linters: ${sl.linters.join(", ")}` }
+	};
+}
+//#endregion
 //#region src/astromech.ts
 /**
 * `createAstromech(options)` — the self-contained task runner.
@@ -800,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();
@@ -847,8 +990,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, runCi, 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.8.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.8.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.8.0"
   },
   "engines": {
     "node": ">=22"