serverless-ircd 0.1.0 → 0.2.0

package/.github/workflows/ci.yml

@@ -1,5 +1,24 @@
 name: CI
 
+# Cross-cutting verification pipeline (coverage gate + contract suite
+# on every PR + mutation-testing spot-check on irc-core).
+#
+# Failure modes (any of these blocks the merge):
+#   - biome lint
+#   - tsc strict typecheck across the workspace
+#   - any package unit/integration test
+#   - vitest per-package coverage threshold regression
+#     (100% on irc-core/irc-server/in-memory-runtime, >=90% elsewhere)
+#   - integration contract suite (packages/cf-adapter/tests/integration)
+#   - Stryker mutation score < 80% on irc-core/protocol or
+#     irc-core/commands
+#
+# The coverage gate is split into its own named step so the GitHub
+# Actions UI surfaces "Coverage gate" as the failing step instead of
+# the generic "Test with coverage" name. The mutation job runs in
+# parallel because Stryker is the slowest single task in the pipeline
+# and is independent of the typecheck/lint/coverage chain.
+
 on:
   push:
     branches: [main]
@@ -16,8 +35,6 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node
         uses: actions/setup-node@v4
@@ -37,6 +54,40 @@ jobs:
       - name: Test with coverage
         run: pnpm coverage
 
+      - name: Coverage gate (coverage-thresholds enforced per package)
+        # Vitest enforces 100% line/function/branch/statement coverage
+        # on irc-core/irc-server/in-memory-runtime and >=90% on
+        # cf-adapter/local-cli/tcp-ws-forwarder via the `thresholds`
+        # block in each package's vitest.config.ts. The previous step
+        # exits non-zero on any regression; this named no-op marker
+        # makes the gate explicit in the Actions UI and reserves a
+        # place to plug in a future aggregate-coverage check.
+        if: success()
+        run: |
+          echo "coverage-thresholds: PASSED"
+          echo "  irc-core:        100% (lines/functions/branches/statements)"
+          echo "  irc-server:      100% (lines/functions/branches/statements)"
+          echo "  in-memory-runtime: 100% (lines/functions/branches/statements)"
+          echo "  cf-adapter:      >=90% (lines/functions/branches/statements)"
+          echo "  local-cli:       >=90% (lines/functions/branches/statements)"
+
+      - name: Contract tests (parametrized integration suite)
+        # The parametrized integration contract suite
+        # (packages/cf-adapter/tests/integration) runs the same IRC
+        # scenarios against every runtime via a runtime factory, so
+        # any contract regression in irc-core surfaces here even when
+        # unit coverage is 100%. Invoked explicitly here so the step
+        # name shows up in the Actions UI; the underlying test files
+        # are also exercised by `pnpm coverage` above.
+        run: pnpm --filter @serverless-ircd/cf-adapter test
+
+      - name: CI hardening config self-check
+        # Validates that the coverage gate and mutation-testing
+        # configs exist and meet the documented thresholds. Catches
+        # drift (someone lowering a threshold or dropping a Stryker
+        # config) before it reaches main.
+        run: pnpm --filter @serverless-ircd/ci-hardening test
+
       - name: Upload coverage
         if: always()
         uses: actions/upload-artifact@v4
@@ -45,3 +96,46 @@ jobs:
           path: |
             packages/*/coverage
             apps/*/coverage
+
+  mutation:
+    name: mutation spot-check (irc-core)
+    runs-on: ubuntu-latest
+    # Stryker is the slowest single task; it is independent of the
+    # typecheck/lint/coverage chain and runs in parallel.
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace (irc-core mutation targets)
+        run: pnpm build
+
+      - name: Stryker spot-check on irc-core/protocol
+        # Mutation score threshold >=80% is enforced by the
+        # stryker.protocol.conf.json `thresholds.break` field. The
+        # job fails if the score drops below the gate.
+        run: pnpm mutation:protocol
+
+      - name: Stryker spot-check on irc-core/commands
+        # Mutation score threshold >=80% is enforced by the
+        # stryker.commands.conf.json `thresholds.break` field. The
+        # job fails if the score drops below the gate.
+        run: pnpm mutation:commands
+
+      - name: Upload mutation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: packages/irc-core/reports/mutation

