serverless-ircd 0.2.0 → 0.4.0

package/PLAN-FIXES.md

@@ -1,358 +0,0 @@
-# PLAN-FIXES.md
-
-Audit of stubbed, incomplete, and not-fully-wired-up functionality in ServerlessIRCd.
-Each item lists location, current behavior, expected behavior, and impact.
-
-Findings are grouped by severity: **Critical** > **Partial** > **Minor / Dead scaffolding**.
-
----
-
-## Critical
-
-### 1. `MessageStore` (IRCv3 `draft/chathistory`) wired into no adapter
-
-`ConnectionActor` accepts `messages?: MessageStore` (`packages/irc-server/src/actor.ts:105`),
-and `irc-core` ships a complete `InMemoryMessageStore`, the `CHATHISTORY` reducer, and
-JOIN auto-playback. None of the three adapters pass it:
-
-- `packages/cf-adapter/src/connection-do.ts:303-312`
-- `packages/aws-adapter/src/handlers/default.ts:103-111`
-- `apps/local-cli/src/server.ts:480-501`
-
-**Impact:** chathistory recording and playback are dead code outside unit tests.
-`ctx.messages` is always `undefined` in any deployment.
-
-**Fix:** construct and pass a `MessageStore` instance at each actor-construction site.
-
----
-
-### 2. `AccountStore` (SASL) not accepted by the actor
-
-`ConnectionActorOptions` (`packages/irc-server/src/actor.ts:89-119`) has **no `accounts`**
-field, and `route()` -> `buildCtx()` (`actor.ts:238-245`) never supplies one, even though
-`buildCtx` supports it (`packages/irc-core/src/types.ts:143`).
-
-**Impact:** SASL PLAIN authentication can never succeed in any adapter. A client completing
-`AUTHENTICATE PLAIN` always receives `904 ERR_SASLFAIL` because `ctx.accounts` is `undefined`.
-Only unit tests (which call `buildCtx` directly) exercise the happy path.
-
-**Fix:** add `accounts?: AccountStore` to `ConnectionActorOptions`, forward it through
-`route()` into `buildCtx`, and supply an implementation in each adapter.
-
----
-
-### 3. Cloudflare runtime stubs (`packages/cf-adapter/src/cf-runtime.ts`)
-
-The AWS runtime fully implements all 16 `IrcRuntime` methods against DynamoDB. The CF
-runtime has explicit stubs that break three commands for anything beyond the local connection.
-
-| Method | Line | Stub | Impact |
-|---|---|---|---|
-| `getConnection()` | cf-runtime.ts:234-244 | returns `null` for remote conns | Remote WHOIS broken (only `401` + `318`) |
-| `getChannelConnections()` | cf-runtime.ts:246-251 | returns empty `Map` | WHO broken on CF |
-| `listChannels()` | cf-runtime.ts:253-258 | returns `[]` | LIST returns no channels on CF |
-| `disconnect()` | cf-runtime.ts:115-126 | cross-connection disconnect is a no-op | KICK of a remote user does not close their socket |
-
-**Fix:** add the missing ConnectionDO RPCs (`getConnState`, channel-membership enumeration,
-channel registry) and a cross-connection `disconnect` RPC; wire `cf-runtime.ts` to call them.
-
----
-
-### 4. AWS disconnect never broadcasts QUIT to peers
-
-`packages/aws-adapter/src/aws-runtime.ts:645` -- `cleanupConnection` explicitly discards
-`managementApi` (`void managementApi;`) and never broadcasts QUIT. Confirmed at the call
-site: `packages/aws-adapter/src/handlers/disconnect.ts:28` hardcodes `null`.
-
-**Impact:** when a connection tears down, peers in shared channels never receive the QUIT
-fanout. Their local rosters go stale until a subsequent broadcast prunes the ghost member.
-
-**Fix:** thread the `managementApi` through `handleDisconnect` and implement QUIT fanout
-to all connections sharing channels with the disconnecting client.
-
----
-
-### 5. AWS `Accounts` DynamoDB table deployed with no runtime consumer
-
-Provisioned in CDK (`packages/aws-adapter/src/cdk-table-defs.ts:61-65`) and required by
-`tablesConfigFromNames`, but no runtime code reads or writes it. No `AccountStore`
-implementation is backed by it.
-
-**Impact:** paid-for infrastructure with no consumer; also blocks SASL account persistence
-(see #2).
-
-**Fix:** either implement a DynamoDB-backed `AccountStore` against this table, or remove
-the table from the CDK stack and config loader until it is needed.
-
----
-
-## Absent IRC commands (scaffolded or advertised, no handler)
-
-Implemented reducers (JOIN/PART/TOPIC/NAMES/KICK/INVITE/MOTD/PRIVMSG/NOTICE/MODE/LIST/
-WHO/WHOIS/CAP/AUTHENTICATE/AWAY/CHATHISTORY) are genuinely complete. The gaps below either
-fall through to `421 ERR_UNKNOWNCOMMAND` or have partial scaffolding.
-
-### 6. `OPER` -- absent, but heavily scaffolded
-
-No `OPER` case in `actor.ts` `route()` switch, no reducer, no entry in
-`packages/irc-core/src/commands/index.ts`. Referenced everywhere:
-
-- `packages/irc-core/src/commands/mode.ts:15` -- "The oper flag (`+o`) is granted via the
-  future OPER command, not via MODE"
-- `packages/irc-core/src/commands/mode.ts:547,612-624` -- user `MODE +o` hard-rejected
-  with `481 ERR_NOPRIVILEGES`, gated on an OPER command that does not exist.
-- `operCreds` is defined, validated, and loaded by **all three adapters**
-  (`packages/cf-adapter/src/config-loader.ts:65`,
-  `packages/aws-adapter/src/config-loader.ts:59`,
-  `apps/local-cli/src/config-loader.ts:27`) but no runtime code ever reads
-  `serverConfig.operCreds`.
-- Reserved-but-unused numerics: `RPL_YOUREOPER: 381`, `RPL_REHASHING: 382`,
-  `ERR_NOOPERHOST: 491` (`packages/irc-core/src/numerics.ts:75-76,138`).
-
-**Impact:** `state.userModes.oper` can never become `true` via any command flow, so the
-`RPL_WHOISOPERATOR` (`313`) branch in `packages/irc-core/src/commands/whois.ts:132-136`
-and the WHO `*` oper flag (`packages/irc-core/src/commands/who.ts:69`) are unreachable.
-
-**Fix:** implement the `OPER` reducer (verify credentials against `operCreds`, set the
-`oper` user mode, emit `381`), add it to the route switch, and wire the dependent
-WHOIS/WHO branches.
-
----
-
-### 7. `TAGMSG` -- replay path exists, no recorder
-
-`StoredCommand = 'PRIVMSG' | 'NOTICE' | 'TAGMSG'` (`packages/irc-core/src/ports.ts:200`)
-and `packages/irc-core/src/commands/chathistory.ts:237-238` contain real replay code for
-a stored TAGMSG. But nothing ever records one: the only call to `ctx.messages.record(...)`
-is `packages/irc-core/src/commands/privmsg.ts:188`, which records `PRIVMSG`/`NOTICE` only.
-
-**Impact:** the `message-tags` cap is advertised (`packages/irc-core/src/caps/capabilities.ts:33`)
-with no command that consumes it. The TAGMSG replay branch is dead code.
-
-**Fix:** add a `TAGMSG` reducer + route case that records the message-tag set via
-`ctx.messages.record({ command: 'TAGMSG', ... })`.
-
----
-
-### 8. `WHOWAS` -- numerics present, no handler
-
-`RPL_ENDOFWHOWAS: 369`, `ERR_WASNOSUCHNICK: 406` defined
-(`packages/irc-core/src/numerics.ts:65,97`); no reducer, no route case.
-
-**Fix:** implement a `WHOWAS` reducer against the nick history (or decide to drop the
-numerics if the feature is not planned).
-
----
-
-### 9. Other unimplemented standard verbs
-
-Currently return `421 ERR_UNKNOWNCOMMAND` via `actor.ts:318-319` (graceful, not broken):
-
-`VERSION`, `ADMIN`, `INFO`, `TIME`, `STATS`, `LUSERS`, `LINKS`, `USERHOST`, `ISON`,
-`WALLOPS`, `SETNAME`, `KILL`, `REHASH`, `CONNECT`, `TRACE`, `SQUIT`, `SERVICE`,
-`SUMMON`, `USERS`.
-
-Several have dedicated numerics defined but unused (`RPL_USERHOST: 302`, `RPL_ISON: 303`,
-`RPL_INFO: 371`, `RPL_LINKS: 364`, `RPL_TIME: 391`, `RPL_ADMINME: 256`).
-
-**Fix:** implement the subset that matters for client compatibility, or remove unused
-numerics to avoid advertising false capability.
-
----
-
-## Partial
-
-### 10. SASL `EXTERNAL` -- hardcoded to fail
-
-`packages/irc-core/src/commands/sasl.ts:95-97` recognizes `AUTHENTICATE EXTERNAL` but
-unconditionally returns `904 ERR_SASLFAIL`. The `sasl` cap advertises `PLAIN,EXTERNAL`
-(`packages/irc-core/src/caps/capabilities.ts:36`,
-`packages/irc-core/src/commands/sasl.ts:42` `SUPPORTED_MECHS = 'PLAIN,EXTERNAL'`).
-
-**Impact:** EXTERNAL is advertised but non-functional. (PLAIN is fully implemented but
-see #2.)
-
-**Fix:** either implement EXTERNAL (mTLS client-cert extraction), or stop advertising it
-in `SUPPORTED_MECHS` until it lands.
-
----
-
-### 11. Welcome MOTD is a hardcoded placeholder
-
-`packages/irc-core/src/commands/registration.ts:84-87` always emits:
-
-```
-375 <nick> :- <server> Message of the day -
-372 <nick> :- MOTD placeholder
-376 <nick> :End of MOTD command
-```
-
-regardless of the configured `MotdProvider`. The comment claims "filled via MotdProvider
-elsewhere" but it is not. The standalone `MOTD` command correctly uses `ctx.motd.lines()`
-(`packages/irc-core/src/commands/motd.ts:59`).
-
-**Impact:** every client sees `372 <nick> :- MOTD placeholder` on connect regardless of
-configuration.
-
-**Fix:** call `ctx.motd.lines()` in `buildWelcomeLines` and emit the real lines.
-
----
-
-### 12. Placeholder constants in registration
-
-`packages/irc-core/src/commands/registration.ts:29,32`:
-
-- `SERVER_VERSION = '0.1.0'` -- "Placeholder until a config-driven version lands"
-- `CREATED_TEXT = 'Phase 1'` -- "Placeholder"
-
-Surfaced verbatim in `002`/`003`/`004` replies.
-
-**Fix:** drive these from `ServerConfig` (read `package.json` version at build time, or
-add `serverVersion`/`createdAt` config fields).
-
----
-
-### 13. `DEFAULT_SERVER_CONFIG` ships a placeholder server name
-
-`packages/irc-core/src/config.ts:244-247` -- `serverName: 'irc.example.com'` as the
-baseline. Documented as a boot/test baseline that adapters overlay, and
-`docs/AWS-Deployment.md:414` warns "(placeholder -- override!)".
-
-**Impact:** if a deployment forgets to override, the server advertises `irc.example.com`.
-
-**Fix:** require `serverName` at adapter config-load time (fail fast if unset) rather
-than relying on a placeholder default.
-
----
-
-### 14. AWS `handleConnect` ignores `serverConfig`
-
-`packages/aws-adapter/src/handlers/connect.ts:36` -- `void params.serverConfig;`
-("reserved for max-clients gating").
-
-**Impact:** connection-count admission gating at connect time is unimplemented.
-
-**Fix:** implement max-clients admission using the supplied config.
-
----
-
-### 15. AWS Lambda transport `disconnect` is a no-op
-
-`packages/aws-adapter/src/handlers/default.ts:86-89` -- `AwsRuntimeHandlers.disconnect`
-does nothing. Documented as a platform limit (a Lambda cannot close its own APIGW socket;
-the canonical close is the `$disconnect` route).
-
-**Impact:** effect-driven `Disconnect` on the bound connection never reaches the transport
-from within a `$default` invocation.
-
-**Fix:** documented platform limitation; no code fix possible without an APIGW feature.
-Consider noting this in operator docs.
-
----
-
-### 16. CF `webSocketMessage` newly-joined-channel registration is a no-op
-
-`packages/cf-adapter/src/connection-do.ts:150-156` -- the loop body is `void chan;`.
-
-**Impact:** no real channel-registration work happens on join beyond the
-`ApplyChannelDelta` already emitted by the reducer.
-
-**Fix:** wire channel-DO registration here, or remove the dead loop.
-
----
-
-## Minor / Dead scaffolding
-
-### 17. Three lookup Effect variants are dead
-
-`LookupNick`, `GetConnectionInfo`, `GetChannelSnapshot` are defined in
-`packages/irc-core/src/effects.ts:74-87` and `:170-178` (and included in the `Effect`
-union at `:112-114`), but their dispatch results are discarded via `noop`
-(`packages/irc-server/src/dispatch.ts:36-38`) and no reducer ever emits them. The
-runtime methods they wrap (`lookupNick`/`getConnectionInfo`/`getChannelSnapshot`) are
-used elsewhere, so only the Effect path is dead.
-
-**Fix:** either wire these effects to real consumers, or remove the variants and their
-dispatch arms.
-
----
-
-### 18. CF outbound batching optimization reserved/disabled
-
-`packages/cf-adapter/src/connection-do.ts:100-101` -- a field for batching outbound line
-drains is commented out, explicitly deferred.
-
-**Fix:** implement the batching optimization, or drop the reserved comment.
-
----
-
-### 19. Stale doc-comments advertise DOs as stubbed
-
-`packages/cf-adapter/src/env.ts:23-36` -- still describes `REGISTRY_DO` as
-"Stubbed now (033); real impl in 034" and `CHANNEL_DO` as "Stubbed now; real in 035",
-even though `registry-do.ts` and `channel-do.ts` now contain real implementations.
-
-`packages/cf-adapter/src/connection-do.ts:148-153, 291-293, 337-338, 504-506, 549` contain
-similar stale "stub" language; `:546-549` exports `applyChannelDelta` purely to keep an
-import used by tests.
-
-**Fix:** update comments to reflect the implemented state; drop the test-only re-export
-or move it behind a test boundary.
-
----
-
-### 20. Case-mapping mismatch vs. advertised ISUPPORT
-
-`packages/irc-core/src/isupport.ts:43` advertises `CASEMAPPING=rfc1459`, but
-`packages/irc-core/src/commands/kick.ts:57-60` (and the duplicated `lowerNick`/`lower`
-helpers in `mode.ts`, `invite.ts`, `join.ts`, `packages/in-memory-runtime/src/in-memory-runtime.ts`)
-use bare ASCII `toLowerCase()`. The advertised case-mapping and the actual folding diverge
-for the `[]\^` special chars.
-
-**Fix:** implement rfc1459 case folding in a single shared helper and use it everywhere.
-
----
-
-### 21. `_disabledRecordId()` generates IDs never consulted
-
-`packages/in-memory-runtime/src/in-memory-runtime.ts:61-69` -- mints admission record ids
-whose own doc comment states "The id is never consulted (no `AdmissionStats` exists)."
-Called at `:116` when admission is disabled; the returned `recordId` flows nowhere.
-
-**Fix:** remove the helper and its call site, or implement the `AdmissionStats` consumer.
-
----
-
-### 22. Stale CLI doc comment
-
-`apps/local-cli/src/main.ts:17` -- "a fuller config-loader lands in a later ticket."
-`apps/local-cli/src/config-loader.ts` already exists and fully validates via
-`ServerConfigSchema`.
-
-**Fix:** update the comment.
-
----
-
-### 23. Stale release-process doc
-
-`docs/Release-Process.md:114` -- "the 90% coverage gate (TICKET-048) is not yet wired in CI."
-`.github/workflows/ci.yml:57-60` shows the gate **is** wired and enforced per package
-(100% on irc-core/irc-server/in-memory-runtime, >=90% elsewhere).
-
-**Fix:** update the doc to reflect the enforced gate.
-
----
-
-## Summary
-
-| Severity | Count | Items |
-|---|---|---|
-| Critical | 5 | #1 MessageStore unwired; #2 AccountStore unwired; #3 CF runtime stubs; #4 AWS no QUIT fanout; #5 AWS Accounts table unused |
-| Absent commands | 4 | #6 OPER; #7 TAGMSG; #8 WHOWAS; #9 misc standard verbs |
-| Partial | 7 | #10 SASL EXTERNAL; #11 Welcome MOTD; #12 Version/Created placeholders; #13 DEFAULT_SERVER_CONFIG; #14 AWS connect ignores config; #15 AWS Lambda disconnect; #16 CF channel-register no-op |
-| Minor / Dead scaffolding | 7 | #17 dead lookup Effects; #18 CF batching reserved; #19 stale DO doc-comments; #20 case-mapping mismatch; #21 unused recordId; #22 stale CLI comment; #23 stale release doc |
-
-**Bottom line:** Implemented command reducers are solid. The real gaps are (1) two whole
-feature ports (`MessageStore`, `AccountStore`) shipped with no adapter wiring, (2) the CF
-runtime's four stubbed methods that break WHO/WHOIS/LIST/remote-disconnect, (3) AWS never
-broadcasts QUIT on disconnect, and (4) `OPER` is the largest scaffolded-but-absent command.