serverless-ircd 0.5.0 → 0.6.0

package/packages/irc-core/src/commands/away.ts

@@ -27,6 +27,7 @@ import type { ChanName } from '../state/channel.js';
 import { hostmaskOf } from '../state/connection.js';
 import type { ConnectionState } from '../state/connection.js';
 import type { Reducer } from '../types.js';
+import { clearPersistedAway, persistAway } from './pre-away.js';
 
 /**
  * Handles `AWAY [:<reason>]`.
@@ -45,7 +46,10 @@ export const awayReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
   const nick = state.nick ?? '*';
 
   if (isSettingAway) {
-    state.away = reason;
+    // IRCv3 draft/pre-away: persist the reason keyed by account when an
+    // AwayStore is bound and the connection is identified. The in-memory
+    // away is also set so the current session tracks the new reason.
+    persistAway(ctx, reason as string);
     effects.push(
       Effect.send(ctx.connId, [
         {
@@ -54,8 +58,10 @@ export const awayReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
       ]),
     );
   } else {
-    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
-    delete state.away;
+    // IRCv3 draft/pre-away: clear the persisted reason on unset so a
+    // reconnect does not re-mark the user away. The in-memory away is
+    // also cleared so the session's view stays consistent.
+    clearPersistedAway(ctx);
     effects.push(
       Effect.send(ctx.connId, [
         {

package/packages/irc-core/src/commands/cap.ts

@@ -33,13 +33,17 @@
  */
 
 import {
+  DEFAULT_MULTILINE_MAX_BYTES,
+  MULTILINE_CAP_NAME,
   SASL_CAP_NAME,
   SUPPORTED_CAPABILITIES,
   capToLsString,
   isSupportedCap,
+  multilineCapValue,
   saslCapValue,
   splitCapsForWire,
 } from '../caps/capabilities.js';
+import { STS_CAP_NAME, stsCapValue } from '../caps/sts.js';
 import { Effect } from '../effects.js';
 import type { RawLine } from '../effects.js';
 import { Numerics } from '../protocol/numerics.js';
@@ -91,11 +95,21 @@ function handleLs(state: ConnectionState, ctx: Ctx): ReducerResult<ConnectionSta
 
   const target = state.nick ?? '*';
   const hasMtls = ctx.mtlsIdentity !== undefined;
-  const tokens = SUPPORTED_CAPABILITIES.map((cap) =>
-    cap.name === SASL_CAP_NAME
-      ? capToLsString({ ...cap, value: saslCapValue(hasMtls) })
-      : capToLsString(cap),
-  );
+  const multilineMax = ctx.serverConfig.multilineMaxBytes ?? DEFAULT_MULTILINE_MAX_BYTES;
+  const tokens = SUPPORTED_CAPABILITIES.map((cap) => {
+    if (cap.name === SASL_CAP_NAME) {
+      return capToLsString({ ...cap, value: saslCapValue(hasMtls) });
+    }
+    if (cap.name === MULTILINE_CAP_NAME) {
+      return capToLsString({ ...cap, value: multilineCapValue(multilineMax) });
+    }
+    return capToLsString(cap);
+  });
+  // STS is conditionally advertised: appended only when the deployment
+  // supplies a policy, and the value is per-transport (plaintext sees the
+  // full `duration,port[,preload]`; TLS sees only `duration`).
+  const stsValue = stsCapValue(ctx.serverConfig.sts, ctx.connection.secure);
+  if (stsValue !== undefined) tokens.push(`${STS_CAP_NAME}=${stsValue}`);
   const maxLen = maxCapsContentLen(ctx, target);
   const chunks = splitCapsForWire(tokens, maxLen);
 
