@auto-engineer/narrative 1.139.0 → 1.140.1

package/src/schema.ts

@@ -15,16 +15,16 @@ export const ModuleSchema = z
     isDerived: z.boolean().describe('True if auto-derived from sourceFile grouping, false if user-authored'),
     contains: z
       .object({
-        narrativeIds: z.array(z.string()).describe('IDs of narratives in this module'),
+        sceneIds: z.array(z.string()).describe('IDs of scenes in this module'),
       })
-      .describe('Narratives contained in this module'),
+      .describe('Scenes contained in this module'),
     declares: z
       .object({
         messages: z.array(MessageRefSchema).describe('Message types owned by this module'),
       })
       .describe('Types declared/owned by this module'),
   })
-  .describe('Module for grouping narratives and owning types');
+  .describe('Module for grouping scenes and owning types');
 
 const IntegrationSchema = z
   .object({
@@ -233,7 +233,7 @@ const UISchema = z
     regions: z.record(z.array(RegionEntrySchema)),
     customizationNotes: z.string().optional(),
   })
-  .describe('UI composition for a slice');
+  .describe('UI composition for a moment');
 
 const ComponentDefinitionSchema = z
   .object({
@@ -254,17 +254,17 @@ export const DesignSchema = z
   })
   .describe('Design fields for visual representation');
 
-const BaseSliceSchema = z
+const BaseMomentSchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    id: z.string().optional().describe('Optional unique identifier for the moment'),
     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'),
+    stream: z.string().optional().describe('Event stream pattern for this moment'),
+    via: z.array(z.string()).optional().describe('Integration names used by this moment'),
     additionalInstructions: z.string().optional().describe('Additional instructions'),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
   })
