@coldtea/pr-lens-cli 0.3.0 → 0.5.0

package/dist/version.js

@@ -1,4 +1,4 @@
 /** Recorded on every document this CLI produces, as the generator's version. */
-export const CLI_VERSION = "0.3.0";
+export const CLI_VERSION = "0.5.0";
 export const GENERATOR_NAME = "pr-lens-cli";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The PR Lens command line: turn a pull request diff into a schema-valid graph with your own model key, render it, and compose the comment.",
   "license": "MIT",
   "author": "Coldtea AI",
@@ -40,8 +40,8 @@
   "dependencies": {
     "yaml": "^2.8.1",
     "zod": "^4.4.3",
-    "@coldtea/pr-lens-renderer": "^0.1.2",
-    "@coldtea/pr-lens-schema": "^0.1.2"
+    "@coldtea/pr-lens-renderer": "^0.2.3",
+    "@coldtea/pr-lens-schema": "^0.2.1"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/src/canvas/api.ts

@@ -1,11 +1,12 @@
+import { z } from "zod";
 import {
   assertNever,
   safeParseGraphDoc,
   type GraphDoc,
 } from "@coldtea/pr-lens-schema";
-import { z } from "zod";
-import { PrLensCliError } from "../errors.js";
+
 import { CLI_VERSION } from "../version.js";
+import { PrLensCliError } from "../errors.js";
 
 const REQUEST_TIMEOUT_MS = 60_000;
 
@@ -87,7 +88,7 @@ const Refusal = z.discriminatedUnion("code", [
 ]);
 
 type Request = {
-  method: "GET" | "POST" | "PUT";
+  method: "GET" | "POST" | "PUT" | "DELETE";
   path: string;
   /** Undefined when minting, so a 404 there is not blamed on a canvas. */
   canvas: string | undefined;
@@ -310,3 +311,14 @@ export const rotateCanvas = (
     },
     Rotated,
   );
+
+export const deleteCanvas = (
+  api: string,
+  id: string,
+  token: string,
+): Promise<{ id: string; deleted: true }> =>
+  call(
+    api,
+    { method: "DELETE", path: canvasPath(id), canvas: id, token },
+    z.object({ id: z.literal(id), deleted: z.literal(true) }),
+  );

package/src/canvas/delete.ts

@@ -0,0 +1,39 @@
+import { deleteCanvas } from "./api.js";
+import { usageError } from "../errors.js";
+import type { Terminal } from "../terminal.js";
+import { parseOptions, readString } from "../args.js";
+import { selectCanvas, readRegistry, updateRegistry } from "./registry.js";
+import { readApi, requireWriteToken, settlePendingRotation } from "./write.js";
+
+export const deleteCommand = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    canvas: { type: "string" },
+    api: { type: "string" },
+  });
+  if (positionals.length > 0)
+    throw usageError(
+      `delete takes no positional arguments, got ${positionals.join(" ")}`,
+    );
+
+  const api = readApi(values.api, env);
+
+  const registry = await readRegistry();
+
+  const ref = readString(values.canvas, "canvas");
+  const selected = selectCanvas(registry, ref);
+
+  const target = await settlePendingRotation(api, selected, terminal);
+  await deleteCanvas(api, target.id, requireWriteToken(target));
+
+  await updateRegistry((current) => {
+    if (current.canvases[target.id]?.api === api)
+      delete current.canvases[target.id];
+  }, terminal);
+  terminal.out(
+    `✓ deleted ${target.id} from ${api}; local graph and SVG files kept`,
+  );
+};

