rhachet-roles-ehmpathy 1.13.0 → 1.13.1

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/howto.write.bdd.[lesson].md

@@ -1,280 +0,0 @@
-# How to Write BDD Style Tests
-
-This guide explains the pattern for writing integration tests using `test-fns` with `given`, `when`, `then`, and `useBeforeAll`.
-
-## Core Pattern
-
-```typescript
-import { given, when, then, useBeforeAll } from 'test-fns';
-
-describe('featureName', () => {
-  // Shared setup for all tests in the describe block
-  const dbConnection = useBeforeAll(() => getDatabaseConnection());
-  afterAll(async () => dbConnection.end());
-
-  given('[case1] description of the initial state', () => {
-    // Setup specific to this case, shared across all when/then blocks
-    const scene = useBeforeAll(async () => {
-      // Create test data
-      const entity = await createEntity({ dbConnection });
-      return { entity };
-    });
-
-    when('[t0] action or event occurs', () => {
-      then('expected outcome', async () => {
-        // Execute and verify using scene.entity
-        const result = await performAction({ id: scene.entity.id });
-        expect(result).toEqual(expectedValue);
-      });
-    });
-
-    when('[t1] different action occurs', () => {
-      then('different expected outcome', async () => {
-        // Another test using the same scene
-        const result = await performOtherAction({ id: scene.entity.id });
-        expect(result).toEqual(otherExpectedValue);
-      });
-    });
-  });
-});
-```
-
-## Key Principles
-
-### 1. Wrap Everything in `describe`
-
-All tests for a feature should be wrapped in a single `describe` block:
-
-```typescript
-describe('syncPhoneFromWhodis', () => {
-  // all given/when/then blocks go here
-});
-```
-
-### 2. Use `useBeforeAll` for shared resources
-
-Instead of `let` + `beforeAll` + `afterAll`:
-
-e.g.,
-```typescript
-// ❌ Don't do this
-let dbConnection: DatabaseConnection;
-beforeAll(async () => {
-  dbConnection = await getDatabaseConnection();
-});
-afterAll(async () => {
-  await dbConnection.end();
-});
-
-// ✅ Do this
-const dbConnection = useBeforeAll(() => getDatabaseConnection());
-afterAll(async () => dbConnection.end());
-```
-
-### 3. Label given(scenes) with `[caseN]`
-
-Each `given` block should have a unique case label:
-
-```typescript
-given('[case1] doer with outdated phone', () => { ... });
-given('[case2] doer with matching phone', () => { ... });
-given('[case3] doer does not exist', () => { ... });
-```
-
-### 4. Label when(event) with `[tN]`
-
-Each `when` block should have an event time index label. The counter resets within each `given` block:
-
-```typescript
-given('[case1] first scenario', () => {
-  when('[t0] command executed in PLAN mode', () => { ... });
-  when('[t1] command executed in EXECUTE mode', () => { ... });
-});
-
-given('[case2] second scenario', () => {
-  when('[t0] first action', () => { ... });  // counter resets to 0
-  when('[t1] second action', () => { ... });
-});
-```
-
-### 5. One Behavioral Assertion per `then` Block
-
-Each `then` block should test a single behavioral assertion. This makes test failures more precise and test names more descriptive:
-
-```typescript
-// ❌ Don't do this - multiple assertions in one then
-when('[t0] command executed in PLAN mode', () => {
-  then('decision is UPDATE and doer remains unchanged', async () => {
-    const result = await command({ mode: 'PLAN' });
-    expect(result.decision).toEqual('UPDATE');
-    expect(result.before.doer.contactPhoneNumber).toEqual('+13175550200');
-
-    const doerAfter = await doerDao.findByUnique({ dbConnection, userUuid });
-    expect(doerAfter?.contactPhoneNumber).toEqual('+13175550200');
-  });
-});
-
-// ✅ Do this - separate then blocks for each behavioral assertion
-when('[t0] command executed in PLAN mode', () => {
-  then('decision is "UPDATE"', async () => {
-    const result = await command({ mode: 'PLAN' });
-    expect(result.decision).toEqual('UPDATE');
-  });
-
-  then('before.doer.contactPhoneNumber is "+13175550200"', async () => {
-    const result = await command({ mode: 'PLAN' });
-    expect(result.before.doer.contactPhoneNumber).toEqual('+13175550200');
-  });
-
-  then('doer contactPhoneNumber remains unchanged', async () => {
-    await command({ mode: 'PLAN' });
-    const doerAfter = await doerDao.findByUnique({ dbConnection, userUuid });
-    expect(doerAfter?.contactPhoneNumber).toEqual('+13175550200');
-  });
-});
-```
-
-### 6. Use `scene` for Shared Test Data
-
-When multiple `when/then` blocks need the same test data, use `useBeforeAll` to create a `scene`:
-
-```typescript
-given('[case1] description', () => {
-  const scene = useBeforeAll(async () => {
-    const doer = await createDoer({ dbConnection });
-    const provider = await createProvider({ dbConnection, doerId: doer.id });
-    return { doer, provider };
-  });
-
-  when('[t0] first test', () => {
-    then('outcome', async () => {
-      // Access scene.doer and scene.provider
-      const result = await action({ doerId: scene.doer.id });
-    });
-  });
-
-  when('[t1] second test', () => {
-    then('outcome', async () => {
-      // Same scene is reused
-      const result = await otherAction({ providerId: scene.provider.id });
-    });
-  });
-});
-```
-
-### 7. Cases Without Setup
-
-If a case doesn't need setup (e.g., testing error handling with invalid input), skip the `scene`:
-
-```typescript
-given('[case4] valid userUuid', () => {
-  when('[t7] Whodis user cannot be found', () => {
-    then('command throws error', async () => {
-      await expect(
-        command({ userUuid: '00000000-0000-0000-0000-000000000001' }),
-      ).rejects.toThrow('Whodis user not found');
-    });
-  });
-});
-```
-
-## Complete Example
-
-```typescript
-import { given, when, then, useBeforeAll } from 'test-fns';
-import { getDatabaseConnection } from '../../utils/database/getDatabaseConnection';
-import { myCommand } from './myCommand';
-
-describe('myCommand', () => {
-  const dbConnection = useBeforeAll(() => getDatabaseConnection());
-  afterAll(async () => dbConnection.end());
-
-  given('[case1] entity exists with state A', () => {
-    const scene = useBeforeAll(async () => {
-      const entity = await createEntity({
-        dbConnection,
-        state: 'A',
-      });
-      return { entity };
-    });
-
-    when('[t0] command executed in PLAN mode', () => {
-      then('decision is "UPDATE"', async () => {
-        const result = await myCommand({
-          entityId: scene.entity.id,
-          mode: 'PLAN',
-        });
-        expect(result.decision).toEqual('UPDATE');
-      });
-
-      then('entity state remains "A"', async () => {
-        await myCommand({ entityId: scene.entity.id, mode: 'PLAN' });
-        const entityAfter = await findEntity({ dbConnection, id: scene.entity.id });
-        expect(entityAfter.state).toEqual('A');
-      });
-    });
-
-    when('[t1] command executed in EXECUTE mode', () => {
-      then('decision is "UPDATE"', async () => {
-        const result = await myCommand({
-          entityId: scene.entity.id,
-          mode: 'EXECUTE',
-        });
-        expect(result.decision).toEqual('UPDATE');
-      });
-
-      then('after.state is "B"', async () => {
-        const result = await myCommand({
-          entityId: scene.entity.id,
-          mode: 'EXECUTE',
-        });
-        expect(result.after.state).toEqual('B');
-      });
-
-      then('entity state is updated to "B"', async () => {
-        await myCommand({ entityId: scene.entity.id, mode: 'EXECUTE' });
-        const entityAfter = await findEntity({ dbConnection, id: scene.entity.id });
-        expect(entityAfter.state).toEqual('B');
-      });
-    });
-  });
-
-  given('[case2] entity already in state B', () => {
-    const scene = useBeforeAll(async () => {
-      const entity = await createEntity({
-        dbConnection,
-        state: 'B',
-      });
-      return { entity };
-    });
-
-    when('[t0] command executed', () => {
-      then('decision is "NOCHANGE"', async () => {
-        const result = await myCommand({
-          entityId: scene.entity.id,
-          mode: 'EXECUTE',
-        });
-        expect(result.decision).toEqual('NOCHANGE');
-      });
-    });
-  });
-
-  given('[case3] invalid entityId', () => {
-    when('[t0] command executed', () => {
-      then('throws error', async () => {
-        await expect(
-          myCommand({ entityId: 'invalid-id', mode: 'PLAN' }),
-        ).rejects.toThrow('Entity not found');
-      });
-    });
-  });
-});
-```
-
-## Benefits
-
-1. **Readable test output**: Test names clearly show the scenario being tested
-2. **Efficient setup**: `useBeforeAll` runs once per `given` block, not per test
-3. **Immutable references**: `const scene` and `const dbConnection` prevent accidental reassignment
-4. **Clear labeling**: `[caseN]` and `[tN]` labels make it easy to identify and discuss specific tests
-5. **Black-box testing**: Tests interact only through the contract layer, not internal implementations

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/prefer.datadriven.md

