serverless-ircd 0.1.0 → 0.2.0

package/README.md

@@ -6,14 +6,16 @@ platform-agnostic core, and two thin adapters run it on **Cloudflare Workers**
 
 One TypeScript codebase. Two serverless substrates. No S2S linking in v1.
 
-> **Status:** **v0.1.0 (preview).** The pure protocol core, the
+> **Status:** **v0.2.0 (preview).** The pure protocol core, the
 > `IrcRuntime` port + in-memory runtime, a runnable local CLI server,
-> and the Cloudflare Workers adapter (deployed to staging) are all
-> functional. SASL, flood control, the AWS adapter, server-password
-> enforcement, and the CI coverage gate are still ahead. See
-> `CHANGELOG.md` for the v0.1.0 manifest, `docs/release.md` for the
-> release process, and `progress.md` / `tickets.md` for per-ticket
-> status.
+> the **Cloudflare Workers** adapter, and the **AWS** (API Gateway
+> WebSocket + Lambda + DynamoDB + CDK) adapter are all functional and
+> deployed to staging. SASL (`PLAIN`), token-bucket flood control,
+> server-password enforcement, hostmask cloaking, connection admission,
+> IRCv3 chat history, and a CI coverage + mutation-testing gate landed
+> in v0.2.0. Remaining 0.x work: oper credentials /
+> config loader, SASL `EXTERNAL` (mTLS), and production TLS transport.
+> See `CHANGELOG.md` for the per-release manifests.
 
 ---
 
@@ -52,7 +54,7 @@ Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
 └─────────────────────────────────────────────────────────────────┘
             ▲                                   ▲
 ┌────────────────────────────┐      ┌──────────────────────────────┐
-│  adapters/cf               │      │  adapters/aws                │
+│  packages/cf-adapter       │      │  packages/aws-adapter        │
 │    ConnectionDO            │      │    $connect/$disconnect/     │
 │    ChannelDO               │      │    $default Lambda handlers  │
 │    RegistryDO              │      │    DynamoDB tables           │
@@ -60,8 +62,8 @@ Hexagonal / ports-and-adapters. The core reasons about IRC; adapters move bytes.
 └────────────────────────────┘      └──────────────────────────────┘
 ```
 
-A planned `packages/in-memory-runtime` provides a reference implementation of
-`IrcRuntime` used by integration tests and a local CLI server.
+`packages/in-memory-runtime` is the reference implementation of
+`IrcRuntime`, used by integration tests and the local CLI server.
 
 ### The key idea: pure reducers + location-of-authority
 
@@ -98,34 +100,36 @@ ServerlessIRCd/
 ├── packages/
 │   ├── irc-core/          pure protocol + reducers (the brain)
 │   ├── irc-server/        orchestration, IrcRuntime port, dispatch
-│   ├── in-memory-runtime/ reference runtime + local CLI server (planned)
-│   ├── cf-adapter/        Durable Objects + CfRuntime (planned)
-│   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime (planned)
+│   ├── in-memory-runtime/ reference runtime (used by tests + local CLI)
+│   ├── irc-test-support/  parametrized IRC scenario suite + harness seam
+│   ├── cf-adapter/        Durable Objects + CfRuntime
+│   └── aws-adapter/       Lambda + DynamoDB + AwsRuntime
 ├── apps/
-│   ├── cf-worker/         worker entry, DO migrations, bindings (planned)
-│   ├── aws-stack/         CDK app entry (planned)
-│   └── local-cli/         runnable WS server using in-memory-runtime
+│   ├── cf-worker/         worker entry, DO migrations, bindings
+│   ├── aws-stack/         CDK stack (APIGW WS + Lambda + DynamoDB)
+│   └── local-cli/         runnable WS + TCP server using in-memory-runtime
 ├── tools/
-│   └── tcp-ws-forwarder/ local TCP↔ws/wss bridge for stock IRC clients
-├── docs/
-│   └── architecture-aws.md
+│   ├── tcp-ws-forwarder/  local TCP↔ws/wss bridge for stock IRC clients
+│   └── ci-hardening/      coverage-gate + mutation-config validators
 ├── pnpm-workspace.yaml    turbo.json   tsconfig.base.json
-└── PLAN.md                progress.md   tickets.md
+└── README.md              CHANGELOG.md
 ```
 
 ---
 
 ## Toolchain
 
