@solid-stack/builder 1.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 (59) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +161 -0
  3. package/dist/bin.cjs +805 -0
  4. package/dist/bin.cjs.map +1 -0
  5. package/dist/bin.d.ts +3 -0
  6. package/dist/bin.d.ts.map +1 -0
  7. package/dist/bin.js +795 -0
  8. package/dist/bin.js.map +1 -0
  9. package/dist/cli.d.ts +3 -0
  10. package/dist/cli.d.ts.map +1 -0
  11. package/dist/commands/checkInfra.d.ts +2 -0
  12. package/dist/commands/checkInfra.d.ts.map +1 -0
  13. package/dist/commands/serviceUp.d.ts +3 -0
  14. package/dist/commands/serviceUp.d.ts.map +1 -0
  15. package/dist/core/compileEnvironment.d.ts +3 -0
  16. package/dist/core/compileEnvironment.d.ts.map +1 -0
  17. package/dist/core/templates.d.ts +3 -0
  18. package/dist/core/templates.d.ts.map +1 -0
  19. package/dist/errors/NotFoundError.d.ts +5 -0
  20. package/dist/errors/NotFoundError.d.ts.map +1 -0
  21. package/dist/errors/ScriptError.d.ts +4 -0
  22. package/dist/errors/ScriptError.d.ts.map +1 -0
  23. package/dist/index.cjs +814 -0
  24. package/dist/index.cjs.map +1 -0
  25. package/dist/index.d.ts +13 -0
  26. package/dist/index.d.ts.map +1 -0
  27. package/dist/index.js +792 -0
  28. package/dist/index.js.map +1 -0
  29. package/dist/templates/docker/docker-compose.base.yml +10 -0
  30. package/dist/templates/docker/docker-compose.dev.yml +11 -0
  31. package/dist/templates/docker/docker-compose.e2e.yml +9 -0
  32. package/dist/templates/docker/docker-compose.prod.yml +10 -0
  33. package/dist/templates/docker/docker-compose.standalone.yml +4 -0
  34. package/dist/templates/docker/docker-compose.test.yml +10 -0
  35. package/dist/types/index.d.ts +31 -0
  36. package/dist/types/index.d.ts.map +1 -0
  37. package/dist/utils/checkDependencies.d.ts +2 -0
  38. package/dist/utils/checkDependencies.d.ts.map +1 -0
  39. package/dist/utils/extractBuildDeps.d.ts +3 -0
  40. package/dist/utils/extractBuildDeps.d.ts.map +1 -0
  41. package/dist/utils/extractOverrides.d.ts +3 -0
  42. package/dist/utils/extractOverrides.d.ts.map +1 -0
  43. package/dist/utils/getBuildJson.d.ts +3 -0
  44. package/dist/utils/getBuildJson.d.ts.map +1 -0
  45. package/dist/utils/ymlMods/addDependenciesToAppService.d.ts +3 -0
  46. package/dist/utils/ymlMods/addDependenciesToAppService.d.ts.map +1 -0
  47. package/dist/utils/ymlMods/attachName.d.ts +2 -0
  48. package/dist/utils/ymlMods/attachName.d.ts.map +1 -0
  49. package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts +2 -0
  50. package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts.map +1 -0
  51. package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts +3 -0
  52. package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts.map +1 -0
  53. package/package.json +75 -0
  54. package/templates/docker/docker-compose.base.yml +10 -0
  55. package/templates/docker/docker-compose.dev.yml +11 -0
  56. package/templates/docker/docker-compose.e2e.yml +9 -0
  57. package/templates/docker/docker-compose.prod.yml +10 -0
  58. package/templates/docker/docker-compose.standalone.yml +4 -0
  59. package/templates/docker/docker-compose.test.yml +10 -0
