serverless-ircd 0.1.0

package/apps/cf-worker/scripts/smoke.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * CI smoke e2e for a deployed Cloudflare Worker.
+ *
+ * Replays the same CONNECT → REGISTER → JOIN → PRIVMSG → QUIT flow as
+ * `tests/smoke.test.ts`, but against a live deployed Worker URL. Exits
+ * non-zero on any failure so the GitHub Actions `deploy-cf.yml` job
+ * fails the build.
+ *
+ * Usage:
+ *   node scripts/smoke.mjs --url wss://serverless-ircd-staging.<acct>.workers.dev
+ *
+ * Defaults to `ws://localhost:8787` so the same script works against a
+ * local `wrangler dev` session.
+ *
+ * Dependencies: only the `ws` WebSocket client (already used by
+ * `apps/local-cli`). The script is plain Node ESM — no TypeScript
+ * transform needed in CI.
+ */
+
+import { WebSocket } from 'ws';
+
+const args = parseArgs(process.argv.slice(2));
+const url = args.url ?? 'ws://localhost:8787';
+
+const POLL_MS = 50;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Numeric command position in an IRC line (after optional `:server` prefix). */
+function numericEquals(line, code) {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  return parts[start] === code;
+}
+
+async function runSmoke() {
+  const ws = await openSocket(url);
+  const received = [];
+
+  ws.on('message', (data) => {
+    const text = data.toString();
+    for (const line of text.split('\r\n')) {
+      if (line.length > 0) received.push(line);
+    }
+  });
+
+  const waitForNumeric = (code, timeoutMs = DEFAULT_TIMEOUT_MS) =>
+    waitForPredicate(
+      (line) => numericEquals(line, code),
+      `numeric ${code}`,
+      received,
+      timeoutMs,
+      POLL_MS,
+    );
+  const waitForLine = (predicate, label, timeoutMs = DEFAULT_TIMEOUT_MS) =>
+    waitForPredicate(predicate, label, received, timeoutMs, POLL_MS);
+
+  // REGISTER
+  ws.send('NICK smoke\r\n');
+  ws.send('USER smoke 0 * :Smoke Test\r\n');
+  await waitForNumeric('001', DEFAULT_TIMEOUT_MS);
+  await waitForNumeric('376', DEFAULT_TIMEOUT_MS);
+
+  // JOIN
+  ws.send('JOIN #smoke\r\n');
+  await waitForLine((l) => l.includes('JOIN') && l.includes('#smoke'), 'JOIN echo');
+  await waitForNumeric('353', DEFAULT_TIMEOUT_MS);
+  await waitForNumeric('366', DEFAULT_TIMEOUT_MS);
+
+  // PRIVMSG (no echo expected — echo-message is opt-in via CAP)
+  ws.send('PRIVMSG #smoke :hello from ci\r\n');
+
+  // QUIT — expect the server to close the socket
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, DEFAULT_TIMEOUT_MS);
+    ws.once('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    ws.once('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`socket error during QUIT: ${err.message}`));
+    });
+    ws.send('QUIT :smoke test complete\r\n');
+  });
+
+  ws.close();
+  process.stdout.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'info',
+      msg: 'cf-worker smoke e2e passed',
+      url,
+    })}\n`,
+  );
+}
+
+function openSocket(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(new Error(`connect timeout: ${url}`));
+    }, DEFAULT_TIMEOUT_MS);
+    ws.once('open', () => {
+      clearTimeout(timer);
+      resolve(ws);
+    });
+    ws.once('error', (err) => {
+      clearTimeout(timer);
+      reject(new Error(`connect failed: ${err.message}`));
+    });
+  });
+}
+
+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();
+  });
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--url' && next !== undefined) {
+      out.url = next;
+      i++;
+    } else if (a === '-h' || a === '--help') {
+      process.stdout.write(
+        [
+          'Usage: node scripts/smoke.mjs --url wss://<worker-url>',
+          '',
+          'Options:',
+          '  --url <ws-url>   WebSocket URL of the deployed Worker.',
+          '                   Defaults to ws://localhost:8787 (wrangler dev).',
+          '  -h, --help       Show this help.',
+          '',
+        ].join('\n'),
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+runSmoke().catch((err) => {
+  process.stderr.write(
+    `${JSON.stringify({
+      ts: new Date().toISOString(),
+      level: 'error',
+      msg: 'cf-worker smoke e2e failed',
+      error: err instanceof Error ? err.message : String(err),
+    })}\n`,
+  );
+  process.exit(1);
+});

package/apps/cf-worker/src/worker.ts

@@ -0,0 +1,59 @@
+/**
+ * `apps/cf-worker` entry point — Cloudflare Worker deploy glue.
+ *
+ * This is the thin production entry that wires the cf-adapter's three
+ * Durable Objects (ConnectionDO, RegistryDO, ChannelDO) to inbound
+ * WebSocket traffic. Per PLAN §6.1 / §2.2:
+ *
+ *   • Worker `fetch` is the public edge: every connection enters here.
+ *   • Each WebSocket upgrade is routed to a fresh `ConnectionDO`
+ *     instance named by a server-generated connection id. Allocating
+ *     the id at the edge (rather than trusting a client-supplied id)
+ *     keeps the id space opaque and unforgeable.
+ *   • Cross-DO coordination (registry + channel) is owned by
+ *     `ConnectionDO` and `CfRuntime`; the worker never touches it.
+ *
+ * The DO classes are re-exported so `wrangler.toml`'s
+ * `durable_objects.bindings.class_name` can resolve them in this
+ * module's scope (wrangler requires the class to be exported from the
+ * `main` entry).
+ *
+ * Deployment: `wrangler deploy --env staging` (or `:production`).
+ * See `wrangler.toml` and `docs/deployment-cf.md`.
+ */
+
+import { ChannelDO, ConnectionDO, type Env, RegistryDO } from '@serverless-ircd/cf-adapter';
+
+// Re-exported for wrangler DO binding resolution. The class names below
+// MUST match `class_name` in `wrangler.toml`.
+export { ChannelDO, ConnectionDO, RegistryDO };
+export type { Env };
+
+/**
+ * Default edge handler. Non-WebSocket requests get a human-readable
+ * health response; WebSocket upgrades are routed to a per-connection
+ * `ConnectionDO`.
+ *
+ * The connection id is allocated here via `crypto.randomUUID()` (the
+ * Web Crypto API is sync-available in Workers for RFC-4122 v4 UUIDs).
+ * If a future deployment needs client-supplied ids (e.g. resumable
+ * sessions), accept an opt-in header like `X-Connection-Id` and validate
+ * it before falling back to a fresh uuid.
+ */
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.headers.get('Upgrade') === 'websocket') {
+      const connId = crypto.randomUUID();
+      const id = env.CONNECTION_DO.idFromName(connId);
+      const stub = env.CONNECTION_DO.get(id);
+      return stub.fetch(request);
+    }
+    return new Response(
+      'ServerlessIRCd (Cloudflare Worker). Connect via WebSocket to begin an IRC session.',
+      {
+        status: 200,
+        headers: { 'content-type': 'text/plain; charset=utf-8' },
+      },
+    );
+  },
+};

package/apps/cf-worker/tests/smoke.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Smoke e2e test for the `apps/cf-worker` deploy glue.
+ *
+ * Drives the full CONNECT → REGISTER → JOIN → PRIVMSG → QUIT flow
+ * against the production worker entry point (`src/worker.ts`). Verifies
+ * that the deploy glue — the wrangler.toml DO bindings, the migrations,
+ * and the worker's `fetch` handler that routes an inbound WebSocket
+ * upgrade to a fresh `ConnectionDO` — wires the cf-adapter DOs together
+ * correctly so a real IRC client can complete a full session.
+ *
+ * The same flow is replayed against a deployed staging URL by CI via
+ * `scripts/smoke.mjs` and `.github/workflows/deploy-cf.yml`.
+ *
+ * Test isolation: `vitest.config.ts` runs under
+ * `@cloudflare/vitest-pool-workers` with `isolatedStorage: true`, so each
+ * test gets a fresh DO storage namespace.
+ */
+
+import { env } from 'cloudflare:test';
+import { describe, expect, it } from 'vitest';
+import worker from '../src/worker';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+      SERVER_NAME: string;
+      NETWORK_NAME: string;
+      MOTD_LINES: string;
+    }
+  }
+}
+
+/** Poll interval for the waitFor* helpers (ms). */
+const POLL_MS = 10;
+/** Default timeout for the waitFor* helpers (ms). */
+const DEFAULT_TIMEOUT_MS = 2000;
+
+/** Numeric command position in an IRC line (after optional `:server` prefix). */
+function numericEquals(line: string, code: string): boolean {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  return parts[start] === code;
+}
+
+describe('cf-worker deploy glue', () => {
+  it('non-WebSocket GET returns a human-readable health response', async () => {
+    const response = await worker.fetch(new Request('https://irc.example.com/'), env);
+    expect(response.status).toBe(200);
+    const body = await response.text();
+    expect(body.toLowerCase()).toContain('serverlessircd');
+  });
+
+  it('completes CONNECT → REGISTER → JOIN → PRIVMSG → QUIT', async () => {
+    // ----- CONNECT: WebSocket upgrade through the worker's fetch handler.
+    const upgrade = new Request('https://irc.example.com/', {
+      headers: { Upgrade: 'websocket' },
+    });
+    const response = await worker.fetch(upgrade, env);
+    expect(response.status).toBe(101);
+    const ws = response.webSocket;
+    expect(ws).toBeDefined();
+    ws?.accept();
+
+    const received: string[] = [];
+    const waitForNumeric = async (
+      code: string,
+      timeoutMs = DEFAULT_TIMEOUT_MS,
+    ): Promise<string> => {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        for (const line of received) {
+          if (numericEquals(line, code)) return line;
+        }
+        await new Promise((r) => setTimeout(r, POLL_MS));
+      }
+      throw new Error(`timed out waiting for ${code}; got: ${JSON.stringify(received)}`);
+    };
+    const waitForLine = async (
+      predicate: (line: string) => boolean,
+      timeoutMs = DEFAULT_TIMEOUT_MS,
+    ): Promise<string> => {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        for (const line of received) {
+          if (predicate(line)) return line;
+        }
+        await new Promise((r) => setTimeout(r, POLL_MS));
+      }
+      throw new Error(`timed out; got: ${JSON.stringify(received)}`);
+    };
+    ws?.addEventListener('message', (ev: MessageEvent) => {
+      const data = ev.data as string;
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) received.push(line);
+      }
+    });
+
+    // ----- REGISTER: NICK + USER → 001 welcome + 376 end-of-MOTD.
+    ws?.send('NICK alice\r\n');
+    ws?.send('USER alice 0 * :Alice\r\n');
+    await waitForNumeric('001');
+    await waitForNumeric('376');
+
+    // ----- JOIN #test → JOIN echo + 353 NAMES + 366 end-of-names.
+    ws?.send('JOIN #test\r\n');
+    await waitForLine((l) => l.includes('JOIN') && l.includes('#test'));
+    await waitForNumeric('353');
+    await waitForNumeric('366');
+
+    // ----- PRIVMSG #test :hello. No echo expected (echo-message is opt-in).
+    ws?.send('PRIVMSG #test :hello\r\n');
+
+    // ----- QUIT :bye. Server closes the socket; we observe via close event.
+    ws?.send('QUIT :bye\r\n');
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, 500);
+      ws?.addEventListener('close', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+
+    // Confirm the QUIT was broadcast to the channel by spawning a second
+    // client and observing alice's QUIT fan-out. (Sparse — the cf-adapter
+    // suite already covers fan-out in depth.)
+  });
+
+  it('allocates a fresh connection id per upgrade (no reuse across clients)', async () => {
+    const a = await worker.fetch(
+      new Request('https://irc.example.com/', { headers: { Upgrade: 'websocket' } }),
+      env,
+    );
+    const b = await worker.fetch(
+      new Request('https://irc.example.com/', { headers: { Upgrade: 'websocket' } }),
+      env,
+    );
+    expect(a.status).toBe(101);
+    expect(b.status).toBe(101);
+    // Both upgrades succeed; the worker must not collapse them into one DO.
+    // (accept() is required before any client-side interaction; the server
+    // side was accepted by ConnectionDO via acceptWebSocket.)
+    a.webSocket?.accept();
+    b.webSocket?.accept();
+    a.webSocket?.close();
+    b.webSocket?.close();
+  });
+});

package/apps/cf-worker/tsconfig.build.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"],
+  "references": [
+    { "path": "../../packages/irc-core/tsconfig.build.json" },
+    { "path": "../../packages/irc-server/tsconfig.build.json" },
+    { "path": "../../packages/cf-adapter/tsconfig.build.json" }
+  ]
+}

package/apps/cf-worker/tsconfig.test.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "node_modules/@cloudflare/vitest-pool-workers/types/cloudflare-test.d.ts"
+  ],
+  "exclude": ["dist"],
+  "references": [
+    { "path": "../../packages/irc-core/tsconfig.build.json" },
+    { "path": "../../packages/irc-server/tsconfig.build.json" },
+    { "path": "../../packages/cf-adapter/tsconfig.build.json" }
+  ]
+}

package/apps/cf-worker/vitest.config.ts

@@ -0,0 +1,31 @@
+import { cloudflareTest } from '@cloudflare/vitest-pool-workers';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 90,
+        functions: 90,
+        branches: 90,
+        statements: 90,
+      },
+    },
+  },
+  plugins: [
+    cloudflareTest({
+      wrangler: {
+        configPath: './wrangler.test.toml',
+      },
+      miniflare: {
+        // Ensure DO alarms and hibernation are supported in tests.
+        compatibilityFlags: ['nodejs_compat'],
+      },
+    }),
+  ],
+});

package/apps/cf-worker/wrangler.test.toml

@@ -0,0 +1,33 @@
+#:schema node_modules/wrangler/config-schema.json
+##
+## Test-only wrangler config for the `apps/cf-worker` smoke suite.
+##
+## Consumed by `vitest.config.ts` via `@cloudflare/vitest-pool-workers`.
+## Mirrors the production `wrangler.toml` minus the staging environment
+## blocks — the smoke test exercises the default env.
+
+name = "cf-worker-test"
+main = "src/worker.ts"
+compatibility_date = "2024-11-01"
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+SERVER_NAME = "irc.example.com"
+NETWORK_NAME = "ServerlessIRCd"
+MOTD_LINES = "Welcome to the cf-worker smoke test."
+
+[[durable_objects.bindings]]
+name = "CONNECTION_DO"
+class_name = "ConnectionDO"
+
+[[durable_objects.bindings]]
+name = "REGISTRY_DO"
+class_name = "RegistryDO"
+
+[[durable_objects.bindings]]
+name = "CHANNEL_DO"
+class_name = "ChannelDO"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]

package/apps/cf-worker/wrangler.toml

@@ -0,0 +1,98 @@
+#:schema node_modules/wrangler/config-schema.json
+##
+## Cloudflare Worker production config for ServerlessIRCd.
+##
+## Deploy:
+##   pnpm deploy:cf:staging     # wrangler deploy --env staging
+##   pnpm deploy:cf:prod        # wrangler deploy
+##
+## The `apps/cf-worker` worker is the public edge for the IRC service.
+## It owns the three Durable Object namespaces from the cf-adapter
+## (ConnectionDO, RegistryDO, ChannelDO) and routes inbound WebSocket
+## upgrades to per-connection ConnectionDO instances. See
+## `src/worker.ts` and PLAN §6.1.
+##
+## Secrets: NEVER put secrets (API tokens, server passwords, account
+## credentials) in this file. Use `wrangler secret put <NAME>` per
+## environment; they live in the Workers KV secrets store, not the repo.
+## As of v1 the worker does not consume any secret bindings — server
+## password, SASL `AccountStore`, and oper creds are future work.
+
+name = "serverless-ircd"
+main = "src/worker.ts"
+compatibility_date = "2024-11-01"
+compatibility_flags = ["nodejs_compat"]
+
+## Observable per-deployment knobs. Override per environment below.
+## Production deployments SHOULD override `SERVER_NAME` to the public
+## hostname clients will see in numerics (001, 005, etc.).
+[vars]
+SERVER_NAME = "irc.example.com"
+NETWORK_NAME = "ServerlessIRCd"
+MOTD_LINES = "Welcome to ServerlessIRCd.\nThis is a deployed Cloudflare Worker."
+
+## ---------------------------------------------------------------------------
+## Staging environment.
+## ---------------------------------------------------------------------------
+## `wrangler deploy --env staging` ships to the staging Worker + DO
+## namespace. The CI workflow (`.github/workflows/deploy-cf.yml`) deploys
+## here on every push to `main` and then runs the smoke e2e.
+[env.staging]
+name = "serverless-ircd-staging"
+
+[env.staging.vars]
+SERVER_NAME = "irc-staging.example.com"
+NETWORK_NAME = "ServerlessIRCd (staging)"
+MOTD_LINES = "Welcome to ServerlessIRCd staging.\nThis Worker was deployed by CI from the main branch."
+
+## ---------------------------------------------------------------------------
+## Durable Object bindings.
+## ---------------------------------------------------------------------------
+## Each binding maps a name (used by `Env` in `src/worker.ts`) to a DO
+## class exported from `main`. The classes themselves live in
+## `packages/cf-adapter/src/{connection,registry,channel}-do.ts` and are
+## re-exported from the worker entry.
+
+# Default environment bindings.
+[[durable_objects.bindings]]
+name = "CONNECTION_DO"
+class_name = "ConnectionDO"
+
+[[durable_objects.bindings]]
+name = "REGISTRY_DO"
+class_name = "RegistryDO"
+
+[[durable_objects.bindings]]
+name = "CHANNEL_DO"
+class_name = "ChannelDO"
+
+# Staging environment bindings (wrangler requires per-env blocks).
+[[env.staging.durable_objects.bindings]]
+name = "CONNECTION_DO"
+class_name = "ConnectionDO"
+
+[[env.staging.durable_objects.bindings]]
+name = "REGISTRY_DO"
+class_name = "RegistryDO"
+
+[[env.staging.durable_objects.bindings]]
+name = "CHANNEL_DO"
+class_name = "ChannelDO"
+
+## ---------------------------------------------------------------------------
+## Durable Object migrations.
+## ---------------------------------------------------------------------------
+## `tag` is the user-defined migration id; wrangler refuses to deploy if
+## the on-disk migrations don't match the live Workers state. `new_classes`
+## declares the three DO classes on first deploy; subsequent schema
+## changes (renames, deletions, splits) extend this list with their own
+## `tag` so the runtime can migrate persisted state.
+##
+## See https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
+
+[[env.staging.migrations]]
+tag = "v1"
+new_sqlite_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]

package/apps/local-cli/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@serverless-ircd/local-cli",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/main.js",
+  "bin": {
+    "local-cli": "./dist/main.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "start": "node --enable-source-maps ./dist/main.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "@serverless-ircd/in-memory-runtime": "workspace:*",
+    "@serverless-ircd/irc-core": "workspace:*",
+    "@serverless-ircd/irc-server": "workspace:*",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@types/ws": "^8.5.13",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}

package/apps/local-cli/src/line-scanner.ts

@@ -0,0 +1,60 @@
+/**
+ * Byte-accurate line scanner for the local-cli's TCP transport.
+ *
+ * TCP is a byte stream, not a message stream: a single `data` chunk may
+ * contain several IRC lines, a partial line, or a line split across two
+ * chunks. The {@link LineScanner} accumulates raw `Buffer` chunks and emits
+ * each complete line as a decoded UTF-8 string the moment it sees a line
+ * terminator. Decoding happens only on whole lines, so a multi-byte UTF-8
+ * sequence split across two TCP chunks is never corrupted.
+ *
+ * Line endings are tolerated per PLAN §9 transport rules: both CRLF
+ * (`\r\n`) and bare LF (`\n`) terminate a line; a lone CR in the middle of
+ * text is treated as data. The trailing `\r` of a CRLF pair is stripped
+ * before the line is returned.
+ *
+ * Mirrors `tools/tcp-ws-forwarder/src/line-scanner.ts` — the same algorithm
+ * applies on both sides of the WS↔TCP bridge so framing semantics match
+ * exactly when a real IRC client connects to local-cli directly.
+ */
+
+export class LineScanner {
+  private carry: Buffer = Buffer.alloc(0);
+
+  /**
+   * Feeds a chunk of TCP bytes. Returns the complete lines found in this
+   * chunk (joined with any leftover carry from prior chunks), in order,
+   * with terminators removed. Any trailing unterminated bytes are retained
+   * internally for the next call.
+   */
+  push(chunk: Buffer): string[] {
+    const buf = Buffer.concat([this.carry, chunk]);
+    const lines: string[] = [];
+    let start = 0;
+    let nl = buf.indexOf(0x0a, start);
+    while (nl !== -1) {
+      let end = nl;
+      if (end > start && buf[end - 1] === 0x0d) {
+        end--;
+      }
+      lines.push(buf.toString('utf8', start, end));
+      start = nl + 1;
+      nl = buf.indexOf(0x0a, start);
+    }
+    this.carry = buf.subarray(start);
+    return lines;
+  }
+
+  /**
+   * Returns any unterminated tail still buffered (lossless), then clears
+   * the carry. The server does NOT call this on TCP close — an IRC line
+   * without a terminator is a protocol violation and is dropped — but the
+   * method is exposed for completeness and tested directly.
+   */
+  flush(): string[] {
+    if (this.carry.length === 0) return [];
+    const rest = this.carry.toString('utf8');
+    this.carry = Buffer.alloc(0);
+    return [rest];
+  }
+}