rhachet-roles-ehmpathy 1.8.0 → 1.9.0

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/best-practice/directional-dependencies.md

@@ -0,0 +1,82 @@
+.tactic = arch:directional-deps
+
+.what
+enforce strict top-down dependency flow across layered system boundaries — lower layers must never import from higher ones
+
+.scope
+- applies to all folders and modules within `src/`
+- required for `contract/`, `access/`, `domain.objects/`, `domain.operations/`
+- governs imports, module references, and stitched flow boundaries
+
+.why
+- upholds **separation of concerns** and enforces **clean architecture**
+- prevents circular dependencies and tangled system boundaries
+- makes each layer easier to test, replace, and understand in isolation
+- aligns with `arch:bounded-contexts` and enables predictable top-down orchestration
+
+.structure
+\`\`\`
+src/
+  contract/            // topmost — public interfaces, local commands
+    api/               // public invocable api endpoints, deployed and exposed by the project; e.g., via `aws-lambda`
+    cmd/               // private internal use entrypoints, supported by the project; e.g., via `as-command`
+    sdk/               // public software development kit exports, supported by the project; e.g., `export ...`
+    cli/               // public command line interface contracts, supported by the project; e.g., via `commander`
+
+  access/              // infrastructure layer (daos, sdks, svcs)
+    daos/              // private persistence logic — may reference domain objects
+    sdks/              // remote third party contracts, from any alt org — may declare their own domain.objects
+    svcs/              // remote first party contracts, from our own org — may declare their own domain.objects
+
+  domain.objects/      // canonical domain declarations
+  domain.operations/   // domain behavior + business rules
+
+  infra/               // infrastructure specific adapters
+\`\`\`
+
+.how
+- each layer may depend **only on the layers below it**
+  - `contract/` may depend on `domain.objects/` and `domain.operations/`
+  - `access/` may depend on `domain.objects/` and `domain.operations/`
+  - `domain.operations/` may depend on `domain.objects/` or `infra/`
+  - `domain.objects/` must not depend on anything outside its own layer
+  - `infra/` must not depend on anything outside its own layer
+
+- stitched flows live in `domain.operations/` or `contract/commands/` and orchestrate downstream only
+- never import upward across layers (e.g., `domain.objects/` importing `access/`)
+- shared types must follow the same directional rules
+
+.enforcement
+- imports that violate top-down boundary = **BLOCKER**
+- circular dependencies between layers = **BLOCKER**
+- logic in `domain.objects/` must never reach into `access/`, `contract/`, or `domain.operations/`
+- logic in `domain.operations/` must not reference infrastructure concerns; they can can only leverage `infra/` adapters
+- logic in `access/` may use domain layers but must remain free of domain knowledge and business rules
+- logic in `infra/` must remain free of domain knowledge and business rules
+
+.examples
+
+✅ positive
+\`\`\`ts
+// contract/endpoints/sendInvoice.ts
+import { generateInvoice } from '@/domain.operations/generateInvoice';
+import { invoiceDao } from '@/access/daos/invoiceDao';
+
+// access/daos/jobDao.ts
+import { Job } from '@/domain.objects/Job';
+
+// domain.operations/calculateTotal.ts
+import { LineItem } from '@/domain.objects/LineItem';
+\`\`\`
+
+❌ negative
+\`\`\`ts
+// domain.objects/Customer.ts
+import { customerDao } from '@/access/daos/customerDao'; // ⛔ illegal upward import
+
+// domain.operations/InvoiceOps.ts
+import { runFlow } from '@/contract/commands'; // ⛔ direction violation
+
+// access/svcs/sdkWrapper.ts
+import { dispatchFlow } from '@/contract/'; // ⛔ bottom-up reference
+\`\`\`

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/best-practice/dot-test-and-dot-temp.md

@@ -0,0 +1,20 @@
+prefer
+
+.temp/ directories over
+- tmp/
+- temp
+
+.test/ directories over
+- __test__
+- __fixtures__
+- __test_assets__
+- __test_utils__
+- etc
+
+---
+
+its easier on the eyes and more consistent with broader patterns
+
+---
+
+this is a NITPICK level violation

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.typescript.utils/best-practice/ref.package.as-command.[tips].md

@@ -0,0 +1,7 @@
+when using `@ehmpathy/as-command`, no need to manage output dirs yourslef
+
+simply use context.out.write()
+
+it will write to a dedicated, safe output dir
+
+---

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.acceptance/best-practice/blackbox.md

@@ -0,0 +1,5 @@
+
+acceptance tests are black box tests
+
+- no ability to assert internal details
+- only what's exposed through the @src/contract layer is accessible to acpt tests

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

@@ -0,0 +1,18 @@
+1. lookup the organization to use from declapract.use.yml
+2. declare the AWS_PROFILE based on the pattern `AWS_PROFILE=$organization.dev`
+   1. always use .dev, never .prod
+   2. this specifies which remote resources we'll have access to for the session
+   3. we always test against dev resources, to avoid prod pollution
+3. run npm run start:testdb (or provision:integration-test-db, if start:testdb is not available yet)
+   1. this setsup the local testdb against which the tests can be run
+
+then, you can run the tests you need to
+
+e.g.,
+
+AWS_PROFILE=$organization.dev npm run test:integration -- syncPhoneFromWhodis.integration.test.ts
+AWS_PROFILE=$organization.dev npm run test:unit -- syncPhoneFromWhodis.test.ts
+
+etc
+
+check package json for the other test variants you can run

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

@@ -0,0 +1,20 @@
+instead of rerunning tests over and over and getting the `head` to check what happened while preserving context
+
+its BEST
+
+to `| tee` into a `@gitroot/.log/test/(unit|integration|acceptance)/run.$ISOTIMESTAMP.out` file
+
+then you can review that file over and over
+
+also, other agents can review as well in parallel
+
+last, it can also be used to compare progress in changes of tests
+
+---
+
+so, pretty much ALWAYS, you should ` | tee` into one of these files
+
+
+===
+
+best practice is to run test via `.skills/run.test.sh`, which does this for you

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

@@ -0,0 +1,3 @@
+import { given, when, then, useBeforeAll } from 'test-fns';
+
+use those to declare the tests

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

@@ -0,0 +1,8 @@
+
+to create an integration test, just add a file with .integration.test.ts extension (collocated) and dont mock anything
+
+you can spy, but never mock
+
+---
+
+use the less on in src/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/howto.write.bdd.[lesson].md for preference on pattern

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

@@ -0,0 +1,9 @@
+
+for unit tests:
+
+only test that the behaviors explicitly important for that test
+
+no need to overtest, only whatever is scoped for that test and unique to it
+
+
+use the less on in src/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/howto.write.bdd.[lesson].md for preference on pattern

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

@@ -0,0 +1,280 @@
+# 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

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,185 @@
+# 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