@junejs/server 1.0.0-dev.29 → 1.0.0-dev.42

package/src/build.ts

@@ -314,7 +314,9 @@ export async function juneBuild(
   // The Link header is frozen here from the same builder the pipeline uses, so
   // the static and dynamic surfaces advertise identically. The adapter wraps the
   // portable pipeline for its target (workers() → withAssets).
-  const linkHeader = buildLinkHeader(frozen.agent);
+  // (catalogs: the same publication rule as the pipeline's catalogOrigin — a
+  // basePath site publishes no /.well-known catalog, so it links none.)
+  const linkHeader = buildLinkHeader(frozen.agent, { catalogs: !frozen.document.basePath });
   const adapterEntry = adapter.entry({ linkHeader });
 
   // Resources (when declared) are bound from the worker's env (env.DB → D1) by
@@ -415,6 +417,10 @@ export class JuneAgentDO extends DurableObject {
   fetch(req: Request): Promise<Response> {
     return this.#agent.fetch(req);
   }
+  // Delivers input announcements left undelivered — a failed hook's retry, or the watchdog (#260).
+  alarm(): Promise<void> {
+    return this.#agent.alarm();
+  }
 }
 `
     : "";
@@ -506,7 +512,16 @@ ${doClass}`;
   if (cssAsset) manifest.document.styles = `/${cssAsset}`; // prerendered HTML links the hashed sheet
   if (clientAsset) manifest.document.clientScript = `/${clientAsset}`;
   if (moduleCssAsset) manifest.document.moduleStyles = `/${moduleCssAsset}`;
-  const worker = createWorker(manifest);
+  // A static site has no server: /mcp (and the WebMCP tools that proxy to it)
+  // and the HTTP API (POST /api/<id>, /openapi.json) do not exist there. Render
+  // with both projected out, so the published files advertise only what is
+  // deployed: llms.txt drops its MCP and HTTP API sections, the catalogs and the
+  // generated skill list neither, pages register no WebMCP tools.
+  const isStatic = adapter.capabilities.runtime === "static";
+  if (isStatic) manifest.agent = { ...manifest.agent, mcp: false, api: false, webmcp: false };
+  // The static() target prerenders its sitemap too; that build is where the
+  // route contract lets `staticPaths` run, so its sitemap lists those pages.
+  const worker = createWorker(manifest, { staticBuild: isStatic });
   let hasAssets = false;
 
   // ---- public/ → assets/ : verbatim static files (favicon, images, fonts) ----
@@ -567,7 +582,6 @@ ${doClass}`;
   // dynamic routes via their staticPaths, and write <stem>/index.html so clean URLs
   // resolve on a dumb file host with no rewrite server. Other targets keep the
   // opt-in `prerender: true` behavior and the flat <stem>.html naming (byte-identical).
-  const isStatic = adapter.capabilities.runtime === "static";
   const i18n = frozen.i18n;
 
   // Render ONE route pathname through the worker → HTML (+ .md/.json projections).
@@ -604,6 +618,17 @@ ${doClass}`;
 
   // Locale variants a static route is emitted at: no i18n → [path]; with i18n → one
   // per locale (defaultLocale keeps the bare path, others get their localeHref prefix).
+  // A static build is ONE file tree on ONE host: a locale on its own domain has no
+  // path in it (and a basePath can't apply there), so say so instead of failing
+  // later with a prerender 404.
+  if (isStatic && i18n) {
+    const onDomain = Object.keys(i18n.locales).filter((l) => i18n.locales[l]!.domain);
+    if (onDomain.length) {
+      throw new Error(
+        `[june build] the static() target serves one host, so i18n locales with their own domain are not supported (${onDomain.join(", ")}). Give them a path prefix instead, e.g. { path: "/${onDomain[0]}" }.`,
+      );
+    }
+  }
   const localeVariants = (path: string): string[] =>
     isStatic && i18n
       ? [...new Set(Object.keys(i18n.locales).map((l) => localeHref(i18n, path, l)))]
@@ -624,6 +649,9 @@ ${doClass}`;
       const sp = dyn.def.staticPaths;
       if (!sp) continue;
       const paths = typeof sp === "function" ? await sp() : sp;
+      // Resolve a producer ONCE: the prerendered sitemap below reads this same
+      // def, so it lists exactly the set prerendered here without a second call.
+      dyn.def.staticPaths = paths;
       for (const p of paths) await prerenderOne(p, dyn.def);
     }
     // Framework surfaces the worker would otherwise generate on the fly. Guarded on
@@ -635,11 +663,45 @@ ${doClass}`;
       ["/llms.txt", "llms.txt"],
       ["/sitemap.xml", "sitemap.xml"],
     ];
