@vigilbase/cli/dist/local/cloudflare-checkup/cf/run-cf.d.ts

Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.

import { CheckupCancelledError, type CancelSignal, type CancelSignalSource } from '../errors.js';
export declare const CF_CALL_TIMEOUT_MS = 45000;
export declare const STDOUT_CAP_BYTES: number;
/** `rulesets get` bodies can be large managed rulesets. */
export declare const RULESET_STDOUT_CAP_BYTES: number;
export declare const STDERR_CAP_BYTES: number;
/** After a cancel, how long withCfRunner waits for `work` to finish (or undo) what it was doing. */
export declare const WORK_SETTLE_MS = 2000;
/**
 * Flags that skip confirmations, switch cf to local simulation or project
 * config, or send a request body. No allowlisted argv contains them; the
 * runner refuses to spawn one that does.
 */
export declare const FORBIDDEN_CF_FLAGS: readonly string[];
export declare function assertSafeCfArgv(argv: readonly string[]): void;
export type CfProcessResult = {
    exitCode: number | null;
    stdout: string;
    stderr: string;
    timedOut: boolean;
    stdoutTooLarge: boolean;
    /** Set when the process could not be started at all. */
    spawnFailed: boolean;
};
export type CfRunOptions = {
    env: Record<string, string>;
    timeoutMs?: number;
    stdoutCapBytes?: number;
};
/** Owns the private working directory and every live cf child. */
export declare class CfProcessRunner {
    readonly entry: string;
    readonly privateDir: string;
    private readonly active;
    private disposed;
    private disposing;
    /** Set by `cancel`: every pending and later call rejects with it. */
    private cancelledBy;
    /** Set once the runner kills its children (abort or shutdown), so those kills are not read as timeouts. */
    private terminating;
    private constructor();
    static create(entry: string): Promise<CfProcessRunner>;
    run(argv: readonly string[], options: CfRunOptions): Promise<CfProcessResult>;
    /**
     * The only interactive cf passthroughs: `cf auth create` (sign-in) and
     * `cf auth delete` (logout). With `stdoutToStderr` (`--json`), cf's stdout
     * is sent to stderr so the CLI's stdout stays a single JSON object.
     */
    runInteractive(argv: readonly string[], env: Record<string, string>, options?: {
        stdoutToStderr?: boolean;
    }): Promise<number>;
    get activeCount(): number;
    /** SIGTERM every live child, then SIGKILL whatever is still running after 2 s. */
    terminateAll(): Promise<void>;
    /** Stop every child and remove the private directory; every caller waits for the same cleanup. */
    dispose(): Promise<void>;
    /** The run was interrupted by `signal`: calls reject with CANCELLED from now on, then everything is disposed. */
    cancel(signal: CancelSignal): Promise<void>;
    get cancellation(): CheckupCancelledError | null;
}
/**
 * Run `work` with a private cf runner; the directory is removed afterwards.
 * On SIGINT, SIGTERM or SIGHUP live children get SIGTERM (then SIGKILL), and
 * this rejects with CANCELLED (`CheckupCancelledError`) once the directory is
 * gone and `work` has settled (every cf call rejects by then; whatever else it
 * waits on gets WORK_SETTLE_MS), so no result of a cancelled run is printed and
 * nothing `work` writes lands after CANCELLED. `work` checks `runner.cancellation`
 * before (and after) writing anything.
 */
export declare function withCfRunner<T>(entry: string, work: (runner: CfProcessRunner) => Promise<T>, signals?: CancelSignalSource): Promise<T>;
export type CfFailure = {
    kind: 'node_unsupported';
} | {
    kind: 'command_unavailable';
} | {
    kind: 'auth';
} | {
    kind: 'http';
    status: number;
} | {
    kind: 'network';
} | {
    kind: 'cf_error';
};
/** ANSI and box-drawing characters removed; lines kept. */
export declare function cleanCfStderr(stderr: string): string;
/**
 * Classify a failed cf call from its stderr, in order: Node version, unknown
 * command, auth without an HTTP status, the HTTP status line
 * (`${status} ${text}[ · HTTP <path>]`), network, anything else. cf wraps
 * messages at the terminal width, so word patterns run over collapsed text.
 */
export declare function classifyCfStderr(stderr: string): CfFailure;
/**
 * Parse cf stdout: lists print a bare JSON array, gets a bare object. cf prints
 * nothing for a `null` result, so an empty get is `null` (the projectors decide).
 */
export declare function parseCfJson(stdout: string, shape: 'array' | 'object'): {
    ok: true;
    value: unknown;
} | {
    ok: false;
};