declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.ts

@@ -0,0 +1,90 @@
+import { HelpfulError, UnexpectedCodePathError } from 'helpful-errors';
+import pg, { Client, type QueryResult, type QueryResultRow } from 'pg';
+
+import { getConfig } from '../config/getConfig';
+import { getEnvironment } from '../environment';
+
+// https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
+pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
+pg.types.setTypeParser(1700, (value) => parseFloat(value)); // cast numerics to numbers; by default, pg returns numerics as strings
+
+export interface DatabaseConnection {
+  query: <Row extends QueryResultRow>(args: {
+    sql: string;
+    values?: unknown[];
+  }) => Promise<QueryResult<Row>>;
+  end: () => Promise<void>;
+}
+
+export class DatabaseQueryError extends HelpfulError {
+  constructor({
+    sql,
+    values,
+    caught,
+  }: {
+    sql: string;
+    values?: unknown[];
+    caught: Error;
+  }) {
+    const message = `
+caught error querying database: ${caught.message}
+
+sql:
+  ${sql.trim()}
+
+values:
+  ${JSON.stringify(values)}
+    `.trim();
+    super(message, { sql, values, cause: caught });
+  }
+}
+
+export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> => {
+  const environment = await getEnvironment();
+  const config = await getConfig();
+  const target = config.database.target;
+  const role = config.database.role.crud;
+
+  // determine which tunnel to use based on environment.server
+  const tunnel =
+    environment.server === 'cloud@aws.lambda'
+      ? config.database.tunnel.lambda
+      : config.database.tunnel.local;
+
+  // ensure tunnel is defined for the requested server
+  if (!tunnel) {
+    throw new UnexpectedCodePathError(
+      `Database tunnel not configured for environment.server + env.access`,
+      { environment },
+    );
+  }
+
+  // instantiate the client
+  const client = new Client({
+    host: tunnel.host,
+    port: tunnel.port,
+    user: role.username,
+    password: role.password,
+    database: target.database,
+  });
+  await client.connect();
+  await client.query(`SET search_path TO ${target.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
+  const dbConnection = {
+    query: ({ sql, values }: { sql: string; values?: unknown[] }) =>
+      client.query(sql, values),
+    end: () => client.end(),
+  };
+
+  // declare our interface
+  return {
+    query: (args: { sql: string; values?: unknown[] }) =>
+      dbConnection.query(args).catch((error) => {
+        throw new DatabaseQueryError({
+          sql: args.sql,
+          values: args.values,
+          caught: error,
+        });
+      }),
+    end: () => dbConnection.end(),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseContext.ts

@@ -1,7 +1,7 @@
 import {
   DatabaseConnection,
-  getDatabaseConnection,
-} from './getDatabaseConnection';
+  getOneDatabaseConnection,
+} from './getOneDatabaseConnection';
 
 export interface DatabaseContext {
   dbConnection: DatabaseConnection;
@@ -32,11 +32,19 @@ export const withDatabaseContext = <P1, P2 extends DatabaseContext, R>(
   ) => {
     // open the db connection, if one was not given
     const dbConnection =
-      context.dbConnection ?? (await getDatabaseConnection());
+      context.dbConnection ?? (await getOneDatabaseConnection());
 
     // try and run the logic with db connection
     try {
-      return await logic(input, { ...context, dbConnection } as P2); // as P2 because: https://github.com/microsoft/TypeScript/issues/35858
+      // as-cast — why types miss: the input context is `Omit<P2,'dbConnection'> &
+      //   { dbConnection? }`; the spread `{ ...context, dbConnection }` re-adds a
+      //   NON-optional dbConnection, but ts cannot prove a spread of a generic
+      //   `Omit<P2,…> & {…}` reconstitutes the exact `P2` (microsoft/TypeScript#35858).
+      // correct type: the value IS `P2` — every P2 key is present (the omit dropped
+      //   only dbConnection, which the spread restores with a concrete connection).
+      // removal path: ts resolves spread-of-generic to the original type
+      //   (microsoft/TypeScript#35858), or the caller passes a fully-typed P2 in.
+      return await logic(input, { ...context, dbConnection } as P2);
     } finally {
       // make sure to close the db connection, both when `logic` throws an error or succeeds
       if (!context.dbConnection) await dbConnection.end();

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -1,13 +1,25 @@
-import type { DatabaseConnection } from './getDatabaseConnection';
+import type { DatabaseConnection } from './getOneDatabaseConnection';
 
+/**
+ * .what = wraps a logic fn so it runs inside one db transaction: START TRANSACTION,
+ *         run the logic, COMMIT on success, ROLLBACK + rethrow on failure. the
+ *         transaction rides the injected `context.dbConnection`.
+ * .why = gives any logic atomic semantics — every write commits together, or none
+ *        does — without each op repeating the begin/commit/rollback dance. a partial
+ *        write cannot survive a throw.
+ * .note = the wrapper is ALWAYS async — it awaits the transaction — so its honest
+ *         return type is `Promise<Awaited<R>>`, NOT `logic`'s `R | Promise<R>`. the
+ *         return type is declared explicitly so no `as` cast is needed and no type
+ *         lie is told: a caller of a sync `logic` correctly sees a Promise back.
+ */
 export const withDatabaseTransaction = <
   P,
   C extends { dbConnection: DatabaseConnection },
   R,
 >(
   logic: (input: P, context: C) => R | Promise<R>,
-): typeof logic => {
-  return (async (input: P, context: C) => {
+): ((input: P, context: C) => Promise<Awaited<R>>) => {
+  return async (input: P, context: C) => {
     await context.dbConnection.query({ sql: 'START TRANSACTION' }); // begin transaction
     try {
       const result = await logic(input, context); // run the request
@@ -17,5 +29,5 @@ export const withDatabaseTransaction = <
       await context.dbConnection.query({ sql: 'ROLLBACK' }); // rollback if not successful
       throw error;
     }
-  }) as typeof logic;
+  };
 };

package/dist/practices/persist-with-rds/deploy-database-gerunds.declapract.integration.test.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #549: the shipped provision/schema/deploy.database.sh carries no gerund
+ *         (-ing) progress-string, comment, or error — imperative/plain verbs only, per
+ *         rule.forbid.gerunds.
+ * .why  = this template is emitted verbatim to every persist-with-rds consumer, and each
+ *         consumer runs the mechanic gerund hook on the emitted file. a gerund in the
+ *         template trips that hook downstream, so each repo re-fixes it and re-diverges from
+ *         the template — the fix must live upstream, here, once.
+ * .teeth = revert any progress-string to its gerund form (e.g. "create the database" ->
+ *          "creating the database") in best-practice/provision/schema/deploy.database.sh and
+ *          the paired "no gerund" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the
+ *         practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('persist-with-rds deploy.database.sh gerund-free', () => {
+  given('the shipped deploy.database.sh', () => {
+    const source = readFileSync(
+      join(__dirname, 'best-practice/provision/schema/deploy.database.sh'),
+      'utf8',
+    );
+
+    // the exact gerund forms #549 removed; none may reappear in the template
+    const forbidden = [
+      'creating',
+      'installing',
+      'granting',
+      'before running this',
+    ];
+
+    when('the template body is read', () => {
+      forbidden.forEach((word) =>
+        then(`it carries no gerund form: "${word}"`, () => {
+          expect(source.includes(word)).toEqual(false);
+        }),
+      );
+
+      then('it keeps the imperative progress strings', () => {
+        expect(source).toContain('🔨 create the database...');
+        expect(source).toContain('🔨 install the extensions...');
+        expect(source).toContain('🔨 create the schema...');
+        expect(source).toContain('🔨 create the cicd user...');
+      });
+
+      then('the emitted deploy.database.sh matches snapshot', () => {
+        // snapshot the whole shipped file so a reworded progress string that stays
+        // gerund-free still reddens a vibecheck in review — the token asserts prove the
+        // gerund class is absent, this proves the exact text (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('deploy.database.sh');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/empty-template-declares-zero-clusters.declapract.integration.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the empty-template invariant the case=7 (stateful-store-alias-not-copy) safety
+ *         rests on: the persist-with-rds declastruct wish declares ZERO rds clusters — `getResources`
+ *         returns only SSM params, and the provision tree imports no cluster/rds/aurora/database
+ *         resource-declaration type.
+ * .why  = case=7's fail-safe is "a lambda under two names is two copies of code; a database under two
+ *         names must be one store with two pointers" — and its load-bearer is that the template holds
+ *         NO cluster for a `fix` to duplicate. a second cluster is the operator's to hand-author,
+ *         against the runbook, never a state the template produces. this is the demoed critipath's
+ *         real test (per `rule.require.experience-catalog-evolution`, a demoed critipath owes a test
+ *         by verification): if a future edit ever declares a cluster in the go-forward wish, the
+ *         "zero clusters to duplicate" premise silently breaks, and this reddens.
+ * .teeth = a cluster resource cannot enter `getResources` without an import of a `DeclaredAws*Cluster`
+ *          / `*Rds` / `*Aurora` / `*Database` type plus its addition to the returned array — so the
+ *          "declares only SSM params" + "imports no cluster type" cases redden the moment one lands.
+ * .note = `.integration.test.ts` because it reads the filesystem (a remote boundary); at the practice
+ *         ROOT (not under best-practice/), so it is neither loaded as a declaration nor copied to a
+ *         consumer. mirrors the source-text clamp in `ssm-cicd-param-names.declapract.integration.test.ts`.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+const resourcesPath = join(__dirname, 'best-practice/provision/aws/resources.ts');
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+// any declastruct-aws resource-declaration type that would name an rds/aurora cluster or database.
+// a cluster resource cannot be declared without one of these, so the negation is the teeth.
+const CLUSTER_TYPE_PATTERN = /Declared\w*(Rds|Cluster|Aurora|Database)/;
+
+describe('persist-with-rds wish declares zero rds clusters (empty-template invariant)', () => {
+  const resources = readFileSync(resourcesPath, 'utf8');
+  const params = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the wish entrypoint resources.ts', () => {
+    when('[t0] resources.ts is read', () => {
+      then('getResources yields only the ssm parameters', () => {
+        expect(resources).toContain('getAllParameters({ accessSlug: null })');
+      });
+
+      then('the wish imports no cluster/rds/aurora/database resource type', () => {
+        expect(resources).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+
+      then('the sole declared aws resource declaration is the ssm parameter secure', () => {
+        // the one resource-declaration import from declastruct-aws is DeclaredAwsSsmParameterSecure
+        // (via resources.parameters.ts). resources.ts itself declares no resource type directly.
+        expect(resources).not.toContain('DeclaredAwsRds');
+        expect(resources).not.toContain('DeclaredAwsAurora');
+      });
+    });
+  });
+
+  given('[case2] the resource set resources.parameters.ts', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('getAllParameters yields a DeclaredAwsSsmParameterSecure array (ssm params only)', () => {
+        expect(params).toContain('DeclaredAwsSsmParameterSecure[]');
+      });
+
+      then('the resource set declares no cluster/rds/aurora/database type', () => {
+        expect(params).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/provision-testdb-access.declapract.integration.test.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #563: the shipped provision:testdb chain sets ACCESS=test on every inner
+ *         provision:schema:* call, so a freshly-stamped repo can derive access and provision its
+ *         local testdb without a hand-edit.
+ * .why  = each schema call invokes sql-schema-control → getConfig() → getEnvironment.static(); with
+ *         no ACCESS in a local shell (no aws account alias / NODE_ENV that fits), every access parser
+ *         fails and it throws `could not derive access`. the local testdb always provisions the
+ *         `test` tier, so ACCESS=test is a constant here, not the cicd `${{ inputs.access }}`
+ *         interpolation the live-db path uses.
+ * .teeth = drop an `ACCESS=test` from any inner schema call in best-practice/package.json and the
+ *          "no bare schema call" assertion reddens (a bare `&& npm run provision:schema:` reappears).
+ * .note = the subject is the shipped TEMPLATE (best-practice/package.json, a CONTAINS check), read
+ *         from __dirname. this file sits at the practice ROOT, so declapract never emits it.
+ */
+describe('persist-with-rds provision:testdb access', () => {
+  given('the shipped best-practice package.json', () => {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+    );
+    const provisionTestdb: string = pkg.scripts['provision:testdb'];
+
+    when('the provision:testdb chain is read', () => {
+      then('each inner schema call carries ACCESS=test', () => {
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:plan',
+        );
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:apply',
+        );
+      });
+
+      then('no inner schema call runs without ACCESS (would throw could-not-derive)', () => {
+        // a bare `&& npm run provision:schema:` (not preceded by ACCESS=test) throws
+        // `could not derive access` in a local shell — the #563 defect
+        expect(provisionTestdb).not.toMatch(/&&\s*npm run provision:schema:/);
+      });
+
+      then('the emitted provision:testdb chain matches snapshot', () => {
+        // snapshot the shipped chain contract itself, so a reword that keeps the
+        // ACCESS=test tokens green (a re-ordered &&, a dropped command) reddens a vibecheck
+        expect(provisionTestdb).toMatchSnapshot('provision:testdb chain');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/ssm-cicd-param-names.declapract.integration.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the ssm-off-terraform wish declares the two cicd credentials as SLASH paths
+ *         with NO tier segment, while the crud credential keeps its dotted tier-scoped name.
+ * .why  = the prod plan role pins its ONE `kms:Decrypt` exception to a slash arn
+ *         (`parameter/*​/svc-*​/database/role/cicd/for-plan/*`) that needs literal `/` separators
+ *         and omits a tier (the aws ACCOUNT separates prep from prod, never the name). a dotted
+ *         name cannot match that arn, so the plan role gets ciphertext or a denial, forever, and
+ *         a repo does not find out until prod (#591). the shipped `ahbode/svc-home-services` proved
+ *         the slash form; this clamp ports it into the practice so no consumer inherits the dotted
+ *         cicd name again. crud is pinned by NO policy, so it keeps its dotted name and this clamp
+ *         leaves it alone.
+ * .teeth = revert either cicd entry to the dotted `${namespace}.database.role.cicd.for-plan.password`
+ *          form and the slash-present case reddens; the no-dotted-cicd case reddens too.
+ * .note = `.declapract.test.ts` = this repo's UNIT-test marker; at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/persist-with-rds/) the best-practice tree is one segment down.
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+describe('persist-with-rds ssm cicd param names are slash-path, tierless', () => {
+  const source = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the two cicd credentials', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('for-plan is a slash path, byte-identical to the iam pin', () => {
+        expect(source).toContain('/database/role/cicd/for-plan/password');
+      });
+
+      then('for-apply is a slash path', () => {
+        expect(source).toContain('/database/role/cicd/for-apply/password');
+      });
+
+      then('neither cicd name is dotted (a dotted name cannot match the arn pin)', () => {
+        expect(source).not.toContain('.database.role.cicd.for-plan');
+        expect(source).not.toContain('.database.role.cicd.for-apply');
+      });
+
+      then('the cicd slash path carries no tier segment (project joins /database directly)', () => {
+        // /{org}/{project}/database/... — a tier segment would split project from database
+        expect(source).toContain('projectName}/database/role/cicd/for-plan/password');
+        expect(source).not.toContain('${slug}/database/role/cicd');
+      });
+
+      // the emitted param-name lines are the caller-faced contract: snapshot them so a reword that
+      // keeps the slash tokens green (a re-templated prefix, a moved tier segment) reddens a vibecheck.
+      then('the emitted cicd + crud param-name lines match snapshot', () => {
+        const nameLines = source
+          .split('\n')
+          .filter((line) => line.includes('database/role/cicd') || line.includes('database.role.'))
+          .map((line) => line.trim());
+        expect(nameLines).toMatchSnapshot('ssm cicd + crud param names');
+      });
+    });
+  });
+
+  given('[case2] the crud credential', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('crud keeps its dotted tier-scoped name (no policy pins it)', () => {
+        expect(source).toContain('${namespace}.database.role.crud.password');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/testdb-preflight-failloud.declapract.integration.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the testdb preflight probe (#589) to fail LOUD, not hide
+ * .why  = the prior probe swallowed psql stderr (`> /dev/null 2>&1`), printed one
+ *         hardcoded diagnosis regardless of the true cause, and passed the secret
+ *         inline in the connection string (which leaks it to `ps`). so a bad
+ *         password, a port conflict, and an image build failure all read the same,
+ *         and the real cause never surfaced on timeout.
+ * .teeth = revert the fix (restore `> /dev/null 2>&1` + the inline password + the
+ *          single hardcoded line) and each `then` below goes red.
+ * .note  = a `.declapract.test.ts` at the practice ROOT is a UNIT-test marker — it is
+ *          not loaded as a declaration nor copied to a consumer. it anchors on
+ *          __dirname (not process.cwd()) so it reads the shipped template directly.
+ */
+
+const source = readFileSync(
+  join(
+    __dirname,
+    'best-practice/provision/docker/testdb/wait-for-postgres.sh',
+  ),
+  'utf8',
+);
+
+describe('testdb preflight fails loud (#589)', () => {
+  given('the shipped wait-for-postgres preflight probe', () => {
+    when('[t0] it runs the psql probe', () => {
+      then('it does not swallow the probe stderr to /dev/null', () => {
+        expect(source).not.toContain('/dev/null');
+      });
+
+      then('it captures the probe stderr for surfacing on timeout', () => {
+        expect(source).toContain('lasterr=$(psql');
+        expect(source).toContain('2>&1');
+      });
+    });
+
+    when('[t1] the probe fails past the timeout', () => {
+      then('it echoes the captured last error to stderr', () => {
+        expect(source).toContain('>&2 echo "$lasterr"');
+      });
+
+      then('it no longer prints only the one hardcoded diagnosis', () => {
+        expect(source).not.toContain('postgres too long');
+      });
+    });
+
+    when('[t2] it authenticates to postgres', () => {
+      then('it passes the secret via PGPASSWORD, not inline in the connstring', () => {
+        // the secret rides PGPASSWORD (never the connstring, which leaks to `ps`), and
+        // the env read uses the safe-default form per rule.require.safe-shell-vars
+        expect(source).toContain('export PGPASSWORD="${POSTGRES_PASSWORD:-}"');
+        expect(source).not.toContain('password=$POSTGRES_PASSWORD');
+      });
+    });
+
+    when('[t3] a consumer shell runs it under nounset', () => {
+      then('it opens with set -eu so an unset env fails loud, not silent', () => {
+        expect(source).toContain('set -eu');
+      });
+
+      then('it reads every optional env var with the ${VAR:-} default form', () => {
+        // no bare "$VAR" env read survives: under set -u a bare read is an unbound-variable
+        // crash; the :- default keeps a loud, correct connect attempt instead
+        expect(source).not.toContain('"$POSTGRES_PASSWORD"');
+        expect(source).not.toContain('dbname=$POSTGRES_DB ');
+        expect(source).toContain('${POSTGRES_DB:-}');
+      });
+    });
+
+    when('[t4] the shipped probe is vibechecked as a whole', () => {
+      then('the emitted wait-for-postgres.sh matches snapshot', () => {
+        // snapshot the whole shipped probe so a reword that keeps the pinned tokens green
+        // (a reshaped psql invocation, a rephrased echo, a moved PGPASSWORD export) reddens a
+        // vibecheck in review — the tokens above prove presence, this proves the exact text
+        // (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('wait-for-postgres.sh preflight probe');
+      });
+    });
+  });
+});