linear-sdk-cli 0.1.0

package/src/output/table.ts

@@ -0,0 +1,198 @@
+/**
+ * Minimal dependency-free table renderer with truncation + optional color.
+ */
+
+import pc from "picocolors";
+import { usageError } from "../lib/errors.js";
+import { sanitizeForTerminal, displayWidth } from "./sanitize.js";
+
+export interface Column<T> {
+  /** Stable key used by --fields selection. */
+  key: string;
+  /** Header label (defaults to key). */
+  header?: string;
+  /** Cell accessor. */
+  value: (row: T) => unknown;
+  /** Max width before truncation (default 60). */
+  max?: number;
+}
+
+/** Cut `s` to at most `max` terminal columns, by grapheme, with an ellipsis. */
+function truncate(s: string, max: number): string {
+  if (displayWidth(s) <= max) return s;
+  if (max <= 1) return sliceToWidth(s, max);
+  return sliceToWidth(s, max - 1) + "…";
+}
+
+/** The longest prefix of `s` that fits in `width` columns — whole graphemes only. */
+function sliceToWidth(s: string, width: number): string {
+  let out = "";
+  let used = 0;
+  for (const { segment } of new Intl.Segmenter().segment(s)) {
+    const w = displayWidth(segment);
+    if (used + w > width) break;
+    out += segment;
+    used += w;
+  }
+  return out;
+}
+
+/**
+ * A value as a human cell. Every string that reaches a table or a detail block
+ * passes through here, and this is where terminal escapes in API data die.
+ *
+ * A relation object (`{id, name}`, `{displayName}`, `{identifier}`) shows its
+ * human name, so `--fields project,assignee` on a row that carries objects
+ * reads as a table and not as `[object Object]`.
+ */
+export function cell(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  if (Array.isArray(v)) return v.map(cell).join(", ");
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    const name = o.name ?? o.displayName ?? o.identifier ?? o.key ?? o.id;
+    return name === undefined ? sanitizeForTerminal(JSON.stringify(v)) : cell(name);
+  }
+  return sanitizeForTerminal(String(v));
+}
+
+/**
+ * Filter columns to a requested subset (by key or header, case-insensitive),
+ * preserving requested order. A field that names no column but IS a key on the
+ * rows becomes a column of that key's value — `issue list --fields id,title,
+ * labels` used to be `Unknown field 'labels'` while every row carried labels,
+ * project, url, updatedAt and estimate. An unknown field is a usage error
+ * rather than a silent fall-through to all columns, and it lists both kinds.
+ */
+export function selectColumns<T>(columns: Column<T>[], fields?: string[], sample?: T): Column<T>[] {
+  if (!fields || fields.length === 0) return columns;
+  const byName = new Map<string, Column<T>>();
+  for (const c of columns) {
+    byName.set(c.key.toLowerCase(), c);
+    if (c.header) byName.set(c.header.toLowerCase(), c);
+  }
+  const rowKeys = sample && typeof sample === "object" ? Object.keys(sample as object) : [];
+  const picked: Column<T>[] = [];
+  for (const f of fields) {
+    const col = byName.get(f.toLowerCase());
+    if (col) {
+      picked.push(col);
+      continue;
+    }
+    const key = rowKeys.find((k) => k.toLowerCase() === f.toLowerCase());
+    if (key === undefined) {
+      const extra = rowKeys.filter((k) => !byName.has(k.toLowerCase()));
+      throw usageError(
+        `Unknown field '${f}'. Available: ${columns.map((c) => c.key).join(", ")}${
+          extra.length ? `; also any row key: ${extra.join(", ")}` : ""
+        }.`,
+      );
+    }
+    picked.push({ key, header: key, value: (row) => (row as Record<string, unknown>)[key] });
+  }
+  return picked;
+}
+
+/**
+ * `--fields` under `--json`: keep only the named top-level keys of each object,
+ * in the order asked. Keys are matched exactly (JSON is case-sensitive), and an
+ * unknown key is a usage error naming the real ones — it used to be silently
+ * ignored, so `--fields nope --json` exited 0 with every key while
+ * `--fields nope` exited 2. An empty list has nothing to check and stays `[]`.
+ */
+export function projectFields<T>(value: T, fields?: string[]): T {
+  if (!fields || fields.length === 0) return value;
+  const pick = (obj: Record<string, unknown>): Record<string, unknown> => {
+    const out: Record<string, unknown> = {};
+    for (const f of fields) {
+      if (!(f in obj)) {
+        throw usageError(`Unknown field '${f}'. Available: ${Object.keys(obj).join(", ")}.`);
+      }
+      out[f] = obj[f];
+    }
+    return out;
+  };
+  if (Array.isArray(value)) {
+    return value.map((row) =>
+      row && typeof row === "object" ? pick(row as Record<string, unknown>) : row,
+    ) as T;
+  }
+  if (value && typeof value === "object") return pick(value as Record<string, unknown>) as T;
+  return value;
+}
+
+/**
+ * `--fields` on a human detail block: keep the pairs whose label matches
+ * (case-insensitively), in the order asked. Unknown → usage error naming the
+ * labels there are.
+ */
+export function selectPairs(
+  pairs: Array<[string, unknown]>,
+  fields?: string[],
+): Array<[string, unknown]> {
+  if (!fields || fields.length === 0) return pairs;
+  const picked: Array<[string, unknown]> = [];
+  for (const f of fields) {
+    const pair = pairs.find(([label]) => label.toLowerCase() === f.toLowerCase());
+    if (!pair) {
+      throw usageError(
+        `Unknown field '${f}'. Available: ${pairs.map(([label]) => label).join(", ")}.`,
+      );
+    }
+    picked.push(pair);
+  }
+  return picked;
+}
+
+export function renderTable<T>(
+  rows: T[],
+  columns: Column<T>[],
+  opts: { color?: boolean; empty?: string } = {},
+): string {
+  const color = opts.color ?? false;
+  const colors = pc.createColors(color);
+  if (rows.length === 0) return colors.dim(sanitizeForTerminal(opts.empty ?? "(no results)"));
+
+  const headers = columns.map((c) => c.header ?? c.key);
+  const body = rows.map((row) => columns.map((c) => truncate(cell(c.value(row)), c.max ?? 60)));
+
+  const widths = columns.map((_, i) => {
+    const header = headers[i] ?? "";
+    const colMax = body.reduce((m, r) => Math.max(m, displayWidth(r[i] ?? "")), 0);
+    return Math.max(displayWidth(header), colMax);
+  });
+
+  const pad = (s: string, w: number) => s + " ".repeat(Math.max(0, w - displayWidth(s)));
+
+  const headerLine = headers
+    .map((h, i) => pad(colors.bold(h), widths[i] ?? 0))
+    .join("  ")
+    .trimEnd();
+
+  const lines = body.map((r) =>
+    r
+      .map((c, i) => pad(c, widths[i] ?? 0))
+      .join("  ")
+      .trimEnd(),
+  );
+
+  return [headerLine, ...lines].join("\n");
+}
+
+/** Render a single record as aligned key: value lines. */
+export function renderDetail(
+  pairs: Array<[string, unknown]>,
+  opts: { color?: boolean } = {},
+): string {
+  const color = opts.color ?? false;
+  const colors = pc.createColors(color);
+  const visible = pairs.filter(([, v]) => v !== undefined && v !== null);
+  const keyWidth = visible.reduce((m, [k]) => Math.max(m, k.length), 0);
+  return visible
+    .map(([k, v]) => {
+      const label = (k + ":").padEnd(keyWidth + 1);
+      return `${colors.dim(label)} ${cell(v)}`;
+    })
+    .join("\n");
+}

