@theholocron/astromech 5.0.0-alpha.11 → 5.0.0-alpha.111

package/README.md

@@ -33,7 +33,7 @@ const report = astromech.run("verification.unitTests", { passthrough: ["--watch"
 `holocron run verification.unitTests` runs your tests — you don't tell it
 turbo vs pnpm vs npm, or which runner:
 
-```
+```text
 1. turbo.json defines the task            → turbo run <task>
 2. package.json has a <task> script       → <detected pm> run <task>
    (a "holocron run …" thin caller is skipped — no recursion)
@@ -53,28 +53,28 @@ what it actually runs, and why. Tool names never appear in
 `holocron.config.ts` — they're an implementation detail this table
 documents, not a naming convention repos need to follow.
 
-| Task                                     | Runs                                                                                               | Notes                                                                                                    |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `verification.unitTests`                 | vitest                                                                                             | carries the `--coverage` org default                                                                     |
-| `verification.typeSafety`                | tsc                                                                                                | `tsc --noEmit`                                                                                           |
-| `verification.performance`               | Lighthouse CI                                                                                      | only runs with a `lighthouse.config.*` present                                                           |
-| `sourceQuality.staticAnalysis`           | eslint, actionlint, git-merge-conflict-markers                                                     | a `linterGroup` — see below                                                                              |
-| `sourceQuality.formatting`               | prettier, editorconfig-checker, markdownlint-cli2                                                  | a `linterGroup`                                                                                          |
-| `sourceQuality.structuredDataValidation` | yamllint                                                                                           |                                                                                                          |
-| `sourceQuality.deadCodeAnalysis`         | knip                                                                                               |                                                                                                          |
-| `security.secretDetection`               | gitleaks                                                                                           |                                                                                                          |
-| `security.codeScanning`                  | CodeQL                                                                                             | no local equivalent — CI only                                                                            |
-| `security.dependencyReview`              | GitHub's native Dependabot alerts/graph                                                            | a capability-model method (`Source.enableVulnerabilityAlerts()`), not a task                             |
-| `delivery.build`                         | tsdown / vite / rollup / tsc, detected from the repo's own config file                             |                                                                                                          |
-| `delivery.publish`                       | semantic-release                                                                                   | no local equivalent — CI only; carries `preview` (npm dist-tags)                                         |
-| `delivery.deploy`                        | Cloudflare Pages / Vercel                                                                          | no local equivalent — CI only; carries `preview`                                                         |
-| `delivery.bundleSize`                    | bundle-size upload to Codecov                                                                      | no local equivalent — CI only                                                                            |
-| `platform.repoSync`                      | `holocron sync`                                                                                    | keeps generated files current                                                                            |
-| `platform.commitStandards`               | commitlint                                                                                         | no local equivalent — enforced by the `commit-msg` hook locally, over the PR's commit range in CI        |
-| `platform.repoValidation`                | `scripts/validate-adrs.mjs`, `scripts/validate-registry.mjs`, `scripts/validate-docs-presence.mjs` | a job-bearing task — spec/ADR frontmatter, registry-doc completeness, and docs-presence, not linters     |
-| `knowledge.wiki`                         | Fern                                                                                               | publishes `docs/wiki/*.md` — not a sync, a publish; carries `preview`                                    |
-| `knowledge.docs`                         | Astro build                                                                                        | the docs site itself; carries `preview` (defaults on)                                                    |
-| `knowledge.components`                   | Storybook build                                                                                    | a browsable component catalog — "Storybook" is the tool, not the intent; carries `preview` (defaults on) |
+| Task                                     | Runs                                                                                                                                                             | Notes                                                                                                    |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `verification.unitTests`                 | vitest                                                                                                                                                           | carries the `--coverage` org default                                                                     |
+| `verification.typeSafety`                | tsc                                                                                                                                                              | `tsc --noEmit`                                                                                           |
+| `verification.performance`               | Lighthouse CI                                                                                                                                                    | only runs with a `lighthouse.config.*` present                                                           |
+| `sourceQuality.staticAnalysis`           | eslint, actionlint, git-merge-conflict-markers                                                                                                                   | a `linterGroup` — see below                                                                              |
+| `sourceQuality.formatting`               | prettier, editorconfig-checker, markdownlint-cli2                                                                                                                | a `linterGroup`                                                                                          |
+| `sourceQuality.structuredDataValidation` | yamllint                                                                                                                                                         |                                                                                                          |
+| `sourceQuality.deadCodeAnalysis`         | knip                                                                                                                                                             |                                                                                                          |
+| `security.secretDetection`               | gitleaks                                                                                                                                                         |                                                                                                          |
+| `security.codeScanning`                  | CodeQL                                                                                                                                                           | no local equivalent — CI only                                                                            |
+| `security.dependencyReview`              | GitHub's native Dependabot alerts/graph                                                                                                                          | a capability-model method (`Source.enableVulnerabilityAlerts()`), not a task                             |
+| `delivery.build`                         | tsdown / vite / rollup / tsc, detected from the repo's own config file, or `package.json`'s own `dependencies`/`devDependencies` if that config file isn't there |                                                                                                          |
+| `delivery.publish`                       | semantic-release                                                                                                                                                 | no local equivalent — CI only; carries `preview` (npm dist-tags)                                         |
+| `delivery.deploy`                        | Cloudflare Pages / Vercel                                                                                                                                        | no local equivalent — CI only; carries `preview`                                                         |
+| `delivery.bundleSize`                    | bundle-size upload to Codecov                                                                                                                                    | no local equivalent — CI only                                                                            |
+| `platform.repoSync`                      | `holocron sync`                                                                                                                                                  | keeps generated files current                                                                            |
+| `platform.commitStandards`               | commitlint                                                                                                                                                       | no local equivalent — enforced by the `commit-msg` hook locally, over the PR's commit range in CI        |
+| `platform.repoValidation`                | `scripts/validate-adrs.mjs`, `scripts/validate-registry.mjs`, `scripts/validate-docs-presence.mjs`                                                               | a job-bearing task — spec/ADR frontmatter, registry-doc completeness, and docs-presence, not linters     |
+| `knowledge.wiki`                         | Fern                                                                                                                                                             | publishes `docs/wiki/*.md` — not a sync, a publish; carries `preview`                                    |
+| `knowledge.docs`                         | Astro build                                                                                                                                                      | the docs site itself; carries `preview` (defaults on)                                                    |
+| `knowledge.components`                   | Storybook build                                                                                                                                                  | a browsable component catalog — "Storybook" is the tool, not the intent; carries `preview` (defaults on) |
 
 **`preview` is a cross-cutting feature, not a namespace.** npm has staging
 dist-tags, Cloudflare/Vercel do per-PR preview deploys, Fern previews
@@ -83,10 +83,12 @@ publish/deploy-shaped task can carry, toggled via that task's `with:`.
 
 **`linterGroup` tasks** (`sourceQuality.staticAnalysis`,
 `sourceQuality.formatting`) bundle more than one tool under a single
-required check. Each tool is still gated by its own detection rule (e.g.
-`eslint` only runs if `eslint.config.*` is present) — the
+required check. Each tool is still gated by its own detection rule — e.g.
+`eslint` runs when either a local `eslint.config.*` is present, or the
+package has no local file but `@theholocron/eslint-config` resolves
+(the same shared-config splice the `tool`/`detect` runner path uses) — the
 `tool name → detection rule → local binary` mapping lives in one place,
-`src/linters.ts`. A repo's choice of which of these run is just which
+`src/linters.ts`. A repo's choice of which of these run is based on which
 tasks it includes in `tasks: [...]`, same as any other task.
 
 **No super-linter.** Each task above runs its own tool directly, through
@@ -116,6 +118,9 @@ export default defineConfig({
 `loadTasksConfig(cwd)` resolves the manifest: the `tasks` key of
 `holocron.config.*` (a bare item array), then a dedicated
 `astromech.config.*` merged on top (dedicated wins; arrays concatenate).
+`mergeTasksLayers(parentTasks, dedicated)` is that merge step on its own,
+for callers that load the two sources some other way (Sentinel reads them
+through the GitHub API).
 
 | `TaskEntry` field        | Effect                                                      |
 | ------------------------ | ----------------------------------------------------------- |
@@ -187,6 +192,27 @@ template. `holocron setup` writes the result via the `source` capability;
 this method never touches the filesystem beyond reading `packages/*` and
 `apps/*` under `cwd`.
 
+## Release-time deploys — `deployOnRelease`
+
+Deploys the workspace packages whose manifest declares it (holocron#930):
+
+```ts
+// packages/<app>/holocron.config.ts
+tasks: [{ name: "delivery.deploy", with: { on: "release", channel: "alpha" } }];
+```
+
+`holocron deploy-on-release --channel=<alpha|main> --from=<previous release commit> --to=<release commit>`
+(or `deployOnRelease()` from `@theholocron/astromech`) deploys each such package
+when the release is on its `channel` (default `main`, the stable release;
+set `alpha` for prereleases) and changes the package or one of its `workspace:*` dependencies
+(`with.paths` overrides that), once npm serves the release's new dependency
+versions, by running `pnpm --filter <package> delivery.deploy`. A package
+that doesn't apply to the release is skipped; a deploy that fails exits
+non-zero. The shared `delivery.publish` workflow runs it as a separate `deploy`
+job after the release job (opt in with `deploy-on-release: true`), so a deploy
+is its own re-runnable check. A `delivery.deploy` task with `on: "release"`
+generates no workflow.
+
 ## Development
 
 | Script                                  | Description                                 |

package/dist/config/index.d.mts

@@ -14,6 +14,13 @@ import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskCon
 declare const defineConfig: <C extends TasksConfig>(config: C) => C;
 //#endregion
 //#region src/config/load.d.ts
+/**
+ * The `tasks` value in each source. A dedicated `astromech.config.*`
+ * default-exports the full {@link TasksConfig} object; the `tasks` key of
+ * `holocron.config.*` is the bare item array (it mirrors the old
+ * `workflows` key). Either form is accepted from either source.
+ */
+type TasksInput = TasksConfig | TaskConfigItem[];
 /**
  * Resolve the task manifest for a repo: the `tasks` key of
  * `holocron.config.*`, then a dedicated `astromech.config.*` merged on
@@ -21,5 +28,13 @@ declare const defineConfig: <C extends TasksConfig>(config: C) => C;
  * neither source is present.
  */
 declare function loadTasksConfig(cwd: string): Promise<TasksConfig>;
+/**
+ * The merge step of {@link loadTasksConfig}, for callers that load the two
+ * sources some other way (Sentinel reads them from the GitHub API, not
+ * from disk, holocron#916): `holocron.config.*`'s `tasks` value first,
+ * then a dedicated `astromech.config.*`'s default export merged on top.
+ * Either may be `undefined` (source absent); returns `{}` when both are.
+ */
+declare function mergeTasksLayers(parentTasks: TasksInput | undefined, dedicated: TasksInput | undefined): TasksConfig;
 //#endregion
-export { type TaskConfigItem, type TaskEntry, type TasksConfig, defineConfig, loadTasksConfig, normalizeTaskEntry };
+export { type TaskConfigItem, type TaskEntry, type TasksConfig, defineConfig, loadTasksConfig, mergeTasksLayers, normalizeTaskEntry };

package/dist/config/index.mjs

@@ -1,5 +1,5 @@
-import { t as normalizeTaskEntry } from "../schema-Cf5dfaDO.mjs";
-import { createDefineConfig, loadConfigFile, mergeConfig } from "@theholocron/datapad";
+import { n as mergeTasksLayers, r as normalizeTaskEntry, t as loadTasksConfig } from "../load-XHHfD9TX.mjs";
+import { createDefineConfig } from "@theholocron/datapad";
 //#region src/config/define.ts
 /**
 * Typed identity helper for `astromech.config.ts`:
@@ -14,26 +14,4 @@ import { createDefineConfig, loadConfigFile, mergeConfig } from "@theholocron/da
 */
 const defineConfig = createDefineConfig();
 //#endregion
-//#region src/config/load.ts
-/**
-* Resolve the task manifest for a repo: the `tasks` key of
-* `holocron.config.*`, then a dedicated `astromech.config.*` merged on
-* top (dedicated wins; item arrays concatenate). Returns `{}` when
-* neither source is present.
-*/
-async function loadTasksConfig(cwd) {
-	const dedicated = await loadConfigFile({
-		cwd,
-		name: "astromech"
-	});
-	return [coerce((await loadConfigFile({
-		cwd,
-		name: "holocron"
-	}))?.config.tasks), coerce(dedicated?.config)].filter((layer) => layer !== void 0).reduce((acc, layer) => mergeConfig(acc, layer), {});
-}
-function coerce(value) {
-	if (value == null) return void 0;
-	return Array.isArray(value) ? { tasks: value } : value;
-}
-//#endregion
-export { defineConfig, loadTasksConfig, normalizeTaskEntry };
+export { defineConfig, loadTasksConfig, mergeTasksLayers, normalizeTaskEntry };

package/dist/index.d.mts

@@ -226,6 +226,10 @@ interface EnsureRootWorkspaceMemberResult {
   content: string;
   changed: boolean;
 }
+interface EnsureTurboDependencyResult {
+  content: string;
+  changed: boolean;
+}
 //#endregion
 //#region src/astromech.d.ts
 interface AstromechOptions {
@@ -328,10 +332,24 @@ 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
@@ -380,6 +398,53 @@ declare function createCodecovConfig(packages: WorkspacePackage[]): string;
  */
 declare function codecovConfig(repoRoot: string, existing: string | null): string;
 //#endregion
+//#region src/deploy-on-release.d.ts
+interface SpawnResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+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[];
+}
+/**
+ * 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 deployOnRelease(options: DeployOnReleaseOptions, { run, readJson, listDirs, sleep, now, loadTasks }?: DeployOnReleaseDeps): Promise<DeployOnReleaseReport>;
+//#endregion
 //#region src/linters.d.ts
 /**
  * The linter registry — one list of linter names (from `config.tasks`'
@@ -434,11 +499,20 @@ 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.
+ * root, OR whose mapped `@theholocron/*-config` package resolves per
+ * {@link sharedConfigAvailable} — a repo can't run eslint with genuinely no
+ * config anywhere (super-linter FATALs if you ask it to,
+ * theholocron/holocron#654), but a *shared* one it has installed counts
+ * (holocron#795: proving `clients`' eslint.config.ts files reduce to zero
+ * remaining content is only half the story — the file itself was still load-
+ * bearing here as the sole "eslint is even configured" signal until this
+ * fallback existed). `always` linters are unconditional. Result is ordered
+ * by {@link LINTERS} declaration order.
+ *
+ * `sharedConfigAvailable` is caller-computed (`run.ts`'s `runLinterGroup`
+ * already resolves each linter's `resolveToolConfig()` per member to build
+ * its actual command — reusing that instead of duplicating the package-
+ * resolution logic here keeps this function itself pure and file-I/O-free).
  *
  * @throws when an `explicit` name is not in the registry — a typo is a
  * config bug, not a linter to silently skip.
@@ -446,6 +520,7 @@ declare const LINTER_NAMES: ReadonlySet<string>;
 declare function resolveLinters(opts: {
   explicit?: string[];
   rootFiles: string[];
+  sharedConfigAvailable?: ReadonlySet<string>;
 }): Array<{
   name: string;
   def: LinterDef;
@@ -577,8 +652,18 @@ declare function requiredChecks(config: TasksConfig): string[];
  * 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.
+ * 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
@@ -596,10 +681,12 @@ interface ResolverDeps {
 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).
+ * `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
@@ -699,4 +786,4 @@ interface TsconfigOptions {
  */
 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 };
+export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type DeployOnReleaseOptions, type DeployOnReleaseReport, type DeployOnReleaseResult, 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, deployOnRelease, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, resolveLinters, resolveToolConfig, reusableTemplates, runCi, runTask };