@frumu/tandem-panel 0.4.9 → 0.4.11

package/lib/setup/env.js

@@ -0,0 +1,190 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { mkdir } from "fs/promises";
+import { randomBytes } from "crypto";
+import { dirname, resolve } from "path";
+
+import { resolveSetupPaths } from "./paths.js";
+
+function parseDotEnv(content) {
+  const out = {};
+  for (const raw of String(content || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const idx = line.indexOf("=");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function serializeEnv(entries) {
+  return `${entries.map(([k, v]) => `${k}=${v}`).join("\n")}\n`;
+}
+
+function loadDotEnvFile(pathname, targetEnv = process.env) {
+  if (!pathname || !existsSync(pathname)) return false;
+  const parsed = parseDotEnv(readFileSync(pathname, "utf8"));
+  for (const [key, value] of Object.entries(parsed)) {
+    if (targetEnv[key] === undefined) targetEnv[key] = value;
+  }
+  return true;
+}
+
+function resolveEnvLoadOrder(options = {}) {
+  const env = options.env || process.env;
+  const cwd = resolve(options.cwd || process.cwd());
+  const paths = resolveSetupPaths({
+    env,
+    platform: options.platform,
+    home: options.home,
+    allowAmbientStateEnv: options.allowAmbientStateEnv,
+  });
+  const explicit = String(options.explicitEnvFile || env.TANDEM_CONTROL_PANEL_ENV_FILE || "").trim();
+  const order = [];
+  if (explicit) order.push(resolve(explicit));
+  order.push(paths.envFile);
+  order.push(resolve(cwd, ".env"));
+  return [...new Set(order.filter(Boolean))];
+}
+
+function bootstrapDefaults(paths) {
+  return {
+    TANDEM_CONTROL_PANEL_PORT: "39732",
+    TANDEM_CONTROL_PANEL_HOST: "127.0.0.1",
+    TANDEM_CONTROL_PANEL_PUBLIC_URL: "",
+    TANDEM_ENGINE_URL: "http://127.0.0.1:39731",
+    TANDEM_ENGINE_HOST: "127.0.0.1",
+    TANDEM_ENGINE_PORT: "39731",
+    TANDEM_CONTROL_PANEL_AUTO_START_ENGINE: "1",
+    TANDEM_CONTROL_PANEL_STATE_DIR: paths.controlPanelStateDir,
+    TANDEM_STATE_DIR: paths.engineStateDir,
+    TANDEM_CONTROL_PANEL_ENGINE_TOKEN: "tk_change_me",
+    TANDEM_DISABLE_TOOL_GUARD_BUDGETS: "1",
+    TANDEM_TOOL_ROUTER_ENABLED: "0",
+    TANDEM_PROMPT_CONTEXT_HOOK_TIMEOUT_MS: "5000",
+    TANDEM_PROVIDER_STREAM_CONNECT_TIMEOUT_MS: "30000",
+    TANDEM_PROVIDER_STREAM_IDLE_TIMEOUT_MS: "90000",
+    TANDEM_PERMISSION_WAIT_TIMEOUT_MS: "15000",
+    TANDEM_TOOL_EXEC_TIMEOUT_MS: "45000",
+    TANDEM_BASH_TIMEOUT_MS: "30000",
+    TANDEM_CONTROL_PANEL_SESSION_TTL_MINUTES: "1440",
+  };
+}
+
+async function ensureBootstrapEnv(options = {}) {
+  const cwd = resolve(options.cwd || process.cwd());
+  const paths = resolveSetupPaths({
+    env: options.env || process.env,
+    platform: options.platform,
+    allowAmbientStateEnv: options.allowAmbientStateEnv,
+  });
+  const envPath = resolve(options.envPath || paths.envFile);
+  const overwrite = options.overwrite === true;
+  const cwdEnvPath = resolve(cwd, ".env");
+  const sourceExamplePath = resolve(cwd, ".env.example");
+  const existing = existsSync(envPath) ? parseDotEnv(readFileSync(envPath, "utf8")) : {};
+  const cwdEnv =
+    options.allowCwdEnvMerge !== false && envPath !== cwdEnvPath && existsSync(cwdEnvPath)
+      ? parseDotEnv(readFileSync(cwdEnvPath, "utf8"))
+      : {};
+  const example = options.allowCwdEnvMerge !== false && existsSync(sourceExamplePath)
+    ? parseDotEnv(readFileSync(sourceExamplePath, "utf8"))
+    : {};
+  const defaults = { ...bootstrapDefaults(paths), ...example };
+  const merged = { ...defaults, ...cwdEnv, ...existing };
+
+  if (
+    overwrite ||
+    !merged.TANDEM_CONTROL_PANEL_ENGINE_TOKEN ||
+    merged.TANDEM_CONTROL_PANEL_ENGINE_TOKEN === "tk_change_me"
+  ) {
+    merged.TANDEM_CONTROL_PANEL_ENGINE_TOKEN = `tk_${randomBytes(16).toString("hex")}`;
+  }
+
+  merged.TANDEM_CONTROL_PANEL_STATE_DIR =
+    merged.TANDEM_CONTROL_PANEL_STATE_DIR || paths.controlPanelStateDir;
+  merged.TANDEM_STATE_DIR = merged.TANDEM_STATE_DIR || paths.engineStateDir;
+  merged.TANDEM_CONTROL_PANEL_HOST = merged.TANDEM_CONTROL_PANEL_HOST || "127.0.0.1";
+
+  const preferredOrder = [
+    "TANDEM_CONTROL_PANEL_PORT",
+    "TANDEM_CONTROL_PANEL_HOST",
+    "TANDEM_CONTROL_PANEL_PUBLIC_URL",
+    "TANDEM_ENGINE_URL",
+    "TANDEM_ENGINE_HOST",
+    "TANDEM_ENGINE_PORT",
+    "TANDEM_STATE_DIR",
+    "TANDEM_CONTROL_PANEL_STATE_DIR",
+    "TANDEM_CONTROL_PANEL_AUTO_START_ENGINE",
+    "TANDEM_CONTROL_PANEL_ENGINE_TOKEN",
+    "TANDEM_CONTROL_PANEL_SESSION_TTL_MINUTES",
+  ];
+
+  const ordered = [];
+  for (const key of preferredOrder) {
+    if (merged[key] !== undefined) ordered.push([key, merged[key]]);
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (!preferredOrder.includes(key)) ordered.push([key, value]);
+  }
+
+  await mkdir(dirname(envPath), { recursive: true });
+  await mkdir(paths.logsDir, { recursive: true });
+  await mkdir(paths.engineStateDir, { recursive: true });
+  await mkdir(paths.controlPanelStateDir, { recursive: true });
+  writeFileSync(envPath, serializeEnv(ordered), "utf8");
+
+  return {
+    envPath,
+    token: merged.TANDEM_CONTROL_PANEL_ENGINE_TOKEN,
+    engineUrl:
+      merged.TANDEM_ENGINE_URL ||
+      `http://${merged.TANDEM_ENGINE_HOST || "127.0.0.1"}:${merged.TANDEM_ENGINE_PORT || "39731"}`,
+    panelHost: merged.TANDEM_CONTROL_PANEL_HOST || "127.0.0.1",
+    panelPort: merged.TANDEM_CONTROL_PANEL_PORT || "39732",
+    paths,
+    env: merged,
+  };
+}
+
+async function bootstrapEngineConfig(options = {}) {
+  const env = options.env || {};
+  const stateDir = resolve(String(env.TANDEM_STATE_DIR || options.stateDir || "").trim() || ".");
+  const configPath = resolve(stateDir, "config.json");
+  if (existsSync(configPath)) return { configPath, created: false };
+  await mkdir(dirname(configPath), { recursive: true });
+  writeFileSync(
+    configPath,
+    JSON.stringify(
+      {
+        default_provider: "openrouter",
+        providers: {
+          openrouter: { default_model: "google/gemini-2.5-pro-preview" },
+          openai: { default_model: "gpt-4o-mini" },
+          anthropic: { default_model: "claude-sonnet-4-5-latest" },
+        },
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  return { configPath, created: true };
+}
+
+export {
+  bootstrapEngineConfig,
+  ensureBootstrapEnv,
+  loadDotEnvFile,
+  parseDotEnv,
+  resolveEnvLoadOrder,
+  serializeEnv,
+};

package/lib/setup/paths.js

@@ -0,0 +1,65 @@
+import { homedir } from "os";
+import { join, resolve } from "path";
+
+function defaultConfigBase(platform, home, env) {
+  if (platform === "darwin") {
+    return env.XDG_CONFIG_HOME || join(home, "Library", "Application Support");
+  }
+  return env.XDG_CONFIG_HOME || join(home, ".config");
+}
+
+function defaultDataBase(platform, home, env) {
+  if (platform === "darwin") {
+    return env.XDG_DATA_HOME || join(home, "Library", "Application Support");
+  }
+  return env.XDG_DATA_HOME || join(home, ".local", "share");
+}
+
+function normalizeDir(value, fallback) {
+  const text = String(value || "").trim();
+  return resolve(text || fallback);
+}
+
+function resolveSetupPaths(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const home = options.home || env.HOME || homedir();
+  const allowAmbientStateEnv = options.allowAmbientStateEnv !== false;
+
+  const configBase = normalizeDir(
+    env.TANDEM_CONFIG_HOME,
+    defaultConfigBase(platform, home, env)
+  );
+  const dataBase = normalizeDir(env.TANDEM_DATA_HOME, defaultDataBase(platform, home, env));
+  const configDir = resolve(configBase, "tandem");
+  const dataDir = resolve(dataBase, "tandem");
+  const logsDir = resolve(dataDir, "logs");
+  const controlPanelStateDir = normalizeDir(
+    allowAmbientStateEnv ? env.TANDEM_CONTROL_PANEL_STATE_DIR : "",
+    resolve(dataDir, "control-panel")
+  );
+  const engineStateDir = normalizeDir(
+    allowAmbientStateEnv ? env.TANDEM_STATE_DIR : "",
+    resolve(dataDir, "data")
+  );
+  const envFile = normalizeDir(
+    env.TANDEM_CONTROL_PANEL_ENV_FILE,
+    resolve(configDir, "control-panel.env")
+  );
+  const tokenFile = resolve(dataDir, "security", "engine_api_token");
+
+  return {
+    home: resolve(home),
+    configBase,
+    dataBase,
+    configDir,
+    dataDir,
+    logsDir,
+    controlPanelStateDir,
+    engineStateDir,
+    envFile,
+    tokenFile,
+  };
+}
+
+export { resolveSetupPaths };

package/lib/setup/services/common.js

@@ -0,0 +1,45 @@
+import { createRequire } from "module";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+import { runCmd } from "../common.js";
+
+const require = createRequire(import.meta.url);
+
+function resolveControlPanelRoot() {
+  return resolve(join(new URL("../../", import.meta.url).pathname));
+}
+
+function resolveScriptPath(name) {
+  return resolveControlPanelRoot() + `/bin/${name}`;
+}
+
+function resolveEngineEntrypoint() {
+  return require.resolve("@frumu/tandem/bin/tandem-engine.js");
+}
+
+async function resolveUserHome(user, platform = process.platform) {
+  const name = String(user || "").trim();
+  if (!name) return "";
+  if (platform === "linux") {
+    try {
+      const out = await runCmd("getent", ["passwd", name]);
+      const row = String(out.stdout || "").trim();
+      const fields = row.split(":");
+      return fields[5] ? resolve(fields[5]) : "";
+    } catch {}
+  }
+  if (platform === "darwin") {
+    try {
+      const out = await runCmd("dscl", [".", "-read", `/Users/${name}`, "NFSHomeDirectory"]);
+      const line = String(out.stdout || "")
+        .split(/\r?\n/)
+        .find((row) => row.includes("NFSHomeDirectory:"));
+      return line ? resolve(line.split(":").slice(1).join(":").trim()) : "";
+    } catch {}
+  }
+  const guess = platform === "darwin" ? `/Users/${name}` : `/home/${name}`;
+  return existsSync(guess) ? resolve(guess) : "";
+}
+
+export { resolveControlPanelRoot, resolveEngineEntrypoint, resolveScriptPath, resolveUserHome };

package/lib/setup/services/launchd.js

@@ -0,0 +1,109 @@
+import { mkdir, writeFile } from "fs/promises";
+import { resolve } from "path";
+
+import { log, runCmd } from "../common.js";
+import { resolveScriptPath } from "./common.js";
+
+function buildLaunchdPlists(options = {}) {
+  const nodePath = options.nodePath || process.execPath;
+  const serviceRunner = resolveScriptPath("service-runner.js");
+  const envFile = options.envFile;
+  const logsDir = resolve(options.logsDir);
+  const homeDir = resolve(options.homeDir);
+  const userName = options.serviceUser;
+  const engineLabel = "ai.frumu.tandem.engine";
+  const panelLabel = "ai.frumu.tandem.control-panel";
+  const enginePath = `/Library/LaunchDaemons/${engineLabel}.plist`;
+  const panelPath = `/Library/LaunchDaemons/${panelLabel}.plist`;
+  const plistFor = (label, mode) => `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>${label}</string>
+    <key>UserName</key><string>${userName}</string>
+    <key>WorkingDirectory</key><string>${homeDir}</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${nodePath}</string>
+      <string>${serviceRunner}</string>
+      <string>${mode}</string>
+      <string>--env-file</string>
+      <string>${envFile}</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>ThrottleInterval</key><integer>5</integer>
+    <key>StandardOutPath</key><string>${logsDir}/${mode}.log</string>
+    <key>StandardErrorPath</key><string>${logsDir}/${mode}.log</string>
+  </dict>
+</plist>
+`;
+  return {
+    engineLabel,
+    panelLabel,
+    enginePath,
+    panelPath,
+    enginePlist: plistFor(engineLabel, "engine"),
+    panelPlist: plistFor(panelLabel, "panel"),
+  };
+}
+
+async function installLaunchdServices(options = {}) {
+  if (process.platform !== "darwin") {
+    throw new Error("launchd install is only supported on macOS.");
+  }
+  if (typeof process.getuid === "function" && process.getuid() !== 0) {
+    throw new Error("launchd install requires root.");
+  }
+  const plists = buildLaunchdPlists(options);
+  await mkdir(options.logsDir, { recursive: true });
+  await writeFile(plists.enginePath, plists.enginePlist, "utf8");
+  await writeFile(plists.panelPath, plists.panelPlist, "utf8");
+  await runCmd("launchctl", ["bootout", "system", plists.enginePath]).catch(() => null);
+  await runCmd("launchctl", ["bootout", "system", plists.panelPath]).catch(() => null);
+  await runCmd("launchctl", ["bootstrap", "system", plists.enginePath], { stdio: "inherit" });
+  await runCmd("launchctl", ["bootstrap", "system", plists.panelPath], { stdio: "inherit" });
+  await runCmd("launchctl", ["kickstart", "-k", `system/${plists.engineLabel}`], {
+    stdio: "inherit",
+  });
+  await runCmd("launchctl", ["kickstart", "-k", `system/${plists.panelLabel}`], {
+    stdio: "inherit",
+  });
+  log(`Installed ${plists.engineLabel} and ${plists.panelLabel}`);
+  return plists;
+}
+
+async function operateLaunchdServices(operation) {
+  const labels = ["ai.frumu.tandem.engine", "ai.frumu.tandem.control-panel"];
+  if (operation === "status") {
+    for (const label of labels) {
+      await runCmd("launchctl", ["print", `system/${label}`], { stdio: "inherit" });
+    }
+    return;
+  }
+  if (operation === "logs") {
+    throw new Error("launchd logs are file-based; inspect the configured log paths.");
+  }
+  if (operation === "uninstall") {
+    for (const label of labels) {
+      await runCmd("launchctl", ["bootout", `system/${label}`], { stdio: "inherit" }).catch(() => null);
+    }
+    return;
+  }
+  if (!["start", "stop", "restart"].includes(operation)) {
+    throw new Error(`Unsupported launchd operation: ${operation}`);
+  }
+  for (const label of labels) {
+    if (operation === "stop") {
+      await runCmd("launchctl", ["kill", "TERM", `system/${label}`], { stdio: "inherit" }).catch(
+        () => null
+      );
+      continue;
+    }
+    await runCmd("launchctl", ["kickstart", operation === "restart" ? "-k" : "", `system/${label}`].filter(Boolean), {
+      stdio: "inherit",
+    });
+  }
+}
+
+export { buildLaunchdPlists, installLaunchdServices, operateLaunchdServices };

package/lib/setup/services/systemd.js

@@ -0,0 +1,104 @@
+import { writeFile } from "fs/promises";
+
+import { log, runCmd } from "../common.js";
+import { resolveEngineEntrypoint, resolveScriptPath } from "./common.js";
+
+function buildSystemdUnits(options = {}) {
+  const nodePath = options.nodePath || process.execPath;
+  const serviceRunner = resolveScriptPath("service-runner.js");
+  const envFile = options.envFile;
+  const serviceUser = options.serviceUser;
+  const serviceGroup = options.serviceGroup || serviceUser;
+  const engineLabel = "tandem-engine";
+  const panelLabel = "tandem-control-panel";
+  const engineUnit = `[Unit]
+Description=Tandem Engine
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${serviceUser}
+Group=${serviceGroup}
+WorkingDirectory=${options.homeDir}
+ExecStart=${nodePath} ${serviceRunner} engine --env-file ${envFile}
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+  const panelUnit = `[Unit]
+Description=Tandem Control Panel
+After=network-online.target ${engineLabel}.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${serviceUser}
+Group=${serviceGroup}
+WorkingDirectory=${options.homeDir}
+ExecStart=${nodePath} ${serviceRunner} panel --env-file ${envFile}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+`;
+  return {
+    engineLabel,
+    panelLabel,
+    enginePath: `/etc/systemd/system/${engineLabel}.service`,
+    panelPath: `/etc/systemd/system/${panelLabel}.service`,
+    engineUnit,
+    panelUnit,
+    engineEntrypoint: resolveEngineEntrypoint(),
+  };
+}
+
+async function installSystemdServices(options = {}) {
+  if (process.platform !== "linux") {
+    throw new Error("systemd install is only supported on Linux.");
+  }
+  if (typeof process.getuid === "function" && process.getuid() !== 0) {
+    throw new Error("systemd install requires root.");
+  }
+  const units = buildSystemdUnits(options);
+  await writeFile(units.enginePath, units.engineUnit, "utf8");
+  await writeFile(units.panelPath, units.panelUnit, "utf8");
+  await runCmd("systemctl", ["daemon-reload"], { stdio: "inherit" });
+  await runCmd("systemctl", ["enable", "--now", `${units.engineLabel}.service`], {
+    stdio: "inherit",
+  });
+  await runCmd("systemctl", ["enable", "--now", `${units.panelLabel}.service`], {
+    stdio: "inherit",
+  });
+  log(`Installed ${units.engineLabel}.service and ${units.panelLabel}.service`);
+  return units;
+}
+
+async function operateSystemdServices(operation) {
+  const units = ["tandem-engine.service", "tandem-control-panel.service"];
+  if (operation === "logs") {
+    const args = units.flatMap((unit) => ["-u", unit]).concat(["-n", "120", "-f", "-o", "short-iso"]);
+    await runCmd("journalctl", args, { stdio: "inherit" });
+    return;
+  }
+  if (operation === "status") {
+    await runCmd("systemctl", ["--no-pager", "--full", "status", ...units], { stdio: "inherit" });
+    return;
+  }
+  if (operation === "uninstall") {
+    for (const unit of units) {
+      await runCmd("systemctl", ["disable", "--now", unit], { stdio: "inherit" }).catch(() => null);
+    }
+    return;
+  }
+  for (const unit of units) {
+    await runCmd("systemctl", [operation, unit], { stdio: "inherit" });
+  }
+}
+
+export { buildSystemdUnits, installSystemdServices, operateSystemdServices };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frumu/tandem-panel",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Full web control center for Tandem Engine (chat, routines, swarm, memory, channels, and ops)",
   "type": "module",
   "bin": {
@@ -15,12 +15,20 @@
     "test:smoke": "node --test tests/smoke.test.mjs",
     "init:env": "node bin/init-env.js",
     "doctor": "node bin/cli.js doctor",
+    "docker:up": "docker compose up --build",
+    "docker:down": "docker compose down",
+    "docker:logs": "docker compose logs -f --tail=200",
+    "docker:ps": "docker compose ps",
+    "docker:config": "docker compose config",
+    "docker:token": "node bin/docker-token.js",
     "prepublishOnly": "npm run build",
     "start": "node bin/cli.js run",
     "mcp:catalog:refresh": "node ../../scripts/generate-mcp-catalog.mjs"
   },
   "files": [
     "bin",
+    "lib",
+    "server",
     "dist",
     ".env.example",
     "README.md"
@@ -32,8 +40,8 @@
   "homepage": "https://tandem.frumu.ai",
   "author": "Frumu Ltd",
   "dependencies": {
-    "@frumu/tandem": "^0.4.8",
-    "@frumu/tandem-client": "^0.4.8",
+    "@frumu/tandem": "^0.4.11",
+    "@frumu/tandem-client": "^0.4.11",
     "@tanstack/react-query": "^5.90.21",
     "dompurify": "^3.3.1",
     "lucide": "^0.575.0",