@theholocron/astromech 5.0.0-alpha.146 → 5.0.0-alpha.148

package/dist/index.mjs

@@ -1,7 +1,10 @@
-import { r as normalizeTaskEntry, t as loadTasksConfig } from "./load-ytspboBj.mjs";
-import { spawnSync } from "node:child_process";
+import { r as normalizeTaskEntry, t as loadTasksConfig } from "./load-BqpxDjMJ.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
+import { stringifyJson } from "@theholocron/json-utils";
+import { dependencyNames, detectPackageManager, readPackageJsonSync } from "@theholocron/pkg-utils";
+import { spawnSync } from "node:child_process";
+import { findExecutableSync } from "@theholocron/fs-utils";
 //#region src/templates/codecov/codecov.yml
 var codecov_default = "codecov:\n  require_ci_to_pass: true\n\ncoverage:\n  precision: 2\n  round: down\n  status:\n    project:\n      default:\n        target: auto\n        threshold: 2%\n        # Infra-only PRs (dep bumps, config, lockfile) touch no coverable code,\n        # so codecov produces no report to compare. Pass instead of blocking\n        # forever on a required check that will never post.\n        if_not_found: success\n    patch:\n      default:\n        target: 80%\n        if_not_found: success\n\ncomment:\n  layout: \"reach,diff,flags,components\"\n  behavior: default\n  require_changes: true\n\ncomponent_management:\n  default_rules:\n    statuses:\n      - type: patch\n        target: 80%\n        if_not_found: success\n  individual_components:\n";
 //#endregion
@@ -607,6 +610,27 @@ function reusableTemplates() {
 }
 //#endregion
 //#region src/registry.ts
