declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/deploy.database.sh

@@ -0,0 +1,97 @@
+#####################################################
+## initialize the database in a live cluster
+## - in other words, it does all of the things that docker does for us when we spin up a cluster without the db already
+## - i.e.,
+##    - create the database
+##    - install the extensions
+##    - creates the schema
+##    - creates the cicd user
+##    - grants the cicd user ownership of the db
+## - note:
+##   - requires pg admin access
+##   - requires _you_ to change the passwords in prod manually
+##
+## usage example:
+## ```sh
+## ./provision/schema/deploy.database.sh prep $(op item get ahbodedb.prep.postgres --fields label=password --format json | jq -r .value)
+## ```
+#####################################################
+
+set -eu
+
+# check that the human has defined the environment that they want this key created for correctly
+ENVIRONMENT="${1:-}";
+if [ "$ENVIRONMENT" != "prod" ] && [ "$ENVIRONMENT" != "prep" ]; then
+  echo "\nerror: environment, the first argument, must be specified as either 'prod' or 'prep'. you specified '$ENVIRONMENT'";
+  exit 2;
+fi
+
+# check that the human is authed into correct account
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account');
+EXPECTED_AWS_ACCOUNT_ID=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.awsAccountId.prod}" || echo "@declapract{variable.awsAccountId.prep}");
+if [ "$AWS_ACCOUNT_ID" != "$EXPECTED_AWS_ACCOUNT_ID" ]; then
+  echo "\nerror: the AWS_ACCOUNT that you are signed into is not correct for the environment you specified. you are authed into account '$AWS_ACCOUNT_ID' but the correct account id for '$ENVIRONMENT' is '$EXPECTED_AWS_ACCOUNT_ID'";
+  exit 2;
+fi
+
+# check that pg admin password was specified
+POSTGRES_ADMIN_PASSWORD="${2:-}"
+if [ -z "${POSTGRES_ADMIN_PASSWORD:-}" ]; then
+  echo "\nerror: POSTGRES_ADMIN_PASSWORD must be defined as second arg";
+  exit 2;
+fi;
+
+# check that the cicd password was provisioned, if in prod, since this is used to create the cicd user
+# note: this reads the legacy DOTTED param name (`....database.role.cicd.password`), a live consumer
+#       distinct from the slash-path plan/apply secrets. it is the prod cicd-user bootstrap credential
+#       and stays alive on purpose — do not prune it as an unreferenced legacy param.
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_PASSWORD=$(aws ssm get-parameter --name "@declapract{variable.organizationName}.@declapract{variable.projectName}.$ENVIRONMENT.database.role.cicd.password" --with-decryption --output text --query Parameter.Value)
+  if [ -z "${CICD_USER_PASSWORD:-}" ]; then
+    echo "\nerror: CICD_USER_PASSWORD must be provisioned with terraform before you run this"
+    exit 2;
+  fi;
+  if [ "$CICD_USER_PASSWORD" = "__IGNORED__" ] || [ "$CICD_USER_PASSWORD" = "__CHANG3_ME__" ]; then
+    echo "\nerror: CICD_USER_PASSWORD must be set to a value other than the default placeholder"
+    exit 2;
+  fi;
+fi;
+
+
+# define the postgres connection string
+CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseTunnelHost.prod}" || echo "@declapract{variable.databaseTunnelHost.prep}");
+CLUSTER_CONNECTION_STRING=postgresql://postgres:$POSTGRES_ADMIN_PASSWORD@$CLUSTER_HOST:5432
+ROOT_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/postgres
+SVC_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/@declapract{variable.databaseName}
+
+# define path to the init sqls
+SRC_PATH=$(readlink --canonicalize "$0");
+SRC_DIR=$(dirname $SRC_PATH);
+INIT_SQLS_DIR=$SRC_DIR/sql/init;
+
+# run the create database command on root db
+echo "\n 🔨 create the database..."
+psql $ROOT_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.database.sql
+
+echo "\n 🔨 install the extensions..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.extensions.sql
+
+echo "\n 🔨 create the schema..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.schema.sql
+
+if [ "$ENVIRONMENT" = "prod" ]; then
+  echo "\n 🔨 grant reads to the datalakedb user..." # only in prod env; we dont want prep's test data in our datalake
+  psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.user.datalakedb.sql
+fi;
+
+echo "\n 🔨 create the cicd user..."
+CICD_USER_CREATE_SQL_PATH=$INIT_SQLS_DIR/.user.cicd.sql
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_CREATE_SQL_PATH_TEMP=$CICD_USER_CREATE_SQL_PATH.tmp # in prod, we must create a temp file which will have the actual password we'll use to create the cicd user
+  cat $CICD_USER_CREATE_SQL_PATH | sed "s/__CHANG3_ME__/${CICD_USER_PASSWORD}/" > $CICD_USER_CREATE_SQL_PATH_TEMP # create the temp file w/ the actual password
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH_TEMP # run the temp create sql w/ the actual password
+  rm $CICD_USER_CREATE_SQL_PATH_TEMP # remove the temp file, so the password doesn't get checked in
+else
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH # otherwise, we can run the file directly. no password replacement required
+fi
+echo "\n 🎉 done"

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.database.sql

