@ampless/runtime 1.0.0-beta.69 → 1.0.0-beta.70

package/README.ja.md

@@ -96,6 +96,15 @@ middleware はリクエストごとに AppSync から `post.format` /
   `app/md/[slug]/route.ts` で配信 — `ampless.postToMarkdown()` による
   Markdown 投影。`cms.config.ai.markdownRoutes: false` で無効化できます。
 
+`/llms.txt` は書き換えを経由せず、`app/llms.txt/route.ts` に直接マウ
+ントされます。直近の公開投稿（デフォルト 100 件、
+`cms.config.ai.llmsTxt.limit` で設定可能、1..1000 にクランプ）を
+`.md` リンクの一覧として返し、サイト全体を 1 ファイルで把握したい AI
+エージェント / クローラー向けの索引になります。
+`cms.config.ai.llmsTxt: false` で無効化できます。どちらの設定でも
+`llms.txt` は予約 slug になります — slug が `llms.txt` の投稿はテーマ
+ページに到達できなくなります。
+
 また、`post.metadata.cache`（auto / deep / hot）+ `post.updatedAt` +
 `cms.config.cache.{cooldownMs, freshTtlSeconds, deepTtlSeconds}` から
 `Cache-Control` を算出してレスポンスに付与します。キャッシュ戦略の
@@ -105,7 +114,7 @@ middleware はリクエストごとに AppSync から `post.format` /
 
 - `@ampless/runtime` — `createAmpless`、ランタイム型、`renderBody`・`renderThemeCss`・フォーマットコンバーターの再エクスポート
 - `@ampless/runtime/middleware` — `createAmplessMiddleware`、`defaultMatcherConfig`
-- `@ampless/runtime/routes` — `createOgRouteHandler`、`createSitemapRouteHandler`、`createFeedRouteHandler`、`createRawRouteHandler`、`createStaticRouteHandler`、`createMarkdownRouteHandler`
+- `@ampless/runtime/routes` — `createOgRouteHandler`、`createSitemapRouteHandler`、`createFeedRouteHandler`、`createRawRouteHandler`、`createStaticRouteHandler`、`createMarkdownRouteHandler`、`createLlmsTxtRouteHandler`
 - `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`、`createThemePostDispatcher`、`createThemeTagDispatcher`（それぞれ対応する `*Metadata` ファクトリーあり）
 
 ## テンプレートに残るもの

package/README.md

@@ -96,6 +96,14 @@ rewrites the request to the right internal handler:
   `app/md/[slug]/route.ts` — Markdown projection via
   `ampless.postToMarkdown()`. Disable with `cms.config.ai.markdownRoutes: false`.
 
+`/llms.txt` isn't rewritten — it's mounted directly at
+`app/llms.txt/route.ts` and lists the site's most recent published
+posts (default 100, configurable via `cms.config.ai.llmsTxt.limit`,
+clamped to 1..1000) as `.md` links, for AI agents / crawlers that want
+a single-file index. Disable with `cms.config.ai.llmsTxt: false`. Note
+that `llms.txt` becomes a reserved slug either way — a post whose slug
+happens to be `llms.txt` can no longer reach the themed route.
+
 It also computes `Cache-Control` from `post.metadata.cache` (auto /
 deep / hot) + `post.updatedAt` + `cms.config.cache.{cooldownMs,
 freshTtlSeconds, deepTtlSeconds}` and sets the header on the response.
@@ -105,7 +113,7 @@ See `docs/CONTENT.md` for the cache strategy contract.
 
 - `@ampless/runtime` — `createAmpless`, runtime types, and re-exports of `renderBody`, `renderThemeCss`, format converters
 - `@ampless/runtime/middleware` — `createAmplessMiddleware`, `defaultMatcherConfig`
-- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`, `createStaticRouteHandler`, `createMarkdownRouteHandler`
+- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`, `createStaticRouteHandler`, `createMarkdownRouteHandler`, `createLlmsTxtRouteHandler`
 - `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`, `createThemePostDispatcher`, `createThemeTagDispatcher` (each with a matching `*Metadata` factory)
 
 ## What's still in the template

package/dist/middleware.js

@@ -120,6 +120,13 @@ function computeCacheControl(flags, cmsConfig) {
   }
   return `public, max-age=${freshTtl}, s-maxage=${freshTtl}`;
 }