package/src/canvas/registry.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import {
   access,
   link,
@@ -9,14 +10,12 @@ import {
   readFile,
   writeFile,
 } from "node:fs/promises";
-import { z } from "zod";
 import type { Stats } from "node:fs";
 import { randomBytes } from "node:crypto";
+import { assertNever } from "@coldtea/pr-lens-schema";
 import { setTimeout as sleep } from "node:timers/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 
-import { assertNever } from "@coldtea/pr-lens-schema";
-
 import { git } from "../git.js";
 import type { Terminal } from "../terminal.js";
 import { PrLensCliError, usageError } from "../errors.js";
@@ -477,3 +476,9 @@ export const onlyCanvas = (registry: CanvasRegistry): Registered => {
 
   return only;
 };
+
+export const selectCanvas = (
+  registry: CanvasRegistry,
+  ref: string | undefined,
+): Registered =>
+  ref === undefined ? onlyCanvas(registry) : findCanvas(registry, ref);

package/src/canvas/write.ts

@@ -0,0 +1,128 @@
+import { readString } from "../args.js";
+import { rotateCanvas } from "./api.js";
+import type { Terminal } from "../terminal.js";
+import { PrLensCliError, usageError } from "../errors.js";
+import { updateRegistry, type Registered } from "./registry.js";
+
+export const DEFAULT_API = "https://prlens.dev";
+export const API_ENV = "PR_LENS_API_URL";
+
+export const readApi = (
+  value: unknown,
+  env: Record<string, string | undefined>,
+): string => {
+  const api = readString(value, "api") ?? env[API_ENV] ?? DEFAULT_API;
+  try {
+    new URL(api);
+  } catch {
+    throw usageError(`--api needs a URL, got ${JSON.stringify(api)}`);
+  }
+  return api.replace(/\/+$/, "");
+};
+
+/** Another app's 404 says nothing about this entry, so it must not change it. */
+export const requireSameApi = (
+  api: string,
+  { id, entry }: Registered,
+): void => {
+  if (entry.api === api) return;
+  throw new PrLensCliError(
+    "CANVAS_UNREGISTERED",
+    `${id} is registered against ${entry.api}, not ${api}`,
+    `pass --api ${entry.api}, or push the document without --canvas to mint a canvas here`,
+  );
+};
+
+export const requireWriteToken = ({ id, entry }: Registered): string => {
+  if (entry.writeToken !== undefined) return entry.writeToken;
+  throw new PrLensCliError(
+    "CANVAS_UNREGISTERED",
+    `this checkout can read ${id} but holds no write token for it`,
+    "pull its edit link, the one with #w= at the end, and the token comes with it",
+  );
+};
+
+const unfinishedRotation = (error: PrLensCliError): PrLensCliError =>
+  new PrLensCliError(
+    error.code,
+    `${error.message}; the rotation is not finished`,
+    [
+      error.details,
+      "run pr-lens canvas rotate again to finish it: the new token is kept until the app confirms it",
+    ]
+      .filter((line) => line !== undefined && line !== "")
+      .join("\n"),
+  );
+
+/** Asking again with the same pair is safe: the app answers "rotated" once the token is on record. */
+export const settleRotation = async (
+  api: string,
+  { id, entry }: Registered,
+  nextToken: string,
+  terminal: Terminal,
+): Promise<{ registered: Registered; editUrl: string }> => {
+  const rotated = await rotateCanvas(
+    api,
+    id,
+    requireWriteToken({ id, entry }),
+    nextToken,
+  ).catch(async (error: unknown) => {
+    if (!(error instanceof PrLensCliError)) throw error;
+    if (error.code !== "CANVAS_UNKNOWN") throw unfinishedRotation(error);
+
+    // Final: a pending token that was current would have been answered
+    // "rotated". Drop it now, or a token imported later would carry it out.
+    await updateRegistry((registry) => {
+      const current = registry.canvases[id];
+      if (
+        current === undefined ||
+        current.pending !== nextToken ||
+        current.api !== api
+      )
+        return;
+      registry.canvases[id] = { ...current, pending: undefined };
+    }, terminal);
+    throw new PrLensCliError(
+      error.code,
+      `${error.message}; the pending rotation was dropped`,
+      error.details,
+    );
+  });
+
+  // A different token pending by now belongs to a later rotation.
+  await updateRegistry((registry) => {
+    const current = registry.canvases[id];
+    if (
+      current === undefined ||
+      current.pending !== nextToken ||
+      current.api !== api
+    )
+      return;
+    registry.canvases[id] = {
+      ...current,
+      writeToken: nextToken,
+      pending: undefined,
+    };
+  }, terminal);
+
+  return {
+    registered: {
+      id,
+      entry: { ...entry, writeToken: nextToken, pending: undefined },
+    },
+    editUrl: rotated.editUrl,
+  };
+};
+
+export const settlePendingRotation = async (
+  api: string,
+  registered: Registered,
+  terminal: Terminal,
+): Promise<Registered> => {
+  requireSameApi(api, registered);
+  requireWriteToken(registered);
+  const pending = registered.entry.pending;
+  return pending === undefined
+    ? registered
+    : (await settleRotation(api, registered, pending, terminal)).registered;
+};

package/src/cli.ts

@@ -1,4 +1,5 @@
 import { assertNever } from "@coldtea/pr-lens-schema";
+
 import { CLI_VERSION } from "./version.js";
 import type { Terminal } from "./terminal.js";
 import { formatError, PrLensCliError } from "./errors.js";
@@ -23,7 +24,7 @@ const HELP = `pr-lens — review what actually matters
   pr-lens comment   --graph --manifest      the pull request comment, as markdown
   pr-lens validate  <file...>               any PR Lens document, checked against the contract
   pr-lens export    <graph.json>            the merged state, as a map worth committing
-  pr-lens canvas    push | pull | rotate    that document, kept on prlens.dev as a page and an embed
+  pr-lens canvas    push | pull | rotate | delete    that document, kept on prlens.dev as a page and an embed
   pr-lens skill                             diagram instructions for coding agents
 
   pr-lens <command> --help                  what a command takes

package/src/commands/canvas.ts

@@ -1,10 +1,9 @@
 import { assertNever } from "@coldtea/pr-lens-schema";
-import { parseOptions, readString } from "../args.js";
+
 import {
   fetchCanvas,
   mintCanvas,
   pushCanvas,
-  rotateCanvas,
   verifyWriteToken,
 } from "../canvas/api.js";
 import {
@@ -13,7 +12,7 @@ import {
   findCanvas,
   isCanvasId,
   mintWriteToken,
-  onlyCanvas,
+  selectCanvas,
   isReservedRegistryTarget,
   readRegistry,
   REGISTRY_PATH,
@@ -25,27 +24,28 @@ import {
   type CanvasRegistry,
   type Registered,
 } from "../canvas/registry.js";
-import { readGraphDoc } from "../document.js";
-import { PrLensCliError, usageError } from "../errors.js";
 import { writeJsonFile } from "../io.js";
+import { readGraphDoc } from "../document.js";
 import type { Terminal } from "../terminal.js";
 import { WORKSPACE_DIR } from "../workspace.js";
+import { deleteCommand } from "../canvas/delete.js";
+import { parseOptions, readString } from "../args.js";
+import { PrLensCliError, usageError } from "../errors.js";
+import { DEFAULT_API, API_ENV, readApi, requireSameApi, requireWriteToken, settleRotation, settlePendingRotation } from "../canvas/write.js";
 
-const DEFAULT_API = "https://prlens.dev";
-const API_ENV = "PR_LENS_API_URL";
 const DEFAULT_SOURCE = `${WORKSPACE_DIR}/drawn.graph.json`;
 const DEFAULT_OUT = `${WORKSPACE_DIR}/graph.json`;
 
-const SUBCOMMANDS = ["push", "pull", "rotate"] as const;
+const SUBCOMMANDS = ["push", "pull", "rotate", "delete"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
 const isSubcommand = (value: string): value is Subcommand =>
   SUBCOMMANDS.some((subcommand) => subcommand === value);
 
-export const USAGE = `pr-lens canvas <push | pull | rotate> [options]
+export const USAGE = `pr-lens canvas <push | pull | rotate | delete> [options]
 
-Keeps a graph document on the PR Lens app as a canvas: a page anyone with the
-link can read, and an SVG a README can embed. The write token lands in
+Keeps a graph document on the PR Lens app as a canvas: a page anyone you share
+it with can read, and an SVG a README can embed. The write token lands in
 ${REGISTRY_PATH}, which git ignores; the edit link carries the same token
 in its fragment, so share the view link and keep the edit link to yourself.
 
@@ -61,20 +61,10 @@ in its fragment, so share the view link and keep the edit link to yourself.
   pr-lens canvas rotate                mint a new write token; the old edit link stops working
     --canvas <id|name>                 which canvas (default the checkout's only canvas)
 
-  --api <url>                          the PR Lens app (default $${API_ENV}, else ${DEFAULT_API})`;
+  pr-lens canvas delete                permanently delete the hosted canvas; keep local graph and SVG files
+    --canvas <id|name>                 which canvas (default the checkout's only canvas)
 
-const readApi = (
-  value: unknown,
-  env: Record<string, string | undefined>,
-): string => {
-  const api = readString(value, "api") ?? env[API_ENV] ?? DEFAULT_API;
-  try {
-    new URL(api);
-  } catch {
-    throw usageError(`--api needs a URL, got ${JSON.stringify(api)}`);
-  }
-  return api.replace(/\/+$/, "");
-};
+  --api <url>                          the PR Lens app (default $${API_ENV}, else ${DEFAULT_API})`;
 
 type CanvasRef = {
   id: string;
@@ -114,100 +104,9 @@ const readCanvasRef = (value: string): CanvasRef => {
   return { id, origin: url.origin, writeToken };
 };
 
-/** Another app's 404 says nothing about this entry, so it must not change it. */
-const requireSameApi = (api: string, { id, entry }: Registered): void => {
-  if (entry.api === api) return;
-  throw new PrLensCliError(
-    "CANVAS_UNREGISTERED",
-    `${id} is registered against ${entry.api}, not ${api}`,
-    `pass --api ${entry.api}, or push the document without --canvas to mint a canvas here`,
-  );
-};
-
-const requireWriteToken = ({ id, entry }: Registered): string => {
-  if (entry.writeToken !== undefined) return entry.writeToken;
-  throw new PrLensCliError(
-    "CANVAS_UNREGISTERED",
-    `this checkout can read ${id} but holds no write token for it`,
-    "pull its edit link, the one with #w= at the end, and the token comes with it",
-  );
-};
-
 const countDiagrams = (count: number): string =>
   `${count} ${count === 1 ? "diagram" : "diagrams"}`;
 
-const unfinishedRotation = (error: PrLensCliError): PrLensCliError =>
-  new PrLensCliError(
-    error.code,
-    `${error.message}; the rotation is not finished`,
-    [
-      error.details,
-      "run pr-lens canvas rotate again to finish it: the new token is kept until the app confirms it",
-    ]
-      .filter((line) => line !== undefined && line !== "")
-      .join("\n"),
-  );
-
-/** Asking again with the same pair is safe: the app answers "rotated" once the token is on record. */
-const settleRotation = async (
-  api: string,
-  { id, entry }: Registered,
-  nextToken: string,
-  terminal: Terminal,
-): Promise<{ registered: Registered; editUrl: string }> => {
-  const rotated = await rotateCanvas(
-    api,
-    id,
-    requireWriteToken({ id, entry }),
-    nextToken,
-  ).catch(async (error: unknown) => {
-    if (!(error instanceof PrLensCliError)) throw error;
-    if (error.code !== "CANVAS_UNKNOWN") throw unfinishedRotation(error);
-
-    // Final: a pending token that was current would have been answered
-    // "rotated". Drop it now, or a token imported later would carry it out.
-    await updateRegistry((registry) => {
-      const current = registry.canvases[id];
-      if (
-        current === undefined ||
-        current.pending !== nextToken ||
-        current.api !== api
-      )
-        return;
-      registry.canvases[id] = { ...current, pending: undefined };
-    }, terminal);
-    throw new PrLensCliError(
-      error.code,
-      `${error.message}; the pending rotation was dropped`,
-      error.details,
-    );
-  });
-
-  // A different token pending by now belongs to a later rotation.
-  await updateRegistry((registry) => {
-    const current = registry.canvases[id];
-    if (
-      current === undefined ||
-      current.pending !== nextToken ||
-      current.api !== api
-    )
-      return;
-    registry.canvases[id] = {
-      ...current,
-      writeToken: nextToken,
-      pending: undefined,
-    };
-  }, terminal);
-
-  return {
-    registered: {
-      id,
-      entry: { ...entry, writeToken: nextToken, pending: undefined },
-    },
-    editUrl: rotated.editUrl,
-  };
-};
-
 type Recorded = "imported" | "kept" | "overtaken" | "refused" | "elsewhere";
 
 type PullRecord = {
@@ -355,12 +254,7 @@ const push = async (
       return { id: minted.id, entry };
     }));
 
-  requireSameApi(api, registered);
-  const pending = registered.entry.pending;
-  const target =
-    pending === undefined
-      ? registered
-      : (await settleRotation(api, registered, pending, terminal)).registered;
+  const target = await settlePendingRotation(api, registered, terminal);
 
   const pushed = await pushCanvas(
     api,
@@ -381,8 +275,9 @@ const push = async (
   terminal.out(
     `✓ ${pushed.viewUrl} — rev ${pushed.rev} · ${countDiagrams(pushed.tiles.length)}`,
   );
-  terminal.out(`  edit link, keep it to yourself: ${pushed.editUrl}`);
+  terminal.out("  unlisted: anyone you share it with can open it, no sign-in needed");
   terminal.out(`  README embed: ${pushed.embedUrl}`);
+  terminal.out("  remove: pr-lens canvas delete");
 };
 
 const pull = async (
@@ -408,9 +303,7 @@ const pull = async (
     positional !== undefined
       ? readCanvasRef(positional)
       : {
-          ...(ref === undefined
-            ? onlyCanvas(registry)
-            : findCanvas(registry, ref)),
+          ...selectCanvas(registry, ref),
           origin: undefined,
           writeToken: undefined,
         };
@@ -487,8 +380,7 @@ const rotate = async (
   await ensureRegistryHome(terminal);
   const registry = await readRegistry();
   const ref = readString(values.canvas, "canvas");
-  const { id } =
-    ref === undefined ? onlyCanvas(registry) : findCanvas(registry, ref);
+  const { id } = selectCanvas(registry, ref);
 
   // Saved before the request, so a lost answer cannot lose it; chosen under
   // the lock, so two rotations at once finish the same one.
@@ -532,7 +424,7 @@ export const canvasCommand = async (
 ): Promise<void> => {
   const [name, ...rest] = args;
   if (name === undefined)
-    throw usageError("canvas needs a subcommand: push, pull or rotate");
+    throw usageError("canvas needs a subcommand: push, pull, rotate or delete");
   if (!isSubcommand(name))
     throw usageError(`unknown canvas subcommand ${JSON.stringify(name)}`);
 
@@ -541,6 +433,8 @@ export const canvasCommand = async (
       return push(rest, terminal, env);
     case "pull":
       return pull(rest, terminal, env);
+    case "delete":
+      return deleteCommand(rest, terminal, env);
     case "rotate":
       return rotate(rest, terminal, env);
     default:

package/src/commands/validate.ts

@@ -10,8 +10,10 @@ const count = (n: number, singular: string): string =>
 const describe = (validated: ValidatedDocument): string => {
   switch (validated.kind) {
     case "graph": {
-      const { lanes, nodes, edges, flows, lenses } = validated.document;
-      return `graph document · ${count(lanes.length, "lane")}, ${count(nodes.length, "node")}, ${count(edges.length, "edge")}, ${count(flows.length, "flow")} · ${lenses.join(", ")}`;
+      const { lanes, nodes, edges, flows, lenses, walkthrough } = validated.document;
+      const tour =
+        walkthrough === undefined ? "" : ` · ${count(walkthrough.steps.length, "walkthrough step")}`;
+      return `graph document · ${count(lanes.length, "lane")}, ${count(nodes.length, "node")}, ${count(edges.length, "edge")}, ${count(flows.length, "flow")} · ${lenses.join(", ")}${tour}`;
     }
     case "patch":
       return `patch document · ${count(validated.document.ops.length, "operation")} · ${validated.document.target.fromSha.slice(0, 7)} → ${validated.document.target.toSha.slice(0, 7)}`;