ticketlens 0.3.0 → 0.4.1

package/README.md

@@ -211,6 +211,53 @@ Flag validation provides actionable hints:
 
 ---
 
+### Compliance
+
+```bash
+ticketlens compliance <TICKET-KEY>                # Check ticket requirements against local diff [Pro/Free 3/mo]
+ticketlens compliance <TICKET-KEY> --profile=acme # Specify a profile
+ticketlens compliance <TICKET-KEY> --plain        # Plain markdown output
+```
+
+Runs the same compliance check as `ticketlens CNV1-2 --compliance` but as a dedicated subcommand — useful when you want to check compliance without fetching the full ticket brief. Free accounts get 3 checks per month; Pro is unlimited.
+
+---
+
+### Compliance Ledger
+
+```bash
+ticketlens ledger                             # View the local compliance audit ledger [Pro]
+ticketlens ledger --plain                     # Plain markdown output
+```
+
+Displays the append-only local ledger of all compliance checks run on this machine. Useful for SOC 2 / HIPAA audit trails. Requires a Pro license.
+
+---
+
+### Git Hook
+
+```bash
+ticketlens install-hooks                      # Install pre-push compliance gate [Pro]
+ticketlens install-hooks --uninstall          # Remove installed hooks
+```
+
+Installs a `pre-push` git hook that runs `ticketlens compliance` on every push. Blocks the push if compliance coverage falls below the configured threshold. Requires a Pro license.
+
+---
+
+### PR Description
+
+```bash
+ticketlens pr <TICKET-KEY>                    # Generate PR description from ticket [Pro]
+ticketlens pr <TICKET-KEY> --profile=acme    # Specify a profile
+ticketlens pr <TICKET-KEY> --plain           # Plain markdown output
+ticketlens pr <TICKET-KEY> | pbcopy          # Copy to clipboard
+```
+
+Generates a PR description template pre-filled with the ticket summary, acceptance criteria, and compliance coverage. Requires a Pro license.
+
+---
+
 ### Standup
 
 ```bash
@@ -295,12 +342,16 @@ Stores the schedule as a cron entry. Delivers your triage digest at the configur
 ```bash
 ticketlens login           # Open browser → authorize in Console → token saved automatically
 ticketlens login --manual  # Paste a token instead (CI/headless environments)
