ticketlens 0.1.0

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

@@ -0,0 +1,63 @@
+/**
+ * Shared constants and utilities used across multiple TicketLens modules.
+ * Single source of truth — import from here, do not redefine locally.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+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. */
+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'));
+    _version = pkg.version || '0.0.0';
+  } catch {
+    _version = '0.0.0';
+  }
+  return _version;
+}
+
+/** Human-readable relative time from an ISO date string. */
+export function timeAgo(dateStr) {
+  if (!dateStr) return '';
+  const diff = Date.now() - new Date(dateStr).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+/** Collapse newlines and truncate to max visible characters. */
+export function truncate(str, max) {
+  if (!str) return '';
+  const oneLine = str.replace(/[\r\n]+/g, ' ').trim();
+  if (oneLine.length <= max) return oneLine;
+  return oneLine.slice(0, max - 3) + '...';
+}
+
+/** Strip carriage returns, preserving all other whitespace. */
+export function stripCr(str) {
+  if (!str) return '';
+  return str.replace(/\r/g, '');
+}
+
+/**
+ * Build the env-like object expected by jira-client functions.
+ * @param {{ baseUrl: string, pat?: string, email?: string, apiToken?: string }} conn
+ * @returns {{ JIRA_BASE_URL: string, JIRA_PAT?: string, JIRA_EMAIL?: string, JIRA_API_TOKEN?: string }}
+ */
+export function buildJiraEnv(conn) {
+  return {
+    JIRA_BASE_URL: conn.baseUrl,
+    ...(conn.pat ? { JIRA_PAT: conn.pat } : { JIRA_EMAIL: conn.email, JIRA_API_TOKEN: conn.apiToken }),
+  };
+}

package/skills/jtb/scripts/lib/diff-analyzer.mjs

@@ -0,0 +1,66 @@
+/**
+ * Maps a list of requirements to FOUND / NOT_FOUND / PARTIAL status
+ * against a git diff string, using keyword heuristics.
+ */
+
+const STOP_WORDS = new Set([
+  'the','a','an','is','are','be','was','were','been','being',
+  'have','has','had','do','does','did','will','would','could','should',
+  'may','might','must','shall','and','or','but','in','on','at','to',
+  'for','of','with','by','from','as','it','its','that','this','these',
+  'those','not','no','if','when','then','given','user','system','api',
+]);
+
+function keywords(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w));
+}
+
+function defaultAnalyzer(requirement, diff) {
+  if (!diff) return 'NOT_FOUND';
+  const kws = keywords(requirement);
+  if (kws.length === 0) return 'NOT_FOUND';
+  const diffLower = diff.toLowerCase();
+  const matched = kws.filter(k => diffLower.includes(k));
+  if (matched.length === 0) return 'NOT_FOUND';
+  if (matched.length >= 3 || matched.length >= kws.length * 0.6) return 'FOUND';
+  return 'PARTIAL';
+}
+
+function defaultEvidence(requirement, diff) {
+  if (!diff) return null;
+  const kws = keywords(requirement);
+  const lines = diff.split('\n');
+  for (const kw of kws) {
+    const match = lines.find(l => l.toLowerCase().includes(kw));
+    if (match) return match.trim().slice(0, 80);
+  }
+  return null;
+}
+
+export function analyzeDiff(requirements, diff, opts = {}) {
+  if (!requirements || requirements.length === 0) {
+    return { results: [], coveragePercent: 0 };
+  }
+
+  const analyzerFn = opts.analyzerFn ?? defaultAnalyzer;
+
+  const results = requirements.map(requirement => {
+    const status   = analyzerFn(requirement, diff);
+    const evidence = status !== 'NOT_FOUND' ? defaultEvidence(requirement, diff) : null;
+    return { requirement, status, evidence };
+  });
+
+  const score = results.reduce((sum, r) => {
+    if (r.status === 'FOUND')    return sum + 1;
+    if (r.status === 'PARTIAL')  return sum + 0.5;
+    return sum;
+  }, 0);
+
+  const coveragePercent = Math.round((score / results.length) * 100);
+
+  return { results, coveragePercent };
+}

package/skills/jtb/scripts/lib/drift-tracker.mjs

