@orkestrel/scaffold 0.0.20 → 0.0.22

package/dist/src/core/index.d.cts

@@ -41,12 +41,18 @@ export declare function alignTable(header: readonly string[], rows: readonly (re
 /** Additional development dependencies required by a private Vue browser application. */
 export declare const APP_BROWSER_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
 
+/** Baseline development dependency required by every private application environment. */
+export declare const APP_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
+
 /**
  * The per-environment application matrix: thin config artifacts, Vitest project
  * label, and executable entry where the environment produces a runtime bundle.
  */
 export declare const APP_MATRIX: Readonly<Record<Environment, AppDefinition>>;
 
+/** Additional development dependencies required by a private server application. */
+export declare const APP_SERVER_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
+
 /** The deterministic config, test-project, and runtime-entry settings for one application environment. */
 export declare interface AppDefinition {
     readonly configs: readonly string[];
@@ -58,9 +64,16 @@ export declare interface AppDefinition {
  * Draft the application source artifacts for every selected app environment.
  *
  * @param spec - The blueprint carrying the application environment set.
+ * @remarks
+ * Two conditional shapes layer over the per-environment set. The health contract —
+ * record, route constants, guard, and the one unknown-to-typed read — is declared by
+ * `app/server` while the server alone reads it and RELOCATES to `app/core` the moment
+ * the browser reads it too, because a contract two hosts share belongs to neither of
+ * them. The showcase entry pair, its seeder, and its factory appear only for a
+ * blueprint that declares the physical showcase wrapper alongside `app/browser`.
  * @returns Complete, runnable app/core, app/browser, and app/server artifacts.
  */
-export declare function applicationArtifacts(spec: Blueprint): readonly Artifact[];
+export declare function applicationArtifacts(spec: Pick<Blueprint, 'name' | 'app' | 'showcase'>): readonly Artifact[];
 
 /**
  * Build the root Vite/Vitest configuration for a workspace that includes
@@ -164,8 +177,8 @@ export declare function artifactShape(): UnionShape<readonly [ ObjectShape<{
  *
  * @remarks
  * A `Compiler.audit` over a gate-failing blueprint sets `complete: false` with
- * the gate's `questions` and zero findings, while `diffPlan` over an existing
- * plan is always `complete: true`.
+ * the gate's `questions` and zero findings. `diffPlan` over an existing plan
+ * is always complete; a host artifact without `hex` is presence-owned.
  */
 export declare interface Audit {
     readonly findings: readonly Finding[];
@@ -255,8 +268,8 @@ export declare interface Blueprint {
     readonly bin: boolean;
     /** Structural: `true` only for a repo that ships `tests/integration` — a slow, opt-in proof project over the repo's own built output, outside the default run, never by name. */
     readonly integration: boolean;
-    /** Structural: `true` only for a repo that ships `tests/service` — a slow, opt-in proof project against a foreign running process, outside the default run, never by name. Derivation requires `tests/setupService.ts` and `scripts/service.sh` beside it and fails `TARGET` otherwise. */
-    readonly service: boolean;
+    /** Structural vendor names derived from non-empty `tests/service/<name>` directories, sorted in code-unit order. Each vendor owns `tests/service/<name>/setup.ts`; the workspace owns `scripts/service.sh`. */
+    readonly services: readonly string[];
     /** Structural: `true` only for a repo that carries the physical, exact-case `tests/setupGlobal.ts` module — integration and `srcBrowser` projects consume that shared global setup only under their own additional structural conditions. */
     readonly global: boolean;
     /** Structural: `true` only for a repo that carries the physical, exact-case `configs/app/vite.showcase.config.ts` regular file; valid only with `app/browser`. */
@@ -271,8 +284,8 @@ export declare interface Blueprint {
  * @remarks
  * `version` / `engines` default `DEFAULT_VERSION` / `DEFAULT_ENGINES`,
  * `src` defaults `['core']`, and `app` / `keywords` / `dependencies` /
- * `peers` / `extras` / `overrides` default `[]`, and `bin` / `integration` /
- * `service` / `global` / `showcase` default `false`. `description` is OMITTED entirely
+ * `peers` / `extras` / `overrides` / `services` default `[]`, and `bin` /
+ * `integration` / `global` / `showcase` default `false`. `description` is OMITTED entirely
  * when absent, so the result round-trips the exact-record `Blueprint` guard.
  * @returns A complete `Blueprint`.
  *
@@ -329,7 +342,7 @@ export declare function blueprintShape(): ObjectShape<{
     }, false>>;
     bin: BooleanShape;
     integration: BooleanShape;
-    service: BooleanShape;
+    services: ArrayShape<StringShape>;
     global: BooleanShape;
     showcase: BooleanShape;
 }, false>;
@@ -341,7 +354,11 @@ export declare function blueprintShape(): ObjectShape<{
  * @remarks
  * Published source environments receive the canonical entity/type/factory/constant
  * inventory. Application environments receive their exact public declaration kinds,
- * including parsers, guards, handlers, errors, and runners where present.
+ * including parsers, guards, handlers, errors, and runners where present. Two groups
+ * move rather than duplicate: the health contract is declared against `app/server`
+ * while the server alone reads it and against `app/core` once the browser reads it
+ * too, and the showcase seed, factory, and root-view identity appear only for a
+ * blueprint whose showcase accompanies `app/browser`.
  * @returns The declared `Member[]`, one set per environment.
  *
  * @example
@@ -381,6 +398,17 @@ export declare type BuildFormat = 'es' | 'cjs';
  */
 export declare function bytesToHex(bytes: Uint8Array): string;
 
+/**
+ * The catalog agent file whose bounded marker region the catalog operation alone owns.
+ *
+ * @remarks
+ * Vendored like every other host artifact, but presence-owned after hydration:
+ * `diffPlan` compares this one path by presence, so a consumer restores it while
+ * absent and never replaces its bytes — not from an audit, not from a repair, and
+ * not under `replace`.
+ */
+export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
+
 /**
  * One fleet package's catalog row — the `orkestrel` agent's package-catalog
  * section, derived rather than hand-maintained.
@@ -422,7 +450,7 @@ export declare function catalogNames(text: string): readonly string[];
 
 /**
  * Project a fleet package catalog into a markdown table — the block
- * `.claude/agents/orkestrel.md`'s catalog markers wrap.
+ * `CATALOG_AGENT_PATH`'s catalog markers wrap.
  *
  * @param entries - The catalog rows to render.
  * @remarks
@@ -647,6 +675,18 @@ export declare function computeHash(text: string): string;
  */
 export declare function configArtifacts(spec: Blueprint): readonly Artifact[];
 
+/**
+ * Build the standalone Node-only root-configuration Vitest project.
+ *
+ * @returns The emitted `config` project definition.
+ *
+ * @example
+ * ```ts
+ * configViteProject().includes("label: 'config'") // true
+ * ```
+ */
+export declare function configViteProject(): string;
+
 /** Constant-declaration token kept out of template literals consumed by parity scans. */
 export declare const CONST_KEYWORD = "const";
 
@@ -876,13 +916,14 @@ export declare function coreViteConfig(): string;
   * @param plan - The plan whose artifacts are the source of truth.
   * @param current - The target's current content, keyed by artifact-relative path.
   * @remarks
-  * Audit semantics are per-origin. A `host`-origin artifact is audited by
-  * PRESENCE only — `missing` or `aligned`, never `stale` — UNLESS it has been
-  * hydrated with its real host bytes (`hydratePlan`'s `content`), in which case
-  * it is content-compared exactly like a `computed` artifact and CAN be
-  * `stale`. `hydratePlan` expands directory-shaped host artifacts into
-  * content-bearing file artifacts; only an unresolved degrade-path host
-  * artifact stays presence-only. A `computed` artifact is content-aware canon —
+  * Audit semantics are per-origin. A `host`-origin artifact with canonical
+  * `hex` is content-compared exactly like a `computed` artifact and CAN be
+  * `stale`. A host artifact without canonical bytes is presence-owned:
+  * present is `aligned`, absent is `missing`. `CATALOG_AGENT_PATH` remains
+  * presence-owned after hydration because the catalog operation alone owns its
+  * bounded marker region. `hydratePlan` expands directory-shaped host artifacts
+  * into byte-aware file artifacts; only an intentional dependency-guide pointer
+  * may remain without `hex`. A `computed` artifact is content-aware canon —
   * `missing` / `aligned` / `stale` — and gates the audit like any drifted
   * finding. A `template`-origin artifact is BIRTH-ONLY and AUDIT-EXEMPT: it is
   * always reported `aligned`, regardless of whether the target has it at all
@@ -1202,6 +1243,32 @@ export declare function coreViteConfig(): string;
   */
  export declare function guideUsage(spec: Blueprint, pascal: string): string;
 
+ /**
+  * Determine whether an application blueprint spans the shared browser/server boundary.
+  *
+  * @param spec - The blueprint to inspect.
+  * @returns True only when app/core, app/browser, and app/server are all selected.
+  *
+  * @example
+  * ```ts
+  * hasApplicationBoundary(blueprint('application', { app: ['core', 'browser', 'server'] }))
+  * ```
+  */
+ export declare function hasApplicationBoundary(spec: Pick<Blueprint, 'app'>): boolean;
+
+ /**
+  * Determine whether an application blueprint emits its browser showcase.
+  *
+  * @param spec - The blueprint to inspect.
+  * @returns True only when showcase intent accompanies app/browser.
+  *
+  * @example
+  * ```ts
+  * hasApplicationShowcase(blueprint('application', { app: ['browser'], showcase: true }))
+  * ```
+  */
+ export declare function hasApplicationShowcase(spec: Pick<Blueprint, 'app' | 'showcase'>): boolean;
+
  /**
   * Whether a structurally valid blueprint selects at least one source or app environment.
   *
@@ -1262,15 +1329,23 @@ export declare function coreViteConfig(): string;
   * The byte-copied host artifact paths, frozen.
   *
   * @remarks
-  * The root docs (`AGENTS.md` / `CLAUDE.md`), `LICENSE`, `.agents`, `.claude`, `.codex`,
-  * the four SessionStart hook scripts (`scripts/deps.sh` / `scripts/cursor.sh` /
-  * `scripts/codex.sh` / `scripts/ollama.sh`), the repository coding-law policy module,
-  * the line's seven byte-identical root dotfiles, and the two guides-grouped
-  * mirror candidates: the line-wide dev-tooling guide
-  * (`guides/src/guide.md`) and the scaffold bin's own self-guide
-  * (`guides/src/scaffold.md`). `stageHost` vendors both; each plan carries the
-  * subset selected by `selectHostPaths`, omitting the target blueprint's own
-  * guide.
+  * The root docs (`AGENTS.md` / `CLAUDE.md`), `LICENSE`, the canonical
+  * orchestration contract (`.agents/orchestration.md`) every harness bridge
+  * points at, `.agents`, `.claude`, `.codex`, `.cursor`, the four SessionStart
+  * hook scripts (`scripts/deps.sh` / `scripts/cursor.sh` / `scripts/codex.sh` /
+  * `scripts/ollama.sh`), the repository coding-law policy module, the line's
+  * seven byte-identical root dotfiles, and the two guides-grouped mirror
+  * candidates: the line-wide dev-tooling guide (`guides/src/guide.md`) and the
+  * scaffold bin's own self-guide (`guides/src/scaffold.md`). `stageHost` vendors
+  * both; each plan carries the subset selected by `selectHostPaths`, omitting the
+  * target blueprint's own guide.
+  *
+  * Three harness bridges point at `.agents/orchestration.md` and carry only their
+  * own harness's specifics: `CLAUDE.md`, `.codex/config.toml`, and
+  * `.cursor/rules`. They are meaningless without the contract they reference, but
+  * they do not share a `Group` — `hostGroup` keeps `CLAUDE.md` in `docs` with the
+  * other root documents, so a plan selecting `orchestration` carries two of the
+  * three and a plan selecting `docs` carries the third.
   */
  export declare const HOST_PATHS: readonly string[];
 
@@ -1292,10 +1367,26 @@ export declare function coreViteConfig(): string;
   * @example
   * ```ts
   * hostGroup('AGENTS.md') // 'docs'
-  * hostGroup('.agents') // 'orchestration'
-  * hostGroup('.claude') // 'orchestration'
-  * hostGroup('.codex') // 'orchestration'
+  * hostGroup('.agents/orchestration.md') // 'orchestration'
+  * hostGroup('.claude/rules') // 'orchestration'
+  * hostGroup('.cursor/rules') // 'orchestration'
+  * hostGroup('.mcp.json') // 'orchestration'
+  * hostGroup('.oxlintrc.json') // 'configs'
   * ```
+  *
+  * @remarks
+  * Takes a `HOST_PATHS` entry, so every example above is one. A bare directory
+  * name is not: `ORCHESTRATION_PATH_PREFIXES` entries carry a trailing slash, so
+  * `hostGroup('.cursor')` is `configs`, and no vendored entry has that form.
+  *
+  * Below the `docs` branch the split is by what a path governs rather than where
+  * it sits, which is why both MCP registrations — `.mcp.json` and
+  * `.cursor/mcp.json` — group with the harness bridges instead of with the root
+  * dotfiles beside them. The `docs` branch is checked first and is deliberately
+  * positional: `AGENTS.md`, `CLAUDE.md`, and `LICENSE` are the root documents, and
+  * `CLAUDE.md` stays there as a root document even though it is also a harness
+  * bridge. A plan selecting `orchestration` therefore carries two of the three
+  * bridges; a plan selecting `docs` carries the third.
   */
  export declare function hostGroup(path: string): Group;
 
@@ -1307,10 +1398,12 @@ export declare function coreViteConfig(): string;
   *
   * @param path - The target-relative path to classify.
   * @remarks
-  * Ordered prefix match — `src/`, `tests/`, `guides/`, `docs/`, `configs/`,
-  * then `.agents/`, `.claude/`, `.codex/`, `.github/`, and `scripts/` as
-  * `'orchestration'`, then the two manifest files by exact name. Anything else
-  * (a root-level, prefix-less file) falls through to `'configs'`.
+  * Ordered prefix match — `src/`, `tests/`, `guides/`, `docs/`, `configs/`, then
+  * `matchesOrchestrationPath`, which owns the orchestration membership rule for
+  * this function and for `hostGroup` alike, then the two manifest files by exact
+  * name. Anything left falls through to `'configs'`. Read the rule at
+  * `matchesOrchestrationPath` rather than here; one rule with two descriptions
+  * drifts exactly as fast as one rule with two implementations.
   * @returns The inferred `Group` for `path`.
   *
   * @example
@@ -1510,6 +1603,23 @@ export declare function coreViteConfig(): string;
   */
  export declare function manifestToName(manifest: string): string | undefined;
 
+ /**
+  * Test whether a path instructs or wires an agent rather than the toolchain.
+  *
+  * @param path - The portable path to classify.
+  * @returns `true` when the path is agent orchestration.
+  *
+  * @example
+  * ```ts
+  * import { matchesOrchestrationPath } from '@orkestrel/scaffold'
+  *
+  * matchesOrchestrationPath('.cursor/rules/orchestration.mdc') // true
+  * matchesOrchestrationPath('.mcp.json') // true
+  * matchesOrchestrationPath('.oxlintrc.json') // false
+  * ```
+  */
+ export declare function matchesOrchestrationPath(path: string): boolean;
+
  /** Maximum byte size accepted for one scaffold artifact. */
  export declare const MAX_ARTIFACT_BYTES = 5242880;
 
@@ -1595,6 +1705,27 @@ export declare function coreViteConfig(): string;
  /** The package-name RegExp — lowercase alphanumeric-with-hyphens, letter-first. */
  export declare const NAME_PATTERN: RegExp;
 
+ /**
+  * The exact root filenames that wire an agent bench rather than the toolchain, frozen.
+  *
+  * @remarks
+  * `.mcp.json` registers MCP servers for the harness. It sits among the root
+  * dotfiles but governs agents, so it groups with the harness bridges.
+  */
+ export declare const ORCHESTRATION_PATH_NAMES: readonly string[];
+
+ /**
+  * The path prefixes whose contents instruct or wire an agent, frozen.
+  *
+  * @remarks
+  * Group classification splits by what a path governs, not by where it sits:
+  * anything under these prefixes is `orchestration`, and everything else that is
+  * not source, tests, guides, docs, or a manifest is `configs`. Both classifiers
+  * — `inferGroup` for a foreign target path and `hostGroup` for a `HOST_PATHS`
+  * entry — read this one list, so a new harness directory is admitted once.
+  */
+ export declare const ORCHESTRATION_PATH_PREFIXES: readonly string[];
+
  /**
   * How an `Artifact`'s content is produced: `host` byte-copied from the vendored
   * data root, `template` filled from a frozen `TemplateDefinition` by
@@ -2048,7 +2179,7 @@ export declare function coreViteConfig(): string;
          }, false>>;
          bin: BooleanShape;
          integration: BooleanShape;
-         service: BooleanShape;
+         services: ArrayShape<StringShape>;
          global: BooleanShape;
          showcase: BooleanShape;
      }, false>;
@@ -2196,6 +2327,28 @@ export declare function coreViteConfig(): string;
   */
  export declare function renderObject(entry: Readonly<Record<string, unknown>>, indent: string): string;
 
+ /**
+  * Render a single-quoted TypeScript string array literal through `oxfmt`'s
+  * inline-or-broken rule — inline when the rendered width fits
+  * `JSON_PRINT_WIDTH`, one item per line with a trailing comma on every line
+  * (including the last) otherwise, matching `.oxfmtrc.json`'s
+  * `trailingComma: "all"` for non-JSON files.
+  *
+  * @param entries - The array's string elements, in order.
+  * @param indent - The current indentation prefix.
+  * @param prefix - The text already emitted on this line before the array.
+  * @param suffix - The text that will follow the array on this line.
+  * @returns The rendered array fragment (no trailing newline).
+  *
+  * @example
+  * ```ts
+  * import { renderStringArray } from '@orkestrel/scaffold'
+  *
+  * renderStringArray(['app', 'guides', 'tests'], '', '', '') // "['app', 'guides', 'tests']"
+  * ```
+  */
+ export declare function renderStringArray(entries: readonly string[], indent: string, prefix: string, suffix: string): string;
+
  /**
   * Render one JSON value through `formatJson`'s dispatch — arrays via
   * `renderArray`, objects via `renderObject`, everything else via
@@ -2267,7 +2420,7 @@ export declare function coreViteConfig(): string;
   *
   * @param src - The declared `Environment[]`.
   * @param facts - Optional structural facts. `bin` appends the standalone executable
-  *   build-and-test project; `integration` and `service` append their standalone
+  *   build-and-test project; `integration` and `services` append their standalone
   *   proof projects; `global` wires the shared global-setup module.
   * @returns The root `vite.config.ts` file content, newline-terminated.
   *
@@ -2279,7 +2432,7 @@ export declare function coreViteConfig(): string;
  export declare function rootViteConfig(src: readonly Environment[], facts?: ViteFacts): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.20";
+ export declare const SCAFFOLD_RANGE = "^0.0.22";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2351,20 +2504,21 @@ export declare function coreViteConfig(): string;
   */
  export declare function serializeTypeScriptString(value: string): string;
 
- /** The consumer-owned live-service provisioner expected only by service workspaces. */
+ /** The birth-only provisioner skeleton retained by workspaces with declared service vendors. */
  export declare const SERVICE_SCRIPT_PATH = "scripts/service.sh";
 
  /**
-  * Build the standalone Node-only live-service proof project.
+  * Build one standalone Node-only live-service vendor proof project.
   *
-  * @returns The emitted `service` project definition.
+  * @param name - The bounded vendor directory name.
+  * @returns The emitted `service:<name>` project definition.
   *
   * @example
   * ```ts
-  * serviceViteProject().includes("label: 'service'") // true
+  * serviceViteProject('claude').includes("label: 'service:claude'") // true
   * ```
   */
- export declare function serviceViteProject(): string;
+ export declare function serviceViteProject(name: string): string;
 
  /** Immutable official actions/setup-node v6.4.0 commit used by generated CI. */
  export declare const SETUP_NODE_ACTION_SHA = "48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e";
@@ -2431,7 +2585,7 @@ export declare function coreViteConfig(): string;
   * factory per environment (AGENTS §5's per-environment centralized-file pattern), so
   * every environment gets the same uniform stub shape.
   *
-  * @param spec - The `Blueprint` to derive source stubs from.
+  * @param spec - The blueprint carrying the declared source environment set.
   * @param pascal - The package's PascalCase entity name.
   * @returns The `source` group's `Artifact[]`.
   *
@@ -2440,7 +2594,7 @@ export declare function coreViteConfig(): string;
   * sourceArtifacts(blueprint('router'), 'Router').length // 4
   * ```
   */
- export declare function sourceArtifacts(spec: Blueprint, pascal: string): readonly Artifact[];
+ export declare function sourceArtifacts(spec: Pick<Blueprint, 'src'>, pascal: string): readonly Artifact[];
 
  /**
   * Split one rendered GFM table row into its trimmed cell strings.
@@ -2755,7 +2909,8 @@ export declare function coreViteConfig(): string;
   * Optional structural facts consumed by a generated root Vite configuration.
   *
   * @remarks
-  * `bin`, `integration`, and `service` select their matching projects.
+  * `bin` and `integration` select their matching projects. `services` is the
+  * sorted list of vendor projects derived from `tests/service/<name>` directories.
   * `global` records the physical `tests/setupGlobal.ts` module and wires it
   * into every selected project that consumes that shared setup. `showcase`
   * records the physical app showcase wrapper and selects its browser machinery.
@@ -2763,7 +2918,7 @@ export declare function coreViteConfig(): string;
  export declare interface ViteFacts {
      readonly bin?: boolean;
      readonly integration?: boolean;
-     readonly service?: boolean;
+     readonly services?: readonly string[];
      readonly global?: boolean;
      readonly showcase?: boolean;
  }
@@ -2841,7 +2996,7 @@ export declare function coreViteConfig(): string;
   * Render the one ordered proof and structural-axis project definition block.
   *
   * @param facts - Optional structural facts.
-  * @returns Policy, guides, then selected axis project definitions, separated by one blank line.
+  * @returns Policy, config, guides, then selected axis project definitions, separated by one blank line.
   *
   * @example
   * ```ts
@@ -2868,7 +3023,7 @@ export declare function coreViteConfig(): string;
   * @example
   * ```ts
   * viteProjectRegistrations(['core'], [], { integration: true })
-  * // [{ project: 'srcCore' }, { project: 'policy' }, { project: 'guides' }, { project: 'integration' }]
+  * // [{ project: 'srcCore' }, { project: 'policy' }, { project: 'config' }, { project: 'guides' }, { project: 'integration' }]
   * ```
   */
  export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], facts?: ViteFacts): readonly ViteProjectRegistration[];