@danypops/tickets 0.2.1 → 0.4.0

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,19 +171,59 @@ tickets auth status
 tickets auth logout github
 ```
 
+### GitHub: reuse an already-authenticated `gh` CLI session
+
+`tickets auth login --backend github --gh-cli [account]` skips the device
+flow (and the `GITHUB_OAUTH_CLIENT_ID` App registration it needs) entirely
+by reading `gh auth token` instead — never re-implement a vendor CLI's own
+auth, just consume its result via its own documented, stable interface.
+Works whether `gh` stores its token in the OS keyring or a legacy
+plaintext file. Omit `account` for `gh`'s current active account, or name
+one of `gh`'s own multiple authenticated accounts (`gh auth status` lists
+them) — pair with a distinct `--backend` name to register each as its own
+tickets backend:
+
+```bash
+tickets auth login --backend github-personal --gh-cli DanyPops
+tickets auth login --backend github-work --gh-cli work-account
+```
+
 A stored, still-fresh delegated token always takes precedence over a static
 config/env token for that backend. Tokens are written to
 `$XDG_STATE_HOME/tickets/oauth/<backend>.json`, mode `0600`, and are never
 printed by any command. **Restart the daemon** after logging in so it picks
 up the new credential — `buildRepositories()` runs once at daemon startup.
 
+### Optional: credentials via Enigma
+
+If an [Enigma](https://github.com/DanyPops/enigma) vault is running,
+tickets checks it first on every request, ahead of a stored delegated token
+and any static config/env token — a credential Enigma rotates is picked up
+on the very next call, no daemon restart needed. Purely additive: tickets
+works identically with no Enigma running at all.
+
+Register tickets as a scoped Enigma client (once), then pass the printed
+token to the daemon via `ENIGMA_CLIENT_TOKEN`:
+
+```bash
+enigma client add tickets --backends github,gitlab,jira
+# -> prints a token once; export it wherever the tickets daemon is started
+export ENIGMA_CLIENT_TOKEN=<printed token>
+```
+
+Without `ENIGMA_CLIENT_TOKEN`, tickets falls back to Enigma's shared
+admin-token file if one exists at `$XDG_STATE_HOME/enigma/token` — fine for
+a single-user machine where every local daemon is equally trusted, but a
+scoped client token is the least-privilege default.
+
 ## The `pi-tickets` extension
 
-Published as `@danypops/pi-tickets`. `../../extensions/pi-tickets/` (this repo's workspace member) registers a single `tickets` tool for
+Published as `@danypops/pi-tickets`. `../pi-tickets/` (this repo's workspace member) registers a single `tickets` tool for
 [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
@@ -196,7 +250,7 @@ To use it, add it to pi's `settings.json`:
 ```
 
 Or, for local development against this monorepo, point at the workspace
