passalong 0.17.0 → 0.19.0

package/src/mcp.js

@@ -297,13 +297,16 @@ export function buildServer() {
         "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
         "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
-        "is a spelling that is not one of the three. " +
+        "is a spelling that is not one of the three. A NEW GUIDE IS READY: it reaches whoever it is " +
+        "for at once. Say `status: draft` only when the person should read it first — something you " +
+        "are unsure of — and tell them; plan_tasks drafts for you. Every kind moves the same way — " +
+        "Ready, taken, handed in, approved. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
-        "alone, and treat Acceptance as the definition of done. New tasks say `status: draft`; " +
-        "a proposal awaiting a team decision stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
-        "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
-        "author reviews it against Acceptance.\n" +
+        "alone, and treat Acceptance as the definition of done. A proposal awaiting a team decision " +
+        "stays Draft until a person makes it Ready. hand_in when every Acceptance line holds: it is " +
+        "final — the task goes to Done with what you showed, and nobody reviews it after you — so " +
+        "show it, and say anything you had to adapt in `writeup` (500 characters).\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
         "Follow its Steps, adapting anything marked ASSUMES to this codebase; run its " +
         "Verification, then hand_in with ok and, when it failed, a note saying what went wrong.\n" +
@@ -346,6 +349,18 @@ export function buildServer() {
         "the user asks what they have been working on, or wants a standup or a summary of a " +
         "period, call log — but say that it holds what they passed along and not everything they " +
         "did. Gotchas are the highest-value section: record what failed and why.\n" +
+        "A FOLDER IS A PLACE; ITS DOCUMENTS ARE WHAT TO KNOW; GUIDES ARE WHAT TO DO. Sort every " +
+        "item before writing it into a folder. If someone still has to act on it — a defect that " +
+        "is still open, work not yet done, a check nobody has run — it is a guide: kind bug for " +
+        "something broken, kind task for work to do. Publish it and link_folder_guide it into the " +
+        "folder; a guide has an owner, a state and an answer. A document has none of those and " +
+        "tells nobody, so open work recorded only as a document is lost. If it is what someone " +
+        "needs to know — an overview, a decision, a finding, something already fixed with its " +
+        "commit — it is a document. An incident is both: one overview document, a document per " +
+        "resolved finding, and a bug or task guide per open item, all in the incident's folder. " +
+        "WHERE A FOLDER LIVES is in the `space` field of create_folder and get_folder: private, " +
+        "or a named team. Tell the person that, never what you meant to do; a folder made without " +
+        "`team` is private, and a subfolder takes its parent's space.\n" +
         "FOLDERS ARE REUSABLE PROJECT CONTEXT, NOT GUIDES. When the user asks for a folder for a " +
         "script, brief, assets or work spanning several guides, call list_folders first to avoid " +
         "making a duplicate. If none fits, call create_folder with a title and short description. " +
@@ -366,8 +381,11 @@ export function buildServer() {
         "unlink_folder_guide takes it out again. Delete a document or file with " +
         "delete_folder_document or delete_folder_asset only when the person asked for it to go: " +
         "neither can be undone. No tool deletes a whole folder; a person does that in the hub. " +
+        "share_folder returns a link anyone can read the folder by, like a guide's; use it only " +
+        "when the person asked to share the folder. " +
         "list_folders with query finds folders and documents by their words, and with guide the " +
-        "folders a guide is in. rename_folder_document renames a document; " +
+        "folders a guide is in. rename_folder_document renames a document and move_folder_document " +
+        "moves it to another folder in the same space, keeping its history; " +
         "get_folder_document_history reads earlier versions, so a bad edit can be put back.\n" +
         "A FOLLOW-UP IS MORE CONTEXT FOR A GUIDE, WRITTEN AS ITS OWN GUIDE. When a guide needs " +
         "more context — a missing detail, a step that needed explaining, what changed since, what " +
@@ -404,15 +422,6 @@ export function buildServer() {
   async function doTake({ id, cwd, any }) {
     const dir = cwd || process.cwd();
     try {
-      // Without sync there is no claim to make; a guide by id can still be read and worked from.
-      if (!api.loggedIn() && id) {
-        const r = await passalong.pull(id, { cwd: dir });
-        return text(
-          `${leadFor(parse(r.markdown).meta)}${r.markdown}\n\n<!-- passalong: not logged in, so ` +
-            "nobody was told you took it; written to " +
-            `${r.path} -->`,
-        );
-      }
       const r = await passalong.take(id, { cwd: dir, any: Boolean(any) });
       if (!r.guide) return text(nextNote(r) || "Nothing is waiting for this agent here.");
       const meta = parse(r.guide.markdown).meta;
@@ -421,8 +430,7 @@ export function buildServer() {
       const from = await passalong.parentGuide(meta);
       const held =
         `<!-- passalong: ${r.guide.id} is yours` +
-        `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}; ` +
-        `written to ${r.path}. -->`;
+        `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}. -->`;
       const said = repliesNote(r.replies);
       return text(
         `${said ? `${said}\n\n` : ""}${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
@@ -559,7 +567,7 @@ export function buildServer() {
       title: "Create project folder",
       annotations: ADDS,
       description:
-        "Create a folder or nested subfolder after checking list_folders. Pass parent to nest it; omit team for a private root, and pass a team slug only when sharing was requested. A subfolder inherits its parent's space.",
+        "Create a folder or nested subfolder after checking list_folders. Pass parent to nest it; omit team for a private root, and pass a team slug only when sharing was requested. A subfolder inherits its parent's space. The answer's `space` says where it landed: report that to the person.",
       inputSchema: {
         title: z.string().describe("Name of the project or body of work"),
         description: z.string().optional().describe("Short purpose of the folder"),
@@ -702,7 +710,8 @@ export function buildServer() {
     {
       title: "Write new folder document",
       annotations: ADDS,
-      description: "Add Markdown such as a brief or script to a folder.",
+      description:
+        "Add a Markdown document to a folder: reference to read, such as a brief, script, overview or a finding already resolved. It has no owner and no state and notifies nobody, so anything someone must still act on (an open bug, work to do) belongs in a bug or task guide linked to the folder instead.",
       inputSchema: { folder: z.string(), name: z.string(), body: z.string() },
     },
     async ({ folder, name, body }) => {
@@ -752,6 +761,45 @@ export function buildServer() {
       }
     },
   );
+  server.registerTool(
+    "share_folder",
+    {
+      title: "Share folder link",
+      annotations: ADDS,
+      description:
+        "Get the folder's share link, making one if it has none: like a guide's link, anyone holding it can read the folder and the folders inside it and download its files, with no account. Linked guides are not included. Call it only when the person asked to share the folder or for its link; stopping sharing is done in the hub.",
+      inputSchema: { folder: z.string() },
+    },
+    async ({ folder }) => {
+      try {
+        return json(await api.shareFolder(folder));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "move_folder_document",
+    {
+      title: "Move folder document",
+      annotations: ADDS,
+      description:
+        "Move a folder document into another folder in the same space, private or the same team. It keeps its id, text and history; pass name too to rename it on the way. Refused if the other folder already has a document by that name.",
+      inputSchema: {
+        folder: z.string().describe("The folder the document is in now"),
+        document: z.string(),
+        to: z.string().describe("The folder to move it into"),
+        name: z.string().optional().describe("A new name, if it should change too"),
+      },
+    },
+    async ({ folder, document, to, name }) => {
+      try {
+        return json(await api.moveFolderDocument(folder, document, to, name || ""));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
   server.registerTool(
     "get_folder_document_history",
     {
@@ -852,7 +900,7 @@ export function buildServer() {
       annotations: READS,
       description:
         "Search transfer guides by words in the title, tags, stack, or body: the user's own " +
-        "(local and synced) plus every team they belong to. Empty query lists everything, newest first.",
+        "plus every team they belong to. Empty query lists everything, newest first.",
       inputSchema: {
         query: z.string().default(""),
         scope: z.string().optional().describe('"mine", "all" (default), or a team slug'),
@@ -861,7 +909,7 @@ export function buildServer() {
     async ({ query, scope }) => {
       try {
         const rows = await passalong.list(query, { scope: scope || "" });
-        return json({ guides: rows, warning: rows.warning });
+        return json({ guides: rows });
       } catch (err) {
         return fail(err);
       }
@@ -1037,7 +1085,7 @@ export function buildServer() {
         const ids = await passalong.planTasks(steps, { cwd: cwd || process.cwd() });
         return json({
           drafts: ids.map((id, i) => ({ id, title: steps[i].title, after: steps[i].after || [] })),
-          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
+          next: `all in Draft: ask the user to read them and mark them Ready on the board at ${api.baseUrl()}/hub/work, or run \`passalong ready --all\``,
         });
       } catch (err) {
         return fail(err);
@@ -1110,7 +1158,7 @@ export function buildServer() {
       outputSchema: handInOut,
       annotations: ADDS,
       description:
-        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "Finished here, with proof. IT IS FINAL: the work goes to Done with what you showed, and nobody reviews it after you (anyone can reopen it with a reason). So SHOW IT: a screenshot for anything with a screen — before and after, for a bug — or, for backend work, the one command and the line of its output that shows it works. Send `checks`: one entry per " +
         "line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a " +
         "bug — each with that line and the evidence for it. That is what its author reads, line " +
         "against line, instead of hunting through a wall of output for the part that answers each " +
@@ -1118,8 +1166,7 @@ export function buildServer() {
         "command proves it: the command is run here before the hand-in lands, a non-zero exit " +
         "refuses it, and what it printed is recorded instead of your account of it. Use `ran` for " +
         "a check no command can settle. `evidence` as one block is the older shape and still " +
-        "works. A task also takes `markdown`, a transfer guide about what you did and decided — " +
-        "this publishes it and attaches it. A handoff or a bug takes `ok`, whether its " +
+        "works. A task needs no write-up guide any more. A handoff or a bug takes `ok`, whether its " +
         "Verification held here, and `note` saying what went wrong when it did not. DO NOT " +
         "publish a guide to carry your evidence: it belongs on this call, and a second document " +
         'titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you ' +
@@ -1195,10 +1242,10 @@ export function buildServer() {
           .string()
           .optional()
           .describe(
-            "handoff or bug: what you had to adapt to make it work here — a version, a name, a " +
-              "step that needed something the guide does not mention. Prose, and optional: leave " +
-              "it out when it worked as written. The next person to open the guide is shown it, " +
-              "which is why it does not need to be a guide of its own",
+            "what you had to adapt to make it work here — a version, a name, a step that needed " +
+              "something the guide does not mention. 500 characters at most; anything longer " +
+              "belongs in the change. Optional: leave it out when it worked as written. The next " +
+              "person to open the guide is shown it",
           ),
         risk: z
           .string()
@@ -1212,11 +1259,11 @@ export function buildServer() {
         markdown: z
           .string()
           .optional()
-          .describe("task: the write-up; start from guide_template kind transfer"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         report: z
           .string()
           .optional()
-          .describe("task, instead of markdown: id of a write-up already published"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         pr: z.string().optional().describe("task: PR or branch link, when there is one"),
         cwd: z
           .string()
@@ -1288,18 +1335,13 @@ export function buildServer() {
       description:
         "READ a transfer guide by passalong id or share link and return its markdown. A guide over " +
         "20,000 characters comes back as an outline (its headings and their sizes) unless you ask " +
-        "for `section`, for one part, or `full`, for all of it. Also " +
-        "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
+        "for `section`, for one part, or `full`, for all of it. Nothing is written to disk. " +
         "Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide " +
         "you have not committed to. If you are about to DO the work, call take instead: " +
         "it does this and takes it in one call, which is the only way the sender learns " +
         "somebody picked it up.",
       inputSchema: {
         ref: z.string().describe("passalong id (e.g. k3mq2xa7) or share URL"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("directory to write .passalong/<id>.md into; default is the server's cwd"),
         section: z
           .string()
           .optional()
@@ -1314,23 +1356,23 @@ export function buildServer() {
           .describe("the whole document, even one over 20,000 characters"),
       },
     },
-    async ({ ref, cwd, section, outline, full }) => {
+    async ({ ref, section, outline, full }) => {
       try {
-        const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
+        const { markdown, from } = await passalong.pull(ref);
         const meta = parse(markdown).meta;
         if (section) {
           const part = sectionOf(markdown, section);
           if (!part)
             return text(
-              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref, path })}`,
+              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref })}`,
             );
           return text(
-            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; the whole guide is at ${path} -->`,
+            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; ask with full: true for the whole guide -->`,
           );
         }
         if (outline || (!full && markdown.length > GUIDE_WARN))
           return text(
-            `${outlineText(markdown, { id: meta.id || ref, path })}\n\n<!-- passalong: ${from}; written to ${path} -->`,
+            `${outlineText(markdown, { id: meta.id || ref })}\n\n<!-- passalong: ${from} -->`,
           );
         const lead = leadFor(meta);
         const siblings = await related(meta);
@@ -1347,7 +1389,7 @@ export function buildServer() {
         // warning against executing the document, so being read first is its whole job.
         return text(
           `${follows}${lead}${markdown}${siblings}${context ? `\n\n${context}` : ""}` +
-            `\n\n<!-- passalong: ${from}; written to ${path} -->` +
+            `\n\n<!-- passalong: ${from} -->` +
             `\n${passalong.handoffNudge(meta)}` +
             `\n${passalong.followUpNote(meta)}`,
         );
@@ -1517,7 +1559,7 @@ export function buildServer() {
     },
     async ({ markdown, to, cwd, parent }) => {
       try {
-        const { guide, url, synced, notified, path } = await passalong.share(markdown, {
+        const { guide, url, synced, notified } = await passalong.share(markdown, {
           cwd: cwd || process.cwd(),
           to,
           follows: parent,
@@ -1531,14 +1573,14 @@ export function buildServer() {
           to: guide.meta.to || "",
           parent: guide.meta.parent || "",
           notified,
-          path,
           ...(sizeWarning(markdown.length) ? { warning: sizeWarning(markdown.length) } : {}),
-          // A task does not go live on publish, and an agent that reports "queued it" has told
-          // the user something untrue. Said in the result so it is said to them.
-          ...(guide.meta.kind === "task" && guide.meta.status === "draft"
+          // Nothing goes live on publish, and an agent that reports "sent it" or "queued it" has
+          // told the user something untrue. Said in the result so it is said to them.
+          ...(guide.meta.status === "draft"
             ? {
                 status: "draft",
-                next: `in Draft: ask the user to read it, then run \`passalong ready ${guide.meta.id}\``,
+                // The hub page, never the share link: the share page has no Ready button.
+                next: `in Draft: ask the user to read it and mark it Ready at ${api.baseUrl()}/hub/g/${guide.meta.id}, or run \`passalong ready ${guide.meta.id}\``,
               }
             : {}),
         });
@@ -1745,5 +1787,6 @@ export function buildServer() {
 
 /** The stdio server: `passalong mcp`, and what `passalong setup` registers with a client. */
 export async function serve() {
+  passalong.tidy().catch(() => {});
   await buildServer().connect(new StdioServerTransport());
 }