serverless-ircd 0.8.0 → 0.10.0

package/apps/web/src/build-env.ts

@@ -5,22 +5,36 @@
  * unit-testable without running the (slow) Kiwi upstream build. The build
  * script delegates here and then validates the selected file against
  * {@link parseKiwiConfig} before baking it into `dist/webclient/static/config.json`.
+ *
+ * There is a single Cloudflare deploy target (`prod`); the staging/prod
+ * split was collapsed. `--env prod` selects `config.prod.json`; omitting
+ * `--env` bakes the dev default (`config.json`). `--env staging` is rejected.
+ *
+ * AWS has its own per-env config because the WebSocket endpoint is a separate
+ * API Gateway URL (`wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}`),
+ * not the CloudFront origin serving the SPA. `--env prod-aws` selects
+ * `config.prod-aws.json`, whose `server` carries `{{API_ID}}` / `{{REGION}}`
+ * / `{{STAGE}}` placeholders the deploy pipeline substitutes at bake time
+ * (no concrete URLs in the repo). The `prod-aws` env name is retained for
+ * fidelity with the historical staging/prod nomenclature even though the
+ * staging/prod split is gone — `aws` alone would read as a cleaner label but
+ * is left for a separate rename pass.
  */
 
 /** argv values accepted by `--env`; mapped to a `static/config.<env>.json` file. */
 export const ENV_TO_CONFIG_FILE = {
-  staging: 'config.staging.json',
   prod: 'config.prod.json',
+  'prod-aws': 'config.prod-aws.json',
 } as const;
 
 export type BuildEnv = keyof typeof ENV_TO_CONFIG_FILE;
 
-/** Default config file baked when `--env` is not supplied (staging target). */
+/** Default config file baked when `--env` is not supplied (dev default). */
 export const DEFAULT_CONFIG_FILE = 'config.json';
 
 /**
  * Resolves which `static/config.*.json` the build should bake from the
- * `--env <staging|prod>` CLI flag.
+ * `--env prod` CLI flag.
  *
  * @param argv the CLI args after the script name (typically `process.argv.slice(2)`)
  * @returns `{ file, env }` where `file` is the basename under `static/` and
@@ -31,7 +45,7 @@ export function resolveConfigFile(argv: string[]): { file: string; env: string }
   const envIndex = argv.indexOf('--env');
   const env = envIndex !== -1 ? argv[envIndex + 1] : undefined;
   if (env === undefined) {
-    return { file: DEFAULT_CONFIG_FILE, env: 'default (staging)' };
+    return { file: DEFAULT_CONFIG_FILE, env: 'default' };
   }
   const file = ENV_TO_CONFIG_FILE[env as BuildEnv];
   if (file === undefined) {
@@ -41,3 +55,110 @@ export function resolveConfigFile(argv: string[]): { file: string; env: string }
   }
   return { file, env };
 }
+
+/**
+ * Resolves the optional `--api-url <value>` flag carried on the build argv.
+ *
+ * The AWS web deploy pipeline reads the deployed stack's `ConnectUrl`
+ * CloudFormation output (the API Gateway WebSocket URL) and forwards it
+ * to the SPA build via `--api-url`. The build script then overrides
+ * `startupOptions.server` in the parsed Kiwi config with this value before
+ * baking `dist/webclient/static/config.json`, so the baked SPA carries the
+ * real wss URL instead of the `{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`
+ * template that lives in `static/config.prod-aws.json`. No concrete URLs
+ * are committed; the URL is read from stack outputs at deploy time.
+ *
+ * Returns `undefined` when the flag is absent OR when it is the final
+ * token on the argv (no following value). The caller treats both cases
+ * identically: leave the config's `server` field untouched. The Cloudflare
+ * deploys never pass this flag; only the AWS deploy pipeline does.
+ *
+ * @param argv the CLI args after the script name (typically `process.argv.slice(2)`)
+ * @returns the URL string following `--api-url`, or `undefined` when unset.
+ */
+export function resolveApiUrl(argv: string[]): string | undefined {
+  const i = argv.indexOf('--api-url');
+  if (i === -1) {
+    return undefined;
+  }
+  return argv[i + 1];
+}
+
+/**
+ * Splits a `wss://` API Gateway WebSocket URL into the two Kiwi fields it
+ * becomes at bake time: `server` (hostname only) and `direct_path` (the
+ * stage-name path segment).
+ *
+ * irc-framework builds the WebSocket URL as `wss://<server>:<port><direct_path>`,
+ * prepending the `wss://` scheme itself whenever `tls: true`. Setting
+ * `server` to a full `wss://...` URL would make irc-framework prepend a
+ * second `wss://`, producing a malformed URL that Firefox reports as
+ * `wss://wss//<host>...` (the inner `:` becomes a userinfo separator).
+ *
+ * AWS API Gateway WebSocket URLs include the stage name as a path
+ * segment (`wss://<id>.execute-api.<region>.amazonaws.com/<stage>`) —
+ * that segment must reach the browser as `direct_path`, not as part of
+ * `server`. The CF Worker's WS upgrade is at root, so CF configs leave
+ * `direct_path` unset (or `/`) and `server` is just the hostname.
+ *
+ * @param url a `wss://` or `ws://` URL (the stack's `ConnectUrl` output)
+ * @returns `{ server, directPath }` where `server` is the bare hostname
+ *   and `directPath` is the leading-slash path (e.g. `/prod`) or
+ *   `undefined` when the URL's path is `/` or empty.
+ * @throws {Error} when the URL is missing the `ws://`/`wss://` scheme or
+ *   fails `new URL()` parsing.
+ */
+export function parseApiUrlForKiwi(url: string): {
+  server: string;
+  directPath: string | undefined;
+} {
+  if (!/^wss?:\/\//iu.test(url)) {
+    throw new Error(
+      `--api-url must be a wss:// (or ws://) URL; got: ${url}. irc-framework prepends the scheme itself from tls:true, so the bake must split the URL into a hostname-only server + a direct_path.`,
+    );
+  }
+  const parsed = new URL(url);
+  const directPath =
+    parsed.pathname === '' || parsed.pathname === '/' ? undefined : parsed.pathname;
+  return { server: parsed.hostname, directPath };
+}
+
+/**
+ * Pattern matching any `{{key}}` placeholder, used by both the Kiwi
+ * runtime templates (`{{hostname}}`, `{{host}}`, `{{port}}`) and the
+ * AWS deploy-time placeholders (`{{API_ID}}`, `{{REGION}}`,
+ * `{{STAGE}}`).
+ */
+export const PLACEHOLDER_PATTERN = /\{\{[^}]+\}\}/u;
+
+/**
+ * The Cloudflare deploy envs whose `server` field legitimately bakes
+ * Kiwi runtime templates. The placeholder guard must NOT fire on these
+ * — `{{hostname}}` is resolved by Kiwi in the browser at load time.
+ */
+const RUNTIME_TEMPLATE_ENVS = new Set<string>(['default', 'prod']);
+
+/**
+ * Returns `true` when a baked Kiwi config carries an unsubstituted
+ * placeholder that would produce a broken SPA. The guard is scoped to
+ * the `prod-aws` env: that is the only config whose `server` carries
+ * AWS deploy-time placeholders (`{{API_ID}}`/`{{REGION}}`/`{{STAGE}}`)
+ * that the deploy pipeline (`scripts/deploy-web-aws.mjs`) must
+ * substitute via `--api-url` before baking.
+ *
+ * The Cloudflare envs (`default`, `prod`) use Kiwi's `{{hostname}}`
+ * runtime template, which is resolved by Kiwi in the browser at load
+ * time and MUST survive the bake. Applying the guard to them would
+ * break every default `pnpm build` and every `build:prod`.
+ *
+ * @param bakedConfigJson the serialised config payload about to be
+ *   written to `dist/webclient/static/config.json`.
+ * @param env the selected build env (the `env` field from
+ *   {@link resolveConfigFile}).
+ */
+export function hasUnsubstitutedPlaceholder(bakedConfigJson: string, env: string): boolean {
+  if (RUNTIME_TEMPLATE_ENVS.has(env)) {
+    return false;
+  }
+  return PLACEHOLDER_PATTERN.test(bakedConfigJson);
+}

