@openpalm/lib 0.9.8 → 0.10.1

package/src/control-plane/spec-to-env.test.ts

@@ -0,0 +1,100 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveSystemEnvFromSpec, writeCapabilityVars } from "./spec-to-env.js";
+import type { StackSpec } from "./stack-spec.js";
+
+function makeSpec(overrides?: Partial<StackSpec>): StackSpec {
+  return {
+    version: 2,
+    capabilities: {
+      llm: "openai/gpt-4o",
+      embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
+      memory: { userId: "default_user" },
+    },
+    ...overrides,
+  };
+}
+
+let tempDir = "";
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "openpalm-spec-env-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("deriveSystemEnvFromSpec", () => {
+  test("produces OP_HOME", () => {
+    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    expect(result.OP_HOME).toBe("/home/op");
+  });
+
+  test("produces default port values", () => {
+    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    expect(result.OP_ASSISTANT_PORT).toBe("3800");
+    expect(result.OP_MEMORY_PORT).toBe("3898");
+    expect(result.OP_GUARDIAN_PORT).toBe("3899");
+  });
+
+  test("does not include LLM provider in system env (lives in OP_CAP_* vars in stack.env)", () => {
+    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    expect(result.SYSTEM_LLM_PROVIDER).toBeUndefined();
+    expect(result.SYSTEM_LLM_MODEL).toBeUndefined();
+  });
+
+  test("does not include embedding config in system env (lives in OP_CAP_* vars in stack.env)", () => {
+    const result = deriveSystemEnvFromSpec(makeSpec(), "/home/op");
+    expect(result.EMBEDDING_MODEL).toBeUndefined();
+    expect(result.EMBEDDING_DIMS).toBeUndefined();
+  });
+
+  test("does not include removed feature flags", () => {
+    const spec = makeSpec();
+    const result = deriveSystemEnvFromSpec(spec, "/home/op");
+    expect(result.OP_OLLAMA_ENABLED).toBeUndefined();
+    expect(result.OP_ADMIN_ENABLED).toBeUndefined();
+  });
+});
+
+describe("writeCapabilityVars", () => {
+  test("writes OP_CAP_* vars to stack.env", () => {
+    const spec = makeSpec({
+      capabilities: {
+        llm: "openai/gpt-4o",
+        embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
+        memory: { userId: "default_user" },
+      },
+    });
+
+    // Seed stack.env so writeCapabilityVars can read/merge it
+    const vaultDir = join(tempDir, "vault");
+    mkdirSync(join(vaultDir, "stack"), { recursive: true });
+    writeFileSync(join(vaultDir, "stack", "stack.env"), "# stack env\n");
+
+    writeCapabilityVars(spec, vaultDir);
+
+    const stackEnvContent = readFileSync(join(vaultDir, "stack", "stack.env"), "utf-8");
+    expect(stackEnvContent).toContain("OP_CAP_LLM_PROVIDER=openai");
+    expect(stackEnvContent).toContain("OP_CAP_LLM_MODEL=gpt-4o");
+    expect(stackEnvContent).toContain("OP_CAP_EMBEDDINGS_MODEL=text-embedding-3-small");
+    expect(stackEnvContent).toContain("OP_CAP_EMBEDDINGS_DIMS=1536");
+    expect(stackEnvContent).toContain("MEMORY_USER_ID=default_user");
+  });
+
+  test("does not create managed.env files", () => {
+    const spec = makeSpec();
+
+    const vaultDir = join(tempDir, "vault");
+    mkdirSync(join(vaultDir, "stack"), { recursive: true });
+    writeFileSync(join(vaultDir, "stack", "stack.env"), "# stack env\n");
+
+    writeCapabilityVars(spec, vaultDir);
+
+    const managedEnvPath = join(vaultDir, "stack", "services", "memory", "managed.env");
+    expect(() => readFileSync(managedEnvPath)).toThrow();
+  });
+});

package/src/control-plane/spec-to-env.ts

