@orkestrel/scaffold 0.0.4 → 0.0.6

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

@@ -144,7 +144,7 @@ export declare interface ArtifactBase {
  *
  * @returns A fresh `ContractShape` describing one planned file.
  */
-export declare function artifactShape(): UnionShape<[ ObjectShape<{
+export declare function artifactShape(): UnionShape<readonly [ ObjectShape<{
     path: StringShape;
     group: LiteralShape<readonly Group[]>;
     origin: LiteralShape<readonly ["host"]>;
@@ -305,7 +305,7 @@ export declare function blueprintToMembers(spec: Blueprint): readonly Member[];
 /**
  * The full pure compilation: draft a blueprint's artifacts — the manifest and
  * exports combination rules over the per-environment `SRC_MATRIX` rows, plus
- * `HOST_PATHS` and `overrides` — then pin.
+ * the `selectHostPaths` selection of `HOST_PATHS` and `overrides` — then pin.
  *
  * @param blueprint - The `Blueprint` to compile.
  * @param groups - An optional `Group[]` selection (default: all groups).
@@ -644,7 +644,7 @@ export declare function contentToHex(content: string): string;
 export declare const CONTROL_CHARACTER_PATTERN: RegExp;
 
 /**
- * `configs/src/tsconfig.core.json` — unchanged core shape.
+ * `configs/src/tsconfig.core.json` — host-neutral core with web interop declarations.
  *
  * @returns The core environment `tsconfig` file content, newline-terminated.
  *
@@ -659,6 +659,7 @@ export declare function coreTsconfig(): string;
  * `configs/src/vite.core.config.ts` — inlines its own `build.lib` /
  * `rolldownOptions` (core's `srcCore` root export carries no build.lib).
  *
+ * @param browser - Whether a declared browser environment enables the shared CSS pipeline.
  * @returns The core environment `vite.config.ts` file content, newline-terminated.
  *
  * @example
@@ -666,7 +667,7 @@ export declare function coreTsconfig(): string;
  * coreViteConfig().includes('srcCore(') // true
  * ```
  */
-export declare function coreViteConfig(): string;
+export declare function coreViteConfig(browser?: boolean): string;
 
 /**
  * Validate and return a `Blueprint` from plain data.
@@ -1041,12 +1042,15 @@ export declare function coreViteConfig(): string;
 
  /**
   * Draft the `guides` group's artifacts — the package's own filled guide stub,
-  * the guides index, and any vendored dependency guide mirrors.
+  * the guides index, and vendored dependency guide mirrors whose paths are
+  * neither the package's own guide nor already carried by the selected host
+  * set.
   *
   * @param spec - The `Blueprint` to derive guide artifacts from.
   * @param pascal - The package's PascalCase entity name.
   * @param members - The blueprint's derived `Member[]`.
-  * @returns The `guides` group's `Artifact[]`.
+  * @returns The `guides` group's `Artifact[]`, with one contributor per guide
+  * path.
   *
   * @example
   * ```ts
@@ -1183,9 +1187,12 @@ export declare function coreViteConfig(): string;
   * 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 mirrors every repo carries: the line-wide
-  * dev-tooling guide (`guides/src/guide.md`) and the
-  * scaffold engine's own self-guide (`guides/src/scaffold.md`).
+  * 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/scaffold.md`). `stageHost` vendors both; each plan carries the
+  * subset selected by `selectHostPaths`, omitting the target blueprint's own
+  * guide.
   */
  export declare const HOST_PATHS: readonly string[];
 
@@ -1392,6 +1399,24 @@ export declare function coreViteConfig(): string;
   */
  export declare function manifestToDependencies(manifestText: string): readonly Dependency[];
 
+ /**
+  * Project a `package.json` text to its own string `name`.
+  *
+  * @param manifest - The `package.json` file content.
+  * @returns The own string `name`, or `undefined` when the manifest exceeds its
+  * byte ceiling, is malformed, has a non-object root, or has no own string
+  * `name`.
+  *
+  * @example
+  * ```ts
+  * import { manifestToName } from '@orkestrel/scaffold'
+  *
+  * manifestToName('{"name":"@orkestrel/router"}') // '@orkestrel/router'
+  * manifestToName('{}') // undefined
+  * ```
+  */
+ export declare function manifestToName(manifest: string): string | undefined;
+
  /** Maximum byte size accepted for one scaffold artifact. */
  export declare const MAX_ARTIFACT_BYTES = 5242880;
 
@@ -1492,12 +1517,13 @@ export declare function coreViteConfig(): string;
  export declare const ORKESTREL_RANGE_PATTERN: RegExp;
 
  /**
-  * One caller template override.
+  * One artifact override.
   *
   * @remarks
   * `content` REPLACES the rendered artifact at `path`, never partially merges.
-  * An override whose `path` matches no planned artifact, or targets a
-  * `host`-origin path, is a BLOCKING question — never a silent add.
+  * An override whose `path` matches no planned artifact, targets a
+  * `host`-origin path, or targets `package.json` is a BLOCKING question.
+  * Accepted overrides surface as retained non-blocking advisories.
   */
  export declare interface Override {
      readonly path: string;
@@ -1930,7 +1956,7 @@ export declare function coreViteConfig(): string;
          engine: BooleanShape;
      }, false>;
      groups: ArrayShape<LiteralShape<readonly Group[]>>;
-     artifacts: ArrayShape<UnionShape<[ ObjectShape<{
+     artifacts: ArrayShape<UnionShape<readonly [ ObjectShape<{
          path: StringShape;
          group: LiteralShape<readonly Group[]>;
          origin: LiteralShape<readonly ["host"]>;
@@ -2131,7 +2157,7 @@ export declare function coreViteConfig(): string;
  export declare function rootViteConfig(src: readonly Environment[], engine?: boolean): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.4";
+ export declare const SCAFFOLD_RANGE = "^0.0.6";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2174,6 +2200,20 @@ export declare function coreViteConfig(): string;
      readonly digest: string;
  }
 
+ /**
+  * Select host paths without the guide owned by the target blueprint.
+  *
+  * @param paths - Host artifact paths in deterministic input order.
+  * @param name - The target blueprint's unscoped package name.
+  * @returns Every host path except `guides/src/<name>.md`, in input order.
+  *
+  * @example
+  * ```ts
+  * selectHostPaths(['guides/src/guide.md', 'LICENSE'], 'guide') // ['LICENSE']
+  * ```
+  */
+ export declare function selectHostPaths(paths: readonly string[], name: string): readonly string[];
+
  /**
   * Serialize text as a single-quoted TypeScript string literal.
   *
@@ -2570,22 +2610,66 @@ export declare function coreViteConfig(): string;
 
  /**
   * The rendered import / `resolve` header block every `rootViteConfig` shape
-  * prefixes — the official Playwright provider import appears only when
-  * `needsPlaywright`, per the three grounded `rootViteConfig`
-  * shapes: unconditional for a multi-environment blueprint, conditional on the
-  * sole environment being `'browser'` for a single non-`core` environment, absent for
-  * `core`-only.
-  *
-  * @param needsPlaywright - Whether this shape ships a browser test project (and so needs Playwright).
-  * @param needsVue - Whether the generated root imports the Vue Vite plugin.
+  * prefixes — the environment boundary and every guarantee it enforces ship
+  * unconditionally; `machinery` selects only the host-specific pipelines layered
+  * over them, per the three grounded `rootViteConfig` shapes: browser machinery
+  * unconditional for a multi-environment blueprint carrying `browser`,
+  * conditional on the sole environment being `'browser'` for a single non-`core`
+  * environment, absent for `core`-only.
+  *
+  * @param machinery - The host-specific machinery this shape carries, from `viteMachinery`.
   * @returns The rendered header block, newline-terminated.
   *
   * @example
   * ```ts
-  * viteHeader(false).includes('@vitest/browser-playwright') // false
-  * viteHeader(true).includes('@vitest/browser-playwright') // true
+  * viteHeader(viteMachinery(['core'])).includes('@vitest/browser-playwright') // false
+  * viteHeader(viteMachinery(['core', 'browser'])).includes('@vitest/browser-playwright') // true
+  * ```
+  */
+ export declare function viteHeader(machinery: ViteMachinery): string;
+
+ /**
+  * Which host-specific machinery a generated root `vite.config.ts` carries.
+  *
+  * @remarks
+  * The boundary GUARANTEES never vary by blueprint: every generated
+  * configuration emits the environment-boundary plugin, its module-graph AST
+  * audit, and stylesheet rejection, because those enforce owner-independent
+  * laws. Only the host-specific pipelines below are selected by the declared
+  * environments. `browser` covers everything a declared browser environment
+  * needs — the CSS pipeline and the Playwright-backed browser test project;
+  * `vue` adds the single-file-component, HTML, and development-server
+  * machinery an application browser environment needs; `output` adds build
+  * output containment, which an application of `core` alone never builds.
+  */
+ export declare interface ViteMachinery {
+     readonly browser: boolean;
+     readonly vue: boolean;
+     readonly output: boolean;
+ }
+
+ /**
+  * Derive which host-specific machinery a workspace's generated root
+  * `vite.config.ts` carries from its declared environments.
+  *
+  * @remarks
+  * This is the SOLE derivation of that set; `rootViteConfig`,
+  * `singleSrcViteConfig`, `applicationViteConfig`, and `configArtifacts` all
+  * read it rather than recomputing an axis of their own. Nothing here selects
+  * a boundary GUARANTEE — the environment-boundary plugin, its module-graph
+  * AST audit, and stylesheet rejection ship in every shape.
+  *
+  * @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.
+  * @returns The machinery set the generated header renders.
+  *
+  * @example
+  * ```ts
+  * viteMachinery(['core']) // { browser: false, vue: false, output: true }
+  * viteMachinery([], ['core']) // { browser: false, vue: false, output: false }
   * ```
   */
- export declare function viteHeader(needsPlaywright: boolean, needsVue?: boolean): string;
+ export declare function viteMachinery(src: readonly Environment[], app?: readonly Environment[], engine?: boolean): ViteMachinery;
 
  export { }

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

@@ -144,7 +144,7 @@ export declare interface ArtifactBase {
  *
  * @returns A fresh `ContractShape` describing one planned file.
  */
-export declare function artifactShape(): UnionShape<[ ObjectShape<{
+export declare function artifactShape(): UnionShape<readonly [ ObjectShape<{
     path: StringShape;
     group: LiteralShape<readonly Group[]>;
     origin: LiteralShape<readonly ["host"]>;
@@ -305,7 +305,7 @@ export declare function blueprintToMembers(spec: Blueprint): readonly Member[];
 /**
  * The full pure compilation: draft a blueprint's artifacts — the manifest and
  * exports combination rules over the per-environment `SRC_MATRIX` rows, plus
- * `HOST_PATHS` and `overrides` — then pin.
+ * the `selectHostPaths` selection of `HOST_PATHS` and `overrides` — then pin.
  *
  * @param blueprint - The `Blueprint` to compile.
  * @param groups - An optional `Group[]` selection (default: all groups).
@@ -644,7 +644,7 @@ export declare function contentToHex(content: string): string;
 export declare const CONTROL_CHARACTER_PATTERN: RegExp;
 
 /**
- * `configs/src/tsconfig.core.json` — unchanged core shape.
+ * `configs/src/tsconfig.core.json` — host-neutral core with web interop declarations.
  *
  * @returns The core environment `tsconfig` file content, newline-terminated.
  *
@@ -659,6 +659,7 @@ export declare function coreTsconfig(): string;
  * `configs/src/vite.core.config.ts` — inlines its own `build.lib` /
  * `rolldownOptions` (core's `srcCore` root export carries no build.lib).
  *
+ * @param browser - Whether a declared browser environment enables the shared CSS pipeline.
  * @returns The core environment `vite.config.ts` file content, newline-terminated.
  *
  * @example
@@ -666,7 +667,7 @@ export declare function coreTsconfig(): string;
  * coreViteConfig().includes('srcCore(') // true
  * ```
  */
-export declare function coreViteConfig(): string;
+export declare function coreViteConfig(browser?: boolean): string;
 
 /**
  * Validate and return a `Blueprint` from plain data.
@@ -1041,12 +1042,15 @@ export declare function coreViteConfig(): string;
 
  /**
   * Draft the `guides` group's artifacts — the package's own filled guide stub,
-  * the guides index, and any vendored dependency guide mirrors.
+  * the guides index, and vendored dependency guide mirrors whose paths are
+  * neither the package's own guide nor already carried by the selected host
+  * set.
   *
   * @param spec - The `Blueprint` to derive guide artifacts from.
   * @param pascal - The package's PascalCase entity name.
   * @param members - The blueprint's derived `Member[]`.
-  * @returns The `guides` group's `Artifact[]`.
+  * @returns The `guides` group's `Artifact[]`, with one contributor per guide
+  * path.
   *
   * @example
   * ```ts
@@ -1183,9 +1187,12 @@ export declare function coreViteConfig(): string;
   * 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 mirrors every repo carries: the line-wide
-  * dev-tooling guide (`guides/src/guide.md`) and the
-  * scaffold engine's own self-guide (`guides/src/scaffold.md`).
+  * 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/scaffold.md`). `stageHost` vendors both; each plan carries the
+  * subset selected by `selectHostPaths`, omitting the target blueprint's own
+  * guide.
   */
  export declare const HOST_PATHS: readonly string[];
 
@@ -1392,6 +1399,24 @@ export declare function coreViteConfig(): string;
   */
  export declare function manifestToDependencies(manifestText: string): readonly Dependency[];
 
+ /**
+  * Project a `package.json` text to its own string `name`.
+  *
+  * @param manifest - The `package.json` file content.
+  * @returns The own string `name`, or `undefined` when the manifest exceeds its
+  * byte ceiling, is malformed, has a non-object root, or has no own string
+  * `name`.
+  *
+  * @example
+  * ```ts
+  * import { manifestToName } from '@orkestrel/scaffold'
+  *
+  * manifestToName('{"name":"@orkestrel/router"}') // '@orkestrel/router'
+  * manifestToName('{}') // undefined
+  * ```
+  */
+ export declare function manifestToName(manifest: string): string | undefined;
+
  /** Maximum byte size accepted for one scaffold artifact. */
  export declare const MAX_ARTIFACT_BYTES = 5242880;
 
@@ -1492,12 +1517,13 @@ export declare function coreViteConfig(): string;
  export declare const ORKESTREL_RANGE_PATTERN: RegExp;
 
  /**
-  * One caller template override.
+  * One artifact override.
   *
   * @remarks
   * `content` REPLACES the rendered artifact at `path`, never partially merges.
-  * An override whose `path` matches no planned artifact, or targets a
-  * `host`-origin path, is a BLOCKING question — never a silent add.
+  * An override whose `path` matches no planned artifact, targets a
+  * `host`-origin path, or targets `package.json` is a BLOCKING question.
+  * Accepted overrides surface as retained non-blocking advisories.
   */
  export declare interface Override {
      readonly path: string;
@@ -1930,7 +1956,7 @@ export declare function coreViteConfig(): string;
          engine: BooleanShape;
      }, false>;
      groups: ArrayShape<LiteralShape<readonly Group[]>>;
-     artifacts: ArrayShape<UnionShape<[ ObjectShape<{
+     artifacts: ArrayShape<UnionShape<readonly [ ObjectShape<{
          path: StringShape;
          group: LiteralShape<readonly Group[]>;
          origin: LiteralShape<readonly ["host"]>;
@@ -2131,7 +2157,7 @@ export declare function coreViteConfig(): string;
  export declare function rootViteConfig(src: readonly Environment[], engine?: boolean): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.4";
+ export declare const SCAFFOLD_RANGE = "^0.0.6";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2174,6 +2200,20 @@ export declare function coreViteConfig(): string;
      readonly digest: string;
  }
 
+ /**
+  * Select host paths without the guide owned by the target blueprint.
+  *
+  * @param paths - Host artifact paths in deterministic input order.
+  * @param name - The target blueprint's unscoped package name.
+  * @returns Every host path except `guides/src/<name>.md`, in input order.
+  *
+  * @example
+  * ```ts
+  * selectHostPaths(['guides/src/guide.md', 'LICENSE'], 'guide') // ['LICENSE']
+  * ```
+  */
+ export declare function selectHostPaths(paths: readonly string[], name: string): readonly string[];
+
  /**
   * Serialize text as a single-quoted TypeScript string literal.
   *
@@ -2570,22 +2610,66 @@ export declare function coreViteConfig(): string;
 
  /**
   * The rendered import / `resolve` header block every `rootViteConfig` shape
-  * prefixes — the official Playwright provider import appears only when
-  * `needsPlaywright`, per the three grounded `rootViteConfig`
-  * shapes: unconditional for a multi-environment blueprint, conditional on the
-  * sole environment being `'browser'` for a single non-`core` environment, absent for
-  * `core`-only.
-  *
-  * @param needsPlaywright - Whether this shape ships a browser test project (and so needs Playwright).
-  * @param needsVue - Whether the generated root imports the Vue Vite plugin.
+  * prefixes — the environment boundary and every guarantee it enforces ship
+  * unconditionally; `machinery` selects only the host-specific pipelines layered
+  * over them, per the three grounded `rootViteConfig` shapes: browser machinery
+  * unconditional for a multi-environment blueprint carrying `browser`,
+  * conditional on the sole environment being `'browser'` for a single non-`core`
+  * environment, absent for `core`-only.
+  *
+  * @param machinery - The host-specific machinery this shape carries, from `viteMachinery`.
   * @returns The rendered header block, newline-terminated.
   *
   * @example
   * ```ts
-  * viteHeader(false).includes('@vitest/browser-playwright') // false
-  * viteHeader(true).includes('@vitest/browser-playwright') // true
+  * viteHeader(viteMachinery(['core'])).includes('@vitest/browser-playwright') // false
+  * viteHeader(viteMachinery(['core', 'browser'])).includes('@vitest/browser-playwright') // true
+  * ```
+  */
+ export declare function viteHeader(machinery: ViteMachinery): string;
+
+ /**
+  * Which host-specific machinery a generated root `vite.config.ts` carries.
+  *
+  * @remarks
+  * The boundary GUARANTEES never vary by blueprint: every generated
+  * configuration emits the environment-boundary plugin, its module-graph AST
+  * audit, and stylesheet rejection, because those enforce owner-independent
+  * laws. Only the host-specific pipelines below are selected by the declared
+  * environments. `browser` covers everything a declared browser environment
+  * needs — the CSS pipeline and the Playwright-backed browser test project;
+  * `vue` adds the single-file-component, HTML, and development-server
+  * machinery an application browser environment needs; `output` adds build
+  * output containment, which an application of `core` alone never builds.
+  */
+ export declare interface ViteMachinery {
+     readonly browser: boolean;
+     readonly vue: boolean;
+     readonly output: boolean;
+ }
+
+ /**
+  * Derive which host-specific machinery a workspace's generated root
+  * `vite.config.ts` carries from its declared environments.
+  *
+  * @remarks
+  * This is the SOLE derivation of that set; `rootViteConfig`,
+  * `singleSrcViteConfig`, `applicationViteConfig`, and `configArtifacts` all
+  * read it rather than recomputing an axis of their own. Nothing here selects
+  * a boundary GUARANTEE — the environment-boundary plugin, its module-graph
+  * AST audit, and stylesheet rejection ship in every shape.
+  *
+  * @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.
+  * @returns The machinery set the generated header renders.
+  *
+  * @example
+  * ```ts
+  * viteMachinery(['core']) // { browser: false, vue: false, output: true }
+  * viteMachinery([], ['core']) // { browser: false, vue: false, output: false }
   * ```
   */
- export declare function viteHeader(needsPlaywright: boolean, needsVue?: boolean): string;
+ export declare function viteMachinery(src: readonly Environment[], app?: readonly Environment[], engine?: boolean): ViteMachinery;
 
  export { }