@artblocks/abx-cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IACjB,cAAc,CAAU;IAEjC,YAAY,OAAe,EAAE,QAAQ,GAAG,CAAC,EAAE,cAAc,GAAG,KAAK;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;CACF"}

package/dist/flag-allowlists.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Per-command flag allowlists — the one place that knows which flags each command accepts, so the
+ * dispatcher can surface a typo'd or unsupported flag instead of silently ignoring it (B30).
+ *
+ * WHY THIS FILE EXISTS, and why the obvious shortcut doesn't work
+ * --------------------------------------------------------------
+ * The CLI used to have three different behaviors for an unrecognized flag: `deploy*` REFUSED,
+ * `preview`/`tokens`/`storage status`/`attach` WARNED, and ~35 other commands said nothing at all —
+ * so `abx set-royalty --bsp 500` or `abx minter buy --quantiy 5` did something quietly different from
+ * what was asked. That silence is the worst failure mode the CLI has, because the creator's next
+ * action is to believe it worked.
+ *
+ * The tempting fix is to DERIVE each allowlist from the `usage` string every command already declares.
+ * An audit of all ~45 commands says that would be actively harmful: several shared helpers read flags
+ * that appear in NO usage string anywhere. `storageOverrides()` reads twelve
+ * (`--backend`, `--gateway`, `--public-base`, `--storage-signer`, …) and is pulled in by `add`,
+ * `render`, `effects`, `migrate`, `storage upload`, and `storage balance|topup`; `--remote-token` is
+ * read by `index`, `verify`, `forget`, `status`, and `migrate`. A usage-derived allowlist would warn on
+ * every one of those — a false warning on a VALID flag, which is worse than the silence it replaces,
+ * because a notice people learn to distrust stops working for the real cases too.
+ *
+ * So the sets below are explicit, and composed from the shared groups by name. A command absent from
+ * `COMMAND_FLAGS` is simply not checked — this can grow incrementally, and an unlisted command keeps
+ * exactly its old behavior rather than acquiring a half-right allowlist.
+ */
+/**
+ * Flags EVERY owner write accepts: the signing lane (`laneFromFlags`), the opt-in confirm gate, the
+ * wallet-lane plumbing, the post-write reindex nudge (`reindexIfKnown` → `resolveRemote`), and
+ * `--json`. Sourced from `riskgate.ts` + `ownerops.ts`, never from a usage string.
+ */
+export declare const SHARED_WRITE: readonly ["send", "sign", "unsigned", "dry-run", "yes", "confirm", "port", "sign-url-file", "remote", "remote-token", "json"];
+/**
+ * What `storageOverrides()` (config.ts) reads. Any command that resolves a storage backend from flags
+ * accepts all twelve — and none of them are documented per-command, which is exactly why a
+ * usage-derived allowlist would have been wrong.
+ */
+export declare const STORAGE_OVERRIDE: readonly ["backend", "endpoint", "bucket", "region", "prefix", "public-base", "gateway", "mode", "api-url", "upload-url", "provider", "storage-signer"];
+/** `remoteFlag()` / `resolveRemote()` — a named service plus its token. */
+export declare const REMOTE: readonly ["remote", "remote-token"];
+/**
+ * Command → accepted flags. Keys are the dispatch names in `main.ts`; a two-word command is keyed by
+ * `"<cmd> <sub>"` (e.g. `"storage upload"`) and falls back to the bare command when no subcommand row
+ * exists. `deploy`/`deploy-series`/`deploy-code` are deliberately ABSENT: they already enforce their
+ * own exhaustive allowlists via `refuseStrayFlags`, and duplicating those sets here would be a second
+ * copy to drift.
+ */
+export declare const COMMAND_FLAGS: Record<string, ReadonlySet<string>>;
+/**
+ * The allowlist for a dispatched command, preferring a `"<cmd> <sub>"` row. Returns undefined when the
+ * command isn't listed, which means "don't check" — never "nothing is allowed".
+ */
+export declare function allowlistFor(cmd: string, sub?: string): ReadonlySet<string> | undefined;
+//# sourceMappingURL=flag-allowlists.d.ts.map

package/dist/flag-allowlists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-allowlists.d.ts","sourceRoot":"","sources":["../src/flag-allowlists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,+HAYf,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,yJAanB,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,MAAM,qCAAsC,CAAC;AAI1D;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAmF7D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAMvF"}

