passalong 0.16.0 → 0.18.0

package/src/mcp.js

@@ -219,6 +219,8 @@ const passOut = openObject({ id: z.string(), passed: z.boolean() });
 
 const READS = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
 const ADDS = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+// Removes something that cannot be brought back. Only a person's request should lead here.
+const REMOVES = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
 const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError: true });
 
 /**
@@ -295,11 +297,13 @@ 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. EVERY NEW GUIDE IS A DRAFT, whatever its kind: " +
+        "it reaches nobody until a person reads it and marks it Ready, and every kind then 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 " +
+        "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 with `markdown`: a " +
         "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
         "author reviews it against Acceptance.\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
@@ -344,9 +348,23 @@ 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. " +
+        "Use its parent id to nest a subfolder at any depth; keep a related project together. " +
+        "A folder's color can mark an area, and update_folder can recolor or move it later. " +
         "A short request is enough: name it from the person's purpose and draft the first Markdown " +
         "document with create_folder_document. Do not leave an empty folder or make them fill a form. " +
         "Pass `team` only when the user wants it shared with that team; use the slug they named " +
@@ -355,8 +373,19 @@ export function buildServer() {
         "get_folder_document to read text and its version, and save_folder_document with that " +
         "version when editing. On a stale-version refusal, reread before retrying so another " +
         "person's work is not lost. Use add_folder_asset for a screenshot or file available on " +
-        "this machine, get_folder_asset to read one already there, and link_folder_guide only " +
-        "when an existing guide uses that folder.\n" +
+        "this machine, and get_folder_asset to read one already there. " +
+        "To put a guide in a folder — a task, bug or handoff, new or already published — publish it " +
+        "as usual (for a team folder, to that folder's team, or its members cannot see it), then call " +
+        "link_folder_guide with the folder id and the guide id. Linking leaves the guide unchanged; " +
+        "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 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 " +
         "you found doing it — publish that context with publish_guide `parent` set to the guide's " +
@@ -392,15 +421,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;
@@ -409,8 +429,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}` : ""}` +
@@ -526,12 +545,16 @@ export function buildServer() {
     {
       title: "List project folders",
       annotations: READS,
-      description: "Find project folders of documents, assets and guides. Requires sync sign-in.",
-      inputSchema: { scope: z.string().optional().describe('"all", "mine", or a team slug') },
+      description: `Find project folders of documents, assets and guides. Pass query to find the folders whose name, description, or any document's name or text mention those words; each then names its matching documents. Pass guide to find the folders a guide is in. Requires sync sign-in.`,
+      inputSchema: {
+        scope: z.string().optional().describe('"all", "mine", or a team slug'),
+        query: z.string().optional().describe("Words to look for in folders and their documents"),
+        guide: z.string().optional().describe("A guide id: only the folders it is linked in"),
+      },
     },
-    async ({ scope }) => {
+    async ({ scope, query, guide }) => {
       try {
-        return json(await api.folders(scope || "all"));
+        return json(await api.folders(scope || "all", { query, guide }));
       } catch (err) {
         return fail(err);
       }
@@ -543,16 +566,57 @@ export function buildServer() {
       title: "Create project folder",
       annotations: ADDS,
       description:
-        "Create a folder for project documents and assets after checking list_folders. Omit team for a private folder; pass a team slug only when sharing was requested.",
+        "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"),
         team: z.string().optional().describe("Team slug; omit for a private folder"),
+        parent: z
+          .string()
+          .optional()
+          .describe("Parent folder id for a nested subfolder; omit for a top-level folder"),
+        color: z
+          .enum(["coral", "amber", "green", "blue", "violet"])
+          .optional()
+          .describe("Optional grouping color"),
       },
     },
-    async ({ title, description, team }) => {
+    async ({ title, description, team, parent, color }) => {
       try {
-        return json(await api.createFolder(title, description || "", team || ""));
+        return json(
+          await api.createFolder(title, description || "", team || "", parent || "", color || ""),
+        );
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "update_folder",
+    {
+      title: "Organize project folder",
+      annotations: ADDS,
+      description:
+        "Rename, describe, recolor or move a folder. Pass parent as an empty string to move it to the top level. A folder cannot move inside itself or a descendant, or into another team/private space.",
+      inputSchema: {
+        folder: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        parent: z
+          .string()
+          .optional()
+          .describe("New parent folder id; empty string means top level"),
+        color: z.enum(["", "coral", "amber", "green", "blue", "violet"]).optional(),
+      },
+    },
+    async ({ folder, title, description, parent, color }) => {
+      try {
+        const changes = Object.fromEntries(
+          Object.entries({ title, description, parent, color }).filter(
+            ([, value]) => value !== undefined,
+          ),
+        );
+        return json(await api.updateFolder(folder, changes));
       } catch (err) {
         return fail(err);
       }
@@ -645,7 +709,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 }) => {
@@ -678,13 +743,90 @@ export function buildServer() {
       }
     },
   );
+  server.registerTool(
+    "rename_folder_document",
+    {
+      title: "Rename folder document",
+      annotations: ADDS,
+      description:
+        "Rename a folder document. Its id, text and history stay; no version is needed, because a rename cannot overwrite anyone's text.",
+      inputSchema: { folder: z.string(), document: z.string(), name: z.string() },
+    },
+    async ({ folder, document, name }) => {
+      try {
+        return json(await api.renameFolderDocument(folder, document, name));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  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",
+    {
+      title: "Read folder document history",
+      annotations: READS,
+      description:
+        "Read a folder document's earlier versions. Without version, lists them newest first; with version, returns that version's text. To bring one back, save it with save_folder_document over the current version.",
+      inputSchema: {
+        folder: z.string(),
+        document: z.string(),
+        version: z.number().int().positive().optional(),
+      },
+    },
+    async ({ folder, document, version }) => {
+      try {
+        return json(await api.folderDocumentHistory(folder, document, version || 0));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
   server.registerTool(
     "link_folder_guide",
     {
       title: "Link guide to folder",
       annotations: ADDS,
       description:
-        "Put an existing task or handoff beside the folder documents and assets it uses.",
+        "Put a task, bug or handoff guide in the folder, beside the documents and assets it uses: one just published or one that already existed.",
       inputSchema: { folder: z.string(), guide: z.string() },
     },
     async ({ folder, guide }) => {
@@ -696,6 +838,60 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "unlink_folder_guide",
+    {
+      title: "Unlink guide from folder",
+      annotations: ADDS,
+      description:
+        "Take a guide out of a folder. Only the link goes: the guide itself is unchanged, and link_folder_guide puts it back.",
+      inputSchema: { folder: z.string(), guide: z.string() },
+    },
+    async ({ folder, guide }) => {
+      try {
+        return json(await api.unlinkFolderGuide(folder, guide));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "delete_folder_document",
+    {
+      title: "Delete folder document",
+      annotations: REMOVES,
+      description:
+        "Delete one document from a folder, with its earlier versions. It cannot be brought back, so do it only when the person asked for that document to go; to change what it says, use save_folder_document instead.",
+      inputSchema: { folder: z.string(), document: z.string() },
+    },
+    async ({ folder, document }) => {
+      try {
+        return json(await api.deleteFolderDocument(folder, document));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "delete_folder_asset",
+    {
+      title: "Delete folder file",
+      annotations: REMOVES,
+      description:
+        "Delete one file from a folder. It cannot be brought back, so do it only when the person asked for that file to go.",
+      inputSchema: { folder: z.string(), asset: z.string() },
+    },
+    async ({ folder, asset }) => {
+      try {
+        return json(await api.deleteFolderAsset(folder, asset));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "search_guides",
     {
@@ -703,7 +899,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'),
@@ -712,7 +908,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);
       }
@@ -769,8 +965,8 @@ export function buildServer() {
         "delivery of, and every verdict and ack they gave. Each item has a rendered `text` line " +
         "and the guide's repo. Use it to answer 'what have I been working on', to write a " +
         "standup or a weekly summary, or to find work from a repo by when it happened rather " +
-        "than by what it was called. This is the opposite of `activity`, which is what other " +
-        "people did. IMPORTANT: it records what was passed along, not what was worked on — work " +
+        "than by what it was called. The hub calls this page Activities, so 'my activities' means " +
+        "this tool. It is the opposite of `activity`, which is what other people did. IMPORTANT: it records what was passed along, not what was worked on — work " +
         "that never became a guide has no entry, so never present it as a complete record of " +
         "this user's work, and never infer that a quiet period was an idle one.",
       inputSchema: {
@@ -797,8 +993,9 @@ export function buildServer() {
       annotations: READS,
       description:
         "What has happened to this user's guides and handoffs: who pulled one, who archived one, " +
-        "who was handed what, who joined a team. Each item has a ready-made `text` line. This only " +
-        "reads; clear_activity is what marks the feed seen.",
+        "who was handed what, who joined a team. Each item has a ready-made `text` line. This is " +
+        "the hub's notifications, not its Activities page — for the user's own acts ('my " +
+        "activities'), use log. This only reads; clear_activity is what marks the feed seen.",
       inputSchema: {
         all: z.boolean().default(false).describe("include what the user has already seen"),
       },
@@ -1138,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()
@@ -1164,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);
@@ -1197,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)}`,
         );
@@ -1367,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,
@@ -1381,11 +1573,10 @@ 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}\``,
@@ -1486,7 +1677,11 @@ export function buildServer() {
           { title: title || "", environment: environment || "", issues },
           { cwd: cwd || process.cwd(), to },
         );
-        return json(filed);
+        return json({
+          ...filed,
+          // Filed is not sent: every bug is a draft until a person reads it.
+          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
+        });
       } catch (err) {
         return fail(err);
       }
@@ -1595,5 +1790,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());
 }