@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 +4 -2
- package/dist/bin.js +73 -5
- package/dist/bin.js.map +1 -1
- package/dist/core/buildSchema.d.ts +6 -0
- package/dist/core/buildSchema.d.ts.map +1 -1
- package/dist/core/composition/compileGraphComposition.d.ts.map +1 -1
- package/dist/core/composition/composeEnvironment.d.ts +1 -0
- package/dist/core/composition/composeEnvironment.d.ts.map +1 -1
- package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -1
- package/dist/core/config/resolveBuildStage.d.ts.map +1 -1
- package/dist/core/config/types.d.ts +3 -0
- package/dist/core/config/types.d.ts.map +1 -1
- package/dist/core/mesh/applyMeshExtends.d.ts.map +1 -1
- package/dist/index.js +73 -5
- package/dist/index.js.map +1 -1
- package/dist/types/index.d.ts +3 -0
- package/dist/types/index.d.ts.map +1 -1
- package/package.json +1 -1
- package/schemas/build-schema.json +30 -0
- package/schemas/mesh-schema.json +24 -0
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
# Solid Stack Builder V3
|
|
2
2
|
|
|
3
|
-
Builder 3.
|
|
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.
|
|
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}`;
|