smashspace 0.3.0 → 0.5.0

package/README.md

@@ -112,6 +112,45 @@ smash card update <cardId> --desc-file spec.md   # multi-line body from a file /
 Pick a board with `-b <label>` (defaults to `main`), or bypass config with
 `--board-id <id>`.
 
+## Agent inbox: who said what to whom
+
+Comments carry an optional **recipient**, so several agents can hand work to
+each other on the card it is about — no separate channel, and a human reads the
+same thread in the UI.
+
+```bash
+smash comment add <cardId> "PR is up, please review" --author codex --to claude-code
+smash inbox --to claude-code          # only what is addressed to me
+smash inbox --since <cursor>          # only what I have not read yet
+```
+
+`smash inbox` prints a `cursor` at the end; pass it as the next `--since` and
+you read each message once. `--json` gives `{ comments, cursor }`.
+
+## Write from CI or a cloud job (no CLI, no MCP)
+
+For environments where you cannot install anything — a scheduled cloud run, a
+webhook handler, a GitHub Action — issue a **board-scoped write-only token** and
+post with `curl`:
+
+```bash
+smash token create <boardId> "GitHub Actions"   # shown once; store it now
+smash token list <boardId>                      # prefix / created / last used
+smash token revoke <boardId> <tokenId>          # immediate
+
+curl -X POST https://smashspace.app/api/ingest \
+  -H "Authorization: Bearer smash_ing_xxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: my-event-123" \
+  -d '{"list":"やること","title":"支払いエラー","labels":["緊急"]}'
+```
+
+The token can only create cards and comments on that one board — it cannot read
+or delete. Lists and labels are matched by name, so the caller needs no internal
+ids, and a repeated `Idempotency-Key` returns the first card instead of making
+another (keys never expire). Tokens can also be issued from the space's
+**Settings → Connect** tab.
+
 ## Multiple repos on one machine
 
 `smash` is **directory-aware**: it walks up from your current directory to the

package/dist/smash.mjs

@@ -3398,6 +3398,40 @@ import { createInterface } from "node:readline/promises";
 import { relative, join as join3, dirname as dirname3, basename } from "node:path";
 import { stdin, stdout } from "node:process";
 
+// ../../shared/assignee-id.ts
+function normalizeAssigneeName(name) {
+  return name.trim().toLowerCase();
+}
+function findAssigneeByName(known, name) {
+  const needle = normalizeAssigneeName(name);
+  return known.find((a) => normalizeAssigneeName(a.display_name) === needle);
+}
+function hash32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+function stableAssigneeId(kind, name) {
+  const normalized = normalizeAssigneeName(name);
+  const ascii = normalized.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  const suffix = ascii.length >= 2 ? ascii : hash32(normalized).toString(36).padStart(7, "0");
+  return `${kind}_${suffix}`;
+}
+function resolveAssignee(known, input) {
+  const existing = input.explicitId ? known.find((a) => a.id === input.explicitId) : findAssigneeByName(known, input.name);
+  const id = input.explicitId ?? existing?.id ?? stableAssigneeId(input.kind, input.name);
+  const emoji = input.emoji ?? existing?.avatar_emoji;
+  return {
+    kind: input.kind,
+    id,
+    display_name: input.name.trim(),
+    ...emoji ? { avatar_emoji: emoji } : {}
+  };
+}
+
 // ../../shared/board-registry.ts
 var BOARD_ID_PATTERN = /^(?:board_|b_|s_)[a-z0-9]+$/i;
 var URL_BOARD_PATTERN = /^(https?:\/\/[^/]+)\/(?:board|space)\/((?:board_|b_|s_)[a-z0-9]+)/i;
@@ -4135,7 +4169,7 @@ cardCmd.command("move <cardId>").description("Move a card to a list (and optiona
 );
 cardCmd.command("delete <cardId>").description("Delete a card").action(async (cardId) => {
   await api(`/api/cards/${cardId}`, { method: "DELETE" });
-  console.log(`\u2713 card ${cardId} deleted`);
+  console.log(`\u2713 card ${cardId} archived (restore with: smash archive restore ${cardId})`);
 });
 cardCmd.command("search <query>").description(
   "Search cards by case-insensitive substring match (title + description). Use --board to search one board, or set SMASH_BOARDS env var to search all registered boards."
@@ -4202,15 +4236,101 @@ cardCmd.command("search <query>").description(
   console.log(`
 ${allHits.length} card(s) found`);
 });
