ticketlens 0.1.0

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

@@ -0,0 +1,119 @@
+/**
+ * ticketlens sync — Pull tracker profile shapes from the TicketLens console.
+ *
+ * Credentials are NEVER synced — they stay on the local machine.
+ * Server wins on all non-credential fields (shape, prefixes, URLs, etc.).
+ */
+
+import { readCliToken } from './cli-auth.mjs';
+import {
+  loadProfiles,
+  loadCredentials,
+  saveProfile,
+  invalidateProfilesCache,
+} from './profile-resolver.mjs';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+
+const DEFAULT_API_BASE = 'https://ticketlens.app';
+
+export const getApiBase = () => process.env.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+
+/**
+ * Convert a server profile (snake_case) to the CLI profile shape (camelCase).
+ * Returns { name, profileData } — no credential fields.
+ */
+export function serverToCliProfile(serverProfile) {
+  const p = serverProfile;
+  const profileData = {
+    baseUrl: p.base_url,
+    auth: p.auth_method,
+    ...(p.email                    ? { email: p.email }                       : {}),
+    ...(p.ticket_prefixes?.length  ? { ticketPrefixes: p.ticket_prefixes }    : {}),
+    ...(p.project_paths?.length    ? { projectPaths: p.project_paths }        : {}),
+    ...(p.triage_statuses?.length  ? { triageStatuses: p.triage_statuses }    : {}),
+  };
+  return { name: p.name, profileData };
+}
+
+/**
+ * Determine whether a profile is missing the credentials it needs to function.
+ */
+export function profileNeedsCredentials(profileData, creds) {
+  if (!creds) return true;
+  const auth = profileData.auth;
+  if (auth === 'pat')    return !creds.pat;
+  return !creds.apiToken; // cloud, basic, github all use apiToken
+}
+
+/**
+ * Sync tracker profile shapes from the TicketLens console API.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.configDir]
+ * @param {Function} [opts.fetcher]   — injectable for tests
+ *
+ * @returns {Promise<
+ *   | { error: 'no-token' | 'unauthorized' | string }
+ *   | { added: string[], updated: string[], unchanged: string[], needsCredentials: string[] }
+ * >}
+ */
+export async function syncProfiles({
+  configDir = DEFAULT_CONFIG_DIR,
+  fetcher = globalThis.fetch,
+} = {}) {
+  const token = readCliToken(configDir);
+  if (!token) return { error: 'no-token' };
+
+  let res;
+  try {
+    res = await fetcher(`${getApiBase()}/v1/profiles`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+      },
+      signal: AbortSignal.timeout(15000),
+    });
+  } catch (err) {
+    return { error: err.name === 'TimeoutError' ? 'timeout' : `network: ${err.message}` };
+  }
+
+  if (res.status === 401) return { error: 'unauthorized' };
+  if (!res.ok) return { error: `http-${res.status}` };
+
+  let json;
+  try { json = await res.json(); } catch { return { error: 'invalid-json' }; }
+
+  const remoteProfiles = Array.isArray(json?.profiles) ? json.profiles : [];
+  const localConfig  = loadProfiles(configDir) || { profiles: {} };
+  const localCreds   = loadCredentials(configDir);
+
+  const added            = [];
+  const updated          = [];
+  const unchanged        = [];
+  const needsCredentials = [];
+
+  for (const remote of remoteProfiles) {
+    const { name, profileData } = serverToCliProfile(remote);
+    const existing = localConfig.profiles[name];
+
+    if (!existing) {
+      saveProfile(name, profileData, {}, configDir);
+      added.push(name);
+    } else if (JSON.stringify(existing) !== JSON.stringify(profileData)) {
+      saveProfile(name, profileData, {}, configDir);
+      updated.push(name);
+    } else {
+      unchanged.push(name);
+    }
+
+    if (profileNeedsCredentials(profileData, localCreds[name])) {
+      needsCredentials.push(name);
+    }
+  }
+
+  if (added.length > 0 || updated.length > 0) {
+    invalidateProfilesCache(configDir);
+  }
+
+  return { added, updated, unchanged, needsCredentials };
+}

package/skills/jtb/scripts/lib/table-formatter.mjs

