movementkit-cli 1.0.1 → 1.0.4

package/kits/engineer/.claude/agents/tester.md

@@ -0,0 +1,174 @@
+---
+name: tester
+description: >-
+  Use this agent when you need to validate code quality through testing for Movement dApps.
+  This includes Move contract unit tests, React component tests, integration tests, and
+  end-to-end testing.
+  Examples:
+  - <example>
+      Context: User has implemented a new Move contract
+      user: "I've finished the staking contract, can you test it?"
+      assistant: "Let me use the tester agent to create comprehensive Move tests"
+      <commentary>
+      Move contract testing requires #[test] functions and proper resource handling.
+      </commentary>
+    </example>
+  - <example>
+      Context: User wants to test frontend wallet interaction
+      user: "Test the wallet connection flow"
+      assistant: "I'll use the tester agent to run React component tests"
+      <commentary>
+      Frontend testing requires mocking wallet adapters and contract calls.
+      </commentary>
+    </example>
+  - <example>
+      Context: User needs full coverage report
+      user: "What's our current test coverage?"
+      assistant: "Let me use the tester agent to analyze coverage across all layers"
+      <commentary>
+      Coverage analysis spans Move contracts and React components.
+      </commentary>
+    </example>
+model: sonnet
+---
+
+You are a senior QA engineer specializing in Movement blockchain dApp testing. Your expertise spans Move contract testing, React component testing, and E2E testing for Web3 applications.
+
+**IMPORTANT**: Target >90% code coverage across all layers.
+**IMPORTANT**: Ensure token efficiency while maintaining high quality.
+
+## Core Competencies
+
+1. **Move Contract Testing**
+   - Unit tests with #[test] attributes
+   - Test expected failures with #[expected_failure]
+   - Resource state verification
+   - Event emission validation
+   - Edge cases and boundary conditions
+
+2. **Frontend Testing**
+   - React component tests with Testing Library
+   - Hook testing with renderHook
+   - Wallet adapter mocking
+   - User interaction simulation
+   - Snapshot testing for UI
+
+3. **E2E Testing**
+   - Full flow testing from UI to blockchain
+   - Wallet interaction testing
+   - Transaction lifecycle verification
+
+## Testing Workflow
+
+1. **Test Planning**
+   - Identify critical paths and edge cases
+   - Plan test data and fixtures
+   - Determine mocking strategy
+
+2. **Test Execution**
+   - Run all test suites
+   - Analyze failures thoroughly
+   - Verify coverage requirements
+
+3. **Reporting**
+   - Document test results
+   - Highlight gaps and risks
+   - Recommend improvements
+
+## Move Contract Tests
+
+```move
+#[test_only]
+module test_addr::token_tests {
+    use std::signer;
+    use my_addr::token;
+
+    #[test(admin = @my_addr)]
+    public fun test_initialize(admin: &signer) {
+        token::initialize(admin);
+        assert!(token::get_total_supply() == 0, 1);
+    }
+
+    #[test(admin = @my_addr, user = @0x123)]
+    public fun test_mint(admin: &signer, user: &signer) {
+        token::initialize(admin);
+        token::mint(admin, signer::address_of(user), 1000);
+        assert!(token::balance(signer::address_of(user)) == 1000, 2);
+    }
+
+    #[test(user = @0x123)]
+    #[expected_failure(abort_code = token::E_NOT_AUTHORIZED)]
+    public fun test_mint_unauthorized(user: &signer) {
+        token::mint(user, @0x456, 1000);
+    }
+}
+```
+
+## React Component Tests
+
+```tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { BalanceDisplay } from '../src/components/BalanceDisplay';
+
+const mockUseWallet = vi.fn();
+vi.mock('@aptos-labs/wallet-adapter-react', () => ({
+  useWallet: () => mockUseWallet(),
+}));
+
+describe('BalanceDisplay', () => {
+  it('renders balance when connected', async () => {
+    mockUseWallet.mockReturnValue({
+      connected: true,
+      account: { address: '0x1234' },
+    });
+    
+    render(<BalanceDisplay />);
+    await waitFor(() => {
+      expect(screen.getByText(/balance/i)).toBeInTheDocument();
+    });
+  });
+
+  it('shows connect prompt when disconnected', () => {
+    mockUseWallet.mockReturnValue({ connected: false });
+    render(<BalanceDisplay />);
+    expect(screen.getByText(/connect wallet/i)).toBeInTheDocument();
+  });
+});
+```
+
+## Test Commands
+
+```bash
+# Move contract tests
+movement move test
+movement move test --coverage
+
+# Frontend tests
+cd frontend
+npm test
+npm run test:coverage
+
+# E2E tests (if configured)
+npm run test:e2e
+```
+
+## Coverage Requirements
+
+| Layer | Minimum Coverage |
+|-------|-----------------|
+| Move Contracts | 90% |
+| React Components | 85% |
+| Critical Paths | 100% |
+
+## Test Report Format
+
+- **Test Results**: Passed/Failed/Skipped counts
+- **Coverage**: Line, branch, function percentages per layer
+- **Failed Tests**: Detailed error messages and stack traces
+- **Critical Issues**: Blocking issues requiring attention
+- **Recommendations**: Actionable improvements
+
+**IMPORTANT:** Use file system to save reports in `./plans/<plan-name>/reports` directory.
+**IMPORTANT:** Sacrifice grammar for concision in reports.
+

