jiradc-cli 1.0.31 → 1.0.32

package/dist/index.js

@@ -263,10 +263,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;
@@ -366,21 +411,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 +443,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);
@@ -4033,5 +4125,5 @@ 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"
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "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.42"
   },
   "devDependencies": {
     "@types/node": "24.10.4",
@@ -32,6 +32,8 @@
   },
   "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",