@gravito/constellation 1.0.0-alpha.6 → 1.0.0

package/dist/{index.mjs → index.js}

@@ -1,76 +1,9 @@
-import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/storage/DiskSitemapStorage.ts
-var exports_DiskSitemapStorage = {};
-__export(exports_DiskSitemapStorage, {
-  DiskSitemapStorage: () => DiskSitemapStorage
-});
-import fs from "node:fs/promises";
-import path from "node:path";
-
-class DiskSitemapStorage {
-  outDir;
-  baseUrl;
-  constructor(outDir, baseUrl) {
-    this.outDir = outDir;
-    this.baseUrl = baseUrl;
-  }
-  async write(filename, content) {
-    await fs.mkdir(this.outDir, { recursive: true });
-    await fs.writeFile(path.join(this.outDir, filename), content);
-  }
-  async read(filename) {
-    try {
-      return await fs.readFile(path.join(this.outDir, filename), "utf-8");
-    } catch {
-      return null;
-    }
-  }
-  async exists(filename) {
-    try {
-      await fs.access(path.join(this.outDir, filename));
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  getUrl(filename) {
-    const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
-    const file = filename.startsWith("/") ? filename.slice(1) : filename;
-    return `${base}/${file}`;
-  }
-}
-var init_DiskSitemapStorage = () => {};
+import {
+  DiskSitemapStorage
+} from "./chunk-7WHLC3OJ.js";
 
 // src/core/ChangeTracker.ts
-class MemoryChangeTracker {
+var MemoryChangeTracker = class {
   changes = [];
   maxChanges;
   constructor(options = {}) {
@@ -98,9 +31,8 @@ class MemoryChangeTracker {
     }
     this.changes = this.changes.filter((change) => change.timestamp < since);
   }
-}
-
-class RedisChangeTracker {
+};
+var RedisChangeTracker = class {
   client;
   keyPrefix;
   ttl;
@@ -175,18 +107,23 @@ class RedisChangeTracker {
           await this.client.zrem(listKey, url);
         }
       }
-    } catch {}
+    } catch {
+    }
   }
-}
+};
+
 // src/core/DiffCalculator.ts
