@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 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 `env.dev`, `env.prod`, `env.test`, and `env.e2e` (without a leading dot). These snapshots do not replace the `.env.<stage>` input files automatically. 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.
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 `env.e2e` reflects that app environment plus any E2E app overrides; it does not merge the tester's `.env.e2e` into the app.
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 (!provideMap[dep.name] && !(mesh.dependencies && mesh.dependencies[dep.name]) && dep.port) {
1170
- claimPort(dep.port, `local dependency "${dep.name}" of service "${serviceName}"`);
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
- buildArgs[k] = interpolateEnvTemplates(v, `Service build.json: ${serviceName}`);
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
- if (dep.port) {
1487
- const portMapping = String(dep.port).includes(":") ? String(dep.port) : `${dep.port}:3000`;
1488
- resolvedMock.ports = [...resolvedMock.ports || [], portMapping];
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
- if (dep.port) {
2877
- let targetSvc = dep.serviceName && yml.services[dep.serviceName] ? dep.serviceName : dep.name;
2878
- if (!yml.services[targetSvc]) {
2879
- targetSvc = Object.keys(yml.services).find((k) => k !== "app" && k !== "tester") || targetSvc;
2880
- }
2881
- if (yml.services[targetSvc]) {
2882
- const portMapping = String(dep.port).includes(":") ? String(dep.port) : `${dep.port}:3000`;
2883
- yml.services[targetSvc].ports = [...yml.services[targetSvc].ports || [], portMapping];
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, `env.${snapshot.stage}`);
3808
+ let filename = path13.join(projectDir, `.env.${snapshot.stage}`);
3701
3809
  while (true) {
3702
3810
  let overwrite = false;
3703
3811
  if (existsSync(filename)) {