@orkestrel/scaffold 0.0.6 → 0.0.8

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

@@ -68,7 +68,7 @@ export declare function applicationArtifacts(spec: Blueprint): readonly Artifact
  *
  * @param src - Published src environments.
  * @param app - Private app environments.
- * @param engine - Whether the workspace also builds scaffold's executable.
+ * @param axes - Optional executable, integration, and service project axes.
  * @returns The root `vite.config.ts` content.
  *
  * @example
@@ -76,7 +76,7 @@ export declare function applicationArtifacts(spec: Blueprint): readonly Artifact
  * applicationViteConfig([], ['core', 'server']).includes('appServer') // true
  * ```
  */
-export declare function applicationViteConfig(src: readonly Environment[], app: readonly Environment[], engine?: boolean): string;
+export declare function applicationViteConfig(src: readonly Environment[], app: readonly Environment[], axes?: ViteAxes): string;
 
 /**
  * Apply a blueprint's `overrides` over a drafted artifact list — an override
@@ -195,6 +195,45 @@ export declare function auditToReview(audit: Audit): string;
 /** Tooling versions shared by scaffold and every generated workspace. */
 export declare const BASE_DEV_DEPENDENCIES: Readonly<Record<string, string>>;
 
+/** The computed configuration files required by a workspace-owned executable. */
+export declare const BIN_CONFIGS: readonly string[];
+
+/**
+ * Build the executable's declaration-only `configs/src/tsconfig.bin.json`.
+ *
+ * @returns The executable `tsconfig` file content, newline-terminated.
+ *
+ * @example
+ * ```ts
+ * binTsconfig().includes('"outDir": "../../dist/bin"') // true
+ * ```
+ */
+export declare function binTsconfig(): string;
+
+/**
+ * Build the executable's `configs/src/vite.bin.config.ts` wrapper.
+ *
+ * @returns The executable Vite configuration content, newline-terminated.
+ *
+ * @example
+ * ```ts
+ * binViteConfig().includes("banner: '#!/usr/bin/env node'") // true
+ * ```
+ */
+export declare function binViteConfig(): string;
+
+/**
+ * Build the executable's dedicated Node-only build and test project.
+ *
+ * @returns The emitted `srcBin` project definition.
+ *
+ * @example
+ * ```ts
+ * binViteProject().includes("label: 'src:bin'") // true
+ * ```
+ */
+export declare function binViteProject(): string;
+
 /** The closed, JSON-serializable source/application workspace spec. */
 export declare interface Blueprint {
     readonly name: string;
@@ -212,8 +251,12 @@ export declare interface Blueprint {
     readonly version: string;
     readonly engines: string;
     readonly overrides: readonly Override[];
-    /** Structural: `true` only for a repo that ships its own `src/bin` — the self-hosting tax (a `bin` field, the `scaffold` script invoking `dist/bin/scaffold.js` directly, the `check/test/build:src:bin` scripts, `build:host`, the `srcBin` vite project) applies ONLY when `true`, never by name. */
-    readonly engine: boolean;
+    /** Structural: `true` only for a repo that ships its own `src/bin` — the self-hosting tax (the manifest's `bin` entry, the `scaffold` script invoking `dist/bin/scaffold.js` directly, the `check/test/build:src:bin` scripts, `build:host`, the `srcBin` vite project) applies ONLY when `true`, never by name. */
+    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;
 }
 
 /**
@@ -224,9 +267,9 @@ export declare interface Blueprint {
  * @remarks
  * `version` / `engines` default `DEFAULT_VERSION` / `DEFAULT_ENGINES`,
  * `src` defaults `['core']`, and `app` / `keywords` / `dependencies` /
- * `peers` / `extras` / `overrides` default `[]`. `description` is OMITTED
- * entirely when absent, so the result round-trips the exact-record
- * `Blueprint` guard.
+ * `peers` / `extras` / `overrides` default `[]`, and `bin` / `integration` /
+ * `service` default `false`. `description` is OMITTED entirely when absent, so
+ * the result round-trips the exact-record `Blueprint` guard.
  * @returns A complete `Blueprint`.
  *
  * @example
@@ -280,7 +323,9 @@ export declare function blueprintShape(): ObjectShape<{
         path: StringShape;
         content: StringShape;
     }, false>>;
-    engine: BooleanShape;
+    bin: BooleanShape;
+    integration: BooleanShape;
+    service: BooleanShape;
 }, false>;
 
 /**
@@ -405,7 +450,7 @@ export declare type Category = 'type' | 'alias' | 'constant' | 'factory' | 'enti
 export declare const CHECKOUT_ACTION_SHA = "de0fac2e4500dabe0009e67214ff5f5447ce83dd";
 
 /**
- * Build selection-aware GitHub CI without external service dependencies.
+ * Build selection-aware GitHub CI, provisioning the declared foreign service before its proof.
  *
  * @param spec - The workspace blueprint.
  * @returns The complete `.github/workflows/ci.yml` content.
@@ -806,21 +851,19 @@ export declare function coreViteConfig(browser?: boolean): string;
  }, false>;
 
  /**
-  * The host-neutral devDependency baseline every generated workspace needs.
-  * Browser providers are added only by browser selections or the scaffold
-  * engine's generated-browser consumer proof. A package's `extras` (code-unit
-  * sorted) merge in on top, the extras' declared range winning on a name
-  * collision with the baseline.
+  * The complete development dependency set one blueprint emits. The shared
+  * baseline is extended by package extras, dev-installed peers, selected
+  * browser environments, and the bin axis's browser test provider.
   *
-  * @param extras - The blueprint's package-specific `extras` `Dependency[]`.
+  * @param spec - The blueprint whose development dependencies are required.
   * @returns The merged `devDependencies` record.
   *
   * @example
   * ```ts
