openzoo 0.50.99 → 0.51.0

package/transmute/lib/build.js

@@ -0,0 +1,311 @@
+// `build`: Vercel deployment model → Rust crate → .so, plus the cost sheet.
+//
+//   readDeployment(root) → transmute() → <out>/.zoo/{crate/, manifest.json,
+//   report.json, static-plan.json, build.json} → cargo build-sbf → .so
+//
+// The compiler (lib/compile/index.js) owns the JS→Rust translation; this
+// module owns the filesystem layout, the cargo invocation and the rent
+// estimate so `deploy` can pick the artifacts up without re-reading the
+// source repo.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readDeployment } from './vercel.js';
+import { ASSET_FIXED_HEADER, MANIFEST_PATH } from './wire.js';
+import { connect } from './solana.js';
+import { rpcUrl } from './wallet.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const RUNTIME_PATH = path.resolve(HERE, '..', 'runtime', 'zoo-host');
+export const SOLANA_BIN = path.join(os.homedir(), '.local', 'share', 'solana', 'install', 'active_release', 'bin');
+export const INSTALL_HINT = 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"';
+export const DEFAULT_ARCH = 'v0';
+export const ARCHES = ['v0', 'v1', 'v2', 'v3', 'v4'];
+/** Rent rule of thumb: 3480 lamports per byte-year × 2 years = 6960 lamports/byte ≈ 6.96 SOL/MB. */
+export const LAMPORTS_PER_BYTE = 6960;
+export const ACCOUNT_OVERHEAD_BYTES = 128;
+export const LAMPORTS_PER_SOL = 1_000_000_000;
+/** BPF upgradeable loader account sizes. */
+export const PROGRAM_ACCOUNT_BYTES = 36;
+export const PROGRAMDATA_HEADER_BYTES = 45;
+export const BUFFER_HEADER_BYTES = 37;
+
+// ---------------------------------------------------------------- naming
+
+/** A crate name Cargo accepts, derived from the project directory (or --name). */
+export function crateNameFor(root, name) {
+  const base = (name || path.basename(path.resolve(root)) || 'site').toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  const safe = /^[a-z]/.test(base) ? base : 'site-' + base;
+  return safe || 'site';
+}
+export function soNameFor(crateName) { return crateName.replace(/-/g, '_') + '.so'; }
+
+/** Parse `[package] name` out of a Cargo.toml (falls back to `fallback`). */
+export function packageNameOf(cargoToml, fallback) {
+  const m = String(cargoToml || '').match(/\[package\][^[]*?\bname\s*=\s*"([^"]+)"/);
+  return m ? m[1] : fallback;
+}
+
+// ---------------------------------------------------------------- cargo
+
+/** Process env with the Solana toolchain on PATH (`cargo build-sbf` lives there). */
+export function solanaEnv(extra = {}) {
+  const sep = path.delimiter;
+  const cur = process.env.PATH || '';
+  const parts = cur.split(sep);
+  const PATH = parts.includes(SOLANA_BIN) ? cur : [SOLANA_BIN, path.join(os.homedir(), '.cargo', 'bin'), cur].filter(Boolean).join(sep);
+  return { ...process.env, PATH, ...extra };
+}
+
+/** Absolute path of `cargo-build-sbf` on the given PATH, or null. */
+export function findCargoBuildSbf(env = solanaEnv()) {
+  const exe = process.platform === 'win32' ? 'cargo-build-sbf.exe' : 'cargo-build-sbf';
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const p = path.join(dir, exe);
+    try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * Run `cargo build-sbf --arch <arch>` in `crateDir`. Never throws for a
+ * missing toolchain: returns `{ok:false, missing:true}` with the install hint.
+ * @returns {Promise<{ok:boolean, missing?:boolean, soPath:string|null, arch:string, code?:number, output:string, error?:string}>}
+ */
+export async function runCargoBuildSbf(crateDir, { arch = DEFAULT_ARCH, outDir, log = console.log, env = solanaEnv(), cargo = 'cargo', extraArgs = [] } = {}) {
+  if (!ARCHES.includes(arch)) throw new Error(`unknown --arch ${arch} (expected one of ${ARCHES.join(', ')})`);
+  const sbfOut = outDir || path.join(crateDir, 'target', 'deploy');
+  if (!findCargoBuildSbf(env) && cargo === 'cargo') {
+    log(`cargo-build-sbf not found on PATH (looked in ${SOLANA_BIN}).`);
+    log(`install the Solana toolchain with:\n    ${INSTALL_HINT}\nthen re-run \`build\`; continuing without a .so.`);
+    return { ok: false, missing: true, soPath: null, arch, output: '', error: 'cargo-build-sbf not installed' };
+  }
+  const args = ['build-sbf', '--arch', arch, '--sbf-out-dir', sbfOut, ...extraArgs];
+  log(`$ ${cargo} ${args.join(' ')}   (in ${crateDir})`);
+  const t0 = Date.now();
+  const res = await new Promise((resolve) => {
+    let output = '';
+    let child;
+    try {
+      child = spawn(cargo, args, { cwd: crateDir, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) { return resolve({ code: -1, output: '', error: String(e?.message || e) }); }
+    const onData = (d) => { const s = d.toString(); output += s; for (const line of s.split('\n')) if (line.trim()) log('  ' + line.trimEnd()); };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.on('error', (e) => resolve({ code: -1, output, error: String(e?.message || e) }));
+    child.on('close', (code) => resolve({ code, output }));
+  });
+  if (res.error && /ENOENT/.test(res.error)) {
+    log(`\`${cargo}\` is not installed. Install the Solana toolchain with:\n    ${INSTALL_HINT}`);
+    return { ok: false, missing: true, soPath: null, arch, output: res.output, error: res.error };
+  }
+  if (res.code !== 0) return { ok: false, soPath: null, arch, code: res.code, output: res.output, error: res.error || `cargo build-sbf exited with ${res.code}` };
+  const soPath = findSo(sbfOut, res.output);
+  log(`built ${soPath ? path.relative(process.cwd(), soPath) : '(no .so found?)'} in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+  return { ok: !!soPath, soPath, arch, code: 0, output: res.output, error: soPath ? undefined : `no .so found in ${sbfOut}` };
+}
+
+function findSo(dir, output = '') {
+  const m = output.match(/\b(\/\S+\.so)\b/);
+  if (m && fs.existsSync(m[1])) return m[1];
+  if (!fs.existsSync(dir)) return null;
+  const sos = fs.readdirSync(dir).filter((f) => f.endsWith('.so')).map((f) => path.join(dir, f)).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  return sos[0] || null;
+}
+
+// ---------------------------------------------------------------- cost
+
+function accountBytesFor(kind, size, contentType = '') {
+  switch (kind) {
+    case 'asset': return ASSET_FIXED_HEADER + Buffer.byteLength(contentType.slice(0, 120)) + size;
+    case 'program': return PROGRAM_ACCOUNT_BYTES;
+    case 'programdata': return PROGRAMDATA_HEADER_BYTES + size;
+    case 'buffer': return BUFFER_HEADER_BYTES + size;
+    default: return size;
+  }
+}
+
+/** Reach the cluster within `timeoutMs`; null when unreachable. */
+export async function probeConnection(cluster, { timeoutMs = 2500 } = {}) {
+  let url;
+  try { url = rpcUrl(cluster); } catch { return null; }
+  const connection = connect(url);
+  try {
+    await Promise.race([connection.getSlot('confirmed'), new Promise((_, rej) => setTimeout(() => rej(new Error('timeout')), timeoutMs).unref?.())]);
+    return connection;
+  } catch { return null; }
+}
+
+/**
+ * Rent the deployment will lock. Uses the cluster's real rent parameters
+ * when a connection is given, else the 6.96 SOL/MB rule of thumb.
+ * @param {{staticFiles:Array<{path:string,size:number,contentType?:string}>, soSize?:number|null, manifestBytes?:number, connection?:object|null, upgrade?:boolean}} o
+ */
+export async function estimateCost({ staticFiles = [], soSize = null, manifestBytes = 0, connection = null, upgrade = false }) {
+  const items = [];
+  if (soSize != null) {
+    if (upgrade) items.push({ label: 'program upgrade buffer (refunded on success)', kind: 'buffer', bytes: accountBytesFor('buffer', soSize), transient: true });
+    else {
+      items.push({ label: 'program account', kind: 'program', bytes: accountBytesFor('program', 0) });
+      items.push({ label: `program data (2×.so = ${(soSize * 2).toLocaleString()} B)`, kind: 'programdata', bytes: accountBytesFor('programdata', soSize * 2) });
+    }
+  } else {
+    items.push({ label: 'program (no .so built yet)', kind: 'program', bytes: 0, unknown: true });
+  }
+  for (const f of staticFiles) items.push({ label: f.path, kind: 'asset', bytes: accountBytesFor('asset', f.size, f.contentType || '') });
+  items.push({ label: MANIFEST_PATH + ' (manifest)', kind: 'asset', bytes: accountBytesFor('asset', manifestBytes, 'application/json; charset=utf-8') });
+
+  let source = 'rule-of-thumb';
+  const rentFor = new Map();
+  if (connection) {
+    try {
+      const sizes = [...new Set(items.filter((i) => !i.unknown).map((i) => i.bytes))];
+      await Promise.all(sizes.map(async (n) => rentFor.set(n, await connection.getMinimumBalanceForRentExemption(n))));
+      source = 'rpc';
+    } catch { rentFor.clear(); }
+  }
+  let lamports = 0, transientLamports = 0;
+  for (const it of items) {
+    it.lamports = it.unknown ? 0 : (rentFor.get(it.bytes) ?? (ACCOUNT_OVERHEAD_BYTES + it.bytes) * LAMPORTS_PER_BYTE);
+    it.sol = it.lamports / LAMPORTS_PER_SOL;
+    if (it.transient) transientLamports += it.lamports; else lamports += it.lamports;
+  }
+  const feeLamports = 5000 * (1 + Math.ceil((soSize || 0) / 900) + staticFiles.reduce((n, f) => n + 1 + Math.ceil(f.size / 900), 0) + 2);
+  return {
+    source, rpc: connection?.rpcEndpoint || null, items,
+    lamports, sol: lamports / LAMPORTS_PER_SOL,
+    transientLamports, transientSol: transientLamports / LAMPORTS_PER_SOL,
+    feeLamports, feeSol: feeLamports / LAMPORTS_PER_SOL,
+    totalLamports: lamports + transientLamports + feeLamports,
+    totalSol: (lamports + transientLamports + feeLamports) / LAMPORTS_PER_SOL,
+    unknownProgram: soSize == null,
+  };
+}
+
+/** Render the cost estimate as a plain-text table. */
+export function formatCostTable(est, { maxRows = 40 } = {}) {
+  const rows = est.items.map((i) => [i.label, i.unknown ? '?' : i.bytes.toLocaleString(), i.unknown ? '?' : i.sol.toFixed(4)]);
+  const shown = rows.length > maxRows ? [...rows.slice(0, maxRows), [`… ${rows.length - maxRows} more files`, '', '']] : rows;
+  shown.push(['rent total', '', est.sol.toFixed(4)]);
+  if (est.transientLamports) shown.push(['+ transient (refunded)', '', est.transientSol.toFixed(4)]);
+  shown.push(['+ tx fees (approx.)', '', est.feeSol.toFixed(4)]);
+  shown.push(['TOTAL', '', est.totalSol.toFixed(4)]);
+  const w0 = Math.min(60, Math.max(...shown.map((r) => r[0].length), 4));
+  const w1 = Math.max(...shown.map((r) => r[1].length), 5);
+  const lines = [`  ${'item'.padEnd(w0)}  ${'bytes'.padStart(w1)}  ${'SOL'.padStart(8)}`];
+  for (const [a, b, c] of shown) lines.push(`  ${a.length > w0 ? a.slice(0, w0 - 1) + '…' : a.padEnd(w0)}  ${b.padStart(w1)}  ${c.padStart(8)}`);
+  lines.push(`  (rent per ${est.source === 'rpc' ? est.rpc.replace(/\?.*$/, '') : 'the 6.96 SOL/MB rule of thumb'}${est.unknownProgram ? '; program rent unknown until the .so is built' : ''})`);
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------- build
+
+async function loadTransmute() {
+  try {
+    const mod = await import('./compile/index.js');
+    if (typeof mod.transmute !== 'function') throw new Error('lib/compile/index.js does not export transmute()');
+    return mod.transmute;
+  } catch (e) {
+    if (e?.code === 'ERR_MODULE_NOT_FOUND' && /compile\/index\.js/.test(String(e.message))) {
+      throw new Error('the compiler (lib/compile/index.js) is not present in this install of openzoo-transmute');
+    }
+    throw e;
+  }
+}
+
+function writeJson(p, obj) { fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n'); }
+
+/** Point the generated Cargo.toml at a zoo-host checkout that exists on this machine. */
+export function fixRuntimePath(cargoToml, runtimePath) {
+  const rt = runtimePath.replace(/\\/g, '/');
+  const re = /(zoo-host\s*=\s*\{[^}]*?\bpath\s*=\s*")([^"]*)(")/;
+  const m = cargoToml.match(re);
+  if (!m) return cargoToml.includes('zoo-host') ? cargoToml : cargoToml + `\n[dependencies.zoo-host]\npath = "${rt}"\n`;
+  if (path.isAbsolute(m[2]) && fs.existsSync(path.join(m[2], 'Cargo.toml'))) return cargoToml;
+  return cargoToml.replace(re, `$1${rt}$3`);
+}
+
+/**
+ * Build a Vercel-shaped repo into `<out>/.zoo/`.
+ *
+ * @param {string} root         the app's directory
+ * @param {{out?:string, name?:string, arch?:string, cluster?:string, runtimePath?:string, skipCargo?:boolean,
+ *          transmute?:Function, log?:Function, cargo?:string, connection?:object|null}} opts
+ * @returns {Promise<{outDir:string, zooDir:string, crateDir:string, manifest:object, report:object, soPath:string|null, arch:string, costEstimate:object, deployment:object, notes:string[]}>}
+ */
+export async function build(root = '.', opts = {}) {
+  const log = opts.log ?? console.log;
+  root = path.resolve(root);
+  if (!fs.existsSync(root)) throw new Error(`${root}: no such directory`);
+  const outDir = path.resolve(opts.out || path.join(root, '.zoo-out'));
+  const zooDir = path.join(outDir, '.zoo');
+  const crateDir = path.join(zooDir, 'crate');
+  const notes = [];
+
+  const deployment = readDeployment(root);
+  const name = crateNameFor(root, opts.name);
+  const runtimePath = path.resolve(opts.runtimePath || RUNTIME_PATH);
+  log(`reading ${root} → ${deployment.source}${deployment.framework ? ` (${deployment.framework})` : ''}: ${deployment.functions.length} function(s), ${deployment.staticFiles.length} static file(s)`);
+  for (const n of deployment.notes) { log(`note: ${n}`); notes.push(n); }
+
+  const transmute = opts.transmute || await loadTransmute();
+  const result = await transmute(deployment, { name, runtimePath, arch: opts.arch, root, outDir });
+  if (!result || !result.crate || !result.crate['Cargo.toml'] || !result.crate['src/lib.rs']) throw new Error('transmute() returned no crate (expected {crate:{"Cargo.toml","src/lib.rs"}, manifest, report})');
+  const manifest = { name, ...(result.manifest || {}) };
+  if (!manifest.version) manifest.version = 1;
+  if (!manifest.framework) manifest.framework = deployment.framework;
+  if (!Array.isArray(manifest.routes)) manifest.routes = [];
+  if (!Array.isArray(manifest.static)) manifest.static = deployment.staticFiles.map((f) => ({ path: f.path, contentType: f.contentType, size: f.size }));
+  if (!manifest.config) manifest.config = deployment.config;
+  const report = { eligible: [], ineligible: [], warnings: [], ...(result.report || {}) };
+
+  // Lay the crate out.
+  fs.rmSync(crateDir, { recursive: true, force: true });
+  fs.mkdirSync(crateDir, { recursive: true });
+  for (const [rel, content] of Object.entries(result.crate)) {
+    const p = path.join(crateDir, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, rel === 'Cargo.toml' ? fixRuntimePath(String(content), runtimePath) : content);
+  }
+  const crateName = packageNameOf(result.crate['Cargo.toml'], name);
+  const byPath = new Map(deployment.staticFiles.map((f) => [f.path, f]));
+  const staticPlan = manifest.static.map((s) => ({ ...s, file: byPath.get(s.path)?.file || s.file || null }));
+  writeJson(path.join(zooDir, 'manifest.json'), manifest);
+  writeJson(path.join(zooDir, 'report.json'), report);
+  writeJson(path.join(zooDir, 'static-plan.json'), staticPlan);
+  log(`wrote ${path.relative(process.cwd(), zooDir) || zooDir}/{crate/, manifest.json, report.json, static-plan.json}`);
+  log(`functions: ${report.eligible.length} eligible, ${report.ineligible.length} ineligible${report.warnings.length ? `, ${report.warnings.length} warning(s)` : ''}`);
+  for (const i of report.ineligible) log(`  ✗ ${i.name}: ${i.reason}${i.file ? ` (${path.relative(root, i.file)}${i.line ? ':' + i.line : ''})` : ''}`);
+  for (const w of report.warnings) log(`  ! ${typeof w === 'string' ? w : w.message || JSON.stringify(w)}`);
+
+  // Compile.
+  let arch = opts.arch || DEFAULT_ARCH;
+  if (!opts.arch) { const n = `no --arch given: building for ${DEFAULT_ARCH} (mainnet); \`deploy\` re-detects the cluster's SBPF version and rebuilds if needed`; notes.push(n); log(`note: ${n}`); }
+  let soPath = null, cargo = null;
+  if (opts.skipCargo) { notes.push('cargo build skipped (--skip-cargo)'); log('skipping cargo build-sbf (--skip-cargo)'); }
+  else {
+    cargo = await runCargoBuildSbf(crateDir, { arch, outDir: path.join(zooDir, 'deploy'), log, cargo: opts.cargo, env: opts.env });
+    if (cargo.ok) soPath = cargo.soPath;
+    else if (cargo.missing) notes.push(`cargo-build-sbf not installed; install with: ${INSTALL_HINT}`);
+    else throw Object.assign(new Error(`cargo build-sbf failed (${cargo.error})\n${cargo.output.split('\n').filter((l) => /error/i.test(l)).slice(0, 20).join('\n')}`), { output: cargo.output });
+  }
+  const soSize = soPath ? fs.statSync(soPath).size : null;
+  writeJson(path.join(zooDir, 'build.json'), {
+    name, crateName, root, outDir, arch, soPath, soSize, soName: soNameFor(crateName), builtAt: new Date().toISOString(),
+    runtimePath, cargo: cargo ? { ok: cargo.ok, missing: !!cargo.missing } : { skipped: true },
+  });
+
+  // Cost sheet.
+  const connection = opts.connection !== undefined ? opts.connection : await probeConnection(opts.cluster || 'localnet');
+  const manifestBytes = Buffer.byteLength(JSON.stringify({ ...manifest, programId: 'x'.repeat(44), deployedAt: new Date().toISOString() }));
+  const costEstimate = await estimateCost({ staticFiles: staticPlan, soSize, manifestBytes, connection });
+  log('');
+  log(formatCostTable(costEstimate));
+  log('');
+  if (soPath) log(`.so: ${soPath} (${soSize.toLocaleString()} B, ${arch})`);
+  log(`next: openzoo-transmute deploy ${path.relative(process.cwd(), outDir) || outDir} --cluster <localnet|devnet|mainnet>`);
+  return { outDir, zooDir, crateDir, manifest, report, soPath, arch, costEstimate, deployment, notes, staticPlan };
+}

package/transmute/lib/cli.js

@@ -0,0 +1,231 @@
+// The openzoo-transmute command line.
+//
+// The openzoo package can mount these subcommands in its own bin without
+// duplicating anything:
+//
+//   case 'build': case 'deploy': case 'serve':
+//     await (await import('openzoo-transmute/lib/cli.js')).run(process.argv.slice(2));
+//
+// `run(argv)` resolves to the exit code (0 = ok) and also sets
+// `process.exitCode` when non-zero; it never calls `process.exit` itself so a
+// `serve` keeps the event loop (and the http server) alive.
+import fs from 'node:fs';
+import path from 'node:path';
+import { PublicKey } from '@solana/web3.js';
+import { readDeployment } from './vercel.js';
+import { build } from './build.js';
+import { deploy, resolveOutDir, clusterLabel } from './deploy.js';
+import { startGateway, DEFAULT_PORT } from './gateway.js';
+import { startHub, DEFAULT_HUB_PORT } from './hub.js';
+import { connect, getProgramInfo, readManifest } from './solana.js';
+import { loadWallet, rpcUrl } from './wallet.js';
+import { MANIFEST_PATH } from './wire.js';
+
+export const USAGE = `openzoo-transmute — Vercel app → Solana program + asset accounts
+
+usage:
+  openzoo-transmute build   [dir] [--out .zoo-out] [--name <crate>] [--arch v0|v3] [--cluster <c>] [--skip-cargo]
+  openzoo-transmute deploy  [dir|outDir] [--cluster mainnet|devnet|localnet|<url>] [--keypair <path>] [--yes] [--program <id>]
+                            [--concurrency 4] [--skip-assets] [--force]
+  openzoo-transmute serve   <programId> [--cluster <c>] [--port ${DEFAULT_PORT}] [--keypair <path>] [--host 127.0.0.1] [--quiet]
+  openzoo-transmute hub     [--cluster mainnet] [--port 8080] [--host 0.0.0.0] [--public-url <https://…>]
+                            hosted explorer for EVERY program on the cluster (/s/<programId>), read-only
+  openzoo-transmute inspect [dir]                 print the Vercel model + eligibility report
+  openzoo-transmute status  <programId> [--cluster <c>]
+  openzoo-transmute help
+
+clusters: mainnet (default, needs --yes to deploy), devnet, testnet, localnet, or an RPC URL.
+env: OPENZOO_CLUSTER, OPENZOO_RPC (mainnet RPC), OPENZOO_KEYPAIR / OPENZOO_WALLET (signer).
+`;
+
+/** `--k v`, `--k=v`, `--flag`, `--no-flag`; everything else is positional. */
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  const boolFlags = new Set(['yes', 'skip-cargo', 'skip-assets', 'force', 'quiet', 'help', 'json', 'version']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { positionals.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      let key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+      let val;
+      if (eq >= 0) val = a.slice(eq + 1);
+      else if (key.startsWith('no-')) { key = key.slice(3); val = false; }
+      else if (boolFlags.has(key) || i + 1 >= argv.length || argv[i + 1].startsWith('--')) val = true;
+      else val = argv[++i];
+      flags[key] = val;
+      flags[key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = val;
+    } else if (a === '-h') flags.help = true;
+    else if (a === '-y') flags.yes = true;
+    else positionals.push(a);
+  }
+  return { cmd: positionals[0] || 'help', positionals: positionals.slice(1), flags };
+}
+
+function fmtBytes(n) { return n == null ? '?' : n.toLocaleString() + ' B'; }
+
+export function inspectText(deployment, report = null) {
+  const lines = [];
+  lines.push(`${deployment.root}`);
+  lines.push(`source: ${deployment.source}${deployment.framework ? ` · framework: ${deployment.framework}` : ''} · static dir: ${deployment.staticDir ? path.relative(deployment.root, deployment.staticDir) || '.' : '-'}`);
+  for (const n of deployment.notes) lines.push(`note: ${n}`);
+  lines.push('');
+  lines.push(`functions (${deployment.functions.length}):`);
+  const inel = new Map((report?.ineligible || []).map((i) => [i.name, i]));
+  const elig = new Set((report?.eligible || []).map((e) => (typeof e === 'string' ? e : e.name)));
+  for (const f of deployment.functions) {
+    const mark = report ? (inel.has(f.name) ? '✗' : elig.has(f.name) ? '✓' : '?') : ' ';
+    const meth = f.methods ? f.methods.join(',') : 'any';
+    lines.push(`  ${mark} ${f.routePath.padEnd(32)} ${f.style.padEnd(12)} ${f.runtime.padEnd(11)} ${String(f.maxDuration + 's').padEnd(5)} ${String(f.memory + 'MB').padEnd(7)} ${meth}${f.params.length ? `  params=${f.params.join(',')}` : ''}${f.middleware ? '  middleware' : ''}${f.prerender ? '  ISR' : ''}`);
+    lines.push(`      ${f.sourceFile ? path.relative(deployment.root, f.sourceFile) : '(no source)'}${Object.keys(f.environment || {}).length ? `  env=${Object.keys(f.environment).join(',')}` : ''}`);
+    const r = inel.get(f.name);
+    if (r) lines.push(`      ineligible: ${r.reason}${r.line ? ` (line ${r.line})` : ''}`);
+  }
+  if (deployment.crons.length) { lines.push(''); lines.push(`crons (${deployment.crons.length}) — not transmuted, Solana has no scheduler:`); for (const c of deployment.crons) lines.push(`  ${c.schedule || '?'}  ${c.path || ''}`); }
+  lines.push('');
+  const total = deployment.staticFiles.reduce((n, f) => n + f.size, 0);
+  lines.push(`static files (${deployment.staticFiles.length}, ${fmtBytes(total)}):`);
+  for (const f of deployment.staticFiles.slice(0, 60)) lines.push(`  ${f.path.padEnd(48)} ${f.contentType.padEnd(32)} ${fmtBytes(f.size)}`);
+  if (deployment.staticFiles.length > 60) lines.push(`  … ${deployment.staticFiles.length - 60} more`);
+  if (report) {
+    lines.push('');
+    lines.push(`eligibility: ${report.eligible.length} eligible, ${report.ineligible.length} ineligible, ${report.warnings.length} warning(s)`);
+    for (const w of report.warnings) lines.push(`  ! ${typeof w === 'string' ? w : w.message || JSON.stringify(w)}`);
+  }
+  const routes = deployment.config?.routes || [];
+  if (routes.length) {
+    lines.push('');
+    lines.push(`routes (${routes.length}):`);
+    for (const r of routes) lines.push('  ' + (r.handle ? `[handle: ${r.handle}]` : `${r.src} → ${r.dest || (r.status ? `status ${r.status}` : '(headers)')}${r.continue ? ' (continue)' : ''}`));
+  }
+  return lines.join('\n');
+}
+
+async function tryTransmute(deployment) {
+  try {
+    const mod = await import('./compile/index.js');
+    if (typeof mod.transmute !== 'function') return null;
+    const r = await mod.transmute(deployment, { name: 'inspect', dryRun: true });
+    return r?.report || null;
+  } catch (e) {
+    if (e?.code === 'ERR_MODULE_NOT_FOUND') return null;
+    return { eligible: [], ineligible: [], warnings: [`compiler failed: ${e?.message || e}`] };
+  }
+}
+
+async function cmdBuild(p, f, log) {
+  const r = await build(p[0] || '.', { out: f.out, name: f.name, arch: f.arch, cluster: f.cluster, runtimePath: f.runtime, skipCargo: !!f.skipCargo, log });
+  if (f.json) log(JSON.stringify({ outDir: r.outDir, soPath: r.soPath, arch: r.arch, report: r.report, costEstimate: { sol: r.costEstimate.sol, totalSol: r.costEstimate.totalSol, source: r.costEstimate.source } }, null, 2));
+  return r.report.ineligible.length && !r.report.eligible.length && r.manifest.routes.length === 0 && r.deployment.functions.length ? 2 : 0;
+}
+
+async function cmdDeploy(p, f, log) {
+  const r = await deploy({ outDir: p[0] || '.', cluster: f.cluster, keypair: f.keypair, programId: f.program, yes: !!f.yes, concurrency: f.concurrency ? Number(f.concurrency) : undefined, skipAssets: !!f.skipAssets, force: !!f.force, log });
+  if (f.json) log(JSON.stringify(r, null, 2));
+  return 0;
+}
+
+async function cmdServe(p, f, log) {
+  let programId = p[0];
+  if (!programId) {
+    // Fall back to the last deploy in ./ or ./.zoo-out.
+    try { programId = JSON.parse(fs.readFileSync(path.join(resolveOutDir('.'), '.zoo', 'deploy.json'), 'utf8')).programId; } catch { /* none */ }
+    if (!programId) throw new Error('usage: serve <programId> (no .zoo/deploy.json found to infer it from)');
+  }
+  new PublicKey(programId); // validate
+  let keypair = null, walletPath = null;
+  if (f.keypair !== false) {
+    try { const w = loadWallet({ keypair: typeof f.keypair === 'string' ? f.keypair : undefined }); keypair = w.keypair; walletPath = w.path; }
+    catch (e) { if (typeof f.keypair === 'string') throw e; log(`no wallet found (${String(e.message).split(';')[0]}); mutating requests will answer 402`); }
+  }
+  const port = f.port != null ? Number(f.port) : DEFAULT_PORT;
+  const host = f.host || '127.0.0.1';
+  if (keypair && !/^(127\.0\.0\.1|localhost|::1|\[::1\])$/.test(host)) log(`warning: binding ${host} with a signer: anyone who can reach this gateway can send transactions paid by ${keypair.publicKey.toBase58()}; use --no-keypair unless that is intended`);
+  const gw = await startGateway({ programId, cluster: f.cluster, port, host, keypair, log, quiet: !!f.quiet });
+  const m = gw.state.manifest;
+  log(`openzoo-transmute gateway → ${gw.url}/  (explorer ${gw.url}/.zoo/, manifest ${gw.url}${MANIFEST_PATH})`);
+  log(`program ${programId} on ${gw.state.cluster} · ${m.routes.length} function(s), ${m.static ? m.static.length : '?'} asset(s) · signer ${keypair ? keypair.publicKey.toBase58() + (walletPath ? ` (${walletPath})` : '') : 'none (reads only)'}`);
+  for (const r of m.routes) log(`  ${(r.methods && r.methods.length ? r.methods.join('|') : 'ANY').padEnd(16)} ${r.routePath}`);
+  const stop = () => gw.close().then(() => process.exit(0));
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  return 0;
+}
+
+async function cmdInspect(p, f, log) {
+  const deployment = readDeployment(p[0] || '.');
+  const report = await tryTransmute(deployment);
+  if (f.json) log(JSON.stringify({ ...deployment, report }, null, 2));
+  else {
+    log(inspectText(deployment, report));
+    if (!report) log('\n(compiler not available: eligibility not checked)');
+  }
+  return 0;
+}
+
+async function cmdStatus(p, f, log) {
+  if (!p[0]) throw new Error('usage: status <programId> [--cluster <c>]');
+  const programId = new PublicKey(p[0]);
+  const rpc = rpcUrl(f.cluster);
+  const connection = connect(rpc);
+  const [info, slot, manifest] = await Promise.all([getProgramInfo(connection, programId), connection.getSlot('confirmed'), readManifest(connection, programId).catch(() => null)]);
+  const out = {
+    programId: programId.toBase58(), cluster: clusterLabel(f.cluster), rpc: rpc.replace(/\?.*$/, ''), slot,
+    exists: info.exists, executable: info.executable ?? null, authority: info.authority ? info.authority.toBase58() : null,
+    deploySlot: info.slot, maxDataLen: info.maxDataLen, programData: info.programData.toBase58(),
+    manifest: manifest ? { name: manifest.name, framework: manifest.framework, routes: manifest.routes?.length ?? 0, static: manifest.static?.length ?? 0, deployedAt: manifest.deployedAt, arch: manifest.arch } : null,
+  };
+  if (f.json) { log(JSON.stringify(out, null, 2)); return info.exists ? 0 : 1; }
+  log(`program     ${out.programId} on ${out.cluster} (${out.rpc}) @ slot ${slot}`);
+  if (!info.exists) { log('status      NOT DEPLOYED'); return 1; }
+  log(`status      deployed at slot ${out.deploySlot}${out.executable === false ? ' (not executable!)' : ''}`);
+  log(`authority   ${out.authority || 'none (immutable)'}`);
+  log(`programData ${out.programData} (max ${out.maxDataLen?.toLocaleString()} B)`);
+  if (manifest) {
+    log(`manifest    ${manifest.name || ''} ${manifest.framework || ''} · ${out.manifest.routes} function(s), ${out.manifest.static} asset(s) · deployed ${manifest.deployedAt || '?'}${manifest.arch ? ` (${manifest.arch})` : ''}`);
+    for (const r of manifest.routes || []) log(`  ${(r.methods && r.methods.length ? r.methods.join('|') : 'ANY').padEnd(16)} ${r.routePath}`);
+  } else log(`manifest    none at ${MANIFEST_PATH}`);
+  return 0;
+}
+
+/**
+ * Run the CLI. Returns the exit code; prints errors to stderr.
+ * @param {string[]} argv  arguments after the program name
+ * @param {{log?:Function, error?:Function}} io
+ */
+async function cmdHub(p, f, log) {
+  // The hosted explorer: every program on the cluster from one public host,
+  // read-only by default (a public signer would be a drain). --keypair opts in.
+  const cluster = f.cluster || process.env.OPENZOO_CLUSTER || 'mainnet';
+  let keypair = null;
+  if (typeof f.keypair === 'string') { keypair = loadWallet({ keypair: f.keypair }).keypair; log(`warning: this hub signs writes with ${keypair.publicKey.toBase58()} for anyone who can reach it`); }
+  const port = f.port != null ? Number(f.port) : Number(process.env.PORT || DEFAULT_HUB_PORT);
+  const h = await startHub({ cluster, port, host: f.host || '0.0.0.0', keypair, log, quiet: !!f.quiet, publicUrl: f.publicUrl || process.env.OPENZOO_HUB_URL || null, maxSites: f.maxSites ? Number(f.maxSites) : undefined });
+  log(`openzoo hub → ${h.url}/.hub  (cluster ${cluster}; sites at ${h.url}/s/<programId>)`);
+  const stop = () => h.close().then(() => process.exit(0));
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  return 0;
+}
+
+export async function run(argv = process.argv.slice(2), io = {}) {
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const { cmd, positionals, flags } = parseArgs(argv);
+  if (flags.version) { log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return 0; }
+  if (flags.help || cmd === 'help' || cmd === '--help') { log(USAGE); return 0; }
+  const commands = { build: cmdBuild, deploy: cmdDeploy, serve: cmdServe, inspect: cmdInspect, status: cmdStatus, hub: cmdHub };
+  const fn = commands[cmd];
+  if (!fn) { error(`unknown command: ${cmd}\n`); error(USAGE); process.exitCode = 1; return 1; }
+  try {
+    const code = (await fn(positionals, flags, log)) || 0;
+    if (code) process.exitCode = code;
+    return code;
+  } catch (e) {
+    error(`error: ${e?.message || e}`);
+    if (process.env.OPENZOO_DEBUG && e?.stack) error(e.stack);
+    process.exitCode = 1;
+    return 1;
+  }
+}