@artblocks/abx-cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/main.js

@@ -21,6 +21,8 @@
  *   abx remote [<name|url>]  inspect a remote service (descriptor · chains · managed rendering · your projects there)
  *   abx index [<address>]    re-index a project from chain (replay; --remote to nudge a remote resolver)
  *   abx verify <address>     re-hash served bytes vs the on-chain commitment (no server)
+ *   abx tokenuri <address>   read tokenURI(id) from the contract + decode  ·  contracturi: the ERC-7572 collection JSON
+ *                            (the contract holds the URL — never hand-build a resolver path)
  *   abx configure-param <addr> <id> <key> <value>  set a governed PostParam (typed encode; any lane)
  *   abx set-param-hooks <addr>  wire/clear a SeriesCode's configure/augment/transfer param hooks
  *   abx render <addr> [id…]  effect-runner repair lane: render missing stills/traits
@@ -177,6 +179,7 @@ async function main() {
         case 'render': return cmdRender(rest[0], rest.slice(1), flags);
         case 'effects': return cmdEffects(flags);
         case 'tokenuri': return cmdTokenUri(rest[0], flags);
+        case 'contracturi': return cmdContractUri(rest[0], flags);
         case 'serve': return cmdServe(flags);
         // owner operations — write + sign (hot/wallet/cold lane), then re-index
         case 'mint': return cmdMint(rest[0], flags);
@@ -3610,8 +3613,15 @@ async function cmdDeployCode(flags) {
         // has nothing to run — point at the from-chain check instead.
         if (hasImageRenderer && !hasProgram)
             info(`  ${g('nothing to run')} — verify from chain: ${bold('abx tokenuri ' + (predicted ?? '<address>'))} ${dim('(decodes name + on-chain SVG + traits)')}`);
-        else
-            info(`  ${dim('stand up the runner:')} ${bold('abx deploy-effects --resolver-url ' + baseUrl)} · one-shot: ${bold('abx render ' + (predicted ?? '<address>') + (onChainUri && hasImageBase ? '' : ' --remote ' + baseUrl))} · verify: ${bold('abx verify ' + (predicted ?? '<address>'))}`);
+        else {
+            const remoteRender = !(onChainUri && hasImageBase);
+            info(`  ${dim('stand up the runner:')} ${bold('abx deploy-effects --resolver-url ' + baseUrl)} · one-shot: ${bold('abx render ' + (predicted ?? '<address>') + (remoteRender ? ' --remote ' + baseUrl : ''))} · verify: ${bold('abx verify ' + (predicted ?? '<address>'))}`);
+            // Rendering against a resolver you don't share a disk with means YOU hold the bytes and it
+            // holds the URL — so say now which backend that needs, rather than letting the render fail.
+            if (remoteRender && !resolveBackend(storageOptions(storageOverrides(flags))).locator) {
+                info(`  ${dim('that render publishes a URL, so it needs a backend that can name one:')} ${bold('--backend cloud')} ${dim('(S3/R2 + public base) ·')} ${bold('ipfs')} ${dim('·')} ${bold('arweave')} ${dim('— or render co-located with the resolver (`abx effects` on its host).')}`);
+            }
+        }
         if (dirUpload)
             await noteStorageReadiness(storageOptions(storageOverrides(flags)), dirUpload.sizes);
         if (deployer && salt && !parseSaltFlag(flags.salt)) {
@@ -3889,6 +3899,10 @@ async function cmdRender(address, tokenIds, flags) {
     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.
@@ -3913,6 +3927,41 @@ async function cmdRender(address, tokenIds, flags) {
     else
         ok(summary);
 }
+/**
+ * The publish topology's one hard prerequisite, checked BEFORE any capture.
+ *
+ * A resolver that doesn't share this machine's disk serves referenced output (the still, a video, a
+ * model) by **redirect** — so it needs a URL, and it refuses the bytes (`specs/protocol/effects.md →
+ * Bound vs referenced`). A backend that can't name a locator therefore has no publish lane at all,
+ * and every render against one would be work spent to earn a 400.
+ *
+ * So this refuses up front and names the ways out, rather than warning and letting the render run.
+ * It deliberately does NOT pick a backend for the operator: which store holds their art — and which
+ * gateway serves it — is theirs to decide. The three that work are peers, not a ranking: `https://`
+ * from S3/R2, an IPFS gateway, and Arweave are all fine, because derived output is re-creatable and
+ * the only real requirement is that a third party can fetch it.
+ */
+function requirePublishableBackend(flags, what) {
+    const backend = resolveBackend(storageOptions(storageOverrides(flags)));
+    // `cloud` is the one backend that HAS a locator method and can still return null: the URL is
+    // `<publicBase>/<key>`, so without a public base it can name nothing. Catch that here too — it
+    // would otherwise be the same failure one render later.
+    if (backend.id === 'cloud' && !backend.publicBase) {
+        throw new Error(`${what} hands the resolver a URL for each render, but the 'cloud' backend has no public read base — ` +
+            `set ${bold('ABX_S3_PUBLIC_BASE')} to the bucket's public URL (an R2/CloudFront/S3-website base), ` +
+            `or use ${bold('--backend ipfs')} / ${bold('--backend arweave')}, or render co-located with the resolver.`);
+    }
+    if (backend.locator)
+        return;
+    const { backend: name, source } = backendResolution(storageOverrides(flags));
+    throw new Error(`${what} publishes each render to a resolver that doesn't share this machine's disk, but the '${name}' backend ` +
+        `(${source === 'default' ? 'the default' : `from ${source}`}) can't produce a URL for what it stores — so the resolver would have nothing to serve.\n` +
+        `  Point it at a backend that can (equal options — pick on cost/ops, not durability dogma):\n` +
+        `    ${bold('--backend cloud')}    S3 / R2 / B2 with a public base (ABX_S3_* + ABX_S3_PUBLIC_BASE)\n` +
+        `    ${bold('--backend ipfs')}     Pinata or your own Kubo + a public gateway (PINATA_JWT / ABX_IPFS_*)\n` +
+        `    ${bold('--backend arweave')}  pay-once permanent (uploads under 100KiB are free, no setup)\n` +
+        `  …or run co-located instead: ${bold('abx effects')} on the same host as ${bold('abx serve')}, sharing one backend and no remote token.`);
+}
 /**
  * `abx effects` — run the reference effect runner LOCALLY, in-process (the local counterpart to
  * `abx deploy-effects`, which scaffolds a HOSTED runner). This is what makes a param change / new
@@ -3932,6 +3981,8 @@ async function cmdEffects(flags) {
     // the shared artifact registry so the resolver's `artifacts` manifest enumerates it. With an
     // admin token, the publish lane records rows on the hosted resolver instead.
     const localStore = adminToken ? null : new SqliteStore();
+    if (adminToken)
+        requirePublishableBackend(flags, 'abx effects against a remote resolver');
     const { EffectRunner, renderEffect } = await loadEffects();
     const runner = new EffectRunner({
         resolverUrl,
@@ -4397,6 +4448,101 @@ async function cmdTokenUri(address, flags) {
         console.log(`    ${uri.slice(0, 240)}${uri.length > 240 ? dim(`… (${uri.length} chars)`) : ''}\n`);
     }
 }
+// ── 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.
+ */
+async function cmdContractUri(address, _flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx contracturi <address>\n');
+        process.exit(1);
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        console.error(`abx contracturi: '${address}' isn't a 0x contract address.\n`);
+        process.exit(1);
+    }
+    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.exit(1);
+    }
+    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.exit(1);
+    }
+    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.exit(1);
+        }
+    }
+    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.exit(1);
+    }
+    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`);
+    }
+}
 // ── serve ──────────────────────────────────────────────────────────────────--
 async function cmdServe(flags) {
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
@@ -5222,10 +5368,16 @@ async function cmdDoctor(flags) {
     try {
         const backend = resolveBackend(storageOptions());
         const h = await backend.health?.();
+        // Whether this backend can name a public URL for what it stores decides one thing operators hit
+        // later: a REMOTE effects runner needs it (the resolver serves referenced output by redirect, so
+        // it takes a URL and refuses bytes). Co-located rendering doesn't care — hence a note, not a fail.
+        const publishable = backend.locator
+            ? 'can publish to a remote resolver'
+            : 'local-only — a remote effects runner needs cloud/ipfs/arweave (co-located rendering is fine)';
         if (h)
-            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''}`);
+            check('storage', h.ok, `${backend.id} · ${h.detail ?? ''} · ${publishable}`);
         else