+/**
+* The task registry — how each task runs *locally*, without GitHub
+* Actions. `holocron run <task>` and `holocron run ci` resolve against this;
+* adding a task here gives every repo that task.
+*
+* Keyed identically to the workflow templates — a task IS a workflow. This
+* is the canonical vocabulary table (epic #672, D11): every other artifact
+* (`KNOWN_TASKS`, `thin-callers.ts`'s `KNOWN_WORKFLOWS`/`WORKFLOW_CHECK_CONTEXTS`,
+* `CI_ORDER`) derives from these keys rather than hand-duplicating them —
+* including the future GitHub App (#679), which imports this same table for
+* config-schema validation instead of reimplementing its own copy.
+*
+* Task names are an intent-facing vocabulary (`verification.*`,
+* `sourceQuality.*`, `security.*`, `delivery.*`, `platform.*`,
+* `knowledge.*`), not tool names — `eslint`/`vitest`/`tsdown`/… stay
+* internal to this file and `theholocron/configs`. See
+* `docs/wiki/specifications/tech-vocabulary-rename.spec.md` (#675) for the full mapping and
+* the reasoning behind each namespace and decomposition.
+*
+* Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` (epic #581).
+*/
 const TASKS = {
 	"verification.unitTests": {
 		local: {
@@ -869,11 +893,11 @@ function turboConfig(config) {
 		} : turbo;
 	}
 	if (Object.keys(tasks).length === 0) return null;
-	return `${JSON.stringify({
+	return stringifyJson({
 		$schema: "https://turborepo.org/schema.json",
 		globalDependencies: GLOBAL_DEPENDENCIES,
 		tasks
-	}, null, 2)}\n`;
+	});
 }
 /**
 * Fixes #692: `turboConfig()` writes a `turbo.json` the moment *any* task in
@@ -1014,13 +1038,22 @@ function ensureTurboDependency(packageJson, workspaceYaml) {
 		devDependencies
 	};
 	return {
-		content: `${JSON.stringify(updated, null, 2)}\n`,
+		content: stringifyJson(updated, { like: packageJson }),
 		changed: true
 	};
 }
 //#endregion
 //#region src/tasks/run/linters.ts
 /**
+* The linter registry — one list of linter names (from `config.tasks`'
+* `{ name: "lint", linters: [...] }`, or auto-detected) maps to both the
+* CI super-linter `VALIDATE_*` env and the native local run. This table is
+* the single source of truth for that mapping; {@link superLinterConfig}
+* (CI) and the `holocron run lint` aggregate (local) both read it.
+*
+* Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` "Lint parity".
+*/
+/**
 * Known linters, in execution order. `always` entries are the current
 * hard-coded super-linter baseline; `prettier` is always-on because the org
 * applies it universally (super-linter only lints files that exist).
@@ -1164,7 +1197,79 @@ function resolveLinters(opts) {
 	}));
 }
 //#endregion
-//#region src/tasks/run/resolver.ts
+//#region src/tasks/run/resolve-bin.ts
+/** `<cwd>/node_modules/.bin/<tool>` when it exists, else the bare `tool` name (left to `PATH`). */
+function resolveBin(cwd, tool, fileExists) {
+	const local = join(cwd, "node_modules", ".bin", tool);
+	return fileExists(local) ? local : tool;
+}
+//#endregion
+//#region src/tasks/run/resolve-runner.ts
+const mkRunner = (tool, args = []) => ({
+	tool,
+	args
+});
+/**
+* Resolve `{ tool, args }` for a runner, applying `detect[]` against repo
+* files, falling back (#750) to each candidate's `tool` name against
+* `package.json`'s own declared dependencies when neither matches by
+* filename. Only called for `tool` / `detect` runners — the caller handles
+* `command` runners itself, so `local.detect` is present whenever
+* `local.tool` is not.
+*
+* The dependency fallback matters once a Bucket A migration (#680) deletes
+* a build tool's own config file (`tsdown.config.ts`, `vite.config.ts`, …):
+* that file was the *only* signal `detect[]` had to offer, so removing it
+* used to make `delivery.build` report "no task for this repo" and silently
+* skip the build, even though the tool is still very much in use — a
+* package can't actually build with `tsdown` without it in
+* `dependencies`/`devDependencies`, so that's a signal at least as reliable
+* as the config file, and one deleting the file doesn't remove.
+*
+* **Per-candidate, not two full passes** (#750 follow-up — the first
+* shipped version got this wrong): `delivery.build`'s own `detect[]` ends
+* with `{ when: /^tsconfig\.json$/, tool: "tsc" }` as its last-resort
+* fallback, and `tsconfig.json` exists in essentially every package
+* regardless of build tool. A "check every candidate's filename, *then*
+* check every candidate's dependency" two-pass design would let that
+* always-present fallback file win over a real `tsdown`/`vite`/`rollup`
+* dependency match, the moment the earlier candidates' own config files are
+* gone — exactly backwards. Checking `(file match) || (dependency match)`
+* together for each candidate before moving to the next preserves the
+* intended precedence: a real signal for an *earlier* candidate, by either
+* means, still wins over a later candidate's mere filename presence.
+*/
+function resolveRunner(local, cwd, listDir, readFile) {
+	if (local.tool) return mkRunner(local.tool, local.args);
+	let files;
+	try {
+		files = listDir(cwd);
+	} catch {
+		files = [];
+	}
+	const deps = dependencyNames(readPackageJsonSync(cwd, { readFile }));
+	for (const candidate of local.detect) if (files.some((f) => candidate.when.test(f)) || deps.has(candidate.tool)) return mkRunner(candidate.tool, candidate.args);
+}
+//#endregion
+//#region src/tasks/run/resolve-export-entry.ts
+/**
+* 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);
+}
+//#endregion
+//#region src/tasks/run/tool-configs.ts
 /**
 * `library` is every mapped tool's org-wide default variant today — every
 * currently-migrated repo (`holocron`, `clients`, `utils`, `configs`,
@@ -1241,7 +1346,42 @@ const LOCAL_CONFIG_FILES = {
 		"commitlint.config.cjs"
 	]
 };
-new Set(Object.keys(TOOL_CONFIGS));
+//#endregion
+//#region src/tasks/run/resolve-tool-config.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).
+*/
 /**
 * `<flag> <absolute path>` for `tool`, resolved against `cwd`'s
 * `node_modules` — or `[]` when the tool isn't mapped, `cwd` already has its
@@ -1254,9 +1394,9 @@ new Set(Object.keys(TOOL_CONFIGS));
 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 ((LOCAL_CONFIG_FILES[tool] ?? []).some((name) => deps.fileExists(join(cwd, name)))) return [];
+	const pkgDir = join(cwd, "node_modules", ...spec.package.split("/"));
+	const pkgJsonPath = join(pkgDir, "package.json");
 	if (!deps.fileExists(pkgJsonPath)) return [];
 	let pkg;
 	try {
@@ -1266,36 +1406,21 @@ function resolveToolConfig(tool, cwd, deps) {
 	}
 	const relative = resolveExportEntry(pkg.exports?.[spec.exportPath]);
 	if (!relative) return [];
-	const absolute = joinPath(pkgDir, relative.replace(/^\.\//, ""));
+	const absolute = join(pkgDir, relative);
 	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/tasks/run/turbo-defines-task.ts
+/** `true` when `<cwd>/turbo.json` declares `task` (under `tasks`, or turbo 1.x's `pipeline`). */
+function turboDefinesTask(cwd, task, readFile, fileExists) {
+	if (!fileExists(join(cwd, "turbo.json"))) return false;
+	try {
+		const turbo = JSON.parse(readFile(join(cwd, "turbo.json")));
+		return Boolean(turbo.tasks?.[task] ?? turbo.pipeline?.[task]);
+	} catch {
+		return false;
+	}
 }
 //#endregion
 //#region src/tasks/run/run.ts