-| Concern        | Choice                                            |
-|----------------|---------------------------------------------------|
-| Runtime        | Node ≥ 20, ES2022+                                |
-| Package mgr    | pnpm workspaces                                   |
-| Build cache    | turbo                                             |
-| Language       | TypeScript (strict, `exactOptionalPropertyTypes`) |
-| Test runner    | vitest + `@vitest/coverage-v8`                    |
-| Property tests | fast-check                                        |
-| Lint / format  | Biome                                             |
+| Concern          | Choice                                            |
+|------------------|---------------------------------------------------|
+| Runtime          | Node ≥ 20, ES2022+                                |
+| Package mgr      | pnpm workspaces                                   |
+| Build cache      | turbo                                             |
+| Language         | TypeScript (strict, `exactOptionalPropertyTypes`) |
+| Test runner      | vitest + `@vitest/coverage-v8`                    |
+| Property tests   | fast-check                                        |
+| Mutation tests   | Stryker (≥80% score gate on irc-core)             |
+| AWS IaC          | AWS CDK v2                                        |
+| Lint / format    | Biome                                             |
 
 ---
 
@@ -140,26 +144,37 @@ pnpm build                # build all packages (turbo)
 pnpm typecheck            # tsc --noEmit across the workspace
 pnpm test                 # run all tests once
 pnpm test:watch           # vitest watch mode
-pnpm coverage             # tests + v8 coverage report
+pnpm coverage             # tests + v8 coverage report (enforces thresholds)
 
 pnpm lint                 # biome check .
 pnpm lint:fix             # biome check --write .
 pnpm format               # biome format --write .
 