@@ -1,41 +0,0 @@
-when possible, prefer data driven, caselist based, tests
-
-this is especially applicable for unit tests, which often evaluate a transform
-
----
-
-
-for example
-
-
-```ts
-
-const TEST_CASES = [
-  {
-    description: 'capitalizes the first word in a sentence',
-    given: {
-      input: 'the bird is in the basket',
-    },
-    expect: {
-      output: 'The bird is in the basket',
-    }
-  },
-  {
-    description: 'retains existing capitals in the sentence',
-    given: {
-      input: 'that Doctor Goose is a loon!',
-    },
-    expect: {
-      output: 'That Doctor Goose is a loon!',
-    }
-  },
-]
-
-describe('asSentenceCase', () => {
-  TEST_CASES.map(thisCase => test(thisCase.description, () => {
-    const output = asSentenceCase(thisCase.given.input);
-    expect(output).toEqual(thisCase.expect.output);
-  }))
-})
-
-```

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/ref.test-fns.[readme].md

@@ -1,185 +0,0 @@
-# test-fns
-
-![ci_on_commit](https://github.com/ehmpathy/test-fns/workflows/ci_on_commit/badge.svg)
-![deploy_on_tag](https://github.com/ehmpathy/test-fns/workflows/deploy_on_tag/badge.svg)
-
-write usecase driven tests systematically for simpler, safer, and more readable code
-
-# purpose
-
-establishes a pattern of writing tests for simpler, safer, and more readable code.
-
-by defining tests in terms of usecases (`given`, `when`, `then`) your tests are
-- simpler to write
-- easier to read
-- safer to trust
-
-# install
-
-```sh
-npm install --save test-fns
-```
-
-# use
-
-```ts
-type Plant = { id: number, hydration: 'DRY' | 'WET' };
-const doesPlantNeedWater = (plant: Plant) => plant.hydration === 'DRY';
-
-describe('doesPlantNeedWater', () => {
-  given('a plant', () => {
-    when('the plant doesnt have enough water', () => {
-      const plant: Plant = {
-        id: 7,
-        hydration: 'DRY',
-      };
-      then('it should return true', () => {
-        expect(doesPlantNeedWater(plant)).toEqual(true)
-      })
-    })
-  })
-})
-```
-
-produces
-
-```sh
- PASS  src/givenWhenThen.test.ts
-  doesPlantNeedWater
-    given: a plant
-      when: the plant doesnt have enough water
-        ✓ then: it should return true (1 ms)
-```
-
-# features
-
-
-### .runIf(condition) && .skipIf(condition)
-
-skip running the suite if the condition is not met
-
-```ts
-describe('your test', () => {
-  given.runIf(onLocalMachine)('some test that should only run locally', () => {
-    then.skipIf(onProduction)('some test that should not run against production', () => {
-      expect(onProduction).toBeFalse()
-    })
-  })
-})
-```
-
-### usePrep
-
-prepare test scenarios within a .given/.when block asynchronously, without any `let`s or `beforeAll`s
-
-`usePrep` accepts a `mode` option to control when setup runs:
-- `mode: 'beforeAll'` - runs setup once for all tests (default)
-- `mode: 'beforeEach'` - runs setup fresh before each test
-
-```ts
-given('an overdue invoice', () => {
-  const invoice = usePrep(async () => {
-    const invoiceOverdue = await ... // your logic
-    return invoiceOverdue;
-  })
-
-  then('it should invoke a reminder', async () => {
-    const result = await nurtureInvoice({ invoice }, context)
-    expect(result.sent.reminder).toEqual(true)
-  })
-})
-```
-
-**useBeforeAll and useBeforeEach are convenience wrappers** around `usePrep`:
-- `useBeforeAll(setup)` is equivalent to `usePrep(setup, { mode: 'beforeAll' })`
-- `useBeforeEach(setup)` is equivalent to `usePrep(setup, { mode: 'beforeEach' })`
-
-Use the named functions for clarity about when setup runs.
-
-### useBeforeAll
-
-prepare test resources once for all tests in a suite, optimizing setup time for expensive operations
-
-```ts
-describe('spaceship refueling system', () => {
-  given('a spaceship that needs to refuel', () => {
-    const spaceship = useBeforeAll(async () => {
-      // This runs once before all tests in this suite
-      const ship = await prepareExampleSpaceship();
-      await ship.dock();
-      return ship;
-    });
-
-    when('no changes are made', () => {
-      then('it should be docked', async () => {
-        expect(spaceship.isDocked).toEqual(true);
-      });
-
-      then('it should need fuel', async () => {
-        expect(spaceship.fuelLevel).toBeLessThan(spaceship.fuelCapacity);
-      });
-    });
-
-    when('it connects to the fuel station', () => {
-      const result = useBeforeAll(async () => await spaceship.connectToFuelStation());
-
-      then('it should be connected', async () => {
-        expect(result.connected).toEqual(true);
-      });
-
-      then('it should calculate required fuel', async () => {
-        expect(result.fuelNeeded).toBeGreaterThan(0);
-      });
-    });
-  });
-});
-```
-
-### useBeforeEach
-
-prepare fresh test resources before each test, ensuring test isolation
-
-```ts
-describe('spaceship combat system', () => {
-  given('a spaceship in battle', () => {
-    // This runs before each test, ensuring a fresh spaceship
-    const spaceship = useBeforeEach(async () => {
-      const ship = await prepareExampleSpaceship();
-      await ship.resetShields();
-      return ship;
-    });
-
-    when('no changes are made', () => {
-      then('it should have full shields', async () => {
-        expect(spaceship.shields).toEqual(100);
-      });
-
-      then('it should be ready for combat', async () => {
-        expect(spaceship.status).toEqual('READY');
-      });
-    });
-
-    when('it takes damage', () => {
-      const result = useBeforeEach(async () => await spaceship.takeDamage(25));
-
-      then('it should reduce shield strength', async () => {
-        expect(spaceship.shields).toEqual(75);
-      });
-
-      then('it should return damage report', async () => {
-        expect(result.damageReceived).toEqual(25);
-      });
-    });
-  });
-});
-```
-
-**When to use each:**
-- `useBeforeAll`: Use when setup is expensive (database connections, API calls) and tests don't modify the resource
-- `useBeforeEach`: Use when tests modify the resource and need isolation between runs
-- `usePrep`: The base function that powers both - use when you want explicit control over the mode or need to dynamically choose between `beforeAll` and `beforeEach`
-
-**Key differences:**
-- All three functions (`usePrep`, `useBeforeAll`, `useBeforeEach`) create a proxy that defers setup until the test framework's lifecycle hooks run
-- `useBeforeAll` and `useBeforeEach` are just clearer, more readable shortcuts for `usePrep` with a specific mode
-- Choose based on readability: use `useBeforeAll`/`useBeforeEach` for explicit intent, or `usePrep` when mode needs to be configurable

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/whento.snapshots.[lesson].md

@@ -1,23 +0,0 @@
-use snapshots whenever output artifacts are created
-
-why?
-- makes it easier to review in prs what is actually being produced
-  - e.g., visual spotcheck, make sure it looks good
-  - especially important when the output is userfacing (e.g., codegen, comms, etc)
-
-- makes it easier to detect exactly what the impact of a change is
-  - most of the time its intended and the snapshot can just be updated
-  - sometimes though, the snapshot diff exposes critical differences that are blockers or nitpicks that need to be addressed
-
-
----
-
-critical:
-
-use both
-- a snapshot
-- AND
-- explicit assertions before the snapshot
-
-snapshot is for observability in code reviews and aesthetic verification
-assertions are for functional verification

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/.readme.md

@@ -1 +0,0 @@
-practices on which terms to use to promote a ubiquitous language go here

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/bad-practices/forbid.term=existing.md

@@ -1,10 +0,0 @@
-never use the term `existing`; its a needless gerund
-
-either
-- foundBefore
-- or
-- foundAfter
-
-or some nonGerund alternative
-
-but never `existing`

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/best-practice/require.order.noun_adj.md

@@ -1,39 +0,0 @@
- always use [noun][adjective] order
-
- e.g.,
-
- instead of
-
- currentOwner = [adj][noun]
-
- prefer
-
- ownerCurrent = [noun][adj]
-
-
----
-
-instead of
-
-
-foundUser
-
-prefer
-
-userFound
-
-----
-
-
-why?
-
-because it enables autocomplete via common prefixes
-
-e.g.,
-
-userBefore
-userAfter
-userCreated
-etc
-
-can see via autocomplete suggestions all the variants of user available in the current scope, rather than need to remember what the variants are

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/domain=practices.terms=forbid_prefer_desire_require.md

@@ -1,13 +0,0 @@
-these are the terms we use to describe how to use practices
-
-forbid = search to ensure this was not done
-- it's a bad practice
-- it's a BLOCKER if detected
-
-prefer = search for opportunities to do this
-- it's a best practice, but not mandatory
-- it's a NITPICK if detected
-
-require = search for opportunities to do this
-- it's a best practice, and is mandatory
-- it's a BLOCKER if detected

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/domain=software.terms=prodcode_vs_testcode.md

@@ -1,7 +0,0 @@
-prodcode = the product's code
-- the code that produces the behavior users experience
-- the code that gets shipped to production
-
-testcode = the builder's code
-- the code that verifies the behaviors users experience
-- the code that runs at build time to protect production

package/dist/logic/roles/mechanic/.briefs/patterns/lang.tones/.readme.md

@@ -1,3 +0,0 @@
-briefs on what tones to use in writing goes here
-
-tones impact how things are thought about, so they are important to curate

package/dist/logic/roles/mechanic/.briefs/style.compressed.md

@@ -1,29 +0,0 @@
-// style:tactics (compressed)
-
-- name:ubiqlang
-  - use one canonical term per concept (e.g., always use `customer`, never `client`, `user`, or `account`)
-  - eliminate overloads: each term must refer to exactly one thing (e.g., do not use `update` for both "save" and "fetch")
-  - when introducing a new term:
-    - define its interface and role
-    - document its meaning clearly
-    - ensure consistent usage across code, docs, and tests
-
-- name:treestruct
-  - for mechanisms (procedures, steps, transforms), use `[Verb][NounHierarchy]` format
-    - verb must come first and be atomic (e.g., `gen`, `set`, `get`, `map`, `submit`)
-    - examples: `genStepImagineViaTemplate`, `setCustomerPhone`
-  - for resources (records, results), use `[NounHierarchy][State]?` format
-    - `State` is optional and should clarify the form or phase (e.g., `Found`, `Updated`, `Draft`, `Final`)
-    - examples: `contentFound`, `invoiceDraft`, `customer`
-  - group nouns by domain to maintain treesorted file and symbol organization
-
-- words:lowercase
-  - use lowercase for all non-code text (comments, prompts, markdown, logs)
-  - never capitalize:
-    - the start of a sentence
-    - generic nouns (`customer`, `step`)
-    - verbs (`set`, `submit`, `handle`)
-    - system messages or instructions
-  - only capitalize:
-    - code symbols (e.g., `StitchStepImagine`, `GitRepo`)
-    - proper nouns or brand names (e.g., OpenAI, GitHub)

package/dist/logic/roles/mechanic/.briefs/style.compressed.prompt.md

@@ -1,5 +0,0 @@
-compress these three style tactics for use in prompt context
-
-retain references to the tactics each section came from, so that it can always be dereferenced
-
-use outline form with each tactic a root bullet