@generacy-ai/workflow-engine 0.0.0-preview-20260304013206

package/dist/types/action.d.ts

@@ -0,0 +1,358 @@
+/**
+ * Action system types.
+ * Defines interfaces for action handlers, context, and results.
+ */
+import type { ExecutableWorkflow } from './execution.js';
+import type { PhaseDefinition, StepDefinition } from './workflow.js';
+import type { Logger } from './logger.js';
+/**
+ * Built-in action types supported by the workflow engine.
+ * These are the core actions that are always available.
+ */
+export type BuiltinActionType = 'workspace.prepare' | 'agent.invoke' | 'verification.check' | 'pr.create' | 'shell' | 'humancy.request_review' | 'speckit';
+/**
+ * GitHub action namespace types
+ */
+export type GitHubActionType = 'github.preflight' | 'github.get_context' | 'github.review_changes' | 'github.commit_and_push' | 'github.merge_from_base' | 'github.create_draft_pr' | 'github.mark_pr_ready' | 'github.update_pr' | 'github.read_pr_feedback' | 'github.respond_pr_feedback' | 'github.add_comment' | 'github.sync_labels';
+/**
+ * Workflow action namespace types
+ */
+export type WorkflowActionType = 'workflow.update_phase' | 'workflow.check_gate' | 'workflow.update_stage';
+/**
+ * Epic action namespace types
+ */
+export type EpicActionType = 'epic.post_tasks_summary' | 'epic.check_completion' | 'epic.update_status' | 'epic.create_pr' | 'epic.close' | 'epic.dispatch_children';
+/**
+ * All known action types (built-in + namespaced).
+ * Use ActionIdentifier for dynamic/custom actions.
+ */
+export type ActionType = BuiltinActionType | GitHubActionType | WorkflowActionType | EpicActionType;
+/**
+ * Action identifier - can be any namespaced string (e.g., 'github.preflight', 'custom.action')
+ * This allows for extensibility beyond the predefined types.
+ */
+export type ActionIdentifier = string;
+/**
+ * Action namespace definition for plugin registration
+ */
+export interface ActionNamespace {
+    /** Namespace name (e.g., 'github', 'workflow', 'epic') */
+    namespace: string;
+    /** Description of the namespace */
+    description?: string;
+    /** Action handlers in this namespace */
+    handlers: ActionHandler[];
+}
+/**
+ * Step output stored for variable interpolation
+ */
+export interface StepOutput {
+    /** Raw string output */
+    raw: string;
+    /** Parsed JSON output (null if not valid JSON) */
+    parsed: unknown | null;
+    /** Exit code from execution */
+    exitCode: number;
+    /** Timestamp when step completed */
+    completedAt: Date;
+}
+/**
+ * Context provided to action handlers during execution
+ */
+export interface ActionContext {
+    /** The full workflow definition */
+    workflow: ExecutableWorkflow;
+    /** Current phase being executed */
+    phase: PhaseDefinition;
+    /** Current step being executed */
+    step: StepDefinition;
+    /** Workflow input parameters */
+    inputs: Record<string, unknown>;
+    /** Outputs from previously executed steps (keyed by stepId) */
+    stepOutputs: Map<string, StepOutput>;
+    /** Merged environment variables */
+    env: Record<string, string>;
+    /** Working directory for command execution */
+    workdir: string;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Logger for action execution */
+    logger: Logger;
+    /** Emit a streaming event (log output or step output) */
+    emitEvent?: (event: {
+        type: 'log:append' | 'step:output';
+        data: Record<string, unknown>;
+    }) => void;
+}
+/**
+ * Result returned by action handlers
+ */
+export interface ActionResult {
+    /** Whether the action completed successfully */
+    success: boolean;
+    /** Structured output from the action (preferably JSON) */
+    output: unknown;
+    /** Raw stdout from command execution */
+    stdout?: string;
+    /** Raw stderr from command execution */
+    stderr?: string;
+    /** Error message if action failed */
+    error?: string;
+    /** Exit code from command (0 = success) */
+    exitCode?: number;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Files modified by this action (for tracking) */
+    filesModified?: string[];
+}
+/**
+ * Validation error structure
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+/**
+ * Validation warning structure
+ */
+export interface ValidationWarning {
+    field: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validation result from step configuration check
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: ValidationError[];
+    /** Validation warnings (if any) */
+    warnings: ValidationWarning[];
+}
+/**
+ * Action handler interface
+ * Defines the contract for all action implementations
+ */
+export interface ActionHandler {
+    /** The action type this handler processes (can be namespaced) */
+    readonly type: ActionIdentifier;
+    /**
+     * Check if this handler can process the given step
+     * @param step The workflow step to check
+     * @returns true if this handler can process the step
+     */
+    canHandle(step: StepDefinition): boolean;
+    /**
+     * Execute the action and return structured result
+     * @param step The workflow step to execute
+     * @param context Execution context with inputs, outputs, and environment
+     * @returns Promise resolving to action result
+     */
+    execute(step: StepDefinition, context: ActionContext): Promise<ActionResult>;
+    /**
+     * Validate step configuration before execution (optional)
+     * @param step The workflow step to validate
+     * @returns Validation result with errors and warnings
+     */
+    validate?(step: StepDefinition): ValidationResult;
+}
+/**
+ * Input for workspace.prepare action
+ */
+export interface WorkspacePrepareInput {
+    /** Branch name to create/checkout */
+    branch: string;
+    /** Base branch to create from (optional, defaults to current) */
+    baseBranch?: string;
+    /** Whether to force checkout (discard local changes) */
+    force?: boolean;
+}
+/**
+ * Output from workspace.prepare action
+ */
+export interface WorkspacePrepareOutput {
+    /** The branch that was checked out */
+    branch: string;
+    /** Previous branch before checkout */
+    previousBranch: string;
+    /** Whether a new branch was created */
+    created: boolean;
+}
+/**
+ * Input for agent.invoke action
+ */
+export interface AgentInvokeInput {
+    /** The prompt/task to send to the agent */
+    prompt: string;
+    /** Optional list of allowed tools */
+    allowedTools?: string[];
+    /** Maximum execution time in seconds */
+    timeout?: number;
+    /** Maximum number of agent turns */
+    maxTurns?: number;
+    /** Working directory for the agent */
+    workdir?: string;
+}
+/**
+ * Output from agent.invoke action
+ */
+export interface AgentInvokeOutput {
+    /** Summary of what the agent accomplished */
+    summary: string;
+    /** Files modified by the agent */
+    filesModified: string[];
+    /** Conversation ID for reference */
+    conversationId?: string;
+    /** Number of turns taken */
+    turns: number;
+    /** Any structured data returned by agent */
+    data?: Record<string, unknown>;
+}
+/**
+ * Input for verification.check action
+ */
+export interface VerificationCheckInput {
+    /** Command to run (e.g., "npm test", "npm run lint") */
+    command: string;
+    /** Working directory */
+    workdir?: string;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+    /** Expected exit code (default: 0) */
+    expectedExitCode?: number;
+}
+/**
+ * Output from verification.check action
+ */
+export interface VerificationCheckOutput {
+    /** Whether verification passed */
+    passed: boolean;
+    /** Test/lint output */
+    output: string;
+    /** Number of tests passed (if applicable) */
+    testsPassed?: number;
+    /** Number of tests failed (if applicable) */
+    testsFailed?: number;
+    /** Lint errors count (if applicable) */
+    lintErrors?: number;
+}
+/**
+ * Input for pr.create action
+ */
+export interface PrCreateInput {
+    /** PR title */
+    title: string;
+    /** PR body/description */
+    body?: string;
+    /** Base branch for the PR */
+    base?: string;
+    /** Whether to create as draft */
+    draft?: boolean;
+    /** Labels to add to the PR */
+    labels?: string[];
+    /** Reviewers to request */
+    reviewers?: string[];
+}
+/**
+ * Output from pr.create action
+ */
+export interface PrCreateOutput {
+    /** Created PR number */
+    number: number;
+    /** PR URL */
+    url: string;
+    /** PR state */
+    state: 'open' | 'draft';
+    /** Head branch */
+    headBranch: string;
+    /** Base branch */
+    baseBranch: string;
+}
+/**
+ * Urgency levels for human review requests
+ */
+export type HumancyUrgency = 'low' | 'normal' | 'blocking_soon' | 'blocking_now';
+/**
+ * Input for humancy.request_review action
+ */
+export interface HumancyReviewInput {
+    /**
+     * Content or file path to present for review.
+     * Supports variable interpolation: ${steps.preview.output.summary}
+     */
+    artifact: string;
+    /**
+     * Review instructions and context for the human reviewer.
+     * Describes what to check and why approval is needed.
+     */
+    context: string;
+    /**
+     * Review urgency level.
+     * - 'low': No time pressure, can wait days
+     * - 'normal': Default, expect response within hours
+     * - 'blocking_soon': Blocking workflow, need response soon
+     * - 'blocking_now': Critical, immediate attention needed
+     * @default 'normal'
+     */
+    urgency?: HumancyUrgency;
+    /**
+     * Timeout in milliseconds for waiting on human response.
+     * After timeout, action fails with timeout reason.
+     * @default 86400000 (24 hours)
+     */
+    timeout?: number;
+}
+/**
+ * Output from humancy.request_review action
+ */
+export interface HumancyReviewOutput {
+    /**
+     * Whether the human approved the review.
+     * Used in conditional step execution: ${steps.review.approved}
+     */
+    approved: boolean;
+    /**
+     * Optional comments from the reviewer.
+     * Present when rejection requires explanation.
+     */
+    comments?: string;
+    /**
+     * Identifier of the user who responded.
+     * From Humancy user profile.
+     */
+    respondedBy?: string;
+    /**
+     * ISO timestamp when response was received.
+     */
+    respondedAt?: string;
+    /**
+     * Unique ID of the review request.
+     * Can be used for audit/tracking.
+     */
+    reviewId: string;
+}
+/**
+ * Check if an action identifier is a namespaced action
+ * @param identifier The action identifier to check
+ * @returns true if the identifier contains a namespace (e.g., 'github.preflight')
+ */
+export declare function isNamespacedAction(identifier: string): boolean;
+/**
+ * Parse namespace and action name from an identifier
+ * @param identifier The action identifier (e.g., 'github.preflight')
+ * @returns Object with namespace and name, or null if not namespaced
+ */
+export declare function parseNamespacedAction(identifier: string): {
+    namespace: string;
+    name: string;
+} | null;
+/**
+ * Parse action type from a workflow step's 'uses' or 'action' field
+ * @param step The workflow step to parse
+ * @returns The detected action type, or 'shell' as fallback
+ */
+export declare function parseActionType(step: StepDefinition): ActionType;
+//# sourceMappingURL=action.d.ts.map

