@lokascript/domain-flow 2.1.0

package/dist/index.d.cts

@@ -0,0 +1,643 @@
+import * as _lokascript_framework from '@lokascript/framework';
+import { PatternGenLanguageProfile, CodeGenerator, SemanticNode, MultilingualDSL, LanguageTokenizer } from '@lokascript/framework';
+
+/**
+ * HATEOAS Command Schemas
+ *
+ * Defines 4 HATEOAS-aware FlowScript commands: enter, follow, perform, capture.
+ * These compile to siren-grail workflow steps instead of vanilla JS.
+ */
+declare const enterSchema: _lokascript_framework.CommandSchema;
+declare const followSchema: _lokascript_framework.CommandSchema;
+declare const performSchema: _lokascript_framework.CommandSchema;
+declare const captureSchema: _lokascript_framework.CommandSchema;
+declare const hateoasSchemas: _lokascript_framework.CommandSchema[];
+
+/**
+ * FlowScript Command Schemas
+ *
+ * Defines the semantic structure of data flow commands using the framework's
+ * defineCommand/defineRole helpers. Each schema specifies roles (source, destination,
+ * style, duration, etc.) and per-language marker overrides for 8 languages.
+ */
+declare const fetchSchema: _lokascript_framework.CommandSchema;
+declare const pollSchema: _lokascript_framework.CommandSchema;
+declare const streamSchema: _lokascript_framework.CommandSchema;
+declare const submitSchema: _lokascript_framework.CommandSchema;
+declare const transformSchema: _lokascript_framework.CommandSchema;
+
+declare const allSchemas: _lokascript_framework.CommandSchema[];
+
+/**
+ * FlowScript Language Profiles
+ *
+ * Pattern generation profiles for 8 supported languages.
+ * Covers SVO (EN, ES, ZH, FR), SOV (JA, KO, TR), and VSO (AR) word orders.
+ *
+ * Role markers are specified via markerOverride on each schema role.
+ * Profile roleMarkers are used only when positional defaults need overriding.
+ */
+
+declare const englishProfile: PatternGenLanguageProfile;
+declare const spanishProfile: PatternGenLanguageProfile;
+declare const japaneseProfile: PatternGenLanguageProfile;
+declare const arabicProfile: PatternGenLanguageProfile;
+declare const koreanProfile: PatternGenLanguageProfile;
+declare const chineseProfile: PatternGenLanguageProfile;
+declare const turkishProfile: PatternGenLanguageProfile;
+declare const frenchProfile: PatternGenLanguageProfile;
+
+/**
+ * FlowScript Domain Types
+ *
+ * Output types for the FlowScript code generator. FlowSpec captures the
+ * semantic intent of a data flow command — URL, method, response format,
+ * target element, polling interval — ready for compilation to vanilla JS,
+ * HTMX attributes, or route descriptors.
+ */
+type FlowAction = 'fetch' | 'poll' | 'stream' | 'submit' | 'transform' | 'enter' | 'follow' | 'perform' | 'capture';
+/**
+ * Structured data flow specification.
+ *
+ * Output of domain-flow's code generator. Can be used to:
+ * - Generate vanilla JS (fetch, EventSource, setInterval)
+ * - Generate HTMX attributes (hx-get, hx-trigger, hx-target)
+ * - Extract route descriptors for server-bridge
+ */
+interface FlowSpec {
+    /** The command that produced this spec */
+    action: FlowAction;
+    /** URL for source commands (fetch, poll, stream, submit destination) */
+    url?: string;
+    /** HTTP method inferred from command type */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Response format */
+    responseFormat?: 'json' | 'html' | 'text' | 'sse';
+    /** Target CSS selector for DOM insertion */
+    target?: string;
+    /** Polling interval in milliseconds (poll command) */
+    intervalMs?: number;
+    /** Form selector (submit command) */
+    formSelector?: string;
+    /** Transform function or format string (transform command) */
+    transformFn?: string;
+    /** Link relation name (follow command) */
+    linkRel?: string;
+    /** Action name (perform command) */
+    actionName?: string;
+    /** Data source selector or inline data (perform command) */
+    dataSource?: string;
+    /** Variable name for captured data (capture command) */
+    captureAs?: string;
+    /** Property path to capture (capture command) */
+    capturePath?: string;
+    /** Metadata for debugging */
+    metadata: {
+        /** Language the command was written in */
+        sourceLanguage: string;
+        /** Raw role values extracted from the parsed command */
+        roles: Record<string, string | undefined>;
+    };
+}
+/** A single step in a HATEOAS workflow */
+type WorkflowStep = {
+    type: 'navigate';
+    rel: string;
+    capture?: Record<string, string>;
+} | {
+    type: 'action';
+    action: string;
+    data?: Record<string, unknown>;
+    dataSource?: string;
+    capture?: Record<string, string>;
+} | {
+    type: 'stop';
+    result?: string;
+    reason?: string;
+};
+/**
+ * A complete HATEOAS workflow specification.
+ *
+ * Compiles to siren-grail's compileWorkflow() step format.
+ * Can also drive an MCP server with dynamic tools.
+ */
+interface WorkflowSpec {
+    /** API entry point URL */
+    entryPoint: string;
+    /** Ordered workflow steps */
+    steps: WorkflowStep[];
+}
+
+/**
+ * FlowScript Code Generator
+ *
+ * Transforms semantic AST nodes into either:
+ * 1. Vanilla JavaScript strings (primary output via CodeGenerator interface)
+ * 2. Structured FlowSpec JSON (via toFlowSpec helper)
+ */
+
+/**
+ * Parse a duration string to milliseconds.
+ * Supports: 500ms, 5s, 1m, 1h, plain number (treated as ms)
+ */
+declare function parseDuration(duration: string): number;
+/**
+ * Extract a structured FlowSpec from a parsed SemanticNode.
+ */
+declare function toFlowSpec(node: SemanticNode, language: string): FlowSpec;
+/**
+ * FlowScript code generator implementation.
+ * Returns vanilla JavaScript — ready to execute in a browser.
+ */
+declare const flowCodeGenerator: CodeGenerator;
+
+/**
+ * FlowScript Natural Language Renderer
+ *
+ * Renders a SemanticNode back into natural-language FlowScript syntax
+ * for a target language. Inverse of the parser — used by translate().
+ */
+
+/**
+ * Render a FlowScript SemanticNode to natural-language text in the target language.
+ */
+declare function renderFlow(node: SemanticNode, language: string): string;
+
+/**
+ * HTMX Attribute Generator
+ *
+ * Transforms a FlowSpec into HTMX-compatible HTML attributes.
+ * Maps fetch → hx-get, poll → hx-get + hx-trigger, submit → hx-post.
+ * Stream (SSE) has no direct HTMX equivalent — returns null with a note.
+ */
+
+interface HTMXAttributes {
+    /** Generated HTMX attribute map */
+    attrs: Record<string, string>;
+    /** Notes about limitations or warnings */
+    notes: string[];
+}
+/**
+ * Generate HTMX attributes from a FlowSpec.
+ *
+ * @returns HTMXAttributes with attr map and notes, or null if the command
+ *          has no HTMX equivalent (e.g., transform)
+ */
+declare function generateHTMX(spec: FlowSpec): HTMXAttributes | null;
+
+/**
+ * Route Extractor
+ *
+ * Extracts server route descriptors from parsed FlowScript commands.
+ * Each fetch/poll/stream/submit URL becomes a RouteDescriptor that can
+ * be fed into server-bridge for server-side code generation.
+ */
+
+/**
+ * Lightweight route descriptor — compatible with server-bridge's RouteDescriptor
+ * but self-contained to avoid a hard dependency on the server-bridge package.
+ */
+interface FlowRouteDescriptor {
+    /** URL path (e.g., /api/users, /api/user/{id}) */
+    path: string;
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Expected response format */
+    responseFormat: 'json' | 'html' | 'text' | 'sse';
+    /** Path parameters extracted from URL (e.g., ['id'] from /api/user/{id}) */
+    pathParams: string[];
+    /** Suggested handler function name */
+    handlerName: string;
+    /** Source command that produced this route */
+    sourceCommand: string;
+}
+/**
+ * Extract route descriptors from a FlowSpec.
+ * Returns null for commands without URLs (e.g., transform).
+ */
+declare function extractRoute(spec: FlowSpec): FlowRouteDescriptor | null;
+/**
+ * Extract multiple route descriptors from an array of FlowSpecs.
+ * Filters out nulls (commands without URLs).
+ */
+declare function extractRoutes(specs: FlowSpec[]): FlowRouteDescriptor[];
+
+/**
+ * Pipeline Parser
+ *
+ * Wraps the framework's single-command DSL parser to handle multi-step
+ * data flow pipelines. Splits input on arrow delimiters (→ / ->), parses
+ * each step individually, and assembles a PipelineParseResult.
+ */
+
+interface PipelineStep {
+    /** The semantic node from parsing a single command */
+    node: SemanticNode;
+}
+interface PipelineParseResult {
+    /** Ordered pipeline steps */
+    steps: PipelineStep[];
+    /** Parse errors for any failed steps */
+    errors: string[];
+}
+/**
+ * Parse a multi-step FlowScript pipeline into ordered steps.
+ *
+ * Splits input on arrow delimiters (→ / ->), parses each segment
+ * via the DSL, and returns the steps in order.
+ *
+ * @example
+ * ```
+ * // Single-line arrow chain
+ * parseFlowPipeline(dsl, 'fetch /api/users as json → transform data with uppercase → into #list', 'en')
+ *
+ * // Multi-line (newline-separated, each line is a step)
+ * parseFlowPipeline(dsl, 'fetch /api/users as json\ntransform data with uppercase', 'en')
+ * ```
+ */
+declare function parseFlowPipeline(dsl: MultilingualDSL, input: string, language: string): PipelineParseResult;
+/**
+ * Compile a pipeline to a single JS code block.
+ *
+ * For linear pipelines (no branching), each step's output feeds into the next
+ * via Promise chaining. The first step must be a source (fetch/poll/stream),
+ * middle steps can be transforms, and the last step can include a destination.
+ */
+declare function compilePipeline(dsl: MultilingualDSL, input: string, language: string): {
+    ok: boolean;
+    code?: string;
+    errors: string[];
+};
+
+/**
+ * FlowScript Tokenizers
+ *
+ * Language-specific tokenizers for data flow commands (4 languages).
+ * Created via the framework's createSimpleTokenizer factory.
+ *
+ * Custom extractors handle:
+ * - CSS selectors (#id, .class)
+ * - URL paths (/api/users, /api/user/{id})
+ * - Duration literals (5s, 30s, 1m, 500ms)
+ * - Latin extended identifiers (diacritics in Spanish)
+ */
+
+declare const EnglishFlowTokenizer: LanguageTokenizer;
+declare const SpanishFlowTokenizer: LanguageTokenizer;
+declare const JapaneseFlowTokenizer: LanguageTokenizer;
+declare const ArabicFlowTokenizer: LanguageTokenizer;
+declare const KoreanFlowTokenizer: LanguageTokenizer;
+declare const ChineseFlowTokenizer: LanguageTokenizer;
+declare const TurkishFlowTokenizer: LanguageTokenizer;
+declare const FrenchFlowTokenizer: LanguageTokenizer;
+
+/**
+ * Workflow Generator — HATEOAS compilation target
+ *
+ * Converts a sequence of parsed FlowSpec objects into a WorkflowSpec
+ * compatible with siren-grail's compileWorkflow() step format.
+ *
+ * This is the bridge between FlowScript's natural-language parsing
+ * and siren-grail's workflow execution engine.
+ */
+
+/**
+ * Convert an ordered array of FlowSpecs (from parsed HATEOAS commands)
+ * into a WorkflowSpec ready for siren-grail execution.
+ *
+ * The first 'enter' command provides the entry point URL.
+ * Subsequent follow/perform/capture commands become workflow steps.
+ *
+ * @throws Error if no 'enter' command is found in the specs
+ */
+declare function toWorkflowSpec(specs: FlowSpec[]): WorkflowSpec;
+/**
+ * Convert a WorkflowSpec to siren-grail's compileWorkflow() step format.
+ *
+ * This produces a plain JSON array compatible with:
+ *   import { compileWorkflow } from 'siren-agent/workflow';
+ *   const decide = compileWorkflow(steps);
+ */
+declare function toSirenGrailSteps(spec: WorkflowSpec): Array<Record<string, unknown>>;
+
+/**
+ * Workflow Executor — siren-grail adapter
+ *
+ * Thin adapter that takes a WorkflowSpec (from FlowScript parsing)
+ * and executes it against a Siren API using siren-grail's OODAAgent
+ * and compileWorkflow().
+ *
+ * This bridges FlowScript's natural-language parsing to siren-grail's
+ * HATEOAS agent runtime.
+ *
+ * @example
+ * ```typescript
+ * import { executeWorkflow } from '@lokascript/domain-flow/runtime';
+ * import { createFlowDSL, toFlowSpec } from '@lokascript/domain-flow';
+ * import { toWorkflowSpec } from '@lokascript/domain-flow/generators/workflow-generator';
+ *
+ * const flow = createFlowDSL();
+ * const specs = [
+ *   toFlowSpec(flow.parse('enter /api', 'en'), 'en'),
+ *   toFlowSpec(flow.parse('follow orders', 'en'), 'en'),
+ *   toFlowSpec(flow.parse('perform createOrder with #checkout', 'en'), 'en'),
+ *   toFlowSpec(flow.parse('capture as orderId', 'en'), 'en'),
+ * ];
+ *
+ * const workflow = toWorkflowSpec(specs);
+ * const result = await executeWorkflow(workflow, { verbose: true });
+ * ```
+ */
+
+/**
+ * Result from a workflow execution.
+ * Maps to siren-grail's OODAResult.
+ */
+interface WorkflowResult {
+    status: 'stopped' | 'error' | 'maxSteps';
+    reason: string;
+    result?: unknown;
+    steps: number;
+    history: Array<Record<string, unknown>>;
+}
+/**
+ * Options for workflow execution.
+ */
+interface ExecuteWorkflowOptions {
+    /** Maximum OODA steps before stopping (default: 50) */
+    maxSteps?: number;
+    /** HTTP headers to send with all requests */
+    headers?: Record<string, string>;
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+    /** Timeout per request in ms (default: 30000) */
+    timeout?: number;
+    /** Enable auto-pursuit on 409 Conflict responses */
+    autoPursue?: boolean;
+    /** Callback on each entity navigation */
+    onEntity?: (entity: unknown, url: string) => void;
+    /** Callback on each decision */
+    onDecision?: (decision: unknown) => void;
+}
+/**
+ * Convert a WorkflowSpec to siren-grail's step format.
+ *
+ * This is a pure-data transformation — no siren-grail dependency required.
+ * The step types map 1:1:
+ *   WorkflowStep.navigate → { type: 'navigate', rel }
+ *   WorkflowStep.action   → { type: 'action', action, data?, dataSource? }
+ *   WorkflowStep.stop     → { type: 'stop', result?, reason? }
+ */
+declare function toSirenSteps(steps: WorkflowStep[]): Array<Record<string, unknown>>;
+/**
+ * Execute a WorkflowSpec against a Siren API using siren-grail.
+ *
+ * Requires `siren-agent` to be installed as a peer dependency.
+ * Dynamically imports it to avoid hard dependency.
+ *
+ * @param spec - The compiled WorkflowSpec from toWorkflowSpec()
+ * @param options - Execution options (headers, timeout, etc.)
+ * @returns The execution result with status, history, and captured values
+ *
+ * @throws Error if siren-agent is not installed
+ */
+declare function executeWorkflow(spec: WorkflowSpec, options?: ExecuteWorkflowOptions): Promise<WorkflowResult>;
+/**
+ * Create a reusable workflow executor bound to specific options.
+ *
+ * Useful when executing multiple workflows against the same API
+ * with shared headers/auth.
+ */
+declare function createWorkflowExecutor(defaultOptions?: ExecuteWorkflowOptions): {
+    execute(spec: WorkflowSpec, overrides?: ExecuteWorkflowOptions): Promise<WorkflowResult>;
+};
+
+/**
+ * MCP Workflow Server — HATEOAS → MCP tool bridge
+ *
+ * An MCP server that wraps a Siren API, exposing current entity affordances
+ * (actions and links) as dynamic MCP tools. As the agent navigates through
+ * hypermedia states, tools appear and disappear — `tools/list_changed` fires
+ * on every state transition.
+ *
+ * This is the novel contribution: MCP's tool protocol becomes a first-class
+ * HATEOAS mechanism. External LLM clients (Claude Code, Cursor, etc.) see
+ * affordance-driven tool sets without needing to understand Siren.
+ *
+ * Tool naming convention:
+ *   action__{name}    — Execute a Siren action
+ *   navigate__{rel}   — Follow a Siren link
+ *   resolve__{name}   — Resolve a 409 prerequisite action
+ *
+ * @example
+ * ```typescript
+ * import { createMcpWorkflowServer } from '@lokascript/domain-flow/runtime';
+ *
+ * const server = createMcpWorkflowServer({
+ *   entryPoint: 'http://api.example.com/',
+ *   name: 'order-api',
+ *   version: '1.0.0',
+ * });
+ *
+ * await server.start(); // Connects to API, builds initial tools, listens on stdio
+ * ```
+ */
+
+/** Siren entity structure (subset for our needs) */
+interface SirenEntity {
+    class?: string[];
+    properties?: Record<string, unknown>;
+    entities?: Array<Record<string, unknown>>;
+    actions?: SirenAction[];
+    links?: SirenLink[];
+}
+interface SirenAction {
+    name: string;
+    title?: string;
+    href: string;
+    method?: string;
+    type?: string;
+    fields?: SirenField[];
+}
+interface SirenField {
+    name: string;
+    type?: string;
+    value?: unknown;
+    title?: string;
+}
+interface SirenLink {
+    rel: string[];
+    href: string;
+    title?: string;
+    type?: string;
+}
+/** MCP tool definition */
+interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/** Configuration for the MCP workflow server */
+interface McpWorkflowServerConfig {
+    /** API entry point URL */
+    entryPoint: string;
+    /** Server name for MCP identification */
+    name?: string;
+    /** Server version */
+    version?: string;
+    /** HTTP headers (e.g., auth) for all API requests */
+    headers?: Record<string, string>;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Optional pre-compiled WorkflowSpec to auto-execute */
+    workflow?: WorkflowSpec;
+}
+/**
+ * Convert Siren actions to MCP tool definitions.
+ *
+ * Each action becomes an `action__{name}` tool with input schema
+ * generated from the action's fields.
+ */
+declare function actionsToTools(actions: SirenAction[]): McpTool[];
+/**
+ * Convert Siren links to MCP tool definitions.
+ *
+ * Each link becomes a `navigate__{rel}` tool with no required inputs.
+ */
+declare function linksToTools(links: SirenLink[]): McpTool[];
+/**
+ * Build the complete tool set from a Siren entity.
+ */
+declare function entityToTools(entity: SirenEntity): McpTool[];
+/**
+ * MCP Workflow Server state machine.
+ *
+ * Manages the Siren agent state and translates between MCP tool
+ * calls and Siren API interactions. Transport (stdio, SSE, etc.)
+ * is handled externally.
+ *
+ * The server lifecycle:
+ * 1. initialize() — fetch entry point, build initial tool set
+ * 2. listTools() — return current affordance-derived tools
+ * 3. callTool(name, args) — execute action or navigate, rebuild tools
+ * 4. On each state change, emit tools/list_changed notification
+ */
+declare class McpWorkflowServer {
+    private config;
+    private currentEntity;
+    private currentUrl;
+    private currentTools;
+    private toolChangeListeners;
+    constructor(config: McpWorkflowServerConfig);
+    /**
+     * Register a listener for tool list changes (maps to tools/list_changed).
+     */
+    onToolsChanged(listener: () => void): void;
+    /**
+     * Initialize the server by fetching the entry point entity.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the current list of available MCP tools.
+     */
+    listTools(): McpTool[];
+    /**
+     * Get the current entity as an MCP resource.
+     */
+    getCurrentEntity(): SirenEntity | null;
+    /**
+     * Get the current URL.
+     */
+    getCurrentUrl(): string;
+    /**
+     * Call a tool (action or navigation).
+     *
+     * Returns the result text and triggers tools/list_changed if the
+     * entity state changed.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content: string;
+        isError?: boolean;
+    }>;
+    /**
+     * Get MCP server capabilities for the initialize response.
+     */
+    getCapabilities(): {
+        tools: {
+            listChanged: boolean;
+        };
+        resources: {};
+    };
+    /**
+     * Get MCP server info for the initialize response.
+     */
+    getServerInfo(): {
+        name: string;
+        version: string;
+    };
+    private fetchEntity;
+    private executeAction;
+    private updateState;
+}
+/**
+ * Create a new MCP workflow server instance.
+ */
+declare function createMcpWorkflowServer(config: McpWorkflowServerConfig): McpWorkflowServer;
+
+/**
+ * @lokascript/domain-flow — Declarative Reactive Data Flow DSL
+ *
+ * A multilingual data flow domain built on @lokascript/framework.
+ * Parses data flow commands written in 8 languages, compiling to
+ * vanilla JS (fetch, EventSource, setInterval) or HTMX attributes.
+ *
+ * @example
+ * ```typescript
+ * import { createFlowDSL } from '@lokascript/domain-flow';
+ *
+ * const flow = createFlowDSL();
+ *
+ * // English (SVO)
+ * flow.compile('fetch /api/users as json into #user-list', 'en');
+ * // → { ok: true, code: "fetch('/api/users').then(r => r.json())..." }
+ *
+ * // Spanish (SVO)
+ * flow.compile('obtener /api/users como json en #user-list', 'es');
+ *
+ * // Japanese (SOV)
+ * flow.compile('/api/users json で 取得', 'ja');
+ *
+ * // Arabic (VSO)
+ * flow.compile('جلب /api/users ك json في #user-list', 'ar');
+ *
+ * // Korean (SOV)
+ * flow.compile('/api/users json 로 가져오기', 'ko');
+ *
+ * // Chinese (SVO)
+ * flow.compile('获取 /api/users 以 json 到 #user-list', 'zh');
+ *
+ * // Turkish (SOV)
+ * flow.compile('/api/users json olarak getir', 'tr');
+ *
+ * // French (SVO)
+ * flow.compile('récupérer /api/users comme json dans #user-list', 'fr');
+ * ```
+ */
+
+/**
+ * Create a multilingual FlowScript DSL instance with all 8 supported languages.
+ */
+declare function createFlowDSL(): MultilingualDSL;
+
+/** HTML attribute and script-type patterns for AOT scanning */
+declare const flowScanConfig: {
+    attributes: readonly ["data-flow", "_flow"];
+    scriptTypes: readonly ["text/flowscript"];
+    defaultLanguage: string;
+};
+
+export { ArabicFlowTokenizer, ChineseFlowTokenizer, EnglishFlowTokenizer, type ExecuteWorkflowOptions, type FlowAction, type FlowRouteDescriptor, type FlowSpec, FrenchFlowTokenizer, type HTMXAttributes, JapaneseFlowTokenizer, KoreanFlowTokenizer, McpWorkflowServer, type McpWorkflowServerConfig, type PipelineParseResult, type PipelineStep, SpanishFlowTokenizer, TurkishFlowTokenizer, type WorkflowResult, type WorkflowSpec, type WorkflowStep, actionsToTools, allSchemas, arabicProfile, captureSchema, chineseProfile, compilePipeline, createFlowDSL, createMcpWorkflowServer, createWorkflowExecutor, englishProfile, enterSchema, entityToTools, executeWorkflow, extractRoute, extractRoutes, fetchSchema, flowCodeGenerator, flowScanConfig, followSchema, frenchProfile, generateHTMX, hateoasSchemas, japaneseProfile, koreanProfile, linksToTools, parseDuration, parseFlowPipeline, performSchema, pollSchema, renderFlow, spanishProfile, streamSchema, submitSchema, toFlowSpec, toSirenGrailSteps, toSirenSteps, toWorkflowSpec, transformSchema, turkishProfile };