@openpalm/lib 0.10.2 → 0.11.0-beta.10

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 (63) hide show
  1. package/README.md +4 -2
  2. package/package.json +11 -3
  3. package/src/control-plane/akm-vault.test.ts +105 -0
  4. package/src/control-plane/akm-vault.ts +311 -0
  5. package/src/control-plane/channels.ts +11 -9
  6. package/src/control-plane/cleanup-guardrails.test.ts +8 -9
  7. package/src/control-plane/compose-args.test.ts +25 -33
  8. package/src/control-plane/compose-args.ts +0 -4
  9. package/src/control-plane/compose-errors.test.ts +106 -0
  10. package/src/control-plane/compose-errors.ts +117 -0
  11. package/src/control-plane/config-persistence.ts +148 -73
  12. package/src/control-plane/core-assets.test.ts +104 -0
  13. package/src/control-plane/core-assets.ts +111 -58
  14. package/src/control-plane/docker.ts +70 -25
  15. package/src/control-plane/env.test.ts +25 -1
  16. package/src/control-plane/env.ts +84 -1
  17. package/src/control-plane/home.ts +66 -69
  18. package/src/control-plane/host-opencode.test.ts +260 -0
  19. package/src/control-plane/host-opencode.ts +229 -0
  20. package/src/control-plane/install-edge-cases.test.ts +190 -292
  21. package/src/control-plane/install-lock.ts +157 -0
  22. package/src/control-plane/lifecycle.ts +65 -75
  23. package/src/control-plane/markdown-task.ts +200 -0
  24. package/src/control-plane/migrate-0110.test.ts +177 -0
  25. package/src/control-plane/migrate-0110.ts +99 -0
  26. package/src/control-plane/operator-ids.test.ts +130 -0
  27. package/src/control-plane/operator-ids.ts +89 -0
  28. package/src/control-plane/paths.ts +80 -0
  29. package/src/control-plane/provider-models.ts +154 -0
  30. package/src/control-plane/registry-components.test.ts +105 -27
  31. package/src/control-plane/registry.test.ts +247 -51
  32. package/src/control-plane/registry.ts +404 -54
  33. package/src/control-plane/rollback.ts +17 -16
  34. package/src/control-plane/scheduler.ts +75 -262
  35. package/src/control-plane/secret-mappings.ts +4 -8
  36. package/src/control-plane/secrets.ts +97 -55
  37. package/src/control-plane/setup-config.schema.json +5 -17
  38. package/src/control-plane/setup-status.ts +9 -29
  39. package/src/control-plane/setup-validation.ts +23 -23
  40. package/src/control-plane/setup.test.ts +143 -244
  41. package/src/control-plane/setup.ts +216 -133
  42. package/src/control-plane/skeleton-guardrail.test.ts +151 -0
  43. package/src/control-plane/spec-to-env.test.ts +75 -60
  44. package/src/control-plane/spec-to-env.ts +68 -153
  45. package/src/control-plane/stack-spec.test.ts +22 -84
  46. package/src/control-plane/stack-spec.ts +9 -89
  47. package/src/control-plane/types.ts +9 -29
  48. package/src/control-plane/ui-assets.ts +385 -0
  49. package/src/control-plane/validate.ts +44 -79
  50. package/src/index.ts +102 -56
  51. package/src/logger.test.ts +228 -0
  52. package/src/logger.ts +71 -1
  53. package/src/provider-constants.ts +22 -1
  54. package/src/control-plane/audit.ts +0 -40
  55. package/src/control-plane/env-schema-validation.test.ts +0 -118
  56. package/src/control-plane/lock.test.ts +0 -194
  57. package/src/control-plane/lock.ts +0 -176
  58. package/src/control-plane/memory-config.ts +0 -298
  59. package/src/control-plane/provider-config.ts +0 -34
  60. package/src/control-plane/redact-schema.ts +0 -50
  61. package/src/control-plane/secret-backend.test.ts +0 -359
  62. package/src/control-plane/secret-backend.ts +0 -322
  63. package/src/control-plane/spec-validator.ts +0 -159
