@auto-engineer/narrative 1.104.0 → 1.105.0

package/ketchup-plan.md

@@ -1,4 +1,4 @@
-# Ketchup Plan: Validate Slice Requests Against Model Messages
+# Ketchup Plan: DataTarget Schema — Target-Only Event Items
 
 ## TODO
 
@@ -6,8 +6,7 @@
 
 ## DONE
 
-- [x] Burst 1: Skeleton + parse safety + export convertJsonAstToSdl (4b1d0b12)
-- [x] Burst 2: Mutation validation (wrong op type, missing input, type mismatch, message not found) (4059d393)
-- [x] Burst 3: Query — operation type + state + top-level fields (73c8c99c)
-- [x] Burst 4: Query — nested field validation (inline objects, referenced messages, unresolvable) (39d3d083)
-- [x] Burst 5: Export from index.ts + integration test (885a805f)
+- [x] Burst 1: Add DataTargetSchema to schema.ts, DataTarget type, DataTargetItem, exports (81188d6b)
+- [x] Burst 2: Add target() builder factory in data-narrative-builders.ts (757b8475)
+- [x] Burst 3: Update stripTypeDiscriminator — completed in burst 1 (type change propagated)
+- [x] Burst 4: Update flow code generator to handle target-only items (057c6e56)

package/package.json

@@ -26,9 +26,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "1.104.0",
-    "@auto-engineer/id": "1.104.0",
-    "@auto-engineer/message-bus": "1.104.0"
+    "@auto-engineer/file-store": "1.105.0",
+    "@auto-engineer/id": "1.105.0",
+    "@auto-engineer/message-bus": "1.105.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.104.0",
+  "version": "1.105.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/data-narrative-builders.specs.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { target } from './data-narrative-builders';
+
+describe('target() builder', () => {
+  it('builds a target-only event item without id', () => {
+    const result = target().event('TodoAdded');
+
+    expect(result).toEqual({
+      target: { type: 'Event', name: 'TodoAdded' },
+      __type: 'target',
+    });
+  });
+
+  it('builds a target-only event item with id', () => {
+    const result = target('dt-1').event('OrderPlaced');
+
+    expect(result).toEqual({
+      id: 'dt-1',
+      target: { type: 'Event', name: 'OrderPlaced' },
+      __type: 'target',
+    });
+  });
+
+  it('omits id when empty string', () => {
+    const result = target('').event('TodoAdded');
+
+    expect(result).toEqual({
+      target: { type: 'Event', name: 'TodoAdded' },
+      __type: 'target',
+    });
+  });
+});

package/src/data-narrative-builders.ts

@@ -1,7 +1,12 @@
 import { integrationExportRegistry } from './integration-export-registry';
+import type { DataTarget } from './schema';
 import type { DataSinkItem, DataSourceItem, DefaultRecord, Integration, MessageTarget } from './types';
 import { createIntegrationOrigin } from './types';
 
+export interface DataTargetItem extends DataTarget {
+  readonly __type: 'target';
+}
+
 // Extended interfaces that add chainable methods
 export interface ChainableSinkMethods {
   additionalInstructions(instructions: string): ChainableSink;
@@ -439,9 +444,26 @@ export class DataSourceBuilder {
   }
 }
 
+export class DataTargetBuilder {
+  private readonly builderId?: string;
+
+  constructor(id?: string) {
+    this.builderId = id;
+  }
+
+  event(name: string): DataTargetItem {
+    return {
+      ...(this.builderId != null && this.builderId !== '' && { id: this.builderId }),
+      target: { type: 'Event' as const, name },
+      __type: 'target' as const,
+    };
+  }
+}
+
 // Factory functions for cleaner API
 export const sink = (id?: string) => new DataSinkBuilder(id);
 export const source = (id?: string) => new DataSourceBuilder(id);
+export const target = (id?: string) => new DataTargetBuilder(id);
 
 // Type-safe sink function that accepts builder results
 export function typedSink(

package/src/index.ts

@@ -24,9 +24,9 @@ export const get = (strings: TemplateStringsArray, ...values: unknown[]) => {
   }, '');
 };
 
