@gatedpath/preflight 0.1.0

package/dist/gas.js

@@ -0,0 +1,221 @@
+// redbelly gas: a gas report in the unit the chain charges in. Reads `.gas-snapshot` (one line per
+// test) or `forge test --gas-report --json` (deployment and every function of the contracts in
+// foundry.toml's gas_reports), prices each row at the latest base fee and the on-chain feed price
+// through the same arithmetic as gasCostUsd in @gatedpath/chains, and prints RBNT and US cents per
+// row, with `--diff <file>` against a previous snapshot or report. Read-only: two RPC reads
+// (eth_getBlockByNumber and the feed) and nothing else. No key.
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, join, relative, resolve } from 'node:path';
+import { PRICE_FEED_DECIMALS, chainById, formatUnits, getLatestPrice, toCaller } from '@gatedpath/chains';
+import { run } from './proc.js';
+const require = createRequire(import.meta.url);
+export const GAS_VERSION = require('../package.json').version;
+// ---- parsing, pure ----
+const SNAPSHOT_LINE = /^([A-Za-z0-9_$]+):(\S.*?)\s+\((.*)\)\s*$/;
+/** `.gas-snapshot`: `Contract:test() (gas: N)`, fuzz lines by their mean (μ), invariant lines (no gas) skipped. */
+export function parseGasSnapshot(text) {
+    const rows = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const m = SNAPSHOT_LINE.exec(line);
+        if (!m)
+            continue;
+        const [, contract, item, inside] = m;
+        const gas = /(?:^|,\s*)gas:\s*(\d+)/.exec(inside);
+        const mean = /μ:\s*(\d+)/.exec(inside);
+        const runs = /runs:\s*(\d+)/.exec(inside);
+        const median = /~:\s*(\d+)/.exec(inside);
+        if (gas)
+            rows.push({ name: `${contract}:${item}`, contract: contract, item: item, gas: BigInt(gas[1]) });
+        else if (mean)
+            rows.push({ name: `${contract}:${item}`, contract: contract, item: item, gas: BigInt(mean[1]), ...(runs ? { calls: Number(runs[1]) } : {}), ...(median ? { min: BigInt(median[1]), max: BigInt(median[1]) } : {}) });
+    }
+    return rows;
+}
+/** `forge test --gas-report --json`: the deployment row, then each function by its mean. Contract names lose their path. */
+export function parseGasReportJson(json) {
+    const entries = Array.isArray(json) ? json : [];
+    const rows = [];
+    for (const e of entries) {
+        if (!e || typeof e.contract !== 'string')
+            continue;
+        const contract = e.contract.includes(':') ? e.contract.slice(e.contract.lastIndexOf(':') + 1) : basename(e.contract, '.sol');
+        if (e.deployment && typeof e.deployment.gas === 'number')
+            rows.push({ name: `${contract}:deployment`, contract, item: 'deployment', gas: BigInt(e.deployment.gas) });
+        for (const [sig, f] of Object.entries(e.functions ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+            rows.push({ name: `${contract}:${sig}`, contract, item: sig, gas: BigInt(Math.round(f.mean)), calls: f.calls, min: BigInt(f.min), max: BigInt(f.max) });
+        }
+    }
+    return rows;
+}
+/** Either format, by content: JSON that parses as an array is a gas report; anything else is a snapshot. */
+export function parseGasFile(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('[')) {
+        try {
+            return { kind: 'gas-report-file', rows: parseGasReportJson(JSON.parse(trimmed)) };
+        }
+        catch {
+            /* fall through: not JSON after all */
+        }
+    }
+    return { kind: 'snapshot', rows: parseGasSnapshot(text) };
+}
+// ---- pricing, pure given a quote ----
+/** wei = gas * baseFee; thousandths of a US cent = wei * raw / 10^(18 + 6 - 5). Only the last step leaves BigInt. */
+export function priceGas(gas, quote) {
+    const wei = gas * quote.baseFeeWei;
+    const scaled = wei * quote.priceRaw; // USD times 10^(18+6)
+    const milliCents = scaled / 10n ** BigInt(18 + PRICE_FEED_DECIMALS - 5); // cents times 1000
+    const cents = Number(milliCents) / 1000;
+    const usd = Number((scaled * 1000000000n) / 10n ** BigInt(18 + PRICE_FEED_DECIMALS)) / 1e9;
+    return { wei, rbnt: formatUnits(wei, 18), usd, cents };
+}
+export function priceRows(rows, quote, before) {
+    const prior = new Map((before ?? []).map((r) => [r.name, r]));
+    const priced = rows.map((r) => {
+        const p = priceGas(r.gas, quote);
+        const b = prior.get(r.name);
+        if (!before)
+            return { ...r, ...p };
+        if (!b)
+            return { ...r, ...p };
+        const bp = priceGas(b.gas, quote);
+        return { ...r, ...p, before: { gas: b.gas, cents: bp.cents }, delta: { gas: r.gas - b.gas, cents: Math.round((p.cents - bp.cents) * 1000) / 1000 } };
+    });
+    const names = new Set(rows.map((r) => r.name));
+    return { rows: priced, added: before ? rows.filter((r) => !prior.has(r.name)).map((r) => r.name) : [], removed: before ? [...prior.keys()].filter((n) => !names.has(n)) : [] };
+}
+// ---- the two reads ----
+export async function quoteGas(rpc, expected) {
+    const caller = toCaller(rpc);
+    const reported = Number(BigInt((await caller('eth_chainId'))));
+    if (reported !== 151 && reported !== 153)
+        throw new Error(`the RPC at ${rpc} reports chain ${reported}; redbelly gas prices through the feed on 151 or 153 (a fork of either works)`);
+    if (expected && reported !== expected)
+        throw new Error(`--chain ${expected} but the RPC at ${rpc} reports ${reported}`);
+    const block = (await caller('eth_getBlockByNumber', ['latest', false]));
+    if (!block?.baseFeePerGas)
+        throw new Error('the latest block has no baseFeePerGas');
+    const price = await getLatestPrice({ rpc });
+    return {
+        chain: reported,
+        network: reported === 151 ? 'mainnet' : 'testnet',
+        rpc,
+        block: Number(BigInt(block.number ?? '0x0')),
+        baseFeeWei: BigInt(block.baseFeePerGas),
+        priceRaw: price.raw,
+        usdPerRbnt: price.usdPerRbnt,
+        priceTimestamp: new Date(price.timestamp * 1000).toISOString(),
+        priceFeed: price.priceFeed,
+    };
+}
+/** A scaffold root's contracts/ when that is where foundry.toml is; otherwise the directory itself. */
+export function foundryDir(project) {
+    if (!existsSync(join(project, 'foundry.toml')) && existsSync(join(project, 'contracts', 'foundry.toml')))
+        return join(project, 'contracts');
+    return project;
+}
+export async function readGasSource(dir, opts) {
+    if (opts.snapshot) {
+        const file = resolve(dir, opts.snapshot);
+        if (!existsSync(file))
+            throw new Error(`no such file: ${file}`);
+        const parsed = parseGasFile(readFileSync(file, 'utf8'));
+        return { source: { kind: parsed.kind, file }, rows: parsed.rows };
+    }
+    const snapshot = join(dir, '.gas-snapshot');
+    if (!opts.report && existsSync(snapshot))
+        return { source: { kind: 'snapshot', file: snapshot }, rows: parseGasSnapshot(readFileSync(snapshot, 'utf8')) };
+    if (!existsSync(join(dir, 'foundry.toml')))
+        throw new Error(`no .gas-snapshot and no foundry.toml in ${dir}; pass --snapshot <file> or run from a Foundry project`);
+    const args = ['test', '--gas-report', '--json'];
+    const r = await run('forge', args, { cwd: dir, env: opts.env ?? process.env, timeoutMs: 600_000 });
+    if (r.spawnError)
+        throw new Error(`forge is not installed or not on PATH (${r.spawnError}); run redbelly-doctor`);
+    const jsonStart = r.stdout.indexOf('[');
+    if (r.code !== 0 || jsonStart < 0)
+        throw new Error(`forge test --gas-report --json exited ${r.code}:\n${(r.stderr || r.stdout).trim().slice(-2000)}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(r.stdout.slice(jsonStart));
+    }
+    catch {
+        throw new Error('forge printed a gas report that is not JSON');
+    }
+    return { source: { kind: 'gas-report', command: `forge ${args.join(' ')}` }, rows: parseGasReportJson(parsed) };
+}
+export async function runGas(opts = {}) {
+    const project = resolve(opts.project ?? process.cwd());
+    const dir = foundryDir(project);
+    const { source, rows } = await readGasSource(dir, opts);
+    if (rows.length === 0)
+        throw new Error(`nothing to price: ${source.kind === 'gas-report' ? 'the gas report has no contracts (set gas_reports in foundry.toml)' : `${source.file} has no gas lines`}`);
+    let before;
+    let diffFile = null;
+    if (opts.diff) {
+        diffFile = resolve(dir, opts.diff);
+        if (!existsSync(diffFile))
+            throw new Error(`--diff: no such file: ${diffFile}`);
+        before = parseGasFile(readFileSync(diffFile, 'utf8')).rows;
+    }
+    const chain = opts.chain ?? 153;
+    const rpc = opts.rpc ?? chainById(chain).rpcUrls.default.http[0];
+    const quote = await quoteGas(rpc, opts.chain);
+    const priced = priceRows(rows, quote, before);
+    return {
+        tool: 'redbelly-gas',
+        version: GAS_VERSION,
+        generatedAt: new Date().toISOString(),
+        project,
+        source,
+        quote,
+        rows: priced.rows,
+        diff: diffFile ? { file: diffFile, rows: before.length, added: priced.added, removed: priced.removed } : null,
+    };
+}
+// ---- text ----
+const num = (n) => n.toLocaleString('en-US');
+const fixed = (n, d) => n.toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d });
+const gwei = (wei) => `${fixed(Number(wei) / 1e9, 2)} gwei`;
+const rbnt6 = (s) => {
+    const n = Number(s);
+    return n === 0 ? '0' : n < 0.000001 ? '<0.000001' : fixed(n, 6);
+};
+const signed = (n, d = 0) => (Number(n) > 0 ? '+' : '') + (typeof n === 'bigint' ? num(n) : fixed(n, d));
+export function renderGasText(report) {
+    const q = report.quote;
+    const src = report.source.kind === 'gas-report' ? `${report.source.command} (${report.rows.length} rows)` : `${relative(report.project, report.source.file) || basename(report.source.file)} (${report.rows.length} rows${report.source.kind === 'snapshot' ? ', one per test' : ''})`;
+    const lines = [];
+    lines.push(`redbelly gas ${report.version}  project ${report.project}  source ${src}`);
+    lines.push(`chain ${q.chain} (${q.network}) via ${q.rpc}  block ${num(q.block)}  base fee ${gwei(q.baseFeeWei)}  RBNT US$${fixed(q.usdPerRbnt, 6)} (feed at ${q.priceTimestamp})`);
+    if (report.diff)
+        lines.push(`diff against ${relative(report.project, report.diff.file) || report.diff.file} (${report.diff.rows} rows${report.diff.added.length ? `, ${report.diff.added.length} new here` : ''}${report.diff.removed.length ? `, ${report.diff.removed.length} gone` : ''})`);
+    lines.push('');
+    const w = Math.min(72, Math.max(24, ...report.rows.map((r) => r.name.length)));
+    const head = ['Item'.padEnd(w), 'Gas'.padStart(11), 'RBNT'.padStart(12), 'US cents'.padStart(10)];
+    if (report.diff)
+        head.push('Gas diff'.padStart(11), 'Cents diff'.padStart(11));
+    lines.push(head.join('  '));
+    for (const r of report.rows) {
+        const cells = [r.name.length > w ? r.name.slice(0, w - 1) + '…' : r.name.padEnd(w), num(r.gas).padStart(11), rbnt6(r.rbnt).padStart(12), fixed(r.cents, 3).padStart(10)];
+        if (report.diff)
+            cells.push((r.delta ? signed(r.delta.gas) : 'new').padStart(11), (r.delta ? signed(r.delta.cents, 3) : '').padStart(11));
+        lines.push(cells.join('  '));
+    }
+    if (report.diff?.removed.length)
+        lines.push('', `gone since ${basename(report.diff.file)}: ${report.diff.removed.join(', ')}`);
+    const deploys = report.rows.filter((r) => r.item === 'deployment');
+    lines.push('');
+    if (deploys.length)
+        lines.push(`deployment: ${deploys.map((d) => `${d.contract} ${num(d.gas)} gas = ${rbnt6(d.rbnt)} RBNT = US$${fixed(d.usd, 4)}`).join('; ')}. Pre-flight's balance check adds 25% on top; pass its --gas the figure here.`);
+    lines.push(`Gas is priced in US dollars and converted to RBNT at execution from the feed, so the cents column is the stable one; the RBNT column moves with the price. Base fee only: the chain charges no priority fee.`);
+    return lines.join('\n') + '\n';
+}
+/** JSON with BigInt as decimal strings. */
+export function gasReportJson(report) {
+    return JSON.stringify(report, (_k, v) => (typeof v === 'bigint' ? v.toString() : v), 2) + '\n';
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export { runPreflight, renderText, CHECK_IDS, DEFAULT_GAS, VERSION } from './run.js';
+export type { RunOptions } from './run.js';
+export type { CheckId, CheckResult, CheckStatus, PreflightOptions, PreflightReport } from './types.js';
+export { readProjectConfig, parseToml, readFoundryConfig, readHardhatConfig, HARDHAT_CONFIG_NAMES } from './config.js';
+export type { ProjectConfig } from './config.js';
+export { scanLine, scanText, scanValue, mnemonicRun } from './secrets.js';
+export type { SecretKind, SecretMatch } from './secrets.js';
+export { scanGitHistory, checkGitSecrets } from './checks/git-secrets.js';
+export { readAdmin, checkAdminSafe, codeHash, SAFE_141_CODE_HASHES } from './checks/admin.js';
+export { checkCompilerPins, SOLC_PIN, EVM_PIN } from './checks/compiler.js';
+export { checkBalance, MARGIN_PERCENT } from './checks/balance.js';
+export { checkSlitherReport, hashSources, DEFAULT_REPORT_PATHS, SOURCES_HASH_FILE } from './checks/slither.js';
+export { checkChainId } from './checks/chain-id.js';
+export { resolveDeployer, checkDeployerVerified } from './checks/deployer.js';
+export { run as runProcess, ACCOUNT_NAME } from './proc.js';
+export { WELL_KNOWN_DEV_ACCOUNTS, isWellKnownDevAccount } from './well-known.js';
+export { readDotEnv, ENV_NAMES } from './dotenv.js';
+export { runDoctor, renderDoctorText, whichOnPath, toolVersion, exitCodePropagates, looksLikeNodeShim, realBinaryNear, scaffoldRoot, DOCTOR_CHECK_IDS, NODE_MIN_MAJOR, SLITHER_PIN, ADERYN_PIN } from './doctor.js';
+export type { DoctorCheck, DoctorCheckId, DoctorOptions, DoctorReport, DoctorStatus } from './doctor.js';
+export { doctorMain, parseDoctorArgs, DOCTOR_HELP } from './doctor-cli.js';
+export { runGas, quoteGas, priceGas, priceRows, parseGasSnapshot, parseGasReportJson, parseGasFile, readGasSource, foundryDir, renderGasText, gasReportJson } from './gas.js';
+export type { GasRow, GasSource, GasQuote, PricedRow, GasReport, GasOptions } from './gas.js';
+export { gasMain, parseGasArgs, GAS_HELP } from './gas-cli.js';
+export { findGatedSuites, summariseTests } from './suites.js';
+export type { ForgeTestJson, SuiteSummary } from './suites.js';
+export { runShip, renderShipMarkdown, renderShipText, shipReportJson, shipReportPath, parseShipHeader, readShipContracts, routescanBase, utcDate, SHIP_HEADER } from './ship.js';
+export type { ShipOptions, ShipReport, ShipCheck, ShipContract } from './ship.js';
+export { shipMain, parseShipArgs, SHIP_HELP } from './ship-cli.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+export { runPreflight, renderText, CHECK_IDS, DEFAULT_GAS, VERSION } from './run.js';
+export { readProjectConfig, parseToml, readFoundryConfig, readHardhatConfig, HARDHAT_CONFIG_NAMES } from './config.js';
+export { scanLine, scanText, scanValue, mnemonicRun } from './secrets.js';
+export { scanGitHistory, checkGitSecrets } from './checks/git-secrets.js';
+export { readAdmin, checkAdminSafe, codeHash, SAFE_141_CODE_HASHES } from './checks/admin.js';
+export { checkCompilerPins, SOLC_PIN, EVM_PIN } from './checks/compiler.js';
+export { checkBalance, MARGIN_PERCENT } from './checks/balance.js';
+export { checkSlitherReport, hashSources, DEFAULT_REPORT_PATHS, SOURCES_HASH_FILE } from './checks/slither.js';
+export { checkChainId } from './checks/chain-id.js';
+export { resolveDeployer, checkDeployerVerified } from './checks/deployer.js';
+export { run as runProcess, ACCOUNT_NAME } from './proc.js';
+export { WELL_KNOWN_DEV_ACCOUNTS, isWellKnownDevAccount } from './well-known.js';
+export { readDotEnv, ENV_NAMES } from './dotenv.js';
+export { runDoctor, renderDoctorText, whichOnPath, toolVersion, exitCodePropagates, looksLikeNodeShim, realBinaryNear, scaffoldRoot, DOCTOR_CHECK_IDS, NODE_MIN_MAJOR, SLITHER_PIN, ADERYN_PIN } from './doctor.js';
+export { doctorMain, parseDoctorArgs, DOCTOR_HELP } from './doctor-cli.js';
+export { runGas, quoteGas, priceGas, priceRows, parseGasSnapshot, parseGasReportJson, parseGasFile, readGasSource, foundryDir, renderGasText, gasReportJson } from './gas.js';
+export { gasMain, parseGasArgs, GAS_HELP } from './gas-cli.js';
+export { findGatedSuites, summariseTests } from './suites.js';
+export { runShip, renderShipMarkdown, renderShipText, shipReportJson, shipReportPath, parseShipHeader, readShipContracts, routescanBase, utcDate, SHIP_HEADER } from './ship.js';
+export { shipMain, parseShipArgs, SHIP_HELP } from './ship-cli.js';

package/dist/proc.d.ts

@@ -0,0 +1,14 @@
+export interface RunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** Set when the binary could not be started at all (ENOENT and friends). */
+    spawnError?: string;
+}
+export declare function run(cmd: string, args: readonly string[], opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    stdin?: string;
+}): Promise<RunResult>;
+export declare const ACCOUNT_NAME: RegExp;

