@continuous-excellence/ze-great-dashboard-aws 0.1.13 → 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Murdock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 
 // packages/aws/src/cli.ts
+import { readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join3 } from "node:path";
+import { parse as parse2 } from "yaml";
 
 // packages/aws/src/index.ts
 import { execFile } from "node:child_process";
-import { cp, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile2, rm, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -116,6 +118,28 @@ function sha256(value) {
 
 // packages/aws/src/index.ts
 var run = promisify(execFile);
+function deploymentTemplate(template, values) {
+  const listed = template.match(/^ {2}PackageManagedParameters: \[([^\]]*)\]\s*$/m)?.[1];
+  if (listed === void 0)
+    throw new Error("CloudFormation template has no PackageManagedParameters metadata");
+  const managed = listed.split(",").map((key) => key.trim()).filter(Boolean);
+  const missing = managed.filter((key) => !Object.hasOwn(values, key));
+  const unknown = Object.keys(values).filter((key) => !managed.includes(key));
+  if (missing.length || unknown.length)
+    throw new Error(
+      `Package-managed CloudFormation parameters are out of sync (missing: ${missing.join(", ") || "none"}; unknown: ${unknown.join(", ") || "none"})`
+    );
+  return managed.reduce((rendered, key) => {
+    const pattern = new RegExp(`^  ${key}: \\{[^\\n]+\\}\\s*$`, "m");
+    const declaration = rendered.match(pattern)?.[0];
+    if (!declaration || /\bDefault:/.test(declaration))
+      throw new Error(`Unable to set the CloudFormation default for ${key}`);
+    return rendered.replace(
+      pattern,
+      declaration.replace(/\s*}\s*$/, `, Default: ${JSON.stringify(values[key])} }`)
+    );
+  }, template);
+}
 async function packageLambda(options) {
   const outputDir = resolve2(options.outputDir);
   await mkdir2(outputDir, { recursive: true });
@@ -137,15 +161,31 @@ async function packageLambda(options) {
       "index.mjs": sha256(await readFile2(join2(runtimeDir, "index.mjs")))
     }
   };
