docs: update portal for WRNexusJS 0.2.17

scripts/generate-docs.ts

@@ -21,6 +21,7 @@ const catalog = [
   ["db", "Data", "Database adapters, typed queries, models, migrations, and sessions."],
   ["dev-server", "Runtime", "Development and production servers, HMR, assets, and gateways."],
   ["encryption", "Security", "Hashing, HMAC, authenticated encryption, and key derivation."],
+  ["helpers", "Tooling", "Safe Context URL helpers and forward-auth login redirects."],
   ["i18n", "Frontend", "Translation loading, locale resolution, and Intl formatting."],
   ["jwt", "Security", "HS256 JWT signing, verification, and bearer authentication."],
   ["mobile", "Native", "SSR-safe compatibility access to Capacitor plugins."],
@@ -244,7 +245,7 @@ writeFileSync(
   shell(
     "Packages",
     "Explore every WrNexus package, API, function, and copy-ready usage example.",
-    `<main class="page"><section class="hero compact"><span class="eyebrow">25 focused packages</span><h1>Package reference</h1><p>Everything in the framework, organized by responsibility and documented from the published ${frameworkVersion} APIs.</p><input class="search" type="search" placeholder="Search packages, features, or categories…" @input="query = event.target.value" /></section><section class="category-filter" aria-label="Filter packages by category"><div class="category-row">${categoryButtons}</div><p>Showing <strong>{category}</strong> packages</p></section><section class="package-grid">${cards}</section></main>`,
+    `<main class="page"><section class="hero compact"><span class="eyebrow">${catalog.length} focused packages</span><h1>Package reference</h1><p>Everything in the framework, organized by responsibility and documented from the published ${frameworkVersion} APIs.</p><input class="search" type="search" placeholder="Search packages, features, or categories…" @input="query = event.target.value" /></section><section class="category-filter" aria-label="Filter packages by category"><div class="category-row">${categoryButtons}</div><p>Showing <strong>{category}</strong> packages</p></section><section class="package-grid">${cards}</section></main>`,
     '  state query = ""\n  state category = "All"\n',
   ),
 );
@@ -285,7 +286,7 @@ writeFileSync(
   shell(
     "Home",
     "WrNexus documentation: build secure, server-rendered, reactive applications with Bun.",
-    `<main class="page"><section class="hero"><span class="eyebrow">WrNexus ${frameworkVersion}</span><h1>Build from the server.<br><em>Ship only what matters.</em></h1><p>An SSR-first, Bun-native framework with reactive .wrn components, typed data, realtime rooms, mobile capabilities, and production security built in.</p><div class="actions"><a class="primary" href="/getting-started">Start building</a><a href="/packages">Explore 25 packages</a></div><div class="code-window"><span>app/pages/counter.wrn</span><pre><code>page Counter {
+    `<main class="page"><section class="hero"><span class="eyebrow">WrNexus ${frameworkVersion}</span><h1>Build from the server.<br><em>Ship only what matters.</em></h1><p>An SSR-first, Bun-native framework with reactive .wrn components, typed data, realtime rooms, mobile capabilities, and production security built in.</p><div class="actions"><a class="primary" href="/getting-started">Start building</a><a href="/packages">Explore ${catalog.length} packages</a></div><div class="code-window"><span>app/pages/counter.wrn</span><pre><code>page Counter {
   state count = 0
   view {
     &lt;button @click=&quot;count++&quot;&gt;

scripts/generate-portal.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { format } from "prettier";
 
 const root = resolve(import.meta.dir, "..");
 const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -8,6 +9,16 @@ const pages = join(root, "app", "pages");
 const docs = join(root, "docs");
 const pub = join(root, "public");
 mkdirSync(docs, { recursive: true });
+const packageNames = [...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDependencies)]
+  .filter((name) => name.startsWith("@wrnexus/"))
+  .map((name) => name.split("/")[1]!)
+  .filter((name, index, all) => all.indexOf(name) === index)
+  .sort();
+const packageCount = packageNames.length;
+
+async function writeFormatted(path: string, source: string) {
+  writeFileSync(path, await format(source, { filepath: path }));
+}
 
 const esc = (s: string) => s.replaceAll("{", "{").replaceAll("}", "}");
 const code = (s: string) =>
@@ -129,7 +140,7 @@ writeFileSync(
 <section><h2>Request lifecycle</h2><ol class="lifecycle"><li><strong>Request</strong><span>Security headers and request limits</span></li><li><strong>Middleware</strong><span>Authentication, policy, and context</span></li><li><strong>File route</strong><span>Page or API handler</span></li><li><strong>Compiler + SSR</strong><span>Safe HTML and scoped runtime</span></li><li><strong>Response</strong><span>HTML, JSON, stream, or realtime upgrade</span></li></ol></section>
 <section><h2>Production proof</h2><div class="feature-grid"><article><h3><a href="https://workroot.in/">WorkRoot</a></h3><p>Public creator/company site and approved WRNexusJS production showcase.</p></article><article><h3><a href="https://wrnexusjs.dev/">wrnexusjs.dev</a></h3><p>This documentation application runs WRNexusJS ${version}.</p></article></div><p><a href="/showcase">View deployment notes and showcase status →</a></p></section>
 <section><h2>Capability status</h2><div class="table-wrap"><table><thead><tr><th>Capability</th><th>Status</th><th>Details</th></tr></thead><tbody><tr><td>SSR, routing, compiler, APIs</td><td>Preview</td><td>Installed in ${version}; public support policy pending.</td></tr><tr><td>Mobile/native</td><td>Experimental</td><td>Capacitor compatibility and native generation have platform limitations.</td></tr><tr><td>Durable queues</td><td>Experimental</td><td>Production durability requires an appropriate driver strategy.</td></tr></tbody></table></div></section>
-<section><h2>Continue exploring</h2><div class="actions"><a href="/packages">Explore 25 packages</a><a href="/changelog">Release notes</a><a href="/roadmap">Roadmap</a><a href="/support">Support and access</a></div></section>`,
+<section><h2>Continue exploring</h2><div class="actions"><a href="/packages">Explore ${packageCount} packages</a><a href="/changelog">Release notes</a><a href="/roadmap">Roadmap</a><a href="/support">Support and access</a></div></section>`,
   ),
 );
 
@@ -252,8 +263,27 @@ const guides: Record<string, [string, string, string]> = {
   ],
   "workspaces-and-gateway": [
     "Workspaces and gateway",
-    "Host isolated applications behind a gateway.",
-    "The workspace gateway dispatches apps by configured boundaries. Test host matching, asset namespaces, cookies, sessions, errors, and cross-app authorization before deployment.",
+    "Add applications, route domains, and implement safe SSO forward authentication.",
+    `<p>A workspace runs isolated applications behind one domain-routing gateway. Add an application from the workspace root; the CLI scaffolds <code>apps/reports</code> and registers it in <code>wrnexus.workspace.ts</code>:</p>${code(`wrnexus workspace add reports --domain=reports.localhost
+bun install
+bun run dev`)}<h2>Forward authentication</h2><p>Point protected applications at a dedicated verifier endpoint. The verifier must return 2xx for an authenticated session, 401/403 to deny access, or an HTTP redirect to begin browser login.</p>${code(`// wrnexus.workspace.ts
+{
+  name: "admin",
+  dir: "apps/admin",
+  domains: ["admin.localhost"],
+  auth: { forward: { url: "http://sso.localhost:3000/api/verify" } },
+}`)}<p>The gateway forwards cookies, authorization, original host, protocol, method, path, and query. Inside the verifier, <code>ctx.url</code> identifies the SSO verifier request—not the original admin URL. Use <code>@wrnexus/helpers</code> to reconstruct and validate the original destination:</p>${code(`import type { Context } from "@wrnexus/core";
+import { redirectToLogin } from "@wrnexus/helpers";
+
+export const GET = async (ctx: Context) => {
+  if (await hasValidSession(ctx)) {
+    return new Response(null, { status: 204 });
+  }
+
+  return redirectToLogin(ctx, "/login", {
+    allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"],
+  });
+};`)}<p>Always allowlist redirect hosts. After login, validate or sign the <code>returnTo</code> value before redirecting. Keep internal app ports private and open applications through the gateway port.</p>`,
   ],
   deployment: [
     "Deployment",
@@ -296,7 +326,7 @@ for (const [slug, [title, desc, text]] of Object.entries(guides))
     `/guides/${slug}`,
     title,
     desc,
-    `<article class="documentation prose standalone"><span class="status status-beta">Preview guide · ${version}</span><h1>${title}</h1><p>${text}</p><h2>Release scope</h2><p>This guide describes installed ${version} capabilities. Follow linked package declarations for exact signatures; undocumented behavior is not guaranteed.</p><p><a href="/packages">Browse package APIs</a> · <a href="/guides/troubleshooting">Troubleshooting</a> · <a href="/support">Support</a></p></article>`,
+    `<article class="documentation prose standalone"><span class="status status-beta">Preview guide · ${version}</span><h1>${title}</h1>${text.startsWith("<") ? text : `<p>${text}</p>`}<h2>Release scope</h2><p>This guide describes installed ${version} capabilities. Follow linked package declarations for exact signatures; undocumented behavior is not guaranteed.</p><p><a href="/packages">Browse package APIs</a> · <a href="/guides/troubleshooting">Troubleshooting</a> · <a href="/support">Support</a></p></article>`,
     "Guides",
   );
 
@@ -346,14 +376,14 @@ page(
   "/changelog",
   "Changelog",
   "WRNexusJS documentation release history and migration notes.",
-  `<article class="documentation prose standalone"><h1>Changelog</h1><h2>${version} <small>2026-07-12</small></h2><p>Documentation application aligned to all 25 installed packages, with generated README and TypeScript declaration references. This portal release establishes truthful private-preview access messaging and expanded framework navigation.</p><h3>Migration notes</h3><p>Keep all <code>@wrnexus/*</code> packages on the same release and run the installed CLI update workflow. No older framework release history is present in this repository.</p><h2>Versioning and support</h2><p>The packages use semantic-looking versions, but a formal compatibility and old-release support policy has not been approved. Preview consumers should treat minor releases as potentially requiring migration review.</p></article>`,
+  `<article class="documentation prose standalone"><h1>Changelog</h1><h2>${version} <small>2026-07-13</small></h2><p>Documentation is aligned to all ${packageCount} installed packages. This release adds <code>@wrnexus/helpers</code>, original-request URL helpers, safe login redirects, working <code>wrnexus workspace add</code>, and forward-auth redirect propagation.</p><h3>Migration notes</h3><p>Run <code>wrnexus update --latest</code> and keep every <code>@wrnexus/*</code> package on ${version}. Existing applications must explicitly add <code>@wrnexus/helpers</code> before importing it; newly scaffolded applications include it automatically.</p><h2>Versioning and support</h2><p>The packages use semantic-looking versions, but a formal compatibility and old-release support policy has not been approved. Preview consumers should treat minor releases as potentially requiring migration review.</p></article>`,
   "Project",
 );
 page(
   `/releases/${version}`,
   `Release ${version}`,
   `WRNexusJS ${version} release notes.`,
-  `<article class="documentation prose standalone"><h1>WRNexusJS ${version}</h1><p>Released 2026-07-12 in this documentation repository. Twenty-five installed packages are aligned to this version. See the <a href="/changelog">changelog</a>, <a href="/guides/upgrading">upgrade guide</a>, and package references.</p></article>`,
+  `<article class="documentation prose standalone"><h1>WRNexusJS ${version}</h1><p>Released 2026-07-13. All ${packageCount} installed packages are aligned to this version. Highlights include the new helpers package, reliable workspace app addition, and browser SSO redirects through forward authentication. See the <a href="/changelog">changelog</a>, <a href="/guides/upgrading">upgrade guide</a>, and package references.</p></article>`,
   "Releases",
 );
 page(
@@ -423,11 +453,6 @@ const routes = [
   "/search",
   "/404",
 ].filter(Boolean);
-const packageNames = Object.keys(pkg.dependencies)
-  .concat(Object.keys(pkg.devDependencies))
-  .filter((x) => x.startsWith("@wrnexus/"))
-  .map((x) => x.split("/")[1])
-  .sort();
 const urls = [...new Set([...routes, ...packageNames.map((x) => `/packages/${x}`)])];
 writeFileSync(
   join(pub, "robots.txt"),
@@ -437,13 +462,13 @@ writeFileSync(
   join(pub, "sitemap.xml"),
   `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls.map((x) => `<url><loc>https://wrnexusjs.dev${x}</loc></url>`).join("")}</urlset>\n`,
 );
-writeFileSync(
+await writeFormatted(
   join(pub, "docs-index.json"),
   JSON.stringify(
     {
       version,
       status: "private-developer-preview",
-      generatedAt: "2026-07-12",
+      generatedAt: "2026-07-13",
       documents: urls.map((url) => ({
         url,
         title: url === "/" ? "WRNexusJS" : url.split("/").pop()!.replaceAll("-", " "),
@@ -465,17 +490,43 @@ writeFileSync(
   `# WRNexusJS ${version} comprehensive documentation index\n\nStatus: Private Developer Preview. Runtime: Bun. UI language: .wrn.\nThis is the documentation application, not the framework monorepo.\n\n${urls.map((x) => `- https://wrnexusjs.dev${x}`).join("\n")}\n\nFor exact APIs, use installed package README files followed by exported declarations.\n`,
 );
 
+const packageMarker = "# Installed package documentation";
+const existingGuide = readFileSync(join(pub, "llms.txt"), "utf8");
+let frameworkGuide = existingGuide.split(`\n${packageMarker}`)[0]!.trim();
+if (frameworkGuide.startsWith("# WRNexusJS documentation ")) {
+  frameworkGuide = frameworkGuide.replace(
+    /^# WRNexusJS documentation [^\n]+/,
+    `# WRNexusJS documentation ${version}`,
+  );
+} else {
+  frameworkGuide = `# WRNexusJS documentation ${version}\n\nStatus: Private Developer Preview. This site documents ${packageCount} release-aligned packages.\n\n${frameworkGuide}`;
+}
+const installedPackageDocs = packageNames
+  .map((name) => {
+    const packageRoot = join(root, "node_modules", "@wrnexus", name);
+    const readme = readFileSync(join(packageRoot, "README.md"), "utf8").trim();
+    const declarations = readFileSync(join(packageRoot, "dist", "index.d.ts"), "utf8").trim();
+    return `## @wrnexus/${name}\n\nDocumentation URL: https://wrnexusjs.dev/packages/${name}\n\n${readme}\n\n### Exported TypeScript declarations\n\n\`\`\`ts\n${declarations}\n\`\`\``;
+  })
+  .join("\n\n---\n\n");
+writeFileSync(
+  join(pub, "llms.txt"),
+  `${frameworkGuide}\n\n${packageMarker}\n\nThe following README files and declarations come from the installed private ${version} release.\n\n${installedPackageDocs}\n`,
+);
+
 const auditDocs: Record<string, string> = {
-  "site-audit.md": `# WRNexusJS site audit\n\nDate: 2026-07-12. Baseline: Bun 1.3.14, framework ${version}.\n\n## Baseline results\n\n- bun install: pass (169 installs / 209 packages, unchanged).\n- docs generation: pass (25 package pages and 5 prior site pages).\n- tests: 6 pass. Check: pass. Production build: pass, 30 routes.\n- Access test with an empty npm config: @wrnexus/cli and @wrnexus/core returned npm E404.\n- Repository: private WorkRoot Git remote; no public LICENSE, SECURITY, or CHANGELOG file found.\n\n## Findings\n\nThe prior generator duplicated package H1s, descriptions, install blocks, and dumped full declarations. It also rewrote hand-authored core pages, used four desktop-only nav links, hid navigation on mobile, branded inconsistently, and presented an unusable public create command. Metadata lacked explicit canonicals and route coverage. No sitemap, robots file, docs index, release/access route, security/support/license policy, showcase evidence notes, benchmarks methodology page, or 404 source existed.\n\n## Audit limitations\n\nBrowser tooling, Lighthouse, axe, screenshots, and an authenticated clean scaffold were unavailable. Scores are therefore not fabricated; post-deploy measurements remain required under docs/audits/.\n`,
+  "site-audit.md": `# WRNexusJS site audit\n\nDate: 2026-07-13. Baseline: Bun 1.3.14, framework ${version}.\n\n## Baseline results\n\n- authenticated private-registry installation: pass.\n- docs generation: pass (${packageCount} package pages plus portal and guide pages).\n- tests, lint, formatting, and production build are required by the release check.\n- package access remains restricted/private.\n- repository: private WorkRoot Git remote; no public license file exists.\n\n## Findings\n\nPackage documentation, discovery assets, and AI-readable references are generated from the installed release. The ${version} portal includes the helpers package, workspace app addition, and safe forward-auth login redirect guidance.\n\n## Audit limitations\n\nBrowser tooling, Lighthouse, axe, screenshots, and authenticated production deployment checks are separate post-deploy work. Scores are not fabricated; reports belong under docs/audits/.\n`,
   "documentation-information-architecture.md": `# Documentation information architecture\n\nGlobal navigation groups Learn, Reference, Guides, Project, and Trust. Canonical discovery begins at the homepage, then /getting-started and /tutorial. Exact APIs live under /packages. Conceptual tasks live under /guides. Status and trust live at /roadmap, /changelog, /security, /support, /license, and /access. Machine discovery uses robots.txt, sitemap.xml, llms.txt, llms-full.txt, and docs-index.json.\n`,
-  "release-access-status.md": `# Release and access status\n\n## Decision: Mode B — Private Developer Preview\n\nActive version: ${version}, derived from package.json#wrnexus.version. All 25 installed @wrnexus packages resolve to ${version}. On 2026-07-12, npm view using a clean empty user config returned E404 for @wrnexus/cli@${version} and @wrnexus/core@${version}. The repository remote is a private WorkRoot Git service and no public license file exists.\n\nExternal users cannot execute an installation without approved private registry credentials. The truthful CTA is Request preview access. After approval, the canonical command is bunx @wrnexus/cli@${version} create my-app. Tokens must never appear in documentation or source.\n`,
+  "release-access-status.md": `# Release and access status\n\n## Decision: Mode B — Private Developer Preview\n\nActive version: ${version}, derived from package.json#wrnexus.version. All ${packageCount} installed @wrnexus packages resolve to ${version} and npm reports restricted access. The repository remote is a private WorkRoot Git service and no public license file exists.\n\nExternal users cannot execute an installation without approved private registry credentials. The truthful CTA is Request preview access. After approval, the canonical command is bunx @wrnexus/cli@${version} create my-app. Tokens must never appear in documentation or source.\n`,
   "documentation-coverage-matrix.md": `# Documentation coverage matrix\n\n| Area | Package reference | Concept guide | Runnable fixture | Tests | Stability | Limitation |\n|---|---|---|---|---|---|---|\n${packageNames.map((x) => `| @wrnexus/${x} | /packages/${x} | ${["validation", "authz", "db", "uploader", "pubsub", "queue", "mobile"].includes(x) ? `/guides/${x === "authz" ? "authorization" : x === "validation" ? "forms-and-validation" : x === "uploader" ? "uploads" : x === "queue" ? "queues" : x}` : "Architecture/package guide"} | Planned | Generator coverage | ${["mobile", "native", "queue"].includes(x) ? "Experimental" : "Preview"} | No standalone CI fixture |`).join("\n")}\n`,
   "seo-metadata-matrix.md": `# SEO metadata matrix\n\nEvery canonical portal page defines a unique descriptive title, description, and absolute canonical. Package metadata is generated from installed package metadata. Sitemap and robots cover portal, guides, release, and package routes. Structured-data support is not exposed by the installed .wrn SEO grammar and remains a framework/generator gap. Preview routes remain indexable because the documentation is public; private package/source locations are not linked.\n`,
   "redirect-map.md": `# Redirect map\n\nNo legacy redirects are currently required: existing /, /getting-started, /architecture, /language, /packages, and /packages/:name remain canonical. If versioned archives are introduced, current unversioned docs should canonicalize to the active release and archived URLs must remain immutable.\n`,
   "release-checklist.md": `# Release checklist\n\n- [ ] Confirm all @wrnexus versions align with package.json#wrnexus.version.\n- [ ] Run bun install, docs:generate twice, test, check, build, and production smoke.\n- [ ] Verify clean-registry access status and CTA.\n- [ ] Crawl routes, links, anchors, canonical metadata, sitemap, robots, and AI files.\n- [ ] Run mobile/desktop accessibility and Lighthouse audits.\n- [ ] Confirm license, disclosure contact, support policy, changelog, and showcase approvals.\n- [ ] Verify no tokens, private paths, fake community links, or unsupported claims.\n`,
   "post-deploy-checklist.md": `# Post-deploy checklist\n\n1. Fetch representative HTML, robots.txt, sitemap.xml, llms.txt, llms-full.txt, and docs-index.json.\n2. Run Lighthouse mobile under controlled conditions; target performance/accessibility/SEO/best-practices >=95 with no critical accessibility issue.\n3. Run keyboard, screen reader, zoom, reduced-motion, link, anchor, and responsive overflow checks.\n4. Submit sitemap in Google Search Console and Bing Webmaster Tools after domain ownership is verified.\n5. Inspect canonical selection, rich-result eligibility, crawl errors, CSP reports, server logs, and 404s.\n6. Save dated reports under docs/audits/.\n`,
 };
-for (const [name, body] of Object.entries(auditDocs)) writeFileSync(join(docs, name), body);
+for (const [name, body] of Object.entries(auditDocs)) {
+  await writeFormatted(join(docs, name), body);
+}
 mkdirSync(join(docs, "audits"), { recursive: true });
 writeFileSync(
   join(docs, "audits", "2026-07-12-baseline.md"),