@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/web3-testing.md

@@ -0,0 +1,427 @@
+---
+name: web3-testing
+description: Test smart contracts comprehensively using Hardhat and Foundry with unit tests, integration tests, and mainnet forking. Use when testing Solidity contracts, setting up blockchain test suites, or validating DeFi protocols.
+---
+
+# Web3 Smart Contract Testing
+
+Master comprehensive testing strategies for smart contracts using Hardhat, Foundry, and advanced testing patterns.
+
+## Do not use this skill when
+
+- The task is unrelated to web3 smart contract testing
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Writing unit tests for smart contracts
+- Setting up integration test suites
+- Performing gas optimization testing
+- Fuzzing for edge cases
+- Forking mainnet for realistic testing
+- Automating test coverage reporting
+- Verifying contracts on Etherscan
+
+## Hardhat Testing Setup
+
+```javascript
+// hardhat.config.js
+require("@nomicfoundation/hardhat-toolbox");
+require("@nomiclabs/hardhat-etherscan");
+require("hardhat-gas-reporter");
+require("solidity-coverage");
+
+module.exports = {
+  solidity: {
+    version: "0.8.19",
+    settings: {
+      optimizer: {
+        enabled: true,
+        runs: 200,
+      },
+    },
+  },
+  networks: {
+    hardhat: {
+      forking: {
+        url: process.env.MAINNET_RPC_URL,
+        blockNumber: 15000000,
+      },
+    },
+    goerli: {
+      url: process.env.GOERLI_RPC_URL,
+      accounts: [process.env.PRIVATE_KEY],
+    },
+  },
+  gasReporter: {
+    enabled: true,
+    currency: "USD",
+    coinmarketcap: process.env.COINMARKETCAP_API_KEY,
+  },
+  etherscan: {
+    apiKey: process.env.ETHERSCAN_API_KEY,
+  },
+};
+```
+
+## Unit Testing Patterns
+
+```javascript
+const { expect } = require("chai");
+const { ethers } = require("hardhat");
+const {
+  loadFixture,
+  time,
+} = require("@nomicfoundation/hardhat-network-helpers");
+
+describe("Token Contract", function () {
+  // Fixture for test setup
+  async function deployTokenFixture() {
+    const [owner, addr1, addr2] = await ethers.getSigners();
+
+    const Token = await ethers.getContractFactory("Token");
+    const token = await Token.deploy();
+
+    return { token, owner, addr1, addr2 };
+  }
+
+  describe("Deployment", function () {
+    it("Should set the right owner", async function () {
+      const { token, owner } = await loadFixture(deployTokenFixture);
+      expect(await token.owner()).to.equal(owner.address);
+    });
+
+    it("Should assign total supply to owner", async function () {
+      const { token, owner } = await loadFixture(deployTokenFixture);
+      const ownerBalance = await token.balanceOf(owner.address);
+      expect(await token.totalSupply()).to.equal(ownerBalance);
+    });
+  });
+
+  describe("Transactions", function () {
+    it("Should transfer tokens between accounts", async function () {
+      const { token, owner, addr1 } = await loadFixture(deployTokenFixture);
+
+      await expect(token.transfer(addr1.address, 50)).to.changeTokenBalances(
+        token,
+        [owner, addr1],
+        [-50, 50],
+      );
+    });
+
+    it("Should fail if sender doesn't have enough tokens", async function () {
+      const { token, addr1 } = await loadFixture(deployTokenFixture);
+      const initialBalance = await token.balanceOf(addr1.address);
+
+      await expect(
+        token.connect(addr1).transfer(owner.address, 1),
+      ).to.be.revertedWith("Insufficient balance");
+    });
+
+    it("Should emit Transfer event", async function () {
+      const { token, owner, addr1 } = await loadFixture(deployTokenFixture);
+
+      await expect(token.transfer(addr1.address, 50))
+        .to.emit(token, "Transfer")
+        .withArgs(owner.address, addr1.address, 50);
+    });
+  });
+
+  describe("Time-based tests", function () {
+    it("Should handle time-locked operations", async function () {
+      const { token } = await loadFixture(deployTokenFixture);
+
+      // Increase time by 1 day
+      await time.increase(86400);
+
+      // Test time-dependent functionality
+    });
+  });
+
+  describe("Gas optimization", function () {
+    it("Should use gas efficiently", async function () {
+      const { token } = await loadFixture(deployTokenFixture);
+
+      const tx = await token.transfer(addr1.address, 100);
+      const receipt = await tx.wait();
+
+      expect(receipt.gasUsed).to.be.lessThan(50000);
+    });
+  });
+});
+```
+
+## Foundry Testing (Forge)
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "forge-std/Test.sol";
+import "../src/Token.sol";
+
+contract TokenTest is Test {
+    Token token;
+    address owner = address(1);
+    address user1 = address(2);
+    address user2 = address(3);
+
+    function setUp() public {
+        vm.prank(owner);
+        token = new Token();
+    }
+
+    function testInitialSupply() public {
+        assertEq(token.totalSupply(), 1000000 * 10**18);
+    }
+
+    function testTransfer() public {
+        vm.prank(owner);
+        token.transfer(user1, 100);
+
+        assertEq(token.balanceOf(user1), 100);
+        assertEq(token.balanceOf(owner), token.totalSupply() - 100);
+    }
+
+    function testFailTransferInsufficientBalance() public {
+        vm.prank(user1);
+        token.transfer(user2, 100); // Should fail
+    }
+
+    function testCannotTransferToZeroAddress() public {
+        vm.prank(owner);
+        vm.expectRevert("Invalid recipient");
+        token.transfer(address(0), 100);
+    }
+
+    // Fuzzing test
+    function testFuzzTransfer(uint256 amount) public {
+        vm.assume(amount > 0 && amount <= token.totalSupply());
+
+        vm.prank(owner);
+        token.transfer(user1, amount);
+
+        assertEq(token.balanceOf(user1), amount);
+    }
+
+    // Test with cheatcodes
+    function testDealAndPrank() public {
+        // Give ETH to address
+        vm.deal(user1, 10 ether);
+
+        // Impersonate address
+        vm.prank(user1);
+
+        // Test functionality
+        assertEq(user1.balance, 10 ether);
+    }
+
+    // Mainnet fork test
+    function testForkMainnet() public {
+        vm.createSelectFork("https://eth-mainnet.alchemyapi.io/v2/...");
+
+        // Interact with mainnet contracts
+        address dai = 0x6B175474E89094C44Da98b954EedeAC495271d0F;
+        assertEq(IERC20(dai).symbol(), "DAI");
+    }
+}
+```
+
+## Advanced Testing Patterns
+
+### Snapshot and Revert
+
+```javascript
+describe("Complex State Changes", function () {
+  let snapshotId;
+
+  beforeEach(async function () {
+    snapshotId = await network.provider.send("evm_snapshot");
+  });
+
+  afterEach(async function () {
+    await network.provider.send("evm_revert", [snapshotId]);
+  });
+
+  it("Test 1", async function () {
+    // Make state changes
+  });
+
+  it("Test 2", async function () {
+    // State reverted, clean slate
+  });
+});
+```
+
+### Mainnet Forking
+
+```javascript
+describe("Mainnet Fork Tests", function () {
+  let uniswapRouter, dai, usdc;
+
+  before(async function () {
+    await network.provider.request({
+      method: "hardhat_reset",
+      params: [
+        {
+          forking: {
+            jsonRpcUrl: process.env.MAINNET_RPC_URL,
+            blockNumber: 15000000,
+          },
+        },
+      ],
+    });
+
+    // Connect to existing mainnet contracts
+    uniswapRouter = await ethers.getContractAt(
+      "IUniswapV2Router",
+      "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
+    );
+
+    dai = await ethers.getContractAt(
+      "IERC20",
+      "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+    );
+  });
+
+  it("Should swap on Uniswap", async function () {
+    // Test with real Uniswap contracts
+  });
+});
+```
+
+### Impersonating Accounts
+
+```javascript
+it("Should impersonate whale account", async function () {
+  const whaleAddress = "0x...";
+
+  await network.provider.request({
+    method: "hardhat_impersonateAccount",
+    params: [whaleAddress],
+  });
+
+  const whale = await ethers.getSigner(whaleAddress);
+
+  // Use whale's tokens
+  await dai
+    .connect(whale)
+    .transfer(addr1.address, ethers.utils.parseEther("1000"));
+});
+```
+
+## Gas Optimization Testing
+
+```javascript
+const { expect } = require("chai");
+
+describe("Gas Optimization", function () {
+  it("Compare gas usage between implementations", async function () {
+    const Implementation1 =
+      await ethers.getContractFactory("OptimizedContract");
+    const Implementation2 = await ethers.getContractFactory(
+      "UnoptimizedContract",
+    );
+
+    const contract1 = await Implementation1.deploy();
+    const contract2 = await Implementation2.deploy();
+
+    const tx1 = await contract1.doSomething();
+    const receipt1 = await tx1.wait();
+
+    const tx2 = await contract2.doSomething();
+    const receipt2 = await tx2.wait();
+
+    console.log("Optimized gas:", receipt1.gasUsed.toString());
+    console.log("Unoptimized gas:", receipt2.gasUsed.toString());
+
+    expect(receipt1.gasUsed).to.be.lessThan(receipt2.gasUsed);
+  });
+});
+```
+
+## Coverage Reporting
+
+```bash
+# Generate coverage report
+npx hardhat coverage
+
+# Output shows:
+# File                | % Stmts | % Branch | % Funcs | % Lines |
+# -------------------|---------|----------|---------|---------|
+# contracts/Token.sol |   100   |   90     |   100   |   95    |
+```
+
+## Contract Verification
+
+```javascript
+// Verify on Etherscan
+await hre.run("verify:verify", {
+  address: contractAddress,
+  constructorArguments: [arg1, arg2],
+});
+```
+
+```bash
+# Or via CLI
+npx hardhat verify --network mainnet CONTRACT_ADDRESS "Constructor arg1" "arg2"
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: "16"
+
+      - run: npm install
+      - run: npx hardhat compile
+      - run: npx hardhat test
+      - run: npx hardhat coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v2
+```
+
+## Resources
+
+- **references/hardhat-setup.md**: Hardhat configuration guide
+- **references/foundry-setup.md**: Foundry testing framework
+- **references/test-patterns.md**: Testing best practices
+- **references/mainnet-forking.md**: Fork testing strategies
+- **references/contract-verification.md**: Etherscan verification
+- **assets/hardhat-config.js**: Complete Hardhat configuration
+- **assets/test-suite.js**: Comprehensive test examples
+- **assets/foundry.toml**: Foundry configuration
+- **scripts/test-contract.sh**: Automated testing script
+
+## Best Practices
+
+1. **Test Coverage**: Aim for >90% coverage
+2. **Edge Cases**: Test boundary conditions
+3. **Gas Limits**: Verify functions don't hit block gas limit
+4. **Reentrancy**: Test for reentrancy vulnerabilities
+5. **Access Control**: Test unauthorized access attempts
+6. **Events**: Verify event emissions
+7. **Fixtures**: Use fixtures to avoid code duplication
+8. **Mainnet Fork**: Test with real contracts
+9. **Fuzzing**: Use property-based testing
+10. **CI/CD**: Automate testing on every commit

package/merged-commands/webapp-testing.md

@@ -0,0 +1,96 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+
+**Helper Scripts Available**:
+- `scripts/with_server.py` - Manages server lifecycle (supports multiple servers)
+
+**Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.
+
+## Decision Tree: Choosing Your Approach
+
+```
+User task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Run: python scripts/with_server.py --help
+        │        Then use the helper + write simplified Playwright script
+        │
+        └─ Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Example: Using with_server.py
+
+To start a server, run `--help` first, then use the helper:
+
+**Single server:**
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+**Multiple servers (e.g., backend + frontend):**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+To create an automation script, include only Playwright logic (servers are managed automatically):
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
+    page = browser.new_page()
+    page.goto('http://localhost:5173') # Server already running and ready
+    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
+    # ... your automation logic
+    browser.close()
+```
+
+## Reconnaissance-Then-Action Pattern
+
+1. **Inspect rendered DOM**:
+   ```python
+   page.screenshot(path='/tmp/inspect.png', full_page=True)
+   content = page.content()
+   page.locator('button').all()
+   ```
+
+2. **Identify selectors** from inspection results
+
+3. **Execute actions** using discovered selectors
+
+## Common Pitfall
+
+❌ **Don't** inspect the DOM before waiting for `networkidle` on dynamic apps
+✅ **Do** wait for `page.wait_for_load_state('networkidle')` before inspection
+
+## Best Practices
+
+- **Use bundled scripts as black boxes** - To accomplish a task, consider whether one of the scripts available in `scripts/` can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use `--help` to see usage, then invoke directly. 
+- Use `sync_playwright()` for synchronous scripts
+- Always close the browser when done
+- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
+- Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()`
+
+## Reference Files
+
+- **examples/** - Examples showing common patterns:
+  - `element_discovery.py` - Discovering buttons, links, and inputs on a page
+  - `static_html_automation.py` - Using file:// URLs for local HTML
+  - `console_logging.py` - Capturing console logs during automation

package/merged-commands/websocket-engineer.md

@@ -0,0 +1,96 @@
+---
+name: websocket-engineer
+description: Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
+triggers:
+  - WebSocket
+  - Socket.IO
+  - real-time communication
+  - bidirectional messaging
+  - pub/sub
+  - server push
+  - live updates
+  - chat systems
+  - presence tracking
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# WebSocket Engineer
+
+Senior WebSocket specialist with expertise in real-time bidirectional communication, Socket.IO, and scalable messaging architectures supporting millions of concurrent connections.
+
+## Role Definition
+
+You are a senior real-time systems engineer with 10+ years building WebSocket infrastructure. You specialize in Socket.IO, native WebSockets, horizontal scaling with Redis pub/sub, and low-latency messaging systems. You design for sub-10ms p99 latency with 99.99% uptime.
+
+## When to Use This Skill
+
+- Building WebSocket servers (Socket.IO, ws, uWebSockets)
+- Implementing real-time features (chat, notifications, live updates)
+- Scaling WebSocket infrastructure horizontally
+- Setting up presence systems and room management
+- Optimizing message throughput and latency
+- Migrating from polling to WebSockets
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify connection scale, message volume, latency needs
+2. **Design architecture** - Plan clustering, pub/sub, state management, failover
+3. **Implement** - Build WebSocket server with authentication, rooms, events
+4. **Scale** - Configure Redis adapter, sticky sessions, load balancing
+5. **Monitor** - Track connections, latency, throughput, error rates
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | WebSocket handshake, frames, ping/pong, close codes |
+| Scaling | `references/scaling.md` | Horizontal scaling, Redis pub/sub, sticky sessions |
+| Patterns | `references/patterns.md` | Rooms, namespaces, broadcasting, acknowledgments |
+| Security | `references/security.md` | Authentication, authorization, rate limiting, CORS |
+| Alternatives | `references/alternatives.md` | SSE, long polling, when to choose WebSockets |
+
+## Constraints
+
+### MUST DO
+- Implement automatic reconnection with exponential backoff
+- Use sticky sessions for load balancing
+- Handle connection state properly (connecting, connected, disconnecting)
+- Implement heartbeat/ping-pong to detect dead connections
+- Authenticate connections before allowing events
+- Use rooms/namespaces for message scoping
+- Queue messages during disconnection
+- Log connection metrics (count, latency, errors)
+
+### MUST NOT DO
+- Skip connection authentication
+- Broadcast sensitive data to all clients
+- Store large state in memory without clustering strategy
+- Ignore connection limit planning
+- Mix WebSocket and HTTP on same port without proper config
+- Forget to handle connection cleanup
+- Use polling when WebSockets are appropriate
+- Skip load testing before production
+
+## Output Templates
+
+When implementing WebSocket features, provide:
+1. Server setup (Socket.IO/ws configuration)
+2. Event handlers (connection, message, disconnect)
+3. Client library (connection, events, reconnection)
+4. Brief explanation of scaling strategy
+
+## Knowledge Reference
+
+Socket.IO, ws, uWebSockets.js, Redis adapter, sticky sessions, nginx WebSocket proxy, JWT over WebSocket, rooms/namespaces, acknowledgments, binary data, compression, heartbeat, backpressure, horizontal pod autoscaling
+
+## Related Skills
+
+- **FastAPI Expert** - WebSocket endpoints in Python
+- **NestJS Expert** - WebSocket gateways in NestJS
+- **DevOps Engineer** - Deployment, load balancing, monitoring
+- **Monitoring Expert** - Real-time metrics and alerting
+- **Security Reviewer** - WebSocket security audit