@lokascript/domain-flow 2.1.0

package/src/generators/htmx-generator.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ */
+
+import type { FlowSpec } from '../types.js';
+
+export 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)
+ */
+export function generateHTMX(spec: FlowSpec): HTMXAttributes | null {
+  switch (spec.action) {
+    case 'fetch':
+      return generateFetchHTMX(spec);
+    case 'poll':
+      return generatePollHTMX(spec);
+    case 'stream':
+      return generateStreamHTMX(spec);
+    case 'submit':
+      return generateSubmitHTMX(spec);
+    case 'transform':
+      return null; // No HTMX equivalent for data transforms
+    default:
+      return null;
+  }
+}
+
+function generateFetchHTMX(spec: FlowSpec): HTMXAttributes {
+  const attrs: Record<string, string> = {};
+  const notes: string[] = [];
+
+  if (spec.url) {
+    attrs['hx-get'] = spec.url;
+  }
+
+  if (spec.target) {
+    attrs['hx-target'] = spec.target;
+  }
+
+  attrs['hx-swap'] = 'innerHTML';
+
+  if (spec.responseFormat === 'json') {
+    notes.push(
+      'HTMX expects HTML responses by default. For JSON, use hx-ext="json-enc" or handle in a hyperscript handler.'
+    );
+  }
+
+  return { attrs, notes };
+}
+
+function generatePollHTMX(spec: FlowSpec): HTMXAttributes {
+  const attrs: Record<string, string> = {};
+  const notes: string[] = [];
+
+  if (spec.url) {
+    attrs['hx-get'] = spec.url;
+  }
+
+  if (spec.intervalMs) {
+    const seconds = spec.intervalMs / 1000;
+    attrs['hx-trigger'] = `every ${seconds}s`;
+  }
+
+  if (spec.target) {
+    attrs['hx-target'] = spec.target;
+  }
+
+  attrs['hx-swap'] = 'innerHTML';
+
+  if (spec.responseFormat === 'json') {
+    notes.push(
+      'HTMX expects HTML responses by default. For JSON, use hx-ext="json-enc" or handle in a hyperscript handler.'
+    );
+  }
+
+  return { attrs, notes };
+}
+
+function generateStreamHTMX(spec: FlowSpec): HTMXAttributes {
+  const attrs: Record<string, string> = {};
+  const notes: string[] = [];
+
+  if (spec.url) {
+    attrs['hx-ext'] = 'sse';
+    attrs['sse-connect'] = spec.url;
+    attrs['sse-swap'] = 'message';
+  }
+
+  if (spec.target) {
+    attrs['hx-target'] = spec.target;
+  }
+
+  notes.push('SSE support requires the htmx sse extension (hx-ext="sse").');
+
+  return { attrs, notes };
+}
+
+function generateSubmitHTMX(spec: FlowSpec): HTMXAttributes {
+  const attrs: Record<string, string> = {};
+  const notes: string[] = [];
+
+  if (spec.url) {
+    attrs['hx-post'] = spec.url;
+  }
+
+  if (spec.responseFormat === 'json') {
+    attrs['hx-ext'] = 'json-enc';
+    attrs['hx-encoding'] = 'application/json';
+  }
+
+  if (spec.target) {
+    attrs['hx-target'] = spec.target;
+  }
+
+  return { attrs, notes };
+}

package/src/generators/route-extractor.ts

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+import type { FlowSpec } from '../types.js';
+
+/**
+ * Lightweight route descriptor — compatible with server-bridge's RouteDescriptor
+ * but self-contained to avoid a hard dependency on the server-bridge package.
+ */
+export 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).
+ */
+export function extractRoute(spec: FlowSpec): FlowRouteDescriptor | null {
+  if (!spec.url) return null;
+
+  const path = spec.url;
+  const pathParams = extractPathParams(path);
+  const handlerName = generateHandlerName(spec);
+
+  return {
+    path,
+    method: spec.method || 'GET',
+    responseFormat: spec.responseFormat || 'text',
+    pathParams,
+    handlerName,
+    sourceCommand: spec.action,
+  };
+}
+
+/**
+ * Extract multiple route descriptors from an array of FlowSpecs.
+ * Filters out nulls (commands without URLs).
+ */
+export function extractRoutes(specs: FlowSpec[]): FlowRouteDescriptor[] {
+  return specs.map(extractRoute).filter((r): r is FlowRouteDescriptor => r !== null);
+}
+
+/**
+ * Extract path parameters from a URL.
+ * Supports both {param} and :param syntax.
+ */
+function extractPathParams(url: string): string[] {
+  const params: string[] = [];
+
+  // {param} syntax
+  const braceMatches = url.matchAll(/\{(\w+)\}/g);
+  for (const match of braceMatches) {
+    params.push(match[1]);
+  }
+
+  // :param syntax
+  const colonMatches = url.matchAll(/:(\w+)/g);
+  for (const match of colonMatches) {
+    params.push(match[1]);
+  }
+
+  return params;
+}
+
+/**
+ * Generate a suggested handler function name from a FlowSpec.
+ */
+function generateHandlerName(spec: FlowSpec): string {
+  if (!spec.url) return 'handler';
+
+  // Extract the last meaningful path segment
+  const segments = spec.url
+    .split('/')
+    .filter(s => s && !s.startsWith('{') && !s.startsWith(':') && !s.includes('?'));
+  const lastSegment = segments[segments.length - 1] || 'data';
+
+  const prefix =
+    spec.method === 'POST'
+      ? 'create'
+      : spec.method === 'PUT'
+        ? 'update'
+        : spec.method === 'DELETE'
+          ? 'delete'
+          : 'get';
+
+  // Capitalize first letter
+  const name = lastSegment.charAt(0).toUpperCase() + lastSegment.slice(1);
+  return `${prefix}${name}`;
+}

