propr-cli 0.8.3 → 0.8.5

package/dist/commands/setup/state.js

@@ -0,0 +1,242 @@
+/**
+ * Setup wizard domain helpers.
+ *
+ * Pure, side-effect-light helpers that the `propr setup` driver and both
+ * renderers (Ink TUI and readline fallback) build on:
+ *   - resolving the stack root (reusing the orchestrator's precedence rules),
+ *   - inspecting whether the stack is already initialized,
+ *   - reading and *safely* editing .env (non-destructive by default),
+ *   - constructing and transitioning the {@link SetupState} step model.
+ *
+ * Nothing here loads the orchestrator's Docker core or renders UI, so the
+ * module can be imported and unit-tested without Docker, Ink, or readline.
+ * `resolveStackRoot` lives in ../../orchestrator/index.js but only reads config
+ * and env — it does not start Docker.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveGithubAuthMode } from "../../vendor/shared/index.js";
+import { resolveStackRoot } from "../../orchestrator/index.js";
+import { clearEnvKeys as clearEnvFileKeys, upsertEnvVars } from "../../utils/envFile.js";
+import { SETUP_STEP_DEFINITIONS, } from "./types.js";
+/**
+ * Sub-directories scaffoldStack creates under the stack root. Exported so the
+ * setup driver and tests can create/check the same scaffold shape without
+ * duplicating these names.
+ */
+export const STACK_SUBDIRS = ["data", "logs", "repos"];
+/** True only when `path` exists and is a directory. Missing paths read false. */
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** True only when `path` exists and is a regular file. Missing paths read false. */
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a value is missing or contains only whitespace. */
+function isBlank(value) {
+    return value === undefined || value.trim() === "";
+}
+/**
+ * Resolve the stack root for setup, reusing the orchestrator's precedence:
+ * explicit flag → PROPR_ROOT env → saved config stackRoot → cwd. Does not load
+ * Docker.
+ */
+export function resolveSetupRoot(configManager, flagRoot) {
+    return resolveStackRoot(configManager, flagRoot);
+}
+/** Absolute path to the .env file for a given stack root. */
+export function envPathFor(rootDir) {
+    return join(rootDir, ".env");
+}
+/**
+ * Inspect whether the stack at `rootDir` looks initialized. Read-only — never
+ * creates anything — so callers can decide whether to skip or re-run
+ * scaffolding. A plain file standing in for an expected directory (or vice
+ * versa) counts as *not* initialized, matching what the runtime requires.
+ */
+export function inspectStackInit(rootDir) {
+    const envExists = isFile(envPathFor(rootDir));
+    const dirs = {};
+    for (const sub of STACK_SUBDIRS) {
+        dirs[sub] = isDirectory(join(rootDir, sub));
+    }
+    const initialized = envExists && STACK_SUBDIRS.every((sub) => dirs[sub]);
+    return { rootDir, envExists, dirs, initialized };
+}
+/** Convenience predicate over {@link inspectStackInit}. */
+export function isStackInitialized(rootDir) {
+    return inspectStackInit(rootDir).initialized;
+}
+/**
+ * Parse the .env at `rootDir` into a flat map. Returns `{}` when the file is
+ * absent. Mirrors the assignment shape the rest of the stack relies on:
+ * `KEY=value`, optionally `export `-prefixed, ignoring blanks and comments.
+ * For unquoted values a trailing ` # comment` is stripped, matching the
+ * orchestrator's env-file reader (and the round-trip that {@link upsertEnvVars}
+ * guards against); surrounding quotes on quoted values are stripped and their
+ * contents kept verbatim. This is intentionally a lightweight reader, not a
+ * full dotenv implementation — it does not handle escaped quotes or multiline
+ * values.
+ */
+export function readEnvVars(rootDir) {
+    const envPath = envPathFor(rootDir);
+    // Treat anything that is not a regular file (absent, a directory, a broken
+    // symlink) as "no vars", matching inspectStackInit's `isFile` guard, so a
+    // malformed stack surfaces as not-initialized instead of crashing the read.
+    if (!isFile(envPath))
+        return {};
+    const vars = {};
+    for (const line of readFileSync(envPath, "utf-8").split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        const trimmed = rawValue.trim();
+        const quoted = trimmed.match(/^(["'])(.*)\1$/);
+        // Quoted values keep their contents verbatim; unquoted values drop a
+        // trailing inline comment so reads agree with what upsertEnvVars allows.
+        vars[key] = quoted ? quoted[2] : trimmed.replace(/\s+#.*$/, "");
+    }
+    return vars;
+}
+/** True when `key` is present in .env with a non-blank value. */
+export function hasEnvValue(rootDir, key) {
+    return !isBlank(readEnvVars(rootDir)[key]);
+}
+/**
+ * Safely edit .env for a setup step.
+ *
+ * Non-destructive by default: a key is only written when it is currently
+ * absent/empty, so re-running `propr setup` never clobbers values the user
+ * already set. Pass `{ overwrite: true }` for steps where the user explicitly
+ * selected a new value and intends to replace whatever is there.
+ *
+ * Blank selections (empty or whitespace-only) are ignored entirely — a step
+ * that has nothing to write must not blank out an existing value. Writes go
+ * through
+ * {@link upsertEnvVars}, which preserves unrelated lines and tightens the
+ * file's permissions.
+ */
+export function applyEnvSelection(rootDir, vars, opts = {}) {
+    const existing = readEnvVars(rootDir);
+    const toWrite = {};
+    const written = [];
+    const skipped = [];
+    for (const [key, value] of Object.entries(vars)) {
+        if (isBlank(value))
+            continue; // never blank out an existing value
+        const alreadySet = !isBlank(existing[key]);
+        if (alreadySet && !opts.overwrite) {
+            skipped.push(key);
+            continue;
+        }
+        toWrite[key] = value;
+        written.push(key);
+    }
+    if (written.length > 0) {
+        upsertEnvVars(envPathFor(rootDir), toWrite);
+    }
+    return { written, skipped };
+}
+/**
+ * Remove `keys` from the stack's `.env` entirely.
+ *
+ * {@link applyEnvSelection} can only set keys (and deliberately ignores blank
+ * values so it never clobbers a value the user set), so it cannot *clear* a key:
+ * writing `KEY=` would leave an empty assignment that reads back as a set-but-
+ * empty value. Setup steps that must genuinely drop a stale key — clearing the
+ * user whitelist back to "none", removing a key when switching modes — call this
+ * instead. A missing `.env` or absent keys are no-ops.
+ */
+export function clearEnvKeys(rootDir, keys) {
+    clearEnvFileKeys(envPathFor(rootDir), keys);
+}
+/**
+ * Infer the current GitHub auth mode from the stack's .env, so the github-auth
+ * step can show what is already configured (and skip prompting when valid).
+ * Reuses the shared resolver the backend uses, so the two can't drift.
+ */
+export function detectGithubAuthMode(rootDir) {
+    const env = readEnvVars(rootDir);
+    const truthy = /^(1|true|yes|on)$/i;
+    return resolveGithubAuthMode({
+        demoMode: truthy.test(env.PROPR_DEMO_MODE ?? ""),
+        ghAuthMode: env.GH_AUTH_MODE,
+        relayUrl: env.PROPR_GH_RELAY_URL,
+        relayToken: env.PROPR_GH_RELAY_TOKEN,
+        appId: env.GH_APP_ID,
+        // The CLI stack records the App key as HOST_GH_PRIVATE_KEY (the orchestrator
+        // bind-mounts it and sets the in-container GH_PRIVATE_KEY_PATH to that path),
+        // so accept either when inferring app mode — otherwise a stack configured by
+        // `propr setup` would resolve as "none" despite being fully set up.
+        privateKeyPath: env.GH_PRIVATE_KEY_PATH ?? env.HOST_GH_PRIVATE_KEY,
+        installationId: env.GH_INSTALLATION_ID,
+    });
+}
+/** Build the initial, all-`pending` setup state for a resolved stack root. */
+export function createSetupState(rootDir) {
+    return {
+        rootDir,
+        steps: SETUP_STEP_DEFINITIONS.map((def) => ({ ...def, status: "pending" })),
+    };
+}
+/** Look up a step by id. */
+export function getStep(state, id) {
+    return state.steps.find((step) => step.id === id);
+}
+/**
+ * Return a new state with `id`'s step patched. Immutable so renderers can diff
+ * by reference; unknown ids return the state unchanged.
+ */
+export function updateStep(state, id, patch) {
+    let changed = false;
+    const steps = state.steps.map((step) => {
+        if (step.id !== id)
+            return step;
+        changed = true;
+        return { ...step, ...patch };
+    });
+    return changed ? { ...state, steps } : state;
+}
+/**
+ * The next step the wizard should act on: the first one still `pending`. Used
+ * by the sequential renderer to drive the flow and by the TUI to highlight the
+ * current step.
+ *
+ * A failed required step blocks everything after it (see the `failed` status in
+ * ./types.ts), so once one is encountered there is no next step until it is
+ * retried — `undefined` is returned. Failed *optional* steps don't block.
+ */
+export function nextPendingStep(state) {
+    // Scan for a blocking failure first so the "a failed required step blocks
+    // everything after it" contract holds even if state was patched out of
+    // order (e.g. a later step failed before an earlier one finished).
+    if (state.steps.some((step) => !step.optional && step.status === "failed")) {
+        return undefined;
+    }
+    return state.steps.find((step) => step.status === "pending");
+}
+/**
+ * True once every required step has reached a terminal, non-failed state.
+ * Optional steps never block completion; a single failed required step does.
+ */
+export function isSetupComplete(state) {
+    return state.steps.every((step) => {
+        if (step.status === "failed")
+            return false;
+        if (step.optional)
+            return true;
+        return step.status === "done" || step.status === "skipped" || step.status === "warning";
+    });
+}

package/dist/commands/setup/types.js

@@ -0,0 +1,85 @@
+/**
+ * Setup wizard domain types.
+ *
+ * `propr setup` walks a new user through getting a local control-plane stack
+ * running end to end. The flow coordinates several existing commands
+ * (environment checks, stack scaffolding, image pulls, agent + GitHub
+ * configuration, stack startup, whitelist + repo setup, and UI launch).
+ *
+ * These types are intentionally free of any rendering concern so the same
+ * step/status model can drive an Ink TUI and a plain readline fallback. They
+ * carry no Docker, Ink, or readline imports — see ./state.ts for the pure
+ * helpers that compute and transition this state.
+ */
+/**
+ * Canonical, ordered step definitions. All start `pending`; renderers and the
+ * command driver transition them via the helpers in ./state.ts.
+ */
+export const SETUP_STEP_DEFINITIONS = [
+    {
+        id: "check",
+        title: "Environment checks",
+        description: "Verify Docker, images, and agent credentials are ready.",
+        optional: false,
+    },
+    {
+        id: "init-stack",
+        title: "Initialize stack",
+        description: "Scaffold the stack root (.env, data/, logs/, repos/).",
+        optional: false,
+    },
+    {
+        id: "pull-images",
+        title: "Pull images",
+        description: "Download the ProPR service and agent container images.",
+        optional: false,
+    },
+    {
+        id: "configure-agents",
+        title: "Configure agents",
+        description: "Record detected host agent-credential directories in .env.",
+        optional: false,
+    },
+    {
+        id: "github-auth",
+        title: "GitHub authentication",
+        description: "Choose how the backend authenticates to GitHub.",
+        optional: false,
+    },
+    {
+        id: "intake",
+        title: "GitHub intake",
+        description: "Choose how the backend ingests GitHub events (routing WebSocket, polling, or direct webhooks).",
+        optional: false,
+    },
+    {
+        id: "start-stack",
+        title: "Start stack",
+        description: "Launch the local control-plane services.",
+        optional: false,
+    },
+    {
+        id: "enable-agents",
+        title: "Enable agents",
+        description: "Enable the selected agents in the backend and authenticate through their images.",
+        optional: false,
+    },
+    {
+        id: "whitelist",
+        title: "Whitelist setup",
+        description: "Restrict which GitHub users may trigger ProPR.",
+        optional: false,
+    },
+    {
+        id: "repo",
+        title: "Repository setup",
+        description: "Optionally connect a first repository to work on.",
+        optional: true,
+    },
+    {
+        id: "launch-ui",
+        title: "Launch UI",
+        description: "Open the ProPR web UI.",
+        optional: true,
+    },
+];

package/dist/commands/setupCommand.js

@@ -0,0 +1,85 @@
+/**
+ * `propr setup` — guided one-time setup for the local ProPR stack.
+ *
+ * The flow itself lives in the UI-agnostic engine (./setup/engine.ts). This
+ * command only chooses how to render it:
+ *
+ *   • The full-screen Ink wizard (../tui/app.tsx) when stdin and stdout are
+ *     interactive TTYs that support raw mode — the keyboard-driven view.
+ *   • The sequential readline wizard (./setup/sequential.ts) otherwise: an
+ *     explicit `--no-tui`, or an interactive terminal that can't enter raw mode
+ *     (some SSH sessions, minimal/embedded terminals). It prompts line by line.
+ *
+ * These two are distinct from the no-stdin case. When stdin is not a TTY at all
+ * (piped, redirected, CI), nobody can answer a prompt, so the sequential wizard
+ * fails fast with actionable guidance rather than hanging — see
+ * {@link runSequentialSetup}.
+ */
+import { Command } from "commander";
+import { createConfigManager } from "../config/index.js";
+import { runSequentialSetup, SequentialSetupUnavailableError } from "./setup/sequential.js";
+/**
+ * Whether the full-screen Ink wizard can run. It needs interactive input *and*
+ * output plus raw-mode support for its keyboard handling; anything short of
+ * that drops to the sequential readline wizard. Kept as a pure function of the
+ * streams so the decision is unit-testable without a real terminal.
+ */
+export function canRenderInkSetup(stdin = process.stdin, stdout = process.stdout) {
+    return Boolean(stdin.isTTY) && Boolean(stdout.isTTY) && typeof stdin.setRawMode === "function";
+}
+export function createSetupCommand() {
+    return new Command("setup")
+        .description("Guided one-time setup for the local ProPR stack")
+        .option("--root <dir>", "Stack root directory (where .env/data/logs/repos live)")
+        .option("--no-tui", "Skip the full-screen wizard; prompt line-by-line instead")
+        .option("--skip-remote-image-check", "Skip the slow registry round-trip when checking that stack images exist")
+        .addHelpText("after", `
+Examples:
+  $ propr setup
+  $ propr setup --no-tui
+  $ propr setup --root ~/propr
+  $ propr setup --skip-remote-image-check
+
+Setup is safe to re-run at any time: it re-discovers your environment and skips
+steps that are already satisfied, so running it again only fills in what is
+missing — it never undoes existing configuration.
+
+The full-screen wizard runs in an interactive terminal. Over SSH, in shells
+without raw-mode support, or with --no-tui, setup falls back to line-by-line
+prompts. When stdin is not a terminal at all (piped, redirected, CI), setup
+cannot prompt and exits with guidance — scaffold non-interactively instead with
+\`propr init stack\`, then edit <root>/.env and run \`propr start\`.
+`)
+        .action(async (options) => {
+        try {
+            const configManager = await createConfigManager();
+            const { skipRemoteImageCheck } = options;
+            const useInk = options.tui !== false && canRenderInkSetup();
+            if (useInk) {
+                // Loaded dynamically so the sequential path never pulls in ink/react.
+                const { renderSetupWizard } = await import("../tui/app.js");
+                const result = await renderSetupWizard({
+                    configManager,
+                    root: options.root,
+                    skipRemoteImageCheck,
+                });
+                process.exit(result.completed ? 0 : 1);
+            }
+            const result = await runSequentialSetup({
+                configManager,
+                root: options.root,
+                skipRemoteImageCheck,
+            });
+            process.exit(result.completed ? 0 : 1);
+        }
+        catch (error) {
+            if (error instanceof SequentialSetupUnavailableError) {
+                // Already actionable guidance — print it verbatim, no "Error:" prefix.
+                console.error(error.message);
+                process.exit(1);
+            }
+            console.error(`Error during setup: ${error.message}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/stackCommands.js

@@ -6,7 +6,7 @@
 import { Command } from "commander";
 import { createConfigManager } from "../config/index.js";
 import { getHostConfig } from "../orchestrator/index.js";
-import { renderStatusTable } from "../orchestrator/format.js";
+import { renderStatusTable, renderTunnelSection } from "../orchestrator/format.js";
 import { printOutput } from "../utils/index.js";
 /** Creates the `status` command — local stack status. */
 export function createStackStatusCommand() {
@@ -30,10 +30,22 @@ Examples:
                 process.exit(1);
             }
             const status = orch.getStackStatus(cfg);
-            if (printOutput(status, options.json ?? false))
+            // The Cloudflare tunnel is a local managed service, so its health is part
+            // of local status. The reachability probe is best-effort with its own
+            // timeout and never throws, so it cannot fail the status command.
+            const tunnel = await orch.getTunnelStatus(cfg, status);
+            if (printOutput({ ...status, tunnel }, options.json ?? false))
                 return;
             console.log("");
             console.log(renderStatusTable(status));
+            // The tunnel is an optional service most stacks never use. Only show the
+            // human-readable Tunnel section when it is configured or enabled, so the
+            // common case isn't cluttered with an all-"no" block. (The --json output
+            // above always includes the `tunnel` key for scripted consumers.)
+            if (tunnel.configured || tunnel.enabled) {
+                console.log("");
+                console.log(renderTunnelSection(tunnel));
+            }
             console.log("");
             if (!status.running) {
                 console.log("Stack is not running. Start it with: propr start");

package/dist/commands/systemCommands.js

@@ -40,7 +40,13 @@ function displaySystemStatus(status) {
         "Worker",
         "Workers Active",
         "GitHub Auth",
+        "GitHub Auth Mode",
+        "GitHub Event Intake",
         "Claude Auth",
+        "Routing URL",
+        "Routing WebSocket",
+        "Last Delivery ID",
+        "Last ACK",
         "Timestamp",
     ];
     const maxLabelWidth = Math.max(...labels.map((l) => l.length));
@@ -52,16 +58,49 @@ function displaySystemStatus(status) {
         console.log(`${"Workers Active".padEnd(maxLabelWidth)}  ${status.workerCount}`);
     }
     console.log(`${"GitHub Auth".padEnd(maxLabelWidth)}  ${formatStatusIndicator(status.githubAuth)}`);
+    if (status.githubAuthMode) {
+        console.log(`${"GitHub Auth Mode".padEnd(maxLabelWidth)}  ${status.githubAuthMode}`);
+    }
+    if (status.githubEventIntake) {
+        console.log(`${"GitHub Event Intake".padEnd(maxLabelWidth)}  ${status.githubEventIntake}`);
+    }
     console.log(`${"Claude Auth".padEnd(maxLabelWidth)}  ${formatStatusIndicator(status.claudeAuth)}`);
+    // Routing WebSocket diagnostics for default (routing_websocket) deployments.
+    const routingIntakeActive = status.githubEventIntake === "routing_websocket";
+    if (status.routing) {
+        const routing = status.routing;
+        console.log("");
+        console.log(`${"Routing URL".padEnd(maxLabelWidth)}  ${routing.routingUrl || "(not set)"}`);
+        console.log(`${"Routing WebSocket".padEnd(maxLabelWidth)}  ${formatStatusIndicator(routing.connected ? "connected" : "disconnected")}`);
+        console.log(`${"Last Delivery ID".padEnd(maxLabelWidth)}  ${routing.lastDeliveryId ?? "(none yet)"}`);
+        console.log(`${"Last ACK".padEnd(maxLabelWidth)}  ${routing.lastAckAt ? new Date(routing.lastAckAt).toLocaleString() : "(none yet)"}`);
+    }
+    else if (routingIntakeActive) {
+        // routing_websocket is the active intake mode but the daemon published no
+        // routing state — the default event path is not diagnosable (publisher down
+        // or daemon not running). Surface it explicitly rather than rendering nothing.
+        console.log("");
+        console.log(`${"Routing WebSocket".padEnd(maxLabelWidth)}  ${formatStatusIndicator("unknown")} (no routing state published)`);
+    }
     console.log("");
     console.log(`${"Timestamp".padEnd(maxLabelWidth)}  ${new Date(status.timestamp).toLocaleString()}`);
     console.log("");
     console.log("=".repeat(50));
+    // Routing health counts against overall health whenever routing_websocket is the
+    // active intake path: a published-but-disconnected state is unhealthy, and so is
+    // a *missing* state (the daemon publisher is not running), since both mean the
+    // default event path is not delivering. When routing is not the active mode, an
+    // absent routing record is expected and does not affect health.
+    const routingStateMissing = routingIntakeActive && !status.routing;
+    const routingHealthy = status.routing
+        ? status.routing.connected === true
+        : !routingIntakeActive;
     const allHealthy = status.api === "healthy" &&
         status.redis === "connected" &&
         status.daemon === "running" &&
         status.worker === "running" &&
-        status.githubAuth === "connected";
+        status.githubAuth === "connected" &&
+        routingHealthy;
     console.log("");
     if (allHealthy) {
         console.log("All systems operational.");
@@ -78,11 +117,19 @@ function displaySystemStatus(status) {
             console.log("  - No workers active. Check worker processes.");
         }
         if (status.githubAuth !== "connected") {
-            console.log("  - GitHub auth not configured. Check GH_APP_ID, GH_PRIVATE_KEY_PATH, and GH_INSTALLATION_ID.");
+            // githubAuth is derived from the resolved auth mode, so a relay deployment
+            // only lands here when nothing valid is configured — mention both paths.
+            console.log(`  - GitHub auth not configured (mode: ${status.githubAuthMode ?? "unknown"}). Set GH_APP_ID, GH_PRIVATE_KEY_PATH, and GH_INSTALLATION_ID for app auth, or PROPR_GH_RELAY_URL and PROPR_GH_RELAY_TOKEN for relay auth.`);
         }
         if (status.claudeAuth !== "connected") {
             console.log("  - Claude auth status unknown or no recent activity.");
         }
+        if (routingStateMissing) {
+            console.log("  - Routing WebSocket state unavailable. routing_websocket is the active intake mode but the daemon published no routing state; ensure the daemon is running and check its logs.");
+        }
+        else if (!routingHealthy) {
+            console.log("  - Routing WebSocket disconnected. The daemon is not connected to the routing relay; check PROPR_ROUTING_URL / PROPR_GH_RELAY_TOKEN and the daemon logs.");
+        }
     }
 }
 /**