@lokascript/domain-flow 2.1.0

package/src/__test__/mcp-workflow-server.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Tests for MCP Workflow Server — Siren → MCP tool generation
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  actionsToTools,
+  linksToTools,
+  entityToTools,
+  McpWorkflowServer,
+} from '../runtime/mcp-workflow-server.js';
+
+// =============================================================================
+// actionsToTools
+// =============================================================================
+
+describe('actionsToTools', () => {
+  it('converts a Siren action to an action__ tool', () => {
+    const tools = actionsToTools([
+      {
+        name: 'create-order',
+        title: 'Create a new order',
+        href: '/api/orders',
+        method: 'POST',
+        fields: [
+          { name: 'product', type: 'text', title: 'Product name' },
+          { name: 'quantity', type: 'number', title: 'Quantity' },
+        ],
+      },
+    ]);
+
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe('action__create-order');
+    expect(tools[0].description).toBe('Create a new order');
+    expect(tools[0].inputSchema.type).toBe('object');
+    expect(tools[0].inputSchema.properties).toEqual({
+      product: { type: 'string', description: 'Product name' },
+      quantity: { type: 'number', description: 'Quantity' },
+    });
+    expect(tools[0].inputSchema.required).toEqual(['product', 'quantity']);
+  });
+
+  it('uses default description when title is absent', () => {
+    const tools = actionsToTools([{ name: 'search', href: '/search', method: 'GET' }]);
+
+    expect(tools[0].description).toBe('Execute the "search" action (GET /search)');
+  });
+
+  it('defaults method to POST in description', () => {
+    const tools = actionsToTools([{ name: 'submit', href: '/submit' }]);
+    expect(tools[0].description).toContain('POST');
+  });
+
+  it('marks fields with default values as optional', () => {
+    const tools = actionsToTools([
+      {
+        name: 'create',
+        href: '/api',
+        fields: [
+          { name: 'required_field', type: 'text' },
+          { name: 'optional_field', type: 'text', value: 'default' },
+        ],
+      },
+    ]);
+
+    expect(tools[0].inputSchema.required).toEqual(['required_field']);
+    expect(tools[0].inputSchema.properties['optional_field']).toEqual({
+      type: 'string',
+      default: 'default',
+    });
+  });
+
+  it('handles actions with no fields', () => {
+    const tools = actionsToTools([{ name: 'delete', href: '/api/1', method: 'DELETE' }]);
+    expect(tools[0].inputSchema.properties).toEqual({});
+    expect(tools[0].inputSchema.required).toBeUndefined();
+  });
+
+  it('maps field types to JSON Schema types', () => {
+    const tools = actionsToTools([
+      {
+        name: 'test',
+        href: '/test',
+        fields: [
+          { name: 'num', type: 'number' },
+          { name: 'rng', type: 'range' },
+          { name: 'chk', type: 'checkbox' },
+          { name: 'txt', type: 'text' },
+          { name: 'em', type: 'email' },
+          { name: 'dt', type: 'date' },
+          { name: 'hid', type: 'hidden' },
+        ],
+      },
+    ]);
+
+    const props = tools[0].inputSchema.properties;
+    expect((props['num'] as Record<string, unknown>).type).toBe('number');
+    expect((props['rng'] as Record<string, unknown>).type).toBe('number');
+    expect((props['chk'] as Record<string, unknown>).type).toBe('boolean');
+    expect((props['txt'] as Record<string, unknown>).type).toBe('string');
+    expect((props['em'] as Record<string, unknown>).type).toBe('string');
+    expect((props['dt'] as Record<string, unknown>).type).toBe('string');
+    expect((props['hid'] as Record<string, unknown>).type).toBe('string');
+  });
+});
+
+// =============================================================================
+// linksToTools
+// =============================================================================
+
+describe('linksToTools', () => {
+  it('converts Siren links to navigate__ tools', () => {
+    const tools = linksToTools([
+      { rel: ['orders'], href: '/api/orders', title: 'View all orders' },
+      { rel: ['next'], href: '/api/orders?page=2' },
+    ]);
+
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe('navigate__orders');
+    expect(tools[0].description).toBe('View all orders');
+    expect(tools[1].name).toBe('navigate__next');
+    expect(tools[1].description).toBe('Navigate to "next" (/api/orders?page=2)');
+  });
+
+  it('skips self links', () => {
+    const tools = linksToTools([
+      { rel: ['self'], href: '/api/orders' },
+      { rel: ['next'], href: '/api/orders?page=2' },
+    ]);
+
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe('navigate__next');
+  });
+
+  it('deduplicates by first rel', () => {
+    const tools = linksToTools([
+      { rel: ['item'], href: '/api/orders/1' },
+      { rel: ['item'], href: '/api/orders/2' },
+    ]);
+
+    expect(tools).toHaveLength(1);
+  });
+
+  it('navigate tools have empty input schema', () => {
+    const tools = linksToTools([{ rel: ['up'], href: '/api' }]);
+    expect(tools[0].inputSchema).toEqual({ type: 'object', properties: {} });
+  });
+});
+
+// =============================================================================
+// entityToTools
+// =============================================================================
+
+describe('entityToTools', () => {
+  it('combines actions and links into a single tool set', () => {
+    const tools = entityToTools({
+      actions: [{ name: 'create', href: '/api', method: 'POST' }],
+      links: [
+        { rel: ['self'], href: '/api' },
+        { rel: ['next'], href: '/api?page=2' },
+      ],
+    });
+
+    expect(tools).toHaveLength(2); // 1 action + 1 link (self skipped)
+    expect(tools[0].name).toBe('action__create');
+    expect(tools[1].name).toBe('navigate__next');
+  });
+
+  it('handles entity with no actions or links', () => {
+    const tools = entityToTools({ properties: { foo: 'bar' } });
+    expect(tools).toHaveLength(0);
+  });
+});
+
+// =============================================================================
+// McpWorkflowServer
+// =============================================================================
+
+describe('McpWorkflowServer', () => {
+  it('returns server info', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+      name: 'test-server',
+      version: '2.0.0',
+    });
+
+    expect(server.getServerInfo()).toEqual({
+      name: 'test-server',
+      version: '2.0.0',
+    });
+  });
+
+  it('uses default name and version', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    expect(server.getServerInfo()).toEqual({
+      name: 'hateoas-mcp-server',
+      version: '1.0.0',
+    });
+  });
+
+  it('returns capabilities with tools.listChanged', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    expect(server.getCapabilities()).toEqual({
+      tools: { listChanged: true },
+      resources: {},
+    });
+  });
+
+  it('returns empty tool list before initialization', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    expect(server.listTools()).toEqual([]);
+  });
+
+  it('returns null entity before initialization', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    expect(server.getCurrentEntity()).toBeNull();
+  });
+
+  it('tracks current URL', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    expect(server.getCurrentUrl()).toBe('http://example.com/api');
+  });
+
+  it('returns error when calling tool before initialization', async () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    const result = await server.callTool('action__test', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('not initialized');
+  });
+
+  it('returns error for unknown tool prefix', async () => {
+    // We need to get past the initialization check by setting internal state
+    // Use a real server with a mock entity approach
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    // Access internal state to bypass initialization check
+    (server as unknown as { currentEntity: unknown }).currentEntity = {
+      actions: [],
+      links: [],
+    };
+
+    const result = await server.callTool('unknown__test', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Unknown tool prefix');
+  });
+
+  it('returns error when action not found', async () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    (server as unknown as { currentEntity: unknown }).currentEntity = {
+      actions: [{ name: 'existing', href: '/api' }],
+      links: [],
+    };
+
+    const result = await server.callTool('action__nonexistent', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('not available');
+    expect(result.content).toContain('existing');
+  });
+
+  it('returns error when link not found', async () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    (server as unknown as { currentEntity: unknown }).currentEntity = {
+      actions: [],
+      links: [{ rel: ['orders'], href: '/api/orders' }],
+    };
+
+    const result = await server.callTool('navigate__nonexistent', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('not available');
+    expect(result.content).toContain('orders');
+  });
+
+  it('fires toolChangeListeners on registration', () => {
+    const server = new McpWorkflowServer({
+      entryPoint: 'http://example.com/api',
+    });
+
+    let called = false;
+    server.onToolsChanged(() => {
+      called = true;
+    });
+
+    // Manually trigger state update via internal method
+    (server as unknown as { updateState: (entity: unknown, url: string) => void }).updateState(
+      { actions: [], links: [] },
+      'http://example.com/api'
+    );
+
+    expect(called).toBe(true);
+  });
+});

