@artblocks/abx-cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/commands/reads.js

@@ -0,0 +1,635 @@
+/**
+ * Read-only commands: `preview` (the studio lane — no chain), `inspect` (static analysis of a
+ * generative script + lane recommendation), `render` (effect-runner repair lane), `tokenuri` /
+ * `contracturi` (read directly from the contract, decode, optionally follow + report what's
+ * served), and `tokens` (every token's owner/seed/params, from chain alone).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, resolve as resolvePath } from 'node:path';
+import { SqliteStore } from '@artblocks/abx-indexer';
+import { analyzeScript, listTokens, makePublicClient, oneOfOneImageAbi, recommendLane, redactRpcUrl, resolveRpcUrl, } from '@artblocks/abx-sdk';
+import { resolveBackend } from '@artblocks/abx-storage';
+import { resolveBaseUrl } from '@artblocks/abx-token-api';
+import { CHAIN, storageOptions, storageOverrides } from '../config.js';
+import { positionalArgs, warnStrayFlags } from '../flags.js';
+import { assertPortFree, bold, c, dim, g, info, loadEffects, ok, requirePublishableBackend, step, warn } from '../output.js';
+import { DEFAULT_PREVIEW_PORT, PREVIEW_FLAGS, parsePreviewParams, previewConfigFromFlags, previewDepTags, shootPreview, startPreviewServer, } from '../preview.js';
+import { remoteFlag, requireRemoteToken } from '../remote.js';
+import { SCHEMA_CATALOG, describeSchema } from '../schema.js';
+import { decodeOnChainJson, fetchServedTokenUri, prettyBody, servedOk } from '../served.js';
+/**
+ * `abx preview` — serve the program on localhost, live, for as long as the work is being made.
+ *
+ * The studio lane, and deliberately the FIRST thing to reach for on a code project: it renders the
+ * same document the generator serves (real `abx.js`, real tokenData shape, real dependency tags)
+ * with a synthetic seed, so a creator can refresh for new seeds, drive their PostParams from real
+ * inputs, and watch an animated piece actually move — none of which a still-image sweep can show.
+ * No chain, no key, no deploy. `--shoot` renders the same document headlessly for an agent that
+ * can't open a browser.
+ */
+export async function cmdPreview(flags) {
+    warnStrayFlags(flags, PREVIEW_FLAGS, 'preview');
+    const cfg = previewConfigFromFlags(flags);
+    const shootDir = flags.shoot && flags.shoot !== 'true' ? String(flags.shoot) : flags.shoot === 'true' ? 'abx-preview' : undefined;
+    const count = Math.min(Math.max(Number(flags.count ?? 9) || 9, 1), 64);
+    console.log(bold(`\n  ABX Self-Host Toolkit — preview\n  ${dim('the program, running locally — no chain, no deploy')}`));
+    const { notes } = previewDepTags(cfg.deps);
+    step('Program');
+    info(cfg.source.kind === 'dir' ? `directory build ${cfg.source.path}/ (its own index.html + abx.js)` : `script ${cfg.source.path} ${dim('(re-read from disk on every render)')}`);
+    if (cfg.schemas.length)
+        info(`params: ${cfg.schemas.map(describeSchema).join(' · ')}`);
+    else
+        info(dim('params: none declared — add --schema key:Type:Auth to drive them from the studio'));
+    for (const n of notes)
+        info(`dep ${n}`);
+    // A raw on-chain dependency can't be fetched without a chain, so the preview would render a
+    // sketch missing its runtime and look broken for the wrong reason. Say so rather than let them
+    // debug their own art.
+    if (cfg.deps.some((d) => d.display.startsWith('0x'))) {
+        warn('an on-chain data-contract dep is NOT loaded in preview — the sketch will run without it here. Use a name@version ref to preview against the CDN copy.');
+    }
+    // `--shoot` takes an ephemeral port (0), so only the studio lane can collide.
+    const previewPort = shootDir ? 0 : Number(flags.port ?? DEFAULT_PREVIEW_PORT);
+    if (previewPort !== 0)
+        await assertPortFree(previewPort, 'preview');
+    const server = await startPreviewServer(cfg, previewPort);
+    if (shootDir) {
+        step(`Render ${count} seeds headlessly`);
+        try {
+            const shotParams = parsePreviewParams(flags.param);
+            if (Object.keys(shotParams).length) {
+                info(`param overrides applied to every frame: ${Object.entries(shotParams).map(([k, v]) => `${k}=${v || dim('(unset)')}`).join(' · ')}`);
+            }
+            const shots = await shootPreview(server.url, shootDir, count, {
+                width: Number(flags.width ?? 1000) || 1000,
+                timeoutMs: Number(flags['timeout-ms'] ?? 10_000) || 10_000,
+                params: shotParams,
+            });
+            ok(`${shots.length} frames → ${shootDir}/  ${dim('(traits in traits.json)')}`);
+            for (const s of shots) {
+                const t = s.traits && Object.keys(s.traits).length
+                    ? Object.entries(s.traits).map(([k, v]) => `${k} ${String(v)}`).join(' · ')
+                    : s.timedOut
+                        ? `${c.orange}timed out — traits unknown${c.reset}`
+                        : `${c.orange}no traits reported${c.reset}`;
+                console.log(`      ${dim(s.seed.slice(0, 10) + '…')}  ${t}${s.done || s.timedOut ? '' : dim('  (no abx.done())')}`);
+            }
+            const timedOut = shots.filter((s) => s.timedOut).length;
+            const silent = shots.filter((s) => !s.traits || !Object.keys(s.traits).length).length;
+            // A timeout is a measurement failure, not a finding about the program — so it must never be
+            // reported as one. The old code printed the "NO frame reported traits" alarm whenever traits
+            // came back empty for any reason, which condemned a CORRECT program on a loaded machine and
+            // inverted the one line agents are told to trust.
+            if (timedOut) {
+                warn(`${timedOut} of ${shots.length} frame(s) hit the ${Math.round((Number(flags['timeout-ms'] ?? 10_000) || 10_000) / 1000)}s wait with nothing reported — ` +
+                    `that is a TIMEOUT, not a verdict on the program. Re-run with ${bold('--timeout-ms 30000')} (or on an idle machine) before believing anything about its traits.`);
+            }
+            if (silent === shots.length && !timedOut) {
+                warn('NO frame reported traits — `abx.traits({…})` is the only thing that becomes marketplace `attributes`. Verify with `abx inspect`.');
+            }
+            else if (silent < shots.length && shots.length > 1 && new Set(shots.map((s) => JSON.stringify(s.traits))).size === 1) {
+                // Only meaningful when traits DID come back: identical values across seeds is the signature
+                // of a sketch that never reads `abx.tokenData.seed` (prototyped on Math.random()), which
+                // deploys as N visually identical tokens. Skipped when nothing reported at all — the
+                // warning above already covers that, and firing both reads as noise.
+                warn('every seed produced identical traits — check the sketch actually reads `abx.tokenData.seed` (the silent "all tokens the same" failure).');
+            }
+        }
+        finally {
+            await server.close();
+        }
+        return;
+    }
+    step('Studio');
+    console.log(`\n  ${g('●')} ${bold('preview')}  ${server.url}`);
+    console.log(`    ${dim('studio     ')}${server.url}          ${dim('seed + params + live traits')}`);
+    console.log(`    ${dim('grid       ')}${server.url}/grid     ${dim('9 seeds at once, all live')}`);
+    console.log(`    ${dim('bare view  ')}${server.url}/view     ${dim('the generator document itself')}`);
+    console.log(`\n  ${dim('Edit the program and refresh — it is re-read from disk. Ctrl-C to stop.')}`);
+    console.log(`  ${dim('This is a preview: `abx inspect` is still the wiring check, and a testnet deploy is the faithful end-to-end.')}\n`);
+    await new Promise(() => { }); // block like `serve` — the creator drives it
+}
+/**
+ * `abx inspect <script.js>` — read a generative script and, WITHOUT executing it, report what it
+ * needs (traits + their on-chain reproducibility, dependency hints, size → assembled-document size →
+ * single-`tokenURI`-eth_call viability) and RECOMMEND a lane. The decision-tree entry point: run it
+ * before choosing `--onchain-uri` vs a resolver vs directory mode, so the choice is derived, not guessed.
+ */
+export async function cmdInspect(path, flags) {
+    if (!path || path.startsWith('--')) {
+        console.error('usage: abx inspect <script.js> [--dep <name@version>[,…]]   (static analysis + a lane recommendation — abx inspect --help)\n');
+        process.exitCode = 1;
+        return;
+    }
+    // `abx inspect` analyzes a JS generative SCRIPT. A creator on the in-chain Solidity lane naturally
+    // tries `abx inspect <renderer address>` — redirect them instead of crashing with a raw ENOENT.
+    if (/^0x[0-9a-fA-F]{40}$/.test(path)) {
+        console.error(`abx inspect analyzes a JS generative SCRIPT file, not an address. For a Solidity renderer (an in-chain SVG/traits contract) there's nothing to statically analyze here — deploy it, then pass its address to ${bold('abx deploy-code --image-renderer 0x..')} / ${bold('--attributes-renderer 0x..')} (deploy-code verifies the address has code).\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const abs = resolvePath(path);
+    if (!existsSync(abs)) {
+        console.error(`abx inspect: no such file '${path}'. It takes a JS generative script (e.g. sketch.js). For a Solidity renderer, pass its DEPLOYED address to ${bold('abx deploy-code --image-renderer/--attributes-renderer')} instead.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const source = readFileSync(abs, 'utf8');
+    const declaredDeps = String(flags.dep ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const a = analyzeScript(source, declaredDeps);
+    console.log(bold(`\n  abx inspect — ${basename(path)}  ${dim('(static analysis; the script is never executed)')}`));
+    step('Program');
+    info(`size: ${a.bytes} bytes → ${a.estChunks} on-chain chunk(s)`);
+    info(`libraries: ${a.depHints.length
+        ? a.depHints.join(', ') + (declaredDeps.length ? '' : dim(' — declare on-chain with --dep <name@version>'))
+        : 'none detected'}`);
+    step('Runtime data contract');
+    if (a.runtime.readsTokenData) {
+        ok(`reads state via ${bold('abx.tokenData')}${a.runtime.reportsTraits ? ` and reports traits via ${bold('abx.traits({…})')}` : ''} — the recognized accessor(s).`);
+        if (!a.runtime.reportsTraits)
+            info(`no ${bold('abx.traits({…})')} call — fine if this piece has no marketplace traits; add one if you want filterable traits (see below).`);
+    }
+    else {
+        // The silent-breaker: a fresh sketch that invents its own global deploys + renders without error
+        // but never receives the seed/params. This is the #1 authoring trap the skill's contract prevents.
+        warn(`this script never reads the abx token data via a recognized accessor (${bold('abx.tokenData')} or ${bold('window.abxTokenData')}).`);
+        if (a.runtime.wrongGlobal)
+            warn(`  found instead: ${bold(a.runtime.wrongGlobal)}.`);
+        info(`the mint ${bold('seed')} and collector ${bold('params')} will NOT reach it → every token renders IDENTICALLY, and traits stay empty. Read state the one supported way: ${bold('var td = (window.abx && abx.tokenData) || {}')} then ${bold('td.seed')} / ${bold('td.<paramKey>')} (flat), report with ${bold('abx.traits({…})')}. Contract + a worked example: the skill's "Authoring the program" section.`);
+    }
+    step('Traits');
+    if (a.traits.present) {
+        info(`reports ${a.traits.keys.length}: ${a.traits.keys.join(', ')}`);
+        const line = `on-chain reproducibility: ${bold(a.feasibility.verdict)} — ${a.feasibility.reason}`;
+        if (a.feasibility.verdict === 'exact-likely')
+            ok(line);
+        else if (a.feasibility.verdict === 'infeasible')
+            warn(line);
+        else
+            info(line);
+    }
+    else {
+        warn(a.feasibility.reason);
+    }
+    step('PostParams (collector-set inputs)');
+    if (a.paramHints.length) {
+        warn(`the script READS ${a.paramHints.length} param(s): ${bold(a.paramHints.join(', '))}`);
+        info(`declare EACH at deploy or it's silently dropped (render sees undefined → its default): ${bold(`--schema ${a.paramHints.map((k) => `${k}:<Type>:<Auth>`).join(',')}`)} ${dim(SCHEMA_CATALOG)}`);
+    }
+    else {
+        // "none detected" is a HINT, not proof — the scan only sees params read as `abx.tokenData.<key>`
+        // (flat) or destructured from it. A creator who reads them a different way (a nested `.params`,
+        // an invented global) gets a false "none" and drops the --schema. Say so, don't reassure.
+        info(`none detected reading ${bold('abx.tokenData.<key>')} (flat) or destructuring from it. If you INTENDED a collector param (e.g. a palette) but see this, you're likely reading it a different way — read it as ${bold('abx.tokenData.<key>')} and re-run, or declare it explicitly with ${bold('--schema')} or it's dropped at render.`);
+    }
+    step('On-chain document — RPC viability');
+    info(`estimated assembled document: ~${Math.round(a.doc.estBytes / 1000)}KB` +
+        `${a.doc.unknownDepSizes ? ' + undeclared/unknown dep bytes' : ''} ` +
+        dim(`(script + runtime${a.doc.deps.length ? ' + ' + a.doc.deps.join('+') : ''})`));
+    if (a.doc.fitsSingleCall)
+        ok('fits a single tokenURI eth_call — the template (fully-on-chain) branch is viable.');
+    else
+        warn('may exceed a single tokenURI eth_call — prefer directory mode, a CDN dep, or the generator piecewise getters.');
+    step('Recommended lane');
+    console.log(`  ${bold(recommendLane(a))}`);
+    console.log(`  ${dim('trait feasibility deep-dive: docs/research/onchain-traits-feasibility.md · all lanes: abx deploy-code --help')}\n`);
+}
+/**
+ * `abx render <address> [tokenId…]` — the ops/repair lane of the effect runner
+ * (`specs/protocol/effects.md → The reference runner`). Same code path as the deployed
+ * service, so a hand-fix and the daemon can't diverge: with a runner up
+ * (ABX_EFFECTS_URL / --effects-url) this enqueues via its `POST /run`; otherwise it
+ * runs the sweep inline (which needs Playwright installed locally — the error says how).
+ * Idempotent either way: only missing artifacts at the CURRENT inputsHash render.
+ */
+export async function cmdRender(address, tokenIds, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx render <address> [tokenId…] [--force] [--remote [name|url]]   (missing stills/traits; --force re-renders an existing one — abx render --help)\n');
+        process.exitCode = 1;
+        return;
+    }
+    // Token ids are decimal (mint order). Keep only those — `parseFlags` leaves `--flag value` pairs
+    // in `rest`, so a flag's VALUE (e.g. the `--remote <url>`) would otherwise be read as a bogus id
+    // and make the sweep match nothing (a silent `ran=0`).
+    const ids = tokenIds.filter((t) => /^\d+$/.test(t));
+    // --force re-renders even when the still already exists at the current inputsHash — the repair
+    // lane for a bad/blank/timed-out capture (the art is otherwise deterministic, so a plain render
+    // idempotent-skips). Overwrites the artifact (and republishes it on --remote).
+    const force = !!flags.force;
+    const runnerUrl = flags['effects-url'] ?? process.env.ABX_EFFECTS_URL;
+    if (runnerUrl) {
+        let res;
+        try {
+            res = await fetch(`${runnerUrl.replace(/\/$/, '')}/run`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ address, tokenIds: ids.length ? ids : undefined, force }),
+            });
+        }
+        catch (err) {
+            // A bare "fetch failed" (ECONNREFUSED) here means nothing is LISTENING at the configured
+            // effects URL — name it and give the two ways out, rather than a contentless error.
+            throw new Error(`no effect runner reachable at ${runnerUrl} (${err.message}). ` +
+                `Start one there with \`abx effects\`, or unset ABX_EFFECTS_URL (and drop --effects-url) to render inline on this machine.`);
+        }
+        if (!res.ok)
+            throw new Error(`effect runner at ${runnerUrl} replied ${res.status} ${(await res.text().catch(() => '')).slice(0, 200)}`);
+        const stats = (await res.json());
+        const line = `runner: ran=${stats.ran} skipped=${stats.skipped} failed=${stats.failed} ${dim(`(${runnerUrl})`)}`;
+        if (stats.failed)
+            warn(`${line}\n  ${dim(stats.errors?.[0] ?? 'see runner logs')}`);
+        else
+            ok(line);
+        return;
+    }
+    // --remote publishes each render to the remote resolver's control plane (the locator bridge) so a
+    // laptop render lands on a resolver that doesn't share this disk; republish=true makes a re-run
+    // restore a resolver that lost its volume without re-rendering. Local (no --remote): shared backend.
+    const remote = remoteFlag(flags);
+    const resolverUrl = (remote?.url ?? process.env.ABX_RESOLVER_URL ?? resolveBaseUrl()).replace(/\/$/, '');
+    const adminToken = remote ? requireRemoteToken(remote) : undefined;
+    // Refuse the combination that can't work before launching Chromium (a laptop render against a
+    // hosted resolver, on a backend with no public URL) — the render would end in a 400 either way.
+    if (remote)
+        requirePublishableBackend(flags, 'abx render --remote');
+    // Co-located (no --remote): record each declared output into the shared store's artifact
+    // registry so the local resolver's `artifacts` manifest enumerates it. Remote: the publish
+    // lane (adminToken) records rows on the hosted resolver instead.
+    const localStore = remote ? null : new SqliteStore();
+    const { EffectRunner, renderEffect } = await loadEffects();
+    const runner = new EffectRunner({
+        resolverUrl,
+        client: makePublicClient({ chainKey: CHAIN }),
+        storage: resolveBackend(storageOptions(storageOverrides(flags))),
+        effects: [renderEffect()],
+        environmentId: process.env.ABX_ENVIRONMENT_ID ?? 'web:any',
+        adminToken,
+        republish: remote ? true : undefined,
+        recordArtifact: localStore ? (row) => localStore.putEffectArtifact(row) : undefined,
+    });
+    const stats = await runner.sweepProject(address, ids.length ? ids : undefined, { force });
+    const where = remote ? `published → ${resolverUrl}` : `resolver ${resolverUrl}`;
+    const forceNote = force ? ' (forced re-render)' : '';
+    const summary = `inline: ran=${stats.ran} skipped=${stats.skipped} failed=${stats.failed}${forceNote} ${dim(`(${where})`)}`;
+    if (stats.failed)
+        warn(`${summary}\n  ${dim(stats.errors[0] ?? 'see error above')}`);
+    else
+        ok(summary);
+    if (stats.ran)
+        noteArweavePropagation(flags);
+}
+/**
+ * After an Arweave publish, say that a fresh 404 at the gateway is PROPAGATION, not a failed render.
+ *
+ * `arweave.net` lags Turbo uploads by minutes: a tester found 32/32 of their renders 404ing there
+ * while Turbo reported CONFIRMED and 22/32 already served fine from other ar.io gateways. The bytes
+ * were never in doubt — only the gateway was behind. Unexplained, a "broken" thumbnail on a fresh
+ * drop reads as a failed render, and the natural next move is `abx render --force` on all of them:
+ * a full re-upload that fixes nothing.
+ *
+ * Note this is advisory only, and deliberately so — the locator is baked into what the resolver
+ * registers at publish time, so it cannot be repaired by a redirect later. Choosing the gateway is
+ * the operator's call (`ABX_ARWEAVE_GATEWAY`), which is why this names it.
+ */
+export function noteArweavePropagation(flags) {
+    const opts = storageOptions(storageOverrides(flags));
+    if (resolveBackend(opts).id !== 'arweave')
+        return;
+    const gateway = opts.arweave?.gateway ?? 'https://arweave.net';
+    if (!/(^|\/\/)([^/]*\.)?arweave\.net/.test(gateway))
+        return; // a gateway they chose — don't lecture
+    info(`${dim('arweave: the locator points at')} ${gateway}${dim(', which can 404 for several minutes after upload while it catches up. That is PROPAGATION, not a failed render — the bytes are already confirmed. Do NOT re-run with')} ${bold('--force')}${dim('; the URL starts working on its own.')}`);
+    info(`  ${dim('to bake a different gateway into the locator instead (it is fixed at publish time):')} ${bold('ABX_ARWEAVE_GATEWAY=https://<gateway>')} ${dim('before you render.')}`);
+    // The note is advisory; this is the answer. Naming it here is the difference between "wait and
+    // hope" and a check a script can gate on — which is what both reporters ended up building.
+    info(`  ${dim('to KNOW rather than wait:')} ${bold('abx storage status <locator>')} ${dim('— ready vs propagating vs unreachable, exits non-zero until it serves.')}`);
+}
+export async function cmdTokenUri(address, flags, extra = []) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx tokenuri <address> [--token <id>] [--fetch] [--json]\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        console.error(`abx tokenuri: '${address}' isn't a 0x contract address.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // `abx tokenuri <addr> 0` silently ignored the `0` and printed token 0 — a COINCIDENTALLY correct
+    // answer, which is the dangerous kind: `… <addr> 7` would have printed token 0 just as confidently
+    // and exited 0. The token id is a flag here, so name it rather than guessing at intent.
+    const strayPositionals = positionalArgs(extra);
+    if (strayPositionals.length) {
+        const first = strayPositionals[0];
+        const looksLikeTokenId = /^\d+$/.test(first);
+        console.error(`abx tokenuri: unexpected extra argument '${first}'.` +
+            (looksLikeTokenId
+                ? ` The token id is a flag — did you mean:\n    abx tokenuri ${address} --token ${first}\n`
+                : `\n  usage: abx tokenuri <address> [--token <id>] [--fetch] [--json]\n`));
+        process.exitCode = 1;
+        return;
+    }
+    const tokenId = BigInt(flags.token ?? '0');
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    // A creator verifying their work often runs this on a wrong / not-yet-mined address — turn viem's
+    // raw revert (with its viem.sh docs link) into a black-box-clean, actionable message.
+    let uri;
+    try {
+        uri = (await publicClient.readContract({
+            address,
+            abi: oneOfOneImageAbi,
+            functionName: 'tokenURI',
+            args: [tokenId],
+        }));
+    }
+    catch {
+        const code = await publicClient.getCode({ address }).catch(() => undefined);
+        if (!code || code === '0x') {
+            // Name the endpoint we actually asked. "No contract here" is indistinguishable from "you're
+            // pointed at the wrong node", and a chain KEY doesn't disambiguate that — two endpoints can
+            // both claim `sepolia` (a fork, a stale duplicate .env line) and only one has your contract.
+            console.error(`abx tokenuri: no contract at ${address} on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}) — ` +
+                `double-check the address, and that this endpoint is the network you deployed to. ` +
+                `If you JUST deployed, give the tx a block or two to mine.\n`);
+        }
+        else {
+            console.error(`abx tokenuri: ${address} didn't return a tokenURI for token ${tokenId} — it may not be an ABX/ERC-721 token, token ${tokenId} may be unminted (try --token <id>), or — on a large on-chain tokenURI — an unauthenticated RPC read hit its gas cap (try a wallet-connected / high-gas RPC).\n`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // --fetch: FOLLOW the URL the contract commits to and print what is actually served (backlog B14).
+    // The gap this closes: `tokenuri` read the chain, `verify` re-hashed bytes, `status` reported the
+    // lifecycle — none of them showed the served JSON body, so an agent in a cold sweep fell back to raw
+    // `curl`. It also makes a provider mismatch self-evident without a warning that cries wolf: if you
+    // registered with one provider while a different base is baked on-chain, the fetch shows you what
+    // the BAKED base returns (often a 404, or another project's document entirely).
+    const served = flags.fetch !== undefined ? await fetchServedTokenUri(uri) : null;
+    // --json: the verbatim document, nothing else on stdout — no banner, no ANSI, no truncation, so
+    // `abx tokenuri <addr> --json | jq` is a supported read path rather than something to regex.
+    if (flags.json !== undefined) {
+        const onChain = decodeOnChainJson(uri, true);
+        if (served === null) {
+            process.stdout.write((onChain ?? uri) + '\n');
+            return;
+        }
+        // With --fetch the payload has to say WHICH answer is which: a marketplace reads the served body,
+        // and conflating it with the on-chain URI is the confusion the flag exists to remove.
+        process.stdout.write(JSON.stringify({
+            tokenId: tokenId.toString(),
+            contract: address,
+            chain: CHAIN,
+            tokenURI: uri,
+            onChain: onChain !== null,
+            served,
+        }, null, 2) + '\n');
+        if (served.status !== null && (served.status < 200 || served.status >= 300))
+            process.exitCode = 1;
+        return;
+    }
+    console.log(`\n  ${bold(`tokenURI(${tokenId})`)} ${dim(`— read directly from ${address} on ${CHAIN}, no server`)}`);
+    const json = decodeOnChainJson(uri);
+    if (json) {
+        info('decoded on-chain JSON:');
+        console.log(json.split('\n').map((l) => '    ' + l).join('\n') + '\n');
+    }
+    else {
+        console.log(`    ${uri.slice(0, 240)}${uri.length > 240 ? dim(`… (${uri.length} chars)`) : ''}\n`);
+    }
+    if (served)
+        reportServedTokenUri(served, address);
+}
+/** The human readout for `--fetch`. */
+export function reportServedTokenUri(served, address) {
+    if (served.skipped) {
+        info(`--fetch: ${served.skipped}`);
+        return;
+    }
+    console.log(`  ${bold('served')} ${dim(`— GET ${served.url}`)}`);
+    if (served.status === null) {
+        warn(`the baked URL did not respond: ${served.error}. That host is what a marketplace will ask, so this is what they see too.`);
+        return;
+    }
+    const line = `HTTP ${served.status}${served.contentType ? dim(` · ${served.contentType.split(';')[0]}`) : ''}`;
+    if (servedOk(served))
+        ok(line);
+    else
+        console.log(`    ${c.orange}\u26a0${c.reset} ${line}`);
+    const pretty = prettyBody(served.body);
+    const clipped = pretty.length > 1200 ? `${pretty.slice(0, 1200)}\n    \u2026 (${pretty.length} chars \u2014 --json for the full body)` : pretty;
+    console.log(clipped.split('\n').map((l) => '    ' + l).join('\n'));
+    if (!servedOk(served)) {
+        // The mismatch case, stated where it is actionable rather than as a standing warning that would
+        // cry wolf on the common custom-domain setup.
+        console.log(`\n    ${dim('the contract commits to that URL, so a non-2xx is about the SERVICE, never a mistyped path:')} ` +
+            `${dim('the project may not be registered there, the service may serve a different chain, or the base baked on-chain may point at a provider you never registered with.')}\n` +
+            `    ${dim('check the lifecycle:')} ${bold(`abx status ${address} --remote <name|url>`)}`);
+    }
+    console.log('');
+}
+// ── contracturi ──────────────────────────────────────────────────────────────
+/**
+ * `abx contracturi <address>` — the collection-level counterpart of `tokenuri`: read
+ * `contractURI()` (ERC-7572) STRAIGHT FROM THE CONTRACT, then FOLLOW it and decode the JSON.
+ *
+ * Why this exists, and why it follows the URL: the resolver's route grammar is committed
+ * on-chain at deploy (`contractURIBase` = `<baseUrl>/c`), so the contract — not a doc, not a
+ * service descriptor — is the source of truth for where a collection's metadata lives. Without
+ * this command the only way to look was to hand-build the URL from memory of the grammar, and a
+ * guessed path that 404s reads exactly like a broken service. Ask the chain instead.
+ */
+export async function cmdContractUri(address, _flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx contracturi <address>\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        console.error(`abx contracturi: '${address}' isn't a 0x contract address.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    let uri;
+    try {
+        uri = (await publicClient.readContract({
+            address,
+            abi: oneOfOneImageAbi,
+            functionName: 'contractURI',
+            args: [],
+        }));
+    }
+    catch {
+        const code = await publicClient.getCode({ address }).catch(() => undefined);
+        if (!code || code === '0x') {
+            // Name the endpoint we actually asked — "no contract here" and "you're pointed at the wrong
+            // node" are indistinguishable otherwise (same reasoning as `tokenuri`).
+            console.error(`abx contracturi: no contract at ${address} on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}) — ` +
+                `double-check the address, and that this endpoint is the network you deployed to. ` +
+                `If you JUST deployed, give the tx a block or two to mine.\n`);
+        }
+        else {
+            console.error(`abx contracturi: ${address} didn't return a contractURI — it may not be an ABX/ERC-7572 contract, or ` +
+                `— on a large on-chain contractURI — an unauthenticated RPC read hit its gas cap (try a wallet-connected / high-gas RPC).\n`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\n  ${bold('contractURI()')} ${dim(`— read directly from ${address} on ${CHAIN}`)}`);
+    if (!uri) {
+        console.error(`\n  ${bold('empty')} — this contract has no contractURI set: no collection-level metadata to resolve. ` +
+            `Set one with ${bold(`abx set-contract-uri ${address} --uri <base>`)}, or point it at the canonical renderer for the on-chain lane.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const onChain = decodeOnChainJson(uri);
+    if (onChain) {
+        info('resolution: ON-CHAIN (data: URI from the renderer — no server in the path)');
+        console.log(onChain.split('\n').map((l) => '    ' + l).join('\n') + '\n');
+        return;
+    }
+    console.log(`  ${dim('resolves to')} ${uri}`);
+    if (!/^https?:\/\//i.test(uri)) {
+        // ipfs:// / ar:// — a locator, not something we can fetch without choosing a gateway. Print it
+        // rather than silently picking one; the creator's gateway choice is theirs.
+        info(`not an http(s) URL — a ${uri.split(':')[0]}: locator needs a gateway to fetch. Nothing more to read from here.`);
+        console.log('');
+        return;
+    }
+    let body;
+    try {
+        const res = await fetch(uri, { headers: { accept: 'application/json' } });
+        body = await res.text();
+        if (!res.ok) {
+            // The URL came FROM THE CHAIN, so a bad status here is genuinely about the service (or the
+            // contract pointing somewhere stale) — never a mistyped path. Say which, so nobody re-guesses.
+            console.error(`\n  ${bold(`HTTP ${res.status}`)} from the contract's own contractURI — the URL is correct by construction (it came from ` +
+                `${address} on-chain), so this is the SERVICE, not the path. Likely: the project isn't registered on that resolver ` +
+                `(${bold('abx add ' + address + ' --remote')}), the node serves a different chain, or it's down. ` +
+                `Response: ${body.slice(0, 200)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch (e) {
+        console.error(`\n  couldn't reach ${uri} — ${e.message}. The URL is what the contract commits to, so check that the ` +
+            `host is up and publicly reachable (a localhost base URL resolves for no one but this machine).\n`);
+        process.exitCode = 1;
+        return;
+    }
+    info('resolution: OFF-CHAIN (fetched from the URL the contract commits to)');
+    try {
+        console.log(JSON.stringify(JSON.parse(body), null, 2)
+            .split('\n')
+            .map((l) => '    ' + l)
+            .join('\n') + '\n');
+    }
+    catch {
+        console.log(`    ${dim('(not JSON)')} ${body.slice(0, 400)}\n`);
+    }
+}
+// ── status ────────────────────────────────────────────────────────────────--
+// ── tokens: every token's seed + params, read straight from chain ────────────────────────────
+// For a generative collection the seed list IS the collection — it's the first thing you want after
+// a drop ("what did the seeds actually deal?") and, before this existed, the one thing no command
+// could answer. An agent's workaround was: start `abx serve`, GET the project API, base64-decode
+// each tokenURI, base64-decode the animation_url inside it, then regex `0x[0-9a-f]{64}` out of the
+// resulting HTML — 32 times. Every input to that was already a plain contract read.
+export const TOKENS_FLAGS = new Set(['json', 'limit', 'from']);
+/** An owner address abbreviated for a human table. Abbreviating for eyes is fine; abbreviating for a
+ *  PROGRAM is not — which is why every value here is also reachable verbatim via `--json`. */
+export function shortAddr(a) {
+    return `${a.slice(0, 6)}…${a.slice(-4)}`;
+}
+export async function cmdTokens(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx tokens <address> [--json] [--from <id>] [--limit <n>]  — every token\'s owner, seed, and params, from chain\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        console.error(`abx tokens: '${address}' isn't a 0x contract address.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    warnStrayFlags(flags, TOKENS_FLAGS, 'tokens');
+    const jsonMode = flags.json !== undefined;
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    const code = await publicClient.getCode({ address }).catch(() => undefined);
+    if (!code || code === '0x') {
+        // Name the endpoint we actually asked — "no contract here" and "wrong node" are otherwise
+        // indistinguishable (same reasoning as `tokenuri` / `contracturi`).
+        console.error(`abx tokens: no contract at ${address} on ${CHAIN} (asked ${redactRpcUrl(resolveRpcUrl(CHAIN))}) — ` +
+            `double-check the address, and that this endpoint is the network you deployed to. ` +
+            `If you JUST deployed, give the tx a block or two to mine.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const listing = await listTokens(publicClient, address, {
+        from: flags.from === undefined ? undefined : Number(flags.from),
+        limit: flags.limit === undefined ? undefined : Number(flags.limit),
+        // Progress on stderr only — stdout must stay pure JSON in --json mode (the ANSI-in-a-locator
+        // lesson: a program's channel is not a place to narrate).
+        onProgress: (done, total) => total > 50 && done % 25 === 0 ? process.stderr.write(`  reading ${done}/${total}…\r`) : undefined,
+    });
+    if (listing.tokens.length > 50)
+        process.stderr.write('                          \r');
+    if (jsonMode) {
+        process.stdout.write(JSON.stringify(listing, null, 2) + '\n');
+        return;
+    }
+    const supply = listing.totalSupply ?? listing.tokens.length;
+    const cap = listing.maxInvocations !== null && listing.maxInvocations > 0 ? ` of ${listing.maxInvocations} max` : '';
+    console.log(`\n  ${bold(`tokens ${address}`)} ${dim(`— ${supply} minted${cap} on ${CHAIN}`)}`);
+    info('read straight from the contract — no indexer, no resolver, no server in the loop');
+    if (!listing.hasParams) {
+        info('this token type has no params extension — so no seeds or params to list (that is correct, not a failed read). Owners below.');
+    }
+    else if (!listing.hasParamEnumeration) {
+        warn('this contract predates on-chain param enumeration — seeds still read, but params cannot be listed. Redeploy on a current implementation to enumerate them.');
+    }
+    const contractKeys = Object.keys(listing.contractParams);
+    if (contractKeys.length) {
+        info(`contract-scope params ${dim('(every token inherits these; a token-scope value of the same key wins)')}`);
+        for (const k of contractKeys.sort())
+            console.log(`      ${g(k)}=${listing.contractParams[k]}`);
+    }
+    if (!listing.tokens.length) {
+        console.log(`\n  ${dim('no tokens in range — nothing minted yet, or --from is past the mint frontier.')}\n`);
+        return;
+    }
+    const anySeed = listing.tokens.some((t) => t.seed !== null);
+    console.log(`\n    ${dim('id'.padStart(4))}  ${anySeed ? dim('seed'.padEnd(66)) + '  ' : ''}${dim('owner')}`);
+    for (const t of listing.tokens) {
+        // A seed is the whole reason this command exists, so it prints in FULL. The owner truncates —
+        // an address stays recognizable abbreviated, and `--json` carries both verbatim either way.
+        const seedCell = anySeed ? `${t.seed ?? dim('—'.padEnd(66))}  ` : '';
+        const owner = t.owner ? shortAddr(t.owner) : dim('— unminted or burned');
+        console.log(`    ${bold(('#' + t.tokenId).padStart(4))}  ${seedCell}${owner}`);
+        const keys = Object.keys(t.params).sort();
+        if (keys.length)
+            console.log(`          ${keys.map((k) => `${g(k)}=${t.params[k]}`).join(dim(' · '))}`);
+    }
+    // The token-scope param SPREAD — what collectors actually chose, which is the question a param
+    // dump is usually a step toward. Deliberately NOT called a trait spread: traits come from running
+    // the script against the seed (that's `abx render`), not from params.
+    const spread = new Map();
+    for (const t of listing.tokens) {
+        for (const [k, v] of Object.entries(t.params)) {
+            const counts = spread.get(k) ?? new Map();
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+            spread.set(k, counts);
+        }
+    }
+    if (spread.size && listing.tokens.length > 1) {
+        console.log(`\n  ${bold('token-scope param spread')} ${dim('(what has actually been set — not the trait spread, which comes from running the script)')}`);
+        for (const key of [...spread.keys()].sort()) {
+            const counts = [...spread.get(key).entries()].sort((a, b) => b[1] - a[1]);
+            const shown = counts.slice(0, 8).map(([v, n]) => `${v} ${dim('×' + n)}`).join(dim(' · '));
+            const rest = counts.length > 8 ? dim(` …+${counts.length - 8} more values`) : '';
+            console.log(`      ${g(key)}: ${shown}${rest}`);
+        }
+    }
+    console.log(`\n  ${dim('every value above verbatim + machine-readable:')} ${bold(`abx tokens ${address} --json`)}\n`);
+}
+//# sourceMappingURL=reads.js.map