@continuous-excellence/ze-great-dashboard-aws 0.7.0 → 0.8.0

package/README.md

@@ -57,10 +57,13 @@ npm exec -- ze-great-dashboard-aws doctor \
 
 npm exec -- ze-great-dashboard-aws package \
   --board-config board.yaml \
+  --parameters aws-dashboard-parameters.json \
   --output aws-dashboard-release
 ```
 
-The deployment guide covers the S3 upload, CloudFormation command, gateway handoff, and CI example.
+`package` writes the complete release-specific `parameters.json` and machine-readable
+`deployment.json` alongside the ZIP and template. The deployment guide covers executing the emitted
+S3 upload and CloudFormation commands, gateway handoff, and CI example.
 Changing `board.yaml` or upgrading the pinned package uses this same path.
 
 ## Package boundaries

package/dist/cli.js

@@ -2075,34 +2075,6 @@ async function publishClientAssets(options) {
   ]);
   return assetPath;
 }
-async function deployLambda(options) {
-  const artifactDir = resolve2(options.artifactDir);
-  const assetsDir = resolve2(options.assetsDir);
-  await readFile3(join2(artifactDir, "lambda.zip"));
-  await readFile3(join2(assetsDir, "index.html"));
-  if (options.dryRun) return;
-  const assetPath = await publishClientAssets(options);
-  await run("aws", [
-    "lambda",
-    "update-function-code",
-    "--function-name",
-    options.functionName,
-    "--zip-file",
-    `fileb://${join2(artifactDir, "lambda.zip")}`,
-    "--no-cli-pager"
-  ]);
-  await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
-  await run("aws", [
-    "lambda",
-    "update-function-configuration",
-    "--function-name",
-    options.functionName,
-    "--environment",
-    `Variables={ASSET_PATH=${assetPath},BOARD_CONFIG_URL=./board.yaml,HOST=0.0.0.0}`,
-    "--no-cli-pager"
-  ]);
-  await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
-}
 async function cloudFormationTemplate() {
   return readFile3(fileURLToPath2(new URL("../template.yml", import.meta.url)), "utf8");
 }
