passalong 0.3.0 → 0.3.1

package/bin/passalong

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Passalong CLI. Few flags on purpose: the defaults are the product.
 //
-//   passalong share [file] [--to TARGET]  publish a guide → id + link
+//   passalong share [file] [--to TARGET] [--follows ID]  publish a guide → id + link
 //     TARGET is a team, team/@handle for one person, or "team/#group" for the people who do a
 //     thing — quote that one, since a shell may read the # as a comment
 //   passalong attach <image>      upload evidence and print the markdown that points at it
@@ -19,7 +19,6 @@
 //   passalong works <id>          you tried it and it holds up
 //   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   passalong done <id>           archive it: off your board and out of the free tier's count
-//   passalong promote <id>        deprecated: mark promoted
 //   passalong rm <id>             delete a guide locally and from sync
 //   passalong export [dir]        dump every guide as plain markdown (default ./passalong-export)
 //   passalong login [token]       create an account, or attach this machine with a token from your hub
@@ -93,8 +92,7 @@ function guideLine(r) {
     const p = r.pulled_by[0];
     pulled = `  ← ${p.handle ? `@${p.handle}` : "link"} ${relDate(p.at)}${r.pulled_by.length > 1 ? ` +${r.pulled_by.length - 1}` : ""}`;
   }
