@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.
- package/LICENSE +18 -0
- package/README.md +161 -0
- package/dist/bin.cjs +805 -0
- package/dist/bin.cjs.map +1 -0
- package/dist/bin.d.ts +3 -0
- package/dist/bin.d.ts.map +1 -0
- package/dist/bin.js +795 -0
- package/dist/bin.js.map +1 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/commands/checkInfra.d.ts +2 -0
- package/dist/commands/checkInfra.d.ts.map +1 -0
- package/dist/commands/serviceUp.d.ts +3 -0
- package/dist/commands/serviceUp.d.ts.map +1 -0
- package/dist/core/compileEnvironment.d.ts +3 -0
- package/dist/core/compileEnvironment.d.ts.map +1 -0
- package/dist/core/templates.d.ts +3 -0
- package/dist/core/templates.d.ts.map +1 -0
- package/dist/errors/NotFoundError.d.ts +5 -0
- package/dist/errors/NotFoundError.d.ts.map +1 -0
- package/dist/errors/ScriptError.d.ts +4 -0
- package/dist/errors/ScriptError.d.ts.map +1 -0
- package/dist/index.cjs +814 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +792 -0
- package/dist/index.js.map +1 -0
- package/dist/templates/docker/docker-compose.base.yml +10 -0
- package/dist/templates/docker/docker-compose.dev.yml +11 -0
- package/dist/templates/docker/docker-compose.e2e.yml +9 -0
- package/dist/templates/docker/docker-compose.prod.yml +10 -0
- package/dist/templates/docker/docker-compose.standalone.yml +4 -0
- package/dist/templates/docker/docker-compose.test.yml +10 -0
- package/dist/types/index.d.ts +31 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/utils/checkDependencies.d.ts +2 -0
- package/dist/utils/checkDependencies.d.ts.map +1 -0
- package/dist/utils/extractBuildDeps.d.ts +3 -0
- package/dist/utils/extractBuildDeps.d.ts.map +1 -0
- package/dist/utils/extractOverrides.d.ts +3 -0
- package/dist/utils/extractOverrides.d.ts.map +1 -0
- package/dist/utils/getBuildJson.d.ts +3 -0
- package/dist/utils/getBuildJson.d.ts.map +1 -0
- package/dist/utils/ymlMods/addDependenciesToAppService.d.ts +3 -0
- package/dist/utils/ymlMods/addDependenciesToAppService.d.ts.map +1 -0
- package/dist/utils/ymlMods/attachName.d.ts +2 -0
- package/dist/utils/ymlMods/attachName.d.ts.map +1 -0
- package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts +2 -0
- package/dist/utils/ymlMods/makeE2eDependOnApp.d.ts.map +1 -0
- package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts +3 -0
- package/dist/utils/ymlMods/renameServicesWithDependencies.d.ts.map +1 -0
- package/package.json +75 -0
- package/templates/docker/docker-compose.base.yml +10 -0
- package/templates/docker/docker-compose.dev.yml +11 -0
- package/templates/docker/docker-compose.e2e.yml +9 -0
- package/templates/docker/docker-compose.prod.yml +10 -0
- package/templates/docker/docker-compose.standalone.yml +4 -0
- 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
|