ticketlens 0.21.1 → 0.21.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "bin/",
     "scripts/",
     "skills/jtb/SKILL.md",
+    "skills/jtb/hooks/",
     "skills/jtb/scripts/lib/",
     "skills/jtb/scripts/fetch-ticket.mjs",
     "skills/jtb/scripts/fetch-my-tickets.mjs"

package/scripts/postinstall.mjs

@@ -62,6 +62,18 @@ if (updated === 0 && skipped === TARGETS.length) {
   console.log('    To install: ticketlens update-skill');
 }
 
+// Recall nudge hooks — best-effort, never breaks the install.
+try {
+  const { setupRecallHooks } = await import('../skills/jtb/scripts/lib/hooks-setup.mjs');
+  for (const r of setupRecallHooks()) {
+    if (r.status === 'installed') console.log(`  ✔ Recall nudge hooks installed in ${r.label}`);
+    else if (r.status === 'error') console.warn(`  ⚠ Recall nudge hooks: ${r.label} — ${r.reason}`);
+    // 'unchanged' and 'skipped' are silent — nothing changed, nothing to report.
+  }
+} catch {
+  // Silent on failure — never breaks the install.
+}
+
 // First-run banner + tl-alias status. Best-effort: npm >=7 hides this output
 // unless the user passes --foreground-scripts, so the guaranteed channel is
 // the first bare `tl`/`ticketlens` run added in a later phase. Never throws —

package/skills/jtb/SKILL.md

@@ -210,6 +210,8 @@ Do not capture: routine/obvious information, anything already fully covered by t
 
 Capture **at the moment you confirm the insight**, not deferred to the end of the session — don't ask the user first, just do it. It requires a Pro license; on a Free account it will no-op with an upgrade hint on stderr, which is fine to ignore. It never blocks or fails the session.
 
+Immediately before dispatching the call, say one line in your response: `🔖 Recall-flag: <one-line reason>`. This is a fixed marker some harness setups scan for to confirm captures are actually happening — always emit it right when you decide to capture, even if you go on to call `note add` in the same breath.
+
 ### How to dispatch the call
 
 If your environment lets you dispatch a tool call without waiting for its result — a background task, an async subagent, a fire-and-forget job — use that mechanism for this call, so it doesn't block your primary work while the note syncs to the team. If you have no such mechanism, call it synchronously; it's fast, and it never blocks or fails your session either way, so there's no harm in the fallback.

package/skills/jtb/hooks/recall-nudge-lib.mjs

@@ -0,0 +1,96 @@
+/**
+ * Shared helpers for the Recall nudge hooks (recall-nudge-post-tool.mjs,
+ * recall-nudge-stop.mjs). Both read the same Claude Code hook stdin JSON
+ * and the same session transcript — kept in one place so the detection
+ * logic can't drift between the two hooks.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const TICKET_KEY_RE = /\b[A-Z][A-Z0-9]{1,9}-\d+\b/;
+export const RECALL_FLAG_RE = /🔖\s*Recall-flag:/;
+export const NOTE_ADD_RE = /\bticketlens\s+note\s+add\b|\/jtb\s+note\b/;
+
+export function readStdinJson() {
+  const raw = fs.readFileSync(0, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function statePath(sessionId) {
+  return path.join(os.tmpdir(), `ticketlens-recall-nudge-${sessionId || 'unknown'}.json`);
+}
+
+export function readState(sessionId) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(sessionId), 'utf8'));
+  } catch {
+    return { ticketToolCalls: 0, lastNudgeAt: 0 };
+  }
+}
+
+export function writeState(sessionId, state) {
+  try {
+    fs.writeFileSync(statePath(sessionId), JSON.stringify(state));
+  } catch { /* best-effort — a lost nudge counter is not worth failing the hook over */ }
+}
+
+/**
+ * Reads the transcript (JSONL) and returns simple booleans about what
+ * happened this session. Best-effort: any read/parse failure returns all
+ * false rather than throwing — a broken transcript must never block Claude.
+ *
+ * Deliberately narrow about WHERE each pattern is allowed to match — jtb's
+ * own SKILL.md instructions contain the literal strings "🔖 Recall-flag:"
+ * and "ticketlens note add" as examples. Matching against the whole raw
+ * entry (as an earlier version of this function did) means loading the
+ * skill at all permanently false-positives both checks: sawRecallFlag gets
+ * stuck true (silently disabling the mid-session nudge, since it thinks
+ * Claude just flagged something every time) and sawNoteAdd gets stuck true
+ * (silently disabling the Stop-hook check, since it thinks a note was
+ * already added). Only count a real assistant-authored text block for the
+ * flag, and only a real executed Bash command for note-add.
+ */
+export function scanTranscript(transcriptPath) {
+  const result = { sawTicketKey: false, sawRecallFlag: false, sawNoteAdd: false };
+  let lines;
+  try {
+    lines = fs.readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return result;
+  }
+
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    // Ticket-key detection stays broad (whole entry, any role) — it's only
+    // the weaker "did ticket work happen at all" signal, and a rare false
+    // positive here just means an extra harmless once-per-session check.
+    if (TICKET_KEY_RE.test(JSON.stringify(entry))) result.sawTicketKey = true;
+
+    if (entry.type !== 'assistant') continue;
+    const blocks = entry.message?.content;
+    if (!Array.isArray(blocks)) continue;
+
+    for (const block of blocks) {
+      if (block.type === 'text' && RECALL_FLAG_RE.test(block.text ?? '')) {
+        result.sawRecallFlag = true;
+      }
+      if (block.type === 'tool_use' && block.name === 'Bash' && NOTE_ADD_RE.test(block.input?.command ?? '')) {
+        result.sawNoteAdd = true;
+      }
+    }
+  }
+
+  return result;
+}

