ticketlens 0.12.0 → 0.16.0

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

@@ -0,0 +1,97 @@
+/**
+ * Reads and writes the small metadata block at the top of a Recall note file.
+ * Hand-rolled — this project does not allow adding a YAML library.
+ * Only supports what Recall notes actually need: plain string fields and
+ * flat string-array fields. Not a general YAML parser.
+ */
+
+const DELIMITER = '---';
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function needsQuoting(value) {
+  return value === '' || /[:#",\n[\]]|^\s|\s$/.test(value);
+}
+
+function quoteScalar(value) {
+  if (!needsQuoting(value)) return value;
+  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+  return `"${escaped}"`;
+}
+
+function unquoteScalar(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+    const inner = trimmed.slice(1, -1);
+    return inner.replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  return trimmed;
+}
+
+function serializeArray(items) {
+  return `[${items.map(quoteScalar).join(', ')}]`;
+}
+
+function parseArray(raw) {
+  const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '').trim();
+  if (inner === '') return [];
+  const items = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (ch === '"' && inner[i - 1] !== '\\') inQuotes = !inQuotes;
+    if (ch === ',' && !inQuotes) {
+      items.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  items.push(current);
+  return items.map(unquoteScalar);
+}
+
+/**
+ * @param {object} data - flat object of string and string-array fields
+ * @param {string} body - the note's markdown body
+ * @returns {string} full note file text
+ */
+export function serializeFrontmatter(data, body) {
+  const lines = [DELIMITER];
+  for (const [key, value] of Object.entries(data)) {
+    const rendered = Array.isArray(value) ? serializeArray(value) : quoteScalar(String(value));
+    lines.push(`${key}: ${rendered}`);
+  }
+  lines.push(DELIMITER, '', body);
+  return lines.join('\n');
+}
+
+/**
+ * @param {string} text - full note file text
+ * @returns {{ data: object, body: string }}
+ */
+export function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  if (lines[0] !== DELIMITER) {
+    return { data: {}, body: text };
+  }
+
+  const closingIndex = lines.indexOf(DELIMITER, 1);
+  if (closingIndex === -1) {
+    return { data: {}, body: text };
+  }
+
+  const data = {};
+  for (const line of lines.slice(1, closingIndex)) {
+    const sepIndex = line.indexOf(': ');
+    if (sepIndex === -1) continue;
+    const key = line.slice(0, sepIndex);
+    if (DANGEROUS_KEYS.has(key)) continue; // a hand-edited note can't repurpose this into a prototype-pollution vector
+    const rawValue = line.slice(sepIndex + 2);
+    data[key] = rawValue.trim().startsWith('[') ? parseArray(rawValue) : unquoteScalar(rawValue);
+  }
+
+  const bodyLines = lines.slice(closingIndex + 1);
+  if (bodyLines[0] === '') bodyLines.shift();
+  return { data, body: bodyLines.join('\n') };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Ephemeral cross-ticket gap-diffing. At brief time, extracts candidate
+ * requirements from a ticket's linked tickets (existing depth-traversal,
+ * already capped at 15 by jira-client.mjs) and from the ticket's own
+ * downloaded attachments, then flags anything not already reflected in the
+ * ticket's own description. Nothing here is persisted — every call
+ * recomputes from data already attached to the ticket object.
+ */
+
+import { extractRequirements } from './requirement-extractor.mjs';
+import { analyzeDiff } from './diff-analyzer.mjs';
+import { readTextAttachments } from './handoff-assembler.mjs';
+
+function normalizeRequirement(requirement) {
+  return requirement.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Flattens a ticket's linkedTicketDetails tree (any depth) into a single
+ * list. Guards against a cyclic or malformed graph — a linked ticket that
+ * points back into the tree (or at the root ticket itself) must not cause
+ * infinite recursion.
+ */
+function flattenLinked(ticket, seen = new Set([ticket.key])) {
+  const out = [];
+  for (const linked of ticket.linkedTicketDetails ?? []) {
+    if (seen.has(linked.key)) continue;
+    seen.add(linked.key);
+    out.push(linked);
+    out.push(...flattenLinked(linked, seen));
+  }
+  return out;
+}
+
+function isUncovered(requirement, currentDescription) {
+  const { results } = analyzeDiff([requirement], currentDescription);
+  return results[0]?.status === 'NOT_FOUND';
+}
+
+/**
+ * @param {object} ticket
+ * @returns {{ requirement: string, sourceType: 'ticket'|'attachment', sourceKey: string, sourceSummary?: string }[]}
+ */
+export function computeGaps(ticket) {
+  const currentDescription = ticket.description ?? '';
+  const seenRequirements = new Set();
+  const gaps = [];
+
+  const addGap = (requirement, sourceType, sourceKey, sourceSummary) => {
+    const normalized = normalizeRequirement(requirement);
+    if (seenRequirements.has(normalized)) return;
+    if (!isUncovered(requirement, currentDescription)) return;
+    seenRequirements.add(normalized);
+    gaps.push({ requirement, sourceType, sourceKey, sourceSummary });
+  };
+
+  for (const linked of flattenLinked(ticket)) {
+    for (const requirement of extractRequirements(linked.description ?? '')) {
+      addGap(requirement, 'ticket', linked.key, linked.summary);
+    }
+  }
+
+  for (const { filename, content } of readTextAttachments(ticket.localAttachments)) {
+    for (const requirement of extractRequirements(content)) {
+      addGap(requirement, 'attachment', filename, undefined);
+    }
+  }
+
+  return gaps;
+}

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

@@ -45,6 +45,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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')} note add ${s.dim('--title=... [--ticket=KEY]')}  Save a Recall note  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} recall ${s.dim('<query|TICKET-KEY>')}   Search your saved Recall notes  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -486,6 +488,58 @@ export function printInitHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printNoteHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('note add')} ${s.dim('--title="..." [--ticket=KEY] [--tags=a,b]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Save a short note about a ticket to your local Recall vault. ${s.dim('[Pro]')}`,
+    `  Notes are saved at ${s.cyan('~/.ticketlens/recall/')} and matched into future ticket briefs.`,
+    `  The note body is read from stdin.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--title')}=${s.dim('TEXT')}        Note title ${s.dim('(required)')}`,
+    `    ${s.brand('--ticket')}=${s.dim('KEY')}        Ticket this note is about ${s.dim('(optional — omit for a general note)')}`,
+    `    ${s.brand('--tags')}=${s.dim('a,b')}          Comma-separated tags`,
+    `    ${s.brand('--include-attachments')}  Seed the note with text from this ticket's cached attachments`,
+    `    ${s.brand('--plain')}       Plain confirmation, no color (default when piped)`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}        Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} echo "Retry needs exponential backoff" | ticketlens note add --title="Retry gotcha" --ticket=PROD-123 --tags=bug`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printRecallHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('recall')} ${s.dim('<query|TICKET-KEY>')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Search your saved Recall notes. Local only — no network calls. ${s.dim('[Pro]')}`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--plain')}       Plain output, no color (default when piped)`,
+    `    ${s.brand('--full')}        Print each matching note's full body content`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens recall PROD-123`,
+    `    ${s.dim('$')} ticketlens recall "retry backoff"`,
+    `    ${s.dim('$')} ticketlens recall PROD-123 --plain`,
+    `    ${s.dim('$')} ticketlens recall PROD-123 --full`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printSwitchHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/note-command.mjs

@@ -0,0 +1,134 @@
+/**
+ * Implements `tl note add`. Order matters: the license check runs before
+ * stdin is read or anything is written, so an unlicensed user never has
+ * their input touched at all.
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { isLicensed, showUpgradePrompt } from './license.mjs';
+import { scanForSecrets } from './secret-scanner.mjs';
+import { writeNote } from './recall-vault.mjs';
+import { readCliToken } from './cli-auth.mjs';
+import { pushNote } from './recall-sync.mjs';
+import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
+import { extractText } from './attachment-text.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+import { createStyler } from './ansi.mjs';
+
+function defaultListAttachments(configDir, ticketKey) {
+  const cacheDir = path.join(configDir, 'cache', ticketKey);
+  try {
+    return fs.readdirSync(cacheDir).map(name => path.join(cacheDir, name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Pulls plain text out of already-cached ticket attachments, for
+ * `note add --include-attachments`. Silently skips any file extractText
+ * can't read (images, PDFs, unsupported formats) — this is an optional
+ * assist, never a requirement.
+ */
+function gatherAttachmentExcerpts(configDir, ticketKey, listAttachmentsFn, extractTextFn) {
+  const files = listAttachmentsFn(configDir, ticketKey);
+  const excerpts = files
+    .map(filePath => ({ name: path.basename(filePath), text: extractTextFn(filePath) }))
+    .filter(f => f.text);
+  if (excerpts.length === 0) return '';
+  const blocks = excerpts.map(f => `=== ${f.name} ===\n${f.text}`);
+  return `\n\n--- Attachment excerpts ---\n\n${blocks.join('\n\n')}`;
+}
+
+function defaultReadStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+    process.stdin.on('error', reject);
+  });
+}
+
+function parseFlag(cmdArgs, name) {
+  return cmdArgs.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+
+/**
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ written: boolean }>}
+ */
+export async function runNoteAdd(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  readStdin = defaultReadStdin,
+  isLicensedFn = isLicensed,
+  scanForSecretsFn = scanForSecrets,
+  writeNoteFn = writeNote,
+  readCliTokenFn = readCliToken,
+  pushNoteFn = pushNote,
+  incrementDraftKeptFn = incrementDraftKept,
+  incrementDraftDeletedFn = incrementDraftDeleted,
+  listAttachmentsFn = defaultListAttachments,
+  extractTextFn = extractText,
+  author = os.userInfo().username,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens note', { stream });
+    return { written: false };
+  }
+
+  const rawTitle = parseFlag(cmdArgs, 'title');
+  if (!rawTitle) {
+    stream.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
+    return { written: false };
+  }
+  // A title is one line: collapse any embedded newline so it can never be used
+  // to forge a fake "## heading" line when the note is later injected into a brief.
+  const title = rawTitle.replace(/[\r\n]+/g, ' ');
+
+  const ticketKey = parseFlag(cmdArgs, 'ticket');
+  if (ticketKey && !TICKET_KEY_PATTERN.test(ticketKey)) {
+    stream.write(`  Invalid --ticket value "${ticketKey}" — expected a ticket key like PROJ-123.\n`);
+    return { written: false };
+  }
+  const tagsArg = parseFlag(cmdArgs, 'tags');
+  const tags = tagsArg ? tagsArg.split(',').map(t => t.trim()).filter(Boolean) : [];
+
+  let body = await readStdin();
+  if (cmdArgs.includes('--include-attachments') && ticketKey) {
+    body += gatherAttachmentExcerpts(configDir, ticketKey, listAttachmentsFn, extractTextFn);
+  }
+
+  const scan = scanForSecretsFn({ title, tags, body });
+  if (scan.rejected) {
+    stream.write(`  Note not saved — ${scan.reasons.join(' ')}\n`);
+    incrementDraftDeletedFn(configDir);
+    return { written: false };
+  }
+  for (const warning of scan.warnings) {
+    stream.write(`  Warning: ${warning}\n`);
+  }
+
+  const ticketKeys = ticketKey ? [ticketKey] : [];
+  const { id } = writeNoteFn({ title, ticketKeys, tags, author, body }, { configDir });
+  incrementDraftKeptFn(configDir);
+  const styled = !cmdArgs.includes('--plain') && stream.isTTY;
+  const s = createStyler({ forceColor: styled, noColor: !styled });
+  stream.write(styled ? `\n  ${s.green('✔')} Saved note "${title}" (${id})\n\n` : `  Saved note "${title}" (${id})\n`);
+
+  const cliToken = readCliTokenFn(configDir);
+  if (cliToken) {
+    // Field names match PushRequest's validation rules (external_id, tickets) —
+    // the backend wire contract, not the local vault's internal camelCase shape.
+    await pushNoteFn(
+      { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body },
+      { cliToken, configDir, warn: (s) => stream.write(s) },
+    );
+  }
+
+  return { written: true };
+}

package/skills/jtb/scripts/lib/prompt-helpers.mjs

@@ -166,6 +166,34 @@ export async function promptScheduleAnswers(args = [], { stream = process.stderr
   return { time, email, timezone };
 }
 
+/**
+ * Three-way single-keystroke prompt: y / n / anything else counts as skip.
+ * Used for the Recall "is this pulling its weight?" pulse check.
+ *
+ * @returns {Promise<'y'|'n'|'skip'>}
+ */
+export function promptRecallPulse(question, { stream = process.stderr } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write(`\n  ${question}  ${s.dim('y/n/skip')}  `);
+  return flushStdin().then(() => new Promise(res => {
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    function onData(char) {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      stream.write('\n');
+      if (char === '\x03') process.exit(0);
+      if (char === 'y' || char === 'Y') { res('y'); return; }
+      if (char === 'n' || char === 'N') { res('n'); return; }
+      res('skip');
+    }
+    stdin.on('data', onData);
+  }));
+}
+
 export function promptYN(question, { stream = process.stderr } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   stream.write(`\n  ${question}  ${s.dim('y/N')}  `);

package/skills/jtb/scripts/lib/recall-command.mjs

@@ -0,0 +1,57 @@
+/**
+ * Implements `tl recall <query|TICKET-KEY>` — a search over saved Recall
+ * notes, local-first. When logged in, pulls the team vault down before
+ * searching (the user is explicitly waiting on this command, so the full
+ * request timeout applies here — unlike the passive brief-fetch pull path).
+ * A pull failure never blocks the local search from returning results.
+ */
+
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+import { isLicensed, showUpgradePrompt } from './license.mjs';
+import { listNotes } from './recall-vault.mjs';
+import { readCliToken } from './cli-auth.mjs';
+import { pullNotes } from './recall-sync.mjs';
+import { styleRecallResults } from './styled-assembler.mjs';
+
+/**
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runRecall(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  errorStream = process.stderr,
+  isLicensedFn = isLicensed,
+  listNotesFn = listNotes,
+  readCliTokenFn = readCliToken,
+  pullNotesFn = pullNotes,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens recall', { stream: errorStream });
+    return { ok: false };
+  }
+
+  const arg = cmdArgs.find(a => !a.startsWith('-'));
+  if (!arg) {
+    stream.write('Usage: ticketlens recall <query|TICKET-KEY>\n');
+    return { ok: false };
+  }
+
+  const cliToken = readCliTokenFn(configDir);
+  if (cliToken) {
+    await pullNotesFn({
+      cliToken,
+      configDir,
+      ...(cmdArgs.includes('--no-cache') && { ttlMs: 0 }),
+    });
+  }
+
+  const filter = TICKET_KEY_PATTERN.test(arg) ? { ticketKey: arg } : { query: arg };
+  const results = listNotesFn(filter, { configDir });
+
+  const styled = !cmdArgs.includes('--plain') && stream.isTTY;
+  const full = cmdArgs.includes('--full');
+  stream.write(styleRecallResults(results, { styled, full }) + '\n');
+  return { ok: true };
+}

package/skills/jtb/scripts/lib/recall-matcher.mjs

@@ -0,0 +1,41 @@
+/**
+ * Decides which saved Recall notes are relevant to a given ticket.
+ * Pure function — no file access, no network calls. Takes a ticket and a
+ * list of notes already loaded into memory, and returns the relevant ones.
+ */
+
+const KEYWORD_RE = /[a-z0-9]{4,}/g;
+const EXACT_TICKET_SCORE = 10;
+const TAG_OVERLAP_SCORE = 3;
+const TITLE_WORD_OVERLAP_SCORE = 1;
+
+function extractKeywords(text) {
+  return new Set((text ?? '').toLowerCase().match(KEYWORD_RE) ?? []);
+}
+
+/**
+ * @param {{ key: string, summary?: string, description?: string }} ticket
+ * @param {object[]} notes
+ * @returns {{ note: object, score: number }[]} sorted strongest match first
+ */
+export function matchNotes(ticket, notes) {
+  const ticketKeywords = extractKeywords(`${ticket.summary ?? ''} ${ticket.description ?? ''}`);
+
+  return notes
+    .map(note => {
+      let score = 0;
+
+      if (note.tickets?.includes(ticket.key)) score += EXACT_TICKET_SCORE;
+
+      const tagOverlap = (note.tags ?? []).filter(tag => ticketKeywords.has(tag.toLowerCase())).length;
+      score += tagOverlap * TAG_OVERLAP_SCORE;
+
+      const titleKeywords = extractKeywords(note.title);
+      const titleOverlap = [...titleKeywords].filter(word => ticketKeywords.has(word)).length;
+      score += titleOverlap * TITLE_WORD_OVERLAP_SCORE;
+
+      return { note, score };
+    })
+    .filter(match => match.score > 0)
+    .sort((a, b) => b.score - a.score);
+}