@auto-engineer/narrative 0.11.11

package/src/samples/test-with-ids.flow.ts

@@ -0,0 +1,109 @@
+import { flow, specs, rule, example } from '../narrative';
+import { command, query, react } from '../fluent-builder';
+import { type Event, type Command, type State } from '../types';
+
+type TestItemCreated = Event<
+  'TestItemCreated',
+  {
+    id: string;
+    name: string;
+    createdAt: Date;
+  }
+>;
+
+type CreateTestItem = Command<
+  'CreateTestItem',
+  {
+    itemId: string;
+    name: string;
+  }
+>;
+
+type TestItemState = State<
+  'TestItemState',
+  {
+    id: string;
+    name: string;
+  }
+>;
+
+flow('Test Flow with IDs', 'FLOW-001', () => {
+  command('Create test item', 'SLICE-001')
+    .client(() => {})
+    .server(() => {
+      specs('Test item creation specs', () => {
+        rule('Valid test items should be created successfully', 'RULE-001', () => {
+          example('User creates a new test item with valid data')
+            .when<CreateTestItem>({
+              itemId: 'test_123',
+              name: 'Test Item',
+            })
+            .then<TestItemCreated>({
+              id: 'test_123',
+              name: 'Test Item',
+              createdAt: new Date('2024-01-15T10:00:00Z'),
+            });
+        });
+
+        rule('Invalid test items should be rejected', 'RULE-002', () => {
+          example('User tries to create item with empty name')
+            .when<CreateTestItem>({
+              itemId: 'test_456',
+              name: '',
+            })
+            .then([
+              {
+                errorType: 'ValidationError' as const,
+                message: 'Item name cannot be empty',
+              },
+            ]);
+        });
+      });
+    });
+
+  query('Get test items', 'SLICE-002')
+    .client(() => {})
+    .server(() => {
+      specs('Test item retrieval specs', () => {
+        rule('Items should be retrievable after creation', 'RULE-003', () => {
+          example('Item becomes available after creation event')
+            .when<TestItemCreated>({
+              id: 'test_123',
+              name: 'Test Item',
+              createdAt: new Date('2024-01-15T10:00:00Z'),
+            })
+            .then<TestItemState>({
+              id: 'test_123',
+              name: 'Test Item',
+            });
+        });
+      });
+    });
+
+  react('React to test event', 'SLICE-003').server(() => {
+    specs('Test event reaction specs', () => {
+      rule('System should react to test item creation', 'RULE-004', () => {
+        example('Notification sent when test item is created')
+          .when([
+            {
+              eventRef: 'TestItemCreated',
+              exampleData: {
+                id: 'test_789',
+                name: 'Another Test Item',
+                createdAt: new Date('2024-01-16T10:00:00Z'),
+              },
+            },
+          ])
+          .then([
+            {
+              commandRef: 'SendNotification',
+              exampleData: {
+                message: 'New test item created: Another Test Item',
+                recipientId: 'admin',
+              },
+            },
+          ]);
+      });
+    });
+  });
+});

package/src/schema-test.ts

