@openpalm/lib 0.9.8 → 0.10.1

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

@@ -1,40 +1,104 @@
 /**
- * Stack specification file (openpalm.yaml) management.
+ * Stack specification file (stack.yml) management.
  *
  * The stack spec is a YAML document that captures the high-level
- * configuration of an OpenPalm installation: connections, capability
- * assignments, and feature flags. It lives in CONFIG_HOME.
+ * configuration of an OpenPalm installation: capabilities only.
+ * It lives in CONFIG_HOME.
+ *
+ * v2: Capabilities-based schema. No connections array — capabilities
+ *     carry their own provider info.
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
 import { stringify as yamlStringify, parse as yamlParse } from "yaml";
 
-// ── Types ──────────────────────────────────────────────────────────────
+// ── Capability Types ────────────────────────────────────────────────────
 
-export type StackSpecConnection = {
-  id: string;
-  name: string;
+export type StackSpecEmbeddings = {
   provider: string;
-  baseUrl: string;
+  model: string;
+  dims: number;
+};
+
+export type StackSpecMemory = {
+  userId: string;
+  customInstructions?: string;
+};
+
+export type StackSpecTts = {
+  enabled: boolean;
+  provider?: string;
+  model?: string;
+  voice?: string;
+  format?: string;
+};
+
+export type StackSpecStt = {
+  enabled: boolean;
+  provider?: string;
+  model?: string;
+  language?: string;
+};
+
+export type StackSpecReranker = {
+  enabled: boolean;
+  provider?: string;
+  mode?: "llm" | "dedicated";
+  model?: string;
+  topK?: number;
+  topN?: number;
 };
 
-export type StackSpecAssignments = {
-  llm: { connectionId: string; model: string; smallModel?: string };
-  embeddings: { connectionId: string; model: string; embeddingDims?: number };
+export type StackSpecCapabilities = {
+  /** Primary LLM: "provider/model" */
+  llm: string;
+  /** Small/fast model: "provider/model" */
+  slm?: string;
+  embeddings: StackSpecEmbeddings;
+  memory: StackSpecMemory;
+  tts?: StackSpecTts;
+  stt?: StackSpecStt;
+  reranking?: StackSpecReranker;
 };
 
+// ── StackSpec v2 ────────────────────────────────────────────────────────
+
 export type StackSpec = {
-  version: 3;
-  connections: StackSpecConnection[];
-  assignments: StackSpecAssignments;
-  ollamaEnabled: boolean;
-  voice?: { tts?: string; stt?: string };
-  channels?: string[];
-  services?: Record<string, boolean>;
+  version: 2;
+  capabilities: StackSpecCapabilities;
 };
 
-// ── Constants ──────────────────────────────────────────────────────────
+// ── Constants ───────────────────────────────────────────────────────────
+
+export const STACK_SPEC_FILENAME = "stack.yml";
+
+export const SPEC_DEFAULTS = {
+  ports: {
+    assistant: 3800,
+    admin: 3880,
+    adminOpencode: 3881,
+    memory: 3898,
+    guardian: 3899,
+    assistantSsh: 2222,
+  },
+  image: {
+    namespace: "openpalm",
+    tag: "latest",
+  },
+} as const;
 
-export const STACK_SPEC_FILENAME = "openpalm.yaml";
+// ── Capability Helpers ──────────────────────────────────────────────────
+
+/** Parse a "provider/model" capability string into parts */
+export function parseCapabilityString(cap: string): { provider: string; model: string } {
+  const idx = cap.indexOf("/");
+  if (idx < 0) return { provider: cap, model: "" };
+  return { provider: cap.slice(0, idx), model: cap.slice(idx + 1) };
+}
+
+/** Format provider + model into a capability string */
+export function formatCapabilityString(provider: string, model: string): string {
+  return `${provider}/${model}`;
+}
 
 // ── Read / Write ────────────────────────────────────────────────────────
 
@@ -48,17 +112,32 @@ export function writeStackSpec(configDir: string, spec: StackSpec): void {
   writeFileSync(stackSpecPath(configDir), content);
 }
 
