@auto-engineer/narrative 0.11.11

package/src/id/hasAllIds.specs.ts

@@ -0,0 +1,267 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import { hasAllIds, addAutoIds } from './index';
+import { getNarratives } from '../getNarratives';
+import { InMemoryFileStore, type IFileStore } from '@auto-engineer/file-store';
+import * as flowApi from '../narrative';
+import * as fluent from '../fluent-builder';
+import * as dataBuilders from '../data-narrative-builders';
+import * as typesApi from '../types';
+import gql from 'graphql-tag';
+
+const importMap = {
+  '../flow': flowApi,
+  '../fluent-builder': fluent,
+  '../data-flow-builders': dataBuilders,
+  '../types': typesApi,
+  'graphql-tag': gql,
+};
+
+describe('hasAllIds', () => {
+  let vfs: IFileStore;
+  const root = '/test';
+
+  beforeEach(async () => {
+    vfs = new InMemoryFileStore();
+
+    const flowWithoutIds = `
+import { flow, specs, rule, example } from '../narrative';
+import { command } from '../fluent-builder';
+
+flow('Test Flow Without IDs', () => {
+  command('Test slice without ID')
+    .server(() => {
+      specs('Test specs', () => {
+        rule('Test rule without ID', () => {
+          example('Test example')
+            .when({ test: 'data' })
+            .then({ result: 'success' });
+        });
+      });
+    });
+});`;
+
+    const flowWithIds = `
+import { flow, specs, rule, example } from '../narrative';
+import { command } from '../fluent-builder';
+
+flow('Test Flow with IDs', 'FLOW-001', () => {
+  command('Test slice with ID', 'SLICE-001')
+    .server(() => {
+      specs('Test specs', () => {
+        rule('Test rule with ID', 'RULE-001', () => {
+          example('Test example')
+            .when({ test: 'data' })
+            .then({ result: 'success' });
+        });
+      });
+    });
+});`;
+
+    const multipleFlowsSameSource = `
+import { flow, specs, should } from '../narrative';
+import { experience } from '../fluent-builder';
+
+flow('Home Screen', 'AUTO-aifPcU3hw', () => {
+  experience('Active Surveys Summary', 'AUTO-slice1').client(() => {
+    specs(() => {
+      should('show active surveys summary');
+    });
+  });
+});
+
+flow('Create Survey', 'AUTO-MPviTMrQC', () => {
+  experience('Create Survey Form', 'AUTO-slice2').client(() => {
+    specs(() => {
+      should('allow entering survey title');
+    });
+  });
+});
+
+flow('Response Analytics', 'AUTO-eME978Euk', () => {
+  experience('Response Rate Charts', 'AUTO-slice3').client(() => {
+    specs(() => {
+      should('show daily response rate charts');
+    });
+  });
+});`;
+
+    const multipleFlowsIncomplete = `
+import { flow, specs, should } from '../narrative';
+import { experience } from '../fluent-builder';
+
+flow('Home Screen', 'AUTO-aifPcU3hw', () => {
+  experience('Active Surveys Summary', 'AUTO-slice1').client(() => {
+    specs(() => {
+      should('show active surveys summary');
+    });
+  });
+});
+
+flow('Create Survey', () => {
+  experience('Create Survey Form', 'AUTO-slice2').client(() => {
+    specs(() => {
+      should('allow entering survey title');
+    });
+  });
+});
+
+flow('Response Analytics', 'AUTO-eME978Euk', () => {
+  experience('Response Rate Charts', 'AUTO-slice3').client(() => {
+    specs(() => {
+      should('show daily response rate charts');
+    });
+  });
+});`;
+
+    const multipleFlowsSliceMissing = `
+import { flow, specs, should } from '../narrative';
+import { experience } from '../fluent-builder';
+
+flow('Home Screen', 'AUTO-aifPcU3hw', () => {
+  experience('Active Surveys Summary', 'AUTO-slice1').client(() => {
+    specs(() => {
+      should('show active surveys summary');
+    });
+  });
+});
+
+flow('Create Survey', 'AUTO-MPviTMrQC', () => {
+  experience('Create Survey Form').client(() => {
+    specs(() => {
+      should('allow entering survey title');
+    });
+  });
+});
+
+flow('Response Analytics', 'AUTO-eME978Euk', () => {
+  experience('Response Rate Charts', 'AUTO-slice3').client(() => {
+    specs(() => {
+      should('show daily response rate charts');
+    });
+  });
+});`;
+
+    const flowContent1 = new TextEncoder().encode(flowWithoutIds);
+    const flowContent2 = new TextEncoder().encode(flowWithIds);
+    const flowContent3 = new TextEncoder().encode(multipleFlowsSameSource);
+    const flowContent4 = new TextEncoder().encode(multipleFlowsIncomplete);
+    const flowContent5 = new TextEncoder().encode(multipleFlowsSliceMissing);
+    await vfs.write('/test/flow-without-ids.flow.ts', flowContent1);
+    await vfs.write('/test/flow-with-ids.flow.ts', flowContent2);
+    await vfs.write('/test/homepage.flow.ts', flowContent3);
+    await vfs.write('/test/homepage-incomplete.flow.ts', flowContent4);
+    await vfs.write('/test/homepage-slice-missing.flow.ts', flowContent5);
+  });
+  it('should return false for models without IDs', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const flowWithoutIds = model.narratives.find((f) => f.name === 'Test Flow Without IDs');
+    expect(flowWithoutIds).toBeDefined();
+
+    if (flowWithoutIds) {
+      const modelWithoutIds = { ...model, narratives: [flowWithoutIds] };
+      expect(hasAllIds(modelWithoutIds)).toBe(false);
+    }
+  });
+
+  it('should return true for models with complete IDs', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const modelWithIds = addAutoIds(model);
+    expect(hasAllIds(modelWithIds)).toBe(true);
+  });
+
+  it('should return true for flows that already have IDs', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const testFlowWithIds = model.narratives.find((f) => f.name === 'Test Flow with IDs');
+    expect(testFlowWithIds).toBeDefined();
+
+    if (testFlowWithIds) {
+      const modelWithExistingIds = { ...model, narratives: [testFlowWithIds] };
+      expect(hasAllIds(modelWithExistingIds)).toBe(true);
+    }
+  });
+
+  it('should return false if any slice is missing an ID', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const modelWithIds = addAutoIds(model);
+    expect(modelWithIds.narratives.length).toBeGreaterThan(0);
+    expect(modelWithIds.narratives[0].slices.length).toBeGreaterThan(0);
+
+    const modifiedModel = structuredClone(modelWithIds);
+    modifiedModel.narratives[0].slices[0].id = '';
+    expect(hasAllIds(modifiedModel)).toBe(false);
+  });
+
+  it('should return false if any rule is missing an ID', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const modelWithIds = addAutoIds(model);
+
+    let found = false;
+    for (const flow of modelWithIds.narratives) {
+      for (const slice of flow.slices) {
+        if ('server' in slice && slice.server?.specs?.rules !== undefined && slice.server.specs.rules.length > 0) {
+          const modifiedModel = structuredClone(modelWithIds);
+          const modifiedFlow = modifiedModel.narratives.find((f) => f.name === flow.name);
+          const modifiedSlice = modifiedFlow?.slices.find((s) => s.name === slice.name);
+          if (modifiedSlice && 'server' in modifiedSlice && modifiedSlice.server?.specs?.rules !== undefined) {
+            modifiedSlice.server.specs.rules[0].id = '';
+            expect(hasAllIds(modifiedModel)).toBe(false);
+            found = true;
+            break;
+          }
+        }
+      }
+      if (found) break;
+    }
+
+    expect(found).toBe(true);
+  });
+
+  it('should return true when multiple flows with same sourceFile all have IDs', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const homepageFlows = model.narratives.filter(
+      (f) => f.sourceFile !== undefined && f.sourceFile.includes('homepage.flow.ts'),
+    );
+    expect(homepageFlows.length).toBe(3);
+
+    const homepageModel = { ...model, narratives: homepageFlows };
+    expect(hasAllIds(homepageModel)).toBe(true);
+  });
+
+  it('should return false when any flow in multiple flows with same sourceFile is missing ID', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const homepageFlows = model.narratives.filter(
+      (f) => f.sourceFile !== undefined && f.sourceFile.includes('homepage-incomplete.flow.ts'),
+    );
+    expect(homepageFlows.length).toBe(3);
+
+    const homepageModel = { ...model, narratives: homepageFlows };
+    expect(hasAllIds(homepageModel)).toBe(false);
+  });
+
+  it('should return false when any slice in multiple flows with same sourceFile is missing ID', async () => {
+    const result = await getNarratives({ vfs, root, pattern: /\.(flow)\.(ts)$/, fastFsScan: true, importMap });
+    const model = result.toModel();
+
+    const homepageFlows = model.narratives.filter(
+      (f) => f.sourceFile !== undefined && f.sourceFile.includes('homepage-slice-missing.flow.ts'),
+    );
+    expect(homepageFlows.length).toBe(3);
+
+    const homepageModel = { ...model, narratives: homepageFlows };
+    expect(hasAllIds(homepageModel)).toBe(false);
+  });
+});

package/src/id/hasAllIds.ts

@@ -0,0 +1,23 @@
+import { Model, Slice } from '../index';
+
+function hasValidId(item: { id?: string }): boolean {
+  return item.id !== undefined && item.id !== '';
+}
+
+function hasServerSpecIds(slice: Slice): boolean {
+  if (!('server' in slice) || slice.server?.specs?.rules === undefined) return true;
+  return slice.server.specs.rules.every(hasValidId);
+}
+
+function hasClientSpecIds(_slice: Slice): boolean {
+  // Client specs use string rules (no IDs needed), so always valid
+  return true;
+}
+
+function hasSliceIds(slice: Slice): boolean {
+  return hasValidId(slice) && hasServerSpecIds(slice) && hasClientSpecIds(slice);
+}
+
+export function hasAllIds(specs: Model): boolean {
+  return specs.narratives.every((narrative) => hasValidId(narrative) && narrative.slices.every(hasSliceIds));
+}

package/src/id/index.ts

@@ -0,0 +1,2 @@
+export { hasAllIds } from './hasAllIds';
+export { addAutoIds } from './addAutoIds';

package/src/index.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+
+// Core types and utilities
+export type {
+  Integration,
+  DataSink,
+  DataSource,
+  DataSinkItem,
+  DataSourceItem,
+  DataItem,
+  MessageTarget,
+  Destination,
+  Origin,
+  State,
+  Command,
+  Event,
+} from './types';
+export { MessageTargetSchema, DataSinkSchema, DataSourceSchema } from './schema';
+export { createIntegration } from './types';
+
+// Apollo GraphQL
+export { gql } from 'graphql-tag';
+
+// HTTP GET template literal function
+export const get = (strings: TemplateStringsArray, ...values: unknown[]) => {
+  return strings.reduce((result, str, i) => {
+    const value = values[i];
+    return result + str + (value !== undefined && value !== null ? String(value) : '');
+  }, '');
+};
+
+// Fluent API
+export type {
+  FluentCommandSliceBuilder,
+  FluentQuerySliceBuilder,
+  FluentReactionSliceBuilder,
+  FluentExperienceSliceBuilder,
+} from './fluent-builder';
+export { command, query, react, experience, decide, evolve } from './fluent-builder';
+
+// Data narrative builders
+export { sink, source } from './data-narrative-builders';
+export type { FieldSelector } from './data-narrative-builders';
+
+// Narrative language functions
+export { narrative, narrative as flow } from './narrative';
+export { client, server, specs, should, request, data, rule, example } from './narrative';
+export type { SliceTypeValueInterface } from './narrative';
+export { SliceType } from './narrative';
+
+// Narrative conversion utilities
+export { getNarratives } from './getNarratives';
+export { modelToNarrative } from './transformers/model-to-narrative';
+
+// Testing helpers
+export { createNarrativeSpec, given, when } from './testing';
+
+// Schema definitions for progressive narrative creation
+export {
+  NarrativeNamesSchema as NarrativeNamesSystemSchema,
+  SliceNamesSchema as SliceNamesSystemSchema,
+  ClientServerNamesSchema as ClientServerNamesSystemSchema,
+  modelSchema as SpecsSystemSchema,
+  MessageFieldSchema,
+  MessageSchema,
+  CommandSchema,
+  EventSchema,
+  StateSchema,
+  IntegrationSchema,
+  CommandSliceSchema,
+  QuerySliceSchema,
+  ReactSliceSchema,
+  ExperienceSliceSchema,
+  SliceSchema,
+  NarrativeSchema,
+  modelSchema,
+  EventExampleSchema,
+  CommandExampleSchema,
+  ExampleSchema,
+  RuleSchema,
+  SpecSchema,
+} from './schema';
+
+import {
+  CommandExampleSchema,
+  ErrorExampleSchema,
+  EventExampleSchema,
+  NarrativeSchema,
+  SliceSchema,
+  modelSchema,
+  StateExampleSchema,
+  QuerySliceSchema,
+  ReactSliceSchema,
+  ExperienceSliceSchema,
+  MessageSchema,
+  MessageFieldSchema,
+  CommandSliceSchema,
+  ExampleSchema,
+  RuleSchema,
+  SpecSchema,
+} from './schema';
+export type Model = z.infer<typeof modelSchema>;
+export type Narrative = z.infer<typeof NarrativeSchema>;
+export type CommandExample = z.infer<typeof CommandExampleSchema>;
+export type EventExample = z.infer<typeof EventExampleSchema>;
+export type Slice = z.infer<typeof SliceSchema>;
+export type StateExample = z.infer<typeof StateExampleSchema>;
+export type ErrorExample = z.infer<typeof ErrorExampleSchema>;
+export type QuerySlice = z.infer<typeof QuerySliceSchema>;
+export type ReactSlice = z.infer<typeof ReactSliceSchema>;
+export type CommandSlice = z.infer<typeof CommandSliceSchema>;
+export type ExperienceSlice = z.infer<typeof ExperienceSliceSchema>;
+export type Message = z.infer<typeof MessageSchema>;
+export type Example = z.infer<typeof ExampleSchema>;
+export type MessageField = z.infer<typeof MessageFieldSchema>;
+export type Rule = z.infer<typeof RuleSchema>;
+export type Spec = z.infer<typeof SpecSchema>;
+
+export {
+  commandHandler as exportSchemaCommandHandler,
+  type ExportSchemaCommand,
+  type ExportSchemaEvents,
+  type SchemaExportedEvent,
+  type SchemaExportFailedEvent,
+} from './commands/export-schema';
+
+import { commandHandler as exportSchemaHandler } from './commands/export-schema';
+export const COMMANDS = [exportSchemaHandler];
+
+// ID assignment utilities
+export { addAutoIds, hasAllIds } from './id';

