rhachet-roles-ehmpathy 1.13.2 → 1.13.3

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.errors.failfast/best-practice/require.fail_fast.md

@@ -0,0 +1,28 @@
+fail fast saves lives
+
+when you fail fast, you detect fast, and you fix fast
+
+this contributes to a pit of success
+- enables tests to alert when unexpected behaviors occur, detected at build time
+- enables logs to alert when unexpected behaviors occur, detected at monitor time
+=>
+- this allows us to more safely develop => as any surprises will be flagged asap, loud and proud
+- this allows us to more rapidly maintain => as any changes live in production will be flagged asap, loud and proud
+
+---
+
+specifically, you should choose from
+
+```ts
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+throw new UnexpectedCodePathError(message, metadata)
+```
+
+or
+
+```ts
+import { BadRequestError } from 'helpful-errors';
+
+throw new BadRequestError(message, metadata)
+```

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.narrative/bad-practices/forbid.else.md

@@ -0,0 +1,54 @@
+else is a code REAK
+
+its not even a smell
+
+its such a bad smell that it reaks
+
+---
+
+else's can _always_ be better rewriten as an IFFE+EarlyReturn
+
+---
+
+see the narrative flow breifs for more context on the desired goal
+
+
+-------
+
+e.g.,
+
+> no if else; only early returns; else is a code REAK
+
+● You're right - the if/else violates the flow:narrative tactic. Let me
+  refactor to use early returns only:
+
+● Update(src/domain.operations/vpcTunnel/setVpcTunnel.ts)
+  ⎿  Updated src/domain.operations/vpcTunnel/setVpcTunnel.ts with 5
+     additions and 3 removals
+       81      if (portInUse) {
+       82        const cacheFilePresent = await isFilePresent({ path:
+            cachePath });
+       83
+       84 +      // port used by unknown process; kill it to reclaim
+       85 +      if (!cacheFilePresent) {
+       86 +        killProcessOnPort({ port: input.from.port });
+       87 +      }
+       88 +
+       89        // check if existing tunnel is ours and healthy
+       90        if (cacheFilePresent) {
+       91          const cacheContent = await fs.readFile(cachePath,
+            'utf-8');
+     ...
+       100          // cleanup stale tunnel
+       101          if (isProcessAlive({ pid: cache.pid }))
+             process.kill(cache.pid, 'SIGTERM');
+       102          await fs.rm(cachePath, { force: true });
+       103 -      } else {
+       104 -        // port used by another process; kill it to reclaim
+       105 -        killProcessOnPort({ port: input.from.port });
+       103        }
+       104      }
+       105
+
+● Removed the else block - now both conditions are independent if statements
+   with no branching maze.

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.narrative/best-practice/early-returns.named-checks.[demo].md

