@coldtea/pr-lens-cli 0.7.0 → 0.8.1

package/dist/workspace.js

@@ -1,5 +1,6 @@
 import { assertNever } from "@coldtea/pr-lens-schema";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
+import { readdir, stat } from "node:fs/promises";
 import { git } from "./git.js";
 import { readTextFile, writeTextFile } from "./io.js";
 /**
@@ -150,14 +151,35 @@ other people's hands.
  * user's, and so is the question of what to do with it.
  */
 export const prepareWorkspace = async (out, terminal) => {
+    // A first render into `.pr-lens/<title>` must still gitignore the workspace.
     const directory = resolve(out);
-    if (directory !== resolve(WORKSPACE_DIR))
+    const workspace = resolve(WORKSPACE_DIR);
+    const inside = directory === workspace || directory.startsWith(`${workspace}${sep}`);
+    if (!inside)
         return;
     // The README first, which is what puts the directory on disk: git is asked
     // whether a directory is ignored, and one that is not there cannot be.
-    await writeTextFile(join(directory, README_NAME), README);
-    const ignored = await ignoreWorkspace(directory);
+    await writeTextFile(join(workspace, README_NAME), README);
+    const ignored = await ignoreWorkspace(workspace);
     if (ignored !== undefined)
         terminal.err(`✓ ${ignored} — ${WORKSPACE_DIR}/ is ignored`);
 };
+/** What `render` writes beside the manifest, in every drawing's directory. */
+export const DRAWN_NAME = "drawn.graph.json";
+/** The top-level `drawn.graph.json` from 0.7.0 counts only until a newer render exists. */
+export async function drawings() {
+    const found = [];
+    // No `isDirectory()` check: it is false for a symlinked drawing.
+    const entries = await readdir(WORKSPACE_DIR).catch(() => []);
+    for (const entry of entries) {
+        const drawn = join(WORKSPACE_DIR, entry, DRAWN_NAME);
+        if (await readable(drawn))
+            found.push(drawn);
+    }
+    if (found.length > 0)
+        return found;
+    const legacy = join(WORKSPACE_DIR, DRAWN_NAME);
+    return (await readable(legacy)) ? [legacy] : [];
+}
+const readable = (path) => stat(path).then((found) => found.isFile()).catch(() => false);
 //# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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-schema": "^0.4.0",
-    "@coldtea/pr-lens-renderer": "^0.2.6"
+    "@coldtea/pr-lens-renderer": "^0.2.6",
+    "@coldtea/pr-lens-schema": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/src/account.ts

@@ -0,0 +1,302 @@
+/**
+ * Sign-in is the OAuth 2.0 device grant (RFC 8628), the one flow that works
+ * over SSH and in containers. Its wire codes are the RFC's, not this CLI's.
+ */
+import { z } from "zod";
+import { createHash } from "node:crypto";
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+import { CLI_VERSION } from "./version.js";
+import { PrLensCliError } from "./errors.js";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+
+const hostOf = (api: string): string => new URL(api).host;
+
+const unavailable = (
+  api: string,
+  details: string,
+  status?: number,
+): PrLensCliError =>
+  new PrLensCliError(
+    "APP_UNAVAILABLE",
+    status === undefined
+      ? `${hostOf(api)} did not answer`
+      : `${hostOf(api)} answered ${status}`,
+    details,
+  );
+
+type Answer = { status: number; body: unknown };
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const send = async (
+  api: string,
+  path: string,
+  init: { method: "GET" | "POST" | "DELETE"; token?: string; body?: unknown },
+): Promise<Answer> => {
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    "user-agent": `pr-lens-cli/${CLI_VERSION}`,
+  };
+  if (init.token !== undefined) headers.authorization = `Bearer ${init.token}`;
+  if (init.body !== undefined) headers["content-type"] = "application/json";
+
+  const response = await fetch(`${api}${path}`, {
+    method: init.method,
+    headers,
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    // A redirect would carry the token to whatever host answered.
+    redirect: "manual",
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  }).catch(() => {
+    // The runtime's message leaks addresses and internals.
+    throw unavailable(api, "check the address and the connection, then try again");
+  });
+
+  if (response.status >= 300 && response.status < 400)
+    throw unavailable(api, "this address redirects, and the sign-in routes must answer directly", response.status);
+
+  const text = await response.text().catch(() => {
+    throw unavailable(api, "the answer was cut off; check the connection, then try again", response.status);
+  });
+
+  return { status: response.status, body: parseJson(text) };
+};
+
+/** Refusals outside the device flow use the app's own envelope. */
+const Refusal = z.object({
+  error: z.looseObject({ code: z.string(), message: z.string() }),
+});
+
+const Started = z.object({
+  device_code: z.string().min(1),
+  user_code: z.string().min(1),
+  verification_uri: z.string().min(1),
+  verification_uri_complete: z.string().min(1).optional(),
+  expires_in: z.number().int().positive(),
+  interval: z.number().int().nonnegative().optional(),
+});
+
+export type StartedSignIn = {
+  deviceCode: string;
+  userCode: string;
+  /** Carries the code, so nobody types it. */
+  approveUrl: string;
+  expiresInSeconds: number;
+  intervalSeconds: number;
+};
+
+/** RFC 8628 §3.2: the floor, and the default when none is served. */
+export const DEFAULT_INTERVAL_SECONDS = 5;
+
+/** The install id goes with the request: the approving browser may be on a phone and cannot know which machine asked. */
+export const startSignIn = async (
+  api: string,
+  installId: string,
+  client: string,
+  name: string,
+): Promise<StartedSignIn> => {
+  const answer = await send(api, "/api/device/code", {
+    method: "POST",
+    body: { install_id: installId, client, name },
+  });
+
+  if (answer.status !== 200) {
+    const refused = Refusal.safeParse(answer.body);
+    const code = refused.success ? refused.data.error.code : undefined;
+    // Twenty codes an hour per address. Usually a retry after a typo, so say what to do next.
+    throw code === "RATE_LIMITED"
+      ? new PrLensCliError(
+          "APP_UNAVAILABLE",
+          `${hostOf(api)} has handed this machine enough sign-in codes for now`,
+          "it goes by the hour, so a short wait clears it; the sign-in you already have is unaffected",
+        )
+      : unavailable(
+          api,
+          refused.success ? refused.data.error.message : "the answer was not in the shape the sign-in expects",
+          answer.status,
+        );
+  }
+
+  const started = Started.safeParse(answer.body);
+  if (!started.success)
+    throw unavailable(api, "the answer was not in the shape the sign-in expects", answer.status);
+
+  return {
+    deviceCode: started.data.device_code,
+    userCode: started.data.user_code,
+    approveUrl: started.data.verification_uri_complete ?? started.data.verification_uri,
+    expiresInSeconds: started.data.expires_in,
+    intervalSeconds: started.data.interval ?? DEFAULT_INTERVAL_SECONDS,
+  };
+};
+
+/** `claimed` is an app extension (RFC 6749 §5.1 allows it); optional so a sign-in never fails over it. */
+const Granted = z.object({
+  access_token: z.string().min(1),
+  claimed: z.coerce.number().int().min(0).optional(),
+});
+
+const Pending = z.object({
+  error: z.enum(["authorization_pending", "slow_down", "access_denied", "expired_token"]),
+  interval: z.number().int().nonnegative().optional(),
+});
+
+export type PollOutcome =
+  | { type: "token"; token: string; claimed: number | undefined }
+  | { type: "pending" }
+  | { type: "slow_down"; intervalSeconds: number | undefined }
+  | { type: "denied" }
+  | { type: "expired" };
+
+export const pollSignIn = async (api: string, deviceCode: string): Promise<PollOutcome> => {
+  const answer = await send(api, "/api/device/token", {
+    method: "POST",
+    body: { device_code: deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" },
+  });
+
+  if (answer.status === 200) {
+    const granted = Granted.safeParse(answer.body);
+    if (!granted.success)
+      throw unavailable(api, "the sign-in was approved and the answer carried no token", answer.status);
+    return { type: "token", token: granted.data.access_token, claimed: granted.data.claimed };
+  }
+
+  const pending = Pending.safeParse(answer.body);
+  if (!pending.success)
+    // Includes `invalid_request`, which waiting will not fix.
+    throw unavailable(api, "the answer was not one the device flow defines", answer.status);
+
+  switch (pending.data.error) {
+    case "authorization_pending":
+      return { type: "pending" };
+    case "slow_down":
+      return { type: "slow_down", intervalSeconds: pending.data.interval };
+    case "access_denied":
+      return { type: "denied" };
+    case "expired_token":
+      return { type: "expired" };
+    default:
+      return assertNever(pending.data.error, "Unhandled device flow answer");
+  }
+};
+
+/**
+ * Must match the app's hash. Duplicated on purpose: asking the app for ours
+ * would put the install id in a URL.
+ */
+export const installHash = (installId: string): string =>
+  createHash("sha256").update(installId, "utf8").digest("hex");
+
+const Machines = z.object({
+  machines: z.array(z.object({ id: z.string(), revoked: z.boolean() })),
+});
+
+/** `unknown`: this machine has no install id to look up. */
+export type MachineState = "linked" | "revoked" | "unlinked" | "unknown";
+
+export type SignInCheck =
+  | { type: "live"; machine: MachineState }
+  | { type: "rejected" }
+  /** The app could not be asked; says nothing about the credential. */
+  | { type: "unknown"; why: string };
+
+/**
+ * `/api/machines` also answers whether this machine is linked. A store without
+ * accounts reads as `unknown`, never as a revoked credential.
+ */
+export const checkSignIn = async (
+  api: string,
+  token: string,
+  ourInstallId: string | undefined,
+): Promise<SignInCheck> => {
+  let answer: Answer;
+  try {
+    answer = await send(api, "/api/machines", { method: "GET", token });
+  } catch (error) {
+    if (!(error instanceof PrLensCliError)) throw error;
+    return { type: "unknown", why: error.message };
+  }
+
+  if (answer.status === 401 || answer.status === 403) return { type: "rejected" };
+
+  const machines = Machines.safeParse(answer.body);
+  if (!machines.success)
+    return { type: "unknown", why: `${hostOf(api)} answered ${answer.status}, which this CLI cannot read` };
+
+  if (ourInstallId === undefined) return { type: "live", machine: "unknown" };
+
+  const ours = installHash(ourInstallId);
+  const machine = machines.data.machines.find((entry) => entry.id === ours);
+
+  return {
+    type: "live",
+    machine: machine === undefined ? "unlinked" : machine.revoked ? "revoked" : "linked",
+  };
+};
+
+const Account = z.object({ email: z.string().min(3) });
+
+/** Undefined on any failure: the sign-in already succeeded and the email is only for the greeting. */
+export const whoAmI = async (api: string, token: string): Promise<string | undefined> => {
+  try {
+    const answer = await send(api, "/api/account", { method: "GET", token });
+    const account = Account.safeParse(answer.body);
+    return answer.status === 200 && account.success ? account.data.email : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Unlike `whoAmI`, keeps a dead token (`ended`) apart from an unreachable store
+ * (`unknown`), which the sign-in flow will report itself.
+ */
+export type Session =
+  | { type: "active"; email: string }
+  | { type: "ended" }
+  | { type: "unknown" };
+
+export const checkSession = async (api: string, token: string): Promise<Session> => {
+  let answer: Awaited<ReturnType<typeof send>>;
+  try {
+    answer = await send(api, "/api/account", { method: "GET", token });
+  } catch {
+    return { type: "unknown" };
+  }
+
+  // Any other status is an outage, not evidence about the credential.
+  if (answer.status === 401 || answer.status === 403) return { type: "ended" };
+
+  const account = Account.safeParse(answer.body);
+  return answer.status === 200 && account.success
+    ? { type: "active", email: account.data.email }
+    : { type: "unknown" };
+};
+
+export type SignOut = "ended" | "already" | { type: "unreachable"; why: string };
+
+/**
+ * Ends the session and leaves the machine linked (`DELETE /api/machines/{id}`
+ * would unlink it). Unreachable is not thrown: the caller forgets the token
+ * locally either way.
+ */
+export const endSession = async (api: string, token: string): Promise<SignOut> => {
+  try {
+    const answer = await send(api, "/api/session", { method: "DELETE", token });
+    if (answer.status === 200) return "ended";
+    // No such route, or the token was already dead.
+    if (answer.status === 404 || answer.status === 401) return "already";
+    return { type: "unreachable", why: `${hostOf(api)} answered ${answer.status}` };
+  } catch (error) {
+    if (!(error instanceof PrLensCliError)) throw error;
+    return { type: "unreachable", why: error.message };
+  }
+};

package/src/auth.ts

@@ -0,0 +1,183 @@
+/**
+ * The sign-in credential on disk, one file per store so a token never reaches
+ * the wrong one. A file per origin also means two shells signing in at once
+ * can only race on the same origin, where the last write wins correctly.
+ * `0600` on the file, `0700` on the directory: the file names reveal which
+ * stores this person signs in to.
+ */
+import { dirname } from "node:path";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+import { PrLensCliError } from "./errors.js";
+import { writeSecretJsonFile } from "./io.js";
+import { originPath } from "./config-home.js";
+
+const CREDENTIALS = "auth";
+
+/**
+ * Read with `||`, never `??`: the Action sets it to "" when no token was
+ * given, since Actions cannot omit an `env` key conditionally.
+ */
+export const TOKEN_ENV = "PR_LENS_TOKEN";
+
+const ACCOUNT_TOKEN = /^prl_u_[A-Za-z0-9_-]{22}$/;
+
+export const authPath = (
+  env: Record<string, string | undefined>,
+  api: string,
+): string | undefined => originPath(env, CREDENTIALS, api);
+
+export type Credential = { token: string; signedInAt: string | undefined };
+
+/**
+ * An unreadable file is kept apart from a missing one and never deleted here:
+ * it may hold a working token. Only `auth logout` removes it.
+ */
+export type CredentialRead =
+  | { type: "credential"; path: string; credential: Credential }
+  | { type: "none" }
+  | { type: "unreadable"; path: string; why: string };
+
+const describe = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const missing = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  "code" in error &&
+  error.code === "ENOENT";
+
+const credentialIn = (text: string): Credential | undefined => {
+  const contents = ((): unknown => {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return undefined;
+    }
+  })();
+  if (typeof contents !== "object" || contents === null) return undefined;
+
+  const { token, signedInAt } = contents as {
+    token?: unknown;
+    signedInAt?: unknown;
+  };
+  if (typeof token !== "string" || !ACCOUNT_TOKEN.test(token)) return undefined;
+
+  return {
+    token,
+    signedInAt: typeof signedInAt === "string" ? signedInAt : undefined,
+  };
+};
+
+export const readCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<CredentialRead> => {
+  const path = authPath(env, api);
+  if (path === undefined) return { type: "none" };
+
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    return missing(error)
+      ? { type: "none" }
+      : { type: "unreadable", path, why: describe(error) };
+  }
+
+  const credential = credentialIn(text);
+  return credential === undefined
+    ? { type: "unreadable", path, why: "it holds no token this CLI can read" }
+    : { type: "credential", path, credential };
+};
+
+/** Every failure answers undefined, so a push never starts failing over an account. */
+export const readToken = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string | undefined> => {
+  const given = env[TOKEN_ENV];
+  if (given) return given;
+
+  const stored = await readCredential(env, api);
+  return stored.type === "credential" ? stored.credential.token : undefined;
+};
+
+/**
+ * For account commands, which must tell an unreadable file apart from being
+ * signed out rather than advise signing in again.
+ */
+export const requireToken = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string> => {
+  const given = env[TOKEN_ENV];
+  if (given) return given;
+
+  const host = new URL(api).host;
+  const stored = await readCredential(env, api);
+  switch (stored.type) {
+    case "credential":
+      return stored.credential.token;
+    case "unreadable":
+      throw new PrLensCliError(
+        "UNREADABLE_FILE",
+        `the sign-in for ${host} cannot be read`,
+        [
+          `${stored.path}: ${stored.why}`,
+          "pr-lens auth logout clears it, and then auth login writes a fresh one",
+        ].join("\n"),
+      );
+    case "none":
+      throw new PrLensCliError(
+        "AUTH_REQUIRED",
+        `not signed in to ${host}`,
+        "pr-lens auth login",
+      );
+    default:
+      return assertNever(stored, "Unhandled credential read");
+  }
+};
+
+export const writeCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+  token: string,
+  now: string,
+): Promise<string> => {
+  const path = authPath(env, api);
+  if (path === undefined)
+    throw new PrLensCliError(
+      "UNREADABLE_FILE",
+      "there is no home directory to keep this sign-in in",
+      "set HOME, or XDG_CONFIG_HOME, to somewhere this machine can write",
+    );
+
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  return writeSecretJsonFile(path, { api, token, signedInAt: now });
+};
+
+/**
+ * The only place that removes the file, readable or not. No read first: a
+ * sign-in from another shell in between would be thrown away unseen.
+ */
+export const forgetCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<boolean> => {
+  const path = authPath(env, api);
+  if (path === undefined) return false;
+
+  try {
+    await rm(path);
+    return true;
+  } catch (error) {
+    if (missing(error)) return false;
+    throw new PrLensCliError(
+      "UNREADABLE_FILE",
+      `cannot remove ${path}`,
+      describe(error),
+    );
+  }
+};