V1.0.0

.cursor/rules/helpers-checklist.mdc

@@ -0,0 +1,20 @@
+---
+description: Checklist when adding or removing std helpers
+globs: modules/std/src/helpers/*.ts
+alwaysApply: false
+---
+
+# Adding / removing a std helper
+
+When you add, remove, or rename a helper in `modules/std/src/helpers/`, you must also update the helper lists in `packages/test-utils/src/constants.ts`:
+
+- `STD_ALL_HELPERS` — every helper.
+- `STD_ADDRESS_HELPERS` — helpers whose `returnType` includes `"address"` or `"any"`.
+- `STD_NUMBER_HELPERS` — helpers whose `returnType` includes `"number"` or `"any"`.
+- `STD_BYTES32_HELPERS` — helpers whose `returnType` includes `"bytes32"` or `"any"`.
+- `STD_BOOL_HELPERS` — helpers whose `returnType` includes `"bool"` or `"any"`.
+- `STD_BYTES_HELPERS` — helpers whose `returnType` includes `"bytes"` or `"any"`.
+
+A `returnType` of `"any"` is compatible with **all** lists.
+
+After updating, run codegen (`bun packages/sdk/scripts/codegen.ts` from the module directory) and verify tests pass (`bun test modules/std/test/unit/completions.test.ts`).

.github/workflows/ci.yml

@@ -27,41 +27,41 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
       - name: Install Dependencies
         run: bun i
 
       - name: Get changed files from evmcrispr
         id: changed-files
         uses: tj-actions/changed-files@v44
         with:
-          files: "packages/evmcrispr/{src,test}/**"
+          files: |
+            packages/core/{src,test}/**
+            packages/sdk/{src,test}/**
+            packages/test-utils/**
+            modules/**
 
       - name: Build
         run: bun run build
 
       - name: Lint code
-        run: bun lint
+        run: bun run lint
+
+      - name: Check types
+        run: bun run type-check
 
-      - name: Check evmcrispr types
-        run: bun type-check
+      - name: Unit Tests
+        run: bun run test:unit
 
-      - name: Tests
+      - name: Integration Tests
         if: steps.changed-files.outputs.any_changed == 'true'
         run: |
-          echo "ARCHIVE_NODE_ENDPOINT=${{ secrets.ARCHIVE_NODE_ENDPOINT }}" >> packages/evmcrispr/.env
-          echo "VITE_PINATA_JWT=${{ secrets.VITE_PINATA_JWT }}" >> packages/evmcrispr/.env
-          echo "ETHERSCAN_API=${{ secrets.ETHERSCAN_API }}" >> packages/evmcrispr/.env
-          bun test:coverage
+          echo "VITE_DRPC_API_KEY=$VITE_DRPC_API_KEY" >> .env
+          echo "VITE_PINATA_JWT=$VITE_PINATA_JWT" >> .env
+          bun run test:integration
         env:
-          ARCHIVE_NODE_ENDPOINT: ${{ secrets.ARCHIVE_NODE_ENDPOINT }}
+          VITE_DRPC_API_KEY: ${{ secrets.VITE_DRPC_API_KEY }}
           VITE_PINATA_JWT: ${{ secrets.VITE_PINATA_JWT }}
-          ETHERSCAN_API: ${{ secrets.ETHERSCAN_API }}
-
-      - name: Coveralls
-        uses: coverallsapp/github-action@master
-        if: steps.changed-files.outputs.any_changed == 'true'
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          flag-name: ${{matrix.os}}-node-${{ matrix.node-version }}
-          base-path: "packages/evmcrispr"
-          path-to-lcov: "packages/evmcrispr/coverage/lcov.info"

.github/workflows/release.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [master]
     paths:
-      - "packages/evmcrispr/**"
+      - "packages/core/**"
 
 jobs:
   release:

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 node_modules
+.astro
 .turbo
 *.log
 dist
@@ -12,3 +13,11 @@ public/dist
 .nyc_output
 cache
 coverage
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+_generated.ts
+
+# Auto-generated docs
+apps/evmcrispr-website/src/content/docs/reference/
+apps/evmcrispr-website/public/llms-full.txt

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "evmcrispr": {
+      "type": "stdio",
+      "command": "bash",
+      "args": [
+        "-c",
+        "source .env && TRANSPORT=stdio bun apps/evmcrispr-mcp/src/index.ts"
+      ]
+    }
+  }
+}

.npmrc

@@ -1 +1 @@
-strict-peer-dependencies=false
+legacy-peer-deps=true

.vscode/launch.json

@@ -8,7 +8,7 @@
       "skipFiles": ["<node_internals>/**"],
       "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/hardhat",
       "args": ["test"],
-      "cwd": "${workspaceFolder}/packages/evmcrispr/"
+      "cwd": "${workspaceFolder}/packages/core/"
     }
   ]
 }

.vscode/settings.json

@@ -1,12 +1,10 @@
 {
   "editor.formatOnSave": true,
+  "editor.defaultFormatter": "biomejs.biome",
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "always"
+    "source.fixAll.biome": "always",
+    "source.organizeImports.biome": "always"
   },
-  "eslint.options": {
-    "extensions": [".js", ".ts", ".tsx"]
-  },
-  "eslint.validate": ["javascript", "typescript", "typescriptreact"],
   "solidity.packageDefaultDependenciesContractsDirectory": "",
   "solidity.packageDefaultDependenciesDirectory": "packages/hardhat/node_modules",
   "solidity.enabledAsYouTypeCompilationErrorCheck": true,

AGENTS.md

@@ -0,0 +1,88 @@
+# EVMcrispr
+
+## What This Project Is
+
+A TypeScript monorepo for a DSL that encodes and executes batched EVM
+transactions. Targets DAOs (especially Aragon), DeFi protocols, and
+general smart contract interaction. Scripts run in a web terminal
+(evmcrispr.com) or programmatically via `@evmcrispr/core`.
+
+## Architecture
+
+- `packages/core`: Parser, interpreter, AST, completions, hover docs
+- `packages/sdk`: Module SDK (`defineCommand`, `defineHelper`, `defineModule`)
+- `modules/std`: Default module (13 commands, 55 helpers) — always loaded
+- `modules/aragonos`: Aragon DAO operations (9 commands, 3 helpers)
+- `modules/sim`: Chain fork simulation — anvil, hardhat, tenderly, ethereumjs (6 commands)
+- `modules/ens`: ENS domain operations (1 command, 1 helper)
+- `modules/giveth`: Giveth protocol (4 commands, 1 helper)
+- `modules/http`: HTTP + JSON helpers (3 helpers)
+- `apps/evmcrispr-terminal`: React + Monaco + Wagmi terminal app
+- `apps/evmcrispr-website`: Astro landing page + docs
+
+## Key Patterns
+
+- Commands: `modules/<mod>/src/commands/<name>.ts` using `defineCommand`
+- Helpers: `modules/<mod>/src/helpers/<name>.ts` using `defineHelper`
+- `_generated.ts` files are auto-generated by codegen — never edit directly
+- Codegen script: `packages/sdk/scripts/codegen.ts`
+- ArgDef types: `address`, `number`, `string`, `bytes`, `bytes32`, `bool`,
+  `array`, `any`, `write-abi`, `read-abi`, `token-symbol`, `block`,
+  `variable`, `helper`, `command`, `expression`, `dao`, `json-path`
+- Commands return `Action[]` (transaction descriptors). Helpers return values.
+- The DSL is modular: `std` is loaded by default, others via `load <module>`
+
+## Common Tasks
+
+- **Add a command**: create `modules/<mod>/src/commands/<name>.ts`, run build
+- **Add a helper**: create `modules/<mod>/src/helpers/<name>.ts`, run build
+- **Regenerate codegen**: `bun packages/sdk/scripts/codegen.ts` (from module dir)
+- **Regenerate docs**: `bun run scripts/generate-docs.ts`
+- **Run tests**: `bun test:unit` / `bun test:integration` (needs anvil)
+- **Dev terminal**: `bun dev:terminal`
+- **Dev website**: `bun dev:website`
+- **Lint**: `biome check .`
+- **Build all**: `bun run build` (uses turbo)
+
+## DSL Quick Reference
+
+```
+# Variables
+set $x 42
+
+# Execute a contract call
+exec 0xAbC... "transfer(address,uint256)" @me 100e18
+
+# Read from a contract
+@get(0xAbC... "balanceOf(address)(uint256)" @me)
+
+# Load modules
+load aragonos
+load sim
+
+# Batch into single tx
+batch (
+  exec ...
+  exec ...
+)
+
+# Aragon DAO operations
+aragonos:connect <dao> (
+  grant <entity> <app> <role>
+  install <app> <params...>
+)
+
+# Simulate on a fork
+sim:fork 1 (
+  sim:set-balance @me 100e18
+  exec ...
+  sim:expect ...
+)
+```
+
+## Documentation
+
+- Reference docs: `apps/evmcrispr-website/src/content/docs/reference/<module>/commands/<name>.md`
+- Guides: `apps/evmcrispr-website/src/content/docs/guides/`
+- Doc generation: `scripts/generate-docs.ts` reads `_generated.ts` metadata
+- `llms.txt` and `llms-full.txt` at repo root for LLM consumption

README.md

@@ -1,33 +1,86 @@
 # EVMcrispr
 
-This is an official starter Turborepo.
+A domain-specific language for encoding and executing batched EVM transactions targeting smart contracts, Aragon DAOs, ENS, and DeFi protocols.
 
-## Using this example
+## Quick Start
 
-Run the following command:
+```
+# Install dependencies
+bun install
 
-```sh
-npx create-turbo@latest -e with-vite
+# Start the web terminal
+bun dev:terminal
+
+# Start the docs website
+bun dev:website
 ```
 
-## What's inside?
+Visit [evmcrispr.com](https://evmcrispr.com) to use the hosted terminal.
 
-This Turborepo includes the following packages and apps:
+## Example Script
+
+```
+# Approve and swap tokens in a single transaction
+load sim
+
+sim:fork (
+  set $router 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D
+  set $amount @token.amount(DAI 100)
+
+  batch (
+    exec @token(DAI) "approve(address,uint256)" $router $amount
+    exec $router "swapExactTokensForETH(uint256,uint256,address[],address,uint256)" $amount 0 [@token(DAI) @token(WETH)] @me @date("2025-12-31")
+  )
+
+  sim:expect @bool(@get(@token(WETH) "balanceOf(address)(uint256)" @me) > 0)
+)
+```
 
-### Apps and Packages
+## Modules
 
-- `docs`: a vanilla [vite](https://vitejs.dev) ts app
-- `web`: another vanilla [vite](https://vitejs.dev) ts app
-- `@repo/ui`: a stub component & utility library shared by both `web` and `docs` applications
-- `@repo/eslint-config`: shared `eslint` configurations
-- `@repo/typescript-config`: `tsconfig.json`s used throughout the monorepo
+| Module | Description | Commands | Helpers |
+|--------|-------------|----------|---------|
+| [std](modules/std/README.md) | Core language (always loaded) | 13 | 55 |
+| [aragonos](modules/aragonos/README.md) | Aragon DAO operations | 9 | 3 |
+| [sim](modules/sim/README.md) | Chain fork simulation | 6 | - |
+| [ens](modules/ens/README.md) | ENS domain operations | 1 | 1 |
+| [giveth](modules/giveth/README.md) | Giveth protocol | 4 | 1 |
+| [http](modules/http/README.md) | HTTP + JSON | - | 3 |
+
+## Project Structure
+
+```
+packages/
+  core/          Parser, interpreter, AST
+  sdk/           Module SDK (defineCommand, defineHelper)
+modules/
+  std/           Default module — always loaded
+  aragonos/      Aragon DAO operations
+  sim/           Chain fork simulation
+  ens/           ENS domain operations
+  giveth/        Giveth protocol
+  http/          HTTP + JSON helpers
+apps/
+  evmcrispr-terminal/   React + Monaco web terminal
+  evmcrispr-website/    Astro landing page + docs
+```
+
+## Development
+
+```sh
+bun install           # Install dependencies
+bun run build         # Build all packages
+bun test:unit         # Run unit tests
+bun test:integration  # Run integration tests (needs anvil)
+biome check .         # Lint
+```
 
-Each package and app is 100% [TypeScript](https://www.typescriptlang.org/).
+## Documentation
 
-### Utilities
+- [Getting Started](apps/evmcrispr-website/src/content/docs/guides/getting-started.md)
+- [Language Basics](apps/evmcrispr-website/src/content/docs/guides/language-basics.md)
+- [Full Reference](https://evmcrispr.com/llms-full.txt)
 
-This Turborepo has some additional tools already setup for you:
+## License
 
-- [TypeScript](https://www.typescriptlang.org/) for static type checking
-- [ESLint](https://eslint.org/) for code linting
-- [Prettier](https://prettier.io) for code formatting
+[GPL-3.0](LICENSE)

apps/evmcrispr-mcp/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "evmcrispr-mcp",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "evmcrispr": "*",
+    "@evmcrispr/core": "*",
+    "@evmcrispr/module-aragonos": "*",
+    "@evmcrispr/module-ens": "*",
+    "@evmcrispr/module-giveth": "*",
+    "@evmcrispr/module-http": "*",
+    "@evmcrispr/module-sim": "*",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@types/node": "^22.15.21"
+  },
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "evmcrispr-build src/index.ts",
+    "start": "bun src/index.ts",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check src"
+  }
+}