@solid-stack/builder 1.2.0 → 2.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 (144) hide show
  1. package/README.md +59 -200
  2. package/dist/bin.js +1689 -2591
  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/command.d.ts.map +1 -1
  6. package/dist/commands/service/commands/export/command.d.ts.map +1 -1
  7. package/dist/commands/service/commands/up/command.d.ts.map +1 -1
  8. package/dist/core/buildSchema.d.ts +1029 -110
  9. package/dist/core/buildSchema.d.ts.map +1 -1
  10. package/dist/core/checkers/checkDockerfile.d.ts.map +1 -1
  11. package/dist/core/checkers/checkDockerfileContract.d.ts +1 -1
  12. package/dist/core/checkers/checkDockerfileContract.d.ts.map +1 -1
  13. package/dist/core/checkers/checkEffectiveServiceStages.d.ts +2 -0
  14. package/dist/core/checkers/checkEffectiveServiceStages.d.ts.map +1 -0
  15. package/dist/core/checkers/checkYamlFiles.d.ts +1 -1
  16. package/dist/core/checkers/checkYamlFiles.d.ts.map +1 -1
  17. package/dist/core/checkers/getDeclaredYamlFiles.d.ts +3 -1
  18. package/dist/core/checkers/getDeclaredYamlFiles.d.ts.map +1 -1
  19. package/dist/core/compileEnvironment.d.ts +1 -1
  20. package/dist/core/compileEnvironment.d.ts.map +1 -1
  21. package/dist/core/composition/compileServiceComposition.d.ts +18 -0
  22. package/dist/core/composition/compileServiceComposition.d.ts.map +1 -0
  23. package/dist/core/composition/composeEnvironment.d.ts +4 -0
  24. package/dist/core/composition/composeEnvironment.d.ts.map +1 -0
  25. package/dist/core/composition/composePaths.d.ts +3 -0
  26. package/dist/core/composition/composePaths.d.ts.map +1 -0
  27. package/dist/core/composition/dependencyLifecycle.d.ts +4 -0
  28. package/dist/core/composition/dependencyLifecycle.d.ts.map +1 -0
  29. package/dist/core/composition/loadCompose.d.ts +8 -0
  30. package/dist/core/composition/loadCompose.d.ts.map +1 -0
  31. package/dist/core/composition/namespaceDependencyCompose.d.ts +15 -0
  32. package/dist/core/composition/namespaceDependencyCompose.d.ts.map +1 -0
  33. package/dist/core/composition/serviceEndpoints.d.ts +5 -0
  34. package/dist/core/composition/serviceEndpoints.d.ts.map +1 -0
  35. package/dist/core/composition/types.d.ts +64 -0
  36. package/dist/core/composition/types.d.ts.map +1 -0
  37. package/dist/core/composition/validateDependencyCompose.d.ts +8 -0
  38. package/dist/core/composition/validateDependencyCompose.d.ts.map +1 -0
  39. package/dist/core/composition/validateOverrideCompose.d.ts +11 -0
  40. package/dist/core/composition/validateOverrideCompose.d.ts.map +1 -0
  41. package/dist/core/config/constants.d.ts +13 -0
  42. package/dist/core/config/constants.d.ts.map +1 -0
  43. package/dist/core/config/endpointProperties.d.ts +16 -0
  44. package/dist/core/config/endpointProperties.d.ts.map +1 -0
  45. package/dist/core/config/hostPorts.d.ts +10 -0
  46. package/dist/core/config/hostPorts.d.ts.map +1 -0
  47. package/dist/core/config/lifecycleGraph.d.ts +7 -0
  48. package/dist/core/config/lifecycleGraph.d.ts.map +1 -0
  49. package/dist/core/config/pathSafety.d.ts +6 -0
  50. package/dist/core/config/pathSafety.d.ts.map +1 -0
  51. package/dist/core/config/references.d.ts +15 -0
  52. package/dist/core/config/references.d.ts.map +1 -0
  53. package/dist/core/config/resolveBuildStage.d.ts +4 -0
  54. package/dist/core/config/resolveBuildStage.d.ts.map +1 -0
  55. package/dist/core/config/resolveMeshStage.d.ts +4 -0
  56. package/dist/core/config/resolveMeshStage.d.ts.map +1 -0
  57. package/dist/core/config/stageMerge.d.ts +4 -0
  58. package/dist/core/config/stageMerge.d.ts.map +1 -0
  59. package/dist/core/config/types.d.ts +44 -0
  60. package/dist/core/config/types.d.ts.map +1 -0
  61. package/dist/core/mesh/MeshRunOptions.d.ts +0 -1
  62. package/dist/core/mesh/MeshRunOptions.d.ts.map +1 -1
  63. package/dist/core/mesh/checkers/checkMeshJson.d.ts +1 -1
  64. package/dist/core/mesh/checkers/checkMeshJson.d.ts.map +1 -1
  65. package/dist/core/mesh/checkers/checkMeshServices.d.ts +1 -1
  66. package/dist/core/mesh/checkers/checkMeshServices.d.ts.map +1 -1
  67. package/dist/core/mesh/checkers/checkMeshTester.d.ts +1 -1
  68. package/dist/core/mesh/checkers/checkMeshTester.d.ts.map +1 -1
  69. package/dist/core/mesh/compileMeshEnvironment.d.ts +1 -3
  70. package/dist/core/mesh/compileMeshEnvironment.d.ts.map +1 -1
  71. package/dist/core/mesh/getMeshJson.d.ts.map +1 -1
  72. package/dist/core/mesh/meshSchema.d.ts +267 -334
  73. package/dist/core/mesh/meshSchema.d.ts.map +1 -1
  74. package/dist/core/mesh/runners/runMeshDev.d.ts.map +1 -1
  75. package/dist/core/mesh/runners/runMeshProd.d.ts.map +1 -1
  76. package/dist/core/mesh/runners/runMeshTest.d.ts.map +1 -1
  77. package/dist/core/mesh/runners/runMeshTestE2e.d.ts.map +1 -1
  78. package/dist/core/mesh/runners/runMeshTestUnit.d.ts.map +1 -1
  79. package/dist/core/mesh/types.d.ts +34 -40
  80. package/dist/core/mesh/types.d.ts.map +1 -1
  81. package/dist/core/mesh/v2/compileMeshComposition.d.ts +6 -0
  82. package/dist/core/mesh/v2/compileMeshComposition.d.ts.map +1 -0
  83. package/dist/core/mesh/v2/compileMeshTester.d.ts +14 -0
  84. package/dist/core/mesh/v2/compileMeshTester.d.ts.map +1 -0
  85. package/dist/core/mesh/v2/lifecycle.d.ts +10 -0
  86. package/dist/core/mesh/v2/lifecycle.d.ts.map +1 -0
  87. package/dist/core/mesh/v2/loadMeshServices.d.ts +5 -0
  88. package/dist/core/mesh/v2/loadMeshServices.d.ts.map +1 -0
  89. package/dist/core/mesh/v2/meshReferences.d.ts +15 -0
  90. package/dist/core/mesh/v2/meshReferences.d.ts.map +1 -0
  91. package/dist/core/mesh/v2/publication.d.ts +3 -0
  92. package/dist/core/mesh/v2/publication.d.ts.map +1 -0
  93. package/dist/core/mesh/v2/substitution.d.ts +5 -0
  94. package/dist/core/mesh/v2/substitution.d.ts.map +1 -0
  95. package/dist/core/mesh/v2/types.d.ts +40 -0
  96. package/dist/core/mesh/v2/types.d.ts.map +1 -0
  97. package/dist/core/runners/runTestE2e.d.ts.map +1 -1
  98. package/dist/core/runners/runTestUnit.d.ts.map +1 -1
  99. package/dist/core/templates.d.ts +1 -0
  100. package/dist/core/templates.d.ts.map +1 -1
  101. package/dist/errors/ConfigError.d.ts +15 -0
  102. package/dist/errors/ConfigError.d.ts.map +1 -0
  103. package/dist/errors/PortConflictError.d.ts +8 -0
  104. package/dist/errors/PortConflictError.d.ts.map +1 -0
  105. package/dist/index.d.ts +2 -0
  106. package/dist/index.d.ts.map +1 -1
  107. package/dist/index.js +1691 -2593
  108. package/dist/index.js.map +1 -1
  109. package/dist/templates/docker/docker-compose.base.yml +4 -4
  110. package/dist/templates/docker/docker-compose.dev.yml +1 -5
  111. package/dist/templates/docker/docker-compose.e2e.yml +9 -8
  112. package/dist/templates/docker/docker-compose.prod.yml +1 -6
  113. package/dist/templates/docker/docker-compose.test.yml +3 -8
  114. package/dist/templates/policy/dockerfile/dockerfile.rego +64 -0
  115. package/dist/types/index.d.ts +60 -50
  116. package/dist/types/index.d.ts.map +1 -1
  117. package/dist/utils/checkPortCollision.d.ts.map +1 -1
  118. package/dist/utils/getBuildJson.d.ts.map +1 -1
  119. package/dist/utils/runState.d.ts.map +1 -1
  120. package/package.json +4 -2
  121. package/schemas/build-schema.json +620 -101
  122. package/schemas/mesh-schema.json +225 -133
  123. package/templates/docker/docker-compose.base.yml +4 -4
  124. package/templates/docker/docker-compose.dev.yml +1 -5
  125. package/templates/docker/docker-compose.e2e.yml +9 -8
  126. package/templates/docker/docker-compose.prod.yml +1 -6
  127. package/templates/docker/docker-compose.test.yml +3 -8
  128. package/templates/policy/dockerfile/dockerfile.rego +64 -0
  129. package/dist/core/checkers/checkComposeContract.d.ts +0 -3
  130. package/dist/core/checkers/checkComposeContract.d.ts.map +0 -1
  131. package/dist/templates/docker/docker-compose.standalone.yml +0 -5
  132. package/dist/utils/dependencyPorts.d.ts +0 -10
  133. package/dist/utils/dependencyPorts.d.ts.map +0 -1
  134. package/dist/utils/extractBuildDeps.d.ts +0 -3
  135. package/dist/utils/extractBuildDeps.d.ts.map +0 -1
  136. package/dist/utils/extractOverrides.d.ts +0 -3
  137. package/dist/utils/extractOverrides.d.ts.map +0 -1
  138. package/dist/utils/ymlMods/addDependenciesToAppService.d.ts +0 -3
  139. package/dist/utils/ymlMods/addDependenciesToAppService.d.ts.map +0 -1
  140. package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts +0 -2
  141. package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts.map +0 -1
  142. package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts +0 -3
  143. package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts.map +0 -1
  144. package/templates/docker/docker-compose.standalone.yml +0 -5
package/README.md CHANGED
@@ -1,228 +1,87 @@
1
- # @solid-stack/builder
1
+ # Solid Stack Builder
2
2
 
3
- The official build system, test runner, and Docker orchestrator CLI for Solid Stack services.
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.
4
4
 
5
- ## Installation
6
-
7
- ### Global Installation (CLI tool)
8
-
9
- Install globally using `pnpm` (or `npm`):
10
-
11
- ```bash
12
- pnpm add -g @solid-stack/builder
13
- ```
14
-
15
- Once installed globally, the CLI tool is available directly as `builder`:
16
-
17
- ```bash
18
- builder --version
19
- builder --help
20
- ```
21
-
22
- ### Local / Project Installation
23
-
24
- When developing within a project or monorepo, add `@solid-stack/builder` to your dependencies (or link to local source during development via `"@solid-stack/builder": "link:../../builder"`), and run commands via `pnpm`:
25
-
26
- ```bash
27
- # Add script in package.json: "builder": "builder"
28
- pnpm builder service up dev
29
- # or via pnpm exec
30
- pnpm exec builder service up dev
31
- ```
32
-
33
- ---
34
-
35
- ## 🚀 CLI Commands
36
-
37
- ### 1. Development Mode (`builder service up dev`)
38
-
39
- Spins up the isolated development environment with hot-reloading:
40
-
41
- ```bash
42
- builder service up dev
43
- ```
44
-
45
- - Performs Dockerfile linting (`hadolint`) and OPA policy contract validation (`conftest`)
46
- - Merges `docker-compose.base.yml`, `docker-compose.dev.yml`, `.env.dev`, and any overrides defined in `build.json`
47
- - Mounts source code with hot-reloading enabled
48
-
49
- #### Full Development Mode (`builder service up dev --full`)
50
-
51
- Spins up the development environment with hot-reloading while connecting to all declared mock dependencies and setting `INFRA_MODE=integrated`:
52
-
53
- ```bash
54
- builder service up dev --full
55
- # Or alias:
56
- builder service up dev --integrated
57
- ```
58
-
59
- ### 2. Production Mode (`builder service up prod`)
60
-
61
- Spins up the production runtime with integrated local mocks:
62
-
63
- ```bash
64
- builder service up prod
65
- ```
66
-
67
- - Validates infrastructure and contract compliance
68
- - Merges production compose definitions with mock dependencies (e.g., wiremock, databases)
69
- - Sets up inter-service health checks (`service_healthy` conditions)
70
-
71
- ### 3. Test Suites (`builder service up test`)
72
-
73
- Runs the full end-to-end test pipeline:
74
-
75
- ```bash
76
- builder service up test
77
- ```
78
-
79
- - Stage 1: Runs isolated unit tests (`pnpm test` in test container)
80
- - Stage 2: If unit tests pass, boots dependencies, app, and tester containers for integration/E2E assertions (`pnpm test:e2e`)
81
- - Automatically cleans up and tears down containers upon completion
82
-
83
- #### Targeting specific test stages
84
-
85
- ```bash
86
- # Run only unit tests
87
- builder service up test --unit
88
- # Or shorthand:
89
- builder service up test-unit
90
-
91
- # Run only E2E integration tests
92
- builder service up test --e2e
93
- # Or shorthand:
94
- builder service up test-e2e
95
- ```
96
-
97
- ---
98
-
99
- ### Export the application environment (`builder service export env [stage]`)
100
-
101
- ```bash
102
- # Export all four stages into the service directory
103
- builder service export env
104
-
105
- # Export one stage only
106
- builder service export env dev
107
- builder service export env prod
108
- builder service export env test
109
- builder service export env e2e -C ./services/backend
110
-
111
- # Match full/integrated development mode
112
- builder service export env dev --full
113
- ```
114
-
115
- The default output names are `.env.dev`, `.env.prod`, `.env.test`, and `.env.e2e`. These are also the stage input files used by Builder, so existing files require explicit confirmation before replacement. If an output file exists, Builder asks whether to overwrite it. Declining prompts for a new filename relative to the service directory; an existing replacement filename also requires confirmation. Existing files require an interactive terminal.
116
-
117
- Exports use the same stage compilation as service startup, including Compose environment files, overrides, Builder URL templates, and `build.json.envOverrides`. All requested stages are compiled before any files are written. Only the application service's resolved runtime environment is exported, not build arguments, dependencies, or tester settings. E2E runs the application using the production configuration, so `.env.e2e` reflects that app environment plus any E2E app overrides; it does not merge the tester's `.env.e2e` into the app.
118
-
119
- The command requires Docker Compose 2.24 or newer, but does not require a running Docker daemon or start/build containers. Image-only `ENV` defaults and values added by application startup code cannot be determined by configuration simulation and are outside the export. New files use owner-only permissions and contain the actual values. Values follow [Compose dotenv quoting rules](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) to preserve literal dollars and multiline strings.
120
-
121
- ## 🛠️ Options
122
-
123
- | Flag | Description |
124
- |---|---|
125
- | `--dry-run` | Preview the merged Docker Compose YAML configuration without starting containers |
126
- | `--debug` | Print the final merged Docker Compose YAML before launching |
127
- | `--skip-check` | Skip hadolint and conftest infrastructure validation |
128
- | `-d, --detach` | Run Docker Compose in detached mode (background) |
129
- | `-C, --project-dir <path>` | Specify target service directory (defaults to current working directory) |
130
- | `--unit` | For `test`, run only unit test stage |
131
- | `--e2e` | For `test`, run only e2e test stage |
132
- | `--full` | For `dev`, spin up with mock dependencies and `INFRA_MODE=integrated` |
133
- | `--integrated` | Alias for `--full` |
134
-
135
- ---
136
-
137
- ## ⚙️ Configuration (`build.json`)
138
-
139
- Each service configures its dependencies and overrides via `build.json` in its project root:
5
+ ## Service configuration
140
6
 
