@ola-893/buidl 0.0.0-stage → 0.4.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.
@@ -0,0 +1,111 @@
1
+ # buidl CLI
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.
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.
6
+
7
+ ## Install
8
+
9
+ Use Node.js 22.13+; install Foundry's `anvil` for the disposable demo.
10
+
11
+ ```sh
12
+ npm install -g @ola-893/buidl@0.4.0
13
+ buidl --version
14
+ buidl --help
15
+ ```
16
+
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.
18
+
19
+ ## One-command demo
20
+
21
+ ```sh
22
+ buidl demo --out ./demo-evidence
23
+ ```
24
+
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
30
+
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).
32
+
33
+ ```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
40
+ ```
41
+
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
63
+
64
+ ```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
74
+ ```
75
+
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.
79
+
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:
81
+
82
+ ```sh
83
+ buidl testnet reconcile --hash 0xTRANSACTIONHASH
84
+ ```
85
+
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.
89
+
90
+ ## CI
91
+
92
+ Use the project's checked testnet configuration and an explicit RPC if necessary:
93
+
94
+ ```sh
95
+ buidl testnet gate ./dist ./release-manifest.json --project ./buidl.json --json
96
+ buidl testnet verify --project ./buidl.json --json
97
+ ```
98
+
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
+ ```
110
+
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.
package/package.json CHANGED
@@ -1,6 +1,69 @@
1
1
  {
2
2
  "name": "@ola-893/buidl",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.0",
4
+ "type": "module",
5
+ "engines": {
6
+ "node": ">=22.13"
7
+ },
8
+ "scripts": {
9
+ "dev": "vite --host 127.0.0.1",
10
+ "build": "tsc --noEmit && vite build",
11
+ "preview": "vite preview --host 127.0.0.1",
12
+ "buidl": "tsx src/cli.ts",
13
+ "demo": "tsx scripts/demo.ts",
14
+ "test": "tsx --test tests/*.test.ts",
15
+ "test:browser": "playwright test",
16
+ "prepare": "npm run build:cli",
17
+ "build:cli": "node scripts/build-cli.mjs",
18
+ "build:contracts": "tsx scripts/contracts.ts --write",
19
+ "test:xlayer-fork": "tsx scripts/xlayer-fork.ts",
20
+ "build:testnet": "tsx scripts/build-testnet.ts",
21
+ "check:testnet": "tsx scripts/build-testnet.ts --check",
22
+ "testnet:relay": "tsx scripts/testnet-relay.ts",
23
+ "test:testnet": "tsx --test tests/testnet.integration.ts",
24
+ "test:cli": "npm run build:cli && tsx --test tests/terminal.integration.ts"
25
+ },
26
+ "devDependencies": {
27
+ "@fontsource-variable/dm-sans": "^5.3.0",
28
+ "@fontsource-variable/inter": "^5.3.0",
29
+ "@playwright/test": "1.65.1",
30
+ "@tapekit/kernel": "file:vendor/tapekit",
31
+ "@types/node": "^22.0.0",
32
+ "@types/react": "^19.2.0",
33
+ "@types/react-dom": "^19.2.0",
34
+ "esbuild": "0.28.2",
35
+ "lucide-react": "^0.577.0",
36
+ "mime": "4.1.0",
37
+ "react": "^19.2.0",
38
+ "react-dom": "^19.2.0",
39
+ "solc": "0.8.38",
40
+ "tsx": "^4.21.0",
41
+ "typescript": "^5.9.3",
42
+ "viem": "2.57.20",
43
+ "vite": "8.3.8"
44
+ },
45
+ "overrides": {
46
+ "tmp": "0.2.7"
47
+ },
48
+ "license": "MIT",
49
+ "repository": {
50
+ "type": "git",
51
+ "url": "git+https://github.com/ola-893/buidl.git"
52
+ },
53
+ "bin": {
54
+ "buidl": "build-cli/buidl.mjs"
55
+ },
56
+ "files": [
57
+ "build-cli/",
58
+ "docs/cli-demo.md"
59
+ ],
60
+ "description": "Release approval, gated publishing and fresh verification for DeWEB on X Layer",
61
+ "publishConfig": {
62
+ "access": "public",
63
+ "registry": "https://registry.npmjs.org/"
64
+ },
65
+ "homepage": "https://github.com/ola-893/buidl#readme",
66
+ "bugs": {
67
+ "url": "https://github.com/ola-893/buidl/issues"
68
+ }
69
+ }