+/**
+ * Read the stack spec. Returns null for missing, corrupt, or unrecognized version files.
+ */
 export function readStackSpec(configDir: string): StackSpec | null {
   const path = stackSpecPath(configDir);
   if (!existsSync(path)) return null;
+
   let raw: unknown;
   try {
-    raw = yamlParse(readFileSync(path, "utf-8"));
+    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 !== 3) return null;
+  if (obj.version !== 2) return null;
+  if (typeof obj.capabilities !== "object" || obj.capabilities === null) return null;
   return obj as unknown as StackSpec;
 }
+
+/**
+ * Update a single capability key in the stack spec.
+ */
+export function updateCapability(configDir: string, key: string, value: unknown): void {
+  const spec = readStackSpec(configDir);
+  if (!spec) throw new Error("stack.yml not found or invalid");
+  (spec.capabilities as Record<string, unknown>)[key] = value;
+  writeStackSpec(configDir, spec);
+}

package/src/control-plane/types.ts

@@ -10,90 +10,15 @@ export type CoreServiceName =
   | "memory"
   | "scheduler";
 
-export type OptionalServiceName = "admin" | "caddy" | "docker-socket-proxy";
+export type OptionalServiceName = "admin" | "docker-socket-proxy";
 
 export type AccessScope = "host" | "lan";
 export type CallerType = "assistant" | "cli" | "ui" | "system" | "test" | "unknown";
 
