diff --git a/.changeset/add-test-command.md b/.changeset/add-test-command.md new file mode 100644 index 00000000..adc8a567 --- /dev/null +++ b/.changeset/add-test-command.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Add `compose test` to run a project's test suite through its detected framework (`forge test` or `npx hardhat test`), with `--` passthrough for framework filters and reporting flags. diff --git a/.changeset/compose-install-package-facets.md b/.changeset/compose-install-package-facets.md new file mode 100644 index 00000000..b2d2db37 --- /dev/null +++ b/.changeset/compose-install-package-facets.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Fix `compose install` of catalog package facets (e.g. `ERC20DataFacet`) in Hardhat projects: package-sourced facets are never copied into `contracts/`, and Hardhat only compiles npm Solidity files listed in `solidity.npmFilesToBuild`, so the install-time validation compile missed the facet and failed with "Facet contract not found in Solidity AST". Install now adds the batch's package facets to the Compose `composeNpmFilesToBuild` overlay in `hardhat.config.ts` before validating, and reverts the config when the transaction rolls back. Projects whose config no longer contains the generated overlay get an error naming the exact specifiers to add manually. Foundry is unaffected (its validation compile already receives the facet paths directly). Install/remove error messages now carry recovery hints (`compose remove `, `path.sol:ContractName` examples, available diamond lists). diff --git a/.changeset/compose-runtime-directory.md b/.changeset/compose-runtime-directory.md new file mode 100644 index 00000000..5a649baf --- /dev/null +++ b/.changeset/compose-runtime-directory.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Move every Compose-owned Hardhat runtime file into the ignored `.compose/hardhat/` directory (`.compose/foundry/` is reserved for Foundry): the transient Ignition runner, the generated deploy result, and the account probe. The probe is now a deterministic rendered template rather than a per-run `scripts/compose-account-check-.ts` file, so an interrupted run can no longer leave an untracked script in a tracked directory. `compose init` and every runtime write now ensure the project `.gitignore` contains `.compose/`; the nested `cache/compose/.gitignore` workaround is gone. diff --git a/.changeset/deploy-command.md b/.changeset/deploy-command.md new file mode 100644 index 00000000..b130a9bd --- /dev/null +++ b/.changeset/deploy-command.md @@ -0,0 +1,7 @@ +--- +"@perfect-abstractions/compose-cli": minor +--- + +Add `compose deploy`: plan the diamond from `compose.json` and generate a reviewable managed deployment artifact. Foundry uses a Solidity script; Hardhat 3 uses a Hardhat Ignition module with an ignored transient runner. The default command prints the artifact path and review instructions without prompting or broadcasting; `--dry-run` simulates on a pinned chain fork, while `--broadcast` explicitly deploys, verifies the result on-chain, and records it in `compose.lock`. Hardhat deployment transaction hashes are read from the Ignition journal by future ID. Signing stays in the framework. Supports `--chain`, a per-deployment `--rpc-url` override, named Compose account aliases, `--instance`, `--redeploy`, and `--` passthrough for framework arguments. Add and list non-secret account aliases with `compose account`. + +Hardhat 3 initialization now uses Hardhat's official non-interactive Ethers/Mocha or Viem/Node test-runner template, overlays Compose project settings without discarding the official config, and requires Node.js 22.13 or newer. diff --git a/.changeset/fix-package-facet-source-precedence.md b/.changeset/fix-package-facet-source-precedence.md new file mode 100644 index 00000000..24fd91c7 --- /dev/null +++ b/.changeset/fix-package-facet-source-precedence.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Resolve package facets from the project framework's package root (Foundry `lib/Compose`, Hardhat `node_modules`), so a project that has both copies no longer fails with an ambiguous package source. diff --git a/.changeset/generated-project-scripts.md b/.changeset/generated-project-scripts.md new file mode 100644 index 00000000..22d8f4c8 --- /dev/null +++ b/.changeset/generated-project-scripts.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Generated Foundry and Hardhat projects now expose native framework commands as `npm run build` and `npm test`, plus Compose workflows as `npm run validate` and `npm run deploy`. Foundry projects also include `npm run fmt`. The `compose build` and `compose test` commands remain available as convenience wrappers. diff --git a/.changeset/hardhat-node-version-check.md b/.changeset/hardhat-node-version-check.md new file mode 100644 index 00000000..2713bbb2 --- /dev/null +++ b/.changeset/hardhat-node-version-check.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Raise the CLI's minimum Node.js version to 22 and check for Node.js 22.13+ before initializing a Hardhat project, so the engine requirement and the getting-started docs agree. diff --git a/.changeset/init-no-deploy-script.md b/.changeset/init-no-deploy-script.md new file mode 100644 index 00000000..2ae0cb01 --- /dev/null +++ b/.changeset/init-no-deploy-script.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": minor +--- + +`compose init` no longer scaffolds a default deploy script; the first `compose deploy` generates the managed, reviewable script from `compose.json` instead. diff --git a/.changeset/init-upgradeability.md b/.changeset/init-upgradeability.md new file mode 100644 index 00000000..c39bba9c --- /dev/null +++ b/.changeset/init-upgradeability.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": minor +--- + +Scaffold immutable diamonds by default: `compose init` prompts for upgradeability, defaulting to Immutable, and non-interactive runs accept `--upgradeable` and `--immutable`. `--upgradeable` includes `DiamondUpgradeFacet` and couples the `owner` base when no ownership base is selected; an explicit `DiamondUpgradeFacet` in `--libraries` opts in for compatibility. Hardhat projects also scaffold a `local` network entry targeting the default Anvil RPC. diff --git a/.changeset/local-compose-cli-dev-dependency.md b/.changeset/local-compose-cli-dev-dependency.md new file mode 100644 index 00000000..b1502247 --- /dev/null +++ b/.changeset/local-compose-cli-dev-dependency.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +`compose init` now adds `@perfect-abstractions/compose-cli` to the generated project's `devDependencies` and installs it, so Compose commands run locally with `npx compose` without a global install. Foundry projects now include a `package.json` for this, and the tutorial and generated READMEs use the `npx compose` flow. diff --git a/.changeset/lock-file-instances.md b/.changeset/lock-file-instances.md new file mode 100644 index 00000000..190630d6 --- /dev/null +++ b/.changeset/lock-file-instances.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": minor +--- + +Nest `compose.lock` deployments by instance (`diamond → chain → instance → deployment`) and validate every recorded instance in `compose validate`. diff --git a/.changeset/redact-command-secrets.md b/.changeset/redact-command-secrets.md new file mode 100644 index 00000000..df9d6e31 --- /dev/null +++ b/.changeset/redact-command-secrets.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": patch +--- + +Redact private keys, mnemonics, passwords, and secret-bearing RPC URLs from command failure errors and passthrough validation messages. diff --git a/.changeset/sepolia-default-chain.md b/.changeset/sepolia-default-chain.md new file mode 100644 index 00000000..629398c8 --- /dev/null +++ b/.changeset/sepolia-default-chain.md @@ -0,0 +1,5 @@ +--- +"@perfect-abstractions/compose-cli": minor +--- + +Generated Foundry and Hardhat projects now include a preconfigured `sepolia` chain. `compose.json` points Sepolia at `${SEPOLIA_RPC_URL}`, Foundry projects add a `sepolia` entry under `[rpc_endpoints]`, and Hardhat projects define a Sepolia HTTP network that reads `SEPOLIA_RPC_URL` and the `SEPOLIA_PRIVATE_KEY` signer. Generated projects also include a `.env.example` and README instructions for Sepolia deployments. diff --git a/.gitignore b/.gitignore index cbd2dd0b..a96c85a3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,9 @@ cache/ out/ +# Compose runtime files +.compose/ + # Ignores development broadcast logs !/broadcast /broadcast/*/31337/ diff --git a/cli/.gitignore b/cli/.gitignore index 00b5052a..9e3f77c8 100644 --- a/cli/.gitignore +++ b/cli/.gitignore @@ -8,4 +8,4 @@ my-diamond/ .env .env.local -docs/ \ No newline at end of file +docs/ diff --git a/cli/README.md b/cli/README.md index 04432504..520428ca 100644 --- a/cli/README.md +++ b/cli/README.md @@ -2,6 +2,8 @@ The Compose CLI is the fastest way to start a modular smart contract project. Scaffold a facet-based diamond, choose your building blocks, and develop with [Foundry](https://book.getfoundry.sh/) or [Hardhat](https://hardhat.org/). +The CLI requires Node.js 22 or newer. Hardhat 3 projects it generates require Node.js 22.13 or newer. + ## Quick Start ```bash @@ -10,6 +12,7 @@ npx @perfect-abstractions/compose-cli init This starts an interactive flow to scaffold a new diamond project with: - Base preset selection (Counter, ERC-20, ERC-721, ERC-721 Enumerable, ERC-1155, ERC-6909) +- Upgradeability selection (immutable by default) - Extension facet selection - Ownership and access control configuration - Compose library facet selection @@ -21,17 +24,24 @@ This starts an interactive flow to scaffold a new diamond project with: compose init [options] [project-name] compose install [facet-ref...] [options] compose remove [facet-ref...] [options] +compose account setup [options] +compose account list +compose account check [options] +compose account remove [options] compose catalog compose info compose validate [options] compose build +compose test [options] compose rpc [options] compose inspect
[options] +compose deploy [options] compose help [command] compose --version | -V compose --help | -h ``` -``` + +Generated projects expose framework-native commands as `npm run build` and `npm test` (plus `npm run fmt` for Foundry), alongside the Compose `npm run validate` workflow. Use `npx compose deploy` to deploy. The `compose build` and `compose test` commands remain available as convenience wrappers. ### `compose init` @@ -42,17 +52,25 @@ Scaffold a new Compose diamond project. - `--framework `: target framework (default: foundry) - `--toolbox `: Hardhat toolbox (default: ethers) - `--base `: base preset — `counter`, `erc-20`, `erc-721`, `erc-721-enumerable`, `erc-1155`, `erc-6909`, or `none` for a blank project -- `--ownership `: ownership base — `owner` or `owner-two-step`; omit the flag for no ownership +- `--ownership `: ownership base — `owner` or `owner-two-step`; omit the flag for no ownership (upgradeable projects without an ownership base default to `owner`) - `--ownership-extensions `: comma-separated ownership extension facets - `--access-control `: comma-separated access control bases (for example `access-control`) - `--access-control-extensions `: comma-separated access control extension facets +- `--upgradeable`: include `DiamondUpgradeFacet` and the owner coupling +- `--immutable`: scaffold without the upgrade facet and owner coupling (default) - `--libraries `: comma-separated Compose library facets - `--extensions `: comma-separated extension facets - `--out `: parent directory for the project (defaults to the current directory) - `--yes`: non-interactive mode; requires `--base` -- `--install-deps` / `--no-install-deps`: install or skip framework dependencies +- `--install-deps` / `--no-install-deps`: install or skip framework dependencies (`--no-install-deps` is Foundry-only; Hardhat 3's official template initializer installs its required dependencies) + +Selection flags apply to `--yes` runs. Without `--yes`, only `[project-name]` and `--out` are honored and `compose init` prompts for the framework, toolbox, base, upgradeability, extensions, libraries, and ownership. Foundry asks whether to install dependencies; Hardhat uses its official template initializer, which installs its dependencies. -Selection flags apply to `--yes` runs. Without `--yes`, only `[project-name]` and `--out` are honored and `compose init` prompts for the framework, toolbox, base, extensions, libraries, ownership, access control, and dependency installation. +Immutable is the default. `--upgradeable` adds `DiamondUpgradeFacet` and, when no ownership base is chosen, Compose offers the `owner` base (interactive) or adds it with a note (non-interactive). An explicit `DiamondUpgradeFacet` in `--libraries` opts into upgradeability the same way for compatibility; combining it with `--immutable` is an error. + +Generated Foundry and Hardhat projects include `local` and `sepolia` chain entries in `compose.json`. Hardhat projects scaffold a `local` network entry (`http://127.0.0.1:8545`, remote accounts) plus a `sepolia` HTTP network, while Foundry projects add a `sepolia` entry under `[rpc_endpoints]` in `foundry.toml`. The local chain remains the default deploy target. + +Hardhat init uses the official Hardhat 3 Ethers/Mocha or Viem/Node test-runner template and requires Node.js 22.13+, npm, and git (the official templates install `forge-std` from GitHub). ### `compose catalog` @@ -141,7 +159,55 @@ Remove manifests list registered facet names: } ``` -Applying a batch validates the resulting source configuration before writing `compose.json`. It checks selector collisions and virtual storage layout compatibility. Install/remove commands do not update `compose.lock` or refresh the deploy script generated by `init`; deployment tooling will consume the configured facet set in a later workflow. +Applying a batch validates the resulting source configuration before writing `compose.json`. It checks selector collisions and virtual storage layout compatibility. Install/remove commands do not update `compose.lock` or the managed deployment artifact; `compose deploy` consumes the configured facet set directly. + +### `compose account` + +Compose account aliases give a deployment signer one stable name across Foundry and Hardhat. They store only a public address and framework-native account reference; Compose never stores private keys or keystore passwords. + +The chain passed to `--chain` must already exist in `compose.json`. Freshly initialized projects include `local` and `sepolia`; add other chain entries before assigning their default account. The generated Sepolia entry is: + +```json +"sepolia": { "rpc": "${SEPOLIA_RPC_URL}", "chainId": 11155111 } +``` + +```bash +# Register an existing Foundry keystore account and use it by default on Sepolia +cast wallet import production-deployer +npx compose account setup deployer --foundry-account production-deployer \ + --address 0x1234567890123456789012345678901234567890 --chain sepolia + +# List configured aliases and defaults +npx compose account list + +# Verify the Foundry keystore entry or Hardhat network signer before deploying +npx compose account check deployer --chain sepolia + +# Remove only the Compose alias; the native keystore entry is left untouched +npx compose account remove deployer +``` + +For Foundry, import a key through Foundry's encrypted keystore with `cast wallet import production-deployer`. Generated Hardhat projects reference the Sepolia signer with `configVariable("SEPOLIA_PRIVATE_KEY")`: + +```ts +import { configVariable } from "hardhat/config"; + +sepolia: { + type: "http", + chainType: "l1", + url: configVariable("SEPOLIA_RPC_URL"), + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], +} +``` + +For a generated Hardhat Sepolia project, store the key with `npx hardhat keystore set SEPOLIA_PRIVATE_KEY`, register its public address, then verify the alias: + +```bash +npx compose account setup deployer --address 0x1234567890123456789012345678901234567890 --chain sepolia +npx compose account check deployer --chain sepolia +``` + +If `hardhat.config.ts` uses a different key variable, store the key using that configured variable instead. `compose account check` verifies the configured signer address before deployment. Interactive Foundry setup can import through Foundry's own prompt; Compose does not read private keys. ### `compose validate` @@ -158,7 +224,26 @@ Exit code non-zero on failure (CI-friendly). ### `compose build` -Compile the project if artifacts are stale or missing. +Compile the project if artifacts are stale or missing. This is a convenience wrapper around the detected framework; generated projects use `npm run build` for the native command. + +### `compose test` + +Run the project's test suite through the detected framework: `forge test` for Foundry projects or `npx hardhat test` for Hardhat projects. Framework output streams directly to the terminal, and a failing suite exits non-zero. This is a convenience wrapper; generated projects use `npm test` for the native command. + +**Options:** +- `--project-root `: start searching for the project from this directory +- `--`: everything after it is forwarded to the framework — use it for filters and reporting flags such as `--match-test`, `--gas-report`, or `--grep` + +```bash +# Run the full suite +compose test + +# Foundry: run one test verbosely +compose test -- --match-test test_Increment -vvv + +# Hardhat: filter by test name +compose test -- --grep "increment" +``` ### `compose rpc` @@ -178,6 +263,49 @@ Inspect a deployed diamond's facets and selectors. **Options:** - `--chain `: chain key from `compose.json` (default: `local`) +### `compose deploy` + +Plan a diamond deployment and generate a reviewable framework artifact. Review it before using `--dry-run` to simulate on a fork or `--broadcast` to deploy it. + +**Options:** +- `--diamond `: diamond definition to deploy; inferred when the project has one, required when it defines several +- `--chain `: chain key from `compose.json` (default: `local`) +- `--rpc-url `: override the RPC endpoint for this deployment only; the chain ID still comes from `compose.json` +- `--account `: signer alias from `compose.json` (defaults to the chain's optional account setting) +- `--instance `: deployment instance name (default: `default`) +- `--project-root `: start searching for the project from this directory +- `--dry-run`: simulate the current managed artifact against a fork of the selected chain without broadcasting or updating `compose.lock`; requires a prepared, unmodified artifact +- `--broadcast`: execute the managed artifact, verify the deployment (including facet selector routing), and write `compose.lock` +- `--redeploy`: plan a fresh deployment when a lock record already exists (the previous one is abandoned, not upgraded). This is a two-step flow: run `compose deploy --redeploy`, review the regenerated artifact, then run `compose deploy --redeploy --broadcast`; `--redeploy` must be repeated on the second command +- `--`: everything after it is forwarded to the framework (`forge script` / `hardhat run`) — use it for signing options like `--private-key` or `--account`; network, build-source, resume, and broadcast-mode flags are reserved for Compose + +Signing stays in the framework; the CLI never handles keys. `compose deploy` writes `script/ComposeDeploy.s.sol` (Foundry) or the reviewable Hardhat Ignition module `ignition/modules/ComposeDeploy.ts`, prints its path, and instructs you to review it. Hardhat's transient runner lives under `.compose/hardhat/` and is generated by Compose; it is not the reviewed deployment artifact. The command never prompts or broadcasts, whether run interactively or non-interactively. When ready, run `compose deploy --broadcast`, repeating `--redeploy` if the artifact was prepared with it. `--broadcast` and `--dry-run` refuse to execute a missing, modified, or stale reviewable artifact; run the same `compose deploy` command without `--broadcast`/`--dry-run` to generate the current artifact, review it, then retry. + +A redeploy always takes two commands. `compose deploy --redeploy` plans the replacement and regenerates the artifact for it; for Hardhat, each redeploy gets a distinct Ignition deployment ID, so the generated module differs. After reviewing it, `compose deploy --redeploy --broadcast` executes that artifact. The flag must be repeated because it participates in plan resolution, not just artifact generation. + +`--dry-run` is a real deployment simulation, not a source preview. Foundry simulates the script against the selected RPC at a pinned fork block without `--broadcast`. Hardhat runs the Ignition module on an isolated EDR fork of the selected chain. If the selected Hardhat signer is not available among the fork's local accounts, Ignition uses a local fork account for simulation; the broadcast still uses the configured signer. Simulation can update local compiler/cache artifacts, but it does not send transactions or change `compose.lock`. For Foundry, specify the intended public sender with `--account ` or `-- --sender
`; simulation does not need or load a private key. Simulation does not verify that a wallet can sign and cannot guarantee the chain state or fees will remain unchanged before a later broadcast. + +Compose uses the RPC URL from `compose.json` unless `--rpc-url` is supplied. The override applies only to this invocation and is used for preflight, deployment, and on-chain verification; it does not change `compose.json`. The plan output shows a redacted endpoint. For Hardhat, Compose overrides only the selected network's URL at runtime, preserving account configuration from `hardhat.config.ts`. The selected Hardhat network must be an HTTP network, and Compose checks its chain ID before deploying. + +Compose selects an account alias from `--account` or the chain's optional `account` default. Hardhat matches the alias's public address against configured network signers; Foundry uses the configured encrypted-keystore account. The deploy plan and success output show the public sender address. Keep framework account-selection flags after `--` only when no Compose alias is selected. + +```bash +compose deploy # plan, write the artifact, review it +compose deploy --redeploy # plan a replacement, regenerate the artifact, review it +compose deploy --dry-run # simulate the reviewed artifact without broadcasting +compose deploy --redeploy --dry-run # simulate a reviewed redeploy artifact +compose deploy --dry-run -- --sender "$DEPLOYER_ADDRESS" # Foundry, when no Compose account alias is selected +compose deploy --broadcast -- --private-key "$DEPLOYER_PRIVATE_KEY" # Foundry; never store the key in compose.json +compose deploy --broadcast # Hardhat; signs with the configured network account +compose deploy --redeploy --broadcast # after review, execute the redeploy artifact +compose deploy --chain sepolia --broadcast # generated projects already define Sepolia +compose deploy --broadcast -- --account deployer +``` + +Foundry broadcast needs a signer: select a Compose alias with `--account`, or pass Foundry-native signing options such as `--private-key`, `--account`, or `--ledger` after `--`. Hardhat uses the signer configured for the selected network in `hardhat.config.ts`. + +A run reports `in sync` and stops when the recorded facet set already matches `compose.json`. This check happens before the artifact is inspected, so `--broadcast` or `--dry-run` without `--redeploy` will not pick up a redeploy artifact; include `--redeploy` again or nothing is deployed. When the composition changed, it prints the add/remove diff and exits non-zero (applying upgrades is a later milestone — `--redeploy` abandons the record and plans a fresh deployment instead). + ## Base Presets Each base preset provides a starting point for common diamond patterns: @@ -244,12 +372,12 @@ my-diamond/ (Custom and extension facets) test/ Diamond.t.sol (Foundry) or Diamond.ts (Hardhat) - script/ - Deploy.s.sol (Foundry) or deploy.ts (Hardhat) compose.json foundry.toml or hardhat.config.ts ``` +`compose deploy` generates a CLI-managed `script/ComposeDeploy.s.sol` (Foundry) or `ignition/modules/ComposeDeploy.ts` (Hardhat) from `compose.json` and records verified deployments in `compose.lock`. + ## Documentation Please see our [documentation website](https://compose.diamonds/docs/) for full documentation. diff --git a/cli/examples/compose.lock.example.json b/cli/examples/compose.lock.example.json index 4ce87044..3ea2f296 100644 --- a/cli/examples/compose.lock.example.json +++ b/cli/examples/compose.lock.example.json @@ -3,42 +3,59 @@ "deployments": { "MyDiamond": { "sepolia": { - "diamond": "0x1234567890abcdef1234567890abcdef12345678", - "facets": { - "DiamondInspectFacet": "0xabcdef1234567890abcdef1234567890abcdef12", - "DiamondUpgradeFacet": "0x9876543210fedcba9876543210fedcba98765432", - "CounterFacet": "0x567890abcdef1234567890abcdef123456789012" + "default": { + "diamond": "0x1234567890abcdef1234567890abcdef12345678", + "facets": { + "DiamondInspectFacet": "0xabcdef1234567890abcdef1234567890abcdef12", + "DiamondUpgradeFacet": "0x9876543210fedcba9876543210fedcba98765432", + "CounterFacet": "0x567890abcdef1234567890abcdef123456789012" + }, + "facetHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b", + "lastSync": "2026-08-03T12:00:00Z", + "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, - "facetHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b", - "lastSync": "2026-08-03T12:00:00Z", - "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" + "staging": { + "diamond": "0x34567890abcdef1234567890abcdef1234567890", + "facets": { + "DiamondInspectFacet": "0xcdef1234567890abcdef1234567890abcdef12", + "DiamondUpgradeFacet": "0x876543210fedcba9876543210fedcba98765432", + "CounterFacet": "0x890abcdef1234567890abcdef1234567890abcd" + }, + "facetHash": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d", + "lastSync": "2026-08-04T09:15:00Z", + "txHash": "0xbcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890a" + } }, "base": { - "diamond": "0x234567890abcdef1234567890abcdef12345678", - "facets": { - "DiamondInspectFacet": "0xbcdef1234567890abcdef1234567890abcdef12", - "DiamondUpgradeFacet": "0x876543210fedcba9876543210fedcba98765432", - "ERC20DataFacet": "0x4567890abcdef1234567890abcdef1234567890", - "ERC20ApproveFacet": "0x67890abcdef1234567890abcdef123456789012", - "ERC20TransferFacet": "0x890abcdef1234567890abcdef1234567890abcd" - }, - "facetHash": "0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c", - "lastSync": "2026-08-02T08:30:00Z", - "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + "default": { + "diamond": "0x234567890abcdef1234567890abcdef12345678", + "facets": { + "DiamondInspectFacet": "0xbcdef1234567890abcdef1234567890abcdef12", + "DiamondUpgradeFacet": "0x876543210fedcba9876543210fedcba98765432", + "ERC20DataFacet": "0x4567890abcdef1234567890abcdef1234567890", + "ERC20ApproveFacet": "0x67890abcdef1234567890abcdef123456789012", + "ERC20TransferFacet": "0x890abcdef1234567890abcdef1234567890abcd" + }, + "facetHash": "0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c", + "lastSync": "2026-08-02T08:30:00Z", + "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + } } }, "ERC721Diamond": { "sepolia": { - "diamond": "0x34567890abcdef1234567890abcdef12345678", - "facets": { - "DiamondInspectFacet": "0xcdef1234567890abcdef1234567890abcdef12", - "ERC721DataFacet": "0x567890abcdef1234567890abcdef1234567890", - "ERC721MintFacet": "0x7890abcdef1234567890abcdef123456789012", - "ERC721BurnFacet": "0x90abcdef1234567890abcdef1234567890abcd" - }, - "facetHash": "0x2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d", - "lastSync": "2026-08-01T15:45:00Z", - "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567891" + "default": { + "diamond": "0x34567890abcdef1234567890abcdef12345678", + "facets": { + "DiamondInspectFacet": "0xcdef1234567890abcdef1234567890abcdef12", + "ERC721DataFacet": "0x567890abcdef1234567890abcdef1234567890", + "ERC721MintFacet": "0x7890abcdef1234567890abcdef123456789012", + "ERC721BurnFacet": "0x90abcdef1234567890abcdef1234567890abcd" + }, + "facetHash": "0x2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d", + "lastSync": "2026-08-01T15:45:00Z", + "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567891" + } } } } diff --git a/cli/package.json b/cli/package.json index d632563a..a7da7d48 100644 --- a/cli/package.json +++ b/cli/package.json @@ -19,7 +19,7 @@ "prepare:lib": "git submodule update --init --recursive" }, "engines": { - "node": ">=20" + "node": ">=22" }, "files": [ "dist/", diff --git a/cli/src/adapters/IFrameworkAdapter/foundryAdapter/accounts.ts b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/accounts.ts new file mode 100644 index 00000000..97a2a819 --- /dev/null +++ b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/accounts.ts @@ -0,0 +1,239 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { getAddress, isAddress, type Hex } from "viem"; +import type { + AccountAddressResolution, + AccountResolutionOptions, + DeploySignerOptions, + SignerAddressOptions, +} from "../types"; +import { runCommandCaptureStdout } from "../../../utils/exec"; +import { FOUNDRY_SIGNING_PASSTHROUGH_OPTIONS } from "../../../utils/args"; + +const EMPTY_ACCOUNT: AccountAddressResolution = { + address: null, + exists: false, + requiresUnlock: false, +}; + +function foundryKeystoreDirectory(): string { + // `forge script --account` resolves names from Foundry's default keystore + // directory. FOUNDRY_DIR controls tool installation, not this account path. + return path.join(os.homedir(), ".foundry", "keystores"); +} + +async function foundryKeystorePath(accountName: string): Promise { + const directory = foundryKeystoreDirectory(); + for (const filename of [accountName, `${accountName}.json`]) { + const filePath = path.join(directory, filename); + try { + await fs.access(filePath); + return filePath; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } + } + return null; +} + +/** Reads a Foundry keystore's plaintext public address without unlocking it. */ +export async function readFoundryAccount(accountName: string): Promise { + const filePath = await foundryKeystorePath(accountName); + if (!filePath) return EMPTY_ACCOUNT; + + let keystore: { address?: unknown }; + try { + keystore = JSON.parse(await fs.readFile(filePath, "utf8")) as { address?: unknown }; + } catch (error) { + throw new Error( + `Unable to read Foundry keystore at ${filePath}: ${(error as Error).message}`, + { cause: error }, + ); + } + + if (typeof keystore.address !== "string") { + return { address: null, exists: true, requiresUnlock: true }; + } + + const address = keystore.address.startsWith("0x") ? keystore.address : `0x${keystore.address}`; + if (!isAddress(address, { strict: false })) { + return { address: null, exists: true, requiresUnlock: true }; + } + + return { address: getAddress(address), exists: true, requiresUnlock: false }; +} + +/** Resolves a Foundry account address, unlocking the keystore when permitted. */ +export async function resolveFoundryAccount( + accountName: string, + projectRoot: string, + options: AccountResolutionOptions = {}, +): Promise { + const stored = await readFoundryAccount(accountName); + if (stored.address || !stored.exists || !options.allowUnlock) return stored; + + options.onUnlock?.(); + const output = await runCommandCaptureStdout( + "cast", + ["wallet", "address", "--account", accountName], + { cwd: projectRoot, forwardStdout: false }, + ); + const address = output.match(/\b0x[0-9a-fA-F]{40}\b/)?.[0]; + if (!address || !isAddress(address, { strict: false })) { + throw new Error(`Foundry did not return a public address for keystore account '${accountName}'.`); + } + + return { address: getAddress(address), exists: true, requiresUnlock: false }; +} + +/** Reads the first value for one of `names` from Foundry passthrough arguments. */ +function readOption(args: string[], names: string[]): string | undefined { + for (let index = 0; index < args.length; index += 1) { + const argument = args[index]; + for (const name of names) { + if (argument === name) { + const value = args[index + 1]; + return value && !value.startsWith("-") ? value : undefined; + } + if (argument.startsWith(`${name}=`)) { + const value = argument.slice(name.length + 1); + return value || undefined; + } + } + } + return undefined; +} + +function toSignerAddress(value: string, label: string): Hex { + if (!isAddress(value, { strict: false })) { + throw new Error(`The ${label} reported an invalid address: ${value}.`); + } + return getAddress(value); +} + +/** Options that do not provide a signer: `--sender` names the sender address and `--password` only unlocks a keystore. */ +const FOUNDRY_NON_SIGNER_OPTIONS = new Set(["--sender", "--password"]); + +/** + * Counts distinct signing sources requested by Foundry passthrough arguments. + * + * Account options accept comma lists and repeated positional values, and each + * signing option occurrence adds a source. Foundry rotates senders across + * broadcast transactions when more than one signer is provided, so any single + * prediction of the diamond transaction signer could be wrong. + * + * @param args - Raw passthrough arguments supplied after `--`. + * @returns The number of signing sources, treating a bare flag as one. + */ +function countFoundrySigningSources(args: string[]): number { + let sources = 0; + for (let index = 0; index < args.length; index += 1) { + const argument = args[index]; + const option = FOUNDRY_SIGNING_PASSTHROUGH_OPTIONS.find( + (name) => argument === name || argument.startsWith(`${name}=`), + ); + if (!option || FOUNDRY_NON_SIGNER_OPTIONS.has(option)) continue; + + if (argument.includes("=")) { + sources += Math.max(1, argument.slice(argument.indexOf("=") + 1).split(",").filter(Boolean).length); + continue; + } + + let consumed = 0; + let next = args[index + 1]; + while (next !== undefined && !next.startsWith("-")) { + consumed += Math.max(1, next.split(",").filter(Boolean).length); + index += 1; + next = args[index + 1]; + } + sources += Math.max(1, consumed); + } + return sources; +} + +/** + * Resolves the signer a Foundry deploy command will use. + * + * A Compose account supplies both the keystore name and public address. + * Without one, Foundry uses an explicit `--sender`, or derives the sender from + * a named `--account` keystore. When the passthrough requests more than one + * signing source, Foundry rotates senders across transactions and no single + * signer can be predicted, so the check is skipped rather than guessed. + * + * @param options - Deploy target, selected account, and framework passthrough. + * @returns The expected signer, or null when it cannot be predicted with + * certainty (multiple signers, an opaque method, or an interactive unlock). + */ +export async function resolveFoundryDeploySigner( + options: DeploySignerOptions, +): Promise { + if (options.account) return getAddress(options.account.address); + + // A wrong prediction here false-fails the post-broadcast signer check after + // gas was spent and would leave compose.lock unrecorded; null skips it. + if (countFoundrySigningSources(options.passthrough) > 1) return null; + + const sender = readOption(options.passthrough, ["--sender"]); + if (sender) return toSignerAddress(sender, "Foundry sender"); + + const accountName = readOption(options.passthrough, ["--account", "--accounts"]); + if (!accountName) return null; + + let addresses: string[]; + try { + addresses = await listFoundrySignerAddresses({ + projectRoot: options.projectRoot, + chainKey: options.chainKey, + rpcUrl: options.rpcUrl, + chainId: options.chainId, + accountName: accountName.split(",")[0]?.trim(), + allowUnlock: false, + }); + } catch { + // Foundry may need an interactive unlock before it exposes the address. + return null; + } + + const [address] = addresses; + return address ? getAddress(address) : null; +} + +/** Lists the Foundry signer address for a named keystore account. */ +export async function listFoundrySignerAddresses( + options: SignerAddressOptions, +): Promise { + if (!options.accountName) return []; + + const resolution = await resolveFoundryAccount(options.accountName, options.projectRoot, { + allowUnlock: options.allowUnlock, + onUnlock: options.onUnlock, + }); + if (resolution.requiresUnlock) { + throw new Error( + `Foundry keystore account '${options.accountName}' needs to be unlocked to verify its public address. Run this command interactively or set ETH_PASSWORD to a Foundry password-file path.`, + ); + } + + return resolution.address ? [resolution.address] : []; +} + +/** Imports a key into Foundry's encrypted keystore and returns its public address. */ +export async function importFoundryAccount( + projectRoot: string, + accountName: string, +): Promise { + const output = await runCommandCaptureStdout("cast", [ + "wallet", + "import", + accountName, + "--interactive", + ], { + cwd: projectRoot, + }); + const importedAddress = output.match(/\bAddress:\s*(0x[0-9a-fA-F]{40})\b/i)?.[1]; + if (importedAddress) return importedAddress; + + const stored = await readFoundryAccount(accountName); + return stored.address; +} diff --git a/cli/src/adapters/IFrameworkAdapter/foundryAdapter/adapter.ts b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/adapter.ts index e28a2c9d..454e5229 100644 --- a/cli/src/adapters/IFrameworkAdapter/foundryAdapter/adapter.ts +++ b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/adapter.ts @@ -1,12 +1,20 @@ import fs from "node:fs/promises"; import path from "node:path"; +import type { Hex } from "viem"; import { ComposeContext } from "../../../context/types"; +import { IFrameworkAdapter } from "../interface"; import { + BroadcastTransaction, ConfigOptions, - IFrameworkAdapter, + DeployCommand, + DeployCommandOptions, + DeploySignerOptions, + DeployToolbox, + FrameworkCommand, SolidityAstSource, -} from "../interface"; -import { writeFileIfMissing } from "../../../utils/files"; + TestCommandOptions, +} from "../types"; +import { toPosixPath, toProjectRelativePath, writeFileIfMissing } from "../../../utils/files"; import { runCommand } from "../../../utils/exec"; import { composePackageSubpath, @@ -14,9 +22,47 @@ import { } from "../../../utils/soliditySources"; import { CLI_ROOT } from "../../../utils/cliRoot"; import { isSourceUnitAst, listJsonFiles, uniqueAstSources } from "../../../utils/solidityAst"; -import { ensureTomlSectionSettings } from "./helpers"; +import { yellow } from "../../../utils/terminal"; +import { ensureGitignoreEntries } from "../../../utils/gitignore"; +import { + buildFoundryPackageJson, + ensureTomlSectionSettings, +} from "./helpers"; +import { + importFoundryAccount, + listFoundrySignerAddresses, + readFoundryAccount, + resolveFoundryAccount, + resolveFoundryDeploySigner, +} from "./accounts"; /** Framework adapter for Foundry-based Diamond projects. */ +const MANAGED_SCRIPT_NAME = "ComposeDeploy.s.sol"; +const MANAGED_SCRIPT_CONTRACT = "ComposeDeployScript"; + +/** + * Installs the generated project's npm dev dependencies (the Compose CLI). + * + * Foundry projects build and test without npm, so a failed install only warns: + * the user can rerun `npm install` later to get the local `npx compose` binary. + * + * @param projectRoot - Absolute path of the generated project. + */ +async function installNpmDependencies(projectRoot: string): Promise { + try { + await runCommand("npm", ["install"], { cwd: projectRoot }); + } catch { + console.log(yellow( + "Could not install npm dependencies. Run `npm install` inside the project " + + "to use the local Compose CLI with `npx compose`.", + )); + } +} + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + const adapter: IFrameworkAdapter = { getContractSourceRoot(projectRoot: string): string { return path.join(projectRoot, "src"); @@ -100,6 +146,12 @@ const adapter: IFrameworkAdapter = { await fs.mkdir(path.join(root, "test"), { recursive: true }); await fs.mkdir(path.join(root, "script"), { recursive: true }); + + await fs.writeFile( + path.join(root, "package.json"), + buildFoundryPackageJson(String(ctx.param.projectName ?? "my-diamond")), + "utf8", + ); }, async writeConfig(ctx: ComposeContext, opts: ConfigOptions): Promise { @@ -113,13 +165,15 @@ const adapter: IFrameworkAdapter = { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } - const updatedFoundryToml = ensureTomlSectionSettings(foundryToml, "profile.default", { + const profileFoundryToml = ensureTomlSectionSettings(foundryToml, "profile.default", { solc: `"${opts.compilerVersion}"`, optimizer: "true", }); + const updatedFoundryToml = ensureTomlSectionSettings(profileFoundryToml, "rpc_endpoints", { + sepolia: '"${SEPOLIA_RPC_URL}"', + }); const remappings = "@perfect-abstractions/compose/=lib/Compose/src/\n"; - const gitignore = "out/\ncache/\n"; let readme: string; try { @@ -134,8 +188,196 @@ const adapter: IFrameworkAdapter = { await fs.writeFile(foundryTomlPath, updatedFoundryToml, "utf8"); } await writeFileIfMissing(path.join(root, "remappings.txt"), remappings); - await writeFileIfMissing(path.join(root, ".gitignore"), gitignore); + await writeFileIfMissing( + path.join(root, ".env.example"), + [ + "# Sepolia RPC endpoint used by `compose deploy --chain sepolia`.", + "# Sign with a Foundry keystore account or pass --private-key after `--`.", + "SEPOLIA_RPC_URL=", + "", + ].join("\n"), + ); + + const gitignorePath = path.join(root, ".gitignore"); + let gitignore = "out/\ncache/\n"; + try { + gitignore = await fs.readFile(gitignorePath, "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } + // `.compose/` is reserved for Compose-owned runtime files; Foundry keeps + // its deploy script in `script/` because that artifact is reviewed and tracked. + const updatedGitignore = ensureGitignoreEntries(gitignore, ["node_modules/", ".compose/"]); + if (updatedGitignore !== gitignore) { + await fs.writeFile(gitignorePath, updatedGitignore, "utf8"); + } + await fs.writeFile(path.join(root, "README.md"), readme, "utf8"); + + if (opts.installDeps) { + await installNpmDependencies(root); + } + }, + + supportsAccountImport: true, + + readAccountAddress(_projectRoot: string, accountName: string) { + return readFoundryAccount(accountName); + }, + + resolveAccountAddress( + projectRoot: string, + accountName: string, + options, + ) { + return resolveFoundryAccount(accountName, projectRoot, options); + }, + + listSignerAddresses(options) { + return listFoundrySignerAddresses(options); + }, + + resolveDeploySigner(options: DeploySignerOptions) { + return resolveFoundryDeploySigner(options); + }, + + importAccount(projectRoot: string, accountName: string) { + return importFoundryAccount(projectRoot, accountName); + }, + + assertSupportedProject(_projectRoot: string): void { + // Foundry projects are validated by the framework's own compiler and tests. + }, + + async getDeployToolbox(_projectRoot: string): Promise { + return null; + }, + + getManagedDeployScriptPath(projectRoot: string): string { + return path.join(projectRoot, "script", MANAGED_SCRIPT_NAME); + }, + + getManagedDeployRunnerPath(): null { + return null; + }, + + getManagedDeployResultPath(): string | null { + // Foundry records deployments in the run broadcast, not a result file. + return null; + }, + + createDeployCommand(opts: DeployCommandOptions): DeployCommand { + const relativeScriptPath = toPosixPath(path.relative(opts.projectRoot, opts.scriptPath)); + const simulating = opts.mode === "simulate"; + return { + command: "forge", + args: [ + "script", + `${relativeScriptPath}:${MANAGED_SCRIPT_CONTRACT}`, + "--rpc-url", + opts.rpcUrl, + ...(simulating && opts.forkBlockNumber !== undefined + ? ["--fork-block-number", String(opts.forkBlockNumber)] + : []), + ...(!simulating && opts.account?.foundryAccount + ? ["--account", opts.account.foundryAccount] + : []), + ...(opts.account ? ["--sender", opts.account.address] : []), + ...(!simulating ? ["--broadcast"] : []), + ...opts.passthrough, + ], + }; + }, + + createTestCommand(opts: TestCommandOptions): FrameworkCommand { + return { + command: "forge", + args: ["test", ...opts.passthrough], + }; + }, + + async readDeployedBytecode( + projectRoot: string, + sourcePath: string, + contractName: string, + ): Promise { + const artifactPath = path.join( + projectRoot, + "out", + path.basename(sourcePath), + `${contractName}.json`, + ); + try { + const artifact = JSON.parse(await fs.readFile(artifactPath, "utf8")) as { + deployedBytecode?: { object?: unknown }; + }; + const object = artifact.deployedBytecode?.object; + return typeof object === "string" && object.length > 2 ? (object as Hex) : undefined; + } catch { + return undefined; + } + }, + + async readBroadcastTransactions( + projectRoot: string, + scriptPath: string, + chainId: number, + ): Promise { + const broadcastPath = path.join( + projectRoot, + "broadcast", + path.basename(scriptPath), + String(chainId), + "run-latest.json", + ); + const displayPath = toProjectRelativePath(projectRoot, broadcastPath); + + let content: string; + try { + content = await fs.readFile(broadcastPath, "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; + throw new Error(`Unable to read the Foundry broadcast at ${displayPath}: ${(error as Error).message}`, { + cause: error, + }); + } + + let raw: unknown; + try { + raw = JSON.parse(content) as unknown; + } catch (error) { + throw new Error(`Unable to parse the Foundry broadcast at ${displayPath}: ${(error as Error).message}`, { + cause: error, + }); + } + if (!isRecord(raw) || !Array.isArray(raw.transactions)) { + throw new Error(`The Foundry broadcast at ${displayPath} is missing a transactions array.`); + } + + const deployments: BroadcastTransaction[] = []; + for (const transaction of raw.transactions) { + if (!isRecord(transaction)) continue; + const transactionType = transaction.transactionType; + if ( + typeof transactionType === "string" + && transactionType !== "CREATE" + && transactionType !== "CREATE2" + ) { + continue; + } + + deployments.push({ + contractAddress: typeof transaction.contractAddress === "string" ? transaction.contractAddress : null, + contractName: typeof transaction.contractName === "string" ? transaction.contractName : null, + txHash: typeof transaction.hash === "string" ? transaction.hash : null, + ...(typeof transaction.from === "string" + ? { from: transaction.from } + : isRecord(transaction.transaction) && typeof transaction.transaction.from === "string" + ? { from: transaction.transaction.from } + : {}), + }); + } + return deployments; }, }; diff --git a/cli/src/adapters/IFrameworkAdapter/foundryAdapter/helpers.ts b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/helpers.ts index 658dcb9f..c9a40d31 100644 --- a/cli/src/adapters/IFrameworkAdapter/foundryAdapter/helpers.ts +++ b/cli/src/adapters/IFrameworkAdapter/foundryAdapter/helpers.ts @@ -1,3 +1,6 @@ +import { withComposeProjectScripts } from "../../../modules/init/projectScripts"; +import { CLI_DEV_DEPENDENCY_VERSION, CLI_PACKAGE_NAME } from "../../../utils/metadata"; + /** Adds missing settings to a TOML section without overwriting existing values. */ export function ensureTomlSectionSettings( content: string, @@ -27,3 +30,32 @@ export function ensureTomlSectionSettings( lines.splice(sectionEnd, 0, ...missingSettings); return `${lines.join("\n")}\n`; } + +/** + * Builds the `package.json` written into generated Foundry projects. + * + * The manifest exposes native Foundry commands alongside the Compose + * validate workflow, and declares the Compose CLI as a dev dependency so + * project scripts run the local CLI instead of a global install. + * + * @param projectName - Name recorded in the generated package manifest. + * @returns Pretty-printed package.json content with a trailing newline. + */ +export function buildFoundryPackageJson(projectName: string): string { + const packageJson = { + name: projectName, + version: "0.1.0", + private: true, + description: "Diamond project generated by Compose CLI", + scripts: withComposeProjectScripts({ + build: "forge build", + test: "forge test", + fmt: "forge fmt", + }), + devDependencies: { + [CLI_PACKAGE_NAME]: CLI_DEV_DEPENDENCY_VERSION, + }, + }; + + return `${JSON.stringify(packageJson, null, 2)}\n`; +} diff --git a/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/accounts.ts b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/accounts.ts new file mode 100644 index 00000000..a5cbbf6d --- /dev/null +++ b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/accounts.ts @@ -0,0 +1,184 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { getAddress } from "viem"; +import type { SignerAddressOptions } from "../types"; +import { runCommandCaptureStdout } from "../../../utils/exec"; +import { atomicWriteFile, toProjectRelativePath } from "../../../utils/files"; +import { loadTemplate } from "../../../utils/codegen"; +import { + composeRuntimeDir, + ensureComposeRuntimeDir, +} from "../../../utils/composeRuntime"; +import { assertHardhat3, detectHardhatToolbox } from "./helpers"; + +function escapeRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +/** + * Conservatively extracts a simple object-property block from the generated + * Hardhat config shape. Unsupported config syntax returns null rather than + * guessing which key variable a network uses. + */ +function extractPropertyBlocks(source: string, propertyName: string): Array { + const escapedName = escapeRegExp(propertyName); + const propertyPattern = new RegExp( + `^[\\t ]*(?:${escapedName}|["']${escapedName}["'])\\s*:\\s*\\{`, + "gm", + ); + const matches = [...source.matchAll(propertyPattern)]; + return matches.map((propertyMatch) => { + if (propertyMatch.index === undefined) return null; + const openBrace = source.indexOf("{", propertyMatch.index); + const closeBrace = findMatchingBrace(source, openBrace); + return closeBrace === null ? null : source.slice(openBrace + 1, closeBrace); + }); +} + +function findMatchingBrace(source: string, openBrace: number): number | null { + let depth = 0; + let quote: "'" | "\"" | "`" | null = null; + let lineComment = false; + let blockComment = false; + let escaped = false; + + for (let index = openBrace; index < source.length; index += 1) { + const character = source[index] ?? ""; + const next = source[index + 1] ?? ""; + + if (lineComment) { + if (character === "\n") lineComment = false; + continue; + } + if (blockComment) { + if (character === "*" && next === "/") { + blockComment = false; + index += 1; + } + continue; + } + if (quote) { + if (escaped) { + escaped = false; + } else if (character === "\\") { + escaped = true; + } else if (character === quote) { + quote = null; + } + continue; + } + + if (character === "/" && next === "/") { + lineComment = true; + index += 1; + continue; + } + if (character === "/" && next === "*") { + blockComment = true; + index += 1; + continue; + } + // A regex literal or division expression is outside the simple generated + // config shape this helper supports; avoid returning a guessed block. + if (character === "/") return null; + if (character === "'" || character === "\"" || character === "`") { + quote = character; + continue; + } + if (character === "{") depth += 1; + if (character === "}") { + depth -= 1; + if (depth === 0) return index; + } + } + + return null; +} + +/** + * Reads the selected network's one literal `configVariable` signer reference. + * Returns null for custom or ambiguous Hardhat config so account setup can + * display safe generic guidance instead of suggesting the wrong key name. + */ +export async function readHardhatAccountKeyVariable( + projectRoot: string, + chainKey: string, +): Promise { + let config: string; + try { + config = await fs.readFile(path.join(projectRoot, "hardhat.config.ts"), "utf8"); + } catch { + return null; + } + + const networksBlocks = extractPropertyBlocks(config, "networks"); + if (networksBlocks.length === 0 || networksBlocks.some((block) => block === null)) return null; + + let selectedNetworkFound = false; + let selectedVariable: string | null = null; + for (const networks of networksBlocks) { + const networkBlocks = extractPropertyBlocks(networks ?? "", chainKey); + if (networkBlocks.length === 0) continue; + if (networkBlocks.length !== 1 || networkBlocks[0] === null) return null; + + selectedNetworkFound = true; + const accountMatches = [...networkBlocks[0].matchAll(/^[\t ]*accounts\s*:\s*\[([^\]]*)\]/gm)]; + if (accountMatches.length !== 1) { + selectedVariable = null; + continue; + } + + const accountExpression = accountMatches[0]?.[1]?.trim() ?? ""; + const variable = accountExpression.match( + /^configVariable\s*\(\s*(["'])([A-Za-z_][A-Za-z0-9_]*)\1\s*\)$/, + ); + selectedVariable = variable?.[2] ?? null; + } + + return selectedNetworkFound ? selectedVariable : null; +} + +/** Lists the signer addresses a Hardhat project configures for the target chain. */ +export async function listHardhatSignerAddresses( + options: SignerAddressOptions, +): Promise { + const { projectRoot, chainKey, rpcUrl, chainId } = options; + assertHardhat3(projectRoot); + const toolbox = await detectHardhatToolbox(projectRoot); + const probePath = path.join(composeRuntimeDir(projectRoot, "hardhat"), "account-probe.ts"); + const accountRead = toolbox === "viem" + ? 'const addresses = (await connection.viem.getWalletClients()).map((wallet) => wallet.account.address);' + : 'const addresses = await Promise.all((await connection.ethers.getSigners()).map((signer) => signer.getAddress()));'; + const template = await loadTemplate("deploy", "compose-hardhat-account-probe.ts"); + const script = template + .split("{{CHAIN_KEY}}").join(JSON.stringify(chainKey)) + .split("{{CHAIN_ID}}").join(String(chainId)) + .split("{{ACCOUNT_READ}}").join(accountRead); + + await ensureComposeRuntimeDir(projectRoot, "hardhat"); + await atomicWriteFile(probePath, script); + + // The probe only reads network configuration; it must not trigger a build. + // Deploy builds once under the production profile and relies on those + // artifacts, and listing signers must work before the project is built. + // The profile flag must match the deploy command because config-override + // profiles can change network accounts, which would otherwise resolve a + // different signer here than the broadcast actually uses. + // The marker is consumed programmatically; do not echo the full signer list. + const output = await runCommandCaptureStdout( + "npx", + ["hardhat", "--build-profile", "production", "run", "--no-compile", toProjectRelativePath(projectRoot, probePath), "--network", chainKey], + { + cwd: projectRoot, + env: { COMPOSE_DEPLOY_RPC_URL: rpcUrl }, + forwardStdout: false, + }, + ); + const marker = output.split(/\r?\n/).find((line) => line.startsWith("COMPOSE_ACCOUNT_ADDRESSES:")); + if (!marker) throw new Error("Hardhat did not report its configured signer addresses."); + const parsed = JSON.parse(marker.slice("COMPOSE_ACCOUNT_ADDRESSES:".length)) as unknown; + if (!Array.isArray(parsed) || !parsed.every((address) => typeof address === "string")) { + throw new Error("Hardhat returned an invalid signer address list."); + } + return parsed.map((address) => getAddress(address)); +} diff --git a/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/adapter.ts b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/adapter.ts index 312bcdf0..08d41e90 100644 --- a/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/adapter.ts +++ b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/adapter.ts @@ -1,30 +1,125 @@ import fs from "node:fs/promises"; import path from "node:path"; +import { getAddress, type Hex } from "viem"; import { ComposeContext } from "../../../context/types"; +import { IFrameworkAdapter } from "../interface"; import { + BroadcastTransaction, ConfigOptions, - IFrameworkAdapter, + DeployCommand, + DeployCommandOptions, + DeploySignerOptions, + DeployToolbox, + FrameworkCommand, SolidityAstSource, -} from "../interface"; -import { writeFileIfMissing } from "../../../utils/files"; + TestCommandOptions, +} from "../types"; +import { toPosixPath, writeFileIfMissing } from "../../../utils/files"; import { runCommand } from "../../../utils/exec"; +import { CLI_DEV_DEPENDENCY_VERSION, CLI_PACKAGE_NAME } from "../../../utils/metadata"; import { composePackageSubpath, isComposePackagePath, } from "../../../utils/soliditySources"; import { ScaffoldingModule } from "../../../modules/scaffolding/module"; import { CLI_ROOT } from "../../../utils/cliRoot"; +import { ensureGitignoreEntries } from "../../../utils/gitignore"; import { isSourceUnitAst, listJsonFiles, uniqueAstSources } from "../../../utils/solidityAst"; -import { resolveHardhatAstSourcePath } from "./helpers"; +import { getHardhatInitTemplate, HARDHAT_INIT_VERSION } from "../../../modules/init/frameworkDeps"; +import { withComposeProjectScripts } from "../../../modules/init/projectScripts"; +import { + assertHardhat3, + detectHardhatToolbox, + resolveHardhatArtifactSourceName, + resolveHardhatAstSourcePath, +} from "./helpers"; +import { listHardhatSignerAddresses, readHardhatAccountKeyVariable } from "./accounts"; +import { assertHardhatNodeVersion } from "../../../utils/nodeVersion"; /** Framework adapter for Hardhat-based Diamond projects. */ +const MANAGED_RUNNER_RELATIVE_PATH = path.join(".compose", "hardhat", "ignition-runner.ts"); + +/** Managed deploy result captured by the transient runner inside Compose's runtime directory. */ +const MANAGED_RESULT_RELATIVE_PATH = path.join(".compose", "hardhat", "deploy-result.json"); + +const HARDHAT_TEMPLATE_SAMPLE_FILES = [ + path.join("contracts", "Counter.sol"), + path.join("contracts", "Counter.t.sol"), + path.join("test", "Counter.ts"), + path.join("ignition", "modules", "Counter.ts"), + path.join("scripts", "send-op-tx.ts"), +]; + +function updatePackageManifest( + packageJson: Record, + projectName: string, +): Record { + const currentDependencies = typeof packageJson.dependencies === "object" && packageJson.dependencies !== null + ? packageJson.dependencies as Record + : {}; + const currentDevDependencies = typeof packageJson.devDependencies === "object" && packageJson.devDependencies !== null + ? packageJson.devDependencies as Record + : {}; + const currentScripts = typeof packageJson.scripts === "object" && packageJson.scripts !== null + ? packageJson.scripts as Record + : {}; + const safeName = projectName.toLowerCase().replace(/[^a-z0-9._-]+/g, "-"); + + return { + ...packageJson, + name: safeName, + type: "module", + engines: { + ...((typeof packageJson.engines === "object" && packageJson.engines !== null) + ? packageJson.engines as Record + : {}), + node: ">=22.13.0", + }, + dependencies: { + ...currentDependencies, + "@perfect-abstractions/compose": "latest", + }, + devDependencies: { + ...currentDevDependencies, + [CLI_PACKAGE_NAME]: CLI_DEV_DEPENDENCY_VERSION, + }, + scripts: withComposeProjectScripts({ + ...currentScripts, + build: currentScripts.build ?? "hardhat build", + test: currentScripts.test ?? "hardhat test", + }), + }; +} + +/** Command used to invoke Hardhat's non-interactive official project template. */ +export function createHardhatInitCommand(toolbox: string): FrameworkCommand { + return { + command: "npx", + args: [ + "--yes", + `--package=hardhat@${HARDHAT_INIT_VERSION}`, + "hardhat", + "--init", + "--template", + getHardhatInitTemplate(toolbox), + ], + }; +} + +/** Removes only the known demo files shipped by Hardhat's selected starter templates. */ +export async function removeHardhatTemplateSamples(projectRoot: string): Promise { + await Promise.all(HARDHAT_TEMPLATE_SAMPLE_FILES.map((relativePath) => + fs.rm(path.join(projectRoot, relativePath), { force: true }), + )); +} + const adapter: IFrameworkAdapter = { getContractSourceRoot(projectRoot: string): string { return path.join(projectRoot, "contracts"); }, getScriptRoot(projectRoot: string): string { - return path.join(projectRoot, "scripts"); + return path.join(projectRoot, "ignition", "modules"); }, getTestRoot(projectRoot: string): string { @@ -36,7 +131,8 @@ const adapter: IFrameworkAdapter = { }, async compile(projectRoot: string): Promise { - await runCommand("npx", ["hardhat", "compile"], { cwd: projectRoot }); + assertHardhat3(projectRoot); + await runCommand("npx", ["hardhat", "build", "--build-profile", "production"], { cwd: projectRoot }); }, async resolveSoliditySourcePath(ctx: ComposeContext, sourcePath: string): Promise { @@ -58,6 +154,7 @@ const adapter: IFrameworkAdapter = { async compileAst(ctx: ComposeContext, sourcePaths: string[]): Promise { const root = String(ctx.param.projectRoot ?? ""); + assertHardhat3(root); await Promise.all(sourcePaths.map((sourcePath) => fs.access(sourcePath))); await runCommand("npx", ["hardhat", "compile", "--force"], { cwd: root }); @@ -89,124 +186,165 @@ const adapter: IFrameworkAdapter = { return uniqueSources; }, + /** + * Adds package facet sources to the Compose `npmFilesToBuild` overlay in + * hardhat.config.ts so Hardhat compiles them. Returns a revert closure when + * the config changed, or null when nothing needed adding. + */ + async ensurePackageFacetsCompilable( + projectRoot: string, + packageSpecifiers: string[], + ): Promise<(() => Promise) | null> { + if (packageSpecifiers.length === 0) return null; + const configPath = path.join(projectRoot, "hardhat.config.ts"); + let original: string; + try { + original = await fs.readFile(configPath, "utf8"); + } catch { + throw new Error(`Cannot update solidity.npmFilesToBuild: ${configPath} is not readable.`); + } + + const guidance = `Add ${packageSpecifiers.map((specifier) => `"${specifier}"`).join(", ")} to solidity.npmFilesToBuild in hardhat.config.ts, then install again.`; + const marker = /const composeNpmFilesToBuild = (\[[\s\S]*?\]);/.exec(original); + if (!marker) throw new Error(`Cannot update the Compose overlay in hardhat.config.ts. ${guidance}`); + + let listed: unknown; + try { + listed = JSON.parse(marker[1]); + } catch { + throw new Error(`Cannot update the Compose overlay in hardhat.config.ts. ${guidance}`); + } + if (!Array.isArray(listed) || !listed.every((entry) => typeof entry === "string")) { + throw new Error(`Cannot update the Compose overlay in hardhat.config.ts. ${guidance}`); + } + + const merged = [...new Set([...(listed as string[]), ...packageSpecifiers])]; + if (merged.length === listed.length) return null; + + const updated = original.replace( + marker[0], + `const composeNpmFilesToBuild = ${JSON.stringify(merged)};`, + ); + await fs.writeFile(configPath, updated, "utf8"); + return async () => { + await fs.writeFile(configPath, original, "utf8"); + }; + }, + async initProject(ctx: ComposeContext): Promise { + assertHardhatNodeVersion(); const root = String(ctx.param.projectRoot ?? ""); - const projectName = String(ctx.param.projectName ?? "my-diamond"); const toolbox = String(ctx.param.toolbox ?? "ethers"); + const command = createHardhatInitCommand(toolbox); + await runCommand(command.command, command.args, { cwd: root }); - const devDeps: Record = - toolbox === "viem" - ? { - hardhat: "^3.8.0", - "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", - } - : { - hardhat: "^3.8.0", - "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0", - }; - - const packageJson = { - name: projectName, - version: "0.1.0", - description: "Diamond project generated by Compose CLI", - type: "module", - main: "index.js", - scripts: { - build: "npx hardhat compile", - test: "npx hardhat test", - }, - keywords: ["solidity", "ethereum", "smart-contracts", "diamonds", "ERC-2535"], - author: "", - license: "MIT", - dependencies: { - "@perfect-abstractions/compose": "latest", - }, - devDependencies: devDeps, - }; - - await fs.writeFile(path.join(root, "package.json"), JSON.stringify(packageJson, null, 2)); + // Compose replaces these sample contracts and tests with its selected + // facets and generated diamond test, while keeping the official template's + // project config, plugins, and directory structure. + await removeHardhatTemplateSamples(root); }, async writeConfig(ctx: ComposeContext, opts: ConfigOptions): Promise { const root = String(ctx.param.projectRoot ?? ""); - const toolbox = String(ctx.param.toolbox ?? "ethers"); const selectedFacets = ScaffoldingModule.getSelectedFacets(ctx); const packageFacetPaths = selectedFacets .map((facet) => facet.entry.path) .filter(isComposePackagePath); - const npmFilesToBuild = packageFacetPaths.length > 0 - ? ` npmFilesToBuild: ${JSON.stringify(packageFacetPaths, null, 4).replace(/\n/g, "\n ")},\n` - : ""; - - const toolboxImport = - toolbox === "viem" - ? `import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";` - : `import hardhatToolboxMochaEthers from "@nomicfoundation/hardhat-toolbox-mocha-ethers";`; - const toolboxPlugin = toolbox === "viem" ? "hardhatToolboxViem" : "hardhatToolboxMochaEthers"; - - const hardhatConfig = `import { defineConfig } from "hardhat/config"; -${toolboxImport} + const packageJsonPath = path.join(root, "package.json"); + const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as Record; + await fs.writeFile( + packageJsonPath, + `${JSON.stringify(updatePackageManifest(packageJson, opts.projectName), null, 2)}\n`, + "utf8", + ); + + // Keep Hardhat's official config in the single config file, then append a + // Compose overlay so its plugins and network settings remain intact. + const officialConfigPath = path.join(root, "hardhat.config.ts"); + const officialConfig = await fs.readFile(officialConfigPath, "utf8"); + const defaultConfigExport = /export\s+default\s+defineConfig\s*\(\s*\{/g; + const defaultConfigExports = officialConfig.match(defaultConfigExport) ?? []; + if (defaultConfigExports.length !== 1) { + throw new Error("Hardhat's official config template did not contain the expected default defineConfig export."); + } + const baseConfigSource = officialConfig.replace( + defaultConfigExport, + "const baseConfig = defineConfig({", + ); + const composeConfig = `${baseConfigSource.trimEnd()} + +const baseSolidity = typeof baseConfig.solidity === "object" && baseConfig.solidity !== null + ? baseConfig.solidity + : {}; +const baseProfiles = baseSolidity.profiles ?? {}; +const defaultProfile = baseProfiles.default ?? {}; +const productionProfile = baseProfiles.production ?? {}; +const composeNpmFilesToBuild = ${JSON.stringify(packageFacetPaths)}; export default defineConfig({ - plugins: [${toolboxPlugin}], + ...baseConfig, solidity: { -${npmFilesToBuild} profiles: { + ...baseSolidity, + npmFilesToBuild: [...new Set([...(baseSolidity.npmFilesToBuild ?? []), ...composeNpmFilesToBuild])], + profiles: { + ...baseProfiles, default: { - version: "${opts.compilerVersion}", + ...defaultProfile, + version: ${JSON.stringify(opts.compilerVersion)}, settings: { - optimizer: { - enabled: true, - }, + ...defaultProfile.settings, + optimizer: { ...defaultProfile.settings?.optimizer, enabled: true }, }, }, production: { - version: "${opts.compilerVersion}", + ...productionProfile, + version: ${JSON.stringify(opts.compilerVersion)}, settings: { - optimizer: { - enabled: true, - }, + ...productionProfile.settings, + optimizer: { ...productionProfile.settings?.optimizer, enabled: true, runs: 200 }, }, }, }, }, - paths: { - sources: "./contracts", - tests: "./test", - cache: "./cache", - artifacts: "./artifacts", + networks: { + ...baseConfig.networks, + local: { + type: "http", + chainType: "l1", + url: "http://127.0.0.1:8545", + accounts: "remote", + }, + sepolia: { + type: "http", + chainType: "l1", + url: configVariable("SEPOLIA_RPC_URL"), + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], + }, }, }); `; + await fs.writeFile(officialConfigPath, composeConfig, "utf8"); - await fs.writeFile(path.join(root, "hardhat.config.ts"), hardhatConfig); - - const tsconfig = `{ - "compilerOptions": { - "target": "ES2020", - "module": "commonjs", - "lib": ["ES2020"], - "outDir": "./dist", - "rootDir": "./contracts", - "strict": true, - "esModuleInterop": true, - "skipLibCheck": true, - "forceConsistentCasingInFileNames": true - }, - "include": ["contracts/**/*.ts"], - "exclude": ["node_modules", "dist"] -}`; - - await fs.writeFile(path.join(root, "tsconfig.json"), tsconfig); - - const gitignore = `node_modules/ -.cache/ -artifacts/ -dist/ -.env -`; - - await fs.writeFile(path.join(root, ".gitignore"), gitignore); + const gitignorePath = path.join(root, ".gitignore"); + let gitignore = ""; + try { + gitignore = await fs.readFile(gitignorePath, "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } + await fs.writeFile( + gitignorePath, + ensureGitignoreEntries(gitignore, [ + "node_modules/", + "cache/", + "artifacts/", + "dist/", + ".env", + ".compose/", + ]), + "utf8", + ); let readme: string; try { @@ -216,14 +354,147 @@ dist/ } catch { readme = `# ${opts.projectName}\n\nGenerated by compose init\n`; } - await writeFileIfMissing(path.join(root, "README.md"), readme); + await fs.writeFile(path.join(root, "README.md"), readme, "utf8"); + await writeFileIfMissing( + path.join(root, ".env.example"), + [ + "# Sepolia RPC endpoint used by `compose deploy --chain sepolia`.", + "SEPOLIA_RPC_URL=", + "# Deployment signer. Prefer `npx hardhat keystore set SEPOLIA_PRIVATE_KEY`.", + "SEPOLIA_PRIVATE_KEY=", + "", + ].join("\n"), + ); await fs.mkdir(path.join(root, "test"), { recursive: true }); + await fs.mkdir(path.join(root, "scripts"), { recursive: true }); if (opts.installDeps) { await runCommand("npm", ["install"], { cwd: root }); } }, + + supportsAccountImport: false, + + async readAccountAddress(_projectRoot: string, _accountName: string) { + return { address: null, exists: false, requiresUnlock: false }; + }, + + async resolveAccountAddress( + _projectRoot: string, + _accountName: string, + _options, + ) { + return { address: null, exists: false, requiresUnlock: false }; + }, + + listSignerAddresses(options) { + return listHardhatSignerAddresses(options); + }, + + getAccountKeyVariable(projectRoot, chainKey) { + return readHardhatAccountKeyVariable(projectRoot, chainKey); + }, + + async resolveDeploySigner(options: DeploySignerOptions): Promise { + if (options.account) return getAddress(options.account.address); + const [address] = await listHardhatSignerAddresses(options); + return address ? getAddress(address) : null; + }, + + async importAccount(_projectRoot: string, _accountName: string): Promise { + throw new Error( + "Hardhat accounts are configured in hardhat.config.ts; Compose does not import keys.", + ); + }, + + assertSupportedProject(projectRoot: string): void { + assertHardhat3(projectRoot); + }, + + async getDeployToolbox(projectRoot: string): Promise { + return detectHardhatToolbox(projectRoot); + }, + + getManagedDeployScriptPath(projectRoot: string): string { + return path.join(projectRoot, "ignition", "modules", "ComposeDeploy.ts"); + }, + + getManagedDeployRunnerPath(projectRoot: string): string { + return path.join(projectRoot, MANAGED_RUNNER_RELATIVE_PATH); + }, + + getManagedDeployResultPath(projectRoot: string): string | null { + return path.join(projectRoot, MANAGED_RESULT_RELATIVE_PATH); + }, + + createDeployCommand(opts: DeployCommandOptions): DeployCommand { + if (!opts.runnerPath) { + throw new Error("Hardhat Ignition deployment requires the transient Compose runner path."); + } + const relativeScriptPath = toPosixPath(path.relative(opts.projectRoot, opts.runnerPath)); + const env: NodeJS.ProcessEnv = { + COMPOSE_DEPLOY_RPC_URL: opts.rpcUrl, + COMPOSE_DEPLOY_MODE: opts.mode, + }; + if (opts.mode === "simulate" && opts.forkBlockNumber !== undefined) { + env.COMPOSE_DEPLOY_FORK_BLOCK_NUMBER = String(opts.forkBlockNumber); + } + return { + command: "npx", + args: [ + "hardhat", + "--build-profile", + "production", + "run", + "--no-compile", + relativeScriptPath, + "--network", + opts.chainKey, + ...opts.passthrough, + ], + env, + }; + }, + + createTestCommand(opts: TestCommandOptions): FrameworkCommand { + return { + command: "npx", + args: ["hardhat", "test", ...opts.passthrough], + }; + }, + + async readDeployedBytecode( + projectRoot: string, + sourcePath: string, + contractName: string, + ): Promise { + const sourceName = await resolveHardhatArtifactSourceName(projectRoot, sourcePath); + if (!sourceName) return undefined; + + const artifactPath = path.join( + projectRoot, + "artifacts", + ...sourceName.split("/"), + `${contractName}.json`, + ); + try { + const artifact = JSON.parse(await fs.readFile(artifactPath, "utf8")) as { + deployedBytecode?: unknown; + }; + return typeof artifact.deployedBytecode === "string" && artifact.deployedBytecode.length > 2 + ? (artifact.deployedBytecode as Hex) + : undefined; + } catch { + return undefined; + } + }, + + async readBroadcastTransactions(): Promise { + // Compose reads Ignition addresses from its result file and transaction + // hashes from the matching future in Hardhat Ignition's journal. + return []; + }, }; export const hardhatAdapter = adapter; diff --git a/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/helpers.ts b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/helpers.ts index 3d42ab4b..44efc7bc 100644 --- a/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/helpers.ts +++ b/cli/src/adapters/IFrameworkAdapter/hardhatAdapter/helpers.ts @@ -1,4 +1,88 @@ +import { readFileSync } from "node:fs"; +import fs from "node:fs/promises"; import path from "node:path"; +import type { DeployToolbox } from "../types"; + +/** + * Detects the Hardhat ethers or viem toolbox from package.json. + * + * @param projectRoot - Absolute project root. + * @returns The detected toolbox variant. + * @throws {Error} If the project has no supported Hardhat toolbox. + */ +export async function detectHardhatToolbox(projectRoot: string): Promise { + let packageJson: { + dependencies?: Record; + devDependencies?: Record; + }; + try { + packageJson = JSON.parse( + await fs.readFile(path.join(projectRoot, "package.json"), "utf8"), + ) as { + dependencies?: Record; + devDependencies?: Record; + }; + } catch { + throw new Error("Cannot determine the Hardhat toolbox: package.json is missing or invalid."); + } + + const dependencies = { ...packageJson.dependencies, ...packageJson.devDependencies }; + if ( + dependencies["@nomicfoundation/hardhat-toolbox-viem"] + || dependencies["@nomicfoundation/hardhat-viem"] + ) { + return "viem"; + } + if ( + dependencies["@nomicfoundation/hardhat-toolbox-mocha-ethers"] + || dependencies["@nomicfoundation/hardhat-ethers"] + ) { + return "ethers"; + } + + throw new Error( + "Compose requires @nomicfoundation/hardhat-ethers or @nomicfoundation/hardhat-viem. " + + "Install the toolbox matching your Hardhat project, then retry.", + ); +} + +/** Ensures that a detected Hardhat project uses the supported Hardhat 3 API. */ +export function assertHardhat3(projectRoot: string): void { + const packagePath = path.join(projectRoot, "package.json"); + let packageJson: { + dependencies?: Record; + devDependencies?: Record; + }; + try { + packageJson = JSON.parse(readFileSync(packagePath, "utf8")) as { + dependencies?: Record; + devDependencies?: Record; + }; + } catch { + throw new Error("Hardhat project package.json is missing or invalid; Compose supports Hardhat 3 projects only."); + } + + let version: string | undefined; + try { + const installedPath = path.join(projectRoot, "node_modules", "hardhat", "package.json"); + version = (JSON.parse(readFileSync(installedPath, "utf8")) as { version?: string }).version; + } catch { + version = packageJson.devDependencies?.hardhat ?? packageJson.dependencies?.hardhat; + } + + const match = version?.match(/(?:^|[^0-9])(\d+)\.(\d+)(?:\.(\d+))?/); + if (!version || !match) { + throw new Error("Could not determine the Hardhat version. Install Hardhat 3 in this project before running Compose."); + } + + const major = Number(match[1]); + const minor = Number(match[2]); + if (major !== 3 || minor < 8) { + throw new Error( + `Compose supports Hardhat 3.8 or newer; this project declares or installs '${version}'.`, + ); + } +} /** Converts a Hardhat compiler source name into its readable filesystem path. */ export function resolveHardhatAstSourcePath(projectRoot: string, sourceName: string): string { @@ -22,3 +106,45 @@ export function resolveHardhatAstSourcePath(projectRoot: string, sourceName: str ? path.normalize(sourceName) : path.resolve(projectRoot, sourceName); } + +/** + * Resolves the Hardhat artifact source name for a file on disk. + * + * Project files map to their project-relative path; files under + * `node_modules` map to `npm/@/`, mirroring the + * source names Hardhat writes into its artifacts directory. Returns null + * when the file cannot be attributed to a Hardhat source name. + */ +export async function resolveHardhatArtifactSourceName( + projectRoot: string, + sourcePath: string, +): Promise { + const normalized = path.resolve(sourcePath); + + const nodeModulesRoot = path.join(projectRoot, "node_modules"); + const packageRelative = path.relative(nodeModulesRoot, normalized); + if (packageRelative && !packageRelative.startsWith("..") && !path.isAbsolute(packageRelative)) { + const segments = packageRelative.replace(/\\/g, "/").split("/"); + const packageName = segments[0].startsWith("@") ? segments.slice(0, 2).join("/") : segments[0]; + const subpath = segments.slice(packageName.split("/").length).join("/"); + if (!subpath) return null; + + try { + const packageJson = JSON.parse( + await fs.readFile(path.join(nodeModulesRoot, packageName, "package.json"), "utf8"), + ) as { version?: unknown }; + const version = typeof packageJson.version === "string" ? packageJson.version : ""; + if (!version) return null; + return `npm/${packageName}@${version}/${subpath}`; + } catch { + return null; + } + } + + const projectRelative = path.relative(projectRoot, normalized); + if (projectRelative && !projectRelative.startsWith("..") && !path.isAbsolute(projectRelative)) { + return projectRelative.replace(/\\/g, "/"); + } + + return null; +} diff --git a/cli/src/adapters/IFrameworkAdapter/interface.ts b/cli/src/adapters/IFrameworkAdapter/interface.ts index 8a5fcff9..0c23ce03 100644 --- a/cli/src/adapters/IFrameworkAdapter/interface.ts +++ b/cli/src/adapters/IFrameworkAdapter/interface.ts @@ -1,27 +1,19 @@ import { ComposeContext } from "../../context/types"; - -/** Options passed to adapter config writing. */ -export type ConfigOptions = { - compilerVersion: string; - projectName: string; - installDeps: boolean; -}; - -/** A Solidity source unit AST returned by a framework compiler. */ -export type SolidityAstSource = { - sourceName: string; - ast: SoliditySourceUnitAst; -}; - -/** Minimal stable shape shared by Solidity compact AST source units. */ -export type SoliditySourceUnitAst = { - id: number; - nodeType: "SourceUnit"; - src: string; - absolutePath?: string; - nodes?: unknown[]; - [key: string]: unknown; -}; +import type { Hex } from "viem"; +import type { + AccountAddressResolution, + AccountResolutionOptions, + BroadcastTransaction, + ConfigOptions, + DeployCommand, + DeployCommandOptions, + DeploySignerOptions, + DeployToolbox, + FrameworkCommand, + SignerAddressOptions, + SolidityAstSource, + TestCommandOptions, +} from "./types"; /** Interface for framework-specific project scaffolding adapters. */ export interface IFrameworkAdapter { @@ -43,6 +35,17 @@ export interface IFrameworkAdapter { /** Compile explicit Solidity entrypoints and return every unique source unit AST. */ compileAst(ctx: ComposeContext, sourcePaths: string[]): Promise; + /** + * Optional: makes package-sourced facets part of the framework build before a + * validating compile. Hardhat lists them in `npmFilesToBuild`; resolves to a + * revert closure, or null when nothing changed. Foundry omits it (its compile + * takes explicit source paths, so package facets already build). + */ + ensurePackageFacetsCompilable?( + projectRoot: string, + packageSpecifiers: string[], + ): Promise<(() => Promise) | null>; + /** * Resolve a catalog Solidity path to a readable local file. * @@ -62,4 +65,88 @@ export interface IFrameworkAdapter { * Called after facets are copied. */ writeConfig(ctx: ComposeContext, opts: ConfigOptions): Promise; + + /** Whether Compose can import keys into this framework's native keystore. */ + readonly supportsAccountImport: boolean; + + /** Read a native account's address without unlocking or prompting. */ + readAccountAddress( + projectRoot: string, + accountName: string, + ): Promise; + + /** Resolve a native account's address, optionally unlocking it. */ + resolveAccountAddress( + projectRoot: string, + accountName: string, + options?: AccountResolutionOptions, + ): Promise; + + /** List the addresses the framework will use to sign on a chain. */ + listSignerAddresses(options: SignerAddressOptions): Promise; + + /** + * Resolve a single configured key variable for the selected network when + * the framework config makes it unambiguous. + */ + getAccountKeyVariable?(projectRoot: string, chainKey: string): Promise; + + /** + * Resolve the signer a deploy command will use without signing anything. + * Returns null when the framework cannot expose the selected signer. + */ + resolveDeploySigner(options: DeploySignerOptions): Promise; + + /** Import a key interactively into the framework keystore and return its address. */ + importAccount( + projectRoot: string, + accountName: string, + ): Promise; + + /** Assert that the project uses a framework version Compose supports. */ + assertSupportedProject(projectRoot: string): void; + + /** + * Detect the contract interaction toolbox used by the framework. + * Returns null for frameworks without a JavaScript toolbox. + */ + getDeployToolbox(projectRoot: string): Promise; + + /** Resolve the path of the CLI-managed deployment artifact inside the project. */ + getManagedDeployScriptPath(projectRoot: string): string; + + /** Resolve an optional runtime runner separate from the reviewed deploy artifact. */ + getManagedDeployRunnerPath(projectRoot: string): string | null; + + /** + * Resolve the path of the CLI-managed deploy result file inside the project. + * Returns null for frameworks that record deployments through their broadcast. + */ + getManagedDeployResultPath(projectRoot: string): string | null; + + /** Build the framework command that simulates or broadcasts the managed deployment artifact. */ + createDeployCommand(opts: DeployCommandOptions): DeployCommand; + + /** Build the framework command that executes the project test suite. */ + createTestCommand(opts: TestCommandOptions): FrameworkCommand; + + /** + * Read compiled deployed bytecode for a contract from the framework's + * local build artifacts. Returns undefined when no artifact is available. + */ + readDeployedBytecode( + projectRoot: string, + sourcePath: string, + contractName: string, + ): Promise; + + /** + * Read the contract deployments recorded by a framework broadcast. + * Returns an empty list for frameworks that report transactions elsewhere. + */ + readBroadcastTransactions( + projectRoot: string, + scriptPath: string, + chainId: number, + ): Promise; } diff --git a/cli/src/adapters/IFrameworkAdapter/types.ts b/cli/src/adapters/IFrameworkAdapter/types.ts new file mode 100644 index 00000000..321afa82 --- /dev/null +++ b/cli/src/adapters/IFrameworkAdapter/types.ts @@ -0,0 +1,124 @@ +/** Options passed to adapter config writing. */ +export type ConfigOptions = { + compilerVersion: string; + projectName: string; + installDeps: boolean; +}; + +/** Options for building the framework command that runs a managed deployment artifact. */ +export type DeployCommandOptions = { + /** Absolute project root the command runs in. */ + projectRoot: string; + /** Absolute path of the reviewable managed deployment artifact. */ + scriptPath: string; + /** Absolute path of a framework runner that invokes the reviewed artifact. */ + runnerPath?: string | null; + /** Chain key as defined in compose.json. */ + chainKey: string; + /** RPC endpoint for the target chain. */ + rpcUrl: string; + /** Expected EVM chain ID for the target chain. */ + chainId: number; + /** Whether the managed script is simulated locally or broadcast to the target. */ + mode: "simulate" | "broadcast"; + /** Target-chain block used as the fork point for simulations. */ + forkBlockNumber?: bigint; + /** Optional Compose account selection mapped to a framework-native signer. */ + account?: { alias: string; address: string; foundryAccount?: string } | null; + /** Extra arguments forwarded to the framework after `--`. */ + passthrough: string[]; +}; + +/** Options for building the framework command that runs the project test suite. */ +export type TestCommandOptions = { + /** Absolute project root the command runs in. */ + projectRoot: string; + /** Extra arguments forwarded to the framework after `--`. */ + passthrough: string[]; +}; + +/** Contract interaction toolbox variants used by Compose's managed deploy scripts. */ +export type DeployToolbox = "ethers" | "viem"; + +/** Result of reading or resolving a framework-native account reference. */ +export type AccountAddressResolution = { + /** Public address when it can be read or was resolved. */ + address: string | null; + /** Whether a native account reference exists (for Foundry, a keystore file). */ + exists: boolean; + /** Whether an existing account needs an interactive unlock to expose its address. */ + requiresUnlock: boolean; +}; + +/** Options for resolving a framework-native account. */ +export type AccountResolutionOptions = { + /** Whether the adapter may unlock an encrypted account. */ + allowUnlock?: boolean; + /** Called immediately before the framework prompts for a password. */ + onUnlock?: () => void; +}; + +/** Options for listing the signers a framework will use for a chain. */ +export type SignerAddressOptions = AccountResolutionOptions & { + /** Absolute project root the framework command runs in. */ + projectRoot: string; + /** Chain key as defined in compose.json. */ + chainKey: string; + /** RPC endpoint for the target chain. */ + rpcUrl: string; + /** Expected EVM chain ID for the target chain. */ + chainId: number; + /** Foundry keystore name; ignored by frameworks without named accounts. */ + accountName?: string; +}; + +/** Options for resolving the signer a deployment command will use. */ +export type DeploySignerOptions = { + /** Absolute project root the framework command runs in. */ + projectRoot: string; + /** Chain key as defined in compose.json. */ + chainKey: string; + /** RPC endpoint for the target chain. */ + rpcUrl: string; + /** Expected EVM chain ID for the target chain. */ + chainId: number; + /** Optional Compose account selection mapped to a framework-native signer. */ + account?: { alias: string; address: string; foundryAccount?: string } | null; + /** Framework arguments forwarded after `--`. */ + passthrough: string[]; +}; + +/** A framework command ready to be executed. */ +export type FrameworkCommand = { + command: string; + args: string[]; + /** Environment overrides for the spawned framework process. */ + env?: NodeJS.ProcessEnv; +}; + +/** A deploy command ready to be executed. */ +export type DeployCommand = FrameworkCommand; + +/** A contract deployment recorded by a framework broadcast. */ +export type BroadcastTransaction = { + contractName?: string | null; + contractAddress?: string | null; + txHash?: string | null; + from?: string | null; +}; + +/** A Solidity source unit AST returned by a framework compiler. */ +export type SolidityAstSource = { + sourceName: string; + ast: SoliditySourceUnitAst; +}; + +/** Minimal stable shape shared by Solidity compact AST source units. */ +export type SoliditySourceUnitAst = { + id: number; + nodeType: "SourceUnit"; + src: string; + absolutePath?: string; + nodes?: unknown[]; + [key: string]: unknown; +}; diff --git a/cli/src/adapters/IRPCAdapter/adapter.ts b/cli/src/adapters/IRPCAdapter/adapter.ts index dba3ae63..e423ec1a 100644 --- a/cli/src/adapters/IRPCAdapter/adapter.ts +++ b/cli/src/adapters/IRPCAdapter/adapter.ts @@ -49,7 +49,7 @@ export async function createRPCAdapter(options: RPCAdapterOptions): Promise client.getChainId()); } catch (error) { - throw error instanceof RPCAdapterError ? error : requestError("getChainId", options.chainId, error); + throw error instanceof RPCAdapterError ? error : requestError("getChainId", options.chainId, error, options.rpcUrl); } if (endpointChainId !== options.chainId) { throw new RPCAdapterError( @@ -64,7 +64,7 @@ export async function createRPCAdapter(options: RPCAdapterOptions): Promise client.getBlockNumber()); } catch (error) { - throw requestError("getBlockNumber", options.chainId, error); + throw requestError("getBlockNumber", options.chainId, error, options.rpcUrl); } } @@ -79,7 +79,7 @@ export async function createRPCAdapter(options: RPCAdapterOptions): Promise client.getCode({ address, blockNumber })); } catch (error) { - throw requestError("getCode", options.chainId, error); + throw requestError("getCode", options.chainId, error, options.rpcUrl); } } @@ -110,7 +110,7 @@ export async function createRPCAdapter(options: RPCAdapterOptions): Promise client.readContract(parameters)) as T; } catch (error) { if (error instanceof RPCAdapterError) throw error; - throw requestError("readContract", options.chainId, error); + throw requestError("readContract", options.chainId, error, options.rpcUrl); } } diff --git a/cli/src/adapters/IRPCAdapter/errors.ts b/cli/src/adapters/IRPCAdapter/errors.ts index 263aaea0..6576b29e 100644 --- a/cli/src/adapters/IRPCAdapter/errors.ts +++ b/cli/src/adapters/IRPCAdapter/errors.ts @@ -1,4 +1,4 @@ -import { statusCode } from "./utils"; +import { errorChain, safeRpcEndpoint, sanitizeRpcCause, statusCode } from "./utils"; /** Stable error categories emitted by the RPC adapter. */ export type RPCErrorCode = @@ -41,15 +41,49 @@ export class RPCAdapterError extends Error { } } +/** + * Returns the deepest non-empty message in an error's cause chain. + * + * Transport failures hide the useful reason (e.g. `connect ECONNREFUSED`) in a + * cause, so the summary walks to the bottom instead of quoting the wrapper. + * @param error Error whose cause chain should be summarized. + * @returns The collapsed, bounded message, or `undefined` when none is found. + */ +function causeSummary(error: unknown): string | undefined { + const causes = errorChain(error).slice(1); + for (let index = causes.length - 1; index >= 0; index -= 1) { + const item = causes[index]; + const raw = item instanceof Error ? item.message : typeof item === "string" ? item : ""; + const message = raw.replace(/\s+/g, " ").trim(); + if (message) return message.length > 200 ? `${message.slice(0, 197)}...` : message; + } + return undefined; +} + /** * Converts an unknown transport failure into a stable adapter error. * @param operation RPC operation that failed. * @param chainId Chain on which the operation was attempted. * @param error Original transport or client failure. + * @param rpcUrl Endpoint the operation targeted, when known. * @returns A normalized adapter error with a stable error code. */ -export function requestError(operation: string, chainId: number, error: unknown): RPCAdapterError { +export function requestError( + operation: string, + chainId: number, + error: unknown, + rpcUrl?: string, +): RPCAdapterError { const status = statusCode(error); const code = status === 401 ? "RPC_UNAUTHORIZED" : "RPC_REQUEST_FAILED"; - return new RPCAdapterError(code, `RPC ${operation} failed on chain ${chainId}`, { operation, chainId, cause: error }); + const endpoint = rpcUrl ? safeRpcEndpoint(rpcUrl) : undefined; + const target = endpoint ? ` at ${endpoint}` : ""; + const rawCause = causeSummary(error); + const cause = rawCause ? sanitizeRpcCause(rawCause, rpcUrl) : undefined; + const detail = cause ? `: ${cause}` : ""; + return new RPCAdapterError(code, `RPC ${operation} failed on chain ${chainId}${target}${detail}`, { + operation, + chainId, + cause: error, + }); } diff --git a/cli/src/adapters/IRPCAdapter/utils.ts b/cli/src/adapters/IRPCAdapter/utils.ts index 7ff008be..e62a28cb 100644 --- a/cli/src/adapters/IRPCAdapter/utils.ts +++ b/cli/src/adapters/IRPCAdapter/utils.ts @@ -39,3 +39,70 @@ export function statusCode(error: unknown): number | undefined { } return undefined; } + +/** + * Returns the non-secret portion of an RPC endpoint for diagnostics. + * Paths are omitted entirely because RPC providers commonly place API keys in + * path segments; query strings, fragments, and userinfo are omitted as well. + */ +export function safeRpcEndpoint(rpcUrl: string): string | undefined { + try { + return new URL(rpcUrl).origin; + } catch { + return undefined; + } +} + +/** + * Collects values from an endpoint that must not be echoed in a cause message. + * Includes path segments too, since providers often use those as API keys. + */ +function endpointSecrets(rpcUrl?: string): string[] { + if (!rpcUrl) return []; + + try { + const url = new URL(rpcUrl); + const values = [ + url.username, + url.password, + ...url.searchParams.values(), + ...url.pathname.split("/"), + url.hash.slice(1), + ]; + return [...new Set(values.flatMap((value) => { + if (!value) return []; + try { + return [value, decodeURIComponent(value)]; + } catch { + return [value]; + } + }))].filter(Boolean).sort((left, right) => right.length - left.length); + } catch { + return []; + } +} + +/** Redacts endpoint secrets, then replaces any URL in text with its safe origin. */ +export function sanitizeRpcCause(message: string, rpcUrl?: string): string { + let sanitized = message; + + for (const secret of endpointSecrets(rpcUrl)) { + const escaped = secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + // Long API tokens should be removed even when adjacent to other text. For + // short path names, use token boundaries to avoid mangling ordinary words. + const pattern = secret.length >= 8 + ? new RegExp(escaped, "g") + : new RegExp(`(^|[^\\p{L}\\p{N}])${escaped}(?=$|[^\\p{L}\\p{N}])`, "gu"); + sanitized = sanitized.replace(pattern, secret.length >= 8 ? "[REDACTED]" : "$1[REDACTED]"); + } + + return sanitized.replace(/https?:\/\/[^\s"'<>]+/gi, (candidate) => { + let urlText = candidate; + let punctuation = ""; + while (/[),.;!?]$/.test(urlText)) { + punctuation = urlText.slice(-1) + punctuation; + urlText = urlText.slice(0, -1); + } + return `${safeRpcEndpoint(urlText) ?? "[redacted URL]"}${punctuation}`; + }); +} diff --git a/cli/src/comander.ts b/cli/src/comander.ts index b71634d7..dbd08848 100644 --- a/cli/src/comander.ts +++ b/cli/src/comander.ts @@ -1,5 +1,6 @@ import { Command } from "commander"; import { VERSION } from "./utils/metadata"; +import { formatCommandArgs } from "./utils/redaction"; /** * Defines the CLI program with per-command flags. @@ -26,10 +27,12 @@ export function buildProgram(): Command { .option("--ownership-extensions ", "Ownership extension facets") .option("--access-control ", "Comma-separated access control bases") .option("--access-control-extensions ", "Access control extension facets") + .option("--upgradeable", "Include the upgrade facet and owner coupling") + .option("--immutable", "Deploy without the upgrade facet (default)") .option("--out ", "Output directory") .option("--yes", "Non-interactive mode (requires --base)") .option("--install-deps", "Install dependencies (default)") - .option("--no-install-deps", "Skip dependency installation") + .option("--no-install-deps", "Skip dependency installation (Foundry only; Hardhat 3 init installs its template)") .option("--toolbox ", "Hardhat toolbox", "ethers"); program @@ -54,6 +57,30 @@ export function buildProgram(): Command { .option("--create-manifest ", "Create a remove batch manifest without applying it") .option("--yes", "Skip confirmation prompts"); + program + .command("account") + .description("Set up, check, list, or remove non-secret deployment account aliases") + .argument("", "setup, check, list, or remove") + .argument("[name]", "Account alias") + .option("--address
", "Public address for the account") + .option("--foundry-account ", "Existing Foundry keystore account name") + .option("--chain ", "Set this account as the chain's default signer") + .option("--rpc-url ", "RPC endpoint override for account verification") + .option("--project-root ", "Compose project directory"); + + program + .command("deploy") + .description("Deploy a diamond from compose.json and record it in compose.lock") + .option("--diamond ", "Diamond name from compose.json") + .option("--chain ", "Chain key from compose.json", "local") + .option("--rpc-url ", "Override this chain's RPC URL for this deployment") + .option("--account ", "Compose account alias to use for deployment") + .option("--instance ", "Deployment instance name", "default") + .option("--project-root ", "Compose project directory") + .option("--broadcast", "Broadcast the reviewed managed deployment artifact") + .option("--dry-run", "Simulate the reviewed deployment artifact on a fork without broadcasting") + .option("--redeploy", "Abandon the existing lock record and plan a fresh deployment"); + program .command("validate") .description("Validate selectors and virtual storage layouts") @@ -71,6 +98,11 @@ export function buildProgram(): Command { .command("build") .description("Compile the project if artifacts are stale or missing") + program + .command("test") + .description("Run the project's test suite through its framework") + .option("--project-root ", "Start searching for the project from this directory") + program .command("rpc") .description("Check RPC connectivity and optionally inspect contract bytecode") @@ -89,12 +121,21 @@ export function buildProgram(): Command { /** * Parses CLI arguments using commander and returns a structured result. * + * Everything from the first `--` (at or after the command) onward is + * passthrough: it is split off before commander parses, so unknown options + * before the separator are still rejected, and the tail is forwarded to the + * framework by `compose deploy`. + * * @param argv - The raw process.argv array (e.g. ["node", "cli.ts", "init", "--yes"]) * @returns The parsed command name and flags object ready for ctx.param. */ export function parseArgs(argv: string[]): { command: string; flags: Record } { + const separatorIndex = argv.indexOf("--", 2); + const cliArgv = separatorIndex === -1 ? argv : argv.slice(0, separatorIndex); + const passthrough = separatorIndex === -1 ? [] : argv.slice(separatorIndex + 1); + const program = buildProgram(); - program.parse(argv); + program.parse(cliArgv); const invokedCommand = program.args[0] ?? ""; const commandInstance = program.commands.find( @@ -102,6 +143,11 @@ export function parseArgs(argv: string[]): { command: string; flags: Record 0) { + throw new Error( + `Unexpected arguments after '--': ${formatCommandArgs(passthrough)}. Only 'compose deploy' and 'compose test' accept passthrough arguments.`, + ); + } return { command: invokedCommand, flags: {} }; } @@ -115,8 +161,20 @@ export function parseArgs(argv: string[]): { command: string; flags: Record 0) { + if (command !== "deploy" && command !== "test") { + throw new Error( + `Unexpected arguments after '--': ${formatCommandArgs(passthrough)}. Only 'compose deploy' and 'compose test' accept passthrough arguments.`, + ); + } + flags.passthrough = passthrough; + } + const positionalArgs = commandInstance.args.filter((arg): arg is string => typeof arg === "string"); - if (command === "install" || command === "remove") { + if (command === "account") { + if (positionalArgs[0]) flags.action = positionalArgs[0]; + if (positionalArgs[1]) flags.accountName = positionalArgs[1]; + } else if (command === "install" || command === "remove") { if (positionalArgs.length > 0) flags.facets = positionalArgs; } else if (positionalArgs.length > 0) { if (command === "inspect" && !flags.address) { diff --git a/cli/src/index.ts b/cli/src/index.ts index 8c0239a6..f2fab1b4 100644 --- a/cli/src/index.ts +++ b/cli/src/index.ts @@ -1,31 +1,17 @@ -import dotenv from "dotenv"; -import path from "node:path"; import { Context } from "./context/context"; import { ComposeContext } from "./context/types"; import { EntryPipeline } from "./pipelines/entryPipeline"; import { exitWithError } from "./utils/errors"; +import { loadProjectEnv } from "./utils/env"; import { parseArgs } from "./comander"; -function loadEnvFiles(): void { - const root = path.parse(process.cwd()).root; - let dir = process.cwd(); - const files: string[] = []; - while (dir !== root) { - files.push(path.join(dir, ".env")); - dir = path.dirname(dir); - } - files.push(path.join(root, ".env")); - for (const file of files.reverse()) { - dotenv.config({ path: file }); - } -} - /** * Main Entrypoint for the Compose CLI */ async function main(): Promise { - loadEnvFiles(); const { command, flags } = parseArgs(process.argv); + const projectRoot = typeof flags.projectRoot === "string" ? flags.projectRoot : process.cwd(); + await loadProjectEnv(projectRoot); const ctx: ComposeContext = Context.create(); ctx.param.command = command; diff --git a/cli/src/modules/accounts/config.ts b/cli/src/modules/accounts/config.ts new file mode 100644 index 00000000..39beea61 --- /dev/null +++ b/cli/src/modules/accounts/config.ts @@ -0,0 +1,50 @@ +import { getAddress, isAddress } from "viem"; +import { isRecord } from "./model"; +import type { DeploymentAccount } from "./types"; + +const ACCOUNT_ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; +const RESERVED_ACCOUNT_ALIASES = new Set(["__proto__", "constructor", "prototype"]); + +/** Ensures an alias is safe to use as a compose.json object key. */ +export function assertValidAccountAlias(alias: string): void { + if (!ACCOUNT_ALIAS_PATTERN.test(alias) || RESERVED_ACCOUNT_ALIASES.has(alias)) { + throw new Error( + `Invalid account alias '${alias}'. Use letters, digits, '.', '_' or '-' and avoid reserved object keys.`, + ); + } +} + +/** Resolves and validates a non-secret signer profile from compose.json. */ +export function resolveAccountProfile( + accounts: unknown, + alias: string, + framework: "foundry" | "hardhat", +): DeploymentAccount { + assertValidAccountAlias(alias); + if (!isRecord(accounts)) throw new Error("compose.json does not define any account profiles."); + + const rawProfile = accounts[alias]; + if (!isRecord(rawProfile)) throw new Error(`Account alias '${alias}' was not found in compose.json.`); + if (typeof rawProfile.address !== "string" || !isAddress(rawProfile.address, { strict: false })) { + throw new Error(`Account '${alias}' must define a valid public address.`); + } + + let foundryAccount: string | undefined; + if (framework === "foundry") { + if (rawProfile.foundry !== undefined && !isRecord(rawProfile.foundry)) { + throw new Error(`Account '${alias}' has an invalid Foundry account reference.`); + } + const foundry = isRecord(rawProfile.foundry) ? rawProfile.foundry : undefined; + if (foundry?.account !== undefined && (typeof foundry.account !== "string" || !foundry.account.trim())) { + throw new Error(`Account '${alias}' has an invalid Foundry account name.`); + } + foundryAccount = typeof foundry?.account === "string" ? foundry.account.trim() : alias; + assertValidAccountAlias(foundryAccount); + } + + return { + alias, + address: getAddress(rawProfile.address), + ...(foundryAccount ? { foundryAccount } : {}), + }; +} diff --git a/cli/src/modules/accounts/model.ts b/cli/src/modules/accounts/model.ts new file mode 100644 index 00000000..30d5424b --- /dev/null +++ b/cli/src/modules/accounts/model.ts @@ -0,0 +1,48 @@ +import type { AccountChainDefault, AccountListEntry } from "./types"; + +/** Narrows unknown JSON values to plain object records. */ +export function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** Returns compose.json's accounts object, or an empty object when unset. */ +export function getComposeAccounts(composeJson: Record): Record { + return isRecord(composeJson.accounts) ? composeJson.accounts : {}; +} + +/** Returns compose.json's chains object, or an empty object when unset. */ +export function getComposeChains(composeJson: Record): Record { + return isRecord(composeJson.chains) ? composeJson.chains : {}; +} + +/** Returns chain keys that point at `alias` as their default account. */ +export function findDefaultChainKeys(composeJson: Record, alias: string): string[] { + return Object.entries(getComposeChains(composeJson)) + .filter(([, chain]) => isRecord(chain) && chain.account === alias) + .map(([chainKey]) => chainKey); +} + +/** Builds the alias and chain-default views used by `compose account list`. */ +export function buildAccountList(composeJson: Record): { + entries: AccountListEntry[]; + defaults: AccountChainDefault[]; +} { + const entries = Object.entries(getComposeAccounts(composeJson)).map(([alias, rawProfile]) => { + const profile = isRecord(rawProfile) ? rawProfile : {}; + const foundry = isRecord(profile.foundry) ? profile.foundry : {}; + + return { + alias, + address: String(profile.address ?? "invalid address"), + ...(typeof foundry.account === "string" ? { foundryAccount: foundry.account } : {}), + }; + }); + + const defaults = Object.entries(getComposeChains(composeJson)).flatMap(([chainKey, rawChain]) => + isRecord(rawChain) && typeof rawChain.account === "string" + ? [{ chainKey, alias: rawChain.account }] + : [], + ); + + return { entries, defaults }; +} diff --git a/cli/src/modules/accounts/module.ts b/cli/src/modules/accounts/module.ts new file mode 100644 index 00000000..73223b6d --- /dev/null +++ b/cli/src/modules/accounts/module.ts @@ -0,0 +1,320 @@ +import { getAddress, isAddress } from "viem"; +import type { ComposeContext } from "../../context/types"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import { validateOptions } from "../../adapters/IRPCAdapter/validation"; +import { resolveChainConfig } from "../../utils/chainConfig"; +import { loadComposeProjectFile, type ComposeProjectFile } from "../../utils/composeProjectFile"; +import { atomicWriteFile } from "../../utils/files"; +import { isInteractive, loadPrompts } from "../../utils/inquirer"; +import type { Framework } from "../framework/module"; +import { assertValidAccountAlias, resolveAccountProfile } from "./config"; +import { buildAccountList, findDefaultChainKeys, getComposeAccounts, getComposeChains, isRecord } from "./model"; +import { + showAccountAvailable, + showAccountList, + showAccountRegistered, + showAccountRemoved, + showFoundryKeystoreUnlock, + showNoAccounts, +} from "./output"; +import type { AccountActionResult, AccountCheckSummary, AccountSetupSummary } from "./types"; + +/** Loaded compose.json state for one account command. */ +export type AccountProject = { + composeFile: ComposeProjectFile; + composeJson: Record; +}; + +/** Framework state the pipeline resolves before check/setup execution. */ +export type AccountDependencies = { + framework: Framework; + adapter: IFrameworkAdapter; +}; + +function requireAccountDependencies( + dependencies: AccountDependencies | undefined, +): AccountDependencies { + if (!dependencies) throw new Error("The account framework adapter was not resolved."); + return dependencies; +} + +async function writeComposeFile( + composeFile: ComposeProjectFile, + composeJson: Record, +): Promise { + await atomicWriteFile(composeFile.path, `${JSON.stringify(composeJson, null, 2)}\n`); +} + +async function promptPublicAddress(): Promise { + const { input } = await loadPrompts(); + return input({ + message: "Public signer address (never enter a private key):", + validate: (value) => isAddress(value, { strict: false }) ? true : "Enter a valid EVM address.", + }); +} + +async function checkAccount( + ctx: ComposeContext, + composeJson: Record, + projectRoot: string, + framework: Framework, + adapter: IFrameworkAdapter, +): Promise { + const alias = String(ctx.param.accountName ?? ""); + assertValidAccountAlias(alias); + const account = resolveAccountProfile(composeJson.accounts, alias, framework); + const requestedChain = typeof ctx.param.chain === "string" ? ctx.param.chain : undefined; + const defaults = findDefaultChainKeys(composeJson, alias); + const chainKey = requestedChain ?? (defaults.length === 1 ? defaults[0] : undefined); + if (!chainKey) { + throw new Error(`Pass --chain or set '${alias}' as the default account for exactly one chain.`); + } + + const chain = await resolveChainConfig({ + chainKey, + projectRoot, + rpcUrlOverride: ctx.param.rpcUrl, + }); + validateOptions({ rpcUrl: chain.rpcUrl, chainId: chain.chainId }); + + const nativeAccount = account.foundryAccount ?? alias; + const availableAddresses = await adapter.listSignerAddresses({ + projectRoot, + chainKey, + rpcUrl: chain.rpcUrl, + chainId: chain.chainId, + accountName: nativeAccount, + allowUnlock: isInteractive() || Boolean(process.env.ETH_PASSWORD), + onUnlock: () => showFoundryKeystoreUnlock(nativeAccount), + }); + + if (!availableAddresses.some((address) => address.toLowerCase() === account.address.toLowerCase())) { + throw new Error( + `Account '${alias}' (${account.address}) is not available in ${framework} on chain '${chainKey}'.`, + ); + } + const summary = { alias, address: account.address, chainKey }; + showAccountAvailable(summary); + return summary; +} + +function listAccounts(composeJson: Record): AccountActionResult { + const { entries, defaults } = buildAccountList(composeJson); + if (entries.length === 0) { + showNoAccounts(); + } else { + showAccountList(entries, defaults); + } + return { action: "list", entries, defaults }; +} + +async function removeAccount( + composeJson: Record, + composeFile: ComposeProjectFile, + alias: string, +): Promise { + const accounts = { ...getComposeAccounts(composeJson) }; + if (!(alias in accounts)) throw new Error(`Account alias '${alias}' was not found in compose.json.`); + delete accounts[alias]; + composeJson.accounts = accounts; + + const chains = { ...getComposeChains(composeJson) }; + for (const [chainKey, rawChain] of Object.entries(chains)) { + if (isRecord(rawChain) && rawChain.account === alias) { + chains[chainKey] = Object.fromEntries( + Object.entries(rawChain).filter(([key]) => key !== "account"), + ); + } + } + composeJson.chains = chains; + + await writeComposeFile(composeFile, composeJson); + showAccountRemoved(alias); +} + +async function setupAccount( + ctx: ComposeContext, + composeJson: Record, + composeFile: ComposeProjectFile, + framework: Framework, + adapter: IFrameworkAdapter, +): Promise { + let alias = String(ctx.param.accountName ?? ""); + if (!alias) { + if (!isInteractive()) throw new Error("Account alias is required in non-interactive mode."); + const { input } = await loadPrompts(); + alias = await input({ + message: "Account alias:", + validate: (value) => { + try { + assertValidAccountAlias(value); + return true; + } catch (error) { + return (error as Error).message; + } + }, + }); + } + assertValidAccountAlias(alias); + + const foundryAccount = framework === "foundry" + ? String(ctx.param.foundryAccount ?? alias) + : undefined; + if (foundryAccount) assertValidAccountAlias(foundryAccount); + + const nativeAccount = foundryAccount ?? alias; + const allowUnlock = isInteractive() || Boolean(process.env.ETH_PASSWORD); + + let updatedChains: Record | undefined; + if (ctx.param.chain !== undefined) { + if (typeof ctx.param.chain !== "string") throw new Error("Chain key must be a string."); + const chains = { ...getComposeChains(composeJson) }; + const chain = chains[ctx.param.chain]; + if (!isRecord(chain)) throw new Error(`Chain '${ctx.param.chain}' was not found in compose.json.`); + updatedChains = { ...chains, [ctx.param.chain]: { ...chain, account: alias } }; + } + + let address = typeof ctx.param.address === "string" ? ctx.param.address : ""; + if (!address) { + const resolution = await adapter.resolveAccountAddress(composeFile.root, nativeAccount, { + allowUnlock, + onUnlock: () => showFoundryKeystoreUnlock(nativeAccount), + }); + address = resolution.address ?? ""; + if (!address && resolution.requiresUnlock && !allowUnlock) { + throw new Error( + `Foundry keystore account '${nativeAccount}' already exists, but its address is encrypted. Run setup interactively, set ETH_PASSWORD to a Foundry password-file path, or pass its public address with --address.`, + ); + } + if (!address && adapter.supportsAccountImport && isInteractive()) { + const { confirm } = await loadPrompts(); + const importAccount = await confirm({ + message: `Import a key into Foundry's encrypted keystore as '${nativeAccount}'?`, + default: true, + }); + if (!importAccount) { + throw new Error(`Import Foundry account '${nativeAccount}' or pass its public address with --address.`); + } + address = await adapter.importAccount(composeFile.root, nativeAccount) ?? ""; + } + } + if (!address && isInteractive()) address = await promptPublicAddress(); + if (!address) { + throw new Error("Public account address is required. Pass --address; never pass a private key to Compose."); + } + if (!isAddress(address, { strict: false })) throw new Error("Account address must be a valid EVM address."); + address = getAddress(address); + + const native = await adapter.readAccountAddress(composeFile.root, nativeAccount); + if (native.address && native.address.toLowerCase() !== address.toLowerCase()) { + throw new Error( + `Foundry keystore account '${nativeAccount}' resolves to ${native.address}, not ${address}.`, + ); + } + + const chainKey = typeof ctx.param.chain === "string" && ctx.param.chain + ? ctx.param.chain + : undefined; + const keyVariableName = framework === "hardhat" && chainKey + ? await adapter.getAccountKeyVariable?.(composeFile.root, chainKey) ?? undefined + : undefined; + + const accounts = { ...getComposeAccounts(composeJson) }; + const existing = accounts[alias]; + if (isRecord(existing) && existing.address !== address) { + throw new Error(`Account alias '${alias}' already points to ${String(existing.address)}. Choose another alias.`); + } + accounts[alias] = { + address, + ...(foundryAccount ? { foundry: { account: foundryAccount } } : {}), + }; + composeJson.accounts = accounts; + + if (updatedChains) composeJson.chains = updatedChains; + + await writeComposeFile(composeFile, composeJson); + + const summary: AccountSetupSummary = { + alias, + address, + framework, + ...(foundryAccount ? { foundryAccount } : {}), + foundryKeystoreExists: native.exists, + ...(keyVariableName ? { keyVariableName } : {}), + ...(chainKey ? { chainKey } : {}), + }; + showAccountRegistered(summary); + return summary; +} + +/** Manages non-secret account aliases; key entry and signing stay in the framework. */ +export const AccountModule = { + /** + * Loads the nearest compose.json and validates that it contains an object. + * + * @param ctx - The compose context with an optional project root. + * @returns The compose file location and parsed object. + */ + async loadProject(ctx: ComposeContext): Promise { + const startDirectory = String(ctx.param.projectRoot ?? process.cwd()); + const loaded = await loadComposeProjectFile(startDirectory); + if (!loaded) throw new Error("compose.json not found. Run 'compose init' first."); + if (!isRecord(loaded.composeJson)) { + throw new Error("compose.json must contain a JSON object."); + } + + return { + composeFile: { path: loaded.path, root: loaded.root }, + composeJson: loaded.composeJson, + }; + }, + + /** + * Runs the requested account action against compose.json and records the + * outcome in `ctx.state.account`. + * + * Check and setup require the pipeline-resolved framework adapter. List and + * remove do not touch the framework. + * + * @param ctx - The compose context with `action`, `accountName`, and command flags. + * @param project - The loaded compose.json project. + * @param dependencies - Framework state resolved by the pipeline for check/setup. + * @returns The context with `state.account` populated on success. + */ + async execute( + ctx: ComposeContext, + project: AccountProject, + dependencies?: AccountDependencies, + ): Promise { + const action = String(ctx.param.action ?? ""); + const { composeFile, composeJson } = project; + + let result: AccountActionResult; + if (action === "list") { + result = listAccounts(composeJson); + } else if (action === "check") { + const resolved = requireAccountDependencies(dependencies); + result = { + action: "check", + ...await checkAccount(ctx, composeJson, composeFile.root, resolved.framework, resolved.adapter), + }; + } else if (action === "remove") { + const alias = String(ctx.param.accountName ?? ""); + assertValidAccountAlias(alias); + await removeAccount(composeJson, composeFile, alias); + result = { action: "remove", alias }; + } else { + if (action !== "setup") { + throw new Error("Use 'compose account setup ', 'compose account check ', 'compose account list', or 'compose account remove '."); + } + const resolved = requireAccountDependencies(dependencies); + result = { + action: "setup", + ...await setupAccount(ctx, composeJson, composeFile, resolved.framework, resolved.adapter), + }; + } + + ctx.state.account = { success: true, result, error: null }; + return ctx; + }, +}; diff --git a/cli/src/modules/accounts/output.ts b/cli/src/modules/accounts/output.ts new file mode 100644 index 00000000..ce6b4ab7 --- /dev/null +++ b/cli/src/modules/accounts/output.ts @@ -0,0 +1,90 @@ +import type { + AccountChainDefault, + AccountCheckSummary, + AccountListEntry, + AccountSetupSummary, +} from "./types"; +import { dim, green } from "../../utils/terminal"; + +/** Prints the Foundry keystore unlock notice before `cast` asks for a password. */ +export function showFoundryKeystoreUnlock(accountName: string): void { + console.log(`Unlocking Foundry keystore account '${accountName}' to read its public address...`); +} + +/** Prints a successful account availability check. */ +export function showAccountAvailable(result: AccountCheckSummary): void { + console.log(`Account '${result.alias}' is available on ${result.chainKey}: ${result.address}`); +} + +/** Prints guidance when no Compose account aliases are configured. */ +export function showNoAccounts(): void { + console.log("No Compose account aliases are configured."); + console.log("Run 'compose account setup ' to register a framework-managed account."); +} + +/** Prints configured aliases and their chain defaults. */ +export function showAccountList(entries: AccountListEntry[], defaults: AccountChainDefault[]): void { + console.log("Compose accounts:"); + for (const entry of entries) { + console.log(` ${entry.alias}: ${entry.address}`); + if (entry.foundryAccount) { + console.log(` Foundry keystore: ${entry.foundryAccount}`); + } + } + + for (const chainDefault of defaults) { + console.log(` Default for ${chainDefault.chainKey}: ${chainDefault.alias}`); + } +} + +/** Prints the result of registering an account alias. */ +export function showAccountRegistered(result: AccountSetupSummary): void { + console.log(); + console.log(green("Account registered")); + console.log(` Alias: ${result.alias}`); + console.log(` Address: ${result.address}`); + + if (result.foundryAccount) { + console.log(` Foundry keystore: ${result.foundryAccount}`); + } + if (result.chainKey) { + console.log(` Default chain: ${result.chainKey}`); + } + + console.log(); + console.log(green("Next steps")); + let step = 1; + if (result.framework === "hardhat") { + if (result.keyVariableName) { + console.log(` ${green(`${step}.`)} Store the signer key in Hardhat's keystore:`); + console.log(` npx hardhat keystore set ${result.keyVariableName}`); + } else { + const network = result.chainKey ? `'${result.chainKey}'` : "selected"; + console.log(` ${green(`${step}.`)} Configure the ${network} network's signer in hardhat.config.ts.`); + console.log(" Store its key using the variable or secret manager configured there."); + } + console.log(" Use a key whose address matches the registered public address above."); + step += 1; + } else if (result.foundryAccount && !result.foundryKeystoreExists) { + console.log(` ${green(`${step}.`)} Import the signer into Foundry's keystore:`); + console.log(` cast wallet import ${result.foundryAccount}`); + console.log(" Enter the key at Foundry's prompt, not in Compose."); + step += 1; + } + + const checkCommand = result.chainKey + ? `compose account check ${result.alias} --chain ${result.chainKey}` + : `compose account check ${result.alias} --chain `; + const checkDescription = result.chainKey + ? "Verify the configured signer matches the registered address:" + : "Choose a chain and verify the signer matches the registered address:"; + console.log(` ${green(`${step}.`)} ${checkDescription}`); + console.log(` ${checkCommand}`); + console.log(); + console.log(dim("Enter private keys only in the framework; Compose stores the public address and account reference.")); +} + +/** Prints the result of removing an account alias. */ +export function showAccountRemoved(alias: string): void { + console.log(`Removed Compose account alias '${alias}'. Native framework credentials were not changed.`); +} diff --git a/cli/src/modules/accounts/types.ts b/cli/src/modules/accounts/types.ts new file mode 100644 index 00000000..2b6a2204 --- /dev/null +++ b/cli/src/modules/accounts/types.ts @@ -0,0 +1,55 @@ +import type { Address } from "viem"; + +/** Non-secret Compose account alias and its framework-native reference. */ +export type ComposeAccountProfile = { + /** Public address expected from this account on every configured framework. */ + address: Address; + /** Foundry keystore alias. Hardhat selects the configured signer by address. */ + foundryAccount?: string; +}; + +/** Account information resolved for one deployment. */ +export type DeploymentAccount = ComposeAccountProfile & { + alias: string; +}; + +/** Account entry rendered by `compose account list`. */ +export type AccountListEntry = { + alias: string; + address: string; + foundryAccount?: string; +}; + +/** Chain default rendered by `compose account list`. */ +export type AccountChainDefault = { + chainKey: string; + alias: string; +}; + +/** Result of a successful `compose account check`. */ +export type AccountCheckSummary = { + alias: string; + address: string; + chainKey: string; +}; + +/** Result of a successful `compose account setup`. */ +export type AccountSetupSummary = { + alias: string; + address: string; + framework: "foundry" | "hardhat"; + foundryAccount?: string; + /** Whether the referenced Foundry keystore file already exists. */ + foundryKeystoreExists: boolean; + /** A single key variable detected in the selected Hardhat network config. */ + keyVariableName?: string; + /** Chain that now defaults to this alias. */ + chainKey?: string; +}; + +/** Result recorded in `ctx.state.account` after a successful action. */ +export type AccountActionResult = + | ({ action: "setup" } & AccountSetupSummary) + | ({ action: "check" } & AccountCheckSummary) + | { action: "list"; entries: AccountListEntry[]; defaults: AccountChainDefault[] } + | { action: "remove"; alias: string }; diff --git a/cli/src/modules/bytecodeValidation/module.ts b/cli/src/modules/bytecodeValidation/module.ts index efdff41c..693f8480 100644 --- a/cli/src/modules/bytecodeValidation/module.ts +++ b/cli/src/modules/bytecodeValidation/module.ts @@ -7,6 +7,7 @@ import type { IRPCAdapter } from "../../adapters/IRPCAdapter/interface"; import type { IDiamondAdapter } from "../../adapters/IDiamondAdapter/interface"; import type { ComposeContext, ModuleState } from "../../context/types"; import type { VirtualStorageLayoutRecord } from "../validation/types"; +import { DEFAULT_INSTANCE } from "../lockFile/types"; import type { BytecodeValidationSummary, DeploymentBytecodeValidationResult, @@ -74,6 +75,7 @@ export const BytecodeValidationModule = { ): Promise { const diamondName = String(ctx.param.diamondName); const chainKey = String(ctx.param.chainKey); + const instance = String(ctx.param.instance ?? DEFAULT_INSTANCE); const diamondAddress = getAddress(String(ctx.param.diamondAddress)); const blockNumber = await dependencies.rpc.getBlockNumber(); let rawFacets; @@ -86,6 +88,7 @@ export const BytecodeValidationModule = { result: { diamondName, chainKey, + instance, diamondAddress, blockNumber, complete: false, @@ -138,6 +141,7 @@ export const BytecodeValidationModule = { const result: DeploymentBytecodeValidationResult = { diamondName, chainKey, + instance, diamondAddress, blockNumber, complete: facets.every((facet) => facet.uncertain === null), @@ -183,6 +187,7 @@ export const BytecodeValidationModule = { return [{ diamondName: String(child.param.diamondName), chainKey: String(child.param.chainKey), + instance: String(child.param.instance ?? DEFAULT_INSTANCE), diamondAddress: String(child.param.diamondAddress), message: deployment.error?.message ?? "Bytecode validation failed.", }]; diff --git a/cli/src/modules/bytecodeValidation/output.ts b/cli/src/modules/bytecodeValidation/output.ts index 358e6ece..62a94add 100644 --- a/cli/src/modules/bytecodeValidation/output.ts +++ b/cli/src/modules/bytecodeValidation/output.ts @@ -37,12 +37,12 @@ export function showBytecodeValidationReport(ctx: ComposeContext): void { for (const failure of state.result?.failures ?? []) { console.error(red("\nBytecode validation failed")); console.error(red(` ${failure.message}`)); - console.error(`${failure.diamondName} / ${failure.chainKey}`); + console.error(`${failure.diamondName} (${failure.chainKey}/${failure.instance})`); console.error(` ${failure.diamondAddress}`); } for (const deployment of state.result?.deployments ?? []) { - const scope = `${deployment.diamondName} / ${deployment.chainKey}`; + const scope = `${deployment.diamondName} (${deployment.chainKey}/${deployment.instance})`; if (deployment.introspectionError) { console.error(red("\nDiamond introspection error")); console.error(red(` ${deployment.introspectionError}`)); diff --git a/cli/src/modules/bytecodeValidation/types.ts b/cli/src/modules/bytecodeValidation/types.ts index a36b8637..46b63d5f 100644 --- a/cli/src/modules/bytecodeValidation/types.ts +++ b/cli/src/modules/bytecodeValidation/types.ts @@ -11,6 +11,7 @@ export type FacetBytecodeValidationResult = { export type DeploymentBytecodeValidationResult = { diamondName: string; chainKey: string; + instance: string; diamondAddress: Address; blockNumber: bigint; complete: boolean; @@ -25,6 +26,7 @@ export type BytecodeValidationSummary = { failures: Array<{ diamondName: string; chainKey: string; + instance: string; diamondAddress: string; message: string; }>; diff --git a/cli/src/modules/config/catalog.ts b/cli/src/modules/config/catalog.ts index a7c837ce..7f61ca3b 100644 --- a/cli/src/modules/config/catalog.ts +++ b/cli/src/modules/config/catalog.ts @@ -7,6 +7,12 @@ export const EMPTY_BASE: BaseDefinition = { optional: {}, }; +/** Name of the optional global library facet that exposes diamond upgrades. */ +export const UPGRADE_FACET_NAME = "DiamondUpgradeFacet"; + +/** Catalog key of the ownership base added when an upgradeable diamond has no owner. */ +export const DEFAULT_OWNER_BASE = "owner"; + /** * Sorts a record of base feature definitions by their `order` metadata property, * falling back to alphabetical label comparison when orders are equal or missing. diff --git a/cli/src/modules/config/module.ts b/cli/src/modules/config/module.ts index db173591..d039a09d 100644 --- a/cli/src/modules/config/module.ts +++ b/cli/src/modules/config/module.ts @@ -2,7 +2,7 @@ import fs from "node:fs/promises"; import path from "node:path"; import { ComposeContext } from "../../context/types"; import { BasesCatalog, BaseDefinition, BaseManifest } from "./types"; -import { sortBaseFeatures, EMPTY_BASE, getDiamondCompilerVersion } from "./catalog"; +import { sortBaseFeatures, EMPTY_BASE, UPGRADE_FACET_NAME, DEFAULT_OWNER_BASE, getDiamondCompilerVersion } from "./catalog"; import { resolveCatalogSelection, getAccessBases, getAvailableLibraryFacets, validateGroupedAccessFlags } from "./selection"; import { CLI_ROOT } from "../../utils/cliRoot"; @@ -15,6 +15,8 @@ import { CLI_ROOT } from "../../utils/cliRoot"; */ export const ConfigModule = { EMPTY_BASE, + UPGRADE_FACET_NAME, + DEFAULT_OWNER_BASE, getDiamondCompilerVersion, resolveCatalogSelection, getAccessBases, diff --git a/cli/src/modules/deployExecution/ignitionJournal.ts b/cli/src/modules/deployExecution/ignitionJournal.ts new file mode 100644 index 00000000..7511131e --- /dev/null +++ b/cli/src/modules/deployExecution/ignitionJournal.ts @@ -0,0 +1,34 @@ +import { isHex, type Hex } from "viem"; + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** Reads the confirmed transaction hash for one Ignition future from a JSONL journal. */ +export function parseIgnitionJournalTransactionHash(journal: string, futureId: string): Hex { + const confirmations: unknown[] = []; + + for (const [index, line] of journal.split(/\r?\n/).entries()) { + if (!line.trim()) continue; + let record: unknown; + try { + record = JSON.parse(line) as unknown; + } catch (error) { + throw new Error(`Invalid JSON in Hardhat Ignition journal at line ${index + 1}.`, { cause: error }); + } + if (!isRecord(record) || record.type !== "TRANSACTION_CONFIRM" || record.futureId !== futureId) continue; + + const receipt = record.receipt; + if (isRecord(receipt) && receipt.status === "SUCCESS") confirmations.push(record.hash); + } + + if (confirmations.length === 0) { + throw new Error(`Hardhat Ignition journal has no successful transaction for future '${futureId}'.`); + } + + const hash = confirmations.at(-1); + if (typeof hash !== "string" || !isHex(hash) || hash.length !== 66) { + throw new Error(`Hardhat Ignition journal contains an invalid transaction hash for future '${futureId}'.`); + } + return hash as Hex; +} diff --git a/cli/src/modules/deployExecution/module.ts b/cli/src/modules/deployExecution/module.ts new file mode 100644 index 00000000..8b9c5bd5 --- /dev/null +++ b/cli/src/modules/deployExecution/module.ts @@ -0,0 +1,398 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { isAddress, isHex, type Hex } from "viem"; +import type { ComposeContext } from "../../context/types"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import type { BroadcastTransaction } from "../../adapters/IFrameworkAdapter/types"; +import { runCommand } from "../../utils/exec"; +import { toPassthroughArgs } from "../../utils/args"; +import { toProjectRelativePath } from "../../utils/files"; +import type { DeployPlan } from "../deployPlan/types"; +import type { DeployExecutionResult, DeployResultFile } from "./types"; +import { getIgnitionDeploymentId, HARDHAT_IGNITION_MODULE_ID } from "../deployScript/model"; +import { parseIgnitionJournalTransactionHash } from "./ignitionJournal"; + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function requireAddress(value: unknown, label: string): Hex { + if (typeof value !== "string" || !isAddress(value)) { + throw new Error(`The deploy script reported an invalid ${label} address: ${String(value)}.`); + } + return value as Hex; +} + +function toTransactionHash(value: unknown): Hex | null { + return typeof value === "string" && isHex(value) && value.length === 66 ? (value as Hex) : null; +} + +/** The framework's deploy result file, when it captures one. */ +type DeployCapture = { + /** Absolute path of the result file. */ + path: string; + /** Project-relative path used in messages. */ + displayPath: string; +}; + +/** Resolves the active capture file for the adapter, or null when it uses a broadcast. */ +function resolveCapture(adapter: IFrameworkAdapter, projectRoot: string): DeployCapture | null { + const capturePath = adapter.getManagedDeployResultPath(projectRoot); + if (!capturePath) return null; + return { path: capturePath, displayPath: toProjectRelativePath(projectRoot, capturePath) }; +} + +/** Reads the result file when present; parse errors still fail hard. */ +async function readOptionalResultFile( + resultPath: string, + displayPath: string, +): Promise { + let raw: string; + try { + raw = await fs.readFile(resultPath, "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; + throw new Error(`Unable to read ${displayPath}: ${(error as Error).message}`, { cause: error }); + } + + try { + return JSON.parse(raw) as DeployResultFile; + } catch (error) { + throw new Error(`Unable to parse ${displayPath}: ${(error as Error).message}`, { + cause: error, + }); + } +} + +/** + * Validates a result file against the plan and extracts the deployment. + * + * Any mismatch (stale script, wrong chain, facet drift) fails hard so a + * stale script can never be verified and recorded as current. + * + * @param raw - The parsed result file. + * @param plan - The resolved deployment plan. + * @param displayPath - Project-relative path of the result file, used in messages. + * @param expectedDeployer - The signer resolved for this execution, when known. + * @returns The reported diamond and facet addresses. + */ +function validateResult( + raw: DeployResultFile, + plan: DeployPlan, + displayPath: string, + expectedDeployer: Hex | null, +): { diamond: Hex; facets: Record; deployer?: Hex; ignitionDeploymentId?: string } { + if (!isRecord(raw)) { + throw new Error(`${displayPath} must contain a JSON object.`); + } + if (raw.mode !== "deploy") { + throw new Error(`${displayPath} has an unexpected mode: ${String(raw.mode)}.`); + } + if (String(raw.planHash).toLowerCase() !== plan.planHash.toLowerCase()) { + throw new Error( + `${displayPath} was written by a different plan (plan hash mismatch). Re-run 'compose deploy' to regenerate the script.`, + ); + } + if (raw.chainId !== plan.chain.chainId) { + throw new Error( + `The deploy script targeted chain id ${String(raw.chainId)}; expected ${plan.chain.chainId}.`, + ); + } + if (raw.chainKey !== plan.chain.chainKey) { + throw new Error( + `The deploy script targeted chain '${String(raw.chainKey)}'; expected '${plan.chain.chainKey}'.`, + ); + } + if (raw.instance !== plan.instance) { + throw new Error( + `The deploy script targeted instance '${String(raw.instance)}'; expected '${plan.instance}'.`, + ); + } + if (raw.framework !== plan.framework) { + throw new Error( + `The deploy script ran under framework '${String(raw.framework)}'; expected '${plan.framework}'.`, + ); + } + + let ignitionDeploymentId: string | undefined; + if (plan.framework === "hardhat") { + const expectedId = getIgnitionDeploymentId(plan, expectedDeployer); + if (raw.ignitionDeploymentId !== expectedId) { + throw new Error( + `${displayPath} has an unexpected Hardhat Ignition deployment ID. Re-run 'compose deploy' to regenerate the runner.`, + ); + } + ignitionDeploymentId = expectedId; + } + + const diamond = requireAddress(raw.diamond, "diamond"); + const deployer = typeof raw.deployer === "string" + ? requireAddress(raw.deployer, "deployer") + : undefined; + if (expectedDeployer && !deployer) { + throw new Error( + plan.account + ? `${displayPath} is missing the selected account address.` + : `${displayPath} is missing the framework default signer address.`, + ); + } + if (deployer && expectedDeployer && deployer.toLowerCase() !== expectedDeployer.toLowerCase()) { + const expected = plan.account + ? `Compose account '${plan.account.alias}' at ${plan.account.address}` + : `the framework default signer at ${expectedDeployer}`; + throw new Error(`The deploy script used signer ${deployer}; expected ${expected}.`); + } + if (!isRecord(raw.facets)) { + throw new Error(`${displayPath} is missing the facets object.`); + } + + const desired = new Set(plan.facets.map((facet) => facet.name)); + const reported = new Set(Object.keys(raw.facets)); + const missing = [...desired].filter((name) => !reported.has(name)); + const unexpected = [...reported].filter((name) => !desired.has(name)); + if (missing.length > 0 || unexpected.length > 0) { + throw new Error( + `The deploy script reported facets that do not match the plan (missing: ${missing.join(", ") || "none"}; unexpected: ${unexpected.join(", ") || "none"}).`, + ); + } + + const facets: Record = {}; + for (const name of desired) { + facets[name] = requireAddress(raw.facets[name], `facet '${name}'`); + } + return { diamond, facets, deployer, ...(ignitionDeploymentId ? { ignitionDeploymentId } : {}) }; +} + +/** + * Derives the deployment from the framework's broadcast transactions. + * + * Used by frameworks that cannot write a result file (Foundry restricts + * cheatcode file writes). Facet transactions are consumed in plan order; + * the diamond is the last remaining matching deployment. + */ +function deriveFromBroadcast( + broadcast: BroadcastTransaction[], + plan: DeployPlan, + expectedDeployer: Hex | null, +): { diamond: Hex; facets: Record; txHash: Hex | null; deployer?: Hex } { + const remaining = [...broadcast]; + const facets: Record = {}; + + for (const facet of plan.facets) { + const index = remaining.findIndex((transaction) => transaction.contractName === facet.contractName); + if (index === -1) { + throw new Error( + `The framework did not report a deployment for facet '${facet.name}' (${facet.contractName}). Re-run 'compose deploy --broadcast' and check the framework output.`, + ); + } + const [transaction] = remaining.splice(index, 1); + facets[facet.name] = requireAddress(transaction.contractAddress, `facet '${facet.name}'`); + } + + let diamondIndex = -1; + for (let index = remaining.length - 1; index >= 0; index -= 1) { + if (remaining[index].contractName === plan.diamond.contractName) { + diamondIndex = index; + break; + } + } + if (diamondIndex === -1) { + throw new Error( + `The framework did not report a deployment of '${plan.diamond.contractName}'. Re-run 'compose deploy --broadcast' and check the framework output.`, + ); + } + + const diamondTransaction = remaining[diamondIndex]; + const deployer = typeof diamondTransaction.from === "string" + ? requireAddress(diamondTransaction.from, "deployer") + : undefined; + if (expectedDeployer && !deployer) { + throw new Error( + plan.account + ? "The Foundry broadcast did not report the deployer address for the selected Compose account." + : "The Foundry broadcast did not report the deployer address for the framework default signer.", + ); + } + if (deployer && expectedDeployer && deployer.toLowerCase() !== expectedDeployer.toLowerCase()) { + throw new Error( + plan.account + ? `Foundry broadcast signer ${deployer} does not match Compose account '${plan.account.alias}' at ${plan.account.address}.` + : `Foundry broadcast signer ${deployer} does not match the framework default signer at ${expectedDeployer}.`, + ); + } + return { + diamond: requireAddress(diamondTransaction.contractAddress, "diamond"), + facets, + txHash: toTransactionHash(diamondTransaction.txHash), + deployer, + }; +} + +/** + * Deploy execution module. + * + * Runs the managed script under the framework, then normalizes the + * deployment from the script's result file (Hardhat) or the framework's + * broadcast transactions (Foundry). Framework output goes to the inherited + * stdio, so signing and network prompts stay in the framework's hands. + */ +export const DeployExecutionModule = { + /** + * Executes the managed deploy script and normalizes its result. + * + * Stores the result in `ctx.state.deployExecution` on success and records a + * failure state before rethrowing. + * + * @param ctx - The compose context with passthrough arguments. + * @param plan - The resolved deployment plan. + * @param scriptPath - Absolute path of the managed script to run. + * @param adapter - The framework adapter building the command. + * @param runnerPath - Absolute path of the transient Hardhat runner. + * @param expectedSigner - The signer already resolved by the caller; when + * omitted, it is resolved here. Explicit null means no signer is known. + * @returns The context with `state.deployExecution` populated. + * @throws {Error} If the framework command fails or the result is invalid. + */ + async execute( + ctx: ComposeContext, + plan: DeployPlan, + scriptPath: string, + adapter: IFrameworkAdapter, + runnerPath: string | null = adapter.getManagedDeployRunnerPath(plan.projectRoot), + expectedSigner?: Hex | null, + ): Promise { + const projectRoot = plan.projectRoot; + const capture = resolveCapture(adapter, projectRoot); + + try { + const expectedDeployer = expectedSigner === undefined + ? await adapter.resolveDeploySigner({ + projectRoot, + chainKey: plan.chain.chainKey, + rpcUrl: plan.chain.rpcUrl, + chainId: plan.chain.chainId, + account: plan.account, + passthrough: toPassthroughArgs(ctx.param.passthrough), + }) + : expectedSigner; + if (capture) { + // The capture file lives under `.compose/`, which the adapter keeps + // gitignored; drop a stale capture so a failed run cannot look successful. + await fs.rm(capture.path, { force: true }); + } + + const command = adapter.createDeployCommand({ + chainId: plan.chain.chainId, + chainKey: plan.chain.chainKey, + passthrough: toPassthroughArgs(ctx.param.passthrough), + projectRoot, + rpcUrl: plan.chain.rpcUrl, + account: plan.account, + scriptPath, + runnerPath, + mode: "broadcast", + }); + await runCommand(command.command, command.args, { + cwd: projectRoot, + ...(command.env ? { env: command.env } : {}), + }); + + const rawResult = capture + ? await readOptionalResultFile(capture.path, capture.displayPath) + : null; + const broadcast = await adapter.readBroadcastTransactions( + projectRoot, + scriptPath, + plan.chain.chainId, + ); + + let diamond: Hex; + let facets: Record; + let deployer: Hex | undefined; + let diamondTxHash: Hex | null; + let ignitionDeploymentId: string | undefined; + if (rawResult && capture) { + const validated = validateResult(rawResult, plan, capture.displayPath, expectedDeployer); + ({ diamond, facets, deployer, ignitionDeploymentId } = validated); + if (plan.framework === "hardhat") { + const hardhatDeploymentId = getIgnitionDeploymentId(plan, expectedDeployer); + const journalPath = path.join( + projectRoot, + "ignition", + "deployments", + hardhatDeploymentId, + "journal.jsonl", + ); + let journal: string; + try { + journal = await fs.readFile(journalPath, "utf8"); + } catch (error) { + throw new Error( + `Unable to read Hardhat Ignition journal for deployment '${hardhatDeploymentId}': ${(error as Error).message}`, + { cause: error }, + ); + } + diamondTxHash = parseIgnitionJournalTransactionHash( + journal, + `${HARDHAT_IGNITION_MODULE_ID}#Diamond`, + ); + } else { + diamondTxHash = toTransactionHash( + isRecord(rawResult.transactions) ? rawResult.transactions.diamond : undefined, + ); + } + } else { + if (plan.framework === "hardhat") { + throw new Error( + `Hardhat did not write the managed deploy result at ${capture?.displayPath ?? "the configured result path"}.`, + ); + } + const derived = deriveFromBroadcast(broadcast, plan, expectedDeployer); + diamond = derived.diamond; + facets = derived.facets; + deployer = derived.deployer; + diamondTxHash = derived.txHash; + } + + if (plan.framework === "foundry") { + diamondTxHash ??= toTransactionHash( + broadcast.find((transaction) => transaction.contractName === plan.diamond.contractName)?.txHash, + ); + } + if (!diamondTxHash) { + throw new Error( + "No diamond deployment transaction was recorded. Re-run 'compose deploy --broadcast' and check the framework output.", + ); + } + + const result: DeployExecutionResult = { + diamond, + facets, + ...(deployer ? { deployer } : {}), + ...(ignitionDeploymentId ? { ignitionDeploymentId } : {}), + transactions: { diamond: diamondTxHash }, + }; + ctx.state.deployExecution = { success: true, result, error: null }; + return ctx; + } catch (error) { + ctx.state.deployExecution = { + success: false, + result: null, + error: { + code: "DEPLOY_EXECUTION_FAILED", + message: error instanceof Error ? error.message : "Deployment failed.", + nativeError: error, + }, + }; + throw error; + } finally { + if (plan.framework === "hardhat" && runnerPath) { + try { + await fs.rm(runnerPath, { force: true }); + } catch { + // Do not convert a completed broadcast into a failure because cleanup failed. + } + } + } + }, +}; diff --git a/cli/src/modules/deployExecution/types.ts b/cli/src/modules/deployExecution/types.ts new file mode 100644 index 00000000..389c79e8 --- /dev/null +++ b/cli/src/modules/deployExecution/types.ts @@ -0,0 +1,29 @@ +import type { Hex } from "viem"; + +/** The normalized result of a managed deploy script run. */ +export type DeployExecutionResult = { + diamond: Hex; + facets: Record; + /** Actual account used by the framework, when reported. */ + deployer?: Hex; + /** Hardhat Ignition journal identity, when the deployment used Ignition. */ + ignitionDeploymentId?: string; + transactions: { + diamond: Hex; + }; +}; + +/** Permissive shape of the JSON written by the managed script. */ +export type DeployResultFile = { + mode?: unknown; + planHash?: unknown; + framework?: unknown; + chainKey?: unknown; + chainId?: unknown; + instance?: unknown; + diamond?: unknown; + facets?: unknown; + deployer?: unknown; + transactions?: unknown; + ignitionDeploymentId?: unknown; +}; diff --git a/cli/src/modules/deployGeneration/model.ts b/cli/src/modules/deployGeneration/model.ts deleted file mode 100644 index 98237048..00000000 --- a/cli/src/modules/deployGeneration/model.ts +++ /dev/null @@ -1,97 +0,0 @@ -import path from "node:path"; -import { ComposeContext, ModuleState } from "../../context/types"; -import { ScaffoldingModule } from "../scaffolding/module"; -import { ScaffoldMapEntry, SelectedFacet, SelectedFacetSource } from "../scaffolding/types"; -import { DeployFacetEntry, DeployFacetGroup, DeployGenerationModel } from "./types"; -import { toPosixPath } from "../../utils/files"; - -/** - * Classifies a selected facet source into a deploy facet group. - * Base-required facets and extensions are grouped as "base"; others as "library". - * - * @param source - The source type of the selected facet. - * @returns The deploy group classification. - */ -function classifyDeployGroup(source: SelectedFacetSource): DeployFacetGroup { - if (source === "base-required" || source === "extension") { - return "base"; - } - return "library"; -} - -/** - * Extracts scaffold map entries from the compose context state. - * - * @param ctx - The compose context containing scaffold map state. - * @returns The list of scaffold map entries. - * @throws {Error} If the scaffold map is missing or in a failed state. - */ -function getScaffoldEntries(ctx: ComposeContext): ScaffoldMapEntry[] { - const state = ctx.state.scaffoldMap as ModuleState<{ entries: ScaffoldMapEntry[] }> | undefined; - if (!state?.success || !state.result) { - throw new Error("Cannot generate deploy script: scaffold map is missing."); - } - return state.result.entries; -} - -/** - * Resolves the deploy generation model by combining scaffold entries with selected facets. - * Produces ordered deploy facet entries with import paths relative to the project root, - * grouped by base facets first, then library facets. - * - * @param ctx - The compose context with project state and parameters. - * @param scriptRoot - Directory where the deploy script will be written. - * @param outputFileName - Name of the output deploy script file. - * @returns The deploy generation model with output path and ordered facet entries. - * @throws {Error} If project root, script root, or scaffold entries are invalid. - */ -export function resolveDeployGenerationModel( - ctx: ComposeContext, - scriptRoot: string, - outputFileName: string, -): DeployGenerationModel { - const projectRoot = String(ctx.param.projectRoot ?? ""); - if (!projectRoot) { - throw new Error("Cannot generate deploy script: project root is empty."); - } - if (!scriptRoot) { - throw new Error("Cannot generate deploy script: script root is empty."); - } - - const scaffoldEntries = getScaffoldEntries(ctx); - const scaffoldByFacetName = new Map(scaffoldEntries.map((entry) => [entry.facetName, entry])); - const selectedFacets = ScaffoldingModule.getSelectedFacets(ctx); - - const deployEntries = selectedFacets.map((facet: SelectedFacet): DeployFacetEntry => { - const scaffoldEntry = scaffoldByFacetName.get(facet.name); - if (!scaffoldEntry) { - throw new Error(`Cannot generate deploy script: scaffold entry not found for ${facet.name}.`); - } - - const importPath = scaffoldEntry.origin === "package" - ? scaffoldEntry.targetPath - : toPosixPath(path.relative(projectRoot, scaffoldEntry.targetPath)); - if (!importPath) { - throw new Error(`Cannot generate deploy script: invalid import path for ${facet.name}.`); - } - - return { - facetName: facet.name, - contractName: scaffoldEntry.contractName, - importPath, - source: facet.source, - origin: scaffoldEntry.origin, - group: classifyDeployGroup(facet.source), - }; - }); - - const facets = [ - ...deployEntries.filter((entry) => entry.group === "base"), - ...deployEntries.filter((entry) => entry.group === "library"), - ]; - - return { - outputPath: path.join(scriptRoot, outputFileName), - facets, - }; -} diff --git a/cli/src/modules/deployGeneration/module.ts b/cli/src/modules/deployGeneration/module.ts deleted file mode 100644 index 7a34d6ad..00000000 --- a/cli/src/modules/deployGeneration/module.ts +++ /dev/null @@ -1,65 +0,0 @@ -import fs from "node:fs/promises"; -import path from "node:path"; -import { ComposeContext } from "../../context/types"; -import { - renderFoundryDeployScript, - renderHardhatEthersDeployScript, - renderHardhatViemDeployScript, -} from "./renderers"; -import { resolveDeployGenerationModel } from "./model"; - -/** - * Module responsible for generating framework-specific deploy scripts. - */ -export const DeployGenerationModule = { - /** - * Generates a deploy script for the selected framework and toolbox, - * writes it to disk, and updates the compose context state. - * - * @param ctx - The compose context with project parameters and state. - * @param scriptRoot - Directory where the deploy script will be written. - * @returns The updated compose context with generation results. - * @throws {Error} If the framework is unsupported or file operations fail. - */ - async generateDeployScript( - ctx: ComposeContext, - scriptRoot: string, - ): Promise { - const framework = String(ctx.param.framework ?? "foundry"); - const toolbox = String(ctx.param.toolbox ?? "ethers"); - const outputFileName = framework === "foundry" ? "Deploy.s.sol" : "deploy.ts"; - const model = resolveDeployGenerationModel(ctx, scriptRoot, outputFileName); - let source: string; - - if (framework === "foundry") { - source = await renderFoundryDeployScript(model); - } else if (framework === "hardhat" && toolbox === "viem") { - source = await renderHardhatViemDeployScript(model); - } else if (framework === "hardhat") { - source = await renderHardhatEthersDeployScript(model); - } else { - throw new Error(`Cannot generate deploy script: unsupported framework ${framework}.`); - } - - await fs.mkdir(path.dirname(model.outputPath), { recursive: true }); - await fs.writeFile(model.outputPath, source, "utf8"); - - ctx.state.generateDeployScript = { - success: true, - result: { - outputPath: model.outputPath, - facets: model.facets.map((facet) => ({ - facetName: facet.facetName, - contractName: facet.contractName, - importPath: facet.importPath, - group: facet.group, - })), - framework, - toolbox: framework === "hardhat" ? toolbox : null, - }, - error: null, - }; - - return ctx; - }, -}; diff --git a/cli/src/modules/deployGeneration/renderers.ts b/cli/src/modules/deployGeneration/renderers.ts deleted file mode 100644 index 039f35d4..00000000 --- a/cli/src/modules/deployGeneration/renderers.ts +++ /dev/null @@ -1,101 +0,0 @@ -import { DeployFacetEntry, DeployGenerationModel } from "./types"; -import { toCamelCase } from "../../utils/strings"; -import { loadTemplate } from "../../utils/codegen"; -import { renderFacetSections } from "../facetSections"; - -/** - * Renders a Foundry (Solidity) deploy script that deploys a Diamond proxy - * with all facets in base-first, library-second order. - * - * @param model - The deploy generation model with facet entries and output path. - * @returns The complete Solidity deploy script source code. - */ -export async function renderFoundryDeployScript(model: DeployGenerationModel): Promise { - const template = await loadTemplate("deploy", "foundry-deploy.sol"); - - const imports = model.facets - .map((facet) => { - const importPath = facet.origin === "local" - ? `../${facet.importPath}` - : facet.importPath; - return `import {${facet.contractName}} from "${importPath}";`; - }) - .join("\n"); - let index = 0; - - const renderDeployLine = (facet: DeployFacetEntry): string => { - const line = ` facets[${index}] = address(new ${facet.contractName}()); - console.log("${facet.contractName}:", facets[${index}]);`; - index += 1; - return line; - }; - - const { baseLines, libraryLines } = renderFacetSections(model.facets, renderDeployLine, "\n"); - - return template - .replace("{{IMPORTS}}", imports) - .replace("{{FACET_COUNT}}", String(model.facets.length)) - .replace("{{BASE_LINES}}", baseLines) - .replace("{{LIBRARY_LINES}}", libraryLines); -} - -/** - * Renders a single facet deployment line using Hardhat + ethers.js. - * - * @param facet - The facet entry to deploy. - * @returns TypeScript code that deploys the facet and pushes its address. - */ -function renderHardhatEthersFacetDeploy(facet: DeployFacetEntry): string { - const variableName = toCamelCase(facet.contractName) || "facet"; - return ` const ${variableName} = await ethers.deployContract("${facet.contractName}"); - await ${variableName}.waitForDeployment(); - console.log("${facet.contractName}:", await ${variableName}.getAddress()); - facets.push(await ${variableName}.getAddress());`; -} - -/** - * Renders a single facet deployment line using Hardhat + viem. - * - * @param facet - The facet entry to deploy. - * @returns TypeScript code that deploys the facet and pushes its address. - */ -function renderHardhatViemFacetDeploy(facet: DeployFacetEntry): string { - const variableName = toCamelCase(facet.contractName) || "facet"; - return ` const ${variableName} = await viem.deployContract("${facet.contractName}"); - console.log("${facet.contractName}:", ${variableName}.address); - facets.push(${variableName}.address);`; -} - -/** - * Renders a complete Hardhat + ethers.js deploy script that deploys a Diamond proxy. - * - * @param model - The deploy generation model with facet entries and output path. - * @returns The complete TypeScript deploy script source code. - */ -export async function renderHardhatEthersDeployScript(model: DeployGenerationModel): Promise { - const [template, { baseLines, libraryLines }] = await Promise.all([ - loadTemplate("deploy", "hardhat-ethers-deploy.ts"), - renderFacetSections(model.facets, renderHardhatEthersFacetDeploy, "\n\n"), - ]); - - return template - .replace("{{BASE_LINES}}", baseLines) - .replace("{{LIBRARY_LINES}}", libraryLines); -} - -/** - * Renders a complete Hardhat + viem deploy script that deploys a Diamond proxy. - * - * @param model - The deploy generation model with facet entries and output path. - * @returns The complete TypeScript deploy script source code. - */ -export async function renderHardhatViemDeployScript(model: DeployGenerationModel): Promise { - const [template, { baseLines, libraryLines }] = await Promise.all([ - loadTemplate("deploy", "hardhat-viem-deploy.ts"), - renderFacetSections(model.facets, renderHardhatViemFacetDeploy, "\n\n"), - ]); - - return template - .replace("{{BASE_LINES}}", baseLines) - .replace("{{LIBRARY_LINES}}", libraryLines); -} diff --git a/cli/src/modules/deployGeneration/types.ts b/cli/src/modules/deployGeneration/types.ts deleted file mode 100644 index d13617c3..00000000 --- a/cli/src/modules/deployGeneration/types.ts +++ /dev/null @@ -1,17 +0,0 @@ -import { FacetOrigin, SelectedFacetSource } from "../scaffolding/types"; - -export type DeployFacetGroup = "base" | "library"; - -export type DeployFacetEntry = { - facetName: string; - contractName: string; - importPath: string; - source: SelectedFacetSource; - origin: FacetOrigin; - group: DeployFacetGroup; -}; - -export type DeployGenerationModel = { - outputPath: string; - facets: DeployFacetEntry[]; -}; diff --git a/cli/src/modules/deployPlan/hash.ts b/cli/src/modules/deployPlan/hash.ts new file mode 100644 index 00000000..a770755e --- /dev/null +++ b/cli/src/modules/deployPlan/hash.ts @@ -0,0 +1,50 @@ +import type { Hex } from "viem"; +import type { IHashingAdapter } from "../../adapters/IHashingAdapter/interface"; +import type { DeployPlan } from "./types"; + +/** A plan without its hash, ready for canonical serialization. */ +export type HashablePlan = Omit; + +/** + * Serializes the deployment target and desired composition as canonical JSON. + * + * Facets are sorted by name so reordering registrations does not change the + * hash, while every other field is included verbatim so drift in the target + * chain, diamond, or facet set produces a new hash. Source identity comes from + * the artifact-facing import specifier, not the absolute source path: checkouts + * and CI workspaces live at different paths, but the same project must produce + * the same plan. + * + * Observed state (the existing lock record and its diff) is intentionally + * excluded, as are the RPC endpoint and selected signer: those are access and + * execution configuration, not part of the deployment identity. Execution + * still resolves the effective signer (including a framework default) before + * running, validates the reported deployer against it, and scopes the Hardhat + * Ignition deployment ID to it. + */ +export function canonicalPlanJson(plan: HashablePlan): string { + const facets = [...plan.facets] + .map((facet) => ({ + contract: facet.contractName, + name: facet.name, + importSpec: facet.importSpec, + })) + .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0)); + + return JSON.stringify({ + chain: { chainId: plan.chain.chainId, key: plan.chain.chainKey }, + diamond: { + contract: plan.diamond.contractName, + name: plan.diamondName, + importSpec: plan.diamond.importSpec, + }, + facets, + framework: plan.framework, + instance: plan.instance, + }); +} + +/** Computes the plan hash used to bind generated scripts to a plan. */ +export function computePlanHash(plan: HashablePlan, hashing: IHashingAdapter): Hex { + return hashing.keccak256(canonicalPlanJson(plan)); +} diff --git a/cli/src/modules/deployPlan/module.ts b/cli/src/modules/deployPlan/module.ts new file mode 100644 index 00000000..a8d0b9f4 --- /dev/null +++ b/cli/src/modules/deployPlan/module.ts @@ -0,0 +1,281 @@ +import path from "node:path"; +import type { ComposeContext, ModuleState } from "../../context/types"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import type { IHashingAdapter } from "../../adapters/IHashingAdapter/interface"; +import type { ValidationProject } from "../validation/project"; +import type { ResolvedFacetSource } from "../validation/types"; +import { selectDiamond } from "../facetConfig/selection"; +import { resolveChainConfig } from "../../utils/chainConfig"; +import { toPosixPath, toRelativeImport } from "../../utils/files"; +import { VERSION } from "../../utils/metadata"; +import { + assertSafeSolidityImportSpec, + assertSolidityContractName, +} from "../../utils/solidityIdentifiers"; +import { UPGRADE_FACET_NAME } from "../config/catalog"; +import { LockFileModule } from "../lockFile/module"; +import { DEFAULT_INSTANCE, type ComposeLock } from "../lockFile/types"; +import { validateOptions } from "../../adapters/IRPCAdapter/validation"; +import { resolveAccountProfile } from "../accounts/config"; +import type { DeploymentAccount } from "../accounts/types"; +import { computePlanHash } from "./hash"; +import type { DeployPlan, PlannedFacet } from "./types"; + +const INSTANCE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; +const RESERVED_INSTANCES = new Set(["__proto__", "constructor", "prototype"]); + +type DiamondConfig = { + contract?: unknown; + facets?: Record; +}; + +/** + * Rejects instance names that cannot safely become compose.lock object keys. + * + * @param instance - The requested deployment instance name. + * @throws {Error} If the instance is empty, malformed, or a reserved object key. + */ +export function assertValidInstance(instance: string): void { + if (!INSTANCE_PATTERN.test(instance) || RESERVED_INSTANCES.has(instance)) { + throw new Error( + `Invalid deployment instance '${instance}'. Use letters, digits, '.', '_' or '-' and avoid reserved object keys.`, + ); + } +} + +/** + * Resolves the import path for a facet source as seen from the managed script. + * + * Compose package files (under `node_modules/@perfect-abstractions/compose` + * or `lib/Compose/src`) keep their package specifier; project files become + * relative imports from the framework script root. + * + * @param sourcePath - Absolute path of the resolved facet source. + * @param projectRoot - Absolute project root. + * @param scriptRoot - Absolute directory holding the managed deploy script. + * @returns The import specifier to use in the generated script. + * @throws {Error} If the source is neither a package file nor inside the project. + */ +export function resolveFacetImportSpec( + sourcePath: string, + projectRoot: string, + scriptRoot: string, +): string { + const normalized = path.resolve(sourcePath); + const composePackageRoots = [ + path.join(projectRoot, "node_modules", "@perfect-abstractions", "compose"), + path.join(projectRoot, "lib", "Compose", "src"), + ]; + for (const packageRoot of composePackageRoots) { + const relative = path.relative(packageRoot, normalized); + if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) { + const spec = `@perfect-abstractions/compose/${toPosixPath(relative)}`; + assertSafeSolidityImportSpec(spec, `Compose package source ${JSON.stringify(sourcePath)}`); + return spec; + } + } + + const relativeToProject = path.relative(projectRoot, normalized); + if (!relativeToProject || relativeToProject.startsWith("..") || path.isAbsolute(relativeToProject)) { + throw new Error( + `Facet source ${JSON.stringify(sourcePath)} is outside the project and not a Compose package file. Fix its path in compose.json or reinstall the facet.`, + ); + } + const spec = toRelativeImport(toPosixPath(path.relative(scriptRoot, normalized))); + assertSafeSolidityImportSpec(spec, `facet source ${JSON.stringify(sourcePath)}`); + return spec; +} + +/** + * Pairs compose.json facet entries with their resolved sources, preserving + * registration order and rejecting any mismatch. + */ +function zipFacets( + diamondName: string, + diamondConfig: DiamondConfig, + resolvedFacets: ResolvedFacetSource[], + projectRoot: string, + scriptRoot: string, +): PlannedFacet[] { + const configured = Object.entries(diamondConfig.facets ?? {}); + if (configured.length !== resolvedFacets.length) { + throw new Error( + `Diamond '${diamondName}' lists ${configured.length} facets in compose.json but ${resolvedFacets.length} sources were resolved.`, + ); + } + + const seenContracts = new Map(); + return configured.map(([name, entry], index) => { + const resolved = resolvedFacets[index]; + const reference = typeof (entry as { contract?: unknown })?.contract === "string" + ? String((entry as { contract: string }).contract) + : ""; + const expectedName = reference.includes(":") + ? reference.slice(reference.lastIndexOf(":") + 1) + : name; + const context = `facet ${JSON.stringify(name)} in diamond ${JSON.stringify(diamondName)}`; + assertSolidityContractName(expectedName, `${context} reference in compose.json`); + assertSolidityContractName(resolved.contractName, context); + if (resolved.contractName !== expectedName) { + throw new Error( + `Facet '${name}' resolved to '${resolved.contractName}' instead of '${expectedName}'. Check compose.json.`, + ); + } + const duplicateOf = seenContracts.get(resolved.contractName); + if (duplicateOf) { + throw new Error( + `Facets '${duplicateOf}' and '${name}' both resolve to contract '${resolved.contractName}'. ` + + "Each facet must use a distinct contract name in the managed deploy script.", + ); + } + seenContracts.set(resolved.contractName, name); + + return { + name, + contractName: resolved.contractName, + sourcePath: resolved.sourcePath, + importSpec: resolveFacetImportSpec(resolved.sourcePath, projectRoot, scriptRoot), + }; + }); +} + +/** + * Deploy plan module. + * + * Resolves the target diamond, chain, and instance against compose.json and + * the existing compose.lock record, then produces the plan the script + * generator and executor operate on. The plan is pure input parsing plus lock + * comparison; it never touches the chain. + */ +export const DeployPlanModule = { + /** + * Builds the deployment plan for the selected diamond, chain, and instance. + * + * Stores the plan in `ctx.state.deployPlan`. + * + * @param ctx - The compose context with project parameters. + * @param dependencies - The loaded validation project, framework adapter, and hashing adapter. + * @returns The context with `state.deployPlan` populated. + * @throws {Error} If the diamond, chain, or lock file cannot be resolved. + */ + async resolve( + ctx: ComposeContext, + dependencies: { + project: ValidationProject; + adapter: IFrameworkAdapter; + hashing: IHashingAdapter; + }, + ): Promise { + const { project, adapter, hashing } = dependencies; + const projectRoot = String(ctx.param.projectRoot); + const framework = String(ctx.param.framework) as DeployPlan["framework"]; + const diamondName = await selectDiamond( + ctx, + project.diamonds.map((diamond) => diamond.name), + "deploy", + { allowPrompt: false }, + ); + const diamond = project.diamonds.find((candidate) => candidate.name === diamondName); + if (!diamond) { + throw new Error(`Diamond '${diamondName}' was not resolved from compose.json.`); + } + + const instance = String(ctx.param.instance ?? DEFAULT_INSTANCE); + assertValidInstance(instance); + + const chain = await resolveChainConfig({ + chainKey: ctx.param.chain, + projectRoot, + rpcUrlOverride: ctx.param.rpcUrl, + }); + validateOptions({ rpcUrl: chain.rpcUrl, chainId: chain.chainId }); + + const composeJson = ctx.config.composeJson as { + accounts?: unknown; + diamonds?: Record; + } | undefined; + const accountAliasValue = ctx.param.account ?? chain.account; + let account: DeploymentAccount | null = null; + if (accountAliasValue !== undefined) { + if (typeof accountAliasValue !== "string") { + throw new Error("Account alias must be a string."); + } + account = resolveAccountProfile(composeJson?.accounts, accountAliasValue, framework); + } + + const diamondConfig = composeJson?.diamonds?.[diamondName]; + if (!diamondConfig) { + throw new Error(`Diamond '${diamondName}' is missing from compose.json.`); + } + const diamondReference = typeof diamondConfig.contract === "string" ? diamondConfig.contract : ""; + const referenceName = diamondReference.includes(":") + ? diamondReference.slice(diamondReference.lastIndexOf(":") + 1) + : ""; + const diamondContractName = referenceName || path.basename(diamond.sourcePath, ".sol"); + assertSolidityContractName( + diamondContractName, + `diamond ${JSON.stringify(diamondName)} in compose.json`, + ); + + const scriptRoot = adapter.getScriptRoot(projectRoot); + const facets = zipFacets(diamondName, diamondConfig, diamond.facets, projectRoot, scriptRoot); + if (facets.some((facet) => facet.contractName === diamondContractName)) { + throw new Error( + `The diamond contract '${diamondContractName}' is also registered as a facet. ` + + "Use a distinct contract name for the facet.", + ); + } + + ctx = await LockFileModule.readLockFile(ctx); + const lockState = ctx.state.lockFile as ModuleState<{ path: string; lock: ComposeLock } | null>; + if (!lockState.success) { + throw new Error(lockState.error?.message ?? "Failed to read compose.lock."); + } + const lock = lockState.result?.lock ?? LockFileModule.createEmptyLock(VERSION); + const existing = LockFileModule.getDeployment(lock, diamondName, chain.chainKey, instance) ?? null; + + let mode: DeployPlan["mode"] = existing ? "in-sync" : "fresh"; + let diff: DeployPlan["diff"] = null; + if (existing) { + const desired = new Set(facets.map((facet) => facet.name)); + const deployed = new Set(Object.keys(existing.facets)); + const added = [...desired].filter((name) => !deployed.has(name)); + const removed = [...deployed].filter((name) => !desired.has(name)); + if (ctx.param.redeploy) { + mode = "redeploy"; + } else if (added.length > 0 || removed.length > 0) { + mode = "diff"; + diff = { added, removed }; + } + } + + const validationState = ctx.state.validationProject as ModuleState<{ composeJsonPath: string }>; + const planBase = { + mode, + framework, + projectRoot, + composeJsonPath: validationState?.result?.composeJsonPath ?? path.join(projectRoot, "compose.json"), + diamondName, + diamond: { + contractName: diamondContractName, + sourcePath: diamond.sourcePath, + importSpec: resolveFacetImportSpec(diamond.sourcePath, projectRoot, scriptRoot), + }, + instance, + chain, + rpcUrlOverridden: ctx.param.rpcUrl !== undefined, + account, + facets, + existing, + diff, + upgradeable: facets.some((facet) => facet.name === UPGRADE_FACET_NAME), + }; + const plan: DeployPlan = { + ...planBase, + planHash: computePlanHash(planBase, hashing), + }; + + ctx.state.deployPlan = { success: true, result: plan, error: null }; + return ctx; + }, +}; diff --git a/cli/src/modules/deployPlan/output.ts b/cli/src/modules/deployPlan/output.ts new file mode 100644 index 00000000..9750f741 --- /dev/null +++ b/cli/src/modules/deployPlan/output.ts @@ -0,0 +1,79 @@ +import { dim, green, yellow } from "../../utils/terminal"; +import { safeRpcEndpoint } from "../../adapters/IRPCAdapter/utils"; +import type { DeployPlan } from "./types"; + +/** + * Prints the fresh/redeploy plan summary. + * + * @param plan - The resolved deployment plan. + */ +export function showDeployPlan(plan: DeployPlan): void { + console.log(); + console.log(`${green("Deploy plan")} ${dim(`(${plan.mode === "redeploy" ? "redeploy" : "fresh"})`)}`); + console.log(` Diamond: ${plan.diamondName} (${plan.diamond.contractName})`); + const rpcEndpoint = safeRpcEndpoint(plan.chain.rpcUrl) ?? "[invalid endpoint]"; + const rpcSource = plan.rpcUrlOverridden ? "CLI override" : "compose.json"; + console.log(` Chain: ${plan.chain.chainKey} (chain id ${plan.chain.chainId})`); + console.log(` RPC: ${rpcEndpoint} (${rpcSource}; credentials and path redacted)`); + console.log(plan.account + ? ` Signer: ${plan.account.alias} (${plan.account.address})` + : " Signer: framework default"); + console.log(` Instance: ${plan.instance}`); + console.log(` Facets (${plan.facets.length}):`); + for (const facet of plan.facets) { + console.log(` - ${facet.name} ${dim(`(${facet.importSpec})`)}`); + } + console.log( + ` Upgradeability: ${plan.upgradeable ? "upgradeable (DiamondUpgradeFacet present)" : "immutable (no upgrade facet)"}`, + ); + if (plan.mode === "redeploy" && plan.existing) { + console.log( + yellow(` Redeploy: the lock record at ${plan.existing.diamond} will be abandoned and replaced.`), + ); + } + console.log(dim(` Plan hash: ${plan.planHash}`)); + console.log(); +} + +/** + * Prints the in-sync summary when nothing needs to happen. + * + * @param plan - The resolved deployment plan with mode `in-sync`. + */ +export function showInSync(plan: DeployPlan): void { + console.log( + `${green("In sync")}: '${plan.diamondName}' on ${plan.chain.chainKey} (instance '${plan.instance}') matches compose.json.`, + ); + if (plan.existing) { + console.log(dim(` Diamond: ${plan.existing.diamond} (${Object.keys(plan.existing.facets).length} facets)`)); + } + console.log(dim("Nothing to do. Use --redeploy to plan a fresh deployment.")); +} + +/** + * Prints the composition diff and stops. + * + * Applying upgrades is a separate milestone; until then `compose deploy` + * reports drift and exits non-zero so CI catches it. + * + * @param plan - The resolved deployment plan with mode `diff`. + */ +export function showDiffStopped(plan: DeployPlan): void { + console.log(); + console.log( + `The deployment of '${plan.diamondName}' on ${plan.chain.chainKey} (instance '${plan.instance}') differs from compose.json:`, + ); + if (plan.existing) { + console.log(dim(` On-chain diamond: ${plan.existing.diamond}`)); + } + if (plan.diff?.added.length) { + console.log(` Facets to add: ${plan.diff.added.join(", ")}`); + } + if (plan.diff?.removed.length) { + console.log(` Facets to remove: ${plan.diff.removed.join(", ")}`); + } + console.log(); + console.log("Nothing was changed. Use --redeploy to plan a fresh deployment,"); + console.log("or restore compose.json to match the recorded deployment."); + console.log(); +} diff --git a/cli/src/modules/deployPlan/types.ts b/cli/src/modules/deployPlan/types.ts new file mode 100644 index 00000000..4344ef0d --- /dev/null +++ b/cli/src/modules/deployPlan/types.ts @@ -0,0 +1,60 @@ +import type { Hex } from "viem"; +import type { ResolvedChainConfig } from "../../utils/chainConfig"; +import type { DiamondDeployment } from "../lockFile/types"; +import type { DeploymentAccount } from "../accounts/types"; + +/** How `compose deploy` treats the current deployment record, if any. */ +export type DeployMode = + /** No deployment record exists for the target; deploy fresh. */ + | "fresh" + /** A record exists and its facet set matches compose.json. */ + | "in-sync" + /** A record exists but its facet set differs from compose.json. */ + | "diff" + /** A record exists and `--redeploy` replaces it with a fresh deploy. */ + | "redeploy"; + +/** One facet in the desired composition, in compose.json registration order. */ +export type PlannedFacet = { + /** compose.json facet key. */ + name: string; + /** Solidity contract to deploy for this facet. */ + contractName: string; + /** Absolute path of the resolved facet source file, used for compilation and validation. */ + sourcePath: string; + /** Stable import path usable from the managed deploy script; part of the plan identity. */ + importSpec: string; +}; + +/** The resolved deployment plan for one diamond on one chain instance. */ +export type DeployPlan = { + mode: DeployMode; + framework: "foundry" | "hardhat"; + projectRoot: string; + composeJsonPath: string; + diamondName: string; + diamond: { + contractName: string; + sourcePath: string; + importSpec: string; + }; + instance: string; + chain: ResolvedChainConfig; + /** Whether `chain.rpcUrl` came from the command-line override. */ + rpcUrlOverridden: boolean; + /** Selected non-secret signer profile, or null for the framework default. */ + account: DeploymentAccount | null; + /** Desired composition in compose.json registration order. */ + facets: PlannedFacet[]; + /** The existing lock record for the target; null for a fresh deployment. */ + existing: DiamondDeployment | null; + /** Composition drift against the existing record; set when mode is "diff". */ + diff: { added: string[]; removed: string[] } | null; + /** True when the desired composition registers DiamondUpgradeFacet. */ + upgradeable: boolean; + /** + * keccak256 over the checkout- and signer-independent target/composition + * identity, used to bind generated scripts. + */ + planHash: Hex; +}; diff --git a/cli/src/modules/deployScript/model.ts b/cli/src/modules/deployScript/model.ts new file mode 100644 index 00000000..ceea4ac0 --- /dev/null +++ b/cli/src/modules/deployScript/model.ts @@ -0,0 +1,128 @@ +import { createHash } from "node:crypto"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import { toCamelCase } from "../../utils/strings"; +import type { DeployPlan } from "../deployPlan/types"; +import type { ManagedScriptModel, ScriptFacetEntry } from "./types"; + +export const HARDHAT_IGNITION_MODULE_ID = "ComposeDeploy"; + +/** + * Names the generated artifacts declare themselves, plus JavaScript and + * Solidity keywords. A facet contract named `M` or `Static` must not shadow + * the Ignition module parameter or produce an invalid identifier. + */ +const RESERVED_VARIABLE_NAMES = new Set([ + "composeSigner", + "diamond", + "facets", + "m", + "abstract", "address", "after", "alias", "anonymous", "apply", "arguments", "as", + "assembly", "auto", "await", "bool", "break", "byte", "bytes", "calldata", "case", + "catch", "class", "constant", "constructor", "const", "continue", "contract", "copyof", + "debugger", "default", "define", "delete", "do", "else", "emit", "enum", "error", + "eval", "event", "export", "extends", "external", "fallback", "false", "final", + "finally", "fixed", "for", "function", "if", "immutable", "implements", "import", "in", + "indexed", "inline", "instanceof", "int", "interface", "internal", "is", "let", + "library", "macro", "mapping", "match", "memory", "modifier", "mutable", "new", "null", + "of", "override", "package", "partial", "payable", "pragma", "private", "promise", + "protected", "public", "pure", "receive", "reference", "relocatable", "return", + "returns", "revert", "sealed", "sizeof", "static", "storage", "string", "struct", + "super", "supports", "switch", "this", "throw", "transient", "true", "try", "type", + "typedef", "typeof", "ufixed", "uint", "unchecked", "using", "var", "view", "virtual", + "void", "while", "with", "yield", +]); + +/** Elementary type names such as `uint256` and `bytes32` are not valid variables. */ +const RESERVED_TYPE_NAME = /^(?:u?int\d*|bytes\d*|u?fixed(?:x\d+)?\d*)$/; + +function isReservedVariableName(name: string): boolean { + return RESERVED_VARIABLE_NAMES.has(name) || RESERVED_TYPE_NAME.test(name); +} + +/** Ignition Future IDs use a predictable identifier independent of local variable naming. */ +function toIgnitionFacetId(name: string): string { + const slug = name.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 32) || "Facet"; + const digest = createHash("sha256").update(name).digest("hex").slice(0, 12); + return `Facet_${slug}_${digest}`; +} + +/** Assigns a unique camelCase variable name to every facet entry. */ +function assignVariableNames(facets: DeployPlan["facets"]): ScriptFacetEntry[] { + const used = new Set(); + return facets.map((facet, index) => { + const rawBase = toCamelCase(facet.contractName) || `facet${index}`; + const base = isReservedVariableName(rawBase) + ? `facet${rawBase.charAt(0).toUpperCase()}${rawBase.slice(1)}` + : rawBase; + let variableName = base; + let suffix = 2; + while (used.has(variableName)) { + variableName = `${base}${suffix}`; + suffix += 1; + } + used.add(variableName); + return { + name: facet.name, + contractName: facet.contractName, + importSpec: facet.importSpec, + variableName, + futureId: toIgnitionFacetId(facet.name), + }; + }); +} + +/** + * Builds a stable journal ID for a plan, with a distinct ID for each redeploy + * generation and a distinct ID per signer. The plan hash intentionally excludes + * the signer, so the signer digest keeps an incomplete Ignition journal from + * being resumed under a different account. + * + * @param plan - The resolved deployment plan. + * @param signerAddress - The signer resolved for this execution. Pass the + * actual framework default before running so two default signers cannot share + * a journal. When omitted, the selected Compose account is used. + */ +export function getIgnitionDeploymentId(plan: DeployPlan, signerAddress?: string | null): string { + const slug = (value: string): string => + value.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 22) || "default"; + const identity = [plan.diamondName, plan.chain.chainKey, plan.instance].map(slug).join("-"); + const planSuffix = plan.planHash.slice(2, 18); + const signer = signerAddress ?? plan.account?.address ?? "framework-default"; + const signerSuffix = createHash("sha256") + .update(signer.toLowerCase()) + .digest("hex") + .slice(0, 12); + const redeploySuffix = plan.mode === "redeploy" && plan.existing + ? `-from-${plan.existing.txHash.slice(2, 14).toLowerCase()}` + : ""; + return `compose-${identity}-${planSuffix}-${signerSuffix}${redeploySuffix}`; +} + +/** + * Builds the managed script model for a plan. + * + * @param plan - The resolved deployment plan. + * @param adapter - The framework adapter resolving script locations. + * @returns The model consumed by the script renderers. + */ +export async function buildScriptModel( + plan: DeployPlan, + adapter: IFrameworkAdapter, +): Promise { + return { + planHash: plan.planHash, + framework: plan.framework, + toolbox: await adapter.getDeployToolbox(plan.projectRoot), + outputPath: adapter.getManagedDeployScriptPath(plan.projectRoot), + runnerPath: adapter.getManagedDeployRunnerPath(plan.projectRoot), + ignitionDeploymentId: plan.framework === "hardhat" ? getIgnitionDeploymentId(plan) : null, + resultPath: adapter.getManagedDeployResultPath(plan.projectRoot), + projectRoot: plan.projectRoot, + diamond: { contractName: plan.diamond.contractName, importSpec: plan.diamond.importSpec }, + facets: assignVariableNames(plan.facets), + chainKey: plan.chain.chainKey, + chainId: plan.chain.chainId, + instance: plan.instance, + account: plan.account, + }; +} diff --git a/cli/src/modules/deployScript/module.ts b/cli/src/modules/deployScript/module.ts new file mode 100644 index 00000000..747ed599 --- /dev/null +++ b/cli/src/modules/deployScript/module.ts @@ -0,0 +1,112 @@ +import fs from "node:fs/promises"; +import type { Hex } from "viem"; +import type { ComposeContext, ModuleState } from "../../context/types"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import type { IHashingAdapter } from "../../adapters/IHashingAdapter/interface"; +import { atomicWriteFile } from "../../utils/files"; +import { ensureComposeRuntimeDir } from "../../utils/composeRuntime"; +import type { DeployPlan } from "../deployPlan/types"; +import { buildScriptModel } from "./model"; +import { + renderFoundryDeployScript, + renderHardhatIgnitionModule, + renderHardhatIgnitionRunner, +} from "./renderers"; +import type { ManagedScriptModel } from "./types"; + +/** + * Deploy script module. + * + * Builds, renders, and writes the CLI-managed framework script for a plan. + * Script freshness is determined by hashing the complete rendered source and + * the complete source on disk; the plan-hash header remains plan metadata. + */ +export const DeployScriptModule = { + /** + * Builds the managed script model for the current plan. + * + * Stores the model and target path in `ctx.state.deployScript`. + * + * @param ctx - The compose context with `state.deployPlan` populated. + * @param adapter - The framework adapter resolving script locations. + * @returns The context with `state.deployScript` populated. + * @throws {Error} If the deploy plan is missing. + */ + async buildModel(ctx: ComposeContext, adapter: IFrameworkAdapter): Promise { + const planState = ctx.state.deployPlan as ModuleState | undefined; + if (!planState?.success || !planState.result) { + throw new Error("Cannot generate the deploy script: the deploy plan is missing."); + } + + const model = await buildScriptModel(planState.result, adapter); + ctx.state.deployScript = { + success: true, + result: { path: model.outputPath, model }, + error: null, + }; + return ctx; + }, + + /** + * Renders the managed script source for a model. + * + * @param model - The managed script model. + * @returns The complete script source. + */ + async render(model: ManagedScriptModel): Promise { + return model.framework === "foundry" + ? renderFoundryDeployScript(model) + : renderHardhatIgnitionModule(model); + }, + + /** Renders the transient Hardhat runtime without changing the reviewable module. */ + async renderRunner(model: ManagedScriptModel): Promise { + if (model.framework !== "hardhat") { + throw new Error("Only Hardhat deployments use a transient deploy runner."); + } + return renderHardhatIgnitionRunner(model); + }, + + /** + * Renders and atomically writes the managed script to its target path. + * + * @param model - The managed script model. + */ + async write(model: ManagedScriptModel): Promise { + const source = await DeployScriptModule.render(model); + await DeployScriptModule.writeSource(model.outputPath, source); + }, + + /** Atomically writes the transient Hardhat runner into the ignored runtime directory. */ + async writeRunner(model: ManagedScriptModel): Promise { + if (!model.runnerPath) throw new Error("The Hardhat deployment runner path is missing."); + await ensureComposeRuntimeDir(model.projectRoot, "hardhat"); + await DeployScriptModule.writeSource(model.runnerPath, await DeployScriptModule.renderRunner(model)); + }, + + /** + * Atomically writes already-rendered script source. + * + * @param scriptPath - Absolute path of the managed script. + * @param source - Complete rendered script source. + */ + async writeSource(scriptPath: string, source: string): Promise { + await atomicWriteFile(scriptPath, source); + }, + + /** + * Hashes the complete UTF-8 contents of the managed script on disk. + * + * @param scriptPath - Absolute path of the managed script. + * @param hashing - Hashing adapter used for the expected script source. + * @returns The script's content hash, or null when missing or unreadable. + */ + async readScriptHash(scriptPath: string, hashing: IHashingAdapter): Promise { + try { + const source = await fs.readFile(scriptPath, "utf8"); + return hashing.keccak256(source); + } catch { + return null; + } + }, +}; diff --git a/cli/src/modules/deployScript/output.ts b/cli/src/modules/deployScript/output.ts new file mode 100644 index 00000000..eee7df63 --- /dev/null +++ b/cli/src/modules/deployScript/output.ts @@ -0,0 +1,17 @@ +import { toProjectRelativePath } from "../../utils/files"; +import { dim, green } from "../../utils/terminal"; + +/** + * Prints the managed deployment artifact location and review instructions. + * + * @param projectRoot - Absolute project root, used to shorten the displayed path. + * @param scriptPath - Absolute path of the managed script. + */ +export function showScriptReady(projectRoot: string, scriptPath: string): void { + console.log(`${green("Deployment artifact ready")}: ${toProjectRelativePath(projectRoot, scriptPath)}`); + console.log(dim("Review this artifact before deploying.")); + console.log(dim( + "When ready, run 'compose deploy --dry-run' to simulate on a fork " + + "or 'compose deploy --broadcast' to send transactions.", + )); +} diff --git a/cli/src/modules/deployScript/renderers.ts b/cli/src/modules/deployScript/renderers.ts new file mode 100644 index 00000000..47d845e6 --- /dev/null +++ b/cli/src/modules/deployScript/renderers.ts @@ -0,0 +1,183 @@ +import { loadTemplate } from "../../utils/codegen"; +import { toPosixPath, toProjectRelativePath } from "../../utils/files"; +import { + assertSafeSolidityImportSpec, + assertSolidityContractName, +} from "../../utils/solidityIdentifiers"; +import path from "node:path"; +import { HARDHAT_IGNITION_MODULE_ID } from "./model"; +import type { ManagedScriptModel, ScriptFacetEntry } from "./types"; + +/** Escapes a string for embedding inside a JSON string literal. */ +function jsonEscape(value: string): string { + return JSON.stringify(value).slice(1, -1); +} + +/** Escapes text for a Solidity block comment without allowing the terminator. */ +function commentEscape(value: string): string { + return jsonEscape(value).replace(/\*\//g, "*\\/"); +} + +/** Rejects values that cannot be safely embedded in a managed artifact. */ +function assertSafeScriptModel(model: ManagedScriptModel): void { + assertSolidityContractName(model.diamond.contractName, "diamond contract"); + assertSafeSolidityImportSpec(model.diamond.importSpec, "diamond import"); + + for (const facet of model.facets) { + const context = `facet ${JSON.stringify(facet.name)}`; + assertSolidityContractName(facet.contractName, `${context} contract`); + assertSafeSolidityImportSpec(facet.importSpec, `${context} import`); + } +} + +/** Unique import lines: the diamond contract first, then every facet source. */ +function importLines(model: ManagedScriptModel): string[] { + const lines = [ + `import {${model.diamond.contractName}} from ${JSON.stringify(model.diamond.importSpec)};`, + ...model.facets.map( + (facet) => `import {${facet.contractName}} from ${JSON.stringify(facet.importSpec)};`, + ), + ]; + return [...new Set(lines)]; +} + +/** + * Renders the Foundry managed deploy script for a plan. + * + * The script only deploys facets and the diamond; `compose deploy` derives + * the resulting addresses from the run broadcast, because Foundry restricts + * cheatcode file writes to explicitly permitted paths. + * + * @param model - The managed script model. + * @returns The complete Solidity script source. + */ +export async function renderFoundryDeployScript(model: ManagedScriptModel): Promise { + assertSafeScriptModel(model); + const template = await loadTemplate("deploy", "compose-foundry.s.sol"); + + const deployLines = model.facets + .map((facet, index) => + [ + ` ${facet.contractName} ${facet.variableName} = new ${facet.contractName}();`, + ` facets[${index}] = address(${facet.variableName});`, + ` console.log("${jsonEscape(facet.name)}:", address(${facet.variableName}));`, + ].join("\n"), + ) + .join("\n\n"); + const accountGuard = model.account + ? [ + ` (, address composeSigner, ) = vm.readCallers();`, + ` console.log("Deployer:", composeSigner);`, + ` if (composeSigner != ${model.account.address}) revert("Compose: selected signer does not match account '${jsonEscape(model.account.alias)}'");`, + ].join("\n") + : ` (, address composeSigner, ) = vm.readCallers();\n console.log("Deployer:", composeSigner);`; + + return template + .split("{{PLAN_HASH}}").join(model.planHash) + .split("{{IMPORTS}}").join(importLines(model).join("\n")) + .split("{{DIAMOND_CONTRACT}}").join(model.diamond.contractName) + .split("{{FACET_COUNT}}").join(String(model.facets.length)) + .split("{{ACCOUNT_GUARD}}").join(accountGuard) + .split("{{DEPLOY_LINES}}").join(deployLines) + .split("{{CHAIN_KEY}}").join(commentEscape(model.chainKey)) + .split("{{CHAIN_ID}}").join(String(model.chainId)); +} + +function renderIgnitionFacetFutures(facets: ScriptFacetEntry[]): string { + return facets.map((facet) => + ` const ${facet.variableName} = m.contract(${JSON.stringify(facet.contractName)}, [], {\n` + + ` id: ${JSON.stringify(facet.futureId)},\n` + + " });", + ).join("\n\n"); +} + +function renderIgnitionResultEntries(facets: ScriptFacetEntry[]): string { + return facets.map((facet) => ` ${facet.variableName},`).join("\n"); +} + +/** Renders the reviewable Hardhat Ignition module. */ +export async function renderHardhatIgnitionModule(model: ManagedScriptModel): Promise { + assertSafeScriptModel(model); + if (!model.ignitionDeploymentId) { + throw new Error("The Hardhat Ignition module requires a deployment ID."); + } + const template = await loadTemplate("deploy", "compose-hardhat-ignition-module.ts"); + return template + .split("{{PLAN_HASH}}").join(model.planHash) + .split("{{IGNITION_DEPLOYMENT_ID}}").join(model.ignitionDeploymentId) + .split("{{IGNITION_MODULE_ID}}").join(HARDHAT_IGNITION_MODULE_ID) + .split("{{FACET_FUTURES}}").join(renderIgnitionFacetFutures(model.facets)) + .split("{{DIAMOND_CONTRACT}}").join(JSON.stringify(model.diamond.contractName)) + .split("{{FACET_VARIABLES}}").join(model.facets.map((facet) => facet.variableName).join(", ")) + .split("{{FACET_RESULTS}}").join(renderIgnitionResultEntries(model.facets)); +} + +function renderSignerResolution(model: ManagedScriptModel): string { + const expected = JSON.stringify(model.account?.address ?? null); + const missingSigner = JSON.stringify(model.account + ? `Hardhat has no configured signer for Compose account '${model.account.alias}' (${model.account.address}).` + : "Hardhat has no configured deployment signer."); + const signerMismatch = JSON.stringify(model.account + ? `Resolved signer does not match Compose account '${model.account.alias}'.` + : "Resolved signer does not match the expected account."); + const prefix = ` const expectedAccountAddress: string | null = ${expected};\n`; + + if (model.toolbox === "viem") { + return prefix + + " const { viem: targetViem } = targetConnection;\n" + + " const configuredWallets = await targetViem.getWalletClients();\n" + + " const targetDeployer = expectedAccountAddress\n" + + " ? configuredWallets.find((wallet) => wallet.account?.address.toLowerCase() === expectedAccountAddress.toLowerCase())\n" + + " : configuredWallets[0];\n" + + " const deployerAddress = targetDeployer?.account?.address;\n" + + ` if (!deployerAddress) throw new Error(${missingSigner});\n` + + " if (expectedAccountAddress && deployerAddress.toLowerCase() !== expectedAccountAddress.toLowerCase()) {\n" + + ` throw new Error(${signerMismatch});\n` + + " }"; + } + + return prefix + + " const { ethers: targetEthers } = targetConnection;\n" + + " const configuredSigners = await targetEthers.getSigners();\n" + + " const targetDeployer = expectedAccountAddress\n" + + " ? await (async () => {\n" + + " for (const signer of configuredSigners) {\n" + + " if ((await signer.getAddress()).toLowerCase() === expectedAccountAddress.toLowerCase()) return signer;\n" + + " }\n" + + " return undefined;\n" + + " })()\n" + + " : configuredSigners[0];\n" + + ` if (!targetDeployer) throw new Error(${missingSigner});\n` + + " const deployerAddress = await targetDeployer.getAddress();\n" + + " if (expectedAccountAddress && deployerAddress.toLowerCase() !== expectedAccountAddress.toLowerCase()) {\n" + + ` throw new Error(${signerMismatch});\n` + + " }"; +} + +function renderFacetAddressEntries(facets: ScriptFacetEntry[]): string { + return facets.map((facet) => + ` ${JSON.stringify(facet.name)}: await addressOf(outputs.${facet.variableName}),`, + ).join("\n"); +} + +/** Renders the ignored, transient runner that executes the reviewed module. */ +export async function renderHardhatIgnitionRunner(model: ManagedScriptModel): Promise { + if (!model.runnerPath || !model.ignitionDeploymentId || !model.resultPath || !model.toolbox) { + throw new Error("The Hardhat Ignition runner is missing required deployment paths or metadata."); + } + const template = await loadTemplate("deploy", "compose-hardhat-ignition-runner.ts"); + const moduleImport = toPosixPath(path.relative(path.dirname(model.runnerPath), model.outputPath)) + .replace(/\.ts$/, ".js"); + const moduleSpecifier = moduleImport.startsWith(".") ? moduleImport : `./${moduleImport}`; + return template + .split("{{MODULE_IMPORT}}").join(moduleSpecifier) + .split("{{CHAIN_ID}}").join(String(model.chainId)) + .split("{{IGNITION_DEPLOYMENT_ID}}").join(JSON.stringify(model.ignitionDeploymentId)) + .split("{{ACCOUNT_ADDRESS}}").join(JSON.stringify(model.account?.address ?? null)) + .split("{{RESULT_PATH}}").join(JSON.stringify(toProjectRelativePath(model.projectRoot, model.resultPath))) + .split("{{CHAIN_KEY}}").join(JSON.stringify(model.chainKey)) + .split("{{RESOLVE_SIGNER}}").join(renderSignerResolution(model)) + .split("{{FACET_ADDRESS_ENTRIES}}").join(renderFacetAddressEntries(model.facets)) + .split("{{PLAN_HASH}}").join(model.planHash) + .split("{{INSTANCE}}").join(JSON.stringify(model.instance)); +} diff --git a/cli/src/modules/deployScript/types.ts b/cli/src/modules/deployScript/types.ts new file mode 100644 index 00000000..10bcdb9f --- /dev/null +++ b/cli/src/modules/deployScript/types.ts @@ -0,0 +1,46 @@ +import type { Hex } from "viem"; +import type { DeployToolbox } from "../../adapters/IFrameworkAdapter/types"; + +/** Hardhat toolbox variants supported by the managed deploy script. */ +export type ScriptToolbox = DeployToolbox; + +/** One facet entry rendered into the managed deploy script. */ +export type ScriptFacetEntry = { + /** compose.json facet key, used in the result file. */ + name: string; + contractName: string; + importSpec: string; + /** Unique camelCase local variable name for the deployed contract. */ + variableName: string; + /** Stable Hardhat Ignition future ID for this facet. */ + futureId: string; +}; + +/** Everything the renderers need to produce a managed deploy script. */ +export type ManagedScriptModel = { + planHash: Hex; + framework: "foundry" | "hardhat"; + toolbox: ScriptToolbox | null; + /** Absolute path where the script is written. */ + outputPath: string; + /** Absolute path of the transient Hardhat Ignition runtime, or null for Foundry. */ + runnerPath: string | null; + /** Stable Ignition journal ID for this Compose deployment attempt, or null for Foundry. */ + ignitionDeploymentId: string | null; + /** Absolute path of the framework's deploy result file, or null when it uses a broadcast. */ + resultPath: string | null; + projectRoot: string; + diamond: { + contractName: string; + importSpec: string; + }; + facets: ScriptFacetEntry[]; + chainKey: string; + chainId: number; + instance: string; + account: { + alias: string; + address: `0x${string}`; + foundryAccount?: string; + } | null; +}; diff --git a/cli/src/modules/deploySimulation/module.ts b/cli/src/modules/deploySimulation/module.ts new file mode 100644 index 00000000..2aaa6272 --- /dev/null +++ b/cli/src/modules/deploySimulation/module.ts @@ -0,0 +1,60 @@ +import fs from "node:fs/promises"; +import type { ComposeContext } from "../../context/types"; +import type { IFrameworkAdapter } from "../../adapters/IFrameworkAdapter/interface"; +import { runCommand } from "../../utils/exec"; +import { toPassthroughArgs } from "../../utils/args"; +import type { DeployPlan } from "../deployPlan/types"; + +/** Runs the managed deployment script on a local fork without broadcasting. */ +export const DeploySimulationModule = { + async simulate( + ctx: ComposeContext, + plan: DeployPlan, + scriptPath: string, + adapter: IFrameworkAdapter, + forkBlockNumber: bigint, + runnerPath: string | null = adapter.getManagedDeployRunnerPath(plan.projectRoot), + ): Promise { + try { + const command = adapter.createDeployCommand({ + chainId: plan.chain.chainId, + chainKey: plan.chain.chainKey, + passthrough: toPassthroughArgs(ctx.param.passthrough), + projectRoot: plan.projectRoot, + rpcUrl: plan.chain.rpcUrl, + account: plan.account, + scriptPath, + runnerPath, + mode: "simulate", + forkBlockNumber, + }); + await runCommand(command.command, command.args, { + cwd: plan.projectRoot, + ...(command.env ? { env: command.env } : {}), + }); + + ctx.state.deploySimulation = { + success: true, + result: { forkBlockNumber }, + error: null, + }; + return ctx; + } catch (error) { + const message = error instanceof Error ? error.message : "Deployment simulation failed."; + ctx.state.deploySimulation = { + success: false, + result: null, + error: { code: "DEPLOY_SIMULATION_FAILED", message, nativeError: error }, + }; + throw error; + } finally { + if (plan.framework === "hardhat" && runnerPath) { + try { + await fs.rm(runnerPath, { force: true }); + } catch { + // The runner is ignored runtime glue; cleanup must not mask the simulation result. + } + } + } + }, +}; diff --git a/cli/src/modules/deploySimulation/output.ts b/cli/src/modules/deploySimulation/output.ts new file mode 100644 index 00000000..847a31b0 --- /dev/null +++ b/cli/src/modules/deploySimulation/output.ts @@ -0,0 +1,18 @@ +import type { DeployPlan } from "../deployPlan/types"; +import { toProjectRelativePath } from "../../utils/files"; +import { dim, green } from "../../utils/terminal"; + +/** Prints the result of a successful fork simulation. */ +export function showDeploySimulationSuccess( + plan: DeployPlan, + scriptPath: string, + forkBlockNumber: bigint, +): void { + console.log(); + console.log(`${green("Simulation succeeded")} for '${plan.diamondName}' on ${plan.chain.chainKey}.`); + console.log(` Fork block: ${forkBlockNumber}`); + console.log(` Script: ${toProjectRelativePath(plan.projectRoot, scriptPath)}`); + console.log(dim("No transactions were broadcast. compose.lock was not changed.")); + console.log(dim("Review the script, then run 'compose deploy --broadcast' to deploy.")); + console.log(); +} diff --git a/cli/src/modules/deployVerification/module.ts b/cli/src/modules/deployVerification/module.ts new file mode 100644 index 00000000..25a11cff --- /dev/null +++ b/cli/src/modules/deployVerification/module.ts @@ -0,0 +1,194 @@ +import type { Hex } from "viem"; +import type { ComposeContext } from "../../context/types"; +import type { IRPCAdapter } from "../../adapters/IRPCAdapter/interface"; +import type { IDiamondAdapter } from "../../adapters/IDiamondAdapter/interface"; +import type { IHashingAdapter } from "../../adapters/IHashingAdapter/interface"; +import { LockFileModule } from "../lockFile/module"; +import type { DiamondDeployment } from "../lockFile/types"; +import type { DeployPlan } from "../deployPlan/types"; +import type { DeployExecutionResult } from "../deployExecution/types"; +import { showVerificationFailure } from "./output"; + +const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"; + +/** + * Rejects duplicate facet addresses and a facet that reuses the diamond address. + * + * @param facets - The reported facet names and addresses. + * @param diamond - The deployed diamond address. + */ +function assertUniqueFacetAddresses(facets: Record, diamond: Hex): void { + const diamondAddress = diamond.toLowerCase(); + const namesByAddress = new Map(); + + for (const [name, address] of Object.entries(facets)) { + const normalized = address.toLowerCase(); + if (normalized === diamondAddress) { + throw new Error( + `Facet '${name}' uses the diamond address ${address}; facets must be separate contracts.`, + ); + } + + const existingName = namesByAddress.get(normalized); + if (existingName) { + throw new Error( + `Facets '${existingName}' and '${name}' report the same address ${address}; facet addresses must be unique.`, + ); + } + namesByAddress.set(normalized, name); + } +} + +/** + * Rejects duplicate or diamond-owned entries in the on-chain facet list. + * + * @param addresses - The facet addresses reported by the diamond. + * @param diamond - The deployed diamond address. + */ +function assertValidOnChainFacetList(addresses: readonly Hex[], diamond: Hex): void { + const diamondAddress = diamond.toLowerCase(); + const seen = new Set(); + + for (const address of addresses) { + const normalized = address.toLowerCase(); + if (normalized === diamondAddress) { + throw new Error(`The on-chain facet list contains the diamond address ${address}.`); + } + if (seen.has(normalized)) { + throw new Error(`The on-chain facet list contains duplicate address ${address}.`); + } + seen.add(normalized); + } +} + +/** + * Verifies that every selector exported by each facet routes back to that facet. + * + * `facetFunctionSelectors` derives its result from the facet's + * `exportSelectors()`, so each selector must be checked with `facetAddress`; + * this catches selectors that the facet exposes but the diamond does not route. + * + * @param diamond - The diamond introspection adapter. + * @param diamondAddress - The deployed diamond address. + * @param facets - The reported facet names and addresses. + */ +async function verifySelectorRouting( + diamond: IDiamondAdapter, + diamondAddress: Hex, + facets: Record, +): Promise { + for (const [name, address] of Object.entries(facets)) { + const selectors = await diamond.facetFunctionSelectors(diamondAddress, address); + if (selectors.length === 0) { + throw new Error( + `Facet '${name}' (${address}) exposes no selectors on the diamond; its first selector is not routed.`, + ); + } + + for (const selector of selectors) { + const routedTo = await diamond.facetAddress(diamondAddress, selector); + const normalized = routedTo.toLowerCase(); + if (normalized === address.toLowerCase()) { + continue; + } + if (normalized === ZERO_ADDRESS) { + throw new Error( + `Selector ${selector} from facet '${name}' (${address}) is not routed by the diamond.`, + ); + } + throw new Error( + `Selector ${selector} from facet '${name}' (${address}) is routed to ${routedTo} instead.`, + ); + } + } +} + +/** + * Deploy verification module. + * + * Checks the deployed diamond against the chain before anything is + * recorded in compose.lock: the diamond and every facet must have code, + * facet addresses must be unique and distinct from the diamond, the diamond + * registry must expose exactly the reported facet addresses, and every + * selector exported by a facet must route back to that facet. + */ +export const DeployVerificationModule = { + /** + * Verifies a deployment result against chain state and builds the lock record. + * + * Stores the record in `ctx.state.deployVerification` on success; records a + * failure state and prints a report on failure. Failure leaves compose.lock + * untouched. + * + * @param ctx - The compose context. + * @param plan - The resolved deployment plan. + * @param execution - The normalized execution result. + * @param dependencies - RPC, diamond, and hashing adapters. + * @returns The context with `state.deployVerification` populated. + */ + async verify( + ctx: ComposeContext, + plan: DeployPlan, + execution: DeployExecutionResult, + dependencies: { rpc: IRPCAdapter; diamond: IDiamondAdapter; hashing: IHashingAdapter }, + ): Promise { + try { + const diamondCode = await dependencies.rpc.getCode(execution.diamond); + if (!diamondCode || diamondCode === "0x") { + throw new Error(`No contract code found at the diamond address ${execution.diamond}.`); + } + + assertUniqueFacetAddresses(execution.facets, execution.diamond); + + for (const [name, address] of Object.entries(execution.facets)) { + const code = await dependencies.rpc.getCode(address); + if (!code || code === "0x") { + throw new Error(`No contract code found at facet '${name}' (${address}).`); + } + } + + const onChainAddresses = await dependencies.diamond.facetAddresses(execution.diamond); + assertValidOnChainFacetList(onChainAddresses, execution.diamond); + + const reported = new Set(Object.values(execution.facets).map((address) => address.toLowerCase())); + const observed = new Set(onChainAddresses.map((address) => address.toLowerCase())); + const missing = [...reported].filter((address) => !observed.has(address)); + const unexpected = [...observed].filter((address) => !reported.has(address)); + if (missing.length > 0 || unexpected.length > 0) { + throw new Error( + `The on-chain facets do not match the deployment result (missing: ${missing.join(", ") || "none"}; unexpected: ${unexpected.join(", ") || "none"}).`, + ); + } + + await verifySelectorRouting(dependencies.diamond, execution.diamond, execution.facets); + + const record: DiamondDeployment = { + diamond: execution.diamond, + facets: execution.facets, + facetHash: LockFileModule.computeFacetHash( + Object.values(execution.facets) as Hex[], + dependencies.hashing, + ), + lastSync: new Date().toISOString(), + txHash: execution.transactions.diamond, + ...(execution.deployer ? { deployer: execution.deployer } : {}), + ...(execution.ignitionDeploymentId ? { ignitionDeploymentId: execution.ignitionDeploymentId } : {}), + }; + + ctx.state.deployVerification = { success: true, result: record, error: null }; + } catch (error) { + ctx.state.deployVerification = { + success: false, + result: null, + error: { + code: "DEPLOY_VERIFICATION_FAILED", + message: error instanceof Error ? error.message : "Verification failed.", + nativeError: error, + }, + }; + showVerificationFailure(plan, execution, error); + } + + return ctx; + }, +}; diff --git a/cli/src/modules/deployVerification/output.ts b/cli/src/modules/deployVerification/output.ts new file mode 100644 index 00000000..279a95ba --- /dev/null +++ b/cli/src/modules/deployVerification/output.ts @@ -0,0 +1,54 @@ +import { toProjectRelativePath } from "../../utils/files"; +import { dim, green, red } from "../../utils/terminal"; +import type { DeployPlan } from "../deployPlan/types"; +import type { DeployExecutionResult } from "../deployExecution/types"; +import type { DiamondDeployment } from "../lockFile/types"; + +/** + * Prints a verification failure report with the captured addresses. + * + * @param plan - The resolved deployment plan. + * @param execution - The normalized execution result. + * @param error - The underlying verification error. + */ +export function showVerificationFailure( + plan: DeployPlan, + execution: DeployExecutionResult, + error: unknown, +): void { + console.error(); + console.error(red("On-chain verification failed; compose.lock was not changed.")); + console.error(` Diamond: ${execution.diamond}`); + console.error(" Result facets:"); + for (const [name, address] of Object.entries(execution.facets)) { + console.error(` - ${name}: ${address}`); + } + console.error(` ${error instanceof Error ? error.message : String(error)}`); + console.error(dim("Inspect the addresses above on the chain, then retry or use --redeploy.")); + console.error(); +} + +/** + * Prints the successful deployment summary and the lock record location + * (relative to the project root). + * + * @param plan - The resolved deployment plan. + * @param record - The verified lock record. + * @param lockPath - Absolute path of the written compose.lock. + */ +export function showDeploySuccess( + plan: DeployPlan, + record: DiamondDeployment, + lockPath: string, +): void { + console.log(); + console.log( + `${green("Deployed")} '${plan.diamondName}' on ${plan.chain.chainKey} (instance '${plan.instance}').`, + ); + console.log(` Diamond: ${record.diamond}`); + if (record.deployer) console.log(` Deployer: ${record.deployer}`); + console.log(` Facets: ${Object.keys(record.facets).length}`); + console.log(` Tx: ${record.txHash}`); + console.log(` Lock: ${toProjectRelativePath(plan.projectRoot, lockPath)}`); + console.log(); +} diff --git a/cli/src/modules/facetConfig/batchMutation.ts b/cli/src/modules/facetConfig/batchMutation.ts index 7647120f..ed70ca0e 100644 --- a/cli/src/modules/facetConfig/batchMutation.ts +++ b/cli/src/modules/facetConfig/batchMutation.ts @@ -83,6 +83,8 @@ type FacetBatchMutation = { entries: unknown; stagedFiles: string[]; }): Promise<{ facets: string[]; changed: boolean }>; + /** Runs after edits, before the validating compile; may change project config. */ + beforeValidate?(): Promise; revert?(options: { stagedFiles: string[] }): Promise; }; @@ -117,6 +119,7 @@ async function applyBatch( // Staged sources are as unverified as a registration change, and only install stages. if (changed || stagedFiles.length > 0) { + await mutation.beforeValidate?.(); ctx = await validateCandidateConfig(ctx, projectConfig); } if (changed) { @@ -156,6 +159,8 @@ export async function applyInstallBatch( const contractSourceRoot = adapter.getContractSourceRoot(project.root); const catalog = ctx.config.bases as BasesCatalog; const resolution = facetReferenceOptions(); + const packageSpecifiers = new Set(); + let restoreConfig: (() => Promise) | null = null; return applyBatch(ctx, project, batch, { operation: "install", @@ -164,6 +169,11 @@ export async function applyInstallBatch( for (const reference of entries as FacetInstallReference[]) { resolved.push(await resolveFacetInstallReference(reference, catalog, project.root, resolution)); } + for (const facet of resolved) { + if (facet.registration.source === "package" && facet.packageSpecifier) { + packageSpecifiers.add(facet.packageSpecifier); + } + } const copied = await copyCatalogFacetSources(resolved, project.root, contractSourceRoot); stagedFiles.push(...copied.createdFiles); @@ -172,7 +182,12 @@ export async function applyInstallBatch( for (const facet of copied.facets) { if (Object.hasOwn(diamond.facets, facet.name)) { if (!sameRegistration(diamond.facets[facet.name], facet.registration)) { - throw new Error(`Facet '${facet.name}' is already registered to a different source in '${diamondName}'.`); + const existing = diamond.facets[facet.name]; + const current = typeof existing.contract === "string" ? existing.contract : JSON.stringify(existing); + throw new Error( + `Facet '${facet.name}' already points to ${current} on '${diamondName}'. ` + + `Remove it first with 'compose remove ${facet.name}', or register the new source under another facet name.`, + ); } continue; } @@ -181,8 +196,15 @@ export async function applyInstallBatch( } return { facets: installedNames, changed: installedNames.length > 0 }; }, + // Package facets must join the Hardhat build before the validating compile + // can see them; foundry compiles the explicit paths already. + beforeValidate: async () => { + if (packageSpecifiers.size === 0 || !adapter.ensurePackageFacetsCompilable) return; + restoreConfig = await adapter.ensurePackageFacetsCompilable(project.root, [...packageSpecifiers]); + }, revert: async ({ stagedFiles }) => { await Promise.all(stagedFiles.map((filePath) => fs.rm(filePath, { force: true }))); + await restoreConfig?.(); }, }); } @@ -206,7 +228,10 @@ export async function applyRemoveBatch( removed.push(facetName); } if (Object.keys(diamond.facets).length === 0) { - throw new Error(`Cannot remove every registered facet from '${diamondName}'.`); + throw new Error( + `Cannot remove every registered facet from '${diamondName}'; a diamond needs at least one facet. ` + + "Leave one facet registered, or remove the diamond entry from compose.json.", + ); } return { facets: removed, changed: removed.length > 0 }; }, diff --git a/cli/src/modules/facetConfig/facetResolver.ts b/cli/src/modules/facetConfig/facetResolver.ts index e7ee6aee..cecb880d 100644 --- a/cli/src/modules/facetConfig/facetResolver.ts +++ b/cli/src/modules/facetConfig/facetResolver.ts @@ -134,6 +134,7 @@ function registrationFromCatalog(candidate: CatalogCandidate): ResolvedFacetInst name, contractName, targetGroup: group, + packageSpecifier: entry.path, registration: { source: "package", contract: contractName, @@ -183,7 +184,8 @@ export async function resolveFacetInstallReference( const matched = await resolveFuzzyLocalReference(reference, projectRoot, options); if (matched) return matched; throw new Error( - `Unknown catalog facet '${reference}'. Use a catalog name, path.sol:ContractName, or the name of a contract in this project.`, + `Unknown catalog facet '${reference}'. ` + + "Use a 'compose catalog' name, path.sol:ContractName, or a project contract name.", ); } @@ -195,13 +197,17 @@ export async function resolveFacetInstallReference( } const matched = await resolveFuzzyLocalReference(reference.name, projectRoot, options); if (matched) return matched; - throw new Error(`Unknown catalog facet '${reference.name}'. Add a local or package source to the manifest.`); + throw new Error( + `Unknown catalog facet '${reference.name}'. ` + + "Use a 'compose catalog' name, path.sol:ContractName, or a project contract name. " + + "In a manifest, give the entry a local or package source.", + ); } if (reference.source === "local") { const contractName = contractReferenceName(reference.contract); if (!contractName) { - throw new Error(`Local facet '${reference.name}' must use path.sol:ContractName.`); + throw new Error(`Local facet '${reference.name}' must use path.sol:ContractName, e.g. "./src/facets/${reference.name}.sol:${reference.name}".`); } if (contractName !== reference.name) { throw new Error(`Local facet key '${reference.name}' must match contract '${contractName}'.`); @@ -241,7 +247,7 @@ async function resolveLocalReference( const source = reference.slice(0, separator); const absolutePath = path.resolve(projectRoot, source); await fs.access(absolutePath).catch(() => { - throw new Error(`Facet source not found: ${source}`); + throw new Error(`Facet source not found: ${source}. Install paths are relative to the Compose project root.`); }); const registration: FacetRegistration = { source: "local", @@ -453,7 +459,13 @@ export async function copyCatalogFacetSources( const existingContent = await fs.readFile(target); const sourceContent = await fs.readFile(source); if (!existingContent.equals(sourceContent)) { - throw new Error(`Facet source destination already exists with different contents: ${target}`); + const relativeTarget = projectRelativePath(projectRoot, target); + const contractName = path.basename(target, ".sol"); + throw new Error( + `Facet source destination already exists with different contents: ${relativeTarget}. ` + + `Keep it: compose install "${relativeTarget}:${contractName}". ` + + "Replace it: move the file, then install again.", + ); } } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; diff --git a/cli/src/modules/facetConfig/manifest.ts b/cli/src/modules/facetConfig/manifest.ts index baa55d12..92b13e46 100644 --- a/cli/src/modules/facetConfig/manifest.ts +++ b/cli/src/modules/facetConfig/manifest.ts @@ -119,7 +119,7 @@ function validateInstallReference(value: unknown, diamondName: string): FacetIns if (value.source === undefined) return { name }; if (value.source === "local") { if (typeof value.contract !== "string" || !/^.+:([A-Za-z_$][A-Za-z0-9_$]*)$/.test(value.contract.trim())) { - throw new Error(`Local facet '${name}' must use path.sol:ContractName.`); + throw new Error(`Local facet '${name}' must use path.sol:ContractName, e.g. "src/facets/${name}.sol:${name}".`); } return { name, source: "local", contract: value.contract.trim() }; } diff --git a/cli/src/modules/facetConfig/projectConfig.ts b/cli/src/modules/facetConfig/projectConfig.ts index aa455fa7..5f60c91f 100644 --- a/cli/src/modules/facetConfig/projectConfig.ts +++ b/cli/src/modules/facetConfig/projectConfig.ts @@ -19,7 +19,8 @@ export function getDiamondOrThrow( diamondName: string, ): ComposeDiamondConfig { if (!Object.hasOwn(diamonds, diamondName)) { - throw new Error(`Diamond '${diamondName}' is not defined in compose.json.`); + const available = Object.keys(diamonds).join(", ") || "none defined"; + throw new Error(`Diamond '${diamondName}' is not defined in compose.json. Available: ${available}.`); } return diamonds[diamondName]; } diff --git a/cli/src/modules/facetConfig/selection.ts b/cli/src/modules/facetConfig/selection.ts index c10dd764..deeee281 100644 --- a/cli/src/modules/facetConfig/selection.ts +++ b/cli/src/modules/facetConfig/selection.ts @@ -1,6 +1,6 @@ import type { ComposeContext } from "../../context/types"; import type { BasesCatalog } from "../config/types"; -import { loadPrompts, checkboxTheme, selectTheme } from "../../utils/inquirer"; +import { loadPrompts, checkboxTheme, selectTheme, isInteractive } from "../../utils/inquirer"; import { dim } from "../../utils/terminal"; import { contractReferenceName, @@ -9,10 +9,6 @@ import { type FacetReferenceResolutionOptions, } from "./facetResolver"; -function isInteractive(): boolean { - return Boolean(process.stdin.isTTY && process.stdout.isTTY); -} - /** Resolution hooks that let interactive installs pick among fuzzy source matches. */ export function facetReferenceOptions(): FacetReferenceResolutionOptions | undefined { if (!isInteractive()) return undefined; @@ -28,7 +24,22 @@ export function facetReferenceOptions(): FacetReferenceResolutionOptions | undef }; } -export async function selectDiamond(ctx: ComposeContext, names: string[], operation: string): Promise { +/** + * Resolves the diamond named by `--diamond`, or the sole defined diamond. + * + * @param ctx - The compose context with command parameters. + * @param names - Diamond names defined in the project. + * @param operation - Human-readable action used in the prompt. + * @param options - Prompt behavior for ambiguous projects. + * @param options.allowPrompt - Whether an ambiguous project may prompt interactively. + * @returns The selected diamond name. + */ +export async function selectDiamond( + ctx: ComposeContext, + names: string[], + operation: string, + options: { allowPrompt?: boolean } = {}, +): Promise { if (typeof ctx.param.diamond === "string" && ctx.param.diamond.trim()) { if (!names.includes(ctx.param.diamond)) { throw new Error(`Diamond '${ctx.param.diamond}' not found. Available: ${names.join(", ")}`); @@ -36,7 +47,7 @@ export async function selectDiamond(ctx: ComposeContext, names: string[], operat return ctx.param.diamond; } if (names.length === 1) return names[0]; - if (!isInteractive()) { + if (options.allowPrompt === false || !isInteractive()) { throw new Error(`Specify --diamond for this project. Available: ${names.join(", ")}`); } const { select } = await loadPrompts(); @@ -108,7 +119,7 @@ export async function selectRemoveFacetNames( withoutArgumentsMessage: "Provide facet names to remove, or use --manifest.", choices: async () => { const configured = Object.keys(configuredFacets); - if (configured.length === 0) throw new Error(`Diamond '${diamondName}' has no registered facets.`); + if (configured.length === 0) throw new Error(`Diamond '${diamondName}' has no registered facets. Nothing to remove; use 'compose install' first.`); return configured; }, }); diff --git a/cli/src/modules/facetConfig/types.ts b/cli/src/modules/facetConfig/types.ts index 3ee61c73..a1307877 100644 --- a/cli/src/modules/facetConfig/types.ts +++ b/cli/src/modules/facetConfig/types.ts @@ -73,6 +73,8 @@ export type ResolvedFacetInstall = { registration: FacetRegistration; catalogSource?: string; targetGroup?: "diamond" | "libraries" | "facets"; + /** Package-relative source (`@scope/pkg/path.sol`) for package registrations. */ + packageSpecifier?: string; }; export type FacetBatchOperation = "install" | "remove"; diff --git a/cli/src/modules/framework/module.ts b/cli/src/modules/framework/module.ts index 70d5530c..169f90b8 100644 --- a/cli/src/modules/framework/module.ts +++ b/cli/src/modules/framework/module.ts @@ -21,5 +21,5 @@ export const FrameworkModule = { } return null; - } -} + }, +}; diff --git a/cli/src/modules/info/scanner.ts b/cli/src/modules/info/scanner.ts index 97ff6627..2d3dec5a 100644 --- a/cli/src/modules/info/scanner.ts +++ b/cli/src/modules/info/scanner.ts @@ -28,21 +28,24 @@ function resolveLocalFacetPath( /** * Searches for a package facet's .sol file in the installed package directories. - * Checks node_modules and Foundry lib directories. + * Prefers the project framework's package root when both are installed. * * @param facetName - Name of the facet contract file (without extension). * @param packageName - The npm or package name to search within. * @param projectRoot - The project root directory. + * @param framework - Project framework ("foundry" or "hardhat"), when known. * @returns The resolved absolute path, or null if not found. */ async function resolvePackageFacetPath( facetName: string, packageName: string, projectRoot: string, + framework?: string, ): Promise { const matches = await findPackageFacetSourceMatches(projectRoot, packageName, facetName, { ignoreReadErrors: true, stopAfterFirstMatch: true, + framework, }); return matches[0] ?? null; } @@ -71,7 +74,7 @@ export async function scanFacets(ctx: ComposeContext): Promise { const warnings: string[] = [...projectInfo.warnings]; for (const diamond of projectInfo.diamonds) { - await scanDiamond(diamond, composeJsonDir, warnings); + await scanDiamond(diamond, composeJsonDir, warnings, projectInfo.framework); } projectInfo.warnings = warnings; @@ -91,14 +94,16 @@ export async function scanFacets(ctx: ComposeContext): Promise { * @param diamond - The diamond to scan (mutated in place). * @param composeJsonDir - Directory containing compose.json for path resolution. * @param warnings - Mutable array to append warning messages to. + * @param framework - Project framework used to pick the package source root. */ async function scanDiamond( diamond: DiamondInfo, composeJsonDir: string, warnings: string[], + framework?: string, ): Promise { for (const facet of diamond.facets) { - await scanFacet(facet, composeJsonDir, warnings); + await scanFacet(facet, composeJsonDir, warnings, framework); } } @@ -108,11 +113,13 @@ async function scanDiamond( * @param facet - The facet to scan (mutated in place). * @param composeJsonDir - Directory containing compose.json for path resolution. * @param warnings - Mutable array to append warning messages to. + * @param framework - Project framework used to pick the package source root. */ async function scanFacet( facet: FacetInfo, composeJsonDir: string, warnings: string[], + framework?: string, ): Promise { if (facet.source === "package") { if (!facet.package) { @@ -120,7 +127,12 @@ async function scanFacet( return; } - const resolvedPath = await resolvePackageFacetPath(facet.name, facet.package, composeJsonDir); + const resolvedPath = await resolvePackageFacetPath( + facet.name, + facet.package, + composeJsonDir, + framework, + ); if (!resolvedPath) { warnings.push(`Package facet ${facet.name}: source not found in ${facet.package}`); return; diff --git a/cli/src/modules/init/flags.ts b/cli/src/modules/init/flags.ts index b2a3946c..1c5f7113 100644 --- a/cli/src/modules/init/flags.ts +++ b/cli/src/modules/init/flags.ts @@ -1,5 +1,29 @@ import { uniqueStrings, splitCommaSeparated } from "../../utils/strings"; -import { AccessFlagSelection } from "./types"; +import { AccessFlagSelection, UpgradeabilitySelection } from "./types"; + +/** + * Resolves the upgradeability choice from CLI flags. + * + * Immutable is the default; `--upgradeable` opts in to the upgrade facet and + * the owner coupling derived from it. + * + * @param param - Raw CLI parameter record containing upgradeability flags. + * @returns The resolved upgradeability selection with explicitness tracking. + * @throws {Error} If both `--upgradeable` and `--immutable` are provided. + */ +export function resolveUpgradeability(param: Record): UpgradeabilitySelection { + const upgradeable = param.upgradeable === true; + const immutable = param.immutable === true; + + if (upgradeable && immutable) { + throw new Error("Use either --upgradeable or --immutable, not both."); + } + + return { + upgradeable, + explicit: upgradeable || immutable, + }; +} /** * Resolves grouped access flags from raw CLI parameters into a structured selection. diff --git a/cli/src/modules/init/frameworkDeps.ts b/cli/src/modules/init/frameworkDeps.ts index 51e515f1..06bd87ae 100644 --- a/cli/src/modules/init/frameworkDeps.ts +++ b/cli/src/modules/init/frameworkDeps.ts @@ -1,8 +1,29 @@ +import { CLI_DEV_DEPENDENCY_VERSION, CLI_PACKAGE_NAME } from "../../utils/metadata"; import { FrameworkDependencies } from "./types"; +/** Hardhat release line used by Compose's generated Hardhat 3 projects. */ +export const HARDHAT_VERSION_RANGE = "^3.8.0"; + +/** Exact CLI version used to materialize the official Hardhat starter templates. */ +export const HARDHAT_INIT_VERSION = "3.8.0"; + +/** Official Hardhat 3 project templates matching Compose's toolbox choices. */ +export const HARDHAT_INIT_TEMPLATES = { + ethers: "mocha-ethers", + viem: "node-test-runner-viem", +} as const; + +export function getHardhatInitTemplate(toolbox: string): string { + if (toolbox !== "ethers" && toolbox !== "viem") { + throw new Error(`Unsupported Hardhat toolbox: ${toolbox}. Choose 'ethers' or 'viem'.`); + } + return HARDHAT_INIT_TEMPLATES[toolbox]; +} + /** * Returns the framework-specific dependencies needed for a Compose project. - * Foundry uses git submodules; Hardhat uses npm packages. + * Foundry uses git submodules; Hardhat uses npm packages. Both frameworks get + * the Compose CLI as an npm dev dependency so `npx compose` works locally. * * @param framework - The target framework ("foundry" or "hardhat"). * @param toolbox - The Hardhat toolbox ("ethers" or "viem"). Ignored for Foundry. @@ -17,22 +38,28 @@ export function getFrameworkDependencies( deps: [ { name: "forge-std", version: "(git submodule)" }, { name: "Perfect-Abstractions/Compose", version: "(git submodule)" }, + { + name: CLI_PACKAGE_NAME, + version: `${CLI_DEV_DEPENDENCY_VERSION} (npm dev dependency)`, + }, ], - packageType: "forge packages", + packageType: "packages", }; } const devDeps: Record = toolbox === "viem" - ? { - hardhat: "^3.8.0", - "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", + ? { + hardhat: HARDHAT_VERSION_RANGE, + "@nomicfoundation/hardhat-toolbox-viem": "^5.0.7", } - : { - hardhat: "^3.8.0", - "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0", + : { + hardhat: HARDHAT_VERSION_RANGE, + "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.7", }; + devDeps[CLI_PACKAGE_NAME] = CLI_DEV_DEPENDENCY_VERSION; + return { deps: [ { name: "@perfect-abstractions/compose", version: "latest" }, diff --git a/cli/src/modules/init/module.ts b/cli/src/modules/init/module.ts index 43b1d5fd..d9127c32 100644 --- a/cli/src/modules/init/module.ts +++ b/cli/src/modules/init/module.ts @@ -6,21 +6,23 @@ import { getOwnershipExtensionChoices, getRoleAccessChoices, getRoleAccessExtensionChoices, + getUpgradeabilityChoices, toFacetChoices, } from "./prompts"; import { checkboxTheme, clearStdin , inputTheme, loadPrompts, selectTheme } from "../../utils/inquirer"; import { getFrameworkDependencies } from "./frameworkDeps"; -import { resolveAccessFlags } from "./flags"; -import { splitCommaSeparated } from "../../utils/strings"; +import { resolveAccessFlags, resolveUpgradeability } from "./flags"; +import { splitCommaSeparated, uniqueStrings } from "../../utils/strings"; import { validateProjectName, validateProjectNameWithFolder } from "./projectNameValidation"; import { showComposeHeader, showDependencies, showSuccess } from "./output"; +import { dim, yellow } from "../../utils/terminal"; /** * Handles interactive and non-interactive init input collection. * * Validates user selections against the loaded bases catalog, resolves - * framework, base, library, extension, access, and example choices, and stores - * the assembled configuration on the context. + * framework, base, upgradeability, library, extension, and access choices, and + * stores the assembled configuration on the context. */ export const InitModule = { showComposeHeader, @@ -30,8 +32,10 @@ export const InitModule = { * * Validates the framework (`foundry` or `hardhat`), base key, library * extensions, access layers, and example selections against the catalog. Defaults the - * Hardhat toolbox to `ethers` if not specified. Throws on any invalid - * selection. + * Hardhat toolbox to `ethers` if not specified. Immutable is the default: + * `--upgradeable` adds `DiamondUpgradeFacet` and couples the `owner` base, + * and an explicit `DiamondUpgradeFacet` in `--libraries` opts in for + * compatibility. Throws on any invalid selection. * * @param ctx - The compose context with CLI flags and the loaded bases catalog. * @returns The context with init options stored in `ctx.state.entry`. @@ -56,9 +60,46 @@ export const InitModule = { throw new Error(`Unknown base: ${baseKey}. Available: ${Object.keys(catalog.features).join(", ")}`); } + const upgradeability = resolveUpgradeability(ctx.param); + const selectedBase = baseKey === "none" ? ConfigModule.EMPTY_BASE : catalog.features[baseKey]; + const availableLibraryFacets = ConfigModule.getAvailableLibraryFacets(catalog, selectedBase); const selectedLibraries = splitCommaSeparated(ctx.param.libraries); const selectedExtensions = splitCommaSeparated(ctx.param.extensions); + const requestsUpgradeFacet = selectedLibraries.includes(ConfigModule.UPGRADE_FACET_NAME); + if (!upgradeability.upgradeable && upgradeability.explicit && requestsUpgradeFacet) { + throw new Error( + `${ConfigModule.UPGRADE_FACET_NAME} in --libraries conflicts with --immutable. ` + + "Remove it or use --upgradeable.", + ); + } + + // An explicit library entry opts into upgradeability for compatibility; + // otherwise the diamond is immutable unless --upgradeable is passed. + const upgradeable = upgradeability.upgradeable || requestsUpgradeFacet; + if ( + upgradeable + && !requestsUpgradeFacet + && ConfigModule.UPGRADE_FACET_NAME in availableLibraryFacets + ) { + selectedLibraries.push(ConfigModule.UPGRADE_FACET_NAME); + } + + const accessSelection = resolveAccessFlags(ctx.param); + const hasOwnership = + selectedBase.accessType === "ownership" || accessSelection.selectedOwnership.length > 0; + if (upgradeable && !hasOwnership) { + accessSelection.selectedOwnership = [ConfigModule.DEFAULT_OWNER_BASE]; + accessSelection.selectedAccess = uniqueStrings([ + ...accessSelection.selectedOwnership, + ...accessSelection.selectedRoleAccess, + ]); + console.log(dim( + "Upgradeable diamonds need an owner; added the " + + `'${ConfigModule.DEFAULT_OWNER_BASE}' base. Pass --ownership to choose another.`, + )); + } + const { selectedOwnership, selectedRoleAccess, @@ -66,7 +107,7 @@ export const InitModule = { selectedRoleAccessExtensions, selectedAccess, selectedAccessExtensions, - } = resolveAccessFlags(ctx.param); + } = accessSelection; ConfigModule.validateGroupedAccessFlags( catalog, @@ -105,6 +146,7 @@ export const InitModule = { framework, selectedBaseKey: baseKey, selectedBaseLabel: selection.selectedBase.label, + upgradeable, selectedLibraries, selectedAccess, selectedExtensions: selection.selectedExtensions, @@ -122,8 +164,8 @@ export const InitModule = { * Runs the init flow interactively using Inquirer prompt primitives. * * Prompts the user for project name, framework (Foundry/Hardhat), toolbox - * (for Hardhat), base, library facets, extension facets, access layers, - * access extension facets, and local example + * (for Hardhat), base, upgradeability, library facets, extension facets, + * access layers, access extension facets, and local example * facets via select and checkbox prompts. Each selection is validated against * the loaded bases catalog. * @@ -131,7 +173,7 @@ export const InitModule = { * @returns The context with user selections stored in `ctx.state.entry`. */ async runInitInteractive(ctx: ComposeContext): Promise { - const { input, checkbox, select } = await loadPrompts(); + const { input, checkbox, select, confirm } = await loadPrompts(); const catalog = ctx.config.bases as BasesCatalog; if (!ctx.param.projectName) { @@ -197,6 +239,15 @@ export const InitModule = { ? ConfigModule.EMPTY_BASE : catalog.features[selectedBaseKey]; + await clearStdin(); + const upgradeability = await select({ + message: "Select upgradeability:", + choices: getUpgradeabilityChoices(), + default: "immutable" as const, + theme: selectTheme, + }); + const upgradeable = upgradeability === "upgradeable"; + const availableExtensions = selectedBase.optional ?? {}; const extensionChoices = toFacetChoices(Object.keys(availableExtensions)); @@ -212,17 +263,25 @@ export const InitModule = { : []; const availableLibraryFacets = ConfigModule.getAvailableLibraryFacets(catalog, selectedBase); - const libraryChoices = toFacetChoices(Object.keys(availableLibraryFacets)); + const libraryChoices = toFacetChoices( + Object.keys(availableLibraryFacets).filter( + (facetName) => facetName !== ConfigModule.UPGRADE_FACET_NAME, + ), + ); await clearStdin(); - const selectedLibraries = await checkbox({ + const selectedLibraryFacets = await checkbox({ message: "Select Compose library facets:", choices: libraryChoices, theme: checkboxTheme, }); + const selectedLibraries = [...selectedLibraryFacets]; + if (upgradeable && ConfigModule.UPGRADE_FACET_NAME in availableLibraryFacets) { + selectedLibraries.push(ConfigModule.UPGRADE_FACET_NAME); + } const accessBases = ConfigModule.getAccessBases(catalog, selectedBaseKey); - const selectedOwnership = selectedBase.accessType === "ownership" + let selectedOwnership = selectedBase.accessType === "ownership" ? undefined : await (async () => { await clearStdin(); @@ -233,6 +292,22 @@ export const InitModule = { }); })(); + if (upgradeable && selectedBase.accessType !== "ownership" && !selectedOwnership) { + await clearStdin(); + const includeOwner = await confirm({ + message: "Upgradeable diamonds need an owner. Include the owner base?", + default: true, + }); + if (includeOwner) { + selectedOwnership = ConfigModule.DEFAULT_OWNER_BASE; + } else { + console.log(yellow( + "Upgradeable diamonds without an owner cannot be upgraded; " + + "add an ownership base before deploying.", + )); + } + } + const ownershipExtensionChoices = getOwnershipExtensionChoices(accessBases, selectedOwnership); const selectedOwnershipExtensions = ownershipExtensionChoices.length > 0 ? await (async () => { @@ -278,12 +353,19 @@ export const InitModule = { const { deps, packageType } = getFrameworkDependencies(framework, String(ctx.param.toolbox)); showDependencies(deps, packageType); - await clearStdin(); - const installDeps = await (await loadPrompts()).confirm({ - message: "Install project dependencies?", - default: true, - }); - ctx.param.installDeps = installDeps; + if (framework === "hardhat") { + // Hardhat's official non-interactive template initializer installs the + // selected toolbox and its peer dependencies as part of scaffolding. + ctx.param.installDeps = true; + console.log(dim("Hardhat 3 initializes from its official template and installs its dependencies.")); + } else { + await clearStdin(); + const installDeps = await confirm({ + message: "Install project dependencies?", + default: true, + }); + ctx.param.installDeps = installDeps; + } const selection = ConfigModule.resolveCatalogSelection( catalog, @@ -308,6 +390,7 @@ export const InitModule = { framework, selectedBaseKey, selectedBaseLabel: selectedBase.label, + upgradeable, selectedLibraries, selectedAccess, selectedExtensions: selection.selectedExtensions, diff --git a/cli/src/modules/init/output.ts b/cli/src/modules/init/output.ts index f0558193..3c1a3ce1 100644 --- a/cli/src/modules/init/output.ts +++ b/cli/src/modules/init/output.ts @@ -30,9 +30,8 @@ export function showDependencies(deps: { name: string; version: string }[], pack * Prints the success message with framework-specific next steps. * * Displays the project name, scaffolded path, and a numbered list of - * next-step commands (e.g. `forge build && forge test` for Foundry, - * `npx hardhat compile && npx hardhat test` for Hardhat). Adjusts steps - * based on whether `installDeps` is enabled. + * next-step commands. Adjusts steps based on whether `installDeps` is enabled + * and points to the locally installed Compose CLI (`npx compose`). * * @param ctx - The compose context with `param.projectName`, `param.projectRoot`, and `param.framework`. */ @@ -51,25 +50,24 @@ export function showSuccess(ctx: ComposeContext): void { } const framework = String(ctx.param.framework ?? "foundry"); - if (framework === "foundry") { - const installDeps = ctx.param.installDeps !== false; - if (installDeps) { - console.log(green(`${stepCount}.`) + ` forge build && forge test`); - } else { + const installDeps = ctx.param.installDeps !== false; + + if (!installDeps) { + console.log(green(`${stepCount}.`) + ` npm install`); + stepCount++; + if (framework === "foundry") { console.log(green(`${stepCount}.`) + ` forge install Perfect-Abstractions/Compose`); - console.log(green(`${stepCount + 1}.`) + ` forge build && forge test`); - } - } else if (framework === "hardhat") { - const installDeps = ctx.param.installDeps !== false; - if (installDeps) { - console.log(green(`${stepCount}.`) + ` npx hardhat compile && npx hardhat test`); - } else { - console.log(green(`${stepCount}.`) + ` npm install`); - console.log(green(`${stepCount + 1}.`) + ` npx hardhat compile && npx hardhat test`); + stepCount++; } } + console.log(green(`${stepCount}.`) + ` ${framework === "hardhat" ? "npx hardhat test" : "forge test"}`); + console.log(""); + if (!installDeps) { + console.log(dim("After `npm install`, run project scripts with `npm run ...` " + + "(e.g. `npm run validate`) or other Compose commands with `npx compose`.")); + } console.log(green("You're all set. We hope you'll Compose something great!\n")); console.log(yellow(`If this helped you, please give us a star on GitHub\n`) + `✨ https://github.com/Perfect-Abstractions/Compose ✨\n`); console.log(`Please report any issues or feedback:\nhttps://github.com/Perfect-Abstractions/Compose/issues\n`); diff --git a/cli/src/modules/init/projectScripts.ts b/cli/src/modules/init/projectScripts.ts new file mode 100644 index 00000000..8e748d2a --- /dev/null +++ b/cli/src/modules/init/projectScripts.ts @@ -0,0 +1,20 @@ +/** npm scripts added to generated projects for Compose-specific workflows. */ +export const COMPOSE_PROJECT_SCRIPTS = { + validate: "compose validate", +} as const; + +/** + * Adds the Compose project scripts without overwriting scripts the project + * already defines. + * + * @param scripts - Existing npm scripts from the generated project manifest. + * @returns The scripts with `validate` present. + */ +export function withComposeProjectScripts( + scripts: Record, +): Record { + return { + ...scripts, + validate: scripts.validate ?? COMPOSE_PROJECT_SCRIPTS.validate, + }; +} diff --git a/cli/src/modules/init/prompts.ts b/cli/src/modules/init/prompts.ts index 6072baa1..5d93e162 100644 --- a/cli/src/modules/init/prompts.ts +++ b/cli/src/modules/init/prompts.ts @@ -13,6 +13,18 @@ export function toFacetChoices(facetNames: string[]): { name: string; value: str })); } +/** + * Returns the upgradeability choices for the init prompt, with Immutable first (the default). + * + * @returns Choices for the upgradeability select prompt. + */ +export function getUpgradeabilityChoices(): { name: string; value: "upgradeable" | "immutable" }[] { + return [ + { name: "Immutable (no upgrade facet)", value: "immutable" }, + { name: "Upgradeable", value: "upgradeable" }, + ]; +} + /** * Returns ownership base choices for the select prompt, with "None" as the first option. * diff --git a/cli/src/modules/init/types.ts b/cli/src/modules/init/types.ts index 7b9d2e5a..7c5b5f32 100644 --- a/cli/src/modules/init/types.ts +++ b/cli/src/modules/init/types.ts @@ -81,6 +81,13 @@ export type AccessFlagSelection = { selectedAccessExtensions: string[]; }; +export type UpgradeabilitySelection = { + /** Whether the diamond includes the upgrade facet. */ + upgradeable: boolean; + /** Whether the choice came from an explicit flag instead of the default. */ + explicit: boolean; +}; + export type FrameworkDependencies = { deps: { name: string; version: string }[]; packageType: string; diff --git a/cli/src/modules/lockFile/module.ts b/cli/src/modules/lockFile/module.ts index 4588601e..4847c4f3 100644 --- a/cli/src/modules/lockFile/module.ts +++ b/cli/src/modules/lockFile/module.ts @@ -3,8 +3,8 @@ import path from "node:path"; import { type Hex } from "viem"; import { ComposeContext } from "../../context/types"; import { IHashingAdapter } from "../../adapters/IHashingAdapter/interface"; -import { atomicWriteFile, findFileAncestor } from "../../utils/files"; -import { ComposeLock, DiamondDeployment } from "./types"; +import { atomicWriteFile, pathExists } from "../../utils/files"; +import { ComposeLock, DEFAULT_INSTANCE, DiamondDeployment } from "./types"; import { validateLockFile } from "./validators"; import { LOCK_FILE_NAME } from "../../utils/metadata"; @@ -19,18 +19,20 @@ export const LockFileModule = { /** * Reads and validates compose.lock from the project root. * - * Searches for compose.lock by walking up the directory tree from the - * project root. Returns null result if file doesn't exist (not an error). + * The lock file belongs to exactly one Compose project, so the lookup is + * confined to the project root. Walking up from a nested project would pick + * up an unrelated parent lock and plan against the wrong deployments. + * Returns null result if the file doesn't exist (not an error). * Throws if file exists but is invalid. * * @param ctx - The compose context with project root parameter. * @returns The updated context with lock file state. */ async readLockFile(ctx: ComposeContext): Promise { - const startDir = String(ctx.param.projectRoot ?? process.cwd()); - const lockFilePath = await findFileAncestor(startDir, LOCK_FILE_NAME); + const projectRoot = String(ctx.param.projectRoot ?? process.cwd()); + const lockFilePath = path.join(projectRoot, LOCK_FILE_NAME); - if (!lockFilePath) { + if (!(await pathExists(lockFilePath))) { ctx.state.lockFile = { success: true, result: null, @@ -138,6 +140,7 @@ export const LockFileModule = { * @param chain - The chain to check. * @param facetAddresses - Current on-chain facet addresses. * @param hashing - Hashing adapter for keccak256 computation. + * @param instance - The deployment instance to check. * @returns True if the lock file is stale. */ isLockStale( @@ -146,8 +149,9 @@ export const LockFileModule = { chain: string, facetAddresses: Hex[], hashing: IHashingAdapter, + instance: string = DEFAULT_INSTANCE, ): boolean { - const deployment = lock.deployments[diamondName]?.[chain]; + const deployment = lock.deployments[diamondName]?.[chain]?.[instance]; if (!deployment) { return true; } @@ -162,14 +166,16 @@ export const LockFileModule = { * @param lock - The lock file content. * @param diamondName - The diamond name. * @param chain - The chain name. + * @param instance - The deployment instance. * @returns The deployment or undefined if not found. */ getDeployment( lock: ComposeLock, diamondName: string, chain: string, + instance: string = DEFAULT_INSTANCE, ): DiamondDeployment | undefined { - return lock.deployments[diamondName]?.[chain]; + return lock.deployments[diamondName]?.[chain]?.[instance]; }, /** @@ -181,6 +187,7 @@ export const LockFileModule = { * @param lock - The lock file content to update. * @param diamondName - The diamond name. * @param chain - The chain name. + * @param instance - The deployment instance. * @param deployment - The deployment details. * @returns The updated lock file content. */ @@ -188,15 +195,23 @@ export const LockFileModule = { lock: ComposeLock, diamondName: string, chain: string, + instance: string, deployment: DiamondDeployment, ): ComposeLock { + if (!instance) { + throw new Error("Deployment instance must be a non-empty string."); + } + return { ...lock, deployments: { ...lock.deployments, [diamondName]: { ...lock.deployments[diamondName], - [chain]: deployment, + [chain]: { + ...lock.deployments[diamondName]?.[chain], + [instance]: deployment, + }, }, }, }; diff --git a/cli/src/modules/lockFile/types.ts b/cli/src/modules/lockFile/types.ts index ab0c6021..e29d19c4 100644 --- a/cli/src/modules/lockFile/types.ts +++ b/cli/src/modules/lockFile/types.ts @@ -1,20 +1,26 @@ import { type Hex } from "viem"; +/** Instance used when a command does not select one. */ +export const DEFAULT_INSTANCE = "default"; + /** Top-level compose.lock structure */ export type ComposeLock = { /** Compose schema version (e.g., "0.0.3") */ compose: string; - /** Deployments organized by diamond name and chain */ + /** Deployments organized by diamond name, chain, and instance */ deployments: Deployments; }; /** Map of diamond names to their chain deployments */ export type Deployments = Record; -/** Map of chain names to deployment details */ -export type ChainDeployments = Record; +/** Map of chain names to instance deployments */ +export type ChainDeployments = Record; + +/** Map of instance names to deployment details */ +export type InstanceDeployments = Record; -/** Deployment details for a specific diamond on a specific chain */ +/** Deployment details for a specific diamond on a specific chain instance */ export type DiamondDeployment = { /** Diamond proxy contract address */ diamond: Hex; @@ -26,6 +32,10 @@ export type DiamondDeployment = { lastSync: string; /** Transaction hash of the deployment/upgrade */ txHash: Hex; + /** Public address that broadcast the deployment, when reported by the framework. */ + deployer?: Hex; + /** Hardhat Ignition journal identity, when the deployment used Ignition. */ + ignitionDeploymentId?: string; }; /** State stored in ctx.state.lockFile after reading */ diff --git a/cli/src/modules/lockFile/validators.ts b/cli/src/modules/lockFile/validators.ts index bb3b27f2..bb57bd27 100644 --- a/cli/src/modules/lockFile/validators.ts +++ b/cli/src/modules/lockFile/validators.ts @@ -44,25 +44,59 @@ function validateDiamondDeployments(diamondName: string, data: unknown): void { const chains = data as Record; for (const [chainName, chainData] of Object.entries(chains)) { - validateChainDeployment(diamondName, chainName, chainData); + validateChainDeployments(diamondName, chainName, chainData); } } /** - * Validates a chain deployment entry. + * Validates the instance deployments for a diamond on a chain. * * @param diamondName - The diamond name being validated. * @param chainName - The chain name being validated. - * @param data - The chain deployment data. - * @throws {Error} If the chain deployment structure is invalid. + * @param data - The chain deployments data. + * @throws {Error} If the chain deployments structure is invalid. */ -function validateChainDeployment(diamondName: string, chainName: string, data: unknown): void { +function validateChainDeployments(diamondName: string, chainName: string, data: unknown): void { if (!data || typeof data !== "object") { - throw new Error(`Deployment for '${diamondName}' on '${chainName}' must be an object`); + throw new Error(`Deployments for '${diamondName}' on '${chainName}' must be an object`); + } + + const instances = data as Record; + if (typeof instances.diamond === "string") { + throw new Error( + `Deployments for '${diamondName}' on '${chainName}' use the legacy lock format; ` + + `nest each deployment under an instance, for example { "default": { ... } }.`, + ); + } + + for (const [instance, instanceData] of Object.entries(instances)) { + validateInstanceDeployment(diamondName, chainName, instance, instanceData); + } +} + +/** + * Validates a single instance deployment entry. + * + * @param diamondName - The diamond name being validated. + * @param chainName - The chain name being validated. + * @param instance - The instance name being validated. + * @param data - The instance deployment data. + * @throws {Error} If the instance deployment structure is invalid. + */ +function validateInstanceDeployment( + diamondName: string, + chainName: string, + instance: string, + data: unknown, +): void { + if (!data || typeof data !== "object") { + throw new Error( + `Deployment for '${diamondName}' on '${chainName}' instance '${instance}' must be an object`, + ); } const deployment = data as Record; - const prefix = `'${diamondName}' on '${chainName}'`; + const prefix = `'${diamondName}' on '${chainName}' instance '${instance}'`; // Validate diamond address if (typeof deployment.diamond !== "string" || !isAddress(deployment.diamond, { strict: false })) { @@ -95,4 +129,18 @@ function validateChainDeployment(diamondName: string, chainName: string, data: u if (typeof deployment.txHash !== "string" || !deployment.txHash.startsWith("0x")) { throw new Error(`${prefix}: invalid or missing 'txHash'`); } + + if ( + deployment.deployer !== undefined + && (typeof deployment.deployer !== "string" || !isAddress(deployment.deployer, { strict: false })) + ) { + throw new Error(`${prefix}: invalid 'deployer' address`); + } + + if ( + deployment.ignitionDeploymentId !== undefined + && (typeof deployment.ignitionDeploymentId !== "string" || deployment.ignitionDeploymentId.length === 0) + ) { + throw new Error(`${prefix}: invalid 'ignitionDeploymentId'`); + } } diff --git a/cli/src/modules/pipelineBuilder/module.ts b/cli/src/modules/pipelineBuilder/module.ts index 2d112d21..00fa7aba 100644 --- a/cli/src/modules/pipelineBuilder/module.ts +++ b/cli/src/modules/pipelineBuilder/module.ts @@ -3,11 +3,14 @@ import { InitPipeline } from "../../pipelines/initPipeline"; import { InfoPipeline } from "../../pipelines/infoPipeline"; import { CatalogPipeline } from "../../pipelines/catalogPipeline"; import { BuildPipeline } from "../../pipelines/buildPipeline"; +import { TestPipeline } from "../../pipelines/testPipeline"; import { RPCPipeline } from "../../pipelines/rpcPipeline"; import { InspectPipeline } from "../../pipelines/inspectPipeline"; import { ValidatePipeline } from "../../pipelines/validatePipeline"; import { InstallPipeline } from "../../pipelines/installPipeline"; import { RemovePipeline } from "../../pipelines/removePipeline"; +import { DeployPipeline } from "../../pipelines/deployPipeline"; +import { AccountPipeline } from "../../pipelines/accountPipeline"; /** * Pipeline builder module that routes CLI commands to their corresponding pipelines. @@ -64,6 +67,13 @@ export const PipelineBuilderModule = { error: null, }; return BuildPipeline.execute(ctx); + case "test": + ctx.state.commandSelected = { + success: true, + result: { command: ctx.param.command }, + error: null, + }; + return TestPipeline.execute(ctx); case "rpc": ctx.state.commandSelected = { success: true, @@ -92,6 +102,26 @@ export const PipelineBuilderModule = { error: null, }; return RemovePipeline.execute(ctx); + case "deploy": + ctx.state.commandSelected = { + success: true, + result: { + command: ctx.param.command, + diamond: ctx.param.diamond, + chain: ctx.param.chain, + instance: ctx.param.instance, + account: ctx.param.account, + }, + error: null, + }; + return DeployPipeline.execute(ctx); + case "account": + ctx.state.commandSelected = { + success: true, + result: { command: ctx.param.command, action: ctx.param.action }, + error: null, + }; + return AccountPipeline.execute(ctx); default: ctx.state.commandRouting = { success: false, diff --git a/cli/src/modules/preflight/module.ts b/cli/src/modules/preflight/module.ts index 2ce99490..ca44df96 100644 --- a/cli/src/modules/preflight/module.ts +++ b/cli/src/modules/preflight/module.ts @@ -1,5 +1,6 @@ import { ComposeContext } from "../../context/types"; import { isBinaryInPath } from "../../utils/exec"; +import { assertHardhatNodeVersion } from "../../utils/nodeVersion"; /** * Pre-flight checks that verify required toolchain binaries are available. @@ -9,28 +10,40 @@ import { isBinaryInPath } from "../../utils/exec"; */ export const PreflightModule = { /** - * Verifies that the required binary for the selected framework exists in PATH. + * Verifies the toolchain requirements for the selected framework. * - * - Foundry: checks for `forge`. - * - Hardhat with `installDeps !== false`: checks for `npm`. + * - Foundry: checks for `forge`, plus `npm` when project dependencies + * (including the local Compose CLI) will be installed. + * - Hardhat: requires Node.js 22.13+, npm, git (the official template includes + * forge-std), and dependency installation because its non-interactive + * initializer installs the selected template. * - * Throws an error with an install suggestion if the binary is not found. + * Throws an error with an install suggestion if a requirement is not met. * * @param ctx - The compose context with `param.framework` and `param.installDeps`. * @returns The context unchanged (validation is pass/fail via throw). */ async check(ctx: ComposeContext): Promise { const framework = String(ctx.param.framework ?? "foundry").toLowerCase(); + const shouldInstallDeps = ctx.param.installDeps !== false; if (framework === "foundry") { await isBinaryInPath("forge"); - } else if (framework === "hardhat") { - const shouldInstallDeps = ctx.param.installDeps !== false; if (shouldInstallDeps) { await isBinaryInPath("npm"); } + } else if (framework === "hardhat") { + assertHardhatNodeVersion(); + if (!shouldInstallDeps) { + throw new Error( + "Hardhat's official non-interactive initializer installs the selected template dependencies. " + + "Use --install-deps for Hardhat projects.", + ); + } + await isBinaryInPath("npm"); + await isBinaryInPath("git"); } return ctx; }, -}; \ No newline at end of file +}; diff --git a/cli/src/modules/scaffolding/module.ts b/cli/src/modules/scaffolding/module.ts index eb82bef8..8aaca862 100644 --- a/cli/src/modules/scaffolding/module.ts +++ b/cli/src/modules/scaffolding/module.ts @@ -201,6 +201,7 @@ export const ScaffoldingModule = { }, chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 }, + sepolia: { rpc: "${SEPOLIA_RPC_URL}", chainId: 11155111 }, }, }; diff --git a/cli/src/modules/testGeneration/model.ts b/cli/src/modules/testGeneration/model.ts index 8c12562c..6d388c89 100644 --- a/cli/src/modules/testGeneration/model.ts +++ b/cli/src/modules/testGeneration/model.ts @@ -1,58 +1,92 @@ import path from "node:path"; import { ComposeContext, ModuleState } from "../../context/types"; -import { TestFacetEntry, TestGenerationModel } from "./types"; - -/** Result shape from the deploy script generation step. */ -type DeployScriptResult = { - outputPath: string; - facets: { - facetName: string; - contractName: string; - importPath: string; - group: string; - }[]; - framework: string; - toolbox: string | null; -}; +import { toPosixPath } from "../../utils/files"; +import { ScaffoldingModule } from "../scaffolding/module"; +import { ScaffoldMapEntry, SelectedFacet, SelectedFacetSource } from "../scaffolding/types"; +import { TestFacetEntry, TestFacetGroup, TestGenerationModel } from "./types"; /** - * Extracts the deploy script generation result from the compose context. + * Classifies a selected facet source into a test section group. + * Base-required facets and extensions are grouped as "base"; others as "library". * - * @param ctx - The compose context with deploy script state. - * @returns The deploy script result. - * @throws {Error} If deploy script generation is missing or failed. + * @param source - The source type of the selected facet. + * @returns The test group classification. */ -function getDeployResult(ctx: ComposeContext): DeployScriptResult { - const state = ctx.state.generateDeployScript as ModuleState | undefined; +function classifyTestGroup(source: SelectedFacetSource): TestFacetGroup { + if (source === "base-required" || source === "extension") { + return "base"; + } + return "library"; +} + +/** + * Extracts scaffold map entries from the compose context state. + * + * @param ctx - The compose context containing scaffold map state. + * @returns The list of scaffold map entries. + * @throws {Error} If the scaffold map is missing or in a failed state. + */ +function getScaffoldEntries(ctx: ComposeContext): ScaffoldMapEntry[] { + const state = ctx.state.scaffoldMap as ModuleState<{ entries: ScaffoldMapEntry[] }> | undefined; if (!state?.success || !state.result) { - throw new Error("Cannot generate test: deploy script generation is missing."); + throw new Error("Cannot generate test: scaffold map is missing."); } - return state.result; + return state.result.entries; } /** - * Resolves the test generation model by extracting facet entries from the - * deploy script result. + * Resolves the test generation model by combining scaffold entries with selected + * facets. Produces ordered facet entries with import paths relative to the + * project root, grouped by base facets first, then library facets. * - * @param ctx - The compose context with deploy script generation state. + * @param ctx - The compose context with project state and parameters. * @param testRoot - Directory where the test file will be written. * @param outputFileName - Name of the output test file. - * @returns The test generation model with output path and facet entries. - * @throws {Error} If deploy script generation is missing. + * @returns The test generation model with output path and ordered facet entries. + * @throws {Error} If project root, test root, or scaffold entries are invalid. */ export function resolveTestGenerationModel( ctx: ComposeContext, testRoot: string, outputFileName: string, ): TestGenerationModel { - const deployResult = getDeployResult(ctx); - - const facets: TestFacetEntry[] = deployResult.facets.map((facet) => ({ - facetName: facet.facetName, - contractName: facet.contractName, - importPath: facet.importPath, - group: facet.group as TestFacetEntry["group"], - })); + const projectRoot = String(ctx.param.projectRoot ?? ""); + if (!projectRoot) { + throw new Error("Cannot generate test: project root is empty."); + } + if (!testRoot) { + throw new Error("Cannot generate test: test root is empty."); + } + + const scaffoldEntries = getScaffoldEntries(ctx); + const scaffoldByFacetName = new Map(scaffoldEntries.map((entry) => [entry.facetName, entry])); + const selectedFacets = ScaffoldingModule.getSelectedFacets(ctx); + + const facetEntries = selectedFacets.map((facet: SelectedFacet): TestFacetEntry => { + const scaffoldEntry = scaffoldByFacetName.get(facet.name); + if (!scaffoldEntry) { + throw new Error(`Cannot generate test: scaffold entry not found for ${facet.name}.`); + } + + const importPath = scaffoldEntry.origin === "package" + ? scaffoldEntry.targetPath + : toPosixPath(path.relative(projectRoot, scaffoldEntry.targetPath)); + if (!importPath) { + throw new Error(`Cannot generate test: invalid import path for ${facet.name}.`); + } + + return { + facetName: facet.name, + contractName: scaffoldEntry.contractName, + importPath, + group: classifyTestGroup(facet.source), + }; + }); + + const facets = [ + ...facetEntries.filter((entry) => entry.group === "base"), + ...facetEntries.filter((entry) => entry.group === "library"), + ]; return { outputPath: path.join(testRoot, outputFileName), diff --git a/cli/src/modules/testGeneration/types.ts b/cli/src/modules/testGeneration/types.ts index 702bb6d9..efa00e2d 100644 --- a/cli/src/modules/testGeneration/types.ts +++ b/cli/src/modules/testGeneration/types.ts @@ -1,10 +1,11 @@ -import { DeployFacetGroup } from "../deployGeneration/types"; +/** Test section group: base facets render before library facets. */ +export type TestFacetGroup = "base" | "library"; export type TestFacetEntry = { facetName: string; contractName: string; importPath: string; - group: DeployFacetGroup; + group: TestFacetGroup; }; export type TestGenerationModel = { diff --git a/cli/src/modules/validation/astSelectors.ts b/cli/src/modules/validation/astSelectors.ts index d9f3336e..2317540b 100644 --- a/cli/src/modules/validation/astSelectors.ts +++ b/cli/src/modules/validation/astSelectors.ts @@ -1,4 +1,4 @@ -import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/interface"; +import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/types"; import { matchesAstSource } from "./astIdentity"; import { astNode, diff --git a/cli/src/modules/validation/module.ts b/cli/src/modules/validation/module.ts index 616e94fe..67e26299 100644 --- a/cli/src/modules/validation/module.ts +++ b/cli/src/modules/validation/module.ts @@ -1,5 +1,5 @@ import { ComposeContext } from "../../context/types"; -import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/interface"; +import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/types"; import { DiamondValidationScope, FacetReference, SelectorCollisionDeps } from "./types"; import { matchesAstSource } from "./astIdentity"; import { scanFacetSelectorsFromAst } from "./astSelectors"; diff --git a/cli/src/modules/validation/project.ts b/cli/src/modules/validation/project.ts index 885d4d23..eb86730a 100644 --- a/cli/src/modules/validation/project.ts +++ b/cli/src/modules/validation/project.ts @@ -1,6 +1,7 @@ import path from "node:path"; import { ComposeContext } from "../../context/types"; import { locateComposeProjectFile, readComposeProjectFile } from "../../utils/composeProjectFile"; +import { assertSolidityContractName } from "../../utils/solidityIdentifiers"; import { ResolvedFacetSource } from "./types"; import { ComposeProjectFacet, @@ -79,6 +80,16 @@ export async function loadValidationProject( if (!diamondSourcePath) { throw new Error("Every diamond in compose.json must define its generated contract path."); } + const diamondContractSuffix = diamondReference.lastIndexOf(":"); + const diamondContractName = diamondContractSuffix >= 0 + ? diamondReference.slice(diamondContractSuffix + 1) + : ""; + if (diamondContractName) { + assertSolidityContractName( + diamondContractName, + `diamond ${JSON.stringify(diamondName)} in compose.json`, + ); + } const resolvedDiamondSourcePath = path.resolve(projectRoot, diamondSourcePath); const diamondFacetIndexes: number[] = []; diamondSourcePaths.add(resolvedDiamondSourcePath); @@ -90,6 +101,10 @@ export async function loadValidationProject( ? contractReference.slice(separatorIndex + 1) : facetAlias; if (!contractName) continue; + assertSolidityContractName( + contractName, + `facet ${JSON.stringify(facetAlias)} in diamond ${JSON.stringify(diamondName)}`, + ); if (facet.source === "package") { const packageName = typeof facet.package === "string" ? facet.package : ""; @@ -120,7 +135,11 @@ export async function loadValidationProject( throw new Error("compose.json does not define any facets to validate."); } - const composeFacetSources = await resolveComposeProjectFacetSources(projectRoot, composeFacets); + const composeFacetSources = await resolveComposeProjectFacetSources( + projectRoot, + composeFacets, + framework, + ); const userFacetSources = resolveUserProjectFacetSources(projectRoot, userFacets); const resolvedFacets = pendingFacets.map((facet) => facet.kind === "compose" ? composeFacetSources[facet.kindIndex] diff --git a/cli/src/modules/validation/projectSourceResolution.ts b/cli/src/modules/validation/projectSourceResolution.ts index 24490c02..aed8382c 100644 --- a/cli/src/modules/validation/projectSourceResolution.ts +++ b/cli/src/modules/validation/projectSourceResolution.ts @@ -16,6 +16,7 @@ export type UserProjectFacet = { export async function resolveComposeProjectFacetSources( projectRoot: string, facets: ComposeProjectFacet[], + framework?: string, ): Promise { return Promise.all( facets.map(async (facet) => ({ @@ -24,6 +25,7 @@ export async function resolveComposeProjectFacetSources( projectRoot, facet.packageName, facet.contractName, + framework, ), })), ); @@ -44,8 +46,14 @@ async function findPackageFacetSource( projectRoot: string, packageName: string, facetName: string, + framework?: string, ): Promise { - const matches = await findPackageFacetSourceMatches(projectRoot, packageName, facetName); + const matches = await findPackageFacetSourceMatches( + projectRoot, + packageName, + facetName, + { framework }, + ); const uniqueMatches = [...new Set(matches.map((match) => path.resolve(match)))]; if (uniqueMatches.length === 0) { throw new Error(`Package facet source not found: ${packageName}/${facetName}.sol`); diff --git a/cli/src/modules/validation/virtualStorageLayout.ts b/cli/src/modules/validation/virtualStorageLayout.ts index e438eebc..57d72814 100644 --- a/cli/src/modules/validation/virtualStorageLayout.ts +++ b/cli/src/modules/validation/virtualStorageLayout.ts @@ -1,5 +1,5 @@ import { keccak256, stringToBytes, toHex } from "viem"; -import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/interface"; +import { SolidityAstSource } from "../../adapters/IFrameworkAdapter/types"; import { matchesAstSource } from "./astIdentity"; import { astNode, diff --git a/cli/src/pipelines/accountPipeline.ts b/cli/src/pipelines/accountPipeline.ts new file mode 100644 index 00000000..d087a133 --- /dev/null +++ b/cli/src/pipelines/accountPipeline.ts @@ -0,0 +1,74 @@ +import type { IFrameworkAdapter } from "../adapters/IFrameworkAdapter/interface"; +import type { ComposeContext, ModuleState } from "../context/types"; +import { AccountModule } from "../modules/accounts/module"; +import type { AccountActionResult } from "../modules/accounts/types"; +import type { Framework } from "../modules/framework/module"; +import { DependencyKey } from "../resolver/dependencyKey"; +import { DependencyResolver } from "../resolver/dependencyResolver"; +import { toComposeError } from "../utils/errors"; + +function requireFramework( + composeJson: Record, + purpose: "checking" | "setting up", +): Framework { + const framework = composeJson.framework; + if (framework !== "foundry" && framework !== "hardhat") { + throw new Error(`compose.json must select the 'foundry' or 'hardhat' framework before ${purpose} accounts.`); + } + return framework; +} + +async function resolveFrameworkAdapter(framework: Framework): Promise { + const key = framework === "foundry" ? DependencyKey.Foundry : DependencyKey.Hardhat; + const dependencies = await DependencyResolver.resolve([{ key }]); + const adapter = dependencies[key] as IFrameworkAdapter | undefined; + if (!adapter) throw new Error(`The ${framework} framework adapter was not resolved.`); + return adapter; +} + +/** Account pipeline for setting up, checking, listing, and removing non-secret aliases. */ +export const AccountPipeline = { + /** + * Loads the project, resolves the framework adapter when needed, and delegates + * the requested action to the accounts module. + * + * Failures are recorded in `state.account` and `status` so the entrypoint can + * exit non-zero without turning expected validation errors into crashes. + * + * @param ctx - The compose context with command parameters. + * @returns The context after the account action completes. + */ + async execute(ctx: ComposeContext): Promise { + try { + const project = await AccountModule.loadProject(ctx); + const action = String(ctx.param.action ?? ""); + + if (action !== "check" && action !== "setup") { + return await AccountModule.execute(ctx, project); + } + + const framework = requireFramework( + project.composeJson, + action === "check" ? "checking" : "setting up", + ); + const adapter = await resolveFrameworkAdapter(framework); + return await AccountModule.execute(ctx, project, { framework, adapter }); + } catch (error) { + const resolved = toComposeError(error, "ACCOUNT_FAILED", "Account command failed."); + const state: ModuleState = { + success: false, + result: null, + error: resolved, + }; + ctx.state.account = state; + ctx.status = { + success: false, + stopped: true, + failedAt: "account", + error: resolved, + }; + console.error(resolved.message); + return ctx; + } + }, +}; diff --git a/cli/src/pipelines/bytecodeValidationPipeline.ts b/cli/src/pipelines/bytecodeValidationPipeline.ts index d95d4875..1e90bb28 100644 --- a/cli/src/pipelines/bytecodeValidationPipeline.ts +++ b/cli/src/pipelines/bytecodeValidationPipeline.ts @@ -5,16 +5,7 @@ import type { IDiamondAdapter } from "../adapters/IDiamondAdapter/interface"; import { BytecodeValidationModule } from "../modules/bytecodeValidation/module"; import { DependencyKey } from "../resolver/dependencyKey"; import { DependencyResolver } from "../resolver/dependencyResolver"; - -function composeError(error: unknown) { - return { - code: typeof error === "object" && error && "code" in error - ? String(error.code) - : "BYTECODE_VALIDATION_FAILED", - message: error instanceof Error ? error.message : "Bytecode validation failed.", - nativeError: error, - }; -} +import { toComposeError } from "../utils/errors"; /** Child pipeline for one diamond deployment on one chain. */ export const BytecodeValidationPipeline = { @@ -54,7 +45,11 @@ export const BytecodeValidationPipeline = { } return ctx; } catch (error) { - const resolvedError = composeError(error); + const resolvedError = toComposeError( + error, + "BYTECODE_VALIDATION_FAILED", + "Bytecode validation failed.", + ); ctx.state.bytecodeDeploymentValidation = { success: false, result: null, diff --git a/cli/src/pipelines/deployPipeline.ts b/cli/src/pipelines/deployPipeline.ts new file mode 100644 index 00000000..9784071c --- /dev/null +++ b/cli/src/pipelines/deployPipeline.ts @@ -0,0 +1,257 @@ +import type { ComposeContext, ModuleState } from "../context/types"; +import type { IHashingAdapter } from "../adapters/IHashingAdapter/interface"; +import type { IFrameworkAdapter } from "../adapters/IFrameworkAdapter/interface"; +import type { IRPCAdapter } from "../adapters/IRPCAdapter/interface"; +import type { IDiamondAdapter } from "../adapters/IDiamondAdapter/interface"; +import { DependencyKey } from "../resolver/dependencyKey"; +import { DependencyResolver } from "../resolver/dependencyResolver"; +import { LockFileModule } from "../modules/lockFile/module"; +import type { ComposeLock, DiamondDeployment } from "../modules/lockFile/types"; +import { VERSION } from "../utils/metadata"; +import { assertSafeDeploymentPassthrough, toPassthroughArgs } from "../utils/args"; +import { toProjectRelativePath } from "../utils/files"; +import { DeployPlanModule } from "../modules/deployPlan/module"; +import type { DeployPlan } from "../modules/deployPlan/types"; +import { showDeployPlan, showDiffStopped, showInSync } from "../modules/deployPlan/output"; +import { DeployScriptModule } from "../modules/deployScript/module"; +import type { ManagedScriptModel } from "../modules/deployScript/types"; +import { showScriptReady } from "../modules/deployScript/output"; +import { DeployExecutionModule } from "../modules/deployExecution/module"; +import type { DeployExecutionResult } from "../modules/deployExecution/types"; +import { getIgnitionDeploymentId } from "../modules/deployScript/model"; +import { DeployVerificationModule } from "../modules/deployVerification/module"; +import { showDeploySuccess } from "../modules/deployVerification/output"; +import { DeploySimulationModule } from "../modules/deploySimulation/module"; +import { showDeploySimulationSuccess } from "../modules/deploySimulation/output"; +import { loadValidationProject } from "../modules/validation/project"; +import { toComposeError } from "../utils/errors"; + +/** + * Deploy pipeline. + * + * Orchestrates fresh deployments end to end: plan the composition against + * compose.json and compose.lock, generate (or reuse) the managed framework + * script, execute it under the framework, verify the result on-chain, and + * record the verified deployment in compose.lock. + * + * The plan is never re-read from the chain before execution; verification is + * the only consumer of chain state, so a failed deployment leaves the lock + * untouched. + */ +export const DeployPipeline = { + /** + * Runs the deploy flow for the command parameters. + * + * @param ctx - The compose context with command parameters. + * @returns The context with `state.deployPipeline` set on failure. + */ + async execute(ctx: ComposeContext): Promise { + let stage = "deployPlan"; + + try { + if (ctx.param.dryRun && ctx.param.broadcast) { + throw new Error("Use either --dry-run or --broadcast, not both."); + } + + // The project defines the framework, so load it before resolving any + // adapter: the script path, renderer, and execution all follow the + // framework recorded in compose.json. + const project = await loadValidationProject(ctx); + const framework = String(ctx.param.framework) as DependencyKey; + + const deployMode = ctx.param.dryRun + ? "simulate" + : ctx.param.broadcast + ? "broadcast" + : "prepare"; + + const frameworkDependencies = await DependencyResolver.resolve([ + { key: DependencyKey.Hashing }, + { key: framework }, + ]); + + const adapter = frameworkDependencies[framework] as IFrameworkAdapter | undefined; + const hashing = frameworkDependencies[DependencyKey.Hashing] as IHashingAdapter | undefined; + + if (!adapter || !hashing) throw new Error("Deploy dependencies were not resolved."); + + adapter.assertSupportedProject(String(ctx.param.projectRoot)); + + ctx = await DeployPlanModule.resolve(ctx, { project, adapter, hashing }); + + const planState = ctx.state.deployPlan as ModuleState; + const plan = planState.result; + if (!plan) throw new Error("Deploy plan was not resolved."); + + assertSafeDeploymentPassthrough( + ctx.param.passthrough, + plan.framework, + plan.account !== null, + deployMode, + ); + + if (plan.mode === "in-sync") { + showInSync(plan); + return ctx; + } + + if (plan.mode === "diff") { + showDiffStopped(plan); + const error = { + code: "COMPOSITION_CHANGED", + message: `compose.json differs from the recorded deployment of '${plan.diamondName}'.`, + nativeError: null, + }; + ctx.state.deployPipeline = { success: false, result: { stage }, error }; + ctx.status = { success: false, stopped: true, failedAt: stage, error }; + return ctx; + } + + showDeployPlan(plan); + + stage = "deployScript"; + ctx = await DeployScriptModule.buildModel(ctx, adapter); + const scriptState = ctx.state.deployScript as ModuleState<{ + path: string; + model: ManagedScriptModel; + }>; + const scriptPath = scriptState.result?.path; + const model = scriptState.result?.model; + if (!scriptPath || !model) throw new Error("Deploy script model was not resolved."); + const expectedSource = await DeployScriptModule.render(model); + + const expectedScriptHash = hashing.keccak256(expectedSource); + const scriptHash = await DeployScriptModule.readScriptHash(scriptPath, hashing); + const scriptMatchesExpected = scriptHash === expectedScriptHash; + + if (deployMode === "prepare") { + if (!scriptMatchesExpected) { + await DeployScriptModule.writeSource(scriptPath, expectedSource); + } + showScriptReady(plan.projectRoot, scriptPath); + return ctx; + } + + if (!scriptMatchesExpected) { + const modeFlag = deployMode === "simulate" ? "dry-run" : "broadcast"; + throw new Error( + `The managed deployment artifact at ${toProjectRelativePath(plan.projectRoot, scriptPath)} is missing, modified, or stale. ` + + `Run 'compose deploy', review the generated artifact, then retry with --${modeFlag}.`, + ); + } + + // Probe and pin the target before a fork simulation or live broadcast. + const chainDependencies = await DependencyResolver.resolve([ + { key: DependencyKey.RPC, params: { resolvedChain: plan.chain } }, + ...(deployMode !== "simulate" + ? [{ key: DependencyKey.Diamond, params: { resolvedChain: plan.chain } }] + : []), + ]); + const rpc = chainDependencies[DependencyKey.RPC] as IRPCAdapter | undefined; + if (!rpc) throw new Error("Deploy RPC dependency was not resolved."); + + if (deployMode === "simulate") { + stage = "deploySimulation"; + // The Hardhat runner is invoked with `--no-compile`, so build the + // production artifacts it will execute against. + if (plan.framework === "hardhat") await adapter.compile(plan.projectRoot); + const forkBlockNumber = await rpc.getBlockNumber(); + if (plan.framework === "hardhat") await DeployScriptModule.writeRunner(model); + ctx = await DeploySimulationModule.simulate( + ctx, + plan, + scriptPath, + adapter, + forkBlockNumber, + model.runnerPath, + ); + showDeploySimulationSuccess(plan, scriptPath, forkBlockNumber); + return ctx; + } + + const diamond = chainDependencies[DependencyKey.Diamond] as IDiamondAdapter | undefined; + if (!diamond) throw new Error("Deploy diamond dependency was not resolved."); + + stage = "deployExecution"; + // `forge script` compiles the Foundry project itself. Hardhat's `run` + // would also compile on its own, but building once here keeps the + // production artifacts deterministic before the signer probe and runner, + // which both pass `--no-compile`. + if (plan.framework === "hardhat") await adapter.compile(plan.projectRoot); + + // Resolve the signer before generating the runtime wrapper so the + // Ignition journal is scoped to the account that will actually sign, + // including a framework-selected default. + const expectedSigner = await adapter.resolveDeploySigner({ + projectRoot: plan.projectRoot, + chainKey: plan.chain.chainKey, + rpcUrl: plan.chain.rpcUrl, + chainId: plan.chain.chainId, + account: plan.account, + passthrough: toPassthroughArgs(ctx.param.passthrough), + }); + if (plan.framework === "hardhat") { + await DeployScriptModule.writeRunner({ + ...model, + ignitionDeploymentId: getIgnitionDeploymentId(plan, expectedSigner), + }); + } + ctx = await DeployExecutionModule.execute( + ctx, + plan, + scriptPath, + adapter, + model.runnerPath, + expectedSigner, + ); + const executionState = ctx.state.deployExecution as ModuleState; + if (!executionState?.success || !executionState.result) { + throw new Error(executionState?.error?.message ?? "Deployment failed."); + } + + stage = "deployVerification"; + ctx = await DeployVerificationModule.verify(ctx, plan, executionState.result, { + diamond, + hashing, + rpc, + }); + const verificationState = ctx.state.deployVerification as ModuleState; + if (!verificationState?.success || !verificationState.result) { + const error = verificationState?.error ?? null; + ctx.state.deployPipeline = { success: false, result: { stage }, error }; + ctx.status = { + success: false, + stopped: true, + failedAt: stage, + error, + }; + return ctx; + } + + stage = "lockFileWrite"; + const lockState = ctx.state.lockFile as ModuleState<{ path: string; lock: ComposeLock } | null>; + const lock = lockState?.result?.lock ?? LockFileModule.createEmptyLock(VERSION); + const nextLock = LockFileModule.setDeployment( + lock, + plan.diamondName, + plan.chain.chainKey, + plan.instance, + verificationState.result, + ); + ctx = await LockFileModule.writeLockFile(ctx, nextLock); + const writeState = ctx.state.lockFileWrite as ModuleState<{ path: string }>; + if (!writeState?.success || !writeState.result) { + throw new Error(writeState?.error?.message ?? "Failed to write compose.lock."); + } + + showDeploySuccess(plan, verificationState.result, writeState.result.path); + return ctx; + } catch (error) { + const resolved = toComposeError(error, "DEPLOY_FAILED", "Deploy failed."); + ctx.state.deployPipeline = { success: false, result: { stage }, error: resolved }; + ctx.status = { success: false, stopped: true, failedAt: stage, error: resolved }; + console.error(resolved.message); + return ctx; + } + }, +}; diff --git a/cli/src/pipelines/initPipeline.ts b/cli/src/pipelines/initPipeline.ts index f9e13202..225e9066 100644 --- a/cli/src/pipelines/initPipeline.ts +++ b/cli/src/pipelines/initPipeline.ts @@ -6,7 +6,6 @@ import { PreflightModule } from "../modules/preflight/module"; import { ProjectDirModule } from "../modules/projectDir/module"; import { ScaffoldingModule } from "../modules/scaffolding/module"; import { DiamondGenerationModule } from "../modules/diamondGeneration/module"; -import { DeployGenerationModule } from "../modules/deployGeneration/module"; import { TestGenerationModule } from "../modules/testGeneration/module"; import { DependencyKey } from "../resolver/dependencyKey"; import { DependencyResolver } from "../resolver/dependencyResolver"; @@ -104,10 +103,6 @@ export const InitPipeline = { } ctx = await DiamondGenerationModule.generateDiamondContract(ctx, contractSourceRoot); - ctx = await DeployGenerationModule.generateDeployScript( - ctx, - adapter.getScriptRoot(root), - ); ctx = await TestGenerationModule.generateTestFile( ctx, adapter.getTestRoot(root), diff --git a/cli/src/pipelines/testPipeline.ts b/cli/src/pipelines/testPipeline.ts new file mode 100644 index 00000000..29fd67ef --- /dev/null +++ b/cli/src/pipelines/testPipeline.ts @@ -0,0 +1,49 @@ +import path from "node:path"; +import type { IFrameworkAdapter } from "../adapters/IFrameworkAdapter/interface"; +import type { ComposeContext } from "../context/types"; +import { FrameworkModule } from "../modules/framework/module"; +import { DependencyKey } from "../resolver/dependencyKey"; +import { DependencyResolver } from "../resolver/dependencyResolver"; +import { toPassthroughArgs } from "../utils/args"; +import { locateComposeProjectFile } from "../utils/composeProjectFile"; +import { runCommand } from "../utils/exec"; + +/** + * Test pipeline. + * + * Resolves the nearest Compose project root, detects its framework, and runs + * the framework's native test command with inherited stdio. Test output and + * exit codes stay in the framework's hands; everything after `--` is + * forwarded as-is. + */ +export const TestPipeline = { + async execute(ctx: ComposeContext): Promise { + const startDirectory = String(ctx.param.projectRoot ?? process.cwd()); + const composeProject = await locateComposeProjectFile(startDirectory); + const projectRoot = composeProject?.root ?? path.resolve(startDirectory); + + const framework = FrameworkModule.detect(projectRoot); + if (!framework) { + throw new Error( + `No supported framework detected in ${projectRoot}. ` + + `Expected foundry.toml or hardhat.config.*`, + ); + } + const deps = await DependencyResolver.resolve([ + { key: framework as DependencyKey }, + ]); + const adapter = deps[framework as DependencyKey] as IFrameworkAdapter | undefined; + if (!adapter) { + throw new Error(`${framework} adapter was not resolved.`); + } + adapter.assertSupportedProject(projectRoot); + + const command = adapter.createTestCommand({ + projectRoot, + passthrough: toPassthroughArgs(ctx.param.passthrough), + }); + await runCommand(command.command, command.args, { cwd: projectRoot }); + + return ctx; + }, +}; diff --git a/cli/src/pipelines/validatePipeline.ts b/cli/src/pipelines/validatePipeline.ts index e663af04..958863e7 100644 --- a/cli/src/pipelines/validatePipeline.ts +++ b/cli/src/pipelines/validatePipeline.ts @@ -58,16 +58,19 @@ export const ValidatePipeline = { const childContexts: ComposeContext[] = []; for (const diamond of project.diamonds) { const chainDeployments = lockState.result.lock.deployments[diamond.name] ?? {}; - for (const [chainKey, deployment] of Object.entries(chainDeployments)) { - const child = Context.create(); - child.param = { - projectRoot: ctx.param.projectRoot, - diamondName: diamond.name, - chainKey, - diamondAddress: deployment.diamond, - virtualStorageRecords: records.filter((record) => record.diamondName === diamond.name), - }; - childContexts.push(await BytecodeValidationPipeline.execute(child)); + for (const [chainKey, instanceDeployments] of Object.entries(chainDeployments)) { + for (const [instance, deployment] of Object.entries(instanceDeployments)) { + const child = Context.create(); + child.param = { + projectRoot: ctx.param.projectRoot, + diamondName: diamond.name, + chainKey, + instance, + diamondAddress: deployment.diamond, + virtualStorageRecords: records.filter((record) => record.diamondName === diamond.name), + }; + childContexts.push(await BytecodeValidationPipeline.execute(child)); + } } } ctx = BytecodeValidationModule.mergeDeployments( diff --git a/cli/src/resolver/dependencyRegistry.ts b/cli/src/resolver/dependencyRegistry.ts index b0fe811d..cce972ea 100644 --- a/cli/src/resolver/dependencyRegistry.ts +++ b/cli/src/resolver/dependencyRegistry.ts @@ -9,7 +9,7 @@ import type { IRPCAdapter } from "../adapters/IRPCAdapter/interface"; import { createRPCAdapter } from "../adapters/IRPCAdapter/adapter"; import type { IDiamondAdapter } from "../adapters/IDiamondAdapter/interface"; import { createDiamondAdapter } from "../adapters/IDiamondAdapter/adapter"; -import { resolveChainConfig } from "../utils/chainConfig"; +import { resolveChainConfig, type ResolvedChainConfig } from "../utils/chainConfig"; import { DependencyKey } from "./dependencyKey"; import { BytecodeValidatorAdapter } from "../adapters/IBytecodeValidatorAdapter/adapter"; import type { IBytecodeValidatorAdapter } from "../adapters/IBytecodeValidatorAdapter/interface"; @@ -20,6 +20,8 @@ export type DependencyParams = Record; type RPCDependencyParams = DependencyParams & { chainKey?: unknown; projectRoot?: string; + rpcUrlOverride?: unknown; + resolvedChain?: ResolvedChainConfig; }; /** Factory function that creates or returns a dependency instance. */ @@ -52,7 +54,8 @@ export const DependencyRegistry: { } = { [DependencyKey.Hashing]: () => HashingAdapter, [DependencyKey.RPC]: async (params) => { - const resolved = await resolveChainConfig(params as RPCDependencyParams | undefined); + const rpcParams = params as RPCDependencyParams | undefined; + const resolved = rpcParams?.resolvedChain ?? await resolveChainConfig(rpcParams); return createRPCAdapter({ rpcUrl: resolved.rpcUrl, chainId: resolved.chainId }); }, [DependencyKey.Diamond]: async (params) => diff --git a/cli/src/templates/deploy/compose-foundry.s.sol b/cli/src/templates/deploy/compose-foundry.s.sol new file mode 100644 index 00000000..81f1e5ef --- /dev/null +++ b/cli/src/templates/deploy/compose-foundry.s.sol @@ -0,0 +1,41 @@ +/* compose-plan-hash: {{PLAN_HASH}} */ +/* compose-target: {{CHAIN_KEY}} (chain id {{CHAIN_ID}}) */ + +/* Generated by `compose deploy`. Do not edit by hand: regenerate with + `compose deploy` after compose.json changes, review the script, then run + `compose deploy --broadcast` to execute this exact script. + + Foundry restricts cheatcode file writes to explicitly permitted paths, so + this script only deploys. `compose deploy` reads the run broadcast + afterwards to record the deployed addresses. +*/ + +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +/* Compose + * https://compose.diamonds + */ + +import {Script} from "forge-std/Script.sol"; +import {console} from "forge-std/console.sol"; +{{IMPORTS}} + +contract ComposeDeployScript is Script { + function setUp() public {} + + function run() public { + vm.startBroadcast(); +{{ACCOUNT_GUARD}} + + address[] memory facets = new address[]({{FACET_COUNT}}); + +{{DEPLOY_LINES}} + + /* Define diamond proxy. */ + {{DIAMOND_CONTRACT}} diamond = new {{DIAMOND_CONTRACT}}(facets); + console.log("Diamond:", address(diamond)); + + vm.stopBroadcast(); + } +} diff --git a/cli/src/templates/deploy/compose-hardhat-account-probe.ts b/cli/src/templates/deploy/compose-hardhat-account-probe.ts new file mode 100644 index 00000000..5520e43b --- /dev/null +++ b/cli/src/templates/deploy/compose-hardhat-account-probe.ts @@ -0,0 +1,11 @@ +import { network } from "hardhat"; + +const rpcUrl = process.env.COMPOSE_DEPLOY_RPC_URL; +if (!rpcUrl) throw new Error("Compose RPC URL was not provided"); +const connection = await network.create({ network: {{CHAIN_KEY}}, override: { url: rpcUrl } }); +if (connection.networkConfig.type !== "http") throw new Error("Selected Hardhat network must be HTTP"); +const actualChainId = Number(BigInt(String(await connection.provider.request({ method: "eth_chainId", params: [] })))); +if (actualChainId !== {{CHAIN_ID}}) throw new Error("Hardhat RPC chain ID does not match Compose"); +{{ACCOUNT_READ}} +console.log("COMPOSE_ACCOUNT_ADDRESSES:" + JSON.stringify(addresses)); +await connection.close(); diff --git a/cli/src/templates/deploy/compose-hardhat-ignition-module.ts b/cli/src/templates/deploy/compose-hardhat-ignition-module.ts new file mode 100644 index 00000000..60d47a01 --- /dev/null +++ b/cli/src/templates/deploy/compose-hardhat-ignition-module.ts @@ -0,0 +1,16 @@ +// compose-plan-hash: {{PLAN_HASH}} +// compose-ignition-deployment-id: {{IGNITION_DEPLOYMENT_ID}} + +import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; + +export default buildModule("{{IGNITION_MODULE_ID}}", (m) => { +{{FACET_FUTURES}} + const diamond = m.contract({{DIAMOND_CONTRACT}}, [[{{FACET_VARIABLES}}]], { + id: "Diamond", + }); + + return { + diamond, +{{FACET_RESULTS}} + }; +}); diff --git a/cli/src/templates/deploy/compose-hardhat-ignition-runner.ts b/cli/src/templates/deploy/compose-hardhat-ignition-runner.ts new file mode 100644 index 00000000..0ffe0dfc --- /dev/null +++ b/cli/src/templates/deploy/compose-hardhat-ignition-runner.ts @@ -0,0 +1,132 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { randomUUID } from "node:crypto"; +import { network } from "hardhat"; +import ComposeDeploy from "{{MODULE_IMPORT}}"; + +const composeMode = process.env.COMPOSE_DEPLOY_MODE; +const simulation = composeMode === "simulate"; +const rpcUrl = process.env.COMPOSE_DEPLOY_RPC_URL; +const expectedChainId = {{CHAIN_ID}}; +const ignitionDeploymentId: string = {{IGNITION_DEPLOYMENT_ID}}; +const expectedAccountAddress: string | null = {{ACCOUNT_ADDRESS}}; +const resultPath = {{RESULT_PATH}}; + +if (!rpcUrl) { + throw new Error("Compose did not provide the RPC URL. Run this with 'compose deploy'."); +} + +async function addressOf(contract: { + getAddress?: () => Promise; + address?: string; +}): Promise { + if (typeof contract.getAddress === "function") return contract.getAddress(); + if (typeof contract.address === "string") return contract.address; + throw new Error("Hardhat Ignition returned a contract without an address."); +} + +async function main() { + const targetConnection = await network.create({ + network: {{CHAIN_KEY}}, + override: { url: rpcUrl }, + }); + if (targetConnection.networkConfig.type !== "http") { + throw new Error( + `Hardhat network '${targetConnection.networkName}' is not an HTTP network. Configure it as an HTTP network for Compose deployments.`, + ); + } + + const chainIdHex = await targetConnection.provider.request({ method: "eth_chainId", params: [] }); + const actualChainId = Number(BigInt(String(chainIdHex))); + if (!Number.isSafeInteger(actualChainId) || actualChainId !== expectedChainId) { + throw new Error(`Compose RPC endpoint reports chain id ${actualChainId}; expected ${expectedChainId}.`); + } + +{{RESOLVE_SIGNER}} + + let deploymentConnection = targetConnection; + let forkBlockNumber: number | null = null; + let executionSender = deployerAddress; + const executionDeploymentId = simulation + ? `${ignitionDeploymentId}-simulation-${randomUUID()}` + : ignitionDeploymentId; + if (simulation) { + const configuredForkBlock = Number(process.env.COMPOSE_DEPLOY_FORK_BLOCK_NUMBER); + if (!Number.isSafeInteger(configuredForkBlock) || configuredForkBlock < 0) { + throw new Error("Compose did not provide a valid fork block for the deployment simulation."); + } + forkBlockNumber = configuredForkBlock; + deploymentConnection = await network.create({ + network: "default", + chainType: targetConnection.networkConfig.chainType ?? "generic", + override: { + chainId: actualChainId, + forking: { url: rpcUrl, blockNumber: forkBlockNumber }, + }, + }); + const forkAccounts = await deploymentConnection.provider.request({ method: "eth_accounts", params: [] }); + if (!Array.isArray(forkAccounts) || typeof forkAccounts[0] !== "string") { + throw new Error("Hardhat Ignition simulation has no local account available on the fork."); + } + executionSender = forkAccounts.find((address) => + typeof address === "string" && address.toLowerCase() === deployerAddress.toLowerCase(), + ) ?? forkAccounts[0]; + if (executionSender.toLowerCase() !== deployerAddress.toLowerCase()) { + console.log(`Using local fork account ${executionSender} for simulation; the configured deployment account remains ${deployerAddress}.`); + } + console.log(`Simulating Ignition deployment on fork block ${forkBlockNumber}...`); + } else { + console.log(`Broadcasting Ignition deployment to ${targetConnection.networkName}...`); + } + + try { + console.log("Deployer:", simulation ? executionSender : deployerAddress); + const outputs = await deploymentConnection.ignition.deploy(ComposeDeploy, { + deploymentId: executionDeploymentId, + defaultSender: executionSender, + }); + const diamondAddress = await addressOf(outputs.diamond); + const facets = { +{{FACET_ADDRESS_ENTRIES}} + }; + + if (simulation) { + console.log("Simulated Diamond:", diamondAddress); + console.log("Simulation succeeded. No transactions were broadcast."); + return; + } + + for (const [name, address] of Object.entries(facets)) { + console.log(`${name}: ${address}`); + } + + await fs.mkdir(path.dirname(resultPath), { recursive: true }); + await fs.writeFile(resultPath, JSON.stringify({ + mode: "deploy", + planHash: "{{PLAN_HASH}}", + framework: "hardhat", + chainKey: {{CHAIN_KEY}}, + chainId: actualChainId, + instance: {{INSTANCE}}, + deployer: deployerAddress, + diamond: diamondAddress, + facets, + ignitionDeploymentId, + }, null, 2)); + console.log("Ignition deployment complete:", resultPath); + } finally { + if (simulation) { + await deploymentConnection.close(); + await fs.rm(path.resolve("ignition", "deployments", executionDeploymentId), { + recursive: true, + force: true, + }); + } + await targetConnection.close(); + } +} + +main().catch((error) => { + console.error(error); + process.exitCode = 1; +}); diff --git a/cli/src/templates/deploy/foundry-deploy.sol b/cli/src/templates/deploy/foundry-deploy.sol deleted file mode 100644 index a38f5d5a..00000000 --- a/cli/src/templates/deploy/foundry-deploy.sol +++ /dev/null @@ -1,33 +0,0 @@ -// SPDX-License-Identifier: MIT -pragma solidity ^0.8.30; - -/* Compose - * https://compose.diamonds - */ - -import {Script} from "forge-std/Script.sol"; -import {console} from "forge-std/console.sol"; -import {Diamond} from "../src/Diamond.sol"; -{{IMPORTS}} - -contract DeployScript is Script { - function setUp() public {} - - function run() public returns (Diamond diamond) { - vm.startBroadcast(); - - address[] memory facets = new address[]({{FACET_COUNT}}); - - /* Base facet generation. */ -{{BASE_LINES}} - - /* Library facet generation. */ -{{LIBRARY_LINES}} - - /* Define diamond proxy. */ - diamond = new Diamond(facets); - console.log("Diamond:", address(diamond)); - - vm.stopBroadcast(); - } -} diff --git a/cli/src/templates/deploy/hardhat-ethers-deploy.ts b/cli/src/templates/deploy/hardhat-ethers-deploy.ts deleted file mode 100644 index 919d384e..00000000 --- a/cli/src/templates/deploy/hardhat-ethers-deploy.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { network } from "hardhat"; - -const { ethers, networkName } = await network.create(); - -async function deploy() { - console.log(`Deploying Diamond to ${networkName}...`); - - const facets: string[] = []; - - // Base facet generation. -{{BASE_LINES}} - - // Library facet generation. -{{LIBRARY_LINES}} - - // Define diamond proxy. - const diamond = await ethers.deployContract("Diamond", [facets]); - await diamond.waitForDeployment(); - - console.log("Diamond:", await diamond.getAddress()); -} - -deploy().catch((error) => { - console.error(error); - process.exitCode = 1; -}); diff --git a/cli/src/templates/deploy/hardhat-viem-deploy.ts b/cli/src/templates/deploy/hardhat-viem-deploy.ts deleted file mode 100644 index a15fbdeb..00000000 --- a/cli/src/templates/deploy/hardhat-viem-deploy.ts +++ /dev/null @@ -1,25 +0,0 @@ -import { network } from "hardhat"; - -const { viem, networkName } = await network.create(); - -async function deploy() { - console.log(`Deploying Diamond to ${networkName}...`); - - const facets: `0x${string}`[] = []; - - // Base facet generation. -{{BASE_LINES}} - - // Library facet generation. -{{LIBRARY_LINES}} - - // Define diamond proxy. - const diamond = await viem.deployContract("Diamond", [facets]); - - console.log("Diamond:", diamond.address); -} - -deploy().catch((error) => { - console.error(error); - process.exitCode = 1; -}); diff --git a/cli/src/templates/readme/foundry-readme.md b/cli/src/templates/readme/foundry-readme.md index 78a23c9c..213a0079 100644 --- a/cli/src/templates/readme/foundry-readme.md +++ b/cli/src/templates/readme/foundry-readme.md @@ -5,6 +5,21 @@ Scaffolded by [Compose CLI](https://compose.diamonds) - The open-source toolkit ## Prerequisites - [Foundry](https://book.getfoundry.sh/getting-started/installation) +- [Node.js](https://nodejs.org/) (v22 or later) for the Compose CLI + +## Install Dependencies + +Install the Solidity dependencies: + +```shell +forge install +``` + +Install the Compose CLI and Node tooling: + +```shell +npm install +``` ## Build @@ -18,7 +33,13 @@ forge build forge test ``` -## Deploy Locally +## Validate + +```shell +npx compose validate +``` + +## Deploy Start a local Ethereum node: @@ -26,18 +47,45 @@ Start a local Ethereum node: anvil ``` -Deploy to the local network: +Plan the deployment and generate the managed deploy script: ```shell -forge script script/Deploy.s.sol:DeployScript --rpc-url http://localhost:8545 --private-key --broadcast +npx compose deploy ``` -## Deploy +Review the script, then simulate or deploy it against the local chain: ```shell -forge script script/Deploy.s.sol:DeployScript --rpc-url --private-key --broadcast +npx compose deploy -- --dry-run -- --sender 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 +npx compose deploy -- --broadcast -- \ + --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \ + --non-interactive ``` +The key above belongs to Anvil's first default account. Use it for local testing only, never on a public network. + +Use `--account ` instead of `--sender` when a Compose account is configured. Dry-run needs only the public sender address, not its private key. + +### Sepolia + +Sepolia is preconfigured in `compose.json` and `foundry.toml`. Copy `.env.example` to `.env` and set `SEPOLIA_RPC_URL`. Import the signer into Foundry's encrypted keystore, then register its public address with Compose: + +```shell +cast wallet import +npx compose account setup deployer --foundry-account \ + --address --chain sepolia +npx compose account check deployer --chain sepolia +``` + +Plan and broadcast the deployment: + +```shell +npx compose deploy -- --chain sepolia --account deployer +npx compose deploy -- --chain sepolia --account deployer --broadcast +``` + +The Compose CLI is a dev dependency of this project, so `npx compose` uses the local version. + ## Format ```shell diff --git a/cli/src/templates/readme/hardhat-readme.md b/cli/src/templates/readme/hardhat-readme.md index 52949c44..1f8ffecd 100644 --- a/cli/src/templates/readme/hardhat-readme.md +++ b/cli/src/templates/readme/hardhat-readme.md @@ -4,7 +4,7 @@ Scaffolded by [Compose CLI](https://compose.diamonds) - The open-source toolkit ## Prerequisites -- [Node.js](https://nodejs.org/) (v20 or later) +- [Node.js](https://nodejs.org/) (v22.13 or later) ## Install Dependencies @@ -15,16 +15,22 @@ npm install ## Build ```shell -npm run build +npx hardhat build ``` ## Test ```shell -npm run test +npx hardhat test ``` -## Deploy Locally +## Validate + +```shell +npx compose validate +``` + +## Deploy Start a local Ethereum node: @@ -32,18 +38,43 @@ Start a local Ethereum node: npx hardhat node ``` -Deploy to the local network (in a separate terminal): +Plan the deployment and generate the managed Ignition module (in a separate terminal): ```shell -npx hardhat run scripts/deploy.ts --network localhost +npx compose deploy ``` -## Deploy +Review `ignition/modules/ComposeDeploy.ts`, then simulate or deploy it against the local chain: + +```shell +npx compose deploy -- --dry-run +npx compose deploy -- --broadcast +``` + +### Sepolia + +Sepolia is preconfigured in `compose.json` and `hardhat.config.ts`. Copy `.env.example` to `.env` and set `SEPOLIA_RPC_URL`. Store the signer key using the variable already configured for the network: + +```shell +npx hardhat keystore set SEPOLIA_PRIVATE_KEY +``` + +Register the matching public address as a Compose account, then verify it: ```shell -npx hardhat run scripts/deploy.ts --network +npx compose account setup deployer-sep --address --chain sepolia +npx compose account check deployer-sep --chain sepolia ``` +Plan the deployment and review `ignition/modules/ComposeDeploy.ts`, then broadcast: + +```shell +npx compose deploy --chain sepolia --account deployer-sep +npx compose deploy --chain sepolia --account deployer-sep --broadcast +``` + +The Compose CLI is a dev dependency of this project, so `npx compose` uses the local version. + ## Learn More - [Hardhat Documentation](https://hardhat.org/docs) diff --git a/cli/src/utils/args.ts b/cli/src/utils/args.ts new file mode 100644 index 00000000..efd58351 --- /dev/null +++ b/cli/src/utils/args.ts @@ -0,0 +1,139 @@ +import { redactSensitiveArgument } from "./redaction"; + +/** + * Foundry passthrough options that select, provide, or override the signing + * account. Shared with the Foundry adapter, which must not predict a signer + * when the passthrough requests more than one. + */ +export const FOUNDRY_SIGNING_PASSTHROUGH_OPTIONS: readonly string[] = [ + "--account", + "--accounts", + "-i", + "--interactive", + "--interactives", + "--private-key", + "--private-keys", + "--mnemonic", + "--mnemonics", + "--keystore", + "--keystores", + "--password", + "--sender", + "--ledger", + "--trezor", + "--aws", + "--gcp", + "--turnkey", + "--unlocked", +]; + +/** + * Normalizes parsed `--` passthrough arguments. + * + * Commander exposes the tail after `--` as `unknown`; only string entries can + * be forwarded to a framework command. + * + * @param value - The raw passthrough value from the parsed CLI flags. + * @returns The string arguments in their original order. + */ +export function toPassthroughArgs(value: unknown): string[] { + return Array.isArray(value) + ? value.filter((item): item is string => typeof item === "string") + : []; +} + +/** + * Prevents framework passthrough flags from silently changing the planned + * deployment target, reviewed artifact sources, deploy mode, or signer. + * + * @param passthrough - Raw arguments supplied after `--`. + * @param framework - Framework running the managed deployment. + * @param accountSelected - Whether Compose selected the signer. + * @param mode - The Compose deploy mode. + * @throws {Error} If a passthrough argument conflicts with the deploy plan. + */ +export function assertSafeDeploymentPassthrough( + passthrough: unknown, + framework: "foundry" | "hardhat", + accountSelected = false, + mode: "prepare" | "simulate" | "broadcast" = "prepare", +): void { + const networkOptions = framework === "foundry" + ? ["-r", "--rpc-url", "--fork-url", "--fork-block-number", "--chain", "--chain-id"] + : ["--network", "--rpc-url"]; + const buildOptions = framework === "foundry" + ? ["--root", "--config-path", "--contracts", "--lib-paths", "--remappings", "--remappings-env", "--hardhat", "--hh"] + : ["--config"]; + const accountOptions = framework === "foundry" + ? [...FOUNDRY_SIGNING_PASSTHROUGH_OPTIONS] + : ["--account"]; + const args = toPassthroughArgs(passthrough); + const conflictingBroadcastOption = args.find((argument) => + argument === "--broadcast" || argument.startsWith("--broadcast=")); + if (conflictingBroadcastOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(conflictingBroadcastOption)}' cannot change Compose deploy mode. ` + + "Use compose deploy --broadcast to send transactions.", + ); + } + + const conflictingResumeOption = args.find((argument) => + argument === "--resume" || argument.startsWith("--resume-")); + if (conflictingResumeOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(conflictingResumeOption)}' cannot resume a past deployment. ` + + "Run compose deploy --broadcast to execute the current reviewed artifact.", + ); + } + + if (mode === "simulate" && framework === "foundry") { + if (args.some((argument) => argument === "--skip-simulation")) { + throw new Error("Framework passthrough '--skip-simulation' disables the requested dry-run."); + } + const signingOption = args.find((argument) => + accountOptions + .filter((option) => option !== "--sender") + .some((option) => argument === option || argument.startsWith(`${option}=`))); + if (signingOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(signingOption)}' is not used for a dry-run. ` + + "Select a Compose account with --account or use a public --sender address after '--'.", + ); + } + if (!accountSelected && !args.some((argument) => + argument === "--sender" || argument.startsWith("--sender="))) { + throw new Error( + "Foundry dry-run needs the intended public sender address. Use --account or pass --sender
after '--'.", + ); + } + } + const conflictingBuildOption = args.find((argument) => + buildOptions.some((option) => argument === option || argument.startsWith(`${option}=`))); + if (conflictingBuildOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(conflictingBuildOption)}' cannot change the reviewed deployment artifact's project or sources. ` + + "Configure the project before running compose deploy.", + ); + } + + const conflictingNetworkOption = args.find((argument) => + networkOptions.some((option) => argument === option || argument.startsWith(`${option}=`))); + + if (conflictingNetworkOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(conflictingNetworkOption)}' cannot change the planned deployment target. ` + + "Use compose deploy --chain and --rpc-url before '--'.", + ); + } + + if (accountSelected) { + const conflictingAccountOption = args.find((argument) => + accountOptions.some((option) => argument === option || argument.startsWith(`${option}=`))); + if (conflictingAccountOption) { + throw new Error( + `Framework passthrough '${redactSensitiveArgument(conflictingAccountOption)}' conflicts with the selected Compose account. ` + + "Use --account before '--' to select the signer.", + ); + } + } +} diff --git a/cli/src/utils/chainConfig.ts b/cli/src/utils/chainConfig.ts index cd7bbb9c..59b2e457 100644 --- a/cli/src/utils/chainConfig.ts +++ b/cli/src/utils/chainConfig.ts @@ -9,6 +9,8 @@ export type ResolvedChainConfig = { rpcUrl: string; /** Expected EVM chain ID for the selected endpoint. */ chainId: number; + /** Optional account alias used by deployments on this chain. */ + account?: string; }; export type ResolveChainOptions = { @@ -16,6 +18,8 @@ export type ResolveChainOptions = { chainKey?: unknown; /** Directory from which to search upward for compose.json. */ projectRoot?: string; + /** Optional per-command RPC URL override; chain identity still comes from compose.json. */ + rpcUrlOverride?: unknown; }; const ENVIRONMENT_VARIABLE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g; @@ -84,11 +88,38 @@ export async function resolveChainConfig(options: ResolveChainOptions = {}): Pro if (!Number.isSafeInteger(entry.chainId) || (entry.chainId as number) <= 0) { throw new RPCAdapterError("RPC_INVALID_CONFIGURATION", `Chain '${chainKey}' has an invalid chainId`, { operation: "resolveChain" }); } + if (entry.account !== undefined && (typeof entry.account !== "string" || entry.account.trim() === "")) { + throw new RPCAdapterError("RPC_INVALID_CONFIGURATION", `Chain '${chainKey}' has an invalid account alias`, { operation: "resolveChain" }); + } + + if (options.rpcUrlOverride !== undefined && typeof options.rpcUrlOverride !== "string") { + throw new RPCAdapterError( + "RPC_INVALID_CONFIGURATION", + "rpcUrlOverride must be a string", + { operation: "resolveChain" }, + ); + } + + const rpcUrlValue = options.rpcUrlOverride === undefined ? entry.rpc : options.rpcUrlOverride; + if (typeof rpcUrlValue !== "string" || rpcUrlValue.trim() === "") { + throw new RPCAdapterError( + "RPC_INVALID_CONFIGURATION", + options.rpcUrlOverride === undefined + ? `Chain '${chainKey}' has an invalid rpc value` + : "RPC URL override must not be empty", + { operation: "resolveChain" }, + ); + } - const rpcUrl = interpolateRPCUrl(entry.rpc); + const rpcUrl = interpolateRPCUrl(rpcUrlValue); if (!rpcUrl.trim()) { throw new RPCAdapterError("RPC_INVALID_CONFIGURATION", `Chain '${chainKey}' resolved to an empty RPC URL`, { operation: "resolveChain" }); } - return { chainKey, rpcUrl, chainId: entry.chainId as number }; + return { + chainKey, + rpcUrl, + chainId: entry.chainId as number, + ...(typeof entry.account === "string" ? { account: entry.account } : {}), + }; } diff --git a/cli/src/utils/composeProjectFile.ts b/cli/src/utils/composeProjectFile.ts index 2a147579..4c6e8455 100644 --- a/cli/src/utils/composeProjectFile.ts +++ b/cli/src/utils/composeProjectFile.ts @@ -7,6 +7,10 @@ export type ComposeProjectFile = { root: string; }; +export type LoadedComposeProjectFile = ComposeProjectFile & { + composeJson: unknown; +}; + /** Finds the nearest compose.json and returns its path and containing project root. */ export async function locateComposeProjectFile( startDirectory: string, @@ -21,3 +25,22 @@ export async function locateComposeProjectFile( export async function readComposeProjectFile(filePath: string): Promise { return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown; } + +/** + * Finds, reads, and parses the nearest compose.json. + * + * Returns null when no file exists so callers can keep command-specific + * guidance. Parse errors propagate unchanged; schema validation stays with the + * caller. + */ +export async function loadComposeProjectFile( + startDirectory: string, +): Promise { + const composeFile = await locateComposeProjectFile(startDirectory); + if (!composeFile) return null; + + return { + ...composeFile, + composeJson: await readComposeProjectFile(composeFile.path), + }; +} diff --git a/cli/src/utils/composeRuntime.ts b/cli/src/utils/composeRuntime.ts new file mode 100644 index 00000000..0dc35be3 --- /dev/null +++ b/cli/src/utils/composeRuntime.ts @@ -0,0 +1,64 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { ensureGitignoreEntries } from "./gitignore"; + +/** Project-relative directory that holds every Compose-owned runtime file. */ +export const COMPOSE_DIR = ".compose"; + +/** Frameworks that can own a Compose runtime directory. */ +export type ComposeFramework = "foundry" | "hardhat"; + +/** + * Resolves the Compose runtime directory for a framework. + * + * @param projectRoot - Absolute project root. + * @param framework - Framework whose transient files live in the directory. + * @returns Absolute path of `/.compose/`. + */ +export function composeRuntimeDir( + projectRoot: string, + framework: ComposeFramework, +): string { + return path.join(projectRoot, COMPOSE_DIR, framework); +} + +/** + * Ensures the project `.gitignore` ignores the Compose runtime directory. + * + * Uses a bare `.compose/` rule so nested workspaces are covered by the same + * entry that hides the project root's runtime files. + * + * @param projectRoot - Absolute project root. + * @throws {Error} If an existing `.gitignore` cannot be read or written. + */ +export async function ensureComposeDirIgnored(projectRoot: string): Promise { + const gitignorePath = path.join(projectRoot, ".gitignore"); + let gitignore = ""; + try { + gitignore = await fs.readFile(gitignorePath, "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } + + const updated = ensureGitignoreEntries(gitignore, [`${COMPOSE_DIR}/`]); + if (updated !== gitignore) { + await fs.writeFile(gitignorePath, updated, "utf8"); + } +} + +/** + * Ensures the runtime directory exists and is ignored by git. + * + * @param projectRoot - Absolute project root. + * @param framework - Framework whose transient files live in the directory. + * @returns Absolute path of the created runtime directory. + */ +export async function ensureComposeRuntimeDir( + projectRoot: string, + framework: ComposeFramework, +): Promise { + await ensureComposeDirIgnored(projectRoot); + const runtimeDir = composeRuntimeDir(projectRoot, framework); + await fs.mkdir(runtimeDir, { recursive: true }); + return runtimeDir; +} diff --git a/cli/src/utils/env.ts b/cli/src/utils/env.ts new file mode 100644 index 00000000..bf6472be --- /dev/null +++ b/cli/src/utils/env.ts @@ -0,0 +1,17 @@ +import dotenv from "dotenv"; +import path from "node:path"; +import { locateComposeProjectFile } from "./composeProjectFile"; + +/** + * Loads the `.env` file for the nearest Compose project, or the starting + * directory when no Compose project is present. Parent and nested `.env` files + * are deliberately ignored so another project cannot affect this command. + * Existing process environment values keep dotenv's default precedence. + */ +export async function loadProjectEnv(startDirectory: string = process.cwd()): Promise { + const resolvedStartDirectory = path.resolve(startDirectory); + const composeProject = await locateComposeProjectFile(resolvedStartDirectory); + const projectRoot = composeProject?.root ?? resolvedStartDirectory; + + dotenv.config({ path: path.join(projectRoot, ".env") }); +} diff --git a/cli/src/utils/errors.ts b/cli/src/utils/errors.ts index 1dc7c1a7..44e6def0 100644 --- a/cli/src/utils/errors.ts +++ b/cli/src/utils/errors.ts @@ -1,3 +1,27 @@ +import type { ComposeError } from "../context/types"; + +/** + * Normalizes an unknown thrown value into a ComposeError, keeping any error + * code exposed by the original value. + * @param error + * @param fallbackCode Code used when the error does not expose one + * @param fallbackMessage Message used when the error is not an Error instance + * @returns Normalized compose error + */ +function toComposeError( + error: unknown, + fallbackCode: string, + fallbackMessage = "Operation failed.", +): ComposeError { + return { + code: typeof error === "object" && error !== null && "code" in error + ? String(error.code) + : fallbackCode, + message: error instanceof Error ? error.message : fallbackMessage, + nativeError: error, + }; +} + /** * Error normalizer * @param error @@ -25,4 +49,4 @@ function exitWithError(error: unknown): void { process.exitCode = 1; } -export { normalizeError, exitWithError }; \ No newline at end of file +export { normalizeError, exitWithError, toComposeError }; \ No newline at end of file diff --git a/cli/src/utils/exec.ts b/cli/src/utils/exec.ts index 1855f3d7..e3de23f9 100644 --- a/cli/src/utils/exec.ts +++ b/cli/src/utils/exec.ts @@ -1,6 +1,7 @@ import { spawn } from "node:child_process"; import fs from "node:fs/promises"; import path from "node:path"; +import { formatCommandArgs } from "./redaction"; /** * Resolves a command string to its executable path. @@ -14,6 +15,25 @@ function resolveCommand(command: string): string { return command; } +/** + * Replaces a raw spawn error, which may retain the full argv in `spawnargs`, + * with an error that only exposes the executable and error code. + * + * @param command - The command that failed to start. + * @param error - The original spawn error. + * @returns A sanitized error preserving the original error code. + */ +function commandStartError(command: string, error: unknown): Error { + const code = typeof error === "object" && error && "code" in error + ? String((error as { code?: unknown }).code) + : undefined; + const failure = new Error( + `Command failed to start: ${command}${code ? ` (${code})` : ""}`, + ) as NodeJS.ErrnoException; + if (code) failure.code = code; + return failure; +} + /** * Spawns a child process with the given command and arguments. * Returns a Promise that resolves when the process exits with code 0, @@ -25,22 +45,64 @@ function resolveCommand(command: string): string { * @param options - Optional spawn options (e.g., working directory). * @returns A Promise that resolves on success or rejects on failure. */ -export function runCommand(command: string, args: string[], options?: { cwd?: string }): Promise { +export function runCommand( + command: string, + args: string[], + options?: { cwd?: string; env?: NodeJS.ProcessEnv }, +): Promise { return new Promise((resolve, reject) => { const resolvedCommand = resolveCommand(command); const useShell = process.platform === "win32" && (command === "npm" || command === "npx"); + const spawnOptions = { ...options }; + if (options?.env) { + spawnOptions.env = { ...process.env, ...options.env }; + } const child = spawn(resolvedCommand, args, { stdio: "inherit", shell: useShell, - ...options, + ...spawnOptions, }); - child.on("error", reject); + child.on("error", (error) => reject(commandStartError(command, error))); child.on("exit", (code) => { if (code === 0) { resolve(); return; } - reject(new Error(`Command failed: ${command} ${args.join(" ")} (exit ${code})`)); + reject(new Error(`Command failed: ${command} ${formatCommandArgs(args)} (exit ${code})`)); + }); + }); +} + +/** Runs a command while optionally forwarding and also returning its stdout. */ +export function runCommandCaptureStdout( + command: string, + args: string[], + options?: { cwd?: string; env?: NodeJS.ProcessEnv; forwardStdout?: boolean }, +): Promise { + return new Promise((resolve, reject) => { + const resolvedCommand = resolveCommand(command); + const useShell = process.platform === "win32" && (command === "npm" || command === "npx"); + const { forwardStdout = true, ...spawnOptions } = options ?? {}; + if (spawnOptions.env) spawnOptions.env = { ...process.env, ...spawnOptions.env }; + const child = spawn(resolvedCommand, args, { + stdio: ["inherit", "pipe", "inherit"], + shell: useShell, + ...spawnOptions, + }); + + let stdout = ""; + child.stdout?.on("data", (chunk: Buffer) => { + const text = chunk.toString(); + stdout += text; + if (forwardStdout) process.stdout.write(text); + }); + child.on("error", (error) => reject(commandStartError(command, error))); + child.on("exit", (code) => { + if (code === 0) { + resolve(stdout); + return; + } + reject(new Error(`Command failed: ${command} ${formatCommandArgs(args)} (exit ${code})`)); }); }); } @@ -70,7 +132,7 @@ export function runCommandCapture( stderr += chunk.toString(); }); - child.on("error", reject); + child.on("error", (error) => reject(commandStartError(command, error))); child.on("exit", (code) => { if (code === 0) { resolve(); @@ -79,7 +141,7 @@ export function runCommandCapture( if (stderr) { process.stderr.write(stderr); } - reject(new Error(`Compilation failed: ${command} ${args.join(" ")} (exit ${code})`)); + reject(new Error(`Compilation failed: ${command} ${formatCommandArgs(args)} (exit ${code})`)); }); }); } diff --git a/cli/src/utils/files.ts b/cli/src/utils/files.ts index 2312ae60..8b7fb854 100644 --- a/cli/src/utils/files.ts +++ b/cli/src/utils/files.ts @@ -102,6 +102,24 @@ export function toRelativeImport(relativePath: string): string { return posixPath.startsWith(".") ? posixPath : `./${posixPath}`; } +/** + * Renders a path relative to the project root for CLI output. + * + * Falls back to the input path when the target lives outside the project + * (or on a different Windows drive), so callers can print the result as-is. + * + * @param projectRoot - Absolute project root. + * @param targetPath - The path to display. + * @returns A project-relative POSIX-style path, or the input when it cannot be made relative. + */ +export function toProjectRelativePath(projectRoot: string, targetPath: string): string { + const relative = path.relative(projectRoot, targetPath); + if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) { + return targetPath; + } + return toPosixPath(relative); +} + /** * Checks whether a directory is empty, optionally ignoring specific entries. * diff --git a/cli/src/utils/gitignore.ts b/cli/src/utils/gitignore.ts new file mode 100644 index 00000000..831533ff --- /dev/null +++ b/cli/src/utils/gitignore.ts @@ -0,0 +1,25 @@ +/** + * Ensures a `.gitignore` entry exists without touching existing content. + * + * @param content - Current `.gitignore` content (may be empty). + * @param entry - Entry to add when it is not already listed. + * @returns The content unchanged, or with the entry appended on its own line. + */ +export function ensureGitignoreEntry(content: string, entry: string): string { + const lines = content.split(/\r?\n/).map((line) => line.trim()); + if (lines.includes(entry)) return content; + + const separator = content === "" || content.endsWith("\n") ? "" : "\n"; + return `${content}${separator}${entry}\n`; +} + +/** + * Ensures several `.gitignore` entries exist, preserving their given order. + * + * @param content - Current `.gitignore` content (may be empty). + * @param entries - Entries to add when they are not already listed. + * @returns The content unchanged, or with the missing entries appended. + */ +export function ensureGitignoreEntries(content: string, entries: string[]): string { + return entries.reduce((current, entry) => ensureGitignoreEntry(current, entry), content); +} diff --git a/cli/src/utils/inquirer.ts b/cli/src/utils/inquirer.ts index ed9e5f95..bba7329e 100644 --- a/cli/src/utils/inquirer.ts +++ b/cli/src/utils/inquirer.ts @@ -29,6 +29,16 @@ export async function loadPrompts(): Promise { return { input, select, checkbox, confirm } as unknown as PromptApi; } +/** + * Returns true when the CLI can safely prompt the user. + * + * Both stdin and stdout must be TTYs; piped or redirected runs must never + * block waiting for input. + */ +export function isInteractive(): boolean { + return Boolean(process.stdin.isTTY && process.stdout.isTTY); +} + /** Custom theme for checkbox prompts with simplified icons, no help tip, and "None" when empty. */ export const checkboxTheme = { prefix: "", diff --git a/cli/src/utils/metadata.ts b/cli/src/utils/metadata.ts index 9598333a..de2f19a0 100644 --- a/cli/src/utils/metadata.ts +++ b/cli/src/utils/metadata.ts @@ -12,6 +12,12 @@ export const COMPOSE_DOCS_URL = "https://compose.diamonds/"; export const VERSION = readVersion(); export const LOCK_FILE_NAME = "compose.lock"; +/** npm package that provides the `compose` binary. */ +export const CLI_PACKAGE_NAME = "@perfect-abstractions/compose-cli"; + +/** Version range written into generated projects so they run the CLI locally. */ +export const CLI_DEV_DEPENDENCY_VERSION = `^${VERSION}`; + export const COMPOSE_HEADER = ` _____ ____ __ __ _____ ____ _____ ______ _____ _ _____ / ____/ __ \\| \\/ | __ \\ / __ \\ / ____| ____| / ____| | |_ _| diff --git a/cli/src/utils/nodeVersion.ts b/cli/src/utils/nodeVersion.ts new file mode 100644 index 00000000..09acf3dd --- /dev/null +++ b/cli/src/utils/nodeVersion.ts @@ -0,0 +1,56 @@ +/** Node.js release required by Hardhat 3 project initialization. */ +export const HARDHAT_MINIMUM_NODE_VERSION = "22.13.0"; + +type ParsedVersion = { + major: number; + minor: number; + patch: number; +}; + +/** Parses the leading `major.minor.patch` portion of a Node.js version. */ +function parseVersion(version: string): ParsedVersion | null { + const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)/); + if (!match) return null; + + return { + major: Number(match[1]), + minor: Number(match[2]), + patch: Number(match[3]), + }; +} + +/** + * Checks whether a Node.js version is at least the given minimum version. + * + * @param version - Version to check, such as `process.versions.node`. + * @param minimum - Minimum version in `major.minor.patch` form. + * @returns True when the version meets or exceeds the minimum. + */ +export function isNodeVersionAtLeast(version: string, minimum: string): boolean { + const current = parseVersion(version); + const required = parseVersion(minimum); + if (!current || !required) return false; + + if (current.major !== required.major) return current.major > required.major; + if (current.minor !== required.minor) return current.minor > required.minor; + return current.patch >= required.patch; +} + +/** + * Throws when the running Node.js version cannot initialize a Hardhat 3 project. + * + * The CLI requires Node.js 22+, but Hardhat 3's official initializer requires + * Node.js 22.13+. The check runs before scaffolding so users get an actionable + * error instead of a failure from Hardhat's template command. + * + * @param version - Node.js version to check, defaulting to the current runtime. + * @throws {Error} If the version is older than Hardhat's minimum requirement. + */ +export function assertHardhatNodeVersion(version: string = process.versions.node): void { + if (!isNodeVersionAtLeast(version, HARDHAT_MINIMUM_NODE_VERSION)) { + throw new Error( + `Hardhat 3 requires Node.js ${HARDHAT_MINIMUM_NODE_VERSION} or newer; current version is ${version}. ` + + "Upgrade Node.js before scaffolding a Hardhat project.", + ); + } +} diff --git a/cli/src/utils/packageFacetSources.ts b/cli/src/utils/packageFacetSources.ts index 74468ad5..986a27a5 100644 --- a/cli/src/utils/packageFacetSources.ts +++ b/cli/src/utils/packageFacetSources.ts @@ -6,40 +6,92 @@ export type PackageFacetSearchOptions = { ignoreReadErrors?: boolean; /** Stop scanning as soon as the first matching source is found. */ stopAfterFirstMatch?: boolean; + /** Framework whose installed package copy takes precedence when both exist. */ + framework?: string; }; -/** Finds matching Solidity source files in the project's Node and Foundry package roots. */ -export async function findPackageFacetSourceMatches( +/** + * Returns the package roots to search, most authoritative first. + * + * Foundry projects compile package facets from `lib/Compose`, while Hardhat + * projects compile them from `node_modules`. When both copies exist (a Foundry + * project also gets a `node_modules` copy through the Compose CLI's own + * dependency tree), the framework's root must win to avoid false ambiguity. + * + * @param projectRoot - Absolute path of the Compose project. + * @param packageName - Package that provides the facet. + * @param framework - Project framework ("foundry" or "hardhat"), when known. + * @returns Search roots ordered by precedence. + */ +function packageSearchRoots( projectRoot: string, packageName: string, + framework?: string, +): string[] { + const nodeModulesRoot = path.join(projectRoot, "node_modules", packageName); + const foundryRoot = path.join(projectRoot, "lib", "Compose", "src"); + + return framework === "foundry" + ? [foundryRoot, nodeModulesRoot] + : [nodeModulesRoot, foundryRoot]; +} + +/** + * Finds matching Solidity sources inside one package root. + * + * @param root - Package root to scan. + * @param facetName - Facet contract file name without the extension. + * @param options - Search behavior options. + * @returns Matching absolute paths, possibly empty. + */ +async function findMatchesInRoot( + root: string, facetName: string, - options: PackageFacetSearchOptions = {}, + options: PackageFacetSearchOptions, ): Promise { - const candidates = [ - path.join(projectRoot, "node_modules", packageName), - path.join(projectRoot, "lib", "Compose", "src"), - ]; - const matches: string[] = []; - - for (const candidate of candidates) { - try { - const entries = await fs.readdir(candidate, { recursive: true, withFileTypes: true }); - for (const entry of entries) { - if (entry.isFile() && entry.name === `${facetName}.sol`) { - matches.push(path.join(entry.parentPath ?? entry.path, entry.name)); - if (options.stopAfterFirstMatch) return matches; - } - } - } catch (error) { - if ( - options.ignoreReadErrors || - (error as NodeJS.ErrnoException).code === "ENOENT" - ) { - continue; + try { + const entries = await fs.readdir(root, { recursive: true, withFileTypes: true }); + const matches: string[] = []; + + for (const entry of entries) { + if (entry.isFile() && entry.name === `${facetName}.sol`) { + matches.push(path.join(entry.parentPath ?? entry.path, entry.name)); + if (options.stopAfterFirstMatch) return matches; } - throw error; } + + return matches; + } catch (error) { + if ( + options.ignoreReadErrors || + (error as NodeJS.ErrnoException).code === "ENOENT" + ) { + return []; + } + throw error; + } +} + +/** + * Finds matching Solidity source files in the project's Node and Foundry + * package roots, preferring the framework's own package installation. + * + * @param projectRoot - Absolute path of the Compose project. + * @param packageName - Package that provides the facet. + * @param facetName - Facet contract file name without the extension. + * @param options - Search behavior options. + * @returns Matches from the first root that contains the facet. + */ +export async function findPackageFacetSourceMatches( + projectRoot: string, + packageName: string, + facetName: string, + options: PackageFacetSearchOptions = {}, +): Promise { + for (const root of packageSearchRoots(projectRoot, packageName, options.framework)) { + const matches = await findMatchesInRoot(root, facetName, options); + if (matches.length > 0) return matches; } - return matches; + return []; } diff --git a/cli/src/utils/redaction.ts b/cli/src/utils/redaction.ts new file mode 100644 index 00000000..2dc44c75 --- /dev/null +++ b/cli/src/utils/redaction.ts @@ -0,0 +1,93 @@ +const REDACTED = "[REDACTED]"; + +const SENSITIVE_FLAG_PATTERN = new RegExp( + [ + "(?:^|[-_])(?:api|access|private|secret|signing)?keys?(?:$|[-_])", + "mnemonic", + "pass(?:word|phrase|wd)", + "pwd", + "secret", + "token", + "credential", + "auth", + "jwt", + ].join("|"), + "i", +); + +const SENSITIVE_VALUE_FLAGS = new Set([ + "--endpoint", + "--eth-rpc-url", + "--fork-url", + "--keystore", + "--keystores", + "--rpc-url", + "--url", +]); + +function isSensitiveFlag(flag: string): boolean { + if (SENSITIVE_VALUE_FLAGS.has(flag.toLowerCase())) return true; + const normalized = flag + .replace(/^--?/, "") + .replace(/([a-z0-9])([A-Z])/g, "$1-$2") + .toLowerCase(); + return SENSITIVE_FLAG_PATTERN.test(normalized); +} + +/** + * Redacts values attached to sensitive command-line flags. + * + * Handles both `--private-key secret` and `--private-key=secret`, and keeps + * redacting consecutive values for flags that accept multiple secrets. + * + * @param args - Command arguments to redact. + * @returns A copy of the arguments with secret values replaced. + */ +export function redactCommandArgs(args: readonly string[]): string[] { + const redacted: string[] = []; + let redactingValues = false; + + for (const argument of args) { + const isOption = argument.startsWith("-") && argument !== "-"; + if (redactingValues && isOption) redactingValues = false; + + if (redactingValues) { + redacted.push(REDACTED); + continue; + } + + const equalsIndex = isOption ? argument.indexOf("=") : -1; + if (equalsIndex === -1) { + redacted.push(argument); + if (isOption && isSensitiveFlag(argument)) redactingValues = true; + continue; + } + + const flag = argument.slice(0, equalsIndex); + redacted.push( + isSensitiveFlag(flag) ? `${flag}=${REDACTED}` : argument, + ); + } + + return redacted; +} + +/** + * Formats command arguments for display without exposing sensitive values. + * + * @param args - Command arguments to format. + * @returns A space-separated, redacted argument string. + */ +export function formatCommandArgs(args: readonly string[]): string { + return redactCommandArgs(args).join(" "); +} + +/** + * Redacts a single argument if it attaches a value to a sensitive flag. + * + * @param argument - Argument to redact. + * @returns The original argument or its redacted form. + */ +export function redactSensitiveArgument(argument: string): string { + return redactCommandArgs([argument])[0] ?? argument; +} diff --git a/cli/src/utils/solidityAst.ts b/cli/src/utils/solidityAst.ts index c965e8ea..8d523c67 100644 --- a/cli/src/utils/solidityAst.ts +++ b/cli/src/utils/solidityAst.ts @@ -3,7 +3,7 @@ import path from "node:path"; import { SolidityAstSource, SoliditySourceUnitAst, -} from "../adapters/IFrameworkAdapter/interface"; +} from "../adapters/IFrameworkAdapter/types"; /** Recursively lists JSON files below an adapter output directory. */ export async function listJsonFiles(root: string): Promise { diff --git a/cli/src/utils/solidityIdentifiers.ts b/cli/src/utils/solidityIdentifiers.ts new file mode 100644 index 00000000..abbe242a --- /dev/null +++ b/cli/src/utils/solidityIdentifiers.ts @@ -0,0 +1,73 @@ +/** + * Solidity identifiers are restricted to ASCII letters, digits, underscores, + * and (per the Solidity grammar) dollar signs, and cannot start with a digit. + * Generated artifacts only accept the conservative subset used by this CLI. + */ +const SOLIDITY_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/; + +/** + * Returns whether a string contains characters that can terminate or escape a + * Solidity string literal, including quotes, backslashes, control characters, + * and Unicode line separators. + */ +function hasUnsafeImportCharacter(value: string): boolean { + if (value.includes('"') || value.includes("\\")) return true; + for (const character of value) { + const codePoint = character.codePointAt(0) ?? 0; + if ( + codePoint <= 0x1f + || (codePoint >= 0x7f && codePoint <= 0x9f) + || codePoint === 0x2028 + || codePoint === 0x2029 + ) { + return true; + } + } + return false; +} + +/** + * Checks whether a value can be inserted into generated code as a Solidity + * identifier or type name. + * + * @param value - The candidate identifier. + * @returns `true` when the value matches the accepted identifier grammar. + */ +export function isSolidityIdentifier(value: string): boolean { + return SOLIDITY_IDENTIFIER.test(value); +} + +/** + * Rejects contract names that cannot be safely embedded in generated Solidity + * or TypeScript artifacts. + * + * @param value - The contract name from project configuration or resolution. + * @param context - Human-readable location of the value, used in the error. + * @throws {Error} If the value is not a Solidity identifier. + */ +export function assertSolidityContractName(value: string, context: string): void { + if (!isSolidityIdentifier(value)) { + throw new Error( + `Invalid Solidity contract name for ${context}: ${JSON.stringify(value)}. ` + + "Use only ASCII letters, digits, and underscores, starting with a letter or underscore.", + ); + } +} + +/** + * Rejects import specifiers that cannot be safely embedded in a generated + * Solidity or TypeScript string literal. + * + * @param value - The import specifier resolved from a source path. + * @param context - Human-readable location of the value, used in the error. + * @throws {Error} If the value is empty or contains quotes, backslashes, or + * control characters. + */ +export function assertSafeSolidityImportSpec(value: string, context: string): void { + if (!value || hasUnsafeImportCharacter(value)) { + throw new Error( + `Invalid Solidity import path for ${context}: ${JSON.stringify(value)}. ` + + "Quotes, backslashes, and control characters are not allowed.", + ); + } +} diff --git a/cli/test/adapters/IFrameworkAdapter/canonicalAst.ts b/cli/test/adapters/IFrameworkAdapter/canonicalAst.ts index babafc26..b470780b 100644 --- a/cli/test/adapters/IFrameworkAdapter/canonicalAst.ts +++ b/cli/test/adapters/IFrameworkAdapter/canonicalAst.ts @@ -1,4 +1,4 @@ -import { SoliditySourceUnitAst } from "../../../src/adapters/IFrameworkAdapter/interface"; +import { SoliditySourceUnitAst } from "../../../src/adapters/IFrameworkAdapter/types"; /** Sorts AST object keys recursively so expected fixtures are stable and reviewable. */ export function canonicalizeAst(ast: SoliditySourceUnitAst): unknown { diff --git a/cli/test/adapters/IFrameworkAdapter/deployMethods.test.ts b/cli/test/adapters/IFrameworkAdapter/deployMethods.test.ts new file mode 100644 index 00000000..5f3fe707 --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/deployMethods.test.ts @@ -0,0 +1,344 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { foundryAdapter } from "../../../src/adapters/IFrameworkAdapter/foundryAdapter/adapter"; +import { hardhatAdapter } from "../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-deploy-adapter-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +async function writeJson(relativePath: string, value: unknown): Promise { + const filePath = path.join(projectRoot, relativePath); + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, JSON.stringify(value), "utf8"); +} + +describe("Foundry adapter deploy methods", () => { + it("resolves the managed script path and deploy command", () => { + const scriptPath = path.join(projectRoot, "script", "ComposeDeploy.s.sol"); + expect(foundryAdapter.getManagedDeployScriptPath(projectRoot)).toBe(scriptPath); + expect(foundryAdapter.getManagedDeployResultPath(projectRoot)).toBeNull(); + + expect( + foundryAdapter.createDeployCommand({ + projectRoot, + scriptPath, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + mode: "broadcast", + passthrough: ["--private-key", "0xabc"], + }), + ).toEqual({ + command: "forge", + args: [ + "script", + "script/ComposeDeploy.s.sol:ComposeDeployScript", + "--rpc-url", + "http://127.0.0.1:8545", + "--broadcast", + "--private-key", + "0xabc", + ], + }); + }); + + it("maps a Compose account to a Foundry keystore account and sender", () => { + const scriptPath = path.join(projectRoot, "script", "ComposeDeploy.s.sol"); + expect(foundryAdapter.createDeployCommand({ + projectRoot, + scriptPath, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + mode: "broadcast", + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + foundryAccount: "production-deployer", + }, + passthrough: [], + })).toEqual({ + command: "forge", + args: [ + "script", + "script/ComposeDeploy.s.sol:ComposeDeployScript", + "--rpc-url", + "http://127.0.0.1:8545", + "--account", + "production-deployer", + "--sender", + "0x00000000000000000000000000000000000000a1", + "--broadcast", + ], + }); + }); + + it("simulates at a pinned fork block without loading a signing account or broadcasting", () => { + const scriptPath = path.join(projectRoot, "script", "ComposeDeploy.s.sol"); + expect(foundryAdapter.createDeployCommand({ + projectRoot, + scriptPath, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + mode: "simulate", + forkBlockNumber: 123n, + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + foundryAccount: "production-deployer", + }, + passthrough: [], + })).toEqual({ + command: "forge", + args: [ + "script", + "script/ComposeDeploy.s.sol:ComposeDeployScript", + "--rpc-url", + "http://127.0.0.1:8545", + "--fork-block-number", + "123", + "--sender", + "0x00000000000000000000000000000000000000a1", + ], + }); + }); + + it("reads deployed bytecode from forge artifacts", async () => { + await writeJson("out/CounterFacet.sol/CounterFacet.json", { + deployedBytecode: { object: "0x6001" }, + }); + + expect( + await foundryAdapter.readDeployedBytecode( + projectRoot, + path.join(projectRoot, "src", "CounterFacet.sol"), + "CounterFacet", + ), + ).toBe("0x6001"); + expect( + await foundryAdapter.readDeployedBytecode(projectRoot, "/tmp/Missing.sol", "Missing"), + ).toBeUndefined(); + }); + + it("maps the run broadcast into deployment transactions", async () => { + await writeJson("broadcast/ComposeDeploy.s.sol/31337/run-latest.json", { + transactions: [ + { + hash: `0x${"01".repeat(32)}`, + transactionType: "CREATE", + contractName: "CounterFacet", + contractAddress: "0x00000000000000000000000000000000000000b1", + transaction: { from: "0x00000000000000000000000000000000000000a1" }, + }, + { + hash: `0x${"02".repeat(32)}`, + transactionType: "CREATE", + contractName: "Diamond", + contractAddress: "0x00000000000000000000000000000000000000aa", + }, + { + hash: `0x${"03".repeat(32)}`, + transactionType: "CALL", + contractName: "CounterFacet", + contractAddress: "0x00000000000000000000000000000000000000b1", + }, + ], + }); + + const scriptPath = path.join(projectRoot, "script", "ComposeDeploy.s.sol"); + expect(await foundryAdapter.readBroadcastTransactions(projectRoot, scriptPath, 31337)).toEqual([ + { + contractAddress: "0x00000000000000000000000000000000000000b1", + contractName: "CounterFacet", + txHash: `0x${"01".repeat(32)}`, + from: "0x00000000000000000000000000000000000000a1", + }, + { + contractAddress: "0x00000000000000000000000000000000000000aa", + contractName: "Diamond", + txHash: `0x${"02".repeat(32)}`, + }, + ]); + expect(await foundryAdapter.readBroadcastTransactions(projectRoot, scriptPath, 1)).toEqual([]); + }); + + it("reports an unreadable or malformed broadcast artifact", async () => { + const scriptPath = path.join(projectRoot, "script", "ComposeDeploy.s.sol"); + const broadcastPath = path.join(projectRoot, "broadcast", "ComposeDeploy.s.sol", "31337", "run-latest.json"); + await fs.mkdir(path.dirname(broadcastPath), { recursive: true }); + + await fs.writeFile(broadcastPath, "{not json", "utf8"); + await expect( + foundryAdapter.readBroadcastTransactions(projectRoot, scriptPath, 31337), + ).rejects.toThrow("Unable to parse the Foundry broadcast"); + + await fs.writeFile(broadcastPath, JSON.stringify({ transactions: "invalid" }), "utf8"); + await expect( + foundryAdapter.readBroadcastTransactions(projectRoot, scriptPath, 31337), + ).rejects.toThrow("missing a transactions array"); + }); +}); + +describe("Hardhat adapter deploy methods", () => { + it("resolves the managed script path and deploy command", () => { + const scriptPath = path.join(projectRoot, "ignition", "modules", "ComposeDeploy.ts"); + const runnerPath = path.join(projectRoot, ".compose", "hardhat", "ignition-runner.ts"); + expect(hardhatAdapter.getScriptRoot(projectRoot)).toBe(path.join(projectRoot, "ignition", "modules")); + expect(hardhatAdapter.getManagedDeployScriptPath(projectRoot)).toBe(scriptPath); + expect(hardhatAdapter.getManagedDeployRunnerPath(projectRoot)).toBe(runnerPath); + expect(hardhatAdapter.getManagedDeployResultPath(projectRoot)).toBe( + path.join(projectRoot, ".compose", "hardhat", "deploy-result.json"), + ); + + expect( + hardhatAdapter.createDeployCommand({ + projectRoot, + scriptPath, + runnerPath, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + mode: "broadcast", + passthrough: ["--verbose"], + }), + ).toEqual({ + command: "npx", + args: [ + "hardhat", + "--build-profile", + "production", + "run", + "--no-compile", + ".compose/hardhat/ignition-runner.ts", + "--network", + "local", + "--verbose", + ], + env: { + COMPOSE_DEPLOY_RPC_URL: "http://127.0.0.1:8545", + COMPOSE_DEPLOY_MODE: "broadcast", + }, + }); + }); + + it("passes the pinned fork block to the Hardhat simulation mode", () => { + const scriptPath = path.join(projectRoot, "ignition", "modules", "ComposeDeploy.ts"); + const runnerPath = path.join(projectRoot, ".compose", "hardhat", "ignition-runner.ts"); + expect(hardhatAdapter.createDeployCommand({ + projectRoot, + scriptPath, + runnerPath, + chainKey: "sepolia", + rpcUrl: "https://rpc.example.test", + chainId: 11155111, + mode: "simulate", + forkBlockNumber: 987n, + passthrough: [], + })).toEqual({ + command: "npx", + args: [ + "hardhat", + "--build-profile", + "production", + "run", + "--no-compile", + ".compose/hardhat/ignition-runner.ts", + "--network", + "sepolia", + ], + env: { + COMPOSE_DEPLOY_RPC_URL: "https://rpc.example.test", + COMPOSE_DEPLOY_MODE: "simulate", + COMPOSE_DEPLOY_FORK_BLOCK_NUMBER: "987", + }, + }); + }); + + it("reads deployed bytecode for project contracts", async () => { + await writeJson("artifacts/contracts/CounterFacet.sol/CounterFacet.json", { + deployedBytecode: "0x6002", + }); + + expect( + await hardhatAdapter.readDeployedBytecode( + projectRoot, + path.join(projectRoot, "contracts", "CounterFacet.sol"), + "CounterFacet", + ), + ).toBe("0x6002"); + }); + + it("reads deployed bytecode for npm package contracts", async () => { + await writeJson("node_modules/@perfect-abstractions/compose/package.json", { + name: "@perfect-abstractions/compose", + version: "9.9.9", + }); + await writeJson( + "artifacts/npm/@perfect-abstractions/compose@9.9.9/diamond/DiamondInspectFacet.sol/DiamondInspectFacet.json", + { deployedBytecode: "0x6003" }, + ); + + expect( + await hardhatAdapter.readDeployedBytecode( + projectRoot, + path.join( + projectRoot, + "node_modules", + "@perfect-abstractions", + "compose", + "diamond", + "DiamondInspectFacet.sol", + ), + "DiamondInspectFacet", + ), + ).toBe("0x6003"); + + expect( + await hardhatAdapter.readDeployedBytecode(projectRoot, "/elsewhere/Facet.sol", "Facet"), + ).toBeUndefined(); + }); + + it("reports no broadcast transactions", async () => { + expect( + await hardhatAdapter.readBroadcastTransactions( + projectRoot, + path.join(projectRoot, "scripts", "compose-deploy.ts"), + 31337, + ), + ).toEqual([]); + }); +}); + +describe("framework adapter project capabilities", () => { + it("does not restrict Foundry projects", async () => { + expect(() => foundryAdapter.assertSupportedProject(projectRoot)).not.toThrow(); + await expect(foundryAdapter.getDeployToolbox(projectRoot)).resolves.toBeNull(); + }); + + it("checks the Hardhat version and detects the toolbox", async () => { + await writeJson("package.json", { + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", + }, + }); + + expect(() => hardhatAdapter.assertSupportedProject(projectRoot)).not.toThrow(); + await expect(hardhatAdapter.getDeployToolbox(projectRoot)).resolves.toBe("viem"); + }); + + it("rejects an unsupported Hardhat version", async () => { + await writeJson("package.json", { devDependencies: { hardhat: "^2.22.0" } }); + expect(() => hardhatAdapter.assertSupportedProject(projectRoot)).toThrow("Hardhat 3.8 or newer"); + }); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/foundryAdapter/accounts.test.ts b/cli/test/adapters/IFrameworkAdapter/foundryAdapter/accounts.test.ts new file mode 100644 index 00000000..054c358a --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/foundryAdapter/accounts.test.ts @@ -0,0 +1,278 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ + runCommandCaptureStdout: vi.fn(), +})); + +vi.mock("../../../../src/utils/exec", () => ({ + runCommandCaptureStdout: mocks.runCommandCaptureStdout, +})); + +import { + importFoundryAccount, + listFoundrySignerAddresses, + readFoundryAccount, + resolveFoundryAccount, + resolveFoundryDeploySigner, +} from "../../../../src/adapters/IFrameworkAdapter/foundryAdapter/accounts"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-foundry-accounts-")); + vi.spyOn(os, "homedir").mockReturnValue(projectRoot); + mocks.runCommandCaptureStdout.mockReset(); +}); + +afterEach(async () => { + vi.restoreAllMocks(); + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +async function writeKeystore(name: string, value: unknown): Promise { + const directory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(directory, { recursive: true }); + await fs.writeFile(path.join(directory, name), JSON.stringify(value), "utf8"); +} + +describe("Foundry account helpers", () => { + it("reads a plaintext address from a keystore", async () => { + await writeKeystore("deployer", { address: "00000000000000000000000000000000000000a1" }); + + await expect(readFoundryAccount("deployer")).resolves.toEqual({ + address: "0x00000000000000000000000000000000000000A1", + exists: true, + requiresUnlock: false, + }); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("falls back to the .json keystore filename", async () => { + await writeKeystore("deployer.json", { address: "0x00000000000000000000000000000000000000a1" }); + + await expect(readFoundryAccount("deployer")).resolves.toMatchObject({ + address: "0x00000000000000000000000000000000000000A1", + exists: true, + }); + }); + + it("reports a missing keystore without unlocking", async () => { + await expect(readFoundryAccount("missing")).resolves.toEqual({ + address: null, + exists: false, + requiresUnlock: false, + }); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("marks an encrypted keystore as requiring an unlock", async () => { + await writeKeystore("deployer", { crypto: {}, id: "test-id", version: 3 }); + + await expect(readFoundryAccount("deployer")).resolves.toEqual({ + address: null, + exists: true, + requiresUnlock: true, + }); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("wraps keystore parse errors with the file path", async () => { + const directory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(directory, { recursive: true }); + await fs.writeFile(path.join(directory, "broken"), "{not json", "utf8"); + + await expect(readFoundryAccount("broken")).rejects.toThrow("Unable to read Foundry keystore at"); + }); + + it("does not unlock an encrypted keystore unless allowed", async () => { + await writeKeystore("deployer", { crypto: {} }); + + await expect(resolveFoundryAccount("deployer", projectRoot)).resolves.toEqual({ + address: null, + exists: true, + requiresUnlock: true, + }); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("unlocks through cast and notifies the caller first", async () => { + await writeKeystore("deployer", { crypto: {} }); + mocks.runCommandCaptureStdout.mockResolvedValue("0x00000000000000000000000000000000000000a1\n"); + const onUnlock = vi.fn(); + + await expect( + resolveFoundryAccount("deployer", projectRoot, { allowUnlock: true, onUnlock }), + ).resolves.toEqual({ + address: "0x00000000000000000000000000000000000000A1", + exists: true, + requiresUnlock: false, + }); + expect(onUnlock).toHaveBeenCalledOnce(); + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledWith( + "cast", + ["wallet", "address", "--account", "deployer"], + { cwd: projectRoot, forwardStdout: false }, + ); + }); + + it("rejects an invalid cast address response", async () => { + await writeKeystore("deployer", { crypto: {} }); + mocks.runCommandCaptureStdout.mockResolvedValue("no address here"); + + await expect( + resolveFoundryAccount("deployer", projectRoot, { allowUnlock: true }), + ).rejects.toThrow("Foundry did not return a public address for keystore account 'deployer'."); + }); + + it("lists the resolved signer address", async () => { + await writeKeystore("deployer", { address: "00000000000000000000000000000000000000a1" }); + + await expect(listFoundrySignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + accountName: "deployer", + })).resolves.toEqual(["0x00000000000000000000000000000000000000A1"]); + }); + + it("rejects listing an encrypted signer without unlock permission", async () => { + await writeKeystore("deployer", { crypto: {} }); + + await expect(listFoundrySignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + accountName: "deployer", + })).rejects.toThrow( + "Foundry keystore account 'deployer' needs to be unlocked to verify its public address.", + ); + }); + + it("resolves a selected Compose account without inspecting passthrough flags", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + foundryAccount: "production-deployer", + }, + passthrough: ["--sender", "0x00000000000000000000000000000000000000a2"], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("resolves an explicit Foundry sender from passthrough", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--sender=0x00000000000000000000000000000000000000a1"], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("resolves a named Foundry keystore account from passthrough", async () => { + await writeKeystore("deployer", { address: "00000000000000000000000000000000000000a1" }); + + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--account", "deployer"], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("leaves an opaque Foundry signing method unresolved", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--private-key", "0xsecret"], + })).resolves.toBeNull(); + }); + + it("skips prediction when a comma list rotates multiple signers", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--accounts", "deployer,other"], + })).resolves.toBeNull(); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("skips prediction when passthrough combines signing sources", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--account", "deployer", "--private-key", "0xsecret"], + })).resolves.toBeNull(); + }); + + it("skips prediction for repeated positional account values", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--accounts", "deployer", "other"], + })).resolves.toBeNull(); + }); + + it("still predicts a single account alongside a keystore password", async () => { + await writeKeystore("deployer", { address: "00000000000000000000000000000000000000a1" }); + + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--account", "deployer", "--password", "pw.txt"], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("predicts an explicit sender over a single hardware signer", async () => { + await expect(resolveFoundryDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: ["--sender", "0x00000000000000000000000000000000000000a1", "--ledger"], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("imports a key and parses the reported address", async () => { + mocks.runCommandCaptureStdout.mockResolvedValue( + "\nDeployer keystore was saved successfully. Address: 0x00000000000000000000000000000000000000a1\n", + ); + + await expect(importFoundryAccount(projectRoot, "deployer")).resolves.toBe( + "0x00000000000000000000000000000000000000a1", + ); + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledWith( + "cast", + ["wallet", "import", "deployer", "--interactive"], + { cwd: projectRoot }, + ); + }); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/foundryAdapter/scaffolding.test.ts b/cli/test/adapters/IFrameworkAdapter/foundryAdapter/scaffolding.test.ts new file mode 100644 index 00000000..e36076a9 --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/foundryAdapter/scaffolding.test.ts @@ -0,0 +1,140 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { CLI_DEV_DEPENDENCY_VERSION, CLI_PACKAGE_NAME } from "../../../../src/utils/metadata"; + +const { runCommand } = vi.hoisted(() => ({ runCommand: vi.fn(async () => undefined) })); + +vi.mock("../../../../src/utils/exec", () => ({ runCommand })); + +import { foundryAdapter } from "../../../../src/adapters/IFrameworkAdapter/foundryAdapter/adapter"; +import { ConfigOptions } from "../../../../src/adapters/IFrameworkAdapter/types"; +import { Context } from "../../../../src/context/context"; +import { ComposeContext } from "../../../../src/context/types"; + +function createContext(projectRoot: string, installDeps: boolean): ComposeContext { + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + ctx.param.projectName = "my-diamond"; + ctx.param.installDeps = installDeps; + return ctx; +} + +function configOptions(installDeps: boolean): ConfigOptions { + return { + compilerVersion: "0.8.30", + projectName: "my-diamond", + installDeps, + }; +} + +/** Tests Foundry scaffolding writes with the framework commands mocked. */ +describe("foundryAdapter project scaffolding", () => { + let projectRoot: string; + + beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-foundry-init-")); + runCommand.mockClear(); + }); + + afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); + }); + + it("writes a package.json that makes the Compose CLI available locally", async () => { + await foundryAdapter.initProject(createContext(projectRoot, false)); + + const packageJson = JSON.parse( + await fs.readFile(path.join(projectRoot, "package.json"), "utf8"), + ) as { + name: string; + scripts: Record; + devDependencies: Record; + }; + + expect(packageJson.name).toBe("my-diamond"); + expect(packageJson.scripts).toEqual({ + build: "forge build", + test: "forge test", + fmt: "forge fmt", + validate: "compose validate", + }); + expect(packageJson.devDependencies).toEqual({ + [CLI_PACKAGE_NAME]: CLI_DEV_DEPENDENCY_VERSION, + }); + expect(runCommand).toHaveBeenCalledWith("forge", ["init", "."], { cwd: projectRoot }); + }); + + it("installs npm dependencies during writeConfig when enabled", async () => { + await foundryAdapter.writeConfig(createContext(projectRoot, true), configOptions(true)); + + expect(runCommand).toHaveBeenCalledWith("npm", ["install"], { cwd: projectRoot }); + }); + + it("skips npm install when dependency installation is disabled", async () => { + await foundryAdapter.writeConfig(createContext(projectRoot, false), configOptions(false)); + + expect(runCommand).not.toHaveBeenCalledWith("npm", ["install"], { cwd: projectRoot }); + }); + + it("adds Sepolia RPC and compile settings without overwriting existing config", async () => { + await fs.writeFile( + path.join(projectRoot, "foundry.toml"), + [ + "[profile.default]", + 'solc = "0.8.28"', + "", + "[rpc_endpoints]", + 'mainnet = "https://ethereum.example"', + "", + ].join("\n"), + "utf8", + ); + + await foundryAdapter.writeConfig(createContext(projectRoot, false), configOptions(false)); + + const foundryToml = await fs.readFile(path.join(projectRoot, "foundry.toml"), "utf8"); + expect(foundryToml).toContain('solc = "0.8.28"'); + expect(foundryToml).toContain("optimizer = true"); + expect(foundryToml).toContain("[rpc_endpoints]"); + expect(foundryToml).toContain('sepolia = "${SEPOLIA_RPC_URL}"'); + expect(foundryToml).toContain('mainnet = "https://ethereum.example"'); + await expect(fs.readFile(path.join(projectRoot, ".env.example"), "utf8")) + .resolves.toContain("SEPOLIA_RPC_URL="); + }); + + it("warns and keeps going when npm install fails", async () => { + runCommand.mockRejectedValueOnce(new Error("npm unavailable")); + const logs = vi.spyOn(console, "log").mockImplementation(() => undefined); + + try { + await expect( + foundryAdapter.writeConfig(createContext(projectRoot, true), configOptions(true)), + ).resolves.toBeUndefined(); + expect(logs.mock.calls.flat().join("\n")).toContain("Could not install npm dependencies"); + } finally { + logs.mockRestore(); + } + }); + + it("adds node_modules and the Compose runtime directory to an existing .gitignore without dropping forge entries", async () => { + await fs.writeFile(path.join(projectRoot, ".gitignore"), "out/\ncache/\n", "utf8"); + + await foundryAdapter.writeConfig(createContext(projectRoot, false), configOptions(false)); + + await expect( + fs.readFile(path.join(projectRoot, ".gitignore"), "utf8"), + ).resolves.toBe("out/\ncache/\nnode_modules/\n.compose/\n"); + }); + + it("does not duplicate the Compose runtime directory when it is already ignored", async () => { + await fs.writeFile(path.join(projectRoot, ".gitignore"), "out/\ncache/\n.compose/\n", "utf8"); + + await foundryAdapter.writeConfig(createContext(projectRoot, false), configOptions(false)); + + await expect( + fs.readFile(path.join(projectRoot, ".gitignore"), "utf8"), + ).resolves.toBe("out/\ncache/\n.compose/\nnode_modules/\n"); + }); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/accounts.test.ts b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/accounts.test.ts new file mode 100644 index 00000000..1fe88f5f --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/accounts.test.ts @@ -0,0 +1,273 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ + runCommandCaptureStdout: vi.fn(), +})); + +vi.mock("../../../../src/utils/exec", () => ({ + runCommandCaptureStdout: mocks.runCommandCaptureStdout, +})); + +import { hardhatAdapter } from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; +import { + listHardhatSignerAddresses, + readHardhatAccountKeyVariable, +} from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/accounts"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-hardhat-accounts-")); + mocks.runCommandCaptureStdout.mockReset(); + await fs.writeFile(path.join(projectRoot, "package.json"), JSON.stringify({ + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", + }, + }), "utf8"); +}); + +afterEach(async () => { + vi.restoreAllMocks(); + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +describe("Hardhat account helpers", () => { + it("reads a single key variable from the selected network config", async () => { + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + export default { + networks: { + local: { type: "http", accounts: "remote" }, + sepolia: { + type: "http", + url: configVariable("SEPOLIA_RPC_URL"), + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], + }, + }, + }; + `, "utf8"); + + await expect(readHardhatAccountKeyVariable(projectRoot, "sepolia")) + .resolves.toBe("SEPOLIA_PRIVATE_KEY"); + await expect(readHardhatAccountKeyVariable(projectRoot, "local")) + .resolves.toBeNull(); + }); + + it("uses the Compose network overlay when the base config also defines networks", async () => { + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + const baseConfig = { + networks: { + sepolia: { + type: "http", + accounts: [configVariable("BASE_SEPOLIA_PRIVATE_KEY")], + }, + }, + }; + export default { + ...baseConfig, + networks: { + ...baseConfig.networks, + sepolia: { + type: "http", + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], + }, + }, + }; + `, "utf8"); + + await expect(readHardhatAccountKeyVariable(projectRoot, "sepolia")) + .resolves.toBe("SEPOLIA_PRIVATE_KEY"); + }); + + it("does not guess for custom or ambiguous account config", async () => { + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + export default { + networks: { + sepolia: { + accounts: process.env.DEPLOYER_KEY ? [process.env.DEPLOYER_KEY] : [], + }, + }, + }; + `, "utf8"); + await expect(readHardhatAccountKeyVariable(projectRoot, "sepolia")) + .resolves.toBeNull(); + + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + export default { + networks: { + sepolia: { + accounts: [ + configVariable("DEPLOYER_KEY"), + configVariable("BACKUP_KEY"), + ], + }, + }, + }; + `, "utf8"); + await expect(readHardhatAccountKeyVariable(projectRoot, "sepolia")) + .resolves.toBeNull(); + }); + + it("returns no key variable when the config file is unavailable", async () => { + await expect(readHardhatAccountKeyVariable(projectRoot, "sepolia")) + .resolves.toBeNull(); + }); + + it("lists the configured signer addresses from the managed probe", async () => { + const address = "0x00000000000000000000000000000000000000a1"; + mocks.runCommandCaptureStdout.mockResolvedValue( + `COMPOSE_ACCOUNT_ADDRESSES:["${address}"]\n`, + ); + + await expect(listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + })).resolves.toEqual(["0x00000000000000000000000000000000000000A1"]); + + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledWith( + "npx", + ["hardhat", "--build-profile", "production", "run", "--no-compile", ".compose/hardhat/account-probe.ts", "--network", "local"], + expect.objectContaining({ + cwd: projectRoot, + env: { COMPOSE_DEPLOY_RPC_URL: "http://127.0.0.1:8545" }, + forwardStdout: false, + }), + ); + }); + + it("writes the probe under the ignored Compose runtime directory", async () => { + mocks.runCommandCaptureStdout.mockResolvedValue( + 'COMPOSE_ACCOUNT_ADDRESSES:["0x00000000000000000000000000000000000000a1"]\n', + ); + + await listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + }); + + await expect( + fs.readdir(path.join(projectRoot, ".compose", "hardhat")), + ).resolves.toEqual(["account-probe.ts"]); + await expect(fs.access(path.join(projectRoot, "scripts"))).rejects.toThrow(); + + const gitignore = await fs.readFile(path.join(projectRoot, ".gitignore"), "utf8"); + expect(gitignore).toBe(".compose/\n"); + + const probe = await fs.readFile( + path.join(projectRoot, ".compose", "hardhat", "account-probe.ts"), + "utf8", + ); + expect(probe).toContain('network: "local"'); + expect(probe).toContain("actualChainId !== 31337"); + expect(probe).toContain("getWalletClients"); + expect(probe).not.toContain("{{"); + }); + + it("keeps the ignored runtime directory stable across runs", async () => { + mocks.runCommandCaptureStdout.mockResolvedValue( + 'COMPOSE_ACCOUNT_ADDRESSES:["0x00000000000000000000000000000000000000a1"]\n', + ); + + await fs.writeFile(path.join(projectRoot, ".gitignore"), "node_modules/\n.compose/\n", "utf8"); + + await listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + }); + await listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + }); + + const gitignore = await fs.readFile(path.join(projectRoot, ".gitignore"), "utf8"); + expect(gitignore).toBe("node_modules/\n.compose/\n"); + await expect( + fs.readdir(path.join(projectRoot, ".compose", "hardhat")), + ).resolves.toEqual(["account-probe.ts"]); + }); + + it("resolves a selected Compose account without listing network signers", async () => { + await expect(hardhatAdapter.resolveDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + }, + passthrough: [], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + }); + + it("resolves the first configured Hardhat signer by default", async () => { + mocks.runCommandCaptureStdout.mockResolvedValue( + 'COMPOSE_ACCOUNT_ADDRESSES:["0x00000000000000000000000000000000000000a1","0x00000000000000000000000000000000000000a2"]\n', + ); + + await expect(hardhatAdapter.resolveDeploySigner({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + account: null, + passthrough: [], + })).resolves.toBe("0x00000000000000000000000000000000000000A1"); + }); + + it("leaves the probe in place when Hardhat fails", async () => { + mocks.runCommandCaptureStdout.mockRejectedValue(new Error("hardhat failed")); + + await expect(listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + })).rejects.toThrow("hardhat failed"); + + await expect( + fs.readdir(path.join(projectRoot, ".compose", "hardhat")), + ).resolves.toEqual(["account-probe.ts"]); + await expect(fs.access(path.join(projectRoot, "scripts"))).rejects.toThrow(); + }); + + it("rejects a response without the Compose marker", async () => { + mocks.runCommandCaptureStdout.mockResolvedValue("no marker here\n"); + + await expect(listHardhatSignerAddresses({ + projectRoot, + chainKey: "local", + rpcUrl: "http://127.0.0.1:8545", + chainId: 31337, + })).rejects.toThrow("Hardhat did not report its configured signer addresses."); + }); + + it("reports that Hardhat has no native account store or Compose-driven import", async () => { + expect(hardhatAdapter.supportsAccountImport).toBe(false); + await expect(hardhatAdapter.readAccountAddress(projectRoot, "deployer")).resolves.toEqual({ + address: null, + exists: false, + requiresUnlock: false, + }); + await expect(hardhatAdapter.resolveAccountAddress(projectRoot, "deployer")).resolves.toEqual({ + address: null, + exists: false, + requiresUnlock: false, + }); + await expect(hardhatAdapter.importAccount(projectRoot, "deployer")).rejects.toThrow( + "Hardhat accounts are configured in hardhat.config.ts; Compose does not import keys.", + ); + }); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/hardhatAdapter.test.ts b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/hardhatAdapter.test.ts index 35752f46..306cfd2b 100644 --- a/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/hardhatAdapter.test.ts +++ b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/hardhatAdapter.test.ts @@ -1,15 +1,84 @@ +import { spawn } from "node:child_process"; import fs from "node:fs/promises"; +import { createServer, type Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import os from "node:os"; import path from "node:path"; import { beforeAll, describe, expect, it } from "vitest"; -import { hardhatAdapter } from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; +import { + createHardhatInitCommand, + hardhatAdapter, + removeHardhatTemplateSamples, +} from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; import { resolveHardhatAstSourcePath } from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/helpers"; +import { Context } from "../../../../src/context/context"; +import { ConfigModule } from "../../../../src/modules/config/module"; +import { CLI_DEV_DEPENDENCY_VERSION, CLI_PACKAGE_NAME } from "../../../../src/utils/metadata"; import { canonicalizeAst } from "../canonicalAst"; import { createHardhatAdapterFixtureHarness, ensureHardhatFixtureDependencies, } from "./harness"; -/** Tests Hardhat AST compilation and build-info normalization. */ +type RPCRequest = { id: number | string | null; method: string }; + +async function startRPCServer(chainId: number): Promise<{ + url: string; + methods: string[]; + close(): Promise; +}> { + const methods: string[] = []; + const server: Server = createServer((request, response) => { + const chunks: Buffer[] = []; + request.on("data", (chunk: Buffer) => chunks.push(chunk)); + request.on("end", () => { + const payload = JSON.parse(Buffer.concat(chunks).toString("utf8")) as RPCRequest; + methods.push(payload.method); + const result = payload.method === "eth_chainId" + ? `0x${chainId.toString(16)}` + : payload.method === "net_version" + ? String(chainId) + : payload.method === "eth_accounts" + ? [] + : null; + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ jsonrpc: "2.0", id: payload.id, result })); + }); + }); + + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const address = server.address() as AddressInfo; + return { + url: `http://127.0.0.1:${address.port}`, + methods, + close: () => new Promise((resolve, reject) => { + server.close((error) => error ? reject(error) : resolve()); + }), + }; +} + +function runHardhatScript( + projectRoot: string, + scriptPath: string, + rpcUrl: string, +): Promise<{ code: number; stdout: string; stderr: string }> { + const hardhatCliPath = path.join(projectRoot, "node_modules", "hardhat", "dist", "src", "cli.js"); + return new Promise((resolve, reject) => { + const child = spawn(process.execPath, [hardhatCliPath, "run", scriptPath, "--network", "local"], { + cwd: projectRoot, + env: { ...process.env, COMPOSE_DEPLOY_RPC_URL: rpcUrl }, + windowsHide: true, + }); + let stdout = ""; + let stderr = ""; + child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); }); + child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); }); + child.once("error", reject); + child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr })); + }); +} + +/** Tests Hardhat AST compilation, build-info normalization, and config scaffolding. */ describe("hardhatAdapter.compileAst", () => { beforeAll(() => ensureHardhatFixtureDependencies(), 120_000); @@ -78,3 +147,247 @@ describe("hardhatAdapter.compileAst", () => { 30_000, ); }); + +/** Tests Hardhat project config scaffolding written by compose init. */ +describe("hardhatAdapter.writeConfig", () => { + it("adds Compose settings to the official config without creating another config file", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-hardhat-config-")); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + ctx.param.base = "none"; + ctx.param.toolbox = "ethers"; + await ConfigModule.loadBasesCatalog(ctx); + + try { + await fs.writeFile(path.join(projectRoot, "package.json"), JSON.stringify({ + name: "hardhat-config-fixture", + private: true, + type: "module", + scripts: { + custom: "echo custom", + validate: "custom validate", + }, + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.7", + }, + }), "utf8"); + await fs.writeFile( + path.join(projectRoot, "hardhat.config.ts"), + [ + 'import hardhatToolboxMochaEthersPlugin from "@nomicfoundation/hardhat-toolbox-mocha-ethers";', + 'import { configVariable, defineConfig } from "hardhat/config";', + "", + "export default defineConfig({", + " plugins: [hardhatToolboxMochaEthersPlugin],", + ' solidity: { profiles: { default: { version: "0.8.28" }, production: { version: "0.8.28" } } },', + ' networks: { sepolia: { type: "http", chainType: "l1", url: configVariable("SEPOLIA_RPC_URL"), accounts: [] } },', + "});", + "", + ].join("\n"), + "utf8", + ); + await fs.writeFile(path.join(projectRoot, "tsconfig.json"), JSON.stringify({ + compilerOptions: { module: "node20", target: "es2023", types: ["node", "mocha"] }, + }), "utf8"); + await fs.writeFile(path.join(projectRoot, ".gitignore"), "node_modules/\n", "utf8"); + + await hardhatAdapter.writeConfig(ctx, { + compilerVersion: "0.8.30", + projectName: "hardhat-config-fixture", + installDeps: false, + }); + + const config = await fs.readFile(path.join(projectRoot, "hardhat.config.ts"), "utf8"); + expect(config).toContain("const baseConfig = defineConfig({"); + expect(config).toContain("hardhatToolboxMochaEthersPlugin"); + expect(config).toContain('configVariable("SEPOLIA_RPC_URL")'); + expect(config).toContain('configVariable("SEPOLIA_PRIVATE_KEY")'); + expect(config).toContain('url: "http://127.0.0.1:8545"'); + expect(config).toContain('accounts: "remote"'); + expect(config).toContain("npmFilesToBuild:"); + + const packageJson = JSON.parse(await fs.readFile(path.join(projectRoot, "package.json"), "utf8")); + expect(packageJson.devDependencies[CLI_PACKAGE_NAME]).toBe(CLI_DEV_DEPENDENCY_VERSION); + expect(packageJson.dependencies["@perfect-abstractions/compose"]).toBe("latest"); + expect(packageJson.devDependencies["@nomicfoundation/hardhat-toolbox-mocha-ethers"]).toBe("^3.0.7"); + expect(packageJson.engines.node).toBe(">=22.13.0"); + expect(packageJson.scripts).toEqual({ + custom: "echo custom", + validate: "custom validate", + build: "hardhat build", + test: "hardhat test", + }); + expect(JSON.parse(await fs.readFile(path.join(projectRoot, "tsconfig.json"), "utf8"))) + .toMatchObject({ compilerOptions: { module: "node20" } }); + + const gitignore = await fs.readFile(path.join(projectRoot, ".gitignore"), "utf8"); + expect(gitignore).toContain("node_modules/"); + expect(gitignore).toContain("cache/"); + expect(gitignore).toContain(".compose/"); + expect(gitignore).not.toContain("scripts/.compose/"); + expect(gitignore).not.toContain(".cache/"); + + const envExample = await fs.readFile(path.join(projectRoot, ".env.example"), "utf8"); + expect(envExample).toContain("SEPOLIA_RPC_URL="); + expect(envExample).toContain("SEPOLIA_PRIVATE_KEY="); + + await expect( + fs.access(path.join(projectRoot, "scripts")), + ).resolves.toBeUndefined(); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); +}); + +/** Verifies Compose invokes Hardhat's official non-interactive template IDs. */ +describe("hardhatAdapter.ensurePackageFacetsCompilable", () => { + async function createConfig(contents: string): Promise { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "compose-npm-build-")); + await fs.writeFile(path.join(root, "hardhat.config.ts"), contents, "utf8"); + return root; + } + + const overlay = (files: string) => `const base = 1;\nconst composeNpmFilesToBuild = ${files};\nexport default base;\n`; + + it("adds missing package specifiers and can revert", async () => { + const root = await createConfig(overlay('["@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol"]')); + const configPath = path.join(root, "hardhat.config.ts"); + + const revert = await hardhatAdapter.ensurePackageFacetsCompilable?.( + root, + ["@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"], + ); + + expect(revert).toBeTypeOf("function"); + const updated = await fs.readFile(configPath, "utf8"); + expect(updated).toContain('"@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol"'); + expect(updated).toContain('"@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"'); + + await revert?.(); + expect(await fs.readFile(configPath, "utf8")).toBe(overlay('["@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol"]')); + await fs.rm(root, { recursive: true, force: true }); + }); + + it("returns null and leaves the config untouched when nothing is missing", async () => { + const contents = overlay('["@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"]'); + const root = await createConfig(contents); + const configPath = path.join(root, "hardhat.config.ts"); + + await expect( + hardhatAdapter.ensurePackageFacetsCompilable?.(root, ["@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"]), + ).resolves.toBeNull(); + expect(await fs.readFile(configPath, "utf8")).toBe(contents); + await fs.rm(root, { recursive: true, force: true }); + }); + + it("gives manual guidance when the compose overlay marker is missing", async () => { + const root = await createConfig("export default { solidity: {} };\n"); + + await expect( + hardhatAdapter.ensurePackageFacetsCompilable?.( + root, + ["@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"], + ), + ).rejects.toThrow( + 'Add "@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol" to solidity.npmFilesToBuild in hardhat.config.ts, then install again.', + ); + await fs.rm(root, { recursive: true, force: true }); + }); +}); + +describe("Hardhat official initializer", () => { + it.each([ + ["ethers", "mocha-ethers"], + ["viem", "node-test-runner-viem"], + ])("uses the %s template without setup prompts", (toolbox, template) => { + expect(createHardhatInitCommand(toolbox)).toEqual({ + command: "npx", + args: [ + "--yes", + "--package=hardhat@3.8.0", + "hardhat", + "--init", + "--template", + template, + ], + }); + }); + + it("removes only known Hardhat demo files before adding Compose contracts", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-hardhat-template-cleanup-")); + const sampleFiles = [ + "contracts/Counter.sol", + "contracts/Counter.t.sol", + "test/Counter.ts", + "ignition/modules/Counter.ts", + "scripts/send-op-tx.ts", + ]; + + try { + await Promise.all(sampleFiles.map(async (relativePath) => { + const filePath = path.join(projectRoot, relativePath); + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, "// official Hardhat sample\n", "utf8"); + })); + const userFile = path.join(projectRoot, "contracts", "UserFacet.sol"); + await fs.writeFile(userFile, "contract UserFacet {}\n", "utf8"); + + await removeHardhatTemplateSamples(projectRoot); + + await Promise.all(sampleFiles.map((relativePath) => + expect(fs.access(path.join(projectRoot, relativePath))).rejects.toThrow(), + )); + await expect(fs.readFile(userFile, "utf8")).resolves.toBe("contract UserFacet {}\n"); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); +}); + +describe("Hardhat managed-deploy RPC override", () => { + beforeAll(() => ensureHardhatFixtureDependencies(), 120_000); + + it("uses the Compose endpoint instead of the configured endpoint", async () => { + const harness = await createHardhatAdapterFixtureHarness(); + const configuredRPC = await startRPCServer(31337); + const composeRPC = await startRPCServer(31337); + + try { + await fs.writeFile( + path.join(harness.projectRoot, "hardhat.config.ts"), + `import { defineConfig } from "hardhat/config";\n\nexport default defineConfig({\n solidity: { version: "0.8.30" },\n networks: {\n local: {\n type: "http",\n chainType: "l1",\n url: "${configuredRPC.url}",\n accounts: "remote",\n },\n },\n});\n`, + "utf8", + ); + await fs.mkdir(path.join(harness.projectRoot, "scripts"), { recursive: true }); + await fs.writeFile( + path.join(harness.projectRoot, "scripts", "check-compose-rpc.ts"), + [ + 'import { network } from "hardhat";', + "const rpcUrl = process.env.COMPOSE_DEPLOY_RPC_URL;", + 'if (!rpcUrl) throw new Error("Missing Compose RPC URL");', + 'const connection = await network.create({ network: "local", override: { url: rpcUrl } });', + 'const chainId = Number(BigInt(String(await connection.provider.request({ method: "eth_chainId", params: [] }))));', + 'console.log("COMPOSE_RPC_RESULT", JSON.stringify({ chainId }));', + "await connection.close();", + ].join("\n"), + "utf8", + ); + + const result = await runHardhatScript( + harness.projectRoot, + "scripts/check-compose-rpc.ts", + composeRPC.url, + ); + const output = `${result.stdout}\n${result.stderr}`; + expect(result.code, output).toBe(0); + expect(output).toContain('COMPOSE_RPC_RESULT {"chainId":31337}'); + expect(composeRPC.methods).toContain("eth_chainId"); + expect(configuredRPC.methods).toEqual([]); + } finally { + await harness.cleanup(); + await Promise.all([configuredRPC.close(), composeRPC.close()]); + } + }, 60_000); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/helpers.test.ts b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/helpers.test.ts new file mode 100644 index 00000000..84db4179 --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/hardhatAdapter/helpers.test.ts @@ -0,0 +1,77 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { + assertHardhat3, + detectHardhatToolbox, +} from "../../../../src/adapters/IFrameworkAdapter/hardhatAdapter/helpers"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-hardhat-version-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +async function writePackage(packageJson: unknown): Promise { + await fs.writeFile(path.join(projectRoot, "package.json"), JSON.stringify(packageJson), "utf8"); +} + +describe("assertHardhat3", () => { + it.each(["^3.8.0", "3.21.0"])("accepts a supported Hardhat 3 version (%s)", async (version) => { + await writePackage({ devDependencies: { hardhat: version } }); + expect(() => assertHardhat3(projectRoot)).not.toThrow(); + }); + + it.each(["^2.22.0", "^3.0.0"])("rejects an unsupported Hardhat version (%s)", async (version) => { + await writePackage({ devDependencies: { hardhat: version } }); + expect(() => assertHardhat3(projectRoot)).toThrow("Hardhat 3.8 or newer"); + }); + + it("requires a declared or installed Hardhat dependency", async () => { + await writePackage({ devDependencies: {} }); + expect(() => assertHardhat3(projectRoot)).toThrow("Could not determine the Hardhat version"); + }); +}); + +describe("detectHardhatToolbox", () => { + it.each([ + ["@nomicfoundation/hardhat-toolbox-viem"], + ["@nomicfoundation/hardhat-viem"], + ])("detects the viem toolbox from %s", async (dependency) => { + await writePackage({ devDependencies: { [dependency]: "^5.0.0" } }); + await expect(detectHardhatToolbox(projectRoot)).resolves.toBe("viem"); + }); + + it.each([ + ["@nomicfoundation/hardhat-toolbox-mocha-ethers"], + ["@nomicfoundation/hardhat-ethers"], + ])("detects the ethers toolbox from %s", async (dependency) => { + await writePackage({ dependencies: { [dependency]: "^3.0.0" } }); + await expect(detectHardhatToolbox(projectRoot)).resolves.toBe("ethers"); + }); + + it("rejects a project without a supported toolbox", async () => { + await writePackage({ devDependencies: { hardhat: "^3.8.0" } }); + await expect(detectHardhatToolbox(projectRoot)).rejects.toThrow( + "Compose requires @nomicfoundation/hardhat-ethers or @nomicfoundation/hardhat-viem", + ); + }); + + it("rejects a missing package.json", async () => { + await expect(detectHardhatToolbox(projectRoot)).rejects.toThrow( + "Cannot determine the Hardhat toolbox", + ); + }); + + it("rejects an invalid package.json", async () => { + await fs.writeFile(path.join(projectRoot, "package.json"), "{not json", "utf8"); + await expect(detectHardhatToolbox(projectRoot)).rejects.toThrow( + "Cannot determine the Hardhat toolbox", + ); + }); +}); diff --git a/cli/test/adapters/IFrameworkAdapter/testMethods.test.ts b/cli/test/adapters/IFrameworkAdapter/testMethods.test.ts new file mode 100644 index 00000000..69532a88 --- /dev/null +++ b/cli/test/adapters/IFrameworkAdapter/testMethods.test.ts @@ -0,0 +1,49 @@ +import { describe, expect, it } from "vitest"; +import { foundryAdapter } from "../../../src/adapters/IFrameworkAdapter/foundryAdapter/adapter"; +import { hardhatAdapter } from "../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; + +describe("Foundry adapter test command", () => { + it("builds forge test and forwards passthrough arguments", () => { + expect( + foundryAdapter.createTestCommand({ + projectRoot: "/project", + passthrough: ["--match-test", "test_Increment", "-vvv"], + }), + ).toEqual({ + command: "forge", + args: ["test", "--match-test", "test_Increment", "-vvv"], + }); + }); + + it("builds a bare forge test command", () => { + expect( + foundryAdapter.createTestCommand({ projectRoot: "/project", passthrough: [] }), + ).toEqual({ + command: "forge", + args: ["test"], + }); + }); +}); + +describe("Hardhat adapter test command", () => { + it("builds hardhat test and forwards passthrough arguments", () => { + expect( + hardhatAdapter.createTestCommand({ + projectRoot: "/project", + passthrough: ["--grep", "increment"], + }), + ).toEqual({ + command: "npx", + args: ["hardhat", "test", "--grep", "increment"], + }); + }); + + it("builds a bare hardhat test command", () => { + expect( + hardhatAdapter.createTestCommand({ projectRoot: "/project", passthrough: [] }), + ).toEqual({ + command: "npx", + args: ["hardhat", "test"], + }); + }); +}); diff --git a/cli/test/adapters/IRPCAdapter/adapter.test.ts b/cli/test/adapters/IRPCAdapter/adapter.test.ts index bb8c6d5e..efc7c14d 100644 --- a/cli/test/adapters/IRPCAdapter/adapter.test.ts +++ b/cli/test/adapters/IRPCAdapter/adapter.test.ts @@ -31,6 +31,7 @@ vi.mock("viem", () => ({ })); import { createRPCAdapter } from "../../../src/adapters/IRPCAdapter/adapter"; +import { requestError } from "../../../src/adapters/IRPCAdapter/errors"; type MockClient = { chain: { id: number }; @@ -76,6 +77,39 @@ describe("createRPCAdapter", () => { }); }); + it("reports the endpoint and the root cause when a request fails", async () => { + useClient({ + getChainId: vi.fn().mockRejectedValue( + new Error("HTTP request failed", { cause: new Error("connect ECONNREFUSED 127.0.0.1:8545") }), + ), + }); + + await expect( + createRPCAdapter({ rpcUrl: "http://127.0.0.1:8545", chainId: 31337 }), + ).rejects.toThrow( + "RPC getChainId failed on chain 31337 at http://127.0.0.1:8545: connect ECONNREFUSED 127.0.0.1:8545", + ); + }); + + it("redacts RPC credentials, query values, path tokens, and secrets echoed by the cause", () => { + const apiKey = "sample-api-key-123456789"; + const rpcUrl = `https://user:password@rpc.example/v1/${apiKey}?apikey=${apiKey}&token=query-secret#fragment-secret`; + const cause = new Error("HTTP request failed", { + cause: new Error(`request failed for ${rpcUrl}; key=${apiKey}`), + }); + + const error = requestError("getChainId", 1, cause, rpcUrl); + + expect(error.message).toContain("at https://rpc.example"); + expect(error.message).toContain("request failed"); + expect(error.message).not.toContain(apiKey); + expect(error.message).not.toContain("user:password"); + expect(error.message).not.toContain("query-secret"); + expect(error.message).not.toContain("fragment-secret"); + expect(error.message).not.toContain("/v1/"); + expect(error.message).not.toContain("?apikey="); + }); + it("checks bytecode only when requested", async () => { useClient(); const adapter = await createRPCAdapter({ rpcUrl: "https://rpc.example", chainId: 11155111 }); diff --git a/cli/test/comander.test.ts b/cli/test/comander.test.ts index 34407125..2d4213fb 100644 --- a/cli/test/comander.test.ts +++ b/cli/test/comander.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { buildProgram, parseArgs } from "../src/comander"; describe("validate command arguments", () => { @@ -36,6 +36,34 @@ describe("init command arguments", () => { }, }); }); + + it("parses upgradeability flags", () => { + expect( + parseArgs(["node", "compose", "init", "--base", "none", "--yes", "--immutable"]), + ).toEqual({ + command: "init", + flags: { + framework: "foundry", + toolbox: "ethers", + base: "none", + yes: true, + immutable: true, + }, + }); + + expect( + parseArgs(["node", "compose", "init", "--base", "none", "--yes", "--upgradeable"]), + ).toEqual({ + command: "init", + flags: { + framework: "foundry", + toolbox: "ethers", + base: "none", + yes: true, + upgradeable: true, + }, + }); + }); }); describe("rpc command", () => { @@ -149,3 +177,221 @@ describe("facet configuration commands", () => { }); }); }); + +describe("account command arguments", () => { + it("parses account setup options", () => { + expect(parseArgs([ + "node", + "compose", + "account", + "setup", + "deployer", + "--address", + "0x00000000000000000000000000000000000000a1", + "--foundry-account", + "prod-key", + "--chain", + "sepolia", + ])).toEqual({ + command: "account", + flags: { + action: "setup", + accountName: "deployer", + address: "0x00000000000000000000000000000000000000a1", + foundryAccount: "prod-key", + chain: "sepolia", + }, + }); + }); + + it("parses account list", () => { + expect(parseArgs(["node", "compose", "account", "list"])).toEqual({ + command: "account", + flags: { action: "list" }, + }); + }); + + it("parses account check options", () => { + expect(parseArgs([ + "node", + "compose", + "account", + "check", + "deployer", + "--chain", + "sepolia", + "--rpc-url", + "https://rpc.example.test", + ])).toEqual({ + command: "account", + flags: { + action: "check", + accountName: "deployer", + chain: "sepolia", + rpcUrl: "https://rpc.example.test", + }, + }); + }); +}); + +describe("test command arguments", () => { + it("accepts a project root and framework passthrough arguments", () => { + expect( + parseArgs([ + "node", + "compose", + "test", + "--project-root", + "./project", + "--", + "--match-test", + "test_Increment", + "-vvv", + ]), + ).toEqual({ + command: "test", + flags: { + projectRoot: "./project", + passthrough: ["--match-test", "test_Increment", "-vvv"], + }, + }); + }); + + it("accepts test without options", () => { + expect(parseArgs(["node", "compose", "test"])).toEqual({ + command: "test", + flags: {}, + }); + }); +}); + +describe("deploy command arguments", () => { + it("defaults chain, instance, and deployment flags", () => { + expect(parseArgs(["node", "compose", "deploy"])).toEqual({ + command: "deploy", + flags: { chain: "local", instance: "default" }, + }); + }); + + it("parses deploy options", () => { + expect( + parseArgs([ + "node", + "compose", + "deploy", + "--diamond", + "Token", + "--chain", + "sepolia", + "--account", + "deployer", + "--instance", + "staging", + "--project-root", + "./project", + "--broadcast", + "--redeploy", + ]), + ).toEqual({ + command: "deploy", + flags: { + diamond: "Token", + chain: "sepolia", + account: "deployer", + instance: "staging", + projectRoot: "./project", + broadcast: true, + redeploy: true, + }, + }); + }); + + it("parses a per-deployment RPC URL override", () => { + expect(parseArgs([ + "node", + "compose", + "deploy", + "--chain", + "sepolia", + "--rpc-url", + "https://rpc.example.test/v1/token", + ])).toEqual({ + command: "deploy", + flags: { + chain: "sepolia", + instance: "default", + rpcUrl: "https://rpc.example.test/v1/token", + }, + }); + }); + + it("forwards arguments after -- as passthrough", () => { + expect( + parseArgs([ + "node", + "compose", + "deploy", + "--broadcast", + "--", + "--private-key", + "0xabc", + "--non-interactive", + ]), + ).toEqual({ + command: "deploy", + flags: { + broadcast: true, + chain: "local", + instance: "default", + passthrough: ["--private-key", "0xabc", "--non-interactive"], + }, + }); + }); + + it("keeps commander strict about unknown options before --", () => { + const exitSpy = vi + .spyOn(process, "exit") + .mockImplementation(((code?: number) => { + throw new Error(`exit:${code}`); + }) as never); + const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true); + + try { + expect(() => parseArgs(["node", "compose", "deploy", "--nope"])).toThrow("exit:1"); + } finally { + exitSpy.mockRestore(); + stderrSpy.mockRestore(); + } + }); + + it("rejects passthrough arguments for commands that do not accept them", () => { + expect(() => parseArgs(["node", "compose", "validate", "--", "--ast"])).toThrow( + "Only 'compose deploy' and 'compose test' accept passthrough arguments.", + ); + expect(() => parseArgs(["node", "compose", "init", "example", "--", "--foo"])).toThrow( + "Only 'compose deploy' and 'compose test' accept passthrough arguments.", + ); + }); + + it("redacts sensitive passthrough values in rejection errors", () => { + let message = ""; + try { + parseArgs([ + "node", + "compose", + "validate", + "--", + "--private-key", + "0xsecret", + "--mnemonic=test test test", + ]); + } catch (error) { + message = (error as Error).message; + } + + expect(message).toContain("--private-key [REDACTED]"); + expect(message).toContain("--mnemonic=[REDACTED]"); + expect(message).not.toContain("0xsecret"); + expect(message).not.toContain("test test test"); + }); +}); diff --git a/cli/test/modules/accounts/module.test.ts b/cli/test/modules/accounts/module.test.ts new file mode 100644 index 00000000..d751ee6b --- /dev/null +++ b/cli/test/modules/accounts/module.test.ts @@ -0,0 +1,63 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; +import { Context } from "../../../src/context/context"; +import type { ComposeContext, ModuleState } from "../../../src/context/types"; +import { AccountModule } from "../../../src/modules/accounts/module"; +import type { AccountActionResult } from "../../../src/modules/accounts/types"; + +let projectRoot: string; +let ctx: ComposeContext; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-account-module-")); + ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + vi.spyOn(console, "log").mockImplementation(() => {}); + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + accounts: { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "deployer" }, + }, + }, + chains: { + local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" }, + }, + }), "utf8"); +}); + +afterEach(async () => { + vi.restoreAllMocks(); + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +describe("AccountModule", () => { + it("checks an account through the pipeline-provided adapter", async () => { + const listSignerAddresses = vi.fn(async () => [ + "0x00000000000000000000000000000000000000A1", + ]); + const adapter = { listSignerAddresses } as unknown as IFrameworkAdapter; + ctx.param.action = "check"; + ctx.param.accountName = "deployer"; + + const project = await AccountModule.loadProject(ctx); + await AccountModule.execute(ctx, project, { framework: "foundry", adapter }); + + const state = ctx.state.account as ModuleState; + expect(state.result).toEqual({ + action: "check", + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + chainKey: "local", + }); + expect(listSignerAddresses).toHaveBeenCalledWith(expect.objectContaining({ + projectRoot, + chainKey: "local", + accountName: "deployer", + })); + }); +}); diff --git a/cli/test/modules/bytecodeValidation/module.test.ts b/cli/test/modules/bytecodeValidation/module.test.ts index 9bce9d5a..e8cfb8e6 100644 --- a/cli/test/modules/bytecodeValidation/module.test.ts +++ b/cli/test/modules/bytecodeValidation/module.test.ts @@ -55,6 +55,58 @@ describe("BytecodeValidationModule", () => { expect(result.state.bytecodeDeploymentValidation.success).toBe(true); }); + it("records the selected instance and defaults to the default instance", async () => { + const { ctx, rpc, diamondAdapter, validator } = setup(); + const defaultResult = await BytecodeValidationModule.validateDeployment( + ctx, + { rpc, diamond: diamondAdapter, validator }, + ); + expect(defaultResult.state.bytecodeDeploymentValidation.result) + .toMatchObject({ instance: "default" }); + + const staging = Context.create(); + staging.param = { ...ctx.param, instance: "staging" }; + const stagingResult = await BytecodeValidationModule.validateDeployment( + staging, + { rpc, diamond: diamondAdapter, validator }, + ); + expect(stagingResult.state.bytecodeDeploymentValidation.result) + .toMatchObject({ instance: "staging" }); + }); + + it("includes the instance in merged failure records", () => { + const ctx = Context.create(); + const failed = Context.create(); + failed.param = { + diamondName: "ExampleDiamond", + chainKey: "local", + instance: "staging", + diamondAddress: diamond, + }; + failed.state.bytecodeDeploymentValidation = { + success: false, + result: null, + error: { + code: "BYTECODE_FACET_VALIDATION_FAILED", + message: "RPC unavailable", + nativeError: null, + }, + }; + + const merged = BytecodeValidationModule.mergeDeployments(ctx, [failed]); + expect(merged.state.bytecodeValidation).toMatchObject({ + success: false, + result: { + failures: [{ + diamondName: "ExampleDiamond", + chainKey: "local", + instance: "staging", + message: "RPC unavailable", + }], + }, + }); + }); + it("reports introspection errors without blocking validation", async () => { const { ctx, rpc, diamondAdapter, validator } = setup(); vi.mocked(diamondAdapter.facets).mockRejectedValue(new Error("packed selectors are invalid")); diff --git a/cli/test/modules/deployExecution/ignitionJournal.test.ts b/cli/test/modules/deployExecution/ignitionJournal.test.ts new file mode 100644 index 00000000..07b451c1 --- /dev/null +++ b/cli/test/modules/deployExecution/ignitionJournal.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "vitest"; +import { parseIgnitionJournalTransactionHash } from "../../../src/modules/deployExecution/ignitionJournal"; + +const DIAMOND_FUTURE = "ComposeDeploy#Diamond"; +const DIAMOND_TX = `0x${"ab".repeat(32)}`; + +describe("parseIgnitionJournalTransactionHash", () => { + it("returns the successful confirmation hash for the exact future ID", () => { + const journal = [ + JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: "ComposeDeploy#Facet_0", + hash: `0x${"11".repeat(32)}`, + receipt: { status: "SUCCESS" }, + }), + JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: DIAMOND_FUTURE, + hash: `0x${"22".repeat(32)}`, + receipt: { status: "FAILURE" }, + }), + JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: DIAMOND_FUTURE, + hash: DIAMOND_TX, + receipt: { status: "SUCCESS" }, + }), + ].join("\n"); + + expect(parseIgnitionJournalTransactionHash(journal, DIAMOND_FUTURE)).toBe(DIAMOND_TX); + }); + + it("rejects a journal without a successful transaction for the future", () => { + const journal = JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: "ComposeDeploy#NotDiamond", + hash: DIAMOND_TX, + receipt: { status: "SUCCESS" }, + }); + + expect(() => parseIgnitionJournalTransactionHash(journal, DIAMOND_FUTURE)).toThrow( + "no successful transaction for future 'ComposeDeploy#Diamond'", + ); + }); + + it("rejects invalid journal JSON and malformed transaction hashes", () => { + expect(() => parseIgnitionJournalTransactionHash("{not-json", DIAMOND_FUTURE)).toThrow( + "Invalid JSON in Hardhat Ignition journal", + ); + const invalidHash = JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: DIAMOND_FUTURE, + hash: "0x1234", + receipt: { status: "SUCCESS" }, + }); + expect(() => parseIgnitionJournalTransactionHash(invalidHash, DIAMOND_FUTURE)).toThrow( + "invalid transaction hash", + ); + }); +}); diff --git a/cli/test/modules/deployExecution/module.test.ts b/cli/test/modules/deployExecution/module.test.ts new file mode 100644 index 00000000..9c927308 --- /dev/null +++ b/cli/test/modules/deployExecution/module.test.ts @@ -0,0 +1,534 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import type { Hex } from "viem"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import type { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; +import type { BroadcastTransaction } from "../../../src/adapters/IFrameworkAdapter/types"; +import { Context } from "../../../src/context/context"; +import type { ModuleState } from "../../../src/context/types"; +import { + DeployExecutionModule, +} from "../../../src/modules/deployExecution/module"; +import type { DeployExecutionResult } from "../../../src/modules/deployExecution/types"; +import type { DeployPlan } from "../../../src/modules/deployPlan/types"; +import { getIgnitionDeploymentId, HARDHAT_IGNITION_MODULE_ID } from "../../../src/modules/deployScript/model"; + +const PLAN_HASH = `0x${"cd".repeat(32)}` as Hex; +const DIAMOND = "0x00000000000000000000000000000000000000aa"; +const FACET_A = "0x00000000000000000000000000000000000000b1"; +const FACET_B = "0x00000000000000000000000000000000000000b2"; +const DIAMOND_TX = `0x${"33".repeat(32)}` as Hex; +const BROADCAST_DIAMOND_TX = `0x${"44".repeat(32)}`; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-deploy-exec-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +function deployPlan(): DeployPlan { + return { + mode: "fresh", + framework: "foundry", + projectRoot, + composeJsonPath: path.join(projectRoot, "compose.json"), + diamondName: "CounterDiamond", + diamond: { + contractName: "Diamond", + sourcePath: path.join(projectRoot, "src", "Diamond.sol"), + importSpec: "../src/Diamond.sol", + }, + instance: "default", + chain: { chainKey: "local", rpcUrl: "http://127.0.0.1:8545", chainId: 31337 }, + rpcUrlOverridden: false, + account: null, + facets: [ + { + name: "AlphaFacet", + contractName: "AlphaFacet", + sourcePath: path.join(projectRoot, "src", "AlphaFacet.sol"), + importSpec: "../src/AlphaFacet.sol", + }, + { + name: "BetaFacet", + contractName: "BetaFacet", + sourcePath: path.join(projectRoot, "src", "BetaFacet.sol"), + importSpec: "../src/BetaFacet.sol", + }, + ], + existing: null, + diff: null, + upgradeable: false, + planHash: PLAN_HASH, + }; +} + +function hardhatPlan(): DeployPlan { + return { ...deployPlan(), framework: "hardhat" }; +} + +function stubAdapter(overrides: Partial = {}): IFrameworkAdapter { + return { + getContractSourceRoot: () => path.join(projectRoot, "src"), + getScriptRoot: () => path.join(projectRoot, "script"), + getTestRoot: () => path.join(projectRoot, "test"), + getArtifactDir: () => path.join(projectRoot, "out"), + compile: async () => {}, + compileAst: async () => [], + resolveSoliditySourcePath: async () => "", + initProject: async () => {}, + writeConfig: async () => {}, + supportsAccountImport: false, + readAccountAddress: async () => ({ address: null, exists: false, requiresUnlock: false }), + resolveAccountAddress: async () => ({ address: null, exists: false, requiresUnlock: false }), + listSignerAddresses: async () => [], + resolveDeploySigner: async ({ account }) => account ? account.address as Hex : null, + importAccount: async () => null, + assertSupportedProject: () => {}, + getDeployToolbox: async () => null, + getManagedDeployScriptPath: () => path.join(projectRoot, "script", "ComposeDeploy.s.sol"), + getManagedDeployRunnerPath: () => null, + getManagedDeployResultPath: () => path.join(projectRoot, ".compose", "hardhat", "deploy-result.json"), + createDeployCommand: () => ({ command: process.execPath, args: ["-e", ""] }), + createTestCommand: () => ({ command: process.execPath, args: ["-e", ""] }), + readDeployedBytecode: async () => undefined, + readBroadcastTransactions: async () => [], + ...overrides, + }; +} + +function validResult(): Record { + return { + mode: "deploy", + planHash: PLAN_HASH, + framework: "foundry", + chainKey: "local", + chainId: 31337, + instance: "default", + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + transactions: { diamond: DIAMOND_TX }, + }; +} + +async function adapterWritingResult(result: Record): Promise { + const payloadPath = path.join(projectRoot, "script", "expected-result.json"); + await fs.mkdir(path.dirname(payloadPath), { recursive: true }); + await fs.writeFile(payloadPath, JSON.stringify(result), "utf8"); + + const script = + 'const fs = require("fs"); fs.mkdirSync(".compose/hardhat", { recursive: true });' + + `fs.copyFileSync(${JSON.stringify(payloadPath)}, ".compose/hardhat/deploy-result.json");`; + return stubAdapter({ + createDeployCommand: () => ({ command: process.execPath, args: ["-e", script] }), + }); +} + +function broadcastAdapter(transactions: BroadcastTransaction[]): IFrameworkAdapter { + return stubAdapter({ readBroadcastTransactions: async () => transactions }); +} + +async function execute( + adapter: IFrameworkAdapter, + plan = deployPlan(), + runnerPath: string | null = null, + passthrough?: unknown, +): Promise<{ + result: DeployExecutionResult | null; + success: boolean; + message: string | null; +}> { + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + if (passthrough !== undefined) ctx.param.passthrough = passthrough; + let throwMessage: string | null = null; + try { + await DeployExecutionModule.execute(ctx, plan, "/tmp/script.s.sol", adapter, runnerPath); + } catch (error) { + throwMessage = (error as Error).message; + } + const state = ctx.state.deployExecution as ModuleState; + return { + result: state?.result ?? null, + success: state?.success ?? false, + message: state?.error?.message ?? throwMessage, + }; +} + +describe("DeployExecutionModule.execute", () => { + it("accepts a result file that matches the plan", async () => { + const adapter = await adapterWritingResult(validResult()); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(true); + expect(outcome.result).toEqual({ + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + transactions: { diamond: DIAMOND_TX }, + }); + }); + + it("passes adapter environment overrides to the framework command", async () => { + const rpcUrl = "https://rpc.example.test/v1/private-token"; + const resultPath = path.join(projectRoot, ".compose", "hardhat", "deploy-result.json"); + const observedPath = path.join(projectRoot, "observed-rpc-url.txt"); + const script = [ + 'const fs = require("node:fs");', + 'fs.mkdirSync(".compose/hardhat", { recursive: true });', + `fs.writeFileSync(${JSON.stringify(resultPath)}, ${JSON.stringify(JSON.stringify(validResult()))});`, + `fs.writeFileSync(${JSON.stringify(observedPath)}, process.env.COMPOSE_DEPLOY_RPC_URL ?? "");`, + ].join("\n"); + const adapter = stubAdapter({ + createDeployCommand: () => ({ + command: process.execPath, + args: ["-e", script], + env: { COMPOSE_DEPLOY_RPC_URL: rpcUrl }, + }), + }); + + const outcome = await execute(adapter); + + expect(outcome.success).toBe(true); + expect(await fs.readFile(observedPath, "utf8")).toBe(rpcUrl); + }); + + it("does not manage a capture file for frameworks without one", async () => { + const adapter = stubAdapter({ + getManagedDeployResultPath: () => null, + readBroadcastTransactions: async () => [ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}` }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}` }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX }, + ], + }); + + const outcome = await execute(adapter); + + expect(outcome.success).toBe(true); + await expect(fs.access(path.join(projectRoot, ".compose"))).rejects.toThrow(); + }); + + it("rejects a result written by a different plan", async () => { + const adapter = await adapterWritingResult({ + ...validResult(), + planHash: `0x${"ee".repeat(32)}`, + }); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("different plan"); + }); + + it("rejects a result whose facet set differs from the plan", async () => { + const adapter = await adapterWritingResult({ + ...validResult(), + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B, ExtraFacet: DIAMOND }, + }); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("do not match the plan"); + expect(outcome.message).toContain("ExtraFacet"); + }); + + it("records and verifies the selected Hardhat account address", async () => { + const accountAddress = "0x00000000000000000000000000000000000000a1"; + const plan = { + ...deployPlan(), + framework: "hardhat" as const, + account: { alias: "deployer", address: accountAddress as Hex }, + }; + const ignitionDeploymentId = getIgnitionDeploymentId(plan); + const journalPath = path.join(projectRoot, "ignition", "deployments", ignitionDeploymentId, "journal.jsonl"); + await fs.mkdir(path.dirname(journalPath), { recursive: true }); + await fs.writeFile(journalPath, JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: `${HARDHAT_IGNITION_MODULE_ID}#Diamond`, + hash: DIAMOND_TX, + receipt: { status: "SUCCESS" }, + }), "utf8"); + const result = { + ...validResult(), + framework: "hardhat", + deployer: accountAddress, + ignitionDeploymentId, + }; + + const outcome = await execute(await adapterWritingResult(result), plan); + + expect(outcome.success).toBe(true); + expect(outcome.result?.deployer).toBe(accountAddress); + }); + + it("takes the Hardhat diamond transaction hash from the matching successful Ignition journal future", async () => { + const plan = hardhatPlan(); + const runnerPath = path.join(projectRoot, ".compose", "hardhat", "ignition-runner.ts"); + await fs.mkdir(path.dirname(runnerPath), { recursive: true }); + await fs.writeFile(runnerPath, "transient", "utf8"); + const ignitionDeploymentId = getIgnitionDeploymentId(plan); + const journalPath = path.join( + projectRoot, + "ignition", + "deployments", + ignitionDeploymentId, + "journal.jsonl", + ); + await fs.mkdir(path.dirname(journalPath), { recursive: true }); + await fs.writeFile(journalPath, [ + JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: `${HARDHAT_IGNITION_MODULE_ID}#Facet_0`, + hash: `0x${"11".repeat(32)}`, + receipt: { status: "SUCCESS" }, + }), + JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: `${HARDHAT_IGNITION_MODULE_ID}#Diamond`, + hash: DIAMOND_TX, + receipt: { status: "SUCCESS" }, + }), + "", + ].join("\n"), "utf8"); + + const result = { + ...validResult(), + framework: "hardhat", + ignitionDeploymentId, + transactions: { diamond: BROADCAST_DIAMOND_TX }, + }; + const outcome = await execute(await adapterWritingResult(result), plan, runnerPath); + + expect(outcome.success).toBe(true); + expect(outcome.result).toEqual({ + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + ignitionDeploymentId, + transactions: { diamond: DIAMOND_TX }, + }); + await expect(fs.access(runnerPath)).rejects.toThrow(); + }); + + it("rejects a Hardhat result associated with another Ignition deployment ID", async () => { + const outcome = await execute(await adapterWritingResult({ + ...validResult(), + framework: "hardhat", + ignitionDeploymentId: "compose-unrelated-deployment", + }), hardhatPlan()); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("unexpected Hardhat Ignition deployment ID"); + }); + + it("validates a Hardhat framework-default deployment against the resolved default signer", async () => { + const defaultSigner = "0x00000000000000000000000000000000000000a1" as Hex; + const plan = hardhatPlan(); + const ignitionDeploymentId = getIgnitionDeploymentId(plan, defaultSigner); + const journalPath = path.join( + projectRoot, + "ignition", + "deployments", + ignitionDeploymentId, + "journal.jsonl", + ); + await fs.mkdir(path.dirname(journalPath), { recursive: true }); + await fs.writeFile(journalPath, JSON.stringify({ + type: "TRANSACTION_CONFIRM", + futureId: `${HARDHAT_IGNITION_MODULE_ID}#Diamond`, + hash: DIAMOND_TX, + receipt: { status: "SUCCESS" }, + }), "utf8"); + + const base = await adapterWritingResult({ + ...validResult(), + framework: "hardhat", + deployer: defaultSigner, + ignitionDeploymentId, + }); + const adapter = { + ...base, + resolveDeploySigner: async () => defaultSigner, + }; + + const outcome = await execute(adapter, plan); + + expect(outcome.success).toBe(true); + expect(outcome.result?.deployer).toBe(defaultSigner); + expect(outcome.result?.ignitionDeploymentId).toBe(ignitionDeploymentId); + }); + + it("rejects a Hardhat framework-default deployment from another default signer", async () => { + const expectedSigner = "0x00000000000000000000000000000000000000a1" as Hex; + const actualSigner = "0x00000000000000000000000000000000000000a2"; + const plan = hardhatPlan(); + const ignitionDeploymentId = getIgnitionDeploymentId(plan, expectedSigner); + + const base = await adapterWritingResult({ + ...validResult(), + framework: "hardhat", + deployer: actualSigner, + ignitionDeploymentId, + }); + const adapter = { + ...base, + resolveDeploySigner: async () => expectedSigner, + }; + + const outcome = await execute(adapter, plan); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("framework default signer"); + }); + + it("rejects a deployment from a different account than the Compose alias", async () => { + const plan = { + ...deployPlan(), + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1" as Hex, + }, + }; + + const outcome = await execute( + await adapterWritingResult({ ...validResult(), deployer: "0x00000000000000000000000000000000000000a2" }), + plan, + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("expected Compose account 'deployer'"); + }); + + it("rejects a result targeting another chain", async () => { + const adapter = await adapterWritingResult({ ...validResult(), chainId: 1 }); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("chain id"); + }); + + it("fails when neither a result file nor broadcast deployments exist", async () => { + const outcome = await execute(stubAdapter()); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("did not report a deployment for facet 'AlphaFacet'"); + }); + + it("derives the deployment from broadcast transactions when no result file exists", async () => { + const adapter = broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}` }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}` }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX }, + ]); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(true); + expect(outcome.result).toEqual({ + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + transactions: { diamond: BROADCAST_DIAMOND_TX }, + }); + }); + + it("verifies the selected Compose account against the Foundry broadcast sender", async () => { + const accountAddress = "0x00000000000000000000000000000000000000a1"; + const plan = { + ...deployPlan(), + account: { alias: "deployer", address: accountAddress as Hex, foundryAccount: "deployer" }, + }; + const adapter = broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}`, from: accountAddress }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}`, from: accountAddress }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX, from: accountAddress }, + ]); + + const outcome = await execute(adapter, plan); + + expect(outcome.success).toBe(true); + expect(outcome.result?.deployer).toBe(accountAddress); + }); + + it("rejects a Foundry broadcast from a different Compose account", async () => { + const plan = { + ...deployPlan(), + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1" as Hex, + foundryAccount: "deployer", + }, + }; + const adapter = broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}` }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}` }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX, from: "0x00000000000000000000000000000000000000a2" }, + ]); + + const outcome = await execute(adapter, plan); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("does not match Compose account 'deployer'"); + }); + + it("validates a Foundry framework-default sender resolved by the adapter", async () => { + const sender = "0x00000000000000000000000000000000000000a1"; + const adapter = { + ...broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}`, from: sender }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}`, from: sender }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX, from: sender }, + ]), + resolveDeploySigner: async () => sender as Hex, + }; + + const outcome = await execute(adapter); + + expect(outcome.success).toBe(true); + expect(outcome.result?.deployer).toBe(sender); + }); + + it("rejects a Foundry framework-default broadcast from another sender", async () => { + const expectedSender = "0x00000000000000000000000000000000000000a1"; + const adapter = { + ...broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}` }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}` }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX, from: "0x00000000000000000000000000000000000000a2" }, + ]), + resolveDeploySigner: async () => expectedSender as Hex, + }; + + const outcome = await execute(adapter); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("does not match the framework default signer"); + }); + + it("falls back to broadcast transactions for the diamond hash", async () => { + const adapter = await adapterWritingResult({ ...validResult(), transactions: {} }); + const withBroadcast = stubAdapter({ + createDeployCommand: adapter.createDeployCommand, + readBroadcastTransactions: async () => [ + { contractName: "Diamond", contractAddress: DIAMOND, txHash: BROADCAST_DIAMOND_TX }, + ], + }); + const outcome = await execute(withBroadcast); + + expect(outcome.success).toBe(true); + expect(outcome.result?.transactions.diamond).toBe(BROADCAST_DIAMOND_TX); + }); + + it("fails when no diamond deployment transaction is recorded", async () => { + const adapter = broadcastAdapter([ + { contractName: "AlphaFacet", contractAddress: FACET_A, txHash: `0x${"01".repeat(32)}` }, + { contractName: "BetaFacet", contractAddress: FACET_B, txHash: `0x${"02".repeat(32)}` }, + { contractName: "Diamond", contractAddress: DIAMOND, txHash: null }, + ]); + const outcome = await execute(adapter); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("No diamond deployment transaction was recorded"); + }); +}); diff --git a/cli/test/modules/deployGeneration/fixtures/expected/Deploy.s.sol b/cli/test/modules/deployGeneration/fixtures/expected/Deploy.s.sol deleted file mode 100644 index f1ee799a..00000000 --- a/cli/test/modules/deployGeneration/fixtures/expected/Deploy.s.sol +++ /dev/null @@ -1,78 +0,0 @@ -// SPDX-License-Identifier: MIT -pragma solidity ^0.8.30; - -/* Compose - * https://compose.diamonds - */ - -import {Script} from "forge-std/Script.sol"; -import {console} from "forge-std/console.sol"; -import {Diamond} from "../src/Diamond.sol"; -import {ERC20DataFacet} from "@perfect-abstractions/compose/token/ERC20/Data/ERC20DataFacet.sol"; -import {ERC20ApproveFacet} from "@perfect-abstractions/compose/token/ERC20/Approve/ERC20ApproveFacet.sol"; -import {ERC20TransferFacet} from "@perfect-abstractions/compose/token/ERC20/Transfer/ERC20TransferFacet.sol"; -import {ERC20BurnFacet} from "@perfect-abstractions/compose/token/ERC20/Burn/ERC20BurnFacet.sol"; -import {ERC20MetadataFacet} from "@perfect-abstractions/compose/token/ERC20/Metadata/ERC20MetadataFacet.sol"; -import {ERC20PermitFacet} from "@perfect-abstractions/compose/token/ERC20/Permit/ERC20PermitFacet.sol"; -import {DiamondInspectFacet} from "@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol"; -import {OwnerDataFacet} from "@perfect-abstractions/compose/access/Owner/Data/OwnerDataFacet.sol"; -import {OwnerTransferFacet} from "@perfect-abstractions/compose/access/Owner/Transfer/OwnerTransferFacet.sol"; -import {AccessControlDataFacet} from "@perfect-abstractions/compose/access/AccessControl/Data/AccessControlDataFacet.sol"; -import {AccessControlGrantFacet} from "@perfect-abstractions/compose/access/AccessControl/Grant/AccessControlGrantFacet.sol"; -import {AccessControlRevokeFacet} from "@perfect-abstractions/compose/access/AccessControl/Revoke/AccessControlRevokeFacet.sol"; -import {DiamondUpgradeFacet} from "@perfect-abstractions/compose/diamond/DiamondUpgradeFacet.sol"; -import {OwnerRenounceFacet} from "@perfect-abstractions/compose/access/Owner/Renounce/OwnerRenounceFacet.sol"; -import {AccessControlGrantBatchFacet} from "@perfect-abstractions/compose/access/AccessControl/Batch/Grant/AccessControlGrantBatchFacet.sol"; -import {AccessControlRevokeBatchFacet} from "@perfect-abstractions/compose/access/AccessControl/Batch/Revoke/AccessControlRevokeBatchFacet.sol"; - -contract DeployScript is Script { - function setUp() public {} - - function run() public returns (Diamond diamond) { - vm.startBroadcast(); - - address[] memory facets = new address[](16); - - /* Base facet generation. */ - facets[0] = address(new ERC20DataFacet()); - console.log("ERC20DataFacet:", facets[0]); - facets[1] = address(new ERC20ApproveFacet()); - console.log("ERC20ApproveFacet:", facets[1]); - facets[2] = address(new ERC20TransferFacet()); - console.log("ERC20TransferFacet:", facets[2]); - facets[3] = address(new ERC20BurnFacet()); - console.log("ERC20BurnFacet:", facets[3]); - facets[4] = address(new ERC20MetadataFacet()); - console.log("ERC20MetadataFacet:", facets[4]); - facets[5] = address(new ERC20PermitFacet()); - console.log("ERC20PermitFacet:", facets[5]); - - /* Library facet generation. */ - facets[6] = address(new DiamondInspectFacet()); - console.log("DiamondInspectFacet:", facets[6]); - facets[7] = address(new OwnerDataFacet()); - console.log("OwnerDataFacet:", facets[7]); - facets[8] = address(new OwnerTransferFacet()); - console.log("OwnerTransferFacet:", facets[8]); - facets[9] = address(new AccessControlDataFacet()); - console.log("AccessControlDataFacet:", facets[9]); - facets[10] = address(new AccessControlGrantFacet()); - console.log("AccessControlGrantFacet:", facets[10]); - facets[11] = address(new AccessControlRevokeFacet()); - console.log("AccessControlRevokeFacet:", facets[11]); - facets[12] = address(new DiamondUpgradeFacet()); - console.log("DiamondUpgradeFacet:", facets[12]); - facets[13] = address(new OwnerRenounceFacet()); - console.log("OwnerRenounceFacet:", facets[13]); - facets[14] = address(new AccessControlGrantBatchFacet()); - console.log("AccessControlGrantBatchFacet:", facets[14]); - facets[15] = address(new AccessControlRevokeBatchFacet()); - console.log("AccessControlRevokeBatchFacet:", facets[15]); - - /* Define diamond proxy. */ - diamond = new Diamond(facets); - console.log("Diamond:", address(diamond)); - - vm.stopBroadcast(); - } -} diff --git a/cli/test/modules/deployGeneration/module.test.ts b/cli/test/modules/deployGeneration/module.test.ts deleted file mode 100644 index 7ba8bd67..00000000 --- a/cli/test/modules/deployGeneration/module.test.ts +++ /dev/null @@ -1,55 +0,0 @@ -import fs from "node:fs/promises"; -import path from "node:path"; -import { describe, expect, it } from "vitest"; -import { ModuleState } from "../../../src/context/types"; -import { DeployGenerationModule } from "../../../src/modules/deployGeneration/module"; -import { createDeployGenerationHarness } from "./harness"; - -type GeneratedDeployScriptState = { - outputPath: string; - facets: { facetName: string }[]; -}; - -/** - * Tests DeployGenerationModule against a full ERC-20 Foundry deploy script snapshot. - * - * It covers ERC-20 extensions, DiamondUpgrade, Owner with renounce, and - * AccessControl with its batch grant and revoke extensions. - */ -describe("DeployGenerationModule", () => { - it("generates a Foundry deploy script from selected facets", async () => { - const harness = await createDeployGenerationHarness(); - - try { - const result = await DeployGenerationModule.generateDeployScript(harness.ctx, harness.scriptRoot); - const outputPath = path.join(harness.scriptRoot, "Deploy.s.sol"); - const generated = await fs.readFile(outputPath, "utf8"); - const expected = await fs.readFile(path.join(__dirname, "fixtures", "expected", "Deploy.s.sol"), "utf8"); - const state = result.state.generateDeployScript as ModuleState; - - expect(state.success).toBe(true); - expect(state.result?.outputPath).toBe(outputPath); - expect(state.result?.facets.map((facet) => facet.facetName)).toEqual([ - "ERC20DataFacet", - "ERC20ApproveFacet", - "ERC20TransferFacet", - "ERC20BurnFacet", - "ERC20MetadataFacet", - "ERC20PermitFacet", - "DiamondInspectFacet", - "OwnerDataFacet", - "OwnerTransferFacet", - "AccessControlDataFacet", - "AccessControlGrantFacet", - "AccessControlRevokeFacet", - "DiamondUpgradeFacet", - "OwnerRenounceFacet", - "AccessControlGrantBatchFacet", - "AccessControlRevokeBatchFacet", - ]); - expect(generated).toBe(expected); - } finally { - await harness.cleanup(); - } - }); -}); diff --git a/cli/test/modules/deployGeneration/renderers.test.ts b/cli/test/modules/deployGeneration/renderers.test.ts deleted file mode 100644 index d08d0dc4..00000000 --- a/cli/test/modules/deployGeneration/renderers.test.ts +++ /dev/null @@ -1,66 +0,0 @@ -import { describe, expect, it } from "vitest"; -import { - renderHardhatEthersDeployScript, - renderHardhatViemDeployScript, -} from "../../../src/modules/deployGeneration/renderers"; -import type { DeployGenerationModel } from "../../../src/modules/deployGeneration/types"; - -const model: DeployGenerationModel = { - outputPath: "scripts/deploy.ts", - facets: [ - { - facetName: "LibraryFirstFacet", - contractName: "LibraryFirstFacet", - importPath: "facets/LibraryFirstFacet.sol", - source: "library-required", - origin: "local", - group: "library", - }, - { - facetName: "BaseFirstFacet", - contractName: "BaseFirstFacet", - importPath: "facets/BaseFirstFacet.sol", - source: "base-required", - origin: "local", - group: "base", - }, - { - facetName: "BaseSecondFacet", - contractName: "BaseSecondFacet", - importPath: "facets/BaseSecondFacet.sol", - source: "extension", - origin: "local", - group: "base", - }, - ], -}; - -function expectBaseSectionsBeforeLibraries(source: string): void { - const baseFirst = source.indexOf("const baseFirstFacet ="); - const baseSecond = source.indexOf("const baseSecondFacet ="); - const library = source.indexOf("const libraryFirstFacet ="); - - expect(baseFirst).toBeGreaterThanOrEqual(0); - expect(baseSecond).toBeGreaterThan(baseFirst); - expect(library).toBeGreaterThan(baseSecond); -} - -describe("Hardhat deploy renderers", () => { - it("renders ethers deployment and logging after grouping base facets first", async () => { - const source = await renderHardhatEthersDeployScript(model); - - expectBaseSectionsBeforeLibraries(source); - expect(source).toContain("await baseFirstFacet.waitForDeployment();"); - expect(source).toContain('console.log("BaseFirstFacet:", await baseFirstFacet.getAddress());'); - expect(source).toContain("facets.push(await baseFirstFacet.getAddress());"); - }); - - it("renders viem deployment and address access after grouping base facets first", async () => { - const source = await renderHardhatViemDeployScript(model); - - expectBaseSectionsBeforeLibraries(source); - expect(source).toContain('console.log("BaseFirstFacet:", baseFirstFacet.address);'); - expect(source).toContain("facets.push(baseFirstFacet.address);"); - expect(source).not.toContain("waitForDeployment"); - }); -}); diff --git a/cli/test/modules/deployPlan/harness.ts b/cli/test/modules/deployPlan/harness.ts new file mode 100644 index 00000000..72a2a575 --- /dev/null +++ b/cli/test/modules/deployPlan/harness.ts @@ -0,0 +1,143 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { Context } from "../../../src/context/context"; +import type { ComposeContext } from "../../../src/context/types"; + +export type DeployProjectHarness = { + ctx: ComposeContext; + projectRoot: string; + scriptRoot: string; + writeComposeJson( + diamondFacets?: Record, + options?: { framework?: "foundry" | "hardhat"; diamondContract?: string }, + ): Promise; + writeLock(deployments: Record): Promise; + cleanup(): Promise; +}; + +export const RPC_URL = "http://127.0.0.1:8545"; +export const CHAIN_ID = 31337; + +export const DEFAULT_FACETS = { + DiamondInspectFacet: { + source: "package", + contract: "DiamondInspectFacet", + package: "@perfect-abstractions/compose", + }, + CounterFacet: { + source: "local", + contract: "src/CounterFacet.sol:CounterFacet", + }, +}; + +const DIAMOND_ADDRESS = "0x00000000000000000000000000000000000000aa"; +const FACET_ADDRESS_A = "0x00000000000000000000000000000000000000b1"; +const FACET_ADDRESS_B = "0x00000000000000000000000000000000000000b2"; + +const FIXTURE_FILES: Array<[string, string]> = [ + ["src/Diamond.sol", "// fixture\ncontract Diamond {}\n"], + ["src/CounterFacet.sol", "// fixture\ncontract CounterFacet {}\n"], + ["src/DiamondUpgradeFacet.sol", "// fixture\ncontract DiamondUpgradeFacet {}\n"], + [ + "lib/Compose/src/diamond/DiamondInspectFacet.sol", + "// fixture\ncontract DiamondInspectFacet {}\n", + ], +]; + +/** Builds a deployment record with valid addresses for lock fixtures. */ +export function deploymentRecord(facets: Record): Record { + return { + diamond: DIAMOND_ADDRESS, + facets, + facetHash: `0x${"11".repeat(32)}`, + lastSync: "2026-01-01T00:00:00.000Z", + txHash: `0x${"22".repeat(32)}`, + }; +} + +/** Facet addresses matching {@link DEFAULT_FACETS}, for matching lock records. */ +export const DEFAULT_FACET_ADDRESSES = { + DiamondInspectFacet: FACET_ADDRESS_A, + CounterFacet: FACET_ADDRESS_B, +}; + +/** + * Creates a temp Compose project fixture for deploy plan and pipeline tests. + * + * The fixture mirrors the layout the CLI resolves against: a local facet, a + * Compose package facet under `lib/Compose/src`, and compose.json with a + * single diamond and the `local` chain pointing at {@link RPC_URL}. + */ +export async function createDeployProjectHarness(): Promise { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-deploy-")); + const scriptRoot = path.join(projectRoot, "script"); + await fs.mkdir(scriptRoot, { recursive: true }); + + await Promise.all( + FIXTURE_FILES.map(async ([relativePath, content]) => { + const filePath = path.join(projectRoot, relativePath); + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, content, "utf8"); + }), + ); + + const ctx = Context.create(); + ctx.param.command = "deploy"; + ctx.param.projectRoot = projectRoot; + + const harness: DeployProjectHarness = { + ctx, + projectRoot, + scriptRoot, + async writeComposeJson(diamondFacets = DEFAULT_FACETS, options = {}) { + const framework = options.framework ?? "foundry"; + await fs.writeFile( + path.join(projectRoot, "compose.json"), + JSON.stringify( + { + project: "fixture", + compose: "0.3.0", + framework, + diamonds: { + CounterDiamond: { + contract: options.diamondContract ?? "src/Diamond.sol:Diamond", + facets: diamondFacets, + }, + }, + chains: { + local: { rpc: RPC_URL, chainId: CHAIN_ID }, + }, + }, + null, + 2, + ), + "utf8", + ); + if (framework === "hardhat") { + await fs.writeFile( + path.join(projectRoot, "package.json"), + JSON.stringify({ + type: "module", + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0", + }, + }, null, 2), + "utf8", + ); + } + }, + async writeLock(deployments) { + await fs.writeFile( + path.join(projectRoot, "compose.lock"), + JSON.stringify({ compose: "0.3.0", deployments }, null, 2), + "utf8", + ); + }, + cleanup: () => fs.rm(projectRoot, { recursive: true, force: true }), + }; + + await harness.writeComposeJson(); + return harness; +} diff --git a/cli/test/modules/deployPlan/hash.test.ts b/cli/test/modules/deployPlan/hash.test.ts new file mode 100644 index 00000000..bd700681 --- /dev/null +++ b/cli/test/modules/deployPlan/hash.test.ts @@ -0,0 +1,182 @@ +import { describe, expect, it } from "vitest"; +import { HashingAdapter } from "../../../src/adapters/IHashingAdapter/adapter"; +import { canonicalPlanJson, computePlanHash, type HashablePlan } from "../../../src/modules/deployPlan/hash"; + +function basePlan(): HashablePlan { + return { + mode: "fresh", + framework: "foundry", + projectRoot: "/tmp/project", + composeJsonPath: "/tmp/project/compose.json", + diamondName: "CounterDiamond", + diamond: { + contractName: "Diamond", + sourcePath: "/tmp/project/src/Diamond.sol", + importSpec: "../src/Diamond.sol", + }, + instance: "default", + chain: { chainKey: "local", rpcUrl: "http://127.0.0.1:8545", chainId: 31337 }, + rpcUrlOverridden: false, + account: null, + facets: [ + { + name: "AlphaFacet", + contractName: "AlphaFacet", + sourcePath: "/tmp/project/src/AlphaFacet.sol", + importSpec: "../src/AlphaFacet.sol", + }, + { + name: "BetaFacet", + contractName: "BetaFacet", + sourcePath: "/tmp/project/src/BetaFacet.sol", + importSpec: "../src/BetaFacet.sol", + }, + ], + existing: null, + diff: null, + upgradeable: false, + }; +} + +describe("canonicalPlanJson", () => { + it("sorts facets by name regardless of registration order", () => { + const plan = basePlan(); + const reordered = { ...plan, facets: [...plan.facets].reverse() }; + expect(canonicalPlanJson(reordered)).toBe(canonicalPlanJson(plan)); + }); + + it("excludes observed state such as the existing record and the diff", () => { + const plan = basePlan(); + const observed: HashablePlan = { + ...plan, + mode: "redeploy", + diff: { added: ["GammaFacet"], removed: ["BetaFacet"] }, + existing: { + diamond: "0x00000000000000000000000000000000000000aa", + facets: { AlphaFacet: "0x00000000000000000000000000000000000000b1" }, + facetHash: `0x${"11".repeat(32)}`, + lastSync: "2026-01-01T00:00:00.000Z", + txHash: `0x${"22".repeat(32)}`, + }, + }; + expect(canonicalPlanJson(observed)).toBe(canonicalPlanJson(plan)); + }); + + it("excludes the RPC endpoint from the deployment identity", () => { + const plan = basePlan(); + const otherEndpoint: HashablePlan = { + ...plan, + chain: { ...plan.chain, rpcUrl: "https://rpc.example.test/v1/private-token" }, + }; + expect(canonicalPlanJson(otherEndpoint)).toBe(canonicalPlanJson(plan)); + }); + + it("is independent of the project's absolute location", () => { + const plan = basePlan(); + const moved: HashablePlan = { + ...plan, + projectRoot: "/srv/other-checkout", + composeJsonPath: "/srv/other-checkout/compose.json", + diamond: { ...plan.diamond, sourcePath: "/srv/other-checkout/src/Diamond.sol" }, + facets: plan.facets.map((facet) => ({ + ...facet, + sourcePath: facet.sourcePath.replace("/tmp/project", "/srv/other-checkout"), + })), + }; + + expect(canonicalPlanJson(moved)).toBe(canonicalPlanJson(plan)); + expect(computePlanHash(moved, HashingAdapter)).toBe(computePlanHash(plan, HashingAdapter)); + }); + + it("is independent of the selected signer", () => { + const plan = basePlan(); + const withAccount: HashablePlan = { + ...plan, + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + }, + }; + + expect(canonicalPlanJson(withAccount)).toBe(canonicalPlanJson(plan)); + expect(computePlanHash(withAccount, HashingAdapter)).toBe(computePlanHash(plan, HashingAdapter)); + }); +}); + +describe("computePlanHash", () => { + it("is stable across facet registration order", () => { + const plan = basePlan(); + const reordered = { ...plan, facets: [...plan.facets].reverse() }; + expect(computePlanHash(reordered, HashingAdapter)).toBe( + computePlanHash(plan, HashingAdapter), + ); + }); + + it("changes when the facet set changes", () => { + const plan = basePlan(); + const added = { + ...plan, + facets: [ + ...plan.facets, + { + name: "GammaFacet", + contractName: "GammaFacet", + sourcePath: "/tmp/project/src/GammaFacet.sol", + importSpec: "../src/GammaFacet.sol", + }, + ], + }; + expect(computePlanHash(added, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + }); + + it("changes when a facet or diamond import path changes", () => { + const plan = basePlan(); + const facetMoved = { + ...plan, + facets: plan.facets.map((facet, index) => ( + index === 0 ? { ...facet, importSpec: "../vendor/AlphaFacet.sol" } : facet + )), + }; + const diamondMoved = { + ...plan, + diamond: { ...plan.diamond, importSpec: "../vendor/Diamond.sol" }, + }; + + expect(computePlanHash(facetMoved, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + expect(computePlanHash(diamondMoved, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + }); + + it("changes when the chain or instance changes", () => { + const plan = basePlan(); + const otherChainId = { ...plan, chain: { ...plan.chain, chainId: 1 } }; + const otherChainKey = { ...plan, chain: { ...plan.chain, chainKey: "sepolia" } }; + const otherInstance = { ...plan, instance: "staging" }; + expect(computePlanHash(otherChainId, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + expect(computePlanHash(otherChainKey, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + expect(computePlanHash(otherInstance, HashingAdapter)).not.toBe( + computePlanHash(plan, HashingAdapter), + ); + }); + + it("is stable when only the RPC endpoint changes", () => { + const plan = basePlan(); + const otherEndpoint = { ...plan, chain: { ...plan.chain, rpcUrl: "https://rpc.example.test" } }; + expect(computePlanHash(otherEndpoint, HashingAdapter)).toBe( + computePlanHash(plan, HashingAdapter), + ); + }); + + it("produces a lowercase keccak256 hex digest", () => { + expect(computePlanHash(basePlan(), HashingAdapter)).toMatch(/^0x[0-9a-f]{64}$/); + }); +}); diff --git a/cli/test/modules/deployPlan/module.test.ts b/cli/test/modules/deployPlan/module.test.ts new file mode 100644 index 00000000..482fc9fc --- /dev/null +++ b/cli/test/modules/deployPlan/module.test.ts @@ -0,0 +1,350 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { foundryAdapter } from "../../../src/adapters/IFrameworkAdapter/foundryAdapter/adapter"; +import { HashingAdapter } from "../../../src/adapters/IHashingAdapter/adapter"; +import type { ModuleState } from "../../../src/context/types"; +import { canonicalPlanJson } from "../../../src/modules/deployPlan/hash"; +import { DeployPlanModule } from "../../../src/modules/deployPlan/module"; +import type { DeployPlan } from "../../../src/modules/deployPlan/types"; +import { getIgnitionDeploymentId } from "../../../src/modules/deployScript/model"; +import { loadValidationProject } from "../../../src/modules/validation/project"; +import { + CHAIN_ID, + createDeployProjectHarness, + DEFAULT_FACETS, + DEFAULT_FACET_ADDRESSES, + deploymentRecord, + RPC_URL, + type DeployProjectHarness, +} from "./harness"; + +let harness: DeployProjectHarness; + +beforeEach(async () => { + harness = await createDeployProjectHarness(); +}); + +afterEach(async () => { + await harness.cleanup(); +}); + +async function resolve(harness: DeployProjectHarness): Promise { + const project = await loadValidationProject(harness.ctx); + const resolved = await DeployPlanModule.resolve(harness.ctx, { + project, + adapter: foundryAdapter, + hashing: HashingAdapter, + }); + const state = resolved.state.deployPlan as ModuleState; + expect(state.success).toBe(true); + return state.result as DeployPlan; +} + +describe("DeployPlanModule.resolve", () => { + it("plans a fresh deployment from compose.json", async () => { + const plan = await resolve(harness); + + expect(plan.mode).toBe("fresh"); + expect(plan.framework).toBe("foundry"); + expect(plan.diamondName).toBe("CounterDiamond"); + expect(plan.diamond).toEqual({ + contractName: "Diamond", + sourcePath: path.join(harness.projectRoot, "src", "Diamond.sol"), + importSpec: "../src/Diamond.sol", + }); + expect(plan.instance).toBe("default"); + expect(plan.chain).toEqual({ chainKey: "local", rpcUrl: RPC_URL, chainId: CHAIN_ID }); + expect(plan.existing).toBeNull(); + expect(plan.diff).toBeNull(); + expect(plan.upgradeable).toBe(false); + expect(plan.planHash).toMatch(/^0x[0-9a-f]{64}$/); + + expect(plan.facets.map((facet) => facet.name)).toEqual([ + "DiamondInspectFacet", + "CounterFacet", + ]); + expect(plan.facets[0]).toMatchObject({ + contractName: "DiamondInspectFacet", + importSpec: "@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol", + sourcePath: path.join( + harness.projectRoot, + "lib", + "Compose", + "src", + "diamond", + "DiamondInspectFacet.sol", + ), + }); + expect(plan.facets[1]).toMatchObject({ + contractName: "CounterFacet", + importSpec: "../src/CounterFacet.sol", + sourcePath: path.join(harness.projectRoot, "src", "CounterFacet.sol"), + }); + }); + + it("produces the same plan for the same project in different checkout roots", async () => { + const other = await createDeployProjectHarness(); + try { + const first = await resolve(harness); + const second = await resolve(other); + + expect(canonicalPlanJson(second)).toBe(canonicalPlanJson(first)); + expect(second.planHash).toBe(first.planHash); + expect(getIgnitionDeploymentId(second)).toBe(getIgnitionDeploymentId(first)); + } finally { + await other.cleanup(); + } + }); + + it("keeps the plan hash stable when only the signer changes", async () => { + const composePath = path.join(harness.projectRoot, "compose.json"); + const composeJson = JSON.parse(await fs.readFile(composePath, "utf8")) as Record; + composeJson.accounts = { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "production-deployer" }, + }, + operator: { + address: "0x00000000000000000000000000000000000000a2", + foundry: { account: "production-operator" }, + }, + }; + composeJson.chains = { + local: { rpc: RPC_URL, chainId: CHAIN_ID, account: "deployer" }, + }; + await fs.writeFile(composePath, JSON.stringify(composeJson, null, 2), "utf8"); + + const deployerPlan = await resolve(harness); + harness.ctx.param.account = "operator"; + const operatorPlan = await resolve(harness); + + expect(operatorPlan.planHash).toBe(deployerPlan.planHash); + expect(getIgnitionDeploymentId(operatorPlan)).not.toBe( + getIgnitionDeploymentId(deployerPlan), + ); + }); + + it("uses the CLI RPC override while retaining the Compose chain ID", async () => { + harness.ctx.param.rpcUrl = "https://override.example.test/v1/private-token"; + + const plan = await resolve(harness); + + expect(plan.chain).toEqual({ + chainKey: "local", + rpcUrl: "https://override.example.test/v1/private-token", + chainId: CHAIN_ID, + }); + expect(plan.rpcUrlOverridden).toBe(true); + harness.ctx.param.rpcUrl = undefined; + const configuredPlan = await resolve(harness); + expect(configuredPlan.rpcUrlOverridden).toBe(false); + expect(plan.planHash).toBe(configuredPlan.planHash); + }); + + it("resolves the chain's default Compose account profile", async () => { + const composePath = path.join(harness.projectRoot, "compose.json"); + const composeJson = JSON.parse(await fs.readFile(composePath, "utf8")) as Record; + composeJson.accounts = { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "production-deployer" }, + }, + }; + composeJson.chains = { + local: { rpc: RPC_URL, chainId: CHAIN_ID, account: "deployer" }, + }; + await fs.writeFile(composePath, JSON.stringify(composeJson, null, 2), "utf8"); + + const plan = await resolve(harness); + + expect(plan.account).toEqual({ + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + foundryAccount: "production-deployer", + }); + }); + + it("uses --account to override the chain's default signer", async () => { + const composePath = path.join(harness.projectRoot, "compose.json"); + const composeJson = JSON.parse(await fs.readFile(composePath, "utf8")) as Record; + composeJson.accounts = { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "production-deployer" }, + }, + operator: { + address: "0x00000000000000000000000000000000000000a2", + foundry: { account: "production-operator" }, + }, + }; + composeJson.chains = { + local: { rpc: RPC_URL, chainId: CHAIN_ID, account: "deployer" }, + }; + await fs.writeFile(composePath, JSON.stringify(composeJson, null, 2), "utf8"); + harness.ctx.param.account = "operator"; + + const plan = await resolve(harness); + + expect(plan.account).toEqual({ + alias: "operator", + address: "0x00000000000000000000000000000000000000A2", + foundryAccount: "production-operator", + }); + }); + + it("reports in-sync when the recorded facet set matches compose.json", async () => { + await harness.writeLock({ + CounterDiamond: { local: { default: deploymentRecord(DEFAULT_FACET_ADDRESSES) } }, + }); + + const plan = await resolve(harness); + + expect(plan.mode).toBe("in-sync"); + expect(plan.existing).toEqual(deploymentRecord(DEFAULT_FACET_ADDRESSES)); + expect(plan.diff).toBeNull(); + }); + + it("reports the composition diff when the recorded facet set differs", async () => { + await harness.writeLock({ + CounterDiamond: { + local: { + default: deploymentRecord({ DiamondInspectFacet: DEFAULT_FACET_ADDRESSES.DiamondInspectFacet }), + }, + }, + }); + + const plan = await resolve(harness); + + expect(plan.mode).toBe("diff"); + expect(plan.diff).toEqual({ added: ["CounterFacet"], removed: [] }); + }); + + it("reports removed facets that are no longer in compose.json", async () => { + await harness.writeLock({ + CounterDiamond: { + local: { + default: deploymentRecord({ + ...DEFAULT_FACET_ADDRESSES, + RemovedFacet: "0x00000000000000000000000000000000000000c1", + }), + }, + }, + }); + + const plan = await resolve(harness); + + expect(plan.mode).toBe("diff"); + expect(plan.diff).toEqual({ added: [], removed: ["RemovedFacet"] }); + }); + + it("switches to redeploy when --redeploy is set and a record exists", async () => { + await harness.writeLock({ + CounterDiamond: { local: { default: deploymentRecord(DEFAULT_FACET_ADDRESSES) } }, + }); + harness.ctx.param.redeploy = true; + + const plan = await resolve(harness); + + expect(plan.mode).toBe("redeploy"); + expect(plan.diff).toBeNull(); + }); + + it("selects the requested instance instead of the default one", async () => { + await harness.writeLock({ + CounterDiamond: { local: { staging: deploymentRecord(DEFAULT_FACET_ADDRESSES) } }, + }); + harness.ctx.param.instance = "staging"; + + const plan = await resolve(harness); + + expect(plan.instance).toBe("staging"); + expect(plan.mode).toBe("in-sync"); + + harness.ctx.param.instance = "default"; + const defaultPlan = await resolve(harness); + expect(defaultPlan.mode).toBe("fresh"); + }); + + it("flags upgradeable compositions", async () => { + await harness.writeComposeJson({ + ...DEFAULT_FACETS, + DiamondUpgradeFacet: { + source: "local", + contract: "src/DiamondUpgradeFacet.sol:DiamondUpgradeFacet", + }, + }); + + const plan = await resolve(harness); + + expect(plan.upgradeable).toBe(true); + expect(plan.facets.map((facet) => facet.name)).toContain("DiamondUpgradeFacet"); + }); + + it("rejects two facets that resolve to the same contract name", async () => { + await harness.writeComposeJson({ + FirstFacet: { source: "local", contract: "src/CounterFacet.sol:CounterFacet" }, + SecondFacet: { source: "local", contract: "src/CounterFacet.sol:CounterFacet" }, + }); + + await expect(resolve(harness)).rejects.toThrow( + "Facets 'FirstFacet' and 'SecondFacet' both resolve to contract 'CounterFacet'", + ); + }); + + it("rejects a facet that uses the diamond contract name", async () => { + await harness.writeComposeJson({ + DiamondAsFacet: { source: "local", contract: "src/Diamond.sol:Diamond" }, + }); + + await expect(resolve(harness)).rejects.toThrow( + "The diamond contract 'Diamond' is also registered as a facet", + ); + }); + + it("rejects instance names that cannot become lock keys", async () => { + harness.ctx.param.instance = "__proto__"; + await expect(resolve(harness)).rejects.toThrow("Invalid deployment instance"); + }); + + it("rejects a facet contract name that is not a Solidity identifier", async () => { + await harness.writeComposeJson({ + CounterFacet: { + source: "local", + contract: 'src/CounterFacet.sol:CounterFacet"; contract Evil {}', + }, + }); + + await expect(resolve(harness)).rejects.toThrow("Invalid Solidity contract name"); + }); + + it("rejects a diamond contract name that is not a Solidity identifier", async () => { + await harness.writeComposeJson(undefined, { + diamondContract: 'src/Diamond.sol:Diamond"; contract Evil {}', + }); + + await expect(resolve(harness)).rejects.toThrow("Invalid Solidity contract name"); + }); + + it("rejects a facet source path that cannot be embedded in a Solidity import", async () => { + await harness.writeComposeJson({ + CounterFacet: { + source: "local", + contract: 'src/Evil".sol:CounterFacet', + }, + }); + + await expect(resolve(harness)).rejects.toThrow("Invalid Solidity import path"); + }); + + it("rejects a facet source path containing a newline", async () => { + await harness.writeComposeJson({ + CounterFacet: { + source: "local", + contract: "src/Evil\nName.sol:CounterFacet", + }, + }); + + await expect(resolve(harness)).rejects.toThrow("Invalid Solidity import path"); + }); +}); diff --git a/cli/test/modules/deployScript/module.test.ts b/cli/test/modules/deployScript/module.test.ts new file mode 100644 index 00000000..0e11c9b8 --- /dev/null +++ b/cli/test/modules/deployScript/module.test.ts @@ -0,0 +1,315 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import type { Hex } from "viem"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { foundryAdapter } from "../../../src/adapters/IFrameworkAdapter/foundryAdapter/adapter"; +import { hardhatAdapter } from "../../../src/adapters/IFrameworkAdapter/hardhatAdapter/adapter"; +import { HashingAdapter } from "../../../src/adapters/IHashingAdapter/adapter"; +import { Context } from "../../../src/context/context"; +import type { ModuleState } from "../../../src/context/types"; +import type { DeployPlan } from "../../../src/modules/deployPlan/types"; +import { DeployScriptModule } from "../../../src/modules/deployScript/module"; +import { buildScriptModel, getIgnitionDeploymentId } from "../../../src/modules/deployScript/model"; +import type { ManagedScriptModel } from "../../../src/modules/deployScript/types"; + +const PLAN_HASH = `0x${"cd".repeat(32)}` as Hex; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-deploy-script-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +function deployPlan(): DeployPlan { + return { + mode: "fresh", + framework: "foundry", + projectRoot, + composeJsonPath: path.join(projectRoot, "compose.json"), + diamondName: "CounterDiamond", + diamond: { + contractName: "Diamond", + sourcePath: path.join(projectRoot, "src", "Diamond.sol"), + importSpec: "../src/Diamond.sol", + }, + instance: "default", + chain: { chainKey: "local", rpcUrl: "http://127.0.0.1:8545", chainId: 31337 }, + rpcUrlOverridden: false, + account: null, + facets: [ + { + name: "CounterFacet", + contractName: "CounterFacet", + sourcePath: path.join(projectRoot, "src", "CounterFacet.sol"), + importSpec: "../src/CounterFacet.sol", + }, + ], + existing: null, + diff: null, + upgradeable: false, + planHash: PLAN_HASH, + }; +} + +function managedModel(): ManagedScriptModel { + return { + planHash: PLAN_HASH, + framework: "foundry", + toolbox: null, + outputPath: path.join(projectRoot, "script", "ComposeDeploy.s.sol"), + runnerPath: null, + ignitionDeploymentId: null, + resultPath: null, + projectRoot, + diamond: { contractName: "Diamond", importSpec: "../src/Diamond.sol" }, + facets: [ + { + name: "CounterFacet", + contractName: "CounterFacet", + importSpec: "../src/CounterFacet.sol", + variableName: "counterFacet", + futureId: "Facet_0_CounterFacet", + }, + ], + chainKey: "local", + chainId: 31337, + instance: "default", + account: null, + }; +} + +describe("DeployScriptModule.buildModel", () => { + it("builds the model from the resolved deploy plan", async () => { + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + ctx.state.deployPlan = { success: true, result: deployPlan(), error: null }; + + const resolved = await DeployScriptModule.buildModel(ctx, foundryAdapter); + const state = resolved.state.deployScript as ModuleState<{ + path: string; + model: ManagedScriptModel; + }>; + + expect(state.success).toBe(true); + expect(state.result?.path).toBe(path.join(projectRoot, "script", "ComposeDeploy.s.sol")); + expect(state.result?.model.resultPath).toBeNull(); + expect(state.result?.model.facets[0]).toMatchObject({ + name: "CounterFacet", + contractName: "CounterFacet", + variableName: "counterFacet", + }); + expect(state.result?.model.facets[0].futureId).toMatch(/^Facet_CounterFacet_[0-9a-f]{12}$/); + }); + + it("keeps Ignition future IDs stable by facet key and gives each redeploy a new journal ID", async () => { + const plan = deployPlan(); + plan.facets.push({ + name: "Other-Facet", + contractName: "OtherFacet", + sourcePath: path.join(projectRoot, "src", "OtherFacet.sol"), + importSpec: "../src/OtherFacet.sol", + }); + const normal = await buildScriptModel(plan, foundryAdapter); + const reordered = await buildScriptModel({ ...plan, facets: [...plan.facets].reverse() }, foundryAdapter); + expect(normal.facets.find((facet) => facet.name === "CounterFacet")?.futureId) + .toBe(reordered.facets.find((facet) => facet.name === "CounterFacet")?.futureId); + + const existing = { + diamond: "0x00000000000000000000000000000000000000aa" as Hex, + facets: {}, + facetHash: `0x${"00".repeat(32)}` as Hex, + lastSync: new Date(0).toISOString(), + txHash: `0x${"11".repeat(32)}` as Hex, + }; + const freshId = getIgnitionDeploymentId({ ...plan, framework: "hardhat" }); + const redeployId = getIgnitionDeploymentId({ + ...plan, + framework: "hardhat", + mode: "redeploy", + existing, + }); + expect(redeployId).not.toBe(freshId); + expect(getIgnitionDeploymentId({ + ...plan, + framework: "hardhat", + mode: "redeploy", + existing, + })).toBe(redeployId); + }); + + it("scopes Ignition journals to the signer without changing the plan identity", () => { + const plan = { ...deployPlan(), framework: "hardhat" as const }; + const deployer = { + ...plan, + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1" as const, + }, + }; + const operator = { + ...plan, + account: { + alias: "operator", + address: "0x00000000000000000000000000000000000000a2" as const, + }, + }; + const renamed = { + ...deployer, + account: { ...deployer.account, alias: "renamed-deployer" }, + }; + + expect(operator.planHash).toBe(deployer.planHash); + expect(getIgnitionDeploymentId(operator)).not.toBe(getIgnitionDeploymentId(deployer)); + expect(getIgnitionDeploymentId(renamed)).toBe(getIgnitionDeploymentId(deployer)); + }); + + it("scopes Ignition journals to an explicitly resolved framework default signer", () => { + const plan = { ...deployPlan(), framework: "hardhat" as const }; + const first = "0x00000000000000000000000000000000000000a1"; + const second = "0x00000000000000000000000000000000000000a2"; + + expect(getIgnitionDeploymentId(plan, first)).not.toBe( + getIgnitionDeploymentId(plan, second), + ); + expect(getIgnitionDeploymentId(plan, first)).toBe( + getIgnitionDeploymentId(plan, first.toUpperCase().replace("0X", "0x")), + ); + }); + + it("avoids template identifiers and language keywords for facet variables", async () => { + const plan = deployPlan(); + plan.facets = [ + { + name: "M", + contractName: "M", + sourcePath: path.join(projectRoot, "src", "M.sol"), + importSpec: "../src/M.sol", + }, + { + name: "Static", + contractName: "Static", + sourcePath: path.join(projectRoot, "src", "Static.sol"), + importSpec: "../src/Static.sol", + }, + { + name: "ComposeSigner", + contractName: "ComposeSigner", + sourcePath: path.join(projectRoot, "src", "ComposeSigner.sol"), + importSpec: "../src/ComposeSigner.sol", + }, + { + name: "Diamond", + contractName: "Diamond", + sourcePath: path.join(projectRoot, "src", "DiamondFacet.sol"), + importSpec: "../src/DiamondFacet.sol", + }, + { + name: "Uint256", + contractName: "Uint256", + sourcePath: path.join(projectRoot, "src", "Uint256.sol"), + importSpec: "../src/Uint256.sol", + }, + { + name: "Revert", + contractName: "Revert", + sourcePath: path.join(projectRoot, "src", "Revert.sol"), + importSpec: "../src/Revert.sol", + }, + ]; + + const model = await buildScriptModel(plan, foundryAdapter); + + expect(model.facets.map((facet) => facet.variableName)).toEqual([ + "facetM", + "facetStatic", + "facetComposeSigner", + "facetDiamond", + "facetUint256", + "facetRevert", + ]); + }); + + it("records the Hardhat Ignition module, runner, and result paths in the model", async () => { + await fs.writeFile( + path.join(projectRoot, "package.json"), + JSON.stringify({ devDependencies: { "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0" } }), + "utf8", + ); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + ctx.state.deployPlan = { + success: true, + result: { ...deployPlan(), framework: "hardhat" }, + error: null, + }; + + const resolved = await DeployScriptModule.buildModel(ctx, hardhatAdapter); + const state = resolved.state.deployScript as ModuleState<{ + path: string; + model: ManagedScriptModel; + }>; + + expect(state.result?.path).toBe(path.join(projectRoot, "ignition", "modules", "ComposeDeploy.ts")); + expect(state.result?.model.toolbox).toBe("ethers"); + expect(state.result?.model.runnerPath).toBe( + path.join(projectRoot, ".compose", "hardhat", "ignition-runner.ts"), + ); + expect(state.result?.model.ignitionDeploymentId).toContain("compose-counterdiamond-local-default-"); + expect(state.result?.model.resultPath).toBe( + path.join(projectRoot, ".compose", "hardhat", "deploy-result.json"), + ); + }); + + it("fails when no plan has been resolved", async () => { + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await expect(DeployScriptModule.buildModel(ctx, foundryAdapter)).rejects.toThrow( + "deploy plan is missing", + ); + }); +}); + +describe("DeployScriptModule.readScriptHash", () => { + it("hashes the complete source, including content beyond the plan marker", async () => { + const scriptPath = path.join(projectRoot, "ComposeDeploy.s.sol"); + const source = `// compose-plan-hash: ${PLAN_HASH}\ncontract ComposeDeployScript {}\n`; + await fs.writeFile(scriptPath, source, "utf8"); + + expect(await DeployScriptModule.readScriptHash(scriptPath, HashingAdapter)).toBe( + HashingAdapter.keccak256(source), + ); + + const modifiedSource = `${source}extraTransaction();\n`; + await fs.writeFile(scriptPath, modifiedSource, "utf8"); + expect(await DeployScriptModule.readScriptHash(scriptPath, HashingAdapter)).toBe( + HashingAdapter.keccak256(modifiedSource), + ); + expect(HashingAdapter.keccak256(modifiedSource)).not.toBe(HashingAdapter.keccak256(source)); + }); + + it("returns null for missing files", async () => { + expect( + await DeployScriptModule.readScriptHash(path.join(projectRoot, "missing.sol"), HashingAdapter), + ).toBeNull(); + }); +}); + +describe("DeployScriptModule.write", () => { + it("renders and writes the managed script", async () => { + const model = managedModel(); + await DeployScriptModule.write(model); + + const source = await fs.readFile(model.outputPath, "utf8"); + expect(source).toContain(`/* compose-plan-hash: ${PLAN_HASH} */`); + expect(source).toContain("CounterFacet counterFacet = new CounterFacet();"); + expect(await DeployScriptModule.readScriptHash(model.outputPath, HashingAdapter)).toBe( + HashingAdapter.keccak256(source), + ); + }); +}); diff --git a/cli/test/modules/deployScript/renderers.test.ts b/cli/test/modules/deployScript/renderers.test.ts new file mode 100644 index 00000000..b62712ee --- /dev/null +++ b/cli/test/modules/deployScript/renderers.test.ts @@ -0,0 +1,252 @@ +import { describe, expect, it } from "vitest"; +import path from "node:path"; +import { + renderFoundryDeployScript, + renderHardhatIgnitionModule, + renderHardhatIgnitionRunner, +} from "../../../src/modules/deployScript/renderers"; +import type { ManagedScriptModel } from "../../../src/modules/deployScript/types"; +import type { Hex } from "viem"; + +const PLAN_HASH = `0x${"ab".repeat(32)}` as Hex; +const RESULT_PATH = path.join("/tmp/project", ".compose", "hardhat", "deploy-result.json"); +const IGNITION_DEPLOYMENT_ID = "compose-counter-local-default-abcdef12"; + +function model(overrides: Partial = {}): ManagedScriptModel { + return { + planHash: PLAN_HASH, + framework: "foundry", + toolbox: null, + outputPath: "/tmp/project/script/ComposeDeploy.s.sol", + runnerPath: null, + ignitionDeploymentId: null, + resultPath: null, + projectRoot: "/tmp/project", + diamond: { contractName: "Diamond", importSpec: "../src/Diamond.sol" }, + facets: [ + { + name: "AlphaFacet", + contractName: "AlphaFacet", + importSpec: "../src/AlphaFacet.sol", + variableName: "alphaFacet", + futureId: "Facet_AlphaFacet_dce992e4a97c", + }, + { + name: "Beta", + contractName: "BetaFacet", + importSpec: "@perfect-abstractions/compose/BetaFacet.sol", + variableName: "betaFacet", + futureId: "Facet_Beta_703390318bd5", + }, + ], + chainKey: "local", + chainId: 31337, + instance: "default", + account: null, + ...overrides, + }; +} + +function expectNoPlaceholders(source: string): void { + expect(source).not.toMatch(/\{\{[A-Z_]+\}\}/); +} + +describe("renderFoundryDeployScript", () => { + it("renders the plan hash, imports, and facet deployments in order", async () => { + const source = await renderFoundryDeployScript(model()); + + expect(source).toContain(`/* compose-plan-hash: ${PLAN_HASH} */`); + expect(source).toContain("/* compose-target: local (chain id 31337) */"); + expect(source).toContain('import {Diamond} from "../src/Diamond.sol";'); + expect(source).toContain('import {AlphaFacet} from "../src/AlphaFacet.sol";'); + expect(source).toContain( + 'import {BetaFacet} from "@perfect-abstractions/compose/BetaFacet.sol";', + ); + expect(source).toContain("address[] memory facets = new address[](2);"); + expect(source).toContain("vm.readCallers()"); + expect(source).toContain('console.log("Deployer:", composeSigner);'); + expect(source).toContain("AlphaFacet alphaFacet = new AlphaFacet();"); + expect(source).toContain("facets[0] = address(alphaFacet);"); + expect(source).toContain("facets[1] = address(betaFacet);"); + expect(source).toContain("Diamond diamond = new Diamond(facets);"); + expectNoPlaceholders(source); + }); + + it("deduplicates import lines for repeated sources", async () => { + const source = await renderFoundryDeployScript( + model({ + facets: [ + { + name: "AlphaFacet", + contractName: "AlphaFacet", + importSpec: "../src/AlphaFacet.sol", + variableName: "alphaFacet", + futureId: "Facet_AlphaFacet_dce992e4a97c", + }, + { + name: "AlphaFacetAlias", + contractName: "AlphaFacet", + importSpec: "../src/AlphaFacet.sol", + variableName: "alphaFacet2", + futureId: "Facet_AlphaFacetAlias_different", + }, + ], + }), + ); + + expect(source.match(/import \{AlphaFacet\} from "\.\.\/src\/AlphaFacet\.sol";/g)).toHaveLength(1); + expect(source).toContain("AlphaFacet alphaFacet2 = new AlphaFacet();"); + }); + + it("guards a Foundry broadcast against the selected Compose account", async () => { + const source = await renderFoundryDeployScript(model({ + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + foundryAccount: "production-deployer", + }, + })); + + expect(source).toContain("if (composeSigner != 0x00000000000000000000000000000000000000a1)"); + expect(source).toContain("Compose: selected signer does not match account 'deployer'"); + expect(source.indexOf("selected signer does not match account 'deployer'")).toBeLessThan( + source.indexOf("AlphaFacet alphaFacet = new AlphaFacet();"), + ); + }); + + it("rejects unsafe contract names before rendering", async () => { + await expect(renderFoundryDeployScript(model({ + diamond: { + contractName: 'Diamond"; contract Evil {}', + importSpec: "../src/Diamond.sol", + }, + }))).rejects.toThrow("Invalid Solidity contract name"); + + await expect(renderFoundryDeployScript(model({ + facets: [{ + name: "Evil", + contractName: 'Evil"; contract Injected {}', + importSpec: "../src/Evil.sol", + variableName: "evil", + futureId: "Facet_Evil", + }], + }))).rejects.toThrow("Invalid Solidity contract name"); + }); + + it("rejects unsafe import paths before rendering", async () => { + await expect(renderFoundryDeployScript(model({ + diamond: { + contractName: "Diamond", + importSpec: '../src/Evil".sol', + }, + }))).rejects.toThrow("Invalid Solidity import path"); + + await expect(renderFoundryDeployScript(model({ + facets: [{ + name: "Evil", + contractName: "EvilFacet", + importSpec: "../src/Evil.sol\ncontract Injected {}", + variableName: "evilFacet", + futureId: "Facet_Evil", + }], + }))).rejects.toThrow("Invalid Solidity import path"); + }); + + it("keeps a block-comment terminator in the target header from closing the comment", async () => { + const source = await renderFoundryDeployScript(model({ + chainKey: "local */ contract Injected {} /*", + })); + + expect(source).not.toContain("*/ contract Injected"); + expect(source.split("\n")[1]).toContain("local *\\/ contract Injected"); + }); +}); + +describe("Hardhat Ignition renderers", () => { + function hardhatModel(toolbox: "ethers" | "viem", overrides: Partial = {}) { + return model({ + framework: "hardhat", + toolbox, + outputPath: path.join("/tmp/project", "ignition", "modules", "ComposeDeploy.ts"), + runnerPath: path.join("/tmp/project", ".compose", "hardhat", "ignition-runner.ts"), + ignitionDeploymentId: IGNITION_DEPLOYMENT_ID, + resultPath: RESULT_PATH, + ...overrides, + }); + } + + it("renders a reviewable module with stable facet and diamond future IDs", async () => { + const source = await renderHardhatIgnitionModule(hardhatModel("ethers")); + + expect(source).toContain(`// compose-plan-hash: ${PLAN_HASH}`); + expect(source).toContain(`// compose-ignition-deployment-id: ${IGNITION_DEPLOYMENT_ID}`); + expect(source).toContain('buildModule("ComposeDeploy"'); + expect(source).toContain('m.contract("AlphaFacet", [], {'); + expect(source).toContain('id: "Facet_AlphaFacet_dce992e4a97c"'); + expect(source).toContain('m.contract("Diamond", [[alphaFacet, betaFacet]], {'); + expect(source).toContain('id: "Diamond"'); + expect(source).toContain("return {\n diamond,"); + expectNoPlaceholders(source); + }); + + it("renders an ethers runner that selects the configured account and captures Ignition outputs", async () => { + const source = await renderHardhatIgnitionRunner(hardhatModel("ethers", { + account: { + alias: "deployer", + address: "0x00000000000000000000000000000000000000a1", + }, + })); + + expect(source).toContain('from "../../ignition/modules/ComposeDeploy.js"'); + expect(source).toContain("const configuredSigners = await targetEthers.getSigners();"); + expect(source).toContain("targetConnection.provider.request({ method: \"eth_chainId\", params: [] })"); + expect(source).toContain("forking: { url: rpcUrl, blockNumber: forkBlockNumber }"); + expect(source).toContain('deploymentConnection.ignition.deploy(ComposeDeploy, {'); + expect(source).toContain(`deploymentId: executionDeploymentId`); + expect(source).toContain('"AlphaFacet": await addressOf(outputs.alphaFacet)'); + expect(source).toContain("for (const [name, address] of Object.entries(facets)) {"); + expect(source).toContain("console.log(`${name}: ${address}`);"); + expect(source).toContain("ignitionDeploymentId,"); + expect(source).not.toContain("transactions:"); + expect(source).toContain("Simulation succeeded. No transactions were broadcast."); + expectNoPlaceholders(source); + }); + + it("renders the viem signer resolver using the official toolbox integration", async () => { + const source = await renderHardhatIgnitionRunner(hardhatModel("viem")); + + expect(source).toContain("const { viem: targetViem } = targetConnection;"); + expect(source).toContain("const configuredWallets = await targetViem.getWalletClients();"); + expect(source).toContain("deploymentConnection.ignition.deploy(ComposeDeploy"); + expect(source).toContain('"Beta": await addressOf(outputs.betaFacet)'); + expectNoPlaceholders(source); + }); + + it("requires the Ignition metadata and runtime paths", async () => { + await expect(renderHardhatIgnitionModule(hardhatModel("ethers", { + ignitionDeploymentId: null, + }))).rejects.toThrow("deployment ID"); + await expect(renderHardhatIgnitionRunner(hardhatModel("ethers", { + runnerPath: null, + }))).rejects.toThrow("runner is missing"); + }); + + it("rejects unsafe contract names in the Ignition module", async () => { + await expect(renderHardhatIgnitionModule(hardhatModel("ethers", { + diamond: { + contractName: 'Diamond"); contract Evil {}', + importSpec: "../src/Diamond.sol", + }, + }))).rejects.toThrow("Invalid Solidity contract name"); + + await expect(renderHardhatIgnitionModule(hardhatModel("ethers", { + facets: [{ + name: "Evil", + contractName: 'Evil"); contract Injected {}', + importSpec: "../src/Evil.sol", + variableName: "evil", + futureId: "Facet_Evil", + }], + }))).rejects.toThrow("Invalid Solidity contract name"); + }); +}); diff --git a/cli/test/modules/deploySimulation/module.test.ts b/cli/test/modules/deploySimulation/module.test.ts new file mode 100644 index 00000000..e53b1575 --- /dev/null +++ b/cli/test/modules/deploySimulation/module.test.ts @@ -0,0 +1,71 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; +import { Context } from "../../../src/context/context"; +import type { ModuleState } from "../../../src/context/types"; +import { DeploySimulationModule } from "../../../src/modules/deploySimulation/module"; +import type { DeployPlan } from "../../../src/modules/deployPlan/types"; + +const mocks = vi.hoisted(() => ({ runCommand: vi.fn(async () => {}) })); +vi.mock("../../../src/utils/exec", () => ({ runCommand: mocks.runCommand })); + +const plan: DeployPlan = { + mode: "fresh", + framework: "foundry", + projectRoot: "/tmp/compose-project", + composeJsonPath: "/tmp/compose-project/compose.json", + diamondName: "ExampleDiamond", + diamond: { contractName: "Diamond", sourcePath: "", importSpec: "" }, + instance: "default", + chain: { chainKey: "sepolia", rpcUrl: "https://rpc.example.test", chainId: 11155111 }, + rpcUrlOverridden: false, + account: null, + facets: [], + existing: null, + diff: null, + upgradeable: false, + planHash: `0x${"ab".repeat(32)}`, +}; + +beforeEach(() => { + mocks.runCommand.mockReset().mockResolvedValue(undefined); +}); + +describe("DeploySimulationModule.simulate", () => { + it("invokes the framework in simulation mode at the pinned fork block", async () => { + const ctx = Context.create(); + const createDeployCommand = vi.fn(() => ({ command: "forge", args: [] })); + const adapter = { createDeployCommand } as unknown as IFrameworkAdapter; + + await DeploySimulationModule.simulate(ctx, plan, "/tmp/ComposeDeploy.s.sol", adapter, 1234n, null); + + expect(createDeployCommand).toHaveBeenCalledWith({ + chainId: 11155111, + chainKey: "sepolia", + passthrough: [], + projectRoot: "/tmp/compose-project", + rpcUrl: "https://rpc.example.test", + account: null, + scriptPath: "/tmp/ComposeDeploy.s.sol", + runnerPath: null, + mode: "simulate", + forkBlockNumber: 1234n, + }); + const state = ctx.state.deploySimulation as ModuleState<{ forkBlockNumber: bigint }>; + expect(state.success).toBe(true); + expect(state.result?.forkBlockNumber).toBe(1234n); + expect(mocks.runCommand).toHaveBeenCalledWith("forge", [], { cwd: plan.projectRoot }); + }); + + it("records failed simulations and rethrows the framework error", async () => { + const ctx = Context.create(); + mocks.runCommand.mockRejectedValueOnce(new Error("Simulated revert")); + const adapter = { createDeployCommand: () => ({ command: "forge", args: [] }) } as unknown as IFrameworkAdapter; + + await expect( + DeploySimulationModule.simulate(ctx, plan, "/tmp/ComposeDeploy.s.sol", adapter, 1234n, null), + ).rejects.toThrow("Simulated revert"); + const state = ctx.state.deploySimulation as ModuleState; + expect(state.success).toBe(false); + expect(state.error?.code).toBe("DEPLOY_SIMULATION_FAILED"); + }); +}); diff --git a/cli/test/modules/deployVerification/module.test.ts b/cli/test/modules/deployVerification/module.test.ts new file mode 100644 index 00000000..2cd8dc56 --- /dev/null +++ b/cli/test/modules/deployVerification/module.test.ts @@ -0,0 +1,311 @@ +import path from "node:path"; +import { getAddress, type Address, type Hex } from "viem"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { IDiamondAdapter } from "../../../src/adapters/IDiamondAdapter/interface"; +import { HashingAdapter } from "../../../src/adapters/IHashingAdapter/adapter"; +import type { IRPCAdapter } from "../../../src/adapters/IRPCAdapter/interface"; +import { Context } from "../../../src/context/context"; +import type { ModuleState } from "../../../src/context/types"; +import type { DeployExecutionResult } from "../../../src/modules/deployExecution/types"; +import type { DeployPlan } from "../../../src/modules/deployPlan/types"; +import { LockFileModule } from "../../../src/modules/lockFile/module"; +import type { DiamondDeployment } from "../../../src/modules/lockFile/types"; +import { DeployVerificationModule } from "../../../src/modules/deployVerification/module"; + +const DIAMOND = "0x00000000000000000000000000000000000000aa"; +const FACET_A = "0x00000000000000000000000000000000000000b1"; +const FACET_B = "0x00000000000000000000000000000000000000b2"; +const SELECTOR_A1 = "0xaaaaaaaa" as Hex; +const SELECTOR_A2 = "0xbbbbbbbb" as Hex; +const SELECTOR_B = "0xcccccccc" as Hex; +const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as Address; +const DIAMOND_TX = `0x${"33".repeat(32)}` as Hex; +const CODE = "0x600060005260206000f3" as Hex; + +const DEFAULT_SELECTORS: Record = { + [FACET_A.toLowerCase()]: [SELECTOR_A1, SELECTOR_A2], + [FACET_B.toLowerCase()]: [SELECTOR_B], +}; + +const DEFAULT_ROUTES: Record = { + [SELECTOR_A1.toLowerCase()]: FACET_A as Address, + [SELECTOR_A2.toLowerCase()]: FACET_A as Address, + [SELECTOR_B.toLowerCase()]: FACET_B as Address, +}; + +function executionResult(ignitionDeploymentId?: string): DeployExecutionResult { + return { + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + ...(ignitionDeploymentId ? { ignitionDeploymentId } : {}), + transactions: { diamond: DIAMOND_TX }, + }; +} + +function deployPlan(): DeployPlan { + return { + mode: "fresh", + framework: "foundry", + projectRoot: "/tmp/project", + composeJsonPath: "/tmp/project/compose.json", + diamondName: "CounterDiamond", + diamond: { + contractName: "Diamond", + sourcePath: path.join("/tmp/project/src/Diamond.sol"), + importSpec: "../src/Diamond.sol", + }, + instance: "default", + chain: { chainKey: "local", rpcUrl: "http://127.0.0.1:8545", chainId: 31337 }, + rpcUrlOverridden: false, + account: null, + facets: [ + { + name: "AlphaFacet", + contractName: "AlphaFacet", + sourcePath: "/tmp/project/src/AlphaFacet.sol", + importSpec: "../src/AlphaFacet.sol", + }, + { + name: "BetaFacet", + contractName: "BetaFacet", + sourcePath: "/tmp/project/src/BetaFacet.sol", + importSpec: "../src/BetaFacet.sol", + }, + ], + existing: null, + diff: null, + upgradeable: false, + planHash: `0x${"cd".repeat(32)}` as Hex, + }; +} + +function stubRpc(codeFor: (address: string) => Hex | undefined): IRPCAdapter { + return { + getBlockNumber: async () => 0n, + readContract: async () => { + throw new Error("readContract is not used by verification"); + }, + getCode: async (address: Address) => codeFor(address.toLowerCase()), + }; +} + +type DiamondStubOptions = { + addresses?: Address[]; + selectors?: Record; + routes?: Record; +}; + +function stubDiamond(options: DiamondStubOptions = {}): IDiamondAdapter { + const addresses = options.addresses ?? [getAddress(FACET_A), getAddress(FACET_B)]; + const selectors = options.selectors ?? DEFAULT_SELECTORS; + const routes = options.routes ?? DEFAULT_ROUTES; + + return { + facets: async () => [], + facetAddresses: async () => addresses, + facetFunctionSelectors: async (_diamond, facet) => selectors[facet.toLowerCase()] ?? [], + facetAddress: async (_diamond, selector) => routes[selector.toLowerCase()] ?? ZERO_ADDRESS, + }; +} + +async function verify( + rpc: IRPCAdapter, + diamond: IDiamondAdapter, + ignitionDeploymentId?: string, + execution: DeployExecutionResult = executionResult(ignitionDeploymentId), +): Promise<{ success: boolean; record: DiamondDeployment | null; message: string | null }> { + const ctx = Context.create(); + const resolved = await DeployVerificationModule.verify(ctx, deployPlan(), execution, { + diamond, + hashing: HashingAdapter, + rpc, + }); + const state = resolved.state.deployVerification as ModuleState; + return { record: state?.result ?? null, success: state?.success ?? false, message: state?.error?.message ?? null }; +} + +afterEach(() => { + vi.restoreAllMocks(); +}); + +describe("DeployVerificationModule.verify", () => { + it("builds the lock record when chain state matches the result", async () => { + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond(), + ); + + expect(outcome.success).toBe(true); + expect(outcome.record).toMatchObject({ + diamond: DIAMOND, + facets: { AlphaFacet: FACET_A, BetaFacet: FACET_B }, + txHash: DIAMOND_TX, + }); + expect(outcome.record?.facetHash).toBe( + LockFileModule.computeFacetHash([FACET_A as Hex, FACET_B as Hex], HashingAdapter), + ); + expect(Date.parse(outcome.record?.lastSync ?? "")).not.toBeNaN(); + }); + + it("persists the Hardhat Ignition deployment ID in the verified lock record", async () => { + const ignitionDeploymentId = "compose-counterdiamond-local-default-abcdef12"; + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond(), + ignitionDeploymentId, + ); + + expect(outcome.success).toBe(true); + expect(outcome.record?.ignitionDeploymentId).toBe(ignitionDeploymentId); + }); + + it("fails when the diamond has no code", async () => { + const report = vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc((address) => (address === DIAMOND ? undefined : CODE)), + stubDiamond(), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("No contract code found at the diamond address"); + expect(report).toHaveBeenCalledWith( + expect.stringContaining("On-chain verification failed"), + ); + }); + + it("fails when a facet has no code", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc((address) => (address === FACET_B ? undefined : CODE)), + stubDiamond(), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("No contract code found at facet 'BetaFacet'"); + }); + + it("fails when the on-chain facet set differs from the result", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond({ + addresses: [ + FACET_A, + FACET_B, + "0x00000000000000000000000000000000000000c3", + ] as Address[], + }), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("do not match the deployment result"); + expect(outcome.message).toContain("0x00000000000000000000000000000000000000c3"); + }); + + it("fails when a reported facet is missing on-chain", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify(stubRpc(() => CODE), stubDiamond({ addresses: [FACET_A] })); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain(FACET_B); + }); + + it("fails when two reported facets share an address", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const execution = executionResult(); + execution.facets = { AlphaFacet: FACET_A, BetaFacet: FACET_A }; + const outcome = await verify(stubRpc(() => CODE), stubDiamond(), undefined, execution); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("Facets 'AlphaFacet' and 'BetaFacet' report the same address"); + expect(outcome.message).toContain("facet addresses must be unique"); + }); + + it("fails when a reported facet address equals the diamond address", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const execution = executionResult(); + execution.facets = { AlphaFacet: DIAMOND, BetaFacet: FACET_B }; + const outcome = await verify(stubRpc(() => CODE), stubDiamond(), undefined, execution); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("Facet 'AlphaFacet' uses the diamond address"); + expect(outcome.message).toContain("facets must be separate contracts"); + }); + + it("fails when the on-chain facet list contains duplicates", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond({ addresses: [FACET_A, FACET_B, FACET_B] }), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("The on-chain facet list contains duplicate address"); + expect(outcome.message).toContain(FACET_B); + }); + + it("fails when a facet exposes no selectors on the diamond", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond({ + selectors: { + ...DEFAULT_SELECTORS, + [FACET_B.toLowerCase()]: [], + }, + }), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("Facet 'BetaFacet'"); + expect(outcome.message).toContain("exposes no selectors"); + }); + + it("fails when a selector routes to a different facet", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond({ + routes: { + ...DEFAULT_ROUTES, + [SELECTOR_B.toLowerCase()]: FACET_A as Address, + }, + }), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain(`Selector ${SELECTOR_B}`); + expect(outcome.message).toContain("is routed to"); + expect(outcome.message).toContain(FACET_A); + }); + + it("fails when a selector is not routed by the diamond", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const outcome = await verify( + stubRpc(() => CODE), + stubDiamond({ + routes: { + ...DEFAULT_ROUTES, + [SELECTOR_A1.toLowerCase()]: ZERO_ADDRESS, + }, + }), + ); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain(`Selector ${SELECTOR_A1}`); + expect(outcome.message).toContain("is not routed by the diamond"); + }); + + it("compares facet addresses case-insensitively", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const execution = executionResult(); + execution.facets = { + AlphaFacet: FACET_A.toUpperCase().replace("0X", "0x") as Hex, + BetaFacet: FACET_A, + }; + const outcome = await verify(stubRpc(() => CODE), stubDiamond(), undefined, execution); + + expect(outcome.success).toBe(false); + expect(outcome.message).toContain("facet addresses must be unique"); + }); +}); diff --git a/cli/test/modules/diamondGeneration/module.test.ts b/cli/test/modules/diamondGeneration/module.test.ts index 7011a6bb..3257d27a 100644 --- a/cli/test/modules/diamondGeneration/module.test.ts +++ b/cli/test/modules/diamondGeneration/module.test.ts @@ -4,7 +4,7 @@ import { describe, expect, it } from "vitest"; import { ModuleState } from "../../../src/context/types"; import { BasesCatalog } from "../../../src/modules/config/types"; import { DiamondGenerationModule } from "../../../src/modules/diamondGeneration/module"; -import { createDeployGenerationHarness } from "../deployGeneration/harness"; +import { createScaffoldHarness } from "../scaffoldHarness"; type DiamondGenerationResult = { outputPath: string; @@ -15,7 +15,7 @@ type DiamondGenerationResult = { /** Tests Diamond.sol generation from the full ERC-20 fixture selection. */ describe("DiamondGenerationModule", () => { it("generates Diamond.sol with selected facet imports and constructors", async () => { - const harness = await createDeployGenerationHarness(); + const harness = await createScaffoldHarness(); const sourceRoot = path.join(harness.projectRoot, "src"); const catalog = harness.ctx.config.bases as BasesCatalog; catalog.features.owner.required.OwnerDataFacet = { diff --git a/cli/test/modules/facetConfig/facetResolver.test.ts b/cli/test/modules/facetConfig/facetResolver.test.ts index f2ffeebb..c270b806 100644 --- a/cli/test/modules/facetConfig/facetResolver.test.ts +++ b/cli/test/modules/facetConfig/facetResolver.test.ts @@ -4,6 +4,7 @@ import path from "node:path"; import { afterEach, describe, expect, it } from "vitest"; import type { BasesCatalog } from "../../../src/modules/config/types"; import { + copyCatalogFacetSources, findLocalContractMatches, listAvailableCatalogFacetNames, resolveFacetInstallReference, @@ -144,3 +145,48 @@ describe("bare facet references", () => { ]); }); }); + +describe("install guidance messages", () => { + it("suggests discovery paths for an unknown bare reference", async () => { + const root = await createProject(); + + await expect( + resolveFacetInstallReference("erc20", { globals: {}, features: {} }, root), + ).rejects.toThrow(/Use a 'compose catalog' name, path\.sol:ContractName, or a project contract name/); + }); + + it("adds the manifest hint for unknown manifest entries", async () => { + const root = await createProject(); + + await expect( + resolveFacetInstallReference({ name: "erc20" }, { globals: {}, features: {} }, root), + ).rejects.toThrow( + /Use a 'compose catalog' name, path\.sol:ContractName, or a project contract name\. In a manifest, give the entry a local or package source\./, + ); + }); + + it("points to local registration when a catalog copy would overwrite edited content", async () => { + const root = await createProject(); + await writeSource(root, "fixtures/CounterDecrementFacet.sol", "// catalog version\ncontract CounterDecrementFacet {}\n"); + await writeSource(root, "contracts/facets/CounterDecrementFacet.sol", "// edited locally\ncontract CounterDecrementFacet {}\n"); + + const conflict = copyCatalogFacetSources( + [{ + name: "CounterDecrementFacet", + contractName: "CounterDecrementFacet", + targetGroup: "facets", + catalogSource: path.join(root, "fixtures", "CounterDecrementFacet.sol"), + registration: { source: "local", contract: "", constructor: undefined }, + }], + root, + path.join(root, "contracts"), + ); + + await expect(conflict).rejects.toThrow( + "Facet source destination already exists with different contents: contracts/facets/CounterDecrementFacet.sol", + ); + await expect(conflict).rejects.toThrow( + 'Keep it: compose install "contracts/facets/CounterDecrementFacet.sol:CounterDecrementFacet". Replace it: move the file, then install again.', + ); + }); +}); diff --git a/cli/test/modules/facetConfig/module.test.ts b/cli/test/modules/facetConfig/module.test.ts index 742389f3..2a985317 100644 --- a/cli/test/modules/facetConfig/module.test.ts +++ b/cli/test/modules/facetConfig/module.test.ts @@ -2,7 +2,8 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { afterEach, describe, expect, it, vi } from "vitest"; -import type { IFrameworkAdapter, SolidityAstSource } from "../../../src/adapters/IFrameworkAdapter/interface"; +import type { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; +import type { SolidityAstSource } from "../../../src/adapters/IFrameworkAdapter/types"; import type { IHashingAdapter } from "../../../src/adapters/IHashingAdapter/interface"; import { Context } from "../../../src/context/context"; import { DependencyKey } from "../../../src/resolver/dependencyKey"; diff --git a/cli/test/modules/facetConfig/projectConfig.test.ts b/cli/test/modules/facetConfig/projectConfig.test.ts index c433c018..2659b0e3 100644 --- a/cli/test/modules/facetConfig/projectConfig.test.ts +++ b/cli/test/modules/facetConfig/projectConfig.test.ts @@ -3,7 +3,7 @@ import os from "node:os"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { Context } from "../../../src/context/context"; -import { loadComposeProject } from "../../../src/modules/facetConfig/projectConfig"; +import { loadComposeProject, getDiamondOrThrow } from "../../../src/modules/facetConfig/projectConfig"; describe("facet config project loader", () => { it("validates the project and defaults omitted facet maps", async () => { @@ -60,3 +60,18 @@ describe("facet config project loader", () => { } }); }); + +describe("getDiamondOrThrow", () => { + it("lists available diamond names when the requested one is missing", () => { + const diamonds = { Alpha: {}, Beta: {} } as never; + expect(() => getDiamondOrThrow(diamonds, "Gamma")).toThrow( + "Diamond 'Gamma' is not defined in compose.json. Available: Alpha, Beta.", + ); + }); + + it("says none defined when the project has no diamonds", () => { + expect(() => getDiamondOrThrow({} as never, "Alpha")).toThrow( + "Available: none defined.", + ); + }); +}); diff --git a/cli/test/modules/facetConfig/selection.test.ts b/cli/test/modules/facetConfig/selection.test.ts new file mode 100644 index 00000000..b05e9be1 --- /dev/null +++ b/cli/test/modules/facetConfig/selection.test.ts @@ -0,0 +1,57 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { Context } from "../../../src/context/context"; +import { selectDiamond } from "../../../src/modules/facetConfig/selection"; + +const mocks = vi.hoisted(() => ({ + isInteractive: vi.fn(() => true), + select: vi.fn(async () => "second"), +})); + +vi.mock("../../../src/utils/inquirer", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + isInteractive: mocks.isInteractive, + loadPrompts: async () => ({ select: mocks.select }), + }; +}); + +beforeEach(() => { + mocks.isInteractive.mockReturnValue(true); + mocks.select.mockReset().mockResolvedValue("second"); +}); + +describe("selectDiamond", () => { + it("uses an explicit diamond without prompting", async () => { + const ctx = Context.create(); + ctx.param.diamond = "second"; + + await expect(selectDiamond(ctx, ["first", "second"], "deploy")).resolves.toBe("second"); + expect(mocks.select).not.toHaveBeenCalled(); + }); + + it("uses the only defined diamond without prompting", async () => { + await expect(selectDiamond(Context.create(), ["only"], "deploy")).resolves.toBe("only"); + expect(mocks.select).not.toHaveBeenCalled(); + }); + + it("prompts for an ambiguous diamond when prompting is allowed", async () => { + await expect(selectDiamond(Context.create(), ["first", "second"], "install facets into")) + .resolves.toBe("second"); + expect(mocks.select).toHaveBeenCalledOnce(); + }); + + it("refuses to prompt when prompting is disabled", async () => { + await expect(selectDiamond(Context.create(), ["first", "second"], "deploy", { allowPrompt: false })) + .rejects.toThrow("Specify --diamond"); + expect(mocks.select).not.toHaveBeenCalled(); + }); + + it("requires --diamond when the terminal is not interactive", async () => { + mocks.isInteractive.mockReturnValue(false); + + await expect(selectDiamond(Context.create(), ["first", "second"], "deploy")) + .rejects.toThrow("Specify --diamond"); + expect(mocks.select).not.toHaveBeenCalled(); + }); +}); diff --git a/cli/test/modules/info/scanner.test.ts b/cli/test/modules/info/scanner.test.ts index 16a46a12..e149f0bd 100644 --- a/cli/test/modules/info/scanner.test.ts +++ b/cli/test/modules/info/scanner.test.ts @@ -8,7 +8,10 @@ import { ComposeProjectInfo } from "../../../src/modules/info/types"; import { scanFacets } from "../../../src/modules/info/scanner"; describe("info package facet scanning", () => { - it("uses the first package source match", async () => { + it.each([ + { framework: "foundry", expected: ["fromFoundryLib()"] }, + { framework: "hardhat", expected: ["fromNodeModules()"] }, + ])("uses the $framework package source match", async ({ framework, expected }) => { const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-info-package-facet-")); try { @@ -37,7 +40,7 @@ describe("info package facet scanning", () => { const projectInfo: ComposeProjectInfo = { project: "example", composeVersion: "0.1.0", - framework: "foundry", + framework, diamonds: [{ name: "ExampleDiamond", contract: "src/Diamond.sol:Diamond", @@ -62,7 +65,7 @@ describe("info package facet scanning", () => { await scanFacets(ctx); const state = ctx.state.infoProject as ModuleState; - expect(state.result?.diamonds[0].facets[0].selectors).toEqual(["fromNodeModules()"]); + expect(state.result?.diamonds[0].facets[0].selectors).toEqual(expected); } finally { await fs.rm(projectRoot, { recursive: true, force: true }); } diff --git a/cli/test/modules/init/module.test.ts b/cli/test/modules/init/module.test.ts index 1dc5e433..a06b1693 100644 --- a/cli/test/modules/init/module.test.ts +++ b/cli/test/modules/init/module.test.ts @@ -1,4 +1,4 @@ -import { beforeEach, describe, expect, it } from "vitest"; +import { beforeEach, describe, expect, it, vi } from "vitest"; import { Context } from "../../../src/context/context"; import { ComposeContext } from "../../../src/context/types"; import { ConfigModule } from "../../../src/modules/config/module"; @@ -48,12 +48,112 @@ describe("InitModule.runInitNonInteractive", () => { expect(result.state.entry?.result).toEqual(expect.objectContaining({ framework: "foundry", selectedBaseKey: "erc-20", + upgradeable: false, selectedLibraries: ["ERC165Facet"], selectedExtensions: ["ERC20BurnFacet"], selectedAccess: ["owner", "access-control"], })); }); + it("defaults to an immutable diamond without owner coupling", async () => { + const logs = vi.spyOn(console, "log").mockImplementation(() => undefined); + + try { + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.libraries).toEqual([]); + expect(result.param.access).toEqual([]); + expect(result.state.entry?.result).toEqual(expect.objectContaining({ + upgradeable: false, + selectedLibraries: [], + selectedAccess: [], + })); + expect(logs).not.toHaveBeenCalled(); + } finally { + logs.mockRestore(); + } + }); + + it("adds the upgrade facet and owner coupling with --upgradeable", async () => { + const logs = vi.spyOn(console, "log").mockImplementation(() => undefined); + ctx.param.upgradeable = true; + + try { + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.libraries).toEqual(["DiamondUpgradeFacet"]); + expect(result.param.access).toEqual(["owner"]); + expect(result.state.entry?.result).toEqual(expect.objectContaining({ + upgradeable: true, + selectedLibraries: ["DiamondUpgradeFacet"], + selectedAccess: ["owner"], + })); + expect(logs.mock.calls.flat().join("\n")).toContain("Upgradeable diamonds need an owner"); + } finally { + logs.mockRestore(); + } + }); + + it("omits the upgrade facet and owner coupling when --immutable is set", async () => { + ctx.param.immutable = true; + + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.libraries).toEqual([]); + expect(result.param.access).toEqual([]); + expect(result.state.entry?.result).toEqual(expect.objectContaining({ upgradeable: false })); + }); + + it("keeps an explicitly selected ownership base", async () => { + ctx.param.ownership = "owner-two-step"; + + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.access).toEqual(["owner-two-step"]); + expect(result.param.libraries).toEqual([]); + }); + + it("does not add an owner when the base itself is an ownership base", async () => { + ctx.param.base = "owner"; + ctx.param.upgradeable = true; + + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.access).toEqual([]); + expect(result.param.libraries).toEqual(["DiamondUpgradeFacet"]); + }); + + it("honors an explicit DiamondUpgradeFacet library as upgradeable", async () => { + const logs = vi.spyOn(console, "log").mockImplementation(() => undefined); + ctx.param.libraries = "DiamondUpgradeFacet"; + + try { + const result = await InitModule.runInitNonInteractive(ctx); + + expect(result.param.libraries).toEqual(["DiamondUpgradeFacet"]); + expect(result.param.access).toEqual(["owner"]); + expect(result.state.entry?.result).toEqual(expect.objectContaining({ upgradeable: true })); + } finally { + logs.mockRestore(); + } + }); + + it("rejects --immutable with an explicit DiamondUpgradeFacet library", async () => { + Object.assign(ctx.param, { immutable: true, libraries: "DiamondUpgradeFacet" }); + + await expect(InitModule.runInitNonInteractive(ctx)).rejects.toThrow( + "DiamondUpgradeFacet in --libraries conflicts with --immutable", + ); + }); + + it("rejects using --upgradeable and --immutable together", async () => { + Object.assign(ctx.param, { upgradeable: true, immutable: true }); + + await expect(InitModule.runInitNonInteractive(ctx)).rejects.toThrow( + "Use either --upgradeable or --immutable, not both.", + ); + }); + it("defaults Hardhat projects to the ethers toolbox", async () => { ctx.param.framework = "hardhat"; diff --git a/cli/test/modules/init/output.test.ts b/cli/test/modules/init/output.test.ts index 0c895ca2..86910ccb 100644 --- a/cli/test/modules/init/output.test.ts +++ b/cli/test/modules/init/output.test.ts @@ -35,5 +35,21 @@ describe("init success output", () => { showSuccess(ctx); expect(log.mock.calls.flat().join("\n")).not.toContain("cd "); + expect(log.mock.calls.flat().join("\n")).toContain("forge test"); + expect(log.mock.calls.flat().join("\n")).not.toContain("The Compose CLI is installed in the project"); + }); + + it("prints the native test command for Hardhat projects", () => { + const ctx = Context.create(); + ctx.param = { + projectName: "my-diamond", + projectRoot: process.cwd(), + framework: "hardhat", + }; + const log = vi.spyOn(console, "log").mockImplementation(() => undefined); + + showSuccess(ctx); + + expect(log.mock.calls.flat().join("\n")).toContain("npx hardhat test"); }); }); diff --git a/cli/test/modules/lockFile/module.test.ts b/cli/test/modules/lockFile/module.test.ts index 59fa5ee6..64a2713f 100644 --- a/cli/test/modules/lockFile/module.test.ts +++ b/cli/test/modules/lockFile/module.test.ts @@ -9,13 +9,15 @@ describe("LockFileModule.isLockStale", () => { deployments: { MyDiamond: { sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: { - FacetA: "0xabcdef1234567890abcdef1234567890abcdef12", + default: { + diamond: "0x1234567890abcdef1234567890abcdef12345678", + facets: { + FacetA: "0xabcdef1234567890abcdef1234567890abcdef12", + }, + facetHash, + lastSync: "2026-08-03T12:00:00Z", + txHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", }, - facetHash, - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", }, }, }, @@ -53,6 +55,22 @@ describe("LockFileModule.isLockStale", () => { const stale = LockFileModule.isLockStale(lock, "MyDiamond", "sepolia", addresses, HashingAdapter); expect(stale).toBe(false); }); + + it("returns true when the instance is not recorded", () => { + const addresses = ["0xabcdef1234567890abcdef1234567890abcdef12"]; + const facetHash = LockFileModule.computeFacetHash(addresses, HashingAdapter); + const lock = createTestLock(facetHash); + + const stale = LockFileModule.isLockStale( + lock, + "MyDiamond", + "sepolia", + addresses, + HashingAdapter, + "staging", + ); + expect(stale).toBe(true); + }); }); describe("LockFileModule.getDeployment", () => { @@ -61,11 +79,13 @@ describe("LockFileModule.getDeployment", () => { deployments: { MyDiamond: { sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: {}, - facetHash: "0x...", - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x...", + default: { + diamond: "0x1234567890abcdef1234567890abcdef12345678", + facets: {}, + facetHash: "0x...", + lastSync: "2026-08-03T12:00:00Z", + txHash: "0x...", + }, }, }, }, @@ -86,6 +106,22 @@ describe("LockFileModule.getDeployment", () => { const deployment = LockFileModule.getDeployment(testLock, "MyDiamond", "mainnet"); expect(deployment).toBeUndefined(); }); + + it("reads a named instance without falling back to the default instance", () => { + const staging: DiamondDeployment = { + diamond: "0x9999999999999999999999999999999999999999", + facets: {}, + facetHash: "0x...", + lastSync: "2026-08-03T12:00:00Z", + txHash: "0x...", + }; + const lock = LockFileModule.setDeployment(testLock, "MyDiamond", "sepolia", "staging", staging); + + expect(LockFileModule.getDeployment(lock, "MyDiamond", "sepolia", "staging")).toEqual(staging); + expect(LockFileModule.getDeployment(lock, "MyDiamond", "sepolia")?.diamond).toBe( + "0x1234567890abcdef1234567890abcdef12345678", + ); + }); }); describe("LockFileModule.setDeployment", () => { @@ -103,32 +139,78 @@ describe("LockFileModule.setDeployment", () => { }; it("adds new deployment to empty lock", () => { - const updated = LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", deployment); - expect(updated.deployments.MyDiamond?.sepolia).toEqual(deployment); + const updated = LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", "default", deployment); + expect(updated.deployments.MyDiamond?.sepolia.default).toEqual(deployment); }); it("does not mutate original lock", () => { const originalDeployments = emptyLock.deployments; - LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", deployment); + LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", "default", deployment); expect(emptyLock.deployments).toBe(originalDeployments); expect(emptyLock.deployments.MyDiamond).toBeUndefined(); }); it("updates existing deployment", () => { - const lockWithDeployment = LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", deployment); + const lockWithDeployment = LockFileModule.setDeployment( + emptyLock, + "MyDiamond", + "sepolia", + "default", + deployment, + ); const newDeployment = { ...deployment, diamond: "0x9999999999999999999999999999999999999999" }; - const updated = LockFileModule.setDeployment(lockWithDeployment, "MyDiamond", "sepolia", newDeployment); - expect(updated.deployments.MyDiamond?.sepolia.diamond).toBe("0x9999999999999999999999999999999999999999"); + const updated = LockFileModule.setDeployment( + lockWithDeployment, + "MyDiamond", + "sepolia", + "default", + newDeployment, + ); + expect(updated.deployments.MyDiamond?.sepolia.default.diamond) + .toBe("0x9999999999999999999999999999999999999999"); }); it("adds deployment to new chain", () => { - const lockWithSepolia = LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", deployment); + const lockWithSepolia = LockFileModule.setDeployment( + emptyLock, + "MyDiamond", + "sepolia", + "default", + deployment, + ); const baseDeployment = { ...deployment, diamond: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }; - const updated = LockFileModule.setDeployment(lockWithSepolia, "MyDiamond", "base", baseDeployment); - expect(updated.deployments.MyDiamond?.sepolia).toEqual(deployment); - expect(updated.deployments.MyDiamond?.base.diamond).toBe("0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"); + const updated = LockFileModule.setDeployment( + lockWithSepolia, + "MyDiamond", + "base", + "default", + baseDeployment, + ); + expect(updated.deployments.MyDiamond?.sepolia.default).toEqual(deployment); + expect(updated.deployments.MyDiamond?.base.default.diamond) + .toBe("0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"); + }); + + it("keeps instances on the same chain independent", () => { + const lock = LockFileModule.setDeployment( + emptyLock, + "MyDiamond", + "sepolia", + "default", + deployment, + ); + const staging = { ...deployment, diamond: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" }; + + const updated = LockFileModule.setDeployment(lock, "MyDiamond", "sepolia", "staging", staging); + expect(updated.deployments.MyDiamond?.sepolia.default).toEqual(deployment); + expect(updated.deployments.MyDiamond?.sepolia.staging).toEqual(staging); + }); + + it("rejects an empty instance name", () => { + expect(() => LockFileModule.setDeployment(emptyLock, "MyDiamond", "sepolia", "", deployment)) + .toThrow("Deployment instance must be a non-empty string."); }); }); diff --git a/cli/test/modules/lockFile/readWrite.test.ts b/cli/test/modules/lockFile/readWrite.test.ts index 589fec78..9bdee574 100644 --- a/cli/test/modules/lockFile/readWrite.test.ts +++ b/cli/test/modules/lockFile/readWrite.test.ts @@ -2,6 +2,7 @@ import { describe, expect, it, beforeEach, afterEach } from "vitest"; import fs from "node:fs/promises"; import path from "node:path"; import { LockFileModule } from "../../../src/modules/lockFile/module"; +import { Context } from "../../../src/context/context"; import { createLockFileHarness, LockFileHarness } from "./harness"; describe("LockFileModule.readLockFile / writeLockFile", () => { @@ -73,4 +74,27 @@ describe("LockFileModule.readLockFile / writeLockFile", () => { const readCtx = await LockFileModule.readLockFile(harness.ctx); expect(readCtx.state.lockFile?.result?.lock).toEqual(lock2); }); + + it("does not read or write an ancestor lock for a nested project root", async () => { + const parentLockPath = path.join(harness.projectRoot, "compose.lock"); + const nestedRoot = path.join(harness.projectRoot, "hh-test"); + const nestedLockPath = path.join(nestedRoot, "compose.lock"); + await fs.mkdir(nestedRoot, { recursive: true }); + + const parentLock = LockFileModule.createEmptyLock("0.3.0"); + await fs.writeFile(parentLockPath, JSON.stringify(parentLock, null, 2), "utf8"); + + const nestedCtx = Context.create(); + nestedCtx.param.projectRoot = nestedRoot; + + const readCtx = await LockFileModule.readLockFile(nestedCtx); + expect(readCtx.state.lockFile?.result).toBeNull(); + + const nestedLock = LockFileModule.createEmptyLock("0.4.0"); + const writeCtx = await LockFileModule.writeLockFile(readCtx, nestedLock); + + expect(writeCtx.state.lockFileWrite?.result?.path).toBe(nestedLockPath); + expect(JSON.parse(await fs.readFile(parentLockPath, "utf8"))).toEqual(parentLock); + expect(JSON.parse(await fs.readFile(nestedLockPath, "utf8"))).toEqual(nestedLock); + }); }); diff --git a/cli/test/modules/lockFile/validators.test.ts b/cli/test/modules/lockFile/validators.test.ts index dbc85103..65fad300 100644 --- a/cli/test/modules/lockFile/validators.test.ts +++ b/cli/test/modules/lockFile/validators.test.ts @@ -1,28 +1,56 @@ import { describe, expect, it } from "vitest"; import { validateLockFile } from "../../../src/modules/lockFile/validators"; -describe("validateLockFile", () => { - const validLock = { +const deployment = { + diamond: "0x1234567890abcdef1234567890abcdef12345678", + facets: { + FacetA: "0xabcdef1234567890abcdef1234567890abcdef12", + }, + facetHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", + lastSync: "2026-08-03T12:00:00Z", + txHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", +}; + +function lockWith(chainDeployments: unknown) { + return { compose: "0.0.3", deployments: { MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: { - FacetA: "0xabcdef1234567890abcdef1234567890abcdef12", - }, - facetHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", - }, + sepolia: chainDeployments, }, }, }; +} + +function lockWithDeployment(overrides: Record, instance = "default") { + return lockWith({ [instance]: { ...deployment, ...overrides } }); +} + +describe("validateLockFile", () => { + const validLock = lockWith({ default: deployment }); it("accepts valid lock file structure", () => { expect(() => validateLockFile(validLock)).not.toThrow(); }); + it("accepts optional Hardhat Ignition deployment metadata", () => { + expect(() => validateLockFile(lockWithDeployment({ + ignitionDeploymentId: "compose-my-diamond-local-default-abcdef12", + }))).not.toThrow(); + }); + + it("rejects an empty Hardhat Ignition deployment ID", () => { + expect(() => validateLockFile(lockWithDeployment({ ignitionDeploymentId: "" }))) + .toThrow("invalid 'ignitionDeploymentId'"); + }); + + it("accepts multiple instances on one chain", () => { + expect(() => validateLockFile(lockWith({ + default: deployment, + staging: { ...deployment, diamond: "0x9999999999999999999999999999999999999999" }, + }))).not.toThrow(); + }); + it("rejects null input", () => { expect(() => validateLockFile(null)).toThrow("Lock file must be a JSON object"); }); @@ -36,7 +64,7 @@ describe("validateLockFile", () => { expect(() => validateLockFile(invalid)).toThrow("missing 'compose' version string"); }); - it("rejects non-string compose version", () => { + it("rejects invalid compose version", () => { const invalid = { compose: 123, deployments: {} }; expect(() => validateLockFile(invalid)).toThrow("missing 'compose' version string"); }); @@ -51,116 +79,54 @@ describe("validateLockFile", () => { expect(() => validateLockFile(invalid)).toThrow("missing 'deployments' object"); }); - it("rejects invalid diamond address", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "not-an-address", - facets: {}, - facetHash: "0x...", - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x...", - }, - }, - }, - }; + it("rejects non-object chain deployments", () => { + expect(() => validateLockFile(lockWith("string"))) + .toThrow("Deployments for 'MyDiamond' on 'sepolia' must be an object"); + }); + + it("rejects non-object instance deployments", () => { + expect(() => validateLockFile(lockWith({ default: "string" }))) + .toThrow("Deployment for 'MyDiamond' on 'sepolia' instance 'default' must be an object"); + }); + it("explains the legacy two-level lock format", () => { + expect(() => validateLockFile(lockWith(deployment))).toThrow("legacy lock format"); + }); + + it("rejects invalid diamond address", () => { + const invalid = lockWithDeployment({ diamond: "not-an-address" }); expect(() => validateLockFile(invalid)).toThrow("invalid or missing 'diamond' address"); }); it("rejects missing facets", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facetHash: "0x...", - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x...", - }, - }, - }, - }; - + const invalid = lockWithDeployment({ facets: undefined }); expect(() => validateLockFile(invalid)).toThrow("missing 'facets' object"); }); it("rejects invalid facet address", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: { - FacetA: "not-an-address", - }, - facetHash: "0x...", - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x...", - }, - }, - }, - }; - + const invalid = lockWithDeployment({ facets: { FacetA: "not-an-address" } }); expect(() => validateLockFile(invalid)).toThrow("invalid address for facet 'FacetA'"); }); it("rejects missing facetHash", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: {}, - lastSync: "2026-08-03T12:00:00Z", - txHash: "0x...", - }, - }, - }, - }; - + const invalid = lockWithDeployment({ facetHash: undefined }); expect(() => validateLockFile(invalid)).toThrow("invalid or missing 'facetHash'"); }); it("rejects invalid lastSync", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: {}, - facetHash: "0x...", - lastSync: "not-a-date", - txHash: "0x...", - }, - }, - }, - }; - + const invalid = lockWithDeployment({ lastSync: "not-a-date" }); expect(() => validateLockFile(invalid)).toThrow("invalid or missing 'lastSync' timestamp"); }); it("rejects missing txHash", () => { - const invalid = { - compose: "0.0.3", - deployments: { - MyDiamond: { - sepolia: { - diamond: "0x1234567890abcdef1234567890abcdef12345678", - facets: {}, - facetHash: "0x...", - lastSync: "2026-08-03T12:00:00Z", - }, - }, - }, - }; - + const invalid = lockWithDeployment({ txHash: undefined }); expect(() => validateLockFile(invalid)).toThrow("invalid or missing 'txHash'"); }); + + it("names the offending instance in field errors", () => { + const invalid = lockWithDeployment({ diamond: "not-an-address" }, "staging"); + expect(() => validateLockFile(invalid)).toThrow( + "'MyDiamond' on 'sepolia' instance 'staging': invalid or missing 'diamond' address", + ); + }); }); diff --git a/cli/test/modules/pipelineBuilder/pipelineBuilder.test.ts b/cli/test/modules/pipelineBuilder/pipelineBuilder.test.ts index 5a957103..b881ac36 100644 --- a/cli/test/modules/pipelineBuilder/pipelineBuilder.test.ts +++ b/cli/test/modules/pipelineBuilder/pipelineBuilder.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it, vi } from "vitest"; import { Context } from "../../../src/context/context"; import { PipelineBuilderModule } from "../../../src/modules/pipelineBuilder/module"; +import { TestPipeline } from "../../../src/pipelines/testPipeline"; import { ValidatePipeline } from "../../../src/pipelines/validatePipeline"; describe("PipelineBuilderModule", () => { @@ -19,4 +20,20 @@ describe("PipelineBuilderModule", () => { execute.mockRestore(); } }); + + it("routes the test command to TestPipeline", async () => { + const ctx = Context.create(); + ctx.param.command = "test"; + const execute = vi.spyOn(TestPipeline, "execute").mockResolvedValue(ctx); + + try { + const result = await PipelineBuilderModule.route(ctx); + + expect(result).toBe(ctx); + expect(execute).toHaveBeenCalledWith(ctx); + expect(ctx.state.commandSelected?.success).toBe(true); + } finally { + execute.mockRestore(); + } + }); }); diff --git a/cli/test/modules/preflight/module.test.ts b/cli/test/modules/preflight/module.test.ts index 2007c45a..2b9ddee8 100644 --- a/cli/test/modules/preflight/module.test.ts +++ b/cli/test/modules/preflight/module.test.ts @@ -15,12 +15,23 @@ describe("PreflightModule", () => { isBinaryInPath.mockClear(); }); - it("requires forge for Foundry", async () => { + it("requires forge and npm for Foundry when dependencies will be installed", async () => { const ctx = Context.create(); ctx.param.framework = "foundry"; await expect(PreflightModule.check(ctx)).resolves.toBe(ctx); expect(isBinaryInPath).toHaveBeenCalledWith("forge"); + expect(isBinaryInPath).toHaveBeenCalledWith("npm"); + }); + + it("skips npm for Foundry when dependency installation is disabled", async () => { + const ctx = Context.create(); + ctx.param.framework = "foundry"; + ctx.param.installDeps = false; + + await PreflightModule.check(ctx); + expect(isBinaryInPath).toHaveBeenCalledWith("forge"); + expect(isBinaryInPath).not.toHaveBeenCalledWith("npm"); }); it("requires npm when Hardhat dependencies will be installed", async () => { @@ -30,14 +41,15 @@ describe("PreflightModule", () => { await PreflightModule.check(ctx); expect(isBinaryInPath).toHaveBeenCalledWith("npm"); + expect(isBinaryInPath).toHaveBeenCalledWith("git"); }); - it("skips npm when Hardhat dependency installation is disabled", async () => { + it("rejects --no-install-deps for Hardhat because the official initializer installs its template", async () => { const ctx = Context.create(); ctx.param.framework = "hardhat"; ctx.param.installDeps = false; - await PreflightModule.check(ctx); + await expect(PreflightModule.check(ctx)).rejects.toThrow("official non-interactive initializer installs"); expect(isBinaryInPath).not.toHaveBeenCalled(); }); }); diff --git a/cli/test/modules/deployGeneration/harness.ts b/cli/test/modules/scaffoldHarness.ts similarity index 88% rename from cli/test/modules/deployGeneration/harness.ts rename to cli/test/modules/scaffoldHarness.ts index 7d2b286d..340e7db2 100644 --- a/cli/test/modules/deployGeneration/harness.ts +++ b/cli/test/modules/scaffoldHarness.ts @@ -1,14 +1,13 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; -import { ComposeContext } from "../../../src/context/types"; -import { Context } from "../../../src/context/context"; -import { BasesCatalog, FacetEntry } from "../../../src/modules/config/types"; +import { ComposeContext } from "../../src/context/types"; +import { Context } from "../../src/context/context"; +import { BasesCatalog, FacetEntry } from "../../src/modules/config/types"; -export type DeployGenerationHarness = { +export type ScaffoldHarness = { ctx: ComposeContext; projectRoot: string; - scriptRoot: string; cleanup(): Promise; }; @@ -107,14 +106,14 @@ function scaffoldEntry(facetName: FacetName) { } /** - * Builds the Compose context needed to test a full ERC-20 deploy script. + * Creates a temporary project context with a full ERC-20 catalog selection. * - * It selects every facet used by the snapshot script: the ERC-20 base and - * extensions, DiamondUpgrade, Owner with renounce, and AccessControl batches. + * It selects every facet used by the init-stage fixtures: the ERC-20 base and + * extensions, DiamondUpgrade, Owner with renounce, and AccessControl batches, + * and records a matching scaffold map. */ -export async function createDeployGenerationHarness(): Promise { - const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-cli-deploy-generation-")); - const scriptRoot = path.join(projectRoot, "script"); +export async function createScaffoldHarness(): Promise { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-cli-scaffold-")); const ctx = Context.create(); ctx.param.projectRoot = projectRoot; @@ -140,7 +139,6 @@ export async function createDeployGenerationHarness(): Promise fs.rm(projectRoot, { recursive: true, force: true }), }; } diff --git a/cli/test/modules/scaffolding/module.test.ts b/cli/test/modules/scaffolding/module.test.ts index 7df8d0e8..6972efbe 100644 --- a/cli/test/modules/scaffolding/module.test.ts +++ b/cli/test/modules/scaffolding/module.test.ts @@ -2,12 +2,12 @@ import fs from "node:fs/promises"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { ScaffoldingModule } from "../../../src/modules/scaffolding/module"; -import { createDeployGenerationHarness } from "../deployGeneration/harness"; +import { createScaffoldHarness } from "../scaffoldHarness"; /** Tests compose.json assembly and persistence from a prepared scaffold map. */ describe("ScaffoldingModule", () => { it("writes selected package facets to compose.json", async () => { - const harness = await createDeployGenerationHarness(); + const harness = await createScaffoldHarness(); const contractSourceRoot = path.join(harness.projectRoot, "src"); try { @@ -24,11 +24,16 @@ describe("ScaffoldingModule", () => { contract: string; facets: Record; }>; + chains: Record; }; const diamond = composeJson.diamonds["my-diamond"]; expect(composeJson.project).toBe("my-diamond"); expect(composeJson.framework).toBe("foundry"); + expect(composeJson.chains).toEqual({ + local: { rpc: "http://127.0.0.1:8545", chainId: 31337 }, + sepolia: { rpc: "${SEPOLIA_RPC_URL}", chainId: 11155111 }, + }); expect(diamond.contract).toBe("src/Diamond.sol:Diamond"); expect(Object.keys(diamond.facets)).toHaveLength(16); expect(diamond.facets.ERC20DataFacet).toEqual({ diff --git a/cli/test/modules/testGeneration/module.test.ts b/cli/test/modules/testGeneration/module.test.ts index 6cfcd47a..b90bb122 100644 --- a/cli/test/modules/testGeneration/module.test.ts +++ b/cli/test/modules/testGeneration/module.test.ts @@ -2,9 +2,8 @@ import fs from "node:fs/promises"; import path from "node:path"; import { describe, expect, it } from "vitest"; import { ModuleState } from "../../../src/context/types"; -import { DeployGenerationModule } from "../../../src/modules/deployGeneration/module"; import { TestGenerationModule } from "../../../src/modules/testGeneration/module"; -import { createDeployGenerationHarness } from "../deployGeneration/harness"; +import { createScaffoldHarness } from "../scaffoldHarness"; type TestGenerationResult = { outputPath: string; @@ -12,14 +11,13 @@ type TestGenerationResult = { framework: string; }; -/** Tests framework test generation using the deploy model as prerequisite state. */ +/** Tests framework test generation from the scaffold map and selected facets. */ describe("TestGenerationModule", () => { it("generates a Foundry Diamond test for every selected facet", async () => { - const harness = await createDeployGenerationHarness(); + const harness = await createScaffoldHarness(); const testRoot = path.join(harness.projectRoot, "test"); try { - await DeployGenerationModule.generateDeployScript(harness.ctx, harness.scriptRoot); const result = await TestGenerationModule.generateTestFile(harness.ctx, testRoot); const state = result.state.generateTestFile as ModuleState; const source = await fs.readFile(path.join(testRoot, "Diamond.t.sol"), "utf8"); diff --git a/cli/test/modules/validation/astSelectors.test.ts b/cli/test/modules/validation/astSelectors.test.ts index 003b2526..3fd19400 100644 --- a/cli/test/modules/validation/astSelectors.test.ts +++ b/cli/test/modules/validation/astSelectors.test.ts @@ -2,10 +2,8 @@ import { describe, expect, it, vi } from "vitest"; import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; -import { - IFrameworkAdapter, - SolidityAstSource, -} from "../../../src/adapters/IFrameworkAdapter/interface"; +import { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; +import { SolidityAstSource } from "../../../src/adapters/IFrameworkAdapter/types"; import { HashingAdapter } from "../../../src/adapters/IHashingAdapter/adapter"; import { Context } from "../../../src/context/context"; import { ModuleState } from "../../../src/context/types"; diff --git a/cli/test/modules/validation/project.test.ts b/cli/test/modules/validation/project.test.ts index 70496191..1d0cea3f 100644 --- a/cli/test/modules/validation/project.test.ts +++ b/cli/test/modules/validation/project.test.ts @@ -218,8 +218,8 @@ describe("validation project loader", () => { } }); - it("rejects package facet sources when both package roots contain a match", async () => { - const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-package-ambiguous-")); + it("prefers the Foundry package root when both package roots contain a match", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-package-foundry-")); const packageSourcePath = path.join( projectRoot, "node_modules", @@ -265,6 +265,118 @@ describe("validation project loader", () => { ); ctx.param.projectRoot = projectRoot; + const project = await loadValidationProject(ctx); + + expect(project.facetSources).toEqual([ + { contractName: "PackageFacet", sourcePath: foundrySourcePath }, + ]); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); + + it("prefers the node_modules package root when the project uses Hardhat", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-package-hardhat-")); + const packageSourcePath = path.join( + projectRoot, + "node_modules", + "@perfect-abstractions", + "compose", + "diamond", + "PackageFacet.sol", + ); + const foundrySourcePath = path.join( + projectRoot, + "lib", + "Compose", + "src", + "diamond", + "PackageFacet.sol", + ); + const ctx = Context.create(); + + try { + await fs.mkdir(path.dirname(packageSourcePath), { recursive: true }); + await fs.mkdir(path.dirname(foundrySourcePath), { recursive: true }); + await fs.writeFile(packageSourcePath, "contract PackageFacet {}", "utf8"); + await fs.writeFile(foundrySourcePath, "contract PackageFacet {}", "utf8"); + await fs.writeFile( + path.join(projectRoot, "compose.json"), + JSON.stringify({ + framework: "hardhat", + diamonds: { + Example: { + contract: "contracts/Diamond.sol:Diamond", + facets: { + PackageFacet: { + source: "package", + contract: "PackageFacet", + package: "@perfect-abstractions/compose", + }, + }, + }, + }, + }), + "utf8", + ); + ctx.param.projectRoot = projectRoot; + + const project = await loadValidationProject(ctx); + + expect(project.facetSources).toEqual([ + { contractName: "PackageFacet", sourcePath: packageSourcePath }, + ]); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); + + it("rejects package facets that are ambiguous within the selected package root", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-package-ambiguous-")); + const firstSourcePath = path.join( + projectRoot, + "lib", + "Compose", + "src", + "first", + "PackageFacet.sol", + ); + const secondSourcePath = path.join( + projectRoot, + "lib", + "Compose", + "src", + "second", + "PackageFacet.sol", + ); + const ctx = Context.create(); + + try { + await fs.mkdir(path.dirname(firstSourcePath), { recursive: true }); + await fs.mkdir(path.dirname(secondSourcePath), { recursive: true }); + await fs.writeFile(firstSourcePath, "contract PackageFacet {}", "utf8"); + await fs.writeFile(secondSourcePath, "contract PackageFacet {}", "utf8"); + await fs.writeFile( + path.join(projectRoot, "compose.json"), + JSON.stringify({ + framework: "foundry", + diamonds: { + Example: { + contract: "src/Diamond.sol:Diamond", + facets: { + PackageFacet: { + source: "package", + contract: "PackageFacet", + package: "@perfect-abstractions/compose", + }, + }, + }, + }, + }), + "utf8", + ); + ctx.param.projectRoot = projectRoot; + await expect(loadValidationProject(ctx)).rejects.toThrow( /Package facet source is ambiguous: @perfect-abstractions\/compose\/PackageFacet\.sol/, ); @@ -321,4 +433,58 @@ describe("validation project loader", () => { await fs.rm(projectRoot, { recursive: true, force: true }); } }); + + it("rejects a facet contract name that is not a Solidity identifier", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-project-name-")); + + try { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + diamonds: { + Example: { + contract: "src/Diamond.sol:Diamond", + facets: { + CounterFacet: { + source: "local", + contract: 'src/CounterFacet.sol:CounterFacet"; contract Evil {}', + }, + }, + }, + }, + }), "utf8"); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await expect(loadValidationProject(ctx)).rejects.toThrow("Invalid Solidity contract name"); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); + + it("rejects a diamond contract name that is not a Solidity identifier", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-validation-diamond-name-")); + + try { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + diamonds: { + Example: { + contract: 'src/Diamond.sol:Diamond"; contract Evil {}', + facets: { + CounterFacet: { + source: "local", + contract: "src/CounterFacet.sol:CounterFacet", + }, + }, + }, + }, + }), "utf8"); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await expect(loadValidationProject(ctx)).rejects.toThrow("Invalid Solidity contract name"); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); }); diff --git a/cli/test/modules/validation/virtualStorageLayout.test.ts b/cli/test/modules/validation/virtualStorageLayout.test.ts index a49beb0d..2b2e830b 100644 --- a/cli/test/modules/validation/virtualStorageLayout.test.ts +++ b/cli/test/modules/validation/virtualStorageLayout.test.ts @@ -1,7 +1,7 @@ import { readFileSync } from "node:fs"; import { resolve } from "node:path"; import { describe, expect, it } from "vitest"; -import { SolidityAstSource } from "../../../src/adapters/IFrameworkAdapter/interface"; +import { SolidityAstSource } from "../../../src/adapters/IFrameworkAdapter/types"; import { FacetReference, VirtualStorageLayoutRecord, diff --git a/cli/test/pipelines/accountPipeline.test.ts b/cli/test/pipelines/accountPipeline.test.ts new file mode 100644 index 00000000..fe19ba6e --- /dev/null +++ b/cli/test/pipelines/accountPipeline.test.ts @@ -0,0 +1,520 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const mocks = vi.hoisted(() => ({ + runCommandCaptureStdout: vi.fn(), + isInteractive: vi.fn(() => false), + confirm: vi.fn(async () => true), +})); + +vi.mock("../../src/utils/exec", () => ({ runCommandCaptureStdout: mocks.runCommandCaptureStdout })); +vi.mock("../../src/utils/inquirer", async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + isInteractive: mocks.isInteractive, + loadPrompts: async () => ({ confirm: mocks.confirm, input: vi.fn() }), + }; +}); + +import { Context } from "../../src/context/context"; +import type { ComposeContext, ModuleState } from "../../src/context/types"; +import type { AccountActionResult } from "../../src/modules/accounts/types"; +import { AccountPipeline } from "../../src/pipelines/accountPipeline"; + +let projectRoot: string; +let ctx: ReturnType; + +beforeEach(async () => { + mocks.runCommandCaptureStdout.mockReset(); + mocks.isInteractive.mockReset().mockReturnValue(false); + mocks.confirm.mockReset().mockResolvedValue(true); + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-accounts-")); + vi.spyOn(os, "homedir").mockReturnValue(projectRoot); + ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + accounts: {}, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 } }, + }), "utf8"); +}); + +afterEach(async () => { + vi.restoreAllMocks(); + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +async function readComposeJson(): Promise> { + return JSON.parse(await fs.readFile(path.join(projectRoot, "compose.json"), "utf8")) as Record; +} + +function readAccountState(ctx: ComposeContext): ModuleState { + return ctx.state.account as ModuleState; +} + +function expectAccountFailure(ctx: ComposeContext, message: string): void { + expect(ctx.status).toMatchObject({ + success: false, + stopped: true, + failedAt: "account", + }); + + const state = readAccountState(ctx); + expect(state.success).toBe(false); + expect(state.result).toBeNull(); + expect(state.error?.message).toContain(message); +} + +describe("AccountPipeline", () => { + it("registers a public address and optional chain default without storing credentials", async () => { + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + ctx.param.action = "setup"; + ctx.param.accountName = "deployer"; + ctx.param.address = "0x00000000000000000000000000000000000000a1"; + ctx.param.foundryAccount = "mainnet-deployer"; + ctx.param.chain = "local"; + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toMatchObject({ + action: "setup", + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + framework: "foundry", + foundryAccount: "mainnet-deployer", + chainKey: "local", + }); + + const composeJson = await readComposeJson(); + expect(composeJson.accounts).toEqual({ + deployer: { + address: "0x00000000000000000000000000000000000000A1", + foundry: { account: "mainnet-deployer" }, + }, + }); + expect(composeJson.chains).toEqual({ + local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" }, + }); + expect(JSON.stringify(composeJson)).not.toContain("privateKey"); + const output = log.mock.calls.flat().join("\n"); + expect(output).toContain("Account registered"); + expect(output).toContain(" Default chain: local"); + expect(output).toContain("Next steps"); + expect(output).toContain("cast wallet import mainnet-deployer"); + expect(output).toContain("Enter the key at Foundry's prompt, not in Compose."); + expect(output).toContain("compose account check deployer --chain local"); + }); + + it("prints exact Hardhat key-storage and check commands when the network variable is clear", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "hardhat", + accounts: {}, + chains: { sepolia: { rpc: "https://rpc.example.test", chainId: 11155111 } }, + }), "utf8"); + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + export default { + networks: { + sepolia: { + type: "http", + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], + }, + }, + }; + `, "utf8"); + ctx.param.action = "setup"; + ctx.param.accountName = "deployer"; + ctx.param.address = "0x00000000000000000000000000000000000000a1"; + ctx.param.chain = "sepolia"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + const output = log.mock.calls.flat().join("\n"); + expect(output).toContain("Account registered"); + expect(output).toContain(" Alias: deployer"); + expect(output).toContain(" Default chain: sepolia"); + expect(output).toContain("Next steps"); + expect(output).toContain("npx hardhat keystore set SEPOLIA_PRIVATE_KEY"); + expect(output).toContain("compose account check deployer --chain sepolia"); + expect(output).toContain("Use a key whose address matches the registered public address above."); + expect(output).not.toContain("COMPOSE_DEPLOYER_PRIVATE_KEY"); + expect(readAccountState(ctx).result).toHaveProperty("keyVariableName", "SEPOLIA_PRIVATE_KEY"); + }); + + it("prints clear fallback guidance when the Hardhat key variable is not detectable", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "hardhat", + accounts: {}, + chains: { sepolia: { rpc: "https://rpc.example.test", chainId: 11155111 } }, + }), "utf8"); + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), ` + export default { + networks: { + sepolia: { accounts: getCustomAccounts() }, + }, + }; + `, "utf8"); + ctx.param.action = "setup"; + ctx.param.accountName = "deployer"; + ctx.param.address = "0x00000000000000000000000000000000000000a1"; + ctx.param.chain = "sepolia"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + const output = log.mock.calls.flat().join("\n"); + expect(output).toContain("Configure the 'sepolia' network's signer in hardhat.config.ts."); + expect(output).toContain("compose account check deployer --chain sepolia"); + expect(output).not.toContain("npx hardhat keystore set"); + }); + + it("asks for an explicit chain in Hardhat check guidance when setup has no default", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "hardhat", + accounts: {}, + chains: { sepolia: { rpc: "https://rpc.example.test", chainId: 11155111 } }, + }), "utf8"); + ctx.param.action = "setup"; + ctx.param.accountName = "deployer"; + ctx.param.address = "0x00000000000000000000000000000000000000a1"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + const output = log.mock.calls.flat().join("\n"); + expect(output).toContain("compose account check deployer --chain "); + }); + + it("delegates Foundry key entry to cast's interactive keystore prompt", async () => { + const nativeAccount = "test-deployer"; + const address = "0x00000000000000000000000000000000000000a1"; + mocks.isInteractive.mockReturnValue(true); + mocks.runCommandCaptureStdout.mockImplementation(async (command, args) => { + expect(command).toBe("cast"); + expect(args).toEqual(["wallet", "import", nativeAccount, "--interactive"]); + const keystoreDirectory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(keystoreDirectory, { recursive: true }); + await fs.writeFile(path.join(keystoreDirectory, nativeAccount), "{}", "utf8"); + return `\n${nativeAccount} keystore was saved successfully. Address: ${address}\n`; + }); + ctx.param.action = "setup"; + ctx.param.accountName = "deployer"; + ctx.param.foundryAccount = nativeAccount; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toMatchObject({ + action: "setup", + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + foundryAccount: nativeAccount, + }); + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledOnce(); + expect((await readComposeJson()).accounts).toEqual({ + deployer: { + address: "0x00000000000000000000000000000000000000A1", + foundry: { account: nativeAccount }, + }, + }); + expect(log.mock.calls.flat().join("\n")).not.toContain("cast wallet import"); + expect(log.mock.calls.flat().join("\n")) + .toContain("compose account check deployer --chain "); + }); + + it("unlocks an existing Foundry keystore to resolve its address without importing again", async () => { + const nativeAccount = "sepolia-deployer"; + const address = "0x8836442b6b4843ba1f077406cc82fddb0f3d16ef"; + const keystoreDirectory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(keystoreDirectory, { recursive: true }); + await fs.writeFile( + path.join(keystoreDirectory, nativeAccount), + JSON.stringify({ crypto: {}, id: "test-id", version: 3 }), + "utf8", + ); + mocks.isInteractive.mockReturnValue(true); + mocks.runCommandCaptureStdout.mockImplementation(async (command, args, options) => { + expect(command).toBe("cast"); + expect(args).toEqual(["wallet", "address", "--account", nativeAccount]); + expect(options).toEqual({ cwd: projectRoot, forwardStdout: false }); + return `${address}\n`; + }); + ctx.param.action = "setup"; + ctx.param.accountName = nativeAccount; + ctx.param.chain = "local"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toMatchObject({ + action: "setup", + alias: nativeAccount, + address: "0x8836442b6B4843BA1f077406cC82FddB0F3D16eF", + foundryAccount: nativeAccount, + }); + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledOnce(); + expect(mocks.confirm).not.toHaveBeenCalled(); + expect(log.mock.calls.flat().join("\n")).not.toContain("cast wallet import"); + expect(log.mock.calls.flat().join("\n")) + .toContain(`compose account check ${nativeAccount} --chain local`); + expect((await readComposeJson()).accounts).toEqual({ + [nativeAccount]: { + address: "0x8836442b6B4843BA1f077406cC82FddB0F3D16eF", + foundry: { account: nativeAccount }, + }, + }); + }); + + it("requires a public address for an existing encrypted Foundry keystore in non-interactive setup", async () => { + const nativeAccount = "sepolia-deployer"; + const keystoreDirectory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(keystoreDirectory, { recursive: true }); + await fs.writeFile( + path.join(keystoreDirectory, nativeAccount), + JSON.stringify({ crypto: {}, id: "test-id", version: 3 }), + "utf8", + ); + ctx.param.action = "setup"; + ctx.param.accountName = nativeAccount; + const errorLog = vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure( + ctx, + "already exists, but its address is encrypted. Run setup interactively, set ETH_PASSWORD to a Foundry password-file path, or pass its public address with --address.", + ); + expect(errorLog).toHaveBeenCalledOnce(); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + expect(mocks.confirm).not.toHaveBeenCalled(); + }); + + it("rejects an unknown chain before prompting for or importing a Foundry key", async () => { + mocks.isInteractive.mockReturnValue(true); + ctx.param.action = "setup"; + ctx.param.accountName = "sepolia-deployer"; + ctx.param.chain = "sepolia"; + vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure(ctx, "Chain 'sepolia' was not found in compose.json."); + expect(mocks.confirm).not.toHaveBeenCalled(); + expect(mocks.runCommandCaptureStdout).not.toHaveBeenCalled(); + expect(await readComposeJson()).toEqual({ + framework: "foundry", + accounts: {}, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 } }, + }); + }); + + it("lists registered aliases and chain defaults", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "hardhat", + accounts: { deployer: { address: "0x00000000000000000000000000000000000000a1" } }, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" } }, + }), "utf8"); + ctx.param.action = "list"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ + action: "list", + entries: [{ alias: "deployer", address: "0x00000000000000000000000000000000000000a1" }], + defaults: [{ chainKey: "local", alias: "deployer" }], + }); + expect(log.mock.calls.flat().join("\n")).toContain("deployer"); + expect(log.mock.calls.flat().join("\n")).toContain("Default for local: deployer"); + }); + + it("checks a Foundry alias against its native keystore address", async () => { + vi.spyOn(os, "homedir").mockReturnValue(projectRoot); + const keystoreDirectory = path.join(projectRoot, ".foundry", "keystores"); + await fs.mkdir(keystoreDirectory, { recursive: true }); + await fs.writeFile( + path.join(keystoreDirectory, "deployer"), + JSON.stringify({ address: "00000000000000000000000000000000000000a1" }), + "utf8", + ); + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + accounts: { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "deployer" }, + }, + }, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" } }, + }), "utf8"); + ctx.param.action = "check"; + ctx.param.accountName = "deployer"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ + action: "check", + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + chainKey: "local", + }); + expect(log.mock.calls.flat().join("\n")).toContain("Account 'deployer' is available on local"); + }); + + it("checks a Hardhat alias against configured network signers", async () => { + const address = "0x00000000000000000000000000000000000000a1"; + await fs.writeFile(path.join(projectRoot, "package.json"), JSON.stringify({ + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", + }, + }), "utf8"); + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "hardhat", + accounts: { deployer: { address } }, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" } }, + }), "utf8"); + mocks.runCommandCaptureStdout.mockResolvedValue( + `COMPOSE_ACCOUNT_ADDRESSES:["${address}"]\n`, + ); + ctx.param.action = "check"; + ctx.param.accountName = "deployer"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ + action: "check", + alias: "deployer", + address: "0x00000000000000000000000000000000000000A1", + chainKey: "local", + }); + expect(mocks.runCommandCaptureStdout).toHaveBeenCalledWith( + "npx", + expect.arrayContaining(["hardhat", "run", "--no-compile", "--network", "local"]), + expect.objectContaining({ + cwd: projectRoot, + env: { COMPOSE_DEPLOY_RPC_URL: "http://127.0.0.1:8545" }, + forwardStdout: false, + }), + ); + expect(log.mock.calls.flat().join("\n")).toContain("Account 'deployer' is available on local"); + expect(await fs.readdir(path.join(projectRoot, ".compose", "hardhat"))) + .toEqual(["account-probe.ts"]); + await expect(fs.access(path.join(projectRoot, "scripts"))).rejects.toThrow(); + }); + + it("lists accounts without requiring a framework adapter", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + accounts: { deployer: { address: "0x00000000000000000000000000000000000000a1" } }, + }), "utf8"); + ctx.param.action = "list"; + vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ + action: "list", + entries: [{ alias: "deployer", address: "0x00000000000000000000000000000000000000a1" }], + defaults: [], + }); + }); + + it("lists an empty account set as successful state", async () => { + ctx.param.action = "list"; + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ + action: "list", + entries: [], + defaults: [], + }); + expect(log.mock.calls.flat().join("\n")).toContain("No Compose account aliases are configured."); + }); + + it("records an unknown action as a failure", async () => { + ctx.param.action = "unknown"; + vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure(ctx, "Use 'compose account setup '"); + expect(await readComposeJson()).toEqual({ + framework: "foundry", + accounts: {}, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 } }, + }); + }); + + it("requires an alias when setup is non-interactive", async () => { + ctx.param.action = "setup"; + vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure(ctx, "Account alias is required in non-interactive mode."); + }); + + it("records an unavailable account as a failure", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + accounts: { deployer: { address: "0x00000000000000000000000000000000000000a1" } }, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" } }, + }), "utf8"); + ctx.param.action = "check"; + ctx.param.accountName = "deployer"; + vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure( + ctx, + "Account 'deployer' (0x00000000000000000000000000000000000000A1) is not available in foundry on chain 'local'.", + ); + }); + + it("records removing a missing alias as a failure", async () => { + ctx.param.action = "remove"; + ctx.param.accountName = "missing"; + vi.spyOn(console, "error").mockImplementation(() => {}); + + await AccountPipeline.execute(ctx); + + expectAccountFailure(ctx, "Account alias 'missing' was not found in compose.json."); + expect(await readComposeJson()).toEqual({ + framework: "foundry", + accounts: {}, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 } }, + }); + }); + + it("removes only the Compose alias and clears its chain defaults", async () => { + await fs.writeFile(path.join(projectRoot, "compose.json"), JSON.stringify({ + framework: "foundry", + accounts: { + deployer: { + address: "0x00000000000000000000000000000000000000a1", + foundry: { account: "deployer" }, + }, + }, + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337, account: "deployer" } }, + }), "utf8"); + ctx.param.action = "remove"; + ctx.param.accountName = "deployer"; + + await AccountPipeline.execute(ctx); + + expect(readAccountState(ctx).result).toEqual({ action: "remove", alias: "deployer" }); + const composeJson = await readComposeJson(); + expect(composeJson.accounts).toEqual({}); + expect(composeJson.chains).toEqual({ + local: { rpc: "http://127.0.0.1:8545", chainId: 31337 }, + }); + }); +}); diff --git a/cli/test/pipelines/deployPipeline/deployE2EHarness.ts b/cli/test/pipelines/deployPipeline/deployE2EHarness.ts new file mode 100644 index 00000000..218cafe5 --- /dev/null +++ b/cli/test/pipelines/deployPipeline/deployE2EHarness.ts @@ -0,0 +1,290 @@ +import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"; +import fs from "node:fs/promises"; +import net from "node:net"; +import os from "node:os"; +import path from "node:path"; + +export const ANVIL_PRIVATE_KEY = + "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"; +const CHAIN_ID = 31337; +const COMPOSE_ROOT = path.resolve(__dirname, "../../../.."); +const DIAMOND_FIXTURE = path.join( + __dirname, + "..", + "validatePipeline", + "fixtures", + "bytecode", + "Diamond.sol", +); +const CLI_ENTRY = process.env.COMPOSE_E2E_CLI_ENTRY + ?? path.join(COMPOSE_ROOT, "cli", "dist", "index.js"); + +/** Passthrough arguments handing signing to Foundry with the first Anvil key. */ +export const SIGNER_ARGS = ["--", "--private-key", ANVIL_PRIVATE_KEY, "--non-interactive"]; + +type ProcessResult = { + code: number; + stdout: string; + stderr: string; +}; + +type LockDeployment = { + diamond: string; + facets: Record; + facetHash: string; + lastSync: string; + txHash: string; + deployer?: string; +}; + +export type DeployE2EHarness = { + projectRoot: string; + rpcUrl: string; + runAccount(args: string[], env?: NodeJS.ProcessEnv): Promise; + runDeploy(args: string[], env?: NodeJS.ProcessEnv): Promise; + runValidate(): Promise; + readDeployment(): Promise; + writeComposeJson(facets: Record, rpcUrl?: string): Promise; + cleanup(): Promise; +}; + +function runProcess( + command: string, + args: string[], + options: { cwd: string; env?: NodeJS.ProcessEnv }, +): Promise { + return new Promise((resolve, reject) => { + const child = spawn(command, args, { + cwd: options.cwd, + env: options.env ? { ...process.env, ...options.env } : process.env, + windowsHide: true, + }); + let stdout = ""; + let stderr = ""; + child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); }); + child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); }); + child.once("error", reject); + child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr })); + }); +} + +async function availablePort(): Promise { + return new Promise((resolve, reject) => { + const server = net.createServer(); + server.once("error", reject); + server.listen(0, "127.0.0.1", () => { + const address = server.address(); + const port = typeof address === "object" && address ? address.port : 0; + server.close((error) => error ? reject(error) : resolve(port)); + }); + }); +} + +async function waitForRPC(rpcUrl: string, process: ChildProcessWithoutNullStreams): Promise { + for (let attempt = 0; attempt < 100; attempt += 1) { + if (process.exitCode !== null) throw new Error("Anvil exited before its RPC endpoint was ready."); + try { + const response = await fetch(rpcUrl, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }), + }); + if (response.ok) return; + } catch { + // The endpoint is not listening yet. + } + await new Promise((resolve) => setTimeout(resolve, 100)); + } + throw new Error("Timed out waiting for Anvil RPC."); +} + +const BASE_FACETS = { + DiamondInspectFacet: { + source: "package", + contract: "DiamondInspectFacet", + package: "@perfect-abstractions/compose", + }, + CounterFacet: { + source: "local", + contract: "src/CounterFacet.sol:CounterFacet", + }, +}; + +const EXTRA_FACET = { + source: "local", + contract: "src/ExtraFacet.sol:ExtraFacet", +}; + +const COUNTER_FACET_SOURCE = `// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +contract CounterFacet { + uint256 private counterValue; + + function increment() external { + counterValue += 1; + } + + function counter() external view returns (uint256) { + return counterValue; + } + + function exportSelectors() external pure returns (bytes memory) { + return bytes.concat(this.increment.selector, this.counter.selector); + } +} +`; + +const EXTRA_FACET_SOURCE = `// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +contract ExtraFacet { + uint256 private doubledValue; + + function double(uint256 value) external { + doubledValue = value * 2; + } + + function doubled() external view returns (uint256) { + return doubledValue; + } + + function exportSelectors() external pure returns (bytes memory) { + return bytes.concat(this.double.selector, this.doubled.selector); + } +} +`; + +async function linkFoundryLibraries(projectRoot: string): Promise { + const libraryRoot = path.join(projectRoot, "lib"); + await fs.mkdir(libraryRoot, { recursive: true }); + const directoryType = process.platform === "win32" ? "junction" : "dir"; + await Promise.all([ + fs.symlink(COMPOSE_ROOT, path.join(libraryRoot, "Compose"), directoryType), + fs.symlink( + path.join(COMPOSE_ROOT, "lib", "forge-std"), + path.join(libraryRoot, "forge-std"), + directoryType, + ), + ]); +} + +async function writeComposeJson( + projectRoot: string, + rpcUrl: string, + facets: Record, +): Promise { + await fs.writeFile( + path.join(projectRoot, "compose.json"), + JSON.stringify( + { + project: "deploy-e2e", + compose: "0.3.0", + framework: "foundry", + diamonds: { + CounterDiamond: { + contract: "src/Diamond.sol:Diamond", + facets, + }, + }, + chains: { + local: { rpc: rpcUrl, chainId: CHAIN_ID }, + }, + }, + null, + 2, + ), + "utf8", + ); +} + +async function createProject(root: string, rpcUrl: string): Promise { + const projectRoot = path.join(root, "project"); + await Promise.all([ + fs.mkdir(path.join(projectRoot, "src"), { recursive: true }), + fs.mkdir(path.join(projectRoot, "script"), { recursive: true }), + ]); + await linkFoundryLibraries(projectRoot); + await Promise.all([ + fs.writeFile( + path.join(projectRoot, "foundry.toml"), + [ + "[profile.default]", + 'src = "src"', + 'script = "script"', + 'out = "out"', + 'libs = ["lib"]', + 'solc = "0.8.30"', + "optimizer = true", + "", + ].join("\n"), + "utf8", + ), + fs.writeFile( + path.join(projectRoot, "remappings.txt"), + "@perfect-abstractions/compose/=lib/Compose/src/\nforge-std/=lib/forge-std/src/\n", + "utf8", + ), + fs.copyFile(DIAMOND_FIXTURE, path.join(projectRoot, "src", "Diamond.sol")), + fs.writeFile(path.join(projectRoot, "src", "CounterFacet.sol"), COUNTER_FACET_SOURCE, "utf8"), + fs.writeFile(path.join(projectRoot, "src", "ExtraFacet.sol"), EXTRA_FACET_SOURCE, "utf8"), + ]); + await writeComposeJson(projectRoot, rpcUrl, BASE_FACETS); + return projectRoot; +} + +/** Starts Anvil and prepares a Foundry project for `compose deploy` E2E tests. */ +export async function createDeployE2EHarness(): Promise { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "compose-deploy-e2e-")); + const port = await availablePort(); + const rpcUrl = `http://127.0.0.1:${port}`; + const anvil = spawn("anvil", ["--silent", "--port", String(port), "--chain-id", String(CHAIN_ID)], { + cwd: root, + windowsHide: true, + }); + + try { + await waitForRPC(rpcUrl, anvil); + const projectRoot = await createProject(root, rpcUrl); + + return { + projectRoot, + rpcUrl, + runAccount: (args, env) => + runProcess(process.execPath, [CLI_ENTRY, "account", ...args, "--project-root", projectRoot], { + cwd: projectRoot, + env, + }), + runDeploy: (args, env) => + runProcess(process.execPath, [CLI_ENTRY, "deploy", "--project-root", projectRoot, ...args], { + cwd: projectRoot, + env, + }), + runValidate: () => + runProcess(process.execPath, [CLI_ENTRY, "validate", "--project-root", projectRoot], { + cwd: projectRoot, + }), + async readDeployment() { + const lock = JSON.parse( + await fs.readFile(path.join(projectRoot, "compose.lock"), "utf8"), + ) as { + deployments: Record>>; + }; + return lock.deployments.CounterDiamond.local.default; + }, + async writeComposeJson(facets, configuredRpcUrl = rpcUrl) { + await writeComposeJson(projectRoot, configuredRpcUrl, facets); + }, + async cleanup() { + anvil.kill("SIGTERM"); + await fs.rm(root, { recursive: true, force: true }); + }, + }; + } catch (error) { + anvil.kill("SIGTERM"); + await fs.rm(root, { recursive: true, force: true }); + throw error; + } +} + +export { BASE_FACETS, EXTRA_FACET }; diff --git a/cli/test/pipelines/deployPipeline/deployPipeline.test.ts b/cli/test/pipelines/deployPipeline/deployPipeline.test.ts new file mode 100644 index 00000000..b0c4d12b --- /dev/null +++ b/cli/test/pipelines/deployPipeline/deployPipeline.test.ts @@ -0,0 +1,321 @@ +import fs from "node:fs/promises"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { ComposeContext } from "../../../src/context/types"; + +import { DeployPipeline } from "../../../src/pipelines/deployPipeline"; +import { + createDeployProjectHarness, + DEFAULT_FACET_ADDRESSES, + DEFAULT_FACETS, + deploymentRecord, + type DeployProjectHarness, +} from "../../modules/deployPlan/harness"; + +let harness: DeployProjectHarness; +let logSpy: ReturnType; +let errorSpy: ReturnType; + +beforeEach(async () => { + harness = await createDeployProjectHarness(); + logSpy = vi.spyOn(console, "log").mockImplementation(() => {}); + errorSpy = vi.spyOn(console, "error").mockImplementation(() => {}); +}); + +afterEach(async () => { + vi.restoreAllMocks(); + await harness.cleanup(); +}); + +function output(): string { + return [...logSpy.mock.calls, ...errorSpy.mock.calls] + .map((call) => call.map((value) => String(value)).join(" ")) + .join("\n"); +} + +function scriptPath(): string { + return path.join(harness.projectRoot, "script", "ComposeDeploy.s.sol"); +} + +async function executePipeline(ctx: ComposeContext): Promise { + return DeployPipeline.execute(ctx); +} + +describe("DeployPipeline option handling", () => { + it("rejects --dry-run together with --broadcast", async () => { + harness.ctx.param.dryRun = true; + harness.ctx.param.broadcast = true; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("Use either --dry-run or --broadcast"); + }); + + it("rejects network endpoint overrides hidden in Foundry passthrough", async () => { + harness.ctx.param.passthrough = ["--rpc-url", "https://other.example"]; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("cannot change the planned deployment target"); + expect(output()).toContain("compose deploy --chain and --rpc-url "); + }); +}); + +describe("DeployPipeline dry-run", () => { + it("requires a prepared script instead of previewing the script source", async () => { + harness.ctx.param.dryRun = true; + harness.ctx.param.passthrough = ["--sender", "0x00000000000000000000000000000000000000a1"]; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("missing, modified, or stale"); + expect(output()).toContain("Run 'compose deploy'"); + expect(output()).toContain("retry with --dry-run"); + expect(output()).not.toContain("--simulate"); + expect(output()).not.toContain("contract ComposeDeployScript is Script"); + + await expect(fs.access(scriptPath())).rejects.toThrow(); + await expect(fs.access(path.join(harness.projectRoot, "compose.lock"))).rejects.toThrow(); + }); +}); + +describe("DeployPipeline in-sync", () => { + it("reports nothing to do when the lock record matches compose.json", async () => { + await harness.writeLock({ + CounterDiamond: { local: { default: deploymentRecord(DEFAULT_FACET_ADDRESSES) } }, + }); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(true); + expect(output()).toContain("In sync"); + await expect(fs.access(scriptPath())).rejects.toThrow(); + }); +}); + +describe("DeployPipeline composition drift", () => { + it("prints the diff and stops without generating a script", async () => { + await harness.writeLock({ + CounterDiamond: { + local: { + default: deploymentRecord({ + DiamondInspectFacet: DEFAULT_FACET_ADDRESSES.DiamondInspectFacet, + }), + }, + }, + }); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(ctx.status.stopped).toBe(true); + expect(ctx.status.failedAt).toBe("deployPlan"); + expect(output()).toContain("differs from compose.json"); + expect(output()).toContain("CounterFacet"); + await expect(fs.access(scriptPath())).rejects.toThrow(); + }); +}); + +describe("DeployPipeline script generation", () => { + it("writes the managed script and gives review instructions without prompting or broadcasting", async () => { + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(true); + expect(output()).toContain("script/ComposeDeploy.s.sol"); + expect(output()).toContain("Review this artifact before deploying."); + expect(output()).toContain("compose deploy --dry-run"); + expect(output()).toContain("compose deploy --broadcast"); + expect(output()).not.toContain("Run the deployment script now?"); + expect(output()).not.toContain(harness.projectRoot); + + const source = await fs.readFile(scriptPath(), "utf8"); + expect(source).toMatch(/^\/\* compose-plan-hash: 0x[0-9a-f]{64} \*\/$/m); + expect(source).toContain("CounterFacet counterFacet = new CounterFacet();"); + await expect(fs.access(path.join(harness.projectRoot, "compose.lock"))).rejects.toThrow(); + }); + + it("reuses a script whose rendered-source hash still matches", async () => { + await executePipeline(harness.ctx); + const firstWrite = await fs.stat(scriptPath()); + await new Promise((resolve) => setTimeout(resolve, 20)); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(true); + const secondWrite = await fs.stat(scriptPath()); + expect(secondWrite.mtimeMs).toBe(firstWrite.mtimeMs); + }); + + it("reuses an artifact generated in another checkout root", async () => { + await executePipeline(harness.ctx); + const source = await fs.readFile(scriptPath(), "utf8"); + const other = await createDeployProjectHarness(); + try { + const otherScriptPath = path.join(other.projectRoot, "script", "ComposeDeploy.s.sol"); + await fs.mkdir(path.dirname(otherScriptPath), { recursive: true }); + await fs.writeFile(otherScriptPath, source, "utf8"); + const firstWrite = await fs.stat(otherScriptPath); + await new Promise((resolve) => setTimeout(resolve, 20)); + + const ctx = await executePipeline(other.ctx); + + expect(ctx.status.success).toBe(true); + await expect(fs.readFile(otherScriptPath, "utf8")).resolves.toBe(source); + const secondWrite = await fs.stat(otherScriptPath); + expect(secondWrite.mtimeMs).toBe(firstWrite.mtimeMs); + } finally { + await other.cleanup(); + } + }); +}); + +describe("DeployPipeline framework selection", () => { + it("generates the Hardhat managed script for a Hardhat project", async () => { + await harness.writeComposeJson(DEFAULT_FACETS, { framework: "hardhat" }); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(true); + const hardhatScriptPath = path.join(harness.projectRoot, "ignition", "modules", "ComposeDeploy.ts"); + const source = await fs.readFile(hardhatScriptPath, "utf8"); + expect(source).toMatch(/^\/\/ compose-plan-hash: 0x[0-9a-f]{64}$/m); + expect(source).toContain('buildModule("ComposeDeploy"'); + expect(source).toContain('m.contract("CounterFacet", [], {'); + expect(source).toContain('m.contract("Diamond", [[diamondInspectFacet, counterFacet]], {'); + await expect(fs.access(scriptPath())).rejects.toThrow(); + expect(output()).toContain("ignition/modules/ComposeDeploy.ts"); + expect(output()).toContain("../../src/CounterFacet.sol"); + expect(output()).not.toContain(harness.projectRoot); + }); +}); + +describe("DeployPipeline broadcast gating", () => { + it("refuses --broadcast when the script is missing or stale and stdin is not interactive", async () => { + harness.ctx.param.broadcast = true; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(ctx.status.failedAt).toBe("deployScript"); + expect(output()).toContain("missing, modified, or stale"); + }); + + it("refuses --broadcast when an existing script belongs to another plan", async () => { + await fs.mkdir(path.dirname(scriptPath()), { recursive: true }); + await fs.writeFile(scriptPath(), `// compose-plan-hash: 0x${"ef".repeat(32)}\n`, "utf8"); + harness.ctx.param.broadcast = true; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("missing, modified, or stale"); + }); + + it("refuses --broadcast when the body changed but the plan marker is unchanged", async () => { + await executePipeline(harness.ctx); + const originalSource = await fs.readFile(scriptPath(), "utf8"); + const modifiedSource = originalSource.replace( + " vm.stopBroadcast();", + " payable(address(0xdead)).transfer(1 ether);\n vm.stopBroadcast();", + ); + expect(modifiedSource).not.toBe(originalSource); + const planMarker = originalSource.match(/\/\* compose-plan-hash: 0x[0-9a-f]{64} \*\//)?.[0]; + expect(planMarker).toBeDefined(); + if (!planMarker) throw new Error("Generated script is missing its plan hash marker."); + expect(modifiedSource).toContain(planMarker); + await fs.writeFile(scriptPath(), modifiedSource, "utf8"); + harness.ctx.param.broadcast = true; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(ctx.status.failedAt).toBe("deployScript"); + expect(output()).toContain("missing, modified, or stale"); + await expect(fs.readFile(scriptPath(), "utf8")).resolves.toBe(modifiedSource); + }); + + it("keeps the reviewable Ignition module stable across supported toolbox choices", async () => { + await harness.writeComposeJson(DEFAULT_FACETS, { framework: "hardhat" }); + await executePipeline(harness.ctx); + + const hardhatModulePath = path.join(harness.projectRoot, "ignition", "modules", "ComposeDeploy.ts"); + const ethersSource = await fs.readFile(hardhatModulePath, "utf8"); + + await fs.writeFile( + path.join(harness.projectRoot, "package.json"), + JSON.stringify({ + type: "module", + devDependencies: { + hardhat: "^3.8.0", + "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0", + }, + }), + "utf8", + ); + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(true); + await expect(fs.readFile(hardhatModulePath, "utf8")).resolves.toBe(ethersSource); + }); +}); + +describe("DeployPipeline code-generation validation", () => { + it("refuses to generate a script for a malicious contract name", async () => { + await harness.writeComposeJson({ + CounterFacet: { + source: "local", + contract: 'src/CounterFacet.sol:CounterFacet"; contract Evil {}', + }, + }); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(ctx.status.failedAt).toBe("deployPlan"); + expect(output()).toContain("Invalid Solidity contract name"); + await expect(fs.access(scriptPath())).rejects.toThrow(); + }); + + it("refuses to generate a script for a malicious facet source path", async () => { + await harness.writeComposeJson({ + CounterFacet: { + source: "local", + contract: 'src/Evil".sol:CounterFacet', + }, + }); + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(ctx.status.failedAt).toBe("deployPlan"); + expect(output()).toContain("Invalid Solidity import path"); + await expect(fs.access(scriptPath())).rejects.toThrow(); + }); +}); + +describe("DeployPipeline artifact freshness", () => { + it("does not regenerate a missing or stale script before broadcast", async () => { + harness.ctx.param.broadcast = true; + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("Run 'compose deploy', review the generated artifact"); + await expect(fs.access(scriptPath())).rejects.toThrow(); + }); + + it("refuses a script modified after review", async () => { + await executePipeline(harness.ctx); + const modifiedSource = `${await fs.readFile(scriptPath(), "utf8")}\n// changed\n`; + await fs.writeFile(scriptPath(), modifiedSource, "utf8"); + harness.ctx.param.broadcast = true; + + const ctx = await executePipeline(harness.ctx); + + expect(ctx.status.success).toBe(false); + expect(output()).toContain("missing, modified, or stale"); + await expect(fs.readFile(scriptPath(), "utf8")).resolves.toBe(modifiedSource); + }); +}); diff --git a/cli/test/pipelines/deployPipeline/deployPipelineE2E.test.ts b/cli/test/pipelines/deployPipeline/deployPipelineE2E.test.ts new file mode 100644 index 00000000..96fc29fa --- /dev/null +++ b/cli/test/pipelines/deployPipeline/deployPipelineE2E.test.ts @@ -0,0 +1,257 @@ +import fs from "node:fs/promises"; +import { execFileSync } from "node:child_process"; +import os from "node:os"; +import path from "node:path"; +import { privateKeyToAccount } from "viem/accounts"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { + BASE_FACETS, + ANVIL_PRIVATE_KEY, + createDeployE2EHarness, + EXTRA_FACET, + SIGNER_ARGS, + type DeployE2EHarness, +} from "./deployE2EHarness"; + +describe.sequential("deploy pipeline E2E", () => { + let harness: DeployE2EHarness; + + beforeAll(async () => { + harness = await createDeployE2EHarness(); + }, 180_000); + + afterAll(async () => { + await harness?.cleanup(); + }); + + async function rpcBlockNumber(): Promise { + const response = await fetch(harness.rpcUrl, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }), + }); + const payload = await response.json() as { result?: string }; + if (!response.ok || !payload.result) throw new Error("Unable to read Anvil block number."); + return payload.result; + } + + it("generates the managed script and stops before broadcasting", async () => { + const result = await harness.runDeploy([]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Deploy plan"); + expect(output).toContain("Review this artifact before deploying."); + expect(output).toContain("When ready, run 'compose deploy --dry-run' to simulate"); + expect(output).toContain("'compose deploy --broadcast' to send transactions"); + + const script = await fs.readFile( + path.join(harness.projectRoot, "script", "ComposeDeploy.s.sol"), + "utf8", + ); + expect(script).toMatch(/^\/\* compose-plan-hash: 0x[0-9a-f]{64} \*\/$/m); + expect(script).toContain("CounterFacet counterFacet = new CounterFacet();"); + + await expect(fs.access(path.join(harness.projectRoot, "compose.lock"))).rejects.toThrow(); + }, 120_000); + + it("simulates the reviewed script on a fork without changing the target chain or lock", async () => { + await harness.runDeploy([]); + const blockBefore = await rpcBlockNumber(); + + const result = await harness.runDeploy([ + "--dry-run", + "--", + "--sender", + privateKeyToAccount(ANVIL_PRIVATE_KEY).address, + ]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Simulation succeeded"); + expect(output).toContain("No transactions were broadcast"); + expect(output).toMatch(/(Estimated total gas used for script|Total simulated gas)/); + expect(await rpcBlockNumber()).toBe(blockBefore); + await expect(fs.access(path.join(harness.projectRoot, "compose.lock"))).rejects.toThrow(); + }, 180_000); + + it("broadcasts, verifies on-chain, and records the deployment in compose.lock", async () => { + const result = await harness.runDeploy(["--broadcast", ...SIGNER_ARGS]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Deployed"); + expect(output).toContain("'CounterDiamond' on local (instance 'default')"); + expect(output).not.toContain("On-chain verification failed"); + + const deployment = await harness.readDeployment(); + expect(deployment.diamond).toMatch(/^0x[0-9a-fA-F]{40}$/); + expect(Object.keys(deployment.facets).sort()).toEqual([ + "CounterFacet", + "DiamondInspectFacet", + ]); + expect(deployment.facetHash).toMatch(/^0x[0-9a-f]{64}$/); + expect(deployment.txHash).toMatch(/^0x[0-9a-f]{64}$/); + expect(Date.parse(deployment.lastSync)).not.toBeNaN(); + + // Foundry runs are recorded from the run broadcast: the capture file is + // Hardhat-only, so no capture file or capture directory is created. + await expect(fs.access(path.join(harness.projectRoot, "compose"))).rejects.toThrow(); + await expect( + fs.access(path.join(harness.projectRoot, "cache", "compose")), + ).rejects.toThrow(); + }, 180_000); + + it("reports in-sync when compose.json is unchanged", async () => { + const result = await harness.runDeploy([]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("In sync"); + }, 120_000); + + it("stops with the composition diff when compose.json gains a facet", async () => { + await harness.writeComposeJson({ ...BASE_FACETS, ExtraFacet: EXTRA_FACET }); + + const result = await harness.runDeploy([]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(1); + expect(output).toContain("differs from compose.json"); + expect(output).toContain("ExtraFacet"); + }, 120_000); + + it("replaces the deployment with --redeploy", async () => { + const before = await harness.readDeployment(); + + const regenerate = await harness.runDeploy(["--redeploy"]); + const regenerateOutput = `${regenerate.stdout}\n${regenerate.stderr}`; + expect(regenerate.code, regenerateOutput).toBe(0); + + const result = await harness.runDeploy(["--redeploy", "--broadcast", ...SIGNER_ARGS]); + const output = `${result.stdout}\n${result.stderr}`; + expect(result.code, output).toBe(0); + expect(output).toContain("abandoned and replaced"); + + const after = await harness.readDeployment(); + expect(after.diamond).not.toBe(before.diamond); + expect(Object.keys(after.facets).sort()).toEqual([ + "CounterFacet", + "DiamondInspectFacet", + "ExtraFacet", + ]); + }, 240_000); + + it("validates the deployed project against the lock", async () => { + const result = await harness.runValidate(); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Validation passed."); + }, 180_000); + + it("uses the command RPC override for Foundry preflight, broadcast, and verification", async () => { + await harness.writeComposeJson(BASE_FACETS, "http://127.0.0.1:1"); + + const generate = await harness.runDeploy([ + "--redeploy", + "--rpc-url", + harness.rpcUrl, + ]); + const generateOutput = `${generate.stdout}\n${generate.stderr}`; + expect(generate.code, generateOutput).toBe(0); + expect(generateOutput).toContain("CLI override"); + + const result = await harness.runDeploy([ + "--redeploy", + "--rpc-url", + harness.rpcUrl, + "--broadcast", + ...SIGNER_ARGS, + ]); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Deployed"); + const deployment = await harness.readDeployment(); + expect(deployment.diamond).toMatch(/^0x[0-9a-fA-F]{40}$/); + }, 180_000); + + it("deploys with a Compose account alias backed by a Foundry keystore", async () => { + const home = await fs.mkdtemp(path.join(os.tmpdir(), "compose-account-home-")); + const password = "compose-e2e-keystore-password"; + const deployerAddress = privateKeyToAccount(ANVIL_PRIVATE_KEY).address; + const passwordFile = path.join(harness.projectRoot, ".compose-e2e-password"); + const childEnv = { HOME: home, ETH_PASSWORD: passwordFile }; + + try { + await fs.writeFile(passwordFile, `${password}\n`, { encoding: "utf8", mode: 0o600 }); + execFileSync("cast", [ + "wallet", + "import", + "compose-e2e-deployer", + "--private-key", + ANVIL_PRIVATE_KEY, + "--unsafe-password", + password, + ], { cwd: harness.projectRoot, env: { ...process.env, ...childEnv }, stdio: "pipe" }); + + await harness.writeComposeJson(BASE_FACETS, harness.rpcUrl); + + const setup = await harness.runAccount([ + "setup", + "deployer", + "--foundry-account", + "compose-e2e-deployer", + "--chain", + "local", + ], childEnv); + const setupOutput = `${setup.stdout}\n${setup.stderr}`; + expect(setup.code, setupOutput).toBe(0); + expect(setupOutput).toContain("Alias: deployer"); + expect(setupOutput).toContain(`Address: ${deployerAddress}`); + expect(setupOutput).toContain("compose account check deployer --chain local"); + expect(setupOutput).not.toContain("cast wallet import"); + expect(setupOutput).not.toContain(ANVIL_PRIVATE_KEY); + expect(setupOutput.split(deployerAddress).length - 1).toBe(1); + + const list = await harness.runAccount(["list"], childEnv); + const listOutput = `${list.stdout}\n${list.stderr}`; + expect(list.code, listOutput).toBe(0); + expect(listOutput).toContain(`deployer: ${deployerAddress}`); + expect(listOutput).toContain("Default for local: deployer"); + + const check = await harness.runAccount(["check", "deployer", "--chain", "local"], childEnv); + const checkOutput = `${check.stdout}\n${check.stderr}`; + expect(check.code, checkOutput).toBe(0); + expect(checkOutput).toContain(`Account 'deployer' is available on local: ${deployerAddress}`); + expect(checkOutput).not.toContain(ANVIL_PRIVATE_KEY); + expect(checkOutput.split(deployerAddress).length - 1).toBe(1); + + const generate = await harness.runDeploy(["--account", "deployer", "--redeploy"], childEnv); + const generateOutput = `${generate.stdout}\n${generate.stderr}`; + expect(generate.code, generateOutput).toBe(0); + + const result = await harness.runDeploy([ + "--account", + "deployer", + "--redeploy", + "--broadcast", + "--", + "--password-file", + passwordFile, + ], childEnv); + const output = `${result.stdout}\n${result.stderr}`; + + expect(result.code, output).toBe(0); + expect(output).toContain("Signer: deployer"); + expect(output).toContain("Deployer:"); + const deployment = await harness.readDeployment(); + expect(deployment.deployer?.toLowerCase()).toBe(deployerAddress.toLowerCase()); + } finally { + await fs.rm(passwordFile, { force: true }); + await fs.rm(home, { recursive: true, force: true }); + } + }, 180_000); + +}); diff --git a/cli/test/pipelines/initPipeline/harness.ts b/cli/test/pipelines/initPipeline/harness.ts index d0076cb2..3a61b82e 100644 --- a/cli/test/pipelines/initPipeline/harness.ts +++ b/cli/test/pipelines/initPipeline/harness.ts @@ -2,11 +2,11 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { vi } from "vitest"; +import { IFrameworkAdapter } from "../../../src/adapters/IFrameworkAdapter/interface"; import { ConfigOptions, - IFrameworkAdapter, SolidityAstSource, -} from "../../../src/adapters/IFrameworkAdapter/interface"; +} from "../../../src/adapters/IFrameworkAdapter/types"; import { Context } from "../../../src/context/context"; import { ComposeContext } from "../../../src/context/types"; import { @@ -57,9 +57,10 @@ function createFixtureAdapter(framework: InitFramework): IFrameworkAdapter { getTestRoot: (projectRoot) => path.join(projectRoot, "test"), getArtifactDir: (projectRoot) => path.join(projectRoot, artifactDirectory), compile: vi.fn(async () => undefined), - compileAst: vi.fn(async (_ctx, sourcePaths) => sourcePaths.map((sourcePath, index) => - contractAst(sourcePath, contractNameFromSourcePath(sourcePath), index * 10 + 1) - )), + compileAst: vi.fn(async (_ctx: ComposeContext, sourcePaths: string[]) => + sourcePaths.map((sourcePath: string, index: number) => + contractAst(sourcePath, contractNameFromSourcePath(sourcePath), index * 10 + 1) + )), resolveSoliditySourcePath: vi.fn(async (_ctx, sourcePath) => resolveCatalogSourceForRead(sourcePath)), initProject: vi.fn(async (ctx) => { @@ -94,6 +95,24 @@ function createFixtureAdapter(framework: InitFramework): IFrameworkAdapter { ), ]); }), + supportsAccountImport: false, + readAccountAddress: async () => ({ address: null, exists: false, requiresUnlock: false }), + resolveAccountAddress: async () => ({ address: null, exists: false, requiresUnlock: false }), + listSignerAddresses: async () => [], + resolveDeploySigner: async () => null, + importAccount: async () => null, + assertSupportedProject: () => {}, + getDeployToolbox: async () => null, + getManagedDeployScriptPath: (projectRoot) => + path.join(projectRoot, scriptDirectory, framework === "foundry" + ? "ComposeDeploy.s.sol" + : "compose-deploy.ts"), + getManagedDeployRunnerPath: () => null, + getManagedDeployResultPath: () => null, + createDeployCommand: () => ({ command: "true", args: [] }), + createTestCommand: () => ({ command: "true", args: [] }), + readDeployedBytecode: async () => undefined, + readBroadcastTransactions: async () => [], }; } @@ -102,6 +121,7 @@ export async function createInitPipelineHarness( framework: InitFramework, base: string, projectName: string, + overrides: Record = {}, ): Promise { const outputRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-init-pipeline-")); const projectRoot = path.join(outputRoot, projectName); @@ -117,6 +137,7 @@ export async function createInitPipelineHarness( projectName, outDir: outputRoot, installDeps: false, + ...overrides, }); return { diff --git a/cli/test/pipelines/initPipeline/initPipeline.test.ts b/cli/test/pipelines/initPipeline/initPipeline.test.ts index 65564642..7e4ef777 100644 --- a/cli/test/pipelines/initPipeline/initPipeline.test.ts +++ b/cli/test/pipelines/initPipeline/initPipeline.test.ts @@ -20,6 +20,7 @@ type ComposeJson = { package?: string; }>; }>; + chains: Record; }; async function expectFiles(projectRoot: string, files: string[]): Promise { @@ -35,6 +36,7 @@ async function readComposeJson(projectRoot: string): Promise { } function useHarnessDependencies(harness: InitPipelineHarness): void { + vi.spyOn(console, "log").mockImplementation(() => undefined); vi.spyOn(InitModule, "showComposeHeader").mockImplementation(() => undefined); vi.spyOn(InitModule, "showSuccess").mockImplementation(() => undefined); vi.spyOn(PreflightModule, "check").mockImplementation(async (ctx) => ctx); @@ -61,11 +63,11 @@ describe("InitPipeline", () => { framework: "foundry" as const, projectName: "bare-foundry", contract: "src/Diamond.sol:Diamond", + scriptRoot: "script", files: [ "compose.json", "foundry.toml", "src/Diamond.sol", - "script/Deploy.s.sol", "test/Diamond.t.sol", ], }, @@ -73,12 +75,12 @@ describe("InitPipeline", () => { framework: "hardhat" as const, projectName: "bare-hardhat", contract: "contracts/Diamond.sol:Diamond", + scriptRoot: "scripts", files: [ "compose.json", "package.json", "hardhat.config.ts", "contracts/Diamond.sol", - "scripts/deploy.ts", "test/Diamond.ts", ], }, @@ -86,9 +88,11 @@ describe("InitPipeline", () => { framework, projectName, contract, + scriptRoot, files, }) => { const harness = await createInitPipelineHarness(framework, "none", projectName); + if (framework === "hardhat") harness.ctx.param.installDeps = true; useHarnessDependencies(harness); try { @@ -101,9 +105,16 @@ describe("InitPipeline", () => { expect(result.state.initPipeline?.success).toBe(true); expect(composeJson.project).toBe(projectName); expect(composeJson.framework).toBe(framework); + expect(composeJson.chains).toEqual({ + local: { rpc: "http://127.0.0.1:8545", chainId: 31337 }, + sepolia: { rpc: "${SEPOLIA_RPC_URL}", chainId: 11155111 }, + }); expect(diamond.contract).toBe(contract); expect(Object.keys(diamond.facets)).toEqual(["DiamondInspectFacet"]); await expectFiles(harness.projectRoot, files); + await expect( + fs.access(path.join(harness.projectRoot, scriptRoot)), + ).resolves.toBeUndefined(); expect(harness.adapter.compileAst).toHaveBeenCalledOnce(); } finally { await harness.cleanup(); @@ -132,4 +143,33 @@ describe("InitPipeline", () => { await harness.cleanup(); } }); + + it("scaffolds an upgradeable ERC-20 diamond with --upgradeable", async () => { + const harness = await createInitPipelineHarness( + "foundry", + "erc-20", + "erc20-upgradeable", + { upgradeable: true }, + ); + useHarnessDependencies(harness); + + try { + const result = await InitPipeline.execute(harness.ctx); + const composeJson = await readComposeJson(harness.projectRoot); + const facetNames = Object.keys(composeJson.diamonds["erc20-upgradeable"].facets).sort(); + + expect(result.status.success).toBe(true); + expect(facetNames).toEqual([ + "DiamondInspectFacet", + "DiamondUpgradeFacet", + "ERC20ApproveFacet", + "ERC20DataFacet", + "ERC20TransferFacet", + "OwnerDataFacet", + "OwnerTransferFacet", + ]); + } finally { + await harness.cleanup(); + } + }); }); diff --git a/cli/test/pipelines/testPipeline.test.ts b/cli/test/pipelines/testPipeline.test.ts new file mode 100644 index 00000000..75af4363 --- /dev/null +++ b/cli/test/pipelines/testPipeline.test.ts @@ -0,0 +1,89 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const { runCommand } = vi.hoisted(() => ({ runCommand: vi.fn(async () => undefined) })); + +vi.mock("../../src/utils/exec", () => ({ runCommand })); + +import { Context } from "../../src/context/context"; +import { TestPipeline } from "../../src/pipelines/testPipeline"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-test-pipeline-")); + runCommand.mockClear(); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +describe("TestPipeline", () => { + it("runs forge test for a Foundry project", async () => { + await fs.writeFile(path.join(projectRoot, "foundry.toml"), "", "utf8"); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await TestPipeline.execute(ctx); + + expect(runCommand).toHaveBeenCalledWith("forge", ["test"], { cwd: projectRoot }); + }); + + it("runs hardhat test for a Hardhat project", async () => { + await fs.writeFile(path.join(projectRoot, "hardhat.config.ts"), "", "utf8"); + await fs.writeFile( + path.join(projectRoot, "package.json"), + JSON.stringify({ devDependencies: { hardhat: "^3.8.0" } }), + "utf8", + ); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await TestPipeline.execute(ctx); + + expect(runCommand).toHaveBeenCalledWith("npx", ["hardhat", "test"], { cwd: projectRoot }); + }); + + it("forwards passthrough arguments to the framework", async () => { + await fs.writeFile(path.join(projectRoot, "foundry.toml"), "", "utf8"); + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + ctx.param.passthrough = ["--match-test", "test_Increment", "-vvv"]; + + await TestPipeline.execute(ctx); + + expect(runCommand).toHaveBeenCalledWith( + "forge", + ["test", "--match-test", "test_Increment", "-vvv"], + { cwd: projectRoot }, + ); + }); + + it("resolves the project root from a nested directory", async () => { + const nestedDirectory = path.join(projectRoot, "src", "facets"); + await fs.mkdir(nestedDirectory, { recursive: true }); + await fs.writeFile(path.join(projectRoot, "foundry.toml"), "", "utf8"); + await fs.writeFile( + path.join(projectRoot, "compose.json"), + JSON.stringify({ framework: "foundry" }), + "utf8", + ); + const ctx = Context.create(); + ctx.param.projectRoot = nestedDirectory; + + await TestPipeline.execute(ctx); + + expect(runCommand).toHaveBeenCalledWith("forge", ["test"], { cwd: projectRoot }); + }); + + it("fails when no supported framework is detected", async () => { + const ctx = Context.create(); + ctx.param.projectRoot = projectRoot; + + await expect(TestPipeline.execute(ctx)).rejects.toThrow("No supported framework detected"); + expect(runCommand).not.toHaveBeenCalled(); + }); +}); diff --git a/cli/test/pipelines/validatePipeline/bytecodeHarness.ts b/cli/test/pipelines/validatePipeline/bytecodeHarness.ts index 0f2b7b5c..a55f0ca7 100644 --- a/cli/test/pipelines/validatePipeline/bytecodeHarness.ts +++ b/cli/test/pipelines/validatePipeline/bytecodeHarness.ts @@ -255,11 +255,13 @@ export async function createBytecodeE2EHarness(): Promise { deployments: { ERC20Diamond: { local: { - diamond: diamondAddress, - facets: deployedFacets, - facetHash: "0x00", - lastSync: new Date().toISOString(), - txHash: diamondTransaction.hash ?? "0x00", + default: { + diamond: diamondAddress, + facets: deployedFacets, + facetHash: "0x00", + lastSync: new Date().toISOString(), + txHash: diamondTransaction.hash ?? "0x00", + }, }, }, }, diff --git a/cli/test/pipelines/validatePipeline/validatePipelineVSL.test.ts b/cli/test/pipelines/validatePipeline/validatePipelineVSL.test.ts index af89f603..39461bf6 100644 --- a/cli/test/pipelines/validatePipeline/validatePipelineVSL.test.ts +++ b/cli/test/pipelines/validatePipeline/validatePipelineVSL.test.ts @@ -78,7 +78,7 @@ describe("validate pipeline", () => { "FullStorageFacet", "CompatibleStorageFacet", ]); - await harness.writeLock({ StorageDiamond: { local: deployment() } }); + await harness.writeLock({ StorageDiamond: { local: { default: deployment() } } }); const report = { ...emptyReport(), uncertainScopes: [ @@ -144,7 +144,7 @@ describe("validate pipeline", () => { "FullStorageFacet", "CompatibleStorageFacet", ]); - await harness.writeLock({ StorageDiamond: { local: deployment() } }); + await harness.writeLock({ StorageDiamond: { local: { default: deployment() } } }); const { rpc, validator } = bytecodeDependencies(emptyReport()); vi.mocked(rpc.getCode).mockResolvedValue("0x"); const originalResolve = DependencyResolver.resolve.bind(DependencyResolver); @@ -190,7 +190,7 @@ describe("validate pipeline", () => { "FullStorageFacet", "CompatibleStorageFacet", ]); - await harness.writeLock({ StorageDiamond: { local: deployment() } }); + await harness.writeLock({ StorageDiamond: { local: { default: deployment() } } }); const collision = { location: { slot: "0", offset: 0, selector: "12345678", pc: 42, symbolicPath: "slot(0)" }, virtualPath: "compose.fixture.virtual-storage", @@ -249,8 +249,8 @@ describe("validate pipeline", () => { ]); await harness.writeLock({ StorageDiamond: { - broken: deployment(), - healthy: deployment(), + broken: { default: deployment() }, + healthy: { default: deployment() }, }, }); const { rpc, validator } = bytecodeDependencies(emptyReport()); @@ -291,9 +291,57 @@ describe("validate pipeline", () => { } }, 30_000); + it("validates every instance of a diamond on the same chain", async () => { + const harness = await createValidatePipelineHarness([ + "FullStorageFacet", + "CompatibleStorageFacet", + ]); + await harness.writeLock({ + StorageDiamond: { + local: { + default: deployment(), + staging: { ...deployment(), diamond: "0x0000000000000000000000000000000000000009" }, + }, + }, + }); + const { rpc, validator } = bytecodeDependencies(emptyReport()); + const originalResolve = DependencyResolver.resolve.bind(DependencyResolver); + const resolver = vi.spyOn(DependencyResolver, "resolve").mockImplementation(async (requests) => { + if (requests.some((request) => request.key === DependencyKey.BytecodeValidator)) { + return { + [DependencyKey.RPC]: rpc, + [DependencyKey.Diamond]: createDiamondAdapter(rpc), + [DependencyKey.BytecodeValidator]: validator, + }; + } + return originalResolve(requests); + }); + const logs = vi.spyOn(console, "log").mockImplementation(() => undefined); + const errors = vi.spyOn(console, "error").mockImplementation(() => undefined); + + try { + const result = await ValidatePipeline.execute(harness.ctx); + expect(result.state.bytecodeValidation).toMatchObject({ + success: true, + result: { + deployments: [ + expect.objectContaining({ instance: "default" }), + expect.objectContaining({ instance: "staging" }), + ], + }, + }); + expect(validator.validate).toHaveBeenCalledTimes(2); + } finally { + resolver.mockRestore(); + logs.mockRestore(); + errors.mockRestore(); + await harness.cleanup(); + } + }, 30_000); + it("runs compiled facet bytecode through the packaged validator", async () => { const harness = await createValidatePipelineHarness(["FullStorageFacet"]); - await harness.writeLock({ StorageDiamond: { local: deployment() } }); + await harness.writeLock({ StorageDiamond: { local: { default: deployment() } } }); const rpc: IRPCAdapter = { getBlockNumber: vi.fn().mockResolvedValue(100n), readContract: vi.fn().mockResolvedValue([{ diff --git a/cli/test/utils/args.test.ts b/cli/test/utils/args.test.ts new file mode 100644 index 00000000..5d39cf05 --- /dev/null +++ b/cli/test/utils/args.test.ts @@ -0,0 +1,168 @@ +import { describe, expect, it } from "vitest"; +import { assertSafeDeploymentPassthrough, toPassthroughArgs } from "../../src/utils/args"; + +describe("toPassthroughArgs", () => { + it("keeps only string arguments in order", () => { + expect(toPassthroughArgs(["--match-test", "test_Increment", 7, null])).toEqual([ + "--match-test", + "test_Increment", + ]); + }); + + it("returns an empty list for missing or non-array values", () => { + expect(toPassthroughArgs(undefined)).toEqual([]); + expect(toPassthroughArgs("--match-test")).toEqual([]); + }); +}); + +describe("assertSafeDeploymentPassthrough", () => { + it.each([ + ["foundry", ["--rpc-url", "https://other.example"]], + ["foundry", ["--rpc-url=https://other.example"]], + ["foundry", ["-r", "https://other.example"]], + ["foundry", ["--fork-url", "https://other.example"]], + ["foundry", ["--fork-block-number", "1"]], + ["foundry", ["--chain", "1"]], + ["foundry", ["--chain-id", "1"]], + ["hardhat", ["--network", "other"]], + ["hardhat", ["--network=other"]], + ["hardhat", ["--rpc-url", "https://other.example"]], + ] as const)("rejects conflicting %s passthrough flags", (framework, args) => { + expect(() => assertSafeDeploymentPassthrough(args, framework)).toThrow( + "cannot change the planned deployment target", + ); + }); + + it("allows signing and other non-network passthrough options", () => { + expect(() => assertSafeDeploymentPassthrough( + ["--private-key", "0xabc", "--non-interactive"], + "foundry", + )).not.toThrow(); + expect(() => assertSafeDeploymentPassthrough(["--account", "deployer"], "hardhat")).not.toThrow(); + }); + + it("prevents passthrough from replacing a selected Compose signer", () => { + expect(() => assertSafeDeploymentPassthrough( + ["--account", "another-deployer"], + "foundry", + true, + )).toThrow("conflicts with the selected Compose account"); + expect(() => assertSafeDeploymentPassthrough( + ["--private-key", "0xsecret"], + "foundry", + true, + )).toThrow("conflicts with the selected Compose account"); + expect(() => assertSafeDeploymentPassthrough( + ["--accounts", "another-deployer"], + "foundry", + true, + )).toThrow("conflicts with the selected Compose account"); + expect(() => assertSafeDeploymentPassthrough( + ["-i"], + "foundry", + true, + )).toThrow("conflicts with the selected Compose account"); + }); + + it("rejects build and source-selection overrides", () => { + expect(() => assertSafeDeploymentPassthrough( + ["--root", "/tmp/other-project"], + "foundry", + )).toThrow("cannot change the reviewed deployment artifact"); + expect(() => assertSafeDeploymentPassthrough( + ["--remappings", "@perfect-abstractions/compose/=other/"], + "foundry", + )).toThrow("cannot change the reviewed deployment artifact"); + expect(() => assertSafeDeploymentPassthrough( + ["--config", "other.config.ts"], + "hardhat", + )).toThrow("cannot change the reviewed deployment artifact"); + }); + + it("rejects resuming a previous Foundry broadcast", () => { + expect(() => assertSafeDeploymentPassthrough( + ["--resume"], + "foundry", + false, + "broadcast", + )).toThrow("cannot resume a past deployment"); + expect(() => assertSafeDeploymentPassthrough( + ["--resume-attempt", "1"], + "foundry", + false, + "broadcast", + )).toThrow("cannot resume a past deployment"); + }); + + it("redacts inline secret values in passthrough errors", () => { + const expectRedacted = (run: () => void, expected: string): void => { + let message = ""; + try { + run(); + } catch (error) { + message = (error as Error).message; + } + expect(message).toContain(expected); + expect(message).not.toContain("0xsecret"); + expect(message).not.toContain("rpc.example.test/v1/secret"); + }; + + expectRedacted( + () => assertSafeDeploymentPassthrough( + ["--private-key=0xsecret"], + "foundry", + false, + "simulate", + ), + "--private-key=[REDACTED]", + ); + expectRedacted( + () => assertSafeDeploymentPassthrough( + ["--private-key=0xsecret"], + "foundry", + true, + ), + "--private-key=[REDACTED]", + ); + expectRedacted( + () => assertSafeDeploymentPassthrough( + ["--rpc-url=https://rpc.example.test/v1/secret"], + "foundry", + ), + "--rpc-url=[REDACTED]", + ); + }); + + it("keeps a framework passthrough from changing simulation into a broadcast", () => { + expect(() => assertSafeDeploymentPassthrough( + ["--broadcast"], + "foundry", + false, + "simulate", + )).toThrow("cannot change Compose deploy mode"); + expect(() => assertSafeDeploymentPassthrough( + ["--skip-simulation"], + "foundry", + false, + "simulate", + )).toThrow("disables the requested dry-run"); + expect(() => assertSafeDeploymentPassthrough( + ["--private-key", "0xsecret"], + "foundry", + false, + "simulate", + )).toThrow("not used for a dry-run"); + expect(() => assertSafeDeploymentPassthrough( + ["-i"], + "foundry", + false, + "simulate", + )).toThrow("not used for a dry-run"); + expect(() => assertSafeDeploymentPassthrough( + ["--sender", "0x00000000000000000000000000000000000000a1"], + "foundry", + false, + "simulate", + )).not.toThrow(); + }); +}); diff --git a/cli/test/utils/chainConfig.test.ts b/cli/test/utils/chainConfig.test.ts index cf2dbefd..e5d5a2da 100644 --- a/cli/test/utils/chainConfig.test.ts +++ b/cli/test/utils/chainConfig.test.ts @@ -47,6 +47,36 @@ describe("resolveChainConfig", () => { await expect(resolveChainConfig({ chainKey: "embedded", projectRoot: root })).resolves.toMatchObject({ rpcUrl: "https://example.test/v1/secret" }); }); + it("uses a command RPC override but retains the chain identity from compose.json", async () => { + process.env.TEST_RPC_URL = "https://override.example/rpc"; + const root = await projectWithCompose({ + chains: { sepolia: { rpc: "https://configured.example/rpc", chainId: 11155111 } }, + }); + + await expect(resolveChainConfig({ + chainKey: "sepolia", + projectRoot: root, + rpcUrlOverride: "${TEST_RPC_URL}", + })).resolves.toEqual({ + chainKey: "sepolia", + rpcUrl: "https://override.example/rpc", + chainId: 11155111, + }); + }); + + it("rejects an empty or non-string RPC override", async () => { + const root = await projectWithCompose({ + chains: { local: { rpc: "http://127.0.0.1:8545", chainId: 31337 } }, + }); + + await expect(resolveChainConfig({ projectRoot: root, rpcUrlOverride: " " })).rejects.toMatchObject({ + code: "RPC_INVALID_CONFIGURATION", + }); + await expect(resolveChainConfig({ projectRoot: root, rpcUrlOverride: 7 })).rejects.toMatchObject({ + code: "RPC_INVALID_CONFIGURATION", + }); + }); + it("fails when an interpolated variable is missing", async () => { const root = await projectWithCompose({ chains: { sepolia: { rpc: "${TEST_RPC_URL}", chainId: 11155111 } } }); diff --git a/cli/test/utils/composeProjectFile.test.ts b/cli/test/utils/composeProjectFile.test.ts index 947bf8f2..aa360772 100644 --- a/cli/test/utils/composeProjectFile.test.ts +++ b/cli/test/utils/composeProjectFile.test.ts @@ -2,7 +2,11 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { describe, expect, it } from "vitest"; -import { locateComposeProjectFile, readComposeProjectFile } from "../../src/utils/composeProjectFile"; +import { + loadComposeProjectFile, + locateComposeProjectFile, + readComposeProjectFile, +} from "../../src/utils/composeProjectFile"; describe("compose project file utilities", () => { it("locates the nearest compose.json and returns its project root", async () => { @@ -50,4 +54,48 @@ describe("compose project file utilities", () => { await fs.rm(root, { recursive: true, force: true }); } }); + + it("loads the nearest compose.json with its project root", async () => { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "compose-project-load-")); + const nestedRoot = path.join(root, "nested"); + const startDirectory = path.join(nestedRoot, "src"); + + try { + await fs.mkdir(startDirectory, { recursive: true }); + await fs.writeFile( + path.join(nestedRoot, "compose.json"), + '{"framework":"foundry"}', + "utf8", + ); + + await expect(loadComposeProjectFile(startDirectory)).resolves.toEqual({ + path: path.join(nestedRoot, "compose.json"), + root: nestedRoot, + composeJson: { framework: "foundry" }, + }); + } finally { + await fs.rm(root, { recursive: true, force: true }); + } + }); + + it("returns null when no compose.json exists", async () => { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "compose-project-load-empty-")); + + try { + await expect(loadComposeProjectFile(root)).resolves.toBeNull(); + } finally { + await fs.rm(root, { recursive: true, force: true }); + } + }); + + it("propagates load parse errors unchanged", async () => { + const root = await fs.mkdtemp(path.join(os.tmpdir(), "compose-project-load-json-")); + + try { + await fs.writeFile(path.join(root, "compose.json"), "{invalid", "utf8"); + await expect(loadComposeProjectFile(root)).rejects.toBeInstanceOf(SyntaxError); + } finally { + await fs.rm(root, { recursive: true, force: true }); + } + }); }); diff --git a/cli/test/utils/composeRuntime.test.ts b/cli/test/utils/composeRuntime.test.ts new file mode 100644 index 00000000..66b8714f --- /dev/null +++ b/cli/test/utils/composeRuntime.test.ts @@ -0,0 +1,76 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { + composeRuntimeDir, + ensureComposeDirIgnored, + ensureComposeRuntimeDir, +} from "../../src/utils/composeRuntime"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-runtime-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +describe("composeRuntimeDir", () => { + it("scopes the runtime directory by framework", () => { + expect(composeRuntimeDir(projectRoot, "hardhat")) + .toBe(path.join(projectRoot, ".compose", "hardhat")); + expect(composeRuntimeDir(projectRoot, "foundry")) + .toBe(path.join(projectRoot, ".compose", "foundry")); + }); +}); + +describe("ensureComposeDirIgnored", () => { + it("creates a .gitignore when the project has none", async () => { + await ensureComposeDirIgnored(projectRoot); + + await expect(fs.readFile(path.join(projectRoot, ".gitignore"), "utf8")) + .resolves.toBe(".compose/\n"); + }); + + it("appends the rule without dropping existing entries", async () => { + await fs.writeFile(path.join(projectRoot, ".gitignore"), "node_modules/\n", "utf8"); + + await ensureComposeDirIgnored(projectRoot); + + await expect(fs.readFile(path.join(projectRoot, ".gitignore"), "utf8")) + .resolves.toBe("node_modules/\n.compose/\n"); + }); + + it("leaves an already ignored project untouched", async () => { + const gitignorePath = path.join(projectRoot, ".gitignore"); + await fs.writeFile(gitignorePath, "node_modules/\n.compose/\n", "utf8"); + const before = await fs.stat(gitignorePath); + + await ensureComposeDirIgnored(projectRoot); + + const after = await fs.stat(gitignorePath); + expect(after.mtimeMs).toBe(before.mtimeMs); + await expect(fs.readFile(gitignorePath, "utf8")) + .resolves.toBe("node_modules/\n.compose/\n"); + }); + + it("surfaces read errors other than a missing file", async () => { + await fs.mkdir(path.join(projectRoot, ".gitignore")); + + await expect(ensureComposeDirIgnored(projectRoot)).rejects.toThrow(); + }); +}); + +describe("ensureComposeRuntimeDir", () => { + it("creates the ignored runtime directory", async () => { + const runtimeDir = await ensureComposeRuntimeDir(projectRoot, "hardhat"); + + expect(runtimeDir).toBe(path.join(projectRoot, ".compose", "hardhat")); + await expect(fs.stat(runtimeDir)).resolves.toMatchObject({ mode: expect.any(Number) }); + await expect(fs.readFile(path.join(projectRoot, ".gitignore"), "utf8")) + .resolves.toBe(".compose/\n"); + }); +}); diff --git a/cli/test/utils/env.test.ts b/cli/test/utils/env.test.ts new file mode 100644 index 00000000..e70f11ec --- /dev/null +++ b/cli/test/utils/env.test.ts @@ -0,0 +1,85 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { loadProjectEnv } from "../../src/utils/env"; + +const ENV_KEYS = [ + "COMPOSE_ENV_TEST_PARENT_ONLY", + "COMPOSE_ENV_TEST_PROJECT_ONLY", + "COMPOSE_ENV_TEST_NESTED_ONLY", + "COMPOSE_ENV_TEST_PRECEDENCE", + "COMPOSE_ENV_TEST_SHELL_VALUE", +]; +const originalEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]])); + +beforeEach(() => { + for (const key of ENV_KEYS) delete process.env[key]; +}); + +afterEach(() => { + for (const key of ENV_KEYS) { + const value = originalEnv.get(key); + if (value === undefined) delete process.env[key]; + else process.env[key] = value; + } +}); + +describe("loadProjectEnv", () => { + it("loads only the nearest Compose project's .env and preserves shell values", async () => { + const outerRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-env-")); + const projectRoot = path.join(outerRoot, "project"); + const nestedDirectory = path.join(projectRoot, "src", "contracts"); + + try { + await fs.mkdir(nestedDirectory, { recursive: true }); + await fs.writeFile(path.join(projectRoot, "compose.json"), "{}", "utf8"); + await fs.writeFile( + path.join(outerRoot, ".env"), + "COMPOSE_ENV_TEST_PARENT_ONLY=parent\nCOMPOSE_ENV_TEST_PRECEDENCE=parent\n", + "utf8", + ); + await fs.writeFile( + path.join(projectRoot, ".env"), + "COMPOSE_ENV_TEST_PROJECT_ONLY=project\nCOMPOSE_ENV_TEST_PRECEDENCE=project\nCOMPOSE_ENV_TEST_SHELL_VALUE=from-file\n", + "utf8", + ); + await fs.writeFile( + path.join(nestedDirectory, ".env"), + "COMPOSE_ENV_TEST_NESTED_ONLY=nested\nCOMPOSE_ENV_TEST_PRECEDENCE=nested\n", + "utf8", + ); + process.env.COMPOSE_ENV_TEST_SHELL_VALUE = "from-shell"; + + await loadProjectEnv(nestedDirectory); + + expect(process.env.COMPOSE_ENV_TEST_PARENT_ONLY).toBeUndefined(); + expect(process.env.COMPOSE_ENV_TEST_PROJECT_ONLY).toBe("project"); + expect(process.env.COMPOSE_ENV_TEST_NESTED_ONLY).toBeUndefined(); + expect(process.env.COMPOSE_ENV_TEST_PRECEDENCE).toBe("project"); + expect(process.env.COMPOSE_ENV_TEST_SHELL_VALUE).toBe("from-shell"); + } finally { + await fs.rm(outerRoot, { recursive: true, force: true }); + } + }); + + it("uses only the starting directory when no Compose project exists", async () => { + const outerRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-env-no-project-")); + const startDirectory = path.join(outerRoot, "working"); + + try { + await fs.mkdir(startDirectory, { recursive: true }); + await fs.writeFile( + path.join(outerRoot, ".env"), + "COMPOSE_ENV_TEST_PARENT_ONLY=parent\n", + "utf8", + ); + + await loadProjectEnv(startDirectory); + + expect(process.env.COMPOSE_ENV_TEST_PARENT_ONLY).toBeUndefined(); + } finally { + await fs.rm(outerRoot, { recursive: true, force: true }); + } + }); +}); diff --git a/cli/test/utils/errors.test.ts b/cli/test/utils/errors.test.ts new file mode 100644 index 00000000..738fb834 --- /dev/null +++ b/cli/test/utils/errors.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it } from "vitest"; +import { toComposeError } from "../../src/utils/errors"; + +describe("toComposeError", () => { + it("keeps an error code exposed by the original error", () => { + const error = Object.assign(new Error("Account lookup failed."), { code: "ACCOUNT_NOT_FOUND" }); + + expect(toComposeError(error, "ACCOUNT_FAILED", "Account command failed.")).toEqual({ + code: "ACCOUNT_NOT_FOUND", + message: "Account lookup failed.", + nativeError: error, + }); + }); + + it("uses the fallback code for errors without one", () => { + const error = new Error("Deploy failed hard."); + + expect(toComposeError(error, "DEPLOY_FAILED", "Deploy failed.")).toEqual({ + code: "DEPLOY_FAILED", + message: "Deploy failed hard.", + nativeError: error, + }); + }); + + it("stringifies numeric error codes", () => { + const error = Object.assign(new Error("RPC failed."), { code: -32000 }); + + expect(toComposeError(error, "DEPLOY_FAILED", "Deploy failed.").code).toBe("-32000"); + }); + + it("uses the fallback code and message for non-Error values", () => { + expect(toComposeError("boom", "BYTECODE_VALIDATION_FAILED", "Bytecode validation failed.")).toEqual({ + code: "BYTECODE_VALIDATION_FAILED", + message: "Bytecode validation failed.", + nativeError: "boom", + }); + expect(toComposeError(null, "DEPLOY_FAILED", "Deploy failed.")).toEqual({ + code: "DEPLOY_FAILED", + message: "Deploy failed.", + nativeError: null, + }); + }); + + it("defaults the fallback message", () => { + expect(toComposeError(undefined, "UNKNOWN_FAILED").message).toBe("Operation failed."); + }); +}); diff --git a/cli/test/utils/exec.test.ts b/cli/test/utils/exec.test.ts new file mode 100644 index 00000000..fd2e3d39 --- /dev/null +++ b/cli/test/utils/exec.test.ts @@ -0,0 +1,140 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { runCommand, runCommandCapture, runCommandCaptureStdout } from "../../src/utils/exec"; + +let projectRoot: string; + +beforeEach(async () => { + projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-run-command-")); +}); + +afterEach(async () => { + await fs.rm(projectRoot, { recursive: true, force: true }); +}); + +const privateKey = "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; +const mnemonic = "test test test test test test test test test test test junk"; +const password = "compose-test-password"; +const rpcUrl = "https://user:password@rpc.example.test/v1/api-key?token=query-secret"; +const sensitiveArgs = [ + "--private-key", + privateKey, + `--mnemonic=${mnemonic}`, + "--password", + password, + "--rpc-url", + rpcUrl, +]; + +function expectRedactedCommandError(error: unknown): void { + expect(error).toBeInstanceOf(Error); + const message = (error as Error).message; + for (const secret of [privateKey, mnemonic, password, rpcUrl]) { + expect(message).not.toContain(secret); + } + expect(message).toContain("--private-key [REDACTED]"); + expect(message).toContain("--mnemonic=[REDACTED]"); + expect(message).toContain("--password [REDACTED]"); + expect(message).toContain("--rpc-url [REDACTED]"); +} + +async function writeFailingScript(): Promise { + const scriptPath = path.join(projectRoot, "fail.mjs"); + await fs.writeFile(scriptPath, "process.exit(9);\n", "utf8"); + return scriptPath; +} + +describe("runCommand environment overrides", () => { + it("merges command-specific environment values with the parent environment", async () => { + const resultPath = path.join(projectRoot, "environment.json"); + const rpcUrl = "https://rpc.example.test/v1/private-token"; + const script = [ + 'const fs = require("node:fs");', + `fs.writeFileSync(${JSON.stringify(resultPath)}, JSON.stringify({`, + " rpcUrl: process.env.COMPOSE_DEPLOY_RPC_URL,", + " path: process.env.PATH,", + "}));", + ].join("\n"); + + await runCommand(process.execPath, ["-e", script], { + cwd: projectRoot, + env: { COMPOSE_DEPLOY_RPC_URL: rpcUrl }, + }); + + const result = JSON.parse(await fs.readFile(resultPath, "utf8")) as { + rpcUrl: string; + path: string; + }; + expect(result.rpcUrl).toBe(rpcUrl); + expect(result.path).toBe(process.env.PATH); + }); + + it("captures stdout without forwarding it when requested", async () => { + const childOutput = "Foundry public address output"; + const stdoutWrite = vi.spyOn(process.stdout, "write"); + + try { + const output = await runCommandCaptureStdout( + process.execPath, + ["-e", `process.stdout.write(${JSON.stringify(childOutput)});`], + { cwd: projectRoot, forwardStdout: false }, + ); + + expect(output).toBe(childOutput); + expect(stdoutWrite.mock.calls.some(([chunk]) => String(chunk).includes(childOutput))).toBe(false); + } finally { + stdoutWrite.mockRestore(); + } + }); +}); + +describe("command failure errors", () => { + it("redacts sensitive argv in runCommand errors", async () => { + const scriptPath = await writeFailingScript(); + const error = await runCommand( + process.execPath, + [scriptPath, ...sensitiveArgs], + { cwd: projectRoot }, + ).catch((caught: unknown) => caught); + + expectRedactedCommandError(error); + }); + + it("redacts sensitive argv in runCommandCaptureStdout errors", async () => { + const scriptPath = await writeFailingScript(); + const error = await runCommandCaptureStdout( + process.execPath, + [scriptPath, ...sensitiveArgs], + { cwd: projectRoot, forwardStdout: false }, + ).catch((caught: unknown) => caught); + + expectRedactedCommandError(error); + }); + + it("redacts sensitive argv in runCommandCapture errors", async () => { + const scriptPath = await writeFailingScript(); + const error = await runCommandCapture( + process.execPath, + [scriptPath, ...sensitiveArgs], + { cwd: projectRoot }, + ).catch((caught: unknown) => caught); + + expectRedactedCommandError(error); + }); + + it("does not expose sensitive argv in spawn errors", async () => { + const error = await runCommand( + "compose-command-that-does-not-exist", + ["--private-key", privateKey, "--mnemonic", mnemonic], + { cwd: projectRoot }, + ).catch((caught: unknown) => caught); + + expect(error).toBeInstanceOf(Error); + expect((error as Error).message).not.toContain(privateKey); + expect((error as Error).message).not.toContain(mnemonic); + expect(JSON.stringify(error)).not.toContain(privateKey); + expect(JSON.stringify(error)).not.toContain(mnemonic); + }); +}); diff --git a/cli/test/utils/files.test.ts b/cli/test/utils/files.test.ts index 57892e8b..c195330a 100644 --- a/cli/test/utils/files.test.ts +++ b/cli/test/utils/files.test.ts @@ -1,6 +1,6 @@ import path from "node:path"; import { describe, expect, it } from "vitest"; -import { planImportClosureTargets } from "../../src/utils/files"; +import { planImportClosureTargets, toProjectRelativePath } from "../../src/utils/files"; const root = path.resolve("/tmp", "plan-import-closure"); const templates = path.join(root, "templates", "import-review"); @@ -56,3 +56,20 @@ describe("planImportClosureTargets", () => { ); }); }); + +describe("toProjectRelativePath", () => { + it("renders paths inside the project relative to its root", () => { + const projectRoot = path.resolve("/tmp", "project"); + const scriptPath = path.join(projectRoot, "scripts", "compose-deploy.ts"); + + expect(toProjectRelativePath(projectRoot, scriptPath)).toBe("scripts/compose-deploy.ts"); + }); + + it("keeps paths outside the project unchanged", () => { + const projectRoot = path.resolve("/tmp", "project"); + const outside = path.resolve("/tmp", "other", "file.ts"); + + expect(toProjectRelativePath(projectRoot, outside)).toBe(outside); + expect(toProjectRelativePath(projectRoot, projectRoot)).toBe(projectRoot); + }); +}); diff --git a/cli/test/utils/gitignore.test.ts b/cli/test/utils/gitignore.test.ts new file mode 100644 index 00000000..dc883ef0 --- /dev/null +++ b/cli/test/utils/gitignore.test.ts @@ -0,0 +1,38 @@ +import { describe, expect, it } from "vitest"; +import { ensureGitignoreEntries, ensureGitignoreEntry } from "../../src/utils/gitignore"; + +describe("ensureGitignoreEntry", () => { + it("adds the entry to empty content", () => { + expect(ensureGitignoreEntry("", ".compose/")).toBe(".compose/\n"); + }); + + it("preserves content that lacks a trailing newline", () => { + expect(ensureGitignoreEntry("node_modules/", ".compose/")).toBe("node_modules/\n.compose/\n"); + }); + + it("does not duplicate an existing entry", () => { + expect(ensureGitignoreEntry("node_modules/\n.compose/\n", ".compose/")) + .toBe("node_modules/\n.compose/\n"); + }); + + it("matches entries surrounded by whitespace", () => { + expect(ensureGitignoreEntry(" .compose/ \n", ".compose/")).toBe(" .compose/ \n"); + }); + + it("preserves CRLF content", () => { + expect(ensureGitignoreEntry("out/\r\ncache/\r\n", ".compose/")) + .toBe("out/\r\ncache/\r\n.compose/\n"); + }); +}); + +describe("ensureGitignoreEntries", () => { + it("appends missing entries in order", () => { + expect(ensureGitignoreEntries("out/\n", ["node_modules/", ".compose/"])) + .toBe("out/\nnode_modules/\n.compose/\n"); + }); + + it("only appends entries that are missing", () => { + expect(ensureGitignoreEntries("out/\n.compose/\n", ["node_modules/", ".compose/"])) + .toBe("out/\n.compose/\nnode_modules/\n"); + }); +}); diff --git a/cli/test/utils/nodeVersion.test.ts b/cli/test/utils/nodeVersion.test.ts new file mode 100644 index 00000000..8e6c52da --- /dev/null +++ b/cli/test/utils/nodeVersion.test.ts @@ -0,0 +1,38 @@ +import { describe, expect, it } from "vitest"; +import { + assertHardhatNodeVersion, + HARDHAT_MINIMUM_NODE_VERSION, + isNodeVersionAtLeast, +} from "../../src/utils/nodeVersion"; + +describe("isNodeVersionAtLeast", () => { + it.each(["22.13.0", "v22.13.0", "22.13.1", "22.14.0", "23.0.0", "24.0.0"])( + "accepts %s as meeting the Hardhat minimum", + (version) => { + expect(isNodeVersionAtLeast(version, HARDHAT_MINIMUM_NODE_VERSION)).toBe(true); + }, + ); + + it.each(["20.19.0", "22.0.0", "22.12.9", "21.99.99"])( + "rejects %s as older than the Hardhat minimum", + (version) => { + expect(isNodeVersionAtLeast(version, HARDHAT_MINIMUM_NODE_VERSION)).toBe(false); + }, + ); + + it("rejects an unparseable version", () => { + expect(isNodeVersionAtLeast("not-a-version", HARDHAT_MINIMUM_NODE_VERSION)).toBe(false); + }); +}); + +describe("assertHardhatNodeVersion", () => { + it("allows the exact minimum Hardhat version", () => { + expect(() => assertHardhatNodeVersion("22.13.0")).not.toThrow(); + }); + + it("reports the current version and the supported minimum", () => { + expect(() => assertHardhatNodeVersion("22.12.0")).toThrow( + "Hardhat 3 requires Node.js 22.13.0 or newer; current version is 22.12.0", + ); + }); +}); diff --git a/cli/test/utils/packageFacetSources.test.ts b/cli/test/utils/packageFacetSources.test.ts index 5253263a..8a13cf6f 100644 --- a/cli/test/utils/packageFacetSources.test.ts +++ b/cli/test/utils/packageFacetSources.test.ts @@ -4,20 +4,67 @@ import path from "node:path"; import { describe, expect, it } from "vitest"; import { findPackageFacetSourceMatches } from "../../src/utils/packageFacetSources"; +const PACKAGE_NAME = "@perfect-abstractions/compose"; + +/** Creates a package facet in both the npm and Foundry package roots. */ +async function createBothPackageRoots(projectRoot: string): Promise<{ + nodeSource: string; + foundrySource: string; +}> { + const nodeSource = path.join(projectRoot, "node_modules", PACKAGE_NAME, "diamond", "PackageFacet.sol"); + const foundrySource = path.join(projectRoot, "lib", "Compose", "src", "diamond", "PackageFacet.sol"); + + await fs.mkdir(path.dirname(nodeSource), { recursive: true }); + await fs.mkdir(path.dirname(foundrySource), { recursive: true }); + await fs.writeFile(nodeSource, "contract PackageFacet {}", "utf8"); + await fs.writeFile(foundrySource, "contract PackageFacet {}", "utf8"); + + return { nodeSource, foundrySource }; +} + describe("package facet source search", () => { - it("returns all matches in Node-package then Foundry search order", async () => { - const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-package-sources-")); + it("prefers the Foundry package root when both roots contain a match", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-package-sources-foundry-")); try { - const nodeSource = path.join(projectRoot, "node_modules", "example-package", "src", "PackageFacet.sol"); - const foundrySource = path.join(projectRoot, "lib", "Compose", "src", "PackageFacet.sol"); - await fs.mkdir(path.dirname(nodeSource), { recursive: true }); - await fs.mkdir(path.dirname(foundrySource), { recursive: true }); - await fs.writeFile(nodeSource, "contract PackageFacet {}", "utf8"); - await fs.writeFile(foundrySource, "contract PackageFacet {}", "utf8"); + const { foundrySource } = await createBothPackageRoots(projectRoot); - await expect(findPackageFacetSourceMatches(projectRoot, "example-package", "PackageFacet")) - .resolves.toEqual([nodeSource, foundrySource]); + await expect(findPackageFacetSourceMatches( + projectRoot, + PACKAGE_NAME, + "PackageFacet", + { framework: "foundry" }, + )).resolves.toEqual([foundrySource]); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); + + it("prefers the node_modules package root for Hardhat", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-package-sources-hardhat-")); + + try { + const { nodeSource } = await createBothPackageRoots(projectRoot); + + await expect(findPackageFacetSourceMatches( + projectRoot, + PACKAGE_NAME, + "PackageFacet", + { framework: "hardhat" }, + )).resolves.toEqual([nodeSource]); + } finally { + await fs.rm(projectRoot, { recursive: true, force: true }); + } + }); + + it("uses the node_modules root first when the framework is unknown", async () => { + const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compose-package-sources-unknown-")); + + try { + const { nodeSource } = await createBothPackageRoots(projectRoot); + + await expect(findPackageFacetSourceMatches(projectRoot, PACKAGE_NAME, "PackageFacet")) + .resolves.toEqual([nodeSource]); } finally { await fs.rm(projectRoot, { recursive: true, force: true }); } diff --git a/cli/test/utils/redaction.test.ts b/cli/test/utils/redaction.test.ts new file mode 100644 index 00000000..28d59795 --- /dev/null +++ b/cli/test/utils/redaction.test.ts @@ -0,0 +1,122 @@ +import { describe, expect, it } from "vitest"; +import { + formatCommandArgs, + redactCommandArgs, + redactSensitiveArgument, +} from "../../src/utils/redaction"; + +describe("redactCommandArgs", () => { + it("redacts separate values for sensitive flags", () => { + expect(redactCommandArgs([ + "--private-key", + "0xprivate", + "--mnemonic", + "test test test test test test test test test test test junk", + "--password", + "hunter2", + "--non-interactive", + ])).toEqual([ + "--private-key", + "[REDACTED]", + "--mnemonic", + "[REDACTED]", + "--password", + "[REDACTED]", + "--non-interactive", + ]); + }); + + it("redacts inline values for sensitive flags", () => { + expect(redactCommandArgs([ + "--private-key=0xprivate", + "--mnemonic=test test", + "--password=hunter2", + "--unsafe-password=hunter2", + ])).toEqual([ + "--private-key=[REDACTED]", + "--mnemonic=[REDACTED]", + "--password=[REDACTED]", + "--unsafe-password=[REDACTED]", + ]); + }); + + it("redacts every value for multi-value sensitive flags", () => { + expect(redactCommandArgs([ + "--private-keys", + "0xprivate1", + "0xprivate2", + "--mnemonics", + "phrase one", + "phrase two", + "--non-interactive", + ])).toEqual([ + "--private-keys", + "[REDACTED]", + "[REDACTED]", + "--mnemonics", + "[REDACTED]", + "[REDACTED]", + "--non-interactive", + ]); + }); + + it("redacts RPC endpoints and camelCase secret flags", () => { + expect(redactCommandArgs([ + "--rpc-url", + "https://user:password@rpc.example/v1/api-key", + "--fork-url=https://rpc.example/v1/api-key", + "--privateKey=0xprivate", + "--apikey=api-secret", + "--secret-key=0xsecret", + "--keystore=/home/user/.foundry/keystores/deployer", + ])).toEqual([ + "--rpc-url", + "[REDACTED]", + "--fork-url=[REDACTED]", + "--privateKey=[REDACTED]", + "--apikey=[REDACTED]", + "--secret-key=[REDACTED]", + "--keystore=[REDACTED]", + ]); + }); + + it("keeps non-sensitive public arguments intact", () => { + const args = [ + "script/ComposeDeploy.s.sol:ComposeDeploy", + "--account", + "deployer", + "--sender", + "0x00000000000000000000000000000000000000a1", + "--match-test", + "test_Increment", + ]; + expect(redactCommandArgs(args)).toEqual(args); + }); + + it("does not treat the next flag as a sensitive value", () => { + expect(redactCommandArgs(["--private-key", "--non-interactive"])).toEqual([ + "--private-key", + "--non-interactive", + ]); + }); +}); + +describe("formatCommandArgs", () => { + it("formats a redacted command line", () => { + expect(formatCommandArgs(["--private-key", "0xprivate", "--broadcast"])).toBe( + "--private-key [REDACTED] --broadcast", + ); + }); +}); + +describe("redactSensitiveArgument", () => { + it("redacts inline secret values", () => { + expect(redactSensitiveArgument("--private-key=0xprivate")).toBe( + "--private-key=[REDACTED]", + ); + }); + + it("preserves flags without an attached value", () => { + expect(redactSensitiveArgument("--private-key")).toBe("--private-key"); + }); +}); diff --git a/cli/test/utils/solidityIdentifiers.test.ts b/cli/test/utils/solidityIdentifiers.test.ts new file mode 100644 index 00000000..e1561a83 --- /dev/null +++ b/cli/test/utils/solidityIdentifiers.test.ts @@ -0,0 +1,61 @@ +import { describe, expect, it } from "vitest"; +import { + assertSafeSolidityImportSpec, + assertSolidityContractName, + isSolidityIdentifier, +} from "../../src/utils/solidityIdentifiers"; + +describe("isSolidityIdentifier", () => { + it.each(["Diamond", "_Facet", "Facet2", "ERC721Facet", "__proto__"])( + "accepts %s", + (name) => { + expect(isSolidityIdentifier(name)).toBe(true); + }, + ); + + it.each([ + "", + "1Facet", + "Facet-Name", + "Facet Name", + "Facet.sol", + 'Facet";', + "Facet\n", + "Facet\\Name", + "Facet$Name", + ])("rejects %j", (name) => { + expect(isSolidityIdentifier(name)).toBe(false); + }); +}); + +describe("assertSolidityContractName", () => { + it("throws with an escaped representation of the rejected value", () => { + expect(() => assertSolidityContractName('Facet";\ncontract Evil {}', 'facet "Evil"')) + .toThrow("Invalid Solidity contract name"); + }); +}); + +describe("assertSafeSolidityImportSpec", () => { + it.each([ + "../src/Diamond.sol", + "./Diamond.sol", + "@perfect-abstractions/compose/diamond/DiamondInspectFacet.sol", + "../src/My File.sol", + ])("accepts %s", (spec) => { + expect(() => assertSafeSolidityImportSpec(spec, "test import")).not.toThrow(); + }); + + it.each([ + "", + '../src/Evil".sol', + "../src/Evil\nName.sol", + "../src/Evil\rName.sol", + "../src/Evil\\Name.sol", + "../src/Evil\u001b.sol", + "../src/Evil\u2028Name.sol", + ])("rejects %j", (spec) => { + expect(() => assertSafeSolidityImportSpec(spec, "test import")).toThrow( + "Invalid Solidity import path", + ); + }); +}); diff --git a/package-lock.json b/package-lock.json index b08e953a..8f11e627 100644 --- a/package-lock.json +++ b/package-lock.json @@ -53,7 +53,7 @@ "vitest": "^4.1.10" }, "engines": { - "node": ">=20" + "node": ">=22" } }, "cli/node_modules/@eslint/js": { diff --git a/website/docs/contribution/cli/code-style-guide.mdx b/website/docs/contribution/cli/code-style-guide.mdx index 594fe2eb..95223eab 100644 --- a/website/docs/contribution/cli/code-style-guide.mdx +++ b/website/docs/contribution/cli/code-style-guide.mdx @@ -139,7 +139,7 @@ Add a helper directly inside a module folder when the code supports that module - Return focused values such as models, selected facets, validation issues, render output, or typed state reads. - Keep domain-aware helpers inside the module folder, not in `utils`. -For example, `deployGeneration/module.ts` owns the pipeline-facing action, while `deployGeneration/model.ts` and `deployGeneration/renderers.ts` provide deploy-generation helpers. +For example, `deployScript/module.ts` owns the pipeline-facing action, while `deployScript/model.ts` and `deployScript/renderers.ts` provide deploy-script helpers. ### Pipeline diff --git a/website/docs/contribution/cli/development.mdx b/website/docs/contribution/cli/development.mdx index 6b3d04bd..d6326dd7 100644 --- a/website/docs/contribution/cli/development.mdx +++ b/website/docs/contribution/cli/development.mdx @@ -13,7 +13,7 @@ import DocSubtitle from '@site/src/components/docs/DocSubtitle'; ## Prerequisites -- [Node.js](https://nodejs.org/) (version 20 or higher) +- [Node.js](https://nodejs.org/) (version 22 or higher) - [npm](https://www.npmjs.com/) - Git diff --git a/website/docs/contribution/cli/testing.mdx b/website/docs/contribution/cli/testing.mdx index dc2bb87a..0ebf654b 100644 --- a/website/docs/contribution/cli/testing.mdx +++ b/website/docs/contribution/cli/testing.mdx @@ -27,10 +27,8 @@ cli/test/ │ └── IRPCAdapter/ │ └── adapter.test.ts ├── modules/ -│ └── deployGeneration/ -│ ├── fixtures/ -│ │ └── expected/ -│ │ └── Deploy.s.sol +│ ├── scaffoldHarness.ts +│ └── deployPlan/ │ ├── harness.ts │ └── module.test.ts ├── pipelines/ @@ -101,22 +99,21 @@ Modules are the main place to test CLI behavior. - Assert the resulting module state and any generated files. - Keep harnesses, fixtures, and mocks under `cli/test`. -The deploy generation test builds a complete ERC-20 context through its harness, executes the real module, and compares the generated script with an expected-output snapshot: +The test generation test builds a complete ERC-20 context through its harness, executes the real module, and asserts both the module state and the generated file: ```ts -const harness = await createDeployGenerationHarness(); +const harness = await createScaffoldHarness(); try { - const result = await DeployGenerationModule.generateDeployScript( + const result = await TestGenerationModule.generateTestFile( harness.ctx, - harness.scriptRoot, + path.join(harness.projectRoot, "test"), ); - const state = result.state.generateDeployScript as ModuleState; - const generated = await fs.readFile(state.result!.outputPath, "utf8"); - const expected = await fs.readFile(expectedDeployScriptPath, "utf8"); + const state = result.state.generateTestFile as ModuleState; + const source = await fs.readFile(state.result!.outputPath, "utf8"); expect(state.success).toBe(true); - expect(generated).toBe(expected); + expect(source).toContain("contract DiamondTest is Test"); } finally { await harness.cleanup(); } @@ -131,7 +128,7 @@ Some module actions depend on state produced by an earlier action. - Use a pipeline test when module order or the complete workflow is part of the behavior. - Avoid reproducing a large production state object in every test; move shared setup into the feature harness. -For example, a deploy generation harness provides the selected catalog, scaffold map, and project parameters because those are direct inputs to `DeployGenerationModule`. An info pipeline harness instead writes a real `compose.json` and facet source because loading and scanning are part of that pipeline's behavior. +For example, the shared scaffold harness provides the selected catalog, scaffold map, and project parameters because those are direct inputs to `ScaffoldingModule` and `TestGenerationModule`. An info pipeline harness instead writes a real `compose.json` and facet source because loading and scanning are part of that pipeline's behavior. ## Pipeline Tests diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 43b2f529..2591a70b 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -21,28 +21,38 @@ Compose is published as two npm packages: ## Prerequisites -- **[Node.js](https://nodejs.org/) >= 20**: required for the CLI and for npm-based Hardhat workflows +- **[Node.js](https://nodejs.org/) >= 22**: required for the CLI and Foundry workflows. Hardhat 3 projects generated by Compose require Node.js 22.13 or newer. - **[Foundry](https://book.getfoundry.sh/getting-started/installation) (Optional)**: required if you use a Foundry scaffold or integrate Solidity with Forge - **Git**: used by Foundry dependency installs inside generated projects ## Create a new project with Compose CLI -The fastest path is to run the CLI with `npx` (no global install): +Run the CLI with `npx` (no global install): ```bash npx @perfect-abstractions/compose-cli init ``` + +```bash +cd my-diamond +npm run build +npm test +npm run validate +``` + +The generated `package.json` exposes native framework commands as `npm run build` and `npm test` (plus `npm run fmt` for Foundry), and the Compose `npm run validate` workflow. Use `npx compose` for the remaining Compose commands, including `npx compose deploy`. + ### Manual Installation -To install the CLI globally: +To install the CLI globally instead: ```bash npm install -g @perfect-abstractions/compose-cli compose init ``` -## Add Compose to an existing project +## Add Compose library to an existing project ### Foundry @@ -62,7 +72,7 @@ Create a `remappings.txt` file in the root of your project with the following co npm install @perfect-abstractions/compose ``` -## Import Compose in your project +## Import in your project ```solidity import {DiamondMod} from "@perfect-abstractions/compose/diamond/DiamondMod.sol"; diff --git a/website/docs/getting-started/my-first-diamond.mdx b/website/docs/getting-started/my-first-diamond.mdx index 23d7884a..e9f1ea8a 100644 --- a/website/docs/getting-started/my-first-diamond.mdx +++ b/website/docs/getting-started/my-first-diamond.mdx @@ -20,7 +20,7 @@ This tutorial uses the `Counter` example: a minimal diamond with increment and r ## Prerequisites -- [Node.js](https://nodejs.org/) >= 20 +- [Node.js](https://nodejs.org/) >= 22 - [Foundry](https://book.getfoundry.sh/getting-started/installation) installed and on your PATH @@ -29,36 +29,23 @@ Althought the CLI support both Foundry and Hardhat, this tutorial will focus on If you haven't used Foundry before, follow the official installation guide first. You only need `forge` and `anvil` for this tutorial. -## Step 1) Install the CLI +## 1. Scaffold the project -Install the Compose CLI so you can run all the CLI commands - - -{`npm install -g @perfect-abstractions/compose-cli`} - - -Verify it's installed: +Run the Compose CLI with `npx` -{`compose --help`} +{`npx @perfect-abstractions/compose-cli init`} -You can skip the global package installation. Just use `npx @perfect-abstractions/compose-cli` wherever you see `compose` in this tutorial. - -## Step 2) Scaffold the project - - -{`compose init`} - - -You'll be prompt to choose from a lot of different options from framework, ERC standards templates, and others. +You'll be prompt with lot of different options from framework, ERC standards templates, and others. For this tutorial, we will choose the `Counter` example with the following options: - + {`Enter project name: my-diamond Select project framework: Foundry Select base: Counter +Select upgradeability: Immutable (no upgrade facet) Select extension facets: None Select Compose library facets: None Select ownership: None @@ -71,21 +58,20 @@ Take the time to review the full library available to you. We support most major You can always skip the interactive prompts entirely: -{`compose init my-first-diamond --framework foundry --base counter --yes`} +{`npx @perfect-abstractions/compose-cli init my-first-diamond --framework foundry --base counter --yes`} - When the CLI finishes, follow the next steps instruction to move into your project and test it: {`✔ Project "my-first-diamond" scaffolded in ".../my-first-diamond" Next steps: -1. cd my-first-diamond -2. forge build && forge test`} +1. cd "my-first-diamond" +2. forge test`} -## Step 3) Explore the project structure +## 2. Explore the project structure The scaffold generates a diamond with two local facets and one from the Compose library. @@ -97,11 +83,11 @@ The scaffold generates a diamond with two local facets and one from the Compose CounterIncrementFacet.sol ← increment the counter`} -Each facet owns a slice of the logic. `CounterDataFacet` exposes the count, `CounterIncrementFacet` mutates it. The `Diamond.sol` proxy routes calls to the right facet via function selectors. +Each facet owns a slice of the applicstion logic. `CounterDataFacet` exposes the count, `CounterIncrementFacet` mutates it. The `Diamond.sol` proxy routes calls to the right logic block via function selectors. ### Diamond.sol: The proxy -The diamond is the application entrypoint. Users call it, but it holds no logic itself, only the storage state. Every call is delegated to a stateless facet via the fallback function: +The [diamond](/docs/foundations/diamond-contracts) is the application entrypoint. Users call it, but it holds no logic itself, only the storage state. Every call is delegated to a stateless facet via the fallback function: {`contract Diamond { @@ -120,11 +106,17 @@ The diamond is the application entrypoint. Users call it, but it holds no logic When a function is called on the diamond, [`DiamondMod.diamondFallback()`](/docs/library/diamond/DiamondMod#diamondfallback) looks up which contract owns that selector and forwards the call. +Diagram showing a call being routed through the diamond proxy to the getCount() and increment() facets + There nothing more to make a diamond proxy work. Now, let's transition where our application logic lives ### CounterDataFacet.sol -Facets need to share state. They do this by pointing to the same storage slot: +Facet are where you implement your application logic. Think of it as stateless logic block that borrow the diamond storage to handle any data. {`contract CounterDataFacet { @@ -159,23 +151,26 @@ Facets need to share state. They do this by pointing to the same storage slot: }`} -Any facet that need `Counter` data uses the same `STORAGE_POSITION [ keccak256("counter") ]` and `CounterStorage` struct. They never import each other. They just agree on the same storage location. +Any facet that need `Counter` data uses the same `STORAGE_POSITION = keccak256("counter")` and `CounterStorage` struct. They never import each other. They just agree on the same storage contract. + Facets can be scoped based on your project needs. Compose encourages small scoped facets, one facet per responsibility, to allow granular composition. In this example, `CounterDataFacet` handles reads and `CounterIncrementFacet` handles mutations. You could combine them into a single facet, but keeping them separate lets you pick exactly the functionality you need at anytime + -## Step 4) Build and test +## 3. Build and test Now let's compile and run the tests: -{`forge build && forge test -vv`} +{`forge build +forge test -vv`} You should see compilation succeed and one passing test in `/test/Diamond.t.sol` The test deploys a diamond with all three facets the `Counter` needs, then calls `facetAddresses()` on `DiamondInspectFacet` to verify the right number of facets are registered. -## Step 5) Write your own test +## 4. Write your own test Let's interact with the `Counter` through a test. Open `test/Diamond.t.sol` and take a look at what's already there: @@ -217,7 +212,11 @@ contract DiamondTest is Test { The test file already has a `setUp()` function that deploys a fresh `Diamond` instance before each test. There's also one test that verifies all three facets are properly registered on the proxy. -Take a look at the order here. The facets are deployed first as separate contracts, then the Diamond proxy is created with references to those pre-deployed facet addresses. This is the core of [composition](/docs/design/design-for-composition) over inheritance. Instead of a monolithic contract that `is` everything through inheritance chains, the Diamond `has` the facets it needs. They're composed at runtime via the constructor or the upgrade functionality. +Take a look at the order here. The facets are deployed first as separate contracts, then the proxy is created with references to those pre-deployed facet addresses. + +This is the core of [composition](/docs/design/design-for-composition) over inheritance. Instead of a monolithic contract that `is` everything through inheritance chains, the Diamond `has` the facets it needs. + +They're composed at runtime via the constructor or the upgrade functionality. Now let's add a test that actually uses our `Counter`. Add this function inside the `DiamondTest` contract: @@ -254,7 +253,7 @@ Run the test suite: All tests pass, demonstrating that data written by one facet is immediately visible to another through the diamond's shared storage. -## Step 6) Deploy locally +## 5. Deploy locally Start a local Ethereum node in one terminal: @@ -262,34 +261,40 @@ Start a local Ethereum node in one terminal: {`anvil`} -In a second terminal, deploy your Counter application: +In a second terminal, plan the deployment and generate the managed script: + + +{`npx compose deploy`} + + +`npx compose deploy` plans the deployment from `compose.json` and writes `script/ComposeDeploy.s.sol`. + +Always review the script, then broadcast it with Anvil's test key: - -{`forge script script/Deploy.s.sol:DeployScript \\ - --rpc-url http://localhost:8545 \\ - --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \\ - --broadcast`} + +{`npx compose deploy --broadcast -- --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`} +The deployment is verified and recorded in `compose.lock`. + The private key above is Anvil's default test key. **Never use it on a real network.** -You'll see the deployed addresses logged: +You'll see the diamond address logged as the script runs: {`== Logs == - CounterDataFacet: 0x5FbDB2315678afecb367f032d93F642f64180aa3 - CounterIncrementFacet: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 - DiamondInspectFacet: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0 Diamond: 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9`} #### Congratulations! -You just deployed your first diamond proxy application. You've scaffolded a `Counter` project using the CLI, written tests that verify shared storage across facets, and deployed a composed system to a local network. +You just deployed your first diamond application. + +We've scaffolded together a `Counter` project using the CLI, written tests that verify shared storage across facets, and deployed a composed system to a local network. -We recommend you to explore all the template available to scaffold. Use the the `catalog` command to review what's available to you. +We recommend you to explore all the template available to scaffold. Use the `npx compose catalog` command to review what's available to you. ## What's next? diff --git a/website/static/img/svg/counter-proxy.svg b/website/static/img/svg/counter-proxy.svg new file mode 100644 index 00000000..bb1885e1 --- /dev/null +++ b/website/static/img/svg/counter-proxy.svg @@ -0,0 +1,4 @@ + + +getCount()increment() \ No newline at end of file