-member directory instead: `{ "packages": ["/path/to/tickets/extensions/pi-tickets"] }`.
+member directory instead: `{ "packages": ["/path/to/tickets/packages/pi-tickets"] }`.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@danypops/daemon-kit": "^0.3.0",
+    "@danypops/enigma-client": "^0.3.0",
     "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.0",
     "jira.js": "^5.4.0",

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[]) {
@@ -23,12 +30,23 @@ export class NotSupportedError extends Error {
 }
 
 export class TicketService {
-  constructor(private readonly repos: Record<string, IssueRepository>) {}
+  constructor(private repos: Record<string, IssueRepository>) {}
 
   backends(): string[] {
     return Object.keys(this.repos);
   }
 
+  /**
+   * Swaps the live backend set atomically. A backend newly configured in
+   * Enigma (or removed) becomes usable on the next call without
+   * reconstructing the service or restarting the daemon -- see
+   * config.ts's createBackendRefreshTask, the maintenance task that calls
+   * this on a schedule.
+   */
+  setRepos(repos: Record<string, IssueRepository>): void {
+    this.repos = repos;
+  }
+
   private repo(backend: string): IssueRepository {
     const repo = this.repos[backend];
     if (!repo) throw new UnknownBackendError(backend, this.backends());
@@ -81,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/gh-cli.ts

@@ -0,0 +1,46 @@
+/**
+ * Optional shortcut: reuse an already-authenticated `gh` CLI session instead
+ * of running tickets' own OAuth device flow. Never re-implement a vendor
+ * CLI's own auth, just delegate to it and consume the result.
+ *
+ * Deliberately shells out to `gh auth token` rather than reading gh's own
+ * credential storage directly: gh's default "secure storage" keeps the
+ * token in the OS keyring (Secret Service/libsecret on Linux, Keychain on
+ * macOS, Credential Manager on Windows) under an internal, undocumented
+ * schema -- not a published contract. `gh auth token` is gh's own
+ * documented, stable interface for exactly this scripting use case,
+ * abstracting over wherever the credential actually lives. The token never
+ * touches this process's own stdout/log output, only the returned string.
+ */
+export type GhCliTokenResult = { ok: true; token: string } | { ok: false; reason: string };
+
+export interface SpawnLike {
+	(command: string[]): { stdout: ReadableStream<Uint8Array> | number; exited: Promise<number> };
+}
+
+const defaultSpawn: SpawnLike = (command) => Bun.spawn(command, { stdout: "pipe" });
+
+/**
+ * Reads `gh auth token`'s output for the given account (gh's own `--user`
+ * flag; omit to use gh's currently active account). Never mints, never
+ * prompts, never falls back to a device flow itself.
+ */
+export async function readGhCliToken(user?: string, spawn: SpawnLike = defaultSpawn): Promise<GhCliTokenResult> {
+	const command = user ? ["gh", "auth", "token", "--user", user] : ["gh", "auth", "token"];
+	let proc: ReturnType<SpawnLike>;
+	try {
+		proc = spawn(command);
+	} catch {
+		return { ok: false, reason: "gh CLI not found -- install it (cli.github.com) or use a different login method" };
+	}
+	const [stdout, code] = await Promise.all([
+		proc.stdout instanceof ReadableStream ? new Response(proc.stdout).text() : Promise.resolve(""),
+		proc.exited,
+	]);
+	if (code !== 0) {
+		return { ok: false, reason: user ? `gh CLI has no authenticated account named "${user}" -- run \`gh auth login\` first` : "gh CLI is not authenticated -- run `gh auth login` first" };
+	}
+	const token = stdout.trim();
+	if (!token) return { ok: false, reason: "gh auth token returned no token" };
+	return { ok: true, token };
+}

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { parseStatus } from "../domain/issue.js";
 import { createTicketsClient, type TicketsRpcClient } from "../client/tickets-client.js";
 import { openUrl } from "../auth/browser.js";
 import { loginWithGitHubDeviceFlow } from "../auth/github-oauth.js";
+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";
@@ -194,6 +195,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
@@ -305,12 +337,20 @@ auth
   .option("--client-secret <secret>", "OAuth client secret (Jira only — GitHub/GitLab device flow needs none)")
   .option("--url <baseUrl>", "self-managed GitLab URL (defaults to gitlab.com)")
   .option("--scope <scope>", "space-delimited OAuth scope override")
+  .option("--gh-cli [account]", "github only: reuse an already-authenticated gh CLI session instead of the device flow (omit value for gh's active account)")
   .action(async (opts) => {
     const type = opts.type ?? opts.backend;
     try {
+      if (type === "github" && opts.ghCli !== undefined) {
+        const result = await readGhCliToken(opts.ghCli === true ? undefined : opts.ghCli);
+        if (!result.ok) throw new Error(result.reason);
+        saveToken(opts.backend, { accessToken: result.token });
+        printJson({ backend: opts.backend, status: "authorized", via: "gh-cli", note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token" });
+        return;
+      }
       if (type === "github") {
         const clientId = opts.clientId ?? process.env.GITHUB_OAUTH_CLIENT_ID;
-        if (!clientId) throw new Error("--client-id or GITHUB_OAUTH_CLIENT_ID is required");
+        if (!clientId) throw new Error("--client-id or GITHUB_OAUTH_CLIENT_ID is required (or pass --gh-cli [account] to reuse an already-authenticated gh CLI session instead)");
         const token = await loginWithGitHubDeviceFlow({
           clientId,
           scope: opts.scope,
@@ -408,6 +448,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

@@ -7,12 +7,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import type { MaintenanceTask } from "@danypops/daemon-kit/daemon";
+import type { Logger } from "@danypops/daemon-kit/logging";
 import { GitHubRepository } from "../adapters/github.js";
 import { GitLabRepository } from "../adapters/gitlab.js";
 import { JiraRepository } from "../adapters/jira.js";
 import type { IssueRepository } from "../ports/repository.js";
+import type { TicketService } from "../application/service.js";
 import { isTokenFresh, loadToken } from "../auth/token-store.js";
-import { type TryEnigmaCredential, tryEnigmaCredential } from "../auth/enigma-source.js";
+import { type TryEnigmaCredential, tryEnigmaCredential } from "@danypops/enigma-client";
 
 export interface BackendConfig {
   /** Adapter type: "github" | "gitlab" | "jira". Falls back to the config key when omitted. */
@@ -59,7 +62,7 @@ function resolveToken(cfg: BackendConfig, env: NodeJS.ProcessEnv, envFallback: s
  * Resolution order, highest priority first: (1) a running Enigma vault, if
  * one happens to be configured for this backend — entirely optional, never a
  * hard dependency, and bounded so Tickets never waits long for it (see
- * auth/enigma-source.ts); (2) a locally stored, still-fresh delegated OAuth
+ * @danypops/enigma-client); (2) a locally stored, still-fresh delegated OAuth
  * token (see auth/token-store.ts, populated by `tickets auth login`); (3) a
  * static config/env PAT. (1) is additive to the pre-Enigma precedence this
  * project already followed for GitHub, GitLab, and Jira — see RESEARCH.md
@@ -74,7 +77,10 @@ export async function preferredAuth(
   envFallback: string,
   tryEnigma: TryEnigmaCredential = tryEnigmaCredential,
 ): Promise<{ token: string | undefined; oauth: boolean; extra?: Record<string, string> }> {
-  const fromEnigma = await tryEnigma(name, { env });
+  // ENIGMA_CLIENT_TOKEN is this daemon's own registered-client token (`enigma client add`) --
+  // Enigma's shared admin-token file is deliberately unreadable outside its own service
+  // account, so tickets must present its own scoped token to get anything back at all.
+  const fromEnigma = await tryEnigma(name, { env, token: env.ENIGMA_CLIENT_TOKEN });
   if (fromEnigma) return { token: fromEnigma.accessToken, oauth: true, extra: fromEnigma.extra };
 
   const stored = loadToken(name, { env });
@@ -118,6 +124,50 @@ export async function buildRepositories(
   return repos;
 }
 
+export type BuildRepositories = typeof buildRepositories;
+
+/**
+ * Re-runs buildRepositories on a schedule and swaps the result into a live
+ * TicketService via setRepos -- the counterpart to token-provider.ts's
+ * per-request freshness in Pipes, one level up: this refreshes which
+ * backends exist at all, not just an existing backend's token. A backend
+ * enigma login just made available becomes callable without a daemon
+ * restart; a removed one stops being offered. A failed refresh (Enigma
+ * unreachable, transient) keeps the previous backend set rather than
+ * wiping it out.
+ */
+export function createBackendRefreshTask(
+  service: TicketService,
+  config: Config,
+  buildRepos: BuildRepositories,
+  intervalMs: number,
+  logger?: Logger,
+): MaintenanceTask {
+  return {
+    name: "backend-refresh",
+    intervalMs,
+    run: async () => {
+      const before = new Set(service.backends());
+      let fresh: Record<string, IssueRepository>;
+      try {
+        fresh = await buildRepos(config);
+      } catch (error) {
+        logger?.warn("backend refresh failed, keeping previous backend set", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+      }
+      service.setRepos(fresh);
+      const after = new Set(Object.keys(fresh));
+      const added = [...after].filter((backend) => !before.has(backend));
+      const removed = [...before].filter((backend) => !after.has(backend));
+      if (added.length > 0 || removed.length > 0) {
+        logger?.info("backend set changed", { added, removed });
+      }
+    },
+  };
+}
+
 async function createRepository(
   name: string,
   type: string,
@@ -155,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;
@@ -165,6 +216,7 @@ async function createRepository(
         email,
         token: auth.token,
         project: cfg.project ?? env.JIRA_PROJECT,
+        configDir: configDir(),
       });
     }
     default:

package/src/daemon/bootstrap.ts

@@ -11,7 +11,7 @@ import { ensureAuthToken, type PathEnvironment, resolveDaemonPaths } from "@dany
 import { checkpoint, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
 import type { StartDaemonOptions } from "@danypops/daemon-kit/daemon";
 import { TicketService } from "../application/service.js";
-import { buildRepositories, type Config, loadConfig } from "../config/config.js";
+import { buildRepositories, type BuildRepositories, type Config, createBackendRefreshTask, loadConfig } from "../config/config.js";
 import type { IssueRepository } from "../ports/repository.js";
 import { FOCUS_MIGRATIONS, FocusStore } from "./focus.js";
 import { Ledger, LEDGER_MIGRATIONS } from "./ledger.js";
@@ -22,12 +22,20 @@ import { createSyncTask } from "./poller.js";
 export interface BootstrapOptions {
   pathEnv?: PathEnvironment;
   config?: Config;
-  /** Injected directly in tests instead of building from config/env. */
+  /**
+   * Injected directly in tests instead of building from config/env. Also
+   * disables the live backend-refresh task -- an injected repo set is a
+   * fixed test fixture, not something to re-resolve from Enigma/config.
+   */
   repos?: Record<string, IssueRepository>;
+  /** Injected in tests to control which backends a refresh cycle resolves to, without a real Enigma/GitHub/GitLab/Jira. */
+  buildRepositories?: BuildRepositories;
   version?: string;
   logger?: Logger;
   syncIntervalMs?: number;
   checkpointIntervalMs?: number;
+  /** How often the live backend set re-resolves from config/env/Enigma. Ignored when repos is injected. */
+  backendRefreshIntervalMs?: number;
   /**
    * Overrides the daemon.shutdown op's effect. Defaults to sending this
    * process SIGTERM, which daemon-kit's runDaemonProcess already handles
@@ -47,6 +55,7 @@ export interface BootstrappedDaemon {
 
 const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_CHECKPOINT_INTERVAL_MS = 10 * 60_000;
+const DEFAULT_BACKEND_REFRESH_INTERVAL_MS = 30_000;
 
 export async function bootstrap(opts: BootstrapOptions = {}): Promise<BootstrappedDaemon> {
   const paths = resolveDaemonPaths(TICKETS_DAEMON_NAMES, opts.pathEnv);
@@ -55,7 +64,9 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
   const ledger = new Ledger(db);
   const focusStore = new FocusStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
-  const repos = opts.repos ?? (await buildRepositories(opts.config ?? loadConfig()));
+  const config = opts.config ?? loadConfig();
+  const buildRepos = opts.buildRepositories ?? buildRepositories;
+  const repos = opts.repos ?? (await buildRepos(config));
   const service = new TicketService(repos);
   const version = opts.version ?? "0.0.0-dev";
 
@@ -64,12 +75,17 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     handlePath: paths.handle,
     logger,
     maintenanceTasks: [
-      createSyncTask(service, ledger, Object.keys(repos), opts.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, logger),
+      createSyncTask(service, ledger, opts.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, logger),
       {
         name: "checkpoint",
         intervalMs: opts.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS,
         run: () => checkpoint(db),
       },
+      // Only when repos came from real config/env/Enigma resolution -- an
+      // injected test fixture (opts.repos) has no config to re-resolve from.
+      ...(opts.repos === undefined
+        ? [createBackendRefreshTask(service, config, buildRepos, opts.backendRefreshIntervalMs ?? DEFAULT_BACKEND_REFRESH_INTERVAL_MS, logger)]
+        : []),
     ],
     buildApp: () =>
       buildApp({

package/src/daemon/ops.ts

@@ -1,10 +1,11 @@
 /**
  * The RPC protocol shared between the tickets daemon (server.ts, running under
- * Bun) and every client (cli/index.ts, extensions/pi-tickets, running under
+ * Bun) and every client (cli/index.ts, packages/pi-tickets, running under
  * whatever consumes this package). Pure types, zero runtime imports, safe to
  * 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/poller.ts

@@ -35,10 +35,16 @@ export async function syncOnce(
   return results;
 }
 
+/**
+ * Reads the backend list fresh from service.backends() on every tick,
+ * rather than a list frozen at task-creation time -- a backend the
+ * refresh task (config.ts's createBackendRefreshTask) just added to the
+ * service is synced on this task's very next run, no daemon restart or
+ * task rebuild needed.
+ */
 export function createSyncTask(
   service: TicketService,
   ledger: Ledger,
-  backends: string[],
   intervalMs: number,
   logger?: Logger,
 ): MaintenanceTask {
@@ -46,7 +52,7 @@ export function createSyncTask(
     name: "ledger-sync",
     intervalMs,
     run: async () => {
-      await syncOnce(service, ledger, backends, logger);
+      await syncOnce(service, ledger, service.backends(), logger);
     },
   };
 }

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";
+}

package/src/auth/enigma-source.ts

@@ -1,65 +0,0 @@
-/**
- * Optional credential source: a running Enigma vault (github.com/DanyPops/enigma),
- * if one happens to be configured on this machine. Purely additive — Tickets
- * has never imported Enigma's package and never will; this talks to Enigma's
- * loopback HTTP API using only @danypops/daemon-kit, which Tickets already
- * depends on for its own daemon plumbing. Enigma's discovery contract is three
- * stable, documented constants (its state-directory name and its handle/token
- * filenames), not an import of Enigma's own source.
- *
- * Never creates Enigma's handle or token files — those are strictly Enigma's
- * own job on its first boot. A consumer that could mint them would be a real
- * security problem, not a convenience. Absence of either file means "Enigma
- * isn't running or isn't configured for this backend," not an error: every
- * failure path here resolves `undefined` rather than throwing, and the whole
- * attempt is time-bounded so a slow or hung Enigma can never stall Tickets'
- * own startup.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { readDaemonHandle, resolveDaemonPaths } from "@danypops/daemon-kit/paths";
-import { createVaultClient, type RefreshableAccessToken } from "@danypops/daemon-kit/vault";
-
-const ENIGMA_STATE_DIRECTORY_NAME = "enigma";
-const ENIGMA_HANDLE_FILENAME = "handle.json";
-const ENIGMA_TOKEN_FILENAME = "token";
-const ENIGMA_LOOKUP_TIMEOUT_MS = 500;
-
-export interface TryEnigmaCredentialEnv {
-	env?: Record<string, string | undefined>;
-	/** Injectable for tests; production default is the real fetch, bounded by AbortSignal.timeout. */
-	fetchImpl?: typeof fetch;
-}
-
-export type TryEnigmaCredential = (backend: string, opts?: TryEnigmaCredentialEnv) => Promise<RefreshableAccessToken | undefined>;
-
-export const tryEnigmaCredential: TryEnigmaCredential = async (backend, opts = {}) => {
-	const env = opts.env ?? process.env;
-	const paths = resolveDaemonPaths(
-		{ stateDirectoryName: ENIGMA_STATE_DIRECTORY_NAME, handleFilename: ENIGMA_HANDLE_FILENAME, tokenFilename: ENIGMA_TOKEN_FILENAME, databaseFilename: "", systemdUnitName: "" },
-		{ env },
-	);
-
-	const handle = readDaemonHandle(paths.handle);
-	if (!handle) return undefined; // Enigma isn't running -- not an error, just not present
-
-	if (!existsSync(paths.token)) return undefined; // never ensureAuthToken here -- read-only, never mint Enigma's own token
-	let token: string;
-	try {
-		token = readFileSync(paths.token, "utf8").trim();
-	} catch {
-		return undefined;
-	}
-
-	const fetchImpl = opts.fetchImpl ?? fetch;
-	const client = createVaultClient({
-		baseUrl: `http://${handle.host}:${handle.port}`,
-		authToken: token,
-		fetchImpl: (url, init) => fetchImpl(url, { ...init, signal: AbortSignal.timeout(ENIGMA_LOOKUP_TIMEOUT_MS) }),
-	});
-
-	try {
-		return await client.getCredentials(backend);
-	} catch {
-		return undefined; // unreachable, timed out, or any other transport failure -- fall through silently
-	}
-};