jiradc-cli 1.0.31 → 1.0.33

package/README.md

@@ -17,6 +17,11 @@ export JIRA_TOKEN="your-personal-access-token" # HTTP Access Token from Jira
 
 ## Breaking changes in this release
 
+- **`field options` is removed.** It called a Jira 9 endpoint and returned 404 for every field on Jira 8.x. Jira scopes a custom field's options to a context, so there is no context-free replacement — use `issue createmeta --project <key> --type <name>` (create screen), `issue editmeta <key>` (edit screen), or `issue transitions <key>` (transition screen).
+- **`issue transitions` no longer reports `required`** on screen fields. Jira reports field-configuration requiredness there, which cannot see the workflow validator that actually gates the transition, so it returned `false` for fields that then rejected the transition. Supply everything in a transition's `fields` block. (`required` from `createmeta`/`editmeta` reflects field configuration and is reliable.)
+- **`issue get` / `issue search` return issue-picker custom fields as a bare key string** (or an array of keys) instead of the whole nested issue. `fields.customfield_NNNNN.key` becomes `fields.customfield_NNNNN`.
+- **`issue create --custom-fields` is now `--fields`**, matching `issue update`. The old name still works as a deprecated alias.
+- **Argument mistakes now exit 2/3/6** (`usage`/`not_found`/`auth`) instead of 1.
 - `issue transitions` now returns a bare JSON array of transitions (previously wrapped in `{ transitions: [...] }`). Each transition is reduced to `{ id, name, to, fields? }` — verbose fields like `to.iconUrl`, `to.statusCategory`, `isGlobal`, `isInitial`, `isConditional`, `hasScreen` are stripped.
 - `component list` now requires `--project <key>` instead of a positional `<projectKey>` argument.
 - `issue link-epic` is now variadic on the issue argument: `link-epic <issueKey...> --epic <epicKey>`. Single-issue calls keep working.
@@ -27,88 +32,89 @@ All commands output JSON. Add `--pretty` to pretty-print.
 
 ### issue
 
