@theholocron/astromech 5.0.0-alpha.13 → 5.0.0-alpha.134

package/dist/index.d.mts

@@ -1,121 +1,11 @@
-import { r as TasksConfig } from "./schema-D01VYg43.mjs";
-//#region src/run.d.ts
-/**
- * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
- * of its sub-jobs) locally.
- *
- * A `job` argument only applies to tasks that declare `jobs`; for any other
- * task it is folded back into the passthrough (`holocron run delivery.build
- * src/`).
- *
- * Resolution:
- *
- *   J. job given                              → TASKS[task].jobs[job].local (unknown job → exit 1)
- *   1. turbo.json defines the task            → `turbo run <task>`
- *   2. package.json has a `<task>` script     → `<pm> run <task>`
- *      (unless it's the `holocron run …` thin caller — that recurses)
- *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
- *   3b. TASKS[task].linterGroup               → run each resolved linter natively (see below)
- *   4. TASKS[task].jobs has entries           → run each job in declared order
- *   5. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
- *   5b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
- *   6. unknown task                           → "unknown task" (exit 1)
- *
- * A `linterGroup` task (`sourceQuality.staticAnalysis`, etc.) runs its fixed
- * set of `linters.ts` entries, each still gated by that linter's own
- * `detect`/`always` rule — every entry runs its `localBin` natively when
- * found on PATH. Missing tools are flagged; the exit code is the worst of
- * the lot. Unlike the old single `lint` task, this check runs *after*
- * turbo/`package.json` resolution (step 3b, not step 0) — a `linterGroup`
- * task is a normal turbo-delegatable task like any other.
- */
-/** Minimal structural logger — `@theholocron/observability`'s `Logger` satisfies it. */
-interface RunLogger {
-  debug(obj: Record<string, unknown>, msg?: string): void;
-  warn(obj: Record<string, unknown>, msg?: string): void;
-}
-type ExecFn = (cmd: string, args: string[], opts: {
-  cwd: string;
-}) => {
-  exitCode: number;
-};
-/**
- * Everything `runTask` needs from the outside world. `createAstromech`
- * fills these with real implementations (or the caller's injected ones);
- * `runTask` never reaches for a global itself, so it has no default
- * branches to leave untested.
- */
-interface RunDeps {
-  print: (line: string) => void;
-  logger: RunLogger;
-  exec: ExecFn;
-  readFile: (path: string) => string;
-  fileExists: (path: string) => boolean;
-  listDir: (path: string) => string[];
-  /** `node_modules/.bin/<bin>` or a PATH entry; `null` when not runnable. */
-  lookPath: (cwd: string, bin: string) => string | null;
-}
-interface RunTaskInput extends RunDeps {
-  /** Registry task name, e.g. `"test"`. */
-  task: string;
-  /**
-   * Sub-job within the task, e.g. `"performance"` in `holocron run audit
-   * performance`. Ignored (folded into `passthrough`) for tasks with no `jobs`.
-   */
-  job?: string;
-  /** Directory to run in. */
-  cwd: string;
-  /** Args after `--` on the command line, forwarded to the tool / turbo / script. */
-  passthrough?: string[];
-  /** Print the resolved command without running it. */
-  dryRun?: boolean;
-  /** Turn "no such task for this repo" (normally exit 0) into a failure. */
-  required?: boolean;
-  /** `turbo --filter=<pkg>` passthrough (monorepo). Ignored when the repo has no `turbo.json`. */
-  filter?: string;
-}
-interface RunTaskReport {
-  status: "ok" | "fail" | "skip" | "dry-run" | "unknown";
-  /** Resolved command, for the caller / tests. */
-  command?: string;
-  message?: string;
-}
-declare function runTask(input: RunTaskInput): RunTaskReport;
-//#endregion
-//#region src/ci.d.ts
-interface CiOptions {
-  /** Print the plan without running anything. */
-  dryRun?: boolean;
-  /** `turbo --filter=<pkg>` passthrough (monorepo). */
-  filter?: string;
-  /** `"required"` (default) or `"all"` (every `ci: true` task). */
-  scope?: "required" | "all";
-}
-interface CiJobReport {
-  task: string;
-  /** The branch-protection check context, or `null` for a non-gating task. */
-  checkContext: string | null;
-  status: "ok" | "fail" | "skip" | "dry-run";
-  command?: string;
-  message?: string;
-}
-interface CiReport {
-  status: "ok" | "fail";
-  jobs: CiJobReport[];
-}
-interface CiInput extends RunDeps, CiOptions {
-  cwd: string;
-  config: TasksConfig;
-}
-declare function runCi(input: CiInput): CiReport;
-//#endregion
-//#region src/thin-callers.d.ts
+import { r as TasksConfig } from "./schema-BDld3xq1.mjs";
+//#region src/generators/github-action-thin-callers.d.ts
 /**
  * Workflow templates + thin-caller generation.
  *
  * `WORKFLOW_TEMPLATES` holds each reusable `.github/workflows/<name>.yml`
  * (synced to `theholocron/.github`); `generateThinCallerContent` wraps one
- * into the thin caller `holocron setup` / `holocron sync` write locally.
+ * into the thin caller `holocron repo setup` / `holocron repo sync` write locally.
  */
 declare const WORKFLOW_TEMPLATES: Record<string, string>;
 declare const KNOWN_WORKFLOWS: Set<string>;
