@gatedpath/preflight 0.1.0

package/dist/checks/deployer.js

@@ -0,0 +1,53 @@
+// Who deploys, and may they? The address comes from `cast wallet address --account NAME`
+// (cast decrypts the keystore locally; this process only sees the address) or from
+// --address for a read-only run. Never from a key.
+import { isAllowed } from '@gatedpath/chains';
+import { ACCOUNT_NAME, run } from '../proc.js';
+import { isWellKnownDevAccount } from '../well-known.js';
+export async function resolveDeployer(src) {
+    if (src.address) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(src.address))
+            return { address: null, how: '--address', error: `"${src.address}" is not a 20-byte hex address.` };
+        return { address: src.address, how: '--address' };
+    }
+    if (src.account) {
+        if (!ACCOUNT_NAME.test(src.account))
+            return { address: null, how: '--account', error: 'Keystore names may only use letters, digits, dot, dash and underscore.' };
+        const args = ['wallet', 'address', '--account', src.account];
+        if (src.passwordFile)
+            args.push('--password-file', src.passwordFile);
+        const r = await run('cast', args, { cwd: src.cwd, env: src.env, timeoutMs: 60_000, stdin: '' });
+        if (r.spawnError)
+            return { address: null, how: '--account', error: `cast is not installed or not on PATH (${r.spawnError}); install Foundry or pass --address for a read-only run.` };
+        const m = /0x[0-9a-fA-F]{40}/.exec(r.stdout);
+        if (r.code !== 0 || !m)
+            return { address: null, how: '--account', error: `cast wallet address --account ${src.account} failed: ${(r.stderr || r.stdout).trim().split('\n').pop() ?? 'no output'}.` };
+        return { address: m[0], how: `cast wallet address --account ${src.account}` };
+    }
+    return { address: null, how: 'none' };
+}
+export async function checkDeployerVerified(address, how, error, rpc, chain) {
+    if (error)
+        return { id: 'deployer-verified', status: 'fail', reason: error };
+    if (!address)
+        return { id: 'deployer-verified', status: 'skip', reason: 'No deployer given; pass --account <keystore-name> or --address <0x…>.' };
+    if (chain !== 151 && chain !== 153)
+        return { id: 'deployer-verified', status: 'skip', reason: 'The RPC is not a Redbelly chain, so there is no permission contract to ask.', data: { address } };
+    try {
+        const allowed = await isAllowed(address, { rpc });
+        if (isWellKnownDevAccount(address)) {
+            return {
+                id: 'deployer-verified',
+                status: 'warn',
+                reason: `${address} (${how}) is one of the ten anvil/Hardhat default accounts whose private keys are public; it ${allowed ? 'passes' : 'fails'} isAllowed on chain ${chain}, but a deploy from it runs under an identity you do not control (RESEARCH.md question 30). Use a keystore of your own.`,
+                data: { address, allowed, how, wellKnownDevAccount: true },
+            };
+        }
+        if (allowed)
+            return { id: 'deployer-verified', status: 'pass', reason: `${address} (${how}) passes permission.isAllowed on chain ${chain}.`, data: { address, allowed, how } };
+        return { id: 'deployer-verified', status: 'fail', reason: `${address} (${how}) fails permission.isAllowed on chain ${chain}; verify it at https://access.redbelly.network before deploying.`, data: { address, allowed, how } };
+    }
+    catch (e) {
+        return { id: 'deployer-verified', status: 'fail', reason: `Could not read permission.isAllowed: ${e.message}.`, data: { address, how } };
+    }
+}

package/dist/checks/git-secrets.d.ts

@@ -0,0 +1,14 @@
+import type { CheckResult } from '../types.js';
+export interface SecretFinding {
+    commit: string;
+    file: string;
+    kind: string;
+    why: string;
+}
+export declare function scanGitHistory(project: string): Promise<{
+    findings: SecretFinding[];
+    commits: number;
+    isRepo: boolean;
+    trackedEnv: string[];
+}>;
+export declare function checkGitSecrets(project: string): Promise<CheckResult>;

package/dist/checks/git-secrets.js

@@ -0,0 +1,91 @@
+// Scans every added line in the whole git history for secret-shaped text. Streams
+// `git log -p --all --unified=0` so nothing is held in memory and a large history still
+// finishes in seconds. Only `+` lines count: a deleted secret was added earlier, and that
+// addition is what gets flagged. Reports file, commit and kind; never the text.
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { scanLine } from '../secrets.js';
+const IGNORED_PATHS = /(^|\/)(node_modules|lib|out|cache|artifacts|typechain(-types)?)\/|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|\.gas-snapshot)$|\.(min\.js|map|svg|png|jpg|pdf)$/;
+const MAX_FINDINGS = 25;
+export async function scanGitHistory(project) {
+    const isRepo = await run('git', ['rev-parse', '--is-inside-work-tree'], project).then((r) => r.code === 0 && r.stdout.trim() === 'true');
+    if (!isRepo)
+        return { findings: [], commits: 0, isRepo: false, trackedEnv: [] };
+    const tracked = await run('git', ['ls-files', '--', '.env', '.env.*', '**/.env', '**/.env.*'], project);
+    const trackedEnv = tracked.stdout.split('\n').map((s) => s.trim()).filter((f) => f && !/\.env\.(example|sample|template)$/.test(f));
+    const findings = [];
+    const seen = new Set();
+    let commits = 0;
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', ['log', '-p', '--all', '--no-color', '--unified=0', '--no-renames', '--format=commit %H', '--', '.'], { cwd: project, stdio: ['ignore', 'pipe', 'pipe'] });
+        let commit = '';
+        let file = '';
+        let skipFile = false;
+        const rl = createInterface({ input: child.stdout });
+        rl.on('line', (line) => {
+            if (line.startsWith('commit ')) {
+                commit = line.slice(7, 47);
+                commits++;
+                return;
+            }
+            if (line.startsWith('+++ ')) {
+                file = line.slice(4).replace(/^b\//, '');
+                skipFile = IGNORED_PATHS.test(file);
+                return;
+            }
+            if (line.startsWith('--- ') || line.startsWith('diff ') || line.startsWith('@@') || skipFile)
+                return;
+            if (line.startsWith('+')) {
+                for (const m of scanLine(line.slice(1))) {
+                    const key = `${file}:${m.kind}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    if (findings.length < MAX_FINDINGS)
+                        findings.push({ commit, file, kind: m.kind, why: m.why });
+                }
+            }
+        });
+        let stderr = '';
+        child.stderr.on('data', (d) => (stderr += d));
+        child.on('error', reject);
+        child.on('close', (code) => (code === 0 || code === null ? resolve() : reject(new Error(`git log exited ${code}: ${stderr.trim()}`))));
+    });
+    return { findings, commits, isRepo: true, trackedEnv };
+}
+export async function checkGitSecrets(project) {
+    let scan;
+    try {
+        scan = await scanGitHistory(project);
+    }
+    catch (e) {
+        return { id: 'git-secrets', status: 'fail', reason: `Could not scan git history: ${e.message}.` };
+    }
+    if (!scan.isRepo)
+        return { id: 'git-secrets', status: 'skip', reason: 'Not a git repository, so there is no history to scan.' };
+    const data = { commits: scan.commits, findings: scan.findings, trackedEnvFiles: scan.trackedEnv };
+    if (scan.findings.length > 0) {
+        const first = scan.findings[0];
+        return {
+            id: 'git-secrets',
+            status: 'fail',
+            reason: `${scan.findings.length} secret-shaped addition${scan.findings.length === 1 ? '' : 's'} in ${scan.commits} commits, first in ${first.file} at ${first.commit.slice(0, 10)} (${first.why}); rotate the key, then rewrite history or start a new repository.`,
+            data,
+        };
+    }
+    if (scan.trackedEnv.length > 0) {
+        return { id: 'git-secrets', status: 'fail', reason: `${scan.trackedEnv.join(', ')} is tracked by git; a .env file belongs in .gitignore even when it holds no key today.`, data };
+    }
+    return { id: 'git-secrets', status: 'pass', reason: `No secret-shaped line added in ${scan.commits} commits, and no .env file is tracked.`, data };
+}
+function run(cmd, args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => (stdout += d));
+        child.stderr.on('data', (d) => (stderr += d));
+        child.on('error', (e) => resolve({ code: null, stdout, stderr: e.message }));
+        child.on('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}

package/dist/checks/slither.d.ts

@@ -0,0 +1,11 @@
+import type { CheckResult } from '../types.js';
+export declare const DEFAULT_REPORT_PATHS: string[];
+/** Sidecar written next to the report: the hash of the sources Slither saw. */
+export declare const SOURCES_HASH_FILE = "slither.sources.sha256";
+/**
+ * SHA-256 over every `.sol` file under `dir`, in sorted order of its POSIX relative path:
+ * for each file, `<relative path>\n`, the file's bytes, then a NUL byte. The scaffold's
+ * `scripts/slither.mjs` computes the same value with the same recipe; keep them in step.
+ */
+export declare function hashSources(dir: string): string;
+export declare function checkSlitherReport(project: string, sourceDir: string, reportPath?: string): Promise<CheckResult>;

package/dist/checks/slither.js

@@ -0,0 +1,119 @@
+// Does a Slither report exist, and does it describe the sources as they are now? Two ways to
+// answer. Preferred: a sidecar `slither.sources.sha256` next to the report holding the hash
+// of every .sol file under the source directory at the time Slither ran (the scaffold's
+// `npm run lint:slither` writes it); the check recomputes the hash and compares. Fallback,
+// when there is no sidecar: times. Checked-out files all share one mtime, so inside a git
+// repository "when" means the commit time of the last change, with the working-tree mtime
+// taken instead for files that are modified or untracked; outside git, plain mtimes. The
+// time rule cannot be satisfied by re-running Slither on a clean project, because a report
+// with no findings is byte-identical and git records no new change for it (found on
+// 2026-09-12 running the prompt cards), which is why the hash sidecar exists.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { run } from '../proc.js';
+export const DEFAULT_REPORT_PATHS = ['reports/slither.json', 'reports/slither.md', 'slither.json', 'slither-report.json', 'slither.md'];
+/** Sidecar written next to the report: the hash of the sources Slither saw. */
+export const SOURCES_HASH_FILE = 'slither.sources.sha256';
+/**
+ * SHA-256 over every `.sol` file under `dir`, in sorted order of its POSIX relative path:
+ * for each file, `<relative path>\n`, the file's bytes, then a NUL byte. The scaffold's
+ * `scripts/slither.mjs` computes the same value with the same recipe; keep them in step.
+ */
+export function hashSources(dir) {
+    const files = listFiles(dir)
+        .filter((f) => f.endsWith('.sol'))
+        .map((f) => ({ rel: relative(dir, f).split(sep).join('/'), abs: f }))
+        .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    const h = createHash('sha256');
+    for (const f of files) {
+        h.update(`${f.rel}\n`);
+        h.update(readFileSync(f.abs));
+        h.update('\0');
+    }
+    return h.digest('hex');
+}
+export async function checkSlitherReport(project, sourceDir, reportPath) {
+    const candidates = reportPath ? [reportPath] : DEFAULT_REPORT_PATHS;
+    const found = candidates.map((p) => join(project, p)).find((p) => existsSync(p));
+    if (!found) {
+        return { id: 'slither-report', status: 'fail', reason: `No Slither report at ${candidates.join(', ')}; run slither and commit the report before deploying.`, data: { looked: candidates } };
+    }
+    const srcAbs = join(project, sourceDir);
+    if (!existsSync(srcAbs))
+        return { id: 'slither-report', status: 'fail', reason: `Source directory ${sourceDir} does not exist under ${project}.`, data: { report: found } };
+    const sources = listFiles(srcAbs).filter((f) => f.endsWith('.sol'));
+    if (sources.length === 0)
+        return { id: 'slither-report', status: 'fail', reason: `No .sol files under ${sourceDir}.`, data: { report: found } };
+    const sidecar = join(dirname(found), SOURCES_HASH_FILE);
+    if (existsSync(sidecar)) {
+        const recorded = readFileSync(sidecar, 'utf8').trim().toLowerCase();
+        const current = hashSources(srcAbs);
+        const data = { report: relative(project, found), sidecar: relative(project, sidecar), recordedHash: recorded, currentHash: current, sources: sources.length };
+        if (recorded === current)
+            return { id: 'slither-report', status: 'pass', reason: `${data.report} describes the current sources: ${data.sidecar} matches the hash of ${sources.length} .sol file(s) under ${sourceDir}.`, data };
+        return { id: 'slither-report', status: 'fail', reason: `${data.report} is stale: the sources under ${sourceDir} no longer match ${data.sidecar}; re-run slither.`, data };
+    }
+    const times = await fileTimes(project, [found, ...sources]);
+    const reportTime = times.get(found) ?? 0;
+    let newestSource = '';
+    let newestTime = 0;
+    for (const s of sources) {
+        const t = times.get(s) ?? 0;
+        if (t > newestTime) {
+            newestTime = t;
+            newestSource = s;
+        }
+    }
+    const data = { report: relative(project, found), reportTime: iso(reportTime), newestSource: relative(project, newestSource), newestSourceTime: iso(newestTime), sources: sources.length };
+    if (reportTime >= newestTime)
+        return { id: 'slither-report', status: 'pass', reason: `${data.report} (${data.reportTime}) is newer than the newest source ${data.newestSource} (${data.newestSourceTime}).`, data };
+    return { id: 'slither-report', status: 'fail', reason: `${data.report} (${data.reportTime}) is older than ${data.newestSource} (${data.newestSourceTime}); re-run slither and write ${SOURCES_HASH_FILE} beside the report (the scaffold's npm run lint:slither does both).`, data };
+}
+function iso(t) {
+    return t ? new Date(t * 1000).toISOString() : 'unknown';
+}
+function listFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listFiles(p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** Unix seconds per file: git commit time, or mtime for dirty, untracked or non-git files. */
+async function fileTimes(project, files) {
+    const out = new Map();
+    const mtime = (f) => Math.floor(statSync(f).mtimeMs / 1000);
+    const inRepo = await run('git', ['rev-parse', '--is-inside-work-tree'], { cwd: project, timeoutMs: 10_000 });
+    if (inRepo.code !== 0 || inRepo.stdout.trim() !== 'true') {
+        for (const f of files)
+            out.set(f, mtime(f));
+        return out;
+    }
+    const status = await run('git', ['status', '--porcelain', '--untracked-files=all', '--', ...files], { cwd: project, timeoutMs: 30_000 });
+    const dirty = new Set(status.stdout.split('\n').filter(Boolean).map((l) => join(repoRoot(project), l.slice(3).trim())));
+    for (const f of files) {
+        if (dirty.has(f)) {
+            out.set(f, mtime(f));
+            continue;
+        }
+        const log = await run('git', ['log', '-1', '--format=%ct', '--', f], { cwd: project, timeoutMs: 30_000 });
+        const t = Number(log.stdout.trim());
+        out.set(f, Number.isFinite(t) && t > 0 ? t : mtime(f));
+    }
+    return out;
+}
+let rootCache = null;
+/** git status prints paths relative to the repository root, which may be above `project`. */
+function repoRoot(project) {
+    if (rootCache && rootCache.project === project)
+        return rootCache.root;
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: project, encoding: 'utf8' }).trim();
+    rootCache = { project, root };
+    return root;
+}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import type { RunOptions } from './run.js';
+export declare function parseArgs(argv: readonly string[]): RunOptions & {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+};
+export declare function main(argv?: readonly string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// redbelly-preflight: run before any deployment. Exit 0 when no check fails, 1 when one does,
+// 2 on bad arguments. Never takes a key: --account names a Foundry keystore that cast reads.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { CHECK_IDS, DEFAULT_GAS, VERSION, renderText, runPreflight } from './run.js';
+const HELP = `redbelly-preflight [options]
+
+Checks a project before it deploys to Redbelly Network. Reads foundry.toml or
+hardhat.config.*, talks JSON-RPC to one RPC and nothing else, and never sees a key.
+
+  --project <dir>          project directory (default: current directory)
+  --profile <name>         Foundry profile or Hardhat network to read
+  --chain <151|153>        expected chain; defaults to the config's chain id, then CHAIN_ID in .env
+  --rpc <url>              JSON-RPC endpoint; defaults to the governors RPC for --chain
+  --account <name>         Foundry keystore name; address resolved with cast wallet address
+  --password-file <path>   passed through to cast for that keystore (or set ETH_PASSWORD)
+  --address <0x…>          deployer address for a read-only run (or DEPLOYER in .env)
+  --admin <0x…>            address that will own the contracts (or ADMIN_SAFE in .env)
+  --gas <units>            expected deployment gas (default ${DEFAULT_GAS.toLocaleString('en-US')})
+  --slither-report <path>  report file (default: reports/slither.json or reports/slither.md)
+  --skip <id,id>           skip checks: ${CHECK_IDS.join(', ')}
+  --json                   print the report as JSON
+  --version, --help
+`;
+export function parseArgs(argv) {
+    const o = { json: false, help: false, version: false };
+    const skip = [];
+    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 '--profile':
+                o.profile = 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 '--account':
+                o.account = next();
+                break;
+            case '--password-file':
+                o.passwordFile = next();
+                break;
+            case '--address':
+                o.address = next();
+                break;
+            case '--admin':
+                o.admin = next();
+                break;
+            case '--gas': {
+                const g = next().replace(/[_,]/g, '');
+                if (!/^\d+$/.test(g))
+                    throw new Error('--gas must be a whole number of gas units');
+                o.gas = BigInt(g);
+                break;
+            }
+            case '--slither-report':
+                o.slitherReport = next();
+                break;
+            case '--skip':
+                for (const id of next().split(',').map((s) => s.trim()).filter(Boolean)) {
+                    if (!CHECK_IDS.includes(id))
+                        throw new Error(`unknown check "${id}"; known: ${CHECK_IDS.join(', ')}`);
+                    skip.push(id);
+                }
+                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; pre-flight never takes one, use --account <keystore-name>');
+                throw new Error(`unknown argument "${a}"\n\n${HELP}`);
+        }
+    }
+    if (skip.length)
+        o.skip = skip;
+    return o;
+}
+export async function main(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (args.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (args.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    const { json, help: _h, version: _v, ...opts } = args;
+    const report = await runPreflight(opts);
+    process.stdout.write(json ? JSON.stringify(report, null, 2) + '\n' : renderText(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)
+    main().then((code) => { process.exitCode = code; }, (e) => { process.stderr.write(`${e.stack ?? e}\n`); process.exitCode = 2; });

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+export interface ProjectConfig {
+    kind: 'foundry' | 'hardhat' | 'none';
+    file: string | null;
+    profile: string | null;
+    solc: string | null;
+    evmVersion: string | null;
+    optimizerRuns: number | null;
+    /** foundry: `src`; hardhat: `contracts`. */
+    sourceDir: string;
+    /** foundry `chain_id` or the hardhat network's `chainId`. */
+    chainId: number | null;
+    /** foundry [rpc_endpoints] or hardhat networks' url values, by name. */
+    rpcEndpoints: Record<string, string>;
+    /** The RPC url of the chosen hardhat network, if any. */
+    rpcUrl: string | null;
+}
+export declare const HARDHAT_CONFIG_NAMES: string[];
+export declare function readProjectConfig(project: string, profile?: string, env?: NodeJS.ProcessEnv): ProjectConfig;
+type TomlValue = string | number | boolean | TomlValue[];
+type TomlTable = Record<string, TomlValue>;
+/** Enough TOML for foundry.toml: sections, dotted headers, scalars, one-line arrays, comments. */
+export declare function parseToml(text: string): Record<string, TomlTable>;
+export declare function readFoundryConfig(file: string, profile: string): ProjectConfig;
+export declare function readHardhatConfig(file: string, network: string | null): ProjectConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,197 @@
+// Reads the target profile from foundry.toml or hardhat.config.* without executing anything.
+// Foundry's TOML is parsed by a small reader that understands the subset Foundry projects use:
+// [section] headers, dotted section names, `key = value` with strings, numbers, booleans and
+// one-line arrays. Hardhat configs are JavaScript, so they are scanned with regular expressions
+// after brace matching narrows the text to the chosen network block. Both readers are tolerant:
+// what they cannot find they report as null, and the checks say so.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const HARDHAT_CONFIG_NAMES = ['hardhat.config.ts', 'hardhat.config.js', 'hardhat.config.cjs', 'hardhat.config.mjs', 'hardhat.config.cts', 'hardhat.config.mts'];
+export function readProjectConfig(project, profile, env = process.env) {
+    const foundry = join(project, 'foundry.toml');
+    if (existsSync(foundry))
+        return readFoundryConfig(foundry, profile ?? env['FOUNDRY_PROFILE'] ?? 'default');
+    for (const name of HARDHAT_CONFIG_NAMES) {
+        const file = join(project, name);
+        if (existsSync(file))
+            return readHardhatConfig(file, profile ?? null);
+    }
+    return { kind: 'none', file: null, profile: null, solc: null, evmVersion: null, optimizerRuns: null, sourceDir: 'src', chainId: null, rpcEndpoints: {}, rpcUrl: null };
+}
+/** Enough TOML for foundry.toml: sections, dotted headers, scalars, one-line arrays, comments. */
+export function parseToml(text) {
+    const out = {};
+    let section = '';
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = stripComment(rawLine).trim();
+        if (!line)
+            continue;
+        const header = /^\[\s*([^\]]+?)\s*\]$/.exec(line);
+        if (header) {
+            section = header[1].replace(/\s+/g, '');
+            out[section] ??= {};
+            continue;
+        }
+        const kv = /^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/.exec(line);
+        if (!kv)
+            continue;
+        out[section] ??= {};
+        out[section][kv[1]] = parseTomlValue(kv[2].trim());
+    }
+    return out;
+}
+function stripComment(line) {
+    let inString = null;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (inString) {
+            if (c === inString)
+                inString = null;
+        }
+        else if (c === '"' || c === "'")
+            inString = c;
+        else if (c === '#')
+            return line.slice(0, i);
+    }
+    return line;
+}
+function parseTomlValue(raw) {
+    if (raw.startsWith('[') && raw.endsWith(']')) {
+        const inner = raw.slice(1, -1).trim();
+        if (!inner)
+            return [];
+        return splitTopLevel(inner).map((v) => parseTomlValue(v.trim()));
+    }
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))
+        return raw.slice(1, -1);
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d[\d_]*$/.test(raw))
+        return Number(raw.replace(/_/g, ''));
+    if (/^-?\d[\d_]*\.\d+$/.test(raw))
+        return Number(raw.replace(/_/g, ''));
+    return raw;
+}
+function splitTopLevel(s) {
+    const parts = [];
+    let depth = 0;
+    let inString = null;
+    let cur = '';
+    for (const c of s) {
+        if (inString) {
+            cur += c;
+            if (c === inString)
+                inString = null;
+            continue;
+        }
+        if (c === '"' || c === "'")
+            inString = c;
+        if (c === '[')
+            depth++;
+        if (c === ']')
+            depth--;
+        if (c === ',' && depth === 0) {
+            parts.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += c;
+    }
+    if (cur.trim())
+        parts.push(cur);
+    return parts;
+}
+export function readFoundryConfig(file, profile) {
+    const toml = parseToml(readFileSync(file, 'utf8'));
+    const base = toml['profile.default'] ?? {};
+    const chosen = toml[`profile.${profile}`] ?? {};
+    const get = (key) => chosen[key] ?? base[key];
+    const str = (key) => {
+        const v = get(key);
+        return typeof v === 'string' ? v : null;
+    };
+    const num = (key) => {
+        const v = get(key);
+        return typeof v === 'number' ? v : null;
+    };
+    const rpcEndpoints = {};
+    for (const [k, v] of Object.entries(toml['rpc_endpoints'] ?? {}))
+        if (typeof v === 'string')
+            rpcEndpoints[k] = expandEnv(v);
+    return {
+        kind: 'foundry',
+        file,
+        profile,
+        solc: str('solc') ?? str('solc_version'),
+        evmVersion: str('evm_version'),
+        optimizerRuns: num('optimizer_runs'),
+        sourceDir: str('src') ?? 'src',
+        chainId: num('chain_id'),
+        rpcEndpoints,
+        rpcUrl: null,
+    };
+}
+/** Foundry lets an endpoint be `${RPC_URL}`; expand from the environment when set. */
+function expandEnv(v) {
+    return v.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => process.env[name] ?? `\${${name}}`);
+}
+// ---------- Hardhat ----------
+export function readHardhatConfig(file, network) {
+    const text = readFileSync(file, 'utf8');
+    const solidity = blockAfter(text, /\bsolidity\s*:/) ?? '';
+    const versions = [...(solidity || text).matchAll(/\bversion\s*:\s*["']([\d.]+)["']/g)].map((m) => m[1]);
+    const shorthand = /\bsolidity\s*:\s*["']([\d.]+)["']/.exec(text);
+    const solc = shorthand ? shorthand[1] : versions.length === 1 ? versions[0] : versions.length > 1 ? versions.join(',') : null;
+    const evm = /\bevmVersion\s*:\s*["']([A-Za-z]+)["']/.exec(solidity || text);
+    const runs = /\bruns\s*:\s*(\d+)/.exec(solidity || text);
+    const networks = blockAfter(text, /\bnetworks\s*:/) ?? '';
+    const rpcEndpoints = {};
+    const chainIds = {};
+    for (const m of networks.matchAll(/([A-Za-z0-9_]+)\s*:\s*\{/g)) {
+        const name = m[1];
+        const body = blockAfter(networks.slice(m.index), new RegExp(`\\b${name}\\s*:`)) ?? '';
+        const url = /\burl\s*:\s*["'`]([^"'`]+)["'`]/.exec(body);
+        const cid = /\bchainId\s*:\s*(\d+)/.exec(body);
+        if (url)
+            rpcEndpoints[name] = url[1];
+        if (cid)
+            chainIds[name] = Number(cid[1]);
+    }
+    const chosen = network ?? null;
+    const contractsDir = /\bsources\s*:\s*["']([^"']+)["']/.exec(text);
+    return {
+        kind: 'hardhat',
+        file,
+        profile: chosen,
+        solc,
+        evmVersion: evm ? evm[1] : null,
+        optimizerRuns: runs ? Number(runs[1]) : null,
+        sourceDir: contractsDir ? contractsDir[1].replace(/^\.\//, '') : 'contracts',
+        chainId: chosen ? (chainIds[chosen] ?? null) : null,
+        rpcEndpoints,
+        rpcUrl: chosen ? (rpcEndpoints[chosen] ?? null) : null,
+    };
+}
+/** Text of the `{ ... }` block that follows the first match of `key`, with braces balanced. */
+function blockAfter(text, key) {
+    const m = key.exec(text);
+    if (!m)
+        return null;
+    const start = text.indexOf('{', m.index + m[0].length);
+    if (start < 0)
+        return null;
+    let depth = 0;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (c === '{')
+            depth++;
+        else if (c === '}') {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}

package/dist/doctor-cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export declare const DOCTOR_HELP = "redbelly-doctor [options]\n\nChecks the machine before the first command: Node 22 or later; forge, anvil and cast on\nPATH, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0\nwhatever the binary returned; slither and aderyn (optional); git; no .env tracked by git;\nand, in a scaffold, vendor/ matching the versions the scaffolder recorded. One line per\ncheck with the fix on the same line. Touches no network and no key.\n\n  --project <dir>   scaffold root, its contracts/ folder, or any directory (default: cwd)\n  --json            print the report as JSON\n  --version, --help\n\nExit 0 when every required check passes (optional checks may warn), 1 otherwise, 2 on bad arguments.\n";
+export declare function parseDoctorArgs(argv: readonly string[]): {
+    project?: string;
+    json: boolean;
+    help: boolean;
+    version: boolean;
+};
+export declare function doctorMain(argv?: readonly string[]): Promise<number>;