package/dist/types/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../src/types/action.ts"],"names":[],"mappings":"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"}

package/dist/types/action.js

@@ -0,0 +1,96 @@
+/**
+ * Check if an action identifier is a namespaced action
+ * @param identifier The action identifier to check
+ * @returns true if the identifier contains a namespace (e.g., 'github.preflight')
+ */
+export function isNamespacedAction(identifier) {
+    return identifier.includes('.') && !identifier.startsWith('.');
+}
+/**
+ * Parse namespace and action name from an identifier
+ * @param identifier The action identifier (e.g., 'github.preflight')
+ * @returns Object with namespace and name, or null if not namespaced
+ */
+export function parseNamespacedAction(identifier) {
+    if (!isNamespacedAction(identifier)) {
+        return null;
+    }
+    const dotIndex = identifier.indexOf('.');
+    return {
+        namespace: identifier.substring(0, dotIndex),
+        name: identifier.substring(dotIndex + 1),
+    };
+}
+/**
+ * Parse action type from a workflow step's 'uses' or 'action' field
+ * @param step The workflow step to parse
+ * @returns The detected action type, or 'shell' as fallback
+ */
+export function parseActionType(step) {
+    // Check 'uses' field first (preferred for action specification)
+    const uses = step.uses;
+    if (uses) {
+        // Check for compound namespace patterns first - these map to a base action type
+        // (e.g., 'speckit.create_feature' → 'speckit', not the full identifier)
+        if (uses.startsWith('speckit.') || uses.startsWith('speckit/')) {
+            return 'speckit';
+        }
+        if (uses.includes('workspace.prepare') || uses.includes('workspace/prepare')) {
+            return 'workspace.prepare';
+        }
+        if (uses.includes('agent.invoke') || uses.includes('agent/invoke') || uses.includes('claude')) {
+            return 'agent.invoke';
+        }
+        if (uses.includes('verification.check') || uses.includes('verification/check') || uses.includes('test') || uses.includes('lint')) {
+            return 'verification.check';
+        }
+        if (uses.includes('pr.create') || uses.includes('pr/create') || uses.includes('pull-request')) {
+            return 'pr.create';
+        }
+        if (uses.includes('humancy.request_review') || uses.includes('humancy/request_review') || uses.includes('humancy')) {
+            return 'humancy.request_review';
+        }
+        // For other namespaced actions (e.g., 'github.preflight', 'workflow.update_phase'),
+        // return the full identifier as the action type
+        if (isNamespacedAction(uses)) {
+            return uses;
+        }
+    }
+    // Check 'action' field as fallback
+    const action = step.action;
+    if (action) {
+        // Check for compound namespace patterns first
+        if (action.startsWith('speckit.') || action.startsWith('speckit/')) {
+            return 'speckit';
+        }
+        if (action === 'workspace.prepare' || action === 'workspace-prepare') {
+            return 'workspace.prepare';
+        }
+        if (action === 'agent.invoke' || action === 'agent-invoke') {
+            return 'agent.invoke';
+        }
+        if (action === 'verification.check' || action === 'verification-check' || action === 'test' || action === 'lint') {
+            return 'verification.check';
+        }
+        if (action === 'pr.create' || action === 'pr-create') {
+            return 'pr.create';
+        }
+        if (action === 'humancy.request_review' || action === 'humancy-request-review') {
+            return 'humancy.request_review';
+        }
+        if (action === 'shell' || action === 'run') {
+            return 'shell';
+        }
+        // For other namespaced actions, return the full identifier
+        if (isNamespacedAction(action)) {
+            return action;
+        }
+    }
+    // If step has command or script, treat as shell
+    if (step.command || step.script) {
+        return 'shell';
+    }
+    // Default to shell for unknown actions
+    return 'shell';
+}
+//# sourceMappingURL=action.js.map

