link-ticket-to-session

You are linking the current Claude Code session (`${CLAUDE_SESSION_ID}`) to: **$ARGUMENTS** Karma is a read-only observer on the user's machine. It stores the link and caches title/status for display, but never writes back to the ticket provider. You fetch metadata via the user's already-configured MCP server. Karma's API URL comes from `KARMA_API_URL` (set by users on non-default ports/hosts) with `http://localhost:8020` as fallback. Inline `${KARMA_API_URL:-http://localhost:8020}` in **every** curl below — bash variables don't persist across separate Bash tool calls, so a top-of-script assignment would be empty by the time the next curl runs. ## Step 1 — Parse $ARGUMENTS Recognized forms: | Provider | Short ref | URL forms | |--------------------|---------------------|--------------------------------------------------------| | Linear | `LINEAR-123` | `https://linear.app/.../issue/ABC-123` | | Jira | `PROJ-45` | `https://*.atlassian.net/browse/PROJ-45` | | GitHub **Issue** | `owner/repo#42` | `https://github.com/owner/repo/issues/42` | | GitHub **PR** | `owner/repo#42` | `https://github.com/owner/repo/pull/42` | GitHub issues and pull requests share a single numbering namespace — `owner/repo#42` could be either. **The URL kind (`/issues/` vs `/pull/`) is the only signal**, and karma's backend preserves it, so when you have a URL keep it intact when POSTing (Step 4). For a bare `owner/repo#N` with no URL, default to `/issues/N` — GitHub auto-redirects to `/pull/N` when N is actually a PR, so the link still resolves. A bare `#N` (no owner/repo) is **not** accepted — always qualify with `owner/repo#N`. ## Step 2 — Identify provider and (for GitHub) kind Set two variables you'll use below: - `<provider>` ∈ `linear` | `jira` | `github` - For GitHub: `<kind>` ∈ `issue` | `pull_request` (derived from URL path) For Linear and Jira this collapses to just `<provider>`. ## Step 3 — Fetch metadata via MCP (when available) Pick the right MCP tool for the provider and kind: | Provider · Kind | MCP tool | |-----------------------------|---------------------------------------------------------| | `linear` | Linear MCP — search/fetch issue by key | | `jira` | Atlassian MCP — fetch by key | | `github` · `issue` | `mcp__plugin_github_github__issue_read`, method `get` | | `github` · `pull_request` | `mcp__plugin_github_github__pull_request_read`, method `get` | Calling the wrong GitHub method silently returns the wrong thing because both shapes look superficially similar — so derive the kind first. If the relevant MCP isn't installed, **skip this step** and proceed to Step 4 without title/status. Karma will create the link; the title/status fields stay NULL and can be refreshed later via Step 5. Pull at minimum: `title`, `status` (or state), `url`. **Strip large fields** — karma caps `metadata_json` at 64 KB and a full PR payload easily exceeds that. Specifically drop: - GitHub PR: `body`, `commits`, `files`, `reviewers`, `comments`, `labels`, `requested_reviewers`, `head` / `base` blobs beyond `ref` - GitHub issue: `body`, `comments`, `reactions`, `labels` - Linear / Jira: `description`, `comments`, `subscribers`, `attachments` ### Status semantics by kind The `status` you cache should reflect *what the provider says now*, not a generic "open/closed". Karma's UI normalizes these to canonical buckets at render time, so faithful provider language is the right input: - **Linear**: workflow state name verbatim — e.g. `Backlog`, `In Progress`, `In Review`, `Done`, `Cancelled` (workspace-defined; don't normalize). - **Jira**: workflow state name — e.g. `To Do`, `In Progress`, `In Review`, `Done`. - **GitHub issue**: `open` or `closed`. - **GitHub PR**: derive from the flags the PR API returns: | `state` | `draft` | `merged` | Cache as | |----------|---------|----------|--------------| | `open` | `true` | — | `draft` | | `open` | `false` | — | `open` | | `closed` | — | `true` | `MERGED` | | `closed` | — | `false` | `closed` | ## Step 4 — POST the link The `url` field should be the URL you actually have — `/pull/N` for PRs, `/issues/N` for issues. **Don't rewrite it.** Karma's parser preserves the path segment; the UI uses it to distinguish PRs from issues. ```bash curl -s -X POST "${KARMA_API_URL:-http://localhost:8020}/sessions/${CLAUDE_SESSION_ID}/tickets" \ -H 'Content-Type: application/json' \ -d '{"ref":"<key>","provider":"<provider>","url":"<url>","source":"slash_command"}' ``` For GitHub, `<key>` is always `owner/repo#N` regardless of kind — the URL field carries the issue/PR distinction. ## Step 5 — PUT the metadata (only if Step 3 succeeded) ```bash curl -s -X PUT "${KARMA_API_URL:-http://localhost:8020}/tickets/<provider>/<key>" \ -H 'Content-Type: application/json' \ -d '{"title":"<title>","status":"<status>"}' ``` For GitHub keys with `/` and `#`, URL-encode the key in the path: `octocat/repo#42` → `octocat%2Frepo%2342`. ## Step 6 — Confirm to the user One line. For GitHub, distinguish the kind so the user knows what they just attached: - `Linked session to LINEAR-123 (Fix login bug, In Progress) — open at https://linear.app/...` - `Linked session to PROJ-45 (Migrate auth, Done) — open at https://acme.atlassian.net/browse/PROJ-45` - `Linked session to octocat/repo#42 [issue] (Empty state lies, open) — open at .../issues/42` - `Linked session to octocat/repo#42 [PR] (Fix linting, MERGED) — open at .../pull/42` ## Notes - Karma is loopback-only by default. `KARMA_API_URL` overrides for custom port or remote host. - POST is idempotent on `(session, ticket)`; re-running upgrades the `link_source` if previously set by branch-detect or dashboard. Order: `slash_command > dashboard > branch`. - If the API is unreachable, tell the user `karma not running at ${KARMA_API_URL:-http://localhost:8020}` so they see what was tried. Don't silently succeed. - GitHub issues and PRs sharing `#N` means a single karma row (one `(provider, external_key)` pair) covers both views of that number. The URL field is what tells karma's UI which one to render. Send the URL you actually have.