agentsys 5.0.3 → 5.2.0

package/plugins/audit-project/lib/state/workflow-state.js

@@ -1,576 +0,0 @@
-/**
- * Simplified workflow state management
- *
- * Two files:
- * - Main project: {stateDir}/tasks.json (tracks active worktree/task)
- * - Worktree: {stateDir}/flow.json (tracks workflow progress)
- *
- * State directory is platform-aware:
- * - Claude Code: .claude/
- * - OpenCode: .opencode/
- * - Codex CLI: .codex/
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { getStateDir } = require('../platform/state-dir');
-const { writeJsonAtomic } = require('../utils/atomic-write');
-const { isPlainObject, updatesApplied, sleepForRetry } = require('../utils/state-helpers');
-
-// File paths
-const TASKS_FILE = 'tasks.json';
-const FLOW_FILE = 'flow.json';
-/**
- * Validate and resolve path to prevent path traversal attacks
- * @param {string} basePath - Base directory path
- * @returns {string} Validated absolute path
- * @throws {Error} If path is invalid
- */
-function validatePath(basePath) {
-  if (typeof basePath !== 'string' || basePath.length === 0) {
-    throw new Error('Path must be a non-empty string');
-  }
-  const resolved = path.resolve(basePath);
-  if (resolved.includes('\0')) {
-    throw new Error('Path contains invalid null byte');
-  }
-  return resolved;
-}
-
-/**
- * Validate that target path is within base directory
- * @param {string} targetPath - Target file path
- * @param {string} basePath - Base directory
- * @throws {Error} If path traversal detected
- */
-function validatePathWithinBase(targetPath, basePath) {
-  const resolvedTarget = path.resolve(targetPath);
-  const resolvedBase = path.resolve(basePath);
-  if (!resolvedTarget.startsWith(resolvedBase + path.sep) && resolvedTarget !== resolvedBase) {
-    throw new Error('Path traversal detected');
-  }
-}
-
-/**
- * Generate a unique workflow ID
- * @returns {string} Workflow ID
- */
-function generateWorkflowId() {
-  const now = new Date();
-  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
-  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
-  const random = crypto.randomBytes(4).toString('hex');
-  return `workflow-${date}-${time}-${random}`;
-}
-
-// Valid phases for the workflow
-const PHASES = [
-  'policy-selection',
-  'task-discovery',
-  'worktree-setup',
-  'exploration',
-  'planning',
-  'user-approval',
-  'implementation',
-  'review-loop',
-  'delivery-validation',
-  'shipping',
-  'complete'
-];
-
-/**
- * Ensure state directory exists (platform-aware)
- */
-function ensureStateDir(basePath) {
-  const stateDir = path.join(basePath, getStateDir(basePath));
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-  }
-  return stateDir;
-}
-
-// =============================================================================
-// TASKS.JSON - Main project directory
-// =============================================================================
-
-/**
- * Get path to tasks.json with validation
- */
-function getTasksPath(projectPath = process.cwd()) {
-  const validatedBase = validatePath(projectPath);
-  const tasksPath = path.join(validatedBase, getStateDir(projectPath), TASKS_FILE);
-  validatePathWithinBase(tasksPath, validatedBase);
-  return tasksPath;
-}
-
-/**
- * Read tasks.json from main project
- * Returns { active: null } if file doesn't exist or is corrupted
- * Logs critical error on corruption to prevent silent data loss
- */
-function readTasks(projectPath = process.cwd()) {
-  const tasksPath = getTasksPath(projectPath);
-  if (!fs.existsSync(tasksPath)) {
-    return { active: null };
-  }
-  try {
-    const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
-    // Normalize legacy format that may not have 'active' field
-    if (!Object.prototype.hasOwnProperty.call(data, 'active')) {
-      return { active: null };
-    }
-    return data;
-  } catch (e) {
-    console.error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}`);
-    return { active: null };
-  }
-}
-
-/**
- * Write tasks.json to main project
- */
-function writeTasks(tasks, projectPath = process.cwd()) {
-  ensureStateDir(projectPath);
-  const tasksPath = getTasksPath(projectPath);
-  writeJsonAtomic(tasksPath, tasks);
-  return true;
-}
-
-/**
- * Set active task in main project
- */
-function setActiveTask(task, projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = {
-    ...task,
-    startedAt: new Date().toISOString()
-  };
-  return writeTasks(tasks, projectPath);
-}
-
-/**
- * Clear active task
- */
-function clearActiveTask(projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  tasks.active = null;
-  return writeTasks(tasks, projectPath);
-}
-
-/**
- * Check if there's an active task
- * Uses != null to catch both null and undefined (legacy format safety)
- */
-function hasActiveTask(projectPath = process.cwd()) {
-  const tasks = readTasks(projectPath);
-  return tasks.active != null;
-}
-
-// =============================================================================
-// FLOW.JSON - Worktree directory
-// =============================================================================
-
-/**
- * Get path to flow.json with validation
- */
-function getFlowPath(worktreePath = process.cwd()) {
-  const validatedBase = validatePath(worktreePath);
-  const flowPath = path.join(validatedBase, getStateDir(worktreePath), FLOW_FILE);
-  validatePathWithinBase(flowPath, validatedBase);
-  return flowPath;
-}
-
-/**
- * Read flow.json from worktree
- * Returns null if file doesn't exist or is corrupted
- * Logs critical error on corruption to prevent silent data loss
- */
-function readFlow(worktreePath = process.cwd()) {
-  const flowPath = getFlowPath(worktreePath);
-  if (!fs.existsSync(flowPath)) {
-    return null;
-  }
-  try {
-    return JSON.parse(fs.readFileSync(flowPath, 'utf8'));
-  } catch (e) {
-    console.error(`[CRITICAL] Corrupted flow.json at ${flowPath}: ${e.message}`);
-    return null;
-  }
-}
-
-/**
- * Write flow.json to worktree
- * Creates a copy to avoid mutating the original object
- * Increments version for optimistic locking
- */
-function writeFlow(flow, worktreePath = process.cwd()) {
-  ensureStateDir(worktreePath);
-  // Clone to avoid mutating the original object
-  const flowCopy = structuredClone(flow);
-  flowCopy.lastUpdate = new Date().toISOString();
-  // Increment version for optimistic locking (initialize if missing)
-  flowCopy._version = (flowCopy._version || 0) + 1;
-  const flowPath = getFlowPath(worktreePath);
-  writeJsonAtomic(flowPath, flowCopy);
-  return true;
-}
-
-/**
- * Update flow.json with partial updates
- * Handles null values correctly (null overwrites existing values)
- * Deep merges nested objects when both exist
- * Uses optimistic locking with version check and retry
- */
-function updateFlow(updates, worktreePath = process.cwd()) {
-  const MAX_RETRIES = 5;
-
-  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    const flow = readFlow(worktreePath) || {};
-    const initialVersion = flow._version || 0;
-
-    for (const [key, value] of Object.entries(updates)) {
-      // Skip internal version field from updates
-      if (key === '_version') continue;
-
-      // Null explicitly overwrites
-      if (value === null) {
-        flow[key] = null;
-      }
-      // Deep merge if both source and target are non-null objects
-      else if (isPlainObject(value) && isPlainObject(flow[key])) {
-        flow[key] = { ...flow[key], ...value };
-      }
-      // Otherwise direct assignment
-      else {
-        flow[key] = value;
-      }
-    }
-
-    // Preserve version for write (writeFlow will increment it)
-    flow._version = initialVersion;
-
-    // Write and verify version wasn't changed by another process
-    writeFlow(flow, worktreePath);
-
-    // Re-read to verify our write succeeded
-    const afterWrite = readFlow(worktreePath);
-    if (afterWrite && afterWrite._version >= initialVersion + 1 && updatesApplied(afterWrite, updates)) {
-      return true; // Success
-    }
-
-    // Version conflict or overwrite - retry after brief delay
-    if (attempt < MAX_RETRIES - 1) {
-      const delay = Math.floor(Math.random() * 50) + 10;
-      sleepForRetry(delay);
-    }
-  }
-
-  // All retries exhausted. One final read can detect if another writer
-  // applied the same updates while we were retrying.
-  const latest = readFlow(worktreePath);
-  if (latest && updatesApplied(latest, updates)) {
-    return true;
-  }
-
-  console.error('[ERROR] updateFlow: failed to apply updates after max retries');
-  return false;
-}
-
-/**
- * Create initial flow for a new task
- * Also registers the task as active in the main project's tasks.json
- * @param {Object} task - Task object with id, title, source, url
- * @param {Object} policy - Policy object with stoppingPoint
- * @param {string} worktreePath - Path to worktree
- * @param {string} projectPath - Path to main project (for tasks.json registration)
- */
-function createFlow(task, policy, worktreePath = process.cwd(), projectPath = null) {
-  const flow = {
-    task: {
-      id: task.id,
-      title: task.title,
-      source: task.source,
-      url: task.url || null
-    },
-    policy: {
-      stoppingPoint: policy.stoppingPoint || 'merged'
-    },
-    phase: 'policy-selection',
-    status: 'in_progress',
-    lastUpdate: new Date().toISOString(),
-    userNotes: '',
-    git: {
-      branch: null,
-      baseBranch: 'main'
-    },
-    pr: null,
-    exploration: null,
-    plan: null,
-    // Store projectPath so completeWorkflow knows where to clear the task
-    projectPath: projectPath
-  };
-
-  writeFlow(flow, worktreePath);
-
-  // Register task as active in main project
-  if (projectPath) {
-    setActiveTask({
-      taskId: task.id,
-      title: task.title,
-      worktree: worktreePath,
-      branch: flow.git.branch
-    }, projectPath);
-  }
-
-  return flow;
-}
-
-/**
- * Delete flow.json
- */
-function deleteFlow(worktreePath = process.cwd()) {
-  const flowPath = getFlowPath(worktreePath);
-  if (fs.existsSync(flowPath)) {
-    fs.unlinkSync(flowPath);
-    return true;
-  }
-  return false;
-}
-
-// =============================================================================
-// PHASE MANAGEMENT
-// =============================================================================
-
-/**
- * Check if phase is valid
- */
-function isValidPhase(phase) {
-  return PHASES.includes(phase);
-}
-
-/**
- * Set current phase
- */
-function setPhase(phase, worktreePath = process.cwd()) {
-  if (!isValidPhase(phase)) {
-    throw new Error(`Invalid phase: ${phase}`);
-  }
-  return updateFlow({ phase, status: 'in_progress' }, worktreePath);
-}
-
-/**
- * Start a phase (alias for setPhase, for backwards compatibility)
- */
-function startPhase(phase, worktreePath = process.cwd()) {
-  return setPhase(phase, worktreePath);
-}
-
-/**
- * Fail the current phase
- */
-function failPhase(reason, context = {}, worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-  if (!flow) return null;
-
-  return updateFlow({
-    status: 'failed',
-    error: reason,
-    failContext: context
-  }, worktreePath);
-}
-
-/**
- * Skip to a specific phase
- */
-function skipToPhase(phase, reason = 'manual skip', worktreePath = process.cwd()) {
-  if (!isValidPhase(phase)) {
-    throw new Error(`Invalid phase: ${phase}`);
-  }
-  return updateFlow({
-    phase,
-    status: 'in_progress',
-    skipReason: reason
-  }, worktreePath);
-}
-
-/**
- * Complete current phase and move to next
- * Uses updateFlow pattern to avoid direct mutation issues
- */
-function completePhase(result = null, worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-  if (!flow) return null;
-
-  const currentIndex = PHASES.indexOf(flow.phase);
-  const nextPhase = PHASES[currentIndex + 1] || 'complete';
-
-  // Build updates object
-  const updates = {
-    phase: nextPhase,
-    status: nextPhase === 'complete' ? 'completed' : 'in_progress'
-  };
-
-  // Store result in appropriate field
-  if (result) {
-    const resultField = getResultField(flow.phase);
-    if (resultField) {
-      updates[resultField] = result;
-    }
-  }
-
-  const updated = updateFlow(updates, worktreePath);
-  return updated ? readFlow(worktreePath) : null;
-}
-
-/**
- * Map phase to result field
- */
-function getResultField(phase) {
-  const mapping = {
-    'exploration': 'exploration',
-    'planning': 'plan',
-    'review-loop': 'reviewResult'
-  };
-  return mapping[phase] || null;
-}
-
-/**
- * Mark workflow as failed
- */
-function failWorkflow(error, worktreePath = process.cwd()) {
-  return updateFlow({
-    status: 'failed',
-    error: error?.message || String(error)
-  }, worktreePath);
-}
-
-/**
- * Mark workflow as complete
- * Automatically clears the active task from tasks.json using stored projectPath
- * @param {string} worktreePath - Path to worktree
- */
-function completeWorkflow(worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-
-  const updated = updateFlow({
-    phase: 'complete',
-    status: 'completed',
-    completedAt: new Date().toISOString()
-  }, worktreePath);
-
-  if (updated && flow && flow.projectPath) {
-    clearActiveTask(flow.projectPath);
-  }
-
-  return updated;
-}
-
-/**
- * Abort workflow
- * Also clears the active task from tasks.json using stored projectPath
- */
-function abortWorkflow(reason, worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-
-  const updated = updateFlow({
-    status: 'aborted',
-    abortReason: reason,
-    abortedAt: new Date().toISOString()
-  }, worktreePath);
-
-  if (updated && flow && flow.projectPath) {
-    clearActiveTask(flow.projectPath);
-  }
-
-  return updated;
-}
-
-// =============================================================================
-// CONVENIENCE FUNCTIONS
-// =============================================================================
-
-/**
- * Get workflow summary for display
- */
-function getFlowSummary(worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-  if (!flow) return null;
-
-  return {
-    task: flow.task?.title || 'Unknown',
-    taskId: flow.task?.id,
-    phase: flow.phase,
-    status: flow.status,
-    lastUpdate: flow.lastUpdate,
-    pr: flow.pr?.number ? `#${flow.pr.number}` : null
-  };
-}
-
-/**
- * Check if workflow can be resumed
- */
-function canResume(worktreePath = process.cwd()) {
-  const flow = readFlow(worktreePath);
-  if (!flow) return false;
-  return flow.status === 'in_progress' && flow.phase !== 'complete';
-}
-
-// =============================================================================
-// BACKWARDS COMPATIBILITY ALIASES
-// =============================================================================
-
-// These maintain compatibility with existing agent code
-const readState = readFlow;
-const writeState = writeFlow;
-const updateState = updateFlow;
-const createState = (type, policy) => createFlow({ id: 'manual', title: 'Manual task', source: 'manual' }, policy);
-const deleteState = deleteFlow;
-const hasActiveWorkflow = hasActiveTask;
-const getWorkflowSummary = getFlowSummary;
-
-module.exports = {
-  // Constants
-  PHASES,
-
-  // Tasks (main project)
-  getTasksPath,
-  readTasks,
-  writeTasks,
-  setActiveTask,
-  clearActiveTask,
-  hasActiveTask,
-
-  // Flow (worktree)
-  getFlowPath,
-  readFlow,
-  writeFlow,
-  updateFlow,
-  createFlow,
-  deleteFlow,
-
-  // Phase management
-  isValidPhase,
-  setPhase,
-  startPhase,
-  completePhase,
-  failPhase,
-  skipToPhase,
-  failWorkflow,
-  completeWorkflow,
-  abortWorkflow,
-
-  // Convenience
-  getFlowSummary,
-  canResume,
-  generateWorkflowId,
-
-  // Backwards compatibility
-  readState,
-  writeState,
-  updateState,
-  createState,
-  deleteState,
-  hasActiveWorkflow,
-  getWorkflowSummary
-};

