@alumbwe/anvil 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# @anvil/cli
+
+A Terminal User Interface (TUI) package built with OpenTUI and React.
+
+## Installation
+
+```bash
+bun install
+```
+
+## Development
+
+Run the TUI in development mode:
+
+```bash
+bun run dev
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+bun test
+```
+
+### Interactive E2E Testing
+
+For testing interactive CLI features, install tmux:
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+
+# Windows (via WSL)
+wsl --install
+sudo apt-get install tmux
+```
+
+Then run the proof-of-concept:
+
+```bash
+bun run test:tmux-poc
+```
+
+**Note:** When sending input to the CLI via tmux, you must use bracketed paste mode. Standard `send-keys` drops characters.
+
+```bash
+# ❌ Broken: tmux send-keys -t session "hello"
+# ✅ Works:  tmux send-keys -t session $'\e[200~hello\e[201~'
+```
+
+See [tmux.knowledge.md](tmux.knowledge.md) for comprehensive tmux documentation and [src/__tests__/README.md](src/__tests__/README.md) for testing documentation.
+
+## Build
+
+Build the package:
+
+```bash
+bun run build
+```
+
+## Run
+
+Run the built TUI:
+
+```bash
+bun run start
+```
+
+Or use the binary directly:
+
+```bash
+anvil-tui
+```
+
+## Features
+
+- Built with OpenTUI for modern terminal interfaces
+- Uses React for declarative component-based UI
+- TypeScript support out of the box

package/bin/anvil

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/entry.ts'

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@alumbwe/anvil",
+  "version": "1.0.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "anvil": "./bin/anvil"
+  },
+  "files": [
+    "bin/anvil",
+    "bin/tree-sitter.wasm",
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anvil-AI/anvil.git",
+    "directory": "cli"
+  },
+  "homepage": "https://anvil.dev",
+  "bugs": {
+    "url": "https://github.com/Anvil-AI/anvil/issues"
+  },
+  "keywords": [
+    "anvil",
+    "ai",
+    "code-editing",
+    "assistant",
+    "cli",
+    "coding-agent"
+  ],
+  "scripts": {
+    "dev": "bun --env-file=../.env.local run src/entry.ts --cwd ..",
+    "build:binary": "bun ./scripts/build-binary.ts anvil $npm_package_version",
+    "typecheck": "tsc --noEmit -p ."
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@gravity-ai/api": "^0.1.2",
+    "@opentui/core": "0.3.4",
+    "@opentui/react": "0.3.4",
+    "@tanstack/react-query": "^5.90.12",
+    "commander": "^14.0.1",
+    "immer": "^10.1.3",
+    "jimp": "^1.6.0",
+    "node-machine-id": "^1.1.12",
+    "open": "^10.1.0",
+    "pino": "9.4.0",
+    "posthog-node": "^5.8.0",
+    "react": "^19.0.0",
+    "react-reconciler": "^0.32.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "string-width": "^7.2.0",
+    "systeminformation": "^5.30.7",
+    "terminal-image": "^4.1.0",
+    "thinking-orbs": "^0.3.1",
+    "ts-pattern": "^5.9.0",
+    "unified": "^11.0.0",
+    "wsl-utils": "^0.1.0",
+    "yoga-layout": "^3.2.1",
+    "zod": "^4.2.1",
+    "zustand": "^5.0.8"
+  }
+}

package/src/__tests__/README.md

@@ -0,0 +1,256 @@
+# CLI Testing
+
+Comprehensive testing suite for the Anvil CLI using tmux for interactive terminal emulation.
+
+## Test Naming Convention
+
+**IMPORTANT:** Follow these patterns for automatic tmux detection:
+
+- **Unit tests:** `*.test.ts` (e.g., `cli-args.test.ts`)
+- **E2E tests:** `e2e-*.test.ts` (e.g., `e2e-cli.test.ts`)
+- **Integration tests:** `integration-*.test.ts` (e.g., `integration-tmux.test.ts`)
+
+Files matching `*integration*.test.ts` or `*e2e*.test.ts` trigger automatic tmux availability checking in `.bin/bun`.
+
+## Quick Start
+
+```bash
+cd cli
+bun test
+```
+
+## Prerequisites
+
+### For Integration Tests
+
+Install tmux for interactive CLI testing:
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+
+# Windows (via WSL)
+wsl --install
+sudo apt-get install tmux
+```
+
+### For E2E Tests
+
+Build the SDK first:
+
+```bash
+cd sdk
+bun run build
+cd ../cli
+```
+
+## Running Tests
+
+### All Tests
+
+```bash
+bun test
+```
+
+### Specific Test Suites
+
+```bash
+# Unit tests
+bun test cli-args.test.ts
+
+# E2E tests (requires SDK)
+bun test e2e-cli.test.ts
+
+# Integration tests (requires tmux)
+bun test integration-tmux.test.ts
+```
+
+### Manual tmux POC
+
+```bash
+bun run test:tmux-poc
+```
+
+## Automatic tmux Detection
+
+The `.bin/bun` wrapper automatically checks for tmux when running integration/E2E tests:
+
+- **Detects** test files matching `*integration*.test.ts` or `*e2e*.test.ts`
+- **Checks** if tmux is installed
+- **Shows** installation instructions if missing
+- **Skips** tests gracefully if tmux unavailable
+
+**Benefits:**
+
+- ✅ Project-wide (works in any package)
+- ✅ No hardcoded paths
+- ✅ Clear test categorization
+- ✅ Automatic dependency validation
+
+## Test Structure
+
+### Unit Tests
+
+Test individual functions in isolation:
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+
+describe('CLI Arguments', () => {
+  test('parses --agent flag', () => {
+    // Test implementation
+  })
+})
+```
+
+### Integration Tests (tmux)
+
+Test interactive CLI with full terminal emulation:
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+import { isTmuxAvailable } from './test-utils'
+
+const tmuxAvailable = isTmuxAvailable()
+
+describe.skipIf(!tmuxAvailable)('CLI Integration Tests', () => {
+  test('handles user input', async () => {
+    // Create tmux session
+    // Send commands
+    // Verify output
+  })
+})
+```
+
+### E2E Tests
+
+Test complete CLI workflows:
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+import { isSDKBuilt } from './test-utils'
+
+const sdkBuilt = isSDKBuilt()
+
+describe.skipIf(!sdkBuilt)('CLI E2E Tests', () => {
+  test('runs --help command', async () => {
+    // Test CLI behavior
+  })
+})
+```
+
+## Test Utilities
+
+Shared utilities in `test-utils.ts`:
+
+```typescript
+import { isTmuxAvailable, isSDKBuilt, sleep } from './test-utils'
+
+// Check for tmux
+if (isTmuxAvailable()) {
+  // Run tmux tests
+}
+
+// Check for SDK
+if (isSDKBuilt()) {
+  // Run E2E tests
+}
+
+// Async delay
+await sleep(1000)
+```
+
+## tmux Testing
+
+**See [`../../tmux.knowledge.md`](../../tmux.knowledge.md) for comprehensive tmux documentation**, including:
+
+- Why standard `send-keys` doesn't work (must use bracketed paste mode)
+- Helper functions for Bash and TypeScript
+- Complete example scripts
+- Debugging and troubleshooting tips
+
+**Quick reference:**
+
+```typescript
+// ❌ Broken:
+await tmux(['send-keys', '-t', session, 'hello'])
+
+// ✅ Works:
+await tmux(['send-keys', '-t', session, '-l', '\x1b[200~hello\x1b[201~'])
+```
+
+## Debugging Tests
+
+### View Test Output
+
+```bash
+# Verbose test output
+bun test --verbose
+
+# Watch mode
+bun test --watch
+```
+
+## Contributing
+
+When adding new tests:
+
+1. **Follow naming convention** (`*integration*.test.ts` or `*e2e*.test.ts`)
+2. **Use test-utils.ts** for shared functionality
+3. **Add graceful skipping** for missing dependencies
+4. **Clean up resources** (tmux sessions, temp files)
+5. **Document test purpose** clearly in test descriptions
+
+## Troubleshooting
+
+### tmux Not Found
+
+```
+⚠️  tmux not found but required for integration/E2E tests
+```
+
+**Solution:** Install tmux (see Prerequisites above)
+
+### SDK Not Built
+
+```
+✓ Build SDK for E2E tests: cd sdk && bun run build [skip]
+```
+
+**Solution:** Build the SDK first (see Prerequisites above)
+
+### Tests Hanging
+
+- Check tmux session isn't waiting for input
+- Ensure proper cleanup in `finally` blocks
+- Use timeouts for tmux operations
+
+### Session Already Exists
+
+- Use unique session names (e.g., timestamp suffix)
+- Clean up sessions in `beforeEach`/`afterEach`
+
+## Performance
+
+- **Unit tests:** ~100ms total
+- **Integration tests:** ~2-5s per test (tmux overhead)
+- **E2E tests:** ~3-10s per test (full CLI startup)
+
+## CI/CD
+
+For CI environments:
+
+```yaml
+# Install tmux in CI
+- name: Install tmux
+  run: |
+    sudo apt-get update
+    sudo apt-get install -y tmux
+
+# Run tests
+- name: Run tests
+  run: bun test
+```