@plotio/cli 0.4.0 → 0.5.0

package/README.md

@@ -38,6 +38,10 @@ a hash. Each is kept once redeemed, so later shells need nothing.
   `PLOT_API_URL` unless it is production) and every command works with no login
   and nothing stored, which is what a sandbox or a CI job wants.
 
+Whoever grants the access also chooses whether the agent may post. Allowed
+drafts only, `plot message` still works and `--send` is refused
+(`draft_only`); `plot whoami` says so under **Writes**.
+
 `plot login` ends three ways, and what it can see decides which:
 
 - **This machine's browser.** It opens, you approve, and it hands the terminal
@@ -63,9 +67,10 @@ a hash. Each is kept once redeemed, so later shells need nothing.
 | `plot read <page> [--json]`                                   | The page as Markdown (topics included), or as JSON; stores the updates cursor |
 | `plot watch <page> [--level …] [options]`                     | Wait for the next update, print it, store the cursor                          |
 | `plot topics <page>`                                          | Topics as JSON, with the quotes behind each point                             |
+| `plot task <page> [--status <s>] [--assign <id>]…`            | A task page's Status and assignees; with an option, set them                  |
 | `plot search <query> [--limit] [--next] [--json]`             | Search every page the workspace grant can read                                |
 | `plot message <page> [--body <t>] [--branch] [--note] [--id]` | Draft a message into the person's composer (body from `--body`, else stdin)   |
-| `plot message <page> --send …`                                | Post it as the person instead, marked "via" your agent                        |
+| `plot message <page> --send …`                                | Post it now instead, shown as your agent, for the person                      |
 | `plot message <page> --show\|--discard [<id>]`                | Read back or withdraw a draft (the last one made here by default)             |
 | `plot mcp-config [--host <h>] [--token] [--write] [<page>]`   | The MCP server block for a host: the `<api>/mcp` URL, signed in with OAuth    |
 | `plot help agents`                                            | The guide for an AI agent                                                     |

package/dist/plot.js

@@ -21,7 +21,7 @@ Run "plot --help" for usage.`, 2);
 };
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // src/api.ts
 var DEFAULT_API_URL = "https://agents.plot.io";
@@ -61,6 +61,7 @@ var UPDATE_LEVELS = [
 ];
 var MAX_WAIT_SECONDS = 240;
 var CURSOR_HEADER = "X-Plot-Updates-Cursor";
+var TASK_STATUSES = ["Todo", "Doing", "Done"];
 function createApi(opts) {
   const fetchFn = opts.fetch ?? fetch;
   const base = opts.base;
@@ -214,6 +215,50 @@ function createApi(opts) {
       });
       return { body: await json(response), cursor: cursorFrom(response) };
     },
+    /** GET /v1/pages/:id/attachments/:id: where one file's bytes are. */
+    async attachment(token, pageId, attachmentId, variant) {
+      const response = await request(
+        "GET",
+        `/v1/pages/${enc(pageId)}/attachments/${enc(attachmentId)}`,
+        { token, query: { variant } }
+      );
+      return await json(response);
+    },
+    /**
+     * The bytes, from the presigned URL the call above handed back.
+     *
+     * No Authorization header, and not through `request`, which would add
+     * one. R2 signs a presigned URL in the query string and refuses a
+     * request that also carries an Authorization header, with
+     * `400 InvalidRequest: Missing x-amz-content-sha256` — an error naming a
+     * header nobody was trying to send, which is why it is written down.
+     *
+     * Note what does *not* need defending against: Node's fetch and `curl`
+     * both drop the header themselves when following a cross-origin
+     * redirect, so `?redirect=1` is safe with either. The way to meet this
+     * is to send the header on purpose, which is what any authenticated
+     * fetch wrapper does — including this file's own `request`.
+     */
+    async download(url) {
+      let response;
+      try {
+        response = await fetchFn(new URL(url), { method: "GET" });
+      } catch (err) {
+        throw new ApiError(
+          0,
+          "network",
+          `Could not fetch the file: ${err.message}`
+        );
+      }
+      if (!response.ok) {
+        throw new ApiError(
+          response.status,
+          "download_failed",
+          `The storage service answered ${response.status} for that file. A signed URL lives only a few minutes; ask for it again.`
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
     /**
      * GET /v1/pages/:id/updates. `wait` is honoured by the production proxy
      * (a long poll, capped at MAX_WAIT_SECONDS) and ignored by Convex directly, so
@@ -242,6 +287,24 @@ function createApi(opts) {
         await request("GET", `/v1/pages/${enc(pageId)}/topics`, { token })
       );
     },
+    /**
+     * PATCH /v1/pages/:id/task: set a task page's Status, its assignees, or
+     * both. Only the fields given are sent. 400 `not_a_task` on any other
+     * page; a grant that cannot post is refused as a send is.
+     */
+    async updateTask(token, pageId, update) {
+      const body = {};
+      if (update.status !== void 0) body.status = update.status;
+      if (update.assigneeIds !== void 0) {
+        body.assigneeIds = update.assigneeIds;
+      }
+      return json(
+        await request("PATCH", `/v1/pages/${enc(pageId)}/task`, {
+          token,
+          body
+        })
+      );
+    },
     /** GET /v1/search?q=. */
     async search(token, q, page2 = {}) {
       return json(
@@ -442,6 +505,8 @@ Usage: plot <command> [options]
   read <page> [--json]                  The page as Markdown, topics included
   watch <page> [--level <level>]        Wait for what is new since the last watch
   topics <page>                         The page's topics as JSON
+  files <page> [--get <id>] [--out <p>] Files on the page; --get writes one to disk
+  task <page> [--status <s>]            A task's Status and assignees, or set them
   search <query> [--limit] [--next]    Search your pages (workspace login)
   message <page> [--body <text> | stdin] Draft a message into the person's composer
   message <page> --send \u2026               Or post it as them, only when they asked
@@ -478,6 +543,12 @@ Read:
                               A later watch starts from the end of this read.
   plot read <page> --json     The same, structured
   plot topics <page>          Topics as JSON, with the quotes behind each point
+  plot files <page>           Files on the page, with the ids read prints
+  plot files <page> --get <id>
+                              Writes that file where you can open it and
+                              prints the path. This is how you look at a
+                              screenshot or a PDF someone attached: fetch
+                              it, then read the path with your own tools
   plot pages                  Pages you can read (workspace login only)
   plot search "<words>"       Find a page or a moment (workspace login only)
 
@@ -493,9 +564,16 @@ Follow a meeting that is still happening:
 
 Write back (only if the person who gave you access can post):
   plot message <page> --body "\u2026"         Goes into their composer as a draft for them to send
-  plot message <page> --send --body "\u2026"  Appears as the person at once, marked "via <your name>":
+  plot message <page> --send --body "\u2026"  Appears at once, as you, for the person:
                                          only when they asked you to post
 
+A task page carries a Status (Todo, Doing, Done) and Assignees; plot read
+shows them on the line under the title. If you are working a task, say
+where you stand on the page itself, with the same access as a send:
+  plot task <page> --status Doing        When you start
+  plot task <page> --status Done         When it is finished
+  plot task <page>                       Just print the Status and assignees
+
 <page> is a page id or a link like https://www.plot.io/p/<id>.
 
 ${DATA_NOT_INSTRUCTIONS}
@@ -572,6 +650,43 @@ stored cursor the server refuses is dropped and the watch starts over.
 
 The page's topics as JSON: title, emoji, summary and points with their
 source quotes and message ids.`,