@@ -0,0 +1,195 @@
+/**
+ * Config-to-env derivation pipeline.
+ *
+ * Reads a StackSpec v2 and deterministically produces:
+ * 1. System env vars for stack.env (non-secret infrastructure config)
+ * 2. Resolved capability vars (OP_CAP_*) written to stack.env
+ */
+
+import type { StackSpec } from "./stack-spec.js";
+import { SPEC_DEFAULTS, parseCapabilityString } from "./stack-spec.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { mergeEnvContent, parseEnvContent } from "./env.js";
+import { PROVIDER_DEFAULT_URLS, PROVIDER_KEY_MAP, OLLAMA_INSTACK_URL } from "../provider-constants.js";
+import { listEnabledAddonIds } from "./registry.js";
+
+/**
+ * Derive the system.env key-value pairs from the StackSpec.
+ * Secrets (tokens, API keys, HMAC) are NOT included — the caller merges them.
+ */
+export function deriveSystemEnvFromSpec(
+  spec: StackSpec,
+  homeDir: string,
+): Record<string, string> {
+  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
+  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
+
+  const ports = SPEC_DEFAULTS.ports;
+  const image = SPEC_DEFAULTS.image;
+
+  const result: Record<string, string> = {};
+
+  // Paths
+  result["OP_HOME"] = homeDir;
+  result["OP_UID"] = String(uid);
+  result["OP_GID"] = String(gid);
+  result["OP_DOCKER_SOCK"] = process.env.OP_DOCKER_SOCK ?? "/var/run/docker.sock";
+
+  // Image
+  result["OP_IMAGE_NAMESPACE"] = image.namespace;
+  result["OP_IMAGE_TAG"] = image.tag;
+
+  // Ports
+  result["OP_ASSISTANT_PORT"] = String(ports.assistant);
+  result["OP_ADMIN_PORT"] = String(ports.admin);
+  result["OP_ADMIN_OPENCODE_PORT"] = String(ports.adminOpencode);
+  result["OP_MEMORY_PORT"] = String(ports.memory);
+  result["OP_GUARDIAN_PORT"] = String(ports.guardian);
+  result["OP_ASSISTANT_SSH_PORT"] = String(ports.assistantSsh);
+
+  return result;
+}
+
+// ── Capability Resolution ────────────────────────────────────────────────
+
+/**
+ * Resolve all capabilities from stack.yml and write OP_CAP_* vars into stack.env.
+ *
+ * Reads raw API keys from the current stack.env, resolves provider → base URL → API key
+ * for each capability, and merges the OP_CAP_* section into stack.env.
+ *
+ * Services consume these via compose ${VAR} substitution in their environment blocks.
+ */
+export function writeCapabilityVars(spec: StackSpec, vaultDir: string): void {
+  const stackEnvPath = `${vaultDir}/stack/stack.env`;
+  const stackEnv = existsSync(stackEnvPath)
+    ? parseEnvContent(readFileSync(stackEnvPath, "utf-8"))
+    : {};
+
+  const resolveKey = (provider: string): string => {
+    const keyVar = PROVIDER_KEY_MAP[provider];
+    return keyVar ? (stackEnv[keyVar] || "") : "";
+  };
+
+  /** Providers that do NOT use an OpenAI-compatible /v1 path prefix. */
+  const NO_V1_SUFFIX = new Set(["ollama", "google"]);
+
+  const ensureV1 = (url: string, provider: string): string => {
+    if (!url || NO_V1_SUFFIX.has(provider)) return url;
+    return url.endsWith("/v1") ? url : `${url.replace(/\/+$/, "")}/v1`;
+  };
+
+  /** Map provider → env var for user-configured base URL overrides. */
+  const BASE_URL_ENV_MAP: Record<string, string> = {
+    openai: "OPENAI_BASE_URL",
+    anthropic: "ANTHROPIC_BASE_URL",
+    groq: "GROQ_BASE_URL",
+    mistral: "MISTRAL_BASE_URL",
+    together: "TOGETHER_BASE_URL",
+    deepseek: "DEEPSEEK_BASE_URL",
+    xai: "XAI_BASE_URL",
+    google: "GOOGLE_BASE_URL",
+    huggingface: "HF_BASE_URL",
+    ollama: "OLLAMA_BASE_URL",
+    lmstudio: "LMSTUDIO_BASE_URL",
+    "model-runner": "MODEL_RUNNER_BASE_URL",
+    "openai-compatible": "OPENAI_COMPATIBLE_BASE_URL",
+  };
+
+  const resolveUrl = (provider: string): string => {
+    if (provider === "ollama" && listEnabledAddonIds(dirname(vaultDir)).includes("ollama")) return OLLAMA_INSTACK_URL;
+    // Check stack.env for a user-configured base URL override for any provider
+    const urlEnvKey = BASE_URL_ENV_MAP[provider];
+    if (urlEnvKey && stackEnv[urlEnvKey]) {
+      return ensureV1(stackEnv[urlEnvKey], provider);
+    }
+    const defaultUrl = PROVIDER_DEFAULT_URLS[provider] || "";
+    return ensureV1(defaultUrl, provider);
+  };
+
+  const caps: Record<string, string> = {};
+
+  /** Set a list of capability env vars to empty string (disabled capability). */
+  const clearCapVars = (prefix: string, fields: string[]): void => {
+    for (const f of fields) caps[`${prefix}_${f}`] = "";
+  };
+
+  // ── LLM ──
+  const { provider: llmP, model: llmM } = parseCapabilityString(spec.capabilities.llm);
+  caps.OP_CAP_LLM_PROVIDER = llmP;
+  caps.OP_CAP_LLM_MODEL = llmM;
+  caps.OP_CAP_LLM_BASE_URL = resolveUrl(llmP);
+  caps.OP_CAP_LLM_API_KEY = resolveKey(llmP);
+
+  // ── SLM ──
+  if (spec.capabilities.slm) {
+    const { provider: slmP, model: slmM } = parseCapabilityString(spec.capabilities.slm);
+    caps.OP_CAP_SLM_PROVIDER = slmP;
+    caps.OP_CAP_SLM_MODEL = slmM;
+    caps.OP_CAP_SLM_BASE_URL = resolveUrl(slmP);
+    caps.OP_CAP_SLM_API_KEY = resolveKey(slmP);
+  } else {
+    clearCapVars("OP_CAP_SLM", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY"]);
+  }
+
+  // ── Embeddings ──
+  const emb = spec.capabilities.embeddings;
+  caps.OP_CAP_EMBEDDINGS_PROVIDER = emb.provider;
+  caps.OP_CAP_EMBEDDINGS_MODEL = emb.model;
+  caps.OP_CAP_EMBEDDINGS_BASE_URL = resolveUrl(emb.provider);
+  caps.OP_CAP_EMBEDDINGS_API_KEY = resolveKey(emb.provider);
+  caps.OP_CAP_EMBEDDINGS_DIMS = String(emb.dims);
+
+  // ── TTS ──
+  const tts = spec.capabilities.tts;
+  if (tts?.enabled) {
+    const p = tts.provider || llmP;
+    caps.OP_CAP_TTS_PROVIDER = p;
+    caps.OP_CAP_TTS_MODEL = tts.model || "";
+    caps.OP_CAP_TTS_BASE_URL = resolveUrl(p);
+    caps.OP_CAP_TTS_API_KEY = resolveKey(p);
+    caps.OP_CAP_TTS_VOICE = tts.voice || "";
+    caps.OP_CAP_TTS_FORMAT = tts.format || "";
+  } else {
+    clearCapVars("OP_CAP_TTS", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "VOICE", "FORMAT"]);
+  }
+
+  // ── STT ──
+  const stt = spec.capabilities.stt;
+  if (stt?.enabled) {
+    const p = stt.provider || llmP;
+    caps.OP_CAP_STT_PROVIDER = p;
+    caps.OP_CAP_STT_MODEL = stt.model || "";
+    caps.OP_CAP_STT_BASE_URL = resolveUrl(p);
+    caps.OP_CAP_STT_API_KEY = resolveKey(p);
+    caps.OP_CAP_STT_LANGUAGE = stt.language || "";
+  } else {
+    clearCapVars("OP_CAP_STT", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "LANGUAGE"]);
+  }
+
+  // ── Reranking ──
+  const rr = spec.capabilities.reranking;
+  if (rr?.enabled) {
+    const p = rr.provider || llmP;
+    caps.OP_CAP_RERANKING_PROVIDER = p;
+    caps.OP_CAP_RERANKING_MODEL = rr.model || "";
+    caps.OP_CAP_RERANKING_BASE_URL = resolveUrl(p);
+    caps.OP_CAP_RERANKING_API_KEY = resolveKey(p);
+    caps.OP_CAP_RERANKING_TOP_K = rr.topK ? String(rr.topK) : "";
+    caps.OP_CAP_RERANKING_TOP_N = rr.topN ? String(rr.topN) : "";
+  } else {
+    clearCapVars("OP_CAP_RERANKING", ["PROVIDER", "MODEL", "BASE_URL", "API_KEY", "TOP_K", "TOP_N"]);
+  }
+
+  // ── Memory ──
+  caps.MEMORY_USER_ID = spec.capabilities.memory.userId || "default_user";
+
+  // Merge into stack.env
+  const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
+  let content = mergeEnvContent(base, caps, {
+    sectionHeader: "# ── Resolved Capabilities (from stack.yml) ─────────────────────────",
+  });
+  if (!content.endsWith("\n")) content += "\n";
+  writeFileSync(stackEnvPath, content, { mode: 0o600 });
+}

