passalong 0.1.0 → 0.3.0

package/src/passalong.js

@@ -1,19 +1,43 @@
-// The operations Passalong exposes. Both surfaces (bin/passalong and the MCP server) call these, so
-// anything an agent can do through MCP a human can do from the terminal and vice versa.
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+// The operations Passalong exposes. Both surfaces (bin/passalong and the MCP server) call these,
+// so anything an agent can do through MCP a human can do from the terminal and vice versa.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
-import { ID_RE, parse, STATUSES, serialize, stamp, stripPlaceholders, validate } from "./guide.js";
+import {
+  bugGuide,
+  ID_RE,
+  parse,
+  STATUSES,
+  serialize,
+  stamp,
+  stripPlaceholders,
+  validate,
+} from "./guide.js";
 import * as store from "./store.js";
 
 export class PassalongError extends Error {}
 
+/** "team" or "team/handle" → { team, to }. */
+/**
+ * Split `--to` into a team and who inside it: "team", "team/@handle", or "team/#group".
+ *
+ * Only the `@` is stripped. The `#` is load-bearing and travels into the frontmatter as written —
+ * it is the sigil the server reads to tell a person from a group, and dropping it here would turn
+ * a handoff to six people into a lookup for a teammate who does not exist.
+ */
+export function parseTarget(to) {
+  if (!to) return {};
+  const [team, who] = String(to).split("/");
+  return { team: team.trim(), to: who ? who.trim().replace(/^@/, "") : undefined };
+}
+
 /**
  * Publish a guide from markdown: fill in defaults, validate, store locally, and sync when
- * logged in. Returns { guide, path, url, synced }.
+ * logged in. `to` addresses it: "team", "team/@handle", or "team/#group". Returns
+ * { guide, path, url, synced }.
  */
