sudocode 1.1.17 → 1.1.18-dev.0

package/node_modules/@sudocode-ai/types/src/workflows.d.ts

@@ -0,0 +1,501 @@
+/**
+ * Workflow types for sudocode
+ * Enables multi-issue automation with dependency-based orchestration
+ */
+
+import type { AgentType } from "./agents.js";
+
+// =============================================================================
+// Status Types
+// =============================================================================
+
+/**
+ * Workflow lifecycle status
+ */
+export type WorkflowStatus =
+  | "pending" // Created, not yet started
+  | "running" // Actively executing steps (includes planning phase)
+  | "paused" // Paused by user or orchestrator
+  | "completed" // All steps finished successfully
+  | "failed" // Workflow failed (unrecoverable)
+  | "cancelled"; // User cancelled
+
+/**
+ * Individual workflow step status
+ */
+export type WorkflowStepStatus =
+  | "pending" // Not yet ready (dependencies not met)
+  | "ready" // Dependencies met, can be executed
+  | "running" // Currently executing
+  | "completed" // Finished successfully
+  | "failed" // Execution failed
+  | "skipped" // Skipped by orchestrator
+  | "blocked"; // Blocked by failed dependency
+
+// =============================================================================
+// Source Types
+// =============================================================================
+
+/**
+ * Defines how a workflow's scope is determined
+ */
+export type WorkflowSource =
+  | WorkflowSourceSpec
+  | WorkflowSourceIssues
+  | WorkflowSourceRootIssue
+  | WorkflowSourceGoal;
+
+/**
+ * Workflow from issues implementing a spec
+ */
+export interface WorkflowSourceSpec {
+  type: "spec";
+  specId: string;
+}
+
+/**
+ * Workflow from explicit list of issues
+ */
+export interface WorkflowSourceIssues {
+  type: "issues";
+  issueIds: string[];
+}
+
+/**
+ * Workflow from a root issue and all its blockers
+ */
+export interface WorkflowSourceRootIssue {
+  type: "root_issue";
+  issueId: string;
+}
+
+/**
+ * Goal-based workflow where orchestrator creates issues dynamically
+ */
+export interface WorkflowSourceGoal {
+  type: "goal";
+  goal: string;
+}
+
+// =============================================================================
+// Escalation Types (Human-in-the-Loop)
+// =============================================================================
+
+/**
+ * Escalation status for human-in-the-loop workflows
+ */
+export type EscalationStatus = "pending" | "resolved" | "bypassed";
+
+/**
+ * User response to an escalation request
+ */
+export interface EscalationResponse {
+  /** User's action choice */
+  action: "approve" | "reject" | "custom";
+  /** Optional message from user */
+  message?: string;
+  /** When the user responded */
+  respondedAt: string;
+}
+
+/**
+ * Escalation data structure for pending or resolved escalations
+ */
+export interface EscalationData {
+  /** Unique escalation request identifier */
+  requestId: string;
+  /** Message displayed to user */
+  message: string;
+  /** Optional predefined options for user to choose */
+  options?: string[];
+  /** Additional context for the escalation */
+  context?: Record<string, unknown>;
+  /** User's response (present when resolved) */
+  response?: EscalationResponse;
+}
+
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
+/**
+ * Workflow engine type
+ * - sequential: Steps are executed in order by the server, no agent orchestration
+ * - orchestrator: An AI agent orchestrates the workflow, making decisions dynamically
+ */
+export type WorkflowEngineType = "sequential" | "orchestrator";
+
+/**
+ * Workflow parallelism mode
+ */
+export type WorkflowParallelism = "sequential" | "parallel";
+
+/**
+ * Failure handling strategy
+ */
+export type WorkflowFailureStrategy =
+  | "stop" // Stop workflow immediately
+  | "pause" // Pause for user intervention
+  | "skip_dependents" // Skip this step and all dependents
+  | "continue"; // Continue with other independent steps
+
+/**
+ * Autonomy level for orchestrator-managed workflows
+ */
+export type WorkflowAutonomyLevel = "full_auto" | "human_in_the_loop";
+
+/**
+ * Workflow configuration options
+ */
+export interface WorkflowConfig {
+  // === Engine Selection ===
+
+  /**
+   * Which engine to use for workflow execution
+   * - sequential: Server-managed step execution (default)
+   * - orchestrator: AI agent orchestrates the workflow
+   * @default "sequential"
+   */
+  engineType: WorkflowEngineType;
+
+  // === Sequential Engine Options ===
+
+  /**
+   * Execution mode: sequential or parallel
+   * @default "sequential"
+   */
+  parallelism: WorkflowParallelism;
+
+  /**
+   * Maximum concurrent executions (when parallelism is "parallel")
+   */
+  maxConcurrency?: number;
+
+  /**
+   * How to handle step failures
+   * @default "pause"
+   */
+  onFailure: WorkflowFailureStrategy;
+
+  /**
+   * Auto-commit changes after each successful step
+   * @default true
+   */
+  autoCommitAfterStep: boolean;
+
+  /**
+   * Default agent type for step executions
+   * @default "claude-code"
+   */
+  defaultAgentType: AgentType;
+
+  // === Orchestrator Engine Options ===
+
+  /**
+   * Agent type for the orchestrator (agent-managed mode)
+   */
+  orchestratorAgentType?: AgentType;
+
+  /**
+   * Model for the orchestrator agent
+   */
+  orchestratorModel?: string;
+
+  /**
+   * Autonomy level for orchestrator decisions
+   * - full_auto: No user intervention, escalate_to_user bypassed
+   * - human_in_the_loop: Pause on escalations for user input
+   * @default "human_in_the_loop"
+   */
+  autonomyLevel: WorkflowAutonomyLevel;
+
+  // === Timeout Options ===
+
+  /**
+   * Timeout for individual executions (ms)
+   * Orchestrator will cancel stuck executions after this time
+   */
+  executionTimeoutMs?: number;
+
+  /**
+   * Idle timeout (ms) - wake orchestrator if nothing happens
+   */
+  idleTimeoutMs?: number;
+
+  /**
+   * Batch window for wakeup events (ms)
+   * Multiple events within this window are batched into one wakeup
+   */
+  wakeupBatchWindowMs?: number;
+
+  // === Worktree Options ===
+
+  /**
+   * Base branch for worktree creation
+   * Defaults to current working branch if not specified
+   */
+  baseBranch?: string;
+
+  /**
+   * Whether to create baseBranch if it doesn't exist
+   * @default false
+   */
+  createBaseBranch?: boolean;
+
+  /**
+   * Reuse an existing worktree by path
+   * If set, the workflow will use this worktree instead of creating a new one
+   * The path must exist and be a valid git worktree
+   */
+  reuseWorktreePath?: string;
+
+  // === Metadata Options ===
+
+  /**
+   * Custom workflow title
+   * Auto-generated from source if not specified
+   */
+  title?: string;
+}
+
+// =============================================================================
+// Core Entity Types
+// =============================================================================
+
+/**
+ * A single step in a workflow
+ * Each step corresponds to one issue execution
+ */
+export interface WorkflowStep {
+  /** Unique step identifier */
+  id: string;
+
+  /** Issue ID this step executes */
+  issueId: string;
+
+  /** Step index in workflow (for ordering) */
+  index: number;
+
+  /** Step IDs this step depends on */
+  dependencies: string[];
+
+  /** Current step status */
+  status: WorkflowStepStatus;
+
+  /** Execution ID once started */
+  executionId?: string;
+
+  /** Git commit SHA after step completion */
+  commitSha?: string;
+
+  /** Error message if failed */
+  error?: string;
+
+  /** Agent type override for this step */
+  agentType?: AgentType;
+
+  /** Model override for this step */
+  model?: string;
+}
+
+/**
+ * A workflow orchestrating multiple issue executions
+ */
+export interface Workflow {
+  /** Unique workflow identifier */
+  id: string;
+
+  /** Human-readable workflow title */
+  title: string;
+
+  /** How the workflow scope was defined */
+  source: WorkflowSource;
+
+  /** Current workflow status */
+  status: WorkflowStatus;
+
+  /** Steps in this workflow (empty initially for goal-based) */
+  steps: WorkflowStep[];
+
+  // === Worktree Information ===
+
+  /** Shared worktree path for sequential execution */
+  worktreePath?: string;
+
+  /** Branch name for workflow changes */
+  branchName?: string;
+
+  /** Base branch to create workflow branch from */
+  baseBranch: string;
+
+  // === Progress Tracking ===
+
+  /** Current step index (for sequential mode) */
+  currentStepIndex: number;
+
+  // === Orchestrator Information (agent-managed mode) ===
+
+  /** Execution ID of the orchestrator agent */
+  orchestratorExecutionId?: string;
+
+  /** Session ID for orchestrator (maintained across wakeups) */
+  orchestratorSessionId?: string;
+
+  // === Configuration ===
+
+  /** Workflow configuration */
+  config: WorkflowConfig;
+
+  // === Timestamps ===
+
+  /** When workflow was created */
+  createdAt: string;
+
+  /** When workflow was last updated */
+  updatedAt: string;
+
+  /** When workflow execution started */
+  startedAt?: string;
+
+  /** When workflow completed (success or failure) */
+  completedAt?: string;
+}
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/**
+ * Types of workflow events
+ */
+export type WorkflowEventType =
+  // Step events
+  | "step_started"
+  | "step_completed"
+  | "step_failed"
+  | "step_skipped"
+  // Workflow lifecycle events
+  | "workflow_started"
+  | "workflow_paused"
+  | "workflow_resumed"
+  | "workflow_completed"
+  | "workflow_failed"
+  | "workflow_cancelled"
+  // Escalation events
+  | "escalation_requested"
+  | "escalation_resolved"
+  // Notification events
+  | "user_notification"
+  // Orchestrator events
+  | "orchestrator_wakeup"
+  | "user_response";
+
+/**
+ * A workflow event for tracking and orchestrator wakeups
+ */
+export interface WorkflowEvent {
+  /** Unique event identifier */
+  id: string;
+
+  /** Workflow this event belongs to */
+  workflowId: string;
+
+  /** Event type */
+  type: WorkflowEventType;
+
+  /** Related step ID (for step events) */
+  stepId?: string;
+
+  /** Related execution ID */
+  executionId?: string;
+
+  /** Event-specific payload */
+  payload: Record<string, unknown>;
+
+  /** When event was created */
+  createdAt: string;
+
+  /** When event was processed by orchestrator */
+  processedAt?: string;
+}
+
+// =============================================================================
+// Database Row Types (snake_case for SQLite)
+// =============================================================================
+
+/**
+ * Workflow row as stored in SQLite
+ * JSON fields are serialized as TEXT
+ */
+export interface WorkflowRow {
+  id: string;
+  title: string;
+  source: string; // JSON (WorkflowSource)
+  status: WorkflowStatus;
+  steps: string; // JSON (WorkflowStep[])
+  worktree_path: string | null;
+  branch_name: string | null;
+  base_branch: string;
+  current_step_index: number;
+  orchestrator_execution_id: string | null;
+  orchestrator_session_id: string | null;
+  config: string; // JSON (WorkflowConfig)
+  created_at: string;
+  updated_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+}
+
+/**
+ * Workflow event row as stored in SQLite
+ */
+export interface WorkflowEventRow {
+  id: string;
+  workflow_id: string;
+  type: WorkflowEventType;
+  step_id: string | null;
+  execution_id: string | null;
+  payload: string; // JSON
+  created_at: string;
+  processed_at: string | null;
+}
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/**
+ * Options for creating a new workflow
+ */
+export interface CreateWorkflowOptions {
+  title: string;
+  source: WorkflowSource;
+  config?: Partial<WorkflowConfig>;
+  baseBranch?: string;
+}
+
+/**
+ * Dependency graph analysis result
+ */
+export interface DependencyGraph {
+  /** Issue IDs in the graph */
+  issueIds: string[];
+
+  /** Edges: [fromId, toId] pairs (from blocks to) */
+  edges: Array<[string, string]>;
+
+  /** Issues in topological order */
+  topologicalOrder: string[];
+
+  /** Detected cycles (if any) */
+  cycles: string[][] | null;
+
+  /** Groups of issues that can run in parallel */
+  parallelGroups: string[][];
+}
+
+/**
+ * Default workflow configuration values (type declaration)
+ * Actual defaults should be implemented in consuming packages
+ */
+export declare const DEFAULT_WORKFLOW_CONFIG: Readonly<WorkflowConfig>;

package/node_modules/commander/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.