package/.github/workflows/deploy-aws.yml

@@ -0,0 +1,129 @@
+name: deploy-aws
+
+# AWS CDK deploy pipeline.
+#
+# On every push to `main`:
+#   1. Install deps (frozen lockfile).
+#   2. Build the aws-adapter + irc-core/irc-server so the CDK stack
+#      typechecks against real workspace packages.
+#   3. `cdk deploy --all` the `apps/aws-stack` stack (API Gateway v2
+#      WebSocket API, Lambda, DynamoDB tables) to the staging AWS
+#      account/region.
+#   4. Replay the smoke e2e (`scripts/smoke.mjs`) against the deployed
+#      WebSocket endpoint — CONNECT/REGISTER/JOIN/PRIVMSG/QUIT. Failure
+#      blocks the merge (the deploy job is required on `main`).
+#
+# Secrets / variables (configure under repo Settings → Secrets and
+# variables → Actions):
+#   AWS_ACCESS_KEY_ID     Static AWS access key with permission to deploy
+#                          the stack (IAM, APIGW, Lambda, DynamoDB).
+#                          Required unless OIDC is used (see below).
+#   AWS_SECRET_ACCESS_KEY Companion secret key. Required unless OIDC.
+#   AWS_DEPLOY_ROLE_ARN   Optional. When set, the job assumes this role
+#                          via OIDC web identity instead of using static
+#                          access keys. Requires `permissions.id-token:
+#                          write` (declared below) and an OIDC trust
+#                          policy on the role granting
+#                          `sts:AssumeRoleWithWebIdentity` to this repo's
+#                          GitHub OIDC provider.
+#   AWS_REGION            AWS region to deploy into (e.g. us-east-1).
+#
+# Repo variable (Settings → Secrets and variables → Variables):
+#   AWS_SMOKE_URL         Optional. The wss:// URL of the deployed
+#                          WebSocket stage. When unset the workflow
+#                          falls back to reading the stack's `ConnectUrl`
+#                          CloudFormation output via the AWS CLI; if that
+#                          also fails the smoke step is skipped with a
+#                          warning (mirrors the CF pipeline's skip
+#                          behaviour).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# OIDC web identity requires id-token write; contents:read for checkout.
+permissions:
+  id-token: write
+  contents: read
+
+# Prevent two deploys racing the same CloudFormation stack.
+concurrency:
+  group: aws-staging
+  cancel-in-progress: false
+
+jobs:
+  deploy-staging:
+    name: cdk deploy --all (staging)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build workspace
+        run: pnpm build
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      # When AWS_DEPLOY_ROLE_ARN is set, assume it via OIDC web identity
+      # (ignores the static access keys). Otherwise fall back to the
+      # static access-key pair. Both shapes are handled by the action:
+      # an empty role-to-assume is treated as unset.
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ secrets.AWS_REGION }}
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+      - name: Deploy to staging
+        run: pnpm deploy:aws:staging -- -c environmentName=staging
+
+      - name: Resolve smoke URL
+        id: smoke-url
+        env:
+          AWS_SMOKE_URL: ${{ vars.AWS_SMOKE_URL }}
+        run: |
+          if [ -n "$AWS_SMOKE_URL" ]; then
+            echo "url=$AWS_SMOKE_URL" >> "$GITHUB_OUTPUT"
+          else
+            # Fall back to the stack's ConnectUrl CloudFormation output.
+            # Stack name is `IrcAwsStack-<environmentName>`; staging →
+            # `IrcAwsStack-staging`.
+            URL=$(aws cloudformation describe-stacks \
+              --stack-name IrcAwsStack-staging \
+              --query 'Stacks[0].Outputs[?OutputKey==`ConnectUrl`].OutputValue' \
+              --output text 2>/dev/null || true)
+            if [ -n "$URL" ]; then
+              echo "url=$URL" >> "$GITHUB_OUTPUT"
+            else
+              echo "::warning::Unable to resolve the staging WebSocket URL (set the AWS_SMOKE_URL repo variable or check the stack ConnectUrl output); smoke step will be skipped."
+              echo "url=" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+      - name: Smoke e2e
+        if: steps.smoke-url.outputs.url != ''
+        env:
+          SMOKE_URL: ${{ steps.smoke-url.outputs.url }}
+        run: pnpm smoke:aws:staging -- --url "$SMOKE_URL"