-  * devDependenciesFor([])['typescript'] // '^6.0.3'
+  * devDependenciesFor(blueprint('router'))['typescript'] // '^6.0.3'
   * ```
   */
- export declare function devDependenciesFor(extras: readonly Dependency[]): Readonly<Record<string, string>>;
+ export declare function devDependenciesFor(spec: Blueprint): Readonly<Record<string, string>>;
 
  /**
   * Diff a plan's artifacts against a target's current content.
@@ -1085,6 +1128,18 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function guideMethods(spec: Blueprint): string;
 
+ /**
+  * Build the standalone Node-only guide-parity Vitest project.
+  *
+  * @returns The emitted `guides` project definition.
+  *
+  * @example
+  * ```ts
+  * guidesViteProject().includes("label: 'guides'") // true
+  * ```
+  */
+ export declare function guidesViteProject(): string;
+
  /**
   * One dependency guide fetched from upstream at its `path`, plus its
   * `freshness` verdict against the local mirror.
@@ -1189,7 +1244,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * `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 engine's own self-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.
@@ -1245,6 +1300,21 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function inferGroup(path: string): Group;
 
+ /**
+  * Build the standalone Node-only installed-consumer integration proof project.
+  *
+  * @param axes - Optional executable and integration axes controlling the shared registry setup.
+  * @returns The emitted `integration` project definition.
+  *
+  * @example
+  * ```ts
+  * integrationViteProject({ bin: true, integration: true }).includes(
+  *   "globalSetup: ['./tests/setupIntegration.ts']",
+  * ) // true
+  * ```
+  */
+ export declare function integrationViteProject(axes?: ViteAxes): string;
+
  /** Visible characters forbidden by portable paths and Markdown path cells. */
  export declare const INVALID_PATH_CHARACTER_PATTERN: RegExp;
 
@@ -1953,7 +2023,9 @@ export declare function coreViteConfig(browser?: boolean): string;
              path: StringShape;
              content: StringShape;
          }, false>>;
