@allocator-one/harness-cli 1.0.0

package/dist/chunk-KN5ILZSA.js

@@ -0,0 +1,1459 @@
+#!/usr/bin/env node
+
+// src/core/errors.ts
+var HttpError = class extends Error {
+  constructor(status, message, body = {}, retryAfter = null) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.retryAfter = retryAfter;
+    this.name = "HttpError";
+  }
+  status;
+  body;
+  retryAfter;
+};
+var UpgradeRequiredError = class extends HttpError {
+  constructor(message, body = {}) {
+    super(426, message, body);
+    this.name = "UpgradeRequiredError";
+  }
+};
+var TransportError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TransportError";
+  }
+};
+var UsageError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+var LocalError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LocalError";
+  }
+};
+var CommandError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CommandError";
+  }
+};
+
+// src/version.ts
+import { readFileSync } from "fs";
+var pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+var CLI_VERSION = pkg.version;
+
+// src/core/client.ts
+var RECEIVE_TIMEOUT_MS = 3e4;
+var UPLOAD_RECEIVE_TIMEOUT_MS = 6e4;
+var UPLOAD_FLOOR_BYTES_PER_MS = 100;
+function uploadTimeoutMs(bodyBytes) {
+  return UPLOAD_RECEIVE_TIMEOUT_MS + Math.ceil(bodyBytes / UPLOAD_FLOOR_BYTES_PER_MS);
+}
+var DEFAULT_MESSAGES = {
+  401: "Missing or invalid token (check HARNESS_API_TOKEN)",
+  403: "Token not permitted (scope or admin gate)",
+  404: "Not found",
+  409: "Conflict",
+  422: "Validation error",
+  426: "CLI too old for this API \u2014 upgrade: npm i -g @allocator-one/harness-cli@latest",
+  429: "Rate limited \u2014 retry later"
+};
+var Client = class {
+  constructor(config) {
+    this.config = config;
+    this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
+  }
+  config;
+  fetchImpl;
+  get cliVersion() {
+    return CLI_VERSION;
+  }
+  get baseUrl() {
+    return this.config.baseUrl;
+  }
+  async get(path2, params) {
+    return this.json(await this.raw("GET", path2, { params }));
+  }
+  async post(path2, body = {}) {
+    return this.json(await this.raw("POST", path2, { json: this.withActor(body) }));
+  }
+  async patch(path2, body) {
+    return this.json(await this.raw("PATCH", path2, { json: this.withActor(body) }));
+  }
+  async put(path2, body) {
+    return this.json(await this.raw("PUT", path2, { json: this.withActor(body) }));
+  }
+  async delete(path2) {
+    return this.json(await this.raw("DELETE", path2, {}));
+  }
+  /**
+   * Posts multipart/form-data — the one endpoint that does not take JSON.
+   * Shares auth, the version header, and error mapping with the JSON verbs,
+   * but never the actor: there is no JSON body to carry an `actor` field,
+   * and the server's file contract is the form itself.
+   */
+  async postMultipart(path2, form, bodyBytes = 0) {
+    return this.json(await this.raw("POST", path2, { form, timeoutMs: uploadTimeoutMs(bodyBytes) }));
+  }
+  /** Binary download (attachments); non-2xx still maps through the JSON error envelope. */
+  async getBytes(path2) {
+    const response = await this.raw("GET", path2, {});
+    if (!response.ok) throw await this.toHttpError(response);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  /**
+   * The server's API version, for `version`'s server side. The header rides
+   * on every response — the versioning plug runs before auth — so even a
+   * 401 answers.
+   */
+  async serverVersion() {
+    const response = await this.raw("GET", "/api/v1/stats", {});
+    return response.headers.get("x-harness-api-version") ?? "unknown";
+  }
+  // Only an explicitly configured actor is sent, and never over one the
+  // caller already put in the body.
+  withActor(body) {
+    if (this.config.actor === null || "actor" in body) return body;
+    return { ...body, actor: this.config.actor };
+  }
+  async raw(method, path2, options) {
+    const url = new URL(this.config.baseUrl + path2);
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = {
+      authorization: `Bearer ${this.config.token}`,
+      "x-harness-cli-version": CLI_VERSION
+    };
+    let body;
+    if (options.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(options.json);
+    } else if (options.form !== void 0) {
+      body = options.form;
+    }
+    try {
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(options.timeoutMs ?? RECEIVE_TIMEOUT_MS),
+        redirect: "manual"
+      });
+    } catch (error) {
+      throw new TransportError(transportMessage(error));
+    }
+  }
+  async json(response) {
+    if (!response.ok) throw await this.toHttpError(response);
+    const text = await response.text();
+    if (text === "") return { data: void 0 };
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new TransportError(`the API answered with a non-JSON body (HTTP ${response.status})`);
+    }
+  }
+  async toHttpError(response) {
+    let parsed = {};
+    try {
+      const candidate = JSON.parse(await response.text());
+      if (typeof candidate === "object" && candidate !== null) {
+        parsed = candidate;
+      }
+    } catch {
+    }
+    const fromBody = typeof parsed["message"] === "string" ? parsed["message"] : null;
+    const message = fromBody ?? DEFAULT_MESSAGES[response.status] ?? `HTTP ${response.status}`;
+    if (response.status === 426) return new UpgradeRequiredError(message, parsed);
+    return new HttpError(response.status, message, parsed, response.headers.get("retry-after"));
+  }
+};
+function transportMessage(error) {
+  if (error instanceof Error) {
+    if (error.name === "TimeoutError" || error.name === "AbortError") return "request timed out";
+    const cause = error.cause;
+    if (cause instanceof Error && cause.message !== "") return cause.message;
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/core/output.ts
+var TITLE_WIDTH = 70;
+var segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+function graphemes(text) {
+  return [...segmenter.segment(text)].map((piece) => piece.segment);
+}
+function graphemeLength(text) {
+  return graphemes(text).length;
+}
+function padGraphemes(text, width) {
+  const shortfall = width - graphemeLength(text);
+  return shortfall > 0 ? text + " ".repeat(shortfall) : text;
+}
+function clean(value) {
+  if (value === null || value === void 0) return "";
+  return String(value).replace(/[\x00-\x1F\x7F\u0080-\u009F]/gu, "");
+}
+function json(term) {
+  return JSON.stringify(term) + "\n";
+}
+function issuesTable(issues) {
+  if (issues.length === 0) return "No issues.\n";
+  const rows = issues.map((issue) => [
+    str(issue["identifier"]),
+    str(path(issue, "state", "name")) || "-",
+    str(issue["priority_label"]) || "-",
+    str(path(issue, "assignee", "name")) || "-",
+    truncate(issue["title"])
+  ]);
+  return table(["ID", "STATE", "PRIORITY", "ASSIGNEE", "TITLE"], rows);
+}
+function issueDetail(issue, images = []) {
+  const header = `${str(issue["identifier"])} \xB7 ${clean(issue["title"])}
+`;
+  const fields = [
+    ["State", path(issue, "state", "name")],
+    ["Priority", issue["priority_label"]],
+    ["Assignee", path(issue, "assignee", "name")],
+    ["Team", path(issue, "team", "key")],
+    ["Labels", labelsLine(issue["labels"])],
+    ["Blocked", blockedLine(issue)],
+    ["Due", issue["due_date"]],
+    ["Updated", issue["updated_at"]]
+  ];
+  const fieldLines = fields.filter(([, value]) => value !== null && value !== void 0 && value !== "").map(([label, value]) => `  ${(label + ":").padEnd(12)}${clean(value)}
+`).join("");
+  const sections = [
+    ["Description", issue["description"]],
+    ["Design", issue["design"]],
+    ["Acceptance criteria", issue["acceptance_criteria"]],
+    ["Notes", issue["notes"]]
+  ];
+  const sectionText = sections.filter(([, text]) => text !== null && text !== void 0 && text !== "").map(([title, text]) => `
+${title}:
+${indent(String(text))}
+`).join("");
+  return header + fieldLines + sectionText + relationsSection(issue["relations"]) + childrenSection(issue["children"]) + commentsSection(issue["comments"]) + imagesSection(images);
+}
+function stats(data) {
+  const teams = data["teams"] ?? [];
+  const totals = data["totals"] ?? {};
+  const rows = teams.map((team) => [
+    str(path(team, "team", "key")),
+    str(team["open"]),
+    str(team["started"]),
+    str(team["blocked"]),
+    str(team["ready"]),
+    str(team["closed"])
+  ]);
+  const totalsRow = ["TOTAL", ...["open", "started", "blocked", "ready", "closed"].map((key) => str(totals[key]))];
+  return table(["TEAM", "OPEN", "STARTED", "BLOCKED", "READY", "CLOSED"], [...rows, totalsRow]);
+}
+function table(headers, rows) {
+  const all = [headers, ...rows.map((row) => row.map((cell) => clean(cell)))];
+  const widths = headers.map((_, column) => Math.max(...all.map((row) => graphemeLength(row[column] ?? ""))));
+  return all.map(
+    (row) => row.map((cell, column) => padGraphemes(cell, widths[column] ?? 0)).join("  ").replace(/\s+$/, "") + "\n"
+  ).join("");
+}
+function relationsSection(relations) {
+  if (!Array.isArray(relations) || relations.length === 0) return "";
+  const lines = relations.map((relation) => `  ${str(relation["direction"]).padEnd(14)}${str(relation["other_issue"])}
+`).join("");
+  return "\nRelations:\n" + lines;
+}
+function childrenSection(children) {
+  if (!Array.isArray(children) || children.length === 0) return "";
+  const lines = children.map((child) => {
+    const state = str(path(child, "state", "name")) || "-";
+    return `  ${str(child["identifier"])}  [${state}]  ${truncate(child["title"])}
+`;
+  }).join("");
+  return "\nSub-issues:\n" + lines;
+}
+function commentsSection(comments2) {
+  if (!Array.isArray(comments2) || comments2.length === 0) return "";
+  const lines = comments2.map((comment2) => {
+    const author = clean(path(comment2, "author", "name") ?? "unknown");
+    return `  [${str(comment2["inserted_at"])}] ${author}: ${truncate(comment2["body"])}
+`;
+  }).join("");
+  return "\nComments:\n" + lines;
+}
+function imagesSection(images) {
+  if (images.length === 0) return "";
+  const lines = images.map((image) => `  [${image["source"]}] ${clean(image["path"])}
+`).join("");
+  return "\nImages (attachments downloaded locally \u2014 read them, they are part of the issue):\n" + lines;
+}
+function labelsLine(labels) {
+  if (!Array.isArray(labels) || labels.length === 0) return null;
+  return labels.map((label) => clean(label["name"])).join(", ");
+}
+function blockedLine(issue) {
+  if (issue["blocked"] === true && Array.isArray(issue["blocked_by"])) {
+    return `yes, by ${issue["blocked_by"].map(String).join(", ")}`;
+  }
+  return null;
+}
+function indent(text) {
+  return cleanMultiline(text).split("\n").map((line) => "  " + line).join("\n");
+}
+function cleanMultiline(text) {
+  return text.split("\n").map((line) => clean(line)).join("\n");
+}
+function truncate(text) {
+  if (text === null || text === void 0) return "";
+  const cleaned = clean(text);
+  const pieces = graphemes(cleaned);
+  if (pieces.length > TITLE_WIDTH) {
+    return pieces.slice(0, TITLE_WIDTH - 1).join("") + "\u2026";
+  }
+  return cleaned;
+}
+function str(value) {
+  return value === null || value === void 0 ? "" : String(value);
+}
+function path(record, ...keys) {
+  let current = record;
+  for (const key of keys) {
+    if (typeof current !== "object" || current === null) return null;
+    current = current[key];
+  }
+  return current ?? null;
+}
+
+// src/commands/issues.ts
+import { openSync, closeSync, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { basename } from "path";
+
+// src/core/attachments.ts
+import { chmodSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var REF = /\/(?:uploads\/harness|api\/v1)\/attachments\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([A-Za-z0-9._-]*\.(?:png|jpe?g|webp|gif))(?![A-Za-z0-9._-])/gi;
+var SOURCES = [
+  ["description", "description"],
+  ["design", "design"],
+  ["acceptance_criteria", "acceptance criteria"],
+  ["notes", "notes"]
+];
+var MAX_IMAGES_PER_SHOW = 20;
+var MAX_ATTACHMENT_BYTES = 25e6;
+function refs(issue) {
+  const texts = SOURCES.map(([field2, source]) => [issue[field2], source]);
+  const comments2 = Array.isArray(issue["comments"]) ? issue["comments"] : [];
+  for (const comment2 of comments2) texts.push([comment2["body"], "comment"]);
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [text, source] of texts) {
+    if (typeof text !== "string" || text === "") continue;
+    for (const match of text.matchAll(REF)) {
+      const ref = {
+        attachmentId: match[1].toLowerCase(),
+        file: match[2],
+        source
+      };
+      const key = `${ref.attachmentId}/${ref.file}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        found.push(ref);
+      }
+    }
+  }
+  return found;
+}
+async function fetchImages(client, issue, cacheDir) {
+  const allRefs = refs(issue);
+  const wanted = allRefs.slice(0, MAX_IMAGES_PER_SHOW);
+  const dropped = allRefs.slice(MAX_IMAGES_PER_SHOW);
+  const images = [];
+  const failures = [];
+  for (const ref of wanted) {
+    const result = await download(client, ref, cacheDir);
+    if (result.ok) {
+      images.push({
+        attachment_id: ref.attachmentId,
+        file: ref.file,
+        path: result.path,
+        source: ref.source
+      });
+    } else {
+      failures.push(`${ref.file}: ${result.message}`);
+    }
+  }
+  if (dropped.length > 0) {
+    failures.push(
+      `${dropped.length} further reference(s) skipped \u2014 the cap is ${MAX_IMAGES_PER_SHOW} images per show`
+    );
+  }
+  return { images, failures };
+}
+async function download(client, ref, cacheDir) {
+  const path2 = join(cacheDir, hostSegment(client.baseUrl), ref.attachmentId, ref.file);
+  try {
+    if (statSync(path2).size > 0) return { ok: true, path: path2 };
+  } catch {
+  }
+  const bytes = await fetchBytes(client, ref);
+  if (!bytes.ok) return bytes;
+  return write(path2, bytes.bytes);
+}
+function hostSegment(baseUrl) {
+  let host = "unknown-host";
+  let port = null;
+  try {
+    const parsed = new URL(baseUrl);
+    host = parsed.hostname.toLowerCase().replace(/[^a-z0-9.-]/g, "_");
+    port = parsed.port === "" ? null : Number(parsed.port);
+  } catch {
+  }
+  return port === null || port === 80 || port === 443 ? host : `${host}_${port}`;
+}
+async function fetchBytes(client, ref) {
+  let bytes;
+  try {
+    bytes = await client.getBytes(`/api/v1/attachments/${ref.attachmentId}/${ref.file}`);
+  } catch (error) {
+    if (error instanceof HttpError) return { ok: false, message: `${error.message} (HTTP ${error.status})` };
+    if (error instanceof TransportError) return { ok: false, message: error.message };
+    throw error;
+  }
+  if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
+    return { ok: false, message: `response is larger than the ${MAX_ATTACHMENT_BYTES}-byte attachment cap` };
+  }
+  if (!isImage(bytes)) return { ok: false, message: "response is not an image" };
+  return { ok: true, bytes };
+}
+function isImage(bytes) {
+  const startsWith = (prefix) => prefix.every((byte, index) => bytes[index] === byte);
+  if (startsWith([137, 80, 78, 71, 13, 10, 26, 10])) return true;
+  if (startsWith([255, 216, 255])) return true;
+  if (startsWith([71, 73, 70, 56, 55, 97])) return true;
+  if (startsWith([71, 73, 70, 56, 57, 97])) return true;
+  if (startsWith([82, 73, 70, 70]) && bytes.length >= 12) {
+    return bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80;
+  }
+  return false;
+}
+var partialCounter = 0;
+function write(path2, bytes) {
+  const partial = `${path2}.partial.${process.pid}.${++partialCounter}`;
+  try {
+    mkdirSync(dirname(path2), { recursive: true });
+    chmodSync(dirname(path2), 448);
+    writeFileSync(partial, bytes);
+    chmodSync(partial, 384);
+    renameSync(partial, path2);
+    return { ok: true, path: path2 };
+  } catch (error) {
+    rmSync(partial, { force: true });
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, message: `cannot write ${path2}: ${detail}` };
+  }
+}
+
+// src/core/pagination.ts
+function notices(meta, requestedPageSize, records) {
+  return capNotice(meta, requestedPageSize) + truncationNotice(meta, records);
+}
+function capNotice(meta, requestedPageSize) {
+  const served = meta?.page_size;
+  if (typeof served === "number" && typeof requestedPageSize === "number" && requestedPageSize > served) {
+    return `harness: --limit ${requestedPageSize} was capped at ${served} by the server.
+`;
+  }
+  return "";
+}
+function truncationNotice(meta, records) {
+  const total = meta?.total;
+  const page = meta?.page;
+  const pages = meta?.total_pages;
+  if (typeof total !== "number" || typeof page !== "number" || typeof pages !== "number") return "";
+  const shown = records.length;
+  if (shown < total) {
+    return `harness: showing ${shown} of ${total} (page ${page} of ${pages}) \u2014 pass --all for the rest, or --page to step through.
+`;
+  }
+  return "";
+}
+async function fetchEveryPage(fetchPage) {
+  const first = await fetchPage(1);
+  const totalPages = pageCount(first.meta);
+  if (totalPages === null) return first.data;
+  let records = first.data;
+  for (let page = 2; page <= totalPages; page++) {
+    const body = await fetchPage(page);
+    records = dedupe([...records, ...body.data]);
+  }
+  return records;
+}
+function pageCount(meta) {
+  const total = meta?.total_pages;
+  return typeof total === "number" && total > 0 ? total : null;
+}
+function dedupe(records) {
+  const seen = /* @__PURE__ */ new Set();
+  return records.filter((record) => {
+    const key = record["id"] ?? record;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// src/commands/issues.ts
+var PRIORITY_NAMES = { urgent: 1, high: 2, medium: 3, low: 4, none: 0 };
+var PRIORITY_RANK = { 1: 0, 2: 1, 3: 2, 4: 3, 0: 4 };
+var STATUS_STATE_TYPES = {
+  open: "backlog,unstarted",
+  in_progress: "started",
+  closed: "completed,canceled"
+};
+var READY_CLAIM_ATTEMPTS = 10;
+var IDENTIFIER_FORMAT = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+function requireIdentifiers(identifiers) {
+  const bad = identifiers.filter((identifier) => !IDENTIFIER_FORMAT.test(identifier));
+  if (bad.length > 0) {
+    throw new UsageError(`not an issue identifier: ${bad.join(", ")} (expected e.g. ALL-4223)`);
+  }
+}
+async function ready(ctx, opts) {
+  const params = { ...listParams(ctx, opts), ready: true };
+  const { records, notice } = await fetchIssues(ctx, params, opts);
+  const rank = (issue) => PRIORITY_RANK[issue["priority"]] ?? 4;
+  const sorted = [...records].sort((a, b) => rank(a) - rank(b));
+  if (opts.claim === true) return claimFirst(ctx, sorted);
+  return { json: sorted, human: issuesTable(sorted), notice };
+}
+async function blocked(ctx, opts) {
+  const params = { ...listParams(ctx, opts), blocked: true };
+  const { records, notice } = await fetchIssues(ctx, params, opts);
+  return { json: records, human: issuesTable(records), notice };
+}
+async function list(ctx, opts) {
+  const params = listParams(ctx, opts);
+  const { records, notice } = await fetchIssues(ctx, params, opts);
+  return { json: records, human: issuesTable(records), notice };
+}
+async function search(ctx, queryWords, opts) {
+  if (queryWords.length === 0) throw new UsageError("usage: harness search <query>");
+  const params = {
+    search: queryWords.join(" "),
+    page_size: opts.limit ?? 50,
+    page: opts.page ?? 1
+  };
+  const { records, notice } = await fetchIssues(ctx, params, opts);
+  return { json: records, human: issuesTable(records), notice };
+}
+async function show(ctx, identifier, opts) {
+  requireIdentifiers([identifier]);
+  const body = await ctx.client.get(`/api/v1/issues/${identifier}`, {
+    include: "relations,children,comments"
+  });
+  const issue = body.data;
+  let images = [];
+  let failures = [];
+  if (opts.images !== false) {
+    ({ images, failures } = await fetchImages(ctx.client, issue, ctx.config.cacheDir));
+  }
+  const json2 = images.length === 0 ? issue : { ...issue, local_images: images };
+  const human = issueDetail(issue, images);
+  const notice = failures.map((failure) => `harness: image not downloaded: ${clean(failure)}
+`).join("");
+  return notice === "" ? { json: json2, human } : { json: json2, human, notice };
+}
+async function stats2(ctx) {
+  const body = await ctx.client.get("/api/v1/stats");
+  return { json: body.data, human: stats(body.data) };
+}
+async function prime(ctx) {
+  const statsBody = await ctx.client.get("/api/v1/stats");
+  const readyBody = await ctx.client.get("/api/v1/issues", { ready: true, page_size: 10 });
+  const json2 = { stats: statsBody.data, ready: readyBody.data };
+  const human = "# Harness workflow context\n\n" + stats(statsBody.data) + "\nReady to work:\n" + issuesTable(readyBody.data) + `
+Workflow: harness ready \u2192 harness update <id> --claim \u2192 work \u2192
+harness close <id> --reason "Implemented in <commit-hash>" (response
+lists newly unblocked issues \u2014 surface them).
+Create tracked work BEFORE coding: harness create --title "\u2026" --type task.
+Dependencies: harness dep add <issue> <blocker> (blocker blocks issue).
+Before reporting done: close the issues you finished.
+`;
+  return { json: json2, human };
+}
+async function version(config) {
+  let server;
+  if (config === null || config.baseUrl === "") {
+    server = "unconfigured";
+  } else {
+    server = await new Client(config).serverVersion().catch(() => "unreachable");
+  }
+  return { json: { cli: CLI_VERSION, server }, human: `harness ${CLI_VERSION} (server API ${server})
+` };
+}
+async function create(ctx, opts) {
+  const labels = wantedLabels(opts);
+  if (opts.title === void 0) {
+    throw new UsageError("usage: harness create --title <title> [--team <key>] \u2026");
+  }
+  validateType(opts.type);
+  const team = requiredTeam(ctx, opts.team);
+  const priority = optionalPriority(opts.priority);
+  const dueDate = optionalDueDate(opts.dueDate);
+  let body = { title: opts.title };
+  body = putOpt(body, "description", opts.description);
+  body = putOpt(body, "design", opts.design);
+  body = putOpt(body, "notes", opts.notes);
+  body = putOpt(body, "acceptance_criteria", opts.acceptance);
+  body = putOpt(body, "parent", opts.parent);
+  body = putPresent(body, "priority", priority);
+  body = putDueDate(body, dueDate);
+  body = putAssignee(body, opts.assignee);
+  const created = await ctx.client.post(`/api/v1/teams/${team}/issues`, body);
+  const issue = created.data;
+  try {
+    const labeled = await applyLabels(ctx, issue, labels);
+    return {
+      json: labeled,
+      human: `Created ${str2(labeled["identifier"])}: ${clean(labeled["title"])}
+`
+    };
+  } catch (error) {
+    if (error instanceof HttpError || error instanceof TransportError) {
+      throw new CommandError(
+        `created ${str2(issue["identifier"])}, but applying labels failed: ${errorText(error)}`
+      );
+    }
+    throw error;
+  }
+}
+async function update(ctx, identifier, opts) {
+  requireIdentifiers([identifier]);
+  if (opts.notes !== void 0 && opts.appendNotes !== void 0) {
+    throw new UsageError("--notes replaces and --append-notes appends \u2014 pass one, not both");
+  }
+  if (opts.claim === true && opts.assignee !== void 0) {
+    throw new UsageError(
+      "--claim takes the issue and starts it; --assignee only sets the field \u2014 pass one, not both (--claim to take it yourself, --assignee to hand it to someone)"
+    );
+  }
+  const priority = optionalPriority(opts.priority);
+  const dueDate = optionalDueDate(opts.dueDate);
+  let issue = null;
+  if (opts.claim === true) {
+    const body = await ctx.client.post(`/api/v1/issues/${identifier}/claim`);
+    issue = body.data;
+  }
+  let patch = {};
+  patch = putOpt(patch, "title", opts.title);
+  patch = putOpt(patch, "description", opts.description);
+  patch = putOpt(patch, "design", opts.design);
+  patch = putOpt(patch, "notes", opts.notes);
+  patch = putOpt(patch, "acceptance_criteria", opts.acceptance);
+  patch = putOpt(patch, "parent", opts.parent);
+  patch = putPresent(patch, "priority", priority);
+  patch = putDueDate(patch, dueDate);
+  patch = putAssignee(patch, opts.assignee);
+  if (opts.appendNotes !== void 0) {
+    const current = await ctx.client.get(`/api/v1/issues/${identifier}`);
+    const existing = current.data["notes"];
+    const combined = existing === null || existing === void 0 || existing === "" ? opts.appendNotes : `${str2(existing)}
+
+${opts.appendNotes}`;
+    patch["notes"] = combined;
+  }
+  if (Object.keys(patch).length > 0) {
+    const body = await ctx.client.patch(`/api/v1/issues/${identifier}`, patch);
+    issue = body.data;
+  }
+  if (opts.state !== void 0) {
+    issue = await setState(ctx, identifier, opts.state);
+  }
+  if (issue === null) {
+    throw new UsageError("usage: harness update <id> --claim | --title \u2026 | --state <name> | \u2026");
+  }
+  return { json: issue, human: `Updated ${str2(issue["identifier"])}
+` };
+}
+async function close(ctx, identifiers, opts) {
+  if (identifiers.length === 0) {
+    throw new UsageError("usage: harness close <id> [<id>\u2026] [--reason <text>] [--cancel]");
+  }
+  requireIdentifiers(identifiers);
+  let body = {};
+  body = putPresent(body, "reason", opts.reason);
+  body = putPresent(body, "cancel", opts.cancel);
+  const results = [];
+  for (const identifier of identifiers) {
+    try {
+      const response = await ctx.client.post(`/api/v1/issues/${identifier}/close`, body);
+      results.push({ identifier, ok: true, response });
+    } catch (error) {
+      if (error instanceof HttpError || error instanceof TransportError) {
+        results.push({ identifier, ok: false, error });
+      } else {
+        throw error;
+      }
+    }
+  }
+  const human = results.map((result) => closeLine(result)).join("");
+  const json2 = results.map(
+    (result) => result.ok ? { identifier: result.identifier, closed: true, unblocked: result.response["unblocked"] ?? null } : { identifier: result.identifier, closed: false, error: errorText(result.error) }
+  );
+  const partial = results.some((result) => !result.ok);
+  return partial ? { json: json2, human, partial: true } : { json: json2, human };
+}
+function closeLine(result) {
+  if (!result.ok) return `FAILED ${result.identifier}: ${errorText(result.error)}
+`;
+  const unblocked = result.response["unblocked"];
+  if (Array.isArray(unblocked) && unblocked.length > 0) {
+    return `Closed ${result.identifier} \u2014 unblocked: ${unblocked.map(String).join(", ")}
+`;
+  }
+  return `Closed ${result.identifier}
+`;
+}
+async function archive(ctx, identifiers, opts) {
+  if (identifiers.length === 0) {
+    throw new UsageError("usage: harness archive <id> [<id>\u2026] [--restore]");
+  }
+  requireIdentifiers(identifiers);
+  const archived = opts.restore !== true;
+  const verb = archived ? "Archived" : "Restored";
+  const results = [];
+  for (const identifier of identifiers) {
+    try {
+      const body = await ctx.client.put(`/api/v1/issues/${identifier}/archive_state`, { archived });
+      results.push({ identifier, ok: true, issue: body.data });
+    } catch (error) {
+      if (error instanceof HttpError || error instanceof TransportError) {
+        results.push({ identifier, ok: false, error });
+      } else {
+        throw error;
+      }
+    }
+  }
+  const human = results.map(
+    (result) => result.ok ? `${verb} ${result.identifier}
+` : `FAILED ${result.identifier}: ${errorText(result.error)}
+`
+  ).join("");
+  const json2 = results.map(
+    (result) => result.ok ? { identifier: result.identifier, archived } : { identifier: result.identifier, error: errorText(result.error) }
+  );
+  const partial = results.some((result) => !result.ok);
+  return partial ? { json: json2, human, partial: true } : { json: json2, human };
+}
+async function comments(ctx, identifier) {
+  requireIdentifiers([identifier]);
+  const body = await ctx.client.get(`/api/v1/issues/${identifier}/comments`);
+  if (body.data.length === 0) return { json: body.data, human: "No comments.\n" };
+  const human = body.data.map((comment2) => {
+    const author = clean((comment2["author"] ?? {})["name"] ?? "unknown");
+    const text = cleanMultiline(str2(comment2["body"])).split("\n").map((line) => "  " + line).join("\n");
+    return `[${str2(comment2["inserted_at"])}] ${author}:
+${text}
+`;
+  }).join("\n");
+  return { json: body.data, human };
+}
+async function dep(ctx, verb, issue, blocker) {
+  requireIdentifiers([issue, blocker]);
+  if (verb === "add") {
+    const response = await ctx.client.post(`/api/v1/issues/${issue}/relations`, {
+      type: "blocked_by",
+      related_issue: blocker
+    });
+    return { json: response.data, human: `${blocker} now blocks ${issue}
+` };
+  }
+  if (verb === "rm") {
+    const body = await ctx.client.get(`/api/v1/issues/${issue}/relations`);
+    const relation = (body.data ?? []).find(
+      (candidate) => candidate["direction"] === "blocked_by" && candidate["other_issue"] === blocker
+    );
+    if (relation === void 0) throw new CommandError(`${blocker} does not block this issue.`);
+    await ctx.client.delete(`/api/v1/issues/${issue}/relations/${str2(relation["id"])}`);
+    return { json: { deleted: relation["id"] }, human: `${blocker} no longer blocks ${issue}
+` };
+  }
+  throw new UsageError("usage: harness dep add|rm <issue> <blocker>  (the blocker blocks the issue)");
+}
+async function comment(ctx, identifier, textWords, mentions) {
+  requireIdentifiers([identifier]);
+  if (textWords.length === 0) {
+    throw new UsageError("usage: harness comment <id> <text> [--mention NAME]\u2026");
+  }
+  const body = { body: textWords.join(" ") };
+  if (mentions.length > 0) body["mentions"] = mentions;
+  const response = await ctx.client.post(`/api/v1/issues/${identifier}/comments`, body);
+  return { json: response.data, human: `Commented on ${identifier}
+` };
+}
+var MAX_ATTACHMENT_BYTES2 = 25e6;
+async function attachImage(ctx, path2) {
+  attachableFile(path2);
+  const bytes = readFileSync2(path2);
+  const form = new FormData();
+  form.set("file", new File([bytes], basename(path2)));
+  const body = await ctx.client.postMultipart("/api/v1/uploads", form, bytes.byteLength);
+  const attachment = body.data;
+  const markdown = attachment["markdown"];
+  if (typeof markdown !== "string") throw new CommandError("the upload response carried no markdown reference");
+  return { json: attachment, human: clean(markdown) + "\n" };
+}
+function attachableFile(path2) {
+  let fileStats;
+  try {
+    fileStats = statSync2(path2);
+  } catch (error) {
+    throw new LocalError(`cannot read ${path2}: ${posixDetail(error)}`);
+  }
+  if (!fileStats.isFile()) {
+    const kind = fileStats.isDirectory() ? "directory" : "special file";
+    throw new LocalError(`${path2} is a ${kind}, not a file.`);
+  }
+  if (fileStats.size > MAX_ATTACHMENT_BYTES2) {
+    throw new LocalError(
+      `${path2} is too large: ${fileStats.size} bytes, and attachments are capped at ${MAX_ATTACHMENT_BYTES2}.`
+    );
+  }
+  try {
+    closeSync(openSync(path2, "r"));
+  } catch (error) {
+    throw new LocalError(`cannot read ${path2}: ${posixDetail(error)}`);
+  }
+}
+function posixDetail(error) {
+  const code = error.code;
+  if (code === "ENOENT") return "no such file or directory";
+  if (code === "EACCES") return "permission denied";
+  return error instanceof Error ? error.message : String(error);
+}
+async function claimFirst(ctx, issues) {
+  for (const issue of issues.slice(0, READY_CLAIM_ATTEMPTS)) {
+    try {
+      const body = await ctx.client.post(`/api/v1/issues/${str2(issue["identifier"])}/claim`);
+      const claimed = body.data;
+      return {
+        json: claimed,
+        human: `Claimed ${str2(claimed["identifier"])}: ${clean(claimed["title"])}
+`
+      };
+    } catch (error) {
+      if (error instanceof HttpError && error.status === 409) continue;
+      throw error;
+    }
+  }
+  throw new CommandError("No claimable ready issues.");
+}
+async function setState(ctx, identifier, stateName) {
+  const showBody = await ctx.client.get(`/api/v1/issues/${identifier}`);
+  const teamKey = str2((showBody.data["team"] ?? {})["key"]);
+  const statesBody = await ctx.client.get(
+    `/api/v1/teams/${teamKey}/workflow_states`
+  );
+  const wanted = stateName.toLowerCase();
+  const state = statesBody.data.find(
+    (candidate) => str2(candidate["name"]).toLowerCase() === wanted || str2(candidate["type"]) === wanted
+  );
+  if (state === void 0) {
+    const names = statesBody.data.map((candidate) => str2(candidate["name"])).join(", ");
+    throw new CommandError(`No workflow state matches "${stateName}". States: ${names}`);
+  }
+  const body = await ctx.client.put(`/api/v1/issues/${identifier}/state`, { state_id: state["id"] });
+  return body.data;
+}
+var ISSUE_TYPES = ["task", "bug", "feature", "epic"];
+function wantedLabels(opts) {
+  const typeLabels = opts.type === void 0 ? [] : [`type/${opts.type}`];
+  return [...typeLabels, ...opts.label ?? []];
+}
+function validateType(type) {
+  if (type !== void 0 && !ISSUE_TYPES.includes(type)) {
+    throw new UsageError(`not an issue type: ${type} (expected ${ISSUE_TYPES.join(", ")})`);
+  }
+}
+async function applyLabels(ctx, issue, names) {
+  if (names.length === 0) return issue;
+  const labelsBody = await ctx.client.get("/api/v1/labels");
+  const byName = new Map(labelsBody.data.map((label) => [str2(label["name"]), label["id"]]));
+  const ids = [];
+  for (const name of names) {
+    const existing = byName.get(name);
+    if (existing !== void 0) {
+      ids.push(existing);
+    } else {
+      const created = await ctx.client.post("/api/v1/labels", {
+        name,
+        color: "gray"
+      });
+      ids.push(created.data["id"]);
+    }
+  }
+  const body = await ctx.client.put(`/api/v1/issues/${str2(issue["identifier"])}/labels`, {
+    label_ids: ids
+  });
+  return body.data;
+}
+async function fetchIssues(ctx, params, opts) {
+  if (opts.all === true && opts.page !== void 0) {
+    throw new UsageError("--all reads every page from the first \u2014 pass --all or --page, not both");
+  }
+  if (opts.all === true) {
+    const records2 = await fetchEveryPage(
+      (page) => ctx.client.get("/api/v1/issues", { ...params, page })
+    );
+    return { records: records2, notice: "" };
+  }
+  const body = await ctx.client.get("/api/v1/issues", params);
+  const records = body.data;
+  const requested = typeof params["page_size"] === "number" ? params["page_size"] : void 0;
+  return { records, notice: notices(body.meta, requested, records) };
+}
+function listParams(ctx, opts) {
+  if (opts.type !== void 0 && opts.label !== void 0) {
+    throw new UsageError("--type is a label filter itself \u2014 pass either --type or --label, not both");
+  }
+  validateType(opts.type);
+  let params = withTeam({ page_size: opts.limit ?? 50, page: opts.page ?? 1 }, ctx, opts);
+  params = putParam(params, "search", opts.search);
+  params = putParam(params, "parent", opts.parent);
+  params = putParam(params, "label", opts.label);
+  params = putParam(params, "scope", opts.scope);
+  params = putParam(params, "assignee", opts.assignee);
+  if (opts.type !== void 0) params = putParam(params, "label", `type/${opts.type}`);
+  if (opts.status !== void 0) {
+    const stateTypes = Object.hasOwn(STATUS_STATE_TYPES, opts.status) ? STATUS_STATE_TYPES[opts.status] : void 0;
+    if (stateTypes === void 0) {
+      throw new UsageError(`status must be one of: ${Object.keys(STATUS_STATE_TYPES).join(", ")}`);
+    }
+    params = putParam(params, "state_type", stateTypes);
+  }
+  const priority = optionalPriority(opts.priority);
+  if (priority !== null) params = putParam(params, "priority", priority);
+  return params;
+}
+function optionalPriority(value) {
+  if (value === void 0) return null;
+  const named = Object.hasOwn(PRIORITY_NAMES, value) ? PRIORITY_NAMES[value] : void 0;
+  if (named !== void 0) return named;
+  if (/^\d+$/.test(value)) {
+    throw new UsageError(
+      `Bare numeric priorities are refused: bd and harness disagree on what
+the numbers mean, so a habit-typed number would silently file the
+wrong priority.
+
+  bd:      0=critical 1=high 2=medium 3=normal 4=backlog
+  harness: 0=none     1=urgent 2=high 3=medium 4=low
+
+Use a name instead: --priority urgent|high|medium|low|none
+`
+    );
+  }
+  throw new UsageError("priority must be one of: urgent, high, medium, low, none");
+}
+function optionalDueDate(value) {
+  if (value === void 0) return null;
+  const trimmed = value.trim();
+  if (trimmed === "") return "clear";
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+  if (match === null) throw new UsageError(`not a date: ${trimmed} (expected YYYY-MM-DD)`);
+  const [, year, month, day] = match.map(Number);
+  const candidate = /* @__PURE__ */ new Date(0);
+  candidate.setUTCFullYear(year, month - 1, day);
+  const real = candidate.getUTCFullYear() === year && candidate.getUTCMonth() === month - 1 && candidate.getUTCDate() === day;
+  if (!real) throw new UsageError(`not a date: ${trimmed} (no such day on the calendar)`);
+  return trimmed;
+}
+var TEAM_KEY_FORMAT = /^[A-Za-z][A-Za-z0-9]*$/;
+function requiredTeam(ctx, team) {
+  const resolved = team ?? ctx.config.team ?? void 0;
+  if (resolved === void 0) throw new UsageError("No team given. Pass --team <key> or set HARNESS_TEAM.");
+  if (!TEAM_KEY_FORMAT.test(resolved)) throw new UsageError(`not a team key: ${resolved} (expected e.g. ALL)`);
+  return resolved;
+}
+function withTeam(params, ctx, opts) {
+  const team = opts.team ?? ctx.config.team ?? void 0;
+  return team === void 0 ? params : { ...params, team };
+}
+function putParam(params, key, value) {
+  return value === void 0 ? params : { ...params, [key]: value };
+}
+function putOpt(body, field2, value) {
+  return value === void 0 ? body : { ...body, [field2]: value };
+}
+function putPresent(body, key, value) {
+  if (value === null || value === void 0 || value === false) return body;
+  return { ...body, [key]: value };
+}
+function putDueDate(body, dueDate) {
+  if (dueDate === null) return body;
+  if (dueDate === "clear") return { ...body, due_date: null };
+  return { ...body, due_date: dueDate };
+}
+function putAssignee(body, assignee) {
+  if (assignee === void 0) return body;
+  return { ...body, assignee: assignee.trim() === "" ? null : assignee };
+}
+function errorText(error) {
+  if (error instanceof HttpError) return `${clean(error.message)} (HTTP ${error.status})`;
+  return `cannot reach the API: ${clean(error.message)}`;
+}
+function str2(value) {
+  return value === null || value === void 0 ? "" : String(value);
+}
+
+// src/commands/extended.ts
+var SAFE_ID = /^[A-Za-z0-9._-]+$/;
+function requireSafeId(kind, id) {
+  if (!SAFE_ID.test(id)) throw new UsageError(`not a ${kind} id: ${id}`);
+}
+function str3(value) {
+  return value === null || value === void 0 ? "" : String(value);
+}
+function field(row, ...keys) {
+  let current = row;
+  for (const key of keys) {
+    if (typeof current !== "object" || current === null) return null;
+    current = current[key];
+  }
+  return current ?? null;
+}
+function putOpt2(body, key, value) {
+  return value === void 0 ? body : { ...body, [key]: value };
+}
+function putDate(body, key, raw) {
+  const parsed = optionalDueDate(raw);
+  if (parsed === null) return body;
+  return { ...body, [key]: parsed === "clear" ? null : parsed };
+}
+async function paginatedRead(ctx, path2, params, opts) {
+  if (opts.all === true && opts.page !== void 0) {
+    throw new UsageError("--all reads every page from the first \u2014 pass --all or --page, not both");
+  }
+  if (opts.all === true) {
+    const records = await fetchEveryPage((page) => ctx.client.get(path2, { ...params, page }));
+    return { records, notice: "" };
+  }
+  const body = await ctx.client.get(path2, params);
+  const requested = typeof params["page_size"] === "number" ? params["page_size"] : void 0;
+  return { records: body.data, notice: notices(body.meta, requested, body.data) };
+}
+async function projectList(ctx, opts) {
+  let params = { page_size: opts.limit ?? 50, page: opts.page ?? 1 };
+  if (opts.search !== void 0) params = { ...params, search: opts.search };
+  if (opts.state !== void 0) params = { ...params, state: opts.state };
+  const { records, notice } = await paginatedRead(ctx, "/api/v1/projects", params, opts);
+  const human = records.length === 0 ? "No projects.\n" : table(
+    ["ID", "STATE", "LEAD", "TARGET", "NAME"],
+    records.map((project) => [
+      str3(project["id"]),
+      str3(project["state"]) || "-",
+      str3(field(project, "lead", "name")) || "-",
+      str3(project["target_date"]) || "-",
+      str3(project["name"])
+    ])
+  );
+  return { json: records, human, notice };
+}
+async function projectShow(ctx, id) {
+  requireSafeId("project", id);
+  const body = await ctx.client.get(`/api/v1/projects/${id}`);
+  const project = body.data;
+  const fields = [
+    ["State", project["state"]],
+    ["Lead", field(project, "lead", "name")],
+    ["Start", project["start_date"]],
+    ["Target", project["target_date"]],
+    ["Updated", project["updated_at"]]
+  ];
+  const fieldLines = fields.filter(([, value]) => value !== null && value !== void 0 && value !== "").map(([label, value]) => `  ${(label + ":").padEnd(12)}${clean(value)}
+`).join("");
+  const sections = [
+    ["Summary", project["summary"]],
+    ["Description", project["description"]]
+  ];
+  const sectionText = sections.filter(([, text]) => text !== null && text !== void 0 && text !== "").map(([title, text]) => `
+${title}:
+${indent2(String(text))}
+`).join("");
+  const milestones = Array.isArray(project["milestones"]) ? project["milestones"] : [];
+  const milestoneText = milestones.length === 0 ? "" : "\nMilestones:\n" + milestones.map((milestone) => `  ${(str3(milestone["target_date"]) || "-").padEnd(12)}${clean(milestone["name"])}
+`).join("");
+  const human = `${str3(project["id"])} \xB7 ${clean(project["name"])}
+` + fieldLines + sectionText + milestoneText;
+  return { json: project, human };
+}
+function projectBody(opts) {
+  let body = {};
+  body = putOpt2(body, "name", opts.name);
+  body = putOpt2(body, "description", opts.description);
+  body = putOpt2(body, "summary", opts.summary);
+  body = putOpt2(body, "state", opts.state);
+  body = putOpt2(body, "lead_id", opts.lead);
+  body = putDate(body, "start_date", opts.startDate);
+  body = putDate(body, "target_date", opts.targetDate);
+  return body;
+}
+async function projectCreate(ctx, opts) {
+  if (opts.name === void 0) throw new UsageError("usage: harness project create --name <name> \u2026");
+  const body = await ctx.client.post("/api/v1/projects", projectBody(opts));
+  const project = body.data;
+  return { json: project, human: `Created project ${clean(project["name"])} (${str3(project["id"])})
+` };
+}
+async function projectUpdate(ctx, id, opts) {
+  requireSafeId("project", id);
+  const patch = projectBody(opts);
+  if (Object.keys(patch).length === 0) {
+    throw new UsageError("usage: harness project update <id> --name \u2026 | --state \u2026 | \u2026");
+  }
+  const body = await ctx.client.patch(`/api/v1/projects/${id}`, patch);
+  return { json: body.data, human: `Updated project ${str3(body.data["id"])}
+` };
+}
+async function milestoneList(ctx, project) {
+  if (project === void 0) throw new UsageError("usage: harness milestone list --project <id>");
+  requireSafeId("project", project);
+  const body = await ctx.client.get(`/api/v1/projects/${project}/milestones`);
+  const human = body.data.length === 0 ? "No milestones.\n" : table(
+    ["ID", "TARGET", "NAME"],
+    body.data.map((milestone) => [
+      str3(milestone["id"]),
+      str3(milestone["target_date"]) || "-",
+      str3(milestone["name"])
+    ])
+  );
+  return { json: body.data, human };
+}
+async function milestoneCreate(ctx, opts) {
+  if (opts.project === void 0 || opts.name === void 0) {
+    throw new UsageError("usage: harness milestone create --project <id> --name <name> [--description TEXT] [--target-date YYYY-MM-DD]");
+  }
+  requireSafeId("project", opts.project);
+  let body = { name: opts.name };
+  body = putOpt2(body, "description", opts.description);
+  body = putDate(body, "target_date", opts.targetDate);
+  const response = await ctx.client.post(`/api/v1/projects/${opts.project}/milestones`, body);
+  const milestone = response.data;
+  return {
+    json: milestone,
+    human: `Created milestone ${clean(milestone["name"])} (${str3(milestone["id"])})
+`
+  };
+}
+async function docList(ctx, opts) {
+  let params = { page_size: opts.limit ?? 50, page: opts.page ?? 1 };
+  if (opts.search !== void 0) params = { ...params, search: opts.search };
+  const { records, notice } = await paginatedRead(ctx, "/api/v1/documents", params, opts);
+  const human = records.length === 0 ? "No documents.\n" : table(
+    ["ID", "UPDATED", "TITLE"],
+    records.map((doc) => [str3(doc["id"]), str3(doc["updated_at"]) || "-", str3(doc["title"])])
+  );
+  return { json: records, human, notice };
+}
+async function docShow(ctx, id) {
+  requireSafeId("document", id);
+  const body = await ctx.client.get(`/api/v1/documents/${id}`);
+  const doc = body.data;
+  const content = doc["content"];
+  const human = `${str3(doc["id"])} \xB7 ${clean(doc["title"])}
+  Updated:    ${clean(doc["updated_at"])}
+` + (content === null || content === void 0 || content === "" ? "" : "\n" + cleanMultiline(String(content)) + "\n");
+  return { json: doc, human };
+}
+async function docCreate(ctx, opts) {
+  if (opts.title === void 0) throw new UsageError("usage: harness doc create --title <title> [--content TEXT] [--project ID]");
+  let body = { title: opts.title };
+  body = putOpt2(body, "content", opts.content);
+  body = putOpt2(body, "project_id", opts.project);
+  const response = await ctx.client.post("/api/v1/documents", body);
+  const doc = response.data;
+  return { json: doc, human: `Created document ${clean(doc["title"])} (${str3(doc["id"])})
+` };
+}
+async function docUpdate(ctx, id, opts) {
+  requireSafeId("document", id);
+  let patch = {};
+  patch = putOpt2(patch, "title", opts.title);
+  patch = putOpt2(patch, "content", opts.content);
+  patch = putOpt2(patch, "project_id", opts.project);
+  if (Object.keys(patch).length === 0) {
+    throw new UsageError("usage: harness doc update <id> --title \u2026 | --content \u2026 | --project \u2026");
+  }
+  const response = await ctx.client.patch(`/api/v1/documents/${id}`, patch);
+  return { json: response.data, human: `Updated document ${str3(response.data["id"])}
+` };
+}
+async function linkList(ctx, issue) {
+  requireIdentifiers([issue]);
+  const body = await ctx.client.get(`/api/v1/issues/${issue}/links`);
+  const human = body.data.length === 0 ? "No links.\n" : table(
+    ["ID", "URL", "TITLE"],
+    body.data.map((link) => [str3(link["id"]), str3(link["url"]), str3(link["title"]) || "-"])
+  );
+  return { json: body.data, human };
+}
+async function linkAdd(ctx, issue, url, title) {
+  requireIdentifiers([issue]);
+  let body = { url };
+  body = putOpt2(body, "title", title);
+  const response = await ctx.client.post(`/api/v1/issues/${issue}/links`, body);
+  return { json: response.data, human: `Linked ${clean(url)} to ${issue}
+` };
+}
+async function linkRm(ctx, issue, idOrUrl) {
+  requireIdentifiers([issue]);
+  const body = await ctx.client.get(`/api/v1/issues/${issue}/links`);
+  const link = body.data.find((candidate) => candidate["id"] === idOrUrl || candidate["url"] === idOrUrl);
+  if (link === void 0) {
+    throw new UsageError(`no link on ${issue} matches ${idOrUrl} (by id or exact URL)`);
+  }
+  await ctx.client.delete(`/api/v1/issues/${issue}/links/${str3(link["id"])}`);
+  return { json: { deleted: link["id"] }, human: `Removed ${clean(link["url"])} from ${issue}
+` };
+}
+async function labelList(ctx) {
+  const body = await ctx.client.get("/api/v1/labels");
+  const human = body.data.length === 0 ? "No labels.\n" : table(
+    ["NAME", "COLOR", "ID"],
+    body.data.map((label) => [str3(label["name"]), str3(label["color"]) || "-", str3(label["id"])])
+  );
+  return { json: body.data, human };
+}
+async function labelCreate(ctx, name, color) {
+  if (name === void 0) throw new UsageError("usage: harness label create <name> [--color <color>]");
+  let body = { name };
+  body = putOpt2(body, "color", color);
+  const response = await ctx.client.post("/api/v1/labels", body);
+  return { json: response.data, human: `Created label ${clean(response.data["name"])}
+` };
+}
+async function teamList(ctx) {
+  const body = await ctx.client.get("/api/v1/teams");
+  const human = body.data.length === 0 ? "No teams.\n" : table(
+    ["KEY", "NAME"],
+    body.data.map((team) => [str3(team["key"]), str3(team["name"])])
+  );
+  return { json: body.data, human };
+}
+async function workflowStates(ctx, team) {
+  const key = requiredTeam({ client: ctx.client, config: ctx.config }, team);
+  const body = await ctx.client.get(`/api/v1/teams/${key}/workflow_states`);
+  const human = body.data.length === 0 ? "No workflow states.\n" : table(
+    ["NAME", "TYPE"],
+    body.data.map((state) => [str3(state["name"]), str3(state["type"])])
+  );
+  return { json: body.data, human };
+}
+async function userList(ctx) {
+  const body = await ctx.client.get("/api/v1/users");
+  const human = body.data.length === 0 ? "No users.\n" : table(
+    ["NAME", "EMAIL", "ID"],
+    body.data.map((user) => [str3(user["name"]), str3(user["email"]), str3(user["id"])])
+  );
+  return { json: body.data, human };
+}
+async function upload(ctx, path2) {
+  return attachImage(ctx, path2);
+}
+function indent2(text) {
+  return cleanMultiline(text).split("\n").map((line) => "  " + line).join("\n");
+}
+
+// src/core/credentials.ts
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname2, isAbsolute, join as join2 } from "path";
+function defaultCredentialsPath(env = process.env) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg !== void 0 && xdg !== "" && isAbsolute(xdg) ? xdg : join2(homedir(), ".config");
+  return join2(base, "harness", "credentials.json");
+}
+function readCredentials(path2) {
+  try {
+    const parsed = JSON.parse(readFileSync3(path2, "utf8"));
+    if (typeof parsed === "object" && parsed !== null) {
+      const { url, token } = parsed;
+      if (typeof url === "string" && typeof token === "string") return { url, token };
+    }
+  } catch {
+  }
+  return null;
+}
+var uniqueCounter = 0;
+function writeCredentials(path2, url, token) {
+  mkdirSync2(dirname2(path2), { recursive: true });
+  const tempPath = `${path2}.${process.pid}.${++uniqueCounter}.tmp`;
+  try {
+    writeFileSync2(tempPath, "", { mode: 384 });
+    chmodSync2(tempPath, 384);
+    writeFileSync2(tempPath, JSON.stringify({ url, token }));
+    renameSync2(tempPath, path2);
+  } finally {
+    rmSync2(tempPath, { force: true });
+  }
+}
+function deleteCredentials(path2) {
+  rmSync2(path2, { force: true });
+}
+
+// src/core/config.ts
+import { homedir as homedir2, tmpdir } from "os";
+import { isAbsolute as isAbsolute2, join as join3 } from "path";
+var DEFAULT_BASE_URL = "https://harness.infra.one";
+function resolveConfig(env = process.env, credentialsPath) {
+  const path2 = credentialsPath ?? defaultCredentialsPath(env);
+  const stored = readCredentials(path2);
+  const envUrl = blankToNull(env["HARNESS_API_URL"]);
+  const envToken = blankToNull(env["HARNESS_API_TOKEN"]);
+  const rawUrl = envUrl ?? (envToken === null && stored !== null ? stored.url : DEFAULT_BASE_URL);
+  const validated = validateBaseUrl(rawUrl);
+  if (!validated.ok) return { kind: "error", message: validated.message };
+  const baseUrl = rawUrl.replace(/\/+$/, "");
+  let token;
+  if (envToken !== null) {
+    token = envToken;
+  } else if (stored !== null && normalize(stored.url) !== null && normalize(stored.url) === normalize(baseUrl)) {
+    token = stored.token;
+  } else {
+    return { kind: "needs-login", baseUrl };
+  }
+  return {
+    kind: "ok",
+    config: {
+      baseUrl,
+      token,
+      actor: blankToNull(env["HARNESS_ACTOR"]),
+      team: blankToNull(env["HARNESS_TEAM"]),
+      cacheDir: resolveCacheDir(env)
+    }
+  };
+}
+function resolveCacheDir(env = process.env) {
+  return absolute(env["HARNESS_CACHE_DIR"]) ?? join3(cacheHome(env), "harness", "attachments");
+}
+function absolute(value) {
+  return value !== void 0 && value !== "" && isAbsolute2(value) ? value : null;
+}
+function cacheHome(env) {
+  return absolute(env["XDG_CACHE_HOME"]) ?? join3(homedir2() || tmpdir(), ".cache");
+}
+function normalize(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const port = parsed.port !== "" ? parsed.port : parsed.protocol === "https:" ? "443" : parsed.protocol === "http:" ? "80" : "";
+  return JSON.stringify([parsed.protocol, parsed.hostname, port, parsed.pathname.replace(/\/+$/, "")]);
+}
+function validateBaseUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    return { ok: false, message: `HARNESS_API_URL must be an http(s) URL with a host, got: ${baseUrl}` };
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    return { ok: false, message: "HARNESS_API_URL must not embed credentials (user:pass@) \u2014 use HARNESS_API_TOKEN" };
+  }
+  if (parsed.protocol === "https:" && parsed.hostname !== "") return { ok: true };
+  if (parsed.protocol === "http:") {
+    if (["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)) return { ok: true };
+    return {
+      ok: false,
+      message: `refusing plain-http HARNESS_API_URL (${baseUrl}) \u2014 the API token would travel in cleartext. Use https, or http against localhost only.`
+    };
+  }
+  return { ok: false, message: `HARNESS_API_URL must be an http(s) URL with a host, got: ${baseUrl}` };
+}
+function loginHelp(baseUrl) {
+  return `Not signed in to ${baseUrl}.
+
+Interactively, in a terminal (not from inside an agent \u2014 the browser
+tab needs someone to see it):
+
+    harness login
+
+For agents and CI, mint an API token (admin \u2192 API tokens) with the
+harness:read scope \u2014 plus harness:write only where the workflow
+creates or closes \u2014 set an expiry, and export it:
+
+    export HARNESS_API_TOKEN=aone_...
+`;
+}
+function blankToNull(value) {
+  if (value === void 0 || value.trim() === "") return null;
+  return value;
+}
+
+export {
+  HttpError,
+  UpgradeRequiredError,
+  TransportError,
+  UsageError,
+  LocalError,
+  CommandError,
+  CLI_VERSION,
+  Client,
+  clean,
+  json,
+  requireIdentifiers,
+  ready,
+  blocked,
+  list,
+  search,
+  show,
+  stats2 as stats,
+  prime,
+  version,
+  create,
+  update,
+  close,
+  archive,
+  comments,
+  dep,
+  comment,
+  attachImage,
+  projectList,
+  projectShow,
+  projectCreate,
+  projectUpdate,
+  milestoneList,
+  milestoneCreate,
+  docList,
+  docShow,
+  docCreate,
+  docUpdate,
+  linkList,
+  linkAdd,
+  linkRm,
+  labelList,
+  labelCreate,
+  teamList,
+  workflowStates,
+  userList,
+  upload,
+  defaultCredentialsPath,
+  readCredentials,
+  writeCredentials,
+  deleteCredentials,
+  DEFAULT_BASE_URL,
+  resolveConfig,
+  validateBaseUrl,
+  loginHelp
+};