-    for (const [reqPath, file] of extra) {
+    // A sitemap needs absolute URLs, and the prerender host is a placeholder: with
+    // no public origin configured the pipeline answers 404 for it (and the loop
+    // below skips it), so say why rather than silently ship no sitemap.
+    if (manifest.agent.discovery && !manifest.document.site.url && !manifest.document.deployOrigin) {
+      console.warn(
+        "[june build] no sitemap.xml: set site.url (or deploy.domain) in june.config.ts so its URLs are absolute.",
+      );
+    }
+    // The agent catalogs (ARD, Agent Skills) — JSON/Markdown files a static host
+    // can serve as-is — only when this site publishes them: agent discovery on, a
+    // root deploy (a basePath site doesn't own /.well-known), and a known public
+    // origin (the files name absolute URLs). Same rule as the pipeline's
+    // catalogOrigin, stated here too so an app catch-all route can never answer
+    // these paths into the build. The generated skill's path carries its name, so
+    // it is read back from the index.
+    const doc = manifest.document;
+    if (manifest.agent.discovery && !doc.basePath && (doc.site.url || doc.deployOrigin)) {
+      extra.push(
+        ["/.well-known/ai-catalog.json", ".well-known/ai-catalog.json"],
+        ["/.well-known/ard.json", ".well-known/ard.json"],
+        ["/.well-known/agent-skills/index.json", ".well-known/agent-skills/index.json"],
+      );
+    }
+    for (let i = 0; i < extra.length; i++) {
+      const [reqPath, file] = extra[i]!;
       const res = await worker.fetch(new Request(`${PRERENDER_ORIGIN}${reqPath}`));
       if (!res.ok) continue;
-      await writeFile(join(assetsDir, file), Buffer.from(await res.arrayBuffer()));
+      const bytes = Buffer.from(await res.arrayBuffer());
+      await mkdir(dirname(join(assetsDir, file)), { recursive: true });
+      await writeFile(join(assetsDir, file), bytes);
       hasAssets = true;
+      if (file.endsWith("agent-skills/index.json")) {
+        const index = JSON.parse(bytes.toString("utf8")) as { skills?: Array<{ url?: string }> };
+        for (const s of index.skills ?? []) {
+          if (!s.url) continue;
+          const p = new URL(s.url, PRERENDER_ORIGIN).pathname;
+          extra.push([p, p.slice(1)]);
+        }
+      }
     }
     // 404.html — GitHub Pages serves it for any unmatched URL. A deliberately-missing
     // path renders June's not-found HTML (body is written regardless of the 404 status).

package/src/core-version.ts

@@ -15,7 +15,7 @@ import * as coreRuntime from "@junejs/core/agent-runtime";
 
 // The contract number this server tree is built against. Bump in lockstep with
 // core's RUNTIME_API_VERSION whenever the server↔core runtime contract changes.
-const EXPECTED_CORE_RUNTIME_API = 2;
+const EXPECTED_CORE_RUNTIME_API = 6;
 
 export function assertCoreRuntimeVersion(surface: string): void {
   checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);

package/src/llms-links.ts

@@ -4,7 +4,7 @@
 // template an agent can't fetch — lists each real page it serves, or is skipped.
 // Links point at the markdown projection (<path>.md) unless the route turned md off,
 // so an agent reads the page rather than its HTML (llmstxt.org's recommendation).
-import type { LlmsLink } from "@junejs/core/discovery";
+import type { LlmsLink, SitemapPage } from "@junejs/core/discovery";
 import type { LlmsEntry } from "@junejs/core/route";
 
 import type { RouteResolver } from "./pipeline";
@@ -49,3 +49,48 @@ export async function collectLlmsLinks(origin: string, routes: string[], resolve
   }
   return links;
 }
+
+// /sitemap.xml pages, enumerated like /llms.txt. A static route is one page; a
+// dynamic route lists its real pages via its `llms` entries (their `lastModified`
+// becomes <lastmod>) — the runtime-safe hook /llms.txt already runs. A route
+// that names none stays out: a [param] template isn't a URL. Resource routes
+// (route.*) are machine endpoints, not pages. `llms = false` keeps a static
+// route listed (its URL is known without entries); on a dynamic route it leaves
+// no entries, so its pages drop out of the runtime sitemap too.
+// `staticPaths` join in only when opts.staticPaths is set — the static() build's
+// prerender, the one place the route contract runs them. Even then they're
+// skipped under i18n: they arrive locale-prefixed, while the sitemap derives
+// each page's locale variants from its canonical path.
+export async function collectSitemapPages(
+  routes: string[],
+  resolve: RouteResolver,
+  opts: { i18n?: boolean; staticPaths?: boolean } = {},
+): Promise<SitemapPage[]> {
+  const pages = new Map<string, SitemapPage>();
+  const add = (path: string, lastModified?: string | Date) => {
+    const key = path === "/" ? "/" : path.replace(/\/+$/, "");
+    const prev = pages.get(key);
+    if (!prev) pages.set(key, lastModified ? { path: key, lastModified } : { path: key });
+    else if (lastModified && !prev.lastModified) prev.lastModified = lastModified;
+  };
+  for (const route of routes) {
+    const resolved = await resolve(route);
+    if (!resolved || !("def" in resolved)) continue;
+    const { def } = resolved;
+    const dynamic = route.includes("[");
+    const declared = def.llms ? (typeof def.llms === "function" ? await def.llms() : def.llms) : undefined;
+    const entries: LlmsEntry[] = declared ? (Array.isArray(declared) ? declared : [declared]) : [];
+    // A static route is exactly one URL — its own. An entry naming another path
+    // (an llms.txt pointer elsewhere) is not a page this route serves.
+    if (!dynamic) {
+      add(route, entries.find((e) => (e.path ?? route) === route)?.lastModified);
+      continue;
+    }
+    for (const e of entries) if (e.path) add(e.path, e.lastModified);
+    if (opts.staticPaths && !opts.i18n && def.staticPaths) {
+      const sp = typeof def.staticPaths === "function" ? await def.staticPaths() : def.staticPaths;
+      for (const p of sp) add(p);
+    }
+  }
+  return [...pages.values()];
+}