package/src/__test__/pipeline-parser.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Pipeline Parser Tests
+ *
+ * Tests multi-step arrow-chained pipelines, multi-line input,
+ * and cross-language pipeline parsing.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createFlowDSL, parseFlowPipeline, compilePipeline } from '../index.js';
+import type { MultilingualDSL } from '@lokascript/framework';
+import { extractRoleValue } from '@lokascript/framework';
+
+describe('Pipeline Parser', () => {
+  let flow: MultilingualDSL;
+
+  beforeAll(() => {
+    flow = createFlowDSL();
+  });
+
+  // ===========================================================================
+  // Single-Line Arrow Chains
+  // ===========================================================================
+
+  describe('Arrow-delimited chains', () => {
+    it('should parse two-step pipeline with Unicode arrow', () => {
+      const result = parseFlowPipeline(
+        flow,
+        'fetch /api/users as json → transform data with uppercase',
+        'en'
+      );
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(2);
+      expect(result.steps[0].node.action).toBe('fetch');
+      expect(result.steps[1].node.action).toBe('transform');
+    });
+
+    it('should parse two-step pipeline with ASCII arrow', () => {
+      const result = parseFlowPipeline(
+        flow,
+        'fetch /api/users as json -> transform data with uppercase',
+        'en'
+      );
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(2);
+    });
+
+    it('should parse three-step pipeline', () => {
+      const result = parseFlowPipeline(
+        flow,
+        'fetch /api/data as json → transform data with uppercase → transform data with trim',
+        'en'
+      );
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(3);
+      expect(result.steps[0].node.action).toBe('fetch');
+      expect(result.steps[1].node.action).toBe('transform');
+      expect(result.steps[2].node.action).toBe('transform');
+    });
+
+    it('should preserve role values across pipeline steps', () => {
+      const result = parseFlowPipeline(
+        flow,
+        'fetch /api/users as json → transform data with uppercase',
+        'en'
+      );
+      expect(extractRoleValue(result.steps[0].node, 'source')).toBe('/api/users');
+      expect(extractRoleValue(result.steps[1].node, 'patient')).toBe('data');
+    });
+  });
+
+  // ===========================================================================
+  // Multi-Line Pipelines
+  // ===========================================================================
+
+  describe('Multi-line pipelines', () => {
+    it('should parse newline-separated commands', () => {
+      const input = `fetch /api/users as json
+transform data with uppercase`;
+      const result = parseFlowPipeline(flow, input, 'en');
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(2);
+    });
+
+    it('should skip comment lines', () => {
+      const input = `-- This is a comment
+fetch /api/users as json
+-- Another comment
+transform data with uppercase`;
+      const result = parseFlowPipeline(flow, input, 'en');
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(2);
+    });
+
+    it('should handle mixed arrows and newlines', () => {
+      const input = `fetch /api/users as json → transform data with uppercase
+stream /api/events as sse`;
+      const result = parseFlowPipeline(flow, input, 'en');
+      expect(result.steps).toHaveLength(3);
+    });
+  });
+
+  // ===========================================================================
+  // Cross-Language Pipelines
+  // ===========================================================================
+
+  describe('Cross-language pipelines', () => {
+    it('should parse Spanish pipeline', () => {
+      const result = parseFlowPipeline(
+        flow,
+        'obtener /api/users como json → transformar data con uppercase',
+        'es'
+      );
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(2);
+      expect(result.steps[0].node.action).toBe('fetch');
+    });
+
+    it('should parse Japanese SOV pipeline', () => {
+      const result = parseFlowPipeline(flow, '/api/users json で 取得', 'ja');
+      expect(result.errors).toHaveLength(0);
+      expect(result.steps).toHaveLength(1);
+      expect(result.steps[0].node.action).toBe('fetch');
+    });
+  });
+
+  // ===========================================================================
+  // Error Handling
+  // ===========================================================================
+
+  describe('Error handling', () => {
+    it('should return errors for unparseable segments', () => {
+      const result = parseFlowPipeline(flow, 'fetch /api/users → gobbledygook nonsense', 'en');
+      expect(result.steps.length).toBeGreaterThanOrEqual(1); // fetch should parse
+      expect(result.errors.length).toBeGreaterThanOrEqual(0); // nonsense may fail
+    });
+
+    it('should handle empty input', () => {
+      const result = parseFlowPipeline(flow, '', 'en');
+      expect(result.steps).toHaveLength(0);
+    });
+
+    it('should handle arrow-only input', () => {
+      const result = parseFlowPipeline(flow, '→ →', 'en');
+      expect(result.steps).toHaveLength(0);
+    });
+  });
+
+  // ===========================================================================
+  // Pipeline Compilation
+  // ===========================================================================
+
+  describe('Pipeline compilation', () => {
+    it('should compile single-step pipeline', () => {
+      const result = compilePipeline(flow, 'fetch /api/users as json into #list', 'en');
+      expect(result.ok).toBe(true);
+      expect(result.code).toContain('fetch');
+    });
+
+    it('should return error for empty pipeline', () => {
+      const result = compilePipeline(flow, '', 'en');
+      expect(result.ok).toBe(false);
+      expect(result.errors).toContain('Empty pipeline');
+    });
+
+    it('should compile multi-step pipeline via renderFlow', () => {
+      const result = compilePipeline(
+        flow,
+        'fetch /api/users as json → transform data with uppercase',
+        'en'
+      );
+      expect(result.ok).toBe(true);
+      expect(result.code).toContain("fetch('/api/users')");
+      expect(result.code).toContain('uppercase');
+      expect(result.code).toContain('--- next step ---');
+    });
+
+    it('should compile Spanish multi-step pipeline', () => {
+      const result = compilePipeline(
+        flow,
+        'obtener /api/users como json → transformar data con uppercase',
+        'es'
+      );
+      expect(result.ok).toBe(true);
+      expect(result.code).toContain("fetch('/api/users')");
+      expect(result.code).toContain('uppercase');
+    });
+  });
+});

