ticketlens 0.26.0 → 0.30.0

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

@@ -16,6 +16,8 @@ import { resolveConnection } from './profile-resolver.mjs';
 import { resolveAdapter } from './resolve-adapter.mjs';
 import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
 import { logAction } from './ticket-action-log.mjs';
+import { readMetadataCache, writeMetadataCache } from './ticket-metadata-cache.mjs';
+import { detectProjectOrTypeError, enrichCreateFailure } from './ticket-create-enrichment.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { scoreCandidates } from './duplicate-scorer.mjs';
 
@@ -68,24 +70,91 @@ function formatWriteFailure(ticketKey, err) {
  * Read-path counterpart to formatWriteFailure — reuses the same
  * classification (rate-limit/timeout/server-error metadata is real and
  * worth keeping, not specific to writes) but with read-appropriate wording,
- * since "duplicates" never writes anything.
+ * parameterized by what's being checked (e.g. "for duplicates", "for link
+ * options") since neither duplicates nor link-list ever writes anything.
  */
+function formatReadFailure(ticketKey, err, actionPhrase) {
+  const classification = classifyWriteFailure(err);
+  switch (classification.kind) {
+    case 'rate-limited': {
+      const wait = classification.detail.retryAfterSeconds ?? null;
+      return wait
+        ? `  Rate limited by the tracker — retry checking ${ticketKey} ${actionPhrase} after ~${wait}s.\n`
+        : `  Rate limited by the tracker — try checking ${ticketKey} ${actionPhrase} again later.\n`;
+    }
+    case 'network-or-timeout':
+      return `  Network error or timeout checking ${ticketKey} ${actionPhrase}. Try again.\n`;
+    case 'server-error':
+      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} ${actionPhrase}. Try again later.\n`;
+    default:
+      return `  Error checking ${ticketKey} ${actionPhrase}: ${err.message}\n`;
+  }
+}
+
 function formatDuplicatesFailure(ticketKey, err) {
+  return formatReadFailure(ticketKey, err, 'for duplicates');
+}
+
+function formatLinkListFailure(ticketKey, err) {
+  return formatReadFailure(ticketKey, err, 'for link options');
+}
+
+/**
+ * Create-path counterpart to formatWriteFailure — same classification, but
+ * there is no ticket key to interpolate (creation never happened).
+ */
+function formatCreateFailure(err) {
   const classification = classifyWriteFailure(err);
   switch (classification.kind) {
     case 'rate-limited': {
       const wait = classification.detail.retryAfterSeconds ?? null;
       return wait
-        ? `  Rate limited by the tracker — retry checking ${ticketKey} after ~${wait}s.\n`
-        : `  Rate limited by the tracker — try checking ${ticketKey} again later.\n`;
+        ? `  Rate limited by the tracker — retry creating the ticket after ~${wait}s.\n`
+        : `  Rate limited by the tracker — try creating the ticket again later.\n`;
     }
     case 'network-or-timeout':
-      return `  Network error or timeout checking ${ticketKey} for duplicates. Try again.\n`;
+      return `  Network error or timeout creating the ticket — not retried automatically (a timed-out write may have already landed; check the tracker before retrying).\n`;
     case 'server-error':
-      return `  Tracker returned a server error (${classification.status}) checking ${ticketKey} for duplicates. Try again later.\n`;
+      return `  Tracker returned a server error (${classification.status}) creating the ticket. Try again later.\n`;
     default:
-      return `  Error checking ${ticketKey} for duplicates: ${err.message}\n`;
+      return `  Failed to create the ticket: ${err.message}\n`;
+  }
+}
+
+/**
+ * Adapter error shapes for updateFields genuinely differ per tracker: a
+ * thrown Error (Jira/atomic-call failures, GitHub's shared title/description
+ * PATCH, GitHub's addLabels call), a { reason: 'not-found', missing/options }
+ * descriptor (Linear's pre-flight label/priority resolution), or a
+ * label -> Error map (GitHub's per-label DELETE loop, since each removal is
+ * independent and can fail differently). Never assume a single shape.
+ */
+function formatFieldError(field, info) {
+  if (info instanceof Error) return `${field} (${info.message})`;
+  if (info?.reason === 'not-found') {
+    const list = info.missing ?? info.options ?? [];
+    return `${field} (not found${list.length ? `: ${list.join(', ')}` : ''})`;
   }
+  const perLabel = Object.entries(info ?? {}).map(([label, err]) => `${label}: ${err.message}`).join(', ');
+  return `${field} (${perLabel})`;
+}
+
+function describeAppliedFields(applied) {
+  const parts = [];
+  if (applied.title) parts.push('title');
+  if (applied.description) parts.push('description');
+  if (applied.priority) parts.push(`priority=${applied.priority}`);
+  if (applied.addLabels?.length) parts.push(`+labels(${applied.addLabels.join(', ')})`);
+  if (applied.removeLabels?.length) parts.push(`-labels(${applied.removeLabels.join(', ')})`);
+  return parts.join(', ');
+}
+
+function formatUpdateResult(ticketKey, { applied, errors }) {
+  const appliedText = describeAppliedFields(applied);
+  const errorText = Object.entries(errors).map(([field, info]) => formatFieldError(field, info)).join('; ');
+  if (appliedText && !errorText) return `  ${ticketKey} updated: ${appliedText}.\n`;
+  if (appliedText && errorText) return `  ${ticketKey} partially updated: ${appliedText}. Failed: ${errorText}.\n`;
+  return `  Nothing updated on ${ticketKey}. Failed: ${errorText}.\n`;
 }
 
 function requireLicense(isLicensedFn, configDir, commandName, stream) {
@@ -103,11 +172,19 @@ function requireTicketKey(cmdArgs, usage, stream) {
   return ticketKey;
 }
 
+/**
+ * `ticketKey` is undefined for ticket_create — there is no existing ticket to
+ * prefix-match a connection from, so resolution falls through to --profile
+ * or the default profile (resolveConnectionFn already handles a falsy
+ * ticketKey by skipping prefix matching, see profile-resolver.mjs).
+ */
 function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
   const profileName = parseFlag(cmdArgs, 'profile');
   const conn = resolveConnectionFn(ticketKey, { configDir, profileName });
   if (!conn.baseUrl) {
-    stream.write(`  No connection configured for ${ticketKey}. Run \`ticketlens init\`.\n`);
+    stream.write(ticketKey
+      ? `  No connection configured for ${ticketKey}. Run \`ticketlens init\`.\n`
+      : `  No connection configured. Run \`ticketlens init\` or pass --profile=NAME.\n`);
     return null;
   }
   return resolveAdapterFn(conn);