-| Command | Description |
-|---------|-------------|
-| `jiradc issue get <key>` | Get issue details (`--fields` to select, `--expand` for changelog/transitions) |
-| `jiradc issue search <jql>` | Search issues with JQL |
-| `jiradc issue create` | Create an issue (`--project`, `--type`, `--summary`, `--description`, `--custom-fields`) |
-| `jiradc issue update <key>` | Update an issue (`--summary`, `--description`, `--priority`, `--assignee`, `--labels`, `--components`, `--fix-versions`, or `--fields` JSON) |
-| `jiradc issue delete <key>` | Delete an issue |
-| `jiradc issue assign <key> <user>` | Assign issue (user can be a username, `me`, or `none` to unassign) |
-| `jiradc issue transition <key>` | Transition issue to a new status (`--to` accepts ID or status name, `--comment` to add a note) |
-| `jiradc issue transitions <key>` | List available transitions |
-| `jiradc issue comment add <key>` | Add a comment (`--body`) |
-| `jiradc issue comment edit <key>` | Edit a comment (`--id`, `--body`) |
-| `jiradc issue comment delete <key>` | Delete a comment (`--id`) |
-| `jiradc issue link <key> <targetKey>` | Link two issues (`--type` link type name) |
-| `jiradc issue unlink <linkId>` | Remove a link |
-| `jiradc issue link-types` | List available link types |
-| `jiradc issue link-epic <keys...>` | Link one or more issues to an epic (`--epic <epicKey>`) |
-| `jiradc issue worklog add <key>` | Add a work log entry (`--time`, `--comment`, `--started`) |
-| `jiradc issue worklog list <key>` | Get work log entries |
-| `jiradc issue worklog edit <key>` | Update a work log entry (`--id`, `--time`, `--comment`, `--started`, `--adjust-estimate`, `--new-estimate`) |
-| `jiradc issue worklog delete <key>` | Delete a work log entry (`--id`, `--adjust-estimate`, `--new-estimate`, `--increase-by`) |
-| `jiradc issue changelog <key>` | Get issue changelog |
-| `jiradc issue batch-changelog` | Get changelog for multiple issues (`--keys`) |
-| `jiradc issue clone <key>` | Clone an issue with subtasks |
-| `jiradc issue batch-create` | Create multiple issues from JSON |
-| `jiradc issue dev-status <key>` | Get development status (branches, PRs, commits) |
+| Command                               | Description                                                                                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jiradc issue get <key>`              | Get issue details (`--fields` to select, `--expand` for changelog/transitions)                                                               |
+| `jiradc issue search <jql>`           | Search issues with JQL                                                                                                                       |
+| `jiradc issue create`                 | Create an issue (`--project`, `--type`, `--summary`, `--description`, `--custom-fields`)                                                     |
+| `jiradc issue update <key>`           | Update an issue (`--summary`, `--description`, `--priority`, `--assignee`, `--labels`, `--components`, `--fix-versions`, or `--fields` JSON) |
+| `jiradc issue delete <key>`           | Delete an issue                                                                                                                              |
+| `jiradc issue assign <key> <user>`    | Assign issue (user can be a username, `me`, or `none` to unassign)                                                                           |
+| `jiradc issue transition <key>`       | Transition issue to a new status (`--to` accepts ID or status name, `--comment` to add a note)                                               |
+| `jiradc issue transitions <key>`      | List available transitions (with any fields their screens require)                                                                           |
+| `jiradc issue createmeta`             | Fields a new issue accepts, with allowed values (`--project`, `--type`)                                                                      |
+| `jiradc issue editmeta <key>`         | Fields an existing issue's edit screen accepts, with allowed values                                                                          |
+| `jiradc issue comment add <key>`      | Add a comment (`--body`)                                                                                                                     |
+| `jiradc issue comment edit <key>`     | Edit a comment (`--id`, `--body`)                                                                                                            |
+| `jiradc issue comment delete <key>`   | Delete a comment (`--id`)                                                                                                                    |
+| `jiradc issue link <key> <targetKey>` | Link two issues (`--type` link type name)                                                                                                    |
+| `jiradc issue unlink <linkId>`        | Remove a link                                                                                                                                |
+| `jiradc issue link-types`             | List available link types                                                                                                                    |
+| `jiradc issue link-epic <keys...>`    | Link one or more issues to an epic (`--epic <epicKey>`)                                                                                      |
+| `jiradc issue worklog add <key>`      | Add a work log entry (`--time`, `--comment`, `--started`)                                                                                    |
+| `jiradc issue worklog list <key>`     | Get work log entries                                                                                                                         |
+| `jiradc issue worklog edit <key>`     | Update a work log entry (`--id`, `--time`, `--comment`, `--started`, `--adjust-estimate`, `--new-estimate`)                                  |
+| `jiradc issue worklog delete <key>`   | Delete a work log entry (`--id`, `--adjust-estimate`, `--new-estimate`, `--increase-by`)                                                     |
+| `jiradc issue changelog <key>`        | Get issue changelog                                                                                                                          |
+| `jiradc issue batch-changelog`        | Get changelog for multiple issues (`--keys`)                                                                                                 |
+| `jiradc issue clone <key>`            | Clone an issue with subtasks                                                                                                                 |
+| `jiradc issue batch-create`           | Create multiple issues from JSON                                                                                                             |
+| `jiradc issue dev-status <key>`       | Get development status (branches, PRs, commits)                                                                                              |
 
 #### issue attachment
 
-| Command | Description |
-|---------|-------------|
-| `jiradc issue attachment list <key>` | List attachments |
+| Command                                                 | Description                    |
+| ------------------------------------------------------- | ------------------------------ |
+| `jiradc issue attachment list <key>`                    | List attachments               |
 | `jiradc issue attachment download <key> <attachmentId>` | Download a specific attachment |
-| `jiradc issue attachment download-all <key>` | Download all attachments |
-| `jiradc issue attachment upload <key> <files...>` | Upload files |
-| `jiradc issue attachment delete <attachmentId>` | Delete an attachment |
+| `jiradc issue attachment download-all <key>`            | Download all attachments       |
+| `jiradc issue attachment upload <key> <files...>`       | Upload files                   |
+| `jiradc issue attachment delete <attachmentId>`         | Delete an attachment           |
 
 ### project
 
-| Command | Description |
-|---------|-------------|
-| `jiradc project list` | List projects |
+| Command                         | Description                 |
+| ------------------------------- | --------------------------- |
+| `jiradc project list`           | List projects               |
 | `jiradc project versions <key>` | List versions for a project |
 
 ### component
 
-| Command | Description |
-|---------|-------------|
-| `jiradc component list` | List components for a project (`--project <key>`) |
-| `jiradc component get <id>` | Get a component by ID |
-| `jiradc component create` | Create a component (`--project`, `--name`, `--description`, `--lead`) |
-| `jiradc component update <id>` | Update a component |
-| `jiradc component issue-count <id>` | Get the number of issues using a component |
+| Command                             | Description                                                           |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| `jiradc component list`             | List components for a project (`--project <key>`)                     |
+| `jiradc component get <id>`         | Get a component by ID                                                 |
+| `jiradc component create`           | Create a component (`--project`, `--name`, `--description`, `--lead`) |
+| `jiradc component update <id>`      | Update a component                                                    |
+| `jiradc component issue-count <id>` | Get the number of issues using a component                            |
 
 ### board
 
-| Command | Description |
-|---------|-------------|
-| `jiradc board list` | List boards (`--project`, `--type`: scrum/kanban/simple, `--name`) |
-| `jiradc board issues <boardId>` | Get issues on a board |
+| Command                         | Description                                                        |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `jiradc board list`             | List boards (`--project`, `--type`: scrum/kanban/simple, `--name`) |
+| `jiradc board issues <boardId>` | Get issues on a board                                              |
 
 ### sprint
 
-| Command | Description |
-|---------|-------------|
-| `jiradc sprint list <boardId>` | List sprints (`--state`: future/active/closed) |
-| `jiradc sprint issues <boardId> <sprintId>` | Get issues in a sprint |
-| `jiradc sprint create <boardId>` | Create a sprint |
-| `jiradc sprint update <sprintId>` | Update a sprint |
-| `jiradc sprint delete <sprintId>` | Delete a sprint (returns its issues to the backlog) |
+| Command                                     | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| `jiradc sprint list <boardId>`              | List sprints (`--state`: future/active/closed)      |
+| `jiradc sprint issues <boardId> <sprintId>` | Get issues in a sprint                              |
+| `jiradc sprint create <boardId>`            | Create a sprint                                     |
+| `jiradc sprint update <sprintId>`           | Update a sprint                                     |
+| `jiradc sprint delete <sprintId>`           | Delete a sprint (returns its issues to the backlog) |
 
 ### field
 
-| Command | Description |
-|---------|-------------|
-| `jiradc field search` | Search for fields (`--query`, `--type`: custom/system) |
-| `jiradc field options <fieldKey>` | Get allowed values for a field (`--project`, `--issue-type`) |
+| Command                         | Description                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `jiradc field search <keyword>` | Search for fields by name or ID (returns name + type, **not** allowed values) |
 
 ### user
 
-| Command | Description |
-|---------|-------------|
+| Command          | Description           |
+| ---------------- | --------------------- |
 | `jiradc user me` | Get current user info |
 
 ## Pagination

package/dist/index.js

@@ -239,6 +239,7 @@ var CliAuthError = class extends Error {
 };
 var NOT_FOUND_RECOVERY = "Verify the id/key, then check your access.";
 var NOT_FOUND_MESSAGE = "Not found: it may not exist, or you may not have permission to see it";
+var USAGE_RECOVERY = "Check the command syntax and flags; run the command with --help.";
 var CliNotFoundError = class extends Error {
   recovery;
   constructor(message, recovery = NOT_FOUND_RECOVERY) {
@@ -247,6 +248,16 @@ var CliNotFoundError = class extends Error {
     this.recovery = recovery;
   }
 };
+var CliUsageError = class extends Error {
+  recovery;
+  detail;
+  constructor(message, recovery = USAGE_RECOVERY, detail) {
+    super(message);
+    this.name = "CliUsageError";
+    this.recovery = recovery;
+    this.detail = detail;
+  }
+};
 var SubcommandRequiredError = class extends Error {
   subcommands;
   constructor(commandPath3, subcommands) {
@@ -263,10 +274,55 @@ var TYPE_EXIT = {
   auth: EXIT.AUTH,
   rate_limited: EXIT.GENERIC,
   server: EXIT.GENERIC,
+  timeout: EXIT.GENERIC,
   network: EXIT.GENERIC,
   unknown: EXIT.GENERIC
 };
-var NETWORK_CODES = ["ENOTFOUND", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT"];
+var TRANSPORT_CODES = {
+  /** Our own timeout fired: connected (or tried to), no response in time. */
+  readTimeout: ["ECONNABORTED"],
+  /** The OS gave up establishing the connection. */
+  connectTimeout: ["ETIMEDOUT"],
+  /** No such host, or DNS itself is unavailable. */
+  unresolved: ["ENOTFOUND", "EAI_AGAIN"],
+  /** Host is there, nothing is listening on that port. */
+  refused: ["ECONNREFUSED"],
+  /** Established, then died mid-flight. */
+  dropped: ["ECONNRESET", "EPIPE"]
+};
+function humanMs(ms) {
+  return ms % 1e3 === 0 ? `${ms / 1e3}s` : `${ms}ms`;
+}
+function targetHost(err) {
+  const config = err?.config;
+  const raw = config?.baseURL ?? config?.url;
+  if (raw === void 0 || raw === "")
+    return void 0;
+  try {
+    return new URL(raw).host;
+  } catch {
+    return void 0;
+  }
+}
+function configuredTimeoutMs(err) {
+  const t = err?.config?.timeout;
+  return typeof t === "number" && t > 0 ? t : void 0;
+}
+function retryAfterSeconds(err) {
+  const headers = err?.response?.headers;
+  const raw = headers?.["retry-after"];
+  if (raw === void 0 || raw === "")
+    return void 0;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds))
+    return Math.max(0, Math.round(seconds));
+  if (typeof raw !== "string")
+    return void 0;
+  const at = Date.parse(raw);
+  if (Number.isNaN(at))
+    return void 0;
+  return Math.max(0, Math.round((at - Date.now()) / 1e3));
+}
 function httpStatus(err) {
   const e = err;
   return e?.response?.status ?? e?.statusCode;
@@ -318,6 +374,15 @@ function normalize(err, opts) {
   if (err instanceof CliNotFoundError) {
     return { type: "not_found", message, recovery: err.recovery, retryable: false };
   }
+  if (err instanceof CliUsageError) {
+    return {
+      type: "usage",
+      message,
+      recovery: err.recovery,
+      retryable: false,
+      ...err.detail !== void 0 ? { detail: err.detail } : {}
+    };
+  }
   const status = httpStatus(err);
   const detail = responseDetail(err);
   if (status !== void 0) {
@@ -366,21 +431,24 @@ function normalize(err, opts) {
           retryable: false,
           detail
         };
-      case 429:
+      case 429: {
+        const wait = retryAfterSeconds(err);
         return {
           type: "rate_limited",
           status,
-          message: "Rate limited",
-          recovery: "Wait and retry the request.",
-          retryable: true
+          message: `${opts.service} is rate limiting these requests`,
+          recovery: wait === void 0 ? `${opts.service} did not say how long to wait. Pause a few seconds before retrying, and make fewer requests at once.` : `${opts.service} asked for a ${wait}s pause before the next request. Wait at least that long, then retry.`,
+          retryable: true,
+          ...wait === void 0 ? {} : { detail: { retryAfterSeconds: wait } }
         };
+      }
     }
     if (status >= 500) {
       return {
         type: "server",
         status,
-        message: `Server error (HTTP ${status})`,
-        recovery: `${opts.service} returned an internal error; retry shortly.`,
+        message: status === 503 ? `${opts.service} returned 503 (service unavailable)` : `${opts.service} returned ${status}`,
+        recovery: status === 503 ? `${opts.service} is temporarily refusing work. Retry shortly.` : `${opts.service} failed to complete the request. Usually temporary, so retry. If it persists, the request itself may be at fault.`,
         retryable: true,
         detail
       };
@@ -395,15 +463,59 @@ function normalize(err, opts) {
     };
   }
   const code = errorCode(err);
-  if (code && NETWORK_CODES.includes(code) || NETWORK_CODES.some((c) => message.includes(c))) {
+  const transport = classifyTransport(err, code, message, opts);
+  if (transport)
+    return transport;
+  return { type: "unknown", message, recovery: "Unexpected error; inspect the message.", retryable: false };
+}
+function classifyTransport(err, code, message, opts) {
+  const matches = (codes) => code !== void 0 && codes.includes(code) || codes.some((c) => message.includes(c));
+  const host = targetHost(err);
+  const where = host ?? opts.service;
+  const urlVar = opts.urlEnvVar ?? "the base-URL environment variable";
+  if (matches(TRANSPORT_CODES.readTimeout)) {
+    const limit = configuredTimeoutMs(err);
+    return {
+      type: "timeout",
+      message: `${opts.service} did not respond${limit === void 0 ? " in time" : ` within ${humanMs(limit)}`}`,
+      recovery: `The request reached ${opts.service} but no response came back in time. Usually the server is busy or the query is too large. Retry, or ask for less: fewer results per page, fewer fields, a narrower query.`,
+      retryable: true
+    };
+  }
+  if (matches(TRANSPORT_CODES.connectTimeout)) {
+    const limit = configuredTimeoutMs(err);
+    return {
+      type: "timeout",
+      message: `Could not open a connection to ${where}${limit === void 0 ? "" : ` within ${humanMs(limit)}`}`,
+      recovery: `The host did not accept a connection in time. If it is reachable at all it is likely overloaded, so retry. If this repeats, confirm ${urlVar} points at a host this machine can reach.`,
+      retryable: true
+    };
+  }
+  if (matches(TRANSPORT_CODES.unresolved)) {
+    return {
+      type: "network",
+      message: `The host ${where} does not resolve`,
+      recovery: `${urlVar} points at a hostname that cannot be looked up from this machine. Check it for a typo. Retrying will not help until it changes.`,
+      retryable: false
+    };
+  }
+  if (matches(TRANSPORT_CODES.refused)) {
     return {
       type: "network",
-      message: `Cannot connect to ${opts.service}: ${message}`,
-      recovery: opts.networkRecovery ?? "Verify the *_URL is correct, the server is reachable, and you are on the VPN if required.",
+      message: `Nothing accepted a connection at ${where}`,
+      recovery: `The host resolved but refused the connection, usually a wrong port or a service that is not running. Retrying will not help until that changes.`,
+      retryable: false
+    };
+  }
+  if (matches(TRANSPORT_CODES.dropped)) {
+    return {
+      type: "network",
+      message: `The connection to ${opts.service} closed before a response arrived`,
+      recovery: `The connection dropped mid-request. This is usually a blip, so retry.`,
       retryable: true
     };
   }
-  return { type: "unknown", message, recovery: "Unexpected error; inspect the message.", retryable: false };
+  return void 0;
 }
 function classifyError(err, opts) {
   const base = normalize(err, opts);
@@ -476,7 +588,7 @@ async function runCli(program, opts) {
 
 // src/program.ts
 import { styleText } from "util";
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // src/commands/board/issues.ts
 import { Argument } from "commander";
@@ -531,9 +643,28 @@ function transformUser(user) {
 function transformField(field) {
   return field;
 }
-function transformCustomFieldOption(option) {
-  const { self: _self, ...rest } = option;
-  return rest;
+
+// src/utils/transformers/field-meta.ts
+function slimAllowedValue(raw) {
+  const out = {};
+  if (typeof raw.id === "string") out.id = raw.id;
+  if (typeof raw.name === "string") out.name = raw.name;
+  if (typeof raw.value === "string") out.value = raw.value;
+  if (Array.isArray(raw.children) && raw.children.length > 0) out.children = raw.children.map(slimAllowedValue);
+  return out;
+}
+function transformFieldMetaEntry(id, meta) {
+  const out = { id, required: meta.required === true };
+  if (typeof meta.name === "string") out.name = meta.name;
+  if (typeof meta.schema?.type === "string") out.type = meta.schema.type;
+  if (Array.isArray(meta.allowedValues) && meta.allowedValues.length > 0) {
+    out.allowedValues = meta.allowedValues.map(slimAllowedValue);
+  }
+  return out;
+}
+function transformFieldMeta(fields) {
+  const entries = Object.entries(fields).map(([id, meta]) => transformFieldMetaEntry(id, meta));
+  return [...entries.filter((f) => f.required), ...entries.filter((f) => !f.required)];
 }
 
 // src/utils/transformers/project.ts
@@ -715,6 +846,29 @@ function pruneSentinels(fields) {
   if (watches && watches.watchCount === 0) delete out.watches;
   return out;
 }
+var ISSUE_KEY_PATTERN = /^[A-Z][A-Z0-9_]*-\d+$/;
+function asIssueRefKey(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const o = value;
+  if (typeof o.key !== "string" || !ISSUE_KEY_PATTERN.test(o.key)) return void 0;
+  if (typeof o.self !== "string" || !o.self.includes("/issue/")) return void 0;
+  return o.key;
+}
+function collapseIssueRefs(fields) {
+  const out = { ...fields };
+  for (const [key, value] of Object.entries(out)) {
+    const single = asIssueRefKey(value);
+    if (single !== void 0) {
+      out[key] = single;
+      continue;
+    }
+    if (Array.isArray(value) && value.length > 0) {
+      const keys = value.map(asIssueRefKey);
+      if (keys.every((k) => k !== void 0)) out[key] = keys;
+    }
+  }
+  return out;
+}
 function transformIssueFields(fields) {
   const {
     // shaped sub-entities (recursed individually)
@@ -741,7 +895,7 @@ function transformIssueFields(fields) {
     // everything else: optional scalars, customfield_*, etc. — gets compacted
     ...rest
   } = fields;
-  const compacted = pruneSentinels(compactRecord(rest));
+  const compacted = collapseIssueRefs(pruneSentinels(compactRecord(rest)));
   return {
     ...compacted,
     summary,
@@ -784,23 +938,23 @@ function transformIssueFields(fields) {
 }
 
 // src/utils/transformers/transition.ts
-function slimAllowedValue(raw) {
+function slimAllowedValue2(raw) {
   if (!raw || typeof raw !== "object") return {};
   const av = raw;
   const slim = {};
   if (typeof av.id === "string") slim.id = av.id;
   if (typeof av.name === "string") slim.name = av.name;
   if (typeof av.value === "string") slim.value = av.value;
+  if (Array.isArray(av.children) && av.children.length > 0) slim.children = av.children.map(slimAllowedValue2);
   return slim;
 }
 function slimField(raw) {
   if (!raw || typeof raw !== "object") return {};
   const field = raw;
   const out = {};
-  if (typeof field.required === "boolean") out.required = field.required;
   if (typeof field.name === "string") out.name = field.name;
   if (Array.isArray(field.allowedValues)) {
-    out.allowedValues = field.allowedValues.map(slimAllowedValue);
+    out.allowedValues = field.allowedValues.map(slimAllowedValue2);
   }
   return out;
 }
@@ -1098,7 +1252,7 @@ function update(parent) {
     async (id, opts) => {
       const description = resolveTextOrFile(opts, "description", { required: false });
       if (opts.name === void 0 && description === void 0 && opts.lead === void 0 && opts.assigneeType === void 0) {
-        throw new Error("Provide at least one of --name, --description, --lead, --assignee-type");
+        throw new CliUsageError("Provide at least one of --name, --description, --lead, --assignee-type");
       }
       const client = getClient();
       const result = await client.components.update({
@@ -1132,22 +1286,6 @@ function registerComponentCommands(program) {
   issueCount(component);
 }
 
-// src/commands/field/options.ts
-function options(parent) {
-  const cmd = parent.command("options").description("Get available options for a custom field").argument("<id>", "Field ID", text).option("--query <text>", "Filter options by text", text).option("--limit <number>", "Max results to return (1-1000)", intInRange(1, 1e3), 25).option("--start <number>", "Page number (1-indexed)", positiveInt);
-  examples(cmd, ["10001", '10001 --query "High"', "10001 --limit 20 --start 2"]);
-  cmd.action(async (id, opts) => {
-    const client = getClient();
-    const result = await client.fields.getFieldOptions({
-      fieldId: id,
-      query: opts.query,
-      maxResults: opts.limit,
-      page: opts.start
-    });
-    output(transformPaged({ ...result, startAt: result.startAt ?? 0 }, transformCustomFieldOption));
-  });
-}
-
 // src/commands/field/search.ts
 function search(parent) {
   const cmd = parent.command("search").description("Search for fields by name or ID").argument("<keyword>", "Search keyword", text).option("--limit <number>", "Maximum number of results (1-1000)", intInRange(1, 1e3), 25);
@@ -1162,9 +1300,8 @@ function search(parent) {
 // src/commands/field/index.ts
 function registerFieldCommands(program) {
   const field = program.command("field").description("Field operations");
-  examples(field, ['search "epic"', 'search "priority"', "options 10120"]);
+  examples(field, ['search "epic"', 'search "priority"']);
   search(field);
-  options(field);
 }
 
 // src/utils/resolve-user.ts
@@ -1575,13 +1712,16 @@ function registerCommentCommands(parent) {
 }
 
 // src/commands/issue/create.ts
+import { Option as Option5 } from "commander";
 import { z as z2 } from "zod";
-var customFieldsSchema = z2.record(z2.unknown());
+var fieldsSchema = z2.record(z2.unknown());
 function create3(parent) {
   const cmd = parent.command("create").description("Create a new issue").requiredOption("--project <key>", "Project key or ID", text).requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)", text).requiredOption("--summary <text>", "Issue summary/title", text).option("--assignee <user>", 'Assignee. Username, "me", or "none" to leave unassigned.', text).option("--reporter <user>", 'Reporter. Username or "me".', text).option("--priority <name>", "Priority name (e.g., High, Medium, Low)", text).option("--labels <labels>", "Comma-separated labels", text).option("--components <names>", "Comma-separated component names", text).option("--fix-versions <versions>", "Comma-separated fix version names", text).option("--due-date <date>", "Due date in YYYY-MM-DD format", date).option("--parent <key>", "Parent issue key (for subtasks)", issueKey).option(
-    "--custom-fields <json>",
-    `Additional custom fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`,
-    jsonShape(customFieldsSchema)
+    "--fields <json>",
+    `Additional fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`,
+    jsonShape(fieldsSchema)
+  ).addOption(
+    new Option5("--custom-fields <json>", "Deprecated alias for --fields").argParser(jsonShape(fieldsSchema)).hideHelp()
   );
   textOrFileOption(cmd, "description", { description: "Issue description in wiki markup" });
   examples(cmd, [
@@ -1592,6 +1732,13 @@ function create3(parent) {
   cmd.action(
     async (opts) => {
       const description = resolveTextOrFile(opts, "description", { required: false });
+      if (opts.fields && opts.customFields) {
+        throw new CliUsageError(
+          "Pass either --fields or --custom-fields, not both",
+          "--custom-fields is a deprecated alias for --fields. Merge the two JSON objects into a single --fields value."
+        );
+      }
+      const fields = opts.fields ?? opts.customFields;
       const assignee = opts.assignee !== void 0 ? await resolveUserToken(opts.assignee) : void 0;
       const reporter = opts.reporter !== void 0 ? await resolveUserToken(opts.reporter) : void 0;
       const client = getClient();
@@ -1608,13 +1755,31 @@ function create3(parent) {
         fixVersions: opts.fixVersions?.split(",").map((v) => v.trim()),
         dueDate: opts.dueDate,
         parent: opts.parent,
-        customFields: opts.customFields
+        customFields: fields
       });
       output(transformCreatedIssue(result));
     }
   );
 }
 
+// src/commands/issue/createmeta.ts
+function createmeta(parent) {
+  const cmd = parent.command("createmeta").description("Show which fields a new issue of a given type accepts, and the values they allow").requiredOption("--project <key>", "Project key", text).requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)", text);
+  examples(cmd, ["--project PROJ --type Task", "--project PROJ --type Bug"]);
+  cmd.action(async (opts) => {
+    const client = getClient();
+    const meta = await client.issues.getCreateMeta({ projectKey: opts.project, issueTypeName: opts.type });
+    const issueType = meta.projects?.[0]?.issuetypes?.[0];
+    if (!issueType?.fields) {
+      throw new CliNotFoundError(
+        `No create metadata for issue type "${opts.type}" in project "${opts.project}"`,
+        "Verify the project key and issue type name, then check you may create that type there."
+      );
+    }
+    output(transformFieldMeta(issueType.fields));
+  });
+}
+
 // src/commands/issue/delete.ts
 function deleteIssue(parent) {
   const cmd = parent.command("delete").description("Delete an issue").argument("<key>", "Issue key", issueKey).option("--delete-subtasks", "Also delete subtasks (default: false)");
@@ -1704,6 +1869,17 @@ function devStatus(parent) {
   });
 }
 
+// src/commands/issue/editmeta.ts
+function editmeta(parent) {
+  const cmd = parent.command("editmeta").description("Show which fields this issue's edit screen accepts, and the values they allow").argument("<key>", "Issue key", issueKey);
+  examples(cmd, ["PROJ-123"]);
+  cmd.action(async (key) => {
+    const client = getClient();
+    const meta = await client.issues.getEditMeta({ issueKeyOrId: key });
+    output(transformFieldMeta(meta.fields ?? {}));
+  });
+}
+
 // src/utils/constants.ts
 var DEFAULT_FIELDS = [
   "summary",
@@ -1832,41 +2008,60 @@ function search2(parent) {
 }
 
 // src/commands/issue/transition.ts
+import { z as z3 } from "zod";
+var fieldsSchema2 = z3.record(z3.unknown());
+function resolveTransitionId(to, transitions2) {
+  const target = to.toLowerCase();
+  const byName = transitions2.filter((t) => t.name.toLowerCase() === target);
+  const matches = byName.length > 0 ? byName : transitions2.filter((t) => t.to.toLowerCase() === target);
+  if (matches.length === 1) return matches[0].id;
+  const available = transitions2.map((t) => ({ id: t.id, name: t.name, to: t.to }));
+  if (matches.length === 0) {
+    throw new CliUsageError(
+      `Transition "${to}" not available from current status`,
+      "Re-run --to with one of the listed transitions (by name, id, or target status).",
+      { available }
+    );
+  }
+  const ids = matches.map((t) => t.id).join(", ");
+  throw new CliUsageError(
+    `"${to}" matches more than one available transition`,
+    `Re-run --to with one of these ids: ${ids}.`,
+    { available }
+  );
+}
 function transition(parent) {
-  const cmd = parent.command("transition").description("Transition issue to a new status").argument("<key>", "Issue key", issueKey).requiredOption("--to <idOrName>", "Transition ID, or status name (case-insensitive)", text);
+  const cmd = parent.command("transition").description("Transition issue to a new status").argument("<key>", "Issue key", issueKey).requiredOption("--to <idOrName>", "Transition ID, transition name, or target status name (case-insensitive)", text).option(
+    "--fields <json>",
+    `Fields required by the transition screen, as JSON (e.g. '{"customfield_10100": {"value": "Approved"}}')`,
+    jsonShape(fieldsSchema2)
+  );
   commentOption(cmd, { description: "Comment to add during transition" });
   examples(cmd, [
     "PROJ-123 --to 31",
+    'PROJ-123 --to "Start Review"',
     'PROJ-123 --to "In Review"',
-    'PROJ-123 --to Done --comment "Verified in staging"'
+    'PROJ-123 --to Done --comment "Verified in staging"',
+    `PROJ-123 --to Approve --fields '{"customfield_10100": {"value": "Approved"}}'`
   ]);
-  cmd.action(async (key, opts) => {
-    const comment = resolveTextOrFile(opts, "comment", { required: false });
-    const client = getClient();
-    let transitionId;
-    if (/^\d+$/.test(opts.to)) {
-      transitionId = opts.to;
-    } else {
-      const raw = await client.issues.getTransitions({
-        issueKeyOrId: key,
-        expand: "transitions.fields"
-      });
-      const transitions2 = transformTransitions(raw);
-      const target = opts.to.toLowerCase();
-      const matches = transitions2.filter((t) => t.name.toLowerCase() === target);
-      if (matches.length === 0) {
-        const names = transitions2.map((t) => `"${t.name}"`).join(", ");
-        throw new Error(`Transition "${opts.to}" not available from current status. Available: ${names || "(none)"}`);
-      }
-      if (matches.length > 1) {
-        const ids = matches.map((t) => t.id).join(", ");
-        throw new Error(`Multiple transitions named "${opts.to}". Use --to <id> with one of: ${ids}`);
+  cmd.action(
+    async (key, opts) => {
+      const comment = resolveTextOrFile(opts, "comment", { required: false });
+      const client = getClient();
+      let transitionId;
+      if (/^\d+$/.test(opts.to)) {
+        transitionId = opts.to;
+      } else {
+        const raw = await client.issues.getTransitions({
+          issueKeyOrId: key,
+          expand: "transitions.fields"
+        });
+        transitionId = resolveTransitionId(opts.to, transformTransitions(raw));
       }
-      transitionId = matches[0].id;
+      await client.issues.transition({ issueKeyOrId: key, transitionId, fields: opts.fields, comment });
+      output({ transitioned: true, issue: transformIssueRef(key) });
     }
-    await client.issues.transition({ issueKeyOrId: key, transitionId, comment });
-    output({ transitioned: true, issue: transformIssueRef(key) });
-  });
+  );
 }
 
 // src/commands/issue/transitions.ts
@@ -1895,7 +2090,7 @@ function unlink2(parent) {
 }
 
 // src/commands/issue/update.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/utils/multi-value.ts
 import { InvalidArgumentError as InvalidArgumentError5 } from "commander";
@@ -1924,7 +2119,7 @@ function parseMultiValue(flagName, raw) {
 }
 
 // src/commands/issue/update.ts
-var fieldsSchema = z3.record(z3.unknown());
+var fieldsSchema3 = z4.record(z4.unknown());
 function buildUpdateOps(parsed, wrap) {
   if (parsed.mode !== "mutate") return void 0;
   return [...parsed.adds.map((v) => ({ add: wrap(v) })), ...parsed.removes.map((v) => ({ remove: wrap(v) }))];
@@ -1937,7 +2132,7 @@ function update3(parent) {
   const cmd = parent.command("update").description("Update issue fields").argument("<key>", "Issue key", issueKey).option(
     "--fields <json>",
     "JSON string of fields to update (advanced; merges with shortcuts, wins on conflict)",
-    jsonShape(fieldsSchema)
+    jsonShape(fieldsSchema3)
   ).option("--no-notify-users", "Suppress notification emails (default: notify)").option("--attachments <paths>", "Comma-separated local file paths to attach", text).option("--summary <text>", "Set the issue summary", text).option("--priority <name>", "Set the priority by name (e.g. High)", text).option("--assignee <user>", 'Set the assignee. Username, "me", or "none" to unassign.', text).option("--labels <list>", 'Set labels ("a,b,c") or mutate ("+add,-remove")', text).option("--components <list>", 'Set components ("a,b") or mutate ("+add,-remove")', text).option("--fix-versions <list>", 'Set fix versions ("1.0,2.0") or mutate ("+1.0,-0.9")', text);
   textOrFileOption(cmd, "description", { description: "Set the issue description (wiki markup)" });
   examples(cmd, [
@@ -1952,7 +2147,7 @@ function update3(parent) {
     const description = resolveTextOrFile(opts, "description", { required: false });
     const hasShortcut = opts.summary !== void 0 || description !== void 0 || opts.priority !== void 0 || opts.assignee !== void 0 || opts.labels !== void 0 || opts.components !== void 0 || opts.fixVersions !== void 0;
     if (!opts.fields && !opts.attachments && !hasShortcut) {
-      throw new Error(
+      throw new CliUsageError(
         "Provide at least one of --fields, --attachments, or a shortcut flag (--summary, --priority, --labels, ...)"
       );
     }
@@ -2040,12 +2235,12 @@ function create4(parent) {
 }
 
 // src/commands/issue/worklog/delete.ts
-import { Option as Option5 } from "commander";
+import { Option as Option6 } from "commander";
 var ADJUST_ESTIMATE = ["new", "leave", "manual", "auto"];
 function deleteWorklog(parent) {
   const cmd = parent.command("delete").description("Delete a worklog entry").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "worklog", { mandatory: true });
-  cmd.addOption(new Option5("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"', text).option(
+  cmd.addOption(new Option6("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"', text).option(
     "--increase-by <amount>",
     'Amount to increase the estimate by; required when --adjust-estimate is "manual"',
     text
@@ -2086,12 +2281,12 @@ function list4(parent) {
 }
 
 // src/commands/issue/worklog/update.ts
-import { Option as Option6 } from "commander";
+import { Option as Option7 } from "commander";
 var ADJUST_ESTIMATE2 = ["new", "leave", "auto"];
 function update4(parent) {
   const cmd = parent.command("update").description("Update an existing worklog entry").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "worklog", { mandatory: true });
-  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')", text).option("--started <datetime>", "Start time in ISO 8601 format", dateTime).addOption(new Option6("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE2)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"', text);
+  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')", text).option("--started <datetime>", "Start time in ISO 8601 format", dateTime).addOption(new Option7("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE2)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"', text);
   commentOption(cmd, { description: "Worklog comment" });
   examples(cmd, [
     'PROJ-123 --worklog-id 12345 --time "1h 30m"',
@@ -2149,6 +2344,8 @@ function registerIssueCommands(program) {
   deleteIssue(issue);
   transition(issue);
   transitions(issue);
+  createmeta(issue);
+  editmeta(issue);
   assign(issue);
   registerCommentCommands(issue);
   registerWorklogCommands(issue);
@@ -2250,10 +2447,10 @@ function issues2(parent) {
 }
 
 // src/commands/sprint/list.ts
-import { Option as Option7 } from "commander";
+import { Option as Option8 } from "commander";
 var SPRINT_STATES = ["future", "active", "closed"];
 function list6(parent) {
-  const cmd = parent.command("list").description("List sprints for a board").requiredOption("--board <id>", "Board ID", positiveInt).addOption(new Option7("--state <state>", "Filter by sprint state").choices(SPRINT_STATES));
+  const cmd = parent.command("list").description("List sprints for a board").requiredOption("--board <id>", "Board ID", positiveInt).addOption(new Option8("--state <state>", "Filter by sprint state").choices(SPRINT_STATES));
   examples(cmd, ["--board 42", "--board 42 --state active"]);
   cmd.action(async (opts) => {
     const client = getClient();
@@ -2266,10 +2463,10 @@ function list6(parent) {
 }
 
 // src/commands/sprint/update.ts
-import { Argument as Argument4, Option as Option8 } from "commander";
+import { Argument as Argument4, Option as Option9 } from "commander";
 var SPRINT_STATES2 = ["future", "active", "closed"];
 function update5(parent) {
-  const cmd = parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name", text).addOption(new Option8("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format", text).option("--end-date <date>", "New end date in ISO 8601 format", text).option("--goal <goal>", "New sprint goal", text);
+  const cmd = parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name", text).addOption(new Option9("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format", text).option("--end-date <date>", "New end date in ISO 8601 format", text).option("--goal <goal>", "New sprint goal", text);
   examples(cmd, [
     '100 --name "Sprint 10 - Extended"',
     "100 --state active",
@@ -2309,10 +2506,10 @@ function registerSprintCommands(program) {
 
 // src/commands/token/client.ts
 import { JiraClient as JiraClient2 } from "jira-data-center-client";
-function getTokenClient(options2 = {}) {
+function getTokenClient(options = {}) {
   const baseUrl = process.env.JIRA_URL;
-  const username = options2.basicUsername ?? process.env.JIRA_BASIC_USERNAME;
-  const password = options2.basicPassword ?? process.env.JIRA_BASIC_PASSWORD;
+  const username = options.basicUsername ?? process.env.JIRA_BASIC_USERNAME;
+  const password = options.basicPassword ?? process.env.JIRA_BASIC_PASSWORD;
   if (!baseUrl || !username || !password) {
     const missing = [
       ...!baseUrl ? ["JIRA_URL"] : [],
@@ -2453,12 +2650,12 @@ function registerUserCommands(program) {
 function assertExactlyOne(opts, keys, label) {
   const present = keys.filter((k) => opts[k] !== void 0);
   if (present.length !== 1)
-    throw new Error(`Provide exactly one of ${keys.map((k) => `--${k}`).join(", ")} (${label}).`);
+    throw new CliUsageError(`Provide exactly one of ${keys.map((k) => `--${k}`).join(", ")} (${label}).`);
   return present[0];
 }
 function assertAtLeastOne(opts, keys) {
   if (!keys.some((k) => opts[k] !== void 0))
-    throw new Error(`Provide at least one of ${keys.map((k) => `--${k}`).join(", ")}.`);
+    throw new CliUsageError(`Provide at least one of ${keys.map((k) => `--${k}`).join(", ")}.`);
 }
 
 // src/commands/xray/execution/add.ts
@@ -2489,7 +2686,9 @@ function add(parent) {
     }
     const allKeys = [...keys];
     if (allKeys.length === 0) {
-      throw new Error("No tests to add \u2014 the given --set(s) contain no tests and no --test keys were provided.");
+      throw new CliUsageError(
+        "No tests to add \u2014 the given --set(s) contain no tests and no --test keys were provided."
+      );
     }
     const result = await client.testExecutions.addTests({ execKey, keys: allKeys });
     output(result ?? { added: allKeys });
@@ -2733,7 +2932,7 @@ function update7(parent) {
   ]);
   cmd.action(async (folderId, opts) => {
     if (opts.name === void 0 && opts.rank === void 0) {
-      throw new Error("Provide at least one of --name or --rank.");
+      throw new CliUsageError("Provide at least one of --name or --rank.");
     }
     const client = getClient();
     await client.testRepository.updateFolder({
@@ -2763,12 +2962,12 @@ function registerFolderCommands(xray) {
 // src/commands/xray/import/execution.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { basename as basename2 } from "path";
-import { Option as Option9 } from "commander";
+import { Option as Option10 } from "commander";
 var FORMATS = ["xray", "junit", "testng", "nunit", "xunit", "robot", "cucumber", "behave"];
 var NEEDS_SCOPE = /* @__PURE__ */ new Set(["junit", "testng", "nunit", "xunit", "robot"]);
 function execution(parent) {
   const cmd = parent.command("execution").description("Import test execution results into Xray").requiredOption("--file <path>", "Path to the result file", filePath).addOption(
-    new Option9(
+    new Option10(
       "--format <format>",
       "Result format. xray/cucumber/behave: JSON body, no --project/--execution required. junit/testng/nunit/xunit/robot: XML body, requires --project OR --execution."
     ).choices(FORMATS).makeOptionMandatory()
@@ -2789,7 +2988,7 @@ function execution(parent) {
   cmd.action(
     async (opts) => {
       if (NEEDS_SCOPE.has(opts.format) && !opts.project && !opts.execution) {
-        throw new Error(
+        throw new CliUsageError(
           `--project or --execution is required for ${opts.format} format. Provide --project <key> to create a new execution, or --execution <key> to import into an existing one.`
         );
       }
@@ -2966,7 +3165,7 @@ function add4(parent) {
 }
 
 // src/commands/xray/precondition/create.ts
-import { Option as Option10 } from "commander";
+import { Option as Option11 } from "commander";
 
 // src/utils/xray/fields.ts
 var CONCEPT_SUFFIX = {
@@ -2997,18 +3196,22 @@ function resolveTestTypeValue(allowedValues, type) {
   if (type === "manual") {
     const match2 = allowedValues.find((v) => /manual/i.test(v));
     if (!match2)
-      throw new Error(`No 'manual' Test Type value found on this instance. Available: ${allowedValues.join(", ")}`);
+      throw new CliNotFoundError(
+        `No 'manual' Test Type value found on this instance. Available: ${allowedValues.join(", ")}`
+      );
     return match2;
   }
   if (type === "generic") {
     const match2 = allowedValues.find((v) => /generic/i.test(v));
     if (!match2)
-      throw new Error(`No 'generic' Test Type value found on this instance. Available: ${allowedValues.join(", ")}`);
+      throw new CliNotFoundError(
+        `No 'generic' Test Type value found on this instance. Available: ${allowedValues.join(", ")}`
+      );
     return match2;
   }
   const match = allowedValues.find((v) => !/manual/i.test(v) && !/generic/i.test(v));
   if (!match)
-    throw new Error(
+    throw new CliNotFoundError(
       `No 'cucumber' (gherkin/automation) Test Type value found on this instance. Available: ${allowedValues.join(", ")}`
     );
   return match;
@@ -3029,7 +3232,7 @@ async function resolveTypeValue(client, params) {
 }
 function requireField(map, concept, label) {
   const id = map[concept];
-  if (!id) throw new Error(`Xray field for '${label}' not found on this instance.`);
+  if (!id) throw new CliNotFoundError(`Xray field for '${label}' not found on this instance.`);
   return id;
 }
 function buildTestCustomFields(map, opts) {
@@ -3067,7 +3270,7 @@ function create10(parent) {
   const cmd = parent.command("create").description(
     "Create a new Xray Pre-Condition issue. Note: the Pre-Condition issue type is only available in projects that have it configured (e.g. BD); it is not on your project scheme."
   ).requiredOption("--project <key>", "Project key (e.g. BD)", text).requiredOption("--summary <text>", "Pre-Condition summary (title)", text).addOption(
-    new Option10("--type <type>", "Pre-Condition type").choices(["manual", "generic", "cucumber"]).default("manual")
+    new Option11("--type <type>", "Pre-Condition type").choices(["manual", "generic", "cucumber"]).default("manual")
   );
   textOrFileOption(cmd, "condition", { description: "Pre-condition body / definition text" });
   textOrFileOption(cmd, "description", { description: "Pre-Condition issue description" });
@@ -3138,9 +3341,9 @@ function remove4(parent) {
 }
 
 // src/commands/xray/precondition/update.ts
-import { Option as Option11 } from "commander";
+import { Option as Option12 } from "commander";
 function update9(parent) {
-  const cmd = parent.command("update").description("Update an Xray Pre-Condition issue").argument("<preKey>", "Pre-Condition issue key (e.g. PROJ-50)", issueKey).option("--summary <text>", "New summary (title)", text).addOption(new Option11("--type <type>", "New Pre-Condition type").choices(["manual", "generic", "cucumber"]));
+  const cmd = parent.command("update").description("Update an Xray Pre-Condition issue").argument("<preKey>", "Pre-Condition issue key (e.g. PROJ-50)", issueKey).option("--summary <text>", "New summary (title)", text).addOption(new Option12("--type <type>", "New Pre-Condition type").choices(["manual", "generic", "cucumber"]));
   textOrFileOption(cmd, "condition", { description: "New pre-condition body / definition text" });
   textOrFileOption(cmd, "description", { description: "New Pre-Condition issue description" });
   examples(cmd, ['PROJ-50 --summary "Updated precondition"', 'PROJ-50 --type generic --condition "apiKey != null"']);
@@ -3163,12 +3366,12 @@ function update9(parent) {
             fieldMap: map
           });
           const typeId = map["precondition-type"];
-          if (!typeId) throw new Error("Xray field for 'Pre-Condition Type' not found on this instance.");
+          if (!typeId) throw new CliNotFoundError("Xray field for 'Pre-Condition Type' not found on this instance.");
           customFields[typeId] = { value: typeValue };
         }
         if (condition !== void 0) {
           const bodyId = map["precondition-body"];
-          if (!bodyId) throw new Error("Xray field for 'Conditions' not found on this instance.");
+          if (!bodyId) throw new CliNotFoundError("Xray field for 'Conditions' not found on this instance.");
           customFields[bodyId] = condition;
         }
       }
@@ -3199,9 +3402,10 @@ function registerPreconditionCommands(xray) {
 // src/utils/xray/run-id.ts
 async function resolveRunId(client, o) {
   if (o.runId !== void 0) return o.runId;
-  if (!o.execution || !o.test) throw new Error("Provide a run id, or both --execution and --test to resolve the run.");
+  if (!o.execution || !o.test)
+    throw new CliUsageError("Provide a run id, or both --execution and --test to resolve the run.");
   const run = await client.testRuns.resolve({ execKey: o.execution, testKey: o.test });
-  if (!run?.id) throw new Error(`No test run found for ${o.test} in ${o.execution}.`);
+  if (!run?.id) throw new CliNotFoundError(`No test run found for ${o.test} in ${o.execution}.`);
   return Number(run.id);
 }
 
@@ -3573,7 +3777,7 @@ function update12(parent) {
       const data = resolveTextOrFile(opts, "data", { required: false });
       const result = resolveTextOrFile(opts, "result", { required: false });
       if (action === void 0 && data === void 0 && result === void 0) {
-        throw new Error(
+        throw new CliUsageError(
           "Provide at least one of --action (or --action-file), --data (or --data-file), --result (or --result-file)."
         );
       }
@@ -3597,16 +3801,16 @@ function registerStepCommands(xray) {
 }
 
 // src/commands/xray/test/create.ts
-import { Option as Option12 } from "commander";
-import { z as z4 } from "zod";
-var stepsSchema = z4.array(
-  z4.object({ action: z4.string(), data: z4.string().optional(), result: z4.string().optional() })
+import { Option as Option13 } from "commander";
+import { z as z5 } from "zod";
+var stepsSchema = z5.array(
+  z5.object({ action: z5.string(), data: z5.string().optional(), result: z5.string().optional() })
 );
 function create11(parent) {
   const cmd = parent.command("create").description("Create a new Xray Test issue").requiredOption("--project <key>", "Project key (e.g. AI)", text).requiredOption("--summary <text>", "Test summary (title)", text).addOption(
-    new Option12("--type <type>", "Test type (when cucumber: also pass --gherkin; when generic: --definition)").choices(["manual", "cucumber", "generic"]).default("manual")
+    new Option13("--type <type>", "Test type (when cucumber: also pass --gherkin; when generic: --definition)").choices(["manual", "cucumber", "generic"]).default("manual")
   ).addOption(
-    new Option12("--cucumber-type <cucumberType>", "Cucumber scenario type (required when --type cucumber)").choices([
+    new Option13("--cucumber-type <cucumberType>", "Cucumber scenario type (required when --type cucumber)").choices([
       "scenario",
       "scenario-outline"
     ])
@@ -3634,10 +3838,10 @@ function create11(parent) {
       const definition = resolveTextOrFile(opts, "definition", { required: false });
       const description = resolveTextOrFile(opts, "description", { required: false });
       if (opts.type === "cucumber" && !gherkin) {
-        throw new Error("--gherkin (or --gherkin-file) is required when --type is cucumber.");
+        throw new CliUsageError("--gherkin (or --gherkin-file) is required when --type is cucumber.");
       }
       if (opts.type === "generic" && !definition) {
-        throw new Error("--definition (or --definition-file) is required when --type is generic.");
+        throw new CliUsageError("--definition (or --definition-file) is required when --type is generic.");
       }
       const cucumberType = opts.cucumberType === "scenario" ? "Scenario" : opts.cucumberType === "scenario-outline" ? "Scenario Outline" : void 0;
       const client = getClient();
@@ -3712,13 +3916,13 @@ function list18(parent) {
       const client = getClient();
       if (opts.folder !== void 0) {
         if (!opts.project) {
-          throw new Error("--project is required when --folder is specified.");
+          throw new CliUsageError("--project is required when --folder is specified.");
         }
         const otherScopes = ["set", "plan", "execution", "precondition"].filter(
           (k) => opts[k] !== void 0
         );
         if (otherScopes.length > 0) {
-          throw new Error(
+          throw new CliUsageError(
             `--folder cannot be combined with ${otherScopes.map((k) => `--${k}`).join(", ")}. Use --folder with --project only.`
           );
         }
@@ -3776,10 +3980,10 @@ function list18(parent) {
 }
 
 // src/commands/xray/test/update.ts
-import { Option as Option13 } from "commander";
+import { Option as Option14 } from "commander";
 function update13(parent) {
-  const cmd = parent.command("update").description("Update an Xray Test issue").argument("<testKey>", "Test issue key (e.g. PROJ-584)", issueKey).option("--summary <text>", "New summary (title)", text).addOption(new Option13("--type <type>", "Test type").choices(["manual", "cucumber", "generic"])).addOption(
-    new Option13("--cucumber-type <cucumberType>", "Cucumber scenario type (required when --type cucumber)").choices([
+  const cmd = parent.command("update").description("Update an Xray Test issue").argument("<testKey>", "Test issue key (e.g. PROJ-584)", issueKey).option("--summary <text>", "New summary (title)", text).addOption(new Option14("--type <type>", "Test type").choices(["manual", "cucumber", "generic"])).addOption(
+    new Option14("--cucumber-type <cucumberType>", "Cucumber scenario type (required when --type cucumber)").choices([
       "scenario",
       "scenario-outline"
     ])
@@ -3810,10 +4014,10 @@ function update13(parent) {
       if (opts.reporter !== void 0) fields.reporter = { name: opts.reporter };
       if (opts.type !== void 0) {
         if (opts.type === "cucumber" && !gherkin) {
-          throw new Error("--gherkin (or --gherkin-file) is required when --type is cucumber.");
+          throw new CliUsageError("--gherkin (or --gherkin-file) is required when --type is cucumber.");
         }
         if (opts.type === "generic" && !definition) {
-          throw new Error("--definition (or --definition-file) is required when --type is generic.");
+          throw new CliUsageError("--definition (or --definition-file) is required when --type is generic.");
         }
         const cucumberType = opts.cucumberType === "scenario" ? "Scenario" : opts.cucumberType === "scenario-outline" ? "Scenario Outline" : void 0;
         const projectKey = testKey.split("-")[0];
@@ -3967,7 +4171,7 @@ function registerXrayCommands(program) {
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
 function buildProgram() {
-  const program = new Command16();
+  const program = new Command17();
   program.name("jiradc").description("Jira Data Center CLI").version(readPackageVersion(import.meta.url)).configureHelp({
     styleTitle: (str) => styleText("bold", str),
     styleUsage: (str) => styleText("dim", str),
@@ -4028,10 +4232,33 @@ function getCredentialInfo() {
   };
 }
 
+// src/utils/field-error-recovery.ts
+var CUSTOM_FIELD_KEY = /^customfield_(\d+)$/;
+function customFieldIds(detail) {
+  if (!detail || typeof detail !== "object") return [];
+  const errors = detail.errors;
+  if (!errors || typeof errors !== "object") return [];
+  return Object.keys(errors).filter((k) => CUSTOM_FIELD_KEY.test(k));
+}
+function adaptFieldErrors(normalized) {
+  const ids = customFieldIds(normalized.detail);
+  if (ids.length === 0) return normalized;
+  const numbers = ids.map((id) => CUSTOM_FIELD_KEY.exec(id)?.[1] ?? id);
+  const lookup = numbers.map((n) => `jiradc field search ${n}`).join(", ");
+  const plural = ids.length > 1 ? "s" : "";
+  return {
+    ...normalized,
+    recovery: `Jira rejected field${plural} ${ids.join(", ")}. Run ${lookup} to see the field's name and type before retrying. For the values a field accepts, use issue transitions (transition screens), issue createmeta (create) or issue editmeta (edit).`
+  };
+}
+
 // src/index.ts
 await runCli(buildProgram(), {
   credentialInfo: getCredentialInfo,
   service: "Jira",
   authRecovery: "Set the JIRA_URL and JIRA_TOKEN environment variables.",
-  networkRecovery: "Verify JIRA_URL is correct, the server is reachable, and you are on the VPN if required."
+  urlEnvVar: "JIRA_URL",
+  // Jira names rejected fields by custom-field id. The generic recovery leaves
+  // an agent holding an opaque id, so point it at the command that explains one.
+  adapt: adaptFieldErrors
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "zod": "^3.25.67",
-    "jira-data-center-client": "1.0.41"
+    "jira-data-center-client": "1.0.44"
   },
   "devDependencies": {
     "@types/node": "24.10.4",
@@ -23,15 +23,17 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
-    "cli-utils": "1.0.0",
+    "config-typescript": "0.0.0",
     "config-eslint": "0.0.0",
-    "config-typescript": "0.0.0"
+    "cli-utils": "1.0.0"
   },
   "engines": {
     "node": ">=22.0.0"
   },
   "scripts": {
     "build": "tsup",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist",
     "dev": "tsx src/index.ts",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",