@theholocron/astromech 4.1.0 → 4.3.0

package/README.md

@@ -79,9 +79,67 @@ export default defineConfig({
 | `with`                   | per-repo overrides on the reusable-workflow channel         |
 | `linters` (`lint` only)  | explicit linter list; omitted → auto-detect                 |
 
-Nothing in `holocron run` reads the config yet — the manifest drives
-`holocron ci`, workflow generation, and script sync in later phases
-(epic #581).
+Top-level keys: `syncScripts: false` disables the `package.json` script
+writes entirely; `holocronScript` sets the command the synced `"holocron"`
+script runs (default `"holocron"`).
+
+### Generated surfaces
+
+```ts
+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", … }
+```
+
+`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
+workflow. `packageScripts()` emits the `holocron` entry
+(`holocronScript ?? "holocron"`) plus one `"<task>": "holocron run <task>"`
+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.
+
+`holocron run` itself does not read the config yet — that (and
+`holocron ci`) come in later phases (epic #581).
+
+## Lint parity
+
+One linter list drives both CI and local — no asymmetry. Source: the
+`lint` task's `linters` array, or auto-detection from the config files
+present. The `linter name → super-linter VALIDATE_* keys` mapping lives in
+one place, `src/linters.ts`.
+
+| linter                       | `VALIDATE_*`                              | always-on                           | local binary                             |
+| ---------------------------- | ----------------------------------------- | ----------------------------------- | ---------------------------------------- |
+| `eslint`                     | `JAVASCRIPT_ES`, `TYPESCRIPT_ES`          | on `eslint.config.*` / `.eslintrc*` | `eslint .`                               |
+| `prettier`                   | `*_PRETTIER` (JS/JSX/TS/TSX/MD) + `FIX_*` | yes                                 | `prettier --check .`                     |
+| `yamllint`                   | `YAML`                                    | yes                                 | `yamllint .` (usually CI-only)           |
+| `actionlint`                 | `GITHUB_ACTIONS`                          | yes                                 | `actionlint` (usually CI-only)           |
+| `gitleaks`                   | `GITLEAKS`                                | yes                                 | `gitleaks dir` (usually CI-only)         |
+| `editorconfig`               | `EDITORCONFIG`                            | yes                                 | `editorconfig-checker` (usually CI-only) |
+| `commitlint`                 | `GIT_COMMITLINT`                          | yes                                 | `commitlint --last`                      |
+| `git-merge-conflict-markers` | `GIT_MERGE_CONFLICT_MARKERS`              | yes                                 | — (CI only)                              |
+| `markdownlint`               | `MARKDOWN`                                | on `.markdownlint*`                 | `markdownlint-cli2`                      |
+
+```ts
+import { superLinterConfig, resolveLinters } from "@theholocron/astromech";
+
+superLinterConfig({ explicit: ["eslint", "prettier"], rootFiles: fs.readdirSync(cwd) });
+// → { env: { VALIDATE_JAVASCRIPT_ES: "true", … }, linters: ["eslint","prettier"], configInputs: { … } }
+```
+
+`superLinterConfig().env` is the exact `VALIDATE_*`/`FIX_*` map the CI
+`lint` job needs — the CLI serializes it as the `super-linter-env` input on
+each repo's generated `lint` thin caller. Setting any `VALIDATE_*` puts
+super-linter in allow-list mode, so emitting only the enabled keys makes it
+run exactly the resolved set.
+
+`holocron run lint` (later phase) runs the same set natively: `turbo run
+lint` for the eslint portion (cached), then each other linter whose binary
+resolves; linters with a binary that is not on `PATH` are flagged with an
+install hint; the rest print "CI only".
 
 ## Development
 

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-4kyr9ILV.mjs";
+import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskConfigItem } from "../schema-DbpiBZCP.mjs";
 //#region src/config/define.d.ts
 /**
  * Typed identity helper for `astromech.config.ts`:

package/dist/config/index.mjs

@@ -1,3 +1,4 @@
+import { t as normalizeTaskEntry } from "../schema-Cf5dfaDO.mjs";
 import { createDefineConfig, loadConfigFile, mergeConfig } from "@theholocron/datapad";
 //#region src/config/define.ts
 /**
@@ -35,14 +36,4 @@ function coerce(value) {
 	return Array.isArray(value) ? { tasks: value } : value;
 }
 //#endregion
-//#region src/config/schema.ts
-/** Normalise a `TaskConfigItem` to a full {@link TaskEntry} with defaults applied. */
-function normalizeTaskEntry(item) {
-	return {
-		ci: true,
-		local: true,
-		...typeof item === "string" ? { name: item } : item
-	};
-}
-//#endregion
 export { defineConfig, loadTasksConfig, normalizeTaskEntry };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { r as TasksConfig } from "./schema-4kyr9ILV.mjs";
+import { r as TasksConfig } from "./schema-DbpiBZCP.mjs";
 //#region src/run.d.ts
 /**
  * `holocron run <task> [-- <passthrough>]` — run a registry task locally.
@@ -56,83 +56,6 @@ interface RunTaskReport {
 }
 declare function runTask(input: RunTaskInput): RunTaskReport;
 //#endregion
-//#region src/astromech.d.ts
-interface AstromechOptions {
-  /** Repo root. */
-  cwd: string;
-  /**
-   * The resolved task manifest. Optional for `run` (which is
-   * filesystem-driven); later methods (`ci`, workflow generation) need it.
-   * Load it with `loadTasksConfig` from `@theholocron/astromech/config`.
-   */
-  config?: TasksConfig;
-  /** Structured-logging sink. Defaults to a no-op. */
-  logger?: RunLogger;
-  /** User-facing line printer. Defaults to `console.log`. */
-  print?: (line: string) => void;
-  /** Injectable subprocess runner (tests). Defaults to `spawnSync` (stdio inherit). */
-  exec?: ExecFn;
-  /** Injectable fs (tests). Default to `node:fs`. */
-  readFile?: (path: string) => string;
-  fileExists?: (path: string) => boolean;
-  listDir?: (path: string) => string[];
-}
-interface RunOptions {
-  /** Args after `--`, forwarded to the tool / turbo / script. */
-  passthrough?: string[];
-  /** Print the resolved command without running it. */
-  dryRun?: boolean;
-  /** Fail (exit 1) instead of skipping when the repo has no such task. */
-  required?: boolean;
-}
-interface Astromech {
-  /** Run one task locally. */
-  run(task: string, opts?: RunOptions): RunTaskReport;
-}
-declare function createAstromech(options: AstromechOptions): Astromech;
-//#endregion
-//#region src/registry.d.ts
-/**
- * The task registry — how each task runs *locally*, without GitHub
- * Actions. `holocron run <task>` and `holocron ci` resolve against this;
- * adding a task here gives every repo that task.
- *
- * Keyed identically to the workflow templates — a task IS a workflow.
- *
- * Spec: `.notes/tech-astromech-task-runner.spec.md` (epic #581).
- */
-/** How to run one task (or job) locally. */
-interface LocalRunner {
-  /** Binary to invoke — resolved from `node_modules/.bin` then PATH. */
-  tool?: string;
-  /** Args appended after the tool. */
-  args?: string[];
-  /** First entry whose `when` filename matches a repo-root file wins. */
-  detect?: Array<{
-    when: RegExp;
-    tool: string;
-    args?: string[];
-  }>;
-  /** The task is already a holocron subcommand (`sync`, `sync-wiki`). */
-  command?: string;
-}
-interface TaskDef {
-  /**
-   * `null` — no local equivalent (CodeQL, deploys). `holocron ci` reports
-   * it as skipped; `holocron run` treats it as "nothing to do".
-   */
-  local: LocalRunner | null;
-  /** Sub-jobs, keyed by slug — `holocron run audit performance`. */
-  jobs?: Record<string, {
-    local: LocalRunner | null;
-  }>;
-  /** Org-default flags injected by tool name. Removed by a repo override. */
-  flags?: Record<string, string[]>;
-}
-declare const TASKS: Record<string, TaskDef>;
-/** Every task name the registry knows. */
-declare const KNOWN_TASKS: Set<string>;
-//#endregion
 //#region src/thin-callers.d.ts
 /**
  * Workflow templates + thin-caller generation.
@@ -231,4 +154,214 @@ declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<str
  */
 declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
-export { type Astromech, type AstromechOptions, type ExecFn, KNOWN_TASKS, KNOWN_WORKFLOWS, type LocalRunner, type OrgContext, type PreviewConfig, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, runTask };
+//#region src/astromech.d.ts
+interface AstromechOptions {
+  /** Repo root. */
+  cwd: string;
+  /**
+   * The resolved task manifest. Optional for `run` (which is
+   * filesystem-driven); `thinCallers` / `packageScripts` / `ci` need it.
+   * Load it with `loadTasksConfig` from `@theholocron/astromech/config`.
+   */
+  config?: TasksConfig;
+  /**
+   * Org context for the `deploy` workflow's `preview:` shorthand — used to
+   * derive the Cloudflare Pages project / domain when they are not spelt out.
+   */
+  orgContext?: OrgContext;
+  /** Structured-logging sink. Defaults to a no-op. */
+  logger?: RunLogger;
+  /** User-facing line printer. Defaults to `console.log`. */
+  print?: (line: string) => void;
+  /** Injectable subprocess runner (tests). Defaults to `spawnSync` (stdio inherit). */
+  exec?: ExecFn;
+  /** Injectable fs (tests). Default to `node:fs`. */
+  readFile?: (path: string) => string;
+  fileExists?: (path: string) => boolean;
+  listDir?: (path: string) => string[];
+}
+interface RunOptions {
+  /** Args after `--`, forwarded to the tool / turbo / script. */
+  passthrough?: string[];
+  /** Print the resolved command without running it. */
+  dryRun?: boolean;
+  /** Fail (exit 1) instead of skipping when the repo has no such task. */
+  required?: boolean;
+}
+interface Astromech {
+  /** Run one task locally. */
+  run(task: string, opts?: RunOptions): RunTaskReport;
+  /**
+   * The `.github/workflows/*.yml` thin callers for this repo's manifest —
+   * `filename` → YAML content (no generated-by header; the caller adds it).
+   * One entry per `config.tasks` item that has a workflow template and is
+   * not `ci: false`.
+   */
+  thinCallers(): Map<string, string>;
+  /**
+   * `package.json` scripts for this repo's manifest — the `"holocron"` entry
+   * (`config.holocronScript ?? "holocron"`) plus `"<task>": "holocron run
+   * <task>"` for every `config.tasks` item that is a runnable registry task
+   * and not `local: false`. Merge into `package.json`; never clobber. Empty
+   * when there is no config or `syncScripts: false`.
+   */
+  packageScripts(): Record<string, string>;
+}
+declare function createAstromech(options: AstromechOptions): Astromech;
+//#endregion
+//#region src/linters.d.ts
+/**
+ * The linter registry — one list of linter names (from `config.tasks`'
+ * `{ name: "lint", linters: [...] }`, or auto-detected) maps to both the
+ * CI super-linter `VALIDATE_*` env and the native local run. This table is
+ * the single source of truth for that mapping; {@link superLinterConfig}
+ * (CI) and the `holocron run lint` aggregate (local) both read it.
+ *
+ * Spec: `.notes/tech-astromech-task-runner.spec.md` "Lint parity".
+ */
+interface LinterDef {
+  /**
+   * super-linter `VALIDATE_*` keys this linter turns on. Setting any
+   * `VALIDATE_*` puts super-linter in allow-list mode, so emitting only the
+   * enabled keys makes it run exactly this set.
+   */
+  validate: string[];
+  /** super-linter `FIX_*` keys (auto-commit / `--write` parity). */
+  fix?: string[];
+  /**
+   * Local binary, resolved from `node_modules/.bin` then `PATH`. Absent →
+   * the linter has no meaningful local run (`holocron run lint` prints
+   * "CI only"); CI still enforces it.
+   */
+  localBin?: string;
+  /** Args for `localBin` in CHECK mode — never `--write` / `--fix`. */
+  localArgs?: string[];
+  /**
+   * Shown by `holocron run lint` when `localBin` is set but not found on
+   * PATH — the "you're missing a tool the repo needs" nudge.
+   */
+  installHint?: string;
+  /**
+   * Repo-root filenames that auto-enable this linter when the `lint` task
+   * has no explicit `linters` list. Ignored when {@link always} is set.
+   */
+  detect?: string[];
+  /** Enabled regardless of detection (the org baseline). */
+  always?: boolean;
+  /** Reusable-workflow config-file input this linter honors, if any. */
+  configInput?: "eslint-config" | "prettier-config" | "yaml-config";
+}
+/**
+ * Known linters, in execution order. `always` entries are the current
+ * hard-coded super-linter baseline; `prettier` is always-on because the org
+ * applies it universally (super-linter only lints files that exist).
+ */
+declare const LINTERS: Record<string, LinterDef>;
+/** Every linter name the registry knows. */
+declare const LINTER_NAMES: ReadonlySet<string>;
+/**
+ * Resolve the linter set for a repo. An `explicit` list (from
+ * `config.tasks`) wins verbatim; otherwise every `always` linter plus every
+ * linter whose `detect` filenames are present at the repo root. Result is
+ * ordered by {@link LINTERS} declaration order.
+ *
+ * @throws when an `explicit` name is not in the registry — a typo is a
+ * config bug, not a linter to silently skip.
+ */
+declare function resolveLinters(opts: {
+  explicit?: string[];
+  rootFiles: string[];
+}): Array<{
+  name: string;
+  def: LinterDef;
+}>;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * The task registry — how each task runs *locally*, without GitHub
+ * Actions. `holocron run <task>` and `holocron ci` resolve against this;
+ * adding a task here gives every repo that task.
+ *
+ * Keyed identically to the workflow templates — a task IS a workflow.
+ *
+ * Spec: `.notes/tech-astromech-task-runner.spec.md` (epic #581).
+ */
+/** How to run one task (or job) locally. */
+interface LocalRunner {
+  /** Binary to invoke — resolved from `node_modules/.bin` then PATH. */
+  tool?: string;
+  /** Args appended after the tool. */
+  args?: string[];
+  /** First entry whose `when` filename matches a repo-root file wins. */
+  detect?: Array<{
+    when: RegExp;
+    tool: string;
+    args?: string[];
+  }>;
+  /** The task is already a holocron subcommand (`sync`, `sync-wiki`). */
+  command?: string;
+}
+interface TaskDef {
+  /**
+   * `null` — no local equivalent (CodeQL, deploys). `holocron ci` reports
+   * it as skipped; `holocron run` treats it as "nothing to do".
+   */
+  local: LocalRunner | null;
+  /** Sub-jobs, keyed by slug — `holocron run audit performance`. */
+  jobs?: Record<string, {
+    local: LocalRunner | null;
+  }>;
+  /** Org-default flags injected by tool name. Removed by a repo override. */
+  flags?: Record<string, string[]>;
+  /**
+   * This task is the linter aggregate: `holocron run lint` resolves the
+   * linter set (`config.tasks` `linters` or auto-detect) and runs each
+   * natively instead of using `local`. See `linters.ts` / `super-linter.ts`.
+   */
+  linters?: boolean;
+}
+declare const TASKS: Record<string, TaskDef>;
+/** Every task name the registry knows. */
+declare const KNOWN_TASKS: Set<string>;
+//#endregion
+//#region src/super-linter.d.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}.
+ */
+interface SuperLinterConfig {
+  /**
+   * Enabled `VALIDATE_*` / `FIX_*` keys → `"true"`. Only enabled keys are
+   * present (super-linter allow-list mode). Ready for `JSON.stringify`.
+   */
+  env: Record<string, string>;
+  /** Resolved linter names in execution order — for the human-readable comment. */
+  linters: string[];
+  /** Config-file inputs the resolved set honors (`eslint-config`, …). */
+  configInputs: Partial<Record<"eslint-config" | "prettier-config" | "yaml-config", true>>;
+}
+/**
+ * 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`)
+ */
+declare function superLinterConfig(opts: {
+  explicit?: string[];
+  rootFiles: string[];
+  includeFix?: boolean;
+}): SuperLinterConfig;
+/**
+ * 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.
+ */
+declare function baselineSuperLinterEnv(): Record<string, 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, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { t as normalizeTaskEntry } from "./schema-Cf5dfaDO.mjs";
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -14,10 +15,13 @@ const TASKS = {
 		tool: "tsc",
 		args: ["--noEmit"]
 	} },
-	lint: { local: {
-		tool: "eslint",
-		args: ["."]
-	} },
+	lint: {
+		local: {
+			tool: "eslint",
+			args: ["."]
+		},
+		linters: true
+	},
 	build: { local: { detect: [
 		{
 			when: /^tsdown\.config\.(ts|js|mjs|cjs)$/,
@@ -199,41 +203,6 @@ function packageJsonScript(cwd, task, readFile, fileExists) {
 	}
 }
 //#endregion
-//#region src/astromech.ts
-/**
-* `createAstromech(options)` — the self-contained task runner.
-* `@theholocron/cli` instantiates it once and delegates the `run` /
-* `ci` / workflow-generation commands to it (like `@theholocron/logger`).
-*/
-const noopLogger = {
-	debug() {},
-	warn() {}
-};
-const realExec = (cmd, args, opts) => {
-	return { exitCode: spawnSync(cmd, args, {
-		cwd: opts.cwd,
-		stdio: "inherit"
-	}).status ?? -1 };
-};
-function createAstromech(options) {
-	const deps = {
-		print: options.print ?? ((line) => console.log(line)),
-		logger: options.logger ?? noopLogger,
-		exec: options.exec ?? realExec,
-		readFile: options.readFile ?? ((path) => readFileSync(path, "utf8")),
-		fileExists: options.fileExists ?? ((path) => existsSync(path)),
-		listDir: options.listDir ?? ((path) => readdirSync(path))
-	};
-	return { run: (task, opts = {}) => runTask({
-		...deps,
-		task,
-		cwd: options.cwd,
-		passthrough: opts.passthrough ?? [],
-		dryRun: opts.dryRun ?? false,
-		required: opts.required ?? false
-	}) };
-}
-//#endregion
 //#region src/thin-callers.ts
 /**
 * Workflow templates + thin-caller generation.
@@ -490,4 +459,252 @@ function deriveDeployPaths(raw) {
 	return paths;
 }
 //#endregion
-export { KNOWN_TASKS, KNOWN_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, runTask };
+//#region src/astromech.ts
+/**
+* `createAstromech(options)` — the self-contained task runner.
+* `@theholocron/cli` instantiates it once and delegates the `run` /
+* `ci` / workflow-generation commands to it (like `@theholocron/logger`).
+*/
+const noopLogger = {
+	debug() {},
+	warn() {}
+};
+const realExec = (cmd, args, opts) => {
+	return { exitCode: spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		stdio: "inherit"
+	}).status ?? -1 };
+};
+function createAstromech(options) {
+	const deps = {
+		print: options.print ?? ((line) => console.log(line)),
+		logger: options.logger ?? noopLogger,
+		exec: options.exec ?? realExec,
+		readFile: options.readFile ?? ((path) => readFileSync(path, "utf8")),
+		fileExists: options.fileExists ?? ((path) => existsSync(path)),
+		listDir: options.listDir ?? ((path) => readdirSync(path))
+	};
+	const items = () => (options.config?.tasks ?? []).map((i) => normalizeTaskEntry(i));
+	return {
+		run: (task, opts = {}) => runTask({
+			...deps,
+			task,
+			cwd: options.cwd,
+			passthrough: opts.passthrough ?? [],
+			dryRun: opts.dryRun ?? false,
+			required: opts.required ?? false
+		}),
+		thinCallers: () => {
+			const orgCtx = options.orgContext ?? {};
+			const out = /* @__PURE__ */ new Map();
+			for (const entry of items()) {
+				if (entry.ci === false || !KNOWN_WORKFLOWS.has(entry.name)) continue;
+				const rawWith = entry.with;
+				const normalized = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
+				const withOverrides = entry.name === "lint" ? {
+					"enable-auto-commit": true,
+					...normalized ?? {}
+				} : normalized;
+				const additionalPaths = entry.paths ?? (entry.name === "deploy" && rawWith ? deriveDeployPaths(rawWith) : void 0);
+				if (entry.name === "deploy" && rawWith) {
+					const preview = extractPreviewConfig(rawWith, orgCtx);
+					if (preview) {
+						const deployWith = normalizeWorkflowWith(rawWith);
+						const deployPaths = entry.paths ?? deriveDeployPaths(rawWith);
+						out.set("deploy.yml", generateCombinedDeployContent(deployWith, deployPaths, preview));
+						continue;
+					}
+				}
+				out.set(`${entry.name}.yml`, generateThinCallerContent(entry.name, withOverrides, additionalPaths, deps.logger));
+			}
+			return out;
+		},
+		packageScripts: () => {
+			const out = {};
+			if (!options.config || options.config.syncScripts === false) return out;
+			out.holocron = options.config.holocronScript ?? "holocron";
+			for (const entry of items()) {
+				if (entry.local === false || !KNOWN_TASKS.has(entry.name) || TASKS[entry.name]?.local === null) continue;
+				out[entry.name] = `holocron run ${entry.name}`;
+			}
+			return out;
+		}
+	};
+}
+//#endregion
+//#region src/linters.ts
+/**
+* Known linters, in execution order. `always` entries are the current
+* hard-coded super-linter baseline; `prettier` is always-on because the org
+* applies it universally (super-linter only lints files that exist).
+*/
+const LINTERS = {
+	eslint: {
+		validate: ["VALIDATE_JAVASCRIPT_ES", "VALIDATE_TYPESCRIPT_ES"],
+		localBin: "eslint",
+		localArgs: ["."],
+		detect: [
+			"eslint.config.ts",
+			"eslint.config.js",
+			"eslint.config.mjs",
+			"eslint.config.cjs",
+			".eslintrc",
+			".eslintrc.json",
+			".eslintrc.yml",
+			".eslintrc.yaml",
+			".eslintrc.cjs"
+		],
+		configInput: "eslint-config"
+	},
+	prettier: {
+		validate: [
+			"VALIDATE_JAVASCRIPT_PRETTIER",
+			"VALIDATE_JSX_PRETTIER",
+			"VALIDATE_TYPESCRIPT_PRETTIER",
+			"VALIDATE_TSX",
+			"VALIDATE_MARKDOWN_PRETTIER"
+		],
+		fix: [
+			"FIX_JAVASCRIPT_PRETTIER",
+			"FIX_JSX_PRETTIER",
+			"FIX_TYPESCRIPT_PRETTIER",
+			"FIX_TSX",
+			"FIX_MARKDOWN_PRETTIER"
+		],
+		always: true,
+		localBin: "prettier",
+		localArgs: ["--check", "."],
+		configInput: "prettier-config"
+	},
+	yamllint: {
+		validate: ["VALIDATE_YAML"],
+		always: true,
+		localBin: "yamllint",
+		localArgs: ["."],
+		installHint: "brew install yamllint",
+		configInput: "yaml-config"
+	},
+	actionlint: {
+		validate: ["VALIDATE_GITHUB_ACTIONS"],
+		always: true,
+		localBin: "actionlint",
+		localArgs: [],
+		installHint: "brew install actionlint"
+	},
+	gitleaks: {
+		validate: ["VALIDATE_GITLEAKS"],
+		always: true,
+		localBin: "gitleaks",
+		localArgs: ["dir", "--no-banner"],
+		installHint: "brew install gitleaks"
+	},
+	editorconfig: {
+		validate: ["VALIDATE_EDITORCONFIG"],
+		always: true,
+		localBin: "editorconfig-checker",
+		localArgs: [],
+		installHint: "brew install editorconfig-checker"
+	},
+	commitlint: {
+		validate: ["VALIDATE_GIT_COMMITLINT"],
+		always: true,
+		localBin: "commitlint",
+		localArgs: ["--last"]
+	},
+	"git-merge-conflict-markers": {
+		validate: ["VALIDATE_GIT_MERGE_CONFLICT_MARKERS"],
+		always: true
+	},
+	markdownlint: {
+		validate: ["VALIDATE_MARKDOWN"],
+		localBin: "markdownlint-cli2",
+		localArgs: ["**/*.md"],
+		detect: [
+			".markdownlint.json",
+			".markdownlint.jsonc",
+			".markdownlint.yaml",
+			".markdownlint.yml",
+			".markdownlint-cli2.jsonc",
+			".markdownlint-cli2.yaml",
+			".markdownlint-cli2.mjs"
+		]
+	}
+};
+/** Every linter name the registry knows. */
+const LINTER_NAMES = new Set(Object.keys(LINTERS));
+/**
+* Resolve the linter set for a repo. An `explicit` list (from
+* `config.tasks`) wins verbatim; otherwise every `always` linter plus every
+* linter whose `detect` filenames are present at the repo root. Result is
+* ordered by {@link LINTERS} declaration order.
+*
+* @throws when an `explicit` name is not in the registry — a typo is a
+* config bug, not a linter to silently skip.
+*/
+function resolveLinters(opts) {
+	const order = Object.keys(LINTERS);
+	if (opts.explicit && opts.explicit.length > 0) {
+		const unknown = opts.explicit.filter((n) => !LINTER_NAMES.has(n));
+		if (unknown.length > 0) throw new Error(`unknown linter${unknown.length > 1 ? "s" : ""} ${unknown.map((n) => `"${n}"`).join(", ")} — known: ${order.join(", ")}`);
+		const wanted = new Set(opts.explicit);
+		return order.filter((n) => wanted.has(n)).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/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;
+}
+//#endregion
+export { KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, baselineSuperLinterEnv, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, resolveLinters, runTask, superLinterConfig };

package/dist/schema-Cf5dfaDO.mjs

@@ -0,0 +1,11 @@
+//#region src/config/schema.ts
+/** Normalise a `TaskConfigItem` to a full {@link TaskEntry} with defaults applied. */
+function normalizeTaskEntry(item) {
+	return {
+		ci: true,
+		local: true,
+		...typeof item === "string" ? { name: item } : item
+	};
+}
+//#endregion
+export { normalizeTaskEntry as t };

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

@@ -34,6 +34,8 @@ interface TaskEntry {
    * from the config files present.
    */
   linters?: string[];
+  /** Extra `on.push.paths` entries for the generated CI workflow. */
+  paths?: string[];
 }
 /** A task is either its bare name (all defaults) or an entry object. */
 type TaskConfigItem = string | TaskEntry;
@@ -42,6 +44,12 @@ interface TasksConfig {
   tasks?: TaskConfigItem[];
   /** Opt out of the `package.json` script writes. Default `true`. */
   syncScripts?: boolean;
+  /**
+   * The command the synced `"holocron"` `package.json` script runs. Default
+   * `"holocron"` (the installed bin). The source repo overrides it to run
+   * its own build, e.g. `"node packages/cli/dist/cli.mjs"`.
+   */
+  holocronScript?: string;
   /**
    * Required status-check contexts not backed by a task — DCO, semantic
    * PR title, …

package/package.json

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