passalong 0.6.0 → 0.9.0

package/src/passalong.js

@@ -287,6 +287,61 @@ export async function taskProgress(id, note, { cwd = process.cwd() } = {}) {
   return api.taskProgress(id, note ? { agent: a, note } : { agent: a });
 }
 
+/**
+ * What a hand-in has to carry, checked before anything is published.
+ *
+ * The server refuses the call without it anyway; the reason to check first is that publishing the
+ * write-up and then being refused leaves a guide nobody asked for behind every refused hand-in.
+ * The rule and the wording are the server's — see evidenceProblem() in apps/api/src/claims.ts.
+ */
+/**
+ * The claim generation this worktree was given when it took a guide, kept in `.passalong/held.json`
+ * beside `agent.json`. See apps/api/migrations/0029_claim_fence.sql.
+ *
+ * The agent never sees this number and is never asked for it — a model echoing an integer back
+ * three calls later is not a lock. `take` writes it, and every call that writes to the claim sends
+ * it, so a hand-in belonging to a claim that was released and re-taken is refused by the server
+ * rather than landing on somebody else's work.
+ */
+function fenceFile(cwd) {
+  return join(localDir(agent(cwd).worktree), "held.json");
+}
+
+function heldFences(cwd) {
+  try {
+    const held = JSON.parse(readFileSync(fenceFile(cwd), "utf8"));
+    return held && typeof held === "object" ? held : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The number this worktree holds for a guide, or undefined when it has none to send. */
+function fenceFor(id, cwd) {
+  const n = heldFences(cwd)[id];
+  return Number.isInteger(n) ? n : undefined;
+}
+
+function rememberFence(id, fence, cwd) {
+  if (!Number.isInteger(fence)) return;
+  const held = heldFences(cwd);
+  held[id] = fence;
+  writeFileSync(fenceFile(cwd), `${JSON.stringify(held, null, 2)}\n`);
+}
+
+/** A check a runner executed: the command it ran, and what the process returned. See checks.js. */
+const verified = (c) => Boolean(c?.cmd) && (typeof c?.exit === "number" || c?.exit === null);
+
+function requireEvidence(evidence) {
+  const said = String(evidence || "").trim();
+  if (said.length >= 16) return;
+  throw new PassalongError(
+    "send `evidence`: what you ran and what came back — the command and the lines that decided " +
+      "it, a test summary, a link to the change, or a screenshot url. " +
+      `"${said || "nothing"}" is a claim, not evidence.`,
+  );
+}
+
 /**
  * The work is done: the task moves to review with a transfer guide about it attached.
  *
@@ -296,9 +351,10 @@ export async function taskProgress(id, note, { cwd = process.cwd() } = {}) {
  */
 export async function finishTask(
   id,
-  { report, markdown, pr = "", note = "", cwd = process.cwd() } = {},
+  { report, markdown, evidence = "", pr = "", note = "", cwd = process.cwd() } = {},
 ) {
   needsSync("finishing a task");
+  requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
     report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
@@ -308,7 +364,7 @@ export async function finishTask(
     throw new PassalongError(
       "finishing needs the write-up: `markdown` for a transfer guide about the work, or `report` with the id of one",
     );
-  return api.finishTask(id, { agent: agent(cwd).agent, report, pr, note });
+  return api.finishTask(id, { agent: agent(cwd).agent, report, evidence, pr, note });
 }
 
 /**
@@ -323,6 +379,7 @@ export async function take(id, { cwd = process.cwd(), any = false } = {}) {
   const who = agent(cwd);
   const r = await api.take({ ...who, ...(id ? { id: await resolveId(id) } : {}), any });
   if (!r.guide?.markdown) return r;
+  rememberFence(r.guide.id, r.guide.fence, cwd);
   const path = join(localDir(who.worktree), `${r.guide.id}.md`);
   writeFileSync(path, r.guide.markdown);
   store.save(parse(r.guide.markdown));
@@ -332,38 +389,97 @@ export async function take(id, { cwd = process.cwd(), any = false } = {}) {
 /** Word from the agent that holds it: the lease starts again, and `note` is what the hub shows. */
 export async function progress(id, note, { cwd = process.cwd() } = {}) {
   needsSync("reporting progress");
-  return api.progress(id, { agent: agent(cwd).agent, ...(note ? { note } : {}) });
+  const fence = fenceFor(id, cwd);
+  return api.progress(id, {
+    agent: agent(cwd).agent,
+    ...(note ? { note } : {}),
+    ...(fence === undefined ? {} : { fence }),
+  });
 }
 
 /**
  * Done here. A task hands in a write-up — `markdown`, published with `parent:` naming the task, or
  * `report`, the id of one already published — for its author to review against Acceptance. Any
  * other guide hands in whether its Verification held: `ok`, and a `note` when it did not.
+ *
+ * Every hand-in carries `evidence`: what was run and what came back. The write-up and the `ok` are
+ * both the agent's word for its own work; evidence is the part the reviewer can check.
  */
 export async function handIn(
   id,
-  { ok, note = "", markdown, report, pr = "", cwd = process.cwd() } = {},
+  {
+    ok,
+    note = "",
+    evidence = "",
+    checks = [],
+    writeup = "",
+    markdown,
+    report,
+    pr = "",
+    cwd = process.cwd(),
+  } = {},
 ) {
   needsSync("handing work in");
+  // Checks are evidence, sorted against the lines they answer: bringing them is bringing it. A
+  // check whose command was actually run is exempt from the length rule — its exit code is the
+  // evidence, and `test -f dist/app.js` exiting 0 says more than any sentence about it would.
+  if (checks.length) checks.forEach((c) => (verified(c) ? null : requireEvidence(c?.ran)));
+  else requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
     report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
       .guide.meta.id;
   }
+  const fence = fenceFor(id, cwd);
   return api.handIn(id, {
     agent: agent(cwd).agent,
     note,
+    evidence,
+    ...(fence === undefined ? {} : { fence }),
+    ...(checks.length
+      ? {
+          checks: checks.map((c) => ({
+            check: c.check,
+            ran: c.ran,
+            // Only present on a check that was run. The server keeps them apart the same way.
+            ...(verified(c) ? { cmd: c.cmd, exit: c.exit, ok: c.ok } : {}),
+          })),
+        }
+      : {}),
     ...(report ? { report, pr } : {}),
+    // Left out when there is nothing to say, rather than sent as "": most hand-ins have nothing
+    // to adapt, and the field is for the ones that do.
+    ...(writeup ? { writeup } : {}),
     ...(typeof ok === "boolean" ? { ok } : {}),
   });
 }
 
+/**
+ * Give a guide or task you wrote to someone else in its team: `@handle` for one person, `#group`
+ * for the people who do a thing, or "team" (or empty) for everyone. Whoever held it and is left out
+ * has it taken back and is told; a task then only goes to the new assignee's agents. The local copy
+ * is dropped so the next read shows the new `to:`.
+ */
+export async function assign(ref, to) {
+  needsSync("reassigning");
+  const id = await resolveId(ref);
+  const target = !to || to === "team" || to === "everyone" ? "" : String(to).trim();
+  const r = await api.assign(id, target);
+  store.remove(id);
+  return r;
+}
+
 /** Not this agent's to do: what it held is open again, and `why` goes to whoever is next. */
 export async function pass(id, why, { cwd = process.cwd() } = {}) {
   needsSync("passing work");
   if (!String(why || "").trim())
     throw new PassalongError("say why you are passing it, so whoever is next knows");
-  return api.pass(id, { agent: agent(cwd).agent, why });
+  const fence = fenceFor(id, cwd);
+  return api.pass(id, {
+    agent: agent(cwd).agent,
+    why,
+    ...(fence === undefined ? {} : { fence }),
+  });
 }
 
 /**
@@ -427,9 +543,16 @@ export async function rejectTask(id, why) {
   return r;
 }
 
-export async function releaseTask(id) {
-  needsSync("releasing a task");
-  const r = await api.releaseTask(id);
+/**
+ * Take it back from whoever is holding it — a task, a handoff or a bug, and from all of them at
+ * once when several people hold the same handoff in different repos.
+ *
+ * It was tasks only, which left an asymmetry nobody chose: the author of a handoff could mark it
+ * done or give it to somebody else, and had no way to simply have it back.
+ */
+export async function release(id) {
+  needsSync("taking work back");
+  const r = await api.release(id);
   store.remove(id);
   return r;
 }
@@ -605,6 +728,39 @@ export async function followUps(meta = {}, deps = {}) {
   ].join("\n\n");
 }
 
+/**
+ * The guide a follow-up came out of, formatted to go in front of it — or "" when there is none.
+ *
+ * Follow-ups travelled one way: opening a guide handed over what was written under it, and opening
+ * one of those handed over nothing. An agent given a follow-up on its own reads a document that
+ * assumes a piece of work it has never seen, and either goes looking for it or treats the note as
+ * the whole job. Where the parent has got to is part of the context, not a separate question.
+ *
+ * The same shape the hosted server's parentOf() returns. Injectable for testing, and never worth
+ * failing the call over: the guide itself is what was asked for.
+ */
+export async function parentGuide(
+  meta = {},
+  { parent = api.parent, loggedIn = api.loggedIn } = {},
+) {
+  if (!meta.id || !meta.parent || !loggedIn()) return "";
+  try {
+    const { guide } = await parent(meta.id, { markdown: true });
+    if (!guide?.id) return "";
+    const who = guide.by?.name || (guide.by?.handle ? `@${guide.by.handle}` : "");
+    const state = guide.state === "held" && who ? `held by ${who}` : guide.state || "open";
+    return (
+      `THIS IS A FOLLOW-UP TO ${guide.id}: ${guide.title || "untitled"} — ${state}. It is more ` +
+      "context for that guide, not a piece of work on its own. Read the guide it follows first; " +
+      "it is below, and where the two disagree this follow-up is newer. If what it asks for " +
+      `depends on ${guide.id} being done and it is not, say so rather than starting.\n\n` +
+      `--- the guide it follows: ${guide.id} ---\n${String(guide.markdown ?? "").trimEnd()}\n\n`
+    );
+  } catch {
+    return "";
+  }
+}
+
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
 export async function list(query = "", { remote = true, scope = "" } = {}) {
   const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);
@@ -663,11 +819,21 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
  * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
  */
+/**
+ * Say whether a guide held, and why at the length that takes.
+ *
+ * The reason used to be one field, capped at 280 characters by the row it was written for — so an
+ * agent that had run the Verification and found it did not hold published a guide called
+ * "Correction: …" instead, because measurements, commands and commit ids do not fit in a tweet.
+ * The first line is the summary a row shows; the whole thing is what the guide shows.
+ */
 export async function verdict(id, ok, note = "") {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
-  if (!ok && !note.trim())
-    throw new PassalongError("say what went wrong: passalong failed <id> <what happened>");
-  return api.verdict(await resolveId(id), ok, note.trim());
+  const said = note.trim();
+  if (!ok && !said)
+    throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  const line = said.split("\n")[0].slice(0, 280);
+  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
 }
 
 /**
@@ -785,9 +951,12 @@ export function workPrompt(t) {
     "When every Acceptance check holds, commit what you changed as one commit whose message",
     `starts with "${t.id}: " — several tasks share this worktree, and a reviewer reads each one's`,
     "change on its own. Then call hand_in with id",
-    `${t.id}, \`pr\` set to that commit's hash, and \`markdown\`: a transfer guide saying what you`,
-    "did, what you decided and why, and how you checked each Acceptance line. If either call",
-    "says you no longer hold the task, stop.",
+    `${t.id}, \`pr\` set to that commit's hash, \`markdown\`: a transfer guide saying what you`,
+    "did, what you decided and why, and how you checked each Acceptance line, and `evidence`:",
+    "what you ran and what came back — the commands and the lines that decided it, the test",
+    "summary, the commit. Keep that as you go; at the end you would be writing it from memory,",
+    "and it is the one part of the hand-in a reviewer can check. If either call says you no",
+    "longer hold the task, stop.",
     "",
     "Nobody reads what you print: this session runs unattended. If something only a person can",
     "do stands between you and an Acceptance line — a permission, a secret, a decision — call",

package/src/update.js

@@ -0,0 +1,116 @@
+// Telling somebody their CLI is old, without ever making them wait to be told.
+//
+// The server can ship a new version of itself in an afternoon; an installed CLI changes only when
+// a person types `npm i -g passalong`. Nothing told them to, so a machine could sit on a build from
+// months ago and simply not have the tools everyone was talking about — and because the API keeps
+// answering old clients on purpose (an absent `fence` is accepted, an absent `cmd` is accepted),
+// nothing broke loudly enough to notice either.
+//
+// The registry is asked, not passalong.dev. What "the latest passalong" is, is a fact about npm,
+// and a server that answered it would be a second copy of that fact to keep in step.
+//
+// **Nothing here waits on the network.** The first attempt at this awaited the fetch after the
+// command finished, on a 1.5s timeout, and measuring it killed the design: the registry answered in
+// six to ten seconds from an ordinary connection, so every check timed out, cached nothing, and the
+// feature would have shipped dead while looking fine in review. So the line is read from a file and
+// the file is refreshed by a process nobody waits for. What a person sees is a day old at worst,
+// which is the right age for "there is a new version".
+import { readConfig, writeConfig } from "./store.js";
+
+/** How long a cached answer lasts before a refresh is worth starting. */
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * How long after a failed check before trying again. A refresh that could not reach the registry
+ * must not blind the check for a whole day — that is one bad minute costing a day of notices — and
+ * must not retry on every command either, which is what the whole-day gap is there to prevent.
+ */
+export const RETRY_AFTER_MS = 60 * 60 * 1000;
+
+/** Nobody is waiting, so this can be patient. It is generous because the registry is slow. */
+const TIMEOUT_MS = 15_000;
+
+const REGISTRY = "https://registry.npmjs.org/passalong/latest";
+
+/**
+ * Is `latest` past `current`? Compares the numeric parts and nothing else.
+ *
+ * A prerelease (`1.2.0-rc.1`) is read as its release: it only matters that the numbers moved, and
+ * nobody is being told to install a tag that `latest` does not point at anyway.
+ */
+export function isNewer(latest, current) {
+  const parts = (v) =>
+    String(v ?? "")
+      .split("-")[0]
+      .split(".")
+      .map((n) => Number.parseInt(n, 10));
+  const a = parts(latest);
+  const b = parts(current);
+  if (a.length !== 3 || b.length !== 3 || [...a, ...b].some(Number.isNaN)) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+/** The one line somebody sees, or "" when there is nothing to say. */
+export function noticeFor(latest, current) {
+  if (!isNewer(latest, current)) return "";
+  return `passalong ${latest} is out (you have ${current}) — npm i -g passalong`;
+}
+
+/**
+ * What to print and whether a refresh is due, from the file alone. No network, no waiting.
+ *
+ * `PASSALONG_NO_UPDATE_CHECK=1` turns the whole thing off, for a machine that should not be
+ * talking to the registry at all — an air-gapped box, or a CI runner where the line is noise.
+ */
+export function cachedNotice({
+  current,
+  now = Date.now(),
+  env = process.env,
+  config = readConfig,
+}) {
+  if (env.PASSALONG_NO_UPDATE_CHECK === "1") return { notice: "", stale: false };
+  const held = config();
+  const checked = Number(held.update_checked) || 0;
+  const failed = !held.update_latest;
+  const wait = failed ? RETRY_AFTER_MS : CHECK_EVERY_MS;
+  return {
+    notice: noticeFor(held.update_latest || "", current),
+    stale: now - checked >= wait,
+  };
+}
+
+/**
+ * Ask the registry and write the answer down. Run by a process nobody is waiting for.
+ *
+ * A failure still records the attempt, so the retry gap applies to it rather than every command
+ * trying again — `cachedNotice` reads an empty `update_latest` as a failure and uses the shorter
+ * gap.
+ */
+export async function refresh({ now = Date.now(), fetchImpl = fetch, save = writeConfig } = {}) {
+  let latest = "";
+  try {
+    const res = await fetchImpl(REGISTRY, {
+      // Plain JSON. The abbreviated `application/vnd.npm.install-v1+json` type is for the whole
+      // packument at `/passalong`; on `/passalong/latest` the registry answers 406, which is how
+      // the first version of this managed to fail every single time.
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (res.ok) {
+      const body = await res.json();
+      if (typeof body?.version === "string") latest = body.version;
+    }
+  } catch {
+    // Offline, blocked, rate-limited, nonsense JSON: the attempt is recorded and nothing is said.
+  }
+  try {
+    save({ update_checked: now, update_latest: latest });
+  } catch {
+    // A config that cannot be written means the next command tries again, which is harmless.
+  }
+  return latest;
+}