tmux-team 1.1.0 → 2.0.0-alpha.3

package/src/cli.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env tsx
+// ─────────────────────────────────────────────────────────────
+// tmux-team CLI entry point
+// ─────────────────────────────────────────────────────────────
+
+import { createContext, ExitCodes } from './context.js';
+import type { Flags } from './types.js';
+
+// Commands
+import { cmdHelp } from './commands/help.js';
+import { cmdInit } from './commands/init.js';
+import { cmdList } from './commands/list.js';
+import { cmdAdd } from './commands/add.js';
+import { cmdUpdate } from './commands/update.js';
+import { cmdRemove } from './commands/remove.js';
+import { cmdTalk } from './commands/talk.js';
+import { cmdCheck } from './commands/check.js';
+import { cmdCompletion } from './commands/completion.js';
+import { cmdPm } from './pm/commands.js';
+import { cmdConfig } from './commands/config.js';
+import { cmdPreamble } from './commands/preamble.js';
+
+// ─────────────────────────────────────────────────────────────
+// Argument parsing
+// ─────────────────────────────────────────────────────────────
+
+function parseArgs(argv: string[]): { command: string; args: string[]; flags: Flags } {
+  const flags: Flags = {
+    json: false,
+    verbose: false,
+  };
+
+  const positional: string[] = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--verbose' || arg === '-v') {
+      flags.verbose = true;
+    } else if (arg === '--force' || arg === '-f') {
+      flags.force = true;
+    } else if (arg === '--config') {
+      flags.config = argv[++i];
+    } else if (arg === '--delay') {
+      flags.delay = parseTime(argv[++i]);
+    } else if (arg === '--wait') {
+      flags.wait = true;
+    } else if (arg === '--timeout') {
+      flags.timeout = parseTime(argv[++i]);
+    } else if (arg === '--no-preamble') {
+      flags.noPreamble = true;
+    } else if (arg.startsWith('--pane=')) {
+      // Handled in update command
+      positional.push(arg);
+    } else if (arg.startsWith('--remark=')) {
+      // Handled in update command
+      positional.push(arg);
+    } else if (arg.startsWith('-')) {
+      // Unknown flag, pass through
+      positional.push(arg);
+    } else {
+      positional.push(arg);
+    }
+    i++;
+  }
+
+  const [command = 'help', ...args] = positional;
+  return { command, args, flags };
+}
+
+/**
+ * Parse time string to seconds.
+ * Default unit is seconds (no suffix needed).
+ */
+function parseTime(value: string): number {
+  if (!value) return 0;
+
+  const match = value.match(/^(\d+(?:\.\d+)?)(ms|s)?$/i);
+  if (!match) {
+    console.error(
+      `Invalid time format: ${value}. Use number (seconds) or number with ms/s suffix.`
+    );
+    process.exit(ExitCodes.ERROR);
+  }
+
+  const num = parseFloat(match[1]);
+  const unit = (match[2] || 's').toLowerCase();
+
+  if (unit === 'ms') {
+    return num / 1000;
+  }
+  return num; // seconds
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  const { command, args, flags } = parseArgs(argv);
+
+  // Help doesn't need context
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    cmdHelp();
+    process.exit(ExitCodes.SUCCESS);
+  }
+
+  if (command === '--version' || command === '-V') {
+    import('./version.js').then((m) => console.log(m.VERSION));
+    return;
+  }
+
+  // Completion doesn't need context
+  if (command === 'completion') {
+    cmdCompletion(args[0]);
+    process.exit(ExitCodes.SUCCESS);
+  }
+
+  // Create context for all other commands
+  const ctx = createContext({ argv, flags });
+
+  const run = async (): Promise<void> => {
+    switch (command) {
+      case 'init':
+        cmdInit(ctx);
+        break;
+
+      case 'list':
+      case 'ls':
+        cmdList(ctx);
+        break;
+
+      case 'add':
+        if (args.length < 2) {
+          ctx.ui.error('Usage: tmux-team add <name> <pane> [remark]');
+          ctx.exit(ExitCodes.ERROR);
+        }
+        cmdAdd(ctx, args[0], args[1], args[2]);
+        break;
+
+      case 'update':
+        if (args.length < 1) {
+          ctx.ui.error('Usage: tmux-team update <name> --pane <pane> | --remark <remark>');
+          ctx.exit(ExitCodes.ERROR);
+        }
+        {
+          const options: { pane?: string; remark?: string } = {};
+          for (let i = 1; i < args.length; i++) {
+            if (args[i] === '--pane' && args[i + 1]) {
+              options.pane = args[++i];
+            } else if (args[i] === '--remark' && args[i + 1]) {
+              options.remark = args[++i];
+            } else if (args[i].startsWith('--pane=')) {
+              options.pane = args[i].slice(7);
+            } else if (args[i].startsWith('--remark=')) {
+              options.remark = args[i].slice(9);
+            }
+          }
+          cmdUpdate(ctx, args[0], options);
+        }
+        break;
+
+      case 'remove':
+      case 'rm':
+        if (args.length < 1) {
+          ctx.ui.error('Usage: tmux-team remove <name>');
+          ctx.exit(ExitCodes.ERROR);
+        }
+        cmdRemove(ctx, args[0]);
+        break;
+
+      case 'talk':
+      case 'send':
+        if (args.length < 2) {
+          ctx.ui.error('Usage: tmux-team talk <target> <message>');
+          ctx.exit(ExitCodes.ERROR);
+        }
+        await cmdTalk(ctx, args[0], args[1]);
+        break;
+
+      case 'check':
+      case 'read':
+        if (args.length < 1) {
+          ctx.ui.error('Usage: tmux-team check <target> [lines]');
+          ctx.exit(ExitCodes.ERROR);
+        }
+        cmdCheck(ctx, args[0], args[1] ? parseInt(args[1], 10) : undefined);
+        break;
+
+      case 'pm':
+        await cmdPm(ctx, args);
+        break;
+
+      case 'config':
+        cmdConfig(ctx, args);
+        break;
+
+      case 'preamble':
+        cmdPreamble(ctx, args);
+        break;
+
+      default:
+        ctx.ui.error(`Unknown command: ${command}. Run 'tmux-team help' for usage.`);
+        ctx.exit(ExitCodes.ERROR);
+    }
+  };
+
+  run().catch((err) => {
+    if (!flags.json) {
+      console.error(err);
+    } else {
+      console.error(JSON.stringify({ error: String(err?.message ?? err) }));
+    }
+    process.exit(ExitCodes.ERROR);
+  });
+}
+
+main();

package/src/commands/add.ts

@@ -0,0 +1,38 @@
+// ─────────────────────────────────────────────────────────────
+// add command - register a new agent
+// ─────────────────────────────────────────────────────────────
+
+import fs from 'fs';
+import type { Context } from '../types.js';
+import { ExitCodes } from '../exits.js';
+import { saveLocalConfig } from '../config.js';
+
+export function cmdAdd(ctx: Context, name: string, pane: string, remark?: string): void {
+  const { ui, config, paths, flags, exit } = ctx;
+
+  // Create config file if it doesn't exist
+  if (!fs.existsSync(paths.localConfig)) {
+    fs.writeFileSync(paths.localConfig, '{}\n');
+    if (!flags.json) {
+      ui.info(`Created ${paths.localConfig}`);
+    }
+  }
+
+  if (config.paneRegistry[name]) {
+    ui.error(`Agent '${name}' already exists. Use 'tmux-team update' to modify.`);
+    exit(ExitCodes.ERROR);
+  }
+
+  config.paneRegistry[name] = { pane };
+  if (remark) {
+    config.paneRegistry[name].remark = remark;
+  }
+
+  saveLocalConfig(paths, config.paneRegistry);
+
+  if (flags.json) {
+    ui.json({ added: name, pane, remark });
+  } else {
+    ui.success(`Added agent '${name}' at pane ${pane}`);
+  }
+}

package/src/commands/check.ts

@@ -0,0 +1,34 @@
+// ─────────────────────────────────────────────────────────────
+// check command - capture output from agent's pane
+// ─────────────────────────────────────────────────────────────
+
+import type { Context } from '../types.js';
+import { ExitCodes } from '../exits.js';
+import { colors } from '../ui.js';
+
+export function cmdCheck(ctx: Context, target: string, lines?: number): void {
+  const { ui, config, tmux, flags, exit } = ctx;
+
+  if (!config.paneRegistry[target]) {
+    const available = Object.keys(config.paneRegistry).join(', ');
+    ui.error(`Agent '${target}' not found. Available: ${available || 'none'}`);
+    exit(ExitCodes.PANE_NOT_FOUND);
+  }
+
+  const pane = config.paneRegistry[target].pane;
+  const captureLines = lines ?? config.defaults.captureLines;
+
+  try {
+    const output = tmux.capture(pane, captureLines);
+
+    if (flags.json) {
+      ui.json({ target, pane, lines: captureLines, output });
+    } else {
+      console.log(colors.cyan(`─── Output from ${target} (${pane}) ───`));
+      console.log(output);
+    }
+  } catch {
+    ui.error(`Failed to capture pane ${pane}. Is tmux running?`);
+    exit(ExitCodes.ERROR);
+  }
+}

package/src/commands/completion.ts

@@ -0,0 +1,118 @@
+// ─────────────────────────────────────────────────────────────
+// completion command - shell completion scripts
+// ─────────────────────────────────────────────────────────────
+
+import { colors } from '../ui.js';
+
+const zshCompletion = `#compdef tmux-team
+
+_tmux-team() {
+  local -a commands agents
+
+  commands=(
+    'talk:Send message to an agent'
+    'check:Capture output from agent pane'
+    'list:List all configured agents'
+    'add:Add a new agent'
+    'update:Update agent config'
+    'remove:Remove an agent'
+    'init:Create empty tmux-team.json'
+    'completion:Output shell completion script'
+    'help:Show help message'
+  )
+
+  _get_agents() {
+    if [[ -f ./tmux-team.json ]]; then
+      agents=(\${(f)"$(node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync('./tmux-team.json'))).join('\\\\n'))" 2>/dev/null)"})
+    fi
+  }
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'tmux-team commands' commands
+  elif (( CURRENT == 3 )); then
+    case \${words[2]} in
+      talk|check|update|remove|rm)
+        _get_agents
+        if [[ -n "$agents" ]]; then
+          _describe -t agents 'agents' agents
+        fi
+        if [[ "\${words[2]}" == "talk" ]]; then
+          compadd "all"
+        fi
+        ;;
+      completion)
+        compadd "zsh" "bash"
+        ;;
+    esac
+  elif (( CURRENT == 4 )); then
+    case \${words[2]} in
+      update)
+        compadd -- "--pane" "--remark"
+        ;;
+      talk)
+        compadd -- "--delay" "--wait" "--timeout"
+        ;;
+    esac
+  fi
+}
+
+_tmux-team "$@"`;
+
+const bashCompletion = `_tmux_team() {
+  local cur prev commands agents
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  commands="talk check list add update remove init completion help"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "\${commands}" -- \${cur}) )
+  elif [[ \${COMP_CWORD} -eq 2 ]]; then
+    case "\${prev}" in
+      talk|check|update|remove|rm)
+        if [[ -f ./tmux-team.json ]]; then
+          agents=$(node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync('./tmux-team.json'))).join(' '))" 2>/dev/null)
+        fi
+        if [[ "\${prev}" == "talk" ]]; then
+          agents="\${agents} all"
+        fi
+        COMPREPLY=( $(compgen -W "\${agents}" -- \${cur}) )
+        ;;
+      completion)
+        COMPREPLY=( $(compgen -W "zsh bash" -- \${cur}) )
+        ;;
+    esac
+  elif [[ \${COMP_CWORD} -eq 3 ]]; then
+    case "\${COMP_WORDS[1]}" in
+      update)
+        COMPREPLY=( $(compgen -W "--pane --remark" -- \${cur}) )
+        ;;
+      talk)
+        COMPREPLY=( $(compgen -W "--delay --wait --timeout" -- \${cur}) )
+        ;;
+    esac
+  fi
+}
+
+complete -F _tmux_team tmux-team`;
+
+export function cmdCompletion(shell?: string): void {
+  if (shell === 'bash') {
+    console.log(bashCompletion);
+  } else if (shell === 'zsh') {
+    console.log(zshCompletion);
+  } else {
+    console.log(`
+${colors.cyan('Shell Completion Setup')}
+
+${colors.yellow('Zsh')} (add to ~/.zshrc):
+  eval "$(tmux-team completion zsh)"
+
+${colors.yellow('Bash')} (add to ~/.bashrc):
+  eval "$(tmux-team completion bash)"
+
+Then restart your shell or run: source ~/.zshrc (or ~/.bashrc)
+`);
+  }
+}

package/src/commands/config.ts

@@ -0,0 +1,187 @@
+// ─────────────────────────────────────────────────────────────
+// Config command - view and modify settings
+// ─────────────────────────────────────────────────────────────
+
+import type { Context } from '../types.js';
+import { ExitCodes } from '../context.js';
+import {
+  loadGlobalConfig,
+  saveGlobalConfig,
+  loadLocalConfigFile,
+  saveLocalConfigFile,
+  updateLocalSettings,
+  clearLocalSettings,
+} from '../config.js';
+
+type ConfigKey = 'mode' | 'preambleMode';
+
+const VALID_KEYS: ConfigKey[] = ['mode', 'preambleMode'];
+
+const VALID_VALUES: Record<ConfigKey, string[]> = {
+  mode: ['polling', 'wait'],
+  preambleMode: ['always', 'disabled'],
+};
+
+function isValidKey(key: string): key is ConfigKey {
+  return VALID_KEYS.includes(key as ConfigKey);
+}
+
+function isValidValue(key: ConfigKey, value: string): boolean {
+  return VALID_VALUES[key].includes(value);
+}
+
+/**
+ * Show resolved config with source indicators.
+ */
+function showConfig(ctx: Context): void {
+  const globalConfig = loadGlobalConfig(ctx.paths);
+  const localConfigFile = loadLocalConfigFile(ctx.paths);
+  const localSettings = localConfigFile.$config;
+
+  if (ctx.flags.json) {
+    ctx.ui.json({
+      resolved: {
+        mode: ctx.config.mode,
+        preambleMode: ctx.config.preambleMode,
+        defaults: ctx.config.defaults,
+      },
+      sources: {
+        mode: localSettings?.mode ? 'local' : globalConfig.mode ? 'global' : 'default',
+        preambleMode: localSettings?.preambleMode
+          ? 'local'
+          : globalConfig.preambleMode
+            ? 'global'
+            : 'default',
+      },
+      paths: {
+        global: ctx.paths.globalConfig,
+        local: ctx.paths.localConfig,
+      },
+    });
+    return;
+  }
+
+  // Determine sources
+  const modeSource = localSettings?.mode ? '(local)' : globalConfig.mode ? '(global)' : '(default)';
+  const preambleSource = localSettings?.preambleMode
+    ? '(local)'
+    : globalConfig.preambleMode
+      ? '(global)'
+      : '(default)';
+
+  ctx.ui.info('Current configuration:\n');
+  ctx.ui.table(
+    ['Key', 'Value', 'Source'],
+    [
+      ['mode', ctx.config.mode, modeSource],
+      ['preambleMode', ctx.config.preambleMode, preambleSource],
+      ['defaults.timeout', String(ctx.config.defaults.timeout), '(global)'],
+      ['defaults.pollInterval', String(ctx.config.defaults.pollInterval), '(global)'],
+      ['defaults.captureLines', String(ctx.config.defaults.captureLines), '(global)'],
+    ]
+  );
+
+  ctx.ui.info(`\nPaths:`);
+  ctx.ui.info(`  Global: ${ctx.paths.globalConfig}`);
+  ctx.ui.info(`  Local:  ${ctx.paths.localConfig}`);
+}
+
+/**
+ * Set a config value.
+ */
+function setConfig(ctx: Context, key: string, value: string, global: boolean): void {
+  if (!isValidKey(key)) {
+    ctx.ui.error(`Invalid key: ${key}. Valid keys: ${VALID_KEYS.join(', ')}`);
+    ctx.exit(ExitCodes.ERROR);
+  }
+
+  if (!isValidValue(key, value)) {
+    ctx.ui.error(
+      `Invalid value for ${key}: ${value}. Valid values: ${VALID_VALUES[key].join(', ')}`
+    );
+    ctx.exit(ExitCodes.ERROR);
+  }
+
+  if (global) {
+    // Set in global config
+    const globalConfig = loadGlobalConfig(ctx.paths);
+    if (key === 'mode') {
+      globalConfig.mode = value as 'polling' | 'wait';
+    } else if (key === 'preambleMode') {
+      globalConfig.preambleMode = value as 'always' | 'disabled';
+    }
+    saveGlobalConfig(ctx.paths, globalConfig);
+    ctx.ui.success(`Set ${key}=${value} in global config`);
+  } else {
+    // Set in local config
+    if (key === 'mode') {
+      updateLocalSettings(ctx.paths, { mode: value as 'polling' | 'wait' });
+    } else if (key === 'preambleMode') {
+      updateLocalSettings(ctx.paths, { preambleMode: value as 'always' | 'disabled' });
+    }
+    ctx.ui.success(`Set ${key}=${value} in local config (repo override)`);
+  }
+}
+
+/**
+ * Clear local config override.
+ */
+function clearConfig(ctx: Context, key?: string): void {
+  if (key) {
+    if (!isValidKey(key)) {
+      ctx.ui.error(`Invalid key: ${key}. Valid keys: ${VALID_KEYS.join(', ')}`);
+      ctx.exit(ExitCodes.ERROR);
+    }
+
+    // Clear specific key from local settings
+    const localConfigFile = loadLocalConfigFile(ctx.paths);
+    if (localConfigFile.$config) {
+      delete localConfigFile.$config[key];
+      // Remove $config if empty
+      if (Object.keys(localConfigFile.$config).length === 0) {
+        delete localConfigFile.$config;
+      }
+      saveLocalConfigFile(ctx.paths, localConfigFile);
+    }
+    ctx.ui.success(`Cleared local override for ${key}`);
+  } else {
+    // Clear all local settings
+    clearLocalSettings(ctx.paths);
+    ctx.ui.success('Cleared all local config overrides');
+  }
+}
+
+/**
+ * Config command entry point.
+ */
+export function cmdConfig(ctx: Context, args: string[]): void {
+  const subcommand = args[0];
+
+  // Parse --global flag
+  const globalFlag = args.includes('--global') || args.includes('-g');
+  const filteredArgs = args.filter((a) => a !== '--global' && a !== '-g');
+
+  switch (subcommand) {
+    case undefined:
+    case 'show':
+      showConfig(ctx);
+      break;
+
+    case 'set':
+      if (filteredArgs.length < 3) {
+        ctx.ui.error('Usage: tmux-team config set <key> <value> [--global]');
+        ctx.exit(ExitCodes.ERROR);
+      }
+      setConfig(ctx, filteredArgs[1], filteredArgs[2], globalFlag);
+      break;
+
+    case 'clear':
+      clearConfig(ctx, filteredArgs[1]);
+      break;
+
+    default:
+      ctx.ui.error(`Unknown config subcommand: ${subcommand}`);
+      ctx.ui.error('Usage: tmux-team config [show|set|clear]');
+      ctx.exit(ExitCodes.ERROR);
+  }
+}

