@theholocron/astromech 4.0.1 → 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,16 +56,119 @@ interface RunTaskReport {
 }
 declare function runTask(input: RunTaskInput): RunTaskReport;
 //#endregion
+//#region src/thin-callers.d.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.
+ */
+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 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.
+ */
+declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
+/**
+ * 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.
+ */
+declare function generateThinCallerContent(name: string, withOverrides?: Record<string, unknown>, additionalPaths?: string[],
+/** Optional sink for the "could not inject `with:`" warning. */
+logger?: {
+  warn(obj: Record<string, unknown>, msg: string): void;
+}): string;
+interface PreviewConfig {
+  /** Cloudflare Pages project name shared across all repos for previews. */
+  project: string;
+  /**
+   * Base domain for preview URLs (e.g. `"preview.theholocron.dev"`).
+   * When set, `holocron setup` automatically provisions:
+   * - Cloudflare Pages custom domain `*.<domain>` on the project
+   * - DNS wildcard CNAME `*.<domain>` → `<project>.pages.dev`
+   *
+   * Preview URLs resolve as `<repo>-pr-<n>.<domain>`.
+   */
+  domain?: string;
+}
+/** Org-level context used to derive preview defaults from `preview: true`. */
+interface OrgContext {
+  /** GitHub org name — becomes the prefix of the default project: `<org>-preview`. */
+  org?: string;
+  /** Org canonical domain — becomes `preview.<domain>` for the default preview domain. */
+  domain?: string;
+  /** Project name — injected as the `name` input to the deploy reusable when `docs: true`. */
+  repoName?: string;
+}
+/**
+ * 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.
+ */
+declare function extractPreviewConfig(raw: Record<string, unknown>, ctx?: OrgContext): PreviewConfig | null;
+/**
+ * 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.
+ */
+declare function generateCombinedDeployContent(deployWith: Record<string, unknown>, paths: string[], preview: Pick<PreviewConfig, "project">): string;
+/**
+ * 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`.
+ */
+declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Derive on.push.paths entries from the deploy with: shorthand.
+ * Used by both `holocron setup` and `sync-workflow-templates`.
+ */
+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); later methods (`ci`, workflow generation) need it.
+   * 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`. */
@@ -88,6 +191,21 @@ interface RunOptions {
 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
@@ -133,4 +251,4 @@ 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, type LocalRunner, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, createAstromech, runTask };
+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,6 +200,262 @@ function packageJsonScript(cwd, task, readFile, fileExists) {
 	}
 }
 //#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) {
+	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) => `      ${k}: ${yamlScalar(v)}`;
+	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).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.
@@ -224,14 +481,52 @@ function createAstromech(options) {
 		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
-	}) };
+	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, TASKS, createAstromech, runTask };
+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.0.1",
+  "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.0.1"
+    "@theholocron/datapad": "4.2.0"
   },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.0.0",
@@ -52,7 +52,8 @@
     "globals": "^17.11.0",
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@theholocron/rollup-plugin-transform-template": "4.2.0"
   },
   "engines": {
     "node": ">=22"