@solid-stack/builder 2.0.3 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +581 -50
- package/dist/bin.js +810 -548
- package/dist/bin.js.map +1 -1
- package/dist/commands/mesh/commands/up/command.d.ts.map +1 -1
- package/dist/commands/mesh/commands/up/handler.d.ts.map +1 -1
- package/dist/commands/service/commands/export/handler.d.ts.map +1 -1
- package/dist/core/composeCleanup.d.ts.map +1 -1
- package/dist/core/composition/assertComposeLifecycleAcyclic.d.ts +7 -0
- package/dist/core/composition/assertComposeLifecycleAcyclic.d.ts.map +1 -0
- package/dist/core/composition/compileServiceComposition.d.ts.map +1 -1
- package/dist/core/composition/mergeAppOverride.d.ts +3 -0
- package/dist/core/composition/mergeAppOverride.d.ts.map +1 -0
- package/dist/core/composition/namespaceDependencyCompose.d.ts.map +1 -1
- package/dist/core/composition/namespaceResourceDefinition.d.ts +3 -0
- package/dist/core/composition/namespaceResourceDefinition.d.ts.map +1 -0
- package/dist/core/composition/selectAppEnvironmentEntries.d.ts +3 -0
- package/dist/core/composition/selectAppEnvironmentEntries.d.ts.map +1 -0
- package/dist/core/composition/types.d.ts +16 -4
- package/dist/core/composition/types.d.ts.map +1 -1
- package/dist/core/composition/validateDependencyCompose.d.ts.map +1 -1
- package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -1
- package/dist/core/config/builderEnvironment.d.ts +12 -0
- package/dist/core/config/builderEnvironment.d.ts.map +1 -0
- package/dist/core/config/endpointProperties.d.ts +5 -2
- package/dist/core/config/endpointProperties.d.ts.map +1 -1
- package/dist/core/config/hostPorts.d.ts +5 -1
- package/dist/core/config/hostPorts.d.ts.map +1 -1
- package/dist/core/config/references.d.ts +9 -3
- package/dist/core/config/references.d.ts.map +1 -1
- package/dist/core/config/resolveBuildStage.d.ts.map +1 -1
- package/dist/core/config/resolveMeshStage.d.ts.map +1 -1
- package/dist/core/config/stageMerge.d.ts +2 -0
- package/dist/core/config/stageMerge.d.ts.map +1 -1
- package/dist/core/config/types.d.ts +7 -2
- package/dist/core/config/types.d.ts.map +1 -1
- package/dist/core/mesh/checkers/checkMesh.d.ts +1 -0
- package/dist/core/mesh/checkers/checkMesh.d.ts.map +1 -1
- package/dist/core/mesh/checkers/checkMeshServices.d.ts +4 -1
- package/dist/core/mesh/checkers/checkMeshServices.d.ts.map +1 -1
- package/dist/core/mesh/meshSchema.d.ts +13 -1
- package/dist/core/mesh/meshSchema.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshDev.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshProd.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshServiceTests.d.ts +3 -0
- package/dist/core/mesh/runners/runMeshServiceTests.d.ts.map +1 -0
- package/dist/core/mesh/runners/runMeshTest.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshTestE2e.d.ts.map +1 -1
- package/dist/core/mesh/runners/runMeshTestUnit.d.ts.map +1 -1
- package/dist/core/mesh/v2/compileMeshTester.d.ts.map +1 -1
- package/dist/core/mesh/v2/meshReferences.d.ts +5 -3
- package/dist/core/mesh/v2/meshReferences.d.ts.map +1 -1
- package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts +4 -0
- package/dist/core/mesh/v2/resolveMeshAppEnvironment.d.ts.map +1 -0
- package/dist/core/mesh/v2/validateMeshTestStage.d.ts.map +1 -1
- package/dist/core/runWithCleanup.d.ts +3 -0
- package/dist/core/runWithCleanup.d.ts.map +1 -0
- package/dist/core/runners/runDev.d.ts.map +1 -1
- package/dist/core/runners/runProd.d.ts.map +1 -1
- package/dist/core/runners/runTestE2e.d.ts.map +1 -1
- package/dist/core/runners/runTestUnit.d.ts.map +1 -1
- package/dist/core/teardownCompose.d.ts.map +1 -1
- package/dist/errors/PortConflictError.d.ts +1 -1
- package/dist/errors/PortConflictError.d.ts.map +1 -1
- package/dist/index.js +809 -547
- package/dist/index.js.map +1 -1
- package/dist/templates/policy/dockerfile/dockerfile.rego +7 -4
- package/package.json +1 -1
- package/schemas/mesh-schema.json +1 -0
- package/templates/policy/dockerfile/dockerfile.rego +7 -4
package/README.md
CHANGED
|
@@ -1,97 +1,628 @@
|
|
|
1
1
|
# Solid Stack Builder
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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": {
|
|
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": {
|
|
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": "
|
|
175
|
+
"compose": ".docker/dependencies/database.compose.yml",
|
|
19
176
|
"endpoints": {
|
|
20
|
-
"tcp": {
|
|
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
|
|
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
|
-
|
|
190
|
+
If a dependency has no effective endpoints, it is inert and is not materialized at runtime.
|
|
33
191
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
-
|
|
207
|
+
Inside `mesh.json`:
|
|
47
208
|
|
|
48
|
-
|
|
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
|
-
"
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
"
|
|
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-unit` | `test` | `test` | `test` | Isolated | No |
|
|
362
|
+
| `builder mesh up test-e2e` | `base -> prod -> e2e` | `base -> prod -> e2e` | `prod` | Integrated unless substituted | Yes |
|
|
363
|
+
| `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 |
|
|
364
|
+
|
|
365
|
+
`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 up test-unit` remains explicit `mesh.test` stage tooling; it is not canonical Phase 1.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
# Global mesh E2E tester
|
|
370
|
+
|
|
371
|
+
A mesh can define a host-networked black-box tester:
|
|
372
|
+
|
|
373
|
+
```json
|
|
374
|
+
{
|
|
61
375
|
"tester": {
|
|
62
376
|
"compose": "./e2e/docker-compose.yml",
|
|
63
377
|
"service": "runner",
|
|
64
|
-
"env": {
|
|
378
|
+
"env": {
|
|
379
|
+
"API_URL": "${gateway.app.endpoints.http.public_url}"
|
|
380
|
+
}
|
|
381
|
+
},
|
|
382
|
+
"services": {
|
|
383
|
+
"gateway": {
|
|
384
|
+
"path": "./services/gateway",
|
|
385
|
+
"publish": [
|
|
386
|
+
"app.endpoints.http"
|
|
387
|
+
]
|
|
388
|
+
}
|
|
65
389
|
}
|
|
66
390
|
}
|
|
67
391
|
```
|
|
68
392
|
|
|
69
|
-
|
|
393
|
+
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.
|
|
394
|
+
|
|
395
|
+
Use:
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
builder mesh up test-e2e
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
or the complete test pipeline:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
builder mesh up test
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
---
|
|
408
|
+
|
|
409
|
+
# Command overview
|
|
410
|
+
|
|
411
|
+
## Global
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
builder --help
|
|
415
|
+
builder --version
|
|
416
|
+
builder --verbose <command>
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
`--verbose` includes stack traces for failures.
|
|
420
|
+
|
|
421
|
+
## Validate a service
|
|
422
|
+
|
|
423
|
+
```bash
|
|
424
|
+
builder check [-C <service-dir>]
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
## Run a service
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
builder service up [dev|prod|test|test-unit|test-e2e] [options]
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
Common options include:
|
|
434
|
+
|
|
435
|
+
```text
|
|
436
|
+
-C, --project-dir <dir>
|
|
437
|
+
-d, --detach
|
|
438
|
+
--debug
|
|
439
|
+
--dry-run
|
|
440
|
+
--skip-checks
|
|
441
|
+
--silence-warnings
|
|
442
|
+
--full
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
`--full` is meaningful for development and materializes declared local endpoint dependencies.
|
|
446
|
+
|
|
447
|
+
## Stop a service
|
|
448
|
+
|
|
449
|
+
```bash
|
|
450
|
+
builder service down [dev|prod|test|test-unit|test-e2e] [options]
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
Options:
|
|
454
|
+
|
|
455
|
+
```text
|
|
456
|
+
-C, --project-dir <dir>
|
|
457
|
+
-v, --volumes
|
|
458
|
+
--debug
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
## Export resolved application environment
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
builder service export env [dev|prod|test|e2e] [options]
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
Without a stage, Builder exports all four configuration stages.
|
|
468
|
+
|
|
469
|
+
Options:
|
|
470
|
+
|
|
471
|
+
```text
|
|
472
|
+
-C, --project-dir <dir>
|
|
473
|
+
--full
|
|
474
|
+
--silence-warnings
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
The default output names are `.env.dev`, `.env.prod`, `.env.test`, and `.env.e2e`.
|
|
478
|
+
|
|
479
|
+
## Validate a mesh
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
builder mesh check [options]
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
Options:
|
|
486
|
+
|
|
487
|
+
```text
|
|
488
|
+
-C, --project-dir <dir>
|
|
489
|
+
--require-tester
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
## Run a mesh
|
|
70
493
|
|
|
71
494
|
```bash
|
|
72
|
-
builder mesh
|
|
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
|
|
495
|
+
builder mesh up [dev|prod|test|test-unit|test-e2e] [options]
|
|
79
496
|
```
|
|
80
497
|
|
|
81
|
-
|
|
498
|
+
Options:
|
|
82
499
|
|
|
83
|
-
|
|
500
|
+
```text
|
|
501
|
+
-C, --project-dir <dir>
|
|
502
|
+
-d, --detach
|
|
503
|
+
--debug
|
|
504
|
+
--dry-run
|
|
505
|
+
--skip-checks
|
|
506
|
+
--silence-warnings
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
## Stop a mesh
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
builder mesh down [dev|prod|test|test-unit|test-e2e] [options]
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
Options:
|
|
516
|
+
|
|
517
|
+
```text
|
|
518
|
+
-C, --project-dir <dir>
|
|
519
|
+
-v, --volumes
|
|
520
|
+
--debug
|
|
521
|
+
```
|
|
84
522
|
|
|
85
|
-
|
|
523
|
+
## Clean unused Docker resources
|
|
524
|
+
|
|
525
|
+
```bash
|
|
526
|
+
builder prune
|
|
527
|
+
builder prune --volumes
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
`builder prune` removes stopped containers and unused networks. `--volumes` also prunes dangling volumes.
|
|
531
|
+
|
|
532
|
+
---
|
|
533
|
+
|
|
534
|
+
# Important usage rules
|
|
535
|
+
|
|
536
|
+
## One primary endpoint
|
|
537
|
+
|
|
538
|
+
If an app or dependency has a non-empty endpoint map, exactly one effective endpoint must have:
|
|
539
|
+
|
|
540
|
+
```json
|
|
541
|
+
"primary": true
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
For the app, that primary endpoint determines the Builder-owned `PORT` value.
|
|
545
|
+
|
|
546
|
+
## `publicPort` means publishable host access
|
|
547
|
+
|
|
548
|
+
Use a fixed port:
|
|
549
|
+
|
|
550
|
+
```json
|
|
551
|
+
"publicPort": 8080
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
or let Builder allocate one:
|
|
555
|
+
|
|
556
|
+
```json
|
|
557
|
+
"publicPort": "AUTO"
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
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.
|
|
561
|
+
|
|
562
|
+
## Environment values are strings
|
|
563
|
+
|
|
564
|
+
Builder JSON environment maps are always:
|
|
565
|
+
|
|
566
|
+
```ts
|
|
567
|
+
Record<string, string>
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
Do not put numbers, booleans, arrays, objects, or `null` in Builder `env` maps.
|
|
571
|
+
|
|
572
|
+
## Environment references do not imply startup ordering
|
|
573
|
+
|
|
574
|
+
An environment value can establish *where* another service lives, but it does not mean Builder should wait for that service.
|
|
575
|
+
|
|
576
|
+
Use:
|
|
577
|
+
|
|
578
|
+
- dependency `dependsOn` for dependency-to-dependency readiness;
|
|
579
|
+
- mesh service `dependsOn` for explicit top-level service readiness;
|
|
580
|
+
- mesh dependency bindings for automatic consumer-to-provider readiness.
|
|
581
|
+
|
|
582
|
+
## Do not hardcode Builder-generated internal names
|
|
583
|
+
|
|
584
|
+
Dependency implementations are namespaced when Builder composes them. Always refer to logical endpoints through Builder references.
|
|
585
|
+
|
|
586
|
+
---
|
|
587
|
+
|
|
588
|
+
# Configuration reference
|
|
589
|
+
|
|
590
|
+
The current repository includes the normative V2 references:
|
|
591
|
+
|
|
592
|
+
- [`docs/BUILD_JSON_DOCS.md`](docs/BUILD_JSON_DOCS.md) — complete `build.json` field reference.
|
|
593
|
+
- [`docs/MESH_JSON_DOCS.md`](docs/MESH_JSON_DOCS.md) — complete `mesh.json` field reference.
|
|
594
|
+
- [`docs/SPECS_V2.md`](docs/SPECS_V2.md) — cross-file V2 behavior and invariants.
|
|
595
|
+
- [`schemas/build-schema.json`](schemas/build-schema.json) — generated `build.json` JSON Schema.
|
|
596
|
+
- [`schemas/mesh-schema.json`](schemas/mesh-schema.json) — generated `mesh.json` JSON Schema.
|
|
597
|
+
|
|
598
|
+
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.
|
|
599
|
+
|
|
600
|
+
---
|
|
601
|
+
|
|
602
|
+
# Repository development
|
|
603
|
+
|
|
604
|
+
When working on Builder itself:
|
|
605
|
+
|
|
606
|
+
```bash
|
|
607
|
+
pnpm install
|
|
608
|
+
pnpm typecheck
|
|
609
|
+
pnpm test
|
|
610
|
+
pnpm build
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
Useful verification commands:
|
|
614
|
+
|
|
615
|
+
```bash
|
|
616
|
+
pnpm test:conformance
|
|
617
|
+
pnpm test:docker
|
|
618
|
+
pnpm check
|
|
619
|
+
pnpm check:full
|
|
620
|
+
```
|
|
86
621
|
|
|
87
|
-
The
|
|
622
|
+
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
623
|
|
|
89
|
-
|
|
624
|
+
---
|
|
90
625
|
|
|
91
|
-
|
|
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.
|
|
626
|
+
# License
|
|
96
627
|
|
|
97
|
-
|
|
628
|
+
See the package metadata and repository license policy for distribution terms.
|