@wjarka/cezarion 0.10.0-pr30.54

package/dist/server-install/steps.js

@@ -0,0 +1,334 @@
+import { spawn } from 'node:child_process';
+import { randomInt } from 'node:crypto';
+import { isRunnerId } from '../core/agent-runner.js';
+import { detectEnvironment } from '../core/backend-detect.js';
+import { CANCEL, } from './types.js';
+/**
+ * Platform-agnostic step helpers. The star is `sudoStep`: the wizard runs as a
+ * normal account and never escalates silently. It prints the exact command,
+ * lets the operator run it via `sudo` or run it themselves, then proves the box
+ * is actually in the expected state with `verify()` before advancing — and
+ * offers a redo when verification fails.
+ */
+/** Real command runner (Node child_process). */
+export const defaultRunner = {
+    capture(program, args, opts) {
+        // spawn (not execFile) so a secret can be fed via stdin instead of argv.
+        return new Promise((resolve) => {
+            const child = spawn(program, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            child.stdout?.on('data', (d) => (stdout += String(d)));
+            child.stderr?.on('data', (d) => (stderr += String(d)));
+            child.on('error', () => resolve({ code: 127, stdout, stderr }));
+            child.on('close', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+            // A child that exits before draining stdin makes the write emit EPIPE;
+            // swallow it so `capture` never crashes the CLI.
+            child.stdin?.on('error', () => { });
+            if (opts?.input != null)
+                child.stdin?.end(opts.input);
+            else
+                child.stdin?.end();
+        });
+    },
+    interactive(program, args, opts) {
+        return new Promise((resolve) => {
+            // With `input`, stdin is piped (sudo still prompts on /dev/tty, not stdin).
+            // `env` adds variables for in-child `$VAR` expansion — the other secret
+            // channel besides stdin that keeps values out of argv.
+            const child = spawn(program, args, {
+                stdio: [opts?.input != null ? 'pipe' : 'inherit', 'inherit', 'inherit'],
+                env: opts?.env ? { ...process.env, ...opts.env } : undefined,
+            });
+            child.on('error', () => resolve(127));
+            child.on('close', (code) => resolve(code ?? 0));
+            if (opts?.input != null) {
+                child.stdin?.on('error', () => { }); // EPIPE if the child exits early
+                child.stdin?.end(opts.input);
+            }
+        });
+    },
+};
+/** Run a probe and assert its result. Returns false in dry-run (nothing is verifiably present). */
+export async function verifyCommand(ctx, program, args, matcher = (r) => r.code === 0) {
+    if (ctx.dryRun)
+        return false;
+    return matcher(await ctx.runner.capture(program, args));
+}
+/**
+ * True when `sudo -n true` succeeds — the box grants passwordless sudo, OR a
+ * sudo timestamp from an earlier command in this session is still cached.
+ * Both mean "sudo will run right now without prompting", which is exactly the
+ * question `--yes` mode needs answered before choosing sudo over delegate.
+ */
+export async function hasPasswordlessSudo(ctx) {
+    if (ctx.dryRun)
+        return false;
+    return (await ctx.runner.capture('sudo', ['-n', 'true'])).code === 0;
+}
+/** A bare DNS hostname — no scheme, no path, no shell/nginx metacharacters. */
+export const HOSTNAME_RE = /^(?=.{1,253}$)([a-z0-9](-?[a-z0-9])*\.)+[a-z]{2,}$/i;
+export class StepCancelled extends Error {
+}
+export class StepAborted extends Error {
+}
+/** Thrown from an optional step's `run()` to record it as `skipped` (e.g. certbot DNS not ready). */
+export class StepSkipped extends Error {
+}
+/**
+ * A strong random cockpit password: guaranteed to mix lower/upper letters, a
+ * digit and a symbol, drawn from a crypto RNG, with visually-ambiguous glyphs
+ * (0/O/1/l/I) removed. Offered by the identity step so operators don't fall back
+ * to a weak hand-picked password.
+ */
+export function generatePassword(length = 16) {
+    const lower = 'abcdefghijkmnpqrstuvwxyz'; // no l
+    const upper = 'ABCDEFGHJKLMNPQRSTUVWXYZ'; // no I, O
+    const digits = '23456789'; // no 0, 1
+    const symbols = '!@#$%^&*-_=+';
+    const all = lower + upper + digits + symbols;
+    const pick = (set) => set.charAt(randomInt(set.length));
+    const chars = [pick(lower), pick(upper), pick(digits), pick(symbols)];
+    while (chars.length < Math.max(length, 8))
+        chars.push(pick(all));
+    // Fisher–Yates shuffle so the guaranteed-class chars aren't always in front.
+    for (let i = chars.length - 1; i > 0; i--) {
+        const j = randomInt(i + 1);
+        const tmp = chars[i];
+        chars[i] = chars[j];
+        chars[j] = tmp;
+    }
+    return chars.join('');
+}
+/**
+ * Execute one privileged command with the operator in the loop:
+ * print → run-via-sudo OR delegate → verify → redo-on-mismatch.
+ *
+ * - Dry-run: prints the intended command and returns (no exec, no verify).
+ * - `--yes` with passwordless sudo: runs non-interactively.
+ * - `--yes` without passwordless sudo: falls back to delegate (never blocks on a hidden prompt).
+ *
+ * Throws `StepCancelled` if the user cancels, `StepAborted` if they give up after a failed verify.
+ */
+/** Single-quote a shell string so a copy-paste of `display` runs exactly what we run. */
+export function shquote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export async function sudoStep(ctx, opts) {
+    const { ui } = ctx;
+    // What we actually run — and what the operator copy-pastes in the delegate path.
+    const display = `sudo bash -lc ${shquote(opts.command)}`;
+    if (ctx.dryRun) {
+        ui.info(opts.input != null
+            ? `DRY RUN — would run: ${display} (with the ${opts.inputLabel ?? 'payload'} on stdin)`
+            : `DRY RUN — would run: ${display}`);
+        return;
+    }
+    const passwordless = await hasPasswordlessSudo(ctx);
+    for (;;) {
+        ui.info(opts.description);
+        if (opts.note)
+            ui.message(opts.note);
+        ui.message(display);
+        let mode;
+        if (ctx.assumeYes) {
+            mode = passwordless ? 'sudo' : 'delegate';
+        }
+        else if (ctx.prefs.sudoMode) {
+            // Remembered from an earlier answer — don't ask again this run (issue #6).
+            mode = ctx.prefs.sudoMode;
+        }
+        else {
+            // Default to "I'll run it myself as root" — the safe, no-surprise choice
+            // for operators who prefer to paste privileged commands into a root shell.
+            const choice = await ui.select({
+                message: 'How should this privileged command run?',
+                options: [
+                    { value: 'delegate', label: "I'll run it myself as root", hint: 'paste & run as root, then confirm' },
+                    { value: 'sudo', label: 'Run it now via sudo', hint: 'streams output here' },
+                ],
+                initialValue: 'delegate',
+            });
+            if (choice === CANCEL)
+                throw new StepCancelled();
+            mode = choice;
+            ctx.prefs.sudoMode = choice; // reuse this choice for every later privileged command
+        }
+        if (mode === 'sudo') {
+            const code = await ctx.runner.interactive('sudo', ['bash', '-lc', opts.command], opts.input != null ? { input: opts.input } : undefined);
+            if (code !== 0)
+                ui.warn(`command exited with code ${code}`);
+        }
+        else {
+            ui.info('Copy the command above and run it as root on the server (paste into a root shell, or prefix with sudo), then confirm below.');
+            if (opts.input != null) {
+                // Screen-only: pasted as stdin it stays out of argv AND shell history.
+                ui.info(`The command reads from stdin — after starting it, paste this ${opts.inputLabel ?? 'line'} and press Ctrl-D:`);
+                ui.message(opts.input);
+            }
+            if (!ctx.assumeYes) {
+                const done = await ui.confirm({ message: 'Have you run it as root?', initialValue: true });
+                if (done === CANCEL)
+                    throw new StepCancelled();
+            }
+        }
+        if (await opts.verify(ctx)) {
+            ui.success('Verified.');
+            return;
+        }
+        ui.error('That did not take effect — the verification check still fails.');
+        if (ctx.assumeYes) {
+            throw opts.skippable
+                ? new StepSkipped(`verification failed for: ${opts.command}`)
+                : new StepAborted(`verification failed for: ${opts.command}`);
+        }
+        if (opts.skippable) {
+            const next = await ui.select({
+                message: 'That did not verify. What now?',
+                options: [
+                    { value: 'retry', label: 'Try again' },
+                    { value: 'skip', label: 'Skip this step', hint: opts.skipHint },
+                ],
+                initialValue: 'retry',
+            });
+            if (next === CANCEL)
+                throw new StepCancelled();
+            if (next === 'skip')
+                throw new StepSkipped(`skipped: ${opts.command}`);
+            continue;
+        }
+        const redo = await ui.confirm({ message: 'Try again?', initialValue: true });
+        if (redo === CANCEL || redo === false)
+            throw new StepAborted(`gave up on: ${opts.command}`);
+    }
+}
+/** Convenience: an `owned` file/service/etc. artifact. */
+export function owned(type, fields) {
+    return { kind: 'owned', type, ...fields };
+}
+/** Convenience: a `shared` artifact (listed, not removed, on uninstall). */
+export function shared(type, fields) {
+    return { kind: 'shared', type, ...fields };
+}
+export function depCheckStep(opts = {}) {
+    const detect = opts.detect ?? detectEnvironment;
+    const install = opts.installTool ?? aptInstallTool;
+    const hintFor = opts.removeHint ?? removeHintFor;
+    return {
+        id: 'deps',
+        title: 'Dependencies (agent CLIs + gh)',
+        async check(ctx) {
+            if (ctx.dryRun)
+                return false;
+            const checks = await detect();
+            // Satisfied when at least one agent CLI is present and authed. Derived from RUNNER_IDS,
+            // never a literal list: `BackendCheck['name']` also carries the non-agent tools (`gh`,
+            // `git`), so the gate has to filter — and a hand-written array silently under-counts the
+            // moment a runner is added (a pi-only host reporting "no agent CLI", #387 review).
+            return checks.some((c) => isRunnerId(c.name) && c.available);
+        },
+        async run(ctx) {
+            const checks = await detect();
+            const missing = checks.filter((c) => !c.available && c.name !== 'git');
+            if (missing.length === 0) {
+                ctx.ui.success('All dependencies present.');
+                return { artifacts: [] };
+            }
+            const pick = await ctx.ui.multiselect({
+                message: 'Missing tools — select the ones to install',
+                options: missing.map((c) => ({ value: c.name, label: c.name, hint: c.hint })),
+                required: false,
+            });
+            if (pick === CANCEL)
+                throw new StepCancelled();
+            const installed = [];
+            for (const name of pick) {
+                const check = missing.find((c) => c.name === name);
+                await install(ctx, name);
+                installed.push(shared('package', { name, removeHint: hintFor(name) }));
+                if (check?.hint)
+                    ctx.ui.note(check.hint, `Authorize ${name}`);
+            }
+            return { artifacts: installed };
+        },
+        async undo(ctx, created) {
+            // Dependencies are `shared` — never auto-removed. List them for the operator.
+            const pkgs = created?.artifacts ?? [];
+            if (pkgs.length === 0)
+                return;
+            ctx.ui.note(pkgs.map((a) => a.removeHint ?? a.name ?? '').filter(Boolean).join('\n'), 'These tools were installed for cezar but may be used elsewhere — remove manually if you want them gone');
+        },
+    };
+}
+const NPM_GLOBAL = {
+    claude: '@anthropic-ai/claude-code',
+    codex: '@openai/codex',
+};
+/** Ubuntu/Debian installer: apt for gh, sudo npm -g for the agent CLIs (system node). */
+export const aptInstallTool = async (ctx, name) => {
+    if (name === 'gh') {
+        await sudoStep(ctx, {
+            description: 'Install the GitHub CLI (only needed for PR creation).',
+            command: 'apt-get update && apt-get install -y gh',
+            verify: (c) => verifyCommand(c, 'gh', ['--version']),
+        });
+        return;
+    }
+    await installViaNpmOrNote(ctx, name, true);
+};
+/** macOS installer: brew (no sudo) for gh, npm -g for the agent CLIs. */
+export const brewInstallTool = async (ctx, name) => {
+    if (name === 'gh') {
+        if (ctx.dryRun) {
+            ctx.ui.info('DRY RUN — would run: brew install gh');
+            return;
+        }
+        await ctx.runner.interactive('brew', ['install', 'gh']);
+        return;
+    }
+    await installViaNpmOrNote(ctx, name, false);
+};
+async function installViaNpmOrNote(ctx, name, sudo) {
+    if (name === 'opencode') {
+        ctx.ui.note('Install OpenCode from https://opencode.ai, then re-run.', 'opencode');
+        return;
+    }
+    const pkg = NPM_GLOBAL[name];
+    if (!pkg) {
+        ctx.ui.warn(`no known installer for ${name} — install it manually`);
+        return;
+    }
+    if (sudo) {
+        await sudoStep(ctx, {
+            description: `Install ${name} globally via npm.`,
+            command: `npm install -g ${pkg}`,
+            verify: (c) => verifyCommand(c, name, ['--version']),
+        });
+        return;
+    }
+    if (ctx.dryRun) {
+        ctx.ui.info(`DRY RUN — would run: npm install -g ${pkg}`);
+        return;
+    }
+    await ctx.runner.interactive('npm', ['install', '-g', pkg]);
+}
+function removeHintFor(name) {
+    const npm = {
+        claude: 'npm rm -g @anthropic-ai/claude-code',
+        codex: 'npm rm -g @openai/codex',
+    };
+    if (name === 'gh')
+        return 'sudo apt-get remove -y gh';
+    return npm[name] ?? `# remove ${name} manually`;
+}
+/** macOS-flavored removal hints (brew instead of apt). */
+export function brewRemoveHint(name) {
+    const npm = {
+        claude: 'npm rm -g @anthropic-ai/claude-code',
+        codex: 'npm rm -g @openai/codex',
+    };
+    if (name === 'gh')
+        return 'brew uninstall gh';
+    return npm[name] ?? `# remove ${name} manually`;
+}
+//# sourceMappingURL=steps.js.map

package/dist/server-install/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/server-install/steps.ts"],"names":[],"mappings":"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"}

package/dist/server-install/strategies.d.ts

@@ -0,0 +1,4 @@
+import { type PlatformId, type PlatformStrategy } from './types.ts';
+export declare function getStrategy(id: string): PlatformStrategy | undefined;
+/** Ids that actually have a registered strategy (a subset of PLATFORM_IDS while phased). */
+export declare function availablePlatformIds(): PlatformId[];

package/dist/server-install/strategies.js

@@ -0,0 +1,20 @@
+import { macosxNgrok } from './platforms/macosx-ngrok.js';
+import { ubuntuVps } from './platforms/ubuntu-vps.js';
+import { PLATFORM_IDS } from './types.js';
+/**
+ * Platform registry. `--platform <id>` is validated against these keys; an
+ * unknown id lists the valid ones and exits 1. Add a strategy here to teach the
+ * wizard a new platform — the engine and helpers are untouched.
+ */
+const REGISTRY = {
+    'ubuntu-vps': ubuntuVps,
+    'macosx-ngrok': macosxNgrok,
+};
+export function getStrategy(id) {
+    return REGISTRY[id];
+}
+/** Ids that actually have a registered strategy (a subset of PLATFORM_IDS while phased). */
+export function availablePlatformIds() {
+    return PLATFORM_IDS.filter((id) => REGISTRY[id] !== undefined);
+}
+//# sourceMappingURL=strategies.js.map

package/dist/server-install/strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/server-install/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,YAAY,EAA0C,MAAM,YAAY,CAAC;AAElF;;;;GAIG;AACH,MAAM,QAAQ,GAAkD;IAC9D,YAAY,EAAE,SAAS;IACvB,cAAc,EAAE,WAAW;CAC5B,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,QAAQ,CAAC,EAAgB,CAAC,CAAC;AACpC,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC;AACjE,CAAC"}

package/dist/server-install/types.d.ts

@@ -0,0 +1,287 @@
+import { z } from 'zod';
+/**
+ * Contracts for the server installer (spec 2026-07-16-server-installer).
+ * The engine closes over `InstallStep` / `PlatformStrategy` and never learns
+ * what a step *does* — only `check` / `run` / `undo`. That seam is what makes
+ * "use ubuntu as a selector and run it that way" a registry lookup, and what
+ * makes the interactive helpers reusable across every future platform.
+ */
+/** The platforms the registry knows. Extend here + add a strategy file. */
+export declare const PLATFORM_IDS: readonly ['ubuntu-vps', 'macosx-ngrok'];
+export type PlatformId = (typeof PLATFORM_IDS)[number];
+/** Per-step lifecycle. `failed` resumes identically to `pending`. */
+export declare const STEP_STATUSES: readonly ['pending', 'done', 'skipped', 'failed'];
+export type StepStatus = (typeof STEP_STATUSES)[number];
+/**
+ * One thing a step created, tagged by who owns its removal:
+ *  - `owned`  — cezar authored it and nothing else uses it → uninstall removes it.
+ *  - `shared` — a system tool the operator may now depend on (gh, agent CLIs,
+ *    certbot + its renewal timer, the cert itself) → uninstall lists it with a
+ *    manual removal hint instead of yanking it.
+ */
+export declare const stepArtifactSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        owned: "owned";
+        shared: "shared";
+    }>;
+    type: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    removeHint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StepArtifact = z.infer<typeof stepArtifactSchema>;
+/** What a step returns from `run()`; `undo()` receives it back verbatim. */
+export declare const stepCreatedSchema: z.ZodNullable<z.ZodObject<{
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            owned: "owned";
+            shared: "shared";
+        }>;
+        type: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        removeHint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>>;
+export type StepCreated = z.infer<typeof stepCreatedSchema>;
+/**
+ * Persisted per-step outcome — the `steps` map in `server.json`. A status this
+ * version doesn't know (written by a newer cezar) degrades to `failed`, which
+ * keeps the record AND keeps it on uninstall's undo path — never to a parse
+ * failure that would discard the whole ledger.
+ */
+export declare const stepOutcomeSchema: z.ZodObject<{
+    status: z.ZodCatch<z.ZodEnum<{
+        done: "done";
+        failed: "failed";
+        pending: "pending";
+        skipped: "skipped";
+    }>>;
+    created: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                owned: "owned";
+                shared: "shared";
+            }>;
+            type: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodString>;
+            removeHint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type StepOutcome = z.infer<typeof stepOutcomeSchema>;
+/**
+ * `~/.cezar/server.json` — host-level, install-once. Additive-safe: every new
+ * field is optional / defaulted so an older cezar still parses a newer file
+ * (BACKWARD_COMPATIBILITY cross-version-state rule). No secrets live here.
+ */
+export declare const serverStateSchema: z.ZodObject<{
+    schema: z.ZodCatch<z.ZodLiteral<1>>;
+    platform: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    instance: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    domain: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    externalProxy: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    bindHost: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    installed: z.ZodCatch<z.ZodDefault<z.ZodBoolean>>;
+    dryRun: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    createdAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    updatedAt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    primaryPort: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    publicUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    ephemeral: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    steps: z.ZodCatch<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodObject<{
+        status: z.ZodCatch<z.ZodEnum<{
+            done: "done";
+            failed: "failed";
+            pending: "pending";
+            skipped: "skipped";
+        }>>;
+        created: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    owned: "owned";
+                    shared: "shared";
+                }>;
+                type: z.ZodString;
+                path: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+                scope: z.ZodOptional<z.ZodString>;
+                removeHint: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>>>;
+}, z.core.$loose>;
+export type ServerState = z.infer<typeof serverStateSchema>;
+/** Freshly-initialized state (no install yet). */
+export declare function freshServerState(): ServerState;
+/**
+ * The interactive surface a step talks to. Implemented by `ui.ts` over
+ * `@clack/prompts`; declared here as a pure interface so `types.ts` (and the
+ * engine) never import the TUI library. Prompt methods resolve to the
+ * `CANCEL` sentinel instead of throwing when the user aborts.
+ */
+export declare const CANCEL: unique symbol;
+export type Cancellable<T> = T | typeof CANCEL;
+export interface SpinnerHandle {
+    start(message?: string): void;
+    stop(message?: string): void;
+    message(message: string): void;
+}
+export interface Ui {
+    intro(message: string): void;
+    outro(message: string): void;
+    note(message: string, title?: string): void;
+    /**
+     * Plain, un-boxed output — no border/table drawing. Use for shell commands and
+     * other content that a `note()` box would mangle when it wraps (long base64
+     * file-writes, certbot lines). Renders verbatim so it stays copy-pasteable.
+     */
+    message(message: string): void;
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    select<T>(opts: {
+        message: string;
+        options: Array<{
+            value: T;
+            label: string;
+            hint?: string;
+        }>;
+        initialValue?: T;
+    }): Promise<Cancellable<T>>;
+    multiselect<T>(opts: {
+        message: string;
+        options: Array<{
+            value: T;
+            label: string;
+            hint?: string;
+        }>;
+        required?: boolean;
+    }): Promise<Cancellable<T[]>>;
+    confirm(opts: {
+        message: string;
+        initialValue?: boolean;
+    }): Promise<Cancellable<boolean>>;
+    text(opts: {
+        message: string;
+        placeholder?: string;
+        initialValue?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<Cancellable<string>>;
+    password(opts: {
+        message: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<Cancellable<string>>;
+    spinner(): SpinnerHandle;
+}
+/** Result of running a command with captured output. */
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Command execution seam. The engine supplies a real implementation; tests
+ * inject a fake so `sudoStep` / `verifyCommand` are exercised without touching
+ * the host. In `CEZ_DRY_RUN`, side-effecting runs are short-circuited by the
+ * step helpers, not the runner.
+ */
+export interface Runner {
+    /**
+     * Capture stdout/stderr; never throws on non-zero exit (returns the code).
+     * `opts.input` is written to the child's stdin — use it to pass secrets
+     * (passwords, tokens) so they never appear in the process's argv.
+     */
+    capture(program: string, args: string[], opts?: {
+        input?: string;
+    }): Promise<CommandResult>;
+    /**
+     * Inherit stdio (streams live output). Resolves with the exit code.
+     * `opts.input` pipes the child's stdin instead of inheriting it — the
+     * secret-passing channel for privileged commands (`cat > file` style), so
+     * credentials never ride in argv where `ps` can read them.
+     */
+    interactive(program: string, args: string[], opts?: {
+        input?: string;
+        env?: Record<string, string>;
+    }): Promise<number>;
+}
+/** Live install/uninstall context, threaded through every step. */
+export interface InstallContext {
+    state: ServerState;
+    ui: Ui;
+    runner: Runner;
+    /**
+     * Instance id (slug) this run targets. `default` (the original single-cockpit
+     * flow) keeps every legacy path unchanged; a domain-derived slug suffixes the
+     * nginx site, htpasswd, and systemd unit so instances never collide on one
+     * host. Steps read this to build their instance-scoped paths.
+     */
+    instance: string;
+    /** Atomically persist `state` to this instance's `~/.cezar` record. */
+    save(): Promise<void>;
+    /** CEZ_DRY_RUN — no real sudo, package installs, or network. */
+    dryRun: boolean;
+    /** `--yes`: auto-accept safe defaults; never invents a sudo password. */
+    assumeYes: boolean;
+    /** Step ids the user asked to force-rerun via `--reconfigure`. */
+    reconfigure: ReadonlySet<string>;
+    /** Repo root the autostart service should run `cezar serve` in. */
+    repoRoot: string;
+    /** ISO timestamp for this run (passed in — Date.now guard). */
+    now: string;
+    /**
+     * Choices remembered for the rest of the run so the wizard stops re-asking.
+     * `sudoMode` is set the first time the operator answers the sudo-vs-delegate
+     * prompt — once they pick "I'll run it myself as root", every later privileged
+     * command reuses that choice instead of prompting again.
+     *
+     * `cockpit` holds the credentials just set, IN MEMORY ONLY (never persisted to
+     * `server.json`), so the final verify step can make a real authenticated
+     * request through the proxy. Absent on a resume where the proxy step was
+     * already done — the verify step then falls back to structural checks.
+     */
+    prefs: {
+        sudoMode?: 'sudo' | 'delegate';
+        cockpit?: {
+            user: string;
+            password: string;
+        };
+    };
+}
+export interface InstallStep {
+    /** Stable — the key in `server.json`. Never rename once it has landed. */
+    id: string;
+    title: string;
+    /** Optional steps (SSL, autostart) can be skipped without failing install. */
+    optional?: boolean;
+    /** True ⇒ already satisfied, engine skips (unless `--reconfigure` names it). */
+    check(ctx: InstallContext): Promise<boolean>;
+    /** Do it, interactively. Return what was created (or null). */
+    run(ctx: InstallContext): Promise<StepCreated>;
+    /** Reverse it, given back the recorded `created`. */
+    undo(ctx: InstallContext, created: StepCreated): Promise<void>;
+}
+export interface PlatformStrategy {
+    id: PlatformId;
+    label: string;
+    /** OS / arch / privilege sanity. Throw `PreflightError` to refuse politely. */
+    preflight(ctx: InstallContext): Promise<void>;
+    /** Ordered steps for this platform. */
+    steps(ctx: InstallContext): InstallStep[];
+    /**
+     * Reload the running cockpit to pick up a new cezar version (a fresh local
+     * build or a newly published `cezarion`) — the standardized `server-deploy`
+     * entry point. Typically: restart the service + re-verify. Throw `StepAborted`
+     * to report a failed deploy.
+     */
+    redeploy?(ctx: InstallContext): Promise<void>;
+}
+/** Thrown by `preflight` to stop with a clean, user-facing reason (no stack). */
+export declare class PreflightError extends Error {
+}