@omnicoreos/planka-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # planka-mcp
 
-Control a Planka 2.x board from Claude Code through 24 MCP tools.
+Control a Planka 2.x board from Claude Code through 41 MCP tools.
 Writes are re-read and verified, so a reported success matches the board.
 An optional workflow turns that board into durable memory for agent work.
 
@@ -30,53 +30,88 @@ Claude Code loads MCP servers when a session starts, so restart it after setup o
 
 ## Requirements
 
-- Node.js 18 or newer and `npm`
+- Node.js 18 or newer and `npx`
 - A reachable Planka 2.x instance
 - A dedicated Planka user that can see the target project and board
-- Claude Code installed and available as `claude`
+- One MCP client: Claude Code, Codex CLI, Cursor or VS Code
 - A project-manager role only if setup must create a board
 
 Linux and macOS are supported. No Bun runtime is required.
 
-## Install in 5 minutes
+## Install
 
-Clone the repository and run the guided installer:
+One command per client. All of them run the published package with `npx`, so
+there is nothing to clone and nothing to build.
+
+| Client | One-liner |
+|---|---|
+| **Claude Code** (plugin: MCP + skills + preflight) | `/plugin marketplace add omnicoreos/planka-mcp` then `/plugin install planka@planka-mcp` |
+| **Claude Code** (server only) | `claude mcp add --scope user --transport stdio planka --env PLANKA_BASE_URL=https://planka.example.com --env PLANKA_API_KEY=<key> -- npx -y @omnicoreos/planka-mcp` |
+| **Codex CLI** | `codex mcp add planka -- npx -y @omnicoreos/planka-mcp` (then add the `env` block, below) |
+| **Cursor** | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=planka&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvbW5pY29yZW9zL3BsYW5rYS1tY3AiXSwiZW52Ijp7IlBMQU5LQV9CQVNFX1VSTCI6Imh0dHBzOi8vcGxhbmthLmV4YW1wbGUuY29tIiwiUExBTktBX0FQSV9LRVkiOiI8eW91ci1wbGFua2EtYXBpLWtleT4ifX0=) |
+| **VS Code** | [![Add to VS Code](https://img.shields.io/badge/VS_Code-Add_planka-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=planka&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40omnicoreos%2Fplanka-mcp%22%5D%2C%22env%22%3A%7B%22PLANKA_BASE_URL%22%3A%22https%3A%2F%2Fplanka.example.com%22%2C%22PLANKA_API_KEY%22%3A%22%3Cyour-planka-api-key%3E%22%7D%2C%22type%22%3A%22stdio%22%7D) |
+| **Any of them, guided** | `npx @omnicoreos/planka-mcp init --client claude\|codex\|cursor\|vscode\|print` |
+
+The Cursor and VS Code links carry a placeholder key, never a real one: a
+deeplink ends up in browser history. Both clients ask for the credential
+themselves — VS Code through a `promptString` input, so the committed
+`.vscode/mcp.json` holds no secret.
+
+### `planka-mcp init`
 
 ```bash
-git clone https://github.com/omnicoreos/planka-mcp.git
-cd planka-mcp
-./scripts/setup.sh
+npx @omnicoreos/planka-mcp init --client claude     # claude mcp add, user scope
+npx @omnicoreos/planka-mcp init --client codex      # appends to ~/.codex/config.toml
+npx @omnicoreos/planka-mcp init --client cursor     # merges ~/.cursor/mcp.json (0600) + prints the deeplink
+npx @omnicoreos/planka-mcp init --client vscode     # writes .vscode/mcp.json with a secret prompt
+npx @omnicoreos/planka-mcp init --client print      # prints every snippet, writes nothing
 ```
 
-Setup asks for the Planka URL, agent email or username, and password. It validates
-those credentials before writing configuration, lets you select or create a board,
-and then runs a real create/label/comment/delete smoke test.
+With a terminal attached it asks for what it needs; `--base-url`, `--api-key`,
+`--board`, `--email` and `--password` make it non-interactive. Before writing
+anything it runs one authenticated `GET /api/users/me`, which is what catches a
+base URL pointing at the SPA instead of the API, or a credential that never
+worked. `--dry-run` prints the exact change and touches nothing.
 
-It offers two Claude Code configurations:
+Every emitter merges: an existing `planka` entry is reported and left alone,
+and the other servers in the same file are preserved. Files written into your
+home directory get mode `0600`.
 
-| Choice | Use it when | Where it lives |
-|---|---|---|
-| `claude mcp add` | You want the easiest personal setup | Claude Code user configuration |
-| Project `.mcp.json` | A team should share the server entry | `<YOUR_PROJECT>/.mcp.json`, safe to commit |
+`./scripts/setup.sh` is an alias for `init --client claude`. The older guided
+installer — the one that also picks or creates a board and runs the full
+create/label/comment/delete smoke test — is still `node scripts/setup.mjs`.
 
-In both cases, setup stores credentials outside Git in
-`~/.config/planka-mcp/config.json` with mode `0600` and creates the private launcher
-`~/.local/bin/planka-mcp`. A generated team configuration contains no password:
+### The Claude Code plugin
 
-```json
-{
-  "mcpServers": {
-    "planka": {
-      "type": "stdio",
-      "command": "${HOME}/.local/bin/planka-mcp",
-      "args": []
-    }
-  }
-}
+The plugin installs the MCP server, the two workflow skills, and a `SessionStart`
+preflight that catches a missing credential or an `http://` base URL before the
+first tool call:
+
+```text
+/plugin marketplace add omnicoreos/planka-mcp
+/plugin install planka@planka-mcp
 ```
 
-The installer is safe to rerun. It updates the `planka` entry, reuses existing
-workflow lists and labels, and deletes its temporary smoke-test card.
+Claude Code asks for the base URL and the API key when the plugin is enabled and
+stores the key in the OS keychain, not in `settings.json`. Codex reads the same
+repository through `.codex-plugin/plugin.json` and
+`.agents/plugins/marketplace.json`.
+
+Plugins cannot ship permission rules, which is the one thing that does not
+travel: use `PLANKA_READ_ONLY` and `PLANKA_DISABLED_TOOLS` (below) instead of a
+client-side deny list — they work in every runtime and cost no context.
+
+### Codex `env` block
+
+`codex mcp add` does not take credentials, so add them to
+`~/.codex/config.toml` (or let `init --client codex` do it):
+
+```toml
+[mcp_servers.planka]
+command = "npx"
+args = ["-y", "@omnicoreos/planka-mcp"]
+env = { PLANKA_BASE_URL = "https://planka.example.com", PLANKA_API_KEY = "<key>" }
+```
 
 ## Verify it works
 
@@ -87,8 +122,11 @@ claude mcp list
 claude mcp get planka
 ```
 
-Then fully restart Claude Code. If you chose `.mcp.json`, open Claude Code in that
-project and approve the project-scoped server when prompted.
+Then fully restart Claude Code — MCP servers are loaded when a session starts. If
+you configured the server in a project's `.mcp.json`, open Claude Code in that
+project and approve the project-scoped server when prompted. If you installed the
+plugin, `/plugin` shows it, and its **Errors** tab shows a server that failed to
+start.
 
 Ask Claude Code:
 
@@ -100,7 +138,144 @@ Show me my Planka projects and boards. In the Pending list, create a card named
 If Claude cannot see the tools, restart first and then follow
 [Troubleshooting](docs/troubleshooting.md).
 
-## The 24 tools
+## Authentication
+
+Two ways to authenticate, and they are mutually exclusive: setting both is a
+configuration error, because Planka reads `Authorization` first and silently
+ignores `x-api-key` when both arrive.
+
+| | `PLANKA_API_KEY` (recommended) | `PLANKA_AGENT_EMAIL` + `PLANKA_AGENT_PASSWORD` |
+|---|---|---|
+| Sent as | `X-Api-Key: <prefix>_<secret>` on every request | `POST /api/access-tokens`, then `Authorization: Bearer` |
+| Login round-trip | none | one per session, refreshed every 25 minutes |
+| Sign-in rate limit | not subject to it | 10 logins per identity per 60 s — reached fast when several agents start at once |
+| Password on disk | none | yes, in the client's configuration file |
+| Attachment downloads | works | works |
+
+### Recipe: a scoped agent user with an API key
+
+Four steps, run by a Planka **admin**. The result is a user that can only ever
+see the boards you name — enforced by Planka itself, not by this server.
+
+1. **Create the user with the lowest global role.** In the Planka UI:
+   *Administration → Users → Add user*, role **`boardUser`**. A `boardUser`
+   cannot create projects and cannot grant itself memberships.
+
+2. **Give it membership on the boards it should work on**, and only those:
+
+   ```bash
+   curl -X POST "$PLANKA_URL/api/boards/<BOARD_ID>/board-memberships" \
+     -H "Authorization: Bearer $ADMIN_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"userId":"<USER_ID>","role":"editor"}'
+   ```
+
+   Use `"role":"viewer"` for an agent that should read and comment but never
+   create or move cards. `GET /api/projects` then returns only the projects
+   derived from these memberships; every other board answers 404.
+
+3. **Issue the API key** (admin-only endpoint). The key is shown **once**, in
+   `included.apiKey`; Planka stores only its hash and prefix:
+
+   ```bash
+   curl -X POST "$PLANKA_URL/api/users/<USER_ID>/api-key" \
+     -H "Authorization: Bearer $ADMIN_TOKEN"
+   ```
+
+4. **Configure the server with the key and nothing else.** Remove
+   `PLANKA_AGENT_EMAIL` and `PLANKA_AGENT_PASSWORD`:
+
+   ```json
+   {
+     "mcpServers": {
+       "planka": {
+         "command": "npx",
+         "args": ["-y", "@omnicoreos/planka-mcp"],
+         "env": {
+           "PLANKA_BASE_URL": "https://planka.example.com",
+           "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef"
+         }
+       }
+     }
+   }
+   ```
+
+Rotating a key is step 3 again: issuing a new one invalidates the old.
+
+## Scoping the server
+
+An API key inherits its user's permissions — it carries no scopes of its own.
+Scoping therefore happens in three layers, and each covers something the others
+cannot.
+
+```
+Layer 1 · PLANKA          the only layer an agent cannot talk its way around
+  boardUser + board memberships + the API key above
+  ⇒ everything outside the allowed boards is 404/403 at the API
+
+Layer 2 · THIS SERVER     ergonomics, and defence against the agent itself
+  the environment variables below; they travel with the package,
+  so Claude Code, Codex and Cursor all get the same rules
+
+Layer 3 · THE CLIENT      survives a downgrade of this package
+  .claude/settings.json deny/ask rules, Codex enabled_tools/disabled_tools
+```
+
+Layer 1 has real enforcement but cannot express "do not call `planka_get_board`,
+it costs forty times more context". Layer 2 can, and reaches every runtime.
+Layer 3 stays true even if this package is pinned back to an older version.
+
+### Layer 2: the environment variables
+
+| Variable | Value | What it does |
+|---|---|---|
+| `PLANKA_DEFAULT_BOARD_ID` | one board id | `boardId` becomes optional on every tool that takes one, and defaults to this board. Saves the `planka_get_structure` call an agent makes only to recover an id that never changes |
+| `PLANKA_ALLOWED_BOARD_IDS` | comma-separated board ids | Boards outside the list are filtered out of `planka_get_structure`, and any call naming one is refused before the request leaves the process |
+| `PLANKA_ALLOWED_PROJECT_IDS` | comma-separated project ids | Same, one level up |
+| `PLANKA_READ_ONLY` | `true` or `1` | The twenty-seven write tools disappear from `tools/list` and are refused if called anyway |
+| `PLANKA_HIDE_DEPRECATED` | `true` or `1` | Drops the seven deprecated tools (`manage_labels`, `manage_lists`, `manage_comment`, `add_comment`, `get_board`, `list_cards`, `list_lists`) from `tools/list`, saving ~6.8 kB of context. They stay callable, so a cached tool list still works |
+| `PLANKA_DISABLED_TOOLS` | comma-separated tool names | Switches individual tools off. The `planka_` prefix is optional: `get_board` and `planka_get_board` mean the same thing |
+| `PLANKA_PROTECTED_LIST_IDS` | comma-separated list ids | Refuses creating or moving cards **into** those lists, editing or deleting the lists themselves, and moving, archiving or deleting the cards **out of** them |
+| `PLANKA_SUMMARY_DECISION_LISTS` | comma-separated column names or ids | Which columns `planka_board_summary` returns cards from when the call does not say. Unset: it returns no cards, only the shape of the board |
+| `PLANKA_SUMMARY_HIGHLIGHT_LABEL` | one label name | The label that marks a card as unblocked in `planka_board_summary`. Unset: nothing is highlighted |
+| `PLANKA_MCP_PREFLIGHT` | `full` | Read by the plugin's SessionStart hook only: also spawn the server binary and wait for its stdio banner. Off by default, because on a cold cache it costs an `npx` download |
+| `PLANKA_MCP_COMMAND` | a command | Read by the same hook: the command to spawn instead of `npx -y @omnicoreos/planka-mcp` (a local checkout, a pinned binary) |
+
+**The server ships with no board vocabulary of its own.** Column names and
+"ready" labels are yours, in your language: the last two variables are how a
+deployment tells the summary what its board looks like. A hint that matches
+nothing comes back in `warnings`, never as an empty answer.
+
+```json
+"PLANKA_SUMMARY_DECISION_LISTS": "decision,probalo,miralo",
+"PLANKA_SUMMARY_HIGHLIGHT_LABEL": "decidido"
+```
+
+**Allowlists are by id, never by name.** Any board editor can rename a board, so
+a name-based allowlist is bypassed with one edit. Planka ids are stable.
+
+Two notes on what these are and are not:
+
+- `PLANKA_READ_ONLY` hides tools; it does not make the account read-only. Pair it
+  with `"role":"viewer"` in step 2 above if that is what you actually need.
+- `PLANKA_PROTECTED_LIST_IDS` is a guard-rail, not a permission: Planka has no
+  per-list rights. It is the right tool for "do not move cards to *Merged* on
+  your own", and the wrong one for anything security-critical.
+
+Example — an agent that reads one board and comments, and nothing else:
+
+```json
+"env": {
+  "PLANKA_BASE_URL": "https://planka.example.com",
+  "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef",
+  "PLANKA_DEFAULT_BOARD_ID": "1234567890123456789",
+  "PLANKA_ALLOWED_BOARD_IDS": "1234567890123456789",
+  "PLANKA_DISABLED_TOOLS": "get_board",
+  "PLANKA_PROTECTED_LIST_IDS": "9876543210987654321"
+}
+```
+
+## The 41 tools
 
 IDs are strings. Start with `planka_get_structure`, then use IDs returned by
 Planka; do not guess them.
@@ -108,41 +283,104 @@ Planka; do not guess them.
 | Tool | What it does |
 |---|---|
 | `planka_get_structure` | Lists visible projects, boards, and lists |
-| `planka_get_board` | Reads one board with its lists, cards, labels, and optional task counts |
-| `planka_list_lists` | Lists a board's columns with card counts, and no cards |
-| `planka_board_summary` | One-call briefing: columns, labels, and the cards waiting on a decision |
-| `planka_list_cards` | Reads one column, paginated, without descriptions by default |
-| `planka_find_cards` | Searches a board's cards by label, text, or column |
+| `planka_get_board` | **Deprecated.** Reads one board whole, up to `limit` cards |
+| `planka_board_summary` | One-call briefing: columns with counts, labels with ids, and optionally the cards of named columns |
+| `planka_find_cards` | The one read over cards: one column (`listId`), or a board searched by text, label or member |
+| `planka_list_lists` | **Deprecated.** Alias of `planka_board_summary` with `cardsFrom: []` |
+| `planka_list_cards` | **Deprecated.** Alias of `planka_find_cards` with `listId` |
 | `planka_create_card` | Creates a card and can attach tasks and labels |
-| `planka_get_card` | Reads complete card details |
+| `planka_get_card` | Card digest; `detail: "full"` and `withComments` on demand |
 | `planka_update_card` | Updates title, description, due date, or completion |
 | `planka_move_card` | Moves a card to another list or position |
 | `planka_delete_card` | Permanently deletes a card |
 | `planka_create_tasks` | Adds checklist tasks to a card |
 | `planka_update_task` | Renames or completes a task |
 | `planka_delete_task` | Deletes a task |
-| `planka_manage_labels` | Creates, updates, or deletes board labels |
+| `planka_create_label` | Creates a board label |
+| `planka_update_label` | Renames a label or changes its color |
+| `planka_delete_label` | Deletes a label from the board and from every card |
+| `planka_manage_labels` | **Deprecated.** Alias routing `action` to the three above |
 | `planka_set_card_labels` | Adds or removes labels and verifies the final state |
-| `planka_add_comment` | Adds a comment through Planka 2.x's dedicated endpoint |
-| `planka_get_comments` | Reads comments through the dedicated endpoint |
-| `planka_manage_comment` | Edits or deletes an existing comment |
-| `planka_manage_lists` | Creates, updates, or deletes board lists |
+| `planka_create_comment` | Adds a comment through Planka 2.x's dedicated endpoint |
+| `planka_get_comments` | Paginated comments (`limit`, `beforeId`, `all`) |
+| `planka_update_comment` | Rewrites an existing comment |
+| `planka_delete_comment` | Deletes a comment |
+| `planka_add_comment` | **Deprecated.** Alias of `planka_create_comment` |
+| `planka_manage_comment` | **Deprecated.** Alias routing `action` to update/delete |
+| `planka_create_list` | Creates a list (column) on a board |
+| `planka_update_list` | Renames, repositions or reclassifies a column |
+| `planka_delete_list` | Deletes a column **and every card in it** |
+| `planka_manage_lists` | **Deprecated.** Alias routing `action` to the three above |
 | `planka_add_attachment` | Uploads a local file to a card and verifies it landed |
 | `planka_get_attachments` | Lists a card's attachments with type, size, and download URL |
 | `planka_view_attachment` | Returns an attachment's content; images come back viewable |
 | `planka_delete_attachment` | Deletes an attachment |
-
-`planka_get_board` returns the entire board, which is often more than the
-question needs. The four scoped reads answer narrower questions and return far
-less text: measured on a board of 100 cards, `planka_list_lists` returned 39
-times less than `planka_get_board`, `planka_board_summary` 16 times less, and
-`planka_find_cards` between 18 and 56 times less depending on the filter. They
-also report `total`, `returned`, and `hasMore`, so a clipped answer never looks
-complete.
+| `planka_card_history` | One card's activity log as human lines: created, moved, assigned, tasks completed |
+| `planka_board_activity` | What moved on a board since a date, grouped by card |
+| `planka_set_card_members` | Assigns or unassigns people and verifies the final membership |
+| `planka_list_users` | The people who can be assigned, with a board-scoped fallback |
+| `planka_whoami` | This server's account, board role, Planka version and access policy |
+| `planka_duplicate_card` | Copies a card with its tasks, labels and members |
+| `planka_archive_card` | Archives a card into the board's hidden archive, or restores it |
+| `planka_move_list_cards` | Moves every card of one column into another, with counts |
+
+The reads follow one principle: **a small digest by default, the detail through
+parameters**. `planka_board_summary` opens a session in one call;
+`planka_find_cards` with a `listId` reads a whole column in ONE request through
+`GET /api/lists/:id`, so `total` is the real size of the column and the answer
+carries `truncated: false`; the same tool without a `listId` searches the board.
+Measured on the reference board of 185 cards, the deprecated `planka_get_board`
+went from 56,112 to 17,215 characters and `planka_get_structure`
+(`withLists: false`) from 696 to 203, while a 159-card column went from five
+requests to two. Every read reports `total`, `returned` and `hasMore`, so a
+clipped answer never looks complete, and every board-derived read carries
+`excludesArchived: true` because Planka keeps archive and trash out of the board
+read.
 
 Every input field and a complete payload for every tool are in
 [Tools reference](docs/tools.md).
 
+## What the client learns on connect
+
+The `initialize` handshake returns a short set of server instructions — how to
+open a session, where IDs come from, why every comment on a card matters, and
+that Planka answers `404` where it means `403`. Claude Code puts them in the
+session system prompt and Codex CLI reads them alongside the tool list, so the
+shared guidance is stated once instead of repeated in 41 tool descriptions.
+Every tool also publishes a display title and all four MCP behavioural hints
+explicitly, rather than inheriting the spec's pessimistic defaults, plus the two
+`_meta` keys Claude Code acts on: a forced confirmation prompt on the tools that
+delete data, and a raised output ceiling on `planka_view_attachment`. Details in
+[Server instructions and annotations](docs/tools.md#server-instructions-and-annotations).
+
+## Resources and prompts
+
+Two more surfaces, and both cost nothing until something asks for them, which is
+why the long-form guidance lives here instead of in the instructions everyone
+pays for on every session. Claude Code reads both; Cursor reads both; Codex
+supports neither, so nothing here is load-bearing.
+
+**Resources** serve the guides that ship inside the package. In Claude Code they
+are `@`-mentioned, in Cursor they come from the resource picker:
+
+| URI | What it is |
+|---|---|
+| `planka://workflow/readme` | The optional board workflow: columns, labels, who moves what |
+| `planka://workflow/board-template` | The columns and labels to create on a fresh board |
+| `planka://workflow/skills/orchestrator` | The director skill, verbatim |
+| `planka://workflow/skills/close-card` | The closing skill, verbatim |
+| `planka://gotchas/planka-2x` | How Planka 2.x actually behaves when a call answers nonsense |
+| `planka://labels/colors` | Every color `planka_create_label` and `planka_update_label` accept, generated from the schema |
+
+**Prompts** are three ways to start, surfaced by Claude Code as
+`/mcp__planka__<name>`:
+
+| Prompt | Arguments | What it does |
+|---|---|---|
+| `planka-open-session` | `boardId?`, `since?` | Summary, then recent movement, then the columns that matter — in that order |
+| `planka-close-card` | `cardId`, `listId?` | Read the whole thread, write an honest closing comment, move it, check `verified` |
+| `planka-board-triage` | `boardId?`, `lists?` | Walk the columns waiting on a person and turn each card into one question |
+
 ## Optional agent workflow
 
 The MCP server works on its own. The optional method solves a different problem:
@@ -187,8 +425,8 @@ npm test
 ```
 
 The real smoke test is opt-in because it mutates a writable board and then cleans
-up after itself. It drives all 24 tools over stdio and cross-checks every write
-against the raw Planka API — 64 named checks:
+up after itself. It drives all 41 tools over stdio and cross-checks every write
+against the raw Planka API — over 90 named checks:
 
 ```bash
 export PLANKA_BASE_URL="https://planka.example.com"

package/dist/cli/init.d.ts

@@ -0,0 +1,101 @@
+export declare const CLIENTS: readonly ["claude", "codex", "cursor", "vscode", "print"];
+export type Client = (typeof CLIENTS)[number];
+export interface InitOptions {
+    client: Client;
+    dryRun: boolean;
+    baseUrl?: string;
+    apiKey?: string;
+    email?: string;
+    password?: string;
+    boardId?: string;
+    /** Where the VS Code config goes. Defaults to the current directory. */
+    projectDir: string;
+    help: boolean;
+}
+export interface ServerSpec {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
+export declare const USAGE = "planka-mcp init \u2014 configure this MCP server in your client\n\nUsage:\n  npx @omnicoreos/planka-mcp init [--client <name>] [options]\n\nClients:\n  claude    Claude Code (claude mcp add, user scope)\n  codex     Codex CLI (~/.codex/config.toml)\n  cursor    Cursor (~/.cursor/mcp.json) and an \"Add to Cursor\" deeplink\n  vscode    VS Code (.vscode/mcp.json, secret asked at startup)\n  print     print every snippet, write nothing (default without a TTY)\n\nOptions:\n  --base-url <url>     Planka origin, e.g. https://planka.example.com\n  --api-key <key>      Planka API key (recommended)\n  --email <email>      Agent email, only if you have no API key\n  --password <pass>    Agent password, only if you have no API key\n  --board <id>         Default board ID (PLANKA_DEFAULT_BOARD_ID)\n  --project-dir <dir>  Where to write .vscode/mcp.json (default: cwd)\n  --dry-run            Print what would be written, change nothing\n  -h, --help           This text\n\nWith no flags and a terminal attached, init asks for what it needs.";
+/** Flags in, options out. Unknown flags are an error, not a silent no-op. */
+export declare function parseInitArgs(argv: string[]): InitOptions;
+/**
+ * The server entry every client gets, in MCP's `{command, args, env}` shape.
+ * `redacted` swaps the secret for a placeholder — that is the version that goes
+ * into anything printed, linked or committed.
+ */
+export declare function serverSpec(options: Pick<InitOptions, "baseUrl" | "apiKey" | "email" | "password" | "boardId">, redacted?: boolean): ServerSpec;
+/** `claude mcp add …`, ready to paste. */
+export declare function claudeMcpAddCommand(spec: ServerSpec): string;
+/** The `[mcp_servers.planka]` block for `~/.codex/config.toml`. */
+export declare function codexTomlBlock(spec: ServerSpec): string;
+/**
+ * Cursor's install deeplink. The base64 payload is the SERVER OBJECT ONLY —
+ * `{command, args, env}` with no name wrapper — and it never carries a real
+ * key: a deeplink ends up in browser history and in READMEs.
+ */
+export declare function cursorDeeplink(spec: ServerSpec): string;
+/** VS Code badge URL. Same payload, url-encoded instead of base64. */
+export declare function vscodeBadgeUrl(spec: ServerSpec): string;
+/**
+ * `.vscode/mcp.json`. The secret is an `inputs` promptString with
+ * `password: true`, so VS Code asks for it at startup and the committed file
+ * holds no credential.
+ */
+export declare function vscodeConfig(options: Pick<InitOptions, "baseUrl" | "boardId">): {
+    inputs: {
+        id: string;
+        type: string;
+        description: string;
+        password: boolean;
+    }[];
+    servers: {
+        planka: {
+            type: string;
+            command: string;
+            args: string[];
+            env: Record<string, string>;
+        };
+    };
+};
+/**
+ * Merge a server entry into an `{mcpServers: …}` document without touching
+ * anything else. An existing `planka` entry wins: this command never silently
+ * replaces a config the user tuned by hand.
+ */
+export declare function mergeMcpJson(document: unknown, spec: ServerSpec, key?: string): {
+    document: Record<string, unknown>;
+    added: boolean;
+};
+/**
+ * Append the Codex block to an existing config.toml. Present already = leave it
+ * alone. TOML is edited as text on purpose: no parser here means no chance of
+ * rewriting (and reformatting, and losing the comments of) somebody's config.
+ */
+export declare function mergeCodexToml(current: string, block: string): {
+    text: string;
+    added: boolean;
+};
+/**
+ * The connection smoke that `scripts/setup.mjs` has always run, reduced to its
+ * useful half: one authenticated GET. It proves the base URL is the API origin
+ * (not an SPA or a proxy page) and that the credential works, before anything
+ * is written. Never fatal — a config that cannot be verified is still worth
+ * writing, as long as we say so.
+ */
+export declare function checkConnection(options: Pick<InitOptions, "baseUrl" | "apiKey" | "email" | "password">, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+type Ask = (question: string, secret?: boolean) => Promise<string>;
+export interface RunInitDeps {
+    log?: (line: string) => void;
+    ask?: Ask;
+    /** Skips the network check. Tests and --dry-run never touch Planka. */
+    check?: typeof checkConnection;
+}
+/** Entry point. Returns the process exit code; never throws for user error. */
+export declare function runInit(argv: string[], deps?: RunInitDeps): Promise<number>;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}