@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/home/setupadapters.ts

@@ -0,0 +1,217 @@
+// The setup checklist's real ports (src/home/setup.ts), and the one function
+// that turns a process's environment into them: the env shim
+// (extensions/cli/home.ts) calls `homeSetupFromEnv(process.env, VERSION)`.
+//
+//   first-run checks  the plugin's pi-version and git steps, over a
+//                     PluginHost of this process (its PATH, the running pi)
+//   repository pick   `gh`: the person's recently pushed repositories, the
+//                     chosen one's canonical name and default branch, and the
+//                     account's login and name
+//   the write         the app config the home's repo port reads
+//                     (locateConfig: $QCR_CONFIG, else the install home's
+//                     config.toml), patched the way the onboarding config
+//                     fill patches it (src/onboard/steps/configfill.ts):
+//                     comment-preserving, only the keys that change, never
+//                     dry_run. A fresh config starts from the shipped
+//                     template, whose dry_run = true it keeps (invariant 6).
+//   timezone          the machine's IANA zone, as Intl resolves it
+//
+// The silent defaults ride on the repository write: the base branch is the
+// chosen repository's (always: it belongs to that repository), and the
+// timezone and the owner's name and login fill a value only while it is
+// empty (or the config is new), so an owner's own choice is never overwritten.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assetRoot } from "@quickchatai/pi-quickreview/src/assetroot.js";
+import { nodeRunner } from "@quickchatai/pi-quickreview/src/plugin/runner.js";
+import type { PluginHost } from "@quickchatai/pi-quickreview/src/plugin/session.js";
+import { declaredPiRange } from "@quickchatai/pi-quickreview/src/plugin/versiongate.js";
+import { writeAtomic } from "@quickchatai/pi-quickreview/src/setupchecklist.js";
+import { locateConfig, stateHome } from "../homes.js";
+import { piAgentDir } from "../piagentdir.js";
+import { execRunner, type Runner, type RunResult } from "./adapters.js";
+import { known, unknown, type Known } from "./ports.js";
+import type { HomeSetupPorts, RepoPickPort, RepoWrite } from "./setup.js";
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+const firstLine = (s: string): string => s.trim().split("\n")[0]?.trim() || "no output";
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** gh's words for "you are not signed in". */
+const SIGNED_OUT = /gh auth login|not logged in|authentication required|HTTP 401|bad credentials/i;
+
+function ghWhy(r: RunResult): string {
+  if (r.missing) return "gh is not installed";
+  if (SIGNED_OUT.test(r.stderr)) return "gh is signed out: run `gh auth login`";
+  return firstLine(r.stderr);
+}
+
+/** The machine's IANA timezone, or null when Intl cannot say. */
+export function systemTimezone(): string | null {
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof tz === "string" && tz !== "" ? tz : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A file's text; null only when it does not exist. Any other failure
+ * throws: a config that exists and cannot be read is never "no config", or
+ * the template would be written over it. */
+function readIfThere(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException | null)?.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export function repoPickPort(o: {
+  runner: Runner;
+  configPath: () => string;
+  templatePath: () => string;
+  read?: (path: string) => string | null;
+  write?: (path: string, text: string) => void;
+}): RepoPickPort {
+  const read = o.read ?? readIfThere;
+  const write = o.write ?? writeAtomic;
+  return {
+    recent: async () => {
+      const r = await o.runner.run("gh", [
+        "repo",
+        "list",
+        "--limit",
+        "8",
+        "--json",
+        "nameWithOwner",
+      ]);
+      if (r.code !== 0) return unknown(ghWhy(r));
+      try {
+        const rows = JSON.parse(r.stdout) as unknown;
+        if (!Array.isArray(rows)) return unknown("gh's answer is not a list");
+        return known(
+          rows.flatMap((x: { nameWithOwner?: unknown }) =>
+            typeof x?.nameWithOwner === "string" ? [x.nameWithOwner] : [],
+          ),
+        );
+      } catch (err) {
+        return unknown(`gh's answer is not JSON: ${message(err)}`);
+      }
+    },
+    describe: async (repo) => {
+      const r = await o.runner.run("gh", [
+        "repo",
+        "view",
+        repo,
+        "--json",
+        "nameWithOwner,defaultBranchRef",
+      ]);
+      if (r.code !== 0) return { ok: false, why: ghWhy(r) };
+      try {
+        const v = JSON.parse(r.stdout) as {
+          nameWithOwner?: unknown;
+          defaultBranchRef?: { name?: unknown } | null;
+        };
+        const branch = v.defaultBranchRef?.name;
+        return {
+          ok: true,
+          repo: typeof v.nameWithOwner === "string" ? v.nameWithOwner : repo,
+          defaultBranch: typeof branch === "string" && branch !== "" ? branch : null,
+        };
+      } catch (err) {
+        return { ok: false, why: `gh's answer is not JSON: ${message(err)}` };
+      }
+    },
+    profile: async (): Promise<Known<{ login: string; name: string | null }>> => {
+      const r = await o.runner.run("gh", ["api", "user"]);
+      if (r.code !== 0) return unknown(ghWhy(r));
+      try {
+        const v = JSON.parse(r.stdout) as { login?: unknown; name?: unknown };
+        if (typeof v.login !== "string") return unknown("gh's account has no login");
+        return known({
+          login: v.login,
+          name: typeof v.name === "string" && v.name.trim() !== "" ? v.name.trim() : null,
+        });
+      } catch (err) {
+        return unknown(`gh's answer is not JSON: ${message(err)}`);
+      }
+    },
+    write: async (choice): Promise<RepoWrite> => {
+      let path: string;
+      try {
+        path = o.configPath();
+      } catch (err) {
+        return { ok: false, why: message(err) };
+      }
+      let existing: string | null;
+      let template: string | null = "";
+      try {
+        existing = read(path);
+      } catch (err) {
+        return { ok: false, why: `can't read ${path} (${message(err)}); nothing was written` };
+      }
+      try {
+        if (existing === null) template = read(o.templatePath());
+      } catch {
+        template = null;
+      }
+      if (template === null)
+        return { ok: false, why: `there is no ${path} and the shipped template is not readable` };
+      // the config fill's writer, loaded only when a repository is written
+      const { renderRepoConfig } = await import("../onboard/steps/repoconfig.js");
+      const r = renderRepoConfig(existing, template, choice);
+      if (!r.ok) return r;
+      try {
+        if (r.text !== existing) write(path, r.text);
+      } catch (err) {
+        return { ok: false, why: `can't write ${path}: ${message(err)}` };
+      }
+      return { ok: true, path, wrote: r.wrote };
+    },
+  };
+}
+
+/** The PluginHost the first-run checks read: this process's PATH and the
+ * running pi (its version, which the env shim reads off pi). Only the
+ * plugin's pi-version and git steps run over it, so its auth answers
+ * nothing. */
+export function firstRunHost(env: Env, piVersion: string): PluginHost {
+  return {
+    cwd: join(stateHome(env), "home"),
+    env,
+    home: (env["HOME"] ?? "").trim() || homedir(),
+    piVersion,
+    agentDir: piAgentDir(env),
+    auth: {
+      logins: () => ({}),
+      configured: () => false,
+      refresh: () => Promise.reject(new Error("the home's first-run checks hold no login")),
+    },
+    runner: nodeRunner(env),
+    shutdown: new AbortController().signal,
+  };
+}
+
+/** The setup's options from a process's environment and the running pi's
+ * version: the env shim's one call. */
+export function homeSetupFromEnv(env: Env, piVersion: string): HomeSetupPorts {
+  let range: string | null = null;
+  try {
+    range = declaredPiRange();
+  } catch {
+    range = null;
+  }
+  return {
+    ...(range !== null ? { firstRun: { host: firstRunHost(env, piVersion), range } } : {}),
+    repos: repoPickPort({
+      runner: execRunner,
+      configPath: () => locateConfig({ env }).path,
+      templatePath: () => join(assetRoot(), "config.example.toml"),
+    }),
+    timezone: systemTimezone,
+  };
+}

package/src/home/setupcard.ts

@@ -0,0 +1,288 @@
+// The setup card: on a machine that is not set up, the home opens on this,
+// centred at half the terminal's width and about half its height, instead of the panel. It draws the setup checklist
+// (src/home/setup.ts) in pi's theme tokens; when the last step is done the
+// extension swaps it for the panel at the top right.
+//
+//   ╭─ quickreview ──────────────────────────── setup ─╮
+//   │   Welcome to quickreview            1 of 3 done   │
+//   │   ✓  Sign in to OpenAI   ChatGPT · signed in with pi │
+//   │   ▸  Connect GitHub                  alt+n check   │  the next step
+//   │        gh is signed out: run `gh auth login` …     │
+//   │   ○  Choose a repository                           │
+//   ├──────────────────────────────────────────────────┤
+//   │ the notice, then the key hints                     │
+//   ╰──────────────────────────────────────────────────╯
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type { HomeModel } from "./model.js";
+import { loginFailureText, type HomeSetup, type SetupStepView } from "./setup.js";
+
+type Fg = Parameters<Theme["fg"]>[0];
+
+/** Where the card sits: centred, half the width. */
+export const SETUP_OVERLAY = {
+  anchor: "center",
+  width: "50%",
+  minWidth: 80,
+  nonCapturing: true,
+} as const;
+
+/** The share of the terminal's height the card fills. */
+export const CARD_HEIGHT = 0.5;
+/** Sub-rows (instructions, the device code) are indented under the label. */
+const INDENT = "       ";
+const NOTICE_ROWS = 3;
+const SPIN = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface CardHost {
+  setup: HomeSetup;
+  model: HomeModel;
+  focused(): boolean;
+  /** The terminal's height. */
+  rows(): number;
+  unfocus(): void;
+  frame(): number;
+  /** Run the next step (⏎ while the card is focused). */
+  next(): void;
+}
+
+/** What each step's key does, in the hint beside it. */
+const VERB: Record<SetupStepView["id"], string> = {
+  login: "sign in",
+  github: "check",
+  repo: "choose",
+};
+
+export class SetupCard implements Component {
+  constructor(
+    private readonly th: Theme,
+    private readonly host: CardHost,
+  ) {}
+
+  private c(color: Fg, s: string): string {
+    return this.th.fg(color, s);
+  }
+
+  private spin(): string {
+    return SPIN[this.host.frame() % SPIN.length]!;
+  }
+
+  private edge(s: string): string {
+    return this.c(this.host.focused() ? "borderAccent" : "borderMuted", s);
+  }
+
+  /** The key that runs the next step now. */
+  private key(): string {
+    return this.host.focused() ? "⏎" : "alt+n";
+  }
+
+  private row(w: number, left: string, right = "", selected = false): string {
+    const inner = w - 4;
+    const r = right ? ` ${right}` : "";
+    const l = truncateToWidth(left, Math.max(1, inner - visibleWidth(r)), "…");
+    const gap = Math.max(0, inner - visibleWidth(l) - visibleWidth(r));
+    let text = ` ${l}${" ".repeat(gap)}${r} `;
+    if (selected) text = this.th.bg("selectedBg", text);
+    return `${this.edge("│")}${text}${this.edge("│")}`;
+  }
+
+  /** Text under a step, wrapped inside the frame. */
+  private sub(w: number, text: string, color: Fg = "muted"): string[] {
+    const room = Math.max(10, w - 4 - INDENT.length);
+    return wrapTextWithAnsi(text, room).map((l) => this.row(w, `${INDENT}${this.c(color, l)}`));
+  }
+
+  private top(w: number): string {
+    const left = `${this.edge("╭─ ")}${this.th.bold(this.c("accent", "quickreview"))} `;
+    const right = ` ${this.c("muted", "setup")}${this.edge(" ─╮")}`;
+    const fill = Math.max(0, w - visibleWidth(left) - visibleWidth(right));
+    return `${left}${this.edge("─".repeat(fill))}${right}`;
+  }
+
+  private rule(w: number): string {
+    return this.edge(`├${"─".repeat(Math.max(0, w - 2))}┤`);
+  }
+
+  private bottom(w: number): string {
+    return this.edge(`╰${"─".repeat(Math.max(0, w - 2))}╯`);
+  }
+
+  private stepRows(w: number, s: SetupStepView): string[] {
+    const v = this.host.setup.view();
+    const out: string[] = [];
+    const k = this.key();
+    let mark: string;
+    let label: string;
+    let right = "";
+    if (s.state === "done") {
+      mark = this.c("success", "✓");
+      label = this.c("muted", s.title);
+      right = this.c("muted", s.found ?? "done");
+    } else if (s.state === "running") {
+      mark = this.c("accent", this.spin());
+      label = this.th.bold(this.c("text", s.title));
+      right = this.c("dim", v.login.code ? "waiting for you…" : "starting…");
+    } else if (s.unknown !== undefined) {
+      mark = this.c("dim", "?");
+      label = s.next ? this.th.bold(this.c("text", s.title)) : this.c("text", s.title);
+      right = s.next
+        ? `${this.c("accent", k)} ${this.c("muted", VERB[s.id])}`
+        : this.c("dim", "unknown");
+    } else if (s.next) {
+      mark = this.c("accent", "▸");
+      label = this.th.bold(this.c("text", s.title));
+      right = `${this.c("accent", k)} ${this.c("muted", VERB[s.id])}`;
+    } else {
+      mark = this.c("dim", "○");
+      label = this.c("dim", s.title);
+    }
+    out.push(this.row(w, `  ${mark}  ${label}`, right, s.next));
+    if (s.state === "done") return out;
+    if (s.id === "login") out.push(...this.loginRows(w, s));
+    else if (s.unknown !== undefined)
+      out.push(...this.sub(w, `Unknown — ${s.unknown}.`, "warning"));
+    else if (s.next && s.id === "github" && s.missing)
+      out.push(...this.sub(w, `${capital(s.missing)}, then ${k} checks again.`, "warning"));
+    else if (s.next && s.id === "repo")
+      out.push(
+        ...this.sub(
+          w,
+          "One of your recently pushed repositories, or paste any owner/name or GitHub URL.",
+        ),
+      );
+    return out;
+  }
+
+  private loginRows(w: number, s: SetupStepView): string[] {
+    const v = this.host.setup.view();
+    const k = this.key();
+    const out: string[] = [];
+    const chatgpt = v.provider === "OpenAI";
+    const setting = "Device-code login must be on first: ChatGPT → Settings → Security.";
+    if (s.state === "running") {
+      const code = v.login.code;
+      if (!code) {
+        if (chatgpt) out.push(...this.sub(w, setting));
+        out.push(
+          this.row(
+            w,
+            `${INDENT}${this.c("accent", this.spin())} ${this.c("dim", "asking for a code…")}`,
+          ),
+        );
+        return out;
+      }
+      out.push(this.row(w, ""));
+      out.push(
+        this.row(
+          w,
+          `${INDENT}${this.c("muted", "1  Open ")}  ${this.c("accent", code.verificationUri)}`,
+        ),
+      );
+      out.push(
+        this.row(
+          w,
+          `${INDENT}${this.c("muted", "2  Enter")}  ${this.th.bold(this.c("text", code.userCode))}`,
+        ),
+      );
+      out.push(this.row(w, ""));
+      if (chatgpt) out.push(...this.sub(w, setting, "dim"));
+      out.push(
+        this.row(
+          w,
+          `${INDENT}${this.c("accent", this.spin())} ${this.c("dim", "waiting for you to approve…")}`,
+        ),
+      );
+      return out;
+    }
+    if (v.login.failure) out.push(...this.sub(w, loginFailureText(v.login.failure, k), "warning"));
+    if (s.unknown !== undefined) out.push(...this.sub(w, `Unknown — ${s.unknown}.`, "warning"));
+    if (s.next && chatgpt && v.login.failure?.kind !== "not_enabled")
+      out.push(...this.sub(w, setting));
+    return out;
+  }
+
+  private hints(w: number): string {
+    const k = (key: string, label: string): string =>
+      `${this.c("accent", key)} ${this.c("muted", label)}`;
+    return this.row(
+      w,
+      this.host.focused()
+        ? `${k("⏎", "next step")}  ${k("esc", "back to the chat")}`
+        : `${k("alt+n", "next step")}  ${k("f2", "focus the card")}  ${this.c("dim", "· or just type to ask pi")}`,
+    );
+  }
+
+  render(width: number): string[] {
+    const w = Math.max(40, width);
+    const v = this.host.setup.view();
+    const body = [
+      this.row(w, ""),
+      this.row(
+        w,
+        `  ${this.th.bold(this.c("text", "Welcome to quickreview"))}`,
+        this.c("muted", `${v.done} of ${v.total} done  `),
+      ),
+      this.row(
+        w,
+        `  ${this.c("muted", "Sign in once, choose a repository, and review your first pull request.")}`,
+      ),
+      this.row(w, ""),
+    ];
+    for (const c of v.checks) {
+      body.push(
+        this.row(
+          w,
+          `  ${this.c("warning", "✗")}  ${this.th.bold(this.c("text", c.title))}`,
+          c.next ? `${this.c("accent", this.key())} ${this.c("muted", "check")}` : "",
+          c.next,
+        ),
+      );
+      body.push(
+        ...this.sub(
+          w,
+          `${capital(c.why)}${c.next ? `, then ${this.key()} checks again.` : "."}`,
+          "warning",
+        ),
+      );
+    }
+    for (const s of v.steps) body.push(...this.stepRows(w, s));
+    body.push(this.row(w, ""));
+    const foot = [this.rule(w)];
+    const n = this.host.model.notice;
+    if (n) {
+      const color: Fg = n.kind === "ok" ? "success" : n.kind === "warn" ? "warning" : "text";
+      for (const l of wrapTextWithAnsi(n.text, w - 4).slice(0, NOTICE_ROWS))
+        foot.push(this.row(w, this.c(color, l)));
+    }
+    foot.push(this.hints(w), this.bottom(w));
+    const target = Math.round(this.host.rows() * CARD_HEIGHT);
+    const spare = Math.max(0, target - 1 - body.length - foot.length);
+    const blank = (k: number): string[] => Array.from({ length: k }, () => this.row(w, ""));
+    return [
+      this.top(w),
+      ...blank(Math.floor(spare / 2)),
+      ...body,
+      ...blank(Math.ceil(spare / 2)),
+      ...foot,
+    ].map((l) => truncateToWidth(l, w));
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) this.host.unfocus();
+    else if (matchesKey(data, "enter")) this.host.next();
+  }
+
+  handleMouse(e: TuiMouseEvent): TuiMouseEventResult | undefined {
+    return e.type === "click" ? { focus: true } : undefined;
+  }
+
+  invalidate(): void {}
+}
+
+const capital = (s: string): string => (s ? `${s[0]!.toUpperCase()}${s.slice(1)}` : s);