package/src/negotiate.ts

@@ -6,6 +6,7 @@
 // header — a link is unambiguous; Accept is a hint. The clean pathname (with
 // the projection extension stripped) is what the router matches.
 
+import { FRAGMENT_ACCEPT } from "@junejs/core/nav-protocol";
 import type { RenderTarget } from "@junejs/core/route";
 
 // The fragment media type + title header are the client-router wire protocol —
@@ -18,12 +19,43 @@ const EXT_TARGET: Record<string, RenderTarget> = {
   ".md": "md",
 };
 
-const ACCEPT_TARGET: Array<[test: RegExp, target: RenderTarget]> = [
-  // fragment first: its media type is exact + can't collide with browser Accepts.
-  [/text\/vnd\.june\.fragment\+html/, "fragment"],
-  [/text\/markdown/, "md"],
-  [/application\/json/, "json"],
-];
+// RFC 9110 §12.4.2 qvalue: 0–1 with at most three decimals ("0", "0.5", "1.000").
+const QVALUE = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+
+// Parse an Accept header into media-range → q (RFC 9110 §12.5.1). A q outside the
+// qvalue grammar ("2", "-0.5", "0.1234") is malformed and reads as the default 1:
+// the client still listed the type, so it stays acceptable at the default weight
+// rather than being dropped or excluded. Parameters other than q are ignored.
+function acceptRanges(accept: string): Map<string, number> {
+  const ranges = new Map<string, number>();
+  for (const part of accept.split(",")) {
+    const [type, ...params] = part.split(";").map((s) => s.trim().toLowerCase());
+    if (!type) continue;
+    const raw = params.find((p) => p.startsWith("q="))?.slice(2).trim();
+    ranges.set(type, raw !== undefined && QVALUE.test(raw) ? Number(raw) : 1);
+  }
+  return ranges;
+}
+
+// The projection an Accept header asks for — null when it asks for none of the
+// agent projections (→ the HTML view). ONE decision shared by the pipeline and
+// the deployed worker's asset layer (withAssets), so the two can't disagree.
+//   - The client router's fragment media type (exact range, q > 0) wins outright.
+//   - Markdown / JSON are chosen when listed with q > 0 and at least as preferred
+//     as HTML; HTML's quality is text/html's, else the text/* or */* wildcard's.
+//     So `text/markdown, text/html;q=0.9` → md, `text/html, text/markdown;q=0.5`
+//     → HTML, and a plain browser Accept (no markdown/json) → HTML.
+//   - Ties go to the agent projection (md before json), as they always have.
+export function acceptTarget(accept: string): RenderTarget | null {
+  const ranges = acceptRanges(accept);
+  if ((ranges.get(FRAGMENT_ACCEPT) ?? 0) > 0) return "fragment";
+  const html = ranges.get("text/html") ?? ranges.get("text/*") ?? ranges.get("*/*") ?? 0;
+  const md = ranges.get("text/markdown") ?? 0;
+  const json = ranges.get("application/json") ?? 0;
+  const best = Math.max(md, json);
+  if (best <= 0 || best < html) return null;
+  return md >= json ? "md" : "json";
+}
 
 export type Negotiated = {
   target: RenderTarget;
@@ -61,15 +93,7 @@ export function negotiate(url: URL, request: Request, basePath?: string): Negoti
     pathname = original;
   }
 
-  if (!target) {
-    const accept = request.headers.get("accept") ?? "";
-    for (const [re, t] of ACCEPT_TARGET) {
-      if (re.test(accept)) {
-        target = t;
-        break;
-      }
-    }
-  }
+  if (!target) target = acceptTarget(request.headers.get("accept") ?? "");
 
   // A speculative request (Sec-Purpose: prefetch / prerender) may never be seen
   // — load()s read it to skip side effects (analytics, rate limits, counters).