@marktoflow/core 2.0.0-alpha.12 → 2.0.0-alpha.13

package/README.md

@@ -128,7 +128,9 @@ await registry.register({
 
 ## Workflow Format
 
-Workflows are written in markdown with YAML frontmatter:
+Workflows are written in markdown with YAML frontmatter. See the [examples/](https://github.com/marktoflow/marktoflow/tree/main/examples) directory for production-ready workflow templates.
+
+### Basic Example
 
 ```markdown
 ---
@@ -165,12 +167,88 @@ This workflow posts a message to Slack.
 \`\`\`yaml
 action: slack.chat.postMessage
 inputs:
-channel: '#general'
-text: '{{ inputs.message }}'
+  channel: '#general'
+  text: '{{ inputs.message }}'
 output_variable: result
 \`\`\`
 ```
 
+### Real-World Examples
+
+See these production workflows in the `examples/` directory:
+
+- **[daily-standup](https://github.com/marktoflow/marktoflow/tree/main/examples/daily-standup)** - Jira + Slack integration with AI-generated summaries
+- **[code-review](https://github.com/marktoflow/marktoflow/tree/main/examples/code-review)** - Automated GitHub PR reviews with security analysis
+- **[incident-response](https://github.com/marktoflow/marktoflow/tree/main/examples/incident-response)** - PagerDuty + Slack + Jira coordination
+- **[gmail-notification](https://github.com/marktoflow/marktoflow/tree/main/examples/gmail-notification)** - Email automation with Gmail API
+- **[web-automation](https://github.com/marktoflow/marktoflow/tree/main/examples/web-automation)** - Browser automation with Playwright
+
+### Advanced Features
+
+The core engine supports sophisticated workflow patterns:
+
+#### Control Flow
+
+```yaml
+# Conditional execution
+- action: jira.issues.getIssue
+  inputs:
+    issueKey: 'PROJ-123'
+  output_variable: issue
+
+- action: slack.chat.postMessage
+  condition: '{{ issue.fields.priority.name == "Critical" }}'
+  inputs:
+    channel: '#urgent'
+    text: 'Critical issue found!'
+```
+
+#### Loops and Iteration
+
+```yaml
+# Process multiple items
+- action: github.pulls.list
+  inputs:
+    owner: marktoflow
+    repo: marktoflow
+  output_variable: prs
+
+- action: code_review
+  for_each: '{{ prs.data }}'
+  inputs:
+    pr: '{{ item }}'
+```
+
+#### Error Handling and Retry
+
+```yaml
+- action: external_api.call
+  retry:
+    max_attempts: 3
+    backoff: exponential
+    initial_delay: 1000
+  on_error: continue
+  fallback:
+    - action: slack.chat.postMessage
+      inputs:
+        channel: '#alerts'
+        text: 'API call failed after retries'
+```
+
+#### Circuit Breaker Pattern
+
+```yaml
+tools:
+  external_api:
+    sdk: 'custom-api-client'
+    circuit_breaker:
+      failure_threshold: 5
+      timeout: 30000
+      reset_timeout: 60000
+```
+
+See [examples/tests/control-flow/](https://github.com/marktoflow/marktoflow/tree/main/examples/tests/control-flow) for more advanced patterns.
+
 ## Architecture
 
 ### Core Components
@@ -291,8 +369,73 @@ class Scheduler {
 
 ## Testing
 
+The core package includes comprehensive unit and integration tests.
+
+### Running Tests
+
 ```bash
-npm test
+# Run all tests (unit + integration)
+pnpm test
+
+# Run only unit tests
+pnpm test:unit
+
+# Run only integration tests
+pnpm test:integration
+
+# Run specific test file
+pnpm test path/to/test.ts
+
+# Run tests matching a pattern
+pnpm test:integration -t "transform"
+
+# Watch mode
+pnpm test --watch
+```
+
+### Test Structure
+
+- **Unit Tests** (`tests/`) - Fast, isolated tests for individual functions and classes
+- **Integration Tests** (`integration-tests/`) - End-to-end workflow execution tests organized by feature:
+  - `suites/built-in-operations.integration.test.ts` - Transform, filter, reduce, etc.
+  - `suites/control-flow.integration.test.ts` - If/else, loops, parallel execution
+  - `suites/error-handling.integration.test.ts` - Retry, circuit breaker, error recovery
+  - `suites/nunjucks-filters.integration.test.ts` - Template engine filters
+  - `suites/script-execution.integration.test.ts` - JavaScript script execution
+  - `suites/variable-resolution.integration.test.ts` - Template variables and context
+
+### Writing Integration Tests
+
+Integration tests use real workflow definitions and the full execution engine:
+
+```typescript
+import { loadInline, createSmartExecutor } from '../helpers/test-utils.js';
+import { WorkflowEngine } from '../../src/engine.js';
+
+const engine = new WorkflowEngine();
+
+it('should execute workflow', async () => {
+  const { workflow } = loadInline(`
+    ---
+    workflow:
+      id: test-workflow
+      name: Test Workflow
+    steps:
+      - id: step1
+        type: action
+        action: core.set
+        inputs:
+          value: "Hello"
+        output_variable: result
+    ---
+  `);
+
+  const { executor, registry } = createSmartExecutor();
+  const result = await engine.execute(workflow, {}, registry, executor);
+
+  expect(result.status).toBe(WorkflowStatus.COMPLETED);
+  expect(result.output.result).toBe('Hello');
+});
 ```
 
 ## Links

package/dist/built-in-operations.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Built-in Operations for marktoflow
+ *
+ * Provides common operations that eliminate the need for verbose script blocks:
+ * - core.set: Simple variable assignment
+ * - core.transform: Map/filter/reduce transformations
+ * - core.extract: Nested path access
+ * - core.format: Date/number/string formatting
+ * - file.read: Read files with format conversion (docx, pdf, xlsx)
+ * - file.write: Write files (text or binary)
+ */
+import { ExecutionContext } from './models.js';
+export interface SetOperationInputs {
+    [key: string]: unknown;
+}
+export interface TransformOperationInputs {
+    input: unknown[];
+    operation: 'map' | 'filter' | 'reduce' | 'find' | 'group_by' | 'unique' | 'sort';
+    expression?: string;
+    condition?: string;
+    initialValue?: unknown;
+    key?: string;
+    reverse?: boolean;
+}
+export interface ExtractOperationInputs {
+    input: unknown;
+    path: string;
+    default?: unknown;
+}
+export interface FormatOperationInputs {
+    value: unknown;
+    type: 'date' | 'number' | 'string' | 'currency' | 'json';
+    format?: string;
+    locale?: string;
+    currency?: string;
+    precision?: number;
+}
+/**
+ * Set multiple variables at once with expression resolution.
+ *
+ * Example:
+ * ```yaml
+ * action: core.set
+ * inputs:
+ *   owner: "{{ inputs.repo =~ /^([^\/]+)\// }}"
+ *   repo_name: "{{ inputs.repo =~ /\/(.+)$/ }}"
+ *   timestamp: "{{ now() }}"
+ * ```
+ */
+export declare function executeSet(inputs: SetOperationInputs, context: ExecutionContext): Record<string, unknown>;
+/**
+ * Transform arrays using common operations like map, filter, reduce.
+ *
+ * Examples:
+ *
+ * Map:
+ * ```yaml
+ * action: core.transform
+ * inputs:
+ *   input: "{{ oncall_response.data.oncalls }}"
+ *   operation: map
+ *   expression: "@{{ item.user.name }}"
+ * ```
+ *
+ * Filter:
+ * ```yaml
+ * action: core.transform
+ * inputs:
+ *   input: "{{ issues }}"
+ *   operation: filter
+ *   condition: "item.priority == 'high'"
+ * ```
+ *
+ * Reduce:
+ * ```yaml
+ * action: core.transform
+ * inputs:
+ *   input: "{{ numbers }}"
+ *   operation: reduce
+ *   expression: "{{ accumulator + item }}"
+ *   initialValue: 0
+ * ```
+ */
+export declare function executeTransform(rawInputs: TransformOperationInputs, resolvedInputs: Record<string, unknown>, context: ExecutionContext): unknown;
+/**
+ * Extract values from nested objects safely.
+ *
+ * Example:
+ * ```yaml
+ * action: core.extract
+ * inputs:
+ *   input: "{{ api_response }}"
+ *   path: "data.users[0].email"
+ *   default: "unknown@example.com"
+ * ```
+ */
+export declare function executeExtract(inputs: ExtractOperationInputs, context: ExecutionContext): unknown;
+/**
+ * Format values for display (dates, numbers, strings, currency).
+ *
+ * Examples:
+ *
+ * Date:
+ * ```yaml
+ * action: core.format
+ * inputs:
+ *   value: "{{ now() }}"
+ *   type: date
+ *   format: "YYYY-MM-DD HH:mm:ss"
+ * ```
+ *
+ * Number:
+ * ```yaml
+ * action: core.format
+ * inputs:
+ *   value: 1234.56
+ *   type: number
+ *   precision: 2
+ * ```
+ *
+ * Currency:
+ * ```yaml
+ * action: core.format
+ * inputs:
+ *   value: 1234.56
+ *   type: currency
+ *   currency: USD
+ *   locale: en-US
+ * ```
+ */
+export declare function executeFormat(inputs: FormatOperationInputs, context: ExecutionContext): string;
+/**
+ * Execute a built-in operation based on action name
+ */
+export declare function executeBuiltInOperation(action: string, rawInputs: Record<string, unknown>, resolvedInputs: Record<string, unknown>, context: ExecutionContext): unknown | Promise<unknown>;
+/**
+ * Check if an action is a built-in operation
+ */
+export declare function isBuiltInOperation(action: string): boolean;
+//# sourceMappingURL=built-in-operations.d.ts.map

package/dist/built-in-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-operations.d.ts","sourceRoot":"","sources":["../src/built-in-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQ/C,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,wBAAwB,EACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CA4CT;AAsKD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAkBT;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAsBR;AAiHD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,gBAAgB,GACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAsB5B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1D"}