package/src/home/setuptools.ts

@@ -0,0 +1,57 @@
+// The setup checklist's `home_*` tools: each step's action, as the model in
+// the chat calls it. The keys call the same HomeSetup methods
+// (extensions/home.ts), so a key and a tool never do two different things.
+import { textResult, type QcrTool } from "@quickchatai/pi-quickreview/extensions/pi-tool.js";
+import type { HomeSetup } from "./setup.js";
+import type { HOME_SETUP_TOOL_NAMES } from "./toolnames.js";
+
+export type HomeSetupToolName = (typeof HOME_SETUP_TOOL_NAMES)[number];
+
+const NO_PARAMS = { type: "object", properties: {}, additionalProperties: false } as const;
+
+/** One definition per HOME_SETUP_TOOL_NAMES entry. */
+export function setupTools(setup: HomeSetup): {
+  [N in HomeSetupToolName]: QcrTool & { name: N };
+} {
+  return {
+    home_setup_next: {
+      name: "home_setup_next",
+      label: "Home: next setup step",
+      description:
+        "Run the next step of the quickreview home's setup checklist (sign in, connect GitHub, choose a repository), as alt+n does. Answers what happened, or that setup is done.",
+      parameters: NO_PARAMS,
+      execute: async () => textResult(await setup.next()),
+    },
+    home_sign_in: {
+      name: "home_sign_in",
+      label: "Home: sign in",
+      description:
+        "Start pi's own device-code login for the provider the chat runs on. Answers with the URL and the code to enter once pi has them; the sign-in finishes in the background when the person approves it. Device-code login must be on in ChatGPT → Settings → Security.",
+      parameters: NO_PARAMS,
+      execute: async () => textResult(await setup.signIn()),
+    },
+    home_check_github: {
+      name: "home_check_github",
+      label: "Home: check GitHub",
+      description:
+        "Check again whether gh is installed and signed in. When it is not, the answer says what to run.",
+      parameters: NO_PARAMS,
+      execute: async () => textResult(await setup.checkGithub()),
+    },
+    home_choose_repo: {
+      name: "home_choose_repo",
+      label: "Home: choose a repository",
+      description:
+        "Set the repository the home reviews: owner/name or any GitHub URL of it. It is written to the qcr config's [github] repo. Without `repo`, answers the person's recently pushed repositories to choose from.",
+      parameters: {
+        type: "object",
+        properties: {
+          repo: { type: "string", description: "owner/name, or a GitHub URL of the repository." },
+        },
+        additionalProperties: false,
+      },
+      execute: async (_id, p) =>
+        textResult(await setup.chooseRepo(typeof p["repo"] === "string" ? p["repo"] : undefined)),
+    },
+  };
+}