+pnpm mutation             # Stryker spot-check on irc-core (protocol + commands)
+
 pnpm clean                # remove dist/coverage/.turbo + node_modules
 ```
 
 Coverage reports are written to `packages/*/coverage/`. CI (`.github/workflows/ci.yml`)
-runs lint, typecheck, and coverage on every push and pull request.
+runs lint, typecheck, the coverage gate, the parametrized contract suite, and a
+Stryker mutation spot-check on every push and pull request. Coverage thresholds
+enforce 100% on `irc-core` / `irc-server` / `in-memory-runtime` and ≥90% on every
+other package.
 
 ---
 
 ## Running the local server
 
-`apps/local-cli` is a runnable WebSocket IRC server built on the in-memory
-runtime. It's the manual-test harness and the e2e fixture target — the same
-`irc-core` reducers and `ConnectionActor` the cloud adapters will use, just
-wired to a plain `ws.WebSocketServer` on localhost.
+`apps/local-cli` is a runnable IRC server built on the in-memory runtime.
+It's the manual-test harness and the e2e fixture target — the same
+`irc-core` reducers and `ConnectionActor` the cloud adapters use, just
+wired to plain localhost listeners. By default it binds **two** listeners
+that share one runtime, so a TCP client and a WS client can see each other
+(cross-transport channel broadcast):
+
+- a **WebSocket** listener (the serverless transport) on `--port`, and
+- an **RFC-style TCP** listener on `--tcp-port` (default `<port> + 1`) so
+  real IRC clients (WeeChat, HexChat, irssi, …) can dial in directly.
 
 First build the workspace (the CLI runs from compiled `dist/`):
 
@@ -178,37 +193,50 @@ pnpm --filter local-cli start --port 6667 --host 127.0.0.1
 On startup it logs a JSON line like:
 
 ```json
-{"ts":"...","level":"info","msg":"local-cli listening","url":"ws://127.0.0.1:6667/","port":6667,"hostname":"127.0.0.1"}
+{"ts":"...","level":"info","msg":"local-cli listening","wsUrl":"ws://127.0.0.1:6667/","port":6667,"tcpPort":6668,"hostname":"127.0.0.1"}
 ```
 
 ### CLI flags
 
-| Flag         | Default     | Description                                  |
-|--------------|-------------|----------------------------------------------|
-| `--port <n>` | `6667`      | TCP port to bind. Use `0` for an ephemeral.  |
-| `--host <h>` | `127.0.0.1` | Hostname / interface to bind.                |
-| `-h, --help` |             | Show help and exit.                          |
+| Flag               | Default       | Description                                            |
+|--------------------|---------------|--------------------------------------------------------|
+| `--port <n>`       | `6667`        | WebSocket port to bind. Use `0` for an ephemeral.      |
+| `--host <h>`       | `127.0.0.1`   | Hostname / interface to bind.                          |
+| `--tcp-port <n>`   | `<port> + 1`  | TCP port for RFC-style IRC clients.                    |
+| `--no-tcp`         |               | Disable the TCP listener (WebSocket only).             |
+| `--motd-file <p>`  | built-in      | Read MOTD lines from this file (one per line).         |
+| `-h, --help`       |               | Show help and exit.                                    |
 
 Pass `--host 0.0.0.0` to expose the server on all interfaces. `SIGINT` /
 `SIGTERM` perform a graceful shutdown (closes active sockets, then exits).
 
 ### Connecting
 
-The server speaks WebSocket text frames (one IRC message per frame). Point any
-WebSocket-capable IRC client (WeeChat with the `irc` protocol's WS relay, or a
-small script) at `ws://127.0.0.1:6667/`. Server name and MOTD are fixed
-defaults (`irc.example.com`) until the config-loader ticket lands.
+The WebSocket listener speaks WebSocket text frames (one IRC message per
+frame) — point any WebSocket-capable IRC client or script at
+`ws://127.0.0.1:6667/`. The TCP listener speaks plain RFC IRC over the
+wire, so stock clients connect directly, e.g. in WeeChat:
+
+```
+/connect 127.0.0.1/6668
+```
+
+No `tcp-ws-forwarder` is needed for local development — both transports
+are built in. The MOTD is the built-in default unless `--motd-file` is
+given.
 
 ---
 
-## Connecting a TCP IRC client (TCP→WS forwarder)
+## Connecting a TCP IRC client to a deployed stack (TCP→WS forwarder)
 
-v1 is WebSocket-only, so a stock TCP IRC client (WeeChat, HexChat, irssi, …)
-cannot dial a deployed worker or the local WS server directly.
-`tools/tcp-ws-forwarder` is a local bridge: it listens on a TCP port and, for
-each connection, opens one WebSocket to a `ws://` / `wss://` target and pumps
-IRC lines both ways — reassembling the TCP byte stream into one message per WS
-frame outbound, and normalizing inbound frames back to canonical CRLF.
+The local CLI ships a built-in TCP listener, so no bridge is needed for local
+development. Deployed stacks (Cloudflare Workers and AWS API Gateway) are
+WebSocket-only, so a stock TCP IRC client (WeeChat, HexChat, irssi, …) cannot
+dial them directly. `tools/tcp-ws-forwarder` is a local bridge for that case:
+it listens on a TCP port and, for each connection, opens one WebSocket to a
+`ws://` / `wss://` target and pumps IRC lines both ways — reassembling the TCP
+byte stream into one message per WS frame outbound, and normalizing inbound
+frames back to canonical CRLF.
 
 Build the workspace, then start the forwarder (from the repo root):
 
@@ -255,14 +283,15 @@ This project follows strict TDD (Red → Green → Refactor) — every reducer i
 landed test-first. See the project-level `CLAUDE.md` / `AGENTS.md` for the
 full rules.
 
-| Layer            | Tooling                                 | What it asserts                       |
-|------------------|-----------------------------------------|---------------------------------------|
-| Parser/serializer| vitest + fast-check                     | Grammar correctness, round-trip       |
-| Reducers (core)  | vitest pure unit tests                  | `(state,msg) → {state,effects}` exact |
-| Runtime contract | vitest parametrized over `IrcRuntime`   | Same scenarios pass in-memory+CF+AWS  |
-| CF adapter       | `vitest-pool-workers` (real workerd)    | DO behavior, alarms, stub fanout      |
-| AWS adapter      | vitest + dynamodb-local / localstack    | DynamoDB schema, transactions, fanout |
-| E2E              | real WS clients in `tools/irc-client`   | RFC-shaped flows vs deployed stack    |
+| Layer              | Tooling                                     | What it asserts                       |
+|--------------------|---------------------------------------------|---------------------------------------|
+| Parser/serializer  | vitest + fast-check                         | Grammar correctness, round-trip       |
+| Reducers (core)    | vitest pure unit tests                      | `(state,msg) → {state,effects}` exact |
+| Mutation (core)    | Stryker spot-check (≥80% score gate)        | Reducer test quality, surviving mutants |
+| Runtime contract   | vitest parametrized via `irc-test-support`  | Same scenarios pass in-memory+CF+AWS  |
+| CF adapter         | `vitest-pool-workers` (real workerd)        | DO behavior, alarms, stub fanout      |
+| AWS adapter        | vitest + testcontainers (DynamoDB Local)    | DynamoDB schema, transactions, fanout |
+| E2E                | `scripts/smoke.mjs` against deployed stack   | CONNECT→REGISTER→JOIN→PRIVMSG→QUIT    |
 
 **Determinism:** reducers never touch real timers or randomness. A `Clock`
 port and an `IdFactory` port are injected so tests are fully deterministic.
@@ -274,20 +303,22 @@ port and an `IdFactory` port are injected so tests are fully deterministic.
 A v1 ships when `irc-core` is at 100% coverage, the parametrized contract
 suite passes against every runtime, both adapters are deployed to staging,
 and ≥3 reference clients (WeeChat, HexChat, IRCCloud, TheLounge) connect
-cleanly. Full per-ticket status lives in `progress.md`. Per-release
-manifests live in `CHANGELOG.md`; the release process is documented in
-`docs/release.md`.
+cleanly. Per-release manifests live in `CHANGELOG.md`.
 
 - **Phase 0** — Foundation (monorepo, turbo, vitest, biome, CI). ✅
-- **Phase 1** — Pure protocol engine: reducers, IRCv3 caps, isupport.
-  Most of this landed in **v0.1.0**; SASL and flood control are still
-  pending.
+- **Phase 1** — Pure protocol engine: reducers, IRCv3 caps, isupport,
+  SASL (`PLAIN`), token-bucket flood control, chat history. ✅ (most in
+  **v0.1.0**; SASL/flood/chathistory landed in **v0.2.0**).
 - **Phase 2** — `IrcRuntime` port, in-memory runtime, `ConnectionActor`,
   local CLI, parametrized contract suite. ✅ landed in **v0.1.0**.
 - **Phase 3** — Cloudflare adapter (ConnectionDO / ChannelDO / RegistryDO).
-  ✅ landed in **v0.1.0** (staging only; prod deploy is manual).
+  ✅ landed in **v0.1.0** (staging auto-deploy via CI; prod deploy is manual).
 - **Phase 4** — AWS adapter (APIGW WS + Lambda + DynamoDB + CDK).
+  ✅ landed in **v0.2.0** (staging auto-deploy via CI; prod deploy is manual).
 - **Phase 5** — Observability, security hardening, config, CI gates.
+  ✅ mostly landed (logger port, server-password, cloaking, admission
+  limits, coverage + mutation gates). Remaining: oper credentials / config
+  loader.
 - **Phase 6** — Load testing, client compatibility sweep, ADRs.
 
 ---
@@ -296,28 +327,31 @@ manifests live in `CHANGELOG.md`; the release process is documented in
 
 **Core (RFC 1459/2812 subset):** registration (`NICK`/`USER`/`CAP`/`PASS`),
 `PING`/`PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`, `MODE` (user +
-channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`, `MOTD`.
+channel), `TOPIC`, `KICK`, `INVITE`, `NAMES`, `LIST`, `WHO`, `WHOIS`, `MOTD`,
+`AWAY`.
 
 **Channel modes:** `o v b i k l t n m s p`.
 **User modes:** `i`, `o` (local only), `w`, `s`.
 
 **IRCv3 extensions (negotiated via `CAP`):** `message-tags`, `server-time`,
-`account-tag`, `echo-message`, `batch`, `sasl` (`PLAIN`, `EXTERNAL` reserved),
-`multi-prefix`, `away-notify`, `chghost`, `invite-notify`, `extended-join`.
+`account-tag`, `echo-message`, `batch`, `sasl` (`PLAIN` implemented,
+`EXTERNAL` reserved pending mTLS), `multi-prefix`, `away-notify`, `chghost`,
+`invite-notify`, `extended-join`, `draft/chathistory`, `safelist`.
 
-**Transport:** WebSocket text frames only (one IRC message per frame, with
-tolerance for `\r\n`-joined frames). No plaintext TCP in v1 — keeps the
-serverless story clean. Stock TCP IRC clients reach the server through the
-local [`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-tcpws-forwarder).
+**Transport:** deployed stacks (Cloudflare Workers, AWS API Gateway) speak
+WebSocket text frames only (one IRC message per frame, with tolerance for
+`\r\n`-joined frames). The local CLI additionally binds a plain RFC TCP
+listener for direct IRC-client access. Stock TCP IRC clients reach a deployed
+WebSocket endpoint through the local
+[`tcp-ws-forwarder`](#connecting-a-tcp-irc-client-to-a-deployed-stack-tcpws-forwarder).
 
 ---
 
 ## Further reading
 
-- `PLAN.md` — full project plan, platform mappings, risks, decisions.
-- `CHANGELOG.md` — per-release manifests (Keep a Changelog format).
-- `docs/release.md` — release process runbook (versioning, tagging,
-  rollback).
-- `progress.md` / `tickets.md` — what's done, what's next.
-- `docs/deployment-cf.md` — Cloudflare deployment guide.
-- `docs/architecture-aws.md` — AWS adapter design notes.
+- `CHANGELOG.md` — per-release manifests (Keep a Changelog format), including
+  the v0.2.0 work (AWS adapter, SASL, flood control, security hardening, CI
+  gates).
+- `README.md` in each `packages/*` and `apps/*` — per-package notes (e.g.
+  `packages/aws-adapter/README.md` for the DynamoDB-Local test setup,
+  `apps/aws-stack/README.md` for CDK commands and localstack validation).

package/apps/aws-stack/README.md

@@ -0,0 +1,73 @@
+# `@serverless-ircd/aws-stack`
+
+AWS CDK v2 stack that provisions the AWS substrate for ServerlessIRCd
+(PLAN §6.2): an API Gateway v2 WebSocket API, a single Node 20 Lambda wired
+to the `$connect` / `$disconnect` / `$default` routes, five DynamoDB tables
+(`Connections`, `ChannelMeta`, `ChannelMembers`, `Nicks`, `Accounts`), and the
+least-privilege IAM glue to let the Lambda read/write the tables and post back
+to connected clients via the management API.
+
+The Lambda handler is currently a stub (`{ statusCode: 200 }`); the real
+`AwsRuntime` dispatch lands in TICKET-040.
+
+## Prerequisites
+
+- Node.js 20+
+- pnpm (workspace root installs this package)
+- An AWS account with credentials configured
+  (`aws configure`, `AWS_PROFILE`, or `SSO`)
+
+## Commands
+
+```sh
+pnpm cdk:synth          # synthesize the CloudFormation template (cdk.out/)
+pnpm deploy:staging     # cdk deploy --all
+pnpm deploy:prod        # cdk deploy --all --require-approval never
+pnpm test               # synth-time assertions (no AWS, no Docker)
+pnpm typecheck
+```
+
+Repo-level shortcuts (from the monorepo root):
+
+```sh
+pnpm deploy:aws:staging
+pnpm deploy:aws:prod
+pnpm smoke:aws:staging   # deferred to TICKET-043
+```
+
+## Optional localstack validation
+
+The default `pnpm test` runs only the in-process synth assertions
+(`tests/stack.test.ts`). A deploy-time check against localstack lives in
+`tests/localstack.test.ts` and is **skipped unless `LOCALSTACK=1`** is set,
+so CI never depends on a Docker daemon.
+
+To run it locally:
+
+```sh
+# 1. Start localstack (requires Docker)
+docker run --rm -d -p 4566:4566 localstack/localstack
+
+# 2. Install the localstack-aware CDK CLI globally
+npm install -g aws-cdk-local
+
+# 3. Point the AWS SDK at localstack (cdklocal reads these)
+export AWS_ACCESS_KEY_ID=test
+export AWS_SECRET_ACCESS_KEY=test
+export AWS_DEFAULT_REGION=us-east-1
+
+# 4. Run the gated test
+LOCALSTACK=1 pnpm test
+```
+
+## Stack outputs
+
+| Output         | Description                                                        |
+|----------------|--------------------------------------------------------------------|
+| `ConnectUrl`   | `wss://` endpoint IRC clients dial.                               |
+| `ManagementUrl`| `https://` endpoint for `ApiGatewayManagementApi.postToConnection`.|
+
+## Handoff
+
+Lambda runtime logic, DynamoDB access patterns, and the `AwsRuntime`
+implementation are TICKET-040. The scheduler/sweeper is TICKET-041/042.

package/apps/aws-stack/bin/aws.ts

@@ -0,0 +1,49 @@
+/**
+ * CDK app entry point for `apps/aws-stack`.
+ *
+ * Run via `tsx bin/aws.ts` (see `cdk.json`). Environment resolves to the
+ * CDK CLI's default account/region when those env vars are set; otherwise
+ * the stack is environment-agnostic (suitable for `cdk synth` and localstack).
+ *
+ * Per-environment isolation is driven by the `environmentName` CDK context
+ * variable (`-c environmentName=staging`). It defaults to `staging` so the
+ * existing deploy pipeline stays green without changes, and it is folded
+ * into the CloudFormation stack id (`IrcAwsStack-<environmentName>`) so
+ * parallel envs coexist in one account+region.
+ */
+
+import { App } from 'aws-cdk-lib';
+import type { IrcStackProps } from '../src/aws-stack.js';
+import { IrcAwsStack } from '../src/aws-stack.js';
+
+const app = new App();
+
+const account = process.env.CDK_DEFAULT_ACCOUNT;
+const region = process.env.CDK_DEFAULT_REGION;
+const environmentName =
+  (app.node.tryGetContext('environmentName') as string | undefined) ?? 'staging';
+
+// Server identity is read from CDK context so deploys can override it
+// without editing source (`-c serverName=…`, `-c networkName=…`,
+// `-c motd=…`). `motd` may be passed as a `\n`-embedded string from the
+// CLI; split it back into lines so the stack re-joins with `\n` and the
+// Lambda config loader round-trips it correctly. Defaults (omitted here)
+// live on the stack itself.
+const serverName = app.node.tryGetContext('serverName') as string | undefined;
+const networkName = app.node.tryGetContext('networkName') as string | undefined;
+const rawMotd = app.node.tryGetContext('motd');
+const motdLines = Array.isArray(rawMotd)
+  ? (rawMotd as string[])
+  : typeof rawMotd === 'string'
+    ? rawMotd.split('\n')
+    : undefined;
+
+const stackProps: IrcStackProps = {
+  environmentName,
+  ...(serverName !== undefined ? { serverName } : {}),
+  ...(networkName !== undefined ? { networkName } : {}),
+  ...(motdLines !== undefined ? { motdLines } : {}),
+  ...(account && region ? { env: { account, region } } : {}),
+};
+
+new IrcAwsStack(app, `IrcAwsStack-${environmentName}`, stackProps);