141
7
  ```json
142
8
  {
143
- "name": "backend",
144
- "dependencies": {
145
- "filesystem": {
146
- "path": ".docker/mocks/docker-compose.filesystem.yml",
147
- "service": "mock-filesystem"
9
+ "name": "api",
10
+ "app": {
11
+ "env": { "DATABASE_HOST": "${dependencies.database.endpoints.tcp.network_host}" },
12
+ "endpoints": {
13
+ "http": { "port": 3000, "publicPort": "AUTO", "primary": true, "scheme": "http" }
148
14
  }
149
15
  },
150
- "overrides": {
151
- "dev": {
152
- "path": ".docker/overrides/docker-compose.dev.override.yml"
153
- },
154
- "test": {
155
- "path": ".docker/overrides/docker-compose.test.override.yml"
156
- },
157
- "prod": {
158
- "path": ".docker/overrides/docker-compose.prod.override.yml"
159
- },
160
- "e2e": {
161
- "path": ".docker/overrides/docker-compose.e2e.override.yml"
16
+ "dependencies": {
17
+ "database": {
18
+ "compose": "./compose/database.yml",
19
+ "endpoints": {
20
+ "tcp": { "service": "postgres", "port": 5432, "primary": true }
21
+ }
162
22
  }
23
+ },
24
+ "tester": {
25
+ "env": { "API_URL": "${app.endpoints.http.public_url}" }
163
26
  }
164
27
  }
165
28
  ```