-  const nudge = r.mine && r.status === "published" && r.pulls >= 3 ? "  ★ promote?" : "";
-  return `${r.id}  ${r.status.padEnd(9)} ${relDate(r.created).padEnd(10)} ${r.title}${who}${tags}${pulled}${nudge}`;
+  return `${r.id}  ${r.status.padEnd(9)} ${relDate(r.created).padEnd(10)} ${r.title}${who}${tags}${pulled}`;
 }
 
 function activityLine(n) {
@@ -127,12 +125,14 @@ const commands = {
     if (!existsSync(path)) die(`no such file: ${path}`);
     if (tty && !f["no-edit"]) edit(path);
     const to = typeof f.to === "string" ? f.to : undefined;
+    const follows = typeof f.follows === "string" ? f.follows : undefined;
     const { guide, url, synced, notified, path: saved } = await passalong
-      .share(readFileSync(path, "utf8"), { to })
+      .share(readFileSync(path, "utf8"), { to, follows })
       .catch((e) => die(e.message));
     if (fromDrafts) store.removeDraft(path);
     console.log(guide.meta.id);
     console.error(`shared "${guide.meta.title}" → ${saved}`);
+    if (guide.meta.parent) console.error(`follows ${guide.meta.parent}`);
     if (guide.meta.team)
       console.error(
         `handed to ${guide.meta.team}${guide.meta.to ? `/@${guide.meta.to}${notified ? " (emailed)" : " (in their inbox)"}` : " (team inbox)"}`,
@@ -334,16 +334,6 @@ const commands = {
     console.error(`${g.meta.id} archived — off your board, and it no longer counts against sync`);
   },
 
-  // Still on the way out: it sets an author lifecycle nothing reads, and the board reports pull
-  // counts on its own. It stays, and warns, because removing a command from a published package
-  // is a breaking change.
-  async promote(f) {
-    const id = f._[0] || die("usage: passalong promote <id>");
-    const g = await passalong.setStatus(id, "promoted").catch((e) => die(e.message));
-    console.error(`${g.meta.id} marked promoted`);
-    console.error("note: `promote` is deprecated — the board reports pull counts on their own");
-  },
-
   async rm(f) {
     const id = f._[0] || die("usage: passalong rm <id>");
     await passalong.remove(id).catch((e) => die(e.message));
@@ -392,7 +382,15 @@ const commands = {
     console.log(`handle   ${who.handle ? `@${who.handle}` : "(none — set one: passalong me --handle <you>)"}`);
     if (who.name) console.log(`name     ${who.name}`);
     if (who.email) console.log(`email    ${who.email}`);
-    console.log(`guides   ${who.guides} synced (${who.limit} active on the free tier)`);
+    // The server sends the state by name, because a number cannot tell "no ceiling" apart from
+    // "may sync nothing" — both of which arrive as a falsy limit.
+    const ceiling =
+      who.sync === "free"
+        ? ` (${who.limit} active on your plan)`
+        : who.sync === "none"
+          ? " (no plan — nothing is syncing)"
+          : " (no limit on your plan)";
+    console.log(`guides   ${who.guides} synced${ceiling}`);
     const current = store.readConfig().team;
     console.log(
       `teams    ${who.teams.length ? who.teams.map((t) => `${t.slug}${t.slug === current ? "*" : ""} (${t.role})`).join(", ") : "(none — passalong team create <name>)"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",

package/src/guide.js

@@ -5,16 +5,30 @@
 import { randomBytes } from "node:crypto";
 
 /**
- * A guide is a draft or it is published. `consumed` and `promoted` are legacy: they were an author
- * lifecycle laid over a transfer that already reports itself — `consumed` duplicated the verdict,
- * and `promoted` was a pull count with a name. Nothing sets them any more.
+ * A guide is a draft or it is published, and `consumed` is the author's shelf — off the board, out
+ * of the free tier's count, reversible. `promoted` is the one true legacy: an author lifecycle laid
+ * over a transfer that already reports itself, since a pull count says how travelled a guide is
+ * without anyone having to grade it.
  *
- * They stay in this list because they are *accepted*, not produced. The value lives in frontmatter
- * inside markdown files in other people's repositories, and `validate()` rejects a status it does
- * not know — so removing them here would make a guide shared a month ago fail to re-share today.
+ * This list is what is **accepted**, and it is not what may be **set** — that is `SETTABLE` below.
+ * The distinction is load-bearing. A status lives in frontmatter, inside markdown files in other
+ * people's repositories, and `validate()` rejects a status it does not know, so dropping a value
+ * from here would make a guide shared a month ago fail to re-share today.
  */
 export const STATUSES = ["draft", "published", "consumed", "promoted"];
 
+/**
+ * What a write may choose. `promoted` is absent: it cannot be set on a guide that does not already
+ * carry it, from any surface.
+ *
+ * Two reasons, and the second is the sharper one. A status that can still be set reads as a
+ * feature to whoever meets it next, however many deprecation notices sit around it. And
+ * `quota.ts` counts `published` and `promoted` as the statuses that occupy room — so while
+ * `promoted` remains settable, promoting every guide is an unlimited free tier. Closing the write
+ * closes that, and does it without touching what the free tier counts, which still has to include
+ * the guides already carrying the status.
+ */
+export const SETTABLE = ["draft", "published", "consumed"];
 /**
  * What a guide is for. The receiving agent behaves completely differently depending on the
  * answer, so it is a field rather than something inferred from the body.
@@ -291,6 +305,24 @@ export function sections(body) {
   return out;
 }
 
+/**
+ * Image targets no reader will ever load. Mirrors `unreachableImages` in apps/api/src/guide.ts,
+ * which is the authority and refuses the publish; this lets a local share fail before the network.
+ *
+ * Only a foreign scheme counts — `attachment://`, `blob:`, `file:`, `data:`. `https:` is left alone
+ * because embedding an image you host is legitimate, and a relative path is left alone because it
+ * has always been accepted.
+ */
+export function unreachableImages(markdown) {
+  const bad = [...String(markdown).matchAll(/!\[[^\]]*\]\(\s*([^)\s]+)/g)]
+    .map((m) => m[1].trim())
+    .filter((target) => {
+      const scheme = /^([a-z][a-z0-9+.\-]*):/i.exec(target);
+      return Boolean(scheme) && !/^https?$/i.test(scheme[1]);
+    });
+  return [...new Set(bad)];
+}
+
 /** Problems that make a guide unfit to publish. Empty array means it is fine. */
 export function validate({ meta, body }) {
   const errors = [];
@@ -321,6 +353,12 @@ export function validate({ meta, body }) {
     errors.push('a bug uses "## Reproduce", not "## Steps" — an agent executes Steps');
   }
   if (body.includes("<!-- passalong:")) errors.push("template placeholders are still in the body");
+  // An agent that has a file id but never called attach_screenshot writes the id as if it were a
+  // link. It publishes, and stores a guide whose screenshot was never uploaded anywhere.
+  for (const target of unreachableImages(body))
+    errors.push(
+      `${target} is not a URL a reader can load — attach the image first and use the URL it returns`,
+    );
   return errors;
 }
 
@@ -354,7 +392,26 @@ export function bugGuide({
   report = "",
   environment = "",
   status = "published",
+  evidence = [],
 } = {}) {
+  /**
+   * Screenshots, as markdown inside the document.
+   *
+   * They go under Problem rather than a heading of their own, because for a visual defect the
+   * picture *is* the problem statement and a bug's sections are a fixed set — a seventh heading
+   * would change the shape every reader keys on to add a line that already belongs in the first
+   * one.
+   *
+   * Naming them in the body is also the only thing that binds them: `claimShots` claims whatever
+   * the markdown points at, scoped to the author, so a URL listed anywhere else would upload
+   * evidence that no guide owns and the nightly sweep deletes.
+   */
+  const shots = (Array.isArray(evidence) ? evidence : [evidence])
+    .map((s) => String(s ?? "").trim())
+    .filter(Boolean)
+    // A caller that already has the markdown line from `attach_screenshot` passes it through
+    // whole; one holding just the URL gets it wrapped. Both reach the same document.
+    .map((s) => (s.startsWith("![") ? s : `![evidence](${s})`));
   const body = [
     // Written into the document, not added by whatever served it.
     //
@@ -367,10 +424,13 @@ export function bugGuide({
     "",
     "## Problem",
     problem.trim() || "_No description given._",
+  ];
+  if (shots.length) body.push("", ...shots);
+  body.push(
     "",
     "## Reproduce",
     reproduce.trim() || "_Not recorded — the description above is what there is._",
-  ];
+  );
   // Both are optional and both are worse than absent when empty: a Verification heading with
   // nothing under it says nobody knows what fixed looks like, on the section a fixer reads first.
   if (verification.trim()) body.push("", "## Verification", verification.trim());

package/src/mcp.js

@@ -81,6 +81,11 @@ export async function serve() {
         "because you reproduced it. " +
         "When you find defects you are not fixing — a test run, a QA pass, a review — call " +
         "file_bugs with all of them at once; each becomes a guide someone can take on its own. " +
+        "AN IMAGE THE USER SHOWED YOU IS EVIDENCE, NOT CONTEXT. Before filing or publishing, " +
+        "attach it with attach_screenshot and pass what it returns as `evidence` — a screenshot " +
+        "you described instead of attaching is the most useful thing in the report, thrown away. " +
+        "A guide already filed without one is not stuck: get_guide it, add the markdown line to " +
+        "the body, and publish_guide the same id — publishing claims whatever the markdown names. " +
         "When the user asks to pass along, hand off, or " +
         "share what was just done, distill the session into a guide (guide_template shows the " +
         "shape) and call publish_guide, with `to` as team, team/@handle for one teammate, or " +
@@ -394,7 +399,10 @@ export async function serve() {
       description:
         "Publish a guide from markdown (frontmatter + sections) — a transfer guide by default, or " +
         "a single bug with `kind: bug`; use file_bugs for more than one. Missing id, created, " +
-        'author, and source_context are filled in. `to` addresses it to a team ("khaime") or a ' +
+        "author, and source_context are filled in. A screenshot belongs in the markdown: attach it " +
+        "with attach_screenshot and put the line it returns in the body, because publishing claims " +
+        "whatever the markdown names. " +
+        '`to` addresses it to a team ("khaime") or a ' +
         'teammate ("khaime/lukman"), who is notified. Returns the id and share link.',
       inputSchema: {
         markdown: z.string().describe("full guide markdown; start from guide_template"),
@@ -406,13 +414,21 @@ export async function serve() {
           .string()
           .optional()
           .describe("directory the work happened in, used to infer source_context"),
+        parent: z
+          .string()
+          .optional()
+          .describe(
+            "id or share link of the guide this one came out of — set it when this is what you " +
+              "learned doing someone else's guide, so theirs lists it as a follow-up",
+          ),
       },
     },
-    async ({ markdown, to, cwd }) => {
+    async ({ markdown, to, cwd, parent }) => {
       try {
         const { guide, url, synced, notified, path } = await passalong.share(markdown, {
           cwd: cwd || process.cwd(),
           to,
+          follows: parent,
         });
         return json({
           id: guide.meta.id,
@@ -421,6 +437,7 @@ export async function serve() {
           synced,
           team: guide.meta.team || "",
           to: guide.meta.to || "",
+          parent: guide.meta.parent || "",
           notified,
           path,
         });
@@ -439,7 +456,10 @@ export async function serve() {
         "publishes each issue as its own guide — its own id, share link, and verdict — so a " +
         "reviewer can hand any one of them to whoever fixes it. Use this after a test run, a QA " +
         "pass, or a review that turned up defects; use publish_guide instead for work you " +
-        "finished and want repeated elsewhere. Needs sync (`passalong login`).",
+        "finished and want repeated elsewhere. If there is a screenshot of any of this, it is " +
+        "evidence: call attach_screenshot first and pass what it returns as that issue's " +
+        "`evidence`. Describing a screenshot instead of attaching it throws away the most useful " +
+        "thing in the report. Needs sync (`passalong login`).",
       inputSchema: {
         title: z
           .string()
@@ -456,6 +476,13 @@ export async function serve() {
         issues: z
           .array(
             z.object({
+              evidence: z
+                .array(z.string())
+                .default([])
+                .describe(
+                  "screenshot URLs from attach_screenshot, or the markdown lines it returned; " +
+                    "they go under Problem, where a reader looks first",
+                ),
               title: z.string().describe("what is broken, in one line"),
               problem: z
                 .string()
@@ -527,10 +554,11 @@ export async function serve() {
     {
       title: "Set guide status",
       description:
-        "Deprecated — prefer verify_guide. Marks a guide consumed or promoted, an author lifecycle " +
-        "nothing reads any more: the board reports where a transfer is and the verdict reports " +
-        "whether it worked. Kept so existing callers do not break. Only the author can promote.",
-      inputSchema: { id: z.string(), status: z.enum(["published", "consumed", "promoted"]) },
+        "Archive a guide (`consumed`) or put it back on the board (`published`). Archiving is the " +
+        "author's shelf: off the board, out of the free tier's count, reversible — it is not a " +
+        "judgement that the work landed, which is what verify_guide reports. `promoted` was " +
+        "retired and the server refuses it.",
+      inputSchema: { id: z.string(), status: z.enum(["published", "consumed"]) },
     },
     async ({ id, status }) => {
       try {

package/src/passalong.js

@@ -37,7 +37,7 @@ export function parseTarget(to) {
  * logged in. `to` addresses it: "team", "team/@handle", or "team/#group". Returns
  * { guide, path, url, synced }.
  */
-export async function share(markdown, { cwd = process.cwd(), to } = {}) {
+export async function share(markdown, { cwd = process.cwd(), to, follows } = {}) {
   const c = context(cwd);
   const raw = parse(markdown);
   let guide = stamp(
@@ -50,6 +50,10 @@ export async function share(markdown, { cwd = process.cwd(), to } = {}) {
   const target = parseTarget(to);
   if (target.team) guide.meta.team = target.team;
   if (target.to) guide.meta.to = target.to;
+  // `follows` names the guide this one came out of: an id, a share link, or a pulled .md file. An id
+  // is used as it is; a link or a file is read for the id in its own frontmatter. `validate()` below
+  // is what refuses a guide that names itself.
+  if (follows) guide.meta.parent = await resolveId(String(follows).trim());
   if (guide.meta.to && !guide.meta.team)
     throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
   const errors = validate(guide);
@@ -390,7 +394,7 @@ export function summary(g) {
   };
 }
 
-/** Move a guide through its lifecycle: published → consumed → promoted (any order allowed). */
+/** Archive a guide (`consumed`) or put it back (`published`). The server refuses `promoted`. */
 export async function setStatus(id, status) {
   if (!STATUSES.includes(status))
     throw new PassalongError(`status must be one of ${STATUSES.join(", ")}`);