package/apps/aws-stack/cdk.json

@@ -0,0 +1,10 @@
+{
+  "app": "tsx bin/aws.ts",
+  "context": {
+    "environmentName": "staging"
+  },
+  "watch": {
+    "include": ["src/**", "bin/**"],
+    "exclude": ["tests/**", "dist/**", "node_modules/**"]
+  }
+}

package/apps/aws-stack/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@serverless-ircd/aws-stack",
+  "version": "0.2.0",
+  "private": true,
+  "description": "AWS CDK v2 stack: API Gateway v2 WebSocket API, Lambda, DynamoDB tables, least-privilege IAM",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo cdk.out",
+    "cdk": "cdk",
+    "cdk:synth": "cdk synth",
+    "deploy:staging": "cdk deploy --all --require-approval never",
+    "deploy:prod": "cdk deploy --all --require-approval never",
+    "smoke:staging": "node scripts/smoke.mjs"
+  },
+  "devDependencies": {
+    "aws-cdk": "^2.160.0",
+    "aws-cdk-lib": "^2.160.0",
+    "constructs": "^10.4.0",
+    "@types/node": "^26.1.1",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.28.1",
+    "rimraf": "^6.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "ws": "^8.18.0"
+  },
+  "dependencies": {
+    "@serverless-ircd/aws-adapter": "workspace:*"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/apps/aws-stack/scripts/smoke-helpers.d.mts

@@ -0,0 +1,22 @@
+/**
+ * Type declarations for `scripts/smoke-helpers.mjs` (plain ESM consumed by the
+ * AWS staging smoke e2e). The runtime file ships as `.mjs` so CI can run it
+ * without a build step; this declaration lets the workspace typecheck resolve
+ * the imports from `tests/smoke-helpers.test.ts`.
+ */
+
+export type ParseResult = { url: string; help: boolean };
+
+export declare const DEFAULT_SMOKE_URL: string;
+
+export declare function numericEquals(line: string, code: string): boolean;
+
+export declare function parseArgs(argv: string[]): ParseResult;
+
+export declare function waitForPredicate(
+  predicate: (line: string) => boolean,
+  label: string,
+  received: string[],
+  timeoutMs: number,
+  pollMs: number,
+): Promise<string>;

package/apps/aws-stack/scripts/smoke-helpers.mjs

@@ -0,0 +1,89 @@
+/**
+ * Pure helpers backing the AWS staging smoke e2e (`scripts/smoke.mjs`).
+ *
+ * Kept dependency-free and side-effect-free (apart from the unavoidable
+ * `setTimeout` polling inside `waitForPredicate`) so they can be unit-tested
+ * in isolation. The smoke script itself owns the WebSocket I/O and process
+ * exit codes; these helpers own the parsing and timing logic.
+ */
+
+/** Default WebSocket target when no `--url` is passed (matches the local dev convention). */
+export const DEFAULT_SMOKE_URL = 'ws://localhost:8787';
+
+/**
+ * Numeric command position in an IRC line (after an optional `:server`
+ * prefix). Recognises both `001 :Welcome` and `:irc.example.com 001 ...`.
+ */
+export function numericEquals(line, code) {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  return parts[start] === code;
+}
+
+/**
+ * Parse the smoke script's CLI args. Returns `{ url, help }` — `url` always
+ * carries a sensible default, `help` is set when `-h`/`--help` was requested
+ * so the caller can print usage and exit 0. Throws on unknown flags or a
+ * dangling `--url` with no value.
+ *
+ * @param {string[]} argv
+ * @returns {{ url: string; help: boolean }}
+ */
+export function parseArgs(argv) {
+  let url = DEFAULT_SMOKE_URL;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--') {
+      // POSIX options terminator — `pnpm <script> -- --url x` forwards it.
+      // Nothing positional follows for this script; just consume and continue.
+      continue;
+    }
+    if (a === '--url') {
+      if (next === undefined) {
+        throw new Error('--url requires a value');
+      }
+      url = next;
+      i++;
+    } else if (a === '-h' || a === '--help') {
+      help = true;
+    } else {
+      throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return { url, help };
+}
+
+/**
+ * Resolve with the first entry in `received` that satisfies `predicate`, or
+ * reject with a descriptive message once `timeoutMs` elapses. Polls every
+ * `pollMs` so a live socket can keep appending to `received` (by reference)
+ * between checks.
+ *
+ * @param {(line: string) => boolean} predicate
+ * @param {string} label
+ * @param {string[]} received
+ * @param {number} timeoutMs
+ * @param {number} pollMs
+ * @returns {Promise<string>}
+ */
+export function waitForPredicate(predicate, label, received, timeoutMs, pollMs) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = () => {
+      for (const line of received) {
+        if (predicate(line)) {
+          resolve(line);
+          return;
+        }
+      }
+      if (Date.now() >= deadline) {
+        reject(new Error(`timed out waiting for ${label}; received=${JSON.stringify(received)}`));
+        return;
+      }
+      setTimeout(check, pollMs);
+    };
+    check();
+  });
+}