@solid-stack/builder 1.1.7 → 1.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 +35 -2
- package/dist/bin.js +134 -26
- package/dist/bin.js.map +1 -1
- package/dist/core/buildSchema.d.ts +9 -0
- package/dist/core/buildSchema.d.ts.map +1 -1
- package/dist/core/compileEnvironment.d.ts.map +1 -1
- package/dist/core/mesh/compileMeshEnvironment.d.ts.map +1 -1
- package/dist/index.js +134 -62
- package/dist/index.js.map +1 -1
- package/dist/types/index.d.ts +4 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/utils/assertUniqueHostPortMappings.d.ts +3 -0
- package/dist/utils/assertUniqueHostPortMappings.d.ts.map +1 -0
- package/dist/utils/dependencyPorts.d.ts +10 -0
- package/dist/utils/dependencyPorts.d.ts.map +1 -0
- package/dist/utils/extractBuildDeps.d.ts.map +1 -1
- package/package.json +1 -1
- package/schemas/build-schema.json +8 -0
package/README.md
CHANGED
|
@@ -112,9 +112,9 @@ builder service export env e2e -C ./services/backend
|
|
|
112
112
|
builder service export env dev --full
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
The default output names are
|
|
115
|
+
The default output names are `.env.dev`, `.env.prod`, `.env.test`, and `.env.e2e`. These are also the stage input files used by Builder, so existing files require explicit confirmation before replacement. If an output file exists, Builder asks whether to overwrite it. Declining prompts for a new filename relative to the service directory; an existing replacement filename also requires confirmation. Existing files require an interactive terminal.
|
|
116
116
|
|
|
117
|
-
Exports use the same stage compilation as service startup, including Compose environment files, overrides, Builder URL templates, and `build.json.envOverrides`. All requested stages are compiled before any files are written. Only the application service's resolved runtime environment is exported, not build arguments, dependencies, or tester settings. E2E runs the application using the production configuration, so
|
|
117
|
+
Exports use the same stage compilation as service startup, including Compose environment files, overrides, Builder URL templates, and `build.json.envOverrides`. All requested stages are compiled before any files are written. Only the application service's resolved runtime environment is exported, not build arguments, dependencies, or tester settings. E2E runs the application using the production configuration, so `.env.e2e` reflects that app environment plus any E2E app overrides; it does not merge the tester's `.env.e2e` into the app.
|
|
118
118
|
|
|
119
119
|
The command requires Docker Compose 2.24 or newer, but does not require a running Docker daemon or start/build containers. Image-only `ENV` defaults and values added by application startup code cannot be determined by configuration simulation and are outside the export. New files use owner-only permissions and contain the actual values. Values follow [Compose dotenv quoting rules](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) to preserve literal dollars and multiline strings.
|
|
120
120
|
|
|
@@ -164,6 +164,39 @@ Each service configures its dependencies and overrides via `build.json` in its p
|
|
|
164
164
|
}
|
|
165
165
|
```
|
|
166
166
|
|
|
167
|
+
|
|
168
|
+
### Dependency host ports
|
|
169
|
+
|
|
170
|
+
`dependencies.<name>.port` exposes the primary local interface. A number such as
|
|
171
|
+
`9000` maps host port 9000 to container port 3000. An explicit value such as
|
|
172
|
+
`"9000:8080"` maps those ports exactly.
|
|
173
|
+
|
|
174
|
+
`dependencies.<name>.ports` exposes additional developer interfaces. Each entry
|
|
175
|
+
must be an explicit `HOST_PORT:CONTAINER_PORT` mapping:
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"dependencies": {
|
|
180
|
+
"tooling": {
|
|
181
|
+
"path": "./tooling.compose.yml",
|
|
182
|
+
"service": "tooling",
|
|
183
|
+
"port": "4080:4000",
|
|
184
|
+
"ports": ["8080:8080", "9150:9150"]
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Auxiliary ports affect only host exposure; they do not change `.network_url` or
|
|
191
|
+
`.public_url` template values. Builder uses only ports declared in `build.json`
|
|
192
|
+
for local dependency host exposure, even if the mock Compose file declares ports.
|
|
193
|
+
This keeps the application service contract predictable while allowing explicit
|
|
194
|
+
interfaces for developer tooling. Static host port collisions fail compilation.
|
|
195
|
+
|
|
196
|
+
In mesh compilation, runtime environment and build args use this precedence:
|
|
197
|
+
Builder defaults, then service stage overrides, then service `build.json.envOverrides`,
|
|
198
|
+
then mesh service `envOverrides`.
|
|
199
|
+
|
|
167
200
|
---
|
|
168
201
|
|
|
169
202
|
## 💻 Programmatic Usage
|
package/dist/bin.js
CHANGED
|
@@ -832,6 +832,114 @@ Examples:
|
|
|
832
832
|
}
|
|
833
833
|
});
|
|
834
834
|
};
|
|
835
|
+
function assertUniqueHostPortMappings(yamlConfig) {
|
|
836
|
+
const parsed = parse(yamlConfig);
|
|
837
|
+
const owners = /* @__PURE__ */ new Map();
|
|
838
|
+
for (const [serviceName, service] of Object.entries(parsed?.services ?? {})) {
|
|
839
|
+
for (const port of service?.ports ?? []) {
|
|
840
|
+
let hostPort = null;
|
|
841
|
+
if (typeof port === "string") {
|
|
842
|
+
const parts = port.split(":");
|
|
843
|
+
if (parts.length === 2) hostPort = Number(parts[0]);
|
|
844
|
+
if (parts.length === 3) hostPort = Number(parts[1]);
|
|
845
|
+
} else if (port && typeof port === "object" && "published" in port) {
|
|
846
|
+
hostPort = Number(port.published);
|
|
847
|
+
}
|
|
848
|
+
if (!hostPort || !Number.isInteger(hostPort)) continue;
|
|
849
|
+
const existing = owners.get(hostPort);
|
|
850
|
+
if (existing) {
|
|
851
|
+
throw new ScriptError(
|
|
852
|
+
`Port Collision Detected: Host port ${hostPort} is requested by both "${existing}" and "${serviceName}".`
|
|
853
|
+
);
|
|
854
|
+
}
|
|
855
|
+
owners.set(hostPort, serviceName);
|
|
856
|
+
}
|
|
857
|
+
}
|
|
858
|
+
}
|
|
859
|
+
|
|
860
|
+
// src/utils/dependencyPorts.ts
|
|
861
|
+
var EXPLICIT_PORT_MAPPING = /^([1-9]\d{0,4}):([1-9]\d{0,4})$/;
|
|
862
|
+
function assertValidPort(port, label) {
|
|
863
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535) {
|
|
864
|
+
throw new ScriptError(`${label} must be between 1 and 65535.`);
|
|
865
|
+
}
|
|
866
|
+
}
|
|
867
|
+
function parseExplicitPortMapping(value, context = "Dependency port") {
|
|
868
|
+
const match = EXPLICIT_PORT_MAPPING.exec(value.trim());
|
|
869
|
+
if (!match) {
|
|
870
|
+
throw new ScriptError(`${context} "${value}" must use "HOST_PORT:CONTAINER_PORT".`);
|
|
871
|
+
}
|
|
872
|
+
const hostPort = Number(match[1]);
|
|
873
|
+
const containerPort = Number(match[2]);
|
|
874
|
+
assertValidPort(hostPort, `${context} host port`);
|
|
875
|
+
assertValidPort(containerPort, `${context} container port`);
|
|
876
|
+
return { raw: `${hostPort}:${containerPort}`, hostPort, containerPort };
|
|
877
|
+
}
|
|
878
|
+
function normalizePrimaryDependencyPort(value, context = "Dependency port") {
|
|
879
|
+
if (typeof value === "number") {
|
|
880
|
+
assertValidPort(value, `${context} host port`);
|
|
881
|
+
return { raw: `${value}:3000`, hostPort: value, containerPort: 3e3 };
|
|
882
|
+
}
|
|
883
|
+
const trimmed = value.trim();
|
|
884
|
+
if (/^[1-9]\d{0,4}$/.test(trimmed)) {
|
|
885
|
+
const hostPort = Number(trimmed);
|
|
886
|
+
assertValidPort(hostPort, `${context} host port`);
|
|
887
|
+
return { raw: `${hostPort}:3000`, hostPort, containerPort: 3e3 };
|
|
888
|
+
}
|
|
889
|
+
return parseExplicitPortMapping(trimmed, context);
|
|
890
|
+
}
|
|
891
|
+
function getDependencyPortMappings(dependency, context = "Dependency") {
|
|
892
|
+
const mappings = [];
|
|
893
|
+
if (dependency.port !== void 0) {
|
|
894
|
+
mappings.push(normalizePrimaryDependencyPort(dependency.port, `${context} primary port`));
|
|
895
|
+
}
|
|
896
|
+
for (const value of dependency.ports ?? []) {
|
|
897
|
+
mappings.push(parseExplicitPortMapping(value, `${context} auxiliary port`));
|
|
898
|
+
}
|
|
899
|
+
return [...new Map(mappings.map((mapping) => [mapping.raw, mapping])).values()];
|
|
900
|
+
}
|
|
901
|
+
var buildPolicyConfigSchema = z.object({
|
|
902
|
+
dockerfile: z.string().optional().describe("Relative path to policy directory for Dockerfile checks"),
|
|
903
|
+
compose: z.string().optional().describe("Relative path to policy directory for Compose contract checks")
|
|
904
|
+
}).strict().describe("Policy configurations for infra/contract verification");
|
|
905
|
+
var auxiliaryPortMappingSchema = z.string().regex(/^([1-9]\d{0,4}):([1-9]\d{0,4})$/, 'Must use "HOST_PORT:CONTAINER_PORT"').refine((value) => value.split(":").every((part) => Number(part) <= 65535), {
|
|
906
|
+
message: "Host and container ports must be between 1 and 65535"
|
|
907
|
+
});
|
|
908
|
+
var buildDependencySchema = z.object({
|
|
909
|
+
path: z.string({ required_error: 'Dependency "path" is required' }).describe("Relative path to mock Docker Compose file"),
|
|
910
|
+
service: z.string().optional().describe("Target service name in the mock compose file"),
|
|
911
|
+
port: z.union([z.number(), z.string()]).optional().describe("Host port to map to this dependency locally"),
|
|
912
|
+
ports: z.array(auxiliaryPortMappingSchema).optional().describe("Additional explicit HOST_PORT:CONTAINER_PORT mappings for local dependency tooling")
|
|
913
|
+
}).strict().describe("Service dependency specification");
|
|
914
|
+
var buildOverrideSchema = z.object({
|
|
915
|
+
path: z.string({ required_error: 'Override "path" is required' }).describe("Relative path to the environment stage override file")
|
|
916
|
+
}).strict().describe("Environment override specification");
|
|
917
|
+
var buildTesterSchema = z.object({
|
|
918
|
+
envOverrides: z.record(z.string(), z.string()).optional().describe(
|
|
919
|
+
"Environment variable overrides for the individual E2E tester with URL templating"
|
|
920
|
+
)
|
|
921
|
+
}).strict().describe("E2E tester configuration");
|
|
922
|
+
z.object({
|
|
923
|
+
$schema: z.string().optional().describe("JSON Schema URL or relative path"),
|
|
924
|
+
name: z.string().optional().describe("Service project name"),
|
|
925
|
+
dockerfile: z.string().optional().describe("Relative path to the Dockerfile (defaults to 'Dockerfile')"),
|
|
926
|
+
port: z.union([z.number(), z.string()]).optional().describe(
|
|
927
|
+
"Host port exposed by this service when listening publicly"
|
|
928
|
+
),
|
|
929
|
+
policy: buildPolicyConfigSchema.optional(),
|
|
930
|
+
policies: buildPolicyConfigSchema.optional(),
|
|
931
|
+
composeFiles: z.array(z.string()).optional().describe("Additional compose files to merge"),
|
|
932
|
+
dependencies: z.record(z.string(), buildDependencySchema).optional().describe("Service dependencies and mocks"),
|
|
933
|
+
envOverrides: z.record(z.string(), z.string()).optional().describe("Environment variable overrides for the app service with URL templating"),
|
|
934
|
+
overrides: z.record(
|
|
935
|
+
z.enum(["dev", "prod", "test", "e2e"]),
|
|
936
|
+
buildOverrideSchema
|
|
937
|
+
).optional().describe("Stage overrides (dev, prod, test, e2e)"),
|
|
938
|
+
services: z.record(z.string(), z.any()).optional().describe("Additional Docker Compose service overrides"),
|
|
939
|
+
tester: buildTesterSchema.optional()
|
|
940
|
+
}).strict().describe("Solid Stack service build and deployment configuration");
|
|
941
|
+
|
|
942
|
+
// src/utils/extractBuildDeps.ts
|
|
835
943
|
var extractBuildDeps = (buildJson, projectDir = process.cwd()) => {
|
|
836
944
|
if (!buildJson || typeof buildJson !== "object") {
|
|
837
945
|
return [];
|
|
@@ -840,14 +948,7 @@ var extractBuildDeps = (buildJson, projectDir = process.cwd()) => {
|
|
|
840
948
|
return [];
|
|
841
949
|
}
|
|
842
950
|
const schema = z.object({
|
|
843
|
-
dependencies: z.record(
|
|
844
|
-
z.string(),
|
|
845
|
-
z.object({
|
|
846
|
-
path: z.string(),
|
|
847
|
-
service: z.string().optional(),
|
|
848
|
-
port: z.union([z.number(), z.string()]).optional()
|
|
849
|
-
})
|
|
850
|
-
)
|
|
951
|
+
dependencies: z.record(z.string(), buildDependencySchema)
|
|
851
952
|
});
|
|
852
953
|
const result = schema.safeParse(buildJson);
|
|
853
954
|
if (!result.success) {
|
|
@@ -863,7 +964,8 @@ var extractBuildDeps = (buildJson, projectDir = process.cwd()) => {
|
|
|
863
964
|
path: path13.resolve(projectDir, service.path),
|
|
864
965
|
name,
|
|
865
966
|
serviceName: service.service,
|
|
866
|
-
port: service.port
|
|
967
|
+
port: service.port,
|
|
968
|
+
ports: service.ports
|
|
867
969
|
};
|
|
868
970
|
}
|
|
869
971
|
);
|
|
@@ -1166,8 +1268,9 @@ function compileMeshEnvironment(mode, rawMeshDir = process.cwd(), options = {})
|
|
|
1166
1268
|
...serviceConfig.provideDependency || {}
|
|
1167
1269
|
};
|
|
1168
1270
|
for (const dep of serviceDeps) {
|
|
1169
|
-
if (
|
|
1170
|
-
|
|
1271
|
+
if (provideMap[dep.name] || mesh.dependencies?.[dep.name]) continue;
|
|
1272
|
+
for (const mapping of getDependencyPortMappings(dep, `Local dependency "${dep.name}" of service "${serviceName}"`)) {
|
|
1273
|
+
claimPort(mapping.raw, `local dependency "${dep.name}" of service "${serviceName}"`);
|
|
1171
1274
|
}
|
|
1172
1275
|
}
|
|
1173
1276
|
const hostPort = publicPort ? String(publicPort).includes(":") ? String(publicPort).split(":")[0] : String(publicPort) : null;
|
|
@@ -1301,7 +1404,9 @@ function compileMeshEnvironment(mode, rawMeshDir = process.cwd(), options = {})
|
|
|
1301
1404
|
}
|
|
1302
1405
|
if (serviceBuildJson.envOverrides) {
|
|
1303
1406
|
for (const [k, v] of Object.entries(serviceBuildJson.envOverrides)) {
|
|
1304
|
-
|
|
1407
|
+
const interpolated = interpolateEnvTemplates(v, `Service build.json: ${serviceName}`);
|
|
1408
|
+
environment[k] = interpolated;
|
|
1409
|
+
buildArgs[k] = interpolated;
|
|
1305
1410
|
}
|
|
1306
1411
|
}
|
|
1307
1412
|
if (serviceConfig.envOverrides) {
|
|
@@ -1483,9 +1588,9 @@ function compileMeshEnvironment(mode, rawMeshDir = process.cwd(), options = {})
|
|
|
1483
1588
|
delete resolvedMock.container_name;
|
|
1484
1589
|
normalizeDependsOn(resolvedMock);
|
|
1485
1590
|
applyInternalMockDependsOnMapping(resolvedMock, sidecarMapping);
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
resolvedMock.ports =
|
|
1591
|
+
const portMappings = getDependencyPortMappings(dep, `Local dependency "${depKey}" of service "${serviceName}"`);
|
|
1592
|
+
if (portMappings.length > 0) {
|
|
1593
|
+
resolvedMock.ports = portMappings.map((mapping) => mapping.raw);
|
|
1489
1594
|
}
|
|
1490
1595
|
resolvedMock.networks = {
|
|
1491
1596
|
[`${serviceName}_net`]: {
|
|
@@ -1598,6 +1703,7 @@ function compileMeshEnvironment(mode, rawMeshDir = process.cwd(), options = {})
|
|
|
1598
1703
|
}
|
|
1599
1704
|
}
|
|
1600
1705
|
const generatedYaml = stringify(composeConfig);
|
|
1706
|
+
assertUniqueHostPortMappings(generatedYaml);
|
|
1601
1707
|
if (options.validateWithDocker === false) {
|
|
1602
1708
|
return { yaml: generatedYaml, testerServiceName };
|
|
1603
1709
|
}
|
|
@@ -2871,18 +2977,19 @@ ${explanation}`);
|
|
|
2871
2977
|
}
|
|
2872
2978
|
}
|
|
2873
2979
|
}
|
|
2874
|
-
if (yml.services) {
|
|
2980
|
+
if (yml.services && (environment === "prod" || environment === "e2e" || environment === "dev" && options.full)) {
|
|
2875
2981
|
for (const dep of dependencies) {
|
|
2876
|
-
|
|
2877
|
-
|
|
2878
|
-
|
|
2879
|
-
|
|
2880
|
-
|
|
2881
|
-
|
|
2882
|
-
|
|
2883
|
-
|
|
2884
|
-
}
|
|
2982
|
+
const mappings = getDependencyPortMappings(dep, `Dependency "${dep.name}"`);
|
|
2983
|
+
let targetSvc = dep.serviceName && yml.services[dep.serviceName] ? dep.serviceName : dep.name;
|
|
2984
|
+
if (!yml.services[targetSvc]) {
|
|
2985
|
+
targetSvc = Object.keys(yml.services).find((key) => key !== "app" && key !== "tester") ?? targetSvc;
|
|
2986
|
+
}
|
|
2987
|
+
const service = yml.services[targetSvc];
|
|
2988
|
+
if (!service) {
|
|
2989
|
+
throw new ScriptError(`Dependency "${dep.name}" target service could not be resolved for port injection.`);
|
|
2885
2990
|
}
|
|
2991
|
+
delete service.ports;
|
|
2992
|
+
if (mappings.length > 0) service.ports = mappings.map((mapping) => mapping.raw);
|
|
2886
2993
|
}
|
|
2887
2994
|
}
|
|
2888
2995
|
if (environment === "dev" && options.full && yml.services?.app) {
|
|
@@ -2891,6 +2998,7 @@ ${explanation}`);
|
|
|
2891
2998
|
}
|
|
2892
2999
|
attachName(yml, projectName);
|
|
2893
3000
|
const finalYamlConfig = stringify(yml);
|
|
3001
|
+
assertUniqueHostPortMappings(finalYamlConfig);
|
|
2894
3002
|
return finalYamlConfig;
|
|
2895
3003
|
};
|
|
2896
3004
|
|
|
@@ -3697,7 +3805,7 @@ async function handleExportEnv(rawStage, options = {}) {
|
|
|
3697
3805
|
const files = [];
|
|
3698
3806
|
try {
|
|
3699
3807
|
for (const snapshot of snapshots) {
|
|
3700
|
-
let filename = path13.join(projectDir,
|
|
3808
|
+
let filename = path13.join(projectDir, `.env.${snapshot.stage}`);
|
|
3701
3809
|
while (true) {
|
|
3702
3810
|
let overwrite = false;
|
|
3703
3811
|
if (existsSync(filename)) {
|