package/src/__test__/route-extractor.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Route Extractor Tests
+ *
+ * Tests extraction of server route descriptors from FlowSpec objects.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createFlowDSL, toFlowSpec, extractRoute, extractRoutes } from '../index.js';
+import type { MultilingualDSL } from '@lokascript/framework';
+
+describe('Route Extractor', () => {
+  let flow: MultilingualDSL;
+
+  beforeAll(() => {
+    flow = createFlowDSL();
+  });
+
+  describe('Single route extraction', () => {
+    it('should extract GET route from fetch', () => {
+      const node = flow.parse('fetch /api/users as json', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route).not.toBeNull();
+      expect(route!.path).toBe('/api/users');
+      expect(route!.method).toBe('GET');
+      expect(route!.responseFormat).toBe('json');
+    });
+
+    it('should extract POST route from submit', () => {
+      const node = flow.parse('submit #checkout to /api/order as json', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.path).toBe('/api/order');
+      expect(route!.method).toBe('POST');
+    });
+
+    it('should extract path params from {param} syntax', () => {
+      const node = flow.parse('fetch /api/users/{id}', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.pathParams).toContain('id');
+    });
+
+    it('should extract path params from :param syntax', () => {
+      const node = flow.parse('fetch /api/users/:id', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.pathParams).toContain('id');
+    });
+
+    it('should generate handler name from URL', () => {
+      const node = flow.parse('fetch /api/users as json', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.handlerName).toBe('getUsers');
+    });
+
+    it('should generate create prefix for POST', () => {
+      const node = flow.parse('submit #form to /api/users', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.handlerName).toBe('createUsers');
+    });
+
+    it('should return null for transform (no URL)', () => {
+      const node = flow.parse('transform data with uppercase', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route).toBeNull();
+    });
+
+    it('should mark stream as SSE response format', () => {
+      const node = flow.parse('stream /api/events as sse', 'en');
+      const spec = toFlowSpec(node, 'en');
+      const route = extractRoute(spec);
+      expect(route!.responseFormat).toBe('sse');
+      expect(route!.sourceCommand).toBe('stream');
+    });
+  });
+
+  describe('Batch route extraction', () => {
+    it('should extract multiple routes', () => {
+      const specs = [
+        toFlowSpec(flow.parse('fetch /api/users as json', 'en'), 'en'),
+        toFlowSpec(flow.parse('submit #form to /api/orders', 'en'), 'en'),
+        toFlowSpec(flow.parse('transform data with uppercase', 'en'), 'en'),
+      ];
+      const routes = extractRoutes(specs);
+      expect(routes).toHaveLength(2); // transform has no route
+      expect(routes[0].path).toBe('/api/users');
+      expect(routes[1].path).toBe('/api/orders');
+    });
+  });
+});