@artblocks/abx-cli 0.1.0-alpha.16 → 0.1.0-alpha.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +233 -0
- package/dist/jsonout.d.ts +37 -0
- package/dist/jsonout.d.ts.map +1 -0
- package/dist/jsonout.js +68 -0
- package/dist/jsonout.js.map +1 -0
- package/dist/main.js +622 -18
- package/dist/main.js.map +1 -1
- package/dist/ownerops.d.ts +14 -0
- package/dist/ownerops.d.ts.map +1 -1
- package/dist/ownerops.js +164 -41
- package/dist/ownerops.js.map +1 -1
- package/dist/resume.d.ts +96 -0
- package/dist/resume.d.ts.map +1 -0
- package/dist/resume.js +95 -0
- package/dist/resume.js.map +1 -0
- package/dist/served.d.ts +46 -0
- package/dist/served.d.ts.map +1 -0
- package/dist/served.js +65 -0
- package/dist/served.js.map +1 -0
- package/package.json +6 -6
- package/skill/SKILL.md +3 -3
- package/skill/reference/code-projects.md +4 -3
- package/skill/reference/setup.md +2 -1
- package/skill/reference/troubleshooting.md +13 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,238 @@
|
|
|
1
1
|
# @artblocks/abx-cli
|
|
2
2
|
|
|
3
|
+
## 0.1.0-alpha.17
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- df298d8: `abx attach` takes several `<key> <uri>` pairs and sends ONE transaction
|
|
8
|
+
|
|
9
|
+
The safety half of backlog B20. The CLI's most-documented flow — mint, then attach each artifact, then
|
|
10
|
+
refresh — sent one transaction per step with **no all-or-nothing boundary**, so a failure partway
|
|
11
|
+
through left a permanently half-written token, and a mint cannot be undone. An integrator hit exactly
|
|
12
|
+
that and folded 8 operations into 1 transaction (846,556 gas) using the SDK's `batchOps` — a primitive
|
|
13
|
+
the CLI already shipped and did not call. Now it calls it.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
abx attach 0x… stems ipfs://…/stems.wav score ipfs://…/score.pdf readme ar://…
|
|
17
|
+
# → 3 artifacts, one multicall: a revert lands NONE of them
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Three things make the batch safe rather than merely shorter:
|
|
21
|
+
|
|
22
|
+
- **Every pair is validated before anything is sent.** A bad locator in pair 5 stops pair 1 — otherwise
|
|
23
|
+
batching would defeat its own purpose.
|
|
24
|
+
- **A key repeated inside one batch is refused.** A field holds one active value, so the later write
|
|
25
|
+
would silently win — the same full-column-upsert hazard that was a real bug in the resolver's
|
|
26
|
+
`register` and a real trap in `lock-field`.
|
|
27
|
+
- **A single pair is unchanged.** `batchOps` passes a lone op through untouched, so the one-artifact
|
|
28
|
+
case sends the identical plain field transaction it always did — no multicall wrapper, no new gas.
|
|
29
|
+
|
|
30
|
+
An odd number of positionals is refused and names the dangling argument, rather than silently ignoring
|
|
31
|
+
it.
|
|
32
|
+
|
|
33
|
+
Still open in B20, and recorded there rather than quietly skipped: batching **`set-field` across several
|
|
34
|
+
fields** needs a flag-grammar decision first (`attach` batched cleanly because its arguments are
|
|
35
|
+
positional pairs; `set-field` takes one `--field` with a correlated `--text`/`--value`, and the parser
|
|
36
|
+
has no notion of correlated repeats). Same for an all-or-nothing "mint and configure" — mint and
|
|
37
|
+
configure are separate commands, so that needs a verb that owns both.
|
|
38
|
+
|
|
39
|
+
- df298d8: `abx deploy-code --resume <address>` — finish a deploy whose setup transaction failed
|
|
40
|
+
|
|
41
|
+
Closes backlog B15. A code project deploys in **two** transactions: create the clone, then one atomic
|
|
42
|
+
`multicall` carrying the script chunks, the PostParam schemas, the dependency declarations, the
|
|
43
|
+
on-chain-URI legs, and any reserve mints. There is no rollback. When the second one fails you own a
|
|
44
|
+
live-but-unusable contract — and the CREATE2 salt reserved for its address is **spent**, so the dry
|
|
45
|
+
run's pinned-salt reproduce command can never be run again. One reporter session produced three
|
|
46
|
+
orphaned contracts from three attempts; another produced five.
|
|
47
|
+
|
|
48
|
+
The useful half of that report is that those contracts were **recoverable, not lost**: resending the
|
|
49
|
+
setup with an adequate gas limit completed one, after which `abx verify` reported chain-complete and the
|
|
50
|
+
token returned its on-chain `animation_url`. The tester did it by hand with `cast`. We deliberately
|
|
51
|
+
never documented that as a recipe — telling a creator to hand-assemble a multicall is worse than telling
|
|
52
|
+
them nothing — so this is the verb.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
abx deploy-code --resume 0x… <the same content flags the original deploy used> --dry-run
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
It deploys nothing. It reads what the contract already holds and sends only the missing legs, in one
|
|
59
|
+
transaction — safe to run twice, and if nothing is missing it sends nothing and says so. Three judgments
|
|
60
|
+
carry it:
|
|
61
|
+
|
|
62
|
+
- **Chunks compare by content, not by count.** A count check would call a chunk "present" when a hand
|
|
63
|
+
repair wrote different bytes at that index — and a hand repair with `cast` is exactly what happened.
|
|
64
|
+
- **A schema that already exists is left alone.** Re-writing one is an upsert that can strand values
|
|
65
|
+
already stored under it; that hazard belongs to `set-schema` and its guard, never to a repair.
|
|
66
|
+
- **Mints are a shortfall against current supply, never a re-send.** `mint` is the one non-idempotent
|
|
67
|
+
leg, and a token cannot be un-minted.
|
|
68
|
+
|
|
69
|
+
`--salt`, `--721c`, `--bootstrap-factory` and `--mint-all` are refused rather than ignored: they all
|
|
70
|
+
describe how a contract is _created_, and this creates nothing. ERC-721C especially — enrollment is
|
|
71
|
+
deploy-time-only and permanent, so silently accepting the flag would imply it can be added later.
|
|
72
|
+
|
|
73
|
+
It shares the deploy's own setup-leg builder, so a resume can never drift from what a fresh deploy would
|
|
74
|
+
have written — a second implementation of that sequence is the failure mode a repair verb most easily
|
|
75
|
+
introduces. Signing goes through the same choke point as every other write, so `--sign` / `--unsigned` /
|
|
76
|
+
the owner check / the chain-id guard all apply, and `--dry-run` previews the repair (one bug found and
|
|
77
|
+
fixed while building this: the deploy's dry-run block returned first, so `--resume … --dry-run` printed a
|
|
78
|
+
fresh-deploy plan with a newly-reserved salt and a different predicted address).
|
|
79
|
+
|
|
80
|
+
15 tests, including every diff branch and the four refusals.
|
|
81
|
+
|
|
82
|
+
- df298d8: `--json` on every value-emitting command: `mint`, `deploy`, `deploy-series`, `deploy-code`, `state`, `verify`
|
|
83
|
+
|
|
84
|
+
Closes backlog B19. The rule it enforces, from an integrator who drove the CLI from a server: **a value
|
|
85
|
+
a program needs must be obtainable without parsing prose.** They had to regex-scrape ANSI-coloured
|
|
86
|
+
stdout for every value — and an escape code was captured into a locator, written into a _stored_ player
|
|
87
|
+
URL, and 404'd in production. The cause was found only by inspecting stored bytes.
|
|
88
|
+
|
|
89
|
+
Under `--json`, **stdout carries exactly one JSON document and nothing else.** Every narration line the
|
|
90
|
+
command would print for a human moves to **stderr** — diverted, not suppressed, because a human
|
|
91
|
+
watching a deploy still wants to see it while a program redirecting stdout still gets a clean parse.
|
|
92
|
+
(The update check already wrote to stderr for exactly this reason; this carries the instinct through to
|
|
93
|
+
the values themselves.)
|
|
94
|
+
|
|
95
|
+
- **`mint --json`** → `{tokenIds, txHash, blockNumber, sent, …}`. The token ids come from the mint's own
|
|
96
|
+
`Transfer(from=0x0)` logs, not from re-reading `nextTokenId` afterwards — a concurrent mint would make
|
|
97
|
+
that answer wrong, and a number that is usually right is worse than no number. A `--count N` batch
|
|
98
|
+
reports all N.
|
|
99
|
+
- **`deploy` / `deploy-series` / `deploy-code --json`** → the address, emitted _the moment it is known_
|
|
100
|
+
rather than at the end, so a failure in the indexing steps that follow still leaves the caller with
|
|
101
|
+
the address of a contract that really exists. That matters most for `deploy-code`, which is two
|
|
102
|
+
transactions: if the setup tx fails, the address of the live-but-incomplete contract is exactly what a
|
|
103
|
+
recovery needs (backlog B15). With `--dry-run` it reports the **predicted** address plus
|
|
104
|
+
`saltPinned` — false meaning a plain re-run reserves a fresh salt and lands elsewhere, so a caller
|
|
105
|
+
must not treat it as reserved.
|
|
106
|
+
- **`state --json`** → the on-chain snapshot as data, with canonical **names** for param types and auth
|
|
107
|
+
legs rather than raw Solidity enum indices (a caller must not have to know the enum ordering), and
|
|
108
|
+
`undefined` (getter absent) kept distinct from a zero address (present, deliberately unset).
|
|
109
|
+
- **`verify --json`** → the findings, with `ok` matching the exit code. This is the one command a CI job
|
|
110
|
+
would gate on, since it already exits non-zero on a byte mismatch. The tri-states stay tri-states:
|
|
111
|
+
`canonical` and each check's `verified` are `true | false | null`, because collapsing "couldn't check"
|
|
112
|
+
into "failed" would report a normal state as a failure.
|
|
113
|
+
|
|
114
|
+
The mechanism is a single shared helper (`withJson`) rather than a `quiet` flag threaded through every
|
|
115
|
+
command body — deliberately, since the alternative is touching dozens of call sites where the one that
|
|
116
|
+
gets missed is a stray line that corrupts a parse, i.e. the exact failure being fixed. A command that
|
|
117
|
+
emits no payload leaves stdout **empty** and exits non-zero rather than printing a `{}` a caller would
|
|
118
|
+
trust. 8 tests cover the channel contract itself, including that the swap is restored when a body
|
|
119
|
+
throws.
|
|
120
|
+
|
|
121
|
+
- df298d8: `abx storage status <locator>` — is it retrievable yet, or only accepted?
|
|
122
|
+
|
|
123
|
+
Backlog B21, and the second half of a gap two independent integrations hit eight days apart. An upload
|
|
124
|
+
service answers "accepted" the moment it holds your bytes; a gateway serves them only once they
|
|
125
|
+
propagate, and on Arweave that runs to minutes. Nothing in the upload result distinguished the two, so
|
|
126
|
+
the natural implementation — upload during a mint, write the locator into the token — mints a token
|
|
127
|
+
that renders broken for the first minutes of its life.
|
|
128
|
+
|
|
129
|
+
The first reporter rebuilt this layer themselves (ranged GETs, a propagating/ready model, retry ladders
|
|
130
|
+
lengthened after measuring real times) and concluded "every serious integrator will rebuild some
|
|
131
|
+
version of this." The second published 32 renders and found **32/32 404ing on `arweave.net` while 22/32
|
|
132
|
+
already served from `permagate.io` and `vilenarios.com`**, with the uploader reporting `CONFIRMED`
|
|
133
|
+
throughout — and the expensive part is what a creator does next, since a placeholder on a fresh drop
|
|
134
|
+
reads as a failed render, so you re-run `abx render --force` and re-upload everything for nothing.
|
|
135
|
+
|
|
136
|
+
That second observation shapes the design: propagation is **per-gateway**, so the check probes the
|
|
137
|
+
gateway your project actually uses _plus two others_, which buys a third verdict the reporters' own
|
|
138
|
+
two-state model couldn't express.
|
|
139
|
+
|
|
140
|
+
- **`ready`** — your gateway serves the bytes. Safe to reference.
|
|
141
|
+
- **`propagating`** — another gateway serves them, so the data **provably exists** on the network and
|
|
142
|
+
yours is merely behind. Waiting is the fix, and the command says plainly not to re-upload.
|
|
143
|
+
- **`unreachable`** — nothing probed serves them. Deliberately _not_ called propagating: from outside,
|
|
144
|
+
a locator that is still settling and one that is simply wrong look identical, and reporting the
|
|
145
|
+
friendlier of the two is how a tool teaches someone to ignore it. When every gateway rejects the id
|
|
146
|
+
itself (a 4xx that isn't 404) rather than just missing it, that _is_ evidence, and the output says
|
|
147
|
+
"malformed locator, waiting will not fix it" — the inverse mistake of waiting out a typo costs more
|
|
148
|
+
than a needless re-upload.
|
|
149
|
+
|
|
150
|
+
Accepts every form a locator arrives in (`ar://`, `ipfs://`, a gateway URL, a bare txid/CID, with a
|
|
151
|
+
directory path suffix), reads **headers only** via a ranged request with the body cancelled — so
|
|
152
|
+
checking a 40 MB asset doesn't download it — and **exits non-zero unless ready**, which makes waiting a
|
|
153
|
+
one-liner instead of a retry ladder: `until abx storage status <loc> --json; do sleep 10; done`.
|
|
154
|
+
|
|
155
|
+
The primitive is `locatorStatus()` in `@artblocks/abx-storage`, not CLI-only (per B20): anything
|
|
156
|
+
programmatic should call it in-process rather than spawning the CLI per check. `abx render`'s existing
|
|
157
|
+
propagation note now points at the command, so the advisory has an answer attached.
|
|
158
|
+
|
|
159
|
+
- df298d8: `abx tokens <address>` — every token's owner, seed, and params, from chain alone
|
|
160
|
+
|
|
161
|
+
The most obvious post-deploy question about a generative collection — _what did the seeds actually
|
|
162
|
+
deal?_ — had no command. `abx verify` reports per-token minted/render status but no seed; `abx
|
|
163
|
+
tokenuri` prints one token and the seed lives inside its base64 `animation_url`; `abx inspect` is
|
|
164
|
+
pre-deploy and static. An agent's workaround was to start `abx serve`, `GET /api/project/<addr>`,
|
|
165
|
+
base64-decode each `tokenURI`, base64-decode the `animation_url` inside it, then regex
|
|
166
|
+
`0x[0-9a-f]{64}` out of the resulting HTML — 32 times. Every input to that was already a plain
|
|
167
|
+
contract read.
|
|
168
|
+
|
|
169
|
+
`abx tokens <address> [--json] [--from <id>] [--limit <n>]` is chain-only: no indexer projection, no
|
|
170
|
+
running resolver, no event scan. The params store maintains its own key lists inside its write paths
|
|
171
|
+
(`tokenParamKeys` / `contractParamKeys`) and `seed` is a reserved param read by name, so the whole
|
|
172
|
+
listing is `eth_call`s — available to anyone with an RPC URL, including before any indexing has
|
|
173
|
+
happened. Seeds print in full (truncating the one value the command exists for would repeat the
|
|
174
|
+
`tokenuri` bug); `--json` emits `{tokenId, owner, seed, params}` per token, contract-scope params
|
|
175
|
+
once on the parent rather than copied into every row.
|
|
176
|
+
|
|
177
|
+
It reports honestly across all three token types rather than failing: a 1/1 has no params extension
|
|
178
|
+
and says so (owners still list), a pre-enumeration project still yields seeds and flags that params
|
|
179
|
+
can't be enumerated, and an id whose `ownerOf` reverts is `null` — not "not minted", because a
|
|
180
|
+
burned id and an unminted id revert identically and a chain-only read can't tell them apart.
|
|
181
|
+
|
|
182
|
+
Two things it deliberately is not. It is not a trait spread: a trait comes from running the script
|
|
183
|
+
against the seed, which is `abx render`'s job — the token-scope _param_ spread it does print is
|
|
184
|
+
labelled as such. And the reader is in the **SDK** (`listTokens`), not just the CLI, so a
|
|
185
|
+
programmatic integrator gets it without reimplementing it.
|
|
186
|
+
|
|
187
|
+
Backlog B25 (from the 2026-08-04 tester batch, feedback `dcfdc6f4`).
|
|
188
|
+
|
|
189
|
+
- df298d8: `abx tokenuri --fetch` — follow the URL the contract commits to and print what is actually served
|
|
190
|
+
|
|
191
|
+
Closes backlog B14. No command printed the served JSON body: `tokenuri` read the chain, `verify`
|
|
192
|
+
re-hashed bytes, `status` reported the indexing lifecycle — each a different slice, none of them the
|
|
193
|
+
document a marketplace actually reads. An agent in a cold sweep fell back to raw `curl` for exactly
|
|
194
|
+
this, which is the tell that a command was missing.
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
abx tokenuri 0x… --fetch # GET the baked URL, print the served body + HTTP status
|
|
198
|
+
abx tokenuri 0x… --fetch --json # {tokenURI, onChain, served: {url, status, contentType, body}}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
It also answers the question a _warning_ could not, which is why the other half of B14 stays declined.
|
|
202
|
+
"Nothing tells you the provider you registered with isn't the base baked on-chain" is a real gap, but
|
|
203
|
+
the obvious check — compare the remote's base URL to the on-chain one — false-positives on the common
|
|
204
|
+
custom-domain case (a baked `meta.artist.xyz` fronting `api.provider.xyz`), and a warning that cries
|
|
205
|
+
wolf on the correct setup is worse than none. Fetching what the **baked** base returns makes the
|
|
206
|
+
mismatch self-evident instead: you see the other provider's 404, or another project's document, with no
|
|
207
|
+
guessing and no false positive.
|
|
208
|
+
|
|
209
|
+
Three judgments worth naming:
|
|
210
|
+
|
|
211
|
+
- **A `data:` URI is not a failure.** It IS the document, and a fully-on-chain project's whole point is
|
|
212
|
+
that there is no server to ask — so it reports "nothing to fetch" and exits 0. Treating it as an error
|
|
213
|
+
would punish the strongest configuration the protocol offers.
|
|
214
|
+
- **A dead host and a served error are different answers**, because they route to different fixes ("your
|
|
215
|
+
provider said no" vs "the URL a marketplace will ask is unreachable").
|
|
216
|
+
- **A non-2xx says it is about the SERVICE, never a mistyped path** — the URL came from the chain, so it
|
|
217
|
+
is right by construction, and the readout points at `abx status --remote` for the lifecycle.
|
|
218
|
+
|
|
219
|
+
Under `--json` the body is verbatim and untruncated and a non-2xx exits non-zero, so CI can gate on it;
|
|
220
|
+
the human readout clips at 1200 chars and says how many it clipped. The fetch itself lives in
|
|
221
|
+
`src/served.ts` with an injectable `fetch`, since `main.ts` exports nothing — the same reason
|
|
222
|
+
`scaffold.ts` was extracted.
|
|
223
|
+
|
|
224
|
+
This retired the last two `curl` recommendations in the shipped skill: verifying an attach is now
|
|
225
|
+
`abx tokenuri <addr> --fetch` (the served document carries the `artifacts` manifest), and the skill's
|
|
226
|
+
claim that `tokenuri` "follows" the URL — previously true only of `contracturi` — is now accurate.
|
|
227
|
+
|
|
228
|
+
- Updated dependencies [df298d8]
|
|
229
|
+
- Updated dependencies [df298d8]
|
|
230
|
+
- Updated dependencies [df298d8]
|
|
231
|
+
- @artblocks/abx-sdk@0.1.0-alpha.9
|
|
232
|
+
- @artblocks/abx-token-api@0.1.0-alpha.12
|
|
233
|
+
- @artblocks/abx-storage@0.1.0-alpha.9
|
|
234
|
+
- @artblocks/abx-indexer@0.1.0-alpha.10
|
|
235
|
+
|
|
3
236
|
## 0.1.0-alpha.16
|
|
4
237
|
|
|
5
238
|
### Patch Changes
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { Flags } from './flags.js';
|
|
2
|
+
/**
|
|
3
|
+
* `--json`: make **stdout a machine channel**.
|
|
4
|
+
*
|
|
5
|
+
* The rule this enforces, from an integrator who drove the CLI from a server: *a value a program
|
|
6
|
+
* needs must be obtainable without parsing prose.* They had to regex-scrape ANSI-coloured stdout for
|
|
7
|
+
* every value — and an escape code ended up inside a locator, was written into a stored player URL,
|
|
8
|
+
* and 404'd in production. The cause was found only by inspecting stored bytes.
|
|
9
|
+
*
|
|
10
|
+
* So under `--json`, stdout carries exactly one JSON document and nothing else. Every narration line
|
|
11
|
+
* the command would print for a human goes to **stderr** instead — not suppressed, because a human
|
|
12
|
+
* watching a deploy still wants to see it, and a program redirecting stdout still gets a clean parse.
|
|
13
|
+
* The update-check already wrote to stderr for precisely this reason; this carries that instinct
|
|
14
|
+
* through to the values themselves.
|
|
15
|
+
*
|
|
16
|
+
* It works by swapping `console.log` for the duration rather than threading a `quiet` flag through
|
|
17
|
+
* every command body. That is deliberate: the alternative is touching dozens of call sites, where the
|
|
18
|
+
* one that gets missed is a stray line that corrupts a parse — the exact failure mode being fixed.
|
|
19
|
+
* `console.error`/`console.warn` are untouched (already stderr), and the payload is written through a
|
|
20
|
+
* captured reference to the real `console.log`, so nothing can intercept it back.
|
|
21
|
+
*/
|
|
22
|
+
export declare function jsonMode(flags: Flags): boolean;
|
|
23
|
+
/**
|
|
24
|
+
* Run `body` and, under `--json`, print whatever it returns as the sole contents of stdout.
|
|
25
|
+
*
|
|
26
|
+
* `body` receives an `emit` it may call to contribute the payload incrementally — for a command that
|
|
27
|
+
* discovers its value midway (a deploy learning its address) and would otherwise have to restructure
|
|
28
|
+
* to return it at the end. The last `emit` wins; a returned value overrides both.
|
|
29
|
+
*
|
|
30
|
+
* Without `--json` this is a plain pass-through: zero behaviour change on the human path.
|
|
31
|
+
*/
|
|
32
|
+
export declare function withJson<T extends Record<string, unknown>>(flags: Flags, body: (emit: (payload: T) => void) => Promise<T | void>): Promise<void>;
|
|
33
|
+
/** BigInt-safe JSON: bigints become decimal strings rather than throwing. Every on-chain number a
|
|
34
|
+
* payload carries (supply, a token id, a block) arrives as a bigint, and `JSON.stringify` refuses
|
|
35
|
+
* them outright — so a payload builder that forgets one would fail at the last line of a deploy. */
|
|
36
|
+
export declare function jsonSafe<T>(value: T): T;
|
|
37
|
+
//# sourceMappingURL=jsonout.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
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
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `--json`: make **stdout a machine channel**.
|
|
3
|
+
*
|
|
4
|
+
* The rule this enforces, from an integrator who drove the CLI from a server: *a value a program
|
|
5
|
+
* needs must be obtainable without parsing prose.* They had to regex-scrape ANSI-coloured stdout for
|
|
6
|
+
* every value — and an escape code ended up inside a locator, was written into a stored player URL,
|
|
7
|
+
* and 404'd in production. The cause was found only by inspecting stored bytes.
|
|
8
|
+
*
|
|
9
|
+
* So under `--json`, stdout carries exactly one JSON document and nothing else. Every narration line
|
|
10
|
+
* the command would print for a human goes to **stderr** instead — not suppressed, because a human
|
|
11
|
+
* watching a deploy still wants to see it, and a program redirecting stdout still gets a clean parse.
|
|
12
|
+
* The update-check already wrote to stderr for precisely this reason; this carries that instinct
|
|
13
|
+
* through to the values themselves.
|
|
14
|
+
*
|
|
15
|
+
* It works by swapping `console.log` for the duration rather than threading a `quiet` flag through
|
|
16
|
+
* every command body. That is deliberate: the alternative is touching dozens of call sites, where the
|
|
17
|
+
* one that gets missed is a stray line that corrupts a parse — the exact failure mode being fixed.
|
|
18
|
+
* `console.error`/`console.warn` are untouched (already stderr), and the payload is written through a
|
|
19
|
+
* captured reference to the real `console.log`, so nothing can intercept it back.
|
|
20
|
+
*/
|
|
21
|
+
export function jsonMode(flags) {
|
|
22
|
+
return flags.json !== undefined;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Run `body` and, under `--json`, print whatever it returns as the sole contents of stdout.
|
|
26
|
+
*
|
|
27
|
+
* `body` receives an `emit` it may call to contribute the payload incrementally — for a command that
|
|
28
|
+
* discovers its value midway (a deploy learning its address) and would otherwise have to restructure
|
|
29
|
+
* to return it at the end. The last `emit` wins; a returned value overrides both.
|
|
30
|
+
*
|
|
31
|
+
* Without `--json` this is a plain pass-through: zero behaviour change on the human path.
|
|
32
|
+
*/
|
|
33
|
+
export async function withJson(flags, body) {
|
|
34
|
+
let payload;
|
|
35
|
+
const emit = (p) => {
|
|
36
|
+
payload = p;
|
|
37
|
+
};
|
|
38
|
+
if (!jsonMode(flags)) {
|
|
39
|
+
await body(emit);
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
const realLog = console.log;
|
|
43
|
+
// Route human narration to stderr. Mirrors console.log's own formatting closely enough for
|
|
44
|
+
// progress text; nothing structured goes through here.
|
|
45
|
+
console.log = (...args) => process.stderr.write(args.map((a) => String(a)).join(' ') + '\n');
|
|
46
|
+
try {
|
|
47
|
+
const returned = await body(emit);
|
|
48
|
+
const out = returned ?? payload;
|
|
49
|
+
// A command that emitted nothing is a bug in that command, not a silent empty object — say so on
|
|
50
|
+
// stderr and leave stdout empty rather than writing `{}` that a caller would trust.
|
|
51
|
+
if (out === undefined) {
|
|
52
|
+
process.stderr.write('abx: --json produced no payload for this command (please report it)\n');
|
|
53
|
+
process.exitCode = 1;
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
realLog(JSON.stringify(out, null, 2));
|
|
57
|
+
}
|
|
58
|
+
finally {
|
|
59
|
+
console.log = realLog;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
/** BigInt-safe JSON: bigints become decimal strings rather than throwing. Every on-chain number a
|
|
63
|
+
* payload carries (supply, a token id, a block) arrives as a bigint, and `JSON.stringify` refuses
|
|
64
|
+
* them outright — so a payload builder that forgets one would fail at the last line of a deploy. */
|
|
65
|
+
export function jsonSafe(value) {
|
|
66
|
+
return JSON.parse(JSON.stringify(value, (_k, v) => (typeof v === 'bigint' ? v.toString() : v)));
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=jsonout.js.map
|
|
@@ -0,0 +1 @@
|
|
|
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"}
|