ticketlens 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.8.0",
+  "version": "0.9.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.8.0 -->
+<!-- jtb-skill-version: 0.9.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.
@@ -72,6 +72,12 @@ node ~/.agents/skills/jtb/scripts/fetch-my-tickets.mjs $EXTRA_ARGS
 
 Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=acme`).
 
+**Urgency levels** (highest → lowest priority):
+- 🔴 `needs-response` — someone commented and you haven't replied
+- 🟡 `aging` — no activity for ≥ `staleDays` (default 5d)
+- 🔵 `stale` — ticket stuck in the same Jira status for ≥ N days (Pro — requires a stale rule configured in the Console)
+- 🟢 `clear` — up to date, no action needed
+
 **IMPORTANT:** Copy the script's stdout and display it directly as your response text (not inside a tool result). This ensures the markdown table renders visibly and URLs are clickable in the terminal. No VCS enrichment, no plan mode. Stop here.
 
 ---

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

@@ -293,8 +293,13 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   session.spin(`Connecting to ${session.label}…`);
 
   // Fire both requests concurrently — they are independent of each other
+  // expandChangelog is derived from staleRule, which the sync API only sends to Pro/Team/Enterprise
+  // users. A user who manually adds staleRule to their local profile.json would still expand
+  // their own Jira data — that is acceptable (Jira credentials are theirs; we gate TicketLens
+  // features server-side, not Jira API access).
+  const expandChangelog = !!(conn.staleRule?.enabled);
   const userPromise = adapter.fetchCurrentUser();
-  const ticketsPromise = adapter.searchTickets(jql);
+  const ticketsPromise = adapter.searchTickets(jql, { expandChangelog });
 
   let currentUser;
   try {
@@ -407,7 +412,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     process.stderr.write(`Viewing ${assigneeName}'s tickets\n\n`);
   }
 
-  const scored = tickets.map(t => scoreAttention(t, effectiveUser, { staleDays, customRules: conn.attentionRules }));
+  const scored = tickets.map(t => scoreAttention(t, effectiveUser, { staleDays, customRules: conn.attentionRules, staleRule: conn.staleRule ?? null }));
   const actionable = scored.filter(s => s.urgency !== 'clear' && s.urgency !== 'ignore');
   const sorted = sortByUrgency(actionable);
   const rawTicketMap = new Map(tickets.map(t => [t.key, t]));

package/skills/jtb/scripts/lib/attention-scorer.mjs