@@ -165,7 +55,7 @@ interface PreviewConfig {
   project: string;
   /**
    * Base domain for preview URLs (e.g. `"preview.theholocron.dev"`).
-   * When set, `holocron setup` automatically provisions:
+   * When set, `holocron repo setup` automatically provisions:
    * - Cloudflare Pages custom domain `*.<domain>` on the project
    * - DNS wildcard CNAME `*.<domain>` → `<project>.pages.dev`
    *
@@ -212,20 +102,162 @@ declare function generateCombinedDeployContent(deployWith: Record<string, unknow
  *   - run-chromatic object → run-chromatic: true + chromatic-projects
  *   - plain arrays → JSON-stringified for YAML scalar quoting
  *
- * Used by both `holocron setup` and `sync-workflow-templates`.
+ * Used by both `holocron repo setup` and `sync-workflow-templates`.
  */
 declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<string, unknown>;
 /**
  * Derive on.push.paths entries from the deploy with: shorthand.
- * Used by both `holocron setup` and `sync-workflow-templates`.
+ * Used by both `holocron repo setup` and `sync-workflow-templates`.
  */
 declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
-//#region src/turbo.d.ts
+//#region src/generators/turbo.d.ts
 interface EnsureRootWorkspaceMemberResult {
   content: string;
   changed: boolean;
 }
+interface EnsureTurboDependencyResult {
+  content: string;
+  changed: boolean;
+}
+//#endregion
+//#region src/tasks/run/run.d.ts
+/**
+ * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
+ * of its sub-jobs) locally.
+ *
+ * A `job` argument only applies to tasks that declare `jobs`; for any other
+ * task it is folded back into the passthrough (`holocron run delivery.build
+ * src/`).
+ *
+ * Resolution:
+ *
+ *   J. job given                              → TASKS[task].jobs[job].local (unknown job → exit 1)
+ *   1. turbo.json defines the task            → `turbo run <task>`
+ *   2. package.json has a `<task>` script     → `<pm> run <task>`
+ *      (unless it's the `holocron run …` thin caller — that recurses)
+ *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
+ *   3b. TASKS[task].linterGroup               → run each resolved linter natively (see below)
+ *   4. TASKS[task].jobs has entries           → run each job in declared order
+ *   5. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
+ *   5b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
+ *   6. unknown task                           → "unknown task" (exit 1)
+ *
+ * A `linterGroup` task (`sourceQuality.staticAnalysis`, etc.) runs its fixed
+ * set of `linters.ts` entries, each still gated by that linter's own
+ * `detect`/`always` rule — every entry runs its `localBin` natively when
+ * found on PATH. Missing tools are flagged; the exit code is the worst of
+ * the lot. Unlike the old single `lint` task, this check runs *after*
+ * turbo/`package.json` resolution (step 3b, not step 0) — a `linterGroup`
+ * task is a normal turbo-delegatable task like any other.
+ */
+/** Minimal structural logger — `@theholocron/observability`'s `Logger` satisfies it. */
+interface RunLogger {
+  debug(obj: Record<string, unknown>, msg?: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+}
+type ExecFn = (cmd: string, args: string[], opts: {
+  cwd: string;
+}) => {
+  exitCode: number;
+};
+/**
+ * Everything `runTask` needs from the outside world. `createAstromech`
+ * fills these with real implementations (or the caller's injected ones);
+ * `runTask` never reaches for a global itself, so it has no default
+ * branches to leave untested.
+ */
+interface RunDeps {
+  print: (line: string) => void;
+  logger: RunLogger;
+  exec: ExecFn;
+  readFile: (path: string) => string;
+  fileExists: (path: string) => boolean;
+  listDir: (path: string) => string[];
+  /** `node_modules/.bin/<bin>` or a PATH entry; `null` when not runnable. */
+  lookPath: (cwd: string, bin: string) => string | null;
+}
+interface RunTaskInput extends RunDeps {
+  /** Registry task name, e.g. `"test"`. */
+  task: string;
+  /**
+   * Sub-job within the task, e.g. `"performance"` in `holocron run audit
+   * performance`. Ignored (folded into `passthrough`) for tasks with no `jobs`.
+   */
+  job?: string;
+  /** Directory to run in. */
+  cwd: string;
+  /** Args after `--` on the command line, forwarded to the tool / turbo / script. */
+  passthrough?: string[];
+  /** Print the resolved command without running it. */
+  dryRun?: boolean;
+  /** Turn "no such task for this repo" (normally exit 0) into a failure. */
+  required?: boolean;
+  /** `turbo --filter=<pkg>` passthrough (monorepo). Ignored when the repo has no `turbo.json`. */
+  filter?: string;
+}
+interface RunTaskReport {
+  status: "ok" | "fail" | "skip" | "dry-run" | "unknown";
+  /** Resolved command, for the caller / tests. */
+  command?: string;
+  message?: string;
+}
+declare function runTask(input: RunTaskInput): RunTaskReport;
+//#endregion
+//#region src/tasks/ci.d.ts
+interface CiOptions {
+  /** Print the plan without running anything. */
+  dryRun?: boolean;
+  /** `turbo --filter=<pkg>` passthrough (monorepo). */
+  filter?: string;
+  /** `"required"` (default) or `"all"` (every `ci: true` task). */
+  scope?: "required" | "all";
+}
+interface CiJobReport {
+  task: string;
+  /** The branch-protection check context, or `null` for a non-gating task. */
+  checkContext: string | null;
+  status: "ok" | "fail" | "skip" | "dry-run";
+  command?: string;
+  message?: string;
+}
+interface CiReport {
+  status: "ok" | "fail";
+  jobs: CiJobReport[];
+}
+interface CiInput extends RunDeps, CiOptions {
+  cwd: string;
+  config: TasksConfig;
+}
+declare function runCi(input: CiInput): CiReport;
+//#endregion
+//#region src/tasks/group.d.ts
+interface GroupOptions {
+  /** Print the resolved commands without running anything. */
+  dryRun?: boolean;
+  /** `turbo --filter=<pkg>` passthrough (monorepo). */
+  filter?: string;
+}
+interface GroupJobReport {
+  task: string;
+  status: "ok" | "fail" | "skip" | "dry-run";
+  command?: string;
+  message?: string;
+}
+interface GroupReport {
+  /** `"unknown"` when the namespace matches zero configured tasks. */
+  status: "ok" | "fail" | "dry-run" | "unknown";
+  jobs: GroupJobReport[];
+}
+interface GroupInput extends RunDeps, GroupOptions {
+  cwd: string;
+  config: TasksConfig;
+  /** The bare namespace, e.g. `"sourceQuality"` — matched against `"sourceQuality."`-prefixed task names. */
+  namespace: string;
+}
+/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
+declare function matchNamespace(config: TasksConfig, namespace: string): string[];
+declare function runGroup(input: GroupInput): GroupReport;
 //#endregion
 //#region src/astromech.d.ts
 interface AstromechOptions {
@@ -272,8 +304,15 @@ interface RunOptions {
   filter?: string;
 }
 interface Astromech {
-  /** Run one task — or one of its sub-jobs (`opts.job`) — locally. */
-  run(task: string, opts?: RunOptions): RunTaskReport;
+  /**
+   * Run one task — or one of its sub-jobs (`opts.job`) — locally. When
+   * `task` isn't an exact registry task but matches the prefix of one or
+   * more configured tasks (`"sourceQuality"` against `sourceQuality.*`),
+   * runs every matching task in sequence instead ({@link GroupReport}) —
+   * `opts.job` is ignored for a namespace match, since a job belongs to
+   * one task, not a namespace.
+   */
+  run(task: string, opts?: RunOptions): RunTaskReport | GroupReport;
   /**
    * Run the merge-gating checks locally, in CI order — "will CI pass?".
    * Default scope: `required: true` tasks (falls back to every `ci: true`
@@ -288,7 +327,7 @@ interface Astromech {
    */
   thinCallers(): Map<string, string>;
   /**
-   * The complete reusable-workflow batch `holocron sync-github` pushes to
+   * The complete reusable-workflow batch `holocron sync github` pushes to
    * `theholocron/.github` — repo-relative path → content, "do not edit" header
    * already applied to the YAML. Config-independent (the same for every repo).
    */
@@ -301,10 +340,19 @@ interface Astromech {
    * when there is no config or `syncScripts: false`.
    */
   packageScripts(): Record<string, string>;
+  /**
+   * Task names this repo's manifest can actually run locally — the same
+   * filter {@link packageScripts} applies (skips `local: false` and tasks
+   * with no local runner at all), but independent of `syncScripts`: a repo
+   * that opts out of generated `package.json` scripts still has real
+   * runnable tasks. Empty when there is no config. Backs `holocron`'s own
+   * interactive task picker (`run` with no task given).
+   */
+  runnableTasks(): string[];
   /**
    * The branch-protection required-status-check contexts for this repo —
    * every `required: true` task's check context plus `extraRequiredChecks`,
-   * ordered and de-duplicated. `holocron setup` prepends `"DCO"` and applies
+   * ordered and de-duplicated. `holocron repo setup` prepends `"DCO"` and applies
    * the list; this method is policy-free (manifest only).
    */
   requiredChecks(): string[];
@@ -312,7 +360,7 @@ interface Astromech {
    * This repo's `codecov.yml` — component `paths` derived from `packages/*`.
    * Pass the current file's content (`null` if none exists yet) to either
    * merge the component list in or scaffold a fresh file. Policy-free same
-   * as {@link requiredChecks} — `holocron setup` owns writing the result.
+   * as {@link requiredChecks} — `holocron repo setup` owns writing the result.
    */
   codecovConfig(existing: string | null): string;
   /**
@@ -328,27 +376,41 @@ interface Astromech {
    * (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.
+   * already) and root `package.json`'s own `scripts` object — values and
+   * all, not just keys, so a task-name-matching script that's already the
+   * generated `holocron run <task> --` wrapper (predating this call, not
+   * written by it) is correctly excluded rather than treated as proof root
+   * is directly buildable (#846). `changed: false` means don't write
+   * anything — the file is already correct.
+   */
+  ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: Readonly<Record<string, 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.
    */
-  ensureRootWorkspaceMember(workspaceYaml: string, rootScripts: readonly string[]): EnsureRootWorkspaceMemberResult;
+  ensureTurboDependency(packageJson: string, workspaceYaml: string): EnsureTurboDependencyResult;
 }
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
-//#region src/codecov.d.ts
+//#region src/generators/codecov.d.ts
 /**
  * `codecov.yml` generation — a manifest-derived artifact (component `paths`
  * come from workspace packages; the status targets track the `test` task's
  * coverage setup), the same category as the reusable `test.yml` this package
  * also generates. Moved out of `@theholocron/cli` (theholocron/holocron#650)
- * — `holocron setup`'s codecov step now calls {@link codecovConfig} instead
+ * — `holocron repo setup`'s codecov step now calls {@link codecovConfig} instead
  * of importing this logic directly.
  */
 interface WorkspacePackage {
   slug: string;
   name: string;
   /** Which workspace root the package was discovered under. Defaults to `"packages"`. */
-  dir?: "packages" | "apps";
+  dir?: "packages" | "apps" | "plugins";
 }
 declare function codecovComponentBlock(packages: WorkspacePackage[]): string;
 /**
@@ -364,97 +426,127 @@ declare function codecovComponentBlock(packages: WorkspacePackage[]): string;
 declare function ensureIfNotFound(yaml: string): string;
 declare function mergeCodecovComponents(existing: string, packages: WorkspacePackage[]): string;
 /**
- * Every public `packages/*` and `apps/*` workspace, sorted by slug. `[]`
- * when neither directory exists. Monorepo templates (Next.js, React, …)
- * ship user-facing code under `apps/` alongside library code under
- * `packages/` — both need a codecov component so `codecov/patch/<slug>`
- * actually posts for each.
+ * Every public `packages/*`, `apps/*`, and `plugins/*` workspace, sorted by
+ * slug. `[]` when none of the three directories exist. Monorepo templates
+ * (Next.js, React, …) ship user-facing code under `apps/` alongside library
+ * code under `packages/`; `holocron` itself splits vendor plugin packages
+ * into their own `plugins/*` root — every recognized root needs a codecov
+ * component so `codecov/patch/<slug>` actually posts for each.
  */
 declare function readWorkspacePackages(repoRoot: string): WorkspacePackage[];
 /** A brand-new `codecov.yml` — the scaffold header + the base template + this repo's component list. */
 declare function createCodecovConfig(packages: WorkspacePackage[]): string;
 /**
- * The full pipeline `holocron setup` needs: read this repo's public
+ * The full pipeline `holocron repo setup` needs: read this repo's public
  * `packages/*`, then either merge them into an `existing` `codecov.yml` or
  * scaffold a new one.
  */
 declare function codecovConfig(repoRoot: string, existing: string | null): string;
 //#endregion
-//#region src/linters.d.ts
+//#region src/generators/github-action-reusable-workflows.d.ts
 /**
- * The linter registry — one list of linter names (from `config.tasks`'
- * `{ name: "lint", linters: [...] }`, or auto-detected) maps to both the
- * CI super-linter `VALIDATE_*` env and the native local run. This table is
- * the single source of truth for that mapping; {@link superLinterConfig}
- * (CI) and the `holocron run lint` aggregate (local) both read it.
+ * The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
+ * `holocron sync github` — the `workflow_call` implementations and composite
+ * actions that every repo's thin callers delegate to.
+ *
+ * `theholocron/.github` is a **pure sync target**: `.github/workflows/*`,
+ * `.github/actions/*` and `workflow-templates/*` there are generated from the
+ * `.yml` files in `src/templates/reusable/` and pushed verbatim (with a
+ * "do not edit" header). Never hand-edit them in `.github`.
  *
- * Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` "Lint parity".
+ * Not to be confused with `WORKFLOW_TEMPLATES` in `github-action-thin-callers.ts` — those are
+ * the *thin-caller bases* written into each consumer repo's `.github/workflows/`.
  */
-interface LinterDef {
-  /**
-   * super-linter `VALIDATE_*` keys this linter turns on. Setting any
-   * `VALIDATE_*` puts super-linter in allow-list mode, so emitting only the
-   * enabled keys makes it run exactly this set.
-   */
-  validate: string[];
-  /** super-linter `FIX_*` keys (auto-commit / `--write` parity). */
-  fix?: string[];
-  /**
-   * Local binary, resolved from `node_modules/.bin` then `PATH`. Absent →
-   * the linter has no meaningful local run (`holocron run lint` prints
-   * "CI only"); CI still enforces it.
-   */
-  localBin?: string;
-  /** Args for `localBin` in CHECK mode — never `--write` / `--fix`. */
-  localArgs?: string[];
+/** `workflow_call` implementations → `.github/workflows/<name>.yml`. */
+declare const REUSABLE_WORKFLOWS: Record<string, string>;
+/** Composite actions → `.github/actions/<name>/action.yml` (key includes `/action`). */
+declare const REUSABLE_ACTIONS: Record<string, string>;
+/** GitHub starter-workflow metadata → `workflow-templates/<name>.properties.json`. */
+declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
+/**
+ * The complete file batch `holocron sync github` pushes to `theholocron/.github`:
+ * path → content. YAML gets the "do not edit" header; the starter-workflow
+ * `.properties.json` files are left bare (native JSON, not a commented file).
+ */
+declare function reusableTemplates(): Map<string, string>;
+//#endregion
+//#region src/generators/required-checks.d.ts
+/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
+declare function requiredChecks(config: TasksConfig): string[];
+//#endregion
+//#region src/generators/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 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.
+ */
+interface TsconfigOptions {
+  /** Human-readable name for the `display` field — the package's own name is the usual choice. */
+  display: string;
   /**
-   * Shown by `holocron run lint` when `localBin` is set but not found on
-   * PATH — the "you're missing a tool the repo needs" nudge.
+   * `@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.
    */
-  installHint?: string;
+  variant?: "astro" | "nextjs" | "node-lts" | "react";
   /**
-   * Repo-root filenames that auto-enable this linter when the `lint` task
-   * has no explicit `linters` list. Ignored when {@link always} is set.
+   * Add a `@/*` → `./src/*` path alias. A real per-package choice, not a
+   * default — roughly 40% of packages checked use one, the rest don't.
    */
-  detect?: string[];
-  /** Enabled regardless of detection (the org baseline). */
-  always?: boolean;
-  /** Reusable-workflow config-file input this linter honors, if any. */
-  configInput?: "eslint-config" | "prettier-config" | "yaml-config";
+  paths?: boolean;
 }
 /**
- * Known linters, in execution order. `always` entries are the current
- * hard-coded super-linter baseline; `prettier` is always-on because the org
- * applies it universally (super-linter only lints files that exist).
- */
-declare const LINTERS: Record<string, LinterDef>;
-/** Every linter name the registry knows. */
-declare const LINTER_NAMES: ReadonlySet<string>;
-/**
- * Resolve the linter set for a repo. An `explicit` list (from `config.tasks`)
- * picks the candidate set; otherwise the candidates are every `always` linter
- * plus every `detect`-gated linter whose filenames are present at the repo
- * root. Either way, a `detect`-gated linter (eslint, markdownlint) only makes
- * the final set when its config file is actually present — a repo can't run
- * eslint without an `eslint.config.*`, and super-linter FATALs if you ask it
- * to (theholocron/holocron#654). `always` linters are unconditional. Result
- * is ordered by {@link LINTERS} declaration order.
- *
- * @throws when an `explicit` name is not in the registry — a typo is a
- * config bug, not a linter to silently skip.
+ * 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 resolveLinters(opts: {
-  explicit?: string[];
-  rootFiles: string[];
-}): Array<{
-  name: string;
-  def: LinterDef;
-}>;
+declare function createTsconfig(options: TsconfigOptions): string;
 //#endregion
 //#region src/registry.d.ts
 /**
  * The task registry — how each task runs *locally*, without GitHub
- * Actions. `holocron run <task>` and `holocron ci` resolve against this;
+ * 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
@@ -468,7 +560,7 @@ declare function resolveLinters(opts: {
  * `sourceQuality.*`, `security.*`, `delivery.*`, `platform.*`,
  * `knowledge.*`), not tool names — `eslint`/`vitest`/`tsdown`/… stay
  * internal to this file and `theholocron/configs`. See
- * `.notes/tech-vocabulary-rename.spec.md` (#675) for the full mapping and
+ * `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).
@@ -511,7 +603,7 @@ interface JobDef {
   /**
    * The CI status-check context this job reports as (e.g.
    * `platform.repoValidation / Validate registry consistency`) — every sub-job is a CI job.
-   * `holocron run <task>` and `holocron ci` label each job line with it;
+   * `holocron run <task>` and `holocron run ci` label each job line with it;
    * the task-level `… / Conclusion` context (only for tasks with several
    * jobs) lives in `WORKFLOW_CHECK_CONTEXTS`.
    */
@@ -522,7 +614,7 @@ interface TaskDef {
    * `null` — the registry has no built-in runner (CodeQL, deploys, the
    * bundle-size job). An explicit turbo task or `package.json` script still
    * runs (resolution steps 1–2); with neither, `holocron run` does nothing
-   * and `holocron ci` skips it — never a failure, even when the task is
+   * and `holocron run ci` skips it — never a failure, even when the task is
    * `required` (a CI-only check isn't a local one).
    */
   local: LocalRunner | null;
@@ -552,151 +644,58 @@ declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
 declare const KNOWN_TASKS: Set<string>;
 /**
- * The order `holocron ci` runs tasks in — cheapest / fastest signal first, so
+ * The order `holocron run ci` runs tasks in — cheapest / fastest signal first, so
  * an agent or a `pre-push` hook fails early. Tasks not listed here run last, in
  * manifest order. (The generated thin callers carry no `needs:` — cross-workflow
- * ordering lives in `theholocron/.github` — so `holocron ci` declares its own.)
+ * ordering lives in `theholocron/.github` — so `holocron run ci` declares its own.)
  */
 declare const CI_ORDER: string[];
 //#endregion
-//#region src/required-checks.d.ts
-/** 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, so this is additive
- * and safe to run unconditionally.
- *
- * `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;
+//#region src/tasks/deploy-on-release.d.ts
+interface SpawnResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
 }
-/** 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, the 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
- * `holocron sync-github` — the `workflow_call` implementations and composite
- * actions that every repo's thin callers delegate to.
- *
- * `theholocron/.github` is a **pure sync target**: `.github/workflows/*`,
- * `.github/actions/*` and `workflow-templates/*` there are generated from the
- * `.yml` files in `src/templates/reusable/` and pushed verbatim (with a
- * "do not edit" header). Never hand-edit them in `.github`.
- *
- * Not to be confused with `WORKFLOW_TEMPLATES` in `thin-callers.ts` — those are
- * the *thin-caller bases* written into each consumer repo's `.github/workflows/`.
- */
-/** `workflow_call` implementations → `.github/workflows/<name>.yml`. */
-declare const REUSABLE_WORKFLOWS: Record<string, string>;
-/** Composite actions → `.github/actions/<name>/action.yml` (key includes `/action`). */
-declare const REUSABLE_ACTIONS: Record<string, string>;
-/** GitHub starter-workflow metadata → `workflow-templates/<name>.properties.json`. */
-declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
-/**
- * The complete file batch `holocron sync-github` pushes to `theholocron/.github`:
- * path → content. YAML gets the "do not edit" header; the starter-workflow
- * `.properties.json` files are left bare (native JSON, not a commented file).
- */
-declare function reusableTemplates(): Map<string, string>;
-//#endregion
-//#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;
+type Run = (command: string, args: string[], options: Record<string, unknown>) => SpawnResult;
+interface Tree {
+  readJson: (path: string) => unknown;
+  listDirs: (path: string) => string[];
+}
+interface DeployOnReleaseOptions {
+  cwd: string;
+  /** The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release. */
+  channel: string;
+  /** The previous release's commit; omitted when there is none, so every deploying channel match deploys. */
+  from?: string;
+  /** The release commit. Default `HEAD`. */
+  to?: string;
+  /** Where progress lines go (stdout in the CLI). */
+  print: (line: string) => void;
+  dryRun?: boolean;
+}
+interface DeployOnReleaseDeps extends Partial<Tree> {
+  run?: Run;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** Reads a package folder's task manifest; `loadTasksConfig` by default. */
+  loadTasks?: (dir: string) => Promise<TasksConfig>;
+}
+interface DeployOnReleaseResult {
+  pkg: string;
+  status: "ok" | "fail" | "skip" | "dry-run";
+  message: string;
+}
+interface DeployOnReleaseReport {
+  /** `fail` if any package's deploy failed; `skip` if none applied to this release; else `ok`. */
+  status: "ok" | "fail" | "skip";
+  results: DeployOnReleaseResult[];
 }
 /**
- * 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).
+ * Deploys every package whose manifest declares a release-time deploy that
+ * applies to this release. Never throws for a deploy problem: each package's
+ * outcome is in the report, and `status: "fail"` is the caller's exit code.
  */
-declare function createTsconfig(options: TsconfigOptions): string;
+declare function deployOnRelease(options: DeployOnReleaseOptions, { run, readJson, listDirs, sleep, now, loadTasks }?: DeployOnReleaseDeps): Promise<DeployOnReleaseReport>;
 //#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 };
+export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type DeployOnReleaseOptions, type DeployOnReleaseReport, type DeployOnReleaseResult, type ExecFn, type GroupJobReport, type GroupOptions, type GroupReport, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, 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, deployOnRelease, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, matchNamespace, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, reusableTemplates, runCi, runGroup, runTask };