@solid-stack/builder 2.0.3 → 2.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.
Files changed (87) hide show
  1. package/README.md +580 -50
  2. package/dist/bin.js +1060 -767
  3. package/dist/bin.js.map +1 -1
  4. package/dist/commands/mesh/commands/down/handler.d.ts.map +1 -1
  5. package/dist/commands/mesh/commands/up/handler.d.ts.map +1 -1
  6. package/dist/commands/service/commands/export/handler.d.ts.map +1 -1
  7. package/dist/core/composeCleanup.d.ts.map +1 -1
  8. package/dist/core/composition/assertComposeLifecycleAcyclic.d.ts +7 -0
  9. package/dist/core/composition/assertComposeLifecycleAcyclic.d.ts.map +1 -0
  10. package/dist/core/composition/compileServiceComposition.d.ts.map +1 -1
  11. package/dist/core/composition/composeDependsOn.d.ts +3 -1
  12. package/dist/core/composition/composeDependsOn.d.ts.map +1 -1
  13. package/dist/core/composition/composePaths.d.ts +1 -0
  14. package/dist/core/composition/composePaths.d.ts.map +1 -1
  15. package/dist/core/composition/dependencyLifecycle.d.ts.map +1 -1
  16. package/dist/core/composition/mergeAppOverride.d.ts +3 -0
  17. package/dist/core/composition/mergeAppOverride.d.ts.map +1 -0
  18. package/dist/core/composition/namespaceDependencyCompose.d.ts.map +1 -1
  19. package/dist/core/composition/namespaceResourceDefinition.d.ts +3 -0
  20. package/dist/core/composition/namespaceResourceDefinition.d.ts.map +1 -0
  21. package/dist/core/composition/selectAppEnvironmentEntries.d.ts +3 -0
  22. package/dist/core/composition/selectAppEnvironmentEntries.d.ts.map +1 -0
  23. package/dist/core/composition/types.d.ts +16 -4
  24. package/dist/core/composition/types.d.ts.map +1 -1
  25. package/dist/core/composition/validateDependencyCompose.d.ts.map +1 -1
  26. package/dist/core/composition/validateMaterializedComposeBuildInputs.d.ts +4 -0
  27. package/dist/core/composition/validateMaterializedComposeBuildInputs.d.ts.map +1 -0
  28. package/dist/core/composition/validateMaterializedComposeFiles.d.ts +8 -0
  29. package/dist/core/composition/validateMaterializedComposeFiles.d.ts.map +1 -0
  30. package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -1
  31. package/dist/core/config/builderEnvironment.d.ts +12 -0
  32. package/dist/core/config/builderEnvironment.d.ts.map +1 -0
  33. package/dist/core/config/endpointProperties.d.ts +5 -2
  34. package/dist/core/config/endpointProperties.d.ts.map +1 -1
  35. package/dist/core/config/hostPorts.d.ts +5 -1
  36. package/dist/core/config/hostPorts.d.ts.map +1 -1
  37. package/dist/core/config/meshStageContract.d.ts +6 -0
  38. package/dist/core/config/meshStageContract.d.ts.map +1 -0
  39. package/dist/core/config/references.d.ts +9 -3
  40. package/dist/core/config/references.d.ts.map +1 -1
  41. package/dist/core/config/resolveBuildStage.d.ts.map +1 -1
  42. package/dist/core/config/resolveMeshStage.d.ts.map +1 -1
  43. package/dist/core/config/stageMerge.d.ts +2 -0
  44. package/dist/core/config/stageMerge.d.ts.map +1 -1
  45. package/dist/core/config/types.d.ts +8 -3
  46. package/dist/core/config/types.d.ts.map +1 -1
  47. package/dist/core/mesh/checkers/checkMeshServices.d.ts +1 -1
  48. package/dist/core/mesh/checkers/checkMeshServices.d.ts.map +1 -1
  49. package/dist/core/mesh/getMeshJson.d.ts.map +1 -1
  50. package/dist/core/mesh/meshSchema.d.ts +13 -56
  51. package/dist/core/mesh/meshSchema.d.ts.map +1 -1
  52. package/dist/core/mesh/runners/runMeshDev.d.ts.map +1 -1
  53. package/dist/core/mesh/runners/runMeshProd.d.ts.map +1 -1
  54. package/dist/core/mesh/runners/runMeshServiceTests.d.ts +3 -0
  55. package/dist/core/mesh/runners/runMeshServiceTests.d.ts.map +1 -0
  56. package/dist/core/mesh/runners/runMeshTest.d.ts.map +1 -1
  57. package/dist/core/mesh/runners/runMeshTestE2e.d.ts.map +1 -1
  58. package/dist/core/mesh/types.d.ts +4 -4
  59. package/dist/core/mesh/types.d.ts.map +1 -1
  60. package/dist/core/mesh/v2/compileMeshComposition.d.ts.map +1 -1
  61. package/dist/core/mesh/v2/compileMeshTester.d.ts.map +1 -1
  62. package/dist/core/mesh/v2/meshReferences.d.ts +5 -3
  63. package/dist/core/mesh/v2/meshReferences.d.ts.map +1 -1
  64. package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts +4 -0
  65. package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts.map +1 -0
  66. package/dist/core/runWithCleanup.d.ts +3 -0
  67. package/dist/core/runWithCleanup.d.ts.map +1 -0
  68. package/dist/core/runners/runDev.d.ts.map +1 -1
  69. package/dist/core/runners/runFiniteTester.d.ts +3 -0
  70. package/dist/core/runners/runFiniteTester.d.ts.map +1 -0
  71. package/dist/core/runners/runProd.d.ts.map +1 -1
  72. package/dist/core/runners/runTestE2e.d.ts.map +1 -1
  73. package/dist/core/runners/runTestUnit.d.ts.map +1 -1
  74. package/dist/core/teardownCompose.d.ts.map +1 -1
  75. package/dist/errors/PortConflictError.d.ts +1 -1
  76. package/dist/errors/PortConflictError.d.ts.map +1 -1
  77. package/dist/index.js +1060 -767
  78. package/dist/index.js.map +1 -1
  79. package/dist/templates/policy/dockerfile/dockerfile.rego +7 -4
  80. package/dist/utils/runState.d.ts.map +1 -1
  81. package/package.json +1 -1
  82. package/schemas/mesh-schema.json +1 -106
  83. package/templates/policy/dockerfile/dockerfile.rego +7 -4
  84. package/dist/core/mesh/runners/runMeshTestUnit.d.ts +0 -3
  85. package/dist/core/mesh/runners/runMeshTestUnit.d.ts.map +0 -1
  86. package/dist/core/mesh/v2/validateMeshTestStage.d.ts +0 -22
  87. package/dist/core/mesh/v2/validateMeshTestStage.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,97 +1,627 @@
