@coldtea/pr-lens-cli 0.8.1 → 0.10.0

package/src/commands/analyze.ts

@@ -1,10 +1,10 @@
-import { LENSES, type GraphDocInput, type Lens } from "@coldtea/pr-lens-schema";
+import { LENSES, PROVIDERS, type GraphDocInput, type Lens, type Provider } from "@coldtea/pr-lens-schema";
 import { dirname } from "node:path";
 import { parseOptions, readBoolean, readInt, readList, readString } from "../args.js";
 import { discoverConfig, loadConfig, type LoadedConfig } from "../config-file.js";
 import { PrLensCliError, usageError } from "../errors.js";
 import { extractGraph } from "../extract.js";
-import { collectDiff, mergeBase, parseRepoSlug, remoteSlug, repositoryRoot, resolveCommit } from "../git.js";
+import { collectDiff, mergeBase, parseRepoSlug, pullRequestUrl, remoteSlug, repositoryRoot, resolveCommit } from "../git.js";
 import { writeJsonFile } from "../io.js";
 import { buildExtractionPrompt, SYSTEM_PROMPT } from "../prompt.js";
 import { completeJson, isProviderId, PROVIDER_IDS, resolveProvider } from "../providers/index.js";
@@ -36,6 +36,8 @@ environment, and the diff goes straight to the provider you name.
   --pr <number>             pull request number, recorded in provenance
   --repo-slug <owner/name>  override the slug read from the git remote
   --remote <name>           remote to read the slug from (default origin)
+  --forge <name>            github | gitlab | bitbucket — where the repository is
+                            hosted (default read from the remote host)
   --max-diff-bytes <n>      truncate the diff sent to the model (default ${DEFAULT_MAX_DIFF_BYTES})
   --max-output-tokens <n>   room for the answer (default ${DEFAULT_MAX_OUTPUT_TOKENS})
   --dry-run                 report what would be sent, and send nothing
@@ -52,6 +54,16 @@ const readLenses = (values: Record<string, unknown>): Lens[] | undefined => {
   return LENSES.filter((lens) => requested.includes(lens));
 };
 
