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

package/dist/handoff.d.ts

@@ -48,9 +48,11 @@ export declare const githubOidcProvider: BootstrapProvider;
 export declare function bootstrapHandoff(input: {
     config: BootstrapConfig;
     configPath: string;
+    workDir?: string;
     coreStack?: unknown;
     coreStackPath?: string;
     githubOidcStack?: unknown;
+    githubOidcStackPath?: string;
     provider?: BootstrapProvider;
     runner?: CommandRunner;
 }): Promise<BootstrapHandoff>;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { type BootstrapConfig, type BootstrapKind, bootstrapContractVersion, bootstrapTemplate, bootstrapTemplatePath, bootstrapTemplateRevision, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
+export { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind, type BootstrapPlan, type BootstrapTemplateInspection, bootstrapConsistency, bootstrapContractVersion, bootstrapPlan, bootstrapTemplate, bootstrapTemplatePath, bootstrapTemplateRevision, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
+export { type BootstrapCheck, type BootstrapCheckDependencies, type BootstrapResourceDifference, type BootstrapResourceDrift, type BootstrapResourceDriftResult, type BootstrapStackCheck, checkBootstrap, formatBootstrapCheckText, } from './bootstrap-check.js';
 export { type BootstrapCheckStatus, type BootstrapInitInput, type BootstrapPreflight, type BootstrapPreflightCheck, bootstrapGuide, bootstrapPreflight, scaffoldBootstrapManifest, } from './guided.js';
 export { type BootstrapHandoff, type BootstrapPhase, type BootstrapProvider, type BootstrapVerification, bootstrapHandoff, type CommandRunner, githubOidcProvider, verifyBootstrap, } from './handoff.js';
 export type ReleaseMetadata = {

package/dist/index.js

@@ -849,6 +849,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);
@@ -896,6 +1015,7 @@ function requiredBootstrapParameters(kind, values) {
     "GitHubOwnerId",
     "GitHubRepositoryId",
     "GitHubEnvironment",
+    "CoreBootstrapStackName",
     "ApplicationStackName",
     "ArtifactBucketName",
     "CloudFormationExecutionRoleArn"
@@ -906,6 +1026,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",
@@ -914,7 +1284,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"
@@ -950,11 +1320,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",
@@ -1023,7 +1399,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"]
     }
   ];
@@ -1077,7 +1453,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) {
@@ -1091,9 +1467,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"
@@ -1108,7 +1485,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
       })
     };
   }
@@ -1120,6 +1498,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)
     });
@@ -1128,7 +1507,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",
@@ -1144,8 +1523,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,
@@ -1157,12 +1537,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."
       ],
@@ -1173,7 +1554,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."
     ],
@@ -1254,7 +1635,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];
@@ -1531,8 +1912,13 @@ function quote(args) {
 }
 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)
@@ -1545,7 +1931,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}`));
@@ -1704,17 +2092,21 @@ async function cloudFormationTemplate() {
   return readFile3(fileURLToPath2(new URL("../template.yml", import.meta.url)), "utf8");
 }
 export {
+  bootstrapConsistency,
   bootstrapContractVersion,
   bootstrapGuide,
   bootstrapHandoff,
+  bootstrapPlan,
   bootstrapPreflight,
   bootstrapTemplate,
   bootstrapTemplatePath,
   bootstrapTemplateRevision,
+  checkBootstrap,
   cloudFormationTemplate,
   coreBootstrapOutputs,
   deployLambda,
   deployedBootstrapStack,
+  formatBootstrapCheckText,
   githubOidcProvider,
   mergeBootstrapParameters,
   packageLambda,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [