@solid-stack/builder 3.1.0 → 3.2.0

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.
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Solid Stack Builder V3
2
2
 
3
- Builder 3.1.0 compiles a service's `build.json` or a system's `mesh.json` into Docker Compose. Services declare possible runtime modules; explicit **requisites** select which modules run and how they wait. Mesh sources stay independently runnable, with explicit `extends` rewrites when a real service replaces a local mock. Main services can declare stage-aware Docker `buildArgs`.
3
+ Builder 3.2.0 compiles a service's `build.json` or a system's `mesh.json` into Docker Compose. Services declare possible runtime modules; explicit **requisites** select which modules run and how they wait. Mesh sources stay independently runnable, with explicit `extends` rewrites when a real service replaces a local mock. Main services can declare stage-aware Docker `buildArgs`, and isolated runs can start local helper modules through `on-inframode-isolated`.
4
4
 
5
- The source package declares version 3.1.0. This checkout does not imply that version has been published to a package registry. For a local checkout, run `pnpm install`, `pnpm build`, and `node dist/bin.js --version`. The package exposes both `builder` and `solid-builder` when installed. Node.js 20 or newer and Docker Engine with Compose are required for runtime commands.
5
+ The source package declares version 3.2.0. This checkout does not imply that version has been published to a package registry. For a local checkout, run `pnpm install`, `pnpm build`, and `node dist/bin.js --version`. The package exposes both `builder` and `solid-builder` when installed. Node.js 20 or newer and Docker Engine with Compose are required for runtime commands.
6
6
 
7
7
  [Builder V3 documentation](docs/README.md)
8
8
 
@@ -10,6 +10,8 @@ The source package declares version 3.1.0. This checkout does not imply that ver
10
10
 
11
11
  [Upgrade from Builder 3.0.0](docs/migration/v3.0-to-v3.1.md)
12
12
 
13
+ [Upgrade from Builder 3.1.0](docs/migration/v3.1-to-v3.2.md)
14
+
13
15
  ## Tests
14
16
 
15
17
  Run `pnpm test` for the complete V3 verification suite. It runs non-Docker tests, typechecking, build and API checks first, then the three Docker acceptance tests. Docker tests require a prepared local fixture image; run `pnpm test:v3:prepare` once when the fixture is missing or stale. For a quick run without Docker, use `pnpm test:v3:fast`.
@@ -41,7 +43,7 @@ services:
41
43
  command: ["sh", "-c", "exit 0"]
