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

package/README.md

@@ -1,163 +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
-```
-
-If you retain a captured GitHub OIDC stack, add `--github-oidc-stack-json
-github-oidc-deployed-stack.json` to have the doctor warn when the installed package contains a
-newer bootstrap template revision. The warning is advisory and does not make the application
-deployment perform bootstrap changes.
 
-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
-
-ARTIFACT_BUCKET="$(jq -er \
-  '.[] | select(.ParameterKey == "LambdaArtifactBucket") | .ParameterValue' \
-  aws-dashboard-parameters.json)"
-ARTIFACT_KEY="$(jq -er '.artifactKey' aws-dashboard-release/release.json)"
+## Package boundaries
 
-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 upgrade guidance](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md#check-the-bootstrap-template-on-package-upgrades).
-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` | Produce bootstrap templates, parameters, preflight, and guidance; administrators run AWS commands explicitly. |
-| `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/bootstrap/core-v1.yml

@@ -105,6 +105,7 @@ Resources:
 
 Outputs:
   BootstrapContractVersion: { Value: '1' }
+  BootstrapTemplateRevision: { Value: '1.1' }
   ArtifactBucketName: { Value: !Ref ArtifactBucket }
   ArtifactBucketArn: { Value: !GetAtt ArtifactBucket.Arn }
   CloudFormationExecutionRoleArn: { Value: !GetAtt CloudFormationExecutionRole.Arn }

package/bootstrap/github-oidc-v2.yml

@@ -7,6 +7,7 @@ Parameters:
   GitHubOwnerId: { Type: String, Description: Immutable numeric GitHub owner id }
   GitHubRepositoryId: { Type: String, Description: Immutable numeric GitHub repository id }
   GitHubEnvironment: { Type: String, Description: Protected GitHub Environment name }
+  CoreBootstrapStackName: { Type: String }
   ApplicationStackName: { Type: String }
   ConsumerGatewayStackName:
     Type: String
@@ -56,6 +57,31 @@ Resources:
                 Effect: Allow
                 Action: [cloudformation:CreateChangeSet, cloudformation:DescribeChangeSet, cloudformation:ExecuteChangeSet, cloudformation:DeleteChangeSet, cloudformation:DescribeStacks, cloudformation:DescribeStackEvents, cloudformation:GetTemplate, cloudformation:GetTemplateSummary]
                 Resource: !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${ApplicationStackName}/*'
+              - Sid: InspectBootstrapStacks
+                Effect: Allow
+                Action: [cloudformation:DescribeStacks, cloudformation:DetectStackDrift, cloudformation:DescribeStackResourceDrifts]
+                Resource:
+                  - !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${CoreBootstrapStackName}/*'
+                  - !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${AWS::StackName}/*'
+              # Detection-status requests are keyed by an opaque detection id, so AWS does not
+              # support scoping this one read action to a stack ARN.
+              - Sid: ReadBootstrapDriftDetectionStatus
+                Effect: Allow
+                Action: cloudformation:DescribeStackDriftDetectionStatus
+                Resource: '*'
+              # CloudFormation uses the caller's read permissions when these administrator-created
+              # stacks have no service role. Keep resource inspection on the exact bootstrap bucket
+              # and roles whose properties drift detection evaluates.
+              - Sid: InspectBootstrapBucketConfiguration
+                Effect: Allow
+                Action: [s3:GetBucketAcl, s3:GetBucketPolicy, s3:GetBucketPublicAccessBlock, s3:GetEncryptionConfiguration, s3:GetBucketOwnershipControls, s3:GetBucketTagging]
+                Resource: !Sub 'arn:${AWS::Partition}:s3:::${ArtifactBucketName}'
+              - Sid: InspectBootstrapRoleConfiguration
+                Effect: Allow
+                Action: [iam:GetRole, iam:GetRolePolicy, iam:ListRolePolicies, iam:ListAttachedRolePolicies, iam:ListRoleTags]
+                Resource:
+                  - !Ref CloudFormationExecutionRoleArn
+                  - !Sub 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/${ApplicationStackName}-github-deploy'
               - !If
                 - HasConsumerGatewayStack
                 - Sid: ReadConsumerGatewayStack
@@ -71,5 +97,5 @@ Resources:
 
 Outputs:
   BootstrapContractVersion: { Value: '2' }
-  BootstrapTemplateRevision: { Value: '2.1' }
+  BootstrapTemplateRevision: { Value: '2.2' }
   GitHubDeployRoleArn: { Value: !GetAtt GitHubDeployRole.Arn }

package/dist/bootstrap-check.d.ts

@@ -0,0 +1,45 @@
+import { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind } from './bootstrap.js';
+export type BootstrapResourceDifference = {
+    path?: string;
+    differenceType?: string;
+    expectedValue?: string;
+    actualValue?: string;
+};
+export type BootstrapResourceDrift = {
+    logicalId: string;
+    resourceType?: string;
+    status?: string;
+    differences: BootstrapResourceDifference[];
+};
+export type BootstrapResourceDriftResult = {
+    ok: boolean;
+    status: string;
+    detectionId?: string;
+    reason?: string;
+    resources: BootstrapResourceDrift[];
+};
+export type BootstrapStackCheck = {
+    kind: BootstrapKind;
+    stackName: string;
+    stackStatus?: string;
+    contractVersion: string;
+    templateRevision?: string;
+    templateSha256: string;
+    consistency: BootstrapConsistency;
+    resourceDrift?: BootstrapResourceDriftResult;
+};
+export type BootstrapCheck = {
+    ok: boolean;
+    packageVersion: string;
+    stacks: BootstrapStackCheck[];
+};
+export type BootstrapCheckDependencies = {
+    execute(command: string, args: string[]): Promise<string>;
+    sleep?(milliseconds: number): Promise<void>;
+    now?(): number;
+};
+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;
+}, dependencies: BootstrapCheckDependencies): Promise<BootstrapCheck>;

package/dist/bootstrap.d.ts

@@ -5,6 +5,9 @@ export type CloudFormationParameterValue = {
     UsePreviousValue?: boolean;
 };
 export type DeployedBootstrapStack = {
+    StackName?: string;
+    StackId?: string;
+    StackStatus?: string;
     Parameters?: CloudFormationParameterValue[];
     Outputs?: {
         OutputKey: string;
@@ -31,10 +34,36 @@ export type BootstrapConfig = {
         consumerGatewayStackName?: string;
     };
 };
+export type BootstrapTemplateInspection = {
+    kind: BootstrapKind;
+    path: string;
+    contractVersion: string;
+    templateRevision?: string;
+    sha256: string;
+    resources: {
+        logicalId: string;
+        type: string;
+    }[];
+    iamActions: string[];
+};
+export type BootstrapPlan = {
+    packageVersion: string;
+    packageTemplates: BootstrapTemplateInspection[];
+    configuration: BootstrapConfig;
+    notes: string[];
+};
+export type BootstrapConsistency = {
+    ok: boolean;
+    mismatches: string[];
+};
 export declare function bootstrapTemplatePath(kind: BootstrapKind): Promise<string>;
 export declare function bootstrapTemplate(kind: BootstrapKind): Promise<string>;
 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. */
+export declare function bootstrapPlan(config: BootstrapConfig): Promise<BootstrapPlan>;
+/** Compares describe-stacks data with manifest and installed-template values without network access. */
+export declare function bootstrapConsistency(kind: BootstrapKind, config: BootstrapConfig, stackInput: unknown, expectedContract: string, expectedRevision?: string, coreOutputs?: Record<string, string | undefined>): BootstrapConsistency;
 /** Merges a new parameter set with deployed values without silently dropping configuration. */
 export declare function mergeBootstrapParameters(requested: CloudFormationParameterValue[], deployed: CloudFormationParameterValue[]): CloudFormationParameterValue[];
 /** Validates a caller-captured `describe-stacks` result before an upgrade merges it locally. */