@quickchatai/quickreview 1.1.0 → 1.2.0

package/src/onboard/choices.ts

@@ -41,6 +41,12 @@ export type IngressChoice = (typeof INGRESS_CHOICES)[number];
 export const AUTH_ROUTES = ["oauth", "api"] as const;
 export type AuthRoute = (typeof AUTH_ROUTES)[number];
 
+/** How the daemon authenticates to GitHub (`config.toml [github] auth`):
+ * "user" is the person's own account (polling only, no App), "app" a GitHub
+ * App. Answered as the github_account step's input; absent ⇒ unanswered. */
+export const GITHUB_AUTH_CHOICES = ["user", "app"] as const;
+export type GithubAuth = (typeof GITHUB_AUTH_CHOICES)[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._-]+)$/;
@@ -71,6 +77,20 @@ export const CHOICE_KEYS = {
   /** `AuthRoute`. Written by the LLM step; read by the interview's shape line. */
   authRoute: "llm_auth_route",
 
+  /** `GithubAuth`. Written by the github_account step (the operator's answer,
+   * defaulted to "user" where `gh auth token` works); read by everything that
+   * differs between the own-account route and the App route — which of
+   * github_account / github_app / app_slug_reconcile is enabled, the
+   * interview's App questions, the ingress shapes on offer, verification. */
+  githubAuth: "github_auth",
+  /** The person's GitHub login, from `GET /user` with their own token (own-
+   * account route). The interview's owner-login answer and `[github]
+   * bot_login` both come from it. */
+  accountLogin: "github_account_login",
+  /** "owner/name" the person picked from the repos their account reaches
+   * (own-account route). The interview reads it as its repo answer. */
+  accountRepo: "github_account_repo",
+
   /** "owner/name" of the reviewed repo. Written by the interview; read by the
    * GitHub App step and the proof round. */
   repo: "reviewed_repo",
@@ -144,6 +164,9 @@ export type ChoiceKey = (typeof CHOICE_KEYS)[ChoiceName];
  */
 export const CHOICE_WRITERS: Record<ChoiceName, readonly string[]> = {
   uid: ["preflight"],
+  githubAuth: ["github_account"],
+  accountLogin: ["github_account"],
+  accountRepo: ["github_account"],
   topology: ["topology"],
   sshAlias: ["topology"],
   sshUser: ["ssh_preflight"],
@@ -158,7 +181,7 @@ export const CHOICE_WRITERS: Record<ChoiceName, readonly string[]> = {
   dryRun: ["config_fill"],
   labels: ["config_fill"],
   appSlug: ["config_fill", "github_app", "app_slug_reconcile"],
-  botLogin: ["github_app", "app_slug_reconcile"],
+  botLogin: ["github_account", "github_app", "app_slug_reconcile"],
   appId: ["github_app"],
   appTarget: ["github_app"],
   appName: ["github_app"],
@@ -216,6 +239,16 @@ export function authRouteOf(choices: Readonly<Record<string, unknown>>): AuthRou
   return memberOf(AUTH_ROUTES, raw(choices, CHOICE_KEYS.authRoute));
 }
 
+/** The recorded GitHub auth route, or null while unanswered. */
+export function githubAuthOf(choices: Readonly<Record<string, unknown>>): GithubAuth | null {
+  return memberOf(GITHUB_AUTH_CHOICES, raw(choices, CHOICE_KEYS.githubAuth));
+}
+
+/** Is the own-account route recorded? (Unanswered is NOT user mode.) */
+export function userAuthRecorded(choices: Readonly<Record<string, unknown>>): boolean {
+  return githubAuthOf(choices) === "user";
+}
+
 /** 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));

package/src/onboard/engine.ts

@@ -19,6 +19,7 @@
 // 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 type { StepForward, StepForwardRequest } from "./stepforward.js";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 
@@ -60,6 +61,11 @@ export interface OnboardAdapters {
    * so no step builds a config path itself. */
   paths: { stateDir: string; configPath: string };
   log?: (line: string) => void;
+  /** Opens the local memory forward for one step call (src/onboard/stepforward.ts):
+   * the compose route's memory engine is reachable from this machine only
+   * through it. The real assembly sets it; absent (every test), no forward is
+   * opened and the step sees whatever already listens. */
+  memoryForward?: (req: StepForwardRequest) => Promise<StepForward | null>;
 }
 
 // ---- step vocabulary --------------------------------------------------------
@@ -116,6 +122,10 @@ export interface OnboardingStep {
    * input, which is the common case. */
   parameters?: unknown;
   enabled?(choices: Readonly<Record<string, unknown>>): boolean;
+  /** After setup: the step still runs and verifies like any other, but the
+   * checklist completes without it — finish never waits on it. (The first
+   * review and the go-live flip: the board offers them once setup is done.) */
+  optional?: boolean;
   run(ctx: StepContext): Promise<StepReport>;
   verify(ctx: StepContext): Promise<StepReport>;
 }
@@ -242,6 +252,8 @@ export interface StepStatusLine {
   explain: string;
   status: "pending" | "done" | "disabled";
   note: string | null;
+  /** The step's `optional` flag: setup completes without it. */
+  optional?: boolean;
 }
 
 export interface ReconcileReport {
@@ -260,7 +272,8 @@ export interface StepRunResult {
 
 export interface VerifyAllResult {
   ok: boolean;
-  results: Array<{ id: string; ok: boolean; failures: string[] }>;
+  /** `optional` results are reported but never hold `ok` false. */
+  results: Array<{ id: string; ok: boolean; failures: string[]; optional?: boolean }>;
 }
 
 export type FinishResult =
@@ -364,6 +377,7 @@ export class OnboardingEngine {
         explain: step.explain,
         status: this.enabled(step) ? (rec?.status ?? "pending") : "disabled",
         note: rec?.note ?? null,
+        ...(step.optional ? { optional: true } : {}),
       };
     });
   }
@@ -483,10 +497,15 @@ export class OnboardingEngine {
           rec.note = "verified green without a recorded run";
         }
       }
-      results.push({ id: step.id, ok: outcome.ok, failures: failures(outcome.checks) });
+      results.push({
+        id: step.id,
+        ok: outcome.ok,
+        failures: failures(outcome.checks),
+        ...(step.optional ? { optional: true } : {}),
+      });
     }
     this.save();
-    return { ok: results.every((r) => r.ok), results };
+    return { ok: results.every((r) => r.ok || r.optional === true), results };
   }
 
   /**

package/src/onboard/launch.ts

@@ -7,35 +7,14 @@
 // 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";
+import { defaultSteps } from "./steps/index.js";
+import { onboardingToolAllowlist } from "./toolnames.js";
 
-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;
-}
+// The pin reader lives in a leaf module: src/version.ts (on the daemon's import
+// graph) needs it, and this module imports the whole step registry.
+export { piPinFromPackageJson, type PiPin } from "./pipin.js";
+import type { PiPin } from "./pipin.js";
 
 /** Dedicated onboarding session store — never the reviewer/companion dirs, so
  * onboarding cannot pollute (or be polluted by) any other pi session store. */
@@ -55,8 +34,17 @@ export function onboardingSessionDir(root: string): string {
  * 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.
+ *
+ * `--tools` is an allowlist over extension tools too (pi 1.4.0; pinned by
+ * tests/onboard-tools-sdk.test.ts on the real SDK), so it names every wizard
+ * tool, derived from the step registry: a step added there is active here
+ * with no second edit. bash, write and edit stay off it.
  */
-export function onboardingPiArgv(pin: PiPin, root: string): string[] {
+export function onboardingPiArgv(
+  pin: PiPin,
+  root: string,
+  stepIds: readonly string[] = defaultSteps().map((s) => s.id),
+): string[] {
   return [
     "npx",
     "-y",
@@ -70,7 +58,7 @@ export function onboardingPiArgv(pin: PiPin, root: string): string[] {
     "--system-prompt",
     join(root, "prompts", "onboarding.md"),
     "--tools",
-    "read,ls,grep",
+    onboardingToolAllowlist(stepIds).join(","),
     "--session-dir",
     onboardingSessionDir(root),
   ];

package/src/onboard/pipin.ts

@@ -0,0 +1,31 @@
+// The pinned pi version, read from package.json. A leaf: the daemon reaches it
+// through src/version.ts, so it imports nothing from the onboarding wizard.
+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;
+}

package/src/onboard/stepforward.ts

@@ -0,0 +1,61 @@
+// The memory forward, held open for ONE onboarding step call.
+//
+// On the compose route the memory engine listens only on its own container's
+// loopback; this machine reaches it through the memory forward, the same relay
+// the TUI runs in-process (src/tui/memforward.ts over
+// scripts/companion-memory-forward.mjs). The wizard runs before any TUI, so
+// without this the memory steps' phase B (minting the user keys, the
+// confinement matrix) found nothing listening and sent the operator to a
+// second terminal — and a wizard driven in order never got memory working.
+//
+// A forward that is already listening (`qcr tui`, the systemd unit) is
+// adopted and left alone; one this opens is closed when the step ends, so the
+// wizard leaves nothing running behind it. The real adapter assembly
+// (extensions/onboarding.ts) hands this to the steps; a test's adapters never
+// do, so no test binds a port.
+import { MemoryForward } from "../tui/memforward.js";
+
+export interface StepForwardRequest {
+  /** Where the step reaches memory (the forward's loopback listener). */
+  baseUrl: string;
+  /** The checkout holding scripts/. */
+  repoRoot: string;
+  /** The memory sidecar's container. */
+  container: string;
+  sudoDocker: boolean;
+  log?: (line: string) => void;
+}
+
+export interface StepForward {
+  /** true when this call started the forward (and stop() closes it). */
+  started: boolean;
+  detail: string;
+  stop(): void;
+}
+
+/** Open (or adopt) the local memory forward; null when none could be made to
+ * answer, with nothing left bound. */
+export async function openStepMemoryForward(
+  req: StepForwardRequest,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<StepForward | null> {
+  const forward = new MemoryForward({
+    baseUrl: req.baseUrl,
+    repoRoot: req.repoRoot,
+    env,
+    local: true,
+    sudoDocker: req.sudoDocker,
+    container: req.container,
+    ...(req.log ? { log: req.log } : {}),
+  });
+  const status = await forward.ensure();
+  if (status.state === "owned")
+    return {
+      started: true,
+      detail: `opened a memory forward to ${req.container} for this step; it closes when the step ends, and \`qcr tui\` runs its own`,
+      stop: () => forward.stop(),
+    };
+  if (status.state === "adopted") return { started: false, detail: status.detail, stop: () => {} };
+  forward.stop();
+  return null;
+}

package/src/onboard/steps/appslug.ts

@@ -50,7 +50,7 @@ import {
   tomlString,
   type TomlEdit,
 } from "./configfill.js";
-import { CHOICE_KEYS, botLoginFor } from "../choices.js";
+import { CHOICE_KEYS, botLoginFor, userAuthRecorded } from "../choices.js";
 import { api, readCredentials } from "./githubapp.js";
 
 export const APP_SLUG_STEP_ID = "app_slug_reconcile";
@@ -254,6 +254,9 @@ export function appSlugStep(opts: AppSlugStepOptions = {}): OnboardingStep {
       "slug, so this step asks the App itself who it is and corrects [github] app_slug and bot_login to match. It matters more " +
       "than it looks: bot_login is how the reviewer recognises its own reviews and comments, and a wrong one fails silently.",
     order: 65,
+    // There is no App slug on the own-account route: `[github] app_slug` is ""
+    // and bot_login is the person's login (the github_account step writes both).
+    enabled: (choices) => !userAuthRecorded(choices),
     async run(ctx): Promise<StepReport> {
       return reconcile(ctx, true);
     },

package/src/onboard/steps/compose.ts

@@ -74,6 +74,9 @@ export const MEMORY_IMAGE_REPO = "ghcr.io/quickchatai/quickreview-memory";
 
 export { CONTAINER_STATE_DIR };
 export const CONTAINER_DRYRUN_DIR = `${CONTAINER_STATE_DIR}/dryrun`;
+/** The daemon's command root in the release image (`<root>/commands`, with the
+ * root-sealed `operator/` under it and the result files in `results/`). */
+export const CONTAINER_COMMANDS_DIR = "/opt/qcr/commands";
 
 /** `<sandbox root>` — the engine's contract is stateDir = `<root>/state`. */
 export function rootOf(adapters: OnboardAdapters): string {
@@ -157,6 +160,12 @@ export function daemonExecArgs(root: string, argv: readonly string[]): string[]
   return composeArgs(root, ["exec", "-T", DAEMON_SERVICE, ...argv]);
 }
 
+/** The same exec as uid 0 — the operator seal on `commands/operator/`, which
+ * the daemon's own uid (every session's) can read but not write. */
+export function daemonRootExecArgs(root: string, argv: readonly string[]): string[] {
+  return composeArgs(root, ["exec", "-T", "-u", "0", DAEMON_SERVICE, ...argv]);
+}
+
 export async function daemonExec(
   runner: ProcessRunner,
   root: string,
@@ -172,9 +181,31 @@ export interface PsReport {
   detail: string;
 }
 
+/** docker-compose.yml's `name:` — the project label on its containers. */
+export const COMPOSE_PROJECT = "quickreview";
+
+/** `docker ps` over the compose project label, one compose-ps-shaped JSON row
+ * per running container: asks Docker without reading the compose file. */
+export function projectPsArgs(): string[] {
+  return [
+    "ps",
+    "--filter",
+    `label=com.docker.compose.project=${COMPOSE_PROJECT}`,
+    "--format",
+    '{"Service":"{{.Label "com.docker.compose.service"}}","State":"{{.State}}"}',
+  ];
+}
+
 export async function composePs(runner: ProcessRunner, root: string): Promise<PsReport> {
   const ps = await runner.run("docker", composeArgs(root, ["ps", "--format", "json"]));
   if (ps.code !== 0) {
+    // `docker compose ps` interpolates the compose file first, and before the
+    // bring-up has written the project .env (QCR_SECRETS_DIR and the rest) it
+    // refuses to run at all. That is a question about the file, not the
+    // stack: Docker itself still answers which of the project's containers
+    // run. Only when Docker cannot answer either is the state unknown.
+    const plain = await runner.run("docker", projectPsArgs());
+    if (plain.code === 0) return { ok: true, rows: parseComposePs(plain.stdout), detail: "" };
     return {
       ok: false,
       rows: [],