ticketlens 0.30.0 → 0.31.0

package/README.md

@@ -413,7 +413,9 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — 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 Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. 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.
+`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.
 
 **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/bin/ticketlens.mjs

@@ -542,7 +542,7 @@ switch (command) {
   case 'cloud-keys': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCloudKeysHelp(); break; }
 
-    const { listCloudKeys, addCloudKey, removeCloudKey, setPriority, setTimeout_, testCloudKey } =
+    const { listCloudKeys, addCloudKey, runCloudKeysRemove, setPriority, setTimeout_, testCloudKey } =
       await import('../skills/jtb/scripts/lib/cloud-keys.mjs');
 
     const cliToken = readCliToken();
@@ -592,12 +592,14 @@ switch (command) {
       if (subCmd === 'remove') {
         const provider = cmdArgs[1];
         if (!provider) {
-          process.stderr.write('Usage: ticketlens cloud-keys remove <provider>\n');
+          process.stderr.write('Usage: ticketlens cloud-keys remove <provider> [--yes|-y]\n');
           process.exitCode = 1;
           return;
         }
-        await removeCloudKey(cfg, provider);
-        process.stdout.write(`${s.brand('✓')} ${provider} key removed.\n`);
+        const forceYes = cmdArgs.includes('--yes') || cmdArgs.includes('-y');
+        const { removed } = await runCloudKeysRemove(cfg, provider, { forceYes });
+        if (removed) process.stdout.write(`${s.brand('✓')} ${provider} key removed.\n`);
+        else process.exitCode = 1;
         return;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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.26.0 -->
+<!-- jtb-skill-version: 0.27.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.
@@ -66,6 +66,8 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb assign PROD-1234 --to=me          # assign the ticket to yourself (Pro)
 ```
 
+**Destructive commands** (`note delete`, `cloud-keys remove`, `delete <profile>`) prompt for interactive y/N confirmation and refuse outright in a non-interactive shell unless `--yes` is passed — there is no way to silently skip this. Only pass `--yes` when the user has explicitly asked for that specific deletion in this conversation (their message *is* the confirmation); never add it to route around the prompt for a deletion you decided to make on your own.
+
 ## Prerequisites
 
 TicketLens supports two connection methods — check in this order:
@@ -91,7 +93,7 @@ If the first argument is `triage`:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/fetch-my-tickets.mjs $EXTRA_ARGS
+ticketlens triage $EXTRA_ARGS
 ```
 
 Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=acme`).
@@ -112,7 +114,7 @@ If the first argument is `collisions`:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/lib/run-collisions.mjs $EXTRA_ARGS
+ticketlens collisions $EXTRA_ARGS
 ```
 
 Where `$EXTRA_ARGS` are any flags passed (e.g. `--json`, `--plain`).
@@ -136,7 +138,7 @@ Follow the Prerequisites section above:
 
 Run:
 ```bash
-node ~/.agents/skills/jtb/scripts/fetch-ticket.mjs "$TICKET_KEY" $EXTRA_ARGS
+ticketlens "$TICKET_KEY" $EXTRA_ARGS
 ```
 
 Where `$TICKET_KEY` is the first argument (e.g. `PROD-1234`) and `$EXTRA_ARGS` are any flags passed (e.g. `--depth=0`).
@@ -234,9 +236,11 @@ echo "The body text of the note, one or more paragraphs." | \
   ticketlens note add --title="Short title" --ticket=TICKET-KEY --tags=a,b
 ```
 
