@vigilbase/cli 0.1.4 → 0.2.1

package/dist/local/cloudflare-checkup/cf/install.js

@@ -0,0 +1,308 @@
+/**
+ * The Vigilbase-managed install of Cloudflare's cf (spec "one command", decision 5).
+ *
+ * When no usable cf is found, the full flow may install the pinned release
+ * into `<configDir>/cf/<version>/` with the npm that ships with this Node:
+ *
+ * - npm runs as `process.execPath <npm-cli.js> install --prefix <staging> …`
+ *   with no shell, from the fresh 0700 staging directory, with the user's
+ *   environment (npm needs their npmrc, proxy and CA settings) minus every
+ *   `CF_*` / `CLOUDFLARE_*` variable and, defensively, any variable whose
+ *   value holds a session code, a verification token or `--email`. (npx 10
+ *   passes arguments only in argv, not in the environment:
+ *   `npm_lifecycle_script` is just the bin name.)
+ * - `--ignore-scripts`: cf runs `--version`, `--dry-run` and API reads without
+ *   lifecycle scripts. `--omit=optional`: the optional dependencies are the
+ *   workerd and sharp platform binaries (about 150 MB). In cf 1.0.0-beta.13
+ *   they are loaded only by `--local` mode and the `workers`, `deploy` and
+ *   `previews` command trees (static and dynamic import graph of
+ *   `dist/*.mjs`), none of which the checkup runs; see LOCAL.md.
+ * - Integrity is pinned: after npm exits, the staging lockfile must record
+ *   `node_modules/cf` at exactly the pinned version and npm `dist.integrity`,
+ *   and the installed package.json must agree; otherwise the staging
+ *   directory is deleted (CF_INSTALL_FAILED). Only then is it renamed into
+ *   place, so a half-finished install is never used. `locateCf` still applies
+ *   its identity checks to the result.
+ * - Ctrl-C while npm runs kills npm and removes the staging directory. Staging
+ *   directories left by a crash or a closed terminal are removed by the next
+ *   install once they are older than the npm timeout (a concurrent install is
+ *   always younger), and by `logout`.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { LocalCheckupError } from '../errors.js';
+/** The cf release the CLI installs; `integrity` is npm's `dist.integrity` for it. */
+export const MANAGED_CF = Object.freeze({
+    version: '1.0.0-beta.13',
+    integrity: 'sha512-dCjpzCJvjudIu8IQbXCJfy9diFoyHU84D/30K4lJp7jUaBgvjJypsMFzLqvUFOuwhF1ggR/igsLqXyehAOR2FQ==',
+    /** Measured `du` of the install without optional dependencies (darwin-arm64: 73 MB). */
+    approxSize: 'about 75 MB',
+});
+export const NPM_INSTALL_TIMEOUT_MS = 10 * 60_000;
+/** A staging directory older than this is a leftover, never a running install. */
+const STALE_STAGING_MS = NPM_INSTALL_TIMEOUT_MS + 60_000;
+const STAGING_PREFIX = '.staging-';
+const NPM_STDERR_KEEP_BYTES = 64 * 1024;
+const MAX_LOCKFILE_BYTES = 16 * 1024 * 1024;
+export const NPM_STDERR_TAIL_LINES = 20;
+/** A Vigilbase session code or verification token, or a command line naming `--email` (were a launcher to export one). */
+const VIGILBASE_SECRET_MARKER = /vbc[sv]1_|--email\b/;
+/** `<configDir>/cf`: every managed version, plus any leftover staging directory. */
+export function managedCfRoot(configDir) {
+    return path.join(configDir, 'cf');
+}
+export function managedCfInstallDir(configDir, version = MANAGED_CF.version) {
+    return path.join(managedCfRoot(configDir), version);
+}
+export function managedCfPackageDir(installDir) {
+    return path.join(installDir, 'node_modules', 'cf');
+}
+/** The npm arguments after `process.execPath`. */
+export function npmInstallArgv(npmCli, prefix, version = MANAGED_CF.version) {
+    return [npmCli, 'install', '--prefix', prefix, '--no-audit', '--no-fund', '--ignore-scripts', '--omit=optional', `cf@${version}`];
+}
+/**
+ * The npm to run: `npm_execpath` when it names an existing `npm-cli.js` (or
+ * `npx-cli.js`, whose sibling is used), otherwise the npm bundled beside this
+ * Node. `null` when neither exists.
+ */
+export function resolveNpmCli(options = { env: process.env }) {
+    const platform = options.platform ?? process.platform;
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    const exists = options.exists ?? existsSync;
+    const fromEnv = options.env.npm_execpath;
+    if (fromEnv && p.isAbsolute(fromEnv)) {
+        const name = p.basename(fromEnv);
+        const candidate = name === 'npm-cli.js' ? fromEnv : name === 'npx-cli.js' ? p.join(p.dirname(fromEnv), 'npm-cli.js') : null;
+        if (candidate && exists(candidate))
+            return candidate;
+    }
+    const nodeDir = p.dirname(options.execPath ?? process.execPath);
+    const bundled = platform === 'win32'
+        ? p.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js')
+        : p.resolve(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    return exists(bundled) ? bundled : null;
+}
+/** The user's environment minus Cloudflare variables and anything carrying a session code, token or `--email`. */
+export function npmChildEnv(parent) {
+    const env = {};
+    for (const [name, value] of Object.entries(parent)) {
+        if (typeof value !== 'string')
+            continue;
+        if (/^(?:CF_|CLOUDFLARE_)/i.test(name))
+            continue;
+        if (VIGILBASE_SECRET_MARKER.test(value))
+            continue;
+        env[name] = value;
+    }
+    env.npm_config_update_notifier = 'false';
+    return env;
+}
+async function readJsonCapped(file) {
+    const info = await stat(file).catch(() => null);
+    if (!info || !info.isFile() || info.size > MAX_LOCKFILE_BYTES)
+        return undefined;
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when every lockfile npm wrote records `node_modules/cf` at the pinned
+ * version and integrity (at least one must exist), and the installed
+ * package.json has that version.
+ */
+export async function verifyManagedInstall(installDir, pin = MANAGED_CF) {
+    let lockfiles = 0;
+    for (const file of [path.join(installDir, 'package-lock.json'), path.join(installDir, 'node_modules', '.package-lock.json')]) {
+        if (!(await stat(file).catch(() => null)))
+            continue;
+        lockfiles++;
+        const lock = await readJsonCapped(file);
+        const entry = lock?.packages?.['node_modules/cf'];
+        if (!entry || entry.version !== pin.version || entry.integrity !== pin.integrity)
+            return false;
+    }
+    if (lockfiles === 0)
+        return false;
+    const manifest = await readJsonCapped(path.join(managedCfPackageDir(installDir), 'package.json'));
+    return manifest?.version === pin.version;
+}
+/** The managed cf package directory when a verified install exists, else null. */
+export async function findManagedCf(configDir) {
+    const installDir = managedCfInstallDir(configDir);
+    const info = await lstat(installDir).catch(() => null);
+    if (!info || !info.isDirectory() || info.isSymbolicLink())
+        return null;
+    return (await verifyManagedInstall(installDir)) ? managedCfPackageDir(installDir) : null;
+}
+/** Create `dir` 0700 if missing; refuse a symlink or non-directory in its place. */
+export async function ensurePrivateDir(dir) {
+    await mkdir(path.dirname(dir), { recursive: true, mode: 0o700 });
+    await mkdir(dir, { mode: 0o700 }).catch((error) => {
+        if (error.code !== 'EEXIST')
+            throw error;
+    });
+    const info = await lstat(dir);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        throw new Error(`${dir} must be a directory, not a symbolic link or file.`);
+    }
+    if (process.platform !== 'win32' && (info.mode & 0o777) !== 0o700)
+        await chmod(dir, 0o700);
+}
+/** A CF_INSTALL_FAILED error that carries the redacted tail of npm's stderr. */
+export class CfInstallError extends LocalCheckupError {
+    npmOutput;
+    constructor(message, npmOutput = []) {
+        super('CF_INSTALL_FAILED', message);
+        this.npmOutput = npmOutput;
+    }
+}
+const SECRET_LINE = /_auth|_password|authorization|bearer|npm_[A-Za-z0-9]{20,}|vbc[sv]1_|--email\b/i;
+/** The last lines of npm's stderr, dropping any line that could carry a registry credential. */
+export function npmStderrTail(stderr, lines = NPM_STDERR_TAIL_LINES) {
+    return stderr.replace(/\r\n?/g, '\n').split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() !== '' && !SECRET_LINE.test(line))
+        .slice(-lines);
+}
+function runNpm(spawn, args, options) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(process.execPath, args, { shell: false, cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        }
+        catch {
+            resolve({ exitCode: null, stderr: '', timedOut: false, spawnFailed: true });
+            return;
+        }
+        options.onSpawn(child);
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, options.timeoutMs);
+        timer.unref?.();
+        child.stdout?.on('data', () => undefined);
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+            if (stderr.length > NPM_STDERR_KEEP_BYTES)
+                stderr = stderr.slice(-NPM_STDERR_KEEP_BYTES);
+        });
+        const finish = (exitCode, spawnFailed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ exitCode, stderr, timedOut, spawnFailed });
+        };
+        child.once('error', () => finish(null, true));
+        child.once('close', (code) => finish(typeof code === 'number' ? code : null, false));
+    });
+}
+/** Remove `.staging-*` leftovers older than `maxAgeMs`; a younger one may belong to a concurrent install. */
+export async function removeStaleStaging(root, maxAgeMs = STALE_STAGING_MS, now = Date.now()) {
+    const names = await readdir(root).catch(() => []);
+    const removed = [];
+    for (const name of names.filter((candidate) => candidate.startsWith(STAGING_PREFIX)).sort()) {
+        const target = path.join(root, name);
+        const info = await lstat(target).catch(() => null);
+        if (!info || now - info.mtimeMs <= maxAgeMs)
+            continue;
+        await rm(target, { recursive: true, force: true }).then(() => removed.push(name), () => undefined);
+    }
+    return removed;
+}
+/**
+ * Ctrl-C while npm runs: kill npm, wait briefly for it to exit, remove the
+ * staging directory, then exit 130 (as `withCfRunner` does for cf).
+ */
+function onInterrupt(staging, running, before) {
+    return () => {
+        before?.();
+        const child = running();
+        const closed = child && child.exitCode === null && child.signalCode === null
+            ? new Promise((resolve) => {
+                child.once('close', () => resolve());
+                setTimeout(resolve, 2_000).unref?.();
+            })
+            : Promise.resolve();
+        child?.kill('SIGKILL');
+        void closed
+            .then(() => rm(staging, { recursive: true, force: true, maxRetries: 3 }))
+            .catch(() => undefined)
+            .finally(() => process.exit(130));
+    };
+}
+/**
+ * Install the pinned cf into `<configDir>/cf/<version>/` and return its
+ * package directory. Throws CF_INSTALL_FAILED (a `CfInstallError`) when npm
+ * is missing or fails, or the result does not match the pin; the staging
+ * directory is always removed (on Ctrl-C too).
+ */
+export async function installManagedCf(options) {
+    const npmCli = options.npmCli !== undefined ? options.npmCli : resolveNpmCli({ env: options.env });
+    if (!npmCli) {
+        throw new CfInstallError('npm was not found beside this Node.js, so cf cannot be installed automatically.');
+    }
+    const root = managedCfRoot(options.configDir);
+    await ensurePrivateDir(root);
+    await removeStaleStaging(root);
+    // realpath: npm keys its lockfile relative to the real prefix, so a symlinked path would not match `node_modules/cf`.
+    const staging = await realpath(await mkdtemp(path.join(root, `${STAGING_PREFIX}${MANAGED_CF.version}-`)));
+    let npmChild = null;
+    const interrupted = onInterrupt(staging, () => npmChild, options.onInterrupt);
+    process.once('SIGINT', interrupted);
+    try {
+        if (process.platform !== 'win32')
+            await chmod(staging, 0o700);
+        const result = await runNpm(options.spawn ?? nodeSpawn, npmInstallArgv(npmCli, staging), {
+            cwd: staging,
+            env: npmChildEnv(options.env),
+            timeoutMs: options.timeoutMs ?? NPM_INSTALL_TIMEOUT_MS,
+            onSpawn: (child) => { npmChild = child; },
+        });
+        if (result.spawnFailed)
+            throw new CfInstallError('npm could not be started, so cf was not installed.');
+        if (result.timedOut)
+            throw new CfInstallError(`npm did not finish installing cf within ${Math.round((options.timeoutMs ?? NPM_INSTALL_TIMEOUT_MS) / 60_000)} minutes.`, npmStderrTail(result.stderr));
+        if (result.exitCode !== 0)
+            throw new CfInstallError(`npm could not install cf@${MANAGED_CF.version} (exit ${result.exitCode ?? 'signal'}).`, npmStderrTail(result.stderr));
+        if (!(await verifyManagedInstall(staging))) {
+            throw new CfInstallError(`The installed cf does not match the pinned cf@${MANAGED_CF.version} integrity; it was deleted.`);
+        }
+        const installDir = managedCfInstallDir(options.configDir);
+        // A leftover install that failed verification is replaced; a verified one (a concurrent run) is kept unless it is being replaced.
+        if (!options.replace && await findManagedCf(options.configDir))
+            return managedCfPackageDir(installDir);
+        await rm(installDir, { recursive: true, force: true });
+        try {
+            await rename(staging, installDir);
+        }
+        catch {
+            if (await findManagedCf(options.configDir))
+                return managedCfPackageDir(installDir);
+            throw new CfInstallError('The installed cf could not be moved into place.');
+        }
+        return managedCfPackageDir(installDir);
+    }
+    finally {
+        process.removeListener('SIGINT', interrupted);
+        await rm(staging, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** `logout`: remove every managed cf version (and any staging leftovers). */
+export async function removeManagedCf(configDir) {
+    const root = managedCfRoot(configDir);
+    const info = await lstat(root).catch(() => null);
+    if (!info)
+        return { path: root, removed: false };
+    await rm(root, { recursive: true, force: true });
+    return { path: root, removed: true };
+}

package/dist/local/cloudflare-checkup/cf/locate.d.ts

@@ -0,0 +1,43 @@
+export type LocateFs = {
+    stat(target: string): Promise<{
+        isFile(): boolean;
+        isDirectory(): boolean;
+    }>;
+    realpath(target: string): Promise<string>;
+    readFile(target: string): Promise<string>;
+    readdir(target: string): Promise<string[]>;
+};
+export type CfLocation = {
+    packageDir: string;
+    /** Absolute path of the `bin.cf` entry script. */
+    entry: string;
+    packageVersion: string;
+    source: 'cf-bin' | 'managed' | 'path' | 'pnpm' | 'volta';
+    /**
+     * The package lies inside the current working directory (warned about), which
+     * may be a project's own cf. Never set for the managed install, which the CLI
+     * installed and verified itself, nor when the working directory is the home
+     * directory, where every global install (nvm, Volta, pnpm) lives.
+     */
+    insideCwd: boolean;
+};
+export declare function isNodeSupported(version?: string): boolean;
+/** cf runs under this Node via process.execPath; workerd ships no win32-arm64 build. */
+export declare function assertLocalRuntimeSupported(version?: string, platform?: NodeJS.Platform, arch?: string): void;
+export declare function locateCf(options: {
+    cfBin?: string;
+    /** The verified managed cf package directory (`findManagedCf`), tried after `--cf-bin`. */
+    managedDir?: string;
+    env: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    cwd?: string;
+    /** Defaults to HOME (USERPROFILE on Windows) from `env`, else the OS home directory. */
+    home?: string;
+    fs?: LocateFs;
+}): Promise<CfLocation>;
+export type CfVersionInfo = {
+    version: string;
+    tested: boolean;
+};
+/** Gate the version cf prints against its package.json and `CF_SUPPORTED`. */
+export declare function checkCfVersion(printed: string, packageVersion: string): CfVersionInfo;

package/dist/local/cloudflare-checkup/cf/locate.js

@@ -0,0 +1,227 @@
+/**
+ * Locating Cloudflare's cf CLI and checking its identity (spec §F2).
+ *
+ * Candidates, in order: `--cf-bin`; the Vigilbase-managed install
+ * (`<configDir>/cf/<version>`, see install.ts); absolute PATH entries holding
+ * `cf`, then `cloudflare` (`cf.cmd` / `cloudflare.cmd` on Windows); then pnpm
+ * and Volta global package directories, probed without spawning a package
+ * manager. A
+ * candidate is accepted only if its package.json says it is Cloudflare's cf
+ * (`name`, `repository`, `bin.cf`); the Cloud Foundry CLI, which also installs
+ * `cf`, and unresolvable shims are skipped. cf is then run as
+ * `process.execPath <bin.cf entry>`, never through a shim or shell.
+ */
+import { promises as fsPromises } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { CF_SUPPORTED, isSupportedCfVersion } from '../contract.js';
+import { LocalCheckupError } from '../errors.js';
+const nodeFs = {
+    stat: (target) => fsPromises.stat(target),
+    realpath: (target) => fsPromises.realpath(target),
+    readFile: (target) => fsPromises.readFile(target, 'utf8'),
+    readdir: (target) => fsPromises.readdir(target),
+};
+const MIN_NODE = [22, 18];
+const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+const MAX_WALK_UP = 4;
+const MAX_PACKAGE_MANAGER_PROBES = 20;
+const MAX_VOLTA_DEPTH = 4;
+export function isNodeSupported(version = process.versions.node) {
+    const [major, minor] = version.split('.').map((part) => Number.parseInt(part, 10));
+    if (!Number.isInteger(major) || !Number.isInteger(minor))
+        return false;
+    return major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+}
+/** cf runs under this Node via process.execPath; workerd ships no win32-arm64 build. */
+export function assertLocalRuntimeSupported(version = process.versions.node, platform = process.platform, arch = process.arch) {
+    if (!isNodeSupported(version)) {
+        throw new LocalCheckupError('NODE_UNSUPPORTED', `Node.js ${version} is too old for cf; local checkups need Node.js 22.18 or newer.`);
+    }
+    if (!['darwin', 'linux', 'win32'].includes(platform) || (platform === 'win32' && arch === 'arm64')) {
+        throw new LocalCheckupError('NODE_UNSUPPORTED', `cf does not support ${platform}-${arch}. Use macOS, Linux or Windows x64.`);
+    }
+}
+function envLookup(env, platform, name) {
+    if (platform !== 'win32')
+        return env[name];
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase());
+    return key === undefined ? undefined : env[key];
+}
+function repositoryUrl(repository) {
+    if (typeof repository === 'string')
+        return repository;
+    if (repository && typeof repository === 'object' && typeof repository.url === 'string') {
+        return repository.url;
+    }
+    return '';
+}
+export async function locateCf(options) {
+    const platform = options.platform ?? process.platform;
+    const p = platform === 'win32' ? path.win32 : path.posix;
+    const fs = options.fs ?? nodeFs;
+    const cwd = options.cwd ?? process.cwd();
+    const home = options.home ?? (envLookup(options.env, platform, platform === 'win32' ? 'USERPROFILE' : 'HOME') || homedir());
+    const cwdIsHome = Boolean(home) && p.isAbsolute(home) && p.relative(home, cwd) === '';
+    let sawOther = false;
+    const isFile = async (target) => (await fs.stat(target).catch(() => null))?.isFile() === true;
+    const isDir = async (target) => (await fs.stat(target).catch(() => null))?.isDirectory() === true;
+    const verifyPackage = async (packageDir, expectedEntry) => {
+        const text = await fs.readFile(p.join(packageDir, 'package.json')).catch(() => null);
+        if (text === null)
+            return { ok: false, reason: 'missing' };
+        if (text.length > MAX_PACKAGE_JSON_BYTES)
+            return { ok: false, reason: 'impostor' };
+        let manifest;
+        try {
+            manifest = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, reason: 'impostor' };
+        }
+        const binCf = manifest.bin && typeof manifest.bin === 'object' ? manifest.bin.cf : undefined;
+        if (manifest.name !== 'cf' || !repositoryUrl(manifest.repository).includes('github.com/cloudflare/cf') ||
+            typeof binCf !== 'string' || typeof manifest.version !== 'string') {
+            return { ok: false, reason: 'impostor' };
+        }
+        const entry = p.resolve(packageDir, binCf);
+        const relative = p.relative(packageDir, entry);
+        if (!relative || relative.startsWith('..') || p.isAbsolute(relative) || !(await isFile(entry))) {
+            return { ok: false, reason: 'impostor' };
+        }
+        if (expectedEntry !== undefined) {
+            const realEntry = await fs.realpath(entry).catch(() => entry);
+            if (realEntry !== expectedEntry)
+                return { ok: false, reason: 'impostor' };
+        }
+        return { ok: true, packageDir, entry, version: manifest.version };
+    };
+    /** A POSIX bin (symlink or file): resolve it and walk up to the nearest package.json. */
+    const fromPosixBin = async (bin) => {
+        const real = await fs.realpath(bin).catch(() => null);
+        if (real === null)
+            return { ok: false, reason: 'missing' };
+        let dir = p.dirname(real);
+        for (let depth = 0; depth < MAX_WALK_UP; depth++) {
+            if (await isFile(p.join(dir, 'package.json')))
+                return verifyPackage(dir, real);
+            const parent = p.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return { ok: false, reason: 'missing' };
+    };
+    const accept = (verified, source) => {
+        const relative = p.relative(cwd, verified.packageDir);
+        const inside = relative === '' || (!relative.startsWith('..') && !p.isAbsolute(relative));
+        return {
+            packageDir: verified.packageDir,
+            entry: verified.entry,
+            packageVersion: verified.version,
+            source,
+            insideCwd: inside && source !== 'managed' && !cwdIsHome,
+        };
+    };
+    // 1. --cf-bin: the package directory or its bin/cf. An explicit path is not
+    //    silently replaced by another cf.
+    if (options.cfBin !== undefined) {
+        if (!p.isAbsolute(options.cfBin))
+            throw new Error('--cf-bin must be an absolute path.');
+        let verified;
+        if (await isDir(options.cfBin))
+            verified = await verifyPackage(options.cfBin);
+        else if (platform === 'win32')
+            verified = await verifyPackage(p.dirname(p.dirname(options.cfBin)));
+        else
+            verified = await fromPosixBin(options.cfBin);
+        if (verified.ok)
+            return accept(verified, 'cf-bin');
+        if (verified.reason === 'missing' && !(await fs.stat(options.cfBin).catch(() => null))) {
+            throw new LocalCheckupError('CF_NOT_FOUND', 'No file or directory exists at --cf-bin.');
+        }
+        throw new LocalCheckupError('CF_WRONG_BINARY', '--cf-bin does not point to Cloudflare\'s cf package (name "cf", repository github.com/cloudflare/cf).');
+    }
+    // 2. The Vigilbase-managed install; an unusable one falls through to the other candidates.
+    if (options.managedDir !== undefined && p.isAbsolute(options.managedDir)) {
+        const verified = await verifyPackage(options.managedDir);
+        if (verified.ok)
+            return accept(verified, 'managed');
+    }
+    // 3. Absolute PATH entries; `cf` everywhere first, then `cloudflare`.
+    const pathValue = envLookup(options.env, platform, 'PATH') ?? '';
+    const dirs = [...new Set(pathValue.split(platform === 'win32' ? ';' : ':'))]
+        .filter((dir) => dir !== '' && dir !== '.' && p.isAbsolute(dir));
+    const names = platform === 'win32' ? ['cf.cmd', 'cloudflare.cmd'] : ['cf', 'cloudflare'];
+    for (const name of names) {
+        for (const dir of dirs) {
+            const hit = p.join(dir, name);
+            if (!(await isFile(hit)))
+                continue;
+            // npm's Windows global layout keeps the package beside the shim.
+            const verified = platform === 'win32' ? await verifyPackage(p.join(dir, 'node_modules', 'cf')) : await fromPosixBin(hit);
+            if (verified.ok)
+                return accept(verified, 'path');
+            // Cloud Foundry's cf, or a shim (pnpm) without a resolvable package: keep searching.
+            sawOther = true;
+        }
+    }
+    // 4. Package-manager global directories, at most 20 filesystem probes.
+    let probes = 0;
+    const probe = async (work, fallback) => {
+        if (probes >= MAX_PACKAGE_MANAGER_PROBES)
+            return fallback;
+        probes++;
+        return work().catch(() => fallback);
+    };
+    const pnpmHome = envLookup(options.env, platform, 'PNPM_HOME');
+    if (pnpmHome && p.isAbsolute(pnpmHome)) {
+        const globalDir = p.join(pnpmHome, 'global');
+        const versions = await probe(() => fs.readdir(globalDir), []);
+        for (const version of versions.sort()) {
+            const packageDir = p.join(globalDir, version, 'node_modules', 'cf');
+            if (!(await probe(() => isFile(p.join(packageDir, 'package.json')), false)))
+                continue;
+            const verified = await verifyPackage(packageDir);
+            if (verified.ok)
+                return accept(verified, 'pnpm');
+            sawOther = true;
+        }
+    }
+    const voltaHome = envLookup(options.env, platform, 'VOLTA_HOME');
+    if (voltaHome && p.isAbsolute(voltaHome)) {
+        let frontier = [p.join(voltaHome, 'tools', 'image', 'packages', 'cf')];
+        for (let depth = 0; depth <= MAX_VOLTA_DEPTH && frontier.length > 0; depth++) {
+            const next = [];
+            for (const dir of frontier) {
+                if (p.basename(dir) === 'cf' && p.basename(p.dirname(dir)) === 'node_modules' &&
+                    await probe(() => isFile(p.join(dir, 'package.json')), false)) {
+                    const verified = await verifyPackage(dir);
+                    if (verified.ok)
+                        return accept(verified, 'volta');
+                    sawOther = true;
+                    continue;
+                }
+                const children = await probe(() => fs.readdir(dir), []);
+                for (const child of children.sort())
+                    next.push(p.join(dir, child));
+            }
+            frontier = next;
+        }
+    }
+    if (sawOther) {
+        throw new LocalCheckupError('CF_WRONG_BINARY', 'A program named cf was found, but it is not Cloudflare\'s cf CLI (for example the Cloud Foundry CLI or an unresolvable shim).');
+    }
+    throw new LocalCheckupError('CF_NOT_FOUND', 'Cloudflare\'s cf CLI was not found on PATH or in the pnpm and Volta global directories.');
+}
+/** Gate the version cf prints against its package.json and `CF_SUPPORTED`. */
+export function checkCfVersion(printed, packageVersion) {
+    const version = printed.trim();
+    if (version !== packageVersion) {
+        throw new LocalCheckupError('CF_WRONG_BINARY', 'cf --version does not match the version in its package.json.');
+    }
+    if (!isSupportedCfVersion(version)) {
+        throw new LocalCheckupError('CF_UNSUPPORTED_VERSION', `cf ${version.slice(0, 40)} is not supported; local checkups need cf >= ${CF_SUPPORTED.min} and < ${CF_SUPPORTED.maxExclusive}.`);
+    }
+    return { version, tested: CF_SUPPORTED.tested.includes(version) };
+}

package/dist/local/cloudflare-checkup/cf/run-cf.d.ts

@@ -0,0 +1,88 @@
+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;
+/**
+ * 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;
+    /** 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>;
+    dispose(): Promise<void>;
+}
+/**
+ * Run `work` with a private cf runner; the directory is removed afterwards and
+ * on SIGINT, when live children get SIGTERM and then SIGKILL.
+ */
+export declare function withCfRunner<T>(entry: string, work: (runner: CfProcessRunner) => Promise<T>): 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;
+};