package/plugins/audit-project/lib/types/agent-frontmatter.d.ts

@@ -1,134 +0,0 @@
-/**
- * Agent Frontmatter Type Definitions
- * Defines the structure of YAML frontmatter in agent markdown files
- *
- * @module lib/types/agent-frontmatter
- * @author Avi Fenesh
- * @license MIT
- */
-
-/**
- * Tool permission for agent
- */
-export type AgentTool =
-  | 'Bash'
-  | 'Bash(git:*)'
-  | 'Bash(gh:*)'
-  | 'Bash(npm:*)'
-  | 'Bash(node:*)'
-  | 'Bash(deployment:*)'
-  | 'Read'
-  | 'Write'
-  | 'Edit'
-  | 'Glob'
-  | 'Grep'
-  | 'Task'
-  | 'LSP'
-  | 'EnterPlanMode'
-  | 'ExitPlanMode'
-  | 'AskUserQuestion'
-  | 'TodoWrite'
-  | 'WebFetch'
-  | 'WebSearch'
-  | string; // Allow custom tools
-
-/**
- * Agent color for UI identification
- */
-export type AgentColor =
-  | 'blue'
-  | 'green'
-  | 'purple'
-  | 'orange'
-  | 'red'
-  | 'yellow'
-  | 'pink'
-  | 'cyan';
-
-/**
- * Agent frontmatter structure
- * YAML metadata at the top of agent markdown files
- */
-export interface AgentFrontmatter {
-  /** Agent unique identifier (kebab-case) */
-  agent: string;
-
-  /** Short description of agent purpose */
-  description: string;
-
-  /** Tools the agent has access to */
-  tools?: AgentTool[];
-
-  /** Preferred model for this agent (sonnet, opus, haiku) */
-  model?: 'sonnet' | 'opus' | 'haiku';
-
-  /** Maximum number of turns before stopping */
-  maxTurns?: number;
-
-  /** UI color for agent identification */
-  color?: AgentColor;
-
-  /** Whether agent can run in background */
-  canRunInBackground?: boolean;
-
-  /** Whether agent requires user approval before running */
-  requiresApproval?: boolean;
-
-  /** Agent category for organization */
-  category?: string;
-
-  /** Tags for searchability */
-  tags?: string[];
-
-  /** When this agent should be used (triggering conditions) */
-  'when-to-use'?: string[];
-
-  /** Example usage scenarios */
-  examples?: string[];
-}
-
-/**
- * Type guard to check if an object is valid AgentFrontmatter
- */
-export function isAgentFrontmatter(obj: unknown): obj is AgentFrontmatter {
-  if (typeof obj !== 'object' || obj === null) return false;
-  const fm = obj as Partial<AgentFrontmatter>;
-
-  return (
-    typeof fm.agent === 'string' &&
-    fm.agent.length > 0 &&
-    typeof fm.description === 'string' &&
-    fm.description.length > 0
-  );
-}
-
-/**
- * Validates agent frontmatter
- * @throws {Error} If frontmatter is invalid
- */
-export function validateAgentFrontmatter(
-  frontmatter: unknown
-): asserts frontmatter is AgentFrontmatter {
-  if (!isAgentFrontmatter(frontmatter)) {
-    throw new Error('Invalid agent frontmatter: missing required fields');
-  }
-
-  // Additional validations
-  if (frontmatter.tools && !Array.isArray(frontmatter.tools)) {
-    throw new Error('Invalid agent frontmatter: tools must be an array');
-  }
-
-  if (frontmatter.model && !['sonnet', 'opus', 'haiku'].includes(frontmatter.model)) {
-    throw new Error('Invalid agent frontmatter: model must be sonnet, opus, or haiku');
-  }
-
-  if (frontmatter.maxTurns !== undefined &&
-      (typeof frontmatter.maxTurns !== 'number' || frontmatter.maxTurns < 1)) {
-    throw new Error('Invalid agent frontmatter: maxTurns must be a positive number');
-  }
-
-  const validColors: AgentColor[] = ['blue', 'green', 'purple', 'orange', 'red', 'yellow', 'pink', 'cyan'];
-  if (frontmatter.color && !validColors.includes(frontmatter.color)) {
-    throw new Error(`Invalid agent frontmatter: color must be one of ${validColors.join(', ')}`);
-  }
-}