@@ -0,0 +1,48 @@
+/**
+ * Plain-text table formatter for terminal output.
+ * Uses box-drawing characters for clean rendering without a markdown parser.
+ */
+
+// Strip ANSI SGR sequences and OSC 8 hyperlinks to get visible (printable) length.
+const ESCAPE_RE = /\x1b\[[0-9;]*m|\x1b\]8;[^\x07]*\x07/g;
+const visibleLength = (str) => str.replace(ESCAPE_RE, '').length;
+
+export function formatTable(headers, rows, opts = {}) {
+  const { maxWidths = {} } = opts;
+
+  // Strip control characters that can corrupt table layout.
+  // Preserves \x07 (BEL) used as OSC 8 hyperlink terminator and \x1b used in escape sequences.
+  const sanitize = (str) => str.replace(/[\x00-\x06\x08\x0b\x0c\x0e-\x1a\r]/g, '');
+
+  // Apply truncation based on visible length so ANSI-styled cells are not cut mid-sequence.
+  const truncate = (str, max) => {
+    if (!max || visibleLength(str) <= max) return str;
+    // Strip styles, truncate, re-apply is complex; these cells are plain text from callers.
+    return str.slice(0, max - 3) + '...';
+  };
+
+  const processedRows = rows.map(row =>
+    row.map((cell, i) => truncate(sanitize(String(cell ?? '')), maxWidths[i]))
+  );
+  const processedHeaders = headers.map((h, i) => truncate(String(h), maxWidths[i]));
+
+  // Calculate column widths using visible length to ignore ANSI escape sequences.
+  const colWidths = processedHeaders.map((h, i) => {
+    const cellMax = processedRows.reduce((max, row) => Math.max(max, visibleLength(row[i] || '')), 0);
+    return Math.max(visibleLength(h), cellMax);
+  });
+
+  // Pad using visible length so styled cells (with invisible escape codes) align correctly.
+  const pad = (str, width) => str + ' '.repeat(Math.max(0, width - visibleLength(str)));
+  const formatRow = (cells) => '  ' + cells.map((c, i) => pad(String(c || ''), colWidths[i])).join('   ');
+
+  const lines = [];
+  lines.push(formatRow(processedHeaders));
+  lines.push('  ' + colWidths.map(w => '─'.repeat(w)).join('   '));
+
+  for (const row of processedRows) {
+    lines.push(formatRow(row));
+  }
+
+  return lines.join('\n');
+}

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