1
1
  # Solid Stack Builder
2
2
 
3
- Builder compiles V2 `build.json` service projects and `mesh.json` service meshes into Docker Compose. Endpoint ports, dependency ownership, health gating, and stage overlays are declared in JSON; Builder generates the Compose publication and lifecycle wiring.
3
+ Solid Stack Builder is a Docker-based CLI for running one service by itself or composing many independently runnable services into a local system.
4
4
 
5
- ## Service configuration
5
+ A service describes its runtime contract in `build.json`. A multi-service system describes how those services connect in `mesh.json`. Builder turns those declarations into predictable development, production, test, and E2E environments without making application code depend on generated container names or hardcoded host ports.
6
+
7
+ ## What Builder gives you
8
+
9
+ - **One workflow for a single service or a full service mesh.**
10
+ - **Named endpoints instead of hardcoded URLs and ports.**
11
+ - **Local dependency implementations** backed by Docker Compose.
12
+ - **Dependency substitution in a mesh** so a local mock can be replaced by a real top-level service.
13
+ - **Private-by-default mesh networking** with explicit host publication.
14
+ - **Fixed or automatic host ports** through `publicPort`.
15
+ - **Health-gated startup ordering** for applications and dependencies.
16
+ - **Stage overlays** for `dev`, `prod`, `test`, and `e2e`.
17
+ - **Service-level and global E2E testing** with endpoint references instead of guessed addresses.
18
+ - **Preflight validation** for Dockerfiles, Builder configuration, dependency Compose files, and mesh contracts.
19
+
20
+ ## Requirements
21
+
22
+ Builder requires:
23
+
24
+ - Node.js **20 or newer**;
25
+ - Docker Engine with a reachable daemon;
26
+ - Docker Compose **2.24.0 or newer**.
27
+
28
+ For the complete user guide, tutorials, configuration references, recipes, and troubleshooting, start at the [Builder V2 documentation](docs/README.md).
29
+
30
+ ## Installation
31
+
32
+ Install the package globally:
33
+
34
+ ```bash
35
+ pnpm add -g @solid-stack/builder
36
+ ```
37
+
38
+ or:
39
+
40
+ ```bash
41
+ npm install -g @solid-stack/builder
42
+ ```
43
+
44
+ The package exposes both `builder` and `solid-builder`. The documentation uses `builder`.
45
+
46
+ Verify the installation:
47
+
48
+ ```bash
49
+ builder --version
50
+ builder --help
51
+ ```
52
+
53
+ ## Core mental model
54
+
55
+ Builder has two configuration files with separate responsibilities:
56
+
57
+ | File | Responsibility |
58
+ |---|---|
59
+ | `build.json` | Describes one independently runnable service: its app endpoints, runtime environment, local dependency implementations, tester environment, and stage-specific changes. |
60
+ | `mesh.json` | Describes how independently runnable services are composed: service paths, dependency substitutions, mesh-owned environment values, startup dependencies, host publication, and the global E2E tester. |
61
+
62
+ A `build.json` never chooses which top-level mesh service replaces one of its dependencies. A `mesh.json` never redefines an application's endpoint ports. This separation keeps each service runnable on its own while allowing larger systems to compose it differently.
63
+
64
+ ---
65
+
66
+ # Quick start: one service
67
+
68
+ A Builder service directory normally contains at least:
69
+
70
+ ```text
71
+ my-api/
72
+ ├── build.json
73
+ ├── Dockerfile
74
+ └── ...application files
75
+ ```
76
+
77
+ ## 1. Define the service
78
+
79
+ Create `build.json`:
80
+
81
+ ```json
82
+ {
83
+ "name": "my-api",
84
+ "app": {
85
+ "endpoints": {
86
+ "http": {
87
+ "port": 3000,
88
+ "publicPort": "AUTO",
89
+ "primary": true,
90
+ "scheme": "http"
91
+ }
92
+ }
93
+ }
94
+ }
95
+ ```
96
+
97
+ The endpoint means:
98
+
99
+ - the app listens on container port `3000`;
100
+ - it may be reached from the host because `publicPort` is declared;
101
+ - Builder chooses an available host port because the value is `"AUTO"`;
102
+ - the endpoint is the app's primary endpoint, so Builder injects `PORT=3000`;
103
+ - URL references can be constructed because `scheme` is `http`.
104
+
105
+ ## 2. Provide the Dockerfile targets
106
+
107
+ A Builder application Dockerfile must expose the expected stage contract:
108
+
109
+ ```text
110
+ dev
111
+ test
112
+ test-e2e
113
+ prod
114
+ ```
115
+
116
+ `dev` and `prod` must provide a valid Docker healthcheck. Network applications should use the Builder-provided `PORT` rather than assuming a fixed application port.
117
+
118
+ ## 3. Validate the project
119
+
120
+ ```bash
121
+ builder check
122
+ ```
123
+
124
+ From another directory:
125
+
126
+ ```bash
127
+ builder check -C ./services/my-api
128
+ ```
129
+
130
+ ## 4. Run development
131
+
132
+ ```bash
133
+ builder service up dev
134
+ ```
135
+
136
+ Development is isolated by default: local dependency implementations are not started.
137
+
138
+ To run development with all endpoint-bearing local dependencies:
139
+
140
+ ```bash
141
+ builder service up dev --full
142
+ ```
143
+
144
+ Stop it with:
145
+
146
+ ```bash
147
+ builder service down dev
148
+ ```
149
+
150
+ ---
151
+
152
+ # Add a local dependency
153
+
154
+ A dependency is a **logical dependency** backed by one Compose implementation and zero or more named endpoints.
6
155
 
7
156
  ```json
8
157
  {
9
- "name": "api",
158
+ "name": "my-api",
10
159
  "app": {
11
- "env": { "DATABASE_HOST": "${dependencies.database.endpoints.tcp.network_host}" },
160
+ "env": {
161
+ "DATABASE_HOST": "${dependencies.database.endpoints.tcp.network_host}",
162
+ "DATABASE_PORT": "${dependencies.database.endpoints.tcp.network_port}"
163
+ },
12
164
  "endpoints": {
13
- "http": { "port": 3000, "publicPort": "AUTO", "primary": true, "scheme": "http" }
165
+ "http": {
166
+ "port": 3000,
167
+ "publicPort": "AUTO",
168
+ "primary": true,
169
+ "scheme": "http"
170
+ }
14
171
  }
15
172
  },
16
173
  "dependencies": {
17
174
  "database": {
18
- "compose": "./compose/database.yml",
175
+ "compose": ".docker/dependencies/database.compose.yml",
19
176
  "endpoints": {
20
- "tcp": { "service": "postgres", "port": 5432, "primary": true }
177
+ "tcp": {
178
+ "service": "postgres",
179
+ "port": 5432,
180
+ "primary": true
181
+ }
21
182
  }
22
183
  }
23
- },
24
- "tester": {
25
- "env": { "API_URL": "${app.endpoints.http.public_url}" }
26
184
  }
27
185
  }
28
186
  ```
