@danypops/tickets 0.3.0 → 0.4.1

package/README.md

@@ -46,6 +46,9 @@ bun run src/cli/index.ts daemon restart
 
 bun run src/cli/index.ts backends
 bun run src/cli/index.ts list -b github --status todo
+# get includes fixVersions, issueLinks, externalLinks (Jira "Web Links", e.g.
+# the PR that fixed a bug), and customFields (by display name -- run
+# `discover fields` first, see below) whenever the backend has them.
 bun run src/cli/index.ts get jira:PROJ-42
 bun run src/cli/index.ts create -b github "Fix the thing" --label bug
 bun run src/cli/index.ts comment add jira:PROJ-42 "Looks good, shipping"
@@ -60,6 +63,17 @@ bun run src/cli/index.ts focus get
 bun run src/cli/index.ts focus pause "waiting on review"
 bun run src/cli/index.ts focus unpause
 bun run src/cli/index.ts focus clear
+
+# Discover and persist backend-specific mappings (Jira only today): custom
+# field display names -> IDs, and status names -> domain status. Read once
+# from the backend, cached to ~/.config/tickets/{fields,statuses}/<backend>.yaml
+# so a later lookup needs no network call and survives a daemon restart.
+bun run src/cli/index.ts discover fields -b jira
+bun run src/cli/index.ts discover statuses -b jira
+
+# Sample recent issues for a project/issue-type and extract a reusable
+# description template from the section headers common to all of them.
+bun run src/cli/index.ts discover template -b jira --project PROJ --issue-type Bug
 ```
 
 ### Running the daemon persistently (systemd --user)
@@ -157,6 +171,22 @@ tickets auth status
 tickets auth logout github
 ```
 
+### Static token instead (API key/PAT, no OAuth)
+
+For a backend with no OAuth app to register against (e.g. a plain Atlassian
+API token from `id.atlassian.com/manage-profile/security/api-tokens`),
+store it directly -- same 0600 local file `auth login` writes to, checked
+ahead of any `token`/`token_env` config-file or plain env-var fallback:
+
+```bash
+tickets auth set-token jira
+# Paste the "jira" token (input hidden): ****
+
+# or non-interactively, e.g. from a password manager (piped stdin works too,
+# since a non-TTY stdin is read as-is with nothing to mask):
+pass show jira-api-token | tickets auth set-token jira
+```
+
 ### GitHub: reuse an already-authenticated `gh` CLI session
 
 `tickets auth login --backend github --gh-cli [account]` skips the device