package/dist/proc.js

@@ -0,0 +1,28 @@
+// One place that spawns processes. Arguments go as an array, never through a shell, so a
+// keystore name or a path cannot become a command.
+import { spawn } from 'node:child_process';
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { cwd: opts.cwd, env: opts.env ?? process.env, stdio: [opts.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            resolve(r);
+        };
+        const timer = opts.timeoutMs ? setTimeout(() => { child.kill('SIGKILL'); finish({ code: null, stdout, stderr: stderr + `\n${cmd} timed out after ${opts.timeoutMs}ms` }); }, opts.timeoutMs) : null;
+        child.stdout?.on('data', (d) => (stdout += d));
+        child.stderr?.on('data', (d) => (stderr += d));
+        child.on('error', (e) => { if (timer)
+            clearTimeout(timer); finish({ code: null, stdout, stderr, spawnError: e.message }); });
+        child.on('close', (code) => { if (timer)
+            clearTimeout(timer); finish({ code, stdout, stderr }); });
+        if (opts.stdin !== undefined && child.stdin) {
+            child.stdin.end(opts.stdin);
+        }
+    });
+}
+export const ACCOUNT_NAME = /^[A-Za-z0-9._-]{1,64}$/;

package/dist/redbelly.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function redbellyMain(argv?: readonly string[]): Promise<number>;

