tmux-team 1.1.0 → 2.0.0-alpha.3

package/src/pm/permissions.test.ts

@@ -0,0 +1,332 @@
+// ─────────────────────────────────────────────────────────────
+// Permission System Tests
+// ─────────────────────────────────────────────────────────────
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  buildPermissionPath,
+  checkPermission,
+  getCurrentActor,
+  resolveActor,
+  PermissionChecks,
+} from './permissions.js';
+import type { ResolvedConfig } from '../types.js';
+
+function createMockConfig(agents: Record<string, { deny?: string[] }>): ResolvedConfig {
+  return {
+    mode: 'polling',
+    preambleMode: 'always',
+    defaults: { timeout: 60, pollInterval: 1, captureLines: 100 },
+    agents,
+    paneRegistry: {},
+  };
+}
+
+describe('buildPermissionPath', () => {
+  it('builds path without fields', () => {
+    expect(buildPermissionPath({ resource: 'task', action: 'list', fields: [] })).toBe(
+      'pm:task:list'
+    );
+  });
+
+  it('builds path with single field', () => {
+    expect(buildPermissionPath({ resource: 'task', action: 'update', fields: ['status'] })).toBe(
+      'pm:task:update(status)'
+    );
+  });
+
+  it('builds path with multiple fields sorted alphabetically', () => {
+    expect(
+      buildPermissionPath({ resource: 'task', action: 'update', fields: ['status', 'assignee'] })
+    ).toBe('pm:task:update(assignee,status)');
+  });
+
+  it('builds path with fields already sorted', () => {
+    expect(
+      buildPermissionPath({ resource: 'task', action: 'update', fields: ['assignee', 'status'] })
+    ).toBe('pm:task:update(assignee,status)');
+  });
+});
+
+describe('getCurrentActor', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns TMT_AGENT_NAME if set', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+    delete process.env.TMUX_TEAM_ACTOR;
+    expect(getCurrentActor()).toBe('codex');
+  });
+
+  it('returns TMUX_TEAM_ACTOR if TMT_AGENT_NAME not set', () => {
+    delete process.env.TMT_AGENT_NAME;
+    process.env.TMUX_TEAM_ACTOR = 'gemini';
+    expect(getCurrentActor()).toBe('gemini');
+  });
+
+  it('returns human if no env vars set', () => {
+    delete process.env.TMT_AGENT_NAME;
+    delete process.env.TMUX_TEAM_ACTOR;
+    expect(getCurrentActor()).toBe('human');
+  });
+
+  it('prefers TMT_AGENT_NAME over TMUX_TEAM_ACTOR', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+    process.env.TMUX_TEAM_ACTOR = 'gemini';
+    expect(getCurrentActor()).toBe('codex');
+  });
+});
+
+describe('checkPermission', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    // Disable pane detection in tests by unsetting TMUX
+    delete process.env.TMUX;
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('allows everything for human actor', () => {
+    delete process.env.TMT_AGENT_NAME;
+    delete process.env.TMUX_TEAM_ACTOR;
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(true);
+  });
+
+  it('allows when no deny patterns for agent', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: {}, // No deny patterns
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(true);
+  });
+
+  it('allows when agent not in config', () => {
+    process.env.TMT_AGENT_NAME = 'unknown-agent';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(true);
+  });
+
+  it('denies when pattern matches exactly', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(false);
+  });
+
+  it('denies when pattern matches any field', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    // Using both status and assignee, should still be denied because status is in deny list
+    expect(
+      checkPermission(config, PermissionChecks.taskUpdate(['status', 'assignee'])).allowed
+    ).toBe(false);
+  });
+
+  it('allows when fields do not match', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    // Only updating assignee, not status
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['assignee'])).allowed).toBe(true);
+  });
+
+  it('denies entire action when pattern has no fields', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update'] },
+    });
+
+    // Any update should be denied
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(false);
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['assignee'])).allowed).toBe(false);
+    expect(checkPermission(config, PermissionChecks.taskUpdate([])).allowed).toBe(false);
+  });
+
+  it('denies when wildcard pattern matches any field', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(*)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(false);
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['assignee'])).allowed).toBe(false);
+  });
+
+  it('allows no-field action when wildcard is used', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(*)'] },
+    });
+
+    // Wildcard only matches when fields are present
+    expect(checkPermission(config, PermissionChecks.taskUpdate([])).allowed).toBe(true);
+  });
+
+  it('allows different resource', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.milestoneUpdate(['status'])).allowed).toBe(
+      true
+    );
+  });
+
+  it('allows different action', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: { deny: ['pm:task:update(status)'] },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskCreate()).allowed).toBe(true);
+    expect(checkPermission(config, PermissionChecks.taskList()).allowed).toBe(true);
+  });
+
+  it('handles multiple deny patterns', () => {
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const config = createMockConfig({
+      codex: {
+        deny: ['pm:task:update(status)', 'pm:milestone:update(status)', 'pm:task:delete'],
+      },
+    });
+
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['status'])).allowed).toBe(false);
+    expect(checkPermission(config, PermissionChecks.milestoneUpdate(['status'])).allowed).toBe(
+      false
+    );
+    expect(checkPermission(config, PermissionChecks.taskDelete()).allowed).toBe(false);
+    expect(checkPermission(config, PermissionChecks.taskUpdate(['assignee'])).allowed).toBe(true);
+  });
+});
+
+describe('PermissionChecks helpers', () => {
+  it('creates correct task checks', () => {
+    expect(PermissionChecks.taskList()).toEqual({ resource: 'task', action: 'list', fields: [] });
+    expect(PermissionChecks.taskShow()).toEqual({ resource: 'task', action: 'show', fields: [] });
+    expect(PermissionChecks.taskCreate()).toEqual({
+      resource: 'task',
+      action: 'create',
+      fields: [],
+    });
+    expect(PermissionChecks.taskUpdate(['status'])).toEqual({
+      resource: 'task',
+      action: 'update',
+      fields: ['status'],
+    });
+    expect(PermissionChecks.taskDelete()).toEqual({
+      resource: 'task',
+      action: 'delete',
+      fields: [],
+    });
+  });
+
+  it('creates correct milestone checks', () => {
+    expect(PermissionChecks.milestoneList()).toEqual({
+      resource: 'milestone',
+      action: 'list',
+      fields: [],
+    });
+    expect(PermissionChecks.milestoneCreate()).toEqual({
+      resource: 'milestone',
+      action: 'create',
+      fields: [],
+    });
+    expect(PermissionChecks.milestoneUpdate(['status'])).toEqual({
+      resource: 'milestone',
+      action: 'update',
+      fields: ['status'],
+    });
+  });
+
+  it('creates correct doc checks', () => {
+    expect(PermissionChecks.docRead()).toEqual({ resource: 'doc', action: 'read', fields: [] });
+    expect(PermissionChecks.docUpdate()).toEqual({ resource: 'doc', action: 'update', fields: [] });
+  });
+
+  it('creates correct team checks', () => {
+    expect(PermissionChecks.teamCreate()).toEqual({
+      resource: 'team',
+      action: 'create',
+      fields: [],
+    });
+    expect(PermissionChecks.teamList()).toEqual({ resource: 'team', action: 'list', fields: [] });
+  });
+
+  it('creates correct log checks', () => {
+    expect(PermissionChecks.logRead()).toEqual({ resource: 'log', action: 'read', fields: [] });
+  });
+});
+
+describe('resolveActor', () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns human when not in tmux and no env var', () => {
+    delete process.env.TMUX;
+    delete process.env.TMT_AGENT_NAME;
+    delete process.env.TMUX_TEAM_ACTOR;
+
+    const result = resolveActor({});
+    expect(result.actor).toBe('human');
+    expect(result.source).toBe('default');
+    expect(result.warning).toBeUndefined();
+  });
+
+  it('uses env var when not in tmux', () => {
+    delete process.env.TMUX;
+    process.env.TMT_AGENT_NAME = 'codex';
+
+    const result = resolveActor({});
+    expect(result.actor).toBe('codex');
+    expect(result.source).toBe('env');
+    expect(result.warning).toBeUndefined();
+  });
+
+  it('prefers TMT_AGENT_NAME over TMUX_TEAM_ACTOR', () => {
+    delete process.env.TMUX;
+    process.env.TMT_AGENT_NAME = 'codex';
+    process.env.TMUX_TEAM_ACTOR = 'gemini';
+
+    const result = resolveActor({});
+    expect(result.actor).toBe('codex');
+    expect(result.source).toBe('env');
+  });
+});