-export type ConnectionKind =
-  | "openai_compatible_remote"
-  | "openai_compatible_local"
-  | "ollama_local";
-
-export type ConnectionAuthMode = "api_key" | "none";
-
-export type CanonicalConnectionProfile = {
-  id: string;
-  name: string;
-  kind: ConnectionKind;
-  provider: string;
-  baseUrl: string;
-  auth: {
-    mode: ConnectionAuthMode;
-    apiKeySecretRef?: string;
-  };
-};
-
-export type RequiredCapability = "llm" | "embeddings";
-export type OptionalCapability = "reranking" | "tts" | "stt";
-export type Capability = RequiredCapability | OptionalCapability;
-
-export type LlmAssignment = {
-  connectionId: string;
-  model: string;
-  smallModel?: string;
-};
-
-export type EmbeddingsAssignment = {
-  connectionId: string;
-  model: string;
-  embeddingDims?: number;
-};
-
-export type RerankerAssignment = {
-  enabled: boolean;
-  connectionId?: string;
-  mode?: "llm" | "dedicated";
-  model?: string;
-  topK?: number;
-  topN?: number;
-};
-
-export type TtsAssignment = {
-  enabled: boolean;
-  connectionId?: string;
-  model?: string;
-  voice?: string;
-  format?: string;
-};
-
-export type SttAssignment = {
-  enabled: boolean;
-  connectionId?: string;
-  model?: string;
-  language?: string;
-};
-
-export type CapabilityAssignments = {
-  llm: LlmAssignment;
-  embeddings: EmbeddingsAssignment;
-  reranking?: RerankerAssignment;
-  tts?: TtsAssignment;
-  stt?: SttAssignment;
-};
-
-export type CanonicalConnectionsDocument = {
-  version: 1;
-  profiles: CanonicalConnectionProfile[];
-  assignments: CapabilityAssignments;
-};
-
 /** Info about a discovered channel */
 export type ChannelInfo = {
   name: string;
-  hasRoute: boolean;
   ymlPath: string;
-  caddyPath: string | null;
 };
 
 export type AuditEntry = {
@@ -115,18 +40,20 @@ export type ArtifactMeta = {
 
 export type ControlPlaneState = {
   adminToken: string;
+  assistantToken: string;
   setupToken: string;
-  stateDir: string;
+  homeDir: string;
   configDir: string;
+  vaultDir: string;
   dataDir: string;
+  logsDir: string;
+  cacheDir: string;
   services: Record<string, "running" | "stopped">;
   artifacts: {
     compose: string;
-    caddyfile: string;
   };
   artifactMeta: ArtifactMeta[];
   audit: AuditEntry[];
-  channelSecrets: Record<string, string>;
 };
 
 // ── Constants ──────────────────────────────────────────────────────────
@@ -139,26 +66,6 @@ export const CORE_SERVICES: CoreServiceName[] = [
 ];
 
 export const OPTIONAL_SERVICES: OptionalServiceName[] = [
-  "caddy",
   "admin",
   "docker-socket-proxy",
 ];
-
-export const CONNECTION_KINDS: ConnectionKind[] = [
-  "openai_compatible_remote",
-  "openai_compatible_local",
-  "ollama_local",
-];
-
-export const REQUIRED_CAPABILITIES: RequiredCapability[] = [
-  "llm",
-  "embeddings",
-];
-
-export const OPTIONAL_CAPABILITIES: OptionalCapability[] = [
-  "reranking",
-  "tts",
-  "stt",
-];
-
-export const MAX_AUDIT_MEMORY = 1000;

package/src/control-plane/validate.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime configuration validation for the OpenPalm control plane.
+ *
+ * Proposed changes are validated against temp copies before writing
+ * to live paths.
+ */
+import { existsSync, copyFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { ControlPlaneState } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Resolve the varlock binary path — honours VARLOCK_BIN for dev environments. */
+const envVarlockBin = process.env.VARLOCK_BIN;
+let VARLOCK_BIN = "varlock";
+if (envVarlockBin) {
+  if (envVarlockBin === "varlock" || envVarlockBin.startsWith("/")) {
+    VARLOCK_BIN = envVarlockBin;
+  }
+}
+
+function sanitizeVarlockMessage(msg: string): string {
+  return msg
+    .replace(/sk-[A-Za-z0-9]{20,}/g, "[REDACTED]")
+    .replace(/gsk_[A-Za-z0-9]{30,}/g, "[REDACTED]")
+    .replace(/AIza[A-Za-z0-9_\-]{35}/g, "[REDACTED]")
+    .replace(/[0-9a-f]{32,}/gi, "[REDACTED]")
+    .replace(/value '([^']*)'/g, "value '[REDACTED]'");
+}
+
+async function runVarlockLoad(
+  schemaFile: string,
+  envFile: string,
+): Promise<void> {
+  const tmpDir = mkdtempSync(join(tmpdir(), "varlock-"));
+  try {
+    copyFileSync(schemaFile, join(tmpDir, ".env.schema"));
+    copyFileSync(envFile, join(tmpDir, ".env"));
+    await execFileAsync(
+      VARLOCK_BIN,
+      ["load", "--path", `${tmpDir}/`],
+      { timeout: 10000 },
+    );
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Validate the current live configuration files in place.
+ *
+ * Checks:
+ * 1. vault/user/user.env against vault/user/user.env.schema
+ * 2. vault/stack/stack.env against vault/stack/stack.env.schema
+ */
+export async function validateProposedState(state: ControlPlaneState): Promise<{
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+}> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  let anyFailed = false;
+
+  function collectOutput(stderr: string): void {
+    for (const line of stderr.split("\n")) {
+      const trimmed = sanitizeVarlockMessage(line.trim());
+      if (!trimmed) continue;
+      if (trimmed.includes("ERROR")) errors.push(trimmed);
+      else if (trimmed.includes("WARN")) warnings.push(trimmed);
+    }
+  }
+
+  // Validate user.env
+  const userEnvSchema = `${state.vaultDir}/user/user.env.schema`;
+  const userEnv = `${state.vaultDir}/user/user.env`;
+  if (existsSync(userEnvSchema) && existsSync(userEnv)) {
+    try {
+      await runVarlockLoad(userEnvSchema, userEnv);
+    } catch (err: unknown) {
+      anyFailed = true;
+      if (err && typeof err === "object" && "stderr" in err) {
+        collectOutput(String((err as { stderr: string }).stderr));
+      }
+    }
+  }
+
+  // Validate stack.env
+  const systemEnvSchema = `${state.vaultDir}/stack/stack.env.schema`;
+  const systemEnv = `${state.vaultDir}/stack/stack.env`;
+  if (existsSync(systemEnvSchema) && existsSync(systemEnv)) {
+    try {
+      await runVarlockLoad(systemEnvSchema, systemEnv);
+    } catch (err: unknown) {
+      anyFailed = true;
+      if (err && typeof err === "object" && "stderr" in err) {
+        collectOutput(String((err as { stderr: string }).stderr));
+      }
+    }
+  }
+
+  return { ok: !anyFailed && errors.length === 0, errors, warnings };
+}