@theholocron/astromech 5.0.0-alpha.4 → 5.0.0-alpha.40

package/dist/index.d.mts

@@ -221,6 +221,16 @@ declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<str
  */
 declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
+//#region src/turbo.d.ts
+interface EnsureRootWorkspaceMemberResult {
+  content: string;
+  changed: boolean;
+}
+interface EnsureTurboDependencyResult {
+  content: string;
+  changed: boolean;
+}
+//#endregion
 //#region src/astromech.d.ts
 interface AstromechOptions {
   /** Repo root. */
@@ -315,6 +325,27 @@ interface Astromech {
    * config (nothing to write). See {@link TurboTaskConfig} in `registry.ts`.
    */
   turboConfig(): string | null;
+  /**
+   * Fixes #692: whenever {@link turboConfig} isn't `null`, this repo's root
+   * package needs to actually be a workspace member for the tasks it fans
+   * out — otherwise a root that's genuinely a directly-buildable package
+   * (not just an orchestrator) silently vanishes from `turbo run <task>`.
+   * Pass `pnpm-workspace.yaml`'s current content (or `""` if none exists —
+   * a no-op either way, since no `packages:` key means single-package mode
+   * already) and root `package.json`'s own `scripts` keys. `changed: false`
+   * means don't write anything — the file is already correct.
+   */
+  ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: readonly string[]): EnsureRootWorkspaceMemberResult;
+  /**
+   * `turboConfig()` writes a `turbo.json` but never touches `package.json`
+   * — a repo with no local `turbo` devDependency falls back to whatever
+   * (if anything) is globally on `PATH`, per `run.ts`'s `resolveBin()`.
+   * Pass root `package.json`'s raw content and `pnpm-workspace.yaml`'s
+   * current content (checked for an existing `turbo` catalog entry, which
+   * takes precedence over the hardcoded fallback version). `changed: false`
+   * means don't write anything — `devDependencies.turbo` already exists.
+   */
+  ensureTurboDependency(packageJson: string, workspaceYaml: string): EnsureTurboDependencyResult;
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
@@ -546,6 +577,58 @@ declare const CI_ORDER: string[];
 /** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
 declare function requiredChecks(config: TasksConfig): string[];
 //#endregion
+//#region src/resolver.d.ts
+/**
+ * Resolves the absolute path to a Bucket A tool's shared `@theholocron/*-config`
+ * entry point, installed in the consuming repo's own `node_modules` — and the
+ * CLI flag(s) to hand it via (`--config`, `--extends`, …). `run.ts` splices the
+ * result into the command it builds for a tool/detect runner or a linter-group
+ * entry, right after the tool's own args.
+ *
+ * Every mapped package's resolved entry point already carries a ready-to-use
+ * default export (a plain re-export for `prettier`/`commitlint`; an invoked,
+ * zero-arg preset for `eslint`/`vitest`/`tsdown` — verified end-to-end against
+ * each tool's real `--config`/`--extends` loader, not just the file's shape).
+ * A repo doesn't need this package installed at all — every lookup degrades to
+ * `[]` (no flag added, the tool falls back to its own auto-discovery of a
+ * local file, unchanged from today) rather than throwing.
+ *
+ * **Local file wins.** A `<tool>.config.*` sitting in `cwd` (whether it's
+ * pure boilerplate or has real per-package customization on top of the
+ * shared bundle, e.g. `mergeConfig(base, { test: { coverage: { exclude }
+ * } })`) always skips the splice, even when the shared package is also
+ * installed — an explicit `--config <shared path>` flag beats a tool's own
+ * auto-discovery every time, so splicing it unconditionally would silently
+ * discard that customization the file is still sitting right there on disk.
+ * The shared bundle is only ever the fallback for a package with *no* local
+ * file at all — that's still the "delete the file to go fully shared" path
+ * this was designed for (#676); it just isn't unconditional (#749).
+ *
+ * `semantic-release`, `devmoji`, `editorconfig-checker`, and `knip` are
+ * deliberately absent — `semantic-release-config`'s `defineConfig()` needs
+ * real per-repo data (branches, npm options) a static `--extends <path>` can't
+ * carry; `devmoji` runs through a git hook template, not `holocron run
+ * <task>`; `editorconfig-checker` has no shared-config package yet; `knip` is
+ * repo-specific by nature, never a shared-config candidate. See
+ * `.notes/tech-config-resolution.spec.md` (#676).
+ */
+interface ResolverDeps {
+  readFile: (path: string) => string;
+  fileExists: (path: string) => boolean;
+}
+/** Every tool name the resolver knows how to point at a shared config. */
+declare const RESOLVABLE_TOOLS: ReadonlySet<string>;
+/**
+ * `<flag> <absolute path>` for `tool`, resolved against `cwd`'s
+ * `node_modules` — or `[]` when the tool isn't mapped, `cwd` already has its
+ * own local config file for it (#749 — local always wins, customized or
+ * not), the shared package isn't installed, its `package.json` doesn't
+ * declare the export subpath this needs, or the resolved file doesn't
+ * actually exist on disk (a stale install, or a package version that
+ * predates the export existing).
+ */
+declare function resolveToolConfig(tool: string, cwd: string, deps: ResolverDeps): string[];
+//#endregion
 //#region src/reusable.d.ts
 /**
  * The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
@@ -573,4 +656,73 @@ declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
  */
 declare function reusableTemplates(): Map<string, string>;
 //#endregion
-export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type ExecFn, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkspacePackage, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask };
+//#region src/tsconfig.d.ts
+/**
+ * `tsconfig.json` generation — Bucket B (config-resolution workstream, #676):
+ * the file must stay committed (the TypeScript language server discovers it
+ * directly from disk, no `--config` override mechanism to hand it a path
+ * instead), but its content is fully derivable, so it's generated rather
+ * than hand-authored — the same category as `.editorconfig`
+ * ({@link "./templates/configs/editorconfig/create-config.js" createConfig})
+ * and {@link codecovConfig}.
+ *
+ * Surveyed every package-level `tsconfig.json` across the org (`holocron`,
+ * `clients`, `utils` — 20+ packages). `extends: "@theholocron/tsconfig/
+ * node-lts"`, `compilerOptions.baseUrl: "./"`, `compilerOptions.outDir:
+ * "./dist"`, `include: ["src/**\/*.ts"]`, and `exclude: ["node_modules",
+ * "dist"]` are uniform in every one — safe defaults here. `paths` (a `@/*`
+ * → `./src/*` import alias) is a real per-package choice, present in
+ * roughly 40% of packages checked — an opt-in parameter, not a default.
+ *
+ * Two fields checked and deliberately *not* absorbed as defaults, unlike
+ * `eslint-config`'s `tsconfigRootDir`/`settings.node` (which turned out
+ * redundant with the shared package's own behavior, `configs`#461):
+ * `compilerOptions.module`/`moduleResolution` (only `@theholocron/cli`
+ * overrides these, to `esnext`/`bundler` — a genuine deviation from the
+ * shared `node-lts` preset's `nodenext`/`nodenext`, needed for its bundler
+ * tooling, not something every package should inherit) and
+ * `compilerOptions.rootDir` (present in exactly two packages, always the
+ * same value `./src` that `include` already implies — an unnecessary
+ * override wherever it appears, not a pattern worth generalizing).
+ *
+ * Monorepo *root* `tsconfig.json` (a TS project-references "solution
+ * file" — `holocron`'s own root is `{ files: [], references: [...] }`,
+ * listing which packages to build) is a structurally different, genuinely
+ * per-repo document — out of scope here, same as Bucket C content.
+ *
+ * Not yet wired into `holocron setup`'s per-package write loop (every
+ * other Bucket B file there is a single repo-root file, safely
+ * overwritten every run — `tsconfig.json` is per-package, and most
+ * packages' files still carry real hand-authored content today, not yet
+ * migrated to a fully-generated state). That per-package iteration +
+ * safe-migration design is `#680`'s job, not duplicated here — this is
+ * the generator itself, ready for it to call.
+ */
+interface TsconfigOptions {
+  /** Human-readable name for the `display` field — the package's own name is the usual choice. */
+  display: string;
+  /**
+   * `@theholocron/tsconfig` variant. Defaults to `"node-lts"` — every
+   * checked package uses it; the other three (`astro`, `nextjs`, `react`)
+   * exist for a template repo's app-shaped packages, not the plain
+   * Node.js library packages this org's currently-migrated repos ship.
+   */
+  variant?: "astro" | "nextjs" | "node-lts" | "react";
+  /**
+   * Add a `@/*` → `./src/*` path alias. A real per-package choice, not a
+   * default — roughly 40% of packages checked use one, the rest don't.
+   */
+  paths?: boolean;
+}
+/**
+ * A package-level `tsconfig.json` — the uniform shape confirmed across
+ * every package checked, parameterized only by the two fields that
+ * genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
+ * `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
+ * JSON has no comment syntax to carry one, and TypeScript's own tolerance
+ * for JSONC comments in `tsconfig.json` isn't worth relying on for a file
+ * this thin).
+ */
+declare function createTsconfig(options: TsconfigOptions): string;
+//#endregion
+export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type ExecFn, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, type LinterDef, type LocalRunner, type OrgContext, type PreviewConfig, RESOLVABLE_TOOLS, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type ResolverDeps, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, type TsconfigOptions, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkspacePackage, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, createTsconfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, resolveToolConfig, reusableTemplates, runCi, runTask };

