@devmarketplacenpm/devmp 0.1.1-beta.5

package/lib/checkpoints.js

@@ -0,0 +1,292 @@
+"use strict";
+
+const fs = require("fs/promises");
+const os = require("os");
+const path = require("path");
+const { createHash, randomUUID } = require("crypto");
+const { resolveInside, isUnsafeFileTarget } = require("./workspace");
+
+const AUTH_DIR = ".devmarketplace";
+const CHECKPOINT_FILE = "cli-checkpoints.json";
+const MAX_CHECKPOINTS = 8;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_CHECKPOINT_BYTES = 12 * 1024 * 1024;
+
+function checkpointPath() {
+  return (
+    process.env.DEVMP_CLI_CHECKPOINTS ||
+    path.join(os.homedir(), AUTH_DIR, CHECKPOINT_FILE)
+  );
+}
+
+function hash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function readDocument(file) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+    return parsed?.workspaces ? parsed : { version: 1, workspaces: {} };
+  } catch {
+    return { version: 1, workspaces: {} };
+  }
+}
+
+async function writeDocument(file, document) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await fs.writeFile(temp, `${JSON.stringify(document, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.rename(temp, file);
+  await fs.chmod(file, 0o600).catch(() => undefined);
+}
+
+function normalizedPath(rootDir, relPath) {
+  const target = resolveInside(rootDir, relPath);
+  if (!target) throw new Error(`refused ${relPath} (outside workspace)`);
+  return path.relative(path.resolve(rootDir), target).split(path.sep).join("/");
+}
+
+async function snapshotFile(rootDir, relPath) {
+  const normalized = normalizedPath(rootDir, relPath);
+  const target = resolveInside(rootDir, normalized);
+  if (await isUnsafeFileTarget(rootDir, target)) {
+    throw new Error(`Cannot safely checkpoint non-regular file: ${normalized}`);
+  }
+  let stat;
+  try {
+    stat = await fs.lstat(target);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { path: normalized, exists: false, content: null, hash: null };
+    }
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Cannot safely checkpoint non-regular file: ${normalized}`);
+  }
+  if (stat.size > MAX_FILE_BYTES) {
+    throw new Error(
+      `Cannot safely checkpoint ${normalized} (${stat.size} bytes; limit ${MAX_FILE_BYTES}).`
+    );
+  }
+  const content = await fs.readFile(target, "utf8");
+  return {
+    path: normalized,
+    exists: true,
+    content,
+    hash: hash(content),
+  };
+}
+
+function sameSnapshot(a, b) {
+  return Boolean(a?.exists) === Boolean(b?.exists) && a?.hash === b?.hash;
+}
+
+async function restoreSnapshot(rootDir, snapshot) {
+  const target = resolveInside(rootDir, snapshot.path);
+  if (!target) throw new Error(`refused ${snapshot.path} (outside workspace)`);
+  if (await isUnsafeFileTarget(rootDir, target)) {
+    throw new Error(`refused ${snapshot.path} (unsafe file target)`);
+  }
+  if (!snapshot.exists) {
+    await fs.unlink(target).catch((error) => {
+      if (error?.code !== "ENOENT") throw error;
+    });
+    return;
+  }
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, snapshot.content, "utf8");
+}
+
+function deriveChanges(checkpoint) {
+  const files = checkpoint?.files || {};
+  const changed = new Map();
+  for (const [filePath, snapshots] of Object.entries(files)) {
+    const before = snapshots.before;
+    const after = snapshots.after;
+    if (!after || sameSnapshot(before, after)) continue;
+    changed.set(filePath, {
+      path: filePath,
+      kind: !before.exists ? "created" : !after.exists ? "deleted" : "modified",
+    });
+  }
+
+  for (const op of checkpoint.operations || []) {
+    if (op.kind !== "move") continue;
+    if (changed.has(op.fromPath) && changed.has(op.toPath)) {
+      changed.delete(op.fromPath);
+      changed.set(op.toPath, {
+        kind: "moved",
+        path: op.toPath,
+        fromPath: op.fromPath,
+      });
+    }
+  }
+  return [...changed.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function publicCheckpoint(checkpoint) {
+  if (!checkpoint) return null;
+  return { ...checkpoint, changes: deriveChanges(checkpoint) };
+}
+
+/**
+ * Durable, local-only per-turn pre-image checkpoints. File contents are never
+ * sent to the backend; the mode-0600 store exists solely so `/undo` survives a
+ * CLI restart. Every pre-image is persisted before the corresponding mutation.
+ */
+function createCheckpointManager({ rootDir, file = checkpointPath() }) {
+  const root = path.resolve(rootDir);
+  let activeId = null;
+
+  async function withWorkspace(mutator) {
+    const document = await readDocument(file);
+    const workspace =
+      document.workspaces[root] ||
+      (document.workspaces[root] = { checkpoints: [] });
+    const result = await mutator(workspace);
+    await writeDocument(file, document);
+    return result;
+  }
+
+  async function beginTurn({ turnId, prompt }) {
+    const id = randomUUID();
+    activeId = id;
+    await withWorkspace((workspace) => {
+      workspace.checkpoints.push({
+        id,
+        turnId,
+        prompt: String(prompt || "").slice(0, 500),
+        createdAt: new Date().toISOString(),
+        status: "active",
+        files: {},
+        operations: [],
+      });
+      workspace.checkpoints = workspace.checkpoints.slice(-MAX_CHECKPOINTS);
+    });
+    return id;
+  }
+
+  async function capture(paths) {
+    if (!activeId) throw new Error("No active turn checkpoint.");
+    const snapshots = [];
+    for (const relPath of paths)
+      snapshots.push(await snapshotFile(root, relPath));
+    await withWorkspace((workspace) => {
+      const checkpoint = workspace.checkpoints.find(
+        (item) => item.id === activeId
+      );
+      if (!checkpoint) throw new Error("The active checkpoint is unavailable.");
+      let bytes = Object.values(checkpoint.files).reduce(
+        (sum, entry) => sum + (entry.before?.content?.length || 0),
+        0
+      );
+      for (const snapshot of snapshots) {
+        if (checkpoint.files[snapshot.path]) continue;
+        bytes += snapshot.content?.length || 0;
+        if (bytes > MAX_CHECKPOINT_BYTES) {
+          throw new Error(
+            "This turn would exceed the local checkpoint safety limit; the change was not applied."
+          );
+        }
+        checkpoint.files[snapshot.path] = { before: snapshot };
+      }
+    });
+  }
+
+  async function recordMove(fromPath, toPath) {
+    if (!activeId) return;
+    const from = normalizedPath(root, fromPath);
+    const to = normalizedPath(root, toPath);
+    await withWorkspace((workspace) => {
+      const checkpoint = workspace.checkpoints.find(
+        (item) => item.id === activeId
+      );
+      if (checkpoint)
+        checkpoint.operations.push({
+          kind: "move",
+          fromPath: from,
+          toPath: to,
+        });
+    });
+  }
+
+  async function finishTurn(status = "completed") {
+    if (!activeId) return null;
+    const id = activeId;
+    activeId = null;
+    const document = await readDocument(file);
+    const workspace = document.workspaces[root];
+    const checkpoint = workspace?.checkpoints.find((item) => item.id === id);
+    if (!checkpoint) return null;
+
+    for (const [filePath, entry] of Object.entries(checkpoint.files)) {
+      entry.after = await snapshotFile(root, filePath);
+    }
+    checkpoint.status = status;
+    checkpoint.completedAt = new Date().toISOString();
+    const changes = deriveChanges(checkpoint);
+    if (!changes.length) {
+      workspace.checkpoints = workspace.checkpoints.filter(
+        (item) => item.id !== id
+      );
+      await writeDocument(file, document);
+      return null;
+    }
+    await writeDocument(file, document);
+    return publicCheckpoint(checkpoint);
+  }
+
+  async function latest({ includeUndone = true } = {}) {
+    const document = await readDocument(file);
+    const checkpoints = document.workspaces[root]?.checkpoints || [];
+    const checkpoint = [...checkpoints]
+      .reverse()
+      .find((item) => includeUndone || !item.undoneAt);
+    return publicCheckpoint(checkpoint);
+  }
+
+  async function undoLatest() {
+    const document = await readDocument(file);
+    const workspace = document.workspaces[root];
+    const checkpoint = [...(workspace?.checkpoints || [])]
+      .reverse()
+      .find((item) => !item.undoneAt && Object.keys(item.files || {}).length);
+    if (!checkpoint) return { ok: false, reason: "empty", conflicts: [] };
+
+    const conflicts = [];
+    for (const [filePath, entry] of Object.entries(checkpoint.files)) {
+      const current = await snapshotFile(root, filePath);
+      if (entry.after && !sameSnapshot(current, entry.after))
+        conflicts.push(filePath);
+    }
+    if (conflicts.length) return { ok: false, reason: "conflict", conflicts };
+
+    for (const entry of Object.values(checkpoint.files).reverse()) {
+      await restoreSnapshot(root, entry.before);
+    }
+    checkpoint.undoneAt = new Date().toISOString();
+    checkpoint.status = "undone";
+    await writeDocument(file, document);
+    return { ok: true, checkpoint: publicCheckpoint(checkpoint) };
+  }
+
+  return {
+    beginTurn,
+    capture,
+    finishTurn,
+    latest,
+    recordMove,
+    undoLatest,
+  };
+}
+
+module.exports = {
+  checkpointPath,
+  createCheckpointManager,
+  deriveChanges,
+  snapshotFile,
+};

package/lib/command-runner.js

@@ -0,0 +1,368 @@
+"use strict";
+
+const { spawn } = require("child_process");
+const { randomUUID } = require("crypto");
+const { color } = require("./ui");
+const { isInteractive, confirmCommand } = require("./prompt");
+
+/** Kill a foreground command that runs longer than this (ms). Background jobs
+ * are exempt — not terminating is the entire point of starting one. */
+const COMMAND_TIMEOUT_MS = 120000;
+/** Cap captured output so a chatty command can't blow up memory / the socket. */
+const MAX_CAPTURE = 200000;
+/** Per-job rolling buffer between checks; a dev server logs forever. */
+const MAX_JOB_BUFFER = 60000;
+/** Grace period between SIGTERM and SIGKILL. */
+const KILL_GRACE_MS = 2000;
+
+/**
+ * Runs shell commands the server agent asks for, on THIS machine, under the same
+ * consent model as file overwrites (M1): a pre-approved run (`--allow-commands`),
+ * an interactive "yes"/"all", or a refusal. The safe default when we can't ask
+ * (non-interactive, no flag) is to refuse — the agent is never allowed to run
+ * arbitrary commands unattended.
+ *
+ * `handle(command)` resolves to the payload the server expects back:
+ *   { refused: true }                                   — user declined
+ *   { exitCode, stdout, stderr, timedOut }              — command ran
+ * Output is streamed to this terminal live AND captured (capped) for the agent.
+ */
+function createCommandRunner({ rootDir, allowCommands, onNotice }) {
+  const interactive = isInteractive();
+  let allowAll = allowCommands === true;
+  const allowedExact = new Set();
+  const active = new Map();
+  // Background jobs are session-scoped, not turn-scoped: the whole point is to
+  // start a server in one turn and probe it in the next.
+  const jobs = new Map();
+  let turnReport = [];
+
+  const notice = (text) => {
+    if (onNotice) onNotice(text);
+    else console.log(text);
+  };
+
+  async function mayRun(command) {
+    if (allowAll) return true;
+    if (allowedExact.has(command)) return true;
+    if (!interactive) return false; // safe default: never run unattended
+    const choice = await confirmCommand(command);
+    if (choice === "all") allowAll = true;
+    if (choice === "exact") allowedExact.add(command);
+    return choice !== "no";
+  }
+
+  function spawnCommand(command, requestId) {
+    return new Promise((resolve) => {
+      notice(color.dim(`  $ ${command}`));
+      const child = spawn(command, {
+        cwd: rootDir,
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        // Own process group: killing `sh` alone would leave whatever it
+        // started running. See terminate().
+        detached: process.platform !== "win32",
+      });
+      if (requestId !== undefined) active.set(requestId, child);
+
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      // Echo by whole lines. Chunks arrive at arbitrary boundaries, and the
+      // interactive screen owns the terminal by the row — handing it a partial
+      // line would desync its accounting against what the terminal displays.
+      let pendingLine = "";
+      const echoLines = (text) => {
+        pendingLine += text;
+        let index = pendingLine.indexOf("\n");
+        while (index !== -1) {
+          notice(color.dim(`  │ ${pendingLine.slice(0, index)}`));
+          pendingLine = pendingLine.slice(index + 1);
+          index = pendingLine.indexOf("\n");
+        }
+      };
+      const capture = (buf, which) => {
+        const text = buf.toString();
+        echoLines(text);
+        if (which === "out") {
+          if (stdout.length < MAX_CAPTURE) stdout += text;
+        } else if (stderr.length < MAX_CAPTURE) {
+          stderr += text;
+        }
+      };
+      child.stdout.on("data", (b) => capture(b, "out"));
+      child.stderr.on("data", (b) => capture(b, "err"));
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        // Escalate if it ignores SIGTERM.
+        setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS).unref();
+      }, COMMAND_TIMEOUT_MS);
+
+      const finish = (exitCode) => {
+        clearTimeout(timer);
+        if (pendingLine) {
+          notice(color.dim(`  │ ${pendingLine}`));
+          pendingLine = "";
+        }
+        if (requestId !== undefined) active.delete(requestId);
+        resolve({
+          exitCode: typeof exitCode === "number" ? exitCode : null,
+          stdout: stdout.slice(0, MAX_CAPTURE),
+          stderr: stderr.slice(0, MAX_CAPTURE),
+          timedOut,
+        });
+      };
+      child.on("close", (code) => finish(code));
+      child.on("error", (err) => {
+        stderr += `\n${err.message}`;
+        finish(null);
+      });
+    });
+  }
+
+  async function handle(command, requestId) {
+    if (!(await mayRun(command))) {
+      notice(color.yellow(`  ✗ skipped command: ${command}`));
+      const refused = {
+        command,
+        exitCode: null,
+        timedOut: false,
+        refused: true,
+      };
+      turnReport.push(refused);
+      return { refused: true };
+    }
+    const result = await spawnCommand(command, requestId);
+    turnReport.push({ command, ...result });
+    const tag = result.timedOut
+      ? color.yellow("timed out — use a background job for long-running processes")
+      : result.exitCode === 0
+      ? color.green("exit 0")
+      : color.red(`exit ${result.exitCode}`);
+    notice(color.dim(`  └ ${tag}`));
+    return result;
+  }
+
+  // ── background jobs ──────────────────────────────────────────────────────
+
+  /**
+   * Signal the child's whole process group. Commands run under `sh -c`, so
+   * signalling the child alone hits the shell and orphans everything it
+   * started — the `npm run dev` that keeps holding port 3000 after you quit.
+   */
+  function signalTree(child, signal) {
+    if (!child?.pid) return false;
+    try {
+      if (process.platform === "win32") {
+        child.kill(signal);
+      } else {
+        process.kill(-child.pid, signal);
+      }
+      return true;
+    } catch {
+      // ESRCH: already gone. Fall back to the direct signal in case the group
+      // was never created (spawn failed before setsid).
+      try {
+        child.kill(signal);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  function terminate(child) {
+    signalTree(child, "SIGTERM");
+    setTimeout(() => {
+      if (!child.killed) signalTree(child, "SIGKILL");
+    }, KILL_GRACE_MS).unref();
+  }
+
+  /**
+   * Start a long-running process and return immediately. Output is buffered
+   * rather than echoed: a dev server would otherwise flood the transcript the
+   * user is trying to read. `check` drains the buffer, so each call returns
+   * only what is new.
+   */
+  async function handleStart(command) {
+    if (!(await mayRun(command))) {
+      notice(color.yellow(`  ✗ skipped background command: ${command}`));
+      turnReport.push({ command, exitCode: null, timedOut: false, refused: true });
+      return { refused: true, jobId: null };
+    }
+
+    const jobId = randomUUID().slice(0, 8);
+    const job = {
+      jobId,
+      command,
+      running: true,
+      exitCode: null,
+      stdout: "",
+      stderr: "",
+      truncated: false,
+    };
+
+    const child = spawn(command, {
+      cwd: rootDir,
+      shell: true,
+      // No inherited stdin: a background process must never contend with the
+      // composer for the terminal.
+      stdio: ["ignore", "pipe", "pipe"],
+      // Own process group, so `npm run dev` does not survive the shell that
+      // started it. See terminate().
+      detached: process.platform !== "win32",
+    });
+    job.child = child;
+
+    const capture = (buf, which) => {
+      const text = buf.toString();
+      const next = job[which] + text;
+      if (next.length > MAX_JOB_BUFFER) {
+        job.truncated = true;
+        job[which] = next.slice(next.length - MAX_JOB_BUFFER);
+      } else {
+        job[which] = next;
+      }
+    };
+    child.stdout.on("data", (b) => capture(b, "stdout"));
+    child.stderr.on("data", (b) => capture(b, "stderr"));
+
+    child.on("close", (code) => {
+      job.running = false;
+      job.stopping = false;
+      job.exitCode = typeof code === "number" ? code : null;
+      job.child = null;
+      notice(
+        color.dim(`  └ background ${jobId} exited (${job.exitCode ?? "killed"})`)
+      );
+    });
+    child.on("error", (err) => {
+      job.running = false;
+      job.stderr += `\n${err.message}`;
+      job.child = null;
+    });
+
+    jobs.set(jobId, job);
+    turnReport.push({ command, background: true, jobId });
+    notice(color.dim(`  $ ${command} ${color.cyan(`[background ${jobId}]`)}`));
+    return { jobId };
+  }
+
+  /** Status plus output since the previous check; the buffer is drained. */
+  function handleCheck(jobId) {
+    const job = jobs.get(jobId);
+    if (!job) return { found: false, running: false, exitCode: null, stdout: "", stderr: "" };
+    const payload = {
+      found: true,
+      running: job.running,
+      exitCode: job.exitCode,
+      stdout: job.stdout,
+      stderr: job.stderr,
+      truncated: job.truncated,
+    };
+    job.stdout = "";
+    job.stderr = "";
+    job.truncated = false;
+    return payload;
+  }
+
+  function handleStop(jobId) {
+    const job = jobs.get(jobId);
+    if (!job) return { found: false, stopped: false };
+    if (!job.running || !job.child) return { found: true, stopped: false };
+    terminate(job.child);
+    // Stays `running` until the process actually closes; the exit teardown
+    // relies on that to escalate to SIGKILL if it ignores SIGTERM.
+    job.stopping = true;
+    notice(color.dim(`  └ stopping background ${jobId}`));
+    return { found: true, stopped: true };
+  }
+
+  function handleList() {
+    return {
+      jobs: [...jobs.values()].map((job) => ({
+        jobId: job.jobId,
+        command: job.command,
+        running: job.running,
+        stopping: Boolean(job.stopping),
+        exitCode: job.exitCode,
+      })),
+    };
+  }
+
+  /** For the shell's `/jobs` view — same data, no socket round-trip. */
+  function listJobs() {
+    return handleList().jobs;
+  }
+
+  function stopJob(jobId) {
+    return handleStop(jobId);
+  }
+
+  /**
+   * Kill every background job. Called when the session ends, so it cannot rely
+   * on terminate()'s unref'd SIGKILL timer — the process exits first and the
+   * kill never lands. This one waits out the grace period itself and returns
+   * only once nothing is left running.
+   */
+  async function killAllJobs() {
+    const live = [...jobs.values()].filter((job) => job.running && job.child);
+    if (!live.length) return [];
+    for (const job of live) signalTree(job.child, "SIGTERM");
+
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (Date.now() < deadline && live.some((job) => job.running)) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+
+    const stubborn = live.filter((job) => job.running);
+    for (const job of stubborn) signalTree(job.child, "SIGKILL");
+    for (const job of live) job.running = false;
+    return live.map((job) => job.jobId);
+  }
+
+  function cancel(requestId) {
+    const child = active.get(requestId);
+    if (!child) return false;
+    terminate(child);
+    return true;
+  }
+
+  /** Cancels foreground commands only; background jobs outlive a turn. */
+  function cancelAll() {
+    for (const requestId of active.keys()) cancel(requestId);
+  }
+
+  function setAllowCommands(value) {
+    allowAll = value === true;
+    if (!allowAll) allowedExact.clear();
+  }
+
+  function beginTurn() {
+    turnReport = [];
+  }
+
+  function getTurnReport() {
+    return turnReport.map((entry) => ({ ...entry }));
+  }
+
+  return {
+    handle,
+    handleStart,
+    handleCheck,
+    handleStop,
+    handleList,
+    listJobs,
+    stopJob,
+    killAllJobs,
+    cancel,
+    cancelAll,
+    setAllowCommands,
+    beginTurn,
+    getTurnReport,
+  };
+}
+
+module.exports = { createCommandRunner };