tmux-team 1.0.0 → 2.0.0-alpha.1

package/src/pm/types.ts

@@ -0,0 +1,79 @@
+// ─────────────────────────────────────────────────────────────
+// Project Management types
+// ─────────────────────────────────────────────────────────────
+
+export type TaskStatus = 'pending' | 'in_progress' | 'done';
+export type MilestoneStatus = 'pending' | 'in_progress' | 'done';
+
+export interface Team {
+  id: string;
+  name: string;
+  windowId?: string;
+  createdAt: string;
+}
+
+export interface Milestone {
+  id: string;
+  name: string;
+  status: MilestoneStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  milestone?: string;
+  status: TaskStatus;
+  assignee?: string;
+  docPath?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AuditEvent {
+  event: string;
+  id: string;
+  actor: string;
+  ts: string;
+  [key: string]: unknown;
+}
+
+export interface CreateTaskInput {
+  title: string;
+  milestone?: string;
+  assignee?: string;
+}
+
+export interface UpdateTaskInput {
+  status?: TaskStatus;
+  assignee?: string;
+  title?: string;
+  milestone?: string;
+}
+
+export interface CreateMilestoneInput {
+  name: string;
+}
+
+export interface UpdateMilestoneInput {
+  name?: string;
+  status?: MilestoneStatus;
+}
+
+export interface ListTasksFilter {
+  milestone?: string;
+  status?: TaskStatus;
+  assignee?: string;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Storage backend configuration
+// ─────────────────────────────────────────────────────────────
+
+export type StorageBackend = 'fs' | 'github';
+
+export interface TeamConfig {
+  backend: StorageBackend;
+  repo?: string; // GitHub repo (owner/repo format) for github backend
+}

package/src/state.test.ts

@@ -0,0 +1,311 @@
+// ─────────────────────────────────────────────────────────────
+// State Tests - Request tracking and TTL cleanup
+// ─────────────────────────────────────────────────────────────
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import type { Paths } from './types.js';
+import {
+  loadState,
+  saveState,
+  cleanupState,
+  setActiveRequest,
+  clearActiveRequest,
+  type AgentRequestState,
+} from './state.js';
+
+describe('State Management', () => {
+  let testDir: string;
+  let paths: Paths;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmux-team-state-test-'));
+    paths = {
+      globalDir: testDir,
+      globalConfig: path.join(testDir, 'config.json'),
+      localConfig: path.join(testDir, 'tmux-team.json'),
+      stateFile: path.join(testDir, 'state.json'),
+    };
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('loadState', () => {
+    it('returns empty state when state.json does not exist', () => {
+      const state = loadState(paths);
+      expect(state.requests).toEqual({});
+    });
+
+    it('loads existing state from state.json', () => {
+      const existingState = {
+        requests: {
+          claude: { id: 'req-1', nonce: 'abc123', pane: '1.0', startedAtMs: 1000 },
+        },
+      };
+      fs.writeFileSync(paths.stateFile, JSON.stringify(existingState));
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeDefined();
+      expect(state.requests.claude?.nonce).toBe('abc123');
+    });
+
+    it('returns empty state when state.json is corrupted', () => {
+      fs.writeFileSync(paths.stateFile, 'not valid json');
+
+      const state = loadState(paths);
+      expect(state.requests).toEqual({});
+    });
+
+    it('returns empty state when state.json has invalid structure', () => {
+      fs.writeFileSync(paths.stateFile, JSON.stringify({ invalid: true }));
+
+      const state = loadState(paths);
+      expect(state.requests).toEqual({});
+    });
+  });
+
+  describe('saveState', () => {
+    it('writes state to state.json', () => {
+      const state = {
+        requests: {
+          claude: { id: 'req-1', nonce: 'xyz', pane: '1.0', startedAtMs: 2000 },
+        },
+      };
+
+      saveState(paths, state);
+
+      expect(fs.existsSync(paths.stateFile)).toBe(true);
+      const saved = JSON.parse(fs.readFileSync(paths.stateFile, 'utf-8'));
+      expect(saved.requests.claude.nonce).toBe('xyz');
+    });
+
+    it('creates globalDir if it does not exist', () => {
+      fs.rmSync(testDir, { recursive: true, force: true });
+      expect(fs.existsSync(testDir)).toBe(false);
+
+      saveState(paths, { requests: {} });
+
+      expect(fs.existsSync(testDir)).toBe(true);
+    });
+  });
+
+  describe('cleanupState', () => {
+    it('removes entries older than TTL', () => {
+      const oldTime = Date.now() - 120 * 1000; // 2 minutes ago
+      const state = {
+        requests: {
+          oldAgent: { id: 'old', nonce: 'old', pane: '1.0', startedAtMs: oldTime },
+        },
+      };
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(paths.stateFile, JSON.stringify(state));
+
+      const cleaned = cleanupState(paths, 60); // 60 second TTL
+
+      expect(cleaned.requests.oldAgent).toBeUndefined();
+    });
+
+    it('keeps entries within TTL', () => {
+      const recentTime = Date.now() - 30 * 1000; // 30 seconds ago
+      const state = {
+        requests: {
+          recentAgent: { id: 'new', nonce: 'new', pane: '1.0', startedAtMs: recentTime },
+        },
+      };
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(paths.stateFile, JSON.stringify(state));
+
+      const cleaned = cleanupState(paths, 60); // 60 second TTL
+
+      expect(cleaned.requests.recentAgent).toBeDefined();
+    });
+
+    it('requires ttlSeconds parameter', () => {
+      // TypeScript enforces this - the function requires ttlSeconds
+      // This test just verifies the behavior with different TTL values
+      const now = Date.now();
+      const state = {
+        requests: {
+          agent1: { id: '1', nonce: 'a', pane: '1.0', startedAtMs: now - 5000 }, // 5s ago
+          agent2: { id: '2', nonce: 'b', pane: '1.1', startedAtMs: now - 15000 }, // 15s ago
+        },
+      };
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(paths.stateFile, JSON.stringify(state));
+
+      // With 10s TTL, agent1 should be kept, agent2 removed
+      const cleaned = cleanupState(paths, 10);
+
+      expect(cleaned.requests.agent1).toBeDefined();
+      expect(cleaned.requests.agent2).toBeUndefined();
+    });
+
+    it('handles entries with missing startedAtMs', () => {
+      const state = {
+        requests: {
+          badAgent: { id: 'bad', nonce: 'bad', pane: '1.0' } as AgentRequestState,
+        },
+      };
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(paths.stateFile, JSON.stringify(state));
+
+      const cleaned = cleanupState(paths, 60);
+
+      // Entry with invalid startedAtMs is removed
+      expect(cleaned.requests.badAgent).toBeUndefined();
+    });
+
+    it('only rewrites file if entries were removed', () => {
+      const recentTime = Date.now();
+      const state = {
+        requests: {
+          agent: { id: '1', nonce: 'a', pane: '1.0', startedAtMs: recentTime },
+        },
+      };
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(paths.stateFile, JSON.stringify(state));
+      const originalMtime = fs.statSync(paths.stateFile).mtimeMs;
+
+      // Wait a tiny bit then cleanup (nothing should change)
+      cleanupState(paths, 3600);
+
+      const newMtime = fs.statSync(paths.stateFile).mtimeMs;
+      // File should not have been rewritten
+      expect(newMtime).toBe(originalMtime);
+    });
+  });
+
+  describe('setActiveRequest', () => {
+    it('adds new request to state', () => {
+      const req: AgentRequestState = {
+        id: 'req-1',
+        nonce: 'nonce123',
+        pane: '1.0',
+        startedAtMs: Date.now(),
+      };
+
+      setActiveRequest(paths, 'claude', req);
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeDefined();
+      expect(state.requests.claude?.id).toBe('req-1');
+    });
+
+    it('stores request with id, nonce, pane, and startedAtMs', () => {
+      const req: AgentRequestState = {
+        id: 'test-id',
+        nonce: 'test-nonce',
+        pane: '2.1',
+        startedAtMs: 1234567890,
+      };
+
+      setActiveRequest(paths, 'codex', req);
+
+      const state = loadState(paths);
+      expect(state.requests.codex?.id).toBe('test-id');
+      expect(state.requests.codex?.nonce).toBe('test-nonce');
+      expect(state.requests.codex?.pane).toBe('2.1');
+      expect(state.requests.codex?.startedAtMs).toBe(1234567890);
+    });
+
+    it('overwrites existing request for same agent', () => {
+      const req1: AgentRequestState = {
+        id: 'old',
+        nonce: 'old-nonce',
+        pane: '1.0',
+        startedAtMs: 1000,
+      };
+      const req2: AgentRequestState = {
+        id: 'new',
+        nonce: 'new-nonce',
+        pane: '1.0',
+        startedAtMs: 2000,
+      };
+
+      setActiveRequest(paths, 'claude', req1);
+      setActiveRequest(paths, 'claude', req2);
+
+      const state = loadState(paths);
+      expect(state.requests.claude?.id).toBe('new');
+      expect(state.requests.claude?.nonce).toBe('new-nonce');
+    });
+
+    it('preserves other agents when adding new one', () => {
+      const req1: AgentRequestState = { id: '1', nonce: 'a', pane: '1.0', startedAtMs: 1000 };
+      const req2: AgentRequestState = { id: '2', nonce: 'b', pane: '1.1', startedAtMs: 2000 };
+
+      setActiveRequest(paths, 'claude', req1);
+      setActiveRequest(paths, 'codex', req2);
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeDefined();
+      expect(state.requests.codex).toBeDefined();
+    });
+  });
+
+  describe('clearActiveRequest', () => {
+    it('removes agent request from state', () => {
+      const req: AgentRequestState = { id: '1', nonce: 'a', pane: '1.0', startedAtMs: 1000 };
+      setActiveRequest(paths, 'claude', req);
+
+      clearActiveRequest(paths, 'claude');
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeUndefined();
+    });
+
+    it('does nothing if agent has no active request', () => {
+      // Should not throw
+      const stateBefore = loadState(paths);
+      const countBefore = Object.keys(stateBefore.requests).length;
+
+      clearActiveRequest(paths, 'nonexistent');
+
+      const stateAfter = loadState(paths);
+      const countAfter = Object.keys(stateAfter.requests).length;
+
+      // Count should be unchanged (no error, no modification)
+      expect(countAfter).toBe(countBefore);
+    });
+
+    it('only clears if requestId matches when provided', () => {
+      const req: AgentRequestState = { id: 'req-1', nonce: 'a', pane: '1.0', startedAtMs: 1000 };
+      setActiveRequest(paths, 'claude', req);
+
+      // Try to clear with wrong requestId
+      clearActiveRequest(paths, 'claude', 'wrong-id');
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeDefined(); // Should still exist
+    });
+
+    it('clears when requestId matches', () => {
+      const req: AgentRequestState = { id: 'req-1', nonce: 'a', pane: '1.0', startedAtMs: 1000 };
+      setActiveRequest(paths, 'claude', req);
+
+      clearActiveRequest(paths, 'claude', 'req-1');
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeUndefined();
+    });
+
+    it('preserves other agents when clearing one', () => {
+      const req1: AgentRequestState = { id: '1', nonce: 'a', pane: '1.0', startedAtMs: 1000 };
+      const req2: AgentRequestState = { id: '2', nonce: 'b', pane: '1.1', startedAtMs: 2000 };
+      setActiveRequest(paths, 'claude', req1);
+      setActiveRequest(paths, 'codex', req2);
+
+      clearActiveRequest(paths, 'claude');
+
+      const state = loadState(paths);
+      expect(state.requests.claude).toBeUndefined();
+      expect(state.requests.codex).toBeDefined();
+    });
+  });
+});

package/src/state.ts

@@ -0,0 +1,83 @@
+// ─────────────────────────────────────────────────────────────
+// State management for wait-mode requests (soft locks + cleanup)
+// ─────────────────────────────────────────────────────────────
+
+import fs from 'fs';
+import type { Paths } from './types.js';
+import { ensureGlobalDir } from './config.js';
+
+export interface AgentRequestState {
+  id: string;
+  nonce: string;
+  pane: string;
+  startedAtMs: number;
+}
+
+export interface StateFile {
+  requests: Record<string, AgentRequestState>;
+}
+
+const DEFAULT_STATE: StateFile = { requests: {} };
+
+function safeParseJson<T>(text: string): T | null {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function loadState(paths: Paths): StateFile {
+  ensureGlobalDir(paths);
+
+  if (!fs.existsSync(paths.stateFile)) {
+    return { ...DEFAULT_STATE };
+  }
+
+  const raw = fs.readFileSync(paths.stateFile, 'utf-8');
+  const parsed = safeParseJson<StateFile>(raw);
+  if (!parsed || typeof parsed !== 'object' || !parsed.requests) {
+    return { ...DEFAULT_STATE };
+  }
+  return parsed;
+}
+
+export function saveState(paths: Paths, state: StateFile): void {
+  ensureGlobalDir(paths);
+  fs.writeFileSync(paths.stateFile, JSON.stringify(state, null, 2) + '\n');
+}
+
+export function cleanupState(paths: Paths, ttlSeconds: number): StateFile {
+  const state = loadState(paths);
+  const now = Date.now();
+
+  const ttlMs = Math.max(1, ttlSeconds) * 1000;
+  const next: StateFile = { requests: {} };
+
+  for (const [agent, req] of Object.entries(state.requests)) {
+    if (!req || typeof req.startedAtMs !== 'number') continue;
+    if (now - req.startedAtMs <= ttlMs) {
+      next.requests[agent] = req;
+    }
+  }
+
+  // Only rewrite if it changed materially
+  if (Object.keys(next.requests).length !== Object.keys(state.requests).length) {
+    saveState(paths, next);
+  }
+  return next;
+}
+
+export function setActiveRequest(paths: Paths, agent: string, req: AgentRequestState): void {
+  const state = loadState(paths);
+  state.requests[agent] = req;
+  saveState(paths, state);
+}
+
+export function clearActiveRequest(paths: Paths, agent: string, requestId?: string): void {
+  const state = loadState(paths);
+  if (!state.requests[agent]) return;
+  if (requestId && state.requests[agent]?.id !== requestId) return;
+  delete state.requests[agent];
+  saveState(paths, state);
+}

package/src/tmux.test.ts

@@ -0,0 +1,205 @@
+// ─────────────────────────────────────────────────────────────
+// Tmux Wrapper Tests - send-keys, capture-pane
+// ─────────────────────────────────────────────────────────────
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { execSync } from 'child_process';
+import { createTmux } from './tmux.js';
+
+// Mock child_process
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+const mockedExecSync = vi.mocked(execSync);
+
+describe('createTmux', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('send', () => {
+    it('calls tmux send-keys with pane ID and message', () => {
+      const tmux = createTmux();
+
+      tmux.send('1.0', 'Hello world');
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        'tmux send-keys -t "1.0" "Hello world"',
+        expect.any(Object)
+      );
+    });
+
+    it('sends Enter key after message', () => {
+      const tmux = createTmux();
+
+      tmux.send('1.0', 'Hello');
+
+      expect(mockedExecSync).toHaveBeenCalledTimes(2);
+      expect(mockedExecSync).toHaveBeenNthCalledWith(
+        2,
+        'tmux send-keys -t "1.0" Enter',
+        expect.any(Object)
+      );
+    });
+
+    it('escapes special characters in message', () => {
+      const tmux = createTmux();
+
+      tmux.send('1.0', 'Hello "world" with \'quotes\'');
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.stringContaining('"Hello \\"world\\" with \'quotes\'"'),
+        expect.any(Object)
+      );
+    });
+
+    it('handles newlines in message', () => {
+      const tmux = createTmux();
+
+      tmux.send('1.0', 'Line 1\nLine 2');
+
+      // JSON.stringify escapes newlines as \n
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.stringContaining('"Line 1\\nLine 2"'),
+        expect.any(Object)
+      );
+    });
+
+    it('throws when pane does not exist', () => {
+      const error = new Error("can't find pane: 99.99");
+      mockedExecSync.mockImplementationOnce(() => {
+        throw error;
+      });
+
+      const tmux = createTmux();
+
+      expect(() => tmux.send('99.99', 'Hello')).toThrow("can't find pane: 99.99");
+    });
+
+    it('uses pipe stdio to suppress output', () => {
+      const tmux = createTmux();
+
+      tmux.send('1.0', 'Hello');
+
+      expect(mockedExecSync).toHaveBeenCalledWith(expect.any(String), { stdio: 'pipe' });
+    });
+  });
+
+  describe('capture', () => {
+    it('calls tmux capture-pane with pane ID and line count', () => {
+      mockedExecSync.mockReturnValue('captured output');
+      const tmux = createTmux();
+
+      tmux.capture('1.0', 100);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        'tmux capture-pane -t "1.0" -p -S -100',
+        expect.any(Object)
+      );
+    });
+
+    it('returns captured pane content', () => {
+      const expectedOutput = 'Line 1\nLine 2\nLine 3';
+      mockedExecSync.mockReturnValue(expectedOutput);
+      const tmux = createTmux();
+
+      const result = tmux.capture('1.0', 50);
+
+      expect(result).toBe(expectedOutput);
+    });
+
+    it('captures specified number of lines', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      tmux.capture('2.1', 200);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        'tmux capture-pane -t "2.1" -p -S -200',
+        expect.any(Object)
+      );
+    });
+
+    it('throws when pane does not exist', () => {
+      const error = new Error("can't find pane: 99.99");
+      mockedExecSync.mockImplementationOnce(() => {
+        throw error;
+      });
+
+      const tmux = createTmux();
+
+      expect(() => tmux.capture('99.99', 100)).toThrow("can't find pane: 99.99");
+    });
+
+    it('uses utf-8 encoding for output', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      tmux.capture('1.0', 100);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ encoding: 'utf-8' })
+      );
+    });
+
+    it('uses pipe stdio for all streams', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      tmux.capture('1.0', 100);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ stdio: ['pipe', 'pipe', 'pipe'] })
+      );
+    });
+  });
+
+  describe('pane ID handling', () => {
+    it('accepts window.pane format', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      tmux.send('1.2', 'Hello');
+      tmux.capture('1.2', 100);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.stringContaining('-t "1.2"'),
+        expect.any(Object)
+      );
+    });
+
+    it('accepts session:window.pane format', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      tmux.send('main:1.2', 'Hello');
+      tmux.capture('main:1.2', 100);
+
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        expect.stringContaining('-t "main:1.2"'),
+        expect.any(Object)
+      );
+    });
+
+    it('quotes pane ID to prevent shell injection', () => {
+      mockedExecSync.mockReturnValue('');
+      const tmux = createTmux();
+
+      // Malicious pane ID attempt
+      tmux.send('1.0; rm -rf /', 'Hello');
+
+      // Should be quoted and treated as literal string
+      expect(mockedExecSync).toHaveBeenCalledWith(
+        'tmux send-keys -t "1.0; rm -rf /" "Hello"',
+        expect.any(Object)
+      );
+    });
+  });
+});

package/src/tmux.ts

@@ -0,0 +1,27 @@
+// ─────────────────────────────────────────────────────────────
+// Pure tmux wrapper - send-keys, capture-pane
+// ─────────────────────────────────────────────────────────────
+
+import { execSync } from 'child_process';
+import type { Tmux } from './types.js';
+
+export function createTmux(): Tmux {
+  return {
+    send(paneId: string, message: string): void {
+      execSync(`tmux send-keys -t "${paneId}" ${JSON.stringify(message)}`, {
+        stdio: 'pipe',
+      });
+      execSync(`tmux send-keys -t "${paneId}" Enter`, {
+        stdio: 'pipe',
+      });
+    },
+
+    capture(paneId: string, lines: number): string {
+      const output = execSync(`tmux capture-pane -t "${paneId}" -p -S -${lines}`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      return output;
+    },
+  };
+}