@@ -208,7 +238,8 @@ Published as `@danypops/pi-tickets`. `../pi-tickets/` (this repo's workspace mem
 [pi](https://github.com/badlogic/pi) with one action per CLI command (`list`,
 `get`, `create`, `update`, `search`, `children`, `comments`, `comment_add`,
 `backends`, `ledger_search`, `ledger_stats`, `focus_set`, `focus_get`,
-`focus_pause`, `focus_unpause`, `focus_clear`). It talks to the same daemon
+`focus_pause`, `focus_unpause`, `focus_clear`, `discover_fields`,
+`discover_statuses`, `discover_template`). It talks to the same daemon
 through the same authenticated RPC client the CLI uses — never a direct
 backend call or a direct SQLite open. OAuth login and daemon lifecycle
 control are deliberately **not** exposed here (neither as a tool action nor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",

package/src/adapters/jira.ts

@@ -15,9 +15,12 @@
 import { Version2Client } from "jira.js";
 import type { HttpException } from "jira.js";
 import type { AxiosAdapter } from "axios";
-import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
+import type { Comment, CreateInput, Issue, IssueLink, ListFilter, Status, UpdateInput } from "../domain/issue.js";
 import { parsePriority } from "../domain/issue.js";
 import { ApiError, IssueNotFoundError } from "./errors.js";
+import type { Template } from "../domain/template.js";
+import { buildTemplateBody, extractTemplateSections } from "../domain/template.js";
+import * as manifest from "../manifest/manifest.js";
 
 /**
  * Basic-auth mode (email + API token) hits the tenant's own *.atlassian.net
@@ -39,6 +42,13 @@ export interface JiraBasicAuthOptions {
   timeoutMs?: number;
   /** Injected in tests instead of a real network call — see axios's AxiosRequestConfig.adapter. */
   axiosAdapter?: AxiosAdapter;
+  /**
+   * Directory holding this daemon's persisted field/status discovery manifests
+   * (see ../manifest/manifest.ts), typically configDir() from config.ts. When
+   * omitted, discovery still works but nothing is persisted across restarts —
+   * every test and any caller that doesn't care about persistence can leave it out.
+   */
+  configDir?: string;
 }
 
 export interface JiraOAuthOptions {
@@ -47,12 +57,22 @@ export interface JiraOAuthOptions {
   project?: string;
   timeoutMs?: number;
   axiosAdapter?: AxiosAdapter;
+  configDir?: string;
 }
 
 function isOAuthOptions(opts: JiraOptions): opts is JiraOAuthOptions {
   return "accessToken" in opts;
 }
 
+interface JiraIssueLinkedIssue {
+  key: string;
+  fields: { summary: string; status: { name: string } };
+}
+interface JiraIssueLink {
+  type: { name: string; inward: string; outward: string };
+  inwardIssue?: JiraIssueLinkedIssue;
+  outwardIssue?: JiraIssueLinkedIssue;
+}
 interface JiraIssueFields {
   summary: string;
   description?: string | null;
@@ -67,6 +87,10 @@ interface JiraIssueFields {
   parent?: { key: string; fields?: { summary: string; status?: { name: string } } };
   created?: string;
   updated?: string;
+  fixVersions?: { name: string }[];
+  issuelinks?: JiraIssueLink[];
+  /** customfield_XXXXX passthrough -- Jira's getIssue returns every field by default, this just doesn't narrow their type. */
+  [key: string]: unknown;
 }
 interface JiraIssue {
   id: string;
@@ -74,6 +98,10 @@ interface JiraIssue {
   self: string;
   fields: JiraIssueFields;
 }
+interface JiraRemoteLink {
+  object?: { url?: string; title?: string };
+  application?: { name?: string };
+}
 interface JiraComment {
   id?: string;
   comment?: string;
@@ -92,12 +120,26 @@ export class JiraRepository {
   readonly name: string;
   private readonly client: Version2Client;
   private readonly project?: string;
+  private readonly configDir?: string;
   /** display name (lowercased) -> { fieldId, schema type/items }, populated lazily from client.issueFields.getFields(). */
   private customFieldCache?: Map<string, { id: string; type: string; items?: string }>;
+  /** field id -> display name, the inbound counterpart of customFieldCache. Seeded from the persisted manifest at construction (no network), refreshed by discoverFields(). */
+  private fieldNameById = new Map<string, string>();
+  /** Jira status name -> domain Status, loaded from the persisted manifest at construction; refreshed by discoverStatuses(). Empty until discovery has run at least once (falls back to category-based mapping until then). */
+  private statusManifest: manifest.Manifest;
 
   constructor(name: string, opts: JiraOptions) {
     this.name = name;
     this.project = opts.project;
+    this.configDir = opts.configDir;
+
+    if (this.configDir) {
+      const fieldManifest = manifest.load("fields", this.name, this.configDir);
+      for (const [displayName, id] of Object.entries(fieldManifest.mappings)) this.fieldNameById.set(id, displayName);
+      this.statusManifest = manifest.load("statuses", this.name, this.configDir);
+    } else {
+      this.statusManifest = { backend: this.name, mappings: {} };
+    }
 
     if (isOAuthOptions(opts)) {
       if (!opts.accessToken || !opts.cloudId) throw new Error("jira: accessToken and cloudId are required for OAuth mode");
@@ -133,8 +175,15 @@ export class JiraRepository {
   }
 
   async get(key: string): Promise<Issue> {
-    const raw = await this.call<JiraIssue>(() => this.client.issues.getIssue({ issueIdOrKey: key }), key);
-    return toDomain(raw);
+    const [raw, remoteLinks] = await Promise.all([
+      this.call<JiraIssue>(() => this.client.issues.getIssue({ issueIdOrKey: key }), key),
+      this.call<JiraRemoteLink[]>(() => this.client.issueRemoteLinks.getRemoteIssueLinks({ issueIdOrKey: key }), key),
+    ]);
+    const issue = this.toDomain(raw);
+    if (remoteLinks.length > 0) {
+      issue.externalLinks = remoteLinks.map((link) => ({ url: link.object?.url ?? "", title: link.object?.title, type: link.application?.name }));
+    }
+    return issue;
   }
 
   /** Runs a jira.js call and maps its HttpException onto this project's shared error taxonomy. */
@@ -218,7 +267,7 @@ export class JiraRepository {
     const result = await this.call<{ issues?: JiraIssue[] }>(() =>
       this.client.issueSearch.searchForIssuesUsingJqlPost({ jql, maxResults: limit }),
     );
-    return (result?.issues ?? []).map(toDomain);
+    return (result?.issues ?? []).map((raw) => this.toDomain(raw));
   }
 
   private async transitionTo(key: string, status: Status, resolution?: string): Promise<void> {
@@ -252,18 +301,173 @@ export class JiraRepository {
   }
 
   private async resolveCustomField(displayName: string): Promise<{ id: string; type: string; items?: string }> {
-    if (!this.customFieldCache) {
-      const all = await this.call<JiraFieldDetails[]>(() => this.client.issueFields.getFields());
-      this.customFieldCache = new Map(
-        all
-          .filter((f) => f.custom && f.id && f.name)
-          .map((f) => [f.name!.toLowerCase(), { id: f.id!, type: f.schema?.type ?? "string", items: f.schema?.items }]),
-      );
-    }
-    const field = this.customFieldCache.get(displayName.toLowerCase());
+    if (!this.customFieldCache) await this.discoverFields();
+    const field = this.customFieldCache?.get(displayName.toLowerCase());
     if (!field) throw new Error(`jira: unknown custom field "${displayName}"`);
     return field;
   }
+
+  /**
+   * Discovers every custom field's display name -> customfield_XXXXX ID via
+   * client.issueFields.getFields() (GET /rest/api/2/field), same live call
+   * resolveCustomField already made lazily -- this just also persists the
+   * result to a manifest (see ../manifest/manifest.ts) so a later inbound
+   * lookup (fieldDisplayName) doesn't need a network round trip at all, and
+   * survives a daemon restart. Ported from emcee's FieldService.DiscoverFields
+   * (~/Workspace/emcee), same manifest file shape.
+   */
+  async discoverFields(): Promise<Record<string, string>> {
+    const all = await this.call<JiraFieldDetails[]>(() => this.client.issueFields.getFields());
+    const custom = all.filter((f) => f.custom && f.id && f.name);
+    this.customFieldCache = new Map(
+      custom.map((f) => [f.name!.toLowerCase(), { id: f.id!, type: f.schema?.type ?? "string", items: f.schema?.items }]),
+    );
+    this.fieldNameById = new Map(custom.map((f) => [f.id!, f.name!]));
+    const mappings = Object.fromEntries(custom.map((f) => [f.name!, f.id!]));
+    if (this.configDir) manifest.save("fields", this.name, this.configDir, manifest.discover(this.name, mappings));
+    return mappings;
+  }
+
+  /** Inbound counterpart of resolveCustomField -- a display name for a raw customfield_XXXXX id, or undefined if never discovered. Never makes a network call; run discoverFields() (or construct with configDir set, so a prior discovery's manifest loads automatically) first. */
+  fieldDisplayName(fieldId: string): string | undefined {
+    return this.fieldNameById.get(fieldId);
+  }
+
+  /**
+   * Discovers every Jira status name -> domain Status via
+   * client.workflowStatuses.getStatuses() (GET /rest/api/2/status), persists
+   * it to a manifest, and immediately applies it in-memory so status mapping
+   * reflects the discovery without a daemon restart. Ported from emcee's
+   * StatusService.DiscoverStatuses.
+   */
+  async discoverStatuses(): Promise<Record<string, string>> {
+    const all = await this.call<{ name: string; statusCategory?: { key: string } }[]>(() => this.client.workflowStatuses.getStatuses());
+    const mappings = Object.fromEntries(all.map((s) => [s.name, categoryToStatus(s.statusCategory?.key)]));
+    this.statusManifest = manifest.discover(this.name, mappings);
+    if (this.configDir) manifest.save("statuses", this.name, this.configDir, this.statusManifest);
+    return mappings;
+  }
+
+  /**
+   * Samples the most recently created issues for a project/issue-type pair
+   * and extracts the description section headers common to all of them --
+   * see ../domain/template.ts. Ported from emcee's TemplateService.DiscoverTemplate.
+   */
+  async discoverTemplate(project: string, issueType: string, sampleSize = 5): Promise<Template | undefined> {
+    const jql = `project = ${jqlQuote(project)} AND issuetype = ${jqlQuote(issueType)} ORDER BY created DESC`;
+    const issues = await this.searchJql(jql, sampleSize > 0 ? sampleSize : 5);
+    const descriptions = issues.map((issue) => issue.description).filter((d): d is string => !!d);
+    const sections = extractTemplateSections(descriptions);
+    if (!sections) return undefined;
+    return { project, issueType, sections, body: buildTemplateBody(sections) };
+  }
+
+  private resolveStatus(categoryKey: string | undefined, statusName: string): Status {
+    const mapped = manifest.get(this.statusManifest, statusName);
+    if (mapped) return mapped as Status;
+    return mapStatusFromCategory(categoryKey);
+  }
+
+  private toDomain(j: JiraIssue): Issue {
+    const issue: Issue = {
+      ref: `jira:${j.key}`,
+      id: j.id,
+      key: j.key,
+      title: j.fields.summary,
+      description: j.fields.description ?? undefined,
+      status: this.resolveStatus(j.fields.status.statusCategory?.key, j.fields.status.name),
+      rawStatus: j.fields.status.name,
+      priority: mapPriorityFromJira(j.fields.priority?.name),
+      labels: j.fields.labels?.length ? j.fields.labels : undefined,
+      assignee: j.fields.assignee?.displayName,
+      reporter: j.fields.reporter?.displayName,
+      project: j.fields.project?.key,
+      issueType: j.fields.issuetype?.name,
+      resolution: j.fields.resolution?.name,
+      createdAt: j.fields.created,
+      updatedAt: j.fields.updated,
+    };
+    if (j.fields.parent) {
+      issue.parent = {
+        key: j.fields.parent.key,
+        title: j.fields.parent.fields?.summary ?? "",
+        status: j.fields.parent.fields?.status?.name,
+      };
+    }
+    if (j.self) {
+      const idx = j.self.indexOf("/rest/");
+      if (idx > 0) issue.url = `${j.self.slice(0, idx)}/browse/${j.key}`;
+    }
+    if (j.fields.fixVersions?.length) issue.fixVersions = j.fields.fixVersions.map((v) => v.name);
+    if (j.fields.issuelinks?.length) issue.issueLinks = j.fields.issuelinks.flatMap(jiraIssueLinkToDomain);
+    const customFields = this.extractCustomFields(j.fields);
+    if (customFields) issue.customFields = customFields;
+    return issue;
+  }
+
+  /**
+   * Every customfield_XXXXX Jira's getIssue response already carries (no
+   * extra call -- "All fields are returned by default", jira.js's own
+   * getIssue doc comment), keyed by display name via fieldNameById. A field
+   * with no known display name yet (discovery never ran for this backend) is
+   * skipped, not guessed at -- matching emcee's own "unmapped field, skip
+   * silently" behavior. Run `tickets discover fields -b <backend>` once, or
+   * construct with configDir set so a prior discovery's manifest loads
+   * automatically (see the constructor), to make more fields resolvable.
+   */
+  private extractCustomFields(fields: JiraIssueFields): Record<string, string> | undefined {
+    if (this.fieldNameById.size === 0) return undefined;
+    let result: Record<string, string> | undefined;
+    for (const [fieldId, displayName] of this.fieldNameById) {
+      const raw = fields[fieldId];
+      if (raw === undefined || raw === null) continue;
+      const value = formatCustomFieldValue(raw);
+      if (value === undefined) continue;
+      result ??= {};
+      result[displayName] = value;
+    }
+    return result;
+  }
+}
+
+function jiraIssueLinkToDomain(link: JiraIssueLink): IssueLink[] {
+  const links: IssueLink[] = [];
+  if (link.outwardIssue) {
+    links.push({
+      type: link.type.outward,
+      direction: "outward",
+      targetRef: `jira:${link.outwardIssue.key}`,
+      targetKey: link.outwardIssue.key,
+      targetTitle: link.outwardIssue.fields.summary,
+      targetStatus: link.outwardIssue.fields.status.name,
+    });
+  }
+  if (link.inwardIssue) {
+    links.push({
+      type: link.type.inward,
+      direction: "inward",
+      targetRef: `jira:${link.inwardIssue.key}`,
+      targetKey: link.inwardIssue.key,
+      targetTitle: link.inwardIssue.fields.summary,
+      targetStatus: link.inwardIssue.fields.status.name,
+    });
+  }
+  return links;
+}
+
+/** Formats one raw customfield_XXXXX value for display: a {name}-bearing array (e.g. version fields) joins names; a {value} option object unwraps; everything else is stringified as-is. */
+function formatCustomFieldValue(raw: unknown): string | undefined {
+  if (typeof raw === "string") return raw;
+  if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
+  if (Array.isArray(raw)) {
+    const names = raw.map((item) => (item && typeof item === "object" && "name" in item ? String((item as { name: unknown }).name) : undefined)).filter((n): n is string => !!n);
+    return names.length > 0 ? names.join(", ") : undefined;
+  }
+  if (raw && typeof raw === "object") {
+    if ("value" in raw) return String((raw as { value: unknown }).value);
+    if ("name" in raw) return String((raw as { name: unknown }).name);
+  }
+  return undefined;
 }
 
 function coerceCustomFieldValue(field: { type: string; items?: string }, rawValue: string): unknown {
@@ -303,7 +507,8 @@ function mapStatusToJira(status: Status): string {
   }
 }
 
-function mapStatusFromJira(categoryKey: string | undefined): Status {
+/** Baseline category -> Status mapping, used until a per-status-name manifest entry (discoverStatuses) says otherwise -- same fallback emcee's own mapStatusFromJira uses. */
+function mapStatusFromCategory(categoryKey: string | undefined): Status {
   switch (categoryKey) {
     case "new":
       return "todo";
@@ -316,6 +521,11 @@ function mapStatusFromJira(categoryKey: string | undefined): Status {
   }
 }
 
+/** categoryKey -> Status, used by discoverStatuses() to seed the persisted manifest from Jira's own status listing. */
+function categoryToStatus(categoryKey: string | undefined): Status {
+  return mapStatusFromCategory(categoryKey);
+}
+
 function mapPriorityToJira(p: ReturnType<typeof parsePriority>): string {
   switch (p) {
     case "urgent":
@@ -349,39 +559,6 @@ function mapPriorityFromJira(name: string | undefined): ReturnType<typeof parseP
   }
 }
 
-function toDomain(j: JiraIssue): Issue {
-  const issue: Issue = {
-    ref: `jira:${j.key}`,
-    id: j.id,
-    key: j.key,
-    title: j.fields.summary,
-    description: j.fields.description ?? undefined,
-    status: mapStatusFromJira(j.fields.status.statusCategory?.key),
-    rawStatus: j.fields.status.name,
-    priority: mapPriorityFromJira(j.fields.priority?.name),
-    labels: j.fields.labels?.length ? j.fields.labels : undefined,
-    assignee: j.fields.assignee?.displayName,
-    reporter: j.fields.reporter?.displayName,
-    project: j.fields.project?.key,
-    issueType: j.fields.issuetype?.name,
-    resolution: j.fields.resolution?.name,
-    createdAt: j.fields.created,
-    updatedAt: j.fields.updated,
-  };
-  if (j.fields.parent) {
-    issue.parent = {
-      key: j.fields.parent.key,
-      title: j.fields.parent.fields?.summary ?? "",
-      status: j.fields.parent.fields?.status?.name,
-    };
-  }
-  if (j.self) {
-    const idx = j.self.indexOf("/rest/");
-    if (idx > 0) issue.url = `${j.self.slice(0, idx)}/browse/${j.key}`;
-  }
-  return issue;
-}
-
 function commentToDomain(c: JiraComment): Comment {
   return {
     id: c.id ?? "",

package/src/application/service.ts

@@ -6,7 +6,14 @@
  */
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
 import { parseRef } from "../domain/issue.js";
-import { hasComments, type IssueRepository } from "../ports/repository.js";
+import type { Template } from "../domain/template.js";
+import {
+  hasComments,
+  hasFieldDiscovery,
+  hasStatusDiscovery,
+  hasTemplateDiscovery,
+  type IssueRepository,
+} from "../ports/repository.js";
 
 export class UnknownBackendError extends Error {
   constructor(backend: string, known: string[]) {
@@ -92,4 +99,22 @@ export class TicketService {
     if (!hasComments(repo)) throw new NotSupportedError(backend, "comments");
     return repo.addComment(key, body);
   }
+
+  async discoverFields(backend: string): Promise<Record<string, string>> {
+    const repo = this.repo(backend);
+    if (!hasFieldDiscovery(repo)) throw new NotSupportedError(backend, "field discovery");
+    return repo.discoverFields();
+  }
+
+  async discoverStatuses(backend: string): Promise<Record<string, string>> {
+    const repo = this.repo(backend);
+    if (!hasStatusDiscovery(repo)) throw new NotSupportedError(backend, "status discovery");
+    return repo.discoverStatuses();
+  }
+
+  async discoverTemplate(backend: string, project: string, issueType: string, sampleSize?: number): Promise<Template | undefined> {
+    const repo = this.repo(backend);
+    if (!hasTemplateDiscovery(repo)) throw new NotSupportedError(backend, "template discovery");
+    return repo.discoverTemplate(project, issueType, sampleSize);
+  }
 }

package/src/auth/masked-prompt.ts

@@ -0,0 +1,54 @@
+/**
+ * Reads a secret from a real TTY with keystrokes masked -- never echoed to
+ * the terminal, so it can't land in scrollback or a screen share the way a
+ * typed-and-visible value would. Falls back to reading one line from stdin
+ * unmasked when stdin isn't a TTY (piped input, e.g. `pass show jira |
+ * tickets auth set-token jira`) -- there is nothing to mask once the value
+ * never touched an interactive terminal in the first place.
+ */
+import { createInterface } from "node:readline";
+
+export function promptMaskedSecret(
+  promptText: string,
+  input: NodeJS.ReadableStream = process.stdin,
+  output: NodeJS.WritableStream = process.stdout,
+): Promise<string> {
+  const isTTY = (input as NodeJS.ReadStream).isTTY === true;
+
+  if (!isTTY) {
+    return new Promise((resolve, reject) => {
+      let data = "";
+      input.setEncoding?.("utf8");
+      input.on("data", (chunk) => {
+        data += chunk;
+      });
+      input.on("end", () => resolve(data.split("\n")[0]?.trim() ?? ""));
+      input.on("error", reject);
+    });
+  }
+
+  return new Promise((resolve, reject) => {
+    const rl = createInterface({ input, output, terminal: true });
+    // readline has no public masking option; overriding the internal
+    // _writeToOutput hook (long-standing, widely-used pattern for exactly
+    // this) is the only way to suppress echoed keystrokes while still
+    // letting the prompt text itself render once.
+    // biome-ignore lint/suspicious/noExplicitAny: readline's internal _writeToOutput has no public type
+    const rlInternal = rl as any;
+    const originalWriteToOutput = rlInternal._writeToOutput.bind(rl);
+    let promptShown = false;
+    rlInternal._writeToOutput = (stringToWrite: string) => {
+      if (!promptShown) {
+        originalWriteToOutput(stringToWrite);
+        if (stringToWrite.includes(promptText)) promptShown = true;
+      }
+      // Every keystroke after the prompt itself is swallowed -- masked.
+    };
+    rl.question(promptText, (answer) => {
+      rl.close();
+      output.write("\n");
+      resolve(answer.trim());
+    });
+    rl.on("error", reject);
+  });
+}

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import { readGhCliToken } from "../auth/gh-cli.js";
 import { gitlabDeviceEndpoints, loginWithGitLabDeviceFlow } from "../auth/gitlab-oauth.js";
 import { loginWithJiraAuthorizationCode } from "../auth/jira-oauth.js";
 import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
+import { promptMaskedSecret } from "../auth/masked-prompt.js";
 import { installTicketsService, systemctlTickets, systemdUnitPath } from "./systemd-service.js";
 
 function printJson(value: unknown): void {
@@ -195,6 +196,37 @@ focus
     await withClient((client) => client.call("focus.clear", {}));
   });
 
+const discoverCmd = program.command("discover").description("discover and persist backend-specific mappings (custom fields, statuses) or a description template");
+
+discoverCmd
+  .command("fields")
+  .description("discover a backend's custom field display names -> IDs and persist them for reuse (Jira only today)")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .action(async (opts) => {
+    await withClient((client) => client.call("discover.fields", { backend: opts.backend }));
+  });
+
+discoverCmd
+  .command("statuses")
+  .description("discover a backend's status names -> domain status and persist them (Jira only today)")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .action(async (opts) => {
+    await withClient((client) => client.call("discover.statuses", { backend: opts.backend }));
+  });
+
+discoverCmd
+  .command("template")
+  .description("sample recent issues for a project/issue-type and extract a reusable description template (Jira only today)")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .requiredOption("--project <project>", "project key")
+  .requiredOption("--issue-type <type>", "issue type, e.g. Bug")
+  .option("--sample-size <n>", "how many recent issues to sample", (v) => Number.parseInt(v, 10))
+  .action(async (opts) => {
+    await withClient((client) =>
+      client.call("discover.template", { backend: opts.backend, project: opts.project, issueType: opts.issueType, sampleSize: opts.sampleSize }),
+    );
+  });
+
 const daemon = program.command("daemon").description("manage the tickets daemon process");
 
 daemon
@@ -391,6 +423,23 @@ auth
     }
   });
 
+auth
+  .command("set-token <backend>")
+  .description("store a plain static token (API key/PAT, no OAuth) for a backend -- e.g. an Atlassian API token for jira")
+  .action(async (backend: string) => {
+    // TICKETS_TOKEN_VALUE remains for non-interactive/scripted use (a provisioning
+    // script, `pass show jira | tickets auth set-token jira`) -- never accepted as a
+    // plain CLI argument, which would land in shell history the way this would not.
+    const value = process.env.TICKETS_TOKEN_VALUE ?? (await promptMaskedSecret(`Paste the "${backend}" token (input hidden): `));
+    if (!value) {
+      process.stderr.write("no token value provided — paste one at the prompt, or set TICKETS_TOKEN_VALUE for non-interactive use\n");
+      process.exitCode = 1;
+      return;
+    }
+    saveToken(backend, { accessToken: value });
+    printJson({ backend, status: "stored", note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token" });
+  });
+
 auth
   .command("status")
   .description("list backends with a locally stored delegated token")
@@ -417,6 +466,13 @@ auth
     printJson({ backend, status: "logged_out" });
   });
 
-program.parseAsync(process.argv).catch(() => {
-  process.exitCode = 1;
-});
+// Guarded so this module can be imported for introspection (e.g. a CLI-parity
+// test walking `program`'s registered commands) without executing real CLI
+// argument parsing against the importer's own process.argv.
+if (import.meta.main) {
+  program.parseAsync(process.argv).catch(() => {
+    process.exitCode = 1;
+  });
+}
+
+export { program };

package/src/config/config.ts

@@ -205,6 +205,7 @@ async function createRepository(
           accessToken: auth.token,
           cloudId: auth.extra.cloudId,
           project: cfg.project ?? env.JIRA_PROJECT,
+          configDir: configDir(),
         });
       }
       const baseUrl = cfg.url ?? env.JIRA_URL;
@@ -215,6 +216,7 @@ async function createRepository(
         email,
         token: auth.token,
         project: cfg.project ?? env.JIRA_PROJECT,
+        configDir: configDir(),
       });
     }
     default:

package/src/daemon/ops.ts

@@ -5,6 +5,7 @@
  * import from either side without pulling in bun:sqlite or Bun.serve.
  */
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+import type { Template } from "../domain/template.js";
 import type { TicketFocusState } from "./focus.js";
 
 export type TicketOperation =
@@ -24,6 +25,9 @@ export type TicketOperation =
   | "focus.pause"
   | "focus.unpause"
   | "focus.clear"
+  | "discover.fields"
+  | "discover.statuses"
+  | "discover.template"
   | "daemon.shutdown";
 
 export interface TicketOpInputs extends Record<TicketOperation, unknown> {
@@ -43,6 +47,9 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "focus.pause": { reason?: string };
   "focus.unpause": Record<string, never>;
   "focus.clear": Record<string, never>;
+  "discover.fields": { backend: string };
+  "discover.statuses": { backend: string };
+  "discover.template": { backend: string; project: string; issueType: string; sampleSize?: number };
   "daemon.shutdown": Record<string, never>;
 }
 
@@ -63,6 +70,9 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "focus.pause": { focus: TicketFocusState };
   "focus.unpause": { focus: TicketFocusState };
   "focus.clear": { cleared: boolean };
+  "discover.fields": { mappings: Record<string, string> };
+  "discover.statuses": { mappings: Record<string, string> };
+  "discover.template": { template: Template | null };
   "daemon.shutdown": { stopping: true };
 }
 
@@ -83,6 +93,9 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "focus.pause",
   "focus.unpause",
   "focus.clear",
+  "discover.fields",
+  "discover.statuses",
+  "discover.template",
   "daemon.shutdown",
 ];
 

package/src/daemon/server.ts

@@ -63,6 +63,11 @@ const handlers: { [Op in TicketOperation]: Handler<Op> } = {
   "focus.pause": async (deps, input) => ({ focus: deps.focusStore.pause(input.reason) }),
   "focus.unpause": async (deps) => ({ focus: deps.focusStore.unpause() }),
   "focus.clear": async (deps) => ({ cleared: deps.focusStore.clear() }),
+  "discover.fields": async (deps, input) => ({ mappings: await deps.service.discoverFields(input.backend) }),
+  "discover.statuses": async (deps, input) => ({ mappings: await deps.service.discoverStatuses(input.backend) }),
+  "discover.template": async (deps, input) => ({
+    template: (await deps.service.discoverTemplate(input.backend, input.project, input.issueType, input.sampleSize)) ?? null,
+  }),
   "daemon.shutdown": async (deps) => {
     // Deferred so this handler's own response has already been handed back
     // to Bun.serve before the process starts tearing down.

package/src/domain/issue.ts

@@ -45,6 +45,25 @@ export interface Comment {
   updatedAt?: string;
 }
 
+/** A link to another issue on the same backend (e.g. Jira's issuelinks: blocks, relates to, caused by). */
+export interface IssueLink {
+  /** The link type's own label from the backend's perspective of this issue, e.g. "blocks" or "is blocked by". */
+  type: string;
+  direction: "inward" | "outward";
+  targetRef: string;
+  targetKey: string;
+  targetTitle?: string;
+  targetStatus?: string;
+}
+
+/** A link to something outside the issue tracker entirely (e.g. Jira's "Web Links"/remote links: a PR, a doc). */
+export interface ExternalLink {
+  url: string;
+  title?: string;
+  /** The linked application's own name when the backend reports one, e.g. "GitHub". */
+  type?: string;
+}
+
 /** The unified representation of a work item, regardless of which platform it lives on. */
 export interface Issue {
   /** "backend:key", e.g. "jira:PROJ-42" or "github:#7". */
@@ -67,6 +86,14 @@ export interface Issue {
   createdAt?: string;
   updatedAt?: string;
   url?: string;
+  /** Versions this issue is fixed in/targeted for release in (Jira: fixVersions). */
+  fixVersions?: string[];
+  /** Links to other issues on the same backend (Jira: issuelinks). */
+  issueLinks?: IssueLink[];
+  /** Links to things outside the tracker entirely -- PRs, docs (Jira: "Web Links"/remote links). Only populated by get(), not list()/search(), to avoid one extra API call per result. */
+  externalLinks?: ExternalLink[];
+  /** Custom fields keyed by their backend display name (e.g. Jira's "Target Version"), resolved via that backend's field-discovery manifest. Empty until discovery has run at least once for the backend. */
+  customFields?: Record<string, string>;
 }
 
 export interface CreateInput {

package/src/domain/template.ts

@@ -0,0 +1,78 @@
+/**
+ * Description template discovery — ported from emcee's internal/domain/template.go
+ * (~/Workspace/emcee). Templates are discovered by sampling existing issues and
+ * extracting the section-header structure repeated across all of them, not
+ * hand-authored. Zero I/O: callers supply the sampled descriptions.
+ */
+
+export interface Template {
+  project: string;
+  issueType: string;
+  sections: string[];
+  body: string;
+}
+
+/** Strips a Jira-style {code}...{code} wrapper, keeping only its inner content. */
+const JIRA_CODE_BLOCK_RE = /\{code(?::[^}]*)?\}([\s\S]*?)\{code\}/;
+
+/**
+ * Returns the section headers ("Label:") that appear in every one of the given
+ * descriptions, in the order they appear in the first description. Returns
+ * undefined if no common sections are found (including on empty input).
+ */
+export function extractTemplateSections(descriptions: string[]): string[] | undefined {
+  if (descriptions.length === 0) return undefined;
+
+  const allSections: string[][] = [];
+  for (const desc of descriptions) {
+    const sections = extractSections(desc);
+    if (sections.length > 0) allSections.push(sections);
+  }
+  if (allSections.length === 0) return undefined;
+
+  let common = allSections[0]!;
+  for (const other of allSections.slice(1)) {
+    const set = new Set(other);
+    common = common.filter((s) => set.has(s));
+  }
+  return common.length > 0 ? common : undefined;
+}
+
+/** Produces the empty template body from a list of section headers. */
+export function buildTemplateBody(sections: string[] | undefined): string {
+  if (!sections || sections.length === 0) return "";
+  return sections.join("\n\n");
+}
+
+function extractSections(rawDesc: string): string[] {
+  let desc = rawDesc.trim();
+  if (desc === "") return [];
+
+  const codeMatch = desc.match(JIRA_CODE_BLOCK_RE);
+  if (codeMatch?.[1] !== undefined) desc = codeMatch[1].trim();
+
+  const sections: string[] = [];
+  const seen = new Set<string>();
+  for (const rawLine of desc.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "") continue;
+
+    const idx = line.indexOf(":");
+    if (idx < 2) continue;
+    const label = line.slice(0, idx + 1);
+    // Must start with an uppercase letter.
+    if (label[0]! < "A" || label[0]! > "Z") continue;
+    if (!isCleanLabel(label.slice(0, -1))) continue;
+    if (!seen.has(label)) {
+      seen.add(label);
+      sections.push(label);
+    }
+  }
+  return sections.length >= 2 ? sections : [];
+}
+
+const CLEAN_LABEL_RE = /^[\p{L}\p{N} /(),-]*$/u;
+
+function isCleanLabel(label: string): boolean {
+  return CLEAN_LABEL_RE.test(label);
+}

package/src/manifest/manifest.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-backend manifests — YAML files mapping semantic names to backend-specific
+ * values (e.g. Jira's "Target Version" -> "customfield_10855", or a Jira status
+ * name -> a domain Status). Ported from emcee's internal/manifest package
+ * (~/Workspace/emcee), same file layout and workflow:
+ *
+ *   1. Run discovery once per backend (adapter-specific: field/status listing).
+ *   2. The manifest is loaded from disk (no network) on subsequent reads.
+ *   3. Config-file entries override individual mappings.
+ *
+ * File location: $XDG_CONFIG_HOME/tickets/<kind>/<backend>.yaml (default
+ * ~/.config/tickets/<kind>/<backend>.yaml) -- kind is "fields" or "statuses".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+export interface Manifest {
+  backend: string;
+  /** ISO timestamp of the last successful discovery run. */
+  discoveredAt?: string;
+  mappings: Record<string, string>;
+}
+
+export function get(manifest: Manifest | undefined, key: string): string | undefined {
+  return manifest?.mappings[key];
+}
+
+/** Returns a new Manifest with overrides applied on top; does not mutate manifest. */
+export function merge(manifest: Manifest, overrides: Record<string, string>): Manifest {
+  return { ...manifest, mappings: { ...manifest.mappings, ...overrides } };
+}
+
+/** Builds a fresh Manifest from already-mapped semantic-name -> value pairs. */
+export function discover(backend: string, mappings: Record<string, string>): Manifest {
+  return { backend, discoveredAt: new Date().toISOString(), mappings: { ...mappings } };
+}
+
+export function defaultPath(kind: string, backend: string, configDir: string): string {
+  return join(configDir, kind, `${backend}.yaml`);
+}
+
+/** Reads a backend's manifest; returns an empty one (not an error) if the file doesn't exist yet. */
+export function load(kind: string, backend: string, configDir: string): Manifest {
+  const path = defaultPath(kind, backend, configDir);
+  if (!existsSync(path)) return { backend, mappings: {} };
+  const data = readFileSync(path, "utf8");
+  const parsed = parseYaml(data) as Partial<Manifest> | undefined;
+  return { backend, discoveredAt: parsed?.discoveredAt, mappings: parsed?.mappings ?? {} };
+}
+
+/** Writes a backend's manifest, creating the <kind> subdirectory if needed. Overwrites any existing file. */
+export function save(kind: string, backend: string, configDir: string, manifest: Manifest): void {
+  const dir = join(configDir, kind);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const header =
+    `# Tickets ${kind} manifest — ${backend}\n` +
+    `# Run \`tickets discover ${kind === "fields" ? "fields" : "statuses"} --backend ${backend}\` to regenerate.\n` +
+    "# Entries in config.yaml override individual mappings.\n\n";
+  const body = stringifyYaml({ backend, discoveredAt: manifest.discoveredAt, mappings: manifest.mappings });
+  writeFileSync(defaultPath(kind, backend, configDir), header + body, { mode: 0o600 });
+}

package/src/ports/repository.ts

@@ -3,6 +3,7 @@
  * The application layer depends only on these interfaces, never on a concrete adapter.
  */
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+import type { Template } from "../domain/template.js";
 
 export interface IssueRepository {
   /** Backend identifier used in refs, e.g. "github", "gitlab", "jira". */
@@ -25,3 +26,35 @@ export interface CommentCapable {
 export function hasComments(repo: IssueRepository): repo is IssueRepository & CommentCapable {
   return typeof (repo as Partial<CommentCapable>).listComments === "function";
 }
+
+/**
+ * Optional capability — discovers a backend's custom field display names ->
+ * IDs (e.g. Jira's "Target Version" -> "customfield_10855") and persists them
+ * to a manifest for reuse without a repeat network call. Only Jira supports
+ * this today (GitHub/GitLab have no tenant-specific custom field IDs).
+ */
+export interface FieldDiscoverable {
+  discoverFields(): Promise<Record<string, string>>;
+}
+
+export function hasFieldDiscovery(repo: IssueRepository): repo is IssueRepository & FieldDiscoverable {
+  return typeof (repo as Partial<FieldDiscoverable>).discoverFields === "function";
+}
+
+/** Optional capability — discovers a backend's status names -> domain Status and persists them to a manifest. */
+export interface StatusDiscoverable {
+  discoverStatuses(): Promise<Record<string, string>>;
+}
+
+export function hasStatusDiscovery(repo: IssueRepository): repo is IssueRepository & StatusDiscoverable {
+  return typeof (repo as Partial<StatusDiscoverable>).discoverStatuses === "function";
+}
+
+/** Optional capability — discovers a reusable description template by sampling existing issues. */
+export interface TemplateDiscoverable {
+  discoverTemplate(project: string, issueType: string, sampleSize?: number): Promise<Template | undefined>;
+}
+
+export function hasTemplateDiscovery(repo: IssueRepository): repo is IssueRepository & TemplateDiscoverable {
+  return typeof (repo as Partial<TemplateDiscoverable>).discoverTemplate === "function";
+}