@orkestrel/scaffold 0.0.133 → 0.0.135

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.
Files changed (92) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1568 -213
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +387 -109
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +275 -33
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/AGENTS.md +1 -1
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  35. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  36. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  37. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  38. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  42. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  43. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  45. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1990 -274
  46. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  47. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
  53. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  54. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  55. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  56. package/dist/host/claude/agents/orkestrel.md +16 -16
  57. package/dist/host/claude/rules/architecture.md +1 -1
  58. package/dist/host/claude/rules/documentation.md +1 -1
  59. package/dist/host/claude/rules/patterns.md +7 -4
  60. package/dist/host/claude/rules/styles.md +1 -1
  61. package/dist/host/claude/rules/tests.md +3 -3
  62. package/dist/host/claude/rules/workspace.md +50 -37
  63. package/dist/host/configs/helpers.ts +117 -71
  64. package/dist/host/dotfiles/oxlintrc.json +6 -0
  65. package/dist/host/guides/agent.md +989 -395
  66. package/dist/host/guides/database.md +357 -342
  67. package/dist/host/guides/form.md +79 -4
  68. package/dist/host/guides/middleware.md +5 -5
  69. package/dist/host/guides/ollama.md +41 -42
  70. package/dist/host/guides/scaffold.md +170 -70
  71. package/dist/host/guides/study.md +12 -12
  72. package/dist/host/guides/table.md +20 -6
  73. package/dist/host/guides/test.md +166 -52
  74. package/dist/host/guides/toolbox.md +127 -81
  75. package/dist/host/guides/workspace.md +21 -14
  76. package/dist/host/manifest.json +54 -54
  77. package/dist/host/tests/config.test.ts +251 -7
  78. package/dist/host/tests/policy.test.ts +14 -21
  79. package/dist/host/tests/setupPolicy.ts +43 -36
  80. package/dist/src/core/index.cjs +533 -139
  81. package/dist/src/core/index.cjs.map +1 -1
  82. package/dist/src/core/index.d.cts +223 -16
  83. package/dist/src/core/index.d.ts +223 -16
  84. package/dist/src/core/index.js +524 -139
  85. package/dist/src/core/index.js.map +1 -1
  86. package/dist/src/server/index.cjs +23 -14
  87. package/dist/src/server/index.cjs.map +1 -1
  88. package/dist/src/server/index.d.cts +3 -2
  89. package/dist/src/server/index.d.ts +3 -2
  90. package/dist/src/server/index.js +24 -15
  91. package/dist/src/server/index.js.map +1 -1
  92. package/package.json +2 -2
package/dist/bin/main.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
3
3
  import { attempt, isArray, isDefined, isError, isInstance, isRecord, isString, parseJSON } from "@orkestrel/contract";
