jiradc-cli 1.0.39 → 1.0.41

package/dist/chunk-3GFKV36K.js

@@ -0,0 +1,1133 @@
+// ../../cli-utils/dist/cache.js
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_TTL = 36e5;
+function getCacheDir(name) {
+  return join(homedir(), ".cache", name);
+}
+function getCachePath(name, key) {
+  return join(getCacheDir(name), `${key}.json`);
+}
+function cacheGet(options, key) {
+  const ttl = options.ttl ?? DEFAULT_TTL;
+  const path = getCachePath(options.name, key);
+  try {
+    const stat = statSync(path);
+    if (Date.now() - stat.mtimeMs > ttl)
+      return null;
+    const raw = readFileSync(path, "utf-8");
+    const entry = JSON.parse(raw);
+    return entry.data;
+  } catch {
+    return null;
+  }
+}
+function cacheSet(options, key, data) {
+  const dir = getCacheDir(options.name);
+  const path = getCachePath(options.name, key);
+  const entry = { data, timestamp: Date.now() };
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(entry));
+  } catch {
+  }
+}
+async function cacheGetOrFetch(options, key, fetcher) {
+  const cached = cacheGet(options, key);
+  if (cached !== null)
+    return cached;
+  const data = await fetcher();
+  cacheSet(options, key, data);
+  return data;
+}
+
+// ../../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";
+  }
+}
+
+// ../../cli-utils/dist/validators.js
+import { InvalidArgumentError } from "commander";
+function intInRange(min, max) {
+  return (raw) => {
+    const n = parseInt(raw, 10);
+    if (Number.isNaN(n) || !Number.isFinite(n)) {
+      throw new InvalidArgumentError("Must be an integer.");
+    }
+    if (n < min || n > max) {
+      throw new InvalidArgumentError(`Must be between ${min} and ${max}.`);
+    }
+    return n;
+  };
+}
+function nonNegativeInt(raw) {
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0) {
+    throw new InvalidArgumentError("Must be a non-negative integer.");
+  }
+  return n;
+}
+function positiveInt(raw) {
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 1) {
+    throw new InvalidArgumentError("Must be a positive integer.");
+  }
+  return n;
+}
+function enumArg(choices) {
+  return (raw) => {
+    if (!choices.includes(raw)) {
+      throw new InvalidArgumentError(`Must be one of: ${choices.join(", ")}`);
+    }
+    return raw;
+  };
+}
+function listOf(item) {
+  return (raw, previous) => [...Array.isArray(previous) ? previous : [], item(raw)];
+}
+function text(raw) {
+  return raw;
+}
+function nonEmpty(raw) {
+  if (raw.trim() === "") {
+    throw new InvalidArgumentError("Must not be empty.");
+  }
+  return raw;
+}
+function integer(raw) {
+  if (!/^[+-]?\d+$/.test(raw.trim())) {
+    throw new InvalidArgumentError("Must be an integer.");
+  }
+  return Number(raw);
+}
+function finiteNumber(raw) {
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(raw.trim())) {
+    throw new InvalidArgumentError("Must be a finite number.");
+  }
+  return Number(raw);
+}
+function date(raw) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+  if (!m) {
+    throw new InvalidArgumentError("Must be a date in YYYY-MM-DD format.");
+  }
+  const [, y, mo, d] = m;
+  const year = Number(y);
+  const month = Number(mo);
+  const day = Number(d);
+  const dt = new Date(Date.UTC(year, month - 1, day));
+  if (dt.getUTCFullYear() !== year || dt.getUTCMonth() !== month - 1 || dt.getUTCDate() !== day) {
+    throw new InvalidArgumentError("Not a real calendar date.");
+  }
+  return raw;
+}
+function dateTime(raw) {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(raw) || Number.isNaN(Date.parse(raw))) {
+    throw new InvalidArgumentError("Must be an ISO 8601 date-time, e.g. 2026-06-08T14:30:00Z.");
+  }
+  return raw;
+}
+function uuid(raw) {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw.trim())) {
+    throw new InvalidArgumentError("Must be a GUID, e.g. 1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d.");
+  }
+  return raw.trim().toLowerCase();
+}
+
+// ../../cli-utils/dist/json.js
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+function jsonShape(schema) {
+  return (raw) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new InvalidArgumentError2("Must be valid JSON.");
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+      throw new InvalidArgumentError2(`Invalid JSON shape \u2014 ${issues}`);
+    }
+    return result.data;
+  };
+}
+
+// ../../cli-utils/dist/text-or-file.js
+import { readFileSync as readFileSync3 } from "fs";
+import { InvalidArgumentError as InvalidArgumentError3, Option } from "commander";
+var STDIN_REF = "-";
+function rejectStdinSentinel(value) {
+  if (value === "@-" || value === STDIN_REF) {
+    throw new InvalidArgumentError3(`"${value}" looks like a stdin redirect, which is not supported here. Pass the text directly, or read it from a file/stdin with the matching --\u2026-file <path|-> option.`);
+  }
+  return value;
+}
+function readFileOrStdin(ref) {
+  if (ref === STDIN_REF) {
+    if (process.stdin.isTTY) {
+      throw new InvalidArgumentError3('"--\u2026-file -" reads stdin, but stdin is a terminal (nothing piped).');
+    }
+    try {
+      return readFileSync3(0, "utf8");
+    } catch (err) {
+      throw new InvalidArgumentError3(`failed to read stdin for "--\u2026-file -": ${err.message}`);
+    }
+  }
+  try {
+    return readFileSync3(ref, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      throw new InvalidArgumentError3(`file not found: "${ref}".`);
+    }
+    throw new InvalidArgumentError3(`failed to read file "${ref}": ${e.message}`);
+  }
+}
+function textOrFileOption(cmd, name, opts = {}) {
+  const label = `${name.charAt(0).toUpperCase()}${name.slice(1)} content`;
+  cmd.option(`--${name} <text>`, opts.description ?? label, rejectStdinSentinel);
+  cmd.addOption(new Option(`--${name}-file <path>`, `Read --${name} from a file, or "-" for stdin (mutually exclusive with --${name})`).conflicts(name).argParser(text));
+  return cmd;
+}
+function resolveTextOrFile(opts, name, { required = true } = {}) {
+  const record = opts;
+  const literal = record[name];
+  const ref = record[`${name}File`];
+  if (literal !== void 0 && ref !== void 0) {
+    throw new InvalidArgumentError3(`--${name} and --${name}-file are mutually exclusive; provide only one.`);
+  }
+  if (ref !== void 0) {
+    return readFileOrStdin(ref);
+  }
+  if (literal === void 0 && required) {
+    throw new InvalidArgumentError3(`a ${name} is required: provide --${name} <text> or --${name}-file <path>.`);
+  }
+  return literal;
+}
+
+// ../../cli-utils/dist/registry.js
+var SCOPE_SPECS = {
+  project: { flag: "--project", placeholder: "<key>", description: "Project key", numeric: false },
+  repo: { flag: "--repo", placeholder: "<slug>", description: "Repository slug", numeric: false },
+  space: { flag: "--space", placeholder: "<key>", description: "Confluence space key", numeric: false },
+  board: { flag: "--board-id", placeholder: "<id>", description: "Agile board id", numeric: true },
+  drive: { flag: "--drive-id", placeholder: "<id>", description: "Graph drive id", numeric: false },
+  chat: { flag: "--chat-id", placeholder: "<id>", description: "Teams chat id", numeric: false },
+  page: { flag: "--page-id", placeholder: "<id>", description: "Confluence page id", numeric: false },
+  // Structure takes an id *or* a name: an agent is normally told "BTI Delivery",
+  // and forcing a lookup before every call is the round trip these CLIs remove.
+  structure: { flag: "--structure", placeholder: "<idOrName>", description: "Structure id or name", numeric: false }
+};
+var SUB_ENTITY_ID_NUMERIC = {
+  comment: true,
+  worklog: true,
+  attachment: true,
+  request: true,
+  type: true,
+  employee: true,
+  message: false,
+  membership: false
+};
+var BANNED_FLAGS = {
+  // Pagination (§4.7): --limit / --start, plus --all to collect every match.
+  // The original auto-pagination ban was later amended — the thin-client
+  // principle it rested on governs the client libraries, not the CLIs.
+  max: "use --limit",
+  "max-results": "use --limit",
+  "page-size": "use --limit",
+  "page-all": "use --all to collect every match, or --limit + --start to page",
+  page: "use --start for pagination, or --page-id for a page scope",
+  offset: "use --start",
+  skip: "use --start",
+  "start-at": "use --start",
+  // Prose payload (§4.6): prose is always --body, never a positional or alias.
+  text: "use --body",
+  content: "use --body",
+  message: "use --body for prose, or --message-id for a message id",
+  // Reactions (§7.5 Pattern C) unify on --emoji.
+  emoticon: "use --emoji"
+};
+
+// ../../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 scopeFlag(cmd, concept, opts) {
+  const spec = SCOPE_SPECS[concept];
+  return defineOption(cmd, `${spec.flag} ${spec.placeholder}`, spec.description, spec.numeric ? positiveInt : text, opts.mandatory);
+}
+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 ?? "");
+}
+var projectOption = (cmd, opts = {}) => scopeFlag(cmd, "project", opts);
+var repoOption = (cmd, opts = {}) => scopeFlag(cmd, "repo", opts);
+var spaceOption = (cmd, opts = {}) => scopeFlag(cmd, "space", opts);
+function scopeIdOption(cmd, concept, opts = {}) {
+  return scopeFlag(cmd, concept, opts);
+}
+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 : text, opts.mandatory);
+}
+function paginationOptions(cmd, opts = {}) {
+  const max = opts.maxLimit ?? 1e3;
+  const def = opts.defaultLimit ?? 25;
+  cmd.option("--limit <n>", `Max results per page (1-${max})`, intInRange(1, max), def);
+  if (opts.startIsToken) {
+    cmd.option("--start <indexOrToken>", "Pagination cursor: 0-based offset or opaque next-page token", text);
+  } else {
+    cmd.option("--start <index>", "Pagination offset (0-based)", nonNegativeInt);
+  }
+  return cmd;
+}
+function bodyOption(cmd, opts = {}) {
+  return textOrFileOption(cmd, "body", { description: "Prose body content", ...opts });
+}
+function commentOption(cmd, opts = {}) {
+  return textOrFileOption(cmd, "comment", { description: "Optional note attached to the action", ...opts });
+}
+function formatOption(cmd, choices, def) {
+  const option = cmd.createOption("--format <format>", "Output/content format").choices(choices);
+  if (def !== void 0)
+    option.default(def);
+  return cmd.addOption(option);
+}
+function fieldsOption(cmd) {
+  return cmd.option("--fields <csv>", "Comma-separated list of fields to return", text);
+}
+var EXAMPLES = /* @__PURE__ */ new WeakSet();
+function commandPath(cmd) {
+  const parts = [];
+  for (let c = cmd; c; c = c.parent)
+    parts.unshift(c.name());
+  return parts.join(" ");
+}
+function exampleLine(path, entry) {
+  if (typeof entry === "string")
+    return entry ? `  ${path} ${entry}` : `  ${path}`;
+  if ("raw" in entry)
+    return `  ${entry.raw}`;
+  const [args, comment] = entry;
+  const line = args ? `${path} ${args}` : path;
+  return `  ${line}  # ${comment}`;
+}
+function examples(cmd, entries) {
+  EXAMPLES.add(cmd);
+  return cmd.addHelpText("after", () => {
+    const path = commandPath(cmd);
+    return `
+Examples:
+${entries.map((e) => exampleLine(path, e)).join("\n")}`;
+  });
+}
+function hasExamples(cmd) {
+  return EXAMPLES.has(cmd);
+}
+
+// ../../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 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) {
+    super(message);
+    this.name = "CliNotFoundError";
+    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) {
+    super(`'${commandPath3}' requires a subcommand`);
+    this.name = "SubcommandRequiredError";
+    this.subcommands = subcommands;
+  }
+};
+var UnknownSubcommandError = class extends Error {
+  subcommands;
+  suggestion;
+  constructor(commandPath3, token, subcommands, suggestion) {
+    super(`'${token}' is not a subcommand of '${commandPath3}'`);
+    this.name = "UnknownSubcommandError";
+    this.subcommands = subcommands;
+    this.suggestion = suggestion;
+  }
+};
+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,
+  timeout: EXIT.GENERIC,
+  network: EXIT.GENERIC,
+  unknown: EXIT.GENERIC
+};
+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;
+}
+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").replace(/^error:\s+/, ""),
+      recovery: "Check the command syntax and flags; run the command with --help.",
+      retryable: false
+    };
+  }
+  if (err instanceof SubcommandRequiredError) {
+    return {
+      type: "usage",
+      message,
+      recovery: `Re-run with one of these subcommands: ${err.subcommands.join(", ")}.`,
+      retryable: false,
+      detail: { subcommands: err.subcommands }
+    };
+  }
+  if (err instanceof UnknownSubcommandError) {
+    const didYouMean = err.suggestion === void 0 ? "" : `Did you mean '${err.suggestion}'? `;
+    return {
+      type: "usage",
+      message,
+      recovery: `${didYouMean}Valid subcommands: ${err.subcommands.join(", ")}.`,
+      retryable: false,
+      detail: { subcommands: err.subcommands }
+    };
+  }
+  if (err instanceof CliAuthError) {
+    return { type: "auth", message: message || "Missing credentials", recovery: opts.authRecovery, retryable: false };
+  }
+  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) {
+    switch (status) {
+      case 400:
+        return {
+          type: "usage",
+          status,
+          message: "Bad request",
+          recovery: "Check parameter values (ids, keys, query syntax) against the API.",
+          retryable: false,
+          detail
+        };
+      case 401:
+        return {
+          type: "auth",
+          status,
+          message: "Authentication failed",
+          recovery: opts.authRecovery,
+          retryable: false
+        };
+      case 403:
+        return {
+          type: "forbidden",
+          status,
+          message: "Forbidden",
+          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_MESSAGE,
+          recovery: NOT_FOUND_RECOVERY,
+          retryable: false,
+          detail
+        };
+      case 409:
+        return {
+          type: "conflict",
+          status,
+          message: "Conflict",
+          recovery: "The resource changed or already exists; re-fetch current state and retry.",
+          retryable: false,
+          detail
+        };
+      case 429: {
+        const wait = retryAfterSeconds(err);
+        return {
+          type: "rate_limited",
+          status,
+          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: 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
+      };
+    }
+    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);
+  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: `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 void 0;
+}
+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 {
+    envelope: {
+      error: {
+        type: n.type,
+        message: n.message,
+        recovery: n.recovery,
+        retryable: n.retryable,
+        ...n.detail !== void 0 ? { detail: n.detail } : {}
+      }
+    },
+    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);
+}
+function commandPath2(cmd) {
+  const parts = [];
+  let cur = cmd;
+  while (cur) {
+    parts.unshift(cur.name());
+    cur = cur.parent;
+  }
+  return parts.join(" ");
+}
+function attachSubcommandGuards(cmd) {
+  cmd.commands.forEach(attachSubcommandGuards);
+  if (cmd.commands.length === 0)
+    return;
+  const hasAction = Boolean(cmd._actionHandler);
+  if (hasAction)
+    return;
+  cmd.allowExcessArguments(true);
+  cmd.action((...params) => {
+    const invoked = params[params.length - 1];
+    const names = cmd.commands.map((c) => c.name()).filter((name) => name !== "help");
+    const [token] = invoked.args;
+    if (token === void 0)
+      throw new SubcommandRequiredError(commandPath2(cmd), names);
+    throw new UnknownSubcommandError(commandPath2(cmd), token, names, suggestSubcommand(token, names));
+  });
+}
+function editDistance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const substitution = prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+      row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, substitution);
+    }
+    prev = row;
+  }
+  return prev[b.length];
+}
+function suggestSubcommand(token, names) {
+  const MAX_EDITS = 2;
+  let best;
+  for (const name of names) {
+    const distance = editDistance(token.toLowerCase(), name.toLowerCase());
+    if (distance <= MAX_EDITS && distance < token.length && (!best || distance < best.distance)) {
+      best = { name, distance };
+    }
+  }
+  return best?.name;
+}
+async function runCli(program, opts) {
+  routeErrors(program);
+  attachSubcommandGuards(program);
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    if (isCleanCommanderExit(err)) {
+      process.exit(err.exitCode ?? 0);
+    }
+    createErrorHandler(opts)(err);
+  }
+}
+
+// ../../cli-utils/dist/conventions.js
+var FORBIDDEN_SCOPE_POSITIONALS = /* @__PURE__ */ new Set([
+  "project",
+  "repo",
+  "space",
+  "drive",
+  "board",
+  "chat",
+  "page",
+  "structure"
+]);
+var FORBIDDEN_PROSE_POSITIONALS = /* @__PURE__ */ new Set(["body", "comment", "text"]);
+var SAFE_ID_WORDS = /* @__PURE__ */ new Set([
+  "uuid",
+  "guid",
+  "grid",
+  "valid",
+  "void",
+  "paid",
+  "hybrid",
+  "android",
+  "rapid",
+  "solid",
+  "liquid"
+]);
+function optionConcept(option) {
+  if (!option.long)
+    return void 0;
+  return option.long.replace(/^--/, "").replace(/^no-/, "");
+}
+function optionTakesValue(option) {
+  return option.required || option.optional;
+}
+function hasValidator(o) {
+  return typeof o.parseArg === "function" || Array.isArray(o.argChoices) && o.argChoices.length > 0;
+}
+function checkVariadicAccumulation(o, label, path, violations) {
+  if (!o.variadic || typeof o.parseArg !== "function")
+    return;
+  const first = o.argChoices?.[0] ?? "PROJ-1";
+  const second = o.argChoices?.[1] ?? o.argChoices?.[0] ?? "PROJ-2";
+  let problem;
+  try {
+    const result = o.parseArg(second, o.parseArg(first, void 0));
+    if (!Array.isArray(result) || result.length !== 2) {
+      problem = `two tokens produced ${JSON.stringify(result)} instead of a two-element array`;
+    }
+  } catch (err) {
+    problem = `the parser threw on the probe tokens (${err instanceof Error ? err.message : String(err)})`;
+  }
+  if (problem) {
+    violations.push(`${path}: variadic ${label} has a parser that does not collect values \u2014 ${problem}. Wrap the item validator in \`listOf(...)\` (\xA74.10); a bare validator makes commander keep only the last token.`);
+  }
+}
+function checkRejectsEmptyString(arg, path, violations) {
+  const parse = arg.parseArg;
+  if (!arg.required || arg.variadic || typeof parse !== "function")
+    return;
+  const accepted = (token) => {
+    try {
+      return { value: parse(token, void 0) };
+    } catch {
+      return void 0;
+    }
+  };
+  const empty = accepted("");
+  const blank = empty ? void 0 : accepted("   ");
+  const problem = empty ? `it parsed "" as ${JSON.stringify(empty.value)}` : blank ? `it parsed a whitespace-only value as ${JSON.stringify(blank.value)}` : void 0;
+  if (!problem)
+    return;
+  violations.push(`${path}: required positional \`<${arg.name()}>\` accepts an empty identifier \u2014 ${problem}. A required positional names one entity, and many APIs route \`/resource/\` to \`/resource\`, so an empty id asks for the whole collection and gets a confident 200 instead of an error. Use \`nonEmpty\` rather than \`text\` (or a stricter validator that already fits \u2014 positiveInt, an id/key shape); empty and whitespace-only must both throw (\xA74.10).`);
+}
+function checkOption(option, path, violations) {
+  const name = optionConcept(option);
+  if (!name)
+    return;
+  if (name === "id") {
+    violations.push(`${path}: flag \`--id\` is banned \u2014 use an entity-qualified id flag (e.g. --comment-id, --message-id) per \xA74.3.`);
+    return;
+  }
+  if (/[a-z]id$/.test(name) && !name.endsWith("-id") && !SAFE_ID_WORDS.has(name)) {
+    violations.push(`${path}: id flag \`--${name}\` must be hyphenated as \`--\u2026-id\` per \xA74.3.`);
+  }
+  const hint = BANNED_FLAGS[name];
+  if (hint) {
+    violations.push(`${path}: non-canonical flag \`--${name}\` \u2014 ${hint} (\xA74.6/\xA74.7).`);
+  }
+  if (optionTakesValue(option) && !hasValidator(option)) {
+    violations.push(`${path}: option \`--${name}\` takes a value but declares no validator \u2014 wire one (date/dateTime/jsonShape/integer/positiveInt/\u2026 or .choices()); for free text use \`text\` (empty allowed) or \`nonEmpty\` (\xA74.10).`);
+  }
+  checkVariadicAccumulation(option, `option \`--${name}\``, path, violations);
+}
+function checkArguments(args, path, violations) {
+  if (args.length > 1) {
+    const names = args.map((a) => a.name()).join(", ");
+    violations.push(`${path}: ${args.length} positionals (${names}) \u2014 at most one is allowed; extras must be flags. The only multi-positional form is a single trailing same-kind variadic (\xA74.2).`);
+  }
+  for (const arg of args) {
+    const name = arg.name();
+    if (FORBIDDEN_SCOPE_POSITIONALS.has(name)) {
+      violations.push(`${path}: scope \`${name}\` must be a flag (--${name} / --${name}-id), never a positional (\xA74.2/\xA74.4).`);
+    }
+    if (FORBIDDEN_PROSE_POSITIONALS.has(name)) {
+      violations.push(`${path}: prose \`${name}\` must be the --body flag, never a positional (\xA74.6).`);
+    }
+    if (!hasValidator(arg)) {
+      violations.push(`${path}: positional \`<${name}>\` declares no validator \u2014 pass a parser to .argument()/subjectArg (e.g. positiveInt, enumArg([...]), text) (\xA74.10).`);
+    }
+    checkVariadicAccumulation(arg, `positional \`<${name}>\``, path, violations);
+    checkRejectsEmptyString(arg, path, violations);
+  }
+}
+function checkAllFlag(cmd, path, violations) {
+  const names = new Set(cmd.options.map((o) => o.attributeName()));
+  if (!names.has("all") || names.has("limit"))
+    return;
+  violations.push(`${path}: \`--all\` means "collect every match" and is only meaningful where there are pages to collect, but this command declares no \`--limit\`. Here it reads as a scope filter \u2014 name it for what it selects (e.g. \`--all-employees\`) so the two meanings cannot be confused (\xA74.7).`);
+}
+var NON_CANONICAL_VERBS = /* @__PURE__ */ new Map([
+  ["new", "create"],
+  ["rm", "delete"],
+  ["edit", "update"],
+  ["fetch", "get"],
+  ["show", "get"],
+  ["read", "get"]
+]);
+function checkVerb(cmd, parentPath, path, violations) {
+  if (!parentPath)
+    return;
+  const canonical = NON_CANONICAL_VERBS.get(cmd.name());
+  if (!canonical)
+    return;
+  violations.push(`${path}: \`${cmd.name()}\` is not a canonical verb \u2014 use \`${canonical}\` (rule 2). An agent that learned the verb on one noun applies it to every noun, so a synonym here costs a failed call everywhere else it guesses.`);
+}
+var WRITE_VERBS = ["create", "update", "delete"];
+var WRITE_WITHOUT_READ_EXEMPT = /* @__PURE__ */ new Map([
+  [
+    "bamboohr timeoff",
+    "The read is `requests`, named for what the vendor API addresses \u2014 it filters requests rather than resolving one by id."
+  ],
+  [
+    "msgraph calendar",
+    "The group is named for the calendar, but `create` and `update` act on events, and the read for those is `events`. A `calendar get` would name the wrong entity; the mismatch is real and wants renaming, not a new command."
+  ]
+]);
+function checkWriteWithoutRead(cmd, path, violations) {
+  if (cmd.commands.length === 0)
+    return;
+  const subs = new Set(cmd.commands.map((c) => c.name()));
+  if (subs.has("get") || subs.has("list"))
+    return;
+  const writes = WRITE_VERBS.filter((v) => subs.has(v));
+  if (writes.length === 0 || WRITE_WITHOUT_READ_EXEMPT.has(path))
+    return;
+  violations.push(`${path}: offers ${writes.join(", ")} and no way to read anything back \u2014 no \`get\`, no \`list\`. Add one, or declare the group in WRITE_WITHOUT_READ_EXEMPT with the reason.`);
+}
+function walk(cmd, parentPath, violations) {
+  const path = parentPath ? `${parentPath} ${cmd.name()}` : cmd.name();
+  for (const option of cmd.options)
+    checkOption(option, path, violations);
+  checkAllFlag(cmd, path, violations);
+  checkVerb(cmd, parentPath, path, violations);
+  checkWriteWithoutRead(cmd, path, violations);
+  checkArguments(cmd.registeredArguments, path, violations);
+  if (cmd.commands.length === 0 && !hasExamples(cmd)) {
+    violations.push(`${path}: runnable command has no examples \u2014 declare 1\u20133 with the examples() builder (\xA7"--help is the agent's interface").`);
+  }
+  for (const sub of cmd.commands)
+    walk(sub, path, violations);
+}
+function assertConventions(program) {
+  const violations = [];
+  walk(program, "", violations);
+  if (violations.length > 0) {
+    throw new Error(`CLI convention violations (${violations.length}):
+${violations.map((v) => `  - ${v}`).join("\n")}`);
+  }
+}
+
+// ../../cli-utils/dist/snapshot.js
+function renderArg(arg) {
+  const name = arg.variadic ? `${arg.name()}...` : arg.name();
+  return arg.required ? `<${name}>` : `[${name}]`;
+}
+function renderOption(option) {
+  const suffix = `${option.mandatory ? "!" : ""}${option.argChoices ? `=${option.argChoices.join("|")}` : ""}`;
+  return `${option.flags}${suffix}`;
+}
+function walk2(cmd, parentPath, lines) {
+  const path = parentPath ? `${parentPath} ${cmd.name()}` : cmd.name();
+  const args = cmd.registeredArguments.map(renderArg);
+  const options = cmd.options.map(renderOption).sort();
+  lines.push([path, ...args, ...options].join(" ").trimEnd());
+  [...cmd.commands].sort((a, b) => a.name().localeCompare(b.name())).forEach((sub) => {
+    walk2(sub, path, lines);
+  });
+}
+function serializeCommandTree(program) {
+  const lines = [];
+  walk2(program, "", lines);
+  return lines.join("\n");
+}
+
+// ../../cli-utils/dist/readme.js
+function tokenize(line) {
+  const tokens = [];
+  let current = "";
+  let quote;
+  let started = false;
+  for (const char of line) {
+    if (quote) {
+      if (char === quote)
+        quote = void 0;
+      else
+        current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current || started)
+        tokens.push(current);
+      current = "";
+      started = false;
+      continue;
+    }
+    if (char === "#" && !current && !started)
+      break;
+    current += char;
+  }
+  if (current || started)
+    tokens.push(current);
+  return tokens;
+}
+function candidates(readme, programName) {
+  const found = [];
+  for (const match of readme.matchAll(/^\|\s*`([^`]+)`/gm))
+    found.push(match[1] ?? "");
+  for (const block of readme.matchAll(/^```[a-z]*\n([\s\S]*?)^```/gm)) {
+    const body = (block[1] ?? "").replace(/\\\n\s*/g, " ");
+    for (const line of body.split("\n"))
+      found.push(line.replace(/^\s*\$\s+/, ""));
+  }
+  return found.filter((line) => tokenize(line)[0] === programName);
+}
+function findOption(cmd, flag) {
+  return cmd.options.find((o) => o.long === flag);
+}
+function optionTakesValue2(option) {
+  return option.required || option.optional;
+}
+function resolve(program, tokens) {
+  let cmd = program;
+  const path = [program.name()];
+  let i = 1;
+  for (; i < tokens.length; i++) {
+    const next = cmd.commands.find((c) => c.name() === tokens[i]);
+    if (!next)
+      break;
+    cmd = next;
+    path.push(cmd.name());
+  }
+  return { cmd, path, rest: tokens.slice(i) };
+}
+function checkOne(program, line, documented, problems) {
+  const tokens = tokenize(line);
+  const { cmd, path, rest } = resolve(program, tokens);
+  const where = path.join(" ");
+  if (cmd.commands.length > 0) {
+    const unknown = rest[0];
+    problems.push(unknown && !unknown.startsWith("-") ? `\`${line.trim()}\`: \`${unknown}\` is not a subcommand of \`${where}\`` : `\`${line.trim()}\`: \`${where}\` is a group, not a runnable command`);
+    return;
+  }
+  let positionals = 0;
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i] ?? "";
+    if (!token.startsWith("--")) {
+      if (!token.startsWith("-"))
+        positionals++;
+      continue;
+    }
+    const [flag, inlineValue] = token.split("=", 2);
+    const option = findOption(cmd, flag ?? "");
+    if (!option) {
+      problems.push(`\`${line.trim()}\`: \`${where}\` has no flag \`${flag}\``);
+      continue;
+    }
+    if (inlineValue !== void 0 || !optionTakesValue2(option))
+      continue;
+    while (rest[i + 1] !== void 0 && !(rest[i + 1] ?? "").startsWith("-")) {
+      i++;
+      if (!option.variadic)
+        break;
+    }
+  }
+  const args = cmd.registeredArguments;
+  const variadic = args.some((a) => a.variadic);
+  if (!variadic && positionals > args.length) {
+    problems.push(`\`${line.trim()}\`: \`${where}\` takes ${args.length} positional(s), ${positionals} documented`);
+    return;
+  }
+  documented.add(where);
+}
+function leaves(cmd, path, out) {
+  const here = [...path, cmd.name()];
+  if (cmd.commands.length === 0)
+    out.push(here.join(" "));
+  else
+    for (const sub of cmd.commands)
+      leaves(sub, here, out);
+}
+function checkReadme(program, readme) {
+  const problems = [];
+  const documented = /* @__PURE__ */ new Set();
+  for (const line of candidates(readme, program.name()))
+    checkOne(program, line, documented, problems);
+  const all = [];
+  for (const sub of program.commands)
+    leaves(sub, [program.name()], all);
+  return { problems, undocumented: all.filter((leaf) => !documented.has(leaf)) };
+}
+
+export {
+  cacheGet,
+  cacheSet,
+  cacheGetOrFetch,
+  readPackageVersion,
+  intInRange,
+  nonNegativeInt,
+  positiveInt,
+  enumArg,
+  listOf,
+  text,
+  nonEmpty,
+  integer,
+  finiteNumber,
+  date,
+  dateTime,
+  uuid,
+  jsonShape,
+  rejectStdinSentinel,
+  textOrFileOption,
+  resolveTextOrFile,
+  SCOPE_SPECS,
+  SUB_ENTITY_ID_NUMERIC,
+  BANNED_FLAGS,
+  subjectArg,
+  projectOption,
+  repoOption,
+  spaceOption,
+  scopeIdOption,
+  subEntityOption,
+  paginationOptions,
+  bodyOption,
+  commentOption,
+  formatOption,
+  fieldsOption,
+  examples,
+  EXIT,
+  CliAuthError,
+  CliNotFoundError,
+  CliUsageError,
+  SubcommandRequiredError,
+  UnknownSubcommandError,
+  classifyError,
+  createErrorHandler,
+  routeErrors,
+  attachSubcommandGuards,
+  runCli,
+  assertConventions,
+  serializeCommandTree,
+  checkReadme
+};