@octaviaflow/flow-rules 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @octaviaflow/flow-rules
+
+The flow **action catalog** and the **rules engine behind Flow Doctor** — the
+two things that decide what a step accepts and whether a flow works.
+
+## Why this exists
+
+Both lived in `octaviaflow-ui`, so both were reachable only from a browser.
+That was fine while the editor was the only thing building flows. It stopped
+being fine when an AI agent became a second author (DEV-391):
+
+- an agent that cannot read an action's `inputSchema` **guesses** at the
+  config, and a guessed config is a flow that fails at run time on the
+  customer's live systems;
+- an agent that cannot run the rules cannot tell whether what it built works,
+  so it reports success and hands over a broken flow.
+
+Copying either into Backend would have produced two rule sets that agree on
+the day they are written — the same failure mode as a duplicated permission
+predicate, and the copy that drifts would be the one the agent trusts.
+
+So they live here, and both the editor and the server import them. The editor
+keeps validating in-process on every structural canvas change; Backend gets
+the identical verdict for `check_flow`.
+
+## What is and is not here
+
+**Here:** the `ActionDefinition` catalog (ids, descriptions, `inputSchema`,
+`outputSchema`), the workflow validator, node config status, and the id
+generators, so a caller building a flow makes ids the editor recognises.
+
+**Not here:** React. The config **panels** stay in `octaviaflow-ui` — a
+component in this package would make it unusable from Backend, which is the
+whole point. `ActionDefinition.icon` is a string key the consumer's catalog
+adapter resolves; this package never names a component.
+
+## Usage
+
+```ts
+import {
+  getAllActions,
+  getActionById,
+  validateWorkflow,
+  getNodeConfigStatus,
+} from "@octaviaflow/flow-rules";
+
+// What may this step be configured with?
+const action = getActionById("http_request");
+const required = action?.inputSchema.fields.filter((f) => f.validation?.required);
+
+// Does this flow work?
+const { isValid, errors, warnings } = validateWorkflow(nodes, edges);
+```
+
+### The severity contract
+
+Unchanged from rules-v2 (DEV-220, ADR-flow-pause-and-rules-v2):
+
+| | |
+|---|---|
+| `error` | the flow cannot work as built. **Blocks activation.** |
+| `warning` | it will run, but probably not the way the author thinks. Blocks nothing. |
+
+**Saving is never blocked.** A caller that treats a warning as a failure will
+refuse flows the editor accepts.
+
+### One field name worth knowing
+
+A node names its action with **`actionDefinitionId`**, not `actionId`. The
+latter looks right and silently matches nothing — which is exactly the kind of
+mistake this package exists to stop an agent making.
+
+## Commands
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build      # tsc → dist (ESM + .d.ts), which is what consumers get
+```
+
+It ships **built** ESM plus declarations rather than raw TypeScript
+(`@octaviaflow/connector-crypto` ships source, but that package is only
+consumed by Bun services — `octaviaflow-ui` is Next.js and would need
+`transpilePackages` for source).
+
+## Consumers
+
+| Repo | Uses |
+|---|---|
+| `octaviaflow-ui` | the editor: catalog, live validation, node status badges |
+| `Octaviaflow-Backend` | `check_flow` and the agent authoring routes it serves |
+| `Octaviaflow-MCP` | indirectly, through Backend |
+
+A change to a rule or an action schema changes what the agent may build. Run
+both consumers' suites before publishing.

package/dist/catalog/actions/console-log/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Console Log Configuration
+ *
+ * Defines the configuration structure and default values for the Console Log action
+ */
+export interface ConsoleLogConfigType {
+    message: string;
+    level?: 'info' | 'warning' | 'error' | 'debug';
+    data?: unknown;
+    /**
+     * When false, the previous step's output is NOT dumped after the
+     * custom message — only the message prints. Useful for summary
+     * "Done" logs following a ForEach that would otherwise spew the
+     * entire iteration result. Defaults to true (legacy behavior).
+     */
+    includeInputData?: boolean;
+}
+export declare const ConsoleLogConfig: {
+    /**
+     * Default configuration for Console Log
+     */
+    defaults: ConsoleLogConfigType;
+    /**
+     * Configuration schema for validation
+     */
+    schema: {
+        message: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        level: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        data: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    /**
+     * Validate configuration
+     */
+    validate: (config: Partial<ConsoleLogConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Merge user config with defaults
+     */
+    merge: (userConfig: Partial<ConsoleLogConfigType>) => ConsoleLogConfigType;
+    /**
+     * Get display label for configuration
+     */
+    getLabel: (config: ConsoleLogConfigType) => string;
+};

package/dist/catalog/actions/console-log/config.js

@@ -0,0 +1,70 @@
+/**
+ * Console Log Configuration
+ *
+ * Defines the configuration structure and default values for the Console Log action
+ */
+export const ConsoleLogConfig = {
+    /**
+     * Default configuration for Console Log
+     */
+    defaults: {
+        message: '',
+        level: 'info',
+        data: undefined,
+        includeInputData: true,
+    },
+    /**
+     * Configuration schema for validation
+     */
+    schema: {
+        message: {
+            type: 'string',
+            required: true,
+            description: 'Message to log',
+        },
+        level: {
+            type: 'select',
+            required: false,
+            description: 'Log level for the message',
+        },
+        data: {
+            type: 'json',
+            required: false,
+            description: 'Additional data to log',
+        },
+    },
+    /**
+     * Validate configuration
+     */
+    validate: (config) => {
+        const errors = [];
+        if (!config.message) {
+            errors.push('Message is required');
+        }
+        else if (typeof config.message !== 'string') {
+            errors.push('Message must be a string');
+        }
+        if (config.level && !['info', 'warning', 'error', 'debug'].includes(config.level)) {
+            errors.push('Invalid log level');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    },
+    /**
+     * Merge user config with defaults
+     */
+    merge: (userConfig) => {
+        return {
+            ...ConsoleLogConfig.defaults,
+            ...userConfig,
+        };
+    },
+    /**
+     * Get display label for configuration
+     */
+    getLabel: (config) => {
+        return `Log [${config.level}]: ${config.message}`;
+    },
+};

package/dist/catalog/actions/console-log/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Console Log Action
+ *
+ * Log messages to the workflow console for debugging and monitoring
+ */
+import { ActionDefinition } from '../../types';
+export declare const consoleLogDefinition: ActionDefinition;

package/dist/catalog/actions/console-log/index.js

@@ -0,0 +1,89 @@
+/**
+ * Console Log Action
+ *
+ * Log messages to the workflow console for debugging and monitoring
+ */
+import { ActionCategory, ActionType, ActionStatus, FieldType } from '../../types';
+export const consoleLogDefinition = {
+    id: 'console_log',
+    name: 'Console Log',
+    description: 'Log messages to the workflow console for debugging',
+    category: ActionCategory.Utility,
+    type: ActionType.Console,
+    tags: ['utility', 'logging', 'debug', 'built-in'],
+    status: ActionStatus.Stable,
+    icon: 'Terminal',
+    color: '#525252',
+    inputSchema: {
+        fields: [
+            {
+                key: 'message',
+                label: 'Message',
+                type: FieldType.String,
+                description: 'Message to log',
+                placeholder: 'e.g., Processing user data...',
+                validation: { required: true },
+            },
+            {
+                key: 'level',
+                label: 'Log Level',
+                type: FieldType.Select,
+                description: 'Log level for the message',
+                defaultValue: 'info',
+                options: [
+                    { label: 'Info', value: 'info' },
+                    { label: 'Warning', value: 'warning' },
+                    { label: 'Error', value: 'error' },
+                    { label: 'Debug', value: 'debug' },
+                ],
+                validation: { required: true },
+            },
+            {
+                key: 'data',
+                label: 'Data',
+                type: FieldType.JSON,
+                description: 'Additional data to log',
+                validation: { required: false },
+            },
+            {
+                key: 'includeInputData',
+                label: 'Include previous step output',
+                type: FieldType.Boolean,
+                description: 'When off, only the custom message prints — useful for summary "Done" logs that follow a ForEach.',
+                defaultValue: true,
+                validation: { required: false },
+            },
+        ],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: [
+            {
+                key: 'logged',
+                type: FieldType.Boolean,
+                description: 'Whether the message was successfully logged',
+            },
+            {
+                key: 'timestamp',
+                type: FieldType.DateTime,
+                description: 'Timestamp of the log entry',
+            },
+            {
+                key: 'level',
+                type: FieldType.String,
+                description: 'Log level used',
+            },
+        ],
+        sampleOutput: {
+            logged: true,
+            timestamp: new Date().toISOString(),
+            level: 'info',
+        },
+    },
+    version: '1.0.0',
+    createdAt: '2025-01-01T00:00:00Z',
+    updatedAt: '2025-12-15T00:00:00Z',
+    createdBy: 'system',
+    isOfficial: true,
+    testable: true,
+};

package/dist/catalog/actions/delay/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Delay Configuration
+ *
+ * Defines the configuration structure and default values for the Delay action
+ */
+export interface DelayConfigType {
+    duration: number;
+    unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours';
+}
+export declare const DelayConfig: {
+    /**
+     * Default configuration for Delay
+     */
+    defaults: DelayConfigType;
+    /**
+     * Configuration schema for validation
+     */
+    schema: {
+        duration: {
+            type: string;
+            required: boolean;
+            description: string;
+            min: number;
+        };
+        unit: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    /**
+     * Validate configuration
+     */
+    validate: (config: Partial<DelayConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Convert duration to milliseconds
+     */
+    toMilliseconds: (duration: number, unit?: string) => number;
+    /**
+     * Merge user config with defaults
+     */
+    merge: (userConfig: Partial<DelayConfigType>) => DelayConfigType;
+    /**
+     * Get display label for configuration
+     */
+    getLabel: (config: DelayConfigType) => string;
+};

package/dist/catalog/actions/delay/config.js

@@ -0,0 +1,79 @@
+/**
+ * Delay Configuration
+ *
+ * Defines the configuration structure and default values for the Delay action
+ */
+export const DelayConfig = {
+    /**
+     * Default configuration for Delay
+     */
+    defaults: {
+        duration: 1000,
+        unit: 'milliseconds',
+    },
+    /**
+     * Configuration schema for validation
+     */
+    schema: {
+        duration: {
+            type: 'number',
+            required: true,
+            description: 'Duration to delay',
+            min: 0,
+        },
+        unit: {
+            type: 'select',
+            required: false,
+            description: 'Time unit for the duration',
+        },
+    },
+    /**
+     * Validate configuration
+     */
+    validate: (config) => {
+        const errors = [];
+        if (config.duration === undefined || config.duration === null) {
+            errors.push('Duration is required');
+        }
+        else if (typeof config.duration !== 'number') {
+            errors.push('Duration must be a number');
+        }
+        else if (config.duration < 0) {
+            errors.push('Duration must be non-negative');
+        }
+        if (config.unit && !['milliseconds', 'seconds', 'minutes', 'hours'].includes(config.unit)) {
+            errors.push('Invalid time unit');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    },
+    /**
+     * Convert duration to milliseconds
+     */
+    toMilliseconds: (duration, unit = 'milliseconds') => {
+        const multipliers = {
+            milliseconds: 1,
+            seconds: 1000,
+            minutes: 60000,
+            hours: 3600000,
+        };
+        return duration * (multipliers[unit] || 1);
+    },
+    /**
+     * Merge user config with defaults
+     */
+    merge: (userConfig) => {
+        return {
+            ...DelayConfig.defaults,
+            ...userConfig,
+        };
+    },
+    /**
+     * Get display label for configuration
+     */
+    getLabel: (config) => {
+        return `Delay ${config.duration}${config.unit ? ' ' + config.unit : 'ms'}`;
+    },
+};

package/dist/catalog/actions/delay/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Delay Action
+ *
+ * Pause workflow execution for a specified duration
+ */
+import { ActionDefinition } from '../../types';
+export declare const delayDefinition: ActionDefinition;

package/dist/catalog/actions/delay/index.js

@@ -0,0 +1,71 @@
+/**
+ * Delay Action
+ *
+ * Pause workflow execution for a specified duration
+ */
+import { ActionCategory, ActionType, ActionStatus, FieldType } from '../../types';
+export const delayDefinition = {
+    id: 'delay',
+    name: 'Delay',
+    description: 'Pause workflow execution for a specified duration',
+    category: ActionCategory.Utility,
+    type: ActionType.Delay,
+    tags: ['utility', 'delay', 'wait', 'built-in'],
+    status: ActionStatus.Stable,
+    icon: 'Timer',
+    color: '#8f8f8f',
+    inputSchema: {
+        fields: [
+            {
+                key: 'duration',
+                label: 'Duration (ms)',
+                type: FieldType.Number,
+                description: 'Duration to delay in milliseconds',
+                defaultValue: 1000,
+                validation: { required: true, min: 0 },
+            },
+            {
+                key: 'unit',
+                label: 'Unit',
+                type: FieldType.Select,
+                description: 'Time unit for the duration',
+                defaultValue: 'milliseconds',
+                options: [
+                    { label: 'Milliseconds', value: 'milliseconds' },
+                    { label: 'Seconds', value: 'seconds' },
+                    { label: 'Minutes', value: 'minutes' },
+                    { label: 'Hours', value: 'hours' },
+                ],
+                validation: { required: true },
+            },
+        ],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: [
+            {
+                key: 'delayedFor',
+                type: FieldType.Number,
+                description: 'Actual delay duration in milliseconds',
+            },
+            {
+                key: 'completedAt',
+                type: FieldType.DateTime,
+                description: 'Timestamp when delay completed',
+            },
+        ],
+        sampleOutput: {
+            delayedFor: 1000,
+            completedAt: new Date().toISOString(),
+        },
+    },
+    execution: {
+        timeout: 3600000,
+    },
+    version: '1.0.0',
+    createdAt: '2025-01-01T00:00:00Z',
+    updatedAt: '2025-12-15T00:00:00Z',
+    createdBy: 'system',
+    isOfficial: true,
+    testable: true,
+};

package/dist/catalog/actions/delay/migrate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Migration shim — legacy `{ duration, unit }` Delay config → v2 multi-mode shape.
+ *
+ * Runs at read time in both UI (panel renders v2 shape) and Engine (executor
+ * dispatches v2 modes). One-way and pure: persisted v1 configs stay v1 on
+ * disk until a user explicitly saves the step in the v2 UI panel.
+ *
+ * Detection rule: a config is v2 when it has a `mode` property; otherwise
+ * treat as v1 and rewrite to fixed-mode with the legacy duration/unit.
+ *
+ * See implementation doc §5.7 for design rationale.
+ */
+import type { DelayConfig } from './types';
+/**
+ * Convert any persisted Delay config (v1 legacy or v2 multi-mode) into the v2
+ * `DelayConfig` shape. Always safe to call — passes v2 inputs through unchanged.
+ */
+export declare function migrateDelayConfig(raw: unknown): DelayConfig;

package/dist/catalog/actions/delay/migrate.js

@@ -0,0 +1,38 @@
+/**
+ * Migration shim — legacy `{ duration, unit }` Delay config → v2 multi-mode shape.
+ *
+ * Runs at read time in both UI (panel renders v2 shape) and Engine (executor
+ * dispatches v2 modes). One-way and pure: persisted v1 configs stay v1 on
+ * disk until a user explicitly saves the step in the v2 UI panel.
+ *
+ * Detection rule: a config is v2 when it has a `mode` property; otherwise
+ * treat as v1 and rewrite to fixed-mode with the legacy duration/unit.
+ *
+ * See implementation doc §5.7 for design rationale.
+ */
+const LEGACY_UNITS = new Set([
+    'milliseconds',
+    'seconds',
+    'minutes',
+    'hours',
+]);
+/**
+ * Convert any persisted Delay config (v1 legacy or v2 multi-mode) into the v2
+ * `DelayConfig` shape. Always safe to call — passes v2 inputs through unchanged.
+ */
+export function migrateDelayConfig(raw) {
+    if (raw && typeof raw === 'object' && 'mode' in raw) {
+        return raw;
+    }
+    const legacy = (raw ?? {});
+    const duration = typeof legacy.duration === 'number' && Number.isFinite(legacy.duration)
+        ? legacy.duration
+        : 1;
+    const unit = typeof legacy.unit === 'string' && LEGACY_UNITS.has(legacy.unit)
+        ? legacy.unit
+        : 'milliseconds';
+    return {
+        mode: 'fixed',
+        fixed: { duration, unit },
+    };
+}

package/dist/catalog/actions/delay/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Delay Action — v2 type definitions.
+ *
+ * v2 turns Delay into a multi-mode primitive (fixed / until / random-jitter /
+ * expression) with per-mode configs. See architecture doc for design rationale:
+ *   (design notes live in the platform's own documentation)
+ *
+ * PR 1 ships these types alongside the legacy `config.ts`. PR 3 collapses the
+ * legacy file and rewrites the action definition (`index.ts`) against this
+ * schema.
+ */
+export type DelayMode = 'fixed' | 'until' | 'random-jitter' | 'expression';
+/**
+ * FxValue<T>: a literal T value OR an `ods://...` expression string that
+ * resolves to T at runtime.
+ *
+ * v1 status: FX is not yet a platform-wide feature. Delay ships FxValue typing
+ * as a testbed so the contract (typing + runtime resolution + tests) lands in
+ * production code before the platform-wide FX rollout. Other actions remain
+ * literal-only for now. See implementation doc §5.3 + §8.5.
+ */
+export type FxValue<T> = T | string;
+export type FixedUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours';
+export interface FixedModeConfig {
+    duration: FxValue<number>;
+    unit: FixedUnit;
+}
+export interface UntilModeConfig {
+    /** ISO 8601 datetime literal OR an `ods://` expression resolving to one. */
+    datetime: FxValue<string>;
+    /** Optional clock-skew tolerance in ms. Literal or FX. Default 0. */
+    toleranceMs?: FxValue<number>;
+}
+export interface RandomJitterModeConfig {
+    baseMs: FxValue<number>;
+    jitterMs: FxValue<number>;
+}
+export interface ExpressionModeConfig {
+    /** Resolves to either a number (ms) or a duration string ("30s", "5m"). */
+    raw: string;
+    /** Fallback when the expression evaluates to undefined / NaN. Default 0. */
+    fallbackMs?: FxValue<number>;
+}
+export interface DelayConfig {
+    mode: DelayMode;
+    /** Optional gate. When set and falsy at runtime, the step short-circuits. */
+    condition?: string;
+    fixed?: FixedModeConfig;
+    until?: UntilModeConfig;
+    randomJitter?: RandomJitterModeConfig;
+    expression?: ExpressionModeConfig;
+}
+/**
+ * Schema version. Bumped from the legacy 1.0.0 to mark the multi-mode
+ * shape. The migration shim (`migrate.ts`) detects v1 configs by the
+ * absence of `mode` and rewrites them to v2 fixed-mode equivalents.
+ */
+export declare const DELAY_CONFIG_VERSION = "2.0.0";

package/dist/catalog/actions/delay/types.js

@@ -0,0 +1,17 @@
+/**
+ * Delay Action — v2 type definitions.
+ *
+ * v2 turns Delay into a multi-mode primitive (fixed / until / random-jitter /
+ * expression) with per-mode configs. See architecture doc for design rationale:
+ *   (design notes live in the platform's own documentation)
+ *
+ * PR 1 ships these types alongside the legacy `config.ts`. PR 3 collapses the
+ * legacy file and rewrites the action definition (`index.ts`) against this
+ * schema.
+ */
+/**
+ * Schema version. Bumped from the legacy 1.0.0 to mark the multi-mode
+ * shape. The migration shim (`migrate.ts`) detects v1 configs by the
+ * absence of `mode` and rewrites them to v2 fixed-mode equivalents.
+ */
+export const DELAY_CONFIG_VERSION = '2.0.0';