@@ -2284,7 +2256,7 @@ var requiredOption = (name, fallback) => {
 function parameter(key, value2) {
   return { ParameterKey: key, ParameterValue: value2 };
 }
-async function existingParameters(path) {
+async function existingParameters(path, allowMissing = false) {
   try {
     const parsed = JSON.parse(await readFile5(path, "utf8"));
     if (!Array.isArray(parsed)) throw new Error(`${path} must contain a JSON parameter array`);
@@ -2299,7 +2271,8 @@ async function existingParameters(path) {
     if (new Set(keys).size !== keys.length) throw new Error(`${path} contains duplicate parameters`);
     return values;
   } catch (error) {
-    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
+    if (allowMissing && error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+      return [];
     throw error;
   }
 }
@@ -2373,23 +2346,86 @@ async function templateParameters() {
     );
   return { definitions: parsed.Parameters, packageManaged };
 }
+function validateConsumerParameters(supplied, template) {
+  const values = Object.fromEntries(
+    supplied.map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
+  );
+  const templateKeys = Object.keys(template.definitions);
+  const unknown = Object.keys(values).filter((key) => !templateKeys.includes(key));
+  if (unknown.length)
+    throw new Error(`Parameter file contains unknown parameters: ${unknown.join(", ")}`);
+  const overridden = [...template.packageManaged].filter((key) => Object.hasOwn(values, key));
+  if (overridden.length)
+    throw new Error(
+      `Parameter file must not set package-managed parameters: ${overridden.join(", ")}`
+    );
+  const missing = templateKeys.filter(
+    (key) => !template.packageManaged.has(key) && !Object.hasOwn(values, key) && !Object.hasOwn(template.definitions[key] ?? {}, "Default")
+  );
+  if (missing.length)
+    throw new Error(`Parameter file is missing required consumer values: ${missing.join(", ")}`);
+  return values;
+}
+function resolvedReleaseParameters(supplied, template, managedValues) {
+  const templateKeys = Object.keys(template.definitions);
+  return templateKeys.map((key) => {
+    const value2 = template.packageManaged.has(key) ? managedValues[key] : supplied[key] ?? template.definitions[key]?.Default;
+    if (value2 === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
+    return parameter(key, String(value2));
+  });
+}
+function deploymentHandoff(input) {
+  const prefix = input.outputDir.replace(/\/+$/, "");
+  const path = (name) => `${prefix}/${name}`;
+  const parameterFile = path("parameters.json");
+  return {
+    template: "template.yml",
+    lambdaZip: "lambda.zip",
+    releaseFile: "release.json",
+    artifact: { bucket: input.artifactBucket, key: input.artifactKey },
+    release: input.release,
+    parameters: "parameters.json",
+    commands: {
+      upload: [
+        "aws",
+        "s3",
+        "cp",
+        path("lambda.zip"),
+        `s3://${input.artifactBucket}/${input.artifactKey}`,
+        "--region",
+        "$AWS_REGION"
+      ],
+      deploy: [
+        "aws",
+        "cloudformation",
+        "deploy",
+        "--stack-name",
+        "$STACK_NAME",
+        "--template-file",
+        path("template.yml"),
+        "--role-arn",
+        "$AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN",
+        "--region",
+        "$AWS_REGION",
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--parameter-overrides",
+        `file://${parameterFile}`,
+        "--no-fail-on-empty-changeset",
+        "--no-cli-pager"
+      ]
+    }
+  };
+}
+function copyableCommand(command) {
+  return command.map(
+    (argument) => /^\$[A-Z][A-Z0-9_]*$/.test(argument) ? argument : `'${argument.replaceAll("'", `'\\"'\\"'`)}'`
+  ).join(" ");
+}
 try {
   const packageVersion = await installedPackageVersion();
   const bundledAssets = fileURLToPath3(new URL("../client", import.meta.url));
-  if (args[0] === "deploy") {
-    const artifactDir = requiredOption("--artifact-dir");
-    const version = requiredOption("--version", packageVersion);
-    await deployLambda({
-      artifactDir,
-      assetsDir: option("--assets-dir", bundledAssets) ?? bundledAssets,
-      assetsBucket: requiredOption("--assets-bucket"),
-      assetsBaseUrl: requiredOption("--assets-base-url"),
-      functionName: requiredOption("--function-name"),
-      version,
-      dryRun: args.includes("--dry-run")
-    });
-    console.log(JSON.stringify({ deployed: true, version }));
-  } else if (args[0] === "publish-assets") {
+  if (args[0] === "publish-assets") {
     const version = requiredOption("--version", packageVersion);
     const assetPath = await publishClientAssets({
       assetsDir: option("--assets-dir", bundledAssets) ?? bundledAssets,
@@ -2427,7 +2463,7 @@ try {
     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";
-    const existing = await existingParameters(output);
+    const existing = await existingParameters(output, true);
     const consumerConfigPath = option("--bootstrap-config");
     const consumerConfig = consumerConfigPath ? await readBootstrapConfig(consumerConfigPath) : void 0;
     const existingValues = Object.fromEntries(
@@ -2713,7 +2749,7 @@ ${plan.notes.join("\n")}`);
     }
   } else if (args[0] !== "package")
     throw new Error(
-      "Usage: ze-great-dashboard-aws package|parameters|bootstrap|publish-assets|deploy|doctor [options]"
+      "Usage: ze-great-dashboard-aws package|parameters|bootstrap|publish-assets|doctor [options]"
     );
   else {
     const boardConfig = option("--board-config");
@@ -2721,13 +2757,41 @@ ${plan.notes.join("\n")}`);
     if (!boardConfig) throw new Error("--board-config is required");
     if (!version)
       throw new Error("Unable to determine the package version; pass --version explicitly");
+    const outputDir = option("--output", "aws-dashboard-release") ?? "aws-dashboard-release";
+    const parametersPath = option("--parameters", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
+    const template = await templateParameters();
+    const consumerParameters = validateConsumerParameters(
+      await existingParameters(parametersPath),
+      template
+    );
     const metadata = await packageLambda({
       boardConfigPath: boardConfig,
-      outputDir: option("--output", "aws-release") ?? "aws-release",
+      outputDir,
       version,
       assetDomain: option("--asset-domain")
     });
-    console.log(JSON.stringify(metadata));
+    const resolvedParameters = resolvedReleaseParameters(consumerParameters, template, {
+      LambdaArtifactKey: metadata.artifactKey,
+      DashboardVersion: metadata.dashboardVersion
+    });
+    await writeFile3(
+      `${outputDir}/parameters.json`,
+      `${JSON.stringify(resolvedParameters, null, 2)}
+`
+    );
+    const handoff = deploymentHandoff({
+      outputDir,
+      artifactBucket: resolvedParameters.find(({ ParameterKey }) => ParameterKey === "LambdaArtifactBucket")?.ParameterValue ?? "",
+      artifactKey: metadata.artifactKey,
+      release: metadata
+    });
+    await writeFile3(`${outputDir}/deployment.json`, `${JSON.stringify(handoff, null, 2)}
+`);
+    console.log(`Packaged ${outputDir}/lambda.zip and ${outputDir}/template.yml`);
+    console.log(`Complete parameters: ${outputDir}/parameters.json`);
+    console.log(`Deployment handoff: ${outputDir}/deployment.json`);
+    console.log(`Upload: ${copyableCommand(handoff.commands.upload)}`);
+    console.log(`Deploy: ${copyableCommand(handoff.commands.deploy)}`);
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);

package/dist/index.d.ts

@@ -22,15 +22,6 @@ export type LambdaPackageOptions = {
     assetDomain?: string;
 };
 export declare function packageLambda(options: LambdaPackageOptions): Promise<PackagedRelease>;
-export type DeployLambdaOptions = {
-    artifactDir: string;
-    assetsDir: string;
-    assetsBucket: string;
-    assetsBaseUrl: string;
-    functionName: string;
-    version: string;
-    dryRun?: boolean;
-};
 export type PublishClientAssetsOptions = {
     assetsDir: string;
     assetsBucket: string;
@@ -39,6 +30,4 @@ export type PublishClientAssetsOptions = {
 };
 /** Publishes the versioned client half of a provider-managed release. */
 export declare function publishClientAssets(options: PublishClientAssetsOptions): Promise<string>;
-/** Performs the AWS-specific half of a release using explicit deployment outputs. */
-export declare function deployLambda(options: DeployLambdaOptions): Promise<void>;
 export declare function cloudFormationTemplate(): Promise<string>;

package/dist/index.js

@@ -2062,34 +2062,6 @@ async function publishClientAssets(options) {
   ]);
   return assetPath;
 }
-async function deployLambda(options) {
-  const artifactDir = resolve2(options.artifactDir);
-  const assetsDir = resolve2(options.assetsDir);
-  await readFile3(join2(artifactDir, "lambda.zip"));
-  await readFile3(join2(assetsDir, "index.html"));
-  if (options.dryRun) return;
-  const assetPath = await publishClientAssets(options);
-  await run("aws", [
-    "lambda",
-    "update-function-code",
-    "--function-name",
-    options.functionName,
-    "--zip-file",
-    `fileb://${join2(artifactDir, "lambda.zip")}`,
-    "--no-cli-pager"
-  ]);
-  await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
-  await run("aws", [
-    "lambda",
-    "update-function-configuration",
-    "--function-name",
-    options.functionName,
-    "--environment",
-    `Variables={ASSET_PATH=${assetPath},BOARD_CONFIG_URL=./board.yaml,HOST=0.0.0.0}`,
-    "--no-cli-pager"
-  ]);
-  await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
-}
 async function cloudFormationTemplate() {
   return readFile3(fileURLToPath2(new URL("../template.yml", import.meta.url)), "utf8");
 }
@@ -2106,7 +2078,6 @@ export {
   checkBootstrap,
   cloudFormationTemplate,
   coreBootstrapOutputs,
-  deployLambda,
   deployedBootstrapStack,
   formatBootstrapCheckText,
   githubOidcProvider,

package/package.json

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