package/dist/flag-allowlists.js

@@ -0,0 +1,157 @@
+/**
+ * Per-command flag allowlists — the one place that knows which flags each command accepts, so the
+ * dispatcher can surface a typo'd or unsupported flag instead of silently ignoring it (B30).
+ *
+ * WHY THIS FILE EXISTS, and why the obvious shortcut doesn't work
+ * --------------------------------------------------------------
+ * The CLI used to have three different behaviors for an unrecognized flag: `deploy*` REFUSED,
+ * `preview`/`tokens`/`storage status`/`attach` WARNED, and ~35 other commands said nothing at all —
+ * so `abx set-royalty --bsp 500` or `abx minter buy --quantiy 5` did something quietly different from
+ * what was asked. That silence is the worst failure mode the CLI has, because the creator's next
+ * action is to believe it worked.
+ *
+ * The tempting fix is to DERIVE each allowlist from the `usage` string every command already declares.
+ * An audit of all ~45 commands says that would be actively harmful: several shared helpers read flags
+ * that appear in NO usage string anywhere. `storageOverrides()` reads twelve
+ * (`--backend`, `--gateway`, `--public-base`, `--storage-signer`, …) and is pulled in by `add`,
+ * `render`, `effects`, `migrate`, `storage upload`, and `storage balance|topup`; `--remote-token` is
+ * read by `index`, `verify`, `forget`, `status`, and `migrate`. A usage-derived allowlist would warn on
+ * every one of those — a false warning on a VALID flag, which is worse than the silence it replaces,
+ * because a notice people learn to distrust stops working for the real cases too.
+ *
+ * So the sets below are explicit, and composed from the shared groups by name. A command absent from
+ * `COMMAND_FLAGS` is simply not checked — this can grow incrementally, and an unlisted command keeps
+ * exactly its old behavior rather than acquiring a half-right allowlist.
+ */
+/**
+ * Flags EVERY owner write accepts: the signing lane (`laneFromFlags`), the opt-in confirm gate, the
+ * wallet-lane plumbing, the post-write reindex nudge (`reindexIfKnown` → `resolveRemote`), and
+ * `--json`. Sourced from `riskgate.ts` + `ownerops.ts`, never from a usage string.
+ */
+export const SHARED_WRITE = [
+    'send',
+    'sign',
+    'unsigned',
+    'dry-run',
+    'yes',
+    'confirm',
+    'port',
+    'sign-url-file',
+    'remote',
+    'remote-token',
+    'json',
+];
+/**
+ * What `storageOverrides()` (config.ts) reads. Any command that resolves a storage backend from flags
+ * accepts all twelve — and none of them are documented per-command, which is exactly why a
+ * usage-derived allowlist would have been wrong.
+ */
+export const STORAGE_OVERRIDE = [
+    'backend',
+    'endpoint',
+    'bucket',
+    'region',
+    'prefix',
+    'public-base',
+    'gateway',
+    'mode',
+    'api-url',
+    'upload-url',
+    'provider',
+    'storage-signer',
+];
+/** `remoteFlag()` / `resolveRemote()` — a named service plus its token. */
+export const REMOTE = ['remote', 'remote-token'];
+const set = (...groups) => new Set(groups.flat());
+/**
+ * Command → accepted flags. Keys are the dispatch names in `main.ts`; a two-word command is keyed by
+ * `"<cmd> <sub>"` (e.g. `"storage upload"`) and falls back to the bare command when no subcommand row
+ * exists. `deploy`/`deploy-series`/`deploy-code` are deliberately ABSENT: they already enforce their
+ * own exhaustive allowlists via `refuseStrayFlags`, and duplicating those sets here would be a second
+ * copy to drift.
+ */
+export const COMMAND_FLAGS = {
+    // ── read-only ──
+    inspect: set(['dep']),
+    predict: set(['salt', 'for', 'factory', 'copies', 'script', 'code-dir', 'image-renderer', 'dir', 'image']),
+    tokenuri: set(['token', 'fetch', 'json']),
+    contracturi: set([]),
+    tokens: set(['json', 'limit', 'from', 'holder']),
+    state: set(['json']),
+    status: set(['watch'], REMOTE),
+    verify: set(['json', 'yes', 'generator'], REMOTE),
+    doctor: set(['for', 'fix', 'global', 'agent']),
+    serve: set(['port']),
+    'skill install': set(['target', 'global', 'agent']),
+    'skill path': set(['target', 'global', 'agent']),
+    // ── indexing / projection ──
+    add: set(['from-block', 'factory', 'label', 'description', 'external-url', 'full', 'yes', 'traits', 'attributes', 'no-wait', 'dry-run'], REMOTE, STORAGE_OVERRIDE),
+    index: set(['full', 'no-wait', 'yes'], REMOTE),
+    forget: set([], REMOTE),
+    migrate: set(['from', 'to', 'from-block', 'factory', 'label', 'yes'], REMOTE, STORAGE_OVERRIDE),
+    remote: set(['conformance', 'remote-token', 'chain-id', 'address', 'from-block']),
+    // ── rendering / effects ──
+    render: set(['force', 'effects-url'], REMOTE, STORAGE_OVERRIDE),
+    effects: set(['once', 'port', 'interval-ms', 'concurrency'], REMOTE, STORAGE_OVERRIDE),
+    'mint-page': set(['dir', 'name', 'rpc', 'minter-contract']),
+    'scaffold-renderer': set(['force']),
+    // ── hosting artifacts ──
+    'deploy-resolver': set(['provider', 'domain', 'app', 'dir', 'from-source']),
+    'deploy-effects': set(['provider', 'resolver-url', 'app', 'dir', 'interval-ms', 'env-id']),
+    // ── storage ──
+    // `show` honors the full override set now (it previews what a given set of flags WOULD resolve to);
+    // before that it read env-only, and the warning correctly fired because the flags really were ignored.
+    storage: set(['check'], STORAGE_OVERRIDE),
+    'storage show': set(['check'], STORAGE_OVERRIDE),
+    'storage upload': set(['key', 'json', 'dry-run'], STORAGE_OVERRIDE),
+    // `status` documents --json and --primary-only in its own usage string; without a row here it fell
+    // back to the bare `storage` row and warned "unrecognized flag(s), ignored: --json" while the flag
+    // visibly worked — a readout contradicting itself is worse than no readout.
+    'storage status': set(['json', 'primary-only'], STORAGE_OVERRIDE),
+    'storage balance': set(['for'], STORAGE_OVERRIDE),
+    'storage topup': set(['usd'], STORAGE_OVERRIDE),
+    'storage backup-key': set(['out']),
+    // ── owner writes (every one also takes SHARED_WRITE) ──
+    refresh: set(['token']), // sends no tx — SHARED_WRITE deliberately does NOT apply
+    'set-minter': set(['minter'], SHARED_WRITE),
+    'set-max-invocations': set(['max'], SHARED_WRITE),
+    'ping-uri': set(['token-ids'], SHARED_WRITE),
+    'configure-param': set(['file', 'remote'], SHARED_WRITE),
+    'submit-app': set(['name', 'summary', 'description', 'mark', 'tone', 'category', 'stage', 'url', 'url-label', 'image', 'tags', 'registry', 'minter'], SHARED_WRITE),
+    'set-schema': set(['schema', 'force'], SHARED_WRITE),
+    'retire-param': set([], SHARED_WRITE),
+    'set-param-hooks': set(['configure', 'augment', 'transfer', 'clear'], SHARED_WRITE),
+    'set-dependency': set([], SHARED_WRITE),
+    'remove-last-dependency': set([], SHARED_WRITE),
+    'set-dependency-registry': set([], SHARED_WRITE),
+    'lock-dependencies': set([], SHARED_WRITE),
+    'lock-script': set([], SHARED_WRITE),
+    'lock-param-hooks': set([], SHARED_WRITE),
+    'set-primary-payee': set(['payee'], SHARED_WRITE),
+    pause: set([], SHARED_WRITE),
+    unpause: set([], SHARED_WRITE),
+    'set-token-uri': set(['uri', 'override', 'token'], SHARED_WRITE),
+    'set-contract-uri': set(['uri', 'override'], SHARED_WRITE),
+    'set-royalty': set(['bps', 'receiver'], SHARED_WRITE),
+    'set-royalty-cap': set(['cap'], SHARED_WRITE),
+    'set-transfer-validator': set([], SHARED_WRITE),
+    'set-seed-source': set([], SHARED_WRITE),
+    'set-field': set(['field', 'text', 'value', 'representation', 'collection', 'token', 'file', 'compress', 'allow-unreadable-onchain'], SHARED_WRITE),
+    'lock-field': set(['field', 'collection', 'token', 'force-field'], SHARED_WRITE),
+    'set-renderer': set(['collection', 'off', 'renderer'], SHARED_WRITE),
+    'lock-uri': set(['collection'], SHARED_WRITE),
+    'set-admin': set(['to'], SHARED_WRITE),
+};
+/**
+ * The allowlist for a dispatched command, preferring a `"<cmd> <sub>"` row. Returns undefined when the
+ * command isn't listed, which means "don't check" — never "nothing is allowed".
+ */
+export function allowlistFor(cmd, sub) {
+    if (sub) {
+        const withSub = COMMAND_FLAGS[`${cmd} ${sub}`];
+        if (withSub)
+            return withSub;
+    }
+    return COMMAND_FLAGS[cmd];
+}
+//# sourceMappingURL=flag-allowlists.js.map

package/dist/flag-allowlists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-allowlists.js","sourceRoot":"","sources":["../src/flag-allowlists.ts"],"names":[],"mappings":"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"}

package/dist/flags.d.ts

@@ -9,6 +9,7 @@
  * the first (a real footgun on a multi-param drop; a Select's options use `|` not `,`, so the
  * comma-join never collides with an option list).
  */
+import { type Hex } from 'viem';
 export type Flags = Record<string, string | undefined>;
 /** Flags where every occurrence counts (values comma-join, in argv order). */
 export declare const REPEATABLE_FLAGS: ReadonlySet<string>;
@@ -18,7 +19,22 @@ export declare const REPEATABLE_FLAGS: ReadonlySet<string>;
  * `no-update-check` opts out of the startup update nudge (see update-check.ts).
  */
 export declare const GLOBAL_FLAGS: ReadonlySet<string>;
+/** Whether `--dry-run` was passed. The one place that truthiness is decided — every write command
+ *  (owner-op or deploy) reads it through here rather than hand-rolling `!!flags['dry-run']`, so a
+ *  fresh command can't ship with a *slightly* different spelling of the same check (or skip it). */
+export declare function isDryRun(flags: Flags): boolean;
+/** Whether `--allow-unreadable-onchain` was passed — the override for the render-gas refusal
+ *  (`guardOnChainSize` in ownerops.ts). Decided in one place for the same reason as
+ *  {@link isDryRun}: every path that stages bytes on-chain has to read it identically. */
+export declare function allowUnreadableOnchain(flags: Flags): boolean;
 export declare function parseFlags(args: string[]): Flags;
+/**
+ * The bare (non-flag) arguments, with flag VALUES removed — the mirror of {@link parseFlags}, and
+ * deliberately next to it: the two must consume argv by the same rule or a flag's value looks like a
+ * positional. (Hand-rolling `args.filter(a => !a.startsWith('-'))` reads `--token 0` as a stray
+ * positional `0`, which is exactly the bug a stray-positional check is meant to catch.)
+ */
+export declare function positionalArgs(args: string[]): string[];
 /**
  * The flag keys in `flags` that are NOT in `allowed` — for a non-fatal "unrecognized flag"
  * notice at a command's entry. {@link parseFlags} keeps any `--k` it sees, so a typo'd or
@@ -28,4 +44,33 @@ export declare function parseFlags(args: string[]): Flags;
  * scripted deploy (owner's stateless/scriptable line — see cli-ux-decisions).
  */
 export declare function unknownFlags(flags: Flags, allowed: Iterable<string>): string[];
+/** Warn (never throw) on a flag the command doesn't recognize — a typo'd or unsupported flag
+ *  otherwise no-ops INVISIBLY (the worst failure mode for a write-adjacent value like a mistyped
+ *  --royalty-bps). Non-fatal, per the owner's scriptability line ([[cli-ux-decisions]]). */
+export declare const FLAG_HINTS: Record<string, (cmd: string) => string | undefined>;
+/**
+ * Unknown flags on a command that can SEND: refuse, don't warn.
+ *
+ * This used to warn and carry on, and `--chain sepolia` proved why that isn't enough — the warning was
+ * accurate, it scrolled past, and the deploy ran on the DEFAULT chain. On a dry run that costs a
+ * confused minute; on a funded send it is a wrong-chain deploy. "Prose that was ignored once will be
+ * ignored again" is the standing rule here, so the tx-sending commands stop instead.
+ *
+ * Safe to refuse rather than warn because a flag absent from the allowlist is, by construction, one
+ * the command never reads — verified per command by comparing every `flags.x` read in its body against
+ * its allowlist. So refusal cannot break a working flag; it only makes an already-ignored one loud.
+ *
+ * `--dry-run` refuses identically. A preview that accepts what the real send rejects is its own trap:
+ * you'd validate a command in preview and have it fail at the moment it matters.
+ */
+export declare function refuseStrayFlags(flags: Flags, allowed: ReadonlySet<string>, cmd: string): void;
+/** Unknown flags on a READ-ONLY command: warn, don't refuse. Nothing can be mis-sent, and a stray
+ *  flag on `preview`/`inspect` shouldn't stop a creator mid-iteration. */
+export declare function warnStrayFlags(flags: Flags, allowed: ReadonlySet<string>, cmd: string): void;
+/** The wallet-lane owner-pinning guard: on `--sign` with no `--for`, whichever wallet connects
+ *  becomes owner + royalty receiver + mint recipient (the launch-readiness "random wallet owns the
+ *  collection" trap). Fires uniformly on deploy / deploy-series / deploy-code. */
+export declare function warnSignWithoutFor(flags: Flags): void;
+/** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
+export declare function parseSaltFlag(raw: string | undefined): Hex | undefined;
 //# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAE9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAC,KAAK,GAAG,EAAC,MAAM,MAAM,CAAC;AAG9B,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEvD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAuC,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAAgC,CAAC;AAE9E;;oGAEoG;AACpG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE9C;AAED;;0FAE0F;AAC1F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE5D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAchD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAWvD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAG9E;AAED;;4FAE4F;AAI5F,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAK1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAU9F;AAED;0EAC0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAS5F;AAED;;kFAEkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAIrD;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,GAAG,SAAS,CAyBtE"}

package/dist/flags.js

@@ -1,11 +1,24 @@
+import { bold, info, warn } from './output.js';
 /** Flags where every occurrence counts (values comma-join, in argv order). */