@@ -0,0 +1,120 @@
+/**
+ * Spec drift detection: compares key ticket fields against a stored snapshot
+ * to detect when a ticket's status, description, or requirements have changed.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fsDefault from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { extractRequirements } from './requirement-extractor.mjs';
+
+/**
+ * Validate that a path component does not contain traversal sequences.
+ * @param {string} value
+ * @param {'profile'|'ticket key'} label
+ */
+function assertSafe(value, label) {
+  if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+    throw new Error(`Invalid ${label}`);
+  }
+}
+
+/**
+ * Get the current git branch name.
+ * @param {{ execFn?: Function, cwd?: string }} opts
+ * @returns {string} Branch name, 'DETACHED' for detached HEAD, '' if not in a git repo.
+ */
+export function getCurrentBranch({ execFn = spawnSync, cwd } = {}) {
+  const spawnOpts = { encoding: 'utf8' };
+  if (cwd) spawnOpts.cwd = cwd;
+  const result = execFn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], spawnOpts);
+  if (result.status !== 0) return '';
+  const branch = (result.stdout ?? '').trim();
+  return branch === 'HEAD' ? 'DETACHED' : branch;
+}
+
+/**
+ * Read a stored snapshot for the given ticket + profile.
+ * @param {string} ticketKey
+ * @param {{ profile?: string, configDir?: string, fsModule?: object }} opts
+ * @returns {object|null}
+ */
+export function readSnapshot(ticketKey, { profile = 'default', configDir = DEFAULT_CONFIG_DIR, fsModule = fsDefault } = {}) {
+  assertSafe(profile, 'profile name');
+  assertSafe(ticketKey, 'ticket key');
+  const filePath = join(configDir, 'drift', profile, `${ticketKey}.json`);
+  try {
+    const raw = fsModule.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a snapshot for the given ticket + profile.
+ * @param {string} ticketKey
+ * @param {object} ticket  Raw Jira ticket object from fetchTicket()
+ * @param {{ profile?: string, configDir?: string, fsModule?: object, branch?: string }} opts
+ */
+export function writeSnapshot(ticketKey, ticket, { profile = 'default', configDir = DEFAULT_CONFIG_DIR, fsModule = fsDefault, branch = '' } = {}) {
+  assertSafe(profile, 'profile name');
+  assertSafe(ticketKey, 'ticket key');
+  const dir = join(configDir, 'drift', profile);
+  fsModule.mkdirSync(dir, { recursive: true });
+  const desc = ticket.fields?.description ?? '';
+  const descriptionHash = createHash('sha256').update(desc).digest('hex');
+  const requirements = extractRequirements(desc);
+  const snapshot = {
+    fetchedAt: new Date().toISOString(),
+    branch,
+    status: ticket.fields?.status?.name ?? '',
+    descriptionHash,
+    requirements,
+  };
+  fsModule.writeFileSync(join(dir, `${ticketKey}.json`), JSON.stringify(snapshot, null, 2), 'utf8');
+}
+
+/**
+ * Compare current ticket fields against a prior snapshot.
+ * @param {{ status: string, descriptionHash: string, requirements: string[] }} current
+ * @param {object|null} prior  Snapshot object, or null if no prior snapshot exists.
+ * @returns {{ drifted: boolean, changes: string[] }}
+ */
+export function detectDrift(current, prior) {
+  if (!prior) return { drifted: false, changes: [] };
+
+  const changes = [];
+
+  if (current.status !== prior.status) {
+    changes.push(`status: "${prior.status}" \u2192 "${current.status}"`);
+  }
+
+  if (current.descriptionHash !== prior.descriptionHash) {
+    changes.push('description changed');
+  }
+
+  const priorReqCount = Array.isArray(prior.requirements) ? prior.requirements.length : 0;
+  const currentReqCount = Array.isArray(current.requirements) ? current.requirements.length : 0;
+  if (currentReqCount !== priorReqCount) {
+    changes.push(`requirements: ${priorReqCount} \u2192 ${currentReqCount}`);
+  }
+
+  return { drifted: changes.length > 0, changes };
+}
+
+/**
+ * Format a drift warning string for output to stderr.
+ * @param {string} ticketKey
+ * @param {string[]} changes
+ * @returns {string}
+ */
+export function formatDriftWarning(ticketKey, changes) {
+  const lines = [`  \u26a0  ${ticketKey} spec drift detected:`];
+  for (const change of changes) {
+    lines.push(`  \u2022 ${change}`);
+  }
+  return lines.join('\n') + '\n';
+}

package/skills/jtb/scripts/lib/error-classifier.mjs

@@ -0,0 +1,119 @@
+/**
+ * Classifies fetch/HTTP errors into user-friendly messages with actionable hints.
+ * Extracts cause codes from Node.js fetch errors and HTTP status from Jira API errors.
+ */
+
+function getNetworkCode(err) {
+  // Node fetch wraps the real error in err.cause
+  const cause = err.cause || err;
+  return cause.code || cause.errno || null;
+}
+
+function getHostname(baseUrl) {
+  try { return new URL(baseUrl).hostname; } catch { return baseUrl; }
+}
+
+export function classifyError(err, { baseUrl, profileName } = {}) {
+  const host = baseUrl ? getHostname(baseUrl) : 'the Jira server';
+  const profile = profileName || 'your profile';
+  const code = getNetworkCode(err);
+
+  // Network-level errors (fetch threw before getting an HTTP response)
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+    return {
+      message: `DNS lookup failed for ${host}`,
+      hint: 'Check your internet connection. If this is a private server, make sure your VPN is connected.',
+    };
+  }
+
+  if (code === 'ECONNREFUSED') {
+    return {
+      message: `Connection refused by ${host}`,
+      hint: 'The server is not accepting connections. Check if the Jira instance is running and the URL is correct.',
+    };
+  }
+
+  if (code === 'ECONNRESET' || code === 'ECONNABORTED') {
+    return {
+      message: `Connection to ${host} was reset`,
+      hint: 'This often happens when a VPN drops or a firewall blocks the connection. Check your VPN status.',
+    };
+  }
+
+  if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT') {
+    return {
+      message: `Connection to ${host} timed out`,
+      hint: `The server didn't respond. If ${host} requires a VPN, make sure it's connected.`,
+    };
+  }
+
+  // AbortSignal.timeout() fires a DOMException with name 'TimeoutError' as err.cause
+  const causeName = (err.cause || err).name;
+  if (causeName === 'TimeoutError') {
+    return {
+      message: `Connection to ${host} timed out`,
+      hint: `The server didn't respond within the allowed time. If ${host} requires a VPN, make sure it's connected.`,
+    };
+  }
+
+  if (code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' || code === 'CERT_HAS_EXPIRED' ||
+      code === 'DEPTH_ZERO_SELF_SIGNED_CERT' || code === 'ERR_TLS_CERT_ALTNAME_INVALID' ||
+      code === 'SELF_SIGNED_CERT_IN_CHAIN') {
+    return {
+      message: `SSL certificate error for ${host}`,
+      hint: 'The server has an invalid or self-signed certificate. Contact your Jira admin.',
+    };
+  }
+
+  // HTTP-level errors (got a response, but it was an error status)
+  const status = err.status || err.statusCode;
+
+  if (status === 401) {
+    return {
+      message: `Authentication failed for ${profile}`,
+      hint: 'Your credentials may have expired. Check your API token or PAT in ~/.ticketlens/credentials.json.',
+    };
+  }
+
+  if (status === 403) {
+    return {
+      message: `Access denied on ${host}`,
+      hint: 'Your account does not have permission. Check your Jira access or ask an admin.',
+    };
+  }
+
+  if (status === 404) {
+    return {
+      message: `Not found on ${host}`,
+      hint: 'The ticket or endpoint does not exist. Check the ticket key and the Jira base URL in your profile.',
+    };
+  }
+
+  if (status === 429) {
+    return {
+      message: `Rate limited by ${host}`,
+      hint: 'Too many requests. Wait a moment and try again.',
+    };
+  }
+
+  if (status && status >= 500) {
+    return {
+      message: `${host} returned a server error (${status})`,
+      hint: 'The Jira instance is having issues. Try again in a few minutes.',
+    };
+  }
+
+  // Generic fetch failure (e.g. "fetch failed" with no useful cause)
+  if (/fetch failed/i.test(err.message) || code === 'UND_ERR_SOCKET') {
+    return {
+      message: `Could not reach ${host}`,
+      hint: 'Check your internet connection. If this is a private server, make sure your VPN is connected.',
+    };
+  }
+
+  // Fallback: return the original message
+  return {
+    message: err.message,
+    hint: null,
+  };
+}

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