4
- import { ARTIFACT_GROUPS, AXES, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, FRAMEWORKS, GLOBAL_SETUP_PATH, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, RESERVED_SHEET_NAMES, SERVICE_SETUP_PATH, SHEET_ENTRY_NAME, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SHOWCASE_PAGES_PATH, SKILLS_CONFIG_PATH, STYLES_ENTRY_PATH, ScaffoldError, THEMES_BARREL_PATH, THEMES_ENTRY_PATH, TREE_TEST_PATH, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToFaces, blueprintToManifestOverrides, blueprintToProjects, blueprintToScripts, blueprintToSheets, blueprintToTestArtifacts, blueprintToToolchainHolds, blueprintToWritableScripts, collectSurfaceAdvisories, collectSurfaceCollisions, compareSurfaceCollisions, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, isSheetName, iterateAnswers, manifestToDependencies, manifestToName, matchesGuideRefusal, nameToGuide, parseExtension, replaceManifestOverrides, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
4
+ import { ARTIFACT_GROUPS, AXES, BIN_ENTRY_PATH, BIN_OUTPUT_PATH, CATALOG_AGENT_PATH, CENTRAL_FILE_NAMES, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, FRAMEWORKS, GLOBAL_SETUP_PATH, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, RESERVED_SHEET_NAMES, SERVICE_SETUP_PATH, SHEET_ENTRY_NAME, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SHOWCASE_PAGES_PATH, SKILLS_CONFIG_PATH, STYLES_ENTRY_PATH, ScaffoldError, THEMES_BARREL_PATH, THEMES_ENTRY_PATH, TREE_TEST_PATH, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToEntries, blueprintToFaces, blueprintToManifest, blueprintToManifestOverrides, blueprintToProjects, blueprintToScripts, blueprintToSheets, blueprintToTestArtifacts, blueprintToToolchainHolds, blueprintToWritableScripts, collectSurfaceAdvisories, collectSurfaceCollisions, compareSurfaceCollisions, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, isSheetName, isSubpathMap, iterateAnswers, manifestToDependencies, manifestToEntries, manifestToName, matchesBarrel, matchesGuideRefusal, nameToGuide, parseExtension, replaceManifestOverrides, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
5
5
  import { MAX_INVENTORY_PATHS, Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readHostManifest, readSnapshot, readSurfaceCandidate, readSurfaceFile, readSurfaceGuide, readSurfaceRecord, resolveContainedPath, resolveSurfaceLoader } from "../src/server/index.js";
6
6
  import { join, normalize, resolve } from "node:path";
7
7
  import { createDuplex } from "@orkestrel/process/server";
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.133",
13
+ version: "0.0.135",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -115,7 +115,7 @@ var package_default = {
115
115
  "@orkestrel/guide": "^0.0.31",
116
116
  "@orkestrel/html": "^0.0.16",
117
117
  "@orkestrel/probe": "^0.0.30",
118
- "@orkestrel/test": "^0.0.36",
118
+ "@orkestrel/test": "^0.0.38",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.1.0",
121
121
  "oxfmt": "^0.78.0",
@@ -188,8 +188,14 @@ var USAGE_CODE = "USAGE";
188
188
  var FAILED_CODE = "FAILED";
189
189
  /** Holds what the failure envelope says when the raised value carried no message. */
190
190
  var FAILED_MESSAGE = "The command failed for an unrecognized reason";
191
- /** Names the gate chains a writing verb lands over a generated predecessor. */
192
- var CHAIN_SCRIPTS = Object.freeze(["test", "build:app"]);
191
+ /** Names the gate chains and aggregates a writing verb lands over a generated predecessor. */
192
+ var CHAIN_SCRIPTS = Object.freeze([
193
+ "test",
194
+ "test:src",
195
+ "check:src",
196
+ "build:src",
197
+ "build:app"
198
+ ]);
193
199
  /**
194
200
  * Names the workspace argument the creation verb takes, as usage writes it.
195
201
  *
@@ -817,8 +823,8 @@ function sheetTestToQuestion(artifact, present) {
817
823
  *
818
824
  * @param manifest - The target manifest text.
819
825
  * @param blueprint - The workspace shape that supplies the planned scripts.
820
- * @returns The blueprint's writable scripts, followed by the planned `test` and `build:app` chains
821
- * where each declared chain is a generated predecessor of its planned chain.
826
+ * @returns The blueprint's writable scripts, followed by each planned chain `CHAIN_SCRIPTS` names
827
+ * whose declared chain is a generated predecessor of it.
822
828
  *
823
829
  * @remarks
824
830
  * A publishing manifest's byte-exact former generated `test` chain also joins the writable
@@ -826,18 +832,20 @@ function sheetTestToQuestion(artifact, present) {
826
832
  * `test:src`. A chain that differs in spacing, order, or another step does not match that
827
833
  * predecessor.
828
834
  *
829
- * A declared `test` or `build:app` chain is a generated predecessor when it runs fewer `&&` steps
830
- * than the planned chain and every step it runs is a planned step, in the planned order. That is
831
- * the chain a birth or an earlier write left before a structural fact planned another step, such as
832
- * a root `tests/setupBrowser.test.ts` proof planning `npm run test:setup:browser`, or studies
833
- * beside the server application planning `npm run build:app:barrel`, so the write lands the
834
- * planned chain in its place. A chain running a step the plan does not generate, or running the
835
- * planned steps in another order, is one the package owns, and no entry names it.
836
- *
837
- * The planned chain joins only when every step it adds runs a script the manifest declares or the
838
- * writable scripts supply. The `test:src` and `test:app` aggregates sit outside the writable
839
- * scripts, so a planned chain adding an aggregate the manifest lacks stays with the package rather
840
- * than landing a step that names a missing script.
835
+ * A declared `test`, `test:src`, `check:src`, `build:src`, or `build:app` chain is a generated
836
+ * predecessor when it runs fewer `&&` steps or fewer `--project` values than the planned chain,
837
+ * and every step it runs matches a planned step, in the planned order, as {@link matchesStep}
838
+ * reads it. That is the chain a birth or an earlier write left before a structural fact planned
839
+ * another step, such as a root `tests/setupBrowser.test.ts` proof planning
840
+ * `npm run test:setup:browser`, `src/bin/main.ts` planning `npm run check:src:bin`, or
841
+ * studies beside the server application planning `npm run build:app:barrel`, so the write lands
842
+ * the planned chain in its place. A chain running a step the plan does not generate, or running
843
+ * the planned steps in another order, is one the package owns, and no entry names it.
844
+ *
845
+ * The planned chain joins only when every step it adds runs a Vitest command or a script the
846
+ * manifest declares or the writable scripts supply. An absent aggregate is never written, so a
847
+ * planned chain adding an aggregate the manifest lacks stays with the package rather than landing
848
+ * a step that names a missing script.
841
849
  */
842
850
  function manifestToWritableScripts(manifest, blueprint) {
843
851
  const writable = blueprintToWritableScripts(blueprint);
@@ -861,11 +869,14 @@ function manifestToWritableScripts(manifest, blueprint) {
861
869
  }
862
870
  const steps = declared.split("&&").map((step) => step.trim());
863
871
  const expected = planned.split("&&").map((step) => step.trim());
864
- if (steps.length >= expected.length) return [];
865
- const resumed = expected.values();
866
- if (!steps.every((step) => resumed.some((entry) => entry === step))) return [];
867
- return expected.every((step) => {
868
- if (steps.includes(step)) return true;
872
+ if (steps.length > expected.length) return [];
873
+ const resumed = expected.entries();
874
+ const matched = steps.map((step) => resumed.find(([, entry]) => matchesStep(step, entry))?.[0]);
875
+ if (matched.some((index) => index === void 0)) return [];
876
+ if (!(steps.length < expected.length || steps.some((step, position) => step !== expected[matched[position] ?? -1]))) return [];
877
+ return expected.every((step, index) => {
878
+ if (matched.includes(index)) return true;
879
+ if (step.startsWith("vitest ")) return true;
869
880
  const name = /^npm run (\S+)$/.exec(step)?.[1];
870
881
  return name !== void 0 && (supplied.has(name) || isString(scripts[name]));
871
882
  }) ? landed : [];
@@ -873,6 +884,87 @@ function manifestToWritableScripts(manifest, blueprint) {
873
884
  return [...writable, ...chains];
874
885
  }
875
886
  /**
887
+ * Renders each manifest entry as the key path and the JSON value a reader adds to `package.json`.
888
+ *
889
+ * @param entries - The entries to render.
890
+ * @returns One line per command, packed path, and subpath, in that section order.
891
+ *
892
+ * @example
893
+ * ```ts
894
+ * import { renderManifestEntries } from './helpers.js'
895
+ *
896
+ * renderManifestEntries({ bin: {}, files: ['dist/bin'], exports: {} }) // ['files[] "dist/bin"']
897
+ * ```
898
+ */
899
+ function renderManifestEntries(entries) {
900
+ return [
901
+ ...Object.entries(entries.bin).map(([name, path]) => `bin[${JSON.stringify(name)}] ${JSON.stringify(path)}`),
902
+ ...entries.files.map((path) => `files[] ${JSON.stringify(path)}`),
903
+ ...Object.entries(entries.exports).map(([path, value]) => `exports[${JSON.stringify(path)}] ${JSON.stringify(value)}`)
904
+ ];
905
+ }
906
+ /**
907
+ * Describes each manifest section whose shape refuses the planned entries it lacks.
908
+ *
909
+ * @param manifest - The target manifest text.
910
+ * @param missing - The planned entries the manifest lacks.
911
+ * @returns One clause per refusing section, naming the shape it holds and the change that admits
912
+ * the entries; empty when every section can take its missing entries.
913
+ *
914
+ * @remarks
915
+ * A string `exports`, a fallback array, and an object of conditions each publish the root export
916
+ * alone, and Node
917
+ * refuses an object that mixes conditions with subpaths, so the clause asks for a subpath map that
918
+ * keeps the declared value under `.`.
919
+ *
920
+ * @example
921
+ * ```ts
922
+ * import { describeEntryRefusal } from './helpers.js'
923
+ *
924
+ * describeEntryRefusal('{"files": "dist"}', { bin: {}, files: ['dist/bin'], exports: {} })
925
+ * // ['its files value is not an array of strings: declare files as an array of paths']
926
+ * ```
927
+ */
928
+ function describeEntryRefusal(manifest, missing) {
929
+ const parsed = parseJSON(manifest);
930
+ if (!isRecord(parsed)) return [];
931
+ const { bin, files, exports } = parsed;
932
+ return [
933
+ ...Object.keys(missing.bin).length === 0 || bin === void 0 || isRecord(bin) ? [] : [isString(bin) ? `its bin value is the string ${JSON.stringify(bin)}, which runs another file: declare bin as an object of commands` : "its bin value is not an object: declare bin as an object of commands"],
934
+ ...missing.files.length === 0 || files === void 0 || isArray(files) && files.every(isString) ? [] : ["its files value is not an array of strings: declare files as an array of paths"],
935
+ ...Object.keys(missing.exports).length === 0 || exports === void 0 || isSubpathMap(exports) ? [] : [isString(exports) || isArray(exports) || isRecord(exports) ? `its exports value is ${isString(exports) ? "a string" : isArray(exports) ? "a fallback array" : `an object of conditions (${Object.keys(exports).join(", ")})`}, which Node reads as the root export alone and refuses beside a subpath: declare exports as a map of subpaths that keeps this value under "."` : "its exports value is not an object: declare exports as a map of subpaths"]
936
+ ];
937
+ }
938
+ /**
939
+ * Checks whether a declared chain step runs a planned step or a generated predecessor of it.
940
+ *
941
+ * @param step - One declared `&&` step, trimmed.
942
+ * @param entry - One planned `&&` step, trimmed.
943
+ * @returns True if the steps are equal, or both run one command whose declared `--project` values
944
+ * are a non-empty subsequence of the planned values, in the planned order; false otherwise.
945
+ *
946
+ * @remarks
947
+ * The second form is the `test:src` aggregate a birth or an earlier write left before a structural
948
+ * fact planned another project, such as `src/bin/main.ts` planning `--project src:bin`.
949
+ * A step naming no project runs every project, so it is no predecessor of a step naming some.
950
+ *
951
+ * @example
952
+ * ```ts
953
+ * import { matchesStep } from './helpers.js'
954
+ *
955
+ * matchesStep('vitest run --project src:core', 'vitest run --project src:core --project src:bin') // true
956
+ * matchesStep('vitest run', 'vitest run --project src:core') // false
957
+ * ```
958
+ */
959
+ function matchesStep(step, entry) {
960
+ if (step === entry) return true;
961
+ const [head, ...projects] = step.split(/\s+--project\s+/u);
962
+ const [command, ...planned] = entry.split(/\s+--project\s+/u);
963
+ if (head !== command || projects.length === 0) return false;
964
+ const resumed = planned.values();
965
+ return projects.every((project) => resumed.some((name) => name === project));
966
+ }
967
+ /**
876
968
  * Keeps only dependencies published by the Orkestrel fleet.
877
969
  *
878
970
  * @param dependencies - The declared dependencies to inspect.
@@ -1446,6 +1538,37 @@ function targetToEnvironments(target, axis) {
1446
1538
  });
1447
1539
  }
1448
1540
  /**
1541
+ * Reads the `src/bin` modules a target physically holds.
1542
+ *
1543
+ * @param target - The target directory to read.
1544
+ * @returns The stem of each direct `.ts` file of `src/bin` that opens with a lowercase letter and
1545
+ * names no centralized file, sorted by stem, and `[]` when `src/bin` is absent.
1546
+ * @throws `ScaffoldError` when `src/bin` holds more entries than one inventory may report.
1547
+ *
1548
+ * @remarks
1549
+ * The read takes the direct children alone, so a nested file is never a module. A capitalized
1550
+ * stem is an implementation file and stays out. Every other stem enters the list whether or not
1551
+ * `isBinModule` admits it, so the blueprint gate refuses a malformed module name rather than the
1552
+ * read dropping it.
1553
+ *
1554
+ * @example
1555
+ * ```ts
1556
+ * import { targetToModules } from './helpers.js'
1557
+ *
1558
+ * targetToModules('./packages/router') // ['main', 'reporter']
1559
+ * ```
1560
+ */
1561
+ function targetToModules(target) {
1562
+ const directory = resolveContainedPath(target, "src/bin");
1563
+ if (directory === void 0 || !isPhysicalDirectory(directory)) return [];
1564
+ const entries = readdirSync(directory, { withFileTypes: true });
1565
+ if (entries.length > MAX_INVENTORY_PATHS) throw new ScaffoldError("TARGET", "The src/bin directory exceeds the inventory limit.");
1566
+ return entries.flatMap((entry) => {
1567
+ const stem = entry.name.slice(0, -3);
1568
+ return entry.isFile() && entry.name.endsWith(".ts") && /^[a-z]/u.test(stem) && !CENTRAL_FILE_NAMES.includes(stem) ? [stem] : [];
1569
+ }).sort();
1570
+ }
1571
+ /**
1449
1572
  * Reads the styles, themes, and showcase markers a target physically holds.
1450
1573
  * @param target - The target directory.
1451
1574
  * @returns The independent structural facts, false when their markers are absent.
@@ -2057,7 +2180,7 @@ var CLI = class {
2057
2180
  showcase: command.showcase === true,
2058
2181
  journey: app.includes("browser"),
2059
2182
  base: app.includes("browser"),
2060
- bin: command.bin === true,
2183
+ bin: command.bin === true ? ["main"] : [],
2061
2184
  setup: [],
2062
2185
  dependencies: selectionToPackages(command.dependencies).map((name) => ({
2063
2186
  name,
@@ -2261,9 +2384,11 @@ var CLI = class {
2261
2384
  scripts: manifestToWritableScripts(this.#manifest(target), blueprint)
2262
2385
  };
2263
2386
  const additions = manifestToAdditions(this.#manifest(target), blueprint);
2387
+ const entries = blueprintToEntries(blueprint);
2388
+ const absent = manifestToEntries(this.#manifest(target), entries);
2264
2389
  const repaired = host.materializer.repair(plan, audit, target);
2265
2390
  const policy = blueprint.showcase && blueprint.app.includes("browser") ? SHOWCASE_DEV_DEPENDENCIES : {};
2266
- const added = additions.runtime.length === 0 && additions.development.length === 0 && Object.keys(policy).length === 0 ? void 0 : host.materializer.declare({
2391
+ const added = additions.runtime.length === 0 && additions.development.length === 0 && Object.keys(policy).length === 0 && Object.keys(absent.bin).length === 0 && absent.files.length === 0 && Object.keys(absent.exports).length === 0 ? void 0 : host.materializer.declare({
2267
2392
  pins: {
2268
2393
  runtime: declared.pins.runtime.filter(({ name }) => Object.hasOwn(policy, name)).map(({ name, range }) => ({
2269
2394
  name,
@@ -2276,7 +2401,8 @@ var CLI = class {
2276
2401
  },
2277
2402
  scripts: [],
2278
2403
  additions,
2279
- overrides: blueprintToManifestOverrides(blueprint)
2404
+ overrides: blueprintToManifestOverrides(blueprint),
2405
+ entries
2280
2406
  }, target);
2281
2407
  const removed = host.materializer.remove(plan, audit, command.dirty === true ? {
2282
2408
  tracked: worktree.tracked,
@@ -2306,6 +2432,8 @@ var CLI = class {
2306
2432
  section: "devDependencies",
2307
2433
  dependencies: additions.development
2308
2434
  }]) for (const { name, range } of dependencies) this.#say(`Declared ${JSON.stringify(name)}: ${JSON.stringify(range)} in ${section}. Run npm install to install it.`);
2435
+ const remaining = new Set(renderManifestEntries(manifestToEntries(this.#manifest(target), entries)));
2436
+ for (const line of renderManifestEntries(absent)) if (!remaining.has(line)) this.#say(`Inserted ${line} in package.json.`);
2309
2437
  if (remainder.note !== void 0) this.#warn(remainder.note);
2310
2438
  }
2311
2439
  if (remainder.note !== void 0) return 1;
@@ -2609,7 +2737,6 @@ var CLI = class {
2609
2737
  const manifest = this.#manifest(target);
2610
2738
  const declared = manifestToName(manifest);
2611
2739
  if (declared === void 0) throw new ScaffoldError("TARGET", `The manifest at ${target} declares no package name.`, { target });
2612
- const bin = resolveContainedPath(target, BIN_ENTRY_PATH);
2613
2740
  const tests = resolveContainedPath(target, "tests");
2614
2741
  const guides = resolveContainedPath(target, GUIDES_TEST_PATH);
2615
2742
  const integration = resolveContainedPath(target, INTEGRATION_TEST_PATH);
@@ -2638,7 +2765,7 @@ var CLI = class {
2638
2765
  src: targetToEnvironments(target, "src"),
2639
2766
  app: targetToEnvironments(target, "app"),
2640
2767
  dependencies: manifestToDependencies(manifest).runtime,
2641
- bin: bin !== void 0 && isExactCaseFile(bin),
2768
+ bin: targetToModules(target),
2642
2769
  setup: [...setup],
2643
2770
  guides: guides !== void 0 && isExactCaseFile(guides),
2644
2771
  integration: integration !== void 0 && isExactCaseFile(integration),
@@ -2747,16 +2874,121 @@ var CLI = class {
2747
2874
  const disk = parseJSON(text);
2748
2875
  const written = isRecord(disk) && isRecord(disk.scripts) ? disk.scripts : {};
2749
2876
  const direct = names.map((project) => `test:${project}`);
2750
- const declared = direct.filter((script) => isString(written[script]));
2751
- const undeclared = direct.filter((script) => !isString(written[script]));
2752
- const remedies = !writing && manifestToWritableScripts(text, blueprint).some(({ name }) => name === "test") ? ["The test chain runs generated steps only, so repair and overwrite write the planned chain and every missing direct script."] : [declared.length === 0 ? "" : `${declared.join(", ")} ${declared.length === 1 ? "is" : "are"} already declared, so the gate is missing rather than the script: invoke ${declared.length === 1 ? "it" : "each of them"} by name from the ${gateNames} chain.`, undeclared.length === 0 ? "" : `${undeclared.join(", ")} ${undeclared.length === 1 ? "is" : "are"} not declared, so the script is missing as well as the gate: declare ${undeclared.length === 1 ? "it" : "each of them"} and invoke ${undeclared.length === 1 ? "it" : "each of them"} by name from the ${gateNames} chain.`];
2877
+ const rewrites = writing ? [] : manifestToWritableScripts(text, blueprint).filter(({ name }) => name === "test" || name === "test:src").map(({ name }) => name);
2878
+ const rewritable = rewrites.length > 0 && this.#projectQuestion(target, blueprint, true) === void 0;
2879
+ const visited = new Set([...chains.values()].flatMap((chain) => [...chain.visited]));
2880
+ const aggregated = names.flatMap((project) => {
2881
+ const owner = Object.entries(expected).find(([name, script]) => name !== `test:${project}` && visited.has(name) && (scriptToInvocations(script)?.projects ?? []).includes(project))?.[0];
2882
+ return owner === void 0 ? [] : [{
2883
+ project,
2884
+ owner
2885
+ }];
2886
+ });
2887
+ const unaggregated = direct.filter((script) => !aggregated.some(({ project }) => script === `test:${project}`));
2888
+ const declared = unaggregated.filter((script) => isString(written[script]));
2889
+ const undeclared = unaggregated.filter((script) => !isString(written[script]));
2890
+ const remedies = rewritable ? [`The ${rewrites.join(" and ")} ${rewrites.length === 1 ? "chain runs" : "chains run"} generated steps only, so repair and overwrite write the planned ${rewrites.length === 1 ? "chain" : "chains"} and every missing direct script.`] : [
2891
+ ...aggregated.map(({ project, owner }) => `The ${gateNames} chain runs ${owner}, which does not pass --project ${project}: add --project ${project} to ${owner}, or invoke npm run test:${project} by name from the ${gateNames} chain.`),
2892
+ declared.length === 0 ? "" : `${declared.join(", ")} ${declared.length === 1 ? "is" : "are"} already declared, so the gate is missing rather than the script: invoke ${declared.length === 1 ? "it" : "each of them"} by name from the ${gateNames} chain.`,
2893
+ undeclared.length === 0 ? "" : `${undeclared.join(", ")} ${undeclared.length === 1 ? "is" : "are"} not declared, so the script is missing as well as the gate: declare ${undeclared.length === 1 ? "it" : "each of them"} and invoke ${undeclared.length === 1 ? "it" : "each of them"} by name from the ${gateNames} chain.`
2894
+ ];
2753
2895
  return {
2754
2896
  field: "projects",
2755
- message: `${writing ? "The configs group is blocked because " : ""}the manifest at ${target} does not reach ${names.length === 1 ? "a Vitest project" : "Vitest projects"} the planned configuration registers: ${names.join(", ")}. No chain from ${gateNames} invokes ${names.length === 1 ? "it" : "them"}. ${remedies.filter((remedy) => remedy !== "").join(" ")}${writing ? " Exclude configs from --groups to write another group." : ""}`,
2897
+ message: `${writing ? "The configs group is blocked because the" : "The"} manifest at ${target} does not reach ${names.length === 1 ? "a Vitest project" : "Vitest projects"} the planned configuration registers: ${names.join(", ")}. No chain from ${gateNames} invokes ${names.length === 1 ? "it" : "them"}. ${remedies.filter((remedy) => remedy !== "").join(" ")}${writing ? " Exclude configs from --groups to write another group." : ""}`,
2756
2898
  blocking: false,
2757
2899
  groups: ["configs"]
2758
2900
  };
2759
2901
  }
2902
+ #barrelQuestion(target, blueprint) {
2903
+ if (!matchesBarrel(blueprint)) return void 0;
2904
+ const text = this.#manifest(target);
2905
+ const manifest = replaceManifestScripts(text, manifestToWritableScripts(text, blueprint)) ?? text;
2906
+ const parsed = parseJSON(manifest);
2907
+ const chain = collectScriptChain("build", isRecord(parsed) && isRecord(parsed.scripts) ? parsed.scripts : {}, /* @__PURE__ */ new Map());
2908
+ if (chain.visited.has("build:app:barrel")) return void 0;
2909
+ if (chain.unreadable.size > 0) return {
2910
+ field: "scripts",
2911
+ message: `The manifest at ${target} declares a build chain the audit could not read literally, so it cannot confirm that npm run build reaches the planned script build:app:barrel. The unreadable scripts are ${[...chain.unreadable].sort().join(", ")}, because each command is not a literal sequence of npm run scripts. Replace each with literal npm run script names.`,
2912
+ blocking: false,
2913
+ groups: ["manifest"]
2914
+ };
2915
+ return {
2916
+ field: "scripts",
2917
+ message: `The manifest at ${target} does not reach the planned script build:app:barrel from build, so npm run build does not emit dist/app/server/index.js. Invoke npm run build:app:barrel from the build chain, after npm run build:app:server.`,
2918
+ blocking: false,
2919
+ groups: ["manifest"]
2920
+ };
2921
+ }
2922
+ #entryQuestion(target, blueprint) {
2923
+ const text = this.#manifest(target);
2924
+ const planned = blueprintToEntries(blueprint);
2925
+ const missing = manifestToEntries(text, planned);
2926
+ const lines = renderManifestEntries(missing);
2927
+ if (lines.length === 0) return void 0;
2928
+ const single = lines.length === 1;
2929
+ const refusals = describeEntryRefusal(text, missing);
2930
+ return {
2931
+ field: "entries",
2932
+ message: `The manifest at ${target} does not declare ${single ? "a planned entry" : "planned entries"}: ${lines.join(", ")}. ${refusals.length > 0 ? `Overwrite cannot insert ${single ? "it" : "them"}, because ${refusals.join("; and ")}. Then run overwrite, or add ${single ? "it" : "each one"} to package.json by hand.` : `Run overwrite to insert ${single ? "it" : "each one"}, or add ${single ? "it" : "each one"} to package.json by hand.`}`,
2933
+ blocking: false,
2934
+ groups: ["manifest"]
2935
+ };
2936
+ }
2937
+ #chainQuestion(target, blueprint) {
2938
+ const faces = blueprint.bin.length > 0 ? ["bin"] : [];
2939
+ if (faces.length === 0) return void 0;
2940
+ const text = this.#manifest(target);
2941
+ const manifest = replaceManifestScripts(text, manifestToWritableScripts(text, blueprint)) ?? text;
2942
+ const parsed = parseJSON(manifest);
2943
+ const scripts = isRecord(parsed) && isRecord(parsed.scripts) ? parsed.scripts : {};
2944
+ const chains = new Map(["check", "build"].map((gate) => [gate, collectScriptChain(gate, scripts, /* @__PURE__ */ new Map())]));
2945
+ const missing = [...chains].flatMap(([gate, chain]) => {
2946
+ return faces.map((face) => `${gate}:src:${face}`).filter((name) => !chain.visited.has(name)).map((name) => ({
2947
+ gate,
2948
+ name,
2949
+ unreadable: [...chain.unreadable]
2950
+ }));
2951
+ });
2952
+ if (missing.length === 0) return void 0;
2953
+ const names = missing.map(({ name }) => name).join(", ");
2954
+ const unreadable = [...new Set(missing.flatMap((entry) => entry.unreadable))].sort();
2955
+ if (unreadable.length > 0) return {
2956
+ field: "scripts",
2957
+ message: `The manifest at ${target} declares a check or build chain the audit could not read literally, so it cannot confirm that the chain reaches the planned ${missing.length === 1 ? "script" : "scripts"} ${names}. The unreadable scripts are ${unreadable.join(", ")}, because each command is not a literal sequence of npm run scripts. Replace each with literal npm run script names.`,
2958
+ blocking: false,
2959
+ groups: ["manifest"]
2960
+ };
2961
+ const planned = blueprintToScripts(blueprint);
2962
+ const remedies = [...chains].flatMap(([gate, reached]) => {
2963
+ const chain = `${gate}:src`;
2964
+ const steps = missing.filter((entry) => entry.gate === gate).map(({ name }) => `npm run ${name}`);
2965
+ if (steps.length === 0) return [];
2966
+ if (!isString(scripts[chain])) return [`The manifest declares no ${chain} script: add ${JSON.stringify(chain)}: ${JSON.stringify(planned[chain] ?? steps.join(" && "))} and invoke npm run ${chain} from the ${gate} chain.`];
2967
+ const inner = collectScriptChain(chain, scripts, /* @__PURE__ */ new Map()).visited;
2968
+ const lacking = steps.filter((step) => !inner.has(step.slice(8)));
2969
+ if (reached.visited.has(chain)) return [`The ${chain} chain runs steps the plan does not generate, so invoke ${lacking.join(" and ")} from it.`];
2970
+ return [lacking.length === 0 ? `The ${gate} chain does not run npm run ${chain}: invoke npm run ${chain} from the ${gate} chain.` : `The ${gate} chain does not run npm run ${chain}, and ${chain} does not run ${lacking.join(" or ")}: invoke ${lacking.join(" and ")} from the ${chain} chain, and npm run ${chain} from the ${gate} chain.`];
2971
+ });
2972
+ return {
2973
+ field: "scripts",
2974
+ message: `The manifest at ${target} does not reach the planned ${missing.length === 1 ? "script" : "scripts"} ${missing.map(({ gate, name }) => `${name} from ${gate}`).join(", ")}. ${remedies.join(" ")}`,
2975
+ blocking: false,
2976
+ groups: ["manifest"]
2977
+ };
2978
+ }
2979
+ #effectQuestion(target, blueprint) {
2980
+ if (!blueprint.bin.includes("main")) return void 0;
2981
+ const parsed = parseJSON(this.#manifest(target));
2982
+ if (!isRecord(parsed) || parsed.sideEffects !== false) return void 0;
2983
+ const born = parseJSON(blueprintToManifest(blueprint));
2984
+ const planned = isRecord(born) && isArray(born.sideEffects) ? born.sideEffects : [`./${BIN_ENTRY_PATH}`, `./${BIN_OUTPUT_PATH}`];
2985
+ return {
2986
+ field: "sideEffects",
2987
+ message: `The manifest at ${target} declares "sideEffects": false, and the plan builds the executable ${BIN_ENTRY_PATH}. A bundler that reads that value may drop the imports the executable runs only for their side effects; "sideEffects": ${JSON.stringify(planned)} keeps them. Scaffold leaves the value to the package.`,
2988
+ blocking: false,
2989
+ groups: ["manifest"]
2990
+ };
2991
+ }
2760
2992
  #scriptQuestion(target, blueprint) {
2761
2993
  const text = this.#manifest(target);
2762
2994
  const writable = blueprintToWritableScripts(blueprint);
@@ -2899,6 +3131,16 @@ var CLI = class {
2899
3131
  const script = this.#scriptQuestion(target, blueprint);
2900
3132
  if (script !== void 0) questions.push(script);
2901
3133
  }
3134
+ const barrel = this.#barrelQuestion(target, blueprint);
3135
+ if (barrel !== void 0) questions.push(barrel);
3136
+ if (!writing) {
3137
+ const chain = this.#chainQuestion(target, blueprint);
3138
+ if (chain !== void 0) questions.push(chain);
3139
+ const entry = this.#entryQuestion(target, blueprint);
3140
+ if (entry !== void 0) questions.push(entry);
3141
+ const effect = this.#effectQuestion(target, blueprint);
3142
+ if (effect !== void 0) questions.push(effect);
3143
+ }
2902
3144
  const project = this.#projectQuestion(target, blueprint, writing);
2903
3145
  if (project !== void 0) questions.push(project);
2904
3146
  const dependency = this.#dependencyQuestion(target, blueprint, writing, declaring);