@openpalm/lib 0.9.8 → 0.10.1

package/src/control-plane/setup-config.schema.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/itlackey/openpalm/main/packages/lib/src/control-plane/setup-config.schema.json",
+  "title": "OpenPalm SetupConfig",
+  "description": "Structured configuration for the OpenPalm setup wizard. Defines connections, model assignments, channels, services, and security settings needed for first-time installation or reconfiguration.",
+  "type": "object",
+  "required": ["version", "security", "capabilities", "assignments"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1,
+      "description": "Schema version. Must be 1."
+    },
+    "owner": {
+      "type": "object",
+      "description": "Optional owner identity for this OpenPalm instance.",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Display name of the instance owner."
+        },
+        "email": {
+          "type": "string",
+          "description": "Email address of the instance owner.",
+          "format": "email"
+        }
+      }
+    },
+    "security": {
+      "type": "object",
+      "description": "Security settings for the instance.",
+      "required": ["adminToken"],
+      "additionalProperties": false,
+      "properties": {
+        "adminToken": {
+          "type": "string",
+          "description": "Admin API authentication token. Used to authenticate CLI and admin UI requests.",
+          "minLength": 8
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "LLM provider capabilities available to the instance. Must contain at least one entry.",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/SetupCapability"
+      }
+    },
+    "assignments": {
+      "$ref": "#/$defs/SetupConfigAssignments"
+    },
+    "memory": {
+      "type": "object",
+      "description": "Optional memory subsystem configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "userId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_]+$",
+          "description": "User ID for the memory service. Alphanumeric and underscores only. Defaults to 'default_user' if omitted."
+        }
+      }
+    },
+    "channels": {
+      "type": "object",
+      "description": "Optional channel configurations. Keys are channel identifiers (e.g. 'chat', 'discord', 'api'). Values can be a boolean to enable (true) or skip (false) installation, or a credential object.",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "boolean",
+            "description": "Enable (true) or disable (false) this channel with default settings."
+          },
+          {
+            "$ref": "#/$defs/ChannelCredentials"
+          }
+        ]
+      }
+    },
+    "services": {
+      "type": "object",
+      "description": "Optional service configurations. Keys are service identifiers (e.g. 'admin', 'ollama'). Values can be a boolean to enable (true) or skip (false) installation, or a config object.",
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "boolean",
+            "description": "Enable (true) or disable (false) this service with default settings."
+          },
+          {
+            "$ref": "#/$defs/ServiceConfig"
+          }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "SetupCapability": {
+      "type": "object",
+      "description": "An LLM provider capability with endpoint and credentials.",
+      "required": ["id", "name", "provider", "baseUrl"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique capability identifier. Must start with a letter or digit; allows A-Z, a-z, 0-9, underscore, and hyphen.",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable display name for this capability.",
+          "minLength": 1
+        },
+        "provider": {
+          "type": "string",
+          "description": "Provider identifier. Must be a recognized provider from the wizard scope. 'ollama-instack' is an internal alias used by the CLI to route Ollama capabilities to the in-stack Ollama service container.",
+          "enum": [
+            "openai",
+            "anthropic",
+            "ollama",
+            "groq",
+            "together",
+            "mistral",
+            "deepseek",
+            "xai",
+            "lmstudio",
+            "model-runner",
+            "ollama-instack",
+            "google",
+            "huggingface"
+          ]
+        },
+        "baseUrl": {
+          "type": "string",
+          "description": "Base URL for the provider API endpoint. Can be empty for cloud providers that use default URLs."
+        },
+        "apiKey": {
+          "type": "string",
+          "description": "API key for authentication. Optional for local providers (e.g. Ollama, LM Studio) that do not require authentication."
+        }
+      }
+    },
+    "SetupConfigAssignments": {
+      "type": "object",
+      "description": "Model capability assignments mapping connections and models to system roles.",
+      "required": ["llm", "embeddings"],
+      "additionalProperties": false,
+      "properties": {
+        "llm": {
+          "type": "object",
+          "description": "Primary LLM assignment for the system.",
+          "required": ["capabilityId", "model"],
+          "additionalProperties": false,
+          "properties": {
+            "capabilityId": {
+              "type": "string",
+              "description": "ID of the connection to use for LLM inference. Must reference a capability in the capabilities array."
+            },
+            "model": {
+              "type": "string",
+              "description": "Model identifier for the primary LLM (e.g. 'gpt-4o', 'claude-sonnet-4-20250514')."
+            },
+            "smallModel": {
+              "type": "string",
+              "description": "Optional smaller/faster model for lightweight tasks (e.g. memory extraction)."
+            }
+          }
+        },
+        "embeddings": {
+          "type": "object",
+          "description": "Embedding model assignment for the memory subsystem.",
+          "required": ["capabilityId", "model"],
+          "additionalProperties": false,
+          "properties": {
+            "capabilityId": {
+              "type": "string",
+              "description": "ID of the connection to use for embeddings. Must reference a capability in the capabilities array."
+            },
+            "model": {
+              "type": "string",
+              "description": "Model identifier for embeddings (e.g. 'text-embedding-3-small', 'nomic-embed-text')."
+            },
+            "embeddingDims": {
+              "type": "integer",
+              "description": "Embedding vector dimensions. Auto-detected from known models if omitted.",
+              "minimum": 1
+            }
+          }
+        },
+        "tts": {
+          "description": "Optional text-to-speech assignment. Can be an engine name string, an object with engine details, or null to disable.",
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "TTS engine name (e.g. 'kokoro', 'piper', 'openai-tts', 'browser-tts')."
+            },
+            {
+              "$ref": "#/$defs/VoiceAssignment"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "stt": {
+          "description": "Optional speech-to-text assignment. Can be an engine name string, an object with engine details, or null to disable.",
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "STT engine name (e.g. 'whisper-local', 'openai-stt', 'browser-stt')."
+            },
+            {
+              "$ref": "#/$defs/VoiceAssignment"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "VoiceAssignment": {
+      "type": "object",
+      "description": "Detailed voice engine assignment with optional connection and model.",
+      "required": ["engine"],
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "type": "string",
+          "description": "Voice engine identifier."
+        },
+        "capabilityId": {
+          "type": "string",
+          "description": "Optional capability ID if the engine requires an API provider."
+        },
+        "model": {
+          "type": "string",
+          "description": "Optional model identifier for the voice engine."
+        }
+      }
+    },
+    "ChannelCredentials": {
+      "type": "object",
+      "description": "Channel configuration with optional credentials. Supports Discord, Slack, and custom channel fields.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether this channel is enabled. Defaults to true if the channel entry exists."
+        },
+        "botToken": {
+          "type": "string",
+          "description": "Discord bot token."
+        },
+        "applicationId": {
+          "type": "string",
+          "description": "Discord application ID."
+        },
+        "registerCommands": {
+          "type": "boolean",
+          "description": "Whether to register Discord slash commands on startup."
+        },
+        "allowedGuilds": {
+          "type": "string",
+          "description": "Comma-separated list of allowed Discord guild IDs."
+        },
+        "allowedRoles": {
+          "type": "string",
+          "description": "Comma-separated list of allowed Discord role IDs."
+        },
+        "allowedUsers": {
+          "type": "string",
+          "description": "Comma-separated list of allowed user IDs."
+        },
+        "blockedUsers": {
+          "type": "string",
+          "description": "Comma-separated list of blocked user IDs."
+        },
+        "slackBotToken": {
+          "type": "string",
+          "description": "Slack bot token (xoxb-...)."
+        },
+        "slackAppToken": {
+          "type": "string",
+          "description": "Slack app-level token (xapp-...)."
+        },
+        "allowedChannels": {
+          "type": "string",
+          "description": "Comma-separated list of allowed Slack channel IDs."
+        }
+      },
+      "additionalProperties": true
+    },
+    "ServiceConfig": {
+      "type": "object",
+      "description": "Service configuration with an enabled flag and optional extra settings.",
+      "required": ["enabled"],
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether this service is enabled."
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

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

@@ -1,8 +1,13 @@
 import { userInfo } from "node:os";
 import { parseEnvFile } from './env.js';
 
-export function readSecretsKeys(configDir: string): Record<string, boolean> {
-  const parsed = parseEnvFile(`${configDir}/secrets.env`);
+export function readSecretsKeys(vaultDir: string): Record<string, boolean> {
+  // System scope wins on overlap because vault/stack/stack.env is the
+  // authoritative source for system-managed credentials and flags.
+  const parsed = {
+    ...parseEnvFile(`${vaultDir}/user/user.env`),
+    ...parseEnvFile(`${vaultDir}/stack/stack.env`),
+  };
   const result: Record<string, boolean> = {};
   for (const [key, value] of Object.entries(parsed)) {
     result[key] = value.length > 0;
@@ -20,12 +25,14 @@ export function detectUserId(): string {
   }
 }
 
-export function isSetupComplete(stateDir: string, configDir: string): boolean {
-  const parsed = parseEnvFile(`${stateDir}/artifacts/stack.env`);
-  if ("OPENPALM_SETUP_COMPLETE" in parsed) {
-    return parsed.OPENPALM_SETUP_COMPLETE.toLowerCase() === "true";
+/**
+ * Check if setup is complete by reading vault/stack/stack.env.
+ */
+export function isSetupComplete(vaultDir: string): boolean {
+  const parsed = parseEnvFile(`${vaultDir}/stack/stack.env`);
+  if ("OP_SETUP_COMPLETE" in parsed) {
+    return parsed.OP_SETUP_COMPLETE.toLowerCase() === "true";
   }
 
-  const keys = readSecretsKeys(configDir);
-  return keys.OPENPALM_ADMIN_TOKEN === true || keys.ADMIN_TOKEN === true;
+  return (parsed.OP_ADMIN_TOKEN ?? "").length > 0;
 }

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

@@ -0,0 +1,90 @@
+/**
+ * Validation logic for SetupSpec inputs.
+ * Extracted from setup.ts to reduce per-file complexity.
+ */
+
+const CAPABILITY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+function requireObj(val: unknown, msg: string, errors: string[]): Record<string, unknown> | null {
+  if (typeof val !== "object" || val === null) { errors.push(msg); return null; }
+  return val as Record<string, unknown>;
+}
+
+function requireStr(obj: Record<string, unknown>, key: string, msg: string, errors: string[]): boolean {
+  if (typeof obj[key] !== "string" || !obj[key]) { errors.push(msg); return false; }
+  return true;
+}
+
+export function validateSetupSpec(input: unknown): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const body = requireObj(input, "Input must be a non-null object", errors);
+  if (!body) return { valid: false, errors };
+
+  validateSecurity(body, errors);
+  validateOwner(body, errors);
+  validateConnectionsArray(body.connections, errors);
+  validateSpecCapabilities(body, errors);
+  if (body.channelCredentials !== undefined && (typeof body.channelCredentials !== "object" || body.channelCredentials === null)) {
+    errors.push("channelCredentials must be an object if provided");
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function validateSecurity(body: Record<string, unknown>, errors: string[]): void {
+  const security = requireObj(body.security, "security object is required", errors);
+  if (!security) return;
+  if (!requireStr(security, "adminToken", "security.adminToken is required and must be a non-empty string", errors)) return;
+  if ((security.adminToken as string).length < 8) errors.push("security.adminToken must be at least 8 characters");
+}
+
+function validateOwner(body: Record<string, unknown>, errors: string[]): void {
+  const owner = body.owner as Record<string, unknown> | undefined;
+  if (!owner) return; // owner is optional
+  if (owner.name !== undefined && typeof owner.name !== "string") errors.push("owner.name must be a string");
+  if (owner.email !== undefined && typeof owner.email !== "string") errors.push("owner.email must be a string");
+}
+
+function validateSpecCapabilities(body: Record<string, unknown>, errors: string[]): void {
+  if (body.version !== 2) errors.push("version must be 2");
+  const caps = requireObj(body.capabilities, "capabilities is required", errors);
+  if (!caps) return;
+  requireStr(caps, "llm", "capabilities.llm is required (format: 'provider/model')", errors);
+  const emb = requireObj(caps.embeddings, "capabilities.embeddings is required", errors);
+  if (emb) {
+    requireStr(emb, "provider", "capabilities.embeddings.provider is required", errors);
+    requireStr(emb, "model", "capabilities.embeddings.model is required", errors);
+    if (emb.dims !== undefined && emb.dims !== 0 && (typeof emb.dims !== "number" || !Number.isInteger(emb.dims) || emb.dims < 1)) {
+      errors.push("capabilities.embeddings.dims must be a positive integer or 0 (auto-resolve)");
+    }
+  }
+  const mem = requireObj(caps.memory, "capabilities.memory is required", errors);
+  if (!mem) return;
+  if (mem.userId !== undefined && typeof mem.userId !== "string") errors.push("capabilities.memory.userId must be a string if provided");
+  if (typeof mem.userId === "string" && mem.userId && !/^[A-Za-z0-9_]+$/.test(mem.userId)) {
+    errors.push("capabilities.memory.userId contains invalid characters (alphanumeric and underscores only)");
+  }
+}
+
+function validateConnectionsArray(connections: unknown, errors: string[]): void {
+  if (!Array.isArray(connections)) {
+    errors.push("connections must be an array");
+    return;
+  }
+  const seenIds = new Set<string>();
+  for (let i = 0; i < connections.length; i++) {
+    const c = connections[i];
+    if (typeof c !== "object" || c === null) { errors.push(`connections[${i}] must be an object`); continue; }
+    const cap = c as Record<string, unknown>;
+    const id = typeof cap.id === "string" ? cap.id.trim() : "";
+    const provider = typeof cap.provider === "string" ? cap.provider.trim() : "";
+    const name = typeof cap.name === "string" ? cap.name.trim() : "";
+
+    if (!id) errors.push(`connections[${i}].id is required`);
+    else if (!CAPABILITY_ID_RE.test(id)) errors.push(`connections[${i}].id must start with a letter or digit (allowed: A-Z, a-z, 0-9, _, -)`);
+    else if (seenIds.has(id)) errors.push(`Duplicate capability ID: ${id}`);
+    else seenIds.add(id);
+
+    if (!name) errors.push(`connections[${i}].name is required`);
+    if (!provider) errors.push(`connections[${i}].provider is required`);
+  }
+}