ai-or-die 0.1.0

package/docs/adrs/0001-bridge-base-class.md

@@ -0,0 +1,53 @@
+# ADR-0001: Extract BaseBridge for CLI Tool Integration
+
+## Status
+
+**Accepted**
+
+## Date
+
+2025-06-01
+
+## Context
+
+The project currently ships three bridge classes -- `ClaudeBridge`, `CodexBridge`, and `AgentBridge` -- that each manage CLI process spawning, session lifecycle, output buffering, and terminal resizing. Approximately 95% of the code across these three files is identical; the only meaningful differences are:
+
+1. The CLI binary name and its search paths.
+2. The default arguments passed at spawn time.
+3. A handful of tool-specific flags (e.g. dangerous-command approval in Claude).
+
+With three additional tools on the roadmap (Copilot CLI, Gemini Code, and a generic terminal bridge), duplicating this pattern further would create a maintenance burden where every cross-cutting fix (e.g. a reconnection bug, a Windows path issue) must be applied in six or more places.
+
+## Decision
+
+Extract a `BaseBridge` base class that encapsulates the shared behaviour:
+
+- **Platform-aware command discovery** -- use `os.homedir()` instead of `process.env.HOME`, and call `where` on Windows / `which` on Unix to locate binaries.
+- **Session lifecycle** -- `startSession`, `stopSession`, `resizeSession`, `getSessionOutput`, and the internal `sessions` Map.
+- **Output buffering** -- ring-buffer of the last N lines (default 1000) for reconnection support.
+- **Process management** -- `node-pty` spawn with `xterm-256color` on Unix and ConPTY on Windows.
+
+Each concrete bridge (e.g. `ClaudeBridge extends BaseBridge`) only needs to supply:
+
+- `toolName` -- human-readable label.
+- `binaryNames` -- ordered list of binary names / paths to search.
+- `buildArgs(options)` -- returns the argument array for a given session.
+- (optional) `dangerousFlags` -- patterns that trigger the plan-approval UI.
+
+## Consequences
+
+### Positive
+
+- Adding a new tool bridge becomes a ~30-line subclass instead of a full copy-paste of 200+ lines.
+- Cross-platform fixes (Windows path handling, ConPTY quirks) are applied once in `BaseBridge`.
+- Unit tests can cover the base class exhaustively; subclass tests only need to verify tool-specific argument construction.
+
+### Negative
+
+- Introduces an inheritance hierarchy, which can become rigid if tools diverge significantly in the future.
+- Existing bridges need to be refactored, which touches stable code.
+
+### Neutral
+
+- No user-facing behaviour change; this is a purely internal refactor.
+- The WebSocket protocol and session store remain unchanged.

package/docs/adrs/0002-devtunnels-over-ngrok.md

@@ -0,0 +1,56 @@
+# ADR-0002: Replace ngrok with Microsoft Dev Tunnels
+
+## Status
+
+**Accepted**
+
+## Date
+
+2025-06-15
+
+## Context
+
+The project uses the `@ngrok/ngrok` npm package (v1.4.0) to expose the local server to the internet for remote access. This approach has several drawbacks:
+
+1. **Third-party npm dependency** -- `@ngrok/ngrok` pulls in native binaries via postinstall scripts, which complicates installs on locked-down machines and adds supply-chain surface area.
+2. **Security posture** -- traffic routes through ngrok's infrastructure, which is a third-party tunnel provider outside the user's control. Enterprise environments often block ngrok domains outright.
+3. **Cost** -- ngrok's free tier has bandwidth and connection limits; paid tiers add ongoing cost for a feature that many users need only occasionally.
+4. **Platform inconsistency** -- the npm package handles its own binary management, which has led to intermittent install failures on Windows and ARM Linux.
+
+Microsoft Dev Tunnels (`devtunnel` CLI) is a free alternative backed by Azure infrastructure. It supports persistent tunnel names, access control via Microsoft/GitHub accounts, and is pre-installed in GitHub Codespaces and VS Code remote environments.
+
+## Decision
+
+Replace the `@ngrok/ngrok` npm dependency with a shell-out to the `devtunnel` CLI:
+
+```
+devtunnel host -p <port> --allow-anonymous
+```
+
+Key implementation details:
+
+- **No npm dependency** -- spawn `devtunnel` as a child process rather than importing an npm package. This removes `@ngrok/ngrok` from `package.json` entirely.
+- **CLI discovery** -- use the same platform-aware discovery pattern from `BaseBridge` to locate `devtunnel` (or `devtunnel.exe` on Windows) in PATH.
+- **Output parsing** -- parse the tunnel URL from the CLI's stdout (it prints `Connect via browser: https://<id>.devtunnels.ms`).
+- **Lifecycle management** -- the tunnel process is tied to the server's lifecycle; it is killed on SIGINT/SIGTERM alongside the Express server.
+- **Fallback messaging** -- if `devtunnel` is not found, log a clear message with install instructions rather than crashing.
+
+## Consequences
+
+### Positive
+
+- Removes the `@ngrok/ngrok` npm dependency and its native binary postinstall step.
+- Traffic routes through Microsoft/Azure infrastructure, which is more acceptable in enterprise environments.
+- Free tier has generous limits (no bandwidth cap for anonymous tunnels).
+- Cross-platform: `devtunnel` CLI ships for Windows, macOS, and Linux (x64 and ARM64).
+
+### Negative
+
+- Requires the user to install the `devtunnel` CLI separately (`winget install Microsoft.devtunnel`, `brew install devtunnel`, or direct download). This is an external prerequisite that the app cannot auto-install.
+- Microsoft account or GitHub sign-in is required for first-time `devtunnel` setup (one-time `devtunnel user login`).
+- Less programmatic control compared to an in-process SDK -- we rely on parsing CLI output, which could break if the output format changes.
+
+### Neutral
+
+- The tunnel feature remains opt-in (activated via `--tunnel` flag); users who do not need remote access are unaffected.
+- The WebSocket protocol and client code require no changes -- the tunnel is transparent at the HTTP/WS layer.

package/docs/adrs/0003-multi-tool-architecture.md

@@ -0,0 +1,71 @@
+# ADR-0003: Multi-Tool Architecture
+
+## Status
+
+**Accepted**
+
+## Date
+
+2025-07-01
+
+## Context
+
+ai-or-die started as a single-purpose web frontend for the Claude Code CLI. Over time, support was added for OpenAI Codex and Cursor Agent, each via a dedicated bridge class and hardcoded UI elements. The roadmap now includes Copilot CLI, Gemini Code Assist, and a generic terminal mode, which means:
+
+1. **Hardcoded tool lists do not scale.** Every new tool requires edits in the server constructor, the WebSocket message handler, the REST API routes, and the client-side UI (tool cards, session tabs, icons).
+2. **The client must know about every tool at build time.** Adding a tool that is not installed on a given server should not break the UI or require a code change -- the card should simply not appear.
+3. **Each tool has different "dangerous" command patterns** that the plan-approval UI needs to intercept (e.g. `rm -rf` for a generic terminal, `--dangerously-skip-permissions` for Claude).
+
+## Decision
+
+Adopt a tool-agnostic architecture with the following components:
+
+### Server-side: Tool Registry
+
+The server maintains a `toolRegistry` -- an ordered list of tool descriptors built at startup by probing which CLI binaries are available:
+
+```js
+{
+  id: 'claude',
+  name: 'Claude',
+  bridge: claudeBridge,        // BaseBridge subclass instance
+  available: true,             // binary was found on this machine
+  dangerousPatterns: [/--dangerously-skip-permissions/],
+  icon: 'claude',              // maps to a client-side icon set
+  description: 'Anthropic Claude Code'
+}
+```
+
+A new `/api/tools` REST endpoint returns the list of available tools (minus internal fields like `bridge`), so the client can render the UI dynamically.
+
+### Client-side: Dynamic UI Card Generation
+
+The landing page fetches `/api/tools` on load and generates one "Start" card per available tool. No tool-specific markup exists in `index.html` -- all cards are built from the same template in `app.js`. Tool icons are resolved from a shared sprite or CSS class map.
+
+### WebSocket Protocol: Unified Messages
+
+The existing WebSocket messages (`create_session`, `start_claude`, `input`, `resize`, `stop`) are generalized:
+
+- `start_claude` becomes `start_tool` with a `toolId` field.
+- Session objects carry a `toolId` so the server routes messages to the correct bridge.
+- All other messages (`input`, `resize`, `stop`, `join_session`, `leave_session`) remain unchanged -- they operate on sessions, not tools.
+
+## Consequences
+
+### Positive
+
+- Adding a new tool requires only a `BaseBridge` subclass and a registry entry -- no client code changes.
+- The UI stays clean regardless of how many tools are registered; unavailable tools simply do not render.
+- Each tool can declare its own dangerous-command patterns, which the plan-detector evaluates at runtime.
+- Server operators can disable tools via environment variables or config without touching code.
+
+### Negative
+
+- The `/api/tools` endpoint is a new network request on page load, adding a small latency hit before the UI renders.
+- Dynamic card generation is slightly harder to debug than static HTML.
+- Tool icons/branding must be managed as a shared asset set rather than inline SVGs.
+
+### Neutral
+
+- Backward compatibility is maintained: existing `start_claude` messages are internally aliased to `start_tool { toolId: 'claude' }` so older clients continue to work during the transition.
+- Session persistence format gains a `toolId` field; sessions without one default to `'claude'` for migration.

