linear-sdk-cli 0.1.0

package/src/lib/shape.ts

@@ -0,0 +1,273 @@
+/**
+ * The vocabulary `linear commands --json` uses to say what a command's `--json`
+ * output looks like, so an agent driving the CLI cold knows that a list row has
+ * `.state.name` and a detail has `.team.key` before it runs anything (TES-610).
+ *
+ * A shape is a JSON value:
+ *   - a scalar type name:      "string" | "number" | "boolean" | "unknown" | "object",
+ *     or the same with `|null` ("string|null") when the value may be null;
+ *   - an object:               { key: <shape>, ... } — exactly these keys, never null.
+ *     A key ending in `?` ("comments?") may be absent; every other key is always present;
+ *   - an array:                [ <shape> ] — one element, the type of every item;
+ *   - a nullable object/array: { "nullable": <shape> } — the wrapped shape, or null.
+ *
+ * "unknown" is a JSON value this CLI passes through unchanged; "object" is a
+ * map with data-dependent keys.
+ *
+ * The row/detail shapes are declared next to the TypeScript interfaces they
+ * describe, through `shape<T>()`, whose parameter type `ShapeOf<T>` is computed
+ * from the interface: a renamed, added, removed, re-typed or de-nulled field is
+ * a compile error in the shape constant, so the description cannot quietly
+ * drift from the type the service returns. `matchesShape` is the runtime half —
+ * the tests hold real emitted objects against the declared shapes, which is
+ * what catches a field the interface promises but the query stopped selecting.
+ */
+
+export type ScalarShape = "string" | "number" | "boolean" | "unknown" | "object";
+
+export type FieldShape =
+  | ScalarShape
+  | `${ScalarShape}|null`
+  | readonly [FieldShape]
+  | { readonly nullable: FieldShape }
+  | { readonly [key: string]: FieldShape };
+
+/** How a command's `--json` stdout is shaped. */
+export interface OutputShape {
+  /**
+   * list    — a bare array of `fields`-shaped rows
+   * object  — a bare object with `fields` (a `view`, `whoami`, `config show`, …)
+   * receipt — a mutation's bare object with `fields` (ids + what happened)
+   * raw     — pass-through JSON whose keys depend on the request (`api`, `schema`)
+   * none    — the command never prints JSON (`completion`)
+   */
+  kind: "list" | "object" | "receipt" | "raw" | "none";
+  fields?: Record<string, FieldShape>;
+  /** What the fields cannot say. */
+  note?: string;
+  /**
+   * A different output under a flag or argument, keyed by what selects it
+   * (`"--web"`, `"op=list"`, `"[path]"`): the whole shape printed in that case.
+   */
+  variants?: Record<string, OutputShape>;
+}
+
+// ---------------------------------------------------------------------------
+// ShapeOf<T>: the shape a TypeScript type must be described as.
+// ---------------------------------------------------------------------------
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * The object form of a non-null object type: every key, an optional or
+ * `undefined`-able one spelled with a trailing `?` (it may be absent from the
+ * JSON — `undefined` is dropped by JSON.stringify — which is not the same as null).
+ */
+type ObjectShapeOf<T> = string extends keyof T
+  ? "object"
+  : {
+      [
+        K in keyof T as IsAny<T[K]> extends true
+          ? K & string
+          : undefined extends T[K]
+            ? `${K & string}?`
+            : K & string
+      ]-?: ShapeOf<Exclude<T[K], undefined>>;
+    };
+
+export type ShapeOf<T> =
+  IsAny<T> extends true
+    ? "unknown"
+    : [T] extends [string]
+      ? "string"
+      : [T] extends [number]
+        ? "number"
+        : [T] extends [boolean]
+          ? "boolean"
+          : [T] extends [Date]
+            ? "string"
+            : [T] extends [string | null]
+              ? "string|null"
+              : [T] extends [number | null]
+                ? "number|null"
+                : [T] extends [boolean | null]
+                  ? "boolean|null"
+                  : [T] extends [Date | null]
+                    ? "string|null"
+                    : [T] extends [readonly (infer E)[]]
+                      ? readonly [ShapeOf<E>]
+                      : [T] extends [readonly (infer E)[] | null]
+                        ? { readonly nullable: readonly [ShapeOf<E>] }
+                        : [T] extends [object]
+                          ? ObjectShapeOf<T>
+                          : [T] extends [object | null]
+                            ? { readonly nullable: ObjectShapeOf<NonNullable<T>> }
+                            : "unknown";
+
+/**
+ * Declare the shape of `T`. The argument is checked against `ShapeOf<T>`, so
+ * it must name every field of `T` with the right type and nothing else.
+ */
+export function shape<T>(s: ShapeOf<T>): ShapeOf<T> {
+  return s;
+}
+
+/** The fields of an object shape (a `ShapeOf<Interface>`), for `OutputShape.fields`. */
+export type ObjectFields = Record<string, FieldShape>;
+
+// ---------------------------------------------------------------------------
+// Runtime: check a real value against a shape, and render a shape for humans.
+// ---------------------------------------------------------------------------
+
+function isNullableWrapper(s: FieldShape): s is { readonly nullable: FieldShape } {
+  return (
+    typeof s === "object" && !Array.isArray(s) && Object.keys(s).length === 1 && "nullable" in s
+  );
+}
+
+/**
+ * Every way `value` fails to be a `shape`, as `path: problem` strings; empty
+ * when it matches. Objects must carry exactly the declared keys: an extra key
+ * is as much a drift as a missing one (it is a key the docs do not mention),
+ * and a missing non-optional key is a drift even when its type allows null —
+ * `undefined` vanishes from JSON, so the documented key would not be there.
+ *
+ * `strictNullable` also flags a `{ nullable: … }` field that IS null. The
+ * sweep uses it: its fake answers every relation, so a relation that still
+ * comes out null was not selected or not mapped — a `?? null` in a mapper hides
+ * exactly the drift TES-652 was.
+ */
+export function matchesShape(
+  value: unknown,
+  shape: FieldShape,
+  path = "$",
+  strictNullable = false,
+): string[] {
+  if (typeof shape === "string") {
+    const [base, nullable] = shape.endsWith("|null")
+      ? [shape.slice(0, -"|null".length) as ScalarShape, true]
+      : [shape as ScalarShape, false];
+    if (value === undefined) return [`${path}: expected ${shape}, got undefined`];
+    if (value === null) return nullable ? [] : [`${path}: expected ${shape}, got null`];
+    if (base === "unknown") return [];
+    if (base === "object") {
+      return typeof value === "object" && !Array.isArray(value)
+        ? []
+        : [`${path}: expected an object, got ${describe(value)}`];
+    }
+    return typeof value === base ? [] : [`${path}: expected ${shape}, got ${describe(value)}`];
+  }
+  if (Array.isArray(shape)) {
+    if (!Array.isArray(value)) return [`${path}: expected an array, got ${describe(value)}`];
+    return value.flatMap((item, i) =>
+      matchesShape(item, shape[0], `${path}[${i}]`, strictNullable),
+    );
+  }
+  if (isNullableWrapper(shape)) {
+    if (value === undefined) return [`${path}: expected an object or null, got undefined`];
+    if (value === null) {
+      return strictNullable ? [`${path}: null, although the source answers every relation`] : [];
+    }
+    return matchesShape(value, shape.nullable, path, strictNullable);
+  }
+  // A plain object shape.
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return [`${path}: expected an object, got ${describe(value)}`];
+  }
+  const record = value as Record<string, unknown>;
+  const problems: string[] = [];
+  const declared = new Set<string>();
+  for (const [spelled, sub] of Object.entries(shape)) {
+    const optional = spelled.endsWith("?");
+    const key = optional ? spelled.slice(0, -1) : spelled;
+    declared.add(key);
+    if (optional && record[key] === undefined) continue;
+    problems.push(...matchesShape(record[key], sub, `${path}.${key}`, strictNullable));
+  }
+  for (const key of Object.keys(record)) {
+    if (!declared.has(key) && record[key] !== undefined)
+      problems.push(`${path}.${key}: not in the declared shape`);
+  }
+  return problems;
+}
+
+function describe(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+/**
+ * A shape as one TypeScript-ish line: `{id: string, state: {name: string, type:
+ * string} | null, labels: string[]}` — the human rendering in `linear commands`.
+ */
+export function renderShape(shape: FieldShape): string {
+  if (typeof shape === "string") return shape.replace("|null", " | null");
+  if (Array.isArray(shape)) {
+    const inner = renderShape(shape[0]);
+    return typeof shape[0] === "string" && !shape[0].includes("|")
+      ? `${inner}[]`
+      : `Array<${inner}>`;
+  }
+  if (isNullableWrapper(shape)) return `${renderShape(shape.nullable)} | null`;
+  const parts = Object.entries(shape).map(([k, v]) => `${k}: ${renderShape(v)}`);
+  return `{${parts.join(", ")}}`;
+}
+
+/**
+ * A variant that is its base plus some keys (`issue view --comments`, `issue
+ * create --start`) is best shown as the difference: the keys it adds or
+ * re-types, and whether it drops any. Returns null when the two are unrelated
+ * (a different kind, or fewer than half the base keys kept), in which case the
+ * variant is shown in full.
+ */
+export function variantDelta(
+  base: OutputShape,
+  variant: OutputShape,
+): { added: Record<string, FieldShape>; dropped: string[] } | null {
+  if (base.kind !== variant.kind || !base.fields || !variant.fields) return null;
+  const same = (a: FieldShape, b: FieldShape) => JSON.stringify(a) === JSON.stringify(b);
+  const kept = Object.keys(base.fields).filter(
+    (k) => k in variant.fields! && same(base.fields![k]!, variant.fields![k]!),
+  );
+  if (kept.length < Object.keys(base.fields).length / 2) return null;
+  const added: Record<string, FieldShape> = {};
+  for (const [k, v] of Object.entries(variant.fields)) {
+    if (!(k in base.fields) || !same(base.fields[k]!, v)) added[k] = v;
+  }
+  const dropped = Object.keys(base.fields).filter((k) => !(k in variant.fields!));
+  return { added, dropped };
+}
+
+/** The lines `linear commands <path>` prints under "Output (--json)". */
+export function renderOutputShape(out: OutputShape, indent = "  "): string[] {
+  const head =
+    out.kind === "list"
+      ? "array of objects:"
+      : out.kind === "object"
+        ? "object:"
+        : out.kind === "receipt"
+          ? "receipt object:"
+          : out.kind === "raw"
+            ? "raw JSON (keys depend on the request)"
+            : "none (never prints JSON)";
+  const lines = [head];
+  for (const [key, sub] of Object.entries(out.fields ?? {})) {
+    lines.push(`${indent}${key}: ${renderShape(sub)}`);
+  }
+  if (out.note) lines.push(`${indent}(${out.note})`);
+  for (const [when, variant] of Object.entries(out.variants ?? {})) {
+    const delta = variantDelta(out, variant);
+    if (delta) {
+      const drop = delta.dropped.length ? `, without ${delta.dropped.join(", ")}` : "";
+      lines.push(`${indent}with ${when}: the same${drop}, plus:`);
+      for (const [key, sub] of Object.entries(delta.added)) {
+        lines.push(`${indent}  ${key}: ${renderShape(sub)}`);
+      }
+      continue;
+    }
+    const [vHead, ...vRest] = renderOutputShape(variant, indent + "  ");
+    lines.push(`${indent}with ${when}: ${vHead}`, ...vRest);
+  }
+  return lines;
+}

package/src/lib/status-update.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared scaffolding for the `project-update` / `initiative-update` groups.
+ *
+ * Both groups take the same content inputs (`--body` / `--body-file` / `--editor`)
+ * and the same `--health` enum, so the option wiring and body resolution live here
+ * once instead of being duplicated per group.
+ */
+
+import { Command, Option } from "commander";
+import { resolveBody } from "./body.js";
+import { usageError } from "./errors.js";
+import { unwrapMutation } from "./mutation.js";
+import type { Context } from "../context.js";
+import type { Column } from "../output/table.js";
+
+/** The health values Linear accepts for a status update (Project/InitiativeUpdateHealthType). */
+export const HEALTH_CHOICES = ["onTrack", "atRisk", "offTrack"] as const;
+export type Health = (typeof HEALTH_CHOICES)[number];
+
+/** A normalized status-update row, shared by project- and initiative-update. */
+export interface UpdateRow {
+  id: string;
+  createdAt: string;
+  user: string;
+  body: string;
+  health: string | null;
+}
+
+/** The table columns for listing status updates — identical for both groups. */
+export const UPDATE_COLUMNS: Column<UpdateRow>[] = [
+  { key: "createdAt", header: "Date", value: (u) => u.createdAt.slice(0, 10) },
+  { key: "user", header: "Author", value: (u) => u.user, max: 18 },
+  { key: "health", header: "Health", value: (u) => u.health ?? "—", max: 10 },
+  { key: "body", header: "Update", value: (u) => u.body.replace(/\n/g, " "), max: 60 },
+];
+
+/**
+ * Unwrap and normalize a `create{Project,Initiative}Update` payload into the shared
+ * row shape (plus the update's `url`). The `payloadKey` is the payload field that
+ * holds the created update (`projectUpdate` / `initiativeUpdate`).
+ */
+export async function normalizeUpdatePayload(
+  payload: any,
+  payloadKey: string,
+): Promise<UpdateRow & { url: string }> {
+  const update: any = await unwrapMutation(payload, payloadKey, "Status update creation");
+  const user = await update.user;
+  return {
+    id: update.id,
+    createdAt: update.createdAt?.toISOString?.() ?? String(update.createdAt),
+    user: user?.displayName ?? "unknown",
+    body: update.body ?? "",
+    health: update.health ?? null,
+    url: update.url,
+  };
+}
+
+/** Add the shared `--body` / `--body-file` / `--editor` / `--health` flags to a `create` command. */
+export function addUpdateFlags(cmd: Command): Command {
+  return cmd
+    .option("--body <text>", "update body (markdown)")
+    .option("--body-file <path>", "read body from a file ('-' = stdin)")
+    .option("--editor", "compose the body in $EDITOR")
+    .addOption(new Option("--health <state>", "status health").choices([...HEALTH_CHOICES]));
+}
+
+/**
+ * Resolve the body for a status update from the shared flags.
+ *
+ * A status update must say *something*: a body, or a health. Linear accepts a
+ * health-only update — the UI's "mark on track" with no text — but the API
+ * still insists on a body field ("Exactly one of body or bodyData must be
+ * defined", verified live) and stores the empty string for it, so `--health`
+ * alone is a complete update with `""` as its body. With neither, there is
+ * nothing to post, and that is a usage error.
+ */
+export function resolveUpdateBody(ctx: Context, opts: Record<string, any>): string {
+  const body = resolveBody({
+    arg: opts.body,
+    file: opts.bodyFile,
+    interactive: !!opts.editor && ctx.isTTY,
+    editorRequested: !!opts.editor,
+  });
+  if (body === undefined || body.trim() === "") {
+    if (opts.health) return "";
+    throw usageError(
+      "An update needs a body or a health. Pass --body, --body-file, --editor, or --health.",
+    );
+  }
+  return body;
+}

package/src/lib/upload.ts

@@ -0,0 +1,329 @@
+/**
+ * File upload — the two-step flow behind `issue attach` and `comment add
+ * --attach` (TES-602).
+ *
+ *   1. `fileUpload(contentType, filename, size, { makePublic })` asks Linear for
+ *      a signed storage URL. The payload is `{ success, uploadFile }`, checked
+ *      like every other mutation (`unwrapMutation`): `success: false` or a
+ *      missing `uploadFile` is a refusal, not a URL.
+ *   2. HTTP `PUT` the bytes to `uploadFile.uploadUrl` with the
+ *      `uploadFile.headers[]` Linear returned, verbatim, plus the Content-Type
+ *      the URL was signed for. The URL is signed over `content-type;host;
+ *      x-goog-content-length-range` (probed on the QA workspace, SDK 89), so a
+ *      wrong or missing header is a 403 from the storage backend, not from
+ *      Linear — and the returned array does not include Content-Type itself,
+ *      which is why it is set here from the type we declared in step 1. Linear's
+ *      own upload guide does the same.
+ *
+ * The signed `uploadUrl` is a bearer credential (anyone holding it can write
+ * that object for the next 60 s). It is never logged, never returned, and is
+ * redacted from any error text — the storage backend echoes it in
+ * `SignatureDoesNotMatch` bodies, and a transport error can carry it too.
+ *
+ * Privacy posture, matching schpet/linear-cli 2.5 and the Linear web app:
+ * uploads are private (workspace members only, `uploads.linear.app`) unless
+ * `public` is asked for; a public upload lands on `public.linear.app`, readable
+ * by anyone with the URL, and is only valid for raster images — Linear itself
+ * answers "Public uploads are only supported for images (excluding SVG)" to
+ * anything else. That rule is enforced here BEFORE any network work, so a
+ * mixed batch cannot publish some files and then fail on the rest.
+ */
+
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { CliError, usageError } from "./errors.js";
+import { unwrapMutation } from "./mutation.js";
+
+/** MIME type by extension. Anything else is `application/octet-stream`. */
+const MIME_TYPES: Record<string, string> = {
+  // images
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".bmp": "image/bmp",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".ico": "image/x-icon",
+  ".heic": "image/heic",
+  ".avif": "image/avif",
+  // documents
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  // text
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".csv": "text/csv",
+  ".tsv": "text/tab-separated-values",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".xml": "text/xml",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".toml": "text/toml",
+  ".json": "application/json",
+  // code
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".cjs": "text/javascript",
+  ".jsx": "text/javascript",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".sh": "text/x-shellscript",
+  ".bash": "text/x-shellscript",
+  ".py": "text/x-python",
+  ".rb": "text/x-ruby",
+  ".go": "text/x-go",
+  ".rs": "text/x-rust",
+  ".java": "text/x-java",
+  ".c": "text/x-c",
+  ".h": "text/x-c",
+  ".cpp": "text/x-c++",
+  ".hpp": "text/x-c++",
+  ".swift": "text/x-swift",
+  ".kt": "text/x-kotlin",
+  // archives
+  ".zip": "application/zip",
+  ".tar": "application/x-tar",
+  ".gz": "application/gzip",
+  ".tgz": "application/gzip",
+  ".7z": "application/x-7z-compressed",
+  ".rar": "application/vnd.rar",
+  // audio / video
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mov": "video/quicktime",
+  ".avi": "video/x-msvideo",
+  // other
+  ".wasm": "application/wasm",
+};
+
+/**
+ * The content types Linear will serve from a public URL: raster images only.
+ * SVG is an image but can carry script, and the API refuses it publicly.
+ */
+const PUBLIC_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/bmp",
+  "image/tiff",
+  "image/heic",
+  "image/avif",
+]);
+
+/** MIME type from the file's extension; `application/octet-stream` when unknown. */
+export function mimeType(path: string): string {
+  return MIME_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+}
+
+/** `image/*` — what renders inline in a comment as `![name](url)`. */
+export function isImage(contentType: string): boolean {
+  return contentType.startsWith("image/");
+}
+
+/** Whether Linear allows this content type on a public URL. */
+export function canBePublic(contentType: string): boolean {
+  return PUBLIC_TYPES.has(contentType);
+}
+
+export interface UploadOptions {
+  /**
+   * Upload to a public, unauthenticated URL. Off by default (private —
+   * workspace members only), and only valid for raster images.
+   */
+  public?: boolean;
+  /** The `fetch` to PUT with; injectable for tests. Defaults to the global. */
+  fetch?: typeof fetch;
+}
+
+/** A file that passed `validateUploads`: what will be declared to `fileUpload`. */
+export interface UploadCandidate {
+  path: string;
+  filename: string;
+  contentType: string;
+  size: number;
+}
+
+export interface UploadResult {
+  /** The permanent URL Linear serves the file from (private unless `public`). */
+  assetUrl: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  /** Whether the file went to a public, world-readable URL. */
+  public: boolean;
+}
+
+/**
+ * Check every path BEFORE any network work: it exists, is a regular file, is
+ * readable, and — with `public` — is a type Linear will serve publicly. Called
+ * on the whole batch up front so a typo in file 3 does not leave files 1–2
+ * uploaded and orphaned, and so a mixed `--public` batch is refused whole
+ * rather than half-published. Returns what each upload will declare.
+ */
+export function validateUploads(paths: string[], opts: UploadOptions = {}): UploadCandidate[] {
+  return paths.map((path) => {
+    let size: number;
+    try {
+      const st = statSync(path);
+      if (!st.isFile()) throw usageError(`'${path}' is not a regular file.`);
+      size = st.size;
+      accessSync(path, constants.R_OK);
+    } catch (err) {
+      if (err instanceof CliError) throw err;
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") throw usageError(`File not found: '${path}'.`);
+      if (code === "EACCES") throw usageError(`Cannot read '${path}': permission denied.`);
+      throw usageError(`Cannot read '${path}': ${(err as Error).message}`);
+    }
+    const contentType = mimeType(path);
+    if (opts.public && !canBePublic(contentType)) {
+      throw usageError(
+        `Cannot upload '${basename(path)}' (${contentType}) to a public URL: Linear only serves raster ` +
+          "images (png, jpeg, gif, webp, bmp, tiff) publicly. Drop --public to upload it privately.",
+      );
+    }
+    return { path, filename: basename(path), contentType, size };
+  });
+}
+
+/**
+ * Upload one file: signed URL from Linear, then PUT the bytes to it. Private
+ * unless `opts.public`. Throws a usage error before any network work when the
+ * file is missing/unreadable or `public` is asked for a non-image.
+ */
+export async function uploadFile(
+  client: LinearClient,
+  path: string,
+  opts: UploadOptions = {},
+): Promise<UploadResult> {
+  const [file] = validateUploads([path], opts);
+  const { filename, contentType, size } = file!;
+  const makePublic = opts.public === true;
+
+  // Read the bytes before asking for the URL: it is only valid for ~60 s, and
+  // a slow disk should not eat into that.
+  const bytes = readFileSync(path);
+
+  const upload = await unwrapMutation(
+    withRetry(() => client.fileUpload(contentType, filename, size, { makePublic })),
+    "uploadFile",
+    `Upload of ${filename}`,
+  );
+  const uploadUrl: string = upload.uploadUrl;
+
+  // Content-Type first (the URL is signed over it), then Linear's headers
+  // verbatim — through `Headers.set`, so a returned Content-Type replaces the
+  // default rather than being appended to it as a second value.
+  const headers = new Headers();
+  headers.set("Content-Type", contentType);
+  for (const h of upload.headers ?? []) headers.set(h.key, h.value);
+
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  let response: Response;
+  try {
+    response = await doFetch(uploadUrl, { method: "PUT", headers, body: bytes });
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    throw new CliError(`Upload of ${filename} failed: ${redact(why, uploadUrl)}`, "network");
+  }
+  if (!response.ok) {
+    const text = redact(await response.text().catch(() => ""), uploadUrl);
+    const why = storageErrorSummary(text);
+    throw new CliError(
+      `Upload of ${filename} failed: storage returned ${response.status} ${response.statusText}${why ? `: ${why}` : ""}`,
+      "api",
+      { status: response.status, statusText: response.statusText, body: text.slice(0, 2000) },
+    );
+  }
+
+  return { assetUrl: upload.assetUrl, filename, contentType, size, public: makePublic };
+}
+
+/**
+ * One line from a storage error body (already redacted). GCS answers in XML —
+ * `<Code>SignatureDoesNotMatch</Code><Message>…</Message><Details>…</Details>`
+ * followed by the whole canonical request — so pick the code and the most
+ * specific sentence; anything else is collapsed and cut short.
+ */
+function storageErrorSummary(text: string): string {
+  const tag = (name: string) => text.match(new RegExp(`<${name}>([^<]*)</${name}>`))?.[1]?.trim();
+  const code = tag("Code");
+  if (code) {
+    const why = tag("Details") || tag("Message");
+    return why ? `${code} — ${why}` : code;
+  }
+  return text.replace(/\s+/g, " ").trim().slice(0, 300);
+}
+
+/**
+ * Strip the signed URL from text that may echo it: the whole URL, its query
+ * string on its own, and any `…Signature=<hex>` parameter, however the
+ * backend or transport spelled it.
+ */
+function redact(text: string, uploadUrl: string): string {
+  let out = text.split(uploadUrl).join("[signed upload URL]");
+  try {
+    const u = new URL(uploadUrl);
+    if (u.search.length > 1) out = out.split(u.search).join("?[redacted]");
+    for (const [key, value] of u.searchParams) {
+      if (/signature|credential/i.test(key) && value) out = out.split(value).join("[redacted]");
+    }
+  } catch {
+    // not a parseable URL — the plain replacement above is all there is to do
+  }
+  return out.replace(/([?&][\w-]*Signature=)[^&\s"'<>]+/gi, "$1[redacted]");
+}
+
+/** Markdown for a comment body: images embed inline, anything else links. */
+export function formatEmbed(
+  r: Pick<UploadResult, "filename" | "assetUrl" | "contentType">,
+): string {
+  return `${isImage(r.contentType) ? "!" : ""}[${r.filename}](${r.assetUrl})`;
+}
+
+/**
+ * A comment body with its uploads embedded: the body, a blank line, then one
+ * embed per line. An empty body is just the embeds. Shared by `comment add
+ * --attach` and `issue attach --comment` so both read the same way.
+ */
+export function appendEmbeds(
+  body: string | undefined,
+  uploads: Array<Pick<UploadResult, "filename" | "assetUrl" | "contentType">>,
+): string {
+  const embeds = uploads.map(formatEmbed).join("\n");
+  if (!embeds) return body ?? "";
+  return body?.trim() ? `${body}\n\n${embeds}` : embeds;
+}
+
+/** `70 B`, `12 KB`, `1.5 KB`, `3 MB` — for the human receipt. */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  const rounded = v >= 10 ? Math.round(v) : Math.round(v * 10) / 10;
+  return `${rounded} ${units[i]}`;
+}