package/src/control-plane/spec-validator.ts

@@ -0,0 +1,159 @@
+/**
+ * StackSpec v2 validation.
+ *
+ * Returns structured, actionable error messages with codes
+ * so users can quickly identify and fix configuration issues.
+ */
+
+import type { StackSpec, StackSpecCapabilities } from "./stack-spec.js";
+
+export type ValidationError = {
+  code: string;
+  message: string;
+  path?: string;
+  hint?: string;
+};
+
+const IMAGE_NS_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+
+export function validateStackSpec(input: unknown): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  if (typeof input !== "object" || input === null) {
+    errors.push({
+      code: "OP-CFG-000",
+      message: "Configuration must be an object",
+      hint: "Check that the YAML file starts with valid configuration keys",
+    });
+    return errors;
+  }
+
+  const spec = input as Record<string, unknown>;
+
+  // Version check
+  if (spec.version !== 2) {
+    errors.push({
+      code: "OP-CFG-020",
+      message: `Expected version: 2, got: ${spec.version ?? "(missing)"}`,
+      path: "version",
+      hint: "Set version: 2 at the top of your config file",
+    });
+    return errors;
+  }
+
+  // Capabilities
+  if (typeof spec.capabilities !== "object" || spec.capabilities === null) {
+    errors.push({
+      code: "OP-CFG-001",
+      message: "No capabilities defined",
+      path: "capabilities",
+      hint: "Add capabilities.llm and capabilities.embeddings sections",
+    });
+  } else {
+    validateCapabilities(spec.capabilities as StackSpecCapabilities, errors);
+  }
+
+  // Image
+  if (spec.image && typeof spec.image === "object") {
+    const img = spec.image as Record<string, unknown>;
+    if (
+      typeof img.namespace === "string" &&
+      !IMAGE_NS_RE.test(img.namespace)
+    ) {
+      errors.push({
+        code: "OP-CFG-012",
+        message: `image.namespace "${img.namespace}" contains invalid characters`,
+        path: "image.namespace",
+        hint: "Use lowercase letters, numbers, dots, hyphens, or underscores",
+      });
+    }
+  }
+
+  return errors;
+}
+
+function validateCapabilities(
+  capabilities: StackSpecCapabilities,
+  errors: ValidationError[],
+): void {
+  // LLM (required, "provider/model" string)
+  if (!capabilities.llm || typeof capabilities.llm !== "string") {
+    errors.push({
+      code: "OP-CFG-008",
+      message: "capabilities.llm is required (format: provider/model)",
+      path: "capabilities.llm",
+      hint: 'Example: "anthropic/claude-sonnet-4-5" or "ollama/qwen2.5-coder:3b"',
+    });
+  } else if (!capabilities.llm.includes("/")) {
+    errors.push({
+      code: "OP-CFG-008",
+      message: `capabilities.llm "${capabilities.llm}" must be in provider/model format`,
+      path: "capabilities.llm",
+      hint: 'Example: "anthropic/claude-sonnet-4-5"',
+    });
+  }
+
+  // SLM (optional, same format)
+  if (capabilities.slm !== undefined) {
+    if (typeof capabilities.slm !== "string") {
+      errors.push({
+        code: "OP-CFG-008",
+        message: "capabilities.slm must be a string (format: provider/model)",
+        path: "capabilities.slm",
+      });
+    } else if (!capabilities.slm.includes("/")) {
+      errors.push({
+        code: "OP-CFG-008",
+        message: `capabilities.slm "${capabilities.slm}" must be in provider/model format`,
+        path: "capabilities.slm",
+      });
+    }
+  }
+
+  // Embeddings (required object)
+  if (!capabilities.embeddings || typeof capabilities.embeddings !== "object") {
+    errors.push({
+      code: "OP-CFG-002",
+      message: "capabilities.embeddings is required",
+      path: "capabilities.embeddings",
+      hint: "Add provider, model, and dims fields",
+    });
+  } else {
+    const emb = capabilities.embeddings;
+    if (!emb.provider || typeof emb.provider !== "string") {
+      errors.push({
+        code: "OP-CFG-004",
+        message: "capabilities.embeddings.provider is required",
+        path: "capabilities.embeddings.provider",
+      });
+    }
+    if (!emb.model || typeof emb.model !== "string") {
+      errors.push({
+        code: "OP-CFG-008",
+        message: "capabilities.embeddings.model is required",
+        path: "capabilities.embeddings.model",
+      });
+    }
+    if (
+      emb.dims !== undefined &&
+      (typeof emb.dims !== "number" || emb.dims < 1)
+    ) {
+      errors.push({
+        code: "OP-CFG-009",
+        message: "capabilities.embeddings.dims must be a positive integer",
+        path: "capabilities.embeddings.dims",
+        hint: "Common values: nomic-embed-text: 768, text-embedding-3-small: 1536",
+      });
+    }
+  }
+
+  // Memory (required object)
+  if (!capabilities.memory || typeof capabilities.memory !== "object") {
+    errors.push({
+      code: "OP-CFG-002",
+      message: "capabilities.memory is required",
+      path: "capabilities.memory",
+      hint: "Add at minimum a userId field",
+    });
+  }
+}

