serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,464 @@
+/**
+ * Synth-time assertions for the `apps/aws-stack` CDK stack.
+ *
+ * These are the primary red→green tests for the infrastructure ticket:
+ * they assert the exact CloudFormation shape that `cdk synth` must
+ * produce — five DynamoDB tables with the PLAN §4 schema, a single
+ * Node 20 Lambda wired to all three WebSocket routes, the API Gateway
+ * v2 WebSocket API, the two stack outputs, and a least-privilege guard
+ * that no IAM policy grants `Resource: '*'` or `Action: '*'`.
+ *
+ * The assertions run against `Template.fromStack`, which executes the
+ * CDK synthesis in-process — no AWS credentials and no Docker required.
+ * The separately-gated `localstack.test.ts` covers the deploy-time
+ * contract against a real localstack container.
+ */
+
+import { App, type Stack } from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { describe, expect, it } from 'vitest';
+import { IrcAwsStack } from '../src/aws-stack.js';
+
+/** All five table names that must exist in the stack (PLAN §4). */
+const TABLE_NAMES = ['Accounts', 'ChannelMembers', 'ChannelMeta', 'Connections', 'Nicks'] as const;
+
+/** Default environment name assumed when the prop is omitted. */
+const DEFAULT_ENV = 'staging';
+
+/**
+ * Capitalises the first character of an environment name so it composes
+ * cleanly with the PascalCase logical table ids (`staging` → `Staging`).
+ */
+function prefixedTableName(environmentName: string, logicalId: string): string {
+  return `${environmentName.charAt(0).toUpperCase()}${environmentName.slice(1)}${logicalId}`;
+}
+
+function makeTemplate(environmentName?: string): { app: App; stack: Stack; template: Template } {
+  const app = new App();
+  const stack = new IrcAwsStack(
+    app,
+    'TestStack',
+    environmentName !== undefined ? { environmentName } : undefined,
+  );
+  const template = Template.fromStack(stack);
+  return { app, stack, template };
+}
+
+describe('IrcAwsStack — DynamoDB tables', () => {
+  it('creates exactly five DynamoDB tables', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::DynamoDB::Table', 5);
+  });
+
+  it.each(TABLE_NAMES)('creates the %s table', (tableName) => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, tableName),
+    });
+  });
+
+  it('configures every table for on-demand (PAY_PER_REQUEST) billing', () => {
+    const { template } = makeTemplate();
+    template.allResourcesProperties('AWS::DynamoDB::Table', {
+      BillingMode: 'PAY_PER_REQUEST',
+    });
+  });
+
+  it('enables TTL on the Connections table via the idleSince attribute', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
+      TimeToLiveSpecification: {
+        AttributeName: 'idleSince',
+        Enabled: true,
+      },
+    });
+  });
+
+  it('keys the Connections table by connectionId (String)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
+      AttributeDefinitions: [{ AttributeName: 'connectionId', AttributeType: 'S' }],
+      KeySchema: [{ AttributeName: 'connectionId', KeyType: 'HASH' }],
+    });
+  });
+
+  it('keys the ChannelMembers table by channelName (PK) + connectionId (SK)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'ChannelMembers'),
+      AttributeDefinitions: [
+        { AttributeName: 'channelName', AttributeType: 'S' },
+        { AttributeName: 'connectionId', AttributeType: 'S' },
+      ],
+      KeySchema: [
+        { AttributeName: 'channelName', KeyType: 'HASH' },
+        { AttributeName: 'connectionId', KeyType: 'RANGE' },
+      ],
+    });
+  });
+
+  it('keys the ChannelMeta table by channelName (String)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'ChannelMeta'),
+      AttributeDefinitions: [{ AttributeName: 'channelName', AttributeType: 'S' }],
+      KeySchema: [{ AttributeName: 'channelName', KeyType: 'HASH' }],
+    });
+  });
+
+  it('keys the Nicks table by nickLower (String)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Nicks'),
+      AttributeDefinitions: [{ AttributeName: 'nickLower', AttributeType: 'S' }],
+      KeySchema: [{ AttributeName: 'nickLower', KeyType: 'HASH' }],
+    });
+  });
+
+  it('keys the Accounts table by account (String)', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Accounts'),
+      AttributeDefinitions: [{ AttributeName: 'account', AttributeType: 'S' }],
+      KeySchema: [{ AttributeName: 'account', KeyType: 'HASH' }],
+    });
+  });
+});
+
+describe('IrcAwsStack — API Gateway v2 WebSocket API', () => {
+  it('creates a WebSocket protocol API Gateway v2 API', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+      ProtocolType: 'WEBSOCKET',
+    });
+  });
+
+  it.each(['$connect', '$disconnect', '$default'] as const)(
+    'wires the %s route to the Lambda integration',
+    (routeKey) => {
+      const { template } = makeTemplate();
+      template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+        RouteKey: routeKey,
+      });
+    },
+  );
+
+  it('creates exactly three routes', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::ApiGatewayV2::Route', 3);
+  });
+});
+
+describe('IrcAwsStack — Lambda', () => {
+  it('creates exactly three Lambda functions (handler + sweeper + pingChecker)', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::Lambda::Function', 3);
+  });
+
+  it('targets the Node 20 runtime for every function', () => {
+    const { template } = makeTemplate();
+    template.allResourcesProperties('AWS::Lambda::Function', {
+      Runtime: 'nodejs20.x',
+    });
+  });
+});
+
+describe('IrcAwsStack — gone-connection sweeper', () => {
+  it('creates an EventBridge rule on a fixed schedule targeting the sweeper', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::Events::Rule', {
+      ScheduleExpression: 'rate(5 minutes)',
+    });
+  });
+
+  it('wires the sweeper Lambda as an EventBridge target', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::Events::Rule', {
+      ScheduleExpression: 'rate(5 minutes)',
+    });
+    // EventBridge needs permission to invoke each scheduled target. APIGW
+    // also creates one permission per route ($connect/$disconnect/$default),
+    // so the total is 5: 3 APIGW + 2 EventBridge (sweeper + pingChecker).
+    template.hasResourceProperties('AWS::Lambda::Permission', {
+      Principal: 'events.amazonaws.com',
+    });
+  });
+
+  it('grants the sweeper read/delete on every DynamoDB table (no wildcards)', () => {
+    const { template } = makeTemplate();
+    // Both Lambda roles must scope their DynamoDB actions to the concrete
+    // table ARNs — the least-privilege suite below also asserts no '*'.
+    const tables = template.findResources('AWS::DynamoDB::Table');
+    expect(Object.keys(tables)).toHaveLength(5);
+  });
+});
+
+describe('IrcAwsStack — idle / PING checker', () => {
+  it('creates an EventBridge rule firing every 1 minute', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::Events::Rule', {
+      ScheduleExpression: 'rate(1 minute)',
+    });
+  });
+
+  it('creates exactly two EventBridge rules (sweeper + pingChecker)', () => {
+    const { template } = makeTemplate();
+    template.resourceCountIs('AWS::Events::Rule', 2);
+  });
+
+  it('grants the ping checker Lambda management-api access on the stage', () => {
+    // The CDK wires execute-api:ManageConnections via
+    // `stage.grantManagementApiAccess(pingChecker)`. We assert the
+    // resource pattern scoping the policy to this API's stage.
+    const { template } = makeTemplate();
+    const policies = template.findResources('AWS::IAM::Policy');
+    let found = false;
+    for (const [, policy] of Object.entries(policies)) {
+      const stmts = (policy as { Properties: { PolicyDocument: { Statement: unknown[] } } })
+        .Properties.PolicyDocument.Statement;
+      for (const stmt of stmts) {
+        const action = (stmt as { Action?: unknown }).Action;
+        const matchesAction =
+          action === 'execute-api:ManageConnections' ||
+          (Array.isArray(action) && action.includes('execute-api:ManageConnections'));
+        if (matchesAction) {
+          found = true;
+        }
+      }
+    }
+    expect(found, 'ping checker must be granted execute-api:ManageConnections').toBe(true);
+  });
+
+  it('forwards the MANAGEMENT_URL env var to the ping checker so it can PING clients', () => {
+    // The $default handler AND the ping checker both need MANAGEMENT_URL
+    // (the sweeper does not). Walk every Lambda function and confirm
+    // at least two carry the env var — combined with the 3-function
+    // count above this locks the wiring in place.
+    const { template } = makeTemplate();
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Environment?: { Variables?: Record<string, string> } } }
+    >;
+    const withMgmt = Object.values(fns).filter(
+      (fn) => fn.Properties?.Environment?.Variables?.MANAGEMENT_URL !== undefined,
+    );
+    expect(withMgmt.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe('IrcAwsStack — stack outputs', () => {
+  it('emits a ConnectUrl output', () => {
+    const { template } = makeTemplate();
+    const outputs = template.toJSON().Outputs ?? {};
+    expect(outputs).toHaveProperty('ConnectUrl');
+  });
+
+  it('emits a ManagementUrl output', () => {
+    const { template } = makeTemplate();
+    const outputs = template.toJSON().Outputs ?? {};
+    expect(outputs).toHaveProperty('ManagementUrl');
+  });
+});
+
+describe('IrcAwsStack — least-privilege IAM', () => {
+  it('never grants Action: "*" in any IAM policy', () => {
+    const { template } = makeTemplate();
+    const policies = template.findResources('AWS::IAM::Policy');
+    for (const [, policy] of Object.entries(policies)) {
+      const statements = (policy as { Properties: { PolicyDocument: { Statement: unknown[] } } })
+        .Properties.PolicyDocument.Statement;
+      for (const stmt of statements) {
+        const action = (stmt as { Action?: unknown }).Action;
+        if (Array.isArray(action)) {
+          expect(
+            action,
+            `policy ${JSON.stringify(policy)} must not grant Action '*'`,
+          ).not.toContain('*');
+        } else {
+          expect(action, `policy ${JSON.stringify(policy)} must not grant Action '*'`).not.toBe(
+            '*',
+          );
+        }
+      }
+    }
+  });
+
+  it('never grants Resource: "*" in any IAM policy', () => {
+    const { template } = makeTemplate();
+    const policies = template.findResources('AWS::IAM::Policy');
+    for (const [, policy] of Object.entries(policies)) {
+      const statements = (policy as { Properties: { PolicyDocument: { Statement: unknown[] } } })
+        .Properties.PolicyDocument.Statement;
+      for (const stmt of statements) {
+        const resource = (stmt as { Resource?: unknown }).Resource;
+        if (Array.isArray(resource)) {
+          expect(
+            resource,
+            `policy ${JSON.stringify(policy)} must not grant Resource '*'`,
+          ).not.toContain('*');
+        } else {
+          expect(resource, `policy ${JSON.stringify(policy)} must not grant Resource '*'`).not.toBe(
+            '*',
+          );
+        }
+      }
+    }
+  });
+});
+
+describe('IrcAwsStack — environmentName prop (env isolation)', () => {
+  it('prefixes the Connections table name with the production environment', () => {
+    const { template } = makeTemplate('production');
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: 'ProductionConnections',
+    });
+  });
+
+  it('prefixes the Connections table name with the staging environment', () => {
+    const { template } = makeTemplate('staging');
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: 'StagingConnections',
+    });
+  });
+
+  it('defaults to the staging prefix when the prop is omitted', () => {
+    const { template } = makeTemplate();
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      TableName: prefixedTableName(DEFAULT_ENV, 'Connections'),
+    });
+  });
+
+  it('injects the prefixed physical table name into every Lambda env var', () => {
+    const { template } = makeTemplate('production');
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Environment?: { Variables?: Record<string, string> } } }
+    >;
+    // Every Lambda must carry CONNECTIONS_TABLE pointing at the production-prefixed name.
+    const withPrefixed = Object.values(fns).filter(
+      (fn) => fn.Properties?.Environment?.Variables?.CONNECTIONS_TABLE === 'ProductionConnections',
+    );
+    expect(withPrefixed).toHaveLength(3);
+  });
+
+  it('produces non-colliding table names for staging vs production', () => {
+    const stagingTables = Object.keys(
+      makeTemplate('staging').template.findResources('AWS::DynamoDB::Table'),
+    );
+    const prodTables = Object.keys(
+      makeTemplate('production').template.findResources('AWS::DynamoDB::Table'),
+    );
+    const stagingNames = new Set(
+      Object.values(
+        makeTemplate('staging').template.findResources('AWS::DynamoDB::Table') as Record<
+          string,
+          { Properties: { TableName: string } }
+        >,
+      ).map((t) => t.Properties.TableName),
+    );
+    const prodNames = Object.values(
+      makeTemplate('production').template.findResources('AWS::DynamoDB::Table') as Record<
+        string,
+        { Properties: { TableName: string } }
+      >,
+    ).map((t) => t.Properties.TableName);
+    expect(stagingTables).toHaveLength(5);
+    expect(prodTables).toHaveLength(5);
+    expect(prodNames.every((n) => !stagingNames.has(n))).toBe(true);
+  });
+
+  it('includes the environment suffix in the CloudFormation stack name', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'IrcAwsStack-production', {
+      environmentName: 'production',
+    });
+    expect(stack.stackName).toBe('IrcAwsStack-production');
+  });
+});
+
+describe('IrcAwsStack — server identity props (configurable deploy identity)', () => {
+  /** Finds a Lambda function resource by its logical-id prefix (e.g. `IrcHandler`). */
+  function findFunction(
+    template: Template,
+    idPrefix: string,
+  ): {
+    Properties?: { Environment?: { Variables?: Record<string, string> } };
+  } {
+    const fns = template.findResources('AWS::Lambda::Function') as Record<
+      string,
+      { Properties?: { Environment?: { Variables?: Record<string, string> } } }
+    >;
+    const found = Object.entries(fns).find(([id]) => id.startsWith(idPrefix));
+    if (!found) {
+      throw new Error(`No Lambda with logical id starting with "${idPrefix}"`);
+    }
+    return found[1];
+  }
+
+  it('injects an overridden serverName into the handler Lambda env', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { serverName: 'irc.my.net' });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toBe('irc.my.net');
+  });
+
+  it('flows the overridden serverName into the pingChecker Lambda env', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { serverName: 'irc.my.net' });
+    const template = Template.fromStack(stack);
+    // Catches the previously duplicated hard-coded copy on IrcPingChecker.
+    expect(
+      findFunction(template, 'IrcPingChecker').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toBe('irc.my.net');
+  });
+
+  it('injects an overridden networkName into both handler and pingChecker', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { networkName: 'MyNet' });
+    const template = Template.fromStack(stack);
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
+    ).toBe('MyNet');
+    expect(
+      findFunction(template, 'IrcPingChecker').Properties?.Environment?.Variables?.NETWORK_NAME,
+    ).toBe('MyNet');
+  });
+
+  it('joins motdLines with newline so the config loader splits them into separate lines', () => {
+    const app = new App();
+    const stack = new IrcAwsStack(app, 'TestStack', { motdLines: ['line one', 'line two'] });
+    const template = Template.fromStack(stack);
+    expect(findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD).toBe(
+      'line one\nline two',
+    );
+  });
+
+  it('applies the default server identity when the props are omitted', () => {
+    const { template } = makeTemplate();
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toBe('irc.example.com');
+    expect(
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.NETWORK_NAME,
+    ).toBe('ExampleNet');
+  });
+
+  it('default MOTD is newline-joined so the loader yields multiple lines (no comma)', () => {
+    const { template } = makeTemplate();
+    const motd =
+      findFunction(template, 'IrcHandler').Properties?.Environment?.Variables?.MOTD ?? '';
+    expect(motd.split('\n').length).toBeGreaterThanOrEqual(2);
+    expect(motd).not.toContain(',');
+  });
+
+  it('does not inject server identity into the sweeper Lambda', () => {
+    const { template } = makeTemplate();
+    expect(
+      findFunction(template, 'IrcSweeper').Properties?.Environment?.Variables?.SERVER_NAME,
+    ).toBeUndefined();
+  });
+});

