trelly 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trelly",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "trelly — fast Trello CLI with multi-profile auth, MCP server, and kanban TUI",
   "type": "module",
   "license": "MIT",

package/skills/README.md

@@ -6,8 +6,8 @@ developing this repo.
 
 | Skill | Use when |
 |-------|----------|
-| [trelly](trelly/SKILL.md) | Terminal / bash: `trelly boards list`, auth, `--json` |
-| [trelly-mcp](trelly-mcp/SKILL.md) | IDE agent with MCP wired: tool names, envelopes, safety |
+| [trelly](trelly/SKILL.md) | Terminal / bash: `trelly boards list`, auth, attachments, GitHub PR/commit links, `--json` |
+| [trelly-mcp](trelly-mcp/SKILL.md) | IDE agent with MCP wired: tool names, GitHub links via `trello_api`, envelopes, safety |
 
 **One copy of the content:** `skills/trelly/` and `skills/trelly-mcp/` in the installed
 package. Plugins and Pi load from there — you don't maintain separate copies.

package/skills/trelly/SKILL.md

@@ -2,9 +2,9 @@
 name: trelly
 description: >-
   Operate the trelly Trello CLI (npm trelly; bins trelly/trello): auth setup/login,
-  human vs --json output, boards/lists/cards, search, trello ui, trello api. Use when
-  the user asks to run trelly/trello commands, script Trello from the terminal, or
-  automate Trello with trelly.
+  human vs --json output, boards/lists/cards, search, attachments, GitHub PR/commit
+  links on cards, trello ui, trello api. Use when the user asks to run trelly/trello
+  commands, link a GitHub PR or commit to a Trello card, or automate Trello with trelly.
 ---
 
 # trelly
