ticketlens 0.2.0 → 0.3.0

package/README.md

@@ -164,6 +164,27 @@ Bot comments (Jira Automation, Jenkins, GitHub Actions) are automatically ignore
 
 ---
 
+### Collisions
+
+```bash
+ticketlens collisions                         # Show branches that overlap with teammates [Team]
+ticketlens collisions --json                  # Machine-readable output
+ticketlens collisions --plain                 # Plain text, no ANSI colour
+```
+
+Requires a Team license and at least one teammate in your group. Compares your current git branch's changed files against your teammates' recent branches (within 7 days). Reports each overlap as a collision: your branch, their branch, the shared files, and linked ticket keys.
+
+```
+[1] feat/auth-refactor ↔ Jane Dev (feat/login-redesign)
+    Your tickets:  PROJ-101
+    Their tickets: PROJ-88
+    Shared files:  src/auth/LoginController.php, src/auth/guards.php
+```
+
+Branches are captured automatically when you run `ticketlens triage --push`. No extra step required.
+
+---
+
 ### Review
 
 ```bash
@@ -291,6 +312,25 @@ ticketlens activate <KEY>         # Activate a Pro or Team license
 
 ---
 
+### Update Skill
+
+```bash
+ticketlens update-skill                          # Sync /jtb skill to all detected AI assistants
+ticketlens update-skill --dry-run                # Preview what would be updated (no writes)
+ticketlens update-skill --path=~/.gemini/commands  # Sync to a specific assistant directory
+ticketlens update-skill --quiet                  # Suppress output (useful in scripts)
+```
+
+Copies the latest `SKILL.md` to every AI assistant command directory where `/jtb` is already installed. Runs automatically on `npm install -g ticketlens` — for most users, upgrading the CLI is enough. Use `--dry-run` to confirm what would change before writing.
+
+Supported assistants detected automatically:
+- Claude Code — `~/.claude/commands/jtb.md`
+- Claude Code (work) — `~/.claude-work/commands/jtb.md`
+- Gemini CLI — `~/.gemini/commands/jtb.md`
+- Copilot CLI — `~/.copilot-cli/commands/jtb.md`
+
+---
+
 ### /jtb — Jira TicketBrief for Claude Code
 
 `/jtb` is a Claude Code slash command that fetches full ticket context and drops a structured implementation brief directly into your session, then enters plan mode.
@@ -301,11 +341,25 @@ ticketlens activate <KEY>         # Activate a Pro or Team license
 
 ```bash
 npm install -g ticketlens && ticketlens init
-cp $(npm root -g)/ticketlens/skills/jtb/SKILL.md ~/.claude/commands/jtb.md
+ticketlens update-skill        # copies /jtb skill into ~/.claude/commands/jtb.md
 # Restart Claude Code, then:
 # /jtb CNV1-2
 ```
 
+**Keeping the skill up to date:**
+
+```bash
+npm install -g ticketlens@latest   # update the CLI
+ticketlens update-skill            # sync the /jtb skill to the new version
+```
+
+`update-skill` runs automatically on `npm install -g`, so for most users the second step is handled. If you manage Claude Code across multiple machines or accounts, run it manually after updating.
+
+```bash
+ticketlens update-skill --dry-run         # preview what would change
+ticketlens update-skill --path=~/.gemini/commands  # sync to a different AI assistant
+```
+
 **Usage in Claude Code:**
 
 ```
@@ -384,6 +438,11 @@ ticketlens triage --profile=acme --stale=3 --static          # Combine flags
 ticketlens triage --plain > my-tickets.md
 ticketlens triage --plain | llm "Which ticket is most urgent and why?"
 
+# ── Collisions ────────────────────────────────────────────────────────────────
+ticketlens collisions                         # Show branch collisions with teammates [Team]
+ticketlens collisions --json                  # Machine-readable JSON output
+ticketlens collisions --plain                 # Plain text, no ANSI colour
+
 # ── PR Review ─────────────────────────────────────────────────────────────────
 ticketlens review                             # Assemble PR review context from current branch
 ticketlens review --branch=main              # Compare against main (auto-detected by default)
@@ -432,6 +491,11 @@ ticketlens login --manual                     # Paste flow — for CI/headless e
 ticketlens license                            # Show license tier and status
 ticketlens activate <LICENSE-KEY>             # Activate a license key
 
