cortad 0.3.1-rc.9 → 0.3.2

package/lib/verbs.mjs

@@ -1,25 +1,44 @@
 import { realpathSync, statSync } from "node:fs";
 import { resolve as resolvePath, sep } from "node:path";
-import { SHOW, showText } from "./read-text.mjs";
-import { fieldConnectText, fieldText, findingsText, finished, linesOf, refusedText, restartedText, runText, STARTING, startedText, statusText, testedLine, waitingText } from "./text.mjs";
+import { machineText, SHOW, showText } from "./read-text.mjs";
+import { numbersText } from "./numbers-text.mjs";
+import { askReach } from "./auto-reach.mjs";
+import { homeOf, projectOf } from "./home.mjs";
+import { reach as reachApp } from "./reach.mjs";
+import { fieldConnectText, fieldText, findingsText, finished, linesOf, notStartedText, refusedText, restartedText, runText, STARTING, startedText, statusText, testedLine, upWaitingText, waitingText } from "./text.mjs";
 
-// The eight things a coding agent may ask of Cortad, each a call to the API with this machine's key
-// and a rendering from lib/text.mjs. The MCP tools and the `npx cortad <verb>` commands are the same
-// functions, so both faces say the same thing.
+// The ten things a coding agent may ask of Cortad, each a call to the API with this machine's key
+// and a rendering from lib/text.mjs; `reach` also sends to the app on this machine. The MCP tools
+// and the `npx cortad <verb>` commands are the same functions, so both faces say the same thing.
 //
-// Codex, Cursor CLI and Copilot CLI cut an MCP call at about 60 seconds. `run` and `verify` answer
-// within a second; `run_status` holds for up to 45 seconds on the server and 58 in all.
+// Codex, Cursor CLI and Copilot CLI cut an MCP call at about 60 seconds. `run_status` holds for up
+// to 45 seconds on the server and 58 in all. `run` and `verify` answer within a second, except while
+// the run before them has its numbers in and its job is still ending: the server holds them until it
+// has, up to the same 45 seconds.
 
 const NOT_CONNECTED = "This folder is not connected to Cortad.\nFor the person: sign in at cortad.com and run the command the connect screen shows, in this folder.";
 const HOLD_S = 45;
+// `wait`: how often it asks whether a run has started, how long the connect command may be gone
+// before no run can start, and how long it waits for one at all.
+const WAIT_POLL_MS = 10_000;
+const GONE_MS = 60_000;
+const IDLE_MS = 6 * 3600_000;
 // What the process that starts a run for an app that is still coming up allows it; lib/cli.mjs.
 export const READY_MS = 240_000;
+// The most changed files a run is scoped by; past it the run replays everything.
+const MOST_CHANGED = 2000;
 
 // `pending` keeps the run this machine asked for in ~/.cortad/<project>/pending.json: { kind,
 // startedAt, after } while the app comes up, then its jobId, or the error that ended it. `after` is
 // the latest run at the time, so a newer run on the server outranks a stale file. A run this machine
 // posted also keeps `tested`, which code it played (lib/fresh.mjs), for its run_status and findings.
