@quickchatai/quickreview 1.1.0 → 1.3.1

package/src/onboard/steps/githubapp.ts

@@ -48,7 +48,7 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { isAbsolute, join } from "node:path";
 import type { Socket } from "node:net";
 import { mintAppJwt } from "@quickchatai/pi-quickreview/src/githubAuth.js";
-import { CHOICE_KEYS, REPO_SLUG_RE, botLoginFor } from "../choices.js";
+import { CHOICE_KEYS, REPO_SLUG_RE, botLoginFor, userAuthRecorded } from "../choices.js";
 import { CONFIG_FILL_STEP_ID } from "./configfill.js";
 import { readTomlKey, secretsDirFor } from "./ingress.js";
 import {
@@ -416,9 +416,54 @@ export interface CallbackServerOptions {
   page: (bound: { url: string; redirectUrl: string }) => string;
   state: string;
   /** Preferred loopback port; a busy port falls back to an ephemeral one and
-   * the manifest's redirect_url follows the port actually bound. */
+   * the manifest's redirect_url follows the port actually bound — except
+   * behind a `hosted` origin, where the port is strict. */
   port: number;
   timeoutMs: number;
+  /** A hosted setup (`QCR_ONBOARD_PUBLIC_ORIGIN`): a reverse proxy forwards
+   * this public https origin to the loopback listener on `port`. */
+  hosted?: HostedCallback;
+}
+
+/** The hosted callback's shape: GitHub redirects to `<origin>/manifest-callback`,
+ * the operator opens `pageUrl`, and the proxy's Host header is admitted. */
+export interface HostedCallback {
+  /** `https://host[:port]`, no path. */
+  origin: string;
+  /** The page URL the operator is told to open (default: the origin). */
+  pageUrl: string;
+}
+
+/** The env knobs of a hosted setup. Total: an unusable origin is a refusal
+ * with its reason, never a silent fallback to loopback. */
+export function hostedCallbackFromEnv(env: NodeJS.ProcessEnv): {
+  hosted?: HostedCallback;
+  problem?: string;
+} {
+  const raw = (env["QCR_ONBOARD_PUBLIC_ORIGIN"] ?? "").trim();
+  if (raw === "") return {};
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return {
+      problem: `QCR_ONBOARD_PUBLIC_ORIGIN=${raw} is not a URL — set an https origin like https://<public host>`,
+    };
+  }
+  if (
+    u.protocol !== "https:" ||
+    u.username ||
+    u.password ||
+    (u.pathname !== "/" && u.pathname !== "") ||
+    u.search ||
+    u.hash
+  )
+    return {
+      problem: `QCR_ONBOARD_PUBLIC_ORIGIN=${raw} must be a bare https origin (https://host[:port], no path) — GitHub redirects to <origin>${CALLBACK_PATH}`,
+    };
+  const origin = u.origin;
+  const page = (env["QCR_ONBOARD_SETUP_URL"] ?? "").trim();
+  return { hosted: { origin, pageUrl: page !== "" ? page : `${origin}/` } };
 }
 
 export type CallbackServerFactory = (o: CallbackServerOptions) => Promise<CallbackListener>;
