@continuous-excellence/ze-great-dashboard-aws 0.14.3 → 0.14.5

package/dist/bootstrap-check.d.ts

@@ -1,4 +1,5 @@
 import { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind } from './bootstrap.js';
+import { type BootstrapRemediation } from './remediation.js';
 export type BootstrapResourceDifference = {
     path?: string;
     differenceType?: string;
@@ -32,6 +33,7 @@ export type BootstrapCheck = {
     ok: boolean;
     packageVersion: string;
     stacks: BootstrapStackCheck[];
+    remediation: BootstrapRemediation;
 };
 export type BootstrapCheckDependencies = {
     execute(command: string, args: string[]): Promise<string>;

package/dist/bootstrap.d.ts

@@ -1,4 +1,5 @@
 import { type ComputeMode } from './compute-mode.js';
+import { type BootstrapRemediation } from './remediation.js';
 export { type ComputeMode, computeMode, resolveComputeMode } from './compute-mode.js';
 export type BootstrapKind = 'core' | 'github-oidc';
 export type CloudFormationParameterValue = {
@@ -55,6 +56,7 @@ export type BootstrapPlan = {
     packageTemplates: BootstrapTemplateInspection[];
     configuration: BootstrapConfig;
     notes: string[];
+    remediation: BootstrapRemediation;
 };
 export type BootstrapConsistency = {
     ok: boolean;

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 // packages/aws/src/cli.ts
+import { execFile as execFile3 } from "node:child_process";
 import { readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { promisify as promisify3 } from "node:util";
 import { parse as parse3 } from "yaml";
 
 // packages/aws/src/doctor.ts
@@ -159,6 +161,46 @@ function sha256(value2) {
   return createHash("sha256").update(value2).digest("hex");
 }
 
+// packages/aws/src/remediation.ts
+var safetyNote = "AWS mutations are emitted for explicit administrator review and invocation; this library never executes them.";
+function bootstrapRemediation(config, input = {}) {
+  const affectedStacks = input.affectedStacks ?? [
+    ["core", config.core?.stackName],
+    ["github-oidc", config.githubOidc?.stackName]
+  ].filter((entry) => Boolean(entry[1])).map(([kind, stackName2]) => ({ kind, stackName: stackName2 }));
+  const configPath = input.configPath ?? "manifest.json";
+  const checkCommand = `ze-great-dashboard-aws bootstrap check --config ${configPath} --format json`;
+  const issues = input.issues ?? [];
+  const summary = input.summary ?? (issues.length ? `Bootstrap validation found ${issues.length} issue${issues.length === 1 ? "" : "s"}.` : "Bootstrap validation is ready for the next reviewed operation.");
+  return {
+    failureSummary: summary,
+    affectedStacks,
+    immediateSteps: [
+      ...issues.length ? ["Review each reported mismatch, access error, or drift finding."] : [],
+      input.nextOperation ?? "Run the next bootstrap operation from the generated handoff.",
+      "Capture the resulting CloudFormation stack output for the next validation step."
+    ],
+    upgradeSteps: [
+      "If the contract or template revision is stale, generate parameters from this installed package and create a reviewed UPDATE change set for each affected stack.",
+      "Review IAM actions, retained resources, parameters, and the change set before an administrator executes it."
+    ],
+    revalidateCommand: checkCommand,
+    safetyNote
+  };
+}
+function formatBootstrapRemediationText(remediation) {
+  return [
+    `Remediation: ${remediation.failureSummary}`,
+    `Affected stacks: ${remediation.affectedStacks.length ? remediation.affectedStacks.map(({ kind, stackName: stackName2, issue }) => `${kind}=${stackName2}${issue ? ` (${issue})` : ""}`).join(", ") : "none identified"}`,
+    "Immediate steps:",
+    ...remediation.immediateSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    "Upgrade steps:",
+    ...remediation.upgradeSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    `Revalidate: ${remediation.revalidateCommand}`,
+    `Safety: ${remediation.safetyNote}`
+  ];
+}
+
 // packages/aws/src/bootstrap.ts
 var templates = {
   core: {
@@ -231,7 +273,10 @@ async function bootstrapPlan(config) {
       "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."
-    ]
+    ],
+    remediation: bootstrapRemediation(config, {
+      nextOperation: "Review the installed templates, then run bootstrap preflight before creating a change set."
+    })
   };
 }
 function capturedStack(input) {
@@ -1118,6 +1163,7 @@ function formatBootstrapCheckText(result) {
         );
     }
   }
+  lines.push("", ...formatBootstrapRemediationText(result.remediation));
   return `${lines.join("\n")}
 `;
 }
@@ -1337,12 +1383,30 @@ async function checkBootstrap(config, options, dependencies) {
       return checked;
     })
   );
