framework/dist/preflight.d.ts

The (AI) Framework: turnkey, zero-config AI orchestration that wraps a coding-agent CLI (Claude Code) as a black box and takes you from an idea to a running app. Vite for AI.

import { type DriverName } from './driver-cli.js';
/**
 * Preflight checks for a live agent. A turnkey tool should fail *early and
 * clearly* when a prerequisite is missing, not spawn a broken process mid-run.
 * The main one: is the wrapped driver's CLI actually installed and runnable?
 * A fake session needs none of this, so preflight only gates live agents.
 *
 * It probes the driver the session actually picked (#542), so a `codex` session is
 * checked against `codex` and fails on `codex` being missing, not `claude`.
 *
 * Installed is not the same as usable (#1326). Our first external-user report (#1323) was a
 * CLI that resolved fine and was logged out, under a daemon started with `sudo`: every session
 * died before writing its agent.json, on both agents, across six projects, while the daemon went
 * on spending a branch and a worktree per attempt. So preflight also asks the CLI whether it is
 * authenticated, and says so when the daemon runs as root.
 */
/** One preflight check's outcome. */
export interface PreflightCheck {
    name: string;
    ok: boolean;
    /** Human-readable detail: the version when ok, or how to fix it when not. */
    detail: string;
    /**
     * A problem worth saying out loud that must not block the agent. Root is the case: a container
     * legitimately runs everything as root, so refusing to start there would break more than it
     * explains.
     */
    warn?: boolean;
}
/** The result of running all preflight checks. */
export interface PreflightResult {
    ok: boolean;
    checks: PreflightCheck[];
}
/**
 * Run `<bin> <args>` and report whether it succeeded and everything it said. Injectable so
 * tests need no real CLI.
 *
 * `output` merges stdout and stderr on purpose: the two CLIs disagree about where a status line
 * belongs, and a check reading only stdout would call a CLI that answered on stderr "could not
 * say".
 */
export type CliProbe = (bin: string, args: readonly string[]) => Promise<{
    ok: boolean;
    output: string;
}>;
/** Options for {@link preflight}. */
export interface PreflightOptions {
    /** The agent to check for. Default `"claude"`. */
    driver?: DriverName;
    /** The CLI binary to probe. Default the agent's own. */
    bin?: string;
    /** CLI probe override (tests). Default runs the real binary. */
    probe?: CliProbe;
    /** Root check override (tests). Default reads this process's uid. */
    isRoot?: () => boolean;
    /** The invoking user `sudo` recorded, named in the root warning. Default read from the environment. */
    sudoUser?: string | undefined;
    /**
     * Also check `gh` (#1419): the agent's PR/merge rung is armed, and the handoff opens and merges
     * PRs through the GitHub CLI. Missing or logged-out `gh` warns without blocking — the agent
     * itself starts fine and the push rung is plain git; only the PR onward would silently degrade.
     */
    publish?: boolean;
}
/**
 * Run the preflight checks: Node is implicit (we are running), the picked driver's CLI must be
 * installed, and it must be logged in. Returns every check plus an overall `ok`, which counts
 * failures only, so a warning travels without blocking anything.
 *
 * The auth probe is skipped when the CLI is missing: a binary that does not resolve cannot
 * answer a second question, and one "not found" beats two lines saying the same thing.
 */
export declare function preflight(opts?: PreflightOptions): Promise<PreflightResult>;
/** The failing checks, one line each, the way a user is told what to fix. */
export declare function preflightProblems(result: PreflightResult): string[];
//# sourceMappingURL=preflight.d.ts.map