@opentf/afw-cli 0.0.0-stage → 1.30.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.
package/README.md CHANGED
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ # @opentf/afw-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The SSG library used by AFW projects during `esdev build`. The package retains
4
+ its historical name, but the `afw` executable and its dev/build/serve commands
5
+ have been retired.
6
+
7
+ ## Installation
8
+
9
+ For projects with a prerender script:
10
+
11
+ ```bash
12
+ pnpm add -D @opentf/afw-cli @opentf/esdev-plugin-afw
13
+ ```
14
+
15
+ Apps also depend on `@opentf/afw`. Install esdev 0.16 or newer and configure the
16
+ AFW compiler/routes plugin in `esdev.json`.
17
+
18
+ ## Development and builds
19
+
20
+ ```bash
21
+ esdev start
22
+ esdev build --minify
23
+ esdev preview
24
+ ```
25
+
26
+ The project owns its HTML entry and build targets. For static rendering, add a
27
+ second target with a prerender entry and `"then": "run"`, following this repo's
28
+ [`website/esdev.json`](../../website/esdev.json) and [`website/ssg.js`](../../website/ssg.js).
29
+ The script checks for release staging and prerenders pages, including sitemap and
30
+ robots output. A release-only `siteOutputPlugin` then generates search, feeds and
31
+ LLM files in staging before publication:
32
+
33
+ ```json
34
+ { "module": "@opentf/afw-cli/ssg", "export": "siteOutputPlugin",
35
+ "options": { "target": "web", "prerenderTarget": "site-ssg", "root": "." } }
36
+ ```
37
+
38
+ Add that object to the project-level `plugins`. `root` locates the source site
39
+ relative to the project working directory; `target` selects the browser output.
40
+ The prerender step calls `writePrerenderReport(outDir, result)` with the return
41
+ value of `runPrerender`, preserving resolved site descriptions for LLM context.
42
+ The hook consumes and removes the temporary report before publication.
43
+
44
+ The hook never runs during `esdev start`. When `prerenderTarget` is configured,
45
+ a selected build omitting it skips generation rather than indexing a CSR shell.
46
+ Building both targets without the report fails with a configuration error.
47
+ Indexing failures fail the build and leave the previous deployment intact.
48
+
49
+ ## SSG exports
50
+
51
+ Import helpers from `@opentf/afw-cli/ssg`. This stable entry exposes route/loader
52
+ collection, compiler resolution, `runPrerender`, API/loader bundle emission,
53
+ docs build helpers and build reporting. It does not supply a dev server or an
54
+ SSR request server. A fullstack app must provide its own server entry and adapter.
55
+
56
+ `AFWC_BIN` overrides the unified toolchain binary. Compilation and documentation
57
+ indexing (`afwc docs index`) use that same executable. Published installations
58
+ use the archive shipped by `@opentf/afw-compiler`; this repository can use its
59
+ Cargo debug build.
60
+
61
+ ## Starter
62
+
63
+ `esdev create <dir> --template=docs` generates a project wired this way: a
64
+ `site-ssg` prerender target plus the `siteOutputPlugin` hook.
65
+
66
+ ## License
67
+
68
+ MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation).
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "@opentf/afw-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.30.0",
4
+ "description": "AFW SSG library — the pre-render driver for `esdev build` (`@opentf/afw-cli/ssg`). The `afw` dev-server/build commands are retired; apps build straight from esdev.json.",
5
+ "type": "module",
6
+ "exports": {
7
+ "./ssg": "./src/ssg.js"
8
+ },
9
+ "files": [
10
+ "src"
11
+ ],
12
+ "engines": {
13
+ "esdev": ">=0.16.0"
14
+ },
15
+ "dependencies": {
16
+ "@opentf/esdev-plugin-afw": "0.4.0"
17
+ },
18
+ "peerDependencies": {
19
+ "@opentf/afw": "0.32.0"
20
+ },
21
+ "keywords": [
22
+ "opentf",
23
+ "web",
24
+ "ssg",
25
+ "esdev",
26
+ "toolchain"
27
+ ],
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "https://github.com/Open-Tech-Foundation/afw.git",
31
+ "directory": "packages/afw-cli"
32
+ },
33
+ "homepage": "https://github.com/Open-Tech-Foundation/afw#readme",
34
+ "bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
35
+ "license": "MIT",
36
+ "publishConfig": {
37
+ "access": "public"
38
+ }
39
+ }
package/src/output.js ADDED
@@ -0,0 +1,61 @@
1
+ // Release-only output work, after every target and prerender step has finished.
2
+ import { file, remove } from "runtime:fs";
3
+ import { join, resolve } from "runtime:path";
4
+ import { cwd, env } from "runtime:process";
5
+ import { exists, writeFile } from "./runtime.js";
6
+ import { discoverPages, loadConfig, resolveCompiler, runBlogFeed, runDocsSearchIndex, runLlmsFiles } from "./shared.js";
7
+ import { step } from "./reporter.js";
8
+
9
+ const REPORT = ".afw-prerender.json";
10
+
11
+ /** Hand resolved render metadata to the finish hook without recompiling pages. */
12
+ export async function writePrerenderReport(outDir, result) {
13
+ await writeFile(join(outDir, REPORT), JSON.stringify({ siteDescription: result.siteDescription ?? "" }));
14
+ }
15
+
16
+ /** esdev project plugin (release-only `finish` hook); output paths come from staging, never from config. */
17
+ export function siteOutputPlugin({ root = ".", target = "web", prerenderTarget, exclude = [] } = {}) {
18
+ const siteRoot = resolve(cwd(), root);
19
+ return {
20
+ name: "afw-site-output",
21
+ finish: {
22
+ async handler(targets) {
23
+ const output = targets[target];
24
+ if (!output) return;
25
+ // A selected browser-only build has no prerender step and must not index CSR.
26
+ if (prerenderTarget && !targets[prerenderTarget]) return;
27
+ if (output.platform !== "browser") throw new Error(`Site output target "${target}" must be a browser target`);
28
+ const siteDir = output.outDir;
29
+ const reportPath = join(siteDir, REPORT);
30
+ let siteDescription = "";
31
+ if (await exists(reportPath)) {
32
+ ({ siteDescription } = await file(reportPath).json());
33
+ await remove(reportPath);
34
+ } else if (prerenderTarget) {
35
+ throw new Error(`Prerender target "${prerenderTarget}" must call writePrerenderReport(outDir, result)`);
36
+ }
37
+ const config = await loadConfig(siteRoot);
38
+ const appDir = join(siteRoot, "app");
39
+ const excluded = new Set([...exclude, ...(env.EXCLUDE_ROUTES ?? "").split(",").filter(Boolean)]);
40
+ const baseUrl = String(config?.site?.url ?? "").replace(/\/+$/, "");
41
+ if (config?.docs?.search?.provider === "afw") {
42
+ const progress = step("Building search index");
43
+ const { afwc } = await resolveCompiler();
44
+ const search = await runDocsSearchIndex(siteRoot, config, siteDir, afwc);
45
+ progress.done(`Search index — ${search?.pages ?? 0} page(s)`);
46
+ }
47
+ if (config?.blog) {
48
+ const progress = step("Generating blog feeds");
49
+ const feed = await runBlogFeed(siteRoot, appDir, config, siteDir, baseUrl, excluded);
50
+ progress.done(feed ? `Blog feeds — ${feed.count} post(s) → ${feed.paths.join(", ")}` : "Blog feeds — skipped");
51
+ }
52
+ if (config?.docs || config?.blog) {
53
+ const progress = step("Generating LLM context");
54
+ const pages = await discoverPages(appDir, excluded);
55
+ const llms = await runLlmsFiles(siteRoot, appDir, pages, config, siteDir, baseUrl, { siteDescription });
56
+ progress.done(llms ? `LLM context — ${llms.paths.join(", ")}` : "LLM context — skipped");
57
+ }
58
+ },
59
+ },
60
+ };
61
+ }
@@ -0,0 +1,216 @@
1
+ // SSG pre-render (ARCHITECTURE.md §6): build a *server* bundle of the app with the
2
+ // compiler's SSG backend (HTML-string renderers), then run it in-process to
3
+ // render each route to a static HTML file. No DOM — the SSG output is pure string
4
+ // concatenation, so no effects/lifecycle run.
5
+
6
+ import { dirname, join } from "runtime:path";
7
+
8
+ import { exists, writeFile } from "./runtime.js";
9
+
10
+ import {
11
+ DATA_FILE,
12
+ buildServerBundle,
13
+ injectHead,
14
+ injectHydrationData,
15
+ injectMarkup,
16
+ injectRouteData,
17
+ modulepreloadTags,
18
+ stampRenderedPath,
19
+ withHtmlLang,
20
+ } from "./shared.js";
21
+
22
+ // "/" → dist/index.html, "/post/1" → dist/post/1/index.html, "/fr/about" → dist/fr/about/index.html.
23
+ function htmlPathFor(outDir, route) {
24
+ return route === "/" ? join(outDir, "index.html") : join(outDir, route, "index.html");
25
+ }
26
+
27
+ // Prefix a locale-agnostic route with `locale` (bare for the default) — the URL form
28
+ // that both selects the output file and, passed to renderRoute, pins router.locale.
29
+ function localizeFor(path, locale, defaultLocale) {
30
+ if (!locale || locale === defaultLocale) return path;
31
+ return path === "/" ? `/${locale}` : `/${locale}${path}`;
32
+ }
33
+
34
+ // `rel="alternate" hreflang` descriptors for a route across all locales (+ x-default),
35
+ // merged into metadata.links so renderHead emits them (docs/I18N.md §6).
36
+ function alternatesFor(path, locales, defaultLocale) {
37
+ const links = locales.map((l) => ({
38
+ rel: "alternate",
39
+ hreflang: l,
40
+ href: localizeFor(path, l, defaultLocale),
41
+ }));
42
+ links.push({ rel: "alternate", hreflang: "x-default", href: localizeFor(path, defaultLocale, defaultLocale) });
43
+ return links;
44
+ }
45
+
46
+ // Absolute URL for sitemap/robots; "" if no base URL configured.
47
+ function absoluteUrl(baseUrl, path) {
48
+ if (!baseUrl) return "";
49
+ return baseUrl.replace(/\/+$/, "") + (path === "/" ? "/" : path);
50
+ }
51
+
52
+ // Emit sitemap.xml (absolute <loc> per rendered path, with <lastmod> where the
53
+ // last-updated map knows the path) — requires a base URL. A project-supplied
54
+ // public/sitemap.xml takes precedence (it overwrites ours on copy).
55
+ async function writeSitemap(outDir, publicDir, baseUrl, paths, lastUpdated = {}) {
56
+ if (await exists(join(publicDir, "sitemap.xml"))) return false;
57
+ if (!baseUrl) {
58
+ console.warn("⚠ sitemap.xml skipped: no site URL (pass --base-url or set afw.config)");
59
+ return false;
60
+ }
61
+ const urls = paths
62
+ .map((p) => {
63
+ const lastmod = lastUpdated[p] ? `<lastmod>${escapeXml(lastUpdated[p])}</lastmod>` : "";
64
+ return ` <url><loc>${escapeXml(absoluteUrl(baseUrl, p))}</loc>${lastmod}</url>`;
65
+ })
66
+ .join("\n");
67
+ const xml =
68
+ `<?xml version="1.0" encoding="UTF-8"?>\n` +
69
+ `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
70
+ await writeFile(join(outDir, "sitemap.xml"), xml);
71
+ return true;
72
+ }
73
+
74
+ // Emit a permissive robots.txt referencing the sitemap (honor a public/ override).
75
+ async function writeRobots(outDir, publicDir, baseUrl, hasSitemap) {
76
+ if (await exists(join(publicDir, "robots.txt"))) return false;
77
+ let body = "User-agent: *\nAllow: /\n";
78
+ if (baseUrl && hasSitemap) body += `Sitemap: ${absoluteUrl(baseUrl, "/sitemap.xml")}\n`;
79
+ await writeFile(join(outDir, "robots.txt"), body);
80
+ return true;
81
+ }
82
+
83
+ function escapeXml(s) {
84
+ return String(s).replace(/[&<>'"]/g, (c) =>
85
+ c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === "'" ? "&apos;" : "&quot;",
86
+ );
87
+ }
88
+
89
+ /**
90
+ * Pre-render the app to static HTML files under `outDir`. Returns
91
+ * `{ count, skipped, failed, siteDescription }` — `siteDescription` is the site's own
92
+ * `<meta name="description">` text (home route, falling back to the root layout's
93
+ * route-independent metadata), which `llms.txt` uses for its summary line.
94
+ */
95
+ export async function runPrerender({ root, pages, afwEntry, afwc, shellHtml, outDir, baseUrl = "", docsPlugins = [], lastUpdated = {}, i18n = null, loaders = null, chunkManifest = null, onCompile, onRender }) {
96
+ const { mod, cleanup } = await buildServerBundle({ root, pages, afwEntry, afwc, docsPlugins, i18n, onCompile });
97
+
98
+ // i18n (docs/I18N.md §6): pre-render each route once per locale. The default
99
+ // locale is emitted bare (dist/<route>/index.html), others under their prefix
100
+ // (dist/<locale>/<route>/index.html). A single `[null]` means i18n is off — the
101
+ // loop collapses to the original one-render-per-route behavior.
102
+ const i18nOn = !!(i18n && Array.isArray(i18n.locales) && i18n.locales.length);
103
+ const locales = i18nOn ? i18n.locales : [null];
104
+ const defaultLocale = i18nOn ? i18n.defaultLocale : null;
105
+
106
+ const { paths, skipped } = await mod.collectRoutePaths();
107
+
108
+ // `<link rel="modulepreload">` for the page + layout chunks this route will import,
109
+ // so the browser fetches them in parallel with `bundle.js` rather than after it.
110
+ const preloadFor = (route) => modulepreloadTags(chunkManifest?.routes?.[route]);
111
+ const failed = [];
112
+ const rendered = []; // concrete paths that produced an HTML file (for the sitemap)
113
+ let renderedCount = 0;
114
+ let siteDescription = ""; // the home route's resolved description (see the JSDoc above)
115
+ for (const { path, params, route } of paths) {
116
+ onRender?.(++renderedCount, paths.length);
117
+ for (const locale of locales) {
118
+ const urlPath = localizeFor(path, locale, defaultLocale);
119
+ try {
120
+ // Route loader (docs/DATA.md): run it at build time with no `request` and
121
+ // an empty query (a query-dependent loader needs a request server). The result
122
+ // is threaded into the render (`router.data`), inlined into the HTML, and
123
+ // written as a sibling `__data.json` — per locale, since a localized
124
+ // loader can return locale-dependent data.
125
+ const m = loaders?.match(urlPath);
126
+ let data;
127
+ let dataJson = "";
128
+ if (m) ({ data, json: dataJson } = await loaders.loadSerialized(m, { query: {} }));
129
+
130
+ // Passing the localized URL pins router.locale (resolveLocale) and still
131
+ // matches the locale-agnostic route table, so `t()` renders in `locale`.
132
+ const { html, metadata, hydration } =
133
+ (await mod.renderRoute(urlPath, params, "", { data })) ?? { html: "", metadata: {}, hydration: "" };
134
+ const meta = i18nOn
135
+ ? { ...metadata, links: [...(metadata.links || []), ...alternatesFor(path, locales, defaultLocale)] }
136
+ : metadata;
137
+ if (path === "/" && (!locale || locale === defaultLocale) && typeof metadata?.description === "string") {
138
+ siteDescription = metadata.description;
139
+ }
140
+ let head = mod.renderHead(meta, { path: urlPath, baseUrl, managed: true });
141
+ const preload = preloadFor(route);
142
+ if (preload) head += `\n${preload}`;
143
+ // SEO: expose the page's last-updated time (git/frontmatter) as Open Graph's
144
+ // article:modified_time so crawlers see when the content actually changed,
145
+ // and a frontmatter `date` as article:published_time (blog posts).
146
+ const iso = lastUpdated[path];
147
+ if (iso) head += `\n<meta data-afw-head="" property="article:modified_time" content="${escapeXml(iso)}">`;
148
+ const published = typeof metadata?.date === "string" ? metadata.date.trim() : "";
149
+ if (published) head += `\n<meta data-afw-head="" property="article:published_time" content="${escapeXml(published)}">`;
150
+ // Static hosts decode requested URLs when locating files. Decode generated
151
+ // segments once; leave literal static folder names unchanged.
152
+ const outputPath = Object.keys(params).length
153
+ ? urlPath.split("/").map(decodeURIComponent).join("/") : urlPath;
154
+ const file = htmlPathFor(outDir, outputPath);
155
+ await writeFile(
156
+ file,
157
+ injectRouteData(
158
+ injectHydrationData(
159
+ injectMarkup(injectHead(withHtmlLang(stampRenderedPath(shellHtml, urlPath), locale), head), html),
160
+ hydration,
161
+ ),
162
+ dataJson,
163
+ ),
164
+ );
165
+ if (m) {
166
+ // The static data file SPA navigation fetches on a plain static host —
167
+ // byte-identical to the inline payload ("null" when the loader returned
168
+ // undefined, so a 200 still parses as JSON).
169
+ const dataFile = join(dirname(file), DATA_FILE);
170
+ await writeFile(dataFile, dataJson || "null");
171
+ }
172
+ rendered.push(urlPath);
173
+ } catch (e) {
174
+ failed.push(urlPath);
175
+ const why = e?.afwNotFound ? "loader called notFound()" : (e?.message ?? e);
176
+ console.error(`✗ pre-render failed for ${urlPath}: ${why}`);
177
+ }
178
+ }
179
+ }
180
+
181
+ // 404: any unmatched path resolves to the registered 404 page. Mark noindex so
182
+ // crawlers don't index the error page, and keep it out of the sitemap.
183
+ try {
184
+ const result = await mod.renderRoute("/__afw_404__");
185
+ if (result) {
186
+ let head = mod.renderHead({ robots: "noindex", ...result.metadata }, { baseUrl, managed: true });
187
+ const preload = modulepreloadTags(chunkManifest?.notFound);
188
+ if (preload) head += `\n${preload}`;
189
+ await writeFile(
190
+ join(outDir, "404.html"),
191
+ injectHydrationData(injectMarkup(injectHead(shellHtml, head), result.html), result.hydration),
192
+ );
193
+ }
194
+ } catch {
195
+ /* no 404 page */
196
+ }
197
+
198
+ // Crawl infrastructure: sitemap.xml + robots.txt (honoring public/ overrides).
199
+ const publicDir = join(root, "public");
200
+ const hasSitemap = await writeSitemap(outDir, publicDir, baseUrl, rendered, lastUpdated);
201
+ await writeRobots(outDir, publicDir, baseUrl, hasSitemap);
202
+
203
+ // No "/" route (or it declared no description): fall back to the layout chain's
204
+ // route-independent metadata — the site-wide description every route inherits.
205
+ if (!siteDescription) {
206
+ try {
207
+ const siteMeta = await mod.resolveMetadata({ route: "/", entry: null });
208
+ if (typeof siteMeta?.description === "string") siteDescription = siteMeta.description;
209
+ } catch {
210
+ /* no root layout metadata */
211
+ }
212
+ }
213
+
214
+ cleanup();
215
+ return { count: rendered.length, skipped, failed, siteDescription };
216
+ }
@@ -0,0 +1,103 @@
1
+ // Build reporter. Each phase is a "step" that announces itself, then collapses to a
2
+ // green ✅ line with the elapsed time when done.
3
+ //
4
+ // On a terminal the announcement is a spinner that stays on one line and shows what
5
+ // the phase is working on. Anywhere else — CI, a piped log, a file — there is nothing
6
+ // to animate and no width to fit into, so the step prints one line when it starts and
7
+ // one when it ends, which is what a log wants to hold anyway.
8
+
9
+ // `stdout` is esdev's, not esrun's: naming it in a static import is a load-time
10
+ // SyntaxError under the runtime a released CLI would run on. Reached through the
11
+ // namespace it is simply absent there, which is the same answer as "no terminal".
12
+ const { stdout } = await import("runtime:process");
13
+
14
+ const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
15
+ const FRAME_IN = "•";
16
+ const INTERVAL = 80;
17
+
18
+ const animated = () => Boolean(stdout?.isTTY);
19
+ const width = () => stdout?.columns ?? 80;
20
+
21
+ /** Humanize a millisecond duration: 940ms, 5.2s. */
22
+ export function fmtMs(n) {
23
+ return n < 1000 ? `${Math.round(n)}ms` : `${(n / 1000).toFixed(1)}s`;
24
+ }
25
+
26
+ /** Cut `s` to the terminal width, so a long path cannot wrap and orphan a line. */
27
+ function fit(s) {
28
+ const max = width() - 1;
29
+ return s.length <= max ? s : `${s.slice(0, Math.max(0, max - 1))}…`;
30
+ }
31
+
32
+ // The step currently drawing, if any. A spinner owns the last line of the terminal,
33
+ // so anything else that prints has to take the line back first — see `quiet`.
34
+ let live = null;
35
+
36
+ /**
37
+ * Stop whatever is spinning and clear its line, so a diagnostic printed from deep
38
+ * inside a build starts on a clean one. `console` is read-only here, so this is a
39
+ * call the printer makes rather than something the reporter can arrange for it.
40
+ */
41
+ export function quiet() {
42
+ live?.stop();
43
+ }
44
+
45
+ class Step {
46
+ constructor(label) {
47
+ this.label = label;
48
+ this.detail = "";
49
+ this.t0 = performance.now();
50
+ this.frame = 0;
51
+ this.timer = null;
52
+
53
+ if (!animated()) return void console.log(` ${FRAME_IN} ${label}…`);
54
+ live = this;
55
+ this.draw();
56
+ this.timer = setInterval(() => {
57
+ this.frame = (this.frame + 1) % FRAMES.length;
58
+ this.draw();
59
+ }, INTERVAL);
60
+ }
61
+
62
+ draw() {
63
+ const detail = this.detail ? ` ${this.detail}` : "";
64
+ stdout.write(`\r${fit(` ${FRAMES[this.frame]} ${this.label}…${detail}`)}`);
65
+ }
66
+
67
+ /**
68
+ * Record the live detail (the current file, an `N/total` count). On a terminal it
69
+ * rides along on the spinner's line; elsewhere nothing is printed — that would be
70
+ * one line per compiled module — but the last value is kept so a failure can say
71
+ * how far the phase got.
72
+ */
73
+ update(detail) {
74
+ this.detail = detail || "";
75
+ if (this.timer) this.draw();
76
+ }
77
+
78
+ /** Finish the step: green ✅ with `msg` (defaults to the label) and elapsed time. */
79
+ done(msg) {
80
+ this.stop();
81
+ console.log(` ✅ ${msg || this.label} ${fmtMs(performance.now() - this.t0)}`);
82
+ }
83
+
84
+ /** Mark the step failed: red ✗ with `msg`, plus how far it had got. */
85
+ fail(msg) {
86
+ const where = this.detail ? ` (at ${this.detail})` : "";
87
+ this.stop();
88
+ console.log(` ✗ ${msg || this.label}${where}`);
89
+ }
90
+
91
+ stop() {
92
+ if (!this.timer) return;
93
+ clearInterval(this.timer);
94
+ this.timer = null;
95
+ stdout.write("\r");
96
+ live = null;
97
+ }
98
+ }
99
+
100
+ /** Start a build phase. Returns a `Step` you drive with `.update()` then `.done()`. */
101
+ export function step(label) {
102
+ return new Step(label);
103
+ }
package/src/runtime.js ADDED
@@ -0,0 +1,135 @@
1
+ // Host primitives for the SSG library on the ES-Runtime (`esdev`).
2
+ //
3
+ // Everything the prerender needs from the host that is not the bundler: awaited
4
+ // filesystem helpers (`runtime:fs` is async-only by design) and package
5
+ // resolution anchored at the *project* rather than at this file.
6
+
7
+ import { exists as fsExists, file, mkdir, readDir, realPath, remove, write } from "runtime:fs";
8
+ import { dirname, fromFileURL, join } from "runtime:path";
9
+
10
+ // ------------------------------------------------------------------ filesystem
11
+
12
+ /**
13
+ * Whether `path` exists. Also false when it sits outside the write/read grant —
14
+ * a caller asking "is this here?" wants an answer, not a capability error.
15
+ */
16
+ export async function exists(path) {
17
+ try {
18
+ return await fsExists(path);
19
+ } catch {
20
+ return false;
21
+ }
22
+ }
23
+
24
+ export const readText = (path) => file(path).text();
25
+
26
+ /** Write `data`, creating the parent directory — `writeFileSync` never had to be told. */
27
+ export async function writeFile(path, data) {
28
+ await mkdir(dirname(path), { recursive: true });
29
+ await write(path, data);
30
+ }
31
+
32
+ export const mkdirp = (dir) => mkdir(dir, { recursive: true });
33
+
34
+ /** Remove a tree, tolerating "already gone" (the `force: true` of `rmSync`). */
35
+ export async function rmrf(dir) {
36
+ try {
37
+ await remove(dir, { recursive: true });
38
+ } catch {}
39
+ }
40
+
41
+ /** Directory entries, or `[]` when the directory is missing. */
42
+ export async function readEntries(dir) {
43
+ try {
44
+ return await readDir(dir);
45
+ } catch {
46
+ return [];
47
+ }
48
+ }
49
+
50
+ /** Nearest ancestor directory of `from` (inclusive) that contains `name`. */
51
+ export async function findUp(name, from) {
52
+ let dir = from;
53
+ for (;;) {
54
+ if (await exists(join(dir, name))) return dir;
55
+ const parent = dirname(dir);
56
+ if (parent === dir) return null;
57
+ dir = parent;
58
+ }
59
+ }
60
+
61
+ // ------------------------------------------------------------------ resolution
62
+
63
+ /**
64
+ * Resolve `sub` ("." or "./x") through a package's `exports` map, the way a node
65
+ * resolver would. `conditions` are tried in order — JS wants `import`/`default`, a
66
+ * stylesheet commonly sits behind `style`.
67
+ */
68
+ export function throughExports(exports, sub, conditions = ["import", "default"]) {
69
+ if (exports == null) return null;
70
+ if (typeof exports === "string") return sub === "." ? exports : null;
71
+ if (Array.isArray(exports)) {
72
+ for (const e of exports) {
73
+ const r = throughExports(e, sub, conditions);
74
+ if (r) return r;
75
+ }
76
+ return null;
77
+ }
78
+ const keys = Object.keys(exports);
79
+ if (keys.some((k) => k.startsWith("."))) {
80
+ if (exports[sub] !== undefined) return throughExports(exports[sub], ".", conditions);
81
+ for (const k of keys) {
82
+ const star = k.indexOf("*"); // "./x/*" subpath patterns
83
+ if (star < 0) continue;
84
+ const pre = k.slice(0, star);
85
+ const post = k.slice(star + 1);
86
+ if (sub.length >= pre.length + post.length && sub.startsWith(pre) && sub.endsWith(post)) {
87
+ const filled = sub.slice(pre.length, sub.length - post.length);
88
+ const target = throughExports(exports[k], ".", conditions);
89
+ if (target) return target.replace("*", filled);
90
+ }
91
+ }
92
+ return null;
93
+ }
94
+ for (const c of conditions) {
95
+ if (exports[c] !== undefined) return throughExports(exports[c], ".", conditions);
96
+ }
97
+ return null;
98
+ }
99
+
100
+ /**
101
+ * Resolve a bare specifier to an absolute file, anchored at `fromDir` — the project
102
+ * root, so the app's own copy of a package wins. Return its canonical path so
103
+ * aliases and package imports share one module instance under symlinked installs.
104
+ *
105
+ * `import.meta.resolve` cannot do this: it resolves against *this* module, which is
106
+ * the CLI's location, not the project's. It is still the fallback for the case where
107
+ * the walk finds nothing (an install layout that hoists somewhere unusual).
108
+ */
109
+ export async function resolveFrom(spec, fromDir, conditions) {
110
+ const m = /^((?:@[^/]+\/)?[^/]+)(?:\/(.*))?$/.exec(spec);
111
+ if (!m) throw new Error(`cannot resolve ${JSON.stringify(spec)}`);
112
+ const [, pkg, rest] = m;
113
+ const sub = rest ? `./${rest}` : ".";
114
+
115
+ for (let dir = fromDir; ; ) {
116
+ const pkgDir = join(dir, "node_modules", pkg);
117
+ const manifest = join(pkgDir, "package.json");
118
+ if (await exists(manifest)) {
119
+ let json = {};
120
+ try {
121
+ json = JSON.parse(await readText(manifest));
122
+ } catch {}
123
+ const target =
124
+ throughExports(json.exports, sub, conditions) ??
125
+ (sub === "." ? (json.module ?? json.main ?? "index.js") : rest);
126
+ const abs = join(pkgDir, target);
127
+ if (await exists(abs)) return realPath(abs);
128
+ }
129
+ const up = dirname(dir);
130
+ if (up === dir) break;
131
+ dir = up;
132
+ }
133
+
134
+ return realPath(fromFileURL(import.meta.resolve(spec)));
135
+ }
package/src/shared.js ADDED
@@ -0,0 +1,683 @@
1
+ // Shared plumbing for the SSG library (`@opentf/afw-cli/ssg`): the pre-render
2
+ // driver that a site's `then: "run"` esdev target calls, plus the release-only
3
+ // output hook. esdev owns development, bundling and serving; this module keeps
4
+ // route discovery, the server render bundle, HTML shell injection and the docs
5
+ // output generators (search, feeds, LLM files) that run after a release build.
6
+
7
+ import { build } from "runtime:build";
8
+ import { dirname, join, toFileURL } from "runtime:path";
9
+ import { exit } from "runtime:process";
10
+
11
+ import { quiet } from "./reporter.js";
12
+
13
+ import { exists, findUp, mkdirp, readEntries, readText, resolveFrom, rmrf, writeFile } from "./runtime.js";
14
+
15
+ // The afwc compiler service and the `runtime:build` transform plugin live in
16
+ // `@opentf/esdev-plugin-afw`. Imported here for the server render bundle and
17
+ // re-exported so the SSG entry keeps a single import site.
18
+ import { closeCompilers, afwPlugin, resolveCompiler } from "@opentf/esdev-plugin-afw";
19
+
20
+ export { closeCompilers, resolveCompiler };
21
+
22
+ export const EXTENSIONS = [".jsx", ".tsx", ".js", ".ts", ".mdx", ".md"];
23
+
24
+ /** Inject `snippet` just before `</body>` (or append when there is none). */
25
+ export function injectBeforeBody(html, snippet) {
26
+ // Function replacer so `$` in `snippet` is literal (String.replace treats `$1`,
27
+ // `$&`, … in a string replacement as back-references — e.g. a "$189.00" price).
28
+ return html.includes("</body>") ? html.replace("</body>", () => `${snippet}</body>`) : html + snippet;
29
+ }
30
+
31
+ /** Inject pre-rendered markup into the shell's empty `#app` container. */
32
+ export function injectMarkup(shellHtml, markup) {
33
+ // Function replacer: `markup` may contain `$` (currency, etc.) — keep it literal.
34
+ return shellHtml.replace(/(<div id="app"[^>]*>)\s*(<\/div>)/, (_m, open, close) => `${open}${markup}${close}`);
35
+ }
36
+
37
+ /**
38
+ * Embed the island hydration payload (`renderRoute().hydration`) as a
39
+ * `<script type="application/json" id="__afw_h">` the client reads at upgrade so
40
+ * components resume from rich JS props (compiler-driven data hydration). Placed before
41
+ * `</body>`; a deferred module bundle runs after parse, so the payload is always in the
42
+ * DOM first. `json` is already `<`-escaped by the server collector, so it can't break out
43
+ * of the script. No-op for an empty payload. Uses a function replacer so `$` in the JSON
44
+ * stays literal.
45
+ */
46
+ export function injectHydrationData(shellHtml, json) {
47
+ if (!json) return shellHtml;
48
+ return injectBeforeBody(shellHtml, `<script type="application/json" id="__afw_h">${json}</script>`);
49
+ }
50
+
51
+ /** The reserved per-route data filename/URL suffix (mirrors the runtime's
52
+ * `DATA_FILE` in `@opentf/afw` runtime/route-data.js). */
53
+ export const DATA_FILE = "__data.json";
54
+
55
+ /**
56
+ * Embed a route loader's data (docs/DATA.md) as a `<script type="application/json"
57
+ * id="__afw_data">` the client router reads on first paint (instead of fetching
58
+ * `<path>/__data.json`). A separate script from the island payload above — the two
59
+ * channels have independent shapes and readers. `json` comes `<`-escaped from
60
+ * `serializeRouteData`; no-op for an empty payload (route without a loader, or an
61
+ * undefined loader result).
62
+ */
63
+ export function injectRouteData(shellHtml, json) {
64
+ if (!json) return shellHtml;
65
+ return injectBeforeBody(shellHtml, `<script type="application/json" id="__afw_data">${json}</script>`);
66
+ }
67
+
68
+ /**
69
+ * Stamp the `data-afw-hydrate` sentinel onto the shell's `#app` container, telling
70
+ * the client to *adopt* the server-rendered DOM on first paint instead of rebuilding
71
+ * it (`runtime/router.js` `mountApp`). Used when the client bundle was built for the
72
+ * hydrate target and there is server markup to adopt (SSR, and SSG pre-render).
73
+ * Idempotent — a no-op if the sentinel is already present.
74
+ */
75
+ export function stampHydrateSentinel(shellHtml) {
76
+ return shellHtml.replace(/<div id="app"([^>]*)>/, (m, attrs) =>
77
+ /\bdata-afw-hydrate\b/.test(attrs) ? m : `<div id="app"${attrs} data-afw-hydrate>`,
78
+ );
79
+ }
80
+
81
+ /**
82
+ * Record the route a prerendered page was rendered for on its hydrate sentinel
83
+ * (`data-afw-hydrate="/docs/x"`), so the client adopts the markup only at that URL
84
+ * and builds the requested route when a host serves this file for another path.
85
+ * A no-op when the shell carries no sentinel (a CSR-only shell).
86
+ */
87
+ export function stampRenderedPath(shellHtml, path) {
88
+ const value = String(path).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
89
+ return shellHtml.replace(/(<div id="app"[^>]*?\sdata-afw-hydrate)(?:="[^"]*")?/, (_m, attr) => `${attr}="${value}"`);
90
+ }
91
+
92
+ /**
93
+ * Inject per-route `<head>` tags before `</head>`, dropping the shell's default
94
+ * `<title>` when the route supplies its own (so each page gets a unique,
95
+ * non-duplicated title). Shared by SSG pre-render and the SSR server.
96
+ */
97
+ export function injectHead(shellHtml, headHtml) {
98
+ if (!headHtml) return shellHtml;
99
+ let out = shellHtml;
100
+ if (/<title[\s>]/i.test(headHtml)) out = out.replace(/<title>[\s\S]*?<\/title>\s*/i, "");
101
+ // Function replacer so `$` in `headHtml` (e.g. a price in a meta description) is literal.
102
+ return out.replace(/<\/head>/i, () => `${headHtml}\n</head>`);
103
+ }
104
+
105
+ /** Set/replace the shell's `<html lang>` for a localized page (i18n; docs/I18N.md §6). */
106
+ export function withHtmlLang(shellHtml, locale) {
107
+ if (!locale) return shellHtml;
108
+ if (/<html[^>]*\slang=/i.test(shellHtml)) {
109
+ return shellHtml.replace(/(<html[^>]*\slang=)(["'])[^"']*\2/i, `$1$2${locale}$2`);
110
+ }
111
+ return shellHtml.replace(/<html\b/i, `<html lang="${locale}"`);
112
+ }
113
+
114
+ export { findUp };
115
+
116
+ /**
117
+ * Load the optional project config (`afw.config.{json,js,mjs}`) as a plain object.
118
+ * Read by the build for the site URL (SEO) and the `docs` block (docs generator).
119
+ */
120
+ export async function loadConfig(root) {
121
+ const json = join(root, "afw.config.json");
122
+ if (await exists(json)) {
123
+ try {
124
+ return JSON.parse(await readText(json)) ?? {};
125
+ } catch (e) {
126
+ console.warn(`⚠ could not parse afw.config.json: ${e?.message ?? e}`);
127
+ }
128
+ }
129
+ for (const name of ["afw.config.js", "afw.config.mjs"]) {
130
+ const p = join(root, name);
131
+ if (await exists(p)) {
132
+ try {
133
+ const mod = await import(toFileURL(p).href);
134
+ return mod.default ?? {};
135
+ } catch (e) {
136
+ console.warn(`⚠ could not load ${name}: ${e?.message ?? e}`);
137
+ }
138
+ }
139
+ }
140
+ return {};
141
+ }
142
+
143
+ /**
144
+ * The docs navigation bundler plugin, when the project opts into the docs
145
+ * generator (a `docs` block in afw.config). Resolved from `@opentf/afw-docs`
146
+ * (the app's own dependency); returns null when docs aren't configured or the
147
+ * package isn't installed, so the core toolchain stays untouched for normal apps.
148
+ */
149
+ export async function loadDocsPlugins(root, appDir, config, exclude = new Set()) {
150
+ const docs = config?.docs;
151
+ const blog = config?.blog;
152
+ if (!docs && !blog) return [];
153
+ try {
154
+ const entry = await resolveFrom("@opentf/afw-docs/build", root);
155
+ const { docsNavPlugin, blogPostsPlugin, lastUpdatedPlugin } = await import(toFileURL(entry).href);
156
+ const plugins = [];
157
+ // Resolves `@opentf/afw-docs/nav` to a section map — one generated tree per top-level
158
+ // folder under app/. Any folder with a DocsLayout becomes a section automatically.
159
+ if (docs) plugins.push(docsNavPlugin({ appDir, exclude }));
160
+ // Resolves `@opentf/afw-docs/posts` to the generated post list.
161
+ if (blog) plugins.push(blogPostsPlugin({ appDir, contentDir: blog.dir ?? "blog", exclude }));
162
+ // Resolves `@opentf/afw-docs/updated` to the per-page last-updated map (every route),
163
+ // when last-updated is turned on anywhere.
164
+ if (wantsLastUpdated(config)) plugins.push(lastUpdatedPlugin({ appDir, exclude }));
165
+ return plugins;
166
+ } catch (e) {
167
+ console.warn(
168
+ `⚠ docs/blog config present but @opentf/afw-docs could not be loaded: ${e?.message ?? e}`,
169
+ );
170
+ return [];
171
+ }
172
+ }
173
+
174
+ /** Whether "last updated" tracking is enabled anywhere (`docs`/`blog` `lastUpdated`). */
175
+ export function wantsLastUpdated(config) {
176
+ return Boolean(config?.docs?.lastUpdated || config?.blog?.lastUpdated);
177
+ }
178
+
179
+ /**
180
+ * Build the `{ [routePath]: ISO }` last-updated map for every page (the same map the
181
+ * `@opentf/afw-docs/updated` virtual module exposes). Used by the SSG step to emit
182
+ * `article:modified_time`. Returns `{}` when last-updated is off or the package can't
183
+ * be loaded.
184
+ */
185
+ export async function runLastUpdated(root, appDir, config, exclude = new Set()) {
186
+ if (!wantsLastUpdated(config)) return {};
187
+ try {
188
+ const entry = await resolveFrom("@opentf/afw-docs/build", root);
189
+ const { loadLastUpdated } = await import(toFileURL(entry).href);
190
+ return await loadLastUpdated({ appDir, exclude });
191
+ } catch (e) {
192
+ console.warn(`⚠ last-updated map skipped: ${e?.message ?? e}`);
193
+ return {};
194
+ }
195
+ }
196
+
197
+ /** Index the completed SSG output when static search is enabled. Errors fail the build. */
198
+ export async function runDocsSearchIndex(root, config, siteDir, afwc) {
199
+ if (config?.docs?.search?.provider !== "afw") return null;
200
+ const entry = await resolveFrom("@opentf/afw-docs/build", root);
201
+ const { indexWithAfwSearch } = await import(toFileURL(entry).href);
202
+ return indexWithAfwSearch({ siteDir, afwc });
203
+ }
204
+
205
+ /**
206
+ * Generate blog feeds when the project has a `blog` config and a base URL. Scans the
207
+ * post folders, renders RSS 2.0 + Atom 1.0, and writes them under
208
+ * `<siteDir>/<blogDir>/`. Project-supplied `public/<blogDir>/{rss,atom}.xml` files
209
+ * take precedence independently. Returns `{ paths, urls, count }` or null (no blog /
210
+ * no base URL / all feeds overridden / package missing). Resolved from the app's
211
+ * `@opentf/afw-docs`.
212
+ */
213
+ export async function runBlogFeed(root, appDir, config, siteDir, baseUrl, exclude = new Set()) {
214
+ const blog = config?.blog;
215
+ if (!blog) return null;
216
+ if (!baseUrl) {
217
+ console.warn("⚠ blog feeds skipped: no site URL (pass --base-url or set afw.config)");
218
+ return null;
219
+ }
220
+ const contentDir = blog.dir ?? "blog";
221
+ try {
222
+ const entry = await resolveFrom("@opentf/afw-docs/build", root);
223
+ const { loadPosts, renderAtomFeed, renderBlogFeed } = await import(toFileURL(entry).href);
224
+ const posts = await loadPosts({ appDir, contentDir, exclude });
225
+ const title = blog.title || (config?.docs?.title ? `${config.docs.title} Blog` : "Blog");
226
+ const channel = {
227
+ title,
228
+ description: blog.description || title,
229
+ link: `/${contentDir}`,
230
+ };
231
+ const feeds = [
232
+ {
233
+ file: "rss.xml",
234
+ path: `/${contentDir}/rss.xml`,
235
+ render: renderBlogFeed,
236
+ },
237
+ {
238
+ file: "atom.xml",
239
+ path: `/${contentDir}/atom.xml`,
240
+ render: renderAtomFeed,
241
+ },
242
+ ];
243
+ const written = [];
244
+ for (const feed of feeds) {
245
+ if (await exists(join(root, "public", contentDir, feed.file))) continue; // honor override
246
+ const out = join(siteDir, contentDir, feed.file);
247
+ await writeFile(out, feed.render({ posts, baseUrl, feedPath: feed.path, channel }));
248
+ written.push(feed.path);
249
+ }
250
+ if (!written.length) return null;
251
+ const origin = baseUrl.replace(/\/+$/, "");
252
+ return { paths: written, urls: written.map((path) => origin + path), count: posts.length };
253
+ } catch (e) {
254
+ console.warn(`⚠ blog feeds skipped: ${e?.message ?? e}`);
255
+ return null;
256
+ }
257
+ }
258
+
259
+ /**
260
+ * Generate `/llms.txt` and `/llms-full.txt` for docs/blog sites from the same
261
+ * filesystem route list used by the app build. Project-supplied public files override
262
+ * each output independently. `siteDescription` is the site's own description (resolved
263
+ * from the app's metadata during the build) — llms.txt summarizes the site with it
264
+ * rather than with a generic line.
265
+ */
266
+ export async function runLlmsFiles(root, appDir, pages, config, siteDir, baseUrl, { siteDescription = "" } = {}) {
267
+ if (!config?.docs && !config?.blog) return null;
268
+ const candidates = [
269
+ { file: "llms.txt", render: "renderLlmsTxt" },
270
+ { file: "llms-full.txt", render: "renderLlmsFullTxt" },
271
+ ];
272
+ const outputs = [];
273
+ for (const out of candidates) {
274
+ if (!(await exists(join(root, "public", out.file)))) outputs.push(out);
275
+ }
276
+ if (!outputs.length) return null;
277
+
278
+ try {
279
+ const entry = await resolveFrom("@opentf/afw-docs/build", root);
280
+ const mod = await import(toFileURL(entry).href);
281
+ const written = [];
282
+ for (const out of outputs) {
283
+ const render = mod[out.render];
284
+ if (typeof render !== "function") continue;
285
+ await writeFile(join(siteDir, out.file), await render({ appDir, pages, baseUrl, config, siteDescription }));
286
+ written.push(`/${out.file}`);
287
+ }
288
+ return written.length ? { paths: written } : null;
289
+ } catch (e) {
290
+ console.warn(`⚠ llms.txt skipped: ${e?.message ?? e}`);
291
+ return null;
292
+ }
293
+ }
294
+
295
+ /** Discover file-based routes under `app/`: every page/layout and the 404. */
296
+ export async function discoverPages(dir, exclude) {
297
+ const out = [];
298
+ for (const entry of await readEntries(dir)) {
299
+ if (entry.isDir && exclude.has(entry.name)) continue;
300
+ const full = `${dir}/${entry.name}`;
301
+ if (entry.isDir) out.push(...(await discoverPages(full, exclude)));
302
+ else if (/^404\.(mdx|md)$/.test(entry.name)) {
303
+ throw new Error(`Unsupported Markdown 404 route: ${full}. Use 404.jsx or 404.tsx instead.`);
304
+ }
305
+ else if (/^(page|layout|404)\.(mdx|md|[jt]sx)$/.test(entry.name)) out.push(full);
306
+ }
307
+ return out;
308
+ }
309
+
310
+ /**
311
+ * Discover file-based API routes anywhere under `app/` (SPEC §11). An endpoint is a
312
+ * `route.{js,ts}` file (the API analogue of `page.{jsx,tsx}`); its folder is the URL.
313
+ * Returns `{ routes, middleware }` — absolute paths to `route.*` handler modules and
314
+ * to `_middleware.{js,ts}` files (folder middleware) respectively.
315
+ */
316
+ export async function discoverApiRoutes(appDir, exclude = new Set()) {
317
+ const routes = [];
318
+ const middleware = [];
319
+ const walk = async (dir) => {
320
+ for (const entry of await readEntries(dir)) {
321
+ if (entry.isDir) {
322
+ if (!exclude.has(entry.name)) await walk(join(dir, entry.name));
323
+ continue;
324
+ }
325
+ const name = entry.name;
326
+ const full = join(dir, name);
327
+ if (/^route\.(jsx?|tsx?)$/.test(name)) routes.push(full);
328
+ else if (/^_middleware\.(jsx?|tsx?)$/.test(name)) middleware.push(full);
329
+ }
330
+ };
331
+ await walk(appDir);
332
+ return { routes, middleware };
333
+ }
334
+
335
+ /**
336
+ * Strip the app-directory prefix from a route file path. With `appDir` the exact
337
+ * prefix is removed (unambiguous even for `app/app/...`); without it, fall back to
338
+ * the last complete `/app` path segment — the lookahead keeps folders that merely
339
+ * start with "app" (`/appointments`) intact.
340
+ */
341
+ function stripAppPrefix(filePath, appDir) {
342
+ if (appDir) {
343
+ const base = appDir.replace(/\/+$/, "");
344
+ if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
345
+ }
346
+ return filePath.replace(/^.*\/app(?=\/)/, "");
347
+ }
348
+
349
+ /** `<link rel="modulepreload">` tags for a route's chunk hrefs (`""` when there are none). */
350
+ export function modulepreloadTags(hrefs) {
351
+ if (!hrefs || hrefs.length === 0) return "";
352
+ return hrefs.map((h) => `<link rel="modulepreload" href="${h}">`).join("\n");
353
+ }
354
+
355
+ /** The page URL for a `.../app/<...>/page.{mdx,md,jsx,tsx}` file (folder = URL). */
356
+ export function pageRouteFromPath(filePath, appDir) {
357
+ const r = stripAppPrefix(filePath, appDir).replace(/\/page\.(mdx|md|jsx|tsx)$/, "");
358
+ return r === "" ? "/" : r;
359
+ }
360
+
361
+ /** The route URL for a `.../app/<...>/route.{js,ts}` file (folder = URL). */
362
+ function apiRoutePath(filePath, appDir) {
363
+ const r = stripAppPrefix(filePath, appDir).replace(/\/route\.(jsx?|tsx?)$/, "");
364
+ return r === "" ? "/" : r;
365
+ }
366
+
367
+ /**
368
+ * Discover route loaders anywhere under `app/` (docs/DATA.md). A loader is a
369
+ * `loader.{js,ts}` file sibling to a `page.*` — the data analogue of a `route.*`
370
+ * endpoint. Strictly `js|ts` (no `x` variants): loaders are plain server modules,
371
+ * never JSX. Returns absolute file paths.
372
+ */
373
+ export async function discoverLoaders(appDir, exclude = new Set()) {
374
+ const out = [];
375
+ const walk = async (dir) => {
376
+ for (const entry of await readEntries(dir)) {
377
+ if (entry.isDir) {
378
+ if (!exclude.has(entry.name)) await walk(join(dir, entry.name));
379
+ } else if (/^loader\.(js|ts)$/.test(entry.name)) out.push(join(dir, entry.name));
380
+ }
381
+ };
382
+ await walk(appDir);
383
+ return out;
384
+ }
385
+
386
+ /** The page route a `.../app/<...>/loader.{js,ts}` file feeds (folder = URL). */
387
+ export function loaderRoutePath(filePath, appDir) {
388
+ const r = stripAppPrefix(filePath, appDir).replace(/\/loader\.(js|ts)$/, "");
389
+ return r === "" ? "/" : r;
390
+ }
391
+
392
+ /**
393
+ * Detect folders that hold both a `page.*` and a `route.*` — they'd resolve to the
394
+ * same URL. Returns the conflicting `{ path, page, route }` entries (empty = none).
395
+ * A page and an endpoint cannot own the same path (as in Next.js's App Router).
396
+ */
397
+ export async function detectRouteConflicts(appDir, exclude = new Set()) {
398
+ const pageByRoute = new Map();
399
+ for (const p of await discoverPages(appDir, exclude)) {
400
+ if (/\/page\.(mdx|md|jsx|tsx)$/.test(p)) pageByRoute.set(pageRouteFromPath(p, appDir), p);
401
+ }
402
+ const conflicts = [];
403
+ for (const r of (await discoverApiRoutes(appDir, exclude)).routes) {
404
+ const path = apiRoutePath(r, appDir);
405
+ if (pageByRoute.has(path)) conflicts.push({ path, page: pageByRoute.get(path), route: r });
406
+ }
407
+ return conflicts;
408
+ }
409
+
410
+ /**
411
+ * Detect misplaced `loader.*` files (docs/DATA.md): a loader feeds the page in
412
+ * its folder, so one without a sibling `page.*` — including one placed next to a
413
+ * `route.*` endpoint — has nothing to feed. Returns `{ loader, route, reason }`.
414
+ */
415
+ export async function detectLoaderConflicts(appDir, exclude = new Set()) {
416
+ const conflicts = [];
417
+ const anyExists = async (dir, names) => {
418
+ for (const n of names) if (await exists(join(dir, n))) return true;
419
+ return false;
420
+ };
421
+ for (const loader of await discoverLoaders(appDir, exclude)) {
422
+ const dir = dirname(loader);
423
+ if (await anyExists(dir, ["page.jsx", "page.tsx", "page.mdx", "page.md"])) continue;
424
+ const hasRoute = await anyExists(dir, ["route.js", "route.ts"]);
425
+ conflicts.push({
426
+ loader,
427
+ route: loaderRoutePath(loader, appDir),
428
+ reason: hasRoute
429
+ ? "sits next to a route.* API endpoint (endpoints take a Request; loaders feed pages)"
430
+ : "has no sibling page.* to feed",
431
+ });
432
+ }
433
+ return conflicts;
434
+ }
435
+
436
+ /** Print the route/page/loader conflicts and exit the prerender step. */
437
+ export async function assertNoRouteConflicts(appDir, exclude = new Set()) {
438
+ const conflicts = await detectRouteConflicts(appDir, exclude);
439
+ if (conflicts.length > 0) {
440
+ const lines = conflicts.map((c) => ` ${c.path}\n page: ${c.page}\n route: ${c.route}`).join("\n");
441
+ fail(`a page and an API route cannot resolve to the same path:\n${lines}\n Move one to a different folder.`);
442
+ }
443
+ const loaderConflicts = await detectLoaderConflicts(appDir, exclude);
444
+ if (loaderConflicts.length > 0) {
445
+ const lines = loaderConflicts.map((c) => ` ${c.route}\n loader: ${c.loader}\n ${c.reason}`).join("\n");
446
+ fail(`a loader.* file must sit next to the page.* it feeds:\n${lines}`);
447
+ }
448
+ }
449
+
450
+ /**
451
+ * Entry source for the API/middleware server bundle: statically import every
452
+ * route + middleware module (keyed by absolute path so scopes/routes derive from
453
+ * the path), then export three composed handlers. Mirrors `serverEntrySource`
454
+ * for the page/SSG bundle.
455
+ *
456
+ * apiHandler — routes with the API-scoped middleware composed in (standalone /
457
+ * legacy adapter use, where nothing else runs the middleware);
458
+ * apiRoutes — routes only, for servers that run `middleware` themselves at
459
+ * pipeline level — middleware must not run twice;
460
+ * middleware — the `createMiddleware` runner governing the whole request
461
+ * pipeline (pages, endpoints, loader data — docs/MIDDLEWARE.md).
462
+ */
463
+ export function apiEntrySource({ routes, middleware }, appDir, i18n = null) {
464
+ const rImports = routes.map((p, i) => `import * as r${i} from ${JSON.stringify(p)};`).join("\n");
465
+ const mImports = middleware.map((p, i) => `import * as m${i} from ${JSON.stringify(p)};`).join("\n");
466
+ const rMap = routes.map((p, i) => ` [${JSON.stringify(p)}]: r${i},`).join("\n");
467
+ const mMap = middleware.map((p, i) => ` [${JSON.stringify(p)}]: m${i},`).join("\n");
468
+ // `appDir` pins the exact prefix to strip from the keys — route derivation stays
469
+ // correct for folders whose name starts with "app" and for nested app/app dirs.
470
+ // `i18n` lets middleware scope matching strip a non-default locale prefix.
471
+ const i18nOpt =
472
+ i18n && Array.isArray(i18n.locales) && i18n.locales.length
473
+ ? `, i18n: ${JSON.stringify({ locales: i18n.locales, defaultLocale: i18n.defaultLocale })}`
474
+ : "";
475
+ const opts = appDir ? `{ appDir: ${JSON.stringify(appDir)}${i18nOpt} }` : `{${i18nOpt.replace(/^,\s*/, " ")} }`;
476
+ return (
477
+ `import { createApiHandler, createMiddleware } from "@opentf/afw/server";\n` +
478
+ `${rImports}\n${mImports}\n` +
479
+ `const routeModules = {\n${rMap}\n};\n` +
480
+ `const middlewareModules = {\n${mMap}\n};\n` +
481
+ `export const apiHandler = createApiHandler(routeModules, middlewareModules, ${opts});\n` +
482
+ `export const apiRoutes = createApiHandler(routeModules, {}, ${opts});\n` +
483
+ `export const middleware = createMiddleware(middlewareModules, ${opts});\n`
484
+ );
485
+ }
486
+
487
+ /**
488
+ * Emit the API handler bundle to `outDir/api.js` for production/deploy (SPEC §13,
489
+ * `dist/server/`). This writes a persistent, self-contained ESM module that
490
+ * exports `apiHandler` / `apiRoutes` / `middleware` (see `apiEntrySource`) — the
491
+ * runtime dispatchers are bundled in; npm/node deps stay external and resolve at
492
+ * the deploy target. A deploy adapter (`server/adapters/`) imports this file and
493
+ * hands requests to the handlers. Returns `{ routes, middleware }`, or `null`
494
+ * when the project has neither API routes nor middleware.
495
+ */
496
+ export async function emitApiBundle({ root, appDir, afwEntry, exclude, i18n, outDir }) {
497
+ const discovered = await discoverApiRoutes(appDir, exclude);
498
+ if (discovered.routes.length === 0 && discovered.middleware.length === 0) return null;
499
+
500
+ const tmp = join(root, ".afw-api-build");
501
+ await mkdirp(tmp);
502
+ const entry = join(tmp, "api-entry.js");
503
+ await writeFile(entry, apiEntrySource(discovered, appDir, i18n));
504
+
505
+ const serverApi = join(dirname(afwEntry), "server", "index.js");
506
+ await mkdirp(outDir);
507
+ const bundle = await build({
508
+ input: entry,
509
+ platform: "node",
510
+ resolve: { alias: { "@opentf/afw/server": serverApi, "@opentf/afw": afwEntry }, extensions: EXTENSIONS },
511
+ external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/afw"),
512
+ });
513
+ try {
514
+ await bundle.write({ dir: outDir, format: "esm", entryFileNames: "api.js" });
515
+ } finally {
516
+ await bundle.close();
517
+ }
518
+ await rmrf(tmp);
519
+ return { routes: discovered.routes, middleware: discovered.middleware };
520
+ }
521
+
522
+ /**
523
+ * Entry source for the loader bundle (docs/DATA.md): statically import every
524
+ * `loader.{js,ts}` module (keyed by absolute path so the registry derives each
525
+ * route from it) and export the composed registry. Mirrors `apiEntrySource`.
526
+ */
527
+ export function loaderEntrySource(loaderFiles, appDir, i18n = null) {
528
+ const imports = loaderFiles.map((p, i) => `import * as l${i} from ${JSON.stringify(p)};`).join("\n");
529
+ const map = loaderFiles.map((p, i) => ` [${JSON.stringify(p)}]: l${i},`).join("\n");
530
+ const i18nOpt =
531
+ i18n && Array.isArray(i18n.locales) && i18n.locales.length
532
+ ? `, i18n: ${JSON.stringify({ locales: i18n.locales, defaultLocale: i18n.defaultLocale })}`
533
+ : "";
534
+ const opts = `\n{ appDir: ${JSON.stringify(appDir ?? "")}${i18nOpt} },\n`;
535
+ return (
536
+ `import { createLoaderRegistry } from "@opentf/afw/server";\n` +
537
+ `${imports}\n` +
538
+ `export const loaders = createLoaderRegistry(\n{\n${map}\n},${opts});\n`
539
+ );
540
+ }
541
+
542
+ /**
543
+ * Emit the loader bundle to `outDir/loaders.js` for production (`dist/server/`,
544
+ * next to `api.js`). The prerender runs these loaders at build time; a deploy
545
+ * server can import the same file to serve `<path>/__data.json`. Returns `{ files }`, or `null` when
546
+ * the app has no loader files.
547
+ */
548
+ export async function emitLoaderBundle({ root, appDir, afwEntry, exclude, i18n, outDir }) {
549
+ const files = await discoverLoaders(appDir, exclude);
550
+ if (files.length === 0) return null;
551
+
552
+ const tmp = join(root, ".afw-loaders-build");
553
+ await mkdirp(tmp);
554
+ const entry = join(tmp, "loaders-entry.js");
555
+ await writeFile(entry, loaderEntrySource(files, appDir, i18n));
556
+
557
+ const serverApi = join(dirname(afwEntry), "server", "index.js");
558
+ await mkdirp(outDir);
559
+ const bundle = await build({
560
+ input: entry,
561
+ platform: "node",
562
+ resolve: { alias: { "@opentf/afw/server": serverApi, "@opentf/afw": afwEntry }, extensions: EXTENSIONS },
563
+ external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/afw"),
564
+ });
565
+ try {
566
+ await bundle.write({ dir: outDir, format: "esm", entryFileNames: "loaders.js" });
567
+ } finally {
568
+ await bundle.close();
569
+ }
570
+ await rmrf(tmp);
571
+ return { files };
572
+ }
573
+
574
+ /**
575
+ * CSS plugin: `import "./x.css"` injects a <style>; `*.module.css` resolves to an
576
+ * identity class-name map (`styles.foo` → "foo"). Dev-grade CSS Modules.
577
+ */
578
+ export function cssPlugin() {
579
+ return {
580
+ name: "css",
581
+ transform: {
582
+ filter: { id: /\.css$/ },
583
+ // `pre` so this claims a stylesheet before the runtime's own CSS Modules pass
584
+ // does: that pass resolves `@import` for real, and an app stylesheet's
585
+ // `@import "tailwindcss"` is a directive for Tailwind, not a module to fetch.
586
+ order: "pre",
587
+ handler(code, id) {
588
+ const inject =
589
+ `const __s = document.createElement("style");` +
590
+ ` __s.textContent = ${JSON.stringify(code)};` +
591
+ ` document.head.appendChild(__s);`;
592
+ const out = id.endsWith(".module.css")
593
+ ? `${inject}\nexport default new Proxy({}, { get: (_, k) => k });`
594
+ : `${inject}\nexport default ${JSON.stringify(code)};`;
595
+ return { code: out, type: "js", moduleSideEffects: true };
596
+ },
597
+ },
598
+ };
599
+ }
600
+
601
+ // Generated server entry: eager-import every page module (so `registerRoutes`
602
+ // sees real namespaces, enabling `getStaticPaths`) and re-export the render API.
603
+ // Shared by the SSG pre-render and the SSR server — both render through the same
604
+ // SSG-compiled bundle (ARCHITECTURE.md §6: "SSR … shares the SSG path").
605
+ export function serverEntrySource(pages, i18n = null) {
606
+ const imports = pages.map((p, i) => `import * as p${i} from ${JSON.stringify(p)};`).join("\n");
607
+ const map = pages.map((p, i) => ` [${JSON.stringify(p)}]: p${i},`).join("\n");
608
+ // i18n: the server-side router needs the locales too — so renderRoute can strip
609
+ // a `/fr/...` prefix to match the route table and set router.locale for `t()`
610
+ // (docs/I18N.md §6). Without this the prefix wouldn't match and pages would
611
+ // render in the default locale (or 404).
612
+ const i18nOn = i18n && Array.isArray(i18n.locales) && i18n.locales.length;
613
+ const named = i18nOn ? "registerRoutes, configureI18n" : "registerRoutes";
614
+ const i18nCall = i18nOn
615
+ ? `configureI18n(${JSON.stringify({ locales: i18n.locales, defaultLocale: i18n.defaultLocale })});\n`
616
+ : "";
617
+ return (
618
+ `${imports}\n` +
619
+ `import { ${named} } from "@opentf/afw/server";\n` +
620
+ `export { renderRoute, renderHead, collectRoutePaths, resolveMetadata } from "@opentf/afw/server";\n` +
621
+ i18nCall +
622
+ `registerRoutes({\n${map}\n});\n`
623
+ );
624
+ }
625
+
626
+ /**
627
+ * Build the server render bundle (the compiler's SSG backend — HTML-string
628
+ * renderers) and import it. Returns `{ mod, cleanup }`, where `mod` exposes
629
+ * `renderRoute` / `renderHead` / `collectRoutePaths` and `cleanup()` removes the
630
+ * temp build dir. The SSG pre-render calls `cleanup()` immediately after rendering
631
+ * every route; the SSR server keeps the module live and cleans up on shutdown.
632
+ */
633
+ export async function buildServerBundle({
634
+ root,
635
+ pages,
636
+ afwEntry,
637
+ afwc,
638
+ docsPlugins = [],
639
+ i18n = null,
640
+ onCompile,
641
+ tmpName = ".afw-ssg",
642
+ }) {
643
+ const tmp = join(root, tmpName);
644
+ await mkdirp(tmp);
645
+ const entry = join(tmp, "ssg-entry.js");
646
+ await writeFile(entry, serverEntrySource(pages, i18n));
647
+
648
+ const serverApi = join(dirname(afwEntry), "server", "index.js");
649
+ const bundle = await build({
650
+ input: entry,
651
+ resolve: {
652
+ alias: { "@opentf/afw/server": serverApi, "@opentf/afw": afwEntry },
653
+ extensions: EXTENSIONS,
654
+ },
655
+ // The runtime guards its dev diagnostics on `process.env.NODE_ENV`, and there is
656
+ // no `process` global here to read it at runtime — so it has to be folded away at
657
+ // bundle time. Server render is a production render.
658
+ define: { "process.env.NODE_ENV": '"production"' },
659
+ plugins: [
660
+ ...docsPlugins,
661
+ afwPlugin(afwc, { failOnError: true, target: "ssg", quiet, onResult: (id) => onCompile?.(id) }),
662
+ cssPlugin(),
663
+ ],
664
+ });
665
+ try {
666
+ await bundle.write({ dir: join(tmp, "out"), format: "esm", entryFileNames: "server.js" });
667
+ } finally {
668
+ await bundle.close();
669
+ }
670
+
671
+ // The runtime defines `class … extends HTMLElement` at load (for CSR custom
672
+ // elements). Server render never instantiates them, but the base class must
673
+ // exist so the class definitions evaluate. A bare stub suffices — no DOM
674
+ // (customElements stays undefined, so elements self-register only in the browser).
675
+ globalThis.HTMLElement ??= class {};
676
+ const mod = await import(toFileURL(join(tmp, "out", "server.js")).href);
677
+ return { mod, cleanup: () => rmrf(tmp) };
678
+ }
679
+
680
+ function fail(msg) {
681
+ console.error(`✗ ${msg}`);
682
+ exit(1);
683
+ }
package/src/ssg.js ADDED
@@ -0,0 +1,31 @@
1
+ // Stable SSG surface for `then: "run"` prerender steps (`website/ssg.js`).
2
+ //
3
+ // A prerender bundle must import ONE specifier that resolves identically whether
4
+ // the site builds inside this monorepo (workspace symlink) or standalone from
5
+ // npm (a Cloudflare `website/` root directory): `@opentf/afw-cli/ssg`. Reaching
6
+ // into `./src/shared.js` relatively would only work in the monorepo, and the
7
+ // package's `exports` map would block the bare subpath — so this module is the
8
+ // curated re-export. When these helpers move to `@opentf/esdev-plugin-afw`,
9
+ // only this file changes; consumers stay untouched.
10
+
11
+ export { exists, findUp, readText, resolveFrom } from "./runtime.js";
12
+ export {
13
+ assertNoRouteConflicts,
14
+ closeCompilers,
15
+ discoverLoaders,
16
+ discoverPages,
17
+ emitApiBundle,
18
+ emitLoaderBundle,
19
+ loadConfig,
20
+ loadDocsPlugins,
21
+ resolveCompiler,
22
+ runBlogFeed,
23
+ runDocsSearchIndex,
24
+ runLastUpdated,
25
+ runLlmsFiles,
26
+ stampHydrateSentinel,
27
+ } from "./shared.js";
28
+ export { runPrerender } from "./prerender.js";
29
+ export { fmtMs, step } from "./reporter.js";
30
+
31
+ export { siteOutputPlugin, writePrerenderReport } from "./output.js";