-export const REPEATABLE_FLAGS = new Set(['dep', 'schema']);
+export const REPEATABLE_FLAGS = new Set(['dep', 'schema', 'param']);
 /**
  * Flags valid on ANY command (handled centrally in main, not by a command handler), so
  * {@link unknownFlags} never flags them as unrecognized regardless of the per-command allowlist.
  * `no-update-check` opts out of the startup update nudge (see update-check.ts).
  */
 export const GLOBAL_FLAGS = new Set(['no-update-check']);
+/** Whether `--dry-run` was passed. The one place that truthiness is decided — every write command
+ *  (owner-op or deploy) reads it through here rather than hand-rolling `!!flags['dry-run']`, so a
+ *  fresh command can't ship with a *slightly* different spelling of the same check (or skip it). */
+export function isDryRun(flags) {
+    return !!flags['dry-run'];
+}
+/** Whether `--allow-unreadable-onchain` was passed — the override for the render-gas refusal
+ *  (`guardOnChainSize` in ownerops.ts). Decided in one place for the same reason as
+ *  {@link isDryRun}: every path that stages bytes on-chain has to read it identically. */
+export function allowUnreadableOnchain(flags) {
+    return flags['allow-unreadable-onchain'] !== undefined;
+}
 export function parseFlags(args) {
     const out = {};
     const set = (k, v) => {
@@ -25,6 +38,25 @@ export function parseFlags(args) {
     }
     return out;
 }
+/**
+ * The bare (non-flag) arguments, with flag VALUES removed — the mirror of {@link parseFlags}, and
+ * deliberately next to it: the two must consume argv by the same rule or a flag's value looks like a
+ * positional. (Hand-rolling `args.filter(a => !a.startsWith('-'))` reads `--token 0` as a stray
+ * positional `0`, which is exactly the bug a stray-positional check is meant to catch.)
+ */
+export function positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (a.indexOf('=') === -1 && args[i + 1] && !args[i + 1].startsWith('--'))
+                i++; // this flag consumes the next token
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
 /**
  * The flag keys in `flags` that are NOT in `allowed` — for a non-fatal "unrecognized flag"
  * notice at a command's entry. {@link parseFlags} keeps any `--k` it sees, so a typo'd or
@@ -37,4 +69,88 @@ export function unknownFlags(flags, allowed) {
     const ok = new Set(allowed);
     return Object.keys(flags).filter((k) => !ok.has(k) && !GLOBAL_FLAGS.has(k));
 }
+/** Warn (never throw) on a flag the command doesn't recognize — a typo'd or unsupported flag
+ *  otherwise no-ops INVISIBLY (the worst failure mode for a write-adjacent value like a mistyped
+ *  --royalty-bps). Non-fatal, per the owner's scriptability line ([[cli-ux-decisions]]). */
+// Targeted "did you mean" hints for the flags creators most often invent (seen across agent sessions).
+// A stray flag is otherwise silently ignored, so a wrong-but-plausible one (a price/supply flag that
+// doesn't exist) reads as "it worked." Command-aware so a flag valid elsewhere isn't mis-hinted.
+export const FLAG_HINTS = {
+    count: (cmd) => (cmd === 'deploy-code' ? 'did you mean --max <N> (the supply cap)?' : undefined),
+    price: () => 'a sale price is NOT set at deploy — configure it after with `abx minter configure <addr> --price <eth>`.',
+    supply: () => 'did you mean --max <N> (the supply cap)?',
+    amount: () => 'a sale price/amount is set post-deploy via `abx minter configure`.',
+};
+/**
+ * Unknown flags on a command that can SEND: refuse, don't warn.
+ *
+ * This used to warn and carry on, and `--chain sepolia` proved why that isn't enough — the warning was
+ * accurate, it scrolled past, and the deploy ran on the DEFAULT chain. On a dry run that costs a
+ * confused minute; on a funded send it is a wrong-chain deploy. "Prose that was ignored once will be
+ * ignored again" is the standing rule here, so the tx-sending commands stop instead.
+ *
+ * Safe to refuse rather than warn because a flag absent from the allowlist is, by construction, one
+ * the command never reads — verified per command by comparing every `flags.x` read in its body against
+ * its allowlist. So refusal cannot break a working flag; it only makes an already-ignored one loud.
+ *
+ * `--dry-run` refuses identically. A preview that accepts what the real send rejects is its own trap:
+ * you'd validate a command in preview and have it fail at the moment it matters.
+ */
+export function refuseStrayFlags(flags, allowed, cmd) {
+    const stray = unknownFlags(flags, allowed);
+    if (!stray.length)
+        return;
+    const hints = stray.map((f) => FLAG_HINTS[f]?.(cmd)).filter(Boolean);
+    throw new Error(`unrecognized flag(s): ${stray.map((f) => '--' + f).join(', ')} — this command would have ignored them silently, so it is refusing instead.\n` +
+        hints.map((h, i) => `    ↳ --${stray[i]}: ${h}`).join('\n') +
+        (hints.length ? '\n' : '') +
+        `    see \`abx help ${cmd}\` for the flags it accepts.`);
+}
+/** Unknown flags on a READ-ONLY command: warn, don't refuse. Nothing can be mis-sent, and a stray
+ *  flag on `preview`/`inspect` shouldn't stop a creator mid-iteration. */
+export function warnStrayFlags(flags, allowed, cmd) {
+    const stray = unknownFlags(flags, allowed);
+    if (stray.length) {
+        warn(`unrecognized flag(s), ignored: ${stray.map((f) => bold('--' + f)).join(', ')} — see \`abx help ${cmd}\`. (A misspelled or unsupported flag silently does nothing.)`);
+        for (const f of stray) {
+            const hint = FLAG_HINTS[f]?.(cmd);
+            if (hint)
+                info(`  ↳ --${f}: ${hint}`);
+        }
+    }
+}
+/** The wallet-lane owner-pinning guard: on `--sign` with no `--for`, whichever wallet connects
+ *  becomes owner + royalty receiver + mint recipient (the launch-readiness "random wallet owns the
+ *  collection" trap). Fires uniformly on deploy / deploy-series / deploy-code. */
+export function warnSignWithoutFor(flags) {
+    if (flags.sign !== undefined && !flags.for) {
+        warn(`--sign without --for: whichever wallet connects becomes ${bold('owner + royalty receiver + mint recipient')}. Pass ${bold('--for <your address>')} to PIN it — the sign page then refuses a mismatched wallet (the intended safety on the wallet lane).`);
+    }
+}
+/** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
+export function parseSaltFlag(raw) {
+    if (!raw || raw === 'true')
+        return undefined;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(raw)) {
+        throw new Error(`--salt must be a 32-byte hex (0x + 64 hex chars); got '${raw}'`);
+    }
+    // Warn here, at the one place every command parses the flag, rather than at the five places a
+    // deploy derives an address from it.
+    //
+    // The factory reads a salt's leading 20 bytes as an access guard: the caller's own address means
+    // only that signer may deploy with it; all-zero means anyone may. Omitting --salt gives you the
+    // former. Only `abx predict` ever explained this, while the deploy commands took an explicit
+    // --salt verbatim and said nothing — so a creator pinning a vanity salt with a zero prefix and
+    // announcing the predicted address was handing it to whoever deployed there first, and the
+    // front-runner becomes `owner()` (ownership is set by `initialize`, not by the prediction).
+    // Reviewed 2026-08; the attack was reproduced. Warn rather than refuse: a zero prefix is the
+    // correct choice for a deliberately shared, caller-independent deployment.
+    if (/^0{40}$/.test(raw.slice(2, 42))) {
+        warn('--salt has an all-zero guard prefix, so ANYONE may deploy to the address it predicts. ' +
+            'Publish that address before you deploy and someone else can take it — and own it. ' +
+            'Drop --salt for a salt pinned to your signer, or keep this only if a shared, ' +
+            'caller-independent address is the point.');
+    }
+    return raw;
+}
 //# sourceMappingURL=flags.js.map

package/dist/flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAaA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAE9E,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE;QACnC,GAAG,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;aAC/C,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;YAC7E,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY,EAAE,OAAyB;IAClE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"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"}

package/dist/jsonout.d.ts

@@ -0,0 +1,37 @@
+import type { Flags } from './flags.js';
+/**
+ * `--json`: make **stdout a machine channel**.
+ *
+ * The rule this enforces, from an integrator who drove the CLI from a server: *a value a program
+ * needs must be obtainable without parsing prose.* They had to regex-scrape ANSI-coloured stdout for
+ * every value — and an escape code ended up inside a locator, was written into a stored player URL,
+ * and 404'd in production. The cause was found only by inspecting stored bytes.
+ *
+ * So under `--json`, stdout carries exactly one JSON document and nothing else. Every narration line
+ * the command would print for a human goes to **stderr** instead — not suppressed, because a human
+ * watching a deploy still wants to see it, and a program redirecting stdout still gets a clean parse.
+ * The update-check already wrote to stderr for precisely this reason; this carries that instinct
+ * through to the values themselves.
+ *
+ * It works by swapping `console.log` for the duration rather than threading a `quiet` flag through
+ * every command body. That is deliberate: the alternative is touching dozens of call sites, where the
+ * one that gets missed is a stray line that corrupts a parse — the exact failure mode being fixed.
+ * `console.error`/`console.warn` are untouched (already stderr), and the payload is written through a
+ * captured reference to the real `console.log`, so nothing can intercept it back.
+ */
+export declare function jsonMode(flags: Flags): boolean;
+/**
+ * Run `body` and, under `--json`, print whatever it returns as the sole contents of stdout.
+ *
+ * `body` receives an `emit` it may call to contribute the payload incrementally — for a command that
+ * discovers its value midway (a deploy learning its address) and would otherwise have to restructure
+ * to return it at the end. The last `emit` wins; a returned value overrides both.
+ *
+ * Without `--json` this is a plain pass-through: zero behaviour change on the human path.
+ */
+export declare function withJson<T extends Record<string, unknown>>(flags: Flags, body: (emit: (payload: T) => void) => Promise<T | void>): Promise<void>;
+/** BigInt-safe JSON: bigints become decimal strings rather than throwing. Every on-chain number a
+ *  payload carries (supply, a token id, a block) arrives as a bigint, and `JSON.stringify` refuses
+ *  them outright — so a payload builder that forgets one would fail at the last line of a deploy. */
+export declare function jsonSafe<T>(value: T): T;
+//# sourceMappingURL=jsonout.d.ts.map

package/dist/jsonout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonout.d.ts","sourceRoot":"","sources":["../src/jsonout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAE9C;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GACtD,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;qGAEqG;AACrG,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEvC"}

package/dist/jsonout.js

@@ -0,0 +1,68 @@
+/**
+ * `--json`: make **stdout a machine channel**.
+ *
+ * The rule this enforces, from an integrator who drove the CLI from a server: *a value a program
+ * needs must be obtainable without parsing prose.* They had to regex-scrape ANSI-coloured stdout for
+ * every value — and an escape code ended up inside a locator, was written into a stored player URL,
+ * and 404'd in production. The cause was found only by inspecting stored bytes.
+ *
+ * So under `--json`, stdout carries exactly one JSON document and nothing else. Every narration line
+ * the command would print for a human goes to **stderr** instead — not suppressed, because a human
+ * watching a deploy still wants to see it, and a program redirecting stdout still gets a clean parse.
+ * The update-check already wrote to stderr for precisely this reason; this carries that instinct
+ * through to the values themselves.
+ *
+ * It works by swapping `console.log` for the duration rather than threading a `quiet` flag through
+ * every command body. That is deliberate: the alternative is touching dozens of call sites, where the
+ * one that gets missed is a stray line that corrupts a parse — the exact failure mode being fixed.
+ * `console.error`/`console.warn` are untouched (already stderr), and the payload is written through a
+ * captured reference to the real `console.log`, so nothing can intercept it back.
+ */
+export function jsonMode(flags) {
+    return flags.json !== undefined;
+}
+/**
+ * Run `body` and, under `--json`, print whatever it returns as the sole contents of stdout.
+ *
+ * `body` receives an `emit` it may call to contribute the payload incrementally — for a command that
+ * discovers its value midway (a deploy learning its address) and would otherwise have to restructure
+ * to return it at the end. The last `emit` wins; a returned value overrides both.
+ *
+ * Without `--json` this is a plain pass-through: zero behaviour change on the human path.
+ */
+export async function withJson(flags, body) {
+    let payload;
+    const emit = (p) => {
+        payload = p;
+    };
+    if (!jsonMode(flags)) {
+        await body(emit);
+        return;
+    }
+    const realLog = console.log;
+    // Route human narration to stderr. Mirrors console.log's own formatting closely enough for
+    // progress text; nothing structured goes through here.
+    console.log = (...args) => process.stderr.write(args.map((a) => String(a)).join(' ') + '\n');
+    try {
+        const returned = await body(emit);
+        const out = returned ?? payload;
+        // A command that emitted nothing is a bug in that command, not a silent empty object — say so on
+        // stderr and leave stdout empty rather than writing `{}` that a caller would trust.
+        if (out === undefined) {
+            process.stderr.write('abx: --json produced no payload for this command (please report it)\n');
+            process.exitCode = 1;
+            return;
+        }
+        realLog(JSON.stringify(out, null, 2));
+    }
+    finally {
+        console.log = realLog;
+    }
+}
+/** BigInt-safe JSON: bigints become decimal strings rather than throwing. Every on-chain number a
+ *  payload carries (supply, a token id, a block) arrives as a bigint, and `JSON.stringify` refuses
+ *  them outright — so a payload builder that forgets one would fail at the last line of a deploy. */
+export function jsonSafe(value) {
+    return JSON.parse(JSON.stringify(value, (_k, v) => (typeof v === 'bigint' ? v.toString() : v)));
+}
+//# sourceMappingURL=jsonout.js.map

package/dist/jsonout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonout.js","sourceRoot":"","sources":["../src/jsonout.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAY;IACnC,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAY,EACZ,IAAuD;IAEvD,IAAI,OAAsB,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,CAAI,EAAE,EAAE;QACpB,OAAO,GAAG,CAAC,CAAC;IACd,CAAC,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAC5B,2FAA2F;IAC3F,uDAAuD;IACvD,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACxG,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,GAAG,GAAI,QAA0B,IAAI,OAAO,CAAC;QACnD,iGAAiG;QACjG,oFAAoF;QACpF,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uEAAuE,CAAC,CAAC;YAC9F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;qGAEqG;AACrG,MAAM,UAAU,QAAQ,CAAI,KAAQ;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAM,CAAC;AACvG,CAAC"}