gate-evm-tools 1.0.27 → 1.0.28

package/docs/superpowers/plans/2026-07-22-manifest-bootstrap-transaction.md

@@ -0,0 +1,50 @@
+# Manifest Bootstrap and Transaction Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make bare gate-tool manifest commands route to the intended release-stage directory before OpenZeppelin loads and recover the exact manifest after any failed sync.
+
+**Architecture:** A dependency-free bin bootstrap validates CLI/environment routing before dynamically importing the compiled command tree. A focused manifest transaction utility owns confinement, locking, byte snapshots, atomic writes, rollback, hashes, and audit reports around `forceImport`.
+
+**Tech Stack:** Node.js ESM, TypeScript, OpenZeppelin upgrades-core, Node test runner.
+
+---
+
+### Task 1: Pre-import manifest bootstrap
+
+**Files:**
+- Create: `bin/manifest-bootstrap.js`
+- Modify: `bin/cli.js`
+- Create: `test/manifest-bootstrap.test.mjs`
+- Modify: `package.json`
+
+- [ ] Write failing tests for `bscDev`, `bscProd`, local, explicit custom directories, environment conflicts, ambiguous mutating networks, traversal, and symlink escape.
+- [ ] Add a module-load-order test proving the environment is set before a simulated upgrades-core import observes it.
+- [ ] Run the focused tests and confirm missing bootstrap behavior.
+- [ ] Implement strict argv parsing and confinement, invoke it before `import('../dist/index.js')`, then re-run tests.
+
+### Task 2: Transactional sync
+
+**Files:**
+- Create: `src/utils/manifestTransaction.ts`
+- Modify: `src/core/syncUpgradeJson.ts`
+- Create: `test/manifest-transaction.test.mjs`
+
+- [ ] Write failing tests for success hashes, concurrent lock rejection, exact-byte rollback, new-file removal, atomic replacement, and symlink rejection.
+- [ ] Implement a dedicated gate-tool lock, snapshots, atomic write helper, rollback, and JSON audit report.
+- [ ] Wrap `forceImport`, manifest validation, and tx-hash enrichment in the transaction and expose report/hash fields in the result.
+- [ ] Run focused and full tests.
+
+### Task 3: Packaging, docs, and integration
+
+**Files:**
+- Modify: `src/core/BytecodeChecker.ts` or its import to use canonical casing
+- Modify: `README.md`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Verify: `dist/**`
+
+- [ ] Add tests that package metadata runs the Node suite and includes bootstrap files.
+- [ ] Correct the existing filename/import casing mismatch so Linux and case-sensitive builds agree.
+- [ ] Document conventional routing, explicit custom `MANIFEST_DEFAULT_DIR`, fail-closed behavior, transaction reports, and full-workflow usage.
+- [ ] Bump gate-tool to `1.0.21`, build `dist`, run all tests, and perform a bare CLI fixture integration check.

package/docs/superpowers/plans/2026-07-22-manifest-review-remediation.md