@@ -40,6 +40,8 @@ Credentials: `~/.config/trelly/config.json` (migrates from `~/.config/trello-cli
 | Pretty JSON | `--json --pretty` |
 
 - **Scripts:** always `--json` if parsing stdout.
+- **Token cost:** raw `--json` returns full Trello objects (a board list ≈ 10k tokens) — trim with `jq` (e.g. `| jq '.data[] | {id,name}'`) or request fewer fields (`--fields`, `--query "fields=id,name"`).
+- **Showing cards to a human?** Render one markdown line per card: `[name](shortUrl)` + non-zero badges `💬 n · 📎 n · ✓ x/y · ⏰ due` + labels as colored dots (red 🔴 orange 🟠 yellow 🟡 green 🟢 blue 🔵 purple 🟣). Slim the JSON first: `jq '.data[] | {name, shortUrl, labels: [.labels[] | {name, color}], badges: {comments: .badges.comments, attachments: .badges.attachments, checkItems: .badges.checkItems, checkItemsChecked: .badges.checkItemsChecked}, due, dueComplete}'`.
 - **`--pretty` alone** does not emit JSON; it only indents `--json` output.
 - Errors: red `✗` in human mode; exit code `1`.
 
@@ -56,6 +58,8 @@ trelly cards comments CARD_ID
 trelly cards create --list LIST_ID --name "Task"
 trelly cards move CARD_ID --list OTHER_LIST_ID
 trelly cards comment CARD_ID --text "Done"
+trelly cards attachments CARD_ID
+trelly cards add-attachment CARD_ID --url "https://github.com/org/repo/pull/42"
 trelly search "query"
 trelly ui BOARD_ID                    # interactive kanban (TTY required)
 trelly auth list
@@ -73,6 +77,89 @@ trelly api -X POST --path /cards --body '{"idList":"LIST_ID","name":"Hi"}'
 
 Request body flag is **`--body`** (not `--json` — that flag is global output).
 
+## Card attachments
+
+```bash
+trelly cards attachments CARD_ID
+trelly cards add-attachment CARD_ID --url "https://…" [--name "label"]
+trelly cards add-attachment CARD_ID --file ./screenshot.png [--name "label"]
+trelly cards delete-attachment CARD_ID ATTACHMENT_ID
+```
+
+Pass **exactly one** of `--url` or `--file`. In `trelly ui`, open a card's detail (**⏎**), then **a** opens the attach prompt (URL or local path).
+
+## GitHub PR / commit on a card
+
+Boards with the **GitHub Power-Up** enabled can show rich PR metadata in the Trello UI.
+trelly attaches the same underlying **URL attachment** — it does **not** drive the
+Power-Up picker or OAuth flow.
+
+### Link a PR or commit (preferred)
+
+```bash
+# Pull request — set --name so the attachment is scannable in lists/UI
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/pull/197" \
+  --name "#197 fix(pre-existing-tests-and-types)"
+
+# Commit
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/commit/2d856ea" \
+  --name "2d856ea Merge PR #197"
+
+# Issue (same mechanism)
+trelly cards add-attachment CARD_ID \
+  --url "https://github.com/PangoliaDev/dogster/issues/42"
+```
+
+Accepted URL shapes: `…/pull/N`, `…/commit/SHA`, `…/issues/N`, `…/tree/branch`.
+Use the canonical `https://github.com/…` URL (no `/files` or `/commits` tab suffix).
+
+### Power-Up UI vs trelly URL attachment
+
+| Feature | GitHub Power-Up (Trello UI) | `cards add-attachment --url` |
+|--------|-----------------------------|------------------------------|
+| Link on card | Yes | Yes |
+| Readable `--name` / PR title | Yes (auto) | Set `--name` yourself (recommended) |
+| CI/check badges on card front | Yes | No |
+| Pick PR from repo browser | Yes | No — pass URL |
+| Comment back on GitHub PR | Yes (optional setting) | No |
+
+If the user needs badges or GitHub-side back-links, attach via **Power-Ups → GitHub**
+in Trello. For agent/CLI workflows (ship PR → link card → move list), URL attachment
+is enough.
+
+### Agent workflow patterns
+
+**After opening or merging a PR** — attach and optionally move the card:
+
+```bash
+CARD_ID=…
+PR_URL="https://github.com/PangoliaDev/dogster/pull/197"
+trelly cards add-attachment "$CARD_ID" --url "$PR_URL" --name "#197 fix scope"
+trelly cards move "$CARD_ID" --list PENDING_REVIEW_LIST_ID
+```
+
+**Fallback — comment only** (visible in activity, not Attachments):
+
+```bash
+trelly cards comment CARD_ID --text "PR: https://github.com/org/repo/pull/42"
+```
+
+**Inspect what's linked:**
+
+```bash
+trelly --json cards attachments CARD_ID | jq '.data[] | {name, url}'
+```
+
+### Raw API (same as CLI)
+
+```bash
+trelly api -X POST --path "/cards/CARD_ID/attachments" \
+  --query "url=https://github.com/org/repo/pull/42" \
+  --query "name=#42 feature title"
+```
+
 ## Custom fields (list-type)
 
 ```bash

package/skills/trelly-mcp/SKILL.md

@@ -2,8 +2,8 @@
 name: trelly-mcp
 description: >-
   Configure and use the trelly MCP stdio server (trello_boards_list,
-  trello_card_create, trello_search, etc.). Use when wiring Cursor/Claude MCP,
-  calling Trello from an IDE agent, or choosing between MCP tools vs trelly CLI.
+  trello_card_create, trello_search, trello_api, etc.). Use when wiring Cursor/Claude
+  MCP, linking GitHub PRs/commits to Trello cards from an agent, or choosing MCP vs CLI.
 ---
 
 # trelly-mcp
@@ -12,6 +12,28 @@ MCP server for Trello (npm package **trelly**, bin **`trelly-mcp`**). Returns JS
 envelope on every tool: `{ ok, profile, data }` /
 `{ ok: false, error, status?, details? }`. Never uses CLI human/Ink output.
 
+List/get tools default to lean `fields` (id, name, url, due, …) to keep responses
+token-cheap; pass `fields: "all"` or a comma list when you need more.
+`trello_list_cards` and `trello_card_get` also include slim `badges`
+(comments/attachments/checkItems counts) and `labels` for rich rendering.
+
+## Rendering card lists for humans
+
+When the user asks to **see** cards (not automation), render one markdown line per
+card — title linked to the card, then only the badges that are non-zero:
+
+```
+1. [Publish module behavior](https://trello.com/c/1jH2UTAu) 🔴 `Priority: Highest` · 💬 4 · 📎 2 · ✓ 2/5 · ⏰ Jul 5
+```
+
+- Title → `[name](shortUrl)`. Counts from `badges`: 💬 comments · 📎 attachments · ✓ checkItemsChecked/checkItems.
+- Due: `⏰ Jul 5`, add `(overdue)` if past and not `dueComplete`; `✓` if complete.
+- Labels: colored dot + name in backticks. Trello color → emoji: red 🔴 · orange 🟠 · yellow 🟡 · green/lime 🟢 · blue/sky 🔵 · purple/pink 🟣 · black ⚫ · none ⚪.
+- Whole board: add `fields: "…,badges,labels"` to `trello_board_cards` (lean by default).
+- Custom-field chips (e.g. `Priority: Highest`): fetch defs once via `trello_api` GET
+  `/boards/{boardId}/customFields`, request `customFieldItems` on cards, match
+  `idValue` → option text/color. Skip unless the user wants them — it's an extra call.
+
 ## Setup
 
 ### 1. Auth (CLI, once)
@@ -99,6 +121,66 @@ Starts stdio MCP manually (IDE normally launches `trelly-mcp` itself).
 | `trello_webhook_delete` | Delete webhook |
 | `trello_api` | Raw REST (`method`, `path`, `query`, `body`) |
 
+There is **no dedicated attachment MCP tool** yet — use `trello_api` or the CLI
+`cards add-attachment` (see **trelly** skill).
+
+## GitHub PR / commit on a card (MCP)
+
+Boards with the **GitHub Power-Up** show rich PR UI when attached through Trello.
+Agents link the same way via **`trello_api`** — a URL attachment, not the Power-Up
+OAuth picker.
+
+### Attach PR or commit
+
+```
+trello_api
+  method: POST
+  path: /cards/{cardId}/attachments
+  query: { "url": "https://github.com/org/repo/pull/42", "name": "#42 feature title" }
+```
+
+Commit:
+
+```
+query: { "url": "https://github.com/org/repo/commit/abc1234", "name": "abc1234 message" }
+```
+
+Always set **`name`** to something scannable (`#N title` or short SHA + subject).
+
+### List or remove attachments
+
+```
+trello_api  GET   /cards/{cardId}/attachments
+trello_api  DELETE /cards/{cardId}/attachments/{attachmentId}
+```
+
+### Comment fallback
+
+```
+trello_card_comment  cardId  text: "PR: https://github.com/org/repo/pull/42"
+```
+
+Comments appear in card activity; they are **not** Attachments.
+
+### Power-Up vs MCP/API
+
+| Feature | GitHub Power-Up (UI) | `trello_api` URL attachment |
+|--------|----------------------|-----------------------------|
+| Link on card | Yes | Yes |
+| PR title / custom name | Auto | Set `name` in query |
+| CI badges on card front | Yes | No |
+| GitHub PR back-link comment | Yes (optional) | No |
+
+Use the Power-Up UI when the user needs badges or GitHub-side comments. For
+agent workflows (link PR after push, move card to review), POST the GitHub URL.
+
+### Typical agent sequence
+
+1. `trello_search` or `trello_list_cards` — find the card
+2. `trello_api` POST `/cards/{id}/attachments` with PR URL + name
+3. `trello_card_move` — e.g. To do → Pending review
+4. Optional: `trello_card_comment` with the same PR URL
+
 ## When to use MCP vs CLI
 
 | Use MCP | Use CLI |

package/src/mcp/handlers.ts

@@ -19,11 +19,49 @@ export const profileField = z.string().optional().describe("Auth profile name");
 export function toolResult(envelope: ToolEnvelope): CallToolResult {
   return {
     structuredContent: envelope,
-    content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(envelope) }],
     isError: envelope.ok === false,
   };
 }
 
+// Trello's badges object is ~400 chars of mostly unused keys; keep the 4 that matter.
+const BADGE_KEYS = ["comments", "attachments", "checkItems", "checkItemsChecked"];
+
+function slimCard(card: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...card };
+  if (out.badges && typeof out.badges === "object" && !Array.isArray(out.badges)) {
+    const badges = out.badges as Record<string, unknown>;
+    out.badges = Object.fromEntries(
+      BADGE_KEYS.filter((key) => badges[key] !== undefined).map((key) => [
+        key,
+        badges[key],
+      ]),
+    );
+  }
+  if (Array.isArray(out.labels)) {
+    out.labels = out.labels.map((label) => {
+      const { id, name, color } = label as Record<string, unknown>;
+      return { id, name, color };
+    });
+  }
+  return out;
+}
+
+/** Slim badges/labels on a card or card array returned by Trello. */
+export function slimCards(data: unknown): unknown {
+  if (Array.isArray(data)) {
+    return data.map((item) =>
+      item && typeof item === "object"
+        ? slimCard(item as Record<string, unknown>)
+        : item,
+    );
+  }
+  if (data && typeof data === "object") {
+    return slimCard(data as Record<string, unknown>);
+  }
+  return data;
+}
+
 export async function withClient<T>(
   profile: string | undefined,
   fn: (client: TrelloClient, profileName: string) => Promise<T>,

package/src/mcp/tools/boards.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  slimCards,
+  toolEnvelopeSchema,
+  withClient,
+} from "../handlers.ts";
 
 export function registerBoardTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -25,7 +30,10 @@ export function registerBoardTools(server: McpServer): void {
           ])
           .optional()
           .default("open"),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,shortUrl,closed")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