package/src/commands/help.ts

@@ -0,0 +1,66 @@
+// ─────────────────────────────────────────────────────────────
+// help command - show usage information
+// ─────────────────────────────────────────────────────────────
+
+import { colors } from '../ui.js';
+import { VERSION } from '../version.js';
+
+export function cmdHelp(): void {
+  console.log(`
+${colors.cyan('tmux-team')} v${VERSION} - AI agent collaboration in tmux
+
+${colors.yellow('USAGE')}
+  tmux-team <command> [arguments]
+
+${colors.yellow('COMMANDS')}
+  ${colors.green('talk')} <target> <message>     Send message to an agent (or "all")
+  ${colors.green('check')} <target> [lines]      Capture output from agent's pane
+  ${colors.green('list')}                        List all configured agents
+  ${colors.green('add')} <name> <pane> [remark]  Add a new agent
+  ${colors.green('update')} <name> [options]     Update an agent's config
+  ${colors.green('remove')} <name>               Remove an agent
+  ${colors.green('init')}                        Create empty tmux-team.json
+  ${colors.green('config')} [show|set|clear]     View/modify settings
+  ${colors.green('preamble')} [show|set|clear]   Manage agent preambles
+  ${colors.green('pm')} <subcommand>             Project management (run 'pm help')
+  ${colors.green('completion')}                  Output shell completion script
+  ${colors.green('help')}                        Show this help message
+
+${colors.yellow('OPTIONS')}
+  ${colors.green('--json')}                      Output in JSON format
+  ${colors.green('--verbose')}                   Show detailed output
+  ${colors.green('--force')}                     Skip warnings
+
+${colors.yellow('TALK OPTIONS')} ${colors.dim('(v2)')}
+  ${colors.green('--delay')} <seconds>           Wait before sending (default: seconds)
+  ${colors.green('--wait')}                      Wait for agent response (nonce-based)
+  ${colors.green('--timeout')} <seconds>         Max wait time (default: 60)
+  ${colors.green('--no-preamble')}               Skip agent preamble for this message
+
+${colors.yellow('EXAMPLES')}
+  tmux-team talk codex "Please review the PR"
+  tmux-team talk all "Sync meeting in 5 minutes"
+  tmux-team check gemini 50
+  tmux-team list --json
+  tmux-team add codex 10.1 "Code review specialist"
+  tmux-team update codex --pane 10.2
+  tmux-team remove codex
+
+${colors.yellow('CONFIG')}
+  Local:  ./tmux-team.json (pane registry + $config override)
+  Global: ~/.config/tmux-team/config.json (settings)
+
+${colors.yellow('CONFIG EXAMPLES')}
+  tmux-team config                     Show current settings
+  tmux-team config set mode wait       Set mode in local config (repo override)
+  tmux-team config set mode polling --global  Set mode in global config
+  tmux-team config clear mode          Clear local override for mode
+  tmux-team config clear               Clear all local overrides
+
+${colors.yellow('PREAMBLE EXAMPLES')}
+  tmux-team preamble                   Show all preambles
+  tmux-team preamble show codex        Show preamble for codex
+  tmux-team preamble set codex "You are a code reviewer. Be concise."
+  tmux-team preamble clear codex       Clear preamble for codex
+`);
+}

package/src/commands/init.ts

@@ -0,0 +1,24 @@
+// ─────────────────────────────────────────────────────────────
+// init command - create tmux-team.json
+// ─────────────────────────────────────────────────────────────
+
+import fs from 'fs';
+import type { Context } from '../types.js';
+import { ExitCodes } from '../exits.js';
+
+export function cmdInit(ctx: Context): void {
+  const { ui, paths, flags, exit } = ctx;
+
+  if (fs.existsSync(paths.localConfig)) {
+    ui.error(`${paths.localConfig} already exists. Remove it first if you want to reinitialize.`);
+    exit(ExitCodes.ERROR);
+  }
+
+  fs.writeFileSync(paths.localConfig, '{}\n');
+
+  if (flags.json) {
+    ui.json({ created: paths.localConfig });
+  } else {
+    ui.success(`Created ${paths.localConfig}`);
+  }
+}