-         engine: BooleanShape;
+         bin: BooleanShape;
+         integration: BooleanShape;
+         service: BooleanShape;
      }, false>;
      groups: ArrayShape<LiteralShape<readonly Group[]>>;
      artifacts: ArrayShape<UnionShape<readonly [ ObjectShape<{
@@ -2016,7 +2088,16 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function planToSummary(plan: Plan): PlanSummary;
 
- /** Build the dedicated Node-only repository policy Vitest project. */
+ /**
+  * Build the dedicated standalone Node-only repository-policy Vitest project.
+  *
+  * @returns The emitted `policy` project definition.
+  *
+  * @example
+  * ```ts
+  * policyViteProject().includes("label: 'policy'") // true
+  * ```
+  */
  export declare function policyViteProject(): string;
 
  /**
@@ -2110,6 +2191,22 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function renderValue(entry: unknown, indent: string, prefix: string, suffix: string): string;
 
+ /**
+  * Render the root Vitest project registration, preserving browser ownership
+  * supplied by the caller.
+  *
+  * @param registrations - Ordered project factory identifiers with optional browser labels.
+  * @param browser - Whether the generated configuration carries browser machinery.
+  * @returns The rendered root `test` property.
+  *
+  * @example
+  * ```ts
+  * renderViteTest([{ project: 'srcCore' }], false)
+  * // '\ttest: {\n\t\tprojects: [srcCore],\n\t},'
+  * ```
+  */
+ export declare function renderViteTest(registrations: readonly ViteProjectRegistration[], browser: boolean): string;
+
  /**
   * The root `tsconfig.json` — one `@src/<environment>` path alias per declared
   * environment, in declared order.
@@ -2128,7 +2225,8 @@ export declare function coreViteConfig(browser?: boolean): string;
  /**
   * The root `vite.config.ts` — three grounded shapes, chosen by a blueprint's
   * `src`:
-  *   1. `core`-only — `srcCore` + `guides`, no Playwright at all (the live
+  *   1. `core`-only — `srcCore` + standalone policy/guides proof projects, no
+  *      Playwright at all (the live
   *      timeout exemplar: no browser project exists anywhere in the file).
   *   2. Multi-environment (2+ src, always including `core` per the live
   *      middleware/router exemplars) — `srcCore` is the shared base;
@@ -2143,10 +2241,9 @@ export declare function coreViteConfig(browser?: boolean): string;
   *      environment is `browser` (it must run its own tests in a real browser).
   *
   * @param src - The declared `Environment[]`.
-  * @param engine - Structural: `true` appends the `srcBin` project (an
-  *   executable build target, never a barrel) after the other declared
-  *   projects — the self-hosting tax, grounded against this very repo's own
-  *   checked-in `vite.config.ts`.
+  * @param axes - Optional structural project axes. `bin` appends the standalone
+  *   executable build-and-test project; `integration` and `service` append their
+  *   standalone proof projects.
   * @returns The root `vite.config.ts` file content, newline-terminated.
   *
   * @example
@@ -2154,10 +2251,10 @@ export declare function coreViteConfig(browser?: boolean): string;
   * rootViteConfig(['core']).includes('srcCore') // true
   * ```
   */
- export declare function rootViteConfig(src: readonly Environment[], engine?: boolean): string;
+ export declare function rootViteConfig(src: readonly Environment[], axes?: ViteAxes): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.6";
+ export declare const SCAFFOLD_RANGE = "^0.0.8";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2229,6 +2326,21 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function serializeTypeScriptString(value: string): string;
 
+ /** The consumer-owned live-service provisioner expected only by service workspaces. */
+ export declare const SERVICE_SCRIPT_PATH = "scripts/service.sh";
+
+ /**
+  * Build the standalone Node-only live-service proof project.
+  *
+  * @returns The emitted `service` project definition.
+  *
+  * @example
+  * ```ts
+  * serviceViteProject().includes("label: 'service'") // true
+  * ```
+  */
+ export declare function serviceViteProject(): string;
+
  /** Immutable official actions/setup-node v6.4.0 commit used by generated CI. */
  export declare const SETUP_NODE_ACTION_SHA = "48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e";
 
@@ -2236,9 +2348,12 @@ export declare function coreViteConfig(browser?: boolean): string;
   * The single non-`core` environment's factory IS the base (Shape 3 of
   * `rootViteConfig`) — the environment's own `viteHeader` (Playwright only when
   * `environment === 'browser'`, per the live sqlite/indexeddb exemplars) prefixes