+  files: `plot files <page> [--json]
+plot files <page> --get <id> [--out <path>] [--original]
+
+The files people attached to messages on the page: name, type, size, an
+image's pixel size, and the id. The same ids "plot read" prints.
+
+--get <id> fetches one and writes it where you can open it, printing the
+path it wrote. That is the point of this command: your file-reading tool
+takes a path, and the signed URL behind the file lives five minutes.
+
+For an image you get the preview Plot made (bounded, WebP, a fraction of
+the bytes) unless you ask for --original; everything else has only the
+original. The bytes come straight from storage, never through Plot.
+  --get <id>        Fetch this file
+  --out <path>      Write it here instead of the cache directory
+                    ($XDG_CACHE_HOME/plot/files/<page>/, else ~/.cache/...).
+                    "--out -" writes the bytes to stdout and nothing to disk
+  --original        The file as uploaded, rather than the preview
+  --variant <v>     original or preview, said explicitly
+  --json            The file's fields, with the path it was written to`,
+  task: `plot task <page> [--status Todo|Doing|Done] [--assign <userId>]...
+                 [--unassign-all] [--json]
+
+A task page's fields, as the line under its title in "plot read": Status
+and Assignees, and the page it is part of. With no options it prints them;
+with any, it sets them and prints the result. An option left out leaves
+that field as it is. A page that is not a task is refused before anything
+is written.
+  --status <s>      Todo, Doing or Done
+  --assign <id>     Make this user an assignee; repeat for more. Replaces the
+                    assignees, so name everyone who should stay. User ids are
+                    the members' ids in "plot read <page> --json"
+  --unassign-all    Leave the task with no assignees
+  --json            Print the task block (status, assignees with id and name)
+
+Setting needs a member who can post: a viewer's grant is refused (read_only)
+as a send is.`,
   search: `plot search <query> [--limit <n>] [--next <cursor>] [--json]
 
 Searches every page the workspace grant can read: messages, topics and page
@@ -594,11 +709,12 @@ same lane replaces the first, and says so.
                   makes one id, so a retry after a dropped connection lands
                   once
 
---send posts it now instead, as the person, marked "via <your agent>". Use it
+--send posts it now instead, shown as your agent, for the person. Use it
 only when they asked you to post. With no words given it sends your earlier
 draft as it stands, formatting intact: the one --id names, else the last one
 made here. A grant that cannot post is refused (read_only), never quietly
-turned into a draft.
+turned into a draft, and so is one whose person allowed drafts only
+(draft_only) \u2014 the same command without --send still works.
 
 --show reads a draft back (its words and note), or says it was sent.
 --discard withdraws a draft; a sent message cannot be withdrawn here
@@ -606,7 +722,8 @@ turned into a draft.
 machine made on the page.
 
 Needs a member who can post: a viewer's grant is refused (read_only) for a
-draft as for a send.`,
+draft as for a send. plot whoami says "Writes: drafts only" for a grant that
+was connected without the send.`,
   "mcp-config": `plot mcp-config [--host <host>] [--write] [--token]
                 [--inline-token] [<page>]
 
