@deployfoundation/foundation-deploy 0.2.50 → 0.2.52

package/dist/chunk-sgdcmme0.js

@@ -0,0 +1,301 @@
+import {
+  aws,
+  putSecretString,
+  readSecretString,
+  secretExists
+} from "./chunk-9zx95xs6.js";
+import"./chunk-rxetj2p9.js";
+import {
+  CrmIdempotencyConflictError,
+  CrmRecordNotFoundError
+} from "./chunk-tey0gh86.js";
+import {
+  crmHttpBaseUrl,
+  isCrmHttpKey
+} from "./chunk-m76jt5rc.js";
+import {
+  CrmPolicyRefusedError
+} from "./chunk-p7zkm4pp.js";
+import {
+  CRM_MAX_ID_CHARS,
+  CrmInputError,
+  parseCrmLogActivityArgs,
+  parseCrmUpdateStatusArgs,
+  parseCrmUpsertRecordsArgs
+} from "./chunk-3614v9rr.js";
+import {
+  crmOutreachConfigured,
+  parseInstanceConfig
+} from "./chunk-96fjaysn.js";
+import {
+  __require
+} from "./chunk-5wgwscd0.js";
+
+// src/deploy/crm.ts
+import { readFileSync } from "node:fs";
+function httpProvider(ctx, command) {
+  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;
+}
+async function crmKey(ctx, options, deps) {
+  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 };
+}
+async function crmCheck(ctx, options, deps) {
+  const provider = httpProvider(ctx, "crm-check");
+  const secret = ctx.names.secretCrmHttp;
+  let apiKey;
+  try {
+    const raw = JSON.parse(await deps.readSecretString(ctx, secret));
+    if (typeof raw === "object" && raw !== null && "api_key" in raw)
+      apiKey = raw.api_key;
+  } catch {}
+  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);
+}
+async function crmCheckTarget(options, deps) {
+  let baseUrl;
+  try {
+    baseUrl = crmHttpBaseUrl(options.baseUrl);
+  } catch {
+    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, baseUrl, log) {
+  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, deps) {
+  return parseInstanceConfig(deps.readFile(ctx.paths.configPath));
+}
+function crmCapability(config) {
+  const crm = config.capabilities.crm;
+  return crm.enabled ? crm : undefined;
+}
+var REPLAY_OPS = ["upsert_records", "update_status", "log_activity"];
+function parseCrmReplay(text, crm, recordIdFor) {
+  const writes = [];
+  const statuses = {
+    company: new Set(crm.statuses.company),
+    contact: new Set(crm.statuses.contact)
+  };
+  const activityTypes = new Set(crm.activityTypes);
+  text.split(`
+`).forEach((raw, index) => {
+    const line = index + 1;
+    if (raw.trim() === "")
+      return;
+    let value;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      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;
+    if (typeof op !== "string" || !REPLAY_OPS.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`);
+      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 args2 = parseCrmUpdateStatusArgs(named);
+        if (!statuses[args2.recordType].has(args2.status))
+          throw new Error(`status is not a configured ${args2.recordType} status`);
+        writes.push({ line, op, args: args2 });
+        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) {
+      throw new Error(`line ${line}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+  return writes;
+}
+async function crmReplay(ctx, options, deps) {
+  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`);
+  const { createDynamoCrmClient, deterministicRecordId } = await import("./chunk-mh1206ne.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) {
+    deps.log(`dry run: ${writes.length} writes would be replayed (${counts})`);
+    return { applied: 0, refused: [] };
+  }
+  const outreach = crmOutreachConfigured(crm.outreach) ? { ...crm.outreach, timezone: config.timezone } : undefined;
+  const client = createDynamoCrmClient({
+    documentClient: await deps.documentClient(ctx),
+    tableName: await deps.crmTableName(ctx),
+    tenantId: instance.name,
+    defaultStatuses: {
+      company: crm.statuses.company[0],
+      contact: crm.statuses.contact[0]
+    },
+    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 = { 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;
+}
+function replayRefusal(error) {
+  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;
+}
+async function readPipedStdin() {
+  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 = [];
+  for await (const chunk of process.stdin)
+    chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function crmTableNameFromStack(ctx) {
+  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];
+}
+async function operatorDocumentClient(ctx) {
+  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 } });
+}
+function defaultCrmCommandDeps() {
+  return {
+    readStdin: readPipedStdin,
+    secretExists,
+    putSecretString,
+    readSecretString,
+    runConformance: async (target) => {
+      const { runCrmConformance } = await import("./chunk-jf5rw6h4.js");
+      return runCrmConformance(target);
+    },
+    crmTableName: crmTableNameFromStack,
+    documentClient: operatorDocumentClient,
+    readFile: (path) => readFileSync(path, "utf8"),
+    log: (line) => console.log(line)
+  };
+}
+export {
+  crmCheck,
+  crmCheckTarget,
+  crmKey,
+  crmReplay,
+  defaultCrmCommandDeps,
+  parseCrmReplay
+};

package/dist/chunk-tey0gh86.js

@@ -0,0 +1,38 @@
+// ../capability-crm/src/proxy/errors.ts
+class CrmOutreachUnconfiguredError extends Error {
+  constructor() {
+    super("CRM outreach is not configured");
+    this.name = "CrmOutreachUnconfiguredError";
+  }
+}
+
+class CrmRecordNotFoundError extends Error {
+  constructor() {
+    super("CRM record does not exist");
+    this.name = "CrmRecordNotFoundError";
+  }
+}
+
+class CrmIdempotencyConflictError extends Error {
+  constructor() {
+    super("CRM idempotency key conflicts with an earlier request");
+    this.name = "CrmIdempotencyConflictError";
+  }
+}
+
+class CrmStorageError extends Error {
+  constructor() {
+    super("CRM storage operation failed");
+    this.name = "CrmStorageError";
+  }
+}
+class CrmStaleWriteError extends Error {
+  code;
+  constructor(code) {
+    super(`CRM record changed since it was read: ${code}`);
+    this.code = code;
+    this.name = "CrmStaleWriteError";
+  }
+}
+
+export { CrmOutreachUnconfiguredError, CrmRecordNotFoundError, CrmIdempotencyConflictError, CrmStorageError, CrmStaleWriteError };

package/dist/src/index.js

@@ -10,42 +10,46 @@ import {
   FoundationPipeline,
   NewsletterStack,
   deployStatements
-} from "../chunk-efqdhd2e.js";
+} from "../chunk-59dpqyap.js";
 import {
   BUN_VERSION,
   LAMBDA_ENTRY_POINTS,
-  LIVE_ENDPOINT_NAME,
   RELEASE_BUCKET_ENV,
   RELEASE_DIR_ENV,
-  WEB_SEARCH_CONNECTOR_VERSION,
-  WEB_SEARCH_TARGET,
-  adminsFor,
   agentImage,
   agentImageTagRequired,
   buildManifest,
-  capabilityEnabled,
-  configPathFor,
   ecrRepositoryArn,
-  enabledIntegrations,
-  instanceNames,
   lambdaBundleContext,
   lambdaCode,
   lambdaKey,
-  loadInstanceFile,
   manifestKey,
   manifestSigningPayload,
   parseManifest,
-  provisionsIntegration,
   releaseAccess,
   releaseCacheDir,
   releaseImageRepositoryArn,
   releaseSource,
-  requiresAuthenticatedQueue,
   skillsKey,
   skipBundle,
   verifyManifest
-} from "../chunk-gnz747z2.js";
+} from "../chunk-pxhftba1.js";
 import"../chunk-dz91avrb.js";
+import {
+  LIVE_ENDPOINT_NAME,
+  WEB_SEARCH_CONNECTOR_VERSION,
+  WEB_SEARCH_TARGET,
+  adminsFor,
+  capabilityEnabled,
+  configPathFor,
+  enabledIntegrations,
+  instanceNames,
+  loadInstanceFile,
+  provisionsIntegration,
+  requiresAuthenticatedQueue
+} from "../chunk-rxetj2p9.js";
+import"../chunk-96fjaysn.js";
+import"../chunk-5wgwscd0.js";
 export {
   BUILD_TIMEOUT,
   BUN_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deployfoundation/foundation-deploy",
-  "version": "0.2.50",
+  "version": "0.2.52",
   "description": "Deploys one Foundation instance from a published, signed release: the CDK app and the deploy tool.",
   "license": "UNLICENSED",
   "private": false,
@@ -28,7 +28,9 @@
     "synth": "cdk synth --quiet"
   },
   "dependencies": {
+    "@aws-sdk/client-dynamodb": "3.1111.0",
     "@aws-sdk/client-kms": "3.1111.0",
+    "@aws-sdk/lib-dynamodb": "3.1111.0",
     "aws-cdk": "2.1142.0",
     "aws-cdk-lib": "2.270.0",
     "constructs": "10.8.1",

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;