@openpalm/lib 0.11.0-rc.6 → 0.11.1

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

@@ -0,0 +1,98 @@
+// Pure decision engine for "what should setup do about AI providers?".
+//
+// Inputs are gathered by the caller (detected cloud providers, host-local
+// providers, GPU). This module makes the call and produces a recommendation +
+// user-facing alert. It is intentionally pure and free of I/O so it is trivially
+// unit-testable and easy to evolve as new hardware/providers/models ship — the
+// only things to edit are the constants at the top and the ordered rules in
+// recommendSetup().
+
+import type { GpuInfo, GpuVendor } from "./hardware-detect.js";
+
+export type { GpuInfo, GpuVendor } from "./hardware-detect.js";
+
+/** Minimum VRAM to auto-enable in-stack Ollama for local models. Edit freely. */
+export const MIN_LOCAL_GPU_VRAM_MB = 8 * 1024;
+
+/** Ollama hardware-profile variant chosen per GPU vendor. Extend per new vendor. */
+const VENDOR_PROFILE_VARIANT: Record<GpuVendor, "cuda" | "rocm" | "cpu"> = {
+  nvidia: "cuda",
+  amd: "rocm",
+  unknown: "cpu",
+};
+
+export function gpuToProfileVariant(gpu: GpuInfo): "cuda" | "rocm" | "cpu" {
+  return VENDOR_PROFILE_VARIANT[gpu.vendor] ?? "cpu";
+}
+
+export type DetectedHostProvider = { provider: string; url: string };
+
+export type SetupRecommendationInput = {
+  /** Cloud providers already connected (api-key / oauth / env). */
+  cloudProviders: string[];
+  /** Local providers reachable on the host (e.g. ollama, lmstudio), available only. */
+  hostProviders: DetectedHostProvider[];
+  /** Best detected GPU, or null. */
+  gpu: GpuInfo | null;
+};
+
+export type SetupRecommendation =
+  // A cloud provider is connected — nothing to auto-configure; proceed normally.
+  | { action: "use-cloud"; cloudProviders: string[] }
+  // No cloud, but local providers are running on the host — add them and proceed
+  // to model detection.
+  | { action: "use-host-providers"; hostProviders: DetectedHostProvider[]; alert: string }
+  // No provider at all, but a capable GPU exists — enable in-stack Ollama.
+  | { action: "enable-ollama"; profileVariant: "cuda" | "rocm" | "cpu"; gpu: GpuInfo; alert: string }
+  // No provider and no capable GPU — the user must connect one manually.
+  | { action: "connect-manually"; alert: string };
+
+const fmtGb = (mb: number): string => (mb / 1024).toFixed(mb % 1024 === 0 ? 0 : 1);
+
+const labelHostProviders = (h: DetectedHostProvider[]): string =>
+  h.map((p) => p.provider).join(" and ");
+
+/**
+ * Decide what setup should do, given detected providers + hardware.
+ *
+ * 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.
+ */
+export function recommendSetup(input: SetupRecommendationInput): SetupRecommendation {
+  const { cloudProviders, hostProviders, gpu } = input;
+
+  if (cloudProviders.length > 0) {
+    return { action: "use-cloud", cloudProviders };
+  }
+
+  if (hostProviders.length > 0) {
+    return {
+      action: "use-host-providers",
+      hostProviders,
+      alert: `No cloud AI provider was detected, but ${labelHostProviders(hostProviders)} ${
+        hostProviders.length > 1 ? "are" : "is"
+      } running on your computer — added automatically. Pick your models on the next step.`,
+    };
+  }
+
+  if (gpu && gpu.vramMb >= MIN_LOCAL_GPU_VRAM_MB) {
+    return {
+      action: "enable-ollama",
+      profileVariant: gpuToProfileVariant(gpu),
+      gpu,
+      alert: `No AI provider was detected, but a capable GPU was found (${gpu.name}, ${fmtGb(
+        gpu.vramMb,
+      )} GB). Local models via Ollama have been enabled for you.`,
+    };
+  }
+
+  return {
+    action: "connect-manually",
+    alert:
+      "No AI provider was detected and no GPU with enough memory for local models was found. " +
+      "Connect a provider to continue — sign in to a provider on the next step, or add a custom OpenAI-compatible endpoint and key.",
+  };
+}

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