package/README.md CHANGED
@@ -3,6 +3,8 @@
3
3
  Shared control-plane library for OpenPalm.
4
4
  CLI, admin, and scheduler use this package so stack behavior stays consistent.
5
5
 
6
+ > **Bun required.** This package ships TypeScript source and relies on Bun's native TS execution. It does not compile to JavaScript and is not compatible with Node.js.
7
+
6
8
  The current model is direct-write over `~/.openpalm/` plus native Docker Compose.
7
9
  Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
8
10
 
@@ -19,7 +21,7 @@ Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
19
21
  ## Important context
20
22
 
21
23
  - Some filenames still use legacy names like `staging`; those modules now support the direct-write compose model
22
- - `config/` is user-owned, `vault/stack/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
24
+ - `config/` is user-owned, `config/stack/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
23
25
  - New reusable control-plane logic belongs here, not duplicated in consumers
24
26
 
25
27
  ## Main module areas
@@ -30,7 +32,7 @@ Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
30
32
  | `control-plane/env` and `control-plane/secrets` | Read, merge, and patch env files |
31
33
  | `control-plane/lifecycle` and `control-plane/docker` | Compose operations and stack lifecycle helpers |
32
34
  | `control-plane/channels` and `control-plane/components` | Addon discovery and install/uninstall logic |
33
- | `control-plane/memory-config` | Memory service configuration helpers |
35
+ | `control-plane/provider-models` | Provider model discovery helpers |
34
36
  | `control-plane/scheduler` | Automation parsing and scheduler helpers |
35
37
  | `logger` | Shared structured logger |
36
38
 