package/dist/redbelly.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// `redbelly <command>`: one bin for the checks a builder runs by hand. `preflight` is the seven
+// checks, `doctor` the machine, `gas` the report in RBNT and US cents, `ship` the mainnet gate that
+// writes its own report. Each is also its own bin (redbelly-preflight, redbelly-doctor) or an MCP tool.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { main as preflightMain } from './cli.js';
+import { doctorMain } from './doctor-cli.js';
+const HELP = `redbelly <command> [options]
+
+  preflight   the seven checks before a deploy (redbelly-preflight)
+  doctor      the machine before the first command (redbelly-doctor)
+  gas         gas per function in RBNT and US cents at the chain's base fee and feed price
+  ship        pre-flight, Slither, the five-state tests and the gas figures, written to deployments/ship-<chain>-<date>.md
+
+redbelly <command> --help for each. Nothing here takes a key; signing tools take a keystore name.
+`;
+const commands = {
+    preflight: preflightMain,
+    doctor: doctorMain,
+    gas: async (argv) => (await import('./gas-cli.js')).gasMain(argv),
+    ship: async (argv) => (await import('./ship-cli.js')).shipMain(argv),
+};
+export async function redbellyMain(argv = process.argv.slice(2)) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '--help' || cmd === '-h') {
+        process.stdout.write(HELP);
+        return cmd ? 0 : 2;
+    }
+    const fn = commands[cmd];
+    if (!fn) {
+        process.stderr.write(`unknown command "${cmd}"\n\n${HELP}`);
+        return 2;
+    }
+    return fn(rest);
+}
+/** 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)
+    redbellyMain().then((code) => { process.exitCode = code; }, (e) => { process.stderr.write(`${e.stack ?? e}\n`); process.exitCode = 2; });

package/dist/run.d.ts

@@ -0,0 +1,9 @@
+import type { CheckId, PreflightOptions, PreflightReport } from './types.js';
+export declare const VERSION: string;
+export declare const CHECK_IDS: readonly CheckId[];
+export declare const DEFAULT_GAS = 3000000n;
+export interface RunOptions extends PreflightOptions {
+    passwordFile?: string;
+}
+export declare function runPreflight(opts?: RunOptions): Promise<PreflightReport>;
+export declare function renderText(report: PreflightReport): string;

package/dist/run.js

@@ -0,0 +1,106 @@
+// Orchestration: pick the chain and RPC, resolve the deployer, run every check, build the
+// report. Nothing here signs, and the only network traffic is JSON-RPC to the chosen RPC.
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { chainById, toCaller } from '@gatedpath/chains';
+import { readProjectConfig } from './config.js';
+import { ENV_NAMES, readDotEnv } from './dotenv.js';
+import { checkAdminSafe } from './checks/admin.js';
+import { checkBalance } from './checks/balance.js';
+import { checkChainId } from './checks/chain-id.js';
+import { checkCompilerPins } from './checks/compiler.js';
+import { checkDeployerVerified, resolveDeployer } from './checks/deployer.js';
+import { checkGitSecrets } from './checks/git-secrets.js';
+import { checkSlitherReport } from './checks/slither.js';
+const require = createRequire(import.meta.url);
+export const VERSION = require('../package.json').version;
+export const CHECK_IDS = ['chain-id', 'deployer-verified', 'admin-safe', 'compiler-pins', 'git-secrets', 'balance', 'slither-report'];
+export const DEFAULT_GAS = 3000000n;
+export async function runPreflight(opts = {}) {
+    const env = opts.env ?? process.env;
+    const project = resolve(opts.project ?? process.cwd());
+    const config = readProjectConfig(project, opts.profile, env);
+    const skip = new Set(opts.skip ?? []);
+    // The scaffolder's .env names (DEPLOYER, ADMIN_SAFE, CHAIN_ID) fill in what the flags leave out.
+    const dotenv = readDotEnv(project, env);
+    const envChain = dotenv[ENV_NAMES.chain] !== undefined ? Number(dotenv[ENV_NAMES.chain]) : null;
+    // Chain and RPC. --chain wins, then the config's chain id, then CHAIN_ID, then whatever the RPC reports.
+    let expected = opts.chain ?? config.chainId ?? (envChain === 151 || envChain === 153 ? envChain : null);
+    let expectedSource = opts.chain ? '--chain' : config.chainId !== null ? (config.kind === 'hardhat' ? `${config.file} network ${config.profile}` : `${config.file}`) : `${ENV_NAMES.chain}`;
+    let rpc = opts.rpc ?? config.rpcUrl ?? pickRpcFromConfig(config.rpcEndpoints, expected) ?? defaultRpc(expected);
+    if (!opts.rpc && !config.rpcUrl && expected === null && Object.keys(config.rpcEndpoints).length === 0) {
+        // nothing said which chain; testnet is the safe default and the chain-id check will say so
+        expectedSource = 'nothing';
+    }
+    let reported = null;
+    try {
+        reported = Number(BigInt((await toCaller(rpc)('eth_chainId'))));
+    }
+    catch {
+        reported = null;
+    }
+    const network = reported === 151 ? 'mainnet' : reported === 153 ? 'testnet' : 'unknown';
+    const address = opts.address ?? (opts.account ? undefined : dotenv[ENV_NAMES.deployer]);
+    const deployer = await resolveDeployer({ account: opts.account, address, passwordFile: opts.passwordFile, cwd: project, env });
+    if (deployer.how === '--address' && !opts.address)
+        deployer.how = ENV_NAMES.deployer;
+    const admin = opts.admin ?? dotenv[ENV_NAMES.admin] ?? dotenv[ENV_NAMES.legacyAdmin] ?? null;
+    const gas = BigInt(opts.gas ?? DEFAULT_GAS);
+    const checks = [];
+    const push = async (id, fn) => {
+        if (skip.has(id))
+            checks.push({ id, status: 'skip', reason: 'Skipped on request.' });
+        else
+            checks.push(await fn());
+    };
+    await push('chain-id', () => checkChainId(expected, reported, expectedSource, rpc));
+    await push('deployer-verified', () => checkDeployerVerified(deployer.address, deployer.how, deployer.error, rpc, reported));
+    await push('admin-safe', () => checkAdminSafe(admin, rpc, reported));
+    await push('compiler-pins', () => checkCompilerPins(config));
+    await push('git-secrets', () => checkGitSecrets(project));
+    await push('balance', () => checkBalance(deployer.address, gas, rpc, reported));
+    await push('slither-report', () => checkSlitherReport(project, config.sourceDir, opts.slitherReport));
+    return {
+        tool: 'redbelly-preflight',
+        version: VERSION,
+        generatedAt: new Date().toISOString(),
+        project,
+        config: { kind: config.kind, file: config.file, profile: config.profile },
+        chain: { expected, reported, rpc, network },
+        deployer: deployer.address,
+        admin,
+        checks,
+        ok: checks.every((c) => c.status !== 'fail'),
+    };
+}
+function defaultRpc(chain) {
+    const c = chainById(chain === 151 ? 151 : 153);
+    if (!c)
+        throw new Error('chain definitions missing');
+    return c.rpcUrls.default.http[0];
+}
+function pickRpcFromConfig(endpoints, chain) {
+    const entries = Object.entries(endpoints);
+    if (entries.length === 0)
+        return null;
+    const want = chain === 151 ? /mainnet/i : chain === 153 ? /testnet/i : null;
+    if (want) {
+        const hit = entries.find(([name, url]) => want.test(name) || want.test(url));
+        if (hit)
+            return hit[1];
+    }
+    return entries.length === 1 ? entries[0][1] : null;
+}
+export function renderText(report) {
+    const lines = [];
+    lines.push(`redbelly-preflight ${report.version}  project ${report.project}`);
+    lines.push(`chain ${report.chain.reported ?? '?'} (${report.chain.network}) via ${report.chain.rpc}${report.deployer ? `  deployer ${report.deployer}` : ''}${report.admin ? `  admin ${report.admin}` : ''}`);
+    lines.push('');
+    for (const c of report.checks)
+        lines.push(`${c.status.padEnd(5)} ${c.id.padEnd(18)} ${c.reason}`);
+    lines.push('');
+    const fails = report.checks.filter((c) => c.status === 'fail').length;
+    const warns = report.checks.filter((c) => c.status === 'warn').length;
+    lines.push(report.ok ? `ok: no check failed${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}.` : `not ok: ${fails} check${fails === 1 ? '' : 's'} failed. Do not deploy.`);
+    return lines.join('\n') + '\n';
+}

package/dist/secrets.d.ts

@@ -0,0 +1,18 @@
+export type SecretKind = 'hex64' | 'hex64-keyword' | 'key-assignment' | 'mnemonic' | 'keystore-json';
+export interface SecretMatch {
+    readonly kind: SecretKind;
+    /** Why this counts. One sentence, no secret material. */
+    readonly why: string;
+}
+/** Every secret-shaped thing on one line of text. */
+export declare function scanLine(line: string): SecretMatch[];
+/** True when the line holds 12+ consecutive BIP-39 words separated by single spaces. */
+export declare function mnemonicRun(line: string): boolean;
+/** Scan a whole string; returns matches with 1-based line numbers. */
+export declare function scanText(text: string): Array<SecretMatch & {
+    line: number;
+}>;
+/** Walks any JSON-like value (tool arguments, config) and reports secret-shaped strings by path. */
+export declare function scanValue(value: unknown, path?: string): Array<SecretMatch & {
+    path: string;
+}>;

