@mandujs/core 0.25.3 → 0.26.0

package/src/router/fs-routes.ts

@@ -86,6 +86,20 @@ export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
     return pageRoute;
   }
 
+  // Issue #206: metadata 라우트 (sitemap / robots / llms-txt / manifest).
+  // metadataKind + contentType는 fs-scanner에서 채워진다. 방어적으로
+  // 없는 경우를 떨어뜨리지 않고 빈 값으로 통과시켜 RoutesManifest 검증
+  // 단계에서 명확한 에러가 나오게 한다.
+  if (fsRoute.kind === "metadata") {
+    const metadataRoute: RouteSpec = {
+      ...base,
+      kind: "metadata" as const,
+      metadataKind: fsRoute.metadataKind ?? "sitemap",
+      contentType: fsRoute.contentType ?? "text/plain; charset=utf-8",
+    };
+    return metadataRoute;
+  }
+
   // API 라우트
   const apiRoute: RouteSpec = {
     ...base,
@@ -127,6 +141,12 @@ export async function resolveAutoLinks(
 
   await Promise.all(
     manifest.routes.map(async (route) => {
+      // Metadata routes (sitemap/robots/llms-txt/manifest) have a
+      // strict file-convention contract — no slots, no contracts.
+      // Skipping them here avoids fs.access chatter on every dev
+      // rescan.
+      if (route.kind === "metadata") return;
+
       const contractPath = join(rootDir, "spec", "contracts", `${route.id}.contract.ts`);
 
       // Check all extensions in parallel
@@ -393,7 +413,7 @@ export function formatRoutesForCLI(manifest: RoutesManifest): string {
   lines.push("─".repeat(60));
 
   for (const route of manifest.routes) {
-    const icon = route.kind === "page" ? "📄" : "📡";
+    const icon = route.kind === "page" ? "📄" : route.kind === "api" ? "📡" : "🗺️";
     const hydration = route.clientModule ? " 🏝️" : "";
     lines.push(`${icon} ${route.pattern.padEnd(30)} → ${route.id}${hydration}`);
   }

package/src/router/fs-scanner.ts

@@ -21,6 +21,7 @@ import {
   parseSegments,
   segmentsToPattern,
   detectFileType,
+  detectMetadataFileKind,
   isPrivateFolder,
   generateRouteId,
   validateSegments,
@@ -28,6 +29,7 @@ import {
   getPatternShape,
 } from "./fs-patterns";
 import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Scanner Class
@@ -166,6 +168,40 @@ export class FSScanner {
         continue;
       }
 
+      // Issue #206: metadata routes (sitemap/robots/llms.txt/manifest)
+      // must sit at the routesDir root — a nested
+      // `app/foo/sitemap.ts` would be ambiguous (group-scoped
+      // sitemap? route under /foo?) so we report it as an error
+      // instead of silently serving /sitemap.xml from the wrong file.
+      if (fileType === "metadata") {
+        if (relativePath.includes("/")) {
+          errors.push({
+            type: "invalid_segment",
+            message:
+              `Metadata routes must sit directly under "${this.config.routesDir}/". ` +
+              `Found "${relativePath}" — move it to "${this.config.routesDir}/${fileName}".`,
+            filePath: fullPath,
+          });
+          continue;
+        }
+        const metadataKind = detectMetadataFileKind(fileName);
+        if (!metadataKind) {
+          // Defensive: detectFileType returned "metadata" but the
+          // narrower helper can't identify which one. Only reachable
+          // if the two detection paths drift.
+          continue;
+        }
+        files.push({
+          absolutePath: fullPath,
+          relativePath,
+          type: fileType,
+          segments: [],
+          extension: ext,
+          metadataKind,
+        });
+        continue;
+      }
+
       const segments = parseSegments(relativePath);
       const validation = validateSegments(segments);
       if (!validation.valid) {
@@ -207,6 +243,7 @@ export class FSScanner {
     const errorMap = new Map<string, ScannedFile>();
     const islandMap = new Map<string, ScannedFile[]>();
     const routeFiles: ScannedFile[] = [];
+    const metadataFiles: ScannedFile[] = [];
 
     for (const file of files) {
       const dirPath = this.getDirPath(file.relativePath);
@@ -234,11 +271,53 @@ export class FSScanner {
         case "route":
           routeFiles.push(file);
           break;
+        case "metadata":
+          metadataFiles.push(file);
+          break;
         default:
           break;
       }
     }
 
+    // Issue #206: emit metadata-route entries first so the normal
+    // page/route loop below can surface "duplicate pattern" errors if
+    // a user ever creates e.g. `app/sitemap.xml/page.tsx` alongside
+    // `app/sitemap.ts` (both map to /sitemap.xml).
+    for (const file of metadataFiles) {
+      if (!file.metadataKind) continue;
+      const meta = METADATA_ROUTES[file.metadataKind];
+      const pattern = meta.pattern;
+      const routeId = `metadata-${file.metadataKind}`;
+      const modulePath = join(this.config.routesDir, file.relativePath).replace(/\\/g, "/");
+
+      const existing = patternMap.get(pattern);
+      if (existing) {
+        routeErrors.push({
+          type: "duplicate_route",
+          message: `Duplicate route pattern "${pattern}" — metadata route "${file.relativePath}" conflicts with "${existing.sourceFile}"`,
+          filePath: file.absolutePath,
+          conflictsWith: existing.sourceFile,
+        });
+        continue;
+      }
+
+      const route: FSRouteConfig = {
+        id: routeId,
+        segments: [],
+        pattern,
+        kind: "metadata",
+        module: modulePath,
+        layoutChain: [],
+        sourceFile: file.absolutePath,
+        metadataKind: file.metadataKind,
+        contentType: meta.contentType,
+      };
+
+      routes.push(route);
+      patternMap.set(pattern, route);
+      shapeMap.set(pattern, route);
+    }
+
     // 페이지 및 API 라우트 처리
     for (const file of routeFiles) {
       const pattern = segmentsToPattern(file.segments);
@@ -462,6 +541,7 @@ export class FSScanner {
         apiCount: 0,
         layoutCount: 0,
         islandCount: 0,
+        metadataCount: 0,
         scanTime,
       },
     };
@@ -481,6 +561,7 @@ export class FSScanner {
       apiCount: routes.filter((r) => r.kind === "api").length,
       layoutCount: files.filter((f) => f.type === "layout").length,
       islandCount: files.filter((f) => f.type === "island").length,
+      metadataCount: routes.filter((r) => r.kind === "metadata").length,
       scanTime,
     };
   }

package/src/router/fs-types.ts

@@ -51,7 +51,15 @@ export type ScannedFileType =
   | "loading" // loading.tsx - 로딩 UI
   | "error" // error.tsx - 에러 UI
   | "not-found" // not-found.tsx - 404 UI
-  | "island"; // *.island.tsx - Island 컴포넌트
+  | "island" // *.island.tsx - Island 컴포넌트
+  | "metadata"; // sitemap.ts / robots.ts / llms.txt.ts / manifest.ts — file-convention metadata routes
+
+/**
+ * Metadata 라우트 종류 (sitemap / robots / llms-txt / manifest)
+ * Duplicated in `@mandujs/core/routes` → `MetadataRouteKind`; kept
+ * inline here to avoid a cross-module import at the type layer.
+ */
+export type MetadataFileKind = "sitemap" | "robots" | "llms-txt" | "manifest";
 
 /**
  * 스캔된 파일 정보
@@ -71,6 +79,13 @@ export interface ScannedFile {
 
   /** 파일 확장자 */
   extension: string;
+
+  /**
+   * When `type === "metadata"`, discriminates which file-convention
+   * metadata route (sitemap / robots / llms-txt / manifest) was
+   * matched. Undefined for all other types.
+   */
+  metadataKind?: MetadataFileKind;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -119,6 +134,18 @@ export interface FSRouteConfig {
 
   /** 원본 파일 경로 */
   sourceFile: string;
+
+  /**
+   * Metadata 라우트에만 존재하는 필드.
+   * `kind === "metadata"`일 때 어떤 종류의 metadata 파일인지 구분.
+   */
+  metadataKind?: MetadataFileKind;
+
+  /**
+   * Metadata 라우트 응답 Content-Type.
+   * `kind === "metadata"`일 때만 의미가 있다.
+   */
+  contentType?: string;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -216,6 +243,9 @@ export interface ScanStats {
   /** Island 수 */
   islandCount: number;
 
+  /** Metadata 라우트 수 (sitemap/robots/llms-txt/manifest) */
+  metadataCount: number;
+
   /** 스캔 소요 시간 (ms) */
   scanTime: number;
 }
@@ -248,6 +278,27 @@ export const FILE_PATTERNS = {
 
   /** Island 파일 */
   island: /\.island\.(tsx?|jsx?)$/,
+
+  // ── Metadata routes (Issue #206) ──
+  /** sitemap.ts → /sitemap.xml */
+  sitemap: /^sitemap\.(ts|js)$/,
+
+  /** robots.ts → /robots.txt */
+  robots: /^robots\.(ts|js)$/,
+
+  /**
+   * llms.txt.ts → /llms.txt
+   *
+   * Note the double-dot filename — we mirror the served path in the
+   * source filename so users can grep the filesystem for "llms.txt"
+   * and hit the right file. Must be matched BEFORE the generic
+   * extension stripper since "llms.txt" itself looks like a full
+   * filename with extension ".txt".
+   */
+  llmsTxt: /^llms\.txt\.(ts|js)$/,
+
+  /** manifest.ts → /manifest.webmanifest */
+  manifest: /^manifest\.(ts|js)$/,
 } as const;
 
 /**

package/src/router/index.ts

@@ -34,6 +34,7 @@ export type {
   // File types
   ScannedFileType,
   ScannedFile,
+  MetadataFileKind,
 
   // Route config
   FSRouteConfig,
@@ -56,6 +57,7 @@ export {
   segmentsToPattern,
   pathToPattern,
   detectFileType,
+  detectMetadataFileKind,
   isPrivateFolder,
   isGroupFolder,
   generateRouteId,

package/src/routes/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @mandujs/core/routes
+ *
+ * File-convention metadata routes: sitemap, robots, llms.txt, manifest.
+ *
+ * This subpath intentionally scopes only the Metadata Routes API so
+ * users can import types without pulling in the full `@mandujs/core`
+ * surface:
+ *
+ * ```ts
+ * import type { SitemapEntry, Robots, WebAppManifest } from "@mandujs/core/routes";
+ * ```
+ *
+ * Runtime helpers (`renderSitemap`, `renderRobots`, `renderManifest`,
+ * `renderLlmsTxt`, `handleMetadataRoute`) are also re-exported so
+ * advanced callers can bypass the auto-discovery pipeline and wire
+ * their own handlers.
+ *
+ * See `docs/architect/metadata-routes.md` for the file-convention
+ * contract.
+ */
+
+// Types
+export type {
+  // Sitemap
+  ChangeFrequency,
+  SitemapAlternates,
+  SitemapEntry,
+  Sitemap,
+
+  // Robots
+  RobotsRule,
+  Robots,
+
+  // Web App Manifest
+  DisplayMode,
+  Orientation,
+  WebAppManifestIcon,
+  WebAppManifestShortcut,
+  WebAppManifest,
+
+  // Default-export contracts
+  SitemapFn,
+  RobotsFn,
+  LlmsTxtFn,
+  ManifestFn,
+
+  // Manifest / fs-scanner discriminator
+  MetadataRouteKind,
+} from "./types";
+
+// Validation schemas + fixed route table (low-level — advanced)
+export {
+  SitemapEntrySchema,
+  SitemapSchema,
+  RobotsRuleSchema,
+  RobotsSchema,
+  WebAppManifestIconSchema,
+  WebAppManifestSchema,
+  METADATA_ROUTES,
+} from "./types";
+
+// Runtime handlers
+export {
+  renderSitemap,
+  renderRobots,
+  renderManifest,
+  renderLlmsTxt,
+  renderValidated,
+  handleMetadataRoute,
+  getMetadataRouteMeta,
+  MetadataRouteValidationError,
+  type MetadataRouteHandlerOptions,
+} from "./metadata-routes";