ticketlens 0.17.0 → 0.18.0

package/README.md

@@ -400,6 +400,8 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Team sync:** on a Team plan with Recall enabled for your account (owner-managed, per-tier or per-client), notes also sync to your team's shared pool — `note add` pushes in the background, `recall` pulls the team's notes (cached 4h) before searching. A team manager reviews and verifies incoming notes at `console/admin/recall` before they're marked trusted. Without Team Recall entitlement, everything stays on your machine — no network call.
 
+**Offline resilience:** if a team push fails for a transient reason (network error, timeout, or a 5xx from the backend), the note stays safely in your local vault and is queued for retry — nothing is lost. The queue flushes automatically in the background (at most once every 15 minutes, whenever `recall` or `note add` next talks to the network), or on demand with `ticketlens recall sync`. A session-expired (401) or not-entitled (403) push is never queued — those need you to act (`ticketlens login`, or an owner grant), not a retry. Queued entries expire after 30 days and are capped at 200; switching accounts never flushes a note under the wrong login.
+
 `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.
 
 **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.
@@ -674,6 +676,7 @@ ticketlens history <TICKET-KEY>               # Show urgency timeline for a tick
 echo "note body" | ticketlens note add --title="..." --ticket=CNV1-2 --tags=a,b  # Save a note [Pro]
 ticketlens recall CNV1-2                      # Search saved notes by ticket key [Pro]
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
+ticketlens recall sync                        # Retry any notes stuck in the local queue [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -752,6 +755,7 @@ ticketlens triage --digest               # POST scored triage results to digest
 ticketlens schedule                      # Set up a scheduled daily digest
 ticketlens note add --title="..."        # Save a Recall note (body from stdin)
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
+ticketlens recall sync                   # Retry any notes stuck in the local queue
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -637,6 +637,16 @@ switch (command) {
 
   case 'recall': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printRecallHelp(); break; }
+    if (cmdArgs[0] === 'sync') {
+      const { runRecallSync } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
+      runRecallSync(cmdArgs.slice(1)).then(({ ok }) => {
+        if (!ok) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
+      break;
+    }
     const { runRecall } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
     runRecall(cmdArgs).then(({ ok }) => {
       if (!ok) process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.17.0",
+  "version": "0.18.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.17.0 -->
+<!-- jtb-skill-version: 0.18.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.
@@ -53,6 +53,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb cloud-keys timeout anthropic 15   # set per-request timeout in seconds
 /jtb note "gotcha text" --ticket=PROD-1234    # save a Recall note (Pro)
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
+/jtb recall sync                       # retry any notes stuck in the local queue (Pro)
 ```
 
 ## Prerequisites
@@ -241,7 +242,7 @@ This never calls any external API or bills any tokens beyond the session you alr
 **Known limitation:** `note patch` only updates the local vault copy. If `note add` already pushed the original draft to a team (Team Recall enabled), a later refinement from this loop is *not* re-pushed — teammates who already pulled the note keep the original draft until this is addressed in a future iteration.
 
 ### Privacy
-Recall notes are stored locally at `~/.ticketlens/recall/`. On a Free/Pro account with no Team Recall entitlement, they never leave the machine — no network calls. On a Team account with Recall enabled (owner-managed, may vary per user), notes also sync to the team's shared pool in the background so teammates can benefit from them too; a team manager reviews and verifies each incoming note before it's marked trusted.
+Recall notes are stored locally at `~/.ticketlens/recall/`. On a Free/Pro account with no Team Recall entitlement, they never leave the machine — no network calls. On a Team account with Recall enabled (owner-managed, may vary per user), notes also sync to the team's shared pool in the background so teammates can benefit from them too; a team manager reviews and verifies each incoming note before it's marked trusted. If a team push fails for a transient reason (network error, timeout, 5xx), the note is queued locally and retried automatically in the background, or on demand with `ticketlens recall sync` — a session-expired or not-entitled push is never queued, since retrying those can't succeed without the user acting first.
 
 ---
 

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

@@ -536,12 +536,17 @@ export function printRecallHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--full')}        Print each matching note's full body content`,
     `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
     '',