package/src/integration-export-registry.ts

@@ -0,0 +1,83 @@
+import { Integration } from './types';
+import { IntegrationExport } from './loader/ts-utils';
+
+/**
+ * Global registry to map integration internal names to their export names and source paths
+ */
+class IntegrationExportRegistry {
+  private integrationNameToExportName = new Map<string, string>();
+  private exportNameToIntegrationName = new Map<string, string>();
+  private exportNameToSourcePath = new Map<string, string>();
+
+  /**
+   * Register integration exports from AST parsing
+   */
+  registerIntegrationExports(integrationExports: IntegrationExport[]): void {
+    for (const { exportName, integrationName, sourcePath } of integrationExports) {
+      this.integrationNameToExportName.set(integrationName, exportName);
+      this.exportNameToIntegrationName.set(exportName, integrationName);
+      if (sourcePath !== null && sourcePath !== undefined && sourcePath !== '') {
+        this.exportNameToSourcePath.set(exportName, sourcePath);
+      }
+    }
+  }
+
+  /**
+   * Get the export name for an integration based on its internal name
+   */
+  getExportName(integrationName: string): string | undefined {
+    return this.integrationNameToExportName.get(integrationName);
+  }
+
+  /**
+   * Get the integration name for an export name
+   */
+  getIntegrationName(exportName: string): string | undefined {
+    return this.exportNameToIntegrationName.get(exportName);
+  }
+
+  /**
+   * Get the source path for an export name
+   */
+  getSourcePath(exportName: string): string | undefined {
+    return this.exportNameToSourcePath.get(exportName);
+  }
+
+  /**
+   * Get the export name for an Integration object
+   * Uses the object's exportName property first, then falls back to registry lookup
+   */
+  getExportNameForIntegration(integration: Integration): string {
+    // First try the exportName property if set
+    if (integration.exportName !== null && integration.exportName !== undefined && integration.exportName !== '') {
+      return integration.exportName;
+    }
+
+    // Fall back to registry lookup
+    const exportName = this.getExportName(integration.name);
+    return exportName !== null && exportName !== undefined && exportName !== '' ? exportName : integration.name; // Ultimate fallback to internal name
+  }
+
+  /**
+   * Clear all registered exports
+   */
+  clear(): void {
+    this.integrationNameToExportName.clear();
+    this.exportNameToIntegrationName.clear();
+    this.exportNameToSourcePath.clear();
+  }
+
+  /**
+   * Get all registered integration exports
+   */
+  getAll(): IntegrationExport[] {
+    const exports: IntegrationExport[] = [];
+    for (const [integrationName, exportName] of this.integrationNameToExportName) {
+      exports.push({ exportName, integrationName });
+    }
+    return exports;
+  }
+}
+
+// Global singleton registry
+export const integrationExportRegistry = new IntegrationExportRegistry();

