@openpalm/lib 0.11.0-beta.1 → 0.11.0-beta.10

package/src/control-plane/operator-ids.test.ts

@@ -0,0 +1,130 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
+
+let tempDir = "";
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "openpalm-opids-"));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("resolveOperatorIds", () => {
+  test("returns the homeDir's owner when it exists and is non-root", () => {
+    // A mkdtemp directory is owned by the current process — neither
+    // root (in any reasonable test env) nor a hard-coded 1000.
+    const expected = statSync(tempDir);
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBe(expected.uid);
+    expect(ids!.gid).toBe(expected.gid);
+  });
+
+  test("falls back to process UID when homeDir does not exist", () => {
+    const missing = join(tempDir, "does-not-exist");
+    const ids = resolveOperatorIds(missing);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    // process.getuid is guaranteed on POSIX runtimes used by this test
+    expect(ids!.uid).toBe(process.getuid!());
+    expect(ids!.gid).toBe(process.getgid!());
+  });
+
+  test("never returns 0 (root) — falls back to process UID when homeDir is root-owned", () => {
+    // We can't easily chown a dir to root without root. Instead, exercise
+    // the branch via a faked statSync output: build a path that triggers
+    // the "owner is 0, prefer process UID" code path by ensuring real
+    // tempDir owner is the process UID and asserting the result for a
+    // missing path matches process UID (already covered above). The
+    // explicit 0-check is enforced by the implementation; this test
+    // documents that the function never *returns* 0 for any of the
+    // exercised inputs in a non-root test process.
+    const ids = resolveOperatorIds(tempDir);
+    if (process.platform === "win32") {
+      expect(ids).toBeNull();
+      return;
+    }
+    expect(ids).not.toBeNull();
+    expect(ids!.uid).toBeGreaterThan(0);
+    expect(ids!.gid).toBeGreaterThan(0);
+  });
+
+  test("returns null when BOTH homeDir owner and process UID/GID are 0 (root install on root-owned OP_HOME)", () => {
+    if (process.platform === "win32") {
+      // win32 short-circuits before any of this logic
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+      return;
+    }
+
+    // Stub process.getuid / getgid to simulate running as root. On Linux,
+    // `/` is owned by uid=0 gid=0, so passing "/" gives us a root-owned
+    // homeDir. Combined with the stubbed process IDs, this hits the
+    // "both signals are root" branch that previously returned {0,0}.
+    const origGetuid = process.getuid;
+    const origGetgid = process.getgid;
+    try {
+      (process as unknown as { getuid: () => number }).getuid = () => 0;
+      (process as unknown as { getgid: () => number }).getgid = () => 0;
+      // Sanity-check the assumption that "/" is root-owned in this env
+      // before relying on it as a fixture. On macOS / Linux CI runners
+      // this holds; if a future weird env breaks it, the assertion
+      // surfaces clearly rather than producing a confusing pass.
+      const rootStat = statSync("/");
+      expect(rootStat.uid).toBe(0);
+      expect(rootStat.gid).toBe(0);
+
+      const ids = resolveOperatorIds("/");
+      expect(ids).toBeNull();
+    } finally {
+      (process as unknown as { getuid: typeof origGetuid }).getuid = origGetuid;
+      (process as unknown as { getgid: typeof origGetgid }).getgid = origGetgid;
+    }
+  });
+
+  test("returns null on win32", () => {
+    // This test is informational; on non-win32 it doesn't run the win32
+    // branch. The check is left here for documentation and runs as a
+    // no-op assertion on POSIX.
+    if (process.platform === "win32") {
+      expect(resolveOperatorIds(tempDir)).toBeNull();
+    } else {
+      // No-op: confirms the test compiles and the helper is callable.
+      expect(typeof resolveOperatorIds).toBe("function");
+    }
+  });
+});
+
+describe("hasUsableOperatorId", () => {
+  test("returns true for positive numeric values", () => {
+    expect(hasUsableOperatorId({ OP_UID: "1000" }, "OP_UID")).toBe(true);
+    expect(hasUsableOperatorId({ OP_GID: "501" }, "OP_GID")).toBe(true);
+  });
+
+  test("returns false for missing key", () => {
+    expect(hasUsableOperatorId({}, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for empty string", () => {
+    expect(hasUsableOperatorId({ OP_UID: "" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for zero", () => {
+    expect(hasUsableOperatorId({ OP_UID: "0" }, "OP_UID")).toBe(false);
+  });
+
+  test("returns false for non-numeric garbage", () => {
+    expect(hasUsableOperatorId({ OP_UID: "abc" }, "OP_UID")).toBe(false);
+  });
+});

package/src/control-plane/operator-ids.ts

@@ -0,0 +1,89 @@
+/**
+ * Operator UID/GID detection for stack.env.
+ *
+ * Container processes that bind-mount host paths (voice models, addon
+ * caches, etc.) run as `${OP_UID}:${OP_GID}`. If those values are wrong,
+ * the container can't write to the mounted volume and the install
+ * silently degrades (model downloads stall, healthchecks time out).
+ *
+ * Detection strategy (Linux/macOS):
+ *   1. Stat OP_HOME. If it exists and is owned by a non-root user,
+ *      prefer that owner — operator may have created OP_HOME under a
+ *      different account than the one running install (e.g. sudo
+ *      install for a service user).
+ *   2. Otherwise fall back to the process's real UID/GID.
+ *   3. Never return 0 (root). Running install as root is allowed but
+ *      the container must run as the operator, not root.
+ *
+ * Returns `null` on Windows (containers run in WSL2's Linux; OP_UID
+ * has no meaning on the win32 host process itself).
+ */
+import { statSync } from "node:fs";
+
+export type OperatorIds = { uid: number; gid: number };
+
+/**
+ * Resolve the operator's UID/GID for stack.env.
+ * Returns null on Windows or when neither homeDir owner nor process
+ * UID/GID is available (e.g. process.getuid undefined on some runtimes).
+ */
+export function resolveOperatorIds(homeDir: string): OperatorIds | null {
+  if (process.platform === "win32") return null;
+
+  const processUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const processGid = typeof process.getgid === "function" ? process.getgid() : undefined;
+
+  let ownerUid: number | undefined;
+  let ownerGid: number | undefined;
+  try {
+    const st = statSync(homeDir);
+    ownerUid = st.uid;
+    ownerGid = st.gid;
+  } catch {
+    // homeDir may not exist yet during a first-time install — that's fine,
+    // we fall through to the process IDs below.
+  }
+
+  // Prefer the homeDir owner when it's a non-root user (the operator may
+  // have created OP_HOME under a different account than the one running
+  // install — e.g. an admin running `sudo openpalm install` on behalf of
+  // a service account).
+  const uid =
+    ownerUid !== undefined && ownerUid !== 0
+      ? ownerUid
+      : processUid !== undefined && processUid !== 0
+        ? processUid
+        : ownerUid; // last resort: homeDir owner even if 0, or undefined
+
+  const gid =
+    ownerGid !== undefined && ownerGid !== 0
+      ? ownerGid
+      : processGid !== undefined && processGid !== 0
+        ? processGid
+        : ownerGid;
+
+  if (uid === undefined || gid === undefined) return null;
+
+  // Final guard: never return 0 (root). This happens when BOTH the OP_HOME
+  // owner AND the process UID are root (e.g. `sudo openpalm install` on a
+  // freshly-created root-owned OP_HOME, common in CI builds and Docker-based
+  // installer flows). Returning null causes the caller to skip writing
+  // OP_UID/OP_GID to stack.env, and compose's `${OP_UID:-1000}` default
+  // kicks in — container runs as 1000:1000, which is the sane fallback
+  // when no real operator can be detected.
+  if (uid === 0 || gid === 0) return null;
+
+  return { uid, gid };
+}
+
+/**
+ * Returns true if the parsed stack.env already has a usable
+ * (non-zero, numeric) operator ID for the given key.
+ * Operator may have hand-set OP_UID/OP_GID; respect that.
+ */
+export function hasUsableOperatorId(parsed: Record<string, string>, key: "OP_UID" | "OP_GID"): boolean {
+  const raw = parsed[key];
+  if (!raw) return false;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0;
+}

package/src/control-plane/paths.ts

@@ -31,8 +31,6 @@ export const assistantConfigDir    = (s: ControlPlaneState): string => `${s.conf
 export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stackDir}/stack.env`;
 /** Guardian HMAC channel secrets */
 export const guardianEnvPath       = (s: ControlPlaneState): string => `${s.stackDir}/guardian.env`;
-/** Stack spec: capability assignments */
-export const stackSpecFilePath     = (s: ControlPlaneState): string => `${s.stackDir}/stack.yml`;
 
 // ── Cache directory — regenerable/semi-persistent ───────────────────────────
 
@@ -52,8 +50,15 @@ export const akmStateDir           = (s: ControlPlaneState): string => `${s.stat
 export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.cacheDir}/akm/tasks/logs/${id}`;
 export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.cacheDir}/akm/tasks/logs`;
 export const logsDir               = (s: ControlPlaneState): string => `${s.stateDir}/logs`;
-export const adminAuditPath        = (s: ControlPlaneState): string => `${s.stateDir}/logs/admin-audit.jsonl`;
+/**
+ * Guardian's own audit log of channel ingress (HMAC verify, replay, rate
+ * limit). Phase 6 of the auth/proxy refactor removed the OpenPalm-side
+ * `admin-audit.jsonl` — OpenCode session logs are the audit trail for
+ * chat + tool activity.
+ */
 export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.stateDir}/logs/guardian-audit.log`;
+/** One-shot 0.11.0 migration log (OP_UI_TOKEN → OPENCODE_SERVER_PASSWORD, endpoints.json move) */
+export const migration0110LogPath  = (s: ControlPlaneState): string => `${s.stateDir}/logs/migration-0.11.0.log`;
 export const backupsDir            = (s: ControlPlaneState): string => `${s.stateDir}/backups`;
 export const registryDir           = (s: ControlPlaneState): string => `${s.stateDir}/registry`;
 export const registryAddonsDir     = (s: ControlPlaneState): string => `${s.stateDir}/registry/addons`;

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

@@ -343,8 +343,9 @@ describe("registry component sensitive fields", () => {
 
   for (const id of fullAddonIds) {
     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;
+      // ollama and voice are local inference servers — no channel secret
+      // or upstream API key needed (LAN-only, no auth by design).
+      if (id === "ollama" || id === "voice") return;
       const schema = readComponentFile(id, ".env.schema");
       const entries = parseEnvSchema(schema);
       const sensitiveEntries = entries.filter((e) =>

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

@@ -21,11 +21,15 @@ import {
   getRegistryAddonConfig,
   listAvailableAddonIds,
   getAddonServiceNames,
-  enableAddon,
-  disableAddonByName,
+  getAddonProfiles,
+  getAddonProfileSelection,
+  setAddonProfileSelection,
   setAddonEnabled,
   installAutomationFromRegistry,
   uninstallAutomation,
+  getAddonProfileAvailability,
+  annotateAddonProfileAvailability,
+  __addonAvailabilityTestHooks,
 } from "./registry.js";
 
 // ── Validation Tests ─────────────────────────────────────────────────
@@ -306,10 +310,11 @@ describe("materialized registry catalog", () => {
 
     materializeRegistryCatalog(sourceRoot);
 
-    expect(enableAddon(process.env.OP_HOME!, 'chat')).toEqual({ ok: true });
+    const stackDir = join(process.env.OP_HOME!, 'config', 'stack');
+    expect(setAddonEnabled(process.env.OP_HOME!, stackDir, 'chat', true)).toMatchObject({ ok: true });
     expect(existsSync(join(process.env.OP_HOME!, 'config', 'stack', 'addons', 'chat', 'compose.yml'))).toBe(true);
 
-    expect(disableAddonByName(process.env.OP_HOME!, 'chat')).toEqual({ ok: true });
+    expect(setAddonEnabled(process.env.OP_HOME!, stackDir, 'chat', false)).toMatchObject({ ok: true });
     expect(existsSync(join(process.env.OP_HOME!, 'config', 'stack', 'addons', 'chat'))).toBe(false);
   });
 
@@ -391,6 +396,67 @@ describe("materialized registry catalog", () => {
     expect(existsSync(join(otherHome, 'backups', 'config', 'stack.yml'))).toBe(false);
   });
 
+  it("parses compose profiles + openpalm.profile.* labels per addon", () => {
+    const sourceRoot = join(tmpDir, 'repo');
+    const addonDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'addons', 'voice');
+    const automationsDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'automations');
+
+    mkdirSync(addonDir, { recursive: true });
+    mkdirSync(automationsDir, { recursive: true });
+    writeFileSync(
+      join(addonDir, 'compose.yml'),
+      [
+        'services:',
+        '  voice:',
+        '    profiles: [cpu]',
+        '    image: openpalm/voice:cpu',
+        '    labels:',
+        '      openpalm.profile.label: CPU',
+        '      openpalm.profile.default: "true"',
+        '  voice-cuda:',
+        '    profiles: [cuda]',
+        '    image: openpalm/voice:cuda',
+        '    labels:',
+        '      openpalm.profile.label: NVIDIA',
+        '      openpalm.profile.requires: nvidia-container-toolkit',
+        '',
+      ].join('\n'),
+    );
+    writeFileSync(join(addonDir, '.env.schema'), 'VOICE=\n');
+    writeFileSync(join(automationsDir, 'cleanup.md'), '---\ndescription: Cleanup\nschedule: "0 3 * * *"\ncommand: ["echo","clean"]\n---\n');
+
+    materializeRegistryCatalog(sourceRoot);
+
+    const profiles = getAddonProfiles(process.env.OP_HOME!, 'voice');
+    expect(profiles).toEqual([
+      { id: 'cpu', services: ['voice'], label: 'CPU', default: true },
+      { id: 'cuda', services: ['voice-cuda'], label: 'NVIDIA', requires: 'nvidia-container-toolkit' },
+    ]);
+  });
+
+  it("round-trips addon profile selection through stack.env", () => {
+    const sourceRoot = join(tmpDir, 'repo');
+    const addonDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'addons', 'voice');
+    const automationsDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'automations');
+
+    mkdirSync(addonDir, { recursive: true });
+    mkdirSync(automationsDir, { recursive: true });
+    writeFileSync(join(addonDir, 'compose.yml'), 'services:\n  voice:\n    profiles: [cpu]\n    image: x\n');
+    writeFileSync(join(addonDir, '.env.schema'), 'VOICE=\n');
+    writeFileSync(join(automationsDir, 'cleanup.md'), '---\ndescription: Cleanup\nschedule: "0 3 * * *"\ncommand: ["echo","clean"]\n---\n');
+
+    materializeRegistryCatalog(sourceRoot);
+
+    const stackDir = join(process.env.OP_HOME!, 'config', 'stack');
+    mkdirSync(stackDir, { recursive: true });
+    writeFileSync(join(stackDir, 'stack.env'), '');
+
+    expect(getAddonProfileSelection(stackDir, 'voice')).toBeNull();
+    setAddonProfileSelection(stackDir, 'voice', 'cuda');
+    expect(getAddonProfileSelection(stackDir, 'voice')).toBe('cuda');
+    expect(readFileSync(join(stackDir, 'stack.env'), 'utf-8')).toContain('OP_VOICE_PROFILE=cuda');
+  });
+
   it("installs and uninstalls automations through stash/tasks", () => {
     const sourceRoot = join(tmpDir, 'repo');
     const addonDir = join(sourceRoot, '.openpalm', 'state', 'registry', 'addons', 'chat');
@@ -414,3 +480,131 @@ describe("materialized registry catalog", () => {
     expect(existsSync(join(stashDir, 'tasks', 'cleanup.md'))).toBe(false);
   });
 });
+
+// ── Host capability probes ───────────────────────────────────────────
+
+describe("getAddonProfileAvailability", () => {
+  beforeEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  afterEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  it("returns available:true for the cpu profile (no host requirements)", async () => {
+    const result = await getAddonProfileAvailability({ id: 'cpu' });
+    expect(result.available).toBe(true);
+    expect(result.reason).toBeUndefined();
+  });
+
+  it("returns available:true for unknown profile ids (no host-side gating)", async () => {
+    const result = await getAddonProfileAvailability({ id: 'something-else' });
+    expect(result.available).toBe(true);
+  });
+
+  it("caches the result across calls (probe runs only once)", async () => {
+    const a = await getAddonProfileAvailability({ id: 'cpu' });
+    const b = await getAddonProfileAvailability({ id: 'cpu' });
+    expect(a).toBe(b); // same reference — cached
+  });
+
+  it("probes cuda: returns available:false on a host with no NVIDIA runtime / CDI", async () => {
+    // This test runs on CI/dev machines without GPUs. We don't mock execFile;
+    // we just assert the contract: when neither signal is present, the
+    // reason mentions nvidia-container-toolkit. If a future GPU host runs
+    // this test, the assertion still tolerates the success case.
+    const result = await getAddonProfileAvailability({ id: 'cuda' });
+    if (!result.available) {
+      expect(result.reason).toContain('NVIDIA');
+    } else {
+      // Host genuinely has the runtime registered — accept it.
+      expect(result.reason).toBeUndefined();
+    }
+  });
+
+  it("probes rocm: returns available:false when /dev/kfd is missing", async () => {
+    const result = await getAddonProfileAvailability({ id: 'rocm' });
+    if (!result.available) {
+      expect(result.reason).toContain('ROCm');
+    } else {
+      expect(result.reason).toBeUndefined();
+    }
+  });
+
+  it("probes rocm: when devices exist, reports unpublished image distinctly from missing-device case", async () => {
+    // On a host without /dev/kfd, we hit the device-missing branch and
+    // get the "devices not present" copy. On a ROCm host, we'd fall
+    // through to the manifest-inspect probe and (until 0.11.0-rocm6
+    // ships) get the "image not published yet" copy. Both must mention
+    // ROCm so operator-facing copy stays consistent.
+    const result = await getAddonProfileAvailability({ id: 'rocm' });
+    if (!result.available && existsSync('/dev/kfd') && existsSync('/dev/dri')) {
+      expect(result.reason).toMatch(/image not published|CPU profile/i);
+    }
+    if (!result.available && !(existsSync('/dev/kfd') && existsSync('/dev/dri'))) {
+      expect(result.reason).toMatch(/devices not present/i);
+    }
+  });
+});
+
+describe("execFileNoThrow (ENOENT capture)", () => {
+  it("captures ENOENT for a missing binary as 'spawn <cmd> ENOENT' stderr", async () => {
+    const result = await __addonAvailabilityTestHooks.execFileNoThrow(
+      '/nonexistent/path/to/openpalm-test-no-such-binary-zzz',
+      ['--help'],
+      2_000,
+    );
+    expect(result.ok).toBe(false);
+    expect(result.stderr).toMatch(/ENOENT/);
+    // When the binary is "docker", the synthetic stderr becomes
+    // `spawn docker ENOENT: command not found` — that string matches the
+    // translateDockerError regex `/spawn .*docker.*ENOENT/i` so the
+    // operator gets actionable copy instead of "unknown error (no stderr)".
+    expect(result.stderr).toMatch(/spawn\s+\S*\s*ENOENT/);
+  });
+
+  it("formats ENOENT for `docker` so translateDockerError can match it", async () => {
+    // Use an absolute path that we know doesn't exist so the test is
+    // deterministic regardless of whether docker is installed on the host.
+    const result = await __addonAvailabilityTestHooks.execFileNoThrow(
+      'docker-not-installed-zzz',
+      ['info'],
+      2_000,
+    );
+    expect(result.ok).toBe(false);
+    expect(result.stderr).toBe('spawn docker-not-installed-zzz ENOENT: command not found');
+  });
+});
+
+describe("annotateAddonProfileAvailability", () => {
+  beforeEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  afterEach(() => {
+    __addonAvailabilityTestHooks.reset();
+  });
+
+  it("decorates each profile with available + optional reason", async () => {
+    const out = await annotateAddonProfileAvailability([
+      { id: 'cpu', services: ['voice'], label: 'CPU', default: true },
+      { id: 'rocm', services: ['voice-rocm'], label: 'AMD' },
+    ]);
+    expect(out).toHaveLength(2);
+    expect(out[0]?.id).toBe('cpu');
+    expect(out[0]?.available).toBe(true);
+    // Preserves original fields.
+    expect(out[0]?.label).toBe('CPU');
+    expect(out[0]?.default).toBe(true);
+    expect(out[1]?.id).toBe('rocm');
+    expect(typeof out[1]?.available).toBe('boolean');
+  });
+
+  it("does not mutate the input array", async () => {
+    const input = [{ id: 'cpu', services: ['voice'] }];
+    const before = JSON.parse(JSON.stringify(input));
+    await annotateAddonProfileAvailability(input);
+    expect(input).toEqual(before);
+  });
+});