@pikku/core 0.12.95 → 0.12.96

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 0.12.96
+
+### Patch Changes
+
+- 88629af: Say why a hot-reload import failed instead of only that it did.
+
+  The dev module runner caught every failure bare and returned `null`, and the reloader turned that into a single line: `Failed to import: … (keeping old code)`. Keeping the old code is the right call, but it leaves the running process disagreeing with the file on disk, and the only symptom is a function returning stale output while the editor shows the new source — `tsc` passes, every import resolves, and there is nothing anywhere to explain it.
+
+  `run` now returns `{ ok: true, exports }` or `{ ok: false, error }`, so the failure case cannot be read past, and the reloader prints the error's message and stack under the existing line. A failure matching pikku's own documented limitation — a file using top-level `await`, which the `cjs` emit cannot express — says so outright, because in that case nothing is wrong with the file and re-reading it will never reveal that.
+
+- f1ccfe3: A step ladder reads as one paragraph, not a list of restatements
+
+  Every step prefixed its actor with `the `, named that actor again, and repeated
+  the phase keyword. A three-step run by one person said their name three times
+  and `Given` three times, only read as English when the persona key happened to
+  be a role noun, and never said who that person was — the fabric template's own
+  placeholder came out as `the nadia opens /app`.
+
+  ```
+  Given yasser (the founder) signs in
+  When  yasser opens the dashboard
+  And   sees the audit log
+  And   nadia reviews the invite
+  ```
+
+  The article is gone: the actor key is the subject verbatim, so a persona named
+  after a person reads as that person. A repeated phase reads as `And`, the way
+  Gherkin has always written it. A step that continues both the phase and the
+  actor drops the repeated subject, because English drops a repeated subject in a
+  compound predicate — it takes both, since eliding across a phase change gives
+  `When opens the dashboard`, and a pronoun rather than a name would give `they
+sees`, step templates being authored in the third person singular.
+
+  An actor is introduced once, by the persona's `jobTitle` — prose someone wrote
+  for a reader. `roles` is authorisation, so a persona whose only description is a
+  `reviewer` grant gets no introduction rather than one assembled out of grants.
+  A row carries `sentenceWithRole` alongside `sentence`, set only where an actor
+  is first named, so a renderer can offer the introduction as a toggle without
+  parsing a composed sentence back apart.
+
+  `{placeholder}` filling, the `#ordinal` lookup for repeated step names and an
+  actorless step reading as its description alone are all unchanged.
+
 ## 0.12.95
 
 ### Patch Changes

package/dist/dev/hot-reload.js

