@coldtea/pr-lens-cli 0.7.0 → 0.8.1

package/src/canvas/api.ts

@@ -85,6 +85,8 @@ const Refusal = z.discriminatedUnion("code", [
     retryAt: z.string(),
   }),
   z.object({ code: z.literal("TOO_LARGE"), message: z.string() }),
+  z.object({ code: z.literal("UNAUTHENTICATED"), message: z.string() }),
+  z.object({ code: z.literal("ALREADY_OWNED"), message: z.string() }),
 ]);
 
 type Request = {
@@ -93,6 +95,8 @@ type Request = {
   /** Undefined when minting, so a 404 there is not blamed on a canvas. */
   canvas: string | undefined;
   token?: string;
+  /** Lets a later sign-in claim what this machine pushed. */
+  install?: string;
   ifMatch?: number;
   body?: unknown;
 };
@@ -112,6 +116,25 @@ const unavailable = (
     details,
   );
 
+/** Untrusted server content, so printable and short. */
+const LOCATION_SHOWN = 200;
+
+/** Printing the target turns an `http://` for `https://` typo into a fix. */
+const redirected = (api: string, response: Response): PrLensCliError => {
+  const location = response.headers
+    .get("location")
+    ?.replace(/[^\x20-\x7e]/g, "")
+    .slice(0, LOCATION_SHOWN);
+
+  return unavailable(
+    api,
+    response.status,
+    location === undefined || location === ""
+      ? "the canvas API answers at the address it is given, and this one redirects"
+      : `the canvas API answers at the address it is given; this one points at ${location}, so pass that as --api`,
+  );
+};
+
 const parseJson = (text: string): unknown => {
   try {
     return JSON.parse(text);
@@ -170,6 +193,21 @@ const refusal = (
         `${hostOf(api)} is rate limiting this client until ${error.retryAt}`,
         error.message,
       );
+    case "UNAUTHENTICATED":
+      return new PrLensCliError(
+        "AUTH_REQUIRED",
+        `${hostOf(api)} did not accept this sign-in`,
+        [error.message, "pr-lens auth login signs this machine in again"].join(
+          "\n",
+        ),
+      );
+    case "ALREADY_OWNED":
+      // The caller holds the write token, so naming the case leaks nothing.
+      return new PrLensCliError(
+        "CANVAS_OWNED",
+        `${request.canvas ?? "that canvas"} belongs to another account on ${hostOf(api)}`,
+        "the first claim wins, and somebody else's landed first",
+      );
     case "INVALID_REQUEST":
     case "TOO_LARGE":
       return unavailable(api, status, error.message);
@@ -191,6 +229,9 @@ const call = async <T>(
   if (request.token !== undefined)
     headers.authorization = `Bearer ${request.token}`;
 
+  if (request.install !== undefined)
+    headers["x-pr-lens-install"] = request.install;
+
   if (request.ifMatch !== undefined)
     headers["if-match"] = String(request.ifMatch);
 
@@ -200,6 +241,9 @@ const call = async <T>(
     method: request.method,
     headers,
     body: request.body === undefined ? undefined : JSON.stringify(request.body),
+    // A cross-origin redirect keeps every header but `authorization`, which
+    // would leak the install id to another host.
+    redirect: "manual",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   }).catch(() => {
     // The runtime's message names addresses and internals; keep it out.
@@ -210,6 +254,10 @@ const call = async <T>(
     );
   });
 
+  // A 3xx body is not an error envelope.
+  if (response.status >= 300 && response.status < 400)
+    throw redirected(api, response);
+
   // A body can fail after the headers arrived.
   const text = await response.text().catch(() => {
     throw unavailable(
@@ -234,8 +282,17 @@ const call = async <T>(
 
 const canvasPath = (id: string): string => `/api/canvas/${id}`;
 
-export const mintCanvas = (api: string): Promise<Minted> =>
-  call(api, { method: "POST", path: "/api/canvas", canvas: undefined }, Minted);
+/** The bearer is how CI attributes a mint: a runner's install id is never linked. */
+export const mintCanvas = (
+  api: string,
+  install: string | undefined,
+  token: string | undefined,
+): Promise<Minted> =>
+  call(
+    api,
+    { method: "POST", path: "/api/canvas", canvas: undefined, install, token },
+    Minted,
+  );
 
 export const fetchCanvas = async (
   api: string,
@@ -322,3 +379,58 @@ export const deleteCanvas = (
     { method: "DELETE", path: canvasPath(id), canvas: id, token },
     z.object({ id: z.literal(id), deleted: z.literal(true) }),
   );
+
+/** An unreadable revision must not read as an empty canvas. */
+const Preview = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("drawn"), title: z.string().min(1) }),
+  z.object({ type: z.literal("not_drawn") }),
+  z.object({ type: z.literal("unreadable") }),
+]);
+
+const Owned = z.object({
+  id: z.string(),
+  rev: z.number().int(),
+  preview: Preview,
+});
+
+const Owning = z.object({ canvases: z.array(Owned) });
+
+export type CanvasPreview = z.infer<typeof Preview>;
+export type OwnedCanvas = z.infer<typeof Owned>;
+
+/**
+ * Carries no write tokens: the app keeps only their hashes. A store without
+ * accounts 404s here, which reads as unavailable, not as a missing canvas.
+ */
+export const listOwnedCanvases = (
+  api: string,
+  token: string,
+): Promise<OwnedCanvas[]> =>
+  call(
+    api,
+    { method: "GET", path: "/api/canvases", canvas: undefined, token },
+    Owning,
+  ).then(({ canvases }) => canvases);
+
+/**
+ * The account token takes the header, so the write tokens go in the body.
+ * The caller mints the next token so a lost answer can be replayed.
+ */
+export const claimCanvas = (
+  api: string,
+  id: string,
+  accountToken: string,
+  writeToken: string,
+  nextWriteToken: string,
+): Promise<Rotated> =>
+  call(
+    api,
+    {
+      method: "POST",
+      path: `${canvasPath(id)}/claim`,
+      canvas: id,
+      token: accountToken,
+      body: { writeToken, nextWriteToken },
+    },
+    Rotated,
+  );

package/src/canvas/claim.ts

@@ -0,0 +1,127 @@
+/**
+ * The write token is the only proof, and it rides in every edit link ever
+ * shared, so claiming retires it in the same step.
+ */
+import { requireToken } from "../auth.js";
+import type { Terminal } from "../terminal.js";
+import { claimCanvas, listOwnedCanvases } from "./api.js";
+import { expectOne, parseOptions } from "../args.js";
+import { PrLensCliError } from "../errors.js";
+import { readApi, requireWriteToken, settlePendingRotation } from "./write.js";
+import {
+  findCanvas,
+  mintWriteToken,
+  readRegistry,
+  REGISTRY_PATH,
+  updateRegistry,
+} from "./registry.js";
+
+const unfinishedClaim = (error: PrLensCliError): PrLensCliError =>
+  new PrLensCliError(
+    error.code,
+    `${error.message}; the claim may have landed`,
+    [
+      error.details,
+      "run pr-lens canvas claim again: the token it minted is kept, and a second run finishes the claim",
+    ]
+      .filter((line) => line !== undefined && line !== "")
+      .join("\n"),
+  );
+
+export const claimCommand = async (
+  args: readonly string[],
+  terminal: Terminal,
+  env: Record<string, string | undefined>,
+): Promise<void> => {
+  const { values, positionals } = parseOptions(args, {
+    api: { type: "string" },
+  });
+  const ref = expectOne(positionals, "the id or name of a canvas to claim");
+
+  const api = readApi(values.api, env);
+  const registry = await readRegistry();
+  const selected = findCanvas(registry, ref);
+
+  // Checked first, so a signed-out machine never costs a rotation.
+  const account = await requireToken(env, api);
+
+  // Also finishes a claim whose answer was lost: its token is still pending.
+  const settled = await settlePendingRotation(api, selected, terminal, env);
+  const id = settled.id;
+
+  // Unlike push and delete, ownership cannot stand in: claiming is how a
+  // canvas gets an owner.
+  requireWriteToken(settled);
+
+  // The app treats an owner's claim as a replay and rotates, so running the
+  // command twice would retire a token for nothing.
+  const mine = await listOwnedCanvases(api, account);
+  if (mine.some((canvas) => canvas.id === id))
+    throw new PrLensCliError(
+      "CANVAS_OWNED",
+      `${id} is already yours on ${new URL(api).host}`,
+      "claiming it again would retire its write token for nothing",
+    );
+
+  terminal.err("! Claiming rotates this canvas's write token.");
+  terminal.err("  Edit links you have already shared will stop working.");
+
+  // Saved first, so a lost answer does not lose the token.
+  const nextToken = mintWriteToken();
+  let saved = false;
+  await updateRegistry((current) => {
+    const entry = current.canvases[id];
+    if (entry === undefined || entry.api !== api) return;
+    current.canvases[id] = { ...entry, pending: nextToken };
+    saved = true;
+  }, terminal);
+  if (!saved)
+    throw new PrLensCliError(
+      "CANVAS_UNREGISTERED",
+      `${id} is no longer in ${REGISTRY_PATH}`,
+    );
+
+  const claimed = await claimCanvas(
+    api,
+    id,
+    account,
+    requireWriteToken(settled),
+    nextToken,
+  ).catch(async (error: unknown) => {
+    if (!(error instanceof PrLensCliError)) throw error;
+    // Only these two mean the app did not rotate. Anything else may have
+    // landed, so the pending token stays for the next run to finish.
+    if (error.code !== "CANVAS_UNKNOWN" && error.code !== "CANVAS_OWNED")
+      throw unfinishedClaim(error);
+
+    await updateRegistry((current) => {
+      const entry = current.canvases[id];
+      if (entry === undefined || entry.pending !== nextToken || entry.api !== api)
+        return;
+      current.canvases[id] = { ...entry, pending: undefined };
+    }, terminal);
+    throw error;
+  });
+
+  // A different token pending by now belongs to a later rotation.
+  await updateRegistry((current) => {
+    const entry = current.canvases[id];
+    if (entry === undefined || entry.pending !== nextToken || entry.api !== api)
+      return;
+    current.canvases[id] = {
+      ...entry,
+      writeToken: nextToken,
+      pending: undefined,
+    };
+  }, terminal);
+
+  const view = new URL(claimed.editUrl);
+  view.hash = "";
+  terminal.out(`✓ ${view.href} is yours`);
+  terminal.out(
+    `  Its new write token is in ${REGISTRY_PATH}, so this checkout can push to it.`,
+  );
+  terminal.out(
+    "  Edit links you shared before this still open the page, and no longer edit it.",
+  );
+};

package/src/canvas/delete.ts

@@ -3,7 +3,7 @@ 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";
+import { readApi, settlePendingRotation, writeCredential } from "./write.js";
 
 export const deleteCommand = async (
   args: readonly string[],
@@ -26,8 +26,8 @@ export const deleteCommand = async (
   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));
+  const target = await settlePendingRotation(api, selected, terminal, env);
+  await deleteCanvas(api, target.id, await writeCredential(target, env, api));
 
   await updateRegistry((current) => {
     if (current.canvases[target.id]?.api === api)

package/src/canvas/registry.ts

@@ -36,7 +36,8 @@ export const mintWriteToken = (): string =>
 
 const Entry = z.object({
   name: z.string(),
-  source: z.string(),
+  /** Absent for a canvas recorded from an edit link: no local file wrote it. */
+  source: z.string().optional(),
   /** Another app's 404 says nothing about this entry. */
   api: z.string(),
   /** Absent for a canvas pulled by its view link. */
@@ -446,7 +447,7 @@ export const findBySource = (
 ): Registered | undefined => {
   const key = sourceKey(path);
   const matching = entries(registry).filter(
-    ({ entry }) => sourceKey(entry.source) === key,
+    ({ entry }) => entry.source !== undefined && sourceKey(entry.source) === key,
   );
   const [only, ...more] = matching;
   if (more.length > 0)
@@ -458,6 +459,27 @@ export const findBySource = (
   return only;
 };
 
+/**
+ * Fallback after the path: a pull and the render after it write two files,
+ * and only one can be the recorded path. A path match wins, since a title
+ * can be edited.
+ */
+export const findByTitle = (
+  registry: CanvasRegistry,
+  title: string,
+): Registered | undefined => {
+  const matching = entries(registry).filter(({ entry }) => entry.name === title);
+  const [only, ...more] = matching;
+
+  if (more.length > 0)
+    throw usageError(
+      `${matching.length} canvases are named ${JSON.stringify(title)}`,
+      `pass --canvas <id>: ${matching.map(describe).join(", ")}`,
+    );
+
+  return only;
+};
+
 export const onlyCanvas = (registry: CanvasRegistry): Registered => {
   const all = entries(registry);
   const [only, ...more] = all;

package/src/canvas/write.ts

@@ -1,4 +1,5 @@
 import { readString } from "../args.js";
+import { readToken } from "../auth.js";
 import { rotateCanvas } from "./api.js";
 import type { Terminal } from "../terminal.js";
 import { PrLensCliError, usageError } from "../errors.js";
@@ -7,11 +8,15 @@ import { updateRegistry, type Registered } from "./registry.js";
 export const DEFAULT_API = "https://prlens.dev";
 export const API_ENV = "PR_LENS_API_URL";
 
+/**
+ * `||` for the environment: a workflow cannot omit an `env` key, so it sets
+ * it to "". The flag keeps `??`, so a typed `--api ""` is reported.
+ */
 export const readApi = (
   value: unknown,
   env: Record<string, string | undefined>,
 ): string => {
-  const api = readString(value, "api") ?? env[API_ENV] ?? DEFAULT_API;
+  const api = readString(value, "api") ?? (env[API_ENV] || DEFAULT_API);
   try {
     new URL(api);
   } catch {
@@ -42,6 +47,30 @@ export const requireWriteToken = ({ id, entry }: Registered): string => {
   );
 };
 
+/**
+ * The write token first: it works signed out and on stores without accounts.
+ * The account token only works if the app finds the account owns the canvas.
+ */
+export const writeCredential = async (
+  registered: Registered,
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string> => {
+  if (registered.entry.writeToken !== undefined) return registered.entry.writeToken;
+
+  const account = await readToken(env, api);
+  if (account !== undefined) return account;
+
+  throw new PrLensCliError(
+    "CANVAS_UNREGISTERED",
+    `this checkout can read ${registered.id} but holds no write token for it`,
+    [
+      "pr-lens auth login signs this machine in, and an owner needs no token",
+      "or pull its edit link, the one with #w= at the end, and the token comes with it",
+    ].join("\n"),
+  );
+};
+
 const unfinishedRotation = (error: PrLensCliError): PrLensCliError =>
   new PrLensCliError(
     error.code,
@@ -60,11 +89,12 @@ export const settleRotation = async (
   { id, entry }: Registered,
   nextToken: string,
   terminal: Terminal,
+  env: Record<string, string | undefined>,
 ): Promise<{ registered: Registered; editUrl: string }> => {
   const rotated = await rotateCanvas(
     api,
     id,
-    requireWriteToken({ id, entry }),
+    await writeCredential({ id, entry }, env, api),
     nextToken,
   ).catch(async (error: unknown) => {
     if (!(error instanceof PrLensCliError)) throw error;
@@ -118,11 +148,12 @@ export const settlePendingRotation = async (
   api: string,
   registered: Registered,
   terminal: Terminal,
+  env: Record<string, string | undefined>,
 ): Promise<Registered> => {
   requireSameApi(api, registered);
-  requireWriteToken(registered);
+
   const pending = registered.entry.pending;
-  return pending === undefined
-    ? registered
-    : (await settleRotation(api, registered, pending, terminal)).registered;
+  if (pending === undefined) return registered;
+
+  return (await settleRotation(api, registered, pending, terminal, env)).registered;
 };

package/src/cli.ts

@@ -3,6 +3,7 @@ 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";
+import { authCommand, USAGE as AUTH_USAGE } from "./commands/auth.js";
 import { skillCommand, USAGE as SKILL_USAGE } from "./commands/skill.js";
 import { exportCommand, USAGE as EXPORT_USAGE } from "./commands/export.js";
 import { canvasCommand, USAGE as CANVAS_USAGE } from "./commands/canvas.js";
@@ -11,7 +12,7 @@ import { analyzeCommand, USAGE as ANALYZE_USAGE } from "./commands/analyze.js";
 import { commentCommand, USAGE as COMMENT_USAGE } from "./commands/comment.js";
 import { USAGE as VALIDATE_USAGE, validateCommand } from "./commands/validate.js";
 
-const COMMANDS = ["analyze", "render", "comment", "validate", "export", "canvas", "skill"] as const;
+const COMMANDS = ["analyze", "render", "comment", "validate", "export", "canvas", "auth", "skill"] as const;
 type CommandName = (typeof COMMANDS)[number];
 
 const isCommand = (value: string): value is CommandName =>
@@ -24,7 +25,8 @@ 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 | delete    that document, kept on prlens.dev as a page and an embed
+  pr-lens canvas    list | push | pull | claim | rotate | delete   that document, kept on prlens.dev as a page and an embed
+  pr-lens auth      login | status | logout   sign this machine in, so the canvases it pushes are yours
   pr-lens skill                             diagram instructions for coding agents
 
   pr-lens <command> --help                  what a command takes
@@ -47,6 +49,8 @@ const usageFor = (command: CommandName): string => {
       return EXPORT_USAGE;
     case "canvas":
       return CANVAS_USAGE;
+    case "auth":
+      return AUTH_USAGE;
     case "skill":
       return SKILL_USAGE;
     default:
@@ -73,6 +77,8 @@ const dispatch = (
       return exportCommand(args, terminal);
     case "canvas":
       return canvasCommand(args, terminal, env);
+    case "auth":
+      return authCommand(args, terminal, env);
     case "skill":
       return skillCommand(args, terminal);
     default: