gastown-gui 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 web3dev1337
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# Gas Town GUI
+
+A standalone web GUI for [Gas Town](https://github.com/steveyegge/gastown) - the multi-agent orchestration system for Claude Code.
+
+![Gas Town GUI Screenshot](assets/screenshot.png)
+
+![Gas Town Loading Screen](assets/loading-background.jpeg)
+
+> **Note:** This is an independent companion project, not part of the official Gas Town repository. Originally submitted as [PR #212](https://github.com/steveyegge/gastown/pull/212), now maintained as a standalone package per Steve's recommendation.
+
+> *"Thank you for the impressive work on this GUI! The effort and thought that went into it is clear - the architecture is clean, the documentation is thorough, and it demonstrates a solid understanding of Gas Town's workflow. [...] If you're interested in continuing this work, I'd encourage publishing it as a standalone companion project."*
+>
+> — **Steve Yegge**, creator of Gas Town ([PR #212 comment](https://github.com/steveyegge/gastown/pull/212))
+
+**Status:** 🚧 **Candidate for Testing** - Provides a solid starting point for a Gas Town GUI interface.
+
+---
+
+## Quick Start
+
+### 1. Install Prerequisites
+
+```bash
+# Gas Town CLI (required)
+npm install -g @gastown/gt
+# Or: go install github.com/steveyegge/gastown/cmd/gt@latest
+
+# GitHub CLI (optional, for PR tracking)
+gh auth login
+```
+
+### 2. Install Gas Town GUI
+
+```bash
+# Via npm (recommended)
+npm install -g gastown-gui
+
+# Or from source
+git clone https://github.com/web3dev1337/gastown-gui.git
+cd gastown-gui
+npm install
+npm link
+```
+
+### 3. Start the GUI
+
+```bash
+gastown-gui start --open
+```
+
+Opens `http://localhost:7667` in your browser.
+
+### 4. Verify Setup
+
+```bash
+gastown-gui doctor
+```
+
+---
+
+## Features
+
+- **Rig Management** - Add, view, and organize project repositories
+- **Work Tracking** - Create and manage work items (beads)
+- **Task Assignment** - Sling work to rigs and agents
+- **Real-Time Updates** - Live WebSocket updates for all operations
+- **PR Tracking** - View GitHub pull requests across projects
+- **Mail Inbox** - Read messages from agents and polecats
+- **Health Monitoring** - Run doctor checks and view system status
+
+---
+
+## CLI Usage
+
+```bash
+# Start server (default port 7667)
+gastown-gui
+
+# Custom port
+gastown-gui start --port 4000
+
+# Open browser automatically
+gastown-gui start --open
+
+# Development mode
+gastown-gui start --dev
+
+# Check prerequisites
+gastown-gui doctor
+
+# Show version
+gastown-gui version
+
+# Show help
+gastown-gui help
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--port, -p` | Server port | 7667 |
+| `--host, -h` | Server host | 127.0.0.1 |
+| `--open, -o` | Open browser | false |
+| `--dev` | Development mode | false |
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | 7667 |
+| `HOST` | Server host | 127.0.0.1 |
+| `GT_ROOT` | Gas Town root directory | ~/gt |
+
+---
+
+## How It Works
+
+The GUI acts as a **bridge** between your browser and the Gas Town CLI:
+
+```
+┌─────────────┐
+│   Browser   │
+│   (Client)  │
+└──────┬──────┘
+       │ HTTP API / WebSocket
+       ↓
+┌─────────────┐
+│  gastown-   │
+│  gui server │
+└──────┬──────┘
+       │ subprocess (gt, bd, gh)
+       ↓
+┌─────────────┐
+│   ~/gt/     │
+│  workspace  │
+└─────────────┘
+```
+
+All operations execute through the official `gt` and `bd` commands - the GUI never directly modifies Gas Town's internal state.
+
+---
+
+## Architecture
+
+### Tech Stack
+
+- **Backend:** Node.js + Express
+- **Frontend:** Vanilla JavaScript (no framework)
+- **Communication:** WebSocket for real-time updates
+- **Testing:** Vitest + Puppeteer E2E tests
+
+### Design Principles
+
+1. **Server-Authoritative** - All operations execute via `gt` and `bd` CLI commands
+2. **Non-Blocking UI** - Modals close immediately, operations run in background
+3. **Real-Time Updates** - WebSocket broadcasts status changes to all clients
+4. **Graceful Degradation** - UI handles missing data and command failures
+5. **Cache & Refresh** - Background data preloading with stale-while-revalidate
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description | CLI Command |
+|--------|----------|-------------|-------------|
+| GET | `/api/status` | System status | `gt status --json` |
+| GET | `/api/rigs` | List rigs | `gt rig list` |
+| POST | `/api/rigs` | Add rig | `gt rig add` |
+| GET | `/api/work` | List work items | `bd list` |
+| POST | `/api/work` | Create work | `bd new` |
+| POST | `/api/sling` | Sling work | `gt sling` |
+| GET | `/api/prs` | GitHub PRs | `gh pr list` |
+| GET | `/api/mail` | Mail inbox | `gt mail inbox` |
+| GET | `/api/doctor` | Health check | `gt doctor` |
+
+---
+
+## Project Structure
+
+```
+gastown-gui/
+├── bin/cli.js           # CLI entry point
+├── server.js            # Express + WebSocket server
+├── index.html           # Main HTML (single page)
+├── css/                 # Stylesheets
+│   ├── variables.css
+│   ├── reset.css
+│   ├── layout.css
+│   ├── components.css
+│   └── animations.css
+├── js/
+│   ├── app.js           # Main app entry
+│   ├── api.js           # API client
+│   ├── state.js         # State management
+│   └── components/      # UI components
+│       ├── dashboard.js
+│       ├── rig-list.js
+│       ├── work-list.js
+│       ├── pr-list.js
+│       ├── mail-list.js
+│       └── ...
+├── test/
+│   ├── unit/            # Unit tests
+│   └── e2e.test.js      # E2E tests
+└── assets/              # Favicons, icons
+```
+
+---
+
+## Testing
+
+```bash
+# All tests
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# E2E tests
+npm run test:e2e
+
+# Watch mode
+npm run test:watch
+```
+
+---
+
+## Known Limitations
+
+### Remaining Features (Use CLI)
+
+| Feature | Status |
+|---------|--------|
+| Polecat spawn/kill/logs | ❌ CLI only |
+| Agent configuration UI | ❌ Not implemented |
+| Rig deletion | ❌ Not implemented |
+
+### Recently Implemented
+
+| Feature | Status |
+|---------|--------|
+| Crew management | ✅ Create/list/view |
+| Formula operations | ✅ Create/list/use |
+| Test coverage | ✅ 206 tests passing |
+
+**Known Issues:**
+- GT CLI sling may fail with "mol bond requires direct database access" (upstream issue)
+
+---
+
+## Compatibility
+
+- **Gas Town:** v0.2.x and later
+- **Node.js:** 18, 20, 22
+- **Browsers:** Chrome, Firefox, Safari (latest)
+
+The GUI calls CLI commands via subprocess, so it should work with any Gas Town version that has compatible CLI output.
+
+---
+
+## Contributing
+
+Contributions welcome!
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test locally (start server with `npm start`, verify in browser)
+5. Run automated tests: `npm test` (206 tests must pass)
+6. Submit a pull request
+
+### Looking for Maintainers
+
+We're looking for maintainers to help review and merge PRs. If you're interested in helping maintain this project, please open an issue or reach out!
+
+---
+
+## License
+
+MIT
+
+---
+
+## Credits
+
+- **Gas Town:** [steveyegge/gastown](https://github.com/steveyegge/gastown) by Steve Yegge
+- **GUI Implementation:** Built with Claude Code
+- **Original PR:** [#212](https://github.com/steveyegge/gastown/pull/212)
+
+### Contributors
+
+Thanks to these community members who contributed to the original PR through testing, comments, and recommended fixes:
+
+- [@gsxdsm](https://github.com/gsxdsm)
+- [@michaellady](https://github.com/michaellady)
+- [@olivierlefloch](https://github.com/olivierlefloch)
+- [@zalo](https://github.com/zalo)
+- [@irelandpaul](https://github.com/irelandpaul)
+
+---
+
+**Disclaimer:** This is an independent community project, not officially affiliated with Gas Town. Use at your own risk.

package/bin/cli.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+
+/**
+ * Gas Town GUI CLI
+ *
+ * Command-line interface for starting the Gas Town GUI server.
+ *
+ * Usage:
+ *   gastown-gui [command] [options]
+ *
+ * Commands:
+ *   start         Start the GUI server (default)
+ *   version       Show version
+ *   help          Show help
+ *
+ * Options:
+ *   --port, -p    Port to run on (default: 7667)
+ *   --host, -h    Host to bind to (default: 127.0.0.1)
+ *   --open, -o    Open browser after starting
+ *   --dev         Enable development mode (auto-reload)
+ */
+
+import { spawn, execSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '..');
+
+// Parse arguments
+const args = process.argv.slice(2);
+
+// Check for help/version flags first (before command parsing)
+if (args.includes('--help') || args.includes('-h')) {
+  showHelp();
+  process.exit(0);
+}
+if (args.includes('--version') || args.includes('-v')) {
+  showVersion();
+  process.exit(0);
+}
+
+const command = args.find(a => !a.startsWith('-')) || 'start';
+const options = {
+  port: getOption(['--port', '-p']) || process.env.PORT || '7667',
+  host: getOption(['--host', '-h']) || process.env.HOST || '127.0.0.1',
+  open: hasFlag(['--open', '-o']),
+  dev: hasFlag(['--dev']),
+};
+
+function getOption(flags) {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && args[idx + 1]) {
+      return args[idx + 1];
+    }
+  }
+  return null;
+}
+
+function hasFlag(flags) {
+  return flags.some(f => args.includes(f));
+}
+
+function showHelp() {
+  console.log(`
+Gas Town GUI - Web interface for Gas Town multi-agent orchestrator
+
+Usage:
+  gastown-gui [command] [options]
+
+Commands:
+  start         Start the GUI server (default)
+  version       Show version information
+  doctor        Check Gas Town installation
+  help          Show this help message
+
+Options:
+  --port, -p <port>   Port to run on (default: 7667, or PORT env var)
+  --host, -h <host>   Host to bind to (default: 127.0.0.1, or HOST env var)
+  --open, -o          Open browser after starting
+  --dev               Enable development mode
+
+Environment Variables:
+  PORT         Server port (default: 7667)
+  HOST         Server host (default: 127.0.0.1)
+  GT_ROOT      Gas Town root directory (default: ~/gt)
+
+Examples:
+  gastown-gui                    # Start on default port
+  gastown-gui start --port 4000  # Start on port 4000
+  gastown-gui start --open       # Start and open browser
+  gastown-gui doctor             # Check gt installation
+
+Prerequisites:
+  - Gas Town CLI (gt) must be installed and in PATH
+  - GitHub CLI (gh) for PR/issue tracking (optional)
+
+More info: https://github.com/web3dev1337/gastown-gui
+`);
+}
+
+function showVersion() {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  console.log(`gastown-gui v${packageJson.version}`);
+
+  // Check gt version
+  try {
+    const gtVersion = execSync('gt version 2>/dev/null || echo "not installed"', { encoding: 'utf8' }).trim();
+    console.log(`gt: ${gtVersion}`);
+  } catch {
+    console.log('gt: not found in PATH');
+  }
+
+  // Check gh version
+  try {
+    const ghVersion = execSync('gh --version 2>/dev/null | head -1 || echo "not installed"', { encoding: 'utf8' }).trim();
+    console.log(`gh: ${ghVersion}`);
+  } catch {
+    console.log('gh: not found in PATH');
+  }
+}
+
+function runDoctor() {
+  console.log('Gas Town GUI Doctor\n');
+  console.log('Checking prerequisites...\n');
+
+  let allGood = true;
+
+  // Check Node.js version
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (major >= 18) {
+    console.log(`✅ Node.js ${nodeVersion} (>= 18 required)`);
+  } else {
+    console.log(`❌ Node.js ${nodeVersion} (>= 18 required)`);
+    allGood = false;
+  }
+
+  // Check gt
+  try {
+    const gtPath = execSync('which gt 2>/dev/null', { encoding: 'utf8' }).trim();
+    const gtVersion = execSync('gt version 2>/dev/null', { encoding: 'utf8' }).trim();
+    console.log(`✅ gt installed at ${gtPath}`);
+    console.log(`   Version: ${gtVersion}`);
+  } catch {
+    console.log('❌ gt not found in PATH');
+    console.log('   Install: npm install -g @gastown/gt');
+    console.log('   Or visit: https://github.com/steveyegge/gastown');
+    allGood = false;
+  }
+
+  // Check bd
+  try {
+    execSync('which bd 2>/dev/null', { encoding: 'utf8' });
+    console.log('✅ bd (beads) installed');
+  } catch {
+    console.log('⚠️  bd (beads) not found - some features may not work');
+  }
+
+  // Check gh
+  try {
+    const ghVersion = execSync('gh --version 2>/dev/null | head -1', { encoding: 'utf8' }).trim();
+    console.log(`✅ GitHub CLI: ${ghVersion}`);
+
+    // Check auth
+    try {
+      execSync('gh auth status 2>&1', { encoding: 'utf8' });
+      console.log('   ✅ Authenticated');
+    } catch {
+      console.log('   ⚠️  Not authenticated - run: gh auth login');
+    }
+  } catch {
+    console.log('⚠️  GitHub CLI (gh) not found - PR/issue tracking disabled');
+  }
+
+  // Check GT_ROOT
+  const gtRoot = process.env.GT_ROOT || path.join(process.env.HOME || '', 'gt');
+  if (fs.existsSync(gtRoot)) {
+    console.log(`✅ GT_ROOT exists: ${gtRoot}`);
+    try {
+      const rigs = fs.readdirSync(gtRoot).filter(f => {
+        const fullPath = path.join(gtRoot, f);
+        return fs.statSync(fullPath).isDirectory() && fs.existsSync(path.join(fullPath, 'config.json'));
+      });
+      console.log(`   Found ${rigs.length} rig(s): ${rigs.join(', ') || '(none)'}`);
+    } catch {
+      // Ignore
+    }
+  } else {
+    console.log(`⚠️  GT_ROOT not found: ${gtRoot}`);
+    console.log('   Run: gt install ~/gt');
+  }
+
+  console.log('');
+  if (allGood) {
+    console.log('✅ All prerequisites met! Run: gastown-gui start');
+  } else {
+    console.log('❌ Some prerequisites missing. Fix issues above and try again.');
+    process.exit(1);
+  }
+}
+
+function startServer() {
+  console.log(`Starting Gas Town GUI on http://${options.host}:${options.port}...`);
+
+  const env = {
+    ...process.env,
+    PORT: options.port,
+    HOST: options.host,
+  };
+
+  const serverPath = path.join(packageRoot, 'server.js');
+  const serverArgs = options.dev ? ['--dev'] : [];
+
+  const child = spawn('node', [serverPath, ...serverArgs], {
+    env,
+    stdio: 'inherit',
+    cwd: packageRoot,
+  });
+
+  // Open browser if requested
+  if (options.open) {
+    setTimeout(() => {
+      const url = `http://${options.host}:${options.port}`;
+      const openCmd = process.platform === 'darwin' ? 'open' :
+                      process.platform === 'win32' ? 'start' : 'xdg-open';
+      try {
+        execSync(`${openCmd} ${url}`, { stdio: 'ignore' });
+      } catch {
+        console.log(`Open browser manually: ${url}`);
+      }
+    }, 1500);
+  }
+
+  child.on('error', (err) => {
+    console.error('Failed to start server:', err.message);
+    process.exit(1);
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Handle signals
+  process.on('SIGINT', () => {
+    child.kill('SIGINT');
+  });
+
+  process.on('SIGTERM', () => {
+    child.kill('SIGTERM');
+  });
+}
+
+// Main
+switch (command) {
+  case 'start':
+    startServer();
+    break;
+  case 'version':
+  case '-v':
+  case '--version':
+    showVersion();
+    break;
+  case 'doctor':
+    runDoctor();
+    break;
+  case 'help':
+  case '-h':
+  case '--help':
+    showHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error('Run: gastown-gui help');
+    process.exit(1);
+}