package/skills/jtb/hooks/recall-nudge-post-tool.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook (matcher: Bash) — mid-session Recall nudge.
+ *
+ * Non-blocking by design: this only prints an advisory reminder to stdout
+ * every NUDGE_EVERY ticket-related Bash calls, and only if Claude hasn't
+ * self-flagged a Recall-worthy insight (🔖 Recall-flag:) since the last one.
+ * Never exits non-zero — a mid-session nudge must never interrupt real work.
+ */
+
+import { readStdinJson, statePath, readState, writeState, TICKET_KEY_RE, scanTranscript } from './recall-nudge-lib.mjs';
+
+const NUDGE_EVERY = 8; // ticket-related Bash calls between nudges
+
+const input = readStdinJson();
+const command = input?.tool_input?.command ?? '';
+const sessionId = input?.session_id;
+const transcriptPath = input?.transcript_path;
+
+if (!TICKET_KEY_RE.test(command) || !sessionId) {
+  process.exit(0);
+}
+
+const state = readState(sessionId);
+state.ticketToolCalls = (state.ticketToolCalls ?? 0) + 1;
+
+// If Claude already self-flagged since we last reset, don't nag — reset the
+// counter so the next nudge only fires after another full quiet stretch.
+if (transcriptPath) {
+  const { sawRecallFlag } = scanTranscript(transcriptPath);
+  if (sawRecallFlag) {
+    state.ticketToolCalls = 0;
+    writeState(sessionId, state);
+    process.exit(0);
+  }
+}
+
+if (state.ticketToolCalls >= NUDGE_EVERY) {
+  state.ticketToolCalls = 0;
+  state.lastNudgeAt = Date.now();
+  writeState(sessionId, state);
+  process.stdout.write(
+    'Reminder (not a request for action right now): if something non-obvious was ' +
+    'confirmed in the last stretch of ticket work — a gotcha, a root cause, a ' +
+    'decision with non-obvious rationale — capture it now via `ticketlens note add` ' +
+    'per the jtb skill\'s Recall guidance, then keep going.\n',
+  );
+  process.exit(0);
+}
+
+writeState(sessionId, state);
+process.exit(0);

package/skills/jtb/hooks/recall-nudge-stop.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — end-of-session Recall check.
+ *
+ * Blocks (exit 2) at most ONCE per session — never traps the user in a
+ * loop regardless of how Claude responds. Two cases force a check:
+ *   1. Claude flagged something (🔖 Recall-flag:) but never called note add
+ *      — a broken promise, the strongest signal something was missed.
+ *   2. Ticket work happened all session with zero flags and zero notes
+ *      — the weaker "did anything ever get considered?" catch.
+ * Anything else (no ticket work at all, or a note was already added) exits
+ * clean — this must never be the reason a session can't end.
+ */
+
+import { readStdinJson, readState, writeState, scanTranscript } from './recall-nudge-lib.mjs';
+
+const input = readStdinJson();
+const sessionId = input?.session_id;
+const transcriptPath = input?.transcript_path;
+
+if (!sessionId || !transcriptPath) process.exit(0);
+
+const state = readState(sessionId);
+if (state.stopChecked) process.exit(0); // already asked once this session — respect the answer
+
+const { sawTicketKey, sawRecallFlag, sawNoteAdd } = scanTranscript(transcriptPath);
+
+if (!sawTicketKey || sawNoteAdd) {
+  process.exit(0); // no ticket work, or already captured — nothing to force
+}
+
+state.stopChecked = true;
+writeState(sessionId, state);
+
+if (sawRecallFlag) {
+  process.stderr.write(
+    'You flagged something as Recall-worthy (🔖 Recall-flag:) earlier this session but ' +
+    'never called `ticketlens note add`. Do that now, or say explicitly why it turned ' +
+    'out not to qualify — then you can finish.\n',
+  );
+} else {
+  process.stderr.write(
+    'This session touched ticket work but nothing was ever captured to Recall. If a ' +
+    'non-obvious insight, gotcha, or decision came up, capture it now via ' +
+    '`ticketlens note add`. If genuinely nothing qualified, just say so — then finish.\n',
+  );
+}
+process.exit(2);

