@deployfoundation/foundation-deploy 0.1.0

package/src/deploy/endpoint.ts

@@ -0,0 +1,242 @@
+/**
+ * The AgentCore runtime's endpoints, and the smoke invoke that decides whether
+ * a version deserves one.
+ *
+ * Humans never talk to DEFAULT: the invoker Lambda calls the pinned endpoint
+ * `live`. A deploy therefore smoke-tests the new version on DEFAULT and only
+ * then moves `live` onto it. `setup` (which has to create `live` in the first
+ * place), `deploy` and `post-deploy` all go through the helpers here, so there
+ * is one wait loop rather than three.
+ *
+ * Every call goes through an {@link EndpointRunner} so a test can hand in a
+ * double and assert on the argv instead of talking to AWS.
+ */
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type AwsCallContext, aws, awsMutate } from "./aws.ts";
+
+export interface EndpointRunner {
+  /** 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>;
+  sleep(ms: number): Promise<void>;
+}
+
+/** The runner that actually shells out, bound to a profile and region. */
+export function cliRunner(ctx: AwsCallContext): EndpointRunner {
+  return {
+    capture: (args) => aws(ctx, args),
+    mutate: (args) => awsMutate(ctx, args),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  };
+}
+
+/** The runtime id is the last segment of the runtime ARN. */
+export function runtimeIdFromArn(arn: string): string {
+  const id = arn.split("/").pop() ?? "";
+  if (id === "") throw new Error(`not an agent runtime arn: ${arn}`);
+  return id;
+}
+
+export interface EndpointState {
+  status: string;
+  liveVersion: string;
+}
+
+/** An endpoint's status and pinned version, or undefined when it does not exist. */
+export async function endpointState(
+  runner: EndpointRunner,
+  id: string,
+  name: string,
+): Promise<EndpointState | undefined> {
+  let text: string;
+  try {
+    text = await runner.capture([
+      "bedrock-agentcore-control",
+      "get-agent-runtime-endpoint",
+      "--agent-runtime-id",
+      id,
+      "--endpoint-name",
+      name,
+      "--query",
+      "[status, liveVersion]",
+      "--output",
+      "text",
+    ]);
+  } catch {
+    return undefined;
+  }
+  const [status = "", liveVersion = ""] = text.trim().split(/\s+/);
+  return { status, liveVersion };
+}
+
+export interface EndpointOptions {
+  id: string;
+  /** Endpoint name; `live` everywhere. */
+  name: string;
+  version: string;
+  attempts?: number;
+  delayMs?: number;
+  dryRun?: boolean;
+  log?: (line: string) => void;
+}
+
+/** Poll until the endpoint is READY on `version`. Throws on a failed status or a timeout. */
+export async function waitForEndpoint(
+  runner: EndpointRunner,
+  opts: EndpointOptions,
+): Promise<void> {
+  const attempts = opts.attempts ?? 60;
+  const delayMs = opts.delayMs ?? 5000;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  for (let i = 0; i < attempts; i++) {
+    const state = await endpointState(runner, opts.id, opts.name);
+    if (state !== undefined) {
+      log(`  ${opts.name} endpoint: ${state.status} (version ${state.liveVersion})`);
+      if (state.status === "READY" && state.liveVersion === opts.version) return;
+      if (state.status.endsWith("_FAILED"))
+        throw new Error(`${opts.name} endpoint ${state.status}`);
+    }
+    await runner.sleep(delayMs);
+  }
+  throw new Error(
+    `timed out waiting for the ${opts.name} endpoint to reach version ${opts.version}`,
+  );
+}
+
+/**
+ * Create the endpoint pinned to `version` if it is not there yet. Idempotent:
+ * an existing endpoint is left exactly where it points (a deploy promotes it,
+ * `setup` must not move it backwards).
+ */
+export async function ensureEndpoint(
+  runner: EndpointRunner,
+  opts: EndpointOptions,
+): Promise<"created" | "exists"> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const create = [
+    "bedrock-agentcore-control",
+    "create-agent-runtime-endpoint",
+    "--agent-runtime-id",
+    opts.id,
+    "--name",
+    opts.name,
+    "--agent-runtime-version",
+    opts.version,
+  ];
+  if (opts.dryRun === true) {
+    await runner.mutate(create);
+    return "created";
+  }
+  const state = await endpointState(runner, opts.id, opts.name);
+  if (state !== undefined) {
+    log(`  ${opts.name} endpoint already exists: ${state.status} (version ${state.liveVersion})`);
+    return "exists";
+  }
+  await runner.mutate(create);
+  await waitForEndpoint(runner, opts);
+  return "created";
+}
+
+/** Point an existing endpoint at `version` and wait for it to be READY there. */
+export async function promoteEndpoint(
+  runner: EndpointRunner,
+  opts: EndpointOptions,
+): Promise<void> {
+  await runner.mutate([
+    "bedrock-agentcore-control",
+    "update-agent-runtime-endpoint",
+    "--agent-runtime-id",
+    opts.id,
+    "--endpoint-name",
+    opts.name,
+    "--agent-runtime-version",
+    opts.version,
+  ]);
+  if (opts.dryRun === true) return;
+  await waitForEndpoint(runner, opts);
+}
+
+/** The version DEFAULT currently serves — the one a deploy just created. */
+export async function currentRuntimeVersion(runner: EndpointRunner, id: string): Promise<string> {
+  const version = await runner.capture([
+    "bedrock-agentcore-control",
+    "get-agent-runtime",
+    "--agent-runtime-id",
+    id,
+    "--query",
+    "agentRuntimeVersion",
+    "--output",
+    "text",
+  ]);
+  if (version === "" || version === "None") throw new Error(`runtime ${id} reports no version`);
+  return version;
+}
+
+/**
+ * What a healthy `_smoke_test` response says. `config_source` is here because
+ * a container that booted before its runtime secret named a bucket answers
+ * happily from the fallback config — a green smoke test hiding a teammate that
+ * knows none of its own configuration.
+ */
+export const SMOKE_EXPECT = ['"authenticated":true', '"config_source":"s3"'];
+
+/** Session ids must be at least 33 characters; pad whatever the caller has. */
+export function smokeSessionId(prefix: string): string {
+  return `${prefix}-${Math.floor(Date.now() / 1000)}`.padEnd(40, "0");
+}
+
+export interface SmokeOptions {
+  arn: string;
+  sessionId: string;
+  qualifier?: string;
+  /** The invoke payload; `{"_smoke_test":true}` unless a probe overrides it. */
+  payload?: string;
+  /** Substrings the response must contain. */
+  expect?: string[];
+  dryRun?: boolean;
+  log?: (line: string) => void;
+}
+
+/** Invoke the runtime and assert the response says what a healthy runtime says. */
+export async function smokeInvoke(runner: EndpointRunner, opts: SmokeOptions): Promise<void> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const payload = opts.payload ?? '{"_smoke_test":true}';
+  const args = [
+    "bedrock-agentcore",
+    "invoke-agent-runtime",
+    "--agent-runtime-arn",
+    opts.arn,
+    ...(opts.qualifier === undefined ? [] : ["--qualifier", opts.qualifier]),
+    "--runtime-session-id",
+    opts.sessionId,
+    // aws CLI v2 expects blob params base64-encoded.
+    "--payload",
+    Buffer.from(payload).toString("base64"),
+  ];
+  if (opts.dryRun === true) {
+    await runner.mutate([...args, "/dev/stdout"]);
+    return;
+  }
+  // A real file, not `/dev/stdout`: when this process's stdout is a captured
+  // pipe or socket (GitHub Actions, CodeBuild), the CLI's open() of
+  // /dev/stdout fails with "No such device or address" (2026-09-07). The
+  // CLI's own stdout carries nothing useful for an outfile invoke.
+  const dir = await mkdtemp(join(tmpdir(), "foundation-smoke-"));
+  const outFile = join(dir, "response.json");
+  let out: string;
+  try {
+    // The real CLI writes the outfile and prints nothing; a runner double in
+    // tests answers on stdout and writes no file. Prefer the file, fall back
+    // to stdout, so both paths read the same response.
+    const printed = await runner.capture([...args, outFile]);
+    out = (await readFile(outFile, "utf8").catch(() => "")) || printed;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  log(`  ${out.replaceAll("\n", "\n  ")}`);
+  for (const needle of opts.expect ?? SMOKE_EXPECT)
+    if (!out.includes(needle)) throw new Error(`smoke test: response does not contain ${needle}`);
+}

