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

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

@@ -159,6 +159,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 +271,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 +1161,7 @@ function formatBootstrapCheckText(result) {
         );
     }
   }
+  lines.push("", ...formatBootstrapRemediationText(result.remediation));
   return `${lines.join("\n")}
 `;
 }
@@ -1337,12 +1381,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}`] : []
+      ])
+    })
   };
 }
 
@@ -1559,6 +1621,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 +1668,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 +1690,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 +1706,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 +1830,10 @@ async function verifyBootstrap(input) {
         "--body",
         executionRole
       ]
-    ]
+    ],
+    remediation: bootstrapRemediation(input.config, {
+      nextOperation: "Set the reviewed GitHub Environment variables, then run bootstrap check before deployment."
+    })
   };
 }
 
@@ -1869,7 +1951,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",
@@ -1977,9 +2068,15 @@ 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(args2) {
@@ -2024,6 +2121,7 @@ async function bootstrapGuide(input) {
     );
     for (const command of verified.githubEnvironmentInstructions) lines.push(quote(command));
   }
+  lines.push("", ...formatBootstrapRemediationText(plan.remediation));
   return `${lines.join("\n")}
 `;
 }
@@ -2357,7 +2455,15 @@ 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
@@ -2451,6 +2557,20 @@ 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));
+}
 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];
@@ -2586,10 +2706,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 +2760,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") {
@@ -2670,7 +2794,10 @@ 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") {
@@ -2692,10 +2819,16 @@ try {
           }
         };
         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));
+        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");
@@ -2708,17 +2841,31 @@ try {
             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 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
+        });
+        const guide = 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
+        });
+        printBootstrap(
+          { handoff, guide, remediation: handoff.remediation },
+          guide,
+          void 0,
+          "text"
         );
       } else if (action === "handoff") {
         const configPath = requiredOption("--config");
@@ -2731,48 +2878,57 @@ try {
             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,6 +2944,7 @@ ${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");
@@ -2802,7 +2959,7 @@ ${plan.notes.join("\n")}`);
             }
           }
         );
-        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 +2997,15 @@ ${plan.notes.join("\n")}`);
         }
         await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
-        console.log(
-          JSON.stringify({ output, kind, preservedDeployedValues: Boolean(deployedStackPath) })
+        printBootstrap(
+          {
+            output,
+            kind,
+            preservedDeployedValues: Boolean(deployedStackPath),
+            remediation: (await bootstrapPlan(config)).remediation
+          },
+          `Wrote ${output}. Next: review and execute the generated ${kind} change set.
+${formatBootstrapRemediationText((await bootstrapPlan(config)).remediation).join("\n")}`
         );
       } else if (action === "change-set") {
         const kind = bootstrapKind();
@@ -2871,17 +3035,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: (await bootstrapPlan(config)).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 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,7 @@ export type BootstrapPreflightCheck = {
 export type BootstrapPreflight = {
     ready: boolean;
     checks: BootstrapPreflightCheck[];
+    remediation: BootstrapRemediation;
 };
 export type BootstrapInitInput = {
     mode?: ComputeMode;

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

@@ -3,6 +3,7 @@ export { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind, ty
 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 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,9 +2055,15 @@ 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) {
@@ -2011,6 +2108,7 @@ async function bootstrapGuide(input) {
     );
     for (const command of verified.githubEnvironmentInstructions) lines.push(quote(command));
   }
+  lines.push("", ...formatBootstrapRemediationText(plan.remediation));
   return `${lines.join("\n")}
 `;
 }
@@ -2193,6 +2291,7 @@ export {
   bootstrapHandoff,
   bootstrapPlan,
   bootstrapPreflight,
+  bootstrapRemediation,
   bootstrapTemplate,
   bootstrapTemplatePath,
   bootstrapTemplateRevision,
@@ -2202,6 +2301,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.4",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [