Simplify AWS deployment and operations (#173)

## What changed

- add a complete AWS lifecycle: `deploy aws`, `status aws`, `upgrade
aws`, and guarded `cleanup aws`
- allow one-time non-secret `HAYASEND_AWS_ACCOUNT_ID` / `AWS_REGION`
setup while retaining a live STS account gate on every command
- make `status aws` combine SES production/sending readiness,
CloudFormation state and drift, problematic resources, stack-owned
CloudWatch alarms, public HayaSend identity/health, dashboard link, and
exact next commands
- make updates reuse the existing isolated SAM build and exact
change-set inspection, while requiring an existing stable stack
- make cleanup plan-first, require both `--apply` and exact
`--confirm-stack`, refuse unmanaged/protected/unstable stacks, wait for
verified deletion, and preserve/print retained customer-data resources
- add a copy-paste AWS quickstart and update the CLI and operations
runbooks

## Why

The accepted two-speed direction in #81 and #132 makes AWS native + SES
the sole active Certified candidate. The AWS path therefore needs to be
the easiest path to create, understand, monitor, update, and remove
safely before the terminal-delivery proof in #126 and AWS dogfood in
#105.

A live read-only run against the designated test account correctly
reported that no `hayasend` stack exists and SES is healthy but
sandbox-only, so it did not claim operational or send readiness.

## Validation

- `npm ci` — 0 vulnerabilities
- `npm outdated --json` — no outdated npm dependencies
- `npm run check`
- `npm run check:workers` — 38 tests passed and Wrangler dry-run passed
- `npm test` — 603 tests passed, 6 skipped
- `npm run build`
- `npm run check:conformance`
- `npm run lint:openapi`
- `npm run site:build && npm run site:verify`
- `git diff --check`
- AWS CLI 2.36.10 and SAM CLI 1.164.0

## Safety

This does not deploy or delete AWS resources. Real mutation remains
plan-first, exact-account gated, change-set inspected, and protected by
explicit acknowledgements. Cleanup never purges `DeletionPolicy: Retain`
data resources.

Closes no evidence gate by itself. #126 must still pass from an exact
reviewed main commit before AWS is production-qualified.

Author: yhay81

.github/workflows/ci.yml

@@ -717,7 +717,7 @@ jobs:
           jq --exit-status '
             .entryCount <= 615 and
             .size < 760000 and
-            .unpackedSize < 3900000 and
+            .unpackedSize < 4000000 and
             ([.files[].path] | index("dist/cli.js") != null) and
             ([.files[].path] | index("NOTICE") != null) and
             ([.files[].path] |

README.md

@@ -389,16 +389,21 @@ Requirements:
 - an SES-enabled AWS Region
 - SES production access before sending to unverified recipients
 
-Start with the non-mutating deployment plan. The explicit account ID prevents
-an authenticated shell from silently targeting the wrong account:
+Authenticate once, then keep the expected account and Region as non-secret
+shell configuration. The CLI checks the live STS identity on every lifecycle
+command, so a stale or wrong SSO session cannot silently target another
+account:
 
 ```bash
-aws_account_id="$(aws sts get-caller-identity --query Account --output text)"
 HAYASEND_VERSION=X.Y.Z
-npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws \
-  --account "$aws_account_id" \
-  --region ap-northeast-1 \
-  --stack hayasend
+export AWS_PROFILE=your-sso-profile
+export AWS_REGION=ap-northeast-1
+aws sso login --profile "$AWS_PROFILE"
+export HAYASEND_AWS_ACCOUNT_ID="$(
+  aws sts get-caller-identity --query Account --output text
+)"
+
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws
 ```
 
 The plan validates the tools and template, performs a clean temporary SAM
@@ -408,9 +413,6 @@ AWS. After reviewing it, repeat the command with `--apply`:
 
 ```bash
 npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws \
-  --account "$aws_account_id" \
-  --region ap-northeast-1 \
-  --stack hayasend \
   --log-retention-days 30 \
   --apply
 ```
@@ -423,6 +425,25 @@ and refuses removals, indeterminate actions, or possible replacements unless
 preservation, finite Lambda log retention, failure recovery, and output
 privacy.
 
+The same CLI covers the complete stack lifecycle:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" status aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws --apply
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws \
+  --apply --confirm-stack hayasend
+```
+
+`status aws` combines CloudFormation state and drift, SES sending readiness,
+stack-resource failures, CloudWatch alarms, public API health, and the
+dashboard link. `cleanup aws` is plan-first and deliberately retains the
+DynamoDB table, payload bucket, and enabled inbound data resources; it prints
+their physical IDs for a separate retention or destruction decision. See the
+copy-paste [AWS quickstart](docs/aws-quickstart.md) and the
+[operations runbook](docs/operations.md).
+
 Before choosing a Region or comparing hosted alternatives, review the
 [reproducible AWS cost model](docs/aws-costs.md). It separates SES charges
 from HayaSend infrastructure, shows list price and recurring free allowances

docs/aws-quickstart.md

@@ -0,0 +1,130 @@
+# AWS quickstart
+
+This is the shortest supported path for creating, checking, updating, and
+removing a HayaSend AWS deployment. Use an exact released HayaSend version in
+every infrastructure command.
+
+## 1. Sign in and set the target once
+
+Install Node.js 24 or newer, npm 12 or newer, the current AWS CLI v2, and the
+current AWS SAM CLI. Sign in with your normal AWS SSO profile:
+
+```bash
+export AWS_PROFILE=your-sso-profile
+export AWS_REGION=ap-northeast-1
+aws sso login --profile "$AWS_PROFILE"
+
+export HAYASEND_AWS_ACCOUNT_ID="$(
+  aws sts get-caller-identity --query Account --output text
+)"
+export HAYASEND_VERSION=X.Y.Z
+```
+
+`HAYASEND_AWS_ACCOUNT_ID` and `AWS_REGION` are non-secret configuration. Every
+HayaSend AWS command calls STS and refuses to continue when the authenticated
+account differs. Pass `--account`, `--region`, `--stack`, or `--profile` only
+when overriding these defaults. The default stack name is `hayasend`.
+
+## 2. Create the stack
+
+Generate a read-only plan:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws
+```
+
+Review the account, Region, SES state, parameters, tags, and exact apply
+command in the JSON result. Then apply:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws --apply
+```
+
+Apply builds the packaged SAM application, creates an unexecuted
+CloudFormation change set, prints every resource action, and executes it only
+when no unacknowledged removal or possible replacement exists. HayaSend never
+changes DNS.
+
+## 3. Check whether it is ready
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" status aws
+```
+
+The result keeps two decisions separate:
+
+- `operational` requires a stable stack, no drift reported, no problematic
+  stack resources, all discovered HayaSend alarms in `OK`, and a successful
+  public `/healthz` request;
+- `send_ready` additionally requires SES production access and account
+  sending to be enabled.
+
+The result includes SES quota, only problematic resource and alarm details,
+the CloudWatch dashboard URL, and exact update, cleanup, and deep-diagnostics
+commands. It does not read the bootstrap secret or API keys.
+
+For authenticated application and queue diagnostics, set a scoped key locally
+and run:
+
+```bash
+export HAYASEND_BASE_URL=https://your-api.example
+export HAYASEND_API_KEY=your-scoped-diagnostics-key
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" doctor
+```
+
+Keep the key in an approved secret manager and out of command arguments,
+transcripts, and issue reports.
+
+## 4. Update safely
+
+Plan an update to the existing stack:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws
+```
+
+After reviewing the plan:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws --apply
+```
+
+`upgrade aws` refuses a missing or non-terminal stack and uses the same exact
+change-set inspection as initial deployment. If CloudFormation proposes any
+removal, indeterminate action, or possible replacement, it stops before
+execution. Use `--allow-destructive-changes` only after reviewing every
+printed destructive action.
+
+Run `status aws` again after every update.
+
+## 5. Remove the running stack
+
+First print the deletion plan:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws
+```
+
+Cleanup refuses an unmanaged stack, a non-terminal stack, or a stack with
+termination protection enabled. To delete the stack, repeat the exact name:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws \
+  --apply \
+  --confirm-stack hayasend
+```
+
+The CLI waits for `stack-delete-complete` and verifies that the stack no longer
+exists. It does not purge retained customer data. The DynamoDB table, payload
+bucket, and enabled inbound bucket and KMS key have `DeletionPolicy: Retain`;
+their physical IDs are printed before and after deletion. Decide their
+retention, export, and eventual destruction separately under the applicable
+backup, audit, and privacy policy.
+
+## Routine operating loop
+
+Run `status aws` after deployment, after updates, after AWS incidents, and
+before production canaries. Subscribe a real on-call destination to the
+`AlarmTopicArn`, confirm that subscription, configure an AWS Budget, and use
+the generated dashboard as the first operational view. The complete response
+procedures are in the [operations runbook](operations.md).

docs/cli.md

@@ -571,20 +571,21 @@ are in [Cloudflare cost evidence](cloudflare-costs.md).
 
 ## Plan and deploy to AWS
 
-Run the exact released CLI version from any working directory. The first
-invocation is a non-mutating plan:
+The copy-paste path is in the [AWS quickstart](aws-quickstart.md). Set the
+expected account and Region once:
 
 ```bash
-npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws \
-  --account 123456789012 \
-  --region ap-northeast-1 \
-  --stack hayasend
+export HAYASEND_AWS_ACCOUNT_ID=123456789012
+export AWS_REGION=ap-northeast-1
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws
 ```
 
-`--account` is required even when the AWS CLI already has credentials. The CLI
-calls STS and stops before reading SES or CloudFormation if the authenticated
-account differs. `--region` can instead come from `AWS_REGION` or
-`AWS_DEFAULT_REGION`; `--profile` selects a named AWS profile.
+`--account` overrides `HAYASEND_AWS_ACCOUNT_ID`. One of them is always
+required even when the AWS CLI already has credentials. The CLI calls STS and
+stops before reading SES or CloudFormation if the authenticated account
+differs. `--region` can instead come from `AWS_REGION` or
+`AWS_DEFAULT_REGION`; `--profile` selects a named AWS profile, while
+`AWS_PROFILE` continues to work through the AWS CLI.
 
 The plan:
 
@@ -610,9 +611,6 @@ Apply only after reviewing the plan:
 
 ```bash
 npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" deploy aws \
-  --account 123456789012 \
-  --region ap-northeast-1 \
-  --stack hayasend \
   --tag Environment=production \
   --apply
 ```
@@ -680,6 +678,64 @@ secret and never creates DNS records. If CloudFormation fails, the error
 includes redacted recent stack events for recovery. Follow the
 [operations runbook](operations.md) before retrying.
 
+## Inspect AWS status
+
+Use the same expected-account gate for an infrastructure and sending-readiness
+snapshot:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" status aws
+```
+
+This is read-only and does not require SAM or build the application. It checks
+the AWS CLI and caller identity, SES production/sending state and quota,
+CloudFormation stack state and last reported drift, individual stack
+resources, stack-owned CloudWatch alarms, and the public `/healthz` endpoint.
+Only problematic resources and alarms are expanded in the result. The output
+also links the generated dashboard and prints exact `upgrade aws`, `cleanup
+aws`, and authenticated `doctor` next steps.
+
+`operational` covers infrastructure, alarms, and public health. `send_ready`
+also requires SES production access and sending to be enabled. A missing stack
+is a successful read-only inspection with both values false and an exact
+`deploy aws` plan command.
+
+## Upgrade AWS
+
+`upgrade aws` accepts the same parameters and tags as `deploy aws`, but it
+requires an existing stable stack:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws --apply
+```
+
+Plan mode validates and builds the exact packaged version without changing
+AWS. Apply uses the same isolated SAM build, exact new change-set selection,
+resource-action output, and destructive-change refusal as deployment. Run
+`status aws` after CloudFormation reaches its terminal state.
+
+## Clean up AWS
+
+Cleanup is also plan-first:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws \
+  --apply --confirm-stack hayasend
+```
+
+The CLI refuses stacks without both `Project=HayaSend` and
+`ManagedBy=HayaSendCLI`, non-terminal stacks, and stacks with termination
+protection enabled. Apply requires the exact stack name, starts ordinary
+CloudFormation deletion, waits for `stack-delete-complete`, and verifies that
+the stack is absent.
+
+Cleanup never purges resources protected by `DeletionPolicy: Retain`. Its
+plan and result identify the retained DynamoDB table, payload bucket, and any
+enabled inbound bucket and KMS key. Export, retain, or destroy those resources
+through a separate reviewed data-lifecycle procedure.
+
 ## Send a hosted template
 
 The CLI supports the same `--template` and repeatable `--var KEY=VALUE` shape

docs/operations.md

@@ -1,6 +1,8 @@
 # Operations runbook
 
 This runbook is the minimum operating procedure for an AWS deployment.
+Use the [AWS quickstart](aws-quickstart.md) for the shortest create, status,
+update, and removal path.
 For disposable end-to-end validation, use the
 [dedicated-account integration workflow](aws-integration-testing.md).
 Budget the selected Region and retention policy with the
@@ -15,6 +17,10 @@ The plan-first CLI needs read access for:
 - `ses:GetAccount`;
 - `cloudformation:DescribeStacks`.
 
+`status aws` additionally uses `cloudformation:ListStackResources` and
+`cloudwatch:DescribeAlarms`, then calls the public HayaSend `/healthz`
+endpoint. It does not read log events, message data, or secret values.
+
 `--apply` additionally reads CloudFormation change sets and failure events
 through `cloudformation:ListChangeSets`,
 `cloudformation:DescribeChangeSet`, and
@@ -28,11 +34,53 @@ template, organizational permission boundaries, Region, and enabled inbound
 features, then review it through the same infrastructure process as other
 production roles.
 
+`cleanup aws --apply` needs `cloudformation:DeleteStack` in addition to the
+read operations. CloudFormation still needs its normal service-role or caller
+permissions to delete stack-owned resources. Cleanup never empties or deletes
+resources protected by `DeletionPolicy: Retain`.
+
 The CLI never reads the bootstrap secret value, edits DNS, or passes
 credentials as command-line arguments. Its JSON output contains account IDs,
 principal and resource ARNs, domain suffixes, and stack outputs, so retain it
 as operational metadata rather than posting it publicly.
 
+## Routine lifecycle
+
+Keep the expected account and Region in non-secret environment variables so
+every operation stays short while retaining the live STS safety gate:
+
+```bash
+export HAYASEND_AWS_ACCOUNT_ID=123456789012
+export AWS_REGION=ap-northeast-1
+
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" status aws
+```
+
+Run `status aws` after every deploy or upgrade, at the start of an incident,
+and before a production canary. Do not treat `operational: true` as proof of
+mail delivery: require `send_ready: true`, then complete a controlled send and
+confirm the terminal recipient event and mailbox receipt.
+
+For an update, review the plan before apply:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" upgrade aws --apply
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" status aws
+```
+
+For decommissioning, first record a disposition for retained customer data:
+
+```bash
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws
+npx --yes "@haya-inc/hayasend@${HAYASEND_VERSION}" cleanup aws \
+  --apply --confirm-stack hayasend
+```
+
+The cleanup result repeats retained resource physical IDs after verified stack
+deletion. Do not improvise a bulk purge; handle those resources under the
+applicable recovery, compliance, and privacy policy.
+
 ## After deployment
 
 1. Subscribe the on-call destination to the `AlarmTopicArn` stack output and