package/dist/types/action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../../src/types/action.ts"],"names":[],"mappings":"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"}

package/dist/types/events.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Execution event types.
+ * Defines events emitted during workflow execution.
+ */
+/**
+ * Execution event types
+ */
+export type ExecutionEventType = 'execution:start' | 'execution:complete' | 'execution:error' | 'execution:cancel' | 'phase:start' | 'phase:complete' | 'phase:error' | 'step:start' | 'step:complete' | 'step:error' | 'step:output' | 'action:start' | 'action:complete' | 'action:error' | 'action:retry' | 'log:append';
+/**
+ * Execution event data
+ */
+export interface ExecutionEvent {
+    type: ExecutionEventType;
+    timestamp: number;
+    workflowName: string;
+    phaseName?: string;
+    stepName?: string;
+    message?: string;
+    data?: unknown;
+}
+/**
+ * Execution event listener
+ */
+export type ExecutionEventListener = (event: ExecutionEvent) => void;
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,oBAAoB,GACpB,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,gBAAgB,GAChB,aAAa,GACb,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC"}

package/dist/types/events.js

@@ -0,0 +1,6 @@
+/**
+ * Execution event types.
+ * Defines events emitted during workflow execution.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/execution.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Execution state types.
+ * Defines runtime state for workflow execution.
+ */
+import type { PhaseDefinition, StepDefinition } from './workflow.js';
+/**
+ * Workflow execution status
+ */
+export type ExecutionStatus = 'idle' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Step execution status
+ */
+export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+/**
+ * Execution mode
+ */
+export type ExecutionMode = 'normal' | 'dry-run';
+/**
+ * Parsed workflow structure for execution
+ * Extends WorkflowDefinition with runtime-resolved values
+ */
+export interface ExecutableWorkflow {
+    /** Workflow name */
+    name: string;
+    /** Workflow description */
+    description?: string;
+    /** Workflow phases */
+    phases: PhaseDefinition[];
+    /** Resolved environment variables */
+    env?: Record<string, string>;
+    /** Default timeout */
+    timeout?: number;
+}
+/**
+ * Step execution result
+ */
+export interface StepResult {
+    /** Step name */
+    stepName: string;
+    /** Phase name containing the step */
+    phaseName: string;
+    /** Execution status */
+    status: StepStatus;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Step output */
+    output?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Exit code from command */
+    exitCode?: number;
+}
+/**
+ * Phase execution result
+ */
+export interface PhaseResult {
+    /** Phase name */
+    phaseName: string;
+    /** Execution status */
+    status: StepStatus;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Results for each step in the phase */
+    stepResults: StepResult[];
+}
+/**
+ * Workflow execution result
+ */
+export interface ExecutionResult {
+    /** Workflow name */
+    workflowName: string;
+    /** Final execution status */
+    status: ExecutionStatus;
+    /** Execution mode used */
+    mode: ExecutionMode;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Results for each phase */
+    phaseResults: PhaseResult[];
+    /** Environment variables used */
+    env: Record<string, string>;
+}
+/**
+ * Execution options
+ */
+export interface ExecutionOptions {
+    /** Execution mode */
+    mode: ExecutionMode;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Working directory */
+    cwd?: string;
+    /** Start from specific phase */
+    startPhase?: string;
+    /** Start from specific step */
+    startStep?: string;
+    /** Enable verbose output */
+    verbose?: boolean;
+}
+/**
+ * Request for executing a single step via the debug adapter.
+ * Used by DebugSession to delegate individual step execution to WorkflowExecutor.
+ */
+export interface SingleStepRequest {
+    /** The step to execute */
+    step: StepDefinition;
+    /** The phase containing the step */
+    phase: PhaseDefinition;
+    /** Execution context for variable interpolation and output storage */
+    context: unknown;
+    /** Index of the phase in the workflow */
+    phaseIndex: number;
+    /** Index of the step within the phase */
+    stepIndex: number;
+}
+/**
+ * Result from executing a single step via the debug adapter.
+ */
+export interface SingleStepResult {
+    /** Whether the step completed successfully */
+    success: boolean;
+    /** Step output (structured or string) */
+    output: unknown | null;
+    /** Error if step failed */
+    error: Error | null;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Whether the step was skipped (e.g., condition not met) */
+    skipped: boolean;
+    /** Exit code from the action handler */
+    exitCode?: number;
+}
+//# sourceMappingURL=execution.d.ts.map

package/dist/types/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/types/execution.ts"],"names":[],"mappings":"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"}

package/dist/types/execution.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execution.js.map

package/dist/types/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../src/types/execution.ts"],"names":[],"mappings":""}