@@ -0,0 +1,49 @@
+# Manifest Review Remediation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the reviewed rollback, writer-serialization, CLI bootstrap, local-network, and report-collision gaps without weakening fail-closed manifest routing.
+
+**Architecture:** Resolve OpenZeppelin's canonical and fallback manifest paths together, confine and lock them by the canonical path, snapshot both exact byte streams, reject dual-file ambiguity, and restore both names exactly on failure. Reuse the same lock around every `sync` and `validate` mutation; emit a per-manifest report path. Treat OpenZeppelin development manifests outside the repository as unsupported for mutating commands.
+
+**Tech Stack:** Node.js ESM, TypeScript, OpenZeppelin upgrades-core, Node test runner.
+
+---
+
+### Task 1: Bootstrap aliases and local fail-closed behavior
+
+**Files:**
+- Modify: `test/manifest-bootstrap.test.mjs`
+- Modify: `bin/manifest-bootstrap.js`
+- Modify: `README.md`
+
+- [ ] Add a failing load-order test for `-n bscDev`.
+- [ ] Change the local-network expectation to an explicit unsupported error and confirm RED.
+- [ ] Parse `--network` and `-n` before command imports; reject local manifest mutations with an actionable error.
+- [ ] Re-run the focused bootstrap tests.
+
+### Task 2: Canonical/fallback transaction and shared writers
+
+**Files:**
+- Modify: `test/manifest-transaction.test.mjs`
+- Modify: `src/utils/openzeppelin.ts`
+- Modify: `src/utils/manifestTransaction.ts`
+- Modify: `src/core/syncUpgradeJson.ts`
+- Modify: `src/core/validateAndGenerateCalldata.ts`
+
+- [ ] Add failing tests for fallback rename rollback, dual-file ambiguity, temporary exact restore, and a shared lock blocking a concurrent writer.
+- [ ] Expose both OpenZeppelin manifest paths.
+- [ ] Implement a canonical lock plus exact two-path snapshots/restoration.
+- [ ] Wrap persistent and temporary `validate` mutations with the shared protocol.
+- [ ] Require sync success to leave one canonical regular file and emit a distinct per-manifest report.
+- [ ] Re-run focused tests after each behavior.
+
+### Task 3: Packaging and verification
+
+**Files:**
+- Modify: `README.md`
+- Verify: `dist/**`
+
+- [ ] Document fallback restoration, shared writer locking, local rejection, and returned report paths.
+- [ ] Build `dist`, run the complete test suite, and run `npm pack --dry-run` with the isolated cache.
+- [ ] Inspect the diff and commit the remediation.

package/docs/superpowers/plans/2026-08-17-custody-hardhat-signers.md