-export type { FieldSelector } from './data-narrative-builders';
+export type { DataTargetItem, FieldSelector } from './data-narrative-builders';
 
-export { sink, source } from './data-narrative-builders';
+export { sink, source, target } from './data-narrative-builders';
 export type {
   FluentCommandSliceBuilder,
   FluentExperienceSliceBuilder,

package/src/model-to-narrative.specs.ts

@@ -3157,6 +3157,84 @@ narrative('All Projection Types', 'ALL-PROJ', () => {
       expect(code).not.toContain("sink('')");
     });
 
+    it('should generate target-only event items without destination', async () => {
+      const modelWithTarget: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'React Flow',
+            id: 'REACT-FLOW',
+            slices: [
+              {
+                name: 'reacts to event',
+                id: 'REACT-SLICE',
+                type: 'react',
+                server: {
+                  description: 'React handler',
+                  data: {
+                    items: [{ target: { type: 'Event', name: 'TodoAdded' } }],
+                  },
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'event',
+            source: 'internal',
+            name: 'TodoAdded',
+            fields: [{ name: 'todoId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithTarget));
+      expect(code).toContain("target().event('TodoAdded')");
+    });
+
+    it('should generate target-only event items with id', async () => {
+      const modelWithTargetId: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'React Flow',
+            id: 'REACT-FLOW',
+            slices: [
+              {
+                name: 'reacts to event',
+                id: 'REACT-SLICE',
+                type: 'react',
+                server: {
+                  description: 'React handler',
+                  data: {
+                    items: [{ id: 'TGT-1', target: { type: 'Event', name: 'TodoAdded' } }],
+                  },
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'event',
+            source: 'internal',
+            name: 'TodoAdded',
+            fields: [{ name: 'todoId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithTargetId));
+      expect(code).toContain("target('TGT-1').event('TodoAdded')");
+    });
+
     it('should generate _additionalInstructions on source items', async () => {
       const modelWithSourceInstructions: Model = {
         variant: 'specs',

package/src/narrative-context.ts

@@ -2,8 +2,8 @@ import createDebug from 'debug';
 import type { z } from 'zod';
 import type { CommandSlice, ExperienceSlice, Narrative, QuerySlice, Slice } from './index';
 import type { GivenTypeInfo } from './loader/ts-utils';
-import type { ClientSpecNode, ExampleSchema, RuleSchema, SpecSchema, StepSchema } from './schema';
-import type { Data, DataItem, DataSink, DataSource } from './types';
+import type { ClientSpecNode, DataTarget, ExampleSchema, RuleSchema, SpecSchema, StepSchema } from './schema';
+import type { Data, DataSink, DataSource } from './types';
 
 type Step = z.infer<typeof StepSchema>;
 type Example = z.infer<typeof ExampleSchema>;
@@ -301,14 +301,14 @@ export function setSliceData(data: Data): void {
   };
 }
 
-function stripTypeDiscriminator(items: (DataSink | DataSource | DataItem)[]): (DataSink | DataSource)[] {
+function stripTypeDiscriminator(items: (DataSink | DataSource | DataTarget)[]): (DataSink | DataSource | DataTarget)[] {
   return items.map((item) => {
     if ('__type' in item) {
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
       const { __type, ...rest } = item;
-      return rest as DataSink | DataSource;
+      return rest;
     }
-    return item as DataSink | DataSource;
+    return item;
   });
 }
 

package/src/narrative.ts

@@ -1,4 +1,5 @@
 import createDebug from 'debug';
+import type { DataTargetItem } from './data-narrative-builders';
 import {
   clearCurrentNarrative,
   endClientBlock,
@@ -214,7 +215,7 @@ export interface SliceTypeValueInterface {
   readonly value: 'command' | 'query' | 'react';
 }
 
-export function data(config: Data | DataItem[]): void {
+export function data(config: Data | (DataItem | DataTargetItem)[]): void {
   const slice = getCurrentSlice();
   if (!slice) throw new Error('No active slice for data configuration');
 

package/src/schema.specs.ts

@@ -2,6 +2,8 @@ import { describe, expect, it } from 'vitest';
 import type { Journey, JourneyPlanning, SceneClassification, SceneRoute } from './schema';
 import {
   CommandSliceSchema,
+  DataSchema,
+  DataTargetSchema,
   JourneyPlanningSchema,
   JourneySchema,
   modelSchema,
@@ -411,6 +413,92 @@ describe('exported types', () => {
   });
 });
 
+describe('DataTargetSchema', () => {
+  it('should accept a target-only event item', () => {
+    const result = DataTargetSchema.safeParse({
+      target: { type: 'Event', name: 'TodoAdded' },
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        target: { type: 'Event', name: 'TodoAdded' },
+      });
+    }
+  });
+
+  it('should accept optional id, transform, and _additionalInstructions', () => {
+    const result = DataTargetSchema.safeParse({
+      id: 'dt-1',
+      target: { type: 'Event', name: 'OrderPlaced' },
+      transform: 'mapOrder',
+      _additionalInstructions: 'extra info',
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({
+        id: 'dt-1',
+        target: { type: 'Event', name: 'OrderPlaced' },
+        transform: 'mapOrder',
+        _additionalInstructions: 'extra info',
+      });
+    }
+  });
+
+  it('should reject Command target type', () => {
+    const result = DataTargetSchema.safeParse({
+      target: { type: 'Command', name: 'CreateTodo' },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject State target type', () => {
+    const result = DataTargetSchema.safeParse({
+      target: { type: 'State', name: 'TodoState' },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('DataSchema with target-only items', () => {
+  it('should accept target-only items in the items array', () => {
+    const result = DataSchema.safeParse({
+      items: [{ target: { type: 'Event', name: 'TodoAdded' } }],
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.items).toEqual([{ target: { type: 'Event', name: 'TodoAdded' } }]);
+    }
+  });
+
+  it('should accept mixed sink and target items', () => {
+    const result = DataSchema.safeParse({
+      items: [
+        {
+          target: { type: 'Event', name: 'TodoAdded' },
+          destination: { type: 'stream', pattern: 'todo-${id}' },
+        },
+        { target: { type: 'Event', name: 'TodoRemoved' } },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.items).toEqual([
+        {
+          target: { type: 'Event', name: 'TodoAdded' },
+          destination: { type: 'stream', pattern: 'todo-${id}' },
+        },
+        { target: { type: 'Event', name: 'TodoRemoved' } },
+      ]);
+    }
+  });
+});
+
 describe('QuerySliceSchema', () => {
   it('should accept optional mappings field with structured entries', () => {
     const slice = {

package/src/schema.ts

@@ -133,12 +133,27 @@ const DataSourceSchema = z
   })
   .describe('Data source configuration for inbound data flow');
 
+const EventTargetSchema = MessageTargetSchema.extend({
+  type: z.enum(['Event']),
+}).describe('Event-only message target');
+
+const DataTargetSchema = z
+  .object({
+    id: z.string().optional().describe('Optional unique identifier for the data target'),
+    target: EventTargetSchema,
+    transform: z.string().optional().describe('Optional transformation function name'),
+    _additionalInstructions: z.string().optional().describe('Additional instructions'),
+  })
+  .describe('Target-only data item for event declaration without routing');
+
 export const DataSchema = z
   .object({
     id: z.string().optional().describe('Optional unique identifier for the data configuration'),
-    items: z.array(z.union([DataSinkSchema, DataSourceSchema])).describe('Array of data sinks and sources'),
+    items: z
+      .array(z.union([DataSinkSchema, DataSourceSchema, DataTargetSchema]))
+      .describe('Array of data sinks, sources, and targets'),
   })
-  .describe('Data configuration containing sinks and sources');
+  .describe('Data configuration containing sinks, sources, and targets');
 
 const MessageFieldSchema = z
   .object({
@@ -512,6 +527,7 @@ export {
   SpecSchema,
   DataSinkSchema,
   DataSourceSchema,
+  DataTargetSchema,
   StepSchema,
   StepErrorSchema,
   StepWithDocStringSchema,
@@ -536,6 +552,7 @@ export type MessageRef = z.infer<typeof MessageRefSchema>;
 export type MappingFieldRef = z.infer<typeof MappingFieldRefSchema>;
 export type MappingEntry = z.infer<typeof MappingEntrySchema>;
 export type Journey = z.infer<typeof JourneySchema>;
+export type DataTarget = z.infer<typeof DataTargetSchema>;
 export type SceneClassification = z.infer<typeof SceneClassificationSchema>;
 export type SceneRoute = z.infer<typeof SceneRouteSchema>;
 export type JourneyPlanning = z.infer<typeof JourneyPlanningSchema>;

package/src/transformers/model-to-narrative/generators/flow.ts

@@ -11,6 +11,7 @@ import type {
   ClientSpecNode,
   DataSinkSchema,
   DataSourceSchema,
+  DataTargetSchema,
   DestinationSchema,
   ExampleSchema,
   OriginSchema,
@@ -25,6 +26,7 @@ type ExperienceSlice = ExperienceSliceType;
 type Example = z.infer<typeof ExampleSchema>;
 type DataSinkItem = z.infer<typeof DataSinkSchema>;
 type DataSourceItem = z.infer<typeof DataSourceSchema>;
+type DataTargetItem = z.infer<typeof DataTargetSchema>;
 type Destination = z.infer<typeof DestinationSchema>;
 type Origin = z.infer<typeof OriginSchema>;
 type Slice = CommandSlice | QuerySlice | ReactSlice | ExperienceSlice;
@@ -305,8 +307,20 @@ function getOriginMethodName(origin: Origin): string {
 function buildSingleDataItem(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
-  it: DataSinkItem | DataSourceItem,
+  it: DataSinkItem | DataSourceItem | DataTargetItem,
 ): tsNS.Expression {
+  if (!('destination' in it) && !('origin' in it)) {
+    const args: tsNS.Expression[] = it.id != null && it.id !== '' ? [f.createStringLiteral(it.id)] : [];
+    return f.createCallExpression(
+      f.createPropertyAccessExpression(
+        f.createCallExpression(f.createIdentifier('target'), undefined, args),
+        f.createIdentifier('event'),
+      ),
+      undefined,
+      [f.createStringLiteral(it.target.name)],
+    );
+  }
+
   let chain = buildInitialChain(ts, f, it.target, it.id);
 
   if ('destination' in it) {
@@ -364,7 +378,7 @@ function buildSingleDataItem(
 function buildDataItems(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
-  data: { id?: string; items: Array<DataSinkItem | DataSourceItem> },
+  data: { id?: string; items: Array<DataSinkItem | DataSourceItem | DataTargetItem> },
 ) {
   const calls = data.items.map((it) => buildSingleDataItem(ts, f, it));
 
@@ -674,7 +688,13 @@ function buildServerStatements(
   const statements: tsNS.Statement[] = [];
 
   if (server.data?.items && server.data.items.length > 0) {
-    statements.push(buildDataItems(ts, f, server.data as { id?: string; items: Array<DataSinkItem | DataSourceItem> }));
+    statements.push(
+      buildDataItems(
+        ts,
+        f,
+        server.data as { id?: string; items: Array<DataSinkItem | DataSourceItem | DataTargetItem> },
+      ),
+    );
   }
 
   if (server.specs !== null && server.specs !== undefined) {

package/src/transformers/model-to-narrative/generators/imports.ts

@@ -15,6 +15,7 @@ export const ALL_FLOW_FUNCTION_NAMES = [
   'sink',
   'source',
   'specs',
+  'target',
 ] as const;
 
 export function buildImports(