package/apps/web/src/config-schema.ts

@@ -83,13 +83,27 @@ export const KiwiStartupOptionsSchema = z
     /**
      * WebSocket path on the server. Kiwi reads `direct_path` (NOT `path`) —
      * upstream `helpers/Misc.js:139` copies `config.direct_path` into the
-     * connection info; a `path` field is silently ignored. The Worker exposes
-     * its WS upgrade at root (`worker.ts` routes the upgrade before any path
-     * dispatch), so any path other than `/` would miss the handler. Optional
-     * — when omitted irc-framework builds `wss://host:port` with no path,
-     * which the browser normalises to `wss://host:port/`.
+     * connection info; a `path` field is silently ignored.
+     *
+     * Two valid shapes:
+     *   - CF Worker: WS upgrade is at root, so `direct_path` is `/`.
+     *   - AWS API Gateway: the WebSocket endpoint URL includes the stage
+     *     name as a path segment
+     *     (`wss://<id>.execute-api.<region>.amazonaws.com/<stage>`), 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. Optional — when omitted irc-framework
+     * builds `wss://host:port` with no path, which the browser normalises
+     * to `wss://host:port/` (CF root case).
      */
-    direct_path: z.literal('/').optional(),
+    direct_path: z
+      .string()
+      .regex(/^\/(?:[a-zA-Z0-9._-]+|\{\{[^}]+\}\})?$/u, 'direct_path must be / or /<stage>')
+      .optional(),
   })
   .passthrough();
 

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

@@ -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/static/{config.staging.json → config.prod-aws.json}

@@ -1,5 +1,5 @@
 {
-  "windowTitle": "ServerlessIRCd (staging)",
+  "windowTitle": "ServerlessIRCd",
   "startupScreen": "welcome",
   "restricted": false,
   "theme": "Dark",
@@ -15,7 +15,8 @@
     { "name": "Elite", "url": "static/themes/elite" }
   ],
   "startupOptions": {
-    "server": "{{hostname}}",
+    "server": "{{API_ID}}.execute-api.{{REGION}}.amazonaws.com",
+    "direct_path": "/{{STAGE}}",
     "direct": true,
     "tls": true,
     "port": 443,