@route-forge/core 1.0.2 → 1.1.0

package/dist/codegen.cjs

@@ -122,33 +122,59 @@ ${levelEntries.join("\n")}
 async function main(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv);
   let levels = opts.levels;
+  let summaryData = null;
   if (levels.length === 0) {
     try {
-      const summary = await fetchSummary(opts.endpoint);
-      levels = Object.keys(summary.levels);
+      summaryData = await fetchSummary(opts.endpoint);
+      levels = Object.keys(summaryData.levels);
     } catch (e) {
       console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${e.message}`);
       console.error("hint: pass --levels explicitly to skip auto-discovery");
       process.exit(1);
     }
   }
+  const UNASSIGNED_LEVEL = "unassigned";
+  let unassignedRoutes = null;
+  const needsUnassigned = levels.includes(UNASSIGNED_LEVEL) || summaryData && summaryData.unassigned && summaryData.unassigned.length > 0;
+  if (needsUnassigned) {
+    if (!summaryData) {
+      try {
+        summaryData = await fetchSummary(opts.endpoint);
+      } catch (e) {
+        console.warn(`[route-forge/codegen] failed to fetch summary for unassigned routes: ${e.message}`);
+      }
+    }
+    if (summaryData?.unassigned && summaryData.unassigned.length > 0) {
+      unassignedRoutes = {};
+      for (const r of summaryData.unassigned) {
+        unassignedRoutes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
+      }
+      if (!levels.includes(UNASSIGNED_LEVEL)) {
+        levels.push(UNASSIGNED_LEVEL);
+      }
+    }
+  }
   if (levels.length === 0) {
     console.error("[route-forge/codegen] no levels found; pass --levels explicitly");
     process.exit(1);
   }
   const levelFetches = await Promise.allSettled(
-    levels.map((lvl) => fetchLevel(opts.endpoint, lvl))
+    levels.filter((lvl) => lvl !== UNASSIGNED_LEVEL).map((lvl) => fetchLevel(opts.endpoint, lvl))
   );
   const routesByLevel = {};
   let failedLevels = 0;
   levelFetches.forEach((res, idx) => {
+    const lvl = levels.filter((l) => l !== UNASSIGNED_LEVEL)[idx];
     if (res.status === "fulfilled") {
-      routesByLevel[levels[idx]] = res.value.routes;
+      routesByLevel[lvl] = res.value.routes;
     } else {
       failedLevels++;
-      console.warn(`[route-forge/codegen] failed to fetch level "${levels[idx]}": ${res.reason.message}`);
+      console.warn(`[route-forge/codegen] failed to fetch level "${lvl}": ${res.reason.message}`);
     }
   });
+  if (unassignedRoutes) {
+    routesByLevel[UNASSIGNED_LEVEL] = unassignedRoutes;
+  }
   const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);
   if (totalRoutes === 0) {
     console.error("[route-forge/codegen] no routes collected from any level");

package/dist/codegen.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/codegen/index.ts"],"names":[],"mappings":"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","file":"codegen.cjs","sourcesContent":["#!/usr/bin/env node\n/**\n * @route-forge/core codegen CLI\n * @see .docs/SPEC.md §4.2\n *\n * 用法：\n *   npx @route-forge/core codegen \\\n *     --endpoint http://localhost/_forge/routes \\\n *     --levels public,client,manage,admin \\\n *     --out src/types/forge-routes.d.ts\n */\n\nimport type { RouteMeta } from '../types.js';\n\nexport interface CodegenOptions {\n  endpoint: string;\n  levels: string[];\n  out: string;\n  responseTypes?: string;\n}\n\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);\n\n/**\n * 解析 argv（最小手写实现，不引入 commander/yargs）\n * 支持：--endpoint VALUE / --endpoint=VALUE / --levels a,b,c / --out PATH / --responseTypes PATH\n */\nexport function parseArgs(argv: string[]): CodegenOptions {\n  const opts: Partial<CodegenOptions> = {};\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const next = (): string => {\n      const v = argv[++i];\n      if (v === undefined) {\n        throw new Error(`[route-forge/codegen] missing value for ${arg}`);\n      }\n      return v;\n    };\n\n    if (arg === '--endpoint') {\n      opts.endpoint = next();\n    } else if (arg?.startsWith('--endpoint=')) {\n      opts.endpoint = arg.slice('--endpoint='.length);\n    } else if (arg === '--levels') {\n      opts.levels = next().split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg?.startsWith('--levels=')) {\n      opts.levels = arg.slice('--levels='.length).split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg === '--out') {\n      opts.out = next();\n    } else if (arg?.startsWith('--out=')) {\n      opts.out = arg.slice('--out='.length);\n    } else if (arg === '--responseTypes') {\n      opts.responseTypes = next();\n    } else if (arg?.startsWith('--responseTypes=')) {\n      opts.responseTypes = arg.slice('--responseTypes='.length);\n    } else if (arg === '--help' || arg === '-h') {\n      printHelp();\n      process.exit(0);\n    }\n  }\n\n  if (!opts.endpoint) {\n    console.error('[route-forge/codegen] --endpoint is required');\n    printHelp();\n    process.exit(1);\n  }\n  if (!opts.out) {\n    console.error('[route-forge/codegen] --out is required');\n    printHelp();\n    process.exit(1);\n  }\n\n  return {\n    endpoint: opts.endpoint,\n    levels: opts.levels ?? [],\n    out: opts.out,\n    responseTypes: opts.responseTypes,\n  };\n}\n\nfunction printHelp(): void {\n  console.log(`\nroute-forge codegen - generate TS route types from backend summary endpoint\n\nUsage:\n  npx @route-forge/core codegen --endpoint URL --out PATH [--levels a,b,c] [--responseTypes PATH]\n\nOptions:\n  --endpoint URL         Backend summary endpoint (e.g. http://localhost/_forge/routes)\n  --levels a,b,c         Optional: explicit level list (skip auto-discovery)\n  --out PATH              Output .d.ts file path\n  --responseTypes PATH    Optional: JSON file mapping route names to response types\n  -h, --help              Show this help\n`);\n}\n\n/**\n * 拉取摘要端点\n */\nexport async function fetchSummary(endpoint: string): Promise<{ levels: Record<string, unknown> }> {\n  const resp = await fetch(endpoint, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`summary endpoint ${endpoint} returned ${resp.status}`);\n  }\n  return (await resp.json()) as { levels: Record<string, unknown> };\n}\n\n/**\n * 拉取单个层级的路由元信息\n */\nexport async function fetchLevel(endpoint: string, level: string): Promise<{ routes: Record<string, RouteMeta> }> {\n  const base = endpoint.replace(/\\/$/, '');\n  const url = `${base}/${encodeURIComponent(level)}`;\n  const resp = await fetch(url, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`level endpoint ${url} returned ${resp.status}`);\n  }\n  const data = (await resp.json()) as { routes?: Record<string, RouteMeta> };\n  return { routes: data.routes ?? {} };\n}\n\n/**\n * 生成 d.ts 内容\n * @param routesByLevel 按层级分组的路由元信息：{ level: { routeName: meta } }\n */\nexport function generateRouteTypes(routesByLevel: Record<string, Record<string, RouteMeta>>): string {\n  const levelEntries = Object.entries(routesByLevel).map(([level, routes]) => {\n    const routeEntries = Object.entries(routes).map(([name, meta]) => {\n      const defaults = meta.parameter_defaults ?? {};\n      const params = (meta.parameters ?? []).map((p) => {\n        // URI 中的 {p?} 或有后端默认值的参数 → 生成可选字段，避免调用方被迫传参\n        const optional = meta.uri?.includes(`{${p}?}`) || p in defaults;\n        return `${p}${optional ? '?' : ''}: string | number;`;\n      }).join(' ');\n      const method = meta.methods?.find((m) => m.toUpperCase() !== 'HEAD') ?? 'GET';\n      const methodUpper = method.toUpperCase();\n      const bodyField = BODY_METHODS.has(methodUpper) ? '\\n      body: unknown;' : '';\n      return `    ${JSON.stringify(name)}: {\\n      method: ${JSON.stringify(methodUpper)};\\n      params: { ${params} };${bodyField}\\n      response: unknown;\\n    };`;\n    });\n    return `  ${JSON.stringify(level)}: {\\n${routeEntries.join('\\n')}\\n  };`;\n  });\n  return `// AUTO-GENERATED by @route-forge/core codegen. Do not edit.\n\n/**\n * 二级路由类型映射：level → routeName → routeMeta\n * 可通过 module augmentation 增强：\n *   declare module '@route-forge/core' {\n *     interface ForgeRouteMap { admin: { 'users.show': { method: 'GET'; params: { user: string | number }; response: User } } }\n *   }\n */\nexport interface ForgeRouteMap {\n${levelEntries.join('\\n')}\n}\n`;\n}\n\n/**\n * CLI 主入口\n */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const opts = parseArgs(argv);\n\n  let levels = opts.levels;\n  if (levels.length === 0) {\n    try {\n      const summary = await fetchSummary(opts.endpoint);\n      levels = Object.keys(summary.levels);\n    } catch (e) {\n      console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${(e as Error).message}`);\n      console.error('hint: pass --levels explicitly to skip auto-discovery');\n      process.exit(1);\n    }\n  }\n\n  if (levels.length === 0) {\n    console.error('[route-forge/codegen] no levels found; pass --levels explicitly');\n    process.exit(1);\n  }\n\n  const levelFetches = await Promise.allSettled(\n    levels.map((lvl) => fetchLevel(opts.endpoint, lvl)),\n  );\n\n  const routesByLevel: Record<string, Record<string, RouteMeta>> = {};\n  let failedLevels = 0;\n  levelFetches.forEach((res, idx) => {\n    if (res.status === 'fulfilled') {\n      routesByLevel[levels[idx]!] = res.value.routes;\n    } else {\n      failedLevels++;\n      console.warn(`[route-forge/codegen] failed to fetch level \"${levels[idx]}\": ${(res.reason as Error).message}`);\n    }\n  });\n\n  const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);\n  if (totalRoutes === 0) {\n    console.error('[route-forge/codegen] no routes collected from any level');\n    process.exit(1);\n  }\n\n  const dts = generateRouteTypes(routesByLevel);\n\n  const fs = await import('node:fs/promises');\n  const path = await import('node:path');\n  const outPath = path.resolve(opts.out);\n  const dir = path.dirname(outPath);\n  await fs.mkdir(dir, { recursive: true });\n  await fs.writeFile(outPath, dts, 'utf8');\n\n  console.log(`[route-forge/codegen] written ${totalRoutes} routes across ${Object.keys(routesByLevel).length} level(s) to ${outPath}`);\n  if (failedLevels > 0) {\n    console.warn(`[route-forge/codegen] ${failedLevels} level(s) failed; output may be incomplete`);\n  }\n}\n\nconst invokedFromCli = (() => {\n  try {\n    if (!process.argv[1]) return false;\n    const argv1 = process.argv[1].replace(/\\\\/g, '/');\n    return argv1.endsWith('/codegen.js') || argv1.endsWith('/codegen.cjs') || argv1.endsWith('/codegen');\n  } catch {\n    return false;\n  }\n})();\n\nif (invokedFromCli) {\n  main().catch((err) => {\n    console.error(err);\n    process.exit(1);\n  });\n}\n\nexport { main as runCodegen };\n"]}
+{"version":3,"sources":["../src/codegen/index.ts"],"names":[],"mappings":"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","file":"codegen.cjs","sourcesContent":["#!/usr/bin/env node\n/**\n * @route-forge/core codegen CLI\n * @see .docs/SPEC.md §4.2\n *\n * 用法：\n *   npx @route-forge/core codegen \\\n *     --endpoint http://localhost/_forge/routes \\\n *     --levels public,client,manage,admin \\\n *     --out src/types/forge-routes.d.ts\n */\n\nimport type { RouteMeta } from '../types.js';\n\nexport interface CodegenOptions {\n  endpoint: string;\n  levels: string[];\n  out: string;\n  responseTypes?: string;\n}\n\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);\n\n/**\n * 解析 argv（最小手写实现，不引入 commander/yargs）\n * 支持：--endpoint VALUE / --endpoint=VALUE / --levels a,b,c / --out PATH / --responseTypes PATH\n */\nexport function parseArgs(argv: string[]): CodegenOptions {\n  const opts: Partial<CodegenOptions> = {};\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const next = (): string => {\n      const v = argv[++i];\n      if (v === undefined) {\n        throw new Error(`[route-forge/codegen] missing value for ${arg}`);\n      }\n      return v;\n    };\n\n    if (arg === '--endpoint') {\n      opts.endpoint = next();\n    } else if (arg?.startsWith('--endpoint=')) {\n      opts.endpoint = arg.slice('--endpoint='.length);\n    } else if (arg === '--levels') {\n      opts.levels = next().split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg?.startsWith('--levels=')) {\n      opts.levels = arg.slice('--levels='.length).split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg === '--out') {\n      opts.out = next();\n    } else if (arg?.startsWith('--out=')) {\n      opts.out = arg.slice('--out='.length);\n    } else if (arg === '--responseTypes') {\n      opts.responseTypes = next();\n    } else if (arg?.startsWith('--responseTypes=')) {\n      opts.responseTypes = arg.slice('--responseTypes='.length);\n    } else if (arg === '--help' || arg === '-h') {\n      printHelp();\n      process.exit(0);\n    }\n  }\n\n  if (!opts.endpoint) {\n    console.error('[route-forge/codegen] --endpoint is required');\n    printHelp();\n    process.exit(1);\n  }\n  if (!opts.out) {\n    console.error('[route-forge/codegen] --out is required');\n    printHelp();\n    process.exit(1);\n  }\n\n  return {\n    endpoint: opts.endpoint,\n    levels: opts.levels ?? [],\n    out: opts.out,\n    responseTypes: opts.responseTypes,\n  };\n}\n\nfunction printHelp(): void {\n  console.log(`\nroute-forge codegen - generate TS route types from backend summary endpoint\n\nUsage:\n  npx @route-forge/core codegen --endpoint URL --out PATH [--levels a,b,c] [--responseTypes PATH]\n\nOptions:\n  --endpoint URL         Backend summary endpoint (e.g. http://localhost/_forge/routes)\n  --levels a,b,c         Optional: explicit level list (skip auto-discovery)\n  --out PATH              Output .d.ts file path\n  --responseTypes PATH    Optional: JSON file mapping route names to response types\n  -h, --help              Show this help\n`);\n}\n\n/**\n * 拉取摘要端点\n */\nexport async function fetchSummary(endpoint: string): Promise<{\n  levels: Record<string, unknown>;\n  unassigned?: Array<{\n    name: string;\n    uri: string;\n    methods: string[];\n    parameters: string[];\n    parameter_defaults?: Record<string, unknown>;\n  }>;\n}> {\n  const resp = await fetch(endpoint, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`summary endpoint ${endpoint} returned ${resp.status}`);\n  }\n  return (await resp.json()) as {\n    levels: Record<string, unknown>;\n    unassigned?: Array<{\n      name: string;\n      uri: string;\n      methods: string[];\n      parameters: string[];\n      parameter_defaults?: Record<string, unknown>;\n    }>;\n  };\n}\n\n/**\n * 拉取单个层级的路由元信息\n */\nexport async function fetchLevel(endpoint: string, level: string): Promise<{ routes: Record<string, RouteMeta> }> {\n  const base = endpoint.replace(/\\/$/, '');\n  const url = `${base}/${encodeURIComponent(level)}`;\n  const resp = await fetch(url, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`level endpoint ${url} returned ${resp.status}`);\n  }\n  const data = (await resp.json()) as { routes?: Record<string, RouteMeta> };\n  return { routes: data.routes ?? {} };\n}\n\n/**\n * 生成 d.ts 内容\n * @param routesByLevel 按层级分组的路由元信息：{ level: { routeName: meta } }\n */\nexport function generateRouteTypes(routesByLevel: Record<string, Record<string, RouteMeta>>): string {\n  const levelEntries = Object.entries(routesByLevel).map(([level, routes]) => {\n    const routeEntries = Object.entries(routes).map(([name, meta]) => {\n      const defaults = meta.parameter_defaults ?? {};\n      const params = (meta.parameters ?? []).map((p) => {\n        // URI 中的 {p?} 或有后端默认值的参数 → 生成可选字段，避免调用方被迫传参\n        const optional = meta.uri?.includes(`{${p}?}`) || p in defaults;\n        return `${p}${optional ? '?' : ''}: string | number;`;\n      }).join(' ');\n      const method = meta.methods?.find((m) => m.toUpperCase() !== 'HEAD') ?? 'GET';\n      const methodUpper = method.toUpperCase();\n      const bodyField = BODY_METHODS.has(methodUpper) ? '\\n      body: unknown;' : '';\n      return `    ${JSON.stringify(name)}: {\\n      method: ${JSON.stringify(methodUpper)};\\n      params: { ${params} };${bodyField}\\n      response: unknown;\\n    };`;\n    });\n    return `  ${JSON.stringify(level)}: {\\n${routeEntries.join('\\n')}\\n  };`;\n  });\n  return `// AUTO-GENERATED by @route-forge/core codegen. Do not edit.\n\n/**\n * 二级路由类型映射：level → routeName → routeMeta\n * 可通过 module augmentation 增强：\n *   declare module '@route-forge/core' {\n *     interface ForgeRouteMap { admin: { 'users.show': { method: 'GET'; params: { user: string | number }; response: User } } }\n *   }\n */\nexport interface ForgeRouteMap {\n${levelEntries.join('\\n')}\n}\n`;\n}\n\n/**\n * CLI 主入口\n */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const opts = parseArgs(argv);\n\n  let levels = opts.levels;\n  // 摘要端点数据（用于自动发现层级 + 获取 unassigned 路由）\n  let summaryData: Awaited<ReturnType<typeof fetchSummary>> | null = null;\n  if (levels.length === 0) {\n    try {\n      summaryData = await fetchSummary(opts.endpoint);\n      levels = Object.keys(summaryData.levels);\n    } catch (e) {\n      console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${(e as Error).message}`);\n      console.error('hint: pass --levels explicitly to skip auto-discovery');\n      process.exit(1);\n    }\n  }\n\n  // 未指定 --levels 或显式包含 unassigned 时，从摘要端点获取未分配路由\n  // @see .docs/SPEC.md §3.1.6\n  const UNASSIGNED_LEVEL = 'unassigned';\n  let unassignedRoutes: Record<string, RouteMeta> | null = null;\n  // 自动发现时检查摘要数据中是否有 unassigned 路由；显式指定 --levels 时仅当包含 unassigned 才处理\n  const needsUnassigned =\n    levels.includes(UNASSIGNED_LEVEL) || (summaryData && summaryData.unassigned && summaryData.unassigned.length > 0);\n  if (needsUnassigned) {\n    if (!summaryData) {\n      try {\n        summaryData = await fetchSummary(opts.endpoint);\n      } catch (e) {\n        console.warn(`[route-forge/codegen] failed to fetch summary for unassigned routes: ${(e as Error).message}`);\n      }\n    }\n    if (summaryData?.unassigned && summaryData.unassigned.length > 0) {\n      unassignedRoutes = {};\n      for (const r of summaryData.unassigned) {\n        unassignedRoutes[r.name] = { ...r, level: UNASSIGNED_LEVEL };\n      }\n      if (!levels.includes(UNASSIGNED_LEVEL)) {\n        levels.push(UNASSIGNED_LEVEL);\n      }\n    }\n  }\n\n  if (levels.length === 0) {\n    console.error('[route-forge/codegen] no levels found; pass --levels explicitly');\n    process.exit(1);\n  }\n\n  const levelFetches = await Promise.allSettled(\n    levels\n      .filter((lvl) => lvl !== UNASSIGNED_LEVEL)  // unassigned 不走 HTTP 拉取\n      .map((lvl) => fetchLevel(opts.endpoint, lvl)),\n  );\n\n  const routesByLevel: Record<string, Record<string, RouteMeta>> = {};\n  let failedLevels = 0;\n  levelFetches.forEach((res, idx) => {\n    const lvl = levels.filter((l) => l !== UNASSIGNED_LEVEL)[idx]!;\n    if (res.status === 'fulfilled') {\n      routesByLevel[lvl] = res.value.routes;\n    } else {\n      failedLevels++;\n      console.warn(`[route-forge/codegen] failed to fetch level \"${lvl}\": ${(res.reason as Error).message}`);\n    }\n  });\n  // unassigned 路由直接从摘要数据填充\n  if (unassignedRoutes) {\n    routesByLevel[UNASSIGNED_LEVEL] = unassignedRoutes;\n  }\n\n  const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);\n  if (totalRoutes === 0) {\n    console.error('[route-forge/codegen] no routes collected from any level');\n    process.exit(1);\n  }\n\n  const dts = generateRouteTypes(routesByLevel);\n\n  const fs = await import('node:fs/promises');\n  const path = await import('node:path');\n  const outPath = path.resolve(opts.out);\n  const dir = path.dirname(outPath);\n  await fs.mkdir(dir, { recursive: true });\n  await fs.writeFile(outPath, dts, 'utf8');\n\n  console.log(`[route-forge/codegen] written ${totalRoutes} routes across ${Object.keys(routesByLevel).length} level(s) to ${outPath}`);\n  if (failedLevels > 0) {\n    console.warn(`[route-forge/codegen] ${failedLevels} level(s) failed; output may be incomplete`);\n  }\n}\n\nconst invokedFromCli = (() => {\n  try {\n    if (!process.argv[1]) return false;\n    const argv1 = process.argv[1].replace(/\\\\/g, '/');\n    return argv1.endsWith('/codegen.js') || argv1.endsWith('/codegen.cjs') || argv1.endsWith('/codegen');\n  } catch {\n    return false;\n  }\n})();\n\nif (invokedFromCli) {\n  main().catch((err) => {\n    console.error(err);\n    process.exit(1);\n  });\n}\n\nexport { main as runCodegen };\n"]}

package/dist/codegen.d.cts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-DExMMUu1.cjs';
+import { R as RouteMeta } from './types-pHQLqpYF.cjs';
 
 /**
  * @route-forge/core codegen CLI
@@ -28,6 +28,13 @@ declare function parseArgs(argv: string[]): CodegenOptions;
  */
 declare function fetchSummary(endpoint: string): Promise<{
     levels: Record<string, unknown>;
+    unassigned?: Array<{
+        name: string;
+        uri: string;
+        methods: string[];
+        parameters: string[];
+        parameter_defaults?: Record<string, unknown>;
+    }>;
 }>;
 /**
  * 拉取单个层级的路由元信息

package/dist/codegen.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { R as RouteMeta } from './types-DExMMUu1.js';
+import { R as RouteMeta } from './types-pHQLqpYF.js';
 
 /**
  * @route-forge/core codegen CLI
@@ -28,6 +28,13 @@ declare function parseArgs(argv: string[]): CodegenOptions;
  */
 declare function fetchSummary(endpoint: string): Promise<{
     levels: Record<string, unknown>;
+    unassigned?: Array<{
+        name: string;
+        uri: string;
+        methods: string[];
+        parameters: string[];
+        parameter_defaults?: Record<string, unknown>;
+    }>;
 }>;
 /**
  * 拉取单个层级的路由元信息

package/dist/codegen.js

@@ -120,33 +120,59 @@ ${levelEntries.join("\n")}
 async function main(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv);
   let levels = opts.levels;
+  let summaryData = null;
   if (levels.length === 0) {
     try {
-      const summary = await fetchSummary(opts.endpoint);
-      levels = Object.keys(summary.levels);
+      summaryData = await fetchSummary(opts.endpoint);
+      levels = Object.keys(summaryData.levels);
     } catch (e) {
       console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${e.message}`);
       console.error("hint: pass --levels explicitly to skip auto-discovery");
       process.exit(1);
     }
   }
+  const UNASSIGNED_LEVEL = "unassigned";
+  let unassignedRoutes = null;
+  const needsUnassigned = levels.includes(UNASSIGNED_LEVEL) || summaryData && summaryData.unassigned && summaryData.unassigned.length > 0;
+  if (needsUnassigned) {
+    if (!summaryData) {
+      try {
+        summaryData = await fetchSummary(opts.endpoint);
+      } catch (e) {
+        console.warn(`[route-forge/codegen] failed to fetch summary for unassigned routes: ${e.message}`);
+      }
+    }
+    if (summaryData?.unassigned && summaryData.unassigned.length > 0) {
+      unassignedRoutes = {};
+      for (const r of summaryData.unassigned) {
+        unassignedRoutes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
+      }
+      if (!levels.includes(UNASSIGNED_LEVEL)) {
+        levels.push(UNASSIGNED_LEVEL);
+      }
+    }
+  }
   if (levels.length === 0) {
     console.error("[route-forge/codegen] no levels found; pass --levels explicitly");
     process.exit(1);
   }
   const levelFetches = await Promise.allSettled(
-    levels.map((lvl) => fetchLevel(opts.endpoint, lvl))
+    levels.filter((lvl) => lvl !== UNASSIGNED_LEVEL).map((lvl) => fetchLevel(opts.endpoint, lvl))
   );
   const routesByLevel = {};
   let failedLevels = 0;
   levelFetches.forEach((res, idx) => {
+    const lvl = levels.filter((l) => l !== UNASSIGNED_LEVEL)[idx];
     if (res.status === "fulfilled") {
-      routesByLevel[levels[idx]] = res.value.routes;
+      routesByLevel[lvl] = res.value.routes;
     } else {
       failedLevels++;
-      console.warn(`[route-forge/codegen] failed to fetch level "${levels[idx]}": ${res.reason.message}`);
+      console.warn(`[route-forge/codegen] failed to fetch level "${lvl}": ${res.reason.message}`);
     }
   });
+  if (unassignedRoutes) {
+    routesByLevel[UNASSIGNED_LEVEL] = unassignedRoutes;
+  }
   const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);
   if (totalRoutes === 0) {
     console.error("[route-forge/codegen] no routes collected from any level");

package/dist/codegen.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/codegen/index.ts"],"names":[],"mappings":"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","file":"codegen.js","sourcesContent":["#!/usr/bin/env node\n/**\n * @route-forge/core codegen CLI\n * @see .docs/SPEC.md §4.2\n *\n * 用法：\n *   npx @route-forge/core codegen \\\n *     --endpoint http://localhost/_forge/routes \\\n *     --levels public,client,manage,admin \\\n *     --out src/types/forge-routes.d.ts\n */\n\nimport type { RouteMeta } from '../types.js';\n\nexport interface CodegenOptions {\n  endpoint: string;\n  levels: string[];\n  out: string;\n  responseTypes?: string;\n}\n\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);\n\n/**\n * 解析 argv（最小手写实现，不引入 commander/yargs）\n * 支持：--endpoint VALUE / --endpoint=VALUE / --levels a,b,c / --out PATH / --responseTypes PATH\n */\nexport function parseArgs(argv: string[]): CodegenOptions {\n  const opts: Partial<CodegenOptions> = {};\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const next = (): string => {\n      const v = argv[++i];\n      if (v === undefined) {\n        throw new Error(`[route-forge/codegen] missing value for ${arg}`);\n      }\n      return v;\n    };\n\n    if (arg === '--endpoint') {\n      opts.endpoint = next();\n    } else if (arg?.startsWith('--endpoint=')) {\n      opts.endpoint = arg.slice('--endpoint='.length);\n    } else if (arg === '--levels') {\n      opts.levels = next().split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg?.startsWith('--levels=')) {\n      opts.levels = arg.slice('--levels='.length).split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg === '--out') {\n      opts.out = next();\n    } else if (arg?.startsWith('--out=')) {\n      opts.out = arg.slice('--out='.length);\n    } else if (arg === '--responseTypes') {\n      opts.responseTypes = next();\n    } else if (arg?.startsWith('--responseTypes=')) {\n      opts.responseTypes = arg.slice('--responseTypes='.length);\n    } else if (arg === '--help' || arg === '-h') {\n      printHelp();\n      process.exit(0);\n    }\n  }\n\n  if (!opts.endpoint) {\n    console.error('[route-forge/codegen] --endpoint is required');\n    printHelp();\n    process.exit(1);\n  }\n  if (!opts.out) {\n    console.error('[route-forge/codegen] --out is required');\n    printHelp();\n    process.exit(1);\n  }\n\n  return {\n    endpoint: opts.endpoint,\n    levels: opts.levels ?? [],\n    out: opts.out,\n    responseTypes: opts.responseTypes,\n  };\n}\n\nfunction printHelp(): void {\n  console.log(`\nroute-forge codegen - generate TS route types from backend summary endpoint\n\nUsage:\n  npx @route-forge/core codegen --endpoint URL --out PATH [--levels a,b,c] [--responseTypes PATH]\n\nOptions:\n  --endpoint URL         Backend summary endpoint (e.g. http://localhost/_forge/routes)\n  --levels a,b,c         Optional: explicit level list (skip auto-discovery)\n  --out PATH              Output .d.ts file path\n  --responseTypes PATH    Optional: JSON file mapping route names to response types\n  -h, --help              Show this help\n`);\n}\n\n/**\n * 拉取摘要端点\n */\nexport async function fetchSummary(endpoint: string): Promise<{ levels: Record<string, unknown> }> {\n  const resp = await fetch(endpoint, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`summary endpoint ${endpoint} returned ${resp.status}`);\n  }\n  return (await resp.json()) as { levels: Record<string, unknown> };\n}\n\n/**\n * 拉取单个层级的路由元信息\n */\nexport async function fetchLevel(endpoint: string, level: string): Promise<{ routes: Record<string, RouteMeta> }> {\n  const base = endpoint.replace(/\\/$/, '');\n  const url = `${base}/${encodeURIComponent(level)}`;\n  const resp = await fetch(url, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`level endpoint ${url} returned ${resp.status}`);\n  }\n  const data = (await resp.json()) as { routes?: Record<string, RouteMeta> };\n  return { routes: data.routes ?? {} };\n}\n\n/**\n * 生成 d.ts 内容\n * @param routesByLevel 按层级分组的路由元信息：{ level: { routeName: meta } }\n */\nexport function generateRouteTypes(routesByLevel: Record<string, Record<string, RouteMeta>>): string {\n  const levelEntries = Object.entries(routesByLevel).map(([level, routes]) => {\n    const routeEntries = Object.entries(routes).map(([name, meta]) => {\n      const defaults = meta.parameter_defaults ?? {};\n      const params = (meta.parameters ?? []).map((p) => {\n        // URI 中的 {p?} 或有后端默认值的参数 → 生成可选字段，避免调用方被迫传参\n        const optional = meta.uri?.includes(`{${p}?}`) || p in defaults;\n        return `${p}${optional ? '?' : ''}: string | number;`;\n      }).join(' ');\n      const method = meta.methods?.find((m) => m.toUpperCase() !== 'HEAD') ?? 'GET';\n      const methodUpper = method.toUpperCase();\n      const bodyField = BODY_METHODS.has(methodUpper) ? '\\n      body: unknown;' : '';\n      return `    ${JSON.stringify(name)}: {\\n      method: ${JSON.stringify(methodUpper)};\\n      params: { ${params} };${bodyField}\\n      response: unknown;\\n    };`;\n    });\n    return `  ${JSON.stringify(level)}: {\\n${routeEntries.join('\\n')}\\n  };`;\n  });\n  return `// AUTO-GENERATED by @route-forge/core codegen. Do not edit.\n\n/**\n * 二级路由类型映射：level → routeName → routeMeta\n * 可通过 module augmentation 增强：\n *   declare module '@route-forge/core' {\n *     interface ForgeRouteMap { admin: { 'users.show': { method: 'GET'; params: { user: string | number }; response: User } } }\n *   }\n */\nexport interface ForgeRouteMap {\n${levelEntries.join('\\n')}\n}\n`;\n}\n\n/**\n * CLI 主入口\n */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const opts = parseArgs(argv);\n\n  let levels = opts.levels;\n  if (levels.length === 0) {\n    try {\n      const summary = await fetchSummary(opts.endpoint);\n      levels = Object.keys(summary.levels);\n    } catch (e) {\n      console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${(e as Error).message}`);\n      console.error('hint: pass --levels explicitly to skip auto-discovery');\n      process.exit(1);\n    }\n  }\n\n  if (levels.length === 0) {\n    console.error('[route-forge/codegen] no levels found; pass --levels explicitly');\n    process.exit(1);\n  }\n\n  const levelFetches = await Promise.allSettled(\n    levels.map((lvl) => fetchLevel(opts.endpoint, lvl)),\n  );\n\n  const routesByLevel: Record<string, Record<string, RouteMeta>> = {};\n  let failedLevels = 0;\n  levelFetches.forEach((res, idx) => {\n    if (res.status === 'fulfilled') {\n      routesByLevel[levels[idx]!] = res.value.routes;\n    } else {\n      failedLevels++;\n      console.warn(`[route-forge/codegen] failed to fetch level \"${levels[idx]}\": ${(res.reason as Error).message}`);\n    }\n  });\n\n  const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);\n  if (totalRoutes === 0) {\n    console.error('[route-forge/codegen] no routes collected from any level');\n    process.exit(1);\n  }\n\n  const dts = generateRouteTypes(routesByLevel);\n\n  const fs = await import('node:fs/promises');\n  const path = await import('node:path');\n  const outPath = path.resolve(opts.out);\n  const dir = path.dirname(outPath);\n  await fs.mkdir(dir, { recursive: true });\n  await fs.writeFile(outPath, dts, 'utf8');\n\n  console.log(`[route-forge/codegen] written ${totalRoutes} routes across ${Object.keys(routesByLevel).length} level(s) to ${outPath}`);\n  if (failedLevels > 0) {\n    console.warn(`[route-forge/codegen] ${failedLevels} level(s) failed; output may be incomplete`);\n  }\n}\n\nconst invokedFromCli = (() => {\n  try {\n    if (!process.argv[1]) return false;\n    const argv1 = process.argv[1].replace(/\\\\/g, '/');\n    return argv1.endsWith('/codegen.js') || argv1.endsWith('/codegen.cjs') || argv1.endsWith('/codegen');\n  } catch {\n    return false;\n  }\n})();\n\nif (invokedFromCli) {\n  main().catch((err) => {\n    console.error(err);\n    process.exit(1);\n  });\n}\n\nexport { main as runCodegen };\n"]}
+{"version":3,"sources":["../src/codegen/index.ts"],"names":[],"mappings":"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","file":"codegen.js","sourcesContent":["#!/usr/bin/env node\n/**\n * @route-forge/core codegen CLI\n * @see .docs/SPEC.md §4.2\n *\n * 用法：\n *   npx @route-forge/core codegen \\\n *     --endpoint http://localhost/_forge/routes \\\n *     --levels public,client,manage,admin \\\n *     --out src/types/forge-routes.d.ts\n */\n\nimport type { RouteMeta } from '../types.js';\n\nexport interface CodegenOptions {\n  endpoint: string;\n  levels: string[];\n  out: string;\n  responseTypes?: string;\n}\n\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);\n\n/**\n * 解析 argv（最小手写实现，不引入 commander/yargs）\n * 支持：--endpoint VALUE / --endpoint=VALUE / --levels a,b,c / --out PATH / --responseTypes PATH\n */\nexport function parseArgs(argv: string[]): CodegenOptions {\n  const opts: Partial<CodegenOptions> = {};\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const next = (): string => {\n      const v = argv[++i];\n      if (v === undefined) {\n        throw new Error(`[route-forge/codegen] missing value for ${arg}`);\n      }\n      return v;\n    };\n\n    if (arg === '--endpoint') {\n      opts.endpoint = next();\n    } else if (arg?.startsWith('--endpoint=')) {\n      opts.endpoint = arg.slice('--endpoint='.length);\n    } else if (arg === '--levels') {\n      opts.levels = next().split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg?.startsWith('--levels=')) {\n      opts.levels = arg.slice('--levels='.length).split(',').map((s) => s.trim()).filter(Boolean);\n    } else if (arg === '--out') {\n      opts.out = next();\n    } else if (arg?.startsWith('--out=')) {\n      opts.out = arg.slice('--out='.length);\n    } else if (arg === '--responseTypes') {\n      opts.responseTypes = next();\n    } else if (arg?.startsWith('--responseTypes=')) {\n      opts.responseTypes = arg.slice('--responseTypes='.length);\n    } else if (arg === '--help' || arg === '-h') {\n      printHelp();\n      process.exit(0);\n    }\n  }\n\n  if (!opts.endpoint) {\n    console.error('[route-forge/codegen] --endpoint is required');\n    printHelp();\n    process.exit(1);\n  }\n  if (!opts.out) {\n    console.error('[route-forge/codegen] --out is required');\n    printHelp();\n    process.exit(1);\n  }\n\n  return {\n    endpoint: opts.endpoint,\n    levels: opts.levels ?? [],\n    out: opts.out,\n    responseTypes: opts.responseTypes,\n  };\n}\n\nfunction printHelp(): void {\n  console.log(`\nroute-forge codegen - generate TS route types from backend summary endpoint\n\nUsage:\n  npx @route-forge/core codegen --endpoint URL --out PATH [--levels a,b,c] [--responseTypes PATH]\n\nOptions:\n  --endpoint URL         Backend summary endpoint (e.g. http://localhost/_forge/routes)\n  --levels a,b,c         Optional: explicit level list (skip auto-discovery)\n  --out PATH              Output .d.ts file path\n  --responseTypes PATH    Optional: JSON file mapping route names to response types\n  -h, --help              Show this help\n`);\n}\n\n/**\n * 拉取摘要端点\n */\nexport async function fetchSummary(endpoint: string): Promise<{\n  levels: Record<string, unknown>;\n  unassigned?: Array<{\n    name: string;\n    uri: string;\n    methods: string[];\n    parameters: string[];\n    parameter_defaults?: Record<string, unknown>;\n  }>;\n}> {\n  const resp = await fetch(endpoint, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`summary endpoint ${endpoint} returned ${resp.status}`);\n  }\n  return (await resp.json()) as {\n    levels: Record<string, unknown>;\n    unassigned?: Array<{\n      name: string;\n      uri: string;\n      methods: string[];\n      parameters: string[];\n      parameter_defaults?: Record<string, unknown>;\n    }>;\n  };\n}\n\n/**\n * 拉取单个层级的路由元信息\n */\nexport async function fetchLevel(endpoint: string, level: string): Promise<{ routes: Record<string, RouteMeta> }> {\n  const base = endpoint.replace(/\\/$/, '');\n  const url = `${base}/${encodeURIComponent(level)}`;\n  const resp = await fetch(url, { method: 'GET' });\n  if (!resp.ok) {\n    throw new Error(`level endpoint ${url} returned ${resp.status}`);\n  }\n  const data = (await resp.json()) as { routes?: Record<string, RouteMeta> };\n  return { routes: data.routes ?? {} };\n}\n\n/**\n * 生成 d.ts 内容\n * @param routesByLevel 按层级分组的路由元信息：{ level: { routeName: meta } }\n */\nexport function generateRouteTypes(routesByLevel: Record<string, Record<string, RouteMeta>>): string {\n  const levelEntries = Object.entries(routesByLevel).map(([level, routes]) => {\n    const routeEntries = Object.entries(routes).map(([name, meta]) => {\n      const defaults = meta.parameter_defaults ?? {};\n      const params = (meta.parameters ?? []).map((p) => {\n        // URI 中的 {p?} 或有后端默认值的参数 → 生成可选字段，避免调用方被迫传参\n        const optional = meta.uri?.includes(`{${p}?}`) || p in defaults;\n        return `${p}${optional ? '?' : ''}: string | number;`;\n      }).join(' ');\n      const method = meta.methods?.find((m) => m.toUpperCase() !== 'HEAD') ?? 'GET';\n      const methodUpper = method.toUpperCase();\n      const bodyField = BODY_METHODS.has(methodUpper) ? '\\n      body: unknown;' : '';\n      return `    ${JSON.stringify(name)}: {\\n      method: ${JSON.stringify(methodUpper)};\\n      params: { ${params} };${bodyField}\\n      response: unknown;\\n    };`;\n    });\n    return `  ${JSON.stringify(level)}: {\\n${routeEntries.join('\\n')}\\n  };`;\n  });\n  return `// AUTO-GENERATED by @route-forge/core codegen. Do not edit.\n\n/**\n * 二级路由类型映射：level → routeName → routeMeta\n * 可通过 module augmentation 增强：\n *   declare module '@route-forge/core' {\n *     interface ForgeRouteMap { admin: { 'users.show': { method: 'GET'; params: { user: string | number }; response: User } } }\n *   }\n */\nexport interface ForgeRouteMap {\n${levelEntries.join('\\n')}\n}\n`;\n}\n\n/**\n * CLI 主入口\n */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const opts = parseArgs(argv);\n\n  let levels = opts.levels;\n  // 摘要端点数据（用于自动发现层级 + 获取 unassigned 路由）\n  let summaryData: Awaited<ReturnType<typeof fetchSummary>> | null = null;\n  if (levels.length === 0) {\n    try {\n      summaryData = await fetchSummary(opts.endpoint);\n      levels = Object.keys(summaryData.levels);\n    } catch (e) {\n      console.error(`[route-forge/codegen] failed to auto-discover levels from summary endpoint: ${(e as Error).message}`);\n      console.error('hint: pass --levels explicitly to skip auto-discovery');\n      process.exit(1);\n    }\n  }\n\n  // 未指定 --levels 或显式包含 unassigned 时，从摘要端点获取未分配路由\n  // @see .docs/SPEC.md §3.1.6\n  const UNASSIGNED_LEVEL = 'unassigned';\n  let unassignedRoutes: Record<string, RouteMeta> | null = null;\n  // 自动发现时检查摘要数据中是否有 unassigned 路由；显式指定 --levels 时仅当包含 unassigned 才处理\n  const needsUnassigned =\n    levels.includes(UNASSIGNED_LEVEL) || (summaryData && summaryData.unassigned && summaryData.unassigned.length > 0);\n  if (needsUnassigned) {\n    if (!summaryData) {\n      try {\n        summaryData = await fetchSummary(opts.endpoint);\n      } catch (e) {\n        console.warn(`[route-forge/codegen] failed to fetch summary for unassigned routes: ${(e as Error).message}`);\n      }\n    }\n    if (summaryData?.unassigned && summaryData.unassigned.length > 0) {\n      unassignedRoutes = {};\n      for (const r of summaryData.unassigned) {\n        unassignedRoutes[r.name] = { ...r, level: UNASSIGNED_LEVEL };\n      }\n      if (!levels.includes(UNASSIGNED_LEVEL)) {\n        levels.push(UNASSIGNED_LEVEL);\n      }\n    }\n  }\n\n  if (levels.length === 0) {\n    console.error('[route-forge/codegen] no levels found; pass --levels explicitly');\n    process.exit(1);\n  }\n\n  const levelFetches = await Promise.allSettled(\n    levels\n      .filter((lvl) => lvl !== UNASSIGNED_LEVEL)  // unassigned 不走 HTTP 拉取\n      .map((lvl) => fetchLevel(opts.endpoint, lvl)),\n  );\n\n  const routesByLevel: Record<string, Record<string, RouteMeta>> = {};\n  let failedLevels = 0;\n  levelFetches.forEach((res, idx) => {\n    const lvl = levels.filter((l) => l !== UNASSIGNED_LEVEL)[idx]!;\n    if (res.status === 'fulfilled') {\n      routesByLevel[lvl] = res.value.routes;\n    } else {\n      failedLevels++;\n      console.warn(`[route-forge/codegen] failed to fetch level \"${lvl}\": ${(res.reason as Error).message}`);\n    }\n  });\n  // unassigned 路由直接从摘要数据填充\n  if (unassignedRoutes) {\n    routesByLevel[UNASSIGNED_LEVEL] = unassignedRoutes;\n  }\n\n  const totalRoutes = Object.values(routesByLevel).reduce((sum, r) => sum + Object.keys(r).length, 0);\n  if (totalRoutes === 0) {\n    console.error('[route-forge/codegen] no routes collected from any level');\n    process.exit(1);\n  }\n\n  const dts = generateRouteTypes(routesByLevel);\n\n  const fs = await import('node:fs/promises');\n  const path = await import('node:path');\n  const outPath = path.resolve(opts.out);\n  const dir = path.dirname(outPath);\n  await fs.mkdir(dir, { recursive: true });\n  await fs.writeFile(outPath, dts, 'utf8');\n\n  console.log(`[route-forge/codegen] written ${totalRoutes} routes across ${Object.keys(routesByLevel).length} level(s) to ${outPath}`);\n  if (failedLevels > 0) {\n    console.warn(`[route-forge/codegen] ${failedLevels} level(s) failed; output may be incomplete`);\n  }\n}\n\nconst invokedFromCli = (() => {\n  try {\n    if (!process.argv[1]) return false;\n    const argv1 = process.argv[1].replace(/\\\\/g, '/');\n    return argv1.endsWith('/codegen.js') || argv1.endsWith('/codegen.cjs') || argv1.endsWith('/codegen');\n  } catch {\n    return false;\n  }\n})();\n\nif (invokedFromCli) {\n  main().catch((err) => {\n    console.error(err);\n    process.exit(1);\n  });\n}\n\nexport { main as runCodegen };\n"]}

package/dist/index.cjs

@@ -174,6 +174,16 @@ var HTTPError = class extends ForgeError {
     });
   }
 };
+var RequestAbortedError = class extends ForgeError {
+  constructor(route, level, cause) {
+    super(`Request aborted${route ? ` for route "${route}"` : ""}`, {
+      code: "RF_FE_009",
+      route,
+      level,
+      cause
+    });
+  }
+};
 
 // src/interceptors.ts
 var InterceptorManagerImpl = class {
@@ -246,12 +256,36 @@ function isPassthroughBody(body) {
   if (body === null) return false;
   return typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof Blob !== "undefined" && body instanceof Blob || typeof ArrayBuffer !== "undefined" && (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
 }
+function isAbortError(err) {
+  const e = err;
+  return !!e && e.name === "AbortError";
+}
+function combineSignals(...signals) {
+  const valid = signals.filter((s) => !!s);
+  if (valid.length === 0) return void 0;
+  if (valid.length === 1) return valid[0];
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.any === "function") {
+    return AbortSignal.any(valid);
+  }
+  const controller = new AbortController();
+  for (const s of valid) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      return controller.signal;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+  }
+  return controller.signal;
+}
 function createBuiltinHttp(forgeInterceptors) {
   const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
   const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
   async function request(config) {
     const finalConfig = await runRequestInterceptors(requestMgr, config);
-    const signal = finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0;
+    const signal = combineSignals(
+      finalConfig.signal,
+      finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0
+    );
     let url = finalConfig.url;
     if (finalConfig.paramsSerializer && finalConfig.params) {
       const qs = finalConfig.paramsSerializer(finalConfig.params);
@@ -279,6 +313,7 @@ function createBuiltinHttp(forgeInterceptors) {
     try {
       res = await fetch(url, fetchInit);
     } catch (e) {
+      if (isAbortError(e)) throw e;
       throw new NetworkError(
         e instanceof Error ? e.message : String(e),
         finalConfig.route,
@@ -375,7 +410,9 @@ async function wrapAxiosAdapter() {
         headers,
         data: config.body,
         // axios 会处理 baseURL/transformRequest 等 defaults；timeout 透传保证超时语义与 builtin 一致
-        timeout: config.timeout
+        timeout: config.timeout,
+        signal: config.signal
+        // 请求取消信号（AbortSignal）
       });
       return {
         route: config.route,
@@ -491,6 +528,7 @@ var LoadingTracker = class {
 // src/forge.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_CACHE_TTL = 3600;
+var UNASSIGNED_LEVEL = "unassigned";
 function createRouteForge(options) {
   if (!options.endpoint) throw new TypeError("options.endpoint is required");
   const {
@@ -509,6 +547,8 @@ function createRouteForge(options) {
   let effectiveEager = explicitEager ?? [];
   let effectiveEndpoint = explicitEndpoint;
   let effectiveUrlPrefix = "";
+  let summaryUnassigned;
+  let backendHasUnassignedLevel = false;
   const summaryPromise = (async () => {
     try {
       const summaryUrl = explicitEndpoint;
@@ -555,9 +595,17 @@ function createRouteForge(options) {
       );
     }
     const backendLevels = Object.keys(summary.levels);
+    backendHasUnassignedLevel = backendLevels.includes(UNASSIGNED_LEVEL);
+    if (Array.isArray(summary.unassigned) && summary.unassigned.length > 0 && !backendHasUnassignedLevel) {
+      summaryUnassigned = summary.unassigned;
+    }
+    const availableLevels = backendLevels.slice();
+    if (summaryUnassigned && !backendHasUnassignedLevel) {
+      availableLevels.push(UNASSIGNED_LEVEL);
+    }
     if (explicitLevels && explicitLevels.length > 0) {
-      const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
-      const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
+      const intersection = explicitLevels.filter((l) => availableLevels.includes(l));
+      const removed = explicitLevels.filter((l) => !availableLevels.includes(l));
       if (removed.length > 0) {
         console.warn(
           `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
@@ -565,7 +613,7 @@ function createRouteForge(options) {
       }
       effectiveLevels = intersection;
     } else {
-      effectiveLevels = backendLevels;
+      effectiveLevels = availableLevels;
     }
     const backendEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
     if (!explicitEager) {
@@ -664,6 +712,14 @@ function createRouteForge(options) {
     if (existing) return existing;
     const p = (async () => {
       try {
+        if (level === UNASSIGNED_LEVEL && !backendHasUnassignedLevel && summaryUnassigned) {
+          const routes = {};
+          for (const r of summaryUnassigned) {
+            routes[r.name] = { ...r, level: UNASSIGNED_LEVEL };
+          }
+          cache.set({ level: UNASSIGNED_LEVEL, routes, cache: null });
+          return;
+        }
         const resp = await fetchLevel(level);
         cache.set(resp);
       } finally {
@@ -740,7 +796,17 @@ function createRouteForge(options) {
     return doApiCall(meta, params);
   }
   async function doApiCall(meta, params) {
-    const { pathParams, query, body, headers, timeout: perCallTimeout } = resolveApiParams(params);
+    const {
+      pathParams,
+      query,
+      body,
+      headers,
+      timeout: perCallTimeout,
+      signal
+    } = resolveApiParams(params);
+    if (signal?.aborted) {
+      throw new RequestAbortedError(meta.name, meta.level, signal.reason);
+    }
     const method = pickMethod(meta);
     const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
     const config = {
@@ -752,10 +818,14 @@ function createRouteForge(options) {
       body,
       params: pathParams,
       timeout: perCallTimeout ?? timeout,
+      signal,
       meta
     };
     const adp = await ensureAdapter();
     const finalConfig = adp.runsInterceptors ? config : await runRequestInterceptors(requestInterceptors, config);
+    if (finalConfig.signal?.aborted) {
+      throw new RequestAbortedError(meta.name, meta.level, finalConfig.signal.reason);
+    }
     loadingTracker.start();
     try {
       const source = adp.request(finalConfig).then(
@@ -776,6 +846,9 @@ function createRouteForge(options) {
         },
         (err) => {
           if (err instanceof ForgeError) throw err;
+          if (isAbortError2(err, finalConfig.signal)) {
+            throw new RequestAbortedError(meta.name, meta.level, err);
+          }
           throw new NetworkError(
             err instanceof Error ? err.message : String(err),
             meta.name,
@@ -876,6 +949,7 @@ function resolveApiParams(input) {
     body: rawBody,
     headers: rawHeaders,
     timeout: perCallTimeout,
+    signal,
     ...flatRest
   } = input;
   const pathParams = explicitParams ? { ...explicitParams } : {};
@@ -908,7 +982,15 @@ function resolveApiParams(input) {
       pathParams.headers = rawHeaders;
     }
   }
-  return { pathParams, query, body, headers, timeout: perCallTimeout };
+  return { pathParams, query, body, headers, timeout: perCallTimeout, signal };
+}
+function isAbortError2(err, signal) {
+  if (signal?.aborted) return true;
+  const e = err;
+  if (!e) return false;
+  if (e.name === "AbortError") return true;
+  if (e.code === "ERR_CANCELED") return true;
+  return false;
 }
 
 exports.AdapterNotFoundError = AdapterNotFoundError;
@@ -919,6 +1001,7 @@ exports.InvalidInterceptorReturnError = InvalidInterceptorReturnError;
 exports.LoadingTracker = LoadingTracker;
 exports.MissingRouteParamError = MissingRouteParamError;
 exports.NetworkError = NetworkError;
+exports.RequestAbortedError = RequestAbortedError;
 exports.RouteCache = RouteCache;
 exports.UnknownLevelError = UnknownLevelError;
 exports.UnknownRouteError = UnknownRouteError;