29
187
 
30
- The `app` primary endpoint sets the container's `PORT`. Builder owns `PORT`, `EXEC_MODE`, and `INFRA_MODE`; do not define them in app environment files. Host access is declared with endpoint `publicPort`, either a fixed integer or `"AUTO"`. Dependency Compose files keep their own service definitions and healthchecks, but must not publish raw host ports. A dependency with no endpoints is inert.
188
+ The dependency endpoint's `service` must exactly name the owning service in the dependency Compose file. Builder does not infer the first service or guess which container owns the endpoint.
31
189
 
32
- Stage overlays are named `dev`, `prod`, `test`, and `e2e`. Each can add or change app environment, endpoints, dependencies, and `override-compose`. E2E reads its own overlay and runs the app's `prod` Dockerfile target with `EXEC_MODE=e2e`.
190
+ If a dependency has no effective endpoints, it is inert and is not materialized at runtime.
33
191
 
34
- ```bash
35
- builder check -C ./services/api
36
- builder service up dev -C ./services/api
37
- builder service up dev --full -C ./services/api
38
- builder service up prod -C ./services/api
39
- builder service up test-unit -C ./services/api
40
- builder service up test-e2e -C ./services/api
41
- builder service up test -C ./services/api
42
- builder service export env dev --full -C ./services/api
43
- builder service down dev -C ./services/api
192
+ Dependency Compose files must keep endpoint-owning services healthcheckable. Builder uses those healthchecks to decide when a dependency is ready.
193
+
194
+ ---
195
+
196
+ # Endpoint references
197
+
198
+ Builder-managed JSON environment values can refer to endpoint properties instead of hardcoding generated addresses.
199
+
200
+ Inside `build.json`:
201
+
202
+ ```text
203
+ ${app.endpoints.<endpoint>.<property>}
204
+ ${dependencies.<dependency>.endpoints.<endpoint>.<property>}
44
205
  ```
45
206
 
46
- `dev` and `test-unit` are isolated by default. `dev --full` and `prod` include local endpoint dependencies. `test` runs unit tests followed by E2E and stops if the unit phase fails. `--dry-run` compiles and validates without starting containers; `--skip-checks` skips the Dockerfile lint and contract preflight where supported.
207
+ Inside `mesh.json`:
47
208
 
48
- ## Mesh configuration
209
+ ```text
210
+ ${<service>.app.endpoints.<endpoint>.<property>}
211
+ ${<service>.dependencies.<dependency>.endpoints.<endpoint>.<property>}
212
+ ```
213
+
214
+ Available properties:
215
+
216
+ | Property | Meaning | Needs `scheme` | Needs effective host publication |
217
+ |---|---|---:|---:|
218
+ | `network_host` | Internal DNS host | No | No |
219
+ | `network_port` | Internal container port | No | No |
220
+ | `network_address` | `host:port` on the internal network | No | No |
221
+ | `network_url` | `scheme://host:port` on the internal network | Yes | No |
222
+ | `public_host` | Host-facing address, currently `127.0.0.1` | No | Yes |
223
+ | `public_port` | Resolved host port | No | Yes |
224
+ | `public_address` | `host:port` from the host | No | Yes |
225
+ | `public_url` | `scheme://host:port` from the host | Yes | Yes |
226
+
227
+ References can be embedded inside larger strings:
228
+
229
+ ```json
230
+ {
231
+ "API_URL": "${dependencies.backend.endpoints.http.network_url}/v1"
232
+ }
233
+ ```
234
+
235
+ Use `$$` when a literal dollar escape is required in Builder-managed environment strings.
236
+
237
+ ---
238
+
239
+ # Service stages
240
+
241
+ Builder has four configuration overlays but five service commands for execution/testing:
242
+
243
+ | Command | Config overlay | Dockerfile target | Local dependencies | Purpose |
244
+ |---|---|---|---|---|
245
+ | `builder service up dev` | `dev` | `dev` | Isolated | Normal development |
246
+ | `builder service up dev --full` | `dev` | `dev` | Integrated | Development with local dependencies |
247
+ | `builder service up prod` | `prod` | `prod` | Integrated | Production-style runtime |
248
+ | `builder service up test-unit` | `test` | `test` | Isolated | Unit/integration test runner |
249
+ | `builder service up test-e2e` | `base -> prod -> e2e` | app=`prod`, tester=`test-e2e` | Integrated | Service-level E2E |
250
+ | `builder service up test` | `test` then `e2e` | test, then prod/test-e2e | As above | Unit tests first, then E2E |
251
+
252
+ E2E uses production-shaped structured configuration: `base -> prod -> e2e`. The app runs Docker target `prod` with `EXEC_MODE=prod` and `INFRA_MODE=integrated`, while its dotenv source remains `.env.e2e`. `.env.prod` is not merged into `.env.e2e`.
253
+
254
+ ---
255
+
256
+ # Quick start: a service mesh
257
+
258
+ A mesh composes service projects that can already run independently.
259
+
260
+ ```text
261
+ system/
262
+ ├── mesh.json
263
+ └── services/
264
+ ├── frontend/
265
+ │ ├── build.json
266
+ │ └── Dockerfile
267
+ └── backend/
268
+ ├── build.json
269
+ └── Dockerfile
270
+ ```
271
+
272
+ Create `mesh.json`:
49
273
 
