@octaviaflow/flow-rules 0.1.0

package/dist/catalog/workflow.d.ts

@@ -0,0 +1,308 @@
+import { ActionDefinition } from './types';
+export interface Position {
+    x: number;
+    y: number;
+}
+export interface Dimensions {
+    width: number;
+    height: number;
+}
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare enum NodeStatus {
+    Idle = "idle",
+    Running = "running",
+    Success = "success",
+    Error = "error",
+    Warning = "warning",
+    Disabled = "disabled"
+}
+export interface NodePort {
+    id: string;
+    type: 'input' | 'output';
+    position: 'top' | 'right' | 'bottom' | 'left';
+    label?: string;
+    connected: boolean;
+    maxConnections?: number;
+}
+export interface DataSchema {
+    type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
+    properties?: Record<string, DataSchema>;
+    items?: DataSchema;
+    required?: string[];
+    description?: string;
+    example?: unknown;
+    /**
+     * Iterable list marker. When set on an array, the Field Mapper treats
+     * the node as expandable regardless of whether items.properties are
+     * known — covering empty-sample and primitive-item arrays the user
+     * still wants to loop over (legacy `loopable` semantics).
+     */
+    loopable?: boolean;
+}
+export interface WorkflowNode {
+    id: string;
+    type: 'action' | 'trigger' | 'condition' | 'transform' | 'group' | 'forEach';
+    actionDefinitionId: string;
+    actionDefinition?: ActionDefinition;
+    name?: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    position: Position;
+    dimensions?: Dimensions;
+    parentId?: string;
+    extent?: 'parent';
+    disabled?: boolean;
+    config: Record<string, unknown>;
+    configStatus?: 'valid' | 'warning' | 'error' | 'unconfigured' | 'hidden';
+    ports: {
+        input: NodePort[];
+        output: NodePort[];
+    };
+    inputSchema?: DataSchema;
+    outputSchema?: DataSchema;
+    status: NodeStatus;
+    selected: boolean;
+    dragging: boolean;
+    isValid: boolean;
+    validationErrors?: string[];
+    expanded: boolean;
+    minimized: boolean;
+    locked: boolean;
+    executionData?: {
+        lastRun?: string;
+        duration?: number;
+        output?: unknown;
+        error?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    notes?: string;
+}
+export declare enum EdgeType {
+    Default = "default",
+    Conditional = "conditional",
+    Loop = "loop",
+    Error = "error"
+}
+export interface EdgeStyle {
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    animated?: boolean;
+}
+export interface WorkflowEdge {
+    id: string;
+    type: EdgeType;
+    source: string;
+    sourcePort: string;
+    target: string;
+    targetPort: string;
+    style?: EdgeStyle;
+    label?: string;
+    condition?: string;
+    selected: boolean;
+    animated: boolean;
+    createdAt: string;
+}
+export interface CanvasViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export interface CanvasSettings {
+    snapToGrid: boolean;
+    gridSize: number;
+    showGrid: boolean;
+    showMinimap: boolean;
+    autoLayout: boolean;
+    useAdvancedLayout: boolean;
+    theme: 'light' | 'dark';
+}
+export interface WorkflowCanvasState {
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    viewport: CanvasViewport;
+    selectedNodes: string[];
+    selectedEdges: string[];
+    isDragging: boolean;
+    isPanning: boolean;
+    isConnecting: boolean;
+    connectingFrom?: {
+        nodeId: string;
+        portId: string;
+        portType: 'input' | 'output';
+    };
+    settings: CanvasSettings;
+    history: {
+        past: WorkflowCanvasState[];
+        future: WorkflowCanvasState[];
+    };
+}
+export type WorkflowAction = {
+    type: 'ADD_NODE';
+    payload: WorkflowNode;
+} | {
+    type: 'UPDATE_NODE';
+    payload: {
+        id: string;
+        updates: Partial<WorkflowNode>;
+    };
+} | {
+    type: 'DELETE_NODE';
+    payload: string;
+} | {
+    type: 'DELETE_NODES';
+    payload: string[];
+} | {
+    type: 'ADD_EDGE';
+    payload: WorkflowEdge;
+} | {
+    type: 'DELETE_EDGE';
+    payload: string;
+} | {
+    type: 'DELETE_EDGES';
+    payload: string[];
+} | {
+    type: 'SELECT_NODE';
+    payload: string;
+} | {
+    type: 'SELECT_NODES';
+    payload: string[];
+} | {
+    type: 'SELECT_EDGE';
+    payload: string;
+} | {
+    type: 'DESELECT_ALL';
+} | {
+    type: 'UPDATE_VIEWPORT';
+    payload: Partial<CanvasViewport>;
+} | {
+    type: 'UPDATE_SETTINGS';
+    payload: Partial<CanvasSettings>;
+} | {
+    type: 'START_CONNECTING';
+    payload: {
+        nodeId: string;
+        portId: string;
+        portType: 'input' | 'output';
+    };
+} | {
+    type: 'END_CONNECTING';
+} | {
+    type: 'UNDO';
+} | {
+    type: 'REDO';
+} | {
+    type: 'RESET';
+};
+export interface DraggedAction {
+    actionDefinition: ActionDefinition;
+    type: 'action';
+}
+export interface DropPosition {
+    x: number;
+    y: number;
+    canvasX: number;
+    canvasY: number;
+}
+export interface LayoutOptions {
+    algorithm: 'dagre' | 'elk' | 'manual';
+    direction: 'TB' | 'BT' | 'LR' | 'RL';
+    spacing: {
+        node: number;
+        rank: number;
+    };
+    align?: 'UL' | 'UR' | 'DL' | 'DR';
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+export interface ValidationIssue {
+    /** Stable identity for the issue (rule + anchor) — list keys, dedupe. */
+    id: string;
+    type: 'node' | 'edge' | 'workflow';
+    severity: 'error' | 'warning';
+    message: string;
+    nodeId?: string;
+    edgeId?: string;
+}
+/** Back-compat aliases (same shape since DEV-220). */
+export type ValidationError = ValidationIssue;
+export type ValidationWarning = ValidationIssue;
+export interface ExecutionState {
+    status: 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+    startedAt?: string;
+    completedAt?: string;
+    currentNodeId?: string;
+    nodeStates: Record<string, NodeExecutionState>;
+}
+export interface NodeExecutionState {
+    status: 'pending' | 'running' | 'success' | 'error' | 'skipped';
+    startedAt?: string;
+    completedAt?: string;
+    duration?: number;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    logs?: string[];
+}
+export interface WorkflowMetadata {
+    id: string;
+    name: string;
+    description?: string;
+    projectId: string;
+    version: string;
+    status: 'draft' | 'active' | 'paused' | 'archived';
+    createdAt: string;
+    updatedAt: string;
+    createdBy: string;
+    tags: string[];
+}
+export interface Workflow {
+    metadata: WorkflowMetadata;
+    canvas: WorkflowCanvasState;
+    policies: import('./policies').WorkflowPolicies;
+    validation: ValidationResult;
+    execution?: ExecutionState;
+}
+export interface WorkflowContextValue {
+    workflow: Workflow;
+    dispatch: (action: WorkflowAction) => void;
+    addNode: (actionDefinition: ActionDefinition, position: Position) => void;
+    updateNode: (id: string, updates: Partial<WorkflowNode>) => void;
+    deleteNode: (id: string) => void;
+    deleteNodes: (ids: string[]) => void;
+    addEdge: (source: string, sourcePort: string, target: string, targetPort: string) => void;
+    deleteEdge: (id: string) => void;
+    startConnecting: (nodeId: string, portId: string, portType: 'input' | 'output') => void;
+    endConnecting: () => void;
+    selectNode: (id: string, multi?: boolean) => void;
+    selectEdge: (id: string) => void;
+    deselectAll: () => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    zoomToFit: () => void;
+    resetViewport: () => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    validate: () => ValidationResult;
+    executeWorkflow: () => Promise<void>;
+    stopExecution: () => void;
+}
+export type NodeMap = Map<string, WorkflowNode>;
+export type EdgeMap = Map<string, WorkflowEdge>;
+export interface ConnectionValidation {
+    valid: boolean;
+    reason?: string;
+}

package/dist/catalog/workflow.js

@@ -0,0 +1,25 @@
+// ============================================
+// workflow.d.ts - Workflow Canvas Type Definitions
+// ============================================
+// ============================================
+// WORKFLOW NODE
+// ============================================
+export var NodeStatus;
+(function (NodeStatus) {
+    NodeStatus["Idle"] = "idle";
+    NodeStatus["Running"] = "running";
+    NodeStatus["Success"] = "success";
+    NodeStatus["Error"] = "error";
+    NodeStatus["Warning"] = "warning";
+    NodeStatus["Disabled"] = "disabled";
+})(NodeStatus || (NodeStatus = {}));
+// ============================================
+// WORKFLOW EDGE (CONNECTION)
+// ============================================
+export var EdgeType;
+(function (EdgeType) {
+    EdgeType["Default"] = "default";
+    EdgeType["Conditional"] = "conditional";
+    EdgeType["Loop"] = "loop";
+    EdgeType["Error"] = "error";
+})(EdgeType || (EdgeType = {}));

package/dist/ids.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ID Generator Utilities
+ *
+ * All randomness comes from the Web Crypto API (`crypto.getRandomValues`),
+ * which is available in every browser and as a Node global (≥18), so these
+ * helpers work both client- and server-side. Using crypto instead of
+ * `Math.random()` also clears the weak-PRNG security hotspot. These IDs are
+ * NOT secrets — crypto is used for collision resistance, not unpredictability.
+ */
+/**
+ * Cryptographically-strong short token: `length` base36 chars (0-9a-z).
+ * Drop-in replacement for the old `Math.random().toString(36).slice(2, 2+n)`
+ * pattern — same character set and length, collision-resistant source.
+ */
+export declare function randomSuffix(length?: number): string;
+/**
+ * Generate a UUID v4 string using the Web Crypto API.
+ */
+export declare function generateUUIDv4(): string;
+/**
+ * Generate a workflow ID using UUID v4
+ */
+export declare function generateWorkflowId(): string;
+/**
+ * Generate a step/node ID with prefix for clarity
+ */
+export declare function generateStepId(): string;
+/**
+ * Generate an edge/connection ID with prefix for clarity
+ */
+export declare function generateEdgeId(sourceId: string, targetId: string): string;

package/dist/ids.js

@@ -0,0 +1,53 @@
+/**
+ * ID Generator Utilities
+ *
+ * All randomness comes from the Web Crypto API (`crypto.getRandomValues`),
+ * which is available in every browser and as a Node global (≥18), so these
+ * helpers work both client- and server-side. Using crypto instead of
+ * `Math.random()` also clears the weak-PRNG security hotspot. These IDs are
+ * NOT secrets — crypto is used for collision resistance, not unpredictability.
+ */
+/**
+ * Cryptographically-strong short token: `length` base36 chars (0-9a-z).
+ * Drop-in replacement for the old `Math.random().toString(36).slice(2, 2+n)`
+ * pattern — same character set and length, collision-resistant source.
+ */
+export function randomSuffix(length = 7) {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    let out = '';
+    for (let i = 0; i < length; i++) {
+        out += (bytes[i] % 36).toString(36);
+    }
+    return out;
+}
+/**
+ * Generate a UUID v4 string using the Web Crypto API.
+ */
+export function generateUUIDv4() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = crypto.getRandomValues(new Uint8Array(1))[0] % 16;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Generate a workflow ID using UUID v4
+ */
+export function generateWorkflowId() {
+    return generateUUIDv4();
+}
+/**
+ * Generate a step/node ID with prefix for clarity
+ */
+export function generateStepId() {
+    return `node_${Date.now()}_${randomSuffix(7)}`;
+}
+/**
+ * Generate an edge/connection ID with prefix for clarity
+ */
+export function generateEdgeId(sourceId, targetId) {
+    // Random suffix (same pattern as generateStepId) guarantees uniqueness even for
+    // two calls in the same millisecond with identical source/target.
+    return `edge_${sourceId}_${targetId}_${Date.now()}_${randomSuffix(7)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @octaviaflow/flow-rules
+ *
+ * One definition of what a flow action accepts, and one definition of what
+ * makes a flow valid.
+ *
+ * Both lived in `octaviaflow-ui` and were therefore 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 input schema guesses at the config, and
+ * an agent that cannot run the rules cannot tell whether what it built works.
+ *
+ * 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.
+ *
+ * NO React, and no imports from either consumer. The config PANELS stay in
+ * octaviaflow-ui; this package is the data and the rules they are built on.
+ */
+export * from "./catalog/types";
+export { actionsRegistry, getAllActions, getActionById, getActionsByCategory, } from "./catalog/index";
+export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, type ValidationError, type ValidationResult, } from "./rules/workflowValidator";
+export { getNodeConfigStatus, type NodeConfigStatus, type NodeConfigStatusResult, } from "./rules/nodeConfigStatus";
+export { generateWorkflowId, generateStepId, generateEdgeId, generateUUIDv4, } from "./ids";

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * @octaviaflow/flow-rules
+ *
+ * One definition of what a flow action accepts, and one definition of what
+ * makes a flow valid.
+ *
+ * Both lived in `octaviaflow-ui` and were therefore 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 input schema guesses at the config, and
+ * an agent that cannot run the rules cannot tell whether what it built works.
+ *
+ * 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.
+ *
+ * NO React, and no imports from either consumer. The config PANELS stay in
+ * octaviaflow-ui; this package is the data and the rules they are built on.
+ */
+// ── The catalog: what an action is, and what it accepts ────────────────────
+export * from "./catalog/types";
+export { actionsRegistry, getAllActions, getActionById, getActionsByCategory, } from "./catalog/index";
+// ── The rules: what makes a flow valid (Flow Doctor's verdict) ─────────────
+export { validateNode, validateEdge, validateWorkflow, getNodeValidationStatus, getEdgeValidationStatus, } from "./rules/workflowValidator";
+export { getNodeConfigStatus, } from "./rules/nodeConfigStatus";
+// ── Ids, so a caller building a flow makes ones the editor recognises ──────
+export { generateWorkflowId, generateStepId, generateEdgeId, generateUUIDv4, } from "./ids";

package/dist/rules/nodeConfigStatus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Node Config Status Utility
+ *
+ * Determines the status indicator for a workflow node based on
+ * how completely its configuration has been filled out relative
+ * to the action definition's input schema.
+ *
+ * Handles:
+ * - Nested config keys (e.g., "visualConfig.tables" → config.visualConfig.tables)
+ * - Conditional required fields (only enforced when their condition is met)
+ * - Default values (count as filled if present)
+ */
+import type { WorkflowNode } from '../catalog/workflow';
+export type NodeConfigStatus = 'valid' | 'warning' | 'error' | 'unconfigured' | 'hidden';
+export interface NodeConfigStatusResult {
+    status: NodeConfigStatus;
+    requiredTotal: number;
+    requiredFilled: number;
+    optionalTotal: number;
+    optionalFilled: number;
+    missingRequired: string[];
+    filledOptional: string[];
+}
+/**
+ * Determine the config completeness status of a workflow node.
+ *
+ * Status logic:
+ * - "valid"        → All active required fields are filled (or no required fields exist)
+ * - "warning"      → Some active required fields are missing, but at least one field has data
+ * - "error"        → Has active required fields and none are filled, config is empty
+ * - "unconfigured" → Action definition not found (unknown action type)
+ */
+export declare function getNodeConfigStatus(node: WorkflowNode): NodeConfigStatusResult;