@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/README.md CHANGED
@@ -1,96 +1,118 @@
1
1
  # buidl
2
2
 
3
- Does this deployed DeWEB app match the exact release approved by the team?
3
+ Does this deployed DeWEB app still match the release its reviewers approved?
4
4
 
5
- buidl verifies X Layer DeWEB bytes against TapeOut and compares complete deployments with independently approved manifests. The local demo uses Anvil. The X Layer pilot uses the native TapeOut contracts and a site-specific authority, with a full rehearsal on an Anvil fork. Approval establishes an artifact match. Security reviews and source-to-build reproducibility are separate claims.
5
+ buidl is a CLI for release manifests, reviewer signatures, gated publishing and fresh verification. Developers operate it through wallet, app, policy and release commands. The [web dashboard](https://ola-893.github.io/buidl/) and [public verification links](https://ola-893.github.io/buidl/?verify=1.2.230.tape) are companion inspection surfaces.
6
6
 
7
- ## Use buidl
7
+ ## Install and connect
8
8
 
9
- The **CLI is the primary product distribution and demo surface**. Developers generate manifests, collect reviewer signatures, gate publishing and verify deployed files from the terminal. The [web dashboard](https://ola-893.github.io/buidl/) and [public verification links](https://ola-893.github.io/buidl/?verify=1.2.230.tape) provide inspection and shareable evidence.
9
+ Use Node.js 22.13 or newer. Install the CLI from [npm](https://www.npmjs.com/package/@ola-893/buidl):
10
10
 
11
11
  ```sh
12
- npm install -g @ola-893/buidl@0.4.0
12
+ npm install -g @ola-893/buidl@0.5.0
13
13
  buidl --version
14
- buidl demo --out ./demo-evidence
14
+ buidl --help
15
+ buidl wallet connect --network testnet
16
+ buidl wallet show
15
17
  ```
16
18
 
17
- The one-command demo requires Foundry Anvil, runs the complete lifecycle on its own disposable local node and writes twelve checks with receipts. It sends no public network transactions. The [CLI guide](docs/cli-demo.md) covers actual testnet wallet signing, publishing, recovery and CI.
19
+ `wallet connect` opens a local page where you choose your browser wallet, select X Layer testnet and sign a connection message. It verifies the recovered address and saves the public connection profile. No private key is imported. Every later release signature or transaction has its own wallet confirmation.
18
20
 
19
- The npm package is [`@ola-893/buidl`](https://www.npmjs.com/package/@ola-893/buidl); its terminal command is `buidl`. To build the same package from source, run `npm ci` and `npm pack`. The [published v0.3.0](https://github.com/ola-893/buidl/releases/tag/v0.3.0) supports the earlier X Layer pilot commands and predates this testnet CLI. Node.js 22.13+ is required.
21
+ The write workflow currently supports **X Layer testnet, chain 1952**, using explicitly labeled buidl hosting fixtures. It rejects mainnet. Live TapeOut mainnet inspection is read-only. The complete native TapeOut workflow was also tested separately on a [mainnet fork](docs/xlayer-release.md); that is a different claim from this public testnet fixture pilot.
20
22
 
21
- Public links perform fresh reads when opened, recheck while open, and display the checked block and UTC check time. A live X Layer link reports content integrity and checks current approval when the site is enrolled in a recognized authority. A loopback demo link checks the actual Anvil registry and shows its reviewer evidence and match status. It is scoped to that particular local registry instance and, when available, its current release digest.
23
+ ## Register an app
22
24
 
23
- ## Run locally
24
-
25
- Use Node.js 22.13+ and npm. The controlled release workflow also requires [Foundry Anvil](https://getfoundry.sh/anvil/).
25
+ Run commands individually. Replace the reviewer placeholders with two addresses that differ from the holder:
26
26
 
27
27
  ```sh
28
- npm ci
29
- npm run dev
28
+ buidl app init checkout --network testnet --reviewers 0xREVIEWER1,0xREVIEWER2
29
+ buidl app show
30
+ buidl app deploy
31
+ buidl app deploy --execute
32
+ buidl app enroll --execute
33
+ buidl app register --execute
34
+ buidl policy show
35
+ buidl doctor
30
36
  ```
31
37
 
32
- Open [buidl](http://127.0.0.1:5173). The default site, `1.2.230.tape`, is read from X Layer mainnet. You can also enter names such as `#1@2.230` or an address scoped as `xlayer:0x…` or `xlayer:0x…#1`. The inspector renders metadata and hashes. It never opens the inspected page.
38
+ `app deploy` previews the testnet contract deployments. `--execute` opens wallet confirmations with gas estimates. Enrollment puts the fixture circuit into the authority contract's custody; the depositor can recover it with `buidl app recover --execute`. To use a deployment you already control, pass `--fixtures fixture-config.json` to `app init`.
33
39
 
34
- Run the mainnet inspection in a terminal with `npm run buidl -- inspect 1.2.230.tape`. A captured result is in [live inspection evidence](docs/live-inspection.json).
40
+ ## Approve and publish a release
35
41
 
36
- For the testnet-only pilot, run `buidl testnet --help` and follow [the CLI guide](docs/cli-demo.md). The [separate testnet dashboard](http://127.0.0.1:5173/?testnet=1) and [custody runbook](docs/testnet-pilot.md) remain available. It uses labeled buidl fixtures on chain 1952 because the reviewed TapeOut deployment addresses have no testnet code. Every transaction has a cost review before wallet signing, and the fixture constructors reject mainnet. The testnet commands are available from this checkout; CLI v0.3.0 predates them.
42
+ Generate the manifest from your own build. Keep the manifest outside the build directory:
37
43
 
38
- ## Run the controlled release workflow
44
+ ```sh
45
+ buidl release create checkout-v1 --build ./dist --out ./manifest.json
46
+ buidl release inspect ./manifest.json
47
+ buidl release request ./manifest.json --out ./approval-request.json
48
+ ```
39
49
 
40
- Start a dedicated Anvil instance bound to loopback:
50
+ Each reviewer connects their own wallet and signs the same request. Reviewers can run these commands on separate machines with copies of the project and request files:
41
51
 
42
52
  ```sh
43
- anvil --host 127.0.0.1 --port 8545 --chain-id 31337
53
+ buidl wallet connect --network testnet --account 0xREVIEWER1
54
+ buidl release sign ./approval-request.json --out ./reviewer1.json
44
55
  ```
45
56
 
46
- In a second terminal:
47
-
48
57
  ```sh
49
- npm run demo -- init
50
- npm run demo -- approve a
51
- npm run buidl -- gate demo/release-a public/local-demo/manifest-a.json public/local-demo/config.json
52
- npm run buidl -- publish-local demo/release-a public/local-demo/manifest-a.json public/local-demo/config.json
53
- npm run buidl -- verify-local public/local-demo/manifest-a.json public/local-demo/config.json
58
+ buidl wallet connect --network testnet --account 0xREVIEWER2
59
+ buidl release sign ./approval-request.json --out ./reviewer2.json
54
60
  ```
55
61
 
56
- The first Anvil account publishes. Two of the next three accounts independently sign typed approval. For browser signing, open **Local demo** from the dev server and select **Releases**, then **Load demo A**. Use **Approvals** to create a request, connect the local reviewer accounts in turn, and sign. Export/import carries the request between reviewers. Once the threshold is met, any connected wallet on the local chain can record the approval. To start with an unregistered local site, use `npm run demo -- init --unregistered`, then connect the holder wallet and select **Approvals → Register app**. The scripted `approve a` command is an alternative to the browser signing steps once a policy exists. Use a disposable extension wallet profile and the test-only accounts printed by Anvil.
62
+ The holder reconnects, records the reviewers' approval and publishes the exact build:
63
+
64
+ ```sh
65
+ buidl wallet connect --network testnet --account 0xHOLDER
66
+ buidl release approve ./reviewer1.json ./reviewer2.json
67
+ buidl release approve ./reviewer1.json ./reviewer2.json --execute
68
+ buidl release gate ./dist ./manifest.json
69
+ buidl release publish ./dist ./manifest.json --execute
70
+ buidl release verify --manifest ./manifest.json --out ./verification.json
71
+ buidl wallet history
72
+ ```
57
73
 
58
- Run `npm run demo` for the entire scripted A → bypassed B → approved B demonstration. The [2:40 demo script](docs/demo.md) gives the browser and terminal sequence.
74
+ These are independent operator commands. Nothing automatically creates accounts, signs approvals, funds wallets or runs the release journey. The [CLI guide](https://github.com/ola-893/buidl/blob/v0.5.0/docs/cli.md) covers configuration and recovery. The [recording guide](https://github.com/ola-893/buidl/blob/v0.5.0/docs/cli-demo.md) gives a manual command sequence for presenting your own app.
59
75
 
60
- To generate a candidate from a directory, use **Releases → Select build folder**, or:
76
+ ## Day-to-day operations
61
77
 
62
78
  ```sh
63
- npm run buidl -- manifest demo/release-a --site public/local-demo/site.json \
64
- --release checkout-a --fallback index.html --out /tmp/buidl-manifest-a.json
79
+ buidl wallet show
80
+ buidl app status
81
+ buidl policy show
82
+ buidl release status
83
+ buidl release revoke --execute
84
+ buidl app recover --execute
85
+ buidl wallet reconcile --hash 0xTRANSACTIONHASH
86
+ buidl wallet disconnect
65
87
  ```
66
88
 
67
- Write the manifest outside the build directory. CI should treat the CLI's nonzero exit as a failed check. `inspect` and `verify-local` exit 2 for completed checks without a complete verification or an approved match, respectively. Command, input, and gate failures exit 1.
89
+ Writes preview their action unless `--execute` is present. `release sign` explicitly requests a reviewer signature without a gas fee. Publishing checks the staged bytes and current approval, verifies onchain files before finishing, and performs a fresh final check. An interrupted upload stays unverified. Re-run `release publish` to resume; files are skipped only when fresh hash, size and type checks match the manifest.
68
90
 
69
- ## Architecture
91
+ The CLI records transaction estimates, hashes and receipts in `.buidl/transactions.json` next to the project. Uncertain submissions stop later writes until reconciled. Disconnect clears the saved CLI profile; reject any already-open request in the extension separately.
70
92
 
71
- - `src/core/tapeout.ts` uses the pinned TapeKit kernel for identity, implementation checks, and multi-operator RPC. The inventory reader hashes raw bytes and uses the exact paths and routing metadata returned by SiteRegistry.
72
- - `src/core/manifest.ts` and `src/core/build.ts` implement the canonical format, artifact staging, and comparison. See the [manifest and approval formats](docs/formats.md).
73
- - `src/core/approval.ts` and `contracts/ReleaseRegistry.sol` verify EIP-712 signatures. The registry stores commitments and policy state onchain. Manifests and file contents stay outside the approval registry.
74
- - `contracts/LocalDeweb.sol` is a controlled local fixture with a SiteRegistry-compatible surface and an ownership epoch. It provides explicit upload state, so a multi-transaction upload can stay visibly incomplete.
75
- - `src/cli.ts`, `src/publish.ts`, and `src/web` expose the CLI gate, staged publisher, and React interface. Local JSON exports and registry logs provide portable evidence and chain history.
93
+ `--json` and piped stdout produce structured output for CI. Successful verification exits 0; a completed check without an approved match exits 2; invalid input, failed gates and unavailable dependencies exit 1.
76
94
 
77
- ## Verification and enforcement
95
+ ## Read-only TapeOut inspection
78
96
 
79
97
  ```sh
80
- npm run build
81
- npm test
82
- npx playwright install chromium
83
- npm run test:browser
98
+ buidl inspect 1.2.230.tape
84
99
  ```
85
100
 
86
- The browser suite expects the disposable Anvil service running. It deploys its own fixture per run. Use `BUIDL_BROWSER=chrome npm run test:browser` with installed Chrome. It reads a real mainnet deployment and signs and submits local transactions through a controlled EIP-1193 test provider. The OKX browser-extension path follows its documented EVM interface and still needs an interactive extension check.
101
+ Inspection reconstructs and hashes deployed files. It does not open the inspected app. Approval proves an artifact match; it does not establish a security audit or source-to-build reproducibility. Enforcing access to approved releases still requires integration with the viewer or gateway serving the app.
87
102
 
88
- The supported publisher gates staged bytes before upload and verifies the staged deployment before ending the upload. Direct holder writes can bypass the publisher. A fresh post-deployment read detects divergence. Viewer-side blocking requires a viewer that integrates and enforces the result. For loopback recovery, rerun the gated publisher after the interrupted process exits. After a hard kill, remove the matching empty `.demo/publish-<container>.lock` directory once the old publisher is gone.
103
+ ## Develop and verify
89
104
 
90
- The hosted frontend uses GitHub Pages as its independent HTTPS origin. The [X Layer release pilot](docs/xlayer-release.md) describes the fork rehearsal and team-signed mainnet steps. Existing public sites remain inspectable, and live approval evidence requires explicit site enrollment. The [integration map](docs/integrations.md) records the verified contracts, provider constraints, and hosting options.
105
+ ```sh
106
+ npm ci
107
+ npm run build
108
+ npm test
109
+ npm run test:testnet
110
+ npm run test:cli
111
+ npm run dev
112
+ ```
91
113
 
92
- ## Commercial use and roadmap
114
+ The integration tests require Foundry Anvil and Playwright Chromium. Use `BUIDL_BROWSER=chrome npm run test:cli` to use installed Chrome. Test accounts and disposable nodes belong to the test harness, not the distributed CLI. `npm pack` builds an installable package containing the CLI and wallet page.
93
115
 
94
- The initial users are payment and dapp teams with publishing wallets and separate reviewers. A proposed model is free inspection and portable public evidence, with paid CI integration, team policy administration, and release notifications. TapeOut developer channels and wallet or gateway integrations are candidate distribution channels. Teams would pay for a repeatable approval gate and incident evidence across releases. Commercial deployments should retain the vendored [TapeKit MIT notice](vendor/tapekit/LICENSE). TAP text is CC0, TapeKit code is MIT, and bundled fonts carry their SIL Open Font License notices.
116
+ The [public fixture pilot evidence](https://github.com/ola-893/buidl/blob/v0.5.0/docs/testnet/results/cli-approved-release.json) records a real holder, two reviewer wallets, onchain approval, CLI publishing and a fresh approved match. [Custody and testnet scope](docs/testnet-pilot.md) · [Manifest and approval formats](docs/formats.md) · [Integration map](docs/integrations.md).
95
117
 
96
- Future work includes a curated DeWEB app store, independent reviewer attestations and revocation, contract evidence bound to chain/address/bytecode/proxy/configuration, authorized isolated AI exploit testing, private disclosures and reviewer-validated bounties, and enforcement integrations for directories, gateways, and wallets.
118
+ The app store and AI testing remain deferred. Commercial deployments should retain the vendored [TapeKit MIT notice](vendor/tapekit/LICENSE); third-party notices are included in the CLI package.