@auto-engineer/narrative 0.11.20 → 0.12.1

package/package.json

@@ -23,9 +23,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "0.11.20",
-    "@auto-engineer/id": "0.11.20",
-    "@auto-engineer/message-bus": "0.11.20"
+    "@auto-engineer/file-store": "0.12.1",
+    "@auto-engineer/id": "0.12.1",
+    "@auto-engineer/message-bus": "0.12.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -33,12 +33,12 @@
     "eslint-plugin-sort-keys-fix": "^1.1.2",
     "fake-indexeddb": "^6.0.0",
     "tsx": "^4.20.3",
-    "@auto-engineer/cli": "0.11.20"
+    "@auto-engineer/cli": "0.12.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.20",
+  "version": "0.12.1",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/fluent-builder.ts

@@ -72,7 +72,7 @@ class CommandSliceBuilderImpl implements FluentCommandSliceBuilder {
       type: 'command',
       name,
       id,
-      client: { description: '', specs: undefined },
+      client: { specs: [] },
       server: { description: '', specs: { name: '', rules: [] }, data: undefined },
     };
     addSlice(this.slice);
@@ -88,16 +88,15 @@ class CommandSliceBuilderImpl implements FluentCommandSliceBuilder {
   client(fn: () => void): FluentCommandSliceBuilder;
   client(description: string, fn: () => void): FluentCommandSliceBuilder;
   client(descriptionOrFn: string | (() => void), fn?: () => void): FluentCommandSliceBuilder {
-    const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugCommand('Adding client block to slice %s, description: "%s"', this.slice.name, description);
+    debugCommand('Adding client block to slice %s', this.slice.name);
 
     if (callback) {
       const slice = getCurrentSlice();
       if (slice) {
         debugCommand('Starting client block execution');
-        startClientBlock(slice, description);
+        startClientBlock(slice);
         callback();
         endClientBlock();
         debugCommand('Client block execution completed');
@@ -179,7 +178,7 @@ class QuerySliceBuilderImpl implements FluentQuerySliceBuilder {
       type: 'query',
       name,
       id,
-      client: { description: '', specs: undefined },
+      client: { specs: [] },
       server: { description: '', specs: { name: '', rules: [] }, data: undefined },
     };
     addSlice(this.slice);
@@ -189,16 +188,15 @@ class QuerySliceBuilderImpl implements FluentQuerySliceBuilder {
   client(fn: () => void): FluentQuerySliceBuilder;
   client(description: string, fn: () => void): FluentQuerySliceBuilder;
   client(descriptionOrFn: string | (() => void), fn?: () => void): FluentQuerySliceBuilder {
-    const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugQuery('Adding client block to slice %s, description: "%s"', this.slice.name, description);
+    debugQuery('Adding client block to slice %s', this.slice.name);
 
     if (callback) {
       const slice = getCurrentSlice();
       if (slice) {
         debugQuery('Starting client block execution');
-        startClientBlock(slice, description);
+        startClientBlock(slice);
         callback();
         endClientBlock();
         debugQuery('Client block execution completed');
@@ -320,7 +318,7 @@ class ExperienceSliceBuilderImpl implements FluentExperienceSliceBuilder {
       type: 'experience',
       name,
       id,
-      client: { description: '', specs: undefined },
+      client: { specs: [] },
     };
     addSlice(this.slice);
     debugExperience('Experience slice added to flow: %s', name);
@@ -329,16 +327,15 @@ class ExperienceSliceBuilderImpl implements FluentExperienceSliceBuilder {
   client(fn: () => void): FluentExperienceSliceBuilder;
   client(description: string, fn: () => void): FluentExperienceSliceBuilder;
   client(descriptionOrFn: string | (() => void), fn?: () => void): FluentExperienceSliceBuilder {
-    const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
     const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn;
 
-    debugExperience('Adding client block to slice %s, description: "%s"', this.slice.name, description);
+    debugExperience('Adding client block to slice %s', this.slice.name);
 
     if (callback) {
       const slice = getCurrentSlice();
       if (slice) {
         debugExperience('Starting client block execution');
-        startClientBlock(slice, description);
+        startClientBlock(slice);
         callback();
         endClientBlock();
         debugExperience('Client block execution completed');

package/src/getNarratives.specs.ts

@@ -56,8 +56,13 @@ describe('getNarratives', (_mode) => {
       expect(createItemSlice.stream).toBe('item-${id}');
       if (createItemSlice.type === 'command') {
         expect(createItemSlice.client.specs).toBeDefined();
-        expect(createItemSlice.client.specs?.name).toBe('A form that allows users to add items');
-        expect(createItemSlice.client.specs?.rules).toHaveLength(1);
+        expect(Array.isArray(createItemSlice.client.specs)).toBe(true);
+        expect(createItemSlice.client.specs).toHaveLength(1);
+        expect(createItemSlice.client.specs[0].type).toBe('describe');
+        expect(createItemSlice.client.specs[0].title).toBe('A form that allows users to add items');
+        if (createItemSlice.client.specs[0].type === 'describe') {
+          expect(createItemSlice.client.specs[0].children).toHaveLength(1);
+        }
         expect(createItemSlice.server.specs).toBeDefined();
         const spec = createItemSlice.server.specs;
         expect(spec.name).toBeDefined();
@@ -91,8 +96,13 @@ describe('getNarratives', (_mode) => {
       expect(viewItemSlice.type).toBe('query');
       expect(viewItemSlice.name).toBe('view items');
       expect(viewItemSlice.client.specs).toBeDefined();
-      expect(viewItemSlice.client.specs?.name).toBe('view Items Screen');
-      expect(viewItemSlice.client.specs?.rules).toHaveLength(3);
+      expect(Array.isArray(viewItemSlice.client.specs)).toBe(true);
+      expect(viewItemSlice.client.specs).toHaveLength(1);
+      expect(viewItemSlice.client.specs[0].type).toBe('describe');
+      expect(viewItemSlice.client.specs[0].title).toBe('view Items Screen');
+      if (viewItemSlice.client.specs[0].type === 'describe') {
+        expect(viewItemSlice.client.specs[0].children).toHaveLength(3);
+      }
       expect(viewItemSlice.request).toBeDefined();
       expect(viewItemSlice.request).toMatch(
         /query items\(\$itemId: String!\) {\s+items\(itemId: \$itemId\) {\s+id\s+description\s+}/,
@@ -119,8 +129,13 @@ describe('getNarratives', (_mode) => {
 
       if (submitOrderSlice.type === 'command') {
         expect(submitOrderSlice.client.specs).toBeDefined();
-        expect(submitOrderSlice.client.specs?.name).toBe('Order submission form');
-        expect(submitOrderSlice.client.specs?.rules).toHaveLength(2);
+        expect(Array.isArray(submitOrderSlice.client.specs)).toBe(true);
+        expect(submitOrderSlice.client.specs).toHaveLength(1);
+        expect(submitOrderSlice.client.specs[0].type).toBe('describe');
+        expect(submitOrderSlice.client.specs[0].title).toBe('Order submission form');
+        if (submitOrderSlice.client.specs[0].type === 'describe') {
+          expect(submitOrderSlice.client.specs[0].children).toHaveLength(2);
+        }
         expect(submitOrderSlice.server.specs).toBeDefined();
         const spec = submitOrderSlice.server.specs;
         expect(spec.rules).toHaveLength(1);
@@ -390,13 +405,13 @@ describe('getNarratives', (_mode) => {
   it('should handle experience slice with client specs', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowWithExperienceContent = `
-import { flow, experience, should, specs } from '@auto-engineer/narrative';
+import { flow, experience, it, specs } from '@auto-engineer/narrative';
 
 flow('Test Experience Flow', () => {
   experience('Homepage', 'AUTO-H1a4Bn6Cy').client(() => {
     specs(() => {
-      should('show a hero section with a welcome message');
-      should('allow user to start the questionnaire');
+      it('show a hero section with a welcome message');
+      it('allow user to start the questionnaire');
     });
   });
 });
@@ -418,15 +433,12 @@ flow('Test Experience Flow', () => {
       if (homepageSlice?.type === 'experience') {
         expect(homepageSlice.client).toBeDefined();
         expect(homepageSlice.client.specs).toBeDefined();
-        expect(homepageSlice.client.specs?.rules).toBeDefined();
-        expect(homepageSlice.client.specs?.rules).toHaveLength(2);
-
-        const rules = homepageSlice.client.specs?.rules;
-        if (rules && Array.isArray(rules)) {
-          expect(rules).toHaveLength(2);
-          expect(rules[0]).toBe('show a hero section with a welcome message');
-          expect(rules[1]).toBe('allow user to start the questionnaire');
-        }
+        expect(Array.isArray(homepageSlice.client.specs)).toBe(true);
+        expect(homepageSlice.client.specs).toHaveLength(2);
+        expect(homepageSlice.client.specs[0].type).toBe('it');
+        expect(homepageSlice.client.specs[0].title).toBe('show a hero section with a welcome message');
+        expect(homepageSlice.client.specs[1].type).toBe('it');
+        expect(homepageSlice.client.specs[1].title).toBe('allow user to start the questionnaire');
       }
     }
   });
@@ -434,12 +446,12 @@ flow('Test Experience Flow', () => {
   it('simulates browser execution with transpiled CommonJS code', async () => {
     const memoryVfs = new InMemoryFileStore();
     const flowContent = `
-import { flow, experience, should, specs } from '@auto-engineer/narrative';
+import { flow, experience, it, specs } from '@auto-engineer/narrative';
 
 flow('Browser Test Flow', () => {
   experience('HomePage').client(() => {
     specs(() => {
-      should('render correctly');
+      it('render correctly');
     });
   });
 });
@@ -466,8 +478,10 @@ flow('Browser Test Flow', () => {
     if (slice.type === 'experience') {
       expect(slice.client).toBeDefined();
       expect(slice.client.specs).toBeDefined();
-      expect(slice.client.specs?.rules).toHaveLength(1);
-      expect(slice.client.specs?.rules?.[0]).toBe('render correctly');
+      expect(Array.isArray(slice.client.specs)).toBe(true);
+      expect(slice.client.specs).toHaveLength(1);
+      expect(slice.client.specs[0].type).toBe('it');
+      expect(slice.client.specs[0].title).toBe('render correctly');
     }
   });
 
@@ -972,7 +986,8 @@ import {
   query,
   experience,
   flow,
-  should,
+  describe,
+  it,
   specs,
   rule,
   example,
@@ -1048,9 +1063,9 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     \`)
     .client(() => {
-      specs('Questionnaire Link', () => {
-        should('display a confirmation message when the link is sent');
-        should('handle errors when the link cannot be sent');
+      describe('Questionnaire Link', () => {
+        it('display a confirmation message when the link is sent');
+        it('handle errors when the link cannot be sent');
       });
     });
 
@@ -1080,8 +1095,8 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     \`)
     .client(() => {
-      specs('Submission Confirmation', () => {
-        should('display a confirmation message upon successful submission');
+      describe('Submission Confirmation', () => {
+        it('display a confirmation message upon successful submission');
       });
     });
 });`;

package/src/id/addAutoIds.specs.ts

@@ -12,7 +12,7 @@ describe('addAutoIds', () => {
           {
             type: 'command',
             name: 'Test Command Slice',
-            client: { description: 'Test client' },
+            client: { specs: [] },
             server: {
               description: 'Test server',
               specs: {
@@ -35,7 +35,7 @@ describe('addAutoIds', () => {
             type: 'query',
             name: 'Test Query Slice',
             id: 'EXISTING-SLICE-001',
-            client: { description: 'Test client' },
+            client: { specs: [] },
             server: {
               description: 'Test server',
               specs: {
@@ -135,7 +135,7 @@ describe('addAutoIds', () => {
             {
               type: 'command',
               name: 'Simple Command',
-              client: { description: 'Simple client' },
+              client: { specs: [] },
               server: {
                 description: 'Simple server',
                 specs: {
@@ -176,11 +176,10 @@ describe('addAutoIds', () => {
               type: 'experience',
               name: 'User Onboarding Experience',
               client: {
-                description: 'User onboarding client',
-                specs: {
-                  name: 'Onboarding Specs',
-                  rules: ['User should see welcome message', 'User should complete profile setup'],
-                },
+                specs: [
+                  { type: 'it', title: 'User should see welcome message' },
+                  { type: 'it', title: 'User should complete profile setup' },
+                ],
               },
             },
             {
@@ -188,11 +187,7 @@ describe('addAutoIds', () => {
               name: 'Checkout Experience',
               id: 'EXISTING-EXPERIENCE-SLICE-001',
               client: {
-                description: 'Checkout client',
-                specs: {
-                  name: 'Checkout Specs',
-                  rules: ['User should review cart items'],
-                },
+                specs: [{ type: 'it', title: 'User should review cart items' }],
               },
             },
           ],
@@ -226,10 +221,7 @@ describe('addAutoIds', () => {
               name: 'Active Surveys Summary',
               type: 'experience',
               client: {
-                specs: {
-                  name: '',
-                  rules: ['show active surveys summary'],
-                },
+                specs: [{ type: 'it', title: 'show active surveys summary' }],
               },
             },
           ],
@@ -242,10 +234,7 @@ describe('addAutoIds', () => {
               name: 'Create Survey Form',
               type: 'experience',
               client: {
-                specs: {
-                  name: '',
-                  rules: ['allow entering survey title'],
-                },
+                specs: [{ type: 'it', title: 'allow entering survey title' }],
               },
             },
           ],
@@ -258,10 +247,7 @@ describe('addAutoIds', () => {
               name: 'Response Rate Charts',
               type: 'experience',
               client: {
-                specs: {
-                  name: '',
-                  rules: ['show daily response rate charts'],
-                },
+                specs: [{ type: 'it', title: 'show daily response rate charts' }],
               },
             },
           ],

package/src/id/hasAllIds.specs.ts

@@ -58,13 +58,13 @@ flow('Test Flow with IDs', 'FLOW-001', () => {
 });`;
 
     const multipleFlowsSameSource = `
-import { flow, specs, should } from '../narrative';
+import { flow, specs, it } 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');
+      it('show active surveys summary');
     });
   });
 });
@@ -72,7 +72,7 @@ flow('Home Screen', 'AUTO-aifPcU3hw', () => {
 flow('Create Survey', 'AUTO-MPviTMrQC', () => {
   experience('Create Survey Form', 'AUTO-slice2').client(() => {
     specs(() => {
-      should('allow entering survey title');
+      it('allow entering survey title');
     });
   });
 });
@@ -80,19 +80,19 @@ flow('Create Survey', 'AUTO-MPviTMrQC', () => {
 flow('Response Analytics', 'AUTO-eME978Euk', () => {
   experience('Response Rate Charts', 'AUTO-slice3').client(() => {
     specs(() => {
-      should('show daily response rate charts');
+      it('show daily response rate charts');
     });
   });
 });`;
 
     const multipleFlowsIncomplete = `
-import { flow, specs, should } from '../narrative';
+import { flow, specs, it } 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');
+      it('show active surveys summary');
     });
   });
 });
@@ -100,7 +100,7 @@ flow('Home Screen', 'AUTO-aifPcU3hw', () => {
 flow('Create Survey', () => {
   experience('Create Survey Form', 'AUTO-slice2').client(() => {
     specs(() => {
-      should('allow entering survey title');
+      it('allow entering survey title');
     });
   });
 });
@@ -108,19 +108,19 @@ flow('Create Survey', () => {
 flow('Response Analytics', 'AUTO-eME978Euk', () => {
   experience('Response Rate Charts', 'AUTO-slice3').client(() => {
     specs(() => {
-      should('show daily response rate charts');
+      it('show daily response rate charts');
     });
   });
 });`;
 
     const multipleFlowsSliceMissing = `
-import { flow, specs, should } from '../narrative';
+import { flow, specs, it } 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');
+      it('show active surveys summary');
     });
   });
 });
@@ -128,7 +128,7 @@ flow('Home Screen', 'AUTO-aifPcU3hw', () => {
 flow('Create Survey', 'AUTO-MPviTMrQC', () => {
   experience('Create Survey Form').client(() => {
     specs(() => {
-      should('allow entering survey title');
+      it('allow entering survey title');
     });
   });
 });
@@ -136,7 +136,7 @@ flow('Create Survey', 'AUTO-MPviTMrQC', () => {
 flow('Response Analytics', 'AUTO-eME978Euk', () => {
   experience('Response Rate Charts', 'AUTO-slice3').client(() => {
     specs(() => {
-      should('show daily response rate charts');
+      it('show daily response rate charts');
     });
   });
 });`;

package/src/index.ts

@@ -44,7 +44,7 @@ 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 { client, server, specs, describe, it, should, request, data, rule, example } from './narrative';
 export type { SliceTypeValueInterface } from './narrative';
 export { SliceType } from './narrative';
 
@@ -115,6 +115,7 @@ 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 type { ClientSpecNode } from './schema';
 
 // ID assignment utilities
 export { addAutoIds, hasAllIds } from './id';