@@ -368,3 +445,319 @@ export async function runTicketDuplicates(cmdArgs, {
     return { ok: false };
   }
 }
+
+/**
+ * Discovery only — never mutates. Lists the tracker's current available
+ * link types for sourceKey→targetKey. Jira's list is always fetched live
+ * (per-instance customizable — never cached, same principle as
+ * getTransitions). GitHub's "list" is really a single-item warning: its
+ * only link action closes sourceKey as a duplicate of targetKey, a
+ * materially louder operation than Jira/Linear's pure relationship-add,
+ * so that asymmetry is surfaced here before a caller ever reaches --confirm.
+ *
+ * @param {string[]} cmdArgs - [sourceKey, targetKey]
+ * @returns {Promise<{ ok: boolean, types?: string[] }>}
+ */
+export async function runTicketLinkList(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+} = {}) {
+  const usage = 'Usage: ticketlens link SOURCE-KEY TARGET-KEY [--type="..." --confirm]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens link', stream)) return { ok: false };
+
+  const sourceKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!sourceKey) return { ok: false };
+  const targetKey = requireTicketKey(cmdArgs.slice(1), usage, stream);
+  if (!targetKey) return { ok: false };
+
+  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  try {
+    const types = await adapter.getLinkTypes();
+    if (types.length === 0) {
+      stream.write(`  No link types available for ${sourceKey} → ${targetKey} on ${adapter.type}.\n`);
+      return { ok: true, types: [] };
+    }
+    stream.write(`  Available link types for ${sourceKey} → ${targetKey} (${adapter.type}):\n`);
+    for (const t of types) stream.write(`    - ${t}\n`);
+    if (adapter.type === 'github') {
+      stream.write(`  Note: GitHub has no generic link relationship — linking will CLOSE ${sourceKey} as a duplicate of ${targetKey}.\n`);
+    }
+    stream.write(`  Run again with --type="<name>" --confirm to execute — ${sourceKey} will be recorded as the one that "types" ${targetKey}.\n`);
+    return { ok: true, types };
+  } catch (err) {
+    stream.write(formatLinkListFailure(sourceKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Executes a link. Requires both --type and --confirm — a type without
+ * confirm is incomplete input, never silently executed. Cooldown is keyed
+ * on the source:target pair (not sourceKey alone) so a second link to a
+ * different target isn't blocked by the debounce window; the audit log
+ * keeps ticketKey as the single valid sourceKey (logAction throws on
+ * anything else) with targetKey/type carried in detail instead.
+ *
+ * @param {string[]} cmdArgs - [sourceKey, targetKey, '--type=...', '--confirm']
+ * @returns {Promise<{ ok: boolean, reason?: string }>}
+ */
+export async function runTicketLink(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  actor = os.userInfo().username,
+} = {}) {
+  const usage = 'Usage: ticketlens link SOURCE-KEY TARGET-KEY --type="..." --confirm\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens link', stream)) return { ok: false };
+
+  const sourceKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!sourceKey) return { ok: false };
+  const targetKey = requireTicketKey(cmdArgs.slice(1), usage, stream);
+  if (!targetKey) return { ok: false };
+
+  const type = parseFlag(cmdArgs, 'type');
+  if (!type) {
+    stream.write(usage);
+    return { ok: false };
+  }
+  if (!cmdArgs.includes('--confirm')) {
+    stream.write(`  Refusing to link ${sourceKey} to ${targetKey} as "${type}" without --confirm. Re-run with --confirm once you've reviewed the target.\n`);
+    return { ok: false };
+  }
+
+  const cooldownKey = `${sourceKey}:${targetKey}`;
+  const cooldown = checkCooldownFn(cooldownKey, 'link', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — ${sourceKey} was already linked to ${targetKey} ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  if (adapter.type === 'github' && type.toLowerCase() !== 'duplicate') {
+    stream.write(`  GitHub only supports linking as a duplicate — no generic link types. Got type "${type}".\n`);
+    return { ok: false };
+  }
+  if (adapter.type === 'github') {
+    stream.write(`  Note: this will CLOSE ${sourceKey} as a duplicate of ${targetKey} on GitHub.\n`);
+  }
+
+  try {
+    const result = await adapter.linkTo(sourceKey, targetKey, type);
+    if (!result.executed) {
+      const optionsHint = result.options?.length ? ` Valid options: ${result.options.join(', ')}.` : '';
+      stream.write(`  Not linked — ${result.reason}.${optionsHint}\n`);
+      return { ok: false, reason: result.reason };
+    }
+    recordActionFn(cooldownKey, 'link', { configDir });
+    logActionFn({ ticketKey: sourceKey, action: 'link', actor, tracker: adapter.type, detail: { targetKey, type } }, { configDir });
+    stream.write(
+      adapter.type === 'github'
+        ? `  ${sourceKey} closed as a duplicate of ${targetKey}.\n`
+        : `  ${sourceKey} linked to ${targetKey} as "${type}".\n`,
+    );
+    return { ok: true };
+  } catch (err) {
+    stream.write(formatWriteFailure(sourceKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Updates a narrow, named field set (title, description, labels, priority).
+ * No --confirm gate, unlike transition/link: those two have a list-then-act
+ * discovery step that --confirm gates the boundary of; update has none
+ * (priority validity surfaces the tracker's own error, same choice already
+ * made for ticket_create's issuetype) and its edits are reversible metadata
+ * changes with no workflow-state side effects — same risk tier as assign,
+ * which also ships with no --confirm.
+ *
+ * updateFields' result shape genuinely differs by how atomic each tracker's
+ * write is: Jira/Linear do it in one call and either fully succeed or throw
+ * (caught below, same as every other write); GitHub's title/description and
+ * label operations are independent HTTP calls, so it always returns
+ * { applied, errors } even on total failure. Whatever DID apply is still
+ * recorded/logged — a caller needs the cooldown to reflect a real partial
+ * write, and the audit trail should show what actually changed even if not
+ * everything did.
+ *
+ * @param {string[]} cmdArgs - [ticketKey, '--title=...', '--description=...', '--add-labels=a,b', '--remove-labels=c', '--priority=...']
+ * @returns {Promise<{ ok: boolean, applied?: object, errors?: object }>}
+ */
+export async function runTicketUpdate(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  actor = os.userInfo().username,
+} = {}) {
+  const usage = 'Usage: ticketlens update TICKET-KEY [--title="..."] [--description="..."] [--add-labels=a,b] [--remove-labels=c] [--priority="High"]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens update', stream)) return { ok: false };
+
+  const ticketKey = requireTicketKey(cmdArgs, usage, stream);
+  if (!ticketKey) return { ok: false };
+
+  const title = parseFlag(cmdArgs, 'title');
+  const description = parseFlag(cmdArgs, 'description');
+  const priority = parseFlag(cmdArgs, 'priority');
+  const addLabelsArg = parseFlag(cmdArgs, 'add-labels');
+  const removeLabelsArg = parseFlag(cmdArgs, 'remove-labels');
+  const addLabels = addLabelsArg ? addLabelsArg.split(',').map(l => l.trim()).filter(Boolean) : undefined;
+  const removeLabels = removeLabelsArg ? removeLabelsArg.split(',').map(l => l.trim()).filter(Boolean) : undefined;
+
+  if (title === undefined && description === undefined && priority === undefined && !addLabels?.length && !removeLabels?.length) {
+    stream.write(usage);
+    return { ok: false };
+  }
+
+  const cooldown = checkCooldownFn(ticketKey, 'update', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — ${ticketKey} was already updated ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  if (adapter.type === 'github' && priority !== undefined) {
+    stream.write(`  GitHub Issues have no native priority field — cannot update priority on ${ticketKey}. Remove --priority and retry.\n`);
+    return { ok: false };
+  }
+
+  try {
+    const result = await adapter.updateFields(ticketKey, { title, description, priority, addLabels, removeLabels });
+    const hasApplied = Object.keys(result.applied).length > 0;
+    const hasErrors = Object.keys(result.errors).length > 0;
+
+    if (hasApplied) {
+      recordActionFn(ticketKey, 'update', { configDir });
+      logActionFn({ ticketKey, action: 'update', actor, tracker: adapter.type, detail: { ...result.applied, failed: Object.keys(result.errors) } }, { configDir });
+    }
+    stream.write(formatUpdateResult(ticketKey, result));
+    return hasErrors ? { ok: false, applied: result.applied, errors: result.errors } : { ok: true, applied: result.applied };
+  } catch (err) {
+    stream.write(formatWriteFailure(ticketKey, err));
+    return { ok: false };
+  }
+}
+
+/**
+ * Creates a new ticket in the tracker (Jira/GitHub/Linear) — architecturally
+ * unlike every other write in this family: there is no existing ticket key
+ * to resolve a connection from, so --profile (or the default profile) picks
+ * the target tracker instead of ticket-prefix matching. --project is the
+ * project key (Jira) or team key (Linear) to create in — GitHub ignores it,
+ * its target repo is fixed by the profile. --type (Jira issuetype) is
+ * Jira-only; GitHub/Linear have no equivalent concept and ignore it with a
+ * warning — unlike an extra --project on GitHub, which is dropped silently,
+ * since a stray --type usually means the caller thought they were talking to
+ * Jira and should hear otherwise. Highest blast radius of the whole write
+ * family — a bad project/issuetype fabricates a real,
+ * hard-to-walk-back item in a live tracker — so, unlike update/assign, the
+ * cooldown key is derived from (project, type, summary) rather than a
+ * ticket key, guarding against exactly the flaky-retry double-creation
+ * scenario this whole mechanism exists to catch. No --confirm gate: same
+ * "no discovery step, reversible-enough risk tier" reasoning already
+ * applied to update/assign — the terminal errors below (missing --project/
+ * --type, an unresolvable Linear team, a bad Jira issuetype) are the
+ * safeguard, not a confirmation prompt.
+ *
+ * @param {string[]} cmdArgs - ['--project=...', '--type=...', '--summary=...', '--description=...', '--profile=...']
+ * @returns {Promise<{ ok: boolean, key?: string }>}
+ */
+export async function runTicketCreate(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  readMetadataCacheFn = readMetadataCache,
+  writeMetadataCacheFn = writeMetadataCache,
+  actor = os.userInfo().username,
+} = {}) {
+  const usage = 'Usage: ticketlens create --project=KEY --type="Task" --summary="..." [--description="..."] [--profile=NAME]\n';
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens create', stream)) return { ok: false };
+
+  const summary = parseFlag(cmdArgs, 'summary');
+  if (!summary) {
+    stream.write(usage);
+    return { ok: false };
+  }
+
+  const project = parseFlag(cmdArgs, 'project');
+  const type = parseFlag(cmdArgs, 'type');
+  const description = parseFlag(cmdArgs, 'description');
+
+  const adapter = resolveTicketAdapter(undefined, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!adapter) return { ok: false };
+
+  if (adapter.type !== 'github' && !project) {
+    stream.write(`  --project is required for ${adapter.type === 'jira' ? 'Jira (project key)' : 'Linear (team key)'}.\n`);
+    return { ok: false };
+  }
+  if (adapter.type === 'jira' && !type) {
+    stream.write(`  --type is required for Jira (issue type, e.g. "Task" or "Bug").\n`);
+    return { ok: false };
+  }
+  if (adapter.type !== 'jira' && type !== undefined) {
+    stream.write(`  Note: --type is ignored by ${adapter.type} — issue created without it.\n`);
+  }
+
+  // JSON-encoded, not naively colon-joined — project/type/summary are free
+  // text that can themselves contain ":", which would let two genuinely
+  // different tuples collide onto the same cooldown key.
+  const cooldownKey = `create:${JSON.stringify([project ?? '', type ?? '', summary])}`;
+  const cooldown = checkCooldownFn(cooldownKey, 'create', { configDir });
+  if (cooldown.active) {
+    stream.write(`  Skipped — a ticket with this summary was already created ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  let result;
+  try {
+    result = await adapter.createTicket({ project, type, summary, description });
+  } catch (err) {
+    // profileName is only resolved when this failure is actually
+    // project/issuetype-shaped — not on every failure, and never on the
+    // success path — since it exists solely to scope the enrichment cache.
+    let enrichment = '';
+    if (detectProjectOrTypeError(err)) {
+      const profileName = resolveConnectionFn(undefined, { configDir, profileName: parseFlag(cmdArgs, 'profile') }).profileName;
+      enrichment = await enrichCreateFailure(err, { adapter, project, profileName, configDir, readMetadataCacheFn, writeMetadataCacheFn });
+    }
+    stream.write(formatCreateFailure(err) + enrichment);
+    return { ok: false };
+  }
+
+  // The write already landed — a real, external, hard-to-walk-back ticket
+  // now exists. From here on, nothing may report this as a failed write:
+  // cooldown/audit bookkeeping is best-effort, never the reason a real
+  // success gets mistaken for one (which risks a caller retrying and
+  // fabricating a genuine duplicate).
+  try {
+    recordActionFn(cooldownKey, 'create', { configDir });
+    logActionFn({ ticketKey: result.key, action: 'create', actor, tracker: adapter.type, detail: { project, type } }, { configDir });
+  } catch (bookkeepingErr) {
+    stream.write(`  Warning: ${result.key} was created but could not be logged: ${bookkeepingErr.message}\n`);
+  }
+  stream.write(`  Created ${result.key}${result.url ? ` (${result.url})` : ''}\n`);
+  return { ok: true, key: result.key };
+}

package/skills/jtb/scripts/lib/ticket-create-enrichment.mjs

@@ -0,0 +1,80 @@
+/**
+ * Failure-message enrichment for `ticket_create` — reactive only, never
+ * runs on the success path. Extracted from ticket-command.mjs to keep that
+ * file under the project's 800-line cap and to isolate a self-contained
+ * concern (project/issuetype cache read-through-and-refresh) from the rest
+ * of ticket-command.mjs's routing logic.
+ */
+
+/**
+ * Detects whether a create failure is shaped like a project/issuetype
+ * mismatch — the only case cache-refresh enrichment applies to. Jira
+ * surfaces this via its own real `err.details.errors.{project,issuetype}`
+ * keys (confirmed by direct observation against a live instance during
+ * ticket_create's own launch verification); Linear's client-side
+ * team-resolution failure is marked with `err.code` instead of
+ * message-sniffed. Anything else (rate limits, network errors, generic
+ * 4xx/5xx) returns null — enrichment never applies there.
+ */
+export function detectProjectOrTypeError(err) {
+  if (err?.code === 'PROJECT_NOT_FOUND') return { project: true, type: false };
+  const errors = err?.details?.errors;
+  if (!errors) return null;
+  const project = 'project' in errors;
+  const type = 'issuetype' in errors;
+  return (project || type) ? { project, type } : null;
+}
+
+/**
+ * Best-effort failure-message enrichment for ticket_create — reactive
+ * only, never runs on the success path or for a non-project/type failure.
+ * Reuses a cached project/issue-type listing when fresh (no extra network
+ * call); refreshes it when missing/stale. A refresh failure is swallowed
+ * entirely and nothing is written to the cache: this can only ever make
+ * an error message MORE informative, never introduce a new way for
+ * ticketlens create to fail or a new way to poison the cache.
+ */
+export async function enrichCreateFailure(err, { adapter, project, profileName, configDir, readMetadataCacheFn, writeMetadataCacheFn }) {
+  const shape = detectProjectOrTypeError(err);
+  if (!shape || adapter.type === 'github') return '';
+
+  let cached = readMetadataCacheFn(profileName, configDir);
+  // Checked independently, not "cache present? skip entirely" — a cache
+  // populated by an earlier *project* error has projects but no issue
+  // types for this specific project, and vice versa. Treating any cache
+  // hit as fully sufficient silently drops the other half of a later,
+  // differently-shaped error's enrichment (caught via live-instance
+  // testing, not by unit tests alone).
+  const needsProjects = shape.project && !cached?.projects?.length;
+  const needsIssueTypes = shape.type && adapter.type === 'jira' && project && !cached?.issueTypesByProject?.[project]?.length;
+
+  if (needsProjects || needsIssueTypes) {
+    try {
+      const projects = needsProjects ? await adapter.listCreatableProjects() : (cached?.projects ?? []);
+      // Object.create(null), not {} — `project` is an unvalidated CLI value
+      // reaching this key position. On a plain {}, assigning to a key like
+      // "__proto__" redirects into the object's own prototype slot instead
+      // of creating a real entry, silently losing this project's cache
+      // write. A null-prototype target has no such accessor to intercept.
+      const issueTypesByProject = Object.assign(Object.create(null), cached?.issueTypesByProject ?? {});
+      if (needsIssueTypes) {
+        issueTypesByProject[project] = await adapter.listIssueTypes(project);
+      }
+      cached = { projects, issueTypesByProject };
+      writeMetadataCacheFn(profileName, cached, configDir);
+    } catch {
+      return '';
+    }
+  }
+
+  if (!cached) return '';
+
+  const parts = [];
+  if (shape.project && cached.projects?.length) {
+    parts.push(`  Known creatable projects: ${cached.projects.map(p => p.key).join(', ')}.\n`);
+  }
+  if (shape.type && project && cached.issueTypesByProject?.[project]?.length) {
+    parts.push(`  Known issue types for ${project}: ${cached.issueTypesByProject[project].map(t => t.name).join(', ')}.\n`);
+  }
+  return parts.join('');
+}

package/skills/jtb/scripts/lib/ticket-metadata-cache.mjs

@@ -0,0 +1,84 @@
+/**
+ * Project/issue-type metadata cache for `ticketlens create` — stores what
+ * this profile has actually confirmed it can create against (real project
+ * keys, real Jira issue types per project), refreshed only when a create
+ * attempt fails with a project/issuetype-shaped error. Never populated on
+ * the success path: that data only has value for enriching a failure
+ * message, so fetching it on every create call "just in case" would waste
+ * a network round-trip for the common case where the caller already got
+ * project/type right.
+ *
+ * Path:   ~/.ticketlens/cache/PROFILE/ticket-metadata.json
+ * Format: { fetchedAt, projects: [{key, name}], issueTypesByProject: {KEY: [{id, name}]} }
+ * TTL:    24 hours (bypassed by an always-forced refresh from the caller
+ *         after a project/issuetype error — see ticket-command.mjs)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+
+export const METADATA_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Returns the absolute path to the ticket-metadata cache file for a profile.
+ */
+export function metadataCachePath(profileName, configDir = DEFAULT_CONFIG_DIR) {
+  const safeProfile = (profileName || '_default').replace(/[^a-zA-Z0-9_\-]/g, '_');
+  const resolvedDir = path.resolve(configDir);
+  const result = path.join(resolvedDir, 'cache', safeProfile, 'ticket-metadata.json');
+  // Defense-in-depth: ensure the final path cannot escape the config directory,
+  // even if configDir itself is manipulated or the sanitization above is weakened.
+  if (!result.startsWith(resolvedDir + path.sep)) {
+    throw new Error(`Cache path escapes config directory: ${result}`);
+  }
+  return result;
+}
+
+/**
+ * Reads cached project/issue-type metadata for a profile.
+ * Returns null on cache miss, expired TTL, or corrupt JSON.
+ *
+ * @param {string|null} profileName
+ * @param {string} [configDir]
+ * @param {number} [ttlMs] - override TTL in ms; defaults to METADATA_TTL_MS (24h)
+ * @returns {{ projects: {key:string,name:string}[], issueTypesByProject: object, fetchedAt: string } | null}
+ */
+export function readMetadataCache(profileName, configDir = DEFAULT_CONFIG_DIR, ttlMs = METADATA_TTL_MS) {
+  const filePath = metadataCachePath(profileName, configDir);
+  if (!fs.existsSync(filePath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const age = Date.now() - new Date(data.fetchedAt).getTime();
+  if (isNaN(age) || age > ttlMs) {
+    try { fs.unlinkSync(filePath); } catch { /* non-fatal */ }
+    return null;
+  }
+
+  return {
+    projects: data.projects ?? [],
+    issueTypesByProject: data.issueTypesByProject ?? {},
+    fetchedAt: data.fetchedAt,
+  };
+}
+
+/**
+ * Writes project/issue-type metadata to the cache. Non-fatal — a write
+ * failure must never break the caller (an enrichment attempt after an
+ * already-failed create).
+ */
+export function writeMetadataCache(profileName, { projects = [], issueTypesByProject = {} } = {}, configDir = DEFAULT_CONFIG_DIR) {
+  const filePath = metadataCachePath(profileName, configDir);
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ fetchedAt: new Date().toISOString(), projects, issueTypesByProject }));
+  } catch {
+    // Non-fatal
+  }
+}