CONTRIBUTING.md

Contributing to better-bash

Setup

git clone https://github.com/alper-dev/better-bash.git
cd better-bash
bun install

Development

bun run build        # Bundle ESM + CJS + generate type declarations
bun test             # Run all tests
bun run typecheck    # Type check without emitting

Project Structure

src/
├── process-manager.ts    # Core engine: ring buffer, long-poll, stdin, cleanup
├── shell-detect.ts       # Cross-platform shell detection + PowerShell Base64 encoding
├── run-effect.ts         # Dual-Effect-instance safe runner
├── types.ts              # Shared types and error classes
├── index.ts              # Public API exports
├── plugin.ts             # OpenCode plugin adapter
├── tools/                # Tool definitions (shared by all adapters)
│   ├── bash-start.ts
│   ├── bash-status.ts
│   ├── bash-kill.ts
│   ├── bash-stdin.ts
│   └── bash-list.ts
└── adapters/             # Platform-specific adapters
    ├── opencode.ts
    └── mimocode.ts

Architecture

ProcessManager is the core. It manages child processes with:

• Ring buffer (100KB default) for output collection
• Long-polling via Effect Deferred
• Auto-cleanup of finished processes
• Per-session process isolation

Tool definitions in tools/ are platform-agnostic. Adapters in adapters/ wrap them for specific platforms.

run-effect.ts exists because MiMoCode has its own Effect runtime. Our bundled Effect and MiMoCode's Effect are different instances, so calling Effect.runPromise from MiMoCode on our Effect objects causes Fiber.runLoop errors. runEffect() uses our bundled instance.

Adding a New Tool

1. Create src/tools/bash-<name>.ts with:

   • bash<Name>Description: tool description string
   • bash<Name>Parameters: JSON schema object
   • executeBash<Name>(pm, params): execution function using runEffect

2. Add ProcessManager method in src/process-manager.ts if needed

3. Export from src/index.ts

4. Add to adapters in src/adapters/opencode.ts and src/adapters/mimocode.ts

5. Add to plugin in src/plugin.ts

6. Add tests in tests/process-manager.test.ts

Testing

Tests use bun:test. Each test gets a fresh ProcessManager instance with tight limits (5 concurrent, 10s timeout, 10KB buffer).

Commands use PowerShell syntax on Windows:

• Use ; to chain commands, not & (PowerShell backgrounds &)
• Use exit 1 not exit /b 1 (cmd.exe syntax)
• Use Start-Sleep -Seconds N for delays

Build Pipeline

1. bun run build.ts: Bun.build bundles ESM (index.js, plugin.js) and CJS (index.cjs, plugin.cjs) with source maps
2. tsc -p tsconfig.dts.json: generates type declarations

We don't use tsup. Bun.build handles bundling natively.

Tool Descriptions

Tool descriptions are the primary documentation for AI agents. They should include:

• When to use this tool vs alternatives
• Shell quoting rules (in bash_start)
• Stdin compatibility table (in bash_stdin)
• Status values and edge cases (in bash_status)

Don't add agent-facing SKILL.md docs for the tool itself; the tool descriptions in src/tools/ and src/plugin.ts are the primary API documentation. (The repo's AGENTS.md is maintenance guidance for AI assistants working in this repository, not agent-facing tooling.)

Releasing

See RELEASING.md for prerequisites, verification, tagging, trusted publishing, and rollback guidance.