@orkestrel/scaffold 0.0.9 → 0.0.11

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

@@ -68,7 +68,7 @@ export declare function applicationArtifacts(spec: Blueprint): readonly Artifact
  *
  * @param src - Published src environments.
  * @param app - Private app environments.
- * @param axes - Optional executable, integration, and service project axes.
+ * @param facts - Optional structural facts.
  * @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[], axes?: ViteAxes): string;
+export declare function applicationViteConfig(src: readonly Environment[], app: readonly Environment[], facts?: ViteFacts): string;
 
 /**
  * Apply a blueprint's `overrides` over a drafted artifact list — an override
@@ -257,6 +257,8 @@ export declare interface Blueprint {
     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: `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;
 }
 
 /**
@@ -268,8 +270,8 @@ export declare interface Blueprint {
  * `version` / `engines` default `DEFAULT_VERSION` / `DEFAULT_ENGINES`,
  * `src` defaults `['core']`, and `app` / `keywords` / `dependencies` /
  * `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.
+ * `service` / `global` default `false`. `description` is OMITTED entirely
+ * when absent, so the result round-trips the exact-record `Blueprint` guard.
  * @returns A complete `Blueprint`.
  *
  * @example
@@ -326,6 +328,7 @@ export declare function blueprintShape(): ObjectShape<{
     bin: BooleanShape;
     integration: BooleanShape;
     service: BooleanShape;
+    global: BooleanShape;
 }, false>;
 
 /**
@@ -1038,6 +1041,21 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function findPathConflict(paths: readonly string[]): readonly [existing: string, duplicate: string] | undefined;
 
+ /**
+  * Test whether a complete rendered line fits the fleet formatter's print width.
+  *
+  * @param text - The complete rendered line, including indentation and trailing punctuation.
+  * @returns Whether the line fits within `JSON_PRINT_WIDTH`.
+  *
+  * @example
+  * ```ts
+  * import { fitsPrintWidth } from '@orkestrel/scaffold'
+  *
+  * fitsPrintWidth('\t["ESNext"],') // true
+  * ```
+  */
+ export declare function fitsPrintWidth(text: string): boolean;
+
  /**
   * Serialize a value to newline-terminated JSON that matches the fleet's own
   * `oxfmt` output byte-for-byte — objects one key per line, arrays collapsed
@@ -1077,6 +1095,9 @@ export declare function coreViteConfig(browser?: boolean): string;
  /** Function-declaration token kept out of template literals consumed by parity scans. */
  export declare const FUNCTION_KEYWORD = "function";
 
+ /** The consumer-owned Vitest global-setup module shared by its independently selected projects. */
+ export declare const GLOBAL_SETUP_PATH = "tests/setupGlobal.ts";
+
  /** The closed artifact-group vocabulary a plan selects over. */
  export declare type Group = 'manifest' | 'configs' | 'source' | 'tests' | 'guides' | 'docs' | 'orchestration';
 
@@ -1303,17 +1324,17 @@ export declare function coreViteConfig(browser?: boolean): string;
  /**
   * Build the standalone Node-only installed-consumer integration proof project.
   *
-  * @param axes - Optional executable and integration axes controlling the shared registry setup.
+  * @param facts - Optional structural facts controlling the shared global setup.
   * @returns The emitted `integration` project definition.
   *
   * @example
   * ```ts
-  * integrationViteProject({ bin: true, integration: true }).includes(
-  *   "globalSetup: ['./tests/setupIntegration.ts']",
+  * integrationViteProject({ bin: true, integration: true, global: true }).includes(
+  *   "globalSetup: ['./tests/setupGlobal.ts']",
   * ) // true
   * ```
   */
- export declare function integrationViteProject(axes?: ViteAxes): string;
+ export declare function integrationViteProject(facts?: ViteFacts): string;
 
  /** Visible characters forbidden by portable paths and Markdown path cells. */
  export declare const INVALID_PATH_CHARACTER_PATTERN: RegExp;
