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

package/dist/types/gate.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Gate types for workflow review checkpoints.
+ * Gates allow workflows to pause for human approval at defined points.
+ */
+import type { ExecutableWorkflow } from './execution.js';
+import type { PhaseDefinition, StepDefinition } from './workflow.js';
+import type { ActionResult } from './action.js';
+/**
+ * Standard gate types for speckit workflows
+ */
+export type GateType = 'spec-review' | 'clarification-review' | 'plan-review' | 'tasks-review' | 'implementation-review' | string;
+/**
+ * Gate configuration options
+ */
+export interface GateConfig {
+    /** Gate identifier */
+    type: GateType;
+    /**
+     * Timeout before auto-action in milliseconds.
+     * Default: undefined (indefinite wait)
+     */
+    timeout_ms?: number;
+    /**
+     * Action to take on timeout.
+     * - 'approve': Auto-approve and continue
+     * - 'reject': Fail the step
+     * - 'block': Keep waiting (default)
+     */
+    timeout_action?: 'approve' | 'reject' | 'block';
+    /** Custom approval handler (optional) */
+    handler?: GateHandler;
+}
+/**
+ * Context passed to gate handlers
+ */
+export interface GateContext {
+    /** The full workflow being executed */
+    workflow: ExecutableWorkflow;
+    /** Current phase containing the gated step */
+    phase: PhaseDefinition;
+    /** The step with the gate */
+    step: StepDefinition;
+    /** Result from executing the step (before gate) */
+    stepResult: ActionResult;
+    /** The gate type string from step.gate */
+    gateType: string;
+    /** Workflow execution ID for state tracking */
+    executionId?: string;
+}
+/**
+ * Result from gate approval check
+ */
+export interface GateResult {
+    /** Whether the gate was approved */
+    approved: boolean;
+    /** Who approved/rejected (username or 'system') */
+    approvedBy?: string;
+    /** Optional comments from reviewer */
+    comments?: string;
+    /** Whether the result was due to timeout */
+    timedOut?: boolean;
+    /** Timestamp of the decision */
+    decidedAt?: string;
+}
+/**
+ * Interface for custom gate handlers.
+ * Implementations can integrate with external approval systems.
+ */
+export interface GateHandler {
+    /**
+     * Check if gate is already approved (non-blocking).
+     * Called first to see if approval exists without waiting.
+     */
+    checkApproval(context: GateContext): Promise<boolean>;
+    /**
+     * Wait for approval with optional timeout.
+     * Called if checkApproval returns false.
+     */
+    waitForApproval(context: GateContext, timeoutMs?: number): Promise<GateResult>;
+    /**
+     * Optional: Notify reviewers that approval is needed.
+     * Called before waitForApproval.
+     */
+    requestApproval?(context: GateContext): Promise<void>;
+}
+/**
+ * Default gate handler that always blocks.
+ * Workflows should be resumed manually after human review.
+ */
+export declare class DefaultGateHandler implements GateHandler {
+    checkApproval(_context: GateContext): Promise<boolean>;
+    waitForApproval(context: GateContext, timeoutMs?: number): Promise<GateResult>;
+}
+/**
+ * Parse gate string into GateConfig
+ */
+export declare function parseGateConfig(gateString: string): GateConfig;
+//# sourceMappingURL=gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/types/gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB,aAAa,GACb,sBAAsB,GACtB,aAAa,GACb,cAAc,GACd,uBAAuB,GACvB,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,IAAI,EAAE,QAAQ,CAAC;IAEf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAEhD,yCAAyC;IACzC,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAE7B,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IAEvB,6BAA6B;IAC7B,IAAI,EAAE,cAAc,CAAC;IAErB,mDAAmD;IACnD,UAAU,EAAE,YAAY,CAAC;IAEzB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IAEjB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAElB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/E;;;OAGG;IACH,eAAe,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IAC9C,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtD,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAqBrF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAM9D"}

package/dist/types/gate.js

@@ -0,0 +1,41 @@
+/**
+ * Default gate handler that always blocks.
+ * Workflows should be resumed manually after human review.
+ */
+export class DefaultGateHandler {
+    async checkApproval(_context) {
+        // Default: not pre-approved, requires explicit decision
+        return false;
+    }
+    async waitForApproval(context, timeoutMs) {
+        // Default implementation: pause workflow (never auto-approve)
+        // The workflow will need to be resumed with explicit decision
+        if (timeoutMs === undefined) {
+            // Indefinite wait - workflow pauses
+            return {
+                approved: false,
+                approvedBy: 'system',
+                comments: `Workflow paused at gate: ${context.gateType}. Resume with explicit approval.`,
+                timedOut: false,
+            };
+        }
+        // With timeout, we could implement polling, but default blocks
+        return {
+            approved: false,
+            approvedBy: 'system',
+            comments: `Gate timeout (${timeoutMs}ms). Workflow paused.`,
+            timedOut: true,
+        };
+    }
+}
+/**
+ * Parse gate string into GateConfig
+ */
+export function parseGateConfig(gateString) {
+    // Simple format: just the gate type
+    // Could be extended to parse "type:timeout:action" format
+    return {
+        type: gateString,
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/types/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/types/gate.ts"],"names":[],"mappings":"AA+GA;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B,KAAK,CAAC,aAAa,CAAC,QAAqB;QACvC,wDAAwD;QACxD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAoB,EAAE,SAAkB;QAC5D,8DAA8D;QAC9D,8DAA8D;QAC9D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,oCAAoC;YACpC,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,UAAU,EAAE,QAAQ;gBACpB,QAAQ,EAAE,4BAA4B,OAAO,CAAC,QAAQ,kCAAkC;gBACxF,QAAQ,EAAE,KAAK;aAChB,CAAC;QACJ,CAAC;QAED,+DAA+D;QAC/D,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,iBAAiB,SAAS,uBAAuB;YAC3D,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,oCAAoC;IACpC,0DAA0D;IAC1D,OAAO;QACL,IAAI,EAAE,UAAsB;KAC7B,CAAC;AACJ,CAAC"}