serverless-ircd 0.4.0 → 0.6.0

package/apps/aws-stack/tests/coverage-command.test.ts

@@ -0,0 +1,155 @@
+/**
+ * CI-hardening acceptance test for the aws-stack coverage command.
+ *
+ * Drives the real `pnpm --filter @serverless-ircd/aws-stack coverage`
+ * pipeline in a subprocess and asserts two things the ticket requires:
+ *
+ *   1. The command exits 0 (no `[ELIFECYCLE]` / OOM crash).
+ *   2. The vitest text reporter prints an `All files` coverage row.
+ *
+ * Before the bundle-stub fix this command exhausted CI memory re-running
+ * esbuild for every `NodejsFunction` synth (one per stack-related test,
+ * multiplied by 3–4 Lambda constructs each), and died with
+ * `[ELIFECYCLE] Command failed with exit code N` before the coverage
+ * table could print. The stub (`makeLambda` in `src/aws-stack.ts`,
+ * armed by `tests/vitest.setup.ts`) makes the synth a no-op for
+ * bundling so the pipeline completes in seconds.
+ *
+ * Recursion guard: the subprocess inherits
+ * `IRC_AWS_COVERAGE_SELF_TEST=1`, which makes this describe block skip
+ * itself when re-entered. Without that, the outer coverage run would
+ * spawn the coverage command, which spawns the coverage command, … .
+ *
+ * Slow-path: the subprocess still spins up pnpm + vitest + the v8
+ * coverage provider, so the test carries a generous timeout. It is
+ * intentionally part of the default `pnpm test` run because it is the
+ * end-to-end guard against the coverage pipeline silently regressing
+ * back into the bundling loop.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it } from 'vitest';
+
+/** Skip-self env var handed to the subprocess so it does not re-spawn. */
+const SELF_TEST_FLAG = 'IRC_AWS_COVERAGE_SELF_TEST';
+
+/** Hard ceiling for the subprocess; the stubbed suite finishes well under this. */
+const COVERAGE_TIMEOUT_MS = 240_000;
+
+/**
+ * Strips ANSI color / cursor escapes from `combined` so the assertion
+ * regexes below can be plain text. Vitest always writes the coverage
+ * banner and table through its colorizer even when stdout is piped, so
+ * without this the banner reads `% \u001b[2mCoverage report from …`
+ * and a literal `/Coverage report from v8/` regex fails to match.
+ */
+function stripAnsi(text: string): string {
+  // The ANSI color escape is the literal ESC byte (0x1B) followed by `[`
+  // and a parameter list. biome's noControlCharactersInRegex flags the
+  // inline `\u001b` literal, so the regex is built from a hex string to
+  // make the intent explicit while satisfying the linter.
+  const ansiPattern = new RegExp(`[${String.fromCharCode(27)}]\\[[0-9;]*m`, 'g');
+  return text.replace(ansiPattern, '');
+}
+
+describe.skipIf(process.env[SELF_TEST_FLAG] === '1')(
+  'aws-stack coverage command (ci-hardening acceptance)',
+  () => {
+    it(
+      'completes and prints an "All files" coverage row',
+      () => {
+        // Strip the `npm_package_*` / `npm_config_*` env vars that the outer
+        // `pnpm run coverage` sets. When those leak into the spawned pnpm,
+        // its `--filter` resolution short-circuits to the current package
+        // and fails with `ERR_PNPM_RECURSIVE_RUN_NO_SCRIPT` even though the
+        // workspace package exposes the script. The inner pnpm must resolve
+        // the filter against the workspace root, not the parent run context.
+        //
+        // Also strip AI-agent env vars (CLAUDECODE, OPENCODE, …): vitest's
+        // std-env dependency detects them and flips the text reporter into
+        // `skipFull` mode, which hides the `All files` row this test exists
+        // to assert on. CI runners never set these; the strip only matters
+        // when the suite is launched from inside an agent shell.
+        const cleanedEnv: Record<string, string | undefined> = { ...process.env };
+        for (const key of Object.keys(cleanedEnv)) {
+          if (
+            key.startsWith('npm_package_') ||
+            key.startsWith('npm_config_') ||
+            key.startsWith('npm_lifecycle_') ||
+            key === 'INIT_CWD' ||
+            key === 'OPENCODE' ||
+            key === 'CLAUDECODE' ||
+            key === 'CLAUDE_CODE' ||
+            key === 'GEMINI_CLI' ||
+            key === 'CODEX_SANDBOX' ||
+            key === 'CODEX_THREAD_ID' ||
+            key === 'AUGMENT_AGENT' ||
+            key === 'GOOSE_PROVIDER'
+          ) {
+            cleanedEnv[key] = '';
+          }
+        }
+        cleanedEnv[SELF_TEST_FLAG] = '1';
+
+        const result = spawnSync(
+          'pnpm',
+          [
+            '--filter',
+            '@serverless-ircd/aws-stack',
+            'exec',
+            'vitest',
+            'run',
+            '--coverage',
+            // Send the inner run's coverage output to a sibling directory so
+            // it cannot race the outer vitest that spawned us (both would
+            // otherwise write to `./coverage` and the loser crashes with
+            // "Something removed the coverage directory").
+            '--coverage.reportsDirectory=coverage-self-test',
+          ],
+          {
+            encoding: 'utf8',
+            env: cleanedEnv,
+          },
+        );
+
+        // Exit code 0 = no `[ELIFECYCLE]` / early exit. Report the captured
+        // output in the assertion message so a CI failure shows what the
+        // subprocess actually printed instead of a bare status code.
+        if (result.status !== 0) {
+          throw new Error(
+            `coverage command exited with status ${result.status as number | string}\n` +
+              `--- stdout ---\n${result.stdout}\n` +
+              `--- stderr ---\n${result.stderr}`,
+          );
+        }
+
+        const combined = stripAnsi(`${result.stdout}\n${result.stderr}`);
+
+        // The vitest text reporter prefixes its table with this banner; the
+        // `All files` summary row follows. Asserting both makes the test
+        // robust to incidental wording changes elsewhere in the output.
+        expect(combined, 'coverage command must emit the v8 coverage banner').toMatch(
+          /Coverage report from v8/,
+        );
+        expect(combined, 'coverage command must emit an "All files" summary row').toMatch(
+          /All files/,
+        );
+
+        // Belt-and-braces: if the bundle stub ever regresses, the subprocess
+        // would flood `Bundling asset TestStack/IrcHandler/Code/Stage…` once
+        // per Lambda per test (dozens to hundreds of times) and eventually
+        // OOM in CI. With the stub active the count is at most a handful
+        // (only the deliberately-ungated production-path test triggers real
+        // esbuild runs, and it bounds itself to one stack). Assert the count
+        // stays small so a regression fails loudly here instead of looking
+        // like a mysterious `[ELIFECYCLE]` exit on the CI runner.
+        const bundleCount = (combined.match(/Bundling asset/g) ?? []).length;
+        expect(
+          bundleCount,
+          'coverage command must not loop esbuild bundling across the test synth',
+        ).toBeLessThan(10);
+      },
+      COVERAGE_TIMEOUT_MS,
+    );
+  },
+);

