@continuous-excellence/ze-great-dashboard-aws 0.31.0 → 0.31.2

package/README.md

@@ -1,74 +1,56 @@
 # Ze Great Dashboard on AWS
 
-`@continuous-excellence/ze-great-dashboard-aws` packages a board for a private AWS Lambda or ECS
-deployment. It includes the Lambda runtime, deployment CLI, and CloudFormation templates; browser
-assets are published separately as `@continuous-excellence/ze-great-dashboard-client`.
-
-Deployment mode is persisted in `dashboard-bootstrap.json` and generated application parameters
-as `ComputeMode`. Existing files without that field mean `lambda`. Choose `--mode ecs` during
-bootstrap initialization; routine packaging and diagnostics then select the matching template.
-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.
-
-This deployment path is intended for teams that already operate AWS and have a protected gateway
-such as API Gateway or an ALB. It deliberately does not create a public endpoint, choose an
-authentication policy, or manage secret values.
-
-If you are evaluating the dashboard, start with the repository's
-[local setup](https://github.com/robertfmurdock/ze-great-dashboard#run-it-locally). You do not need
-AWS to try it.
-
-## What you need
+`@continuous-excellence/ze-great-dashboard-aws` validates and packages a board for a private AWS Lambda
+or ECS deployment. It includes the server runtime, deployment CLI, and CloudFormation
+templates. The matching immutable browser client is published separately as
+`@continuous-excellence/ze-great-dashboard-client` and is selected automatically unless you provide
+another exact asset URL.
+
+This package is for teams that already operate AWS and can provide a protected entry path:
+
+- Lambda requires a consumer-owned API Gateway, ALB, or equivalent gateway with private invocation
+  permission.
+- ECS requires consumer-owned subnets, security groups, and protected load balancing or routing for
+  the long-lived Fargate service.
+
+In both modes, a consumer-owned gateway or load balancer defines the public entry and authentication
+boundary.
+
+The templates create no public endpoint, choose no authentication policy, and manage no secret
+values. To evaluate the dashboard without AWS, start with the
+[local setup](https://github.com/robertfmurdock/ze-great-dashboard#try-it).
+
+## Prerequisites
 
 - Node.js 22 or newer, npm, the AWS CLI, and `jq`.
-- An AWS administrator for the one-time bootstrap.
-- A pre-existing central GitHub OIDC provider and a protected GitHub Environment if GitHub Actions
-  will deploy the dashboard.
-- A consumer-owned gateway that can privately invoke Lambda and enforce your access policy.
-
-The included deployment works out of the box with public GitHub repositories and HTTP endpoints
-that do not require credentials. For private GitHub sources, `SecretReference` is the ARN of one
-consumer-owned Secrets Manager JSON map or Parameter Store `SecureString` (for example,
-`{"GITHUB_TOKEN":"github_pat_…"}`). The runtime resolves configured `token_env` names only at
-Lambda cold start and never exposes token values to the browser, API responses, logs,
-CloudFormation parameters, or Lambda environment. The two added AWS SDK clients provide
-IAM-authenticated `GetSecretValue` and decrypted `GetParameter` support in the bundled Lambda, at
-the cost of their bundled code and one cold-start request when private sources are configured.
-
-## Deployment map
-
-1. An administrator creates the artifact bucket and restricted deployment roles using the
-   [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md).
-2. The application owner writes `board.yaml`, packages the Lambda, and deploys its private
-   CloudFormation stack using the
-   [deployment guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md).
-3. The consumer connects the returned `ServerFunctionArn` to its protected gateway.
-4. GitHub Actions can repeat the package-and-deploy step after the administrator configures the two
-   reviewed role ARNs.
-
-## The normal application workflow
-
-Pin an exact package version in the repository that owns the deployment:
+- An AWS administrator for one-time bootstrap.
+- A pre-existing account-level GitHub OIDC provider and protected GitHub Environment when GitHub
+  Actions will deploy the dashboard.
+- Consumer-owned networking, gateway or load balancing, authentication, and runtime health checks.
+
+## Choose and bootstrap a compute mode
+
+Lambda is the compatibility default. Select ECS with `--mode ecs` when running `bootstrap init`.
+The choice is stored in `dashboard-bootstrap.json` and generated application parameters as
+`ComputeMode`; older files without the field mean Lambda.
+
+An explicit mode that conflicts with persisted configuration fails. Changing between Lambda and ECS
+requires regenerated, administrator-reviewed bootstrap and application parameters—it is not a
+routine package option.
+
+Follow the [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md),
+then the [Lambda deployment guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md).
+
+## Package a deployment
+
+Pin the reviewed package version in the repository that owns the deployment:
 
 ```sh
 npm install --save-exact @continuous-excellence/ze-great-dashboard-aws
 ```
 
-Append `@version` when installing a previously reviewed release rather than the current one.
-
-After bootstrap is complete, the recurring workflow is only:
+Append `@version` when installing a previously reviewed release rather than the current one. After
+bootstrap, generate and diagnose application parameters, then package the board:
 
 ```sh
 npm exec -- ze-great-dashboard-aws parameters \
@@ -85,29 +67,50 @@ npm exec -- ze-great-dashboard-aws package \
   --output aws-dashboard-release
 ```
 
-`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.
+For ECS, the persisted parameters select the ECS template and `package` also requires an immutable,
+digest-pinned image through `--image`. The generated `deployment.json` contains structured upload
+and CloudFormation command arguments for the approved deployment process to invoke.
 
-## Package boundaries
+`package` writes release-specific `parameters.json`, `deployment.json`, and `template.yml`, plus
+`lambda.zip` for Lambda. Changing `board.yaml` or the pinned package version uses this same path.
+Run the read-only `bootstrap check` before every deployment.
 
-| The package owns | You own |
-| --- | --- |
-| Board validation and Lambda packaging | Board content and source access |
-| Server runtime and CloudFormation templates | The immutable browser asset host and authentication |
-| Private application CloudFormation template | AWS account administration |
-| Restricted bootstrap templates | Secret values and the credential-map ARN |
-| Read-only preflight and consistency checks | Reviewing and executing AWS changes |
+## Private source credentials
 
-Bootstrap commands never execute mutating AWS operations. They produce plans, parameters, and
-commands for an administrator to review and run explicitly. `bootstrap check` is the named
-read-only live diagnostic used before routine deployments.
+Public GitHub repositories and unauthenticated HTTP sources work without credentials. For private
+sources, set `SecretReference` to the ARN of one consumer-owned Secrets Manager JSON value or
+Parameter Store `SecureString`, for example:
+
+```json
+{"GITHUB_TOKEN":"github_pat_…"}
+```
+
+The board references `GITHUB_TOKEN` through `token_env`; the credential value never belongs in the
+board, bootstrap manifest, CloudFormation parameters, runtime environment variables, logs, API
+responses, or browser. The runtime reads only the exact secret or parameter authorized by the
+application role, resolves configured `token_env` names only at Lambda cold start, and fails closed
+when a key is absent.
+
+## Ownership boundaries
+
+| Package responsibility | Consumer responsibility |
+| --- | --- |
+| Board validation and release packaging | Board content and source permissions |
+| Server runtime and application templates | AWS account and network administration |
+| Restricted bootstrap templates | Reviewing and executing AWS changes |
+| Default immutable client asset selection | Approval of alternate asset hosts |
+| Read-only preflight, doctor, and consistency checks | Gateway, authentication, and health checks |
+| Exact secret-resource integration | Secret values, rotation, and credential-map ARN |
+
+Bootstrap commands do not perform mutating AWS operations. They emit plans, parameters, captures,
+and command arguments for an administrator to review and invoke. `bootstrap check` is the read-only
+live diagnostic used before routine deployments; when it fails, use the
+[bootstrap upgrade runbook](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap-upgrade.md).
 
 ## References
 
 - [Board configuration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
 - [Administrator bootstrap](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
-- [Application deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
+- [Lambda deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
 - [GitHub Actions deployment](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-github-actions.md)
 - [Issue tracker](https://github.com/robertfmurdock/ze-great-dashboard/issues)

package/dist/lambda.mjs

@@ -26039,7 +26039,7 @@ var require_dist_cjs16 = __commonJS({
       Region: { type: "builtInParams", name: "region" },
       UseDualStack: { type: "builtInParams", name: "useDualstackEndpoint" }
     };
-    var version2 = "3.1130.0";
+    var version2 = "3.1131.0";
     var packageInfo = {
       version: version2
     };
@@ -27817,7 +27817,7 @@ var require_dist_cjs17 = __commonJS({
       Region: { type: "builtInParams", name: "region" },
       UseDualStack: { type: "builtInParams", name: "useDualstackEndpoint" }
     };
-    var version2 = "3.1130.0";
+    var version2 = "3.1131.0";
     var packageInfo = {
       version: version2
     };
@@ -52014,7 +52014,7 @@ ${content.join("\n")}
 var version = {
   major: 4,
   minor: 6,
-  patch: 4
+  patch: 5
 };
 
 // node_modules/zod/v4/core/schemas.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "type": "module",
   "description": "AWS server runtime and CloudFormation deployment tooling for Ze Great Dashboard.",
   "keywords": [
@@ -36,7 +36,7 @@
   "dependencies": {
     "fflate": "^0.8.3",
     "yaml": "^2.9.1",
-    "zod": "^4.6.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "esbuild": "^0.28.2",