Merge pull request #26 from web3dev1337/fix/issue-25-gt-path

fix: resolve Homebrew gt path and prevent activity-feed ENOENT crash

Author: web3dev1337

CODEBASE_DOCUMENTATION.md

@@ -65,6 +65,7 @@ server/infrastructure/CommandRunner.js - Safe child_process.execFile wrapper
 
 server/infrastructure/CacheRegistry.js - TTL cache for CLI output
 server/infrastructure/EventBus.js - Internal pub/sub for cache invalidation
+server/infrastructure/ExecutableResolver.js - Resolves gt/bd binaries from PATH, env overrides, and Homebrew/Linuxbrew fallback paths
 ```
 
 ## Backend — Services
@@ -161,6 +162,7 @@ test/e2e.test.js - Puppeteer browser tests (real server + browser)
 test/integration.test.js - Legacy integration tests
 test/integration/endpoints.test.js - API endpoint contract tests
 test/integration/cli-compatibility.test.js - Real server + stubbed CLI coverage for gt/bd old/new command fallback behavior
+test/integration/cli-executable-resolution.test.js - Real server coverage for gt/bd executable path resolution and missing-gt activity-stream crash prevention
 test/integration/rig-parsing-fallback.test.js - Real server + stubbed CLI coverage for rig list fallback/emoji parsing
 test/integration/websocket.test.js - WebSocket lifecycle tests
 test/integration/cache.test.js - Cache invalidation tests
@@ -173,6 +175,7 @@ test/unit/ - 32 unit test files covering:
 ├─ Infrastructure: cacheRegistry, commandRunner, eventBus
 ├─ Services: statusService, targetService, githubService, convoyService,
 │            formulaService, beadService, workService
+├─ CLI resolution: executableResolver
 ├─ Routes: statusRoutes, targetRoutes, githubRoutes, convoyRoutes,
 │          formulaRoutes, beadRoutes, workRoutes
 ├─ Frontend: state, htmlUtils, quoteArg, formattingTime, animationsShared,

README.md

@@ -177,6 +177,8 @@ gastown-gui help
 | `GASTOWN_PORT` | Server port | 7667 |
 | `HOST` | Server host | 127.0.0.1 |
 | `GT_ROOT` | Gas Town root directory | ~/gt |
+| `GT_BIN` | Override `gt` executable path | auto-detect (`PATH`, `/opt/homebrew/bin/gt`, `/usr/local/bin/gt`) |
+| `BD_BIN` | Override `bd` executable path | auto-detect (`PATH`, `/opt/homebrew/bin/bd`, `/usr/local/bin/bd`) |
 
 ---
 

server.js

@@ -32,6 +32,11 @@ import {
 import { AgentPath } from './server/domain/values/AgentPath.js';
 import { CommandRunner } from './server/infrastructure/CommandRunner.js';
 import { CacheRegistry } from './server/infrastructure/CacheRegistry.js';
+import {
+  DEFAULT_BD_FALLBACK_PATHS,
+  DEFAULT_GT_FALLBACK_PATHS,
+  resolveExecutable,
+} from './server/infrastructure/ExecutableResolver.js';
 import { BDGateway } from './server/gateways/BDGateway.js';
 import { GTGateway } from './server/gateways/GTGateway.js';
 import { GitHubGateway } from './server/gateways/GitHubGateway.js';
@@ -60,10 +65,20 @@ const PORT = process.env.GASTOWN_PORT || 7667;
 const HOST = process.env.HOST || '127.0.0.1';
 const HOME = process.env.HOME || os.homedir();
 const GT_ROOT = process.env.GT_ROOT || path.join(HOME, 'gt');
+const GT_EXECUTABLE = resolveExecutable({
+  command: 'gt',
+  envVarName: 'GT_BIN',
+  fallbackPaths: DEFAULT_GT_FALLBACK_PATHS,
+});
+const BD_EXECUTABLE = resolveExecutable({
+  command: 'bd',
+  envVarName: 'BD_BIN',
+  fallbackPaths: DEFAULT_BD_FALLBACK_PATHS,
+});
 
 const commandRunner = new CommandRunner();
-const gtGateway = new GTGateway({ runner: commandRunner, gtRoot: GT_ROOT });
-const bdGateway = new BDGateway({ runner: commandRunner, gtRoot: GT_ROOT });
+const gtGateway = new GTGateway({ runner: commandRunner, gtRoot: GT_ROOT, executable: GT_EXECUTABLE });
+const bdGateway = new BDGateway({ runner: commandRunner, gtRoot: GT_ROOT, executable: BD_EXECUTABLE });
 const tmuxGateway = new TmuxGateway({ runner: commandRunner });
 const backendCache = new CacheRegistry();
 const convoyService = new ConvoyService({
@@ -467,11 +482,11 @@ async function getPolecatOutput(sessionName, lines = 50) {
 
 // Execute a Gas Town command
 async function executeGT(args, options = {}) {
-  const cmd = `gt ${args.join(' ')}`;
+  const cmd = `${GT_EXECUTABLE} ${args.join(' ')}`;
   console.log(`[GT] Executing: ${cmd}`);
 
   try {
-    const { stdout, stderr } = await execFileAsync('gt', args, {
+    const { stdout, stderr } = await execFileAsync(GT_EXECUTABLE, args, {
       cwd: options.cwd || GT_ROOT,
       timeout: options.timeout || 30000,
       env: { ...process.env, ...options.env }
@@ -506,14 +521,14 @@ async function executeGT(args, options = {}) {
 
 // Execute a Beads command
 async function executeBD(args, options = {}) {
-  const cmd = `bd ${args.join(' ')}`;
+  const cmd = `${BD_EXECUTABLE} ${args.join(' ')}`;
   console.log(`[BD] Executing: ${cmd}`);
 
   // Set BEADS_DIR to ensure bd finds the database
   const beadsDir = path.join(GT_ROOT, '.beads');
 
   try {
-    const { stdout } = await execFileAsync('bd', args, {
+    const { stdout } = await execFileAsync(BD_EXECUTABLE, args, {
       cwd: options.cwd || GT_ROOT,
       timeout: options.timeout || 30000,
       env: { ...process.env, BEADS_DIR: beadsDir }
@@ -1174,7 +1189,7 @@ app.get('/api/setup/status', async (req, res) => {
 
   // Check gt
   try {
-    const gtResult = await execFileAsync('gt', ['version'], { timeout: 5000 });
+    const gtResult = await execFileAsync(GT_EXECUTABLE, ['version'], { timeout: 5000 });
     status.gt_installed = true;
     status.gt_version = String(gtResult.stdout || '').trim().split('\n')[0];
   } catch {
@@ -1183,7 +1198,7 @@ app.get('/api/setup/status', async (req, res) => {
 
   // Check bd
   try {
-    const bdResult = await execFileAsync('bd', ['version'], { timeout: 5000 });
+    const bdResult = await execFileAsync(BD_EXECUTABLE, ['version'], { timeout: 5000 });
     status.bd_installed = true;
     status.bd_version = String(bdResult.stdout || '').trim().split('\n')[0];
   } catch {
@@ -1713,14 +1728,26 @@ registerGitHubRoutes(app, { gitHubService });
 
 // Start activity stream
 let activityProcess = null;
+let activityRestartTimer = null;
+
+function scheduleActivityRestart() {
+  if (clients.size === 0) return;
+  if (activityRestartTimer) return;
+  activityRestartTimer = setTimeout(() => {
+    activityRestartTimer = null;
+    if (clients.size > 0) {
+      startActivityStream();
+    }
+  }, 5000);
+}
 
 function startActivityStream() {
   if (activityProcess) return;
 
   console.log('[WS] Starting activity stream...');
 
   // Use gt feed for comprehensive activity (beads + gt events + convoys)
-  activityProcess = spawn('gt', ['feed', '--plain', '--follow'], {
+  activityProcess = spawn(GT_EXECUTABLE, ['feed', '--plain', '--follow'], {
     cwd: GT_ROOT
   });
 
@@ -1738,13 +1765,16 @@ function startActivityStream() {
     console.error(`[BD Activity] stderr: ${data}`);
   });
 
+  activityProcess.on('error', (error) => {
+    console.error(`[BD Activity] Process error: ${error.message}`);
+    activityProcess = null;
+    scheduleActivityRestart();
+  });
+
   activityProcess.on('close', (code) => {
     console.log(`[BD Activity] Process exited with code ${code}`);
     activityProcess = null;
-    // Restart after delay if clients connected
-    if (clients.size > 0) {
-      setTimeout(startActivityStream, 5000);
-    }
+    scheduleActivityRestart();
   });
 }
 
@@ -1816,9 +1846,15 @@ wss.on('connection', (ws) => {
     clients.delete(ws);
 
     // Stop activity stream if no clients
-    if (clients.size === 0 && activityProcess) {
-      activityProcess.kill();
-      activityProcess = null;
+    if (clients.size === 0) {
+      if (activityRestartTimer) {
+        clearTimeout(activityRestartTimer);
+        activityRestartTimer = null;
+      }
+      if (activityProcess) {
+        activityProcess.kill();
+        activityProcess = null;
+      }
     }
   });
 

server/gateways/BDGateway.js

@@ -9,18 +9,19 @@ function parseJsonOrNull(text) {
 }
 
 export class BDGateway {
-  constructor({ runner, gtRoot }) {
+  constructor({ runner, gtRoot, executable = 'bd' }) {
     if (!runner?.exec) throw new Error('BDGateway requires a runner with exec()');
     if (!gtRoot) throw new Error('BDGateway requires gtRoot');
     this._runner = runner;
     this._gtRoot = gtRoot;
+    this._executable = executable;
     this._beadsDir = path.join(gtRoot, '.beads');
     this._supportsNoDaemon = null;
   }
 
   async exec(args, options = {}) {
     const env = { BEADS_DIR: this._beadsDir, ...(options.env ?? {}) };
-    return this._runner.exec('bd', args, { cwd: this._gtRoot, ...options, env });
+    return this._runner.exec(this._executable, args, { cwd: this._gtRoot, ...options, env });
   }
 
   _resultText(result) {

server/gateways/GTGateway.js

@@ -7,15 +7,16 @@ function parseJsonOrNull(text) {
 }
 
 export class GTGateway {
-  constructor({ runner, gtRoot }) {
+  constructor({ runner, gtRoot, executable = 'gt' }) {
     if (!runner?.exec) throw new Error('GTGateway requires a runner with exec()');
     if (!gtRoot) throw new Error('GTGateway requires gtRoot');
     this._runner = runner;
     this._gtRoot = gtRoot;
+    this._executable = executable;
   }
 
   async exec(args, options = {}) {
-    return this._runner.exec('gt', args, { cwd: this._gtRoot, ...options });
+    return this._runner.exec(this._executable, args, { cwd: this._gtRoot, ...options });
   }
 
   async status({ fast = true, allowExitCodes } = {}) {

server/infrastructure/ExecutableResolver.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_GT_FALLBACK_PATHS = [
+  '/opt/homebrew/bin/gt',
+  '/usr/local/bin/gt',
+  '/home/linuxbrew/.linuxbrew/bin/gt',
+];
+
+export const DEFAULT_BD_FALLBACK_PATHS = [
+  '/opt/homebrew/bin/bd',
+  '/usr/local/bin/bd',
+  '/home/linuxbrew/.linuxbrew/bin/bd',
+];
+
+function hasPathSeparator(value) {
+  return value.includes('/') || value.includes('\\');
+}
+
+function canExecute(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function executableFromPath(command, env) {
+  const pathValue = env.PATH || '';
+  const dirs = pathValue.split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, command);
+    if (canExecute(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function resolveExecutable({
+  command,
+  envVarName,
+  fallbackPaths = [],
+  env = process.env,
+} = {}) {
+  if (!command) throw new Error('resolveExecutable requires command');
+
+  const override = envVarName ? String(env[envVarName] || '').trim() : '';
+  if (override) {
+    if (canExecute(override)) return override;
+    throw new Error(`${envVarName} is set but is not executable: ${override}`);
+  }
+
+  if (hasPathSeparator(command) && canExecute(command)) {
+    return command;
+  }
+
+  const fromPath = executableFromPath(command, env);
+  if (fromPath) return fromPath;
+
+  for (const candidate of fallbackPaths) {
+    if (canExecute(candidate)) return candidate;
+  }
+
+  return command;
+}