@@ -2026,6 +2047,7 @@ export declare function coreViteConfig(browser?: boolean): string;
          bin: BooleanShape;
          integration: BooleanShape;
          service: BooleanShape;
+         global: BooleanShape;
      }, false>;
      groups: ArrayShape<LiteralShape<readonly Group[]>>;
      artifacts: ArrayShape<UnionShape<readonly [ ObjectShape<{
@@ -2241,9 +2263,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 axes - Optional structural project axes. `bin` appends the standalone
-  *   executable build-and-test project; `integration` and `service` append their
-  *   standalone proof projects.
+  * @param facts - Optional structural facts. `bin` appends the standalone executable
+  *   build-and-test project; `integration` and `service` append their standalone
+  *   proof projects; `global` wires the shared global-setup module.
   * @returns The root `vite.config.ts` file content, newline-terminated.
   *
   * @example
@@ -2251,10 +2273,10 @@ export declare function coreViteConfig(browser?: boolean): string;
   * rootViteConfig(['core']).includes('srcCore') // true
   * ```
   */
- export declare function rootViteConfig(src: readonly Environment[], axes?: ViteAxes): 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.8";
+ export declare const SCAFFOLD_RANGE = "^0.0.11";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2353,7 +2375,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * projects.
   *
   * @param environment - The sole declared non-`core` environment.
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns The root `vite.config.ts` file content for a single non-`core` environment, newline-terminated.
   *
   * @example
@@ -2361,7 +2383,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * singleSrcViteConfig('server').includes('srcServer') // true
   * ```
   */
- export declare function singleSrcViteConfig(environment: 'browser' | 'server', axes?: ViteAxes): string;
+ export declare function singleSrcViteConfig(environment: 'browser' | 'server', facts?: ViteFacts): string;
 
  /** Exact lowercase hexadecimal target bytes keyed by artifact-relative path. */
  export declare type Snapshot = Readonly<Record<string, string>>;
@@ -2723,11 +2745,19 @@ export declare function coreViteConfig(browser?: boolean): string;
      readonly note?: string;
  }
 
- /** Optional structural projects appended to a generated root Vite configuration. */
- export declare interface ViteAxes {
+ /**
+  * Optional structural facts consumed by a generated root Vite configuration.
+  *
+  * @remarks
+  * `bin`, `integration`, and `service` select their matching projects.
+  * `global` records the physical `tests/setupGlobal.ts` module and wires it
+  * into every selected project that consumes that shared setup.
+  */
+ export declare interface ViteFacts {
      readonly bin?: boolean;
      readonly integration?: boolean;
      readonly service?: boolean;
+     readonly global?: boolean;
  }
 
  /**
@@ -2797,7 +2827,7 @@ export declare function coreViteConfig(browser?: boolean): string;
  /**
   * Render the one ordered proof and structural-axis project definition block.
   *
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns Policy, guides, then selected axis project definitions, separated by one blank line.
   *
   * @example
@@ -2805,7 +2835,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * viteProjectDefinitions({ bin: true }).includes('export const srcBin =') // true
   * ```
   */
- export declare function viteProjectDefinitions(axes?: ViteAxes): string;
+ export declare function viteProjectDefinitions(facts?: ViteFacts): string;
 
  /** One generated Vitest project factory and its optional browser-project label. */
  export declare interface ViteProjectRegistration {
@@ -2819,7 +2849,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   *
   * @param src - The declared published environments.
   * @param app - The declared application environments.
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns Source projects, application projects, proof projects, then optional axis projects.
   *
   * @example
@@ -2828,6 +2858,6 @@ export declare function coreViteConfig(browser?: boolean): string;
   * // [{ project: 'srcCore' }, { project: 'policy' }, { project: 'guides' }, { project: 'integration' }]
   * ```
   */
- export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], axes?: ViteAxes): readonly ViteProjectRegistration[];
+ export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], facts?: ViteFacts): readonly ViteProjectRegistration[];
 
  export { }

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 axes - Optional executable, integration, and service project axes.
+ * @param facts - Optional structural facts.
  * @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[], axes?: ViteAxes): string;
+export declare function applicationViteConfig(src: readonly Environment[], app: readonly Environment[], facts?: ViteFacts): string;
 
 /**
  * Apply a blueprint's `overrides` over a drafted artifact list — an override
@@ -257,6 +257,8 @@ export declare interface Blueprint {
     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: `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;
 }
 
 /**
@@ -268,8 +270,8 @@ export declare interface Blueprint {
  * `version` / `engines` default `DEFAULT_VERSION` / `DEFAULT_ENGINES`,
  * `src` defaults `['core']`, and `app` / `keywords` / `dependencies` /
  * `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.
+ * `service` / `global` default `false`. `description` is OMITTED entirely
+ * when absent, so the result round-trips the exact-record `Blueprint` guard.
  * @returns A complete `Blueprint`.
  *
  * @example
@@ -326,6 +328,7 @@ export declare function blueprintShape(): ObjectShape<{
     bin: BooleanShape;
     integration: BooleanShape;
     service: BooleanShape;
+    global: BooleanShape;
 }, false>;
 
 /**
@@ -1038,6 +1041,21 @@ export declare function coreViteConfig(browser?: boolean): string;
   */
  export declare function findPathConflict(paths: readonly string[]): readonly [existing: string, duplicate: string] | undefined;
 
+ /**
+  * Test whether a complete rendered line fits the fleet formatter's print width.
+  *
+  * @param text - The complete rendered line, including indentation and trailing punctuation.
+  * @returns Whether the line fits within `JSON_PRINT_WIDTH`.
+  *
+  * @example
+  * ```ts
+  * import { fitsPrintWidth } from '@orkestrel/scaffold'
+  *
+  * fitsPrintWidth('\t["ESNext"],') // true
+  * ```
+  */
+ export declare function fitsPrintWidth(text: string): boolean;
+
  /**
   * Serialize a value to newline-terminated JSON that matches the fleet's own
   * `oxfmt` output byte-for-byte — objects one key per line, arrays collapsed
@@ -1077,6 +1095,9 @@ export declare function coreViteConfig(browser?: boolean): string;
  /** Function-declaration token kept out of template literals consumed by parity scans. */
  export declare const FUNCTION_KEYWORD = "function";
 
+ /** The consumer-owned Vitest global-setup module shared by its independently selected projects. */
+ export declare const GLOBAL_SETUP_PATH = "tests/setupGlobal.ts";
+
  /** The closed artifact-group vocabulary a plan selects over. */
  export declare type Group = 'manifest' | 'configs' | 'source' | 'tests' | 'guides' | 'docs' | 'orchestration';
 
@@ -1303,17 +1324,17 @@ export declare function coreViteConfig(browser?: boolean): string;
  /**
   * Build the standalone Node-only installed-consumer integration proof project.
   *
-  * @param axes - Optional executable and integration axes controlling the shared registry setup.
+  * @param facts - Optional structural facts controlling the shared global setup.
   * @returns The emitted `integration` project definition.
   *
   * @example
   * ```ts
-  * integrationViteProject({ bin: true, integration: true }).includes(
-  *   "globalSetup: ['./tests/setupIntegration.ts']",
+  * integrationViteProject({ bin: true, integration: true, global: true }).includes(
+  *   "globalSetup: ['./tests/setupGlobal.ts']",
   * ) // true
   * ```
   */
- export declare function integrationViteProject(axes?: ViteAxes): string;
+ export declare function integrationViteProject(facts?: ViteFacts): string;
 
  /** Visible characters forbidden by portable paths and Markdown path cells. */
  export declare const INVALID_PATH_CHARACTER_PATTERN: RegExp;
@@ -2026,6 +2047,7 @@ export declare function coreViteConfig(browser?: boolean): string;
          bin: BooleanShape;
          integration: BooleanShape;
          service: BooleanShape;
+         global: BooleanShape;
      }, false>;
      groups: ArrayShape<LiteralShape<readonly Group[]>>;
      artifacts: ArrayShape<UnionShape<readonly [ ObjectShape<{
@@ -2241,9 +2263,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 axes - Optional structural project axes. `bin` appends the standalone
-  *   executable build-and-test project; `integration` and `service` append their
-  *   standalone proof projects.
+  * @param facts - Optional structural facts. `bin` appends the standalone executable
+  *   build-and-test project; `integration` and `service` append their standalone
+  *   proof projects; `global` wires the shared global-setup module.
   * @returns The root `vite.config.ts` file content, newline-terminated.
   *
   * @example
@@ -2251,10 +2273,10 @@ export declare function coreViteConfig(browser?: boolean): string;
   * rootViteConfig(['core']).includes('srcCore') // true
   * ```
   */
- export declare function rootViteConfig(src: readonly Environment[], axes?: ViteAxes): 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.8";
+ export declare const SCAFFOLD_RANGE = "^0.0.11";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2353,7 +2375,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * projects.
   *
   * @param environment - The sole declared non-`core` environment.
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns The root `vite.config.ts` file content for a single non-`core` environment, newline-terminated.
   *
   * @example
@@ -2361,7 +2383,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * singleSrcViteConfig('server').includes('srcServer') // true
   * ```
   */
- export declare function singleSrcViteConfig(environment: 'browser' | 'server', axes?: ViteAxes): string;
+ export declare function singleSrcViteConfig(environment: 'browser' | 'server', facts?: ViteFacts): string;
 
  /** Exact lowercase hexadecimal target bytes keyed by artifact-relative path. */
  export declare type Snapshot = Readonly<Record<string, string>>;
@@ -2723,11 +2745,19 @@ export declare function coreViteConfig(browser?: boolean): string;
      readonly note?: string;
  }
 
- /** Optional structural projects appended to a generated root Vite configuration. */
- export declare interface ViteAxes {
+ /**
+  * Optional structural facts consumed by a generated root Vite configuration.
+  *
+  * @remarks
+  * `bin`, `integration`, and `service` select their matching projects.
+  * `global` records the physical `tests/setupGlobal.ts` module and wires it
+  * into every selected project that consumes that shared setup.
+  */
+ export declare interface ViteFacts {
      readonly bin?: boolean;
      readonly integration?: boolean;
      readonly service?: boolean;
+     readonly global?: boolean;
  }
 
  /**
@@ -2797,7 +2827,7 @@ export declare function coreViteConfig(browser?: boolean): string;
  /**
   * Render the one ordered proof and structural-axis project definition block.
   *
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns Policy, guides, then selected axis project definitions, separated by one blank line.
   *
   * @example
@@ -2805,7 +2835,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   * viteProjectDefinitions({ bin: true }).includes('export const srcBin =') // true
   * ```
   */
- export declare function viteProjectDefinitions(axes?: ViteAxes): string;
+ export declare function viteProjectDefinitions(facts?: ViteFacts): string;
 
  /** One generated Vitest project factory and its optional browser-project label. */
  export declare interface ViteProjectRegistration {
@@ -2819,7 +2849,7 @@ export declare function coreViteConfig(browser?: boolean): string;
   *
   * @param src - The declared published environments.
   * @param app - The declared application environments.
-  * @param axes - Optional executable, integration, and service project axes.
+  * @param facts - Optional structural facts.
   * @returns Source projects, application projects, proof projects, then optional axis projects.
   *
   * @example
@@ -2828,6 +2858,6 @@ export declare function coreViteConfig(browser?: boolean): string;
   * // [{ project: 'srcCore' }, { project: 'policy' }, { project: 'guides' }, { project: 'integration' }]
   * ```
   */
- export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], axes?: ViteAxes): readonly ViteProjectRegistration[];
+ export declare function viteProjectRegistrations(src: readonly Environment[], app?: readonly Environment[], facts?: ViteFacts): readonly ViteProjectRegistration[];
 
  export { }