@continuous-excellence/ze-great-dashboard-aws 0.6.0 → 0.6.1

package/README.md

@@ -1,169 +1,86 @@
-# Ze Great Dashboard AWS deployment
+# Ze Great Dashboard on AWS
 
-`@continuous-excellence/ze-great-dashboard-aws` packages a configured Ze Great Dashboard as an AWS
-Lambda deployment. It includes the compatible immutable client, Lambda runtime, CLI, and
-CloudFormation template.
+`@continuous-excellence/ze-great-dashboard-aws` packages a board as a private AWS Lambda. It
+includes the Lambda runtime, matching browser client, deployment CLI, and CloudFormation templates.
 
-It does not create a public endpoint, choose an authentication policy, create a gateway, provide a
-secret value, or own consumer AWS infrastructure. You provide the protected gateway and complete the
-administrator-owned bootstrap process first.
+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.
 
-For a deployment workflow that verifies a consumer-owned gateway stack, configure
-`--consumer-gateway-stack gateway-stack-name` during `bootstrap init`. The GitHub OIDC v2 role then
-gets only `cloudformation:DescribeStacks` for that exact stack; the package still does not create,
-invoke, or authenticate the gateway.
+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.
 
-## Prerequisites
+## What you need
 
-You need Node.js 22+, npm, the AWS CLI, `jq`, and one AWS Region for the artifact bucket, Lambda,
-and application stack. You also need a consumer-owned artifact bucket and the bootstrap-created
-restricted roles. Follow the [AWS bootstrap guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
-before this deployment procedure.
+- 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.
 
-## Deploy a dashboard
+The included deployment works out of the box with public GitHub repositories and HTTP endpoints
+that do not require credentials. Private sources require a consumer-owned runtime integration; the
+stock template does not turn a Secrets Manager reference into `token_env` variables.
 
-Use an exact package version in a deployment project:
+## 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:
 
 ```sh
-npm install --save-exact @continuous-excellence/ze-great-dashboard-aws@1.2.3
+npm install --save-exact @continuous-excellence/ze-great-dashboard-aws
 ```
 
-Create `board.yaml`. This small configuration has one GitHub Actions panel and one HTTP value panel;
-see the [board configuration guide](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
-for the full schema.
-
-```yaml
-sources:
-  github:
-    type: github-actions
-    repo: your-org/your-repo
-    branch: main
-    token_env: GITHUB_TOKEN
-
-boards:
-  operations:
-    refresh: 60s
-    panels:
-      - id: build
-        type: pipeline-status
-        source: github
-        pipeline: main.yml
-        position: { x: 0, y: 0, w: 8, h: 6 }
-      - id: version
-        type: http-value
-        url: https://status.example.com/version.json
-        json_path: $.version
-        position: { x: 8, y: 0, w: 4, h: 6 }
-```
+Append `@version` when installing a previously reviewed release rather than the current one.
 
-Generate the application parameters from the non-secret `dashboard-bootstrap.json` created during
-bootstrap:
+After bootstrap is complete, the recurring workflow is only:
 
 ```sh
 npm exec -- ze-great-dashboard-aws parameters \
   --bootstrap-config dashboard-bootstrap.json \
   --output aws-dashboard-parameters.json
-```
-
-After the parameter file exists, run the read-only doctor. It checks local tooling, your AWS
-identity, parameters, the artifact bucket and Region, and the matching hosted client:
 
-```sh
 npm exec -- ze-great-dashboard-aws doctor \
   --parameters aws-dashboard-parameters.json \
   --region us-east-1
-```
 
-After assuming the generated GitHub deploy role, run the canonical blocking consistency check before
-packaging or deployment:
-
-```sh
-npm exec -- ze-great-dashboard-aws bootstrap check \
-  --config dashboard-bootstrap.json --format text
-```
-
-Add `--resource-drift` only for a slower scheduled or manually dispatched CloudFormation drift
-audit. Neither form updates stack resources.
-
-Package the release. This validates the board and writes `lambda.zip`, `release.json`, and
-`template.yml` to the output directory:
-
-```sh
 npm exec -- ze-great-dashboard-aws package \
   --board-config board.yaml \
   --output aws-dashboard-release
 ```
 
-Upload the generated ZIP to the bucket and key specified by the parameter file and release metadata:
+The deployment guide covers the S3 upload, CloudFormation command, gateway handoff, and CI example.
+Changing `board.yaml` or upgrading the pinned package uses this same path.
 
-```sh
-export AWS_REGION=us-east-1
-export STACK_NAME=my-ze-great-dashboard
+## Package boundaries
 
-ARTIFACT_BUCKET="$(jq -er \
-  '.[] | select(.ParameterKey == "LambdaArtifactBucket") | .ParameterValue' \
-  aws-dashboard-parameters.json)"
-ARTIFACT_KEY="$(jq -er '.artifactKey' aws-dashboard-release/release.json)"
-
-aws s3 cp aws-dashboard-release/lambda.zip \
-  "s3://${ARTIFACT_BUCKET}/${ARTIFACT_KEY}" \
-  --region "$AWS_REGION"
-```
-
-Deploy the generated CloudFormation template using the restricted execution role captured from the
-core bootstrap stack:
-
-```sh
-aws cloudformation deploy \
-  --stack-name "$STACK_NAME" \
-  --template-file aws-dashboard-release/template.yml \
-  --role-arn "$CLOUDFORMATION_EXECUTION_ROLE_ARN" \
-  --region "$AWS_REGION" \
-  --capabilities CAPABILITY_NAMED_IAM \
-  --parameter-overrides file://aws-dashboard-parameters.json \
-  --no-fail-on-empty-changeset
-```
-
-The stack outputs `ServerFunctionArn`. Integrate that ARN with your protected API Gateway, ALB, or
-other consumer-owned gateway, then verify the protected `/health` endpoint. The template deliberately
-does not grant public Lambda invoke permission.
-
-## Operate safely
-
-To upgrade, install a newer exact package version and repeat package, upload, and deploy. A change to
-`board.yaml` follows the same path; it does not require a package change.
-
-After upgrading, also check the [bootstrap consistency guidance](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md#check-bootstrap-consistency-on-every-deployment).
-Compatible releases may add optional bootstrap capabilities without changing the contract version.
-If your workflow verifies a consumer-owned gateway stack, add `githubOidc.consumerGatewayStackName`
-to the reviewed manifest and update the GitHub OIDC stack; other consumers do not need to rerun
-bootstrap.
-
-Tokens belong in runtime secret handling, never in board YAML, `aws-dashboard-parameters.json`, or
-the generated ZIP. See [runtime secrets](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#runtime-secrets)
-for the supported secret reference and integration boundary.
-
-## Commands and boundaries
-
-| Command | Use |
+| The package owns | You own |
 | --- | --- |
-| `doctor` | Read-only preflight for an existing parameter file. |
-| `parameters` | Generate or update application CloudFormation parameters. |
-| `package` | Validate board YAML and build a deployable Lambda release. |
-| `bootstrap` | Plan and guide administrator bootstrap work; `bootstrap check` is the explicit live diagnostic used by CI. |
-| `publish-assets` | Provider-only: publish immutable client assets. Normal consumers use the hosted client. |
-| `deploy` | Provider-only: automation helper for a provider-managed asset and Lambda deployment. |
+| Board validation and Lambda packaging | Board content and source access |
+| Compatible immutable browser assets | The protected gateway and authentication |
+| Private application CloudFormation template | AWS account administration |
+| Restricted bootstrap templates | Secret values and runtime credential loading |
+| Read-only preflight and consistency checks | Reviewing and executing AWS changes |
+
+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.
 
-## Further reading and support boundary
+## References
 
 - [Board configuration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/board-configuration.md)
-- [AWS bootstrap](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md)
-- [Consumer deployment and CI setup](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md)
-- [GitHub Actions deployment workflow YAML example](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#github-actions)
-- [Runtime secret integration](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#runtime-secrets)
-- [Repository source](https://github.com/robertfmurdock/ze-great-dashboard)
+- [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)
+- [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)
-- [MIT license](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/LICENSE)
-
-The package owns the Lambda deployment artifact. Gateway design, authentication, secret-value
-provisioning, and consumer AWS account administration remain your responsibility.

package/dist/cli.js

@@ -1341,6 +1341,9 @@ function changeSetCommands(input) {
   const stack = stackName(input.config, input.kind);
   const common = ["--stack-name", stack, "--region", region(input.config)];
   const parameters = [
+    "npm",
+    "exec",
+    "--",
     "ze-great-dashboard-aws",
     "bootstrap",
     "parameters",

package/dist/index.js

@@ -1328,6 +1328,9 @@ function changeSetCommands(input) {
   const stack = stackName(input.config, input.kind);
   const common = ["--stack-name", stack, "--region", region(input.config)];
   const parameters = [
+    "npm",
+    "exec",
+    "--",
     "ze-great-dashboard-aws",
     "bootstrap",
     "parameters",

package/package.json

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