@frumu/tandem-panel 0.3.28 → 0.4.3

package/.env.example

@@ -1,7 +1,13 @@
 # Control panel bind port
 TANDEM_CONTROL_PANEL_PORT=39732
 
-# Tip: run `tandem-control-panel --init` to auto-generate this file and token.
+# Tip: run `tandem-setup init` to auto-generate this file and token.
+
+# Control panel bind host (loopback by default)
+TANDEM_CONTROL_PANEL_HOST=127.0.0.1
+
+# Optional externally reachable URL for future pairing / gateway flows
+TANDEM_CONTROL_PANEL_PUBLIC_URL=
 
 # Full engine URL (preferred)
 TANDEM_ENGINE_URL=http://127.0.0.1:39731
@@ -13,6 +19,10 @@ TANDEM_ENGINE_PORT=39731
 # Auto-start local engine if not running (1=yes, 0=no)
 TANDEM_CONTROL_PANEL_AUTO_START_ENGINE=1
 
+# Canonical state roots for official bootstrap installs
+TANDEM_STATE_DIR=
+TANDEM_CONTROL_PANEL_STATE_DIR=
+
 # Engine API token used when control panel auto-starts a local engine.
 # If unset, the panel generates one at startup and prints it in logs.
 TANDEM_CONTROL_PANEL_ENGINE_TOKEN=tk_change_me
@@ -26,6 +36,15 @@ TANDEM_PROVIDER_STREAM_IDLE_TIMEOUT_MS=90000
 TANDEM_PERMISSION_WAIT_TIMEOUT_MS=15000
 TANDEM_TOOL_EXEC_TIMEOUT_MS=45000
 TANDEM_BASH_TIMEOUT_MS=30000
+# Bug Monitor (disabled by default)
+# TANDEM_BUG_MONITOR_ENABLED=0
+# TANDEM_BUG_MONITOR_REPO=owner/repo
+# TANDEM_BUG_MONITOR_MCP_SERVER=github
+# TANDEM_BUG_MONITOR_PROVIDER_PREFERENCE=auto
+# TANDEM_BUG_MONITOR_PROVIDER_ID=openrouter
+# TANDEM_BUG_MONITOR_MODEL_ID=openai/gpt-4.1-mini
+# Optional global duplicate-signature retry limit for tool calls.
+# TANDEM_TOOL_LOOP_DUPLICATE_SIGNATURE_LIMIT=200
 
 # Optional caps when guard budgets are enabled
 # TANDEM_TOOL_BUDGET_DEFAULT=10

package/README.md

@@ -8,40 +8,47 @@ Full web control center for Tandem Engine (non-desktop entry point).
 npm i -g @frumu/tandem-panel
 ```
 
-## Run
+## Official Bootstrap
 
 ```bash
-tandem-control-panel
+tandem-setup init
 ```
 
-Alias also supported:
+This creates a canonical env file, bootstraps engine state, and installs services on Linux/macOS when run with the privileges needed for service registration.
+
+Useful follow-up commands:
 
 ```bash
-tandem-setup
+tandem-setup doctor
+tandem-setup service status
+tandem-setup service restart
+tandem-setup pair mobile
 ```
 
-Bootstrap env/token first (recommended):
+## Run Foreground
 
 ```bash
-tandem-control-panel --init
+tandem-control-panel
 ```
 
 Or:
 
 ```bash
-tandem-control-panel-init
+tandem-setup run
 ```
 
-Install Linux systemd services (engine + panel):
+## Service Management
 
 ```bash
-sudo tandem-control-panel --install-services
+tandem-setup service install
+tandem-setup service status
+tandem-setup service restart
+tandem-setup service logs
 ```
 
-Options:
+Legacy flag mode is still supported for compatibility:
 
-- `--service-mode=both|engine|panel` (default `both`)
-- `--service-user=<linux-user>` (default: `SUDO_USER`/current user)
+`tandem-control-panel --init`, `--install-services`, and `--service-op=...`
 
 ## Features
 
@@ -68,8 +75,12 @@ cp .env.example .env
 Variables:
 
 - `TANDEM_CONTROL_PANEL_PORT` (default `39732`)
+- `TANDEM_CONTROL_PANEL_HOST` (default `127.0.0.1`)
+- `TANDEM_CONTROL_PANEL_PUBLIC_URL` (optional future pairing / gateway URL)
 - `TANDEM_ENGINE_URL` (default `http://127.0.0.1:39731`)
 - `TANDEM_ENGINE_HOST` + `TANDEM_ENGINE_PORT` fallback