+function safeDecodeURIComponent(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
 var RESERVED_PREFIXES = /* @__PURE__ */ new Set([
   "admin",
   "api",
@@ -131,6 +138,7 @@ var RESERVED_PREFIXES = /* @__PURE__ */ new Set([
   // route handler folders that live alongside `app/[slug]/page.tsx`
   "feed.xml",
   "sitemap.xml",
+  "llms.txt",
   "og",
   "tag",
   // internal rewrite targets — direct hits should not be middleware-driven
@@ -163,7 +171,8 @@ function createAmplessMiddleware(opts) {
     const restPath = segments.slice(1);
     const isMdRequest = restPath.length === 0 && slug.endsWith(".md") && slug.length > 3 && opts.cmsConfig.ai?.markdownRoutes !== false;
     const lookupSlug = isMdRequest ? slug.slice(0, -3) : slug;
-    const flags = await getCachedFlags(opts, lookupSlug);
+    const flagsSlug = isMdRequest ? safeDecodeURIComponent(lookupSlug) : lookupSlug;
+    const flags = await getCachedFlags(opts, flagsSlug);
     if (!flags) {
       if (restPath.length > 0 || isMdRequest) {
         return new NextResponse("Not Found", { status: 404 });

package/dist/routes/index.d.ts

@@ -5,18 +5,18 @@ import 'react';
 import 'aws-amplify/storage/server';
 import 'next/headers';
 
-interface Ctx$5 {
+interface Ctx$6 {
     params: Promise<{
         slug: string;
     }>;
 }
-type OgRouteHandler = (req: Request, ctx: Ctx$5) => Promise<Response>;
+type OgRouteHandler = (req: Request, ctx: Ctx$6) => Promise<Response>;
 declare function createOgRouteHandler(ampless: Ampless): OgRouteHandler;
 
-interface Ctx$4 {
+interface Ctx$5 {
     params: Promise<Record<string, never>>;
 }
-type SitemapRouteHandler = (req: Request, ctx: Ctx$4) => Promise<Response>;
+type SitemapRouteHandler = (req: Request, ctx: Ctx$5) => Promise<Response>;
 /**
  * Sitemap route delegate. Looks up the active theme and forwards to
  * whichever `routes.sitemap` handler the theme provides. Themes
@@ -24,10 +24,10 @@ type SitemapRouteHandler = (req: Request, ctx: Ctx$4) => Promise<Response>;
  */
 declare function createSitemapRouteHandler(ampless: Ampless): SitemapRouteHandler;
 
-interface Ctx$3 {
+interface Ctx$4 {
     params: Promise<Record<string, never>>;
 }
-type FeedRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
+type FeedRouteHandler = (req: Request, ctx: Ctx$4) => Promise<Response>;
 /**
  * Feed route delegate. Looks up the active theme and forwards to
  * whichever `routes.feed` handler the theme provides. Themes without
@@ -35,12 +35,12 @@ type FeedRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
  */
 declare function createFeedRouteHandler(ampless: Ampless): FeedRouteHandler;
 
-interface Ctx$2 {
+interface Ctx$3 {
     params: Promise<{
         slug: string;
     }>;
 }
-type RawRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
+type RawRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
 /**
  * Internal route handler for `format: 'html'` posts whose
  * `metadata.no_layout === true` — the body is its own complete HTML
@@ -63,13 +63,13 @@ type RawRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
  */
 declare function createRawRouteHandler(ampless: Ampless): RawRouteHandler;
 
-interface Ctx$1 {
+interface Ctx$2 {
     params: Promise<{
         slug: string;
         path?: string[];
     }>;
 }
-type StaticRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
+type StaticRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
 /**
  * Internal route handler for `format: 'static'` posts — the body is a
  * manifest describing a bundle of files in S3 at
@@ -97,12 +97,12 @@ type StaticRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
  */
 declare function createStaticRouteHandler(ampless: Ampless): StaticRouteHandler;
 
-interface Ctx {
+interface Ctx$1 {
     params: Promise<{
         slug: string;
     }>;
 }
-type MarkdownRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
+type MarkdownRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
 /**
  * Route handler serving the per-post Markdown projection
  * (`ampless.postToMarkdown()`) for published posts of any format.
@@ -119,4 +119,16 @@ type MarkdownRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
  */
 declare function createMarkdownRouteHandler(ampless: Ampless): MarkdownRouteHandler;
 
-export { type FeedRouteHandler, type MarkdownRouteHandler, type OgRouteHandler, type RawRouteHandler, type SitemapRouteHandler, type StaticRouteHandler, createFeedRouteHandler, createMarkdownRouteHandler, createOgRouteHandler, createRawRouteHandler, createSitemapRouteHandler, createStaticRouteHandler };
+interface Ctx {
+    params: Promise<Record<string, never>>;
+}
+type LlmsTxtRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
+/**
+ * `ai.llmsTxt: false` disables the route (404). Note that `llms.txt`
+ * is always a reserved slug (`middleware.ts` `RESERVED_PREFIXES`)
+ * regardless of that flag — a post whose slug happens to be
+ * `llms.txt` can never reach the themed route.
+ */
+declare function createLlmsTxtRouteHandler(ampless: Ampless): LlmsTxtRouteHandler;
+
+export { type FeedRouteHandler, type LlmsTxtRouteHandler, type MarkdownRouteHandler, type OgRouteHandler, type RawRouteHandler, type SitemapRouteHandler, type StaticRouteHandler, createFeedRouteHandler, createLlmsTxtRouteHandler, createMarkdownRouteHandler, createOgRouteHandler, createRawRouteHandler, createSitemapRouteHandler, createStaticRouteHandler };

package/dist/routes/index.js

@@ -189,11 +189,10 @@ async function signStaticAsset({
 function createMarkdownRouteHandler(ampless) {
   return async function GET(_request, { params }) {
     const { slug } = await params;
-    const cleanSlug = slug.replace(/\.md$/, "");
     if (ampless.cmsConfig.ai?.markdownRoutes === false) {
       return new Response("Not Found", { status: 404 });
     }
-    const post = await ampless.getPublishedPost(cleanSlug);
+    const post = await ampless.getPublishedPost(slug);
     if (!post) {
       return new Response("Not Found", { status: 404 });
     }
@@ -206,8 +205,155 @@ function createMarkdownRouteHandler(ampless) {
     });
   };
 }
+
+// src/routes/llms.ts
+var DEFAULT_LIMIT = 100;
+var MIN_LIMIT = 1;
+var MAX_LIMIT = 1e3;
+var PAGE_SIZE_CAP = 50;
+var MAX_PAGES = 21;
+var EXCERPT_MAX = 200;
+function clampLimit(raw) {
+  const n = raw ?? DEFAULT_LIMIT;
+  if (!Number.isFinite(n)) return DEFAULT_LIMIT;
+  return Math.min(MAX_LIMIT, Math.max(MIN_LIMIT, Math.floor(n)));
+}
+function resolveLimit(ampless) {
+  const cfg = ampless.cmsConfig.ai?.llmsTxt;
+  if (cfg === false) return false;
+  const raw = typeof cfg === "object" && cfg !== null ? cfg.limit : void 0;
+  return clampLimit(raw);
+}
+var CONTROL_CHARS_RE = /[\x00-\x1f\x7f]/g;
+function normalizeText(s) {
+  return s.replace(CONTROL_CHARS_RE, " ").replace(/\s+/g, " ").trim();
+}
+function escapeLinkText(s) {
+  return s.replace(/\[/g, "[").replace(/\]/g, "]");
+}
+function truncateExcerpt(s) {
+  return s.length > EXCERPT_MAX ? s.slice(0, EXCERPT_MAX) + "\u2026" : s;
+}
+function fixedEncodeURIComponent(s) {
+  return encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase()
+  );
+}
+async function collectPosts(ampless, limit) {
+  const items = [];
+  const seenTokens = /* @__PURE__ */ new Set();
+  let token;
+  let truncated = null;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const remaining = limit + 1 - items.length;
+    const pageLimit = Math.min(PAGE_SIZE_CAP, remaining);
+    const res = await ampless.listPublishedPosts({ limit: pageLimit, nextToken: token });
+    items.push(...res.items);
+    if (items.length > limit) {
+      truncated = "limit";
+      break;
+    }
+    if (!res.nextToken) {
+      break;
+    }
+    if (seenTokens.has(res.nextToken)) {
+      truncated = "early";
+      break;
+    }
+    seenTokens.add(res.nextToken);
+    token = res.nextToken;
+    if (page === MAX_PAGES - 1) {
+      truncated = "early";
+    }
+  }
+  return {
+    items: truncated === "limit" ? items.slice(0, limit) : items,
+    truncated
+  };
+}
+function truncationNote(truncated, limit) {
+  if (truncated === "limit") {
+    return `Note: only the ${limit} most recent posts are listed; older posts are omitted.`;
+  }
+  if (truncated === "early") {
+    return "Note: this index was truncated early while scanning the post list; some older posts may be missing. Lower ai.llmsTxt.limit or reduce post sizes.";
+  }
+  return null;
+}
+function createLlmsTxtRouteHandler(ampless) {
+  return async function GET(request) {
+    const limit = resolveLimit(ampless);
+    if (limit === false) {
+      return new Response("Not Found", { status: 404 });
+    }
+    const url = new URL(request.url);
+    if (url.search) {
+      return new Response(null, {
+        status: 308,
+        headers: {
+          Location: url.pathname,
+          "Cache-Control": "public, max-age=3600"
+        }
+      });
+    }
+    const [{ items, truncated }, settings] = await Promise.all([
+      collectPosts(ampless, limit),
+      ampless.loadSiteSettings()
+    ]);
+    const markdownRoutesEnabled = ampless.cmsConfig.ai?.markdownRoutes !== false;
+    const siteUrl = (settings.site.url || "").replace(/\/+$/, "");
+    const buildUrl = (path) => siteUrl ? `${siteUrl}${path}` : path;
+    const blocks = [`# ${normalizeText(settings.site.name)}`];
+    if (settings.site.description) {
+      blocks.push(`> ${normalizeText(settings.site.description)}`);
+    }
+    if (markdownRoutesEnabled) {
+      blocks.push(
+        "Each entry links to the markdown projection of the post; drop the `.md` suffix for the themed HTML page."
+      );
+    }
+    const note = truncationNote(truncated, limit);
+    if (note) blocks.push(note);
+    if (items.length > 0) {
+      const lines = items.map((post) => {
+        const encodedSlug = fixedEncodeURIComponent(post.slug);
+        const href = markdownRoutesEnabled ? buildUrl(`/${encodedSlug}.md`) : buildUrl(`/${encodedSlug}`);
+        const title = escapeLinkText(normalizeText(post.title));
+        const excerpt = post.excerpt ? truncateExcerpt(normalizeText(post.excerpt)) : "";
+        const tags = (post.tags ?? []).map((t) => normalizeText(t)).filter(Boolean);
+        let line = `- [${title}](${href})`;
+        if (excerpt && tags.length > 0) {
+          line += `: ${excerpt} (tags: ${tags.join(", ")})`;
+        } else if (excerpt) {
+          line += `: ${excerpt}`;
+        } else if (tags.length > 0) {
+          line += `: (tags: ${tags.join(", ")})`;
+        }
+        return line;
+      });
+      blocks.push(`## Posts
+
+${lines.join("\n")}`);
+    }
+    const body = blocks.join("\n\n") + "\n";
+    return new Response(body, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        // Self-computed: this route isn't reached via a middleware
+        // rewrite, so nothing else would set Cache-Control (see the
+        // header comment / og.ts for the same pattern). CDN-cacheable
+        // for an hour so repeated crawler hits don't each cost a fresh
+        // paginated AppSync walk.
+        "Cache-Control": "public, max-age=300, s-maxage=3600, stale-while-revalidate=3600"
+      }
+    });
+  };
+}
 export {
   createFeedRouteHandler,
+  createLlmsTxtRouteHandler,
   createMarkdownRouteHandler,
   createOgRouteHandler,
   createRawRouteHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-beta.69",
+  "version": "1.0.0-beta.70",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -51,8 +51,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "tailwind-merge": "^3.6.0",
-    "@ampless/plugin-og-image": "0.2.0-beta.56",
-    "ampless": "1.0.0-beta.56"
+    "@ampless/plugin-og-image": "0.2.0-beta.57",
+    "ampless": "1.0.0-beta.57"
   },
   "peerDependencies": {
     "@aws-amplify/adapter-nextjs": "^1",