ticketlens 0.38.37 → 0.38.39

package/README.md

@@ -460,6 +460,8 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Tags matter for search relevance.** `--tags=a,b` accepts anything, but a generic tag (the project name, "gotcha", "bug") gives future search almost nothing to match on. Tag with what the note is actually *about* — the specific technology, error type, or root cause (`retry-backoff`, `null-pointer`, `auth-middleware`) — so it surfaces when someone else hits the same problem.
 
+**Local file attachments.** `note add --attach=path1,path2` (or the `recall_add` MCP tool's `attachments` array) saves a screenshot or file alongside the note, in your local vault only (`~/.ticketlens/recall/<PREFIX>/<note-id>/`) — same 10 MB/file, 50 MB/call, 20-file caps as ticket attachments. Unlike ticket attachments, this is never pushed to Team Recall sync — a teammate who pulls the note gets the text only, not the file.
+
 **Gaps** — every `ticketlens PROJ-123` brief also diffs the ticket's own description against its linked tickets (from the depth traversal you already requested) and its own downloaded attachments, looking for requirements mentioned there but missing here. Anything uncovered shows up under a `## Gaps` section, citing exactly where it came from — a linked ticket key or an attachment filename — as evidence, never an instruction to act on. Nothing is saved anywhere; it's recomputed fresh on every fetch. Requires a Pro license, same as Recall. No network call beyond what the brief already made.
 
 ---
@@ -801,6 +803,7 @@ ticketlens history <TICKET-KEY>               # Show urgency timeline for a tick
 
 # ── Recall ────────────────────────────────────────────────────────────────────
 echo "note body" | ticketlens note add --title="..." --ticket=CNV1-2 --tags=a,b  # Save a note [Pro]
+echo "note body" | ticketlens note add --title="..." --attach=shot.png,log.txt  # Save a note with local file attachments [Pro]
 ticketlens note delete --id="..." --ticket=CNV1-2  # Remove a note from your local vault [Pro]
 ticketlens recall CNV1-2                      # Search saved notes by ticket key [Pro]
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]

package/bin/ticketlens.mjs

@@ -743,7 +743,7 @@ switch (command) {
       });
       break;
     }
-    process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
+    process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b] [--attach=path1,path2]\n');
     process.exitCode = 1;
     break;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.37",
+  "version": "0.38.39",
   "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.40.0 -->
+<!-- jtb-skill-version: 0.42.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.
@@ -59,6 +59,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb cloud-keys priority groq 1        # set provider priority (lower = tried first)
 /jtb cloud-keys timeout anthropic 15   # set per-request timeout in seconds
 /jtb note add --title="gotcha text" --ticket=PROD-1234    # save a Recall note (Pro, body from stdin)
+/jtb note add --title="..." --attach=./shot.png,./log.txt # attach local files to a Recall note (Pro, local vault only — see note below)
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
 /jtb recall sync                       # retry any notes stuck in the local queue (Team+)
 /jtb recall settings                   # show effective retry-queue settings, fetched live (Team+)
@@ -370,6 +371,8 @@ echo "The body text of the note, one or more paragraphs." | \
 
 **Choosing tags:** derive them from this note's actual content — the specific technology, error type, root cause, or affected component (e.g. `retry-backoff`, `null-pointer`, `auth-middleware`) — never the project name or a generic category word like `gotcha` or `bug`. A tag like `jtb` or `ticketlens` tells a future search nothing that the ticket/project context doesn't already say; a tag like `retry-backoff` is what actually surfaces this note when someone else hits the same problem. A tag that just restates the title in different words, or one you can't trace to a specific sentence in the body, gives that same zero signal — if you can't point to the exact phrase that justifies it, drop it. Same rule whether you're constructing the bash command above or calling `recall_add` directly — see its tool description for the same guidance.
 
