Repository navigation
feat(cli): managed compose deploy workflow - #418
Merged
Merged
Conversation
- nest compose.lock deployments as diamond → chain → instance and make LockFileModule instance-aware (isLockStale, getDeployment, setDeployment) - reject the legacy two-level lock layout with a migration hint and name the offending instance in field errors - validate every recorded instance in compose validate and print chain/instance scope in bytecode validation reports - update the example lock file and tests; add a minor changeset
- prompt for upgradeability (immutable by default) and add the --upgradeable / --immutable flags; an explicit DiamondUpgradeFacet library entry opts in, and combining it with --immutable is an error - couple upgradeable diamonds to an owner base: interactive runs confirm the owner base, non-interactive runs add it and print a note - scaffold a local Hardhat network (http://127.0.0.1:8545, remote accounts) and fix the scaffolded .gitignore to ignore cache/ - update docs and tests; add a minor changeset
- plan the deployment from compose.json and the instance-aware lock record, generate a reviewable framework script, execute it through forge/hardhat, verify the result on-chain, and record the deployment - review gate: print the project-relative script path and ask before running; add --broadcast, --dry-run, --redeploy, --instance, --chain, and --project-root - forward arguments after -- to the framework so signing stays with forge/hardhat; add adapter deploy commands, artifact bytecode reads, and broadcast transaction parsing (Hardhat captures its managed result in cache/compose/deploy-result.json) - hoist isInteractive and toProjectRelativePath into shared utils and route "deploy" through the pipeline builder - add module, pipeline, and E2E tests; add a minor changeset
- remove init-time deploy script generation (DeployGenerationModule and its templates/tests); compose deploy owns the managed script now - keep the empty script/ (Foundry) and scripts/ (Hardhat) directories so projects have a conventional place for scripts - decouple test generation from the deploy model: build the facet list from the scaffold map plus the selected facets, and classify base vs library groups locally - share the scaffold test harness with the diamond and scaffolding suites - update the README templates, CLI README, and website docs; add a minor changeset
- append the endpoint and the deepest cause message (bounded) to requestError messages so transport failures explain themselves - pass the RPC URL through every adapter operation that reports errors
✅ Deploy Preview for compose-diamonds ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
🦋 Changeset detectedLatest commit: a5e46a1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
CLI CoverageCommit:
|
Add `compose test` to run the project's test suite through its detected framework (`forge test` or `npx hardhat test`). Arguments after `--` are forwarded to the framework, and `--project-root` points at the project to test. Extract passthrough normalization into a shared utility so deploy and test handle `--` arguments the same way.
Search the framework's own package root first (Foundry `lib/Compose`, Hardhat `node_modules`) instead of treating matches in both roots as ambiguous. This matters for Foundry projects that also get an npm copy through the CLI dependency. Ambiguity is still reported when multiple matches exist inside the selected root.
Add `@perfect-abstractions/compose-cli` to generated projects' devDependencies and install it, so every Compose command runs locally with `npx compose` without a global install. Foundry projects get a generated `package.json` and `node_modules/` gitignore entry; Hardhat projects get the devDependency alongside their toolbox. Preflight now requires npm for Foundry when dependencies will be installed, and the init next steps, generated READMEs, and tutorial use the `npx compose` flow.
maxnorm
marked this pull request as ready for review
October 28, 2026 23:57
Collaborator
|
@maxnorm |
Collaborator
Author
|
Perfect! I glad the workflow works well. I'll do a refactoring pass right now before merging. |
Bump the CLI engine requirement to Node.js 22 and add a shared nodeVersion utility that asserts Node.js 22.13+ before initializing a Hardhat 3 project. Preflight and the Hardhat adapter now use it, and the README, generated project README, and website prerequisites agree on the requirement.
Split the shared adapter declarations into IFrameworkAdapter/types.ts and extend the interface with account, signer, toolbox, and project-support capabilities. Foundry keystore reads, signer listing, key import, and deploy-signer resolution move from accountPipeline into the Foundry adapter; Hardhat signer listing moves into the Hardhat adapter and its transient probe becomes a deterministic template rendered into the ignored `.compose/hardhat/` runtime directory instead of a random UUID script in `scripts/`. assertHardhat3 and detectHardhatToolbox relocate into the Hardhat adapter, composeError normalizes into utils/errors, and the account pipeline now delegates to a dedicated accounts module (model, module, output) that records typed results and failures in ctx.state.account. Project .gitignore maintenance consolidates into utils/gitignore, and generated and existing projects keep `.compose/` ignored.
The plan hash now uses stable import specifiers instead of absolute source paths, so an artifact prepared in one checkout validates in another, and it no longer folds in the selected signer: instead the Ignition deployment ID is scoped per signer, the effective deploy signer (including a framework default) is resolved before execution, and the reported deployer is validated against it. Broadcast verification also rejects duplicate or diamond-owned facet addresses and checks that every selector a facet exposes routes back to that facet before compose.lock is written. Generated artifacts validate contract names and import specifiers as Solidity identifiers, escape the chain key in the Foundry header comment, and quote imports and the diamond contract via JSON.stringify to close the code-injection path from compose.json. Hardhat builds once under the production profile and runs the probe, runner, and Ignition with --no-compile; lock reads move onto the shared gitignore helper and the nested cache/compose/.gitignore workaround is gone as the transient runner and deploy result move under .compose/hardhat/.
Duplicate registrations now name the current source and the remove or rename path, removing the last facet points at the diamond rule, unknown catalog references list the accepted reference shapes, facet-source conflicts show the keep-or-move choice for the exact destination, and a missing diamond lists the configured ones. Package-sourced facets are merged into the Compose npmFilesToBuild overlay in hardhat.config.ts before the validating compile, with a revert on failure.
Startup loads only the nearest project's .env instead of merging every ancestor, so a parent workspace cannot leak configuration into an unrelated project. compose.lock reads likewise stay inside the project root: a nested project no longer plans against an ancestor's lock or overwrites one.
Add an optional getAccountKeyVariable adapter capability and a conservative hardhat.config.ts reader that returns the selected network's literal configVariable signer name only when the config is unambiguous; custom, multiple, or unreadable account entries resolve to null instead of a guess. account setup replaces the synthetic COMPOSE_<alias>_PRIVATE_KEY hint with structured "Account registered / Next steps" output: the detected keystore command (or generic guidance naming the configured signer source), the cast wallet import step when the Foundry keystore is still missing, and the compose account check command with the default chain filled in. Generated Hardhat and Foundry project READMEs and the CLI README now walk through the real store, register, check, deploy sequence.
The transient Ignition runner now echoes each deployed facet name and address alongside the diamond, so a broadcast reports the full composition without opening the result file or compose.lock.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a managed
compose deployworkflow to the CLI: plan a diamond deployment fromcompose.json, generate a reviewable framework script, execute it through Foundry/Hardhat, verify the result on-chain, and record it incompose.lock. To support this, the lock file becomes instance-aware,compose initgains upgradeability selection, and deploy scripts move from init-time generation to on-demand generation bycompose deploy.Chnages
Managed deploy workflow
compose deployis a two-step workflow:compose deployresolves the plan, writes the managed artifact, prints its path, and stops for review. It does not prompt, execute, or broadcast.compose deploy --dry-runsimulates the reviewed artifact on a pinned fork. No transactions are sent;compose.lockis unchanged.compose deploy --broadcastexecutes the reviewed artifact, verifies the deployment on-chain, and writescompose.lockonly after verification succeeds.Flags:
--diamond <name>--chain <chain-key>--rpc-url <url>— one-invocation override; chain identity still comes fromcompose.json--account <alias>— Compose account alias--instance <name>— deployment instance, defaultdefault--project-root <dir>--dry-run--broadcast--redeploy— abandon the existing record and plan a fresh deployment--— forward remaining arguments toforge scriptorhardhat runSafety behavior:
--dry-runand--broadcastrefuse a missing, modified, or stale managed artifact.--dry-runpins the fork block.in syncor an add/remove diff and a non-zero exit.--redeployis required to replace a record. Applying upgrades is a later milestone.Framework behavior:
script/ComposeDeploy.s.sol. Compose reads the run broadcast to recover facet and diamond addresses.ignition/modules/ComposeDeploy.tsmodule plus a transientscripts/.compose/ignition-runner.ts. The runner captures the result incache/compose/deploy-result.json; the diamond transaction hash is read from the Ignition journal by future ID.Instance-aware
compose.lockdiamond → chain → instance → deployment.LockFileModuleis instance-aware for read, write, lookup, and staleness.compose validatechecks every recorded instance.Upgradeability at init
compose initprompts for upgradeability. Immutable is the default.--upgradeableand--immutable.--upgradeableaddsDiamondUpgradeFacetand couples theownerbase when no ownership base is selected.DiamondUpgradeFacetlibrary entry opts in for compatibility.DiamondUpgradeFacetcombined with--immutableis an error.Hardhat 3 and generated projects
localHTTP network and a preconfiguredsepolianetwork.sepoliaRPC endpoint..env.exampleand.gitignoreupdates.npx composeuses the local version.Deploy scripts generated on demand
DeployGenerationModule, its templates, and tests.compose deployowns managed script generation.script/andscripts/directories remain as conventional locations.compose testand generated scriptscompose test; arguments after--are forwarded toforge testornpx hardhat test.npm run buildnpm testnpm run fmtfor Foundrynpm run validatenpx compose deploy; nonpm run deployscript is generated.compose buildandcompose testremain available as convenience wrappers.Accounts and RPC
compose deploy --rpc-url <url>overrides the endpoint for preflight, deployment, and verification without changingcompose.json.Hardening
lib/Composenode_modulesDocs, examples, and tests
Breaking changes and migration
compose initno longer scaffolds a deploy script. The firstcompose deploygenerates it.--redeployabandons the record and deploys fresh.Checklist
Before submitting this PR, please ensure:
Code follows the Solidity feature ban - No inheritance, constructors, modifiers, public/private variables, external library functions,
using fordirectives, orselfdestructCode follows Design Principles - Readable, uses diamond storage, favors composition over inheritance
Code matches the codebase style - Consistent formatting, documentation, and patterns (e.g. ERC20Facet.sol)
Code is formatted with
forge fmtExisting tests pass - Run tests to be sure existing tests pass.
New tests are optional - If you don't provide tests for new functionality or changes then please create a new issue so this can be assigned to someone.
All tests pass - Run
forge testand ensure everything worksDocumentation updated - If applicable, update relevant documentation
Changesets — If this PR changes publishable packages (
src/,cli/), changeset-bot will comment if a release note might be needed. You can add one when convenient or defer to maintainers.Make sure to follow the contributing guidelines.
Additional Notes