+# ── Skill maintenance ─────────────────────────────────────────────────────────
+ticketlens update-skill                       # Sync /jtb skill to all detected AI assistants
+ticketlens update-skill --dry-run             # Preview what would be updated
+ticketlens update-skill --path=~/.gemini/commands  # Sync to a custom assistant directory
+
 # ── Help and version ──────────────────────────────────────────────────────────
 ticketlens --help                             # Main help
 ticketlens --version                          # Show installed version

package/bin/ticketlens.mjs

@@ -52,6 +52,15 @@ switch (command) {
     });
     break;
 
+  case 'collisions': {
+    const { runCollisions } = await import('../skills/jtb/scripts/lib/run-collisions.mjs');
+    runCollisions(cmdArgs).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'init':
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printInitHelp(); break; }
     runInit().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.2.0 -->
+<!-- jtb-skill-version: 0.3.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -27,6 +27,10 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb triage --stale=3                  # custom aging threshold (days)
 /jtb triage --status=CR,QA             # only check specific statuses
 /jtb triage --profile=acme             # explicit profile override
+/jtb triage --push                     # push snapshot + git branches to Console (Team)
+/jtb triage --share                    # generate 24h share URL (Team)
+/jtb collisions                        # show branch collisions with teammates (Team)
+/jtb collisions --json                 # machine-readable output
 ```
 
 ## Prerequisites
@@ -63,6 +67,23 @@ Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=
 
 ---
 
+### Collisions subcommand
+
+If the first argument is `collisions`:
+
+Run:
+```bash
+node ~/.agents/skills/jtb/scripts/lib/run-collisions.mjs $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--json`, `--plain`).
+
+Requires a Team license and at least one teammate in the same group. Compares your current branch's changed files against teammates' recent branches. Outputs a collision report or an empty-state message.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+---
+
 ### Fetch ticket workflow (default)
 
 ### Step 1: Validate environment

package/skills/jtb/scripts/fetch-my-tickets.mjs

@@ -354,7 +354,9 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   if (pushFlag) {
     const { pushTriageSnapshot } = await import('./lib/triage-push.mjs');
+    const { scanCurrentBranch } = await import('./lib/branch-scanner.mjs');
     const pushFn = opts.pushFn ?? pushTriageSnapshot;
+    const scanFn = opts.scanFn ?? scanCurrentBranch;
     const licenseKey = readLicense(configDir)?.key ?? null;
     const printFn = opts.print ?? ((s) => process.stdout.write(s));
     await pushFn({
@@ -363,6 +365,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       profile: profileName ?? 'default',
       baseUrl: conn.baseUrl,
       licenseKey,
+      gitBranches: scanFn(),
       fetcher,
       print: printFn,
     });

package/skills/jtb/scripts/lib/branch-scanner.mjs

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TICKET_KEY_RE = /([A-Z][A-Z0-9]+-\d+)/g;
+const SPAWN_OPTS = { encoding: 'utf8', timeout: 10_000 };
+const MAX_FILES = 200;
+const BASE_CANDIDATES = ['origin/main', 'origin/master', 'origin/develop', 'main', 'master'];
+
+function run(execFn, args, cwd) {
+  const result = execFn('git', args, { ...SPAWN_OPTS, cwd, stdio: 'pipe' });
+  return result.status === 0 ? (result.stdout ?? '') : null;
+}
+
+function extractTicketKeys(text) {
+  return [...new Set([...text.matchAll(TICKET_KEY_RE)].map(m => m[1]))];
+}
+
+function detectBase(execFn, cwd) {
+  for (const candidate of BASE_CANDIDATES) {
+    if (run(execFn, ['rev-parse', '--verify', candidate], cwd) !== null) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Scans the current git branch for changed files and linked ticket keys.
+ *
+ * @param {object}   [opts]
+ * @param {string}   [opts.cwd]    Working directory (default: process.cwd())
+ * @param {Function} [opts.execFn] spawnSync replacement (injectable for tests)
+ * @param {Function} [opts.fsCheck] existsSync replacement (injectable for tests)
+ * @returns {Array<{branch:string, base:string|null, tickets:string[], files:string[]}>|null}
+ *   One-element array for the current branch, or null if not in a git repo / detached HEAD.
+ */
+export function scanCurrentBranch({ cwd = process.cwd(), execFn = spawnSync, fsCheck = existsSync } = {}) {
+  if (!fsCheck(join(cwd, '.git'))) return null;
+
+  const branch = run(execFn, ['rev-parse', '--abbrev-ref', 'HEAD'], cwd)?.trim();
+  if (!branch || branch === 'HEAD') return null;
+
+  const base = detectBase(execFn, cwd);
+
+  let files = [];
+  if (base) {
+    const diffOut = run(execFn, ['diff', '--name-only', `${base}..HEAD`], cwd);
+    if (diffOut) {
+      files = diffOut.trim().split('\n').filter(Boolean).slice(0, MAX_FILES);
+    }
+  }
+
+  const recentLog = run(execFn, ['log', '--oneline', '-20'], cwd) ?? '';
+  const tickets = extractTicketKeys(`${branch} ${recentLog}`);
+
+  return [{ branch, base, tickets, files }];
+}

package/skills/jtb/scripts/lib/collision-reporter.mjs

@@ -0,0 +1,45 @@
+const INDENT = '        ';
+
+/**
+ * Formats a collision list from the /v1/triage/collisions API response.
+ *
+ * @param {object[]} collisions
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.plain]  Suppress ANSI (forced when not TTY)
+ * @param {boolean}  [opts.isTTY] Enable ANSI escape sequences
+ * @param {boolean}  [opts.json]  Emit raw JSON instead of text
+ * @returns {string}
+ */
+export function formatCollisions(collisions, { plain = false, isTTY = false, json = false } = {}) {
+  if (json) return JSON.stringify(collisions, null, 2) + '\n';
+
+  const useAnsi = isTTY && !plain;
+  const warn = useAnsi ? '\x1b[33m⚠\x1b[0m' : '⚠';
+  const ok   = useAnsi ? '\x1b[32m✓\x1b[0m' : '✓';
+  const bold = useAnsi ? (s) => `\x1b[1m${s}\x1b[0m` : (s) => s;
+  const dim  = useAnsi ? (s) => `\x1b[2m${s}\x1b[0m` : (s) => s;
+
+  if (collisions.length === 0) {
+    return `${ok} No branch collisions detected.\n`;
+  }
+
+  const n = collisions.length;
+  const lines = [`${warn} ${bold(`${n} collision${n === 1 ? '' : 's'} detected`)}\n`];
+
+  for (let i = 0; i < n; i++) {
+    const c = collisions[i];
+    const yourKeys  = c.your_tickets?.length  ? c.your_tickets.join(', ')  : '—';
+    const theirKeys = c.their_tickets?.length ? c.their_tickets.join(', ') : '—';
+    const count     = c.shared_files?.length ?? 0;
+
+    lines.push(
+      `  [${i + 1}] ${bold('You')} ${dim(`(${c.your_branch})`)} ↔ ${bold(c.teammate)} ${dim(`(${c.their_branch})`)}`,
+      `      Tickets: ${yourKeys} ↔ ${theirKeys}`,
+      `      Shared files (${count}):`,
+      ...(c.shared_files ?? []).map(f => `${INDENT}${f}`),
+      '',
+    );
+  }
+
+  return lines.join('\n');
+}

package/skills/jtb/scripts/lib/config.mjs

@@ -3,20 +3,24 @@
  * Single source of truth — import from here, do not redefine locally.
  */
 
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
 /** Canonical config directory: ~/.ticketlens */
 export const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
 
-/** Read package.json version once per process, memoized. */
+/** Read package.json version once per process, memoized.
+ * Uses realpathSync to resolve symlinks before navigating, so the correct
+ * package.json is found whether the module is loaded via a symlink or directly.
+ */
 let _version;
 export function getVersion() {
   if (_version) return _version;
   try {
-    const pkgPath = new URL('../../../../package.json', import.meta.url);
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const realDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(readFileSync(join(realDir, '..', '..', '..', '..', 'package.json'), 'utf8'));
     _version = pkg.version || '0.0.0';
   } catch {
     _version = '0.0.0';

package/skills/jtb/scripts/lib/help.mjs

@@ -38,6 +38,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} ${s.dim('<TICKET-KEY>')} ${s.dim('[options]')}   Fetch a ticket brief`,
     `    ${s.brand('ticketlens')} get ${s.dim('<TICKET-KEY>')}         Same as above ${s.dim('(explicit alias)')}`,
     `    ${s.brand('ticketlens')} triage ${s.dim('[options]')}         Scan your assigned tickets`,
+    `    ${s.brand('ticketlens')} collisions ${s.dim('[--json]')}        Show branch collisions with teammates  ${s.dim('[Team]')}`,
     `    ${s.brand('ticketlens')} review ${s.dim('[--branch=BRANCH]')}   Code-review context brief from current branch`,
     `    ${s.brand('ticketlens')} standup ${s.dim('[--since=N]')}        Standup summary from git log  ${s.dim('(last 24h by default)')}`,
     `    ${s.brand('ticketlens')} compliance ${s.dim('<TICKET-KEY>')}    Check requirements coverage  ${s.dim('[Pro/Free 3/mo]')}`,

package/skills/jtb/scripts/lib/run-collisions.mjs

@@ -0,0 +1,64 @@
+import { readLicense } from './license.mjs';
+import { formatCollisions } from './collision-reporter.mjs';
+
+const COLLISIONS_PATH = '/v1/triage/collisions';
+const DEFAULT_API_BASE = 'http://ticketlens.test';
+
+function apiBase() {
+  return process.env?.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+}
+
+/**
+ * Fetches cross-team branch collision data from the TicketLens API and prints results.
+ *
+ * @param {string[]} args              CLI argument array (e.g. ['--json', '--plain'])
+ * @param {object}   [opts]
+ * @param {Function} [opts.fetcher]        Injectable fetch
+ * @param {Function} [opts.print]          Output function
+ * @param {Function} [opts.readLicenseFn]  Injectable license reader
+ * @returns {Promise<{ ok: boolean, status?: number }>}
+ */
+export async function runCollisions(args = [], opts = {}) {
+  const jsonFlag  = args.includes('--json');
+  const plainFlag = args.includes('--plain');
+  const fetcher        = opts.fetcher       ?? globalThis.fetch;
+  const print          = opts.print         ?? ((s) => process.stdout.write(s));
+  const readLicenseFn  = opts.readLicenseFn ?? (() => readLicense());
+
+  const licenseKey = readLicenseFn()?.key ?? null;
+  if (!licenseKey) {
+    print('✗ collisions requires an active Team license (ticketlens activate <key>)\n');
+    return { ok: false };
+  }
+
+  try {
+    const res = await fetcher(`${apiBase()}${COLLISIONS_PATH}`, {
+      headers: { Authorization: `Bearer ${licenseKey}` },
+    });
+
+    if (!res.ok) {
+      if (res.status === 401) { print('✗ Invalid license key\n');              return { ok: false, status: 401 }; }
+      if (res.status === 403) { print('✗ collisions requires a Team license\n'); return { ok: false, status: 403 }; }
+      print(`⚠ Failed to fetch collisions (${res.status})\n`);
+      return { ok: false, status: res.status };
+    }
+
+    const { collisions = [], message } = await res.json();
+
+    if (message && collisions.length === 0) {
+      print(message + '\n');
+      return { ok: true };
+    }
+
+    print(formatCollisions(collisions, {
+      json:   jsonFlag,
+      plain:  plainFlag,
+      isTTY:  process.stdout.isTTY ?? false,
+    }));
+
+    return { ok: true };
+  } catch {
+    print('⚠ Failed to fetch collisions (network error)\n');
+    return { ok: false };
+  }
+}

package/skills/jtb/scripts/lib/triage-push.mjs

@@ -44,6 +44,7 @@ function buildTicketPayload(scored, rawMap, baseUrl) {
  * @param {string}   [opts.baseUrl]      - Jira base URL for URL construction
  * @param {string}   [opts.licenseKey]   - Bearer token for the API
  * @param {string}   [opts.capturedAt]   - ISO 8601 timestamp (defaults to now)
+ * @param {Array}    [opts.gitBranches]  - Branch metadata from scanCurrentBranch (null = not in git repo)
  * @param {Function} [opts.fetcher]      - Injectable fetch (default: globalThis.fetch)
  * @param {Function} [opts.print]        - Output fn (default: process.stdout.write)
  * @returns {Promise<{ ok: boolean, status?: number }>}
@@ -55,6 +56,7 @@ export async function pushTriageSnapshot({
   baseUrl,
   licenseKey,
   capturedAt,
+  gitBranches,
   fetcher = globalThis.fetch,
   print = (s) => process.stdout.write(s),
 } = {}) {
@@ -67,6 +69,7 @@ export async function pushTriageSnapshot({
     profile: String(profile ?? 'default').slice(0, 100),
     captured_at: capturedAt ?? new Date().toISOString(),
     tickets: sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl)),
+    ...(gitBranches != null && { git_branches: gitBranches }),
   };
 
   try {