@a5c-ai/cloud 5.0.1-staging.7a8768ec
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 +21 -0
- package/README.md +40 -0
- package/SPEC.md +449 -0
- package/dist/adapters/agent-mux-gateway.d.ts +3 -0
- package/dist/adapters/agent-mux-gateway.d.ts.map +1 -0
- package/dist/adapters/agent-mux-gateway.js +164 -0
- package/dist/adapters/agent-mux-gateway.js.map +1 -0
- package/dist/adapters/babysitter-agent.d.ts +3 -0
- package/dist/adapters/babysitter-agent.d.ts.map +1 -0
- package/dist/adapters/babysitter-agent.js +94 -0
- package/dist/adapters/babysitter-agent.js.map +1 -0
- package/dist/adapters/kanban.d.ts +3 -0
- package/dist/adapters/kanban.d.ts.map +1 -0
- package/dist/adapters/kanban.js +99 -0
- package/dist/adapters/kanban.js.map +1 -0
- package/dist/cli.d.ts +8 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +341 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/kubernetes/render.d.ts +3 -0
- package/dist/kubernetes/render.d.ts.map +1 -0
- package/dist/kubernetes/render.js +64 -0
- package/dist/kubernetes/render.js.map +1 -0
- package/dist/sdk/agents.d.ts +7 -0
- package/dist/sdk/agents.d.ts.map +1 -0
- package/dist/sdk/agents.js +153 -0
- package/dist/sdk/agents.js.map +1 -0
- package/dist/sdk/auth.d.ts +2 -0
- package/dist/sdk/auth.d.ts.map +1 -0
- package/dist/sdk/auth.js +47 -0
- package/dist/sdk/auth.js.map +1 -0
- package/dist/sdk/config.d.ts +5 -0
- package/dist/sdk/config.d.ts.map +1 -0
- package/dist/sdk/config.js +239 -0
- package/dist/sdk/config.js.map +1 -0
- package/dist/sdk/deploy.d.ts +3 -0
- package/dist/sdk/deploy.d.ts.map +1 -0
- package/dist/sdk/deploy.js +170 -0
- package/dist/sdk/deploy.js.map +1 -0
- package/dist/sdk/environments.d.ts +3 -0
- package/dist/sdk/environments.d.ts.map +1 -0
- package/dist/sdk/environments.js +126 -0
- package/dist/sdk/environments.js.map +1 -0
- package/dist/sdk/plans.d.ts +2 -0
- package/dist/sdk/plans.d.ts.map +1 -0
- package/dist/sdk/plans.js +145 -0
- package/dist/sdk/plans.js.map +1 -0
- package/dist/sdk/providers.d.ts +6 -0
- package/dist/sdk/providers.d.ts.map +1 -0
- package/dist/sdk/providers.js +183 -0
- package/dist/sdk/providers.js.map +1 -0
- package/dist/sdk/upgrade.d.ts +2 -0
- package/dist/sdk/upgrade.d.ts.map +1 -0
- package/dist/sdk/upgrade.js +5 -0
- package/dist/sdk/upgrade.js.map +1 -0
- package/dist/terraform/root.d.ts +2 -0
- package/dist/terraform/root.d.ts.map +1 -0
- package/dist/terraform/root.js +168 -0
- package/dist/terraform/root.js.map +1 -0
- package/dist/types.d.ts +341 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/package.json +76 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 a5c-ai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# @a5c-ai/cloud
|
|
2
|
+
|
|
3
|
+
Deployment SDK and CLI for installing Babysitter repo services into Kubernetes.
|
|
4
|
+
|
|
5
|
+
This package implements the spec in [SPEC.md](./SPEC.md) with:
|
|
6
|
+
|
|
7
|
+
- environment-aware config loading and validation
|
|
8
|
+
- deployment plan construction
|
|
9
|
+
- Terraform rendering for Minikube, existing clusters, EKS, AKS, and GKE
|
|
10
|
+
- Kubernetes manifest rendering for `kanban`, `agent-mux-gateway`, and optional `babysitter-agent`
|
|
11
|
+
- install, upgrade, status, auth bootstrap, provider configuration, and agent install workflows
|
|
12
|
+
- a `cloud` CLI built on the SDK
|
|
13
|
+
|
|
14
|
+
Current scope deliberately excludes the separately tracked upstream dependency tickets referenced in the spec.
|
|
15
|
+
|
|
16
|
+
<!-- docs-status:start -->
|
|
17
|
+
> Status: Public package.
|
|
18
|
+
> Canonical docs home: [Package and Plugin Docs Map](../../docs/package-and-plugin-map.md).
|
|
19
|
+
> This README is the canonical package contract until a dedicated docs-site guide exists.
|
|
20
|
+
<!-- docs-status:end -->
|
|
21
|
+
|
|
22
|
+
## Package scripts
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm run build --workspace=@a5c-ai/cloud
|
|
26
|
+
npm run test --workspace=@a5c-ai/cloud
|
|
27
|
+
npm run test:coverage --workspace=@a5c-ai/cloud
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## CLI examples
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
cloud init --env minikube
|
|
34
|
+
cloud plan --env staging --provider eks --set target.region=us-east-1
|
|
35
|
+
cloud render terraform --config cloud.config.json
|
|
36
|
+
cloud render kubernetes --config cloud.config.json
|
|
37
|
+
cloud install --config cloud.config.json --dry-run
|
|
38
|
+
cloud status --config cloud.config.json
|
|
39
|
+
```
|
|
40
|
+
|
package/SPEC.md
ADDED
|
@@ -0,0 +1,449 @@
|
|
|
1
|
+
# `packages/cloud` Spec
|
|
2
|
+
|
|
3
|
+
## 1. Purpose
|
|
4
|
+
|
|
5
|
+
`packages/cloud` will be the deployment control plane for this monorepo.
|
|
6
|
+
|
|
7
|
+
It will ship as a single JavaScript package that exposes:
|
|
8
|
+
|
|
9
|
+
- an SDK for composing deployment plans and environment configurations
|
|
10
|
+
- a CLI for install, upgrade, auth bootstrap, provider setup, and status workflows
|
|
11
|
+
- Terraform rendering/apply support for cluster infrastructure
|
|
12
|
+
- Kubernetes manifest/Helm-style rendering for repo services
|
|
13
|
+
- CI/CD entrypoints for staging and production
|
|
14
|
+
|
|
15
|
+
The package is responsible for making the repo's deployable utilities work together in a Kubernetes environment with minimal manual glue.
|
|
16
|
+
|
|
17
|
+
## 2. Primary Goals
|
|
18
|
+
|
|
19
|
+
1. Deploy repo utilities into Kubernetes as one coherent system.
|
|
20
|
+
2. Support three target modes:
|
|
21
|
+
- local Minikube
|
|
22
|
+
- existing Kubernetes cluster
|
|
23
|
+
- newly created managed cluster on EKS, AKS, or GKE
|
|
24
|
+
3. Support install, upgrade, reconfigure, and drift-aware reconciliation.
|
|
25
|
+
4. Make `agent-mux` Kubernetes mode a first-class deployment option.
|
|
26
|
+
5. Optionally configure `babysitter-agent` providers and model routing.
|
|
27
|
+
6. Optionally install agent binaries and their Babysitter plugins when the target runtime needs them.
|
|
28
|
+
7. Provide a non-local authentication bootstrap path, including a default admin password flow.
|
|
29
|
+
8. Fit existing repo CI/release conventions with staging and production automation.
|
|
30
|
+
|
|
31
|
+
## 3. Non-Goals
|
|
32
|
+
|
|
33
|
+
- Replacing deep runtime logic that belongs in `agent-mux`, `kanban`, or `babysitter-agent`
|
|
34
|
+
- Becoming a general-purpose IaC framework outside this monorepo
|
|
35
|
+
- Owning application business logic for kanban, gateway, or Babysitter orchestration
|
|
36
|
+
- Hiding provider credentials inside the repo; secrets must come from the environment, secret stores, or explicit config files
|
|
37
|
+
|
|
38
|
+
## 4. What Gets Deployed
|
|
39
|
+
|
|
40
|
+
`packages/cloud` should be able to deploy, wire, and upgrade at least these repo surfaces:
|
|
41
|
+
|
|
42
|
+
- `@a5c-ai/kanban`
|
|
43
|
+
- `@a5c-ai/agent-mux-gateway`
|
|
44
|
+
- `@a5c-ai/babysitter-agent` as an optional service/runtime
|
|
45
|
+
- optional observer and supporting runtime components when enabled
|
|
46
|
+
|
|
47
|
+
The baseline topology is:
|
|
48
|
+
|
|
49
|
+
- `kanban` exposed as the primary web UI
|
|
50
|
+
- `agent-mux-gateway` exposed as the session/control gateway for UI and agents
|
|
51
|
+
- persistent storage for gateway token/event state
|
|
52
|
+
- shared config and secret wiring between gateway, kanban, and optional agent services
|
|
53
|
+
- ingress/service definitions so the components work together in-cluster without manual URL/token patching
|
|
54
|
+
|
|
55
|
+
## 5. Supported Deployment Modes
|
|
56
|
+
|
|
57
|
+
### 5.1 Local Minikube
|
|
58
|
+
|
|
59
|
+
Use case:
|
|
60
|
+
|
|
61
|
+
- local dev, demo, smoke tests, end-to-end verification
|
|
62
|
+
|
|
63
|
+
Requirements:
|
|
64
|
+
|
|
65
|
+
- create or reuse a Minikube cluster
|
|
66
|
+
- provision namespace, storage class assumptions, ingress choice, and local DNS/URL hints
|
|
67
|
+
- bootstrap a local admin account/password
|
|
68
|
+
- default to local-friendly settings, reduced resource requests, and local images where possible
|
|
69
|
+
|
|
70
|
+
### 5.2 Existing Cluster
|
|
71
|
+
|
|
72
|
+
Use case:
|
|
73
|
+
|
|
74
|
+
- platform team already provides Kubernetes
|
|
75
|
+
|
|
76
|
+
Requirements:
|
|
77
|
+
|
|
78
|
+
- no cluster creation
|
|
79
|
+
- validate context, namespace, ingress class, storage class, and secret prerequisites
|
|
80
|
+
- install or upgrade only repo workloads
|
|
81
|
+
- support dry-run and render-only modes before apply
|
|
82
|
+
|
|
83
|
+
### 5.3 New Managed Cluster
|
|
84
|
+
|
|
85
|
+
Providers:
|
|
86
|
+
|
|
87
|
+
- AWS EKS
|
|
88
|
+
- Azure AKS
|
|
89
|
+
- Google GKE (request used `gks`; package should accept `gks` as a friendly alias)
|
|
90
|
+
|
|
91
|
+
Requirements:
|
|
92
|
+
|
|
93
|
+
- Terraform module selection by provider
|
|
94
|
+
- provider-specific auth/bootstrap config
|
|
95
|
+
- cluster + node pool creation
|
|
96
|
+
- kubeconfig/context handoff into app deployment stage
|
|
97
|
+
- staging/prod preset support
|
|
98
|
+
|
|
99
|
+
## 6. Package Shape
|
|
100
|
+
|
|
101
|
+
This package should eventually be a normal workspace package named `@a5c-ai/cloud`.
|
|
102
|
+
|
|
103
|
+
Proposed implementation layout:
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
packages/cloud/
|
|
107
|
+
README.md
|
|
108
|
+
SPEC.md
|
|
109
|
+
package.json
|
|
110
|
+
tsconfig.json
|
|
111
|
+
src/
|
|
112
|
+
index.ts
|
|
113
|
+
cli.ts
|
|
114
|
+
sdk/
|
|
115
|
+
config.ts
|
|
116
|
+
environments.ts
|
|
117
|
+
plans.ts
|
|
118
|
+
deploy.ts
|
|
119
|
+
upgrade.ts
|
|
120
|
+
auth.ts
|
|
121
|
+
providers.ts
|
|
122
|
+
agents.ts
|
|
123
|
+
terraform/
|
|
124
|
+
root.ts
|
|
125
|
+
modules/
|
|
126
|
+
minikube/
|
|
127
|
+
eks/
|
|
128
|
+
aks/
|
|
129
|
+
gke/
|
|
130
|
+
kubernetes/
|
|
131
|
+
manifests/
|
|
132
|
+
values/
|
|
133
|
+
render.ts
|
|
134
|
+
adapters/
|
|
135
|
+
kanban.ts
|
|
136
|
+
agent-mux-gateway.ts
|
|
137
|
+
babysitter-agent.ts
|
|
138
|
+
tests/
|
|
139
|
+
unit/
|
|
140
|
+
integration/
|
|
141
|
+
fixtures/
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## 7. SDK Contract
|
|
145
|
+
|
|
146
|
+
The SDK should be programmatic first. The CLI should be a thin wrapper over SDK actions.
|
|
147
|
+
|
|
148
|
+
Core SDK surface:
|
|
149
|
+
|
|
150
|
+
- `loadCloudConfig(input)`
|
|
151
|
+
- `validateCloudConfig(config)`
|
|
152
|
+
- `buildDeploymentPlan(config)`
|
|
153
|
+
- `renderTerraform(plan)`
|
|
154
|
+
- `applyTerraform(plan)`
|
|
155
|
+
- `renderKubernetes(plan)`
|
|
156
|
+
- `applyKubernetes(plan)`
|
|
157
|
+
- `installEnvironment(config)`
|
|
158
|
+
- `upgradeEnvironment(config)`
|
|
159
|
+
- `bootstrapAuth(config)`
|
|
160
|
+
- `configureProviders(config)`
|
|
161
|
+
- `installAgents(config)`
|
|
162
|
+
- `getEnvironmentStatus(config)`
|
|
163
|
+
|
|
164
|
+
The SDK must return structured results, not only console strings.
|
|
165
|
+
|
|
166
|
+
## 8. CLI Contract
|
|
167
|
+
|
|
168
|
+
Proposed CLI:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
cloud init
|
|
172
|
+
cloud plan
|
|
173
|
+
cloud install
|
|
174
|
+
cloud upgrade
|
|
175
|
+
cloud status
|
|
176
|
+
cloud auth bootstrap
|
|
177
|
+
cloud providers configure
|
|
178
|
+
cloud agents install
|
|
179
|
+
cloud render terraform
|
|
180
|
+
cloud render kubernetes
|
|
181
|
+
cloud cluster create
|
|
182
|
+
cloud cluster destroy
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Important flags:
|
|
186
|
+
|
|
187
|
+
- `--env <local|minikube|staging|prod>`
|
|
188
|
+
- `--provider <minikube|existing|eks|aks|gke|gks>`
|
|
189
|
+
- `--cluster-name <name>`
|
|
190
|
+
- `--namespace <name>`
|
|
191
|
+
- `--config <path>`
|
|
192
|
+
- `--set key=value`
|
|
193
|
+
- `--dry-run`
|
|
194
|
+
- `--render-only`
|
|
195
|
+
- `--upgrade`
|
|
196
|
+
- `--install-agents`
|
|
197
|
+
- `--configure-providers`
|
|
198
|
+
|
|
199
|
+
## 9. Configuration Model
|
|
200
|
+
|
|
201
|
+
The package needs one canonical config model with layered overrides:
|
|
202
|
+
|
|
203
|
+
1. built-in defaults
|
|
204
|
+
2. environment preset
|
|
205
|
+
3. config file
|
|
206
|
+
4. CLI flags / explicit overrides
|
|
207
|
+
5. secret references / environment variables
|
|
208
|
+
|
|
209
|
+
Proposed top-level config shape:
|
|
210
|
+
|
|
211
|
+
```ts
|
|
212
|
+
interface CloudConfig {
|
|
213
|
+
environment: "minikube" | "staging" | "prod" | "custom";
|
|
214
|
+
target:
|
|
215
|
+
| { type: "minikube"; profile?: string }
|
|
216
|
+
| { type: "existing"; kubeContext: string; namespace: string }
|
|
217
|
+
| { type: "eks"; region: string; clusterName: string }
|
|
218
|
+
| { type: "aks"; subscriptionId: string; resourceGroup: string; clusterName: string }
|
|
219
|
+
| { type: "gke"; projectId: string; region: string; clusterName: string };
|
|
220
|
+
ingress: {
|
|
221
|
+
hostnames: string[];
|
|
222
|
+
tls?: boolean;
|
|
223
|
+
ingressClassName?: string;
|
|
224
|
+
};
|
|
225
|
+
auth: {
|
|
226
|
+
mode: "local-dev" | "bootstrap-admin";
|
|
227
|
+
adminUsername: string;
|
|
228
|
+
adminPasswordSecretRef?: string;
|
|
229
|
+
defaultAdminPassword?: string;
|
|
230
|
+
};
|
|
231
|
+
components: {
|
|
232
|
+
kanban: { enabled: boolean; replicas?: number };
|
|
233
|
+
gateway: { enabled: boolean; replicas?: number };
|
|
234
|
+
babysitterAgent?: {
|
|
235
|
+
enabled: boolean;
|
|
236
|
+
providers?: ProviderConfig[];
|
|
237
|
+
modelRouting?: ModelRoutingConfig[];
|
|
238
|
+
};
|
|
239
|
+
};
|
|
240
|
+
agents?: {
|
|
241
|
+
install: boolean;
|
|
242
|
+
targets: Array<"claude-code" | "codex" | "cursor" | "copilot" | "gemini-cli" | "opencode">;
|
|
243
|
+
installBabysitterPlugins: boolean;
|
|
244
|
+
};
|
|
245
|
+
storage: {
|
|
246
|
+
className?: string;
|
|
247
|
+
gatewayStateSize?: string;
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
## 10. Deployment Architecture
|
|
253
|
+
|
|
254
|
+
### 10.1 Kubernetes Resources
|
|
255
|
+
|
|
256
|
+
Baseline resources:
|
|
257
|
+
|
|
258
|
+
- namespace
|
|
259
|
+
- service accounts and RBAC where required
|
|
260
|
+
- config maps
|
|
261
|
+
- secrets
|
|
262
|
+
- persistent volume claims for gateway state and any durable app state
|
|
263
|
+
- deployments/statefulsets as appropriate
|
|
264
|
+
- services
|
|
265
|
+
- ingress
|
|
266
|
+
- network policies when enabled
|
|
267
|
+
|
|
268
|
+
### 10.2 App Wiring
|
|
269
|
+
|
|
270
|
+
The deployment package must own the cross-service wiring:
|
|
271
|
+
|
|
272
|
+
- kanban receives the gateway base URL automatically
|
|
273
|
+
- gateway receives storage paths and auth bootstrap config automatically
|
|
274
|
+
- optional babysitter-agent receives gateway URL, provider config, and model config automatically
|
|
275
|
+
- agent-mux Kubernetes invocation mode is selectable in generated runtime config
|
|
276
|
+
|
|
277
|
+
### 10.3 Auth Bootstrap
|
|
278
|
+
|
|
279
|
+
For non-local installs:
|
|
280
|
+
|
|
281
|
+
- the system must support a bootstrap admin identity with a default admin password flow
|
|
282
|
+
- bootstrap secrets must be injectable through Kubernetes secrets or cloud secret managers
|
|
283
|
+
- first-run token issuance should be automatable for kanban/gateway integration
|
|
284
|
+
|
|
285
|
+
Open dependency:
|
|
286
|
+
|
|
287
|
+
- current gateway auth is bearer-token based and does not yet expose a password/admin bootstrap workflow suitable for this package
|
|
288
|
+
|
|
289
|
+
## 11. Upgrade Model
|
|
290
|
+
|
|
291
|
+
`packages/cloud` must support:
|
|
292
|
+
|
|
293
|
+
- first install
|
|
294
|
+
- idempotent re-apply
|
|
295
|
+
- in-place upgrade
|
|
296
|
+
- version-pinned deploys
|
|
297
|
+
- rollback-ready plan output
|
|
298
|
+
|
|
299
|
+
Upgrade sequence:
|
|
300
|
+
|
|
301
|
+
1. validate target and config
|
|
302
|
+
2. render desired infra/app state
|
|
303
|
+
3. diff cluster and infra state
|
|
304
|
+
4. apply infra changes
|
|
305
|
+
5. apply app changes
|
|
306
|
+
6. run smoke checks
|
|
307
|
+
7. report versions, endpoints, and auth bootstrap outputs
|
|
308
|
+
|
|
309
|
+
## 12. Provider and Model Configuration
|
|
310
|
+
|
|
311
|
+
Optional `babysitter-agent` setup should support:
|
|
312
|
+
|
|
313
|
+
- provider credentials references
|
|
314
|
+
- provider enable/disable lists
|
|
315
|
+
- default provider selection
|
|
316
|
+
- model routing/preset configuration
|
|
317
|
+
- environment-specific model defaults
|
|
318
|
+
|
|
319
|
+
This should be represented as declarative config, not one-off shell scripts.
|
|
320
|
+
|
|
321
|
+
Open dependency:
|
|
322
|
+
|
|
323
|
+
- some provider/model automation may require new non-interactive config surfaces in `babysitter-agent` and/or `agent-mux`
|
|
324
|
+
|
|
325
|
+
## 13. Optional Agent + Plugin Installation
|
|
326
|
+
|
|
327
|
+
Optional install flow should support:
|
|
328
|
+
|
|
329
|
+
- agent binary installation where appropriate
|
|
330
|
+
- installation validation
|
|
331
|
+
- Babysitter plugin installation for selected harnesses
|
|
332
|
+
- reporting of installed vs skipped harnesses
|
|
333
|
+
|
|
334
|
+
Expected initial targets:
|
|
335
|
+
|
|
336
|
+
- Claude Code
|
|
337
|
+
- Codex
|
|
338
|
+
- Cursor
|
|
339
|
+
- Gemini CLI
|
|
340
|
+
- GitHub Copilot
|
|
341
|
+
- OpenCode
|
|
342
|
+
|
|
343
|
+
Open dependency:
|
|
344
|
+
|
|
345
|
+
- cloud-safe, non-interactive install/config workflows are not yet standardized across all harness/plugin combinations
|
|
346
|
+
|
|
347
|
+
## 14. CI/CD Integration
|
|
348
|
+
|
|
349
|
+
The package must hook into existing repo automation with:
|
|
350
|
+
|
|
351
|
+
- workspace build
|
|
352
|
+
- unit tests
|
|
353
|
+
- integration tests
|
|
354
|
+
- coverage threshold enforcement
|
|
355
|
+
- staging deploy entrypoints
|
|
356
|
+
- production deploy entrypoints
|
|
357
|
+
|
|
358
|
+
Expected repo-level additions:
|
|
359
|
+
|
|
360
|
+
- root scripts for `build:cloud`, `test:cloud`, and coverage validation
|
|
361
|
+
- CI workflow coverage for the new workspace
|
|
362
|
+
- staging/prod workflow integration for rendering/apply/deploy
|
|
363
|
+
|
|
364
|
+
## 15. Testing Strategy
|
|
365
|
+
|
|
366
|
+
Required test layers:
|
|
367
|
+
|
|
368
|
+
- unit tests for config loading, plan generation, and rendering
|
|
369
|
+
- fixture-based tests for Terraform and Kubernetes output
|
|
370
|
+
- Minikube integration tests for install and upgrade flows
|
|
371
|
+
- smoke tests for auth bootstrap and basic kanban/gateway connectivity
|
|
372
|
+
- coverage checks in CI
|
|
373
|
+
|
|
374
|
+
Suggested minimum scripts:
|
|
375
|
+
|
|
376
|
+
```json
|
|
377
|
+
{
|
|
378
|
+
"scripts": {
|
|
379
|
+
"build": "tsc --build",
|
|
380
|
+
"test": "vitest run",
|
|
381
|
+
"test:coverage": "vitest run --coverage",
|
|
382
|
+
"test:integration": "vitest run tests/integration",
|
|
383
|
+
"lint": "eslint \"src/**/*.ts\" --max-warnings=0"
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
## 16. Ownership Boundaries
|
|
389
|
+
|
|
390
|
+
### `packages/cloud` owns
|
|
391
|
+
|
|
392
|
+
- deployment planning
|
|
393
|
+
- Terraform orchestration
|
|
394
|
+
- Kubernetes rendering/apply
|
|
395
|
+
- environment presets
|
|
396
|
+
- cross-package wiring
|
|
397
|
+
- staged/prod deploy automation entrypoints
|
|
398
|
+
|
|
399
|
+
### Existing packages should continue to own
|
|
400
|
+
|
|
401
|
+
- gateway auth/runtime semantics
|
|
402
|
+
- kanban application behavior
|
|
403
|
+
- babysitter-agent orchestration/runtime behavior
|
|
404
|
+
- agent-mux adapter capabilities and installation semantics
|
|
405
|
+
|
|
406
|
+
## 17. Dependency Gaps Identified During Spec
|
|
407
|
+
|
|
408
|
+
The following areas should be tracked outside `packages/cloud` implementation:
|
|
409
|
+
|
|
410
|
+
1. `agent-mux-gateway` needs a bootstrap admin/password-based auth story suitable for cloud deployments.
|
|
411
|
+
Tracking: `ACA-234`
|
|
412
|
+
2. `kanban` needs cloud bootstrap behavior so it can connect to a provisioned gateway without manual local-storage token pasting as the only path.
|
|
413
|
+
Tracking: `ACA-235`
|
|
414
|
+
3. `babysitter-agent` and/or `agent-mux` need stronger non-interactive provider/model and harness/plugin installation/configuration surfaces.
|
|
415
|
+
Tracking: `ACA-236`
|
|
416
|
+
4. Root CI/release automation needs explicit support for the new cloud workspace.
|
|
417
|
+
Tracking: `ACA-237`
|
|
418
|
+
|
|
419
|
+
## 18. Implementation Phasing
|
|
420
|
+
|
|
421
|
+
### Phase 1
|
|
422
|
+
|
|
423
|
+
- create package workspace
|
|
424
|
+
- implement config loader and plan model
|
|
425
|
+
- support Minikube and existing-cluster render-only/install flows
|
|
426
|
+
- deploy gateway + kanban
|
|
427
|
+
|
|
428
|
+
### Phase 2
|
|
429
|
+
|
|
430
|
+
- add managed cluster Terraform for EKS, AKS, GKE
|
|
431
|
+
- add upgrade and smoke-check flows
|
|
432
|
+
- add auth bootstrap integration
|
|
433
|
+
|
|
434
|
+
### Phase 3
|
|
435
|
+
|
|
436
|
+
- add optional babysitter-agent provider/model setup
|
|
437
|
+
- add optional harness/plugin install flow
|
|
438
|
+
- wire staging/prod pipelines
|
|
439
|
+
|
|
440
|
+
## 19. Acceptance Criteria
|
|
441
|
+
|
|
442
|
+
The package is ready for initial rollout when all of the following are true:
|
|
443
|
+
|
|
444
|
+
1. A user can create or reuse a Minikube cluster and install kanban + gateway with one CLI command.
|
|
445
|
+
2. A user can target an existing cluster with a declarative config file and get an idempotent install/upgrade.
|
|
446
|
+
3. A user can create an EKS, AKS, or GKE cluster and deploy the app stack from the same package.
|
|
447
|
+
4. Non-local installs have an explicit bootstrap admin password flow.
|
|
448
|
+
5. CI runs unit tests plus coverage checks for the workspace.
|
|
449
|
+
6. Staging and production automation can invoke the package without manual command editing.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { AuthBootstrapResult, CloudConfig, ComponentPlan, KubernetesManifest } from "../types.js";
|
|
2
|
+
export declare function buildGatewayPlan(config: CloudConfig, releaseTag: string, publicUrl: string | undefined): ComponentPlan;
|
|
3
|
+
export declare function buildGatewayManifests(config: CloudConfig, plan: ComponentPlan, auth: AuthBootstrapResult): readonly KubernetesManifest[];
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agent-mux-gateway.d.ts","sourceRoot":"","sources":["../../src/adapters/agent-mux-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMvG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAkBtH;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,mBAAmB,GAAG,SAAS,kBAAkB,EAAE,CA6IxI"}
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
function resolveImage(config, releaseTag) {
|
|
2
|
+
return config.images?.gateway ?? `${config.imageRegistry ?? "ghcr.io/a5c-ai/babysitter"}/agent-mux:${releaseTag}`;
|
|
3
|
+
}
|
|
4
|
+
export function buildGatewayPlan(config, releaseTag, publicUrl) {
|
|
5
|
+
return {
|
|
6
|
+
id: "gateway",
|
|
7
|
+
enabled: config.components.gateway.enabled,
|
|
8
|
+
image: {
|
|
9
|
+
image: resolveImage(config, releaseTag),
|
|
10
|
+
pullPolicy: "IfNotPresent",
|
|
11
|
+
},
|
|
12
|
+
replicas: config.components.gateway.replicas ?? 1,
|
|
13
|
+
serviceName: "agent-mux-gateway",
|
|
14
|
+
port: 7878,
|
|
15
|
+
internalUrl: "http://agent-mux-gateway:7878",
|
|
16
|
+
...(publicUrl ? { publicUrl } : {}),
|
|
17
|
+
summary: [
|
|
18
|
+
"agent-mux gateway exposed through service `agent-mux-gateway`",
|
|
19
|
+
"runs with SQLite token store and persistent event log volume",
|
|
20
|
+
],
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
export function buildGatewayManifests(config, plan, auth) {
|
|
24
|
+
if (!plan.enabled) {
|
|
25
|
+
return [];
|
|
26
|
+
}
|
|
27
|
+
return [
|
|
28
|
+
{
|
|
29
|
+
apiVersion: "v1",
|
|
30
|
+
kind: "PersistentVolumeClaim",
|
|
31
|
+
metadata: {
|
|
32
|
+
name: `${plan.serviceName}-state`,
|
|
33
|
+
namespace: config.namespace,
|
|
34
|
+
},
|
|
35
|
+
spec: {
|
|
36
|
+
accessModes: ["ReadWriteOnce"],
|
|
37
|
+
...(config.storage.className ? { storageClassName: config.storage.className } : {}),
|
|
38
|
+
resources: {
|
|
39
|
+
requests: {
|
|
40
|
+
storage: config.storage.gatewayStateSize ?? "5Gi",
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
apiVersion: "apps/v1",
|
|
47
|
+
kind: "Deployment",
|
|
48
|
+
metadata: {
|
|
49
|
+
name: plan.serviceName,
|
|
50
|
+
namespace: config.namespace,
|
|
51
|
+
labels: {
|
|
52
|
+
"app.kubernetes.io/name": plan.serviceName,
|
|
53
|
+
"app.kubernetes.io/component": "gateway",
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
spec: {
|
|
57
|
+
replicas: plan.replicas,
|
|
58
|
+
selector: {
|
|
59
|
+
matchLabels: {
|
|
60
|
+
"app.kubernetes.io/name": plan.serviceName,
|
|
61
|
+
},
|
|
62
|
+
},
|
|
63
|
+
template: {
|
|
64
|
+
metadata: {
|
|
65
|
+
labels: {
|
|
66
|
+
"app.kubernetes.io/name": plan.serviceName,
|
|
67
|
+
"app.kubernetes.io/component": "gateway",
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
spec: {
|
|
71
|
+
containers: [
|
|
72
|
+
{
|
|
73
|
+
name: "gateway",
|
|
74
|
+
image: plan.image.image,
|
|
75
|
+
imagePullPolicy: plan.image.pullPolicy,
|
|
76
|
+
command: ["amux"],
|
|
77
|
+
args: [
|
|
78
|
+
"gateway",
|
|
79
|
+
"serve",
|
|
80
|
+
"--host",
|
|
81
|
+
"0.0.0.0",
|
|
82
|
+
"--port",
|
|
83
|
+
String(plan.port),
|
|
84
|
+
"--no-webui",
|
|
85
|
+
],
|
|
86
|
+
ports: [{ containerPort: plan.port, name: "http" }],
|
|
87
|
+
env: [
|
|
88
|
+
{ name: "AMUX_GATEWAY_TOKEN_DB_PATH", value: "/var/lib/amux-gateway/tokens.db" },
|
|
89
|
+
{ name: "AMUX_GATEWAY_EVENT_LOG_DIR", value: "/var/lib/amux-gateway/events" },
|
|
90
|
+
{ name: "AMUX_GATEWAY_BOOTSTRAP_AUTH_MODE", value: config.auth.mode },
|
|
91
|
+
{
|
|
92
|
+
name: "AMUX_GATEWAY_BOOTSTRAP_ADMIN_USERNAME",
|
|
93
|
+
valueFrom: {
|
|
94
|
+
secretKeyRef: {
|
|
95
|
+
name: auth.secretName,
|
|
96
|
+
key: "ADMIN_USERNAME",
|
|
97
|
+
},
|
|
98
|
+
},
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
name: "AMUX_GATEWAY_BOOTSTRAP_ADMIN_PASSWORD",
|
|
102
|
+
valueFrom: {
|
|
103
|
+
secretKeyRef: {
|
|
104
|
+
name: auth.secretName,
|
|
105
|
+
key: "ADMIN_PASSWORD",
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
name: "AMUX_GATEWAY_BOOTSTRAP_TOKEN_SEED",
|
|
111
|
+
valueFrom: {
|
|
112
|
+
secretKeyRef: {
|
|
113
|
+
name: auth.secretName,
|
|
114
|
+
key: "ADMIN_TOKEN_SEED",
|
|
115
|
+
},
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
{ name: "CLOUD_BOOTSTRAP_AUTH_SECRET", value: auth.secretName },
|
|
119
|
+
{ name: "CLOUD_BOOTSTRAP_ADMIN_USERNAME", value: auth.username },
|
|
120
|
+
{ name: "CLOUD_BOOTSTRAP_AUTH_MODE", value: config.auth.mode },
|
|
121
|
+
],
|
|
122
|
+
volumeMounts: [
|
|
123
|
+
{
|
|
124
|
+
name: "gateway-state",
|
|
125
|
+
mountPath: "/var/lib/amux-gateway",
|
|
126
|
+
},
|
|
127
|
+
],
|
|
128
|
+
},
|
|
129
|
+
],
|
|
130
|
+
volumes: [
|
|
131
|
+
{
|
|
132
|
+
name: "gateway-state",
|
|
133
|
+
persistentVolumeClaim: {
|
|
134
|
+
claimName: `${plan.serviceName}-state`,
|
|
135
|
+
},
|
|
136
|
+
},
|
|
137
|
+
],
|
|
138
|
+
},
|
|
139
|
+
},
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
{
|
|
143
|
+
apiVersion: "v1",
|
|
144
|
+
kind: "Service",
|
|
145
|
+
metadata: {
|
|
146
|
+
name: plan.serviceName,
|
|
147
|
+
namespace: config.namespace,
|
|
148
|
+
},
|
|
149
|
+
spec: {
|
|
150
|
+
selector: {
|
|
151
|
+
"app.kubernetes.io/name": plan.serviceName,
|
|
152
|
+
},
|
|
153
|
+
ports: [
|
|
154
|
+
{
|
|
155
|
+
name: "http",
|
|
156
|
+
port: plan.port,
|
|
157
|
+
targetPort: plan.port,
|
|
158
|
+
},
|
|
159
|
+
],
|
|
160
|
+
},
|
|
161
|
+
},
|
|
162
|
+
];
|
|
163
|
+
}
|
|
164
|
+
//# sourceMappingURL=agent-mux-gateway.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agent-mux-gateway.js","sourceRoot":"","sources":["../../src/adapters/agent-mux-gateway.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { CloudConfig, ComponentPlan, KubernetesManifest, ProviderConfigurationResult } from "../types.js";
|
|
2
|
+
export declare function buildBabysitterAgentPlan(config: CloudConfig, releaseTag: string): ComponentPlan;
|
|
3
|
+
export declare function buildBabysitterAgentManifests(config: CloudConfig, plan: ComponentPlan, gatewayInternalUrl: string, providers: ProviderConfigurationResult): readonly KubernetesManifest[];
|