WIP: Add tmux-based CLI testing infrastructure

- Add integration and E2E test suites using tmux
- Add automatic tmux detection in .bin/bun wrapper
- Add test utilities for checking dependencies
- Add comprehensive testing documentation
- Update CLI to use strip-ansi for output cleaning

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

.bin/bun

@@ -172,6 +172,14 @@ create_cache() {
     fi
 }
 
+# Function to check if tmux is installed
+check_tmux_installed() {
+    if ! command -v tmux &> /dev/null; then
+        return 1
+    fi
+    return 0
+}
+
 # Function to check if command doesn't need secrets
 # Returns 0 if secrets are NOT needed, 1 if they ARE needed
 doesnt_need_secrets() {
@@ -248,6 +256,43 @@ doesnt_need_secrets() {
                     ;;
             esac
             ;;
+        # Test command needs special handling
+        test)
+            # Check for integration/e2e tests that require tmux
+            # Convention: test files matching *integration*.test.ts or *e2e*.test.ts
+            local needs_tmux=false
+            
+            for arg in "$@"; do
+                # Check if running integration or e2e tests
+                if [[ "$arg" =~ (integration|e2e).*\.test\.(ts|tsx|js|jsx) ]]; then
+                    needs_tmux=true
+                    break
+                fi
+                # Also check if running all tests and integration files exist
+                if [[ "$arg" == "test" ]] || [[ -z "$arg" ]]; then
+                    if ls */src/__tests__/*integration*.test.ts 2>/dev/null || ls */src/__tests__/*e2e*.test.ts 2>/dev/null; then
+                        needs_tmux=true
+                        break
+                    fi
+                fi
+            done
+            
+            # If running integration/e2e tests, check tmux availability
+            if [ "$needs_tmux" = true ]; then
+                if ! check_tmux_installed; then
+                    echo "⚠️  tmux not found but required for integration/E2E tests"
+                    echo ""
+                    echo "📦 Install tmux:"
+                    echo "   macOS:    brew install tmux"
+                    echo "   Ubuntu:   sudo apt-get install tmux"
+                    echo "   Windows:  Use WSL and run 'sudo apt-get install tmux'"
+                    echo ""
+                    echo "ℹ️  Skipping tmux-dependent tests..."
+                    echo ""
+                fi
+            fi
+            return 1  # Tests need secrets
+            ;;
         *)
             # Default to needing secrets for all other commands
             return 1

CONTRIBUTING.md

@@ -114,35 +114,35 @@ Before you begin, you'll need to install a few tools:
 
 10. **Running in other directories**:
 
-   In order to run the CLI from other directories, you need to first publish the agents to the database.
+In order to run the CLI from other directories, you need to first publish the agents to the database.
 
-   - First, create a publisher profile at http://localhost:3000/publishers. Make sure the `publisher_id` is `codebuff`.
+- First, create a publisher profile at http://localhost:3000/publishers. Make sure the `publisher_id` is `codebuff`.
 
-   - Run:
+- Run:
 
-     ```bash
-     bun run start-bin publish base
-     ```
+  ```bash
+  bun run start-bin publish base
+  ```
 
-   - It will give you an error along the lines of `Invalid agent ID: [some agent ID]`, e.g. `Invalid agent ID: context-pruner`. You need to publish that agent at the same time, e.g.:
+- It will give you an error along the lines of `Invalid agent ID: [some agent ID]`, e.g. `Invalid agent ID: context-pruner`. You need to publish that agent at the same time, e.g.:
 
-     ```bash
-     bun run start-bin publish base context-pruner
-     ```
+  ```bash
+  bun run start-bin publish base context-pruner
+  ```
 
-   - Repeat this until there are no more errors.
+- Repeat this until there are no more errors.
 
-     - As of the time of writing, the command required is:
+  - As of the time of writing, the command required is:
 
-     ```bash
-     bun start-bin publish base context-pruner file-explorer file-picker researcher thinker reviewer
-     ```
+  ```bash
+  bun start-bin publish base context-pruner file-explorer file-picker researcher thinker reviewer
+  ```
 
-   - Now, you can start the CLI in any directory by running:
+- Now, you can start the CLI in any directory by running:
 
-     ```bash
-     bun run start-bin --cwd [some/other/directory]
-     ```
+  ```bash
+  bun run start-bin --cwd [some/other/directory]
+  ```
 
 ## Understanding the Codebase
 
@@ -204,6 +204,31 @@ bun test specific.test.ts  # Run just one test file
 
 **Writing tests:** Use `spyOn()` for mocking functions (it's cleaner than `mock.module()`), and always clean up with `mock.restore()` in your `afterEach()` blocks.
 
+#### Interactive CLI Testing
+
+For testing interactive CLI features (user input, real-time responses), install tmux:
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+
+# Windows (via WSL)
+wsl --install
+sudo apt-get install tmux
+```
+
+Run the proof-of-concept to validate your setup:
+
+```bash
+cd cli
+bun run test:tmux-poc
+```
+
+See [cli/src/__tests__/README.md](cli/src/__tests__/README.md) for comprehensive interactive testing documentation.
+
 ### Commit Messages
 
 We use conventional commit format:

README.md

@@ -148,6 +148,31 @@ We ❤️ contributions from the community - whether you're fixing bugs, tweakin
 
 **Want to contribute?** Check out our [Contributing Guide](./CONTRIBUTING.md) to get started.
 
+### Running Tests
+
+To run the test suite:
+
+```bash
+cd cli
+bun test
+```
+
+**For interactive E2E testing**, install tmux:
+
+```bash
+# macOS
+brew install tmux
+
+# Ubuntu/Debian
+sudo apt-get install tmux
+
+# Windows (via WSL)
+wsl --install
+sudo apt-get install tmux
+```
+
+See [cli/src/__tests__/README.md](cli/src/__tests__/README.md) for comprehensive testing documentation.
+
 Some ways you can help:
 
 - 🐛 **Fix bugs** or add features

cli/README.md

@@ -16,6 +16,38 @@ Run the TUI in development mode:
 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
+```
+
+See [src/__tests__/README.md](src/__tests__/README.md) for comprehensive testing documentation.
+
 ## Build
 
 Build the package:

cli/knowledge.md

@@ -1,5 +1,22 @@
 # CLI Package Knowledge
 
+## Test Naming Conventions
+
+**IMPORTANT**: Follow these naming patterns for automatic dependency 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`)
+
+**Why?** The `.bin/bun` wrapper detects files matching `*integration*.test.ts` or `*e2e*.test.ts` patterns and automatically checks for tmux availability. If tmux is missing, it shows installation instructions but lets tests continue (they skip gracefully).
+
+**Benefits:**
+
+- Project-wide convention (not CLI-specific)
+- No hardcoded directory paths
+- Automatic dependency validation
+- Clear test categorization
+
 ## Migration from Custom OpenTUI Fork
 
 **October 2024**: Migrated from custom `CodebuffAI/opentui#codebuff/custom` fork to official `@opentui/react@^0.1.27` and `@opentui/core@^0.1.27` packages.

cli/package.json

@@ -22,6 +22,7 @@
     "build:binary": "bun ./scripts/build-binary.ts codecane $npm_package_version",
     "start": "bun run dist/index.js",
     "test": "bun test",
+    "test:tmux-poc": "bun run src/__tests__/tmux-poc.ts",
     "pretypecheck": "bun run build:sdk",
     "typecheck": "tsc --noEmit -p ."
   },
@@ -46,6 +47,7 @@
     "@types/bun": "^1.3.0",
     "@types/node": "22",
     "@types/react": "^18.3.12",
-    "@types/react-reconciler": "^0.32.0"
+    "@types/react-reconciler": "^0.32.0",
+    "strip-ansi": "^7.1.2"
   }
 }