-export async function share(markdown, { cwd = process.cwd() } = {}) {
+export async function share(markdown, { cwd = process.cwd(), to } = {}) {
   const c = context(cwd);
   const raw = parse(markdown);
   let guide = stamp(
@@ -23,6 +47,11 @@ export async function share(markdown, { cwd = process.cwd() } = {}) {
       source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
     },
   );
+  const target = parseTarget(to);
+  if (target.team) guide.meta.team = target.team;
+  if (target.to) guide.meta.to = target.to;
+  if (guide.meta.to && !guide.meta.team)
+    throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
   const errors = validate(guide);
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
@@ -31,14 +60,68 @@ export async function share(markdown, { cwd = process.cwd() } = {}) {
 
   let url = guide.meta.url || null;
   let synced = false;
+  let notified = false;
   if (api.loggedIn()) {
     const res = await api.publish(guide.meta.id, serialize(guide));
     url = res.url;
     synced = true;
+    notified = Boolean(res.notified);
     guide = { ...guide, meta: { ...guide.meta, url } };
+  } else if (guide.meta.team) {
+    throw new PassalongError("sharing to a team needs sync — run `passalong login` first");
   }
   const path = store.save(guide);
-  return { guide, path, url, synced };
+  return { guide, path, url, synced, notified };
+}
+
+/**
+ * File a set of bugs as one report.
+ *
+ * The report is opened first because each issue's frontmatter names it, and the issues go up one
+ * at a time — a partial failure that has filed three of five should say which three, since the
+ * three that landed are real guides someone can already act on.
+ *
+ * Unlike `share()`, this needs sync: a report is a server-side parent, and there is nothing local
+ * for a set to belong to. One bug on its own does not — that is just `share()` with a bug
+ * document, and it works offline like any other guide.
+ */
+export async function fileBugs(
+  { title = "", environment = "", issues = [] },
+  { cwd = process.cwd(), to } = {},
+) {
+  if (!issues.length) throw new PassalongError("a report needs at least one issue");
+  if (!api.loggedIn())
+    throw new PassalongError("filing a report needs sync — run `passalong login` first");
+  const target = parseTarget(to);
+  const { report } = await api.createReport({
+    title,
+    environment,
+    team: target.team || "",
+    to: target.to || "",
+  });
+
+  const filed = [];
+  try {
+    for (const issue of issues) {
+      const markdown = bugGuide({ ...issue, report: report.id, environment });
+      const { guide, url } = await share(markdown, { cwd, to });
+      filed.push({
+        id: guide.meta.id,
+        title: guide.meta.title,
+        area: guide.meta.area || "",
+        severity: guide.meta.severity || "",
+        url,
+      });
+    }
+  } catch (err) {
+    if (!filed.length) throw err;
+    throw new PassalongError(
+      `filed ${filed.length} of ${issues.length} issues (${filed
+        .map((f) => f.id)
+        .join(", ")}) before failing: ${err.message}`,
+    );
+  }
+  return { report: { id: report.id, title, environment }, issues: filed };
 }
 
 /** Resolve a reference (id, share URL, or local file path) to a guide. */
@@ -48,7 +131,6 @@ export async function resolve(ref) {
     return { guide: parse(md), from: "link" };
   }
   if (ref.endsWith(".md") && existsSync(ref)) {
-    const { readFileSync } = await import("node:fs");
     return { guide: parse(readFileSync(ref, "utf8")), from: "file" };
   }
   if (!ID_RE.test(ref))
@@ -71,36 +153,157 @@ export async function resolve(ref) {
 }
 
 /**
- * Pull a guide into a working directory: writes .passalong/<id>.md there and returns the guide so
- * the caller can put the text straight into an agent's context.
+ * Resolve a reference to its id alone, without fetching the guide.
+ *
+ * The reader's two answers — an ack and a verdict — are writes that take an id and nothing else,
+ * so the guide body they used to fetch on the way was never read. That fetch was not free:
+ * `GET /v1/guides/:id` records a pull, which is how somebody saying "not me" on a handoff
+ * registered as taking delivery of it — inflating the guide's pull count and moving it into the
+ * sender's "landed" queue. An id needs no lookup at all, and a link or a file carries the id in
+ * its own frontmatter.
+ *
+ * Unlike `resolve()`, a bare id is not checked for existence here. The server answers that when
+ * the write lands, and "no such guide" from the route the write went to is the same news one
+ * round trip earlier.
+ */
+export async function resolveId(ref) {
+  if (/^https?:\/\//.test(ref)) return parse(await api.fetchShared(ref)).meta.id;
+  if (ref.endsWith(".md") && existsSync(ref)) return parse(readFileSync(ref, "utf8")).meta.id;
+  if (ID_RE.test(ref)) return ref;
+  throw new PassalongError(`"${ref}" is not a passalong id, share link, or .md file`);
+}
+
+/**
+ * Pull a guide into a working directory: writes .passalong/<id>.md there and returns the guide
+ * so the caller can put the text straight into an agent's context. A pull of someone else's
+ * guide is also recorded server-side, which is how the sender sees the transfer landed.
  */
 export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
   const { guide, from } = await resolve(ref);
+  // A locally cached copy of a teammate's guide still counts as a pull for them.
+  if (from === "local" && api.loggedIn() && guide.meta.team) {
+    api.get(guide.meta.id).catch(() => {});
+  }
   let path = null;
   if (write) {
     const dir = join(cwd, ".passalong");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    // A pulled guide carries its own share URL in the frontmatter, and that URL needs no account
+    // to read. Committing this directory would publish the guide to anyone who can see the repo,
+    // so the directory ignores itself. Delete this file if you do want guides in the repo.
+    const ignore = join(dir, ".gitignore");
+    if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
     path = join(dir, `${guide.meta.id}.md`);
     writeFileSync(path, serialize(guide));
   }
   return { guide, from, path, markdown: serialize(guide) };
 }
 
+/**
+ * Pull a guide *and* take the handoff: the two halves of starting work, in one call.
+ *
+ * `pull` says the guide arrived. `ack` says somebody is doing it, which is the thing the sender
+ * cannot find out any other way — and the two are deliberately separate, because reading a guide
+ * to decide it is not yours is exactly what `pass` is for. Fetching is not committing.
+ *
+ * For an agent the distinction is real but the ordering never varies: it reads a guide because it
+ * is about to follow it. So this is the path an agent takes when it means to do the work, and it
+ * is one call rather than two — the mandated thing has to be the cheap thing or it gets skipped.
+ * `pull` alone remains the way to read one without answering for it.
+ *
+ * The ack is best-effort and never costs the caller the markdown, which is what they came for:
+ *
+ *   - the author's own guide is a 403 (`ack` is the reader's answer and an author is not a party
+ *     to it), and that is a no-op, not a failure — an agent working in its own user's repo hits
+ *     this constantly;
+ *   - logged out, there is nobody to tell;
+ *   - anything else is reported in `ack_error` rather than swallowed, because an ack that quietly
+ *     did not land leaves the sender in the silence the whole feature exists to end.
+ */
+export async function start(ref, { cwd = process.cwd(), write = true } = {}) {
+  const pulled = await pull(ref, { cwd, write });
+  const id = pulled.guide.meta.id;
+  if (!api.loggedIn()) return { ...pulled, took: false, ack_error: "", own: false };
+  try {
+    await api.ack(id, true, "");
+    return { ...pulled, took: true, ack_error: "", own: false };
+  } catch (err) {
+    if (err.status === 403) return { ...pulled, took: false, ack_error: "", own: true };
+    return { ...pulled, took: false, ack_error: err.message, own: false };
+  }
+}
+
+/**
+ * The one line `get_guide` adds to a guide it is handing an agent, or "" when there is nothing to
+ * say. Separate from the tool so it can be tested without a server.
+ *
+ * Only a guide that was addressed to somebody can be taken — one nobody was handed has no handoff
+ * to answer for, and nudging about it is noise that teaches an agent to ignore the nudge.
+ *
+ * It goes after the document, not in front of it. Anything before the opening `---` stops the
+ * frontmatter being frontmatter, and an agent that writes what it was handed back out to a file
+ * would lose the id along with it.
+ */
+export function handoffNudge(meta = {}) {
+  if (!meta.to && !meta.team) return "";
+  return (
+    "<!-- passalong: this guide was handed to someone. If you are about to do the work, call " +
+    "start_guide instead of get_guide — it takes the handoff so the sender stops guessing. " +
+    "If you are only reading, or it turns out not to be yours, answer with ack_guide taken=false " +
+    "and a reason. -->"
+  );
+}
+
+/**
+ * The image types a guide can carry as evidence. Mirrors SHOT_TYPES in apps/api/src/shots.ts —
+ * the server is the authority and refuses anything else; this is what lets a local caller find
+ * out before spending an upload on it.
+ */
+export const SHOT_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+/**
+ * Attach a screenshot from disk, and return the markdown that points at it.
+ *
+ * Evidence belongs *in* the document: a guide travels as markdown to anyone holding its link, so
+ * an image beside it would not travel at all. `claimShots` binds the upload to whichever guide's
+ * markdown names it at publish, which is why this returns a line to paste rather than taking a
+ * guide id — there is nothing to attach it to until the document says so.
+ *
+ * Local because it reads a path. An agent in a terminal has one; a hosted assistant does not, and
+ * reaches the same route through `attach_screenshot` on the HTTP server instead.
+ */
+export async function attach(file, { name = "" } = {}) {
+  if (!api.loggedIn())
+    throw new PassalongError("attaching evidence needs sync — run `passalong login` first");
+  if (!existsSync(file)) throw new PassalongError(`no file at ${file}`);
+  const ext = file.slice(file.lastIndexOf(".")).toLowerCase();
+  const type = SHOT_TYPES[ext];
+  if (!type)
+    throw new PassalongError(
+      `screenshots must be ${[...new Set(Object.values(SHOT_TYPES))].join(", ")} — ${ext || file} is not one`,
+    );
+  const shot = await api.uploadShot(readFileSync(file), type, name || basename(file));
+  return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
+}
+
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
-export async function list(query = "", { remote = true } = {}) {
-  const local = store.search(query);
+export async function list(query = "", { remote = true, scope = "" } = {}) {
+  const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);
   const seen = new Set(local.map((g) => g.meta.id));
   const rows = local.map((g) => ({ ...summary(g), where: "local" }));
   if (remote && api.loggedIn()) {
     try {
-      const res = await api.list(query);
+      const res = await api.list(query, scope);
       for (const r of res.guides) {
-        if (seen.has(r.id)) {
-          const row = rows.find((x) => x.id === r.id);
-          row.where = "synced";
-          row.url = r.url;
-          row.pulls = r.pulls;
-        } else rows.push({ ...r, where: "synced" });
+        const row = seen.has(r.id) ? rows.find((x) => x.id === r.id) : null;
+        if (row) Object.assign(row, r, { where: "synced" });
+        else rows.push({ ...r, where: "synced" });
       }
     } catch (err) {
       rows.warning = `sync unavailable: ${err.message}`;
@@ -109,6 +312,68 @@ export async function list(query = "", { remote = true } = {}) {
   return rows.sort((a, b) => (b.created || "").localeCompare(a.created || ""));
 }
 
+/** Guides handed to you (or your teams) that you have not pulled yet. Needs sync. */
+export async function inbox() {
+  const res = await api.inbox();
+  return res.guides;
+}
+
+/**
+ * The state of your transfers as four queues: waiting on you, in flight (handed over, untouched),
+ * and landed (someone else has it). Needs sync.
+ */
+export const board = () => api.board();
+
+/**
+ * What you did, newest first: what you published, what you took delivery of, and every verdict and
+ * ack you gave. The other half of `activity` — that one is what other people did to your guides and
+ * it clears when you read it; this is your own record and it never clears.
+ *
+ * It is a record of what you passed along, not of what you worked on. Work that never became a
+ * guide has no row, so anything printing this has to say so. Needs sync.
+ */
+export async function log({ repo = "", since = "" } = {}) {
+  const res = await api.log({ repo, since });
+  return res.log;
+}
+
+/**
+ * What happened while you were away: your guides being pulled and shipped, guides handed to you,
+ * invites taken up. Each item carries a rendered `text` line so every surface says the same thing.
+ */
+export async function activity({ all = false, limit = 50 } = {}) {
+  return api.notifications({ unread: !all, limit });
+}
+
+/**
+ * Report whether a guide actually works. This is the reader's answer, not the author's status:
+ * `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.
+ */
+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());
+}
+
+/**
+ * Say whether you are taking a guide someone handed you — before doing any of it.
+ *
+ * The hop the product had no signal for: until this, a handoff nobody had answered looked exactly
+ * like one nobody had noticed. Passing needs a reason for the same cause a failing verdict does —
+ * "not me" without "why" leaves the sender where the silence did.
+ */
+export async function ack(id, taken, note = "") {
+  if (!api.loggedIn()) throw new PassalongError("acks need sync — run `passalong login` first");
+  if (!taken && !note.trim())
+    throw new PassalongError("say why you are passing: pass a note with taken=false");
+  return api.ack(await resolveId(id), taken, note.trim());
+}
+
+/** Mark notifications seen. No ids means everything unread. */
+export const seen = (ids = []) => api.markRead(ids);
+
 export function summary(g) {
   return {
     id: g.meta.id,
@@ -119,6 +384,9 @@ export function summary(g) {
     tags: g.meta.tags || [],
     stack_assumptions: g.meta.stack_assumptions || [],
     url: g.meta.url || null,
+    team: g.meta.team || "",
+    to: g.meta.to || "",
+    mine: true,
   };
 }
 
@@ -134,7 +402,7 @@ export async function setStatus(id, status) {
 }
 
 export async function remove(id) {
-  store.remove(id);
+  // Server first: if it refuses (not the author), the local copy must survive too.
   if (api.loggedIn()) {
     try {
       await api.remove(id);
@@ -142,6 +410,7 @@ export async function remove(id) {
       if (err.status !== 404) throw err;
     }
   }
+  store.remove(id);
 }
 
 /** Write every local guide to a directory as plain markdown. Returns the paths written. */