@opentf/web-cli 1.1.0 → 1.2.0

package/README.md

@@ -39,7 +39,10 @@ otfw serve          # build, then server-render each route per request (SSR)
   Picks port 3000 (scanning upward), or `--port` for an explicit one. Phase 1: the page
   becomes interactive via the client bundle (CSR mount); hydration is a later phase.
 
-`OTFWC_BIN` overrides the compiler binary location (used for compiler development).
+`OTFWC_BIN` overrides the compiler binary location. Published installs under
+`node_modules` use the packaged compiler, even when the app lives inside a Cargo
+workspace; this repository's own source checkout may build and use
+`target/debug/otfwc` for compiler development.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OTF Web dev toolchain — the Rolldown-driven CSR dev server, production build, and SSG.",
   "type": "module",
   "bin": {

package/src/build.js

@@ -29,6 +29,7 @@ import {
   readHtmlShell,
   runBlogFeed,
   runDocsSearchIndex,
+  runLlmsFiles,
   runLastUpdated,
   stampHydrateSentinel,
 } from "./shared.js";
@@ -36,17 +37,37 @@ import { fmtMs, step } from "./reporter.js";
 
 const hash = (s) => Bun.hash(s).toString(16).padStart(16, "0").slice(0, 8);
 
-// Site origin for absolute canonical / sitemap URLs. Priority: `--base-url=` flag,
-// then `otfw.config` (`{ site: { url } }`), else "" (relative canonicals, sitemap
-// skipped with a warning).
-function resolveBaseUrl(config) {
-  const flag = process.argv.find((a) => a.startsWith("--base-url="));
+// Site origin for absolute canonical / sitemap/feed URLs. Priority: `--base-url=`
+// flag, then `otfw.config` (`{ site: { url } }`).
+export function resolveBaseUrl(config, argv = process.argv) {
+  const flag = argv.find((a) => a.startsWith("--base-url="));
   if (flag) return flag.slice("--base-url=".length).replace(/\/+$/, "");
   if (config?.site?.url) return String(config.site.url).replace(/\/+$/, "");
   return "";
 }
 
+export function buildRequiresBaseUrl(config, argv = process.argv) {
+  return argv.includes("--ssg") || !!config?.docs || !!config?.blog;
+}
+
+function requireBaseUrl(config, argv = process.argv) {
+  const baseUrl = resolveBaseUrl(config, argv);
+  if (baseUrl || !buildRequiresBaseUrl(config, argv)) return baseUrl;
+  console.error(
+    `✗ site.url is required for this production build.\n` +
+      `  Add it to otfw.config.js:\n\n` +
+      `  export default defineDocsConfig({\n` +
+      `    site: { url: "https://example.com" }\n` +
+      `  })\n\n` +
+      `  Or pass --base-url=https://example.com`,
+  );
+  process.exit(1);
+}
+
 export async function runBuild(options = {}) {
+  const projectRoot = process.cwd();
+  const config = await loadConfig(projectRoot);
+  const baseUrl = requireBaseUrl(config);
   const { root, appDir, webEntry, otfwc, exclude } = loadProject();
   const t0 = performance.now();
 
@@ -63,7 +84,6 @@ export async function runBuild(options = {}) {
 
   // Docs generator: resolve `@opentf/web-docs/nav` to the build-time nav tree when
   // the project has a `docs` config block.
-  const config = await loadConfig(root);
   const docsPlugins = await loadDocsPlugins(root, appDir, config, exclude);
 
   const outDir = join(root, "dist");
@@ -145,7 +165,6 @@ export async function runBuild(options = {}) {
   // (so per-route files carry the same bundle + stylesheet links).
   let ssg = null;
   if (process.argv.includes("--ssg")) {
-    const baseUrl = resolveBaseUrl(config);
     const { runPrerender } = await import("./prerender.js");
     // Per-page last-updated map (git/frontmatter) for the article:modified_time tag.
     const lastUpdated = await runLastUpdated(root, appDir, config, exclude);
@@ -185,13 +204,20 @@ export async function runBuild(options = {}) {
     searchStep.done(`Search index — ${search?.pages ?? 0} page(s)`);
   }
 
-  // Blog RSS feed (when a `blog` block + site URL are configured). Written after the
-  // public/ copy so a project-supplied feed override isn't clobbered.
+  // Blog RSS + Atom feeds (when a `blog` block is configured). Written
+  // after the public/ copy so project-supplied feed overrides aren't clobbered.
   if (config?.blog) {
-    const feedStep = step("Generating RSS feed");
-    const feed = await runBlogFeed(root, appDir, config, outDir, resolveBaseUrl(config), exclude);
-    if (feed) feedStep.done(`RSS feed — ${feed.count} post(s) → ${feed.path}`);
-    else feedStep.done("RSS feed — skipped");
+    const feedStep = step("Generating blog feeds");
+    const feed = await runBlogFeed(root, appDir, config, outDir, baseUrl, exclude);
+    if (feed) feedStep.done(`Blog feeds — ${feed.count} post(s) → ${feed.paths.join(", ")}`);
+    else feedStep.done("Blog feeds — skipped");
+  }
+
+  if (config?.docs || config?.blog) {
+    const llmsStep = step("Generating LLM context");
+    const llms = await runLlmsFiles(root, appDir, pages, config, outDir, baseUrl);
+    if (llms) llmsStep.done(`LLM context — ${llms.paths.join(", ")}`);
+    else llmsStep.done("LLM context — skipped");
   }
 
   console.log(`\n  → dist/  ready in ${fmtMs(performance.now() - t0)}\n`);

package/src/prerender.js

@@ -6,7 +6,13 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { buildServerBundle, injectHead, injectMarkup, withHtmlLang } from "./shared.js";
+import {
+  buildServerBundle,
+  injectHead,
+  injectHydrationData,
+  injectMarkup,
+  withHtmlLang,
+} from "./shared.js";
 
 // "/" → dist/index.html, "/post/1" → dist/post/1/index.html, "/fr/about" → dist/fr/about/index.html.
 function htmlPathFor(outDir, route) {
@@ -97,7 +103,8 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
       try {
         // Passing the localized URL pins router.locale (resolveLocale) and still
         // matches the locale-agnostic route table, so `t()` renders in `locale`.
-        const { html, metadata } = (await mod.renderRoute(urlPath, params)) ?? { html: "", metadata: {} };
+        const { html, metadata, hydration } =
+          (await mod.renderRoute(urlPath, params)) ?? { html: "", metadata: {}, hydration: "" };
         const meta = i18nOn
           ? { ...metadata, links: [...(metadata.links || []), ...alternatesFor(path, locales, defaultLocale)] }
           : metadata;
@@ -108,7 +115,13 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
         if (iso) head += `\n<meta property="article:modified_time" content="${escapeXml(iso)}">`;
         const file = htmlPathFor(outDir, urlPath);
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, injectMarkup(injectHead(withHtmlLang(shellHtml, locale), head), html));
+        writeFileSync(
+          file,
+          injectHydrationData(
+            injectMarkup(injectHead(withHtmlLang(shellHtml, locale), head), html),
+            hydration,
+          ),
+        );
         rendered.push(urlPath);
       } catch (e) {
         failed.push(urlPath);
@@ -123,7 +136,10 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
     const result = await mod.renderRoute("/__otfw_404__");
     if (result) {
       const head = mod.renderHead({ robots: "noindex", ...result.metadata }, { baseUrl });
-      writeFileSync(join(outDir, "404.html"), injectMarkup(injectHead(shellHtml, head), result.html));
+      writeFileSync(
+        join(outDir, "404.html"),
+        injectHydrationData(injectMarkup(injectHead(shellHtml, head), result.html), result.hydration),
+      );
     }
   } catch {
     /* no 404 page */

package/src/serve.js

@@ -33,6 +33,7 @@ import {
   buildServerBundle,
   discoverPages,
   injectHead,
+  injectHydrationData,
   injectMarkup,
   loadConfig,
   loadDocsPlugins,
@@ -189,7 +190,10 @@ export async function runServe() {
       : result.metadata;
     const head = mod.renderHead(meta, { path: url.pathname, baseUrl });
     const localizedShell = i18nOn ? withHtmlLang(shell, localeOf(url.pathname)) : shell;
-    const html = injectMarkup(injectHead(localizedShell, head), result.html);
+    const html = injectHydrationData(
+      injectMarkup(injectHead(localizedShell, head), result.html),
+      result.hydration,
+    );
     // 200 for a real route; 404 when the path fell back to the registered 404 page.
     return new Response(html, {
       status: result.status ?? 200,

package/src/shared.js

@@ -59,6 +59,20 @@ export function injectMarkup(shellHtml, markup) {
   return shellHtml.replace(/(<div id="app"[^>]*>)\s*(<\/div>)/, (_m, open, close) => `${open}${markup}${close}`);
 }
 
+/**
+ * Embed the island hydration payload (`renderRoute().hydration`) as a
+ * `<script type="application/json" id="__otfw_h">` the client reads at upgrade so
+ * components resume from rich JS props (compiler-driven data hydration). Placed before
+ * `</body>`; a deferred module bundle runs after parse, so the payload is always in the
+ * DOM first. `json` is already `<`-escaped by the server collector, so it can't break out
+ * of the script. No-op for an empty payload. Uses a function replacer so `$` in the JSON
+ * stays literal.
+ */
+export function injectHydrationData(shellHtml, json) {
+  if (!json) return shellHtml;
+  return injectBeforeBody(shellHtml, `<script type="application/json" id="__otfw_h">${json}</script>`);
+}
+
 /**
  * Stamp the `data-otfw-hydrate` sentinel onto the shell's `#app` container, telling
  * the client to *adopt* the server-rendered DOM on first paint instead of rebuilding
@@ -105,10 +119,45 @@ export function findUp(name, from) {
   }
 }
 
+function hasLocalCompilerWorkspace(workspace) {
+  return !!workspace && existsSync(join(workspace, "crates", "otfw_cli", "Cargo.toml"));
+}
+
+export function resolveCompiler({
+  cliDir = dirname(fileURLToPath(import.meta.url)),
+  env = process.env,
+  resolvePackagedCompiler = otfwcPath,
+  findWorkspace = findUp,
+  ensure = ensureCompiler,
+} = {}) {
+  if (env.OTFWC_BIN) return { otfwc: env.OTFWC_BIN, workspace: null };
+
+  let packagedError = null;
+  try {
+    return { otfwc: resolvePackagedCompiler(), workspace: null };
+  } catch (e) {
+    packagedError = e;
+  }
+
+  const installedPackage = cliDir.split(/[\\/]/).includes("node_modules");
+  const workspace = installedPackage ? null : findWorkspace("Cargo.toml", cliDir);
+  if (hasLocalCompilerWorkspace(workspace)) {
+    const otfwc = join(workspace, "target", "debug", "otfwc");
+    ensure(otfwc, workspace);
+    return { otfwc, workspace };
+  }
+
+  fail(
+    `${packagedError?.message ?? "cannot resolve @opentf/web-compiler prebuilt binary"}\n` +
+      `  No local otfwc compiler workspace was found to build from source.`,
+  );
+}
+
 /**
  * Resolve the project and toolchain: the app being built (cwd), the runtime
  * package, the `otfwc` compiler, and the excluded routes. Exits with a clear
- * message on any hard failure. Builds the compiler on demand from the workspace.
+ * message on any hard failure. Source checkouts can build the compiler on demand
+ * from this repo's Cargo workspace; published installs use @opentf/web-compiler.
  */
 export function loadProject() {
   const root = process.cwd();
@@ -129,25 +178,9 @@ export function loadProject() {
     fail(`cannot resolve "@opentf/web" from ${root}\n  add it to your dependencies.`);
   }
 
-  // Locate the `otfwc` compiler. Published: the prebuilt binary from `@opentf/web-compiler`
-  // (a dependency of this CLI). In this repo's own dev (a Cargo workspace is found
-  // above the CLI): the cargo `target/debug` build, rebuilt on demand. `OTFWC_BIN`
-  // overrides both.
-  const cliDir = dirname(fileURLToPath(import.meta.url));
-  const workspace = findUp("Cargo.toml", cliDir);
-  let otfwc;
-  if (process.env.OTFWC_BIN) {
-    otfwc = process.env.OTFWC_BIN;
-  } else if (workspace) {
-    otfwc = join(workspace, "target", "debug", "otfwc");
-    ensureCompiler(otfwc, workspace);
-  } else {
-    try {
-      otfwc = otfwcPath();
-    } catch (e) {
-      fail(e.message);
-    }
-  }
+  // Locate the `otfwc` compiler. Explicit overrides win, then the packaged
+  // compiler binary, then this repo's local Rust workspace as a source fallback.
+  const { otfwc, workspace } = resolveCompiler();
 
   // Route directories to skip during discovery — comma-separated names in
   // EXCLUDE_ROUTES. None are excluded by default.
@@ -162,6 +195,19 @@ function ensureCompiler(otfwc, workspace) {
   if (existsSync(otfwc)) return;
   if (!workspace) fail(`otfwc compiler not found at ${otfwc}`);
   console.log("building compiler (cargo build -p otfw_cli)…");
+  const cargo = Bun.spawnSync(["cargo", "--version"], {
+    cwd: workspace,
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  if (cargo.error || cargo.exitCode !== 0) {
+    fail(
+      `cannot build otfwc because cargo is not available.\n` +
+        `  This source checkout needs Rust/Cargo to build ${otfwc}.\n` +
+        `  Install Rust in the build environment, set OTFWC_BIN to an existing otfwc binary,\n` +
+        `  or build with the published @opentf/web-cli package so @opentf/web-compiler can use its prebuilt binary.`,
+    );
+  }
   const b = Bun.spawnSync(["cargo", "build", "-p", "otfw_cli"], {
     cwd: workspace,
     stdout: "inherit",
@@ -271,43 +317,86 @@ export async function runDocsSearchIndex(root, config, siteDir, onProgress) {
 }
 
 /**
- * Generate the blog RSS feed when the project has a `blog` config and a base URL.
- * Scans the post folders, renders RSS 2.0, and writes `<siteDir>/<blogDir>/rss.xml`.
- * A project-supplied `public/<blogDir>/rss.xml` takes precedence (it overwrites ours
- * on the public/ copy). Returns `{ path, url, count }` or null (no blog / no base URL
- * / package missing). Resolved from the app's `@opentf/web-docs`.
+ * Generate blog feeds when the project has a `blog` config and a base URL. Scans the
+ * post folders, renders RSS 2.0 + Atom 1.0, and writes them under
+ * `<siteDir>/<blogDir>/`. Project-supplied `public/<blogDir>/{rss,atom}.xml` files
+ * take precedence independently. Returns `{ paths, urls, count }` or null (no blog /
+ * no base URL / all feeds overridden / package missing). Resolved from the app's
+ * `@opentf/web-docs`.
  */
 export async function runBlogFeed(root, appDir, config, siteDir, baseUrl, exclude = new Set()) {
   const blog = config?.blog;
   if (!blog) return null;
   if (!baseUrl) {
-    console.warn("⚠ blog RSS feed skipped: no site URL (pass --base-url or set otfw.config)");
+    console.warn("⚠ blog feeds skipped: no site URL (pass --base-url or set otfw.config)");
     return null;
   }
   const contentDir = blog.dir ?? "blog";
-  if (existsSync(join(root, "public", contentDir, "rss.xml"))) return null; // honor override
   try {
     const entry = Bun.resolveSync("@opentf/web-docs/build", root);
-    const { loadPosts, renderBlogFeed } = await import(pathToFileURL(entry).href);
+    const { loadPosts, renderAtomFeed, renderBlogFeed } = await import(pathToFileURL(entry).href);
     const posts = loadPosts({ appDir, contentDir, exclude });
-    const feedPath = `/${contentDir}/rss.xml`;
     const title = blog.title || (config?.docs?.title ? `${config.docs.title} Blog` : "Blog");
-    const xml = renderBlogFeed({
-      posts,
-      baseUrl,
-      feedPath,
-      channel: {
-        title,
-        description: blog.description || title,
-        link: `/${contentDir}`,
+    const channel = {
+      title,
+      description: blog.description || title,
+      link: `/${contentDir}`,
+    };
+    const feeds = [
+      {
+        file: "rss.xml",
+        path: `/${contentDir}/rss.xml`,
+        render: renderBlogFeed,
       },
-    });
-    const out = join(siteDir, contentDir, "rss.xml");
-    mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, xml);
-    return { path: feedPath, url: baseUrl.replace(/\/+$/, "") + feedPath, count: posts.length };
+      {
+        file: "atom.xml",
+        path: `/${contentDir}/atom.xml`,
+        render: renderAtomFeed,
+      },
+    ];
+    const written = [];
+    for (const feed of feeds) {
+      if (existsSync(join(root, "public", contentDir, feed.file))) continue; // honor override
+      const out = join(siteDir, contentDir, feed.file);
+      mkdirSync(dirname(out), { recursive: true });
+      writeFileSync(out, feed.render({ posts, baseUrl, feedPath: feed.path, channel }));
+      written.push(feed.path);
+    }
+    if (!written.length) return null;
+    const origin = baseUrl.replace(/\/+$/, "");
+    return { paths: written, urls: written.map((path) => origin + path), count: posts.length };
+  } catch (e) {
+    console.warn(`⚠ blog feeds skipped: ${e?.message ?? e}`);
+    return null;
+  }
+}
+
+/**
+ * Generate `/llms.txt` and `/llms-full.txt` for docs/blog sites from the same
+ * filesystem route list used by the app build. Project-supplied public files override
+ * each output independently.
+ */
+export async function runLlmsFiles(root, appDir, pages, config, siteDir, baseUrl) {
+  if (!config?.docs && !config?.blog) return null;
+  const outputs = [
+    { file: "llms.txt", render: "renderLlmsTxt" },
+    { file: "llms-full.txt", render: "renderLlmsFullTxt" },
+  ].filter((out) => !existsSync(join(root, "public", out.file)));
+  if (!outputs.length) return null;
+
+  try {
+    const entry = Bun.resolveSync("@opentf/web-docs/build", root);
+    const mod = await import(pathToFileURL(entry).href);
+    const written = [];
+    for (const out of outputs) {
+      const render = mod[out.render];
+      if (typeof render !== "function") continue;
+      writeFileSync(join(siteDir, out.file), render({ appDir, pages, baseUrl, config }));
+      written.push(`/${out.file}`);
+    }
+    return written.length ? { paths: written } : null;
   } catch (e) {
-    console.warn(`⚠ blog RSS feed skipped: ${e?.message ?? e}`);
+    console.warn(`⚠ llms.txt skipped: ${e?.message ?? e}`);
     return null;
   }
 }