@@ -6,7 +6,7 @@ import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
-import { createModuleRunner } from './module-runner.js';
+import { createModuleRunner, isTopLevelAwaitLimitation, } from './module-runner.js';
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
@@ -40,6 +40,20 @@ const isWatchedTsFile = (filename) => {
         // Hidden files: editor/sed atomic-write temps must never trigger a reload.
         !basename(filename).startsWith('.'));
 };
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error) => {
+    if (isTopLevelAwaitLimitation(error)) {
+        return (`  ${error.message}\n` +
+            '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+            'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+            'dev server to pick the file up.');
+    }
+    return `  ${error.stack ?? error.message}`;
+};
 export async function pikkuDevReloader(options) {
     const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
@@ -56,11 +70,17 @@ export async function pikkuDevReloader(options) {
             return;
         const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
         const importPath = compiledFile ?? changedTsFile;
-        const mod = await moduleRunner.run(importPath);
-        if (!mod) {
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
+        const result = await moduleRunner.run(importPath);
+        if (!result.ok) {
+            // Keeping the old code leaves the process disagreeing with the file on
+            // disk, and the only symptom is stale output from a function that looks
+            // correct in the editor — so the reason has to be printed here, where it
+            // is still known, rather than left for the developer to reconstruct.
+            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+                reloadFailureReason(result.error));
             return;
         }
+        const mod = result.exports;
         // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
         for (const [exportName, exportValue] of Object.entries(mod)) {
             if (!isFunctionConfig(exportValue))

package/dist/dev/module-runner.d.ts

@@ -1,10 +1,27 @@
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult = {
+    ok: true;
+    exports: Record<string, unknown>;
+} | {
+    ok: false;
+    error: Error;
+};
 export interface PikkuModuleRunner {
     /** Run a user module by absolute path. Repeated runs of one path overwrite a
-     *  single registry slot. Returns `null` on failure so the caller can keep the
-     *  previously-loaded code. */
-    run: (absPath: string) => Promise<Record<string, unknown> | null>;
+     *  single registry slot. Failure is returned, not thrown, so the caller can
+     *  keep the previously-loaded code — and the discriminant makes that case
+     *  impossible to read past by accident. */
+    run: (absPath: string) => Promise<PikkuModuleRunResult>;
     evict: (absPath: string) => void;
     clear: () => void;
     readonly size: number;
 }
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export declare const isTopLevelAwaitLimitation: (error: Error) => boolean;
 export declare const createModuleRunner: () => PikkuModuleRunner;

package/dist/dev/module-runner.js

@@ -13,6 +13,11 @@ const loadTransform = async () => {
     transformSync = esbuild.transformSync;
     return transformSync;
 };
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
@@ -30,12 +35,20 @@ export const createModuleRunner = () => {
             const moduleObj = { exports: {} };
             fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
             registry.set(absPath, moduleObj.exports);
-            return moduleObj.exports;
+            return { ok: true, exports: moduleObj.exports };
         }
-        catch {
+        catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level
-            // `await`, which cannot be emitted in `cjs` form.
-            return null;
+            // `await`, which cannot be emitted in `cjs` form. Normalised to an
+            // `Error` so the caller always has a message and a stack to print
+            // without re-deriving them; a non-`Error` throw keeps its original value
+            // as the `cause`.
+            return {
+                ok: false,
+                error: thrown instanceof Error
+                    ? thrown
+                    : new Error(String(thrown), { cause: thrown }),
+            };
         }
     };
     return {

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -1,10 +1,32 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
-export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+export declare const composeStepProse: ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;
     template?: string;
     input?: unknown;
     actor?: string;
+    /**
+     * What this actor is, rendered as an apposition after their key — "yasser
+     * (the founder)". Only pass it where the actor has not been named yet: an
+     * ordinary run repeats one actor for a dozen steps, and repeating the role
+     * with them turns the one piece of context into the noise around it.
+     */
+    actorRole?: string;
+    /**
+     * This step repeats the phase of the one before it, so it reads as `And`
+     * rather than saying `Given` three times — the same thing Gherkin does.
+     */
+    continuesPhase?: boolean;
+    /**
+     * The step before this one had the same actor. Combined with `continuesPhase`
+     * the subject is dropped, because English drops a repeated subject in a
+     * compound predicate: "yasser opens the dashboard / and sees the audit log".
+     *
+     * It takes both. Dropping the subject across a phase change gives "When opens
+     * the dashboard", and a pronoun instead of a name would give "they sees",
+     * since step templates are authored in the third person singular.
+     */
+    continuesActor?: boolean;
     keywordWidth?: number;
 }) => string;

package/dist/wirings/workflow/scenario-prose.js

@@ -14,9 +14,13 @@ const formatValue = (value) => {
     }
     return String(value);
 };
-export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = capitalise(phase);
-    const subject = actor ? `the ${actor}` : '';
+export const composeStepProse = ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }) => {
+    const keyword = capitalise(continuesPhase ? 'and' : phase);
+    // The actor key is the subject verbatim, with no article in front of it.
+    // "the ${actor}" only reads as English when the key happens to be a role
+    // noun — it turns a persona named after a person into "the nadia", which
+    // is the reporter quietly imposing a naming convention on the author.
+    const subject = continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole);
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');
     if (keywordWidth === undefined) {
@@ -24,4 +28,9 @@ export const composeStepProse = ({ phase, description, template, input, actor, k
     }
     return `${keyword.padEnd(keywordWidth)} ${sentence}`;
 };
+const composeSubject = (actor, actorRole) => {
+    if (!actor)
+        return '';
+    return actorRole ? `${actor} (the ${actorRole})` : actor;
+};
 const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -35,6 +35,13 @@ export interface ScenarioArtifact {
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
+    /**
+     * The same sentence with the actor's role in it — "yasser (the founder)
+     * signs in". Set only on the step that first names each actor, and only
+     * when a persona declares a job title or a role, so a reader who wants the
+     * context picks this and one who wants the bare run picks `sentence`.
+     */
+    sentenceWithRole?: string;
     status: string;
     durationMs?: number;
     error?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.95",
+  "version": "0.12.96",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/dev/hot-reload.test.ts

@@ -215,6 +215,48 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
     assert.deepEqual(await func.func({} as any, {}, {} as any), {
       working: true,
     })
+
+    // Serving the old code is only safe if the developer is told why; without
+    // the reason the sole symptom is a function that ignores the file on disk.
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    assert.ok(
+      failureLog!.message.includes('keeping old code'),
+      'Should say the old code is still being served'
+    )
+    assert.match(failureLog!.message, /badFunc\.js/)
+  })
+
+  test('should name the top-level await limitation when a reload hits it', async (t) => {
+    if (!(await ensureRecursiveWatchAvailable(t, tmpDir))) return
+
+    await writeFile(join(tmpDir, 'tlaFunc.ts'), '// initial')
+
+    reloader = await pikkuDevReloader({
+      srcDirectories: [tmpDir],
+      logger: mockLogger,
+      pikkuDir: tmpDir,
+    })
+
+    await writeFile(
+      join(tmpDir, 'tlaFunc.ts'),
+      `const config = await Promise.resolve({ ok: true })
+       export const tlaFunc = { func: async () => config }
+       // trigger ${Date.now()}`
+    )
+
+    await wait(300)
+
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    // The file is valid TypeScript; pointing at pikku's own `cjs` emit is the
+    // difference between a two-minute fix and an afternoon.
+    assert.match(failureLog!.message, /top-level `?await`?/i)
+    assert.match(failureLog!.message, /pikku limitation/i)
   })
 
   test('should ignore non-ts files, test files, and gen files', async (t) => {

package/src/dev/hot-reload.ts

@@ -9,7 +9,10 @@ import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middlewa
 import { httpRouter } from '../wirings/http/routers/http-router.js'
 import type { Logger } from '../services/logger.js'
 import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
-import { createModuleRunner } from './module-runner.js'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} from './module-runner.js'
 
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
@@ -63,6 +66,23 @@ const isWatchedTsFile = (filename: string): boolean => {
   )
 }
 
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error: Error): string => {
+  if (isTopLevelAwaitLimitation(error)) {
+    return (
+      `  ${error.message}\n` +
+      '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+      'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+      'dev server to pick the file up.'
+    )
+  }
+  return `  ${error.stack ?? error.message}`
+}
+
 export interface PikkuDevReloaderHandle {
   close: () => void
   /** Re-import every file changed since the last drain (post-codegen, once
@@ -96,13 +116,19 @@ export async function pikkuDevReloader(
     )
     const importPath = compiledFile ?? changedTsFile
 
-    const mod = await moduleRunner.run(importPath)
-    if (!mod) {
+    const result = await moduleRunner.run(importPath)
+    if (!result.ok) {
+      // Keeping the old code leaves the process disagreeing with the file on
+      // disk, and the only symptom is stale output from a function that looks
+      // correct in the editor — so the reason has to be printed here, where it
+      // is still known, rather than left for the developer to reconstruct.
       logger.error(
-        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`
+        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+          reloadFailureReason(result.error)
       )
       return
     }
+    const mod = result.exports
 
     // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
     for (const [exportName, exportValue] of Object.entries(mod)) {

package/src/dev/module-runner.test.ts

@@ -8,7 +8,10 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { tmpdir } from 'node:os'
 
-import { createModuleRunner } from './module-runner.js'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} from './module-runner.js'
 
 // A forced-GC hook without launching the process with a flag: on Bun use the
 // native collector; on Node flip --expose-gc on just long enough to grab `gc`.
@@ -56,9 +59,10 @@ describe('createModuleRunner', { concurrency: false }, () => {
        export const createTodo = { func: async (_s: any, d: Todo) => ({ id: d.id }) }`
     )
 
-    const mod = await runner.run(file)
-    assert.ok(mod)
-    const createTodo = mod!.createTodo as {
+    const result = await runner.run(file)
+    assert.equal(result.ok, true)
+    const createTodo = (result as { exports: Record<string, unknown> }).exports
+      .createTodo as {
       func: (...a: any[]) => Promise<any>
     }
     assert.equal(typeof createTodo.func, 'function')
@@ -83,8 +87,9 @@ describe('createModuleRunner', { concurrency: false }, () => {
        wire('createTodo', createTodo)`
     )
 
-    const mod = await runner.run(userFile)
-    assert.ok(mod)
+    const result = await runner.run(userFile)
+    assert.equal(result.ok, true)
+    const mod = (result as { exports: Record<string, unknown> }).exports
 
     // Read the dependency through the same resolver the runner uses, so we
     // observe the exact instance the user module's `import` bound to (using a
@@ -103,26 +108,64 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     await writeFile(file, `export const value = { func: async () => 'v1' }`)
     const first = await runner.run(file)
-    assert.equal(await (first!.value as any).func(), 'v1')
+    assert.equal(first.ok, true)
+    assert.equal(await ((first as any).exports.value as any).func(), 'v1')
 
     await writeFile(file, `export const value = { func: async () => 'v2' }`)
     const second = await runner.run(file)
-    assert.equal(await (second!.value as any).func(), 'v2')
+    assert.equal(second.ok, true)
+    assert.equal(await ((second as any).exports.value as any).func(), 'v2')
 
     // Stable key: many reloads of one path never grow the registry.
     for (let i = 0; i < 20; i++) await runner.run(file)
     assert.equal(runner.size, 1)
   })
 
-  test('returns null on a bad edit so the caller keeps old code', async () => {
+  test('reports a bad edit with its reason so the caller can say why', async () => {
     const runner = createModuleRunner()
     const file = join(tmpDir, 'broken.ts')
     await writeFile(
       file,
       `export const oops = { func: async () => ( } ] syntax`
     )
-    const mod = await runner.run(file)
-    assert.equal(mod, null)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // The caller keeps serving the old code, so this error is the only thing
+    // standing between the developer and an unexplained stale response.
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.match(error.message, /broken\.ts/)
+    assert.equal(isTopLevelAwaitLimitation(error), false)
+  })
+
+  test('names the top-level await limitation as such', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'tla.ts')
+    await writeFile(
+      file,
+      `const config = await Promise.resolve({ ok: true })
+       export const load = { func: async () => config }`
+    )
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // Nothing is wrong with this file — the `cjs` emit is what cannot take it,
+    // and the caller has to be able to tell the developer that.
+    assert.equal(
+      isTopLevelAwaitLimitation((result as { error: Error }).error),
+      true
+    )
+  })
+
+  test('a thrown non-Error still arrives as an Error carrying its value', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'throws-a-string.ts')
+    await writeFile(file, `throw 'boom'`)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.equal(error.message, 'boom')
+    assert.equal((error as { cause?: unknown }).cause, 'boom')
   })
 
   test('editing and reimporting a module 200x does not leak memory', async () => {
@@ -153,8 +196,8 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     for (let i = 1; i <= 200; i++) {
       await write(i)
-      const mod = await runner.run(file)
-      assert.ok(mod)
+      const result = await runner.run(file)
+      assert.equal(result.ok, true)
     }
     gc()
     const growth = heapUsedMb() - baseline

package/src/dev/module-runner.ts

@@ -18,22 +18,35 @@ const loadTransform = async (): Promise<EsbuildTransform> => {
   return transformSync
 }
 
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult =
+  { ok: true; exports: Record<string, unknown> } | { ok: false; error: Error }
+
 export interface PikkuModuleRunner {
   /** Run a user module by absolute path. Repeated runs of one path overwrite a
-   *  single registry slot. Returns `null` on failure so the caller can keep the
-   *  previously-loaded code. */
-  run: (absPath: string) => Promise<Record<string, unknown> | null>
+   *  single registry slot. Failure is returned, not thrown, so the caller can
+   *  keep the previously-loaded code — and the discriminant makes that case
+   *  impossible to read past by accident. */
+  run: (absPath: string) => Promise<PikkuModuleRunResult>
   evict: (absPath: string) => void
   clear: () => void
   readonly size: number
 }
 
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error: Error): boolean =>
+  /top-level await/i.test(error.message)
+
 export const createModuleRunner = (): PikkuModuleRunner => {
   const registry = new Map<string, Record<string, unknown>>()
 
-  const run = async (
-    filePath: string
-  ): Promise<Record<string, unknown> | null> => {
+  const run = async (filePath: string): Promise<PikkuModuleRunResult> => {
     const absPath = resolve(filePath)
     try {
       const transform = await loadTransform()
@@ -55,11 +68,20 @@ export const createModuleRunner = (): PikkuModuleRunner => {
       fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath))
 
       registry.set(absPath, moduleObj.exports)
-      return moduleObj.exports
-    } catch {
+      return { ok: true, exports: moduleObj.exports }
+    } catch (thrown) {
       // A bad edit, or the one known limitation: a file using top-level
-      // `await`, which cannot be emitted in `cjs` form.
-      return null
+      // `await`, which cannot be emitted in `cjs` form. Normalised to an
+      // `Error` so the caller always has a message and a stack to print
+      // without re-deriving them; a non-`Error` throw keeps its original value
+      // as the `cause`.
+      return {
+        ok: false,
+        error:
+          thrown instanceof Error
+            ? thrown
+            : new Error(String(thrown), { cause: thrown }),
+      }
     }
   }
 

package/src/wirings/virtual-user/virtual-user-derive.test.ts

@@ -222,10 +222,10 @@ describe('deriving intents from scenarios', () => {
   test('the prose comes through with its placeholders left open', () => {
     const [intent] = deriveIntents(workflows, functions)
     assert.deepEqual(intent!.steps, [
-      'Given the orgAdmin is signed in',
+      'Given orgAdmin is signed in',
       // The scenario knows which address it invites. The user has to pick one.
-      'When the orgAdmin invites {email}',
-      'Then the orgAdmin sees the new member in the list',
+      'When orgAdmin invites {email}',
+      'Then orgAdmin sees the new member in the list',
     ])
   })
 
@@ -298,8 +298,8 @@ describe('deriving intents from scenarios', () => {
     )
 
     assert.deepEqual(intents[0]!.steps, [
-      'Given the orgAdmin is signed in',
-      'When the orgAdmin invites {email}',
+      'Given orgAdmin is signed in',
+      'When orgAdmin invites {email}',
     ])
     assert.deepEqual(intents[0]!.personas, ['orgAdmin'])
   })