@@ -1404,8 +1529,11 @@ function runTask(input) {
 		];
 		return run(resolveBin(cwd, "turbo", fileExists), args);
 	}
-	const script = packageJsonScript(cwd, task, readFile, fileExists);
-	if (script && !/^holocron run\b/.test(script.trim())) return run(packageManager(cwd, readFile, fileExists), [
+	const script = readPackageJsonSync(cwd, { readFile })?.scripts?.[task];
+	if (script && !/^holocron run\b/.test(script.trim())) return run(detectPackageManager(cwd, {
+		readFile,
+		fileExists
+	}), [
 		"run",
 		task,
 		...passthrough.length ? ["--", ...passthrough] : []
@@ -1627,92 +1755,6 @@ function runLinterGroup(input, names, passthrough) {
 		command
 	};
 }
-const mkRunner = (tool, args = []) => ({
-	tool,
-	args
-});
-/**
-* Resolve `{ tool, args }` for a runner, applying `detect[]` against repo
-* files, falling back (#750) to each candidate's `tool` name against
-* `package.json`'s own declared dependencies when neither matches by
-* filename. Only called for `tool` / `detect` runners — the caller handles
-* `command` runners itself, so `local.detect` is present whenever
-* `local.tool` is not.
-*
-* The dependency fallback matters once a Bucket A migration (#680) deletes
-* a build tool's own config file (`tsdown.config.ts`, `vite.config.ts`, …):
-* that file was the *only* signal `detect[]` had to offer, so removing it
-* used to make `delivery.build` report "no task for this repo" and silently
-* skip the build, even though the tool is still very much in use — a
-* package can't actually build with `tsdown` without it in
-* `dependencies`/`devDependencies`, so that's a signal at least as reliable
-* as the config file, and one deleting the file doesn't remove.
-*
-* **Per-candidate, not two full passes** (#750 follow-up — the first
-* shipped version got this wrong): `delivery.build`'s own `detect[]` ends
-* with `{ when: /^tsconfig\.json$/, tool: "tsc" }` as its last-resort
-* fallback, and `tsconfig.json` exists in essentially every package
-* regardless of build tool. A "check every candidate's filename, *then*
-* check every candidate's dependency" two-pass design would let that
-* always-present fallback file win over a real `tsdown`/`vite`/`rollup`
-* dependency match, the moment the earlier candidates' own config files are
-* gone — exactly backwards. Checking `(file match) || (dependency match)`
-* together for each candidate before moving to the next preserves the
-* intended precedence: a real signal for an *earlier* candidate, by either
-* means, still wins over a later candidate's mere filename presence.
-*/
-function resolveRunner(local, cwd, listDir, readFile) {
-	if (local.tool) return mkRunner(local.tool, local.args);
-	let files;
-	try {
-		files = listDir(cwd);
-	} catch {
-		files = [];
-	}
-	const deps = packageJsonDependencies(cwd, readFile);
-	for (const candidate of local.detect) if (files.some((f) => candidate.when.test(f)) || deps.has(candidate.tool)) return mkRunner(candidate.tool, candidate.args);
-}
-/** Every key from `package.json`'s `dependencies` + `devDependencies`, or an empty set on any read/parse failure. */
-function packageJsonDependencies(cwd, readFile) {
-	try {
-		const pkg = JSON.parse(readFile(join(cwd, "package.json")));
-		return /* @__PURE__ */ new Set([...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})]);
-	} catch {
-		return /* @__PURE__ */ new Set();
-	}
-}
-function resolveBin(cwd, tool, fileExists) {
-	const local = join(cwd, "node_modules", ".bin", tool);
-	return fileExists(local) ? local : tool;
-}
-function packageManager(cwd, readFile, fileExists) {
-	try {
-		const pkg = JSON.parse(readFile(join(cwd, "package.json")));
-		if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
-	} catch {}
-	if (fileExists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (fileExists(join(cwd, "bun.lockb"))) return "bun";
-	if (fileExists(join(cwd, "yarn.lock"))) return "yarn";
-	if (fileExists(join(cwd, "package-lock.json"))) return "npm";
-	return "pnpm";
-}
-function turboDefinesTask(cwd, task, readFile, fileExists) {
-	if (!fileExists(join(cwd, "turbo.json"))) return false;
-	try {
-		const turbo = JSON.parse(readFile(join(cwd, "turbo.json")));
-		return Boolean(turbo.tasks?.[task] ?? turbo.pipeline?.[task]);
-	} catch {
-		return false;
-	}
-}
-function packageJsonScript(cwd, task, readFile, fileExists) {
-	if (!fileExists(join(cwd, "package.json"))) return void 0;
-	try {
-		return JSON.parse(readFile(join(cwd, "package.json"))).scripts?.[task];
-	} catch {
-		return;
-	}
-}
 //#endregion
 //#region src/tasks/ci.ts
 /**
@@ -1784,19 +1826,7 @@ function taskName(item) {
 	return typeof item === "string" ? item : item.name;
 }
 //#endregion
-//#region src/tasks/group.ts
-/**
-* `holocron run <namespace>` — run every configured task under one
-* namespace prefix (`sourceQuality.*`, `verification.*`, …) in sequence.
-* `Astromech.run()` falls back here whenever the given name isn't an exact
-* `TASKS` entry but matches the prefix of one or more configured tasks —
-* same "aggregate several real tasks into one report" shape `runCi` already
-* established, scoped to one namespace instead of the merge-gating set.
-*
-* Every task in the namespace always runs — one task's failure never skips
-* the rest, same as `runCi`'s own loop — so a single invocation surfaces
-* every problem in the namespace at once instead of stopping at the first.
-*/
+//#region src/tasks/match-namespace.ts
 /** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
 function matchNamespace(config, namespace) {
 	const prefix = `${namespace}.`;
@@ -1805,6 +1835,8 @@ function matchNamespace(config, namespace) {
 		return names;
 	}, []);
 }
+//#endregion
+//#region src/tasks/group.ts
 function runGroup(input) {
 	const { print, namespace } = input;
 	const names = matchNamespace(input.config, namespace);
@@ -1843,29 +1875,47 @@ function runGroup(input) {
 	};
 }
 //#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/observability`).
-*/
-const noopLogger = {
-	debug() {},
-	warn() {}
-};
+//#region src/utils/default-list-dirs.ts
+const defaultListDirs = (path) => readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+//#endregion
+//#region src/utils/default-read-json.ts
+const defaultReadJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+//#endregion
+//#region src/utils/default-run.ts
+const defaultRun = (command, args, opts) => spawnSync(command, args, {
+	encoding: "utf8",
+	...opts
+});
+//#endregion
+//#region src/utils/default-sleep.ts
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+//#endregion
+//#region src/utils/exec.ts
+/** Runs `cmd` with the parent's stdio; a signal-killed or unspawnable process reports `-1`. */
 const realExec = (cmd, args, opts) => {
 	return { exitCode: spawnSync(cmd, args, {
 		cwd: opts.cwd,
 		stdio: "inherit"
 	}).status ?? -1 };
 };
+//#endregion
+//#region src/utils/look-path.ts
 /** `node_modules/.bin/<bin>`, else the first `PATH` entry that has it, else `null`. */
-const realLookPath = (cwd, bin) => {
-	const local = join(cwd, "node_modules", ".bin", bin);
-	if (existsSync(local)) return local;
-	for (const dir of (process.env["PATH"] ?? "").split(":")) if (dir && existsSync(join(dir, bin))) return join(dir, bin);
-	return null;
+const realLookPath = (cwd, bin) => findExecutableSync(bin, { path: join(cwd, "node_modules", ".bin") }) ?? findExecutableSync(bin) ?? null;
+//#endregion
+//#region src/utils/noop-logger.ts
+/** The `RunLogger` used when the caller injects none: drops every record. */
+const noopLogger = {
+	debug() {},
+	warn() {}
 };
+//#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/observability`).
+*/
 function createAstromech(options) {
 	const deps = {
 		print: options.print ?? ((line) => console.log(line)),
@@ -1980,6 +2030,47 @@ function createAstromech(options) {
 //#endregion
 //#region src/generators/tsconfig.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 repo 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.
+*/
+/**
 * 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
@@ -2002,81 +2093,25 @@ function createTsconfig(options) {
 		include: ["src/**/*.ts"],
 		exclude: ["node_modules", "dist"]
 	};
-	return JSON.stringify(config, null, 2) + "\n";
+	return stringifyJson(config);
 }
 //#endregion
-//#region src/tasks/deploy-on-release.ts
-/**
-* Deploy workspace packages once a release has published (holocron#930).
-*
-* A package opts in with a `delivery.deploy` task in its own `holocron.config`
-* whose `with.on` is `"release"`:
-*
-* ```ts
-* // packages/<app>/holocron.config.ts
-* tasks: [{ name: "delivery.deploy", with: { on: "release", channel: "alpha" } }];
-* ```
-*
-* `channel` defaults to `main` (a stable release); set a prerelease identifier
-* such as `alpha` to deploy those releases instead.
-*
-* The shared `delivery.publish` workflow runs this (`holocron deploy on-release`)
-* as its own `deploy` job after the release job, so a deploy is a separate,
-* re-runnable check rather than a step buried in the release log. Each package
-* with such a task deploys when the release is on its `channel` and changes a file under its paths: the package itself plus its
-* `workspace:*` dependencies ({@link defaultPaths}), or an explicit
-* `with.paths`. It first waits for npm to serve the release's new versions of
-* those dependencies ({@link waitForPublished}) — the registry can lag a version
-* it has just accepted, and the deploy installs them — then runs
-* `pnpm --filter <package> delivery.deploy`.
-*
-* The release is already published by then, so a failed deploy can't undo it;
-* it fails this job instead, loudly and re-runnable on its own. A task is
-* `skip`ped (not failed) only when it doesn't apply to this release.
-*
-* A `delivery.deploy` task with `on: "release"` generates no CI workflow.
-*/
+//#region src/tasks/deploy-on-release/constants.ts
 /** A stable release (no prerelease identifier) is on `main`, the default channel for a task. */
 const MAIN_CHANNEL = "main";
 const DEPLOY_TASK = "delivery.deploy";
 /** How long to wait for npm to serve the release's versions, and how often to ask. */
 const WAIT_TIMEOUT_MS = 3e5;
 const WAIT_INTERVAL_MS = 1e4;
-function scanWorkspaceDir(dirPath, { readJson, listDirs }) {
-	let folders;
-	try {
-		folders = listDirs(dirPath);
-	} catch {
-		return [];
-	}
-	return folders.flatMap((folder) => {
-		try {
-			const manifest = readJson(join(dirPath, folder, "package.json"));
-			if (!manifest.name) return [];
-			return [{
-				name: manifest.name,
-				dir: join(dirPath, folder),
-				version: manifest.version,
-				dependencies: manifest.dependencies ?? {}
-			}];
-		} catch {
-			return [];
-		}
-	});
-}
-/**
-* Every package under `<repoRoot>/packages/*` and `<repoRoot>/plugins/*`
-* with a readable, named `package.json` — `holocron`'s own layout splits
-* vendor plugin packages into `plugins/*`, sibling to `packages/*`.
-*/
-function workspacePackages(repoRoot, tree) {
-	return [...scanWorkspaceDir(join(repoRoot, "packages"), tree), ...scanWorkspaceDir(join(repoRoot, "plugins"), tree)];
-}
+//#endregion
+//#region src/tasks/deploy-on-release/workspace-dependencies.ts
 /** The `workspace:*` dependencies of `pkg`, as workspace packages (with their current version). */
 function workspaceDependencies(pkg, all) {
 	const names = new Set(Object.entries(pkg.dependencies).filter(([, spec]) => String(spec).startsWith("workspace:")).map(([name]) => name));
 	return all.filter((candidate) => names.has(candidate.name));
 }
+//#endregion
+//#region src/tasks/deploy-on-release/default-paths.ts
 /**
 * The paths a release must touch to redeploy `pkg` when its manifest doesn't
 * list them: its own folder plus the folder of every
@@ -2088,6 +2123,8 @@ function workspaceDependencies(pkg, all) {
 function defaultPaths(repoRoot, pkg, all) {
 	return [pkg, ...workspaceDependencies(pkg, all)].map(({ dir }) => `${relative(repoRoot, dir)}/`);
 }
+//#endregion
+//#region src/tasks/deploy-on-release/deploy-targets.ts
 /**
 * The packages whose manifest declares a release-time `delivery.deploy`
 * (`with.on === "release"`), with the task's options resolved.
@@ -2095,7 +2132,7 @@ function defaultPaths(repoRoot, pkg, all) {
 function deployTargets(packages, manifests) {
 	return packages.flatMap((pkg) => (manifests.get(pkg.dir)?.tasks ?? []).flatMap((item) => {
 		const entry = normalizeTaskEntry(item);
-		if (entry.name !== DEPLOY_TASK || entry.with?.["on"] !== "release") return [];
+		if (entry.name !== "delivery.deploy" || entry.with?.["on"] !== "release") return [];
 		const { channel, paths } = entry.with;
 		return [{
 			pkg,
@@ -2104,6 +2141,32 @@ function deployTargets(packages, manifests) {
 		}];
 	}));
 }
+//#endregion
+//#region src/tasks/deploy-on-release/should-deploy.ts
+/**
+* @param channel The release's channel: its prerelease identifier (`alpha`), or `main` for a stable release.
+* @param changedFiles `undefined` when there's no previous release to diff against.
+*/
+function shouldDeploy({ channel, configuredChannel, changedFiles, paths }) {
+	if (channel !== configuredChannel) return {
+		deploy: false,
+		reason: `channel "${channel}" isn't "${configuredChannel}"`
+	};
+	if (changedFiles === void 0) return {
+		deploy: true,
+		reason: "no previous release to diff against"
+	};
+	const touched = changedFiles.find((file) => paths.some((path) => file.startsWith(path)));
+	return touched ? {
+		deploy: true,
+		reason: `the release changes ${touched}`
+	} : {
+		deploy: false,
+		reason: `the release changes nothing under ${paths.join(", ")}`
+	};
+}
+//#endregion
+//#region src/tasks/deploy-on-release/wait-for-published.ts
 /**
 * Waits until npm serves every `name@version` in `packages`, asking with
 * `npm view --prefer-online` (so npm's local cache can't answer for the
@@ -2129,35 +2192,70 @@ async function waitForPublished({ packages, run, sleep, now, cwd, timeoutMs = WA
 		await sleep(intervalMs);
 	}
 }
+//#endregion
+//#region src/tasks/deploy-on-release/workspace-packages.ts
+function scanWorkspaceDir(dirPath, { readJson, listDirs }) {
+	let folders;
+	try {
+		folders = listDirs(dirPath);
+	} catch {
+		return [];
+	}
+	return folders.flatMap((folder) => {
+		try {
+			const manifest = readJson(join(dirPath, folder, "package.json"));
+			if (!manifest.name) return [];
+			return [{
+				name: manifest.name,
+				dir: join(dirPath, folder),
+				version: manifest.version,
+				dependencies: manifest.dependencies ?? {}
+			}];
+		} catch {
+			return [];
+		}
+	});
+}
 /**
-* @param channel The release's channel: its prerelease identifier (`alpha`), or `main` for a stable release.
-* @param changedFiles `undefined` when there's no previous release to diff against.
+* Every package under `<repoRoot>/packages/*` and `<repoRoot>/plugins/*`
+* with a readable, named `package.json` — `holocron`'s own layout splits
+* vendor plugin packages into `plugins/*`, sibling to `packages/*`.
 */
-function shouldDeploy({ channel, configuredChannel, changedFiles, paths }) {
-	if (channel !== configuredChannel) return {
-		deploy: false,
-		reason: `channel "${channel}" isn't "${configuredChannel}"`
-	};
-	if (changedFiles === void 0) return {
-		deploy: true,
-		reason: "no previous release to diff against"
-	};
-	const touched = changedFiles.find((file) => paths.some((path) => file.startsWith(path)));
-	return touched ? {
-		deploy: true,
-		reason: `the release changes ${touched}`
-	} : {
-		deploy: false,
-		reason: `the release changes nothing under ${paths.join(", ")}`
-	};
+function workspacePackages(repoRoot, tree) {
+	return [...scanWorkspaceDir(join(repoRoot, "packages"), tree), ...scanWorkspaceDir(join(repoRoot, "plugins"), tree)];
 }
-const defaultRun = (command, args, opts) => spawnSync(command, args, {
-	encoding: "utf8",
-	...opts
-});
-const defaultReadJson = (path) => JSON.parse(readFileSync(path, "utf8"));
-const defaultListDirs = (path) => readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+//#endregion
+//#region src/tasks/deploy-on-release/deploy-on-release.ts
+/**
+* Deploy workspace packages once a release has published (holocron#930).
+*
+* A package opts in with a `delivery.deploy` task in its own `holocron.config`
+* whose `with.on` is `"release"`:
+*
+* ```ts
+* // packages/<app>/holocron.config.ts
+* tasks: [{ name: "delivery.deploy", with: { on: "release", channel: "alpha" } }];
+* ```
+*
+* `channel` defaults to `main` (a stable release); set a prerelease identifier
+* such as `alpha` to deploy those releases instead.
+*
+* The shared `delivery.publish` workflow runs this (`holocron deploy on-release`)
+* as its own `deploy` job after the release job, so a deploy is a separate,
+* re-runnable check rather than a step buried in the release log. Each package
+* with such a task deploys when the release is on its `channel` and changes a file under its paths: the package itself plus its
+* `workspace:*` dependencies ({@link defaultPaths}), or an explicit
+* `with.paths`. It first waits for npm to serve the release's new versions of
+* those dependencies ({@link waitForPublished}) — the registry can lag a version
+* it has just accepted, and the deploy installs them — then runs
+* `pnpm --filter <package> delivery.deploy`.
+*
+* The release is already published by then, so a failed deploy can't undo it;
+* it fails this job instead, loudly and re-runnable on its own. A task is
+* `skip`ped (not failed) only when it doesn't apply to this release.
+*
+* A `delivery.deploy` task with `on: "release"` generates no CI workflow.
+*/
 /**
 * Deploys every package whose manifest declares a release-time deploy that
 * applies to this release. Never throws for a deploy problem: each package's
@@ -2165,7 +2263,7 @@ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 */
 async function deployOnRelease(options, { run = defaultRun, readJson = defaultReadJson, listDirs = defaultListDirs, sleep = defaultSleep, now = Date.now, loadTasks = loadTasksConfig } = {}) {
 	const { cwd, from, print } = options;
-	const channel = options.channel || MAIN_CHANNEL;
+	const channel = options.channel || "main";
 	const to = options.to ?? "HEAD";
 	const packages = workspacePackages(cwd, {
 		readJson,