166
29
 
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.
167
31
 
168
- ### Dependency host ports
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`.
169
33
 
170
- `dependencies.<name>.port` exposes the primary local interface. A number such as
171
- `9000` maps host port 9000 to container port 3000. An explicit value such as
172
- `"9000:8080"` maps those ports exactly.
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
44
+ ```
173
45
 
174
- `dependencies.<name>.ports` exposes additional developer interfaces. Each entry
175
- must be an explicit `HOST_PORT:CONTAINER_PORT` mapping:
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.
47
+
48
+ ## Mesh configuration
176
49
 
177
50
  ```json
178
51
  {
179
- "dependencies": {
180
- "tooling": {
181
- "path": "./tooling.compose.yml",
182
- "service": "tooling",
183
- "port": "4080:4000",
184
- "ports": ["8080:8080", "9150:9150"]
52
+ "name": "system",
53
+ "services": {
54
+ "database": { "path": "./services/database" },
55
+ "api": {
56
+ "path": "./services/api",
57
+ "dependencies": { "database": "database" },
58
+ "publish": ["app.endpoints.http"]
185
59
  }
60
+ },
61
+ "tester": {
62
+ "compose": "./e2e/docker-compose.yml",
63
+ "service": "runner",
64
+ "env": { "API_URL": "${api.app.endpoints.http.public_url}" }
186
65
  }
187
66
  }
188
67
  ```
