serverless-ircd 0.1.0

package/packages/in-memory-runtime/tests/in-memory-runtime.test.ts

@@ -0,0 +1,502 @@
+import {
+  type ChannelDelta,
+  type ConnectionState,
+  FakeClock,
+  type RawLine,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { InMemoryRuntime } from '../src/in-memory-runtime';
+
+const L = (text: string): RawLine => ({ text });
+
+function makeConn(id: string, nick?: string): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  if (nick !== undefined) {
+    s.nick = nick;
+    s.user = nick.toLowerCase();
+    s.host = 'example.com';
+    s.realname = nick;
+    s.registration = 'registered';
+  }
+  return s;
+}
+
+describe('InMemoryRuntime — reserveNick', () => {
+  it('returns ok:true the first time a nick is reserved', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+
+    const result = await rt.reserveNick('alice', 'c1');
+    expect(result).toEqual({ ok: true });
+  });
+
+  it('returns ok:false when the nick is already taken by another connection', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.registerConnection(makeConn('c2'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('alice', 'c1');
+    const second = await rt.reserveNick('alice', 'c2');
+    expect(second).toEqual({ ok: false });
+  });
+
+  it('treats nick names case-insensitively (Alice vs alice collide)', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.registerConnection(makeConn('c2'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('Alice', 'c1');
+    const second = await rt.reserveNick('alice', 'c2');
+    expect(second).toEqual({ ok: false });
+  });
+
+  it('allows the same connection to re-reserve its own nick (idempotent)', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('alice', 'c1');
+    const second = await rt.reserveNick('alice', 'c1');
+    expect(second).toEqual({ ok: true });
+  });
+
+  it('is race-free under interleaved concurrent reservations for the same nick', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.registerConnection(makeConn('c2'), { send: () => {}, disconnect: () => {} });
+
+    // Fire both reservations without awaiting between them.
+    const [r1, r2] = await Promise.all([
+      rt.reserveNick('alice', 'c1'),
+      rt.reserveNick('alice', 'c2'),
+    ]);
+
+    // Exactly one wins.
+    const oks = [r1, r2].filter((r) => r.ok).length;
+    expect(oks).toBe(1);
+  });
+
+  it('stress test: 1000 concurrent reservations for one nick yield exactly one winner', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const N = 1000;
+    for (let i = 0; i < N; i++) {
+      const id = `c${i}`;
+      rt.registerConnection(makeConn(id), { send: () => {}, disconnect: () => {} });
+    }
+
+    const results = await Promise.all(
+      Array.from({ length: N }, (_, i) => rt.reserveNick('alice', `c${i}`)),
+    );
+    const winners = results.filter((r) => r.ok).length;
+    expect(winners).toBe(1);
+
+    // The single winner is the owner of record in the registry.
+    const owner = await rt.lookupNick('alice');
+    expect(owner).not.toBeNull();
+    expect(owner).toBe(`c${results.findIndex((r) => r.ok)}`);
+  });
+});
+
+describe('InMemoryRuntime — changeNick', () => {
+  it('returns true and updates the registry when the new nick is free', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('alice', 'c1');
+    const ok = await rt.changeNick('c1', 'alice', 'bob');
+    expect(ok).toBe(true);
+    expect(await rt.lookupNick('alice')).toBeNull();
+    expect(await rt.lookupNick('bob')).toBe('c1');
+  });
+
+  it('returns false and leaves the old mapping when the new nick is taken', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.registerConnection(makeConn('c2'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('alice', 'c1');
+    await rt.reserveNick('bob', 'c2');
+
+    const ok = await rt.changeNick('c1', 'alice', 'bob');
+    expect(ok).toBe(false);
+    expect(await rt.lookupNick('alice')).toBe('c1');
+    expect(await rt.lookupNick('bob')).toBe('c2');
+  });
+});
+
+describe('InMemoryRuntime — releaseNick', () => {
+  it('removes the nick from the registry so it can be re-reserved', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.registerConnection(makeConn('c2'), { send: () => {}, disconnect: () => {} });
+
+    await rt.reserveNick('alice', 'c1');
+    await rt.releaseNick('alice');
+    const second = await rt.reserveNick('alice', 'c2');
+    expect(second).toEqual({ ok: true });
+  });
+
+  it('is a no-op for a nick that was never reserved', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await expect(rt.releaseNick('ghost')).resolves.toBeUndefined();
+  });
+});
+
+describe('InMemoryRuntime — lookupNick', () => {
+  it('returns the connection id owning the nick', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    await rt.reserveNick('alice', 'c1');
+
+    expect(await rt.lookupNick('alice')).toBe('c1');
+  });
+
+  it('is case-insensitive', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    await rt.reserveNick('Alice', 'c1');
+
+    expect(await rt.lookupNick('alice')).toBe('c1');
+    expect(await rt.lookupNick('ALICE')).toBe('c1');
+  });
+
+  it('returns null when no connection owns the nick', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    expect(await rt.lookupNick('nobody')).toBeNull();
+  });
+});
+
+describe('InMemoryRuntime — getConnectionInfo', () => {
+  it('returns a snapshot of a registered connection', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const conn = makeConn('c1', 'alice');
+    rt.registerConnection(conn, { send: () => {}, disconnect: () => {} });
+
+    const snap = await rt.getConnectionInfo('c1');
+    expect(snap).not.toBeNull();
+    expect(snap?.id).toBe('c1');
+    expect(snap?.nick).toBe('alice');
+    expect(snap?.hostmask).toBe('alice!alice@example.com');
+  });
+
+  it('reflects subsequent mutations to the live state object', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const conn = makeConn('c1');
+    rt.registerConnection(conn, { send: () => {}, disconnect: () => {} });
+
+    let snap = await rt.getConnectionInfo('c1');
+    expect(snap?.nick).toBeUndefined();
+
+    conn.nick = 'alice';
+    snap = await rt.getConnectionInfo('c1');
+    expect(snap?.nick).toBe('alice');
+  });
+
+  it('returns null for an unknown connection', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    expect(await rt.getConnectionInfo('ghost')).toBeNull();
+  });
+});
+
+describe('InMemoryRuntime — applyChannelDelta / getChannelSnapshot', () => {
+  it('creates a channel on demand when a delta arrives for it', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const delta: ChannelDelta = {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    };
+    await rt.applyChannelDelta('#foo', delta);
+
+    const snap = await rt.getChannelSnapshot('#foo');
+    expect(snap).not.toBeNull();
+    expect(snap?.name).toBe('#foo');
+    expect(snap?.nameLower).toBe('#foo');
+    expect(snap?.members.size).toBe(1);
+    expect(snap?.members.get('c1')?.nick).toBe('alice');
+  });
+
+  it('is case-insensitive on the channel name (lookup and dedup)', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await rt.applyChannelDelta('#Foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    const snap = await rt.getChannelSnapshot('#foo');
+    expect(snap).not.toBeNull();
+    expect(snap?.name).toBe('#Foo'); // original case preserved
+    expect(snap?.members.has('c1')).toBe(true);
+  });
+
+  it('returns null from getChannelSnapshot for an unknown channel', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    expect(await rt.getChannelSnapshot('#nope')).toBeNull();
+  });
+
+  it('applies mode and topic deltas alongside memberships', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await rt.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice', op: true }],
+      modeChanges: [{ mode: 'topicLock', set: true }],
+      topic: { text: 'hi', setter: 'alice', setAt: 100 },
+    });
+
+    const snap = await rt.getChannelSnapshot('#foo');
+    expect(snap?.modes.topicLock).toBe(true);
+    expect(snap?.topic).toEqual({ text: 'hi', setter: 'alice', setAt: 100 });
+    expect(snap?.members.get('c1')?.op).toBe(true);
+  });
+});
+
+describe('InMemoryRuntime — send', () => {
+  it('delivers lines to the target connection send handler', async () => {
+    const sent: RawLine[][] = [];
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), {
+      send: (lines) => {
+        sent.push(lines);
+      },
+      disconnect: () => {},
+    });
+
+    await rt.send('c1', [L('PONG :tok')]);
+    expect(sent).toEqual([[{ text: 'PONG :tok' }]]);
+  });
+
+  it('silently drops sends to unknown connections', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await expect(rt.send('ghost', [L('hi')])).resolves.toBeUndefined();
+  });
+});
+
+describe('InMemoryRuntime — broadcast', () => {
+  it('delivers lines to every member of the channel', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const received: Record<string, RawLine[][]> = { c1: [], c2: [], c3: [] };
+    const push = (id: string) => (lines: RawLine[]) => received[id]?.push(lines);
+    for (const id of ['c1', 'c2', 'c3']) {
+      rt.registerConnection(makeConn(id, id === 'c1' ? 'alice' : `nick_${id}`), {
+        send: push(id),
+        disconnect: () => {},
+      });
+    }
+    await rt.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'alice' },
+        { type: 'add', conn: 'c2', nick: 'nick_c2' },
+        { type: 'add', conn: 'c3', nick: 'nick_c3' },
+      ],
+    });
+
+    await rt.broadcast('#foo', [L(':alice PRIVMSG #foo :hi')]);
+    expect(received.c1).toHaveLength(1);
+    expect(received.c2).toHaveLength(1);
+    expect(received.c3).toHaveLength(1);
+  });
+
+  it('skips the except connection when supplied', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const received: Record<string, RawLine[][]> = { c1: [], c2: [], c3: [] };
+    const push = (id: string) => (lines: RawLine[]) => received[id]?.push(lines);
+    for (const id of ['c1', 'c2', 'c3']) {
+      rt.registerConnection(makeConn(id, `nick_${id}`), {
+        send: push(id),
+        disconnect: () => {},
+      });
+    }
+    await rt.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'nick_c1' },
+        { type: 'add', conn: 'c2', nick: 'nick_c2' },
+        { type: 'add', conn: 'c3', nick: 'nick_c3' },
+      ],
+    });
+
+    await rt.broadcast('#foo', [L('hi')], 'c2');
+    expect(received.c1).toHaveLength(1);
+    expect(received.c2).toHaveLength(0);
+    expect(received.c3).toHaveLength(1);
+  });
+
+  it('broadcasts to all members when except is omitted', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const received: Record<string, number> = { c1: 0, c2: 0 };
+    const bump = (id: string) => () => {
+      received[id] = (received[id] ?? 0) + 1;
+    };
+    for (const id of ['c1', 'c2']) {
+      rt.registerConnection(makeConn(id, `nick_${id}`), {
+        send: bump(id),
+        disconnect: () => {},
+      });
+    }
+    await rt.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'nick_c1' },
+        { type: 'add', conn: 'c2', nick: 'nick_c2' },
+      ],
+    });
+
+    await rt.broadcast('#foo', [L('hi')]);
+    expect(received).toEqual({ c1: 1, c2: 1 });
+  });
+
+  it('silently drops delivery to members whose connection has gone', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    let c2Received = 0;
+    rt.registerConnection(makeConn('c1', 'alice'), {
+      send: () => {},
+      disconnect: () => {},
+    });
+    rt.registerConnection(makeConn('c2', 'bob'), {
+      send: () => {
+        c2Received++;
+      },
+      disconnect: () => {},
+    });
+    await rt.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'alice' },
+        { type: 'add', conn: 'c2', nick: 'bob' },
+      ],
+    });
+
+    // c2 vanishes without the channel being updated.
+    rt.unregisterConnection('c2');
+    await rt.broadcast('#foo', [L('hi')]);
+    expect(c2Received).toBe(0);
+  });
+
+  it('is a no-op for a channel that does not exist', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await expect(rt.broadcast('#nope', [L('hi')])).resolves.toBeUndefined();
+  });
+});
+
+describe('InMemoryRuntime — sendToNick', () => {
+  it('routes lines to the connection that owns the nick', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const sent: RawLine[][] = [];
+    rt.registerConnection(makeConn('c1', 'alice'), {
+      send: (lines) => {
+        sent.push(lines);
+      },
+      disconnect: () => {},
+    });
+    rt.registerConnection(makeConn('c2', 'bob'), { send: () => {}, disconnect: () => {} });
+    await rt.reserveNick('alice', 'c1');
+
+    await rt.sendToNick('alice', 'c2', [L(':bob PRIVMSG alice :hi')]);
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toEqual([{ text: ':bob PRIVMSG alice :hi' }]);
+  });
+
+  it('delivers notFoundLines to the sender when the nick is offline', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const senderOut: RawLine[][] = [];
+    rt.registerConnection(makeConn('c1', 'bob'), {
+      send: (lines) => {
+        senderOut.push(lines);
+      },
+      disconnect: () => {},
+    });
+
+    await rt.sendToNick('ghost', 'c1', [L('hi')], [L('401 bob ghost :No such nick')]);
+    expect(senderOut).toEqual([[{ text: '401 bob ghost :No such nick' }]]);
+  });
+
+  it('silently drops when the nick is offline and no notFoundLines were supplied', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const senderOut: RawLine[][] = [];
+    rt.registerConnection(makeConn('c1', 'bob'), {
+      send: (lines) => {
+        senderOut.push(lines);
+      },
+      disconnect: () => {},
+    });
+
+    await rt.sendToNick('ghost', 'c1', [L('hi')]);
+    expect(senderOut).toEqual([]);
+  });
+
+  it('drops silently when the sender itself is gone (cannot deliver notFoundLines)', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await expect(rt.sendToNick('ghost', 'c1', [L('hi')], [L('401')])).resolves.toBeUndefined();
+  });
+});
+
+describe('InMemoryRuntime — disconnect', () => {
+  it('invokes the registered disconnect handler with the reason', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    let disconnected: string | undefined;
+    rt.registerConnection(makeConn('c1', 'alice'), {
+      send: () => {},
+      disconnect: (reason) => {
+        disconnected = reason;
+      },
+    });
+
+    await rt.disconnect('c1', 'Excess Flood');
+    expect(disconnected).toBe('Excess Flood');
+  });
+
+  it('passes undefined reason through unchanged', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    let disconnected: string | undefined = 'unset';
+    rt.registerConnection(makeConn('c1', 'alice'), {
+      send: () => {},
+      disconnect: (reason) => {
+        disconnected = reason;
+      },
+    });
+
+    await rt.disconnect('c1');
+    expect(disconnected).toBeUndefined();
+  });
+
+  it('is a no-op for an unknown connection', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    await expect(rt.disconnect('ghost')).resolves.toBeUndefined();
+  });
+});
+
+describe('InMemoryRuntime — connection lifecycle', () => {
+  it('registerConnection tracks a connection; unregisterConnection removes it', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1', 'alice'), { send: () => {}, disconnect: () => {} });
+    expect(rt.hasConnection('c1')).toBe(true);
+
+    rt.unregisterConnection('c1');
+    expect(rt.hasConnection('c1')).toBe(false);
+    expect(await rt.getConnectionInfo('c1')).toBeNull();
+  });
+
+  it('unregisterConnection is idempotent', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    rt.registerConnection(makeConn('c1'), { send: () => {}, disconnect: () => {} });
+    rt.unregisterConnection('c1');
+    expect(() => rt.unregisterConnection('c1')).not.toThrow();
+  });
+
+  it('getConnection returns the live state object that reducers mutate in place', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const conn = makeConn('c1');
+    rt.registerConnection(conn, { send: () => {}, disconnect: () => {} });
+
+    const live = await rt.getConnection('c1');
+    expect(live).toBe(conn);
+  });
+
+  it('getConnection returns null for an unknown connection', async () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    expect(await rt.getConnection('ghost')).toBeNull();
+  });
+
+  it('getOrCreateChannel creates a fresh channel keyed by nameLower on first access', () => {
+    const rt = new InMemoryRuntime({ clock: new FakeClock(0) });
+    const chan = rt.getOrCreateChannel('#Foo');
+    expect(chan.name).toBe('#Foo');
+    expect(chan.nameLower).toBe('#foo');
+    expect(chan.members.size).toBe(0);
+
+    // Second access returns the same object.
+    expect(rt.getOrCreateChannel('#foo')).toBe(chan);
+  });
+});