@@ -10,7 +10,6 @@ import {
   performSetup,
 } from "./setup.js";
 import type { SetupSpec, SetupConnection } from "./setup.js";
-import { STACK_SPEC_FILENAME, readStackSpec } from "./stack-spec.js";
 import { readSecret } from './secrets-files.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────────
@@ -431,15 +430,6 @@ describe("performSetup", () => {
     expect(config.llm).toBeUndefined();
   });
 
-  it("writes stack.yml v2 version marker", async () => {
-    const result = await performSetup(makeValidSpec());
-    expect(result.ok).toBe(true);
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
-  });
-
   it("writes core compose file to stack/", async () => {
     const result = await performSetup(makeValidSpec());
     expect(result.ok).toBe(true);
@@ -522,16 +512,10 @@ describe("performSetup", () => {
     }
   });
 
-  it("writes stack.yml as version marker only", async () => {
+  it("does not create a stack.yml (addon state lives in stack.env)", async () => {
     const result = await performSetup(makeValidSpec());
     expect(result.ok).toBe(true);
-
-    const specPath = join(stackDir, STACK_SPEC_FILENAME);
-    expect(existsSync(specPath)).toBe(true);
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
+    expect(existsSync(join(stackDir, "stack.yml"))).toBe(false);
   });
 
   it("completes setup with multiple connections", async () => {
@@ -545,10 +529,6 @@ describe("performSetup", () => {
     const result = await performSetup(input);
     expect(result.ok).toBe(true);
 
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
-
     const stackEnv = readFileSync(join(homeDir, "knowledge", "env", "stack.env"), 'utf-8');
     expect(stackEnv).not.toContain('OPENAI_API_KEY=');
     expect(readSecret(stackDir, 'openai_api_key')).toBeNull();

package/src/control-plane/setup.ts

@@ -24,7 +24,6 @@ import {
   writeAuthJsonProviderKeys,
 } from "./secrets.js";
 import { createState } from "./lifecycle.js";
-import { readStackSpec, writeStackSpec } from "./stack-spec.js";
 import { writeVoiceVars } from "./spec-to-env.js";
 import type { ControlPlaneState } from "./types.js";
 import { validateSetupSpec } from "./setup-validation.js";
@@ -221,9 +220,6 @@ export async function performSetup(
     // single try/catch so that a disk-full or permission-denied mid-way returns a
     // clean error rather than leaving a broken half-installed ~/.openpalm/.
     try {
-      // Preserve addon enablement while refreshing the stack schema marker.
-      writeStackSpec(state.stackDir, readStackSpec(state.stackDir) ?? { version: 2 });
-
       // Write image tag and AKM mount paths to stack.env — atomic to avoid
       // partial writes if the process is interrupted mid-write.
       const systemEnvForAkm = existsSync(`${state.stashDir}/env/stack.env`)

package/src/control-plane/skeleton-guardrail.test.ts

@@ -57,12 +57,13 @@ describe("skeleton: helper scripts", () => {
 // ── config/ subdirectory ──────────────────────────────────────────────
 
 describe("skeleton: .openpalm/config/ structure", () => {
-  test("config/stack/ exists with fixed compose files and stack.yml", () => {
+  test("config/stack/ exists with fixed compose files (no stack.yml)", () => {
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "core.compose.yml"))).toBe(true);
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "services.compose.yml"))).toBe(true);
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "channels.compose.yml"))).toBe(true);
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "custom.compose.yml"))).toBe(true);
-    expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.yml"))).toBe(true);
+    // stack.yml removed in 0.11.0 — addon enablement lives in stack.env.
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.yml"))).toBe(false);
   });
 
   test("config/stack/addons/ does not exist", () => {

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

@@ -5,7 +5,7 @@
  * Voice channel vars (TTS/STT) are written separately via writeVoiceVars.
  */
 
-import { SPEC_DEFAULTS } from "./stack-spec.js";
+import { SPEC_DEFAULTS } from "./defaults.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { mergeEnvContent } from "./env.js";
@@ -14,7 +14,7 @@ import { assertNoSecretLikeStackEnvKeys } from './secrets.js';
 import { stackEnvPathFromStackDir } from './paths.js';
 
 /**
- * Derive the system.env key-value pairs from the StackSpec.
+ * Derive the system.env key-value pairs from the setup spec + defaults.
  * Secrets (tokens, API keys, HMAC) are NOT included — the caller merges them.
  */
 export function deriveSystemEnvFromSpec(homeDir: string): Record<string, string> {

package/src/control-plane/upgrade-path.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Upgrade-path regression tests.
+ *
+ * #449 — Check-up "latest" install: a `latest` (or empty) tag selection must be
+ * resolved to the concrete newest published platform tag BEFORE fetching stack
+ * assets. GitHub has no `.openpalm/...` asset tree at a `latest` ref, so passing
+ * `latest` straight through used to fail with a raw download error.
+ *
+ * #450 — "Update now" must force-recreate guardian + channel containers so they
+ * re-resolve their npm dist-tag adapters; guardian must never fall out of the
+ * recreated service set.
+ */
+import { describe, test, expect, afterEach } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolveLatestPlatformTag, applyTagChange } from "./lifecycle.js";
+import type { ControlPlaneState } from "./types.js";
+
+const LIB_CONTROL_PLANE_DIR = join(import.meta.dir);
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+function dockerTagsResponse(names: string[]): Response {
+  return new Response(
+    JSON.stringify({ results: names.map((name) => ({ name })) }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+}
+
+// ── #449: latest-tag resolution ──────────────────────────────────────────
+
+describe("resolveLatestPlatformTag (#449)", () => {
+  test("returns the newest semver tag from the Docker registry", async () => {
+    globalThis.fetch = (async () =>
+      dockerTagsResponse(["latest", "v0.11.0", "edge"])) as typeof fetch;
+
+    const tag = await resolveLatestPlatformTag("openpalm");
+    expect(tag).toBe("v0.11.0");
+  });
+
+  test("throws when the registry yields no usable tag", async () => {
+    globalThis.fetch = (async () => dockerTagsResponse(["latest"])) as typeof fetch;
+    await expect(resolveLatestPlatformTag("openpalm")).rejects.toThrow(
+      /No usable Docker image tag/,
+    );
+  });
+});
+
+describe("applyTagChange latest resolution (#449)", () => {
+  function makeState(): ControlPlaneState {
+    const home = mkdtempSync(join(tmpdir(), "openpalm-upgrade-test-"));
+    mkdirSync(join(home, "knowledge", "env"), { recursive: true });
+    writeFileSync(join(home, "knowledge", "env", "stack.env"), "OP_IMAGE_NAMESPACE=openpalm\n");
+    return {
+      homeDir: home,
+      configDir: join(home, "config"),
+      stashDir: join(home, "knowledge"),
+      workspaceDir: join(home, "workspace"),
+      dataDir: join(home, "data"),
+      stackDir: join(home, "config", "stack"),
+      services: {},
+      artifacts: { compose: "" },
+      artifactMeta: [],
+    };
+  }
+
+  test('a "latest" selection that cannot be resolved fails with a clear validation error, not a raw download error', async () => {
+    globalThis.fetch = (async () => {
+      throw new Error("network down");
+    }) as typeof fetch;
+
+    const state = makeState();
+    // Resolution happens BEFORE any asset download, so the error must be the
+    // resolution message — never the GitHub "Failed to download ..." error.
+    await expect(applyTagChange(state, "latest")).rejects.toThrow(
+      /Cannot resolve "latest" to a concrete release/,
+    );
+  });
+
+  test('an empty selection is treated like "latest" and resolved (not passed through as a blank ref)', async () => {
+    globalThis.fetch = (async () => {
+      throw new Error("network down");
+    }) as typeof fetch;
+
+    const state = makeState();
+    await expect(applyTagChange(state, "   ")).rejects.toThrow(
+      /Cannot resolve "latest" to a concrete release/,
+    );
+  });
+});
+
+// ── #450: upgrade recreates guardian + channel containers ─────────────────
+
+describe("performUpgrade force-recreates managed services (#450)", () => {
+  test("performUpgrade passes forceRecreate to composeUp", () => {
+    const src = readFileSync(join(LIB_CONTROL_PLANE_DIR, "lifecycle.ts"), "utf-8");
+    // The post-pull composeUp in performUpgrade must force-recreate so channel
+    // containers re-resolve their dist-tag adapters.
+    expect(src).toMatch(/composeUp\(\{[^}]*forceRecreate:\s*true/);
+  });
+
+  test("buildManagedServices always includes the core services (guardian)", () => {
+    const src = readFileSync(join(LIB_CONTROL_PLANE_DIR, "lifecycle.ts"), "utf-8");
+    // Guardian comes from CORE_SERVICES and must be seeded into the set
+    // regardless of how the rest of the service list is discovered.
+    expect(src).toContain("new Set<string>(CORE_SERVICES)");
+  });
+});

package/src/index.ts

@@ -39,6 +39,15 @@ export {
   backupOpenPalmHome,
 } from "./control-plane/backup.js";
 
+// ── Layout migration harness ────────────────────────────────────────────────
+export {
+  ensureMigrated,
+  MigrationError,
+  CURRENT_LAYOUT_VERSION,
+  LAYOUT_VERSION_KEY,
+} from "./control-plane/migrations.js";
+export type { MigrationReport } from "./control-plane/migrations.js";
+
 // ── Registry Catalog ─────────────────────────────────────────────────────
 export type {
   AddonMutationResult,
@@ -243,6 +252,7 @@ export {
   applyUpgrade,
   performUpgrade,
   applyTagChange,
+  resolveLatestPlatformTag,
   updateStackEnvToLatestImageTag,
   buildComposeFileList,
   buildManagedServices,
@@ -287,6 +297,20 @@ export {
 export type { LocalProviderDetection } from "./control-plane/model-runner.js";
 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 type {
+  DetectedHostProvider,
+  SetupRecommendation,
+  SetupRecommendationInput,
+} from "./control-plane/setup-recommendation.js";
+export {
+  recommendSetup,
+  gpuToProfileVariant,
+  MIN_LOCAL_GPU_VRAM_MB,
+} from "./control-plane/setup-recommendation.js";
+
 // ── Compose Arguments ────────────────────────────────────────────────────
 export {
   buildComposeOptions,
@@ -307,16 +331,6 @@ export {
   summarizeComposeStderr,
 } from "./control-plane/compose-errors.js";
 
-// ── Stack Spec (v2) ──────────────────────────────────────────────────────
-export type {
-  StackSpec,
-} from "./control-plane/stack-spec.js";
-export {
-  STACK_SPEC_FILENAME,
-  writeStackSpec,
-  readStackSpec,
-} from "./control-plane/stack-spec.js";
-
 // ── Spec-to-Env Derivation ──────────────────────────────────────────────
 export type { VoiceVarsConfig } from "./control-plane/spec-to-env.js";
 export {

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

@@ -1,98 +0,0 @@
-/**
- * Stack spec parser tests.
- *
- * Verifies that readStackSpec / writeStackSpec produce consistent results.
- */
-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,
-} 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 });
-});
-
-const MINIMAL_SPEC: StackSpec = { version: 2 };
-
-// ── readStackSpec / writeStackSpec round-trip ────────────────────────────
-
-describe("readStackSpec / writeStackSpec round-trip", () => {
-  it("round-trips a minimal spec", () => {
-    writeStackSpec(configDir, MINIMAL_SPEC);
-    const read = readStackSpec(configDir);
-    expect(read).not.toBeNull();
-    expect(read!.version).toBe(2);
-  });
-
-  it("round-trips enabled addons", () => {
-    writeStackSpec(configDir, { version: 2, addons: ['chat', 'api'] });
-    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['api', 'chat'] });
-  });
-
-  it("writes to the canonical filename", () => {
-    writeStackSpec(configDir, MINIMAL_SPEC);
-    const expectedPath = join(configDir, STACK_SPEC_FILENAME);
-    expect(expectedPath).toBe(join(configDir, "stack.yml"));
-    expect(readStackSpec(configDir)).not.toBeNull();
-  });
-
-  it("ignores legacy capabilities fields on read", () => {
-    // On upgraded installs, old stack.yml may have capabilities — should still parse
-    writeFileSync(join(configDir, STACK_SPEC_FILENAME),
-      "version: 2\ncapabilities:\n  llm: openai/gpt-4o\n  embeddings:\n    provider: openai\n    model: text-embedding-3-small\n    dims: 1536\n"
-    );
-    const read = readStackSpec(configDir);
-    expect(read).not.toBeNull();
-    expect(read!.version).toBe(2);
-  });
-});
-
-// ── 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 valid spec for version 2 with no other fields", () => {
-    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\n");
-    const spec = readStackSpec(configDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
-  });
-
-  it("ignores malformed addon names", () => {
-    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\naddons:\n  - chat\n  - ../bad\n  - API\n");
-    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['chat'] });
-  });
-});
-
-// ── STACK_SPEC_FILENAME ───────────────────────────────────────────────────
-
-describe("STACK_SPEC_FILENAME", () => {
-  it("is stack.yml", () => {
-    expect(STACK_SPEC_FILENAME).toBe("stack.yml");
-  });
-});

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

@@ -1,88 +0,0 @@
-/**
- * Stack specification file (stack.yml) management.
- *
- * The stack spec is a YAML document used as a version marker for the
- * OpenPalm installation schema. AI provider configuration lives in
- * config/akm/config.json (managed via the admin AKM tab).
- *
- * v2: capabilities removed — LLM/embedding now live in akm config.
- */
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
-import { stringify as yamlStringify, parse as yamlParse } from "yaml";
-
-// ── StackSpec v2 ────────────────────────────────────────────────────────
-
-export type StackSpec = {
-  version: 2;
-  addons?: string[];
-};
-
-const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
-
-// ── Constants ───────────────────────────────────────────────────────────
-
-export const STACK_SPEC_FILENAME = "stack.yml";
-
-export const SPEC_DEFAULTS = {
-  ports: {
-    assistant: 3800,
-    hostUi: 3880,
-    assistantSsh: 2222,
-  },
-  image: {
-    namespace: "openpalm",
-    tag: "latest",
-  },
-} as const;
-
-// ── Read / Write ────────────────────────────────────────────────────────
-
-export function writeStackSpec(configDir: string, spec: StackSpec): void {
-  mkdirSync(configDir, { recursive: true });
-  const content = yamlStringify(spec, { indent: 2 });
-  writeFileSync(`${configDir}/${STACK_SPEC_FILENAME}`, content);
-}
-
-/**
- * Read the stack spec. Returns null for missing or corrupt files.
- * Only the version field is checked; legacy capability fields are ignored.
- */
-export function readStackSpec(configDir: string): StackSpec | null {
-  const path = `${configDir}/${STACK_SPEC_FILENAME}`;
-  if (!existsSync(path)) return null;
-
-  let raw: unknown;
-  try {
-    raw = yamlParse(readFileSync(path, "utf-8"), { maxAliasCount: 100 });
-  } catch {
-    return null;
-  }
-  if (typeof raw !== "object" || raw === null) return null;
-  const obj = raw as Record<string, unknown>;
-  if (obj.version !== 2) return null;
-  const spec: StackSpec = { version: 2 };
-  if (Array.isArray(obj.addons)) {
-    const addons = obj.addons
-      .filter((value): value is string => typeof value === 'string' && ADDON_NAME_RE.test(value))
-      .filter((value, index, all) => all.indexOf(value) === index)
-      .sort();
-    if (addons.length > 0) spec.addons = addons;
-  }
-  return spec;
-}
-
-export function listStackSpecAddons(configDir: string): string[] {
-  return readStackSpec(configDir)?.addons ?? [];
-}
-
-export function setStackSpecAddon(configDir: string, name: string, enabled: boolean): void {
-  if (!ADDON_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
-  const current = readStackSpec(configDir) ?? { version: 2 };
-  const addons = new Set(current.addons ?? []);
-  if (enabled) addons.add(name);
-  else addons.delete(name);
-  const next: StackSpec = { version: 2 };
-  const sorted = [...addons].sort();
-  if (sorted.length > 0) next.addons = sorted;
-  writeStackSpec(configDir, next);
-}