189
68
 
190
- Auxiliary ports affect only host exposure; they do not change `.network_url` or
191
- `.public_url` template values. Builder uses only ports declared in `build.json`
192
- for local dependency host exposure, even if the mock Compose file declares ports.
193
- This keeps the application service contract predictable while allowing explicit
194
- interfaces for developer tooling. Static host port collisions fail compilation.
195
-
196
- In mesh compilation, runtime environment and build args use this precedence:
197
- Builder defaults, then service stage overrides, then service `build.json.envOverrides`,
198
- then mesh service `envOverrides`.
199
-
200
- ---
201
-
202
- ## 💻 Programmatic Usage
203
-
204
- You can also import `@solid-stack/builder` inside Node.js or TypeScript code:
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.
205
70
 
206
- ```typescript
207
- import {
208
- compileEnvironment,
209
- getBuildJson,
210
- checkInfra,
211
- handleServiceUp,
212
- } from "@solid-stack/builder";
213
-
214
- // Compile Docker Compose YAML for a specific environment
215
- const devYaml = compileEnvironment("dev", "/path/to/service");
216
-
217
- // Boot an environment programmatically
218
- await handleServiceUp("dev", {
219
- projectDir: "/path/to/service",
220
- skipCheck: false,
221
- });
71
+ ```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
222
79
  ```
223
80
 
224
- ---
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.
82
+
83
+ ## Contracts and reference
225
84
 
226
- ## 📄 License
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.
227
86
 
228
- UNLICENSED © Solid Stack Digital
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).