50
274
  ```json
51
275
  {
52
276
  "name": "system",
53
277
  "services": {
54
- "database": { "path": "./services/database" },
55
- "api": {
56
- "path": "./services/api",
57
- "dependencies": { "database": "database" },
58
- "publish": ["app.endpoints.http"]
278
+ "backend": {
279
+ "path": "./services/backend"
280
+ },
281
+ "frontend": {
282
+ "path": "./services/frontend",
283
+ "dependencies": {
284
+ "backend": "backend"
285
+ },
286
+ "publish": [
287
+ "app.endpoints.http"
288
+ ]
59
289
  }
60
- },
290
+ }
291
+ }
292
+ ```
293
+
294
+ The binding:
295
+
296
+ ```json
297
+ "dependencies": {
298
+ "backend": "backend"
299
+ }
300
+ ```
301
+
302
+ means:
303
+
304
+ > for the `frontend` service's logical dependency named `backend`, use the top-level mesh service named `backend` instead of the frontend service's local dependency Compose implementation.
305
+
306
+ Substitution is atomic: the local implementation for that logical dependency is suppressed as a whole.
307
+
308
+ Run the mesh:
309
+
310
+ ```bash
311
+ builder mesh check
312
+ builder mesh up dev
313
+ ```
314
+
315
+ Stop it:
316
+
317
+ ```bash
318
+ builder mesh down dev
319
+ ```
320
+
321
+ ---
322
+
323
+ # Mesh publication is explicit
324
+
325
+ Declaring `publicPort` in a service's `build.json` makes an endpoint *publishable*. It does not automatically make the endpoint host-visible inside a mesh.
326
+
327
+ The mesh must explicitly publish it:
328
+
329
+ ```json
330
+ {
331
+ "services": {
332
+ "gateway": {
333
+ "path": "./services/gateway",
334
+ "publish": [
335
+ "app.endpoints.http"
336
+ ]
337
+ }
338
+ }
339
+ }
340
+ ```
341
+
342
+ A mesh can publish:
343
+
344
+ ```text
345
+ app.endpoints.<endpoint>
346
+ dependencies.<dependency>.endpoints.<endpoint>
347
+ ```
348
+
349
+ A substituted dependency cannot be published through the consumer's old local dependency path. Publish the provider service's app endpoint instead.
350
+
351
+ This makes it practical to keep databases, APIs, queues, and internal services private while publishing only the entry point that developers or external test clients need.
352
+
353
+ ---
354
+
355
+ # Mesh stages
356
+
357
+ | Command | Mesh overlay | Service build overlay | App target | Local service dependencies | Global tester |
358
+ |---|---|---|---|---|---|
359
+ | `builder mesh up dev` | `dev` | `dev` | `dev` | Integrated unless substituted | No |
360
+ | `builder mesh up prod` | `prod` | `prod` | `prod` | Integrated unless substituted | No |
361
+ | `builder mesh up test-e2e` | `base -> prod -> e2e` | `base -> prod -> e2e` | `prod` | Integrated unless substituted | Yes |
362
+ | `builder mesh up test` | Phase 1: root service tests; Phase 2: `base -> prod -> e2e` | service lifecycle, then global E2E | `test`, then `prod` | Per phase | Global tester in Phase 2 |
363
+
364
+ `mesh test` has two phases. Phase 1 runs each root service’s complete standalone test lifecycle—unit/isolated tests followed by that service’s own E2E tester—sequentially with full teardown. Phase 2 starts a clean `base -> prod -> e2e` mesh and runs the global E2E tester. Stage-only mesh services are not Phase-1 members unless they also exist in root `services`. `mesh.json` supports `dev`, `prod`, and `e2e` overlays only. A root `test` field is rejected, including an empty object and when `--skip-checks` is used. `build.json.test` remains supported. See [v2.2 migration](docs/migration/v2.1-to-v2.2.md).
365
+
366
+ ---
367
+
368
+ # Global mesh E2E tester
369
+
370
+ A mesh can define a host-networked black-box tester:
371
+
372
+ ```json
373
+ {
61
374
  "tester": {
62
375
  "compose": "./e2e/docker-compose.yml",
63
376
  "service": "runner",
64
- "env": { "API_URL": "${api.app.endpoints.http.public_url}" }
377
+ "env": {
378
+ "API_URL": "${gateway.app.endpoints.http.public_url}"
379
+ }
380
+ },
381
+ "services": {
382
+ "gateway": {
383
+ "path": "./services/gateway",
384
+ "publish": [
385
+ "app.endpoints.http"
386
+ ]
387
+ }
65
388
  }
66
389
  }
67
390
  ```