package/packages/in-memory-runtime/tsconfig.build.json

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

package/packages/in-memory-runtime/tsconfig.test.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": [],
+    "composite": false
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["dist"],
+  "references": [
+    { "path": "../irc-core/tsconfig.build.json" },
+    { "path": "../irc-server/tsconfig.build.json" }
+  ]
+}

package/packages/in-memory-runtime/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/index.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      },
+    },
+  },
+});

package/packages/irc-core/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@serverless-ircd/irc-core",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Platform-agnostic IRC protocol core: parser, serializer, command reducers, state shapes",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "import": "./dist/protocol/index.js"
+    }
+  },
+  "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"
+  },
+  "files": ["dist", "src", "README.md"]
+}

package/packages/irc-core/src/caps/capabilities.ts

@@ -0,0 +1,96 @@
+/**
+ * IRCv3 capability table (data only).
+ *
+ * The CAP *negotiation reducer* ships separately; this module is the
+ * pure-data table that advertises what caps this server supports. PLAN §3
+ * lists the v1 cap set; later tickets implement each cap's behavior.
+ *
+ * The table is exposed as a frozen, sorted list so the `CAP LS` response
+ * (and any future `CAP NEW` push) serializes deterministically.
+ */
+
+/** One advertised IRCv3 capability. */
+export interface Capability {
+  /** Wire name (`server-time`, `sasl`, …). */
+  name: string;
+  /** Optional value (`PLAIN,EXTERNAL` for `sasl`); bare name when absent. */
+  value?: string;
+}
+
+/**
+ * Every cap advertised by this server in PLAN §3, in canonical (alpha) order
+ * so wire output is deterministic across runs.
+ */
+export const SUPPORTED_CAPABILITIES: ReadonlyArray<Capability> = Object.freeze([
+  { name: 'account-tag' },
+  { name: 'away-notify' },
+  { name: 'batch' },
+  { name: 'chghost' },
+  { name: 'echo-message' },
+  { name: 'extended-join' },
+  { name: 'invite-notify' },
+  { name: 'message-tags' },
+  { name: 'multi-prefix' },
+  { name: 'safelist' },
+  { name: 'sasl', value: 'PLAIN,EXTERNAL' },
+  { name: 'server-time' },
+]);
+
+/** Set form for fast membership checks during `CAP REQ`. */
+export const SUPPORTED_CAP_NAMES: ReadonlySet<string> = new Set<string>(
+  SUPPORTED_CAPABILITIES.map((c) => c.name),
+);
+
+/** Returns true iff `name` is a supported cap (case-sensitive). */
+export function isSupportedCap(name: string): boolean {
+  return SUPPORTED_CAP_NAMES.has(name);
+}
+
+/**
+ * Serializes one capability to its `CAP LS` token form:
+ * `name` when no value, `name=value` when present.
+ */
+export function capToLsString(cap: Capability): string {
+  return cap.value === undefined ? cap.name : `${cap.name}=${cap.value}`;
+}
+
+/**
+ * Returns the full `CAP LS` payload (space-separated tokens) for every
+ * supported cap, in {@link SUPPORTED_CAPABILITIES} order.
+ */
+export function getLsString(): string {
+  return SUPPORTED_CAPABILITIES.map(capToLsString).join(' ');
+}
+
+/**
+ * Splits a list of cap tokens into wire lines that each fit within
+ * `maxBytes` (the per-line content budget, NOT the full 512 — callers
+ * subtract the `:server CAP nick LS :` overhead before passing).
+ *
+ * Packing is greedy: each line is filled until the next token would
+ * overflow the budget. A token longer than the budget gets its own line
+ * (still emitted — never dropped).
+ *
+ * Returns `['']` for an empty token list so the wire layer always has at
+ * least one LS line to send (IRC clients expect a trailing `:*`).
+ */
+export function splitCapsForWire(tokens: readonly string[], maxBytes: number): string[] {
+  if (tokens.length === 0) return [''];
+  const lines: string[] = [];
+  let current = '';
+  for (const token of tokens) {
+    if (current.length === 0) {
+      current = token;
+      continue;
+    }
+    const candidate = `${current} ${token}`;
+    if (candidate.length <= maxBytes) {
+      current = candidate;
+    } else {
+      lines.push(current);
+      current = token;
+    }
+  }
+  lines.push(current);
+  return lines;
+}

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

@@ -0,0 +1 @@
+export * from './capabilities.js';