@coldtea/pr-lens-cli 0.6.1 → 0.8.0

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: