@ola-893/buidl 0.4.0 → 0.5.0

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/docs/cli-demo.md CHANGED
@@ -1,111 +1,77 @@
1
- # buidl CLI
1
+ # Recording with the CLI
2
2
 
3
- The CLI is buidl's primary distribution and demo surface. It generates release manifests, collects separate reviewer approvals, gates publishing and checks deployed bytes. The dashboard and public verification links remain useful companions.
3
+ Use the actual operational commands below, one at a time. There is no bundled demo command. Prepare your funded testnet holder and two reviewer wallets, a small build directory and a clean recording terminal.
4
4
 
5
- The workflow takes inspiration from [Remora's CLI](https://github.com/ola-893/Remora/tree/codex/near-hackathon/packages/cli): terminal commands own the lifecycle, browser wallets approve signatures, and portable evidence makes the run independently inspectable. This implementation uses buidl's existing release registry and publisher; it does not include Remora code.
5
+ This sequence uses X Layer testnet (1952) and explicitly labeled buidl hosting fixtures. It does not deploy actual TapeOut testnet contracts. The software's adversarial integration tests run separately from the presentation.
6
6
 
7
- ## Install
8
-
9
- Use Node.js 22.13+; install Foundry's `anvil` for the disposable demo.
7
+ ## Holder: connect and register
10
8
 
11
9
  ```sh
12
- npm install -g @ola-893/buidl@0.4.0
10
+ npm install -g @ola-893/buidl@0.5.0
13
11
  buidl --version
14
- buidl --help
12
+ buidl wallet connect --network testnet
13
+ buidl wallet show
14
+ buidl app init checkout --network testnet --reviewers 0xREVIEWER1,0xREVIEWER2
15
+ buidl app deploy
16
+ buidl app deploy --execute
17
+ buidl app enroll --execute
18
+ buidl app register --execute
19
+ buidl policy show
15
20
  ```
16
21
 
17
- The npm package is `@ola-893/buidl`; the executable remains `buidl`. To build from source, run `npm ci` and `npm pack`, then install `./ola-893-buidl-0.4.0.tgz`. The old GitHub v0.3.0 download does not contain these commands. The packed CLI includes its wallet page, fixture bytecode and demo; it runs outside the repository without Vite, React, source files or a running dashboard.
22
+ Replace the address placeholders. Wallet connection signs a message without a gas fee. Deploying, enrolling and registering open separate transaction confirmations with estimates. For an existing app, initialize with its `--fixtures` configuration and inspect `app status` instead of deploying again.
18
23
 
19
- ## One-command demo
24
+ ## Developer: prepare the release
20
25
 
21
26
  ```sh
22
- buidl demo --out ./demo-evidence
27
+ buidl release create checkout-v1 --build ./dist --out ./manifest.json
28
+ buidl release inspect ./manifest.json
29
+ buidl release request ./manifest.json --out ./approval-request.json
23
30
  ```
24
31
 
25
- This starts its own disposable local Anvil, uses its test accounts, prints twelve `PASS` checks, saves public-style receipts and snapshots, and stops Anvil. It covers registration, separate reviewer signatures, threshold rejection, approved publishing, changed-file detection despite valid hashes, interrupted uploads and resumption, revocation, ownership invalidation and circuit recovery. It uses simulated contracts and local accounts; it sends no public testnet or mainnet transactions.
26
-
27
- For a short recording, explain the question: “Does the deployed app still match what the team approved?” Run the command, point out the valid-hash mismatch and the failed ownership reuse, then open `demo-evidence/results.json`. The evidence labels the local network explicitly. Actual public testnet receipts belong in a separate segment.
28
-
29
- ## Actual X Layer testnet
32
+ Explain that the manifest commits to exact files, lengths, content types and routing. The request also binds the reviewers' signatures to this registry, chain, policy, sequence and expiry.
30
33
 
31
- Only chain **1952** is accepted. The reviewed TapeOut mainnet contract addresses have no testnet code, so these commands explicitly use buidl's fixtures. They do not demonstrate an actual TapeOut testnet deployment. See [discovery and custody details](testnet-pilot.md).
34
+ ## Reviewer one
32
35
 
33
36
  ```sh
34
- buidl testnet init --owner 0xHOLDER --reviewers 0xREVIEWER1,0xREVIEWER2
35
- buidl testnet doctor
36
- buidl testnet deploy
37
- buidl testnet deploy --broadcast --wallet
38
- buidl testnet enroll --broadcast --wallet
39
- buidl testnet policy --broadcast --wallet
37
+ buidl wallet connect --network testnet --account 0xREVIEWER1
38
+ buidl release sign ./approval-request.json --out ./reviewer1.json
40
39
  ```
41
40
 
42
- Replace the address placeholders. `doctor` verifies the RPC chain, balance, nonce and configured contract runtime. A fresh project writes `buidl.json`. To use already deployed fixtures, add `--fixtures fixture-config.json` to `init`. To use the guarded loopback RPC relay, add `--rpc http://127.0.0.1:8552`; it forwards to the actual public testnet, while the disposable demo uses its own isolated node.
43
-
44
- All writes default to previews. `--broadcast --wallet` opens a small, temporary wallet review page on `127.0.0.1:5362`. Reusing this local origin avoids reconnecting the extension for every transaction. Only one CLI wallet request can run at a time. The terminal prints each estimated test OKB gas maximum before signing. The page displays the account, chain, destination, nonce and exact payload; choose your wallet and click **Review in wallet**, then confirm in the extension. The CLI verifies the returned signature or transaction against its original request. It never accepts a private key. The estimate is gas limit × quoted gas price; the wallet presents the final network fee.
45
-
46
- ```sh
47
- buidl testnet manifest ./build --release checkout-a --out ./manifest.json
48
- buidl testnet request ./manifest.json --out ./request.json
49
- buidl testnet sign ./request.json --reviewer 0xREVIEWER1 --out ./reviewer1.json --wallet
50
- buidl testnet sign ./request.json --reviewer 0xREVIEWER2 --out ./reviewer2.json --wallet
51
- buidl testnet approve ./reviewer1.json ./reviewer2.json
52
- buidl testnet approve ./reviewer1.json ./reviewer2.json --broadcast --wallet
53
- buidl testnet gate ./build ./manifest.json
54
- buidl testnet publish ./build ./manifest.json --broadcast --wallet
55
- buidl testnet verify --manifest ./manifest.json --out ./verification.json
56
- ```
57
-
58
- Switch to the named reviewer for each signature and back to the holder for publishing. Separate signed files merge only when they describe exactly the same request. The holder cannot count as a reviewer. Previously approved artifacts require a new `request --rollback` and fresh reviewer signatures.
59
-
60
- The manifest must stay outside the build directory. The publisher stages all bytes, rechecks their hashes, verifies the onchain files before finishing, and reconstructs the final release at a checked block. A successful `verify` exits 0. A completed check without an approved match exits 2; input, network and gate failures exit 1. `--json` produces structured output; piped stdout uses JSON automatically.
61
-
62
- ## Resume and lifecycle controls
41
+ ## Reviewer two
63
42
 
64
43
  ```sh
65
- buidl testnet interrupt --broadcast --wallet
66
- buidl testnet verify
67
- buidl testnet publish ./build ./manifest.json --broadcast --wallet
68
- buidl testnet revoke --broadcast --wallet
69
- buidl testnet recover --broadcast --wallet
70
- buidl testnet transfer --to 0xNEWOWNER --broadcast --wallet
71
- buidl testnet enroll --from 0xNEWOWNER --broadcast --wallet
72
- buidl testnet verify
73
- buidl testnet recover --from 0xNEWOWNER --broadcast --wallet
44
+ buidl wallet connect --network testnet --account 0xREVIEWER2
45
+ buidl release sign ./approval-request.json --out ./reviewer2.json
74
46
  ```
75
47
 
76
- A new owner needs test OKB for transactions. Set a new reviewer policy excluding that owner before requesting new approvals. Re-enrollment advances authority history; old signatures cannot be reused.
77
-
78
- `publish` resumes a matching in-progress attempt and skips files only when fresh onchain byte verification matches their exact manifest hash, size and type. Incomplete or changed files are rewritten deterministically. It does not mark an interrupted release as verified. After an interrupted deployment, repeat `deploy`; the saved deployment plan permits resuming the missing authority without redeploying the fixture. If the nonce changed before the first deployment, inspect the saved plan before replacing it.
48
+ Switch the account in your extension when asked. The CLI verifies each recovered reviewer independently. In a team, reviewers can perform these commands separately and return their signed request files.
79
49
 
80
- The CLI saves transaction plans, hashes, complete receipts, blocks and paid gas costs in `.buidl/transactions.json` next to the project. If signing or broadcasting has an uncertain outcome, further writes stop. Check wallet activity and reconcile the exact hash:
50
+ ## Holder: approve, publish and verify
81
51
 
82
52
  ```sh
83
- buidl testnet reconcile --hash 0xTRANSACTIONHASH
53
+ buidl wallet connect --network testnet --account 0xHOLDER
54
+ buidl release approve ./reviewer1.json ./reviewer2.json
55
+ buidl release approve ./reviewer1.json ./reviewer2.json --execute
56
+ buidl release gate ./dist ./manifest.json
57
+ buidl release publish ./dist ./manifest.json --execute
58
+ buidl release verify --manifest ./manifest.json --out ./verification.json
59
+ buidl wallet history
84
60
  ```
85
61
 
86
- After a hard process kill, inspect that journal and the wallet before removing `.buidl/transaction.lock`. No automatic resubmission happens. If a request was rejected before receiving any hash, retain the journal and confirm cancellation in the wallet before using a new project; no onchain receipt can prove a still-open wallet request was cancelled.
87
-
88
- For a controlled mismatch demonstration, generate a second manifest from a build with a different `payment.json`, then run `buidl testnet mutate <changed-build> <changed-manifest> --broadcast --wallet`. This fixture-only operation intentionally bypasses the normal artifact gate while keeping a valid file hash. Fresh verification must report divergence. It is distinct from the normal gated publisher.
62
+ Show the preview, real wallet confirmations, public receipts and checked verification block. You decide when to run each command. Keep the manifest and request exports outside the build directory.
89
63
 
90
- ## CI
64
+ For a changed-build gate check, edit a file in a copy of the build and run `release gate` against the approved manifest. It must fail before requesting a transaction. Changing the deployed files is a separate controlled test; a failed local gate alone does not demonstrate detection of an onchain content change.
91
65
 
92
- Use the project's checked testnet configuration and an explicit RPC if necessary:
66
+ ## Optional lifecycle operations
93
67
 
94
68
  ```sh
95
- buidl testnet gate ./dist ./release-manifest.json --project ./buidl.json --json
96
- buidl testnet verify --project ./buidl.json --json
69
+ buidl release revoke --execute
70
+ buidl release verify --manifest ./manifest.json
71
+ buidl app recover --execute
72
+ buidl wallet disconnect
97
73
  ```
98
74
 
99
- The gate controls workflows that invoke it. Blocking users from opening an unauthorized release still requires integration with the serving viewer or gateway.
100
-
101
- ## Recorded public fixture pilot
102
-
103
- The actual holder and two reviewer wallets completed approval → CLI publishing → fresh verification on X Layer testnet 1952. [Verification evidence](testnet/results/cli-approved-release.json) records **Matches approved release** at block **46452266**, checked **2026-11-17 10:25:09 UTC**. [Final public receipt](https://www.okx.com/web3/explorer/xlayer-test/tx/0x2aa40ef20a4b93ab2b4cad85bfcb1d3bcddef574cfd8356caa04c0b29c824db9) · [All CLI receipts and estimates](testnet/cli-transactions.json).
104
-
105
- From the checkout, perform a new read rather than relying on the saved result:
106
-
107
- ```sh
108
- npm run buidl -- testnet verify --project docs/testnet/cli-project.json --manifest docs/testnet/manifest-a.json --json
109
- ```
75
+ Revocation changes the live verification result. Recovery returns custody to the depositor and invalidates the prior authority. Capture these after recording a successful approved match. Use `wallet reconcile --hash HASH` if a submitted transaction's browser response is interrupted.
110
76
 
111
- On this Mac, append `--rpc http://127.0.0.1:8552` while the guarded public-testnet relay is running if the direct RPC is unavailable. Approval expiry, revocation, ownership and content can change the fresh result. This public pilot uses buidl fixtures. The adverse lifecycle scenarios remain separately labeled local tests.
77
+ The earlier [public fixture pilot](testnet/results/cli-approved-release.json) records holder/reviewer signing and a successful approved match. Its historical receipt evidence remains separate from a new run. For full operation and setup details, see [the CLI guide](cli.md).
package/docs/cli.md ADDED
@@ -0,0 +1,90 @@
1
+ # buidl CLI
2
+
3
+ Install `@ola-893/buidl@0.5.0` from npm and run `buidl --help`. The CLI is an operational tool: you connect the wallets, submit each command and confirm signatures yourself.
4
+
5
+ ## Wallets
6
+
7
+ ```sh
8
+ buidl wallet connect --network testnet
9
+ buidl wallet show
10
+ buidl wallet disconnect
11
+ ```
12
+
13
+ Connect opens `http://127.0.0.1:5362` with a temporary request token. Choose an installed EVM browser wallet and the intended account. The network button can switch or add X Layer testnet, chain 1952. Sign the displayed connection message; the CLI recovers the signer and verifies the RPC chain before saving the public profile.
14
+
15
+ Use `--account 0xADDRESS` to require a specific holder or reviewer. Every later approval signature and transaction verifies the selected account and network again. Connecting never gives the CLI a private key or permission to sign later transactions automatically.
16
+
17
+ The default profile is `~/.config/buidl/wallet.json`. Set `BUIDL_HOME` to a separate directory for a different operator profile or terminal. `wallet disconnect` removes that profile. It does not revoke extension site permissions or cancel an open extension prompt.
18
+
19
+ For an RPC connection problem, specify `--rpc https://YOUR_TESTNET_RPC`. On the pilot Mac, the guarded loopback relay can be used with `--rpc http://127.0.0.1:8552`; it forwards to the public X Layer testnet. The local signing page uses the extension's selected network RPC.
20
+
21
+ ## Apps and policies
22
+
23
+ ```sh
24
+ buidl app init NAME --network testnet --reviewers ADDRESS1,ADDRESS2 --threshold 2
25
+ buidl app show
26
+ buidl app deploy
27
+ buidl app deploy --execute
28
+ buidl app enroll --execute
29
+ buidl app register --execute
30
+ buidl policy show
31
+ buidl policy set --reviewers ADDRESS1,ADDRESS2 --threshold 2 --execute
32
+ ```
33
+
34
+ The project lives in `buidl.json`, or the file given with `--project PATH`. Initialization defaults its holder to the connected wallet. `--owner ADDRESS` permits preparing a project before connecting. Reviewers must be distinct and cannot include the holder.
35
+
36
+ Testnet deployments use buidl's simulated circuit, file store and custody authority. They are not actual TapeOut testnet deployments. [Discovery and custody details](testnet-pilot.md) document the boundary. Enrollment transfers the circuit fixture into the authority; only its depositor can recover it while enrolled.
37
+
38
+ `app init --fixtures FILE` adopts a known fixture configuration. The CLI checks deployed runtime fingerprints, the authority binding and registry provenance before operating on it. Partial deployment plans persist so repeating `app deploy --execute` can resume the missing contract after reconciliation.
39
+
40
+ ## Releases
41
+
42
+ ```sh
43
+ buidl release create NAME --build DIRECTORY --out MANIFEST --fallback index.html
44
+ buidl release inspect MANIFEST
45
+ buidl release request MANIFEST --out REQUEST
46
+ buidl release sign REQUEST --out SIGNED
47
+ buidl release approve SIGNED1 SIGNED2
48
+ buidl release approve SIGNED1 SIGNED2 --execute
49
+ buidl release gate BUILD MANIFEST
50
+ buidl release publish BUILD MANIFEST --execute
51
+ buidl release verify --manifest MANIFEST --out REPORT
52
+ ```
53
+
54
+ Manifest creation reads your files and works offline once the project's site identity is configured. The manifest must be outside the build directory. The fixture publisher accepts files up to 60 KB, uploaded in 12 KB chunks.
55
+
56
+ `release sign` uses the connected reviewer wallet. Its EIP-712 signature binds the chain, site, registry, policy version, sequence, expiry, manifest and artifact set. Unauthorized, duplicate or expired signatures fail validation. Signed request files merge only if they describe the same exact approval.
57
+
58
+ `release approve` previews recording after verifying the threshold. With `--execute`, the active wallet submits it to the registry. `release publish` requires the connected circuit governor, rechecks exact build bytes and approval, requests each transaction separately, verifies deployed files and routing, then closes the publication. The final verification includes the checked block and time.
59
+
60
+ Previously approved artifacts require `release request MANIFEST --out NEW_REQUEST --rollback` and fresh reviewer signatures. A request or signature from before an ownership exit, policy change or re-enrollment cannot be reused.
61
+
62
+ ## Recovery and history
63
+
64
+ ```sh
65
+ buidl wallet history
66
+ buidl wallet reconcile --hash HASH
67
+ buidl release status
68
+ buidl release revoke --execute
69
+ buidl app recover --execute
70
+ buidl app transfer --to NEW_OWNER --execute
71
+ ```
72
+
73
+ The publisher saves `.buidl/transactions.json` next to the project, including estimates, nonces, hashes, receipts and paid gas. A normal rejection in the wallet is recorded as cancelled. An interruption with an uncertain outcome stops later writes; `wallet reconcile` validates the exact returned transaction against the original plan and records its receipt. Never submit again solely because a browser callback failed.
74
+
75
+ After a hard process kill, check wallet activity and the journal before removing a stale `.buidl/transaction.lock`. A wallet confirmation can still broadcast after the CLI exits. If it did, reconcile that hash before continuing. After reconciliation, `release publish` resumes the existing attempt and avoids uploading already verified files again.
76
+
77
+ Ownership exit and re-enrollment invalidate approval authority. Connect the new owner before enrolling. Update the reviewer policy to exclude the new owner before collecting fresh signatures; a confirmed policy change updates the project's configured owner and policy.
78
+
79
+ ## Diagnostics and CI
80
+
81
+ ```sh
82
+ buidl diagnostics
83
+ buidl doctor
84
+ buidl release gate ./dist ./manifest.json --project ./buidl.json --json
85
+ buidl release verify --project ./buidl.json --json
86
+ ```
87
+
88
+ Interactive output is concise; `--json` and pipes retain structured values. The exit codes are 0 for success, 2 for completed verification without a match, and 1 for input, RPC or gate failures. Verification and build gates do not require wallet connection.
89
+
90
+ The operational write workflow accepts testnet 1952 only. `buidl inspect IDENTIFIER` remains a separate read-only TapeOut mainnet inspection command. Viewer or gateway integration is required to block access to unapproved apps.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ola-893/buidl",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=22.13"
@@ -10,7 +10,6 @@
10
10
  "build": "tsc --noEmit && vite build",
11
11
  "preview": "vite preview --host 127.0.0.1",
12
12
  "buidl": "tsx src/cli.ts",
13
- "demo": "tsx scripts/demo.ts",
14
13
  "test": "tsx --test tests/*.test.ts",
15
14
  "test:browser": "playwright test",
16
15
  "prepare": "npm run build:cli",
@@ -55,6 +54,7 @@
55
54
  },
56
55
  "files": [
57
56
  "build-cli/",
57
+ "docs/cli.md",
58
58
  "docs/cli-demo.md"
59
59
  ],
60
60
  "description": "Release approval, gated publishing and fresh verification for DeWEB on X Layer",
@@ -62,7 +62,7 @@
62
62
  "access": "public",
63
63
  "registry": "https://registry.npmjs.org/"
64
64
  },
65
- "homepage": "https://github.com/ola-893/buidl#readme",
65
+ "homepage": "https://github.com/ola-893/buidl/tree/v0.5.0#readme",
66
66
  "bugs": {
67
67
  "url": "https://github.com/ola-893/buidl/issues"
68
68
  }