package/src/services/agent-session.ts

@@ -0,0 +1,289 @@
+/**
+ * Agent-session service: the sessions Linear's agent integrations (Codex,
+ * Claude, Cursor, …) open on an issue when they are mentioned or delegated to.
+ *
+ * Both listings and the single `view` use tailored GraphQL queries: one
+ * selection set for the row, so a session looks the same whether it was found
+ * through its issue or through the workspace-wide feed, and one round-trip for
+ * the detail (the SDK-model path fetches the agent, the creator, the issue and
+ * the activities as four more requests). Every field selected is public schema
+ * — the SDK's own `AgentSession` model carries the same ones — so this does not
+ * depend on the `[Internal]` `Issue.agentSessions` connection.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collectRawQuery, hasMoreResults, setPaginationMetadata } from "../lib/pagination.js";
+import { notFound } from "../lib/errors.js";
+
+/** The statuses Linear reports for a session (AgentSessionStatus). */
+export const AGENT_SESSION_STATUSES = [
+  "pending",
+  "active",
+  "awaitingInput",
+  "complete",
+  "error",
+  "stale",
+] as const;
+export type AgentSessionStatus = (typeof AGENT_SESSION_STATUSES)[number];
+
+/** A user as the session references it: the agent (`appUser`) or a human. */
+export interface SessionUser {
+  id: string;
+  name: string;
+  displayName: string;
+}
+
+const SESSION_USER_SHAPE = shape<SessionUser>({
+  id: "string",
+  name: "string",
+  displayName: "string",
+});
+
+export interface AgentSessionRow {
+  id: string;
+  status: string;
+  /** Deprecated upstream (always `commentThread` today); kept because the API still returns it. */
+  type: string | null;
+  summary: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  endedAt: string | null;
+  url: string | null;
+  issue: { id: string; identifier: string; title: string } | null;
+  /** The agent user the session belongs to (the API's `appUser`). */
+  agent: SessionUser | null;
+  /** The human who started the session; null when an automation or another agent did. */
+  creator: SessionUser | null;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const AGENT_SESSION_ROW_SHAPE = shape<AgentSessionRow>({
+  id: "string",
+  status: "string",
+  type: "string|null",
+  summary: "string|null",
+  createdAt: "string",
+  startedAt: "string|null",
+  endedAt: "string|null",
+  url: "string|null",
+  issue: { nullable: { id: "string", identifier: "string", title: "string" } },
+  agent: { nullable: SESSION_USER_SHAPE },
+  creator: { nullable: SESSION_USER_SHAPE },
+});
+
+const ROW_FIELDS = `
+  id status type summary createdAt startedAt endedAt url
+  issue { id identifier title }
+  appUser { id name displayName }
+  creator { id name displayName }
+`;
+
+/**
+ * An issue's sessions, read off its comments: every session is anchored to a
+ * comment thread on the issue (`Comment.agentSession`), and that edge is public
+ * where `Issue.agentSessions` is not. Comments are paged to exhaustion —
+ * sessions are sparse among them, so a limit on comments would not be a limit
+ * on sessions — and the caller's limit is applied to the sessions found.
+ */
+const ISSUE_QUERY = `
+query CliIssueAgentSessions($id: String!, $first: Int!, $after: String) {
+  issue(id: $id) {
+    comments(first: $first, after: $after) {
+      nodes { agentSession { ${ROW_FIELDS} } }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}`;
+
+/** The workspace-wide feed, newest first — the SDK's `agentSessions`. */
+const ALL_QUERY = `
+query CliAgentSessions($first: Int!, $after: String) {
+  agentSessions(first: $first, after: $after) {
+    nodes { ${ROW_FIELDS} }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+export interface ListOptions {
+  /** Keep only sessions in this status (validated by the command's `.choices`). */
+  status?: string;
+}
+
+/** Sessions on one issue (identifier or id), newest first. */
+export async function listIssueAgentSessions(
+  client: LinearClient,
+  issueId: string,
+  limit: number,
+  opts: ListOptions = {},
+): Promise<AgentSessionRow[]> {
+  const sessions = await collectRawQuery<AgentSessionRow | null>(
+    client as any,
+    ISSUE_QUERY,
+    { id: issueId },
+    "issue.comments",
+    Infinity,
+    (n) => (n.agentSession ? toRow(n.agentSession) : null),
+  );
+  return finish(sessions, limit, opts);
+}
+
+/** Every session in the workspace, newest first. */
+export async function listAllAgentSessions(
+  client: LinearClient,
+  limit: number,
+  opts: ListOptions = {},
+): Promise<AgentSessionRow[]> {
+  // The status filter is applied after the fetch (the API has no filter
+  // argument on this connection), so the page has to be exhaustive when one is
+  // set — a limit on the unfiltered feed would hide matches.
+  const rows = await collectRawQuery<AgentSessionRow>(
+    client as any,
+    ALL_QUERY,
+    {},
+    "agentSessions",
+    opts.status ? Infinity : limit,
+    toRow,
+  );
+  return finish(rows, limit, opts);
+}
+
+function finish(
+  rows: Array<AgentSessionRow | null>,
+  limit: number,
+  opts: ListOptions,
+): AgentSessionRow[] {
+  const present = rows.filter((r): r is AgentSessionRow => r !== null);
+  const filtered = opts.status ? present.filter((r) => r.status === opts.status) : present;
+  // Newest first, whichever query found them (an issue's comments come oldest first).
+  filtered.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+  if (limit === Infinity) return setPaginationMetadata(filtered, false);
+  return setPaginationMetadata(
+    filtered.slice(0, limit),
+    filtered.length > limit || (!opts.status && filtered.length >= limit && hasMoreResults(rows)),
+  );
+}
+
+function toRow(s: any): AgentSessionRow {
+  return {
+    id: s.id,
+    status: s.status,
+    type: s.type ?? null,
+    summary: s.summary ?? null,
+    createdAt: s.createdAt,
+    startedAt: s.startedAt ?? null,
+    endedAt: s.endedAt ?? null,
+    url: s.url ?? null,
+    issue: s.issue ?? null,
+    agent: s.appUser ?? null,
+    creator: s.creator ?? null,
+  };
+}
+
+/** One step of the agent's work, flattened from the activity-content union. */
+export interface AgentActivityRow {
+  id: string;
+  createdAt: string;
+  /** thought | action | response | prompt | error | elicitation */
+  type: string;
+  /** The text of a thought/response/prompt/error/elicitation; null for an action. */
+  body: string | null;
+  /** An action's name (`Running command`) and its parameter/result; null otherwise. */
+  action: string | null;
+  parameter: string | null;
+  result: string | null;
+}
+
+export const AGENT_ACTIVITY_ROW_SHAPE = shape<AgentActivityRow>({
+  id: "string",
+  createdAt: "string",
+  type: "string",
+  body: "string|null",
+  action: "string|null",
+  parameter: "string|null",
+  result: "string|null",
+});
+
+export interface AgentSessionDetail extends AgentSessionRow {
+  updatedAt: string;
+  dismissedAt: string | null;
+  dismissedBy: SessionUser | null;
+  externalLink: string | null;
+  /** Oldest first, up to `ACTIVITY_LIMIT`; `activitiesTruncated` says whether more exist. */
+  activities: AgentActivityRow[];
+  activitiesTruncated: boolean;
+}
+
+/** The detail's shape; checked against `AgentSessionDetail` (the row, plus the transcript). */
+export const AGENT_SESSION_DETAIL_SHAPE = shape<AgentSessionDetail>({
+  ...AGENT_SESSION_ROW_SHAPE,
+  updatedAt: "string",
+  dismissedAt: "string|null",
+  dismissedBy: { nullable: SESSION_USER_SHAPE },
+  externalLink: "string|null",
+  activities: [AGENT_ACTIVITY_ROW_SHAPE],
+  activitiesTruncated: "boolean",
+});
+
+/** How many activities `view` fetches — a session is short, and the API prices nested lists by their worst case. */
+const ACTIVITY_LIMIT = 100;
+
+const DETAIL_QUERY = `
+query CliAgentSessionDetail($id: String!, $activities: Int!) {
+  agentSession(id: $id) {
+    ${ROW_FIELDS}
+    updatedAt dismissedAt externalLink
+    dismissedBy { id name displayName }
+    activities(first: $activities) {
+      nodes {
+        id createdAt
+        content {
+          __typename
+          ... on AgentActivityThoughtContent { type body }
+          ... on AgentActivityActionContent { type action parameter result }
+          ... on AgentActivityResponseContent { type body }
+          ... on AgentActivityPromptContent { type body }
+          ... on AgentActivityErrorContent { type body }
+          ... on AgentActivityElicitationContent { type body }
+        }
+      }
+      pageInfo { hasNextPage }
+    }
+  }
+}`;
+
+export async function getAgentSessionDetail(
+  client: LinearClient,
+  id: string,
+): Promise<AgentSessionDetail> {
+  const data: any = await withRetry(() =>
+    (client as any).client.rawRequest(DETAIL_QUERY, { id, activities: ACTIVITY_LIMIT }),
+  );
+  const s = data.data?.agentSession;
+  if (!s) throw notFound(`No agent session '${id}'.`);
+  const activities: any[] = s.activities?.nodes ?? [];
+  return {
+    ...toRow(s),
+    updatedAt: s.updatedAt,
+    dismissedAt: s.dismissedAt ?? null,
+    dismissedBy: s.dismissedBy ?? null,
+    externalLink: s.externalLink ?? null,
+    // The API serves activities newest first; a transcript reads the other way.
+    activities: activities.map(toActivity).reverse(),
+    activitiesTruncated: s.activities?.pageInfo?.hasNextPage === true,
+  };
+}
+
+function toActivity(a: any): AgentActivityRow {
+  const c = a.content ?? {};
+  return {
+    id: a.id,
+    createdAt: a.createdAt,
+    type: c.type ?? "unknown",
+    body: c.body ?? null,
+    action: c.action ?? null,
+    parameter: c.parameter ?? null,
+    result: c.result ?? null,
+  };
+}

package/src/services/attachment.ts

@@ -0,0 +1,198 @@
+/**
+ * Attachment service: all SDK access for attachments lives here so commands
+ * stay thin.
+ *
+ * Listing goes through the typed `issue.attachments()` connection on a resolved
+ * issue; `create` unwraps the `{ success, attachment }` payload and `delete`
+ * removes by id. `attachFiles` is `issue attach`: upload each file (see
+ * `lib/upload.ts`), then attach it by its asset URL.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
+import { notFound, usageError } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveIssue } from "../lib/resolve.js";
+import { appendEmbeds, uploadFile, validateUploads, type UploadResult } from "../lib/upload.js";
+
+export interface AttachmentRow {
+  id: string;
+  title: string;
+  subtitle: string | null;
+  url: string;
+  source: string | null;
+  createdAt: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const ATTACHMENT_ROW_SHAPE = shape<AttachmentRow>({
+  id: "string",
+  title: "string",
+  subtitle: "string|null",
+  url: "string",
+  source: "string|null",
+  createdAt: "string",
+});
+
+/** Derive a human-friendly source label from the Attachment's source/sourceType. */
+export function sourceLabel(a: any): string | null {
+  if (a.sourceType) return String(a.sourceType);
+  const src = a.source;
+  if (src && typeof src === "object" && typeof src.type === "string") return src.type;
+  if (typeof src === "string") return src;
+  return null;
+}
+
+function toRow(a: any): AttachmentRow {
+  return {
+    id: a.id,
+    title: a.title,
+    subtitle: a.subtitle ?? null,
+    url: a.url,
+    source: sourceLabel(a),
+    createdAt: dateStr(a.createdAt),
+  };
+}
+
+/** List the attachments on an issue (resolved from identifier or UUID). */
+export async function listAttachments(
+  client: LinearClient,
+  issueArg: string,
+  limit: number,
+): Promise<AttachmentRow[]> {
+  const issue = await resolveIssue(client, issueArg);
+  const conn = await withRetry(() => issue.attachments({ first: pageSize(limit) }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(nodes.map(toRow), nodes);
+}
+
+export interface CreateOptions {
+  url: string;
+  title: string;
+  subtitle?: string;
+}
+
+/** Create an attachment on an issue, unwrapping the `{ success, attachment }` payload. */
+export async function createAttachment(
+  client: LinearClient,
+  issueArg: string,
+  opts: CreateOptions,
+) {
+  const issue = await resolveIssue(client, issueArg);
+  const input: Record<string, any> = {
+    issueId: issue.id,
+    url: opts.url,
+    title: opts.title,
+  };
+  if (opts.subtitle !== undefined) input.subtitle = opts.subtitle;
+
+  return unwrapMutation(
+    withRetry(() => client.createAttachment(input as any)),
+    "attachment",
+    "Attachment creation",
+  );
+}
+
+export interface AttachFilesOptions {
+  /** Attachment title; only meaningful for a single file (default: the filename). */
+  title?: string;
+  /** Also post one comment with this body, embedding every file as markdown. */
+  comment?: string;
+  /** Upload to public, world-readable URLs (raster images only). Default: private. */
+  public?: boolean;
+  /** Called as each file is attached (with the resolved issue), for progress output. */
+  onAttached?: (attached: AttachedFile, issue: { id: string; identifier: string }) => void;
+}
+
+/** One uploaded-and-attached file: the attachment plus what was uploaded. */
+export interface AttachedFile extends UploadResult {
+  id: string;
+  title: string;
+  url: string;
+}
+
+/**
+ * `issue attach <issue> <file...>`: upload each file to Linear's storage and
+ * attach it to the issue by its asset URL. Every file is validated first — it
+ * exists, is readable, and (with `public`) is a type Linear serves publicly —
+ * so a typo in file 3 does not leave files 1–2 uploaded and orphaned. Then the
+ * issue is resolved (a bad id fails before any bytes move), and each file is
+ * uploaded and attached in turn. `comment` posts ONE comment afterwards, its
+ * body followed by a blank line and one markdown embed per file, so an image
+ * shows inline in the thread as well as in the sidebar.
+ */
+export async function attachFiles(
+  client: LinearClient,
+  issueArg: string,
+  paths: string[],
+  opts: AttachFilesOptions,
+): Promise<{
+  issue: { id: string; identifier: string };
+  attachments: AttachedFile[];
+  comment?: { id: string; url: string };
+}> {
+  if (opts.title !== undefined && paths.length > 1) {
+    throw usageError(
+      "--title names a single attachment; with several files, drop it to use each file's name.",
+    );
+  }
+  validateUploads(paths, { public: opts.public });
+  const issue = await resolveIssue(client, issueArg);
+
+  const attachments: AttachedFile[] = [];
+  for (const path of paths) {
+    const upload = await uploadFile(client, path, { public: opts.public });
+    const attachment = await unwrapMutation(
+      withRetry(() =>
+        client.createAttachment({
+          issueId: issue.id,
+          url: upload.assetUrl,
+          title: opts.title ?? upload.filename,
+        }),
+      ),
+      "attachment",
+      "Attachment creation",
+    );
+    const attached: AttachedFile = {
+      ...upload,
+      id: attachment.id,
+      title: attachment.title,
+      url: attachment.url,
+    };
+    attachments.push(attached);
+    opts.onAttached?.(attached, issue);
+  }
+
+  let comment: { id: string; url: string } | undefined;
+  if (opts.comment !== undefined) {
+    const created = await unwrapMutation(
+      withRetry(() =>
+        client.createComment({ issueId: issue.id, body: appendEmbeds(opts.comment, attachments) }),
+      ),
+      "comment",
+      "Comment creation",
+    );
+    comment = { id: created.id, url: created.url };
+  }
+
+  return { issue: { id: issue.id, identifier: issue.identifier }, attachments, comment };
+}
+
+/** Delete an attachment by id; returns the removed attachment's id/title. */
+export async function deleteAttachment(client: LinearClient, id: string) {
+  const attachment = await withRetry(() => client.attachment(id));
+  if (!attachment) throw notFound(`No attachment ${id}.`);
+  await assertMutation(
+    withRetry(() => client.deleteAttachment(id)),
+    "Attachment deletion",
+  );
+  return { id: attachment.id, title: attachment.title };
+}
+
+/** Normalize a Date (SDK model) or string into an ISO string. */
+export function dateStr(v: unknown): string {
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}