trelly 0.1.1 → 0.2.1

package/skills/trelly/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: trelly
+description: >-
+  Operate the trelly Trello CLI (npm trelly; bins trelly/trello): auth setup/login,
+  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
+
+Fast Trello CLI (`npm install -g trelly`). **Human Trello-styled output by default**;
+**`--json` for scripts**. Commands: **`trelly`** or **`trello`** (same binary).
+
+## Prerequisites
+
+```bash
+npm install -g trelly
+trelly auth setup    # once: API key from https://trello.com/power-ups/admin
+trelly auth login    # browser Allow → saves token
+```
+
+From source: clone [brandonkramer/trelly](https://github.com/brandonkramer/trelly),
+`bun install`, then `./bin/trelly auth setup`.
+
+Auth notes (common confusion):
+
+- Power-Up admin is **developer registration**, not installing a Power-Up on a board.
+- Pick any workspace you **admin** (personal is fine) — does not limit which boards you can use.
+- After login the CLI is **you** on Trello (member permissions, not board admin).
+
+Credentials: `~/.config/trelly/config.json` (migrates from `~/.config/trello-cli/`; never read/log/commit).
+
+## Output contract
+
+| Goal | Flags |
+|------|--------|
+| Human (default) | *(none)* |
+| JSON envelope | `--json` → `{ ok, profile, data }` or `{ ok: false, error, ... }` |
+| Pretty JSON | `--json --pretty` |
+
+- **Scripts:** always `--json` if parsing stdout.
+- **`--pretty` alone** does not emit JSON; it only indents `--json` output.
+- Errors: red `✗` in human mode; exit code `1`.
+
+## Common commands
+
+```bash
+trelly boards list
+trelly --json boards list | jq '.data[].name'
+trelly boards lists BOARD_ID
+trelly boards cards BOARD_ID          # or: api GET /boards/{id}/cards
+trelly lists cards LIST_ID
+trelly cards get CARD_ID --fields name,desc
+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
+```
+
+Global: `-p, --profile <name>` (or `TRELLO_PROFILE`).
+
+## Raw API escape hatch
+
+```bash
+trelly api -X GET --path /members/me
+trelly api -X PUT --path /cards/CARD_ID --query idList=LIST_ID
+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
+trelly api -X PUT \
+  --path "/cards/CARD_ID/customField/FIELD_ID/item" \
+  --body '{"idValue":"OPTION_ID"}'
+```
+
+## Safety
+
+| Action | CLI | Reversible? |
+|--------|-----|-------------|
+| Close | `cards archive`, `boards archive` | Yes (Trello UI) |
+| Destroy | `cards delete`, `boards delete` | **No** |
+
+Prefer **archive** unless the user explicitly wants permanent deletion.
+
+## Multi-profile
+
+```bash
+trelly auth login --profile work
+trelly -p work boards list
+```
+
+Env override: `TRELLO_APP_API_KEY`, `TRELLO_API_KEY`, `TRELLO_TOKEN`, `TRELLO_PROFILE`.
+
+## MCP vs CLI
+
+- **CLI:** human or `--json` on stdout.
+- **MCP:** separate stdio server (`trelly-mcp`) — see **trelly-mcp** skill.

package/skills/trelly-mcp/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: trelly-mcp
+description: >-
+  Configure and use the trelly MCP stdio server (trello_boards_list,
+  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
+
+MCP server for Trello (npm package **trelly**, bin **`trelly-mcp`**). Returns JSON
+envelope on every tool: `{ ok, profile, data }` /
+`{ ok: false, error, status?, details? }`. Never uses CLI human/Ink output.
+
+## Setup
+
+### 1. Auth (CLI, once)
+
+```bash
+trelly auth setup
+trelly auth login
+trelly auth list
+```
+
+### 2. Cursor — plugin or `~/.cursor/mcp.json`
+
+**Plugin (skills + MCP):** after `npm install -g trelly`:
+
+```bash
+cp -R "$(npm root -g)/trelly" ~/.cursor/plugins/local/trelly
+# or from clone: ./bin/install-cursor-plugin-local.sh
+```
+
+**MCP only** — `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trelly": {
+      "command": "trelly-mcp",
+      "env": {
+        "TRELLO_PROFILE": "default"
+      }
+    }
+  }
+}
+```
+
+See [mcp.example.json](../../mcp.example.json).
+
+### 3. Restart the IDE
+
+Reload MCP servers after editing config.
+
+### 4. Smoke test (optional)
+
+```bash
+cd trello-cli && bun run mcp
+```
+
+Starts stdio MCP manually (IDE normally launches `trelly-mcp` itself).
+
+## Using tools
+
+- Pass **`profile`** on any tool for a non-default account (or set `TRELLO_PROFILE` in env).
+- Read **`ok`** before using **`data`**.
+- Prefer **`trello_card_archive`** / **`trello_board_archive`** to close items.
+- **`trello_card_delete`** is **permanent** — no MCP board-delete tool.
+
+## Tool catalog
+
+| Tool | Purpose |
+|------|---------|
+| `trello_profiles_list` | Saved profiles + default |
+| `trello_member_me` | Authenticated member |
+| `trello_boards_list` | Member boards (`filter`, `fields`) |
+| `trello_board_get` | Board by id |
+| `trello_board_create` | Create board |
+| `trello_board_archive` | Close board (reversible) |
+| `trello_board_lists` | Lists on board |
+| `trello_board_cards` | All cards on board |
+| `trello_list_create` | Create list |
+| `trello_list_cards` | Cards in list |
+| `trello_card_get` | Card (`fields` optional) |
+| `trello_card_create` | Create card on list |
+| `trello_card_update` | Update card fields map |
+| `trello_card_move` | Move to another list |
+| `trello_card_comments` | List comments |
+| `trello_card_comment` | Add comment |
+| `trello_card_archive` | Close card (reversible) |
+| `trello_card_delete` | **Permanent** delete |
+| `trello_checklist_create` | Checklist on card |
+| `trello_checklist_add_item` | Checklist item |
+| `trello_label_create` | Board label |
+| `trello_card_add_label` | Label on card |
+| `trello_search` | Search Trello |
+| `trello_webhooks_list` | Token webhooks |
+| `trello_webhook_create` | Create webhook |
+| `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 |
+|---------|---------|
+| IDE agent managing Trello in chat | Terminal, shell scripts, jq pipelines |
+| Structured tool calls with schemas | `trello ui` interactive board |
+| Cursor/Codex/Claude with MCP wired | CI with `--json` |
+
+For terminal work, invoke the **trelly** skill instead.
+
+## Extending
+
+New tools: `src/mcp/tools/` — zod input, envelope `outputSchema`,
+`readOnlyHint` / `destructiveHint`. See [AGENTS.md](../../AGENTS.md).

package/src/api/client.ts

@@ -28,7 +28,7 @@ export class TrelloClient {
     method: string,
     path: string,
     query: Query = {},
-    body?: JsonValue,
+    body?: JsonValue | FormData,
   ): Promise<T> {
     const url = new URL(`${this.base}${path.startsWith("/") ? path : `/${path}`}`);
 
@@ -43,7 +43,9 @@ export class TrelloClient {
     };
 
     const init: RequestInit = { method, headers };
-    if (body !== undefined) {
+    if (body instanceof FormData) {
+      init.body = body; // fetch sets the multipart boundary
+    } else if (body !== undefined) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(body);
     }
@@ -63,7 +65,11 @@ export class TrelloClient {
     return this.request("GET", path, query);
   }
 
-  post<T = JsonValue>(path: string, query?: Query, body?: JsonValue): Promise<T> {
+  post<T = JsonValue>(
+    path: string,
+    query?: Query,
+    body?: JsonValue | FormData,
+  ): Promise<T> {
     return this.request("POST", path, query, body);
   }
 
@@ -218,6 +224,15 @@ export class TrelloClient {
     return this.post(`/cards/${id}/attachments`, query);
   }
 
+  /** Upload a local file as a card attachment (multipart). */
+  cardUploadAttachment(id: string, form: FormData) {
+    return this.post(`/cards/${id}/attachments`, {}, form);
+  }
+
+  cardDeleteAttachment(id: string, attachmentId: string) {
+    return this.delete(`/cards/${id}/attachments/${attachmentId}`);
+  }
+
   cardCustomFieldItems(id: string) {
     return this.get(`/cards/${id}/customFieldItems`);
   }

package/src/cli/commands/boards.ts

@@ -71,7 +71,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("archive <id>")
     .description("Close (archive) a board — reversible in Trello UI")
-    .action((id, cmd) =>
+    .action((id, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardArchive(id);
@@ -81,7 +81,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("delete <id>")
     .description("Permanently delete a board — irreversible")
-    .action((id, cmd) =>
+    .action((id, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardDelete(id);
@@ -102,7 +102,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("cards <boardId>")
     .description("List cards on a board")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardCards(boardId);
@@ -112,7 +112,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("labels <boardId>")
     .description("List labels on a board")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardLabels(boardId);
@@ -122,7 +122,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("members <boardId>")
     .description("List board members")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardMembers(boardId);
@@ -143,7 +143,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("custom-fields <boardId>")
     .description("List custom field definitions")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardCustomFields(boardId);

package/src/cli/commands/cards.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+import { attachmentForm } from "../../util/attachment.ts";
 import { getClient, parseJsonFlag, parseKvPairs } from "../context.ts";
 import { rootOpts, run } from "./run.ts";
 
@@ -176,15 +177,32 @@ export function registerCardCommands(program: Command): void {
 
   cards
     .command("add-attachment <id>")
-    .requiredOption("--url <url>", "Attachment URL")
+    .option("--url <url>", "Attachment URL")
+    .option("--file <path>", "Local file to upload")
     .option("--name <name>", "Attachment name")
     .action((id, opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
+        if (!opts.url === !opts.file) {
+          throw new Error("Pass exactly one of --url or --file");
+        }
+        if (opts.file) {
+          return client.cardUploadAttachment(id, attachmentForm(opts.file, opts.name));
+        }
         return client.cardAddAttachment(id, { url: opts.url, name: opts.name });
       }),
     );
 
+  cards
+    .command("delete-attachment <id> <attachmentId>")
+    .description("Delete an attachment from a card")
+    .action((id, attachmentId, _opts, cmd) =>
+      run(cmd, async () => {
+        const { client } = getClient(rootOpts(cmd).profile);
+        return client.cardDeleteAttachment(id, attachmentId);
+      }),
+    );
+
   cards.command("custom-fields <id>").action((id, _opts, cmd) =>
     run(cmd, async () => {
       const { client } = getClient(rootOpts(cmd).profile);