@deployfoundation/foundation-deploy 0.1.0

package/src/deploy/stage-customization.ts

@@ -0,0 +1,224 @@
+/**
+ * Validate and stage a tenant-owned runtime configuration.
+ *
+ * The instance repository's own config is never modified: CDK and deploy-time
+ * policy always read that file. Config sync alone consumes the staged runtime
+ * copy.
+ */
+import {
+  type Stats,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, posix, relative, resolve, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import {
+  type InstanceConfig,
+  parseInstanceConfig,
+  parseSchedule,
+} from "@deployfoundation/foundation-core";
+import { CUSTOMIZATION_ARTIFACT_NAME } from "@deployfoundation/foundation-core/instance";
+import type { InstanceContext } from "./instance.ts";
+
+export type CustomizationStageStatus = "not-configured" | "migration-fallback" | "staged";
+
+export interface CustomizationStageResult {
+  status: CustomizationStageStatus;
+  runtimeConfigPath: string;
+}
+
+export interface StageCustomizationOptions {
+  /** The deployment being staged: its instance file, config path and root. */
+  paths: InstanceContext;
+  /** Injectable for tests; defaults to the build process environment. */
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Injectable so optional migration fallbacks remain observable to callers. */
+  log?: (message: string) => void;
+  /** Validate and plan without deleting or writing the local handoff. */
+  dryRun?: boolean;
+}
+
+function sourceRootFor(sourceDir: string | undefined): string {
+  if (sourceDir === undefined || sourceDir === "")
+    throw new Error("Customization source is missing.");
+  let sourceStats: Stats;
+  try {
+    sourceStats = statSync(sourceDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      throw new Error("Customization source is missing.");
+    throw error;
+  }
+  if (!sourceStats.isDirectory()) throw new Error("Customization source must be a directory.");
+  return realpathSync(sourceDir);
+}
+
+function isNormalizedRelativePosixPath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    !path.includes("\\") &&
+    !posix.isAbsolute(path) &&
+    posix.normalize(path) === path &&
+    path !== "." &&
+    path.split("/").every((part) => part !== "" && part !== "." && part !== "..")
+  );
+}
+function assertCustomizationPath(path: string, label = "Customization path"): void {
+  if (!isNormalizedRelativePosixPath(path))
+    throw new Error(`${label} must be a normalized relative POSIX path.`);
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const pathFromRoot = relative(root, candidate);
+  return (
+    pathFromRoot !== "" &&
+    pathFromRoot !== ".." &&
+    !pathFromRoot.startsWith(`..${sep}`) &&
+    !isAbsolute(pathFromRoot)
+  );
+}
+
+/** Resolve a validated POSIX path and defend again against traversal at use time. */
+function customizationFile(sourceRoot: string, configuredPath: string): string {
+  assertCustomizationPath(configuredPath);
+
+  const candidate = resolve(sourceRoot, ...configuredPath.split("/"));
+  if (!isWithin(sourceRoot, candidate))
+    throw new Error("Customization path escapes its source directory.");
+  return candidate;
+}
+
+/**
+ * Resolve each repository path component separately. ENOENT means a genuinely
+ * absent path; a dangling symlink is observed by lstat and then fails realpath.
+ */
+function resolvedCustomizationFile(sourceRoot: string, configuredPath: string): string | undefined {
+  customizationFile(sourceRoot, configuredPath);
+  const parts = configuredPath.split("/");
+  let current = sourceRoot;
+  for (const [index, part] of parts.entries()) {
+    const entry = resolve(current, part);
+    let entryStats: Stats;
+    try {
+      entryStats = lstatSync(entry);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+    current = entryStats.isSymbolicLink() ? realpathSync(entry) : entry;
+    if (current !== sourceRoot && !isWithin(sourceRoot, current))
+      throw new Error("Customization file escapes its source directory.");
+    const last = index === parts.length - 1;
+    const resolvedStats = statSync(current);
+    if (!last && !resolvedStats.isDirectory())
+      throw new Error("Customization path has a non-directory parent.");
+    if (last && !resolvedStats.isFile())
+      throw new Error("Customization path must identify a regular file.");
+  }
+  return current;
+}
+
+/**
+ * Where the validated tenant YAML is staged: beside the instance file, in an
+ * ignored directory, named for the instance. Config sync is its only consumer.
+ */
+export function stagedCustomizationPath(paths: InstanceContext): string {
+  return resolve(paths.root, STAGING_DIRECTORY, `${paths.instance.name}.yaml`);
+}
+
+/** Ignored directory the staged copy is written to, beside the instance file. */
+export const STAGING_DIRECTORY = ".foundation-staging";
+
+function assertUnchanged(path: string, platform: unknown, tenant: unknown): void {
+  if (!isDeepStrictEqual(platform, tenant))
+    throw new Error(
+      `Customization changes platform-owned authorization or capability policy. Field: ${path}.`,
+    );
+}
+
+/** Remove only the three tenant-editable leaves from a complete config. */
+function protectedConfig(config: InstanceConfig): unknown {
+  const { digestHour: _digestHour, ...todos } = config.capabilities.todos;
+  const { defined: _defined, ...routines } = config.capabilities.routines;
+  const { outreach: _outreach, ...crm } = config.capabilities.crm;
+  return {
+    ...config,
+    capabilities: {
+      ...config.capabilities,
+      todos,
+      routines,
+      crm,
+    },
+  };
+}
+
+function assertProtectedPolicy(platform: InstanceConfig, tenant: InstanceConfig): void {
+  assertUnchanged("config", protectedConfig(platform), protectedConfig(tenant));
+}
+
+function assertValidTenantRoutines(tenant: InstanceConfig): void {
+  for (const routine of tenant.capabilities.routines.defined) {
+    const parsed = parseSchedule(routine.schedule);
+    if (!parsed.ok) throw new Error(`Invalid defined routine "${routine.id}": ${parsed.reason}`);
+  }
+}
+
+function migrationFallback(
+  required: boolean,
+  log: (message: string) => void,
+  platformConfigPath: string,
+): CustomizationStageResult {
+  if (required) throw new Error("Customization file is missing.");
+  log(
+    "Customization file is absent; retaining the platform runtime configuration during migration.",
+  );
+  return { status: "migration-fallback", runtimeConfigPath: platformConfigPath };
+}
+
+/** Validate tenant YAML and stage it without changing deployment-owned input. */
+export function stageCustomization(options: StageCustomizationOptions): CustomizationStageResult {
+  const instance = options.paths.instance;
+  const env = options.env ?? process.env;
+  const platformConfigPath = options.paths.configPath;
+  const stagedPath = stagedCustomizationPath(options.paths);
+  // Never let an old local staging result survive a missing or invalid new source.
+  if (options.dryRun !== true) rmSync(stagedPath, { force: true });
+
+  const customization = instance.customization;
+  if (customization === undefined)
+    return { status: "not-configured", runtimeConfigPath: platformConfigPath };
+
+  const log = options.log ?? console.log;
+  // A legacy CodeBuild project has only the primary artifact. It may use the
+  // optional-file fallback once to install the new secondary source action.
+  const sourceDir =
+    env[`CODEBUILD_SRC_DIR_${CUSTOMIZATION_ARTIFACT_NAME}`] ??
+    (customization.required === false ? env.CODEBUILD_SRC_DIR : undefined);
+  const sourceRoot = sourceRootFor(sourceDir);
+  const sourceFile = resolvedCustomizationFile(sourceRoot, customization.path);
+  if (sourceFile === undefined)
+    return migrationFallback(customization.required, log, platformConfigPath);
+
+  // Preserve original bytes after validation: runtime gets exactly the reviewed YAML.
+  const yaml = readFileSync(sourceFile);
+  const tenantConfig = parseInstanceConfig(yaml.toString("utf8"));
+  const platformConfig = parseInstanceConfig(readFileSync(platformConfigPath, "utf8"));
+  if (tenantConfig.name !== instance.displayName)
+    throw new Error("Customization config name must match the selected instance.");
+  assertValidTenantRoutines(tenantConfig);
+  assertProtectedPolicy(platformConfig, tenantConfig);
+
+  if (options.dryRun !== true) {
+    mkdirSync(dirname(stagedPath), { recursive: true });
+    writeFileSync(stagedPath, yaml);
+  }
+  return {
+    status: "staged",
+    runtimeConfigPath: options.dryRun === true ? sourceFile : stagedPath,
+  };
+}

package/src/deploy/tracing.ts

@@ -0,0 +1,243 @@
+/**
+ * CloudWatch Transaction Search, the account-level switch that makes exported
+ * spans readable.
+ *
+ * The agent SigV4-posts its spans to the X-Ray OTLP endpoint (see
+ * `packages/agent/src/observability/otel.ts`), but they are only indexed — and only
+ * visible under CloudWatch → Application Signals → Transaction Search and the
+ * GenAI Observability views — once the account's trace segment destination is
+ * `CloudWatchLogs` and an indexing rule samples them.
+ *
+ * Both settings are PER ACCOUNT and PER REGION, not per instance, so this runs
+ * once per account and is idempotent: an account already configured is read,
+ * reported and left alone.
+ *
+ * **The cost knob is the sampling percentage.** Indexed spans are billed per
+ * trace, so 100% is right only while volume is small (one Slack team's turns).
+ * Lower it here if a deployment ever gets busy.
+ */
+import { type AwsCallContext, aws, awsMutate } from "./aws.ts";
+
+export interface TracingRunner {
+  /** Run an `aws` subcommand and return trimmed stdout. */
+  capture(args: string[]): Promise<string>;
+  /** Run a mutating `aws` subcommand (a dry run prints it instead). */
+  mutate(args: string[]): Promise<void>;
+}
+
+/** The runner that actually shells out, bound to a profile and region. */
+export function cliTracingRunner(ctx: AwsCallContext): TracingRunner {
+  return {
+    capture: (args) => aws(ctx, args),
+    mutate: (args) => awsMutate(ctx, args),
+  };
+}
+
+/** The destination that puts spans in CloudWatch Logs rather than X-Ray only. */
+export const CLOUDWATCH_LOGS_DESTINATION = "CloudWatchLogs";
+
+/** The one indexing rule the service ships; there is no second one to name. */
+export const DEFAULT_INDEXING_RULE = "Default";
+
+/** Index everything: one deployment's span volume is a handful of turns an hour. */
+export const DEFAULT_SAMPLING_PERCENTAGE = 100;
+
+/** What one setting was found to be, and whether this run changed it. */
+export type SettingOutcome = "already-set" | "updated";
+
+export interface TransactionSearchResult {
+  destination: SettingOutcome;
+  indexing: SettingOutcome;
+  /** The Logs resource policy that lets X-Ray write spans; see {@link spansIngestionPolicy}. */
+  ingestionPolicy: SettingOutcome;
+}
+
+/** Name of the Logs resource policy this helper owns. */
+export const SPANS_INGESTION_POLICY_NAME = "FoundationSpansIngestion";
+
+/**
+ * The CloudWatch Logs resource policy X-Ray needs to deliver spans into
+ * `aws/spans` (and Application Signals metrics into its group). Enabling
+ * Transaction Search from the console writes an equivalent managed policy;
+ * enabling it from the CLI does NOT, and a hand-written one that grants only
+ * `PutLogEvents` fails every export with HTTP 400 — 2026-09-07 —
+ * because X-Ray must also `CreateLogStream`. Both actions, both groups.
+ */
+export function spansIngestionPolicy(account: string, region: string): string {
+  const statement = (sid: string, group: string) => ({
+    Sid: sid,
+    Effect: "Allow",
+    Principal: { Service: "xray.amazonaws.com" },
+    Action: ["logs:PutLogEvents", "logs:CreateLogStream"],
+    Resource: group.endsWith("*")
+      ? `arn:aws:logs:${region}:${account}:log-group:${group}`
+      : `arn:aws:logs:${region}:${account}:log-group:${group}:*`,
+    Condition: {
+      StringEquals: { "aws:SourceAccount": account },
+      ArnLike: { "aws:SourceArn": `arn:aws:xray:${region}:${account}:*` },
+    },
+  });
+  return JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [
+      statement("SpansFromXray", "aws/spans"),
+      statement("ApplicationSignalsFromXray", "/aws/application-signals/data"),
+      // The agent names its OWN runtime log group in `x-aws-log-group`, and
+      // X-Ray delivers there too: without this, exports fail with "not
+      // authorized to perform logs:PutLogEvents on /aws/bedrock-agentcore/
+      // runtimes/<runtime>-live" (2026-09-07).
+      statement("AgentCoreRuntimeSpansFromXray", "/aws/bedrock-agentcore/runtimes/*"),
+    ],
+  });
+}
+
+/** True when some resource policy already lets X-Ray create streams in `aws/spans`. */
+export function hasSpansIngestionPolicy(describeOutput: string): boolean {
+  let policies: unknown;
+  try {
+    policies = (JSON.parse(describeOutput) as { resourcePolicies?: unknown }).resourcePolicies;
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(policies)) return false;
+  return policies.some((p) => {
+    const doc = String((p as { policyDocument?: unknown }).policyDocument ?? "");
+    return (
+      doc.includes("aws/spans") &&
+      doc.includes("logs:CreateLogStream") &&
+      doc.includes("/aws/bedrock-agentcore/runtimes/")
+    );
+  });
+}
+
+/** `{"Destination":"CloudWatchLogs","Status":"ACTIVE"}` → the destination. */
+export function parseDestination(text: string): string {
+  try {
+    return String((JSON.parse(text) as { Destination?: unknown }).Destination ?? "");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The sampling percentage of one indexing rule, or null when the account has
+ * no such rule (which is itself a reason to write one).
+ */
+export function parseSamplingPercentage(text: string, ruleName: string): number | null {
+  let rules: unknown;
+  try {
+    rules = (JSON.parse(text) as { IndexingRules?: unknown }).IndexingRules;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(rules)) return null;
+  for (const rule of rules as {
+    Name?: unknown;
+    Rule?: { Probabilistic?: { DesiredSamplingPercentage?: unknown } };
+  }[]) {
+    if (rule.Name !== ruleName) continue;
+    const percentage = rule.Rule?.Probabilistic?.DesiredSamplingPercentage;
+    return typeof percentage === "number" ? percentage : null;
+  }
+  return null;
+}
+
+export interface EnsureTransactionSearchOptions {
+  samplingPercentage?: number;
+  /** Needed to write the ingestion policy; when absent the policy step is skipped. */
+  account?: string;
+  region?: string;
+  /** Print the two mutations instead of reading the account and applying them. */
+  dryRun?: boolean;
+}
+
+/**
+ * Turn Transaction Search on for this account and region, if it is not on
+ * already. Read first, write only what differs — running it twice makes one
+ * pair of read calls and no change.
+ */
+export async function ensureTransactionSearch(
+  runner: TracingRunner,
+  options: EnsureTransactionSearchOptions = {},
+): Promise<TransactionSearchResult> {
+  const percentage = options.samplingPercentage ?? DEFAULT_SAMPLING_PERCENTAGE;
+  const rule = JSON.stringify({ Probabilistic: { DesiredSamplingPercentage: percentage } });
+  // A dry run has nothing to compare against, so it prints both mutations —
+  // the honest upper bound on what the real run would do.
+  if (options.dryRun === true) {
+    if (options.account !== undefined && options.region !== undefined) {
+      await runner.mutate([
+        "logs",
+        "put-resource-policy",
+        "--policy-name",
+        SPANS_INGESTION_POLICY_NAME,
+        "--policy-document",
+        spansIngestionPolicy(options.account, options.region),
+      ]);
+    }
+    await runner.mutate([
+      "xray",
+      "update-trace-segment-destination",
+      "--destination",
+      CLOUDWATCH_LOGS_DESTINATION,
+    ]);
+    await runner.mutate([
+      "xray",
+      "update-indexing-rule",
+      "--name",
+      DEFAULT_INDEXING_RULE,
+      "--rule",
+      rule,
+    ]);
+    return { destination: "updated", indexing: "updated", ingestionPolicy: "updated" };
+  }
+
+  // The policy FIRST: a destination switched on with no policy behind it
+  // accepts nothing, and the failure only shows up as 400s from the agent.
+  let ingestionPolicy: SettingOutcome = "already-set";
+  if (options.account !== undefined && options.region !== undefined) {
+    if (!hasSpansIngestionPolicy(await runner.capture(["logs", "describe-resource-policies"]))) {
+      await runner.mutate([
+        "logs",
+        "put-resource-policy",
+        "--policy-name",
+        SPANS_INGESTION_POLICY_NAME,
+        "--policy-document",
+        spansIngestionPolicy(options.account, options.region),
+      ]);
+      ingestionPolicy = "updated";
+    }
+  }
+
+  let destination: SettingOutcome = "already-set";
+  if (
+    parseDestination(await runner.capture(["xray", "get-trace-segment-destination"])) !==
+    CLOUDWATCH_LOGS_DESTINATION
+  ) {
+    await runner.mutate([
+      "xray",
+      "update-trace-segment-destination",
+      "--destination",
+      CLOUDWATCH_LOGS_DESTINATION,
+    ]);
+    destination = "updated";
+  }
+
+  let indexing: SettingOutcome = "already-set";
+  const current = parseSamplingPercentage(
+    await runner.capture(["xray", "get-indexing-rules"]),
+    DEFAULT_INDEXING_RULE,
+  );
+  if (current !== percentage) {
+    await runner.mutate([
+      "xray",
+      "update-indexing-rule",
+      "--name",
+      DEFAULT_INDEXING_RULE,
+      "--rule",
+      rule,
+    ]);
+    indexing = "updated";
+  }
+  return { destination, indexing, ingestionPolicy };
+}

package/src/deploy-permissions.ts

@@ -0,0 +1,165 @@
+/**
+ * What a deployer is allowed to do, defined once.
+ *
+ * An instance is deployed either by GitHub Actions, through the OIDC role in
+ * `ci-stack.ts`, or by a CodePipeline in its own account, through the CodeBuild
+ * role in `pipeline-stack.ts`. Both run the very same `foundation-deploy`, so
+ * both need the very same permissions — and two hand-maintained copies of an
+ * IAM policy drift the first time one deploy step is added. They share this.
+ *
+ * The permissions are those the deploy tool actually exercises. Most of the
+ * real work happens through the CDK bootstrap roles (`cdk-hnb659fds-*`), so
+ * `sts:AssumeRole` on `cdk-*` is the broad grant here — admin-equivalent in the
+ * account by design, which is why what may assume the *role* (an OIDC subject,
+ * or CodeBuild in this account) is the security boundary, not this policy.
+ */
+import type * as cdk from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type * as kms from "aws-cdk-lib/aws-kms";
+import type * as s3 from "aws-cdk-lib/aws-s3";
+import { type Instance, type InstanceNames, provisionsIntegration } from "./names.ts";
+
+export interface DeployTargets {
+  /** The data stack's bucket — config and skills are synced into it. */
+  bucket: s3.IBucket;
+  /** The CMK that bucket is encrypted with. */
+  dataKey: kms.IKey;
+}
+
+/**
+ * The statements a deploy role carries. `stack` supplies partition, account and
+ * region; everything else is referenced by ARN *pattern* rather than by
+ * construct, so a deployer stack depends on the data stack and nothing more —
+ * naming the agent stack's repository or runtime directly would create a
+ * cross-stack cycle for no benefit.
+ */
+export function deployStatements(
+  stack: cdk.Stack,
+  names: InstanceNames,
+  targets: DeployTargets,
+  instance?: Instance,
+): iam.PolicyStatement[] {
+  // Imported secrets carry a partial ARN (no service-generated 6-character
+  // suffix), which IAM will not match — append the wildcard, the same way
+  // CDK's own `grantRead` does. It is a suffix wildcard on a named secret, not
+  // a wildcard over secrets: nothing here can read a secret it is not named.
+  const secretArn = (name: string) =>
+    `arn:${stack.partition}:secretsmanager:${stack.region}:${stack.account}:secret:${name}-??????`;
+  const runtimeSecret = secretArn(names.secretRuntime);
+  const knockOauthClient = secretArn(names.secretKnockOauthClient);
+
+  return [
+    // How `cdk deploy` does everything else: it assumes the bootstrap roles for
+    // lookup, asset publishing and the CloudFormation call.
+    new iam.PolicyStatement({
+      sid: "AssumeCdkBootstrapRoles",
+      actions: ["sts:AssumeRole"],
+      resources: [`arn:${stack.partition}:iam::${stack.account}:role/cdk-*`],
+    }),
+    // The deploy reads stack outputs (repository uri, table, bucket, runtime
+    // arn) before and after `cdk deploy`.
+    new iam.PolicyStatement({
+      sid: "ReadStackOutputs",
+      actions: ["cloudformation:DescribeStacks"],
+      resources: ["*"],
+    }),
+    // The image is pushed with the caller's own credentials, not the
+    // image-publishing role. GetAuthorizationToken is account-wide by design —
+    // it takes no resource.
+    new iam.PolicyStatement({
+      sid: "EcrLogin",
+      actions: ["ecr:GetAuthorizationToken"],
+      resources: ["*"],
+    }),
+    new iam.PolicyStatement({
+      sid: "EcrPushAgentImage",
+      actions: [
+        "ecr:BatchCheckLayerAvailability",
+        "ecr:CompleteLayerUpload",
+        "ecr:InitiateLayerUpload",
+        "ecr:PutImage",
+        "ecr:UploadLayerPart",
+        "ecr:BatchGetImage",
+        "ecr:GetDownloadUrlForLayer",
+        "ecr:DescribeImages",
+      ],
+      resources: [
+        `arn:${stack.partition}:ecr:${stack.region}:${stack.account}:repository/${names.ecrRepo}`,
+      ],
+    }),
+    // The GitHub App id is baked into the image; the Slack bot token and the
+    // runtime env map are re-composed after every deploy.
+    new iam.PolicyStatement({
+      sid: "ReadDeploySecrets",
+      actions: ["secretsmanager:GetSecretValue"],
+      resources: [secretArn(names.secretSlackApp), secretArn(names.secretGithubApp), runtimeSecret],
+    }),
+    new iam.PolicyStatement({
+      sid: "WriteRuntimeSecret",
+      actions: ["secretsmanager:PutSecretValue"],
+      resources: [runtimeSecret],
+    }),
+    // The deploy caches its last successful license verification here, and
+    // creates the secret the first time. Only for an instance that HAS a
+    // license: the check is skipped otherwise, so the grant would be dead.
+    ...(instance?.license === undefined
+      ? []
+      : [
+          new iam.PolicyStatement({
+            sid: "CacheLicenseVerification",
+            actions: [
+              "secretsmanager:CreateSecret",
+              "secretsmanager:DescribeSecret",
+              "secretsmanager:GetSecretValue",
+              "secretsmanager:PutSecretValue",
+            ],
+            resources: [secretArn(names.secretLicenseLastVerified)],
+          }),
+        ]),
+    ...(instance !== undefined && provisionsIntegration(instance, "knock")
+      ? [
+          new iam.PolicyStatement({
+            sid: "RegisterKnockOauthClient",
+            actions: ["secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue"],
+            resources: [knockOauthClient],
+          }),
+        ]
+      : []),
+    // `foundation-deploy config:sync` puts config/ and skills/ in the bucket.
+    new iam.PolicyStatement({
+      sid: "SyncConfigAndSkills",
+      actions: ["s3:PutObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetObject"],
+      resources: [
+        targets.bucket.bucketArn,
+        targets.bucket.arnForObjects("config/*"),
+        targets.bucket.arnForObjects("skills/*"),
+      ],
+    }),
+    new iam.PolicyStatement({
+      sid: "UseDataKey",
+      actions: ["kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey*"],
+      resources: [targets.dataKey.keyArn],
+    }),
+    // `foundation-deploy post-deploy`: the smoke test (`_smoke_test`,
+    // `_fs_probe`) against DEFAULT, then promotion of the new version onto `live`.
+    new iam.PolicyStatement({
+      sid: "SmokeTestRuntime",
+      actions: [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:GetAgentRuntime",
+        "bedrock-agentcore:ListAgentRuntimeVersions",
+        "bedrock-agentcore:GetAgentRuntimeEndpoint",
+        "bedrock-agentcore:UpdateAgentRuntimeEndpoint",
+      ],
+      resources: [
+        `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/${names.runtimeName}*`,
+        `arn:${stack.partition}:bedrock-agentcore:${stack.region}:${stack.account}:runtime/${names.runtimeName}*/runtime-endpoint/*`,
+      ],
+    }),
+    new iam.PolicyStatement({
+      sid: "WhoAmI",
+      actions: ["sts:GetCallerIdentity"],
+      resources: ["*"],
+    }),
+  ];
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+export {
+  BUN_VERSION,
+  LAMBDA_ENTRY_POINTS,
+  RELEASE_BUCKET_ENV,
+  RELEASE_DIR_ENV,
+  type LambdaArtifactId,
+  type ReleaseSource,
+  agentImage,
+  agentImageTagRequired,
+  ecrRepositoryArn,
+  lambdaCode,
+  releaseCacheDir,
+  releaseImageRepositoryArn,
+  releaseSource,
+  skipBundle,
+} from "./artifacts.ts";
+export {
+  type KmsVerifier,
+  type ReleaseArtifact,
+  type ReleaseManifest,
+  type ReleaseSignature,
+  type SigningAlgorithm,
+  buildManifest,
+  lambdaKey,
+  manifestKey,
+  manifestSigningPayload,
+  parseManifest,
+  skillsKey,
+  verifyManifest,
+} from "./release/manifest.ts";
+export { deployStatements, type DeployTargets } from "./deploy-permissions.ts";
+export { lambdaBundleContext } from "./lambda-bundle-context.ts";
+export {
+  LIVE_ENDPOINT_NAME,
+  WEB_SEARCH_CONNECTOR_VERSION,
+  WEB_SEARCH_TARGET,
+  adminsFor,
+  capabilityEnabled,
+  configPathFor,
+  enabledIntegrations,
+  type Instance,
+  type InstanceFile,
+  type InstanceNames,
+  loadInstanceFile,
+  namesFor,
+  provisionsIntegration,
+  requiresAuthenticatedQueue,
+} from "./names.ts";
+export { FoundationAgent, type FoundationAgentProps } from "./stacks/agent-stack.ts";
+export { FoundationApi, type FoundationApiProps } from "./stacks/api-stack.ts";
+export { FoundationCi, type FoundationCiProps } from "./stacks/ci-stack.ts";
+export { FoundationData, type FoundationDataProps } from "./stacks/data-stack.ts";
+export { FoundationNetwork, type FoundationNetworkProps } from "./stacks/network-stack.ts";
+export { NewsletterStack, type NewsletterStackProps } from "./stacks/newsletter-stack.ts";
+export {
+  BUILD_TIMEOUT,
+  DEFAULT_BUILDSPEC_PATH,
+  FoundationPipeline,
+  type FoundationPipelineProps,
+} from "./stacks/pipeline-stack.ts";