package/dist/index.mjs

@@ -327,6 +327,141 @@ function resolveLinters(opts) {
 	}));
 }
 //#endregion
+//#region src/resolver.ts
+/**
+* `library` is every mapped tool's org-wide default variant today — every
+* currently-migrated repo (`holocron`, `clients`, `utils`, `configs`,
+* `themes`, `observability`, `skills`) is a publishable library package, and
+* `eslint-config`/`vitest-config`/`tsdown-config` all name their
+* general-purpose preset exactly that. Picking a different variant per repo
+* (an app-type template, say) needs new `holocron.config.ts` surface this
+* doesn't add yet — deliberately out of scope until a real consumer needs it.
+*/
+const TOOL_CONFIGS = {
+	eslint: {
+		package: "@theholocron/eslint-config",
+		exportPath: "./bundles/library",
+		flag: ["--config"]
+	},
+	prettier: {
+		package: "@theholocron/prettier-config",
+		exportPath: ".",
+		flag: ["--config"]
+	},
+	vitest: {
+		package: "@theholocron/vitest-config",
+		exportPath: "./bundles/library",
+		flag: ["--config"]
+	},
+	tsdown: {
+		package: "@theholocron/tsdown-config",
+		exportPath: "./presets/library",
+		flag: ["--config"]
+	},
+	commitlint: {
+		package: "@theholocron/commitlint-config",
+		exportPath: ".",
+		flag: ["--config"]
+	}
+};
+/**
+* Every filename a tool's own auto-discovery would pick up from `cwd` —
+* same extension set `registry.ts`'s `turbo.inputs`/`local.detect` entries
+* already use for these tools, kept in sync by hand (no shared source of
+* truth between the two today). Presence of any one of these means the
+* package has its own local config — customized or not, `resolveToolConfig`
+* can't tell the difference from the filename alone, so it defers to it
+* either way (#749).
+*/
+const LOCAL_CONFIG_FILES = {
+	eslint: [
+		"eslint.config.ts",
+		"eslint.config.js",
+		"eslint.config.mjs",
+		"eslint.config.cjs"
+	],
+	prettier: [
+		"prettier.config.ts",
+		"prettier.config.js",
+		"prettier.config.mjs",
+		"prettier.config.cjs"
+	],
+	vitest: [
+		"vitest.config.ts",
+		"vitest.config.js",
+		"vitest.config.mjs"
+	],
+	tsdown: [
+		"tsdown.config.ts",
+		"tsdown.config.js",
+		"tsdown.config.mjs",
+		"tsdown.config.cjs"
+	],
+	commitlint: [
+		"commitlint.config.ts",
+		"commitlint.config.js",
+		"commitlint.config.mjs",
+		"commitlint.config.cjs"
+	]
+};
+/** Every tool name the resolver knows how to point at a shared config. */
+const RESOLVABLE_TOOLS = new Set(Object.keys(TOOL_CONFIGS));
+/**
+* `<flag> <absolute path>` for `tool`, resolved against `cwd`'s
+* `node_modules` — or `[]` when the tool isn't mapped, `cwd` already has its
+* own local config file for it (#749 — local always wins, customized or
+* not), the shared package isn't installed, its `package.json` doesn't
+* declare the export subpath this needs, or the resolved file doesn't
+* actually exist on disk (a stale install, or a package version that
+* predates the export existing).
+*/
+function resolveToolConfig(tool, cwd, deps) {
+	const spec = TOOL_CONFIGS[tool];
+	if (!spec) return [];
+	if ((LOCAL_CONFIG_FILES[tool] ?? []).some((name) => deps.fileExists(joinPath(cwd, name)))) return [];
+	const pkgDir = joinPath(cwd, "node_modules", ...spec.package.split("/"));
+	const pkgJsonPath = joinPath(pkgDir, "package.json");
+	if (!deps.fileExists(pkgJsonPath)) return [];
+	let pkg;
+	try {
+		pkg = JSON.parse(deps.readFile(pkgJsonPath));
+	} catch {
+		return [];
+	}
+	const relative = resolveExportEntry(pkg.exports?.[spec.exportPath]);
+	if (!relative) return [];
+	const absolute = joinPath(pkgDir, relative.replace(/^\.\//, ""));
+	if (!deps.fileExists(absolute)) return [];
+	return [...spec.flag, absolute];
+}
+/**
+* Unwrap a `package.json#exports` subpath entry down to its file path —
+* either a bare string, or an object with condition keys (`import`,
+* `default`, `require`, …) that may themselves nest one level (`{ import: {
+* types, default } }`, the shape every `@theholocron/*-config` package
+* actually uses). Prefers `import` (this org ships ESM), then `default`,
+* then `require` as a last resort.
+*/
+function resolveExportEntry(entry) {
+	if (typeof entry === "string") return entry;
+	if (entry === null || typeof entry !== "object") return void 0;
+	const conditions = entry;
+	const value = conditions.import ?? conditions.default ?? conditions.require;
+	if (typeof value === "string") return value;
+	if (typeof value === "object" && value !== null) return resolveExportEntry(value);
+}
+/**
+* A minimal, POSIX-safe `path.join` — avoids importing `node:path` just for
+* this. Every path in play here is either already POSIX (a `package.json`
+* `exports` value, always forward-slashed regardless of platform) or built
+* from platform-neutral segments (`cwd`, `"node_modules"`, a scoped package
+* name split on `/`), so a manual join is safe and keeps this module
+* dependency-free like the rest of `run.ts`'s helpers.
+*/
+function joinPath(...segments) {
+	return segments.map((s, i) => i === 0 ? s.replace(/\/+$/, "") : s.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+}
+//#endregion
 //#region src/run.ts
 /**
 * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
@@ -448,8 +583,13 @@ function runTask(input) {
 		const runner = resolveRunner(def.local, cwd, listDir);
 		if (runner) {
 			const flags = (def.flags?.[runner.tool] ?? []).filter((f) => !passthrough.includes(f));
+			const configFlags = resolveToolConfig(runner.tool, cwd, {
+				readFile,
+				fileExists
+			});
 			return run(resolveBin(cwd, runner.tool, fileExists), [
 				...runner.args,
+				...configFlags,
 				...flags,
 				...passthrough
 			]);
@@ -582,7 +722,7 @@ function runAllJobs(input, jobs, passthrough) {
 * turbo/a package script would have already caught in steps 1–2.
 */
 function runLinterGroup(input, names, passthrough) {
-	const { print, logger, listDir, lookPath, cwd, task } = input;
+	const { print, logger, listDir, lookPath, cwd, task, readFile, fileExists } = input;
 	const dryRun = input.dryRun ?? false;
 	const runOne = makeRunOne(input);
 	let rootFiles;
@@ -609,7 +749,15 @@ function runLinterGroup(input, names, passthrough) {
 			print(`! ${name} — ${bin} not on PATH${def.installHint ? `. ${def.installHint}` : ""} (enforced in CI)`);
 			continue;
 		}
-		reports.push(runOne(found, [...def.localArgs ?? [], ...passthrough]));
+		const configFlags = resolveToolConfig(name, cwd, {
+			readFile,
+			fileExists
+		});
+		reports.push(runOne(found, [
+			...configFlags,
+			...def.localArgs ?? [],
+			...passthrough
+		]));
 	}
 	if (reports.length === 0) {
 		const required = input.required && anyHasLocalBin;
@@ -718,7 +866,7 @@ const WORKFLOW_TEMPLATES = {
 	"platform.repoValidation": "name: Platform\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  repo-validation:\n    name: Repo Validation\n    uses: theholocron/.github/.github/workflows/platform.repoValidation.yml@main\n    secrets: inherit\n",
 	"knowledge.wiki": "name: Knowledge\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/knowledge.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/knowledge.wiki.yml@main\n    with:\n      preview: true\n      preview-id: pr-${{ github.event.pull_request.number }}\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: Lint Annotations\n    uses: theholocron/.github/.github/workflows/review.yml@main\n    secrets: inherit\n",
+	review: "name: Source Quality\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: Annotations\n    uses: theholocron/.github/.github/workflows/review.yml@main\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",
 	greetings: "name: Platform\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    name: Greetings\n    uses: theholocron/.github/.github/workflows/greetings.yml@main\n    secrets: inherit\n",
 	dependencies: "name: Platform\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  dependencies:\n    name: Dependencies\n    uses: theholocron/.github/.github/workflows/dependencies.yml@main\n    secrets: inherit\n",
@@ -1197,7 +1345,7 @@ var holocron_default = "name: Holocron\ndescription: >\n  Run the Holocron CLI
 var install_default = "name: Install dependencies\ndescription: Install project dependencies with pnpm frozen lockfile.\n\nruns:\n  using: composite\n\n  steps:\n    - name: Install dependencies\n      if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n      shell: bash\n      run: pnpm install --frozen-lockfile\n";
 //#endregion
 //#region src/templates/reusable/actions/setup.yml
-var setup_default = "name: Setup\ndescription: Prepare the environment and install project dependencies.\n\ninputs:\n  node-version:\n    description: Node.js version\n    required: false\n    default: \"22.x\"\n\nruns:\n  using: composite\n\n  steps:\n    - uses: theholocron/.github/.github/actions/setup-node@main\n      with:\n        node-version: ${{ inputs.node-version }}\n\n    - uses: theholocron/.github/.github/actions/install@main\n\n    # `@theholocron/cli`'s `dist/cli.mjs` doesn't exist yet at this point, so\n    # pnpm's workspace bin-linking can't create `node_modules/.bin/holocron`\n    # (silent `WARN ... ENOENT`, not a hard failure). Every package whose\n    # scripts delegate via `holocron run <task> --` then fails at run time\n    # with `holocron: not found` (#698). Build the CLI, then re-run install\n    # so pnpm links the bin now that the target file exists — the second\n    # install is cheap, the store is already warm from the first.\n    - name: Build the Holocron CLI\n      shell: bash\n      run: pnpm --filter @theholocron/cli build\n\n    - name: Re-link workspace bins\n      uses: theholocron/.github/.github/actions/install@main\n\n    - name: Cache Turbo artifacts\n      if: ${{ hashFiles('turbo.json') != '' }}\n      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0\n      with:\n        path: .turbo\n        key: turbo-${{ runner.os }}-${{ github.sha }}\n        restore-keys: |\n          turbo-${{ runner.os }}-\n";
+var setup_default = "name: Setup\ndescription: Prepare the environment and install project dependencies.\n\ninputs:\n  node-version:\n    description: Node.js version\n    required: false\n    default: \"22.x\"\n\nruns:\n  using: composite\n\n  steps:\n    - uses: theholocron/.github/.github/actions/setup-node@main\n      with:\n        node-version: ${{ inputs.node-version }}\n\n    - uses: theholocron/.github/.github/actions/install@main\n\n    # `@theholocron/cli`'s `dist/cli.mjs` doesn't exist yet at this point, so\n    # pnpm's workspace bin-linking can't create `node_modules/.bin/holocron`\n    # (silent `WARN ... ENOENT`, not a hard failure). Every package whose\n    # scripts delegate via `holocron run <task> --` then fails at run time\n    # with `holocron: not found` (#698). Same fix the `holocron` composite\n    # action already applies for its own direct invocation (see its \"Build\n    # the workspace when the CLI resolves to an unbuilt checkout\" step) —\n    # mirrored here so it also covers *nested* `holocron run <task> --`\n    # calls from inside package.json scripts, which that action's own guard\n    # doesn't reach. `pnpm build` (not a scoped `--filter`) so the CLI's own\n    # workspace dependencies (e.g. rollup-plugin-transform-template) build\n    # in topological order too — a scoped build skips them and fails.\n    # No-op in every consumer repo, where the published tarball already\n    # ships `dist/`.\n    - name: Build the Holocron CLI\n      shell: bash\n      run: |\n        if [ ! -f node_modules/@theholocron/cli/dist/cli.mjs ]; then\n          echo \"→ @theholocron/cli dist/ missing — building the workspace from source\" >&2\n          pnpm build\n          echo \"→ re-linking node_modules/.bin — pnpm skipped it pre-build\" >&2\n          pnpm install --frozen-lockfile\n        fi\n\n    - name: Cache Turbo artifacts\n      if: ${{ hashFiles('turbo.json') != '' }}\n      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0\n      with:\n        path: .turbo\n        key: turbo-${{ runner.os }}-${{ github.sha }}\n        restore-keys: |\n          turbo-${{ runner.os }}-\n";
 //#endregion
 //#region src/templates/reusable/actions/setup-node.yml
 var setup_node_default = "name: Setup Node\ndescription: Install pnpm and Node.js with pnpm dependency caching.\n\ninputs:\n  node-version:\n    description: Node.js version\n    required: false\n    default: \"22.x\"\nruns:\n  using: composite\n\n  steps:\n    - name: Setup pnpm\n      if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n      uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4\n\n    - name: Setup Node.js\n      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0\n      with:\n        node-version: ${{ hashFiles('.node-version') != '' && '' || inputs.node-version }}\n        node-version-file: ${{ hashFiles('.node-version') != '' && '.node-version' || '' }}\n        cache: ${{ hashFiles('pnpm-lock.yaml') != '' && 'pnpm' || '' }}\n        # Do NOT add registry-url here. setup-node writes .npmrc with\n        # _authToken=${NODE_AUTH_TOKEN} and sets NPM_CONFIG_USERCONFIG to it.\n        # pnpm reads that file, fails env-var substitution when the token is\n        # empty, and loses auth entirely. Without registry-url, pnpm 10.15+\n        # handles Trusted Publishing via its own native OIDC exchange.\n\n    - name: Add node_modules/.bin to PATH\n      shell: bash\n      run: echo \"$GITHUB_WORKSPACE/node_modules/.bin\" >> $GITHUB_PATH\n";
@@ -1232,7 +1380,7 @@ const REUSABLE_WORKFLOWS = {
 	"delivery.deploy": "name: Deploy\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      type:\n        description: \"Type of deployment: docs or storybook\"\n        required: true\n        type: string\n      storybook-projects:\n        description: >\n          JSON array of { \"name\"?, \"workingDir\", \"outputDir\"? } objects for storybook deploys.\n          Each is built via `pnpm -C <workingDir> build:storybook`. If \"name\" is provided the\n          output is placed under `sandbox/<name>/`; omit \"name\" for single-repo deploys and the\n          output lands directly in `sandbox/`.\n        type: string\n        required: false\n        default: \"[]\"\n      build-script:\n        description: pnpm script that builds the Storybook static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: build:storybook\n      output-dir:\n        description: Directory where Storybook writes its static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: storybook-static\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pages: write\n      id-token: write\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' }}\n        run: pnpm -C docs build\n\n      - name: Build Storybook projects\n        if: ${{ inputs.storybook-projects != '[]' }}\n        env:\n          PROJECTS: ${{ inputs.storybook-projects }}\n        run: |\n          echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n            workingDir=$(echo \"$project\" | jq -r '.workingDir')\n            pnpm -C \"$workingDir\" build:storybook\n          done\n\n      - name: Build Storybook\n        if: ${{ inputs.type == 'storybook' && inputs.storybook-projects == '[]' }}\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n        run: pnpm run \"$BUILD_SCRIPT\"\n\n      - name: Assemble site\n        env:\n          DEPLOY_TYPE: ${{ inputs.type }}\n          PROJECTS: ${{ inputs.storybook-projects }}\n          STORYBOOK_OUTPUT_DIR: ${{ inputs.output-dir }}\n        run: |\n          mkdir -p _site\n          if [ \"$DEPLOY_TYPE\" = \"docs\" ]; then\n            cp -r docs/dist/. _site/\n          fi\n          if [ \"$PROJECTS\" != \"[]\" ]; then\n            echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n              name=$(echo \"$project\" | jq -r '.name // \"\"')\n              workingDir=$(echo \"$project\" | jq -r '.workingDir')\n              outputDir=$(echo \"$project\" | jq -r '.outputDir // \"storybook-static\"')\n              if [ -n \"$name\" ]; then\n                target=\"_site/sandbox/${name}\"\n              else\n                target=\"_site/sandbox\"\n              fi\n              mkdir -p \"$target\"\n              cp -r \"${workingDir}/${outputDir}/.\" \"$target/\"\n            done\n          elif [ \"$DEPLOY_TYPE\" = \"storybook\" ]; then\n            mkdir -p _site/sandbox\n            cp -r \"${STORYBOOK_OUTPUT_DIR}/.\" _site/sandbox/\n          fi\n\n      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1\n        name: Upload pages artifact\n        with:\n          path: _site\n\n      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5\n        id: deployment\n        name: Deploy to GitHub Pages\n",
 	"delivery.bundleSize": "name: Audit the Bundle Size\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    secrets:\n      CODECOV_TOKEN:\n        required: false\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  bundle-size:\n    name: Upload bundle stats to Codecov\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n      # Read by the bundle-stats uploader inside `holocron run delivery.build`.\n      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: theholocron/.github/.github/actions/holocron@main\n        name: Build and upload bundle stats\n        with:\n          task: delivery.build\n",
 	"platform.repoSync": "name: Sync\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      steps:\n        description: >\n          Sync steps to run (default: all). Valid values:\n          labels, properties, teams, topics, keywords, description, homepage, readme, workflows, wiki.\n          Pass a space-separated list to run a subset, e.g. \"readme\" or \"readme wiki\".\n        type: string\n        required: false\n    secrets:\n      HOLOCRON_ADMIN_TOKEN:\n        description: Fine-grained PAT with admin scopes (labels, properties, teams).\n        required: false\n      HOLOCRON_AXIOM_TOKEN:\n        description: >\n          Axiom API token. When set alongside the HOLOCRON_AXIOM_DATASET\n          repo/org variable, the CLI ships this run's structured logs to Axiom.\n          Falls back to the vendor-native AXIOM_TOKEN secret.\n        required: false\n      AXIOM_TOKEN:\n        description: Vendor-native fallback for HOLOCRON_AXIOM_TOKEN.\n        required: false\n      HOLOCRON_DEPLOY_TOKEN:\n        description: Fine-grained PAT for GitHub Pages configuration.\n        required: false\n      HOLOCRON_ISSUES_TOKEN:\n        description: Fine-grained PAT for issue management.\n        required: false\n      HOLOCRON_ORG_TOKEN:\n        description: Org-scoped fine-grained PAT for team sync and org properties.\n        required: false\n      HOLOCRON_READ_TOKEN:\n        description: Fine-grained PAT for read-only GitHub API calls.\n        required: false\n      HOLOCRON_SYNC_TOKEN:\n        required: false\n      GH_TOKEN:\n        description: >\n          Generic GitHub token fallback for gh CLI calls. Used when\n          HOLOCRON_SYNC_TOKEN is not set.\n        required: false\n\njobs:\n  sync:\n    name: Run holocron sync\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    permissions:\n      contents: write\n      pull-requests: write\n    # Job-level so the `holocron` composite action's steps inherit them.\n    env:\n      HOLOCRON_ADMIN_TOKEN: ${{ secrets.HOLOCRON_ADMIN_TOKEN }}\n      HOLOCRON_AXIOM_TOKEN: ${{ secrets.HOLOCRON_AXIOM_TOKEN || secrets.AXIOM_TOKEN }}\n      HOLOCRON_AXIOM_DATASET: ${{ vars.HOLOCRON_AXIOM_DATASET || vars.AXIOM_DATASET }}\n      POSTHOG_PROJECT_TOKEN: ${{ vars.POSTHOG_PROJECT_TOKEN }}\n      HOLOCRON_DEPLOY_TOKEN: ${{ secrets.HOLOCRON_DEPLOY_TOKEN }}\n      HOLOCRON_ISSUES_TOKEN: ${{ secrets.HOLOCRON_ISSUES_TOKEN }}\n      HOLOCRON_ORG_TOKEN: ${{ secrets.HOLOCRON_ORG_TOKEN }}\n      HOLOCRON_READ_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN }}\n      HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Run holocron sync\n        # The `holocron` action resolves @theholocron/cli from node_modules (or\n        # builds the workspace when it's an unbuilt checkout — the holocron repo\n        # itself). `inputs.steps` is a space-separated list or empty; the\n        # `--steps <list>` arg is omitted when empty.\n        uses: theholocron/.github/.github/actions/holocron@main\n        with:\n          command: sync\n          args: ${{ inputs.steps != '' && format('--steps {0}', inputs.steps) || '' }}\n\n      - name: Format generated files\n        run: |\n          pnpm exec prettier --write README.md docs/src/content/docs/index.mdx 2>/dev/null || true\n          # `holocron sync` writes package.json fields (keywords, description,\n          # homepage) with a plain assignment, which appends new keys at the\n          # end — re-apply the canonical order the lint config enforces.\n          pnpm exec eslint --fix --no-warn-ignored package.json 2>/dev/null || true\n\n      - uses: theholocron/.github/.github/actions/auto-commit@main\n        id: auto-commit\n        name: Commit sync changes\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n          branch: chore/auto-sync\n          commit-message: \"chore: sync from holocron.config\"\n          commit-options: \"--no-verify\"\n\n      - name: Open PR if changes were committed\n        if: steps.auto-commit.outputs.changes-detected == 'true'\n        run: |\n          gh pr create \\\n            --title \"chore: sync README and repo metadata\" \\\n            --body \"Automated sync triggered by changes to config or package files. Merge to apply.\" \\\n            --base main \\\n            --head chore/auto-sync \\\n          || echo \"PR already open — branch updated.\"\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - name: Broadcast wiki sync if navbar changed\n        if: >-\n          steps.auto-commit.outputs.changes-detected == 'true' &&\n          github.event_name == 'push' &&\n          (inputs.steps == '' || contains(inputs.steps, 'wiki'))\n        run: |\n          if git diff HEAD~1 --name-only | grep -q 'fern/docs.yml'; then\n            gh workflow run sync-dispatch.yml \\\n              --repo theholocron/.github \\\n              --field \"steps=wiki\" \\\n            || echo \"skipping broadcast — insufficient permissions\"\n          fi\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n",
-	"platform.commitStandards": "name: Commit Standards\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    secrets:\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  commit-standards:\n    name: Run commitlint\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      # No local equivalent (linters.ts: commitlint has no localBin — enforced\n      # only at commit time via the commit-msg hook, and here in CI over the\n      # PR's commit range). Not run through the holocron composite action.\n      - name: Run commitlint over the PR range\n        if: github.event_name == 'pull_request'\n        run: pnpm exec commitlint --from \"${{ github.event.pull_request.base.sha }}\" --to \"${{ github.sha }}\"\n",
+	"platform.commitStandards": "name: Commit Standards\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    secrets:\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  commit-standards:\n    name: Run commitlint\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      # No local equivalent (linters.ts: commitlint has no localBin — enforced\n      # only at commit time via the commit-msg hook, and here in CI over the\n      # PR's commit range). Not run through the holocron composite action.\n      #\n      # --config <resolved shared path> (config-resolution workstream, #676)\n      # — falls back to commitlint's own auto-discovery of a local\n      # commitlint.config.ts when the shared package's built dist/ isn't\n      # present, same guard as the commit-msg hook.\n      - name: Run commitlint over the PR range\n        if: github.event_name == 'pull_request'\n        run: |\n          COMMITLINT_CONFIG=\"node_modules/@theholocron/commitlint-config/dist/index.js\"\n          if [ -f \"$COMMITLINT_CONFIG\" ]; then\n            pnpm exec commitlint --config \"$COMMITLINT_CONFIG\" --from \"${{ github.event.pull_request.base.sha }}\" --to \"${{ github.sha }}\"\n          else\n            pnpm exec commitlint --from \"${{ github.event.pull_request.base.sha }}\" --to \"${{ github.sha }}\"\n          fi\n",
 	"platform.repoValidation": "name: Repo Validation\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    secrets:\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  adrs:\n    name: Validate ADRs and specs\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: theholocron/.github/.github/actions/holocron@main\n        name: Validate ADR and spec frontmatter\n        with:\n          task: platform.repoValidation\n          job: adrs\n\n  registry:\n    name: Validate registry consistency\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: theholocron/.github/.github/actions/holocron@main\n        name: Validate registry consistency\n        with:\n          task: platform.repoValidation\n          job: registry\n\n  docs-presence:\n    name: Validate docs presence\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: theholocron/.github/.github/actions/holocron@main\n        name: Validate docs presence for new packages\n        with:\n          task: platform.repoValidation\n          job: docsPresence\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}\n\n  conclusion:\n    name: Conclusion\n    runs-on: ubuntu-latest\n    if: always()\n    needs: [adrs, registry, docs-presence]\n    steps:\n      - name: Check job statuses\n        run: |\n          if [[ \"$RESULTS\" == *\"failure\"* ]] || [[ \"$RESULTS\" == *\"cancelled\"* ]]; then\n            exit 1\n          fi\n        env:\n          RESULTS: ${{ join(needs.*.result, ',') }}\n",
 	"knowledge.wiki": "name: Wiki\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      fern-version:\n        description: >\n          Fern CLI version to install. Pin this to avoid breaking changes when\n          Fern updates their config schema.\n        type: string\n        required: false\n        default: \"5.114.1\"\n      preview:\n        description: >\n          When true, publishes a preview instead of production.\n          Requires preview-id to be set.\n        type: boolean\n        required: false\n        default: false\n      preview-id:\n        description: >\n          Stable ID for the preview build. Use the PR number (e.g. \"pr-123\")\n          so the same preview URL is reused on every push to the branch.\n        type: string\n        required: false\n        default: \"\"\n      fern-org:\n        description: >\n          DEPRECATED — the preview URL is now read from Fern's own output.\n          Kept as a fallback for building the URL when that parse fails, and so\n          existing callers do not error.\n        type: string\n        required: false\n        default: \"\"\n      base-path:\n        description: >\n          DEPRECATED — see fern-org. Basepath appended to the fallback preview\n          URL (e.g. \"holocron\" for multi-source routing).\n        type: string\n        required: false\n        default: \"\"\n    secrets:\n      HOLOCRON_FERN_TOKEN:\n        required: false\n      FERN_TOKEN:\n        required: false\n\njobs:\n  publish:\n    name: Publish to Fern\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    permissions:\n      contents: read\n      deployments: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - name: Install Fern CLI\n        run: npm install -g \"fern-api@$FERN_VERSION\"\n        env:\n          FERN_VERSION: ${{ inputs.fern-version }}\n\n      - name: Publish docs\n        if: ${{ !inputs.preview }}\n        run: fern generate --docs\n        env:\n          FERN_TOKEN: ${{ secrets.HOLOCRON_FERN_TOKEN || secrets.FERN_TOKEN }}\n\n      - name: Preview docs\n        id: preview\n        if: ${{ inputs.preview && inputs.preview-id != '' }}\n        env:\n          FERN_TOKEN: ${{ secrets.HOLOCRON_FERN_TOKEN || secrets.FERN_TOKEN }}\n          PREVIEW_ID: ${{ inputs.preview-id }}\n        run: |\n          out=$(fern generate --docs --preview --id \"$PREVIEW_ID\" 2>&1) || { printf '%s\\n' \"$out\"; exit 1; }\n          printf '%s\\n' \"$out\"\n          # Fern prints \"Published docs to https://<org>-preview-<id>.docs.buildwithfern.com/<path>\"\n          url=$(printf '%s\\n' \"$out\" | grep -oiE 'https://[a-z0-9.-]+\\.docs\\.buildwithfern\\.com[^ )]*' | head -n1)\n          echo \"url=$url\" >> \"$GITHUB_OUTPUT\"\n\n      - name: Report preview URL\n        if: ${{ inputs.preview && inputs.preview-id != '' }}\n        env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          CAPTURED_URL: ${{ steps.preview.outputs.url }}\n          FERN_ORG: ${{ inputs.fern-org }}\n          PREVIEW_ID: ${{ inputs.preview-id }}\n          BASE_PATH: ${{ inputs.base-path }}\n        run: |\n          PREVIEW_URL=\"$CAPTURED_URL\"\n          if [ -z \"$PREVIEW_URL\" ] && [ -n \"$FERN_ORG\" ]; then\n            PREVIEW_URL=\"https://${FERN_ORG}-preview-${PREVIEW_ID}.docs.buildwithfern.com${BASE_PATH:+/${BASE_PATH}}\"\n          fi\n          if [ -z \"$PREVIEW_URL\" ]; then\n            echo \"::warning::no preview URL parsed from Fern output and no fern-org fallback — skipping the deployment widget\"\n            exit 0\n          fi\n          PAYLOAD=$(printf '{\"ref\":\"%s\",\"environment\":\"wiki (Preview)\",\"description\":\"Wiki\",\"production_environment\":false,\"auto_merge\":false,\"required_contexts\":[]}' \\\n            \"$GITHUB_HEAD_REF\")\n          DEPLOY_ID=$(printf '%s\\n' \"$PAYLOAD\" | gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            --method POST --input - | jq -r '.id')\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments/${DEPLOY_ID}/statuses\" \\\n            --method POST --field state=success --field environment_url=\"$PREVIEW_URL\"\n",
 	bookkeeping: "name: Bookkeeping\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      configuration-path:\n        description: Path to the labeler configuration file in the calling repo\n        type: string\n        required: false\n        default: .github/labeler.yml\n\njobs:\n  label:\n    name: Apply Labels\n    permissions:\n      contents: read\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 5\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        with:\n          sparse-checkout: ${{ inputs.configuration-path || '.github/labeler.yml' }}\n          sparse-checkout-cone-mode: false\n\n      - uses: github/issue-labeler@c1b0f9f52a63158c4adc09425e858e87b32e9685 # v3.4\n        if: ${{ github.event_name == 'pull_request' && hashFiles(inputs.configuration-path || '.github/labeler.yml') != '' }}\n        # v3.4 bundles Node 20; allow it to run under Actions' current default.\n        env:\n          ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true\n        with:\n          # Fall back to default path when triggered directly (not via workflow_call)\n          # because inputs.* defaults only apply on workflow_call events.\n          configuration-path: ${{ inputs.configuration-path || '.github/labeler.yml' }}\n          include-title: 1\n          include-body: 0\n          sync-labels: 1\n          enable-versioned-regex: 0\n          repo-token: ${{ github.token }}\n",
@@ -1339,6 +1487,120 @@ function turboConfig(config) {
 		tasks
 	}, null, 2)}\n`;
 }
+/**
+* Fixes #692: `turboConfig()` writes a `turbo.json` the moment *any* task in
+* the manifest has fan-out config — with no check for whether the repo's own
+* root package is actually covered by `pnpm-workspace.yaml`'s `packages:`
+* list. A repo shaped like `observability` (the library lives at repo root;
+* `packages:` lists only an unrelated `docs` site) silently breaks the
+* instant `turbo.json` exists: `holocron run <task>` switches from running
+* root's own script directly to `turbo run <task>`, which only sees declared
+* workspace members — root vanishes, the task "succeeds" with zero real work
+* done (confirmed empirically: `Packages in scope: docs`, root never
+* mentioned, exit 0).
+*
+* Detection is narrow and specific: root only needs to be an explicit
+* workspace member if its *own* `package.json` has a script literally named
+* after one of the tasks turbo.json is about to fan out — a plain
+* orchestrator root (`holocron`'s own `"build": "turbo run delivery.build"`,
+* which has no `delivery.build` script itself) never trips this; only a root
+* that's genuinely a directly-buildable package does. Confirmed the fix
+* empirically too — adding `.` to `packages:` makes turbo pick root back up
+* (`Packages in scope: docs, root-lib`) without disturbing the sibling
+* package's own caching.
+*
+* A targeted line-based edit, not a full YAML parse/reserialize — same
+* pattern `codecov.ts`'s `mergeCodecovComponents()` already uses for editing
+* an existing generated file. `pnpm-workspace.yaml` routinely carries a
+* `catalog:`/`catalogs:`/`overrides:` block after `packages:`; a real parser
+* round-trip risks reformatting or reordering content nobody asked to touch.
+* Only ever *adds* a line — never rewrites or reorders anything already
+* there — and is a no-op (`changed: false`) whenever root doesn't need it,
+* root is already listed, or `packages:` isn't in the plain block-list form
+* every repo checked actually uses.
+*/
+function ensureRootWorkspaceMember(workspaceYaml, rootScripts, taskNames) {
+	if (!taskNames.some((t) => rootScripts.includes(t))) return {
+		content: workspaceYaml,
+		changed: false
+	};
+	const lines = workspaceYaml.split("\n");
+	const packagesLineIdx = lines.findIndex((l) => /^packages:\s*$/.test(l));
+	if (packagesLineIdx === -1) return {
+		content: workspaceYaml,
+		changed: false
+	};
+	const items = [];
+	let cursor = packagesLineIdx + 1;
+	while (cursor < lines.length && /^\s*-\s*/.test(lines[cursor])) {
+		items.push(lines[cursor]);
+		cursor++;
+	}
+	if (items.some((item) => {
+		const value = item.replace(/^\s*-\s*/, "").replace(/^["']|["']$/g, "").trim();
+		return value === "." || value === "";
+	})) return {
+		content: workspaceYaml,
+		changed: false
+	};
+	const newLine = `${items[0]?.match(/^(\s*-\s*)/)?.[1] ?? "  - "}"."`;
+	return {
+		content: [
+			...lines.slice(0, packagesLineIdx + 1),
+			newLine,
+			...lines.slice(packagesLineIdx + 1)
+		].join("\n"),
+		changed: true
+	};
+}
+/**
+* Fallback pin when a repo's own `pnpm-workspace.yaml` has no `turbo`
+* catalog entry yet — matches this repo's own catalog version (the
+* canonical source-of-truth repo for the whole org's tooling).
+*/
+const DEFAULT_TURBO_VERSION = "^2.10.12";
+/**
+* Ensures `turbo` is declared in `package.json#devDependencies` — found
+* the hard way rolling this out to `observability` (predates #691):
+* `turboConfig()` writes a `turbo.json` the moment any task has fan-out
+* config, but never touches `package.json`, so a repo that predates this
+* feature (or never had `turbo` installed for any other reason) ends up
+* with a `turbo.json` and nothing local to run it. `resolveBin()`
+* (`run.ts`) falls back to a bare `turbo` on `PATH` when
+* `node_modules/.bin/turbo` doesn't exist — on a machine with no global
+* `turbo` at all that's a hard failure for every task; on one that
+* happens to have an unrelated global install, silent version skew
+* (confirmed empirically: a global 2.6.0 rejected this repo's generated
+* `turbo.json` outright — `Found an unknown key "globalDependencies"`,
+* a schema key from a newer version than the one actually resolved).
+*
+* Prefers `"catalog:"` when the repo's own `pnpm-workspace.yaml` already
+* has a `turbo` catalog entry — matches every already-migrated repo
+* (`holocron`, `clients`, …) — falling back to a real pinned version
+* otherwise. Never touches an existing `devDependencies.turbo` entry, so
+* a repo pinning its own version on purpose is left alone — idempotent,
+* a no-op once set either way.
+*/
+function ensureTurboDependency(packageJson, workspaceYaml) {
+	const pkg = JSON.parse(packageJson);
+	if (typeof pkg.devDependencies?.turbo === "string") return {
+		content: packageJson,
+		changed: false
+	};
+	const hasTurboCatalogEntry = /^\s*turbo:\s*\S/m.test(workspaceYaml);
+	const devDependencies = {
+		...pkg.devDependencies,
+		turbo: hasTurboCatalogEntry ? "catalog:" : DEFAULT_TURBO_VERSION
+	};
+	const updated = {
+		...pkg,
+		devDependencies
+	};
+	return {
+		content: `${JSON.stringify(updated, null, 2)}\n`,
+		changed: true
+	};
+}
 //#endregion
 //#region src/astromech.ts
 /**
@@ -1441,8 +1703,39 @@ function createAstromech(options) {
 		reusableTemplates: () => reusableTemplates(),
 		requiredChecks: () => requiredChecks(options.config ?? {}),
 		codecovConfig: (existing) => codecovConfig(options.cwd, existing),
-		turboConfig: () => turboConfig(options.config ?? {})
+		turboConfig: () => turboConfig(options.config ?? {}),
+		ensureRootWorkspaceMember: (workspaceYaml, rootScripts) => {
+			return ensureRootWorkspaceMember(workspaceYaml, rootScripts, (options.config?.tasks ?? []).map(normalizeTaskEntry).filter((e) => e.local !== false).map((e) => e.name));
+		},
+		ensureTurboDependency: (packageJson, workspaceYaml) => ensureTurboDependency(packageJson, workspaceYaml)
+	};
+}
+//#endregion
+//#region src/tsconfig.ts
+/**
+* A package-level `tsconfig.json` — the uniform shape confirmed across
+* every package checked, parameterized only by the two fields that
+* genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
+* `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
+* JSON has no comment syntax to carry one, and TypeScript's own tolerance
+* for JSONC comments in `tsconfig.json` isn't worth relying on for a file
+* this thin).
+*/
+function createTsconfig(options) {
+	const variant = options.variant ?? "node-lts";
+	const compilerOptions = {
+		baseUrl: "./",
+		outDir: "./dist"
+	};
+	if (options.paths) compilerOptions.paths = { "@/*": ["./src/*"] };
+	const config = {
+		display: options.display,
+		extends: `@theholocron/tsconfig/${variant}`,
+		compilerOptions,
+		include: ["src/**/*.ts"],
+		exclude: ["node_modules", "dist"]
 	};
+	return JSON.stringify(config, null, 2) + "\n";
 }
 //#endregion
-export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, reusableTemplates, runCi, runTask };
+export { CI_ORDER, KNOWN_TASKS, KNOWN_WORKFLOWS, LINTERS, LINTER_NAMES, RESOLVABLE_TOOLS, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, TASKS, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, createTsconfig, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, resolveToolConfig, reusableTemplates, runCi, runTask };

package/package.json

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