ticketlens 0.1.23 → 0.1.24

package/README.md

@@ -97,10 +97,11 @@ ticketlens CNV1-2 --no-cache       # Bypass cache, re-fetch from Jira
 ticketlens CNV1-2 --no-attachments # Skip attachment download and Confluence page fetching
 ticketlens CNV1-2 --check          # Append local VCS diff + Claude Code review instructions
 ticketlens CNV1-2 --compliance     # Check ticket requirements against local diff [Pro/Free 3/mo]
-ticketlens CNV1-2 --summarize      # AI summary via your own API key (BYOK) [Pro]
-ticketlens CNV1-2 --summarize --cloud  # AI summary routed through TicketLens API [Pro]
-ticketlens CNV1-2 --handoff        # AI handoff brief from comment thread (BYOK) [Pro]
-ticketlens CNV1-2 --handoff --cloud    # AI handoff brief via TicketLens API [Pro]
+ticketlens CNV1-2 --summarize                  # AI summary via your own API key (BYOK) [Pro]
+ticketlens CNV1-2 --summarize --provider=groq  # Force a specific AI provider [Pro]
+ticketlens CNV1-2 --summarize --cloud          # AI summary routed through TicketLens API [Pro]
+ticketlens CNV1-2 --handoff                    # AI handoff brief from comment thread (BYOK) [Pro]
+ticketlens CNV1-2 --handoff --cloud            # AI handoff brief via TicketLens API [Pro]
 ```
 
 | `--depth` | Scope |
@@ -328,6 +329,7 @@ ticketlens init                               # Guided wizard (recommended)
 ticketlens switch                             # Switch between configured profiles
 ticketlens config                             # Edit the active profile
 ticketlens config --profile=acme             # Edit a specific profile
+ticketlens config set aiProvider groq        # Set default AI provider (groq|openai|anthropic)
 ticketlens profiles                           # List all configured profiles
 ticketlens ls                                 # Alias for profiles
 ticketlens profiles --plain                   # Tab-separated (scripts / pipes)
@@ -347,10 +349,11 @@ ticketlens CNV1-2 --no-attachments           # Skip attachment download entirely
 ticketlens CNV1-2 --no-cache                 # Skip brief cache + force re-download
 ticketlens CNV1-2 --check                    # Append local VCS diff + Claude Code review instructions
 ticketlens CNV1-2 --compliance               # Check ticket requirements against local diff [Pro/Free 3/mo]
-ticketlens CNV1-2 --summarize                # AI summary via your own API key (BYOK) [Pro]
-ticketlens CNV1-2 --summarize --cloud        # AI summary via TicketLens API [Pro]
-ticketlens CNV1-2 --handoff                  # AI handoff brief from comment thread (BYOK) [Pro]
-ticketlens CNV1-2 --handoff --cloud          # AI handoff brief via TicketLens API [Pro]
+ticketlens CNV1-2 --summarize                   # AI summary via your own API key (BYOK) [Pro]
+ticketlens CNV1-2 --summarize --provider=groq   # Force Groq (Llama 3.1, free tier) [Pro]
+ticketlens CNV1-2 --summarize --cloud           # AI summary via TicketLens API [Pro]
+ticketlens CNV1-2 --handoff                     # AI handoff brief from comment thread (BYOK) [Pro]
+ticketlens CNV1-2 --handoff --cloud             # AI handoff brief via TicketLens API [Pro]
 ticketlens CNV1-2 --depth=2 --profile=acme --plain   # Combine flags freely
 
 # Pipe plain output to clipboard, LLM, or file
@@ -469,7 +472,28 @@ ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 - **Open questions** — decisions not yet made
 - **Recommendation** — where to start
 
-Add `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` to `~/.ticketlens/credentials.json` for BYOK, or use `--cloud` to route through the TicketLens API.
+Add one of the following to `~/.ticketlens/credentials.json` for BYOK, or use `--cloud` to route through the TicketLens API:
+
+| Key | Provider | Cost |
+|---|---|---|
+| `anthropicApiKey` | Anthropic (Claude Haiku) | Paid |
+| `openaiApiKey` | OpenAI (GPT-4o mini) | Paid |
+| `groqApiKey` | Groq (Llama 3.1 8B) | **Free tier** — [console.groq.com](https://console.groq.com) |
+
+**Selecting a provider:** By default, the first available key is used (Anthropic → OpenAI → Groq). To set a persistent default:
+
+```bash
+ticketlens config set aiProvider groq        # always use Groq
+ticketlens config set aiProvider openai      # always use OpenAI
+ticketlens config set aiProvider anthropic   # always use Anthropic
+```
+
+Override per-command with `--provider=`:
+
+```bash
+ticketlens CNV1-2 --summarize --provider=groq
+ticketlens CNV1-2 --handoff --provider=openai
+```
 
 <div align="center">
   <img src="docs/demos/pro-triage.gif" alt="ticketlens triage --stale=3 demo" width="700" />

package/bin/ticketlens.mjs

@@ -15,7 +15,7 @@ import { run as runInit } from '../skills/jtb/scripts/lib/init-wizard.mjs';
 import { runSwitch } from '../skills/jtb/scripts/lib/profile-switcher.mjs';
 import { run as runConfig } from '../skills/jtb/scripts/lib/config-wizard.mjs';
 import { activateLicense, checkLicense, revalidateIfStale, isLicensed, showUpgradePrompt, readLicense } from '../skills/jtb/scripts/lib/license.mjs';
-import { deleteProfile, loadProfiles } from '../skills/jtb/scripts/lib/profile-resolver.mjs';
+import { deleteProfile, loadProfiles, saveCredentialKey } from '../skills/jtb/scripts/lib/profile-resolver.mjs';
 import { run as runCache } from '../skills/jtb/scripts/lib/cache-manager.mjs';
 import {
   printHelp, printProfiles,
@@ -70,6 +70,27 @@ switch (command) {
 
   case 'config': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printConfigHelp(); break; }
+
+    if (cmdArgs[0] === 'set' && cmdArgs[1] === 'aiProvider') {
+      const s = createStyler({ isTTY: process.stdout.isTTY });
+      const value = cmdArgs[2];
+      if (!value) {
+        process.stderr.write(`${s.red('✖')} Missing value.\n  Usage: ticketlens config set aiProvider <anthropic|openai|groq>\n`);
+        process.exitCode = 1;
+        break;
+      }
+      const validProviders = ['anthropic', 'openai', 'groq'];
+      if (!validProviders.includes(value)) {
+        process.stderr.write(`${s.red('✖')} Unknown provider "${value}". Valid: ${validProviders.join(', ')}\n`);
+        process.exitCode = 1;
+        break;
+      }
+      saveCredentialKey('aiProvider', value);
+      process.stdout.write(`  ${s.green('✔')} AI provider set to ${s.bold(s.cyan(value))}\n`);
+      process.stdout.write(`  ${s.dim('Applied when running --summarize or --handoff without --provider=')}\n`);
+      break;
+    }
+
     const profileArg = cmdArgs.find(a => a.startsWith('--profile='));
     const profileName = profileArg ? profileArg.split('=')[1] : undefined;
     runConfig({ profileName }).catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "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/scripts/fetch-ticket.mjs

@@ -98,6 +98,12 @@ function saveCloudConsent(configDir, profileName) {
   } catch { /* non-fatal */ }
 }
 
+function resolveAiProvider(args, credentials) {
+  const flagArg = args.find(a => a.startsWith('--provider='));
+  if (flagArg) return flagArg.split('=')[1];
+  return credentials?.aiProvider ?? undefined;
+}
+
 /**
  * Apply --summarize to a brief string.
  * Returns the modified brief, or null if the caller should exit (license gate / consent refused).
@@ -135,7 +141,8 @@ async function applySummarize(brief, args, opts, configDir, conn, licensedFn, up
     });
     const credentials = opts.credentials ?? loadCredentials(configDir);
     const licenseKey = readLicense(configDir)?.key;
-    const summary = await summarizerFn({ brief, mode, credentials, licenseKey });
+    const provider = opts.provider ?? resolveAiProvider(args, credentials);
+    const summary = await summarizerFn({ brief, mode, credentials, licenseKey, provider });
     const divider = '─'.repeat(60);
     return brief + `\n\n${divider}\n─── AI Summary ${'─'.repeat(45)}\n${summary}\n${divider}\n`;
   } catch (err) {
@@ -166,8 +173,9 @@ async function applyHandoff(ticket, args, opts, configDir, licensedFn, upgradeFn
     });
     const credentials = opts.credentials ?? loadCredentials(configDir);
     const licenseKey = readLicense(configDir)?.key;
+    const provider = opts.provider ?? resolveAiProvider(args, credentials);
     const input = buildHandoffInput(ticket);
-    const body = await summarizerFn({ brief: input, mode, credentials, licenseKey, prompt: HANDOFF_PROMPT, maxTokens: 512 });
+    const body = await summarizerFn({ brief: input, mode, credentials, licenseKey, prompt: HANDOFF_PROMPT, maxTokens: 512, provider });
     return `## Handoff Brief — ${ticket.key}\n\n${body}\n`;
   } catch (err) {
     const onErrorFn = opts.onError ?? ((msg) => process.stderr.write(msg + '\n'));
@@ -815,7 +823,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   const validatedArgs = await handleUnknownFlags(
     args,
-    ['--help', '-h', '--plain', '--styled', '--no-attachments', '--no-cache', '--profile=', '--depth=', '--check', '--summarize', '--cloud', '--compliance', '--budget=', '--handoff'],
+    ['--help', '-h', '--plain', '--styled', '--no-attachments', '--no-cache', '--profile=', '--depth=', '--check', '--summarize', '--cloud', '--compliance', '--budget=', '--handoff', '--provider='],
     { hints: ['--stale=', '--status=', '--static'] } // triage-only flags — shown as hints, not applied
   );
   if (validatedArgs === null) { process.exitCode = 1; return; }

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

@@ -98,6 +98,11 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('Or use env vars:')} JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN`,
     `    ${s.dim('               ')} TICKETLENS_API_URL  ${s.dim('(override API host for local dev)')}`,
     '',
+    `    ${s.dim('BYOK AI keys')}  ${s.dim('(add to credentials.json):')}`,
+    `    ${s.dim('               ')} anthropicApiKey  ${s.dim('→ Claude (paid)')}`,
+    `    ${s.dim('               ')} openaiApiKey     ${s.dim('→ GPT-4o mini (paid)')}`,
+    `    ${s.dim('               ')} groqApiKey       ${s.dim('→ Llama 3.1 (free tier — console.groq.com)')}`,
+    '',
     '',
   ];
 
@@ -131,6 +136,7 @@ export function printFetchHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
     `    ${s.brand('--handoff')}          AI handoff brief from comment thread ${s.dim('(BYOK or --cloud) [Pro]')}`,
     `    ${s.brand('--cloud')}            Route AI request through TicketLens API ${s.dim('[Pro]')}`,
+    `    ${s.brand('--provider')}=${s.dim('NAME')}     Force AI provider ${s.dim('(anthropic|openai|groq)')}`,
     `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