@@ -0,0 +1,181 @@
+
+● The check now walks up the prototype chain starting from error.constructor, checking if any class in the
+  inheritance hierarchy is named 'BadRequestError'. This handles cases where a custom error class extends
+  BadRequestError (or extends something that extends it, etc.).
+
+> lets actually create a new constant called "isExtensionOfBadRequestError"
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 4 additions and 2 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       11 -    const isNamedAfterBadRequestError = (() => {
+       12 -      let proto = error.constructor;
+       11 +    const isNamedAfterBadRequestError =
+       12 +      error.constructor.name === 'BadRequestError';
+       13 +    const isExtensionOfBadRequestError = (() => {
+       14 +      let proto = Object.getPrototypeOf(error.constructor);
+       15        while (proto) {
+       16          if (proto.name === 'BadRequestError') return true;
+       17          proto = Object.getPrototypeOf(proto);
+
+● Now I need to add the new constant to the return statement:
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 1 addition and 1 removal
+       18        }
+       19        return false;
+       20      })();
+       21 -    return isInstanceOfBadRequestError || isNamedAfterBadRequestError;
+       21 +    return isInstanceOfBadRequestError || isNamedAfterBadRequestError
+          +   || isExtensionOfBadRequestError;
+       22    };
+       23
+       24    /**
+
+● Done. Now decideIsBadRequestError has three separate checks:
+
+  1. isInstanceOfBadRequestError - uses instanceof check
+  2. isNamedAfterBadRequestError - checks if the error's constructor is named 'BadRequestError'
+  3. isExtensionOfBadRequestError - walks up the prototype chain to check if any parent class is named
+  'BadRequestError'
+
+> add a header comment for each constant
+  ⎿  Found 1 new diagnostic issue in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 11 additions and 1 removal
+        7     * .what = procedure for deciding whether an error is a bad request error
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10 +    // check if the error is an instance of BadRequestError
+       11      const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       12 +
+       13 +    // check if the error's constructor is named 'BadRequestError'
+       14      const isNamedAfterBadRequestError =
+       15        error.constructor.name === 'BadRequestError';
+       16 +
+       17 +    // check if any parent class in the prototype chain is named 'BadRequestError'
+       18      const isExtensionOfBadRequestError = (() => {
+       19        let proto = Object.getPrototypeOf(error.constructor);
+       20        while (proto) {
+     ...
+       18        }
+       19        return false;
+       20      })();
+       21 -    return isInstanceOfBadRequestError || isNamedAfterBadRequestError ||
+          - isExtensionOfBadRequestError;
+       21 +
+       22 +    return (
+       23 +      isInstanceOfBadRequestError ||
+       24 +      isNamedAfterBadRequestError ||
+       25 +      isExtensionOfBadRequestError
+       26 +    );
+       27    };
+       28
+       29    /**
+
+● Done. Added header comments for each constant and also fixed the formatting on the return statement to
+  satisfy the eslint rule.
+
+> use early returns after each check, rather than needoing to evalaute all three
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 8 additions and 16 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      // check if the error is an instance of BadRequestError
+       11 -    const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       11 +    if (error instanceof BadRequestError) return true;
+       12
+       13      // check if the error's constructor is named 'BadRequestError'
+       14 -    const isNamedAfterBadRequestError =
+       15 -      error.constructor.name === 'BadRequestError';
+       14 +    if (error.constructor.name === 'BadRequestError') return true;
+       15
+       16      // check if any parent class in the prototype chain is named 'BadRequestError'
+       17 -    const isExtensionOfBadRequestError = (() => {
+       18 -      let proto = Object.getPrototypeOf(error.constructor);
+       19 -      while (proto) {
+       20 -        if (proto.name === 'BadRequestError') return true;
+       21 -        proto = Object.getPrototypeOf(proto);
+       22 -      }
+       23 -      return false;
+       24 -    })();
+       17 +    let proto = Object.getPrototypeOf(error.constructor);
+       18 +    while (proto) {
+       19 +      if (proto.name === 'BadRequestError') return true;
+       20 +      proto = Object.getPrototypeOf(proto);
+       21 +    }
+       22
+       23 -    return (
+       24 -      isInstanceOfBadRequestError ||
+       25 -      isNamedAfterBadRequestError ||
+       26 -      isExtensionOfBadRequestError
+       27 -    );
+       23 +    return false;
+       24    };
+       25
+       26    /**
+
+● Done. Now the function uses early returns, so it short-circuits as soon as any check passes without needing
+  to evaluate the remaining checks.
+
+> header comment on the last return, too
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 1 addition
+       20        proto = Object.getPrototypeOf(proto);
+       21      }
+       22
+       23 +    // otherwise, not a bad request error
+       24      return false;
+       25    };
+       26
+
+● Done.
+
+> keep the names of the constants though; if (isXyz) is important for greater readability
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 14 additions and 7 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      // check if the error is an instance of BadRequestError
+       11 -    if (error instanceof BadRequestError) return true;
+       11 +    const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       12 +    if (isInstanceOfBadRequestError) return true;
+       13
+       14      // check if the error's constructor is named 'BadRequestError'
+       15 -    if (error.constructor.name === 'BadRequestError') return true;
+       15 +    const isNamedAfterBadRequestError =
+       16 +      error.constructor.name === 'BadRequestError';
+       17 +    if (isNamedAfterBadRequestError) return true;
+       18
+       19      // check if any parent class in the prototype chain is named 'BadRequestError'
+       20 -    let proto = Object.getPrototypeOf(error.constructor);
+       21 -    while (proto) {
+       22 -      if (proto.name === 'BadRequestError') return true;
+       23 -      proto = Object.getPrototypeOf(proto);
+       24 -    }
+       20 +    const isExtensionOfBadRequestError = (() => {
+       21 +      let proto = Object.getPrototypeOf(error.constructor);
+       22 +      while (proto) {
+       23 +        if (proto.name === 'BadRequestError') return true;
+       24 +        proto = Object.getPrototypeOf(proto);
+       25 +      }
+       26 +      return false;
+       27 +    })();
+       28 +    if (isExtensionOfBadRequestError) return true;
+       29
+       30      // otherwise, not a bad request error
+       31      return false;
+
+● Done. Now each check has a named constant (isInstanceOfBadRequestError, isNamedAfterBadRequestError,
+  isExtensionOfBadRequestError) followed by an early return, giving both readability and short-circuit
+  evaluation.

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/bad-practices/forbid.barrel.exports.ts.md

@@ -0,0 +1,41 @@
+this is an alias to ./forbid.index.ts.md
+
+NEVER do barrel exports
+
+e.g.,
+- `src/domain.objects/index.ts`
+- `src/domain.operations/organization/index.ts`
+- `src/domain.operations/organizationAccount/index.ts`
+- `src/access/daos/index.ts`
+- `src/contract/sdks/index.ts`
+
+all are banned
+
+they're just new aliases that increase
+- codepath variants
+- cyclical import chances
+
+totally forbidden
+
+they add zero value
+
+
+---
+
+the only thing that's allowed is
+
+within an index.ts file, exporting one object
+
+e.g.,
+
+```ts
+export const daoAwsOrganization = {
+  getOne,
+  getAll,
+  set,
+  del,
+}
+```
+nice and tight export
+
+but thats it. never just an export forwarder

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/bad-practices/forbid.index.ts.md

@@ -0,0 +1,3 @@
+the _only_ time an index.ts file is acceptable is if its
+1. the entrypoint of the public package, if this is a public package
+2. the entrypoint of a dao, if it is a dao

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.diagnose.[lesson].md

@@ -0,0 +1,14 @@
+if you have a failing test
+
+1. make the error super clear via
+   1. observable error messages
+   2. clear log trails
+
+2. when you detect which subcomponent has unexpected behavior
+   1. cover that subscomponent with tests of its own (unit, integration, etc)
+   2. if it does not have its own procedure, breakit out into its own procedure (own function + own file + own test suite)
+
+that way
+1. its easy to see exactly what is failing
+2. its easy to prove we fixed it (or verify that the behavior is / isnt expected)
+3. we can systematically track down the bug, one subcomponnent at a time

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