package/src/integration-registry.ts

@@ -0,0 +1,53 @@
+// integration-helper.ts - Add this to your flow package
+import { Integration } from './types';
+import createDebug from 'debug';
+
+const debug = createDebug('auto:flow:integrations');
+if ('color' in debug && typeof debug === 'object') {
+  (debug as { color: string }).color = '6';
+} // cyan
+
+// Global registry for integrations
+class GlobalIntegrationRegistry {
+  private integrations = new Map<string, Integration>();
+
+  register(integration: Integration) {
+    debug('Registering integration: %s', integration.name);
+    this.integrations.set(integration.name, integration);
+    debug('Integration registered successfully: %s, total: %d', integration.name, this.integrations.size);
+  }
+
+  getAll(): Integration[] {
+    const integrations = Array.from(this.integrations.values());
+    debug('Getting all integrations, count: %d', integrations.length);
+    if (integrations.length > 0) {
+      debug(
+        'Integrations: %o',
+        integrations.map((i) => i.name),
+      );
+    }
+    return integrations;
+  }
+
+  clear() {
+    debug('Clearing integrations, current count: %d', this.integrations.size);
+    this.integrations.clear();
+  }
+
+  get(name: string): Integration | undefined {
+    const integration = this.integrations.get(name);
+    debug('Getting integration %s: %s', name, integration ? 'found' : 'not found');
+    return integration;
+  }
+}
+
+export const globalIntegrationRegistry = new GlobalIntegrationRegistry();
+
+export const registerIntegrations = (...integrations: Integration[]) => {
+  for (const integration of integrations) {
+    globalIntegrationRegistry.register(integration);
+  }
+};
+
+// Export for use in schema generation
+export { globalIntegrationRegistry as integrationRegistry };

package/src/loader/fs-path.ts

@@ -0,0 +1,29 @@
+export const toPosix = (p: string) => p.replace(/\\/g, '/');
+
+export function dirname(p: string) {
+  const posix = toPosix(p);
+  const idx = posix.lastIndexOf('/');
+  return idx > 0 ? posix.slice(0, idx) : '/';
+}
+
+export function join(a: string, b: string) {
+  const aa = toPosix(a).replace(/\/+$/, '');
+  const bb = toPosix(b).replace(/^\/+/, '');
+  return (aa ? aa + '/' : '/') + bb;
+}
+
+export function normalize(path: string): string {
+  const parts = toPosix(path).split('/');
+  const out: string[] = [];
+  for (const part of parts) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      if (out.length) out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return '/' + out.join('/');
+}
+
+export const CANDIDATE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];