+ticketlens logout          # Revoke and remove the stored CLI token
+ticketlens sync            # Pull your latest tracker profiles from the Console
 ```
 
 `ticketlens login` opens the TicketLens Console in your default browser. Click **Authorize**, and the CLI receives your token via a one-shot localhost callback — no copy-pasting. Cancelling in the browser exits the CLI cleanly.
 
 Use `--manual` when there is no GUI (CI runners, SSH sessions, containers).
 
+`ticketlens sync` pulls any tracker profiles you have configured in the Console and writes them locally, keeping your CLI in sync with your team settings without re-running `init`.
+
 ---
 
 ### License
@@ -483,9 +534,21 @@ ticketlens schedule                           # Interactive wizard — set time,
 ticketlens schedule --stop                    # Cancel the scheduled digest [Pro]
 ticketlens schedule --status                  # Show current schedule [Pro]
 
+# ── Compliance ────────────────────────────────────────────────────────────────
+ticketlens compliance <TICKET-KEY>            # Check ticket requirements against local diff [Pro/Free 3/mo]
+ticketlens ledger                             # View local compliance audit ledger [Pro]
+ticketlens install-hooks                      # Install pre-push compliance gate [Pro]
+ticketlens install-hooks --uninstall          # Remove installed hooks [Pro]
+
+# ── PR Description ─────────────────────────────────────────────────────────────
+ticketlens pr <TICKET-KEY>                    # Generate PR description from ticket [Pro]
+ticketlens pr <TICKET-KEY> | pbcopy          # Copy to clipboard [Pro]
+
 # ── Login ─────────────────────────────────────────────────────────────────────
 ticketlens login                              # Browser flow — opens Console, token saved automatically
 ticketlens login --manual                     # Paste flow — for CI/headless environments
+ticketlens logout                             # Revoke and remove stored CLI token
+ticketlens sync                               # Pull tracker profiles from the Console
 
 # ── License and account ────────────────────────────────────────────────────────
 ticketlens license                            # Show license tier and status

package/bin/ticketlens.mjs

@@ -24,6 +24,7 @@ import {
   printProfilesHelp, printScheduleHelp,
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
+  printCollisionsHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
 import { readCliToken, saveCliToken, deleteCliToken } from '../skills/jtb/scripts/lib/cli-auth.mjs';
@@ -53,6 +54,7 @@ switch (command) {
     break;
 
   case 'collisions': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCollisionsHelp(); break; }
     const { runCollisions } = await import('../skills/jtb/scripts/lib/run-collisions.mjs');
     runCollisions(cmdArgs).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
@@ -127,6 +129,9 @@ switch (command) {
         process.stderr.write(`\n  ${s.red('✖')} Activation failed: ${result.error}\n\n`);
         process.exitCode = 1;
       }
+    }).catch(err => {
+      process.stderr.write(`\n  ${s.red('✖')} Activation error: ${err.message}\n\n`);
+      process.exitCode = 1;
     });
     break;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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.3.0 -->
+<!-- jtb-skill-version: 0.4.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.
@@ -249,6 +249,12 @@ Generates a structured handoff brief synthesised from the ticket's full comment
 
 Output is a concise markdown document, not a full TicketBrief. No plan mode — output is displayed and the workflow stops.
 
+### triage --push compliance enrichment (Pro)
+
+When `--push` is run by a Pro-licensed user, the local compliance ledger (written by `--compliance` runs) is read and merged into the snapshot before sending. Each ticket's `compliance_status` (`pass`/`gap`) and `compliance_coverage` (%) are included in the push payload. This feeds the **Compliance Analytics** dashboard in the Console (`/console/admin/compliance-analytics`), which shows gap-rate trends by project, ticket status, and week.
+
+Non-Pro users push with `compliance_status: unknown` — no data is lost, and the analytics page simply shows no compliance data for those snapshots.
+
 ### --plain / --styled
 
 Control output formatting:

package/skills/jtb/scripts/lib/brief-cache.mjs

@@ -47,7 +47,7 @@ export function readBriefCache(ticketKey, profileName, depth, configDir = DEFAUL
   }
 
   const age = Date.now() - new Date(data.fetchedAt).getTime();
-  if (age > ttlMs) {
+  if (isNaN(age) || age > ttlMs) {
     try { fs.unlinkSync(filePath); } catch { /* non-fatal */ }
     return null;
   }

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

@@ -106,6 +106,10 @@ export function parseCommand(args) {
     return { command: 'update-skill', args: args.slice(1) };
   }
 
+  if (first === 'collisions') {
+    return { command: 'collisions', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

package/skills/jtb/scripts/lib/error-classifier.mjs

@@ -71,7 +71,7 @@ export function classifyError(err, { baseUrl, profileName } = {}) {
   if (status === 401) {
     return {
       message: `Authentication failed for ${profile}`,
-      hint: 'Your credentials may have expired. Check your API token or PAT in ~/.ticketlens/credentials.json.',
+      hint: 'Your credentials may have expired. Check your API token or PAT in your TicketLens credentials file.',
     };
   }
 

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

@@ -644,6 +644,37 @@ export function printUpdateSkillHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printCollisionsHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('collisions')} ${s.dim('[--json] [--plain]')}`,
+    '',
+    `  Show branches where your changed files overlap with a teammate's.`,
+    `  Reads the most recent snapshot pushed by you and each teammate (within 7 days).`,
+    `  Requires a ${s.bold('Team')} license and at least one teammate in your group.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--json')}     Output raw JSON array of collision objects`,
+    `    ${s.brand('--plain')}    Plain text output ${s.dim('(no ANSI colour)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}  Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens collisions`,
+    `    ${s.dim('$')} ticketlens collisions --json`,
+    `    ${s.dim('$')} ticketlens collisions --plain`,
+    '',
+    `  ${s.bold('NOTES')}`,
+    '',
+    `    Branch data is captured automatically when you run ${s.brand('ticketlens triage --push')}.`,
+    `    Snapshots older than 7 days are ignored.`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printStandupHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/jira-client.mjs

@@ -75,7 +75,9 @@ export async function fetchCurrentUser(opts = {}) {
   const response = await fetcher(url, fetchOpts);
 
   if (!response.ok) {
-    throw new Error(`Jira API error ${response.status} (${response.statusText}) fetching current user`);
+    const err = new Error(`Jira API error ${response.status} fetching current user`);
+    err.status = response.status;
+    throw err;
   }
 
   const raw = await response.json();
@@ -98,7 +100,9 @@ export async function fetchStatuses(opts = {}) {
   const response = await fetcher(url, fetchOpts);
 
   if (!response.ok) {
-    throw new Error(`Jira API error ${response.status} (${response.statusText}) fetching statuses`);
+    const err = new Error(`Jira API error ${response.status} fetching statuses`);
+    err.status = response.status;
+    throw err;
   }
 
   const raw = await response.json();
@@ -121,7 +125,7 @@ export async function searchTickets(jql, opts = {}) {
   if (!response.ok) {
     let detail = '';
     try { const body = await response.json(); detail = (body.errorMessages || []).join('; '); } catch {}
-    const err = new Error(`Jira API error ${response.status} (${response.statusText}) searching tickets${detail ? ': ' + detail : ''}`);
+    const err = new Error(`Jira API error ${response.status} searching tickets`);
     err.status = response.status;
     err.detail = detail;
     throw err;
@@ -159,7 +163,9 @@ export async function fetchTicket(ticketKey, opts = {}) {
   const response = await fetcher(url, fetchOpts);
 
   if (!response.ok) {
-    throw new Error(`Jira API error ${response.status} (${response.statusText}) fetching ${ticketKey}`);
+    const err = new Error(`Jira API error ${response.status} fetching ${ticketKey}`);
+    err.status = response.status;
+    throw err;
   }
 
   const raw = await response.json();

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

@@ -47,7 +47,8 @@ export function readLedger({ configDir = DEFAULT_CONFIG_DIR, fsModule = _fs, sin
   return raw
     .split('\n')
     .filter(line => line.trim().length > 0)
-    .map(line => JSON.parse(line))
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(record => record !== null)
     .filter(record => sinceMs === null || new Date(record.ts).getTime() >= sinceMs);
 }
 

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

@@ -5,6 +5,9 @@ import crypto from 'node:crypto';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { createStyler } from './ansi.mjs';
 
+export // 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.
+const LICENSE_HMAC_SALT = 'tl-lic-v1';
 export const LICENSE_TIERS = { free: 0, pro: 1, team: 2 };
 const LICENSE_FILE = 'license.json';
 const REVALIDATION_DAYS = 7;   // attempt background revalidation after this many days
@@ -24,9 +27,14 @@ export function readLicense(configDir = DEFAULT_CONFIG_DIR) {
     const { sig, ...payload } = data;
     // Legacy unsigned files are trusted; will be re-signed on next write
     if (!sig) return payload;
-    const expected = crypto.createHmac('sha256', payload.key || '')
+    const sigKey = `${LICENSE_HMAC_SALT}:${payload.key || ''}`;
+    const expected = crypto.createHmac('sha256', sigKey)
       .update(JSON.stringify(payload)).digest('hex');
-    return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)) ? payload : null;
+    const sigBuf = Buffer.from(sig, 'hex');
+    const expBuf = Buffer.from(expected, 'hex');
+    // timingSafeEqual requires equal-length buffers; unequal lengths mean tampered sig
+    if (sigBuf.length !== expBuf.length) return null;
+    return crypto.timingSafeEqual(sigBuf, expBuf) ? payload : null;
   } catch {
     return null;
   }
@@ -36,7 +44,8 @@ export function writeLicense(data, configDir = DEFAULT_CONFIG_DIR) {
   fs.mkdirSync(configDir, { recursive: true });
   const filePath = path.join(configDir, LICENSE_FILE);
   const { sig: _, ...payload } = data; // strip any existing sig before re-signing
-  const mac = crypto.createHmac('sha256', payload.key || '')
+  const sigKey = `${LICENSE_HMAC_SALT}:${payload.key || ''}`;
+  const mac = crypto.createHmac('sha256', sigKey)
     .update(JSON.stringify(payload)).digest('hex');
   fs.writeFileSync(filePath, JSON.stringify({ ...payload, sig: mac }), 'utf8');
   fs.chmodSync(filePath, 0o600);

package/skills/jtb/scripts/lib/profile-resolver.mjs

@@ -3,7 +3,7 @@
  * Resolution order: --profile flag → ticket prefix match → default profile → env vars
  */
 
-import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, chmodSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
@@ -51,8 +51,7 @@ export function saveDefault(name, configDir = DEFAULT_CONFIG_DIR) {
   const profilesPath = join(configDir, 'profiles.json');
   const config = loadProfiles(configDir) || { profiles: {} };
   config.default = name;
-  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  chmodSync(profilesPath, 0o600);
+  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   invalidateProfilesCache(configDir);
 }
 
@@ -61,14 +60,12 @@ export function saveProfile(name, profileData, credData, configDir = DEFAULT_CON
   const profilesPath = join(configDir, 'profiles.json');
   const config = loadProfiles(configDir) || { profiles: {} };
   config.profiles[name] = profileData;
-  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  chmodSync(profilesPath, 0o600);
+  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   if (credData && Object.keys(credData).length > 0) {
     const credPath = join(configDir, 'credentials.json');
     const creds = loadCredentials(configDir);
     creds[name] = credData;
-    writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', 'utf8');
-    chmodSync(credPath, 0o600);
+    writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   }
   invalidateProfilesCache(configDir);
 }
@@ -81,8 +78,7 @@ export function deleteProfile(name, configDir = DEFAULT_CONFIG_DIR) {
   delete config.profiles[name];
   if (config.default === name) delete config.default;
 
-  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  chmodSync(profilesPath, 0o600);
+  writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
 
   // Remove credentials entry
   const credPath = join(configDir, 'credentials.json');
@@ -90,8 +86,7 @@ export function deleteProfile(name, configDir = DEFAULT_CONFIG_DIR) {
     const creds = loadCredentials(configDir);
     if (creds[name]) {
       delete creds[name];
-      writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', 'utf8');
-      chmodSync(credPath, 0o600);
+      writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
     }
   }
 
@@ -103,9 +98,13 @@ export function loadProfiles(configDir = DEFAULT_CONFIG_DIR) {
   if (_profilesCache.has(configDir)) return _profilesCache.get(configDir);
   const profilesPath = join(configDir, 'profiles.json');
   if (!existsSync(profilesPath)) return null;
-  const data = JSON.parse(readFileSync(profilesPath, 'utf8'));
-  _profilesCache.set(configDir, data);
-  return data;
+  try {
+    const data = JSON.parse(readFileSync(profilesPath, 'utf8'));
+    _profilesCache.set(configDir, data);
+    return data;
+  } catch {
+    return null;
+  }
 }
 
 export function loadCredentials(configDir = DEFAULT_CONFIG_DIR) {
@@ -115,9 +114,14 @@ export function loadCredentials(configDir = DEFAULT_CONFIG_DIR) {
     _credentialsCache.set(configDir, {});
     return {};
   }
-  const data = JSON.parse(readFileSync(credPath, 'utf8'));
-  _credentialsCache.set(configDir, data);
-  return data;
+  try {
+    const data = JSON.parse(readFileSync(credPath, 'utf8'));
+    _credentialsCache.set(configDir, data);
+    return data;
+  } catch {
+    _credentialsCache.set(configDir, {});
+    return {};
+  }
 }
 
 export function saveCredentialKey(key, value, configDir = DEFAULT_CONFIG_DIR) {
@@ -129,8 +133,7 @@ export function saveCredentialKey(key, value, configDir = DEFAULT_CONFIG_DIR) {
   } else {
     creds[key] = value;
   }
-  writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', 'utf8');
-  chmodSync(credPath, 0o600);
+  writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   invalidateProfilesCache(configDir);
 }
 

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

@@ -34,6 +34,7 @@ export async function runCollisions(args = [], opts = {}) {
   try {
     const res = await fetcher(`${apiBase()}${COLLISIONS_PATH}`, {
       headers: { Authorization: `Bearer ${licenseKey}` },
+      signal: AbortSignal.timeout(15_000),
     });
 
     if (!res.ok) {

package/skills/jtb/scripts/lib/triage-history.mjs

@@ -5,12 +5,10 @@
  */
 
 import * as defaultFs from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-const DEFAULT_CONFIG_DIR = join(
-  process.env.HOME ?? process.env.USERPROFILE ?? '',
-  '.ticketlens'
-);
+const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
 
 const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
 

package/skills/jtb/scripts/lib/triage-push.mjs

@@ -3,6 +3,10 @@
  * All errors are caught — push failure must never break triage output.
  */
 
+import { readLedger } from './ledger.mjs';
+import { isLicensed } from './license.mjs';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+
 const PUSH_PATH = '/v1/triage/push';
 // Local dev: http://ticketlens.test — production override via TICKETLENS_API_URL env var
 const DEFAULT_API_BASE = 'http://ticketlens.test';
@@ -12,10 +16,15 @@ function apiBase() {
 }
 
 // Derive console queue URL from API base:
-//   http://ticketlens.test          → http://ticketlens.test/console/queue
+//   http://api.ticketlens.test      → http://ticketlens.test/console/queue
 //   https://api.ticketlens.com      → https://app.ticketlens.com/console/queue
-function queueUrl(base) {
-  return base.replace(/^(https?:\/\/)api\./, '$1app.') + '/console/queue';
+export function queueUrl(base) {
+  const noApi = base.replace(/^(https?:\/\/)api\./, '$1');
+  // Production: ticketlens.com → app.ticketlens.com
+  const console = /ticketlens\.com/.test(noApi)
+    ? noApi.replace('://', '://app.')
+    : noApi;
+  return console + '/console/queue';
 }
 
 function buildTicketPayload(scored, rawMap, baseUrl) {
@@ -59,16 +68,43 @@ export async function pushTriageSnapshot({
   gitBranches,
   fetcher = globalThis.fetch,
   print = (s) => process.stdout.write(s),
+  readLedgerFn = readLedger,
+  isLicensedFn = isLicensed,
+  configDir = DEFAULT_CONFIG_DIR,
 } = {}) {
   if (!licenseKey) {
     print('✗ --push requires an active Team license (ticketlens activate <key>)\n');
     return { ok: false };
   }
 
+  let tickets = sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl));
+
+  if (isLicensedFn('pro', configDir)) {
+    try {
+      const entries = readLedgerFn({ configDir });
+      const latestByKey = new Map();
+      for (const entry of entries) {
+        const prev = latestByKey.get(entry.ticketKey);
+        if (!prev || entry.ts > prev.ts) latestByKey.set(entry.ticketKey, entry);
+      }
+      tickets = tickets.map(t => {
+        const entry = latestByKey.get(t.key);
+        if (!entry) return t;
+        return {
+          ...t,
+          compliance_coverage: entry.coverage ?? null,
+          compliance_status: (entry.missing?.length ?? 0) === 0 ? 'pass' : 'gap',
+        };
+      });
+    } catch {
+      // non-fatal — ledger errors must not break triage push
+    }
+  }
+
   const payload = {
     profile: String(profile ?? 'default').slice(0, 100),
     captured_at: capturedAt ?? new Date().toISOString(),
-    tickets: sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl)),
+    tickets,
     ...(gitBranches != null && { git_branches: gitBranches }),
   };
 
@@ -80,6 +116,7 @@ export async function pushTriageSnapshot({
         'Authorization': `Bearer ${licenseKey}`,
       },
       body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(15_000),
     });
 
     if (res.ok) {

package/skills/jtb/scripts/lib/triage-share.mjs

@@ -67,6 +67,7 @@ export async function shareTriageSnapshot({
         'Authorization': `Bearer ${licenseKey}`,
       },
       body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(15_000),
     });
 
     if (res.ok) {