@deployfoundation/foundation-deploy 0.1.0

package/src/artifacts.ts

@@ -0,0 +1,318 @@
+/**
+ * Where the deployed bytes come from. **This is the one module a release
+ * changes.**
+ *
+ * Two modes, and every stack is written against the seam rather than either
+ * of them:
+ *
+ *   **local build** (the default). Every Lambda bundle is built from this
+ *   checkout at synth and the agent image is built and pushed by the deploy
+ *   before the runtime references it by tag. A contributor synthesizes and
+ *   deploys their working tree this way, and the snapshot tests run here with
+ *   `FOUNDATION_SKIP_BUNDLE=1` — no Docker, no Bun bundle, no release.
+ *
+ *   **release** (`-c release=vX.Y.Z` or `-c releaseManifest=<path>`, with
+ *   `-c releaseBucket=<name>`). Nothing is built. Each Lambda's code is the
+ *   object the signed manifest names in Foundation's release bucket, and the
+ *   agent image is Foundation's own ECR repository pinned by DIGEST. This is
+ *   what a customer's pipeline runs, and it is why that pipeline needs no
+ *   Foundation checkout, no Docker and no Bun.
+ *
+ * The manifest reaching a synth has already been verified: `foundation-deploy`
+ * checks its KMS signature and refuses to call the CDK at all otherwise
+ * (`src/release/manifest.ts`). Reading it here is a plain file read, so a
+ * synth still needs no credentials and no network.
+ *
+ * Every entry point named here lives in Foundation: the gateway and its
+ * invoker in `packages/gateway`, each capability's proxy in its own
+ * `packages/capability-*`, the newsletter's three handlers in
+ * `packages/newsletter`. The bundle input is the Foundation workspace, not an
+ * instance repository — see `lambda-bundle-context.ts`.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as cdk from "aws-cdk-lib";
+import type * as ecr from "aws-cdk-lib/aws-ecr";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import type { Construct } from "constructs";
+import { lambdaBundleContext } from "./lambda-bundle-context.ts";
+import { type ReleaseManifest, parseManifest } from "./release/manifest.ts";
+
+/** Pinned Bun used to bundle every Lambda (and the docker fallback image tag). */
+export const BUN_VERSION = "1.4.0";
+
+/** This file is `<workspaceRoot>/packages/infra/src/artifacts.ts`. */
+export const WORKSPACE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+/**
+ * The Lambdas a Foundation release carries, and the workspace-relative entry
+ * point each is built from. The keys are the names the release manifest will
+ * use for `releases/vX.Y.Z/lambda/<name>.zip`.
+ *
+ * `playwright` marks a bundle whose entry pulls `playwright-core`: its chromium
+ * driver must stay external and the output is a directory rather than a single
+ * file, so the bundler is invoked differently.
+ */
+export const LAMBDA_ENTRY_POINTS = {
+  gateway: { entry: "packages/gateway/src/lambda.ts" },
+  invoker: { entry: "packages/gateway/src/invoker.ts" },
+  "email-proxy": { entry: "packages/capability-email/src/proxy/handler.ts" },
+  "otter-proxy": { entry: "packages/capability-otter/src/proxy/handler.ts" },
+  "knock-proxy": { entry: "packages/capability-knock/src/proxy/handler.ts" },
+  "crm-proxy": { entry: "packages/capability-crm/src/proxy/handler.ts" },
+  "upwork-proxy": { entry: "packages/capability-upwork/src/proxy/handler.ts" },
+  "browser-proxy": { entry: "packages/gateway/src/browser-proxy.ts", playwright: true },
+  "newsletter-public": { entry: "packages/newsletter/src/lambda-public.ts" },
+  "newsletter-campaign": { entry: "packages/newsletter/src/lambda-campaign.ts" },
+  "newsletter-ses-events": { entry: "packages/newsletter/src/lambda-ses-events.ts" },
+} as const satisfies Record<string, { entry: string; playwright?: true }>;
+
+export type LambdaArtifactId = keyof typeof LAMBDA_ENTRY_POINTS;
+
+/**
+ * Is this synth allowed to skip bundling altogether?
+ *
+ * Template assertions and a no-Docker synth check want the stacks' shape, not
+ * their bytes, and a real bundle makes both depend on a working Bun or Docker
+ * toolchain. Read at call time so a test can set it before a stack is built.
+ *
+ * It says nothing about release mode: a release has bundles already and never
+ * stubs them, so {@link releaseSource} is consulted first everywhere below.
+ */
+export function skipBundle(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.FOUNDATION_SKIP_BUNDLE === "1";
+}
+
+/** Where a synth gets the released bytes: one bucket, one verified manifest. */
+export interface ReleaseSource {
+  version: string;
+  /** The Foundation release bucket every `lambda.*.key` is relative to. */
+  bucket: string;
+  manifest: ReleaseManifest;
+}
+
+/** Env fallbacks for the two release context keys, for a pipeline that sets env rather than flags. */
+export const RELEASE_BUCKET_ENV = "FOUNDATION_RELEASE_BUCKET";
+export const RELEASE_DIR_ENV = "FOUNDATION_RELEASE_DIR";
+
+/**
+ * Where `foundation-deploy` leaves the manifest it verified, and where
+ * `-c release=<version>` looks for it when no explicit path is given.
+ *
+ * A directory under the system temp dir rather than one inside this package:
+ * the published tool may sit in a read-only `node_modules`, and the manifest
+ * is a cache of something immutable, not state worth keeping.
+ */
+export function releaseCacheDir(version: string, env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env[RELEASE_DIR_ENV];
+  if (configured !== undefined && configured !== "") return configured;
+  return join(tmpdir(), "foundation-release", version);
+}
+
+const manifestCache = new Map<string, ReleaseManifest>();
+
+/** Read and validate a manifest from disk, once per path per process. */
+export function readManifestFile(path: string): ReleaseManifest {
+  const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  const cached = manifestCache.get(absolute);
+  if (cached !== undefined) return cached;
+  let text: string;
+  try {
+    text = readFileSync(absolute, "utf8");
+  } catch {
+    throw new Error(`no release manifest at ${absolute}`);
+  }
+  const manifest = parseManifest(text);
+  manifestCache.set(absolute, manifest);
+  return manifest;
+}
+
+/**
+ * The release this synth deploys, or `undefined` for the local-build default.
+ *
+ * `-c releaseManifest=<path>` is the authoritative form and what the deploy
+ * tool passes, having just verified that very file. `-c release=<version>`
+ * is the human form: same thing, found in {@link releaseCacheDir}. Either way
+ * `-c releaseBucket=<name>` (or `FOUNDATION_RELEASE_BUCKET`) says which bucket
+ * the manifest's keys live in, because the manifest deliberately does not name
+ * it — a release can be mirrored.
+ */
+export function releaseSource(scope: Construct): ReleaseSource | undefined {
+  const node = scope.node;
+  const version: string | undefined = node.tryGetContext("release");
+  const manifestPath: string | undefined = node.tryGetContext("releaseManifest");
+  if (
+    (version === undefined || version === "") &&
+    (manifestPath === undefined || manifestPath === "")
+  )
+    return undefined;
+
+  const path =
+    manifestPath !== undefined && manifestPath !== ""
+      ? manifestPath
+      : join(releaseCacheDir(version as string), "manifest.json");
+  const manifest = readManifestFile(path);
+  if (version !== undefined && version !== "" && manifest.version !== version)
+    throw new Error(
+      `-c release=${version} but ${path} describes ${manifest.version}; pass the manifest for the version you are deploying`,
+    );
+
+  const bucket: string =
+    node.tryGetContext("releaseBucket") ?? process.env[RELEASE_BUCKET_ENV] ?? "";
+  if (bucket === "")
+    throw new Error(
+      `-c releaseBucket=<name> is required when deploying a release (or set ${RELEASE_BUCKET_ENV}); it is the bucket holding ${manifest.lambda.gateway?.key ?? "the release artifacts"}`,
+    );
+  return { version: manifest.version, bucket, manifest };
+}
+
+/**
+ * The release bucket as one imported construct per stack. Every Lambda in a
+ * stack references the same bucket, and importing it once keeps the template's
+ * `S3Bucket` a plain name rather than eleven identical constructs.
+ */
+function releaseBucket(scope: Construct, source: ReleaseSource): s3.IBucket {
+  const stack = cdk.Stack.of(scope);
+  const existing = stack.node.tryFindChild("FoundationReleaseBucket");
+  if (existing !== undefined) return existing as s3.IBucket;
+  return s3.Bucket.fromBucketName(stack, "FoundationReleaseBucket", source.bucket);
+}
+
+/**
+ * The code for one released Lambda.
+ *
+ * In release mode it is the object the manifest names, referenced straight out
+ * of Foundation's release bucket: nothing is built, and the bytes
+ * CloudFormation fetches are the bytes the signature covered.
+ *
+ * Otherwise it is bundled locally with the pinned Bun when one is on the box;
+ * the docker image is the fallback for hosts without a Bun toolchain.
+ */
+export function lambdaCode(scope: Construct, id: LambdaArtifactId): lambda.Code {
+  const source = releaseSource(scope);
+  if (source !== undefined) {
+    const artifact = source.manifest.lambda[id];
+    if (artifact === undefined)
+      throw new Error(
+        `release ${source.version} carries no Lambda bundle for "${id}"; it was built by an older Foundation`,
+      );
+    return lambda.Code.fromBucket(releaseBucket(scope, source), artifact.key);
+  }
+  if (skipBundle())
+    return lambda.Code.fromInline("export const handler = async () => ({statusCode: 200});");
+
+  const artifact: { entry: string; playwright?: true } = LAMBDA_ENTRY_POINTS[id];
+  const bundleRoot = lambdaBundleContext(WORKSPACE_ROOT);
+  return lambda.Code.fromAsset(bundleRoot, {
+    exclude: ["**/node_modules", "**/dist", "cdk.out"],
+    bundling: {
+      image: cdk.DockerImage.fromRegistry(`oven/bun:${BUN_VERSION}`),
+      command: [
+        "bash",
+        "-c",
+        `cd /asset-input && bun install --frozen-lockfile && ${bunBuild(artifact, "/asset-output").join(" ")}`,
+      ],
+      local: {
+        tryBundle(outputDir: string): boolean {
+          const bun = process.env.BUN_BIN ?? `${process.env.HOME}/.bun/bin/bun`;
+          const [, ...args] = bunBuild(artifact, outputDir);
+          const result = spawnSync(bun, args, { cwd: WORKSPACE_ROOT, stdio: "inherit" });
+          if (result.error !== undefined) return false;
+          return result.status === 0;
+        },
+      },
+    },
+  });
+}
+
+/**
+ * The bundler command, identical in the local path, the docker path and the
+ * RELEASE build, so no two of them can produce different bytes. The entry is
+ * workspace-relative, which is what `/asset-input`, a local checkout root and
+ * the release workflow's checkout all resolve it against.
+ */
+export function bunBuild(
+  artifact: { entry: string; playwright?: true },
+  outputDir: string,
+): string[] {
+  return [
+    "bun",
+    "build",
+    artifact.entry,
+    "--target=node",
+    "--format=esm",
+    ...(artifact.playwright === true
+      ? [
+          // playwright-core resolves these lazily and neither exists on Lambda;
+          // bundling them fails the build rather than the invocation.
+          "--external",
+          "electron",
+          "--external",
+          "chromium-bidi",
+          `--outdir=${outputDir}`,
+          "--entry-naming=index.mjs",
+        ]
+      : [`--outfile=${join(outputDir, "index.mjs")}`]),
+  ];
+}
+
+/**
+ * The container URI the AgentCore runtime is created against.
+ *
+ * Locally the image was built from `packages/infra/agent-image/Dockerfile` by
+ * the deploy and pushed to the instance's OWN ECR repository, so the reference
+ * is `<repo>:<tag>` where the tag is the commit that was built. In release
+ * mode it is Foundation's repository pinned by digest — `<repo>@sha256:…`,
+ * which AgentCore accepts identically — and the customer's account pulls it
+ * across accounts under the repository policy Foundation publishes.
+ *
+ * `tag` is therefore only required in the local path; a release has no tag to
+ * pass, which is why {@link agentImageTagRequired} exists.
+ */
+export function agentImage(
+  scope: Construct,
+  repository: ecr.IRepository,
+  tag: string | undefined,
+): string {
+  const source = releaseSource(scope);
+  if (source !== undefined)
+    return `${source.manifest.agentImage.repository}@${source.manifest.agentImage.digest}`;
+  if (tag === undefined || tag === "")
+    throw new Error("agentImage: a tag is required outside release mode");
+  return `${repository.repositoryUri}:${tag}`;
+}
+
+/** Does this synth need `-c agentImageTag=<tag>`? Not when a release names the image. */
+export function agentImageTagRequired(scope: Construct): boolean {
+  return releaseSource(scope) === undefined;
+}
+
+/**
+ * The repository the agent image is pulled FROM, as an ARN, when that is not
+ * the instance's own repository.
+ *
+ * The AgentCore execution role's `ecr:BatchGetImage` is scoped to a
+ * repository, so a release deploy has to name Foundation's alongside the
+ * instance's. Derived from the manifest's repository URI rather than written
+ * down: `<account>.dkr.ecr.<region>.amazonaws.com/<name>`.
+ */
+export function releaseImageRepositoryArn(scope: Construct): string | undefined {
+  const source = releaseSource(scope);
+  if (source === undefined) return undefined;
+  return ecrRepositoryArn(source.manifest.agentImage.repository);
+}
+
+/** `<account>.dkr.ecr.<region>.amazonaws.com/<name>` → `arn:aws:ecr:<region>:<account>:repository/<name>`. */
+export function ecrRepositoryArn(repositoryUri: string): string {
+  const match = /^(\d{12})\.dkr\.ecr\.([a-z0-9-]+)\.amazonaws\.com\/(.+)$/.exec(repositoryUri);
+  if (match === null)
+    throw new Error(
+      `not an ECR repository URI: ${repositoryUri} (expected <account>.dkr.ecr.<region>.amazonaws.com/<name>)`,
+    );
+  const [, account, region, name] = match;
+  return `arn:aws:ecr:${region}:${account}:repository/${name}`;
+}

package/src/deploy/assets/github-app-manifest.yml

@@ -0,0 +1,29 @@
+# GitHub App manifest (app-as-code): identity text per instance.
+#
+# A package asset, not a file in any instance repository. This is a TEMPLATE:
+# `${displayName}` and `${url}` are substituted per instance by
+# `github-app-manifest.ts` before the document is posted, so each deployment's
+# App is named and described after its own teammate and repo.
+#
+# Fed to GitHub's App Manifest flow by `foundation-deploy github-app-create`.
+#
+# PERMISSIONS ARE NOT IN THIS FILE. They come from the capability registry
+# (the `github` capability in `packages/core/src/capabilities.ts`) via
+# requiredGithubPermissions(), plus `workflows: write` for instances that opt in
+# through `github.workflowWriteRepos`. `github-app-manifest.ts` merges them in;
+# a default_permissions block here is an error.
+#
+# Changing this file or an instance's workflowWriteRepos setting does NOT change
+# a live installation: an org admin must accept the pending permission update.
+# The broker's token request (`packages/connectors/src/github.ts`) must stay a
+# subset of the permissions that installation has ACCEPTED.
+#
+# No webhook (hook_attributes omitted): the agent pulls via the REST API only.
+name: ${displayName} Agent
+url: ${url}
+description: >-
+  ${displayName}'s GitHub connector. Mints short-lived (<=1h) installation
+  tokens so ${displayName} can use plain git/gh against the repos this App is
+  installed on.
+public: false
+default_events: []

package/src/deploy/assets/slack-app-manifest.yml

@@ -0,0 +1,95 @@
+# Declarative Slack app manifest (app-as-code), shared by every deployment.
+#
+# A package asset, not a file in any instance repository. ${DISPLAY_NAME} and
+# ${BOT_NAME} come from the instance file's `displayName`, and ${COMMAND_PREFIX}
+# from its `slack.commandPrefix`, so one template renders every deployment's app.
+#
+# Synced with the Slack CLI: `slack manifest validate`, `slack app install`
+# (creates the app on first install), `slack manifest diff`. The CLI reads the
+# manifest through a `get-manifest` hook, which `foundation-deploy` renders with
+# the request URLs substituted from env:
+#   ${EVENTS_REQUEST_URL}       https://<api-id>.execute-api.<region>.amazonaws.com/prod/slack/events
+#   ${COMMANDS_REQUEST_URL}     same host, /slack/commands
+#   ${INTERACTIVE_REQUEST_URL}  same host, /slack/interactive
+# When those env vars are unset (before the API stack is deployed), the hook
+# STRIPS event_subscriptions, slash_commands and interactivity entirely — Slack
+# verifies request URLs on manifest create, so a placeholder would be rejected.
+#
+# Console-only: keep the app private / non-distributed. Adding a bot scope
+# (in the registry) still requires a workspace REINSTALL (`slack app install`).
+
+display_information:
+  name: ${DISPLAY_NAME}
+  description: ${DISPLAY_NAME} — our AI teammate. Mention @${DISPLAY_NAME} in a channel or DM me.
+  background_color: "#2e6fb7"
+  long_description: >-
+    ${DISPLAY_NAME} is our self-hosted AI teammate. Mention @${DISPLAY_NAME} in a channel to
+    start a threaded session, reply in the thread to continue it, or DM
+    ${DISPLAY_NAME} directly. ${DISPLAY_NAME} can work in our GitHub repos, remembers
+    per-channel context, and runs on our own infrastructure.
+
+features:
+  bot_user:
+    display_name: ${BOT_NAME}
+    always_online: true
+  app_home:
+    home_tab_enabled: false
+    messages_tab_enabled: true
+    messages_tab_read_only_enabled: false
+  # agent_view (not the deprecated assistant_view): DMs behave like a normal
+  # writable DM with threaded replies. ONE-WAY DOOR — Slack does not allow
+  # reverting agent_view -> assistant_view.
+  agent_view:
+    agent_description: Our AI teammate. Ask anything, or hand ${DISPLAY_NAME} a coding task in one of our repos.
+    suggested_prompts:
+      - title: What can you do?
+        message: What can you help with, and which repos can you work in?
+  # slash_commands MUST live under `features` (a `settings.slash_commands`
+  # block is silently dropped by Slack).
+  # Command SUFFIXES are product-level (declared by the capability registry);
+  # the prefix is the instance's `slack.commandPrefix` and is substituted here
+  # as ${COMMAND_PREFIX}. The gateway matches by suffix.
+  slash_commands:
+    - command: /${COMMAND_PREFIX}-help
+      url: ${COMMANDS_REQUEST_URL}
+      description: What ${DISPLAY_NAME} can do
+      should_escape: false
+    - command: /${COMMAND_PREFIX}-calendar-connect
+      url: ${COMMANDS_REQUEST_URL}
+      description: Connect your own Google Calendar to ${DISPLAY_NAME}
+      should_escape: false
+    # Admins only, and it sets the ONE Drive identity the whole workspace
+    # reads through, not the caller's own Drive.
+    - command: /${COMMAND_PREFIX}-drive-connect
+      url: ${COMMANDS_REQUEST_URL}
+      description: Connect the Google Drive account ${DISPLAY_NAME} reads as (admins)
+    # Admins only for the same reason: one company mailbox, not the caller's.
+    - command: /${COMMAND_PREFIX}-email-connect
+      url: ${COMMANDS_REQUEST_URL}
+      description: Connect the mailbox ${DISPLAY_NAME} drafts from (admins)
+      should_escape: false
+    - command: /${COMMAND_PREFIX}-knock-connect
+      url: ${COMMANDS_REQUEST_URL}
+      description: Connect ${DISPLAY_NAME} to Knock read-only tools (admins)
+      should_escape: false
+    # Admins only: one company Upwork app/profile, with credentials isolated in
+    # a proxy rather than exposed to the agent runtime.
+    - command: /${COMMAND_PREFIX}-upwork-connect
+      url: ${COMMANDS_REQUEST_URL}
+      description: Connect the Upwork account ${DISPLAY_NAME} uses (admins)
+      should_escape: false
+
+# oauth_config.scopes.bot and settings.event_subscriptions.bot_events are
+# GENERATED from the capability registry by `slack-manifest.ts`
+# (requiredSlackScopes / BASE_SLACK_EVENTS). Listing scopes here is an error.
+oauth_config: {}
+
+settings:
+  event_subscriptions:
+    request_url: ${EVENTS_REQUEST_URL}
+  interactivity:
+    is_enabled: true
+    request_url: ${INTERACTIVE_REQUEST_URL}
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false