serverless-ircd 0.8.0 → 0.10.0

package/apps/web/tests/build-env.test.ts

@@ -1,28 +1,40 @@
 import { describe, expect, it } from 'vitest';
-import { DEFAULT_CONFIG_FILE, ENV_TO_CONFIG_FILE, resolveConfigFile } from '../src/build-env';
+import {
+  DEFAULT_CONFIG_FILE,
+  ENV_TO_CONFIG_FILE,
+  hasUnsubstitutedPlaceholder,
+  parseApiUrlForKiwi,
+  resolveApiUrl,
+  resolveConfigFile,
+} from '../src/build-env';
 
 // ============================================================================
 // resolveConfigFile — per-env config selection
 // ============================================================================
 
 describe('resolveConfigFile', () => {
-  it('selects config.staging.json for --env staging', () => {
-    const result = resolveConfigFile(['--env', 'staging']);
-    expect(result.file).toBe('config.staging.json');
-    expect(result.env).toBe('staging');
-  });
-
   it('selects config.prod.json for --env prod', () => {
     const result = resolveConfigFile(['--env', 'prod']);
     expect(result.file).toBe('config.prod.json');
     expect(result.env).toBe('prod');
   });
 
-  it('falls back to the default config (staging target) when --env is absent', () => {
+  // AWS deploys the WebSocket endpoint as a separate API Gateway URL, so the
+  // AWS SPA build needs its own per-env config (`config.prod-aws.json`) baked
+  // into dist/webclient/static/config.json. The `prod-aws` env name matches
+  // the historical staging/prod split nomenclature (now collapsed); see the
+  // build-env.ts docstring.
+  it('selects config.prod-aws.json for --env prod-aws', () => {
+    const result = resolveConfigFile(['--env', 'prod-aws']);
+    expect(result.file).toBe('config.prod-aws.json');
+    expect(result.env).toBe('prod-aws');
+  });
+
+  it('falls back to the default config when --env is absent', () => {
     const result = resolveConfigFile([]);
     expect(result.file).toBe(DEFAULT_CONFIG_FILE);
     expect(result.file).toBe('config.json');
-    expect(result.env).toBe('default (staging)');
+    expect(result.env).toBe('default');
   });
 
   it('throws on an unknown --env value', () => {
@@ -36,6 +48,15 @@ describe('resolveConfigFile', () => {
     expect(() => resolveConfigFile(['--env', 'stg'])).toThrowError(/Unknown --env value: stg/u);
   });
 
+  it('rejects staging (no longer a recognised env)', () => {
+    // staging was collapsed into the single prod target; the config file
+    // and the ENV_TO_CONFIG_FILE entry are gone, so --env staging must
+    // throw like any other unknown value.
+    expect(() => resolveConfigFile(['--env', 'staging'])).toThrowError(
+      /Unknown --env value: staging/u,
+    );
+  });
+
   it('names the accepted env values in the error message', () => {
     try {
       resolveConfigFile(['--env', 'nope']);
@@ -61,3 +82,183 @@ describe('resolveConfigFile', () => {
     expect(result.file).toBe(DEFAULT_CONFIG_FILE);
   });
 });
+
+// ============================================================================
+// resolveApiUrl — stack-output URL override (`--api-url` flag)
+// ============================================================================
+//
+// The AWS web deploy pipeline reads the deployed stack's `ConnectUrl` output
+// (the API Gateway WebSocket URL) and forwards it to the SPA build via
+// `--api-url`, so the baked `config.json` `startupOptions.server` carries
+// the real wss URL instead of the `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`
+// template baked into `static/config.prod-aws.json`. No hardcoded URLs
+// live in the repo: the URL is read from CloudFormation outputs at deploy
+// time and threaded through this flag.
+
+describe('resolveApiUrl', () => {
+  it('returns the value following --api-url', () => {
+    expect(resolveApiUrl(['--api-url', 'wss://abc.execute-api.us-east-1.amazonaws.com/prod'])).toBe(
+      'wss://abc.execute-api.us-east-1.amazonaws.com/prod',
+    );
+  });
+
+  it('returns undefined when --api-url is absent', () => {
+    expect(resolveApiUrl([])).toBeUndefined();
+    expect(resolveApiUrl(['--env', 'prod-aws'])).toBeUndefined();
+  });
+
+  it('returns undefined when --api-url has no following value', () => {
+    // Trailing `--api-url` with no value: indexOf + 1 yields `undefined`,
+    // which the caller treats as "not supplied".
+    expect(resolveApiUrl(['--api-url'])).toBeUndefined();
+  });
+
+  it('coexists with --env on the same argv', () => {
+    // The deploy pipeline invokes the build with both flags at once:
+    //   pnpm --filter web run build:prod-aws -- --api-url <url>
+    // resolves to `node scripts/build.mjs --env prod-aws --api-url <url>`.
+    const argv = ['--env', 'prod-aws', '--api-url', 'wss://example'];
+    expect(resolveApiUrl(argv)).toBe('wss://example');
+    expect(resolveConfigFile(argv).file).toBe('config.prod-aws.json');
+  });
+});
+
+// ============================================================================
+// hasUnsubstitutedPlaceholder — guard against shipping a broken baked config
+// ============================================================================
+//
+// The placeholder guard prevents the AWS deploy pipeline from shipping a
+// prod-aws config that still carries `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`
+// (which would produce a broken SPA dialling a literal `{{API_ID}}...` URL).
+// It is scoped to the prod-aws env only — the CF envs (`default`, `prod`)
+// intentionally use Kiwi's `{{hostname}}` runtime template, which is
+// resolved by Kiwi in the browser at load time and must survive the bake.
+// A regression that applied the guard to the CF envs would break every
+// default `pnpm build` and every `build:prod`.
+
+describe('hasUnsubstitutedPlaceholder', () => {
+  it('returns false for the default env with a {{hostname}} runtime template (CF dev config)', () => {
+    // This is the regression that broke `pnpm build` after the initial
+    // T167 placeholder guard: the check fired on {{hostname}}, treating
+    // it as an unsubstituted AWS placeholder. {{hostname}} is a Kiwi
+    // runtime template resolved at browser load time and must survive.
+    const baked = JSON.stringify({
+      startupOptions: { server: '{{hostname}}', tls: true, port: 443 },
+    });
+    expect(hasUnsubstitutedPlaceholder(baked, 'default')).toBe(false);
+  });
+
+  it('returns false for the prod env with a {{hostname}} runtime template (CF prod config)', () => {
+    const baked = JSON.stringify({
+      startupOptions: { server: '{{hostname}}', tls: true, port: 443 },
+    });
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod')).toBe(false);
+  });
+
+  it('returns true for the prod-aws env with unsubstituted {{API_ID}}/{{REGION}}/{{STAGE}}', () => {
+    const baked = JSON.stringify({
+      startupOptions: {
+        server: 'wss://{{API_ID}}.execute-api.{{REGION}}.amazonaws.com/{{STAGE}}',
+        tls: true,
+        port: 443,
+      },
+    });
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod-aws')).toBe(true);
+  });
+
+  it('returns false for the prod-aws env after --api-url substitution', () => {
+    const baked = JSON.stringify({
+      startupOptions: {
+        server: 'wss://abc123.execute-api.us-east-1.amazonaws.com/prod',
+        tls: true,
+        port: 443,
+      },
+    });
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod-aws')).toBe(false);
+  });
+
+  it('still rejects a {{hostname}}-only payload in the prod-aws env (defensive — AWS does not use the runtime template)', () => {
+    // prod-aws config carries literal wss:// + AWS placeholders, never
+    // {{hostname}}. If somehow {{hostname}} ended up in a prod-aws bake,
+    // the guard would catch it — better to fail loudly than ship a
+    // browser-resolved hostname on the AWS path where the wss endpoint
+    // is on a different origin.
+    const baked = JSON.stringify({ startupOptions: { server: '{{hostname}}' } });
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod-aws')).toBe(true);
+  });
+
+  it('returns false for any env when the baked payload has no placeholder at all', () => {
+    const baked = JSON.stringify({ startupOptions: { server: 'wss://concrete.example.com' } });
+    expect(hasUnsubstitutedPlaceholder(baked, 'default')).toBe(false);
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod')).toBe(false);
+    expect(hasUnsubstitutedPlaceholder(baked, 'prod-aws')).toBe(false);
+  });
+});
+
+// ============================================================================
+// parseApiUrlForKiwi — split a wss:// URL into Kiwi's server + direct_path
+// ============================================================================
+//
+// irc-framework builds the WS URL as `wss://<server>:<port><direct_path>`,
+// prepending the `wss://` scheme itself whenever `tls: true`. The AWS
+// deploy pipeline's `--api-url` therefore cannot pass the full URL through
+// to `server` — that would produce a doubled-scheme URL like
+// `wss://wss//<host>...`. The helper splits the stack-output URL into the
+// two fields Kiwi actually wants: a hostname-only `server` and a
+// stage-name `direct_path`.
+
+describe('parseApiUrlForKiwi', () => {
+  it('splits a wss:// URL with a stage path into server + direct_path', () => {
+    const r = parseApiUrlForKiwi('wss://abc.execute-api.us-east-1.amazonaws.com/prod');
+    expect(r.server).toBe('abc.execute-api.us-east-1.amazonaws.com');
+    expect(r.directPath).toBe('/prod');
+  });
+
+  it('returns direct_path undefined when the URL path is / (CF Worker root case)', () => {
+    const r = parseApiUrlForKiwi('wss://worker.example.com/');
+    expect(r.server).toBe('worker.example.com');
+    expect(r.directPath).toBeUndefined();
+  });
+
+  it('returns direct_path undefined when the URL has no path', () => {
+    const r = parseApiUrlForKiwi('wss://worker.example.com');
+    expect(r.server).toBe('worker.example.com');
+    expect(r.directPath).toBeUndefined();
+  });
+
+  it('accepts a ws:// (insecure) URL', () => {
+    // Local dev / testing only; the prod build always carries wss://. The
+    // helper still splits it so the build script does not need to know the
+    // scheme in advance.
+    const r = parseApiUrlForKiwi('ws://localhost:8787/dev');
+    expect(r.server).toBe('localhost');
+    expect(r.directPath).toBe('/dev');
+  });
+
+  it('strips the port into neither server nor direct_path (Kiwi reads `port` separately)', () => {
+    // The deploy pipeline sets `port` to 443 via the template; the URL's
+    // explicit `:443` is dropped during the split. irc-framework re-adds
+    // it from the `port` field at WS construction time.
+    const r = parseApiUrlForKiwi('wss://host.example.com:8443/stage');
+    expect(r.server).toBe('host.example.com');
+    expect(r.directPath).toBe('/stage');
+  });
+
+  it('throws when the URL has no wss:// or ws:// scheme', () => {
+    expect(() => parseApiUrlForKiwi('abc.execute-api.us-east-1.amazonaws.com/prod')).toThrowError(
+      /must be a wss:\/\/ \(or ws:\/\/\) URL/u,
+    );
+  });
+
+  it('throws on a https:// URL (wrong scheme)', () => {
+    expect(() => parseApiUrlForKiwi('https://example.com/prod')).toThrowError(
+      /must be a wss:\/\/ \(or ws:\/\/\) URL/u,
+    );
+  });
+
+  it('throws on an unparseable URL', () => {
+    // `new URL('wss://')` does not throw, but a hostname with invalid
+    // chars does. Pick a value the URL parser rejects outright.
+    expect(() => parseApiUrlForKiwi('wss://<<>>/prod')).toThrowError();
+  });
+});

package/apps/web/tests/build-smoke.test.ts

@@ -10,8 +10,8 @@ const indexPath = path.join(appDist, 'index.html');
 const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
 const landingDist = path.join(pkgRoot, 'dist', 'index.html');
 
-// Validates the output of `pnpm --filter web build` (or `build:staging` /
-// `build:prod`). Skipped until the SPA has been built (the Kiwi upstream
+// Validates the output of `pnpm --filter web build` (or `build:prod`).
+// Skipped until the SPA has been built (the Kiwi upstream
 // build is too heavy to run inside the test suite); run the build first to
 // exercise these assertions.
 const built = existsSync(indexPath);
@@ -70,9 +70,9 @@ describe('landing page source (landing/index.html)', () => {
     expect(html).toMatch(/href=["']\/webclient\/?["']/);
   });
 
-  it('does not link to the project docs (docs button temporarily removed)', () => {
+  it('links to the rendered project docs at /docs/', () => {
     const html = readFileSync(landingSrc, 'utf8');
-    expect(html).not.toMatch(/href=["'][^"']*docs\/?["']/);
+    expect(html).toMatch(/href=["']\/docs\/?["']/);
   });
 
   it('links to the source repository on Gitea', () => {
@@ -101,3 +101,32 @@ describe.skipIf(!landingBuilt)('landing page build output (dist/index.html)', ()
     expect(dist).toBe(src);
   });
 });
+
+// Validates the docs/ build pass: `pnpm --filter web build` renders every
+// `docs/*.md` to standalone HTML under `dist/docs/` so the Worker `[assets]`
+// binding serves them at `/docs/<name>.html` (and `/docs/` for the index).
+// Gated on the directory's presence — like the Kiwi SPA gate above — so CI
+// can run this test file without paying the heavy SPA build cost; the
+// pipeline runs in full via `apps/web/tests/render-docs.test.ts`.
+const docsDist = path.join(pkgRoot, 'dist', 'docs');
+const docsBuilt = existsSync(docsDist) && statSync(docsDist).size > 0;
+
+describe.skipIf(!docsBuilt)('docs build output (dist/docs/)', () => {
+  it('emits dist/docs/index.html', () => {
+    expect(existsSync(path.join(docsDist, 'index.html'))).toBe(true);
+  });
+
+  it('emits Services.html with rendered HTML (an <h1>, not raw markdown)', () => {
+    const target = path.join(docsDist, 'Services.html');
+    expect(existsSync(target)).toBe(true);
+    const html = readFileSync(target, 'utf8');
+    expect(html).toMatch(/<h1[^>]*>/);
+    // The markdown H1 marker must not survive rendering.
+    expect(html).not.toMatch(/^# IRC Services Reference/m);
+  });
+
+  it('shares a stylesheet (a .css file is emitted alongside the HTML)', () => {
+    const css = readdirSync(docsDist).filter((f) => f.endsWith('.css'));
+    expect(css.length).toBeGreaterThanOrEqual(1);
+  });
+});

package/apps/web/tests/config-schema.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
+import { resolveConfigFile } from '../src/build-env';
 import { KiwiConfigSchema, parseKiwiConfig } from '../src/config-schema';
 
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -240,23 +241,21 @@ describe('KiwiConfigSchema — direct WebSocket mode', () => {
 //
 // NOTE: Kiwi reads `startupOptions.direct_path`, NOT `startupOptions.path`
 // (upstream `src/helpers/Misc.js:139`: `connection.direct_path = config.direct_path || ''`).
-// The Worker accepts WS upgrades at `/` (root), so `direct_path` — when
-// supplied — MUST be `/`. It is optional: an empty/absent value lets
-// irc-framework build `wss://host:port` with no path, which the browser
-// normalises to `wss://host:port/` and the Worker accepts.
+//
+// Two valid shapes:
+//   - CF Worker: WS upgrade is at root, so `direct_path` is `/` (or absent).
+//   - AWS API Gateway: the WebSocket endpoint URL includes the stage name as
+//     a path segment (`wss://<id>.execute-api.<region>.amazonaws.com/prod`),
+//     so `direct_path` MUST be `/<stage>` (e.g. `/prod`). irc-framework
+//     builds the WS URL as `wss://<server>:<port><direct_path>`.
+//
+// The constraint accepts a leading-slash plus zero or one path segment
+// (no nested paths), allowing alphanumeric stage names and the
+// `{{STAGE}}` placeholder baked into `config.prod-aws.json` for the
+// deploy pipeline to substitute.
 
 describe('KiwiConfigSchema — WS path (direct_path)', () => {
-  it('rejects a direct_path other than / (WS endpoint is at root)', () => {
-    expect(() =>
-      parseKiwiConfig(
-        validConfig({
-          startupOptions: validStartupOptions({ direct_path: '/webclient/' }),
-        }),
-      ),
-    ).toThrowError(/direct_path/u);
-  });
-
-  it('accepts the / direct_path', () => {
+  it('accepts the / direct_path (CF Worker — WS upgrade at root)', () => {
     const cfg = parseKiwiConfig(
       validConfig({
         startupOptions: validStartupOptions({ direct_path: '/' }),
@@ -269,6 +268,44 @@ describe('KiwiConfigSchema — WS path (direct_path)', () => {
     const cfg = parseKiwiConfig(validConfig());
     expect(cfg.startupOptions.direct_path).toBeUndefined();
   });
+
+  it('accepts a single-segment stage path (AWS API Gateway — /prod)', () => {
+    const cfg = parseKiwiConfig(
+      validConfig({
+        startupOptions: validStartupOptions({ direct_path: '/prod' }),
+      }),
+    );
+    expect(cfg.startupOptions.direct_path).toBe('/prod');
+  });
+
+  it('accepts the /{{STAGE}} template placeholder (config.prod-aws.json before substitution)', () => {
+    const cfg = parseKiwiConfig(
+      validConfig({
+        startupOptions: validStartupOptions({ direct_path: '/{{STAGE}}' }),
+      }),
+    );
+    expect(cfg.startupOptions.direct_path).toBe('/{{STAGE}}');
+  });
+
+  it('rejects a multi-segment direct_path (path nesting is not a stage shape)', () => {
+    expect(() =>
+      parseKiwiConfig(
+        validConfig({
+          startupOptions: validStartupOptions({ direct_path: '/webclient/' }),
+        }),
+      ),
+    ).toThrowError(/direct_path/u);
+  });
+
+  it('rejects a direct_path with no leading slash', () => {
+    expect(() =>
+      parseKiwiConfig(
+        validConfig({
+          startupOptions: validStartupOptions({ direct_path: 'prod' }),
+        }),
+      ),
+    ).toThrowError(/direct_path/u);
+  });
 });
 
 // ============================================================================
@@ -368,30 +405,35 @@ describe('KiwiConfigSchema — server auto-detect ({{hostname}} template)', () =
 });
 
 // ============================================================================
-// Static config files — per-env build matrix
+// Static config files — build matrix (single prod target + dev default)
 // ============================================================================
 
 describe('static config files', () => {
-  it('config.json parses (default = staging target)', () => {
+  it('config.json parses (dev default)', () => {
     const cfg = parseKiwiConfig(readStaticConfig('config.json'));
     expect(cfg.startupOptions.server.length).toBeGreaterThan(0);
     expect(cfg.startupOptions.channel.startsWith('#')).toBe(true);
   });
 
-  it('config.staging.json parses', () => {
-    const cfg = parseKiwiConfig(readStaticConfig('config.staging.json'));
+  it('config.prod.json parses', () => {
+    const cfg = parseKiwiConfig(readStaticConfig('config.prod.json'));
     expect(cfg.startupOptions.channel.startsWith('#')).toBe(true);
   });
 
-  it('config.prod.json parses', () => {
-    const cfg = parseKiwiConfig(readStaticConfig('config.prod.json'));
+  // AWS deploys the WebSocket endpoint as a separate API Gateway URL
+  // (wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}), not the
+  // CloudFront origin the SPA is served from. The prod-aws config carries
+  // a templated API-GW URL whose {{...}} placeholders the deploy pipeline
+  // substitutes at bake time, so no concrete URL is hardcoded in the repo.
+  it('config.prod-aws.json parses', () => {
+    const cfg = parseKiwiConfig(readStaticConfig('config.prod-aws.json'));
     expect(cfg.startupOptions.channel.startsWith('#')).toBe(true);
   });
 
   it('the raw schema also accepts every static config', () => {
     expect(KiwiConfigSchema.safeParse(readStaticConfig('config.json')).success).toBe(true);
-    expect(KiwiConfigSchema.safeParse(readStaticConfig('config.staging.json')).success).toBe(true);
     expect(KiwiConfigSchema.safeParse(readStaticConfig('config.prod.json')).success).toBe(true);
+    expect(KiwiConfigSchema.safeParse(readStaticConfig('config.prod-aws.json')).success).toBe(true);
   });
 
   // Deploy-time resolution: every shipped config uses the {{hostname}} template
@@ -399,7 +441,7 @@ describe('static config files', () => {
   // time. This is the whole point of NOT baking a per-env hostname; if any
   // config regresses to a literal host, this assertion fires.
   it('every static config bakes {{hostname}} for server (deploy-time auto-detect)', () => {
-    for (const file of ['config.json', 'config.staging.json', 'config.prod.json']) {
+    for (const file of ['config.json', 'config.prod.json']) {
       const cfg = parseKiwiConfig(readStaticConfig(file));
       expect(cfg.startupOptions.server, `${file} server`).toBe('{{hostname}}');
     }
@@ -410,7 +452,7 @@ describe('static config files', () => {
   // opens a wss:// WebSocket straight to the Worker instead of probing the
   // (non-existent) /webirc/kiwiirc/info gateway endpoint and 404-ing.
   it('every static config sets direct:true + tls:true (no kiwiServer gateway)', () => {
-    for (const file of ['config.json', 'config.staging.json', 'config.prod.json']) {
+    for (const file of ['config.json', 'config.prod.json', 'config.prod-aws.json']) {
       const cfg = parseKiwiConfig(readStaticConfig(file));
       expect(cfg.startupOptions.direct, `${file} direct`).toBe(true);
       expect(cfg.startupOptions.tls, `${file} tls`).toBe(true);
@@ -424,9 +466,91 @@ describe('static config files', () => {
   // `plugins` block. If plugin support is ever needed, the build must copy
   // `.example` → `.html` (or ship a real plugin file) first.
   it('no static config ships a plugins block (avoids the customise.html 404)', () => {
-    for (const file of ['config.json', 'config.staging.json', 'config.prod.json']) {
+    for (const file of ['config.json', 'config.prod.json', 'config.prod-aws.json']) {
       const raw = readStaticConfig(file) as Record<string, unknown>;
       expect(raw.plugins, `${file} plugins`).toBeUndefined();
     }
   });
 });
+
+// ============================================================================
+// AWS prod-aws config — API Gateway WebSocket URL + bake pipeline shape
+// ============================================================================
+//
+// On AWS the WebSocket endpoint is a separate API Gateway URL, not the
+// CloudFront origin that serves the SPA. The prod-aws config therefore
+// bakes a templated host (`{{API_ID}}.execute-api.{{REGION}}.amazonaws.com`)
+// for `server` plus a templated `direct_path` of `/{{STAGE}}` for the API
+// Gateway stage path. irc-framework builds the WS URL as
+// `wss://<server>:<port><direct_path>` (it prepends `wss://` itself when
+// `tls: true`), so a full `wss://...` URL in `server` would produce a
+// doubled-scheme URL that Firefox rejects. No concrete URL is committed;
+// the `{{...}}` placeholders are substituted by the deploy pipeline (see
+// `parseApiUrlForKiwi` and the AWS web deploy ticket) after `cdk deploy`
+// emits the real API id, region, and stage. This block covers the
+// accept-criteria: schema-conformant file, API-GW-shaped server + path,
+// invariants shared with the CF configs, and a malformed prod-aws payload
+// failing the build with a readable aggregated Zod error.
+
+describe('static config files — prod-aws (AWS API Gateway)', () => {
+  it('config.prod-aws.json server is the templated API Gateway host (no wss:// scheme)', () => {
+    const cfg = parseKiwiConfig(readStaticConfig('config.prod-aws.json'));
+    expect(cfg.startupOptions.server).toBe('{{API_ID}}.execute-api.{{REGION}}.amazonaws.com');
+  });
+
+  it('config.prod-aws.json direct_path is the templated stage path', () => {
+    const cfg = parseKiwiConfig(readStaticConfig('config.prod-aws.json'));
+    expect(cfg.startupOptions.direct_path).toBe('/{{STAGE}}');
+  });
+
+  it('config.prod-aws.json keeps direct:true + tls:true (CloudFront serves HTTPS; WS must be wss://)', () => {
+    const cfg = parseKiwiConfig(readStaticConfig('config.prod-aws.json'));
+    expect(cfg.startupOptions.direct).toBe(true);
+    expect(cfg.startupOptions.tls).toBe(true);
+  });
+
+  // Mirrors the bake step in scripts/build.mjs (resolveConfigFile → read →
+  // parseKiwiConfig → re-serialise) without invoking the heavy Kiwi upstream
+  // build. The point of the assertion is that the prod-aws server + path
+  // survive the parse + re-stringify round-trip verbatim, i.e. the baked
+  // dist/webclient/static/config.json would carry the API-GW-shaped fields.
+  it('the baked prod-aws config carries the API-GW-shaped server + direct_path (bake round-trip)', () => {
+    const resolved = resolveConfigFile(['--env', 'prod-aws']);
+    expect(resolved.file).toBe('config.prod-aws.json');
+    const raw = readStaticConfig(resolved.file);
+    const parsed = parseKiwiConfig(raw);
+    const baked = `${JSON.stringify(parsed, null, 2)}\n`;
+    expect(baked).toContain('{{API_ID}}.execute-api.{{REGION}}.amazonaws.com');
+    expect(baked).toContain('/{{STAGE}}');
+  });
+
+  it('a malformed prod-aws server (non-empty string required) fails the build with a readable Zod error', () => {
+    const valid = readStaticConfig('config.prod-aws.json') as Record<string, unknown>;
+    const startupOptions = (valid.startupOptions as Record<string, unknown>) ?? {};
+    const malformed = {
+      ...valid,
+      startupOptions: { ...startupOptions, server: '' },
+    };
+    expect(() => parseKiwiConfig(malformed)).toThrowError(/server/u);
+  });
+
+  it('an out-of-range port in a prod-aws payload fails the build', () => {
+    const valid = readStaticConfig('config.prod-aws.json') as Record<string, unknown>;
+    const startupOptions = (valid.startupOptions as Record<string, unknown>) ?? {};
+    const malformed = {
+      ...valid,
+      startupOptions: { ...startupOptions, port: 99999 },
+    };
+    expect(() => parseKiwiConfig(malformed)).toThrowError(/port/u);
+  });
+
+  it('a non-# channel in a prod-aws payload fails the build', () => {
+    const valid = readStaticConfig('config.prod-aws.json') as Record<string, unknown>;
+    const startupOptions = (valid.startupOptions as Record<string, unknown>) ?? {};
+    const malformed = {
+      ...valid,
+      startupOptions: { ...startupOptions, channel: 'welcome' },
+    };
+    expect(() => parseKiwiConfig(malformed)).toThrowError(/channel/u);
+  });
+});

package/apps/web/tests/landing-content.test.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
+
+// Pure-string assertions over landing/index.html. The file is copied verbatim
+// to dist/index.html by scripts/build.mjs (verified separately by
+// build-smoke.test.ts), so these checks run against the source in CI without
+// paying the Kiwi SPA build cost.
+const html = readFileSync(landingSrc, 'utf8');
+
+describe('landing page "Connect" section', () => {
+  it('contains a "Connect" heading', () => {
+    // The project front door must tell visitors how to reach the IRC server.
+    expect(html).toMatch(/<h2[^>]*>\s*Connect\s*<\/h2>/i);
+  });
+
+  it('documents the WeeChat client', () => {
+    expect(html).toMatch(/WeeChat/i);
+  });
+
+  it('documents the HexChat client', () => {
+    expect(html).toMatch(/HexChat/i);
+  });
+
+  it('documents the irssi client', () => {
+    expect(html).toMatch(/irssi/i);
+  });
+
+  it('documents the IRCCloud client', () => {
+    expect(html).toMatch(/IRCCloud/i);
+  });
+
+  it('documents TheLounge client', () => {
+    expect(html).toMatch(/TheLounge/i);
+  });
+
+  it('mentions the wss (secure WebSocket) transport for the web client', () => {
+    expect(html).toMatch(/\bwss\b/i);
+  });
+
+  it('mentions port 443 for the wss transport', () => {
+    expect(html).toMatch(/443\b/);
+  });
+
+  it('mentions the irc+tls :6697 direct-connect transport', () => {
+    expect(html).toMatch(/6697\b/);
+  });
+
+  it('hides the low-level WebSocket subprotocol framing detail', () => {
+    // The subprotocol negotiation + 510-byte frame budget is IRC-wire-level
+    // detail that doesn't belong on the project front door. It lives in the
+    // docs; the page should not surface `text.ircv3.net` or the 510 figure.
+    expect(html).not.toMatch(/text\.ircv3\.net/i);
+    expect(html).not.toMatch(/\b510\b/);
+  });
+
+  it('links to the Web Client Guide doc', () => {
+    // Cross-references to the docs/ subtree keep the page terse while still
+    // pointing at full instructions. The docs are out-of-tree (git submodule)
+    // so the link is a relative repo path, not a served route.
+    expect(html).toMatch(/WebClientGuide/i);
+  });
+
+  it('references the tcp-ws-forwarder bridge for stock TCP clients', () => {
+    expect(html).toMatch(/tcp-ws-forwarder/i);
+  });
+
+  it('uses a generic hostname placeholder (no per-env host baked in)', () => {
+    // The landing page is built once and served across staging + prod, so it
+    // must NOT pin a concrete worker hostname.
+    expect(html).toMatch(/irc\.example\.com|{{\s*hostname\s*}}|your deployed Worker host/i);
+  });
+
+  it('includes a WeeChat /server add snippet', () => {
+    expect(html).toMatch(/\/server add/i);
+  });
+
+  it('renders the connect instructions as a radio-backed client tab picker', () => {
+    // A horizontal list of client "buttons" selects which instructions show.
+    // Radio inputs share one name so the picker works without JavaScript
+    // (the build-smoke suite asserts the page ships no <script> tags).
+    const tabRadios = html.match(/type=["']radio["'][^>]*name=["']client-tab["']/gi) ?? [];
+    expect(tabRadios.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('renders a tab label for each documented client', () => {
+    expect(html).toMatch(/<label[^>]*for=["']tab-web["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-weechat["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-hexchat["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-irccloud["']/i);
+  });
+
+  it('hides client panels by default and reveals the selected one via :checked', () => {
+    // Pure-CSS tabs: panels are display:none unless their radio is checked,
+    // then `:checked ~ #panel-x` flips them to display:block.
+    expect(html).toMatch(/\.panel\s*\{[^}]*display:\s*none/i);
+    expect(html).toMatch(/:checked\s*~\s*#panel-/i);
+  });
+});