@coldtea/pr-lens-cli 0.1.2 → 0.2.0

package/src/commands/canvas.ts

@@ -0,0 +1,549 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { parseOptions, readString } from "../args.js";
+import {
+  fetchCanvas,
+  mintCanvas,
+  pushCanvas,
+  rotateCanvas,
+  verifyWriteToken,
+} from "../canvas/api.js";
+import {
+  ensureRegistryHome,
+  findBySource,
+  findCanvas,
+  isCanvasId,
+  mintWriteToken,
+  onlyCanvas,
+  isReservedRegistryTarget,
+  readRegistry,
+  REGISTRY_PATH,
+  sourceKey,
+  updateRegistry,
+  withRegistryLock,
+  writeRegistry,
+  type CanvasEntry,
+  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 type { Terminal } from "../terminal.js";
+import { WORKSPACE_DIR } from "../workspace.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;
+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]
+
+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
+${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})
+    --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)
+
+  pr-lens canvas pull [url|id]         fetch the document (default the checkout's only canvas)
+    --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 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})`;
+
+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(/\/+$/, "");
+};
+
+type CanvasRef = {
+  id: string;
+  origin: string | undefined;
+  writeToken: string | undefined;
+};
+
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{22}$/;
+
+/** Pulling an edit link is how a checkout that never pushed a canvas gets its token. */
+const readCanvasRef = (value: string): CanvasRef => {
+  if (isCanvasId(value))
+    return { id: value, origin: undefined, writeToken: undefined };
+
+  const url = (() => {
+    try {
+      return new URL(value);
+    } catch {
+      throw usageError(
+        `expected a canvas id or a canvas URL, got ${JSON.stringify(value)}`,
+      );
+    }
+  })();
+
+  const [, c, last, ...deeper] = url.pathname.split("/");
+  const id = last?.replace(/\.svg$/, "");
+  if (c !== "c" || id === undefined || deeper.length > 0 || !isCanvasId(id))
+    throw usageError(`${value} is not a canvas URL`, "expected {app}/c/{id}");
+
+  const fragment = new URLSearchParams(url.hash.replace(/^#/, ""));
+  const writeToken = fragment.get("w") ?? undefined;
+  if (writeToken !== undefined && !TOKEN_SHAPE.test(writeToken))
+    throw usageError(
+      `${value} carries something after #w= that is not a write token`,
+      "an edit link ends in #w= and 22 characters",
+    );
+  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 = {
+  api: string;
+  id: string;
+  /** Undefined for a canvas minted and never pushed to. */
+  fetched: { rev: number; title: string } | undefined;
+  out: string;
+  writeToken: string | undefined;
+  /** The stored token when the proof was made; if it changed since, the proof is stale. */
+  seenToken: string | undefined;
+  proven: boolean;
+};
+
+/**
+ * Decided under the lock. A token that changes hands drops a pending
+ * rotation, which was the old holder's business; the same token keeps it.
+ */
+const recordPull = (current: CanvasRegistry, pull: PullRecord): Recorded => {
+  const entry = current.canvases[pull.id];
+  if (entry !== undefined && entry.api !== pull.api) return "elsewhere";
+
+  const untouched = entry?.writeToken === pull.seenToken;
+  const imports =
+    pull.proven && untouched && pull.writeToken !== entry?.writeToken;
+
+  const kept = imports ? pull.writeToken : entry?.writeToken;
+  const pending = imports ? undefined : entry?.pending;
+
+  current.canvases[pull.id] = {
+    name: entry?.name ?? pull.fetched?.title ?? pull.id,
+    source:
+      entry?.source ??
+      (pull.fetched === undefined ? DEFAULT_SOURCE : sourceKey(pull.out)),
+    api: pull.api,
+    ...(pending === undefined ? {} : { pending }),
+    ...(kept === undefined ? {} : { writeToken: kept }),
+    rev: pull.fetched?.rev ?? entry?.rev ?? 0,
+  };
+
+  return imports
+    ? "imported"
+    : pull.proven && !untouched
+      ? "overtaken"
+      : pull.writeToken !== undefined && !pull.proven
+        ? "refused"
+        : "kept";
+};
+
+const tellRecorded = (
+  recorded: Recorded,
+  id: string,
+  terminal: Terminal,
+): void => {
+  switch (recorded) {
+    case "imported":
+      terminal.out(`  the edit link's token is now in ${REGISTRY_PATH}`);
+      return;
+    case "refused":
+      terminal.err(
+        `  the edit link's token no longer opens ${id}; nothing was recorded for it`,
+      );
+      return;
+    case "overtaken":
+      terminal.err(
+        `  ${REGISTRY_PATH} changed while the edit link was being checked; its token was not recorded`,
+      );
+      return;
+    case "elsewhere":
+      terminal.err(
+        `  ${id} is registered against another app in ${REGISTRY_PATH}; that entry was left as it is`,
+      );
+      return;
+    case "kept":
+      return;
+    default:
+      return assertNever(recorded, "Unhandled record outcome");
+  }
+};
+
+const push = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    canvas: { type: "string" },
+    name: { type: "string" },
+    api: { type: "string" },
+  });
+  if (positionals.length > 1)
+    throw usageError(
+      `push takes one graph document, got ${positionals.length}`,
+    );
+
+  const source = positionals[0] ?? DEFAULT_SOURCE;
+  const document = await readGraphDoc(source);
+  const api = readApi(values.api, env);
+  await ensureRegistryHome(terminal);
+  const registry = await readRegistry();
+
+  const ref = readString(values.canvas, "canvas");
+  const known =
+    ref === undefined
+      ? findBySource(registry, source)
+      : findCanvas(registry, ref);
+
+  const registered: Registered =
+    known ??
+    // Under the lock, so a racing push of the same file finds this entry
+    // instead of minting its own.
+    (await withRegistryLock(async () => {
+      const current = await readRegistry();
+      const meanwhile =
+        ref === undefined ? findBySource(current, source) : undefined;
+      if (meanwhile !== undefined) return meanwhile;
+
+      const minted = await mintCanvas(api);
+      const entry: CanvasEntry = {
+        name: readString(values.name, "name") ?? document.title,
+        source: sourceKey(source),
+        api,
+        writeToken: minted.writeToken,
+        rev: minted.rev,
+      };
+      current.canvases[minted.id] = entry;
+
+      try {
+        await writeRegistry(current, terminal);
+      } catch (error) {
+        // The app hands the token out once; the terminal is the only place left for it.
+        if (!(error instanceof PrLensCliError)) throw error;
+        throw new PrLensCliError(
+          error.code,
+          `${error.message}; the canvas was minted and its token is not saved`,
+          [
+            `keep this edit link, it is the only copy: ${minted.editUrl}`,
+            "pull it once the registry can be written, and the token is recorded",
+            error.details ?? "",
+          ]
+            .filter((line) => line !== "")
+            .join("\n"),
+        );
+      }
+      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 pushed = await pushCanvas(
+    api,
+    target.id,
+    requireWriteToken(target),
+    target.entry.rev,
+    document,
+  );
+
+  await updateRegistry((current) => {
+    current.canvases[target.id] = {
+      ...(current.canvases[target.id] ?? target.entry),
+      source: sourceKey(source),
+      rev: pushed.rev,
+    };
+  }, terminal);
+
+  terminal.out(
+    `✓ ${pushed.viewUrl} — rev ${pushed.rev} · ${countDiagrams(pushed.tiles.length)}`,
+  );
+  terminal.out(`  edit link, keep it to yourself: ${pushed.editUrl}`);
+  terminal.out(`  README embed: ${pushed.embedUrl}`);
+};
+
+const pull = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    canvas: { type: "string" },
+    out: { type: "string", short: "o" },
+    api: { type: "string" },
+  });
+  if (positionals.length > 1)
+    throw usageError(
+      `pull takes one canvas url or id, got ${positionals.length}`,
+    );
+
+  const registry = await readRegistry();
+  const ref = readString(values.canvas, "canvas");
+  const [positional] = positionals;
+
+  const { id, origin, writeToken } =
+    positional !== undefined
+      ? readCanvasRef(positional)
+      : {
+          ...(ref === undefined
+            ? onlyCanvas(registry)
+            : findCanvas(registry, ref)),
+          origin: undefined,
+          writeToken: undefined,
+        };
+
+  // A pasted link says where it lives; --api still wins.
+  const explicit = readString(values.api, "api");
+  const api =
+    explicit === undefined && origin !== undefined
+      ? origin
+      : readApi(explicit, env);
+  const out = readString(values.out, "out") ?? DEFAULT_OUT;
+  if (await isReservedRegistryTarget(out))
+    throw usageError(
+      `${out} is where the write tokens live; a document cannot be written there`,
+    );
+
+  // Proven before the fetch: an old bookmark must not replace the token
+  // that works, and an unpushed canvas has nothing to fetch yet.
+  const seenToken = registry.canvases[id]?.writeToken;
+  const proven =
+    writeToken !== undefined && (await verifyWriteToken(api, id, writeToken));
+
+  const fetched = await fetchCanvas(api, id).catch((error: unknown) => {
+    // Minted and never pushed: nothing to show, but a proven token is worth recording.
+    if (
+      error instanceof PrLensCliError &&
+      error.code === "CANVAS_UNKNOWN" &&
+      proven
+    )
+      return undefined;
+    throw error;
+  });
+  if (fetched !== undefined) await writeJsonFile(out, fetched.document);
+
+  const outcome: { recorded: Recorded } = { recorded: "kept" };
+  await updateRegistry((current) => {
+    outcome.recorded = recordPull(current, {
+      api,
+      id,
+      fetched:
+        fetched === undefined
+          ? undefined
+          : { rev: fetched.rev, title: fetched.document.title },
+      out,
+      writeToken,
+      seenToken,
+      proven,
+    });
+  }, terminal);
+
+  terminal.out(
+    fetched === undefined
+      ? `✓ ${id} has nothing pushed to it yet`
+      : `✓ ${out} — rev ${fetched.rev} of ${fetched.viewUrl}`,
+  );
+  tellRecorded(outcome.recorded, id, terminal);
+};
+
+const rotate = 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(
+      `rotate takes no positional arguments, got ${positionals.join(" ")}`,
+    );
+
+  const api = readApi(values.api, env);
+  await ensureRegistryHome(terminal);
+  const registry = await readRegistry();
+  const ref = readString(values.canvas, "canvas");
+  const { id } =
+    ref === undefined ? onlyCanvas(registry) : findCanvas(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.
+  let pending: Registered | undefined;
+  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() },
+    };
+    current.canvases[id] = pending.entry;
+  }, terminal);
+  if (pending === undefined || pending.entry.pending === undefined)
+    throw new PrLensCliError(
+      "CANVAS_UNREGISTERED",
+      `${id} is no longer in ${REGISTRY_PATH}`,
+    );
+
+  const { editUrl } = await settleRotation(
+    api,
+    pending,
+    pending.entry.pending,
+    terminal,
+  );
+
+  const view = new URL(editUrl);
+  view.hash = "";
+  terminal.out(`✓ new edit link for ${view.href}: ${editUrl}`);
+  terminal.out("  the old edit link no longer works");
+};
+
+export const canvasCommand = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const [name, ...rest] = args;
+  if (name === undefined)
+    throw usageError("canvas needs a subcommand: push, pull or rotate");
+  if (!isSubcommand(name))
+    throw usageError(`unknown canvas subcommand ${JSON.stringify(name)}`);
+
+  switch (name) {
+    case "push":
+      return push(rest, terminal, env);
+    case "pull":
+      return pull(rest, terminal, env);
+    case "rotate":
+      return rotate(rest, terminal, env);
+    default:
+      return assertNever(name, "Unhandled canvas subcommand");
+  }
+};