package/package.json CHANGED
@@ -1,12 +1,16 @@
1
1
  {
2
2
  "name": "@openpalm/lib",
3
- "version": "0.10.2",
3
+ "version": "0.11.0-beta.10",
4
4
  "license": "MPL-2.0",
5
5
  "type": "module",
6
6
  "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",
7
+ "engines": {
8
+ "bun": ">=1.0.0"
9
+ },
7
10
  "scripts": {
8
11
  "test": "bun test"
9
12
  },
13
+ "types": "./src/index.ts",
10
14
  "exports": {
11
15
  ".": "./src/index.ts",
12
16
  "./provider-constants": "./src/provider-constants.ts",
@@ -23,8 +27,12 @@
23
27
  "directory": "packages/lib"
24
28
  },
25
29
  "dependencies": {
26
- "croner": "^9.0.0",
27
- "dotenv": "^16.4.7",
30
+ "dotenv": "^17.4.2",
31
+ "tar": "^7.5.15",
28
32
  "yaml": "^2.8.0"
33
+ },
34
+ "devDependencies": {
35
+ "@types/tar": "^7.0.87",
36
+ "bun-types": "^1.3.14"
29
37
  }
30
38
  }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Tests for the akm vault helpers. The vault helpers spawn `akm vault set
3
+ * <ref> <key>` and feed the secret VALUE on stdin (akm-cli >= 0.8.0).
4
+ *
5
+ * Tests gate on the akm CLI being on PATH so the suite stays green in
6
+ * environments without akm installed.
7
+ */
8
+ import { describe, expect, it, beforeEach, afterEach, mock } from "bun:test";
9
+ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
10
+ import { tmpdir } from "node:os";
11
+ import { join } from "node:path";
12
+ import { execFileSync } from "node:child_process";
13
+ import {
14
+ ensureAkmUserVault,
15
+ readAkmUserVaultFile,
16
+ writeAkmVaultKey,
17
+ deleteAkmVaultKey,
18
+ AKM_USER_VAULT_REF,
19
+ } from "./akm-vault.js";
20
+ import type { ControlPlaneState } from "./types.js";
21
+
22
+ function makeState(homeDir: string): ControlPlaneState {
23
+ return {
24
+ homeDir,
25
+ configDir: join(homeDir, "config"),
26
+ stashDir: join(homeDir, "stash"),
27
+ workspaceDir: join(homeDir, "workspace"),
28
+ cacheDir: join(homeDir, "cache"),
29
+ stateDir: join(homeDir, "state"),
30
+ stackDir: join(homeDir, "stack"),
31
+ services: {},
32
+ artifacts: { compose: "" },
33
+ artifactMeta: [],
34
+ };
35
+ }
36
+
37
+ function hasAkmCli(): boolean {
38
+ try {
39
+ execFileSync("akm", ["--version"], { stdio: "ignore" });
40
+ return true;
41
+ } catch {
42
+ return false;
43
+ }
44
+ }
45
+
46
+ const AKM_AVAILABLE = hasAkmCli();
47
+
48
+
49
+ describe("writeAkmVaultKey", () => {
50
+ let homeDir: string;
51
+ let state: ControlPlaneState;
52
+
53
+ beforeEach(() => {
54
+ homeDir = mkdtempSync(join(tmpdir(), "openpalm-akm-write-"));
55
+ state = makeState(homeDir);
56
+ mkdirSync(state.stashDir, { recursive: true });
57
+ mkdirSync(`${state.stateDir}/cache/akm`, { recursive: true });
58
+ });
59
+
60
+ afterEach(() => {
61
+ rmSync(homeDir, { recursive: true, force: true });
62
+ });
63
+
64
+ it.skipIf(!AKM_AVAILABLE)("writes a key via `akm vault set` (stdin mode, no argv leak)", async () => {
65
+ const value = "argv-free-secret-9988";
66
+ const ok = await writeAkmVaultKey(state, "TOKEN", value);
67
+ expect(ok).toBe(true);
68
+
69
+ const vaultPath = await ensureAkmUserVault(state);
70
+ expect(vaultPath).not.toBeNull();
71
+ if (vaultPath) {
72
+ const stored = readAkmUserVaultFile(vaultPath);
73
+ expect(stored.TOKEN).toBe(value);
74
+ }
75
+ });
76
+
77
+ it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey removes a key via `akm vault unset`", async () => {
78
+ await writeAkmVaultKey(state, "TOKEN_A", "value-a");
79
+ await writeAkmVaultKey(state, "TOKEN_B", "value-b");
80
+
81
+ const ok = await deleteAkmVaultKey(state, "TOKEN_A");
82
+ expect(ok).toBe(true);
83
+
84
+ const vaultPath = await ensureAkmUserVault(state);
85
+ if (vaultPath) {
86
+ const stored = readAkmUserVaultFile(vaultPath);
87
+ expect(stored.TOKEN_A).toBeUndefined();
88
+ expect(stored.TOKEN_B).toBe("value-b");
89
+ }
90
+ });
91
+
92
+ it.skipIf(!AKM_AVAILABLE)("deleteAkmVaultKey is idempotent on a missing key", async () => {
93
+ // Deleting a key that was never set should not throw — `akm vault unset`
94
+ // either exits 0 or emits a "not found" message we tolerate.
95
+ const ok = await deleteAkmVaultKey(state, "NEVER_SET_KEY");
96
+ expect(ok).toBe(true);
97
+ });
98
+ });
99
+
100
+
101
+ describe("AKM_USER_VAULT_REF", () => {
102
+ it("exports the canonical akm ref string", () => {
103
+ expect(AKM_USER_VAULT_REF).toBe("vault:user");
104
+ });
105
+ });
@@ -0,0 +1,311 @@
1
+ /// <reference types="bun-types" />
2
+ /**
3
+ * akm `vault:user` helpers.
4
+ *
5
+ * The akm-cli vault store at `${OP_HOME}/stash/vaults/user.env` is the
6
+ * canonical home for user-managed environment secrets. The assistant
7
+ * entrypoint sources this file directly at startup.
8
+ *
9
+ * `stack.env` and `guardian.env` are operator-managed and NOT mirrored
10
+ * into akm — mirroring them would break guardian's HMAC env_file
11
+ * hot-reload contract.
12
+ *
13
+ * SECURITY: every write into the akm vault is performed by spawning
14
+ * `akm vault set <ref> <key>` with the secret VALUE delivered via stdin
15
+ * (akm-cli >= 0.8.0). Values never appear in argv, so they cannot leak
16
+ * through `/proc/<pid>/cmdline`. The matching delete path uses
17
+ * `akm vault unset <ref> <key>` which is naturally argv-safe.
18
+ *
19
+ * Layout:
20
+ * stash/ — AKM_STASH_DIR: asset content (skills, vaults, knowledge, agents)
21
+ * state/akm/ — AKM_DATA_DIR / AKM_STATE_DIR / AKM_CONFIG_DIR: operational metadata
22
+ * cache/akm/ — AKM_CACHE_DIR: regenerable registry artifacts
23
+ */
24
+ import { existsSync, readFileSync } from "node:fs";
25
+ import { execFile as execFileCb } from "node:child_process";
26
+ import { promisify } from "node:util";
27
+ import { parseEnvFile } from "./env.js";
28
+ import { createLogger } from "../logger.js";
29
+ import type { ControlPlaneState } from "./types.js";
30
+
31
+ const execFile = promisify(execFileCb);
32
+ const logger = createLogger("akm-vault");
33
+
34
+ export const AKM_USER_VAULT_REF = "vault:user";
35
+
36
+ /**
37
+ * Build the env that points akm at the shared OpenPalm stash. We mirror the
38
+ * layout that the assistant/admin containers use (see
39
+ * `.openpalm/config/stack/core.compose.yml`) so host-side and container-side
40
+ * runs resolve to the same vault file.
41
+ *
42
+ * AKM_CONFIG_DIR lives in config/ (alongside stack.env, auth.json) so
43
+ * operators can inspect and version-control akm setup alongside other config.
44
+ * AKM_CACHE_DIR lives in cache/ since registry index and downloaded artifacts
45
+ * are regenerable and should not be indexed alongside stash assets.
46
+ */
47
+ export function buildAkmEnv(state: ControlPlaneState): NodeJS.ProcessEnv {
48
+ const akmOperational = `${state.stateDir}/akm`;
49
+ return {
50
+ ...process.env,
51
+ AKM_STASH_DIR: state.stashDir,
52
+ AKM_CONFIG_DIR: `${state.configDir}/akm`,
53
+ AKM_DATA_DIR: `${akmOperational}/data`,
54
+ AKM_STATE_DIR: `${akmOperational}/state`,
55
+ AKM_CACHE_DIR: `${state.cacheDir}/akm`,
56
+ };
57
+ }
58
+
59
+ /**
60
+ * Per-invocation timeout (ms) for every akm subprocess we launch. The CLI is
61
+ * a local binary and these probes (`--version`, `vault create`, `vault path`,
62
+ * `vault set/unset`) complete in well under a second on a healthy host;
63
+ * anything longer means akm is wedged or unreachable. Bounding the call
64
+ * keeps `mirrorUserVaultToAkm` truly best-effort: a stuck akm binary cannot
65
+ * block install/upgrade.
66
+ *
67
+ * Why a wall-clock race instead of execFile's built-in `timeout` option:
68
+ * node's `child_process.execFile` in Bun is implemented on top of `Bun.spawn`,
69
+ * and its `timeout` option only fires once stdout/stderr are wired up. Test
70
+ * suites that stub `Bun.spawn` (e.g. `packages/cli/src/main.test.ts`
71
+ * `mockDockerCli`) return a fake child whose stdout never closes, so neither
72
+ * the underlying promise nor the timeout option ever resolves. A simple
73
+ * `Promise.race` against an unref'd setTimeout converts that failure mode
74
+ * into a fast rejection that `akmAvailable` swallows as "akm not on PATH",
75
+ * without changing behaviour on real hosts.
76
+ */
77
+ const AKM_EXEC_TIMEOUT_MS = 2_000;
78
+
79
+ /**
80
+ * Race a promise against an unref'd setTimeout. If the timeout fires first,
81
+ * reject with `<label> timed out after <ms>ms`. The timer is always cleared
82
+ * in `finally` so it never keeps the event loop alive past resolution. The
83
+ * unref means the timer alone won't block process exit — the surrounding
84
+ * subprocess work owns the liveness.
85
+ */
86
+ function raceWithTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
87
+ let timer: ReturnType<typeof setTimeout> | undefined;
88
+ const timeoutPromise = new Promise<never>((_, reject) => {
89
+ timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
90
+ timer.unref?.();
91
+ });
92
+ return Promise.race([promise, timeoutPromise]).finally(() => {
93
+ if (timer) clearTimeout(timer);
94
+ });
95
+ }
96
+
97
+ async function execAkm(args: string[], env: NodeJS.ProcessEnv): Promise<{ stdout: string; stderr: string }> {
98
+ return raceWithTimeout(
99
+ execFile("akm", args, { env }),
100
+ AKM_EXEC_TIMEOUT_MS,
101
+ `akm ${args[0] ?? "?"}`,
102
+ );
103
+ }
104
+
105
+ async function akmAvailable(env: NodeJS.ProcessEnv): Promise<boolean> {
106
+ try {
107
+ await execAkm(["--version"], env);
108
+ return true;
109
+ } catch {
110
+ return false;
111
+ }
112
+ }
113
+
114
+ /**
115
+ * Return the absolute path of the akm vault file, creating the vault if
116
+ * missing. Callers that have already built the akm env (via `buildAkmEnv`)
117
+ * can pass it in to avoid rebuilding — the result is identical either way.
118
+ */
119
+ export async function ensureAkmUserVault(
120
+ state: ControlPlaneState,
121
+ env: NodeJS.ProcessEnv = buildAkmEnv(state),
122
+ ): Promise<string | null> {
123
+ if (!(await akmAvailable(env))) {
124
+ return null;
125
+ }
126
+ try {
127
+ // `vault create` accepts only the ref on argv — no secret material crosses
128
+ // the process boundary here.
129
+ await execAkm(["vault", "create", AKM_USER_VAULT_REF], env);
130
+ } catch (err) {
131
+ // `create` is documented as a no-op when the vault already exists, but
132
+ // some build channels emit a non-zero exit. Probe `path` to distinguish
133
+ // a real failure from "already exists".
134
+ logger.debug("akm vault create returned non-zero", {
135
+ ref: AKM_USER_VAULT_REF,
136
+ error: err instanceof Error ? err.message : String(err),
137
+ });
138
+ }
139
+ try {
140
+ const { stdout } = await execAkm(["vault", "path", AKM_USER_VAULT_REF], env);
141
+ const path = stdout.trim();
142
+ return path.length > 0 ? path : null;
143
+ } catch (err) {
144
+ logger.warn("akm vault path failed", {
145
+ ref: AKM_USER_VAULT_REF,
146
+ error: err instanceof Error ? err.message : String(err),
147
+ });
148
+ return null;
149
+ }
150
+ }
151
+
152
+ /**
153
+ * Spawn `akm vault set <ref> <key>` and feed the secret VALUE via stdin.
154
+ * The value never crosses argv, so it cannot leak through
155
+ * `/proc/<pid>/cmdline`. Bounded by AKM_EXEC_TIMEOUT_MS — a stuck akm
156
+ * binary cannot block the calling install/upgrade flow.
157
+ */
158
+ async function akmVaultSetViaStdin(
159
+ ref: string,
160
+ key: string,
161
+ value: string,
162
+ env: NodeJS.ProcessEnv,
163
+ ): Promise<void> {
164
+ // We use Bun.spawn directly because it supports an in-memory stdin pipe
165
+ // (a buffer/string stream) without dragging in an extra dependency, and
166
+ // because akm-cli on >= 0.8.0 reads the value from stdin when no
167
+ // positional `<value>` is provided. (The CLI silently switched stdin to
168
+ // the default in commit c50f9f4; explicit `--stdin` is still accepted
169
+ // for older binaries — but since we pin akm-cli >= 0.8.0-rc2 across all
170
+ // images via Dockerfile ARGs, the implicit form is enough.)
171
+ const child = Bun.spawn(["akm", "vault", "set", ref, key], {
172
+ env,
173
+ stdin: "pipe",
174
+ stdout: "pipe",
175
+ stderr: "pipe",
176
+ });
177
+
178
+ // Feed the secret. `child.stdin` is a FileSink in Bun — write+end then
179
+ // wait for exit. We don't use `await child.stdin.end(value)` because
180
+ // some Bun versions return undefined here; explicit write+end is portable.
181
+ if (child.stdin) {
182
+ // child.stdin is typed as FileSink in Bun
183
+ const sink = child.stdin as { write: (data: string) => unknown; end: () => unknown };
184
+ sink.write(value);
185
+ sink.end();
186
+ }
187
+
188
+ // Wall-clock bound — mirror of the execAkm pattern. On timeout we also
189
+ // SIGKILL the child so the orphaned subprocess doesn't outlive us.
190
+ let exitCode: number;
191
+ try {
192
+ exitCode = await raceWithTimeout(
193
+ child.exited,
194
+ AKM_EXEC_TIMEOUT_MS,
195
+ `akm vault set ${key}`,
196
+ );
197
+ } catch (err) {
198
+ try { child.kill(); } catch { /* best-effort */ }
199
+ throw err;
200
+ }
201
+
202
+ if (exitCode !== 0) {
203
+ const stderrText = child.stderr ? await new Response(child.stderr).text() : "";
204
+ throw new Error(`akm vault set ${key} failed (exit ${exitCode}): ${stderrText.trim()}`);
205
+ }
206
+ }
207
+
208
+ /**
209
+ * Write a single key/value into the akm `vault:user` store via
210
+ * `akm vault set <ref> <key>` with the value delivered on stdin.
211
+ *
212
+ * Returns `true` on success, `false` when akm is unavailable or the vault
213
+ * could not be ensured. Throws on akm subprocess failures (non-zero exit
214
+ * with a captured stderr, or wall-clock timeout) so callers can surface
215
+ * the real error instead of silently dropping the write.
216
+ */
217
+ export async function writeAkmVaultKey(
218
+ state: ControlPlaneState,
219
+ key: string,
220
+ value: string,
221
+ ): Promise<boolean> {
222
+ // Build env once and thread it through both the ensure step and the
223
+ // subsequent `akm vault set`. Avoids a redundant `buildAkmEnv` call.
224
+ const env = buildAkmEnv(state);
225
+ const vaultPath = await ensureAkmUserVault(state, env);
226
+ if (!vaultPath) return false;
227
+ await akmVaultSetViaStdin(AKM_USER_VAULT_REF, key, value, env);
228
+ return true;
229
+ }
230
+
231
+ /**
232
+ * Remove a key from the akm `vault:user` store via `akm vault unset`.
233
+ * The key name is a normal identifier and crosses argv only — secret
234
+ * values are never involved. Returns `true` if the operation completed
235
+ * (whether or not the key was present), `false` when akm is unavailable.
236
+ */
237
+ export async function deleteAkmVaultKey(
238
+ state: ControlPlaneState,
239
+ key: string,
240
+ ): Promise<boolean> {
241
+ // Build env once and pass it into ensureAkmUserVault so we don't pay
242
+ // for two `buildAkmEnv` calls on a single delete.
243
+ const env = buildAkmEnv(state);
244
+ const vaultPath = await ensureAkmUserVault(state, env);
245
+ if (!vaultPath) return false;
246
+ try {
247
+ // --yes: newer akm versions require explicit confirmation for any
248
+ // destructive operation in non-interactive mode. Without this flag
249
+ // the command exits with NON_INTERACTIVE_REQUIRES_YES and our
250
+ // delete looks like a hard failure instead of an idempotent unset.
251
+ await execAkm(["vault", "unset", "--yes", AKM_USER_VAULT_REF, key], env);
252
+ } catch (err) {
253
+ // `unset` of a missing key is a benign no-op; many akm versions exit 0
254
+ // anyway. If akm hard-fails (non-zero, non-empty stderr) we surface it.
255
+ const message = err instanceof Error ? err.message : String(err);
256
+ // Heuristic: tolerate "not found" / "no such" messages so re-running
257
+ // delete on an already-deleted key stays idempotent for callers.
258
+ if (/not\s*found|no\s+such|does\s+not\s+exist/i.test(message)) {
259
+ logger.debug("akm vault unset reported missing key", { key, message });
260
+ return true;
261
+ }
262
+ throw err;
263
+ }
264
+ return true;
265
+ }
266
+
267
+ /**
268
+ * Synchronously resolve the canonical akm `vault:user` file path for a given
269
+ * control-plane state. Used by sync read paths (e.g. plaintext secret backend
270
+ * `list`/`exists`) that cannot await `ensureAkmUserVault`.
271
+ *
272
+ * The path is deterministic: `buildAkmEnv` pins `AKM_STASH_DIR` to
273
+ * `state.stashDir`, and akm-cli (>= 0.8.0) materializes vault files
274
+ * at `${AKM_STASH_DIR}/vaults/<ref>.env`.
275
+ *
276
+ * Returns the path string regardless of whether the file currently exists —
277
+ * callers should `existsSync` if presence matters.
278
+ */
279
+ export function akmUserVaultPathSync(state: ControlPlaneState): string {
280
+ return `${state.stashDir}/vaults/user.env`;
281
+ }
282
+
283
+ /**
284
+ * Read the user-managed env namespace from the akm `vault:user` store.
285
+ *
286
+ * Returns `{}` when the vault file does not exist yet. Pure sync — no subprocess spawn.
287
+ */
288
+ export function readUserVaultSync(state: ControlPlaneState): Record<string, string> {
289
+ const akmPath = akmUserVaultPathSync(state);
290
+ if (existsSync(akmPath)) {
291
+ return readAkmUserVaultFile(akmPath);
292
+ }
293
+ return {};
294
+ }
295
+
296
+ /** Return the parsed contents of the akm vault file (public API used by admin UI list endpoint). */
297
+ export function readAkmUserVaultFile(vaultPath: string): Record<string, string> {
298
+ if (!existsSync(vaultPath)) return {};
299
+ try {
300
+ return parseEnvFile(vaultPath);
301
+ } catch {
302
+ // Fallback: hand-parse if dotenv chokes (e.g. file with stray BOM).
303
+ const raw = readFileSync(vaultPath, "utf-8");
304
+ const out: Record<string, string> = {};
305
+ for (const line of raw.split("\n")) {
306
+ const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
307
+ if (m) out[m[1]] = m[2];
308
+ }
309
+ return out;
310
+ }
311
+ }
@@ -19,9 +19,11 @@ function isValidChannelName(name: string): boolean {
19
19
  // ── Channel Discovery ─────────────────────────────────────────────────
20
20
 
21
21
  /**
22
- * Check if a compose file defines a channel service (has CHANNEL_NAME or GUARDIAN_URL).
23
- * This is compose-derived: we parse the actual compose content rather than
24
- * relying on filename patterns or directory naming conventions.
22
+ * Check if a compose file defines a channel service (has CHANNEL_NAME).
23
+ * Compose-derived: we parse the actual compose content rather than rely on
24
+ * filename or directory naming conventions. (GUARDIAN_URL used to be a
25
+ * fallback signal — it's been removed since channels-sdk now hardcodes the
26
+ * in-network guardian URL.)
25
27
  */
26
28
  export function isChannelAddon(composePath: string): boolean {
27
29
  try {
@@ -36,9 +38,9 @@ export function isChannelAddon(composePath: string): boolean {
36
38
  const env = (svcDef as Record<string, unknown>).environment;
37
39
  if (typeof env === "object" && env !== null) {
38
40
  if (Array.isArray(env)) {
39
- if (env.some((e: unknown) => typeof e === "string" && (e.startsWith("CHANNEL_NAME=") || e.startsWith("GUARDIAN_URL=")))) return true;
41
+ if (env.some((e: unknown) => typeof e === "string" && e.startsWith("CHANNEL_NAME="))) return true;
40
42
  } else {
41
- if ("CHANNEL_NAME" in (env as Record<string, unknown>) || "GUARDIAN_URL" in (env as Record<string, unknown>)) return true;
43
+ if ("CHANNEL_NAME" in (env as Record<string, unknown>)) return true;
42
44
  }
43
45
  }
44
46
  }
@@ -51,7 +53,7 @@ export function isChannelAddon(composePath: string): boolean {
51
53
  /**
52
54
  * Discover installed channels by scanning stack/addons/ for channel addons.
53
55
  * A channel addon is identified by compose-derived truth: its compose.yml
54
- * defines services with CHANNEL_NAME or GUARDIAN_URL environment variables.
56
+ * defines services with a CHANNEL_NAME environment variable.
55
57
  *
56
58
  * Non-channel addons (admin, ollama, etc.) are excluded.
57
59
  *
@@ -60,7 +62,7 @@ export function isChannelAddon(composePath: string): boolean {
60
62
  */
61
63
  export function discoverChannels(configDir: string): ChannelInfo[] {
62
64
  const homeDir = dirname(configDir);
63
- const addonsDir = `${homeDir}/stack/addons`;
65
+ const addonsDir = `${homeDir}/config/stack/addons`;
64
66
  if (!existsSync(addonsDir)) return [];
65
67
 
66
68
  const entries = readdirSync(addonsDir, { withFileTypes: true });
@@ -91,7 +93,7 @@ export function isAllowedService(value: string, configDir?: string): boolean {
91
93
 
92
94
  if (configDir) {
93
95
  const homeDir = dirname(configDir);
94
- const addonsDir = `${homeDir}/stack/addons`;
96
+ const addonsDir = `${homeDir}/config/stack/addons`;
95
97
  if (!existsSync(addonsDir)) return false;
96
98
 
97
99
  // Check if any addon compose.yml defines this service name (YAML-parsed)
@@ -125,7 +127,7 @@ export function isValidChannel(value: string, configDir?: string): boolean {
125
127
  if (!isValidChannelName(value)) return false;
126
128
  if (configDir) {
127
129
  const homeDir = dirname(configDir);
128
- return existsSync(`${homeDir}/stack/addons/${value}/compose.yml`);
130
+ return existsSync(`${homeDir}/config/stack/addons/${value}/compose.yml`);
129
131
  }
130
132
  return false;
131
133
  }
@@ -149,17 +149,16 @@ describe("guardrail: compose-derived service discovery", () => {
149
149
  });
150
150
  });
151
151
 
152
- // ── Guardrail 5: Env schema paths are correct ──────────────────────────
152
+ // ── Guardrail 5: No varlock or .env.schema references in validate.ts ───
153
153
 
154
- describe("guardrail: env schema validation paths", () => {
155
- test("validate.ts uses correct nested vault schema paths", () => {
154
+ describe("guardrail: validate.ts is varlock-free", () => {
155
+ test("validate.ts does not import child_process or read .env.schema", () => {
156
156
  const validateTs = readFileSync(join(LIB_CONTROL_PLANE_DIR, "validate.ts"), "utf-8");
157
- // Must use nested paths
158
- expect(validateTs).toContain("vaultDir}/user/user.env.schema");
159
- expect(validateTs).toContain("vaultDir}/stack/stack.env.schema");
160
- // Must NOT use flat paths
161
- expect(validateTs).not.toContain("vaultDir}/user.env.schema");
162
- expect(validateTs).not.toContain("vaultDir}/system.env.schema");
157
+ // Post-#391: validation is key-presence only — no schema files, no binary.
158
+ expect(validateTs).not.toContain("node:child_process");
159
+ expect(validateTs).not.toContain("execFile");
160
+ expect(validateTs).not.toContain("VARLOCK_BIN");
161
+ expect(validateTs).not.toContain(".env.schema");
163
162
  });
164
163
  });
165
164