@deployfoundation/foundation-deploy 0.2.53 → 0.2.55

package/dist/{chunk-1pww63wd.js → chunk-ztrhakgc.js}

@@ -3,8 +3,8 @@ import {
   putSecretString,
   readSecretString,
   secretExists
-} from "./chunk-nvsj7bbw.js";
-import"./chunk-fjdgxw8h.js";
+} from "./chunk-345e0grd.js";
+import"./chunk-pmjbzsq3.js";
 import {
   CrmIdempotencyConflictError,
   CrmRecordNotFoundError
@@ -12,27 +12,30 @@ import {
 import {
   crmHttpBaseUrl,
   isCrmHttpKey
-} from "./chunk-m76jt5rc.js";
+} from "./chunk-hvntk8p5.js";
 import {
   CrmPolicyRefusedError
-} from "./chunk-p7zkm4pp.js";
+} from "./chunk-caqstrxb.js";
 import {
   CRM_MAX_ID_CHARS,
   CrmInputError,
   parseCrmLogActivityArgs,
   parseCrmUpdateStatusArgs,
   parseCrmUpsertRecordsArgs
-} from "./chunk-3614v9rr.js";
+} from "./chunk-xt9gdsa0.js";
 import {
+  RawCrmStatusPolicy,
+  RawCrmStatusesByType,
   crmOutreachConfigured,
   parseInstanceConfig
-} from "./chunk-96fjaysn.js";
+} from "./chunk-rvx0cncy.js";
 import {
   __require
 } from "./chunk-5wgwscd0.js";
 
 // src/deploy/crm.ts
 import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
 function httpProvider(ctx, command) {
   const { instance } = ctx;
   const provider = instance.crm.provider;
@@ -78,6 +81,11 @@ async function crmCheck(ctx, options, deps) {
   });
   return reportConformance(report, provider.baseUrl, deps.log);
 }
