@solid-stack/builder 2.2.0 → 3.0.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 (163) hide show
  1. package/README.md +40 -592
  2. package/dist/bin.js +1715 -1946
  3. package/dist/bin.js.map +1 -1
  4. package/dist/commands/mesh/command.d.ts.map +1 -1
  5. package/dist/commands/mesh/commands/down/handler.d.ts.map +1 -1
  6. package/dist/commands/mesh/commands/up/command.d.ts.map +1 -1
  7. package/dist/commands/mesh/commands/up/handler.d.ts.map +1 -1
  8. package/dist/commands/prune/command.d.ts.map +1 -1
  9. package/dist/commands/prune/handler.d.ts +3 -1
  10. package/dist/commands/prune/handler.d.ts.map +1 -1
  11. package/dist/commands/service/command.d.ts.map +1 -1
  12. package/dist/commands/service/commands/down/handler.d.ts.map +1 -1
  13. package/dist/commands/service/commands/up/command.d.ts.map +1 -1
  14. package/dist/commands/service/commands/up/handler.d.ts.map +1 -1
  15. package/dist/core/buildSchema.d.ts +217 -952
  16. package/dist/core/buildSchema.d.ts.map +1 -1
  17. package/dist/core/checkers/checkDockerfileContract.d.ts +1 -0
  18. package/dist/core/checkers/checkDockerfileContract.d.ts.map +1 -1
  19. package/dist/core/checkers/checkInfra.d.ts +7 -1
  20. package/dist/core/checkers/checkInfra.d.ts.map +1 -1
  21. package/dist/core/checkers/getDeclaredYamlFiles.d.ts +1 -1
  22. package/dist/core/checkers/getDeclaredYamlFiles.d.ts.map +1 -1
  23. package/dist/core/compileApplicationEnv.d.ts +7 -2
  24. package/dist/core/compileApplicationEnv.d.ts.map +1 -1
  25. package/dist/core/compileEnvironment.d.ts +1 -0
  26. package/dist/core/compileEnvironment.d.ts.map +1 -1
  27. package/dist/core/composeCleanup.d.ts.map +1 -1
  28. package/dist/core/composition/compileGraphComposition.d.ts +16 -0
  29. package/dist/core/composition/compileGraphComposition.d.ts.map +1 -0
  30. package/dist/core/composition/compileServiceComposition.d.ts +2 -13
  31. package/dist/core/composition/compileServiceComposition.d.ts.map +1 -1
  32. package/dist/core/composition/compileTester.d.ts +24 -0
  33. package/dist/core/composition/compileTester.d.ts.map +1 -0
  34. package/dist/core/composition/composeDependsOn.d.ts +8 -4
  35. package/dist/core/composition/composeDependsOn.d.ts.map +1 -1
  36. package/dist/core/composition/composeHealthcheck.d.ts.map +1 -1
  37. package/dist/core/composition/dotenv.d.ts +3 -0
  38. package/dist/core/composition/dotenv.d.ts.map +1 -0
  39. package/dist/core/composition/generatedNames.d.ts.map +1 -1
  40. package/dist/core/composition/inspectRequiredHealth.d.ts +11 -0
  41. package/dist/core/composition/inspectRequiredHealth.d.ts.map +1 -0
  42. package/dist/core/composition/mergeMainOverride.d.ts +3 -0
  43. package/dist/core/composition/mergeMainOverride.d.ts.map +1 -0
  44. package/dist/core/composition/types.d.ts +21 -39
  45. package/dist/core/composition/types.d.ts.map +1 -1
  46. package/dist/core/composition/validateMaterializedComposeBuildInputs.d.ts.map +1 -1
  47. package/dist/core/composition/validateMaterializedComposeFiles.d.ts.map +1 -1
  48. package/dist/core/composition/validateOverrideCompose.d.ts +4 -4
  49. package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -1
  50. package/dist/core/composition/validateServiceCompose.d.ts +12 -0
  51. package/dist/core/composition/validateServiceCompose.d.ts.map +1 -0
  52. package/dist/core/config/constants.d.ts +2 -4
  53. package/dist/core/config/constants.d.ts.map +1 -1
  54. package/dist/core/config/endpointProperties.d.ts +2 -2
  55. package/dist/core/config/endpointProperties.d.ts.map +1 -1
  56. package/dist/core/config/executionProfile.d.ts +11 -0
  57. package/dist/core/config/executionProfile.d.ts.map +1 -0
  58. package/dist/core/config/hostPorts.d.ts +7 -1
  59. package/dist/core/config/hostPorts.d.ts.map +1 -1
  60. package/dist/core/config/publication.d.ts +11 -0
  61. package/dist/core/config/publication.d.ts.map +1 -0
  62. package/dist/core/config/references.d.ts +15 -15
  63. package/dist/core/config/references.d.ts.map +1 -1
  64. package/dist/core/config/resolveBuildStage.d.ts.map +1 -1
  65. package/dist/core/config/resolveMeshStage.d.ts +1 -1
  66. package/dist/core/config/resolveMeshStage.d.ts.map +1 -1
  67. package/dist/core/config/serviceGraph.d.ts +10 -0
  68. package/dist/core/config/serviceGraph.d.ts.map +1 -0
  69. package/dist/core/config/stageMerge.d.ts +2 -3
  70. package/dist/core/config/stageMerge.d.ts.map +1 -1
  71. package/dist/core/config/types.d.ts +104 -27
  72. package/dist/core/config/types.d.ts.map +1 -1
  73. package/dist/core/mesh/applyMeshExtends.d.ts +3 -0
  74. package/dist/core/mesh/applyMeshExtends.d.ts.map +1 -0
  75. package/dist/core/mesh/checkers/checkMesh.d.ts +2 -0
  76. package/dist/core/mesh/checkers/checkMesh.d.ts.map +1 -1
  77. package/dist/core/mesh/checkers/checkMeshServices.d.ts +2 -1
  78. package/dist/core/mesh/checkers/checkMeshServices.d.ts.map +1 -1
  79. package/dist/core/mesh/checkers/checkMeshTester.d.ts +1 -3
  80. package/dist/core/mesh/checkers/checkMeshTester.d.ts.map +1 -1
  81. package/dist/core/mesh/compileMeshComposition.d.ts +6 -0
  82. package/dist/core/mesh/compileMeshComposition.d.ts.map +1 -0
  83. package/dist/core/mesh/compileMeshEnvironment.d.ts +3 -2
  84. package/dist/core/mesh/compileMeshEnvironment.d.ts.map +1 -1
  85. package/dist/core/mesh/loadMeshSources.d.ts +4 -0
  86. package/dist/core/mesh/loadMeshSources.d.ts.map +1 -0
  87. package/dist/core/mesh/meshSchema.d.ts +41 -225
  88. package/dist/core/mesh/meshSchema.d.ts.map +1 -1
  89. package/dist/core/mesh/runners/runMeshDev.d.ts +1 -1
  90. package/dist/core/mesh/runners/runMeshDev.d.ts.map +1 -1
  91. package/dist/core/mesh/runners/runMeshProd.d.ts +1 -1
  92. package/dist/core/mesh/runners/runMeshProd.d.ts.map +1 -1
  93. package/dist/core/mesh/runners/runMeshServiceTests.d.ts +2 -1
  94. package/dist/core/mesh/runners/runMeshServiceTests.d.ts.map +1 -1
  95. package/dist/core/mesh/runners/runMeshTest.d.ts +7 -1
  96. package/dist/core/mesh/runners/runMeshTest.d.ts.map +1 -1
  97. package/dist/core/mesh/runners/runMeshTestE2e.d.ts +2 -1
  98. package/dist/core/mesh/runners/runMeshTestE2e.d.ts.map +1 -1
  99. package/dist/core/mesh/types.d.ts +18 -24
  100. package/dist/core/mesh/types.d.ts.map +1 -1
  101. package/dist/core/runCompose.d.ts +4 -0
  102. package/dist/core/runCompose.d.ts.map +1 -1
  103. package/dist/core/runners/runDev.d.ts.map +1 -1
  104. package/dist/core/runners/runFiniteTester.d.ts +12 -2
  105. package/dist/core/runners/runFiniteTester.d.ts.map +1 -1
  106. package/dist/core/runners/runLongLived.d.ts +15 -0
  107. package/dist/core/runners/runLongLived.d.ts.map +1 -0
  108. package/dist/core/runners/runProd.d.ts.map +1 -1
  109. package/dist/core/runners/runTest.d.ts +7 -1
  110. package/dist/core/runners/runTest.d.ts.map +1 -1
  111. package/dist/core/runners/runTestE2e.d.ts +9 -1
  112. package/dist/core/runners/runTestE2e.d.ts.map +1 -1
  113. package/dist/core/runners/runTestUnit.d.ts +9 -1
  114. package/dist/core/runners/runTestUnit.d.ts.map +1 -1
  115. package/dist/index.js +1718 -1947
  116. package/dist/index.js.map +1 -1
  117. package/dist/templates/docker/docker-compose.base.yml +1 -1
  118. package/dist/templates/docker/docker-compose.dev.yml +1 -4
  119. package/dist/templates/docker/docker-compose.e2e.yml +1 -6
  120. package/dist/templates/docker/docker-compose.prod.yml +1 -1
  121. package/dist/templates/docker/docker-compose.test.yml +1 -1
  122. package/dist/templates/policy/dockerfile/dockerfile.rego +3 -6
  123. package/dist/types/index.d.ts +51 -32
  124. package/dist/types/index.d.ts.map +1 -1
  125. package/dist/utils/runState.d.ts +9 -1
  126. package/dist/utils/runState.d.ts.map +1 -1
  127. package/package.json +11 -6
  128. package/schemas/build-schema.json +868 -507
  129. package/schemas/mesh-schema.json +947 -384
  130. package/templates/docker/docker-compose.base.yml +1 -1
  131. package/templates/docker/docker-compose.dev.yml +1 -4
  132. package/templates/docker/docker-compose.e2e.yml +1 -6
  133. package/templates/docker/docker-compose.prod.yml +1 -1
  134. package/templates/docker/docker-compose.test.yml +1 -1
  135. package/templates/policy/dockerfile/dockerfile.rego +3 -6
  136. package/dist/core/composition/dependencyLifecycle.d.ts +0 -4
  137. package/dist/core/composition/dependencyLifecycle.d.ts.map +0 -1
  138. package/dist/core/composition/mergeAppOverride.d.ts +0 -3
  139. package/dist/core/composition/mergeAppOverride.d.ts.map +0 -1
  140. package/dist/core/composition/selectAppEnvironmentEntries.d.ts +0 -3
  141. package/dist/core/composition/selectAppEnvironmentEntries.d.ts.map +0 -1
  142. package/dist/core/composition/serviceEndpoints.d.ts +0 -5
  143. package/dist/core/composition/serviceEndpoints.d.ts.map +0 -1
  144. package/dist/core/composition/validateDependencyCompose.d.ts +0 -8
  145. package/dist/core/composition/validateDependencyCompose.d.ts.map +0 -1
  146. package/dist/core/mesh/v2/compileMeshComposition.d.ts +0 -6
  147. package/dist/core/mesh/v2/compileMeshComposition.d.ts.map +0 -1
  148. package/dist/core/mesh/v2/compileMeshTester.d.ts +0 -15
  149. package/dist/core/mesh/v2/compileMeshTester.d.ts.map +0 -1
  150. package/dist/core/mesh/v2/lifecycle.d.ts +0 -10
  151. package/dist/core/mesh/v2/lifecycle.d.ts.map +0 -1
  152. package/dist/core/mesh/v2/loadMeshServices.d.ts +0 -5
  153. package/dist/core/mesh/v2/loadMeshServices.d.ts.map +0 -1
  154. package/dist/core/mesh/v2/meshReferences.d.ts +0 -17
  155. package/dist/core/mesh/v2/meshReferences.d.ts.map +0 -1
  156. package/dist/core/mesh/v2/publication.d.ts +0 -3
  157. package/dist/core/mesh/v2/publication.d.ts.map +0 -1
  158. package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts +0 -4
  159. package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts.map +0 -1
  160. package/dist/core/mesh/v2/substitution.d.ts +0 -5
  161. package/dist/core/mesh/v2/substitution.d.ts.map +0 -1
  162. package/dist/core/mesh/v2/types.d.ts +0 -40
  163. package/dist/core/mesh/v2/types.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,627 +1,75 @@