package/apps/aws-stack/tests/stack.test.ts

@@ -1,7 +1,7 @@
 /**
  * Synth-time assertions for the `apps/aws-stack` CDK stack.
  *
- * These are the primary red→green tests for the infrastructure ticket:
+ * These are the primary red→green tests for the infrastructure stack:
  * they assert the exact CloudFormation shape that `cdk synth` must
  * produce — five DynamoDB tables with the PLAN §4 schema, a single
  * Node 24 Lambda wired to all three WebSocket routes, the API Gateway
@@ -149,6 +149,52 @@ describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
     const { template } = makeTemplate();
     template.resourceCountIs('AWS::ApiGatewayV2::Route', 3);
   });
+
+  it('enables the $connect route to return a response (route response selection)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+      RouteKey: '$connect',
+      RouteResponseSelectionExpression: '$default',
+    });
+  });
+
+  it('creates a $connect route response so the upgrade can carry a response', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::RouteResponse', {
+      RouteResponseKey: '$default',
+    });
+  });
+});
+
+describe('IrcAwsStack — IRCv3 WebSocket subprotocol echo', () => {
+  it('attaches an integration response on the $connect route mapping Sec-WebSocket-Protocol', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      ResponseParameters: {
+        'method.response.header.Sec-WebSocket-Protocol':
+          'integration.response.header.Sec-WebSocket-Protocol',
+      },
+    });
+  });
+
+  it('binds the subprotocol integration response to the $connect integration', () => {
+    const { template, stack } = makeTemplate();
+    const responses = template.findResources('AWS::ApiGatewayV2::IntegrationResponse');
+    // Exactly one integration response is configured (the $connect subprotocol echo).
+    expect(Object.keys(responses)).toHaveLength(1);
+    // The IntegrationId Ref must resolve to a CfnIntegration under the $connect route.
+    const stackName = stack.stackName;
+    void stackName;
+    const cfnIntegrations = template.findResources('AWS::ApiGatewayV2::Integration');
+    expect(Object.keys(cfnIntegrations).length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('uses the $default integration response key', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::IntegrationResponse', {
+      IntegrationResponseKey: '$default',
+    });
+  });
 });
 
 describe('IrcAwsStack — Lambda', () => {
@@ -437,11 +483,11 @@ describe('IrcAwsStack — server identity props (configurable deploy identity)',
     );
   });
 
-  it('applies the default server identity when the props are omitted', () => {
+  it('applies a non-placeholder fallback server identity when the props are omitted', () => {
     const { template } = makeTemplate();
     expect(
       findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
-    ).toBe('irc.example.com');
+    ).toBe('irc.localhost');
     expect(
       findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
     ).toBe('ExampleNet');

package/apps/aws-stack/tests/synth-no-bundle.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Red→green driver for the aws-stack test-mode bundle stub.
+ *
+ * The IrcAwsStack constructs up to four `NodejsFunction` resources. Each
+ * one invokes esbuild at synth time to bundle the Lambda handler entry.
+ * Repeated across the full `apps/aws-stack` test suite, the bundler ran
+ * dozens of times per coverage invocation and exhausted CI memory before
+ * the vitest coverage table could be printed (the failure mode behind
+ * the coverage-command crash).
+ *
+ * Setting `IRC_AWS_STACK_TEST_NO_BUNDLE=1` (done once for the whole
+ * suite by `tests/vitest.setup.ts`) flips the stack onto a stub code
+ * path that emits an inline Lambda zip and skips esbuild entirely,
+ * while preserving every other CloudFormation shape the rest of the
+ * suite asserts on (runtime, env vars, IAM grants, route wiring, …).
+ *
+ * The assertions below lock that stub in place. They fail loudly the
+ * moment a refactor re-routes the stack back to `NodejsFunction` under
+ * test, or drops the env-var guard, so the coverage pipeline cannot
+ * silently regress back into an unbounded esbuild loop.
+ */
+
+import { App } from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { IrcAwsStack } from '../src/aws-stack.js';
+
+/**
+ * Collects every `AWS::Lambda::Function`'s `Code` block from a synthesized
+ * template. Under the stub each Code must be `{ ZipFile: … }` (inline) and
+ * must NOT be `{ S3Bucket: …, S3Key: … }` (the shape CDK emits only after
+ * esbuild has run).
+ */
+function lambdaCodeBlocks(template: Template): Array<Record<string, unknown>> {
+  const fns = template.findResources('AWS::Lambda::Function') as Record<
+    string,
+    { Properties?: { Code?: Record<string, unknown> } }
+  >;
+  return Object.values(fns).map((fn) => fn.Properties?.Code ?? {});
+}
+
+describe('IrcAwsStack — test-mode bundle stub (no esbuild)', () => {
+  it('emits inline (ZipFile) Lambda code for the default wss stack so esbuild is skipped', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack');
+    const template = Template.fromStack(stack);
+    const codes = lambdaCodeBlocks(template);
+    // handler + sweeper + pingChecker.
+    expect(codes).toHaveLength(3);
+    for (const code of codes) {
+      expect(code).toHaveProperty('ZipFile');
+      expect(code).not.toHaveProperty('S3Bucket');
+      expect(code).not.toHaveProperty('S3Key');
+    }
+  });
+
+  it('emits inline (ZipFile) Lambda code for the NLB streaming handler when tcpTlsDomainName is set', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      environmentName: 'staging',
+      tcpTlsDomainName: 'irc.example.com',
+    });
+    const template = Template.fromStack(stack);
+    const codes = lambdaCodeBlocks(template);
+    // handler + sweeper + pingChecker + nlbHandler.
+    expect(codes).toHaveLength(4);
+    for (const code of codes) {
+      expect(code).toHaveProperty('ZipFile');
+      expect(code).not.toHaveProperty('S3Bucket');
+    }
+  });
+
+  it('preserves the Node 24 runtime on every stubbed Lambda', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', {
+      tcpTlsDomainName: 'irc.example.com',
+    });
+    const template = Template.fromStack(stack);
+    template.allResourcesProperties('AWS::Lambda::Function', {
+      Runtime: 'nodejs24.x',
+    });
+  });
+});
+
+/**
+ * Production-path coverage. The stub above is the test-only fast path; the
+ * `NodejsFunction` branch in `makeLambda` is what every real `cdk synth`
+ * takes. Exercising it once here covers the otherwise-unreached return and
+ * asserts the production Code shape (`S3Bucket` / asset-backed) so a
+ * refactor that accidentally drops the production path fails loudly.
+ *
+ * Bounded to a single synth (one stack, no `tcpTlsDomainName`) so esbuild
+ * runs at most three times — enough to cover the branch without
+ * re-introducing the unbounded bundling loop the stub exists to dodge.
+ */
+describe('IrcAwsStack — production bundling path (no stub)', () => {
+  let savedFlag: string | undefined;
+
+  beforeEach(() => {
+    savedFlag = process.env.IRC_AWS_STACK_TEST_NO_BUNDLE;
+    process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '';
+  });
+
+  afterEach(() => {
+    if (savedFlag !== undefined) {
+      process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = savedFlag;
+    } else {
+      process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '';
+    }
+  });
+
+  it('uses NodejsFunction (S3-bundled asset) when the stub env var is unset', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack');
+    const template = Template.fromStack(stack);
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Code?: Record<string, unknown> } }
+    >;
+    const codes = Object.values(fns).map((fn) => fn.Properties?.Code ?? {});
+    expect(codes).toHaveLength(3);
+    for (const code of codes) {
+      // Production synth emits an S3-backed asset (esbuild ran). No
+      // `ZipFile` should appear on any production Lambda.
+      expect(code).toHaveProperty('S3Bucket');
+      expect(code).not.toHaveProperty('ZipFile');
+    }
+  });
+});

