ticketlens 0.6.0 → 0.7.0

package/README.md

@@ -133,6 +133,9 @@ ticketlens triage --stale=3                    # Aging threshold: 3 days (defaul
 ticketlens triage --status="Code Review,QA"    # Override statuses to scan
 ticketlens triage --assignee="Jane Dev"        # Another dev's tickets [Team]
 ticketlens triage --sprint="Sprint 12"         # Filter by sprint [Team]
+ticketlens triage --project=MYPROJ             # Scope to a Jira project key [Team]
+ticketlens triage --label=Bug,P1               # Filter by label(s) [Team]
+ticketlens triage --priority=High              # Filter by priority level [Team]
 ticketlens triage --export=csv                 # Export results to CSV [Team]
 ticketlens triage --export=json                # Export results to JSON [Team]
 ticketlens triage --push                       # Push snapshot to Console queue [Team]
@@ -519,6 +522,10 @@ ticketlens triage --static                   # Static table output (no interacti
 ticketlens triage --plain                    # Plain markdown — pipe to LLM or file
 ticketlens triage --assignee="Jane Dev"      # View another dev's tickets [Team]
 ticketlens triage --sprint="Sprint 12"       # Filter by sprint name [Team]
+ticketlens triage --project=MYPROJ           # Scope to a Jira project key [Team]
+ticketlens triage --label=Bug,P1             # Filter by label(s) [Team]
+ticketlens triage --priority=High            # Filter by priority level [Team]
+ticketlens triage --project=MYPROJ --label=Bug --priority=High  # Combined [Team]
 ticketlens triage --assignee="Jane Dev" --sprint="Sprint 12"  # Combined [Team]
 ticketlens triage --export=csv               # Export to CSV [Team]
 ticketlens triage --export=json              # Export to JSON [Team]
@@ -701,6 +708,9 @@ Pro also unlocks configurable brief cache TTL per profile — set `cacheTtl` to
 ```bash
 ticketlens triage --assignee="Jane Dev"        # View another dev's tickets
 ticketlens triage --sprint="Sprint 12"         # Filter by sprint name
+ticketlens triage --project=MYPROJ             # Scope to a Jira project key
+ticketlens triage --label=Bug,P1               # Filter by label(s)
+ticketlens triage --priority=High              # Filter by priority level
 ticketlens triage --export=csv                 # Export triage to CSV for standups and reports
 ticketlens triage --export=json                # Machine-readable export for dashboards
 ticketlens triage --push                       # Push snapshot to the Console queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.6.0",
+  "version": "0.7.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.6.0 -->
+<!-- jtb-skill-version: 0.7.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.
@@ -29,6 +29,9 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb triage --profile=acme             # explicit profile override
 /jtb triage --all                      # triage all configured profiles at once, merged (Pro)
 /jtb triage --save=~/triage.txt        # save ANSI-stripped output to file (Pro)
+/jtb triage --project=MYPROJ           # scope to a Jira project key (Team)
+/jtb triage --label=Bug,P1             # filter by label(s) (Team)
+/jtb triage --priority=High            # filter by priority level (Team)
 /jtb triage --push                     # push snapshot + git branches to Console (Team)
 /jtb triage --share                    # generate 24h share URL (Team)
 /jtb history PROD-1234                 # show urgency timeline for a ticket (Pro)

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

@@ -65,20 +65,15 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     printTriageHelp();
     return;
   }
-  // Normalize --project= alias once at entry so all recursive calls only see --profile=
-  const projectArg = args.find(a => a.startsWith('--project='));
-  if (projectArg) {
-    process.stderr.write(`Hint: --project recognized as alias for --profile=${projectArg.split('=')[1]}\n\n`);
-    args = args.map(a => a.startsWith('--project=') ? `--profile=${a.split('=')[1]}` : a);
-  }
-
   const profileArg = args.find(a => a.startsWith('--profile='));
   const profileName = profileArg ? profileArg.split('=')[1] : undefined;
 
   const validatedArgs = await handleUnknownFlags(
     args,
-    ['--help', '-h', '--static', '--plain', '--styled', '--profile=', '--stale=', '--status=', '--assignee=', '--sprint=', '--export=', '--digest', '--push', '--share', '--all', '--save='],
-    { hints: ['--depth=', '--no-attachments', '--no-cache'] } // fetch-only flags — shown as hints, not applied
+    ['--help', '-h', '--static', '--plain', '--styled', '--profile=', '--stale=', '--status=',
+     '--assignee=', '--sprint=', '--export=', '--digest', '--push', '--share', '--all', '--save=',
+     '--project=', '--label=', '--priority='],
+    { hints: ['--depth=', '--no-attachments', '--no-cache'] }
   );
   if (validatedArgs === null) { process.exitCode = 1; return; }
   args = validatedArgs;
@@ -89,9 +84,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const staleArg = args.find(a => a.startsWith('--stale='));
   const staleDays = staleArg ? parseInt(staleArg.split('=')[1], 10) : 5;
 
-  const statusArg = args.find(a => a.startsWith('--status='));
+  const statusArg   = args.find(a => a.startsWith('--status='));
   const assigneeArg = args.find(a => a.startsWith('--assignee='));
-  const sprintArg = args.find(a => a.startsWith('--sprint='));
+  const sprintArg   = args.find(a => a.startsWith('--sprint='));
+  const projectArg  = args.find(a => a.startsWith('--project='));
+  const labelArg    = args.find(a => a.startsWith('--label='));
+  const priorityArg = args.find(a => a.startsWith('--priority='));
   const exportArg = args.find(a => a.startsWith('--export='))?.split('=')[1] ?? null;
   const digestFlag = args.includes('--digest');
   const pushFlag = args.includes('--push');
@@ -125,6 +123,16 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     } catch { /* doesn't exist yet — ok */ }
   }
 
+  // --project / --label / --priority: Team gate
+  if (projectArg || labelArg || priorityArg) {
+    if (!licensedFn('team', configDir)) {
+      const flag = projectArg ? '--project' : labelArg ? '--label' : '--priority';
+      upgradeFn('team', flag);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   // --all: triage all configured profiles in parallel with live status block
   if (allFlag) {
     if (!licensedFn('pro', configDir)) {
@@ -270,10 +278,16 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     : conn.triageStatuses || DEFAULT_STATUSES;
 
   // Build JQL before any I/O — pure computation, no dependency on currentUser
-  const statusList    = statuses.map(s => `"${escapeJql(s)}"`).join(',');
+  const statusList     = statuses.map(s => `"${escapeJql(s)}"`).join(',');
   const assigneeClause = assigneeName ? `assignee = "${escapeJql(assigneeName)}"` : `assignee = currentUser()`;
   const sprintClause   = sprintName   ? ` AND sprint = "${escapeJql(sprintName)}"` : '';
-  const jql = `${assigneeClause} AND status IN (${statusList})${sprintClause} ORDER BY updated DESC`;
+  const projectClause  = projectArg   ? ` AND project = "${escapeJql(projectArg.split('=')[1])}"` : '';
+  const labelValues    = labelArg ? labelArg.split('=')[1].split(',').map(l => l.trim()).filter(Boolean) : [];
+  const labelClause    = labelValues.length > 1
+    ? ` AND labels IN (${labelValues.map(l => `"${escapeJql(l)}"`).join(',')})`
+    : labelValues.length === 1 ? ` AND labels = "${escapeJql(labelValues[0])}"` : '';
+  const priorityClause = priorityArg  ? ` AND priority = "${escapeJql(priorityArg.split('=')[1])}"` : '';
+  const jql = `${assigneeClause} AND status IN (${statusList})${sprintClause}${projectClause}${labelClause}${priorityClause} ORDER BY updated DESC`;
 
   const session = createSession(conn);
   session.spin(`Connecting to ${session.label}…`);
@@ -421,7 +435,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
         await import('./lib/triage-history.mjs');
       const yesterday = loadYesterdaySnapshot({ profile: profileName ?? 'default', configDir });
       if (yesterday) {
-        const deltas = diffSnapshots(sorted, yesterday);
+        const deltas = diffSnapshots(sorted, yesterday.tickets);
         delta = buildDeltaSection(deltas) || null;
       }
     } catch { /* non-fatal — digest still sends */ }

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

@@ -77,6 +77,9 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--status')}=${s.dim('X,Y')}       Override statuses to scan`,
     `    ${s.brand('--assignee')}=${s.dim('NAME')}    Triage another dev's tickets  ${s.dim('[Team]')}`,
     `    ${s.brand('--sprint')}=${s.dim('NAME')}      Filter by sprint name  ${s.dim('[Team]')}`,
+    `    ${s.brand('--project')}=${s.dim('PROJ')}     Filter by Jira project key  ${s.dim('[Team]')}`,
+    `    ${s.brand('--label')}=${s.dim('X,Y')}        Filter by label(s)  ${s.dim('[Team]')}`,
+    `    ${s.brand('--priority')}=${s.dim('LEVEL')}   Filter by priority  ${s.dim('(e.g. High, Blocker) [Team]')}`,
     `    ${s.brand('--export')}=${s.dim('FORMAT')}   Export results to file  ${s.dim('(csv|json) [Team]')}`,
     `    ${s.brand('--push')}             Push snapshot to Console queue  ${s.dim('[Team]')}`,
     `    ${s.brand('--share')}            Generate a 24h share URL  ${s.dim('(no login required) [Team]')}`,