1
- # Solid Stack Builder
1
+ # Solid Stack Builder V3
2
2
 
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.
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.
4
4
 
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.
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.
6
6
 
7
- ## What Builder gives you
7
+ [Builder V3 documentation](docs/README.md)
8
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.
9
+ [Upgrade from Builder 2.2.0](docs/migration/v2.2-to-v3.0.md)
19
10
 
20
- ## Requirements
11
+ ## Tests
21
12
 
22
- Builder requires:
13
+ 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`.
23
14
 
24
- - Node.js **20 or newer**;
25
- - Docker Engine with a reachable daemon;
26
- - Docker Compose **2.24.0 or newer**.
15
+ ## A service
27
16
 
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.
17
+ `build.json` (complete minimal configuration):
155
18
 
156
19
  ```json
157
20
  {
158
21
  "name": "my-api",
159
- "app": {
160
- "env": {
161
- "DATABASE_HOST": "${dependencies.database.endpoints.tcp.network_host}",
162
- "DATABASE_PORT": "${dependencies.database.endpoints.tcp.network_port}"
163
- },
164
- "endpoints": {
165
- "http": {
166
- "port": 3000,
167
- "publicPort": "AUTO",
168
- "primary": true,
169
- "scheme": "http"
170
- }
171
- }
172
- },
173
- "dependencies": {
174
- "database": {
175
- "compose": ".docker/dependencies/database.compose.yml",
22
+ "services": {
23
+ "main": {
176
24
  "endpoints": {
177
- "tcp": {
178
- "service": "postgres",
179
- "port": 5432,
180
- "primary": true
181
- }
25
+ "http": { "port": 3000, "publicPort": "AUTO", "primary": true, "scheme": "http" }
182
26
  }
183
- }
184
- }
185
- }
186
- ```
187
-
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.
189
-
190
- If a dependency has no effective endpoints, it is inert and is not materialized at runtime.
191
-
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>}
205
- ```
206
-
207
- Inside `mesh.json`:
208
-
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`:
273
-
274
- ```json
275
- {
276
- "name": "system",
277
- "services": {
278
- "backend": {
279
- "path": "./services/backend"
280
27
  },
281
- "frontend": {
282
- "path": "./services/frontend",
283
- "dependencies": {
284
- "backend": "backend"
285
- },
286
- "publish": [
287
- "app.endpoints.http"
288
- ]
289
- }
28
+ "tester": { "compose": "./e2e/docker-compose.yml", "service": "runner" }
290
29
  }
291
30
  }
292
31
  ```
293
32
 
294
- The binding:
33
+ Provide a project `Dockerfile` with `dev`, `test`, and `prod` targets. The `dev` and `prod` main images need a usable healthcheck. The tester is a separate Compose implementation; its selected `runner` determines the E2E result. A minimal `e2e/docker-compose.yml` is:
295
34
 
296
- ```json
297
- "dependencies": {
298
- "backend": "backend"
299
- }
35
+ ```yaml
36
+ services:
37
+ runner:
38
+ image: alpine:3.20
39
+ command: ["sh", "-c", "exit 0"]
300
40
  ```
301
41
 
302
- means:
42
+ The [service quickstart](docs/getting-started/service-quickstart.md) gives a runnable tree. Run `builder check`, then `builder service up dev`; `builder service up dev --full` includes the effective requisite closure. `builder service up prod` uses the `prod` target and integrated graph. `builder service up test` runs isolated unit tests, cleans up, then runs service E2E with a production main and full graph.
303
43
 
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.
44
+ | Workflow | Main target | Main execution mode | Infrastructure mode |
45
+ |---|---|---|---|
46
+ | `service up dev` | `dev` | `dev` | isolated |
47
+ | `service up dev --full` | `dev` | `dev` | integrated |
48
+ | `service up prod` | `prod` | `prod` | integrated |
49
+ | `service up test-unit` | `test` | `test` | isolated |
50
+ | `service up test-e2e` | `prod` | `prod` | integrated |
51
+ | `mesh up dev` / `prod` | `dev` / `prod` | same | integrated |
305
52
 
306
- Substitution is atomic: the local implementation for that logical dependency is suppressed as a whole.
53
+ `test-unit` and `test-e2e` are standalone workflow names, not required Dockerfile targets.
307
54
 
308
- Run the mesh:
55
+ ## A mesh rewrite
309
56
 
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:
57
+ A mesh has a required `name`, `services.tester`, and at least one source. To replace `frontend`'s local `backend` mock with a real `backend` source, remove the local edge and add the real one explicitly:
328
58
 
329
59
  ```json
330
- {
331
- "services": {
332
- "gateway": {
333
- "path": "./services/gateway",
334
- "publish": [
335
- "app.endpoints.http"
336
- ]
60
+ "frontend": {
61
+ "source": "./services/frontend",
62
+ "extends": {
63
+ "main": {
64
+ "requisites": { "source.backend": false, "backend": "dependency" },
65
+ "env": { "BACKEND_URL": "${backend.source.main.endpoints.http.network_url}" }
337
66
  }
338
67
  }
339
68
  }
340
69
  ```
341
70
 
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
- {
374
- "tester": {
375
- "compose": "./e2e/docker-compose.yml",
376
- "service": "runner",
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
- }
388
- }
389
- }
390
- ```
391
-
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
492
-
493
- ```bash
494
- builder mesh up [dev|prod|test|test-e2e] [options]
495
- ```
496
-
497
- Options:
498
-
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
- ```
521
-
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
- ```
620
-
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.
622
-
623
- ---
71
+ That is an overlay fragment at `mesh.json.services.frontend`; see the [complete mesh example](docs/getting-started/mesh-quickstart.md). The reference alone does not add the edge. Mesh endpoints are private unless `publish` selects an already reachable endpoint with `publicPort`.
624
72
 
625
- # License
73
+ `builder mesh up test` tests each base source independently and sequentially, then starts a fresh global E2E composition. The public mesh `up` stages are `dev`, `prod`, and `test`.
626
74
 
627
- See the package metadata and repository license policy for distribution terms.
75
+ See the [configuration reference](docs/reference/build-json.md), [mesh reference](docs/reference/mesh-json.md), [CLI reference](docs/reference/cli.md), and [migration guide](docs/migration/v2.2-to-v3.0.md).