npm - serverless-ircd - Versions diffs - 0.8.0 → 0.9.0 - Mend

serverless-ircd 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/.github/workflows/ci.yml +4 -0
package/CHANGELOG.md +245 -0
package/README.md +160 -200
package/apps/aws-stack/package.json +1 -1
package/apps/cf-tcp-container/package.json +1 -1
package/apps/cf-tcp-container/src/container-server.ts +21 -1
package/apps/cf-tcp-container/tests/config-loader.test.ts +43 -0
package/apps/cf-tcp-container/tests/container-server.test.ts +249 -1
package/apps/cf-tcp-container/tests/persistence.test.ts +9 -0
package/apps/cf-tcp-container/tests/tls-e2e.test.ts +24 -5
package/apps/cf-worker/package.json +1 -1
package/apps/local-cli/package.json +1 -1
package/apps/local-cli/src/server.ts +94 -31
package/apps/local-cli/tests/config-resolution.test.ts +65 -0
package/apps/local-cli/tests/motd-file-non-error.test.ts +29 -0
package/apps/local-cli/tests/rehash.test.ts +147 -0
package/apps/local-cli/tests/server-helpers.test.ts +63 -0
package/apps/local-cli/tests/tcp.test.ts +89 -0
package/apps/local-cli/tests/ws-subprotocol.test.ts +92 -0
package/apps/web/landing/index.html +226 -3
package/apps/web/package.json +2 -1
package/apps/web/scripts/build.mjs +25 -2
package/apps/web/src/render-docs.ts +292 -0
package/apps/web/tests/build-smoke.test.ts +31 -2
package/apps/web/tests/landing-content.test.ts +103 -0
package/apps/web/tests/render-docs.test.ts +198 -0
package/docs/AWS-Adapter-Architecture.md +3 -2
package/docs/Services.md +33 -1
package/package.json +2 -2
package/packages/aws-adapter/package.json +1 -1
package/packages/aws-adapter/src/aws-runtime.ts +15 -1
package/packages/aws-adapter/src/handlers/nlb-stream.ts +10 -2
package/packages/aws-adapter/tests/aws-runtime.test.ts +23 -1
package/packages/aws-adapter/tests/connection-counter.test.ts +17 -0
package/packages/aws-adapter/tests/global-setup.ts +28 -1
package/packages/aws-adapter/tests/gone-exception.test.ts +21 -2
package/packages/aws-adapter/tests/nlb-stream.test.ts +29 -1
package/packages/aws-adapter/tests/sweeper.test.ts +20 -0
package/packages/cf-adapter/package.json +1 -1
package/packages/cf-adapter/src/connection-do.ts +18 -6
package/packages/cf-adapter/tests/connection-do-pure.test.ts +130 -0
package/packages/in-memory-runtime/package.json +1 -1
package/packages/irc-core/package.json +1 -1
package/packages/irc-core/src/commands/account-auth.ts +46 -18
package/packages/irc-core/src/commands/chanserv.ts +288 -4
package/packages/irc-core/src/commands/hostserv.ts +38 -3
package/packages/irc-core/src/commands/index.ts +1 -0
package/packages/irc-core/src/commands/join.ts +41 -35
package/packages/irc-core/src/commands/nickserv.ts +16 -4
package/packages/irc-core/src/commands/registration.ts +27 -16
package/packages/irc-core/src/commands/service-aliases.ts +52 -0
package/packages/irc-core/src/commands/topic.ts +23 -10
package/packages/irc-core/src/state/channel.ts +17 -0
package/packages/irc-core/tests/commands/chanserv.test.ts +668 -1
package/packages/irc-core/tests/commands/hostserv.test.ts +71 -0
package/packages/irc-core/tests/commands/join.test.ts +179 -0
package/packages/irc-core/tests/commands/nickserv.test.ts +185 -2
package/packages/irc-core/tests/commands/registration.test.ts +227 -6
package/packages/irc-core/tests/commands/sasl.test.ts +44 -0
package/packages/irc-core/tests/commands/service-aliases.test.ts +52 -0
package/packages/irc-server/package.json +1 -1
package/packages/irc-server/src/actor.ts +80 -30
package/packages/irc-server/tests/actor.test.ts +365 -3
package/packages/irc-test-support/package.json +1 -1
package/packages/irc-test-support/src/in-memory-harness.ts +8 -5
package/packages/irc-test-support/src/scenarios.ts +21 -6
package/packages/irc-test-support/tests/in-memory-harness.test.ts +19 -0
package/packages/irc-test-support/vitest.config.ts +6 -1
package/tools/ci-hardening/package.json +1 -1
package/tools/load-test/package.json +1 -1
package/tools/load-test/src/client.ts +13 -13
package/tools/load-test/tests/client.test.ts +258 -2
package/tools/load-test/tests/config.test.ts +39 -0
package/tools/load-test/tests/harness.test.ts +21 -0
package/tools/load-test/tests/metrics.test.ts +7 -0
package/tools/tcp-ws-forwarder/package.json +1 -1
package/tools/tcp-ws-forwarder/tests/close-error.test.ts +40 -0
package/tools/tcp-ws-forwarder/tests/defensive-branches.test.ts +78 -0
package/tools/tcp-ws-forwarder/tests/forwarder.test.ts +51 -0
package/tools/tcp-ws-forwarder/tests/logger.test.ts +31 -1