42
44
  ```
43
45
 
44
- The [service quickstart](docs/getting-started/service-quickstart.md) gives a runnable tree. Run `builder check`, then `builder service up dev`; `builder service up dev --full` includes the effective requisite closure. `builder service up prod` uses the `prod` target and integrated graph. `builder service up test` runs isolated unit tests, cleans up, then runs service E2E with a production main and full graph.
46
+ The [service quickstart](docs/getting-started/service-quickstart.md) gives a runnable tree. Run `builder check`, then `builder service up dev`; `builder service up dev --full` includes the effective requisite closure; `dev.on-inframode-isolated` can add local helpers to plain isolated dev. `builder service up prod` uses the `prod` target and integrated graph. `builder service up test` runs isolated unit tests, cleans up, then runs service E2E with a production main and full graph.
45
47
 
46
48
  | Workflow | Main target | Main execution mode | Infrastructure mode |
47
49
  |---|---|---|---|
package/dist/bin.js CHANGED
@@ -77,14 +77,21 @@ var buildServicesSchema = z.record(identifier, z.unknown()).superRefine((value,
77
77
  if (!parsed.success) for (const issue of parsed.error.issues) context.addIssue({ ...issue, path: [key, ...issue.path] });
78
78
  }
79
79
  });
80
- var buildStageSchema = z.object({ services: z.record(identifier, z.unknown()).superRefine((value, context) => {
80
+ var overlayServices = (allowTester) => z.record(identifier, z.unknown()).superRefine((value, context) => {
81
81
  for (const [key, entry] of Object.entries(value)) {
82
+ if (key === "tester" && !allowTester) {
83
+ context.addIssue({ code: "custom", path: [key], message: "tester cannot be configured in on-inframode-isolated" });
84
+ continue;
85
+ }
82
86
  const schema = key === "main" ? mainOverlaySchema : key === "tester" ? testerOverlaySchema : ordinaryOverlaySchema;
83
87
  const parsed = schema.safeParse(entry);
84
88
  if (!parsed.success) for (const issue of parsed.error.issues) context.addIssue({ ...issue, path: [key, ...issue.path] });
85
89
  }
86
- }).optional() }).strict();
87
- var buildJsonSchema = z.object({ $schema: z.string().optional(), name: nonblank, services: buildServicesSchema, dev: buildStageSchema.optional(), prod: buildStageSchema.optional(), test: buildStageSchema.optional(), e2e: buildStageSchema.optional() }).strict();
90
+ });
91
+ var buildStageSchema = z.object({ services: overlayServices(true).optional() }).strict();
92
+ var isolatedInfraOverlaySchema = z.object({ services: overlayServices(false).optional() }).strict();
93
+ var isolatableBuildStageSchema = z.object({ services: overlayServices(true).optional(), "on-inframode-isolated": isolatedInfraOverlaySchema.optional() }).strict();
94
+ var buildJsonSchema = z.object({ $schema: z.string().optional(), name: nonblank, services: buildServicesSchema, dev: isolatableBuildStageSchema.optional(), prod: buildStageSchema.optional(), test: isolatableBuildStageSchema.optional(), e2e: buildStageSchema.optional() }).strict();
88
95
 
89
96
  // src/utils/errorMessage.ts
90
97
  function errorMessage(err) {
@@ -333,6 +340,14 @@ function checkDockerfileContract(build, projectDir) {
333
340
  runStep("docker", ["run", "--rm", "--network", "none", "--mount", `type=bind,src=${root},dst=/project,readonly`, "--mount", `type=bind,src=${policyDir},dst=/builder-policy,readonly`, "-w", "/project", CONFTEST_IMAGE, "test", relative, "-p", "/builder-policy"], root, { stepName: "Dockerfile Contract", targetFile: relative });
334
341
  }
335
342
 
343
+ // src/core/config/executionProfile.ts
344
+ function executionProfile(stage2, composition, full = false) {
345
+ if (composition === "mesh" && stage2 === "test") throw new Error("Mesh test is a workflow, not a configuration stage");
346
+ if (stage2 === "dev") return { configStage: stage2, envStage: stage2, mainTarget: "dev", execMode: "dev", infraMode: composition === "mesh" || full ? "integrated" : "isolated", attachTester: false };
347
+ if (stage2 === "test") return { configStage: stage2, envStage: stage2, mainTarget: "test", execMode: "test", infraMode: "isolated", attachTester: false };
348
+ return { configStage: stage2, envStage: stage2, mainTarget: "prod", execMode: "prod", infraMode: "integrated", attachTester: stage2 === "e2e" };
349
+ }
350
+
336
351
  // src/core/config/endpointProperties.ts
337
352
  function resolveEndpointProperty(endpoint, property, context) {
338
353
  const reference = context.referencedObject ?? endpoint.logicalPath;
@@ -400,11 +415,12 @@ function applyServiceOverlay(base, patch) {
400
415
  }
401
416
 
402
417
  // src/core/config/resolveBuildStage.ts
403
- var originFor = (sourceFile, configPath, layer) => ({ sourceFile, configPath, projectDir: path.dirname(sourceFile), scope: "build", layer });
418
+ var ISOLATED_OVERLAY_KEY = "on-inframode-isolated";
419
+ var originFor = (sourceFile, configPath, layer, isolatedOverlay = false) => ({ sourceFile, configPath, projectDir: path.dirname(sourceFile), scope: "build", layer, ...isolatedOverlay ? { isolatedOverlay: true } : {} });
404
420
  var fail = (sourceFile, stage2, configPath, reason, value) => {
405
421
  throw new ConfigError({ sourceFile, stage: stage2, composition: "service", configPath, reason, value });
406
422
  };
407
- function resolveBuildStage(build, stage2, sourceFile) {
423
+ function resolveBuildStage(build, stage2, sourceFile, options = {}) {
408
424
  const services2 = structuredClone(build.services);
409
425
  const origins = /* @__PURE__ */ new Map();
410
426
  const envOrigins = /* @__PURE__ */ new Map();
@@ -412,38 +428,43 @@ function resolveBuildStage(build, stage2, sourceFile) {
412
428
  const requisiteOrigins = /* @__PURE__ */ new Map();
413
429
  const layers = [];
414
430
  const deletedRequisiteTargets = [];
415
- const record = (name, entry, layer) => {
416
- const where = layer === "base" ? `services.${name}` : `${layer}.services.${name}`;
417
- const origin = originFor(sourceFile, where, layer);
431
+ const record = (name, entry, layer, servicesPath, isolatedOverlay = false) => {
432
+ const where = `${servicesPath}.${name}`;
433
+ const origin = originFor(sourceFile, where, layer, isolatedOverlay);
418
434
  origins.set(name, origin);
419
435
  const env2 = envOrigins.get(name) ?? /* @__PURE__ */ new Map();
420
- for (const key of Object.keys(entry.env ?? {})) env2.set(key, originFor(sourceFile, `${where}.env.${key}`, layer));
436
+ for (const key of Object.keys(entry.env ?? {})) env2.set(key, originFor(sourceFile, `${where}.env.${key}`, layer, isolatedOverlay));
421
437
  envOrigins.set(name, env2);
422
438
  const args = buildArgsOrigins.get(name) ?? /* @__PURE__ */ new Map();
423
- for (const key of Object.keys(entry.buildArgs ?? {})) args.set(key, originFor(sourceFile, `${where}.buildArgs.${key}`, layer));
439
+ for (const key of Object.keys(entry.buildArgs ?? {})) args.set(key, originFor(sourceFile, `${where}.buildArgs.${key}`, layer, isolatedOverlay));
424
440
  buildArgsOrigins.set(name, args);
425
441
  const edges = requisiteOrigins.get(name) ?? /* @__PURE__ */ new Map();
426
442
  for (const [key, value] of Object.entries(entry.requisites ?? {})) {
427
443
  if (value === false) edges.delete(key);
428
- else edges.set(key, originFor(sourceFile, `${where}.requisites.${key}`, layer));
444
+ else edges.set(key, originFor(sourceFile, `${where}.requisites.${key}`, layer, isolatedOverlay));
429
445
  }
430
446
  requisiteOrigins.set(name, edges);
431
447
  };
432
- for (const [name, value] of Object.entries(services2).sort(([a], [b]) => a.localeCompare(b))) record(name, value, "base");
433
- layers.push({ stage: "base", services: structuredClone(services2), origin: originFor(sourceFile, "services", "base") });
434
- for (const overlayStage of stageOverlayChain(stage2)) {
435
- const patches = build[overlayStage]?.services ?? {};
448
+ const applyOverlay = (patches, overlayStage, servicesPath, isolatedOverlay) => {
436
449
  for (const [name, patch] of Object.entries(patches).sort(([a], [b]) => a.localeCompare(b))) {
437
450
  const current = services2[name];
438
- const where = `${overlayStage}.services.${name}`;
451
+ const where = `${servicesPath}.${name}`;
452
+ if (isolatedOverlay && name === "tester") fail(sourceFile, stage2, where, `tester cannot be configured in ${ISOLATED_OVERLAY_KEY}`);
439
453
  if (!current && (name === "main" || name === "tester")) fail(sourceFile, stage2, where, "Required special service is missing from base");
440
454
  if (current && patch.compose !== void 0 && patch.compose !== current.compose) fail(sourceFile, stage2, `${where}.compose`, `compose is immutable; previous declaration ${origins.get(name)?.configPath}.compose, attempted ${where}.compose`, patch.compose);
441
455
  if (!current && name !== "main" && name !== "tester" && (typeof patch.compose !== "string" || !patch.compose.trim())) fail(sourceFile, stage2, `${where}.compose`, "Stage-introduced service requires a complete compose declaration");
442
456
  services2[name] = current ? applyServiceOverlay(current, patch) : structuredClone(patch);
443
457
  for (const [target, kind] of Object.entries(patch.requisites ?? {})) if (kind === false) deletedRequisiteTargets.push({ target, path: `${where}.requisites.${target}` });
444
- record(name, patch, overlayStage);
458
+ record(name, patch, overlayStage, servicesPath, isolatedOverlay);
445
459
  }
446
- layers.push({ stage: overlayStage, services: structuredClone(patches), origin: originFor(sourceFile, `${overlayStage}.services`, overlayStage) });
460
+ layers.push({ stage: overlayStage, services: structuredClone(patches), origin: originFor(sourceFile, servicesPath, overlayStage, isolatedOverlay) });
461
+ };
462
+ for (const [name, value] of Object.entries(services2).sort(([a], [b]) => a.localeCompare(b))) record(name, value, "base", "services");
463
+ layers.push({ stage: "base", services: structuredClone(services2), origin: originFor(sourceFile, "services", "base") });
464
+ for (const overlayStage of stageOverlayChain(stage2)) applyOverlay(build[overlayStage]?.services ?? {}, overlayStage, `${overlayStage}.services`, false);
465
+ if (options.isolated && (stage2 === "dev" || stage2 === "test")) {
466
+ const block = build[stage2]?.[ISOLATED_OVERLAY_KEY];
467
+ if (block) applyOverlay(block.services ?? {}, stage2, `${stage2}.${ISOLATED_OVERLAY_KEY}.services`, true);
447
468
  }
448
469
  for (const deleted of deletedRequisiteTargets) if (!(deleted.target in services2)) fail(sourceFile, stage2, deleted.path, "Unknown requisite target", deleted.target);
449
470
  for (const [name, value] of Object.entries(services2)) {
@@ -528,14 +549,6 @@ function assertDotenvDoesNotDefineKeys(filePath, keys, context) {
528
549
  }
529
550
  }
530
551
 
531
- // src/core/config/executionProfile.ts
532
- function executionProfile(stage2, composition, full = false) {
533
- if (composition === "mesh" && stage2 === "test") throw new Error("Mesh test is a workflow, not a configuration stage");
534
- if (stage2 === "dev") return { configStage: stage2, envStage: stage2, mainTarget: "dev", execMode: "dev", infraMode: composition === "mesh" || full ? "integrated" : "isolated", attachTester: false };
535
- if (stage2 === "test") return { configStage: stage2, envStage: stage2, mainTarget: "test", execMode: "test", infraMode: "isolated", attachTester: false };
536
- return { configStage: stage2, envStage: stage2, mainTarget: "prod", execMode: "prod", infraMode: "integrated", attachTester: stage2 === "e2e" };
537
- }
538
-
539
552
  // src/errors/PortConflictError.ts
540
553
  var PortConflictError = class extends ConfigError {
541
554
  port;
@@ -732,14 +745,14 @@ function buildDeclaredGraph(input) {
732
745
  edges.sort((a, b) => `${a.consumer}:${a.target}:${a.kind}`.localeCompare(`${b.consumer}:${b.target}:${b.kind}`));
733
746
  return { nodes: input.nodes, roots: [...input.roots].sort(), edges };
734
747
  }
735
- function computeClosure(start, adjacency) {
748
+ function computeClosure(start, adjacency, follow = () => true) {
736
749
  const visited = /* @__PURE__ */ new Set();
737
750
  const stack = [start];
738
751
  while (stack.length) {
739
752
  const id = stack.pop();
740
753
  if (visited.has(id)) continue;
741
754
  visited.add(id);
742
- for (const edge of adjacency.get(id) ?? []) stack.push(edge.target);
755
+ for (const edge of adjacency.get(id) ?? []) if (follow(edge)) stack.push(edge.target);
743
756
  }
744
757
  return visited;
745
758
  }
@@ -750,11 +763,12 @@ function selectReachableGraph(declared, profile) {
750
763
  list.push(edge);
751
764
  adjacency.set(edge.consumer, list);
752
765
  }
766
+ const rootSet = new Set(declared.roots), isolated = profile.infraMode === "isolated";
767
+ const follow = (edge) => !isolated || !rootSet.has(edge.consumer) || edge.origin.isolatedOverlay === true;
753
768
  const active = /* @__PURE__ */ new Set();
754
- if (profile.infraMode === "isolated") for (const root of declared.roots) active.add(root);
755
- else for (const root of declared.roots) for (const id of computeClosure(root, adjacency)) active.add(id);
769
+ for (const root of declared.roots) for (const id of computeClosure(root, adjacency, follow)) active.add(id);
756
770
  const nodes = new Map([...declared.nodes].filter(([id]) => active.has(id)));
757
- const edges = profile.infraMode === "isolated" ? [] : declared.edges.filter((edge) => active.has(edge.consumer) && active.has(edge.target));
771
+ const edges = declared.edges.filter((edge) => follow(edge) && active.has(edge.consumer) && active.has(edge.target));
758
772
  const activeAdjacency = /* @__PURE__ */ new Map();
759
773
  for (const edge of edges) {
760
774
  const list = activeAdjacency.get(edge.consumer) ?? [];
@@ -1925,7 +1939,8 @@ function compileGraphComposition(input) {
1925
1939
 
1926
1940
  // src/core/composition/compileServiceComposition.ts
1927
1941
  function compileServiceComposition(stage2, projectDir, options = {}) {
1928
- const root = resolveProjectDir(projectDir), build = resolveBuildStage(getBuildJson(root), stage2, path.join(root, "build.json"));
1942
+ const root = resolveProjectDir(projectDir), isolated = executionProfile(stage2, "service", Boolean(options.full)).infraMode === "isolated";
1943
+ const build = resolveBuildStage(getBuildJson(root), stage2, path.join(root, "build.json"), { isolated });
1929
1944
  return compileGraphComposition({ stage: stage2, composition: "service", projectDir: root, name: build.name, instances: /* @__PURE__ */ new Map([["", build]]), full: Boolean(options.full), validationMode: Boolean(options.validationMode) });
1930
1945
  }
1931
1946
 
@@ -2998,21 +3013,6 @@ var runMeshProd = (options = {}) => {
2998
3013
  const root = resolveProjectDir(options.projectDir);
2999
3014
  return runLongLived("prod", root, options, (validationMode) => compileMeshComposition("prod", root, { validationMode }), "mesh");
3000
3015
  };
3001
- async function runTestUnit(options, adapters = {}) {
3002
- const compiled = compileServiceComposition("test", options.projectDir, { validationMode: Boolean(options.dryRun) }), yaml = stringify(compiled.compose);
3003
- const main = compiled.mainServiceNames.get(nodeId(void 0, "main"));
3004
- if (options.debug) console.log(redactYamlSecrets(yaml));
3005
- if (options.dryRun) return 0;
3006
- await (adapters.checkPorts ?? checkHostPortCollisions)(extractHostPorts(yaml));
3007
- await (adapters.teardown ?? teardownCompose)(yaml, options.projectDir, { removeVolumes: true, silent: true });
3008
- persistHostPortAllocations(options.projectDir, compiled.allocations);
3009
- writeRunState(options.projectDir, { projectName: compiled.projectName, stage: "test-unit", configStage: "test", workflow: "test", composition: "service", projectDir: options.projectDir, runtimeServiceNames: [main], testerServiceNames: [], allocatedEndpointKeys: [...compiled.allocations.keys()] });
3010
- return runWithCleanup(() => (adapters.compose ?? runCompose)(["up", "--build", "--abort-on-container-exit", "--exit-code-from", main, main], yaml, options.projectDir, { removeVolumes: true }), async () => {
3011
- await (adapters.teardown ?? teardownCompose)(yaml, options.projectDir, { removeVolumes: true });
3012
- removeHostPortAllocations(options.projectDir, [...compiled.allocations.keys()]);
3013
- clearRunState(options.projectDir);
3014
- });
3015
- }
3016
3016
  function inspectRunnerExit(yaml, projectDir, runner) {
3017
3017
  const ps = spawnSync("docker", ["compose", "--project-directory", projectDir, "-f", "-", "ps", "-aq", runner], { cwd: projectDir, encoding: "utf8", input: yaml });
3018
3018
  const id = ps.stdout?.trim();
@@ -3063,7 +3063,43 @@ async function runFiniteTester(compiled, projectDir, adapters = {}) {
3063
3063
  return status;
3064
3064
  }
3065
3065
 
3066
- // src/core/runners/runTestE2e.ts
3066
+ // src/core/runners/runTestUnit.ts
3067
+ async function runUnitWithLocalModules(compiled, yaml, main, projectDir, compose, inspectExit) {
3068
+ const started = await compose(["up", "--build", "--detach", ...compiled.runtimeServiceNames], yaml, projectDir, { removeVolumes: true, timeoutMs: 12e4 });
3069
+ if (started !== 0) {
3070
+ try {
3071
+ await compose(["logs", "--no-color"], yaml, projectDir, { removeVolumes: true });
3072
+ } catch (error) {
3073
+ console.warn("Could not collect startup logs", error);
3074
+ }
3075
+ return started;
3076
+ }
3077
+ const waited = await compose(["wait", main], yaml, projectDir, { removeVolumes: true });
3078
+ const status = inspectExit(yaml, projectDir, main) ?? (waited === 0 ? 1 : waited);
3079
+ try {
3080
+ await compose(["logs", "--no-color", main], yaml, projectDir, { removeVolumes: true });
3081
+ } catch (error) {
3082
+ console.warn("Could not collect unit logs", error);
3083
+ }
3084
+ return status;
3085
+ }
3086
+ async function runTestUnit(options, adapters = {}) {
3087
+ const compiled = compileServiceComposition("test", options.projectDir, { validationMode: Boolean(options.dryRun) }), yaml = stringify(compiled.compose);
3088
+ const main = compiled.mainServiceNames.get(nodeId(void 0, "main"));
3089
+ if (options.debug) console.log(redactYamlSecrets(yaml));
3090
+ if (options.dryRun) return 0;
3091
+ await (adapters.checkPorts ?? checkHostPortCollisions)(extractHostPorts(yaml));
3092
+ await (adapters.teardown ?? teardownCompose)(yaml, options.projectDir, { removeVolumes: true, silent: true });
3093
+ persistHostPortAllocations(options.projectDir, compiled.allocations);
3094
+ writeRunState(options.projectDir, { projectName: compiled.projectName, stage: "test-unit", configStage: "test", workflow: "test", composition: "service", projectDir: options.projectDir, runtimeServiceNames: compiled.runtimeServiceNames, testerServiceNames: [], allocatedEndpointKeys: [...compiled.allocations.keys()] });
3095
+ const compose = adapters.compose ?? runCompose;
3096
+ const execute = compiled.runtimeServiceNames.length === 1 ? () => compose(["up", "--build", "--abort-on-container-exit", "--exit-code-from", main, main], yaml, options.projectDir, { removeVolumes: true }) : () => runUnitWithLocalModules(compiled, yaml, main, options.projectDir, compose, adapters.inspectExit ?? inspectRunnerExit);
3097
+ return runWithCleanup(execute, async () => {
3098
+ await (adapters.teardown ?? teardownCompose)(yaml, options.projectDir, { removeVolumes: true });
3099
+ removeHostPortAllocations(options.projectDir, [...compiled.allocations.keys()]);
3100
+ clearRunState(options.projectDir);
3101
+ });
3102
+ }
3067
3103
  async function runTestE2e(options, adapters = {}) {
3068
3104
  const compiled = compileServiceComposition("e2e", options.projectDir, { validationMode: Boolean(options.dryRun) }), yaml = stringify(compiled.compose);
3069
3105
  if (options.debug) console.log(redactYamlSecrets(yaml));