@n-dx/core 0.1.0

package/refresh-plan.js

@@ -0,0 +1,79 @@
+const ALLOWED_REFRESH_FLAGS = new Set(["--ui-only", "--data-only", "--pr-markdown", "--no-build", "--quiet", "-q"]);
+
+export class RefreshPlanError extends Error {
+  constructor(message, suggestion) {
+    super(message);
+    this.name = "RefreshPlanError";
+    this.suggestion = suggestion;
+  }
+}
+
+/**
+ * Translate refresh flags into an explicit, validated execution plan.
+ */
+export function buildRefreshPlan(flags) {
+  const unknownFlags = flags.filter((f) => !ALLOWED_REFRESH_FLAGS.has(f));
+  if (unknownFlags.length > 0) {
+    throw new RefreshPlanError(
+      `Unknown option(s) for refresh: ${unknownFlags.join(", ")}`,
+      "Run 'ndx refresh --help' to see supported options.",
+    );
+  }
+
+  const uiOnly = flags.includes("--ui-only");
+  const dataOnly = flags.includes("--data-only");
+  const prMarkdown = flags.includes("--pr-markdown");
+  const noBuild = flags.includes("--no-build");
+  const quietFlags = flags.filter((f) => f === "--quiet" || f === "-q");
+
+  if (uiOnly && dataOnly) {
+    throw new RefreshPlanError(
+      "--ui-only and --data-only cannot be used together.",
+      "Choose one scope flag, or omit both to run the full refresh.",
+    );
+  }
+  if (uiOnly && prMarkdown) {
+    throw new RefreshPlanError(
+      "--ui-only cannot be combined with --pr-markdown.",
+      "Use --pr-markdown by itself to refresh PR markdown.",
+    );
+  }
+
+  const steps = [];
+  const skippedSteps = [];
+  const notes = [];
+  let needsSourcevisionDir = false;
+
+  if (prMarkdown) {
+    needsSourcevisionDir = true;
+    steps.push({ kind: "sourcevision-pr-markdown" });
+    skippedSteps.push({ kind: "sourcevision-analyze", reason: "--pr-markdown" });
+    skippedSteps.push({ kind: "sourcevision-dashboard-artifacts", reason: "--pr-markdown" });
+    skippedSteps.push({ kind: "web-build", reason: "--pr-markdown" });
+    notes.push("Refresh plan: running PR markdown refresh only; skipping data analysis and UI build.");
+    return { steps, skippedSteps, quietFlags, notes, needsSourcevisionDir };
+  }
+
+  if (!uiOnly) {
+    steps.push({ kind: "sourcevision-analyze" });
+    steps.push({ kind: "sourcevision-dashboard-artifacts" });
+  } else {
+    skippedSteps.push({ kind: "sourcevision-analyze", reason: "--ui-only" });
+    skippedSteps.push({ kind: "sourcevision-dashboard-artifacts", reason: "--ui-only" });
+    notes.push("Refresh plan: skipping SourceVision data refresh because --ui-only was set.");
+  }
+
+  if (dataOnly) {
+    skippedSteps.push({ kind: "web-build", reason: "--data-only" });
+    notes.push(
+      "Refresh plan: skipping UI build because --data-only was set; no implementation constraints require a UI build.",
+    );
+  } else if (noBuild) {
+    skippedSteps.push({ kind: "web-build", reason: "--no-build" });
+    notes.push("Refresh plan: skipping UI build because --no-build was set.");
+  } else {
+    steps.push({ kind: "web-build" });
+  }
+
+  return { steps, skippedSteps, quietFlags, notes, needsSourcevisionDir };
+}