package/apps/web/landing/index.html CHANGED Viewed

@@ -4,8 +4,9 @@
   Served at `/` by the Worker `[assets]` binding (apps/cf-worker/wrangler.toml).
   The build (`scripts/build.mjs`) copies this file verbatim to `dist/index.html`.
-  The Kiwi IRC SPA lives at `/webclient/`; this page links through to it plus
-  the project docs and source repo. Pure static HTML + inline CSS, no JavaScript.
+  The Kiwi IRC SPA lives at `/webclient/`; the rendered docs at `/docs/`
+  (built from the `docs/` submodule); this page links through to both plus
+  the source repo. Pure static HTML + inline CSS, no JavaScript.
 -->
 <html lang="en">
   <head>
@@ -135,6 +136,113 @@
         border-radius: 4px;
         font-size: 0.9em;
       }
+      pre {
+        font-family: var(--mono);
+        background-color: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 14px 16px;
+        margin: 12px 0;
+        overflow-x: auto;
+        line-height: 1.5;
+        font-size: 0.88rem;
+      }
+      pre code {
+        background: none;
+        border: none;
+        padding: 0;
+        font-size: inherit;
+      }
+      section.connect {
+        margin: 36px 0 8px;
+        padding: 24px 0;
+        border-top: 1px solid var(--border);
+      }
+      section.connect h2 {
+        margin: 0 0 12px;
+        font-size: 1.4rem;
+        letter-spacing: -0.01em;
+      }
+      section.connect h3 {
+        margin: 22px 0 6px;
+        font-size: 1.08rem;
+        color: var(--accent-hover);
+      }
+      section.connect p {
+        margin: 8px 0;
+        color: var(--text);
+      }
+      section.connect p.lead {
+        color: var(--muted);
+      }
+      section.connect .note {
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+      section.connect .cta {
+        margin: 14px 0;
+      }
+      /* Client picker — pure CSS, no JavaScript. Radio inputs hold the
+         selected tab; the labels are the visible buttons arranged in a
+         horizontal row; `:checked ~` reveals the matching panel and
+         highlights its label. See build-smoke "works without JavaScript". */
+      .client-tabs {
+        margin: 8px 0 4px;
+      }
+      .client-tabs > input[type="radio"] {
+        position: absolute;
+        opacity: 0;
+        pointer-events: none;
+      }
+      .client-tabs .tablist {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-bottom: 16px;
+      }
+      .client-tabs .tablist label {
+        padding: 10px 16px;
+        cursor: pointer;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background-color: var(--surface);
+        color: var(--muted);
+        font-weight: 600;
+        font-size: 0.95rem;
+        -webkit-tap-highlight-color: transparent;
+        transition: border-color 0.15s, color 0.15s, background-color 0.15s;
+      }
+      .client-tabs .tablist label:hover {
+        border-color: var(--accent);
+        color: var(--text);
+      }
+      .client-tabs .panel {
+        display: none;
+      }
+      .client-tabs .panel h3 {
+        margin-top: 0;
+      }
+      #tab-web:checked ~ .tablist label[for="tab-web"],
+      #tab-weechat:checked ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:checked ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:checked ~ .tablist label[for="tab-irccloud"] {
+        background-color: var(--bg);
+        color: var(--accent-hover);
+        border-color: var(--accent);
+      }
+      #tab-web:focus-visible ~ .tablist label[for="tab-web"],
+      #tab-weechat:focus-visible ~ .tablist label[for="tab-weechat"],
+      #tab-hexchat:focus-visible ~ .tablist label[for="tab-hexchat"],
+      #tab-irccloud:focus-visible ~ .tablist label[for="tab-irccloud"] {
+        outline: 2px solid var(--accent);
+        outline-offset: 2px;
+      }
+      #tab-web:checked ~ #panel-web,
+      #tab-weechat:checked ~ #panel-weechat,
+      #tab-hexchat:checked ~ #panel-hexchat,
+      #tab-irccloud:checked ~ #panel-irccloud {
+        display: block;
+      }
       .links {
         margin-top: 28px;
         padding: 20px 0;
@@ -170,7 +278,7 @@
     <header>
       <div class="container">
         <h1>Serverless<span class="irc">IRCd</span></h1>
-        <p>An IRC daemon with a serverless deployment model.</p>
+        <p>IRC daemon with a serverless deployment model.</p>
       </div>
     </header>
@@ -194,7 +302,122 @@
           <a class="primary" href="/webclient/">Launch Web Client</a>
         </div>
+        <section class="connect">
+          <h2>Connect</h2>
+          <p class="lead">
+            ServerlessIRCd speaks IRC over secure WebSocket
+            (<code>wss://</code>, port <code>443</code>) as its primary
+            transport, and optionally raw <code>irc+tls</code> on port
+            <code>6697</code>. Replace <code>irc.example.com</code> with your
+            deployed Worker hostname in the snippets below. This page is
+            static and identical across staging and prod.
+          </p>
+          <div class="client-tabs">
+            <input type="radio" name="client-tab" id="tab-web" checked />
+            <input type="radio" name="client-tab" id="tab-weechat" />
+            <input type="radio" name="client-tab" id="tab-hexchat" />
+            <input type="radio" name="client-tab" id="tab-irccloud" />
+            <div
+              class="tablist"
+              role="tablist"
+              aria-label="IRC client connect instructions"
+            >
+              <label for="tab-web" class="tab" role="tab">Web client</label>
+              <label for="tab-weechat" class="tab" role="tab">WeeChat</label>
+              <label for="tab-hexchat" class="tab" role="tab"
+                >HexChat / irssi</label
+              >
+              <label for="tab-irccloud" class="tab" role="tab"
+                >IRCCloud / TheLounge</label
+              >
+            </div>
+            <div
+              class="panel"
+              id="panel-web"
+              role="tabpanel"
+              aria-labelledby="tab-web"
+            >
+              <p>
+                <code>wss</code> on port <code>443</code>, same origin as this
+                page. No client install or bridge required.
+              </p>
+              <div class="cta">
+                <a class="primary" href="/webclient/">Launch Web Client</a>
+              </div>
+            </div>
+            <div
+              class="panel"
+              id="panel-weechat"
+              role="tabpanel"
+              aria-labelledby="tab-weechat"
+            >
+              <p>
+                Connect over <code>wss</code> (port <code>443</code>) using the
+                snippet below, or directly over <code>irc+tls</code> on port
+                <code>6697</code> when the TCP+TLS surface is deployed.
+              </p>
+              <pre><code>/server add ircd irc.example.com/443
+/set irc.server.ircd.ssl on
+/connect ircd
+/join #test</code></pre>
+              <p class="note">
+                For the <code>irc+tls :6697</code> path, swap the port above for
+                <code>6697</code>. The TCP surface is a separate deployment
+                (Cloudflare Spectrum + Container); see the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/Cloudflare-TCP-Deployment"
+                  >Cloudflare TCP Deployment Guide</a
+                >.
+              </p>
+            </div>
+            <div
+              class="panel"
+              id="panel-hexchat"
+              role="tabpanel"
+              aria-labelledby="tab-hexchat"
+            >
+              <p>
+                These TCP-only IRC clients do not support WebSocket natively.
+                Use <code>tools/tcp-ws-forwarder</code> to bridge them: it
+                listens on a local TCP port and forwards each IRC line over
+                <code>wss</code> to the Worker, negotiating the
+                <code>binary.ircv3.net</code> subprotocol upstream.
+              </p>
+              <pre><code>pnpm --filter tcp-ws-forwarder start \
+  --target wss://irc.example.com/ --listen-port 16667</code></pre>
+              <p class="note">
+                Then point HexChat / irssi at <code>127.0.0.1:16667</code>
+                (TLS off &mdash; the bridge is local). Bridging instructions
+                are in the
+                <a
+                  href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/wiki/WebClientGuide"
+                  >Web Client Guide</a
+                >.
+              </p>
+            </div>
+            <div
+              class="panel"
+              id="panel-irccloud"
+              role="tabpanel"
+              aria-labelledby="tab-irccloud"
+            >
+              <p>
+                Both support WebSocket natively. Add a network pointing at
+                <code>wss://irc.example.com/</code> (port <code>443</code>, TLS
+                on); no bridge required.
+              </p>
+            </div>
+          </div>
+        </section>
         <div class="links">
+          <a href="/docs/">Docs</a>
           <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd">Source Code (Gitea)</a>
           <a href="https://gitea.com/ServerlessIRCd/ServerlessIRCd/issues">Issue Tracker</a>
           <a href="/webclient/">Web IRC Client</a>

package/apps/web/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/web",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "Web client workspace: Kiwi IRC SPA served at /webclient/ and project landing page at /",
   "license": "BSD-3-Clause",
@@ -21,6 +21,7 @@
   "devDependencies": {
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.0",
+    "marked": "^18.0.9",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.0"

package/apps/web/scripts/build.mjs CHANGED Viewed

@@ -5,12 +5,17 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveConfigFile } from '../src/build-env.ts';
 import { parseKiwiConfig } from '../src/config-schema.ts';
+import { buildDocs } from '../src/render-docs.ts';
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const upstream = path.resolve(pkgRoot, 'upstream');
 const dist = path.resolve(pkgRoot, 'dist');
 const appDist = path.join(dist, 'webclient');
 const staticDir = path.join(pkgRoot, 'static');
+// The `docs/` submodule lives at the monorepo root (two levels up from
+// apps/web). Rendered to dist/docs/ by the docs build step (see step 6).
+const docsSrc = path.resolve(pkgRoot, '..', '..', 'docs');
+const docsDist = path.join(dist, 'docs');
 // The SPA is served at /webclient/ on the Worker (the [assets] binding serves
 // `dist/`). All hashed asset URLs must be /webclient/-prefixed so they load
@@ -44,6 +49,16 @@ if (!existsSync(upstream)) {
   );
 }