package/.github/workflows/deploy-cf.yml

@@ -45,8 +45,6 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node
         uses: actions/setup-node@v4

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs"]
+	path = docs
+	url = https://gitea.com/fowlmouth/ServerlessIRCd.wiki.git

package/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+## Code Style
+
+- **Do not reference ticket IDs in source files.** Never put `TICKET-###` or similar ticket-tracker tokens in `.ts` or `.js` files (code or comments). Describe the intent or cross-reference by feature/command name instead. Ticket tracking lives in `progress.md` / `tickets.md`, not in source.

package/CHANGELOG.md

@@ -0,0 +1,352 @@
+# Changelog
+
+All notable changes to ServerlessIRCd are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/) with
+the 0.x convention (any release may change anything).
+
+For the release process itself — versioning policy, pre-release checklist,
+cutting a tag, rolling back — see [`docs/release.md`](docs/release.md).
+Cross-reference `progress.md` / `tickets.md` for per-ticket detail.
+
+## [0.2.0] - 2026-07-23
+
+### Added — Authentication & flood control (`@serverless-ircd/irc-core`)
+
+- **SASL `AUTHENTICATE`**: pure reducer for the IRCv3 SASL exchange.
+  `PLAIN` is fully implemented (decodes the payload, validates against
+  the injected synchronous `AccountStore` port, emits `900 RPL_LOGGEDIN`
+  + `903 RPL_SASLSUCCESS` on success, `904 ERR_SASLFAIL` on failure).
+  `EXTERNAL` is recognized but stubbed to `904` until mTLS lands; any
+  other mechanism gets `908 ERR_SASLMECHS`. Multi-frame `<=400`-byte
+  chunked payloads and `AUTHENTICATE *` abort (`906 ERR_SASLABORT`) are
+  handled. `CAP sasl` is now negotiated end-to-end (no longer
+  advertised-only).
+- **Token-bucket flood control**: `wrapFloodControl` is a pure
+  higher-order reducer wrapper enforcing a per-connection token bucket.
+  The bucket is refilled from the injected `Clock` (deterministic —
+  never `Date.now()`) and, once it crosses the configured negative
+  threshold, short-circuits with `Disconnect("Excess Flood")` without
+  invoking the inner reducer — matching hybrid/charybdis/Unreal.
+- **Per-command flood cost**: each command carries an integer cost;
+  control-plane commands (`PING`/`PONG`/`QUIT`/`CAP`/`AUTHENTICATE`)
+  are exempt so registration and keepalive can never be starved.
+
+### Added — IRCv3 chat history (`@serverless-ircd/irc-core`)
+
+- **`draft/chathistory`**: pure reducer for `CHATHISTORY <sub> <target>
+  [<args>...]`. Reads backlog from the injected `MessageStore` port and
+  replays matching `PRIVMSG`/`NOTICE`/`TAGMSG` lines wrapped in a single
+  `BATCH chathistory <target>` frame, each carrying its original
+  `@time=…` (server-time) and `msgid=…` tags. The cap must be
+  negotiated before queries are accepted. Backed by a flood-wrapped
+  routed-reducer path so chat-history reads cannot bypass the bucket.
+
+### Added — Observability & configuration (`@serverless-ircd/irc-core`)
+
+- **Structured logger port**: a `Logger` port with `traceId` /
+  `connectionId` propagation, injected through `ctx` so reducers and
+  the actor layer emit structured JSON logs without ambient state.
+- **Shared `ServerConfigSchema`**: a single Zod-style schema validating
+  `serverName`, `networkName`, `motdLines`, `serverPassword`,
+  `cloaking`, `maxConnectionsPerIp`, `maxConnectionsPerUser`, and
+  `perIpConnectionRate` with the same defaults across every adapter.
+  Each adapter ships a thin loader (`loadServerConfigFromLambdaEnv`,
+  CF `vars`, local CLI flags) that reduces to the shared schema.
+
+### Added — Security hardening (`@serverless-ircd/irc-core`, `@serverless-ircd/in-memory-runtime`, `@serverless-ircd/local-cli`)
+
+- **Server password enforcement**: when `serverPassword` is set in
+  `ServerConfig`, connections must supply it via `PASS <password>`
+  (or authenticate via SASL PLAIN) before registration completes;
+  otherwise the server replies `464 ERR_PASSWDMISMATCH` and closes
+  the link.
+- **Hostmask cloaking**: `cloakHost(realHost, config, suffix)` replaces
+  the client's visible IP with a deterministic 64-bit FNV-1a hash
+  encoded as lowercase base32, using a deployment-wide secret. Enabled
+  via `cloaking: { enabled, secret, cloakedSuffix }` in `ServerConfig`.
+- **Connection admission gate**: `AdmissionStats` + `decideAdmission`
+  enforce three independent limits at connection-accept time, each with
+  a distinct rejection reason:
+  - Per-IP simultaneous-connection cap (`maxConnectionsPerIp`, default 10).
+  - Per-user simultaneous-connection cap (`maxConnectionsPerUser`,
+    default 5; falls back to source IP when no SASL identity is present).
+  - Per-IP connection-rate limit (sliding window
+    `perIpConnectionRate`, default 5 per 60 s).
+- **512-byte input cap**: the IRC line parser rejects any line whose
+  post-CRLF-strip length exceeds `MAX_INPUT_BYTES` (512), matching
+  RFC 2812 §2.3 and the existing output-side `enforceLineLimit`.
+
+### Added — AWS adapter (`@serverless-ircd/aws-adapter`, `@serverless-ircd/aws-stack`)
+
+The second serverless substrate lands, mirroring the Cloudflare adapter
+on the same `irc-core` reducers and `IrcRuntime` port. Cloudflare and
+AWS are now both deployable.
+
+- **`AwsRuntime`**: `IrcRuntime` implementation backed by DynamoDB +
+  `ApiGatewayManagementApi`. Marshal/unmarshal helpers map irc-core
+  state shapes to/from DynamoDB rows.
+- **Lambda handlers**: `$connect` / `$disconnect` / `$default` entry
+  point dispatched on `event.requestContext.routeKey`, wired through
+  `ConnectionActor` + `dispatch` against `AwsRuntime`.
+- **Gone-connection sweeper** (`sweeperHandler`): scheduled Lambda that
+  reaps connections whose WebSocket link is dead, using atomic DynamoDB
+  membership transactions so roster/part fanout stays consistent.
+- **Idle / PING checker** (`pingCheckerHandler`): scheduled Lambda that
+  drives the PING / no-PONG disconnect sweep, the AWS analogue of the
+  Cloudflare DO `alarm()`.
+- **CDK v2 stack** (`apps/aws-stack`): API Gateway v2 WebSocket API +
+  auto-deploying `prod` stage, one Node 20 `NodejsFunction` for the
+  runtime, one for the sweeper, and one for the PING checker, five
+  DynamoDB tables (`Connections`, `ChannelMeta`, `ChannelMembers`,
+  `Nicks`, `Accounts`), and least-privilege IAM (per-table data-plane
+  grants + `execute-api:ManageConnections` scoped to the stage).
+- **Per-environment isolation**: `environmentName` prop isolates
+  stacks (`IrcAwsStack-<env>`); configurable server identity
+  (name / network / MOTD).
+- **AWS deploy workflow** (`.github/workflows/deploy-aws.yml`):
+  serialized `cdk deploy --all` to staging on every push to `main`,
+  followed by the smoke e2e (`scripts/smoke.mjs`) against the deployed
+  `ConnectUrl`. Supports static keys or OIDC web-identity role
+  assumption.
+
+### Added — Shared test harness (`@serverless-ircd/irc-test-support`)
+
+- New workspace package owning the parametrized IRC scenario suite
+  (`runIrcScenarios`, 31 Phase 2 scenarios) and the
+  `IrcHarnessFactory` / `IrcHarness` / `ClientHarness` seam each
+  adapter implements. Ships the reference `inMemoryHarnessFactory`.
+  cf-adapter and aws-adapter integration tests both consume it, so the
+  same flows run against in-memory, Cloudflare, and AWS runtimes.
+
+### Added — CI / build
+
+- **Coverage gate**: vitest per-package `thresholds` now enforce 100%
+  line/function/branch/statement on `irc-core` / `irc-server` /
+  `in-memory-runtime` and ≥90% on every other package. The gate is a
+  dedicated named CI step; a regression blocks the merge.
+- **Mutation testing**: Stryker spot-checks on `irc-core/protocol` and
+  `irc-core/commands` (≥80% mutation score gate), running as a parallel
+  CI job. Repo-level `pnpm mutation` / `mutation:protocol` /
+  `mutation:commands` scripts drive it locally.
+- **`@serverless-ircd/ci-hardening`** tool: validates the coverage-gate
+  and mutation-testing configs exist and meet the documented
+  thresholds, catching drift (a lowered threshold or dropped Stryker
+  config) before it reaches `main`.
+- **CF observability**: Worker `observability.invocation_logs` enabled
+  for runtime visibility in the Cloudflare dashboard.
+- **tcp-ws-forwarder logging**: structured logger with configurable
+  log levels.
+
+### Changed
+
+- `CAP LS` now advertises `draft/chathistory`; `sasl` is negotiated
+  end-to-end rather than advertised-only.
+- The local CLI now binds a **second RFC-style TCP listener** by default
+  (`--tcp-port`, default `<port> + 1`) alongside the WebSocket listener,
+  so stock IRC clients can dial in directly without the forwarder.
+  Pass `--no-tcp` for WebSocket-only. `--motd-file` loads the MOTD from
+  disk.
+
+### Known limitations
+
+- **No config loader for oper credentials / max clients.** Server name,
+  network, MOTD, cloaking secret, and admission limits are configurable,
+  but oper credentials and dynamic max-client limits remain hardcoded
+  defaults.
+- **No TLS / raw TCP transport in production.** The local CLI exposes a
+  TCP listener for development; deployed stacks (CF + AWS) are
+  WebSocket text frames only. `irc+tls` is 0.x work.
+- **SASL `EXTERNAL` is reserved.** It is recognized but returns `904`
+  until mTLS lands.
+- **`chathistory` storage is adapter-supplied.** The `MessageStore` port
+  is implemented per adapter; clients that query backlog against a
+  runtime with no store configured will see an empty result.
+
+## [0.1.0] - 2026-07-21
+
+First tagged release. Establishes the pure-reducer protocol core, the
+runtime port + reference implementation, a runnable local CLI server,
+and a working Cloudflare Workers adapter deployed to staging.
+
+This is a **preview release**. The AWS adapter, SASL authentication,
+flood control, server-password enforcement, and a CI coverage gate
+are not yet implemented — see **Known limitations** below. The
+Cloudflare staging deployment is functional; production deploys are
+manual per `docs/release.md` §8.3.
+
+### Added — Protocol core (`@serverless-ircd/irc-core`)
+
+- Pure reducer architecture: every command handler is
+  `(state, msg, ctx) => { state, effects }`. Side effects are values
+  (`Effect[]`), interpreted by a separate `dispatch` step.
+- Discriminated `Effect` taxonomy (`Send`, `Broadcast`, `Disconnect`,
+  `ReserveNick`, `ChangeNick`, `ReleaseNick`, `ApplyChannelDelta`,
+  `Lookup`, …) covering every side effect referenced in PLAN §2.1.
+- Determinism ports `Clock` and `IdFactory` injected into `ctx` so
+  reducers never touch real timers or randomness.
+- RFC 1459 / 2812 command set: registration (`NICK` / `USER` / `PASS`),
+  `PING` / `PONG`, `QUIT`, `JOIN`, `PART`, `PRIVMSG`, `NOTICE`,
+  `TOPIC`, `NAMES`, `MOTD`, `MODE` (channel + user), `KICK`, `INVITE`,
+  `WHO`, `WHOIS`, `LIST`.
+- Channel modes: `o v b i k l t n m s p`. User modes: `i`, `o` (local
+  only), `w`, `s`.
+- Welcome numeric sequence `001`–`005` with `isupport` (`005`)
+  generator emitting `NETWORK=`, `CHANLIMIT=`, `CASEMAPPING=`,
+  `SAFELIST`, and the negotiated IRCv3 caps.
+- IRCv3 `CAP` negotiation: full `LS` / `REQ` / `ACK` / `NAK` / `END` /
+  `LIST` / `NEW` / `DEL` lifecycle.
+- IRCv3 extensions: `message-tags`, `server-time`, `echo-message`,
+  `multi-prefix`, `extended-join`, `chghost`, `away-notify`,
+  `invite-notify`, `batch`, and the `safelist` capability +
+  `SAFELIST` isupport token.
+
+### Added — Orchestration (`@serverless-ircd/irc-server`)
+
+- The `IrcRuntime` port: side-effect interface (transport + state IO)
+  that every adapter implements.
+- `dispatch(effects, runtime)` interpreter that walks an `Effect[]`
+  against a bound runtime, with ordering and dedup verified.
+- `ConnectionActor`: bytes → framed messages → reducer → dispatch.
+  Drives the full registration handshake, PING/PONG cadence, and
+  command dispatch.
+
+### Added — In-memory runtime (`@serverless-ircd/in-memory-runtime`)
+
+- Single-process reference implementation of `IrcRuntime` backed by
+  in-memory Maps. Used by integration tests and the local CLI server.
+
+### Added — Local CLI server (`@serverless-ircd/local-cli`)
+
+- Runnable WebSocket IRC server on `ws://127.0.0.1:6667/` (default),
+  built on the in-memory runtime. Speaks WebSocket text frames, one
+  IRC message per frame. `SIGINT` / `SIGTERM` perform graceful
+  shutdown. Manual-test harness and e2e fixture target.
+- CLI flags: `--port`, `--host`, `-h/--help`.
+
+### Added — Cloudflare adapter (`@serverless-ircd/cf-adapter`)
+
+- `ConnectionDO`: hibernatable WebSocket handler (one DO per
+  connection). Owns `ConnectionState`, drives `ConnectionActor`,
+  persists state across hibernation, drives the PING / no-PONG
+  disconnect sweep via `alarm()`.
+- `RegistryDO`: sharded nick-uniqueness authority. Shard assignment is
+  `fnv1a32(lowercased(nick)) mod N`, default fleet size 32. DO
+  single-threadedness makes the uniqueness invariant structural.
+- `ChannelDO`: per-lowercased-channel-name DO holding roster, modes,
+  topic, and fanout via `ConnectionDO` stubs.
+- `CfRuntime`: implements the `IrcRuntime` port against the three DO
+  classes.
+
+### Added — Cloudflare Worker (`@serverless-ircd/cf-worker`)
+
+- Worker edge entry point: WebSocket upgrade → allocates
+  `connectionId = crypto.randomUUID()` → routes to `ConnectionDO`.
+  Non-upgrade requests get a human-readable 200 health string.
+- `wrangler.toml` with default (production) + `[env.staging]`
+  environments, DO bindings, `[[migrations]]` block.
+- `scripts/smoke.mjs`: replay CONNECT → NICK/USER → JOIN → PRIVMSG →
+  QUIT and assert the server emits `001`, `376`, `353`, `366`, then
+  closes. Run by CI against staging, runnable locally against
+  `wrangler dev`.
+
+### Added — TCP ↔ WebSocket forwarder (`@serverless-ircd/tcp-ws-forwarder`)
+
+- Local bridge so stock TCP IRC clients (WeeChat, HexChat, irssi) can
+  reach the WebSocket-only server. Listens on a TCP port, opens one
+  WebSocket per connection, reassembles the TCP byte stream into one
+  message per WS frame outbound, normalizes inbound frames back to
+  canonical CRLF. Transport-agnostic — ships no
+  `@serverless-ircd/*` dependency.
+
+### Added — CI / build
+
+- GitHub Actions CI (`.github/workflows/ci.yml`): lint, typecheck,
+  test with coverage on every push / pull request to `main`.
+- GitHub Actions CF deploy (`.github/workflows/deploy-cf.yml`):
+  serialized staging deploy on every push to `main`, followed by the
+  smoke e2e against the deployed URL. Failure blocks the merge.
+- Toolchain: pnpm 9 workspaces, turbo, TypeScript (strict +
+  `exactOptionalPropertyTypes`), vitest + `@vitest/coverage-v8`,
+  fast-check, Biome.
+
+### Added — Documentation
+
+- `README.md` — architecture, repository layout, toolchain, local
+  server + forwarder usage, testing strategy, roadmap, protocol scope.
+- `docs/architecture-aws.md` — AWS adapter design notes (adapter
+  itself lands in a later release).
+- `docs/deployment-cf.md` — end-to-end Cloudflare deployment guide
+  (prerequisites, account setup, local dev, staging + production
+  deploys, config reference, sharding, cost, CI/CD, troubleshooting).
+- `docs/release.md` — this release process runbook.
+
+### Changed
+
+- None (this is the first tagged release).
+
+### ⚠️ Migration required
+
+- None. No prior releases to migrate from. The DO `[[migrations]]`
+  block in `wrangler.toml` is `tag = "v1"` and will provision cleanly
+  on a fresh account.
+
+### Known limitations
+
+- **No AWS adapter.** Tickets TICKET-039 through TICKET-044 (CDK
+  stack, APIGW WebSocket handlers, DynamoDB transactions, EventBridge
+  timers, deploy pipeline, deployment doc) are pending. Cloudflare is
+  the only deployable platform in 0.1.0.
+- **No SASL.** `CAP sasl` is advertised in the capability list but
+  `AUTHENTICATE` is not wired into the dispatcher. Plain-text password
+  authentication via `PASS` is also not enforced (TICKET-046).
+- **No flood control.** A token-bucket wrapper (TICKET-028) is
+  pending. Misbehaving clients can send unbounded commands.
+- **No server-password enforcement, rate limits, cloaking, or oper
+  credentials** (TICKET-046).
+- **No config loader.** Server name, network name, MOTD, channel
+  prefixes, max clients, oper creds are hardcoded defaults
+  (TICKET-047). The `MOTD.txt` file at the repo root is informational
+  only; the live MOTD is compiled into the Worker from
+  `[vars].MOTD_LINES`.
+- **No CI coverage gate.** Coverage is computed and uploaded as an
+  artifact, but no threshold is enforced (TICKET-048). Inspect
+  `packages/*/coverage/` before deploying.
+- **No TLS / raw TCP transport.** v1 is WebSocket text frames only.
+  TLS-hardened and `irc+tls` transports are 0.x work (TICKET-052
+  through TICKET-058). Stock TCP IRC clients reach the server through
+  the local `tcp-ws-forwarder` bridge.
+- **No `chathistory` playback.** TICKET-063 is pending; clients that
+  request backlog on JOIN will see an empty batch or no response.
+
+### Security
+
+- None. No vulnerabilities have been reported or fixed in this
+  release. Report security issues per the contributing guide.
+
+---
+
+<!-- Release template — copy for the next release, fill in, move above this line.
+
+## [Unreleased]
+
+### Added
+-
+
+### Changed
+-
+
+### ⚠️ Migration required
+-
+
+### Fixed
+-
+
+### Known limitations
+-
+
+### Security
+-
+
+-->

package/MOTD.txt

@@ -0,0 +1,3 @@
+Welcome to the test network for Serverless IRCd project.
+
+Join #general for chat.