+const readForge = (values: Record<string, unknown>): Provider | undefined => {
+  const forge = readString(values.forge, "forge");
+  if (forge === undefined) return undefined;
+
+  const known = PROVIDERS.find((provider) => provider === forge);
+  if (known === undefined)
+    throw usageError(`unknown forge ${JSON.stringify(forge)}`, `known forges: ${PROVIDERS.join(", ")}`);
+  return known;
+};
+
 const readProviderId = (values: Record<string, unknown>) => {
   const id = readString(values.provider, "provider") ?? "gemini";
   if (!isProviderId(id))
@@ -78,6 +90,7 @@ export const analyzeCommand = async (
     pr: { type: "string" },
     "repo-slug": { type: "string" },
     remote: { type: "string" },
+    forge: { type: "string" },
     "max-diff-bytes": { type: "string" },
     "max-output-tokens": { type: "string" },
     "dry-run": { type: "boolean" },
@@ -94,17 +107,28 @@ export const analyzeCommand = async (
   const maxDiffBytes = readInt(values["max-diff-bytes"], "max-diff-bytes", DEFAULT_MAX_DIFF_BYTES);
 
   const slugOption = readString(values["repo-slug"], "repo-slug");
-  const slug = slugOption === undefined
+  const detected = slugOption === undefined
     ? await remoteSlug(repo, readString(values.remote, "remote") ?? "origin")
     : parseRepoSlug(slugOption);
 
-  if (slug === undefined)
+  if (detected === undefined)
     throw new PrLensCliError(
       "REPOSITORY_UNKNOWN",
       "cannot tell which repository this is",
       "pass --repo-slug owner/name, or add a git remote the CLI can read",
     );
 
+  const forge = readForge(values);
+  // An owner/name slug carries no host, and parseRepoSlug fills in
+  // github.com — which a non-GitHub forge would then dress in the wrong
+  // URLs. Refusing beats a permalink that 404s in the reader's face.
+  if (forge !== undefined && forge !== "github" && slugOption !== undefined)
+    throw usageError(
+      `--forge ${forge} cannot be combined with --repo-slug`,
+      "an owner/name slug names no host; let the CLI read the git remote, which carries one",
+    );
+  const slug = forge === undefined ? detected : { ...detected, provider: forge };
+
   const configPath = readString(values.config, "config");
   const configured: LoadedConfig | undefined = readBoolean(values["no-config"])
     ? undefined
@@ -162,10 +186,10 @@ export const analyzeCommand = async (
   const pullRequest =
     pr === undefined
       ? undefined
-      : { number: pr, url: `https://${slug.host}/${slug.owner}/${slug.name}/pull/${pr}` };
+      : { number: pr, url: pullRequestUrl(slug, pr) };
 
   const provenance: GraphDocInput["provenance"] = {
-    repo: slug,
+    repo: { owner: slug.owner, name: slug.name, host: slug.host },
     base: { sha: comparedAgainst, ref: baseCommit.ref },
     head: { sha: headCommit.sha, ref: headCommit.ref },
     ...(pullRequest === undefined ? {} : { pullRequest }),

package/src/commands/auth.ts

@@ -72,7 +72,7 @@ const sleep = (ms: number): Promise<void> =>
 const hostOf = (api: string): string => new URL(api).host;
 
 /** True means asked, not opened (over SSH it "succeeds" on no screen), so the link is printed either way. */
-const askToOpen = (url: string): boolean => {
+export const askToOpen = (url: string): boolean => {
   // The URL came off the wire: only http(s), and never through a shell
   // (hence `rundll32` over `cmd /c start`).
   const scheme = ((): string => {

package/src/commands/canvas.ts

@@ -36,6 +36,14 @@ 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 {
+  answerCommand,
+  forkCommand,
+  LIVE_USAGE,
+  lookCommand,
+  openLiveCommand,
+  showCommand,
+} from "../canvas/live.js";
 import { parseOptions, readBoolean, readString } from "../args.js";
 import { PrLensCliError, usageError } from "../errors.js";
 import { DEFAULT_API, API_ENV, readApi, requireSameApi, requireWriteToken, settleRotation, settlePendingRotation, writeCredential } from "../canvas/write.js";
@@ -53,13 +61,18 @@ const SUBCOMMANDS = [
   "claim",
   "rotate",
   "delete",
+  "open",
+  "answer",
+  "show",
+  "fork",
+  "look",
 ] 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 <list | push | pull | claim | rotate | delete> [options]
+export const USAGE = `pr-lens canvas <list | push | pull | claim | rotate | delete | open | answer | show | fork | look> [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
@@ -91,6 +104,16 @@ in its fragment, so share the view link and keep the edit link to yourself.
   pr-lens canvas delete                permanently delete the hosted canvas; keep local graph and SVG files
     --canvas <id|name>                 which canvas (default the checkout's only canvas)
 
+Live mode puts your coding agent beside an open canvas: it answers there, with
+the camera, the highlights and the links the page's own agent uses.
+
+${LIVE_USAGE}
+
+  Every live command takes the drawing it is about:
+    --drawing <path>                   the same drawn.graph.json you opened (open takes it as
+                                       its argument); left out, the checkout's only paired canvas
+    --canvas <id|name>                 a canvas by id or name, instead of a drawing
+
   --api <url>                          the PR Lens app (default $${API_ENV}, else ${DEFAULT_API})`;
 
 type CanvasRef = {
@@ -173,6 +196,7 @@ const recordPull = (current: CanvasRegistry, pull: PullRecord): Recorded => {
     ...(pending === undefined ? {} : { pending }),
     ...(kept === undefined ? {} : { writeToken: kept }),
     rev: pull.fetched?.rev ?? entry?.rev ?? 0,
+    ...(entry?.live === undefined ? {} : { live: entry.live }),
   };
 
   return imports
@@ -639,7 +663,7 @@ export const canvasCommand = async (
   const [name, ...rest] = args;
   if (name === undefined)
     throw usageError(
-      "canvas needs a subcommand: list, push, pull, claim, rotate or delete",
+      "canvas needs a subcommand: list, push, pull, claim, rotate, delete, open, answer, show, fork or look",
     );
   if (!isSubcommand(name))
     throw usageError(`unknown canvas subcommand ${JSON.stringify(name)}`);
@@ -657,6 +681,16 @@ export const canvasCommand = async (
       return deleteCommand(rest, terminal, env);
     case "rotate":
       return rotate(rest, terminal, env);
+    case "open":
+      return openLiveCommand(rest, terminal, env);
+    case "answer":
+      return answerCommand(rest, terminal, env);
+    case "show":
+      return showCommand(rest, terminal, env);
+    case "fork":
+      return forkCommand(rest, terminal, env);
+    case "look":
+      return lookCommand(rest, terminal, env);
     default:
       return assertNever(name, "Unhandled canvas subcommand");
   }

package/src/commands/comment.ts

@@ -1,6 +1,7 @@
 import { graphContentHash } from "@coldtea/pr-lens-renderer";
+import { PROVIDERS, type Provider } from "@coldtea/pr-lens-schema";
 import { parseOptions, readBoolean, readString } from "../args.js";
-import { composeComment, COMMENT_MARKER } from "../comment.js";
+import { commentMarker, composeComment } from "../comment.js";
 import { loadConfig } from "../config-file.js";
 import { readGraphDoc, readRenderManifest } from "../document.js";
 import { usageError } from "../errors.js";
@@ -20,10 +21,21 @@ goes to stdout, or to a file, for whatever does the posting.
                               manifest records local paths
       --config <file>         read 'branding' from a repository config
       --no-branding           leave off the PR Lens footer
+      --target <forge>        github | gitlab | bitbucket — who renders the
+                              comment (default github). GitLab gets no <picture>
+                              pair; Bitbucket gets plain markdown, no HTML
       --print-marker          print the hidden marker that identifies the
                               comment, and nothing else
   -o, --out <file>            write the markdown here instead of stdout`;
 
+const readTarget = (values: Record<string, unknown>): Provider => {
+  const target = readString(values.target, "target") ?? "github";
+  const known = PROVIDERS.find((provider) => provider === target);
+  if (known === undefined)
+    throw usageError(`unknown target ${JSON.stringify(target)}`, `known targets: ${PROVIDERS.join(", ")}`);
+  return known;
+};
+
 export const commentCommand = async (args: readonly string[], terminal: Terminal): Promise<void> => {
   const { values, positionals } = parseOptions(args, {
     graph: { type: "string" },
@@ -31,6 +43,7 @@ export const commentCommand = async (args: readonly string[], terminal: Terminal
     "asset-base-url": { type: "string" },
     config: { type: "string" },
     "no-branding": { type: "boolean" },
+    target: { type: "string" },
     "print-marker": { type: "boolean" },
     out: { type: "string", short: "o" },
   });
@@ -38,8 +51,10 @@ export const commentCommand = async (args: readonly string[], terminal: Terminal
   if (positionals.length > 0)
     throw usageError(`comment takes no positional arguments, got ${positionals.join(" ")}`);
 
+  const target = readTarget(values);
+
   if (readBoolean(values["print-marker"])) {
-    terminal.out(COMMENT_MARKER);
+    terminal.out(commentMarker(target));
     return;
   }
 
@@ -65,6 +80,7 @@ export const commentCommand = async (args: readonly string[], terminal: Terminal
     manifest,
     assetBaseUrl: readString(values["asset-base-url"], "asset-base-url"),
     branding: readBoolean(values["no-branding"]) ? false : (configured?.config.branding ?? true),
+    target,
   });
 
   const out = readString(values.out, "out");

package/src/commands/render.ts

@@ -1,4 +1,10 @@
-import { applyCorrections, PrLensRenderError, renderAll, THEMES, type Theme } from "@coldtea/pr-lens-renderer";
+import {
+  applyCorrections,
+  PrLensRenderError,
+  renderAll,
+  THEME_PAIR,
+  type RenderThemes,
+} from "@coldtea/pr-lens-renderer";
 import { safeParseGraphDoc, type Config, type GraphDoc } from "@coldtea/pr-lens-schema";
 import { join } from "node:path";
 import { expectOne, parseOptions, readBoolean, readString } from "../args.js";
@@ -36,20 +42,27 @@ with no sections gets one diagram per lens it declares.
 
   -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)
+      --theme <theme>  light | dark | both | neutral (default both)
+                       neutral is the single self-contained render for a
+                       surface that shows one image: GitLab and Bitbucket
       --config <file>  corrections to draw with (default the repository's, if any)
       --no-config      ignore the repository's corrections`;
 
-const readThemes = (value: unknown): readonly Theme[] => {
+const readThemes = (value: unknown): RenderThemes => {
   const theme = readString(value, "theme") ?? "both";
   switch (theme) {
     case "light":
     case "dark":
+    // A surface that shows one image wants this one instead of the pair, not
+    // as well as it — so it is a choice of --theme, never an addition to both.
+    case "neutral":
       return [theme];
     case "both":
-      return THEMES;
+      return THEME_PAIR;
     default:
-      throw usageError(`--theme takes light, dark or both, got ${JSON.stringify(theme)}`);
+      throw usageError(
+        `--theme takes light, dark, both or neutral, got ${JSON.stringify(theme)}`,
+      );
   }
 };