package/src/deploy/github-app-create.ts

@@ -0,0 +1,154 @@
+/**
+ * Create an instance's GitHub App on its org via GitHub's App Manifest flow.
+ *
+ *   foundation-deploy github-app-create --instance .foundation/instance.yaml
+ *   foundation-deploy github-app-create --instance … --dry-run
+ *
+ * `--dry-run` renders the shipped manifest template for the instance and
+ * prints it without serving anything or touching GitHub.
+ *
+ * The org, the secret id, the AWS profile and the region all default to the
+ * instance's; `--org`, `--secret`, `--profile` and `--region` still override.
+ *
+ * 1. Serves http://localhost:<port>/ with an auto-submitting form that POSTs
+ *    the rendered manifest (as JSON) to GitHub's "new app from manifest" page.
+ * 2. You click "Create GitHub App"; GitHub redirects to /callback?code=…
+ * 3. Exchanges the single-use code (POST /app-manifests/{code}/conversions —
+ *    no auth needed) for {id, slug, pem, html_url}.
+ * 4. Writes {app_id, private_key} to Secrets Manager via the aws CLI, PEM over
+ *    stdin (never argv / never printed), then prints the install URL.
+ *
+ * Record the installation_id in the same secret after installing the App.
+ */
+import { instanceNames } from "@deployfoundation/foundation-core/instance";
+import { loadAppManifest } from "./github-app-manifest.ts";
+import type { InstanceContext } from "./instance.ts";
+
+export interface GithubAppCreateOptions {
+  paths: InstanceContext;
+  org?: string;
+  port?: number;
+  secret?: string;
+  profile?: string;
+  region?: string;
+  dryRun?: boolean;
+}
+
+export async function githubAppCreate(options: GithubAppCreateOptions): Promise<void> {
+  const instance = options.paths.instance;
+  const names = instanceNames(instance);
+  const org = options.org ?? instance.github.org;
+  const port = options.port ?? 8765;
+  const secretName = options.secret ?? names.secretGithubApp;
+  const profile = options.profile ?? instance.aws.profile;
+  const region = options.region ?? instance.aws.region;
+
+  // The manifest is a template: its name, url and description are this
+  // instance's. The permission set comes from the capability registry.
+  const manifest = loadAppManifest(instance);
+  if (options.dryRun === true) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+  const redirectUrl = `http://localhost:${port}/callback`;
+  const state = crypto.randomUUID();
+  const body = JSON.stringify({ ...manifest, redirect_url: redirectUrl });
+
+  async function writeSecret(value: string): Promise<void> {
+    const run = async (cmd: string[]) => {
+      const p = Bun.spawn(["aws", ...cmd, "--profile", profile, "--region", region], {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      p.stdin.write(value);
+      p.stdin.end();
+      const code = await p.exited;
+      return { code, err: await new Response(p.stderr).text() };
+    };
+    let r = await run([
+      "secretsmanager",
+      "create-secret",
+      "--name",
+      secretName,
+      "--description",
+      `${instance.displayName} GitHub App: app_id, installation_id, private_key`,
+      "--secret-string",
+      "file:///dev/stdin",
+    ]);
+    if (r.code !== 0 && r.err.includes("ResourceExistsException"))
+      r = await run([
+        "secretsmanager",
+        "put-secret-value",
+        "--secret-id",
+        secretName,
+        "--secret-string",
+        "file:///dev/stdin",
+      ]);
+    if (r.code !== 0) throw new Error(`aws secretsmanager failed: ${r.err.trim()}`);
+  }
+
+  const server = Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname === "/") {
+        const html = `<!doctype html><title>Create ${instance.displayName} GitHub App</title><body style="font-family:system-ui;padding:2rem">
+<h2>Creating the <b>${instance.displayName}</b> GitHub App on <b>${org}</b>…</h2><p>If nothing happens, click the button.</p>
+<form id="f" method="post" action="https://github.com/organizations/${org}/settings/apps/new?state=${state}">
+<input type="hidden" name="manifest" id="m"><button>Create GitHub App</button></form>
+<script>document.getElementById('m').value=${JSON.stringify(body)};document.getElementById('f').submit();</script></body>`;
+        return new Response(html, { headers: { "content-type": "text/html" } });
+      }
+      if (url.pathname === "/callback") {
+        const code = url.searchParams.get("code");
+        if (url.searchParams.get("state") !== state || code === null)
+          return new Response("bad state/code", { status: 400 });
+        const res = await fetch(
+          `https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`,
+          {
+            method: "POST",
+            headers: {
+              Accept: "application/vnd.github+json",
+              "X-GitHub-Api-Version": "2022-11-28",
+            },
+          },
+        );
+        if (!res.ok) return new Response(`conversion failed: HTTP ${res.status}`, { status: 502 });
+        const app = (await res.json()) as {
+          id: number;
+          slug: string;
+          pem: string;
+          html_url: string;
+        };
+        await writeSecret(
+          JSON.stringify({ app_id: String(app.id), installation_id: "", private_key: app.pem }),
+        );
+        const installUrl = `https://github.com/apps/${app.slug}/installations/new`;
+        console.log(
+          JSON.stringify({
+            app_id: app.id,
+            slug: app.slug,
+            html_url: app.html_url,
+            install_url: installUrl,
+            secret: secretName,
+          }),
+        );
+        setTimeout(() => {
+          server.stop(true);
+          process.exit(0);
+        }, 500);
+        return new Response(
+          `<!doctype html><body style="font-family:system-ui;padding:2rem"><h2>✅ App "${app.slug}" created (id ${app.id}); private key stored in Secrets Manager ${secretName}.</h2><p>Next: <a href="${installUrl}">install it on your repos</a>.</p></body>`,
+          { headers: { "content-type": "text/html" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  console.log(`Open http://localhost:${port}/ to create the app (waiting up to 10 minutes)…`);
+  setTimeout(() => {
+    console.error("timed out");
+    process.exit(1);
+  }, 10 * 60_000);
+}

package/src/deploy/github-app-manifest.ts

@@ -0,0 +1,53 @@
+/**
+ * Renders the GitHub App manifest template for one instance.
+ *
+ * The manifest is a template shipped with this package: the App's name,
+ * user-facing URL and description identify the instance, so Apps remain
+ * distinguishable. Permissions are NOT in the template — they come from the
+ * capability registry (`requiredGithubPermissions`), plus `workflows: write`
+ * for instances that explicitly opt in per repo.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { requiredGithubPermissions } from "@deployfoundation/foundation-core";
+import { type Instance, instanceNames } from "@deployfoundation/foundation-core/instance";
+import { parse as parseYaml } from "yaml";
+import { PACKAGE_ASSETS } from "./paths.ts";
+
+/** The GitHub App manifest template this package ships. */
+export const GITHUB_APP_MANIFEST_PATH = join(PACKAGE_ASSETS, "github-app-manifest.yml");
+
+/** The App's homepage: the repo the agent works in, else the org itself. */
+export function manifestUrl(instance: Instance): string {
+  const repo = instance.github.defaultRepo ?? instanceNames(instance).defaultRepo;
+  return `https://github.com/${repo === "" ? instance.github.org : repo}`;
+}
+
+/** Substitute `${displayName}` and `${url}`; returns the rendered YAML text. */
+export function renderAppManifest(template: string, instance: Instance): string {
+  const values: Record<string, string> = {
+    displayName: instance.displayName,
+    url: manifestUrl(instance),
+  };
+  return template.replace(/\$\{(\w+)\}/g, (match, key: string) => {
+    const value = values[key];
+    if (value === undefined) throw new Error(`app-manifest.yml: unknown placeholder ${match}`);
+    return value;
+  });
+}
+
+/** Read the template and render it into the object GitHub is posted. */
+export function loadAppManifest(instance: Instance, template?: string): Record<string, unknown> {
+  const text = template ?? readFileSync(GITHUB_APP_MANIFEST_PATH, "utf8");
+  const manifest = parseYaml(renderAppManifest(text, instance)) as Record<string, unknown>;
+  if ("default_permissions" in manifest)
+    throw new Error(
+      "app-manifest.yml: default_permissions are generated from the capability registry; remove them from the template",
+    );
+  // The App exists for the `github` capability; its permission set is that
+  // capability's declaration plus the per-instance workflow opt-in.
+  manifest.default_permissions = requiredGithubPermissions(["github"], {
+    workflowWrites: (instance.github.workflowWriteRepos?.length ?? 0) > 0,
+  });
+  return manifest;
+}

package/src/deploy/image.ts

@@ -0,0 +1,80 @@
+/**
+ * The agent image tag. One tag per commit so a deploy is traceable to source;
+ * a dirty tree gets a `-dirty` suffix, which the ECR repo's IMMUTABLE tags
+ * would reject on a second push — that is deliberate: commit, then deploy.
+ */
+import { type AwsCallContext, argv, aws } from "./aws.ts";
+import { runCapture } from "./sh.ts";
+
+/** Tag for a commit: the short sha, `-dirty` when the tree has changes. */
+export function imageTag(shortSha: string, dirty: boolean): string {
+  const sha = shortSha.trim();
+  if (!/^[0-9a-f]{7,40}$/.test(sha)) throw new Error(`not a git short sha: ${JSON.stringify(sha)}`);
+  return dirty ? `${sha}-dirty` : sha;
+}
+
+/** The registry host of an ECR repository URI (`<acct>.dkr.ecr.<r>.amazonaws.com`). */
+export function registryOf(repositoryUri: string): string {
+  const host = repositoryUri.split("/")[0];
+  if (host === undefined || !host.includes(".dkr.ecr."))
+    throw new Error(`not an ECR repository URI: ${repositoryUri}`);
+  return host;
+}
+
+/**
+ * The commit a CI system says it checked out, when it says so. CodeBuild
+ * receives CodePipeline's source as a zip WITHOUT `.git` (a pipeline's first
+ * run failed on `git rev-parse` for exactly that reason, 2026-09-07) but sets
+ * `CODEBUILD_RESOLVED_SOURCE_VERSION` to the full sha; GitHub Actions sets
+ * `GITHUB_SHA`. Either is the same 7-character tag `git rev-parse --short`
+ * would give, and a CI checkout is never dirty.
+ */
+export function ciCommitSha(env: Record<string, string | undefined> = process.env): string | null {
+  const sha = env.CODEBUILD_RESOLVED_SOURCE_VERSION ?? env.GITHUB_SHA ?? "";
+  return /^[0-9a-f]{7,40}$/.test(sha) ? sha.slice(0, 7) : null;
+}
+
+/** Resolve the tag for the working tree at `repoRoot`. */
+export async function currentImageTag(repoRoot: string): Promise<string> {
+  const ci = ciCommitSha();
+  if (ci !== null) return imageTag(ci, false);
+  const sha = await runCapture(["git", "rev-parse", "--short", "HEAD"], { cwd: repoRoot });
+  const status = await runCapture(["git", "status", "--porcelain"], { cwd: repoRoot });
+  return imageTag(sha, status !== "");
+}
+
+/**
+ * Is this tag already in the repository? ECR tags are IMMUTABLE here, so a
+ * push of one that exists fails ("cannot be overwritten") — which is what a
+ * re-run of a failed deploy job does, since the tag is the commit sha. The
+ * image is byte-identical anyway, so the answer is to skip the push, not to
+ * force it.
+ *
+ * A dry run prints the check and answers "absent", so the plan it prints is
+ * the full build.
+ */
+export async function ecrImageExists(
+  ctx: AwsCallContext,
+  opts: { repositoryName: string; tag: string },
+): Promise<boolean> {
+  const args = [
+    "ecr",
+    "describe-images",
+    "--repository-name",
+    opts.repositoryName,
+    "--image-ids",
+    `imageTag=${opts.tag}`,
+    "--output",
+    "text",
+  ];
+  if (ctx.dryRun === true) {
+    console.log(`  $ ${argv(ctx, args).join(" ")}`);
+    return false;
+  }
+  try {
+    await aws(ctx, args);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/deploy/instance.ts

@@ -0,0 +1,87 @@
+/**
+ * How a deploy command decides which deployment it is talking to.
+ *
+ * One input: `--instance <path>`, the path to the deployment's instance YAML.
+ * There is no instance *name* to resolve, no `instances/` directory to search,
+ * no `FOUNDATION_INSTANCE`, and no default. Foundation ships no instance file; the
+ * deployment's own repository owns it, and everything else — the runtime
+ * config, the skills directory, the staging path — is resolved relative to the
+ * directory that file sits in.
+ *
+ * That directory is the "instance root" below. An instance repository whose
+ * layout is `.foundation/{instance.yaml,config.yaml,skills/}` therefore needs
+ * no configuration beyond `--instance .foundation/instance.yaml`.
+ */
+import { dirname } from "node:path";
+import {
+  type Instance,
+  type InstanceNames,
+  instanceNames,
+} from "@deployfoundation/foundation-core/instance";
+import { type InstanceFile, loadInstanceFile } from "../names.ts";
+
+export { instanceNames };
+export type { Instance, InstanceNames, InstanceFile };
+
+/** Env var the CodeBuild pipeline passes instead of a flag. */
+export const INSTANCE_FILE_ENV = "FOUNDATION_INSTANCE_FILE";
+
+/**
+ * The instance file path a command was given: `--instance <path>` (or
+ * `--instance=<path>`), else {@link INSTANCE_FILE_ENV}. There is no fallback
+ * beyond that on purpose — a deploy that guessed its target would be a deploy
+ * into the wrong account.
+ */
+export function resolveInstanceFilePath(
+  argv: readonly string[] = [],
+  env: Record<string, string | undefined> = {},
+): string {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] ?? "";
+    if (arg === "--instance") {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("-"))
+        throw new Error("--instance needs a path, e.g. --instance .foundation/instance.yaml");
+      return next;
+    }
+    if (arg.startsWith("--instance=")) {
+      const value = arg.slice("--instance=".length);
+      if (value === "") throw new Error("--instance needs a path");
+      return value;
+    }
+  }
+  const fromEnv = env[INSTANCE_FILE_ENV];
+  if (fromEnv !== undefined && fromEnv !== "") return fromEnv;
+  throw new Error(
+    `--instance <path> is required (or set ${INSTANCE_FILE_ENV}); it is the path to the deployment's instance YAML`,
+  );
+}
+
+/** Everything a command needs about where its deployment's files live. */
+export interface InstanceContext extends InstanceFile {
+  /** Directory the instance file sits in; every other path resolves against it. */
+  root: string;
+}
+
+/** Load the instance a command targets, from an explicit path. */
+export function loadInstanceContext(path: string, cwd: string = process.cwd()): InstanceContext {
+  const file = loadInstanceFile(path, cwd);
+  return { ...file, root: dirname(file.path) };
+}
+
+/**
+ * Load from argv/env. Commands call this once, at the top, so a bad or missing
+ * `--instance` fails before anything touches AWS.
+ */
+export function loadInstanceFromArgs(
+  argv: readonly string[] = process.argv.slice(2),
+  env: Record<string, string | undefined> = process.env,
+): InstanceContext {
+  return loadInstanceContext(resolveInstanceFilePath(argv, env));
+}
+
+/** The banner every command prints before it touches AWS. */
+export function instanceBanner(context: InstanceContext): string {
+  const { instance } = context;
+  return `instance: ${instance.name} (account ${instance.aws.account}, region ${instance.aws.region})\n  file: ${context.path}\n  config: ${context.configPath}`;
+}

package/src/deploy/license-cache.ts

@@ -0,0 +1,47 @@
+/**
+ * Where an instance keeps the last time its license verified.
+ *
+ * `<prefix>/license/last-verified` in the INSTANCE's own Secrets Manager —
+ * the customer's account, readable by the customer. It holds a timestamp and
+ * an expiry, never the key, and it exists so that an outage at Foundry 41
+ * cannot stop a customer deploying for up to 30 days (`license.ts`).
+ *
+ * No stack creates it: an instance with no license has no reason to carry an
+ * empty secret, so the deploy creates it the first time a check succeeds. The
+ * deploy role is granted create/read/write on that one secret id, and only for
+ * an instance whose file declares a license (`deploy-permissions.ts`).
+ */
+import {
+  type AwsContext,
+  createSecretString,
+  putSecretString,
+  readSecretString,
+  secretExists,
+} from "./aws.ts";
+import type { LastVerified, LicenseCache } from "./license.ts";
+
+export function secretsManagerLicenseCache(ctx: AwsContext): LicenseCache {
+  const secretId = ctx.names.secretLicenseLastVerified;
+  return {
+    async read(): Promise<LastVerified | undefined> {
+      if (ctx.dryRun === true) return undefined;
+      if (!(await secretExists(ctx, secretId))) return undefined;
+      const text = await readSecretString(ctx, secretId);
+      const value = JSON.parse(text) as LastVerified;
+      return typeof value.verifiedAt === "string" ? value : undefined;
+    },
+    async write(value: LastVerified): Promise<void> {
+      const json = JSON.stringify(value);
+      if (ctx.dryRun !== true && !(await secretExists(ctx, secretId))) {
+        await createSecretString(
+          ctx,
+          secretId,
+          json,
+          "Last successful Foundation license verification (no key material).",
+        );
+        return;
+      }
+      await putSecretString(ctx, secretId, json);
+    },
+  };
+}