@continuous-excellence/ze-great-dashboard-aws 0.14.7 → 0.15.0

package/README.md

@@ -10,6 +10,15 @@ bootstrap initialization; routine packaging and diagnostics then select the matc
 An explicit mode fails if it disagrees with persisted configuration, so changing mode requires
 regenerating the reviewed bootstrap and parameter artifacts.
 
+`dashboard-bootstrap.json` is checked-in desired state, not a capture of AWS. If an intentionally
+upgraded package changes a bootstrap template contract or revision, run `bootstrap upgrade
+--config dashboard-bootstrap.json`, review and commit only that metadata change, then have the
+consumer's approved deployment automation preview and execute CloudFormation UPDATE change sets.
+Package upgrades that do not change bootstrap template identity do not require a manifest update or
+bootstrap redeploy. Captures and generated parameter files are disposable deployment artifacts;
+the package owns template contents and the manifest records the intended package/template identity.
+No credentials belong in the manifest.
+
 Consumer ECS deployments use the long-lived service template and provide their own subnets and
 security groups.
 

package/bootstrap/dashboard-bootstrap.example.json

@@ -1,5 +1,12 @@
 {
   "mode": "lambda",
+  "desiredState": {
+    "packageVersion": "0.0.0-dev",
+    "templates": {
+      "core": { "contractVersion": "1", "templateRevision": "1.3" },
+      "githubOidc": { "contractVersion": "2", "templateRevision": "2.3" }
+    }
+  },
   "region": "us-east-1",
   "core": {
     "stackName": "team-dashboard-bootstrap",

package/dist/bootstrap-check.d.ts

@@ -1,4 +1,4 @@
-import { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind } from './bootstrap.js';
+import { type BootstrapConfig, type BootstrapConsistency, type BootstrapDesiredStateComparison, type BootstrapKind } from './bootstrap.js';
 import { type BootstrapRemediation } from './remediation.js';
 export type BootstrapResourceDifference = {
     path?: string;
@@ -33,6 +33,7 @@ export type BootstrapCheck = {
     ok: boolean;
     packageVersion: string;
     stacks: BootstrapStackCheck[];
+    desiredState: BootstrapDesiredStateComparison;
     remediation: BootstrapRemediation;
 };
 export type BootstrapCheckDependencies = {
@@ -44,4 +45,5 @@ export declare function formatBootstrapCheckText(result: BootstrapCheck): string
 /** Runs the explicitly named live bootstrap diagnostic; it never changes stack resources. */
 export declare function checkBootstrap(config: BootstrapConfig, options: {
     resourceDrift?: boolean;
+    configPath?: string;
 }, dependencies: BootstrapCheckDependencies): Promise<BootstrapCheck>;

package/dist/bootstrap.d.ts

@@ -18,6 +18,7 @@ export type DeployedBootstrapStack = {
     }[];
 };
 export type BootstrapConfig = {
+    desiredState?: BootstrapDesiredState;
     /** Omitted in older manifests; Lambda is the compatibility default. */
     mode?: ComputeMode;
     region?: string;
@@ -39,6 +40,19 @@ export type BootstrapConfig = {
         consumerGatewayStackName?: string;
     };
 };
+export type BootstrapDesiredState = {
+    packageVersion: string;
+    templates: {
+        core: {
+            contractVersion: string;
+            templateRevision: string;
+        };
+        githubOidc: {
+            contractVersion: string;
+            templateRevision: string;
+        };
+    };
+};
 export type BootstrapTemplateInspection = {
     kind: BootstrapKind;
     path: string;
@@ -55,9 +69,18 @@ export type BootstrapPlan = {
     packageVersion: string;
     packageTemplates: BootstrapTemplateInspection[];
     configuration: BootstrapConfig;
+    desiredState: BootstrapDesiredStateComparison;
     notes: string[];
     remediation: BootstrapRemediation;
 };
+export type BootstrapDesiredStateComparison = {
+    manifest?: BootstrapDesiredState;
+    installed: BootstrapDesiredState;
+    matches: boolean;
+    packageVersionMatches: boolean;
+    ok: boolean;
+    mismatches: string[];
+};
 export type BootstrapConsistency = {
     ok: boolean;
     mismatches: string[];
@@ -65,6 +88,8 @@ export type BootstrapConsistency = {
 export declare function requireComputeMode(persisted: Pick<BootstrapConfig, 'mode'>, explicit?: string): ComputeMode;
 export declare function bootstrapTemplatePath(kind: BootstrapKind, mode?: ComputeMode): Promise<string>;
 export declare function bootstrapTemplate(kind: BootstrapKind, mode?: ComputeMode): Promise<string>;
+/** Resolves the package-owned identity intended for a manifest at the selected compute mode. */
+export declare function installedBootstrapDesiredState(config?: Pick<BootstrapConfig, 'mode'>): Promise<BootstrapDesiredState>;
 export declare function bootstrapContractVersion(template: string): string;
 export declare function bootstrapTemplateRevision(template: string): string;
 /** Returns installed templates and a reviewable, non-secret plan without external calls. */

package/dist/cli.js

@@ -2,14 +2,14 @@
 
 // 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 { readFile as readFile6, writeFile as writeFile4 } 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
 import { execFile as execFile2 } from "node:child_process";
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 import { promisify as promisify2 } from "node:util";
 import { parse as parse2 } from "yaml";
 
@@ -169,7 +169,34 @@ function bootstrapRemediation(config, input = {}) {
     ["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 checkCommand = `npm exec -- ze-great-dashboard-aws bootstrap check --config ${configPath} --format text`;
+  const desiredStateUpdateCommand = `npm exec -- ze-great-dashboard-aws bootstrap upgrade --config ${configPath}`;
+  const desiredStateUpdateRequired = input.desiredStateUpdateRequired ?? false;
+  const jsonCheckCommand = `npm exec -- ze-great-dashboard-aws bootstrap check --config ${configPath} --format json`;
+  const region2 = config.region ?? "<region>";
+  const recoveryStacks = [
+    ["core", config.core?.stackName],
+    ["github-oidc", config.githubOidc?.stackName]
+  ].filter((entry) => Boolean(entry[1]));
+  const captures = new Map(
+    recoveryStacks.map(([kind]) => [kind, `.bootstrap-work/${kind}-deployed-stack.json`])
+  );
+  const recoveryCommands = recoveryStacks.map(([kind, stackName2]) => ({
+    name: `capture-${kind}-stack`,
+    command: `mkdir -p .bootstrap-work && aws cloudformation describe-stacks --stack-name ${stackName2} --region ${region2} --output json --no-cli-pager > ${captures.get(kind)}`
+  }));
+  for (const [kind, stackName2] of recoveryStacks) {
+    const parameters = `.bootstrap-work/${kind}-bootstrap-parameters.json`;
+    recoveryCommands.push({
+      name: `preserve-${kind}-parameters`,
+      command: `npm exec -- ze-great-dashboard-aws bootstrap parameters --kind ${kind} --config ${configPath} --deployed-stack-json ${captures.get(kind)}${kind === "github-oidc" && captures.has("core") ? ` --core-stack-json ${captures.get("core")}` : ""} --output ${parameters}`
+    });
+    recoveryCommands.push({
+      name: `generate-${kind}-update-change-set`,
+      command: `npm exec -- ze-great-dashboard-aws bootstrap change-set --kind ${kind} --config ${configPath} --stack-name ${stackName2} --change-set-name repair-${kind} --change-set-type UPDATE --parameters ${parameters}`
+    });
+  }
+  recoveryCommands.push({ name: "revalidate-bootstrap", command: checkCommand });
   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 {
@@ -181,10 +208,22 @@ function bootstrapRemediation(config, input = {}) {
       "Capture the resulting CloudFormation stack output for the next validation step."
     ],
     upgradeSteps: [
+      ...desiredStateUpdateRequired ? [`Bootstrap template identity changed; review and run: ${desiredStateUpdateCommand}`] : [],
       "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,
+    recoveryCommands,
+    ...desiredStateUpdateRequired ? {
+      desiredStateUpdateCommand,
+      desiredStateCheckpoint: "Review and commit the desired-state manifest mutation before the administrator deployment process consumes it; never copy deployed AWS values into desired state."
+    } : {},
+    reviewCheckpoints: [
+      "Review the captured stack JSON and preserved parameter files before generating any change set.",
+      "Inspect every generated UPDATE change set in CloudFormation; verify IAM actions, retained resources, and parameters before executing it.",
+      "Execute change sets only as an administrator, one affected stack at a time, then capture both stacks again."
+    ],
+    runbookTarget: "docs/aws-bootstrap-upgrade.md",
+    revalidateCommand: jsonCheckCommand,
     safetyNote
   };
 }
@@ -196,6 +235,17 @@ function formatBootstrapRemediationText(remediation) {
     ...remediation.immediateSteps.map((step, index) => `  ${index + 1}. ${step}`),
     "Upgrade steps:",
     ...remediation.upgradeSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    ...remediation.desiredStateUpdateCommand ? [
+      `Desired-state update (repository mutation; review and commit):
+  $ ${remediation.desiredStateUpdateCommand}`,
+      `Desired-state checkpoint: ${remediation.desiredStateCheckpoint}`
+    ] : [],
+    "Copy/paste recovery commands (review before execute):",
+    ...remediation.recoveryCommands.map(({ name, command }) => `  ${name}:
+    $ ${command}`),
+    "Review checkpoints:",
+    ...remediation.reviewCheckpoints.map((checkpoint, index) => `  ${index + 1}. ${checkpoint}`),
+    `Runbook: ${remediation.runbookTarget}`,
     `Revalidate: ${remediation.revalidateCommand}`,
     `Safety: ${remediation.safetyNote}`
   ];
@@ -222,6 +272,47 @@ async function bootstrapTemplatePath(kind, mode = "lambda") {
 async function bootstrapTemplate(kind, mode = "lambda") {
   return readFile2(await bootstrapTemplatePath(kind, mode), "utf8");
 }
+async function installedBootstrapDesiredState(config = {}) {
+  const packageManifest = JSON.parse(
+    await readFile2(new URL("../package.json", import.meta.url), "utf8")
+  );
+  return desiredStateFromTemplates(
+    packageVersion(packageManifest),
+    await installedTemplateInspections(computeMode(config))
+  );
+}
+function packageVersion(packageManifest) {
+  return typeof packageManifest.version === "string" ? packageManifest.version : "unknown";
+}
+function desiredStateFromTemplates(version, packageTemplates) {
+  const template = (kind) => packageTemplates.find((entry) => entry.kind === kind);
+  const core = template("core");
+  const githubOidc = template("github-oidc");
+  if (!core || !githubOidc) throw new Error("Installed package is missing a bootstrap template");
+  if (!core.templateRevision || !githubOidc.templateRevision)
+    throw new Error("Installed bootstrap template has no template revision");
+  return {
+    packageVersion: version,
+    templates: {
+      core: { contractVersion: core.contractVersion, templateRevision: core.templateRevision },
+      githubOidc: {
+        contractVersion: githubOidc.contractVersion,
+        templateRevision: githubOidc.templateRevision
+      }
+    }
+  };
+}
+async function installedTemplateInspections(mode) {
+  return Promise.all(
+    ["core", "github-oidc"].map(async (kind) => {
+      const [path, template] = await Promise.all([
+        bootstrapTemplatePath(kind, mode),
+        bootstrapTemplate(kind, mode)
+      ]);
+      return inspectTemplate(kind, path, template);
+    })
+  );
+}
 function bootstrapContractVersion(template) {
   const version = template.match(/BootstrapContractVersion:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
   if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
@@ -255,26 +346,36 @@ 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 mode = computeMode(config);
-      const [path, template] = await Promise.all([
-        bootstrapTemplatePath(kind, mode),
-        bootstrapTemplate(kind, mode)
-      ]);
-      return inspectTemplate(kind, path, template);
-    })
+  const packageTemplates = await installedTemplateInspections(computeMode(config));
+  const installedDesiredState = desiredStateFromTemplates(
+    packageVersion(packageManifest),
+    packageTemplates
   );
+  const desiredStateMatches = Boolean(config.desiredState) && ["core", "githubOidc"].every((kind) => {
+    const manifestTemplate = config.desiredState?.templates[kind];
+    const installedTemplate = installedDesiredState.templates[kind];
+    return manifestTemplate?.contractVersion === installedTemplate.contractVersion && manifestTemplate?.templateRevision === installedTemplate.templateRevision;
+  });
+  const packageVersionMatches = config.desiredState?.packageVersion === installedDesiredState.packageVersion;
   return {
-    packageVersion: typeof packageManifest.version === "string" ? packageManifest.version : "unknown",
+    packageVersion: installedDesiredState.packageVersion,
     packageTemplates,
     configuration: config,
+    desiredState: {
+      ...config.desiredState ? { manifest: config.desiredState } : {},
+      installed: installedDesiredState,
+      matches: desiredStateMatches,
+      packageVersionMatches,
+      ok: desiredStateMatches,
+      mismatches: desiredStateMatches ? [] : ["manifest bootstrap template identity differs from installed package"]
+    },
     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."
     ],
     remediation: bootstrapRemediation(config, {
+      desiredStateUpdateRequired: !desiredStateMatches,
       nextOperation: "Review the installed templates, then run bootstrap preflight before creating a change set."
     })
   };
@@ -417,7 +518,7 @@ function requiredBootstrapParameters(kind, values) {
 
 // packages/aws/src/index.ts
 import { execFile } from "node:child_process";
-import { cp, mkdir as mkdir2, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile4, rm, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify } from "node:util";
@@ -1143,7 +1244,15 @@ import { parseDocument, Scalar } from "yaml";
 
 // packages/aws/src/bootstrap-check.ts
 function formatBootstrapCheckText(result) {
-  const lines = [`AWS bootstrap consistency (${result.packageVersion})`];
+  const lines = [
+    `AWS bootstrap consistency (${result.packageVersion})`,
+    `Desired state: ${result.desiredState.ok ? "PASS" : "FAIL"}`,
+    `Package provenance: ${result.desiredState.packageVersionMatches ? "matches installed package" : `manifest ${result.desiredState.manifest?.packageVersion ?? "missing"}, installed ${result.desiredState.installed.packageVersion} (informational)`}`,
+    ...(result.desiredState.mismatches ?? []).map((mismatch) => `  mismatch: ${mismatch}`),
+    ...result.remediation.desiredStateUpdateCommand ? [
+      `Desired-state update command (review, commit, then deploy): ${result.remediation.desiredStateUpdateCommand}`
+    ] : []
+  ];
   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"})`,
@@ -1193,6 +1302,17 @@ function outputs(stack) {
     ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
   );
 }
+function desiredStateShape(value2) {
+  if (!value2 || typeof value2 !== "object") return false;
+  const state = value2;
+  const templates2 = state.templates;
+  if (typeof state.packageVersion !== "string" || !templates2 || typeof templates2 !== "object")
+    return false;
+  return ["core", "githubOidc"].every((kind) => {
+    const template = templates2[kind];
+    return Boolean(template) && typeof template === "object" && typeof template.contractVersion === "string" && typeof template.templateRevision === "string";
+  });
+}
 async function resourceDrift(stackName2, region2, dependencies) {
   try {
     const detected = parseJson(
@@ -1326,6 +1446,26 @@ async function checkBootstrap(config, options, dependencies) {
     "github-oidc": config.githubOidc?.stackName
   };
   const plan = await bootstrapPlan(config);
+  const desiredStateMismatches = [];
+  const declared = config.desiredState;
+  if (!desiredStateShape(declared))
+    desiredStateMismatches.push(
+      `manifest desiredState metadata is ${declared ? "malformed" : "missing"}; run the explicit bootstrap upgrade command`
+    );
+  else {
+    for (const kind of ["core", "githubOidc"]) {
+      const wanted = declared.templates[kind];
+      const installed = plan.desiredState.installed.templates[kind];
+      if (!wanted || wanted.contractVersion !== installed.contractVersion)
+        desiredStateMismatches.push(
+          `${kind} contract is ${wanted?.contractVersion ?? "missing"}; installed package has ${installed.contractVersion}`
+        );
+      if (!wanted || wanted.templateRevision !== installed.templateRevision)
+        desiredStateMismatches.push(
+          `${kind} template revision is ${wanted?.templateRevision ?? "missing"}; installed package has ${installed.templateRevision}`
+        );
+    }
+  }
   const responses = await Promise.all(
     ["core", "github-oidc"].map(async (kind) => {
       const stackName2 = stackNames[kind];
@@ -1361,8 +1501,8 @@ async function checkBootstrap(config, options, dependencies) {
         kind,
         config,
         response,
-        template.contractVersion,
-        template.templateRevision,
+        (desiredStateShape(declared) ? declared.templates[kind === "core" ? "core" : "githubOidc"].contractVersion : void 0) ?? template.contractVersion,
+        (desiredStateShape(declared) ? declared.templates[kind === "core" ? "core" : "githubOidc"].templateRevision : void 0) ?? template.templateRevision,
         coreOutputValues
       );
       const checked = {
@@ -1387,12 +1527,22 @@ async function checkBootstrap(config, options, dependencies) {
     ({ consistency, resourceDrift: resourceDrift2 }) => !consistency.ok || Boolean(resourceDrift2 && !resourceDrift2.ok)
   );
   return {
-    ok: stacks.every(
+    ok: desiredStateMismatches.length === 0 && stacks.every(
       ({ consistency, resourceDrift: drift }) => consistency.ok && (!drift || drift.ok)
     ),
     packageVersion: plan.packageVersion,
     stacks,
+    desiredState: {
+      ok: desiredStateMismatches.length === 0,
+      mismatches: desiredStateMismatches,
+      ...desiredStateShape(declared) ? { manifest: declared } : {},
+      installed: plan.desiredState.installed,
+      matches: desiredStateMismatches.length === 0,
+      packageVersionMatches: declared?.packageVersion === plan.desiredState.installed.packageVersion
+    },
     remediation: bootstrapRemediation(config, {
+      configPath: options.configPath,
+      desiredStateUpdateRequired: desiredStateMismatches.length > 0,
       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 }) => ({
@@ -1410,6 +1560,9 @@ async function checkBootstrap(config, options, dependencies) {
   };
 }
 
+// packages/aws/src/guided.ts
+import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+
 // packages/aws/src/handoff.ts
 var githubSubjectKeys = [
   "repository_owner",
@@ -1902,6 +2055,7 @@ async function scaffoldBootstrapManifest(input) {
   if (!repositoryId)
     throw new Error("--github-repository-id is required when GitHub is unavailable");
   return {
+    desiredState: await installedBootstrapDesiredState({ mode: input.mode ?? "lambda" }),
     region: region2,
     core: {
       stackName: `${slug}-bootstrap`,
@@ -1920,6 +2074,55 @@ async function scaffoldBootstrapManifest(input) {
     }
   };
 }
+async function upgradeBootstrapManifest(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile3(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `Unable to read bootstrap manifest ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error(`Bootstrap manifest ${path} must contain a JSON object`);
+  const existing = parsed;
+  const missing = incomplete(existing);
+  if (missing.length) throw new Error(`Bootstrap manifest is incomplete: ${missing.join(", ")}`);
+  if (existing.mode && existing.mode !== "lambda" && existing.mode !== "ecs")
+    throw new Error("Bootstrap manifest has invalid mode; expected lambda or ecs");
+  const desiredState = await installedBootstrapDesiredState({ mode: existing.mode ?? "lambda" });
+  const previous = existing.desiredState;
+  const metadataChanges = [
+    ...previous?.packageVersion !== desiredState.packageVersion ? [
+      {
+        path: "packageVersion",
+        before: previous?.packageVersion,
+        after: desiredState.packageVersion
+      }
+    ] : [],
+    ...["core", "githubOidc"].flatMap((kind) => [
+      ...previous?.templates?.[kind]?.contractVersion !== desiredState.templates[kind].contractVersion ? [
+        {
+          path: `templates.${kind}.contractVersion`,
+          before: previous?.templates?.[kind]?.contractVersion,
+          after: desiredState.templates[kind].contractVersion
+        }
+      ] : [],
+      ...previous?.templates?.[kind]?.templateRevision !== desiredState.templates[kind].templateRevision ? [
+        {
+          path: `templates.${kind}.templateRevision`,
+          before: previous?.templates?.[kind]?.templateRevision,
+          after: desiredState.templates[kind].templateRevision
+        }
+      ] : []
+    ])
+  ];
+  const changed = metadataChanges.map(({ path: path2 }) => path2);
+  const manifest = { ...existing, desiredState };
+  await writeFile2(path, `${JSON.stringify(manifest, null, 2)}
+`);
+  return { manifest, desiredState, changed, metadataChanges };
+}
 function incomplete(config) {
   const fields = [
     ["region", config.region],
@@ -2189,13 +2392,13 @@ async function packageLambda(options) {
     computeMode: "lambda",
     artifactChecksums: {
       ...release.metadata.artifactChecksums,
-      "index.mjs": sha256(await readFile3(join2(runtimeDir, "index.mjs")))
+      "index.mjs": sha256(await readFile4(join2(runtimeDir, "index.mjs")))
     }
   };
-  await writeFile2(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
+  await writeFile3(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
 `);
   const sums = Object.entries(runtimeMetadata.artifactChecksums).map(([name, digest]) => `${digest}  ${name}`).join("\n");
-  await writeFile2(join2(runtimeDir, "SHA256SUMS"), `${sums}
+  await writeFile3(join2(runtimeDir, "SHA256SUMS"), `${sums}
 `);
   const lambdaPath = join2(outputDir, "lambda.zip");
   const archiveFiles = ["SHA256SUMS", "board.yaml", "index.mjs", "release.json"].sort();
@@ -2204,24 +2407,24 @@ async function packageLambda(options) {
       archiveFiles.map(async (name) => [
         name,
         [
-          strToU8(await readFile3(join2(runtimeDir, name), "utf8")),
+          strToU8(await readFile4(join2(runtimeDir, name), "utf8")),
           { mtime: new Date(1980, 0, 1, 0, 0, 0), level: 9 }
         ]
       ])
     )
   );
-  await writeFile2(lambdaPath, zipSync(archive));
+  await writeFile3(lambdaPath, zipSync(archive));
   await rm(runtimeDir, { recursive: true, force: true });
-  const lambdaChecksum = sha256(await readFile3(lambdaPath));
+  const lambdaChecksum = sha256(await readFile4(lambdaPath));
   const deploymentChecksum = sha256(JSON.stringify(runtimeMetadata));
   const packagedRelease = {
     ...runtimeMetadata,
     artifactChecksums: { ...runtimeMetadata.artifactChecksums, "lambda.zip": lambdaChecksum },
     artifactKey: `lambda/${deploymentChecksum}.zip`
   };
-  await writeFile2(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
+  await writeFile3(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
 `);
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "template.yml"),
     deploymentTemplate(await cloudFormationTemplate("lambda"), {
       ComputeMode: "lambda",
@@ -2249,9 +2452,9 @@ async function packageEcs(options) {
     image: imageReference,
     artifactKey: `ecs/${sha256(JSON.stringify({ ...release.metadata, image: imageReference }))}`
   };
-  await writeFile2(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
+  await writeFile3(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
 `);
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "template.yml"),
     deploymentTemplate(await cloudFormationTemplate("ecs"), {
       ComputeMode: "ecs",
@@ -2259,16 +2462,16 @@ async function packageEcs(options) {
       DashboardVersion: packagedRelease.dashboardVersion
     })
   );
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "SHA256SUMS"),
-    `${sha256(await readFile3(join2(outputDir, "release.json")))}  release.json
+    `${sha256(await readFile4(join2(outputDir, "release.json")))}  release.json
 `
   );
   return packagedRelease;
 }
 async function publishClientAssets(options) {
   const assetsDir = resolve2(options.assetsDir);
-  await readFile3(join2(assetsDir, "index.html"));
+  await readFile4(join2(assetsDir, "index.html"));
   const assetPath = `${options.assetsBaseUrl.replace(/\/+$/, "")}/dashboard/${options.version}`;
   await run("aws", [
     "s3",
@@ -2291,7 +2494,7 @@ async function publishClientAssets(options) {
   return assetPath;
 }
 async function cloudFormationTemplate(mode = "lambda") {
-  return readFile3(
+  return readFile4(
     fileURLToPath2(
       new URL(mode === "ecs" ? "../template-ecs.yml" : "../template.yml", import.meta.url)
     ),
@@ -2396,7 +2599,7 @@ async function runDoctor(options, dependencies = actualDependencies) {
   let parameterData;
   await check("Parameters/template", async () => {
     const parameters = readParameterValues(
-      JSON.parse(await readFile4(options.parametersPath, "utf8"))
+      JSON.parse(await readFile5(options.parametersPath, "utf8"))
     );
     parameterData = await templateContract(parameters);
     return `${options.parametersPath} is compatible (${computeMode({ mode: parameterData.values.ComputeMode })})`;
@@ -2438,7 +2641,7 @@ async function runDoctor(options, dependencies = actualDependencies) {
     const template = await bootstrapTemplate("github-oidc");
     const expectedRevision = bootstrapTemplateRevision(template);
     await check("Bootstrap template", async () => {
-      const raw = JSON.parse(await readFile4(stackPath, "utf8"));
+      const raw = JSON.parse(await readFile5(stackPath, "utf8"));
       const stack = raw && typeof raw === "object" && "Stacks" in raw ? raw.Stacks?.[0] : raw;
       if (!stack || typeof stack !== "object")
         throw new Error("captured stack JSON contains no stack");
@@ -2476,7 +2679,7 @@ var option = (name, fallback) => {
 };
 async function installedPackageVersion() {
   const packageManifest = JSON.parse(
-    await readFile5(new URL("../package.json", import.meta.url), "utf8")
+    await readFile6(new URL("../package.json", import.meta.url), "utf8")
   );
   return typeof packageManifest.version === "string" ? packageManifest.version : "";
 }
@@ -2490,7 +2693,7 @@ function parameter(key, value2) {
 }
 async function existingParameters(path, allowMissing = false) {
   try {
-    const parsed = JSON.parse(await readFile5(path, "utf8"));
+    const parsed = JSON.parse(await readFile6(path, "utf8"));
     if (!Array.isArray(parsed)) throw new Error(`${path} must contain a JSON parameter array`);
     const values = parsed.map((value2) => {
       if (!value2 || typeof value2 !== "object" || typeof value2.ParameterKey !== "string" || typeof value2.ParameterValue !== "string")
@@ -2514,7 +2717,7 @@ function bootstrapKind() {
   throw new Error("--kind must be core or github-oidc");
 }
 async function readBootstrapConfig(path) {
-  const parsed = JSON.parse(await readFile5(path, "utf8"));
+  const parsed = JSON.parse(await readFile6(path, "utf8"));
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
     throw new Error("--config must contain a JSON object");
   return parsed;
@@ -2693,10 +2896,10 @@ function copyableCommand(command) {
   ).join(" ");
 }
 try {
-  const packageVersion = await installedPackageVersion();
+  const packageVersion2 = await installedPackageVersion();
   const bundledAssets = fileURLToPath3(new URL("../client", import.meta.url));
   if (args[0] === "publish-assets") {
-    const version = requiredOption("--version", packageVersion);
+    const version = requiredOption("--version", packageVersion2);
     const assetPath = await publishClientAssets({
       assetsDir: option("--assets-dir", bundledAssets) ?? bundledAssets,
       assetsBucket: requiredOption("--assets-bucket"),
@@ -2719,7 +2922,7 @@ try {
           return fetch(url);
         },
         nodeVersion: process.versions.node,
-        packageVersion
+        packageVersion: packageVersion2
       }
     );
     const remediation = checks[0]?.remediation;
@@ -2774,7 +2977,7 @@ try {
       if (value2 === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
       return parameter(key, String(value2));
     });
-    await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
+    await writeFile4(output, `${JSON.stringify(parameters, null, 2)}
 `);
     printBootstrap({ output }, `Wrote ${output}. Next: run the generated deployment handoff.`);
   } else if (args[0] === "bootstrap") {
@@ -2782,7 +2985,7 @@ try {
     if (action === "init") {
       const output = requiredOption("--output");
       try {
-        await readFile5(output, "utf8");
+        await readFile6(output, "utf8");
         throw new Error(`Refusing to overwrite existing manifest: ${output}`);
       } catch (error) {
         if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
@@ -2801,12 +3004,21 @@ try {
         mode: option("--mode", "lambda") ?? "lambda",
         runner
       });
-      await writeFile3(output, `${JSON.stringify(manifest, null, 2)}
+      await writeFile4(output, `${JSON.stringify(manifest, null, 2)}
 `, { flag: "wx" });
       printBootstrap(
         { output, manifest, remediation: (await bootstrapPlan(manifest)).remediation },
         `Wrote ${output}. Next: run bootstrap preflight, then bootstrap handoff.`
       );
+    } else if (action === "upgrade") {
+      const configPath = requiredOption("--config");
+      const result = await upgradeBootstrapManifest(configPath);
+      printBootstrap(
+        result,
+        `Updated desired-state metadata in ${configPath}.
+Changed: ${result.metadataChanges.length ? result.metadataChanges.map(({ path, before, after }) => `${path}: ${before ?? "missing"} -> ${after}`).join(", ") : "none (already current)"}.
+Review and commit this manifest before deployment.`
+      );
     } else {
       const config = await bootstrapConfig();
       if (action === "preflight") {
@@ -2831,9 +3043,9 @@ try {
           config,
           configPath,
           workDir: option("--work-dir"),
-          coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
+          coreStack: coreStackPath ? JSON.parse(await readFile6(coreStackPath, "utf8")) : void 0,
           coreStackPath,
-          githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+          githubOidcStack: githubStackPath ? JSON.parse(await readFile6(githubStackPath, "utf8")) : void 0,
           githubOidcStackPath: githubStackPath,
           runner
         });
@@ -2855,9 +3067,9 @@ try {
           config,
           configPath,
           workDir: option("--work-dir"),
-          coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
+          coreStack: coreStackPath ? JSON.parse(await readFile6(coreStackPath, "utf8")) : void 0,
           coreStackPath,
-          githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+          githubOidcStack: githubStackPath ? JSON.parse(await readFile6(githubStackPath, "utf8")) : void 0,
           githubOidcStackPath: githubStackPath,
           runner
         });
@@ -2872,8 +3084,8 @@ ${formatBootstrapRemediationText(handoff.remediation).join("\n")}`
         const githubStackPath = requiredOption("--github-oidc-stack-json");
         const verified = await verifyBootstrap({
           config,
-          coreStack: JSON.parse(await readFile5(coreStackPath, "utf8")),
-          githubOidcStack: JSON.parse(await readFile5(githubStackPath, "utf8"))
+          coreStack: JSON.parse(await readFile6(coreStackPath, "utf8")),
+          githubOidcStack: JSON.parse(await readFile6(githubStackPath, "utf8"))
         });
         printBootstrap(
           verified,
@@ -2904,6 +3116,20 @@ ${formatBootstrapRemediationText(template.remediation).join("\n")}`
         if (outputFormat() === "text") {
           console.log("AWS bootstrap plan (read-only)");
           console.log(`Package version: ${plan.packageVersion}`);
+          console.log(
+            `Manifest desired state: ${plan.desiredState.manifest ? JSON.stringify(plan.desiredState.manifest) : "missing"}`
+          );
+          console.log(`Installed desired state: ${JSON.stringify(plan.desiredState.installed)}`);
+          console.log(
+            `Bootstrap template identity matches installed package: ${plan.desiredState.matches ? "yes" : "no"}`
+          );
+          console.log(
+            `Package version provenance matches installed package: ${plan.desiredState.packageVersionMatches ? "yes" : "no (informational)"}`
+          );
+          if (!plan.desiredState.matches)
+            console.log(
+              `Run: npm exec -- ze-great-dashboard-aws bootstrap upgrade --config ${requiredOption("--config")}`
+            );
           for (const template of plan.packageTemplates) {
             console.log(`
 ${template.kind}: ${template.path}`);
@@ -2923,7 +3149,10 @@ ${plan.notes.join("\n")}`);
         requiredOption("--config");
         const result = await checkBootstrap(
           config,
-          { resourceDrift: args.includes("--resource-drift") },
+          {
+            resourceDrift: args.includes("--resource-drift"),
+            configPath: requiredOption("--config")
+          },
           {
             execute: runner.execute
           }
@@ -2940,7 +3169,7 @@ ${plan.notes.join("\n")}`);
         if (kind === "github-oidc" && coreStackPath) {
           coreOutputs = coreBootstrapOutputs(
             deployedBootstrapStack(
-              JSON.parse(await readFile5(coreStackPath, "utf8")),
+              JSON.parse(await readFile6(coreStackPath, "utf8")),
               bootstrapContractVersion(await bootstrapTemplate("core", mode))
             )
           );
@@ -2953,7 +3182,7 @@ ${plan.notes.join("\n")}`);
         const deployedStackPath = option("--deployed-stack-json");
         if (deployedStackPath) {
           const stack = deployedBootstrapStack(
-            JSON.parse(await readFile5(deployedStackPath, "utf8")),
+            JSON.parse(await readFile6(deployedStackPath, "utf8")),
             bootstrapContractVersion(await bootstrapTemplate(kind, mode))
           );
           if (kind === "github-oidc" && !(stack.Parameters ?? []).some(
@@ -2964,7 +3193,7 @@ ${plan.notes.join("\n")}`);
             );
           parameters = mergeBootstrapParameters(supplied, stack.Parameters ?? []);
         }
-        await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
+        await writeFile4(output, `${JSON.stringify(parameters, null, 2)}
 `);
         const remediation = (await bootstrapPlan(config)).remediation;
         printBootstrap(
@@ -3024,7 +3253,7 @@ ${shellCommand(awsCommand)}`,
         );
       } else {
         throw new Error(
-          "Usage: ze-great-dashboard-aws bootstrap init|preflight|plan|check|guide|handoff|verify --config manifest.json [options], or bootstrap template|parameters|change-set --kind core|github-oidc [options]"
+          "Usage: ze-great-dashboard-aws bootstrap init|upgrade|preflight|plan|check|guide|handoff|verify --config manifest.json [options], or bootstrap template|parameters|change-set --kind core|github-oidc [options]"
         );
       }
     }
@@ -3034,7 +3263,7 @@ ${shellCommand(awsCommand)}`,
     );
   else {
     const boardConfig = option("--board-config");
-    const version = option("--version", process.env.DASHBOARD_VERSION ?? packageVersion);
+    const version = option("--version", process.env.DASHBOARD_VERSION ?? packageVersion2);
     if (!boardConfig) throw new Error("--board-config is required");
     if (!version)
       throw new Error("Unable to determine the package version; pass --version explicitly");
@@ -3073,7 +3302,7 @@ ${shellCommand(awsCommand)}`,
         resolvedParameters.findIndex(({ ParameterKey }) => ParameterKey === "ComputeMode"),
         1
       );
-    await writeFile3(
+    await writeFile4(
       `${outputDir}/parameters.json`,
       `${JSON.stringify(resolvedParameters, null, 2)}
 `
@@ -3084,7 +3313,7 @@ ${shellCommand(awsCommand)}`,
       artifactKey: metadata.artifactKey,
       release: metadata
     });
-    await writeFile3(`${outputDir}/deployment.json`, `${JSON.stringify(handoff, null, 2)}
+    await writeFile4(`${outputDir}/deployment.json`, `${JSON.stringify(handoff, null, 2)}
 `);
     console.log(
       `Packaged ${mode === "lambda" ? `${outputDir}/lambda.zip` : metadata.image} and ${outputDir}/template.yml`

package/dist/guided.d.ts

@@ -30,8 +30,20 @@ export type BootstrapInitInput = {
     consumerGatewayStackName?: string;
     runner?: CommandRunner;
 };
+export type BootstrapManifestUpgrade = {
+    manifest: BootstrapConfig;
+    desiredState: NonNullable<BootstrapConfig['desiredState']>;
+    changed: string[];
+    metadataChanges: {
+        path: string;
+        before?: string;
+        after: string;
+    }[];
+};
 /** Creates the non-secret manifest data; callers control where (and whether) it is written. */
 export declare function scaffoldBootstrapManifest(input: BootstrapInitInput): Promise<BootstrapConfig>;
+/** Explicitly updates only package-owned desired-state metadata; it never reads AWS. */
+export declare function upgradeBootstrapManifest(path: string): Promise<BootstrapManifestUpgrade>;
 /** Runs only named read-only discovery checks. Network/auth failures remain usable offline. */
 export declare function bootstrapPreflight(input: {
     config: BootstrapConfig;

package/dist/index.d.ts

@@ -1,9 +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 BootstrapConfig, type BootstrapConsistency, type BootstrapDesiredState, type BootstrapDesiredStateComparison, type BootstrapKind, type BootstrapPlan, type BootstrapTemplateInspection, bootstrapConsistency, bootstrapContractVersion, bootstrapPlan, bootstrapTemplate, bootstrapTemplatePath, bootstrapTemplateRevision, type CloudFormationParameterValue, type ComputeMode, computeMode, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, installedBootstrapDesiredState, 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 BootstrapGuideReport, type BootstrapInitInput, type BootstrapPreflight, type BootstrapPreflightCheck, bootstrapGuide, bootstrapGuideReport, bootstrapPreflight, scaffoldBootstrapManifest, } from './guided.js';
+export { type BootstrapCheckStatus, type BootstrapGuideReport, type BootstrapInitInput, type BootstrapManifestUpgrade, type BootstrapPreflight, type BootstrapPreflightCheck, bootstrapGuide, bootstrapGuideReport, bootstrapPreflight, scaffoldBootstrapManifest, upgradeBootstrapManifest, } 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 BootstrapAffectedStack, type BootstrapRecoveryCommand, type BootstrapRemediation, type BootstrapRemediationInput, bootstrapRemediation, formatBootstrapRemediationText, } from './remediation.js';
 export type ReleaseMetadata = {
     computeMode: ComputeMode;
     dashboardVersion: string;

package/dist/index.js

@@ -1,6 +1,6 @@
 // packages/aws/src/index.ts
 import { execFile } from "node:child_process";
-import { cp, mkdir as mkdir2, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile4, rm, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify } from "node:util";
@@ -880,7 +880,34 @@ function bootstrapRemediation(config, input = {}) {
     ["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 checkCommand = `npm exec -- ze-great-dashboard-aws bootstrap check --config ${configPath} --format text`;
+  const desiredStateUpdateCommand = `npm exec -- ze-great-dashboard-aws bootstrap upgrade --config ${configPath}`;
+  const desiredStateUpdateRequired = input.desiredStateUpdateRequired ?? false;
+  const jsonCheckCommand = `npm exec -- ze-great-dashboard-aws bootstrap check --config ${configPath} --format json`;
+  const region2 = config.region ?? "<region>";
+  const recoveryStacks = [
+    ["core", config.core?.stackName],
+    ["github-oidc", config.githubOidc?.stackName]
+  ].filter((entry) => Boolean(entry[1]));
+  const captures = new Map(
+    recoveryStacks.map(([kind]) => [kind, `.bootstrap-work/${kind}-deployed-stack.json`])
+  );
+  const recoveryCommands = recoveryStacks.map(([kind, stackName2]) => ({
+    name: `capture-${kind}-stack`,
+    command: `mkdir -p .bootstrap-work && aws cloudformation describe-stacks --stack-name ${stackName2} --region ${region2} --output json --no-cli-pager > ${captures.get(kind)}`
+  }));
+  for (const [kind, stackName2] of recoveryStacks) {
+    const parameters = `.bootstrap-work/${kind}-bootstrap-parameters.json`;
+    recoveryCommands.push({
+      name: `preserve-${kind}-parameters`,
+      command: `npm exec -- ze-great-dashboard-aws bootstrap parameters --kind ${kind} --config ${configPath} --deployed-stack-json ${captures.get(kind)}${kind === "github-oidc" && captures.has("core") ? ` --core-stack-json ${captures.get("core")}` : ""} --output ${parameters}`
+    });
+    recoveryCommands.push({
+      name: `generate-${kind}-update-change-set`,
+      command: `npm exec -- ze-great-dashboard-aws bootstrap change-set --kind ${kind} --config ${configPath} --stack-name ${stackName2} --change-set-name repair-${kind} --change-set-type UPDATE --parameters ${parameters}`
+    });
+  }
+  recoveryCommands.push({ name: "revalidate-bootstrap", command: checkCommand });
   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 {
@@ -892,10 +919,22 @@ function bootstrapRemediation(config, input = {}) {
       "Capture the resulting CloudFormation stack output for the next validation step."
     ],
     upgradeSteps: [
+      ...desiredStateUpdateRequired ? [`Bootstrap template identity changed; review and run: ${desiredStateUpdateCommand}`] : [],
       "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,
+    recoveryCommands,
+    ...desiredStateUpdateRequired ? {
+      desiredStateUpdateCommand,
+      desiredStateCheckpoint: "Review and commit the desired-state manifest mutation before the administrator deployment process consumes it; never copy deployed AWS values into desired state."
+    } : {},
+    reviewCheckpoints: [
+      "Review the captured stack JSON and preserved parameter files before generating any change set.",
+      "Inspect every generated UPDATE change set in CloudFormation; verify IAM actions, retained resources, and parameters before executing it.",
+      "Execute change sets only as an administrator, one affected stack at a time, then capture both stacks again."
+    ],
+    runbookTarget: "docs/aws-bootstrap-upgrade.md",
+    revalidateCommand: jsonCheckCommand,
     safetyNote
   };
 }
@@ -907,6 +946,17 @@ function formatBootstrapRemediationText(remediation) {
     ...remediation.immediateSteps.map((step, index) => `  ${index + 1}. ${step}`),
     "Upgrade steps:",
     ...remediation.upgradeSteps.map((step, index) => `  ${index + 1}. ${step}`),
+    ...remediation.desiredStateUpdateCommand ? [
+      `Desired-state update (repository mutation; review and commit):
+  $ ${remediation.desiredStateUpdateCommand}`,
+      `Desired-state checkpoint: ${remediation.desiredStateCheckpoint}`
+    ] : [],
+    "Copy/paste recovery commands (review before execute):",
+    ...remediation.recoveryCommands.map(({ name, command }) => `  ${name}:
+    $ ${command}`),
+    "Review checkpoints:",
+    ...remediation.reviewCheckpoints.map((checkpoint, index) => `  ${index + 1}. ${checkpoint}`),
+    `Runbook: ${remediation.runbookTarget}`,
     `Revalidate: ${remediation.revalidateCommand}`,
     `Safety: ${remediation.safetyNote}`
   ];
@@ -933,6 +983,47 @@ async function bootstrapTemplatePath(kind, mode = "lambda") {
 async function bootstrapTemplate(kind, mode = "lambda") {
   return readFile2(await bootstrapTemplatePath(kind, mode), "utf8");
 }
+async function installedBootstrapDesiredState(config = {}) {
+  const packageManifest = JSON.parse(
+    await readFile2(new URL("../package.json", import.meta.url), "utf8")
+  );
+  return desiredStateFromTemplates(
+    packageVersion(packageManifest),
+    await installedTemplateInspections(computeMode(config))
+  );
+}
+function packageVersion(packageManifest) {
+  return typeof packageManifest.version === "string" ? packageManifest.version : "unknown";
+}
+function desiredStateFromTemplates(version, packageTemplates) {
+  const template = (kind) => packageTemplates.find((entry) => entry.kind === kind);
+  const core = template("core");
+  const githubOidc = template("github-oidc");
+  if (!core || !githubOidc) throw new Error("Installed package is missing a bootstrap template");
+  if (!core.templateRevision || !githubOidc.templateRevision)
+    throw new Error("Installed bootstrap template has no template revision");
+  return {
+    packageVersion: version,
+    templates: {
+      core: { contractVersion: core.contractVersion, templateRevision: core.templateRevision },
+      githubOidc: {
+        contractVersion: githubOidc.contractVersion,
+        templateRevision: githubOidc.templateRevision
+      }
+    }
+  };
+}
+async function installedTemplateInspections(mode) {
+  return Promise.all(
+    ["core", "github-oidc"].map(async (kind) => {
+      const [path, template] = await Promise.all([
+        bootstrapTemplatePath(kind, mode),
+        bootstrapTemplate(kind, mode)
+      ]);
+      return inspectTemplate(kind, path, template);
+    })
+  );
+}
 function bootstrapContractVersion(template) {
   const version = template.match(/BootstrapContractVersion:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
   if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
@@ -966,26 +1057,36 @@ 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 mode = computeMode(config);
-      const [path, template] = await Promise.all([
-        bootstrapTemplatePath(kind, mode),
-        bootstrapTemplate(kind, mode)
-      ]);
-      return inspectTemplate(kind, path, template);
-    })
+  const packageTemplates = await installedTemplateInspections(computeMode(config));
+  const installedDesiredState = desiredStateFromTemplates(
+    packageVersion(packageManifest),
+    packageTemplates
   );
+  const desiredStateMatches = Boolean(config.desiredState) && ["core", "githubOidc"].every((kind) => {
+    const manifestTemplate = config.desiredState?.templates[kind];
+    const installedTemplate = installedDesiredState.templates[kind];
+    return manifestTemplate?.contractVersion === installedTemplate.contractVersion && manifestTemplate?.templateRevision === installedTemplate.templateRevision;
+  });
+  const packageVersionMatches = config.desiredState?.packageVersion === installedDesiredState.packageVersion;
   return {
-    packageVersion: typeof packageManifest.version === "string" ? packageManifest.version : "unknown",
+    packageVersion: installedDesiredState.packageVersion,
     packageTemplates,
     configuration: config,
+    desiredState: {
+      ...config.desiredState ? { manifest: config.desiredState } : {},
+      installed: installedDesiredState,
+      matches: desiredStateMatches,
+      packageVersionMatches,
+      ok: desiredStateMatches,
+      mismatches: desiredStateMatches ? [] : ["manifest bootstrap template identity differs from installed package"]
+    },
     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."
     ],
     remediation: bootstrapRemediation(config, {
+      desiredStateUpdateRequired: !desiredStateMatches,
       nextOperation: "Review the installed templates, then run bootstrap preflight before creating a change set."
     })
   };
@@ -1128,7 +1229,15 @@ function requiredBootstrapParameters(kind, values) {
 
 // packages/aws/src/bootstrap-check.ts
 function formatBootstrapCheckText(result) {
-  const lines = [`AWS bootstrap consistency (${result.packageVersion})`];
+  const lines = [
+    `AWS bootstrap consistency (${result.packageVersion})`,
+    `Desired state: ${result.desiredState.ok ? "PASS" : "FAIL"}`,
+    `Package provenance: ${result.desiredState.packageVersionMatches ? "matches installed package" : `manifest ${result.desiredState.manifest?.packageVersion ?? "missing"}, installed ${result.desiredState.installed.packageVersion} (informational)`}`,
+    ...(result.desiredState.mismatches ?? []).map((mismatch) => `  mismatch: ${mismatch}`),
+    ...result.remediation.desiredStateUpdateCommand ? [
+      `Desired-state update command (review, commit, then deploy): ${result.remediation.desiredStateUpdateCommand}`
+    ] : []
+  ];
   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"})`,
@@ -1178,6 +1287,17 @@ function outputs(stack) {
     ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
   );
 }
+function desiredStateShape(value2) {
+  if (!value2 || typeof value2 !== "object") return false;
+  const state = value2;
+  const templates2 = state.templates;
+  if (typeof state.packageVersion !== "string" || !templates2 || typeof templates2 !== "object")
+    return false;
+  return ["core", "githubOidc"].every((kind) => {
+    const template = templates2[kind];
+    return Boolean(template) && typeof template === "object" && typeof template.contractVersion === "string" && typeof template.templateRevision === "string";
+  });
+}
 async function resourceDrift(stackName2, region2, dependencies) {
   try {
     const detected = parseJson(
@@ -1311,6 +1431,26 @@ async function checkBootstrap(config, options, dependencies) {
     "github-oidc": config.githubOidc?.stackName
   };
   const plan = await bootstrapPlan(config);
+  const desiredStateMismatches = [];
+  const declared = config.desiredState;
+  if (!desiredStateShape(declared))
+    desiredStateMismatches.push(
+      `manifest desiredState metadata is ${declared ? "malformed" : "missing"}; run the explicit bootstrap upgrade command`
+    );
+  else {
+    for (const kind of ["core", "githubOidc"]) {
+      const wanted = declared.templates[kind];
+      const installed = plan.desiredState.installed.templates[kind];
+      if (!wanted || wanted.contractVersion !== installed.contractVersion)
+        desiredStateMismatches.push(
+          `${kind} contract is ${wanted?.contractVersion ?? "missing"}; installed package has ${installed.contractVersion}`
+        );
+      if (!wanted || wanted.templateRevision !== installed.templateRevision)
+        desiredStateMismatches.push(
+          `${kind} template revision is ${wanted?.templateRevision ?? "missing"}; installed package has ${installed.templateRevision}`
+        );
+    }
+  }
   const responses = await Promise.all(
     ["core", "github-oidc"].map(async (kind) => {
       const stackName2 = stackNames[kind];
@@ -1346,8 +1486,8 @@ async function checkBootstrap(config, options, dependencies) {
         kind,
         config,
         response,
-        template.contractVersion,
-        template.templateRevision,
+        (desiredStateShape(declared) ? declared.templates[kind === "core" ? "core" : "githubOidc"].contractVersion : void 0) ?? template.contractVersion,
+        (desiredStateShape(declared) ? declared.templates[kind === "core" ? "core" : "githubOidc"].templateRevision : void 0) ?? template.templateRevision,
         coreOutputValues
       );
       const checked = {
@@ -1372,12 +1512,22 @@ async function checkBootstrap(config, options, dependencies) {
     ({ consistency, resourceDrift: resourceDrift2 }) => !consistency.ok || Boolean(resourceDrift2 && !resourceDrift2.ok)
   );
   return {
-    ok: stacks.every(
+    ok: desiredStateMismatches.length === 0 && stacks.every(
       ({ consistency, resourceDrift: drift }) => consistency.ok && (!drift || drift.ok)
     ),
     packageVersion: plan.packageVersion,
     stacks,
+    desiredState: {
+      ok: desiredStateMismatches.length === 0,
+      mismatches: desiredStateMismatches,
+      ...desiredStateShape(declared) ? { manifest: declared } : {},
+      installed: plan.desiredState.installed,
+      matches: desiredStateMismatches.length === 0,
+      packageVersionMatches: declared?.packageVersion === plan.desiredState.installed.packageVersion
+    },
     remediation: bootstrapRemediation(config, {
+      configPath: options.configPath,
+      desiredStateUpdateRequired: desiredStateMismatches.length > 0,
       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 }) => ({
@@ -1395,6 +1545,9 @@ async function checkBootstrap(config, options, dependencies) {
   };
 }
 
+// packages/aws/src/guided.ts
+import { readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+
 // packages/aws/src/handoff.ts
 var githubSubjectKeys = [
   "repository_owner",
@@ -1887,6 +2040,7 @@ async function scaffoldBootstrapManifest(input) {
   if (!repositoryId)
     throw new Error("--github-repository-id is required when GitHub is unavailable");
   return {
+    desiredState: await installedBootstrapDesiredState({ mode: input.mode ?? "lambda" }),
     region: region2,
     core: {
       stackName: `${slug}-bootstrap`,
@@ -1905,6 +2059,55 @@ async function scaffoldBootstrapManifest(input) {
     }
   };
 }
+async function upgradeBootstrapManifest(path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile3(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `Unable to read bootstrap manifest ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error(`Bootstrap manifest ${path} must contain a JSON object`);
+  const existing = parsed;
+  const missing = incomplete(existing);
+  if (missing.length) throw new Error(`Bootstrap manifest is incomplete: ${missing.join(", ")}`);
+  if (existing.mode && existing.mode !== "lambda" && existing.mode !== "ecs")
+    throw new Error("Bootstrap manifest has invalid mode; expected lambda or ecs");
+  const desiredState = await installedBootstrapDesiredState({ mode: existing.mode ?? "lambda" });
+  const previous = existing.desiredState;
+  const metadataChanges = [
+    ...previous?.packageVersion !== desiredState.packageVersion ? [
+      {
+        path: "packageVersion",
+        before: previous?.packageVersion,
+        after: desiredState.packageVersion
+      }
+    ] : [],
+    ...["core", "githubOidc"].flatMap((kind) => [
+      ...previous?.templates?.[kind]?.contractVersion !== desiredState.templates[kind].contractVersion ? [
+        {
+          path: `templates.${kind}.contractVersion`,
+          before: previous?.templates?.[kind]?.contractVersion,
+          after: desiredState.templates[kind].contractVersion
+        }
+      ] : [],
+      ...previous?.templates?.[kind]?.templateRevision !== desiredState.templates[kind].templateRevision ? [
+        {
+          path: `templates.${kind}.templateRevision`,
+          before: previous?.templates?.[kind]?.templateRevision,
+          after: desiredState.templates[kind].templateRevision
+        }
+      ] : []
+    ])
+  ];
+  const changed = metadataChanges.map(({ path: path2 }) => path2);
+  const manifest = { ...existing, desiredState };
+  await writeFile2(path, `${JSON.stringify(manifest, null, 2)}
+`);
+  return { manifest, desiredState, changed, metadataChanges };
+}
 function incomplete(config) {
   const fields = [
     ["region", config.region],
@@ -2177,13 +2380,13 @@ async function packageLambda(options) {
     computeMode: "lambda",
     artifactChecksums: {
       ...release.metadata.artifactChecksums,
-      "index.mjs": sha256(await readFile3(join2(runtimeDir, "index.mjs")))
+      "index.mjs": sha256(await readFile4(join2(runtimeDir, "index.mjs")))
     }
   };
-  await writeFile2(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
+  await writeFile3(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
 `);
   const sums = Object.entries(runtimeMetadata.artifactChecksums).map(([name, digest]) => `${digest}  ${name}`).join("\n");
-  await writeFile2(join2(runtimeDir, "SHA256SUMS"), `${sums}
+  await writeFile3(join2(runtimeDir, "SHA256SUMS"), `${sums}
 `);
   const lambdaPath = join2(outputDir, "lambda.zip");
   const archiveFiles = ["SHA256SUMS", "board.yaml", "index.mjs", "release.json"].sort();
@@ -2192,24 +2395,24 @@ async function packageLambda(options) {
       archiveFiles.map(async (name) => [
         name,
         [
-          strToU8(await readFile3(join2(runtimeDir, name), "utf8")),
+          strToU8(await readFile4(join2(runtimeDir, name), "utf8")),
           { mtime: new Date(1980, 0, 1, 0, 0, 0), level: 9 }
         ]
       ])
     )
   );
-  await writeFile2(lambdaPath, zipSync(archive));
+  await writeFile3(lambdaPath, zipSync(archive));
   await rm(runtimeDir, { recursive: true, force: true });
-  const lambdaChecksum = sha256(await readFile3(lambdaPath));
+  const lambdaChecksum = sha256(await readFile4(lambdaPath));
   const deploymentChecksum = sha256(JSON.stringify(runtimeMetadata));
   const packagedRelease = {
     ...runtimeMetadata,
     artifactChecksums: { ...runtimeMetadata.artifactChecksums, "lambda.zip": lambdaChecksum },
     artifactKey: `lambda/${deploymentChecksum}.zip`
   };
-  await writeFile2(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
+  await writeFile3(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
 `);
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "template.yml"),
     deploymentTemplate(await cloudFormationTemplate("lambda"), {
       ComputeMode: "lambda",
@@ -2237,9 +2440,9 @@ async function packageEcs(options) {
     image: imageReference,
     artifactKey: `ecs/${sha256(JSON.stringify({ ...release.metadata, image: imageReference }))}`
   };
-  await writeFile2(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
+  await writeFile3(join2(outputDir, "release.json"), `${JSON.stringify(packagedRelease, null, 2)}
 `);
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "template.yml"),
     deploymentTemplate(await cloudFormationTemplate("ecs"), {
       ComputeMode: "ecs",
@@ -2247,16 +2450,16 @@ async function packageEcs(options) {
       DashboardVersion: packagedRelease.dashboardVersion
     })
   );
-  await writeFile2(
+  await writeFile3(
     join2(outputDir, "SHA256SUMS"),
-    `${sha256(await readFile3(join2(outputDir, "release.json")))}  release.json
+    `${sha256(await readFile4(join2(outputDir, "release.json")))}  release.json
 `
   );
   return packagedRelease;
 }
 async function publishClientAssets(options) {
   const assetsDir = resolve2(options.assetsDir);
-  await readFile3(join2(assetsDir, "index.html"));
+  await readFile4(join2(assetsDir, "index.html"));
   const assetPath = `${options.assetsBaseUrl.replace(/\/+$/, "")}/dashboard/${options.version}`;
   await run("aws", [
     "s3",
@@ -2279,7 +2482,7 @@ async function publishClientAssets(options) {
   return assetPath;
 }
 async function cloudFormationTemplate(mode = "lambda") {
-  return readFile3(
+  return readFile4(
     fileURLToPath2(
       new URL(mode === "ecs" ? "../template-ecs.yml" : "../template.yml", import.meta.url)
     ),
@@ -2306,6 +2509,7 @@ export {
   formatBootstrapCheckText,
   formatBootstrapRemediationText,
   githubOidcProvider,
+  installedBootstrapDesiredState,
   mergeBootstrapParameters,
   packageEcs,
   packageLambda,
@@ -2314,5 +2518,6 @@ export {
   requiredBootstrapParameters,
   resolveComputeMode,
   scaffoldBootstrapManifest,
+  upgradeBootstrapManifest,
   verifyBootstrap
 };

package/dist/remediation.d.ts

@@ -4,11 +4,20 @@ export type BootstrapAffectedStack = {
     stackName: string;
     issue?: string;
 };
+export type BootstrapRecoveryCommand = {
+    name: string;
+    command: string;
+};
 export type BootstrapRemediation = {
     failureSummary: string;
     affectedStacks: BootstrapAffectedStack[];
     immediateSteps: string[];
     upgradeSteps: string[];
+    desiredStateUpdateCommand?: string;
+    desiredStateCheckpoint?: string;
+    recoveryCommands: BootstrapRecoveryCommand[];
+    reviewCheckpoints: string[];
+    runbookTarget: string;
     revalidateCommand: string;
     safetyNote: string;
 };
@@ -18,6 +27,7 @@ export type BootstrapRemediationInput = {
     configPath?: string;
     nextOperation?: string;
     issues?: string[];
+    desiredStateUpdateRequired?: boolean;
 };
 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.7",
+  "version": "0.15.0",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [