feat(jira): add watch/unwatch/watchers commands

- jira watch <key> - Start watching an issue
- jira unwatch <key> - Stop watching an issue
- jira watchers <key> - List watchers for an issue

Added webhook server to roadmap as next phase (Bun HTTP server).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: BjoernSchotte

apps/cli/src/commands/jira.ts

@@ -93,6 +93,15 @@ export async function handleJira(
     case "me":
       await handleMe(flags, opts);
       return;
+    case "watch":
+      await handleWatch(rest, flags, opts);
+      return;
+    case "unwatch":
+      await handleUnwatch(rest, flags, opts);
+      return;
+    case "watchers":
+      await handleWatchers(rest, flags, opts);
+      return;
     default:
       output(jiraHelp(), opts);
       return;
@@ -3393,12 +3402,107 @@ Examples:
 `;
 }
 
+// ============ Watch Commands ============
+
+async function handleWatch(
+  args: string[],
+  flags: Record<string, string | boolean>,
+  opts: OutputOptions
+): Promise<void> {
+  const [key] = args;
+  if (!key) {
+    fail(opts, 1, ERROR_CODES.USAGE, "Usage: jira watch <issue-key>");
+    return;
+  }
+
+  const client = await getClient(flags, opts);
+  const me = await client.getCurrentUser();
+
+  if (!me.accountId) {
+    fail(opts, 1, ERROR_CODES.AUTH, "Could not determine current user accountId.");
+    return;
+  }
+
+  await client.addWatcher(key, me.accountId);
+
+  if (opts.json) {
+    output({ schemaVersion: "1", watching: key, user: me.displayName }, opts);
+  } else {
+    output(`Now watching ${key}`, opts);
+  }
+}
+
+async function handleUnwatch(
+  args: string[],
+  flags: Record<string, string | boolean>,
+  opts: OutputOptions
+): Promise<void> {
+  const [key] = args;
+  if (!key) {
+    fail(opts, 1, ERROR_CODES.USAGE, "Usage: jira unwatch <issue-key>");
+    return;
+  }
+
+  const client = await getClient(flags, opts);
+  const me = await client.getCurrentUser();
+
+  if (!me.accountId) {
+    fail(opts, 1, ERROR_CODES.AUTH, "Could not determine current user accountId.");
+    return;
+  }
+
+  await client.removeWatcher(key, me.accountId);
+
+  if (opts.json) {
+    output({ schemaVersion: "1", unwatched: key, user: me.displayName }, opts);
+  } else {
+    output(`Stopped watching ${key}`, opts);
+  }
+}
+
+async function handleWatchers(
+  args: string[],
+  flags: Record<string, string | boolean>,
+  opts: OutputOptions
+): Promise<void> {
+  const [key] = args;
+  if (!key) {
+    fail(opts, 1, ERROR_CODES.USAGE, "Usage: jira watchers <issue-key>");
+    return;
+  }
+
+  const client = await getClient(flags, opts);
+  const result = await client.getWatchers(key);
+
+  if (opts.json) {
+    output({
+      schemaVersion: "1",
+      issue: key,
+      watchCount: result.watchCount,
+      isWatching: result.isWatching,
+      watchers: result.watchers.map((w) => ({
+        accountId: w.accountId,
+        displayName: w.displayName,
+        email: w.emailAddress,
+      })),
+    }, opts);
+  } else {
+    output(`Watchers for ${key} (${result.watchCount}):`, opts);
+    if (result.isWatching) {
+      output(`  (You are watching this issue)`, opts);
+    }
+    for (const w of result.watchers) {
+      output(`  - ${w.displayName}${w.emailAddress ? ` <${w.emailAddress}>` : ""}`, opts);
+    }
+  }
+}
+
 function jiraHelp(): string {
   return `atlcli jira <command>
 
 Commands:
   project     Project operations (list, get, create, types)
-  issue       Issue operations (get, create, update, delete, transition, comment, link)
+  issue       Issue operations (get, create, update, delete, transition, comment, link, attach)
   board       Board operations (list, get, backlog, issues)
   sprint      Sprint operations (list, get, create, start, close, add, remove, report)
   worklog     Time tracking (add, list, update, delete, timer)
@@ -3410,6 +3514,9 @@ Commands:
   import      Import issues from CSV/JSON file
   search      Search with JQL
   me          Get current user info
+  watch       Start watching an issue (receive notifications)
+  unwatch     Stop watching an issue
+  watchers    List watchers for an issue
 
 Options:
   --profile <name>   Use a specific auth profile
@@ -3423,6 +3530,7 @@ Examples:
   atlcli jira analyze velocity --board 123 --sprints 5
   atlcli jira export --jql "project = PROJ" -o issues.json
   atlcli jira import --file issues.json --project PROJ --dry-run
+  atlcli jira watch PROJ-123
   atlcli jira search --project PROJ --assignee me
 `;
 }

packages/jira/src/client.ts

@@ -1390,6 +1390,51 @@ export class JiraClient {
     throw lastError ?? new Error("Attachment upload failed");
   }
 
+  // ============ Watcher Operations ============
+
+  /**
+   * Get watchers for an issue.
+   *
+   * GET /rest/api/3/issue/{keyOrId}/watchers
+   */
+  async getWatchers(keyOrId: string): Promise<{
+    watchers: JiraUser[];
+    watchCount: number;
+    isWatching: boolean;
+  }> {
+    const result = await this.request<{
+      watchers: JiraUser[];
+      watchCount: number;
+      isWatching: boolean;
+    }>(`/issue/${keyOrId}/watchers`);
+    return result;
+  }
+
+  /**
+   * Add a watcher to an issue.
+   *
+   * POST /rest/api/3/issue/{keyOrId}/watchers
+   * Body is just the accountId as a quoted string.
+   */
+  async addWatcher(keyOrId: string, accountId: string): Promise<void> {
+    await this.request(`/issue/${keyOrId}/watchers`, {
+      method: "POST",
+      body: accountId, // Just the accountId string, not an object
+    });
+  }
+
+  /**
+   * Remove a watcher from an issue.
+   *
+   * DELETE /rest/api/3/issue/{keyOrId}/watchers?accountId={accountId}
+   */
+  async removeWatcher(keyOrId: string, accountId: string): Promise<void> {
+    await this.request(`/issue/${keyOrId}/watchers`, {
+      method: "DELETE",
+      query: { accountId },
+    });
+  }
+
   // ============ Helpers ============
 
   /**

spec/jira-roadmap.md

@@ -320,6 +320,49 @@ Commercial plugin - not implementing.
 
 ---
 
+## 12. Issue Watchers (Priority: Low)
+
+**Status**: COMPLETE ✅
+
+Watch/unwatch issues to receive Jira notifications.
+
+**Features:**
+- `jira watch <key>` - Start watching an issue ✅
+- `jira unwatch <key>` - Stop watching an issue ✅
+- `jira watchers <key>` - List watchers for an issue ✅
+
+**API Endpoints:**
+- `GET /rest/api/3/issue/{key}/watchers` - List watchers
+- `POST /rest/api/3/issue/{key}/watchers` - Add watcher
+- `DELETE /rest/api/3/issue/{key}/watchers?accountId=X` - Remove watcher
+
+---
+
+## 13. Webhook Server (Priority: Low)
+
+**Status**: Not Started
+
+Real-time notifications via local webhook server (like Confluence sync).
+
+**Features:**
+- `jira webhook serve [--port 8080]` - Start local webhook server
+- `jira webhook register --url <url> --events <events>` - Register webhook with Jira
+- `jira webhook list` - List registered webhooks
+- `jira webhook delete <id>` - Delete webhook
+
+**Webhook Events:**
+- `jira:issue_created`, `jira:issue_updated`, `jira:issue_deleted`
+- `comment_created`, `comment_updated`, `comment_deleted`
+- `sprint_started`, `sprint_closed`
+
+**Implementation Notes:**
+- Use Bun's built-in HTTP server
+- Support JQL filtering for targeted notifications
+- Output events to stdout or file
+- Optional: Desktop notifications via system notify
+
+---
+
 ## Priority Order
 
 | Priority | Feature | Effort | Dependencies | Status |
@@ -335,6 +378,8 @@ Commercial plugin - not implementing.
 | 9 | Import/Export | Medium | Issues, JQL | ✅ COMPLETE |
 | 10 | Saved Filters | Small | JQL | ✅ COMPLETE |
 | 11 | Tempo Integration | Medium | Time Tracking | ⏭️ SKIPPED |
+| 12 | Issue Watchers | Small | Issues | ✅ COMPLETE |
+| 13 | Webhook Server | Medium | Watchers | Not Started |
 
 ---