@orkestrel/scaffold 0.0.129 → 0.0.131

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1030,6 +1030,9 @@ export declare function blueprintToToolchainHolds(blueprint: Blueprint): Readonl
1030
1030
  * A base browser application's journey axis also adds `journey` and `capture`, and each
1031
1031
  * app-side browser face adds `journey:<name>` and `capture:<name>`. Their generated
1032
1032
  * commands are writable and have no predecessor forms; customized values remain caller-owned.
1033
+ * A workspace that plans the application server barrel adds `build:app:barrel`, which has no
1034
+ * predecessor form. A workspace with the server application adds `serve:build`, which runs `build`
1035
+ * before `serve`, so the barrel and every browser face the server serves are rebuilt.
1033
1036
  * Aggregate test scripts and
1034
1037
  * maintainer-owned gate chains stay outside the region.
1035
1038
  *
@@ -1040,8 +1043,8 @@ export declare function blueprintToToolchainHolds(blueprint: Blueprint): Readonl
1040
1043
  * existed. The pack hook accepts the build chain emitted before it
1041
1044
  * delegated to `build`. The publication hook accepts the same gate chain without
1042
1045
  * {@link RELEASE_PROOF_COMMAND}. No accepted publication chain carries a study
1043
- * step. The value being written is always writable, so
1044
- * it is not repeated there. Any other value is a script the workspace author
1046
+ * step. `serve:build` accepts the server-only chain it ran before it delegated to
1047
+ * `build`. The value being written is always writable, so it is not repeated there. Any other value is a script the workspace author
1045
1048
  * customized, and {@link replaceManifestScripts} retains it while writing the
1046
1049
  * other named scripts independently.
1047
1050
  *
@@ -1030,6 +1030,9 @@ export declare function blueprintToToolchainHolds(blueprint: Blueprint): Readonl
1030
1030
  * A base browser application's journey axis also adds `journey` and `capture`, and each
1031
1031
  * app-side browser face adds `journey:<name>` and `capture:<name>`. Their generated
1032
1032
  * commands are writable and have no predecessor forms; customized values remain caller-owned.
1033
+ * A workspace that plans the application server barrel adds `build:app:barrel`, which has no
1034
+ * predecessor form. A workspace with the server application adds `serve:build`, which runs `build`
1035
+ * before `serve`, so the barrel and every browser face the server serves are rebuilt.
1033
1036
  * Aggregate test scripts and
1034
1037
  * maintainer-owned gate chains stay outside the region.
1035
1038
  *
@@ -1040,8 +1043,8 @@ export declare function blueprintToToolchainHolds(blueprint: Blueprint): Readonl
1040
1043
  * existed. The pack hook accepts the build chain emitted before it
1041
1044
  * delegated to `build`. The publication hook accepts the same gate chain without
1042
1045
  * {@link RELEASE_PROOF_COMMAND}. No accepted publication chain carries a study
1043
- * step. The value being written is always writable, so
1044
- * it is not repeated there. Any other value is a script the workspace author
1046
+ * step. `serve:build` accepts the server-only chain it ran before it delegated to
1047
+ * `build`. The value being written is always writable, so it is not repeated there. Any other value is a script the workspace author
1045
1048
  * customized, and {@link replaceManifestScripts} retains it while writing the
1046
1049
  * other named scripts independently.
1047
1050
  *
@@ -3,7 +3,7 @@ import { fillTemplate } from "@orkestrel/template";
3
3
  import { Emitter } from "@orkestrel/emitter";
