@coldtea/pr-lens-cli 0.7.0 → 0.8.0

package/src/commands/canvas.ts

@@ -2,13 +2,17 @@ import { assertNever } from "@coldtea/pr-lens-schema";
 
 import {
   fetchCanvas,
+  listOwnedCanvases,
   mintCanvas,
   pushCanvas,
   verifyWriteToken,
+  type CanvasPreview,
+  type OwnedCanvas,
 } from "../canvas/api.js";
 import {
   ensureRegistryHome,
   findBySource,
+  findByTitle,
   findCanvas,
   isCanvasId,
   mintWriteToken,
@@ -25,31 +29,50 @@ import {
   type Registered,
 } from "../canvas/registry.js";
 import { writeJsonFile } from "../io.js";
+import { readInstallId } from "../install.js";
 import { readGraphDoc } from "../document.js";
 import type { Terminal } from "../terminal.js";
-import { WORKSPACE_DIR } from "../workspace.js";
+import { drawings, WORKSPACE_DIR } from "../workspace.js";
+import { readToken, requireToken } from "../auth.js";
+import { claimCommand } from "../canvas/claim.js";
 import { deleteCommand } from "../canvas/delete.js";
-import { parseOptions, readString } from "../args.js";
+import { parseOptions, readBoolean, readString } from "../args.js";
 import { PrLensCliError, usageError } from "../errors.js";
-import { DEFAULT_API, API_ENV, readApi, requireSameApi, requireWriteToken, settleRotation, settlePendingRotation } from "../canvas/write.js";
+import { DEFAULT_API, API_ENV, readApi, requireSameApi, requireWriteToken, settleRotation, settlePendingRotation, writeCredential } from "../canvas/write.js";
 
-const DEFAULT_SOURCE = `${WORKSPACE_DIR}/drawn.graph.json`;
+const DRAWN = "drawn.graph.json";
+
+/** Where 0.7.0 rendered; its registry entries still name this path. */
+const LEGACY_SOURCE = `${WORKSPACE_DIR}/${DRAWN}`;
 const DEFAULT_OUT = `${WORKSPACE_DIR}/graph.json`;
 
-const SUBCOMMANDS = ["push", "pull", "rotate", "delete"] as const;
+const SUBCOMMANDS = [
+  "list",
+  "push",
+  "pull",
+  "claim",
+  "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 | delete> [options]
+export const USAGE = `pr-lens canvas <list | push | pull | claim | rotate | delete> [options]
 
 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.
 
-  pr-lens canvas push [graph.json]     send the document (default ${DEFAULT_SOURCE})
+  pr-lens canvas list                  every canvas this checkout knows
+    --remote                           add every canvas the signed-in account owns
+    --api <url>                        only the canvases at that app
+    --json                             the same listing, for scripts
+
+  pr-lens canvas push [graph.json]     send the document (default the checkout's
+                                       only drawing, under ${WORKSPACE_DIR}/)
     --canvas <id|name>                 which canvas (default the one this document
                                        was pushed to before, else a new one)
     --name <name>                      what to call a new canvas (default the document's title)
@@ -58,6 +81,10 @@ in its fragment, so share the view link and keep the edit link to yourself.
     --canvas <id|name>                 which canvas, when no url or id is given
     -o, --out <file>                   where to write it (default ${DEFAULT_OUT})
 
+  pr-lens canvas claim <id|name>       take a canvas onto the account this machine
+                                       is signed in to, proving it with the write
+                                       token; that token is retired in the same step
+
   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)
 
@@ -140,7 +167,8 @@ const recordPull = (current: CanvasRegistry, pull: PullRecord): Recorded => {
     name: entry?.name ?? pull.fetched?.title ?? pull.id,
     source:
       entry?.source ??
-      (pull.fetched === undefined ? DEFAULT_SOURCE : sourceKey(pull.out)),
+      // No document, so no source a bare push could resolve to.
+      (pull.fetched === undefined ? undefined : sourceKey(pull.out)),
     api: pull.api,
     ...(pending === undefined ? {} : { pending }),
     ...(kept === undefined ? {} : { writeToken: kept }),
@@ -187,6 +215,38 @@ const tellRecorded = (
   }
 };
 
+/** Like `onlyCanvas`: none or several is reported, never guessed at. */
+const onlyDrawing = async (): Promise<string> => {
+  const found = await drawings();
+  const [only, ...more] = found;
+
+  if (only === undefined)
+    throw usageError(
+      `no drawing in ${WORKSPACE_DIR}/`,
+      "pr-lens render <graph.json> draws one, or name the document to push",
+    );
+
+  if (more.length > 0)
+    throw usageError(
+      `${found.length} drawings in ${WORKSPACE_DIR}/`,
+      `name the one to push: ${found.join(", ")}`,
+    );
+
+  return only;
+};
+
+/**
+ * Without this, the first push after upgrading from 0.7.0 would orphan the
+ * old canvas. The push records the new path, so it is adopted once.
+ */
+const adoptLegacy = (
+  registry: CanvasRegistry,
+  source: string,
+): Registered | undefined =>
+  sourceKey(source) === sourceKey(LEGACY_SOURCE)
+    ? undefined
+    : findBySource(registry, LEGACY_SOURCE);
+
 const push = async (
   args: readonly string[],
   terminal: Terminal,
@@ -202,16 +262,19 @@ const push = async (
       `push takes one graph document, got ${positionals.length}`,
     );
 
-  const source = positionals[0] ?? DEFAULT_SOURCE;
+  const source = positionals[0] ?? (await onlyDrawing());
   const document = await readGraphDoc(source);
   const api = readApi(values.api, env);
   await ensureRegistryHome(terminal);
   const registry = await readRegistry();
 
   const ref = readString(values.canvas, "canvas");
+  // A push onto a known path updates, so a redraw moves the canvas on a revision.
   const known =
     ref === undefined
-      ? findBySource(registry, source)
+      ? findBySource(registry, source) ??
+        adoptLegacy(registry, source) ??
+        findByTitle(registry, document.title)
       : findCanvas(registry, ref);
 
   const registered: Registered =
@@ -224,7 +287,12 @@ const push = async (
         ref === undefined ? findBySource(current, source) : undefined;
       if (meanwhile !== undefined) return meanwhile;
 
-      const minted = await mintCanvas(api);
+      // Only a mint names the machine.
+      const minted = await mintCanvas(
+        api,
+        await readInstallId(env, api),
+        await readToken(env, api),
+      );
       const entry: CanvasEntry = {
         name: readString(values.name, "name") ?? document.title,
         source: sourceKey(source),
@@ -254,12 +322,12 @@ const push = async (
       return { id: minted.id, entry };
     }));
 
-  const target = await settlePendingRotation(api, registered, terminal);
+  const target = await settlePendingRotation(api, registered, terminal, env);
 
   const pushed = await pushCanvas(
     api,
     target.id,
-    requireWriteToken(target),
+    await writeCredential(target, env, api),
     target.entry.rev,
     document,
   );
@@ -380,7 +448,13 @@ const rotate = async (
   await ensureRegistryHome(terminal);
   const registry = await readRegistry();
   const ref = readString(values.canvas, "canvas");
-  const { id } = selectCanvas(registry, ref);
+  const selected = selectCanvas(registry, ref);
+  const { id } = selected;
+
+  // Checked before the pending token is saved, or an unauthorised rotation
+  // would leave one behind for the next push to carry out.
+  requireSameApi(api, selected);
+  await writeCredential(selected, env, api);
 
   // Saved before the request, so a lost answer cannot lose it; chosen under
   // the lock, so two rotations at once finish the same one.
@@ -388,10 +462,7 @@ const rotate = async (
   await updateRegistry((current) => {
     const entry = current.canvases[id];
     if (entry === undefined) return;
-    // Without a token, a pending rotation would be carried out by whatever
-    // token arrives next, retiring the very link that brought it.
     requireSameApi(api, { id, entry });
-    requireWriteToken({ id, entry });
     pending = {
       id,
       entry: { ...entry, pending: entry.pending ?? mintWriteToken() },
@@ -409,6 +480,7 @@ const rotate = async (
     pending,
     pending.entry.pending,
     terminal,
+    env,
   );
 
   const view = new URL(editUrl);
@@ -417,6 +489,148 @@ const rotate = async (
   terminal.out("  the old edit link no longer works");
 };
 
+type Listed = {
+  id: string;
+  name: string;
+  api: string;
+  rev: number;
+  /** False for a view-link pull: the app keeps only the token's hash. */
+  editHere: boolean;
+};
+
+const byNameThenId = (a: Listed, b: Listed): number =>
+  a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
+
+/** Not spread: the entry carries write tokens, which must not be listed. */
+const listed = (registry: CanvasRegistry): Listed[] =>
+  Object.entries(registry.canvases)
+    .map(([id, entry]) => ({
+      id,
+      name: entry.name,
+      api: entry.api,
+      rev: entry.rev,
+      editHere: entry.writeToken !== undefined,
+    }))
+    .sort(byNameThenId);
+
+const previewName = (preview: CanvasPreview): string | undefined => {
+  switch (preview.type) {
+    case "drawn":
+      return preview.title;
+    case "not_drawn":
+    case "unreadable":
+      return undefined;
+    default:
+      return assertNever(preview, "Unhandled canvas preview");
+  }
+};
+
+/**
+ * The app owns names; only the registry knows whether the write token is
+ * here. Keyed by app too, since an id at another app is another canvas.
+ */
+const merged = (
+  local: readonly Listed[],
+  api: string,
+  owned: readonly OwnedCanvas[],
+): Listed[] => {
+  const rows = new Map(
+    local.map((canvas) => [`${canvas.api}\n${canvas.id}`, canvas]),
+  );
+
+  for (const canvas of owned) {
+    const key = `${api}\n${canvas.id}`;
+    const here = rows.get(key);
+    rows.set(key, {
+      id: canvas.id,
+      name: previewName(canvas.preview) ?? here?.name ?? canvas.id,
+      api,
+      rev: canvas.rev,
+      editHere: here?.editHere ?? false,
+    });
+  }
+
+  return [...rows.values()].sort(byNameThenId);
+};
+
+const HEADINGS = ["ID", "NAME", "REV", "EDIT HERE"] as const;
+
+const row = (cells: readonly string[], widths: readonly number[]): string =>
+  `  ${cells.map((cell, column) => cell.padEnd(widths[column] ?? 0)).join("  ")}`.trimEnd();
+
+const tally = (canvases: readonly Listed[]): string => {
+  const count = `${canvases.length} ${canvases.length === 1 ? "canvas" : "canvases"}`;
+  const readOnly = canvases.filter((canvas) => !canvas.editHere).length;
+  return readOnly === 0
+    ? count
+    : `${count} · ${readOnly} this checkout cannot edit`;
+};
+
+const list = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    json: { type: "boolean" },
+    remote: { type: "boolean" },
+    api: { type: "string" },
+  });
+  if (positionals.length > 0)
+    throw usageError(
+      `list takes no positional arguments, got ${positionals.join(" ")}`,
+    );
+
+  const remote = readBoolean(values.remote);
+
+  // Only the flag filters. $PR_LENS_API_URL is read only when asking an app,
+  // so a local listing neither hides canvases nor fails on a bad value.
+  const narrowed = readString(values.api, "api") !== undefined;
+  const api = readApi(values.api, remote || narrowed ? env : {});
+
+  const local = listed(await readRegistry()).filter(
+    (canvas) => !narrowed || canvas.api === api,
+  );
+
+  const canvases = remote
+    ? merged(
+        local,
+        api,
+        await listOwnedCanvases(api, await requireToken(env, api)),
+      )
+    : local;
+
+  if (readBoolean(values.json)) {
+    terminal.out(JSON.stringify({ canvases }, null, 2));
+    return;
+  }
+
+  if (canvases.length === 0) {
+    terminal.out(
+      remote
+        ? `no canvases at ${new URL(api).host} for this account, and none in ${REGISTRY_PATH}`
+        : `no canvases in ${REGISTRY_PATH} yet`,
+    );
+    terminal.out("  pr-lens canvas push mints one");
+    return;
+  }
+
+  const rows = canvases.map((canvas) => [
+    canvas.id,
+    canvas.name,
+    String(canvas.rev),
+    canvas.editHere ? "yes" : "no",
+  ]);
+  const widths = HEADINGS.map((heading, column) =>
+    Math.max(heading.length, ...rows.map((cells) => cells[column]?.length ?? 0)),
+  );
+
+  terminal.out(row(HEADINGS, widths));
+  for (const cells of rows) terminal.out(row(cells, widths));
+  terminal.out("");
+  terminal.out(`  ${tally(canvases)}`);
+};
+
 export const canvasCommand = async (
   args: readonly string[],
   terminal: Terminal,
@@ -424,15 +638,21 @@ export const canvasCommand = async (
 ): Promise<void> => {
   const [name, ...rest] = args;
   if (name === undefined)
-    throw usageError("canvas needs a subcommand: push, pull, rotate or delete");
+    throw usageError(
+      "canvas needs a subcommand: list, push, pull, claim, rotate or delete",
+    );
   if (!isSubcommand(name))
     throw usageError(`unknown canvas subcommand ${JSON.stringify(name)}`);
 
   switch (name) {
+    case "list":
+      return list(rest, terminal, env);
     case "push":
       return push(rest, terminal, env);
     case "pull":
       return pull(rest, terminal, env);
+    case "claim":
+      return claimCommand(rest, terminal, env);
     case "delete":
       return deleteCommand(rest, terminal, env);
     case "rotate":

package/src/commands/render.ts

@@ -9,9 +9,12 @@ import { PrLensCliError, usageError } from "../errors.js";
 import { repositoryRoot } from "../git.js";
 import { writeJsonFile, writeTextFile } from "../io.js";
 import type { Terminal } from "../terminal.js";
+import { slugify } from "../slug.js";
 import { prepareWorkspace, WORKSPACE_DIR } from "../workspace.js";
 
-const DEFAULT_OUT = WORKSPACE_DIR;
+/** Same title, same directory, so a redraw updates its canvas instead of minting one. */
+const defaultOut = (title: string): string => join(WORKSPACE_DIR, slugify(title));
+
 const MANIFEST = "manifest.json";
 
 /**
@@ -31,7 +34,8 @@ Draws the document as self-contained SVGs — one per drill-down section per
 lens, in light and dark — and writes the manifest describing them. A document
 with no sections gets one diagram per lens it declares.
 
-  -o, --out <dir>      where the SVGs and the manifest go (default ${DEFAULT_OUT}/)
+  -o, --out <dir>      where the SVGs, the document and the manifest go
+                       (default ${WORKSPACE_DIR}/<title>/, one directory per drawing)
       --theme <theme>  light | dark | both (default both)
       --config <file>  corrections to draw with (default the repository's, if any)
       --no-config      ignore the repository's corrections`;
@@ -72,7 +76,7 @@ export const renderCommand = async (args: readonly string[], terminal: Terminal)
   });
 
   const graph = await readGraphDoc(expectOne(positionals, "one graph document to render"));
-  const out = readString(values.out, "out") ?? DEFAULT_OUT;
+  const out = readString(values.out, "out") ?? defaultOut(graph.title);
 
   const configPath = readString(values.config, "config");
   const configured = readBoolean(values["no-config"])

package/src/config-home.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-machine state: the install id and the sign-in credential. Either one
+ * can act as this machine, so each store gets its own file and neither can
+ * reach the wrong `--api`.
+ */
+import { join } from "node:path";
+
+const DIRECTORY = "pr-lens";
+
+/** Takes `env` from the caller so tests never write to the real home directory. */
+export const configHome = (
+  env: Record<string, string | undefined>,
+): string | undefined => {
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg) return xdg;
+
+  const home = env.HOME || env.USERPROFILE;
+  return home ? join(home, ".config") : undefined;
+};
+
+/**
+ * http and https only: other schemes have the origin "null", which would put
+ * unrelated stores in one file.
+ */
+const fileFor = (api: string): string | undefined => {
+  try {
+    const { protocol, origin } = new URL(api);
+    if (protocol !== "http:" && protocol !== "https:") return undefined;
+    return `${encodeURIComponent(origin)}.json`;
+  } catch {
+    return undefined;
+  }
+};
+
+export const originPath = (
+  env: Record<string, string | undefined>,
+  folder: string,
+  api: string,
+): string | undefined => {
+  const home = configHome(env);
+  const file = fileFor(api);
+  return home === undefined || file === undefined
+    ? undefined
+    : join(home, DIRECTORY, folder, file);
+};

package/src/errors.ts

@@ -17,11 +17,15 @@ export type CliErrorCode =
   | "RENDER_FAILED"
   | "CANVAS_UNREGISTERED"
   | "CANVAS_UNKNOWN"
+  | "CANVAS_OWNED"
   | "CANVAS_CONFLICT"
   | "CANVAS_REJECTED"
   | "CANVAS_RATE_LIMITED"
   | "CANVAS_UNAVAILABLE"
-  | "CANVAS_REGISTRY_EXPOSED";
+  | "CANVAS_REGISTRY_EXPOSED"
+  | "AUTH_REQUIRED"
+  | "MACHINE_REVOKED"
+  | "APP_UNAVAILABLE";
 
 export class PrLensCliError extends Error {
   readonly code: CliErrorCode;

package/src/install.ts

@@ -0,0 +1,107 @@
+/**
+ * Names this machine to a store so a later sign-in can claim what it pushed.
+ *
+ * Kept per store, since whoever holds the id can have this machine's canvases
+ * attributed to them. Never put in a link, unlike a write token.
+ */
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+
+import { originPath } from "./config-home.js";
+
+const INSTALLS = "installs";
+
+const PREFIX = "prl_i_";
+
+const INSTALL_ID = /^prl_i_[A-Za-z0-9_-]{22}$/;
+
+export const installPath = (
+  env: Record<string, string | undefined>,
+  api: string,
+): string | undefined => originPath(env, INSTALLS, api);
+
+const idIn = (text: string): string | undefined => {
+  const contents = ((): unknown => {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return undefined;
+    }
+  })();
+  if (typeof contents !== "object" || contents === null) return undefined;
+
+  const { installId } = contents as { installId?: unknown };
+  return typeof installId === "string" && INSTALL_ID.test(installId)
+    ? installId
+    : undefined;
+};
+
+/** Unreadable counts as absent: a machine with no id still pushes. */
+const storedId = (path: string): Promise<string | undefined> =>
+  readFile(path, "utf8").then(idIn, () => undefined);
+
+export const readStoredInstallId = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string | undefined> => {
+  const path = installPath(env, api);
+  return path === undefined ? undefined : storedId(path);
+};
+
+const write = async (path: string): Promise<string> => {
+  const minted = `${PREFIX}${randomBytes(16).toString("base64url")}`;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, `${JSON.stringify({ installId: minted }, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+    flag: "wx",
+  });
+  return minted;
+};
+
+const alreadyThere = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  "code" in error &&
+  error.code === "EEXIST";
+
+/**
+ * Exclusive create settles two first runs without a lock: the loser reads the
+ * winner's id. Repairing a junk file can race under concurrency; accepted as rare.
+ */
+const create = async (path: string): Promise<string | undefined> => {
+  try {
+    return await write(path);
+  } catch (error) {
+    if (!alreadyThere(error)) return undefined;
+
+    // One read, so a peer's repair cannot land between two.
+    const text = await readFile(path, "utf8").catch(() => undefined);
+
+    // An unreadable file may hold an id the app already has; never delete it.
+    if (text === undefined) return undefined;
+
+    const won = idIn(text);
+    if (won !== undefined) return won;
+
+    const cleared = await rm(path, { force: true }).then(
+      () => true,
+      () => false,
+    );
+    if (!cleared) return undefined;
+
+    return write(path).catch(() => storedId(path));
+  }
+};
+
+/** Failures answer undefined: attribution is never worth breaking a push. */
+export const readInstallId = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string | undefined> => {
+  const path = installPath(env, api);
+  if (path === undefined) return undefined;
+
+  return (await storedId(path)) ?? (await create(path));
+};