@continuous-excellence/ze-great-dashboard-aws 0.5.1 → 0.6.1

package/dist/cli.js

@@ -862,6 +862,125 @@ function bootstrapTemplateRevision(template) {
   if (!revision) throw new Error("Bootstrap template has no BootstrapTemplateRevision output");
   return revision;
 }
+function templateRevisionIfPresent(template) {
+  return template.match(/BootstrapTemplateRevision:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
+}
+function inspectTemplate(kind, path, template) {
+  const resourcesBlock = template.match(/^Resources:\n([\s\S]*?)(?=^[A-Za-z][A-Za-z0-9]*:\s*$)/m)?.[1] ?? "";
+  const resources = [
+    ...resourcesBlock.matchAll(/^ {2}([A-Za-z][A-Za-z0-9]+):\n {4}Type: ([^\n]+)$/gm)
+  ].map((match) => ({ logicalId: match[1], type: match[2] }));
+  const iamActions = [...template.matchAll(/^\s+Action: (?:\[([^\]]+)\]|([^\n]+))$/gm)].flatMap(([, list, scalar]) => (list ?? scalar ?? "").split(",").map((action) => action.trim())).filter(Boolean);
+  return {
+    kind,
+    path,
+    contractVersion: bootstrapContractVersion(template),
+    templateRevision: templateRevisionIfPresent(template),
+    sha256: sha256(template),
+    resources,
+    iamActions: [...new Set(iamActions)]
+  };
+}
+async function bootstrapPlan(config) {
+  const packageManifest = JSON.parse(
+    await readFile2(new URL("../package.json", import.meta.url), "utf8")
+  );
+  const packageTemplates = await Promise.all(
+    ["core", "github-oidc"].map(async (kind) => {
+      const [path, template] = await Promise.all([
+        bootstrapTemplatePath(kind),
+        bootstrapTemplate(kind)
+      ]);
+      return inspectTemplate(kind, path, template);
+    })
+  );
+  return {
+    packageVersion: typeof packageManifest.version === "string" ? packageManifest.version : "unknown",
+    packageTemplates,
+    configuration: config,
+    notes: [
+      "Templates are owned by the installed npm package; package.json and package-lock.json pin the source version.",
+      "Generated CloudFormation parameter files and describe-stacks captures are deployment artifacts, not source configuration.",
+      "This plan performs no AWS or GitHub mutations."
+    ]
+  };
+}
+function capturedStack(input) {
+  const stack = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  return stack && typeof stack === "object" ? stack : {};
+}
+function outputValues(stack) {
+  return Object.fromEntries(
+    (stack.Outputs ?? []).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
+  );
+}
+function bootstrapConsistency(kind, config, stackInput, expectedContract, expectedRevision, coreOutputs = {}) {
+  const stack = capturedStack(stackInput);
+  const mismatches = [];
+  const expectedStackName = kind === "core" ? config.core?.stackName : config.githubOidc?.stackName;
+  if (stack.StackName !== expectedStackName)
+    mismatches.push(
+      `stack name is ${stack.StackName ?? "missing"}; expected ${expectedStackName ?? "missing"}`
+    );
+  const observedRegion = stack.StackId?.match(/^arn:[^:]+:cloudformation:([^:]+):/)?.[1];
+  if (observedRegion !== config.region)
+    mismatches.push(
+      `Region is ${observedRegion ?? "missing"}; expected ${config.region ?? "missing"}`
+    );
+  if (!["CREATE_COMPLETE", "UPDATE_COMPLETE"].includes(stack.StackStatus ?? ""))
+    mismatches.push(
+      `stack status is ${stack.StackStatus ?? "missing"}; expected a successful stable status`
+    );
+  const outputs2 = outputValues(stack);
+  if (outputs2.BootstrapContractVersion !== expectedContract)
+    mismatches.push(
+      `contract is ${outputs2.BootstrapContractVersion ?? "missing"}; expected ${expectedContract}`
+    );
+  if (expectedRevision && outputs2.BootstrapTemplateRevision !== expectedRevision)
+    mismatches.push(
+      `template revision is ${outputs2.BootstrapTemplateRevision ?? "missing"}; expected ${expectedRevision}`
+    );
+  const requiredOutputs = kind === "core" ? ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"] : ["GitHubDeployRoleArn"];
+  for (const key of requiredOutputs) if (!outputs2[key]) mismatches.push(`${key} output is missing`);
+  if (kind === "core") {
+    if (outputs2.ArtifactBucketName !== config.core?.artifactBucketName)
+      mismatches.push(
+        `ArtifactBucketName output is ${outputs2.ArtifactBucketName ?? "missing"}; expected ${config.core?.artifactBucketName ?? "missing"}`
+      );
+    if (outputs2.ApplicationStackName !== config.core?.applicationStackName)
+      mismatches.push(
+        `ApplicationStackName output is ${outputs2.ApplicationStackName ?? "missing"}; expected ${config.core?.applicationStackName ?? "missing"}`
+      );
+  }
+  const parameters = Object.fromEntries(
+    (stack.Parameters ?? []).map(({ ParameterKey, ParameterValue }) => [
+      ParameterKey,
+      ParameterValue
+    ])
+  );
+  const expectedParameters = kind === "core" ? {
+    ArtifactBucketName: config.core?.artifactBucketName,
+    ApplicationStackName: config.core?.applicationStackName,
+    DashboardFunctionName: config.core?.dashboardFunctionName,
+    RuntimeSecretArn: config.core?.runtimeSecretArn ?? "",
+    ArtifactKmsKeyArn: config.core?.artifactKmsKeyArn ?? ""
+  } : {
+    GitHubOidcProviderArn: config.githubOidc?.providerArn,
+    GitHubRepository: config.githubOidc?.repository,
+    GitHubOwnerId: config.githubOidc?.ownerId,
+    GitHubRepositoryId: config.githubOidc?.repositoryId,
+    GitHubEnvironment: config.githubOidc?.environment,
+    CoreBootstrapStackName: config.core?.stackName,
+    ApplicationStackName: config.core?.applicationStackName,
+    ArtifactBucketName: config.core?.artifactBucketName,
+    CloudFormationExecutionRoleArn: coreOutputs.CloudFormationExecutionRoleArn,
+    ConsumerGatewayStackName: config.githubOidc?.consumerGatewayStackName ?? ""
+  };
+  for (const [key, expected] of Object.entries(expectedParameters))
+    if (expected !== void 0 && parameters[key] !== expected)
+      mismatches.push(`${key} is ${parameters[key] ?? "missing"}; expected ${expected}`);
+  return { ok: mismatches.length === 0, mismatches };
+}
 function mergeBootstrapParameters(requested, deployed) {
   const supplied = new Map(requested.map((entry) => [entry.ParameterKey, entry.ParameterValue]));
   const duplicates = requested.map((entry) => entry.ParameterKey);
@@ -909,6 +1028,7 @@ function requiredBootstrapParameters(kind, values) {
     "GitHubOwnerId",
     "GitHubRepositoryId",
     "GitHubEnvironment",
+    "CoreBootstrapStackName",
     "ApplicationStackName",
     "ArtifactBucketName",
     "CloudFormationExecutionRoleArn"
@@ -919,6 +1039,256 @@ function requiredBootstrapParameters(kind, values) {
   return [...keys, ...optional2].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
 }
 
+// packages/aws/src/bootstrap-check.ts
+function formatBootstrapCheckText(result) {
+  const lines = [`AWS bootstrap consistency (${result.packageVersion})`];
+  for (const stack of result.stacks) {
+    lines.push(
+      `${stack.consistency.ok && (!stack.resourceDrift || stack.resourceDrift.ok) ? "PASS" : "FAIL"} ${stack.kind}: ${stack.stackName} (${stack.stackStatus ?? "unavailable"})`,
+      `  template: contract ${stack.contractVersion}, revision ${stack.templateRevision ?? "none"}, sha256 ${stack.templateSha256}`
+    );
+    for (const mismatch of stack.consistency.mismatches) lines.push(`  mismatch: ${mismatch}`);
+    if (!stack.resourceDrift) continue;
+    lines.push(`  resource drift: ${stack.resourceDrift.status}`);
+    if (stack.resourceDrift.reason) lines.push(`  drift error: ${stack.resourceDrift.reason}`);
+    for (const resource of stack.resourceDrift.resources) {
+      lines.push(
+        `  drifted resource: ${resource.logicalId} (${resource.resourceType ?? "unknown"}, ${resource.status ?? "unknown"})`
+      );
+      for (const difference of resource.differences)
+        lines.push(
+          `    ${difference.path ?? "unknown property"}: ${difference.differenceType ?? "changed"}; expected ${difference.expectedValue ?? "unknown"}, actual ${difference.actualValue ?? "unknown"}`
+        );
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function parseJson(raw, operation) {
+  try {
+    const value2 = JSON.parse(raw);
+    if (!value2 || typeof value2 !== "object" || Array.isArray(value2))
+      throw new Error("response is not an object");
+    return value2;
+  } catch (error) {
+    throw new Error(`${operation} returned invalid JSON: ${message(error)}`);
+  }
+}
+function stackFrom(response) {
+  const stacks = response.Stacks;
+  return Array.isArray(stacks) && stacks[0] && typeof stacks[0] === "object" ? stacks[0] : void 0;
+}
+function outputs(stack) {
+  const entries = stack?.Outputs;
+  if (!Array.isArray(entries)) return {};
+  return Object.fromEntries(
+    entries.filter(
+      (entry) => Boolean(entry && typeof entry === "object" && typeof entry.OutputKey === "string")
+    ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
+  );
+}
+async function resourceDrift(stackName2, region2, dependencies) {
+  try {
+    const detected = parseJson(
+      await dependencies.execute("aws", [
+        "cloudformation",
+        "detect-stack-drift",
+        "--stack-name",
+        stackName2,
+        "--region",
+        region2,
+        "--output",
+        "json",
+        "--no-cli-pager"
+      ]),
+      "detect-stack-drift"
+    );
+    const detectionId = detected.StackDriftDetectionId;
+    if (typeof detectionId !== "string")
+      throw new Error("detect-stack-drift returned no StackDriftDetectionId");
+    const now = dependencies.now ?? Date.now;
+    const sleep = dependencies.sleep ?? ((milliseconds) => new Promise((resolve3) => setTimeout(resolve3, milliseconds)));
+    const deadline = now() + 10 * 60 * 1e3;
+    let status;
+    while (true) {
+      status = parseJson(
+        await dependencies.execute("aws", [
+          "cloudformation",
+          "describe-stack-drift-detection-status",
+          "--stack-drift-detection-id",
+          detectionId,
+          "--region",
+          region2,
+          "--output",
+          "json",
+          "--no-cli-pager"
+        ]),
+        "describe-stack-drift-detection-status"
+      );
+      if (status.DetectionStatus !== "DETECTION_IN_PROGRESS") break;
+      if (now() >= deadline)
+        return {
+          ok: false,
+          status: "TIMED_OUT",
+          detectionId,
+          reason: "CloudFormation drift detection did not complete within 10 minutes",
+          resources: []
+        };
+      await sleep(5e3);
+    }
+    if (status.DetectionStatus !== "DETECTION_COMPLETE")
+      return {
+        ok: false,
+        status: String(status.DetectionStatus ?? "UNKNOWN"),
+        detectionId,
+        reason: typeof status.DetectionStatusReason === "string" ? status.DetectionStatusReason : "CloudFormation drift detection failed",
+        resources: []
+      };
+    const stackDriftStatus = String(status.StackDriftStatus ?? "UNKNOWN");
+    if (stackDriftStatus !== "DRIFTED")
+      return {
+        ok: stackDriftStatus === "IN_SYNC",
+        status: stackDriftStatus,
+        detectionId,
+        resources: []
+      };
+    const described = parseJson(
+      await dependencies.execute("aws", [
+        "cloudformation",
+        "describe-stack-resource-drifts",
+        "--stack-name",
+        stackName2,
+        "--stack-resource-drift-status-filters",
+        "MODIFIED",
+        "DELETED",
+        "--region",
+        region2,
+        "--output",
+        "json",
+        "--no-cli-pager"
+      ]),
+      "describe-stack-resource-drifts"
+    );
+    const resources = Array.isArray(described.StackResourceDrifts) ? described.StackResourceDrifts.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      const drift = entry;
+      if (typeof drift.LogicalResourceId !== "string") return [];
+      const differences = Array.isArray(drift.PropertyDifferences) ? drift.PropertyDifferences.flatMap((item) => {
+        if (!item || typeof item !== "object") return [];
+        const difference = item;
+        return [
+          {
+            ...typeof difference.PropertyPath === "string" ? { path: difference.PropertyPath } : {},
+            ...typeof difference.DifferenceType === "string" ? { differenceType: difference.DifferenceType } : {},
+            ...typeof difference.ExpectedValue === "string" ? { expectedValue: difference.ExpectedValue } : {},
+            ...typeof difference.ActualValue === "string" ? { actualValue: difference.ActualValue } : {}
+          }
+        ];
+      }) : [];
+      return [
+        {
+          logicalId: drift.LogicalResourceId,
+          ...typeof drift.ResourceType === "string" ? { resourceType: drift.ResourceType } : {},
+          ...typeof drift.StackResourceDriftStatus === "string" ? { status: drift.StackResourceDriftStatus } : {},
+          differences
+        }
+      ];
+    }) : [];
+    return { ok: false, status: stackDriftStatus, detectionId, resources };
+  } catch (error) {
+    return { ok: false, status: "ERROR", reason: message(error), resources: [] };
+  }
+}
+async function checkBootstrap(config, options, dependencies) {
+  const requiredManifestValues = [
+    ["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]
+  ];
+  const missing = requiredManifestValues.filter(([, value2]) => !value2).map(([name]) => name);
+  if (missing.length) throw new Error(`Bootstrap manifest is missing: ${missing.join(", ")}`);
+  const stackNames = {
+    core: config.core?.stackName,
+    "github-oidc": config.githubOidc?.stackName
+  };
+  const plan = await bootstrapPlan(config);
+  const responses = await Promise.all(
+    ["core", "github-oidc"].map(async (kind) => {
+      const stackName2 = stackNames[kind];
+      try {
+        const response = parseJson(
+          await dependencies.execute("aws", [
+            "cloudformation",
+            "describe-stacks",
+            "--stack-name",
+            stackName2,
+            "--region",
+            config.region,
+            "--output",
+            "json",
+            "--no-cli-pager"
+          ]),
+          "describe-stacks"
+        );
+        return { kind, stackName: stackName2, response };
+      } catch (error) {
+        return { kind, stackName: stackName2, error: message(error) };
+      }
+    })
+  );
+  const coreResponse = responses.find(({ kind }) => kind === "core")?.response;
+  const coreOutputValues = outputs(stackFrom(coreResponse ?? {}));
+  const stacks = await Promise.all(
+    responses.map(async ({ kind, stackName: stackName2, response, error }) => {
+      const template = plan.packageTemplates.find((candidate) => candidate.kind === kind);
+      if (!template) throw new Error(`Installed package has no ${kind} bootstrap template`);
+      const stack = stackFrom(response ?? {});
+      const consistency = error ? { ok: false, mismatches: [`unable to describe stack: ${error}`] } : bootstrapConsistency(
+        kind,
+        config,
+        response,
+        template.contractVersion,
+        template.templateRevision,
+        coreOutputValues
+      );
+      const checked = {
+        kind,
+        stackName: stackName2,
+        ...typeof stack?.StackStatus === "string" ? { stackStatus: stack.StackStatus } : {},
+        contractVersion: template.contractVersion,
+        templateRevision: template.templateRevision,
+        templateSha256: template.sha256,
+        consistency
+      };
+      if (options.resourceDrift && !error)
+        checked.resourceDrift = await resourceDrift(
+          stackName2,
+          config.region,
+          dependencies
+        );
+      return checked;
+    })
+  );
+  return {
+    ok: stacks.every(
+      ({ consistency, resourceDrift: drift }) => consistency.ok && (!drift || drift.ok)
+    ),
+    packageVersion: plan.packageVersion,
+    stacks
+  };
+}
+
 // packages/aws/src/handoff.ts
 var githubSubjectKeys = [
   "repository_owner",
@@ -927,7 +1297,7 @@ var githubSubjectKeys = [
   "repository_id",
   "context"
 ];
-function outputValues(stack) {
+function outputValues2(stack) {
   return Object.fromEntries(
     (stack.Outputs ?? []).filter(
       (entry) => typeof entry.OutputKey === "string" && typeof entry.OutputValue === "string"
@@ -963,11 +1333,17 @@ function stackName(config, kind) {
     `${kind}.stackName`
   );
 }
+function workFile(workDir, name) {
+  return workDir ? `${workDir.replace(/\/+$/, "")}/${name}` : name;
+}
 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 = [
+    "npm",
+    "exec",
+    "--",
     "ze-great-dashboard-aws",
     "bootstrap",
     "parameters",
@@ -1036,7 +1412,7 @@ function changeSetCommands(input) {
     },
     {
       name: "capture-stack",
-      captureFile: `${input.kind}-deployed-stack.json`,
+      captureFile: workFile(input.workDir, `${input.kind}-deployed-stack.json`),
       args: ["aws", "cloudformation", "describe-stacks", ...common, "--no-cli-pager"]
     }
   ];
@@ -1090,7 +1466,7 @@ async function contracts() {
 }
 async function bootstrapHandoff(input) {
   const expectedContracts = await contracts();
-  const coreCapturePath = input.coreStackPath ?? "core-deployed-stack.json";
+  const coreCapturePath = input.coreStackPath ?? workFile(input.workDir, "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) {
@@ -1104,9 +1480,10 @@ async function bootstrapHandoff(input) {
       phase: "core",
       expectedContracts,
       templatePath,
-      parameterPath: "core-bootstrap.json",
+      parameterPath: workFile(input.workDir, "core-bootstrap.json"),
       expectedOutputs: [
         "BootstrapContractVersion",
+        "BootstrapTemplateRevision",
         "ArtifactBucketName",
         "ApplicationStackName",
         "CloudFormationExecutionRoleArn"
@@ -1121,7 +1498,8 @@ async function bootstrapHandoff(input) {
         config: input.config,
         configPath: input.configPath,
         templatePath,
-        parameterPath: "core-bootstrap.json"
+        parameterPath: workFile(input.workDir, "core-bootstrap.json"),
+        workDir: input.workDir
       })
     };
   }
@@ -1133,6 +1511,7 @@ async function bootstrapHandoff(input) {
       GitHubOwnerId: input.config.githubOidc?.ownerId,
       GitHubRepositoryId: input.config.githubOidc?.repositoryId,
       GitHubEnvironment: input.config.githubOidc?.environment,
+      CoreBootstrapStackName: input.config.core?.stackName,
       ConsumerGatewayStackName: input.config.githubOidc?.consumerGatewayStackName,
       ...coreBootstrapOutputs(core)
     });
@@ -1141,7 +1520,7 @@ async function bootstrapHandoff(input) {
       phase: "github-oidc",
       expectedContracts,
       templatePath,
-      parameterPath: "github-oidc-bootstrap.json",
+      parameterPath: workFile(input.workDir, "github-oidc-bootstrap.json"),
       expectedOutputs: [
         "BootstrapContractVersion",
         "BootstrapTemplateRevision",
@@ -1157,8 +1536,9 @@ async function bootstrapHandoff(input) {
         config: input.config,
         configPath: input.configPath,
         templatePath,
-        parameterPath: "github-oidc-bootstrap.json",
-        coreCapturePath
+        parameterPath: workFile(input.workDir, "github-oidc-bootstrap.json"),
+        coreCapturePath,
+        workDir: input.workDir
       }),
       prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
         input.config,
@@ -1170,12 +1550,13 @@ async function bootstrapHandoff(input) {
     input.config,
     input.runner
   );
+  const githubOidcCapturePath = input.githubOidcStackPath ?? workFile(input.workDir, "github-oidc-deployed-stack.json");
   if (prerequisite.status !== "ready")
     return {
       phase: "github-environment",
       expectedContracts,
       expectedOutputs: [],
-      requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+      requiredCapturedFiles: [coreCapturePath, githubOidcCapturePath],
       reviewCheckpoints: [
         "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
       ],
@@ -1186,7 +1567,7 @@ async function bootstrapHandoff(input) {
     phase: "application-gateway",
     expectedContracts,
     expectedOutputs: [],
-    requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+    requiredCapturedFiles: [coreCapturePath, githubOidcCapturePath],
     reviewCheckpoints: [
       "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
     ],
@@ -1267,7 +1648,7 @@ async function verifyBootstrap(input) {
   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;
+  const deployRole = outputValues2(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];
@@ -1544,8 +1925,13 @@ function quote(args2) {
 }
 async function bootstrapGuide(input) {
   const handoff = await bootstrapHandoff(input);
+  const plan = await bootstrapPlan(input.config);
   const lines = [
     `Phase: ${handoff.phase}`,
+    `Package version: ${plan.packageVersion}`,
+    ...plan.packageTemplates.map(
+      (template) => `Template ${template.kind}: contract ${template.contractVersion}${template.templateRevision ? `, revision ${template.templateRevision}` : ""}, sha256 ${template.sha256}`
+    ),
     `Required captures: ${handoff.requiredCapturedFiles.join(", ") || "none"}`
   ];
   if (handoff.expectedOutputs.length)
@@ -1558,7 +1944,9 @@ async function bootstrapGuide(input) {
       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)}`);
+    lines.push(
+      command.captureFile ? `${quote(command.args)} > ${quote([command.captureFile])}` : quote(command.args)
+    );
   }
   if (handoff.reviewCheckpoints.length)
     lines.push("", "Review pauses:", ...handoff.reviewCheckpoints.map((item) => `- ${item}`));
@@ -1939,16 +2327,17 @@ function bootstrapValues(config, coreOutputs = {}) {
       coreOutputs.ApplicationStackName ?? config.core?.applicationStackName
     ),
     DashboardFunctionName: option("--function-name", config.core?.dashboardFunctionName),
-    RuntimeSecretArn: option("--runtime-secret-arn", config.core?.runtimeSecretArn),
-    ArtifactKmsKeyArn: option("--artifact-kms-key-arn", config.core?.artifactKmsKeyArn),
+    RuntimeSecretArn: option("--runtime-secret-arn", config.core?.runtimeSecretArn ?? ""),
+    ArtifactKmsKeyArn: option("--artifact-kms-key-arn", config.core?.artifactKmsKeyArn ?? ""),
     GitHubOidcProviderArn: option("--github-oidc-provider-arn", config.githubOidc?.providerArn),
     GitHubRepository: option("--github-repository", config.githubOidc?.repository),
     GitHubOwnerId: option("--github-owner-id", config.githubOidc?.ownerId),
     GitHubRepositoryId: option("--github-repository-id", config.githubOidc?.repositoryId),
     GitHubEnvironment: option("--github-environment", config.githubOidc?.environment),
+    CoreBootstrapStackName: config.core?.stackName,
     ConsumerGatewayStackName: option(
       "--consumer-gateway-stack",
-      config.githubOidc?.consumerGatewayStackName
+      config.githubOidc?.consumerGatewayStackName ?? ""
     ),
     CloudFormationExecutionRoleArn: option(
       "--execution-role-arn",
@@ -2149,9 +2538,11 @@ try {
           await bootstrapGuide({
             config,
             configPath,
+            workDir: option("--work-dir"),
             coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
             coreStackPath,
             githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+            githubOidcStackPath: githubStackPath,
             runner
           })
         );
@@ -2171,9 +2562,11 @@ try {
             await bootstrapHandoff({
               config,
               configPath,
+              workDir: option("--work-dir"),
               coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
               coreStackPath,
               githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+              githubOidcStackPath: githubStackPath,
               runner
             })
           )
@@ -2200,6 +2593,42 @@ try {
             contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind))
           })
         );
+      } else if (action === "plan") {
+        requiredOption("--config");
+        const plan = await bootstrapPlan(config);
+        if (option("--format") === "text") {
+          console.log("AWS bootstrap plan (read-only)");
+          console.log(`Package version: ${plan.packageVersion}`);
+          for (const template of plan.packageTemplates) {
+            console.log(`
+${template.kind}: ${template.path}`);
+            console.log(`  contract: ${template.contractVersion}`);
+            if (template.templateRevision) console.log(`  revision: ${template.templateRevision}`);
+            console.log(`  sha256: ${template.sha256}`);
+            console.log(
+              `  resources: ${template.resources.map(({ logicalId, type }) => `${logicalId} (${type})`).join(", ")}`
+            );
+            console.log(`  declared IAM actions: ${template.iamActions.join(", ") || "none"}`);
+          }
+          console.log(`
+${plan.notes.join("\n")}`);
+        } else console.log(JSON.stringify(plan));
+      } else if (action === "check") {
+        requiredOption("--config");
+        const { execFile: execFile3 } = await import("node:child_process");
+        const { promisify: promisify3 } = await import("node:util");
+        const result = await checkBootstrap(
+          config,
+          { resourceDrift: args.includes("--resource-drift") },
+          {
+            async execute(command, commandArgs) {
+              return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+            }
+          }
+        );
+        if (option("--format") === "text") process.stdout.write(formatBootstrapCheckText(result));
+        else console.log(JSON.stringify(result));
+        if (!result.ok) process.exitCode = 1;
       } else if (action === "parameters") {
         const kind = bootstrapKind();
         const output = option("--output", `aws-dashboard-bootstrap-${kind}.json`) ?? `aws-dashboard-bootstrap-${kind}.json`;
@@ -2234,33 +2663,14 @@ try {
         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);
+        const plan = await bootstrapPlan(config);
+        const template = plan.packageTemplates.find((candidate) => candidate.kind === kind);
         await existingParameters(parametersPath);
         const awsCommand = [
           "aws",
@@ -2284,6 +2694,10 @@ try {
         console.log(
           JSON.stringify({
             kind,
+            packageVersion: plan.packageVersion,
+            contractVersion: template?.contractVersion,
+            templateRevision: template?.templateRevision,
+            templateSha256: template?.sha256,
             reviewRequired: true,
             awsCommand,
             shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
@@ -2291,7 +2705,7 @@ try {
         );
       } 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]"
+          "Usage: ze-great-dashboard-aws bootstrap init|preflight|plan|check|guide|handoff|verify --config manifest.json [options], or bootstrap template|parameters|change-set --kind core|github-oidc [options]"
         );
       }
     }

package/dist/guided.d.ts

@@ -1,4 +1,4 @@
-import type { BootstrapConfig } from './bootstrap.js';
+import { type BootstrapConfig } from './bootstrap.js';
 import { type BootstrapProvider, bootstrapHandoff, type CommandRunner } from './handoff.js';
 export type BootstrapCheckStatus = 'ready' | 'missing' | 'mismatch' | 'unverified';
 export type BootstrapPreflightCheck = {