@hyacine/astro 0.0.1

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@hyacine/astro",
+  "version": "0.0.1",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./src/virtual-modules.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "bunx --bun oxlint --type-aware --type-check . --fix",
+    "format": "bunx oxfmt ."
+  },
+  "dependencies": {
+    "@hyacine/core": "workspace:*",
+    "@hyacine/helper": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "astro": "^5.16.11"
+  }
+}

package/src/hyacine-plugin.ts

@@ -0,0 +1,278 @@
+import type { AstroIntegration } from "astro";
+import { existsSync } from "node:fs";
+import type { Plugin as VitePlugin } from "vite";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { HyacinePluginSystemConfig } from "@hyacine/core";
+import type { PluginManifest } from "@hyacine/core";
+import {
+  CONFIG_FILE_NAMES,
+  collectRuntimeOnlyEntries,
+  findConfigFilePath,
+  generateTempAstroTemplateFile,
+  generateTempRuntimeFile,
+  getPluginManifests,
+  groupEntriesByInjectPoint,
+} from "@hyacine/helper";
+import type { ViteDevServer } from "vite";
+
+// 虚拟模块 ID 常量
+const RUNTIME_VIRTUAL_ID = "virtual:hyacine/runtime";
+const RUNTIME_RESOLVED_ID = "\0virtual:hyacine/runtime";
+
+// Astro 组件虚拟模块 ID 前缀
+const ASTRO_VIRTUAL_ID_PREFIX = "virtual:hyacine/inject/";
+const ASTRO_RESOLVED_ID_PREFIX = "\0virtual:hyacine/inject/";
+
+function toViteFsPath(filePath: string): string {
+  // Vite 的 /@fs/ 需要 POSIX 风格路径分隔符
+  return `/@fs/${filePath.replaceAll("\\", "/")}`;
+}
+
+/**
+ * 读取插件配置文件
+ * 支持 hyacine.plugin.ts 和 hyacine.plugin.mjs
+ * @param root 项目根目录 URL
+ * @param bypassCache 是否绕过模块缓存（开发模式 HMR 时使用）
+ */
+async function loadPluginConfig(
+  root: URL,
+  bypassCache = false,
+  viteServer?: Pick<ViteDevServer, "ssrLoadModule">,
+): Promise<HyacinePluginSystemConfig | null> {
+  const rootPath = fileURLToPath(root);
+  const configPath = findConfigFilePath(rootPath);
+
+  if (!configPath) {
+    console.warn("[hyacine-plugin] 未找到插件配置文件 (hyacine.plugin.ts 或 .mjs)");
+    return null;
+  }
+
+  try {
+    // dev 模式下优先使用 Vite 的 ssrLoadModule：
+    // 1) 可直接加载/转译 .ts 配置
+    // 2) 受 Vite module graph 管理，更符合 HMR 场景
+    // 3) 搭配 query 时间戳，确保每次都是“新模块 id”
+    let configModule: unknown;
+
+    if (viteServer) {
+      let moduleId = toViteFsPath(configPath);
+      if (bypassCache) {
+        moduleId = `${moduleId}?t=${Date.now()}`;
+      }
+      configModule = await viteServer.ssrLoadModule(moduleId);
+    } else {
+      // 使用原生动态导入加载配置文件（构建模式 / 无 Vite server 时）
+      let configUrl = pathToFileURL(configPath).href;
+      if (bypassCache) {
+        configUrl = `${configUrl}?t=${Date.now()}`;
+      }
+      configModule = await import(/* @vite-ignore */ configUrl);
+    }
+
+    const moduleAsRecord = configModule as Record<string, unknown>;
+    const config = moduleAsRecord.default as HyacinePluginSystemConfig;
+
+    if (!config || !config.plugins) {
+      console.warn("[hyacine-plugin] 配置文件格式无效，缺少 plugins 字段");
+      return null;
+    }
+
+    return config;
+  } catch (error) {
+    console.error("[hyacine-plugin] 加载配置文件失败:", error);
+    return null;
+  }
+}
+
+/**
+ * 创建处理 runtime 虚拟模块的 Vite plugin
+ */
+function createHyacineVitePlugin(
+  configGetter: () => HyacinePluginSystemConfig | null,
+  manifestsGetter: () => PluginManifest[] | null,
+): VitePlugin {
+  return {
+    name: "vite-plugin-hyacine-virtual",
+    enforce: "pre", // 确保在其他 plugins 之前执行
+
+    resolveId(id: string) {
+      // Runtime 虚拟模块
+      if (id === RUNTIME_VIRTUAL_ID) {
+        return RUNTIME_RESOLVED_ID;
+      }
+
+      // Astro 组件虚拟模块
+      if (id.startsWith(ASTRO_VIRTUAL_ID_PREFIX)) {
+        const injectPoint = id.slice(ASTRO_VIRTUAL_ID_PREFIX.length);
+        // 保留 .astro 扩展名，让 Astro 编译器识别
+        return `${ASTRO_RESOLVED_ID_PREFIX}${injectPoint}.astro`;
+      }
+
+      return null;
+    },
+
+    load(id: string) {
+      const config = configGetter();
+      const manifests = manifestsGetter();
+
+      if (!config || !manifests) {
+        return null;
+      }
+
+      // 加载 runtime 虚拟模块
+      if (id === RUNTIME_RESOLVED_ID) {
+        const runtimeEntries = collectRuntimeOnlyEntries(manifests);
+        return generateTempRuntimeFile(runtimeEntries, config.injectPoints);
+      }
+
+      // 加载 .astro 虚拟模块
+      if (id.startsWith(ASTRO_RESOLVED_ID_PREFIX) && id.endsWith(".astro")) {
+        const injectPoint = id.slice(ASTRO_RESOLVED_ID_PREFIX.length).replace(".astro", "");
+
+        const groups = groupEntriesByInjectPoint(manifests);
+        const entries = groups.get(injectPoint);
+
+        if (entries) {
+          // 返回 Astro 源码，让 Astro 的 Vite plugin 继续处理
+          return generateTempAstroTemplateFile(entries);
+        }
+      }
+
+      return null;
+    },
+  };
+}
+
+/**
+ * Hyacine 插件系统 Astro 集成
+ */
+export default function hyacinePlugin(): AstroIntegration {
+  let rootUrl: URL;
+  let rootPath: string;
+  const configFiles = CONFIG_FILE_NAMES;
+
+  // 缓存配置和 manifests 供虚拟模块使用
+  let cachedConfig: HyacinePluginSystemConfig | null = null;
+  let cachedManifests: PluginManifest[] | null = null;
+
+  // 保存 change 监听器的引用，用于清理
+  let changeListener: ((filePath: string) => Promise<void>) | null = null;
+
+  return {
+    name: "hyacine-plugin",
+    hooks: {
+      "astro:config:setup": async ({ config, injectScript, updateConfig }) => {
+        rootUrl = config.root;
+        rootPath = fileURLToPath(config.root);
+
+        // 读取并缓存配置
+        const pluginConfig = await loadPluginConfig(rootUrl, false);
+        if (pluginConfig) {
+          cachedConfig = pluginConfig;
+          cachedManifests = getPluginManifests(pluginConfig);
+        }
+
+        // 注入 Vite plugin 处理虚拟模块
+        updateConfig({
+          vite: {
+            plugins: [
+              createHyacineVitePlugin(
+                () => cachedConfig,
+                () => cachedManifests,
+              ) as any, // 类型断言解决 Vite 版本不一致问题
+            ],
+          },
+        });
+
+        // 使用虚拟模块路径注入 runtime
+        injectScript("page", `import "${RUNTIME_VIRTUAL_ID}";`);
+      },
+
+      "astro:server:setup": async ({ server, logger }) => {
+        server.watcher.setMaxListeners(20); // 增加监听器上限，避免警告
+        // 如果已有旧的监听器，先移除
+        if (changeListener) {
+          server.watcher.off("change", changeListener);
+        }
+
+        // 手动将配置文件加入 Vite watcher，避免使用 addWatchFile 导致这整个 server 重启
+        for (const fileName of configFiles) {
+          const configPath = join(rootPath, fileName);
+          if (existsSync(configPath)) {
+            server.watcher.add(configPath);
+            logger.info(`[hyacine-plugin] 监听配置文件 (HMR): ${fileName}`);
+          }
+        }
+
+        // 创建新的监听器并保存引用
+        changeListener = async (filePath: string) => {
+          const isPluginConfig = configFiles.some((name) => filePath.endsWith(name));
+
+          if (isPluginConfig) {
+            logger.info("[hyacine-plugin] 检测到配置变化，重新加载插件配置...");
+
+            try {
+              // 重新加载配置（绕过缓存）
+              const config = await loadPluginConfig(rootUrl, true, server);
+              if (config) {
+                // 更新缓存
+                cachedConfig = config;
+                cachedManifests = getPluginManifests(config);
+
+                // 使所有虚拟模块失效
+                const virtualModuleIds = [
+                  RUNTIME_RESOLVED_ID,
+                  // 所有 inject point 虚拟模块
+                  ...Object.keys(config.injectPoints).map(
+                    (injectPoint) => `${ASTRO_RESOLVED_ID_PREFIX}${injectPoint}.astro`,
+                  ),
+                ];
+
+                for (const moduleId of virtualModuleIds) {
+                  const mod = server.moduleGraph.getModuleById(moduleId);
+                  if (mod) {
+                    server.moduleGraph.invalidateModule(mod);
+                  }
+                }
+
+                logger.info("[hyacine-plugin] 已使所有虚拟模块失效");
+
+                // 触发完整页面重载（HMR）
+                server.ws.send({
+                  type: "full-reload",
+                  path: "*",
+                });
+
+                logger.info("[hyacine-plugin] 配置已重新加载，页面即将刷新");
+              }
+            } catch (error) {
+              logger.error(
+                `[hyacine-plugin] 重新加载失败: ${error instanceof Error ? error.message : String(error)}`,
+              );
+            }
+          }
+        };
+
+        // 监听配置文件变化，触发重新生成
+        server.watcher.on("change", changeListener);
+      },
+
+      "astro:server:start": async ({ logger }) => {
+        if (!cachedConfig || !cachedManifests) {
+          logger.warn("[hyacine-plugin] 未找到有效的插件配置");
+          return;
+        }
+
+        logger.info(`[hyacine-plugin] 开发模式：已加载 ${cachedManifests.length} 个插件`);
+      },
+
+      "astro:build:start": async ({ logger }) => {
+        // 构建时虚拟模块会自动被 Vite 处理，无需手动生成文件
+        if (cachedConfig && cachedManifests) {
+          logger.info(`[hyacine-plugin] 构建模式：${cachedManifests.length} 个插件已加载`);
+        }
+      },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default as hyacinePlugin } from "./hyacine-plugin";

package/src/virtual-modules.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 虚拟模块类型定义
+ * 为 Hyacine 插件系统的虚拟模块提供 TypeScript 类型支持
+ */
+
+/**
+ * Runtime 虚拟模块
+ * 负责初始化全局注入点映射和执行 runtime-only 插件
+ *
+ * @remarks
+ * 该模块会自动注入到每个页面，无需手动导入
+ * 执行后会设置 globalThis.__HYACINE_INJECT_POINTS__
+ */
+declare module "virtual:hyacine/runtime" {
+  // Runtime module 是 side-effect only，无导出
+}
+/**
+ * Inject Point 虚拟模块
+ * 每个注入点对应一个虚拟 Astro 组件
+ *
+ * @remarks
+ * 使用方式：
+ * ```astro
+ * ---
+ * import Footer from "virtual:hyacine/inject/footer";
+ * ---
+ * <Footer />
+ * ```
+ *
+ * 替代原有的文件系统路径：
+ * - 旧：`import Footer from "/generated/hyacine/footer.astro"`
+ * - 新：`import Footer from "virtual:hyacine/inject/footer"`
+ */
+declare module "virtual:hyacine/inject/*" {
+  import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+  const component: AstroComponentFactory;
+  export default component;
+}