+  const failed = stacks.filter(
+    ({ consistency, resourceDrift: resourceDrift2 }) => !consistency.ok || Boolean(resourceDrift2 && !resourceDrift2.ok)
+  );
   return {
     ok: stacks.every(
       ({ consistency, resourceDrift: drift }) => consistency.ok && (!drift || drift.ok)
     ),
     packageVersion: plan.packageVersion,
-    stacks
+    stacks,
+    remediation: bootstrapRemediation(config, {
+      summary: failed.length ? `Bootstrap validation failed for ${failed.length} stack${failed.length === 1 ? "" : "s"}.` : "Bootstrap stacks are consistent and ready for the deployment check.",
+      affectedStacks: (failed.length ? failed : stacks).map(
+        ({ kind, stackName: stackName2, consistency, resourceDrift: resourceDrift2 }) => ({
+          kind,
+          stackName: stackName2,
+          ...!consistency.ok ? { issue: consistency.mismatches[0] ?? "consistency mismatch" } : resourceDrift2 && !resourceDrift2.ok ? { issue: `resource drift: ${resourceDrift2.status}` } : {}
+        })
+      ),
+      nextOperation: failed.length ? "Apply only reviewed administrator-approved bootstrap updates, then capture both stacks again." : "Run the deployment or release check that consumes these bootstrap outputs.",
+      issues: failed.flatMap(({ consistency, resourceDrift: resourceDrift2 }) => [
+        ...consistency.mismatches,
+        ...resourceDrift2 && !resourceDrift2.ok ? [`resource drift: ${resourceDrift2.status}`] : []
+      ])
+    })
   };
 }
 
@@ -1476,7 +1540,7 @@ function changeSetCommands(input) {
 }
 var githubOidcProvider = {
   name: "github-oidc",
-  async prerequisite(config, runner) {
+  async prerequisite(config, runner2) {
     const repository = config.githubOidc?.repository;
     if (!repository)
       return {
@@ -1484,7 +1548,7 @@ var githubOidcProvider = {
         blocking: false,
         detail: "GitHub repository is absent from the manifest."
       };
-    if (!runner)
+    if (!runner2)
       return {
         status: "unverified",
         blocking: false,
@@ -1492,7 +1556,7 @@ var githubOidcProvider = {
       };
     try {
       const response = JSON.parse(
-        await runner.execute("gh", ["api", `repos/${repository}/actions/oidc/customization/sub`])
+        await runner2.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)))
@@ -1559,6 +1623,10 @@ async function bootstrapHandoff(input) {
         templatePath,
         parameterPath: workFile(input.workDir, "core-bootstrap.json"),
         workDir: input.workDir
+      }),
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        nextOperation: "Review and execute the core bootstrap change set, then capture the core stack."
       })
     };
   }
@@ -1602,7 +1670,11 @@ async function bootstrapHandoff(input) {
       prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
         input.config,
         input.runner
-      )
+      ),
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        nextOperation: "Review and execute the GitHub OIDC change set, then capture the GitHub OIDC stack."
+      })
     };
   }
   const prerequisite = await (input.provider ?? githubOidcProvider).prerequisite(
@@ -1620,7 +1692,12 @@ async function bootstrapHandoff(input) {
         "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
       ],
       commands: [],
-      prerequisite
+      prerequisite,
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        summary: "The GitHub Environment immutable-subject prerequisite is not verified.",
+        nextOperation: "A GitHub administrator must complete and verify the immutable-subject migration, then rerun bootstrap handoff."
+      })
     };
   return {
     phase: "application-gateway",
@@ -1631,7 +1708,11 @@ async function bootstrapHandoff(input) {
       "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
     ],
     commands: [],
-    prerequisite
+    prerequisite,
+    remediation: bootstrapRemediation(input.config, {
+      configPath: input.configPath,
+      nextOperation: "Configure and verify the consumer gateway, then run bootstrap verify and the deployment check."
+    })
   };
 }
 function assertEqual(actual, expected, label) {
@@ -1751,7 +1832,10 @@ async function verifyBootstrap(input) {
         "--body",
         executionRole
       ]
-    ]
+    ],
+    remediation: bootstrapRemediation(input.config, {
+      nextOperation: "Set the reviewed GitHub Environment variables, then run bootstrap check before deployment."
+    })
   };
 }
 