@@ -164,8 +178,12 @@ function handleReq(
   const requested = rawCaps.split(' ').filter((c) => c.length > 0);
   const target = state.nick ?? '*';
 
+  // STS is conditionally supported: ACKed only when the deployment supplies
+  // a policy. Other caps consult the static table.
+  const stsConfigured = ctx.serverConfig.sts !== undefined;
   const allSupported = requested.every((tok) => {
     const name = tok.startsWith('-') ? tok.slice(1) : tok;
+    if (name === STS_CAP_NAME) return stsConfigured;
     return isSupportedCap(name);
   });
 

package/packages/irc-core/src/commands/chathistory.ts

@@ -141,7 +141,17 @@ function handleChannelSub(
   // LATEST / BEFORE / AFTER / AROUND
   const pivot = msg.params[2];
   const limitRaw = msg.params[3];
-  if (sub !== 'LATEST' && pivot === undefined) {
+
+  // IRCv3 draft/read-marker integration: BEFORE without an explicit pivot
+  // falls back to the connection's per-channel last-read marker so a client
+  // can resume "everything before my last read position" without re-supplying
+  // the msgid. AFTER/AROUND still require an explicit pivot.
+  const markerPivot =
+    sub === 'BEFORE' && pivot === undefined
+      ? ctx.connection.lastReadMarkers?.get(chanLower)
+      : undefined;
+
+  if (sub !== 'LATEST' && pivot === undefined && markerPivot === undefined) {
     return { effects: [Effect.send(ctx.connId, [needMoreParamsLine(ctx)])] };
   }
   const limit = parseLimit(limitRaw);
@@ -163,12 +173,13 @@ function handleChannelSub(
     return { effects: buildChathistoryBatch(ctx, channel.name, result) };
   }
 
-  // BEFORE / AFTER / AROUND — pivot is required. The `sub !== 'LATEST' &&
-  // pivot === undefined` guard above already rejected the missing-pivot
-  // case and LATEST returned early just above; assert non-null for the
-  // type-checker without an unreachable branch.
-  const pivotMsgid = pivot as string;
-  if (!storeHas(ctx, chanLower, pivotMsgid)) {
+  // BEFORE / AFTER / AROUND — pivot is required. Resolve from the explicit
+  // msgid when supplied, otherwise from the marker fallback computed above.
+  // The guard near the top already guaranteed at least one is defined.
+  const pivotMsgid = (pivot ?? markerPivot) as string;
+  // An explicit pivot must reference a retained message; a marker fallback
+  // may point at an evicted message (→ empty result, not INVALID_PARAMS).
+  if (pivot !== undefined && !storeHas(ctx, chanLower, pivotMsgid)) {
     return { effects: [Effect.send(ctx.connId, [invalidParamsLine(ctx)])] };
   }
   const result = storeQuery(ctx, {
@@ -228,16 +239,34 @@ export function buildChathistoryBatch(
 /**
  * Reconstructs the wire line for one stored message, decorated with the
  * original server-time and msgid tags. PRIVMSG/NOTICE carry the trailing
- * text; TAGMSG has no trailing parameter.
+ * text; TAGMSG has no trailing parameter. Optional `clientTags` recorded
+ * with the message (e.g. `+draft/multiline`) are appended to the tag
+ * section so chathistory clients can recognise the message kind.
  */
 export function formatReplayLine(m: StoredMessage, displayChan: string): RawLine {
   const stamp = formatServerTime(m.time);
   const prefix = storedHostmask(m);
-  const tag = `@time=${stamp};msgid=${m.msgid}`;
+  const tags = buildReplayTags(stamp, m.msgid, m.clientTags);
   if (m.command === 'TAGMSG') {
-    return { text: `${tag} :${prefix} TAGMSG ${displayChan}` };
+    return { text: `${tags} :${prefix} TAGMSG ${displayChan}` };
+  }
+  return { text: `${tags} :${prefix} ${m.command} ${displayChan} :${m.text}` };
+}
+
+/**
+ * Builds the `@time=…;msgid=…[;+client-tag…]` tag section for a replay line.
+ * Client tags (when present) are appended after the server tags, matching the
+ * IRCv3 message-tags wire order.
+ */
+function buildReplayTags(
+  stamp: string,
+  msgid: string,
+  clientTags: readonly string[] | undefined,
+): string {
+  if (clientTags === undefined || clientTags.length === 0) {
+    return `@time=${stamp};msgid=${msgid}`;
   }
-  return { text: `${tag} :${prefix} ${m.command} ${displayChan} :${m.text}` };
+  return `@time=${stamp};msgid=${msgid};${clientTags.join(';')}`;
 }
 
 /** Builds the `nick!user@host` source for a stored message. */

package/packages/irc-core/src/commands/index.ts

@@ -46,6 +46,8 @@ export { generateIsupport } from './isupport.js';
 export { capReducer } from './cap.js';
 export { emitChghost } from './chghost.js';
 export type { ChgHostInput } from './chghost.js';
+export { emitAccountNotify } from './account-notify.js';
+export type { AccountNotifyInput } from './account-notify.js';
 export { awayReducer } from './away.js';
 export { setnameReducer } from './setname.js';
 export { authenticateReducer } from './sasl.js';
@@ -56,6 +58,18 @@ export {
   CHATHISTORY_CAP,
 } from './chathistory.js';
 export { tagmsgChannelReducer, tagmsgUserReducer } from './tagmsg.js';
+export {
+  DEFAULT_MULTILINE_MAX_BYTES,
+  MULTILINE_CAP,
+  type FinalizeMultilineResult,
+  type MultilineEntry,
+  type MultilineFanout,
+  buildMultilineFanout,
+  finalizeMultilineBatch,
+  joinMultiline,
+  multilineByteLength,
+  recordMultilineMessage,
+} from './multiline.js';
 export {
   versionReducer,
   timeReducer,
@@ -64,3 +78,23 @@ export {
 } from './server-info.js';
 export { userhostReducer, formatUserhostReply } from './userhost.js';
 export { isonReducer } from './ison.js';
+export {
+  monitorReducer,
+  MONITOR_CAP,
+  DEFAULT_MONITOR_LIMIT,
+} from './monitor.js';
+export {
+  READ_MARKER_CAP,
+  READ_MARKER_TAG,
+  isReadMarkerTagmsg,
+  persistReadMarker,
+  readMarkerMsgid,
+  seedReadMarkers,
+} from './read-marker.js';
+export {
+  PRE_AWAY_CAP,
+  clearPersistedAway,
+  nowAwayLine,
+  persistAway,
+  replayPersistedAway,
+} from './pre-away.js';

package/packages/irc-core/src/commands/isupport.ts

@@ -15,8 +15,10 @@
  * per-deployment (PLAN §10 capacity planning).
  */
 
+import { DEFAULT_MULTILINE_MAX_BYTES } from '../caps/capabilities.js';
 import type { RawLine } from '../effects.js';
 import type { ServerConfig } from '../types.js';
+import { DEFAULT_MONITOR_LIMIT } from './monitor.js';
 
 /** Max bytes per IRC wire line, including trailing `\r\n`. */
 const LINE_MAX_BYTES = 510;
@@ -36,6 +38,32 @@ const CHANMODES = {
 /** Channel-user prefix sigils, in PREFIX order (highest rank first). */
 const PREFIX = '(ov)@+';
 
+/**
+ * STATUSMSG delivery prefixes — the channel-user sigils a sender may prefix
+ * a target with (`@#channel` / `+#channel`) so only that rank and above
+ * receive the message. Mirrors the PREFIX sigil tail.
+ */
+const STATUSMSG_PREFIXES = '@+';
+
+/**
+ * Default extended-ban prefix when {@link ServerConfig.extbanPrefix} is
+ * unset. `~` is the de-facto IRC standard (matches nearly every daemon).
+ */
+const DEFAULT_EXTBAN_PREFIX = '~';
+
+/**
+ * Extended-ban types this server understands independent of services.
+ * `q` = quiet ban (prevents matching targets from speaking).
+ */
+const EXTBAN_TYPES = 'q';
+
+/**
+ * Account-name extended-ban type, advertised as a dedicated `ACCOUNTEXTBAN=a`
+ * token only when services are enabled, since account bans require registered
+ * nicks to be meaningful.
+ */
+const ACCOUNTEXTBAN_TYPE = 'a';
+
 /** Channel name sigils this server recognises. */
 const CHANTYPES = '#';
 
@@ -56,6 +84,9 @@ const TRAILER = 'are supported by this server';
  * can diff between servers. Tokens are space-separated, never empty.
  */
 function buildTokens(cfg: ServerConfig): string[] {
+  const monitorLimit = cfg.monitorLimit ?? DEFAULT_MONITOR_LIMIT;
+  const extbanPrefix = cfg.extbanPrefix ?? DEFAULT_EXTBAN_PREFIX;
+  const multilineMax = cfg.multilineMaxBytes ?? DEFAULT_MULTILINE_MAX_BYTES;
   return [
     `CHANTYPES=${CHANTYPES}`,
     `CHANMODES=${CHANMODES.list},${CHANMODES.paramSet},${CHANMODES.paramAlways},${CHANMODES.boolean}`,
@@ -73,6 +104,28 @@ function buildTokens(cfg: ServerConfig): string[] {
     // per-connection opt-in). LIST is always non-destructive here so the
     // token is unconditional.
     'SAFELIST',
+    // IRCv3 MONITOR cap ceiling. The value matches the per-connection
+    // watchlist size enforced by the monitor reducer; deployments lower it
+    // via `serverConfig.monitorLimit`.
+    `MONITOR=${monitorLimit}`,
+    // STATUSMSG — prefixes a sender may target (`@#chan`/`+#chan`) for
+    // rank-scoped delivery. The sigil set mirrors PREFIX.
+    `STATUSMSG=${STATUSMSG_PREFIXES}`,
+    // EXTBAN — extended-ban prefix and the base type list (`q` = quiet).
+    // The prefix is config-derived. The account-name extban is advertised
+    // as a separate `ACCOUNTEXTBAN=a` token (below) when services ship.
+    `EXTBAN=${extbanPrefix},${EXTBAN_TYPES}`,
+    // draft/typing advertisement — the cap is always supported, so the
+    // token is unconditional. (Draft caps have no RFC ISUPPORT token; this
+    // is the local marker clients can key on.)
+    'TYPING',
+    // draft/multiline byte budget — mirrors the `draft/multiline=<n>` cap
+    // value so the ceiling is visible pre-cap-negotiation.
+    `MULTILINE=${multilineMax}`,
+    // ACCOUNTEXTBAN — account-name extended ban. Meaningful only once
+    // services register nicks, so suppressed until a deployment wires
+    // services up via `serverConfig.servicesEnabled`.
+    ...(cfg.servicesEnabled ? [`ACCOUNTEXTBAN=${ACCOUNTEXTBAN_TYPE}`] : []),
   ];
 }
 

package/packages/irc-core/src/commands/mode.ts

@@ -528,7 +528,7 @@ const USER_MODE_LETTERS: Readonly<Record<string, keyof ConnectionState['userMode
 };
 
 /** User-mode letters in canonical 221 output order. */
-const USER_MODE_LETTER_ORDER = ['i', 'w', 's', 'o'] as const;
+const USER_MODE_LETTER_ORDER = ['i', 'w', 's', 'o', 'S'] as const;
 
 /**
  * Handles `MODE <nick> [<modestring>]`.
@@ -640,6 +640,13 @@ export const userModeReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
 function buildUserModeString(state: ConnectionState): string {
   let modeStr = '+';
   for (const letter of USER_MODE_LETTER_ORDER) {
+    // `S` (TLS connected) is read-only: it is not in USER_MODE_LETTERS
+    // (the write-side map the parser consults) so `MODE nick +S` rejects
+    // with 501. Surface it on the read side directly from its field.
+    if (letter === 'S') {
+      if (state.userModes.tls) modeStr += 'S';
+      continue;
+    }
     const field = USER_MODE_LETTERS[letter];
     if (field !== undefined && state.userModes[field]) modeStr += letter;
   }

package/packages/irc-core/src/commands/monitor.ts

@@ -0,0 +1,327 @@
+/**
+ * Pure reducer for the IRCv3 `MONITOR` command.
+ *
+ * IRCv3 MONITOR spec <https://ircv3.net/specs/extensions/monitor-3.2.html>:
+ *
+ *   - `MONITOR + <nick>{,<nick>}` — add targets to the watchlist.
+ *   - `MONITOR - <nick>{,<nick>}` — remove targets from the watchlist.
+ *   - `MONITOR C`                 — clear the watchlist.
+ *   - `MONITOR L`                 — list the watchlist (`732` per line +
+ *                                   `733` terminator).
+ *   - `MONITOR S`                 — status: `730 RPL_MONONLINE` for the
+ *                                   online subset, `731 RPL_MONOFFLINE`
+ *                                   for the rest.
+ *
+ * Numerics:
+ *   - `730 RPL_MONONLINE`    `:<server> 730 <nick> :<online>{,<online>}`
+ *   - `731 RPL_MONOFFLINE`   `:<server> 731 <nick> :<offline>{,<offline>}`
+ *   - `732 RPL_MONLIST`      `:<server> 732 <nick> :<entry>`
+ *   - `733 RPL_ENDOFMONLIST` `:<server> 733 <nick> :End of MONITOR list`
+ *   - `734 ERR_MONLISTFULL`  `:<server> 734 <nick> <limit> :<rejected>{,<rejected>}`
+ *
+ * The watchlist lives on {@link ConnectionState.monitorList} (folded nicks,
+ * case-insensitive membership). The reducer resolves each requested nick
+ * against the supplied `online` map (folded-keyed → display spelling); the
+ * actor builds that map from the nick registry before invoking the reducer,
+ * mirroring the {@link isonReducer} pattern.
+ *
+ * Asynchronous `730`/`731` pushes on online/offline transitions are emitted
+ * by the actor layer (it watches `ReserveNick` / `ReleaseNick` effects
+ * against the watchlists); the pure reducer only handles the request/reply
+ * subcommands above.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, ReducerResult } from '../types.js';
+
+/** Wire name of the IRCv3 MONITOR capability. */
+export const MONITOR_CAP = 'monitor';
+
+/** Default monitor cap (max watchlist size) advertised via `MONITOR=<n>`. */
+export const DEFAULT_MONITOR_LIMIT = 30;
+
+/**
+ * Handles the IRCv3 `MONITOR` subcommands.
+ *
+ * Signature is bespoke (not {@link Reducer}) because the actor must resolve
+ * the requested nicks asynchronously before formatting — mirrors
+ * {@link isonReducer} / {@link whoisReducer}.
+ *
+ * @param online       Folded-keyed → display-spelling map of currently
+ *                     online nicks (built by the actor from the nick
+ *                     registry).
+ * @param maxMonitor   Server-wide cap on the per-connection watchlist size
+ *                     (advertised via `MONITOR=<n>` in `005`).
+ * @param msg          Parsed `MONITOR <sub> [<args>]` message.
+ * @param ctx          Per-invocation context.
+ */
+export function monitorReducer(
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  msg: { params: readonly string[] },
+  ctx: Ctx,
+): ReducerResult<ConnectionState> {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const state = ctx.connection;
+  const nick = state.nick ?? '*';
+  const serverName = ctx.serverName;
+
+  const sub = (msg.params[0] ?? '').toUpperCase();
+
+  // No subcommand at all → 461 NEEDMOREPARAMS (the parser hands us an
+  // empty string when the sender wrote bare `MONITOR`). A non-empty but
+  // unknown subcommand (e.g. `MONITOR Z`) is also 461 with a different
+  // trailing string per the IRCv3 MONITOR dispatch table.
+  if (sub.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  switch (sub) {
+    case '+':
+      return handleAdd(state, online, maxMonitor, msg.params[1] ?? '', nick, serverName);
+    case '-':
+      return handleRemove(state, msg.params[1] ?? '');
+    case 'C':
+      return handleClear(state);
+    case 'L':
+      return handleList(state, nick, serverName);
+    case 'S':
+      return handleStatus(state, online, nick, serverName);
+    default:
+      return {
+        state,
+        effects: [
+          Effect.send(ctx.connId, [
+            numericLine(
+              serverName,
+              Numerics.ERR_NEEDMOREPARAMS,
+              nick,
+              'MONITOR',
+              'Unknown command',
+            ),
+          ]),
+        ],
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+function handleAdd(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  maxMonitor: number,
+  targetList: string,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (targetList.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(state.id, [
+          numericLine(
+            serverName,
+            Numerics.ERR_NEEDMOREPARAMS,
+            nick,
+            'MONITOR',
+            'Not enough parameters',
+          ),
+        ]),
+      ],
+    };
+  }
+
+  const watchlist = ensureWatchlist(state);
+
+  const added: { folded: string; display: string }[] = [];
+  const rejected: string[] = [];
+  for (const requested of splitNicks(targetList)) {
+    const folded = requested.toLowerCase();
+    if (watchlist.has(folded)) continue; // already monitored; no output
+    if (watchlist.size >= maxMonitor) {
+      rejected.push(requested);
+      continue;
+    }
+    watchlist.add(folded);
+    // For the display spelling prefer the online map (canonical) and fall
+    // back to the requester spelling when the nick is offline.
+    const display = online.get(folded) ?? requested;
+    added.push({ folded, display });
+  }
+
+  const effects: EffectType[] = [];
+
+  const onlineDisplays = added.filter((a) => online.has(a.folded)).map((a) => a.display);
+  const offlineDisplays = added.filter((a) => !online.has(a.folded)).map((a) => a.display);
+
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (rejected.length > 0) {
+    effects.push(
+      Effect.send(state.id, [monListFullLine(serverName, nick, maxMonitor, rejected.join(','))]),
+    );
+  }
+
+  return { state, effects };
+}
+
+function handleRemove(state: ConnectionState, targetList: string): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined) return { state, effects: [] };
+  if (targetList.length === 0) return { state, effects: [] };
+  for (const requested of splitNicks(targetList)) {
+    state.monitorList.delete(requested.toLowerCase());
+  }
+  return { state, effects: [] };
+}
+
+function handleClear(state: ConnectionState): ReducerResult<ConnectionState> {
+  // Allocate the set on first clear so callers observe a stable post-state
+  // (size 0) regardless of whether the watchlist previously existed.
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  } else {
+    state.monitorList.clear();
+  }
+  return { state, effects: [] };
+}
+
+function handleList(
+  state: ConnectionState,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  const effects: EffectType[] = [];
+  if (state.monitorList !== undefined) {
+    for (const entry of state.monitorList) {
+      effects.push(Effect.send(state.id, [monLine(Numerics.RPL_MONLIST, serverName, nick, entry)]));
+    }
+  }
+  effects.push(
+    Effect.send(state.id, [
+      monLine(Numerics.RPL_ENDOFMONLIST, serverName, nick, 'End of MONITOR list'),
+    ]),
+  );
+  return { state, effects };
+}
+
+function handleStatus(
+  state: ConnectionState,
+  online: ReadonlyMap<string, string>,
+  nick: string,
+  serverName: string,
+): ReducerResult<ConnectionState> {
+  if (state.monitorList === undefined || state.monitorList.size === 0) {
+    return { state, effects: [] };
+  }
+  const onlineDisplays: string[] = [];
+  const offlineDisplays: string[] = [];
+  for (const folded of state.monitorList) {
+    const display = online.get(folded);
+    if (display !== undefined) {
+      onlineDisplays.push(display);
+    } else {
+      offlineDisplays.push(folded);
+    }
+  }
+  const effects: EffectType[] = [];
+  if (onlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONONLINE, serverName, nick, onlineDisplays.join(',')),
+      ]),
+    );
+  }
+  if (offlineDisplays.length > 0) {
+    effects.push(
+      Effect.send(state.id, [
+        monLine(Numerics.RPL_MONOFFLINE, serverName, nick, offlineDisplays.join(',')),
+      ]),
+    );
+  }
+  return { state, effects };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the connection's watchlist, lazily allocating it on first use.
+ * Existing persisted state migrates without a schema bump (the field stays
+ * optional; reducers that pre-date MONITOR never touch it).
+ */
+function ensureWatchlist(state: ConnectionState): Set<string> {
+  if (state.monitorList === undefined) {
+    state.monitorList = new Set<string>();
+  }
+  return state.monitorList;
+}
+
+/** Splits a comma-separated nick list, dropping empty entries. */
+function splitNicks(csv: string): string[] {
+  return csv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** `:<server> <code> <nick> :<trailing>` — used by 730/731/732/733. */
+function monLine(code: number, serverName: string, nick: string, trailing: string): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} :${trailing}` };
+}
+
+/** `:<server> 734 <nick> <limit> :<rejected>` (ERR_MONLISTFULL). */
+function monListFullLine(
+  serverName: string,
+  nick: string,
+  limit: number,
+  rejected: string,
+): RawLine {
+  const codeStr = Numerics.ERR_MONLISTFULL.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${limit} :${rejected}` };
+}
+
+/** `:<server> <code> <nick> <cmd> :<trailing>` — used by 461-style errors. */
+function numericLine(
+  serverName: string,
+  code: number,
+  nick: string,
+  cmd: string,
+  trailing: string,
+): RawLine {
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: `:${serverName} ${codeStr} ${nick} ${cmd} :${trailing}` };
+}