package/dist/secrets.js

@@ -0,0 +1,89 @@
+// Spots secret-shaped text. Used by the git-history check here and by the MCP server's
+// argument guard. It reports the kind of match and where, never the matched text.
+import { BIP39_ENGLISH } from './bip39-words.js';
+const HEX64 = /(?<![0-9a-fA-F])(0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
+/** A 0x-prefixed 64-hex string is usually a hash. It reads as a key when the line says so. */
+const KEY_WORDS = /\b(private[_ -]?key|privkey|secret|signer[_ -]?key|deployer[_ -]?key|wallet[_ -]?key|mnemonic|seed)\b/i;
+/** Lines that are plainly about hashes stay quiet even without the 0x prefix. */
+const HASH_WORDS = /"id"\s*:|\b(sha-?256|sha-?512|sha-?3|keccak|blake2?b?|integrity|checksum|digest|codehash|code hash|tx ?hash|transactionHash|blockHash|merkle|root)\b/i;
+const KEY_ASSIGNMENT = /\b(PRIVATE_KEY|PRIV_KEY|DEPLOYER_KEY|DEPLOYER_PRIVATE_KEY|WALLET_KEY|SIGNER_KEY|MNEMONIC|SEED_PHRASE|SEED)\b\s*[=:]\s*["'`]?([^\s"'`#]+(?:\s+[a-z]+)*)/;
+const PLACEHOLDER = /^(<|\$|\{\{|your|xxx+|\.\.\.|changeme|replace|example|0x0+$|todo|none|null|undefined|""|'')/i;
+const KEYSTORE = /"(ciphertext|kdfparams|mac)"\s*:/;
+/** Every secret-shaped thing on one line of text. */
+export function scanLine(line) {
+    const out = [];
+    if (line.length > 20_000)
+        return out; // minified bundles; a key there is not a key someone typed
+    for (const m of line.matchAll(HEX64)) {
+        const prefixed = m[1] === '0x';
+        if (prefixed) {
+            if (KEY_WORDS.test(line))
+                out.push({ kind: 'hex64-keyword', why: 'a 0x-prefixed 64-hex value on a line that talks about a key' });
+        }
+        else if (!HASH_WORDS.test(line)) {
+            out.push({ kind: 'hex64', why: 'a bare 64-hex value, the shape of a private key in a .env or keystore export' });
+        }
+    }
+    const assign = KEY_ASSIGNMENT.exec(line);
+    if (assign) {
+        const value = assign[2].trim();
+        const isMnemonicVar = /MNEMONIC|SEED/.test(assign[1]);
+        if (!PLACEHOLDER.test(value) && (isMnemonicVar ? value.split(/\s+/).length >= 3 : value.length >= 16)) {
+            out.push({ kind: 'key-assignment', why: `${assign[1]} is assigned a non-placeholder value` });
+        }
+    }
+    if (mnemonicRun(line))
+        out.push({ kind: 'mnemonic', why: 'twelve or more consecutive BIP-39 words' });
+    if (KEYSTORE.test(line))
+        out.push({ kind: 'keystore-json', why: 'an encrypted keystore JSON committed to the repository' });
+    return out;
+}
+/** True when the line holds 12+ consecutive BIP-39 words separated by single spaces. */
+export function mnemonicRun(line) {
+    const words = line.trim().split(/[\s"'`=,;:()[\]{}]+/);
+    let run = 0;
+    for (const w of words) {
+        if (w && BIP39_ENGLISH.has(w)) {
+            run++;
+            if (run >= 12)
+                return true;
+        }
+        else
+            run = 0;
+    }
+    return false;
+}
+/** Scan a whole string; returns matches with 1-based line numbers. */
+export function scanText(text) {
+    const out = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++)
+        for (const m of scanLine(lines[i]))
+            out.push({ ...m, line: i + 1 });
+    return out;
+}
+/** Walks any JSON-like value (tool arguments, config) and reports secret-shaped strings by path. */
+export function scanValue(value, path = '$') {
+    const out = [];
+    if (typeof value === 'string') {
+        for (const m of scanLine(value))
+            out.push({ ...m, path });
+        // a bare 64-hex string is a key even without context words; a 0x one alone is ambiguous but
+        // no tool here takes a hash, so treat it as a key too
+        if (/^(0x)?[0-9a-fA-F]{64}$/.test(value.trim()) && !out.some((m) => m.kind.startsWith('hex64'))) {
+            out.push({ kind: 'hex64', path, why: 'the whole value is 64 hex characters, the shape of a private key' });
+        }
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((v, i) => out.push(...scanValue(v, `${path}[${i}]`)));
+    }
+    else if (value && typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            if (/^(private_?key|privkey|mnemonic|seed(_phrase)?|secret|password)$/i.test(k)) {
+                out.push({ kind: 'key-assignment', path: `${path}.${k}`, why: `an argument named ${k}` });
+            }
+            out.push(...scanValue(v, `${path}.${k}`));
+        }
+    }
+    return out;
+}

package/dist/ship-cli.d.ts

@@ -0,0 +1,8 @@
+import type { ShipOptions } from './ship.js';
+export declare const SHIP_HELP = "redbelly ship --chain <151|153> --account <keystore-name> [options]\n\nRuns pre-flight (seven checks) with the keystore's address, checks the Slither sidecar, runs\nforge test and the five-state suites, prices the gas report at the chain's base fee and feed\nprice, reads the deployer and the admin (isAllowed, Safe 1.4.1, threshold, owners), and writes\ndeployments/ship-<chain>-<date>.md with every check and its result, the addresses, the\nconstructor arguments and the verify command. Refuses to write when any check fails. The\ndeploy script refuses to broadcast on 151 without a report dated today; 153 warns.\n\n  --chain <151|153>        required\n  --account <name>         required; Foundry keystore name, resolved with cast wallet address\n  --password-file <path>   passed through to cast (or set ETH_PASSWORD)\n  --admin <0x\u2026>            the Safe that receives every role (or ADMIN_SAFE in .env); required on 151\n  --gas <units>            deployment gas for the balance check (default: the gas report's deployment row)\n  --verifier <0x\u2026>         the dApp's verifier (or VERIFIER in .env); required on 151\n  --project <dir>          Foundry project or scaffold root (default: current directory)\n  --rpc <url>              JSON-RPC endpoint (default: the governors RPC for --chain; a fork works)\n  --out <path>             write the report here instead\n  --json                   print the report as JSON (the file is still written when checks pass)\n  --version, --help\n";
+export declare function parseShipArgs(argv: readonly string[]): (Partial<ShipOptions> & {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+});
+export declare function shipMain(argv?: readonly string[]): Promise<number>;