+var STDIN_KEYS = [
+  { flag: "--key-stdin", name: "the crm/1 key" },
+  { flag: "--readonly-key-stdin", name: "the read-only key" },
+  { flag: "--harness-key-stdin", name: "the harness key" }
+];
 async function crmCheckTarget(options, deps) {
   let baseUrl;
   try {
@@ -87,20 +95,86 @@ async function crmCheckTarget(options, deps) {
   }
   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 writeInputs = [
+    ["--harness-url", options.harnessUrl !== undefined],
+    ["--readonly-key-stdin", options.readOnlyKeyStdin === true],
+    ["--status-policy", options.statusPolicyFile !== undefined],
+    ["--suppressed-statuses", options.suppressedStatusesFile !== undefined],
+    ["--spend-weekly-allowance", options.spendWeeklyAllowance === true]
+  ].filter(([, given]) => given).map(([flag]) => flag);
+  if (!options.write && writeInputs.length > 0)
+    throw new Error(`${writeInputs.join(", ")} only feed the write cases: add --write, against a sandbox tenant`);
+  const { createCrmHttpHarness, crmHarnessUrl } = await import("./chunk-gpq7e1kq.js");
+  let harnessUrl;
+  try {
+    harnessUrl = options.harnessUrl === undefined ? undefined : crmHarnessUrl(options.harnessUrl);
+  } catch {
+    throw new Error("--harness-url must be an HTTPS URL with no userinfo, query or fragment");
+  }
+  const statusPolicy = options.statusPolicyFile === undefined ? undefined : deploymentInput(deps, "--status-policy", options.statusPolicyFile, RawCrmStatusPolicy);
+  const suppressedStatuses = options.suppressedStatusesFile === undefined ? undefined : deploymentInput(deps, "--suppressed-statuses", options.suppressedStatusesFile, RawCrmStatusesByType);
+  const wanted = STDIN_KEYS.filter(({ flag }) => flag === "--key-stdin" || flag === "--readonly-key-stdin" && options.readOnlyKeyStdin === true || flag === "--harness-key-stdin" && harnessUrl !== undefined);
+  const keys = stdinKeys(await deps.readStdin(), wanted);
+  const key = (flag) => keys[wanted.findIndex((entry) => entry.flag === flag)];
+  const apiKey = key("--key-stdin");
+  const readOnlyApiKey = key("--readonly-key-stdin");
+  const harnessKey = key("--harness-key-stdin");
+  const harness = harnessUrl === undefined || harnessKey === undefined ? undefined : createCrmHttpHarness({
+    url: harnessUrl,
+    apiKey: harnessKey,
+    tenantId: options.tenantId,
+    fetchImpl: deps.fetch
+  });
   const report = await deps.runConformance({
     baseUrl,
     apiKey,
     tenantId: options.tenantId,
     write: options.write,
-    strict: !options.allowSkips
+    strict: !options.allowSkips,
+    ...readOnlyApiKey === undefined ? {} : { readOnlyApiKey },
+    ...statusPolicy === undefined ? {} : { statusPolicy },
+    ...suppressedStatuses === undefined ? {} : { suppressedStatuses },
+    ...options.spendWeeklyAllowance === true ? { spendWeeklyAllowance: true } : {},
+    ...harness === undefined ? {} : { harness }
   });
-  return reportConformance(report, baseUrl, deps.log);
+  return reportConformance(report, baseUrl, deps.log, harnessUrl);
+}
+function stdinKeys(text, wanted) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== "");
+  if (wanted.length === 1) {
+    if (lines.length !== 1 || !isCrmHttpKey(lines[0]))
+      throw new Error("stdin did not hold a usable crm/1 key (--key-stdin)");
+    return lines;
+  }
+  if (lines.length !== wanted.length)
+    throw new Error(`stdin must hold ${wanted.length} keys, one per line: ${wanted.map(({ name, flag }) => `${name} (${flag})`).join(", then ")}; it held ${lines.length}`);
+  lines.forEach((line, index) => {
+    const entry = wanted[index];
+    if (!isCrmHttpKey(line))
+      throw new Error(`stdin line ${index + 1}, ${entry.name} (${entry.flag}), is not a usable key: 16 to 1024 visible ASCII characters, no spaces`);
+  });
+  return lines;
+}
+function deploymentInput(deps, flag, path, schema) {
+  let text;
+  try {
+    text = deps.readFile(path);
+  } catch {
+    throw new Error(`${flag} ${path} could not be read`);
+  }
+  let value;
+  try {
+    value = parseYaml(text);
+  } catch {
+    throw new Error(`${flag} ${path} is not JSON or YAML`);
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success)
+    throw new Error(`${flag} ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "(top level)"}: ${issue.message}`).join("; ")}`);
+  return parsed.data;
 }
-function reportConformance(report, baseUrl, log) {
-  log(`crm/1 conformance against ${baseUrl}`);
+function reportConformance(report, baseUrl, log, harnessUrl) {
+  log(`crm/1 conformance against ${baseUrl}${harnessUrl === undefined ? "" : `, harness ${harnessUrl}`}`);
   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})`}`);
@@ -181,7 +255,7 @@ async function crmReplay(ctx, options, 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`);
-  const { createDynamoCrmClient, deterministicRecordId } = await import("./chunk-mh1206ne.js");
+  const { createDynamoCrmClient, deterministicRecordId } = await import("./chunk-7k4e3d7n.js");
   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) {
@@ -282,12 +356,13 @@ function defaultCrmCommandDeps() {
     putSecretString,
     readSecretString,
     runConformance: async (target) => {
-      const { runCrmConformance } = await import("./chunk-jf5rw6h4.js");
+      const { runCrmConformance } = await import("./chunk-p6yjbtqz.js");
       return runCrmConformance(target);
     },
     crmTableName: crmTableNameFromStack,
     documentClient: operatorDocumentClient,
     readFile: (path) => readFileSync(path, "utf8"),
+    fetch: (input, init) => fetch(input, init),
     log: (line) => console.log(line)
   };
 }