@@ -516,13 +561,30 @@ export const nodeCallbackServer: CallbackServerFactory = async (o) => {
   let port: number;
   try {
     port = await listen(o.port);
-  } catch {
+  } catch (err) {
+    // Behind a hosted origin the proxy forwards to exactly this port, so
+    // another one would be a listener nothing reaches: refuse, and say so.
+    if (o.hosted)
+      throw new Error(
+        `port ${o.port} is busy, and the hosted callback (${o.hosted.origin} → 127.0.0.1:${o.port}) needs exactly ` +
+          `that port — stop whatever holds it and run the step again (${String(err instanceof Error ? err.message : err)})`,
+        { cause: err },
+      );
     port = await listen(0); // preferred port busy — any loopback port will do
   }
 
   allowedHosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
-  const url = `http://127.0.0.1:${port}/`;
-  const redirectUrl = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+  let url = `http://127.0.0.1:${port}/`;
+  let redirectUrl = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+  if (o.hosted) {
+    // The proxy's own Host header is the public one: admitted by name, with
+    // and without the scheme's default port, alongside loopback.
+    const pub = new URL(o.hosted.origin);
+    allowedHosts.add(pub.host.toLowerCase());
+    if (pub.port === "") allowedHosts.add(`${pub.hostname.toLowerCase()}:443`);
+    url = o.hosted.pageUrl;
+    redirectUrl = `${o.hosted.origin}${CALLBACK_PATH}`;
+  }
   html = o.page({ url, redirectUrl });
 
   const timer = setTimeout(
@@ -720,7 +782,7 @@ export async function findInstallation(
   };
 }
 
-async function installationToken(
+export async function installationToken(
   fetchFn: typeof fetch,
   apiBase: string,
   jwt: string,
@@ -851,6 +913,9 @@ export interface GithubAppStepOptions {
   randomToken?: (bytes: number) => string;
   /** Try to open the operator's browser at the page (best effort, never fatal). */
   openBrowser?: boolean;
+  /** Env for the hosted-callback knobs (`QCR_ONBOARD_PUBLIC_ORIGIN`,
+   * `QCR_ONBOARD_SETUP_URL`); default the process env. */
+  env?: NodeJS.ProcessEnv;
 }
 
 interface Resolved {
@@ -863,8 +928,18 @@ interface Resolved {
 }
 
 function resolveLabels(ctx: StepContext): Resolved["labels"] {
-  const config = readTextOrNull(ctx.adapters.paths.configPath);
-  const recorded = (ctx.choices[CHOICE_KEYS.labels] ?? {}) as Partial<
+  return labelSpecs(readTextOrNull(ctx.adapters.paths.configPath), ctx.choices);
+}
+
+/** The three trigger/status labels this installation means — config.toml
+ * first, then the names the interview recorded, then the shipped defaults —
+ * with the colour and description the wizard creates them with. Shared with
+ * the own-account step, which creates the same labels with the person's token. */
+export function labelSpecs(
+  config: string | null,
+  choices: Readonly<Record<string, unknown>>,
+): Array<{ name: string; color: string; description: string }> {
+  const recorded = (choices[CHOICE_KEYS.labels] ?? {}) as Partial<
     Record<keyof typeof DEFAULT_LABELS, unknown>
   >;
   return LABEL_META.map((meta) => {
@@ -1148,12 +1223,17 @@ export function githubAppStep(opts: GithubAppStepOptions = {}): OnboardingStep {
     // The page can only be rendered once the port is known (the manifest's
     // redirect_url must name the port actually bound), so the listener builds
     // it from its own bound address.
+    const hostedEnv = hostedCallbackFromEnv(opts.env ?? process.env);
+    if (hostedEnv.problem) {
+      return [{ name: "callback listener", ok: false, detail: hostedEnv.problem }];
+    }
     let listener: CallbackListener;
     try {
       listener = await serve({
         state,
         port: opts.callbackPort ?? DEFAULT_CALLBACK_PORT,
         timeoutMs: callbackTimeoutMs,
+        ...(hostedEnv.hosted ? { hosted: hostedEnv.hosted } : {}),
         page: (bound) =>
           manifestPageHtml({
             postUrl: appCreationUrl(target, r.githubBase),
@@ -1319,6 +1399,10 @@ export function githubAppStep(opts: GithubAppStepOptions = {}): OnboardingStep {
     // ingress step (39), whose recorded webhook URL goes into the manifest;
     // before the bring-up steps.
     order: 40,
+    // The App route only. The own-account route (github_account, order 33)
+    // needs no App at all; an unanswered route keeps this step, so a
+    // checklist from before the question existed still verifies its App.
+    enabled: (choices) => !userAuthRecorded(choices),
     // The reviewed repo is NOT a parameter: it is the interview's answer, read
     // from the checklist (CHOICE_KEYS.repo). The only thing the operator may
     // supply here is what nothing else can derive — the App's display name.

package/src/onboard/steps/golive.ts

@@ -267,6 +267,8 @@ export function goLiveStep(opts: GoLiveStepOptions = {}): OnboardingStep {
       'arguments to get the explanation to read out; then call it again with decision: "stay_dry_run", or with ' +
       `decision: "go_live" AND confirm: "${GO_LIVE_CONFIRMATION}" if — and only if — they said so explicitly.`,
     order: 78,
+    // After setup: the board offers it; finish never waits on it.
+    optional: true,
     parameters: {
       type: "object",
       properties: {

package/src/onboard/steps/index.ts

@@ -7,6 +7,7 @@ import { bringUpStep } from "./bringup.js";
 import { configFillStep } from "./configfill.js";
 import { embeddingsStep } from "./embeddings.js";
 import { escalationStep } from "./escalation.js";
+import { githubAccountStep } from "./githubaccount.js";
 import { githubAppStep } from "./githubapp.js";
 import { goLiveStep } from "./golive.js";
 import { ingressStep } from "./ingress.js";
@@ -38,6 +39,12 @@ export function defaultSteps(): OnboardingStep[] {
   //   ssh_preflight (22) VM only, and FIRST on that route: the alias, the
   //                      agent and the passphrase trap, before anything is
   //                      minted, written or deployed;
+  //
+  // The GitHub route split is the second question, asked by github_account
+  // (33): "user" (the person's own account — token file, polling, no App) or
+  // "app". Once answered, exactly one of github_account (33) / github_app (40)
+  // is enabled, and app_slug_reconcile (65) runs only on the App route.
+  //
   //   vm_inventory (68)  VM only: the deploy inventory, from the answers;
   //   vm_deploy (71)     VM only: `scripts/deploy.sh`, composed, with every
   //                      preflight it has — the peer of bringup (70), which is
@@ -51,6 +58,10 @@ export function defaultSteps(): OnboardingStep[] {
     topologyStep(),
     sshPreflightStep(),
     llmAuthStep(),
+    // github_account (33) before the interview (35): the interview asks the
+    // App questions only on the App route, and takes the repo and login the
+    // own-account route already settled.
+    githubAccountStep(),
     configFillStep(),
     escalationStep(),
     embeddingsStep(),

package/src/onboard/steps/ingress.ts

@@ -18,11 +18,18 @@
 //           permanent hostname (the VM route's default). No rotation, so no
 //           self-heal: `[ingress] shape = "none"` and `[server] hostname`
 //           carries the name.
-//   polling No tunnel at all. The reconcile poll becomes the ONLY trigger
-//           path, at `[daemon] poll_interval_s`. What degrades is stated
-//           plainly in the step's own output (author-reply routing and the
-//           [feedback] loop are webhook-only), and the tunnel is offered as a
-//           later upgrade — re-running this step is the upgrade.
+//   polling No tunnel at all — THE DEFAULT on every route, and the only
+//           shape the own-account route (`[github] auth = "user"`) allows.
+//           `[ingress] shape = "polling"`. The reconcile poll becomes the ONLY
+//           trigger path, at `[daemon] poll_interval_s`. What degrades is
+//           stated plainly in the step's own output (author-reply routing and
+//           the [feedback] loop are webhook-only), and the tunnel is offered
+//           as a later upgrade — re-running this step is the upgrade.
+//
+// Called with no choice and none recorded, the step applies the default
+// (polling) and says so in one plain line, with the other shapes listed as
+// the later upgrade: a stated default is not a guess, and nothing about it is
+// irreversible.
 //
 // The step is deliberately self-contained: it owns the `[ingress]` section of
 // config.toml, the project `.env`'s COMPOSE_PROFILES line, and nothing else.
@@ -33,7 +40,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { INGRESS_DEFAULTS } from "../../config.js";
 import { locateSecrets } from "../../install.js";
-import { CHOICE_KEYS, INGRESS_CHOICES, type IngressChoice } from "../choices.js";
+import { CHOICE_KEYS, INGRESS_CHOICES, userAuthRecorded, type IngressChoice } from "../choices.js";
 import { topologyOf } from "./topology.js";
 import {
   readTextOrNull,
@@ -67,7 +74,7 @@ export interface IngressOption {
   /** Honest trade-offs — the good and the bad, in the operator's words. */
   tradeoffs: string[];
   /** `[ingress] shape` this choice configures. */
-  shape: "tunnel-file" | "none";
+  shape: "tunnel-file" | "none" | "polling";
   /** COMPOSE_PROFILES value ("" ⇒ no sidecar at all). */
   profile: string;
   /** Secrets-dir file this choice requires, if any. */
@@ -78,7 +85,7 @@ export interface IngressOption {
 
 const INGRESS_OPTION_METADATA = {
   quick: {
-    headline: "Cloudflare quick tunnel (default) — no account, nothing to sign up for",
+    headline: "Cloudflare quick tunnel — no account, nothing to sign up for",
     tradeoffs: [
       "no account, no credential, no DNS: it works within seconds of `docker compose up`",
       "the *.trycloudflare.com hostname ROTATES on every tunnel restart — the daemon re-points the App's webhook URL itself, so this costs you nothing to operate",
@@ -117,14 +124,14 @@ const INGRESS_OPTION_METADATA = {
     service: "tunnel-named",
   },
   polling: {
-    headline: "Polling only — no tunnel, nothing exposed",
+    headline: "Polling only (default) — no tunnel, nothing exposed",
     tradeoffs: [
       "nothing to install, nothing reachable from the internet: the daemon only makes outbound calls",
       "the reconcile poll becomes the ONLY trigger path, so a review starts up to one poll interval late ([daemon] poll_interval_s, 300s by default)",
       "what degrades, plainly: author replies do not route to the PR's session (the ping-pong path is webhook-driven), the [feedback] tuning loop never sees a comment, and the CI-completed retry of a withheld approval waits for the next sweep",
       "it is not a dead end — re-run this step later and pick a tunnel; nothing else has to change",
     ],
-    shape: "none",
+    shape: "polling",
     profile: "",
     secret: null,
     service: null,
@@ -163,6 +170,16 @@ const INGRESS_ANCHOR = /^\[daemon\]/m;
 
 /** The section body (header line included) for a choice. */
 export function ingressBlock(option: IngressOption): string {
+  if (option.shape === "polling") {
+    return [
+      "[ingress]",
+      "# Written by the onboarding wizard.",
+      "# Chosen shape: polling — no webhook reaches this daemon; the reconcile poll",
+      "# ([daemon] poll_interval_s) is the only trigger path.",
+      'shape = "polling"',
+      "",
+    ].join("\n");
+  }
   if (option.shape === "none") {
     return [
       "[ingress]",
@@ -425,35 +442,62 @@ function chosen(ctx: StepContext): IngressChoice | null {
 }
 
 /**
- * The recommended default differs by topology, and saying so is the honest
- * part. On a laptop the quick tunnel wins: no account, and the daemon
- * re-points its own rotating hostname. On a server the named tunnel wins: the
- * playbook installs cloudflared there from your token, and a permanent
- * installation deserves a permanent hostname. Every option stays selectable on
- * both — on the server route the ones the playbook does not install mean "you
- * front the daemon's port yourself", which the inventory step spells out.
+ * The recommended default is polling on every topology: nothing to install,
+ * nothing exposed, and the only shape the own-account route allows. A tunnel
+ * (quick on a laptop, named on a server) is the later upgrade for webhook
+ * latency and the reply-driven paths. Every option stays selectable on both
+ * topologies — on the server route the ones the playbook does not install mean
+ * "you front the daemon's port yourself", which the inventory step spells out.
  */
-export function recommendedIngressFor(topology: string): IngressChoice {
-  return topology === "vm" ? "named" : "quick";
+export function recommendedIngressFor(_topology: string): IngressChoice {
+  return "polling";
+}
+
+/** The reconcile poll's interval in whole minutes, as the config states it
+ * (the shipped default when it does not). */
+export function pollMinutes(configText: string | null): number {
+  const raw = configText ? readTomlKey(configText, "daemon", "poll_interval_s") : null;
+  const seconds = raw !== null && /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : 300;
+  return Math.max(1, Math.round(seconds / 60));
+}
+
+/** The one plain line the default is applied with. */
+export function pollingDefaultLine(configText: string | null): string {
+  return (
+    `polling: the reviewer checks GitHub every ${pollMinutes(configText)} minutes for pull requests to review — ` +
+    "nothing to set up, nothing exposed to the internet. Webhooks (faster starts, author replies) are optional and " +
+    "can be added later by re-running this step with a tunnel choice."
+  );
 }
 
 function offerCheck(topology: string): CheckResult {
-  const recommended = recommendedIngressFor(topology);
   return {
     name: "choice",
     ok: false,
     detail:
       `pick one of ${CHOICE_IDS.join(" | ")} and call this step again with it (choice: "<id>").\n` +
+      `The default is "${recommendedIngressFor(topology)}" — nothing to set up and nothing exposed; webhooks are a later upgrade.` +
       (topology === "vm"
-        ? `On the server route the recommended answer is "${recommended}" — the deploy installs cloudflared on that machine from ` +
-          "your tunnel token, and an always-on installation deserves a hostname that never rotates. The others stay available: " +
-          "polling needs no ingress at all, and quick/ngrok mean you run that tunnel on the server yourself.\n"
-        : `On this machine the recommended answer is "${recommended}" — no account, nothing to sign up for, and the daemon ` +
-          "re-points its own webhook URL when the hostname rotates.\n") +
+        ? " On the server route the named tunnel is the upgrade worth having: the deploy installs cloudflared on that machine " +
+          "from your tunnel token, and a hostname that never rotates. quick/ngrok mean you run that tunnel on the server yourself.\n"
+        : " On this machine the quick tunnel is the no-account upgrade: the daemon re-points its own webhook URL when the " +
+          "hostname rotates.\n") +
       renderOptions(),
   };
 }
 
+/** The own-account route has no webhook: no App exists to deliver one. */
+function userRouteRefusal(choice: IngressChoice): CheckResult {
+  return {
+    name: "choice",
+    ok: false,
+    detail:
+      `"${choice}" needs webhooks, and the own-account GitHub route ([github] auth = "user") has none — webhooks are ` +
+      'delivered to a GitHub App, and this install runs on your own account instead. It is polling only: run this step with choice: "polling" ' +
+      '(or with no choice). To use webhooks, switch to the App route first: the github_account step with github_auth: "app".',
+  };
+}
+
 function credentialPresent(file: string): boolean {
   return existsSync(file) && readFileSync(file, "utf8").trim() !== "";
 }
@@ -464,7 +508,7 @@ export function ingressStep(opts: { stream?: StreamRunner } = {}): OnboardingSte
     title: "Webhook ingress: how GitHub reaches your daemon",
     explain:
       "GitHub delivers webhooks to an HTTPS URL, so your daemon needs one. Offer the four shapes with their real " +
-      "trade-offs — quick tunnel (the default: no account, rotating hostname the daemon re-points itself), ngrok " +
+      "trade-offs — quick tunnel (no account, rotating hostname the daemon re-points itself), ngrok " +
       "(stable hostname, free-tier caps), a named Cloudflare tunnel (your own domain), or polling-only (no tunnel; " +
       "the reconcile poll triggers reviews, and author-reply routing plus the feedback loop go quiet). The recommended " +
       "answer depends on where the reviewer lives: the quick tunnel on this computer, the named tunnel on a server (the " +
@@ -493,13 +537,32 @@ export function ingressStep(opts: { stream?: StreamRunner } = {}): OnboardingSte
     },
 
     async run(ctx): Promise<StepReport> {
-      const choice = chosen(ctx);
-      if (choice === null)
+      const userRoute = userAuthRecorded(ctx.choices);
+      const typed = ctx.input.choice;
+      const typedAnswer = typeof typed === "string" && typed.trim() !== "";
+      let choice = chosen(ctx);
+      // An answer that names no shape is re-offered, never defaulted over.
+      if (choice === null && typedAnswer)
         return { ok: false, checks: [offerCheck(String(ctx.choices[CHOICE_KEYS.topology] ?? ""))] };
+      const defaulted = choice === null;
+      if (choice === null)
+        choice = recommendedIngressFor(String(ctx.choices[CHOICE_KEYS.topology] ?? ""));
+      if (userRoute && choice !== "polling") {
+        // A shape recorded before the route was switched is not an answer now.
+        if (!typedAnswer) choice = "polling";
+        else return { ok: false, checks: [userRouteRefusal(choice)] };
+      }
       const option = optionFor(choice)!;
       const root = sandboxRootOf(ctx.adapters);
       const checks: CheckResult[] = [
-        { name: "choice", ok: true, detail: `${option.id} — ${option.headline}` },
+        {
+          name: "choice",
+          ok: true,
+          detail:
+            defaulted && option.id === "polling"
+              ? `${pollingDefaultLine(readTextOrNull(ctx.adapters.paths.configPath))}\nThe other shapes, for later: ${CHOICE_IDS.filter((id) => id !== "polling").join(", ")}.`
+              : `${option.id} — ${option.headline}`,
+        },
         { name: "trade-offs", ok: true, detail: option.tradeoffs.map((t) => `• ${t}`).join("\n") },
       ];
 
@@ -580,7 +643,9 @@ export function ingressStep(opts: { stream?: StreamRunner } = {}): OnboardingSte
         detail:
           option.shape === "tunnel-file"
             ? '[ingress] shape = "tunnel-file" — the daemon watches the hostname file and re-points the App webhook URL when the tunnel rotates'
-            : '[ingress] shape = "none" — no webhook self-heal (this hostname does not rotate)',
+            : option.shape === "polling"
+              ? '[ingress] shape = "polling" — no webhook, the reconcile poll is the only trigger path'
+              : '[ingress] shape = "none" — no webhook self-heal (this hostname does not rotate)',
       });
 
       // 4. the compose profile — which sidecar (if any) comes up with the stack.
@@ -697,7 +762,9 @@ export function ingressStep(opts: { stream?: StreamRunner } = {}): OnboardingSte
               ok: false,
               detail: `${ctx.adapters.paths.configPath} is gone — re-run the ingress step after restoring it`,
             }
-          : shape === option.shape
+          : shape === option.shape ||
+              // a polling install from before the shape had its own name
+              (option.id === "polling" && shape === "none" && !userAuthRecorded(ctx.choices))
             ? { name: "config", ok: true, detail: `[ingress] shape = "${shape}"` }
             : {
                 name: "config",