@lokascript/domain-flow 2.1.0

package/src/schemas/hateoas-schemas.ts

@@ -0,0 +1,152 @@
+/**
+ * HATEOAS Command Schemas
+ *
+ * Defines 4 HATEOAS-aware FlowScript commands: enter, follow, perform, capture.
+ * These compile to siren-grail workflow steps instead of vanilla JS.
+ */
+
+import { defineCommand, defineRole } from '@lokascript/framework';
+
+// =============================================================================
+// ENTER — Establish HATEOAS entry point
+// =============================================================================
+
+export const enterSchema = defineCommand({
+  action: 'enter',
+  description: 'Connect to a HATEOAS API entry point',
+  category: 'source',
+  primaryRole: 'source',
+  roles: [
+    defineRole({
+      role: 'source',
+      description: 'API entry point URL',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+    }),
+  ],
+});
+
+// =============================================================================
+// FOLLOW — Navigate by link relation
+// =============================================================================
+
+export const followSchema = defineCommand({
+  action: 'follow',
+  description: 'Navigate to a resource by following a link relation',
+  category: 'action',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Link relation name to follow (e.g., "orders", "next")',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+    }),
+    defineRole({
+      role: 'instrument',
+      description: 'Parameter or sub-resource identifier (e.g., item {id})',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+      markerOverride: {
+        en: 'item',
+        es: 'elemento',
+        ja: 'の',
+        ar: 'عنصر',
+        ko: '항목',
+        zh: '项',
+        tr: 'öğe',
+        fr: 'élément',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// PERFORM — Execute a server-defined action
+// =============================================================================
+
+export const performSchema = defineCommand({
+  action: 'perform',
+  description: 'Execute a server-defined action (Siren affordance)',
+  category: 'action',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Action name to execute (e.g., "create-order", "ship-order")',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 1,
+    }),
+    defineRole({
+      role: 'source',
+      description: 'Data source — form selector or inline data',
+      required: false,
+      expectedTypes: ['selector', 'expression'],
+      svoPosition: 1,
+      sovPosition: 2,
+      markerOverride: {
+        en: 'with',
+        es: 'con',
+        ja: 'で',
+        ar: 'ب',
+        ko: '로',
+        zh: '用',
+        tr: 'ile',
+        fr: 'avec',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// CAPTURE — Bind response data to a variable
+// =============================================================================
+
+export const captureSchema = defineCommand({
+  action: 'capture',
+  description: 'Bind response data to a named variable for later use',
+  category: 'action',
+  primaryRole: 'destination',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Property path to capture (optional — captures entire entity if omitted)',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Variable name to bind the captured value to',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+      markerOverride: {
+        en: 'as',
+        es: 'como',
+        ja: 'として',
+        ar: 'ك',
+        ko: '로',
+        zh: '为',
+        tr: 'olarak',
+        fr: 'comme',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// All HATEOAS Schemas
+// =============================================================================
+
+export const hateoasSchemas = [enterSchema, followSchema, performSchema, captureSchema];

package/src/schemas/index.ts

@@ -0,0 +1,320 @@
+/**
+ * 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.
+ */
+
+import { defineCommand, defineRole } from '@lokascript/framework';
+
+// =============================================================================
+// FETCH — Single HTTP request with target
+// =============================================================================
+
+export const fetchSchema = defineCommand({
+  action: 'fetch',
+  description: 'Fetch data from a URL and deliver to a target element',
+  category: 'source',
+  primaryRole: 'source',
+  roles: [
+    defineRole({
+      role: 'source',
+      description: 'URL to fetch from',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Response format (json, html, text)',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+      markerOverride: {
+        en: 'as',
+        es: 'como',
+        ja: 'で',
+        ar: 'ك',
+        ko: '로',
+        zh: '以',
+        tr: 'olarak',
+        fr: 'comme',
+      },
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Target element to deliver data to',
+      required: false,
+      expectedTypes: ['selector', 'expression'],
+      svoPosition: 0,
+      sovPosition: 0,
+      markerOverride: {
+        en: 'into',
+        es: 'en',
+        ja: 'に',
+        ar: 'في',
+        ko: '에',
+        zh: '到',
+        tr: 'e',
+        fr: 'dans',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// POLL — Repeated fetch with interval
+// =============================================================================
+
+export const pollSchema = defineCommand({
+  action: 'poll',
+  description: 'Repeatedly fetch data at a specified interval',
+  category: 'source',
+  primaryRole: 'source',
+  roles: [
+    defineRole({
+      role: 'source',
+      description: 'URL to poll',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 4,
+      sovPosition: 4,
+    }),
+    defineRole({
+      role: 'duration',
+      description: 'Polling interval (e.g., 5s, 30s, 1m)',
+      required: true,
+      expectedTypes: ['expression', 'literal'],
+      svoPosition: 3,
+      sovPosition: 3,
+      markerOverride: {
+        en: 'every',
+        es: 'cada',
+        ja: 'ごとに',
+        ar: 'كل',
+        ko: '마다',
+        zh: '每',
+        tr: 'her',
+        fr: 'chaque',
+      },
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Response format (json, html, text)',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+      markerOverride: {
+        en: 'as',
+        es: 'como',
+        ja: 'で',
+        ar: 'ك',
+        ko: '로',
+        zh: '以',
+        tr: 'olarak',
+        fr: 'comme',
+      },
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Target element for poll results',
+      required: false,
+      expectedTypes: ['selector', 'expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+      markerOverride: {
+        en: 'into',
+        es: 'en',
+        ja: 'に',
+        ar: 'في',
+        ko: '에',
+        zh: '到',
+        tr: 'e',
+        fr: 'dans',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// STREAM — Server-Sent Events connection
+// =============================================================================
+
+export const streamSchema = defineCommand({
+  action: 'stream',
+  description: 'Open a streaming connection (SSE) to a URL',
+  category: 'source',
+  primaryRole: 'source',
+  roles: [
+    defineRole({
+      role: 'source',
+      description: 'URL for SSE stream',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 2,
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Stream type (sse)',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 1,
+      markerOverride: {
+        en: 'as',
+        es: 'como',
+        ja: 'で',
+        ar: 'ك',
+        ko: '로',
+        zh: '以',
+        tr: 'olarak',
+        fr: 'comme',
+      },
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Target element for streamed data',
+      required: false,
+      expectedTypes: ['selector', 'expression'],
+      svoPosition: 0,
+      sovPosition: 0,
+      markerOverride: {
+        en: 'into',
+        es: 'en',
+        ja: 'に',
+        ar: 'في',
+        ko: '에',
+        zh: '到',
+        tr: 'e',
+        fr: 'dans',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// SUBMIT — Form submission
+// =============================================================================
+
+export const submitSchema = defineCommand({
+  action: 'submit',
+  description: 'Submit form data to a URL',
+  category: 'action',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Form element to submit',
+      required: true,
+      expectedTypes: ['selector', 'expression'],
+      svoPosition: 2,
+      sovPosition: 1,
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'URL to submit to',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 1,
+      sovPosition: 2,
+      markerOverride: {
+        en: 'to',
+        es: 'a',
+        ja: 'に',
+        ar: 'إلى',
+        ko: '로',
+        zh: '到',
+        tr: 'e',
+        fr: 'vers',
+      },
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Request encoding (json, form, multipart)',
+      required: false,
+      expectedTypes: ['expression'],
+      svoPosition: 0,
+      sovPosition: 0,
+      markerOverride: {
+        en: 'as',
+        es: 'como',
+        ja: 'で',
+        ar: 'ك',
+        ko: '로',
+        zh: '以',
+        tr: 'olarak',
+        fr: 'comme',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// TRANSFORM — Data transformation step
+// =============================================================================
+
+export const transformSchema = defineCommand({
+  action: 'transform',
+  description: 'Transform data using a function or format string',
+  category: 'transform',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Data to transform',
+      required: true,
+      expectedTypes: ['expression'],
+      svoPosition: 2,
+      sovPosition: 1,
+    }),
+    defineRole({
+      role: 'instrument',
+      description: 'Transform function, format string, or mapping',
+      required: true,
+      expectedTypes: ['expression', 'literal'],
+      svoPosition: 1,
+      sovPosition: 2,
+      markerOverride: {
+        en: 'with',
+        es: 'con',
+        ja: 'で',
+        ar: 'ب',
+        ko: '로',
+        zh: '用',
+        tr: 'ile',
+        fr: 'avec',
+      },
+    }),
+  ],
+});
+
+// =============================================================================
+// HATEOAS Schemas (re-exported from dedicated file)
+// =============================================================================
+
+export {
+  enterSchema,
+  followSchema,
+  performSchema,
+  captureSchema,
+  hateoasSchemas,
+} from './hateoas-schemas.js';
+import { hateoasSchemas } from './hateoas-schemas.js';
+
+// =============================================================================
+// All Schemas
+// =============================================================================
+
+export const allSchemas = [
+  fetchSchema,
+  pollSchema,
+  streamSchema,
+  submitSchema,
+  transformSchema,
+  ...hateoasSchemas,
+];

package/src/siren-agent.d.ts

@@ -0,0 +1,14 @@
+/** Type stub for optional peer dependency siren-agent */
+declare module 'siren-agent' {
+  export class OODAAgent {
+    constructor(url: string, opts: Record<string, unknown>);
+    run(): Promise<{
+      status: 'stopped' | 'error' | 'maxSteps';
+      reason: string;
+      result?: unknown;
+      steps: number;
+      history: Array<Record<string, unknown>>;
+    }>;
+  }
+  export function compileWorkflow(steps: Array<Record<string, unknown>>): unknown;
+}