-  * the environment-specific `srcBrowser` / `srcServer` + `guides` projects export.
+  * the environment-specific `srcBrowser` / `srcServer` project, followed by the
+  * standalone policy and guides proof projects and any selected structural-axis
+  * projects.
   *
   * @param environment - The sole declared non-`core` environment.
+  * @param axes - Optional executable, integration, and service project axes.
   * @returns The root `vite.config.ts` file content for a single non-`core` environment, newline-terminated.
   *
   * @example
@@ -2246,7 +2361,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * singleSrcViteConfig('server').includes('srcServer') // true
   * ```
   */
- export declare function singleSrcViteConfig(environment: 'browser' | 'server'): string;
+ export declare function singleSrcViteConfig(environment: 'browser' | 'server', axes?: ViteAxes): string;
 
  /** Exact lowercase hexadecimal target bytes keyed by artifact-relative path. */
  export declare type Snapshot = Readonly<Record<string, string>>;
@@ -2608,6 +2723,13 @@ export declare function coreViteConfig(browser?: boolean): string;
      readonly note?: string;
  }
 
+ /** Optional structural projects appended to a generated root Vite configuration. */
+ export declare interface ViteAxes {
+     readonly bin?: boolean;
+     readonly integration?: boolean;
+     readonly service?: boolean;
+ }
+
  /**
   * The rendered import / `resolve` header block every `rootViteConfig` shape
   * prefixes — the environment boundary and every guarantee it enforces ship
@@ -2661,7 +2783,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   *
   * @param src - The declared published `Environment[]`.
   * @param app - The declared application `Environment[]`, defaulting to none.
-  * @param engine - Whether the workspace also builds its own executable.
+  * @param bin - Whether the workspace also builds its own executable.
   * @returns The machinery set the generated header renders.
   *
   * @example
@@ -2670,6 +2792,42 @@ export declare function coreViteConfig(browser?: boolean): string;
   * viteMachinery([], ['core']) // { browser: false, vue: false, output: false }
   * ```
   */
- export declare function viteMachinery(src: readonly Environment[], app?: readonly Environment[], engine?: boolean): ViteMachinery;
+ export declare function viteMachinery(src: readonly Environment[], app?: readonly Environment[], bin?: boolean): ViteMachinery;
+
+ /**
+  * Render the one ordered proof and structural-axis project definition block.
+  *
+  * @param axes - Optional executable, integration, and service project axes.
+  * @returns Policy, guides, then selected axis project definitions, separated by one blank line.
+  *
+  * @example
+  * ```ts
+  * viteProjectDefinitions({ bin: true }).includes('export const srcBin =') // true
+  * ```
+  */
+ export declare function viteProjectDefinitions(axes?: ViteAxes): string;
+
+ /** One generated Vitest project factory and its optional browser-project label. */
+ export declare interface ViteProjectRegistration {
+     readonly project: string;
+     readonly browser?: string;
+ }
+
+ /**
+  * Derive the one ordered Vitest project registration list shared by every
+  * generated root configuration shape.
+  *
+  * @param src - The declared published environments.
+  * @param app - The declared application environments.
+  * @param axes - Optional executable, integration, and service project axes.
+  * @returns Source projects, application projects, proof projects, then optional axis projects.
+  *
+  * @example
+  * ```ts
+  * viteProjectRegistrations(['core'], [], { integration: true })
+  * // [{ project: 'srcCore' }, { project: 'policy' }, { project: 'guides' }, { project: 'integration' }]
+  * ```
+  */
+ export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], axes?: ViteAxes): readonly ViteProjectRegistration[];
 
  export { }