package/src/pm/permissions.ts

@@ -0,0 +1,278 @@
+// ─────────────────────────────────────────────────────────────
+// Permission system for PM commands
+// ─────────────────────────────────────────────────────────────
+
+import { execSync } from 'child_process';
+import type { ResolvedConfig, PaneEntry } from '../types.js';
+
+/**
+ * Permission expression format:
+ * pm:<resource>:<action>(<field1>,<field2>,...)
+ *
+ * Examples:
+ * - pm:task:list
+ * - pm:task:update(status)
+ * - pm:task:update(assignee,status)
+ * - pm:task:update(*) - wildcard, any field
+ * - pm:task:update - no fields, entire action
+ */
+
+export interface PermissionCheck {
+  resource: string; // task, milestone, team, doc, log
+  action: string; // list, show, create, update, read
+  fields: string[]; // sorted alphabetically
+}
+
+/**
+ * Build permission path from command context.
+ */
+export function buildPermissionPath(check: PermissionCheck): string {
+  const base = `pm:${check.resource}:${check.action}`;
+  if (check.fields.length === 0) {
+    return base;
+  }
+  // Sort fields alphabetically for canonical form
+  const sortedFields = [...check.fields].sort();
+  return `${base}(${sortedFields.join(',')})`;
+}
+
+/**
+ * Parse a deny pattern into its components.
+ */
+function parsePattern(pattern: string): {
+  resource: string;
+  action: string;
+  fields: string[] | '*' | null;
+} {
+  // Pattern format: pm:resource:action or pm:resource:action(fields) or pm:resource:action(*)
+  const match = pattern.match(/^pm:(\w+):(\w+)(?:\(([^)]*)\))?$/);
+  if (!match) {
+    return { resource: '', action: '', fields: null };
+  }
+
+  const [, resource, action, fieldsStr] = match;
+
+  if (fieldsStr === undefined) {
+    // No parentheses - blocks entire action
+    return { resource, action, fields: null };
+  }
+
+  if (fieldsStr === '*') {
+    // Wildcard - blocks any field
+    return { resource, action, fields: '*' };
+  }
+
+  // Specific fields
+  const fields = fieldsStr
+    .split(',')
+    .map((f) => f.trim())
+    .filter(Boolean);
+  return { resource, action, fields };
+}
+
+/**
+ * Check if a permission path matches a deny pattern.
+ */
+function matchesPattern(path: PermissionCheck, pattern: string): boolean {
+  const parsed = parsePattern(pattern);
+
+  // Resource and action must match
+  if (parsed.resource !== path.resource || parsed.action !== path.action) {
+    return false;
+  }
+
+  // No fields in pattern = block entire action
+  if (parsed.fields === null) {
+    return true;
+  }
+
+  // Wildcard = block if path has any fields
+  if (parsed.fields === '*') {
+    return path.fields.length > 0;
+  }
+
+  // Specific fields = block if path uses ANY of the denied fields
+  return parsed.fields.some((f) => path.fields.includes(f));
+}
+
+/**
+ * Get current tmux pane in "window.pane" format.
+ * Returns null if not running in tmux.
+ */
+function getCurrentPane(): string | null {
+  // Check if we're in tmux
+  if (!process.env.TMUX) {
+    return null;
+  }
+
+  try {
+    const result = execSync("tmux display-message -p '#{window_index}.#{pane_index}'", {
+      encoding: 'utf-8',
+      timeout: 1000,
+    }).trim();
+    return result || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Look up agent name by pane ID in the registry.
+ */
+function findAgentByPane(paneRegistry: Record<string, PaneEntry>, paneId: string): string | null {
+  for (const [agentName, entry] of Object.entries(paneRegistry)) {
+    if (entry.pane === paneId) {
+      return agentName;
+    }
+  }
+  return null;
+}
+
+export interface ActorResolution {
+  actor: string;
+  source: 'pane' | 'env' | 'default';
+  warning?: string;
+}
+
+/**
+ * Resolve current actor using pane registry as primary source.
+ *
+ * Priority:
+ * 1. Look up current tmux pane in pane registry → agent name
+ * 2. If not in registry → 'human' (full access)
+ *
+ * Warnings:
+ * - If TMT_AGENT_NAME is set but conflicts with pane registry → warn about spoofing
+ * - If TMT_AGENT_NAME is set but pane not in registry → warn about unregistered pane
+ */
+export function resolveActor(paneRegistry: Record<string, PaneEntry>): ActorResolution {
+  const envActor = process.env.TMT_AGENT_NAME || process.env.TMUX_TEAM_ACTOR;
+  const currentPane = getCurrentPane();
+
+  // Not in tmux - use env var or default to human
+  if (!currentPane) {
+    if (envActor) {
+      return { actor: envActor, source: 'env' };
+    }
+    return { actor: 'human', source: 'default' };
+  }
+
+  // In tmux - look up pane in registry
+  const paneAgent = findAgentByPane(paneRegistry, currentPane);
+
+  if (paneAgent) {
+    // Pane is registered to an agent
+    if (envActor && envActor !== paneAgent) {
+      // Env var conflicts with pane registry - warn about potential spoofing
+      return {
+        actor: paneAgent,
+        source: 'pane',
+        warning: `⚠️  Identity mismatch: TMT_AGENT_NAME="${envActor}" but pane ${currentPane} is registered to "${paneAgent}". Using pane identity.`,
+      };
+    }
+    return { actor: paneAgent, source: 'pane' };
+  }
+
+  // Pane not in registry
+  if (envActor) {
+    // Agent claims identity but pane not registered - warn
+    return {
+      actor: 'human',
+      source: 'default',
+      warning: `⚠️  Unregistered pane: TMT_AGENT_NAME="${envActor}" but pane ${currentPane} is not in registry. Treating as human (full access).`,
+    };
+  }
+
+  // Not registered, no env var - human
+  return { actor: 'human', source: 'default' };
+}
+
+/**
+ * Get current actor (agent name or 'human').
+ * Legacy function for backward compatibility.
+ * Reads from TMT_AGENT_NAME or TMUX_TEAM_ACTOR env vars.
+ */
+export function getCurrentActor(): string {
+  return process.env.TMT_AGENT_NAME || process.env.TMUX_TEAM_ACTOR || 'human';
+}
+
+export interface PermissionResult {
+  allowed: boolean;
+  actor: string;
+  source: 'pane' | 'env' | 'default';
+  warning?: string;
+}
+
+/**
+ * Check if an action is allowed for the current actor.
+ * Uses pane-based identity resolution with warnings for conflicts.
+ */
+export function checkPermission(config: ResolvedConfig, check: PermissionCheck): PermissionResult {
+  const resolution = resolveActor(config.paneRegistry);
+  const { actor, source, warning } = resolution;
+
+  // Human is always allowed (no deny patterns for human)
+  if (actor === 'human') {
+    return { allowed: true, actor, source, warning };
+  }
+
+  // Get agent config
+  const agentConfig = config.agents[actor];
+  if (!agentConfig || !agentConfig.deny || agentConfig.deny.length === 0) {
+    // No deny patterns = allow all
+    return { allowed: true, actor, source, warning };
+  }
+
+  // Check if any deny pattern matches
+  for (const pattern of agentConfig.deny) {
+    if (matchesPattern(check, pattern)) {
+      return { allowed: false, actor, source, warning };
+    }
+  }
+
+  return { allowed: true, actor, source, warning };
+}
+
+/**
+ * Simple permission check (legacy, for tests).
+ * Returns true if allowed, false if denied.
+ */
+export function checkPermissionSimple(config: ResolvedConfig, check: PermissionCheck): boolean {
+  return checkPermission(config, check).allowed;
+}
+
+/**
+ * Build permission check for common PM operations.
+ */
+export const PermissionChecks = {
+  // Task operations
+  taskList: (): PermissionCheck => ({ resource: 'task', action: 'list', fields: [] }),
+  taskShow: (): PermissionCheck => ({ resource: 'task', action: 'show', fields: [] }),
+  taskCreate: (): PermissionCheck => ({ resource: 'task', action: 'create', fields: [] }),
+  taskUpdate: (fields: string[]): PermissionCheck => ({
+    resource: 'task',
+    action: 'update',
+    fields,
+  }),
+  taskDelete: (): PermissionCheck => ({ resource: 'task', action: 'delete', fields: [] }),
+
+  // Milestone operations
+  milestoneList: (): PermissionCheck => ({ resource: 'milestone', action: 'list', fields: [] }),
+  milestoneCreate: (): PermissionCheck => ({ resource: 'milestone', action: 'create', fields: [] }),
+  milestoneUpdate: (fields: string[]): PermissionCheck => ({
+    resource: 'milestone',
+    action: 'update',
+    fields,
+  }),
+
+  // Doc operations
+  docRead: (): PermissionCheck => ({ resource: 'doc', action: 'read', fields: [] }),
+  docUpdate: (): PermissionCheck => ({ resource: 'doc', action: 'update', fields: [] }),
+
+  // Team operations
+  teamCreate: (): PermissionCheck => ({ resource: 'team', action: 'create', fields: [] }),
+  teamList: (): PermissionCheck => ({ resource: 'team', action: 'list', fields: [] }),
+
+  // Log operations
+  logRead: (): PermissionCheck => ({ resource: 'log', action: 'read', fields: [] }),
+};

package/src/pm/storage/adapter.ts

@@ -0,0 +1,55 @@
+// ─────────────────────────────────────────────────────────────
+// Storage adapter interface for PM backends
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  Team,
+  Milestone,
+  Task,
+  AuditEvent,
+  CreateTaskInput,
+  UpdateTaskInput,
+  CreateMilestoneInput,
+  UpdateMilestoneInput,
+  ListTasksFilter,
+} from '../types.js';
+
+/**
+ * Abstract storage adapter interface.
+ * Implemented by:
+ * - FSAdapter (Phase 4): Local filesystem storage
+ * - GitHubAdapter (Phase 5): GitHub Issues as storage
+ */
+export interface StorageAdapter {
+  // Team operations
+  initTeam(name: string, windowId?: string): Promise<Team>;
+  getTeam(): Promise<Team | null>;
+  updateTeam(updates: Partial<Team>): Promise<Team>;
+
+  // Milestone operations
+  createMilestone(input: CreateMilestoneInput): Promise<Milestone>;
+  getMilestone(id: string): Promise<Milestone | null>;
+  listMilestones(): Promise<Milestone[]>;
+  updateMilestone(id: string, input: UpdateMilestoneInput): Promise<Milestone>;
+  deleteMilestone(id: string): Promise<void>;
+
+  // Task operations
+  createTask(input: CreateTaskInput): Promise<Task>;
+  getTask(id: string): Promise<Task | null>;
+  listTasks(filter?: ListTasksFilter): Promise<Task[]>;
+  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;
+  deleteTask(id: string): Promise<void>;
+
+  // Documentation
+  getTaskDoc(id: string): Promise<string | null>;
+  setTaskDoc(id: string, content: string): Promise<void>;
+
+  // Audit log
+  appendEvent(event: AuditEvent): Promise<void>;
+  getEvents(limit?: number): Promise<AuditEvent[]>;
+}
+
+/**
+ * Factory function type for creating storage adapters.
+ */
+export type StorageAdapterFactory = (teamDir: string) => StorageAdapter;