@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/onboard/engine.ts

@@ -0,0 +1,518 @@
+// OnboardingEngine — the seam of the onboarding wizard: a checklist state
+// machine plus deterministic step implementations behind injected adapters.
+// pi is a thin driver over this engine (extensions/onboarding.ts registers one
+// tool per step); the engine
+// itself is fully drivable from tests and from a non-LLM fallback entry, and
+// nothing in here touches the network, Docker, or a real pi except through
+// the adapters.
+//
+// Resumability contract:
+//   - checklist state persists to state/onboarding/checklist.json after every
+//     step, tmp+rename atomic (the verdicts.ts convention);
+//   - startup reconciles claimed state against reality: a step claimed done is
+//     re-verified with its verify(), never trusted from the file alone;
+//   - a fully-done checklist re-runs as verify-only (the wizard doubles as a
+//     diagnostic);
+//   - a corrupt/unreadable checklist degrades to a fresh one (the resume
+//     re-verifies everything anyway) — never a crash.
+//
+// The finish path writes the first-run marker state/companion/first-run.json
+// ({"completed_at": "<iso>"}) exactly once — the contract the companion's
+// first-run greeting consumes. Keep the path and shape stable.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+// ---- adapters ---------------------------------------------------------------
+
+export interface ProcessResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Process seam. Never throws: a missing binary is a nonzero code with the
+ * error text in stderr, so a step can render it as a plain red check. */
+export interface ProcessRunner {
+  run(cmd: string, args: string[]): Promise<ProcessResult>;
+}
+
+/** Everything a step may touch outside its own logic. All injected — tests
+ * fake every field; extensions/onboarding.ts builds the real set. Steps use
+ * fetch (manifest exchange, health probes) and prompter (non-LLM fallback
+ * entry) as they need them; preflight needs neither. */
+export interface OnboardAdapters {
+  /** HTTP seam (GitHub App manifest exchange, health endpoints, …). */
+  fetch: typeof fetch;
+  runner: ProcessRunner;
+  clock: () => Date;
+  /** Interactive fallback question seam. pi is the normal prompter — steps
+   * driven from the pi session get their answers as tool inputs instead. */
+  prompter?: (question: string) => Promise<string>;
+  /** Deterministic host facts, captured once by the real assembly so steps
+   * never read process globals themselves. `uid` is null where the platform
+   * has no uid (Windows). `inContainer`: the wizard is running inside a
+   * container (the release image), where there is no Docker to drive —
+   * bring-up then prints the host's commands instead. */
+  host: { nodeVersion: string; uid: number | null; inContainer?: boolean };
+  /** Filesystem roots. `stateDir` is `<sandbox root>/state`; `configPath` is
+   * the live config.toml as the install locator resolved it — the
+   * one file every step reads and writes, captured once by the real assembly
+   * so no step builds a config path itself. */
+  paths: { stateDir: string; configPath: string };
+  log?: (line: string) => void;
+}
+
+// ---- step vocabulary --------------------------------------------------------
+
+export interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+/** What run() and verify() both return. `data` (run only) is persisted onto
+ * the step's checklist record and handed back as ctx.data on later calls. */
+export interface StepReport {
+  ok: boolean;
+  checks: CheckResult[];
+  data?: Record<string, unknown>;
+}
+
+export interface StepContext {
+  adapters: OnboardAdapters;
+  /** The tool call's inputs — the operator's answer to a step that asks one
+   * (`{}` for a step that declares no `parameters`, and always on verify()).
+   * A step that needs an answer and does not get one must return a refusal
+   * naming the options, never a guess: the wizard offers, the operator picks. */
+  input: Readonly<Record<string, unknown>>;
+  /** Recorded operator choices (topology, auth route, captured uid, …). */
+  choices: Readonly<Record<string, unknown>>;
+  /** This step's persisted data from a previous run ({} on first run). */
+  data: Readonly<Record<string, unknown>>;
+  /** Record an operator choice / derived fact for later steps (persisted with
+   * the step result). */
+  recordChoice(key: string, value: unknown): void;
+}
+
+/**
+ * One onboarding step (the registered set is defaultSteps in
+ * src/onboard/steps/index.ts); the interface is the extension point:
+ *   - `id` must be tool-name-safe ([a-z][a-z0-9_]*) — the pi extension
+ *     registers each step as tool `onboard_<id>`;
+ *   - `explain` is the teach-text the guide relays before running the step;
+ *   - `enabled` gates on recorded choices (e.g. the VM route's steps are
+ *     disabled on the laptop topology); absent ⇒ always enabled;
+ *   - `run` performs the step; `verify` re-checks its outcome against reality
+ *     and must be safe to call any number of times.
+ */
+export interface OnboardingStep {
+  id: string;
+  title: string;
+  explain: string;
+  /** Ascending display/registration order. */
+  order: number;
+  /** JSON-schema object the step's pi tool declares, for steps that need the
+   * operator's answer (a choice, a hostname). Absent ⇒ the tool takes no
+   * input, which is the common case. */
+  parameters?: unknown;
+  enabled?(choices: Readonly<Record<string, unknown>>): boolean;
+  run(ctx: StepContext): Promise<StepReport>;
+  verify(ctx: StepContext): Promise<StepReport>;
+}
+
+export function failures(checks: readonly CheckResult[]): string[] {
+  return checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
+}
+
+// ---- checklist file ---------------------------------------------------------
+
+export const CHECKLIST_VERSION = 1;
+
+export interface StepRecord {
+  status: "pending" | "done";
+  completed_at: string | null;
+  /** Last successful re-verification (resume / finish). */
+  verified_at: string | null;
+  /** Why a claimed-done step was demoted, or other engine notes. */
+  note: string | null;
+  data: Record<string, unknown>;
+}
+
+export interface ChecklistFile {
+  version: number;
+  created_at: string;
+  updated_at: string;
+  /** Set exactly once, by finish() when every enabled step verifies green.
+   * History — when onboarding first finished; it never moves and never clears. */
+  completed_at: string | null;
+  /** When a completed checklist stopped verifying (a demotion, a failed run,
+   * a refused finish, a newly-enabled unfinished step, a step run again —
+   * a run changes what the full verification checked); null/absent while the
+   * completion still holds. A green finish() clears it. Whether onboarding is
+   * complete now is `completed_at` set and this unset. */
+  reopened_at?: string | null;
+  choices: Record<string, unknown>;
+  steps: Record<string, StepRecord>;
+}
+
+export function checklistPath(stateDir: string): string {
+  return join(stateDir, "onboarding", "checklist.json");
+}
+
+/** The first-run contract path: the companion's first-run greeting keys off this
+ * file. Written once, by finish(), shape {"completed_at": "<iso>"}. */
+export function firstRunMarkerPath(stateDir: string): string {
+  return join(stateDir, "companion", "first-run.json");
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Read the checklist; null when absent or unreadable (both mean "fresh"). */
+export function readChecklist(stateDir: string): ChecklistFile | null {
+  const path = checklistPath(stateDir);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (typeof raw !== "object" || raw === null) return null;
+    const file = raw as ChecklistFile;
+    // Every field the engine dereferences is checked here: a file that parses
+    // but lacks one (hand-edited, foreign) would otherwise throw out of a
+    // step predicate or record() on every call — a wedge, not a fresh start.
+    if (typeof file.version !== "number") return null;
+    if (!isPlainObject(file.choices)) return null;
+    if (file.completed_at !== null && typeof file.completed_at !== "string") return null;
+    if (!isPlainObject(file.steps)) return null;
+    for (const rec of Object.values(file.steps)) {
+      if (!isPlainObject(rec) || !isPlainObject(rec.data)) return null;
+    }
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/** Does the checklist file say onboarding finished? The CLI's post-exit
+ * handoff reads exactly this (the finish tool only sets it after a full green
+ * re-verification, so "the file says so" is a verified claim). */
+export function checklistComplete(stateDir: string): boolean {
+  const file = readChecklist(stateDir);
+  return file !== null && completeNow(file);
+}
+
+/** Is onboarding complete NOW: finished once, and not reopened since. The one
+ * reading of the two fields, for the file on disk and the engine's copy. */
+function completeNow(file: Pick<ChecklistFile, "completed_at" | "reopened_at">): boolean {
+  return typeof file.completed_at === "string" && !file.reopened_at;
+}
+
+/** `<sandbox root>` — the parent of `paths.stateDir`, by the adapters'
+ * contract (stateDir = `<sandbox root>/state`). The one place that says so. */
+export function sandboxRoot(paths: { readonly stateDir: string }): string {
+  return resolve(paths.stateDir, "..");
+}
+
+/** tmp+rename atomic write — the one writer every onboarding file write goes
+ * through (the checklist, config.toml, .env, the inventory): a reader, the
+ * daemon's own loader one bind mount away included, never sees a half-written
+ * file, and an interrupted write leaves the previous file whole. */
+export function writeAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${basename(path)}.onboard.tmp`);
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+/** A file's text, or null when it cannot be read for any reason. For a read
+ * where only ABSENCE may be null, read it yourself. */
+export function readTextOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// ---- engine -----------------------------------------------------------------
+
+export interface StepStatusLine {
+  id: string;
+  title: string;
+  explain: string;
+  status: "pending" | "done" | "disabled";
+  note: string | null;
+}
+
+export interface ReconcileReport {
+  /** Claimed-done steps whose verify() held. */
+  verified: string[];
+  /** Claimed-done steps whose verify() failed — demoted to pending. */
+  demoted: Array<{ id: string; failures: string[] }>;
+}
+
+export interface StepRunResult {
+  id: string;
+  ok: boolean;
+  checks: CheckResult[];
+  failures: string[];
+}
+
+export interface VerifyAllResult {
+  ok: boolean;
+  results: Array<{ id: string; ok: boolean; failures: string[] }>;
+}
+
+export type FinishResult =
+  | { ok: true; completed_at: string; marker_written: boolean }
+  | { ok: false; results: VerifyAllResult["results"] };
+
+export class OnboardingEngine {
+  private readonly registry: OnboardingStep[];
+  private checklist: ChecklistFile;
+
+  constructor(
+    steps: OnboardingStep[],
+    private readonly adapters: OnboardAdapters,
+  ) {
+    this.registry = [...steps].sort((a, b) => a.order - b.order);
+    const loaded = readChecklist(adapters.paths.stateDir);
+    if (loaded === null && existsSync(checklistPath(adapters.paths.stateDir))) {
+      adapters.log?.(
+        "onboarding: checklist file unreadable — starting fresh (recorded choices and step progress were reset)",
+      );
+    }
+    this.checklist = loaded ?? this.fresh();
+  }
+
+  private fresh(): ChecklistFile {
+    const now = this.adapters.clock().toISOString();
+    return {
+      version: CHECKLIST_VERSION,
+      created_at: now,
+      updated_at: now,
+      completed_at: null,
+      choices: {},
+      steps: {},
+    };
+  }
+
+  private save(): void {
+    this.checklist.updated_at = this.adapters.clock().toISOString();
+    writeAtomic(
+      checklistPath(this.adapters.paths.stateDir),
+      `${JSON.stringify(this.checklist, null, 2)}\n`,
+    );
+  }
+
+  private record(id: string): StepRecord {
+    const existing = this.checklist.steps[id];
+    if (existing) return existing;
+    const created: StepRecord = {
+      status: "pending",
+      completed_at: null,
+      verified_at: null,
+      note: null,
+      data: {},
+    };
+    this.checklist.steps[id] = created;
+    return created;
+  }
+
+  private ctxFor(id: string, input: Record<string, unknown> = {}): StepContext {
+    return {
+      adapters: this.adapters,
+      input,
+      choices: this.checklist.choices,
+      data: this.record(id).data,
+      recordChoice: (key, value) => {
+        this.checklist.choices[key] = value;
+      },
+    };
+  }
+
+  /** The registered steps, in order (the pi tools register off this). */
+  stepDefs(): readonly OnboardingStep[] {
+    return this.registry;
+  }
+
+  private enabled(step: OnboardingStep): boolean {
+    return step.enabled ? step.enabled(this.checklist.choices) : true;
+  }
+
+  choices(): Readonly<Record<string, unknown>> {
+    return this.checklist.choices;
+  }
+
+  isComplete(): boolean {
+    return completeNow(this.checklist);
+  }
+
+  /** A completed checklist no longer verifies: withdraw the current-completion
+   * claim (the post-exit handoff reads it) without touching the history. */
+  private reopen(): void {
+    if (this.checklist.completed_at === null || this.checklist.reopened_at) return;
+    this.checklist.reopened_at = this.adapters.clock().toISOString();
+  }
+
+  list(): StepStatusLine[] {
+    return this.registry.map((step) => {
+      const rec = this.checklist.steps[step.id];
+      return {
+        id: step.id,
+        title: step.title,
+        explain: step.explain,
+        status: this.enabled(step) ? (rec?.status ?? "pending") : "disabled",
+        note: rec?.note ?? null,
+      };
+    });
+  }
+
+  /**
+   * Resume: re-verify every enabled claimed-done step against reality. A step
+   * whose verify() fails is demoted to pending with the failures in its note —
+   * the file's claim is never trusted alone. A fully-done checklist therefore
+   * re-runs as verify-only. Persists once at the end.
+   */
+  async reconcile(): Promise<ReconcileReport> {
+    const report: ReconcileReport = { verified: [], demoted: [] };
+    for (const step of this.registry) {
+      if (!this.enabled(step)) continue;
+      const rec = this.checklist.steps[step.id];
+      if (!rec || rec.status !== "done") {
+        this.reopen();
+        continue;
+      }
+      const outcome = await this.safeVerify(step);
+      if (outcome.ok) {
+        rec.verified_at = this.adapters.clock().toISOString();
+        report.verified.push(step.id);
+      } else {
+        const fails = failures(outcome.checks);
+        rec.status = "pending";
+        rec.note = `re-verification failed: ${fails.join("; ") || "unknown"}`;
+        this.reopen();
+        report.demoted.push({ id: step.id, failures: fails });
+      }
+    }
+    this.save();
+    return report;
+  }
+
+  /** Run one step, optionally with the operator's answer (`input`, the pi
+   * tool's params). Unknown/disabled ids are refusals-as-answers, never
+   * throws (the caller is an LLM tool belt). Persists after the step. */
+  async runStep(id: string, input: Record<string, unknown> = {}): Promise<StepRunResult> {
+    const step = this.registry.find((s) => s.id === id);
+    if (!step) {
+      return {
+        id,
+        ok: false,
+        checks: [],
+        failures: [`unknown step "${id}" — known: ${this.registry.map((s) => s.id).join(", ")}`],
+      };
+    }
+    if (!this.enabled(step)) {
+      return {
+        id,
+        ok: false,
+        checks: [],
+        failures: [`step "${id}" is disabled by the recorded choices`],
+      };
+    }
+    const rec = this.record(id);
+    rec.status = "pending";
+    this.reopen();
+    this.save();
+    let report: StepReport;
+    try {
+      report = await step.run(this.ctxFor(id, input));
+    } catch (err) {
+      report = {
+        ok: false,
+        checks: [{ name: id, ok: false, detail: `step threw: ${String(err)}` }],
+      };
+    }
+    if (report.data) rec.data = { ...rec.data, ...report.data };
+    if (report.ok) {
+      rec.status = "done";
+      rec.completed_at = this.adapters.clock().toISOString();
+      rec.verified_at = null;
+      rec.note = null;
+      // A run acts on the installation (choices, config, deploys) after the
+      // full verification that backed the completion claim: only the next
+      // green finish() may make that claim again.
+      this.reopen();
+    } else {
+      rec.status = "pending";
+      rec.note = `last run failed: ${failures(report.checks).join("; ") || "unknown"}`;
+      this.reopen();
+    }
+    this.save();
+    return { id, ok: report.ok, checks: report.checks, failures: failures(report.checks) };
+  }
+
+  private async safeVerify(step: OnboardingStep): Promise<StepReport> {
+    try {
+      return await step.verify(this.ctxFor(step.id));
+    } catch (err) {
+      return {
+        ok: false,
+        checks: [{ name: step.id, ok: false, detail: `verify threw: ${String(err)}` }],
+      };
+    }
+  }
+
+  /**
+   * Verify every enabled step — done or not. A pending step whose verify()
+   * holds is promoted to done (its outcome exists in reality, which is the
+   * only truth the checklist mirrors); a done step whose verify() fails
+   * reports red here (finish refuses) but demotion is reconcile()'s job.
+   */
+  async verifyAll(): Promise<VerifyAllResult> {
+    const results: VerifyAllResult["results"] = [];
+    for (const step of this.registry) {
+      if (!this.enabled(step)) continue;
+      const outcome = await this.safeVerify(step);
+      const rec = this.record(step.id);
+      if (outcome.ok) {
+        rec.verified_at = this.adapters.clock().toISOString();
+        if (rec.status !== "done") {
+          rec.status = "done";
+          rec.completed_at = rec.completed_at ?? rec.verified_at;
+          rec.note = "verified green without a recorded run";
+        }
+      }
+      results.push({ id: step.id, ok: outcome.ok, failures: failures(outcome.checks) });
+    }
+    this.save();
+    return { ok: results.every((r) => r.ok), results };
+  }
+
+  /**
+   * The finish tool's engine half: re-run the full verification checklist.
+   * Anything red ⇒ refuse with the failures (the caller returns them as the
+   * tool result and does not exit). All green ⇒ mark the checklist complete
+   * and write the first-run marker — once: a marker already on disk is left
+   * untouched, so the completed_at the companion greets on never moves.
+   */
+  async finish(): Promise<FinishResult> {
+    const all = await this.verifyAll();
+    if (!all.ok) {
+      this.reopen();
+      this.save();
+      return { ok: false, results: all.results };
+    }
+    const completedAt = this.checklist.completed_at ?? this.adapters.clock().toISOString();
+    this.checklist.completed_at = completedAt;
+    this.checklist.reopened_at = null;
+    this.save();
+    const marker = firstRunMarkerPath(this.adapters.paths.stateDir);
+    let markerWritten = false;
+    if (!existsSync(marker)) {
+      writeAtomic(marker, `${JSON.stringify({ completed_at: completedAt })}\n`);
+      markerWritten = true;
+    }
+    return { ok: true, completed_at: completedAt, marker_written: markerWritten };
+  }
+}

package/src/onboard/launch.ts

@@ -0,0 +1,115 @@
+// `qcr onboard` mechanics: launch pi at the pinned version via npx
+// (pi stays a non-dependency — this works from a bare clone with only Node and
+// the checkout), hand it the onboarding system prompt + exactly one onboarding
+// extension + a restricted built-in tool set, and on exit either exec the TUI
+// (checklist complete) or say how to resume.
+//
+// Everything effectful is injected (spawn, completion read, log), so tests
+// drive the whole flow with fakes; src/cli.ts cmdOnboard is the one real
+// assembly.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface PiPin {
+  package: string;
+  version: string;
+}
+
+/** The pin from package.json's "qcrPi" block — the mirror that exists on a bare
+ * public clone, where config.toml does not (the wizard writes it later).
+ * config.toml [pi] stays the preferred source when it loads (cmdOnboard tries
+ * it first); both mirror the same pinned version by rule 7's discipline. */
+export function piPinFromPackageJson(
+  root: string,
+  readFile: (p: string) => string = (p) => readFileSync(p, "utf8"),
+): PiPin | null {
+  try {
+    const pkg = JSON.parse(readFile(join(root, "package.json"))) as {
+      qcrPi?: { package?: unknown; version?: unknown };
+    };
+    const pi = pkg.qcrPi;
+    if (pi && typeof pi.package === "string" && typeof pi.version === "string") {
+      return { package: pi.package, version: pi.version };
+    }
+  } catch {
+    // fall through — the caller reports the missing pin
+  }
+  return null;
+}
+
+/** Dedicated onboarding session store — never the reviewer/companion dirs, so
+ * onboarding cannot pollute (or be polluted by) any other pi session store. */
+export function onboardingSessionDir(root: string): string {
+  return join(root, "state", "onboarding", "pi-sessions");
+}
+
+/**
+ * The full npx argv for the onboarding pi session.
+ *
+ * `--approve` is the same never-block-on-input rule as buildPiCommand
+ * (src/sessions.ts) and the companion's piArgv: the wizard must never stall
+ * on pi's interactive "Trust project folder?" modal.
+ *
+ * VERIFY-ON-PIN: `--no-extensions`, `--no-skills`, `--no-context-files`,
+ * `-e <path>` and `--tools <list>` against the pinned pi version's --help —
+ * the intent (no ambient extensions, exactly one onboarding extension, a
+ * read-only built-in belt) is the design decision; the exact flag spellings
+ * are unverified statically and belong to the named onboarding smoke step.
+ */
+export function onboardingPiArgv(pin: PiPin, root: string): string[] {
+  return [
+    "npx",
+    "-y",
+    `${pin.package}@${pin.version}`,
+    "--approve",
+    "--no-extensions",
+    "--no-skills",
+    "--no-context-files",
+    "-e",
+    join(root, "extensions", "cli", "onboarding.ts"),
+    "--system-prompt",
+    join(root, "prompts", "onboarding.md"),
+    "--tools",
+    "read,ls,grep",
+    "--session-dir",
+    onboardingSessionDir(root),
+  ];
+}
+
+export interface OnboardRunDeps {
+  pin: PiPin;
+  root: string;
+  /** Spawn with stdio inherited; resolves with the exit code (a spawn failure
+   * is a nonzero code, never a throw). */
+  spawn(cmd: string, args: string[]): Promise<number>;
+  /** Does the checklist file say every step verified? (engine.checklistComplete
+   * over state/ — the finish tool only sets the flag after a green re-verify.) */
+  isComplete(): boolean;
+  log(line: string): void;
+  /** Compiled CLI path for the TUI handoff (dist/src/cli.js). */
+  cliPath: string;
+  /** Node binary for the handoff; defaults to the running one. */
+  nodeBin?: string;
+}
+
+/**
+ * Run the onboarding session and handle the handoff:
+ *   - checklist complete after pi exits ⇒ open the TUI (same stdio);
+ *   - otherwise print how to resume — `qcr onboard` again re-verifies
+ *     completed steps and continues at the first unfinished one.
+ */
+export async function runOnboard(deps: OnboardRunDeps): Promise<number> {
+  const argv = onboardingPiArgv(deps.pin, deps.root);
+  deps.log(
+    `onboarding: launching pi ${deps.pin.package}@${deps.pin.version} via npx (first run downloads it — give it a moment)`,
+  );
+  const code = await deps.spawn(argv[0]!, argv.slice(1));
+  if (deps.isComplete()) {
+    deps.log("onboarding: checklist verified complete — opening the TUI.");
+    return deps.spawn(deps.nodeBin ?? process.execPath, [deps.cliPath, "tui"]);
+  }
+  deps.log(
+    "onboarding: not finished yet. Run `qcr onboard` again to resume — completed steps are re-verified, not repeated.",
+  );
+  return code;
+}