@artblocks/abx-cli 0.1.0-alpha.9 → 0.2.0

package/dist/deps.js

@@ -1,11 +1,9 @@
 /**
- * The deploy-time dependency lane for `abx deploy-code` — pure flag parsing, registry-pointer
- * defaulting, and setup-multicall leg composition (all unit-testable, no network), plus the
- * BEST-EFFORT selection-time registry check (an eth_call per Registry dep; never blocks a
- * deploy). See specs/protocol/dependency-registry.md — the pointer is soft and non-validating.
+ * The `--dep` flag grammar for `abx deploy-code` — the one CLI-local piece of the dependency
+ * lane. Everything downstream of a parsed ref (registry-pointer resolution, setup-multicall leg
+ * composition, the selection-time registry check) lives in `@artblocks/abx-sdk`'s `deps.ts`.
  */
-import { encodeFunctionData } from 'viem';
-import { DEP_RESOLUTION, parseDependencyRef, readRegistryDependency, resolveDependencyRegistry, seriesCodeAbi, } from '@artblocks/abx-sdk';
+import { parseDependencyRef } from '@artblocks/abx-sdk';
 /**
  * Parse the accumulated `--dep` flag value (repeats comma-join — see flags.ts — and each
  * value may itself be comma-separated) into ordered refs. Order is load-bearing: the first
@@ -25,66 +23,4 @@ export function parseDepFlag(value) {
         .filter((s) => s && s.toLowerCase() !== 'none')
         .map(parseDependencyRef);
 }
-/**
- * The registry pointer a deploy with ≥1 Registry-resolution dep should set: an explicit
- * `--dep-registry` wins (validated), else the chain's known AB registry (env-overridable),
- * else none — the caller WARNS and skips the leg (soft pointer; the resolver falls back to
- * its built-in CDN map). Never a blocker.
- */
-export function resolveDepRegistryPointer(flagValue, chainId) {
-    if (flagValue !== undefined) {
-        if (flagValue === 'true' || !/^0x[0-9a-fA-F]{40}$/.test(flagValue)) {
-            throw new Error(`--dep-registry must be an address (0x + 40 hex); got '${flagValue}'`);
-        }
-        return { registry: flagValue, source: 'flag' };
-    }
-    const known = resolveDependencyRegistry(chainId);
-    return known ? { registry: known, source: 'default' } : { registry: null, source: 'none' };
-}
-/**
- * The dependency legs of the setup multicall: one `setDependency(i, resolution, ref)` per
- * dep in index order, plus the `setDependencyRegistry` leg when a pointer resolved. These
- * ride the SAME atomic setup multicall as script chunks/schemas/mints, in every signing lane.
- */
-export function dependencySetupCalls(deps, registry) {
-    const calls = deps.map((d, i) => encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setDependency', args: [BigInt(i), d.resolution, d.ref] }));
-    if (deps.length && registry) {
-        calls.push(encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setDependencyRegistry', args: [registry] }));
-    }
-    return calls;
-}
-/**
- * Best-effort existence/on-chain-ness check of every Registry-resolution dep against the
- * pointer registry. A revert or an empty record ⇒ `not-found` (a warning — the owner may
- * intend a custom registry). A transport failure ⇒ the remaining checks are `skipped` and
- * `rpcOk: false` — one info line, never an error: the deploy proceeds regardless.
- */
-export async function checkRegistryDeps(client, registry, deps) {
-    const registryDeps = deps.filter((d) => d.resolution === DEP_RESOLUTION.registry);
-    const checks = [];
-    let rpcOk = true;
-    for (const d of registryDeps) {
-        if (!rpcOk) {
-            checks.push({ dep: d.display, status: 'skipped' });
-            continue;
-        }
-        try {
-            const details = await readRegistryDependency(client, registry, d.ref);
-            checks.push(details ? { dep: d.display, status: 'found', details } : { dep: d.display, status: 'not-found' });
-        }
-        catch (e) {
-            // A contract revert means the registry answered "no such dependency"; anything else
-            // (DNS, timeout, HTTP) means we couldn't ask — degrade to skipped, not failed.
-            const msg = `${e.name ?? ''} ${e.message ?? ''}`;
-            if (/ContractFunction|revert|returned no data/i.test(msg)) {
-                checks.push({ dep: d.display, status: 'not-found' });
-            }
-            else {
-                rpcOk = false;
-                checks.push({ dep: d.display, status: 'skipped' });
-            }
-        }
-    }
-    return { checks, rpcOk };
-}
 //# sourceMappingURL=deps.js.map

package/dist/deps.js.map

@@ -1 +1 @@
-{"version":3,"file":"deps.js","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deps.js","sourceRoot":"","sources":["../src/deps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,kBAAkB,EAA2B,MAAM,oBAAoB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB;IACpD,IAAI,KAAK,KAAK,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;IAC5H,4FAA4F;IAC5F,mGAAmG;IACnG,8FAA8F;IAC9F,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;SACvB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;SAC9C,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC7B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one error type a command throws when it needs to abort with a specific exit code. No command
+ * body calls `process.exit()` mid-flow: a local failure sets
+ * `process.exitCode` and returns; a DEEP failure that needs to unwind through several calls throws).
+ *
+ * A plain `Error` still works everywhere (the top-level catch in main.ts prints `.message` with the
+ * same `✗` prefix either way) — `CliError` adds two opt-ins:
+ *   - `exitCode`, for the rare case that isn't 1.
+ *   - `alreadyPrinted`, for a validation helper (e.g. ownerops.ts's `requireAddress`/`requireFlag`)
+ *     that has a non-`void` return type and so can't just set `exitCode` and `return` — it has to
+ *     `throw` to make the "unreachable after this" true to the type checker, but it already printed
+ *     its own usage text via `console.error` BEFORE this existed and that text doesn't have (and must
+ *     not gain) the generic catch's `✗` prefix. The top-level catch skips its own printing for these.
+ */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly alreadyPrinted: boolean;
+    constructor(message: string, exitCode?: number, alreadyPrinted?: boolean);
+}
+/** Mark a completed batch command as failed when any item failed, while preserving command cleanup. */
+export declare function markBatchFailure(failed: number): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,cAAc,UAAQ;CAMlE;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIxD"}

package/dist/errors.js

@@ -0,0 +1,32 @@
+/**
+ * The one error type a command throws when it needs to abort with a specific exit code. No command
+ * body calls `process.exit()` mid-flow: a local failure sets
+ * `process.exitCode` and returns; a DEEP failure that needs to unwind through several calls throws).
+ *
+ * A plain `Error` still works everywhere (the top-level catch in main.ts prints `.message` with the
+ * same `✗` prefix either way) — `CliError` adds two opt-ins:
+ *   - `exitCode`, for the rare case that isn't 1.
+ *   - `alreadyPrinted`, for a validation helper (e.g. ownerops.ts's `requireAddress`/`requireFlag`)
+ *     that has a non-`void` return type and so can't just set `exitCode` and `return` — it has to
+ *     `throw` to make the "unreachable after this" true to the type checker, but it already printed
+ *     its own usage text via `console.error` BEFORE this existed and that text doesn't have (and must
+ *     not gain) the generic catch's `✗` prefix. The top-level catch skips its own printing for these.
+ */
+export class CliError extends Error {
+    exitCode;
+    alreadyPrinted;
+    constructor(message, exitCode = 1, alreadyPrinted = false) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+        this.alreadyPrinted = alreadyPrinted;
+    }
+}
+/** Mark a completed batch command as failed when any item failed, while preserving command cleanup. */
+export function markBatchFailure(failed) {
+    if (failed <= 0)
+        return false;
+    process.exitCode = 1;
+    return true;
+}
+//# sourceMappingURL=errors.js.map

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;AAED,uGAAuG;AACvG,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC"}

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.
+ *
+ * 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", "sponsor", "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,0IAaf,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,CAoH7D,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,188 @@
+/**
+ * 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.
+ *
+ * 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',
+    'sponsor',
+    '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']),
+    capabilities: set(['json']),
+    predict: set(['salt', 'for', 'factory', 'copies', 'script', 'code-dir', 'image-renderer', 'dir', 'image']),
+    tokenuri: set(['token', 'fetch', 'json']),
+    contracturi: set(['json']),
+    tokens: set(['json', 'limit', 'from', 'holder']),
+    state: set(['json']),
+    status: set(['watch'], REMOTE),
+    verify: set(['json', 'yes', 'generator'], REMOTE),
+    artifacts: set(['json', 'token'], REMOTE, STORAGE_OVERRIDE),
+    doctor: set(['for', 'fix', 'global', 'agent']),
+    serve: set(['port']),
+    vacuum: set([]),
+    'vacuum convert': set([]),
+    'vacuum incremental': set(['pages']),
+    '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', 'json'], REMOTE, STORAGE_OVERRIDE),
+    index: set(['full', 'no-wait', 'yes', 'to-block'], 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']),
+    'remote set': set(['url']),
+    feedback: set([
+        'remote',
+        'remote-token',
+        'mine',
+        'area',
+        'component',
+        'kind',
+        'summary',
+        'detail',
+        'detail-file',
+        'severity',
+        'via',
+        'context',
+        'context-file',
+        'limit',
+        'yes',
+        'json',
+    ]),
+    'auth login': set(['remote', 'no-open', 'force']),
+    'auth logout': set(['remote']),
+    'auth keys': set(['remote']),
+    'auth revoke-key': set(['remote']),
+    // ── rendering / effects ──
+    render: set(['force', 'effects-url'], REMOTE, STORAGE_OVERRIDE),
+    effects: set(['once', 'port', 'resolver-port', 'interval-ms', 'concurrency'], REMOTE, STORAGE_OVERRIDE),
+    'mint-page': set(['dir', 'name', 'rpc', 'minter-contract']),
+    'scaffold-renderer': set(['force']),
+    'scaffold solidity': 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']),
+    'deploy-contract': set(['artifact', 'initcode', 'constructor-args', 'constructor-args-file', 'label', 'for', 'salt'], SHARED_WRITE),
+    // ── 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'], 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,8 @@
  * 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 Address, type Hex } from 'viem';
+import { type ReconstructBlockTag } from '@artblocks/abx-sdk';
 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 +20,18 @@ 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;
 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 +41,44 @@ 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 `--to-block` for the index lane: only the two REORG-SAFE tags, never a raw block number.
+ *  A number is deliberately refused — `abx index` is incremental and picks its own scan window, so a
+ *  hand-pinned height would silently freeze the watermark somewhere the next run can't reason about;
+ *  the tags are the only values that stay meaningful across runs. Undefined when absent. */
+export declare function parseBlockTagFlag(raw: string | undefined): ReconstructBlockTag | undefined;
+/** Validate an explicit --salt (a 32-byte hex). Undefined when absent. */
+export declare function parseSaltFlag(raw: string | undefined): Hex | undefined;
+/** Refuse an explicit deterministic salt whose deployer guard names somebody else.
+ *
+ * A factory reads the leading 20 salt bytes as either zero (permissionless) or the only address
+ * allowed to deploy it. Prediction itself cannot fail, so without this check a dry run can show a
+ * perfectly real address that the selected signer can never create. */
+export declare function assertSaltGuardForDeployer(salt: Hex, deployer: Address): void;
 //# 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,EAAa,KAAK,OAAO,EAAE,KAAK,GAAG,EAAc,MAAM,MAAM,CAAC;AACrE,OAAO,EAAY,KAAK,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAGvE,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;AAGD,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;;;4FAG4F;AAC5F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAU1F;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,GAAG,SAAS,CAyBtE;AAED;;;;uEAIuE;AACvE,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAQ7E"}