@@ -41,7 +49,10 @@ export function registerBoardTools(server: McpServer): void {
       inputSchema: {
         profile: profileField,
         boardId: z.string().min(1),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,desc,shortUrl,closed")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
@@ -94,23 +105,38 @@ export function registerBoardTools(server: McpServer): void {
         profile: profileField,
         boardId: z.string().min(1),
         filter: z.string().optional().default("open"),
+        fields: z
+          .string()
+          .default("id,name,closed,pos")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, boardId, filter }) =>
-      withClient(profile, (client) => client.boardLists(boardId, { filter })),
+    async ({ profile, boardId, filter, fields }) =>
+      withClient(profile, (client) => client.boardLists(boardId, { filter, fields })),
   );
 
   server.registerTool(
     "trello_board_cards",
     {
       description: "List all cards on a board.",
-      inputSchema: { profile: profileField, boardId: z.string().min(1) },
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        fields: z
+          .string()
+          .default("id,name,idList,due,dueComplete,shortUrl,closed")
+          .describe(
+            'comma-separated fields, "all" for everything; add "badges,labels" for rich lists',
+          ),
+      },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, boardId }) =>
-      withClient(profile, (client) => client.boardCards(boardId)),
+    async ({ profile, boardId, fields }) =>
+      withClient(profile, async (client) =>
+        slimCards(await client.boardCards(boardId, { fields })),
+      ),
   );
 }

package/src/mcp/tools/cards.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  slimCards,
+  toolEnvelopeSchema,
+  withClient,
+} from "../handlers.ts";
 
 export function registerCardTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -12,13 +17,18 @@ export function registerCardTools(server: McpServer): void {
       inputSchema: {
         profile: profileField,
         cardId: z.string().min(1),
-        fields: z.string().optional(),
+        fields: z
+          .string()
+          .default("id,name,desc,due,dueComplete,idList,shortUrl,labels,badges")
+          .describe('comma-separated fields, "all" for everything'),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
     async ({ profile, cardId, fields }) =>
-      withClient(profile, (client) => client.cardGet(cardId, { fields })),
+      withClient(profile, async (client) =>
+        slimCards(await client.cardGet(cardId, { fields })),
+      ),
   );
 
   server.registerTool(

package/src/mcp/tools/lists.ts

@@ -1,6 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+import {
+  profileField,
+  slimCards,
+  toolEnvelopeSchema,
+  withClient,
+} from "../handlers.ts";
 
 export function registerListTools(server: McpServer): void {
   const outputSchema = toolEnvelopeSchema;
@@ -27,11 +32,20 @@ export function registerListTools(server: McpServer): void {
     "trello_list_cards",
     {
       description: "List cards in a list.",
-      inputSchema: { profile: profileField, listId: z.string().min(1) },
+      inputSchema: {
+        profile: profileField,
+        listId: z.string().min(1),
+        fields: z
+          .string()
+          .default("id,name,idList,due,dueComplete,shortUrl,closed,badges,labels")
+          .describe('comma-separated fields, "all" for everything'),
+      },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, listId }) =>
-      withClient(profile, (client) => client.listCards(listId)),
+    async ({ profile, listId, fields }) =>
+      withClient(profile, async (client) =>
+        slimCards(await client.listCards(listId, { fields })),
+      ),
   );
 }

package/src/mcp/tools/search.ts

@@ -15,16 +15,28 @@ export function registerSearchTools(server: McpServer): void {
         modelTypes: z.string().optional(),
         cardsLimit: z.number().int().positive().optional(),
         boardsLimit: z.number().int().positive().optional(),
+        cardFields: z.string().default("id,name,idList,shortUrl"),
+        boardFields: z.string().default("id,name,shortUrl"),
       },
       annotations: { readOnlyHint: true },
       outputSchema,
     },
-    async ({ profile, query, modelTypes, cardsLimit, boardsLimit }) =>
+    async ({
+      profile,
+      query,
+      modelTypes,
+      cardsLimit,
+      boardsLimit,
+      cardFields,
+      boardFields,
+    }) =>
       withClient(profile, (client) =>
         client.search(query, {
           modelTypes,
           cards_limit: cardsLimit,
           boards_limit: boardsLimit,
+          card_fields: cardFields,
+          board_fields: boardFields,
         }),
       ),
   );