@deployfoundation/foundation-deploy 0.2.51 → 0.2.53

package/src/deploy/cli.ts

@@ -35,6 +35,9 @@ export const COMMANDS = [
   "slack-manifest",
   "stage-customization",
   "job-key",
+  "crm-key",
+  "crm-check",
+  "crm-replay",
 ] as const;
 
 export type Command = (typeof COMMANDS)[number];
@@ -56,6 +59,12 @@ commands
   slack-manifest       print the instance's Slack app manifest as JSON
   stage-customization  validate and stage a tenant-owned runtime config
   job-key <id>         print a webhook job's URL and signing key as JSON
+  crm-key              write the company CRM's crm/1 key, read from stdin, into
+                       the instance's <secretPrefix>/crm/http secret
+  crm-check            run the crm/1 conformance suite against the instance's
+                       CRM (crm.provider kind http) with its stored key
+  crm-replay           replay the agent's CRM writes (JSONL) into the
+                       instance's own table after a rollback to dynamodb
 
 options
   --instance <path>    REQUIRED: path to the deployment's instance YAML
@@ -91,6 +100,24 @@ job-key options
   --put-secret <id>    write {url, key} into this Secrets Manager secret
                        (created if absent) instead of printing the key
 
+crm-key options
+  --stdin              REQUIRED: read the key from a pipe, never argv, e.g.
+                       pbpaste | foundation-deploy crm-key --instance <path> --stdin
+
+crm-check options
+  --allow-skips        pass despite cases only a person can set up (they need
+                       the CRM's own harness); without it they count as failed
+  --base-url <url>     check any crm/1 server instead of the instance's: needs
+  --tenant <id>        the tenant its /meta names, and the key on stdin
+  --key-stdin          (--key-stdin). No --instance in this form.
+  --write              with --base-url only: also run the write cases, which
+                       create records and spend the week's outreach allowance;
+                       point it at a sandbox tenant
+
+crm-replay options
+  --from <file>        REQUIRED: the writes to replay, one JSON object per line
+                       (docs/crm-provider-contract.md); --dry-run validates only
+
 github-app-create options
   --org <org>          GitHub org (default: the instance's github.org)
   --port <n>           local callback port (default 8765)
@@ -199,6 +226,27 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
     return 0;
   }
 
+  // A CRM's own CI checks its server with the published tool and no instance
+  // file at all: everything the suite needs is a flag, and the key a pipe.
+  if (command === "crm-check" && args.includes("--base-url")) {
+    if (args.some((arg) => arg === "--instance" || arg.startsWith("--instance=")))
+      throw new Error("crm-check takes --instance or --base-url, not both");
+    const baseUrl = flag(args, "--base-url");
+    const tenantId = flag(args, "--tenant");
+    if (baseUrl === undefined || tenantId === undefined || !args.includes("--key-stdin"))
+      throw new Error("crm-check --base-url needs --tenant <id> and --key-stdin");
+    const { crmCheckTarget, defaultCrmCommandDeps } = await import("./crm.ts");
+    return crmCheckTarget(
+      {
+        baseUrl,
+        tenantId,
+        write: args.includes("--write"),
+        allowSkips: args.includes("--allow-skips"),
+      },
+      defaultCrmCommandDeps(),
+    );
+  }
+
   if (command === "github-app-create") {
     const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
     console.log(instanceBanner(paths));
@@ -270,6 +318,29 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
       console.log(`  ${result.status}: ${result.runtimeConfigPath}`);
       return 0;
     }
+    // Loaded on demand: the CRM commands bring the conformance suite and,
+    // for a replay, the AWS SDK's DynamoDB client.
+    case "crm-key": {
+      const { crmKey, defaultCrmCommandDeps } = await import("./crm.ts");
+      await crmKey(ctx, { stdin: args.includes("--stdin") }, defaultCrmCommandDeps());
+      return 0;
+    }
+    case "crm-check": {
+      if (args.includes("--write"))
+        throw new Error(
+          "crm-check --write creates records and spends the week's outreach allowance, so it never runs against the instance's own tenant: use --base-url with a sandbox tenant",
+        );
+      const { crmCheck, defaultCrmCommandDeps } = await import("./crm.ts");
+      return crmCheck(ctx, { allowSkips: args.includes("--allow-skips") }, defaultCrmCommandDeps());
+    }
+    case "crm-replay": {
+      const from = flag(args, "--from");
+      if (from === undefined || from.startsWith("-"))
+        throw new Error("crm-replay needs --from <file>: the writes to replay, as JSONL");
+      const { crmReplay, defaultCrmCommandDeps } = await import("./crm.ts");
+      const result = await crmReplay(ctx, { from }, defaultCrmCommandDeps());
+      return result.refused.length > 0 ? 1 : 0;
+    }
     default:
       console.error(`unhandled command: ${command}\n\n${USAGE}`);
       return 1;

package/src/deploy/crm.ts

@@ -0,0 +1,491 @@
+/**
+ * The operator's side of a company's own CRM (`crm.provider` kind `http`,
+ * docs/crm-provider-contract.md):
+ *
+ *   foundation-deploy crm-key    --instance <path> --stdin
+ *   foundation-deploy crm-check  --instance <path> [--allow-skips]
+ *   foundation-deploy crm-check  --base-url <url> --tenant <id> --key-stdin [--write] [--allow-skips]
+ *   foundation-deploy crm-replay --instance <path> --from <writes.jsonl> [--dry-run]
+ *
+ * - `crm-key` writes the `crm/1` key into the secret FoundationData created
+ *   empty. The key arrives on a pipe and goes to the AWS CLI through a 0600
+ *   temp file: never argv, never shell history, never printed.
+ * - `crm-check` runs the `crm/1` conformance suite. Against the instance it
+ *   uses the deployment's base URL, tenant and stored key and runs only the
+ *   read cases, since the write cases create records and spend the week's
+ *   outreach allowance. With `--base-url` (no instance at all) it is what a
+ *   CRM's own CI runs against a sandbox tenant, `--write` included. Strict
+ *   unless `--allow-skips`: a case only a person can set up counts as failed
+ *   when it could not run.
+ * - `crm-replay` is the rollback half of a cutover: once `crm.provider` is
+ *   back on `dynamodb`, it writes the agent's writes made in the company's CRM
+ *   since the cutover (exported as JSONL) into the instance's own table,
+ *   through the same DynamoDB store the proxy uses, under the deployment's
+ *   policy. Drafts move each contact's touch clock but are not counted again:
+ *   the shared ledger counted them when they happened.
+ *
+ * A CRM reply body never reaches this output: the suite reports fixed text,
+ * codes and statuses only, and a refused replay line is reported by its line
+ * number and refusal code.
+ */
+import { readFileSync } from "node:fs";
+import type {
+  CrmConformanceReport,
+  CrmConformanceTarget,
+} from "@deployfoundation/foundation-capability-crm/contract/conformance";
+import {
+  CrmIdempotencyConflictError,
+  CrmRecordNotFoundError,
+} from "@deployfoundation/foundation-capability-crm/proxy/errors";
+import {
+  type CrmOutreachPolicy,
+  CrmPolicyRefusedError,
+} from "@deployfoundation/foundation-capability-crm/proxy/policy";
+import type { CrmDocumentClient } from "@deployfoundation/foundation-capability-crm/proxy/repository";
+import {
+  CRM_MAX_ID_CHARS,
+  CrmInputError,
+  type CrmLogActivityArgs,
+  type CrmRecordType,
+  type CrmUpdateStatusArgs,
+  type CrmUpsertRecordsArgs,
+  parseCrmLogActivityArgs,
+  parseCrmUpdateStatusArgs,
+  parseCrmUpsertRecordsArgs,
+} from "@deployfoundation/foundation-connectors/crm";
+import { crmHttpBaseUrl, isCrmHttpKey } from "@deployfoundation/foundation-connectors/crm-http";
+import {
+  type CrmCapabilityConfig,
+  type InstanceConfig,
+  crmOutreachConfigured,
+  parseInstanceConfig,
+} from "@deployfoundation/foundation-core";
+import { type AwsContext, aws, putSecretString, readSecretString, secretExists } from "./aws.ts";
+
+/** What these commands reach outside the process; tests replace every one. */
+export interface CrmCommandDeps {
+  /** Everything on stdin, or a refusal when stdin is a terminal (it would echo). */
+  readStdin: () => Promise<string>;
+  secretExists: (ctx: AwsContext, secretId: string) => Promise<boolean>;
+  putSecretString: (ctx: AwsContext, secretId: string, value: string) => Promise<void>;
+  readSecretString: (ctx: AwsContext, secretId: string) => Promise<string>;
+  runConformance: (target: CrmConformanceTarget) => Promise<CrmConformanceReport>;
+  /** The physical name of the instance's CRM table. */
+  crmTableName: (ctx: AwsContext) => Promise<string>;
+  /** A DocumentClient on the operator's own credentials. */
+  documentClient: (ctx: AwsContext) => Promise<CrmDocumentClient>;
+  readFile: (path: string) => string;
+  log: (line: string) => void;
+}
+
+/** The deployment's `http` provider, or a refusal naming what is missing. */
+function httpProvider(ctx: AwsContext, command: string) {
+  const { instance } = ctx;
+  const provider = instance.crm.provider;
+  if (!instance.integrations.crm || provider.kind !== "http")
+    throw new Error(
+      `${command} needs crm.provider kind http (and integrations.crm) in ${ctx.paths.path}; the DynamoDB provider has no CRM key or base URL`,
+    );
+  return provider;
+}
+
+// --- crm-key ---------------------------------------------------------------
+
+export interface CrmKeyResult {
+  secret: string;
+}
+
+/**
+ * Write the `crm/1` key from stdin into `<secretPrefix>/crm/http`. The secret
+ * must exist (FoundationData creates it on the first deploy with the `http`
+ * provider), so a typo in the instance cannot create a stray secret.
+ */
+export async function crmKey(
+  ctx: AwsContext,
+  options: { stdin: boolean },
+  deps: CrmCommandDeps,
+): Promise<CrmKeyResult> {
+  httpProvider(ctx, "crm-key");
+  const secret = ctx.names.secretCrmHttp;
+  if (!options.stdin)
+    throw new Error(
+      "crm-key reads the key from stdin only, so it never lands in argv or shell history: pipe it in with --stdin, e.g. `pbpaste | foundation-deploy crm-key --instance <path> --stdin`",
+    );
+  const key = (await deps.readStdin()).trim();
+  if (!isCrmHttpKey(key))
+    throw new Error(
+      "stdin did not hold a usable crm/1 key: 16 to 1024 visible ASCII characters, no spaces, one per run",
+    );
+  if (!(await deps.secretExists(ctx, secret)))
+    throw new Error(
+      `secret ${secret} does not exist yet: deploy with crm.provider kind http first, which creates it empty`,
+    );
+  await deps.putSecretString(ctx, secret, JSON.stringify({ api_key: key }));
+  deps.log(
+    `wrote the crm/1 key to ${secret}. The CRM proxy reads it within 5 minutes, or at once after a 401. Check it with: foundation-deploy crm-check --instance ${ctx.paths.path}`,
+  );
+  return { secret };
+}
+
+// --- crm-check -------------------------------------------------------------
+
+export interface CrmCheckOptions {
+  allowSkips: boolean;
+}
+
+/**
+ * The suite's read cases against the deployment's CRM, with its stored key,
+ * tenant and baked policy. Returns the process exit code.
+ */
+export async function crmCheck(
+  ctx: AwsContext,
+  options: CrmCheckOptions,
+  deps: CrmCommandDeps,
+): Promise<number> {
+  const provider = httpProvider(ctx, "crm-check");
+  const secret = ctx.names.secretCrmHttp;
+  let apiKey: unknown;
+  try {
+    const raw = JSON.parse(await deps.readSecretString(ctx, secret)) as unknown;
+    if (typeof raw === "object" && raw !== null && "api_key" in raw) apiKey = raw.api_key;
+  } catch {
+    // Unreadable or not JSON: the same as no key, reported below.
+  }
+  if (!isCrmHttpKey(apiKey))
+    throw new Error(`${secret} holds no crm/1 key yet: run foundation-deploy crm-key first`);
+  const crm = crmCapability(instanceConfig(ctx, deps));
+  const report = await deps.runConformance({
+    baseUrl: provider.baseUrl,
+    apiKey,
+    tenantId: provider.expectedTenant,
+    strict: !options.allowSkips,
+    ...(crm === undefined
+      ? {}
+      : {
+          statusPolicy: crm.statusPolicy,
+          ...(crmOutreachConfigured(crm.outreach)
+            ? { suppressedStatuses: crm.outreach.suppressedStatuses }
+            : {}),
+        }),
+  });
+  return reportConformance(report, provider.baseUrl, deps.log);
+}
+
+export interface CrmCheckTargetOptions extends CrmCheckOptions {
+  baseUrl: string;
+  tenantId: string;
+  write: boolean;
+}
+
+/**
+ * The suite against any `crm/1` server, no instance involved: what a CRM's
+ * own CI runs from the published tool. The key comes from stdin.
+ */
+export async function crmCheckTarget(
+  options: CrmCheckTargetOptions,
+  deps: Pick<CrmCommandDeps, "readStdin" | "runConformance" | "log">,
+): Promise<number> {
+  let baseUrl: string;
+  try {
+    baseUrl = crmHttpBaseUrl(options.baseUrl);
+  } catch {
+    // The connector's own message says only that it must be HTTPS.
+    throw new Error("--base-url must be an HTTPS URL with no userinfo, query or fragment");
+  }
+  if (!/^[\x21-\x7e]{1,256}$/.test(options.tenantId))
+    throw new Error("--tenant must be the tenant id the server's /meta names");
+  const apiKey = (await deps.readStdin()).trim();
+  if (!isCrmHttpKey(apiKey)) throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+  const report = await deps.runConformance({
+    baseUrl,
+    apiKey,
+    tenantId: options.tenantId,
+    write: options.write,
+    strict: !options.allowSkips,
+  });
+  return reportConformance(report, baseUrl, deps.log);
+}
+
+function reportConformance(
+  report: CrmConformanceReport,
+  baseUrl: string,
+  log: (line: string) => void,
+): number {
+  log(`crm/1 conformance against ${baseUrl}`);
+  for (const entry of report.cases) {
+    const mark = entry.outcome === "fail" ? "FAIL" : entry.outcome;
+    log(
+      `  ${mark.padEnd(4)}  ${entry.id}: ${entry.title}${entry.detail === undefined ? "" : ` (${entry.detail})`}`,
+    );
+  }
+  log(`${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
+  return report.failed > 0 ? 1 : 0;
+}
+
+function instanceConfig(ctx: AwsContext, deps: Pick<CrmCommandDeps, "readFile">): InstanceConfig {
+  return parseInstanceConfig(deps.readFile(ctx.paths.configPath));
+}
+
+/** The instance's `capabilities.crm`, when it is on. */
+function crmCapability(config: InstanceConfig): CrmCapabilityConfig | undefined {
+  const crm = config.capabilities.crm;
+  return crm.enabled ? crm : undefined;
+}
+
+// --- crm-replay ------------------------------------------------------------
+
+/**
+ * One write in a replay file, one JSON object per line:
+ *
+ *   {"op":"upsert_records","idempotencyKey":"…","companies":[…],"contacts":[…]}
+ *   {"op":"update_status","idempotencyKey":"…","recordType":"contact","externalId":"…","status":"…"}
+ *   {"op":"log_activity","idempotencyKey":"…","recordType":"contact","externalId":"…",
+ *    "activityType":"…","summary":"…","occurredAt":"…","attributes":{…}}
+ *
+ * Records are named by `externalId`, which both providers share; the
+ * DynamoDB store derives its own record id from it.
+ */
+export type CrmReplayWrite =
+  | { line: number; op: "upsert_records"; args: CrmUpsertRecordsArgs }
+  | { line: number; op: "update_status"; args: CrmUpdateStatusArgs }
+  | { line: number; op: "log_activity"; args: CrmLogActivityArgs };
+
+export interface CrmReplayResult {
+  applied: number;
+  refused: { line: number; op: CrmReplayWrite["op"]; code: string }[];
+}
+
+const REPLAY_OPS = ["upsert_records", "update_status", "log_activity"] as const;
+
+/**
+ * Parse and validate a whole replay file against the deployment's CRM
+ * policy. Nothing is written unless every line passes, so a file this cannot
+ * replay (a status the deployment does not have, an operation it does not
+ * take) is fixed before anything changes. Errors name the line and the rule,
+ * never its content.
+ */
+export function parseCrmReplay(
+  text: string,
+  crm: CrmCapabilityConfig,
+  recordIdFor: (recordType: CrmRecordType, externalId: string) => string,
+): CrmReplayWrite[] {
+  const writes: CrmReplayWrite[] = [];
+  const statuses = {
+    company: new Set(crm.statuses.company),
+    contact: new Set(crm.statuses.contact),
+  };
+  const activityTypes = new Set(crm.activityTypes);
+  text.split("\n").forEach((raw, index) => {
+    const line = index + 1;
+    if (raw.trim() === "") return;
+    let value: unknown;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      // JSON.parse quotes the offending text; the line number is enough.
+      throw new Error(`line ${line} is not a JSON object`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+      throw new Error(`line ${line} is not a JSON object`);
+    const { op, externalId, ...rest } = value as Record<string, unknown>;
+    if (typeof op !== "string" || !(REPLAY_OPS as readonly string[]).includes(op))
+      throw new Error(`line ${line}: op must be one of ${REPLAY_OPS.join(", ")}`);
+    try {
+      if (op === "upsert_records") {
+        if (externalId !== undefined) throw new Error("upsert_records names records inside");
+        writes.push({ line, op, args: parseCrmUpsertRecordsArgs(rest, crm.maxBatchSize) });
+        return;
+      }
+      if (
+        typeof externalId !== "string" ||
+        externalId.trim() === "" ||
+        externalId.length > CRM_MAX_ID_CHARS
+      )
+        throw new Error(`externalId must be 1 to ${CRM_MAX_ID_CHARS} characters`);
+      // An id is a provider's own; only the externalId means the same record in both.
+      if (Object.hasOwn(rest, "recordId"))
+        throw new Error("records are named by externalId, never by a provider's recordId");
+      const recordType = rest.recordType;
+      if (recordType !== "company" && recordType !== "contact")
+        throw new Error("recordType must be company or contact");
+      const named = { ...rest, recordId: recordIdFor(recordType, externalId) };
+      if (op === "update_status") {
+        const args = parseCrmUpdateStatusArgs(named);
+        if (!statuses[args.recordType].has(args.status))
+          throw new Error(`status is not a configured ${args.recordType} status`);
+        writes.push({ line, op, args });
+        return;
+      }
+      const args = parseCrmLogActivityArgs(named);
+      if (!activityTypes.has(args.activityType))
+        throw new Error("activityType is not a configured activity type");
+      writes.push({ line, op: "log_activity", args });
+    } catch (error) {
+      // Parser and rule messages name the rule, never the value.
+      throw new Error(`line ${line}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  return writes;
+}
+
+/**
+ * Replay a file of the agent's CRM writes into the instance's own table.
+ * Each line keeps its idempotency key, so running the same file twice writes
+ * nothing new. A write the policy refuses (a status change a later one made
+ * stale, a contact already drafted) is reported and the rest go on; any
+ * other failure stops at that line.
+ */
+export async function crmReplay(
+  ctx: AwsContext,
+  options: { from: string },
+  deps: CrmCommandDeps,
+): Promise<CrmReplayResult> {
+  const { instance } = ctx;
+  if (!instance.integrations.crmStorage)
+    throw new Error(
+      `crm-replay needs the instance's CRM table (integrations.crm) in ${ctx.paths.path}`,
+    );
+  if (instance.crm.provider.kind !== "dynamodb")
+    throw new Error(
+      "crm-replay writes into the DynamoDB provider's table: set crm.provider back to kind dynamodb, deploy, then replay",
+    );
+  const config = instanceConfig(ctx, deps);
+  const crm = crmCapability(config);
+  if (crm === undefined || crm.statuses.company.length === 0 || crm.statuses.contact.length === 0)
+    throw new Error(`${ctx.paths.configPath}: crm-replay needs capabilities.crm with its statuses`);
+  // Loaded here, not at the top: it brings the AWS SDK's DynamoDB client,
+  // which no other command needs.
+  const { createDynamoCrmClient, deterministicRecordId } = await import(
+    "@deployfoundation/foundation-capability-crm/proxy/repository"
+  );
+  const writes = parseCrmReplay(deps.readFile(options.from), crm, deterministicRecordId);
+  const counts = REPLAY_OPS.map(
+    (op) => `${writes.filter((write) => write.op === op).length} ${op}`,
+  ).join(", ");
+  if (ctx.dryRun === true) {
+    deps.log(`dry run: ${writes.length} writes would be replayed (${counts})`);
+    return { applied: 0, refused: [] };
+  }
+  const outreach: CrmOutreachPolicy | undefined = crmOutreachConfigured(crm.outreach)
+    ? { ...crm.outreach, timezone: config.timezone }
+    : undefined;
+  const client = createDynamoCrmClient({
+    documentClient: await deps.documentClient(ctx),
+    tableName: await deps.crmTableName(ctx),
+    // The tenant the CRM proxy serves: the instance's name, as it bakes it.
+    tenantId: instance.name,
+    defaultStatuses: {
+      company: crm.statuses.company[0] as string,
+      contact: crm.statuses.contact[0] as string,
+    },
+    maxBatchSize: crm.maxBatchSize,
+    actor: {
+      teamId: instance.slack.teamId,
+      userId: "foundation-deploy",
+      channelId: "crm-replay",
+      sessionKey: `crm-replay:${instance.name}`,
+    },
+    statusPolicy: crm.statusPolicy,
+    ...(outreach === undefined ? {} : { outreach }),
+    countsOutreach: false,
+  });
+  deps.log(`replaying ${writes.length} writes (${counts})`);
+  const result: CrmReplayResult = { applied: 0, refused: [] };
+  for (const write of writes) {
+    try {
+      if (write.op === "upsert_records") await client.upsertRecords(write.args);
+      else if (write.op === "update_status") await client.updateStatus(write.args);
+      else await client.logActivity(write.args);
+      result.applied += 1;
+    } catch (error) {
+      const code = replayRefusal(error);
+      if (code === undefined)
+        throw new Error(
+          `line ${write.line} (${write.op}) failed: ${error instanceof Error ? error.name : "error"}; lines before it were replayed, and rerunning the file skips them`,
+        );
+      result.refused.push({ line: write.line, op: write.op, code });
+    }
+  }
+  deps.log(`${result.applied} applied, ${result.refused.length} refused`);
+  for (const refused of result.refused)
+    deps.log(`  line ${refused.line} (${refused.op}): ${refused.code}`);
+  return result;
+}
+
+/** The fixed code for a write the store refused, or undefined for a failure. */
+function replayRefusal(error: unknown): string | undefined {
+  if (error instanceof CrmPolicyRefusedError) return error.code;
+  if (error instanceof CrmRecordNotFoundError) return "not_found";
+  if (error instanceof CrmIdempotencyConflictError) return "conflict";
+  if (error instanceof CrmInputError) return "invalid_input";
+  return undefined;
+}
+
+// --- production dependencies ------------------------------------------------
+
+/** Every byte on stdin; refuses a terminal, where the key would be echoed. */
+async function readPipedStdin(): Promise<string> {
+  if (process.stdin.isTTY === true)
+    throw new Error(
+      "stdin is a terminal, where the key would be echoed: pipe it in instead, e.g. `pbpaste | foundation-deploy …`",
+    );
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk as Uint8Array));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** The CRM table FoundationData created; its name is CloudFormation's. */
+async function crmTableNameFromStack(ctx: AwsContext): Promise<string> {
+  const names = (
+    await aws(ctx, [
+      "cloudformation",
+      "describe-stack-resources",
+      "--stack-name",
+      ctx.names.data,
+      "--query",
+      "StackResources[?ResourceType=='AWS::DynamoDB::Table' && starts_with(LogicalResourceId, 'CrmTable')].PhysicalResourceId",
+      "--output",
+      "text",
+    ])
+  )
+    .split(/\s+/)
+    .filter((name) => name !== "" && name !== "None");
+  if (names.length !== 1)
+    throw new Error(
+      `expected one CRM table in ${ctx.names.data}, found ${names.length}: is integrations.crm deployed?`,
+    );
+  return names[0] as string;
+}
+
+async function operatorDocumentClient(ctx: AwsContext): Promise<CrmDocumentClient> {
+  const [{ DynamoDBClient }, { DynamoDBDocumentClient }] = await Promise.all([
+    import("@aws-sdk/client-dynamodb"),
+    import("@aws-sdk/lib-dynamodb"),
+  ]);
+  return DynamoDBDocumentClient.from(
+    new DynamoDBClient({
+      region: ctx.region,
+      ...(ctx.profile === "" ? {} : { profile: ctx.profile }),
+    }),
+    { marshallOptions: { removeUndefinedValues: true } },
+  );
+}
+
+export function defaultCrmCommandDeps(): CrmCommandDeps {
+  return {
+    readStdin: readPipedStdin,
+    secretExists,
+    putSecretString,
+    readSecretString,
+    runConformance: async (target) => {
+      const { runCrmConformance } = await import(
+        "@deployfoundation/foundation-capability-crm/contract/conformance"
+      );
+      return runCrmConformance(target);
+    },
+    crmTableName: crmTableNameFromStack,
+    documentClient: operatorDocumentClient,
+    readFile: (path) => readFileSync(path, "utf8"),
+    log: (line) => console.log(line),
+  };
+}

package/src/deploy/runtime-secret.ts

@@ -12,6 +12,7 @@ import {
   instanceNames as namesFor,
   slackCommandPrefix,
 } from "@deployfoundation/foundation-core/instance";
+import { mongoCollectionPolicyEnv } from "@deployfoundation/foundation-core/mongodb-collections";
 
 /** The pinned AgentCore endpoint a deploy promotes and the invoker calls. */
 export const LIVE_ENDPOINT = "live";
@@ -258,6 +259,14 @@ export function composeRuntimeSecret(inputs: RuntimeSecretInputs): Record<string
     // LAZILY, so a secret still holding the CDK placeholder costs nothing
     // until someone asks a MongoDB question.
     FOUNDATION_MONGODB_SECRET_ID: names.secretMongodbReadonly,
+    // Collections the MongoDB tools refuse beyond the compiled-in defaults,
+    // from the instance file and never from config.yaml, so only a reviewed
+    // deploy changes it. Absent when the instance file adds nothing: the
+    // defaults hold without it.
+    ...(instance.mongodbReadonly.deniedCollections.length > 0 ||
+    instance.mongodbReadonly.unsafeReadDefaultDeniedCollections.length > 0
+      ? { FOUNDATION_MONGODB_COLLECTION_POLICY: mongoCollectionPolicyEnv(instance.mongodbReadonly) }
+      : {}),
     // CRM storage, the Otter credential, the Knock OAuth secrets, and the
     // Upwork/E*TRADE OAuth secrets are intentionally absent here: the
     // shell-capable agent receives only their fixed proxy ARNs.