ticketlens 0.21.0 → 0.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "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,72 @@
+/**
+ * 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.
+ */
+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 text;
+    try {
+      const entry = JSON.parse(line);
+      // Transcript entries vary by role/type; flatten whatever text exists.
+      text = JSON.stringify(entry);
+    } catch {
+      continue;
+    }
+    if (TICKET_KEY_RE.test(text)) result.sawTicketKey = true;
+    if (RECALL_FLAG_RE.test(text)) result.sawRecallFlag = true;
+    if (NOTE_ADD_RE.test(text)) 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/cli-auth.mjs

@@ -25,13 +25,37 @@ export function readCliToken(configDir = DEFAULT_CONFIG_DIR) {
   }
 }
 
-export function saveCliToken(token, configDir = DEFAULT_CONFIG_DIR) {
+// Server-asserted tier (personal or team-seat) synced alongside the token on
+// every login/sync — separate from the signed, offline license.json file.
+// Lets team-invited members get Pro-equivalent CLI access without a personal
+// TL- key, mirroring what the manager already pays for.
+export function readCliTokenTier(configDir = DEFAULT_CONFIG_DIR) {
+  const p = cliTokenPath(configDir);
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf8'));
+    return typeof data.tier === 'string' ? data.tier : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCliToken(token, configDir = DEFAULT_CONFIG_DIR, tier = undefined) {
   mkdirSync(configDir, { recursive: true });
   const p = cliTokenPath(configDir);
-  writeFileSync(p, JSON.stringify({ token }, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+  const payload = tier === undefined ? { token } : { token, tier };
+  writeFileSync(p, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   chmodSync(p, 0o600);
 }
 
+// Updates just the cached tier without touching the token — used by `tl sync`
+// to keep entitlement fresh between logins.
+export function saveCliTokenTier(tier, configDir = DEFAULT_CONFIG_DIR) {
+  const token = readCliToken(configDir);
+  if (!token) return;
+  saveCliToken(token, configDir, tier);
+}
+
 export function deleteCliToken(configDir = DEFAULT_CONFIG_DIR) {
   const p = cliTokenPath(configDir);
   if (existsSync(p)) {

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;
+}

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

@@ -5,6 +5,7 @@ import crypto from 'node:crypto';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { createStyler } from './ansi.mjs';
 import { siteBase } from './api-utils.mjs';
+import { readCliTokenTier } from './cli-auth.mjs';
 
 // Mixed into the HMAC key so that knowing the license key alone is not sufficient
 // to forge a valid signature — an attacker also needs this constant from the source.
@@ -100,6 +101,15 @@ export function isLicensed(tier, configDir = DEFAULT_CONFIG_DIR) {
   if (required === 0) return true;
   if (process.env.TICKETLENS_SKIP_LICENSE === 'true') return true;
 
+  if (checkOwnLicense(required, configDir)) return true;
+
+  // Team-seat entitlement, server-asserted and synced via login/`tl sync` —
+  // covers invited team members who never activated a personal TL- key.
+  const syncedTier = LICENSE_TIERS[readCliTokenTier(configDir)] ?? 0;
+  return syncedTier >= required;
+}
+
+function checkOwnLicense(required, configDir) {
   const license = readLicense(configDir);
   if (!license) return false;
 

package/skills/jtb/scripts/lib/login-flow.mjs

@@ -83,7 +83,12 @@ export async function runLogin({
     return;
   }
 
-  saveCliTokenFn(token);
+  let tier;
+  try {
+    tier = (await res.json())?.tier;
+  } catch { /* tier is best-effort — token is still valid */ }
+
+  saveCliTokenFn(token, undefined, tier);
   stream.write(`\x1b[A\r\x1b[2K  ${s.green('✔')} Logged in.\n`);
 
   // Flow 1: pull team Jira config for Pro/Team members (silently skipped for Free)

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

@@ -5,7 +5,7 @@
  * Server wins on all non-credential fields (shape, prefixes, URLs, etc.).
  */
 
-import { readCliToken } from './cli-auth.mjs';
+import { readCliToken, saveCliTokenTier } from './cli-auth.mjs';
 import {
   loadProfiles,
   loadCredentials,
@@ -88,6 +88,8 @@ export async function syncProfiles({
   let json;
   try { json = await res.json(); } catch { return { error: 'invalid-json' }; }
 
+  if (typeof json?.tier === 'string') saveCliTokenTier(json.tier, configDir);
+
   const remoteProfiles = Array.isArray(json?.profiles) ? json.profiles : [];
   const localConfig  = loadProfiles(configDir) || { profiles: {} };
   const localCreds   = loadCredentials(configDir);