@continuous-excellence/ze-great-dashboard-aws 0.1.33 → 0.3.0

package/dist/index.js

@@ -730,7 +730,7 @@ import { z as z2 } from "zod";
 
 // packages/aws/src/internal-board.ts
 import { z } from "zod";
-var durationSchema = z.string().regex(/^\d+(?:ms|s|m|h)$/).refine((value) => Number.parseInt(value, 10) > 0).brand();
+var durationSchema = z.string().regex(/^\d+(?:ms|s|m|h)$/).refine((value2) => Number.parseInt(value2, 10) > 0).brand();
 var positionSchema = z.object({
   x: z.number().int().min(0),
   y: z.number().int().min(0),
@@ -821,8 +821,8 @@ async function assembleRelease(input) {
   );
   return { metadata, files };
 }
-function sha256(value) {
-  return createHash("sha256").update(value).digest("hex");
+function sha256(value2) {
+  return createHash("sha256").update(value2).digest("hex");
 }
 
 // packages/aws/src/bootstrap.ts
@@ -879,8 +879,8 @@ function coreBootstrapOutputs(stack) {
       (output) => Boolean(output.OutputValue)
     ).map((output) => [output.OutputKey, output.OutputValue])
   );
-  const required = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
-  const missing = required.filter((key) => !values[key]);
+  const required2 = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
+  const missing = required2.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Core stack JSON is missing outputs: ${missing.join(", ")}`);
   return values;
 }
@@ -897,8 +897,656 @@ function requiredBootstrapParameters(kind, values) {
   ];
   const missing = keys.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Missing required bootstrap values: ${missing.join(", ")}`);