68
391
 
69
- Mesh service keys are authoritative identities. Bindings replace a service's logical dependency with a top-level provider. `publish` explicitly selects host-visible endpoints. Mesh `dev`, `prod`, `test`, and `e2e` overlays can add services and adjust bindings, environment, lifecycle, and publication. The root tester selects one exact Compose service; Builder places that runner on the host network and gates it on all top-level app healthchecks.
392
+ Tester environment references must use `public_*` endpoint properties because the selected runner acts as a host-side client. The selected runner receives root `.env.e2e-tester`, `EXEC_MODE=e2e`, and no `INFRA_MODE`; it is host-networked and supplies the exit code. Helper services in the tester Compose implementation are preserved.
393
+
394
+ Use:
395
+
396
+ ```bash
397
+ builder mesh up test-e2e
398
+ ```
399
+
400
+ or the complete test pipeline:
401
+
402
+ ```bash
403
+ builder mesh up test
404
+ ```
405
+
406
+ ---
407
+
408
+ # Command overview
409
+
410
+ ## Global
411
+
412
+ ```bash
413
+ builder --help
414
+ builder --version
415
+ builder --verbose <command>
416
+ ```
417
+
418
+ `--verbose` includes stack traces for failures.
419
+
420
+ ## Validate a service
421
+
422
+ ```bash
423
+ builder check [-C <service-dir>]
424
+ ```
425
+
426
+ ## Run a service
427
+
428
+ ```bash
429
+ builder service up [dev|prod|test|test-unit|test-e2e] [options]
430
+ ```
431
+
432
+ Common options include:
433
+
434
+ ```text
435
+ -C, --project-dir <dir>
436
+ -d, --detach
437
+ --debug
438
+ --dry-run
439
+ --skip-checks
440
+ --silence-warnings
441
+ --full
442
+ ```
443
+
444
+ `--full` is meaningful for development and materializes declared local endpoint dependencies.
445
+
446
+ ## Stop a service
447
+
448
+ ```bash
449
+ builder service down [dev|prod|test|test-unit|test-e2e] [options]
450
+ ```
451
+
452
+ Options:
453
+
454
+ ```text
455
+ -C, --project-dir <dir>
456
+ -v, --volumes
457
+ --debug
458
+ ```
459
+
460
+ ## Export resolved application environment
461
+
462
+ ```bash
463
+ builder service export env [dev|prod|test|e2e] [options]
464
+ ```
465
+
466
+ Without a stage, Builder exports all four configuration stages.
467
+
468
+ Options:
469
+
470
+ ```text
471
+ -C, --project-dir <dir>
472
+ --full
473
+ --silence-warnings
474
+ ```
475
+
476
+ The default output names are `.env.dev`, `.env.prod`, `.env.test`, and `.env.e2e`.
477
+
478
+ ## Validate a mesh
479
+
480
+ ```bash
481
+ builder mesh check [options]
482
+ ```
483
+
484
+ Options:
485
+
486
+ ```text
487
+ -C, --project-dir <dir>
488
+ --require-tester
489
+ ```
490
+
491
+ ## Run a mesh
70
492
 
