@openpalm/lib 0.9.9 → 0.10.1

package/src/control-plane/opencode-client.test.ts

@@ -0,0 +1,154 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from "bun:test";
+import { createOpenCodeClient } from "./opencode-client.ts";
+
+// ── Test server helper ──────────────────────────────────────────────────
+
+let server: ReturnType<typeof Bun.serve> | null = null;
+let serverPort = 0;
+
+function startMockServer(handler: (req: Request) => Response | Promise<Response>) {
+  server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    fetch: handler,
+  });
+  serverPort = server.port;
+}
+
+afterEach(() => {
+  if (server) { server.stop(true); server = null; }
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────
+
+describe("createOpenCodeClient", () => {
+  test("proxy returns ok:true for 200 responses", async () => {
+    startMockServer(() => new Response(JSON.stringify({ hello: "world" }), {
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const result = await client.proxy("/test");
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data).toEqual({ hello: "world" });
+  });
+
+  test("proxy returns ok:false for non-200 responses", async () => {
+    startMockServer(() => new Response(JSON.stringify({ message: "bad" }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const result = await client.proxy("/test");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(400);
+      expect(result.message).toBe("bad");
+    }
+  });
+
+  test("proxy returns unavailable for gateway errors", async () => {
+    startMockServer(() => new Response("bad gateway", { status: 502 }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const result = await client.proxy("/test");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe("opencode_unavailable");
+    }
+  });
+
+  test("proxy returns unavailable on network error", async () => {
+    const client = createOpenCodeClient({ baseUrl: "http://127.0.0.1:1", /* unreachable port */ });
+    const result = await client.proxy("/test");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe("opencode_unavailable");
+    }
+  });
+
+  test("getProviders returns array from data.all", async () => {
+    startMockServer(() => new Response(JSON.stringify({
+      all: [{ id: "openai", name: "OpenAI" }, { id: "groq", name: "Groq" }],
+    }), { headers: { "Content-Type": "application/json" } }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const providers = await client.getProviders();
+    expect(providers).toHaveLength(2);
+    expect(providers[0].id).toBe("openai");
+  });
+
+  test("getProviders returns empty array on error", async () => {
+    startMockServer(() => new Response("error", { status: 500 }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const providers = await client.getProviders();
+    expect(providers).toEqual([]);
+  });
+
+  test("getProviderAuth returns auth map", async () => {
+    startMockServer(() => new Response(JSON.stringify({
+      openai: [{ type: "api", label: "API Key" }],
+    }), { headers: { "Content-Type": "application/json" } }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const auth = await client.getProviderAuth();
+    expect(auth.openai).toHaveLength(1);
+    expect(auth.openai[0].type).toBe("api");
+  });
+
+  test("setProviderApiKey sends PUT with correct body", async () => {
+    let receivedBody: any = null;
+    let receivedMethod = "";
+    let receivedPath = "";
+
+    startMockServer(async (req) => {
+      receivedMethod = req.method;
+      receivedPath = new URL(req.url).pathname;
+      receivedBody = await req.json();
+      return new Response(JSON.stringify({ ok: true }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const result = await client.setProviderApiKey("openai", "sk-test-123");
+
+    expect(result.ok).toBe(true);
+    expect(receivedMethod).toBe("PUT");
+    expect(receivedPath).toBe("/auth/openai");
+    expect(receivedBody).toEqual({ type: "api", key: "sk-test-123" });
+  });
+
+  test("isAvailable returns true when /provider responds 200", async () => {
+    startMockServer(() => new Response(JSON.stringify({ all: [] }), {
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    expect(await client.isAvailable()).toBe(true);
+  });
+
+  test("isAvailable returns false when unreachable", async () => {
+    const client = createOpenCodeClient({ baseUrl: "http://127.0.0.1:1", /* unreachable port */ });
+    expect(await client.isAvailable()).toBe(false);
+  });
+
+  test("getConfig returns config object on success", async () => {
+    startMockServer(() => new Response(JSON.stringify({ model: "gpt-4o" }), {
+      headers: { "Content-Type": "application/json" },
+    }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    const config = await client.getConfig();
+    expect(config).toEqual({ model: "gpt-4o" });
+  });
+
+  test("getConfig returns null on error", async () => {
+    startMockServer(() => new Response("error", { status: 500 }));
+
+    const client = createOpenCodeClient({ baseUrl: `http://127.0.0.1:${serverPort}` });
+    expect(await client.getConfig()).toBeNull();
+  });
+});

package/src/control-plane/opencode-client.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared OpenCode REST API client.
+ *
+ * Factory function that returns typed accessors for an OpenCode server
+ * at a configurable base URL. Used by both the admin (container) and
+ * CLI (host subprocess) to talk to OpenCode.
+ */
+
+export type OpenCodeClientOpts = {
+  baseUrl: string;
+};
+
+export type ProxyResult =
+  | { ok: true; data: unknown }
+  | { ok: false; status: number; code: string; message: string };
+
+export type OpenCodeProvider = {
+  id: string;
+  name?: string;
+  [key: string]: unknown;
+};
+
+export function createOpenCodeClient(opts: OpenCodeClientOpts) {
+  const { baseUrl } = opts;
+
+  const DEFAULT_TIMEOUT_MS = 30_000;
+
+  async function proxy(path: string, options?: RequestInit): Promise<ProxyResult> {
+    try {
+      const signal = options?.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+      const res = await fetch(`${baseUrl}${path}`, { ...options, signal });
+      if (!res.ok) {
+        const body = await res.json().catch((e: unknown) => {
+          console.warn('[opencode-client] Failed to parse error response:', e);
+          return {} as Record<string, unknown>;
+        });
+        const message = typeof (body as Record<string, unknown>).message === 'string'
+          ? (body as Record<string, unknown>).message as string
+          : `OpenCode returned ${res.status}`;
+        if (res.status === 502 || res.status === 503 || res.status === 504) {
+          return { ok: false, status: res.status, code: 'opencode_unavailable', message };
+        }
+        return { ok: false, status: res.status >= 500 ? 502 : res.status, code: 'opencode_error', message };
+      }
+      return { ok: true, data: await res.json() };
+    } catch (e) {
+      console.warn('[opencode-client] OpenCode request failed:', path, e);
+      return { ok: false, status: 503, code: 'opencode_unavailable', message: 'OpenCode is not reachable' };
+    }
+  }
+
+  async function getProviders(): Promise<OpenCodeProvider[]> {
+    const result = await proxy('/provider');
+    if (!result.ok) return [];
+    const data = result.data as Record<string, unknown>;
+    if (data && Array.isArray(data.all)) return data.all as OpenCodeProvider[];
+    if (Array.isArray(result.data)) return result.data as OpenCodeProvider[];
+    return [];
+  }
+
+  async function getProviderAuth(): Promise<Record<string, Array<{ type: string; label: string }>>> {
+    const result = await proxy('/provider/auth');
+    if (!result.ok) return {};
+    return result.data as Record<string, Array<{ type: string; label: string }>>;
+  }
+
+  async function setProviderApiKey(providerID: string, apiKey: string): Promise<ProxyResult> {
+    return proxy(`/auth/${encodeURIComponent(providerID)}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: 'api', key: apiKey }),
+    });
+  }
+
+  async function startProviderOAuth(providerID: string, methodIndex: number): Promise<ProxyResult> {
+    return proxy(`/provider/${encodeURIComponent(providerID)}/oauth/authorize`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ method: methodIndex }),
+    });
+  }
+
+  async function completeProviderOAuth(providerID: string, methodIndex: number, code?: string): Promise<ProxyResult> {
+    return proxy(`/provider/${encodeURIComponent(providerID)}/oauth/callback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ method: methodIndex, ...(code ? { code } : {}) }),
+    });
+  }
+
+  async function getConfig(): Promise<Record<string, unknown> | null> {
+    const result = await proxy('/config');
+    if (!result.ok) return null;
+    return result.data as Record<string, unknown>;
+  }
+
+  async function isAvailable(): Promise<boolean> {
+    // OpenCode has no /health endpoint — check /provider instead
+    const result = await proxy('/provider');
+    return result.ok;
+  }
+
+  return {
+    proxy,
+    getProviders,
+    getProviderAuth,
+    setProviderApiKey,
+    startProviderOAuth,
+    completeProviderOAuth,
+    getConfig,
+    isAvailable,
+  };
+}

package/src/control-plane/provider-config.ts

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { ControlPlaneState } from './types.js';
+
+export type SecretProviderConfig = {
+  provider: 'plaintext' | 'pass';
+  passwordStoreDir?: string;
+  passPrefix?: string;
+};
+
+function providerConfigPath(state: ControlPlaneState): string {
+  return `${state.dataDir}/secrets/provider.json`;
+}
+
+export function readSecretProviderConfig(state: ControlPlaneState): SecretProviderConfig | null {
+  const path = providerConfigPath(state);
+  if (!existsSync(path)) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as SecretProviderConfig;
+    if (parsed?.provider === 'plaintext' || parsed?.provider === 'pass') {
+      return parsed;
+    }
+  } catch {
+    // ignore malformed provider config and fall back to schema detection
+  }
+
+  return null;
+}
+
+export function writeSecretProviderConfig(state: ControlPlaneState, config: SecretProviderConfig): void {
+  const dir = `${state.dataDir}/secrets`;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(providerConfigPath(state), JSON.stringify(config, null, 2) + '\n');
+}

package/src/control-plane/redact-schema.ts

@@ -0,0 +1,50 @@
+/**
+ * Auto-generates a `redact.env.schema` from the canonical secret mappings.
+ *
+ * This ensures that every env var carrying a secret is marked for redaction
+ * by varlock, without requiring manual maintenance of the schema file.
+ */
+import { getCoreSecretMappings } from './secret-mappings.js';
+
+/**
+ * Generate a redact.env.schema string from the canonical secret mappings.
+ *
+ * @param systemEnv - The current system env (used to discover dynamic channel secrets)
+ * @returns A complete `@env-spec` schema suitable for varlock redaction
+ */
+export function generateRedactSchema(systemEnv: Record<string, string>): string {
+  const lines: string[] = [
+    '# OpenPalm — Runtime Redaction Schema (auto-generated)',
+    '# Marks env vars as @sensitive so varlock redacts their values from',
+    '# stdout/stderr before they reach docker compose logs.',
+    '#',
+    '# @defaultSensitive=true',
+    '# @defaultRequired=false',
+    '# ---',
+    '',
+  ];
+
+  const envKeys = new Set<string>();
+  for (const mapping of getCoreSecretMappings(systemEnv)) {
+    envKeys.add(mapping.envKey);
+  }
+
+  // Include container-runtime env names that differ from env-file keys
+  // (compose maps OP_MEMORY_TOKEN -> MEMORY_AUTH_TOKEN, etc.)
+  envKeys.add('ADMIN_TOKEN');
+  envKeys.add('MEMORY_AUTH_TOKEN');
+  envKeys.add('OPENCODE_SERVER_PASSWORD');
+
+  // Resolved capability API keys (written to stack.env by spec-to-env)
+  envKeys.add('OP_CAP_LLM_API_KEY');
+  envKeys.add('OP_CAP_EMBEDDINGS_API_KEY');
+  envKeys.add('OP_CAP_TTS_API_KEY');
+  envKeys.add('OP_CAP_STT_API_KEY');
+  envKeys.add('OP_CAP_SLM_API_KEY');
+
+  for (const key of [...envKeys].sort()) {
+    lines.push(`${key}=`);
+  }
+
+  return lines.join('\n') + '\n';
+}

package/src/control-plane/registry-components.test.ts

@@ -0,0 +1,313 @@
+/**
+ * Tests for the registry component directory format.
+ *
+ * Validates that all components in .openpalm/registry/addons/ follow the
+ * component conventions: compose.yml with required labels, .env.schema
+ * with documented variables, proper service naming, and no security
+ * violations.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/** Resolve path from repo root */
+const REPO_ROOT = resolve(import.meta.dir, "../../../..");
+const REGISTRY_DIR = join(REPO_ROOT, ".openpalm/registry/addons");
+
+/** List all component directories in the registry */
+function listComponentDirs(): string[] {
+  if (!existsSync(REGISTRY_DIR)) return [];
+  return readdirSync(REGISTRY_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+
+/** Read a file from a component directory */
+function readComponentFile(componentId: string, filename: string): string {
+  return readFileSync(join(REGISTRY_DIR, componentId, filename), "utf-8");
+}
+
+/** Parse .env.schema into { variable, annotations, defaultValue, comments } entries */
+function parseEnvSchema(content: string): Array<{
+  variable: string;
+  defaultValue: string;
+  annotations: string[];
+  comments: string[];
+}> {
+  const entries: Array<{
+    variable: string;
+    defaultValue: string;
+    annotations: string[];
+    comments: string[];
+  }> = [];
+
+  const lines = content.split("\n");
+  let pendingComments: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith("#")) {
+      pendingComments.push(trimmed);
+      continue;
+    }
+
+    if (trimmed === "" || trimmed === "---") {
+      // Blank line or section separator — keep accumulating comments
+      // for the next variable.
+      continue;
+    }
+
+    const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)/);
+    if (match) {
+      const variable = match[1];
+      const defaultValue = match[2];
+
+      // Extract @annotations from pending comments
+      const annotations: string[] = [];
+      for (const c of pendingComments) {
+        const annots = c.match(/@[a-z]+/g);
+        if (annots) annotations.push(...annots);
+      }
+
+      entries.push({
+        variable,
+        defaultValue,
+        annotations,
+        comments: [...pendingComments],
+      });
+      pendingComments = [];
+    }
+  }
+
+  return entries;
+}
+
+// ── Discovery Tests ──────────────────────────────────────────────────────
+
+describe("registry component discovery", () => {
+  const componentIds = listComponentDirs();
+
+  it("finds at least one component in the registry", () => {
+    expect(componentIds.length).toBeGreaterThan(0);
+  });
+
+  it("contains the expected core components", () => {
+    expect(componentIds).toContain("chat");
+    expect(componentIds).toContain("api");
+    expect(componentIds).toContain("discord");
+    expect(componentIds).toContain("slack");
+    expect(componentIds).toContain("voice");
+  });
+
+  it("component IDs are valid (lowercase alphanumeric + hyphens)", () => {
+    const validIdRe = /^[a-z0-9][a-z0-9-]{0,62}$/;
+    for (const id of componentIds) {
+      expect(validIdRe.test(id)).toBe(true);
+    }
+  });
+});
+
+// ── Required Files Tests ─────────────────────────────────────────────────
+
+describe("registry component required files", () => {
+  const componentIds = listComponentDirs();
+
+  for (const id of componentIds) {
+    it(`${id}: has compose.yml`, () => {
+      expect(existsSync(join(REGISTRY_DIR, id, "compose.yml"))).toBe(true);
+    });
+
+    it(`${id}: has .env.schema`, () => {
+      expect(existsSync(join(REGISTRY_DIR, id, ".env.schema"))).toBe(true);
+    });
+  }
+});
+
+// ── Compose Overlay Validation Tests ─────────────────────────────────────
+
+describe("registry compose.yml validation", () => {
+  const componentIds = listComponentDirs();
+
+  for (const id of componentIds) {
+    describe(id, () => {
+      const compose = readComponentFile(id, "compose.yml");
+
+      it("has openpalm.name label", () => {
+        expect(compose).toMatch(/openpalm\.name:/);
+      });
+
+      it("has openpalm.description label", () => {
+        expect(compose).toMatch(/openpalm\.description:/);
+      });
+
+      it("uses static service name (no INSTANCE_ID)", () => {
+        expect(compose).not.toContain("${INSTANCE_ID}");
+      });
+
+      it("does not use container_name", () => {
+        expect(compose).not.toMatch(/container_name:/);
+      });
+
+      it("does not reference INSTANCE_DIR", () => {
+        expect(compose).not.toContain("${INSTANCE_DIR}");
+      });
+
+      it("joins a valid stack network", () => {
+        const hasValidNetwork = compose.includes("channel_lan") || compose.includes("channel_public") || compose.includes("assistant_net");
+        expect(hasValidNetwork).toBe(true);
+      });
+
+      it("has restart policy", () => {
+        expect(compose).toMatch(/restart:\s/);
+      });
+
+      it("has healthcheck", () => {
+        expect(compose).toMatch(/healthcheck:/);
+      });
+
+      it("does not mount vault directory (single-file mounts allowed)", () => {
+        // Directory-level vault mounts are a security violation — only admin gets full vault access.
+        // Single-file mounts like vault/user/ov.conf are allowed (the source must end with a filename).
+        const lines = compose.split("\n");
+        for (const line of lines) {
+          if (line.match(/^\s*-\s+.*vault.*:/)) {
+            // Extract the source portion (before first colon that follows a path)
+            const match = line.match(/^\s*-\s+(.+?):/);
+            if (match) {
+              const source = match[1];
+              // Allow single-file vault mounts (path ends with a file, i.e. has an extension or
+              // a non-directory final segment). Block bare vault/ or vault/<dir>/ mounts.
+              if (/vault\b/i.test(source) && !/vault\/.*\.[a-z]+$/i.test(source)) {
+                throw new Error(`Vault directory mount detected: ${line.trim()}`);
+              }
+            }
+          }
+        }
+      });
+
+      it("does not mount docker socket", () => {
+        // admin component is exempt — docker-socket-proxy IS the docker socket accessor by design
+        if (id === "admin") return;
+        expect(compose).not.toContain("/var/run/docker.sock");
+      });
+
+      it("has a comment header describing the component", () => {
+        expect(compose.startsWith("#")).toBe(true);
+      });
+    });
+  }
+});
+
+// ── .env.schema Validation Tests ─────────────────────────────────────────
+
+describe("registry .env.schema validation", () => {
+  const componentIds = listComponentDirs();
+
+  for (const id of componentIds) {
+    describe(id, () => {
+      const schema = readComponentFile(id, ".env.schema");
+      const entries = parseEnvSchema(schema);
+
+      it("is non-empty", () => {
+        expect(schema.length).toBeGreaterThan(0);
+      });
+
+      it("has at least one variable definition", () => {
+        expect(entries.length).toBeGreaterThan(0);
+      });
+
+      it("does not include INSTANCE_ID (removed)", () => {
+        const names = entries.map((e) => e.variable);
+        expect(names).not.toContain("INSTANCE_ID");
+      });
+
+      it("does not include INSTANCE_DIR (removed)", () => {
+        const names = entries.map((e) => e.variable);
+        expect(names).not.toContain("INSTANCE_DIR");
+      });
+
+      it("has at least one @required variable", () => {
+        const requiredEntries = entries.filter((e) =>
+          e.annotations.includes("@required")
+        );
+        expect(requiredEntries.length).toBeGreaterThan(0);
+      });
+
+      it("variable names are valid (uppercase with underscores)", () => {
+        const validVarRe = /^[A-Z_][A-Z0-9_]*$/;
+        for (const entry of entries) {
+          expect(validVarRe.test(entry.variable)).toBe(true);
+        }
+      });
+
+      it("every variable has at least one comment line above it", () => {
+        for (const entry of entries) {
+          expect(entry.comments.length).toBeGreaterThan(0);
+        }
+      });
+
+      it("does not contain vault references", () => {
+        expect(schema.toLowerCase()).not.toContain("vault/");
+      });
+    });
+  }
+});
+
+// ── Sensitive Fields Tests ───────────────────────────────────────────────
+
+describe("registry component sensitive fields", () => {
+  const componentIds = listComponentDirs();
+
+  for (const id of componentIds) {
+    it(`${id}: has at least one @sensitive field (channel secret)`, () => {
+      // ollama is a local inference server — no channel secret or API key needed
+      if (id === "ollama") return;
+      const schema = readComponentFile(id, ".env.schema");
+      const entries = parseEnvSchema(schema);
+      const sensitiveEntries = entries.filter((e) =>
+        e.annotations.includes("@sensitive")
+      );
+      expect(sensitiveEntries.length).toBeGreaterThan(0);
+    });
+  }
+});
+
+// ── Cross-Component Consistency Tests ────────────────────────────────────
+
+describe("cross-component consistency", () => {
+  const componentIds = listComponentDirs();
+
+  it("no duplicate openpalm.name labels across components", () => {
+    const names = new Set<string>();
+    for (const id of componentIds) {
+      const compose = readComponentFile(id, "compose.yml");
+      const nameMatch = compose.match(/openpalm\.name:\s*(.+)/);
+      expect(nameMatch).not.toBeNull();
+      const name = nameMatch![1].trim();
+      expect(names.has(name)).toBe(false);
+      names.add(name);
+    }
+  });
+
+  it("all components join a valid stack network", () => {
+    for (const id of componentIds) {
+      const compose = readComponentFile(id, "compose.yml");
+      const hasValidNetwork = compose.includes("channel_lan") || compose.includes("channel_public") || compose.includes("assistant_net");
+      expect(hasValidNetwork).toBe(true);
+    }
+  });
+
+  it("no compose file uses INSTANCE_ID anywhere", () => {
+    for (const id of componentIds) {
+      const compose = readComponentFile(id, "compose.yml");
+      expect(compose).not.toContain("INSTANCE_ID");
+    }
+  });
+});