-            check('storage', true, `${backend.id} · configured`);
+            check('storage', true, `${backend.id} · configured · ${publishable}`);
     }
     catch (err) {
         check('storage', false, `${backendId} · ${err.message}`);
@@ -5434,13 +5586,19 @@ async function cmdDeployEffects(flags) {
     const intervalMs = flags['interval-ms'] ? Number(flags['interval-ms']) : undefined;
     const environmentId = flags['env-id'] ?? process.env.ABX_ENVIRONMENT_ID;
     const storageBackend = process.env.ABX_STORAGE_BACKEND;
-    // A HOSTED runner must publish renders where the resolver can read them — a durable locator
-    // (ipfs/arweave) or a shared bucket (s3). The default `fs` writes to the runner CONTAINER's disk,
-    // which the resolver can't see → the thumbnail never clears. Flag it before scaffolding (not just
-    // in the artifact's comments), since it's the #1 silent misconfig for a hosted effects runner.
+    // A HOSTED runner holds its own render bytes and hands the resolver a URL — that's the whole
+    // topology (`specs/protocol/effects.md → Bound vs referenced`). The default `fs` writes to the
+    // runner CONTAINER's disk, which nothing else can reach, so there is no URL to publish: the runner
+    // now REFUSES to start on that config. Scaffolding it anyway would just deploy a container that
+    // exits, so this is a hard stop rather than the warning it used to be.
     if (!storageBackend || storageBackend === 'fs') {
-        warn(`ABX_STORAGE_BACKEND is ${storageBackend ? "'fs'" : 'unset (defaults to fs)'} — a HOSTED runner can't publish 'fs' renders anywhere the resolver can read ` +
-            `(the thumbnail will stay a placeholder). Set ABX_STORAGE_BACKEND to ${bold('ipfs')} / ${bold('arweave')} (durable locator) or ${bold('s3')} before deploying the runner.`);
+        throw new Error(`ABX_STORAGE_BACKEND is ${storageBackend ? "'fs'" : 'unset (defaults to fs)'} — a hosted runner can't serve renders off its own container disk, ` +
+            `and it refuses to start without a backend that can name a public URL for what it stores.\n` +
+            `  Set ABX_STORAGE_BACKEND to one of (equal options — pick on cost/ops):\n` +
+            `    ${bold('cloud')} (alias s3)  S3 / R2 / B2 with ABX_S3_* + a public base\n` +
+            `    ${bold('ipfs')}             Pinata or your own Kubo + a public gateway\n` +
+            `    ${bold('arweave')}          pay-once permanent (<100KiB uploads are free)\n` +
+            `  …then re-run. (Rendering on the resolver's own host instead? Use ${bold('abx effects')} co-located — no publish lane, no locator needed.)`);
     }
     const repoRoot = findRepoRoot();
     if (!repoRoot) {
@@ -5462,10 +5620,7 @@ async function cmdDeployEffects(flags) {
     const outDir = resolvePath(joinPath(dir, 'effects'));
     console.log(bold(`\n  ABX Self-Host Toolkit — provision effects runner (fly)`));
     info(`resolver: ${bold(cleanResolver)} ${dim('(reads token state + publishes renders here)')}`);
-    info(`storage home: ${bold(storageBackend ?? 'fs')} ${dim('— where rendered thumbnails live; the resolver redirects/serves from here')}`);
-    if (!storageBackend || storageBackend === 'fs') {
-        warn('storage backend is fs (LOCAL) — a HOSTED runner needs a PUBLIC home (ipfs/arweave/s3) so the resolver can serve the render. Set ABX_STORAGE_BACKEND before deploying, or the runner will push raw bytes to the resolver.');
-    }
+    info(`storage home: ${bold(storageBackend)} ${dim('— the runner HOLDS the render bytes here and publishes their URL; the resolver redirects to it and never proxies')}`);
     step('Write the effects artifact (self-contained — Dockerfile.effects + fly.toml + vendored source)');
     mkdirSync(outDir, { recursive: true });
     for (const f of art.files) {
@@ -5709,8 +5864,12 @@ const COMMAND_HELP = {
     No tokenId → sweeps all minted tokens; pass ids (${g('0 1 2')}) to target specific tokens.
     ${g('--force')}               RE-RENDER even when the still already exists — the fix for a bad / blank / timed-out capture
                           (the art is otherwise deterministic, so a plain render idempotent-skips an existing still). Overwrites it (+ republishes on --remote).
-    ${g('--remote [name|url]')}   publish each render to a REMOTE resolver (the locator bridge: upload to ${bold('ABX_STORAGE_BACKEND')}, POST /v1/effect-artifacts).
-                          Idempotent; a re-run restores a resolver that lost its volume. Needs its token (a named remote's
+    ${g('--remote [name|url]')}   register each render with a REMOTE resolver: the bytes go to ${bold('ABX_STORAGE_BACKEND')} (YOU hold them), and
+                          POST /v1/effect-artifacts hands the resolver the URL — it redirects there and never proxies. Traits are the
+                          exception: they stitch into the token JSON, so their content (≤64KB) goes to the resolver itself.
+                          ${bold('Requires a backend that can name a public URL')} — ${g('--backend cloud')} (S3/R2 + public base), ${g('ipfs')}, or ${g('arweave')};
+                          equal options, pick on cost/ops. The default ${g('fs')} is refused up front rather than after the render.
+                          Idempotent; a re-run re-registers rows on a resolver that lost them. Needs its token (a named remote's
                           ${g('ABX_REMOTE_<NAME>_TOKEN')}, else ${g('ABX_RESOLVER_ADMIN_TOKEN')}).
     --effects-url <url>   enqueue on a running effect-runner service instead of rendering inline (else ${g('ABX_EFFECTS_URL')})
     ${dim('Inline (no --remote) renders on THIS machine (needs `npx playwright install chromium` once), pointing Chromium at the live')}
@@ -5727,8 +5886,10 @@ const COMMAND_HELP = {
     --port <n>            HTTP port (default ${g('ABX_EFFECTS_PORT')} / 8788) — ${g('POST /notify')} enqueues (watcher lane) · ${g('POST /run')} sweeps synchronously (command lane)
     --interval-ms <n>     the SAFETY-FLOOR sweep (default ${g('ABX_EFFECTS_INTERVAL_MS')} / 300000) — catches a missed notify / cold start; the watcher is the trigger
     --concurrency <n>     parallel renders while draining (default ${g('ABX_EFFECTS_CONCURRENCY')} / 1 — Chromium is heavy; raise deliberately)
-    ${dim('Co-located with a local `abx serve` (same store) → no tokens needed. Against a REMOTE resolver: --remote <name|url> (its')}
-    ${dim('token publishes renders + reports status), or ABX_RESOLVER_URL + ABX_RESOLVER_ADMIN_TOKEN. PUBLIC runner? set ABX_EFFECTS_TOKEN — it gates /run + /notify.')}
+    ${dim('Co-located with a local `abx serve` (same store) → no tokens needed, any backend works (fs included).')}
+    ${dim('Against a REMOTE resolver: --remote <name|url> (its token registers renders + reports status), or ABX_RESOLVER_URL +')}
+    ${dim('ABX_RESOLVER_ADMIN_TOKEN — and a backend that can name a public URL (cloud/ipfs/arweave), since the resolver takes the')}
+    ${dim('URL and refuses the bytes. PUBLIC runner? set ABX_EFFECTS_TOKEN — it gates /run + /notify.')}
     ${dim('To HOST the runner (fly/docker), use `abx deploy-effects`.')}`,
     'configure-param': `
   ${bold('abx configure-param')} <address> <tokenId|-> <key> <value> ${dim('— set a PostParam (typed, canonical encode). Sends a tx.')}
@@ -5951,7 +6112,14 @@ const COMMAND_HELP = {
     ${dim(`${g('onChainStatus')} (branch · chain-complete · unresolved refs · URL budget) and decodes ${g('tokenURI')} straight from the contract.`)}`,
     tokenuri: `
   ${bold('abx tokenuri')} <address> [--token <id>] ${dim('— read tokenURI(id) straight from the contract on-chain + decode the JSON (read-only; no server).')}
-    ${dim('The proof a fully on-chain token self-resolves: any RPC returns the renderer-assembled metadata. Default token 0.')}`,
+    ${dim('The proof a fully on-chain token self-resolves: any RPC returns the renderer-assembled metadata. Default token 0.')}
+    ${dim('Collection-level (ERC-7572) counterpart:')} ${g('abx contracturi <address>')}`,
+    contracturi: `
+  ${bold('abx contracturi')} <address> ${dim('— read contractURI() (ERC-7572 collection metadata) from the contract, FOLLOW it, and decode (read-only).')}
+    ${dim('The collection-level counterpart of')} ${g('tokenuri')}${dim('. On-chain lane: decodes the data: URI. Off-chain lane: fetches the')}
+    ${dim('URL the contract itself commits to and prints the JSON.')}
+    ${bold('Never hand-build a resolver URL to check this')} ${dim('— the contract holds the answer, so a URL from here is right by')}
+    ${dim('construction. A bad status is then about the SERVICE (unregistered project · wrong chain · down), never a mistyped path.')}`,
     forget: `
   ${bold('abx forget')} <address> ${dim('— drop a project’s local registration + projection. On-chain data is untouched.')}
     ${g('--remote [name|url]')}  deregister on a REMOTE resolver instead (it stops serving the project; re-add any time)`,
@@ -6022,6 +6190,7 @@ function help() {
     ${g('abx index')} [<address>]   re-index from chain (incremental by default; ${g('--full')} forces a replay from deploy)
     ${g('abx verify')} <addr>       re-hash served bytes vs the on-chain commitment (no server needed)
     ${g('abx tokenuri')} <addr>     read tokenURI(0) on-chain + decode the JSON (proof a self-resolving token works)
+    ${g('abx contracturi')} <addr>  read contractURI() (ERC-7572 collection metadata) on-chain, follow it, decode — never hand-build the URL
     ${g('abx state')} <addr>        one-glance on-chain snapshot: owner · supply · paused · minter · payee · royalty · renderer
     ${g('abx serve')} [--port ..]   serve the token API + dashboard — and WATCH the chain: auto-index every registered
                             project + notify the effects layer on change (${g('ABX_WATCH_INTERVAL_MS')}; 0 = off)