nemoris 0.1.0

package/src/onboarding/doctor.js

@@ -0,0 +1,530 @@
+/**
+ * Nemoris Doctor — standalone health report command.
+ *
+ * Pure functions (checkPlatform, formatDoctorReport) are unit-tested.
+ * runDoctor orchestrates all checks and is tested in integration.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getDaemonPaths, listServeDaemonPids } from "../cli/runtime-control.js";
+
+const execFileAsync = promisify(execFile);
+
+// ── Minimum supported Node.js major version ─────────────────────────
+const MIN_NODE_MAJOR = 22;
+
+// ── Platform check ───────────────────────────────────────────────────
+
+/**
+ * Returns basic platform information.
+ * @returns {{ os: string, arch: string, nodeVersion: string, nodeOk: boolean }}
+ */
+export function checkPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.replace(/^v/, "").split(".")[0], 10);
+  const nodeOk = major >= MIN_NODE_MAJOR;
+
+  // Map os.platform() to a human-readable OS name
+  const osNames = {
+    darwin: "macOS",
+    linux: "Linux",
+    win32: "Windows",
+  };
+  const osDisplay = osNames[platform] || platform;
+
+  return {
+    os: osDisplay,
+    arch,
+    nodeVersion,
+    nodeOk,
+  };
+}
+
+// ── Dependency checks ────────────────────────────────────────────────
+
+/**
+ * Checks for required and optional CLI dependencies.
+ * @returns {Promise<Array<{ name: string, found: boolean, required: boolean, installHint: string }>>}
+ */
+export async function checkDependencies() {
+  const platform = os.platform();
+  const whichCmd = platform === "win32" ? "where" : "which";
+  const deps = [];
+
+  async function check(name, required, hint) {
+    try {
+      await execFileAsync(whichCmd, [name], { timeout: 3000 });
+      deps.push({ name, found: true, required, installHint: hint });
+    } catch {
+      deps.push({ name, found: false, required, installHint: hint });
+    }
+  }
+
+  await check("git", true, "https://git-scm.com");
+  await check("ollama", false, "https://ollama.ai");
+  await check("gh", false, "https://cli.github.com (optional)");
+
+  if (platform === "win32") {
+    await check("pm2", false, "npm install -g pm2 (https://pm2.io)");
+  }
+
+  return deps;
+}
+
+// ── Format helpers ───────────────────────────────────────────────────
+
+function _stripAnsi(str) {
+  // Strip ANSI escape codes for length calculations
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function checkIcon(ok) {
+  return ok ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
+}
+
+function warnIcon() {
+  return "\x1b[33m!\x1b[0m";
+}
+
+function bold(text) {
+  return `\x1b[1m${text}\x1b[0m`;
+}
+
+function dim(text) {
+  return `\x1b[2m${text}\x1b[0m`;
+}
+
+function formatProviderReason(status) {
+  if (status === null || status === undefined || status === "") {
+    return "";
+  }
+
+  if (typeof status === "number") {
+    return `HTTP ${status}`;
+  }
+
+  const text = String(status).trim();
+  const missingToken = text.match(/\(env:([A-Z0-9_]+)\)/);
+  if (missingToken) {
+    return `missing ${missingToken[1]}`;
+  }
+
+  return text;
+}
+
+function row(label, value, ok) {
+  const icon = ok === null ? warnIcon() : checkIcon(ok);
+  const labelPad = label.padEnd(16);
+  const valuePad = (value || "").toString().padEnd(22);
+  return `  ${labelPad}${valuePad}${icon}`;
+}
+
+// ── formatDoctorReport ───────────────────────────────────────────────
+
+/**
+ * Renders a human-readable doctor report string.
+ *
+ * @param {{
+ *   platform: { os: string, arch: string, nodeVersion: string, nodeOk: boolean },
+ *   installDir: string,
+ *   configValid: boolean,
+ *   configErrors: string[],
+ *   providers: Array<{ id: string, healthy: boolean, status?: string }>,
+ *   lanes: Array<{ id: string, ready: boolean }>,
+ *   jobs: Array<{ id: string, healthy: boolean }>,
+ *   delivery: Array<{ id: string, ready: boolean }>,
+ *   daemon?: { pids?: number[], stalePidFile?: boolean },
+ *   suggestions: string[],
+ *   exitCode?: number,
+ * }} results
+ * @returns {string}
+ */
+export function formatDoctorReport(results) {
+  const {
+    platform,
+    installDir,
+    configValid,
+    configErrors = [],
+    dependencies = [],
+    providers = [],
+    lanes = [],
+    jobs = [],
+    delivery = [],
+    mcpServers = [],
+    daemon = {},
+    suggestions = [],
+  } = results;
+
+  const lines = [];
+
+  // Header
+  const headerLine = "─".repeat(40);
+  lines.push(`\n${bold(`── Nemoris Doctor `)}${bold(headerLine.slice(19))}\n`);
+
+  // Platform section
+  const osLabel = `${platform.os} (${platform.arch})`;
+  lines.push(row("Platform", osLabel, true));
+  lines.push(row("Node.js", platform.nodeVersion, platform.nodeOk));
+
+  // Install dir — shorten to ~ if in home
+  const homeDir = os.homedir();
+  const displayDir = installDir
+    ? installDir.startsWith(homeDir)
+      ? installDir.replace(homeDir, "~")
+      : installDir
+    : "(unknown)";
+  lines.push(row("Install", displayDir, true));
+
+  const allLanesReady = lanes.every((lane) => lane.ready);
+
+  // Dependencies section
+  if (dependencies.length > 0) {
+    lines.push(`\n${bold("  Dependencies")}`);
+    for (let i = 0; i < dependencies.length; i++) {
+      const d = dependencies[i];
+      const prefix = i === dependencies.length - 1 ? "  └─" : "  ├─";
+      if (d.found) {
+        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("found")}  ${checkIcon(true)}`);
+      } else if (d.required) {
+        lines.push(`${prefix} ${d.name.padEnd(14)} \x1b[31mmissing\x1b[0m  ${checkIcon(false)}  ${dim(d.installHint)}`);
+      } else {
+        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("missing")}  \x1b[33m!\x1b[0m  ${dim(d.installHint)}`);
+      }
+    }
+  }
+
+  // Providers section
+  if (providers.length > 0) {
+    lines.push(`\n${bold("  Providers")}`);
+    for (let i = 0; i < providers.length; i++) {
+      const p = providers[i];
+      const prefix = i === providers.length - 1 ? "  └─" : "  ├─";
+      if (p.healthy) {
+        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("healthy")}  ${checkIcon(true)}`);
+      } else if (allLanesReady) {
+        const reasonText = formatProviderReason(p.status);
+        const reason = reasonText ? `  ${dim(`(${reasonText})`)}` : "";
+        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("not configured")}  —${reason}`);
+      } else {
+        const reasonText = formatProviderReason(p.status);
+        const reason = reasonText ? dim(`(${reasonText})`) : "";
+        lines.push(`${prefix} ${p.id.padEnd(14)} \x1b[31munhealthy\x1b[0m  ${checkIcon(false)}  ${reason}`);
+      }
+    }
+  }
+
+  // Config section
+  const configNote = configValid
+    ? `${configErrors.length === 0 ? "all manifests valid" : `${configErrors.length} error(s)`}`
+    : `${configErrors.length} error(s)`;
+  lines.push(`\n${row("Config", configNote, configValid)}`);
+
+  if (configErrors.length > 0) {
+    for (const err of configErrors) {
+      lines.push(`    ${dim("• " + err)}`);
+    }
+  }
+
+  // Lanes section
+  if (lanes.length > 0) {
+    lines.push(`\n${bold("  Lanes")}`);
+    for (let i = 0; i < lanes.length; i++) {
+      const l = lanes[i];
+      const prefix = i === lanes.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${l.id.padEnd(30)} ${checkIcon(l.ready)}`);
+    }
+  }
+
+  // Jobs section
+  if (jobs.length > 0) {
+    lines.push(`\n${bold("  Jobs")}`);
+    for (let i = 0; i < jobs.length; i++) {
+      const j = jobs[i];
+      const prefix = i === jobs.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${j.id.padEnd(30)} ${checkIcon(j.healthy)}`);
+    }
+  }
+
+  // Delivery section
+  if (delivery.length > 0) {
+    lines.push(`\n${bold("  Delivery")}`);
+    for (let i = 0; i < delivery.length; i++) {
+      const d = delivery[i];
+      const prefix = i === delivery.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${d.id.padEnd(30)} ${checkIcon(d.ready)}`);
+    }
+  }
+
+  // MCP Servers section
+  if (mcpServers.length > 0) {
+    lines.push(`\n${bold("  MCP Servers")}`);
+    for (let i = 0; i < mcpServers.length; i++) {
+      const s = mcpServers[i];
+      const prefix = i === mcpServers.length - 1 ? "  └─" : "  ├─";
+      if (s.alive) {
+        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("running")}  ${checkIcon(true)}`);
+      } else {
+        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("stopped")}  ${checkIcon(false)}`);
+      }
+    }
+  }
+
+  if ((daemon.pids || []).length > 1 || daemon.stalePidFile) {
+    lines.push(`\n${bold("  Daemon")}`);
+    if ((daemon.pids || []).length > 1) {
+      lines.push(`  ⚠️  Multiple daemon processes detected (pids: ${daemon.pids.join(", ")}). Run nemoris stop && nemoris start to fix.`);
+    }
+    if (daemon.stalePidFile) {
+      lines.push("  ⚠️  Stale PID file found. Daemon is not running.");
+    }
+  }
+
+  // Overall status
+  // An unhealthy provider is only critical if lanes can't resolve without it.
+  // If all lanes are ready, unhealthy providers are warnings (unused/optional).
+  const allDeliveryReady = delivery.every((d) => d.ready);
+  const allJobsHealthy = jobs.every((j) => j.healthy);
+  const allProviderHealthy = providers.every((p) => p.healthy);
+  const overallHealthy = configValid && (allProviderHealthy || allLanesReady) && allDeliveryReady && allJobsHealthy;
+
+  const suggCount = suggestions.length;
+  const suggNote = suggCount > 0 ? ` (${suggCount} suggestion${suggCount === 1 ? "" : "s"})` : "";
+  const overallLabel = overallHealthy ? bold("healthy") : bold("degraded");
+  lines.push(`\n  Overall: ${overallLabel}${suggNote}\n`);
+
+  // Suggestions
+  if (suggestions.length > 0) {
+    for (const s of suggestions) {
+      lines.push(`  \x1b[33m💡\x1b[0m ${s}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ── runDoctor ────────────────────────────────────────────────────────
+
+/**
+ * Orchestrates all health checks and returns a results object.
+ *
+ * @param {string} installDir  — path to the nemoris install root
+ * @param {{
+ *   execFileImpl?: Function,
+ *   fsImpl?: typeof import("node:fs"),
+ *   listServeDaemonPidsImpl?: Function,
+ * }} options
+ * @returns {Promise<object>}  — results suitable for formatDoctorReport + exitCode
+ */
+export async function runDoctor(
+  installDir,
+  {
+    execFileImpl = execFileAsync,
+    fsImpl = fs,
+    listServeDaemonPidsImpl = listServeDaemonPids,
+  } = {},
+) {
+  const results = {
+    platform: checkPlatform(),
+    installDir,
+    configValid: true,
+    configErrors: [],
+    dependencies: [],
+    providers: [],
+    lanes: [],
+    jobs: [],
+    delivery: [],
+    mcpServers: [],
+    daemon: {
+      pids: [],
+      stalePidFile: false,
+    },
+    suggestions: [],
+    exitCode: 0,
+  };
+
+  // ── 0. Dependency checks ──────────────────────────────────────────
+  try {
+    results.dependencies = await checkDependencies();
+  } catch {
+    // Dependency check failure is non-fatal
+  }
+
+  // ── 1. Config validation ─────────────────────────────────────────
+  try {
+    const { ConfigLoader } = await import("../config/loader.js");
+    const { validateAllConfigs } = await import("../config/schema-validator.js");
+    const configDir = `${installDir}/config`;
+    const loader = new ConfigLoader({ rootDir: configDir });
+    const config = await loader.loadAll();
+    const validation = validateAllConfigs(config, configDir);
+    results.configValid = validation.ok;
+    results.configErrors = validation.errors || [];
+    results._config = config;
+  } catch (err) {
+    // Gracefully degrade — config may not exist yet
+    results.configValid = false;
+    results.configErrors = [err.message || "Failed to load config"];
+    results._config = null;
+  }
+
+  // ── 2. Provider health ───────────────────────────────────────────
+  try {
+    const { ProviderRegistry } = await import("../providers/registry.js");
+    const config = results._config;
+    if (config?.providers) {
+      const registry = new ProviderRegistry({ fetchImpl: fetch });
+      for (const [id, providerConfig] of Object.entries(config.providers)) {
+        try {
+          const adapter = registry.create(providerConfig);
+          let healthy = true;
+          let status = null;
+          if (typeof adapter.healthCheck === "function") {
+            const h = await adapter.healthCheck();
+            healthy = Boolean(h.ok);
+            status = h.status ?? null;
+          }
+          results.providers.push({ id, healthy, status });
+        } catch (err) {
+          results.providers.push({ id, healthy: false, status: err.message });
+        }
+      }
+    }
+  } catch {
+    // Provider module unavailable — skip
+  }
+
+  // ── 3. Lane readiness ────────────────────────────────────────────
+  try {
+    const { buildLaneReadiness } = await import("../runtime/lane-readiness.js");
+    const config = results._config;
+    if (config?.router) {
+      for (const [laneId] of Object.entries(config.router)) {
+        try {
+          const readiness = buildLaneReadiness({ jobId: laneId });
+          results.lanes.push({ id: laneId, ready: readiness.ready !== false });
+        } catch {
+          results.lanes.push({ id: laneId, ready: false });
+        }
+      }
+    }
+  } catch {
+    // Lane readiness module unavailable — skip
+  }
+
+  // ── 4. Job dependency health ─────────────────────────────────────
+  try {
+    const { DependencyHealth } = await import("../runtime/dependency-health.js");
+    const config = results._config;
+    if (config?.jobs) {
+      const dh = new DependencyHealth({
+        projectRoot: installDir,
+        liveRoot: installDir,
+        fetchImpl: fetch,
+        execFileImpl,
+      });
+      for (const [jobId] of Object.entries(config.jobs)) {
+        try {
+          let healthy = true;
+          if (typeof dh.forJob === "function") {
+            const jobHealth = await dh.forJob(jobId);
+            healthy = Boolean(jobHealth?.ok !== false);
+          }
+          results.jobs.push({ id: jobId, healthy });
+        } catch {
+          results.jobs.push({ id: jobId, healthy: false });
+        }
+      }
+    }
+  } catch {
+    // Dependency health module unavailable — skip
+  }
+
+  // ── 5. Delivery channel readiness ───────────────────────────────
+  try {
+    const config = results._config;
+    if (config?.delivery?.profiles) {
+      for (const [id, profile] of Object.entries(config.delivery.profiles)) {
+        // Basic check: profile exists and has an adapter
+        const ready = Boolean(profile?.adapter);
+        results.delivery.push({ id, ready });
+      }
+    }
+  } catch {
+    // Delivery config unavailable — skip
+  }
+
+  // ── 5b. MCP server health ────────────────────────────────────────────────────
+  try {
+    const config = results._config;
+    if (config?.mcp?.servers) {
+      for (const id of Object.keys(config.mcp.servers)) {
+        // MCP servers are lazy — at doctor time they're not running.
+        // Report them as configured but stopped (informational only).
+        results.mcpServers.push({ id, alive: false });
+      }
+    }
+  } catch {
+    // MCP config unavailable — skip
+  }
+
+  // ── 5c. Daemon process health ────────────────────────────────────────────────
+  try {
+    const { pidFile } = getDaemonPaths(installDir);
+    results.daemon.pids = await listServeDaemonPidsImpl({ execFileImpl });
+    results.daemon.stalePidFile = results.daemon.pids.length === 0 && fsImpl.existsSync(pidFile);
+  } catch {
+    // Daemon process checks are best-effort only.
+  }
+
+  // ── 6. Suggestions ───────────────────────────────────────────────
+  try {
+    const config = results._config;
+    // Suggest Telegram if no delivery configured
+    if (!config?.delivery?.profiles || Object.keys(config.delivery?.profiles || {}).length === 0) {
+      results.suggestions.push("Connect Telegram for delivery: nemoris channel add telegram");
+    }
+    // Suggest enabling embeddings if no embedding config
+    if (config && !config.runtime?.embeddings?.enabled) {
+      // Only suggest if runtime loaded but embeddings not explicitly enabled
+      if (config.runtime && config.runtime.embeddings === undefined) {
+        results.suggestions.push("Enable embeddings for semantic memory search: set runtime.embeddings.enabled = true");
+      }
+    }
+  } catch {
+    // Skip suggestions on error
+  }
+
+  // ── 7. Determine exit code ───────────────────────────────────────
+  // Unhealthy providers are only critical if lanes can't resolve without them.
+  const allLanesOk = results.lanes.every((l) => l.ready);
+  const providerIssuesCritical = results.providers.some((p) => !p.healthy) && !allLanesOk;
+  const hasCritical = !results.configValid ||
+    providerIssuesCritical ||
+    results.delivery.some((d) => !d.ready);
+  const hasWarning = results.suggestions.length > 0 ||
+    results.providers.some((p) => !p.healthy) ||
+    results.jobs.some((j) => !j.healthy) ||
+    results.lanes.some((l) => !l.ready) ||
+    results.daemon.pids.length > 1 ||
+    results.daemon.stalePidFile;
+
+  if (hasCritical) {
+    results.exitCode = 2;
+  } else if (hasWarning) {
+    results.exitCode = 1;
+  } else {
+    results.exitCode = 0;
+  }
+
+  // Clean up internal fields
+  delete results._config;
+
+  return results;
+}

package/src/onboarding/lock.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const PHASES = ["detect", "choose", "build", "validate", "verify"];
+
+const LOCK_FILENAME = "nemoris.lock";
+const OLD_PHASE_NAMES = ["scaffold", "identity", "auth", "hatch"];
+
+function lockPath(installDir) {
+  return path.join(installDir, LOCK_FILENAME);
+}
+
+export function writeLock(installDir, state) {
+  fs.writeFileSync(lockPath(installDir), JSON.stringify(state, null, 2), "utf8");
+}
+
+export function readLock(installDir) {
+  const p = lockPath(installDir);
+  try {
+    const raw = fs.readFileSync(p, "utf8");
+    const parsed = JSON.parse(raw);
+    const completed = parsed.completed || [];
+    const isOldFormat = completed.some((name) => OLD_PHASE_NAMES.includes(name));
+    if (isOldFormat) {
+      console.log("  Previous partial install detected — restarting with new wizard.");
+      try { fs.unlinkSync(p); } catch {}
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function deleteLock(installDir) {
+  const p = lockPath(installDir);
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    // ignore if already gone
+  }
+}