+**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. Same rule whether you're constructing the bash command above or calling `recall_add` directly — see its tool description for the same guidance.
+
 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 (`ticketlens mcp` — `recall_add`/`recall_search` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same secret scan, same vault, same team sync, just no shell command to construct. Fall back to the bash form only when the MCP tools aren't available. 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.
+**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.
 
 ### Quality loop (Pro, in-session only)
 
@@ -284,7 +288,7 @@ ticketlens duplicates PROD-1234                               # find likely dupl
 
 The three write actions (comment/transition/assign) have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is. `duplicates` has neither, since nothing is written.
 
-**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (tools named `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create` — often shown as `mcp__ticketlens__ticket_comment` etc. — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same cooldown, same audit log. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list; if that's because this project has never registered the server, see the `ticketlens mcp install` note above (Recall section) — same guidance applies here.
 
 Requires a Pro license — on Free, all four no-op with an upgrade hint on stderr.
 

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

@@ -130,6 +130,10 @@ export function parseCommand(args) {
     return { command: 'mcp', args: args.slice(1) };
   }
 
+  if (first === 'cloud-keys') {
+    return { command: 'cloud-keys', args: args.slice(1) };
+  }
+
   if (first === 'comment') {
     return { command: 'comment', args: args.slice(1) };
   }

package/skills/jtb/scripts/lib/cloud-keys.mjs

@@ -4,6 +4,8 @@
  * All operations require a CLI token (set via `ticketlens login`).
  */
 
+import { confirmDestructive } from './confirm.mjs';
+
 const SUPPORTED_PROVIDERS = ['groq', 'anthropic', 'openai'];
 
 function apiBase(config) {
@@ -84,6 +86,29 @@ export async function removeCloudKey(config, provider) {
   await fetchApi(config, `/v1/ai-providers/${target.id}`, 'DELETE');
 }
 
+/**
+ * CLI-facing wrapper around removeCloudKey — gates the irreversible remote
+ * deletion behind a y/N confirmation (or --yes) before calling it.
+ */
+export async function runCloudKeysRemove(config, provider, opts = {}) {
+  const {
+    stream = process.stderr,
+    stdin = process.stdin,
+    forceYes = false,
+    confirmFn = confirmDestructive,
+    removeCloudKeyFn = removeCloudKey,
+  } = opts;
+
+  const confirmed = await confirmFn(`Remove the ${provider} key`, { stdin, stream, forceYes });
+  if (!confirmed) {
+    stream.write('  Aborted — key was not removed.\n');
+    return { removed: false };
+  }
+
+  await removeCloudKeyFn(config, provider);
+  return { removed: true };
+}
+
 export async function setPriority(config, provider, priority) {
   const target = await findProvider(config, provider);
   await fetchApi(config, `/v1/ai-providers/${target.id}`, 'PUT', { priority: Number(priority) });

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

@@ -42,10 +42,13 @@ export function getPackageMeta() {
   };
 }
 
-/** Human-readable relative time from an ISO date string. */
-export function timeAgo(dateStr) {
+/**
+ * Human-readable relative time from an ISO date string.
+ * @param {{ now?: () => Date }} [opts] - injectable clock, for deterministic tests only
+ */
+export function timeAgo(dateStr, { now = () => new Date() } = {}) {
   if (!dateStr) return '';
-  const diff = Date.now() - new Date(dateStr).getTime();
+  const diff = now().getTime() - new Date(dateStr).getTime();
   const mins = Math.floor(diff / 60000);
   if (mins < 60) return `${mins}m ago`;
   const hours = Math.floor(mins / 60);

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

@@ -0,0 +1,29 @@
+/**
+ * Interactive y/N confirmation gate for destructive, unrecoverable actions
+ * (deleting a Recall note, removing a stored cloud-provider key, etc).
+ * Enter with no input aborts — an accidental keystroke never destroys data.
+ * Non-interactive callers must pass forceYes explicitly (--yes/-y at the CLI).
+ */
+export async function confirmDestructive(action, opts = {}) {
+  const { stdin = process.stdin, stream = process.stderr, forceYes = false } = opts;
+
+  if (forceYes) return true;
+
+  if (!stdin.isTTY || !stdin.setRawMode) {
+    stream.write('  ✖ Non-interactive mode: pass --yes to confirm without a prompt.\n');
+    return false;
+  }
+
+  stream.write(`  ${action} — this cannot be restored. Continue?  y/N  `);
+  return new Promise(resolve => {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.once('data', buf => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      const confirmed = buf.toString().toLowerCase() === 'y';
+      stream.write(confirmed ? 'y\n' : 'N\n');
+      resolve(confirmed);
+    });
+  });
+}

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

@@ -574,11 +574,12 @@ export function printNoteHelp({ stream = process.stdout } = {}) {
     `  Code session — not typically invoked by hand. Every note it writes gets the`,
     `  same structural and secret-scan checks ${s.brand('note add')} applies to user input.`,
     '',
-    `  ${s.bold('ticketlens note delete')} ${s.dim('--id="..." [--ticket=KEY]')}  ${s.dim('[Pro]')}`,
+    `  ${s.bold('ticketlens note delete')} ${s.dim('--id="..." [--ticket=KEY] [--yes]')}  ${s.dim('[Pro]')}`,
     '',
     `  Removes a note from your local vault. Local only — if this note 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).`,
+    `  too is a manager action from the Console (Admin > Recall). In TTY mode,`,
+    `  prompts for confirmation before deleting. Pass ${s.cyan('--yes')} (or ${s.cyan('-y')}) to skip the prompt.`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -1263,7 +1264,7 @@ export function printCloudKeysHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.brand('list')}                          List configured providers`,
     `    ${s.brand('add')} ${s.dim('<provider> <key>')}         Add or replace an API key`,
-    `    ${s.brand('remove')} ${s.dim('<provider>')}            Remove a provider's key`,
+    `    ${s.brand('remove')} ${s.dim('<provider>')} ${s.dim('[--yes]')}   Remove a provider's key — prompts for confirmation`,
     `    ${s.brand('test')} ${s.dim('<provider>')}              Send a test request through the provider`,
     `    ${s.brand('priority')} ${s.dim('<provider> <N>')}      Set priority (lower = tried first)`,
     `    ${s.brand('timeout')} ${s.dim('<provider> <seconds>')} Set per-request timeout`,
@@ -1271,6 +1272,7 @@ export function printCloudKeysHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--timeout')}=${s.dim('N')}   Timeout in seconds when adding a key  ${s.dim('(default: 5)')}`,
+    `    ${s.brand('--yes')}, ${s.brand('-y')}   Skip the confirmation prompt when removing a key`,
     `    ${s.brand('-h')}, ${s.brand('--help')}  Show this help`,
     '',
     `  ${s.bold('PROVIDERS')}`,

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

@@ -36,7 +36,7 @@ const TOOLS = [
       properties: {
         title: { type: 'string', description: 'Short one-line title.' },
         ticket: { type: 'string', description: 'Optional ticket key, e.g. PROJ-123.' },
-        tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
+        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.' },
         body: { type: 'string', description: 'The note body — one or more paragraphs.' },
       },
       required: ['title', 'body'],

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

@@ -19,6 +19,7 @@ import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mj
 import { extractText } from './attachment-text.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { createStyler } from './ansi.mjs';
+import { confirmDestructive } from './confirm.mjs';
 
 function defaultListAttachments(configDir, ticketKey) {
   const cacheDir = path.join(configDir, 'cache', ticketKey);
@@ -226,8 +227,10 @@ export async function runNotePatch(cmdArgs, {
 export async function runNoteDelete(cmdArgs, {
   configDir = DEFAULT_CONFIG_DIR,
   stream = process.stderr,
+  stdin = process.stdin,
   isLicensedFn = isLicensed,
   deleteNoteFn = deleteNote,
+  confirmFn = confirmDestructive,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
     showUpgradePrompt('pro', 'ticketlens note', { stream });
@@ -236,7 +239,7 @@ export async function runNoteDelete(cmdArgs, {
 
   const id = parseFlag(cmdArgs, 'id');
   if (!id) {
-    stream.write('Usage: ticketlens note delete --id="..." [--ticket=KEY]\n');
+    stream.write('Usage: ticketlens note delete --id="..." [--ticket=KEY] [--yes|-y]\n');
     return { deleted: false };
   }
 
@@ -246,6 +249,13 @@ export async function runNoteDelete(cmdArgs, {
     return { deleted: false };
   }
 
+  const forceYes = cmdArgs.includes('--yes') || cmdArgs.includes('-y');
+  const confirmed = await confirmFn(`Delete note (${id})`, { stdin, stream, forceYes });
+  if (!confirmed) {
+    stream.write('  Aborted — note was not deleted.\n');
+    return { deleted: false };
+  }
+
   const { deleted } = deleteNoteFn({ external_id: id, tickets: ticketKey ? [ticketKey] : [] }, { configDir });
   stream.write(deleted
     ? `  Deleted note (${id}) — local vault only; see help for team-synced notes.\n`

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

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { DEFAULT_CONFIG_DIR, escapeLeadingHeading } from './config.mjs';
+import { DEFAULT_CONFIG_DIR, escapeLeadingHeading, timeAgo } from './config.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { parseFrontmatter, serializeFrontmatter } from './frontmatter.mjs';
 
@@ -348,7 +348,7 @@ export function rebuildIndex(prefix, { configDir = DEFAULT_CONFIG_DIR } = {}) {
     // content is lower trust than a user's own local notes, so it needs the same
     // heading-injection guard already applied in brief-assembler.mjs/styled-assembler.mjs.
     const ticketList = n.tickets.length > 0 ? ` — ${escapeLeadingHeading(n.tickets.join(', '))}` : '';
-    lines.push(`- [[${escapeLeadingHeading(n.title)}]]${ticketList} — ${n.created.split('T')[0]}`);
+    lines.push(`- [[${escapeLeadingHeading(n.title)}]]${ticketList} — ${timeAgo(n.created)}`);
   }
 
   writeFileAtomically(indexPath, lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/run-collisions.mjs

@@ -71,3 +71,12 @@ export async function runCollisions(args = [], opts = {}) {
     return { ok: false };
   }
 }
+
+// Run if invoked directly
+const isMain = process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/.*\//, ''));
+if (isMain) {
+  runCollisions(process.argv.slice(2)).catch(err => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exitCode = 1;
+  });
+}

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

@@ -115,7 +115,7 @@ export function styleRecallResults(digests, opts = {}) {
   if (!styled) {
     const entries = digests.map(d => {
       const ticketList = d.tickets?.length > 0 ? ` (${escapeLeadingHeading(d.tickets.join(', '))})` : '';
-      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${d.created.split('T')[0]}  [${d.id}]`;
+      const summary = `${escapeLeadingHeading(d.title)}${ticketList} — ${timeAgo(d.created)}  [${d.id}]`;
       return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
     });
     return entries.join(full ? '\n\n' : '\n');
@@ -124,9 +124,9 @@ export function styleRecallResults(digests, opts = {}) {
   const s = createStyler({ forceColor: true });
   const entries = digests.map(d => {
     const ticketList = d.tickets?.length > 0 ? ` ${s.dim(`(${escapeLeadingHeading(d.tickets.join(', '))})`)}` : '';
-    const date = s.dim(d.created.split('T')[0]);
+    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('—')} ${date}  ${id}`;
+    const summary = `${s.brand('●')} ${s.bold(escapeLeadingHeading(d.title))}${ticketList} ${s.dim('—')} ${ago}  ${id}`;
     return full ? `${summary}\n${escapeLeadingHeading(d.body)}` : summary;
   });
   return entries.join(full ? '\n\n' : '\n');