@solid-stack/builder 3.0.0 → 3.1.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,13 +1,15 @@
1
1
  # Solid Stack Builder V3
2
2
 
3
- Builder 3.0.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.
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`.
4
4
 
5
- The source package declares version 3.0.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.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.
6
6
 
7
7
  [Builder V3 documentation](docs/README.md)
8
8
 
9
9
  [Upgrade from Builder 2.2.0](docs/migration/v2.2-to-v3.0.md)
10
10
 
11
+ [Upgrade from Builder 3.0.0](docs/migration/v3.0-to-v3.1.md)
12
+
11
13
  ## Tests
12
14
 
13
15
  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`.
package/dist/bin.js CHANGED
@@ -55,6 +55,7 @@ var AUTO_PORT_SCAN_START = 2e4;
55
55
  var identifier = z.string().regex(BUILDER_IDENTIFIER_PATTERN);
56
56
  var nonblank = z.string().min(1).refine((value) => value.trim().length > 0, "must not be blank");
57
57
  var env = z.record(z.string(), z.string());
58
+ var buildArgs = z.record(z.string(), z.string());
58
59
  var port = z.number().int().min(1).max(65535);
59
60
  var publicPort = z.union([port, z.literal("AUTO")]);
60
61
  var requisite = z.enum(["requirement", "dependency", "prerequisite"]);
@@ -62,10 +63,10 @@ var requisites = z.record(identifier, requisite);
62
63
  var requisiteOverlay = z.record(identifier, z.union([requisite, z.literal(false)]));
63
64
  var mainEndpointSchema = z.object({ port, publicPort: publicPort.optional(), primary: z.boolean().optional(), scheme: z.string().regex(ENDPOINT_SCHEME_PATTERN).optional() }).strict();
64
65
  var serviceEndpointSchema = mainEndpointSchema.extend({ service: nonblank }).strict();
65
- var mainServiceSchema = z.object({ env: env.optional(), endpoints: z.record(identifier, mainEndpointSchema).optional(), requisites: requisites.optional(), "override-compose": nonblank.optional() }).strict();
66
+ var mainServiceSchema = z.object({ env: env.optional(), buildArgs: buildArgs.optional(), endpoints: z.record(identifier, mainEndpointSchema).optional(), requisites: requisites.optional(), "override-compose": nonblank.optional() }).strict();
66
67
  var testerServiceSchema = z.object({ compose: nonblank, service: nonblank, env: env.optional() }).strict();
67
68
  var ordinaryServiceSchema = z.object({ compose: nonblank, service: nonblank.optional(), env: env.optional(), endpoints: z.record(identifier, serviceEndpointSchema).optional(), requisites: requisites.optional() }).strict().refine((value) => Boolean(value.service) || Boolean(value.endpoints && Object.keys(value.endpoints).length), "endpoint-less service requires service");
68
- var mainOverlaySchema = z.object({ env: env.optional(), endpoints: z.record(identifier, mainEndpointSchema.partial().strict()).optional(), requisites: requisiteOverlay.optional(), "override-compose": nonblank.optional() }).strict();
69
+ var mainOverlaySchema = z.object({ env: env.optional(), buildArgs: buildArgs.optional(), endpoints: z.record(identifier, mainEndpointSchema.partial().strict()).optional(), requisites: requisiteOverlay.optional(), "override-compose": nonblank.optional() }).strict();
69
70
  var testerOverlaySchema = testerServiceSchema.partial().strict();
70
71
  var ordinaryOverlaySchema = z.object({ compose: nonblank.optional(), service: nonblank.optional(), env: env.optional(), endpoints: z.record(identifier, serviceEndpointSchema.partial().strict()).optional(), requisites: requisiteOverlay.optional() }).strict();
71
72
  var buildServicesSchema = z.record(identifier, z.unknown()).superRefine((value, context) => {
@@ -407,6 +408,7 @@ function resolveBuildStage(build, stage2, sourceFile) {
407
408
  const services2 = structuredClone(build.services);
408
409
  const origins = /* @__PURE__ */ new Map();
409
410
  const envOrigins = /* @__PURE__ */ new Map();
411
+ const buildArgsOrigins = /* @__PURE__ */ new Map();
410
412
  const requisiteOrigins = /* @__PURE__ */ new Map();
411
413
  const layers = [];
412
414
  const deletedRequisiteTargets = [];
@@ -417,6 +419,9 @@ function resolveBuildStage(build, stage2, sourceFile) {
417
419
  const env2 = envOrigins.get(name) ?? /* @__PURE__ */ new Map();
418
420
  for (const key of Object.keys(entry.env ?? {})) env2.set(key, originFor(sourceFile, `${where}.env.${key}`, layer));
419
421
  envOrigins.set(name, env2);
422
+ 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));
424
+ buildArgsOrigins.set(name, args);
420
425
  const edges = requisiteOrigins.get(name) ?? /* @__PURE__ */ new Map();
421
426
  for (const [key, value] of Object.entries(entry.requisites ?? {})) {
422
427
  if (value === false) edges.delete(key);
@@ -460,11 +465,12 @@ function resolveBuildStage(build, stage2, sourceFile) {
460
465
  if (primary?.service && value.service !== primary.service) fail(sourceFile, stage2, `${originPath}.service`, "top-level service must equal primary endpoint owner", value.service);
461
466
  }
462
467
  value.env ??= {};
468
+ if (name === "main") value.buildArgs ??= {};
463
469
  value.endpoints ??= {};
464
470
  value.requisites ??= {};
465
471
  value.kind = name === "main" ? "main" : "ordinary";
466
472
  }
467
- return { name: build.name, services: services2, layers, origins, envOrigins, requisiteOrigins, sourceFile, projectDir: path.dirname(sourceFile) };
473
+ return { name: build.name, services: services2, layers, origins, envOrigins, buildArgsOrigins, requisiteOrigins, sourceFile, projectDir: path.dirname(sourceFile) };
468
474
  }
469
475
  function normalizeProjectName(name, projectDir) {
470
476
  let normalized = name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^[-_]+/, "").replace(/[-_]+$/, "");
@@ -877,6 +883,34 @@ function normalizeComposeEnvironment(value, context) {
877
883
  }
878
884
  return result;
879
885
  }
886
+ function normalizeComposeBuildArgs(value, context, sourceFile) {
887
+ const result = {};
888
+ if (value == null) return result;
889
+ const fail4 = (configPath, reason, item) => {
890
+ throw new ConfigError({ ...sourceFile ? { sourceFile } : {}, configPath, value: item, reason });
891
+ };
892
+ if (Array.isArray(value)) {
893
+ for (const item of value) {
894
+ if (typeof item !== "string") fail4(context, "Compose build arg entries must be strings", item);
895
+ const at = item.indexOf("=");
896
+ const key = at < 0 ? item : item.slice(0, at);
897
+ if (!key) fail4(context, "Compose build arg key must not be empty", item);
898
+ result[key] = at < 0 ? "" : item.slice(at + 1);
899
+ }
900
+ return result;
901
+ }
902
+ if (typeof value !== "object") fail4(context, "Compose build args must be a map or list", value);
903
+ for (const [key, val] of Object.entries(value)) {
904
+ if (!key) fail4(context, "Compose build arg key must not be empty", key);
905
+ if (val === null || val === void 0) {
906
+ result[key] = "";
907
+ continue;
908
+ }
909
+ if (typeof val === "object") fail4(`${context}.${key}`, "Compose build arg value must be scalar", val);
910
+ result[key] = String(val);
911
+ }
912
+ return result;
913
+ }
880
914
 
881
915
  // src/core/composition/composeNetworks.ts
882
916
  function normalizeNetworks(value) {
@@ -1415,6 +1449,7 @@ function validateAndPrepareMainOverride(document, context) {
1415
1449
  fail4("services.main.build.context", "override cannot change main build context", build.context);
1416
1450
  }
1417
1451
  }
1452
+ if (build.args !== void 0) build.args = normalizeComposeBuildArgs(build.args, "services.main.build.args", context.file);
1418
1453
  }
1419
1454
  const env2 = normalizeComposeEnvironment(main.environment, "services.main.environment");
1420
1455
  for (const k of ["EXEC_MODE", "INFRA_MODE"]) if (k in env2) fail4(`services.main.environment.${k}`, "override cannot set Builder-owned environment");
@@ -1624,7 +1659,7 @@ function makeGraph(input) {
1624
1659
  for (const [name, declaration] of Object.entries(build.services)) {
1625
1660
  if (name === "tester") continue;
1626
1661
  const id = nodeId(root, name), origin = copyOrigin(build.origins.get(name), root);
1627
- nodes.set(id, { id, kind: name === "main" ? "main" : "ordinary", projectDir: build.projectDir, sourceService: name, ...root ? { meshRoot: root } : {}, declaration, envLayers: [], origin, envOrigins: new Map([...build.envOrigins.get(name) ?? []].map(([key, value]) => [key, copyOrigin(value, root)])), requisiteOrigins: new Map([...build.requisiteOrigins.get(name) ?? []].map(([key, value]) => [key, copyOrigin(value, root)])) });
1662
+ nodes.set(id, { id, kind: name === "main" ? "main" : "ordinary", projectDir: build.projectDir, sourceService: name, ...root ? { meshRoot: root } : {}, declaration, envLayers: [], origin, envOrigins: new Map([...build.envOrigins.get(name) ?? []].map(([key, value]) => [key, copyOrigin(value, root)])), buildArgsOrigins: new Map([...build.buildArgsOrigins.get(name) ?? []].map(([key, value]) => [key, copyOrigin(value, root)])), requisiteOrigins: new Map([...build.requisiteOrigins.get(name) ?? []].map(([key, value]) => [key, copyOrigin(value, root)])) });
1628
1663
  }
1629
1664
  }
1630
1665
  input.mesh?.tester ?? input.instances.get("")?.services.tester;
@@ -1691,6 +1726,22 @@ function resolveJsonEnv(node, graph, endpoints, stage2, composition, shadowed) {
1691
1726
  function validateJsonEnv(node, graph, endpoints, stage2, composition, shadowed) {
1692
1727
  resolveJsonEnv(node, graph, endpoints, stage2, composition, shadowed);
1693
1728
  }
1729
+ function resolveJsonBuildArgs(node, graph, endpoints, stage2, composition, shadowed) {
1730
+ const output = {};
1731
+ const main = node.declaration;
1732
+ for (const [key, value] of Object.entries(main.buildArgs)) {
1733
+ if (shadowed.has(key)) continue;
1734
+ const origin = node.buildArgsOrigins.get(key) ?? node.origin;
1735
+ output[key] = interpolateBuilderReferences(value, { graph, endpoints, consumer: node.id, origin, stage: stage2, composition }).replace(/\$/g, "$$$$");
1736
+ }
1737
+ return output;
1738
+ }
1739
+ function assertNoReservedBuildArgs(args, origin, stage2, composition) {
1740
+ for (const key of Object.keys(args)) if (key.startsWith("BUILDER_")) {
1741
+ const where = origin(key);
1742
+ throw new ConfigError({ sourceFile: where.sourceFile, configPath: where.configPath, stage: stage2, composition, reason: "BUILDER_ build arguments are reserved for Builder", value: key });
1743
+ }
1744
+ }
1694
1745
  function validateReserved(node, keys, stage2, composition) {
1695
1746
  for (const key of keys) if (key in node.declaration.env) {
1696
1747
  const origin = node.envOrigins.get(key) ?? node.origin;
@@ -1702,6 +1753,7 @@ function compileGraphComposition(input) {
1702
1753
  const projectName = deriveProjectName(input.name, input.stage, input.projectDir), compose = { name: projectName, services: {}, networks: { builder: { driver: "bridge" } } };
1703
1754
  const mainServiceNames = /* @__PURE__ */ new Map(), modules = /* @__PURE__ */ new Map(), runtimeServiceNames = [], deferredHealthChecks = [];
1704
1755
  const mainOverrideEnv = /* @__PURE__ */ new Map();
1756
+ const mainOverrideBuildArgs = /* @__PURE__ */ new Map();
1705
1757
  for (const [id, node] of [...graph.nodes].sort(([a], [b]) => a.localeCompare(b))) {
1706
1758
  if (node.kind === "main") {
1707
1759
  resolveApplicationDockerfile(node.projectDir, "Dockerfile", input.stage);
@@ -1724,11 +1776,11 @@ function compileGraphComposition(input) {
1724
1776
  validateMaterializedComposeFiles(raw, file, input.stage, { baseDir: selected.origin.projectDir, composition: input.composition });
1725
1777
  for (const section of ["volumes", "networks", "configs", "secrets"]) if (prepared.resources[section]) mergeDocument(compose, { services: {}, [section]: prepared.resources[section] }, selected.origin, input.stage);
1726
1778
  mainOverrideEnv.set(id, normalizeComposeEnvironment(prepared.main.environment, `${selected.origin.configPath}.services.main.environment`));
1779
+ if (prepared.main.build && typeof prepared.main.build === "object" && Object.hasOwn(prepared.main.build, "args")) mainOverrideBuildArgs.set(id, normalizeComposeBuildArgs(prepared.main.build.args, "services.main.build.args", file));
1727
1780
  const overlay = { ...prepared.main };
1728
1781
  delete overlay.environment;
1729
1782
  delete overlay.build;
1730
1783
  Object.assign(service, mergeMainOverride(service, overlay));
1731
- if (prepared.main.build && typeof prepared.main.build === "object") Object.assign(service.build, { args: prepared.main.build.args });
1732
1784
  }
1733
1785
  withBuilderNetwork(service);
1734
1786
  compose.services[serviceName] = service;
@@ -1790,6 +1842,13 @@ function compileGraphComposition(input) {
1790
1842
  const override = mainOverrideEnv.get(id) ?? {};
1791
1843
  const shadowed = new Set(node.kind === "main" ? Object.keys(override).filter((key) => node.envOrigins.get(key)?.scope !== "mesh") : []);
1792
1844
  validateJsonEnv(node, graph, endpoints, input.stage, input.composition, shadowed);
1845
+ if (node.kind === "main") {
1846
+ const args = node.declaration.buildArgs, overrideArgs = mainOverrideBuildArgs.get(id) ?? {};
1847
+ assertNoReservedBuildArgs(args, (key) => node.buildArgsOrigins.get(key) ?? node.origin, input.stage, input.composition);
1848
+ const overrideFile = selectedOverride(input.instances.get(node.meshRoot ?? ""), "main");
1849
+ assertNoReservedBuildArgs(overrideArgs, (key) => ({ sourceFile: overrideFile?.origin.sourceFile ?? node.origin.sourceFile, configPath: `services.main.build.args.${key}`, projectDir: node.projectDir, scope: node.origin.scope, layer: node.origin.layer }), input.stage, input.composition);
1850
+ resolveJsonBuildArgs(node, graph, endpoints, input.stage, input.composition, new Set(Object.keys(overrideArgs).filter((key) => node.buildArgsOrigins.get(key)?.scope !== "mesh")));
1851
+ }
1793
1852
  }
1794
1853
  const tester = input.mesh?.tester ?? input.instances.get("")?.services.tester;
1795
1854
  const testerOrigin = input.mesh ? { sourceFile: input.mesh.sourceFile, configPath: "services.tester", projectDir: input.projectDir, scope: "mesh", layer: "base" } : { sourceFile: input.instances.get("").sourceFile, configPath: "services.tester", projectDir: input.projectDir, scope: "build", layer: "base" };
@@ -1822,6 +1881,12 @@ function compileGraphComposition(input) {
1822
1881
  const sourceEnv = Object.fromEntries(Object.entries(buildEnv).filter(([key]) => node.envOrigins.get(key)?.scope !== "mesh"));
1823
1882
  const meshEnv = Object.fromEntries(Object.entries(buildEnv).filter(([key]) => node.envOrigins.get(key)?.scope === "mesh"));
1824
1883
  service.environment = { ...sourceEnv, ...override, ...meshEnv, EXEC_MODE: profile.execMode, INFRA_MODE: profile.infraMode, ...primary ? { PORT: String(primary.port) } : {} };
1884
+ const overrideArgs = mainOverrideBuildArgs.get(id) ?? {}, shadowedArgs = new Set(Object.keys(overrideArgs).filter((key) => node.buildArgsOrigins.get(key)?.scope !== "mesh"));
1885
+ const resolvedArgs = resolveJsonBuildArgs(node, graph, endpoints, input.stage, input.composition, shadowedArgs);
1886
+ const sourceArgs = Object.fromEntries(Object.entries(resolvedArgs).filter(([key]) => node.buildArgsOrigins.get(key)?.scope !== "mesh"));
1887
+ const meshArgs = Object.fromEntries(Object.entries(resolvedArgs).filter(([key]) => node.buildArgsOrigins.get(key)?.scope === "mesh"));
1888
+ const effectiveArgs = { ...sourceArgs, ...overrideArgs, ...meshArgs };
1889
+ if (Object.keys(effectiveArgs).length || mainOverrideBuildArgs.has(id)) service.build.args = effectiveArgs;
1825
1890
  } else {
1826
1891
  const module = modules.get(id);
1827
1892
  for (const name of module.serviceNames) {
@@ -2110,6 +2175,9 @@ function applyMeshExtends(mesh, builds, stage2) {
2110
2175
  const env2 = build.envOrigins.get(name) ?? /* @__PURE__ */ new Map();
2111
2176
  for (const key of Object.keys(patch.env ?? {})) env2.set(key, { ...origin, configPath: `${origin.configPath}.env.${key}` });
2112
2177
  build.envOrigins.set(name, env2);
2178
+ const args = build.buildArgsOrigins.get(name) ?? /* @__PURE__ */ new Map();
2179
+ for (const key of Object.keys(patch.buildArgs ?? {})) args.set(key, { ...origin, configPath: `${origin.configPath}.buildArgs.${key}` });
2180
+ build.buildArgsOrigins.set(name, args);
2113
2181
  const edges = build.requisiteOrigins.get(name) ?? /* @__PURE__ */ new Map();
2114
2182
  for (const [target, kind] of Object.entries(patch.requisites ?? {})) {
2115
2183
  const canonical = target.startsWith("source.") ? target.slice(7) : `@mesh:${target}`;