package/skills/jtb/scripts/lib/hooks-setup.mjs

@@ -0,0 +1,115 @@
+/**
+ * Installs the Recall nudge hooks (recall-nudge-post-tool.mjs,
+ * recall-nudge-stop.mjs) into any detected Claude Code settings.json —
+ * run from postinstall.mjs on every install/update so a user never has to
+ * wire this by hand. Idempotent: safe to run on every `npm install`.
+ *
+ * Never touches an existing settings.json's other content, and never
+ * throws — a malformed or unreadable settings.json is skipped, not
+ * overwritten, so a broken install can never corrupt the user's config.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOOKS_DIR = join(__dirname, '..', '..', 'hooks');
+const POST_TOOL_SCRIPT = join(HOOKS_DIR, 'recall-nudge-post-tool.mjs');
+const STOP_SCRIPT       = join(HOOKS_DIR, 'recall-nudge-stop.mjs');
+
+// Distinctive substring used to find/replace our own entries on re-install —
+// never matches anything a user could plausibly have written by hand.
+const MARKER = 'recall-nudge-post-tool.mjs';
+const STOP_MARKER = 'recall-nudge-stop.mjs';
+
+const CLAUDE_DIRS = [
+  join(homedir(), '.claude'),
+  join(homedir(), '.claude-work'),
+];
+
+function makeHookEntry(scriptPath, matcher) {
+  return {
+    matcher,
+    hooks: [
+      {
+        type: 'command',
+        command: `node "${scriptPath}"`,
+        timeout: 5,
+      },
+    ],
+  };
+}
+
+function upsertHookEntry(list, marker, entry) {
+  const idx = list.findIndex(h =>
+    (h.hooks || []).some(inner => typeof inner.command === 'string' && inner.command.includes(marker)),
+  );
+  if (idx === -1) {
+    list.push(entry);
+    return 'added';
+  }
+  if (JSON.stringify(list[idx]) === JSON.stringify(entry)) return 'unchanged';
+  list[idx] = entry;
+  return 'updated';
+}
+
+function installInto(settingsPath) {
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      return { status: 'skipped', reason: 'malformed settings.json — left untouched' };
+    }
+  }
+
+  settings.hooks ??= {};
+  settings.hooks.PostToolUse ??= [];
+  settings.hooks.Stop ??= [];
+
+  const postResult = upsertHookEntry(
+    settings.hooks.PostToolUse,
+    MARKER,
+    makeHookEntry(POST_TOOL_SCRIPT, 'Bash'),
+  );
+  const stopResult = upsertHookEntry(
+    settings.hooks.Stop,
+    STOP_MARKER,
+    makeHookEntry(STOP_SCRIPT, '*'),
+  );
+
+  if (postResult === 'unchanged' && stopResult === 'unchanged') {
+    return { status: 'unchanged' };
+  }
+
+  const tmpPath = `${settingsPath}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  // Atomic on POSIX — avoids ever leaving settings.json half-written.
+  renameSync(tmpPath, settingsPath);
+
+  return { status: 'installed', postResult, stopResult };
+}
+
+/**
+ * @returns {{ label: string, status: string }[]} one entry per Claude
+ *   directory found on this machine, for the caller to log.
+ */
+export function setupRecallHooks() {
+  const results = [];
+
+  for (const dir of CLAUDE_DIRS) {
+    if (!existsSync(dir)) continue;
+    const settingsPath = join(dir, 'settings.json');
+    try {
+      mkdirSync(dir, { recursive: true });
+      const result = installInto(settingsPath);
+      results.push({ label: dir, ...result });
+    } catch (err) {
+      results.push({ label: dir, status: 'error', reason: err.message });
+    }
+  }
+
+  return results;
+}