ticketlens 0.38.46 → 0.38.47

package/README.md

@@ -456,13 +456,13 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `issue_types`, `history`, `collisions`, `ledger`, `doctor`, `recall_add`, `recall_update`, `recall_delete`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — every CLI action now has an MCP tool, so any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `issue_types` is Free and Jira-only — pre-fetches and caches a profile's real creatable projects and issue types ahead of a `ticket_create` attempt, sharing its cache with that tool's own reactive enrichment; Linear/GitHub profiles get a clear "not available" instead of an empty result; `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; `ledger` exports the local, signed compliance audit trail (zero network) and requires Pro; every other tool needs Pro. `recall_update` overwrites an existing Recall note's body — internal plumbing for the note quality loop, not typically called directly. `recall_delete` is destructive and local-vault-only — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal to prompt against), so omitting it always fails rather than silently blocking. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `issue_types`, `history`, `collisions`, `ledger`, `doctor`, `recall_add`, `recall_update`, `recall_delete`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — every CLI action now has an MCP tool, so any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `issue_types` is Free and Jira-only — pre-fetches and caches a profile's real creatable projects and issue types ahead of a `ticket_create` attempt, sharing its cache with that tool's own reactive enrichment; Linear/GitHub profiles get a clear "not available" instead of an empty result; `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; `ledger` exports the local, signed compliance audit trail (zero network) and requires Pro; every other tool needs Pro. `recall_update` overwrites an existing Recall note's body — internal plumbing for the note quality loop, not typically called directly; its `attachments` array appends new files to whatever the note already has, same as `recall_add`'s, never replacing existing ones. `recall_delete` is destructive and local-vault-only — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal to prompt against), so omitting it always fails rather than silently blocking. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
 
 **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 (`~/.ticketlens/recall/<PREFIX>/<note-id>/`) — same 10 MB/file, 50 MB/call, 20-file caps as ticket attachments for the local save. With Team Recall sync active, the attachment syncs too — visible and downloadable from Console > Admin > Recall — but the sync path caps at 12 MB/call (the backend's request-size limit, lower than the 50 MB local-save cap). Going over it fails the whole push, not just the attachment — the note stays saved locally, but neither its text nor the attachment reaches the team until it's pushed within the cap. Attachments with plain-text content (detected from the actual bytes, not the filename) go through the same secret scan as the note body before syncing; a rejected scan blocks the whole push the same way.
+**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 (`~/.ticketlens/recall/<PREFIX>/<note-id>/`) — same 10 MB/file, 50 MB/call, 20-file caps as ticket attachments for the local save. `note patch --attach=path1,path2` (or `recall_update`'s `attachments` array) attaches more files to an existing note later — appended to what's already there, never replacing it; patch is local-vault only, so these are never pushed even if the note's original attachments were. With Team Recall sync active, the attachment syncs too — visible and downloadable from Console > Admin > Recall — but the sync path caps at 12 MB/call (the backend's request-size limit, lower than the 50 MB local-save cap). Going over it fails the whole push, not just the attachment — the note stays saved locally, but neither its text nor the attachment reaches the team until it's pushed within the cap. Attachments with plain-text content (detected from the actual bytes, not the filename) go through the same secret scan as the note body before syncing; a rejected scan blocks the whole push the same way.
 
 **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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.46",
+  "version": "0.38.47",
   "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.42.5 -->
+<!-- jtb-skill-version: 0.42.6 -->
 ---
 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.
@@ -397,7 +397,9 @@ When it does apply, run up to 3 rounds:
    ```
    `--expect-mtime` is what keeps this safe: if the file changed since step 1 (the user hand-edited it while you were drafting), the patch silently no-ops and prints "not found or already changed" — the user's own edit always wins, never gets clobbered by a stale background draft.
 
-   If this harness has TicketLens's MCP server configured (a tool named `recall_update` — often shown as `mcp__ticketlens__recall_update` — visible in your tool list), prefer it over the bash form: same license gate, same structural/secret-scan checks, same optimistic-concurrency behavior via `expectMtime` — just no shell command or stdin piping to construct. It accepts `id`/`body`/`ticket`/`expectMtime`.
+   `note patch` also takes `--attach=path1,path2` (Pro), same caps and secret-scan treatment as `note add`'s — new files are appended to whatever the note already has, never replacing existing attachments.
+
+   If this harness has TicketLens's MCP server configured (a tool named `recall_update` — often shown as `mcp__ticketlens__recall_update` — visible in your tool list), prefer it over the bash form: same license gate, same structural/secret-scan checks, same optimistic-concurrency behavior via `expectMtime` — just no shell command or stdin piping to construct. It accepts `id`/`body`/`ticket`/`expectMtime`/`attachments`.
 5. Repeat from step 1 (re-capture mtime/body fresh each round) up to 3 total rounds. If no round ever produces a fully-passing draft, patch in whichever round scored highest across all attempts, and let the "not found or already changed" message stand if that patch itself loses a late race — don't retry past round 3.
 
 This never calls any external API or bills any tokens beyond the session you already have open — the generator and validator are subagents inside your own Claude Code session, not a TicketLens server call.

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/mcp-server.mjs

@@ -393,11 +393,14 @@ async function callRecallAdd(args, { configDir, runNoteAddFn }) {
  * as buildNoteAddArgs above. `expectMtime` is optimistic-concurrency: a
  * caller that fetched a note via recall_search and wants to refine it
  * without racing a concurrent edit passes back the mtime it observed.
+ * `attachments` (backlog #21) is appended to whatever the note already has,
+ * same as buildNoteAddArgs's — never a replace.
  */
-function buildNotePatchArgs({ id, ticket, expectMtime }) {
+function buildNotePatchArgs({ id, ticket, expectMtime, attachments }) {
   const args = [`--id=${id}`];
   if (ticket) args.push(`--ticket=${ticket}`);
   if (expectMtime !== undefined) args.push(`--expect-mtime=${expectMtime}`);
+  if (Array.isArray(attachments) && attachments.length > 0) args.push(`--attach=${attachments.join(',')}`);
   return args;
 }
 

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

@@ -180,6 +180,7 @@ export const TOOLS = [
         body: { type: 'string', description: 'The replacement note body — brief, not a paragraph. ~20 (strict), 30 (balanced), or 50 (loose) words max — scales with recallStrictness — going over doesn\'t block the update, but prints a non-blocking warning.' },
         ticket: { type: 'string', description: 'Ticket key the note is about, e.g. PROJ-123. Optional — narrows the search when omitted, the vault is searched across all ticket prefixes.' },
         expectMtime: { type: 'number', description: 'The note file\'s mtime (ms) last observed by the caller. If the note changed since then, the patch is a no-op rather than an overwrite — optimistic concurrency, not a hard requirement.' },
+        attachments: { type: 'array', items: { type: 'string' }, description: 'Local file paths to attach (screenshots, logs, etc.) — appended to whatever the note already has, never replacing existing attachments. Same 10MB/file, 50MB/call, 20-file caps as recall_add. Local vault only — recall_update never syncs to a team backend, so this never pushes.' },
       },
       required: ['id', 'body'],
     },

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

@@ -228,7 +228,9 @@ export async function runNoteAdd(cmdArgs, {
  * meant to be typed by hand): the loop's generator subagent produces a body,
  * SKILL.md's orchestration pipes it through this command, and the new body
  * gets exactly the same structural and secret gates a user-typed body gets —
- * there is no weaker path here for AI-authored content.
+ * there is no weaker path here for AI-authored content. `--attach` works the
+ * same as `note add`'s — files are appended to whatever the note already has,
+ * never replacing them.
  *
  * @param {string[]} cmdArgs
  * @returns {Promise<{ patched: boolean }>}
@@ -245,6 +247,7 @@ export async function runNotePatch(cmdArgs, {
   resolveEffectiveRecallStrictnessFn = resolveEffectiveRecallStrictness,
   scanForSecretsFn = scanForSecrets,
   patchNoteBodyFn = patchNoteBody,
+  readAttachmentsFn = readAttachments,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
     showUpgradePrompt('pro', 'ticketlens note', { stream });
@@ -253,7 +256,7 @@ export async function runNotePatch(cmdArgs, {
 
   const id = parseFlag(cmdArgs, 'id');
   if (!id) {
-    stream.write('Usage: ticketlens note patch --id="..." [--ticket=KEY]\n');
+    stream.write('Usage: ticketlens note patch --id="..." [--ticket=KEY] [--attach=path1,path2]\n');
     return { patched: false };
   }
 
@@ -288,11 +291,18 @@ export async function runNotePatch(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] : [];
   const expectMtimeArg = parseFlag(cmdArgs, 'expect-mtime');
   const expectedMtimeMs = expectMtimeArg !== undefined ? Number(expectMtimeArg) : undefined;
-  const { patched } = patchNoteBodyFn({ id, ticketKeys, body, expectedMtimeMs }, { configDir });
-  stream.write(patched ? `  Updated note (${id})\n` : `  Note not updated — (${id}) not found or already changed.\n`);
+  const { patched } = patchNoteBodyFn({ id, ticketKeys, body, expectedMtimeMs, attachments }, { configDir });
+  const attachSuffix = patched && attachments.length > 0 ? ` + ${attachments.length} attachment(s)` : '';
+  stream.write(patched ? `  Updated note (${id})${attachSuffix}\n` : `  Note not updated — (${id}) not found or already changed.\n`);
   return { patched };
 }
 

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

@@ -90,7 +90,10 @@ function writeAttachments(noteDir, id, attachments) {
   if (attachments.length === 0) return [];
   const attachDir = attachmentsDirFor(noteDir, id);
   fs.mkdirSync(attachDir, { recursive: true });
-  const used = new Set();
+  // Seeded from what's already on disk, not just this call's batch — patchNoteBody
+  // can call this a second time against the same note id, and a same-named file
+  // from an earlier add/patch must count toward uniqueness too.
+  const used = new Set(fs.readdirSync(attachDir));
   const saved = [];
   for (const { filename, buffer } of attachments) {
     const uniqueName = uniquifyFilename(filename, used);
@@ -248,8 +251,10 @@ export function deleteNoteAnyPrefix(externalId, { configDir = DEFAULT_CONFIG_DIR
  * Overwrites an existing local note's body in place — used by the jtb skill's
  * generator/validator quality loop to swap in a better draft after `note add`
  * already saved the original. Patch-only: never creates a note, and every
- * frontmatter field except body is carried over unchanged, so this can never
- * become a covert way to retitle/retag/re-tie a note to a different ticket.
+ * frontmatter field except body and attachments is carried over unchanged, so
+ * this can never become a covert way to retitle/retag/re-tie a note to a
+ * different ticket. New attachments are appended to whatever the note already
+ * has — a patch refines a note, it never discards what's already attached.
  *
  * Guards, same failure-mode split as deleteNote: a malformed id or ticket key
  * is a caller bug (throw); a missing file, an externalId that doesn't match
@@ -257,17 +262,18 @@ export function deleteNoteAnyPrefix(externalId, { configDir = DEFAULT_CONFIG_DIR
  * (expectedMtimeMs) are all best-effort no-ops, not errors — the original
  * note is always left exactly as-is on any of these.
  *
- * @param {{ id: string, ticketKeys?: string[], body: string, expectedMtimeMs?: number }} params
+ * @param {{ id: string, ticketKeys?: string[], body: string, expectedMtimeMs?: number, attachments?: Array<{ filename: string, buffer: Buffer }> }} params
  * @param {{ configDir?: string }} [opts]
  * @returns {{ patched: boolean, path: string|null }}
  */
-export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs }, { configDir = DEFAULT_CONFIG_DIR } = {}) {
+export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs, attachments = [] }, { configDir = DEFAULT_CONFIG_DIR } = {}) {
   if (!EXTERNAL_ID_PATTERN.test(id)) {
     throw new Error(`Invalid note id: "${id}"`);
   }
 
   const prefix = resolvePrefix(ticketKeys[0]);
-  const notePath = path.join(prefixDir(configDir, prefix), id);
+  const dir = prefixDir(configDir, prefix);
+  const notePath = path.join(dir, id);
 
   if (!fs.existsSync(notePath)) {
     return { patched: false, path: null };
@@ -281,6 +287,13 @@ export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs }, {
     return { patched: false, path: notePath };
   }
 
+  // existing.attachments is the full list already on disk (from add and/or a
+  // prior patch) — carried forward here, or the drop bug returns: patch would
+  // silently strip the attachments: key, orphaning files that stay on disk but
+  // become permanently unlisted and unpushable.
+  const savedAttachments = writeAttachments(dir, id, attachments);
+  const mergedAttachments = [...existing.attachments, ...savedAttachments];
+
   const data = {
     title: existing.title,
     aliases: existing.aliases,
@@ -291,6 +304,7 @@ export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs }, {
     status: existing.status,
     sources: existing.sources,
     externalId: existing.externalId,
+    ...(mergedAttachments.length > 0 ? { attachments: mergedAttachments } : {}),
   };
 
   writeFileAtomically(notePath, serializeFrontmatter(data, body));