-cardCmd.command("comment <cardId> <body>").description("Add a comment to a card").option("--author <name>", "Author name").action(
+cardCmd.command("comment <cardId> <body>").description("Add a comment to a card").option("--author <name>", "Author name").option(
+  "--to <id>",
+  "Address the comment to an assignee id (repeatable). Agents poll their own with `smash inbox --to <id>`.",
+  collectRepeated,
+  []
+).action(
   async (cardId, body, opts) => {
     const comment = await api(`/api/cards/${cardId}/comments`, {
       method: "POST",
-      body: JSON.stringify({ body, authorName: opts.author })
+      body: JSON.stringify({
+        body,
+        authorName: opts.author,
+        ...opts.to.length > 0 ? { recipients: opts.to } : {}
+      })
     });
-    show(comment, [`\u2713 comment ${comment.id} added`]);
+    show(comment, [
+      `\u2713 comment ${comment.id} added${comment.recipients?.length ? ` \u2192 ${comment.recipients.join(", ")}` : ""}`
+    ]);
   }
 );
+function collectRepeated(value, previous) {
+  return [...previous, value];
+}
+program2.command("cards").description(
+  "List cards on the resolved board \u2014 light by default (no description). Filter by list/assignee, pick columns with --fields."
+).option("-b, --board <label>", "board label from config").option("--board-id <id>", "explicit board id (bypass config)").option("-l, --list <name>", "only cards in this list (name or id)").option("--assignee <idOrName>", "only cards assigned to this id or display name").option(
+  "--fields <list>",
+  "comma-separated columns (default: id,title,listId,listTitle,updatedAt). Add description only when you need bodies."
+).option("--limit <n>", "max cards per page (default 100, max 500)").option("--cursor <cursor>", "continue from a previous response's cursor").action(async (opts) => {
+  const ctx = resolveContext(opts);
+  const params = new URLSearchParams();
+  if (opts.list)
+    params.set("list", opts.list);
+  if (opts.assignee)
+    params.set("assignee", opts.assignee);
+  if (opts.fields)
+    params.set("fields", opts.fields);
+  if (opts.limit)
+    params.set("limit", opts.limit);
+  if (opts.cursor)
+    params.set("cursor", opts.cursor);
+  const qs = params.toString();
+  const result = await api(
+    `/api/boards/${ctx.boardId}/cards${qs ? `?${qs}` : ""}`,
+    void 0,
+    ctx.baseUrl
+  );
+  if (getOpts().json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  for (const card of result.cards) {
+    const listTitle = typeof card.listTitle === "string" ? `[${card.listTitle}] ` : "";
+    console.log(`${listTitle}${String(card.title ?? "")}  (${String(card.id ?? "")})`);
+  }
+  console.log(
+    `
+${result.cards.length} of ${result.total}${result.cursor ? `  next: --cursor ${result.cursor}` : ""}`
+  );
+});
+program2.command("inbox").description(
+  `New comments across the resolved board (${CONFIG_FILENAME}). Poll with --since <cursor> to read only what you have not seen.`
+).option("-b, --board <label>", "board label from config").option("--board-id <id>", "explicit board id (bypass config)").option("--since <iso>", "only comments created after this ISO timestamp (exclusive)").option("--to <id>", "only comments addressed to this assignee id").option("--limit <n>", "max comments to read (default 100, max 500)").action(async (opts) => {
+  const ctx = resolveContext(opts);
+  const params = new URLSearchParams();
+  if (opts.since)
+    params.set("since", opts.since);
+  if (opts.to)
+    params.set("to", opts.to);
+  if (opts.limit)
+    params.set("limit", opts.limit);
+  const qs = params.toString();
+  const result = await api(
+    `/api/boards/${ctx.boardId}/comments${qs ? `?${qs}` : ""}`,
+    void 0,
+    ctx.baseUrl
+  );
+  if (getOpts().json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.comments.length === 0) {
+    console.log(`(no new comments)${result.cursor ? `  cursor: ${result.cursor}` : ""}`);
+    return;
+  }
+  for (const c of result.comments) {
+    const to = c.recipients?.length ? ` \u2192 ${c.recipients.join(", ")}` : "";
+    console.log(
+      `[${c.createdAt}] ${c.authorName ?? "anon"}${to}  (${c.listTitle} / ${c.cardTitle} \xB7 ${c.cardId})`
+    );
+    console.log(`  ${c.body.replace(/\n/g, "\n  ")}`);
+  }
+  console.log(`
+cursor: ${result.cursor}`);
+});
 var archiveCmd = program2.command("archive [cardId]").description("Archive a card (soft-delete). Without cardId: manage archived cards (list/restore/purge)").option("-b, --board <label>", `board label from ${CONFIG_FILENAME}`).option("--board-id <id>", "explicit board id (bypass config)").action(async (cardId, opts) => {
   if (!cardId) {
     archiveCmd.help();
@@ -4278,12 +4398,18 @@ checklistCmd.command("delete <itemId>").description("Delete a checklist item").a
   console.log(`\u2713 checklist item ${itemId} deleted`);
 });
 var commentCmd = program2.command("comment").description("Card comments (add / edit / delete)");
-commentCmd.command("add <cardId> <body>").description("Add a comment to a card").option("--author <name>", "Author name").action(async (cardId, body, opts) => {
+commentCmd.command("add <cardId> <body>").description("Add a comment to a card").option("--author <name>", "Author name").option("--to <id>", "Address the comment to an assignee id (repeatable)", collectRepeated, []).action(async (cardId, body, opts) => {
   const comment = await api(`/api/cards/${cardId}/comments`, {
     method: "POST",
-    body: JSON.stringify({ body, authorName: opts.author })
+    body: JSON.stringify({
+      body,
+      authorName: opts.author,
+      ...opts.to.length > 0 ? { recipients: opts.to } : {}
+    })
   });
-  show(comment, [`\u2713 comment ${comment.id} added`]);
+  show(comment, [
+    `\u2713 comment ${comment.id} added${comment.recipients?.length ? ` \u2192 ${comment.recipients.join(", ")}` : ""}`
+  ]);
 });
 commentCmd.command("edit <commentId> <body>").description("Edit (replace body of) an existing comment").action(async (commentId, body) => {
   const comment = await api(`/api/comments/${commentId}`, {
@@ -4396,6 +4522,48 @@ attachmentCmd.command("delete <attachmentId>").description("Delete an attachment
   await api(`/api/attachments/${attachmentId}`, { method: "DELETE" });
   console.log(`\u2713 attachment ${attachmentId} deleted`);
 });
+var tokenCmd = program2.command("token").description("Board-scoped write tokens for external services (POST /api/ingest)");
+tokenCmd.command("create <boardId> <name>").description("Issue a write-only token for one board. The token is shown once.").action(async (boardId, name) => {
+  const created = await api(
+    `/api/boards/${boardId}/ingest-tokens`,
+    { method: "POST", body: JSON.stringify({ name }) }
+  );
+  show(created, [
+    `\u2713 token ${created.id} created for ${boardId}`,
+    "",
+    created.token,
+    "",
+    "Store it now \u2014 it is not shown again. It can only create cards and",
+    "comments on this board:",
+    `  curl -X POST ${resolveBaseUrl()}/api/ingest \\`,
+    `    -H "Authorization: Bearer ${created.token}" \\`,
+    '    -H "Content-Type: application/json" \\',
+    `    -d '{"list":"\u3084\u308B\u3053\u3068","title":"\u2026"}'`
+  ]);
+});
+tokenCmd.command("list <boardId>").description("List a board's write tokens (prefix, created, last used)").action(async (boardId) => {
+  const items = await api(`/api/boards/${boardId}/ingest-tokens`);
+  if (getOpts().json) {
+    console.log(JSON.stringify(items, null, 2));
+    return;
+  }
+  if (items.length === 0) {
+    console.log("(no tokens)");
+    return;
+  }
+  for (const t of items) {
+    console.log(
+      `${t.id}  ${t.name}  ${t.tokenPrefix}\u2026  created ${t.createdAt}  last used ${t.lastUsedAt ?? "never"}`
+    );
+  }
+});
+tokenCmd.command("revoke <boardId> <tokenId>").description("Revoke a write token (takes effect immediately)").action(async (boardId, tokenId) => {
+  const revoked = await api(
+    `/api/boards/${boardId}/ingest-tokens/${tokenId}`,
+    { method: "DELETE" }
+  );
+  show(revoked, [`\u2713 token ${revoked.id} revoked at ${revoked.revokedAt}`]);
+});
 var labelCmd = program2.command("label").description("Labels");
 labelCmd.command("create <boardId> <name>").description("Create a board label").option(
   "--color <color>",
@@ -4601,23 +4769,31 @@ assigneesCmd.command("add <cardId>").description("Append a single assignee (read
     console.error("--name must not be empty");
     process.exit(1);
   }
-  const id = opts.id ?? `${opts.kind}_${Math.random().toString(36).slice(2, 10)}`;
   const detail = await api(`/api/cards/${cardId}`);
   const current = detail.card.assignees ?? [];
-  const next = [
+  const board = await api(
+    `/api/boards/${detail.card.boardId}/cards?fields=assignees&limit=500`
+  );
+  const known = [
     ...current,
-    {
-      kind: opts.kind,
-      id,
-      display_name: opts.name,
-      ...opts.emoji ? { avatar_emoji: opts.emoji } : {}
-    }
+    ...board.cards.flatMap(
+      (c) => Array.isArray(c.assignees) ? c.assignees : []
+    )
   ];
+  const entry = resolveAssignee(known, {
+    kind: opts.kind,
+    name: opts.name,
+    explicitId: opts.id,
+    emoji: opts.emoji
+  });
+  const next = [...current, entry];
   const card = await api(`/api/cards/${cardId}`, {
     method: "PATCH",
     body: JSON.stringify({ assignees: next })
   });
-  show(card, [`\u2713 card ${card.id} assignees now has ${next.length} entries`]);
+  show(card, [
+    `\u2713 card ${card.id} assignees now has ${next.length} entries (${entry.display_name} \u2192 ${entry.id})`
+  ]);
 });
 assigneesCmd.command("update <cardId> <assigneeId>").description("Change an assignee's icon (emoji) and/or display name").option("--emoji <emoji>", "New avatar_emoji").option("--no-emoji", "Remove the avatar_emoji (fall back to the default icon)").option("--name <name>", "New display_name").action(async (cardId, assigneeId, opts) => {
   if (opts.emoji === void 0 && opts.name === void 0) {

package/dist/smashspace-mcp.mjs

@@ -15509,7 +15509,7 @@ var tools = [
   },
   {
     name: "smash_get_board",
-    description: "Get full board detail including lists, cards (with labelIds), and labels.",
+    description: "Get full board detail including lists, cards (with labelIds), and labels. This returns every card's full description and can run to six figures of characters on a busy board \u2014 prefer smash_list_cards when you only need to find cards, and come back here for the whole structure.",
     inputSchema: {
       type: "object",
       properties: {
@@ -15653,7 +15653,7 @@ var tools = [
   },
   {
     name: "smash_set_agent_meta",
-    description: "Set or clear a card's agent_meta (structured field for external agents like Claude Code). Pass agentMeta=null to clear. Common shape: {primary_agent, status: 'idle'|'working'|'waiting_review'|'blocked'|'done', turn: 'human'|'agent'|'blocked', started_at, updated_at, progress (0..1), current_step}. avatar_emoji is shown on the board's cards, so give each agent a distinct emoji (and reuse the same id) to make ownership visible at a glance. Extra keys are accepted for forward-compat.",
+    description: "Set or clear a card's agent_meta (structured field for external agents like Claude Code). Pass agentMeta=null to clear. Common shape: {primary_agent, status: 'idle'|'working'|'waiting_review'|'blocked'|'done', turn: 'human'|'agent'|'blocked', started_at, updated_at, progress (0..1), current_step}. REUSE THE SAME id for the same role across cards (e.g. always 'platform', not a fresh random id): ids are how anyone filters cards later, and a role that gets a new id per card cannot be filtered at all. Check smash_list_cards with fields=['assignees'] to see which ids the board already uses. avatar_emoji is shown on the board's cards, so give each agent a distinct emoji (and reuse the same id) to make ownership visible at a glance. Extra keys are accepted for forward-compat.",
     inputSchema: {
       type: "object",
       properties: {
@@ -15701,6 +15701,41 @@ var tools = [
       body: JSON.stringify({ externalRefs: args.externalRefs ?? null })
     })
   },
+  {
+    name: "smash_list_cards",
+    description: "List a board's cards WITHOUT their descriptions \u2014 use this instead of smash_get_board when you only need to find cards. smash_get_board returns every card body and can exceed a tool-output limit on a busy board. Filter with `list` and `assignee` (matches an assignee id or display name), and pick columns with `fields` (default: id, title, listId, listTitle, updatedAt). Pass fields including 'description' only when you truly need bodies; otherwise fetch one card with smash_get_card. Paginate with the returned `cursor`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        boardId: { type: "string" },
+        list: { type: "string", description: "List name (case-insensitive) or list id" },
+        assignee: { type: "string", description: "Assignee id or display name" },
+        fields: {
+          type: "array",
+          items: { type: "string" },
+          description: "Columns to return: id, boardId, title, description, listId, listTitle, position, dueAt, labelIds, checklistTitle, agentMeta, externalRefs, assignees, customData, createdAt, updatedAt"
+        },
+        limit: { type: "number", description: "Max cards per page (default 100, max 500)" },
+        cursor: { type: "string", description: "Cursor from a previous response" }
+      },
+      required: ["boardId"]
+    },
+    handler: async (args) => {
+      const params = new URLSearchParams();
+      if (typeof args.list === "string" && args.list)
+        params.set("list", args.list);
+      if (typeof args.assignee === "string" && args.assignee)
+        params.set("assignee", args.assignee);
+      if (Array.isArray(args.fields) && args.fields.length > 0)
+        params.set("fields", args.fields.join(","));
+      if (typeof args.limit === "number")
+        params.set("limit", String(args.limit));
+      if (typeof args.cursor === "string" && args.cursor)
+        params.set("cursor", args.cursor);
+      const qs = params.toString();
+      return api(`/api/boards/${args.boardId}/cards${qs ? `?${qs}` : ""}`);
+    }
+  },
   {
     name: "smash_set_assignees",
     description: "Set or clear a card's assignees (humans + external agents listed together). Pass assignees=null to clear. Each entry: {kind: 'human'|'agent', id: string, display_name: string, avatar_emoji?: string}. Extra keys are accepted for forward-compat.",
@@ -15753,7 +15788,7 @@ var tools = [
   },
   {
     name: "smash_delete_card",
-    description: "Soft-delete a card.",
+    description: "Archive a card (soft delete). It leaves the board but is kept: it shows up in the space's archived column and smash_restore_card puts it back. Nothing is destroyed here \u2014 smash_permanently_delete_card is the irreversible one.",
     inputSchema: {
       type: "object",
       properties: { cardId: { type: "string" } },
@@ -15761,26 +15796,64 @@ var tools = [
     },
     handler: async (args) => {
       await api(`/api/cards/${args.cardId}`, { method: "DELETE" });
-      return { ok: true };
+      return {
+        ok: true,
+        archived: true,
+        note: `Archived, not destroyed. Restore with smash_restore_card({cardId: "${args.cardId}"}), or find it in the space's \u5B8C\u4E86\u6E08\u307F / Archive column.`
+      };
     }
   },
   {
     name: "smash_add_comment",
-    description: "Add a comment to a card. Markdown is supported.",
+    description: "Add a comment to a card. Markdown is supported. Use `recipients` to address the comment to specific assignee ids (the same ids as smash_set_assignees), so the addressee can poll just its own messages with smash_list_new_comments. Agent-to-agent hand-offs belong on the card they are about \u2014 there is no separate channel, which keeps the exchange attached to the work.",
     inputSchema: {
       type: "object",
       properties: {
         cardId: { type: "string" },
         body: { type: "string" },
-        authorName: { type: "string" }
+        authorName: { type: "string" },
+        recipients: {
+          type: "array",
+          items: { type: "string" },
+          description: "Assignee ids this comment is addressed to (e.g. ['claude-code'])"
+        }
       },
       required: ["cardId", "body"]
     },
     handler: async (args) => api(`/api/cards/${args.cardId}/comments`, {
       method: "POST",
-      body: JSON.stringify({ body: args.body, authorName: args.authorName })
+      body: JSON.stringify({
+        body: args.body,
+        authorName: args.authorName,
+        ...Array.isArray(args.recipients) && args.recipients.length > 0 ? { recipients: args.recipients } : {}
+      })
     })
   },
+  {
+    name: "smash_list_new_comments",
+    description: "Read comments across a whole board in created order \u2014 an agent inbox. Pass `since` (an ISO timestamp, exclusive) to get only what you have not seen, and `to` to keep just the comments addressed to you. The result carries a `cursor`; store it and pass it as the next `since`. Prefer this over re-reading the board: it is one request and returns only new messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        boardId: { type: "string" },
+        since: { type: "string", description: "ISO timestamp; returns comments created after it" },
+        to: { type: "string", description: "Only comments addressed to this assignee id" },
+        limit: { type: "number", description: "Max comments to read (default 100, max 500)" }
+      },
+      required: ["boardId"]
+    },
+    handler: async (args) => {
+      const params = new URLSearchParams();
+      if (typeof args.since === "string" && args.since)
+        params.set("since", args.since);
+      if (typeof args.to === "string" && args.to)
+        params.set("to", args.to);
+      if (typeof args.limit === "number")
+        params.set("limit", String(args.limit));
+      const qs = params.toString();
+      return api(`/api/boards/${args.boardId}/comments${qs ? `?${qs}` : ""}`);
+    }
+  },
   {
     name: "smash_add_checklist_item",
     description: "Add a checklist item to a card.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smashspace",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "SmashSpace CLI + MCP — operate SmashSpace boards from your terminal, Claude Code, Cursor, and Codex.",
   "type": "module",
   "bin": {