-export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, root, writes = null, code = null, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+// `runner` is the record of the process holding the app up on this machine (lib/runner.mjs): the
+// app's state is read there and nowhere else. `seen` is told each run the agent has now read to its
+// end, so what was kept to tell it of that run is not said again. `wasRead` says whether the agent has read a run, and
+// `spec` is the package the agent calls back, npx -y <spec>.
+// `appLog` is the file the connect command keeps the app's output in; its path is said here, on this
+// machine, beside a failure, and never sent.
+export function makeVerbs({ api, token, runner = () => null, fetchImpl = fetch, startApp, pending, root, writes = null, appLog = null, code = null, seen = () => {}, wasRead = () => false, spec = "cortad", now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
   const call = async (method, path, body, timeoutMs = 30_000) => {
     const key = typeof token === "function" ? token() : token;
     if (!key) return { status: 0, ok: false, data: { error: NOT_CONNECTED } };
@@ -39,8 +58,17 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
     try { data = text ? JSON.parse(text) : null; } catch { data = { error: text.slice(0, 200) }; }
     return { status: res.status, ok: res.ok, data };
   };
-  const failed = (res) => ({ text: res.data?.why ?? res.data?.error ?? `Cortad answered ${res.status}.`, data: res.data, isError: true });
+  // `code` and `why` are what lib/calls.mjs counts a failure under. `why` is set only where the
+  // sentence is Cortad's own: a failure that quotes the app's output carries a code and no words.
+  const failed = (res) => {
+    const text = res.data?.why ?? res.data?.error ?? `Cortad answered ${res.status}.`;
+    const code = res.status ? `http_${res.status}` : text === NOT_CONNECTED ? "not_connected" : "unreachable";
+    return { text, data: res.data, isError: true, code, why: text };
+  };
   const iso = () => new Date(now()).toISOString();
+  const heard = (id) => { try { seen(String(id)); } catch { /* said once more by the hook */ } };
+  // Empty for an app the connect command found already running.
+  const logSaid = (failing) => (failing && appLog && sizeOf(appLog) > 0 ? `Your app's whole output from this session is in ${appLog}.` : "");
   const withTested = (d, id) => {
     const kept = pending.read();
     return kept?.tested && kept.jobId === id ? { ...d, tested: kept.tested } : d;
@@ -48,16 +76,37 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
 
   // With show, one section of the read in full, paged; a name that is not a section is the plain status.
   const status = async ({ show, page } = {}) => {
+    // What the connect command does here is this machine's to say: nothing is sent.
+    if (show === "machine") return { text: machineText(runner()?.machine ?? null).join("\n") };
     const section = SHOW.includes(show) ? show : null;
-    const res = await call("GET", `/mcp/status${section ? `?show=${section}` : ""}`);
+    // The plain status is the one read that prints the server's news, and says so; a section prints
+    // none, so it takes none.
+    // The reviews are written when the read ends: asked for by name, the answer holds for that.
+    const hold = section === "reviews" ? 45 : 0;
+    const res = await call("GET", `/mcp/status${section ? `?show=${section}&quiet=1${hold ? `&wait=${hold}` : ""}` : "?news=1"}`, undefined, hold ? (hold + 13) * 1000 : undefined);
     if (!res.ok) return failed(res);
-    return { text: section ? showText(res.data, section, page) : statusText(res.data), data: res.data };
+    // Status says a finished run itself, so the line kept to tell the agent of it is not said again.
+    if (finished(res.data?.run) && res.data.run.jobId) heard(res.data.run.jobId);
+    const here = runner();
+    const data = here ? { ...res.data, runner: here } : res.data;
+    const log = section ? "" : logSaid(appFailed(data.run) || (data.contact?.proven ?? []).some((v) => v.problems?.length));
+    const text = section ? showText(data, section, page) : statusText(data);
+    return { text: log ? withBack(text, log) : text, data };
+  };
+
+  // The files saved since the run the next one is compared with (status `baseline`), which scope a
+  // run after a change on Cortad's side. None when this machine cannot say: the run replays everything.
+  const changeOf = async (seen) => {
+    const base = (seen ?? (await call("GET", "/mcp/status?quiet=1")).data)?.baseline;
+    const files = base?.jobId ? code?.saved?.(base.startedAt) : null;
+    return files && files.length <= MOST_CHANGED ? { since: base.jobId, files } : null;
   };
 
   // Asks the server for the run and keeps its id here, so run_status finds it without one.
-  const post = async (args, kind, restarted = []) => {
+  const post = async (args, kind, restarted = [], seen = null) => {
     const tested = code?.tested() ?? null;
-    const res = await call("POST", "/mcp/run", args);
+    const change = kind === "run" ? await changeOf(seen) : null;
+    const res = await call("POST", "/mcp/run", change ? { ...args, change } : args, (HOLD_S + 13) * 1000);
     if (res.status === 202 || (res.ok && res.data?.joined)) {
       const mine = res.status === 202 ? tested : null;
       pending.write({ jobId: res.data.jobId, kind: res.data.kind ?? kind, startedAt: iso(), ...(mine ? { tested: mine } : {}) });
@@ -65,30 +114,33 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
       const said = [restarted.length ? restartedText(restarted) : "", mine?.stale ? testedLine(mine) : ""];
       return { text: startedText(res.data, kind, args.findingId, said), data: res.data };
     }
-    if (res.status === 402) return { text: refusedText(res.data), data: res.data, isError: true };
-    if (res.status === 409) return { text: `${res.data?.why ?? "The run could not start."}\nNothing ran.`, data: res.data, isError: true };
+    if (res.status === 402) return { text: refusedText(res.data), data: res.data, isError: true, code: "plan_spent" };
+    if (res.status === 409) return { text: `${res.data?.why ?? "The run could not start."}\nNothing ran.`, data: res.data, isError: true, code: "run_refused" };
     return failed(res);
   };
 
-  // An app that is up gets the run now, started again first when its code changed and nothing
-  // reloaded it; never under a run already playing, which is joined. One that is not up is started
-  // in the background, and the run is posted from there once it answers.
+  // An app the runner says is up, and the server is ready to play, gets the run now, started again
+  // first when its code changed and nothing reloaded it; never under a run already playing, which is
+  // joined. One that could not start says why and nothing is posted. Otherwise the runner is started
+  // if none holds the app, and the run is posted in the background once it can be.
   const start = async (args, kind) => {
-    const before = await call("GET", "/mcp/status");
+    const here = runner();
+    if (here?.state === "failed") return { text: notStartedText(here), data: { app: here }, isError: true, code: "app_not_started" };
+    const before = await call("GET", "/mcp/status?quiet=1");
     if (!before.ok) return failed(before);
-    if (before.data.app?.state === "ready-to-test") {
+    if (here?.state === "up" && before.data.app?.state === "ready-to-test") {
       const idle = !before.data.run || finished(before.data.run);
       const got = code && idle ? await code.fresh() : {};
-      if (got.error) return { text: `${got.error}\nNothing ran.`, isError: true };
-      return post(args, kind, got.restarted);
+      if (got.error) return { text: `${got.error}\nNothing ran.`, isError: true, code: "app_not_started" };
+      return post(args, kind, got.restarted, before.data);
     }
     pending.write({ kind, startedAt: iso(), after: before.data.run?.jobId ?? null });
     const began = await startApp(args, kind);
     if (!began.ok) {
       pending.write({ kind, startedAt: iso(), error: began.why });
-      return { text: began.why, isError: true };
+      return { text: began.why, isError: true, code: "app_not_started" };
     }
-    return { text: STARTING, data: { pending: true } };
+    return { text: here?.state === "up" ? upWaitingText(here, before.data.app) : STARTING, data: { pending: true } };
   };
   const run = () => start({}, "run");
   const verify = ({ findingId, jobId } = {}) => start({ findingId, ...(jobId ? { jobId } : {}) }, "verify");
@@ -96,7 +148,7 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
   // With no id: the run this machine is still starting, held here until it has an id, or else the
   // latest run on the server.
   const resolve = async (until) => {
-    const latest = await call("GET", "/mcp/status");
+    const latest = await call("GET", "/mcp/status?quiet=1");
     if (!latest.ok) return failed(latest);
     const newest = latest.data.run?.jobId ?? null;
     let p = pending.read();
@@ -107,9 +159,9 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
       p = pending.read() ?? p;
     }
     if (p.jobId) return { id: p.jobId };
-    if (p.error) return { text: `${p.error}\nnext: status`, isError: true };
-    if (stale()) return { text: "The process starting your app for the run ended without a result.\nNothing ran.\nnext: status", isError: true };
-    return { text: waitingText(p, now(), READY_MS) };
+    if (p.error) return { text: `${p.error}\nnext: status`, isError: true, code: "app_not_started" };
+    if (stale()) return { text: "The process starting your app for the run ended without a result.\nNothing ran.\nnext: status", isError: true, code: "app_not_started" };
+    return { text: waitingText(p, now(), READY_MS, runner(), latest.data.app) };
   };
 
   const runStatus = async ({ jobId } = {}) => {
@@ -124,13 +176,48 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
     const res = await call("GET", `/mcp/run/${encodeURIComponent(id)}${hold ? `?wait=${hold}` : ""}`, undefined, (hold + 13) * 1000);
     if (!res.ok) {
       const out = failed(res);
-      return { ...out, text: `${out.text}\nnext: run_status ${id}` };
+      // Unreached is this terminal's side only: the run is on Cortad's servers and goes on without it.
+      const said = res.status === 0 ? `${out.text} The run is on Cortad's side and goes on without this call; nothing was lost or charged by it.` : out.text;
+      return { ...out, text: `${said}\nnext: run_status ${id}` };
     }
+    // A finished run's dissection is also handed over as data, for a client that reads structured results.
+    return { text: shown(res.data, id), data: res.data, ...(res.data?.dissection ? { structured: res.data.dissection } : {}) };
+  };
+
+  const shown = (d, id) => {
     // The run is over: what the app wrote into its folder during it is put back, said before the next step.
     let back = "";
-    if (writes && finished(res.data)) { try { back = writes.putBack(); } catch { back = ""; } }
-    const text = runText(withTested(res.data, id));
-    return { text: back ? withBack(text, back) : text, data: res.data };
+    if (writes && finished(d)) { try { back = writes.putBack(); } catch { back = ""; } }
+    // The id asked for and the run the answer names: a verify that played another round names its latest.
+    if (finished(d)) { heard(id); if (d?.jobId && d.jobId !== id) heard(d.jobId); }
+    return [logSaid(appFailed(d)), back].filter(Boolean).reduce(withBack, runText(withTested(d, id)));
+  };
+
+  // `npx cortad wait`: returns when the next run ends, started from the browser or by the agent, with
+  // what it found. A coding agent starts it in the background and is woken when it exits; it is a shell
+  // verb alone, since an MCP call is cut at about 60 seconds. A run playing when it starts is that run,
+  // and so is a finished one the agent has not read: a first run can end before the agent starts this.
+  const wait = async () => {
+    if (!(typeof token === "function" ? token() : token)) return { text: NOT_CONNECTED, isError: true, code: "not_connected", why: NOT_CONNECTED };
+    const began = now();
+    let id = null;
+    let goneAt = null;
+    for (;;) {
+      if (runner()) goneAt = null;
+      else if (now() - (goneAt ??= now()) >= GONE_MS) return { text: "The connect command stopped, so no run can start from the browser.\nFor the person: run the connect command again in this folder.\nnext: status", isError: true };
+      if (now() - began >= IDLE_MS) return { text: `No run ended in 6 hours.\nnext: npx -y ${spec} wait` };
+      const res = id ? await call("GET", `/mcp/run/${encodeURIComponent(id)}?wait=${HOLD_S}`, undefined, (HOLD_S + 13) * 1000) : await call("GET", "/mcp/status?quiet=1");
+      // A key that no longer opens this repository, or a run that is gone, does not come back by asking again.
+      if ([401, 403, 404].includes(res.status)) return failed(res);
+      if (res.ok && id && finished(res.data)) {
+        const text = shown(res.data, id).replace(/\nnext: [^\n]*$/, "");
+        return { text: `${text}\nnext: findings ${res.data.jobId ?? id}`, data: res.data };
+      }
+      const r = res.ok && !id ? res.data?.run : null;
+      if (r?.jobId && r.kind !== "verify" && (!finished(r) || !wasRead(r.jobId))) { id = r.jobId; continue; }
+      // A run being followed holds on the server; a failed call, or no run yet, is asked again later.
+      if (!id || !res.ok) await sleep(WAIT_POLL_MS);
+    }
   };
 
   // Every server page of a run's findings, so the pages the agent reads are cut by size here.
@@ -157,8 +244,15 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
     return first;
   };
 
-  const findings = async ({ jobId, page } = {}) => {
+  // With show numbers: every number the run measured, whole, paged here.
+  const findings = async ({ jobId, page, show } = {}) => {
+    if (show === "numbers") {
+      const q = new URLSearchParams({ show, ...(jobId ? { jobId } : {}) }).toString();
+      const res = await call("GET", `/mcp/findings?${q}`);
+      return res.ok ? { text: numbersText(res.data, page), data: res.data } : failed(res);
+    }
     const res = await gather(jobId);
+    if (res.ok && res.data.runId) heard(res.data.runId);
     return res.ok ? { text: findingsText(withTested(res.data, res.data.runId), page), data: res.data } : failed(res);
   };
 
@@ -167,6 +261,23 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
     return res.ok ? { text: res.data.said, data: res.data } : failed(res);
   };
 
+  // A note about Cortad itself, filed where the browser's feedback box files, for the Cortad team to read.
+  const feedback = async ({ about, kind, needed, got, tried }) => {
+    const res = await call("POST", "/mcp/feedback", { about, kind, needed, ...(got ? { got } : {}), ...(tried ? { tried } : {}) });
+    return res.ok ? { text: res.data.said, data: res.data } : failed(res);
+  };
+
+  // Cortad's test request to each endpoint not yet answered, from this machine (lib/reach.mjs). The
+  // connect command sends it, signed in where it signed a test account in; the server is asked only
+  // for the list.
+  const reach = async ({ paths } = {}) => {
+    const here = runner();
+    if (here?.state === "up" && here.reach === "ask" && root) return askReach(homeOf(projectOf(root)), paths);
+    const res = here?.state === "up" ? await call("GET", "/mcp/status?quiet=1") : null;
+    if (res && !res.ok) return failed(res);
+    return reachApp({ runner: here, contact: res?.data?.contact, paths, fetchImpl });
+  };
+
   const fieldConnect = async () => {
     const res = await call("POST", "/mcp/field/connect");
     return res.ok ? { text: fieldConnectText(res.data), data: res.data } : failed(res);
@@ -178,9 +289,10 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
   };
 
   // `status --changed`: the files Cortad cites that changed since the latest run started, with the
-  // findings at them. Empty when there is nothing to say, or nothing could be asked.
+  // findings at them. Empty when there is nothing to say, or nothing could be asked. The code review's
+  // files are those of the review shown: the read's misses, or the lines Cortad's team's review cites.
   const changed = async () => {
-    const [s, f] = await Promise.all([call("GET", "/mcp/status"), gather()]);
+    const [s, f] = await Promise.all([call("GET", "/mcp/status?quiet=1"), gather()]);
     const r = s.ok ? s.data?.run : null;
     if (!r) return { text: "" };
     const kept = pending.read();
@@ -190,18 +302,23 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
     const paths = [
       ...lines.map((l) => l.path),
       ...(read.rules?.examples ?? []).map((e) => e.path),
-      ...(read.machine?.misses ?? []).map((m) => m.path),
+      ...(read.machine?.misses ?? read.machine?.cited ?? []).map((m) => m.path),
       ...(Array.isArray(read.rules?.files) ? read.rules.files : []),
     ].filter((p) => typeof p === "string" && p);
     return { text: changedLine({ root, since, runId: r.jobId, paths, lines }) };
   };
 
   // `post` and `changed` serve lib/cli.mjs; the MCP answers only the names in TOOLS.
-  return { status, run, run_status: runStatus, findings, verify, dispute, field_connect: fieldConnect, field, post, changed };
+  return { status, reach, run, run_status: runStatus, wait, findings, verify, dispute, feedback, field_connect: fieldConnect, field, post, changed };
 }
 
+const sizeOf = (path) => { try { return statSync(path).size; } catch { return 0; } };
+
+// A run whose replies failed, or with a fault on the app's side, is one whose app output is worth reading.
+const appFailed = (run) => Boolean(run?.failedReplies?.rows?.length || run?.replies?.crashed > 0 || (run?.faults ?? []).some((f) => f.side === "theirs"));
+
 // Only paths inside the repository are looked at; a path from the server never reaches outside it.
-// The put-back line sits above the next step, never after it.
+// A line said after a result sits above the next step, never after it.
 const withBack = (text, back) => {
   const lines = text.split("\n");
   const at = lines.findIndex((l) => l.startsWith("next:"));