@@ -0,0 +1,67 @@
+import { DataSinkSchema, DataSourceSchema, MessageTargetSchema } from './schema';
+import { sink, source } from './data-narrative-builders';
+
+// Test that the builders produce output compatible with the schema
+const testSink = sink().event('TestEvent').fields({ id: true }).toStream('test-${id}');
+
+const testSource = source().state('TestState').fromProjection('TestProjection', 'id');
+
+// Test new additionalInstructions functionality
+const sinkWithInstructions = sink()
+  .event('TestEvent')
+  .additionalInstructions('Custom processing instructions')
+  .toStream('test-${id}');
+
+const sourceWithInstructions = source()
+  .state('TestState')
+  .additionalInstructions('Custom query instructions')
+  .fromProjection('TestProjection', 'eventId');
+
+// Test withState functionality for commands
+const commandSinkWithState = sink()
+  .command('TestCommand')
+  .withState(testSource)
+  .additionalInstructions('Process with state context')
+  .toIntegration('TestIntegration', 'DoSomething', 'command');
+
+console.log('Testing sink schema compatibility...');
+const sinkResult = DataSinkSchema.safeParse(testSink);
+console.log('Sink valid:', sinkResult.success);
+if (!sinkResult.success) {
+  console.log('Sink errors:', sinkResult.error);
+}
+
+console.log('Testing source schema compatibility...');
+const sourceResult = DataSourceSchema.safeParse(testSource);
+console.log('Source valid:', sourceResult.success);
+if (!sourceResult.success) {
+  console.log('Source errors:', sourceResult.error);
+}
+
+console.log('Testing message target schema compatibility...');
+const targetResult = MessageTargetSchema.safeParse(testSink.target);
+console.log('Target valid:', targetResult.success);
+if (!targetResult.success) {
+  console.log('Target errors:', targetResult.error);
+}
+
+console.log('\nTesting sink with additional instructions...');
+const sinkWithInstructionsResult = DataSinkSchema.safeParse(sinkWithInstructions);
+console.log('Sink with instructions valid:', sinkWithInstructionsResult.success);
+if (!sinkWithInstructionsResult.success) {
+  console.log('Sink with instructions errors:', sinkWithInstructionsResult.error);
+}
+
+console.log('\nTesting source with additional instructions...');
+const sourceWithInstructionsResult = DataSourceSchema.safeParse(sourceWithInstructions);
+console.log('Source with instructions valid:', sourceWithInstructionsResult.success);
+if (!sourceWithInstructionsResult.success) {
+  console.log('Source with instructions errors:', sourceWithInstructionsResult.error);
+}
+
+console.log('\nTesting command sink with state...');
+const commandSinkWithStateResult = DataSinkSchema.safeParse(commandSinkWithState);
+console.log('Command sink with state valid:', commandSinkWithStateResult.success);
+if (!commandSinkWithStateResult.success) {
+  console.log('Command sink with state errors:', commandSinkWithStateResult.error);
+}

package/src/schema.ts