+- `TANDEM_STATE_DIR` (canonical engine state dir for official installs)
+- `TANDEM_CONTROL_PANEL_STATE_DIR` (control-panel state dir for official installs)
 - `TANDEM_CONTROL_PANEL_AUTO_START_ENGINE` (`1`/`0`)
 - `TANDEM_CONTROL_PANEL_ENGINE_TOKEN` (token injected when panel auto-starts engine)
 - `TANDEM_API_TOKEN` (backward-compatible alias for engine token)
@@ -117,9 +128,10 @@ Notes:
 
 ## Setup Flow
 
-1. Run `tandem-control-panel --init` to create/update `.env` and generate a token if missing.
-2. Run `tandem-control-panel`.
-3. Sign in with the printed `TANDEM_CONTROL_PANEL_ENGINE_TOKEN`.
+1. Run `tandem-setup init`.
+2. Verify with `tandem-setup doctor`.
+3. If running foreground, start `tandem-control-panel`.
+4. Sign in with the printed `TANDEM_CONTROL_PANEL_ENGINE_TOKEN`.
 
 ## Development
 
@@ -129,3 +141,20 @@ npm install
 npm run dev
 npm run build
 ```
+
+### Repo Source Workflow (No Global npm Install)
+
+If you run from this repo directly, use:
+
+```bash
+node packages/tandem-control-panel/bin/cli.js init --no-service
+node packages/tandem-control-panel/bin/cli.js run
+```
+
+Service install/ops from source:
+
+```bash
+sudo node packages/tandem-control-panel/bin/cli.js service install
+node packages/tandem-control-panel/bin/cli.js service status
+sudo node packages/tandem-control-panel/bin/cli.js service restart
+```

package/bin/cli.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { basename } from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+import { printInitSummary, initializeInstall } from "../lib/setup/bootstrap.js";
+import { printDoctor, runDoctor } from "../lib/setup/doctor.js";
+import { parseCliArgs, err } from "../lib/setup/common.js";
+import { resolveSetupPaths } from "../lib/setup/paths.js";
+import { installSystemdServices, operateSystemdServices } from "../lib/setup/services/systemd.js";
+import { installLaunchdServices, operateLaunchdServices } from "../lib/setup/services/launchd.js";
+import { resolveUserHome } from "../lib/setup/services/common.js";
+
+const argv = process.argv.slice(2);
+const cli = parseCliArgs(argv);
+const entry = basename(process.argv[1] || "tandem-setup");
+const setupLegacyPath = fileURLToPath(new URL("./setup.js", import.meta.url));
+
+function runLegacy(args = []) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [setupLegacyPath, ...args], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code || 0));
+  });
+}
+
+async function installServicesFromEnv(envFile) {
+  const paths = resolveSetupPaths();
+  const serviceUser = String(cli.value("service-user") || process.env.SUDO_USER || process.env.USER || "").trim();
+  const homeDir = (await resolveUserHome(serviceUser || process.env.USER, process.platform)) || paths.home;
+  const options = {
+    envFile,
+    homeDir,
+    logsDir: paths.logsDir,
+    serviceUser: serviceUser || process.env.USER,
+    nodePath: process.execPath,
+  };
+  if (process.platform === "linux") return installSystemdServices(options);
+  if (process.platform === "darwin") return installLaunchdServices(options);
+  throw new Error("Service install is only supported on Linux and macOS.");
+}
+
+async function operateServices(operation) {
+  if (process.platform === "linux") return operateSystemdServices(operation);
+  if (process.platform === "darwin") return operateLaunchdServices(operation);
+  throw new Error("Service operations are only supported on Linux and macOS.");
+}
+
+async function main() {
+  const first = String(argv[0] || "").trim();
+  if (!first) {
+    process.exit(await runLegacy([]));
+  }
+
+  if (first.startsWith("--")) {
+    console.warn("[Tandem Setup] Legacy flag mode is deprecated. Use `tandem-setup init|service|doctor`.");
+    process.exit(await runLegacy(argv));
+  }
+
+  if (first === "run") {
+    process.exit(await runLegacy(argv.slice(1)));
+  }
+
+  if (first === "init") {
+    const result = await initializeInstall({
+      envPath: cli.value("env-file"),
+      overwrite: cli.has("rotate-token") || cli.has("reset-token"),
+      allowAmbientStateEnv: false,
+      allowCwdEnvMerge: false,
+    });
+    if (process.platform === "linux" || process.platform === "darwin") {
+      if (!cli.has("no-service") && !cli.has("foreground")) {
+        await installServicesFromEnv(result.envPath);
+      }
+    }
+    printInitSummary(result);
+    return;
+  }
+
+  if (first === "doctor") {
+    const result = await runDoctor({
+      envFile: cli.value("env-file"),
+      allowAmbientStateEnv: false,
+      allowCwdEnvMerge: false,
+    });
+    printDoctor(result, cli.has("json"));
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  if (first === "service") {
+    const op = String(argv[1] || "").trim().toLowerCase();
+    if (!op || op === "install") {
+      const result = await initializeInstall({
+        envPath: cli.value("env-file"),
+        overwrite: false,
+        allowAmbientStateEnv: false,
+        allowCwdEnvMerge: false,
+      });
+      await installServicesFromEnv(result.envPath);
+      return;
+    }
+    await operateServices(op);
+    return;
+  }
+
+  if (first === "pair" && String(argv[1] || "").trim().toLowerCase() === "mobile") {
+    const doctor = await runDoctor({
+      envFile: cli.value("env-file"),
+      allowAmbientStateEnv: false,
+      allowCwdEnvMerge: false,
+    });
+    console.log("Mobile pairing is not implemented in this build.");
+    console.log(`Control panel: http://${doctor.panelHost}:${doctor.panelPort}`);
+    console.log(`Public URL:    ${doctor.panelPublicUrl || "(not configured)"}`);
+    console.log(`Engine URL:    ${doctor.engineUrl}`);
+    return;
+  }
+
+  if (entry === "tandem-control-panel") {
+    process.exit(await runLegacy(argv));
+  }
+
+  err(`Unknown command: ${first}`);
+  process.exit(1);
+}
+
+main().catch((error) => {
+  err(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/bin/init-env.js

@@ -1,89 +1,15 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import { resolve, join } from "path";
-import { randomBytes } from "crypto";
+import { initializeInstall, printInitSummary } from "../lib/setup/bootstrap.js";
+import { parseCliArgs } from "../lib/setup/common.js";
 
-function parseEnv(content) {
-  const out = {};
-  for (const rawLine of String(content || "").split(/\r?\n/)) {
-    const line = rawLine.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;
-}
+const cli = parseCliArgs(process.argv.slice(2));
 
-function serializeEnv(entries) {
-  return `${entries.map(([k, v]) => `${k}=${v}`).join("\n")}\n`;
-}
+const result = await initializeInstall({
+  envPath: cli.value("env-file"),
+  overwrite: cli.has("reset-token") || cli.has("rotate-token") || cli.has("overwrite"),
+  allowAmbientStateEnv: false,
+  allowCwdEnvMerge: false,
+});
 
-function ensureEnv({ cwd = process.cwd(), overwrite = false } = {}) {
-  const envPath = resolve(cwd, ".env");
-  const existed = existsSync(envPath);
-  const examplePath = resolve(cwd, ".env.example");
-  const localExamplePath = resolve(join(process.cwd(), "packages", "tandem-control-panel", ".env.example"));
-
-  const sourcePath = existsSync(examplePath) ? examplePath : localExamplePath;
-  const defaults = existsSync(sourcePath)
-    ? parseEnv(readFileSync(sourcePath, "utf8"))
-    : {
-        TANDEM_CONTROL_PANEL_PORT: "39732",
-        TANDEM_ENGINE_URL: "http://127.0.0.1:39731",
-        TANDEM_CONTROL_PANEL_AUTO_START_ENGINE: "1",
-      };
-
-  const current = existsSync(envPath) ? parseEnv(readFileSync(envPath, "utf8")) : {};
-  const merged = { ...defaults, ...current };
-
-  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")}`;
-  }
-
-  const preferredOrder = [
-    "TANDEM_CONTROL_PANEL_PORT",
-    "TANDEM_ENGINE_URL",
-    "TANDEM_ENGINE_HOST",
-    "TANDEM_ENGINE_PORT",
-    "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]);
-  }
-
-  writeFileSync(envPath, serializeEnv(ordered), "utf8");
-
-  return {
-    envPath,
-    token: merged.TANDEM_CONTROL_PANEL_ENGINE_TOKEN,
-    created: !existed,
-    engineUrl: merged.TANDEM_ENGINE_URL || `http://${merged.TANDEM_ENGINE_HOST || "127.0.0.1"}:${merged.TANDEM_ENGINE_PORT || "39731"}`,
-    panelPort: merged.TANDEM_CONTROL_PANEL_PORT || "39732",
-  };
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const overwrite = process.argv.includes("--reset-token") || process.argv.includes("--overwrite");
-  const result = ensureEnv({ overwrite });
-  console.log("[Tandem Control Panel] Environment initialized.");
-  console.log(`[Tandem Control Panel] .env:      ${result.envPath}`);
-  console.log(`[Tandem Control Panel] Engine URL: ${result.engineUrl}`);
-  console.log(`[Tandem Control Panel] Panel URL:  http://localhost:${result.panelPort}`);
-  console.log(`[Tandem Control Panel] Token:      ${result.token}`);
-}
-
-export { ensureEnv };
+printInitSummary(result);

package/bin/service-local.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SETUP_JS="$SCRIPT_DIR/setup.js"
+NODE_BIN="${NODE_BIN:-$(command -v node || true)}"
+
+if [[ -z "${NODE_BIN}" ]]; then
+  echo "node not found in PATH" >&2
+  exit 1
+fi
+
+cmd="${1:-help}"
+arg1="${2:-}"
+arg2="${3:-}"
+
+run_setup() {
+  sudo "$NODE_BIN" "$SETUP_JS" "$@"
+}
+
+case "$cmd" in
+  install-panel)
+    panel_port="${arg1:-3402}"
+    sudo TANDEM_CONTROL_PANEL_PORT="$panel_port" "$NODE_BIN" "$SETUP_JS" --install-services --service-mode=panel
+    ;;
+  install-both)
+    engine_port="${arg1:-39731}"
+    panel_port="${arg2:-3402}"
+    sudo TANDEM_ENGINE_PORT="$engine_port" TANDEM_CONTROL_PANEL_PORT="$panel_port" \
+      "$NODE_BIN" "$SETUP_JS" --install-services --service-mode=both
+    ;;
+  restart-panel)
+    run_setup --service-op=restart --service-mode=panel
+    ;;
+  restart-both)
+    run_setup --service-op=restart --service-mode=both
+    ;;
+  status-panel)
+    run_setup --service-op=status --service-mode=panel
+    ;;
+  status-both)
+    run_setup --service-op=status --service-mode=both
+    ;;
+  logs-panel)
+    run_setup --service-op=logs --service-mode=panel
+    ;;
+  logs-both)
+    run_setup --service-op=logs --service-mode=both
+    ;;
+  *)
+    cat <<'EOF'
+Usage:
+  bash packages/tandem-control-panel/bin/service-local.sh install-panel [panel_port]
+  bash packages/tandem-control-panel/bin/service-local.sh install-both [engine_port] [panel_port]
+  bash packages/tandem-control-panel/bin/service-local.sh restart-panel
+  bash packages/tandem-control-panel/bin/service-local.sh restart-both
+  bash packages/tandem-control-panel/bin/service-local.sh status-panel
+  bash packages/tandem-control-panel/bin/service-local.sh status-both
+  bash packages/tandem-control-panel/bin/service-local.sh logs-panel
+  bash packages/tandem-control-panel/bin/service-local.sh logs-both
+EOF
+    ;;
+esac