package/dist/src/crm-conformance.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Declarations for `@deployfoundation/foundation-deploy/crm-conformance`
+ * (src/crm-conformance.ts): the `crm/1` conformance suite. Self-contained on
+ * purpose: the source behind them is bundled from workspace packages that are
+ * never published. test/crm-conformance-export.test.ts fails the typecheck
+ * when these and the source drift apart.
+ *
+ * docs/crm-provider-contract.md#conformance describes each option.
+ */
+
+/** A fetch the suite sends every request through; default the global `fetch`. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type CrmRecordType = "company" | "contact";
+
+/** The agent's allowed status changes on one record type. */
+export interface CrmStatusRule {
+  /** From each status, the statuses the agent may move a record to. No entry, no exit. */
+  agentTransitions: Readonly<Record<string, readonly string[]>>;
+  /** Apply `personSet` to a status a person set; otherwise who set it does not matter. */
+  respectHumanChanges: boolean;
+  /** `advance`: only forward along `ladder`. `lock`: never. */
+  personSet: "lock" | "advance";
+  /** The evidence ladder, earliest status first. */
+  ladder: readonly string[];
+}
+
+/** Absent for a record type, any configured status of that type may be set. */
+export type CrmStatusPolicy = Readonly<Partial<Record<CrmRecordType, CrmStatusRule>>>;
+
+/** What only a person can do in a CRM, done directly by the server's own test code. */
+export interface CrmConformanceHarness {
+  /** Set a record's status as a person would: stamps `person`, bumps statusVersion. */
+  setStatusAsPerson(recordType: CrmRecordType, recordId: string, status: string): Promise<void>;
+  /** Set the do-not-contact flag on a contact or a company record. */
+  setDoNotContact(recordType: CrmRecordType, recordId: string): Promise<void>;
+  /** Suppress an email address for the tenant. */
+  suppressEmail(email: string): Promise<void>;
+  /**
+   * Log a note as a person (`attributes.by = person`); returns its activity
+   * id. The summary may exceed 4000 characters; the server must truncate it
+   * on read.
+   */
+  addPersonNote(recordType: CrmRecordType, recordId: string, summary: string): Promise<string>;
+}
+
+export interface CrmConformanceTarget {
+  baseUrl: string;
+  apiKey: string;
+  tenantId: string;
+  fetchImpl?: FetchLike;
+  /** Run cases that create records and spend outreach allowance. */
+  write?: boolean;
+  /** Also drive the weekly first-touch cap to its limit (CI against a throwaway database only). */
+  spendWeeklyAllowance?: boolean;
+  /** A key for the same tenant without write scopes: writes must be 403 forbidden. */
+  readOnlyApiKey?: string;
+  /**
+   * A status the agent may not move a fresh record of this type to (from the
+   * type's first status). Absent, it is read off `statusPolicy`.
+   */
+  disallowedTransition?: { recordType: CrmRecordType; to: string };
+  /** The deployment's status policy, as the proxy bakes it. */
+  statusPolicy?: CrmStatusPolicy;
+  /** The deployment's suppressed statuses. */
+  suppressedStatuses?: { company: readonly string[]; contact: readonly string[] };
+  harness?: CrmConformanceHarness;
+  /** Count a case skipped for want of a harness as a failure. */
+  strict?: boolean;
+  /** Prefix for created externalIds and idempotency keys; default a random id. */
+  runId?: string;
+}
+
+export type CrmConformanceOutcome = "pass" | "fail" | "skip";
+
+export interface CrmConformanceCase {
+  id: string;
+  title: string;
+  outcome: CrmConformanceOutcome;
+  /** Why it failed or was skipped: fixed text, codes and statuses, never a reply body. */
+  detail?: string;
+}
+
+export interface CrmConformanceReport {
+  contract: "crm/1";
+  passed: number;
+  failed: number;
+  skipped: number;
+  cases: CrmConformanceCase[];
+}
+
+/** Run every case against one server and report each outcome. Never throws for a server fault. */
+export declare function runCrmConformance(
+  target: CrmConformanceTarget,
+): Promise<CrmConformanceReport>;

