@zumino/cli 2.1.0 → 2.2.0

package/src/commands/task.js

@@ -1,18 +1,57 @@
 import { api } from "../client.js";
 import { resolveContext } from "../config.js";
 import { CliError } from "../errors.js";
-import { codeOf, givenFlag, json, out, pick, positiveInt, safeText } from "../output.js";
+import {
+  clip,
+  codeOf,
+  dim,
+  json,
+  out,
+  pageLine,
+  pick,
+  safeText,
+  table,
+} from "../output.js";
+import {
+  assertUserRef,
+  csv,
+  givenFlag,
+  nonNegativeInt,
+  oneValue,
+  positiveInt,
+  searchText,
+} from "../flags.js";
+import { listEvents } from "../events.js";
 import { projectPath, resolveItem } from "../items.js";
+import { resolveUser, resolveUserRef } from "../users.js";
 
 /*
- * Everything that writes a task.
+ * Tasks: the project's work, read and written.
  *
- * Per-kind because `DOMAIN.md` says writes are per-kind: each has its own Zod
- * schema and its own rate-limit bucket, so a run filing twenty-five tasks is
- * never the reason naming the epic they belong to is refused.
+ * Per-kind because `DOMAIN.md` says writes are per-kind: each kind has its own
+ * Zod schema and its own rate-limit bucket, so a run filing twenty-five tasks is
+ * never the reason naming the epic they belong to is refused. The *list* lives
+ * here for the same reason — it reads the task endpoint, with the task
+ * vocabulary, and publishes priority, readiness and tags, which the read that
+ * spans every kind deliberately does not (`docs/decisions/0003`).
  */
 
-const SUB = { create, status, assign, spec, comment, link, ref, attention, show };
+export const SUB = {
+  list,
+  show,
+  events,
+  create,
+  edit,
+  status,
+  assign,
+  spec,
+  comment,
+  link,
+  ref,
+  attention,
+  tag,
+  untag,
+};
 
 export async function run(args, flags) {
   const [sub, ...rest] = args;
@@ -25,40 +64,164 @@ export async function run(args, flags) {
   return fn(rest, flags);
 }
 
+/**
+ * `--epic` as the API takes it, in its two places.
+ *
+ * An **epic** reference in this project, and nothing else. `epicNumber` is
+ * project-local, so a key prefix cannot express a foreign epic — its only effect
+ * was to let one through silently: `OPS-E14` targeted epic 14 *here*. And
+ * stripping leading letters off anything turned the task code `ONS-14` into epic
+ * 14, which is legal because task and epic numbers are separate namespaces, so
+ * the task was created under the wrong parent and reported success. Accept `E3`
+ * or `3`; refuse everything else and say why.
+ *
+ * @param {string} raw
+ * @param {{allowNone: boolean}} opts  `none` is a filter value and a detach
+ */
+function epicRef(raw, { allowNone }) {
+  const v = String(raw).trim();
+  if (allowNone && (v === "none" || v === "-")) return null;
+  const m = /^[Ee]?(\d+)$/.exec(v);
+  if (!m) {
+    throw new CliError(`--epic "${v}" is not an epic in this project.`, {
+      hint:
+        "Write E3 or 3" +
+        (allowNone ? ", or none" : "") +
+        ". A task code like ONS-14 is not an epic, and an epic in another " +
+        "project cannot be a parent — move the task instead.",
+    });
+  }
+  return positiveInt(m[1], "epic");
+}
+
+async function list(args, flags) {
+  const ctx = resolveContext(flags);
+  const base = await projectPath(ctx);
+
+  // `!== undefined`, not truthiness: `--assignee ""` and `--epic ""` are given
+  // and empty, and a falsy test drops them into an unfiltered list.
+  const assignee =
+    flags.assignee !== undefined
+      ? await resolveUser(ctx, oneValue(flags, "assignee"), { flag: "--assignee" })
+      : undefined;
+  const epic =
+    flags.epic !== undefined ? epicRef(oneValue(flags, "epic"), { allowNone: true }) : undefined;
+  const offset = nonNegativeInt(flags.offset, "offset");
+
+  const res = await api(ctx, "GET", `${base}/tasks`, {
+    query: {
+      q: searchText(args, flags),
+      status: csv(flags, "status"),
+      type: oneValue(flags, "type"),
+      priority: oneValue(flags, "priority"),
+      assignee,
+      tag: oneValue(flags, "tag"),
+      // `none` is the ungrouped remainder, which no number can express — and it
+      // is the one filter on this endpoint that refuses what it cannot parse,
+      // because an unfiltered list is indistinguishable from a filter that
+      // matched everything.
+      epic: epic === null ? "none" : epic,
+      needsInput: flags["needs-input"] ? "true" : undefined,
+      open: flags.open ? "true" : undefined,
+      sort: oneValue(flags, "sort"),
+      offset,
+      limit: positiveInt(flags.limit, "limit"),
+    },
+  });
+
+  const tasks = res?.tasks ?? [];
+  if (flags.json) return json(tasks), 0;
+  if (tasks.length === 0) return out("No tasks match."), 0;
+
+  table(
+    tasks.map((t) => [
+      codeOf(t) || `#${t.number}`,
+      t.status ?? "",
+      t.priority ?? "",
+      t.type ?? "",
+      safeText(t.assignee?.name) || "—",
+      clip(t.title, 48),
+    ]),
+    { head: ["CODE", "STATUS", "PRIORITY", "TYPE", "ASSIGNEE", "TITLE"] },
+  );
+  out(dim(`\n${pageLine(res, tasks.length, offset)}`));
+  return 0;
+}
+
+async function show(args, flags) {
+  const [itemRef] = args;
+  if (!itemRef) throw new CliError("zumino task show <CODE>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const res = pick(await api(ctx, "GET", path), "task");
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${safeText(res.title)}`);
+  out(`status ${res.status}   priority ${res.priority ?? "-"}   assignee ${safeText(res.assignee?.name) || "-"}`);
+  if (res.description) out(`\n${safeText(res.description)}`);
+  return 0;
+}
+
+async function events(args, flags) {
+  const [itemRef] = args;
+  if (!itemRef) throw new CliError("zumino task events <CODE>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  return listEvents(ctx, path, flags);
+}
+
+/**
+ * The fields a task write carries, built once for `create` and for `edit`.
+ *
+ * `!== undefined`, not truthiness: `--description ""` is an instruction to leave
+ * it blank, and dropping it silently left whatever was there. A field nobody
+ * named is absent from the body, so a patch touches exactly what was asked for —
+ * which is also what makes `edit` one audit group rather than several.
+ *
+ * @param {any} ctx
+ * @param {Record<string, any>} flags
+ * @param {{patch: boolean}} opts  a patch may clear; a create has nothing to clear
+ */
+async function fields(ctx, flags, { patch }) {
+  /** @type {Record<string, any>} */
+  const body = {};
+  const text = (name) => {
+    const v = givenFlag(flags[name]);
+    if (v !== undefined) body[name] = v;
+  };
+  text("title");
+  text("description");
+
+  for (const name of ["type", "status", "priority"]) {
+    const v = oneValue(flags, name);
+    if (v !== undefined) body[name] = v;
+  }
+  // Nullable enums: `-` clears them, which is only meaningful on a patch.
+  for (const name of ["size", "clarity"]) {
+    const v = oneValue(flags, name);
+    if (v === undefined) continue;
+    body[name] = patch && (v === "-" || v === "") ? null : v;
+  }
+  for (const [name, key] of [["assignee", "assigneeId"], ["reviewer", "reviewerId"]]) {
+    const v = oneValue(flags, name);
+    if (v === undefined) continue;
+    body[key] = await resolveUser(ctx, v, { flag: `--${name}`, allowClear: true });
+  }
+  if (flags.epic !== undefined) {
+    body.epicNumber = epicRef(oneValue(flags, "epic"), { allowNone: patch });
+  }
+  return body;
+}
+
 async function create(args, flags) {
   const ctx = resolveContext(flags);
-  const title = flags.title ?? args.join(" ").trim();
+  const title = oneValue(flags, "title") ?? args.join(" ").trim();
   if (!title) {
     throw new CliError("A task needs a title.", {
       hint: 'zumino task create --title "…"',
     });
   }
   const base = await projectPath(ctx);
-  const body = { title };
-  // `!== undefined`, not truthiness: `--description ""` is an instruction to
-  // leave it blank, and dropping it silently left whatever was there.
-  if (givenFlag(flags.description) !== undefined) body.description = flags.description;
-  if (givenFlag(flags.status) !== undefined) body.status = flags.status;
-  // An **epic** reference in this project, and nothing else.
-  //
-  // `epicNumber` is project-local, so a key prefix cannot express a foreign
-  // epic — its only effect was to let one through silently: `OPS-E14` targeted
-  // epic 14 *here*. And stripping leading letters off anything turned the task
-  // code `ONS-14` into epic 14, which is legal because task and epic numbers are
-  // separate namespaces, so the task was created under the wrong parent and
-  // reported success. Accept `E3` or `3`; refuse everything else and say why.
-  if (givenFlag(flags.epic) !== undefined) {
-    const raw = String(flags.epic).trim();
-    const m = /^[Ee]?(\d+)$/.exec(raw);
-    if (!m) {
-      throw new CliError(`--epic "${raw}" is not an epic in this project.`, {
-        hint:
-          "Write E3 or 3. A task code like ONS-14 is not an epic, and an epic in " +
-          "another project cannot be a parent — move the task instead.",
-      });
-    }
-    body.epicNumber = positiveInt(m[1], "epic");
-  }
+  const body = { ...(await fields(ctx, flags, { patch: false })), title };
 
   const res = pick(await api(ctx, "POST", `${base}/tasks`, { body }), "task");
   if (flags.json) return json(res), 0;
@@ -66,15 +229,41 @@ async function create(args, flags) {
   return 0;
 }
 
+/**
+ * One PATCH carrying every field that was named.
+ *
+ * It exists because the alternative was five calls and five audit groups for one
+ * decision: the history renders a group as one sentence, so `--priority critical
+ * --status in_progress` should read as one move and not two. `status` and
+ * `assign` keep their own subcommands — they are the two an agent does
+ * constantly, and they want to be three words.
+ */
+async function edit(args, flags) {
+  const [itemRef] = args;
+  if (!itemRef) throw new CliError("zumino task edit <CODE> [fields]");
+  const ctx = resolveContext(flags);
+  const body = await fields(ctx, flags, { patch: true });
+  if (Object.keys(body).length === 0) {
+    throw new CliError("Nothing to change.", {
+      hint: "Name at least one field. See: zumino help task edit",
+    });
+  }
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const res = pick(await api(ctx, "PATCH", path, { body }), "task");
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${Object.keys(body).join(", ")} written`);
+  return 0;
+}
+
 async function status(args, flags) {
-  const [ref, value] = args;
-  if (!ref || !value) {
+  const [itemRef, value] = args;
+  if (!itemRef || !value) {
     throw new CliError("zumino task status <CODE> <status>", {
-      hint: "Statuses are tokens: backlog, shaping, todo, in_progress, done, wont_do.",
+      hint: "Statuses are tokens: backlog, shaping, todo, in_progress, in_review, done, wont_do.",
     });
   }
   const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
   const res = pick(await api(ctx, "PATCH", path, { body: { status: value } }), "task");
   if (flags.json) return json(res), 0;
   out(`${codeOf(res)}  ${res.status}`);
@@ -82,28 +271,20 @@ async function status(args, flags) {
 }
 
 async function assign(args, flags) {
-  const [ref, who] = args;
-  if (!ref || !who) {
-    throw new CliError("zumino task assign <CODE> <userId|->", {
+  const [itemRef, who] = args;
+  if (!itemRef || !who) {
+    throw new CliError("zumino task assign <CODE> <userId|me|->", {
       hint: "`-` clears the assignee. An assignee is always a person, even when an agent does the work.",
     });
   }
-  // An email is the natural guess and the server cannot say so: it looks the
-  // value up as a user id and refuses with "not a member of this workspace",
-  // which reads as "that person has no access" rather than "that is the wrong
-  // kind of value". Caught here, where the difference is still visible.
-  if (who !== "-" && /@/.test(who)) {
-    throw new CliError(`"${who}" looks like an email; assign takes a user id.`, {
-      hint: "Find one on an item you can read: zumino task show <CODE> --json | jq -r '.assignee.id'",
-    });
-  }
-
+  // The shape of the argument is checked before anything is resolved: an email
+  // here is wrong whether or not a credential exists, and "No Zumino account is
+  // configured" is the less useful of the two answers.
+  const person = assertUserRef(who, { flag: "assign", allowClear: true });
   const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "task" });
-  const res = pick(
-    await api(ctx, "PATCH", path, { body: { assigneeId: who === "-" ? null : who } }),
-    "task",
-  );
+  const assigneeId = await resolveUserRef(ctx, person);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const res = pick(await api(ctx, "PATCH", path, { body: { assigneeId } }), "task");
   if (flags.json) return json(res), 0;
   out(`${codeOf(res)}  ${safeText(res.assignee?.name) || "unassigned"}`);
   return 0;
@@ -115,9 +296,9 @@ async function assign(args, flags) {
  * be judged against.
  */
 async function spec(args, flags) {
-  const [ref] = args;
+  const [itemRef] = args;
   const section = flags.plan !== undefined ? "plan" : flags.acceptance !== undefined ? "acceptance" : null;
-  if (!ref || !section) {
+  if (!itemRef || !section) {
     throw new CliError("zumino task spec <CODE> --plan TEXT | --acceptance TEXT", {
       hint: "One section per call, on purpose.",
     });
@@ -128,41 +309,41 @@ async function spec(args, flags) {
     });
   }
   const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
   const body = section === "plan" ? flags.plan : flags.acceptance;
   const res = pick(
     await api(ctx, "PUT", `${path}/spec/${section}`, { body: { body: body === "" ? null : body } }),
     "task",
   );
   if (flags.json) return json(res), 0;
-  out(`${ref}  ${section} written`);
+  out(`${itemRef}  ${section} written`);
   return 0;
 }
 
 async function comment(args, flags) {
-  const [ref, ...text] = args;
+  const [itemRef, ...text] = args;
   const bodyText = flags.body ?? text.join(" ").trim();
-  if (!ref || !bodyText) throw new CliError("zumino task comment <CODE> <text>");
+  if (!itemRef || !bodyText) throw new CliError("zumino task comment <CODE> <text>");
   const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
   const res = pick(await api(ctx, "POST", `${path}/comments`, { body: { body: bodyText } }), "comment");
   if (flags.json) return json(res), 0;
-  out(`${ref}  commented`);
+  out(`${itemRef}  commented`);
   return 0;
 }
 
 const LINK_TYPES = { blocks: "blocks", "blocked-by": "blockedBy", blockedby: "blockedBy", related: "related", answers: "answers" };
 
 async function link(args, flags) {
-  const [ref, kind, other] = args;
+  const [itemRef, kind, other] = args;
   const type = LINK_TYPES[String(kind ?? "").toLowerCase()];
-  if (!ref || !type || !other) {
+  if (!itemRef || !type || !other) {
     throw new CliError("zumino task link <CODE> <blocks|blocked-by|related|answers> <CODE|project#N>", {
       hint: "`answers` says this work exists because of a request, and takes project#N.",
     });
   }
   const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
   // A far end written `project#42` is a request; anything else is a task. The
   // API takes them under different keys because only a request can be answered.
   const body = other.includes("#") && !/^#?\d+$/.test(other)
@@ -170,7 +351,7 @@ async function link(args, flags) {
     : { type, task: other };
   const res = pick(await api(ctx, "POST", `${path}/links`, { body }), "task");
   if (flags.json) return json(res), 0;
-  out(`${ref}  ${type}  ${other}`);
+  out(`${itemRef}  ${type}  ${other}`);
   return 0;
 }
 
@@ -185,7 +366,7 @@ async function ref(args, flags) {
   const ctx = resolveContext(flags);
   const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
   const body = { url };
-  if (givenFlag(flags.title) !== undefined) body.title = flags.title;
+  if (givenFlag(flags.title) !== undefined) body.title = givenFlag(flags.title);
   const res = pick(await api(ctx, "POST", `${path}/refs`, { body }), "ref");
   if (flags.json) return json(res), 0;
   out(`${itemRef}  ${url}`);
@@ -209,15 +390,39 @@ async function attention(args, flags) {
   return 0;
 }
 
-async function show(args, flags) {
-  const [itemRef] = args;
-  if (!itemRef) throw new CliError("zumino task show <CODE>");
+async function tag(args, flags) {
+  return setTag(args, flags, true);
+}
+
+async function untag(args, flags) {
+  return setTag(args, flags, false);
+}
+
+/**
+ * A tag on or off, by id.
+ *
+ * By id and not by name because a palette belongs to a project and names repeat
+ * across them — `zumino project tags` is the read that turns one into the other,
+ * and it is the only reason that command exists.
+ */
+async function setTag(args, flags, on) {
+  const [itemRef, tagId] = args;
+  const verb = on ? "tag" : "untag";
+  if (!itemRef || !tagId) {
+    throw new CliError(`zumino task ${verb} <CODE> <tagId>`, {
+      hint: "List the project's tag ids with: zumino project tags",
+    });
+  }
   const ctx = resolveContext(flags);
   const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
-  const res = pick(await api(ctx, "GET", path), "task");
-  if (flags.json) return json(res), 0;
-  out(`${codeOf(res)}  ${safeText(res.title)}`);
-  out(`status ${res.status}   priority ${res.priority ?? "-"}   assignee ${safeText(res.assignee?.name) || "-"}`);
-  if (res.description) out(`\n${safeText(res.description)}`);
+  // Written as two calls with literal methods rather than one with a ternary:
+  // `test/cli-routes.test.ts` reads these call sites out of the source to check
+  // each against the server, and a method it cannot read is an endpoint nothing
+  // checks.
+  const res = on
+    ? await api(ctx, "PUT", `${path}/tags/${encodeURIComponent(tagId)}`)
+    : await api(ctx, "DELETE", `${path}/tags/${encodeURIComponent(tagId)}`);
+  if (flags.json) return json(res ?? { ok: true }), 0;
+  out(`${itemRef}  ${on ? "tagged" : "untagged"}`);
   return 0;
 }

package/src/commands/workspace.js

@@ -0,0 +1,51 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { clip, json, note, out, table } from "../output.js";
+
+/*
+ * The workspaces a token can reach.
+ *
+ * **The bootstrap read.** Every other path on this API carries a `{workspace}`
+ * segment, so a client holding a fresh token cannot build a single URL until
+ * this one has answered — which is exactly why it was the first thing missing: a
+ * CLI with no way to ask "what am I looking at" sends its user to
+ * `zumino api GET /workspaces`, and an escape hatch is not an answer to the
+ * first question anybody has.
+ *
+ * There is nothing else here, and that is the API's shape rather than an
+ * omission: creating a workspace, membership and roles are governance, and an
+ * agent changes the work and not the workspace (`DOMAIN.md` § Rules).
+ */
+
+export const SUB = { list };
+
+export async function run(args, flags) {
+  const [sub, ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino workspace: unknown subcommand "${sub ?? ""}".`, {
+      hint: `One of: ${Object.keys(SUB).join(", ")}`,
+    });
+  }
+  return fn(rest, flags);
+}
+
+async function list(args, flags) {
+  const ctx = resolveContext(flags);
+  const res = await api(ctx, "GET", "/workspaces");
+  const workspaces = res?.workspaces ?? [];
+  if (flags.json) return json(workspaces), 0;
+
+  if (workspaces.length === 0) {
+    out("No workspaces.");
+    note("  A token acts for its owner, so this is every workspace they belong to.");
+    return 0;
+  }
+
+  table(
+    workspaces.map((w) => [w.slug ?? "", w.role ?? "", clip(w.name)]),
+    { head: ["SLUG", "ROLE", "NAME"] },
+  );
+  return 0;
+}

package/src/events.js

@@ -0,0 +1,104 @@
+import { api } from "./client.js";
+import { oneValue, positiveInt } from "./flags.js";
+import { clip, dim, json, out, safeText, table } from "./output.js";
+
+/*
+ * The activity log, for whatever the activity is about.
+ *
+ * One renderer rather than one per kind, because the endpoint is one pager: a
+ * task and a request produce structurally identical events — same kinds, same
+ * two sides, same actor — and the server publishes them through the same view.
+ *
+ * **What this is for.** The comment thread records what people *said*; this
+ * records what anyone, person or agent, actually *did*. "What was tried and then
+ * reverted" is the context an executor cannot recover any other way, and the
+ * usual cost of not having it is re-doing an approach somebody abandoned for a
+ * reason nobody wrote down.
+ */
+
+/**
+ * @param {any} ctx
+ * @param {string} itemPath  the item's own path, as the server published it
+ * @param {Record<string, any>} flags
+ */
+export async function listEvents(ctx, itemPath, flags) {
+  const res = await api(ctx, "GET", `${itemPath}/events`, {
+    query: {
+      // Single-valued: the endpoint reads one `?kind=` and one `?field=`, so a
+      // second would be dropped rather than widen the filter.
+      kind: oneValue(flags, "kind"),
+      field: oneValue(flags, "field"),
+      limit: positiveInt(flags.limit, "limit"),
+      before: oneValue(flags, "before"),
+    },
+  });
+
+  const events = res?.events ?? [];
+  if (flags.json) return json(res), 0;
+  if (events.length === 0) return out("No events."), 0;
+
+  table(
+    events.map((e) => [
+      when(e.createdAt),
+      e.kind ?? "",
+      e.field ?? "",
+      safeText(e.actor?.name) || "—",
+      move(e),
+    ]),
+    { head: ["WHEN", "KIND", "FIELD", "WHO", "WHAT"] },
+  );
+
+  /*
+   * `total` is the history's whole length, NOT the number of rows the filter
+   * matched — the endpoint counts every event on the item and pages the filtered
+   * set. Printed as "1 of 6" that reads as "five more matches", which is the
+   * wrong thing to believe about a filter, so a filtered page says what it is.
+   */
+  const more = res?.nextBefore;
+  const total = typeof res?.total === "number" ? res.total : null;
+  const filtered = Boolean(flags.kind || flags.field);
+  const count =
+    total === null
+      ? `${events.length} shown.`
+      : filtered
+        ? `${events.length} shown — the history has ${total} events in all.`
+        : `${events.length} of ${total}.`;
+  out(dim(`\n${count}${more ? `  Next page: --before ${more}` : ""}`));
+  return 0;
+}
+
+/** `2026-09-10 14:02`, in the reader's own zone. Seconds are noise here. */
+function when(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return safeText(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/**
+ * `before → after`, short enough for a row.
+ *
+ * A list response elides long values and says so (`truncated`), so a spec
+ * rewrite reads as a length rather than as half a document pasted into a table.
+ * The full stored value is one event read away — `zumino api GET …/events/{id}`.
+ */
+function move(e) {
+  const side = (v) => {
+    if (!v) return "";
+    if (v.truncated) return `${clip(v.value, 24)} (${v.length} chars)`;
+    const value = v.value;
+    if (value === null || value === undefined) return "—";
+    if (typeof value === "string") return clip(value, 28);
+    // A person, as the log records one: `{id, name}`. Printed as JSON it fills
+    // the column with an id nobody reads, and the name is the whole point of
+    // the row — `assigneeId: — → Yuna Park`.
+    if (value && typeof value === "object" && "id" in value && "name" in value) {
+      return clip(value.name ?? value.id, 28);
+    }
+    return clip(JSON.stringify(value), 28);
+  };
+  const before = side(e.before);
+  const after = side(e.after);
+  if (!before && !after) return "";
+  return before ? `${before} → ${after}` : after;
+}