package/bin/service-runner.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+import { loadDotEnvFile, resolveEnvLoadOrder } from "../lib/setup/env.js";
+import { parseCliArgs } from "../lib/setup/common.js";
+
+const require = createRequire(import.meta.url);
+const argv = process.argv.slice(2);
+const mode = String(argv[0] || "").trim().toLowerCase();
+const cli = parseCliArgs(argv.slice(1));
+const explicitEnvFile = String(cli.value("env-file") || "").trim();
+
+for (const envPath of resolveEnvLoadOrder({ explicitEnvFile })) {
+  loadDotEnvFile(envPath);
+}
+
+async function runPanel() {
+  const runtimePath = fileURLToPath(new URL("./setup.js", import.meta.url));
+  const child = spawn(process.execPath, [runtimePath, "--env-file", explicitEnvFile].filter(Boolean), {
+    stdio: "inherit",
+    env: process.env,
+  });
+  child.on("close", (code) => process.exit(code || 0));
+}
+
+async function runEngine() {
+  const engineEntrypoint = require.resolve("@frumu/tandem/bin/tandem-engine.js");
+  const host = String(process.env.TANDEM_ENGINE_HOST || "127.0.0.1").trim();
+  const port = String(process.env.TANDEM_ENGINE_PORT || "39731").trim();
+  const child = spawn(
+    process.execPath,
+    [engineEntrypoint, "serve", "--hostname", host, "--port", port],
+    { stdio: "inherit", env: process.env }
+  );
+  child.on("close", (code) => process.exit(code || 0));
+}
+
+if (mode === "engine") {
+  runEngine();
+} else if (mode === "panel") {
+  runPanel();
+} else {
+  console.error("Usage: service-runner.js <engine|panel> [--env-file PATH]");
+  process.exit(1);
+}