+    `  ${s.bold('COMMANDS')}`,
+    '',
+    `    ${s.brand('sync')}          Manually retry any team-synced notes stuck in the local retry queue ${s.dim('[Pro, requires login]')}`,
+    '',
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens recall PROD-123`,
     `    ${s.dim('$')} ticketlens recall "retry backoff"`,
     `    ${s.dim('$')} ticketlens recall PROD-123 --plain`,
     `    ${s.dim('$')} ticketlens recall PROD-123 --full`,
+    `    ${s.dim('$')} ticketlens recall sync`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

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

@@ -14,6 +14,7 @@ import { checkNoteStructure } from './note-structural-check.mjs';
 import { writeNote, patchNoteBody } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 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 { TICKET_KEY_PATTERN } from './cli.mjs';
@@ -72,6 +73,9 @@ export async function runNoteAdd(cmdArgs, {
   writeNoteFn = writeNote,
   readCliTokenFn = readCliToken,
   pushNoteFn = pushNote,
+  enqueueNoteFn = enqueueNote,
+  isRetryableFailureFn = isRetryableFailure,
+  maybeAutoFlushFn = maybeAutoFlush,
   incrementDraftKeptFn = incrementDraftKept,
   incrementDraftDeletedFn = incrementDraftDeleted,
   listAttachmentsFn = defaultListAttachments,
@@ -131,12 +135,15 @@ export async function runNoteAdd(cmdArgs, {
 
   const cliToken = readCliTokenFn(configDir);
   if (cliToken) {
+    const warn = (s) => stream.write(s);
     // Field names match PushRequest's validation rules (external_id, tickets) —
     // the backend wire contract, not the local vault's internal camelCase shape.
-    await pushNoteFn(
-      { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body },
-      { cliToken, configDir, warn: (s) => stream.write(s) },
-    );
+    const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body };
+    const result = await pushNoteFn(payload, { cliToken, configDir, warn });
+    if (isRetryableFailureFn(result)) {
+      enqueueNoteFn(payload, { cliToken, configDir, warn });
+    }
+    await maybeAutoFlushFn({ cliToken, configDir });
   }
 
   return { written: true };

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

@@ -12,6 +12,7 @@ import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { listNotes } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 import { pullNotes } from './recall-sync.mjs';
+import { maybeAutoFlush, flushQueue, readQueue } from './recall-queue.mjs';
 import { styleRecallResults } from './styled-assembler.mjs';
 
 /**
@@ -26,6 +27,7 @@ export async function runRecall(cmdArgs, {
   listNotesFn = listNotes,
   readCliTokenFn = readCliToken,
   pullNotesFn = pullNotes,
+  maybeAutoFlushFn = maybeAutoFlush,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
     showUpgradePrompt('pro', 'ticketlens recall', { stream: errorStream });
@@ -45,6 +47,7 @@ export async function runRecall(cmdArgs, {
       configDir,
       ...(cmdArgs.includes('--no-cache') && { ttlMs: 0 }),
     });
+    await maybeAutoFlushFn({ cliToken, configDir });
   }
 
   const filter = TICKET_KEY_PATTERN.test(arg) ? { ticketKey: arg } : { query: arg };
@@ -55,3 +58,41 @@ export async function runRecall(cmdArgs, {
   stream.write(styleRecallResults(results, { styled, full }) + '\n');
   return { ok: true };
 }
+
+/**
+ * Implements `tl recall sync` — manually flushes the local retry queue
+ * (notes whose team push previously failed for a transient reason). Unlike
+ * the auto-flush attempted from `runRecall`/`note add`, this is an explicit
+ * user action, so failures are reported visibly rather than staying silent.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runRecallSync(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  isLicensedFn = isLicensed,
+  readCliTokenFn = readCliToken,
+  readQueueFn = readQueue,
+  flushQueueFn = flushQueue,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens recall', { stream });
+    return { ok: false };
+  }
+
+  const cliToken = readCliTokenFn(configDir);
+  if (!cliToken) {
+    stream.write('Not logged in — run `ticketlens login` first.\n');
+    return { ok: false };
+  }
+
+  if (readQueueFn(configDir).length === 0) {
+    stream.write('Nothing to sync.\n');
+    return { ok: true };
+  }
+
+  const { flushed, remaining } = await flushQueueFn({ cliToken, configDir, warn: (s) => stream.write(s) });
+  stream.write(`Synced ${flushed} note(s). ${remaining} still pending.\n`);
+  return { ok: true };
+}

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

@@ -0,0 +1,227 @@
+/**
+ * Local retry queue for Recall notes whose push to the team backend failed
+ * for a transient reason (network error, timeout, or 5xx). A note is never
+ * lost — it's already safe in the local vault (recall-vault.mjs) before this
+ * module ever sees it; this only tracks the separate, best-effort intent to
+ * also sync it to the team.
+ *
+ * Retry classification happens once, at the moment the original push fails
+ * (isRetryableFailure) — 401/403/other-4xx are deliberately excluded: a
+ * stale session or a doomed payload will never succeed by retrying, and
+ * pushNote already warns the user about those synchronously.
+ *
+ * Growth is bounded two independent ways: a hard cap on entry count, and an
+ * age-based expiry keyed off firstQueuedAt (not failedAt, which refreshes on
+ * every retry attempt and would otherwise let a perpetually-failing entry
+ * live forever).
+ *
+ * enqueueNote/flushQueue do read-modify-write on the queue file with no file
+ * lock — same tradeoff already accepted by recall-pull-state.json and
+ * recall-entitlement-state.json in recall-sync.mjs. Two concurrent CLI
+ * invocations racing this file can lose one writer's update. Bounded,
+ * accepted risk: this queue is a retry-intent cache, not the source of truth
+ * (the note itself is already safe in the vault before it ever reaches here)
+ * — not worth a lock for a low-frequency, single-user CLI tool.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { writeFileAtomically } from './recall-vault.mjs';
+import { pushNote, hashToken } from './recall-sync.mjs';
+
+const QUEUE_FILE = 'recall-pending.json';
+const FLUSH_STATE_FILE = 'recall-flush-state.json';
+
+export const MAX_QUEUE_SIZE = 200;
+export const MAX_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const AUTO_FLUSH_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+
+function queuePath(configDir) {
+  return path.join(configDir, QUEUE_FILE);
+}
+
+function flushStatePath(configDir) {
+  return path.join(configDir, FLUSH_STATE_FILE);
+}
+
+/**
+ * @param {string} configDir
+ * @returns {Array<{id: string, notePayload: object, tokenHash: string, firstQueuedAt: string, failedAt: string, attempts: number}>}
+ */
+export function readQueue(configDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(queuePath(configDir), 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(configDir, entries) {
+  writeFileAtomically(queuePath(configDir), JSON.stringify(entries));
+}
+
+function purgeExpired(entries, now) {
+  return entries.filter(entry => now - new Date(entry.firstQueuedAt).getTime() <= MAX_ENTRY_AGE_MS);
+}
+
+/**
+ * Decides whether a failed push is worth retrying later. Network errors and
+ * timeouts (pushNote returns no `status` for these) and 5xx responses are
+ * transient. 401 (session expired), 403 (not entitled / no team), and any
+ * other 4xx (e.g. a validation failure) are not — retrying cannot fix them
+ * without the user acting, or would just retry a payload that will never be
+ * accepted.
+ *
+ * @param {{ ok: boolean, status?: number }} result
+ * @returns {boolean}
+ */
+export function isRetryableFailure(result) {
+  return !result.ok && (result.status === undefined || result.status >= 500);
+}
+
+/**
+ * Queues a note for later retry after a transient push failure. Purges
+ * expired entries first, then evicts the oldest entry (with a single warn)
+ * if appending would exceed MAX_QUEUE_SIZE.
+ *
+ * @param {object}   notePayload - exact wire payload passed to pushNote
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.warn]
+ */
+export function enqueueNote(notePayload, {
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => Date.now(),
+  warn = (s) => process.stderr.write(s),
+} = {}) {
+  const nowMs = now();
+  let entries = purgeExpired(readQueue(configDir), nowMs);
+
+  if (entries.length >= MAX_QUEUE_SIZE) {
+    entries = entries.slice(1);
+    warn('  Recall queue full — dropped the oldest queued note to make room.\n');
+  }
+
+  const nowIso = new Date(nowMs).toISOString();
+  entries.push({
+    id: notePayload.external_id,
+    notePayload,
+    tokenHash: hashToken(cliToken),
+    firstQueuedAt: nowIso,
+    failedAt: nowIso,
+    attempts: 0,
+  });
+
+  writeQueue(configDir, entries);
+}
+
+/**
+ * Attempts to push every queued entry belonging to the current account
+ * (matched by tokenHash). Entries queued under a different account are left
+ * untouched — never attempted, never evicted by this pass. Expired entries
+ * are purged first, regardless of tokenHash.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {Function} [opts.pushNoteFn]
+ * @param {Function} [opts.warn] - defaults to silent; callers doing a visible/manual sync should pass a real one
+ * @param {() => number} [opts.now]
+ * @returns {Promise<{ flushed: number, remaining: number }>}
+ */
+export async function flushQueue({
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  pushNoteFn = pushNote,
+  isRetryableFailureFn = isRetryableFailure,
+  warn = () => {},
+  now = () => Date.now(),
+} = {}) {
+  const nowMs = now();
+  const currentHash = hashToken(cliToken);
+  const entries = purgeExpired(readQueue(configDir), nowMs);
+
+  let flushed = 0;
+  const remaining = [];
+  for (const entry of entries) {
+    if (entry.tokenHash !== currentHash) {
+      remaining.push(entry);
+      continue;
+    }
+
+    const result = await pushNoteFn(entry.notePayload, { cliToken, configDir, warn });
+    if (result.ok) {
+      flushed++;
+      continue;
+    }
+
+    // A retry can surface a DIFFERENT failure than the one that originally
+    // queued this entry (e.g. the session expired between enqueue and this
+    // attempt) — reclassify every time rather than trusting the original
+    // enqueue decision, so a now-unrecoverable entry is dropped immediately
+    // instead of silently retrying for up to MAX_ENTRY_AGE_MS.
+    if (!isRetryableFailureFn(result)) continue;
+
+    remaining.push({ ...entry, attempts: entry.attempts + 1, failedAt: new Date(nowMs).toISOString() });
+  }
+
+  writeQueue(configDir, remaining);
+  return { flushed, remaining: remaining.length };
+}
+
+function readLastFlushAttemptAt(configDir) {
+  try {
+    return JSON.parse(fs.readFileSync(flushStatePath(configDir), 'utf8')).lastAttemptAt ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLastFlushAttemptAt(configDir, isoTimestamp) {
+  try {
+    fs.writeFileSync(flushStatePath(configDir), JSON.stringify({ lastAttemptAt: isoTimestamp }), 'utf8');
+  } catch {
+    // Non-fatal — worst case the next command re-checks a moment sooner than the interval intends.
+  }
+}
+
+/**
+ * Time-gated background flush, attempted from the CLI's existing
+ * Recall-touching entry points (note add's push, recall's pull) rather than
+ * on every invocation — a no-op unless the queue is non-empty AND at least
+ * AUTO_FLUSH_INTERVAL_MS has passed since the last attempt. The attempt
+ * timestamp is recorded even on failure, so a down backend can't be hammered
+ * once per command within the window.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.flushQueueFn]
+ */
+export async function maybeAutoFlush({
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => Date.now(),
+  flushQueueFn = flushQueue,
+} = {}) {
+  if (readQueue(configDir).length === 0) return;
+
+  const lastAttemptAt = readLastFlushAttemptAt(configDir);
+  const nowMs = now();
+  if (lastAttemptAt && nowMs - new Date(lastAttemptAt).getTime() < AUTO_FLUSH_INTERVAL_MS) return;
+
+  try {
+    await flushQueueFn({ cliToken, configDir, now });
+  } catch {
+    // A down backend or a thrown network error must never crash the command
+    // that opportunistically triggered this background attempt.
+  } finally {
+    writeLastFlushAttemptAt(configDir, new Date(nowMs).toISOString());
+  }
+}

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

@@ -56,7 +56,7 @@ function entitlementCachePath(configDir) {
 // switch (e.g. login as someone else) so a stale cache never suppresses a
 // different account's push. Found via Local Live Test: configDir alone is
 // not a valid cache key — cli-token.json can change without configDir changing.
-function hashToken(cliToken) {
+export function hashToken(cliToken) {
   return createHash('sha256').update(cliToken).digest('hex');
 }
 
@@ -107,7 +107,11 @@ export async function pushNote(note, {
   // flips the Recall grant — without this, the warning below repeats forever.
   const checkedAt = readEntitlementCheckedAt(configDir, cliToken);
   if (checkedAt && now() - new Date(checkedAt).getTime() < ttlMs) {
-    return { ok: false, skipped: true };
+    // status: 403 — this is a cached replay of the entitlement 403 below, not a
+    // fresh network outcome. Without it, isRetryableFailure's "no status means
+    // network error" rule misclassifies this as transient and queues a note
+    // that can never succeed until the owner grants entitlement.
+    return { ok: false, status: 403, skipped: true };
   }
 
   warnIfInsecure(apiBase(), warn);

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

@@ -49,7 +49,7 @@ function generateNoteId() {
   return `${Date.now()}-${randomBytes(3).toString('hex')}.md`;
 }
 
-function writeFileAtomically(filePath, contents) {
+export function writeFileAtomically(filePath, contents) {
   const tmpPath = `${filePath}.${process.pid}.tmp`;
   fs.writeFileSync(tmpPath, contents, 'utf8');
   fs.renameSync(tmpPath, filePath);