propr-cli 0.8.3 → 0.8.5

package/dist/commands/setup/github.js

@@ -0,0 +1,181 @@
+/**
+ * GitHub event-intake + user-whitelist helpers for `propr setup`.
+ *
+ * Two concerns the setup wizard must guide a new user through, factored out of
+ * the engine so the decision logic lives in one tested place and both renderers
+ * (Ink + readline) share it:
+ *
+ *   - **Intake mode** — how the backend learns about GitHub events, selected by
+ *     the `GITHUB_EVENT_INTAKE_MODE` `.env` key (the legacy `ENABLE_GITHUB_WEBHOOKS`
+ *     boolean is deprecated and no longer selects the mode). Three paths:
+ *       routing_websocket — events stream over the hosted ProPR routing
+ *                           WebSocket; no inbound webhook listener and no own
+ *                           GitHub App required. The default, and only usable
+ *                           with relay auth (PROPR_GH_RELAY_TOKEN).
+ *       polling           — the daemon polls the GitHub API on an interval; works
+ *                           with any usable GitHub auth and needs no inbound URL.
+ *       direct_webhook    — GitHub posts directly to the local API; requires an
+ *                           own GitHub App plus a signing secret so forged
+ *                           payloads are rejected.
+ *     {@link buildIntakeEnvVars} turns a chosen mode into the exact `.env` keys
+ *     (`GITHUB_EVENT_INTAKE_MODE`, and `GH_WEBHOOK_SECRET` for direct webhooks),
+ *     refusing to produce a direct_webhook config without a secret — the API
+ *     would otherwise refuse to boot.
+ *
+ *   - **User whitelist** — which GitHub users may trigger ProPR. Saved through
+ *     the settings API when the backend is running (a partial update that never
+ *     clobbers unrelated settings), and mirrored into `.env` so the value
+ *     survives a restart. {@link saveWhitelist} owns that routing and degrades to
+ *     an `.env`-only write when the backend is down or the API call fails.
+ *
+ * Like the rest of the setup module these helpers are UI-agnostic and free of
+ * Docker/network imports: side effects are passed in as callbacks so the engine
+ * binds them to the real API/`.env` and tests drive the whole thing in memory.
+ */
+/** Documentation surfaced in the intake prompt's detail text. */
+export const INTAKE_DOCS_URL = "https://docs.propr.dev/docs/architecture/daemon";
+/** Documentation for configuring direct webhook delivery. */
+export const WEBHOOK_DOCS_URL = "https://docs.propr.dev/docs/tutorials/setup-server";
+/** Thrown when an intake selection is missing required input (e.g. a webhook secret). */
+export class IntakeConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IntakeConfigError";
+    }
+}
+/**
+ * The intake mode to pre-select for a given GitHub auth mode. The hosted routing
+ * WebSocket is the product default, but it only works with relay auth (it needs
+ * a relay token and the shared ProPR App), so it's recommended only when relay
+ * auth is configured. Every other auth mode falls back to polling, which works
+ * with any usable GitHub auth and needs no inbound network exposure — and unlike
+ * direct webhooks requires no public URL or own GitHub App.
+ */
+export function defaultIntakeMode(authMode) {
+    return authMode === "relay" ? "routing_websocket" : "polling";
+}
+/**
+ * The intake choice the prompt should pre-select.
+ *
+ * On a re-run where `.env` already carries an intake decision
+ * (`GITHUB_EVENT_INTAKE_MODE` is set), the safe default is `"keep"`: a blank Enter
+ * must never silently rewrite a working config — e.g. an existing
+ * `direct_webhook` install must not flip to `routing_websocket` just because the
+ * auth-derived recommendation differs. This upholds the setup engine's re-run
+ * safety model (keep existing config unless the user explicitly changes it). Only
+ * on a fresh install, with no intake config yet, do we fall back to the
+ * auth-derived recommendation from {@link defaultIntakeMode}.
+ */
+export function defaultIntakeChoice(authMode, opts) {
+    return opts.intakeConfigured ? "keep" : defaultIntakeMode(authMode);
+}
+/**
+ * Translate a chosen {@link GithubIntakeMode} into the `.env` keys it implies.
+ * The mode is selected by `GITHUB_EVENT_INTAKE_MODE`, the value the backend boot
+ * path resolves (see resolveGithubEventIntakeMode); the deprecated
+ * `ENABLE_GITHUB_WEBHOOKS` boolean is intentionally never written here.
+ *
+ *   - `routing_websocket` / `polling` set `GITHUB_EVENT_INTAKE_MODE` to the mode
+ *     and nothing else — routing events arrive over the relay WebSocket and
+ *     polling pulls them from the API, neither needing a local webhook listener.
+ *     A previously recorded `GH_WEBHOOK_SECRET` is intentionally *not* cleared:
+ *     `applyEnvSelection`/`upsertEnvVars` only set keys, never remove them. The
+ *     leftover secret is inert while not in direct_webhook mode (the API never
+ *     reads it), but callers wanting a pristine `.env` must remove it by hand.
+ *   - `direct_webhook` records the signing secret alongside the mode. An
+ *     empty/whitespace secret is rejected with {@link IntakeConfigError}: the API
+ *     refuses to boot in direct_webhook mode with no secret, so writing it would
+ *     only break startup.
+ */
+export function buildIntakeEnvVars(mode, opts = {}) {
+    switch (mode) {
+        case "routing_websocket":
+        case "polling":
+            return { GITHUB_EVENT_INTAKE_MODE: mode };
+        case "direct_webhook": {
+            const secret = (opts.webhookSecret ?? "").trim();
+            if (!secret) {
+                throw new IntakeConfigError("A webhook secret is required for direct webhooks — the API refuses to start without one.");
+            }
+            return { GITHUB_EVENT_INTAKE_MODE: "direct_webhook", GH_WEBHOOK_SECRET: secret };
+        }
+    }
+}
+/** A short, human-readable label for an intake mode, shared by both renderers. */
+export function intakeModeLabel(mode) {
+    switch (mode) {
+        case "routing_websocket":
+            return "ProPR routing WebSocket (hosted relay)";
+        case "polling":
+            return "polling (no inbound webhooks)";
+        case "direct_webhook":
+            return "direct webhooks (signing secret recorded)";
+    }
+}
+/**
+ * The intake modes to show for a given GitHub auth mode, in display order, each
+ * flagged available or not. Unavailable modes are intentionally still returned
+ * so the prompt can show them inactive with the reason — a new user sees the
+ * full set and learns why a path is closed rather than wondering where it went.
+ *
+ * The availability rules mirror {@link validateIntakeModePrerequisites} so the
+ * prompt and the backend boot-time check can never disagree:
+ *   - routing_websocket needs the ProPR token relay; a custom GitHub App can't use it.
+ *   - direct_webhook needs your own GitHub App; the ProPR relay can't deliver to it.
+ *   - polling works with either usable auth, but is not recommended for production.
+ */
+export function intakeModeOptions(authMode) {
+    const relay = authMode === "relay";
+    const app = authMode === "app";
+    return [
+        {
+            mode: "routing_websocket",
+            available: relay,
+            note: relay
+                ? undefined
+                : "needs the ProPR GitHub App (token relay); not available with a custom GitHub App",
+        },
+        {
+            mode: "polling",
+            available: relay || app,
+            note: relay || app
+                ? "not recommended for production: subject to GitHub API rate limits and delayed event detection (depends on the polling interval and the number of repos/PRs/issues)"
+                : "needs usable GitHub auth — configure the token relay or a custom GitHub App first",
+        },
+        {
+            mode: "direct_webhook",
+            available: app,
+            note: app
+                ? undefined
+                : "needs your own custom GitHub App; not available with the ProPR token relay",
+        },
+    ];
+}
+/**
+ * Persist the user whitelist, preferring the settings API when the backend is
+ * running so the change takes effect immediately without a restart, and always
+ * mirroring into `.env` so it survives one. If the API call fails we fall back
+ * to the `.env` write and report the error rather than abort setup.
+ *
+ * The settings-API path issues a *partial* update (only the whitelist key), so
+ * unrelated settings are never overwritten.
+ */
+export async function saveWhitelist(params) {
+    const { users, backendRunning, saveViaSettings, saveViaEnv } = params;
+    if (backendRunning) {
+        try {
+            await saveViaSettings(users);
+            // Mirror into `.env` so the whitelist persists across `propr start`.
+            saveViaEnv(users);
+            return { target: "settings", count: users.length };
+        }
+        catch (error) {
+            // The backend rejected the update (or was unreachable after all) — keep
+            // the value in `.env` so it is not lost, and surface why.
+            saveViaEnv(users);
+            return { target: "env", count: users.length, error: error.message };
+        }
+    }
+    saveViaEnv(users);
+    return { target: "env", count: users.length };
+}

