ticketlens 0.1.0

package/skills/jtb/scripts/lib/adapters/github-adapter.mjs

@@ -0,0 +1,112 @@
+/**
+ * Parses owner and repo from a GitHub profile baseUrl.
+ * Expected format: https://github.com/OWNER/REPO
+ */
+export function parseGitHubRepo(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid GitHub baseUrl: ${baseUrl}`);
+  }
+  const parts = url.pathname.replace(/^\//, '').split('/').filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(
+      `GitHub profile baseUrl must include owner and repo: https://github.com/OWNER/REPO (got: ${baseUrl})`,
+    );
+  }
+  return { owner: parts[0], repo: parts[1] };
+}
+
+/**
+ * Maps a raw GitHub issue + comments array to the normalized ticket shape.
+ * @param {object} raw - GitHub issue object
+ * @param {object[]} comments - GitHub issue comments array
+ * @param {string} [keyPrefix] - prefix used to construct the ticket key (e.g. 'GH')
+ */
+export function normalizeGitHubIssue(raw, comments = [], keyPrefix = 'GH') {
+  return {
+    key: `${keyPrefix}-${raw.number}`,
+    summary: raw.title,
+    type: 'Issue',
+    status: raw.state,
+    priority: null,
+    assignee: raw.assignees?.[0]?.login ?? raw.assignee?.login ?? null,
+    reporter: raw.user?.login ?? null,
+    description: raw.body ?? null,
+    created: raw.created_at ?? null,
+    updated: raw.updated_at ?? null,
+    labels: (raw.labels ?? []).map(l => l.name),
+    components: [],
+    comments: comments.map(c => ({
+      author: c.user?.login ?? null,
+      authorAccountId: null,
+      authorName: c.user?.login ?? null,
+      body: c.body ?? '',
+      created: c.created_at ?? null,
+    })),
+    linkedIssues: [],
+    attachments: [],
+  };
+}
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Returns a tracker adapter backed by the GitHub Issues REST API.
+ * Profile baseUrl must be https://github.com/OWNER/REPO.
+ * Auth token stored as apiToken (or pat) in credentials.json.
+ */
+export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
+  const { owner, repo } = parseGitHubRepo(conn.baseUrl);
+  const keyPrefix = conn.ticketPrefixes?.[0] ?? 'GH';
+  const token = conn.apiToken || conn.pat;
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+
+  return {
+    type: 'github',
+
+    async fetchTicket(key, opts = {}) {
+      const number = parseInt(key.split('-').pop(), 10);
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const [issueRes, commentsRes] = await Promise.all([
+        fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, { headers, signal }),
+        fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/comments`, { headers, signal }),
+      ]);
+      if (!issueRes.ok) {
+        throw new Error(`GitHub API error ${issueRes.status} (${issueRes.statusText}) fetching ${key}`);
+      }
+      const raw = await issueRes.json();
+      const comments = commentsRes.ok ? await commentsRes.json() : [];
+      return normalizeGitHubIssue(raw, comments, keyPrefix);
+    },
+
+    async fetchCurrentUser(opts = {}) {
+      const res = await fetcher(`${GITHUB_API}/user`, {
+        headers,
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) throw new Error(`GitHub API error ${res.status} fetching current user`);
+      const raw = await res.json();
+      return { displayName: raw.name || raw.login, email: raw.email ?? null };
+    },
+
+    async searchTickets(_query, opts = {}) {
+      const res = await fetcher(
+        `${GITHUB_API}/repos/${owner}/${repo}/issues?state=open&assignee=me&per_page=50`,
+        { headers, signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000) },
+      );
+      if (!res.ok) throw new Error(`GitHub API error ${res.status} searching issues`);
+      const raw = await res.json();
+      return raw.map(issue => normalizeGitHubIssue(issue, [], keyPrefix));
+    },
+
+    async fetchStatuses() {
+      return ['open', 'closed'];
+    },
+  };
+}

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -0,0 +1,19 @@
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses } from '../jira-client.mjs';
+import { buildJiraEnv } from '../config.mjs';
+
+/**
+ * Returns a tracker adapter backed by the Jira REST API.
+ * Binds connection credentials so callers never touch jira-client directly.
+ */
+export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
+  const env = buildJiraEnv(conn);
+  const apiVersion = conn.auth === 'cloud' ? 3 : 2;
+
+  return {
+    type: 'jira',
+    fetchTicket: (key, opts = {}) => fetchTicket(key, { env, fetcher, apiVersion, ...opts }),
+    fetchCurrentUser: (opts = {}) => fetchCurrentUser({ env, fetcher, apiVersion, ...opts }),
+    searchTickets: (query, opts = {}) => searchTickets(query, { env, fetcher, apiVersion, ...opts }),
+    fetchStatuses: (opts = {}) => fetchStatuses({ env, fetcher, apiVersion, ...opts }),
+  };
+}

package/skills/jtb/scripts/lib/adf-converter.mjs

@@ -0,0 +1,67 @@
+/**
+ * Converts Atlassian Document Format (ADF) to plain text.
+ * Used for Jira Cloud v3 API responses where description and
+ * comment bodies are ADF objects instead of plain text strings.
+ */
+
+export function adfToText(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || value.type !== 'doc') return '';
+
+  return extractBlocks(value.content || []);
+}
+
+function extractBlocks(nodes) {
+  return nodes.map(extractBlock).filter(Boolean).join('\n\n');
+}
+
+function extractBlock(node) {
+  switch (node.type) {
+    case 'paragraph':
+    case 'heading':
+    case 'codeBlock':
+      return extractInlines(node.content || []);
+    case 'bulletList':
+    case 'orderedList':
+      return (node.content || []).map(li => extractBlock(li)).filter(Boolean).join('\n');
+    case 'listItem':
+      return extractBlocks(node.content || []);
+    case 'blockquote':
+    case 'panel':
+    case 'expand':
+    case 'nestedExpand':
+    case 'layoutSection':
+    case 'layoutColumn':
+    case 'tableCell':
+    case 'tableHeader':
+    case 'tableRow':
+    case 'table':
+      return extractBlocks(node.content || []);
+    default:
+      if (node.content) return extractBlocks(node.content);
+      return '';
+  }
+}
+
+function extractInlines(nodes) {
+  return nodes.map(extractInline).join('');
+}
+
+function extractInline(node) {
+  switch (node.type) {
+    case 'text':
+      return node.text || '';
+    case 'mention':
+      return node.attrs?.text || '';
+    case 'inlineCard':
+      return node.attrs?.url || '';
+    case 'emoji':
+      return node.attrs?.shortName || '';
+    case 'hardBreak':
+      return '\n';
+    default:
+      if (node.content) return extractInlines(node.content);
+      return '';
+  }
+}

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

@@ -0,0 +1,87 @@
+const ESC = '\x1b[';
+const codes = {
+  bold: [1, 22], dim: [2, 22],
+  blue: [34, 39], cyan: [36, 39],
+  magenta: [35, 39], white: [37, 39],
+  brightGreen: [92, 39], brightYellow: [93, 39], brightCyan: [96, 39],
+};
+
+// Brand design tokens mapped from landing page CSS variables
+const TOKENS = {
+  brand:  { rgb: [121, 192, 255], idx: 117 }, // #79c0ff — landing page .t-blue
+  green:  { rgb: [63,  185, 80 ], idx: 71  }, // #3fb950
+  yellow: { rgb: [227, 179, 65 ], idx: 178 }, // #e3b341
+  red:    { rgb: [248, 81,  73 ], idx: 203 }, // #f85149
+};
+
+function detectStyled({ forceColor, noColor, term, isTTY } = {}) {
+  if (forceColor) return true;
+  if (noColor) return false;
+  if (term === 'dumb') return false;
+  return !!isTTY;
+}
+
+function detectTruecolor({ colorterm } = {}) {
+  return colorterm === 'truecolor' || colorterm === '24bit';
+}
+
+export function createStyler(opts = {}) {
+  const enabled = detectStyled(opts);
+  const tc = enabled && detectTruecolor(opts);
+
+  const wrap = (open, close) => (text) =>
+    enabled ? `${ESC}${open}m${text}${ESC}${close}m` : String(text);
+
+  const wrapToken = (token) => {
+    const { rgb: [r, g, b], idx } = TOKENS[token];
+    const open = tc ? `38;2;${r};${g};${b}` : `38;5;${idx}`;
+    return (text) => enabled ? `${ESC}${open}m${text}${ESC}39m` : String(text);
+  };
+
+  const link = (url, text) =>
+    enabled ? `\x1b]8;;${url}\x07${text}\x1b]8;;\x07` : String(text);
+
+  return {
+    bold:         wrap(codes.bold[0], codes.bold[1]),
+    dim:          wrap(codes.dim[0], codes.dim[1]),
+    red:          wrapToken('red'),
+    green:        wrapToken('green'),
+    yellow:       wrapToken('yellow'),
+    blue:         wrap(codes.blue[0], codes.blue[1]),
+    cyan:         wrap(codes.cyan[0], codes.cyan[1]),
+    magenta:      wrap(codes.magenta[0], codes.magenta[1]),
+    white:        wrap(codes.white[0], codes.white[1]),
+    brightGreen:  wrap(codes.brightGreen[0], codes.brightGreen[1]),
+    brightYellow: wrap(codes.brightYellow[0], codes.brightYellow[1]),
+    brightCyan:   wrap(codes.brightCyan[0], codes.brightCyan[1]),
+    brand:        wrapToken('brand'),
+    link,
+    enabled,
+  };
+}
+
+function envStyler() {
+  return createStyler({
+    forceColor: !!process.env.FORCE_COLOR,
+    noColor:    !!process.env.NO_COLOR,
+    term:       process.env.TERM,
+    colorterm:  process.env.COLORTERM,
+    isTTY:      process.stdout.isTTY,
+  });
+}
+
+const defaultStyler = envStyler();
+export const bold         = defaultStyler.bold;
+export const dim          = defaultStyler.dim;
+export const red          = defaultStyler.red;
+export const green        = defaultStyler.green;
+export const yellow       = defaultStyler.yellow;
+export const blue         = defaultStyler.blue;
+export const cyan         = defaultStyler.cyan;
+export const magenta      = defaultStyler.magenta;
+export const white        = defaultStyler.white;
+export const brightGreen  = defaultStyler.brightGreen;
+export const brightYellow = defaultStyler.brightYellow;
+export const brightCyan   = defaultStyler.brightCyan;
+export const brand        = defaultStyler.brand;
+export const isStyled     = () => defaultStyler.enabled;

package/skills/jtb/scripts/lib/arg-validator.mjs

@@ -0,0 +1,178 @@
+/**
+ * CLI argument validation — unknown flag detection with "did you mean?" and
+ * an interactive y/N prompt to apply the corrected flag before re-running.
+ *
+ * Known-flags format
+ * ──────────────────
+ *   '--stale='   trailing '=' → flag takes a value  (--stale=5)
+ *   '--plain'    no trailing '=' → boolean flag      (--plain)
+ *
+ * hints (optional)
+ * ────────────────
+ *   Same format, but these flags are from *other* commands.
+ *   They widen the suggestion pool so a cross-command typo like
+ *   --dept in triage can still surface "--depth (fetch flag)" as a hint.
+ *   Hint suggestions are shown as informational only — no y/N prompt,
+ *   since applying them wouldn't work for the current command.
+ */
+
+import { createStyler } from './ansi.mjs';
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => i ? (j ? 0 : i) : j)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+// Strip leading dashes before distance comparison so '--dept' vs '--depth' = 1 edit,
+// not 3 (the shared '--' prefix would inflate every distance by 0 but skew alignment).
+function bare(flag) {
+  return flag.startsWith('--') ? flag.slice(2) : flag.startsWith('-') ? flag.slice(1) : flag;
+}
+
+// Threshold scales with bare flag length so short names require tight matches:
+//   4-char bare ('dept')   → 2  —  'dept' vs 'help' = 3 > 2, no false positive
+//   5-char bare ('state')  → 2  —  'state' vs 'stale' = 1 ≤ 2, correct match
+//   7-char bare ('profile') → 3  —  'profle' vs 'profile' = 1 ≤ 3, correct
+function threshold(bareFlag) {
+  return Math.max(1, Math.ceil(bareFlag.length / 3));
+}
+
+/**
+ * Find the best-matching flag name (without trailing '=') from `candidates`, or null.
+ *
+ * @param {string}   inputFlag  e.g. '--state'
+ * @param {string[]} candidates from knownFlags and/or hints
+ * @param {boolean}  hasValue   true when the user typed --flag=VALUE
+ */
+function findSuggestion(inputFlag, candidates, hasValue) {
+  const input = bare(inputFlag);
+  const limit = threshold(input);
+
+  // Value-type filtering: --flag=value inputs should only match value-taking flags.
+  // This prevents --help (boolean) from ever being suggested for --dept=5.
+  const pool = hasValue ? candidates.filter(f => f.endsWith('=')) : candidates;
+
+  const ranked = pool
+    .map(f => {
+      const name = f.replace(/=$/, '');
+      return { name, dist: levenshtein(input, bare(name)) };
+    })
+    .sort((a, b) => a.dist - b.dist);
+
+  return ranked[0]?.dist <= limit ? ranked[0].name : null;
+}
+
+function correctedArg(arg, suggestion) {
+  const eqIdx = arg.indexOf('=');
+  return eqIdx === -1 ? suggestion : `${suggestion}=${arg.slice(eqIdx + 1)}`;
+}
+
+/**
+ * Detect unrecognized flags and either interactively fix them or signal exit.
+ *
+ * TTY + fixable suggestion:  prints styled error + "Apply <fix>? (y/N)"
+ *   y → returns corrected args (caller re-runs with the fixed flag)
+ *   N → returns null (caller sets exitCode=1)
+ *
+ * TTY + hint-only suggestion: prints error + informational "closest match" line, exits.
+ *
+ * Non-TTY: prints error + "Try: <fix>" or no tip, returns null.
+ *
+ * No unknowns → returns original args unchanged.
+ *
+ * @param {string[]}  args       CLI args (already normalised, e.g. --project→--profile)
+ * @param {string[]}  knownFlags Flags this command accepts; append '=' for value-taking
+ * @param {{ stream?: NodeJS.WritableStream, hints?: string[] }} opts
+ *   hints: cross-command flags used only for suggestions, never auto-applied
+ * @returns {Promise<string[]|null>}
+ */
+export async function handleUnknownFlags(args, knownFlags, { stream = process.stderr, hints = [] } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+
+  // Lookup set — strips trailing '=' so '--stale=3' matches the known entry '--stale='
+  const knownNames = new Set(knownFlags.map(f => f.replace(/=$/, '')));
+
+  // Suggestion pool = command flags + cross-command hints
+  const allCandidates = [...knownFlags, ...hints];
+
+  const unknowns = [];
+  for (const arg of args) {
+    if (!arg.startsWith('-')) continue;
+    const flagName = arg.split('=')[0];
+    if (knownNames.has(flagName)) continue;
+    const hasValue = arg.includes('=');
+    const suggestion = findSuggestion(flagName, allCandidates, hasValue);
+    // isApplicable: suggestion is in this command's known flags (can be auto-applied)
+    const isApplicable = suggestion !== null && knownNames.has(suggestion.replace(/=$/, ''));
+    unknowns.push({ arg, flagName, hasValue, suggestion, isApplicable });
+  }
+
+  if (unknowns.length === 0) return args;
+
+  // ── One diagnostic line per unknown flag ──────────────────────────────────
+  stream.write('\n');
+  for (const { flagName, suggestion, isApplicable } of unknowns) {
+    if (suggestion && isApplicable) {
+      stream.write(
+        `  ${s.red('✗')} ${s.cyan(flagName)} is not a recognized flag — did you mean ${s.cyan(suggestion)}?\n`
+      );
+    } else if (suggestion) {
+      // Cross-command hint: helpful but can't be auto-applied
+      stream.write(
+        `  ${s.red('✗')} ${s.cyan(flagName)} is not a recognized flag — closest match: ${s.cyan(suggestion)} ${s.dim('(not available in this command)')}\n`
+      );
+    } else {
+      stream.write(`  ${s.red('✗')} ${s.cyan(flagName)} is not a recognized flag.\n`);
+    }
+  }
+
+  const fixable = unknowns.filter(u => u.suggestion && u.isApplicable);
+
+  // ── TTY: offer an interactive fix for applicable suggestions ──────────────
+  if (stream.isTTY && process.stdin.setRawMode && fixable.length > 0) {
+    const preview = fixable.map(u => s.cyan(correctedArg(u.arg, u.suggestion))).join(', ');
+    stream.write(`\n  Apply ${preview}?  ${s.dim('y/N')}  `);
+
+    const answer = await new Promise(res => {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding('utf8');
+      process.stdin.once('data', char => {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        stream.write('\n\n');
+        if (char === '\x03') process.exit(0);
+        res(char === 'y' || char === 'Y');
+      });
+    });
+
+    if (answer) {
+      let corrected = args;
+      for (const { arg, suggestion } of fixable) {
+        const fixed = correctedArg(arg, suggestion);
+        corrected = corrected.map(a => a === arg ? fixed : a);
+      }
+      return corrected;
+    }
+
+    return null;
+  }
+
+  // ── Non-TTY: print tip and signal exit ────────────────────────────────────
+  if (fixable.length > 0) {
+    const tips = fixable.map(u => s.cyan(correctedArg(u.arg, u.suggestion))).join(', ');
+    stream.write(`  ${s.dim('Try:')} ${tips}\n`);
+  }
+  stream.write('\n');
+  return null;
+}

package/skills/jtb/scripts/lib/attachment-downloader.mjs

@@ -0,0 +1,123 @@
+/**
+ * Downloads ticket attachments from Jira to a local cache directory.
+ * Supports all file types; respects a per-file size cap.
+ * Auth headers are required — Jira attachment URLs are not public.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildAuthHeader } from './jira-client.mjs';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+const MAX_ATTACHMENTS = 20;
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+
+/**
+ * @param {object} ticket         Normalized ticket (from normalizeTicket)
+ * @param {object} opts
+ * @param {object} opts.env       Env-like object with JIRA_BASE_URL + auth vars
+ * @param {Function} opts.fetcher fetch-compatible function (default: globalThis.fetch)
+ * @param {string} opts.configDir Base config dir (default: ~/.ticketlens)
+ * @param {boolean} opts.noCache  Force re-download even if cached (default: false)
+ * @param {Function} opts.onProgress  Optional callback(msg: string) for progress lines
+ *
+ * @returns {Promise<Array<{filename, mimeType, size, localPath, skipped, skipReason, error}>>}
+ */
+export async function downloadAttachments(ticket, opts = {}) {
+  const {
+    env = process.env,
+    fetcher = globalThis.fetch,
+    configDir = DEFAULT_CONFIG_DIR,
+    noCache = false,
+    onProgress = null,
+  } = opts;
+
+  const attachments = (ticket.attachments ?? []).filter(a => a.content);
+  if (attachments.length === 0) return [];
+
+  const cacheDir = path.join(configDir, 'cache', ticket.key);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const jiraOrigin = env.JIRA_BASE_URL ? new URL(env.JIRA_BASE_URL).origin : null;
+
+  // Attachments beyond the limit are bulk-skipped
+  const capped = attachments.slice(0, MAX_ATTACHMENTS);
+  const limited = attachments.slice(MAX_ATTACHMENTS).map(a => makeResult(a, null, 'limit', null));
+
+  // Pre-classify: resolve immediate results, collect pending downloads
+  const results = new Array(capped.length);
+  const pending = [];
+
+  for (let i = 0; i < capped.length; i++) {
+    const a = capped[i];
+
+    if (a.size && a.size > MAX_FILE_BYTES) {
+      onProgress?.(`  skipped   ${a.filename} (${formatSize(a.size)} — exceeds 10 MB limit)`);
+      results[i] = makeResult(a, null, 'too-large', null);
+      continue;
+    }
+
+    const localPath = path.join(cacheDir, sanitizeFilename(a.filename));
+
+    if (!noCache && fs.existsSync(localPath)) {
+      onProgress?.(`  cached    ${a.filename}`);
+      results[i] = makeResult(a, localPath, 'cached', null);
+      continue;
+    }
+
+    // SSRF protection: only send auth headers to the configured Jira origin
+    let contentOrigin;
+    try { contentOrigin = new URL(a.content).origin; } catch { contentOrigin = null; }
+    if (!contentOrigin || contentOrigin !== jiraOrigin) {
+      onProgress?.(`  blocked   ${a.filename} (cross-origin URL rejected)`);
+      results[i] = makeResult(a, null, 'ssrf-blocked', null);
+      continue;
+    }
+
+    pending.push({ a, localPath, i });
+  }
+
+  // Download pending attachments in parallel batches of 3
+  const BATCH = 3;
+  for (let b = 0; b < pending.length; b += BATCH) {
+    await Promise.all(pending.slice(b, b + BATCH).map(async ({ a, localPath, i }) => {
+      onProgress?.(`  download  ${a.filename}`);
+      try {
+        const headers = buildAuthHeader(env);
+        const response = await fetcher(a.content, { headers });
+        if (!response.ok) throw new Error(`HTTP ${response.status} (${response.statusText})`);
+        const buffer = await response.arrayBuffer();
+        fs.writeFileSync(localPath, Buffer.from(buffer));
+        results[i] = makeResult(a, localPath, null, null);
+      } catch (err) {
+        process.stderr.write(`  warning: failed to download ${a.filename}: ${err.message}\n`);
+        results[i] = makeResult(a, null, 'error', err.message);
+      }
+    }));
+  }
+
+  return [...results, ...limited];
+}
+
+export function formatSize(bytes) {
+  if (!bytes) return '?';
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+function makeResult(attachment, localPath, skipReason, error) {
+  return {
+    filename: attachment.filename,
+    mimeType: attachment.mimeType,
+    size: attachment.size,
+    localPath,
+    skipped: localPath === null || skipReason === 'cached',
+    skipReason,
+    error,
+  };
+}
+
+function sanitizeFilename(filename) {
+  // Strip directory components, replace unsafe chars, preserve extension
+  return path.basename(filename).replace(/[^a-zA-Z0-9._\-]/g, '_');
+}