@@ -0,0 +1,398 @@
+import { z } from 'zod';
+
+const IntegrationSchema = z
+  .object({
+    name: z.string().describe('Integration name (e.g., MailChimp, Twilio)'),
+    description: z.string().optional(),
+    source: z.string().describe('integration module source (e.g., @auto-engineer/mailchimp-integration)'),
+  })
+  .describe('External service integration configuration');
+
+// Data flow schemas for unified architecture
+export const MessageTargetSchema = z
+  .object({
+    type: z.enum(['Event', 'Command', 'State']).describe('Type of message to target'),
+    name: z.string().describe('Name of the specific message'),
+    fields: z.record(z.unknown()).optional().describe('Field selector for partial message targeting'),
+  })
+  .describe('Target message with optional field selection');
+
+export const DestinationSchema = z
+  .discriminatedUnion('type', [
+    z.object({
+      type: z.literal('stream'),
+      pattern: z.string().describe('Stream pattern with interpolation (e.g., listing-${propertyId})'),
+    }),
+    z.object({
+      type: z.literal('integration'),
+      systems: z.array(z.string()).describe('Integration names to send to'),
+      message: z
+        .object({
+          name: z.string(),
+          type: z.enum(['command', 'query', 'reaction']),
+        })
+        .optional(),
+    }),
+    z.object({
+      type: z.literal('database'),
+      collection: z.string().describe('Database collection name'),
+    }),
+    z.object({
+      type: z.literal('topic'),
+      name: z.string().describe('Message topic/queue name'),
+    }),
+  ])
+  .describe('Destination for outbound data');
+
+export const OriginSchema = z
+  .discriminatedUnion('type', [
+    z.object({
+      type: z.literal('projection'),
+      name: z.string(),
+      idField: z.string().describe('Field from event used as the projection’s unique identifier'),
+    }),
+    z.object({
+      type: z.literal('readModel'),
+      name: z.string().describe('Read model name'),
+    }),
+    z.object({
+      type: z.literal('database'),
+      collection: z.string().describe('Database collection name'),
+      query: z.unknown().optional().describe('Optional query filter'),
+    }),
+    z.object({
+      type: z.literal('api'),
+      endpoint: z.string().describe('API endpoint URL'),
+      method: z.string().optional().describe('HTTP method (defaults to GET)'),
+    }),
+    z.object({
+      type: z.literal('integration'),
+      systems: z.array(z.string()),
+    }),
+  ])
+  .describe('Origin for inbound data');
+
+const DataSinkSchema = z
+  .object({
+    target: MessageTargetSchema,
+    destination: DestinationSchema,
+    transform: z.string().optional().describe('Optional transformation function name'),
+    _additionalInstructions: z.string().optional().describe('Additional instructions'),
+    _withState: z
+      .lazy(() => DataSourceSchema)
+      .optional()
+      .describe('Optional state data source for command'),
+  })
+  .describe('Data sink configuration for outbound data flow');
+
+const DataSourceSchema = z
+  .object({
+    target: MessageTargetSchema,
+    origin: OriginSchema,
+    transform: z.string().optional().describe('Optional transformation function name'),
+    _additionalInstructions: z.string().optional().describe('Additional instructions'),
+  })
+  .describe('Data source configuration for inbound data flow');
+
+const MessageFieldSchema = z
+  .object({
+    name: z.string(),
+    type: z.string().describe('Field type (e.g., string, number, Date, UUID, etc.)'),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    defaultValue: z.unknown().optional().describe('Default value for optional fields'),
+  })
+  .describe('Field definition for a message');
+
+const BaseMessageSchema = z.object({
+  name: z.string().describe('Message name'),
+  fields: z.array(MessageFieldSchema),
+  description: z.string().optional(),
+  metadata: z
+    .object({
+      version: z.number().default(1).describe('Version number for schema evolution'),
+    })
+    .optional(),
+});
+
+const CommandSchema = BaseMessageSchema.extend({
+  type: z.literal('command'),
+}).describe('Command that triggers state changes');
+
+const EventSchema = BaseMessageSchema.extend({
+  type: z.literal('event'),
+  source: z.enum(['internal', 'external']).default('internal'),
+}).describe('Event representing something that has happened');
+
+const StateSchema = BaseMessageSchema.extend({
+  type: z.literal('state'),
+}).describe('State/Read Model representing a view of data');
+
+const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema]);
+
+export const EventExampleSchema = z
+  .object({
+    eventRef: z.string().describe('Reference to event message by name'),
+    exampleData: z.record(z.unknown()).describe('Example data matching the event schema'),
+    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
+  })
+  .describe('Event example with reference and data');
+
+export const CommandExampleSchema = z
+  .object({
+    commandRef: z.string().describe('Reference to command message by name'),
+    exampleData: z.record(z.unknown()).describe('Example data matching the command schema'),
+    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
+  })
+  .describe('Command example with reference and data');
+
+const StateExampleSchema = z
+  .object({
+    stateRef: z.string().describe('Reference to state message by name'),
+    exampleData: z.record(z.unknown()).describe('Example data matching the state schema'),
+    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
+  })
+  .describe('State example with reference and data');
+
+const BaseSliceSchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    description: z.string().optional(),
+    stream: z.string().optional().describe('Event stream pattern for this slice'),
+    via: z.array(z.string()).optional().describe('Integration names used by this slice'),
+    additionalInstructions: z.string().optional().describe('Additional instructions'),
+  })
+  .describe('Base properties shared by all slice types');
+
+const ErrorExampleSchema = z
+  .object({
+    errorType: z.enum(['IllegalStateError', 'ValidationError', 'NotFoundError']).describe('Expected error'),
+    message: z.string().optional().describe('Optional error message'),
+  })
+  .describe('Error outcome');
+
+const ExampleSchema = z
+  .object({
+    description: z.string().describe('Example description'),
+    given: z
+      .array(z.union([EventExampleSchema, StateExampleSchema]))
+      .optional()
+      .describe('Given conditions'),
+    when: z
+      .union([CommandExampleSchema, EventExampleSchema, z.array(CommandExampleSchema), z.array(EventExampleSchema)])
+      .describe('When action or events occur'),
+    then: z
+      .array(z.union([EventExampleSchema, StateExampleSchema, CommandExampleSchema, ErrorExampleSchema]))
+      .describe('Then expected outcomes'),
+  })
+  .describe('BDD example with given-when-then structure');
+
+const RuleSchema = z
+  .object({
+    id: z.string().optional().describe('Optional rule identifier'),
+    description: z.string().describe('Rule description'),
+    examples: z.array(ExampleSchema).describe('Examples demonstrating the rule'),
+  })
+  .describe('Business rule with examples');
+
+const SpecSchema = z
+  .object({
+    name: z.string().describe('Spec name/feature name'),
+    rules: z.array(RuleSchema).describe('Business rules for this spec'),
+  })
+  .describe('Specification with business rules');
+
+const CommandSliceSchema = BaseSliceSchema.extend({
+  type: z.literal('command'),
+  client: z.object({
+    description: z.string(),
+    specs: z
+      .object({
+        name: z.string().describe('Spec group name'),
+        rules: z.array(z.string()).describe('UI specifications (should statements)'),
+      })
+      .optional()
+      .describe('Client-side specifications'),
+  }),
+  request: z.string().describe('Command request (GraphQL, REST endpoint, or other query format)').optional(),
+  server: z.object({
+    description: z.string(),
+    data: z.array(DataSinkSchema).optional().describe('Data sinks for command slices'),
+    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+  }),
+}).describe('Command slice handling user actions and business logic');
+
+const QuerySliceSchema = BaseSliceSchema.extend({
+  type: z.literal('query'),
+  client: z.object({
+    description: z.string(),
+    specs: z
+      .object({
+        name: z.string().describe('Spec group name'),
+        rules: z.array(z.string()).describe('UI specifications (should statements)'),
+      })
+      .optional()
+      .describe('Client-side specifications'),
+  }),
+  request: z.string().describe('Query request (GraphQL, REST endpoint, or other query format)').optional(),
+  server: z.object({
+    description: z.string(),
+    data: z.array(DataSourceSchema).optional().describe('Data sources for query slices'),
+    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+  }),
+}).describe('Query slice for reading data and maintaining projections');
+
+const ReactSliceSchema = BaseSliceSchema.extend({
+  type: z.literal('react'),
+  server: z.object({
+    description: z.string().optional(),
+    data: z
+      .array(z.union([DataSinkSchema, DataSourceSchema]))
+      .optional()
+      .describe('Data items for react slices (mix of sinks and sources)'),
+    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+  }),
+}).describe('React slice for automated responses to events');
+
+const ExperienceSliceSchema = BaseSliceSchema.extend({
+  type: z.literal('experience'),
+  client: z.object({
+    description: z.string().optional(),
+    specs: z
+      .object({
+        name: z.string().describe('Spec group name'),
+        rules: z.array(z.string()).describe('UI specifications (should statements)'),
+      })
+      .optional()
+      .describe('Client-side specifications'),
+  }),
+}).describe('Experience slice for user interactions and UI behavior');
+
+const SliceSchema = z.discriminatedUnion('type', [
+  CommandSliceSchema,
+  QuerySliceSchema,
+  ReactSliceSchema,
+  ExperienceSliceSchema,
+]);
+
+const NarrativeSchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    description: z.string().optional(),
+    slices: z.array(SliceSchema),
+    sourceFile: z.string().optional(),
+  })
+  .describe('Business narrative containing related slices');
+
+// Variant 1: Just narrative names
+const NarrativeNamesOnlySchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    description: z.string().optional(),
+  })
+  .describe('Narrative with just name for initial planning');
+
+// Variant 2: Narrative with slice names
+const SliceNamesOnlySchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    description: z.string().optional(),
+    type: z.enum(['command', 'query', 'react']),
+  })
+  .describe('Slice with just name and type for structure planning');
+
+const NarrativeWithSliceNamesSchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    description: z.string().optional(),
+    slices: z.array(SliceNamesOnlySchema),
+  })
+  .describe('Narrative with slice names for structure planning');
+
+// Variant 3: Narrative with client & server names
+const ClientServerNamesSliceSchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    type: z.enum(['command', 'query', 'react']),
+    description: z.string().optional(),
+    client: z
+      .object({
+        description: z.string(),
+      })
+      .optional(),
+    server: z
+      .object({
+        description: z.string(),
+      })
+      .optional(),
+  })
+  .describe('Slice with client/server descriptions for behavior planning');
+
+const NarrativeWithClientServerNamesSchema = z
+  .object({
+    name: z.string(),
+    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    description: z.string().optional(),
+    slices: z.array(ClientServerNamesSliceSchema),
+  })
+  .describe('Narrative with client/server descriptions for behavior planning');
+
+// Variant 4: Full specs (uses existing schemas)
+
+export const NarrativeNamesSchema = z
+  .object({
+    variant: z.literal('narrative-names').describe('Just narrative names for initial ideation'),
+    narratives: z.array(NarrativeNamesOnlySchema),
+  })
+  .describe('System with just flow names for initial planning');
+
+export const SliceNamesSchema = z
+  .object({
+    variant: z.literal('slice-names').describe('Narratives with slice names for structure planning'),
+    narratives: z.array(NarrativeWithSliceNamesSchema),
+  })
+  .describe('System with narrative and slice names for structure planning');
+
+export const ClientServerNamesSchema = z
+  .object({
+    variant: z.literal('client-server-names').describe('Narratives with client/server descriptions'),
+    narratives: z.array(NarrativeWithClientServerNamesSchema),
+  })
+  .describe('System with client/server descriptions for behavior planning');
+
+export const modelSchema = z
+  .object({
+    variant: z.literal('specs').describe('Full specification with all details'),
+    narratives: z.array(NarrativeSchema),
+    messages: z.array(MessageSchema),
+    integrations: z.array(IntegrationSchema).optional(),
+  })
+  .describe('Complete system specification with all implementation details');
+
+export {
+  StateExampleSchema,
+  MessageFieldSchema,
+  ErrorExampleSchema,
+  MessageSchema,
+  CommandSchema,
+  EventSchema,
+  StateSchema,
+  IntegrationSchema,
+  CommandSliceSchema,
+  QuerySliceSchema,
+  ReactSliceSchema,
+  ExperienceSliceSchema,
+  SliceSchema,
+  NarrativeSchema,
+  ExampleSchema,
+  RuleSchema,
+  SpecSchema,
+  DataSinkSchema,
+  DataSourceSchema,
+};

package/src/slice-builder.ts

@@ -0,0 +1,100 @@
+import type { Integration } from './types';
+import { getCurrentNarrative, addSlice } from './narrative-context';
+import type { CommandSlice, QuerySlice, ReactSlice } from './index';
+
+export interface SliceConfig {
+  integration?: Integration;
+  eventStream?: string;
+  retries?: number;
+}
+
+export interface SliceBuilder {
+  via(integrationOrStream: Integration | string): SliceBuilder;
+
+  retries(count: number): SliceBuilder;
+
+  stream(eventStream: string): SliceBuilder;
+
+  command(name: string, fn: () => void): void;
+
+  query(name: string, fn: () => void): void;
+
+  reaction(name: string, fn: () => void): void;
+}
+
+export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
+  via(integrationOrStream: Integration | string): SliceBuilder {
+    if (typeof integrationOrStream === 'string') {
+      return createSliceBuilder({ ...config, eventStream: integrationOrStream });
+    } else {
+      return createSliceBuilder({ ...config, integration: integrationOrStream });
+    }
+  },
+
+  retries(count: number): SliceBuilder {
+    return createSliceBuilder({ ...config, retries: count });
+  },
+
+  stream(eventStream: string): SliceBuilder {
+    return createSliceBuilder({ ...config, eventStream });
+  },
+
+  command(name: string, fn: () => void) {
+    const flow = getCurrentNarrative();
+    if (!flow) throw new Error('No active flow');
+
+    // Create a properly typed command slice
+    const slice: CommandSlice = {
+      type: 'command',
+      name,
+      client: { description: '', specs: undefined },
+      server: { description: '', specs: { name: '', rules: [] }, data: undefined },
+      // Optional fields
+      ...(config.eventStream != null && { stream: config.eventStream }),
+      ...(config.integration && { via: [config.integration.name] }),
+      ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
+    };
+    addSlice(slice);
+    fn();
+  },
+
+  query(name: string, fn: () => void) {
+    const flow = getCurrentNarrative();
+    if (!flow) throw new Error('No active flow');
+
+    // Create a properly typed query slice
+    const slice: QuerySlice = {
+      type: 'query',
+      name,
+      client: { description: '', specs: undefined },
+      server: { description: '', specs: { name: '', rules: [] }, data: undefined },
+      // Optional fields
+      ...(config.eventStream != null && { stream: config.eventStream }),
+      ...(config.integration && { via: [config.integration.name] }),
+      ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
+    };
+
+    addSlice(slice);
+
+    // Execute the function which will populate client/server blocks
+    fn();
+  },
+
+  reaction(name: string, fn: () => void) {
+    const flow = getCurrentNarrative();
+    if (!flow) throw new Error('No active flow');
+
+    // Create a properly typed react slice (note: 'reaction' -> 'react' for schema compliance)
+    const slice: ReactSlice = {
+      type: 'react',
+      name,
+      server: { specs: { name: '', rules: [] }, data: undefined },
+      // Optional fields
+      ...(config.eventStream != null && { stream: config.eventStream }),
+      ...(config.integration && { via: [config.integration.name] }),
+      ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
+    };
+    addSlice(slice);
+    fn();
+  },
+});