4
4
  var package_default = {
5
5
  name: "@orkestrel/scaffold",
6
- version: "0.0.129",
6
+ version: "0.0.131",
7
7
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
8
8
  keywords: [
9
9
  "audit",
@@ -1689,7 +1689,8 @@ export function service(override?: UserConfig): UserConfig {
1689
1689
  return mergeOverride(project, override)
1690
1690
  }
1691
1691
  `,
1692
- studies: `// Run these @orkestrel/study proofs on demand with npm run test:studies; no gate or chain runs them.
1692
+ studies: `// Run these @orkestrel/study proofs on demand with npm run test:studies;
1693
+ // no gate or chain runs them.
1693
1694
  export function studies(override?: UserConfig): UserConfig {
1694
1695
  const project: UserConfig = {
1695
1696
  resolve,
@@ -2754,10 +2755,15 @@ export interface DistributionClassification {
2754
2755
  readonly targets: readonly string[]
2755
2756
  }
2756
2757
 
2758
+ /** Holds the file, leading arguments, and shell route an npm run spawns with. */
2759
+ export interface DistributionNpmCommand {
2760
+ readonly file: string
2761
+ readonly prefix: readonly string[]
2762
+ readonly shell: boolean
2763
+ }
2764
+
2757
2765
  /** Names the workspace whose packed artifact the proof consumes. */
2758
2766
  export const DISTRIBUTION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
2759
- /** Names the npm executable on the running host. */
2760
- export const DISTRIBUTION_NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'
2761
2767
  // The compiler this workspace installs, run as a command rather than called in
2762
2768
  // process: the command and its plain-text diagnostics are the same across the
2763
2769
  // compiler majors this toolchain supports, and its in-process API is not. It is
@@ -2770,12 +2776,6 @@ export const DISTRIBUTION_TYPESCRIPT = createRequire(
2770
2776
  ).resolve('typescript/package.json')
2771
2777
  /** Names the compiler installed by the workspace under proof. */
2772
2778
  export const DISTRIBUTION_COMPILER = join(dirname(DISTRIBUTION_TYPESCRIPT), 'bin', 'tsc')
2773
- // Windows needs a shell to launch a \`.cmd\`: Node refuses one directly since the
2774
- // batch-argument hardening, and \`spawnSync\` returns \`EINVAL\` with a null status
2775
- // rather than an exit code a caller can read. Every following argument is a literal or
2776
- // a path this file built, so the shell has nothing to escape.
2777
- /** Selects the Windows command-shell route required by the npm shim. */
2778
- export const DISTRIBUTION_SHELL = process.platform === 'win32'
2779
2779
  // \`prepublishOnly\` runs this proof as \`npm run test:distribution -- --mode release\`,
2780
2780
  // and the root configuration's project factories carry that mode into this project.
2781
2781
  // Release is the publish gate, so evidence it cannot obtain fails there and skips
@@ -3102,6 +3102,50 @@ export function readDistributionOutput(result: SpawnSyncReturns<string>): string
3102
3102
  return \`\${result.stdout ?? ''}\${result.stderr ?? ''}\`.trim()
3103
3103
  }
3104
3104
 
3105
+ /**
3106
+ * Resolves the npm command for the running host.
3107
+ *
3108
+ * @remarks
3109
+ * npm's JavaScript entry beside the running Node binary spawns without a shell on every host. The
3110
+ * shim is the fallback where none sits there, and Windows needs a shell to launch its \`.cmd\`: Node
3111
+ * refuses one directly since the batch-argument hardening, and \`spawnSync\` returns \`EINVAL\` with a
3112
+ * null status rather than an exit code a caller can read. Every argument this file passes is a
3113
+ * literal or a path it built, so the shell has nothing to escape.
3114
+ *
3115
+ * @returns The file to spawn, the arguments that precede npm's own, and whether it needs a shell.
3116
+ */
3117
+ export function resolveDistributionNpm(): DistributionNpmCommand {
3118
+ const cli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js')
3119
+ if (existsSync(cli)) return { file: process.execPath, prefix: [cli], shell: false }
3120
+ const windows = process.platform === 'win32'
3121
+ return { file: windows ? 'npm.cmd' : 'npm', prefix: [], shell: windows }
3122
+ }
3123
+
3124
+ /**
3125
+ * Merges added variables over an inherited environment by case-folded name.
3126
+ *
3127
+ * @remarks
3128
+ * A Windows environment block folds names by case, and npm reads its \`npm_config_\` variables
3129
+ * case-insensitively on every host, so every inherited name an added name claims is dropped first:
3130
+ * an inherited \`NPM_CONFIG_CACHE\` would otherwise outrank an added \`npm_config_cache\`.
3131
+ *
3132
+ * @param inherited - The environment the child would inherit.
3133
+ * @param added - The variables the call sets.
3134
+ * @returns The merged environment.
3135
+ */
3136
+ export function mergeDistributionEnvironment(
3137
+ inherited: Readonly<Record<string, string | undefined>>,
3138
+ added: Readonly<Record<string, string>>,
3139
+ ): Readonly<Record<string, string | undefined>> {
3140
+ const claimed = new Set(Object.keys(added).map((name) => name.toLowerCase()))
3141
+ return {
3142
+ ...Object.fromEntries(
3143
+ Object.entries(inherited).filter(([name]) => !claimed.has(name.toLowerCase())),
3144
+ ),
3145
+ ...added,
3146
+ }
3147
+ }
3148
+
3105
3149
  /**
3106
3150
  * Runs npm with a cache inside the owned scratch directory.
3107
3151
  *
@@ -3115,11 +3159,12 @@ export function runDistributionNpm(
3115
3159
  cwd: string,
3116
3160
  scratch: string,
3117
3161
  ): SpawnSyncReturns<string> {
3118
- return spawnSync(DISTRIBUTION_NPM, [...args], {
3162
+ const npm = resolveDistributionNpm()
3163
+ return spawnSync(npm.file, [...npm.prefix, ...args], {
3119
3164
  cwd,
3120
3165
  encoding: 'utf8',
3121
- env: { ...process.env, npm_config_cache: join(scratch, 'cache') },
3122
- shell: DISTRIBUTION_SHELL,
3166
+ env: mergeDistributionEnvironment(process.env, { npm_config_cache: join(scratch, 'cache') }),
3167
+ shell: npm.shell,
3123
3168
  windowsHide: true,
3124
3169
  })
3125
3170
  }
@@ -7424,7 +7469,7 @@ function blueprintToScripts(blueprint) {
7424
7469
  ...blueprint.showcase ? Object.fromEntries(application.flatMap((name) => [[`showcase:${name}`, `${showcase} --mode ${name}`], [`build:showcase:${name}`, `${buildShowcase} --mode ${name}`]])) : {},
7425
7470
  ...blueprint.app.includes("server") ? {
7426
7471
  serve: "node dist/app/server/main.cjs",
7427
- "serve:build": "npm run build:app:server && npm run serve"
7472
+ "serve:build": "npm run build && npm run serve"
7428
7473
  } : {},
7429
7474
  ...publishes ? {
7430
7475
  prepack: "npm run build",
@@ -7454,6 +7499,9 @@ function blueprintToScripts(blueprint) {
7454
7499
  * A base browser application's journey axis also adds `journey` and `capture`, and each
7455
7500
  * app-side browser face adds `journey:<name>` and `capture:<name>`. Their generated
7456
7501
  * commands are writable and have no predecessor forms; customized values remain caller-owned.
7502
+ * A workspace that plans the application server barrel adds `build:app:barrel`, which has no
7503
+ * predecessor form. A workspace with the server application adds `serve:build`, which runs `build`
7504
+ * before `serve`, so the barrel and every browser face the server serves are rebuilt.
7457
7505
  * Aggregate test scripts and
7458
7506
  * maintainer-owned gate chains stay outside the region.
7459
7507
  *
@@ -7464,8 +7512,8 @@ function blueprintToScripts(blueprint) {
7464
7512
  * existed. The pack hook accepts the build chain emitted before it
7465
7513
  * delegated to `build`. The publication hook accepts the same gate chain without
7466
7514
  * {@link RELEASE_PROOF_COMMAND}. No accepted publication chain carries a study
7467
- * step. The value being written is always writable, so
7468
- * it is not repeated there. Any other value is a script the workspace author
7515
+ * step. `serve:build` accepts the server-only chain it ran before it delegated to
7516
+ * `build`. The value being written is always writable, so it is not repeated there. Any other value is a script the workspace author
7469
7517
  * customized, and {@link replaceManifestScripts} retains it while writing the
7470
7518
  * other named scripts independently.
7471
7519
  *
@@ -7486,11 +7534,14 @@ function blueprintToWritableScripts(blueprint) {
7486
7534
  const sheet = sheets.some((face) => name === `build:src:${face}` || name === `check:src:${face}`);
7487
7535
  const framework = blueprintToFaces(blueprint).some((extension) => extension.surface === "browser" && extension.axes.some((axis) => name === `check:${axis}:${extension.name}` || name === `build:${axis}:${extension.name}` || axis === "app" && (name === `dev:${extension.name}` || name === `journey:${extension.name}` || name === `capture:${extension.name}`)));
7488
7536
  const showcase = name === "showcase" || name.startsWith("showcase:") || name === "build:showcase" || name.startsWith("build:showcase:");
7489
- if (!direct && !sheet && !framework && !showcase && !(name === "journey" || name === "capture")) return [];
7537
+ const capture = name === "journey" || name === "capture";
7538
+ const barrel = matchesBarrel(blueprint) && name === "build:app:barrel";
7539
+ const served = blueprint.app.includes("server") && name === "serve:build";
7540
+ if (!direct && !sheet && !framework && !showcase && !capture && !barrel && !served) return [];
7490
7541
  return [{
7491
7542
  name,
7492
7543
  command,
7493
- accepted: name === "test:guides" ? ["vitest run --config vite.config.ts --no-cache --reporter=dot --project guides"] : name === "test:bench" ? ["vitest bench --config vite.config.ts --no-cache --project probe"] : name === "build:src:styles" && blueprint.themes ? ["vite build --config configs/src/vite.styles.config.ts"] : sheets.some((face) => name === `test:src:${face}`) ? [command.slice(command.indexOf(" && ") + 4)] : []
7544
+ accepted: name === "test:guides" ? ["vitest run --config vite.config.ts --no-cache --reporter=dot --project guides"] : name === "test:bench" ? ["vitest bench --config vite.config.ts --no-cache --project probe"] : name === "build:src:styles" && blueprint.themes ? ["vite build --config configs/src/vite.styles.config.ts"] : sheets.some((face) => name === `test:src:${face}`) ? [command.slice(command.indexOf(" && ") + 4)] : name === "serve:build" ? ["npm run build:app:server && npm run serve"] : []
7494
7545
  }];
7495
7546
  });
7496
7547
  const prepack = scripts.prepack;