@@ -140,6 +146,7 @@ export function printFetchHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens PROJ-123 --profile=acme --depth=2`,
     `    ${s.dim('$')} ticketlens PROJ-123 --handoff`,
     `    ${s.dim('$')} ticketlens PROJ-123 --handoff --cloud`,
+    `    ${s.dim('$')} ticketlens PROJ-123 --summarize --provider=groq`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -484,10 +491,21 @@ export function printConfigHelp({ stream = process.stdout } = {}) {
   const lines = [
     '',
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('config')} ${s.dim('[--profile=NAME]')}`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('config set aiProvider')} ${s.dim('<anthropic|openai|groq>')}`,
     '',
     `  Edit settings for an existing profile using an interactive wizard.`,
     `  Without ${s.cyan('--profile')}, edits the currently active profile.`,
     '',
+    `  Use ${s.cyan('config set aiProvider')} to set a persistent default AI provider`,
+    `  for ${s.cyan('--summarize')} and ${s.cyan('--handoff')}. Overridden per-command with ${s.cyan('--provider=')}.`,
+    '',
+    `  ${s.bold('SUBCOMMANDS')}`,
+    '',
+    `    ${s.brand('set aiProvider')} ${s.dim('<PROVIDER>')}   Persist default AI provider`,
+    `                            ${s.dim('anthropic')} = Claude Haiku ${s.dim('(paid)')}`,
+    `                            ${s.dim('openai')}    = GPT-4o mini ${s.dim('(paid)')}`,
+    `                            ${s.dim('groq')}      = Llama 3.1 ${s.dim('(free tier)')}`,
+    '',
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--profile')}=${s.dim('NAME')}   Profile to configure`,
@@ -497,7 +515,8 @@ export function printConfigHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.dim('$')} ticketlens config`,
     `    ${s.dim('$')} ticketlens config --profile=work`,
-    `    ${s.dim('$')} ticketlens config --profile=acme`,
+    `    ${s.dim('$')} ticketlens config set aiProvider groq`,
+    `    ${s.dim('$')} ticketlens config set aiProvider anthropic`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

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

@@ -120,6 +120,20 @@ export function loadCredentials(configDir = DEFAULT_CONFIG_DIR) {
   return data;
 }
 
+export function saveCredentialKey(key, value, configDir = DEFAULT_CONFIG_DIR) {
+  mkdirSync(configDir, { recursive: true });
+  const credPath = join(configDir, 'credentials.json');
+  const creds = loadCredentials(configDir);
+  if (value === null || value === undefined) {
+    delete creds[key];
+  } else {
+    creds[key] = value;
+  }
+  writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', 'utf8');
+  chmodSync(credPath, 0o600);
+  invalidateProfilesCache(configDir);
+}
+
 export function expandTilde(p) {
   if (p.startsWith('~/')) return join(homedir(), p.slice(2));
   if (p === '~') return homedir();

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

@@ -1,5 +1,6 @@
 const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
 const OPENAI_URL = 'https://api.openai.com/v1/chat/completions';
+const GROQ_URL = 'https://api.groq.com/openai/v1/chat/completions';
 const CLOUD_URL = 'https://api.ticketlens.dev/v1/summarize';
 const DEFAULT_PROMPT = 'Summarize this Jira ticket in 3 sentences. Focus on what matters most for implementation. Be concrete.\n\n';
 const DEFAULT_MAX_TOKENS = 256;
@@ -9,34 +10,45 @@ const DEFAULT_MAX_TOKENS = 256;
  * @param {object} opts
  * @param {string} opts.brief - Markdown brief text
  * @param {'byok'|'cloud'} opts.mode
- * @param {object} [opts.credentials] - { anthropicApiKey?, openaiApiKey? }
+ * @param {object} [opts.credentials] - { anthropicApiKey?, openaiApiKey?, groqApiKey? }
  * @param {string} [opts.licenseKey] - Required for cloud mode
  * @param {Function} [opts.fetcher] - Injectable for tests (defaults to globalThis.fetch)
  * @param {number} [opts.timeoutMs]
  * @returns {Promise<string>} Summary text
  */
-export async function summarize({ brief, mode, credentials = null, licenseKey = null, fetcher = globalThis.fetch, timeoutMs = 30_000, prompt, maxTokens }) {
+export async function summarize({ brief, mode, credentials = null, licenseKey = null, fetcher = globalThis.fetch, timeoutMs = 30_000, prompt, maxTokens, provider }) {
   const effectivePrompt = prompt ?? DEFAULT_PROMPT;
   const effectiveMaxTokens = maxTokens ?? DEFAULT_MAX_TOKENS;
   if (mode === 'byok') {
-    return byok({ brief, credentials, fetcher, timeoutMs, prompt: effectivePrompt, maxTokens: effectiveMaxTokens });
+    return byok({ brief, credentials, fetcher, timeoutMs, prompt: effectivePrompt, maxTokens: effectiveMaxTokens, provider });
   }
   return cloud({ brief, licenseKey, fetcher, timeoutMs });
 }
 
-async function byok({ brief, credentials, fetcher, timeoutMs, prompt, maxTokens }) {
+async function byok({ brief, credentials, fetcher, timeoutMs, prompt, maxTokens, provider }) {
   const anthropicKey = credentials?.anthropicApiKey;
   const openaiKey = credentials?.openaiApiKey;
+  const groqKey = credentials?.groqApiKey;
 
-  if (!anthropicKey && !openaiKey) {
-    throw new Error('No API key found. Add ANTHROPIC_API_KEY or OPENAI_API_KEY to ~/.ticketlens/credentials.json');
-  }
-
-  if (anthropicKey) {
+  if (provider === 'anthropic') {
+    if (!anthropicKey) throw new Error('No ANTHROPIC_API_KEY found. Add it to ~/.ticketlens/credentials.json');
     return callAnthropic({ brief, apiKey: anthropicKey, fetcher, timeoutMs, prompt, maxTokens });
   }
+  if (provider === 'openai') {
+    if (!openaiKey) throw new Error('No OPENAI_API_KEY found. Add it to ~/.ticketlens/credentials.json');
+    return callOpenAi({ brief, apiKey: openaiKey, fetcher, timeoutMs, prompt, maxTokens });
+  }
+  if (provider === 'groq') {
+    if (!groqKey) throw new Error('No GROQ_API_KEY found. Add it to ~/.ticketlens/credentials.json');
+    return callGroq({ brief, apiKey: groqKey, fetcher, timeoutMs, prompt, maxTokens });
+  }
 
-  return callOpenAi({ brief, apiKey: openaiKey, fetcher, timeoutMs, prompt, maxTokens });
+  if (!anthropicKey && !openaiKey && !groqKey) {
+    throw new Error('No API key found. Add ANTHROPIC_API_KEY, OPENAI_API_KEY, or GROQ_API_KEY to ~/.ticketlens/credentials.json');
+  }
+  if (anthropicKey) return callAnthropic({ brief, apiKey: anthropicKey, fetcher, timeoutMs, prompt, maxTokens });
+  if (openaiKey) return callOpenAi({ brief, apiKey: openaiKey, fetcher, timeoutMs, prompt, maxTokens });
+  return callGroq({ brief, apiKey: groqKey, fetcher, timeoutMs, prompt, maxTokens });
 }
 
 async function callAnthropic({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens }) {
@@ -94,6 +106,33 @@ async function callOpenAi({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens
   return data.choices[0].message.content;
 }
 
+async function callGroq({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens }) {
+  const res = await fetcher(GROQ_URL, {
+    method: 'POST',
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: 'llama-3.1-8b-instant',
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt + brief }],
+    }),
+  });
+
+  if (!res.ok) {
+    let detail = '';
+    try { detail = (await res.json()).error?.message || ''; } catch {}
+    const err = new Error(`Groq API error ${res.status}${detail ? ': ' + detail : ''}`);
+    err.status = res.status;
+    throw err;
+  }
+
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
 async function cloud({ brief, licenseKey, fetcher, timeoutMs }) {
   const res = await fetcher(CLOUD_URL, {
     method: 'POST',