@theholocron/astromech 4.1.0 → 4.2.0

package/README.md

@@ -79,9 +79,30 @@ 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).
 
 ## 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,101 @@ declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<str
  */
 declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
+//#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/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
 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 };

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";
@@ -199,41 +200,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 +456,77 @@ function deriveDeployPaths(raw) {
 	return paths;
 }
 //#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))
+	};
+	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
 export { KNOWN_TASKS, KNOWN_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, createAstromech, deriveDeployPaths, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, normalizeWorkflowWith, runTask };

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.2.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.2.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.2.0"
   },
   "engines": {
     "node": ">=22"