-  .describe('Base properties shared by all slice types');
+  .describe('Base properties shared by all moment types');
 
 const StepErrorSchema = z.object({
   type: z.enum(['IllegalStateError', 'ValidationError', 'NotFoundError']).describe('Error type'),
@@ -339,7 +339,7 @@ export const ClientSpecNodeSchema: z.ZodType<ClientSpecNode> = z.lazy(() =>
 
 export const ClientSpecSchema = z.array(ClientSpecNodeSchema).default([]);
 
-const CommandSliceSchema = BaseSliceSchema.extend({
+const CommandMomentSchema = BaseMomentSchema.extend({
   type: z.literal('command'),
   client: z.object({
     specs: ClientSpecSchema,
@@ -348,12 +348,12 @@ const CommandSliceSchema = BaseSliceSchema.extend({
   mappings: z.array(MappingEntrySchema).optional().describe('Field mappings between Command/Event/State messages'),
   server: z.object({
     description: z.string(),
-    data: DataSchema.optional().describe('Data configuration for command slices'),
+    data: DataSchema.optional().describe('Data configuration for command moments'),
     specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
-}).describe('Command slice handling user actions and business logic');
+}).describe('Command moment handling user actions and business logic');
 
-const QuerySliceSchema = BaseSliceSchema.extend({
+const QueryMomentSchema = BaseMomentSchema.extend({
   type: z.literal('query'),
   client: z.object({
     specs: ClientSpecSchema,
@@ -362,32 +362,32 @@ const QuerySliceSchema = BaseSliceSchema.extend({
   mappings: z.array(MappingEntrySchema).optional().describe('Field mappings between Command/Event/State messages'),
   server: z.object({
     description: z.string(),
-    data: DataSchema.optional().describe('Data configuration for query slices'),
+    data: DataSchema.optional().describe('Data configuration for query moments'),
     specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
-}).describe('Query slice for reading data and maintaining projections');
+}).describe('Query moment for reading data and maintaining projections');
 
-const ReactSliceSchema = BaseSliceSchema.extend({
+const ReactMomentSchema = BaseMomentSchema.extend({
   type: z.literal('react'),
   server: z.object({
     description: z.string().optional(),
-    data: DataSchema.optional().describe('Data configuration for react slices'),
+    data: DataSchema.optional().describe('Data configuration for react moments'),
     specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
-}).describe('React slice for automated responses to events');
+}).describe('React moment for automated responses to events');
 
-const ExperienceSliceSchema = BaseSliceSchema.extend({
+const ExperienceMomentSchema = BaseMomentSchema.extend({
   type: z.literal('experience'),
   client: z.object({
     specs: ClientSpecSchema,
   }),
-}).describe('Experience slice for user interactions and UI behavior');
+}).describe('Experience moment for user interactions and UI behavior');
 
-const SliceSchema = z.discriminatedUnion('type', [
-  CommandSliceSchema,
-  QuerySliceSchema,
-  ReactSliceSchema,
-  ExperienceSliceSchema,
+const MomentSchema = z.discriminatedUnion('type', [
+  CommandMomentSchema,
+  QueryMomentSchema,
+  ReactMomentSchema,
+  ExperienceMomentSchema,
 ]);
 
 export const SceneRouteSchema = z
@@ -420,64 +420,64 @@ export const SceneClassificationSchema = z
       .optional(),
     route: SceneRouteSchema.optional(),
   })
-  .describe('Scene classification metadata for a narrative');
+  .describe('Scene classification metadata for a scene');
 
-export const JourneySchema = z
+export const NarrativeSchema = z
   .object({
-    id: z.string().optional().describe('Unique identifier for the journey'),
-    name: z.string().describe('Journey name'),
+    id: z.string().optional().describe('Unique identifier for the narrative'),
+    name: z.string().describe('Narrative name'),
     description: z.string().optional(),
     actors: z.array(z.string()).optional(),
-    narrativeIds: z.array(z.string()).describe('Ordered narrative IDs composing this journey'),
+    sceneIds: z.array(z.string()).describe('Ordered scene IDs composing this narrative'),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
   })
-  .describe('User journey grouping narratives into an ordered flow');
+  .describe('Narrative grouping scenes into an ordered flow');
 
-const NarrativeSchema = z
+const SceneSchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    id: z.string().optional().describe('Optional unique identifier for the scene'),
     description: z.string().optional(),
-    slices: z.array(SliceSchema),
+    moments: z.array(MomentSchema),
     sourceFile: z.string().optional(),
     scene: SceneClassificationSchema.optional(),
     design: DesignSchema.optional().describe('Design fields for visual representation'),
   })
-  .describe('Business narrative containing related slices');
+  .describe('Business scene containing related moments');
 
-// Variant 1: Just narrative names
-export const NarrativeNamesOnlySchema = z
+// Variant 1: Just scene names
+export const SceneNamesOnlySchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    id: z.string().optional().describe('Optional unique identifier for the scene'),
     description: z.string().optional(),
   })
-  .describe('Narrative with just name for initial planning');
+  .describe('Scene with just name for initial planning');
 
-// Variant 2: Narrative with slice names
-const SliceNamesOnlySchema = z
+// Variant 2: Scene with moment names
+const MomentNamesOnlySchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    id: z.string().optional().describe('Optional unique identifier for the moment'),
     description: z.string().optional(),
     type: z.enum(['command', 'query', 'react']),
   })
-  .describe('Slice with just name and type for structure planning');
+  .describe('Moment with just name and type for structure planning');
 
-const NarrativeWithSliceNamesSchema = z
+const SceneWithMomentNamesSchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    id: z.string().optional().describe('Optional unique identifier for the scene'),
     description: z.string().optional(),
-    slices: z.array(SliceNamesOnlySchema),
+    moments: z.array(MomentNamesOnlySchema),
   })
-  .describe('Narrative with slice names for structure planning');
+  .describe('Scene with moment names for structure planning');
 
-// Variant 3: Narrative with client & server names
-const ClientServerNamesSliceSchema = z
+// Variant 3: Scene with client & server names
+const ClientServerNamesMomentSchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the slice'),
+    id: z.string().optional().describe('Optional unique identifier for the moment'),
     type: z.enum(['command', 'query', 'react']),
     description: z.string().optional(),
     client: z
@@ -491,54 +491,54 @@ const ClientServerNamesSliceSchema = z
       })
       .optional(),
   })
-  .describe('Slice with client/server descriptions for behavior planning');
+  .describe('Moment with client/server descriptions for behavior planning');
 
-const NarrativeWithClientServerNamesSchema = z
+const SceneWithClientServerNamesSchema = z
   .object({
     name: z.string(),
-    id: z.string().optional().describe('Optional unique identifier for the narrative'),
+    id: z.string().optional().describe('Optional unique identifier for the scene'),
     description: z.string().optional(),
-    slices: z.array(ClientServerNamesSliceSchema),
+    moments: z.array(ClientServerNamesMomentSchema),
   })
-  .describe('Narrative with client/server descriptions for behavior planning');
+  .describe('Scene with client/server descriptions for behavior planning');
 
 // Variant 4: Full specs (uses existing schemas)
 
-const JourneyPlanningJourneySchema = z
+const NarrativePlanningNarrativeSchema = z
   .object({
     name: z.string(),
     description: z.string().optional(),
     actors: z.array(z.string()).optional(),
-    narrativeNames: z.array(z.string()).describe('Ordered narrative names'),
+    sceneNames: z.array(z.string()).describe('Ordered scene names'),
   })
-  .describe('Journey with narrative names for planning');
+  .describe('Narrative with scene names for planning');
 
-export const JourneyPlanningSchema = z
+export const NarrativePlanningSchema = z
   .object({
-    variant: z.literal('journey-planning').describe('Journey-based planning with narrative names'),
-    journeys: z.array(JourneyPlanningJourneySchema),
-    narratives: z.array(NarrativeNamesOnlySchema),
+    variant: z.literal('narrative-planning').describe('Narrative-based planning with scene names'),
+    narratives: z.array(NarrativePlanningNarrativeSchema),
+    scenes: z.array(SceneNamesOnlySchema),
   })
-  .describe('Progressive disclosure variant for journey-based planning');
+  .describe('Progressive disclosure variant for narrative-based planning');
 
-export const NarrativeNamesSchema = z
+export const SceneNamesSchema = z
   .object({
-    variant: z.literal('narrative-names').describe('Just narrative names for initial ideation'),
-    narratives: z.array(NarrativeNamesOnlySchema),
+    variant: z.literal('scene-names').describe('Just scene names for initial ideation'),
+    scenes: z.array(SceneNamesOnlySchema),
   })
-  .describe('System with just flow names for initial planning');
+  .describe('System with just scene names for initial planning');
 
-export const SliceNamesSchema = z
+export const MomentNamesSchema = z
   .object({
-    variant: z.literal('slice-names').describe('Narratives with slice names for structure planning'),
-    narratives: z.array(NarrativeWithSliceNamesSchema),
+    variant: z.literal('moment-names').describe('Scenes with moment names for structure planning'),
+    scenes: z.array(SceneWithMomentNamesSchema),
   })
-  .describe('System with narrative and slice names for structure planning');
+  .describe('System with scene and moment 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),
+    variant: z.literal('client-server-names').describe('Scenes with client/server descriptions'),
+    scenes: z.array(SceneWithClientServerNamesSchema),
   })
   .describe('System with client/server descriptions for behavior planning');
 
@@ -549,11 +549,11 @@ const ModelDesignSchema = DesignSchema.extend({
 export const modelSchema = z
   .object({
     variant: z.literal('specs').describe('Full specification with all details'),
-    narratives: z.array(NarrativeSchema),
+    scenes: z.array(SceneSchema),
     messages: z.array(MessageSchema),
     integrations: z.array(IntegrationSchema).optional(),
     modules: z.array(ModuleSchema).describe('Modules for type ownership and file grouping'),
-    journeys: z.array(JourneySchema).optional(),
+    narratives: z.array(NarrativeSchema),
     design: ModelDesignSchema.optional().describe('Design fields for visual representation'),
   })
   .describe('Complete system specification with all implementation details');
@@ -568,12 +568,12 @@ export {
   StateSchema,
   QuerySchema,
   IntegrationSchema,
-  CommandSliceSchema,
-  QuerySliceSchema,
-  ReactSliceSchema,
-  ExperienceSliceSchema,
-  SliceSchema,
-  NarrativeSchema,
+  CommandMomentSchema,
+  QueryMomentSchema,
+  ReactMomentSchema,
+  ExperienceMomentSchema,
+  MomentSchema,
+  SceneSchema,
   ExampleSchema,
   RuleSchema,
   SpecSchema,
@@ -590,12 +590,12 @@ export {
 };
 
 export type Model = z.infer<typeof modelSchema>;
-export type Narrative = z.infer<typeof NarrativeSchema>;
-export type Slice = z.infer<typeof SliceSchema>;
-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 Scene = z.infer<typeof SceneSchema>;
+export type Moment = z.infer<typeof MomentSchema>;
+export type QueryMoment = z.infer<typeof QueryMomentSchema>;
+export type ReactMoment = z.infer<typeof ReactMomentSchema>;
+export type CommandMoment = z.infer<typeof CommandMomentSchema>;
+export type ExperienceMoment = z.infer<typeof ExperienceMomentSchema>;
 export type Message = z.infer<typeof MessageSchema>;
 export type Example = z.infer<typeof ExampleSchema>;
 export type MessageField = z.infer<typeof MessageFieldSchema>;
@@ -606,11 +606,11 @@ export type Module = z.infer<typeof ModuleSchema>;
 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 Narrative = z.infer<typeof NarrativeSchema>;
 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>;
+export type NarrativePlanning = z.infer<typeof NarrativePlanningSchema>;
 export type ImageAsset = z.infer<typeof ImageAssetSchema>;
 export type Design = z.infer<typeof DesignSchema>;
 export type RegionEntry = z.infer<typeof RegionEntrySchema>;

package/src/slice-builder.ts

@@ -1,19 +1,19 @@
-import type { CommandSlice, QuerySlice, ReactSlice } from './index';
-import { addSlice, getCurrentNarrative } from './narrative-context';
+import type { CommandMoment, QueryMoment, ReactMoment } from './index';
+import { addMoment, getCurrentScene } from './narrative-context';
 import type { Integration } from './types';
 
-export interface SliceConfig {
+export interface MomentConfig {
   integration?: Integration;
   eventStream?: string;
   retries?: number;
 }
 
-export interface SliceBuilder {
-  via(integrationOrStream: Integration | string): SliceBuilder;
+export interface MomentBuilder {
+  via(integrationOrStream: Integration | string): MomentBuilder;
 
-  retries(count: number): SliceBuilder;
+  retries(count: number): MomentBuilder;
 
-  stream(eventStream: string): SliceBuilder;
+  stream(eventStream: string): MomentBuilder;
 
   command(name: string, fn: () => void): void;
 
@@ -22,29 +22,29 @@ export interface SliceBuilder {
   reaction(name: string, fn: () => void): void;
 }
 
-export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
-  via(integrationOrStream: Integration | string): SliceBuilder {
+export const createMomentBuilder = (config: MomentConfig = {}): MomentBuilder => ({
+  via(integrationOrStream: Integration | string): MomentBuilder {
     if (typeof integrationOrStream === 'string') {
-      return createSliceBuilder({ ...config, eventStream: integrationOrStream });
+      return createMomentBuilder({ ...config, eventStream: integrationOrStream });
     } else {
-      return createSliceBuilder({ ...config, integration: integrationOrStream });
+      return createMomentBuilder({ ...config, integration: integrationOrStream });
     }
   },
 
-  retries(count: number): SliceBuilder {
-    return createSliceBuilder({ ...config, retries: count });
+  retries(count: number): MomentBuilder {
+    return createMomentBuilder({ ...config, retries: count });
   },
 
-  stream(eventStream: string): SliceBuilder {
-    return createSliceBuilder({ ...config, eventStream });
+  stream(eventStream: string): MomentBuilder {
+    return createMomentBuilder({ ...config, eventStream });
   },
 
   command(name: string, fn: () => void) {
-    const flow = getCurrentNarrative();
-    if (!flow) throw new Error('No active flow');
+    const currentScene = getCurrentScene();
+    if (!currentScene) throw new Error('No active scene');
 
-    // Create a properly typed command slice
-    const slice: CommandSlice = {
+    // Create a properly typed command moment
+    const slice: CommandMoment = {
       type: 'command',
       name,
       client: { specs: [] },
@@ -54,16 +54,16 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
       ...(config.integration && { via: [config.integration.name] }),
       ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
     };
-    addSlice(slice);
+    addMoment(slice);
     fn();
   },
 
   query(name: string, fn: () => void) {
-    const flow = getCurrentNarrative();
-    if (!flow) throw new Error('No active flow');
+    const currentScene = getCurrentScene();
+    if (!currentScene) throw new Error('No active scene');
 
-    // Create a properly typed query slice
-    const slice: QuerySlice = {
+    // Create a properly typed query moment
+    const slice: QueryMoment = {
       type: 'query',
       name,
       client: { specs: [] },
@@ -74,18 +74,18 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
       ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
     };
 
-    addSlice(slice);
+    addMoment(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');
+    const currentScene = getCurrentScene();
+    if (!currentScene) throw new Error('No active scene');
 
-    // Create a properly typed react slice (note: 'reaction' -> 'react' for schema compliance)
-    const slice: ReactSlice = {
+    // Create a properly typed react moment (note: 'reaction' -> 'react' for schema compliance)
+    const slice: ReactMoment = {
       type: 'react',
       name,
       server: { specs: [], data: undefined },
@@ -94,7 +94,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
       ...(config.integration && { via: [config.integration.name] }),
       ...(config.retries != null && { additionalInstructions: `retries: ${config.retries}` }),
     };
-    addSlice(slice);
+    addMoment(slice);
     fn();
   },
 });

package/src/transformers/model-to-narrative/analysis/lint-helpers.ts

@@ -43,7 +43,7 @@ export function findCodeBoundaries(lines: string[]): { lastImportIdx: number } {
   for (let i = 0; i < lines.length; i++) {
     if (lines[i].match(/^\s*import\s/)) {
       lastImportIdx = i;
-    } else if (lines[i].includes('flow(')) {
+    } else if (lines[i].includes('scene(')) {
       break;
     }
   }