package/src/errors.ts

@@ -14,7 +14,14 @@ export type CliErrorCode =
   | "MISSING_API_KEY"
   | "PROVIDER_FAILED"
   | "MODEL_OUTPUT_INVALID"
-  | "RENDER_FAILED";
+  | "RENDER_FAILED"
+  | "CANVAS_UNREGISTERED"
+  | "CANVAS_UNKNOWN"
+  | "CANVAS_CONFLICT"
+  | "CANVAS_REJECTED"
+  | "CANVAS_RATE_LIMITED"
+  | "CANVAS_UNAVAILABLE"
+  | "CANVAS_REGISTRY_EXPOSED";
 
 export class PrLensCliError extends Error {
   readonly code: CliErrorCode;

package/src/io.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PrLensCliError } from "./errors.js";
 
@@ -36,3 +36,25 @@ export const writeTextFile = async (path: string, contents: string): Promise<str
 /** One trailing newline, so written documents behave in a diff and in a shell. */
 export const writeJsonFile = (path: string, value: unknown): Promise<string> =>
   writeTextFile(path, `${JSON.stringify(value, null, 2)}\n`);
+
+/**
+ * A file that holds a secret and nothing else can rebuild: readable by its
+ * owner alone, and replaced in one step so an interrupted write leaves the
+ * old copy rather than half of a new one.
+ */
+export const secretStagingPath = (path: string): string => `${resolve(path)}.${process.pid}.tmp`;
+
+export const writeSecretJsonFile = async (path: string, value: unknown): Promise<string> => {
+  const absolute = resolve(path);
+  const staging = secretStagingPath(path);
+  try {
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(staging, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(staging, absolute);
+  } catch (error) {
+    // Never leave a secret lying about under a temporary name.
+    await unlink(staging).catch(() => undefined);
+    throw new PrLensCliError("UNREADABLE_FILE", `cannot write ${path}`, describe(error));
+  }
+  return absolute;
+};

package/src/prompt.ts

@@ -31,7 +31,11 @@ export const SYSTEM_PROMPT = [
   "- Give the document a title a reviewer would recognise, and a summary that answers 'what does this change do?' in a short paragraph.",
   "- Attach file refs to nodes, edges and steps wherever the diff shows where they live: they become the permalinks a reader clicks.",
   "- Add a data flow only when the change actually has an ordered sequence worth animating. One good flow beats three thin ones.",
-  "- Build the drill-down tree: a view over the whole document, and a focused view for each part of the change that deserves its own section. Views are what a reader expands in the comment, so a document without them renders as one picture and nothing else.",
+  "- Choose architecture views as a C4-inspired decision tree, not a quota. A small change may need only one useful view.",
+  "- Start at the highest useful level: use system context when the change affects a user, an external system or a system boundary; otherwise start with containers. Container views cover affected applications, services, jobs, data stores and runtimes. Add a component child only when an affected container's internals matter. Do not add code-level views by default.",
+  "- Each architecture child moves down one level and materially narrows the scope. Skip empty, repetitive or speculative levels, and never create views with substantially the same nodes and edges. Infer boundaries from behavior and dependencies, not folder names alone.",
+  "- Keep data-flow views as separate roots, outside the architecture hierarchy. Set the highest useful architecture view `defaultOpen: true`; lower architecture views should normally stay collapsed.",
+  "- Views are expandable comment sections. Without views, each requested lens renders once.",
   "- Stat chips carry the numbers that make the change legible, e.g. label 'Postmark calls' value '500x fewer'. Leave out files changed and line counts — those are filled in for you.",
   "",
   "Answer with the JSON document alone. No prose, no markdown fence.",

package/src/version.ts

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

package/src/workspace.ts

@@ -160,13 +160,18 @@ const README = `# .pr-lens
 PR Lens writes its previews here: the diagrams as light and dark SVGs, the
 document they were drawn from, and the manifest describing them.
 
-None of it belongs in a commit. Every file is rebuilt from the diff by
+None of that belongs in a commit. Those files are rebuilt from the diff by
 \`pr-lens analyze\` and \`pr-lens render\`, so a stale copy in the history is
 worth less than nothing — it is a diagram of a pull request somebody already
 merged. What readers are meant to see is the comment on the pull request, or
-the share page it links to.
-
-Delete the directory whenever you like. Nothing reads it back.
+the share page it links to. Delete them whenever you like; nothing reads them
+back.
+
+\`canvas.json\` is the exception. It holds the write token for every canvas
+this checkout has pushed with \`pr-lens canvas push\`, and nothing can rebuild
+it. Without it the canvases stay readable by everyone, but pushing to them
+again needs the edit link you were given. Keep it out of commits and out of
+other people's hands.
 `;
 
 /**