+**Attaching local files.** `note add --attach=path1,path2` (Pro) saves a screenshot or file alongside the note, in the local vault only — same 10 MB/file, 50 MB/call, 20-file caps as `ticket_create`/`ticket_comment`'s `--attach`. Unlike ticket attachments, this never uploads anywhere: it is not pushed to the team Console backend even with Team Recall sync active, so a teammate who pulls this note gets the text only, not the file. The `recall_add` MCP tool has a matching `attachments` array parameter — prefer it over the bash form when available, same rule as the rest of this section.
+
 To search saved notes directly (outside of automatic brief injection): `ticketlens recall "<query>"`.
 
 **Pick exactly one path per capture — never both.** If this harness has TicketLens's MCP server configured (tools named `recall_add`/`recall_search` — often shown as `mcp__ticketlens__recall_add` — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same secret scan, same vault, same team sync, just no shell command to construct. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list. If they're absent because this project has never registered the server, tell the user once: `ticketlens mcp install` writes (or merges into) this project's `.mcp.json` — don't run it yourself unprompted, since it changes what your harness auto-connects to on next launch, and the user should be the one deciding that. Calling both for the same insight creates two near-duplicate notes (no dedup exists between the two paths) and, with team sync on, two separate pushes for a manager to review.

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
+export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

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

@@ -107,7 +107,11 @@ export function assembleBrief(ticket, codeRefs = null, templateSections = null,
       const ticketList = note.tickets?.length > 0 ? ` (${escapeLeadingHeading(note.tickets.join(', '))})` : '';
       const badge = note.status === 'unverified' ? ' _(unverified)_' : '';
       const tagsLine = note.tags?.length > 0 ? `\n  Tags: ${escapeLeadingHeading(note.tags.join(', '))}` : '';
-      return `- **${escapeLeadingHeading(note.title)}**${ticketList}${badge}${tagsLine}\n  ${escapeLeadingHeading(note.body)}`;
+      // Filenames are already sanitized to [a-zA-Z0-9._-] before being saved
+      // (attachment-uploader.mjs's sanitizeFilename), so no heading-injection
+      // escaping is needed here — same trust chain as styled-assembler.mjs.
+      const attachmentsLine = note.attachments?.length > 0 ? `\n  Attachments: ${note.attachments.join(', ')}` : '';
+      return `- **${escapeLeadingHeading(note.title)}**${ticketList}${badge}${tagsLine}${attachmentsLine}\n  ${escapeLeadingHeading(note.body)}`;
     });
     const more = recallMoreCount > 0
       ? `\n\n**${recallMoreCount} more Recall note${recallMoreCount === 1 ? '' : 's'} linked to ${ticket.key} — run \`ticketlens recall ${ticket.key}\` for details.**`

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -362,10 +362,11 @@ async function callCollisions(args, { configDir, runCollisionsFn }) {
  * `--ticket=EVIL-999` stays inert precisely because it's never anything
  * but one opaque array element.
  */
-function buildNoteAddArgs({ title, ticket, tags }) {
+function buildNoteAddArgs({ title, ticket, tags, attachments }) {
   const args = [`--title=${title}`];
   if (ticket) args.push(`--ticket=${ticket}`);
   if (Array.isArray(tags) && tags.length > 0) args.push(`--tags=${tags.join(',')}`);
+  if (Array.isArray(attachments) && attachments.length > 0) args.push(`--attach=${attachments.join(',')}`);
   return args;
 }
 

package/skills/jtb/scripts/lib/mcp-tool-schemas.mjs

@@ -165,6 +165,7 @@ export const TOOLS = [
         ticket: { type: 'string', description: 'Optional ticket key, e.g. PROJ-123.' },
         tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags derived from this note\'s actual content — the specific technology, error type, root cause, or affected component (e.g. "retry-backoff", "null-pointer", "auth-middleware"). Never the project name or a generic category word like "gotcha" or "bug" — those provide no search signal to someone else looking for this note later. A tag that just restates the title in different words, or one you cannot trace to a specific sentence in the body, gives that same zero signal — if you cannot point to the exact phrase that justifies it, drop it.' },
         body: { type: 'string', description: 'The note body — one or more paragraphs.' },
+        attachments: { type: 'array', items: { type: 'string' }, description: 'Local file paths to attach (screenshots, logs, etc.), saved next to the note in the local vault. Same 10MB/file, 50MB/call, 20-file caps as ticket_comment/ticket_create. Unlike ticket attachments, these are never pushed to Team Recall sync — a teammate who pulls this note gets the text only, not the file.' },
       },
       required: ['title', 'body'],
     },

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

@@ -18,10 +18,42 @@ import { pushNote } from './recall-sync.mjs';
 import { enqueueNote, isRetryableFailure, maybeAutoFlush } from './recall-queue.mjs';
 import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
 import { extractText } from './attachment-text.mjs';
