@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/missingconfig.ts

@@ -0,0 +1,7 @@
+// The refusal `loadConfig` raises when the live config does not exist: its
+// message already says where it looked and what writes one, so the `qcr` bin
+// prints it as one line (`qcr <verb>: <message>`) instead of a stack. A leaf,
+// so the bin's front door can recognise it without loading the config module.
+export class MissingConfigError extends Error {
+  override readonly name = "MissingConfigError";
+}

package/src/npmverbs.ts

@@ -0,0 +1,264 @@
+// The verbs an npm install of qcr adds beside the app's: `qcr login`,
+// `qcr pi` and `qcr update`. Each runs the pinned pi or a package manager and
+// nothing else: no state, no SQLite, no config beyond the homes.
+//
+//   qcr login [provider]  pi's own /login, in the pinned pi (src/picli.ts),
+//                         into the user's pi agent dir. pi's UI is the flow:
+//                         qcr types /login for the person and steps aside.
+//   qcr pi [args]         the pinned pi with the qcr plugin preloaded
+//                         (`-e <the plugin package's dir>`), args passed on.
+//   qcr update            the package manager that installed qcr (npm, pnpm or
+//                         bun) updates it globally. The release image keeps its
+//                         own route (a release), and a checkout its git.
+//
+// Everything effectful is injected, so tests drive each verb with fakes;
+// `npmVerbDeps()` is the real assembly.
+import { spawnSync, type SpawnSyncOptions } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { pluginPackageDir } from "./coreext.js";
+import { detectInstall, type Installer } from "./installkind.js";
+import { readLogins } from "./loginhint.js";
+import { piCliPath } from "./picli.js";
+
+/** The npm package this CLI is published as. */
+export const CLI_PACKAGE = "@quickchatai/quickreview";
+// The plugin package and where it is installed live in a leaf of their own, so
+// the session manager can find the core's extension files without these verbs.
+export { PLUGIN_PACKAGE, pluginPackageDir } from "./coreext.js";
+// How this qcr was installed lives in a leaf of its own, so the daemon can ask
+// it (src/runhost.ts) without reaching the login verbs below.
+export { IMAGE_APP_ROOT, detectInstall, type InstallKind, type Installer } from "./installkind.js";
+/** The command that updates the CLI globally with `installer`. The plugin is
+ * a dependency at the CLI's exact version, so it moves with it. */
+export function updateCommand(installer: Installer, pkg: string = CLI_PACKAGE): string[] {
+  const spec = `${pkg}@latest`;
+  switch (installer) {
+    case "npm":
+      return ["npm", "install", "-g", spec];
+    case "pnpm":
+      return ["pnpm", "add", "-g", spec];
+    case "bun":
+      return ["bun", "add", "-g", spec];
+  }
+}
+
+/** pi's agent dir: `$PI_CODING_AGENT_DIR`, else `~/.pi/agent`, as pi reads it. */
+export function piAgentDir(env: Readonly<Record<string, string | undefined>>): string {
+  const set = (env["PI_CODING_AGENT_DIR"] ?? "").trim();
+  if (set !== "") return set;
+  return join((env["HOME"] ?? "").trim() || homedir(), ".pi", "agent");
+}
+
+/** The providers pi holds a credential for in `agentDir`, from its auth.json;
+ * empty when there is none or it cannot be read. Never a token. */
+export function loggedInProviders(agentDir: string): string[] {
+  return Object.keys(readLogins(agentDir));
+}
+
+/** Is `cmd` an executable on `path`? */
+export function onPath(cmd: string, path: string | undefined): boolean {
+  for (const dir of (path ?? "").split(delimiter)) {
+    if (dir === "") continue;
+    if (existsSync(join(dir, cmd))) return true;
+  }
+  return false;
+}
+
+export interface NpmVerbDeps {
+  env: Readonly<Record<string, string | undefined>>;
+  /** The CLI package's root (src/config.ts `sandboxRoot`). */
+  pkgRoot: string;
+  /** The pinned pi's CLI entry (src/picli.ts `piCliPath`). */
+  piCli: () => string;
+  /** The plugin package's directory (`pluginPackageDir`). */
+  pluginDir: () => string;
+  /** Run a child with the terminal handed over; its exit code (null: signalled). */
+  run: (
+    cmd: string,
+    args: readonly string[],
+    opts: { env?: NodeJS.ProcessEnv },
+  ) => { status: number | null; error?: Error };
+  /** Is this an interactive terminal (stdin and stdout)? */
+  interactive: boolean;
+  out: (line: string) => void;
+  err: (line: string) => void;
+  /** `node`: the pinned pi's entry is a script, run by this node. */
+  execPath: string;
+}
+
+export function npmVerbDeps(pkgRoot: string): NpmVerbDeps {
+  return {
+    env: process.env,
+    pkgRoot,
+    piCli: () => piCliPath(),
+    pluginDir: () => pluginPackageDir(),
+    run: (cmd, args, opts) => {
+      const o: SpawnSyncOptions = { stdio: "inherit", ...(opts.env ? { env: opts.env } : {}) };
+      const r = spawnSync(cmd, [...args], o);
+      return { status: r.status, ...(r.error ? { error: r.error } : {}) };
+    },
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    out: (l) => console.log(l),
+    err: (l) => console.error(l),
+    execPath: process.execPath,
+  };
+}
+
+/** `qcr pi [args]`: the pinned pi with the plugin preloaded; pi's exit code. */
+export function cmdPi(args: readonly string[], deps: NpmVerbDeps): number {
+  let pi: string;
+  let plugin: string;
+  try {
+    pi = deps.piCli();
+    plugin = deps.pluginDir();
+  } catch (err) {
+    deps.err(`qcr pi: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  const r = deps.run(deps.execPath, [pi, "-e", plugin, ...args], {});
+  if (r.error) {
+    deps.err(`qcr pi: pi could not start: ${r.error.message}`);
+    return 1;
+  }
+  return r.status ?? 1;
+}
+
+export const LOGIN_USAGE = "usage: qcr login [provider]";
+
+/** `qcr login [provider]`: pi's own /login in the pinned pi. With tmux, qcr
+ * starts pi in a tmux session and types /login for the person (the companion's
+ * `qcr scan login` route, src/pilogin.ts `loginInPi`); without it, pi opens
+ * and the person types /login. Either way the login lands in pi's agent dir,
+ * where every review reads it. */
+export async function cmdLogin(args: readonly string[], deps: NpmVerbDeps): Promise<number> {
+  if (args.length > 1 || args.some((a) => a.startsWith("-") && a !== "--help" && a !== "-h")) {
+    deps.err(LOGIN_USAGE);
+    return 2;
+  }
+  if (args[0] === "--help" || args[0] === "-h") {
+    deps.out(
+      [
+        LOGIN_USAGE,
+        "",
+        "Opens pi's own /login in the pi qcr runs on, so the review sessions can use it.",
+        "The login is kept in pi's agent dir ($PI_CODING_AGENT_DIR, default ~/.pi/agent).",
+        "The default review models run on a ChatGPT login (openai-codex); an API key in the",
+        "environment does not stand in for it: log in, or set the review's models in your qcr config.",
+      ].join("\n"),
+    );
+    return 0;
+  }
+  const provider = args[0];
+  if (provider !== undefined && !/^[A-Za-z0-9._-]+$/.test(provider)) {
+    deps.err(`qcr login: ${JSON.stringify(provider)} is not a provider name`);
+    return 2;
+  }
+  if (!deps.interactive) {
+    deps.err("qcr login is interactive: run it in a terminal");
+    return 1;
+  }
+  let pi: string;
+  try {
+    pi = deps.piCli();
+  } catch (err) {
+    deps.err(`qcr login: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  const agentDir = piAgentDir(deps.env);
+  const before = loggedInProviders(agentDir);
+  let status: number | null;
+  if (onPath("tmux", deps.env["PATH"])) {
+    const { loginInPi } = await import("./pilogin.js");
+    let argv: string[];
+    try {
+      argv = loginInPi(provider, pi);
+    } catch (err) {
+      deps.err(
+        err instanceof Error ? err.message.replace(/^scan login/, "qcr login") : String(err),
+      );
+      return 1;
+    }
+    deps.out(`qcr login: opening pi with /login (pi's agent dir ${agentDir}); quit pi when done.`);
+    // Inside tmux already: the login session is a session of its own, not nested.
+    const env: NodeJS.ProcessEnv = { ...deps.env };
+    delete env["TMUX"];
+    const r = deps.run(argv[0]!, argv.slice(1), { env });
+    if (r.error) {
+      deps.err(`qcr login: tmux could not start: ${r.error.message}`);
+      return 1;
+    }
+    status = r.status;
+  } else {
+    deps.out(
+      `qcr login: opening pi — type /login${provider ? ` ${provider}` : ""} and pick your provider, then quit pi (the login lands in ${agentDir}).`,
+    );
+    const r = deps.run(deps.execPath, [pi], {});
+    if (r.error) {
+      deps.err(`qcr login: pi could not start: ${r.error.message}`);
+      return 1;
+    }
+    status = r.status;
+  }
+  const after = loggedInProviders(agentDir);
+  const added = after.filter((p) => !before.includes(p));
+  if (after.length === 0) {
+    deps.err(`qcr login: pi holds no login in ${agentDir} yet; run qcr login again to log in.`);
+    return 1;
+  }
+  deps.out(
+    added.length > 0
+      ? `qcr login: logged in to ${added.join(", ")} (pi's agent dir ${agentDir}).`
+      : `qcr login: pi holds logins for ${after.join(", ")} (pi's agent dir ${agentDir}).`,
+  );
+  return status === 0 || status === null ? 0 : status;
+}
+
+/** `qcr update`: the package manager that installed qcr updates it. A local
+ * (project) install, a checkout and the release image each say how they
+ * update instead; nothing runs. */
+export function cmdUpdate(args: readonly string[], deps: NpmVerbDeps): number {
+  if (args.length > 0) {
+    deps.err("usage: qcr update");
+    return 2;
+  }
+  let root = deps.pkgRoot;
+  try {
+    root = realpathSync(root);
+  } catch {
+    // an unresolvable root is judged as given
+  }
+  const install = detectInstall(root, deps.env);
+  switch (install.kind) {
+    case "image":
+      deps.err(
+        "qcr update: this is the release image, which updates as a release, never in place.",
+      );
+      return 1;
+    case "checkout":
+      deps.err(
+        `qcr update: this qcr runs from a checkout (${install.root}): update it with git pull, then npm run build.`,
+      );
+      return 1;
+    case "local":
+      deps.err(
+        `qcr update: this qcr is a dependency of a project (${install.root}): update it there, with ${install.installer} (${updateCommand(install.installer).join(" ").replace(" -g", "")}).`,
+      );
+      return 1;
+    case "global": {
+      const argv = updateCommand(install.installer);
+      deps.out(`qcr update: ${argv.join(" ")}`);
+      const r = deps.run(argv[0]!, argv.slice(1), {});
+      if (r.error) {
+        deps.err(`qcr update: ${install.installer} could not start: ${r.error.message}`);
+        return 1;
+      }
+      if (r.status === 0)
+        deps.out(
+          "qcr update: done. The pi plugin inside pi updates with pi (`pi update`), if you installed it there.",
+        );
+      return r.status ?? 1;
+    }
+  }
+}

package/src/onboard/choices.ts

@@ -0,0 +1,222 @@
+// The onboarding choice vocabulary — one declaration of every key the steps
+// hand each other, and of every value vocabulary both sides of a handoff must
+// agree on.
+//
+// Why this file exists: each step is tested against its own fake choices, so
+// every per-step suite can stay green while the composed flow is broken — a
+// reader looking under a key no step writes, or testing for a value the writer
+// never records. Two rules prevent that, and `tests/onboard-choices.test.ts`
+// enforces both:
+//
+//   1. No step carries its own string literal for a shared key. Every read and
+//      every write names `CHOICE_KEYS.x`; a step's exported `*_CHOICE_KEY`
+//      constants are aliases of these, kept only so existing call sites and
+//      tests read naturally. A typo is then a compile error, not a silent miss.
+//   2. Every declared key has a writer. `CHOICE_WRITERS` names the step(s) that
+//      record each key, and the test proves each named step really does — so a
+//      key that only ever gets read cannot survive review.
+//
+// A key private to one step — the go-live decision, the bring-up timestamp, the
+// vm-deploy record, the model prefix, the memory key-file path — stays a local
+// constant in that step. This file is about the handoffs.
+//
+// Nothing here imports a step (the steps import this), so there is no cycle and
+// no ordering hazard.
+
+// ---- value vocabularies ------------------------------------------------------
+// Declared once and imported by both sides of the handoff, so a mismatch is a
+// type error rather than a conditional that never fires.
+
+/** Where the reviewer runs. Absent ⇒ "local" (see `topologyOf`). */
+export const TOPOLOGY_CHOICES = ["vm", "local"] as const;
+export type Topology = (typeof TOPOLOGY_CHOICES)[number];
+
+/** The webhook ingress shapes. These four ids are also the operator-facing
+ * names in `INGRESS_OPTIONS` and in docs/onboarding.md. */
+export const INGRESS_CHOICES = ["quick", "ngrok", "named", "polling"] as const;
+export type IngressChoice = (typeof INGRESS_CHOICES)[number];
+
+/** The LLM auth routes. "api" is the API-key route — not "api_key": the value
+ * the LLM step writes is the value every reader must test for. */
+export const AUTH_ROUTES = ["oauth", "api"] as const;
+export type AuthRoute = (typeof AUTH_ROUTES)[number];
+
+/** "owner/name" — the reviewed repo as the interview records it and the App
+ * step parses it: no URL, no trailing `.git`. */
+export const REPO_SLUG_RE = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/;
+
+/** Whether the operator set memory up or declined it (a supported answer). */
+export const MEMORY_CHOICE_IDS = ["configure", "declined"] as const;
+export type MemoryChoice = (typeof MEMORY_CHOICE_IDS)[number];
+
+// ---- the keys ----------------------------------------------------------------
+
+/**
+ * Every choice key handed from one step to another, with the step that writes
+ * it and the step(s) that read it. The comment on each is the contract: change
+ * the value here and every side moves together.
+ */
+export const CHOICE_KEYS = {
+  /** The operator's uid, captured by preflight: the containers run as it. */
+  uid: "qcr_uid",
+
+  /** `Topology`. Written by the topology step; read by everything that has to
+   * know where the stack runs (transport selection, the VM-only steps). */
+  topology: "topology",
+  /** The ssh alias of the review host (VM route). */
+  sshAlias: "vm_ssh_alias",
+  /** The login user ssh resolves for that alias (VM route). */
+  sshUser: "vm_ssh_user",
+
+  /** `AuthRoute`. Written by the LLM step; read by the interview's shape line. */
+  authRoute: "llm_auth_route",
+
+  /** "owner/name" of the reviewed repo. Written by the interview; read by the
+   * GitHub App step and the proof round. */
+  repo: "reviewed_repo",
+  /** The operator's local checkout of the reviewed repo. */
+  repoDir: "reviewed_repo_dir",
+  /** The repo's default branch. */
+  baseBranch: "base_branch",
+  /** IANA ops timezone. */
+  timezone: "ops_timezone",
+  /** The operator's GitHub login. */
+  ownerLogin: "owner_github_login",
+  /** The secrets dir the daemon reads — the App step and the slug reconcile
+   * both resolve their credentials through it. */
+  secretsDir: "secrets_dir",
+  /** Absolute path of the config.toml the interview wrote. */
+  configPath: "config_path",
+  /** What `dry_run` the written config carries (informational for go-live). */
+  dryRun: "config_dry_run",
+  /** The three label names the config carries, so the App step creates the
+   * labels this installation actually triggers on rather than the defaults. */
+  labels: "github_labels",
+
+  /** The App slug. Written by the interview (the operator's answer), then
+   * corrected by the App step and the slug reconcile from GitHub itself. */
+  appSlug: "github_app_slug",
+  /** `botLoginFor(slug)` — how the daemon recognises its own reviews. */
+  botLogin: "github_bot_login",
+  /** Numeric App id. */
+  appId: "github_app_id",
+  /** "personal" | "org:<login>" — where the App is registered. */
+  appTarget: "github_app_target",
+  /** The App name the operator chose (absent ⇒ a suggested unique name). */
+  appName: "github_app_name",
+  /** The installation id on the repo's owner. */
+  installationId: "github_installation_id",
+  /** The App's page on GitHub. */
+  appHtmlUrl: "github_app_html_url",
+
+  /** `IngressChoice`. Written by the ingress step; read by the interview
+   * (does the operator own the hostname?), compose/inventory (which sidecar)
+   * and the verification layer. */
+  ingress: "ingress_choice",
+  /** The public hostname, where the chosen shape has one the operator owns. */
+  ingressHostname: "ingress_hostname",
+  /** The public webhook endpoint, once a stable hostname is settled — the App
+   * step puts it in the manifest instead of the artifact's placeholder. */
+  webhookUrl: "webhook_url",
+
+  /** `MemoryChoice`. Written by the memory step; read by its phase-B peer. */
+  memory: "memory_setup",
+
+  /** Shared by the two memory phases through their common implementation. */
+  memoryRestartOwed: "memory_restart_owed",
+
+  /** The proof round record. Written by the proof step; read by go-live. */
+  proof: "proof_round_completed",
+
+  /** The last successful VM deploy: `{mode: "release", version, host, ...}`.
+   * Written by the deploy step; read by the ssh transport, whose "restart" is a
+   * re-release of the version recorded here. */
+  vmDeployed: "vm_deployed",
+} as const;
+
+export type ChoiceName = keyof typeof CHOICE_KEYS;
+export type ChoiceKey = (typeof CHOICE_KEYS)[ChoiceName];
+
+/**
+ * Which step records each key. Pinned against the sources by
+ * `tests/onboard-choices.test.ts`: every name here must be written by every
+ * step id listed, and no shared key may be left with no writer at all.
+ */
+export const CHOICE_WRITERS: Record<ChoiceName, readonly string[]> = {
+  uid: ["preflight"],
+  topology: ["topology"],
+  sshAlias: ["topology"],
+  sshUser: ["ssh_preflight"],
+  authRoute: ["llm_auth"],
+  repo: ["config_fill"],
+  repoDir: ["config_fill"],
+  baseBranch: ["config_fill"],
+  timezone: ["config_fill"],
+  ownerLogin: ["config_fill"],
+  secretsDir: ["config_fill"],
+  configPath: ["config_fill"],
+  dryRun: ["config_fill"],
+  labels: ["config_fill"],
+  appSlug: ["config_fill", "github_app", "app_slug_reconcile"],
+  botLogin: ["github_app", "app_slug_reconcile"],
+  appId: ["github_app"],
+  appTarget: ["github_app"],
+  appName: ["github_app"],
+  installationId: ["github_app"],
+  appHtmlUrl: ["github_app"],
+  ingress: ["ingress"],
+  ingressHostname: ["ingress"],
+  webhookUrl: ["ingress"],
+  memory: ["memory"],
+  proof: ["proof_round"],
+  vmDeployed: ["vm_deploy"],
+  memoryRestartOwed: ["memory"],
+};
+
+/**
+ * Keys deliberately private to one step: the step records them for its own
+ * later verify() and nothing else ever reads them, so they stay a local literal
+ * in that file rather than joining the shared vocabulary above.
+ *
+ * This is a closed list, and `tests/onboard-choices.test.ts` holds it shut: a
+ * literal-keyed choice constant in a step must appear here (naming the one step
+ * that owns it) and must be referenced by no other step. To hand a value to
+ * another step you therefore have to declare it in `CHOICE_KEYS`, where the
+ * writer check applies.
+ */
+export const PRIVATE_CHOICE_KEYS: Readonly<Record<string, string>> = {
+  llm_model_prefix: "llm_auth",
+  openviking_keys_file: "memory",
+  stack_brought_up_at: "bringup",
+  go_live_decision: "go_live",
+};
+
+/** The bot login GitHub gives an App with this slug. One rule, one place —
+ * every step that writes or checks `[github] bot_login` derives it here. */
+export function botLoginFor(slug: string): string {
+  return `${slug}[bot]`;
+}
+
+// ---- typed readers -----------------------------------------------------------
+// The few places a value vocabulary is tested. Each is total: an absent or
+// unrecognised value is the documented default, never a throw.
+
+function raw(choices: Readonly<Record<string, unknown>>, key: ChoiceKey): string {
+  const v = choices[key];
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/** `value` when it is a member of `vocabulary`, else null. */
+export function memberOf<T extends string>(vocabulary: readonly T[], value: string): T | null {
+  return (vocabulary as readonly string[]).includes(value) ? (value as T) : null;
+}
+
+/** The recorded auth route, or null when the LLM step has not run. */
+export function authRouteOf(choices: Readonly<Record<string, unknown>>): AuthRoute | null {
+  return memberOf(AUTH_ROUTES, raw(choices, CHOICE_KEYS.authRoute));
+}
+
+/** The recorded ingress shape, or null when the ingress step has not run. */
+export function ingressChoiceOf(choices: Readonly<Record<string, unknown>>): IngressChoice | null {
+  return memberOf(INGRESS_CHOICES, raw(choices, CHOICE_KEYS.ingress));
+}