@@ -0,0 +1,10 @@
+/**
+ * this command creates the database that the service will use
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a db to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE DATABASE @declapract{variable.databaseName};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql

@@ -0,0 +1,16 @@
+/**
+ * postgres databases use extensions to increase functionality
+ * - we have a minimum set of extensions that are required for sql-schema-generator
+ * - services may also include their own extensions if they want additional functionality
+ * - this is not managed by sql-schema-control
+ *   - requires superuser privileges, cicd user only has db_owner privileges
+ * - this is applied
+ *   - automatically for integration-test db (through `provision/docker/.../init/` directory, with files cp'd by npm provision scripts)
+ *   - by the deployment script for live deployments
+ */
+
+-- extensions required for all sql-schema-generator resources:
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- extensions required for custom use cases in this service:

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql.declapract.ts

@@ -0,0 +1,37 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+const grabCreateExtensionLinesFromContents = (contents: string) =>
+  contents
+    .split('\n')
+    .filter((line) => line.startsWith('CREATE EXTENSION IF NOT EXISTS'));
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // if the file doesn't exist, create what we want to see - with an additional example of how it can be extended
+  if (!contents)
+    return {
+      contents: `${context.declaredFileContents!.trim()}\n-- CREATE EXTENSION IF NOT EXISTS ...`,
+    };
+
+  // if the file does exist, then find all the custom create extension lines
+  const requiredCreateExtensionLines = grabCreateExtensionLinesFromContents(
+    context.declaredFileContents!,
+  );
+  const foundCreateExtensionLines =
+    grabCreateExtensionLinesFromContents(contents);
+  const foundCustomCreateExtensionLines = foundCreateExtensionLines.filter(
+    (foundCreateExtensionLine) =>
+      !requiredCreateExtensionLines.some((requiredCreateExtensionLine) =>
+        foundCreateExtensionLine.includes(requiredCreateExtensionLine),
+      ), // if this found create-extension statement is not a required one, then its custom
+  );
+
+  // and set the contents equal to what we want to see + their custom ones
+  return {
+    contents: [
+      context.declaredFileContents!.trim(),
+      ...foundCustomCreateExtensionLines,
+    ].join('\n'),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.schema.sql

@@ -0,0 +1,11 @@
+/**
+ * this command creates the schema that the service + sql-schema-control will use
+ * - this command must be run inside of the database that was created for this service
+ * - this creates a schema with the same name as the database
+ * - this not managed by sql-schema-control
+ *   - sql-schema-control needs a schema to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+*/
+CREATE SCHEMA @declapract{variable.databaseName};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.cicd.sql

@@ -0,0 +1,14 @@
+/**
+ * creates a cicd user, with total control over the database and the schema, to be used by sql-schema-control
+ * - full control required since it'll be managing all resources for this db
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a user to run _under_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE USER @declapract{variable.databaseUserName.cicdUser} WITH PASSWORD '__CHANG3_ME__'; -- create cicd user
+ALTER DATABASE @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the database
+ALTER SCHEMA @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the schema, too
+ALTER USER @declapract{variable.databaseUserName.cicdUser} WITH CREATEROLE; -- allow the cicd user to create other users

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.datalakedb.sql

@@ -0,0 +1,12 @@
+/**
+ * grants read access to `datalakedb_federated_query_reader` so that we can query this db from redshift
+ * - this not managed by sql-schema-control
+ *   - since it does not apply in integration test environment (since that user wont exist there)
+ * - this is applied
+ *   - by the deployment script for live deployments
+ */
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+GRANT SELECT ON ALL TABLES IN SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT ON TABLES TO datalakedb_federated_query_reader;
+
+-- don't forget to hop into the datalakedb and add the ext_@declapract{variable.databaseName}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/default_transaction_isolation.sql

@@ -0,0 +1,6 @@
+/**
+ * we want `read-committed` as the default txn isolation level on our databases
+ * - its _required_ to support high concurrency operations for the upserts generated by `sql-schema-generator`
+ * - this is done automatically by sql-schema-control under the cicd user
+ */
+ALTER DATABASE @declapract{variable.databaseName} SET DEFAULT_TRANSACTION_ISOLATION TO 'read committed';

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/user.service.sql

@@ -0,0 +1,16 @@
+/**
+ * the service user has maximally restricted permissions
+ * - this is the user that the service will be using to interact with the database
+ * - insert only, baby!
+ */
+CREATE USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__CHANG3_ME__';
+-- ALTER USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__actual_password__';
+
+-- grant usage
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO @declapract{variable.databaseUserName.serviceUser};
+
+-- grant specific privileges to resources in the schema, for all created now and onward (i.e., all)
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT, INSERT, UPDATE ON TABLES TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT EXECUTE ON FUNCTIONS TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT USAGE, SELECT ON SEQUENCES TO @declapract{variable.databaseUserName.serviceUser};
+

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml

@@ -0,0 +1,9 @@
+- type: change
+  id: init_default_txn_isolation
+  author: declapract
+  path: ./init/default_transaction_isolation.sql
+
+- type: change
+  id: init_service_user
+  author: declapract
+  path: ./init/user.service.sql

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // contains since the user may have exclusions in that "for" object

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+
+/** .what = the two oidc grant scopes config can be read under. */
+export type Grant = 'plan' | 'apply';
+
+/**
+ * .what = get the config schema for a given oidc grant.
+ * .why = the prod plan job's oidc role is DENIED every ssm secret except the
+ *        for-plan db credential. under grant=plan the
+ *        eagerly-read getConfig() cannot read for-apply's password (or any other
+ *        secret); sdk-config substitutes undefined for each denied param, so those
+ *        must be .optional() to tolerate the miss. grant=apply (the default — apply
+ *        job, cloud runtime, local dev, tests) keeps every secret REQUIRED, so its
+ *        inferred type carries no `| undefined` and needs no guards at consumers.
+ * .note = grant is a per-schema arg, NOT read from env here; getConfig picks which
+ *         schema to parse with at call time (see getConfig.ts).
+ */
+const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
+  // required by default; optional only under grant=plan. generic on the LITERAL
+  // TGrant so each schema infers monomorphically (all-required for apply,
+  // reader-denied-optional for plan) instead of the widened union.
+  const secret = <T extends z.ZodTypeAny>(
+    schema: T,
+  ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
+    // as-cast — why types miss: TS cannot relate a conditional return type
+    //   (`TGrant extends 'plan' ? … : …`) to a runtime `grant === 'plan'`
+    //   ternary; the two are unrelated to the checker, so the ternary widens to
+    //   `ZodOptional<T> | T` and does not fit the declared conditional return.
+    // correct type: the value IS `ZodOptional<T>` when TGrant='plan' and `T`
+    //   otherwise — exactly the declared return; the runtime branch matches the
+    //   type branch one-to-one, so the assertion is sound.
+    // removal path: TS learns to relate a conditional return type to a runtime
+    //   discriminant check (microsoft/TypeScript#33912), or the caller splits
+    //   into two monomorphic overloads that never share this body.
+    (grant === 'plan' ? schema.optional() : schema) as TGrant extends 'plan'
+      ? z.ZodOptional<T>
+      : T;
+
+  return z.object({
+    organization: z.string(),
+    project: z.string(),
+    environment: z.object({
+      access: z.enum(['test', 'prep', 'prod']),
+    }),
+    aws: z.object({
+      account: z.string(),
+      namespace: z.string(),
+    }),
+    database: z.object({
+      target: z.object({
+        database: z.string(),
+        schema: z.string(),
+      }),
+      role: z.object({
+        cicd: z.object({
+          // for-plan and for-apply may map to DIFFERENT db users (e.g. a readonly
+          // user for-plan), so each carries its own username. names mirror the prod
+          // oidc roles (for-plan / for-apply) that read them.
+          // .note: only for-apply's PASSWORD is reader-denied under grant=plan; the
+          // username is a readable static, so the object is always present. mark the
+          // password itself as the secret (a secret() on the whole object would never
+          // tolerate the miss — the present object still validates its required password).
+          'for-plan': z.object({ username: z.string(), password: z.string() }),
+          'for-apply': z.object({
+            username: z.string(),
+            password: secret(z.string()),
+          }),
+        }),
+        crud: z.object({
+          username: z.string(),
+          password: secret(z.string()),
+        }),
+      }),
+      tunnel: z.object({
+        bastion: z.object({ exid: z.string() }).optional(),
+        cluster: z.object({ name: z.string() }).optional(),
+        local: z.object({
+          host: z.string(),
+          port: z.number(),
+        }),
+        lambda: z
+          .object({
+            host: z.string(),
+            port: z.number(),
+          })
+          .nullable(),
+      }),
+    }),
+  });
+};
+
+/**
+ * .what = one schema per grant. apply = every secret required (the default);
+ *         plan = the reader-denied secrets optional.
+ * .why = getConfig picks which to parse with by grant (see getConfig.ts).
+ */
+export const schema = {
+  apply: getOneSchema('apply'),
+  plan: getOneSchema('plan'),
+} as const;
+
+/**
+ * .what = the config type for a grant, default apply.
+ * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
+ *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
+ *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
+ */
+export type Config<TGrant extends Grant = 'apply'> = z.infer<
+  (typeof schema)[TGrant]
+>;

package/dist/{practices/persist-with-rds/best-practice/src/utils/database/getDatabaseConnection.integration.test.ts → .test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.integration.test.ts}

@@ -1,8 +1,8 @@
-import { getDatabaseConnection } from './getDatabaseConnection';
+import { getOneDatabaseConnection } from './getOneDatabaseConnection';
 
-describe('getDatabaseConnection', () => {
+describe('getOneDatabaseConnection', () => {
   it('should be able to connect and execute a query', async () => {
-    const dbConnection = await getDatabaseConnection();
+    const dbConnection = await getOneDatabaseConnection();
     const result = await dbConnection.query({ sql: 'select 1' });
     expect(result.rows.length).toEqual(1);
     await dbConnection.end();

package/dist/{practices/persist-with-rds/best-practice/src/utils/database/getDatabaseConnection.ts → .test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.ts}

@@ -39,7 +39,7 @@ values:
   }
 }
 
-export const getDatabaseConnection = async (): Promise<DatabaseConnection> => {
+export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> => {
   const environment = await getEnvironment();
   const config = await getConfig();
   const target = config.database.target;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseContext.ts

@@ -0,0 +1,53 @@
+import {
+  DatabaseConnection,
+  getOneDatabaseConnection,
+} from './getOneDatabaseConnection';
+
+export interface DatabaseContext {
+  dbConnection: DatabaseConnection;
+}
+
+/**
+ * wraps the function to provide a managed database connection to it's context, if one was not already passed in
+ *
+ * note
+ * - manages the database connection it gives to the function by opening it and closing it once the function finishes
+ * - if a database connection was passed in as part of the arguments, it will instead use that one and will not close it once it finishes (useful for transactions)
+ *
+ * example usage:
+ * ```
+ *   const findById = withDatabaseContext(({ id }: { id: string }, context: { dbConnection: DatabaseConnection }) => {
+ *     // do logic with dbConnection
+ *   });
+ *   // ...
+ *   await findById({ id: 821 }); // note how we don't have to pass in the dbConnection
+ * ```
+ */
+export const withDatabaseContext = <P1, P2 extends DatabaseContext, R>(
+  logic: (input: P1, context: P2) => R | Promise<R>,
+) => {
+  return async (
+    input: P1,
+    context: Omit<P2, 'dbConnection'> & { dbConnection?: DatabaseConnection },
+  ) => {
+    // open the db connection, if one was not given
+    const dbConnection =
+      context.dbConnection ?? (await getOneDatabaseConnection());
+
+    // try and run the logic with db connection
+    try {
+      // 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/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -0,0 +1,33 @@
+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>,
+): ((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
+      await context.dbConnection.query({ sql: 'COMMIT' }); // commit if successful
+      return result;
+    } catch (error) {
+      await context.dbConnection.query({ sql: 'ROLLBACK' }); // rollback if not successful
+      throw error;
+    }
+  };
+};

package/dist/.test/assets/cicd-service/declarations/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/.test/assets/cicd-service/declarations/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/.test/assets/cicd-service/declarations/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');
+      });
+    });
+  });
+});