-  const optional = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
-  return [...keys, ...optional].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
+  const optional2 = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
+  return [...keys, ...optional2].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
+}
+
+// packages/aws/src/handoff.ts
+var githubSubjectKeys = [
+  "repository_owner",
+  "repository_owner_id",
+  "repository",
+  "repository_id",
+  "context"
+];
+function outputValues(stack) {
+  return Object.fromEntries(
+    (stack.Outputs ?? []).filter(
+      (entry) => typeof entry.OutputKey === "string" && typeof entry.OutputValue === "string"
+    ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
+  );
+}
+function parameterValues(stack) {
+  return Object.fromEntries(
+    (stack.Parameters ?? []).filter(
+      (entry) => typeof entry.ParameterKey === "string" && typeof entry.ParameterValue === "string"
+    ).map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
+  );
+}
+function capturedStackIdentity(input) {
+  const candidate = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  if (!candidate || typeof candidate !== "object") return {};
+  const { StackName, StackId } = candidate;
+  return {
+    ...typeof StackName === "string" ? { StackName } : {},
+    ...typeof StackId === "string" ? { StackId } : {}
+  };
+}
+function required(value2, name) {
+  if (!value2) throw new Error(`Bootstrap manifest is missing ${name}`);
+  return value2;
+}
+function region(config) {
+  return required(config.region, "region");
+}
+function stackName(config, kind) {
+  return required(
+    kind === "core" ? config.core?.stackName : config.githubOidc?.stackName,
+    `${kind}.stackName`
+  );
+}
+function changeSetCommands(input) {
+  const name = `${input.kind}-initial-review`;
+  const stack = stackName(input.config, input.kind);
+  const common = ["--stack-name", stack, "--region", region(input.config)];
+  const parameters = [
+    "ze-great-dashboard-aws",
+    "bootstrap",
+    "parameters",
+    "--kind",
+    input.kind,
+    "--config",
+    input.configPath,
+    "--output",
+    input.parameterPath
+  ];
+  if (input.kind === "github-oidc")
+    parameters.push("--core-stack-json", input.coreCapturePath ?? "core-deployed-stack.json");
+  return [
+    { name: "generate-parameters", args: parameters },
+    {
+      name: "create-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "create-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--change-set-type",
+        "CREATE",
+        "--template-body",
+        `file://${input.templatePath}`,
+        "--parameters",
+        `file://${input.parameterPath}`,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "wait-for-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "wait",
+        "change-set-create-complete",
+        ...common,
+        "--change-set-name",
+        name
+      ]
+    },
+    {
+      name: "review-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "describe-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "execute-reviewed-change-set",
+      args: ["aws", "cloudformation", "execute-change-set", ...common, "--change-set-name", name]
+    },
+    {
+      name: "wait-for-stack",
+      args: ["aws", "cloudformation", "wait", "stack-create-complete", ...common]
+    },
+    {
+      name: "capture-stack",
+      captureFile: `${input.kind}-deployed-stack.json`,
+      args: ["aws", "cloudformation", "describe-stacks", ...common, "--no-cli-pager"]
+    }
+  ];
+}
+var githubOidcProvider = {
+  name: "github-oidc",
+  async prerequisite(config, runner) {
+    const repository = config.githubOidc?.repository;
+    if (!repository)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub repository is absent from the manifest."
+      };
+    if (!runner)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting was not queried."
+      };
+    try {
+      const response = JSON.parse(
+        await runner.execute("gh", ["api", `repos/${repository}/actions/oidc/customization/sub`])
+      );
+      const keys = response.include_claim_keys;
+      if (response.use_default === false && Array.isArray(keys) && githubSubjectKeys.every((key) => keys.includes(key)))
+        return {
+          status: "ready",
+          blocking: false,
+          detail: "GitHub emits the immutable owner/repository-ID OIDC subject required by this adapter."
+        };
+      return {
+        status: "immutable-subject-required",
+        blocking: true,
+        detail: "Coordinate migration: inventory and temporarily make existing name-based trust policies compatible, enable immutable GitHub OIDC subjects as a separate GitHub-admin action, verify existing deployments, then retire legacy trust."
+      };
+    } catch {
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting could not be verified (gh CLI, authentication, permission, or network unavailable)."
+      };
+    }
+  }
+};
+async function contracts() {
+  return {
+    core: bootstrapContractVersion(await bootstrapTemplate("core")),
+    githubOidc: bootstrapContractVersion(await bootstrapTemplate("github-oidc"))
+  };
+}
+async function bootstrapHandoff(input) {
+  const expectedContracts = await contracts();
+  const coreCapturePath = input.coreStackPath ?? "core-deployed-stack.json";
+  const core = input.coreStack === void 0 ? void 0 : deployedBootstrapStack(input.coreStack, expectedContracts.core);
+  const oidc = input.githubOidcStack === void 0 ? void 0 : deployedBootstrapStack(input.githubOidcStack, expectedContracts.githubOidc);
+  if (!core) {
+    requiredBootstrapParameters("core", {
+      ArtifactBucketName: input.config.core?.artifactBucketName,
+      ApplicationStackName: input.config.core?.applicationStackName,
+      DashboardFunctionName: input.config.core?.dashboardFunctionName
+    });
+    const templatePath = await bootstrapTemplatePath("core");
+    return {
+      phase: "core",
+      expectedContracts,
+      templatePath,
+      parameterPath: "core-bootstrap.json",
+      expectedOutputs: [
+        "BootstrapContractVersion",
+        "ArtifactBucketName",
+        "ApplicationStackName",
+        "CloudFormationExecutionRoleArn"
+      ],
+      requiredCapturedFiles: [],
+      reviewCheckpoints: [
+        "Review every IAM action and CAPABILITY_NAMED_IAM acknowledgement.",
+        "Do not approve retained bucket or role replacements."
+      ],
+      commands: changeSetCommands({
+        kind: "core",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "core-bootstrap.json"
+      })
+    };
+  }
+  coreBootstrapOutputs(core);
+  if (!oidc) {
+    requiredBootstrapParameters("github-oidc", {
+      GitHubOidcProviderArn: input.config.githubOidc?.providerArn,
+      GitHubRepository: input.config.githubOidc?.repository,
+      GitHubOwnerId: input.config.githubOidc?.ownerId,
+      GitHubRepositoryId: input.config.githubOidc?.repositoryId,
+      GitHubEnvironment: input.config.githubOidc?.environment,
+      ...coreBootstrapOutputs(core)
+    });
+    const templatePath = await bootstrapTemplatePath("github-oidc");
+    return {
+      phase: "github-oidc",
+      expectedContracts,
+      templatePath,
+      parameterPath: "github-oidc-bootstrap.json",
+      expectedOutputs: ["BootstrapContractVersion", "GitHubDeployRoleArn"],
+      requiredCapturedFiles: [coreCapturePath],
+      reviewCheckpoints: [
+        "Review the exact immutable GitHub OIDC subject, audience, bucket lambda/* prefix, application stack, and execution role.",
+        "Do not execute until the GitHub Environment prerequisite is ready."
+      ],
+      commands: changeSetCommands({
+        kind: "github-oidc",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "github-oidc-bootstrap.json",
+        coreCapturePath
+      }),
+      prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
+        input.config,
+        input.runner
+      )
+    };
+  }
+  const prerequisite = await (input.provider ?? githubOidcProvider).prerequisite(
+    input.config,
+    input.runner
+  );
+  if (prerequisite.status !== "ready")
+    return {
+      phase: "github-environment",
+      expectedContracts,
+      expectedOutputs: [],
+      requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+      reviewCheckpoints: [
+        "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
+      ],
+      commands: [],
+      prerequisite
+    };
+  return {
+    phase: "application-gateway",
+    expectedContracts,
+    expectedOutputs: [],
+    requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+    reviewCheckpoints: [
+      "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
+    ],
+    commands: [],
+    prerequisite
+  };
+}
+function assertEqual(actual, expected, label) {
+  if (actual !== expected)
+    throw new Error(
+      `${label} mismatch (captured: ${actual ?? "missing"}; manifest: ${expected ?? "missing"})`
+    );
+}
+async function verifyBootstrap(input) {
+  const expected = await contracts();
+  const core = deployedBootstrapStack(input.coreStack, expected.core);
+  const oidc = deployedBootstrapStack(input.githubOidcStack, expected.githubOidc);
+  for (const [kind, capture] of [
+    ["Core", capturedStackIdentity(input.coreStack)],
+    ["GitHub OIDC", capturedStackIdentity(input.githubOidcStack)]
+  ]) {
+    const expectedName = kind === "Core" ? input.config.core?.stackName : input.config.githubOidc?.stackName;
+    assertEqual(capture.StackName, expectedName, `${kind} stack name`);
+    const capturedRegion = capture.StackId?.match(/^arn:[^:]+:cloudformation:([^:]+):/)?.[1];
+    assertEqual(capturedRegion, input.config.region, `${kind} stack Region`);
+  }
+  const coreOutputs = coreBootstrapOutputs(core);
+  const coreParameters = parameterValues(core);
+  assertEqual(
+    coreParameters.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Artifact bucket"
+  );
+  assertEqual(
+    coreParameters.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Application stack"
+  );
+  assertEqual(
+    coreParameters.DashboardFunctionName,
+    input.config.core?.dashboardFunctionName,
+    "Dashboard function"
+  );
+  assertEqual(
+    coreOutputs.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Core output artifact bucket"
+  );
+  assertEqual(
+    coreOutputs.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Core output application stack"
+  );
+  const oidcParameters = parameterValues(oidc);
+  const github = input.config.githubOidc;
+  const executionRole = required(
+    coreOutputs.CloudFormationExecutionRoleArn,
+    "core CloudFormationExecutionRoleArn output"
+  );
+  for (const [key, value2] of Object.entries({
+    GitHubOidcProviderArn: github?.providerArn,
+    GitHubRepository: github?.repository,
+    GitHubOwnerId: github?.ownerId,
+    GitHubRepositoryId: github?.repositoryId,
+    GitHubEnvironment: github?.environment,
+    ApplicationStackName: coreOutputs.ApplicationStackName,
+    ArtifactBucketName: coreOutputs.ArtifactBucketName,
+    CloudFormationExecutionRoleArn: executionRole
+  }))
+    assertEqual(oidcParameters[key], value2, `OIDC ${key}`);
+  if (!/^\d+$/.test(github?.ownerId ?? "") || !/^\d+$/.test(github?.repositoryId ?? ""))
+    throw new Error("GitHub immutable owner and repository IDs must be numeric");
+  const [owner, repository, ...extra] = (github?.repository ?? "").split("/");
+  if (!owner || !repository || extra.length)
+    throw new Error("GitHub repository must be owner/repository");
+  const deployRole = outputValues(oidc).GitHubDeployRoleArn;
+  if (!deployRole) throw new Error("GitHub OIDC stack JSON is missing outputs: GitHubDeployRoleArn");
+  const providerArn = github?.providerArn ?? "";
+  const account = providerArn.match(/^arn:[^:]+:iam::(\d+):oidc-provider\//)?.[1];
+  const deployAccount = deployRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  const executionAccount = executionRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  if (!account || account !== deployAccount || account !== executionAccount)
+    throw new Error("Provider and reviewed role ARNs must belong to the same AWS account");
+  return {
+    verified: true,
+    immutableSubject: `repo:${owner}@${github?.ownerId}/${repository}@${github?.repositoryId}:environment:${github?.environment}`,
+    environmentVariables: {
+      AWS_DEPLOY_ROLE_ARN: deployRole,
+      AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN: executionRole
+    },
+    reviewedArns: {
+      githubDeployRoleArn: deployRole,
+      cloudFormationExecutionRoleArn: executionRole
+    },
+    githubEnvironmentInstructions: [
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_DEPLOY_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        deployRole
+      ],
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        executionRole
+      ]
+    ]
+  };
+}
+
+// packages/aws/src/guided.ts
+function value(input, label) {
+  if (typeof input !== "string" || !input.trim()) throw new Error(`${label} is required`);
+  return input.trim();
+}
+function repositoryParts(repository) {
+  const [owner, name, extra] = repository.split("/");
+  if (!owner || !name || extra) throw new Error("repository must be owner/repository");
+  return [owner, name];
+}
+function accountFromArn(arn) {
+  return arn.match(/^arn:[^:]+:iam::(\d+):oidc-provider\//)?.[1];
+}
+async function optional(runner, command, args) {
+  if (!runner) return void 0;
+  try {
+    return await runner.execute(command, args);
+  } catch {
+    return void 0;
+  }
+}
+async function discovered(input) {
+  const identity = await optional(input.runner, "aws", [
+    "sts",
+    "get-caller-identity",
+    "--output",
+    "json"
+  ]);
+  const aws = parseOrUnavailable(identity) ?? {};
+  const accountId = typeof aws.Account === "string" ? aws.Account : void 0;
+  const region2 = await optional(input.runner, "aws", ["configure", "get", "region"]);
+  const repo = await optional(input.runner, "gh", ["api", `repos/${input.repository}`]);
+  const github = parseOrUnavailable(repo) ?? {};
+  return {
+    accountId,
+    region: region2?.trim() || void 0,
+    ownerId: typeof github.owner?.id === "number" || typeof github.owner?.id === "string" ? String(github.owner.id) : void 0,
+    repositoryId: typeof github.id === "number" || typeof github.id === "string" ? String(github.id) : void 0
+  };
+}
+async function scaffoldBootstrapManifest(input) {
+  const slug = value(input.slug, "slug");
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(slug))
+    throw new Error("slug must use lowercase letters, digits, and hyphens");
+  const repository = value(input.repository, "repository");
+  repositoryParts(repository);
+  const environment = value(input.environment, "environment");
+  const providerArn = value(input.providerArn, "github OIDC provider ARN");
+  if (!accountFromArn(providerArn)) throw new Error("github OIDC provider ARN is invalid");
+  const found = await discovered(input);
+  const accountId = input.accountId ?? found.accountId;
+  const region2 = input.region ?? found.region;
+  const ownerId = input.ownerId ?? found.ownerId;
+  const repositoryId = input.repositoryId ?? found.repositoryId;
+  if (!accountId) throw new Error("--account-id is required when AWS identity is unavailable");
+  if (!region2) throw new Error("--region is required when AWS Region is unavailable");
+  if (!ownerId) throw new Error("--github-owner-id is required when GitHub is unavailable");
+  if (!repositoryId)
+    throw new Error("--github-repository-id is required when GitHub is unavailable");
+  return {
+    region: region2,
+    core: {
+      stackName: `${slug}-bootstrap`,
+      artifactBucketName: `${slug}-lambda-artifacts-${accountId}`,
+      applicationStackName: slug,
+      dashboardFunctionName: slug
+    },
+    githubOidc: {
+      stackName: `${slug}-github-bootstrap`,
+      providerArn,
+      repository,
+      ownerId,
+      repositoryId,
+      environment
+    }
+  };
+}
+function incomplete(config) {
+  const fields = [
+    ["region", config.region],
+    ["core.stackName", config.core?.stackName],
+    ["core.artifactBucketName", config.core?.artifactBucketName],
+    ["core.applicationStackName", config.core?.applicationStackName],
+    ["core.dashboardFunctionName", config.core?.dashboardFunctionName],
+    ["githubOidc.stackName", config.githubOidc?.stackName],
+    ["githubOidc.providerArn", config.githubOidc?.providerArn],
+    ["githubOidc.repository", config.githubOidc?.repository],
+    ["githubOidc.ownerId", config.githubOidc?.ownerId],
+    ["githubOidc.repositoryId", config.githubOidc?.repositoryId],
+    ["githubOidc.environment", config.githubOidc?.environment]
+  ];
+  return fields.filter(([, v]) => typeof v !== "string" || !v).map(([name]) => name);
+}
+function parseOrUnavailable(raw) {
+  if (!raw) return void 0;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+function absent(raw) {
+  return /not found|nosuchentity|404/i.test(raw ?? "");
+}
+async function bootstrapPreflight(input) {
+  const checks = [];
+  const missing = incomplete(input.config);
+  checks.push(
+    missing.length ? { name: "manifest", status: "missing", detail: `Missing: ${missing.join(", ")}` } : { name: "manifest", status: "ready", detail: "Manifest has all bootstrap fields." }
+  );
+  if (missing.length) return { ready: false, checks };
+  const runner = input.runner;
+  const identityRaw = await optional(runner, "aws", [
+    "sts",
+    "get-caller-identity",
+    "--output",
+    "json"
+  ]);
+  const identity = parseOrUnavailable(identityRaw);
+  const providerAccount = accountFromArn(input.config.githubOidc?.providerArn ?? "");
+  if (!identity || typeof identity.Account !== "string")
+    checks.push({
+      name: "aws-identity",
+      status: "unverified",
+      detail: "AWS identity could not be read."
+    });
+  else
+    checks.push(
+      identity.Account === providerAccount ? {
+        name: "aws-identity",
+        status: "ready",
+        detail: `AWS account ${identity.Account} matches the provider ARN.`
+      } : {
+        name: "aws-identity",
+        status: "mismatch",
+        detail: `AWS account ${identity.Account} does not match provider account ${providerAccount}.`
+      }
+    );
+  const regionRaw = await optional(runner, "aws", ["configure", "get", "region"]);
+  if (!regionRaw?.trim())
+    checks.push({
+      name: "aws-region",
+      status: "unverified",
+      detail: "AWS Region could not be read."
+    });
+  else
+    checks.push(
+      regionRaw.trim() === input.config.region ? { name: "aws-region", status: "ready", detail: `AWS Region is ${input.config.region}.` } : {
+        name: "aws-region",
+        status: "mismatch",
+        detail: `AWS Region ${regionRaw.trim()} does not match manifest ${input.config.region}.`
+      }
+    );
+  const providerRaw = await optional(runner, "aws", [
+    "iam",
+    "get-open-id-connect-provider",
+    "--open-id-connect-provider-arn",
+    input.config.githubOidc?.providerArn ?? ""
+  ]);
+  checks.push(
+    !providerRaw ? {
+      name: "oidc-provider",
+      status: "unverified",
+      detail: "OIDC provider could not be queried."
+    } : absent(providerRaw) ? { name: "oidc-provider", status: "missing", detail: "OIDC provider does not exist." } : { name: "oidc-provider", status: "ready", detail: "OIDC provider exists." }
+  );
+  const repository = input.config.githubOidc?.repository ?? "";
+  const repoRaw = await optional(runner, "gh", ["api", `repos/${repository}`]);
+  const repo = parseOrUnavailable(repoRaw);
+  if (!repoRaw)
+    checks.push({
+      name: "github-repository",
+      status: "unverified",
+      detail: "GitHub repository could not be queried."
+    });
+  else if (absent(repoRaw))
+    checks.push({
+      name: "github-repository",
+      status: "missing",
+      detail: "GitHub repository does not exist or is unavailable."
+    });
+  else if (String(repo?.id) !== input.config.githubOidc?.repositoryId || String(repo?.owner?.id) !== input.config.githubOidc?.ownerId)
+    checks.push({
+      name: "github-repository",
+      status: "mismatch",
+      detail: "GitHub numeric repository identity does not match the manifest."
+    });
+  else
+    checks.push({
+      name: "github-repository",
+      status: "ready",
+      detail: "GitHub repository identity matches the manifest."
+    });
+  const environmentRaw = await optional(runner, "gh", [
+    "api",
+    `repos/${repository}/environments/${input.config.githubOidc?.environment}`
+  ]);
+  checks.push(
+    !environmentRaw ? {
+      name: "github-environment",
+      status: "unverified",
+      detail: "GitHub Environment could not be queried."
+    } : absent(environmentRaw) ? {
+      name: "github-environment",
+      status: "missing",
+      detail: "GitHub Environment does not exist."
+    } : {
+      name: "github-environment",
+      status: "ready",
+      detail: "GitHub Environment exists; its policy is administrator-owned context."
+    }
+  );
+  const subject = await (input.provider ?? githubOidcProvider).prerequisite(input.config, runner);
+  checks.push({
+    name: "immutable-subject",
+    status: subject.status === "immutable-subject-required" ? "mismatch" : subject.status,
+    detail: subject.detail
+  });
+  return {
+    ready: !checks.some(({ status }) => status === "missing" || status === "mismatch"),
+    checks
+  };
+}
+function quote(args) {
+  return args.map((arg) => `'${arg.replaceAll("'", `'\\"'\\"'`)}'`).join(" ");
+}
+async function bootstrapGuide(input) {
+  const handoff = await bootstrapHandoff(input);
+  const lines = [
+    `Phase: ${handoff.phase}`,
+    `Required captures: ${handoff.requiredCapturedFiles.join(", ") || "none"}`
+  ];
+  if (handoff.expectedOutputs.length)
+    lines.push(`Expected outputs: ${handoff.expectedOutputs.join(", ")}`);
+  if (handoff.prerequisite)
+    lines.push(`Prerequisite: ${handoff.prerequisite.status} \u2014 ${handoff.prerequisite.detail}`);
+  lines.push("", "Commands (copy and run each AWS command yourself):");
+  for (const command of handoff.commands) {
+    if (command.name === "review-change-set")
+      lines.push("PAUSE: review the change set before approval.");
+    if (command.name === "execute-reviewed-change-set")
+      lines.push("PAUSE: execute only after explicit approval.");
+    lines.push(`${command.captureFile ? `${command.captureFile}: ` : ""}${quote(command.args)}`);
+  }
+  if (handoff.reviewCheckpoints.length)
+    lines.push("", "Review pauses:", ...handoff.reviewCheckpoints.map((item) => `- ${item}`));
+  if (input.coreStack !== void 0 && input.githubOidcStack !== void 0) {
+    const verified = await verifyBootstrap({
+      config: input.config,
+      coreStack: input.coreStack,
+      githubOidcStack: input.githubOidcStack
+    });
+    lines.push(
+      "",
+      "Optional GitHub administrator action (after the successful verification above):"
+    );
+    for (const command of verified.githubEnvironmentInstructions) lines.push(quote(command));
+  }
+  return `${lines.join("\n")}
+`;
 }
 
 // packages/aws/src/index.ts
@@ -1041,14 +1689,20 @@ async function cloudFormationTemplate() {
 }
 export {
   bootstrapContractVersion,
+  bootstrapGuide,
+  bootstrapHandoff,
+  bootstrapPreflight,
   bootstrapTemplate,
   bootstrapTemplatePath,
   cloudFormationTemplate,
   coreBootstrapOutputs,
   deployLambda,
   deployedBootstrapStack,
+  githubOidcProvider,
   mergeBootstrapParameters,
   packageLambda,
   publishClientAssets,
-  requiredBootstrapParameters
+  requiredBootstrapParameters,
+  scaffoldBootstrapManifest,
+  verifyBootstrap
 };