@gatedpath/preflight 0.1.0

package/dist/doctor-cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// redbelly-doctor: one line per check, pass, warn or fail, with the fix on the same line.
+// Exit 0 only when every required check passes; 1 otherwise; 2 on bad arguments. --json for agents.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { DOCTOR_VERSION, renderDoctorText, runDoctor } from './doctor.js';
+export const DOCTOR_HELP = `redbelly-doctor [options]
+
+Checks the machine before the first command: Node 22 or later; forge, anvil and cast on
+PATH, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0
+whatever the binary returned; slither and aderyn (optional); git; no .env tracked by git;
+and, in a scaffold, vendor/ matching the versions the scaffolder recorded. One line per
+check with the fix on the same line. Touches no network and no key.
+
+  --project <dir>   scaffold root, its contracts/ folder, or any directory (default: cwd)
+  --json            print the report as JSON
+  --version, --help
+
+Exit 0 when every required check passes (optional checks may warn), 1 otherwise, 2 on bad arguments.
+`;
+export function parseDoctorArgs(argv) {
+    const o = { json: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const [flag, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+        switch (flag) {
+            case '--project': {
+                const v = inline ?? argv[++i];
+                if (v === undefined)
+                    throw new Error('--project needs a value');
+                o.project = v;
+                break;
+            }
+            case '--json':
+                o.json = true;
+                break;
+            case '--help':
+            case '-h':
+                o.help = true;
+                break;
+            case '--version':
+                o.version = true;
+                break;
+            default:
+                if (/^(0x)?[0-9a-fA-F]{64}$/.test(a))
+                    throw new Error('that argument looks like a private key; doctor never takes one and needs no address');
+                throw new Error(`unknown argument "${a}"\n\n${DOCTOR_HELP}`);
+        }
+    }
+    return o;
+}
+export async function doctorMain(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseDoctorArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (args.help) {
+        process.stdout.write(DOCTOR_HELP);
+        return 0;
+    }
+    if (args.version) {
+        process.stdout.write(`${DOCTOR_VERSION}\n`);
+        return 0;
+    }
+    const report = await runDoctor(args.project !== undefined ? { project: args.project } : {});
+    process.stdout.write(args.json ? JSON.stringify(report, null, 2) + '\n' : renderDoctorText(report));
+    return report.ok ? 0 : 1;
+}
+/** True when this file is the process entry point (a bin symlink resolves to it), not an import. */
+const isEntry = Boolean(process.argv[1]) && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+if (isEntry)
+    doctorMain().then((code) => { process.exitCode = code; }, (e) => { process.stderr.write(`${e.stack ?? e}\n`); process.exitCode = 2; });

package/dist/doctor.d.ts

@@ -0,0 +1,60 @@
+export declare const DOCTOR_VERSION: string;
+export type DoctorCheckId = 'node' | 'git' | 'forge' | 'anvil' | 'cast' | 'foundry-version' | 'foundry-exit-code' | 'slither' | 'aderyn' | 'env-tracked' | 'vendor';
+export declare const DOCTOR_CHECK_IDS: readonly DoctorCheckId[];
+export type DoctorStatus = 'pass' | 'warn' | 'fail';
+export interface DoctorCheck {
+    readonly id: DoctorCheckId;
+    /** A required check that fails makes the exit code 1. Optional checks warn at worst. */
+    readonly required: boolean;
+    readonly status: DoctorStatus;
+    /** One sentence, printed after the status and the id. */
+    readonly reason: string;
+    /** The next command, printed on the same line. From the failure table where the table has the entry. */
+    readonly fix: string | null;
+    /** The failure-table kind the fix comes from, so explain_failure says the same thing. */
+    readonly kind: string | null;
+    readonly data?: Record<string, unknown>;
+}
+export interface DoctorOptions {
+    /** Project directory: a scaffold root, its contracts/ folder, or any directory. Default: cwd. */
+    project?: string;
+    /** Environment to read PATH (and PATHEXT on Windows) from. Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Node version to judge. Default: process.version. Tests hand in an older one. */
+    nodeVersion?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+}
+export interface DoctorReport {
+    readonly tool: 'redbelly-doctor';
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly project: string;
+    readonly scaffold: boolean;
+    readonly checks: readonly DoctorCheck[];
+    /** True when every required check passes. Warnings never clear or cause a fail. */
+    readonly ok: boolean;
+}
+export declare const NODE_MIN_MAJOR = 22;
+export declare const SLITHER_PIN = "0.11.6";
+export declare const ADERYN_PIN = "0.6.8";
+declare const FOUNDRY_TOOLS: readonly ["forge", "anvil", "cast"];
+type FoundryTool = (typeof FOUNDRY_TOOLS)[number];
+/** First match for `name` on PATH, the way a shell finds it. Windows adds PATHEXT. */
+export declare function whichOnPath(name: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | null;
+/** The semantic version a tool prints for --version, or null. */
+export declare function toolVersion(path: string): Promise<{
+    version: string | null;
+    output: string;
+}>;
+/** Does the binary hand its exit code back? The npm shim spawns the real tool and always exits 0. */
+export declare function exitCodePropagates(path: string): Promise<boolean | null>;
+/** A Node script where a binary should be: a .mjs/.js/.cjs, a `#!…node` shebang, or a Windows .cmd calling node. */
+export declare function looksLikeNodeShim(path: string): boolean;
+/** The platform binary the @foundry-rs shim would spawn, when it sits beside the shim. */
+export declare function realBinaryNear(shimPath: string, tool: FoundryTool, platform?: NodeJS.Platform, arch?: string): string | null;
+/** Scaffold root for a directory: itself, or its parent when the directory is a scaffold's contracts/. */
+export declare function scaffoldRoot(project: string): string | null;
+export declare function runDoctor(opts?: DoctorOptions): Promise<DoctorReport>;
+export declare function renderDoctorText(report: DoctorReport): string;
+export {};

package/dist/doctor.js

@@ -0,0 +1,251 @@
+// redbelly-doctor: the machine before the first command. Node 22 or later; forge, anvil and cast
+// present, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0
+// whatever the binary returned; slither and aderyn optional; git; no .env tracked; and, in a
+// scaffold, vendor/ matching the versions the scaffolder recorded. One line per check with the fix
+// on the same line. The fix text comes from the failure table in @gatedpath/agent-rules, so
+// explain_failure and doctor use the same words. Nothing here touches a network or a key.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, delimiter, dirname, join, resolve } from 'node:path';
+import { failureByKind } from '@gatedpath/agent-rules/failures';
+import { run } from './proc.js';
+const require = createRequire(import.meta.url);
+export const DOCTOR_VERSION = require('../package.json').version;
+export const DOCTOR_CHECK_IDS = ['node', 'git', 'forge', 'anvil', 'cast', 'foundry-version', 'foundry-exit-code', 'slither', 'aderyn', 'env-tracked', 'vendor'];
+export const NODE_MIN_MAJOR = 22;
+export const SLITHER_PIN = '0.11.6';
+export const ADERYN_PIN = '0.6.8';
+const FOUNDRY_TOOLS = ['forge', 'anvil', 'cast'];
+/** The flag no Foundry binary knows. clap exits 2 on it; the npm shim exits 0. */
+const BOGUS_FLAG = '--this-flag-does-not-exist';
+const fixFor = (kind) => failureByKind(kind)?.fix.command ?? null;
+/** First match for `name` on PATH, the way a shell finds it. Windows adds PATHEXT. */
+export function whichOnPath(name, env = process.env, platform = process.platform) {
+    const dirs = (env.PATH ?? env.Path ?? '').split(delimiter).filter(Boolean);
+    const exts = platform === 'win32' ? ['', ...(env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').map((e) => e.toLowerCase())] : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = join(dir, name + ext);
+            try {
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                /* not here */
+            }
+        }
+    }
+    return null;
+}
+/** The semantic version a tool prints for --version, or null. */
+export async function toolVersion(path) {
+    const r = await run(path, ['--version'], { timeoutMs: 20_000 });
+    const output = (r.stdout + r.stderr).trim();
+    if (r.spawnError)
+        return { version: null, output: r.spawnError };
+    const m = /(\d+\.\d+\.\d+)/.exec(output);
+    return { version: m ? m[1] : null, output };
+}
+/** Does the binary hand its exit code back? The npm shim spawns the real tool and always exits 0. */
+export async function exitCodePropagates(path) {
+    const r = await run(path, [BOGUS_FLAG], { timeoutMs: 20_000 });
+    if (r.spawnError || r.code === null)
+        return null;
+    return r.code !== 0;
+}
+/** A Node script where a binary should be: a .mjs/.js/.cjs, a `#!…node` shebang, or a Windows .cmd calling node. */
+export function looksLikeNodeShim(path) {
+    try {
+        const real = realpathSync(path);
+        if (/\.(mjs|cjs|js)$/i.test(real))
+            return true;
+        const head = readFileSync(real).subarray(0, 512).toString('utf8');
+        if (head.startsWith('#!') && /node/.test(head.split('\n')[0]))
+            return true;
+        if (/\.cmd$/i.test(real) && /node/.test(head))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** The platform binary the @foundry-rs shim would spawn, when it sits beside the shim. */
+export function realBinaryNear(shimPath, tool, platform = process.platform, arch = process.arch) {
+    let dir;
+    try {
+        dir = dirname(realpathSync(shimPath));
+    }
+    catch {
+        return null;
+    }
+    const archName = arch === 'x64' ? 'amd64' : arch;
+    const pkg = `${tool}-${platform}-${archName}`;
+    const exe = platform === 'win32' ? '.exe' : '';
+    const candidates = [join(dir, 'node_modules', '@foundry-rs', pkg, 'bin', tool + exe), join(dir, '..', pkg, 'bin', tool + exe), join(dir, '..', '..', '@foundry-rs', pkg, 'bin', tool + exe)];
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+/** Scaffold root for a directory: itself, or its parent when the directory is a scaffold's contracts/. */
+export function scaffoldRoot(project) {
+    const isScaffold = (dir) => existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'vendor')) && readdirSync(join(dir, 'vendor')).some((d) => d.startsWith('redbelly-'));
+    if (isScaffold(project))
+        return project;
+    const parent = resolve(project, '..');
+    if (basename(project) === 'contracts' && isScaffold(parent))
+        return parent;
+    return null;
+}
+const majorOf = (v) => Number(/^v?(\d+)/.exec(v)?.[1] ?? 0);
+export async function runDoctor(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const arch = opts.arch ?? process.arch;
+    const project = resolve(opts.project ?? process.cwd());
+    const root = scaffoldRoot(project);
+    const checks = [];
+    // node
+    const nodeVersion = opts.nodeVersion ?? process.version;
+    const major = majorOf(nodeVersion);
+    checks.push(major >= NODE_MIN_MAJOR
+        ? { id: 'node', required: true, status: 'pass', reason: `${nodeVersion} (${NODE_MIN_MAJOR} or later)`, fix: null, kind: null, data: { version: nodeVersion } }
+        : { id: 'node', required: true, status: 'fail', reason: `${nodeVersion} is older than ${NODE_MIN_MAJOR}; the scaffold, the MCP server and the web app are built and tested on ${NODE_MIN_MAJOR}.`, fix: fixFor('node-too-old'), kind: 'node-too-old', data: { version: nodeVersion } });
+    // git
+    const gitPath = whichOnPath('git', env, platform);
+    const git = gitPath ? await toolVersion(gitPath) : null;
+    checks.push(gitPath && git?.version
+        ? { id: 'git', required: true, status: 'pass', reason: `${git.version} at ${gitPath}`, fix: null, kind: null, data: { path: gitPath, version: git.version } }
+        : { id: 'git', required: true, status: 'fail', reason: 'not found on PATH.', fix: fixFor('git-not-found'), kind: 'git-not-found' });
+    // forge, anvil, cast
+    const found = {};
+    for (const tool of FOUNDRY_TOOLS) {
+        const path = whichOnPath(tool, env, platform);
+        const kind = tool === 'anvil' ? 'anvil-not-found' : 'forge-not-found';
+        if (!path) {
+            checks.push({ id: tool, required: true, status: 'fail', reason: 'not found on PATH.', fix: fixFor(kind), kind });
+            continue;
+        }
+        const v = await toolVersion(path);
+        const propagates = await exitCodePropagates(path);
+        const shim = propagates === false || looksLikeNodeShim(path);
+        const real = shim ? realBinaryNear(path, tool, platform, arch) : null;
+        found[tool] = { path, version: v.version, propagates, shim, real };
+        if (!v.version) {
+            checks.push({ id: tool, required: true, status: 'fail', reason: `${path} did not answer --version (${v.output.slice(0, 120) || 'no output'}).`, fix: fixFor(kind), kind, data: { path } });
+            continue;
+        }
+        checks.push({ id: tool, required: true, status: 'pass', reason: `${v.version} at ${path}${shim ? ' (the npm shim; see foundry-exit-code)' : ''}`, fix: null, kind: null, data: { path, version: v.version, shim } });
+    }
+    // one version across the three
+    const versions = FOUNDRY_TOOLS.map((t) => found[t]?.version ?? null);
+    if (versions.some((v) => v === null)) {
+        checks.push({ id: 'foundry-version', required: true, status: 'fail', reason: `cannot compare: ${FOUNDRY_TOOLS.filter((t) => !found[t]?.version).join(', ')} missing (above).`, fix: fixFor('foundry-version-mismatch'), kind: 'foundry-version-mismatch', data: { versions } });
+    }
+    else if (new Set(versions).size === 1) {
+        checks.push({ id: 'foundry-version', required: true, status: 'pass', reason: `forge, anvil and cast are all ${versions[0]}.`, fix: null, kind: null, data: { version: versions[0] } });
+    }
+    else {
+        checks.push({ id: 'foundry-version', required: true, status: 'fail', reason: FOUNDRY_TOOLS.map((t) => `${t} ${found[t].version}`).join(', ') + '; Foundry ships and tests the three together.', fix: fixFor('foundry-version-mismatch'), kind: 'foundry-version-mismatch', data: { versions } });
+    }
+    // the shim that drops exit codes
+    const present = FOUNDRY_TOOLS.filter((t) => found[t]);
+    const shims = present.filter((t) => found[t].shim);
+    if (present.length === 0) {
+        checks.push({ id: 'foundry-exit-code', required: true, status: 'fail', reason: 'nothing to probe: forge, anvil and cast are missing (above).', fix: null, kind: 'foundry-exit-code-shim' });
+    }
+    else if (shims.length === 0) {
+        checks.push({ id: 'foundry-exit-code', required: true, status: 'pass', reason: `${present.join(', ')} hand back their exit codes (${BOGUS_FLAG} exits ${present.map((t) => found[t].propagates === null ? '?' : 'non-zero').join(', ')}).`, fix: null, kind: null });
+    }
+    else {
+        const detail = shims.map((t) => `${t} at ${found[t].path} is the @foundry-rs npm shim (${BOGUS_FLAG} exited 0; the real binary exits 2)${found[t].real ? `, real binary ${found[t].real}` : ''}`).join('; ');
+        const concrete = shims.map((t) => (found[t].real ? `ln -sf ${found[t].real} ${found[t].path}` : null)).filter(Boolean).join(' && ');
+        checks.push({ id: 'foundry-exit-code', required: true, status: 'fail', reason: `${detail}. A failed forge build or test reports success through it.`, fix: concrete || fixFor('foundry-exit-code-shim'), kind: 'foundry-exit-code-shim', data: { shims: shims.map((t) => ({ tool: t, path: found[t].path, real: found[t].real })) } });
+    }
+    // slither, aderyn (optional)
+    for (const [tool, pin, kind] of [['slither', SLITHER_PIN, 'slither-not-found'], ['aderyn', ADERYN_PIN, 'aderyn-not-found']]) {
+        const path = whichOnPath(tool, env, platform);
+        if (!path) {
+            checks.push({ id: tool, required: false, status: 'warn', reason: `not found on PATH (optional${tool === 'slither' ? '; pre-flight wants its report before a deploy' : ''}).`, fix: fixFor(kind), kind });
+            continue;
+        }
+        const v = await toolVersion(path);
+        if (!v.version)
+            checks.push({ id: tool, required: false, status: 'warn', reason: `${path} did not answer --version (optional).`, fix: fixFor(kind), kind, data: { path } });
+        else if (v.version !== pin)
+            checks.push({ id: tool, required: false, status: 'warn', reason: `${v.version} at ${path}; CI pins ${pin}, so findings may differ.`, fix: null, kind: null, data: { path, version: v.version, pin } });
+        else
+            checks.push({ id: tool, required: false, status: 'pass', reason: `${v.version} at ${path}`, fix: null, kind: null, data: { path, version: v.version } });
+    }
+    // no .env tracked
+    if (!gitPath) {
+        checks.push({ id: 'env-tracked', required: true, status: 'fail', reason: 'cannot check without git (above).', fix: null, kind: 'git-not-found' });
+    }
+    else {
+        const inRepo = await run(gitPath, ['rev-parse', '--is-inside-work-tree'], { cwd: root ?? project, timeoutMs: 10_000 });
+        if (inRepo.code !== 0 || inRepo.stdout.trim() !== 'true') {
+            checks.push({ id: 'env-tracked', required: true, status: 'pass', reason: 'not a git repository, so nothing is tracked.', fix: null, kind: null, data: { repository: false } });
+        }
+        else {
+            const ls = await run(gitPath, ['ls-files'], { cwd: root ?? project, timeoutMs: 30_000 });
+            const files = ls.stdout.split('\n').filter(Boolean);
+            const tracked = files.filter((f) => /^\.env(\..+)?$/.test(basename(f)) && !/\.(example|sample)$/.test(f));
+            if (tracked.length === 0)
+                checks.push({ id: 'env-tracked', required: true, status: 'pass', reason: `no .env among ${files.length} tracked file${files.length === 1 ? '' : 's'}.`, fix: null, kind: null, data: { repository: true, tracked: files.length } });
+            else
+                checks.push({ id: 'env-tracked', required: true, status: 'fail', reason: `${tracked.join(', ')} ${tracked.length === 1 ? 'is' : 'are'} tracked by git.`, fix: fixFor('env-tracked'), kind: 'env-tracked', data: { tracked } });
+        }
+    }
+    // vendor/ against the scaffolder's record
+    if (!root) {
+        checks.push({ id: 'vendor', required: true, status: 'pass', reason: 'not a scaffold (no vendor/redbelly-*), so nothing to compare.', fix: null, kind: null, data: { scaffold: false } });
+    }
+    else {
+        const pkg = readJson(join(root, 'package.json'));
+        const record = pkg?.redbelly?.vendor;
+        const vendored = {};
+        for (const dir of readdirSync(join(root, 'vendor')).filter((d) => d.startsWith('redbelly-')).sort()) {
+            const v = readJson(join(root, 'vendor', dir, 'package.json'));
+            vendored[dir] = v?.version ?? null;
+        }
+        if (!record) {
+            checks.push({ id: 'vendor', required: true, status: 'warn', reason: `${Object.keys(vendored).length} vendored package${Object.keys(vendored).length === 1 ? '' : 's'} (${Object.entries(vendored).map(([d, v]) => `${d} ${v ?? '?'}`).join(', ')}); this scaffold predates the version record in package.json, so nothing to compare against.`, fix: null, kind: null, data: { vendored, record: null } });
+        }
+        else {
+            const drift = Object.entries(record).filter(([dir, want]) => vendored[dir] !== want).map(([dir, want]) => `vendor/${dir} is ${vendored[dir] ?? 'missing'}, the record says ${want}`);
+            if (drift.length === 0)
+                checks.push({ id: 'vendor', required: true, status: 'pass', reason: `vendor/ matches the record: ${Object.entries(record).map(([d, v]) => `${d} ${v}`).join(', ')}.`, fix: null, kind: null, data: { vendored, record, scaffolder: pkg?.redbelly?.scaffolder ?? null } });
+            else
+                checks.push({ id: 'vendor', required: true, status: 'fail', reason: `${drift.join('; ')}.`, fix: fixFor('vendor-drift'), kind: 'vendor-drift', data: { vendored, record, scaffolder: pkg?.redbelly?.scaffolder ?? null } });
+        }
+    }
+    return {
+        tool: 'redbelly-doctor',
+        version: DOCTOR_VERSION,
+        generatedAt: new Date().toISOString(),
+        project,
+        scaffold: root !== null,
+        checks,
+        ok: checks.every((c) => !(c.required && c.status === 'fail')),
+    };
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function renderDoctorText(report) {
+    const lines = [];
+    lines.push(`redbelly-doctor ${report.version}  project ${report.project}${report.scaffold ? '  (scaffold)' : ''}`);
+    lines.push('');
+    for (const c of report.checks)
+        lines.push(`${c.status.padEnd(5)} ${c.id.padEnd(18)} ${c.reason}${c.fix && c.status !== 'pass' ? `  Fix: ${c.fix}` : ''}`);
+    lines.push('');
+    const fails = report.checks.filter((c) => c.required && c.status === 'fail').length;
+    const warns = report.checks.filter((c) => c.status === 'warn').length;
+    lines.push(report.ok
+        ? `ok: every required check passed${warns ? ` (${warns} warning${warns === 1 ? '' : 's'}, optional)` : ''}. Next: npm run dev in a scaffold, or create-redbelly-dapp my-app --yes to make one.`
+        : `not ok: ${fails} required check${fails === 1 ? '' : 's'} failed. Run each Fix above, then redbelly-doctor again.`);
+    return lines.join('\n') + '\n';
+}

package/dist/dotenv.d.ts

@@ -0,0 +1,7 @@
+export declare const ENV_NAMES: {
+    readonly deployer: "DEPLOYER";
+    readonly admin: "ADMIN_SAFE";
+    readonly chain: "CHAIN_ID";
+    readonly legacyAdmin: "PREFLIGHT_ADMIN";
+};
+export declare function readDotEnv(project: string, env: NodeJS.ProcessEnv): Record<string, string>;

package/dist/dotenv.js

@@ -0,0 +1,28 @@
+// Reads KEY=VALUE lines from a project's .env without executing it, for the names the
+// scaffolder's templates use (DEPLOYER, ADMIN_SAFE, CHAIN_ID). Values already in the
+// process environment win. Nothing here is written back and secrets are not looked for; the
+// git-secrets check covers what should never be in that file.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const ENV_NAMES = { deployer: 'DEPLOYER', admin: 'ADMIN_SAFE', chain: 'CHAIN_ID', legacyAdmin: 'PREFLIGHT_ADMIN' };
+export function readDotEnv(project, env) {
+    const out = {};
+    const file = join(project, '.env');
+    if (existsSync(file)) {
+        for (const raw of readFileSync(file, 'utf8').split(/\r?\n/)) {
+            const line = raw.trim();
+            if (!line || line.startsWith('#'))
+                continue;
+            const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+            if (!m)
+                continue;
+            out[m[1]] = m[2].replace(/^(["'])(.*)\1$/, '$2').trim();
+        }
+    }
+    for (const name of Object.values(ENV_NAMES)) {
+        const v = env[name];
+        if (v !== undefined && v !== '')
+            out[name] = v;
+    }
+    return out;
+}

package/dist/gas-cli.d.ts

@@ -0,0 +1,8 @@
+import type { GasOptions } from './gas.js';
+export declare const GAS_HELP = "redbelly gas [options]\n\nPrices a gas snapshot or a forge gas report at the chain's latest base fee and on-chain feed\nprice, one row per test or function, in RBNT and US cents. Reads .gas-snapshot when the project\nhas one, else runs forge test --gas-report --json. Read-only: two RPC reads, no key.\n\n  --project <dir>      Foundry project or scaffold root (default: current directory)\n  --chain <151|153>    chain to price on (default 153); the RPC must report it\n  --rpc <url>          JSON-RPC endpoint (default: the governors RPC for --chain; a fork works)\n  --snapshot <file>    price this .gas-snapshot or gas-report JSON instead of the project's\n  --report             run forge test --gas-report --json even when .gas-snapshot exists\n  --diff <file>        a previous .gas-snapshot or gas-report JSON to compare against\n  --json               print the report as JSON\n  --version, --help\n";
+export declare function parseGasArgs(argv: readonly string[]): GasOptions & {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+};
+export declare function gasMain(argv?: readonly string[]): Promise<number>;

package/dist/gas-cli.js

@@ -0,0 +1,100 @@
+// `redbelly gas`: the gas report in RBNT and US cents. Exit 0 when priced, 1 when the source could
+// not be read or the RPC did not answer, 2 on bad arguments. --json for agents.
+import { GAS_VERSION, gasReportJson, renderGasText, runGas } from './gas.js';
+export const GAS_HELP = `redbelly gas [options]
+
+Prices a gas snapshot or a forge gas report at the chain's latest base fee and on-chain feed
+price, one row per test or function, in RBNT and US cents. Reads .gas-snapshot when the project
+has one, else runs forge test --gas-report --json. Read-only: two RPC reads, no key.
+
+  --project <dir>      Foundry project or scaffold root (default: current directory)
+  --chain <151|153>    chain to price on (default 153); the RPC must report it
+  --rpc <url>          JSON-RPC endpoint (default: the governors RPC for --chain; a fork works)
+  --snapshot <file>    price this .gas-snapshot or gas-report JSON instead of the project's
+  --report             run forge test --gas-report --json even when .gas-snapshot exists
+  --diff <file>        a previous .gas-snapshot or gas-report JSON to compare against
+  --json               print the report as JSON
+  --version, --help
+`;
+export function parseGasArgs(argv) {
+    const o = { json: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const [flag, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+        const next = () => {
+            if (inline !== undefined)
+                return inline;
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`${flag} needs a value`);
+            return v;
+        };
+        switch (flag) {
+            case '--project':
+                o.project = next();
+                break;
+            case '--chain': {
+                const c = Number(next());
+                if (c !== 151 && c !== 153)
+                    throw new Error('--chain must be 151 or 153');
+                o.chain = c;
+                break;
+            }
+            case '--rpc':
+                o.rpc = next();
+                break;
+            case '--snapshot':
+                o.snapshot = next();
+                break;
+            case '--report':
+                o.report = true;
+                break;
+            case '--diff':
+                o.diff = next();
+                break;
+            case '--json':
+                o.json = true;
+                break;
+            case '--help':
+            case '-h':
+                o.help = true;
+                break;
+            case '--version':
+                o.version = true;
+                break;
+            default:
+                if (/^(0x)?[0-9a-fA-F]{64}$/.test(a))
+                    throw new Error('that argument looks like a private key; redbelly gas reads the chain and never takes one');
+                throw new Error(`unknown argument "${a}"\n\n${GAS_HELP}`);
+        }
+    }
+    return o;
+}
+export async function gasMain(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseGasArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (args.help) {
+        process.stdout.write(GAS_HELP);
+        return 0;
+    }
+    if (args.version) {
+        process.stdout.write(`${GAS_VERSION}\n`);
+        return 0;
+    }
+    const { json, help: _h, version: _v, ...opts } = args;
+    try {
+        const report = await runGas(opts);
+        process.stdout.write(json ? gasReportJson(report) : renderGasText(report));
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`redbelly gas: ${e.message}\n`);
+        return 1;
+    }
+}

package/dist/gas.d.ts

@@ -0,0 +1,110 @@
+export declare const GAS_VERSION: string;
+export interface GasRow {
+    /** `Contract:item`, the key rows are matched on across two files. */
+    readonly name: string;
+    readonly contract: string;
+    /** A test name from a snapshot, a function signature from a gas report, or `deployment`. */
+    readonly item: string;
+    readonly gas: bigint;
+    /** From a gas report: how many calls the mean is over. From a fuzz line: the runs. */
+    readonly calls?: number;
+    readonly min?: bigint;
+    readonly max?: bigint;
+}
+export type GasSource = {
+    readonly kind: 'snapshot';
+    readonly file: string;
+} | {
+    readonly kind: 'gas-report';
+    readonly command: string;
+} | {
+    readonly kind: 'gas-report-file';
+    readonly file: string;
+};
+export interface GasQuote {
+    readonly chain: 151 | 153;
+    readonly network: 'mainnet' | 'testnet';
+    readonly rpc: string;
+    readonly block: number;
+    readonly baseFeeWei: bigint;
+    /** The feed's raw integer (six decimals) and the derived USD per RBNT. */
+    readonly priceRaw: bigint;
+    readonly usdPerRbnt: number;
+    readonly priceTimestamp: string;
+    readonly priceFeed: string;
+}
+export interface PricedRow extends GasRow {
+    readonly wei: bigint;
+    readonly rbnt: string;
+    readonly usd: number;
+    /** US cents to three decimal places, as a number. */
+    readonly cents: number;
+    readonly before?: {
+        readonly gas: bigint;
+        readonly cents: number;
+    };
+    readonly delta?: {
+        readonly gas: bigint;
+        readonly cents: number;
+    };
+}
+export interface GasReport {
+    readonly tool: 'redbelly-gas';
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly project: string;
+    readonly source: GasSource;
+    readonly quote: GasQuote;
+    readonly rows: readonly PricedRow[];
+    readonly diff: {
+        readonly file: string;
+        readonly rows: number;
+        readonly added: readonly string[];
+        readonly removed: readonly string[];
+    } | null;
+}
+export interface GasOptions {
+    /** A Foundry project, or a scaffold root (its contracts/ is used). Default: cwd. */
+    project?: string;
+    chain?: 151 | 153;
+    rpc?: string;
+    /** A snapshot or gas-report JSON file to price instead of the project's .gas-snapshot. */
+    snapshot?: string;
+    /** Run `forge test --gas-report --json` even when a .gas-snapshot exists. */
+    report?: boolean;
+    /** A previous snapshot or gas-report JSON to compare against. */
+    diff?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** `.gas-snapshot`: `Contract:test() (gas: N)`, fuzz lines by their mean (μ), invariant lines (no gas) skipped. */
+export declare function parseGasSnapshot(text: string): GasRow[];
+/** `forge test --gas-report --json`: the deployment row, then each function by its mean. Contract names lose their path. */
+export declare function parseGasReportJson(json: unknown): GasRow[];
+/** Either format, by content: JSON that parses as an array is a gas report; anything else is a snapshot. */
+export declare function parseGasFile(text: string): {
+    kind: 'snapshot' | 'gas-report-file';
+    rows: GasRow[];
+};
+/** wei = gas * baseFee; thousandths of a US cent = wei * raw / 10^(18 + 6 - 5). Only the last step leaves BigInt. */
+export declare function priceGas(gas: bigint, quote: Pick<GasQuote, 'baseFeeWei' | 'priceRaw'>): {
+    wei: bigint;
+    rbnt: string;
+    usd: number;
+    cents: number;
+};
+export declare function priceRows(rows: readonly GasRow[], quote: Pick<GasQuote, 'baseFeeWei' | 'priceRaw'>, before?: readonly GasRow[]): {
+    rows: PricedRow[];
+    added: string[];
+    removed: string[];
+};
+export declare function quoteGas(rpc: string, expected?: 151 | 153): Promise<GasQuote>;
+/** A scaffold root's contracts/ when that is where foundry.toml is; otherwise the directory itself. */
+export declare function foundryDir(project: string): string;
+export declare function readGasSource(dir: string, opts: Pick<GasOptions, 'snapshot' | 'report' | 'env'>): Promise<{
+    source: GasSource;
+    rows: GasRow[];
+}>;
+export declare function runGas(opts?: GasOptions): Promise<GasReport>;
+export declare function renderGasText(report: GasReport): string;
+/** JSON with BigInt as decimal strings. */
+export declare function gasReportJson(report: GasReport): string;