@@ -0,0 +1,253 @@
+/**
+ * Styled help output for TicketLens CLI.
+ */
+
+import { createStyler } from './ansi.mjs';
+import { getVersion } from './config.mjs';
+
+export function printHelp({ stream = process.stdout } = {}) {
+  const isTTY = stream.isTTY;
+  const s = createStyler({ isTTY });
+  const v = getVersion();
+
+  // Column targets (visible chars):
+  //   USAGE: command portion = 36, so descriptions always start at the same column
+  //   OPTIONS: flag portion = 19, so descriptions always start at the same column
+  //
+  // Spaces after each item are computed as: target - visibleWidth(item)
+  // ANSI codes (s.cyan, s.dim) add invisible bytes — they do NOT affect visible width.
+
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('◆ TicketLens'))} ${s.dim(`v${v}`)}`,
+    `  ${s.dim('Stop tab-switching. Start building.')}`,
+    '',
+    `  ${s.bold('USAGE')}`,
+    '',
+    // visible widths: "ticketlens init"=15, "switch"=17, "config [--profile=NAME]"=34,
+    // "profiles"=19, "<TICKET-KEY> [options]"=33, "triage [options]"=27,
+    // "activate <KEY>"=25, "license"=18, "cache [size|clear]"=29  →  target=36
+    // Groups: Setup ─── Daily use ─── Account / Maintenance
+    `    ${s.brand('ticketlens')} init                     Configure Jira connections`,
+    `    ${s.brand('ticketlens')} switch                   Switch active profile`,
+    `    ${s.brand('ticketlens')} config ${s.dim('[--profile=NAME]')}  Edit profile settings`,
+    `    ${s.brand('ticketlens')} profiles                 List all configured profiles  ${s.dim('(alias: ls)')}`,
+    '',
+    `    ${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')} compliance ${s.dim('<TICKET-KEY>')}    Check requirements coverage  ${s.dim('[Pro/Free 3/mo]')}`,
+    '',
+    `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}     Remove a profile`,
+    `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}           Activate a license key`,
+    `    ${s.brand('ticketlens')} license                  Show license status`,
+    `    ${s.brand('ticketlens')} cache ${s.dim('[size|clear]')}       Manage attachment cache  ${s.dim('(try cache --help)')}`,
+    `    ${s.brand('ticketlens')} schedule ${s.dim('[--stop|--status]')} Manage digest schedule  ${s.dim('[Pro]')}`,
+    '',
+    `  ${s.bold('FETCH OPTIONS')}`,
+    '',
+    // visible widths: "--profile=NAME"=14, "--depth=N"=9, "--plain"=7, "--styled"=8,
+    // "--no-attachments"=16, "--no-cache"=10  →  target=19
+    `    ${s.brand('--profile')}=${s.dim('NAME')}     Use a specific Jira profile`,
+    `    ${s.brand('--depth')}=${s.dim('N')}          Traversal depth ${s.dim('(0=ticket only, 1=+linked, 2=deep)')}`,
+    `    ${s.brand('--plain')}            Plain markdown output ${s.dim('(for piping / LLM)')}`,
+    `    ${s.brand('--styled')}           Force ANSI-styled output`,
+    `    ${s.brand('--no-attachments')}   Skip downloading attachments`,
+    `    ${s.brand('--no-cache')}         Re-download attachments even if cached`,
+    `    ${s.brand('--check')}            Append VCS diff + review instructions for Claude Code`,
+    `    ${s.brand('--compliance')}       Check ticket requirements against local diff  ${s.dim('[Pro/Free 3/mo]')}`,
+    `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
+    `    ${s.brand('--cloud')}            Route summary through TicketLens API ${s.dim('[Pro]')}`,
+    '',
+    `  ${s.bold('TRIAGE OPTIONS')}`,
+    '',
+    // visible widths: "--profile=NAME"=14, "--stale=N"=9, "--status=X,Y"=12,
+    // "--assignee=NAME"=15, "--sprint=NAME"=13, "--static"=8, "--plain"=7  →  target=19
+    `    ${s.brand('--profile')}=${s.dim('NAME')}     Use a specific Jira profile`,
+    `    ${s.brand('--stale')}=${s.dim('N')}          Aging threshold in days ${s.dim('(default: 5)')}`,
+    `    ${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('--export')}=${s.dim('FORMAT')}   Export results to file  ${s.dim('(csv|json) [Team]')}`,
+    `    ${s.brand('--digest')}           POST scored results to digest endpoint  ${s.dim('[Pro]')}`,
+    `    ${s.brand('--static')}           Static table output ${s.dim('(skip interactive mode)')}`,
+    `    ${s.brand('--plain')}            Plain markdown output ${s.dim('(for piping / LLM)')}`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens PROJ-123`,
+    `    ${s.dim('$')} ticketlens get PROJ-123 --depth=0 --profile=myteam`,
+    `    ${s.dim('$')} ticketlens triage`,
+    `    ${s.dim('$')} ticketlens triage --profile=acme --stale=3`,
+    `    ${s.dim('$')} ticketlens triage --static`,
+    '',
+    `  ${s.bold('CONFIGURATION')}`,
+    '',
+    `    ${s.dim('Profiles:')}     ~/.ticketlens/profiles.json`,
+    `    ${s.dim('Credentials:')}  ~/.ticketlens/credentials.json`,
+    `    ${s.dim('License:')}      ~/.ticketlens/license.json`,
+    '',
+    `    ${s.dim('Or use env vars:')} JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN`,
+    '',
+    '',
+  ];
+
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printFetchHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('<TICKET-KEY>')} ${s.dim('[options]')}`,
+    '',
+    `  Fetch a Jira ticket's full context: description, comments,`,
+    `  linked issues, and code references.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--profile')}=${s.dim('NAME')}     Use a specific Jira profile`,
+    // visible widths: "--profile=NAME"=14, "--depth=N"=9, "--plain"=7, "--styled"=8,
+    // "--no-attachments"=16, "--no-cache"=10, "-h, --help"=10  →  target=19
+    `    ${s.brand('--depth')}=${s.dim('N')}          Traversal depth ${s.dim('(default: 1)')}`,
+    `                       ${s.dim('0 = target ticket only')}`,
+    `                       ${s.dim('1 = + linked ticket details')}`,
+    `                       ${s.dim('2 = + linked-of-linked')}`,
+    `    ${s.brand('--plain')}            Plain markdown output`,
+    `    ${s.brand('--styled')}           Force ANSI-styled output`,
+    `    ${s.brand('--no-attachments')}   Skip downloading attachments`,
+    `    ${s.brand('--no-cache')}         Re-download attachments even if cached`,
+    `    ${s.brand('--check')}            Append VCS diff + review instructions for Claude Code`,
+    `    ${s.brand('--compliance')}       Check ticket requirements against local diff  ${s.dim('[Pro/Free 3/mo]')}`,
+    `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
+    `    ${s.brand('--cloud')}            Route summary through TicketLens API ${s.dim('[Pro]')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens PROJ-123`,
+    `    ${s.dim('$')} ticketlens PROJ-123 --depth=0`,
+    `    ${s.dim('$')} ticketlens PROJ-123 --profile=acme --depth=2`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+const ANSI_RE_HELP = /\x1b\[[0-9;]*m/g;
+function padRightVis(str, len) {
+  const vis = str.replace(ANSI_RE_HELP, '').length;
+  return str + ' '.repeat(Math.max(0, len - vis));
+}
+
+export function printProfiles({ stream = process.stdout, config, plain = false } = {}) {
+  const isTTY = !plain && stream.isTTY;
+  const s = createStyler({ isTTY });
+  const profiles = config?.profiles || {};
+  const names = Object.keys(profiles);
+
+  if (names.length === 0) {
+    stream.write(`\n  No profiles configured.\n  Run ${s.cyan('ticketlens init')} to set one up.\n\n`);
+    return;
+  }
+
+  // Active = explicitly set default, else first profile in file
+  const active = config?.default || names[0];
+  const defaultIsExplicit = !!config?.default;
+
+  const getData = (name) => {
+    const p = profiles[name];
+    return {
+      prefixes: (p.ticketPrefixes || []).join(', ') || '—',
+      statuses: (p.triageStatuses || []).join(', ') || '—',
+      url: p.baseUrl || '',
+    };
+  };
+
+  if (plain) {
+    for (const name of names) {
+      const { url, prefixes, statuses } = getData(name);
+      stream.write(`${name}\t${name === active ? 'active' : 'inactive'}\t${url}\t${prefixes}\t${statuses}\n`);
+    }
+    return;
+  }
+
+  const MAX_STATUS_W = 45;
+  const nameW = Math.max('Profile'.length, ...names.map(n => n.length));
+  const urlW = Math.max('URL'.length, ...names.map(n => getData(n).url.length));
+  const prefW = Math.max('Prefixes'.length, ...names.map(n => getData(n).prefixes.length));
+
+  // Header + separator (4 chars before name = 2 leading + indicator + space)
+  const hdr = `    ${padRightVis('Profile', nameW + 2)}${padRightVis('URL', urlW + 2)}${padRightVis('Prefixes', prefW + 2)}Statuses`;
+  const sep = `    ${'─'.repeat(nameW).padEnd(nameW + 2)}${'─'.repeat(urlW).padEnd(urlW + 2)}${'─'.repeat(prefW).padEnd(prefW + 2)}${'─'.repeat('Statuses'.length)}`;
+
+  const lines = ['', s.dim(hdr), s.dim(sep)];
+
+  for (const name of names) {
+    const { url, prefixes, statuses } = getData(name);
+    const isActive = name === active;
+    const indicator = isActive ? s.green('●') : s.dim('○');
+    const nameStyled = isActive ? s.bold(s.cyan(name)) : name;
+    const statusDisplay = statuses.length > MAX_STATUS_W
+      ? statuses.slice(0, MAX_STATUS_W - 1) + '…'
+      : statuses;
+    lines.push(
+      `  ${indicator} ` +
+      padRightVis(nameStyled, nameW + 2) +
+      url.padEnd(urlW + 2) +
+      prefixes.padEnd(prefW + 2) +
+      statusDisplay
+    );
+  }
+  lines.push('');
+
+  const activeNote = defaultIsExplicit
+    ? `${s.dim('Active:')} ${s.cyan(active)}`
+    : `${s.dim('Active:')} ${s.cyan(active)} ${s.dim('(first — run ticketlens switch to set default)')}`;
+  lines.push(`  ${activeNote}  ${s.dim('·  ticketlens switch  ·  ticketlens config --profile=NAME')}`);
+  lines.push('');
+
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printTriageHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('triage')} ${s.dim('[options]')}`,
+    '',
+    `  Scan your assigned Jira tickets and surface what needs attention.`,
+    `  Opens an interactive navigator in TTY mode.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    // visible widths: "--profile=NAME"=14, "--stale=N"=9, "--status=X,Y"=12,
+    // "--assignee=NAME"=15, "--sprint=NAME"=13, "--static"=8, "--plain"=7, "-h, --help"=10  →  target=19
+    `    ${s.brand('--profile')}=${s.dim('NAME')}     Use a specific Jira profile`,
+    `    ${s.brand('--stale')}=${s.dim('N')}          Aging threshold in days ${s.dim('(default: 5)')}`,
+    `    ${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('--export')}=${s.dim('FORMAT')}    Export results to file  ${s.dim('(csv|json) [Team]')}`,
+    `    ${s.brand('--digest')}           POST scored results to digest endpoint  ${s.dim('[Pro]')}`,
+    `    ${s.brand('--static')}           Static table output ${s.dim('(skip interactive mode)')}`,
+    `    ${s.brand('--plain')}            Plain markdown output`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens triage`,
+    `    ${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 --static`,
+    '',
+    `  ${s.bold('INTERACTIVE MODE')}`,
+    '',
+    `    ${s.dim('↑/↓')}    Navigate tickets`,
+    `    ${s.dim('Enter')}  Open ticket in browser`,
+    `    ${s.dim('p')}      Switch profile`,
+    `    ${s.dim('q/Esc')}  Exit`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}