package/LICENSE ADDED
@@ -0,0 +1,18 @@
1
+ Copyright (c) 2026 Solid Stack Digital
2
+
3
+ All rights reserved.
4
+
5
+ This software and its associated documentation files (the "Software") are
6
+ proprietary to Solid Stack Digital.
7
+
8
+ Strictly confidential. No part of this Software may be used, copied,
9
+ modified, merged, published, distributed, sublicensed, or sold in any form
10
+ or by any means without the prior written permission of the copyright owner.
11
+
12
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
13
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
14
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
15
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
16
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
17
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
18
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,161 @@
1
+ # @solid-stack/builder
2
+
3
+ The official build system, test runner, and Docker orchestrator CLI for Solid Stack services.
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
+ ### 2. Production Mode (`builder service up prod`)
50
+
51
+ Spins up the production runtime with integrated local mocks:
52
+
53
+ ```bash
54
+ builder service up prod
55
+ ```
56
+
57
+ - Validates infrastructure and contract compliance
58
+ - Merges production compose definitions with mock dependencies (e.g., wiremock, databases)
59
+ - Sets up inter-service health checks (`service_healthy` conditions)
60
+
61
+ ### 3. Test Suites (`builder service up test`)
62
+
63
+ Runs the full end-to-end test pipeline:
64
+
65
+ ```bash
66
+ builder service up test
67
+ ```
68
+
69
+ - Stage 1: Runs isolated unit tests (`pnpm test` in test container)
70
+ - Stage 2: If unit tests pass, boots dependencies, app, and tester containers for integration/E2E assertions (`pnpm test:e2e`)
71
+ - Automatically cleans up and tears down containers upon completion
72
+
73
+ #### Targeting specific test stages
74
+
75
+ ```bash
76
+ # Run only unit tests
77
+ builder service up test --unit
78
+ # Or shorthand:
79
+ builder service up test-unit
80
+
81
+ # Run only E2E integration tests
82
+ builder service up test --e2e
83
+ # Or shorthand:
84
+ builder service up test-e2e
85
+ ```
86
+
87
+ ---
88
+
89
+ ## 🛠️ Options
90
+
91
+ | Flag | Description |
92
+ |---|---|
93
+ | `--dry-run` | Preview the merged Docker Compose YAML configuration without starting containers |
94
+ | `--debug` | Print the final merged Docker Compose YAML before launching |
95
+ | `--skip-check` | Skip hadolint and conftest infrastructure validation |
96
+ | `-d, --detach` | Run Docker Compose in detached mode (background) |
97
+ | `-C, --project-dir <path>` | Specify target service directory (defaults to current working directory) |
98
+ | `--unit` | For `test`, run only unit test stage |
99
+ | `--e2e` | For `test`, run only e2e test stage |
100
+
101
+ ---
102
+
103
+ ## ⚙️ Configuration (`build.json`)
104
+
105
+ Each service configures its dependencies and overrides via `build.json` in its project root:
106
+
107
+ ```json
108
+ {
109
+ "name": "backend",
110
+ "dependencies": {
111
+ "filesystem": {
112
+ "path": ".docker/mocks/docker-compose.filesystem.yml",
113
+ "service": "mock-filesystem"
114
+ }
115
+ },
116
+ "overrides": {
117
+ "dev": {
118
+ "path": ".docker/overrides/docker-compose.dev.override.yml"
119
+ },
120
+ "test": {
121
+ "path": ".docker/overrides/docker-compose.test.override.yml"
122
+ },
123
+ "prod": {
124
+ "path": ".docker/overrides/docker-compose.prod.override.yml"
125
+ },
126
+ "e2e": {
127
+ "path": ".docker/overrides/docker-compose.e2e.override.yml"
128
+ }
129
+ }
130
+ }
131
+ ```
132
+
133
+ ---
134
+
135
+ ## 💻 Programmatic Usage
136
+
137
+ You can also import `@solid-stack/builder` inside Node.js or TypeScript code:
138
+
139
+ ```typescript
140
+ import {
141
+ compileEnvironment,
142
+ getBuildJson,
143
+ checkInfra,
144
+ handleServiceUp,
145
+ } from "@solid-stack/builder";
146
+
147
+ // Compile Docker Compose YAML for a specific environment
148
+ const devYaml = compileEnvironment("dev", "/path/to/service");
149
+
150
+ // Boot an environment programmatically
151
+ await handleServiceUp("dev", {
152
+ projectDir: "/path/to/service",
153
+ skipCheck: false,
154
+ });
155
+ ```
156
+
157
+ ---
158
+
159
+ ## 📄 License
160
+
161
+ UNLICENSED © Solid Stack Digital