@auto-engineer/narrative 1.139.0 → 1.140.0

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.139.0",
-    "@auto-engineer/message-bus": "1.139.0",
-    "@auto-engineer/id": "1.139.0"
+    "@auto-engineer/file-store": "1.140.0",
+    "@auto-engineer/message-bus": "1.140.0",
+    "@auto-engineer/id": "1.140.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.139.0",
+  "version": "1.140.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/scripts/convert-flow-exec.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { NodeFileStore } from '@auto-engineer/file-store/node';
-import { getNarratives } from '../src';
+import { getScenes } from '../src';
 
 const main = async () => {
   try {
-    const result = await getNarratives({ vfs: new NodeFileStore(), root: path.resolve(__dirname) });
+    const result = await getScenes({ vfs: new NodeFileStore(), root: path.resolve(__dirname) });
     const schema = result.toModel();
     console.log(JSON.stringify(schema, null, 2));
   } catch (error) {

package/scripts/print-schema.ts

@@ -1,21 +1,21 @@
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
-  CommandSliceSchema,
+  CommandMomentSchema,
   IntegrationSchema,
   MessageSchema,
-  NarrativeSchema,
-  QuerySliceSchema,
-  ReactSliceSchema,
+  QueryMomentSchema,
+  ReactMomentSchema,
+  SceneSchema,
 } from '../src';
 
 const schemas = Object.fromEntries(
   Object.entries({
-    narrative: NarrativeSchema,
+    scene: SceneSchema,
     message: MessageSchema,
     integration: IntegrationSchema,
-    commandSlice: CommandSliceSchema,
-    querySlice: QuerySliceSchema,
-    reactSlice: ReactSliceSchema,
+    commandMoment: CommandMomentSchema,
+    queryMoment: QueryMomentSchema,
+    reactMoment: ReactMomentSchema,
   }).map(([k, v]) => [
     k,
     zodToJsonSchema(v, {

package/src/fluent-builder.specs.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { command, react } from './fluent-builder';
-import { clearCurrentNarrative, startNarrative } from './narrative-context';
+import { clearCurrentScene, startScene } from './narrative-context';
 import { createIntegration } from './types';
 
 // Test integrations
@@ -9,11 +9,11 @@ const Twilio = createIntegration('twilio', 'Twilio');
 
 describe('via method', () => {
   beforeEach(() => {
-    startNarrative('test-flow');
+    startScene('test-flow');
   });
 
   afterEach(() => {
-    clearCurrentNarrative();
+    clearCurrentScene();
   });
 
   it('should accept a single integration', () => {

package/src/fluent-builder.ts

@@ -1,11 +1,11 @@
 import createDebug from 'debug';
 import { type ASTNode, print } from 'graphql';
-import type { CommandSlice, ExperienceSlice, QuerySlice, ReactSlice } from './index';
+import type { CommandMoment, ExperienceMoment, QueryMoment, ReactMoment } from './index';
 import {
-  addSlice,
+  addMoment,
   endClientBlock,
   endServerBlock,
-  getCurrentSlice,
+  getCurrentMoment,
   startClientBlock,
   startServerBlock,
 } from './narrative-context';
@@ -32,125 +32,125 @@ if ('color' in debugExperience && typeof debugExperience === 'object') {
   (debugExperience as { color: string }).color = '5';
 } // magenta
 
-export interface FluentCommandSliceBuilder {
-  stream(name: string): FluentCommandSliceBuilder;
-  client(fn: () => void): FluentCommandSliceBuilder;
-  client(description: string, fn: () => void): FluentCommandSliceBuilder;
-  server(fn: () => void): FluentCommandSliceBuilder;
-  server(description: string, fn: () => void): FluentCommandSliceBuilder;
-  via(integration: Integration | Integration[]): FluentCommandSliceBuilder;
-  retries(count: number): FluentCommandSliceBuilder;
-  request(mutation: unknown): FluentCommandSliceBuilder;
+export interface FluentCommandMomentBuilder {
+  stream(name: string): FluentCommandMomentBuilder;
+  client(fn: () => void): FluentCommandMomentBuilder;
+  client(description: string, fn: () => void): FluentCommandMomentBuilder;
+  server(fn: () => void): FluentCommandMomentBuilder;
+  server(description: string, fn: () => void): FluentCommandMomentBuilder;
+  via(integration: Integration | Integration[]): FluentCommandMomentBuilder;
+  retries(count: number): FluentCommandMomentBuilder;
+  request(mutation: unknown): FluentCommandMomentBuilder;
 }
 
-export interface FluentQuerySliceBuilder {
-  client(fn: () => void): FluentQuerySliceBuilder;
-  client(description: string, fn: () => void): FluentQuerySliceBuilder;
-  server(fn: () => void): FluentQuerySliceBuilder;
-  server(description: string, fn: () => void): FluentQuerySliceBuilder;
-  request(query: unknown): FluentQuerySliceBuilder;
+export interface FluentQueryMomentBuilder {
+  client(fn: () => void): FluentQueryMomentBuilder;
+  client(description: string, fn: () => void): FluentQueryMomentBuilder;
+  server(fn: () => void): FluentQueryMomentBuilder;
+  server(description: string, fn: () => void): FluentQueryMomentBuilder;
+  request(query: unknown): FluentQueryMomentBuilder;
 }
 
-export interface FluentReactionSliceBuilder {
-  server(fn: () => void): FluentReactionSliceBuilder;
-  server(description: string, fn: () => void): FluentReactionSliceBuilder;
-  via(integration: Integration | Integration[]): FluentReactionSliceBuilder;
-  retries(count: number): FluentReactionSliceBuilder;
+export interface FluentReactionMomentBuilder {
+  server(fn: () => void): FluentReactionMomentBuilder;
+  server(description: string, fn: () => void): FluentReactionMomentBuilder;
+  via(integration: Integration | Integration[]): FluentReactionMomentBuilder;
+  retries(count: number): FluentReactionMomentBuilder;
 }
 
-export interface FluentExperienceSliceBuilder {
-  client(fn: () => void): FluentExperienceSliceBuilder;
-  client(description: string, fn: () => void): FluentExperienceSliceBuilder;
+export interface FluentExperienceMomentBuilder {
+  client(fn: () => void): FluentExperienceMomentBuilder;
+  client(description: string, fn: () => void): FluentExperienceMomentBuilder;
 }
 
-class CommandSliceBuilderImpl implements FluentCommandSliceBuilder {
-  private slice: CommandSlice;
+class CommandMomentBuilderImpl implements FluentCommandMomentBuilder {
+  private moment: CommandMoment;
 
   constructor(name: string, id?: string) {
-    debugCommand('Creating command slice: %s', name);
-    this.slice = {
+    debugCommand('Creating command moment: %s', name);
+    this.moment = {
       type: 'command',
       name,
       id,
       client: { specs: [] },
       server: { description: '', specs: [], data: undefined },
     };
-    addSlice(this.slice);
-    debugCommand('Command slice added to flow: %s', name);
+    addMoment(this.moment);
+    debugCommand('Command moment added to scene: %s', name);
   }
 
-  stream(name: string): FluentCommandSliceBuilder {
-    debugCommand('Setting stream for slice %s: %s', this.slice.name, name);
-    this.slice.stream = name;
+  stream(name: string): FluentCommandMomentBuilder {
+    debugCommand('Setting stream for moment %s: %s', this.moment.name, name);
+    this.moment.stream = name;
     return this;
   }
 
-  client(fn: () => void): FluentCommandSliceBuilder;
-  client(description: string, fn: () => void): FluentCommandSliceBuilder;
-  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentCommandSliceBuilder {
+  client(fn: () => void): FluentCommandMomentBuilder;
+  client(description: string, fn: () => void): FluentCommandMomentBuilder;
+  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentCommandMomentBuilder {
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugCommand('Adding client block to slice %s', this.slice.name);
+    debugCommand('Adding client block to moment %s', this.moment.name);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugCommand('Starting client block execution');
-        startClientBlock(slice);
+        startClientBlock(moment);
         callback();
         endClientBlock();
         debugCommand('Client block execution completed');
       } else {
-        debugCommand('WARNING: No current slice found for client block');
+        debugCommand('WARNING: No current moment found for client block');
       }
     }
 
     return this;
   }
 
-  server(fn: () => void): FluentCommandSliceBuilder;
-  server(description: string, fn: () => void): FluentCommandSliceBuilder;
-  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentCommandSliceBuilder {
+  server(fn: () => void): FluentCommandMomentBuilder;
+  server(description: string, fn: () => void): FluentCommandMomentBuilder;
+  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentCommandMomentBuilder {
     const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugCommand('Adding server block to slice %s, description: "%s"', this.slice.name, description);
+    debugCommand('Adding server block to moment %s, description: "%s"', this.moment.name, description);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugCommand('Starting server block execution');
-        startServerBlock(slice, description);
+        startServerBlock(moment, description);
         callback();
         endServerBlock();
         debugCommand('Server block execution completed');
       } else {
-        debugCommand('WARNING: No current slice found for server block');
+        debugCommand('WARNING: No current moment found for server block');
       }
     }
 
     return this;
   }
 
-  via(integration: Integration | Integration[]): FluentCommandSliceBuilder {
+  via(integration: Integration | Integration[]): FluentCommandMomentBuilder {
     const integrations = Array.isArray(integration) ? integration : [integration];
-    this.slice.via = integrations.map((i) => i.name);
-    debugCommand('Set integrations for slice %s: %o', this.slice.name, this.slice.via);
+    this.moment.via = integrations.map((i) => i.name);
+    debugCommand('Set integrations for moment %s: %o', this.moment.name, this.moment.via);
     return this;
   }
 
-  retries(count: number): FluentCommandSliceBuilder {
-    debugCommand('Setting retries for slice %s: %d', this.slice.name, count);
+  retries(count: number): FluentCommandMomentBuilder {
+    debugCommand('Setting retries for moment %s: %d', this.moment.name, count);
     // Store retries in additionalInstructions or metadata
-    this.slice.additionalInstructions = `retries: ${count}`;
+    this.moment.additionalInstructions = `retries: ${count}`;
     return this;
   }
 
-  request(query: unknown): FluentCommandSliceBuilder {
-    debugCommand('Setting request for slice %s', this.slice.name);
+  request(query: unknown): FluentCommandMomentBuilder {
+    debugCommand('Setting request for moment %s', this.moment.name);
     if (typeof query === 'string') {
       debugCommand('Request is string, length: %d', query.length);
-      this.slice.request = query;
+      this.moment.request = query;
     } else if (
       query !== null &&
       query !== undefined &&
@@ -159,8 +159,8 @@ class CommandSliceBuilderImpl implements FluentCommandSliceBuilder {
       query.kind === 'Document'
     ) {
       debugCommand('Request is GraphQL AST Document, converting to SDL');
-      this.slice.request = print(query as ASTNode); // ✅ convert AST to SDL string
-      debugCommand('Converted SDL length: %d', this.slice.request.length);
+      this.moment.request = print(query as ASTNode); // ✅ convert AST to SDL string
+      debugCommand('Converted SDL length: %d', this.moment.request.length);
     } else {
       debugCommand('ERROR: Invalid GraphQL query format');
       throw new Error('Invalid GraphQL query format');
@@ -169,74 +169,74 @@ class CommandSliceBuilderImpl implements FluentCommandSliceBuilder {
   }
 }
 
-class QuerySliceBuilderImpl implements FluentQuerySliceBuilder {
-  private slice: QuerySlice;
+class QueryMomentBuilderImpl implements FluentQueryMomentBuilder {
+  private moment: QueryMoment;
 
   constructor(name: string, id?: string) {
-    debugQuery('Creating query slice: %s', name);
-    this.slice = {
+    debugQuery('Creating query moment: %s', name);
+    this.moment = {
       type: 'query',
       name,
       id,
       client: { specs: [] },
       server: { description: '', specs: [], data: undefined },
     };
-    addSlice(this.slice);
-    debugQuery('Query slice added to flow: %s', name);
+    addMoment(this.moment);
+    debugQuery('Query moment added to scene: %s', name);
   }
 
-  client(fn: () => void): FluentQuerySliceBuilder;
-  client(description: string, fn: () => void): FluentQuerySliceBuilder;
-  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentQuerySliceBuilder {
+  client(fn: () => void): FluentQueryMomentBuilder;
+  client(description: string, fn: () => void): FluentQueryMomentBuilder;
+  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentQueryMomentBuilder {
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugQuery('Adding client block to slice %s', this.slice.name);
+    debugQuery('Adding client block to moment %s', this.moment.name);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugQuery('Starting client block execution');
-        startClientBlock(slice);
+        startClientBlock(moment);
         callback();
         endClientBlock();
         debugQuery('Client block execution completed');
       } else {
-        debugQuery('WARNING: No current slice found for client block');
+        debugQuery('WARNING: No current moment found for client block');
       }
     }
 
     return this;
   }
 
-  server(fn: () => void): FluentQuerySliceBuilder;
-  server(description: string, fn: () => void): FluentQuerySliceBuilder;
-  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentQuerySliceBuilder {
+  server(fn: () => void): FluentQueryMomentBuilder;
+  server(description: string, fn: () => void): FluentQueryMomentBuilder;
+  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentQueryMomentBuilder {
     const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugQuery('Adding server block to slice %s, description: "%s"', this.slice.name, description);
+    debugQuery('Adding server block to moment %s, description: "%s"', this.moment.name, description);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugQuery('Starting server block execution');
-        startServerBlock(slice, description);
+        startServerBlock(moment, description);
         callback();
         endServerBlock();
         debugQuery('Server block execution completed');
       } else {
-        debugQuery('WARNING: No current slice found for server block');
+        debugQuery('WARNING: No current moment found for server block');
       }
     }
 
     return this;
   }
 
-  request(query: unknown): FluentQuerySliceBuilder {
-    debugQuery('Setting request for slice %s', this.slice.name);
+  request(query: unknown): FluentQueryMomentBuilder {
+    debugQuery('Setting request for moment %s', this.moment.name);
     if (typeof query === 'string') {
       debugQuery('Request is string, length: %d', query.length);
-      this.slice.request = query;
+      this.moment.request = query;
     } else if (
       query !== null &&
       query !== undefined &&
@@ -245,8 +245,8 @@ class QuerySliceBuilderImpl implements FluentQuerySliceBuilder {
       query.kind === 'Document'
     ) {
       debugQuery('Request is GraphQL AST Document, converting to SDL');
-      this.slice.request = print(query as ASTNode); // ✅ convert AST to SDL string
-      debugQuery('Converted SDL length: %d', this.slice.request.length);
+      this.moment.request = print(query as ASTNode); // ✅ convert AST to SDL string
+      debugQuery('Converted SDL length: %d', this.moment.request.length);
     } else {
       debugQuery('ERROR: Invalid GraphQL query format');
       throw new Error('Invalid GraphQL query format');
@@ -255,92 +255,92 @@ class QuerySliceBuilderImpl implements FluentQuerySliceBuilder {
   }
 }
 
-class ReactionSliceBuilderImpl implements FluentReactionSliceBuilder {
-  private slice: ReactSlice;
+class ReactionMomentBuilderImpl implements FluentReactionMomentBuilder {
+  private moment: ReactMoment;
 
   constructor(name: string, id?: string) {
-    debugReact('Creating reaction slice: %s', name);
-    this.slice = {
+    debugReact('Creating reaction moment: %s', name);
+    this.moment = {
       type: 'react',
       name,
       id,
       server: { specs: [], data: undefined },
     };
-    addSlice(this.slice);
-    debugReact('Reaction slice added to flow: %s', name);
+    addMoment(this.moment);
+    debugReact('Reaction moment added to scene: %s', name);
   }
 
-  server(fn: () => void): FluentReactionSliceBuilder;
-  server(description: string, fn: () => void): FluentReactionSliceBuilder;
-  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentReactionSliceBuilder {
+  server(fn: () => void): FluentReactionMomentBuilder;
+  server(description: string, fn: () => void): FluentReactionMomentBuilder;
+  server(descriptionOrFn: string | (() => void), fn?: () => void): FluentReactionMomentBuilder {
     const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugReact('Adding server block to slice %s, description: "%s"', this.slice.name, description);
+    debugReact('Adding server block to moment %s, description: "%s"', this.moment.name, description);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugReact('Starting server block execution');
-        startServerBlock(slice, description);
+        startServerBlock(moment, description);
         callback();
         endServerBlock();
         debugReact('Server block execution completed');
       } else {
-        debugReact('WARNING: No current slice found for server block');
+        debugReact('WARNING: No current moment found for server block');
       }
     }
 
     return this;
   }
 
-  via(integration: Integration | Integration[]): FluentReactionSliceBuilder {
+  via(integration: Integration | Integration[]): FluentReactionMomentBuilder {
     const integrations = Array.isArray(integration) ? integration : [integration];
-    this.slice.via = integrations.map((i) => i.name);
-    debugReact('Set integrations for slice %s: %o', this.slice.name, this.slice.via);
+    this.moment.via = integrations.map((i) => i.name);
+    debugReact('Set integrations for moment %s: %o', this.moment.name, this.moment.via);
     return this;
   }
 
-  retries(count: number): FluentReactionSliceBuilder {
-    debugReact('Setting retries for slice %s: %d', this.slice.name, count);
+  retries(count: number): FluentReactionMomentBuilder {
+    debugReact('Setting retries for moment %s: %d', this.moment.name, count);
     // Store retries in additionalInstructions or metadata
-    this.slice.additionalInstructions = `retries: ${count}`;
+    this.moment.additionalInstructions = `retries: ${count}`;
     return this;
   }
 }
 
-class ExperienceSliceBuilderImpl implements FluentExperienceSliceBuilder {
-  private slice: ExperienceSlice;
+class ExperienceMomentBuilderImpl implements FluentExperienceMomentBuilder {
+  private moment: ExperienceMoment;
 
   constructor(name: string, id?: string) {
-    debugExperience('Creating experience slice: %s', name);
-    this.slice = {
+    debugExperience('Creating experience moment: %s', name);
+    this.moment = {
       type: 'experience',
       name,
       id,
       client: { specs: [] },
     };
-    addSlice(this.slice);
-    debugExperience('Experience slice added to flow: %s', name);
+    addMoment(this.moment);
+    debugExperience('Experience moment added to scene: %s', name);
   }
 
-  client(fn: () => void): FluentExperienceSliceBuilder;
-  client(description: string, fn: () => void): FluentExperienceSliceBuilder;
-  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentExperienceSliceBuilder {
+  client(fn: () => void): FluentExperienceMomentBuilder;
+  client(description: string, fn: () => void): FluentExperienceMomentBuilder;
+  client(descriptionOrFn: string | (() => void), fn?: () => void): FluentExperienceMomentBuilder {
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugExperience('Adding client block to slice %s', this.slice.name);
+    debugExperience('Adding client block to moment %s', this.moment.name);
 
     if (callback) {
-      const slice = getCurrentSlice();
-      if (slice) {
+      const moment = getCurrentMoment();
+      if (moment) {
         debugExperience('Starting client block execution');
-        startClientBlock(slice);
+        startClientBlock(moment);
         callback();
         endClientBlock();
         debugExperience('Client block execution completed');
       } else {
-        debugExperience('WARNING: No current slice found for client block');
+        debugExperience('WARNING: No current moment found for client block');
       }
     }
 
@@ -348,32 +348,32 @@ class ExperienceSliceBuilderImpl implements FluentExperienceSliceBuilder {
   }
 }
 
-export const command = (name: string, id?: string): FluentCommandSliceBuilder => {
-  debug('Creating command slice: %s', name);
-  return new CommandSliceBuilderImpl(name, id);
+export const command = (name: string, id?: string): FluentCommandMomentBuilder => {
+  debug('Creating command moment: %s', name);
+  return new CommandMomentBuilderImpl(name, id);
 };
 
-export const query = (name: string, id?: string): FluentQuerySliceBuilder => {
-  debug('Creating query slice: %s', name);
-  return new QuerySliceBuilderImpl(name, id);
+export const query = (name: string, id?: string): FluentQueryMomentBuilder => {
+  debug('Creating query moment: %s', name);
+  return new QueryMomentBuilderImpl(name, id);
 };
 
-export const react = (name: string, id?: string): FluentReactionSliceBuilder => {
-  debug('Creating react slice: %s', name);
-  return new ReactionSliceBuilderImpl(name, id);
+export const react = (name: string, id?: string): FluentReactionMomentBuilder => {
+  debug('Creating react moment: %s', name);
+  return new ReactionMomentBuilderImpl(name, id);
 };
 
-export const experience = (name: string, id?: string): FluentExperienceSliceBuilder => {
-  debug('Creating experience slice: %s', name);
-  return new ExperienceSliceBuilderImpl(name, id);
+export const experience = (name: string, id?: string): FluentExperienceMomentBuilder => {
+  debug('Creating experience moment: %s', name);
+  return new ExperienceMomentBuilderImpl(name, id);
 };
 
-export const decide = (name: string, id?: string): FluentCommandSliceBuilder => {
-  debug('Creating command slice via decide alias: %s', name);
-  return new CommandSliceBuilderImpl(name, id);
+export const decide = (name: string, id?: string): FluentCommandMomentBuilder => {
+  debug('Creating command moment via decide alias: %s', name);
+  return new CommandMomentBuilderImpl(name, id);
 };
 
-export const evolve = (name: string, id?: string): FluentQuerySliceBuilder => {
-  debug('Creating query slice via evolve alias: %s', name);
-  return new QuerySliceBuilderImpl(name, id);
+export const evolve = (name: string, id?: string): FluentQueryMomentBuilder => {
+  debug('Creating query moment via evolve alias: %s', name);
+  return new QueryMomentBuilderImpl(name, id);
 };