serverless-ircd 0.5.0 → 0.6.0

package/apps/aws-stack/src/aws-stack.ts

@@ -37,8 +37,8 @@ import {
 import { LambdaTarget } from 'aws-cdk-lib/aws-elasticloadbalancingv2-targets';
 import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
 import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
-import { Runtime } from 'aws-cdk-lib/aws-lambda';
-import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { Code, Function as Lambda, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction, type NodejsFunctionProps } from 'aws-cdk-lib/aws-lambda-nodejs';
 import type { Construct } from 'constructs';
 
 /** Stage name served by the auto-deploying WebSocket stage. */
@@ -64,8 +64,14 @@ const PING_CHECKER_SCHEDULE_RATE = Duration.minutes(1);
  */
 const DEFAULT_ENVIRONMENT_NAME = 'staging';
 
-/** Default server identity, used when the corresponding prop is omitted. */
-const DEFAULT_SERVER_NAME = 'irc.example.com';
+/**
+ * Fallback server identity, used when the corresponding prop is omitted.
+ * Deliberately not `irc.example.com` (the retired placeholder) so a
+ * deployment that forgets to override advertises an obviously-local name
+ * instead of a deceptive example domain. Production stacks MUST pass
+ * `serverName` explicitly.
+ */
+const DEFAULT_SERVER_NAME = 'irc.localhost';
 const DEFAULT_NETWORK_NAME = 'ExampleNet';
 const DEFAULT_MOTD_LINES = [
   'Welcome to the ServerlessIRCd deployment.',
@@ -74,6 +80,22 @@ const DEFAULT_MOTD_LINES = [
 
 const HERE = fileURLToPath(new URL('.', import.meta.url));
 
+/**
+ * Env-var flag that flips {@link makeLambda} onto a stub code path which
+ * emits an inline Lambda zip and skips esbuild entirely. The IrcAwsStack
+ * test suite synthesizes the stack dozens of times per coverage run; if
+ * each synth invoked esbuild the runner exhausted its memory budget
+ * before the vitest coverage table could print. The stub preserves every
+ * CloudFormation shape the rest of the test suite asserts on (runtime,
+ * env vars, IAM grants, route wiring, …) while making the bundling step
+ * a no-op.
+ *
+ * Intentionally a plain `process.env` read (not a CDK context var or
+ * construct prop) so the toggle lives in one place — `tests/vitest.setup.ts`
+ * — and cannot leak into a production synth driven by `bin/aws.ts`.
+ */
+const TEST_NO_BUNDLE_FLAG = 'IRC_AWS_STACK_TEST_NO_BUNDLE';
+
 /**
  * Construct props for {@link IrcAwsStack}. Acts as the single
  * configuration bag extended by deploy-time knobs (environment name,
@@ -93,7 +115,8 @@ export interface IrcStackProps extends StackProps {
 
   /**
    * Server name advertised to clients (`SERVER_NAME` / the `001`
-   * welcome source). Defaults to `irc.example.com`.
+   * welcome source). Falls back to `irc.localhost` when omitted; production
+   * stacks MUST pass an explicit value.
    */
   readonly serverName?: string;
 
@@ -150,7 +173,7 @@ export class IrcAwsStack extends Stack {
       }),
     );
 
-    const handler = new NodejsFunction(this, 'IrcHandler', {
+    const handler = makeLambda(this, 'IrcHandler', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'handler',
@@ -166,7 +189,7 @@ export class IrcAwsStack extends Stack {
     // bundle (tree-shaken to the sweeper path by esbuild at synth time).
     // Catches connections that vanished without APIGW emitting $disconnect;
     // see packages/aws-adapter/src/handlers/sweeper.ts.
-    const sweeper = new NodejsFunction(this, 'IrcSweeper', {
+    const sweeper = makeLambda(this, 'IrcSweeper', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'sweeperHandler',
@@ -180,7 +203,7 @@ export class IrcAwsStack extends Stack {
     // those that never answer; see
     // packages/aws-adapter/src/handlers/ping-checker.ts. The Cloudflare
     // adapter implements the equivalent flow inside `ConnectionDO.alarm()`.
-    const pingChecker = new NodejsFunction(this, 'IrcPingChecker', {
+    const pingChecker = makeLambda(this, 'IrcPingChecker', {
       runtime: Runtime.NODEJS_24_X,
       entry: handlerEntry(),
       handler: 'pingCheckerHandler',
@@ -318,7 +341,7 @@ export class IrcAwsStack extends Stack {
       // Shares the bundled aws-adapter code (tree-shaken to the nlb-stream
       // path by esbuild at synth time). Reuses the same DynamoDB tables,
       // server identity, and MANAGEMENT_URL as the wss handler.
-      const nlbHandler = new NodejsFunction(this, 'IrcNlbHandler', {
+      const nlbHandler = makeLambda(this, 'IrcNlbHandler', {
         runtime: Runtime.NODEJS_24_X,
         entry: handlerEntry(),
         handler: 'nlbStreamHandler',
@@ -391,6 +414,48 @@ function handlerEntry(): string {
   return resolve(HERE, '..', '..', '..', 'packages', 'aws-adapter', 'src', 'handlers', 'index.ts');
 }
 
+/**
+ * Internal Lambda-construct props: `NodejsFunctionProps` narrowed so the
+ * runtime and handler are required. Every call site in the stack already
+ * passes both explicitly; this type just makes that invariant visible to
+ * the compiler so {@link makeLambda} can hand them straight through to
+ * the stub `Function` constructor without a non-null assertion.
+ */
+type StrictLambdaProps = NodejsFunctionProps & {
+  readonly runtime: Runtime;
+  readonly handler: string;
+};
+
+/**
+ * Builds a Lambda function for the IRC stack, selecting between the real
+ * esbuild-bundled `NodejsFunction` and a no-op stub `Function` based on
+ * {@link TEST_NO_BUNDLE_FLAG}.
+ *
+ * Production synth (`bin/aws.ts`) never sets the flag, so it always lands
+ * on the `NodejsFunction` branch and produces a real bundled asset. The
+ * test suite sets the flag via `tests/vitest.setup.ts`, which routes
+ * every Lambda onto the inline-zip stub so the synth does not invoke
+ * esbuild and the coverage pipeline can complete.
+ *
+ * The stub mirrors only the fields the rest of the stack mutates
+ * post-construction (`runtime`, `handler`, env vars, IAM grants) — it
+ * deliberately ignores `entry` and `bundling` because both are
+ * meaningless once esbuild is bypassed.
+ *
+ * Returns the base `Function` type (not `NodejsFunction`) so callers
+ * cannot reach for bundler-only APIs on the stub path.
+ */
+function makeLambda(scope: Construct, id: string, props: StrictLambdaProps): Lambda {
+  if (process.env[TEST_NO_BUNDLE_FLAG] === '1') {
+    return new Lambda(scope, id, {
+      runtime: props.runtime,
+      handler: props.handler,
+      code: Code.fromInline('void 0'),
+    });
+  }
+  return new NodejsFunction(scope, id, props);
+}
+
 /**
  * Builds the physical DynamoDB table name for a logical id under the
  * given environment. Capitalises the environment's first letter so it

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

@@ -483,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.5.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.5.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.5.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.