package/apps/aws-stack/tests/vitest.setup.ts

@@ -0,0 +1,18 @@
+/**
+ * Vitest setup for the aws-stack test suite.
+ *
+ * Runs once per test file before any test body executes. Sets the flag
+ * consumed by `makeLambda()` in `src/aws-stack.ts` to route every Lambda
+ * construct onto the inline-zip stub, so synthesizing the stack under
+ * test does NOT invoke esbuild. Without this, the ~80 stack-related
+ * tests each triggered one esbuild bundle per Lambda (4 functions × 80
+ * synths = 320+ bundles per coverage run), which exhausted CI memory
+ * before the vitest coverage table could print.
+ *
+ * The stub preserves every CloudFormation shape the rest of the suite
+ * asserts on (runtime, env vars, IAM grants, route wiring, …) while
+ * making the bundling step a no-op. Production synth (`bin/aws.ts`) is
+ * driven by `cdk synth` / the CDK CLI, never via vitest, so it cannot
+ * accidentally inherit this env var.
+ */
+process.env.IRC_AWS_STACK_TEST_NO_BUNDLE = '1';

package/apps/aws-stack/vitest.config.ts

@@ -4,6 +4,9 @@ export default defineConfig({
   test: {
     include: ['tests/**/*.test.ts'],
     exclude: ['cdk.out/**', 'dist/**', 'node_modules/**'],
+    setupFiles: ['./tests/vitest.setup.ts'],
+    testTimeout: 60_000,
+    fileParallelism: false,
     coverage: {
       provider: 'v8',
       all: false,

package/apps/cf-tcp-container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-tcp-container",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Cloudflare Container TCP origin for the irc+tls :6697 transport — Spectrum terminates TLS at the edge, this container runs the IRC core over plaintext TCP",
   "license": "BSD-3-Clause",

package/apps/cf-tcp-container/src/config-loader.ts

@@ -58,14 +58,13 @@ const DEFAULT_TCP_PORT = 6667;
 const DEFAULT_TCP_HOST = '0.0.0.0';
 const DEFAULT_SNAPSHOT_INTERVAL_MS = 60_000;
 
-/** Default server name / network when env vars are missing. */
-const DEFAULT_SERVER_NAME = 'irc.example.com';
-const DEFAULT_NETWORK_NAME = 'ExampleNet';
-
 /**
  * Loads and validates the IRC server config plus container-specific knobs
  * from a platform env. Throws on an invalid IRC config (bad port number,
- * missing required fields, etc.) so boot fails fast.
+ * missing required fields, etc.) so boot fails fast. `SERVER_NAME` and
+ * `NETWORK_NAME` are required — omitting them produces a readable error
+ * pointing at the missing knob rather than silently advertising a
+ * placeholder identity.
  */
 export function loadContainerConfig(env: ContainerConfigEnv): ContainerConfig {
   const server = parseServerConfig(buildServerInput(env));
@@ -89,8 +88,8 @@ function parseIntOrDefault(raw: string | undefined, def: number): number {
 
 function buildServerInput(env: ContainerConfigEnv): Record<string, unknown> {
   const input: Record<string, unknown> = {
-    serverName: env.SERVER_NAME ?? DEFAULT_SERVER_NAME,
-    networkName: env.NETWORK_NAME ?? DEFAULT_NETWORK_NAME,
+    serverName: env.SERVER_NAME,
+    networkName: env.NETWORK_NAME,
   };
   if (env.SERVER_VERSION !== undefined) input.serverVersion = env.SERVER_VERSION;
   if (env.CREATED_AT !== undefined) input.createdAt = parseCreatedAt(env.CREATED_AT);

package/apps/cf-tcp-container/src/container-server.ts

@@ -286,6 +286,9 @@ function attachConnection(
     history,
     logger,
     transport: new TcpByteStreamTransport(),
+    // Spectrum terminates TLS at the edge before forwarding plaintext TCP
+    // to this origin, so every connection is secure → user mode `S`.
+    secure: true,
   });
 
   runtime.registerConnection(

package/apps/cf-tcp-container/tests/config-loader.test.ts

@@ -40,9 +40,16 @@ describe('config-loader — IRC server config', () => {
     ]);
   });
 
-  it('applies schema default serverName when unset', () => {
-    const cfg = loadContainerConfig({ NETWORK_NAME: 'TestNet' } as ContainerConfigEnv);
-    expect(cfg.server.serverName).toBe('irc.example.com');
+  it('throws a readable error naming serverName when SERVER_NAME is unset', () => {
+    expect(() =>
+      loadContainerConfig({ NETWORK_NAME: 'TestNet' } as ContainerConfigEnv),
+    ).toThrowError(/serverName/u);
+  });
+
+  it('throws a readable error naming networkName when NETWORK_NAME is unset', () => {
+    expect(() =>
+      loadContainerConfig({ SERVER_NAME: 'irc.test' } as ContainerConfigEnv),
+    ).toThrowError(/networkName/u);
   });
 });
 

package/apps/cf-tcp-container/wrangler.toml

@@ -47,7 +47,7 @@ new_sqlite_classes = ["IrcTcpOrigin"]
 
 # --- Environment ---
 [vars]
-SERVER_NAME = "irc.example.com"
+SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ExampleNet"
 MOTD_LINES = "Welcome to the ServerlessIRCd TCP origin."
 TCP_PORT = "6667"

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",
@@ -27,6 +27,7 @@
     "@cloudflare/vitest-pool-workers": "0.18.6",
     "@cloudflare/workers-types": "^5.20260714.1",
     "@types/ws": "^8.5.13",
+    "@vitest/coverage-istanbul": "^4.1.0",
     "@vitest/coverage-v8": "^4.1.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",

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

@@ -5,7 +5,7 @@ export default defineConfig({
   test: {
     include: ['tests/**/*.test.ts'],
     coverage: {
-      provider: 'v8',
+      provider: 'istanbul',
       all: false,
       include: ['src/**/*.ts'],
       reporter: ['text', 'html', 'json-summary'],

package/apps/cf-worker/wrangler.toml

@@ -45,10 +45,12 @@ enabled = true
 invocation_logs = true
 
 ## 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.).
+## `SERVER_NAME` is REQUIRED — the CF config loader
+## (`loadServerConfigFromCfEnv`) fails fast at boot when it is unset.
+## Production deployments MUST override it to the public hostname
+## clients see in numerics (001, 005, etc.).
 [vars]
-SERVER_NAME = "irc.example.com"
+SERVER_NAME = "irc.your-domain.invalid"
 NETWORK_NAME = "ServerlessIRCd"
 MOTD_LINES = """
 Welcome to ServerlessIRCd.

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Runnable WebSocket IRC server using the in-memory runtime; manual-test harness and e2e fixture target",
   "license": "BSD-3-Clause",

package/apps/local-cli/src/config-loader.ts

@@ -13,14 +13,14 @@ import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc
 
 /**
  * CLI / programmatic input for `loadServerConfigFromCliArgs`. Every
- * field is optional except the two required schema fields
- * (`serverName`, `networkName`); the schema applies defaults to the
- * rest. Field types match the schema's input shape (numbers stay
- * numbers, etc.) so callers don't need to coerce strings.
+ * field is optional; the schema rejects a missing `serverName` or
+ * `networkName` with a readable error so the caller learns at boot
+ * rather than mid-session. Field types match the schema's input shape
+ * (numbers stay numbers, etc.) so callers don't need to coerce strings.
  */
 export interface CliConfigInput {
-  serverName: string;
-  networkName: string;
+  serverName?: string | undefined;
+  networkName?: string | undefined;
   /**
    * Server version surfaced in `002`/`004`/`351`/`371`. When omitted the
    * schema default ({@link DEFAULT_SERVER_VERSION}) applies.

package/apps/local-cli/src/main.ts

@@ -31,9 +31,15 @@ interface CliArgs {
   tcpPort: number | undefined;
   /** undefined when --motd-file is not given; built-in default MOTD applies. */
   motdFile: string | undefined;
+  /** Server identity shown in 001/005 numerics. */
+  serverName: string;
+  /** Network name advertised in 005 NETWORK=... */
+  networkName: string;
 }
 
 const DEFAULT_PORT = 6667;
+const DEFAULT_SERVER_NAME = 'irc.localhost';
+const DEFAULT_NETWORK_NAME = 'LocalNet';
 
 function parseArgs(argv: string[]): CliArgs {
   const out: CliArgs = {
@@ -41,6 +47,8 @@ function parseArgs(argv: string[]): CliArgs {
     hostname: '127.0.0.1',
     tcpPort: undefined,
     motdFile: undefined,
+    serverName: DEFAULT_SERVER_NAME,
+    networkName: DEFAULT_NETWORK_NAME,
   };
   let tcpDisabled = false;
   let tcpPortOverride: number | undefined;
@@ -59,6 +67,12 @@ function parseArgs(argv: string[]): CliArgs {
     } else if (a === '--motd-file' && next !== undefined) {
       out.motdFile = next;
       i++;
+    } else if (a === '--server-name' && next !== undefined) {
+      out.serverName = next;
+      i++;
+    } else if (a === '--network-name' && next !== undefined) {
+      out.networkName = next;
+      i++;
     } else if (a === '--no-tcp') {
       tcpDisabled = true;
     } else if (a === '--help' || a === '-h') {
@@ -74,6 +88,10 @@ function parseArgs(argv: string[]): CliArgs {
           '  --no-tcp           Disable the TCP listener (WebSocket only).',
           '  --motd-file <path> Read MOTD lines from this file (one per line).',
           '                     Optional; overrides the built-in default MOTD.',
+          '  --server-name <h>  Server hostname in 001/005 numerics.',
+          '                     Optional; defaults to irc.localhost for the local CLI.',
+          '  --network-name <n> Network name in 005 NETWORK=...',
+          '                     Optional; defaults to LocalNet.',
           '  -h, --help         Show this help and exit.',
           '',
         ].join('\n'),
@@ -99,6 +117,8 @@ async function main(): Promise<void> {
     port: args.port,
     hostname: args.hostname,
     tcpPort: args.tcpPort,
+    serverName: args.serverName,
+    networkName: args.networkName,
     ...(motdLines !== undefined ? { motdLines } : {}),
   });