package/src/control-plane/stack-spec.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Stack spec parser tests.
+ *
+ * Verifies that readStackSpec / writeStackSpec produce consistent results
+ * and that all addon resolution goes through the canonical lib functions.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readStackSpec,
+  writeStackSpec,
+  STACK_SPEC_FILENAME,
+  stackSpecPath,
+  parseCapabilityString,
+  formatCapabilityString,
+  updateCapability,
+} from "./stack-spec.js";
+import type { StackSpec } from "./stack-spec.js";
+
+let configDir: string;
+
+beforeEach(() => {
+  configDir = mkdtempSync(join(tmpdir(), "stack-spec-test-"));
+});
+
+afterEach(() => {
+  rmSync(configDir, { recursive: true, force: true });
+});
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function makeSpec(): StackSpec {
+  return {
+    version: 2,
+    capabilities: {
+      llm: "openai/gpt-4o",
+      embeddings: { provider: "openai", model: "text-embedding-3-small", dims: 1536 },
+      memory: { userId: "test-user" },
+    },
+  };
+}
+
+// ── readStackSpec / writeStackSpec round-trip ────────────────────────────
+
+describe("readStackSpec / writeStackSpec round-trip", () => {
+  it("round-trips a spec with capabilities only", () => {
+    const spec = makeSpec();
+    writeStackSpec(configDir, spec);
+    const read = readStackSpec(configDir);
+    expect(read).not.toBeNull();
+    expect(read!.version).toBe(2);
+    expect(read!.capabilities.llm).toBe("openai/gpt-4o");
+  });
+
+  it("writes to the canonical filename", () => {
+    writeStackSpec(configDir, makeSpec());
+    const expectedPath = join(configDir, STACK_SPEC_FILENAME);
+    const read = readStackSpec(configDir);
+    expect(read).not.toBeNull();
+    expect(stackSpecPath(configDir)).toBe(expectedPath);
+  });
+});
+
+// ── readStackSpec edge cases ────────────────────────────────────────────
+
+describe("readStackSpec edge cases", () => {
+  it("returns null for missing file", () => {
+    expect(readStackSpec(configDir)).toBeNull();
+  });
+
+  it("returns null for v1 format (connections array)", () => {
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 1\nconnections: []\n");
+    expect(readStackSpec(configDir)).toBeNull();
+  });
+
+  it("returns null for corrupt YAML", () => {
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "{{invalid yaml");
+    expect(readStackSpec(configDir)).toBeNull();
+  });
+
+  it("returns null when capabilities is missing", () => {
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\n");
+    expect(readStackSpec(configDir)).toBeNull();
+  });
+});
+
+// ── Capability helpers ──────────────────────────────────────────────────
+
+describe("parseCapabilityString", () => {
+  it("splits provider/model", () => {
+    expect(parseCapabilityString("openai/gpt-4o")).toEqual({ provider: "openai", model: "gpt-4o" });
+  });
+
+  it("handles model with slashes", () => {
+    expect(parseCapabilityString("ollama/qwen/2.5-coder:3b")).toEqual({ provider: "ollama", model: "qwen/2.5-coder:3b" });
+  });
+
+  it("handles missing slash", () => {
+    expect(parseCapabilityString("openai")).toEqual({ provider: "openai", model: "" });
+  });
+});
+
+describe("formatCapabilityString", () => {
+  it("joins provider and model", () => {
+    expect(formatCapabilityString("openai", "gpt-4o")).toBe("openai/gpt-4o");
+  });
+});
+
+// ── updateCapability ────────────────────────────────────────────────────
+
+describe("updateCapability", () => {
+  it("updates a single capability key", () => {
+    writeStackSpec(configDir, makeSpec());
+    updateCapability(configDir, "llm", "anthropic/claude-sonnet-4");
+    const read = readStackSpec(configDir);
+    expect(read).not.toBeNull();
+    expect(read!.capabilities.llm).toBe("anthropic/claude-sonnet-4");
+  });
+
+  it("throws when spec is missing", () => {
+    expect(() => updateCapability(configDir, "llm", "test")).toThrow("stack.yml not found or invalid");
+  });
+});
+
+// ── stackSpecPath / STACK_SPEC_FILENAME ──────────────────────────────────
+
+describe("stackSpecPath", () => {
+  it("returns configDir/stack.yml", () => {
+    expect(stackSpecPath("/foo/config")).toBe("/foo/config/stack.yml");
+  });
+
+  it("uses STACK_SPEC_FILENAME constant", () => {
+    expect(STACK_SPEC_FILENAME).toBe("stack.yml");
+    expect(stackSpecPath(configDir)).toBe(`${configDir}/${STACK_SPEC_FILENAME}`);
+  });
+});
+
+// ── writeStackSpec creates directory ─────────────────────────────────────
+
+describe("writeStackSpec", () => {
+  it("creates configDir if it does not exist", () => {
+    const nestedDir = join(configDir, "nested", "deep");
+    writeStackSpec(nestedDir, makeSpec());
+    const read = readStackSpec(nestedDir);
+    expect(read).not.toBeNull();
+    expect(read!.version).toBe(2);
+  });
+});