package/docs/adrs/0004-cross-platform-support.md

@@ -0,0 +1,101 @@
+# ADR-0004: Cross-Platform Support (Windows + Linux)
+
+## Status
+
+**Accepted**
+
+## Date
+
+2025-07-15
+
+## Context
+
+The original codebase was written with Linux (and macOS) as the sole target. Several patterns in the code are not portable:
+
+1. **`process.env.HOME`** -- undefined on Windows, where the equivalent is `process.env.USERPROFILE` or `os.homedir()`.
+2. **`which` for command discovery** -- Windows uses `where.exe` instead.
+3. **Hardcoded Unix paths** -- e.g. `/usr/local/bin/claude`, `/home/ec2-user/.claude/local/claude`.
+4. **`node-pty` defaults** -- Linux uses the Unix PTY subsystem; Windows requires ConPTY (available since Windows 10 version 1809).
+5. **Default shell** -- the bridges implicitly assume `/bin/bash` or similar; Windows should default to PowerShell (`pwsh` or `powershell.exe`).
+
+Users on Windows (especially WSL2 and native Windows with `node-pty` ConPTY support) have reported install and runtime failures stemming from these assumptions.
+
+## Decision
+
+Introduce platform detection at the `BaseBridge` level (see ADR-0001) with the following changes:
+
+### Command Discovery
+
+```js
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+function commandExists(binary) {
+  const checker = process.platform === 'win32' ? 'where.exe' : 'which';
+  try {
+    execFileSync(checker, [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+### Home Directory
+
+Replace all uses of `process.env.HOME` with `os.homedir()`, which returns the correct value on every platform.
+
+### Search Paths
+
+Each bridge's `binaryNames` list includes both Unix and Windows variants:
+
+```js
+// ClaudeBridge
+binaryNames: [
+  'claude',
+  path.join(os.homedir(), '.claude', 'local', 'claude'),   // Unix
+  path.join(os.homedir(), '.claude', 'local', 'claude.exe'), // Windows
+  '/usr/local/bin/claude',
+]
+```
+
+Non-existent paths are silently skipped during discovery.
+
+### PTY Configuration
+
+```js
+const ptyOptions = {
+  name: process.platform === 'win32' ? 'conpty' : 'xterm-256color',
+  cols: options.cols || 80,
+  rows: options.rows || 24,
+  cwd: options.workingDir,
+  env: process.env,
+  ...(process.platform === 'win32' && { useConpty: true }),
+};
+```
+
+### Default Shell (generic terminal bridge)
+
+For the planned generic terminal tool, the default shell is:
+
+- **Windows**: `pwsh.exe` (PowerShell 7+), falling back to `powershell.exe`, then `cmd.exe`.
+- **Linux/macOS**: `$SHELL`, falling back to `/bin/bash`, then `/bin/sh`.
+
+## Consequences
+
+### Positive
+
+- The application works out of the box on Windows 10 1809+ (with ConPTY) and all supported Linux distributions.
+- WSL2 users can run the server natively on Windows or inside the WSL2 VM -- both paths work.
+- CI can run a test matrix across `ubuntu-latest` and `windows-latest` to catch regressions.
+
+### Negative
+
+- Windows ConPTY has known quirks with certain escape sequences; some terminal rendering may differ from Unix.
+- `node-pty` native compilation on Windows requires build tools (Visual Studio Build Tools or `windows-build-tools`), which adds install friction.
+- Testing surface area doubles -- every bridge test must pass on both platforms.
+
+### Neutral
+
+- macOS support comes for free since it shares the Unix PTY path; no additional work is needed.
+- The `--tunnel` feature (Dev Tunnels) already supports both platforms, so no tunnel-specific changes are required.

package/docs/adrs/0005-single-binary-distribution.md

@@ -0,0 +1,58 @@
+# ADR 0005: Single Binary Distribution via Node.js SEA
+
+## Status
+
+Accepted
+
+## Context
+
+Users currently install ai-or-die via `npm install -g ai-or-die` or `npx ai-or-die`, both of which require Node.js and npm to be pre-installed. A single binary distribution would allow download-and-run without a Node.js runtime, simplifying distribution and onboarding.
+
+The main challenge is the `@lydell/node-pty` dependency, which ships platform-specific prebuilt native `.node` files and helper binaries (conpty.dll, OpenConsole.exe on Windows; spawn-helper on Linux).
+
+## Decision
+
+Use **Node.js Single Executable Application (SEA)**, available as a stable feature since Node 22. This is the only actively maintained, officially supported approach for packaging Node.js apps as standalone binaries.
+
+### Build pipeline
+
+1. **esbuild** bundles all JavaScript into `dist/bundle.js`, with `@lydell/node-pty` marked as external (native modules cannot be bundled)
+2. Static assets (`src/public/**`) and platform-specific native `.node` prebuilts are collected as SEA assets
+3. `node --experimental-sea-config` generates a preparation blob
+4. The blob is injected into a copy of the Node binary using `postject`
+5. The resulting binary is uploaded to GitHub Releases
+
+### Runtime behavior
+
+A `sea-bootstrap.js` wrapper detects SEA mode and:
+- Extracts native `.node` files to a temp directory
+- Patches `Module._resolveFilename` to redirect `@lydell/node-pty` requires
+- Cleans up the temp directory on exit
+
+Static assets are served from the SEA blob via a custom Express middleware that uses `sea.getRawAsset()`.
+
+## Alternatives Considered
+
+| Option | Why not |
+|--------|---------|
+| `pkg` (Vercel) | Deprecated since 2023, unmaintained |
+| `nexe` | Sporadic maintenance, limited Node 22+ support |
+| Bun compile | Requires Bun runtime; `@lydell/node-pty` is Node-specific |
+| Standalone tarball | Not a single file; still requires manual extraction |
+
+## Consequences
+
+### Positive
+- Zero-install distribution: download binary, run it
+- Binaries attached to GitHub Releases automatically
+- No Node.js runtime required on user machines
+
+### Negative
+- Binary size ~80-100MB (includes Node.js runtime)
+- Native addon extraction to temp directory at startup adds ~100ms
+- Must build on each target platform (no cross-compilation)
+- External CLI tools (Claude, Copilot, Gemini) must still be installed separately
+
+### Neutral
+- npm installation remains the primary distribution method
+- SEA binaries are a convenience alternative, not a replacement

package/docs/agent-instructions/00-philosophy.md

@@ -0,0 +1,55 @@
+# Core Philosophy
+
+## Prime Directive
+
+We do not guess. We research, we plan, we test, then we code.
+
+## Principles
+
+### 1. Documentation Drives Code
+
+No code is written without a corresponding spec in `docs/specs/`. If the docs say X and the code says Y, the code is wrong. Before implementing any feature:
+
+- Check `docs/specs/` for existing specification
+- If no spec exists, write one first
+- After implementation, update the spec to reflect the final state
+
+### 2. Research Before Implementing
+
+Every agent must search the web for current best practices before coding. Training data goes stale. Libraries change. APIs evolve. Before adding any dependency or implementing any pattern:
+
+- Search for the current recommended approach
+- Verify library versions are not deprecated
+- Check for known CVEs or security advisories
+- Document findings in the relevant ADR if it's an architectural decision
+
+### 3. Test Alongside Code
+
+No pull request without tests for new behavior. Tests are not an afterthought — they are written alongside (or before) the implementation. Target 90% coverage for all new code.
+
+### 4. Measure Twice, Cut Once
+
+Plan before executing. Read the existing code before modifying it. Understand the bridge pattern, the WebSocket protocol, and the session lifecycle before touching any of them. Check `docs/adrs/` for past architectural decisions to avoid regression.
+
+### 5. Cross-Platform Always
+
+Every code change must consider both Windows and Linux. Use `os.homedir()` not `process.env.HOME`. Use `path.join()` not string concatenation. Test path handling for both OS types. The CI pipeline runs on both platforms — if it doesn't pass on both, it doesn't merge.
+
+## The CEO Model
+
+When tackling complex tasks, the initiating agent acts as CEO — orchestrating sub-agents as workers. The CEO:
+
+- Breaks the task into independent, parallelizable units
+- Delegates to specialized agents (architect, engineer, QA, etc.)
+- Monitors progress and resolves blockers
+- Ensures the final result is coherent and tested
+
+## Decision Records
+
+Significant architectural decisions are recorded in `docs/adrs/`. Before making a decision that affects:
+- How tools are integrated (bridge pattern)
+- How data flows (WebSocket protocol)
+- What dependencies are used
+- How the system is deployed
+
+Write an ADR first. The format is in `docs/adrs/0000-template.md`.

package/docs/agent-instructions/01-research-and-web.md

@@ -0,0 +1,49 @@
+# Research and Web Usage
+
+## Internet is First-Class
+
+The internet is not optional. Agents must use web search to find current best practices before coding. Do not rely solely on training data for:
+
+- Library APIs and versions
+- Security advisories
+- Platform-specific behavior
+- Current recommended patterns
+
+## When to Research
+
+### Before Adding Dependencies
+
+- Search for the package's current status (maintained? deprecated?)
+- Check npm download trends and last publish date
+- Look for known vulnerabilities (`npm audit` equivalent)
+- Verify compatibility with Node.js 16+
+
+### Before Implementing Patterns
+
+- Search for "[pattern] best practices [year]"
+- Look for cross-platform gotchas (especially Windows + Linux)
+- Check if the framework/library has built-in solutions
+
+### Before Making Architectural Decisions
+
+- Search for alternatives and their tradeoffs
+- Find 3+ sources before committing to an approach
+- Document sources in the ADR
+
+## Validation Protocol
+
+1. **Version Check**: Before using any API, search for its current documentation
+2. **CVE Check**: Before adding dependencies, search for known vulnerabilities
+3. **Platform Check**: Before using OS-specific features, verify cross-platform support
+4. **Deprecation Check**: Before using any pattern, verify it's not deprecated
+
+## Information Saturation
+
+Research until you reach information saturation — the point where new searches return the same information you already have. Only then proceed to implementation.
+
+## Citation in ADRs
+
+When writing Architecture Decision Records, cite external sources:
+- Link to documentation pages
+- Reference Stack Overflow answers or GitHub issues
+- Note the date of the research (information has a shelf life)

package/docs/agent-instructions/02-testing-and-validation.md

@@ -0,0 +1,63 @@
+# Testing and Validation
+
+## Coverage Target
+
+Target 90% code coverage for all new code. This is not optional for new features or refactors. Existing code without tests should be covered when modified.
+
+## Test-Driven Approach
+
+Write tests alongside implementation, not after. The workflow:
+
+1. Write the test describing expected behavior
+2. Implement the code to make the test pass
+3. Refactor if needed, keeping tests green
+
+## Test Framework
+
+- **Framework**: Mocha with Node.js built-in `assert`
+- **Location**: `test/` directory
+- **Naming**: `name.test.js`
+- **Running**: `npm test`
+
+## Test Guidelines
+
+- Write fast, isolated unit tests
+- Avoid network calls and real CLI spawning in tests — mock process spawns
+- Use temp directories for file system tests (see `session-store.test.js` pattern)
+- Test cross-platform behavior: path construction, command resolution, shell detection
+
+## Self-Validation
+
+Before committing, every agent must:
+
+1. Run `npm test` — all tests pass
+2. Run `npm start` — server boots without errors
+3. Run `scripts/validate.sh` (Linux) or `scripts/validate.ps1` (Windows)
+4. Verify the change doesn't break existing functionality
+
+## What to Test
+
+### For Bridge Changes
+- Command discovery on mock file systems
+- Session lifecycle (start, input, resize, stop)
+- Error handling (command not found, process crash)
+- Platform-specific paths
+
+### For Server Changes
+- REST API responses (status codes, JSON structure)
+- WebSocket message handling
+- Session creation and deletion
+- Auth middleware behavior
+
+### For Client Changes
+- Manual browser testing (create session, select tool, verify output)
+- Check mobile responsiveness
+- Verify WebSocket reconnection
+
+## When Tests Fail
+
+If tests fail, fix them before moving on. Do not:
+- Skip failing tests
+- Comment out assertions
+- Reduce coverage to make the build pass
+- Commit with known failures

package/docs/agent-instructions/03-tooling-and-pipelines.md

@@ -0,0 +1,59 @@
+# Tooling and Pipelines
+
+## Automation Rule
+
+If you perform a verification task twice, script it. All scripts live in the `scripts/` directory.
+
+### Current Scripts
+
+- `scripts/validate.sh` — Linux validation (lint, test, docs check)
+- `scripts/validate.ps1` — Windows validation (same checks)
+- `scripts/release-pr.sh` — Release process automation
+
+## CI/CD Pipeline
+
+### GitHub Actions
+
+The CI pipeline (`.github/workflows/ci.yml`) runs on every push and PR:
+
+1. **Matrix**: Runs on both `ubuntu-latest` and `windows-latest`
+2. **Install**: `npm ci`
+3. **Lint**: ESLint check
+4. **Test**: `npm test` with coverage reporting
+5. **Audit**: `npm audit` for security vulnerabilities
+6. **Docs Check**: Verify docs/ structure exists
+
+### Release Pipeline
+
+The release pipeline (`.github/workflows/release-on-main.yml`) triggers on push to main:
+
+1. Read version from `package.json`
+2. Check if git tag already exists
+3. Create GitHub Release with tag
+4. Publish to npm
+
+## Tool Creation Guidelines
+
+When creating new scripts:
+
+- Use `#!/bin/bash` for Linux scripts, PowerShell for Windows
+- Include error handling and meaningful exit codes
+- Add usage instructions as comments at the top
+- Make scripts idempotent (safe to run multiple times)
+
+## Dependency Management
+
+- Pin major versions in `package.json` (use `^` for minor/patch)
+- Run `npm audit` before adding any new dependency
+- Prefer packages with:
+  - Active maintenance (commits within last 6 months)
+  - No known vulnerabilities
+  - Cross-platform support
+  - Minimal transitive dependencies
+
+## Code Quality
+
+- **Linter**: ESLint (configured in project)
+- **Style**: 2-space indentation, semicolons, single quotes
+- **Naming**: kebab-case files, PascalCase classes, camelCase functions
+- **Comments**: Only where the logic isn't self-evident