@@ -1768,10 +1852,10 @@ function repositoryParts(repository) {
 function accountFromArn(arn) {
   return arn.match(/^arn:[^:]+:iam::(\d+):oidc-provider\//)?.[1];
 }
-async function optional(runner, command, args2) {
-  if (!runner) return void 0;
+async function optional(runner2, command, args2) {
+  if (!runner2) return void 0;
   try {
-    return await runner.execute(command, args2);
+    return await runner2.execute(command, args2);
   } catch {
     return void 0;
   }
@@ -1869,9 +1953,18 @@ async function bootstrapPreflight(input) {
   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", [
+  if (missing.length)
+    return {
+      ready: false,
+      checks,
+      remediation: bootstrapRemediation(input.config, {
+        summary: "Bootstrap manifest configuration is incomplete.",
+        issues: missing,
+        nextOperation: "Complete the missing manifest fields, then rerun bootstrap preflight."
+      })
+    };
+  const runner2 = input.runner;
+  const identityRaw = await optional(runner2, "aws", [
     "sts",
     "get-caller-identity",
     "--output",
@@ -1897,7 +1990,7 @@ async function bootstrapPreflight(input) {
         detail: `AWS account ${identity.Account} does not match provider account ${providerAccount}.`
       }
     );
-  const regionRaw = await optional(runner, "aws", ["configure", "get", "region"]);
+  const regionRaw = await optional(runner2, "aws", ["configure", "get", "region"]);
   if (!regionRaw?.trim())
     checks.push({
       name: "aws-region",
@@ -1912,7 +2005,7 @@ async function bootstrapPreflight(input) {
         detail: `AWS Region ${regionRaw.trim()} does not match manifest ${input.config.region}.`
       }
     );
-  const providerRaw = await optional(runner, "aws", [
+  const providerRaw = await optional(runner2, "aws", [
     "iam",
     "get-open-id-connect-provider",
     "--open-id-connect-provider-arn",
@@ -1926,7 +2019,7 @@ async function bootstrapPreflight(input) {
     } : 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 repoRaw = await optional(runner2, "gh", ["api", `repos/${repository}`]);
   const repo = parseOrUnavailable(repoRaw);
   if (!repoRaw)
     checks.push({
@@ -1952,7 +2045,7 @@ async function bootstrapPreflight(input) {
       status: "ready",
       detail: "GitHub repository identity matches the manifest."
     });
-  const environmentRaw = await optional(runner, "gh", [
+  const environmentRaw = await optional(runner2, "gh", [
     "api",
     `repos/${repository}/environments/${input.config.githubOidc?.environment}`
   ]);
@@ -1971,23 +2064,28 @@ async function bootstrapPreflight(input) {
       detail: "GitHub Environment exists; its policy is administrator-owned context."
     }
   );
-  const subject = await (input.provider ?? githubOidcProvider).prerequisite(input.config, runner);
+  const subject = await (input.provider ?? githubOidcProvider).prerequisite(input.config, runner2);
   checks.push({
     name: "immutable-subject",
     status: subject.status === "immutable-subject-required" ? "mismatch" : subject.status,
     detail: subject.detail
   });
+  const ready = !checks.some(({ status }) => status === "missing" || status === "mismatch");
   return {
-    ready: !checks.some(({ status }) => status === "missing" || status === "mismatch"),
-    checks
+    ready,
+    checks,
+    remediation: bootstrapRemediation(input.config, {
+      summary: ready ? "Bootstrap preflight is ready." : "Bootstrap preflight found configuration or identity issues.",
+      issues: checks.filter(({ status }) => status === "missing" || status === "mismatch").map(({ detail }) => detail),
+      nextOperation: ready ? "Run bootstrap plan, then create and review the next bootstrap change set." : "Resolve the reported configuration or identity issues, then rerun bootstrap preflight."
+    })
   };
 }
 function quote(args2) {
   return args2.map((arg) => `'${arg.replaceAll("'", `'\\"'\\"'`)}'`).join(" ");
 }
-async function bootstrapGuide(input) {
-  const handoff = await bootstrapHandoff(input);
-  const plan = await bootstrapPlan(input.config);
+async function bootstrapGuideReport(input) {
+  const [handoff, plan] = await Promise.all([bootstrapHandoff(input), bootstrapPlan(input.config)]);
   const lines = [
     `Phase: ${handoff.phase}`,
     `Package version: ${plan.packageVersion}`,
@@ -2024,8 +2122,9 @@ async function bootstrapGuide(input) {
     );
     for (const command of verified.githubEnvironmentInstructions) lines.push(quote(command));
   }
-  return `${lines.join("\n")}
-`;
+  lines.push("", ...formatBootstrapRemediationText(plan.remediation));
+  return { handoff, plan, guide: `${lines.join("\n")}
+` };
 }
 
 // packages/aws/src/index.ts
@@ -2357,11 +2456,20 @@ async function runDoctor(options, dependencies = actualDependencies) {
       checkResult.detail = `WARNING: ${checkResult.detail}`;
     }
   }
-  return checks;
+  const remediation = bootstrapRemediation(
+    {},
+    {
+      summary: checks.some(({ ok }) => !ok) ? "Deployment doctor found issues that require operator review." : "Deployment doctor is healthy; proceed to the deployment check.",
+      issues: checks.filter(({ ok }) => !ok).map(({ detail }) => detail),
+      nextOperation: checks.some(({ ok }) => !ok) ? "Resolve failed checks, then rerun the deployment doctor and bootstrap check." : "Run bootstrap check before deploying the release."
+    }
+  );
+  return checks.map((check2) => ({ ...check2, remediation }));
 }
 
 // packages/aws/src/cli.ts
 var args = process.argv.slice(2);
+var runCommand = promisify3(execFile3);
 var option = (name, fallback) => {
   const i2 = args.indexOf(name);
   return i2 >= 0 ? args[i2 + 1] : fallback;
@@ -2451,6 +2559,38 @@ function bootstrapStackName(kind, config) {
 function shellCommand(command) {
   return command.map((argument) => `'${argument.replaceAll("'", `'\\"'\\"'`)}'`).join(" ");
 }
+function outputFormat(defaultFormat = "json") {
+  if (args.includes("--format-shell")) return "shell";
+  const format = option("--format", defaultFormat);
+  if (format !== "json" && format !== "text") throw new Error("--format must be json or text");
+  return format;
+}
+function printBootstrap(value2, text, shell, defaultFormat = "json") {
+  const format = outputFormat(defaultFormat);
+  if (format === "shell") {
+    if (!shell) throw new Error("--format-shell is only supported for command handoffs");
+    console.log(shell);
+  } else if (format === "text") console.log(text);
+  else console.log(JSON.stringify(value2));
+}
+var runner = {
+  async execute(command, commandArgs) {
+    return (await runCommand(command, commandArgs)).stdout.trim();
+  }
+};
+var preflightRunner = {
+  async execute(command, commandArgs) {
+    try {
+      return await runner.execute(command, commandArgs);
+    } 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;
+    }
+  }
+};
 async function templateParameters(mode = "lambda") {
   const template = await cloudFormationTemplate(mode);
   const block = template.match(/^Parameters:\n[\s\S]*?(?=^[A-Za-z][A-Za-z0-9]*:\s*$)/m)?.[0];
@@ -2574,11 +2714,7 @@ try {
         githubOidcStackPath: option("--github-oidc-stack-json")
       },
       {
-        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();
-        },
+        execute: runner.execute,
         async fetch(url) {
           return fetch(url);
         },
@@ -2586,10 +2722,14 @@ try {
         packageVersion
       }
     );
-    for (const check of checks)
-      console.log(
-        `${check.warning ? "WARN" : check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`
-      );
+    const remediation = checks[0]?.remediation;
+    if (outputFormat("text") === "text") {
+      for (const check of checks)
+        console.log(
+          `${check.warning ? "WARN" : check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`
+        );
+      if (remediation) console.log(formatBootstrapRemediationText(remediation).join("\n"));
+    } else console.log(JSON.stringify({ checks, remediation }));
     if (checks.some(({ ok }) => !ok)) process.exitCode = 1;
   } else if (args[0] === "parameters") {
     const output = option("--output", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
@@ -2636,7 +2776,7 @@ try {
     });
     await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
-    console.log(JSON.stringify({ output }));
+    printBootstrap({ output }, `Wrote ${output}. Next: run the generated deployment handoff.`);
   } else if (args[0] === "bootstrap") {
     const action = args[1];
     if (action === "init") {
@@ -2648,13 +2788,6 @@ try {
         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"),
@@ -2670,109 +2803,105 @@ try {
       });
       await writeFile3(output, `${JSON.stringify(manifest, null, 2)}
 `, { flag: "wx" });
-      console.log(JSON.stringify({ output, manifest }));
+      printBootstrap(
+        { output, manifest, remediation: (await bootstrapPlan(manifest)).remediation },
+        `Wrote ${output}. Next: run bootstrap preflight, then bootstrap handoff.`
+      );
     } 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));
+        const result = await bootstrapPreflight({ config, runner: preflightRunner });
+        printBootstrap(
+          result,
+          [
+            ...result.checks.map(
+              (check) => `${check.status.toUpperCase()} ${check.name}: ${check.detail}`
+            ),
+            "",
+            ...formatBootstrapRemediationText(result.remediation)
+          ].join("\n")
+        );
         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,
-            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
-          })
+        const report = await bootstrapGuideReport({
+          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
+        });
+        printBootstrap(
+          {
+            handoff: report.handoff,
+            guide: report.guide,
+            remediation: report.handoff.remediation
+          },
+          report.guide,
+          void 0,
+          "text"
         );
       } 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,
-              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
-            })
-          )
+        const handoff = 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
+        });
+        printBootstrap(
+          handoff,
+          `${JSON.stringify(handoff, null, 2)}
+${formatBootstrapRemediationText(handoff.remediation).join("\n")}`
         );
       } 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"))
-            })
-          )
+        const verified = await verifyBootstrap({
+          config,
+          coreStack: JSON.parse(await readFile5(coreStackPath, "utf8")),
+          githubOidcStack: JSON.parse(await readFile5(githubStackPath, "utf8"))
+        });
+        printBootstrap(
+          verified,
+          `Bootstrap verified.
+${formatBootstrapRemediationText(verified.remediation).join("\n")}`
         );
       } else if (action === "template") {
         const kind = bootstrapKind();
         const mode = requireComputeMode(config, option("--mode"));
-        console.log(
-          JSON.stringify({
-            kind,
-            mode,
-            template: await bootstrapTemplatePath(kind, mode),
-            contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind, mode))
+        const template = {
+          kind,
+          mode,
+          template: await bootstrapTemplatePath(kind, mode),
+          contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind, mode)),
+          remediation: bootstrapRemediation(config, {
+            nextOperation: `Review the ${kind} template, then run bootstrap parameters and create a reviewed change set.`
           })
+        };
+        printBootstrap(
+          template,
+          `Template: ${template.template}
+Contract: ${template.contractVersion}
+${formatBootstrapRemediationText(template.remediation).join("\n")}`
         );
       } else if (action === "plan") {
         requiredOption("--config");
         const plan = await bootstrapPlan(config);
-        if (option("--format") === "text") {
+        if (outputFormat() === "text") {
           console.log("AWS bootstrap plan (read-only)");
           console.log(`Package version: ${plan.packageVersion}`);
           for (const template of plan.packageTemplates) {
@@ -2788,21 +2917,18 @@ ${template.kind}: ${template.path}`);
           }
           console.log(`
 ${plan.notes.join("\n")}`);
+          console.log(formatBootstrapRemediationText(plan.remediation).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();
-            }
+            execute: runner.execute
           }
         );
-        if (option("--format") === "text") process.stdout.write(formatBootstrapCheckText(result));
+        if (outputFormat() === "text") process.stdout.write(formatBootstrapCheckText(result));
         else console.log(JSON.stringify(result));
         if (!result.ok) process.exitCode = 1;
       } else if (action === "parameters") {
@@ -2840,8 +2966,16 @@ ${plan.notes.join("\n")}`);
         }
         await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
-        console.log(
-          JSON.stringify({ output, kind, preservedDeployedValues: Boolean(deployedStackPath) })
+        const remediation = (await bootstrapPlan(config)).remediation;
+        printBootstrap(
+          {
+            output,
+            kind,
+            preservedDeployedValues: Boolean(deployedStackPath),
+            remediation
+          },
+          `Wrote ${output}. Next: review and execute the generated ${kind} change set.
+${formatBootstrapRemediationText(remediation).join("\n")}`
         );
       } else if (action === "change-set") {
         const kind = bootstrapKind();
@@ -2871,17 +3005,22 @@ ${plan.notes.join("\n")}`);
           ...region2 ? ["--region", region2] : [],
           "--no-cli-pager"
         ];
-        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
-          })
+        const handoff = {
+          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,
+          remediation: plan.remediation
+        };
+        printBootstrap(
+          handoff,
+          `Run the reviewed change set command:
+${shellCommand(awsCommand)}`,
+          shellCommand(awsCommand)
         );
       } else {
         throw new Error(

package/dist/doctor.d.ts

@@ -1,8 +1,10 @@
+import { type BootstrapRemediation } from './remediation.js';
 export type DoctorCheck = {
     name: string;
     ok: boolean;
     detail: string;
     warning?: boolean;
+    remediation?: BootstrapRemediation;
 };
 export type DoctorDependencies = {
     execute(command: string, args: string[]): Promise<string>;

package/dist/guided.d.ts

@@ -1,5 +1,6 @@
-import { type BootstrapConfig, type ComputeMode } from './bootstrap.js';
+import { type BootstrapConfig, bootstrapPlan, type ComputeMode } from './bootstrap.js';
 import { type BootstrapProvider, bootstrapHandoff, type CommandRunner } from './handoff.js';
+import { type BootstrapRemediation } from './remediation.js';
 export type BootstrapCheckStatus = 'ready' | 'missing' | 'mismatch' | 'unverified';
 export type BootstrapPreflightCheck = {
     name: string;
@@ -9,6 +10,12 @@ export type BootstrapPreflightCheck = {
 export type BootstrapPreflight = {
     ready: boolean;
     checks: BootstrapPreflightCheck[];
+    remediation: BootstrapRemediation;
+};
+export type BootstrapGuideReport = {
+    handoff: Awaited<ReturnType<typeof bootstrapHandoff>>;
+    plan: Awaited<ReturnType<typeof bootstrapPlan>>;
+    guide: string;
 };
 export type BootstrapInitInput = {
     mode?: ComputeMode;
@@ -31,4 +38,5 @@ export declare function bootstrapPreflight(input: {
     runner?: CommandRunner;
     provider?: BootstrapProvider;
 }): Promise<BootstrapPreflight>;
+export declare function bootstrapGuideReport(input: Parameters<typeof bootstrapHandoff>[0]): Promise<BootstrapGuideReport>;
 export declare function bootstrapGuide(input: Parameters<typeof bootstrapHandoff>[0]): Promise<string>;

package/dist/handoff.d.ts

@@ -1,4 +1,5 @@
 import { type BootstrapConfig } from './bootstrap.js';
+import { type BootstrapRemediation } from './remediation.js';
 export type BootstrapPhase = 'core' | 'github-oidc' | 'github-environment' | 'application-gateway';
 export type CommandRunner = {
     execute(command: string, args: string[]): Promise<string>;
@@ -30,6 +31,7 @@ export type BootstrapHandoff = {
     reviewCheckpoints: string[];
     commands: HandoffCommand[];
     prerequisite?: ProviderPrerequisite;
+    remediation: BootstrapRemediation;
 };
 export type BootstrapVerification = {
     verified: true;
@@ -43,6 +45,7 @@ export type BootstrapVerification = {
         cloudFormationExecutionRoleArn: string;
     };
     githubEnvironmentInstructions: string[][];
+    remediation: BootstrapRemediation;
 };
 export declare const githubOidcProvider: BootstrapProvider;
 export declare function bootstrapHandoff(input: {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import type { ComputeMode } from './bootstrap.js';
 export { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind, type BootstrapPlan, type BootstrapTemplateInspection, bootstrapConsistency, bootstrapContractVersion, bootstrapPlan, bootstrapTemplate, bootstrapTemplatePath, bootstrapTemplateRevision, type CloudFormationParameterValue, type ComputeMode, computeMode, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requireComputeMode, requiredBootstrapParameters, resolveComputeMode, } 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 BootstrapCheckStatus, type BootstrapGuideReport, type BootstrapInitInput, type BootstrapPreflight, type BootstrapPreflightCheck, bootstrapGuide, bootstrapGuideReport, bootstrapPreflight, scaffoldBootstrapManifest, } from './guided.js';
 export { type BootstrapHandoff, type BootstrapPhase, type BootstrapProvider, type BootstrapVerification, bootstrapHandoff, type CommandRunner, githubOidcProvider, verifyBootstrap, } from './handoff.js';
+export { type BootstrapAffectedStack, type BootstrapRemediation, type BootstrapRemediationInput, bootstrapRemediation, formatBootstrapRemediationText, } from './remediation.js';
 export type ReleaseMetadata = {
     computeMode: ComputeMode;
     dashboardVersion: string;

package/dist/index.js

@@ -872,6 +872,46 @@ function computeMode(config) {
   return resolveComputeMode({ persisted: config.mode });
 }
 
+// packages/aws/src/remediation.ts
+var safetyNote = "AWS mutations are emitted for explicit administrator review and invocation; this library never executes them.";
+function bootstrapRemediation(config, input = {}) {
+  const affectedStacks = input.affectedStacks ?? [
+    ["core", config.core?.stackName],
+    ["github-oidc", config.githubOidc?.stackName]
+  ].filter((entry) => Boolean(entry[1])).map(([kind, stackName2]) => ({ kind, stackName: stackName2 }));
+  const configPath = input.configPath ?? "manifest.json";
+  const checkCommand = `ze-great-dashboard-aws bootstrap check --config ${configPath} --format json`;
+  const issues = input.issues ?? [];
+  const summary = input.summary ?? (issues.length ? `Bootstrap validation found ${issues.length} issue${issues.length === 1 ? "" : "s"}.` : "Bootstrap validation is ready for the next reviewed operation.");
+  return {
+    failureSummary: summary,
+    affectedStacks,
+    immediateSteps: [
+      ...issues.length ? ["Review each reported mismatch, access error, or drift finding."] : [],
+      input.nextOperation ?? "Run the next bootstrap operation from the generated handoff.",
+      "Capture the resulting CloudFormation stack output for the next validation step."
+    ],
+    upgradeSteps: [
+      "If the contract or template revision is stale, generate parameters from this installed package and create a reviewed UPDATE change set for each affected stack.",
+      "Review IAM actions, retained resources, parameters, and the change set before an administrator executes it."
+    ],
+    revalidateCommand: checkCommand,
+    safetyNote
+  };
+}
+function formatBootstrapRemediationText(remediation) {
+  return [
+    `Remediation: ${remediation.failureSummary}`,
+    `Affected stacks: ${remediation.affectedStacks.length ? remediation.affectedStacks.map(({ kind, stackName: stackName2, issue }) => `${kind}=${stackName2}${issue ? ` (${issue})` : ""}`).join(", ") : "none identified"}`,
+    "Immediate steps:",
+    ...remediation.immediateSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    "Upgrade steps:",
+    ...remediation.upgradeSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    `Revalidate: ${remediation.revalidateCommand}`,
+    `Safety: ${remediation.safetyNote}`
+  ];
+}
+
 // packages/aws/src/bootstrap.ts
 var templates = {
   core: {
@@ -944,7 +984,10 @@ async function bootstrapPlan(config) {
       "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."
-    ]
+    ],
+    remediation: bootstrapRemediation(config, {
+      nextOperation: "Review the installed templates, then run bootstrap preflight before creating a change set."
+    })
   };
 }
 function capturedStack(input) {
@@ -1105,6 +1148,7 @@ function formatBootstrapCheckText(result) {
         );
     }
   }
+  lines.push("", ...formatBootstrapRemediationText(result.remediation));
   return `${lines.join("\n")}
 `;
 }
@@ -1324,12 +1368,30 @@ async function checkBootstrap(config, options, dependencies) {
       return checked;
     })
   );
+  const failed = stacks.filter(
+    ({ consistency, resourceDrift: resourceDrift2 }) => !consistency.ok || Boolean(resourceDrift2 && !resourceDrift2.ok)
+  );
   return {
     ok: stacks.every(
       ({ consistency, resourceDrift: drift }) => consistency.ok && (!drift || drift.ok)
     ),
     packageVersion: plan.packageVersion,
-    stacks
+    stacks,
+    remediation: bootstrapRemediation(config, {
+      summary: failed.length ? `Bootstrap validation failed for ${failed.length} stack${failed.length === 1 ? "" : "s"}.` : "Bootstrap stacks are consistent and ready for the deployment check.",
+      affectedStacks: (failed.length ? failed : stacks).map(
+        ({ kind, stackName: stackName2, consistency, resourceDrift: resourceDrift2 }) => ({
+          kind,
+          stackName: stackName2,
+          ...!consistency.ok ? { issue: consistency.mismatches[0] ?? "consistency mismatch" } : resourceDrift2 && !resourceDrift2.ok ? { issue: `resource drift: ${resourceDrift2.status}` } : {}
+        })
+      ),
+      nextOperation: failed.length ? "Apply only reviewed administrator-approved bootstrap updates, then capture both stacks again." : "Run the deployment or release check that consumes these bootstrap outputs.",
+      issues: failed.flatMap(({ consistency, resourceDrift: resourceDrift2 }) => [
+        ...consistency.mismatches,
+        ...resourceDrift2 && !resourceDrift2.ok ? [`resource drift: ${resourceDrift2.status}`] : []
+      ])
+    })
   };
 }
 
@@ -1546,6 +1608,10 @@ async function bootstrapHandoff(input) {
         templatePath,
         parameterPath: workFile(input.workDir, "core-bootstrap.json"),
         workDir: input.workDir
+      }),
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        nextOperation: "Review and execute the core bootstrap change set, then capture the core stack."
       })
     };
   }
@@ -1589,7 +1655,11 @@ async function bootstrapHandoff(input) {
       prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
         input.config,
         input.runner
-      )
+      ),
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        nextOperation: "Review and execute the GitHub OIDC change set, then capture the GitHub OIDC stack."
+      })
     };
   }
   const prerequisite = await (input.provider ?? githubOidcProvider).prerequisite(
@@ -1607,7 +1677,12 @@ async function bootstrapHandoff(input) {
         "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
       ],
       commands: [],
-      prerequisite
+      prerequisite,
+      remediation: bootstrapRemediation(input.config, {
+        configPath: input.configPath,
+        summary: "The GitHub Environment immutable-subject prerequisite is not verified.",
+        nextOperation: "A GitHub administrator must complete and verify the immutable-subject migration, then rerun bootstrap handoff."
+      })
     };
   return {
     phase: "application-gateway",
@@ -1618,7 +1693,11 @@ async function bootstrapHandoff(input) {
       "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
     ],
     commands: [],
-    prerequisite
+    prerequisite,
+    remediation: bootstrapRemediation(input.config, {
+      configPath: input.configPath,
+      nextOperation: "Configure and verify the consumer gateway, then run bootstrap verify and the deployment check."
+    })
   };
 }
 function assertEqual(actual, expected, label) {
@@ -1738,7 +1817,10 @@ async function verifyBootstrap(input) {
         "--body",
         executionRole
       ]
-    ]
+    ],
+    remediation: bootstrapRemediation(input.config, {
+      nextOperation: "Set the reviewed GitHub Environment variables, then run bootstrap check before deployment."
+    })
   };
 }
 
@@ -1856,7 +1938,16 @@ async function bootstrapPreflight(input) {
   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 };
+  if (missing.length)
+    return {
+      ready: false,
+      checks,
+      remediation: bootstrapRemediation(input.config, {
+        summary: "Bootstrap manifest configuration is incomplete.",
+        issues: missing,
+        nextOperation: "Complete the missing manifest fields, then rerun bootstrap preflight."
+      })
+    };
   const runner = input.runner;
   const identityRaw = await optional(runner, "aws", [
     "sts",
@@ -1964,17 +2055,22 @@ async function bootstrapPreflight(input) {
     status: subject.status === "immutable-subject-required" ? "mismatch" : subject.status,
     detail: subject.detail
   });
+  const ready = !checks.some(({ status }) => status === "missing" || status === "mismatch");
   return {
-    ready: !checks.some(({ status }) => status === "missing" || status === "mismatch"),
-    checks
+    ready,
+    checks,
+    remediation: bootstrapRemediation(input.config, {
+      summary: ready ? "Bootstrap preflight is ready." : "Bootstrap preflight found configuration or identity issues.",
+      issues: checks.filter(({ status }) => status === "missing" || status === "mismatch").map(({ detail }) => detail),
+      nextOperation: ready ? "Run bootstrap plan, then create and review the next bootstrap change set." : "Resolve the reported configuration or identity issues, then rerun bootstrap preflight."
+    })
   };
 }
 function quote(args) {
   return args.map((arg) => `'${arg.replaceAll("'", `'\\"'\\"'`)}'`).join(" ");
 }
-async function bootstrapGuide(input) {
-  const handoff = await bootstrapHandoff(input);
-  const plan = await bootstrapPlan(input.config);
+async function bootstrapGuideReport(input) {
+  const [handoff, plan] = await Promise.all([bootstrapHandoff(input), bootstrapPlan(input.config)]);
   const lines = [
     `Phase: ${handoff.phase}`,
     `Package version: ${plan.packageVersion}`,
@@ -2011,8 +2107,12 @@ async function bootstrapGuide(input) {
     );
     for (const command of verified.githubEnvironmentInstructions) lines.push(quote(command));
   }
-  return `${lines.join("\n")}
-`;
+  lines.push("", ...formatBootstrapRemediationText(plan.remediation));
+  return { handoff, plan, guide: `${lines.join("\n")}
+` };
+}
+async function bootstrapGuide(input) {
+  return (await bootstrapGuideReport(input)).guide;
 }
 
 // packages/aws/src/index.ts
@@ -2190,9 +2290,11 @@ export {
   bootstrapConsistency,
   bootstrapContractVersion,
   bootstrapGuide,
+  bootstrapGuideReport,
   bootstrapHandoff,
   bootstrapPlan,
   bootstrapPreflight,
+  bootstrapRemediation,
   bootstrapTemplate,
   bootstrapTemplatePath,
   bootstrapTemplateRevision,
@@ -2202,6 +2304,7 @@ export {
   coreBootstrapOutputs,
   deployedBootstrapStack,
   formatBootstrapCheckText,
+  formatBootstrapRemediationText,
   githubOidcProvider,
   mergeBootstrapParameters,
   packageEcs,

package/dist/remediation.d.ts

@@ -0,0 +1,23 @@
+import type { BootstrapConfig, BootstrapKind } from './bootstrap.js';
+export type BootstrapAffectedStack = {
+    kind: BootstrapKind;
+    stackName: string;
+    issue?: string;
+};
+export type BootstrapRemediation = {
+    failureSummary: string;
+    affectedStacks: BootstrapAffectedStack[];
+    immediateSteps: string[];
+    upgradeSteps: string[];
+    revalidateCommand: string;
+    safetyNote: string;
+};
+export type BootstrapRemediationInput = {
+    summary?: string;
+    affectedStacks?: BootstrapAffectedStack[];
+    configPath?: string;
+    nextOperation?: string;
+    issues?: string[];
+};
+export declare function bootstrapRemediation(config: BootstrapConfig, input?: BootstrapRemediationInput): BootstrapRemediation;
+export declare function formatBootstrapRemediationText(remediation: BootstrapRemediation): string[];

package/package.json

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