+// The `docs/` submodule must be checked out — step 6 renders every docs/*.md
+// to dist/docs/. Mirrors the Kiwi upstream guard above so a stale/partial
+// submodule checkout fails loudly with the recovery command instead of
+// producing an empty docs/ section on the deployed site.
+if (!existsSync(docsSrc)) {
+  throw new Error(
+    `Docs submodule missing at ${docsSrc}. Run \`git submodule update --init docs\` first.`,
+  );
+}
 // 1. Install upstream deps. Kiwi ships a yarn.lock; --frozen-lockfile gives a
 //    reproducible tree. Contributors get yarn via `corepack enable`. The
 //    guard checks for the actual binary the build invokes, not just the
@@ -116,8 +131,8 @@ await writeFile(
 // 5. Landing page: copy the static landing page (landing/index.html) to
 //    dist/index.html so the Worker `[assets]` binding serves it at `/`. Pure
-//    static HTML + inline CSS (no JS); links to /webclient/ (the SPA), docs/,
-//    and the source repo.
+//    static HTML + inline CSS (no JS); links to /webclient/ (the SPA),
+//    /docs/ (the rendered docs built in step 6), and the source repo.
 await mkdir(dist, { recursive: true });
 const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
 if (!existsSync(landingSrc)) {
@@ -127,6 +142,14 @@ if (!existsSync(landingSrc)) {
 }
 await cp(landingSrc, path.join(dist, 'index.html'));
+// 6. Docs: render 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 — Home.md becomes index.html). Requires the `docs/`
+//    submodule (guarded at step 0). Zero Worker changes — the existing
+//    [assets] binding already serves dist/ with not_found_handling = "none".
+const docsResult = await buildDocs({ srcDir: docsSrc, outDir: docsDist });
 console.log(
   `Kiwi SPA built -> dist/webclient/ (publicPath=${PUBLIC_PATH}, config=${configFileName}, env=${configEnv})`,
 );
+console.log(`Docs rendered -> dist/docs/ (${docsResult.emitted.length} pages, index=index.html)`);

package/apps/web/src/render-docs.ts ADDED Viewed

@@ -0,0 +1,292 @@
+/**
+ * Markdown → static-HTML render pipeline for the `docs/` submodule.
+ *
+ * Renders every `docs/*.md` to a standalone HTML page under `dist/docs/` so
+ * the Worker `[assets]` binding serves them at `/docs/<name>.html` (and
+ * `/docs/` for the index — `Home.md` becomes `index.html`). Wired into the
+ * `apps/web` build by `scripts/build.mjs`.
+ *
+ * Extracted from the build script so the rendering pipeline is unit-testable
+ * without running the (heavy) Kiwi upstream SPA build.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { marked } from 'marked';
+// GFM is on by default in marked v18+, but pin it explicitly so a future
+// upstream default flip can't silently change the rendered output. `async:
+// false` makes `.parse()` return a plain string (its return type is the
+// union `string | Promise<string>` — narrowed with a type assertion at the
+// call site).
+marked.use({ gfm: true, async: false });
+/** Basename of the docs landing page (rendered to `index.html`). */
+const HOME_SLUG = 'Home';
+/**
+ * Render GitHub-flavored markdown to an HTML fragment (no surrounding
+ * `<html>`/`<body>` — {@link buildDocs} wraps the result in a full page).
+ */
+export function renderMarkdown(md: string): string {
+  return marked.parse(md, { async: false }) as string;
+}
+/**
+ * Rewrite intra-docs links in already-rendered HTML so relative references
+ * resolve on the static site. Two source shapes are handled:
+ *
+ * 1. `[x](OtherDoc.md)` / `[x](./OtherDoc.md)` — Gitea-relative, emitted by
+ *    marked as `<a href="./OtherDoc.md">`.
+ * 2. `[x](OtherDoc)` — Gitea-wiki "bare" link (no extension), used heavily
+ *    in `Home.md` and `ADR-Index.md`.
+ *
+ * Only slugs present in `knownDocs` are rewritten, so external links, repo
+ * paths, and unknown targets are left untouched. Anchor fragments
+ * (`#section`) are preserved.
+ */
+export function rewriteDocLinks(html: string, knownDocs: Set<string>): string {
+  return html.replace(/href="([^"]*)"/g, (match, raw: string) => {
+    // Leave external URLs and pure-anchor links alone.
+    if (raw === '' || raw.startsWith('#') || /^(?:https?:|mailto:|tel:|data:)/i.test(raw)) {
+      return match;
+    }
+    const [pathPartRaw, ...fragParts] = raw.split('#');
+    const pathPart = pathPartRaw ?? '';
+    const fragment = fragParts.length > 0 ? `#${fragParts.join('#')}` : '';
+    const slug = pathPart.replace(/^\.\//, '').replace(/\.md$/i, '').trim();
+    if (slug === '' || !knownDocs.has(slug)) {
+      return match;
+    }
+    return `href="${slug}.html${fragment}"`;
+  });
+}
+export interface BuildDocsOptions {
+  /** Source directory containing the `*.md` files (typically the `docs/` submodule). */
+  srcDir: string;
+  /** Output directory to write the rendered site (typically `dist/docs/`). */
+  outDir: string;
+}
+export interface BuildDocsResult {
+  /** Relative names of the files written under `outDir`. */
+  emitted: string[];
+}
+/**
+ * Render every `*.md` under `srcDir` into a standalone HTML page under
+ * `outDir`. `Home.md` becomes `index.html`; every other file `<Slug>.md`
+ * becomes `<Slug>.html`. Throws a clear error if `srcDir` is missing or
+ * empty — the build script surfaces this so a stale `docs/` submodule
+ * checkout fails loudly (mirroring the Kiwi `upstream/` guard).
+ */
+export async function buildDocs({ srcDir, outDir }: BuildDocsOptions): Promise<BuildDocsResult> {
+  if (!existsSync(srcDir)) {
+    throw new Error(
+      `Docs source missing at ${srcDir}. Run \`git submodule update --init docs\` first.`,
+    );
+  }
+  const entries = await readdir(srcDir);
+  const mdFiles = entries.filter((f) => f.toLowerCase().endsWith('.md'));
+  if (mdFiles.length === 0) {
+    throw new Error(
+      `Docs source directory is empty at ${srcDir}. Run \`git submodule update --init docs\` first.`,
+    );
+  }
+  const knownSlugs = new Set(mdFiles.map((f) => f.replace(/\.md$/i, '')));
+  await mkdir(outDir, { recursive: true });
+  // Shared stylesheet — single source of truth for every page, mirroring the
+  // landing page's dark theme (CSS variables kept inline so the rendered
+  // docs work as static files served from any path).
+  await writeFile(path.join(outDir, 'docs.css'), DOCS_CSS, 'utf8');
+  const emitted: string[] = [];
+  for (const file of mdFiles) {
+    const slug = file.replace(/\.md$/i, '');
+    const md = await readFile(path.join(srcDir, file), 'utf8');
+    const body = rewriteDocLinks(renderMarkdown(md), knownSlugs);
+    const title = extractTitle(md) ?? slug;
+    const outName = slug === HOME_SLUG ? 'index.html' : `${slug}.html`;
+    const html = wrapPage(title, body, slug === HOME_SLUG);
+    await writeFile(path.join(outDir, outName), html, 'utf8');
+    emitted.push(outName);
+  }
+  return { emitted };
+}
+/** Extract the first ATX `# Heading` as the page title; `undefined` if none. */
+function extractTitle(md: string): string | undefined {
+  const match = md.match(/^#\s+(.+?)\s*$/m);
+  return match?.[1];
+}
+/** Escape the four significant HTML characters in a text string. */
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+/** Wrap a rendered HTML fragment in a full page with the shared stylesheet. */
+function wrapPage(title: string, body: string, isIndex: boolean): string {
+  const back = isIndex ? '' : '<p class="back"><a href="./index.html">Docs home</a></p>';
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)} — ServerlessIRCd Docs</title>
+    <link rel="stylesheet" href="./docs.css" />
+  </head>
+  <body>
+    <header>
+      <div class="container">
+        <h1><a href="./index.html">ServerlessIRCd Docs</a></h1>
+      </div>
+    </header>
+    <main class="container">
+      ${back}
+      <article>
+${body}
+      </article>
+    </main>
+    <footer>
+      <div class="container">
+        <p><a href="/">Back to landing</a></p>
+      </div>
+    </footer>
+  </body>
+</html>
+`;
+}
+const DOCS_CSS = `:root {
+  --bg: #0d1117;
+  --surface: #161b22;
+  --border: #30363d;
+  --text: #e6edf3;
+  --muted: #8b949e;
+  --accent: #58a6ff;
+  --accent-hover: #79c0ff;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas,
+    "Liberation Mono", monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial,
+    sans-serif;
+}
+* { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; }
+body {
+  margin: 0;
+  font-family: var(--sans);
+  line-height: 1.6;
+  color: var(--text);
+  background-color: var(--bg);
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+.container {
+  width: 100%;
+  max-width: 820px;
+  margin: 0 auto;
+  padding: 0 20px;
+}
+header {
+  padding: 24px 0 14px;
+  border-bottom: 1px solid var(--border);
+}
+header h1 {
+  margin: 0;
+  font-size: 1.4rem;
+  letter-spacing: -0.02em;
+}
+header h1 a {
+  color: var(--accent);
+  text-decoration: none;
+}
+header h1 a:hover { text-decoration: underline; }
+main { flex: 1 0 auto; padding: 28px 0; }
+article {
+  font-size: 1rem;
+  overflow-wrap: break-word;
+}
+article h1, article h2, article h3, article h4 {
+  letter-spacing: -0.01em;
+  line-height: 1.25;
+  margin-top: 1.6em;
+  margin-bottom: 0.6em;
+}
+article h1 { font-size: 1.7rem; margin-top: 0; }
+article h2 { font-size: 1.35rem; border-bottom: 1px solid var(--border); padding-bottom: 0.3em; }
+article h3 { font-size: 1.12rem; }
+article h4 { font-size: 1rem; color: var(--accent-hover); }
+article p { margin: 0.8em 0; }
+article a { color: var(--accent); text-decoration: none; }
+article a:hover { text-decoration: underline; }
+article ul, article ol { padding-left: 1.6em; }
+article li { margin: 0.25em 0; }
+article blockquote {
+  margin: 0.9em 0;
+  padding: 0.4em 1em;
+  border-left: 3px solid var(--border);
+  color: var(--muted);
+}
+article blockquote p { margin: 0.4em 0; }
+article code {
+  font-family: var(--mono);
+  background-color: var(--surface);
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+article pre {
+  font-family: var(--mono);
+  background-color: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 14px 16px;
+  margin: 12px 0;
+  overflow-x: auto;
+  line-height: 1.5;
+  font-size: 0.88rem;
+}
+article pre code {
+  background: none; border: none; padding: 0; font-size: inherit;
+}
+article table {
+  border-collapse: collapse;
+  margin: 1em 0;
+  display: block;
+  overflow-x: auto;
+}
+article table th, article table td {
+  border: 1px solid var(--border);
+  padding: 6px 12px;
+  text-align: left;
+}
+article table th { background-color: var(--surface); }
+article hr {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 1.6em 0;
+}
+article img { max-width: 100%; }
+.back { margin-top: 0; color: var(--muted); font-size: 0.92rem; }
+.back a { color: var(--accent); }
+footer {
+  flex-shrink: 0;
+  padding: 18px 0;
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+footer a { color: var(--muted); text-decoration: none; }
+footer a:hover { color: var(--accent); }
+`;

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

@@ -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);
+  });
+});