package/dist/commands/setup/sequential.js

@@ -0,0 +1,501 @@
+/**
+ * Sequential (readline) fallback wizard for `propr setup`.
+ *
+ * The setup engine (./engine.ts) is UI-agnostic: it drives the flow, emits
+ * progress through a {@link SetupReporter}, and collects decisions through
+ * optional {@link SetupPrompts} hooks. The Ink TUI (../../tui/SetupApp.tsx)
+ * wires those seams to a full-screen React view; this module wires the exact
+ * same seams to plain `readline/promises` prompts and line-by-line output.
+ *
+ * It exists for every terminal where Ink can't run — no raw-mode support, SSH
+ * shells, CI-like environments, and an explicit `--no-tui`. The flow, the
+ * decision logic, and the safe-default contract are all the engine's; only the
+ * rendering differs, so the two paths can never drift in behaviour.
+ *
+ * Prompting requires an interactive stdin. When stdin is not a TTY there is no
+ * one to answer, so {@link runSequentialSetup} fails fast with actionable
+ * guidance instead of hanging on a prompt that can never be satisfied.
+ *
+ * The I/O is abstracted behind {@link SequentialIo} so the prompt mapping and
+ * reporter can be unit-tested with a scripted in-memory transcript — no TTY,
+ * Docker, or readline required.
+ */
+import { createInterface } from "node:readline/promises";
+import { DEFAULT_PROPR_GH_RELAY_URL } from "../../vendor/shared/index.js";
+import { INTAKE_DOCS_URL, WEBHOOK_DOCS_URL, intakeModeOptions, } from "./github.js";
+import { runSetup, } from "./engine.js";
+const ANSI = {
+    reset: "",
+    bold: "",
+    dim: "",
+    red: "",
+    green: "",
+    yellow: "",
+    cyan: "",
+};
+function makePaint(enabled) {
+    return (text, ...codes) => (enabled ? `${codes.join("")}${text}${ANSI.reset}` : text);
+}
+/**
+ * A {@link SequentialIo} backed by `readline/promises` over the given streams.
+ * Masked questions suppress keystroke echo by intercepting readline's internal
+ * output writer — the prompt itself is drawn normally, only what the user types
+ * afterwards is hidden (the same behaviour as a password prompt).
+ */
+export function createReadlineIo(input = process.stdin, output = process.stdout) {
+    const rl = createInterface({ input, output });
+    let muted = false;
+    // readline echoes input by writing through `_writeToOutput`; override it so a
+    // masked question can swallow keystroke echo while still emitting newlines so
+    // the cursor advances when the user submits. Falls back gracefully: if the
+    // internal hook is ever absent, input simply stays visible.
+    const internal = rl;
+    if (typeof internal._writeToOutput === "function") {
+        internal._writeToOutput = (chunk) => {
+            if (muted) {
+                if (chunk.includes("\n"))
+                    output.write("\n");
+                return;
+            }
+            output.write(chunk);
+        };
+    }
+    return {
+        print(line = "") {
+            output.write(`${line}\n`);
+        },
+        async ask(question, opts) {
+            // Draw the prompt unmuted, then mute so only the typed answer is hidden.
+            const answer = rl.question(question);
+            muted = Boolean(opts?.mask);
+            try {
+                return await answer;
+            }
+            finally {
+                muted = false;
+            }
+        },
+        close() {
+            rl.close();
+        },
+    };
+}
+/** Print a prompt's heading: a blank line, the title, then an optional detail. */
+function printHeading(io, paint, title, detail) {
+    io.print();
+    io.print(paint(title, ANSI.bold, ANSI.cyan));
+    if (detail)
+        io.print(paint(detail, ANSI.dim));
+}
+async function promptConfirm(io, paint, req) {
+    printHeading(io, paint, req.title, req.detail);
+    const def = req.defaultValue ?? false;
+    const suffix = def ? "[Y/n]" : "[y/N]";
+    for (;;) {
+        const answer = (await io.ask(`  ${paint("❯", ANSI.cyan)} ${suffix} `)).trim().toLowerCase();
+        if (answer === "")
+            return def;
+        if (answer === "y" || answer === "yes")
+            return true;
+        if (answer === "n" || answer === "no")
+            return false;
+        io.print(paint("  Please answer y or n.", ANSI.yellow));
+    }
+}
+async function promptInput(io, paint, req) {
+    printHeading(io, paint, req.title, req.detail);
+    const def = req.defaultValue ?? "";
+    const shownDefault = req.mask ? "•".repeat(def.length) : def;
+    const hint = def ? paint(` (blank → ${shownDefault})`, ANSI.dim) : "";
+    const answer = await io.ask(`  ${paint("❯", ANSI.cyan)}${hint} `, { mask: req.mask });
+    // Mirror the Ink input exactly: a blank entry falls back to the default,
+    // otherwise the raw text is returned for the engine hook to trim/parse.
+    return answer.length > 0 ? answer : def;
+}
+async function promptSelect(io, paint, req) {
+    // A single-choice prompt with no options is a caller bug; fail loudly with a
+    // clear message rather than crash on an out-of-range default index below.
+    if (req.options.length === 0) {
+        throw new Error(`Cannot prompt "${req.title}": no options were provided.`);
+    }
+    // Likewise, a prompt whose every option is disabled has no valid answer.
+    const firstEnabled = req.options.findIndex((o) => !o.disabled);
+    if (firstEnabled === -1) {
+        throw new Error(`Cannot prompt "${req.title}": every option is unavailable.`);
+    }
+    printHeading(io, paint, req.title, req.detail);
+    // Never pre-select a disabled option: a blank Enter must land on something the
+    // user can actually pick.
+    let defaultIndex = Math.min(Math.max(req.defaultIndex ?? 0, 0), req.options.length - 1);
+    if (req.options[defaultIndex].disabled)
+        defaultIndex = firstEnabled;
+    req.options.forEach((option, index) => {
+        const marker = index === defaultIndex ? paint("›", ANSI.cyan) : " ";
+        const hint = option.hint ? paint(` (${option.hint})`, ANSI.dim) : "";
+        const label = option.disabled ? paint(`${option.label} — unavailable`, ANSI.dim) : option.label;
+        io.print(`  ${marker} ${index + 1}) ${label}${hint}`);
+    });
+    for (;;) {
+        const answer = (await io.ask(`  ${paint("❯", ANSI.cyan)} choose 1-${req.options.length} (blank → ${defaultIndex + 1}) `)).trim();
+        if (answer === "")
+            return req.options[defaultIndex].value;
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= req.options.length) {
+            const picked = req.options[n - 1];
+            if (picked.disabled) {
+                io.print(paint(`  Option ${n} is unavailable: ${picked.hint ?? "not valid for the current GitHub auth mode"}.`, ANSI.yellow));
+                continue;
+            }
+            return picked.value;
+        }
+        io.print(paint(`  Enter a number between 1 and ${req.options.length}.`, ANSI.yellow));
+    }
+}
+async function promptMultiSelect(io, paint, req) {
+    printHeading(io, paint, req.title, req.detail);
+    // Nothing to choose from: note it and return an empty set rather than pose a
+    // prompt whose only valid answer is "blank" with an "between 1 and 0" error.
+    if (req.options.length === 0) {
+        io.print(paint("  (no options available)", ANSI.dim));
+        return [];
+    }
+    const defaults = new Set(req.defaultSelected ?? []);
+    req.options.forEach((option, index) => {
+        const checked = defaults.has(option.value) ? "[x]" : "[ ]";
+        const hint = option.hint ? paint(` (${option.hint})`, ANSI.dim) : "";
+        io.print(`  ${index + 1}) ${checked} ${option.label}${hint}`);
+    });
+    io.print(paint('  Enter comma-separated numbers to select, blank to keep the defaults, or "none" for an empty set.', ANSI.dim));
+    for (;;) {
+        const answer = (await io.ask(`  ${paint("❯", ANSI.cyan)} numbers `)).trim();
+        if (answer === "")
+            return req.options.filter((o) => defaults.has(o.value)).map((o) => o.value);
+        if (answer.toLowerCase() === "none")
+            return [];
+        const nums = answer
+            .split(",")
+            .map((part) => part.trim())
+            .filter(Boolean)
+            .map(Number);
+        if (nums.length > 0 && nums.every((n) => Number.isInteger(n) && n >= 1 && n <= req.options.length)) {
+            // De-dupe (first occurrence wins) and preserve option order for a stable result.
+            const picked = new Set(nums.map((n) => req.options[n - 1].value));
+            return req.options.filter((o) => picked.has(o.value)).map((o) => o.value);
+        }
+        io.print(paint(`  Enter numbers between 1 and ${req.options.length}, separated by commas.`, ANSI.yellow));
+    }
+}
+// ---------------------------------------------------------------------------
+// Engine prompt hooks.
+// ---------------------------------------------------------------------------
+/**
+ * Map the engine's typed prompt hooks onto the sequential primitives. The hook
+ * bodies mirror {@link buildSetupPrompts} in ../../tui/SetupApp.tsx one-for-one
+ * so both renderers honour the same safe defaults: a blank input or a "keep"
+ * choice leaves existing configuration untouched.
+ */
+export function buildSequentialPrompts(io, paint = makePaint(false)) {
+    return {
+        async resolveStackRoot({ currentRoot, init }) {
+            const entered = await promptInput(io, paint, {
+                title: "Stack root directory",
+                detail: init.initialized
+                    ? `A stack already exists at ${currentRoot}.`
+                    : `The stack will be scaffolded at ${currentRoot}.`,
+                defaultValue: currentRoot,
+            });
+            const rootDir = entered.trim() || currentRoot;
+            // Only offer a re-scaffold when the resolved root already looks complete;
+            // an incomplete root is scaffolded by the engine regardless.
+            let reinitialize = false;
+            if (init.initialized && rootDir === currentRoot) {
+                reinitialize = await promptConfirm(io, paint, {
+                    title: "Re-scaffold the stack?",
+                    detail: "Fill in any missing files. Your existing .env is preserved.",
+                    defaultValue: false,
+                });
+            }
+            return { rootDir, reinitialize };
+        },
+        async selectAgents({ available, detected }) {
+            const detectedSet = new Set(detected);
+            return promptMultiSelect(io, paint, {
+                title: "Select agents to enable",
+                detail: "Their images are pulled and host credentials recorded in .env.",
+                options: available.map((type) => ({
+                    label: type,
+                    value: type,
+                    hint: detectedSet.has(type) ? "detected" : undefined,
+                })),
+                defaultSelected: detected,
+            });
+        },
+        async configureGithubAuth({ current }) {
+            // Token relay (the hosted ProPR GitHub App) leads as the recommended path.
+            // "Keep current configuration" is offered only when there is an existing
+            // config to keep — on a fresh install there is nothing to preserve, so the
+            // relay option is the first (and default) choice.
+            const options = [];
+            if (current.mode !== "none") {
+                options.push({ label: "Keep current configuration", value: "keep", hint: current.mode });
+            }
+            options.push({ label: "Token relay (use the ProPR GitHub App)", value: "relay" });
+            options.push({ label: "Custom GitHub App (set up your own GitHub App)", value: "app" });
+            const choice = await promptSelect(io, paint, {
+                title: "GitHub authentication",
+                detail: `Currently detected: ${current.mode}.`,
+                options,
+                defaultIndex: 0,
+            });
+            if (choice === "keep")
+                return { keep: true };
+            // Switching to a real auth mode must explicitly turn demo mode off:
+            // detectGithubAuthMode reads PROPR_DEMO_MODE, so a leftover
+            // PROPR_DEMO_MODE=true would keep resolving as demo and ignore the App/relay
+            // config the user just entered.
+            if (choice === "relay") {
+                // No manual URL/token entry: the engine enrolls with the hosted relay
+                // using the stored `propr login` token, discovers the installation, and
+                // mints the token. Only the relay base URL is asked, prefilled with the
+                // hosted default (Enter accepts it; override for a self-hosted relay).
+                const relayUrl = await promptInput(io, paint, {
+                    title: "Relay URL",
+                    detail: "Press Enter for the hosted ProPR relay; override only for a self-hosted relay.",
+                    defaultValue: DEFAULT_PROPR_GH_RELAY_URL,
+                });
+                return { mode: "relay", enrollRelay: { relayUrl: relayUrl.trim() || DEFAULT_PROPR_GH_RELAY_URL } };
+            }
+            const appId = await promptInput(io, paint, { title: "GitHub App ID", defaultValue: "" });
+            // The CLI stack bind-mounts the key from the host via HOST_GH_PRIVATE_KEY
+            // (NOT the in-container GH_PRIVATE_KEY_PATH, which is the launcher path) —
+            // so `propr start` can find it. Ask for the host path and write that key.
+            const privateKeyPath = await promptInput(io, paint, { title: "Host path to the App private key (.pem)", defaultValue: "" });
+            const installationId = await promptInput(io, paint, { title: "Installation ID", defaultValue: "" });
+            return {
+                mode: "app",
+                vars: { PROPR_DEMO_MODE: "false", GH_AUTH_MODE: "app", GH_APP_ID: appId, HOST_GH_PRIVATE_KEY: privateKeyPath, GH_INSTALLATION_ID: installationId },
+            };
+        },
+        async confirmGithubLogin({ reason }) {
+            return promptConfirm(io, paint, {
+                title: "Log in to GitHub now?",
+                detail: `${reason} Runs \`gh auth login\` (the GitHub CLI).`,
+                defaultValue: true,
+            });
+        },
+        async selectInstallation({ installations }) {
+            const choice = await promptSelect(io, paint, {
+                title: "Choose a GitHub App installation",
+                detail: "Your account can access more than one; the relay token is minted for the one you pick.",
+                options: installations.map((i) => ({
+                    label: `${i.account_login} (${i.account_type})`,
+                    value: String(i.installation_id),
+                    hint: String(i.installation_id),
+                })),
+                defaultIndex: 0,
+            });
+            return choice;
+        },
+        async configureIntake({ authMode, defaultMode, currentMode }) {
+            // Only some intake modes are valid for the chosen auth mode (e.g. direct
+            // webhooks need an own GitHub App, the routing WebSocket needs the ProPR
+            // relay). Show every mode, but mark the unsupported ones inactive with the
+            // reason so the user understands why a path is closed.
+            const baseLabel = {
+                routing_websocket: "Routing WebSocket — hosted ProPR relay (recommended)",
+                polling: "Polling (no inbound webhooks)",
+                direct_webhook: "Direct webhooks (own GitHub App + a signing secret)",
+            };
+            const options = intakeModeOptions(authMode).map((opt) => ({
+                label: baseLabel[opt.mode],
+                value: opt.mode,
+                hint: opt.note,
+                disabled: !opt.available,
+            }));
+            options.push({ label: "Keep current", value: "keep", hint: currentMode });
+            let defaultIndex = Math.max(0, options.findIndex((o) => o.value === defaultMode));
+            // If the recommended default isn't valid for this auth mode, fall back to
+            // the first selectable option rather than pre-selecting a disabled one.
+            if (options[defaultIndex]?.disabled)
+                defaultIndex = options.findIndex((o) => !o.disabled);
+            const choice = await promptSelect(io, paint, {
+                title: "GitHub event intake",
+                detail: `How the backend receives GitHub events. Docs: ${INTAKE_DOCS_URL}`,
+                options,
+                defaultIndex,
+            });
+            if (choice === "keep")
+                return { keep: true };
+            if (choice === "direct_webhook") {
+                // The API refuses to boot in direct_webhook mode with no secret — keep
+                // asking until a non-empty secret is entered.
+                let secret = "";
+                while (secret === "") {
+                    secret = (await promptInput(io, paint, {
+                        title: "Webhook signing secret",
+                        detail: `Verifies GitHub webhook signatures; forged payloads are rejected. Docs: ${WEBHOOK_DOCS_URL}`,
+                        mask: true,
+                    })).trim();
+                    if (secret === "")
+                        io.print(paint("  A webhook secret is required.", ANSI.yellow));
+                }
+                return { mode: "direct_webhook", webhookSecret: secret };
+            }
+            return { mode: choice };
+        },
+        async confirmStartStack({ rootDir, alreadyRunning }) {
+            // A running stack is reused without prompting — nothing to start.
+            if (alreadyRunning)
+                return true;
+            return promptConfirm(io, paint, {
+                title: "Start the stack now?",
+                detail: `Launch the local control-plane services in ${rootDir}.`,
+                defaultValue: true,
+            });
+        },
+        async confirmAgentLogin({ candidates }) {
+            return promptMultiSelect(io, paint, {
+                title: "Authenticate agents through their images?",
+                detail: 'Log in inside each agent\'s Docker image; credentials are written to the mounted host directory. Blank or "none" skips.',
+                options: candidates.map((type) => ({ label: type, value: type })),
+                defaultSelected: [],
+            });
+        },
+        async configureWhitelist({ current, demoMode }) {
+            if (demoMode)
+                return null;
+            const entered = await promptInput(io, paint, {
+                title: "Allowed GitHub usernames",
+                detail: 'Comma-separated; only these users can trigger ProPR. Blank keeps the current value, "none" clears it.',
+                defaultValue: current.join(", "),
+            });
+            const trimmed = entered.trim();
+            if (trimmed === "")
+                return null;
+            // An explicit "none" empties the whitelist — a discoverable affordance that
+            // mirrors agent selection, instead of needing a bare comma to clear it.
+            if (trimmed.toLowerCase() === "none")
+                return [];
+            return trimmed
+                .split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+        },
+        async addRepository() {
+            const add = await promptConfirm(io, paint, {
+                title: "Connect a repository now?",
+                detail: "Optionally add a first repository for ProPR to monitor.",
+                defaultValue: false,
+            });
+            if (!add)
+                return null;
+            const fullName = (await promptInput(io, paint, { title: "Repository (owner/repo)", defaultValue: "" })).trim();
+            if (!fullName)
+                return null;
+            const baseBranch = (await promptInput(io, paint, { title: "Base branch (optional, blank for the default)", defaultValue: "" })).trim();
+            return { fullName, baseBranch: baseBranch || undefined };
+        },
+        async launchUi({ url }) {
+            if (!url)
+                return false;
+            return promptConfirm(io, paint, { title: "Open the ProPR web UI?", detail: url, defaultValue: false });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Progress reporting.
+// ---------------------------------------------------------------------------
+/** Terminal glyph + color for a settled step, mirroring the Ink status row. */
+const SETTLED_GLYPH = {
+    done: { glyph: "✓", color: ANSI.green },
+    skipped: { glyph: "−", color: ANSI.dim },
+    warning: { glyph: "!", color: ANSI.yellow },
+    failed: { glyph: "✗", color: ANSI.red },
+};
+/**
+ * Build the reporter that streams the engine's progress as plain lines: a
+ * heading when each step starts, a glyph + detail when it settles, and any log
+ * lines in between. `onState` is intentionally unused — replaying the whole
+ * step list on every transition reads as noise in a scrolling log, whereas the
+ * Ink view repaints it in place.
+ */
+export function buildSequentialReporter(io, paint = makePaint(false)) {
+    return {
+        onStepStart(step) {
+            io.print();
+            const optional = step.optional ? paint(" (optional)", ANSI.dim) : "";
+            io.print(`${paint("▶", ANSI.cyan, ANSI.bold)} ${paint(step.title, ANSI.bold)}${optional}`);
+            io.print(paint(`  ${step.description}`, ANSI.dim));
+        },
+        onStepSettled(step) {
+            if (step.status === "active" || step.status === "pending")
+                return;
+            const { glyph, color } = SETTLED_GLYPH[step.status];
+            io.print(`  ${paint(glyph, color)} ${step.detail ?? step.status}`);
+            if (step.nextAction)
+                io.print(`     ${paint("↳", ANSI.dim)} ${step.nextAction}`);
+        },
+        onLog(line) {
+            io.print(paint(`  · ${line}`, ANSI.dim));
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point.
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when the sequential wizard cannot prompt because stdin is not an
+ * interactive terminal. Carries actionable guidance in its message so the
+ * command layer can print it verbatim and exit non-zero.
+ */
+export class SequentialSetupUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SequentialSetupUnavailableError";
+    }
+}
+/**
+ * Run `propr setup` through the readline fallback wizard, reusing the shared
+ * engine. Fails fast (without prompting) when stdin is not interactive.
+ *
+ * @throws {SequentialSetupUnavailableError} when stdin is not a TTY and no I/O
+ *   seam was injected — there is no one to answer the prompts.
+ */
+export async function runSequentialSetup(options = {}) {
+    const { io: injectedIo, input = process.stdin, output = process.stdout, color, ...setupOptions } = options;
+    // No interactive stdin means no one can answer the prompts; fail with guidance
+    // rather than hang. Skipped when a test injects its own scripted I/O.
+    if (!injectedIo && !input.isTTY) {
+        throw new SequentialSetupUnavailableError([
+            "`propr setup` needs an interactive terminal to ask you questions, but stdin is not a TTY",
+            "(it looks piped, redirected, or running under CI).",
+            "",
+            "Run `propr setup` directly in an interactive shell, or configure the stack without prompts:",
+            "  • `propr init stack`, then edit <root>/.env by hand and run `propr start`",
+            "  • or pre-set the values in <root>/.env before re-running setup",
+        ].join("\n"));
+    }
+    const colorEnabled = color ?? (Boolean(output.isTTY) && process.env.NO_COLOR === undefined);
+    const paint = makePaint(colorEnabled);
+    const io = injectedIo ?? createReadlineIo(input, output);
+    io.print(paint("ProPR setup", ANSI.bold));
+    io.print(paint("Running the sequential wizard (no interactive TUI).", ANSI.dim));
+    try {
+        const result = await runSetup({
+            ...setupOptions,
+            prompts: buildSequentialPrompts(io, paint),
+            reporter: buildSequentialReporter(io, paint),
+        });
+        io.print();
+        if (result.completed) {
+            io.print(paint("✓ Setup complete.", ANSI.green, ANSI.bold));
+        }
+        else {
+            io.print(paint("✗ Setup did not finish — see the failed step above and re-run `propr setup`.", ANSI.red, ANSI.bold));
+        }
+        return result;
+    }
+    finally {
+        io.close();
+    }
+}