package/kits/engineer/.claude/commands/cook/contracts.md

@@ -0,0 +1,174 @@
+# /cook:contracts - Move Smart Contract Generation
+
+Generate Move smart contracts for the Movement blockchain.
+
+## Prerequisites
+
+### Install Movement CLI
+
+Before generating contracts, ensure the Movement CLI is installed. See [Movement CLI docs](https://docs.movementnetwork.xyz/devs/movementcli) for details.
+
+#### Quick Install (Testnet - with Move 2 support)
+
+**macOS (Apple Silicon/M-series):**
+```bash
+curl -LO https://github.com/movementlabsxyz/homebrew-movement-cli/releases/download/bypass-homebrew/movement-move2-testnet-macos-arm64.tar.gz && mkdir -p temp_extract && tar -xzf movement-move2-testnet-macos-arm64.tar.gz -C temp_extract && chmod +x temp_extract/movement && sudo mv temp_extract/movement /usr/local/bin/movement && rm -rf temp_extract movement-move2-testnet-macos-arm64.tar.gz
+```
+
+**macOS (Intel):**
+```bash
+curl -LO https://github.com/movementlabsxyz/homebrew-movement-cli/releases/download/bypass-homebrew/movement-move2-testnet-macos-x86_64.tar.gz && mkdir -p temp_extract && tar -xzf movement-move2-testnet-macos-x86_64.tar.gz -C temp_extract && chmod +x temp_extract/movement && sudo mv temp_extract/movement /usr/local/bin/movement && rm -rf temp_extract movement-move2-testnet-macos-x86_64.tar.gz
+```
+
+**Linux (x86_64):**
+```bash
+curl -LO https://github.com/movementlabsxyz/homebrew-movement-cli/releases/download/bypass-homebrew/movement-move2-testnet-linux-x86_64.tar.gz && mkdir -p temp_extract && tar -xzf movement-move2-testnet-linux-x86_64.tar.gz -C temp_extract && chmod +x temp_extract/movement && sudo mv temp_extract/movement /usr/local/bin/movement && rm -rf temp_extract movement-move2-testnet-linux-x86_64.tar.gz
+```
+
+**Verify installation:**
+```bash
+movement --version
+```
+
+### Initialize Account (if not done)
+```bash
+movement init --network testnet
+```
+
+This creates a `.movement/config.yaml` with your account credentials.
+
+### Get Testnet Tokens
+Visit https://faucet.movementnetwork.xyz/ to get testnet MOVE tokens for deployment.
+
+## Workflow
+
+### Step 1: Read Move Language Reference
+**CRITICAL:** Always read the Move language reference first:
+```bash
+cat docs/MOVE_LANGUAGE_REFERENCE.md
+```
+
+### Step 2: Analyze Requirements
+From the plan or user request, identify:
+- Module structure
+- Resource definitions
+- Entry functions
+- View functions
+- Events
+- Error codes
+
+### Step 3: Generate Move.toml
+```toml
+[package]
+name = "{project_name}"
+version = "1.0.0"
+authors = []
+
+[addresses]
+module_addr = "_"
+
+[dependencies]
+AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-framework", rev = "mainnet" }
+AptosStdlib = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-stdlib", rev = "mainnet" }
+MoveStdlib = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/move-stdlib", rev = "mainnet" }
+```
+
+### Step 4: Generate Move Modules
+Create modules in `contracts/sources/`:
+
+```move
+module module_addr::module_name {
+    use std::signer;
+    use std::string::String;
+    use aptos_framework::event;
+    use aptos_framework::account;
+
+    // Error codes
+    const E_NOT_AUTHORIZED: u64 = 1;
+    const E_ALREADY_EXISTS: u64 = 2;
+
+    // Resources
+    struct ResourceName has key, store {
+        field1: u64,
+        field2: String,
+    }
+
+    // Events
+    #[event]
+    struct EventName has drop, store {
+        field1: u64,
+        timestamp: u64,
+    }
+
+    // Entry functions
+    public entry fun function_name(
+        account: &signer,
+        param1: u64,
+    ) acquires ResourceName {
+        let addr = signer::address_of(account);
+        // Implementation
+        event::emit(EventName { field1: param1, timestamp: 0 });
+    }
+
+    // View functions
+    #[view]
+    public fun get_value(addr: address): u64 acquires ResourceName {
+        borrow_global<ResourceName>(addr).field1
+    }
+}
+```
+
+### Step 5: Generate Unit Tests
+Create tests in `contracts/tests/`:
+
+```move
+#[test_only]
+module module_addr::module_name_tests {
+    use std::signer;
+    use module_addr::module_name;
+
+    #[test(account = @0x1)]
+    fun test_function_name(account: &signer) {
+        // Test implementation
+    }
+
+    #[test]
+    #[expected_failure(abort_code = module_name::E_NOT_AUTHORIZED)]
+    fun test_unauthorized_access() {
+        // Test error case
+    }
+}
+```
+
+### Step 6: Compile and Test
+```bash
+cd contracts
+movement move compile
+movement move test
+```
+
+## Best Practices
+
+1. **Resource Safety**: Always use proper resource management
+2. **Access Control**: Validate signers on privileged functions
+3. **Events**: Emit events for all state changes
+4. **Error Codes**: Use descriptive error constants
+5. **Documentation**: Add inline comments for complex logic
+
+## Output Summary
+```markdown
+# 📜 Contracts Generated
+
+## Modules
+| Module | Functions | Events | Tests |
+|--------|-----------|--------|-------|
+| module_name | 5 | 3 | 10 |
+
+## Compilation: ✅ Success
+## Tests: ✅ 10/10 passed
+
+## Next Steps
+- Run `/cook:frontend` to generate frontend
+- Run `/test:contracts` for comprehensive testing
+```
+

package/kits/engineer/.claude/commands/cook/frontend.md

@@ -0,0 +1,325 @@
+# /cook:frontend - React Frontend Generation
+
+Generate React frontend with wallet integration for Movement blockchain.
+
+## References
+- [TypeScript SDK](https://docs.movementnetwork.xyz/devs/interactonchain/tsSdk)
+- [Wallet Adapter](https://docs.movementnetwork.xyz/devs/interactonchain/wallet-adapter/connect_wallet)
+- [useWallet Hook](https://docs.movementnetwork.xyz/devs/interactonchain/wallet-adapter/useWallet/ConnectWallet)
+- [Sign & Submit](https://docs.movementnetwork.xyz/devs/interactonchain/wallet-adapter/useWallet/signAndSubmitTx)
+
+## Movement Network Configuration
+
+**Chain IDs:**
+- Mainnet: `126`
+- Testnet: `250`
+
+**RPC Endpoints:**
+- Mainnet: `https://mainnet.movementnetwork.xyz/v1`
+- Testnet: `https://full.testnet.movementinfra.xyz/v1`
+
+**Explorer:**
+- `https://explorer.movementnetwork.xyz/txn/{txHash}?network={mainnet|testnet}`
+
+## Workflow
+
+### Step 1: Analyze Requirements
+From the plan or contracts, identify:
+- UI components needed
+- User interactions
+- Contract functions to call (entry functions vs view functions)
+- Data display needs
+
+### Step 2: Generate package.json
+```json
+{
+  "name": "{project_name}-frontend",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@aptos-labs/ts-sdk": "^1.33.1",
+    "@aptos-labs/wallet-adapter-react": "^3.7.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}
+```
+
+### Step 3: Generate Environment Configuration
+`frontend/.env`:
+```bash
+VITE_MODULE_ADDRESS=<YOUR_CONTRACT_ADDRESS>
+VITE_NETWORK=testnet
+VITE_NODE_URL=https://full.testnet.movementinfra.xyz/v1
+```
+
+### Step 4: Generate Wallet Provider
+`frontend/src/contexts/WalletProvider.tsx`:
+```tsx
+import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
+import { AptosConfig, Network } from "@aptos-labs/ts-sdk";
+import { PropsWithChildren } from "react";
+
+export function WalletProvider({ children }: PropsWithChildren) {
+  // Movement Network configuration
+  const config = new AptosConfig({
+    network: Network.CUSTOM,
+    fullnode: import.meta.env.VITE_NODE_URL || 'https://full.testnet.movementinfra.xyz/v1',
+  });
+
+  return (
+    <AptosWalletAdapterProvider
+      plugins={[]}
+      autoConnect={true}
+      dappConfig={config}
+      onError={(error) => {
+        console.error("Wallet error:", error);
+      }}
+    >
+      {children}
+    </AptosWalletAdapterProvider>
+  );
+}
+```
+
+### Step 5: Generate Custom Hooks
+`frontend/src/hooks/useContract.ts`:
+```tsx
+import { useWallet } from "@aptos-labs/wallet-adapter-react";
+import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+
+const MODULE_ADDRESS = import.meta.env.VITE_MODULE_ADDRESS;
+const MODULE_NAME = "{module_name}";
+
+// Create Aptos client for Movement Network
+const aptosConfig = new AptosConfig({
+  network: Network.CUSTOM,
+  fullnode: import.meta.env.VITE_NODE_URL || "https://full.testnet.movementinfra.xyz/v1",
+});
+const aptos = new Aptos(aptosConfig);
+
+export function useContract() {
+  const { signAndSubmitTransaction, account, connected } = useWallet();
+
+  // Call entry function (modifies state, requires signing)
+  const callFunction = async (functionName: string, args: any[]) => {
+    if (!connected || !account) throw new Error("Wallet not connected");
+
+    const response = await signAndSubmitTransaction({
+      data: {
+        function: `${MODULE_ADDRESS}::${MODULE_NAME}::${functionName}`,
+        functionArguments: args,
+      },
+    });
+
+    // Wait for transaction confirmation
+    const result = await aptos.waitForTransaction({
+      transactionHash: response.hash
+    });
+
+    return result;
+  };
+
+  // Call view function (read-only, no signing required)
+  const viewFunction = async (functionName: string, args: any[]) => {
+    return await aptos.view({
+      payload: {
+        function: `${MODULE_ADDRESS}::${MODULE_NAME}::${functionName}`,
+        functionArguments: args,
+      },
+    });
+  };
+
+  return { callFunction, viewFunction, account, connected, aptos };
+}
+```
+
+### Step 6: Generate Wallet Connect Component
+`frontend/src/components/WalletConnect.tsx`:
+```tsx
+import { useWallet } from "@aptos-labs/wallet-adapter-react";
+
+export function WalletConnect() {
+  const {
+    connect,
+    disconnect,
+    account,
+    connected,
+    wallets,
+    isLoading
+  } = useWallet();
+
+  if (isLoading) {
+    return <button disabled>Loading...</button>;
+  }
+
+  if (connected && account) {
+    return (
+      <div className="wallet-connected">
+        <span className="address">
+          {account.address.slice(0, 6)}...{account.address.slice(-4)}
+        </span>
+        <button onClick={disconnect}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="wallet-select">
+      {wallets?.filter(w => w.readyState === 'Installed').map((wallet) => (
+        <button
+          key={wallet.name}
+          onClick={() => connect(wallet.name)}
+        >
+          Connect {wallet.name}
+        </button>
+      ))}
+      {wallets?.filter(w => w.readyState === 'Installed').length === 0 && (
+        <p>No wallets detected. Please install a Movement-compatible wallet.</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Step 7: Generate Main App
+`frontend/src/App.tsx`:
+```tsx
+import { WalletProvider } from "./contexts/WalletProvider";
+import { WalletConnect } from "./components/WalletConnect";
+
+export default function App() {
+  return (
+    <WalletProvider>
+      <div className="app">
+        <header>
+          <h1>{Project Name}</h1>
+          <WalletConnect />
+        </header>
+        <main>
+          {/* Main content - add your components here */}
+        </main>
+      </div>
+    </WalletProvider>
+  );
+}
+```
+
+### Step 8: Generate Vite Config
+`frontend/vite.config.ts`:
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  define: {
+    'process.env': {},
+  },
+});
+```
+
+### Step 9: Generate TypeScript Config
+`frontend/tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
+```
+
+## Common Patterns
+
+### Reading Contract State
+```tsx
+const { viewFunction } = useContract();
+
+// Read a value from contract
+const fetchData = async () => {
+  const [result] = await viewFunction("get_value", []);
+  setValue(Number(result));
+};
+```
+
+### Writing to Contract
+```tsx
+const { callFunction, connected } = useContract();
+
+const handleSubmit = async () => {
+  if (!connected) return;
+
+  try {
+    const result = await callFunction("set_value", [newValue]);
+    console.log("Transaction successful:", result.hash);
+  } catch (error) {
+    console.error("Transaction failed:", error);
+  }
+};
+```
+
+### Transaction Status
+```tsx
+const [txStatus, setTxStatus] = useState<'idle' | 'pending' | 'success' | 'error'>('idle');
+
+const handleTransaction = async () => {
+  setTxStatus('pending');
+  try {
+    await callFunction("some_function", []);
+    setTxStatus('success');
+  } catch {
+    setTxStatus('error');
+  }
+};
+```
+
+## Output Summary
+```markdown
+# 🎨 Frontend Generated
+
+## Files Created
+- src/App.tsx
+- src/contexts/WalletProvider.tsx
+- src/hooks/useContract.ts
+- src/components/WalletConnect.tsx
+- src/components/{additional components}
+- vite.config.ts
+- tsconfig.json
+- .env
+
+## Next Steps
+1. Run `npm install` to install dependencies
+2. Update `.env` with your contract address
+3. Run `npm run dev` to start development server
+4. Install a Movement-compatible wallet (Razor, Nightly, etc.)
+5. Connect wallet and test interactions
+```