71
493
  ```bash
72
- builder mesh check -C ./system
73
- builder mesh up dev -C ./system
74
- builder mesh up prod -C ./system
75
- builder mesh up test-unit -C ./system
76
- builder mesh up test-e2e -C ./system
77
- builder mesh up test -C ./system
78
- builder mesh down test -C ./system
494
+ builder mesh up [dev|prod|test|test-e2e] [options]
79
495
  ```
80
496
 
81
- `mesh test` runs per-service isolated unit tests followed by global E2E. Global E2E requires root `tester`; ordinary `mesh check` can validate dev, prod, and test without one.
497
+ Options:
82
498
 
83
- ## Contracts and reference
499
+ ```text
500
+ -C, --project-dir <dir>
501
+ -d, --detach
502
+ --debug
503
+ --dry-run
504
+ --skip-checks
505
+ --silence-warnings
506
+ ```
507
+
508
+ ## Stop a mesh
509
+
510
+ ```bash
511
+ builder mesh down [dev|prod|test|test-e2e] [options]
512
+ ```
513
+
514
+ Options:
515
+
516
+ ```text
517
+ -C, --project-dir <dir>
518
+ -v, --volumes
519
+ --debug
520
+ ```
84
521
 
85
- Application Dockerfiles require `dev`, `test`, `test-e2e`, and `prod` targets. `dev` and `prod` need Docker healthchecks, and `prod` needs an artifact `COPY --from=...`. Builder's packaged Conftest policy enforces these rules. Endpoint-bearing service Dockerfiles should probe the injected `PORT` dynamically.
522
+ ## Clean unused Docker resources
523
+
524
+ ```bash
525
+ builder prune
526
+ builder prune --volumes
527
+ ```
528
+
529
+ `builder prune` removes stopped containers and unused networks. `--volumes` also prunes dangling volumes.
530
+
531
+ ---
532
+
533
+ # Important usage rules
534
+
535
+ ## One primary endpoint
536
+
537
+ If an app or dependency has a non-empty endpoint map, exactly one effective endpoint must have:
538
+
539
+ ```json
540
+ "primary": true
541
+ ```
542
+
543
+ For the app, that primary endpoint determines the Builder-owned `PORT` value.
544
+
545
+ ## `publicPort` means publishable host access
546
+
547
+ Use a fixed port:
548
+
549
+ ```json
550
+ "publicPort": 8080
551
+ ```
552
+
553
+ or let Builder allocate one:
554
+
555
+ ```json
556
+ "publicPort": "AUTO"
557
+ ```
558
+
559
+ In standalone execution, eligible declared endpoints can be published directly. In a mesh, an endpoint is host-visible only when the effective mesh `publish` list selects it.
560
+
561
+ ## Environment values are strings
562
+
563
+ Builder JSON environment maps are always:
564
+
565
+ ```ts
566
+ Record<string, string>
567
+ ```
568
+
569
+ Do not put numbers, booleans, arrays, objects, or `null` in Builder `env` maps.
570
+
571
+ ## Environment references do not imply startup ordering
572
+
573
+ An environment value can establish *where* another service lives, but it does not mean Builder should wait for that service.
574
+
575
+ Use:
576
+
577
+ - dependency `dependsOn` for dependency-to-dependency readiness;
578
+ - mesh service `dependsOn` for explicit top-level service readiness;
579
+ - mesh dependency bindings for automatic consumer-to-provider readiness.
580
+
581
+ ## Do not hardcode Builder-generated internal names
582
+
583
+ Dependency implementations are namespaced when Builder composes them. Always refer to logical endpoints through Builder references.
584
+
585
+ ---
586
+
587
+ # Configuration reference
588
+
589
+ The current repository includes the normative V2 references:
590
+
591
+ - [`.docs/specs_v2/BUILD_JSON_DOCS.md`](.docs/specs_v2/BUILD_JSON_DOCS.md) — complete `build.json` field reference.
592
+ - [`.docs/specs_v2/MESH_JSON_DOCS.md`](.docs/specs_v2/MESH_JSON_DOCS.md) — complete `mesh.json` field reference.
593
+ - [`.docs/specs_v2/SPECS_V2.md`](.docs/specs_v2/SPECS_V2.md) — cross-file V2 behavior and invariants.
594
+ - [`schemas/build-schema.json`](schemas/build-schema.json) — generated `build.json` JSON Schema.
595
+ - [`schemas/mesh-schema.json`](schemas/mesh-schema.json) — generated `mesh.json` JSON Schema.
596
+
597
+ The long-form user documentation should be organized around workflows and usage rather than requiring users to read the specification end-to-end. See `docs_plan.md` for the proposed documentation structure.
598
+
599
+ ---
600
+
601
+ # Repository development
602
+
603
+ When working on Builder itself:
604
+
605
+ ```bash
606
+ pnpm install
607
+ pnpm typecheck
608
+ pnpm test
609
+ pnpm build
610
+ ```
611
+
612
+ Useful verification commands:
613
+
614
+ ```bash
615
+ pnpm test:conformance
616
+ pnpm test:docker
617
+ pnpm check
618
+ pnpm check:full
619
+ ```
86
620
 