-  const clientSource = fileURLToPath(new URL("../client", import.meta.url));
-  await cp(clientSource, join2(outputDir, "assets"), { recursive: true });
   await writeFile2(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 run("zip", ["-X", "-q", "-r", join2(outputDir, "lambda.zip"), "."], { cwd: runtimeDir });
-  return runtimeMetadata;
+  const lambdaPath = join2(outputDir, "lambda.zip");
+  await run("zip", ["-X", "-q", "-r", lambdaPath, "."], { cwd: runtimeDir });
+  await rm(runtimeDir, { recursive: true, force: true });
+  const lambdaChecksum = sha256(await readFile2(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 writeFile2(
+    join2(outputDir, "template.yml"),
+    deploymentTemplate(await cloudFormationTemplate(), {
+      LambdaArtifactKey: packagedRelease.artifactKey,
+      DashboardVersion: packagedRelease.dashboardVersion
+    })
+  );
+  return packagedRelease;
 }
 async function deployLambda(options) {
   const artifactDir = resolve2(options.artifactDir);
@@ -193,6 +233,9 @@ async function deployLambda(options) {
   ]);
   await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
 }
+async function cloudFormationTemplate() {
+  return readFile2(fileURLToPath(new URL("../template.yml", import.meta.url)), "utf8");
+}
 
 // packages/aws/src/cli.ts
 var args = process.argv.slice(2);
@@ -200,30 +243,116 @@ var option = (name, fallback) => {
   const i = args.indexOf(name);
   return i >= 0 ? args[i + 1] : fallback;
 };
+async function installedPackageVersion() {
+  const packageManifest = JSON.parse(
+    await readFile3(new URL("../package.json", import.meta.url), "utf8")
+  );
+  return typeof packageManifest.version === "string" ? packageManifest.version : "";
+}
+var requiredOption = (name, fallback) => {
+  const value = option(name, fallback);
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+};
+function parameter(key, value) {
+  return { ParameterKey: key, ParameterValue: value };
+}
+async function existingParameters(path) {
+  try {
+    const parsed = JSON.parse(await readFile3(path, "utf8"));
+    if (!Array.isArray(parsed)) throw new Error(`${path} must contain a JSON parameter array`);
+    const values = parsed.map((value) => {
+      if (!value || typeof value !== "object" || typeof value.ParameterKey !== "string" || typeof value.ParameterValue !== "string")
+        throw new Error(
+          `${path} entries must contain string ParameterKey and ParameterValue fields`
+        );
+      return value;
+    });
+    const keys = values.map(({ ParameterKey }) => ParameterKey);
+    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 [];
+    throw error;
+  }
+}
+async function templateParameters() {
+  const template = await cloudFormationTemplate();
+  const block = template.match(/^Parameters:\n[\s\S]*?(?=^[A-Za-z][A-Za-z0-9]*:\s*$)/m)?.[0];
+  if (!block) throw new Error("Unable to read Parameters from the CloudFormation template");
+  const parsed = parse2(block);
+  if (!parsed.Parameters) throw new Error("CloudFormation template has no Parameters");
+  const metadataBlock = template.match(/^Metadata:\n[\s\S]*?(?=^Parameters:\s*$)/m)?.[0];
+  const metadata = metadataBlock ? parse2(metadataBlock).Metadata ?? {} : {};
+  if (metadata.PackageManagedParameters !== void 0 && (!Array.isArray(metadata.PackageManagedParameters) || !metadata.PackageManagedParameters.every((key) => typeof key === "string")))
+    throw new Error("CloudFormation template has invalid PackageManagedParameters metadata");
+  const packageManaged = new Set(metadata.PackageManagedParameters ?? []);
+  const unknownManaged = [...packageManaged].filter(
+    (key) => !Object.hasOwn(parsed.Parameters ?? {}, key)
+  );
+  if (unknownManaged.length)
+    throw new Error(
+      `CloudFormation template has unknown package-managed parameters: ${unknownManaged.join(", ")}`
+    );
+  return { definitions: parsed.Parameters, packageManaged };
+}
 try {
   if (args[0] === "deploy") {
-    const required = (name) => {
-      const value = option(name);
-      if (!value) throw new Error(`${name} is required`);
-      return value;
-    };
-    const artifactDir = required("--artifact-dir");
+    const artifactDir = requiredOption("--artifact-dir");
     await deployLambda({
       artifactDir,
       assetsDir: option("--assets-dir", join3(artifactDir, "assets")) ?? join3(artifactDir, "assets"),
-      assetsBucket: required("--assets-bucket"),
-      assetsBaseUrl: required("--assets-base-url"),
-      functionName: required("--function-name"),
-      version: required("--version"),
+      assetsBucket: requiredOption("--assets-bucket"),
+      assetsBaseUrl: requiredOption("--assets-base-url"),
+      functionName: requiredOption("--function-name"),
+      version: requiredOption("--version"),
       dryRun: args.includes("--dry-run")
     });
-    console.log(JSON.stringify({ deployed: true, version: required("--version") }));
+    console.log(JSON.stringify({ deployed: true, version: requiredOption("--version") }));
+  } else if (args[0] === "parameters") {
+    const output = option("--output", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
+    const existing = await existingParameters(output);
+    const existingValues = Object.fromEntries(
+      existing.map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
+    );
+    const artifactBucket = option("--artifact-bucket", existingValues.LambdaArtifactBucket);
+    if (!artifactBucket) throw new Error("--artifact-bucket is required");
+    const { definitions, packageManaged } = await templateParameters();
+    const templateKeys = Object.keys(definitions);
+    const hasDefault = (key) => Object.hasOwn(definitions[key] ?? {}, "Default");
+    const hasValue = (key) => key === "LambdaArtifactBucket" || Object.hasOwn(existingValues, key);
+    const missingRequired = templateKeys.filter(
+      (key) => !hasDefault(key) && !packageManaged.has(key) && !hasValue(key)
+    );
+    const staleExisting = Object.keys(existingValues).filter(
+      (key) => !Object.hasOwn(definitions, key)
+    );
+    if (missingRequired.length || staleExisting.length) {
+      throw new Error(
+        `Parameter values are out of sync with the CloudFormation template (missing: ${missingRequired.join(", ") || "none"}; stale: ${staleExisting.join(", ") || "none"})`
+      );
+    }
+    const includeDefaults = args.includes("--include-defaults");
+    const parameters = templateKeys.filter(
+      (key) => !packageManaged.has(key) && (includeDefaults || !hasDefault(key) || Object.hasOwn(existingValues, key))
+    ).map((key) => {
+      const definition = definitions[key];
+      const value = key === "LambdaArtifactBucket" ? artifactBucket : existingValues[key] ?? definition?.Default;
+      if (value === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
+      return parameter(key, String(value));
+    });
+    await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
+`);
+    console.log(JSON.stringify({ output }));
   } else if (args[0] !== "package")
-    throw new Error("Usage: ze-great-dashboard-aws package|deploy [options]");
+    throw new Error("Usage: ze-great-dashboard-aws package|parameters|deploy [options]");
   else {
     const boardConfig = option("--board-config");
-    const version = option("--version", process.env.DASHBOARD_VERSION);
-    if (!boardConfig || !version) throw new Error("--board-config and --version are required");
+    const packageVersion = await installedPackageVersion();
+    const version = option("--version", process.env.DASHBOARD_VERSION ?? packageVersion);
+    if (!boardConfig) throw new Error("--board-config is required");
+    if (!version)
+      throw new Error("Unable to determine the package version; pass --version explicitly");
     const metadata = await packageLambda({
       boardConfigPath: boardConfig,
       outputDir: option("--output", "aws-release") ?? "aws-release",

package/dist/index.d.ts

@@ -8,13 +8,16 @@ export type ReleaseMetadata = {
         node: string;
     };
 };
+export type PackagedRelease = ReleaseMetadata & {
+    artifactKey: string;
+};
 export type LambdaPackageOptions = {
     boardConfigPath: string;
     outputDir: string;
     version: string;
     assetDomain?: string;
 };
-export declare function packageLambda(options: LambdaPackageOptions): Promise<ReleaseMetadata>;
+export declare function packageLambda(options: LambdaPackageOptions): Promise<PackagedRelease>;
 export type DeployLambdaOptions = {
     artifactDir: string;
     assetsDir: 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 readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile2, rm, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
@@ -111,6 +111,28 @@ function sha256(value) {
 
 // packages/aws/src/index.ts
 var run = promisify(execFile);
+function deploymentTemplate(template, values) {
+  const listed = template.match(/^ {2}PackageManagedParameters: \[([^\]]*)\]\s*$/m)?.[1];
+  if (listed === void 0)
+    throw new Error("CloudFormation template has no PackageManagedParameters metadata");
+  const managed = listed.split(",").map((key) => key.trim()).filter(Boolean);
+  const missing = managed.filter((key) => !Object.hasOwn(values, key));
+  const unknown = Object.keys(values).filter((key) => !managed.includes(key));
+  if (missing.length || unknown.length)
+    throw new Error(
+      `Package-managed CloudFormation parameters are out of sync (missing: ${missing.join(", ") || "none"}; unknown: ${unknown.join(", ") || "none"})`
+    );
+  return managed.reduce((rendered, key) => {
+    const pattern = new RegExp(`^  ${key}: \\{[^\\n]+\\}\\s*$`, "m");
+    const declaration = rendered.match(pattern)?.[0];
+    if (!declaration || /\bDefault:/.test(declaration))
+      throw new Error(`Unable to set the CloudFormation default for ${key}`);
+    return rendered.replace(
+      pattern,
+      declaration.replace(/\s*}\s*$/, `, Default: ${JSON.stringify(values[key])} }`)
+    );
+  }, template);
+}
 async function packageLambda(options) {
   const outputDir = resolve2(options.outputDir);
   await mkdir2(outputDir, { recursive: true });
@@ -132,15 +154,31 @@ async function packageLambda(options) {
       "index.mjs": sha256(await readFile2(join2(runtimeDir, "index.mjs")))
     }
   };
-  const clientSource = fileURLToPath(new URL("../client", import.meta.url));
-  await cp(clientSource, join2(outputDir, "assets"), { recursive: true });
   await writeFile2(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 run("zip", ["-X", "-q", "-r", join2(outputDir, "lambda.zip"), "."], { cwd: runtimeDir });
-  return runtimeMetadata;
+  const lambdaPath = join2(outputDir, "lambda.zip");
+  await run("zip", ["-X", "-q", "-r", lambdaPath, "."], { cwd: runtimeDir });
+  await rm(runtimeDir, { recursive: true, force: true });
+  const lambdaChecksum = sha256(await readFile2(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 writeFile2(
+    join2(outputDir, "template.yml"),
+    deploymentTemplate(await cloudFormationTemplate(), {
+      LambdaArtifactKey: packagedRelease.artifactKey,
+      DashboardVersion: packagedRelease.dashboardVersion
+    })
+  );
+  return packagedRelease;
 }
 async function deployLambda(options) {
   const artifactDir = resolve2(options.artifactDir);

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
+  "keywords": [
+    "aws",
+    "lambda",
+    "cloudformation",
+    "dashboard"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/robertfmurdock/ze-great-dashboard.git"
@@ -19,7 +29,8 @@
   "files": [
     "dist",
     "client",
-    "template.yml"
+    "template.yml",
+    "LICENSE"
   ],
   "dependencies": {
     "yaml": "^2.8.1",

package/template.yml

@@ -1,6 +1,9 @@
 AWSTemplateFormatVersion: '2010-09-09'
 Description: Provider adapter for a Ze Great Dashboard Lambda deployment
 
+Metadata:
+  PackageManagedParameters: [LambdaArtifactKey, DashboardVersion]
+
 Parameters:
   Name: { Type: String, Default: dashboard }
   LambdaArtifactBucket: { Type: String }
@@ -36,7 +39,7 @@ Resources:
                 Resource: !If [HasSecretReference, !Ref SecretReference, !Ref AWS::NoValue]
   ServerLogGroup:
     Type: AWS::Logs::LogGroup
-    Properties: { RetentionInDays: !Ref LogRetentionInDays, LogGroupName: !Sub /aws/lambda/${Name} }
+    Properties: { RetentionInDays: !Ref LogRetentionInDays, LogGroupName: !Sub '/aws/lambda/${Name}' }
   ServerFunction:
     Type: AWS::Lambda::Function
     DependsOn: ServerLogGroup