@@ -0,0 +1,227 @@
+# Custody Hardhat Signers Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extend `gate-evm-tools` with one custody credential format that automatically creates an ethers v5 or v6 remote signer and transparently supplies it through Hardhat signer helpers.
+
+**Architecture:** A dependency-light credential module parses real private keys and `custody:<ProjectSecret>:<WalletAddress>` values. A runtime signer factory receives the active `hre.ethers` object, detects its real major version, and constructs the matching v5/v6 Signer without bundling ethers. A Hardhat environment wrapper replaces `getSigners`, matching `getSigner`, and matching `provider.getSigner`, while real private keys continue through native `networks.accounts`. The package publishes ESM and CJS subpath exports so both modern imports and Hardhat 2 configuration loading work.
+
+**Tech Stack:** TypeScript, Node.js ESM/CJS, Node test runner, ethers 5.7/6.15, Hardhat 2, OpenZeppelin Hardhat Upgrades 3.9.
+
+---
+
+### Task 1: Credential parsing and Hardhat accounts
+
+**Files:**
+- Create: `test/custody-credential.test.mjs`
+- Create: `src/custody/credential.ts`
+- Create: `src/custody/version.ts`
+- Create: `src/custody/index.ts`
+
+- [ ] **Step 1: Write failing credential tests**
+
+Test these public calls before they exist:
+
+```js
+parseWalletCredential(`0x${"11".repeat(32)}`)
+parseWalletCredential(`custody:${projectSecret}:${walletAddress}`)
+resolveHardhatAccounts(custodyCredential)
+resolveWalletCredential({ PRIVATE_KEY: custodyCredential })
+detectEthersMajor({ version: "ethers/5.7.2" })
+detectEthersMajor({ version: "6.15.0" })
+```
+
+Require private keys to normalize to `0x` form, custody credentials to expose only the parsed secret/address internally, custody accounts to return `[]`, private-key accounts to return `[privateKey]`, conflicting environment variables to fail, zero/invalid addresses to fail, and unsupported ethers versions to fail.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+npm run build
+node --test test/custody-credential.test.mjs
+```
+
+Expected: FAIL because `gate-evm-tools/custody` is not exported.
+
+- [ ] **Step 3: Implement minimal parsing and version detection**
+
+Expose:
+
+```ts
+parseWalletCredential(value: string): ParsedWalletCredential
+resolveWalletCredential(env?: NodeJS.ProcessEnv): ParsedWalletCredential | undefined
+resolveHardhatAccounts(value?: string): string[]
+detectEthersMajor(ethersRuntime: { version?: unknown }): 5 | 6
+```
+
+Accept only `0x`-optional 64-hex private keys or the versioned custody format. Never treat a valid-looking 64-hex value as a custody credential.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run the focused test and require all assertions to pass.
+
+### Task 2: Real ethers v5/v6 remote signers
+
+**Files:**
+- Create: `test/custody-signer.test.mjs`
+- Create: `src/custody/service.ts`
+- Create: `src/custody/signer.ts`
+- Modify: `src/custody/index.ts`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+
+- [ ] **Step 1: Install a test-only ethers v5 alias**
+
+Add:
+
+```json
+"ethers5": "npm:ethers@5.7.2"
+```
+
+Keep host `ethers` as a peer dependency rather than a production dependency.
+
+- [ ] **Step 2: Write failing cross-version signer tests**
+
+For real ethers 5.7 and 6.15 runtime objects, require `createSigner` to:
+
+```js
+createSigner({
+  ethers: ethersRuntime,
+  credential,
+  provider,
+  baseUrl: "http://custody.local",
+  fetchImpl,
+})
+```
+
+Test a real private key returns the matching native Wallet. For custody mode, make the fake HTTP service sign transactions, UTF-8 messages, byte messages, and EIP-712 values with a known wallet. Require v6 `signTypedData`, v5 `_signTypedData`, locally recovered addresses, signed raw transaction sender, unchanged unsigned transaction, Authorization header, endpoint paths, and unique idempotency keys.
+
+- [ ] **Step 3: Verify RED**
+
+Run the focused test. Expected: FAIL because `createSigner` does not exist.
+
+- [ ] **Step 4: Implement service client and dynamic signer classes**
+
+The v6 class must extend the active runtime's `AbstractSigner`; the v5 class must extend its `Signer`. Both implement `getAddress`, `connect`, `signTransaction`, and `signMessage`; v6 implements `signTypedData`, while v5 implements `_signTypedData`. Validate every returned signature locally before returning it, and compare signed/unsigned transaction payloads before broadcast.
+
+- [ ] **Step 5: Verify GREEN**
+
+Run focused credential and signer tests for both majors.
+
+### Task 3: Hardhat signer injection
+
+**Files:**
+- Create: `test/custody-hardhat.test.mjs`
+- Create: `src/custody/hardhat-runtime.ts`
+- Create: `src/custody/hardhat.ts`
+
+- [ ] **Step 1: Write failing Hardhat wrapper tests**
+
+Use v5 and v6-shaped HRE fixtures. Require custody mode to return the remote signer from:
+
+```js
+await hre.ethers.getSigners()
+await hre.ethers.getSigner(custodyAddress)
+await hre.ethers.provider.getSigner(0)
+await hre.ethers.provider.getSigner(custodyAddress)
+```
+
+Require an unrelated address and non-custody configuration to delegate to the original methods. Require version/address logging without logging the Project Secret.
+
+- [ ] **Step 2: Verify RED**
+
+Run the focused test. Expected: FAIL because `installCustodyHardhatRuntime` does not exist.
+
+- [ ] **Step 3: Implement runtime installation and plugin registration**
+
+Expose a pure testable installer and register it through `extendEnvironment`. Read `WALLET_CREDENTIAL` or legacy `PRIVATE_KEY` only when signer helpers execute, cache by credential, require `CUSTODY_API_BASE_URL`, and never change impersonated signers.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run all custody unit tests.
+
+### Task 4: Dual ESM/CJS packaging and documentation
+
+**Files:**
+- Create: `tsconfig.custody-cjs.json`
+- Create: `scripts/write-cjs-package.mjs`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `README.md`
+- Verify: `dist/custody/**`
+- Verify: `dist-cjs/custody/**`
+
+- [ ] **Step 1: Write failing package export tests**
+
+Extend tests to load both:
+
+```js
+await import("gate-evm-tools/custody")
+require("gate-evm-tools/custody")
+await import("gate-evm-tools/hardhat")
+require("gate-evm-tools/hardhat")
+```
+
+Expected before packaging work: CJS or subpath resolution fails.
+
+- [ ] **Step 2: Build both module formats**
+
+Compile all source to `dist` as ESM and custody source to `dist-cjs` as CommonJS. Write `dist-cjs/package.json` containing `{ "type": "commonjs" }`. Add `exports` entries with `types`, `import`, and `require`, include `dist-cjs/` in package files, expand the ethers peer range to `>=5.7.0 <7.0.0`, and build before tests.
+
+- [ ] **Step 3: Document migration**
+
+Document:
+
+```ts
+import { resolveHardhatAccounts } from "gate-evm-tools/hardhat";
+
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+accounts: resolveHardhatAccounts(PRIVATE_KEY)
+```
+
+Explain that business scripts stay unchanged, custody mode leaves native accounts empty, v5/v6 are selected from `hre.ethers.version`, and OpenZeppelin CREATE2 patching remains independent.
+
+- [ ] **Step 4: Verify package contents**
+
+Run build, all tests, and `npm pack --dry-run`; require both module formats and docs to be included with no fixture secrets.
+
+### Task 5: Native Hardhat and OpenZeppelin local integration
+
+**Files:**
+- Create: `test/fixtures/custody-hardhat-v6/**`
+- Create: `scripts/test-custody-hardhat-v6.mjs`
+- Modify: `package.json`
+
+- [ ] **Step 1: Create a local native fixture**
+
+Start a Hardhat node with its public first development key, start a mock custody HTTP service for that key, and run a second Hardhat config whose remote `localhost` network uses:
+
+```ts
+accounts: resolveHardhatAccounts(process.env.PRIVATE_KEY)
+```
+
+The deployment script must call `ethers.getContractFactory` and `upgrades.deployProxy` without explicitly passing a signer.
+
+- [ ] **Step 2: Verify the native flow**
+
+Set only the composite `PRIVATE_KEY`, custody URL, and RPC URL. Require implementation/proxy deployment transactions to hit `/sign-transaction`, the proxy state to be initialized, and the signer address to equal the custody address.
+
+- [ ] **Step 3: Final verification**
+
+Run:
+
+```bash
+npm test
+npm run test:custody:hardhat-v6
+npm pack --dry-run
+git diff --check
+```
+
+Expected: all commands exit 0. Record the limitation that a separate native ethers-v5 Hardhat fixture remains necessary before publishing v5 support if the real plugin integration differs from the unit-tested runtime contract.
+
+## Self-review
+
+- Spec coverage: unified credential, native private key fallback, automatic ethers v5/v6 detection, Hardhat signer replacement, OpenZeppelin proxy deployment, ESM/CJS loading, and local tests are covered.
+- Safety: Project Secrets are never logged or written to fixtures; the mock uses only Hardhat's public development key.
+- Type consistency: the public factory, Hardhat wrapper, and tests all use the same credential and signer option names.

package/docs/superpowers/plans/2026-09-09-remove-template-infrastructure-contracts.md

@@ -0,0 +1,11 @@
+# Remove template infrastructure contracts
+
+Goal: business projects consume deployed Multicall and placeholder addresses without compiling their implementations.
+
+- [x] Add packaged authority ABI; use it in deploy/upgrade without named Multicall artifacts.
+- [x] Accept business implementation name in proxy step.contract, require agreement with firstUpgrade.contract, retain legacy placeholder name as compatibility metadata.
+- [x] Remove two template contracts, compile ERC1967Proxy directly from OpenZeppelin through the package adapter and business compiler configuration.
+- [x] Update examples, initialization detection and tests; do not delete historical project contracts automatically.
+- [x] Bump minimum runtime/template patch versions and validate using a local tarball, tests and no-broadcast compilation.
+
+Compatibility: deployed infrastructure and proxy init code must remain unchanged. No redeployment, salt changes, transaction broadcast, npm publication or Git push. Historical artifact fixtures stay available for unrelated infrastructure deployment tests.