87
- The full configuration and reference grammar are documented in [BUILD_JSON_DOCS.md](docs/BUILD_JSON_DOCS.md), [MESH_JSON_DOCS.md](docs/MESH_JSON_DOCS.md), and [SPECS_V2.md](docs/SPECS_V2.md). Published JSON Schemas are [build-schema.json](schemas/build-schema.json) and [mesh-schema.json](schemas/mesh-schema.json).
621
+ The default unit/conformance workflow is designed to run without requiring Docker for every test. Docker acceptance remains the final verification path for real Compose behavior.
88
622
 
89
- ## Development tests
623
+ ---
90
624
 
91
- - `pnpm test` — parallel unit, compiler, checker-boundary, and runner tests; no Docker required.
92
- - `pnpm test:conformance` — all 384 catalog scenarios plus audit regressions. A traceability test requires each scenario ID exactly once in this suite.
93
- - `pnpm check` — TypeScript and fast conformance checks.
94
- - `pnpm test:docker` — serial Docker acceptance tests, including real readiness transitions, CLI pipelines, networking, cleanup, and the Rego policy matrix. Requires Docker Engine and Compose; cold image pulls and builds can take several minutes.
95
- - `pnpm check:full` — fast checks, the complete default suite, legacy-removal guard, build, and Docker acceptance. Use this for releases, nightly CI, or manual acceptance.
625
+ # License
96
626
 
97
- Fast catalog tests inspect generated health gates and mock external process boundaries. Actual Docker behavior and Rego semantics remain covered in `tests/docker-acceptance`; the fast suite alone does not replace that acceptance gate. Normal test files run in parallel with up to four workers; Docker acceptance remains serial. Ordinary development aims for a sub-minute default suite without depending on Docker cache state.
627
+ See the package metadata and repository license policy for distribution terms.