jiradc-cli 1.0.21 → 2.0.0-g9960cad.8

package/dist/index.js

@@ -1,16 +1,25 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync } from "fs";
-import { dirname, join as join4 } from "path";
-import { fileURLToPath } from "url";
-import { styleText } from "util";
-import { Command as Command11 } from "commander";
+// ../../cli-utils/dist/cache.js
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 
-// src/commands/board/issues.ts
-import { Argument } from "commander";
+// ../../cli-utils/dist/bootstrap.js
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function readPackageVersion(importMetaUrl) {
+  try {
+    const here = dirname(fileURLToPath(importMetaUrl));
+    const pkg = JSON.parse(readFileSync2(join2(here, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 
-// src/utils/cli.ts
+// ../../cli-utils/dist/validators.js
 import { InvalidArgumentError } from "commander";
 function intInRange(min, max) {
   return (raw) => {
@@ -39,43 +48,256 @@ function positiveInt(raw) {
   return n;
 }
 
-// src/utils/client.ts
-import { JiraClient } from "jira-data-center-client";
-
-// src/utils/credentials.ts
-function getCredentialInfo() {
-  const baseUrl = process.env.JIRA_URL;
-  const token = process.env.JIRA_TOKEN;
+// ../../cli-utils/dist/registry.js
+var SUB_ENTITY_ID_NUMERIC = {
+  comment: true,
+  worklog: true,
+  attachment: true,
+  request: true,
+  type: true,
+  employee: true,
+  message: false,
+  membership: false
+};
+
+// ../../cli-utils/dist/builders.js
+function defineOption(cmd, flags, description, parser, mandatory) {
+  if (mandatory) {
+    return parser ? cmd.requiredOption(flags, description, parser) : cmd.requiredOption(flags, description);
+  }
+  return parser ? cmd.option(flags, description, parser) : cmd.option(flags, description);
+}
+function subjectArg(cmd, name, opts = {}) {
+  const inner = opts.variadic ? `${name}...` : name;
+  const token = opts.optional ? `[${inner}]` : `<${inner}>`;
+  return opts.parser ? cmd.argument(token, opts.description ?? "", opts.parser) : cmd.argument(token, opts.description ?? "");
+}
+function subEntityOption(cmd, entity, opts = {}) {
+  const numeric = opts.numeric ?? SUB_ENTITY_ID_NUMERIC[entity] ?? true;
+  const description = `${entity.charAt(0).toUpperCase()}${entity.slice(1)} id`;
+  return defineOption(cmd, `--${entity}-id <id>`, description, numeric ? positiveInt : void 0, opts.mandatory);
+}
+function bodyOption(cmd, opts = {}) {
+  return defineOption(cmd, "--body <text>", "Prose body content", void 0, opts.mandatory);
+}
+
+// ../../cli-utils/dist/errors.js
+import { CommanderError } from "commander";
+var EXIT = {
+  SUCCESS: 0,
+  GENERIC: 1,
+  USAGE: 2,
+  NOT_FOUND: 3,
+  FORBIDDEN: 4,
+  CONFLICT: 5,
+  AUTH: 6
+};
+var CliAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliAuthError";
+  }
+};
+var TYPE_EXIT = {
+  usage: EXIT.USAGE,
+  not_found: EXIT.NOT_FOUND,
+  forbidden: EXIT.FORBIDDEN,
+  conflict: EXIT.CONFLICT,
+  auth: EXIT.AUTH,
+  rate_limited: EXIT.GENERIC,
+  server: EXIT.GENERIC,
+  network: EXIT.GENERIC,
+  unknown: EXIT.GENERIC
+};
+var NETWORK_CODES = ["ENOTFOUND", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT"];
+function httpStatus(err) {
+  const e = err;
+  return e?.response?.status ?? e?.statusCode;
+}
+function responseDetail(err) {
+  const e = err;
+  const data = e?.response?.data;
+  if (data && typeof data === "object")
+    return data;
+  const body = e?.body;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return parsed.error ?? parsed;
+    } catch {
+      return void 0;
+    }
+  }
+  if (body && typeof body === "object") {
+    return body.error ?? body;
+  }
+  return void 0;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function normalize(err, opts) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof CommanderError) {
+    return {
+      type: "usage",
+      message: message || "Invalid command usage",
+      recovery: "Check the command syntax and flags; run the command with --help.",
+      retryable: false
+    };
+  }
+  if (err instanceof CliAuthError) {
+    return { type: "auth", message: message || "Missing credentials", recovery: opts.authRecovery, retryable: false };
+  }
+  const status = httpStatus(err);
+  const detail = responseDetail(err);
+  if (status !== void 0) {
+    switch (status) {
+      case 400:
+        return {
+          type: "usage",
+          status,
+          message: "Bad request (HTTP 400)",
+          recovery: "Check parameter values (ids, keys, query syntax) against the API.",
+          retryable: false,
+          detail
+        };
+      case 401:
+        return {
+          type: "auth",
+          status,
+          message: "Authentication failed (HTTP 401)",
+          recovery: opts.authRecovery,
+          retryable: false
+        };
+      case 403:
+        return {
+          type: "forbidden",
+          status,
+          message: "Forbidden (HTTP 403)",
+          recovery: `Your ${opts.service} account lacks permission for this operation; check token scope and resource permissions.`,
+          retryable: false,
+          detail
+        };
+      case 404:
+        return {
+          type: "not_found",
+          status,
+          message: "Not found (HTTP 404)",
+          recovery: "Verify the id/key exists and that you have access to it.",
+          retryable: false,
+          detail
+        };
+      case 409:
+        return {
+          type: "conflict",
+          status,
+          message: "Conflict (HTTP 409)",
+          recovery: "The resource changed or already exists; re-fetch current state and retry.",
+          retryable: false,
+          detail
+        };
+      case 429:
+        return {
+          type: "rate_limited",
+          status,
+          message: "Rate limited (HTTP 429)",
+          recovery: "Wait and retry the request.",
+          retryable: true
+        };
+    }
+    if (status >= 500) {
+      return {
+        type: "server",
+        status,
+        message: `Server error (HTTP ${status})`,
+        recovery: `${opts.service} returned an internal error; retry shortly.`,
+        retryable: true,
+        detail
+      };
+    }
+    return {
+      type: "unknown",
+      status,
+      message: `${opts.service} error (HTTP ${status}): ${message}`,
+      recovery: "Inspect the detail field for the API response.",
+      retryable: false,
+      detail
+    };
+  }
+  const code = errorCode(err);
+  if (code && NETWORK_CODES.includes(code) || NETWORK_CODES.some((c) => message.includes(c))) {
+    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.",
+      retryable: true
+    };
+  }
+  return { type: "unknown", message, recovery: "Unexpected error; inspect the message.", retryable: false };
+}
+function classifyError(err, opts) {
+  const base = normalize(err, opts);
+  const n = opts.adapt ? opts.adapt(base, err) : base;
+  if (n.type === "auth" && n.detail === void 0 && opts.credentialInfo) {
+    n.detail = opts.credentialInfo();
+  }
   return {
-    environment: {
-      JIRA_URL: {
-        value: baseUrl ?? null,
-        description: "Your Jira Server base URL (e.g., https://jira.example.com)"
-      },
-      JIRA_TOKEN: {
-        value: token ? "<set>" : null,
-        description: "Personal Access Token"
+    envelope: {
+      error: {
+        type: n.type,
+        message: n.message,
+        recovery: n.recovery,
+        retryable: n.retryable,
+        ...n.detail !== void 0 ? { detail: n.detail } : {}
       }
     },
-    tokenUrl: `${baseUrl ?? "https://jira.example.com"}/secure/ViewProfile.jspa`,
-    hint: "Export environment variables in your shell profile (e.g., ~/.zshrc)."
+    exitCode: TYPE_EXIT[n.type]
+  };
+}
+function createErrorHandler(opts) {
+  return (err) => {
+    const { envelope, exitCode } = classifyError(err, opts);
+    process.stderr.write(`${JSON.stringify(envelope)}
+`);
+    return process.exit(exitCode);
   };
 }
+function isCleanCommanderExit(err) {
+  return err instanceof CommanderError && (err.exitCode === 0 || err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version");
+}
+function routeErrors(cmd) {
+  cmd.exitOverride();
+  cmd.configureOutput({ writeErr: () => void 0 });
+  cmd.commands.forEach(routeErrors);
+}
+async function runCli(program, opts) {
+  routeErrors(program);
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    if (isCleanCommanderExit(err)) {
+      process.exit(err.exitCode ?? 0);
+    }
+    createErrorHandler(opts)(err);
+  }
+}
+
+// src/program.ts
+import { styleText } from "util";
+import { Command as Command11 } from "commander";
+
+// src/commands/board/issues.ts
+import { Argument } from "commander";
 
 // src/utils/client.ts
+import { JiraClient } from "jira-data-center-client";
 function getClient() {
   const baseUrl = process.env.JIRA_URL;
   const token = process.env.JIRA_TOKEN;
   if (!baseUrl || !token) {
     const missing = [...!baseUrl ? ["JIRA_URL"] : [], ...!token ? ["JIRA_TOKEN"] : []];
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Missing required environment variables: ${missing.join(", ")}`,
-        ...getCredentialInfo()
-      })}
-`
-    );
-    process.exit(1);
+    throw new CliAuthError(`Missing required environment variables: ${missing.join(", ")}`);
   }
   return new JiraClient({ baseUrl, token });
 }
@@ -89,68 +311,6 @@ function output(data) {
   process.stdout.write(`${JSON.stringify(data, null, prettyPrint ? 2 : void 0)}
 `);
 }
-function handleError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  const axiosStatus = err?.response?.status;
-  if (axiosStatus === 400) {
-    const responseData = err?.response?.data;
-    const jiraErrors = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Bad request (HTTP 400)`,
-        detail: jiraErrors ?? message,
-        hint: "Check that all parameters are valid (JQL syntax, field names, project keys, etc.)."
-      })}
-`
-    );
-  } else if (axiosStatus === 401) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Authentication failed (HTTP 401)",
-        ...getCredentialInfo()
-      })}
-`
-    );
-  } else if (axiosStatus === 403) {
-    const responseData = err?.response?.data;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Forbidden (HTTP 403)",
-        detail: responseData && typeof responseData === "object" ? responseData : message,
-        hint: "Your account does not have permission for this operation. Check project permissions and token scope."
-      })}
-`
-    );
-  } else if (message.includes("ENOTFOUND") || message.includes("ECONNREFUSED") || message.includes("ECONNRESET")) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Cannot connect to Jira server: ${message}`,
-        hint: "Verify that JIRA_URL is correct and the server is reachable."
-      })}
-`
-    );
-  } else if (axiosStatus === 500) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Server error (HTTP 500): ${message}`,
-        hint: "The server returned an internal error. Check that all parameters are valid (project keys, issue keys, JQL query syntax)."
-      })}
-`
-    );
-  } else {
-    const responseData = err?.response?.data;
-    const detail = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: message,
-        ...axiosStatus !== void 0 && { statusCode: axiosStatus },
-        ...detail && { detail }
-      })}
-`
-    );
-  }
-  process.exit(1);
-}
 
 // src/utils/transformers/base.ts
 function jiraBaseUrl() {
@@ -513,8 +673,8 @@ function list(parent) {
 }
 
 // src/commands/board/index.ts
-function registerBoardCommands(program2) {
-  const board = program2.command("board").description("Board operations").addHelpText(
+function registerBoardCommands(program) {
+  const board = program.command("board").description("Board operations").addHelpText(
     "after",
     `
 Examples:
