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

package/dist/cli.js

@@ -743,7 +743,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),
@@ -834,8 +834,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
@@ -892,8 +892,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;
 }
@@ -910,8 +910,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, args2) {
+  if (!runner) return void 0;
+  try {
+    return await runner.execute(command, args2);
+  } 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(args2) {
+  return args2.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
@@ -1065,9 +1713,9 @@ var actualDependencies = {
   nodeVersion: process.versions.node,
   packageVersion: ""
 };
-function readParameterValues(value) {
-  if (!Array.isArray(value)) throw new Error("must contain a JSON parameter array");
-  const parameters = value.map((entry) => {
+function readParameterValues(value2) {
+  if (!Array.isArray(value2)) throw new Error("must contain a JSON parameter array");
+  const parameters = value2.map((entry) => {
     if (!entry || typeof entry !== "object" || typeof entry.ParameterKey !== "string" || typeof entry.ParameterValue !== "string")
       throw new Error("entries must contain string ParameterKey and ParameterValue fields");
     return entry;
@@ -1200,23 +1848,23 @@ async function installedPackageVersion() {
   return typeof packageManifest.version === "string" ? packageManifest.version : "";
 }
 var requiredOption = (name, fallback) => {
-  const value = option(name, fallback);
-  if (!value) throw new Error(`${name} is required`);
-  return value;
+  const value2 = option(name, fallback);
+  if (!value2) throw new Error(`${name} is required`);
+  return value2;
 };
-function parameter(key, value) {
-  return { ParameterKey: key, ParameterValue: value };
+function parameter(key, value2) {
+  return { ParameterKey: key, ParameterValue: value2 };
 }
 async function existingParameters(path) {
   try {
     const parsed = JSON.parse(await readFile5(path, "utf8"));
     if (!Array.isArray(parsed)) throw new Error(`${path} must contain a JSON parameter array`);
-    const values = parsed.map((value) => {
-      if (!value || typeof value !== "object" || typeof value.ParameterKey !== "string" || typeof value.ParameterValue !== "string")
+    const values = parsed.map((value2) => {
+      if (!value2 || typeof value2 !== "object" || typeof value2.ParameterKey !== "string" || typeof value2.ParameterValue !== "string")
         throw new Error(
           `${path} entries must contain string ParameterKey and ParameterValue fields`
         );
-      return value;
+      return value2;
     });
     const keys = values.map(({ ParameterKey }) => ParameterKey);
     if (new Set(keys).size !== keys.length) throw new Error(`${path} contains duplicate parameters`);
@@ -1318,9 +1966,9 @@ try {
     console.log(JSON.stringify({ published: true, version, assetPath }));
   } else if (args[0] === "doctor") {
     const parametersPath = option("--parameters", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
-    const region = option("--region", process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1") ?? "us-east-1";
+    const region2 = option("--region", process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1") ?? "us-east-1";
     const checks = await runDoctor(
-      { parametersPath, region },
+      { parametersPath, region: region2 },
       {
         async execute(command, commandArgs) {
           const { execFile: execFile3 } = await import("node:child_process");
@@ -1371,109 +2019,225 @@ try {
       (key) => !packageManaged.has(key) && (includeDefaults || !hasDefault(key) || Object.hasOwn(existingValues, key) || key === "Name" && Boolean(functionName))
     ).map((key) => {
       const definition = definitions[key];
-      const value = key === "LambdaArtifactBucket" ? artifactBucket : key === "Name" && functionName ? functionName : existingValues[key] ?? definition?.Default;
-      if (value === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
-      return parameter(key, String(value));
+      const value2 = key === "LambdaArtifactBucket" ? artifactBucket : key === "Name" && functionName ? functionName : existingValues[key] ?? definition?.Default;
+      if (value2 === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
+      return parameter(key, String(value2));
     });
     await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
     console.log(JSON.stringify({ output }));
   } else if (args[0] === "bootstrap") {
     const action = args[1];
-    const kind = bootstrapKind();
-    const config = await bootstrapConfig();
-    if (action === "template") {
-      console.log(
-        JSON.stringify({
-          kind,
-          template: await bootstrapTemplatePath(kind),
-          contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind))
-        })
-      );
-    } else if (action === "parameters") {
-      const output = option("--output", `aws-dashboard-bootstrap-${kind}.json`) ?? `aws-dashboard-bootstrap-${kind}.json`;
-      let coreOutputs = {};
-      const coreStackPath = option("--core-stack-json");
-      if (kind === "github-oidc" && coreStackPath) {
-        coreOutputs = coreBootstrapOutputs(
-          deployedBootstrapStack(
-            JSON.parse(await readFile5(coreStackPath, "utf8")),
-            bootstrapContractVersion(await bootstrapTemplate("core"))
+    if (action === "init") {
+      const output = requiredOption("--output");
+      try {
+        await readFile5(output, "utf8");
+        throw new Error(`Refusing to overwrite existing manifest: ${output}`);
+      } catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+          throw error;
+      }
+      const runner = {
+        async execute(command, commandArgs) {
+          const { execFile: execFile3 } = await import("node:child_process");
+          const { promisify: promisify3 } = await import("node:util");
+          return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+        }
+      };
+      const manifest = await scaffoldBootstrapManifest({
+        slug: requiredOption("--slug"),
+        repository: requiredOption("--repository"),
+        environment: requiredOption("--environment"),
+        providerArn: requiredOption("--github-oidc-provider-arn"),
+        region: option("--region"),
+        accountId: option("--account-id"),
+        ownerId: option("--github-owner-id"),
+        repositoryId: option("--github-repository-id"),
+        runner
+      });
+      await writeFile3(output, `${JSON.stringify(manifest, null, 2)}
+`, { flag: "wx" });
+      console.log(JSON.stringify({ output, manifest }));
+    } else {
+      const config = await bootstrapConfig();
+      if (action === "preflight") {
+        requiredOption("--config");
+        const runner = {
+          async execute(command, commandArgs) {
+            const { execFile: execFile3 } = await import("node:child_process");
+            const { promisify: promisify3 } = await import("node:util");
+            try {
+              return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+            } catch (error) {
+              if (error && typeof error === "object" && "stderr" in error) {
+                const stderr = error.stderr;
+                if (typeof stderr === "string" && /not found|404|nosuchentity/i.test(stderr))
+                  return stderr;
+              }
+              throw error;
+            }
+          }
+        };
+        const result = await bootstrapPreflight({ config, runner });
+        if (option("--format") === "text")
+          for (const check of result.checks)
+            console.log(`${check.status.toUpperCase()} ${check.name}: ${check.detail}`);
+        else console.log(JSON.stringify(result));
+        if (!result.ready) process.exitCode = 1;
+      } else if (action === "guide") {
+        const configPath = requiredOption("--config");
+        const coreStackPath = option("--core-stack-json");
+        const githubStackPath = option("--github-oidc-stack-json");
+        const runner = {
+          async execute(command, commandArgs) {
+            const { execFile: execFile3 } = await import("node:child_process");
+            const { promisify: promisify3 } = await import("node:util");
+            return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+          }
+        };
+        process.stdout.write(
+          await bootstrapGuide({
+            config,
+            configPath,
+            coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
+            coreStackPath,
+            githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+            runner
+          })
+        );
+      } else if (action === "handoff") {
+        const configPath = requiredOption("--config");
+        const coreStackPath = option("--core-stack-json");
+        const githubStackPath = option("--github-oidc-stack-json");
+        const runner = {
+          async execute(command, commandArgs) {
+            const { execFile: execFile3 } = await import("node:child_process");
+            const { promisify: promisify3 } = await import("node:util");
+            return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+          }
+        };
+        console.log(
+          JSON.stringify(
+            await bootstrapHandoff({
+              config,
+              configPath,
+              coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
+              coreStackPath,
+              githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+              runner
+            })
           )
         );
-      }
-      const supplied = requiredBootstrapParameters(kind, bootstrapValues(config, coreOutputs));
-      let parameters = supplied;
-      const deployedStackPath = option("--deployed-stack-json");
-      if (deployedStackPath) {
-        const stack = deployedBootstrapStack(
-          JSON.parse(await readFile5(deployedStackPath, "utf8")),
-          bootstrapContractVersion(await bootstrapTemplate(kind))
+      } else if (action === "verify") {
+        requiredOption("--config");
+        const coreStackPath = requiredOption("--core-stack-json");
+        const githubStackPath = requiredOption("--github-oidc-stack-json");
+        console.log(
+          JSON.stringify(
+            await verifyBootstrap({
+              config,
+              coreStack: JSON.parse(await readFile5(coreStackPath, "utf8")),
+              githubOidcStack: JSON.parse(await readFile5(githubStackPath, "utf8"))
+            })
+          )
         );
-        parameters = mergeBootstrapParameters(supplied, stack.Parameters ?? []);
-      }
-      await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
+      } else if (action === "template") {
+        const kind = bootstrapKind();
+        console.log(
+          JSON.stringify({
+            kind,
+            template: await bootstrapTemplatePath(kind),
+            contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind))
+          })
+        );
+      } else if (action === "parameters") {
+        const kind = bootstrapKind();
+        const output = option("--output", `aws-dashboard-bootstrap-${kind}.json`) ?? `aws-dashboard-bootstrap-${kind}.json`;
+        let coreOutputs = {};
+        const coreStackPath = option("--core-stack-json");
+        if (kind === "github-oidc" && coreStackPath) {
+          coreOutputs = coreBootstrapOutputs(
+            deployedBootstrapStack(
+              JSON.parse(await readFile5(coreStackPath, "utf8")),
+              bootstrapContractVersion(await bootstrapTemplate("core"))
+            )
+          );
+        }
+        const supplied = requiredBootstrapParameters(kind, bootstrapValues(config, coreOutputs));
+        let parameters = supplied;
+        const deployedStackPath = option("--deployed-stack-json");
+        if (deployedStackPath) {
+          const stack = deployedBootstrapStack(
+            JSON.parse(await readFile5(deployedStackPath, "utf8")),
+            bootstrapContractVersion(await bootstrapTemplate(kind))
+          );
+          parameters = mergeBootstrapParameters(supplied, stack.Parameters ?? []);
+        }
+        await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
-      console.log(
-        JSON.stringify({ output, kind, preservedDeployedValues: Boolean(deployedStackPath) })
-      );
-    } else if (action === "status") {
-      const stackName = requiredOption("--stack-name", bootstrapStackName(kind, config));
-      const region = option("--region", config.region);
-      const awsCommand = [
-        "aws",
-        "cloudformation",
-        "describe-stacks",
-        "--stack-name",
-        stackName,
-        ...region ? ["--region", region] : [],
-        "--no-cli-pager"
-      ];
-      console.log(
-        JSON.stringify({
-          kind,
-          contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind)),
-          awsCommand,
-          shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
-        })
-      );
-    } else if (action === "change-set") {
-      const stackName = requiredOption("--stack-name", bootstrapStackName(kind, config));
-      const changeSetName = requiredOption("--change-set-name");
-      const parametersPath = requiredOption("--parameters");
-      const region = option("--region", config.region);
-      await existingParameters(parametersPath);
-      const awsCommand = [
-        "aws",
-        "cloudformation",
-        "create-change-set",
-        "--stack-name",
-        stackName,
-        "--change-set-name",
-        changeSetName,
-        "--change-set-type",
-        option("--change-set-type", "UPDATE") ?? "UPDATE",
-        "--template-body",
-        `file://${await bootstrapTemplatePath(kind)}`,
-        "--parameters",
-        `file://${parametersPath}`,
-        "--capabilities",
-        "CAPABILITY_NAMED_IAM",
-        ...region ? ["--region", region] : [],
-        "--no-cli-pager"
-      ];
-      console.log(
-        JSON.stringify({
-          kind,
-          reviewRequired: true,
-          awsCommand,
-          shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
-        })
-      );
-    } else {
-      throw new Error(
-        "Usage: ze-great-dashboard-aws bootstrap template|parameters|status|change-set --kind core|github-oidc [options]"
-      );
+        console.log(
+          JSON.stringify({ output, kind, preservedDeployedValues: Boolean(deployedStackPath) })
+        );
+      } else if (action === "status") {
+        const kind = bootstrapKind();
+        const stackName2 = requiredOption("--stack-name", bootstrapStackName(kind, config));
+        const region2 = option("--region", config.region);
+        const awsCommand = [
+          "aws",
+          "cloudformation",
+          "describe-stacks",
+          "--stack-name",
+          stackName2,
+          ...region2 ? ["--region", region2] : [],
+          "--no-cli-pager"
+        ];
+        console.log(
+          JSON.stringify({
+            kind,
+            contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind)),
+            awsCommand,
+            shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
+          })
+        );
+      } else if (action === "change-set") {
+        const kind = bootstrapKind();
+        const stackName2 = requiredOption("--stack-name", bootstrapStackName(kind, config));
+        const changeSetName = requiredOption("--change-set-name");
+        const parametersPath = requiredOption("--parameters");
+        const region2 = option("--region", config.region);
+        await existingParameters(parametersPath);
+        const awsCommand = [
+          "aws",
+          "cloudformation",
+          "create-change-set",
+          "--stack-name",
+          stackName2,
+          "--change-set-name",
+          changeSetName,
+          "--change-set-type",
+          option("--change-set-type", "UPDATE") ?? "UPDATE",
+          "--template-body",
+          `file://${await bootstrapTemplatePath(kind)}`,
+          "--parameters",
+          `file://${parametersPath}`,
+          "--capabilities",
+          "CAPABILITY_NAMED_IAM",
+          ...region2 ? ["--region", region2] : [],
+          "--no-cli-pager"
+        ];
+        console.log(
+          JSON.stringify({
+            kind,
+            reviewRequired: true,
+            awsCommand,
+            shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
+          })
+        );
+      } else {
+        throw new Error(
+          "Usage: ze-great-dashboard-aws bootstrap init|preflight|guide|handoff|verify --config manifest.json [options], or bootstrap template|parameters|status|change-set --kind core|github-oidc [options]"
+        );
+      }
     }
   } else if (args[0] !== "package")
     throw new Error(