package/refresh-validate.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, resolve } from "path";
+
+/**
+ * Sourcevision output files captured before a refresh for potential rollback.
+ * These are the files written by the sourcevision-analyze and
+ * sourcevision-dashboard-artifacts steps.
+ */
+const SOURCEVISION_SNAPSHOT_FILES = [
+  "manifest.json",
+  "CONTEXT.md",
+  "inventory.json",
+  "imports.json",
+  "zones.json",
+  "components.json",
+  "callgraph.json",
+  "dashboard-artifacts.json",
+];
+
+/**
+ * Key output files to verify after each step kind completes successfully.
+ * An empty array means no post-step file validation is performed for that step.
+ */
+const STEP_OUTPUT_FILES = {
+  "sourcevision-analyze": ["manifest.json"],
+  "sourcevision-dashboard-artifacts": ["dashboard-artifacts.json"],
+  "sourcevision-pr-markdown": [],
+  "web-build": [],
+};
+
+/**
+ * Capture the current contents of sourcevision output files so they can be
+ * restored if a subsequent refresh step fails.
+ *
+ * Only files in the `.sourcevision/` directory are snapshotted; `web-build`
+ * output is not included because build artifact restoration is unreliable and
+ * a failed build does not leave the previous build in a worse state.
+ *
+ * @param {string} dir   Project directory (absolute or relative)
+ * @param {object} plan  Refresh plan returned by buildRefreshPlan
+ * @returns {Promise<{absDir: string, svDir: string, files: object, capturedAt: number, fileCount: number}>}
+ */
+export async function snapshotRefreshState(dir, plan) {
+  const absDir = resolve(dir);
+  const svDir = join(absDir, ".sourcevision");
+
+  const stepsToRun = new Set((plan.steps ?? []).map((s) => s.kind));
+  const shouldSnapshot =
+    stepsToRun.has("sourcevision-analyze") ||
+    stepsToRun.has("sourcevision-dashboard-artifacts") ||
+    stepsToRun.has("sourcevision-pr-markdown");
+
+  const files = {};
+
+  if (shouldSnapshot && existsSync(svDir)) {
+    for (const name of SOURCEVISION_SNAPSHOT_FILES) {
+      const filePath = join(svDir, name);
+      if (existsSync(filePath)) {
+        try {
+          // Store as Buffer so binary-safe restoration is possible
+          files[name] = readFileSync(filePath);
+        } catch {
+          // best-effort: skip files that cannot be read
+        }
+      }
+    }
+  }
+
+  return {
+    absDir,
+    svDir,
+    files,
+    capturedAt: Date.now(),
+    fileCount: Object.keys(files).length,
+  };
+}
+
+/**
+ * Validate that the expected output files for a single step exist and contain
+ * parseable content. Called after each step reports success as a belt-and-
+ * suspenders check that the CLI actually produced its outputs.
+ *
+ * @param {string} stepKind  Step kind identifier (e.g. "sourcevision-analyze")
+ * @param {string} dir       Project directory
+ * @returns {{ valid: boolean, issues: string[] }}
+ */
+export function validateRefreshStep(stepKind, dir) {
+  const absDir = resolve(dir);
+  const svDir = join(absDir, ".sourcevision");
+  const outputFiles = STEP_OUTPUT_FILES[stepKind] ?? [];
+  const issues = [];
+
+  for (const name of outputFiles) {
+    const filePath = join(svDir, name);
+    if (!existsSync(filePath)) {
+      issues.push(`missing expected output: .sourcevision/${name}`);
+      continue;
+    }
+    // Validate JSON files can be parsed — a corrupt JSON file means the step
+    // produced an incomplete result even though it exited with code 0.
+    if (name.endsWith(".json")) {
+      try {
+        JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        issues.push(`.sourcevision/${name} exists but contains invalid JSON`);
+      }
+    }
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * Validate that all planned steps produced their expected outputs.
+ * Called after every step reports success, before the operation is marked
+ * complete, to confirm that the refresh fully succeeded.
+ *
+ * @param {string} dir   Project directory
+ * @param {object} plan  Refresh plan (contains `steps` array)
+ * @returns {{ valid: boolean, issues: string[] }}
+ */
+export function validateRefreshCompletion(dir, plan) {
+  const allIssues = [];
+
+  for (const step of plan.steps ?? []) {
+    const { issues } = validateRefreshStep(step.kind, dir);
+    for (const issue of issues) {
+      allIssues.push(`[${step.kind}] ${issue}`);
+    }
+  }
+
+  return { valid: allIssues.length === 0, issues: allIssues };
+}
+
+/**
+ * Restore sourcevision files from a pre-refresh snapshot.
+ * Called when a refresh step fails or completion validation fails, to return
+ * the project to a consistent state.
+ *
+ * @param {object} snapshot  Snapshot returned by snapshotRefreshState
+ * @returns {Promise<{restored: number, failed: number, errors: string[]}>}
+ */
+export async function rollbackRefreshState(snapshot) {
+  if (!snapshot || Object.keys(snapshot.files).length === 0) {
+    return { restored: 0, failed: 0, errors: [] };
+  }
+
+  const errors = [];
+  let restored = 0;
+  let failed = 0;
+
+  try {
+    mkdirSync(snapshot.svDir, { recursive: true });
+  } catch (err) {
+    const count = Object.keys(snapshot.files).length;
+    return {
+      restored: 0,
+      failed: count,
+      errors: [`Cannot recreate .sourcevision directory: ${err.message}`],
+    };
+  }
+
+  for (const [name, content] of Object.entries(snapshot.files)) {
+    const filePath = join(snapshot.svDir, name);
+    try {
+      writeFileSync(filePath, content);
+      restored++;
+    } catch (err) {
+      errors.push(`Failed to restore ${name}: ${err.message}`);
+      failed++;
+    }
+  }
+
+  return { restored, failed, errors };
+}

package/web.js

@@ -0,0 +1,458 @@
+/**
+ * Server orchestration for n-dx.
+ *
+ * Starts the unified server (@n-dx/web serve) with support for:
+ *   - Configurable port (--port, config, default 3117)
+ *   - Background/daemon mode (--background)
+ *   - PID file management (.n-dx-web.pid)
+ *   - Graceful stop (ndx start stop / ndx web stop)
+ *
+ * Used by both `ndx start` (unified: dashboard + MCP) and `ndx web` (alias).
+ *
+ * Usage:
+ *   ndx start [dir]                  Start server (dashboard + MCP) in foreground
+ *   ndx start --port=4000 [dir]      Start on custom port
+ *   ndx start --background [dir]     Start detached (daemon mode)
+ *   ndx start stop [dir]             Stop a background server
+ *   ndx start status [dir]           Check if server is running
+ */
+
+import { spawn } from "child_process";
+import { createConnection } from "net";
+import { readFile, writeFile, unlink, access } from "fs/promises";
+import { join, resolve } from "path";
+
+const DEFAULT_PORT = 3117;
+const PID_FILE = ".n-dx-web.pid";
+const PORT_FILE = ".n-dx-web.port";
+
+// ── Output helpers ───────────────────────────────────────────────────────────
+// Orchestration files avoid importing from packages (they spawn CLIs instead).
+// These local helpers mirror @n-dx/llm-client's output.ts for consistency.
+
+/** Print informational output. Suppressed in quiet mode. */
+function log(...args) {
+  if (!_quiet) console.log(...args);
+}
+
+let _quiet = false;
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load the project .n-dx.json and return the web.port if configured.
+ */
+async function loadConfigPort(dir) {
+  const configPath = join(dir, ".n-dx.json");
+  if (!(await fileExists(configPath))) return undefined;
+  try {
+    const raw = await readFile(configPath, "utf-8");
+    const config = JSON.parse(raw);
+    const port = config?.web?.port;
+    if (typeof port === "number" && port > 0) return port;
+  } catch {
+    // ignore malformed config
+  }
+  return undefined;
+}
+
+/**
+ * Check if a port is in use by attempting a TCP connection.
+ */
+function isPortInUse(port) {
+  return new Promise((res) => {
+    const sock = createConnection({ port, host: "127.0.0.1" });
+    sock.once("connect", () => {
+      sock.destroy();
+      res(true);
+    });
+    sock.once("error", () => {
+      res(false);
+    });
+  });
+}
+
+/**
+ * Read the port file written by the server process.
+ * Returns the actual port number or null.
+ */
+async function readPortFile(dir) {
+  const portPath = join(dir, PORT_FILE);
+  if (!(await fileExists(portPath))) return null;
+  try {
+    const raw = await readFile(portPath, "utf-8");
+    const port = parseInt(raw.trim(), 10);
+    return isNaN(port) ? null : port;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the port file.
+ */
+export async function removePortFile(dir) {
+  const portPath = join(dir, PORT_FILE);
+  try {
+    await unlink(portPath);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Wait for the server process to write its port file, polling at intervals.
+ * Returns the actual port or null if the timeout expires.
+ */
+async function waitForPortFile(dir, timeoutMs = 5000, intervalMs = 100) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const port = await readPortFile(dir);
+    if (port !== null) return port;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return null;
+}
+
+/**
+ * Read the PID file for a given project directory.
+ * Returns { pid, port } or null.
+ */
+export async function readPidFile(dir) {
+  const pidPath = join(dir, PID_FILE);
+  if (!(await fileExists(pidPath))) return null;
+  try {
+    const raw = await readFile(pidPath, "utf-8");
+    const data = JSON.parse(raw);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write PID file with process info.
+ */
+async function writePidFile(dir, pid, port) {
+  const pidPath = join(dir, PID_FILE);
+  await writeFile(
+    pidPath,
+    JSON.stringify({ pid, port, startedAt: new Date().toISOString() }, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+/**
+ * Remove PID file.
+ */
+export async function removePidFile(dir) {
+  const pidPath = join(dir, PID_FILE);
+  try {
+    await unlink(pidPath);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Check if a process is still running.
+ */
+export function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Subcommands ──────────────────────────────────────────────────────────────
+
+/**
+ * Poll until a process exits or the deadline is reached.
+ *
+ * @param {number} pid          Process ID to watch.
+ * @param {number} timeoutMs    Maximum wait time in milliseconds.
+ * @param {number} [intervalMs] Polling interval. Defaults to 100 ms.
+ * @returns {Promise<boolean>}  `true` if the process exited, `false` if timeout.
+ */
+export async function waitForProcessExit(pid, timeoutMs, intervalMs = 100) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessRunning(pid)) return true;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
+/**
+ * Stop a running background server.
+ *
+ * Sends SIGTERM and waits up to `gracePeriodMs` for the server to exit
+ * cleanly.  If the server is still alive after the grace period, SIGKILL
+ * is sent as a force-kill fallback.
+ *
+ * The default grace period is intentionally short (2 s) so the CLI stop
+ * command stays responsive.  For servers that need longer, pass gracePeriodMs
+ * explicitly or set N_DX_STOP_GRACE_MS in the environment.
+ *
+ * @param {string} dir
+ * @param {string} [label]
+ * @param {number} [gracePeriodMs]  Grace period before SIGKILL. Default: 2 000 ms.
+ */
+async function stopServer(dir, label = "n-dx server", gracePeriodMs = Number(process.env.N_DX_STOP_GRACE_MS ?? 2_000)) {
+  const info = await readPidFile(dir);
+  if (!info) {
+    log("No background server found.");
+    return true;
+  }
+
+  if (!isProcessRunning(info.pid)) {
+    log("Server process is no longer running (stale PID file).");
+    await removePidFile(dir);
+    await removePortFile(dir);
+    return true;
+  }
+
+  try {
+    process.kill(info.pid, "SIGTERM");
+  } catch (err) {
+    console.error(`Failed to send SIGTERM to server (PID ${info.pid}): ${err.message}`);
+    return false;
+  }
+
+  // Wait for graceful exit
+  const exited = await waitForProcessExit(info.pid, gracePeriodMs);
+
+  if (!exited) {
+    // Force-kill unresponsive server
+    log(`Server (PID ${info.pid}) did not exit within ${gracePeriodMs} ms — sending SIGKILL.`);
+    try {
+      process.kill(info.pid, "SIGKILL");
+    } catch {
+      // Process may have exited between the check and the kill — that's fine
+    }
+    // Give SIGKILL a moment to take effect
+    await waitForProcessExit(info.pid, 2_000);
+  }
+
+  log(`Stopped ${label} (PID ${info.pid}, port ${info.port}).`);
+  await removePidFile(dir);
+  await removePortFile(dir);
+  return true;
+}
+
+/**
+ * Show status of a background server.
+ */
+async function showStatus(dir, port, label = "n-dx server") {
+  const info = await readPidFile(dir);
+  if (!info) {
+    log("No background server recorded.");
+    // Still check if something is on the port
+    if (await isPortInUse(port)) {
+      log(`Note: Port ${port} is in use by another process.`);
+    }
+    return;
+  }
+
+  // The port file reflects the actual port the server bound to (may differ
+  // from the PID file's port if dynamic allocation kicked in).
+  const actualPort = (await readPortFile(dir)) ?? info.port;
+  const running = isProcessRunning(info.pid);
+  const portActive = await isPortInUse(actualPort);
+
+  if (running && portActive) {
+    log(`${label} is running (PID ${info.pid}, port ${actualPort}).`);
+    log(`  URL: http://localhost:${actualPort}`);
+    log(`  MCP (rex):          http://localhost:${actualPort}/mcp/rex`);
+    log(`  MCP (sourcevision): http://localhost:${actualPort}/mcp/sourcevision`);
+    log(`  Started: ${info.startedAt}`);
+  } else if (running) {
+    log(`Server process is running (PID ${info.pid}) but port ${actualPort} is not responding.`);
+  } else {
+    log("Server process is no longer running (stale PID file).");
+    await removePidFile(dir);
+    await removePortFile(dir);
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Run the server command (used by both `ndx start` and `ndx web`).
+ *
+ * @param {string} dir          Project directory
+ * @param {string[]} rest       Remaining CLI arguments
+ * @param {object} deps         Injected dependencies from cli.js
+ * @param {Function} deps.run   Run a tool script (foreground)
+ * @param {object} deps.tools   Tool script paths
+ * @param {string} deps.__dir   Root directory of n-dx
+ * @param {string} [deps.commandName="web"]  CLI command name for messaging ("start" or "web")
+ */
+export async function runWeb(dir, rest, { run, tools, __dir, commandName = "web" }) {
+  const absDir = resolve(dir);
+
+  // Parse flags and detect subcommand
+  const flags = {};
+  let subcommand = null;
+
+  for (const arg of rest) {
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        flags[arg.slice(2)] = true;
+      }
+    } else if (arg === "-q") {
+      flags.quiet = true;
+    } else if (!arg.startsWith("-") && arg !== dir) {
+      // Non-flag, non-dir arg is a subcommand
+      if (!subcommand) subcommand = arg;
+    }
+  }
+
+  _quiet = !!(flags.quiet);
+
+  // Resolve port: --port flag > .n-dx.json config > default
+  let port = DEFAULT_PORT;
+  if (flags.port) {
+    const parsed = parseInt(flags.port, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+      console.error(`Invalid port: ${flags.port}`);
+      process.exit(1);
+    }
+    port = parsed;
+  } else {
+    const configPort = await loadConfigPort(absDir);
+    if (configPort) port = configPort;
+  }
+
+  const isBackground = flags.background || flags.daemon || flags.bg;
+
+  // Labels for user-facing messages
+  const label = commandName === "start" ? "n-dx server" : "n-dx dashboard";
+  const stopCmd = `ndx ${commandName} stop`;
+
+  // --- Subcommand: stop ---
+  if (subcommand === "stop") {
+    const ok = await stopServer(absDir, label);
+    return ok ? 0 : 1;
+  }
+
+  // --- Subcommand: status ---
+  if (subcommand === "status") {
+    await showStatus(absDir, port, label);
+    return 0;
+  }
+
+  if (subcommand) {
+    console.error(`Unknown ${commandName} subcommand: ${subcommand}`);
+    console.error("Available: stop, status");
+    return 1;
+  }
+
+  // --- Check for stale PID / already running ---
+  const existing = await readPidFile(absDir);
+  if (existing && isProcessRunning(existing.pid)) {
+    console.error(`${label} is already running (PID ${existing.pid}, port ${existing.port}).`);
+    console.error(`  URL: http://localhost:${existing.port}`);
+    console.error(`Use '${stopCmd}' to stop it first.`);
+    return 1;
+  } else if (existing) {
+    // Stale PID file — clean up
+    await removePidFile(absDir);
+    await removePortFile(absDir);
+  }
+
+  // Note: Port availability is checked inside the server process itself,
+  // which will automatically fall back to the next available port in the
+  // range 3117–3200 if the configured port is already in use.
+
+  // --- Build serve args ---
+  const serveArgs = ["serve", `--port=${port}`, absDir];
+
+  // --- Background mode ---
+  if (isBackground) {
+    // Remove stale port file before spawning so we can detect the fresh one
+    await removePortFile(absDir);
+
+    const script = resolve(__dir, tools.web);
+    // Strip CLAUDECODE so child processes (rex analyze, hench run) can
+    // spawn the claude CLI without the "nested session" guard blocking them.
+    const { CLAUDECODE: _cc, ...serverEnv } = process.env;
+    const child = spawn(process.execPath, [script, ...serveArgs], {
+      stdio: "ignore",
+      detached: true,
+      env: serverEnv,
+    });
+    child.unref();
+
+    // Wait for the server to write its port file with the actual bound port.
+    // This handles dynamic port allocation — the actual port may differ from
+    // the requested port if the requested port was already in use.
+    const actualPort = await waitForPortFile(absDir);
+
+    if (actualPort === null) {
+      // Server may have failed to start. Check if process is still running.
+      if (!isProcessRunning(child.pid)) {
+        console.error(`${label} failed to start. Check logs for details.`);
+        return 1;
+      }
+      // Process is alive but port file not written yet — use requested port as fallback
+      await writePidFile(absDir, child.pid, port);
+      log(`${label} started in background (PID ${child.pid}).`);
+      log(`  URL: http://localhost:${port}`);
+      log(`Use '${stopCmd}' to stop it.`);
+      return 0;
+    }
+
+    await writePidFile(absDir, child.pid, actualPort);
+
+    if (actualPort !== port) {
+      log(`Port ${port} is in use — using port ${actualPort} instead.`);
+    }
+
+    log(`${label} started in background (PID ${child.pid}).`);
+    log(`  URL: http://localhost:${actualPort}`);
+    log(`  MCP (rex):          http://localhost:${actualPort}/mcp/rex`);
+    log(`  MCP (sourcevision): http://localhost:${actualPort}/mcp/sourcevision`);
+    log("");
+    log("Claude Code MCP setup:");
+    log(`  claude mcp add --transport http rex http://localhost:${actualPort}/mcp/rex`);
+    log(`  claude mcp add --transport http sourcevision http://localhost:${actualPort}/mcp/sourcevision`);
+    log("");
+    log(`Use '${stopCmd}' to stop it.`);
+    return 0;
+  }
+
+  // --- Foreground mode ---
+  // Clean up PID and port files on exit (in case of SIGINT/SIGTERM)
+  const cleanup = () => Promise.all([
+    removePidFile(absDir).catch(() => {}),
+    removePortFile(absDir).catch(() => {}),
+  ]);
+
+  process.on("SIGINT", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  const code = await run(tools.web, serveArgs);
+  await cleanup();
+  return code;
+}