@@ -635,8 +795,8 @@ Examples:
 }
 
 // src/commands/component/index.ts
-function registerComponentCommands(program2) {
-  const component = program2.command("component").description("Project component operations").addHelpText(
+function registerComponentCommands(program) {
+  const component = program.command("component").description("Project component operations").addHelpText(
     "after",
     `
 Examples:
@@ -658,16 +818,16 @@ Examples:
 
 // src/commands/field/options.ts
 function options(parent) {
-  parent.command("options <id>").description("Get available options for a custom field").option("--query <text>", "Filter options by text").option("--limit <number>", "Max results to return (1-1000)", intInRange(1, 1e3), 25).option("--page <number>", "Page number (1-indexed)", positiveInt).addHelpText(
+  parent.command("options <id>").description("Get available options for a custom field").option("--query <text>", "Filter options by text").option("--limit <number>", "Max results to return (1-1000)", intInRange(1, 1e3), 25).option("--start <number>", "Page number (1-indexed)", positiveInt).addHelpText(
     "after",
-    '\nExamples:\n  jiradc field options 10001\n  jiradc field options 10001 --query "High"\n  jiradc field options 10001 --limit 20 --page 2'
+    '\nExamples:\n  jiradc field options 10001\n  jiradc field options 10001 --query "High"\n  jiradc field options 10001 --limit 20 --start 2'
   ).action(async (id, opts) => {
     const client = getClient();
     const result = await client.fields.getFieldOptions({
       fieldId: id,
       query: opts.query,
       maxResults: opts.limit,
-      page: opts.page
+      page: opts.start
     });
     output(transformPaged({ ...result, startAt: result.startAt ?? 0 }, transformCustomFieldOption));
   });
@@ -686,8 +846,8 @@ function search(parent) {
 }
 
 // src/commands/field/index.ts
-function registerFieldCommands(program2) {
-  const field = program2.command("field").description("Field operations").addHelpText(
+function registerFieldCommands(program) {
+  const field = program.command("field").description("Field operations").addHelpText(
     "after",
     `
 Examples:
@@ -718,15 +878,15 @@ async function resolveUserToken(token) {
 
 // src/commands/issue/assign.ts
 function assign(parent) {
-  parent.command("assign <key> <user>").description('Assign an issue. <user> is a username, "me", or "none" to unassign.').addHelpText(
+  parent.command("assign <key>").description('Assign an issue. --assignee is a username, "me", or "none" to unassign.').requiredOption("--assignee <user>", 'Username to assign, "me" for the current user, or "none" to unassign').addHelpText(
     "after",
     `
 Examples:
-  jiradc issue assign PROJ-123 jsmith
-  jiradc issue assign PROJ-123 me
-  jiradc issue assign PROJ-123 none`
-  ).action(async (key, user) => {
-    const resolved = await resolveUserToken(user);
+  jiradc issue assign PROJ-123 --assignee jsmith
+  jiradc issue assign PROJ-123 --assignee me
+  jiradc issue assign PROJ-123 --assignee none`
+  ).action(async (key, opts) => {
+    const resolved = await resolveUserToken(opts.assignee);
     const client = getClient();
     await client.issues.update({
       issueKeyOrId: key,
@@ -738,20 +898,22 @@ Examples:
 
 // src/commands/issue/attachment/delete.ts
 function deleteAttachment(parent) {
-  parent.command("delete").description("Delete an attachment by ID").requiredOption("--id <attachmentId>", "Attachment ID to delete").addHelpText("after", "\nExamples:\n  jiradc issue attachment delete --id 12345").action(async (opts) => {
+  const cmd = parent.command("delete <key>").description("Delete an attachment by ID");
+  subEntityOption(cmd, "attachment", { mandatory: true });
+  cmd.addHelpText("after", "\nExamples:\n  jiradc issue attachment delete PROJ-123 --attachment-id 12345").action(async (key, opts) => {
     const client = getClient();
-    await client.issues.deleteAttachment({ attachmentId: opts.id });
-    output({ deleted: true, attachmentId: opts.id });
+    await client.issues.deleteAttachment({ attachmentId: String(opts.attachmentId) });
+    output({ deleted: true, issueKey: key, attachmentId: opts.attachmentId });
   });
 }
 
 // src/commands/issue/attachment/download-all.ts
-import { mkdirSync } from "fs";
-import { join } from "path";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join3 } from "path";
 function downloadAll(parent) {
   parent.command("download-all <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into").addHelpText("after", "\nExamples:\n  jiradc issue attachment download-all PROJ-123 --output ./downloads").action(async (key, opts) => {
     const client = getClient();
-    mkdirSync(opts.output, { recursive: true });
+    mkdirSync2(opts.output, { recursive: true });
     const issue = await client.issues.get({
       issueKeyOrId: key,
       fields: ["attachment"]
@@ -768,7 +930,7 @@ function downloadAll(parent) {
         failed.push({ filename: att.filename, error: "No content URL" });
         continue;
       }
-      const destPath = join(opts.output, att.filename);
+      const destPath = join3(opts.output, att.filename);
       try {
         await client.issues.downloadAttachment({ url: att.content, destinationPath: destPath });
         results.push({ filename: att.filename, size: att.size, path: destPath });
@@ -788,11 +950,17 @@ function downloadAll(parent) {
 
 // src/commands/issue/attachment/download.ts
 function download(parent) {
-  parent.command("download <key>").description("Download a single attachment by ID").requiredOption("--id <attachmentId>", "Attachment ID").requiredOption("--output <path>", "Local file path to save the attachment").addHelpText("after", "\nExamples:\n  jiradc issue attachment download PROJ-123 --id 12345 --output ./report.pdf").action(async (key, opts) => {
+  const cmd = parent.command("download <key>").description("Download a single attachment by ID");
+  subEntityOption(cmd, "attachment", { mandatory: true });
+  cmd.requiredOption("--output <path>", "Local file path to save the attachment").addHelpText(
+    "after",
+    "\nExamples:\n  jiradc issue attachment download PROJ-123 --attachment-id 12345 --output ./report.pdf"
+  ).action(async (key, opts) => {
     const client = getClient();
-    const attachment = await client.issues.getAttachment({ attachmentId: opts.id });
+    const attachmentId = String(opts.attachmentId);
+    const attachment = await client.issues.getAttachment({ attachmentId });
     if (!attachment.content) {
-      throw new Error(`Attachment ${opts.id} has no content URL`);
+      throw new Error(`Attachment ${attachmentId} has no content URL`);
     }
     await client.issues.downloadAttachment({
       url: attachment.content,
@@ -841,8 +1009,8 @@ function upload(parent) {
     const filePaths = opts.files.split(",").map((f) => f.trim());
     const results = [];
     for (const filePath of filePaths) {
-      const attachments2 = await client.issues.addAttachment({ issueKeyOrId: key, filePath });
-      results.push(...attachments2);
+      const attachments = await client.issues.addAttachment({ issueKeyOrId: key, filePath });
+      results.push(...attachments);
     }
     output({
       issueKey: key,
@@ -866,9 +1034,9 @@ function registerAttachmentCommands(parent) {
 Examples:
   $ jiradc issue attachment list PROJ-123
   $ jiradc issue attachment upload PROJ-123 --files ./report.pdf
-  $ jiradc issue attachment download PROJ-123 --id 12345 --output ./report.pdf
+  $ jiradc issue attachment download PROJ-123 --attachment-id 12345 --output ./report.pdf
   $ jiradc issue attachment download-all PROJ-123 --output ./downloads
-  $ jiradc issue attachment delete --id 12345
+  $ jiradc issue attachment delete PROJ-123 --attachment-id 12345
 `
   );
   upload(attachment);
@@ -878,47 +1046,6 @@ Examples:
   deleteAttachment(attachment);
 }
 
-// src/commands/issue/attachments.ts
-import { mkdirSync as mkdirSync2 } from "fs";
-import { join as join2 } from "path";
-function attachments(parent) {
-  parent.command("attachments <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into").addHelpText("after", "\nExamples:\n  jiradc issue attachments PROJ-123 --output ./downloads").action(async (key, opts) => {
-    const client = getClient();
-    mkdirSync2(opts.output, { recursive: true });
-    const issue = await client.issues.get({
-      issueKeyOrId: key,
-      fields: ["attachment"]
-    });
-    const atts = issue.fields.attachment ?? [];
-    if (atts.length === 0) {
-      output({ issueKey: key, downloaded: 0, files: [] });
-      return;
-    }
-    const results = [];
-    const failed = [];
-    for (const att of atts) {
-      if (!att.content) {
-        failed.push({ filename: att.filename, error: "No content URL" });
-        continue;
-      }
-      const destPath = join2(opts.output, att.filename);
-      try {
-        await client.issues.downloadAttachment({ url: att.content, destinationPath: destPath });
-        results.push({ filename: att.filename, size: att.size, path: destPath });
-      } catch (err) {
-        failed.push({ filename: att.filename, error: String(err) });
-      }
-    }
-    output({
-      issueKey: key,
-      downloaded: results.length,
-      total: atts.length,
-      files: results,
-      ...failed.length > 0 && { failed }
-    });
-  });
-}
-
 // src/commands/issue/batch-changelog.ts
 function batchChangelog(parent) {
   parent.command("batch-changelog <keys>").description("Get changelogs for multiple issues at once").option("--limit <number>", "Max changelog entries per issue (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).addHelpText(
@@ -979,7 +1106,7 @@ function changelog(parent) {
 // src/commands/issue/clone.ts
 import { unlink } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 var CLONE_FIELDS = [
   "summary",
   "description",
@@ -1030,7 +1157,7 @@ Examples:
         const tmpFiles = [];
         const copied = await Promise.all(
           f.attachment.map(async (att) => {
-            const tmpPath = join3(tmpdir(), `jiradc-clone-${Date.now()}-${att.filename}`);
+            const tmpPath = join4(tmpdir(), `jiradc-clone-${Date.now()}-${att.filename}`);
             tmpFiles.push(tmpPath);
             await client.issues.downloadAttachment({ url: att.content, destinationPath: tmpPath });
             await client.issues.addAttachment({ issueKeyOrId: newKey, filePath: tmpPath });
@@ -1071,9 +1198,11 @@ Examples:
   );
 }
 
-// src/commands/issue/comment/add.ts
-function add(parent) {
-  parent.command("add <key>").description("Add a comment to an issue").requiredOption("--body <text>", "Comment body in wiki markup").addHelpText("after", '\nExamples:\n  jiradc issue comment add PROJ-123 --body "Fixed in latest build"').action(async (key, opts) => {
+// src/commands/issue/comment/create.ts
+function create2(parent) {
+  const cmd = parent.command("create <key>").description("Add a comment to an issue").addHelpText("after", '\nExamples:\n  jiradc issue comment create PROJ-123 --body "Fixed in latest build"');
+  bodyOption(cmd, { mandatory: true });
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const result = await client.issues.addComment({ issueKeyOrId: key, body: opts.body });
     output(transformComment(result));
@@ -1082,18 +1211,30 @@ function add(parent) {
 
 // src/commands/issue/comment/delete.ts
 function deleteComment(parent) {
-  parent.command("delete <key>").description("Delete a comment from an issue").requiredOption("--id <commentId>", "Comment ID to delete").addHelpText("after", "\nExamples:\n  jiradc issue comment delete PROJ-123 --id 12345").action(async (key, opts) => {
+  const cmd = parent.command("delete <key>").description("Delete a comment from an issue").addHelpText("after", "\nExamples:\n  jiradc issue comment delete PROJ-123 --comment-id 12345");
+  subEntityOption(cmd, "comment", { mandatory: true });
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    await client.issues.deleteComment({ issueKeyOrId: key, commentId: opts.id });
-    output({ deleted: true, issueKey: key, commentId: opts.id });
+    await client.issues.deleteComment({ issueKeyOrId: key, commentId: String(opts.commentId) });
+    output({ deleted: true, issueKey: key, commentId: opts.commentId });
   });
 }
 
-// src/commands/issue/comment/edit.ts
-function edit(parent) {
-  parent.command("edit <key>").description("Edit an existing comment").requiredOption("--id <commentId>", "Comment ID to edit").requiredOption("--body <text>", "Updated comment body in wiki markup").addHelpText("after", '\nExamples:\n  jiradc issue comment edit PROJ-123 --id 12345 --body "Updated comment text"').action(async (key, opts) => {
+// src/commands/issue/comment/update.ts
+function update2(parent) {
+  const cmd = parent.command("update <key>").description("Update an existing comment").addHelpText(
+    "after",
+    '\nExamples:\n  jiradc issue comment update PROJ-123 --comment-id 12345 --body "Updated comment text"'
+  );
+  subEntityOption(cmd, "comment", { mandatory: true });
+  bodyOption(cmd, { mandatory: true });
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    const result = await client.issues.editComment({ issueKeyOrId: key, commentId: opts.id, body: opts.body });
+    const result = await client.issues.editComment({
+      issueKeyOrId: key,
+      commentId: String(opts.commentId),
+      body: opts.body
+    });
     output(transformComment(result));
   });
 }
@@ -1104,18 +1245,18 @@ function registerCommentCommands(parent) {
     "after",
     `
 Examples:
-  $ jiradc issue comment add PROJ-123 --body "Fixed in latest build"
-  $ jiradc issue comment edit PROJ-123 --id 12345 --body "Updated comment text"
-  $ jiradc issue comment delete PROJ-123 --id 12345
+  $ jiradc issue comment create PROJ-123 --body "Fixed in latest build"
+  $ jiradc issue comment update PROJ-123 --comment-id 12345 --body "Updated comment text"
+  $ jiradc issue comment delete PROJ-123 --comment-id 12345
 `
   );
-  add(comment);
-  edit(comment);
+  create2(comment);
+  update2(comment);
   deleteComment(comment);
 }
 
 // src/commands/issue/create.ts
-function create2(parent) {
+function create3(parent) {
   parent.command("create").description("Create a new issue").requiredOption("--project <key>", "Project key or ID").requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)").requiredOption("--summary <text>", "Issue summary/title").option("--description <text>", "Issue description in wiki markup").option("--assignee <username>", "Assignee username").option("--reporter <username>", "Reporter username").option("--priority <name>", "Priority name (e.g., High, Medium, Low)").option("--labels <labels>", "Comma-separated labels").option("--components <names>", "Comma-separated component names").option("--fix-versions <versions>", "Comma-separated fix version names").option("--due-date <date>", "Due date in YYYY-MM-DD format").option("--parent <key>", "Parent issue key (for subtasks)").option("--custom-fields <json>", `Additional custom fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`).addHelpText(
     "after",
     `
@@ -1449,7 +1590,7 @@ function buildSetValue(parsed, wrap) {
   if (parsed.mode !== "set") return void 0;
   return parsed.values.map(wrap);
 }
-function update2(parent) {
+function update3(parent) {
   parent.command("update <key>").description("Update issue fields").option("--fields <json>", "JSON string of fields to update (advanced; merges with shortcuts, wins on conflict)").option("--no-notify-users", "Suppress notification emails (default: notify)").option("--attachments <paths>", "Comma-separated local file paths to attach").option("--summary <text>", "Set the issue summary").option("--description <text>", "Set the issue description (wiki markup)").option("--priority <name>", "Set the priority by name (e.g. High)").option("--assignee <user>", 'Set the assignee. Username, "me", or "none" to unassign.').option("--labels <list>", 'Set labels ("a,b,c") or mutate ("+add,-remove")').option("--components <list>", 'Set components ("a,b") or mutate ("+add,-remove")').option("--fix-versions <list>", 'Set fix versions ("1.0,2.0") or mutate ("+1.0,-0.9")').addHelpText(
     "after",
     `
@@ -1530,11 +1671,11 @@ Examples:
   });
 }
 
-// src/commands/issue/worklog/add.ts
-function add2(parent) {
-  parent.command("add <key>").description("Log time spent on an issue").requiredOption("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addHelpText(
+// src/commands/issue/worklog/create.ts
+function create4(parent) {
+  parent.command("create <key>").description("Log time spent on an issue").requiredOption("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addHelpText(
     "after",
-    '\nExamples:\n  jiradc issue worklog add PROJ-123 --time 2h\n  jiradc issue worklog add PROJ-123 --time "1d 4h" --comment "Backend implementation"\n  jiradc issue worklog add PROJ-123 --time 3h --started "2026-03-19T09:00:00.000+0000"'
+    '\nExamples:\n  jiradc issue worklog create PROJ-123 --time 2h\n  jiradc issue worklog create PROJ-123 --time "1d 4h" --comment "Backend implementation"\n  jiradc issue worklog create PROJ-123 --time 3h --started "2026-03-19T09:00:00.000+0000"'
   ).action(async (key, opts) => {
     const client = getClient();
     const result = await client.issues.addWorklog({
@@ -1551,37 +1692,57 @@ function add2(parent) {
 import { Option as Option4 } from "commander";
 var ADJUST_ESTIMATE = ["new", "leave", "manual", "auto"];
 function deleteWorklog(parent) {
-  parent.command("delete <key>").description("Delete a worklog entry").requiredOption("--id <worklogId>", "Worklog ID to delete").addOption(new Option4("--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"').option("--increase-by <amount>", 'Amount to increase the estimate by; required when --adjust-estimate is "manual"').addHelpText(
+  const cmd = parent.command("delete <key>").description("Delete a worklog entry");
+  subEntityOption(cmd, "worklog", { mandatory: true });
+  cmd.addOption(new Option4("--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"').option("--increase-by <amount>", 'Amount to increase the estimate by; required when --adjust-estimate is "manual"').addHelpText(
     "after",
-    "\nExamples:\n  jiradc issue worklog delete PROJ-123 --id 12345\n  jiradc issue worklog delete PROJ-123 --id 12345 --adjust-estimate leave\n  jiradc issue worklog delete PROJ-123 --id 12345 --adjust-estimate new --new-estimate 2h"
+    "\nExamples:\n  jiradc issue worklog delete PROJ-123 --worklog-id 12345\n  jiradc issue worklog delete PROJ-123 --worklog-id 12345 --adjust-estimate leave\n  jiradc issue worklog delete PROJ-123 --worklog-id 12345 --adjust-estimate new --new-estimate 2h"
   ).action(
     async (key, opts) => {
       const client = getClient();
       await client.issues.deleteWorklog({
         issueKeyOrId: key,
-        worklogId: opts.id,
+        worklogId: String(opts.worklogId),
         adjustEstimate: opts.adjustEstimate,
         newEstimate: opts.newEstimate,
         increaseBy: opts.increaseBy
       });
-      output({ deleted: true, issueKey: key, worklogId: opts.id });
+      output({ deleted: true, issueKey: key, worklogId: opts.worklogId });
     }
   );
 }
 
-// src/commands/issue/worklog/edit.ts
+// src/commands/issue/worklog/list.ts
+function list4(parent) {
+  parent.command("list <key>").description("Get worklogs for an issue").option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--limit <number>", "Max results per page (1-1000)", intInRange(1, 1e3), 25).addHelpText(
+    "after",
+    "\nExamples:\n  jiradc issue worklog list PROJ-123\n  jiradc issue worklog list PROJ-123 --limit 10\n  jiradc issue worklog list PROJ-123 --start 10 --limit 5"
+  ).action(async (key, opts) => {
+    const client = getClient();
+    const result = await client.issues.getWorklogs({
+      issueKeyOrId: key,
+      startAt: opts.start,
+      maxResults: opts.limit
+    });
+    output(transformPaged(result, transformWorklog));
+  });
+}
+
+// src/commands/issue/worklog/update.ts
 import { Option as Option5 } from "commander";
 var ADJUST_ESTIMATE2 = ["new", "leave", "auto"];
-function edit2(parent) {
-  parent.command("edit <key>").description("Update an existing worklog entry").requiredOption("--id <worklogId>", "Worklog ID to edit").option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addOption(new Option5("--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"').addHelpText(
+function update4(parent) {
+  const cmd = parent.command("update <key>").description("Update an existing worklog entry");
+  subEntityOption(cmd, "worklog", { mandatory: true });
+  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addOption(new Option5("--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"').addHelpText(
     "after",
-    '\nExamples:\n  jiradc issue worklog edit PROJ-123 --id 12345 --time "1h 30m"\n  jiradc issue worklog edit PROJ-123 --id 12345 --comment "Revised note"\n  jiradc issue worklog edit PROJ-123 --id 12345 --time 2h --adjust-estimate new --new-estimate 4h'
+    '\nExamples:\n  jiradc issue worklog update PROJ-123 --worklog-id 12345 --time "1h 30m"\n  jiradc issue worklog update PROJ-123 --worklog-id 12345 --comment "Revised note"\n  jiradc issue worklog update PROJ-123 --worklog-id 12345 --time 2h --adjust-estimate new --new-estimate 4h'
   ).action(
     async (key, opts) => {
       const client = getClient();
       const result = await client.issues.updateWorklog({
         issueKeyOrId: key,
-        worklogId: opts.id,
+        worklogId: String(opts.worklogId),
         timeSpent: opts.time,
         comment: opts.comment,
         started: opts.started,
@@ -1593,43 +1754,27 @@ function edit2(parent) {
   );
 }
 
-// src/commands/issue/worklog/list.ts
-function list4(parent) {
-  parent.command("list <key>").description("Get worklogs for an issue").option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--limit <number>", "Max results per page (1-1000)", intInRange(1, 1e3), 25).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue worklog list PROJ-123\n  jiradc issue worklog list PROJ-123 --limit 10\n  jiradc issue worklog list PROJ-123 --start 10 --limit 5"
-  ).action(async (key, opts) => {
-    const client = getClient();
-    const result = await client.issues.getWorklogs({
-      issueKeyOrId: key,
-      startAt: opts.start,
-      maxResults: opts.limit
-    });
-    output(transformPaged(result, transformWorklog));
-  });
-}
-
 // src/commands/issue/worklog/index.ts
 function registerWorklogCommands(parent) {
   const worklog = parent.command("worklog").description("Worklog operations").addHelpText(
     "after",
     `
 Examples:
-  $ jiradc issue worklog add PROJ-123 --time 2h --comment "Backend work"
+  $ jiradc issue worklog create PROJ-123 --time 2h --comment "Backend work"
   $ jiradc issue worklog list PROJ-123 --limit 10
-  $ jiradc issue worklog edit PROJ-123 --id 12345 --time "1h 30m"
-  $ jiradc issue worklog delete PROJ-123 --id 12345
+  $ jiradc issue worklog update PROJ-123 --worklog-id 12345 --time "1h 30m"
+  $ jiradc issue worklog delete PROJ-123 --worklog-id 12345
 `
   );
-  add2(worklog);
+  create4(worklog);
   list4(worklog);
-  edit2(worklog);
+  update4(worklog);
   deleteWorklog(worklog);
 }
 
 // src/commands/issue/index.ts
-function registerIssueCommands(program2) {
-  const issue = program2.command("issue").description("Issue operations").addHelpText(
+function registerIssueCommands(program) {
+  const issue = program.command("issue").description("Issue operations").addHelpText(
     "after",
     `
 Examples:
@@ -1643,8 +1788,8 @@ Examples:
   );
   get2(issue);
   search2(issue);
-  create2(issue);
-  update2(issue);
+  create3(issue);
+  update3(issue);
   deleteIssue(issue);
   transition(issue);
   transitions(issue);
@@ -1658,7 +1803,6 @@ Examples:
   linkTypes(issue);
   linkEpic(issue);
   registerAttachmentCommands(issue);
-  attachments(issue);
   batchCreate(issue);
   clone(issue);
   devStatus(issue);
@@ -1689,8 +1833,8 @@ function versions(parent) {
 }
 
 // src/commands/project/index.ts
-function registerProjectCommands(program2) {
-  const project = program2.command("project").description("Project operations").addHelpText(
+function registerProjectCommands(program) {
+  const project = program.command("project").description("Project operations").addHelpText(
     "after",
     `
 Examples:
@@ -1703,7 +1847,7 @@ Examples:
 }
 
 // src/commands/sprint/create.ts
-function create3(parent) {
+function create5(parent) {
   parent.command("create").description("Create a new sprint").requiredOption("--board <id>", "Board ID to create sprint in", positiveInt).requiredOption("--name <name>", "Sprint name").option("--start-date <date>", "Start date in ISO 8601 format").option("--end-date <date>", "End date in ISO 8601 format").option("--goal <goal>", "Sprint goal").addHelpText(
     "after",
     '\nExamples:\n  jiradc sprint create --board 42 --name "Sprint 10"\n  jiradc sprint create --board 42 --name "Sprint 10" --start-date 2026-03-20 --end-date 2026-04-03 --goal "Complete auth module"'
@@ -1769,7 +1913,7 @@ function list6(parent) {
 // src/commands/sprint/update.ts
 import { Argument as Argument4, Option as Option7 } from "commander";
 var SPRINT_STATES2 = ["future", "active", "closed"];
-function update3(parent) {
+function update5(parent) {
   parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name").addOption(new Option7("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format").option("--end-date <date>", "New end date in ISO 8601 format").option("--goal <goal>", "New sprint goal").addHelpText(
     "after",
     '\nExamples:\n  jiradc sprint update 100 --name "Sprint 10 - Extended"\n  jiradc sprint update 100 --state active\n  jiradc sprint update 100 --end-date 2026-04-10 --goal "Updated goal"'
@@ -1790,8 +1934,8 @@ function update3(parent) {
 }
 
 // src/commands/sprint/index.ts
-function registerSprintCommands(program2) {
-  const sprint = program2.command("sprint").description("Sprint operations").addHelpText(
+function registerSprintCommands(program) {
+  const sprint = program.command("sprint").description("Sprint operations").addHelpText(
     "after",
     `
 Examples:
@@ -1803,8 +1947,8 @@ Examples:
   );
   list6(sprint);
   issues2(sprint);
-  create3(sprint);
-  update3(sprint);
+  create5(sprint);
+  update5(sprint);
   deleteSprint(sprint);
 }
 
@@ -1834,7 +1978,7 @@ function getTokenClient(options2 = {}) {
 }
 
 // src/commands/token/create.ts
-function create4(parent) {
+function create6(parent) {
   parent.command("create").description("Create a Personal Access Token. The secret is returned exactly once.").requiredOption("--name <name>", "Token name").option(
     "--expiration-duration <days>",
     "Token lifetime in days. Omit for a non-expiring token (admin policy permitting).",
@@ -1880,35 +2024,37 @@ function list7(parent) {
 
 // src/commands/token/revoke.ts
 function revoke(parent) {
-  parent.command("revoke").description("Revoke a Personal Access Token by id").requiredOption("--id <tokenId>", "Token id to revoke", positiveInt).option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
+  const cmd = parent.command("revoke").description("Revoke a Personal Access Token by id").option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
     "--basic-password <p>",
     "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
-  ).action(async (opts) => {
+  );
+  subjectArg(cmd, "tokenId", { parser: positiveInt, description: "Token id to revoke" });
+  cmd.action(async (tokenId, opts) => {
     const { client, username, password } = getTokenClient({
       basicUsername: opts.basicUsername,
       basicPassword: opts.basicPassword
     });
-    await client.accessTokens.revoke({ username, password, tokenId: opts.id });
-    output({ revoked: opts.id });
+    await client.accessTokens.revoke({ username, password, tokenId });
+    output({ revoked: tokenId });
   });
 }
 
 // src/commands/token/index.ts
-function registerTokenCommands(program2) {
-  const token = program2.command("token").description("Personal Access Token management").addHelpText(
+function registerTokenCommands(program) {
+  const token = program.command("token").description("Personal Access Token management").addHelpText(
     "after",
     `
 Examples:
   $ jiradc token list
   $ jiradc token create --name my-pat
-  $ jiradc token revoke --id 173
+  $ jiradc token revoke 173
 
 Auth:
   Requires JIRA_BASIC_USERNAME + JIRA_BASIC_PASSWORD
   (or --basic-username / --basic-password on any subcommand).
 `
   );
-  create4(token);
+  create6(token);
   list7(token);
   revoke(token);
 }
@@ -1950,8 +2096,8 @@ function search3(parent) {
 }
 
 // src/commands/user/index.ts
-function registerUserCommands(program2) {
-  const user = program2.command("user").description("User operations").addHelpText(
+function registerUserCommands(program) {
+  const user = program.command("user").description("User operations").addHelpText(
     "after",
     `
 Examples:
@@ -1965,31 +2111,22 @@ Examples:
   search3(user);
 }
 
-// src/index.ts
-function readPackageVersion() {
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = join4(here, "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
+// src/program.ts
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
-var program = new Command11();
-program.name("jiradc").description("Jira Data Center CLI").version(readPackageVersion()).configureHelp({
-  styleTitle: (str) => styleText("bold", str),
-  styleUsage: (str) => styleText("dim", str),
-  styleCommandDescription: (str) => styleText("dim", str),
-  styleOptionDescription: (str) => styleText("dim", str),
-  styleSubcommandDescription: (str) => styleText("dim", str)
-}).addHelpText("beforeAll", `
+function buildProgram() {
+  const program = new Command11();
+  program.name("jiradc").description("Jira Data Center CLI").version(readPackageVersion(import.meta.url)).configureHelp({
+    styleTitle: (str) => styleText("bold", str),
+    styleUsage: (str) => styleText("dim", str),
+    styleCommandDescription: (str) => styleText("dim", str),
+    styleOptionDescription: (str) => styleText("dim", str),
+    styleSubcommandDescription: (str) => styleText("dim", str)
+  }).addHelpText("beforeAll", `
 ${styleText("bold", "jiradc")} ${DIM}\u2014 Jira Data Center CLI${RESET}
 `).addHelpText(
-  "after",
-  `
+    "after",
+    `
 ${styleText("bold", "Environment:")}
   JIRA_URL      Jira Server base URL ${DIM}(e.g., https://jira.example.com)${RESET}
   JIRA_TOKEN    Personal Access Token ${DIM}(generate in Jira > Profile > Personal Access Tokens)${RESET}
@@ -2003,21 +2140,46 @@ ${styleText("bold", "Examples:")}
   ${DIM}$${RESET} jiradc board list --type scrum
   ${DIM}$${RESET} jiradc sprint list --board 42 --state active
 `
-);
-program.option("--pretty", "Pretty-print JSON output");
-program.hook("preAction", (thisCommand) => {
-  if (thisCommand.optsWithGlobals().pretty) setPretty(true);
-});
-registerIssueCommands(program);
-registerProjectCommands(program);
-registerComponentCommands(program);
-registerBoardCommands(program);
-registerSprintCommands(program);
-registerFieldCommands(program);
-registerUserCommands(program);
-registerTokenCommands(program);
-try {
-  await program.parseAsync();
-} catch (err) {
-  handleError(err);
+  );
+  program.option("--pretty", "Pretty-print JSON output");
+  program.hook("preAction", (thisCommand) => {
+    if (thisCommand.optsWithGlobals().pretty) setPretty(true);
+  });
+  registerIssueCommands(program);
+  registerProjectCommands(program);
+  registerComponentCommands(program);
+  registerBoardCommands(program);
+  registerSprintCommands(program);
+  registerFieldCommands(program);
+  registerUserCommands(program);
+  registerTokenCommands(program);
+  return program;
+}
+
+// src/utils/credentials.ts
+function getCredentialInfo() {
+  const baseUrl = process.env.JIRA_URL;
+  const token = process.env.JIRA_TOKEN;
+  return {
+    environment: {
+      JIRA_URL: {
+        value: baseUrl ?? null,
+        description: "Your Jira Server base URL (e.g., https://jira.example.com)"
+      },
+      JIRA_TOKEN: {
+        value: token ? "<set>" : null,
+        description: "Personal Access Token"
+      }
+    },
+    tokenUrl: `${baseUrl ?? "https://jira.example.com"}/secure/ViewProfile.jspa`,
+    hint: "Set these as environment variables in the process that runs this CLI (e.g. shell export, container env, or CI/secret store)."
+  };
 }
+
+// src/index.ts
+await runCli(buildProgram(), {
+  credentialInfo: getCredentialInfo,
+  service: "Jira",
+  authRecovery: "Provide JIRA_URL and JIRA_TOKEN as environment variables to this process (shell export, container env, or CI secret). error.detail lists which are currently set and where to create a token.",
+  networkRecovery: "Verify JIRA_URL is correct, the server is reachable, and you are on the VPN if required."
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.21",
+  "version": "2.0.0-g9960cad.8",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
+    "cli-utils": "1.0.0",
     "jira-data-center-client": "1.0.37"
   },
   "devDependencies": {
@@ -34,6 +35,6 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "test": "vitest run",
-    "test:integration": "vitest run tests/integration"
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   }
 }