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

package/dist/main.js

@@ -3613,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)) {
@@ -3892,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.
@@ -3916,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
@@ -3935,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,
@@ -5320,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}`);
@@ -5532,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) {
@@ -5560,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) {
@@ -5807,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')}
@@ -5825,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.')}