@@ -97,7 +97,7 @@ function applyCustomRule(ticket, rule) {
 }
 
 export function scoreAttention(ticket, currentUser, opts = {}) {
-  const { staleDays = 5, now = new Date(), customRules } = opts;
+  const { staleDays = 5, now = new Date(), customRules, staleRule } = opts;
 
   // Custom rules evaluated first — first match wins
   if (Array.isArray(customRules)) {
@@ -162,6 +162,27 @@ export function scoreAttention(ticket, currentUser, opts = {}) {
     }
   }
 
+  // Stale check — only when rule is active and statusChangedAt was captured via changelog expand.
+  // Runs as final gate so needs-response and aging always take precedence.
+  if (staleRule?.enabled && ticket.statusChangedAt) {
+    const daysInCurrentStatus = (now - new Date(ticket.statusChangedAt)) / (1000 * 60 * 60 * 24);
+    if (
+      daysInCurrentStatus >= (staleRule.stale_days ?? 14) &&
+      Array.isArray(staleRule.statuses) &&
+      staleRule.statuses.includes(ticket.status)
+    ) {
+      return {
+        ticketKey: ticket.key,
+        summary: ticket.summary,
+        status: ticket.status,
+        urgency: 'stale',
+        reason: `Stuck in '${ticket.status}' for ${Math.floor(daysInCurrentStatus)}d`,
+        lastComment,
+        daysInCurrentStatus: Math.floor(daysInCurrentStatus),
+      };
+    }
+  }
+
   return {
     ticketKey: ticket.key,
     summary: ticket.summary,
@@ -172,7 +193,7 @@ export function scoreAttention(ticket, currentUser, opts = {}) {
   };
 }
 
-const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
+export const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'stale': 2, 'clear': 3 };
 
 export function sortByUrgency(scores) {
   return [...scores].sort((a, b) => {

package/skills/jtb/scripts/lib/brief-assembler.mjs

@@ -103,6 +103,7 @@ export function assembleTriageSummary(scoredTickets, opts = {}) {
 
   const needsResponse = actionable.filter(t => t.urgency === 'needs-response');
   const aging = actionable.filter(t => t.urgency === 'aging');
+  const stale = actionable.filter(t => t.urgency === 'stale');
   const allKeys = [];
 
   if (needsResponse.length > 0) {
@@ -129,13 +130,28 @@ export function assembleTriageSummary(scoredTickets, opts = {}) {
       return [String(agingOffset + i + 1), t.ticketKey, truncate(t.summary, 50), t.status, `${days}d`];
     });
     const table = formatTable(
-      ['#', 'Ticket', 'Summary', 'Status', 'Stale'],
+      ['#', 'Ticket', 'Summary', 'Status', 'Idle'],
       tableRows,
       { maxWidths: { 2: 50 } },
     );
     sections.push(`Aging — no activity > ${staleDays} days (${aging.length})\n\n${table}`);
   }
 
+  if (stale.length > 0) {
+    const staleOffset = needsResponse.length + aging.length;
+    const tableRows = stale.map((t, i) => {
+      allKeys.push(t.ticketKey);
+      const days = t.daysInCurrentStatus ?? '?';
+      return [String(staleOffset + i + 1), t.ticketKey, truncate(t.summary, 50), t.status, `${days}d`];
+    });
+    const table = formatTable(
+      ['#', 'Ticket', 'Summary', 'Status', 'Stuck'],
+      tableRows,
+      { maxWidths: { 2: 50 } },
+    );
+    sections.push(`Stale — stuck in same status (${stale.length})\n\n${table}`);
+  }
+
   if (browseUrl && allKeys.length > 0) {
     const links = allKeys.map((k, i) => `[${i + 1}] ${k}: ${browseUrl}${k}`);
     sections.push(`Quick Links\n\n${links.join('\n')}`);

package/skills/jtb/scripts/lib/jira-client.mjs

@@ -12,19 +12,44 @@ function toText(value) {
   return adfToText(value);
 }
 
+/**
+ * Returns the ISO date string when the ticket entered its current status,
+ * derived from Jira's changelog history. Walks backwards (most recent first)
+ * to find the last transition whose `toString` matches `currentStatus`.
+ * Returns null when changelog is absent or has no matching transition.
+ */
+export function parseStatusChangedAt(changelog, currentStatus) {
+  if (!changelog?.histories?.length || !currentStatus) return null;
+  for (let i = changelog.histories.length - 1; i >= 0; i--) {
+    const history = changelog.histories[i];
+    const item = history.items?.find(it => it.field === 'status' && it.toString === currentStatus);
+    if (item) return history.created ?? null;
+  }
+  return null;
+}
+
 export function normalizeTicket(raw) {
   const f = raw.fields;
+  const currentStatus = f.status?.name ?? null;
+  // statusChangedAt: when the ticket entered its current status.
+  // Only populated when raw.changelog is present (i.e. ?expand=changelog was requested).
+  // Falls back to ticket.created when changelog is present but no matching transition exists
+  // (ticket was created in its current status and never transitioned away then back).
+  const statusChangedAt = raw.changelog !== undefined
+    ? (parseStatusChangedAt(raw.changelog, currentStatus) ?? (f.created ?? null))
+    : null;
   return {
     key: raw.key,
     summary: f.summary,
     type: f.issuetype?.name ?? null,
-    status: f.status?.name ?? null,
+    status: currentStatus,
     priority: f.priority?.name ?? null,
     assignee: f.assignee?.displayName ?? null,
     reporter: f.reporter?.displayName ?? null,
     description: toText(f.description),
     created: f.created ?? null,
     updated: f.updated ?? null,
+    statusChangedAt,
     labels: f.labels ?? [],
     components: (f.components ?? []).map(c => c.name),
     comments: (f.comment?.comments ?? []).map(c => ({
@@ -110,12 +135,13 @@ export async function fetchStatuses(opts = {}) {
 }
 
 export async function searchTickets(jql, opts = {}) {
-  const { env = process.env, fetcher = globalThis.fetch, maxResults = 50, apiVersion = 2, timeoutMs = 10_000 } = opts;
+  const { env = process.env, fetcher = globalThis.fetch, maxResults = 50, apiVersion = 2, timeoutMs = 10_000, expandChangelog = false } = opts;
   const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
   const headers = { ...buildAuthHeader(env), 'Content-Type': 'application/json' };
 
-  const fields = 'summary,status,assignee,priority,issuetype,comment,updated,statuscategorychangedate';
+  const fields = 'summary,status,assignee,priority,issuetype,comment,updated,statuscategorychangedate,created';
   const params = new URLSearchParams({ jql, fields, maxResults: String(maxResults) });
+  if (expandChangelog) params.set('expand', 'changelog');
   const endpoint = apiVersion >= 3 ? `/rest/api/3/search/jql` : `/rest/api/2/search`;
   const url = `${baseUrl}${endpoint}?${params}`;
   const fetchOpts = { headers };
@@ -153,11 +179,12 @@ export async function fetchRemoteLinks(ticketKey, opts = {}) {
 }
 
 export async function fetchTicket(ticketKey, opts = {}) {
-  const { env = process.env, fetcher = globalThis.fetch, depth = 1, apiVersion = 2, timeoutMs = 10_000, _visited = new Set(), _currentDepth = 0 } = opts;
+  const { env = process.env, fetcher = globalThis.fetch, depth = 1, apiVersion = 2, timeoutMs = 10_000, expandChangelog = false, _visited = new Set(), _currentDepth = 0 } = opts;
   const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
   const headers = { ...buildAuthHeader(env), 'Content-Type': 'application/json' };
 
-  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}`;
+  const expand = expandChangelog ? '?expand=changelog' : '';
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}${expand}`;
   const fetchOpts = { headers };
   if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
   const response = await fetcher(url, fetchOpts);
@@ -184,7 +211,8 @@ export async function fetchTicket(ticketKey, opts = {}) {
     linkedKeys.forEach(k => _visited.add(k));
 
     ticket.linkedTicketDetails = await Promise.all(
-      linkedKeys.map(k => fetchTicket(k, { ...opts, _visited, _currentDepth: _currentDepth + 1 }))
+      // Linked tickets are context only — never scored, so skip changelog expansion for them.
+      linkedKeys.map(k => fetchTicket(k, { ...opts, expandChangelog: false, _visited, _currentDepth: _currentDepth + 1 }))
     );
   }
 

package/skills/jtb/scripts/lib/profile-resolver.mjs

@@ -232,6 +232,7 @@ export function resolveConnection(ticketKey, opts = {}) {
       triageStatuses: profile.triageStatuses || null,
       ticketPrefixes: profile.ticketPrefixes || null,
       attentionRules: profile.attentionRules ?? null,
+      staleRule: profile.staleRule ?? null,
       source: 'profile',
       profileName: profile.name,
     };

package/skills/jtb/scripts/lib/styled-assembler.mjs

@@ -28,10 +28,12 @@ export function styleTriageSummary(scoredTickets, opts = {}) {
 
   const needsResponse = actionable.filter(t => t.urgency === 'needs-response');
   const aging = actionable.filter(t => t.urgency === 'aging');
+  const stale = actionable.filter(t => t.urgency === 'stale');
 
   const parts = [];
   if (needsResponse.length > 0) parts.push(`${needsResponse.length} need response`);
   if (aging.length > 0) parts.push(`${aging.length} aging`);
+  if (stale.length > 0) parts.push(`${stale.length} stale`);
 
   const sections = [];
   sections.push(s.bold(`${actionable.length} tickets need attention`) + ' ' + s.dim(`(${parts.join(', ')})`) );
@@ -40,6 +42,7 @@ export function styleTriageSummary(scoredTickets, opts = {}) {
   const legendParts = [];
   if (needsResponse.length > 0) legendParts.push(`${s.red('●')} needs response`);
   if (aging.length > 0) legendParts.push(`${s.yellow('●')} aging`);
+  if (stale.length > 0) legendParts.push(`${s.cyan('●')} stale`);
   let legend = legendParts.join('    ');
   if (browseUrl) legend += `\n${s.dim('Open:')} ${browseUrl}${s.dim('<key>')}`;
   sections.push(legend);
@@ -70,7 +73,21 @@ export function styleTriageSummary(scoredTickets, opts = {}) {
       return [String(agingOffset + i + 1), ticketCell(t.ticketKey, s.yellow), truncate(t.summary, 45), t.status, `${days}d`];
     });
     const table = formatTable(
-      ['#', 'Ticket', 'Title', 'Status', 'Stale'],
+      ['#', 'Ticket', 'Title', 'Status', 'Idle'],
+      tableRows,
+      { maxWidths: { 2: 45 } },
+    );
+    sections.push(table);
+  }
+
+  if (stale.length > 0) {
+    const staleOffset = needsResponse.length + aging.length;
+    const tableRows = stale.map((t, i) => {
+      const days = t.daysInCurrentStatus ?? '?';
+      return [String(staleOffset + i + 1), ticketCell(t.ticketKey, s.cyan), truncate(t.summary, 45), t.status, `${days}d`];
+    });
+    const table = formatTable(
+      ['#', 'Ticket', 'Title', 'Status', 'Stuck'],
       tableRows,
       { maxWidths: { 2: 45 } },
     );

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

@@ -33,6 +33,8 @@ export function serverToCliProfile(serverProfile) {
     ...(p.ticket_prefixes?.length  ? { ticketPrefixes: p.ticket_prefixes }    : {}),
     ...(p.project_paths?.length    ? { projectPaths: p.project_paths }        : {}),
     ...(p.triage_statuses?.length  ? { triageStatuses: p.triage_statuses }    : {}),
+    ...(p.stale_rule               ? { staleRule: p.stale_rule }              : {}),
+    ...(p.known_statuses?.length   ? { knownStatuses: p.known_statuses, statusesCachedAt: p.statuses_cached_at ?? null } : {}),
   };
   return { name: p.name, profileData };
 }

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,

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

@@ -10,7 +10,7 @@ import { join } from 'node:path';
 
 export const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
 
-const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
+const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'stale': 2, 'clear': 3 };
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -126,8 +126,8 @@ export function diffSnapshots(today, yesterday) {
     const changes = [];
 
     // Urgency worsened
-    const todayOrder = URGENCY_ORDER[t.urgency] ?? 2;
-    const yesterdayOrder = URGENCY_ORDER[y.urgency] ?? 2;
+    const todayOrder = URGENCY_ORDER[t.urgency] ?? 3;
+    const yesterdayOrder = URGENCY_ORDER[y.urgency] ?? 3;
     if (todayOrder < yesterdayOrder) {
       changes.push(`${y.urgency} \u2192 ${t.urgency}`);
     }
@@ -284,7 +284,7 @@ function loadSnapshotForDate(dateStr, profile, configDir, fsModule) {
  *   medianResponseHours: number|null,
  *   clearRate: number|null,
  *   triageRunCount: number,
- *   currentUrgency: { needsResponse: number, aging: number, clear: number }|null,
+ *   currentUrgency: { needsResponse: number, aging: number, stale: number, clear: number }|null,
  *   windowDays: number,
  *   trendHours: number|null,
  * }}
@@ -354,6 +354,7 @@ export function computeResponseMetrics(profile, {
     ? {
         needsResponse: latest.tickets.filter(t => t.urgency === 'needs-response').length,
         aging:         latest.tickets.filter(t => t.urgency === 'aging').length,
+        stale:         latest.tickets.filter(t => t.urgency === 'stale').length,
         clear:         latest.tickets.filter(t => t.urgency === 'clear').length,
       }
     : null;