package/src/generators/workflow-generator.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ */
+
+import type { FlowSpec, WorkflowSpec, WorkflowStep } from '../types.js';
+
+/**
+ * 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
+ */
+export function toWorkflowSpec(specs: FlowSpec[]): WorkflowSpec {
+  let entryPoint: string | undefined;
+  const steps: WorkflowStep[] = [];
+
+  // Track the last step so capture can attach to it
+  let lastStep: WorkflowStep | undefined;
+
+  for (const spec of specs) {
+    switch (spec.action) {
+      case 'enter': {
+        if (!spec.url) throw new Error('enter command requires a URL');
+        entryPoint = spec.url;
+        break;
+      }
+
+      case 'follow': {
+        if (!spec.linkRel) throw new Error('follow command requires a link relation');
+        const step: WorkflowStep = { type: 'navigate', rel: spec.linkRel };
+        steps.push(step);
+        lastStep = step;
+        break;
+      }
+
+      case 'perform': {
+        if (!spec.actionName) throw new Error('perform command requires an action name');
+        const step: WorkflowStep = {
+          type: 'action',
+          action: spec.actionName,
+        };
+        if (spec.dataSource) {
+          step.dataSource = spec.dataSource;
+        }
+        steps.push(step);
+        lastStep = step;
+        break;
+      }
+
+      case 'capture': {
+        if (!spec.captureAs) throw new Error('capture command requires a variable name');
+
+        // Capture attaches to the previous step as a capture modifier
+        if (lastStep && (lastStep.type === 'navigate' || lastStep.type === 'action')) {
+          if (!lastStep.capture) lastStep.capture = {};
+          lastStep.capture[spec.captureAs] = spec.capturePath || 'properties';
+        } else {
+          // Standalone capture — attach to an implicit navigate to 'self'
+          const step: WorkflowStep = {
+            type: 'navigate',
+            rel: 'self',
+            capture: { [spec.captureAs]: spec.capturePath || 'properties' },
+          };
+          steps.push(step);
+          lastStep = step;
+        }
+        break;
+      }
+
+      default:
+        // Non-HATEOAS commands (fetch, poll, etc.) are not part of workflows
+        break;
+    }
+  }
+
+  if (!entryPoint) {
+    throw new Error('Workflow requires an "enter" command to specify the API entry point');
+  }
+
+  return { entryPoint, steps };
+}
+
+/**
+ * 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);
+ */
+export function toSirenGrailSteps(spec: WorkflowSpec): Array<Record<string, unknown>> {
+  return spec.steps.map(step => {
+    switch (step.type) {
+      case 'navigate':
+        return {
+          type: 'navigate',
+          rel: step.rel,
+          ...(step.capture ? { capture: step.capture } : {}),
+        };
+
+      case 'action':
+        return {
+          type: 'action',
+          action: step.action,
+          ...(step.data ? { data: step.data } : {}),
+          ...(step.dataSource ? { dataSource: step.dataSource } : {}),
+          ...(step.capture ? { capture: step.capture } : {}),
+        };
+
+      case 'stop':
+        return {
+          type: 'stop',
+          ...(step.result ? { result: step.result } : {}),
+          ...(step.reason ? { reason: step.reason } : {}),
+        };
+
+      default:
+        return step as Record<string, unknown>;
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,210 @@
+/**
+ * @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');
+ * ```
+ */
+
+import { createMultilingualDSL, type MultilingualDSL } from '@lokascript/framework';
+import {
+  allSchemas,
+  fetchSchema,
+  pollSchema,
+  streamSchema,
+  submitSchema,
+  transformSchema,
+} from './schemas/index.js';
+import {
+  englishProfile,
+  spanishProfile,
+  japaneseProfile,
+  arabicProfile,
+  koreanProfile,
+  chineseProfile,
+  turkishProfile,
+  frenchProfile,
+} from './profiles/index.js';
+import {
+  EnglishFlowTokenizer,
+  SpanishFlowTokenizer,
+  JapaneseFlowTokenizer,
+  ArabicFlowTokenizer,
+  KoreanFlowTokenizer,
+  ChineseFlowTokenizer,
+  TurkishFlowTokenizer,
+  FrenchFlowTokenizer,
+} from './tokenizers/index.js';
+import { flowCodeGenerator } from './generators/flow-generator.js';
+
+/**
+ * Create a multilingual FlowScript DSL instance with all 8 supported languages.
+ */
+export function createFlowDSL(): MultilingualDSL {
+  return /*#__PURE__*/ createMultilingualDSL({
+    name: 'FlowScript',
+    schemas: allSchemas,
+    languages: [
+      {
+        code: 'en',
+        name: 'English',
+        nativeName: 'English',
+        tokenizer: EnglishFlowTokenizer,
+        patternProfile: englishProfile,
+      },
+      {
+        code: 'es',
+        name: 'Spanish',
+        nativeName: 'Español',
+        tokenizer: SpanishFlowTokenizer,
+        patternProfile: spanishProfile,
+      },
+      {
+        code: 'ja',
+        name: 'Japanese',
+        nativeName: '日本語',
+        tokenizer: JapaneseFlowTokenizer,
+        patternProfile: japaneseProfile,
+      },
+      {
+        code: 'ar',
+        name: 'Arabic',
+        nativeName: 'العربية',
+        tokenizer: ArabicFlowTokenizer,
+        patternProfile: arabicProfile,
+      },
+      {
+        code: 'ko',
+        name: 'Korean',
+        nativeName: '한국어',
+        tokenizer: KoreanFlowTokenizer,
+        patternProfile: koreanProfile,
+      },
+      {
+        code: 'zh',
+        name: 'Chinese',
+        nativeName: '中文',
+        tokenizer: ChineseFlowTokenizer,
+        patternProfile: chineseProfile,
+      },
+      {
+        code: 'tr',
+        name: 'Turkish',
+        nativeName: 'Türkçe',
+        tokenizer: TurkishFlowTokenizer,
+        patternProfile: turkishProfile,
+      },
+      {
+        code: 'fr',
+        name: 'French',
+        nativeName: 'Français',
+        tokenizer: FrenchFlowTokenizer,
+        patternProfile: frenchProfile,
+      },
+    ],
+    codeGenerator: flowCodeGenerator,
+  });
+}
+
+// Re-export schemas for consumers who want to extend
+export { allSchemas, fetchSchema, pollSchema, streamSchema, submitSchema, transformSchema };
+export {
+  enterSchema,
+  followSchema,
+  performSchema,
+  captureSchema,
+  hateoasSchemas,
+} from './schemas/hateoas-schemas.js';
+export {
+  englishProfile,
+  spanishProfile,
+  japaneseProfile,
+  arabicProfile,
+  koreanProfile,
+  chineseProfile,
+  turkishProfile,
+  frenchProfile,
+} from './profiles/index.js';
+export { flowCodeGenerator, toFlowSpec, parseDuration } from './generators/flow-generator.js';
+export { renderFlow } from './generators/flow-renderer.js';
+export { generateHTMX } from './generators/htmx-generator.js';
+export { extractRoute, extractRoutes } from './generators/route-extractor.js';
+export { parseFlowPipeline, compilePipeline } from './parser/pipeline-parser.js';
+export type { HTMXAttributes } from './generators/htmx-generator.js';
+export type { FlowRouteDescriptor } from './generators/route-extractor.js';
+export type { PipelineStep, PipelineParseResult } from './parser/pipeline-parser.js';
+export {
+  EnglishFlowTokenizer,
+  SpanishFlowTokenizer,
+  JapaneseFlowTokenizer,
+  ArabicFlowTokenizer,
+  KoreanFlowTokenizer,
+  ChineseFlowTokenizer,
+  TurkishFlowTokenizer,
+  FrenchFlowTokenizer,
+} from './tokenizers/index.js';
+export type { FlowSpec, FlowAction, WorkflowSpec, WorkflowStep } from './types.js';
+export { toWorkflowSpec, toSirenGrailSteps } from './generators/workflow-generator.js';
+
+// =============================================================================
+// Runtime: HATEOAS Workflow Execution + MCP Server
+// =============================================================================
+
+export {
+  executeWorkflow,
+  createWorkflowExecutor,
+  toSirenSteps,
+} from './runtime/workflow-executor.js';
+export type { WorkflowResult, ExecuteWorkflowOptions } from './runtime/workflow-executor.js';
+
+export {
+  McpWorkflowServer,
+  createMcpWorkflowServer,
+  actionsToTools,
+  linksToTools,
+  entityToTools,
+} from './runtime/mcp-workflow-server.js';
+export type { McpWorkflowServerConfig } from './runtime/mcp-workflow-server.js';
+
+// =============================================================================
+// Domain Scan Config (for AOT / Vite plugin integration)
+// =============================================================================
+
+/** HTML attribute and script-type patterns for AOT scanning */
+export const flowScanConfig = {
+  attributes: ['data-flow', '_flow'] as const,
+  scriptTypes: ['text/flowscript'] as const,
+  defaultLanguage: 'en',
+};