@@ -795,7 +912,10 @@ function renderPages(pages2, next) {
   const rows = pages2.map((page2) => {
     const extras = [
       page2.unread ? `${page2.unread} unread` : "",
-      page2.canPost === false ? "read-only" : ""
+      // Three states, not two: a draft-only grant may still write into the
+      // person's composer here, and labelling that "read-only" tells the
+      // agent not to try.
+      page2.canPost === false ? page2.canDraft ? "drafts only" : "read-only" : ""
     ].filter(Boolean);
     const when = formatTime(page2.updatedAt);
     return [
@@ -860,6 +980,11 @@ function renderUpdate(update) {
       ].filter(Boolean);
       const tag = marks.length ? ` [${marks.join(", ")}]` : "";
       out.push(`${line.authorName || "Unknown"}${tag}: ${line.text ?? ""}`);
+      for (const file of line.files ?? []) {
+        out.push(
+          `  [Attachment: ${file.name} \xB7 ${file.contentType} \xB7 id ${file.id}]`
+        );
+      }
     }
     out.push("");
   }
@@ -901,6 +1026,10 @@ function credentialsPath(env, homeDir) {
   const configHome = env.XDG_CONFIG_HOME?.trim() || join(homeDir, ".config");
   return join(configHome, "plot", "credentials.json");
 }
+function filesCachePath(env, homeDir, pageId) {
+  const cacheHome = env.XDG_CACHE_HOME?.trim() || join(homeDir, ".cache");
+  return join(cacheHome, "plot", "files", pageId);
+}
 async function loadStore(path) {
   let text;
   try {
@@ -1335,6 +1464,13 @@ function describeMe(me, source, origin) {
   const rows = [
     ["API", origin],
     ["Credential", `${me.scope ?? "unknown"} scope (from ${source})`],
+    // Only worth a row when it is the narrower one: "can post" is what a
+    // credential has always been able to do, and whether it can here still
+    // depends on the page.
+    [
+      "Writes",
+      me.capability === "draft" ? "drafts only, cannot post" : void 0
+    ],
     ["Agent", me.agent],
     ["Granted by", me.grantedBy],
     ["Workspace", me.workspace?.name],
@@ -1350,37 +1486,178 @@ function describeMe(me, source, origin) {
   return rows.filter(([, value]) => value).map(([label, value]) => `${`${label}:`.padEnd(12)}${value}`).join("\n");
 }
 
+// src/commands/files.ts
+import { mkdir as mkdir2, mkdtemp, writeFile as writeFile2 } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename as basename2, isAbsolute, join as join2, resolve, sep } from "node:path";
+function renderFiles(files2) {
+  if (files2.length === 0) return "No files on this page.";
+  return files2.map((file) => {
+    const parts = [file.name, file.contentType, formatSize(file.size)];
+    if (file.image) parts.push(`${file.image.width}\xD7${file.image.height}`);
+    parts.push(`id ${file.id}`);
+    return parts.join(" \xB7 ");
+  }).join("\n");
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${Math.round(kb)} KB`;
+  const mb = kb / 1024;
+  return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
+}
+function safeFileName(name) {
+  const base = basename2(name).replace(/[^A-Za-z0-9._-]+/g, "-");
+  const trimmed = base.replace(/^[.-]+/, "").slice(0, 120);
+  return trimmed === "" ? "file" : trimmed;
+}
+var EXTENSION_FOR = {
+  "image/webp": ".webp",
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/gif": ".gif",
+  "image/avif": ".avif"
+};
+function nameForBytes(name, contentType) {
+  const want = EXTENSION_FOR[contentType];
+  if (!want) return name;
+  const dot = name.lastIndexOf(".");
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  return name.slice(dot).toLowerCase() === want ? name : `${stem}${want}`;
+}
+async function listFiles(rt, pageId, token) {
+  const read2 = await rt.api.readJson(token, pageId);
+  const messages = Array.isArray(read2.body.messages) ? read2.body.messages : [];
+  return messages.flatMap((message2) => message2.attachments ?? []);
+}
+function variantFlag(rt) {
+  const original = rt.values.original === true;
+  const asked = stringFlag(rt, "variant");
+  if (asked !== void 0 && original) {
+    throw new UsageError("--variant does not go with --original.");
+  }
+  if (original) return "original";
+  if (asked === void 0) return void 0;
+  if (asked !== "original" && asked !== "preview") {
+    throw new UsageError(
+      `--variant "${asked}" is not a variant: use original or preview.`
+    );
+  }
+  return asked;
+}
+function contained(dir, name) {
+  const path = resolve(dir, name);
+  if (path !== dir && !path.startsWith(resolve(dir) + sep)) {
+    throw new CliError(
+      `Refusing to write outside ${dir}: that file's details do not make a filename.`
+    );
+  }
+  return path;
+}
+async function write(path, bytes) {
+  await mkdir2(join2(path, ".."), { recursive: true });
+  await writeFile2(path, bytes);
+}
+async function files(rt) {
+  const pageId = parsePageRef(rt.positionals[0]);
+  if (rt.positionals.length > 1) {
+    throw new UsageError(`Unexpected argument "${rt.positionals[1]}".`);
+  }
+  const id = stringFlag(rt, "get");
+  if (id === void 0 && rt.values.get !== void 0) {
+    throw new UsageError(
+      '--get needs the id of a file. Run "plot files" for them.'
+    );
+  }
+  const variant = variantFlag(rt);
+  const out = stringFlag(rt, "out");
+  if (id === void 0 && (out !== void 0 || variant !== void 0)) {
+    throw new UsageError(
+      "--out, --variant and --original only apply with --get <id>."
+    );
+  }
+  if (id === void 0) {
+    const list = await withToken(
+      rt,
+      pageId,
+      (token) => listFiles(rt, pageId, token)
+    );
+    if (rt.values.json) printJson(rt, list);
+    else rt.ctx.out(renderFiles(list));
+    return;
+  }
+  const { found, bytes } = await withToken(rt, pageId, async (token) => {
+    const found2 = await rt.api.attachment(token, pageId, id, variant);
+    return { found: found2, bytes: await rt.api.download(found2.url) };
+  });
+  if (out === "-") {
+    rt.ctx.writeStdout(bytes);
+    return;
+  }
+  const label = found.variant === "preview" || found.variant === "original" ? found.variant : "file";
+  const name = `${safeFileName(id)}-${label}-${nameForBytes(
+    safeFileName(found.name),
+    found.urlContentType
+  )}`;
+  const dir = filesCachePath(rt.ctx.env, rt.ctx.homeDir, pageId);
+  const chosen = out === void 0 ? contained(dir, name) : isAbsolute(out) ? out : resolve(rt.ctx.cwd, out);
+  let path = chosen;
+  try {
+    await write(chosen, bytes);
+  } catch (err) {
+    if (out !== void 0) {
+      throw new CliError(`Could not write ${chosen}: ${err.message}`);
+    }
+    path = contained(await mkdtemp(join2(tmpdir(), "plot-files-")), name);
+    try {
+      await write(path, bytes);
+    } catch (second) {
+      throw new CliError(
+        `Could not write ${chosen} (${err.message}) or ${path} (${second.message}).`
+      );
+    }
+    rt.ctx.err(
+      `Could not write under ${filesCachePath(rt.ctx.env, rt.ctx.homeDir, pageId)}; used the temp directory instead. A temp directory may differ between calls in a sandbox, so read this file now rather than later.`
+    );
+  }
+  if (rt.values.json) {
+    printJson(rt, { ...found, path });
+  } else {
+    rt.ctx.out(path);
+  }
+}
+
 // src/commands/mcpConfig.ts
-import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { chmod as chmod2, mkdir as mkdir3, readFile as readFile2, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname as dirname2, join as join3 } from "node:path";
 var withHeaders = (headers) => headers ? { headers } : {};
 var HOSTS = {
   "claude-code": {
     root: "mcpServers",
     server: (url, headers) => ({ type: "http", url, ...withHeaders(headers) }),
-    file: (rt) => join2(rt.ctx.cwd, ".mcp.json"),
+    file: (rt) => join3(rt.ctx.cwd, ".mcp.json"),
     where: ".mcp.json in the project",
     envRef: (name) => `\${${name}}`
   },
   cursor: {
     root: "mcpServers",
     server: (url, headers) => ({ url, ...withHeaders(headers) }),
-    file: (rt) => join2(rt.ctx.homeDir, ".cursor", "mcp.json"),
+    file: (rt) => join3(rt.ctx.homeDir, ".cursor", "mcp.json"),
     where: "~/.cursor/mcp.json",
     envRef: (name) => `\${env:${name}}`
   },
   vscode: {
     root: "servers",
     server: (url, headers) => ({ type: "http", url, ...withHeaders(headers) }),
-    file: (rt) => join2(rt.ctx.cwd, ".vscode", "mcp.json"),
+    file: (rt) => join3(rt.ctx.cwd, ".vscode", "mcp.json"),
     where: ".vscode/mcp.json in the project",
     envRef: (name) => `\${env:${name}}`
   },
   zed: {
     root: "context_servers",
     server: (url, headers) => ({ url, ...withHeaders(headers) }),
-    file: (rt) => join2(
-      rt.ctx.env.XDG_CONFIG_HOME?.trim() || join2(rt.ctx.homeDir, ".config"),
+    file: (rt) => join3(
+      rt.ctx.env.XDG_CONFIG_HOME?.trim() || join3(rt.ctx.homeDir, ".config"),
       "zed",
       "settings.json"
     ),
@@ -1525,8 +1802,8 @@ async function mcpConfig(rt) {
   }
   const root = existing[spec.root] ?? {};
   existing[spec.root] = { ...root, ...block[spec.root] };
-  await mkdir2(dirname2(file), { recursive: true });
-  await writeFile2(file, `${JSON.stringify(existing, null, 2)}
+  await mkdir3(dirname2(file), { recursive: true });
+  await writeFile3(file, `${JSON.stringify(existing, null, 2)}
 `, {
     mode: created ? 384 : void 0
   });
@@ -1629,19 +1906,27 @@ function renderCreated(status, created, title) {
   }
   if (m?.status === "sent" && status === 200) {
     lines.push(
-      created.agent ? `Already sent as the person who granted access, marked "via ${created.agent}", on ${place} (id ${m.id}). Nothing new was posted.` : `Already sent by the person who granted access, from their composer, on ${place} (id ${m.id}). Nothing new was posted.`
+      created.agent ? `Already sent as ${created.agent}, for the person who granted access, on ${place} (id ${m.id}). Nothing new was posted.` : `Already sent by the person who granted access, from their composer, on ${place} (id ${m.id}). Nothing new was posted.`
     );
   } else if (m?.status === "sent") {
     lines.push(
-      `Sent as the person who granted access, marked "via ${agent}", on ${place} (id ${m.id}).`
+      `Sent as ${agent}, for the person who granted access, on ${place} (id ${m.id}).`
     );
   } else {
     const verb = status === 201 || created.replaced ? "Drafted" : "Updated the draft";
     lines.push(
-      `${verb} into the composer of the person who granted access, on ${place} (id ${m?.id}).`,
-      "Nobody else sees it: they edit it and send it, or discard it. Send it yourself only if they ask:",
-      `  plot message ${m?.pageId ?? "<page>"} --send --id ${m?.id}`
+      `${verb} into the composer of the person who granted access, on ${place} (id ${m?.id}).`
     );
+    if (m?.canSend === false) {
+      lines.push(
+        "Nobody else sees it: they edit it and send it, or discard it. This connection cannot post, so sending it is theirs to do."
+      );
+    } else {
+      lines.push(
+        "Nobody else sees it: they edit it and send it, or discard it. Send it yourself only if they ask:",
+        `  plot message ${m?.pageId ?? "<page>"} --send --id ${m?.id}`
+      );
+    }
   }
   return lines.join("\n");
 }
@@ -1749,6 +2034,73 @@ async function message(rt) {
   else rt.ctx.out(renderCreated(created.status, created.body, title));
 }
 
+// src/commands/task.ts
+function statusFlag(rt) {
+  const raw = stringFlag(rt, "status");
+  if (raw === void 0) {
+    if (rt.values.status !== void 0) throw badStatus("");
+    return void 0;
+  }
+  const status = TASK_STATUSES.find((s) => s.toLowerCase() === raw.toLowerCase());
+  if (!status) throw badStatus(raw);
+  return status;
+}
+function badStatus(raw) {
+  return new UsageError(
+    `--status "${raw}" is not a status: use ${TASK_STATUSES.join(", ")}.`
+  );
+}
+function assigneeFlags(rt) {
+  const raw = rt.values.assign;
+  const given = (Array.isArray(raw) ? raw : raw === void 0 ? [] : [raw]).map((id) => String(id).trim()).filter(Boolean);
+  const all = rt.values["unassign-all"] === true;
+  if (all && given.length > 0) {
+    throw new UsageError("--assign does not go with --unassign-all.");
+  }
+  if (all) return [];
+  if (raw !== void 0 && given.length === 0) {
+    throw new UsageError("--assign needs a user id.");
+  }
+  return given.length > 0 ? given : void 0;
+}
+function notATask(page2, pageId) {
+  const name = page2.title ? `"${page2.title}"` : pageId;
+  return new CliError(
+    `Not a task page: ${name}${page2.type ? ` (a ${page2.type})` : ""}. Only a task has a Status and assignees.`
+  );
+}
+function renderTask(page2, task2) {
+  const parts = ["Task", `Status: ${task2.status ?? "not set"}`];
+  const names = task2.assignees.map((a) => a.name || a.id);
+  if (names.length > 0) parts.push(`Assignees: ${names.join(", ")}`);
+  if (page2.parentUrl) parts.push(`Part of ${page2.parentUrl}`);
+  return page2.url ? `${parts.join(" \xB7 ")}
+${page2.url}` : parts.join(" \xB7 ");
+}
+async function task(rt) {
+  const pageId = parsePageRef(rt.positionals[0]);
+  if (rt.positionals.length > 1) {
+    throw new UsageError(`Unexpected argument "${rt.positionals[1]}".`);
+  }
+  const status = statusFlag(rt);
+  const assigneeIds = assigneeFlags(rt);
+  const writes = status !== void 0 || assigneeIds !== void 0;
+  const result = await withToken(rt, pageId, async (token) => {
+    const read2 = await rt.api.readJson(token, pageId);
+    const page2 = read2.body.page;
+    if (page2.type !== "task" || !page2.task) throw notATask(page2, pageId);
+    if (!writes) return { page: page2, task: page2.task };
+    return rt.api.updateTask(token, pageId, { status, assigneeIds }).catch((err) => {
+      if (err instanceof ApiError && err.code === "not_a_task") {
+        throw notATask(page2, pageId);
+      }
+      throw err;
+    });
+  });
+  if (rt.values.json) printJson(rt, result.task);
+  else rt.ctx.out(renderTask(result.page, result.task));
+}
+
 // src/commands/watch.ts
 var DEFAULT_INTERVAL_SECONDS = 3;
 function seconds(rt, key, fallback) {
@@ -1853,6 +2205,23 @@ var COMMANDS = {
     }
   },
   topics: { run: topics },
+  files: {
+    run: files,
+    options: {
+      get: { type: "string" },
+      out: { type: "string" },
+      variant: { type: "string" },
+      original: { type: "boolean" }
+    }
+  },
+  task: {
+    run: task,
+    options: {
+      status: { type: "string" },
+      assign: { type: "string", multiple: true },
+      "unassign-all": { type: "boolean" }
+    }
+  },
   search: {
     run: search,
     options: { next: { type: "string" }, limit: { type: "string" } }
@@ -1942,8 +2311,8 @@ import { createServer } from "node:http";
 function startLoopback(state) {
   let resolveCode;
   let rejectCode;
-  const code = new Promise((resolve, reject) => {
-    resolveCode = resolve;
+  const code = new Promise((resolve2, reject) => {
+    resolveCode = resolve2;
     rejectCode = reject;
   });
   code.catch(() => {
@@ -1992,13 +2361,13 @@ function startLoopback(state) {
     );
     resolveCode(value);
   });
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     server.once("error", reject);
     server.listen(0, "127.0.0.1", () => {
       server.off("error", reject);
       const { port } = server.address();
       let closed = false;
-      resolve({
+      resolve2({
         redirectUri: `http://127.0.0.1:${port}/callback`,
         code,
         close: () => {
@@ -2044,13 +2413,14 @@ function nodeContext() {
 `),
     err: (text) => process.stderr.write(text.endsWith("\n") ? text : `${text}
 `),
+    writeStdout: (bytes) => process.stdout.write(bytes),
     readStdin: async () => {
       const chunks = [];
       for await (const chunk of process.stdin) chunks.push(chunk);
       return Buffer.concat(chunks).toString("utf8");
     },
     stdinIsTTY: Boolean(process.stdin.isTTY),
-    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
     now: () => Date.now(),
     openUrl: (url) => openInBrowser(url, process.platform),
     listenLoopback: (state) => startLoopback(state).catch(() => void 0),
@@ -2061,8 +2431,8 @@ function nodeContext() {
   };
 }
 function promptLine(question, signal) {
-  return new Promise((resolve) => {
-    if (signal.aborted) return resolve(void 0);
+  return new Promise((resolve2) => {
+    if (signal.aborted) return resolve2(void 0);
     const rl = createInterface({
       input: process.stdin,
       output: process.stderr,
@@ -2070,7 +2440,7 @@ function promptLine(question, signal) {
     });
     let answered = false;
     rl.once("close", () => {
-      if (!answered) resolve(void 0);
+      if (!answered) resolve2(void 0);
     });
     signal.addEventListener(
       "abort",
@@ -2084,23 +2454,23 @@ function promptLine(question, signal) {
     rl.question(question, (answer) => {
       answered = true;
       rl.close();
-      resolve(answer);
+      resolve2(answer);
     });
   });
 }
 function openInBrowser(url, platform) {
   const command = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : null;
   if (!command) return Promise.resolve(false);
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     try {
       const child = spawn(command, [url], { stdio: "ignore", detached: true });
-      child.once("error", () => resolve(false));
+      child.once("error", () => resolve2(false));
       child.once("spawn", () => {
         child.unref();
-        resolve(true);
+        resolve2(true);
       });
     } catch {
-      resolve(false);
+      resolve2(false);
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plotio/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Read Plot pages, follow a meeting as it happens, and draft or send messages, from any agent with a shell.",
   "type": "module",
   "license": "MIT",