+import { readAttachments, MAX_ATTACHMENTS } from './attachment-uploader.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { createStyler } from './ansi.mjs';
 import { confirmDestructive } from './confirm.mjs';
 
+const ATTACHMENT_ERROR_MESSAGES = {
+  'not-found': 'file not found',
+  'not-a-file': 'not a file',
+  'empty': 'file is empty',
+  'too-large': 'exceeds 10 MB limit',
+  'total-size-exceeded': 'exceeds the 50 MB total limit for this note',
+};
+
+function parseAttachPaths(cmdArgs) {
+  const raw = parseFlag(cmdArgs, 'attach');
+  return raw ? raw.split(',').map(p => p.trim()).filter(Boolean) : [];
+}
+
+/**
+ * Splits a readAttachments() batch into what's usable for writeNote (plain
+ * {filename, buffer} pairs — the vault doesn't care about size/mimeType)
+ * and human-readable warning lines for anything that failed, same
+ * best-effort philosophy as ticket_create/comment's --attach: one bad path
+ * never blocks the note from being saved.
+ */
+function summarizeAttachments({ files, droppedCount }) {
+  const saved = [];
+  const warnings = [];
+  for (const f of files) {
+    if (f.ok) saved.push({ filename: f.filename, buffer: f.buffer });
+    else warnings.push(`  Skipped attachment ${f.path}: ${ATTACHMENT_ERROR_MESSAGES[f.error] ?? f.error}\n`);
+  }
+  if (droppedCount > 0) warnings.push(`  ${droppedCount} attachment(s) dropped — exceeds the ${MAX_ATTACHMENTS}-file limit per call.\n`);
+  return { saved, warnings };
+}
+
 function defaultListAttachments(configDir, ticketKey) {
   const cacheDir = path.join(configDir, 'cache', ticketKey);
   try {
@@ -84,6 +116,7 @@ export async function runNoteAdd(cmdArgs, {
   incrementDraftDeletedFn = incrementDraftDeleted,
   listAttachmentsFn = defaultListAttachments,
   extractTextFn = extractText,
+  readAttachmentsFn = readAttachments,
   author = os.userInfo().username,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
@@ -93,7 +126,7 @@ export async function runNoteAdd(cmdArgs, {
 
   const rawTitle = parseFlag(cmdArgs, 'title');
   if (!rawTitle) {
-    stream.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
+    stream.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b] [--attach=path1,path2]\n');
     return { written: false };
   }
   // A title is one line: collapse any embedded newline so it can never be used
@@ -130,16 +163,24 @@ export async function runNoteAdd(cmdArgs, {
     stream.write(`  Warning: ${warning}\n`);
   }
 
+  const attachPaths = parseAttachPaths(cmdArgs);
+  const { saved: attachments, warnings: attachWarnings } = attachPaths.length > 0
+    ? summarizeAttachments(readAttachmentsFn(attachPaths))
+    : { saved: [], warnings: [] };
+  for (const warning of attachWarnings) stream.write(warning);
+
   const ticketKeys = ticketKey ? [ticketKey] : [];
   // Captured once and threaded into writeNoteFn's now() override so the local
   // vault file's `created` and the pushed payload's captured_at can never skew
   // by the (short but real) gap between the local write and the push below.
   const capturedAt = new Date();
-  const { id } = writeNoteFn({ title, ticketKeys, tags, author, body }, { configDir, now: () => capturedAt });
+  const { id } = writeNoteFn({ title, ticketKeys, tags, author, body, attachments }, { configDir, now: () => capturedAt });
   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 attachSuffix = attachments.length > 0 ? ` + ${attachments.length} attachment(s)` : '';
+  const savedLine = `Saved note "${title}" (${id})${attachSuffix}`;
+  stream.write(styled ? `\n  ${s.green('✔')} ${savedLine}\n\n` : `  ${savedLine}\n`);
 
   const cliToken = readCliTokenFn(configDir);
   if (cliToken) {

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

@@ -49,24 +49,70 @@ function generateNoteId() {
   return `${Date.now()}-${randomBytes(3).toString('hex')}.md`;
 }
 
+// Also used for attachment bytes: Node ignores the encoding argument when
+// contents is a Buffer, so binary is written verbatim.
 export function writeFileAtomically(filePath, contents) {
   const tmpPath = `${filePath}.${process.pid}.tmp`;
   fs.writeFileSync(tmpPath, contents, 'utf8');
   fs.renameSync(tmpPath, filePath);
 }
 
+// A note's attachment folder is always named after its own id (minus the
+// .md extension) — same "derived, never trusted from user text" rule as
+// the note filename itself, so it needs no separate path-safety guard.
+function attachmentsDirFor(noteDir, id) {
+  return path.join(noteDir, id.replace(/\.md$/, ''));
+}
+
+// Two attachments in one note can share a basename (e.g. two screenshots
+// both named "screenshot.png" from different source folders) — dedupe so
+// the second write can't silently clobber the first.
+function uniquifyFilename(filename, used) {
+  const ext = path.extname(filename);
+  const stem = path.basename(filename, ext);
+  let candidate = filename;
+  let n = 1;
+  while (used.has(candidate)) {
+    n += 1;
+    candidate = `${stem}-${n}${ext}`;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+/**
+ * @param {string} noteDir
+ * @param {string} id
+ * @param {Array<{ filename: string, buffer: Buffer }>} attachments
+ * @returns {string[]} the filenames actually saved, in order
+ */
+function writeAttachments(noteDir, id, attachments) {
+  if (attachments.length === 0) return [];
+  const attachDir = attachmentsDirFor(noteDir, id);
+  fs.mkdirSync(attachDir, { recursive: true });
+  const used = new Set();
+  const saved = [];
+  for (const { filename, buffer } of attachments) {
+    const uniqueName = uniquifyFilename(filename, used);
+    writeFileAtomically(path.join(attachDir, uniqueName), buffer);
+    saved.push(uniqueName);
+  }
+  return saved;
+}
+
 /**
- * @param {{ title: string, ticketKeys?: string[], tags?: string[], author: string, sources?: string[], body: string }} note
+ * @param {{ title: string, ticketKeys?: string[], tags?: string[], author: string, sources?: string[], body: string, attachments?: Array<{ filename: string, buffer: Buffer }> }} note
  * @param {{ configDir?: string, now?: () => Date }} [opts]
  * @returns {{ id: string, path: string }}
  */
-export function writeNote({ title, ticketKeys = [], tags = [], author, sources = [], body }, { configDir = DEFAULT_CONFIG_DIR, now = () => new Date() } = {}) {
+export function writeNote({ title, ticketKeys = [], tags = [], author, sources = [], body, attachments = [] }, { configDir = DEFAULT_CONFIG_DIR, now = () => new Date() } = {}) {
   const prefix = resolvePrefix(ticketKeys[0]);
   const dir = prefixDir(configDir, prefix);
   fs.mkdirSync(dir, { recursive: true });
 
   const id = generateNoteId();
   const notePath = path.join(dir, id);
+  const savedAttachments = writeAttachments(dir, id, attachments);
 
   const data = {
     title,
@@ -80,6 +126,7 @@ export function writeNote({ title, ticketKeys = [], tags = [], author, sources =
     // A locally-authored note's own filename doubles as its push idempotency
     // key — pushing the same file twice must upsert one backend row, not two.
     externalId: id,
+    ...(savedAttachments.length > 0 ? { attachments: savedAttachments } : {}),
   };
 
   writeFileAtomically(notePath, serializeFrontmatter(data, body));
@@ -161,6 +208,7 @@ export function deleteNote({ external_id: externalId, tickets = [] }, { configDi
   }
 
   fs.unlinkSync(notePath);
+  fs.rmSync(attachmentsDirFor(path.dirname(notePath), externalId), { recursive: true, force: true });
   return { deleted: true, prefix };
 }
 
@@ -185,9 +233,11 @@ export function deleteNoteAnyPrefix(externalId, { configDir = DEFAULT_CONFIG_DIR
 
   const prefixes = [GENERAL_BUCKET, ...allPrefixDirs(configDir).filter(p => p !== GENERAL_BUCKET)];
   for (const prefix of prefixes) {
-    const notePath = path.join(prefixDir(configDir, prefix), externalId);
+    const dir = prefixDir(configDir, prefix);
+    const notePath = path.join(dir, externalId);
     if (fs.existsSync(notePath)) {
       fs.unlinkSync(notePath);
+      fs.rmSync(attachmentsDirFor(dir, externalId), { recursive: true, force: true });
       return { deleted: true, prefix };
     }
   }
@@ -268,8 +318,10 @@ function readNote(filePath) {
   // place every consumer (search display, index rebuild, brief injection) reads
   // a note through, so nothing downstream has to remember to guard against it.
   const title = (data.title ?? '(untitled note)').replace(/[\r\n]+/g, ' ');
+  const id = path.basename(filePath);
+  const attachments = data.attachments ?? [];
   return {
-    id: path.basename(filePath),
+    id,
     path: filePath,
     title,
     aliases: data.aliases ?? [],
@@ -280,6 +332,8 @@ function readNote(filePath) {
     status: data.status ?? 'unverified',
     sources: data.sources ?? [],
     externalId: data.externalId ?? null,
+    attachments,
+    attachmentsDir: attachments.length > 0 ? attachmentsDirFor(path.dirname(filePath), id) : null,
     body,
   };
 }

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

@@ -112,11 +112,14 @@ export function styleRecallResults(digests, opts = {}) {
     return 'No matching notes found.';
   }
 
+  const attachmentBadge = d => d.attachments?.length > 0 ? `  (${d.attachments.length} attachment${d.attachments.length === 1 ? '' : 's'})` : '';
+  const attachmentLine = d => d.attachments?.length > 0 ? `\nAttachments: ${d.attachments.join(', ')}` : '';
+
   if (!styled) {
     const entries = digests.map(d => {
       const ticketList = d.tickets?.length > 0 ? ` (${escapeLeadingHeading(d.tickets.join(', '))})` : '';
-      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${timeAgo(d.created)}  [${d.id}]`;
-      return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
+      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${timeAgo(d.created)}  [${d.id}]${attachmentBadge(d)}`;
+      return full ? `${summary}${attachmentLine(d)}\n${escapeLeadingHeading(d.body)}` : summary;
     });
     return entries.join(full ? '\n\n' : '\n');
   }
@@ -126,8 +129,9 @@ export function styleRecallResults(digests, opts = {}) {
     const ticketList = d.tickets?.length > 0 ? ` ${s.dim(`(${escapeLeadingHeading(d.tickets.join(', '))})`)}` : '';
     const ago = s.dim(timeAgo(d.created));
     const id = s.dim(`[${d.id}]`);
-    const summary = `${s.brand('●')} ${s.bold(escapeLeadingHeading(d.title))}${ticketList} ${s.dim('—')} ${ago}  ${id}`;
-    return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
+    const badge = d.attachments?.length > 0 ? s.dim(attachmentBadge(d)) : '';
+    const summary = `${s.brand('●')} ${s.bold(escapeLeadingHeading(d.title))}${ticketList} ${s.dim('—')} ${ago}  ${id}${badge}`;
+    return full ? `${summary}${attachmentLine(d)}\n${escapeLeadingHeading(d.body)}` : summary;
   });
   return entries.join(full ? '\n\n' : '\n');
 }
@@ -245,7 +249,10 @@ export function styleBrief(ticket, codeRefs = null, opts = {}) {
       const ticketList = note.tickets?.length > 0 ? ` ${s.dim(`(${escapeLeadingHeading(note.tickets.join(', '))})`)}` : '';
       const badge = note.status === 'unverified' ? ` ${s.dim('(unverified)')}` : '';
       const tagsLine = note.tags?.length > 0 ? `\n  ${s.dim(`Tags: ${escapeLeadingHeading(note.tags.join(', '))}`)}` : '';
-      return `${s.brand('●')} ${s.bold(escapeLeadingHeading(note.title))}${ticketList}${badge}${tagsLine}\n  ${escapeLeadingHeading(note.body)}`;
+      // Filenames are already sanitized to [a-zA-Z0-9._-] before being saved
+      // (attachment-uploader.mjs), so no heading-injection escaping is needed here.
+      const attachmentsLine = note.attachments?.length > 0 ? `\n  ${s.dim(`Attachments: ${note.attachments.join(', ')}`)}` : '';
+      return `${s.brand('●')} ${s.bold(escapeLeadingHeading(note.title))}${ticketList}${badge}${tagsLine}${attachmentsLine}\n  ${escapeLeadingHeading(note.body)}`;
     });
     const more = recallMoreCount > 0
       ? `\n\n${s.bold(s.yellow(`${recallMoreCount} more Recall note${recallMoreCount === 1 ? '' : 's'} linked to ${ticket.key} — run`))} ${s.bold(s.brand(`ticketlens recall ${ticket.key}`))} ${s.bold(s.yellow('for details.'))}`