-class DiffCalculator {
+var DiffCalculator = class {
   batchSize;
   constructor(options = {}) {
     this.batchSize = options.batchSize || 1e4;
   }
+  /**
+   * 計算兩個 sitemap 狀態的差異
+   */
   calculate(oldEntries, newEntries) {
-    const oldMap = new Map;
-    const newMap = new Map;
+    const oldMap = /* @__PURE__ */ new Map();
+    const newMap = /* @__PURE__ */ new Map();
     for (const entry of oldEntries) {
       oldMap.set(entry.url, entry);
     }
@@ -211,9 +148,12 @@ class DiffCalculator {
     }
     return { added, updated, removed };
   }
+  /**
+   * 批次計算差異（用於大量 URL）
+   */
   async calculateBatch(oldEntries, newEntries) {
-    const oldMap = new Map;
-    const newMap = new Map;
+    const oldMap = /* @__PURE__ */ new Map();
+    const newMap = /* @__PURE__ */ new Map();
     for await (const entry of oldEntries) {
       oldMap.set(entry.url, entry);
     }
@@ -222,8 +162,11 @@ class DiffCalculator {
     }
     return this.calculate(Array.from(oldMap.values()), Array.from(newMap.values()));
   }
+  /**
+   * 從變更記錄計算差異
+   */
   calculateFromChanges(baseEntries, changes) {
-    const entryMap = new Map;
+    const entryMap = /* @__PURE__ */ new Map();
     for (const entry of baseEntries) {
       entryMap.set(entry.url, entry);
     }
@@ -239,6 +182,9 @@ class DiffCalculator {
     const newEntries = Array.from(entryMap.values());
     return this.calculate(baseEntries, newEntries);
   }
+  /**
+   * 檢查 entry 是否有變更
+   */
   hasChanged(oldEntry, newEntry) {
     if (oldEntry.lastmod !== newEntry.lastmod) {
       return true;
@@ -256,9 +202,10 @@ class DiffCalculator {
     }
     return false;
   }
-}
+};
+
 // src/core/ShadowProcessor.ts
-class ShadowProcessor {
+var ShadowProcessor = class {
   options;
   shadowId;
   operations = [];
@@ -266,6 +213,9 @@ class ShadowProcessor {
     this.options = options;
     this.shadowId = `shadow-${Date.now()}-${Math.random().toString(36).substring(7)}`;
   }
+  /**
+   * 添加一個影子操作
+   */
   async addOperation(operation) {
     if (!this.options.enabled) {
       await this.options.storage.write(operation.filename, operation.content);
@@ -281,6 +231,9 @@ class ShadowProcessor {
       await this.options.storage.write(operation.filename, operation.content);
     }
   }
+  /**
+   * 提交所有影子操作
+   */
   async commit() {
     if (!this.options.enabled) {
       return;
@@ -298,22 +251,31 @@ class ShadowProcessor {
     }
     this.operations = [];
   }
+  /**
+   * 取消所有影子操作
+   */
   async rollback() {
     if (!this.options.enabled) {
       return;
     }
     this.operations = [];
   }
+  /**
+   * 獲取當前影子 ID
+   */
   getShadowId() {
     return this.shadowId;
   }
+  /**
+   * 獲取所有操作
+   */
   getOperations() {
     return [...this.operations];
   }
-}
+};
 
 // src/core/SitemapIndex.ts
-class SitemapIndex {
+var SitemapIndex = class {
   options;
   entries = [];
   constructor(options) {
@@ -344,8 +306,7 @@ class SitemapIndex {
 `;
     const indent = pretty ? "  " : "";
     const subIndent = pretty ? "    " : "";
-    const nl = pretty ? `
-` : "";
+    const nl = pretty ? "\n" : "";
     for (const entry of this.entries) {
       let loc = entry.url;
       if (!loc.startsWith("http")) {
@@ -368,10 +329,10 @@ class SitemapIndex {
   escape(str) {
     return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
   }
-}
+};
 
 // src/core/SitemapStream.ts
-class SitemapStream {
+var SitemapStream = class {
   options;
   entries = [];
   constructor(options) {
@@ -422,8 +383,7 @@ class SitemapStream {
   renderUrl(entry, baseUrl, pretty) {
     const indent = pretty ? "  " : "";
     const subIndent = pretty ? "    " : "";
-    const nl = pretty ? `
-` : "";
+    const nl = pretty ? "\n" : "";
     let loc = entry.url;
     if (!loc.startsWith("http")) {
       if (!loc.startsWith("/")) {
@@ -440,7 +400,7 @@ class SitemapStream {
     if (entry.changefreq) {
       item += `${subIndent}<changefreq>${entry.changefreq}</changefreq>${nl}`;
     }
-    if (entry.priority !== undefined) {
+    if (entry.priority !== void 0) {
       item += `${subIndent}<priority>${entry.priority.toFixed(1)}</priority>${nl}`;
     }
     if (entry.alternates) {
@@ -466,7 +426,7 @@ class SitemapStream {
       item += `${subIndent}<xhtml:link rel="canonical" href="${this.escape(canonicalUrl)}"/>${nl}`;
     }
     if (entry.redirect && !entry.redirect.canonical) {
-      item += `${subIndent}<!-- Redirect: ${entry.redirect.from} → ${entry.redirect.to} (${entry.redirect.type}) -->${nl}`;
+      item += `${subIndent}<!-- Redirect: ${entry.redirect.from} \u2192 ${entry.redirect.to} (${entry.redirect.type}) -->${nl}`;
     }
     if (entry.images) {
       for (const img of entry.images) {
@@ -562,15 +522,15 @@ class SitemapStream {
   escape(str) {
     return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
   }
-}
+};
 
 // src/core/SitemapGenerator.ts
-class SitemapGenerator {
+var SitemapGenerator = class {
   options;
   shadowProcessor = null;
   constructor(options) {
     this.options = {
-      maxEntriesPerFile: 50000,
+      maxEntriesPerFile: 5e4,
       filename: "sitemap.xml",
       ...options
     };
@@ -608,7 +568,7 @@ class SitemapGenerator {
       const url = this.options.storage.getUrl(filename);
       index.add({
         url,
-        lastmod: new Date
+        lastmod: /* @__PURE__ */ new Date()
       });
       shardIndex++;
       currentCount = 0;
@@ -649,13 +609,16 @@ class SitemapGenerator {
       await this.options.storage.write(this.options.filename, indexXml);
     }
   }
+  /**
+   * 獲取影子處理器（如果啟用）
+   */
   getShadowProcessor() {
     return this.shadowProcessor;
   }
-}
+};
 
 // src/core/IncrementalGenerator.ts
-class IncrementalGenerator {
+var IncrementalGenerator = class {
   options;
   changeTracker;
   diffCalculator;
@@ -663,9 +626,12 @@ class IncrementalGenerator {
   constructor(options) {
     this.options = options;
     this.changeTracker = options.changeTracker;
-    this.diffCalculator = options.diffCalculator || new DiffCalculator;
+    this.diffCalculator = options.diffCalculator || new DiffCalculator();
     this.generator = new SitemapGenerator(options);
   }
+  /**
+   * 生成完整的 sitemap（首次生成）
+   */
   async generateFull() {
     await this.generator.run();
     if (this.options.autoTrack) {
@@ -678,12 +644,15 @@ class IncrementalGenerator {
             type: "add",
             url: entry.url,
             entry,
-            timestamp: new Date
+            timestamp: /* @__PURE__ */ new Date()
           });
         }
       }
     }
   }
+  /**
+   * 增量生成（只更新變更的部分）
+   */
   async generateIncremental(since) {
     const changes = await this.changeTracker.getChanges(since);
     if (changes.length === 0) {
@@ -693,12 +662,21 @@ class IncrementalGenerator {
     const diff = this.diffCalculator.calculateFromChanges(baseEntries, changes);
     await this.generateDiff(diff);
   }
+  /**
+   * 手動追蹤變更
+   */
   async trackChange(change) {
     await this.changeTracker.track(change);
   }
+  /**
+   * 獲取變更記錄
+   */
   async getChanges(since) {
     return this.changeTracker.getChanges(since);
   }
+  /**
+   * 載入基礎 entries（從現有 sitemap）
+   */
   async loadBaseEntries() {
     const entries = [];
     const { providers } = this.options;
@@ -709,9 +687,15 @@ class IncrementalGenerator {
     }
     return entries;
   }
+  /**
+   * 生成差異部分
+   */
   async generateDiff(_diff) {
     await this.generator.run();
   }
+  /**
+   * 將 AsyncIterable 轉換為陣列
+   */
   async toArray(iterable) {
     const array = [];
     for await (const item of iterable) {
@@ -719,17 +703,21 @@ class IncrementalGenerator {
     }
     return array;
   }
-}
+};
+
 // src/core/ProgressTracker.ts
-class ProgressTracker {
+var ProgressTracker = class {
   storage;
   updateInterval;
   currentProgress = null;
   updateTimer = null;
   constructor(options) {
     this.storage = options.storage;
-    this.updateInterval = options.updateInterval || 1000;
+    this.updateInterval = options.updateInterval || 1e3;
   }
+  /**
+   * 初始化進度追蹤
+   */
   async init(jobId, total) {
     this.currentProgress = {
       jobId,
@@ -737,10 +725,13 @@ class ProgressTracker {
       total,
       processed: 0,
       percentage: 0,
-      startTime: new Date
+      startTime: /* @__PURE__ */ new Date()
     };
     await this.storage.set(jobId, this.currentProgress);
   }
+  /**
+   * 更新進度
+   */
   async update(processed, status) {
     if (!this.currentProgress) {
       return;
@@ -760,26 +751,35 @@ class ProgressTracker {
       }, this.updateInterval);
     }
   }
+  /**
+   * 完成進度追蹤
+   */
   async complete() {
     if (!this.currentProgress) {
       return;
     }
     this.currentProgress.status = "completed";
-    this.currentProgress.endTime = new Date;
+    this.currentProgress.endTime = /* @__PURE__ */ new Date();
     this.currentProgress.percentage = 100;
     await this.flush();
     this.stop();
   }
+  /**
+   * 標記為失敗
+   */
   async fail(error) {
     if (!this.currentProgress) {
       return;
     }
     this.currentProgress.status = "failed";
-    this.currentProgress.endTime = new Date;
+    this.currentProgress.endTime = /* @__PURE__ */ new Date();
     this.currentProgress.error = error;
     await this.flush();
     this.stop();
   }
+  /**
+   * 刷新進度到儲存
+   */
   async flush() {
     if (!this.currentProgress) {
       return;
@@ -792,16 +792,23 @@ class ProgressTracker {
       error: this.currentProgress.error
     });
   }
+  /**
+   * 停止更新計時器
+   */
   stop() {
     if (this.updateTimer) {
       clearInterval(this.updateTimer);
       this.updateTimer = null;
     }
   }
+  /**
+   * 獲取當前進度
+   */
   getCurrentProgress() {
     return this.currentProgress ? { ...this.currentProgress } : null;
   }
-}
+};
+
 // src/helpers/I18nSitemap.ts
 function generateI18nEntries(path, locales, baseUrl = "", options = {}) {
   const cleanPath = path.startsWith("/") ? path : `/${path}`;
@@ -820,9 +827,10 @@ function generateI18nEntries(path, locales, baseUrl = "", options = {}) {
     };
   });
 }
+
 // src/jobs/GenerateSitemapJob.ts
 import { Job } from "@gravito/stream";
-class GenerateSitemapJob extends Job {
+var GenerateSitemapJob = class extends Job {
   options;
   generator;
   totalEntries = 0;
@@ -861,6 +869,9 @@ class GenerateSitemapJob extends Job {
       throw err;
     }
   }
+  /**
+   * 計算總 URL 數
+   */
   async calculateTotal() {
     let total = 0;
     const { providers } = this.options.generatorOptions;
@@ -876,11 +887,14 @@ class GenerateSitemapJob extends Job {
     }
     return total;
   }
+  /**
+   * 帶進度追蹤的生成
+   */
   async generateWithProgress() {
     const { progressTracker, shadowProcessor, onProgress } = this.options;
     const {
       providers,
-      maxEntriesPerFile = 50000,
+      maxEntriesPerFile = 5e4,
       storage,
       baseUrl,
       pretty,
@@ -899,20 +913,24 @@ class GenerateSitemapJob extends Job {
       });
     }
   }
-}
+};
+
 // src/OrbitSitemap.ts
-import { randomUUID } from "node:crypto";
+import { randomUUID } from "crypto";
 
 // src/redirect/RedirectHandler.ts
-class RedirectHandler {
+var RedirectHandler = class {
   options;
   constructor(options) {
     this.options = options;
   }
+  /**
+   * 處理 entries 中的轉址
+   */
   async processEntries(entries) {
     const { manager, strategy, followChains, maxChainLength } = this.options;
     const _processedEntries = [];
-    const redirectMap = new Map;
+    const redirectMap = /* @__PURE__ */ new Map();
     for (const entry of entries) {
       const redirectTarget = await manager.resolve(entry.url, followChains, maxChainLength);
       if (redirectTarget && entry.url !== redirectTarget) {
@@ -920,6 +938,7 @@ class RedirectHandler {
           from: entry.url,
           to: redirectTarget,
           type: 301
+          // Default to 301 for resolved chains
         });
       }
     }
@@ -936,9 +955,12 @@ class RedirectHandler {
         return entries;
     }
   }
+  /**
+   * 策略一：移除舊 URL，加入新 URL
+   */
   handleRemoveOldAddNew(entries, redirectMap) {
     const processed = [];
-    const redirectedUrls = new Set;
+    const redirectedUrls = /* @__PURE__ */ new Set();
     for (const entry of entries) {
       const redirect = redirectMap.get(entry.url);
       if (redirect) {
@@ -958,6 +980,9 @@ class RedirectHandler {
     }
     return processed;
   }
+  /**
+   * 策略二：保留關聯，使用 canonical link
+   */
   handleKeepRelation(entries, redirectMap) {
     const processed = [];
     for (const entry of entries) {
@@ -978,6 +1003,9 @@ class RedirectHandler {
     }
     return processed;
   }
+  /**
+   * 策略三：僅更新 URL
+   */
   handleUpdateUrl(entries, redirectMap) {
     return entries.map((entry) => {
       const redirect = redirectMap.get(entry.url);
@@ -995,9 +1023,12 @@ class RedirectHandler {
       return entry;
     });
   }
+  /**
+   * 策略四：雙重標記
+   */
   handleDualMark(entries, redirectMap) {
     const processed = [];
-    const addedUrls = new Set;
+    const addedUrls = /* @__PURE__ */ new Set();
     for (const entry of entries) {
       const redirect = redirectMap.get(entry.url);
       if (redirect) {
@@ -1027,15 +1058,14 @@ class RedirectHandler {
     }
     return processed;
   }
-}
+};
 
 // src/storage/MemorySitemapStorage.ts
-class MemorySitemapStorage {
-  baseUrl;
-  files = new Map;
+var MemorySitemapStorage = class {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
   }
+  files = /* @__PURE__ */ new Map();
   async write(filename, content) {
     this.files.set(filename, content);
   }
@@ -1050,28 +1080,60 @@ class MemorySitemapStorage {
     const file = filename.startsWith("/") ? filename.slice(1) : filename;
     return `${base}/${file}`;
   }
-}
+};
 
 // src/OrbitSitemap.ts
-class OrbitSitemap {
+function sanitizeFilename(value) {
+  if (!value) {
+    return null;
+  }
+  if (value.includes("\0")) {
+    return null;
+  }
+  if (value.includes("/") || value.includes("\\")) {
+    return null;
+  }
+  if (value.includes("..")) {
+    return null;
+  }
+  return value;
+}
+var OrbitSitemap = class _OrbitSitemap {
   options;
   mode;
   constructor(mode, options) {
     this.mode = mode;
     this.options = options;
   }
+  /**
+   * Create a dynamic sitemap configuration.
+   *
+   * @param options - The dynamic sitemap options.
+   * @returns An OrbitSitemap instance configured for dynamic generation.
+   */
   static dynamic(options) {
-    return new OrbitSitemap("dynamic", {
+    return new _OrbitSitemap("dynamic", {
       path: "/sitemap.xml",
       ...options
     });
   }
+  /**
+   * Create a static sitemap configuration.
+   *
+   * @param options - The static sitemap options.
+   * @returns An OrbitSitemap instance configured for static generation.
+   */
   static static(options) {
-    return new OrbitSitemap("static", {
+    return new _OrbitSitemap("static", {
       filename: "sitemap.xml",
       ...options
     });
   }
+  /**
+   * Install the sitemap module into PlanetCore.
+   *
+   * @param core - The PlanetCore instance.
+   */
   install(core) {
     if (this.mode === "dynamic") {
       this.installDynamic(core);
@@ -1083,10 +1145,14 @@ class OrbitSitemap {
     const opts = this.options;
     const storage = opts.storage ?? new MemorySitemapStorage(opts.baseUrl);
     const indexFilename = opts.path?.split("/").pop() ?? "sitemap.xml";
-    const baseDir = opts.path ? opts.path.substring(0, opts.path.lastIndexOf("/")) : undefined;
+    const baseDir = opts.path ? opts.path.substring(0, opts.path.lastIndexOf("/")) : void 0;
     const handler = async (ctx) => {
       const reqPath = ctx.req.path;
-      const filename = reqPath.split("/").pop() || indexFilename;
+      const rawName = reqPath.split("/").pop() || indexFilename;
+      const filename = sanitizeFilename(rawName);
+      if (!filename) {
+        return ctx.text("Not Found", 404);
+      }
       const isIndex = filename === indexFilename;
       let content = await storage.read(filename);
       if (!content && isIndex) {
@@ -1131,6 +1197,12 @@ class OrbitSitemap {
     const shardRoute = `${baseDir}/${basename}-:shard.xml`;
     core.router.get(shardRoute, handler);
   }
+  /**
+   * Generate the sitemap (static mode only).
+   *
+   * @returns A promise that resolves when generation is complete.
+   * @throws {Error} If called in dynamic mode.
+   */
   async generate() {
     if (this.mode !== "static") {
       throw new Error("generate() can only be called in static mode");
@@ -1138,7 +1210,7 @@ class OrbitSitemap {
     const opts = this.options;
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await Promise.resolve().then(() => (init_DiskSitemapStorage(), exports_DiskSitemapStorage));
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-7ZZMGC4K.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     let providers = opts.providers;
@@ -1167,6 +1239,13 @@ class OrbitSitemap {
     await generator.run();
     console.log(`[OrbitSitemap] Generated sitemap in ${opts.outDir}`);
   }
+  /**
+   * Generate incremental sitemap updates (static mode only).
+   *
+   * @param since - Only include items modified since this date.
+   * @returns A promise that resolves when incremental generation is complete.
+   * @throws {Error} If called in dynamic mode, or if incremental generation is not enabled/configured.
+   */
   async generateIncremental(since) {
     if (this.mode !== "static") {
       throw new Error("generateIncremental() can only be called in static mode");
@@ -1177,7 +1256,7 @@ class OrbitSitemap {
     }
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await Promise.resolve().then(() => (init_DiskSitemapStorage(), exports_DiskSitemapStorage));
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-7ZZMGC4K.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     const incrementalGenerator = new IncrementalGenerator({
@@ -1191,6 +1270,13 @@ class OrbitSitemap {
     await incrementalGenerator.generateIncremental(since);
     console.log(`[OrbitSitemap] Generated incremental sitemap in ${opts.outDir}`);
   }
+  /**
+   * Generate sitemap asynchronously in the background (static mode only).
+   *
+   * @param options - Options for the async generation job.
+   * @returns A promise resolving to the job ID.
+   * @throws {Error} If called in dynamic mode.
+   */
   async generateAsync(options) {
     if (this.mode !== "static") {
       throw new Error("generateAsync() can only be called in static mode");
@@ -1199,7 +1285,7 @@ class OrbitSitemap {
     const jobId = randomUUID();
     let storage = opts.storage;
     if (!storage) {
-      const { DiskSitemapStorage: DiskSitemapStorage2 } = await Promise.resolve().then(() => (init_DiskSitemapStorage(), exports_DiskSitemapStorage));
+      const { DiskSitemapStorage: DiskSitemapStorage2 } = await import("./DiskSitemapStorage-7ZZMGC4K.js");
       storage = new DiskSitemapStorage2(opts.outDir, opts.baseUrl);
     }
     let providers = opts.providers;
@@ -1245,6 +1331,12 @@ class OrbitSitemap {
     });
     return jobId;
   }
+  /**
+   * Install API endpoints for triggering and monitoring sitemap generation.
+   *
+   * @param core - The PlanetCore instance.
+   * @param basePath - The base path for the API endpoints (default: '/admin/sitemap').
+   */
   installApiEndpoints(core, basePath = "/admin/sitemap") {
     const opts = this.options;
     core.router.post(`${basePath}/generate`, async (ctx) => {
@@ -1252,7 +1344,7 @@ class OrbitSitemap {
         const body = await ctx.req.json().catch(() => ({}));
         const jobId = await this.generateAsync({
           incremental: body.incremental,
-          since: body.since ? new Date(body.since) : undefined
+          since: body.since ? new Date(body.since) : void 0
         });
         return ctx.json({ jobId, status: "started" });
       } catch (error) {
@@ -1282,6 +1374,9 @@ class OrbitSitemap {
       return ctx.json(history);
     });
   }
+  /**
+   * Convert an AsyncIterable to an array.
+   */
   async toArray(iterable) {
     const array = [];
     for await (const item of iterable) {
@@ -1289,16 +1384,17 @@ class OrbitSitemap {
     }
     return array;
   }
-}
+};
+
 // src/providers/RouteScanner.ts
 function matchGlob(str, pattern) {
   const regexPattern = pattern.replace(/\./g, "\\.").replace(/\*/g, ".*").replace(/\?/g, ".");
   const regex = new RegExp(`^${regexPattern}$`);
   return regex.test(str);
 }
-
-class RouteScanner {
+var RouteScanner = class {
   router;
+  // Using any to key access internal routes
   options;
   constructor(router, options = {}) {
     this.router = router;
@@ -1335,10 +1431,10 @@ class RouteScanner {
     }
     return routes;
   }
-  shouldInclude(path2) {
+  shouldInclude(path) {
     if (this.options.exclude) {
       for (const pattern of this.options.exclude) {
-        if (matchGlob(path2, pattern)) {
+        if (matchGlob(path, pattern)) {
           return false;
         }
       }
@@ -1346,7 +1442,7 @@ class RouteScanner {
     if (this.options.include) {
       let matched = false;
       for (const pattern of this.options.include) {
-        if (matchGlob(path2, pattern)) {
+        if (matchGlob(path, pattern)) {
           matched = true;
           break;
         }
@@ -1355,17 +1451,21 @@ class RouteScanner {
     }
     return true;
   }
-}
+};
 function routeScanner(router, options) {
   return new RouteScanner(router, options);
 }
+
 // src/redirect/RedirectDetector.ts
-class RedirectDetector {
+var RedirectDetector = class {
   options;
-  cache = new Map;
+  cache = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = options;
   }
+  /**
+   * 偵測單一 URL 的轉址
+   */
   async detect(url) {
     if (this.options.autoDetect?.cache) {
       const cached = this.cache.get(url);
@@ -1395,21 +1495,29 @@ class RedirectDetector {
     }
     return null;
   }
+  /**
+   * 批次偵測轉址
+   */
   async detectBatch(urls) {
-    const results = new Map;
+    const results = /* @__PURE__ */ new Map();
     const maxConcurrent = this.options.autoDetect?.maxConcurrent || 10;
     const batches = [];
-    for (let i = 0;i < urls.length; i += maxConcurrent) {
+    for (let i = 0; i < urls.length; i += maxConcurrent) {
       batches.push(urls.slice(i, i + maxConcurrent));
     }
     for (const batch of batches) {
-      const promises = batch.map((url) => this.detect(url).then((rule) => {
-        results.set(url, rule);
-      }));
+      const promises = batch.map(
+        (url) => this.detect(url).then((rule) => {
+          results.set(url, rule);
+        })
+      );
       await Promise.all(promises);
     }
     return results;
   }
+  /**
+   * 從資料庫偵測
+   */
   async detectFromDatabase(url) {
     const { database } = this.options;
     if (!database?.enabled) {
@@ -1432,14 +1540,17 @@ class RedirectDetector {
       return null;
     }
   }
+  /**
+   * 從設定檔偵測
+   */
   async detectFromConfig(url) {
     const { config } = this.options;
     if (!config?.enabled) {
       return null;
     }
     try {
-      const fs2 = await import("node:fs/promises");
-      const data = await fs2.readFile(config.path, "utf-8");
+      const fs = await import("fs/promises");
+      const data = await fs.readFile(config.path, "utf-8");
       const redirects = JSON.parse(data);
       const rule = redirects.find((r) => r.from === url);
       return rule || null;
@@ -1447,6 +1558,9 @@ class RedirectDetector {
       return null;
     }
   }
+  /**
+   * 自動偵測（透過 HTTP 請求）
+   */
   async detectAuto(url) {
     const { autoDetect, baseUrl } = this.options;
     if (!autoDetect?.enabled) {
@@ -1454,14 +1568,15 @@ class RedirectDetector {
     }
     try {
       const fullUrl = url.startsWith("http") ? url : `${baseUrl}${url}`;
-      const timeout = autoDetect.timeout || 5000;
-      const controller = new AbortController;
+      const timeout = autoDetect.timeout || 5e3;
+      const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeout);
       try {
         const response = await fetch(fullUrl, {
           method: "HEAD",
           signal: controller.signal,
           redirect: "manual"
+          // 手動處理轉址
         });
         clearTimeout(timeoutId);
         if (response.status === 301 || response.status === 302) {
@@ -1480,23 +1595,28 @@ class RedirectDetector {
           throw error;
         }
       }
-    } catch {}
+    } catch {
+    }
     return null;
   }
+  /**
+   * 快取結果
+   */
   cacheResult(url, rule) {
     if (!this.options.autoDetect?.cache) {
       return;
     }
-    const ttl = (this.options.autoDetect.cacheTtl || 3600) * 1000;
+    const ttl = (this.options.autoDetect.cacheTtl || 3600) * 1e3;
     this.cache.set(url, {
       rule,
       expires: Date.now() + ttl
     });
   }
-}
+};
+
 // src/redirect/RedirectManager.ts
-class MemoryRedirectManager {
-  rules = new Map;
+var MemoryRedirectManager = class {
+  rules = /* @__PURE__ */ new Map();
   maxRules;
   constructor(options = {}) {
     this.maxRules = options.maxRules || 1e5;
@@ -1537,9 +1657,8 @@ class MemoryRedirectManager {
     }
     return current;
   }
-}
-
-class RedisRedirectManager {
+};
+var RedisRedirectManager = class {
   client;
   keyPrefix;
   ttl;
@@ -1618,19 +1737,17 @@ class RedisRedirectManager {
     }
     return current;
   }
-}
-
-// src/index.ts
-init_DiskSitemapStorage();
+};
 
 // src/storage/GCPSitemapStorage.ts
-class GCPSitemapStorage {
+var GCPSitemapStorage = class {
   bucket;
   prefix;
   baseUrl;
   shadowEnabled;
   shadowMode;
   storageClient;
+  // 動態載入 @google-cloud/storage
   bucketInstance;
   constructor(options) {
     this.bucket = options.bucket;
@@ -1646,12 +1763,15 @@ class GCPSitemapStorage {
     try {
       const { Storage } = await import("@google-cloud/storage");
       const clientOptions = {};
-      if (this.constructor.name === "GCPSitemapStorage") {}
+      if (this.constructor.name === "GCPSitemapStorage") {
+      }
       this.storageClient = new Storage(clientOptions);
       this.bucketInstance = this.storageClient.bucket(this.bucket);
       return { client: this.storageClient, bucket: this.bucketInstance };
     } catch (error) {
-      throw new Error(`Failed to load Google Cloud Storage. Please install @google-cloud/storage: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `Failed to load Google Cloud Storage. Please install @google-cloud/storage: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   getKey(filename) {
@@ -1703,6 +1823,7 @@ class GCPSitemapStorage {
     const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
     return `${base}/${key}`;
   }
+  // 影子處理方法
   async writeShadow(filename, content, shadowId) {
     if (!this.shadowEnabled) {
       return this.write(filename, content);
@@ -1779,10 +1900,11 @@ class GCPSitemapStorage {
     }
     await versionedFile.copy(bucket.file(key));
   }
-}
+};
+
 // src/storage/MemoryProgressStorage.ts
-class MemoryProgressStorage {
-  storage = new Map;
+var MemoryProgressStorage = class {
+  storage = /* @__PURE__ */ new Map();
   async get(jobId) {
     const progress = this.storage.get(jobId);
     return progress ? { ...progress } : null;
@@ -1808,9 +1930,10 @@ class MemoryProgressStorage {
     });
     return limit ? sorted.slice(0, limit) : sorted;
   }
-}
+};
+
 // src/storage/RedisProgressStorage.ts
-class RedisProgressStorage {
+var RedisProgressStorage = class {
   client;
   keyPrefix;
   ttl;
@@ -1880,9 +2003,10 @@ class RedisProgressStorage {
       return [];
     }
   }
-}
+};
+
 // src/storage/S3SitemapStorage.ts
-class S3SitemapStorage {
+var S3SitemapStorage = class {
   bucket;
   region;
   prefix;
@@ -1890,6 +2014,7 @@ class S3SitemapStorage {
   shadowEnabled;
   shadowMode;
   s3Client;
+  // 動態載入 @aws-sdk/client-s3
   constructor(options) {
     this.bucket = options.bucket;
     this.region = options.region || "us-east-1";
@@ -1915,7 +2040,8 @@ class S3SitemapStorage {
       const clientOptions = {
         region: this.region
       };
-      if (this.constructor.name === "S3SitemapStorage") {}
+      if (this.constructor.name === "S3SitemapStorage") {
+      }
       this.s3Client = {
         S3Client,
         PutObjectCommand,
@@ -1928,7 +2054,9 @@ class S3SitemapStorage {
       };
       return this.s3Client;
     } catch (error) {
-      throw new Error(`Failed to load AWS SDK. Please install @aws-sdk/client-s3: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `Failed to load AWS SDK. Please install @aws-sdk/client-s3: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   getKey(filename) {
@@ -1938,21 +2066,25 @@ class S3SitemapStorage {
   async write(filename, content) {
     const s3 = await this.getS3Client();
     const key = this.getKey(filename);
-    await s3.client.send(new s3.PutObjectCommand({
-      Bucket: this.bucket,
-      Key: key,
-      Body: content,
-      ContentType: "application/xml"
-    }));
+    await s3.client.send(
+      new s3.PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: content,
+        ContentType: "application/xml"
+      })
+    );
   }
   async read(filename) {
     try {
       const s3 = await this.getS3Client();
       const key = this.getKey(filename);
-      const response = await s3.client.send(new s3.GetObjectCommand({
-        Bucket: this.bucket,
-        Key: key
-      }));
+      const response = await s3.client.send(
+        new s3.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
       if (!response.Body) {
         return null;
       }
@@ -1973,10 +2105,12 @@ class S3SitemapStorage {
     try {
       const s3 = await this.getS3Client();
       const key = this.getKey(filename);
-      await s3.client.send(new s3.HeadObjectCommand({
-        Bucket: this.bucket,
-        Key: key
-      }));
+      await s3.client.send(
+        new s3.HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
       return true;
     } catch (error) {
       if (error.name === "NotFound" || error.$metadata?.httpStatusCode === 404) {
@@ -1990,6 +2124,7 @@ class S3SitemapStorage {
     const base = this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl;
     return `${base}/${key}`;
   }
+  // 影子處理方法
   async writeShadow(filename, content, shadowId) {
     if (!this.shadowEnabled) {
       return this.write(filename, content);
@@ -1997,12 +2132,14 @@ class S3SitemapStorage {
     const s3 = await this.getS3Client();
     const id = shadowId || `shadow-${Date.now()}-${Math.random().toString(36).substring(7)}`;
     const shadowKey = this.getKey(`${filename}.shadow.${id}`);
-    await s3.client.send(new s3.PutObjectCommand({
-      Bucket: this.bucket,
-      Key: shadowKey,
-      Body: content,
-      ContentType: "application/xml"
-    }));
+    await s3.client.send(
+      new s3.PutObjectCommand({
+        Bucket: this.bucket,
+        Key: shadowKey,
+        Body: content,
+        ContentType: "application/xml"
+      })
+    );
   }
   async commitShadow(shadowId) {
     if (!this.shadowEnabled) {
@@ -2010,14 +2147,18 @@ class S3SitemapStorage {
     }
     const s3 = await this.getS3Client();
     const prefix = this.prefix ? `${this.prefix}/` : "";
-    const listResponse = await s3.client.send(new s3.ListObjectsV2Command({
-      Bucket: this.bucket,
-      Prefix: prefix
-    }));
+    const listResponse = await s3.client.send(
+      new s3.ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: prefix
+      })
+    );
     if (!listResponse.Contents) {
       return;
     }
-    const shadowFiles = listResponse.Contents.filter((obj) => obj.Key?.includes(`.shadow.${shadowId}`));
+    const shadowFiles = listResponse.Contents.filter(
+      (obj) => obj.Key?.includes(`.shadow.${shadowId}`)
+    );
     for (const shadowFile of shadowFiles) {
       if (!shadowFile.Key) {
         continue;
@@ -2025,35 +2166,45 @@ class S3SitemapStorage {
       const originalKey = shadowFile.Key.replace(/\.shadow\.[^/]+$/, "");
       const _originalFilename = originalKey.replace(prefix, "");
       if (this.shadowMode === "atomic") {
-        await s3.client.send(new s3.CopyObjectCommand({
-          Bucket: this.bucket,
-          CopySource: `${this.bucket}/${shadowFile.Key}`,
-          Key: originalKey,
-          ContentType: "application/xml"
-        }));
-        await s3.client.send(new s3.DeleteObjectCommand({
-          Bucket: this.bucket,
-          Key: shadowFile.Key
-        }));
+        await s3.client.send(
+          new s3.CopyObjectCommand({
+            Bucket: this.bucket,
+            CopySource: `${this.bucket}/${shadowFile.Key}`,
+            Key: originalKey,
+            ContentType: "application/xml"
+          })
+        );
+        await s3.client.send(
+          new s3.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: shadowFile.Key
+          })
+        );
       } else {
         const version = shadowId;
         const versionedKey = `${originalKey}.v${version}`;
-        await s3.client.send(new s3.CopyObjectCommand({
-          Bucket: this.bucket,
-          CopySource: `${this.bucket}/${shadowFile.Key}`,
-          Key: versionedKey,
-          ContentType: "application/xml"
-        }));
-        await s3.client.send(new s3.CopyObjectCommand({
-          Bucket: this.bucket,
-          CopySource: `${this.bucket}/${shadowFile.Key}`,
-          Key: originalKey,
-          ContentType: "application/xml"
-        }));
-        await s3.client.send(new s3.DeleteObjectCommand({
-          Bucket: this.bucket,
-          Key: shadowFile.Key
-        }));
+        await s3.client.send(
+          new s3.CopyObjectCommand({
+            Bucket: this.bucket,
+            CopySource: `${this.bucket}/${shadowFile.Key}`,
+            Key: versionedKey,
+            ContentType: "application/xml"
+          })
+        );
+        await s3.client.send(
+          new s3.CopyObjectCommand({
+            Bucket: this.bucket,
+            CopySource: `${this.bucket}/${shadowFile.Key}`,
+            Key: originalKey,
+            ContentType: "application/xml"
+          })
+        );
+        await s3.client.send(
+          new s3.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: shadowFile.Key
+          })
+        );
       }
     }
   }
@@ -2065,10 +2216,12 @@ class S3SitemapStorage {
       const s3 = await this.getS3Client();
       const key = this.getKey(filename);
       const prefix = key.replace(/\.xml$/, "");
-      const listResponse = await s3.client.send(new s3.ListObjectsV2Command({
-        Bucket: this.bucket,
-        Prefix: prefix
-      }));
+      const listResponse = await s3.client.send(
+        new s3.ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix
+        })
+      );
       if (!listResponse.Contents) {
         return [];
       }
@@ -2098,37 +2251,39 @@ class S3SitemapStorage {
     if (!exists) {
       throw new Error(`Version ${version} not found for ${filename}`);
     }
-    await s3.client.send(new s3.CopyObjectCommand({
-      Bucket: this.bucket,
-      CopySource: `${this.bucket}/${versionedKey}`,
-      Key: key,
-      ContentType: "application/xml"
-    }));
+    await s3.client.send(
+      new s3.CopyObjectCommand({
+        Bucket: this.bucket,
+        CopySource: `${this.bucket}/${versionedKey}`,
+        Key: key,
+        ContentType: "application/xml"
+      })
+    );
   }
-}
+};
 export {
-  routeScanner,
-  generateI18nEntries,
-  SitemapStream,
-  SitemapIndex,
-  SitemapGenerator,
-  ShadowProcessor,
-  S3SitemapStorage,
-  RouteScanner,
-  RedisRedirectManager,
-  RedisProgressStorage,
-  RedisChangeTracker,
-  RedirectHandler,
-  RedirectDetector,
-  ProgressTracker,
-  OrbitSitemap,
-  MemorySitemapStorage,
-  MemoryRedirectManager,
-  MemoryProgressStorage,
-  MemoryChangeTracker,
-  IncrementalGenerator,
-  GenerateSitemapJob,
-  GCPSitemapStorage,
+  DiffCalculator,
   DiskSitemapStorage,
-  DiffCalculator
+  GCPSitemapStorage,
+  GenerateSitemapJob,
+  IncrementalGenerator,
+  MemoryChangeTracker,
+  MemoryProgressStorage,
+  MemoryRedirectManager,
+  MemorySitemapStorage,
+  OrbitSitemap,
+  ProgressTracker,
+  RedirectDetector,
+  RedirectHandler,
+  RedisChangeTracker,
+  RedisProgressStorage,
+  RedisRedirectManager,
+  RouteScanner,
+  S3SitemapStorage,
+  ShadowProcessor,
+  SitemapGenerator,
+  SitemapIndex,
+  SitemapStream,
+  generateI18nEntries,
+  routeScanner
 };