package/apps/aws-stack/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"]
+}

package/apps/aws-stack/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "bin/**/*.ts"],
+  "exclude": ["dist"]
+}

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

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

package/apps/cf-worker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-worker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "Cloudflare Worker deploy glue: WebSocket edge entry point + DO bindings + wrangler pipeline",
   "license": "BSD-3-Clause",

package/apps/cf-worker/wrangler.toml

@@ -23,6 +23,27 @@ main = "src/worker.ts"
 compatibility_date = "2024-11-01"
 compatibility_flags = ["nodejs_compat"]
 
+## ---------------------------------------------------------------------------
+## Observability.
+## ---------------------------------------------------------------------------
+## `observability` enables Workers Analytics: every `console.*` call the
+## `ConnectionActor` emits via `ConsoleLogger` (one JSON line per record,
+## stamped with `traceId` + `connectionId`) is streamed into the Workers
+## Observability pipeline. Tail the live feed with `wrangler tail`, build
+## dashboards on the Workers Analytics tab, or export via Logpush.
+## The structured `msg` field names below (`frame.receive`, `dispatch`,
+## `dispatch.error`, `frame.parse-error`) are the canonical query keys.
+[observability]
+enabled = true
+## `head_sampling_rate` keeps 100% of console output — valuable during v1
+## and consistent with the per-frame traceId scheme (every request is
+## uniquely identifiable). Lower this (e.g. 0.1) once traffic grows.
+head_sampling_rate = 1
+
+[observability.logs]
+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.).
@@ -40,6 +61,10 @@ MOTD_LINES = "Welcome to ServerlessIRCd.\nThis is a deployed Cloudflare Worker."
 [env.staging]
 name = "serverless-ircd-staging"
 
+[env.staging.observability]
+enabled = true
+head_sampling_rate = 1
+
 [env.staging.vars]
 SERVER_NAME = "irc-staging.example.com"
 NETWORK_NAME = "ServerlessIRCd (staging)"

package/apps/local-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/local-cli",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -0,0 +1,56 @@
+/**
+ * Local-cli config loader.
+ *
+ * Both adapters (Cloudflare Workers via `loadServerConfigFromCfEnv`, and
+ * this local harness via `loadServerConfigFromCliArgs`) consume the
+ * single `ServerConfigSchema` shipped from `irc-core`. The local-cli
+ * accepts already-typed values (no env-string coercion needed) and
+ * validates them through the shared schema so misconfigurations are
+ * surfaced at boot rather than mid-session.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * 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.
+ */
+export interface CliConfigInput {
+  serverName: string;
+  networkName: string;
+  motdLines?: string[];
+  channelPrefixes?: string;
+  maxClients?: number;
+  operCreds?: Array<{ user: string; password: string }>;
+  maxChannelsPerUser?: number;
+  maxTargetsPerCommand?: number;
+  maxListEntries?: number;
+  nickLen?: number;
+  channelLen?: number;
+  topicLen?: number;
+  quitMessage?: string;
+}
+
+/**
+ * Validates CLI-supplied config against the shared
+ * {@link ServerConfigSchema} from `irc-core`.
+ *
+ * Throws a single readable `Error` listing every invalid field if the
+ * input fails validation. Adapters MUST call this once at boot —
+ * `startLocalServer` already calls it via its options normalisation.
+ */
+export function loadServerConfigFromCliArgs(input: CliConfigInput): ParsedServerConfig {
+  return parseServerConfig(stripUndefined(input));
+}
+
+/** Returns a shallow copy of `obj` with `undefined` values dropped. */
+function stripUndefined(obj: CliConfigInput): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}