ticketlens 0.7.0 → 0.8.1

package/README.md

@@ -355,6 +355,29 @@ Requires a Pro license. No network call — reads local snapshots only.
 
 ---
 
+### Response-Time Stats
+
+```bash
+ticketlens stats                         # Personal metrics from local triage history
+ticketlens stats --profile=acme          # Metrics for a specific profile
+ticketlens stats --days=14               # Extend lookback window [Pro, max 30]
+ticketlens stats --format=json           # JSON output for scripting
+ticketlens stats --format=json | jq '.avgResponseHours'
+```
+
+Shows avg/median response time, clear rate (resolved within 24h), triage run count, and week-over-week trend — all computed from local `~/.ticketlens/triage-history/` snapshots. No network call.
+
+- **Free**: last 7 days (fixed)
+- **Pro**: `--days=N` up to 30 days
+
+A one-line summary footer is also appended automatically to `ticketlens triage` output once you have 2 or more triage runs:
+
+```
+── This week: avg 3.2h response · 80% cleared within 24h (5 runs) ──
+```
+
+---
+
 ### Custom Attention Rules
 
 Add an `attentionRules` array to any profile in `~/.ticketlens/profiles.json` to override how `ticketlens triage` scores specific tickets:
@@ -589,6 +612,12 @@ ticketlens schedule --local                   # Local-only cron/LaunchAgent —
 # ── History ───────────────────────────────────────────────────────────────────
 ticketlens history <TICKET-KEY>               # Show urgency timeline for a ticket [Pro]
 
+# ── Stats ──────────────────────────────────────────────────────────────────────
+ticketlens stats                              # Response-time metrics from local history
+ticketlens stats --profile=acme              # Metrics for a specific profile
+ticketlens stats --days=14                   # Extend lookback window (Pro, max 30)
+ticketlens stats --format=json               # JSON output for scripting
+
 # ── Compliance ────────────────────────────────────────────────────────────────
 ticketlens compliance <TICKET-KEY>            # Check ticket requirements against local diff [Pro/Free 3/mo]
 ticketlens ledger                             # View local compliance audit ledger [Pro]

package/bin/ticketlens.mjs

@@ -24,8 +24,9 @@ import {
   printProfilesHelp, printScheduleHelp,
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
-  printCollisionsHelp,
+  printCollisionsHelp, printStatsHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
+import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
 import { readCliToken, saveCliToken, deleteCliToken } from '../skills/jtb/scripts/lib/cli-auth.mjs';
 import { browserLogin } from '../skills/jtb/scripts/lib/browser-login.mjs';
@@ -103,6 +104,15 @@ switch (command) {
     break;
   }
 
+  case 'stats': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printStatsHelp(); break; }
+    runStats(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.7.0",
+  "version": "0.8.1",
   "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.7.0 -->
+<!-- jtb-skill-version: 0.8.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.
@@ -35,6 +35,9 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /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)
+/jtb stats                             # personal response-time metrics from local history
+/jtb stats --days=14                   # extend lookback window (Pro, max 30)
+/jtb stats --format=json               # JSON output for scripting
 /jtb collisions                        # show branch collisions with teammates (Team)
 /jtb collisions --json                 # machine-readable output
 ```

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

@@ -529,6 +529,49 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   const printFn = opts.print ?? ((s) => process.stdout.write(s));
   printFn(summary + '\n');
+
+  // Inline stats footer — shown when ≥2 triage runs exist (non-fatal)
+  try {
+    const metricsInjector = opts.metricsInjector;
+    let metrics;
+    if (metricsInjector) {
+      metrics = metricsInjector();
+    } else {
+      const { computeResponseMetrics } = await import('./lib/triage-history.mjs');
+      metrics = computeResponseMetrics(profileName ?? 'default', { days: 7, configDir });
+    }
+    // Only show footer when there's a meaningful metric to display
+    const hasAvg = metrics && metrics.avgResponseHours !== null;
+    const hasClearRate = metrics && metrics.clearRate !== null;
+    if (metrics && metrics.triageRunCount >= 2 && (hasAvg || hasClearRate)) {
+      const usePlain = args.includes('--plain') || !process.stdout.isTTY;
+      const runs = metrics.triageRunCount;
+
+      let part;
+      if (hasAvg && hasClearRate) {
+        part = `avg ${metrics.avgResponseHours.toFixed(1)}h response · ${Math.round(metrics.clearRate * 100)}% cleared within 24h (${runs} runs)`;
+      } else if (hasAvg) {
+        part = `avg ${metrics.avgResponseHours.toFixed(1)}h response (${runs} runs)`;
+      } else {
+        part = `${Math.round(metrics.clearRate * 100)}% cleared within 24h (${runs} runs)`;
+      }
+
+      if (usePlain) {
+        printFn(`── This week: ${part} ──\n`);
+      } else {
+        const { dim, bold: boldFn, cyan } = await import('./lib/ansi.mjs');
+        let styledPart;
+        if (hasAvg && hasClearRate) {
+          styledPart = `avg ${boldFn(cyan(metrics.avgResponseHours.toFixed(1) + 'h'))} response · ${boldFn(Math.round(metrics.clearRate * 100) + '%')} cleared within 24h (${runs} runs)`;
+        } else if (hasAvg) {
+          styledPart = `avg ${boldFn(cyan(metrics.avgResponseHours.toFixed(1) + 'h'))} response (${runs} runs)`;
+        } else {
+          styledPart = `${boldFn(Math.round(metrics.clearRate * 100) + '%')} cleared within 24h (${runs} runs)`;
+        }
+        printFn(`${dim('──')} This week: ${styledPart} ${dim('──')}\n`);
+      }
+    }
+  } catch { /* non-fatal */ }
 }
 
 // Run if invoked directly

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

@@ -114,6 +114,10 @@ export function parseCommand(args) {
     return { command: 'history', args: args.slice(1) };
   }
 
+  if (first === 'stats') {
+    return { command: 'stats', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

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

@@ -43,6 +43,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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]')}`,
     `    ${s.brand('ticketlens')} history ${s.dim('<TICKET-KEY>')}       Urgency timeline for a ticket  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} stats ${s.dim('[options]')}            Personal response-time metrics from local history`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}     Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}           Activate a license key`,
@@ -688,6 +689,36 @@ export function printCollisionsHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printStatsHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('stats')} ${s.dim('[--days=N] [--format=plain|json] [--profile=NAME]')}`,
+    '',
+    `  Show response-time and triage-cadence metrics from your local triage history.`,
+    `  Reads daily snapshots captured by ${s.brand('ticketlens triage --push')} or the CLI.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    // visible widths: "--days=N"=8, "--format=plain"=14, "--format=json"=13,
+    // "--profile=NAME"=14, "-h, --help"=10  →  target col = 19
+    `    ${s.brand('--days')}=${s.dim('N')}           Lookback window in days  ${s.dim('(default: 7, Free max: 7, Pro max: 30)')}`,
+    `    ${s.brand('--format')}=${s.dim('plain')}     Human-readable table  ${s.dim('(default)')}`,
+    `    ${s.brand('--format')}=${s.dim('json')}      JSON output for scripting/piping`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')}     Use a specific tracker profile`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens stats`,
+    `    ${s.dim('$')} ticketlens stats --days=14             ${s.dim('# Pro only')}`,
+    `    ${s.dim('$')} ticketlens stats --format=json | jq .`,
+    `    ${s.dim('$')} ticketlens stats --profile=myteam`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printStandupHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

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

@@ -0,0 +1,122 @@
+import { computeResponseMetrics, DEFAULT_CONFIG_DIR } from './triage-history.mjs';
+import { loadProfiles } from './profile-resolver.mjs';
+import { isLicensed as defaultIsLicensed } from './license.mjs';
+import { createStyler } from './ansi.mjs';
+import { handleUnknownFlags } from './arg-validator.mjs';
+import { printStatsHelp } from './help.mjs';
+
+const FREE_DAYS_CAP = 7;
+const MAX_DAYS = 30;
+
+export async function runStats(args = [], opts = {}) {
+  const print     = opts.print            ?? ((s) => process.stdout.write(s));
+  const warn      = opts.warn             ?? ((s) => process.stderr.write(s));
+  const configDir = opts.configDir        ?? DEFAULT_CONFIG_DIR;
+  const isLic     = opts.isLicensed       ?? defaultIsLicensed;
+  const calcMetrics = opts.metricsCalculator ?? computeResponseMetrics;
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printStatsHelp();
+    return;
+  }
+
+  const validated = await handleUnknownFlags(
+    args,
+    ['--help', '-h', '--profile=', '--days=', '--format='],
+    { hints: [] },
+  );
+  if (validated === null) { process.exitCode = 1; return; }
+
+  const profileArg = args.find(a => a.startsWith('--profile='));
+  const daysArg    = args.find(a => a.startsWith('--days='));
+  const formatArg  = args.find(a => a.startsWith('--format='));
+
+  const format = formatArg ? formatArg.split('=')[1] : 'plain';
+  if (format !== 'plain' && format !== 'json') {
+    warn(`Error: --format must be plain or json, got: ${format}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const rawDays = daysArg ? daysArg.split('=')[1] : '7';
+  const parsedDays = parseInt(rawDays, 10);
+  if (isNaN(parsedDays) || parsedDays < 1 || parsedDays > MAX_DAYS) {
+    warn(`Error: --days must be between 1 and ${MAX_DAYS}, got: ${rawDays}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Free tier: silently cap at 7 days
+  const isPro = isLic('pro', configDir);
+  const days  = (!isPro && parsedDays > FREE_DAYS_CAP) ? FREE_DAYS_CAP : parsedDays;
+
+  // Resolve profile name
+  let profile = profileArg ? profileArg.split('=')[1] : null;
+  if (!profile) {
+    const config = loadProfiles(configDir);
+    profile = config?.default ?? 'default';
+  }
+
+  let metrics;
+  try {
+    metrics = calcMetrics(profile, { days, configDir });
+  } catch (err) {
+    warn(`Error: Could not compute stats for profile "${profile}": ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (format === 'json') {
+    print(JSON.stringify({ profile, ...metrics }, null, 2) + '\n');
+    return;
+  }
+
+  const isTTY = process.stdout.isTTY;
+  const s = createStyler({ isTTY });
+
+  if (metrics.triageRunCount === 0) {
+    print(`\n  ${s.dim('No triage history found for profile')} ${s.bold(profile)}.\n`);
+    print(`  ${s.dim('Run')} ${s.cyan('ticketlens triage')} ${s.dim('at least twice to generate stats.')}\n\n`);
+    return;
+  }
+
+  const fmtH   = (h) => h != null ? `${h.toFixed(1)}h` : '—';
+  const fmtPct = (r) => r != null ? `${Math.round(r * 100)}%` : '—';
+  const fmtTrend = (t) => {
+    if (t == null) return '';
+    const abs = Math.abs(t).toFixed(1);
+    return t > 0
+      ? s.dim(`  ↑ +${abs}h vs prior week`)
+      : s.dim(`  ↓ -${abs}h vs prior week`);
+  };
+
+  const W = 52;
+  const bar = s.dim('─'.repeat(W));
+  const dayLabel = `last ${days} day${days === 1 ? '' : 's'}`;
+
+  print('\n');
+  print(`${bar}\n`);
+  print(`  ${s.bold('Response Metrics')} ${s.dim(`(${dayLabel})`)}\n`);
+  print(`${bar}\n`);
+  print(`  Avg response time    ${s.bold(s.cyan(fmtH(metrics.avgResponseHours)))}${fmtTrend(metrics.trendHours)}\n`);
+  print(`  Median response time ${s.bold(fmtH(metrics.medianResponseHours))}\n`);
+  print(`  Clear rate           ${s.bold(fmtPct(metrics.clearRate))}  ${s.dim('(resolved within 24h)')}\n`);
+  print(`  Triage runs          ${s.bold(String(metrics.triageRunCount))} ${s.dim(`of ${days} days`)}\n`);
+
+  if (metrics.currentUrgency) {
+    const u = metrics.currentUrgency;
+    print(`${bar}\n`);
+    print(`  ${s.bold('Right now')}\n`);
+    print(`${bar}\n`);
+    if (u.needsResponse > 0) print(`  ${s.red('needs-response')}  ${s.bold(String(u.needsResponse))}\n`);
+    if (u.aging > 0)         print(`  ${s.yellow('aging')}           ${s.bold(String(u.aging))}\n`);
+    print(`  ${s.green('clear')}           ${s.bold(String(u.clear))}\n`);
+  }
+
+  if (!isPro) {
+    print(`${bar}\n`);
+    print(`  ${s.dim('💡 Pro unlocks --days up to 30 days · $9/mo →')} ${s.cyan('ticketlens.dev')}\n`);
+  }
+
+  print('\n');
+}

package/skills/jtb/scripts/lib/ticket-payload.mjs

@@ -11,6 +11,9 @@ export function buildTicketPayload(scored, rawMap, baseUrl) {
     assignee: raw?.assignee ?? null,
     attention_score: null,
     flags: scored.urgency === 'clear' ? [] : [scored.urgency],
+    // last_comment_at feeds server-side response-time metrics (F19c).
+    // null for custom-rule overrides (urgency forced without a real comment).
+    last_comment_at: scored.lastComment?.created ?? null,
     compliance_coverage: null,
     compliance_status: 'unknown',
     url: baseUrl ? `${baseUrl}/browse/${scored.ticketKey}` : null,