package/dist/src/crm-conformance.js

@@ -0,0 +1,11 @@
+import {
+  runCrmConformance
+} from "../chunk-vcz9zbb3.js";
+import"../chunk-hvntk8p5.js";
+import"../chunk-caqstrxb.js";
+import"../chunk-xt9gdsa0.js";
+import"../chunk-rvx0cncy.js";
+import"../chunk-5wgwscd0.js";
+export {
+  runCrmConformance
+};

package/dist/src/index.js

@@ -10,7 +10,7 @@ import {
   FoundationPipeline,
   NewsletterStack,
   deployStatements
-} from "../chunk-spq5kr1t.js";
+} from "../chunk-68jxyg2n.js";
 import {
   BUN_VERSION,
   LAMBDA_ENTRY_POINTS,
@@ -34,7 +34,6 @@ import {
   skipBundle,
   verifyManifest
 } from "../chunk-pxhftba1.js";
-import"../chunk-dz91avrb.js";
 import {
   LIVE_ENDPOINT_NAME,
   WEB_SEARCH_CONNECTOR_VERSION,
@@ -47,8 +46,9 @@ import {
   loadInstanceFile,
   provisionsIntegration,
   requiresAuthenticatedQueue
-} from "../chunk-fjdgxw8h.js";
-import"../chunk-96fjaysn.js";
+} from "../chunk-pmjbzsq3.js";
+import"../chunk-dz91avrb.js";
+import"../chunk-rvx0cncy.js";
 import"../chunk-5wgwscd0.js";
 export {
   BUILD_TIMEOUT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deployfoundation/foundation-deploy",
-  "version": "0.2.53",
+  "version": "0.2.55",
   "description": "Deploys one Foundation instance from a published, signed release: the CDK app and the deploy tool.",
   "license": "UNLICENSED",
   "private": false,
@@ -9,7 +9,16 @@
     "foundation-deploy": "./dist/bin/foundation-deploy.js"
   },
   "exports": {
-    ".": "./dist/src/index.js"
+    ".": "./dist/src/index.js",
+    "./crm-conformance": {
+      "types": "./dist/src/crm-conformance.d.ts",
+      "default": "./dist/src/crm-conformance.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "crm-conformance": ["./dist/src/crm-conformance.d.ts"]
+    }
   },
   "files": [
     "dist",

package/src/crm-conformance.ts

@@ -0,0 +1,27 @@
+/**
+ * `@deployfoundation/foundation-deploy/crm-conformance`: the `crm/1`
+ * conformance suite, for a CRM's own CI to run in-process with its own
+ * harness (docs/crm-provider-contract.md#conformance).
+ *
+ *   import { runCrmConformance } from "@deployfoundation/foundation-deploy/crm-conformance";
+ *
+ * This is the published package's stable surface for the suite: the function,
+ * its target and report, and the harness interface. Its declarations are
+ * hand-written in `types/crm-conformance.d.ts`, because the source behind it
+ * lives in workspace packages that are bundled, never published;
+ * `test/crm-conformance-export.test.ts` holds the two to the same types.
+ */
+export type { CrmRecordType } from "@deployfoundation/foundation-connectors/crm";
+export type { FetchLike } from "@deployfoundation/foundation-connectors/github";
+export {
+  type CrmConformanceCase,
+  type CrmConformanceHarness,
+  type CrmConformanceOutcome,
+  type CrmConformanceReport,
+  type CrmConformanceTarget,
+  runCrmConformance,
+} from "@deployfoundation/foundation-capability-crm/contract/conformance";
+export type {
+  CrmStatusPolicy,
+  CrmStatusRule,
+} from "@deployfoundation/foundation-capability-crm/proxy/policy";

package/src/deploy/cli.ts

@@ -113,6 +113,20 @@ crm-check options
   --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
+  with --base-url --write, what the remaining write cases need:
+  --harness-url <url>  the CRM's harness endpoint (crm-harness/1), which does
+  --harness-key-stdin  what only a person can; its key comes on stdin
+  --readonly-key-stdin a key for the same tenant without write scopes, on stdin
+  --status-policy <file>
+                       the deployment's capabilities.crm.statusPolicy (JSON
+                       or YAML)
+  --suppressed-statuses <file>
+                       its capabilities.crm.outreach.suppressedStatuses
+  --spend-weekly-allowance
+                       drive this week's outreach caps to their limits
+                       (a throwaway database only)
+  Keys on stdin go one per line, in this order: the crm/1 key, the read-only
+  key, the harness key (each only when its flag is given).
 
 crm-replay options
   --from <file>        REQUIRED: the writes to replay, one JSON object per line
@@ -128,6 +142,24 @@ function flag(args: readonly string[], name: string): string | undefined {
   return index === -1 ? undefined : args[index + 1];
 }
 
+/** A flag that must carry a value when given: refuses `--x` alone or followed by another flag. */
+function valueFlag(args: readonly string[], name: string, what: string): string | undefined {
+  if (!args.includes(name)) return undefined;
+  const value = flag(args, name);
+  if (value === undefined || value.startsWith("-")) throw new Error(`${name} needs ${what}`);
+  return value;
+}
+
+/** `crm-check` inputs only the `--base-url` form takes: they feed the write cases. */
+const CRM_CHECK_TARGET_FLAGS = [
+  "--harness-url",
+  "--harness-key-stdin",
+  "--readonly-key-stdin",
+  "--status-policy",
+  "--suppressed-statuses",
+  "--spend-weekly-allowance",
+] as const;
+
 /** The AWS context for a command, with the instance file already resolved. */
 function contextFor(args: readonly string[]): AwsContext {
   const paths = loadInstanceContext(resolveInstanceFilePath(args, process.env));
@@ -235,6 +267,15 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
     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 harnessUrl = valueFlag(args, "--harness-url", "the CRM's harness endpoint URL");
+    // The harness acts as a person, so it is never called without its key,
+    // and the key, like every key here, comes on stdin.
+    if ((harnessUrl !== undefined) !== args.includes("--harness-key-stdin"))
+      throw new Error(
+        "crm-check --harness-url <url> and --harness-key-stdin go together: the harness key comes on stdin",
+      );
+    const statusPolicyFile = valueFlag(args, "--status-policy", "a file");
+    const suppressedStatusesFile = valueFlag(args, "--suppressed-statuses", "a file");
     const { crmCheckTarget, defaultCrmCommandDeps } = await import("./crm.ts");
     return crmCheckTarget(
       {
@@ -242,6 +283,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
         tenantId,
         write: args.includes("--write"),
         allowSkips: args.includes("--allow-skips"),
+        readOnlyKeyStdin: args.includes("--readonly-key-stdin"),
+        spendWeeklyAllowance: args.includes("--spend-weekly-allowance"),
+        ...(harnessUrl === undefined ? {} : { harnessUrl }),
+        ...(statusPolicyFile === undefined ? {} : { statusPolicyFile }),
+        ...(suppressedStatusesFile === undefined ? {} : { suppressedStatusesFile }),
       },
       defaultCrmCommandDeps(),
     );
@@ -330,6 +376,11 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
         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 targetOnly = CRM_CHECK_TARGET_FLAGS.filter((name) => args.includes(name));
+      if (targetOnly.length > 0)
+        throw new Error(
+          `crm-check --instance runs the read cases with the deployment's own key and policy; ${targetOnly.join(", ")} feed the write cases: use --base-url --write with a sandbox tenant`,
+        );
       const { crmCheck, defaultCrmCommandDeps } = await import("./crm.ts");
       return crmCheck(ctx, { allowSkips: args.includes("--allow-skips") }, defaultCrmCommandDeps());
     }