cli4ai 1.2.5 → 1.2.6

package/dist/core/routine-engine.d.ts

@@ -1,6 +1,39 @@
 /**
  * Structured routine runner (v1).
  */
+import { EventEmitter } from 'events';
+/**
+ * Event emitter for routine execution events.
+ * Used by the dashboard for real-time updates.
+ */
+export declare const routineEvents: EventEmitter<[never]>;
+export interface RoutineRunStartedEvent {
+    runId: string;
+    routineName: string;
+    triggerType: 'scheduled' | 'manual' | 'api';
+}
+export interface RoutineLogEvent {
+    runId: string;
+    stream: 'stdout' | 'stderr';
+    line: string;
+    stepId?: string;
+}
+export interface RoutineStepEvent {
+    runId: string;
+    stepId: string;
+    stepType: string;
+    status: 'running' | 'success' | 'failed' | 'skipped' | 'caught';
+    exitCode?: number;
+    durationMs?: number;
+    stdout?: string;
+    stderr?: string;
+}
+export interface RoutineRunFinishedEvent {
+    runId: string;
+    status: 'success' | 'failed';
+    exitCode: number;
+    durationMs: number;
+}
 export declare class RoutineParseError extends Error {
     path: string;
     constructor(path: string, message: string);
@@ -63,6 +96,32 @@ export interface RoutineExecStep extends RoutineBaseStep {
     capture?: Exclude<StepCapture, 'inherit'>;
 }
 export type RoutineStep = RoutineC4aiStep | RoutineSetStep | RoutineExecStep;
+export interface RoutineParallelGroup {
+    /** Steps to execute in parallel (only cli4ai and exec allowed) */
+    parallel: RoutineStep[];
+    /** If true (default), fail immediately on first error. If false, wait for all to complete. */
+    failFast?: boolean;
+}
+export interface RoutineTryBlock {
+    /** Steps to attempt */
+    try: RoutineStep[];
+    /** Steps to run if any try step fails (has access to {{error}} context) */
+    catch?: RoutineStep[];
+    /** Steps to always run after try/catch */
+    finally?: RoutineStep[];
+}
+/** Error context available in catch blocks via {{error}} */
+export interface ErrorContext {
+    stepId: string;
+    stepType: string;
+    code: string;
+    message: string;
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+}
+/** A step entry can be a regular step, parallel group, or try block */
+export type RoutineStepEntry = RoutineStep | RoutineParallelGroup | RoutineTryBlock;
 export interface RoutineDefinition {
     version: 1;
     name: string;
@@ -74,13 +133,13 @@ export interface RoutineDefinition {
     vars?: Record<string, RoutineVarDef>;
     /** Schedule configuration for automatic execution */
     schedule?: RoutineSchedule;
-    steps: RoutineStep[];
+    steps: RoutineStepEntry[];
     result?: unknown;
 }
 export interface StepRunResult {
     id: string;
-    type: RoutineStep['type'];
-    status: 'success' | 'failed' | 'skipped';
+    type: RoutineStep['type'] | 'parallel' | 'try';
+    status: 'success' | 'failed' | 'skipped' | 'caught';
     exitCode?: number;
     durationMs?: number;
     stdout?: string;
@@ -103,9 +162,16 @@ export interface RoutineRunSummary {
     result?: unknown;
 }
 export interface RoutineDryRunStep {
-    id: string;
-    type: RoutineStep['type'];
-    rendered: Record<string, unknown>;
+    id?: string;
+    type: RoutineStep['type'] | 'parallel' | 'try';
+    rendered?: Record<string, unknown>;
+    /** For parallel groups */
+    steps?: RoutineDryRunStep[];
+    failFast?: boolean;
+    /** For try blocks */
+    try?: RoutineDryRunStep[];
+    catch?: RoutineDryRunStep[];
+    finally?: RoutineDryRunStep[];
 }
 export interface RoutineDryRunPlan {
     routine: string;
@@ -115,10 +181,28 @@ export interface RoutineDryRunPlan {
     result?: unknown;
 }
 export declare function loadRoutineDefinition(path: string): RoutineDefinition;
+/**
+ * Serialize a routine definition to YAML or JSON string.
+ */
+export declare function serializeRoutineDefinition(def: RoutineDefinition, format?: 'yaml' | 'json'): string;
 /**
  * Validate a schedule configuration.
  * Exported for use by scheduler and tests.
  */
 export declare function validateScheduleConfig(schedule: unknown, source?: string): RoutineSchedule;
+export declare function isParallelGroup(entry: unknown): entry is RoutineParallelGroup;
+export declare function isTryBlock(entry: unknown): entry is RoutineTryBlock;
 export declare function dryRunRoutine(def: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineDryRunPlan>;
 export declare function runRoutine(def: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineRunSummary>;
+export interface TrackedRunOptions {
+    runId?: string;
+    triggerType?: 'scheduled' | 'manual' | 'api';
+}
+export interface TrackedRunResult extends RoutineRunSummary {
+    runId: string;
+}
+/**
+ * Run a routine with event emissions for real-time tracking.
+ * Emits events: run:started, run:log, run:step, run:finished
+ */
+export declare function runRoutineTracked(def: RoutineDefinition, vars: Record<string, string>, invocationDir: string, options?: TrackedRunOptions): Promise<TrackedRunResult>;