@@ -0,0 +1,93 @@
+import { writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+
+/**
+ * Export triage results to CSV or JSON.
+ * @param {object} opts
+ * @param {Array} opts.tickets - Scored ticket objects from attention-scorer
+ * @param {'csv'|'json'} opts.format
+ * @param {string} [opts.profile]
+ * @param {string} [opts.configDir]
+ * @returns {string} Absolute path to written file
+ */
+export function exportTriage({ tickets, format, profile = 'default', configDir = DEFAULT_CONFIG_DIR }) {
+  // Check for path traversal attempts in profile name
+  if (profile.includes('/') || profile.includes('\\') || profile.includes('..')) {
+    throw new Error(`Invalid profile name: contains path traversal characters`);
+  }
+
+  const exportsDir = join(configDir, 'exports');
+  assertSafePath(exportsDir, configDir);
+  mkdirSync(exportsDir, { recursive: true });
+
+  const dateStr = formatDate(new Date());
+  const safeProfile = profile.replace(/[^a-z0-9_-]/gi, '_').slice(0, 40);
+  const filename = `${dateStr}-${safeProfile}.${format}`;
+  const outputPath = join(exportsDir, filename);
+  const tmpPath = `${outputPath}.tmp`;
+
+  const content = format === 'csv' ? buildCsv(tickets) : buildJson(tickets, profile);
+
+  writeFileSync(tmpPath, content, 'utf8');
+  renameSync(tmpPath, outputPath);
+
+  return outputPath;
+}
+
+function buildCsv(tickets) {
+  const header = '#,Ticket,Summary,Status,Urgency,LastCommentFrom,LastCommentDate,DaysSinceUpdate,URL';
+  const rows = tickets.map((t, i) => [
+    i + 1,
+    t.ticketKey ?? '',
+    escapeCsv(t.summary),
+    t.status ?? '',
+    t.urgency ?? '',
+    escapeCsv(t.lastComment?.author ?? ''),
+    t.lastComment?.created ?? '',
+    t.daysSinceUpdate ?? '',
+    t.url ?? '',
+  ].join(','));
+  return [header, ...rows].join('\n') + '\n';
+}
+
+function buildJson(tickets, profile) {
+  const needsResponse = tickets.filter(t => t.urgency === 'needs-response').length;
+  const aging = tickets.filter(t => t.urgency === 'aging').length;
+  return JSON.stringify({
+    exportedAt: new Date().toISOString(),
+    profile,
+    summary: { total: tickets.length, needsResponse, aging },
+    tickets: tickets.map(t => ({
+      ticketKey: t.ticketKey ?? null,
+      summary: t.summary ?? null,
+      status: t.status ?? null,
+      urgency: t.urgency ?? null,
+      lastComment: t.lastComment ?? null,
+      daysSinceUpdate: t.daysSinceUpdate ?? null,
+      url: t.url ?? null,
+    })),
+  }, null, 2);
+}
+
+function escapeCsv(str) {
+  if (str == null) return '';
+  const s = String(str).replace(/[\r\n]+/g, ' ');
+  if (s.includes(',') || s.includes('"')) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+function formatDate(d) {
+  const pad = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}-${pad(d.getMinutes())}`;
+}
+
+function assertSafePath(targetPath, basePath) {
+  const resolved = resolve(targetPath);
+  const base = resolve(basePath);
+  if (!resolved.startsWith(base + '/') && resolved !== base) {
+    throw new Error(`Invalid path: ${targetPath} is outside ${basePath}`);
+  }
+}

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

@@ -0,0 +1,166 @@
+/**
+ * Triage history: save/load daily snapshots and compute delta reports.
+ * Named exports only, no default export.
+ * All I/O deps are injectable (fsModule, configDir, now).
+ */
+
+import * as defaultFs from 'node:fs';
+import { join } from 'node:path';
+
+const DEFAULT_CONFIG_DIR = join(
+  process.env.HOME ?? process.env.USERPROFILE ?? '',
+  '.ticketlens'
+);
+
+const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function validateProfile(profile) {
+  if (!profile || /[/\\]/.test(profile) || profile === '..' || profile.includes('..')) {
+    throw new Error('Invalid profile name');
+  }
+}
+
+function toDateString(date) {
+  // Format as YYYY-MM-DD in local wall-clock date
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function snapshotPath(configDir, dateStr, profile) {
+  return join(configDir, 'triage-history', dateStr, `${profile}.json`);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Save the current scored tickets as today's snapshot.
+ *
+ * @param {object[]} tickets - Array of scoreAttention() results
+ * @param {object} opts
+ * @param {string} opts.profile - Profile name (sanitized)
+ * @param {string} [opts.configDir]
+ * @param {object} [opts.fsModule] - Injectable fs (default: node:fs)
+ * @param {Date}   [opts.now]     - Date for deterministic tests
+ */
+export function saveTriageSnapshot(tickets, {
+  profile,
+  configDir = DEFAULT_CONFIG_DIR,
+  fsModule = defaultFs,
+  now = new Date(),
+} = {}) {
+  validateProfile(profile);
+  const dateStr = toDateString(now);
+  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');
+}
+
+/**
+ * Load yesterday's snapshot, or null if none exists.
+ *
+ * @param {object} opts
+ * @param {string} opts.profile
+ * @param {string} [opts.configDir]
+ * @param {object} [opts.fsModule]
+ * @param {Date}   [opts.now]
+ * @returns {object[]|null}
+ */
+export function loadYesterdaySnapshot({
+  profile,
+  configDir = DEFAULT_CONFIG_DIR,
+  fsModule = defaultFs,
+  now = new Date(),
+} = {}) {
+  validateProfile(profile);
+  const yest = new Date(now);
+  yest.setDate(yest.getDate() - 1);
+  const dateStr = toDateString(yest);
+  const filePath = snapshotPath(configDir, dateStr, profile);
+  try {
+    const raw = fsModule.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare today's and yesterday's ticket arrays, returning only tickets that
+ * worsened (urgency moved toward 'needs-response', new comment, or stale threshold crossed).
+ *
+ * Only tickets present in BOTH arrays are compared.
+ *
+ * @param {object[]} today     - Today's scored tickets
+ * @param {object[]} yesterday - Yesterday's scored tickets
+ * @returns {{ ticketKey: string, summary: string, changes: string[] }[]}
+ */
+export function diffSnapshots(today, yesterday) {
+  const yesterdayMap = new Map(yesterday.map(t => [t.ticketKey, t]));
+  const deltas = [];
+
+  for (const t of today) {
+    const y = yesterdayMap.get(t.ticketKey);
+    if (!y) continue; // new ticket — skip
+
+    const changes = [];
+
+    // Urgency worsened
+    const todayOrder = URGENCY_ORDER[t.urgency] ?? 2;
+    const yesterdayOrder = URGENCY_ORDER[y.urgency] ?? 2;
+    if (todayOrder < yesterdayOrder) {
+      changes.push(`${y.urgency} \u2192 ${t.urgency}`);
+    }
+
+    // New comment (today has a comment with a different created timestamp)
+    if (
+      t.lastComment?.created &&
+      t.lastComment.created !== y.lastComment?.created
+    ) {
+      changes.push('1 new comment');
+    }
+
+    // Stale threshold crossed: was <7 days, now >=7 days
+    if (
+      typeof t.daysSinceUpdate === 'number' &&
+      typeof y.daysSinceUpdate === 'number' &&
+      t.daysSinceUpdate >= 7 &&
+      y.daysSinceUpdate < 7
+    ) {
+      changes.push(`stale threshold crossed (${t.daysSinceUpdate} days idle)`);
+    }
+
+    if (changes.length > 0) {
+      deltas.push({ ticketKey: t.ticketKey, summary: t.summary, changes });
+    }
+  }
+
+  return deltas;
+}
+
+/**
+ * Render the delta section as a plain-text string for inclusion in the digest payload.
+ *
+ * @param {{ ticketKey: string, summary: string, changes: string[] }[]} deltas
+ * @returns {string} Empty string when deltas is empty
+ */
+export function buildDeltaSection(deltas) {
+  if (!deltas || deltas.length === 0) return '';
+
+  const lines = ['\u2500\u2500 What got worse since yesterday \u2500\u2500'];
+
+  for (const { ticketKey, changes } of deltas) {
+    const changeStr = changes.join('  ');
+    lines.push(`\u25bc ${ticketKey}  ${changeStr}`);
+  }
+
+  return lines.join('\n') + '\n';
+}

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

@@ -0,0 +1,98 @@
+/**
+ * POST scored triage snapshot to the TicketLens API.
+ * All errors are caught — push failure must never break triage output.
+ */
+
+const PUSH_PATH = '/v1/triage/push';
+// Local dev: http://ticketlens.test — production override via TICKETLENS_API_URL env var
+const DEFAULT_API_BASE = 'http://ticketlens.test';
+
+function apiBase() {
+  return process.env?.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+}
+
+// Derive console queue URL from API base:
+//   http://ticketlens.test          → http://ticketlens.test/console/queue
+//   https://api.ticketlens.com      → https://app.ticketlens.com/console/queue
+function queueUrl(base) {
+  return base.replace(/^(https?:\/\/)api\./, '$1app.') + '/console/queue';
+}
+
+function buildTicketPayload(scored, rawMap, baseUrl) {
+  const raw = rawMap?.get(scored.ticketKey);
+  return {
+    key: scored.ticketKey,
+    summary: scored.summary ?? null,
+    status: scored.status ?? null,
+    assignee: raw?.assignee ?? null,
+    attention_score: null,
+    flags: scored.urgency === 'clear' ? [] : [scored.urgency],
+    compliance_coverage: null,
+    compliance_status: 'unknown',
+    url: baseUrl ? `${baseUrl}/browse/${scored.ticketKey}` : null,
+    last_updated: raw?.updated ?? null,
+  };
+}
+
+/**
+ * POST the scored triage snapshot to the TicketLens API.
+ *
+ * @param {object}   opts
+ * @param {object[]} [opts.sorted]       - Scored tickets from attention-scorer
+ * @param {Map}      [opts.rawTicketMap] - Map<key, normalizedTicket>
+ * @param {string}   [opts.profile]      - Resolved profile name (max 100 chars)
+ * @param {string}   [opts.baseUrl]      - Jira base URL for URL construction
+ * @param {string}   [opts.licenseKey]   - Bearer token for the API
+ * @param {string}   [opts.capturedAt]   - ISO 8601 timestamp (defaults to now)
+ * @param {Function} [opts.fetcher]      - Injectable fetch (default: globalThis.fetch)
+ * @param {Function} [opts.print]        - Output fn (default: process.stdout.write)
+ * @returns {Promise<{ ok: boolean, status?: number }>}
+ */
+export async function pushTriageSnapshot({
+  sorted = [],
+  rawTicketMap = new Map(),
+  profile,
+  baseUrl,
+  licenseKey,
+  capturedAt,
+  fetcher = globalThis.fetch,
+  print = (s) => process.stdout.write(s),
+} = {}) {
+  if (!licenseKey) {
+    print('✗ --push requires an active Team license (ticketlens activate <key>)\n');
+    return { ok: false };
+  }
+
+  const payload = {
+    profile: String(profile ?? 'default').slice(0, 100),
+    captured_at: capturedAt ?? new Date().toISOString(),
+    tickets: sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl)),
+  };
+
+  try {
+    const res = await fetcher(`${apiBase()}${PUSH_PATH}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${licenseKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (res.ok) {
+      print(`✓ Queue updated — view at ${queueUrl(apiBase())}\n`);
+      return { ok: true, status: res.status };
+    }
+
+    if (res.status === 403) {
+      print('✗ --push requires a Team license\n');
+      return { ok: false, status: res.status };
+    }
+
+    print(`⚠ Push failed (${res.status}) — triage output unaffected\n`);
+    return { ok: false, status: res.status };
+  } catch {
+    print('⚠ Push failed (network error) — triage output unaffected\n');
+    return { ok: false };
+  }
+}

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

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const FREE_LIMIT = 3;
+
+const USAGE_FILE = 'usage.json';
+
+function currentMonth() {
+  return new Date().toISOString().slice(0, 7); // "YYYY-MM"
+}
+
+function readUsageFile(configDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(configDir, USAGE_FILE), 'utf8'));
+  } catch {
+    return { compliance: {} };
+  }
+}
+
+function writeUsageFile(configDir, data) {
+  try {
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, USAGE_FILE), JSON.stringify(data, null, 2), 'utf8');
+  } catch {
+    // Non-fatal — usage tracking is best-effort
+  }
+}
+
+/**
+ * Checks free-tier usage for the current month.
+ * @param {string} configDir - Path to the TicketLens config directory
+ * @returns {{ count: number, month: string, canUse: boolean }}
+ */
+export function checkUsage(configDir) {
+  const month = currentMonth();
+  const data = readUsageFile(configDir);
+  const count = data.compliance?.[month] ?? 0;
+  return { count, month, canUse: count < FREE_LIMIT };
+}
+
+/**
+ * Increments the compliance counter for the current month.
+ * Caller is responsible for checking {@link checkUsage} before calling this.
+ * This function does not enforce the free-tier cap — cap enforcement is
+ * handled by the orchestrator and server-side; client-side is UX-only.
+ * @param {string} configDir - Path to the TicketLens config directory
+ */
+export function incrementUsage(configDir) {
+  const month = currentMonth();
+  const data = readUsageFile(configDir);
+  if (!data.compliance) data.compliance = {};
+  data.compliance[month] = (data.compliance[month] ?? 0) + 1;
+  writeUsageFile(configDir, data);
+}

package/skills/jtb/scripts/lib/vcs-detector.mjs

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Detects the version control system in use at a given directory.
+ */
+export function detectVcs(dir) {
+  if (existsSync(join(dir, '.git'))) return { type: 'git' };
+  if (existsSync(join(dir, '.svn'))) return { type: 'svn' };
+  if (existsSync(join(dir, '.hg'))) return { type: 'hg' };
+  return { type: 'none' };
+}