@solid-stack/builder 1.1.8 → 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 +62 -170
  2. package/dist/bin.js +1713 -2507
  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 -101
  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 +1715 -2545
  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 -46
  116. package/dist/types/index.d.ts.map +1 -1
  117. package/dist/utils/assertUniqueHostPortMappings.d.ts +3 -0
  118. package/dist/utils/assertUniqueHostPortMappings.d.ts.map +1 -0
  119. package/dist/utils/checkPortCollision.d.ts.map +1 -1
  120. package/dist/utils/getBuildJson.d.ts.map +1 -1
  121. package/dist/utils/runState.d.ts.map +1 -1
  122. package/package.json +4 -2
  123. package/schemas/build-schema.json +623 -96
  124. package/schemas/mesh-schema.json +225 -133
  125. package/templates/docker/docker-compose.base.yml +4 -4
  126. package/templates/docker/docker-compose.dev.yml +1 -5
  127. package/templates/docker/docker-compose.e2e.yml +9 -8
  128. package/templates/docker/docker-compose.prod.yml +1 -6
  129. package/templates/docker/docker-compose.test.yml +3 -8
  130. package/templates/policy/dockerfile/dockerfile.rego +64 -0
  131. package/dist/core/checkers/checkComposeContract.d.ts +0 -3
  132. package/dist/core/checkers/checkComposeContract.d.ts.map +0 -1
  133. package/dist/templates/docker/docker-compose.standalone.yml +0 -5
  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,195 +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
5
+ ## Service configuration
6
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
7
+ ```json
8
+ {
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" }
14
+ }
15
+ },
16
+ "dependencies": {
17
+ "database": {
18
+ "compose": "./compose/database.yml",
19
+ "endpoints": {
20
+ "tcp": { "service": "postgres", "port": 5432, "primary": true }
21
+ }
22
+ }
23
+ },
24
+ "tester": {
25
+ "env": { "API_URL": "${app.endpoints.http.public_url}" }
26
+ }
27
+ }
77
28
  ```
78
29
 
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
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.
82
31
 
83
- #### Targeting specific test stages
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`.
84
33
 
85
34
  ```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
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
95
44
  ```
96
45
 
97
- ---
98
-
99
- ### Export the application environment (`builder service export env [stage]`)
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.
100
47
 
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:
48
+ ## Mesh configuration
140
49
 
141
50
  ```json
142
51
  {
143
- "name": "backend",
144
- "dependencies": {
145
- "filesystem": {
146
- "path": ".docker/mocks/docker-compose.filesystem.yml",
147
- "service": "mock-filesystem"
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"]
148
59
  }
149
60
  },
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"
162
- }
61
+ "tester": {
62
+ "compose": "./e2e/docker-compose.yml",
63
+ "service": "runner",
64
+ "env": { "API_URL": "${api.app.endpoints.http.public_url}" }
163
65
  }
164
66
  }
165
67
  ```
166
68
 
167
- ---
168
-
169
- ## 💻 Programmatic Usage
170
-
171
- 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.
172
70
 
173
- ```typescript
174
- import {
175
- compileEnvironment,
176
- getBuildJson,
177
- checkInfra,
178
- handleServiceUp,
179
- } from "@solid-stack/builder";
180
-
181
- // Compile Docker Compose YAML for a specific environment
182
- const devYaml = compileEnvironment("dev", "/path/to/service");
183
-
184
- // Boot an environment programmatically
185
- await handleServiceUp("dev", {
186
- projectDir: "/path/to/service",
187
- skipCheck: false,
188
- });
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
189
79
  ```
190
80
 
191
- ---
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
192
84
 
193
- ## 📄 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.
194
86
 
195
- 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).