@openpalm/lib 0.11.1 → 0.11.2-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.1",
+  "version": "0.11.2-rc.1",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",

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

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  detectExistingProject,
+  isProjectOurs,
+  resolveComposeProjectName,
+} from "./docker.js";
+
+describe("isProjectOurs (ours-vs-foreign decision)", () => {
+  it("treats a matching working_dir as ours", () => {
+    expect(isProjectOurs("/home/me/.openpalm", "/home/me/.openpalm")).toBe(true);
+  });
+
+  it("treats a different working_dir as foreign", () => {
+    expect(isProjectOurs("/home/other/.openpalm", "/home/me/.openpalm")).toBe(false);
+  });
+
+  it("treats an empty/unknown working_dir as ours (reconcile, don't refuse)", () => {
+    expect(isProjectOurs("", "/home/me/.openpalm")).toBe(true);
+    expect(isProjectOurs("   ", "/home/me/.openpalm")).toBe(true);
+  });
+
+  it("ignores surrounding whitespace on the label", () => {
+    expect(isProjectOurs("  /home/me/.openpalm \n", "/home/me/.openpalm")).toBe(true);
+  });
+});
+
+describe("detectExistingProject", () => {
+  // Use a project name that cannot possibly match any running container so the
+  // result is deterministic whether or not a docker daemon is present:
+  //  - docker error (no daemon)      → { exists:false }
+  //  - docker ok, no matching label  → { exists:false }
+  const ghostName = `openpalm-detect-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+  it("returns exists:false when no project matches (or docker is unavailable)", async () => {
+    const result = await detectExistingProject({
+      projectName: ghostName,
+      expectedWorkingDir: "/nonexistent/op_home",
+    });
+    expect(result.exists).toBe(false);
+    expect(result.isOurs).toBe(false);
+    expect(result.workingDir).toBe("");
+  });
+});
+
+describe("resolveComposeProjectName", () => {
+  const saved = process.env.OP_PROJECT_NAME;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.OP_PROJECT_NAME;
+    else process.env.OP_PROJECT_NAME = saved;
+  });
+
+  it("defaults to openpalm", () => {
+    delete process.env.OP_PROJECT_NAME;
+    delete process.env.COMPOSE_PROJECT_NAME;
+    expect(resolveComposeProjectName({})).toBe("openpalm");
+  });
+
+  it("honors OP_PROJECT_NAME from overrides first", () => {
+    expect(resolveComposeProjectName({ OP_PROJECT_NAME: "openpalm-dev" })).toBe("openpalm-dev");
+  });
+});

package/src/control-plane/docker.ts

@@ -51,6 +51,83 @@ export function resolveComposeProjectName(envOverrides: Record<string, string> =
   );
 }
 
+/**
+ * Result of probing the Docker daemon for an existing compose project that
+ * shares our project name.
+ *
+ * - `exists`   — at least one running container carries the project label.
+ * - `isOurs`   — those containers were launched from THIS install's working
+ *                dir (compose working_dir label === expectedWorkingDir). When
+ *                true the caller should reconcile in place (up --force-recreate).
+ *                When false a DIFFERENT OpenPalm install (e.g. dev vs host) owns
+ *                the name and the caller must refuse.
+ * - `workingDir` — the working_dir label read off the first container, for
+ *                error messages. Empty string when unknown.
+ */
+export type ExistingProject = {
+  exists: boolean;
+  isOurs: boolean;
+  workingDir: string;
+};
+
+/**
+ * Decide whether a running compose project (identified by its
+ * `com.docker.compose.project.working_dir` label) is OURS — i.e. was launched
+ * from this install's working dir. An empty/unknown label can't prove foreign,
+ * so it counts as ours (reconcile rather than wrongly refuse a redeploy).
+ *
+ * Pure decision split out from detectExistingProject so the ours-vs-foreign
+ * rule is unit-testable without a Docker daemon.
+ */
+export function isProjectOurs(workingDirLabel: string, expectedWorkingDir: string): boolean {
+  const label = workingDirLabel.trim();
+  return label === "" || label === expectedWorkingDir;
+}
+
+/**
+ * Probe the Docker daemon for a running compose project that shares
+ * `projectName`. Decides ours-vs-foreign by comparing the project's
+ * `com.docker.compose.project.working_dir` label against `expectedWorkingDir`
+ * (the install's OP_HOME / compose context).
+ *
+ * Returns `{ exists:false }` on any docker error (daemon down, no permission) —
+ * detection is best-effort and never blocks the caller; a real failure surfaces
+ * later through composeUp.
+ */
+export function detectExistingProject(opts: {
+  projectName: string;
+  expectedWorkingDir: string;
+}): Promise<ExistingProject> {
+  const none: ExistingProject = { exists: false, isOurs: false, workingDir: "" };
+  return new Promise((resolve) => {
+    execFile(
+      "docker",
+      ["ps", "-q", "--filter", `label=com.docker.compose.project=${opts.projectName}`],
+      { timeout: 10_000 },
+      (err, stdout) => {
+        if (err) return resolve(none);
+        const ids = stdout.toString().trim().split(/\s+/).filter(Boolean);
+        if (ids.length === 0) return resolve(none);
+        execFile(
+          "docker",
+          [
+            "inspect",
+            "--format",
+            '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}',
+            ids[0],
+          ],
+          { timeout: 10_000 },
+          (err2, stdout2) => {
+            if (err2) return resolve({ exists: true, isOurs: false, workingDir: "" });
+            const workingDir = stdout2.toString().trim();
+            resolve({ exists: true, isOurs: isProjectOurs(workingDir, opts.expectedWorkingDir), workingDir });
+          },
+        );
+      },
+    );
+  });
+}
+
 /** Check if Docker is available */
 export async function checkDocker(): Promise<DockerResult> {
   return new Promise((resolve) => {
@@ -172,7 +249,21 @@ export async function composeUp(
   if (options.forceRecreate) args.push("--force-recreate");
   if (options.removeOrphans) args.push("--remove-orphans");
   if (options.services?.length) args.push(...options.services);
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, composeUpTimeoutMs(), collectEnvOverrides(options.envFiles));
+}
+
+/**
+ * Timeout budget for `compose up`. A first install extracts multi-GB images
+ * (voice CUDA ~7.6 GB) onto slow disks; the previous hard 5-minute cap
+ * SIGTERM-killed the start mid-extraction and surfaced as an empty/opaque
+ * error. Default 30 min, override with OP_COMPOSE_UP_TIMEOUT_MS. Kept bounded
+ * (never removed) so a genuinely hung start still eventually fails.
+ */
+function composeUpTimeoutMs(): number {
+  const raw = process.env.OP_COMPOSE_UP_TIMEOUT_MS?.trim();
+  const parsed = raw ? Number(raw) : NaN;
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return 30 * 60_000;
 }
 
 /**

package/src/control-plane/hardware-detect.ts

@@ -11,7 +11,7 @@ import { createLogger } from "../logger.js";
 
 const logger = createLogger("hardware-detect");
 
-export type GpuVendor = "nvidia" | "amd" | "unknown";
+export type GpuVendor = "nvidia" | "amd" | "apple" | "unknown";
 
 export type GpuInfo = {
   vendor: GpuVendor;
@@ -27,6 +27,8 @@ type GpuProbe = {
   args: string[];
   /** Pure parser: tool stdout -> detected GPUs. Must not throw. */
   parse: (stdout: string) => GpuInfo[];
+  /** Optional gate — when present and false, the probe is skipped entirely. */
+  enabled?: boolean;
 };
 
 /** Parse `nvidia-smi --query-gpu=name,memory.total --format=csv,noheader,nounits`. */
@@ -68,6 +70,25 @@ export function parseRocmSmi(stdout: string): GpuInfo[] {
   return out;
 }
 
+/**
+ * Parse `sysctl -n hw.memsize hw.model` (two lines: total bytes, then model id)
+ * into an Apple-Silicon GpuInfo. `hw.memsize` is UNIFIED memory shared between
+ * CPU and GPU, carried here as vramMb for informational display only — callers
+ * must NOT treat it like discrete VRAM (see setup-recommendation). Pure; never throws.
+ */
+export function parseAppleSilicon(stdout: string): GpuInfo[] {
+  const lines = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return [];
+  const bytes = Number.parseInt(lines[0] ?? "", 10);
+  if (!Number.isFinite(bytes) || bytes <= 0) return [];
+  const vramMb = Math.round(bytes / (1024 * 1024));
+  const model = lines[1] && lines[1].length > 0 ? lines[1] : "arm64";
+  return [{ vendor: "apple", name: `Apple Silicon (${model})`, vramMb }];
+}
+
 const GPU_PROBES: GpuProbe[] = [
   {
     vendor: "nvidia",
@@ -81,6 +102,16 @@ const GPU_PROBES: GpuProbe[] = [
     args: ["--showmeminfo", "vram", "--showproductname", "--json"],
     parse: parseRocmSmi,
   },
+  {
+    // Apple Silicon Macs expose no nvidia-smi/rocm-smi. Probe macOS sysctl for
+    // unified-memory size + model id. Gated to darwin/arm64 so it never runs (and
+    // never spawns a missing binary) on Linux/Intel.
+    vendor: "apple",
+    command: "sysctl",
+    args: ["-n", "hw.memsize", "hw.model"],
+    parse: parseAppleSilicon,
+    enabled: process.platform === "darwin" && process.arch === "arm64",
+  },
 ];
 
 function run(command: string, args: string[], timeoutMs = 3_000): Promise<string | null> {
@@ -100,6 +131,7 @@ export async function detectGpu(): Promise<GpuInfo | null> {
   const found: GpuInfo[] = [];
   await Promise.all(
     GPU_PROBES.map(async (probe) => {
+      if (probe.enabled === false) return;
       const stdout = await run(probe.command, probe.args);
       if (stdout === null) return;
       try {

package/src/control-plane/setup-recommendation.test.ts

@@ -5,7 +5,7 @@ import {
   MIN_LOCAL_GPU_VRAM_MB,
   type SetupRecommendationInput,
 } from "./setup-recommendation.js";
-import { parseNvidiaSmi, parseRocmSmi, type GpuInfo } from "./hardware-detect.js";
+import { parseNvidiaSmi, parseRocmSmi, parseAppleSilicon, type GpuInfo } from "./hardware-detect.js";
 
 const base: SetupRecommendationInput = { cloudProviders: [], hostProviders: [], gpu: null };
 const gpu = (vendor: GpuInfo["vendor"], vramMb: number, name = "Test GPU"): GpuInfo => ({ vendor, name, vramMb });
@@ -53,6 +53,39 @@ describe("recommendSetup", () => {
     expect(r.action).toBe("connect-manually");
   });
 
+  test("darwin + apple GPU + no provider -> connect-manually (NOT enable-ollama), Mac-tailored alert", () => {
+    const r = recommendSetup({ ...base, platform: "darwin", gpu: gpu("apple", 65536, "Apple Silicon (Mac15,7)") });
+    expect(r.action).toBe("connect-manually");
+    expect(r.action).not.toBe("enable-ollama");
+    if (r.action === "connect-manually") {
+      expect(r.alert).toContain("macOS");
+      expect(r.alert).toContain("Metal");
+      expect(r.alert.toLowerCase()).toContain("ollama");
+    }
+  });
+
+  test("darwin + apple GPU never selects cuda/rocm (no in-stack enable)", () => {
+    // Even with huge unified memory, darwin+apple must not enable in-stack ollama.
+    const r = recommendSetup({ ...base, platform: "darwin", gpu: gpu("apple", 131072) });
+    expect(r.action).not.toBe("enable-ollama");
+  });
+
+  test("darwin + host ollama running -> still use-host-providers (wins over apple guidance)", () => {
+    const r = recommendSetup({
+      ...base,
+      platform: "darwin",
+      hostProviders: [{ provider: "ollama", url: "http://localhost:11434" }],
+      gpu: gpu("apple", 65536),
+    });
+    expect(r.action).toBe("use-host-providers");
+  });
+
+  test("linux + nvidia >= threshold -> still enable-ollama cuda (unchanged)", () => {
+    const r = recommendSetup({ ...base, platform: "linux", gpu: gpu("nvidia", 24576) });
+    expect(r.action).toBe("enable-ollama");
+    if (r.action === "enable-ollama") expect(r.profileVariant).toBe("cuda");
+  });
+
   test("no cloud, no host, no GPU -> connect-manually", () => {
     const r = recommendSetup(base);
     expect(r.action).toBe("connect-manually");
@@ -61,13 +94,32 @@ describe("recommendSetup", () => {
 });
 
 describe("gpuToProfileVariant", () => {
-  test("nvidia->cuda, amd->rocm, unknown->cpu", () => {
+  test("nvidia->cuda, amd->rocm, apple->cpu, unknown->cpu", () => {
     expect(gpuToProfileVariant(gpu("nvidia", 8192))).toBe("cuda");
     expect(gpuToProfileVariant(gpu("amd", 8192))).toBe("rocm");
+    expect(gpuToProfileVariant(gpu("apple", 65536))).toBe("cpu");
     expect(gpuToProfileVariant(gpu("unknown", 8192))).toBe("cpu");
   });
 });
 
+describe("parseAppleSilicon", () => {
+  test("parses hw.memsize bytes -> MiB + vendor apple + model name", () => {
+    const stdout = `${16 * 1024 * 1024 * 1024}\nMac15,7\n`;
+    const out = parseAppleSilicon(stdout);
+    expect(out).toEqual([{ vendor: "apple", name: "Apple Silicon (Mac15,7)", vramMb: 16384 }]);
+  });
+  test("missing model line -> falls back to arm64", () => {
+    const out = parseAppleSilicon(`${8 * 1024 * 1024 * 1024}\n`);
+    expect(out[0]?.vendor).toBe("apple");
+    expect(out[0]?.name).toBe("Apple Silicon (arm64)");
+    expect(out[0]?.vramMb).toBe(8192);
+  });
+  test("garbage / empty -> []", () => {
+    expect(parseAppleSilicon("")).toEqual([]);
+    expect(parseAppleSilicon("not-a-number\nMac15,7")).toEqual([]);
+  });
+});
+
 describe("parseNvidiaSmi", () => {
   test("parses name + VRAM (MiB), handles commas in name", () => {
     const out = parseNvidiaSmi("NVIDIA GeForce RTX 4090, 24564\nNVIDIA A100, 81920\n");

package/src/control-plane/setup-recommendation.ts

@@ -18,6 +18,10 @@ export const MIN_LOCAL_GPU_VRAM_MB = 8 * 1024;
 const VENDOR_PROFILE_VARIANT: Record<GpuVendor, "cuda" | "rocm" | "cpu"> = {
   nvidia: "cuda",
   amd: "rocm",
+  // The in-stack Ollama container on a Mac is a Linux container with no Metal
+  // access, so it can only ever run CPU. (On darwin apple GPUs are routed to
+  // host-Ollama guidance and never reach enable-ollama — see recommendSetup.)
+  apple: "cpu",
   unknown: "cpu",
 };
 
@@ -34,6 +38,13 @@ export type SetupRecommendationInput = {
   hostProviders: DetectedHostProvider[];
   /** Best detected GPU, or null. */
   gpu: GpuInfo | null;
+  /**
+   * Host platform. Defaults to `process.platform` when omitted, but the decision
+   * logic only reads this field (never `process.*`) so the function stays pure.
+   * On darwin the in-stack Linux Ollama can't reach the Mac's Metal GPU, so an
+   * apple GPU is routed to host-Ollama guidance instead of enable-ollama.
+   */
+  platform?: NodeJS.Platform;
 };
 
 export type SetupRecommendation =
@@ -58,11 +69,13 @@ const labelHostProviders = (h: DetectedHostProvider[]): string =>
  * Order (first match wins):
  *  1. cloud provider connected      -> use it.
  *  2. host-local provider running   -> add it, proceed.
- *  3. capable GPU (>= threshold)    -> enable in-stack Ollama.
- *  4. otherwise                     -> ask the user to connect a provider.
+ *  3. darwin + apple GPU            -> guide to HOST Ollama (Metal); never in-stack.
+ *  4. capable GPU (>= threshold)    -> enable in-stack Ollama.
+ *  5. otherwise                     -> ask the user to connect a provider.
  */
 export function recommendSetup(input: SetupRecommendationInput): SetupRecommendation {
   const { cloudProviders, hostProviders, gpu } = input;
+  const platform = input.platform ?? process.platform;
 
   if (cloudProviders.length > 0) {
     return { action: "use-cloud", cloudProviders };
@@ -78,6 +91,22 @@ export function recommendSetup(input: SetupRecommendationInput): SetupRecommenda
     };
   }
 
+  // macOS: the in-stack Ollama is a Linux container with no access to the Mac's
+  // Metal GPU, so enabling it would silently fall back to slow CPU. When the Mac
+  // has an Apple-Silicon GPU and nothing is connected yet, steer the user to a
+  // native host Ollama (which DOES use Metal) via connect-manually — reusing the
+  // existing action avoids a new wizard branch (chosen for minimal UI impact).
+  if (platform === "darwin" && gpu && gpu.vendor === "apple") {
+    return {
+      action: "connect-manually",
+      alert:
+        "No AI provider was detected. On macOS, fast local models need Ollama running " +
+        "natively (it uses your Apple Silicon / Metal GPU) — the bundled in-stack Ollama " +
+        "runs in Linux and cannot reach Metal. Install Ollama for macOS (https://ollama.com/download), " +
+        "or connect a provider on the next step.",
+    };
+  }
+
   if (gpu && gpu.vramMb >= MIN_LOCAL_GPU_VRAM_MB) {
     return {
       action: "enable-ollama",

package/src/index.ts

@@ -260,10 +260,11 @@ export {
 } from "./control-plane/lifecycle.js";
 
 // ── Docker ──────────────────────────────────────────────────────────────
-export type { DockerResult } from "./control-plane/docker.js";
+export type { DockerResult, ExistingProject } from "./control-plane/docker.js";
 export {
   checkDocker,
   checkDockerCompose,
+  detectExistingProject,
   resolveComposeProjectName,
   composePreflight,
   composeUp,
@@ -299,7 +300,7 @@ export { detectLocalProviders } from "./control-plane/model-runner.js";
 
 // ── Hardware detection + setup recommendation ───────────────────────────
 export type { GpuInfo, GpuVendor } from "./control-plane/hardware-detect.js";
-export { detectGpu, parseNvidiaSmi, parseRocmSmi } from "./control-plane/hardware-detect.js";
+export { detectGpu, parseNvidiaSmi, parseRocmSmi, parseAppleSilicon } from "./control-plane/hardware-detect.js";
 export type {
   DetectedHostProvider,
   SetupRecommendation,