@@ -549,6 +552,9 @@ export function printTriageHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--status')}=${s.dim('X,Y')}       Override statuses to scan`,
     `    ${s.brand('--assignee')}=${s.dim('NAME')}    Triage another dev's tickets  ${s.dim('[Team]')}`,
     `    ${s.brand('--sprint')}=${s.dim('NAME')}      Filter by sprint name  ${s.dim('[Team]')}`,
+    `    ${s.brand('--project')}=${s.dim('PROJ')}     Filter by Jira project key  ${s.dim('[Team]')}`,
+    `    ${s.brand('--label')}=${s.dim('X,Y')}        Filter by label(s)  ${s.dim('[Team]')}`,
+    `    ${s.brand('--priority')}=${s.dim('LEVEL')}   Filter by priority  ${s.dim('(e.g. High, Blocker) [Team]')}`,
     `    ${s.brand('--export')}=${s.dim('FORMAT')}    Export results to file  ${s.dim('(csv|json) [Team]')}`,
     `    ${s.brand('--push')}             Push snapshot to Console queue  ${s.dim('[Team]')}`,
     `    ${s.brand('--share')}            Generate a 24h share URL  ${s.dim('(no login required) [Team]')}`,
@@ -565,6 +571,8 @@ export function printTriageHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens triage --profile=acme`,
     `    ${s.dim('$')} ticketlens triage --stale=3 --status="Code Review,QA Testing"`,
     `    ${s.dim('$')} ticketlens triage --assignee="Jane Dev" --sprint="Sprint 12"`,
+    `    ${s.dim('$')} ticketlens triage --project=MYPROJ --priority=High`,
+    `    ${s.dim('$')} ticketlens triage --label=Bug,P1`,
     `    ${s.dim('$')} ticketlens triage --static`,
     '',
     `  ${s.bold('INTERACTIVE MODE')}`,

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

@@ -8,7 +8,7 @@ import * as defaultFs from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
+export const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
 
 const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
 
@@ -16,6 +16,17 @@ const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+function median(arr) {
+  if (!arr.length) return null;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
 function validateProfile(profile) {
   if (!profile || /[/\\]/.test(profile) || profile === '..' || profile.includes('..')) {
     throw new Error('Invalid profile name');
@@ -59,7 +70,8 @@ export function saveTriageSnapshot(tickets, {
   const dir = join(configDir, 'triage-history', dateStr);
   fsModule.mkdirSync(dir, { recursive: true });
   const filePath = snapshotPath(configDir, dateStr, profile);
-  fsModule.writeFileSync(filePath, JSON.stringify(tickets, null, 2), 'utf8');
+  const envelope = { captured_at: now.toISOString(), tickets };
+  fsModule.writeFileSync(filePath, JSON.stringify(envelope, null, 2), 'utf8');
 }
 
 /**
@@ -70,7 +82,7 @@ export function saveTriageSnapshot(tickets, {
  * @param {string} [opts.configDir]
  * @param {object} [opts.fsModule]
  * @param {Date}   [opts.now]
- * @returns {object[]|null}
+ * @returns {{ captured_at: string|null, tickets: object[] }|null}
  */
 export function loadYesterdaySnapshot({
   profile,
@@ -85,7 +97,9 @@ export function loadYesterdaySnapshot({
   const filePath = snapshotPath(configDir, dateStr, profile);
   try {
     const raw = fsModule.readFileSync(filePath, 'utf8');
-    return JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return { captured_at: null, tickets: parsed };
+    return parsed;
   } catch {
     return null;
   }
@@ -201,11 +215,12 @@ export function queryTicketHistory(ticketKey, {
       const profile = file.slice(0, -5); // strip .json
       let tickets;
       try {
-        tickets = JSON.parse(fsModule.readFileSync(join(dayDir, file), 'utf8'));
+        const raw = JSON.parse(fsModule.readFileSync(join(dayDir, file), 'utf8'));
+        tickets = Array.isArray(raw) ? raw : (raw.tickets ?? []);
       } catch {
         continue;
       }
-      const found = Array.isArray(tickets) && tickets.find(t => t.ticketKey === ticketKey);
+      const found = tickets.find(t => t.ticketKey === ticketKey);
       if (found) {
         entries.push({
           date,
@@ -230,3 +245,134 @@ export function queryTicketHistory(ticketKey, {
 
   return entries;
 }
+
+/**
+ * Load a snapshot file for an arbitrary date string. Returns { captured_at, tickets } or null.
+ *
+ * @param {string} dateStr - YYYY-MM-DD
+ * @param {string} profile
+ * @param {string} configDir
+ * @param {object} fsModule
+ * @returns {{ captured_at: string|null, tickets: object[] }|null}
+ */
+function loadSnapshotForDate(dateStr, profile, configDir, fsModule) {
+  const filePath = snapshotPath(configDir, dateStr, profile);
+  try {
+    const parsed = JSON.parse(fsModule.readFileSync(filePath, 'utf8'));
+    if (Array.isArray(parsed)) return { captured_at: null, tickets: parsed };
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute response-time and triage-cadence metrics from local triage history.
+ *
+ * A "response transition" is detected when a ticket appears as `needs-response`
+ * in snapshot D and `clear` in snapshot D+1. Response time = captured_at of the
+ * clear snapshot minus lastComment.created of the needs-response snapshot.
+ *
+ * @param {string} profile
+ * @param {object} [opts]
+ * @param {number} [opts.days=7]            Lookback window in calendar days
+ * @param {string} [opts.configDir]
+ * @param {object} [opts.fsModule]
+ * @param {Date}   [opts.now]
+ * @returns {{
+ *   avgResponseHours: number|null,
+ *   medianResponseHours: number|null,
+ *   clearRate: number|null,
+ *   triageRunCount: number,
+ *   currentUrgency: { needsResponse: number, aging: number, clear: number }|null,
+ *   windowDays: number,
+ *   trendHours: number|null,
+ * }}
+ */
+export function computeResponseMetrics(profile, {
+  days = 7,
+  configDir = DEFAULT_CONFIG_DIR,
+  fsModule = defaultFs,
+  now = new Date(),
+} = {}) {
+  validateProfile(profile);
+
+  function windowSnapshots(offsetStart, count) {
+    const snaps = [];
+    for (let i = offsetStart + count - 1; i >= offsetStart; i--) {
+      const d = new Date(now);
+      d.setDate(d.getDate() - i);
+      const dateStr = toDateString(d);
+      const snap = loadSnapshotForDate(dateStr, profile, configDir, fsModule);
+      if (snap) snaps.push({ dateStr, ...snap });
+    }
+    return snaps; // chronological order (oldest first)
+  }
+
+  function computeFromSnaps(snaps) {
+    const durations = [];
+    let transitions = 0;
+    let fastTransitions = 0;
+
+    for (let i = 0; i + 1 < snaps.length; i++) {
+      const dayA = snaps[i];
+      const dayB = snaps[i + 1];
+      const mapA = new Map(dayA.tickets.map(t => [t.ticketKey, t]));
+
+      for (const tb of dayB.tickets) {
+        if (tb.urgency !== 'clear') continue;
+        const ta = mapA.get(tb.ticketKey);
+        if (!ta || ta.urgency !== 'needs-response') continue;
+
+        transitions++;
+        const commentCreated = ta.lastComment?.created;
+        const clearedAt = dayB.captured_at;
+        if (!commentCreated || !clearedAt) continue;
+
+        const ms = new Date(clearedAt).getTime() - new Date(commentCreated).getTime();
+        if (isNaN(ms) || ms < 0) continue;
+        const hours = ms / 3_600_000;
+        durations.push(hours);
+        if (hours <= 24) fastTransitions++;
+      }
+    }
+
+    return {
+      avgResponseHours: durations.length ? durations.reduce((a, b) => a + b, 0) / durations.length : null,
+      medianResponseHours: median(durations),
+      clearRate: durations.length > 0 ? fastTransitions / durations.length : null,
+      triageRunCount: snaps.length,
+    };
+  }
+
+  const currentSnaps = windowSnapshots(0, days);
+  const current = computeFromSnaps(currentSnaps);
+
+  // Current urgency from the most recent snapshot
+  const latest = currentSnaps[currentSnaps.length - 1] ?? null;
+  const currentUrgency = latest
+    ? {
+        needsResponse: latest.tickets.filter(t => t.urgency === 'needs-response').length,
+        aging:         latest.tickets.filter(t => t.urgency === 'aging').length,
+        clear:         latest.tickets.filter(t => t.urgency === 'clear').length,
+      }
+    : null;
+
+  // Trend: compare current window avg vs prior window avg
+  const priorSnaps = windowSnapshots(days, days);
+  const prior = computeFromSnaps(priorSnaps);
+  const trendHours =
+    current.avgResponseHours !== null && prior.avgResponseHours !== null
+      ? current.avgResponseHours - prior.avgResponseHours
+      : null;
+
+  return {
+    avgResponseHours: current.avgResponseHours,
+    medianResponseHours: current.medianResponseHours,
+    clearRate: current.clearRate,
+    triageRunCount: current.triageRunCount,
+    currentUrgency,
+    windowDays: days,
+    trendHours,
+  };
+}