@hyacine/helper 0.0.1

package/src/generateTempFile.test.ts

@@ -0,0 +1,415 @@
+import { describe, expect, it } from "bun:test";
+import {
+  generateTempAstroTemplateFile,
+  generateTempRuntimeFile,
+  safeComponentName,
+} from "./generateTempFile";
+
+describe("safeComponentName", () => {
+  it("returns pascalCase name when it is a valid component identifier", () => {
+    expect(safeComponentName("hello-world", 0)).toBe("HelloWorld");
+    expect(safeComponentName("NavBar", 1)).toBe("NavBar");
+    expect(safeComponentName("foo_bar", 2)).toBe("FooBar");
+  });
+
+  it("falls back to HyacineComponent{index} for invalid/edge names", () => {
+    expect(safeComponentName("", 0)).toBe("HyacineComponent0");
+    expect(safeComponentName("123", 3)).toBe("HyacineComponent3");
+    expect(safeComponentName("-", 9)).toBe("HyacineComponent9");
+    // 中文/emoji 等在 pascalCase 后通常不满足 /^[A-Z][A-Za-z0-9]*$/
+    expect(safeComponentName("你好", 4)).toBe("HyacineComponent4");
+    expect(safeComponentName("😀", 5)).toBe("HyacineComponent5");
+  });
+});
+
+describe("generateTempAstroTemplateFile", () => {
+  it("generates imports and usage for custom-element entries", () => {
+    const out = generateTempAstroTemplateFile([
+      {
+        type: "custom-element",
+        injectPoint: "layout",
+        name: "code-block",
+        path: "./CodeBlock.svelte",
+      },
+    ]);
+
+    expect(out).toContain('import CodeBlock from "./CodeBlock.svelte";');
+    expect(out).toContain('<CodeBlock style="display: none;" />');
+    expect(out).toContain("//⚠️ This file is auto-generated");
+  });
+
+  it("generates ssr usage with safe client hydration attribute", () => {
+    const out = generateTempAstroTemplateFile([
+      {
+        type: "ssr",
+        platform: "astro",
+        injectPoint: "header",
+        name: "NavBar",
+        path: "./NavBar.svelte",
+        clientHydrationInstruction: "load",
+      },
+    ]);
+
+    expect(out).toContain('import NavBar from "./NavBar.svelte";');
+    expect(out).toContain("<NavBar client:load />");
+  });
+
+  it("supports multiple mixed entries (custom-element + ssr)", () => {
+    const out = generateTempAstroTemplateFile([
+      {
+        type: "custom-element",
+        injectPoint: "layout",
+        name: "code-block",
+        path: "./CodeBlock.svelte",
+      },
+      {
+        type: "ssr",
+        platform: "astro",
+        injectPoint: "header",
+        name: "NavBar",
+        path: "./NavBar.svelte",
+        clientHydrationInstruction: "idle",
+      },
+      {
+        type: "ssr",
+        platform: "astro",
+        injectPoint: "footer",
+        name: "Waves",
+        path: "./Waves.svelte",
+      },
+    ]);
+
+    // imports
+    expect(out).toContain('import CodeBlock from "./CodeBlock.svelte";');
+    expect(out).toContain('import NavBar from "./NavBar.svelte";');
+    expect(out).toContain('import Waves from "./Waves.svelte";');
+
+    // usage
+    expect(out).toContain('<CodeBlock style="display: none;" />');
+    expect(out).toContain("<NavBar client:idle />");
+    // 没有 hydration 指令时，不应有 client:* 属性
+    expect(out).toContain("<Waves />");
+    expect(out).not.toContain("<Waves client:");
+  });
+
+  it("dedupes repeated paths (defense against duplicate mount)", () => {
+    const out = generateTempAstroTemplateFile([
+      { type: "custom-element", injectPoint: "layout", name: "A", path: "./Same.svelte" },
+      // same path, different name/type should be ignored
+      {
+        type: "ssr",
+        platform: "astro",
+        injectPoint: "header",
+        name: "B",
+        path: "./Same.svelte",
+        clientHydrationInstruction: "load",
+      },
+    ]);
+
+    const importCount = (out.match(/\bimport\b/g) ?? []).length;
+    expect(importCount).toBe(1);
+    // usage 也只应出现一次
+    const sameTagCount = (out.match(/<\w+ style="display: none;" \/>/g) ?? []).length;
+    expect(sameTagCount).toBe(1);
+    // 不应出现第二个 entry 的 hydration
+    expect(out).not.toContain("client:load");
+  });
+
+  it("handles empty entries (edge case)", () => {
+    const out = generateTempAstroTemplateFile([]);
+    expect(out).toContain("---");
+    expect(out).toContain("<Fragment>");
+    // 不应包含任何 import
+    expect(out).not.toMatch(/\bimport\b/);
+  });
+
+  it("defuses malicious name injection by falling back to safeComponentName", () => {
+    const maliciousName = '"><script>alert(1)</script>';
+    const expectedComponentName = safeComponentName(maliciousName, 0);
+
+    const out = generateTempAstroTemplateFile([
+      {
+        type: "custom-element",
+        injectPoint: "layout", // 尝试把脚本注入到标签/标识符
+        name: maliciousName,
+        path: "./Evil.svelte",
+      },
+    ]);
+
+    expect(out).toContain(`import ${expectedComponentName} from "./Evil.svelte";`);
+    expect(out).toContain(`<${expectedComponentName} style="display: none;" />`);
+    expect(out).not.toContain("<script>");
+    expect(out).not.toContain("</script>");
+  });
+
+  it("defuses malicious path injection by escaping import string literal", () => {
+    const maliciousPath = "./ok';\nconsole.log('PWNED');\n//";
+    const out = generateTempAstroTemplateFile([
+      { type: "custom-element", injectPoint: "layout", name: "Safe", path: maliciousPath },
+    ]);
+
+    // JSON.stringify 会把真实换行转成 \n，避免生成文件出现新的语句行
+    expect(out).toContain(`import Safe from ${JSON.stringify(maliciousPath)};`);
+    // 不应出现真实的注入语句行（带真实换行的 console.log）
+    expect(out).not.toContain("\nconsole.log('PWNED');\n");
+  });
+
+  it("ignores malicious hydration instruction (runtime validation)", () => {
+    const out = generateTempAstroTemplateFile([
+      {
+        type: "ssr",
+        platform: "astro",
+        injectPoint: "header",
+        name: "NavBar",
+        path: "./NavBar.svelte",
+        // 绕过类型系统的注入：运行时必须忽略
+        clientHydrationInstruction: "load on:click=alert(1)" as any,
+      },
+    ]);
+
+    expect(out).toContain("<NavBar />");
+    expect(out).not.toContain("client:load on:click");
+  });
+});
+
+describe("generateTempRuntimeFile", () => {
+  const mockInjectPoints = {
+    footer: "#footer",
+    header: ".header",
+    sidebar: "[data-sidebar]",
+  };
+
+  it("generates imports and init calls for runtime-only entries", () => {
+    const out = generateTempRuntimeFile(
+      [{ type: "runtime-only", name: "mouse-firework", path: "./mouse-firework.ts" }],
+      mockInjectPoints,
+    );
+
+    // name 会变成 MouseFirework
+    expect(out).toContain('import { init as init_MouseFirework } from "./mouse-firework.ts";');
+    expect(out).toContain("init_MouseFirework({});");
+  });
+
+  it("falls back to HyacineComponent{index} for invalid runtime-only names", () => {
+    const out = generateTempRuntimeFile(
+      [{ type: "runtime-only", name: "123", path: "./runtime.ts" }],
+      mockInjectPoints,
+    );
+
+    expect(out).toContain('import { init as init_HyacineComponent0 } from "./runtime.ts";');
+    expect(out).toContain("init_HyacineComponent0({});");
+  });
+
+  it("supports multiple runtime-only entries (mixed valid + fallback)", () => {
+    const out = generateTempRuntimeFile(
+      [
+        { type: "runtime-only", name: "mouse-firework", path: "./mouse-firework.ts" },
+        { type: "runtime-only", name: "你好", path: "./cn.ts" },
+      ],
+      mockInjectPoints,
+    );
+
+    // 第 0 个：正常 pascalCase
+    expect(out).toContain('import { init as init_MouseFirework } from "./mouse-firework.ts";');
+    expect(out).toContain("init_MouseFirework({});");
+
+    // 第 1 个：fallback
+    expect(out).toContain('import { init as init_HyacineComponent1 } from "./cn.ts";');
+    expect(out).toContain("init_HyacineComponent1({});");
+  });
+
+  it("dedupes repeated paths (defense against duplicate init)", () => {
+    const out = generateTempRuntimeFile(
+      [
+        { type: "runtime-only", name: "A", path: "./same.ts" },
+        { type: "runtime-only", name: "B", path: "./same.ts" },
+      ],
+      mockInjectPoints,
+    );
+
+    // 去重后应该只有一个 init import
+    const initImportCount = (out.match(/import { init as init_/g) ?? []).length;
+    expect(initImportCount).toBe(1);
+
+    // init 调用也只应一次
+    const initCallCount = (out.match(/\binit_\w+\({.*?}\);/g) ?? []).length;
+    expect(initCallCount).toBe(1);
+  });
+
+  it("defuses malicious path injection in runtime file", () => {
+    const maliciousPath = "./ok';\nthrow new Error('PWNED');\n//";
+    const out = generateTempRuntimeFile(
+      [{ type: "runtime-only", name: "Safe", path: maliciousPath }],
+      mockInjectPoints,
+    );
+
+    expect(out).toContain(`from ${JSON.stringify(maliciousPath)};`);
+    expect(out).not.toContain("\nthrow new Error('PWNED');\n");
+  });
+
+  it("initializes global inject points map", () => {
+    const out = generateTempRuntimeFile([], mockInjectPoints);
+
+    // 验证全局变量被初始化
+    expect(out).toContain("globalThis.__HYACINE_INJECT_POINTS__ =");
+
+    // 验证 injectPoints 被正确序列化
+    expect(out).toContain('"footer": "#footer"');
+    expect(out).toContain('"header": ".header"');
+    expect(out).toContain('"sidebar": "[data-sidebar]"');
+  });
+
+  it("generates init calls with serialized options when provided", () => {
+    const out = generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "mouse-firework",
+          path: "./mouse-firework.ts",
+          options: { theme: "dark", count: 42, enabled: true },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    // 验证 init 调用包含序列化的 options
+    expect(out).toContain('import { init as init_MouseFirework } from "./mouse-firework.ts";');
+    expect(out).toContain('init_MouseFirework({"theme":"dark","count":42,"enabled":true});');
+  });
+
+  it("generates init calls with empty object when no options provided (backward compatibility)", () => {
+    const out = generateTempRuntimeFile(
+      [{ type: "runtime-only", name: "legacy-plugin", path: "./legacy.ts" }],
+      mockInjectPoints,
+    );
+
+    // 验证向后兼容：无 options 时传入空对象
+    expect(out).toContain('import { init as init_LegacyPlugin } from "./legacy.ts";');
+    expect(out).toContain("init_LegacyPlugin({});");
+  });
+
+  it("handles complex options with nested objects and arrays", () => {
+    const out = generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "complex",
+          path: "./complex.ts",
+          options: {
+            config: { nested: { deep: "value" } },
+            items: [1, 2, 3],
+            mixed: { arr: ["a", "b"], num: 123 },
+          },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    expect(out).toContain('import { init as init_Complex } from "./complex.ts";');
+    // 验证复杂对象被正确序列化（JSON.stringify 输出）
+    expect(out).toContain('"config":{"nested":{"deep":"value"}}');
+    expect(out).toContain('"items":[1,2,3]');
+    expect(out).toContain('"mixed":{"arr":["a","b"],"num":123}');
+  });
+
+  it("filters out invalid option keys for safety", () => {
+    const out = generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "safe",
+          path: "./safe.ts",
+          options: {
+            validKey: "ok",
+            "invalid-key": "bad", // 包含连字符，不符合标识符规则
+            "123": "bad", // 以数字开头
+          },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    // 只有 validKey 应该被保留
+    expect(out).toContain('"validKey":"ok"');
+    expect(out).not.toContain("invalid-key");
+    expect(out).not.toContain('"123"');
+  });
+
+  it("filters out non-serializable values (functions, undefined)", () => {
+    const out = generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "filtered",
+          path: "./filtered.ts",
+          options: {
+            goodString: "hello",
+            badFunction: (() => {}) as any, // 函数不可序列化
+            badUndefined: undefined, // undefined 会被 JSON.stringify 跳过
+            goodNull: null, // null 是可序列化的
+          },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    expect(out).toContain('"goodString":"hello"');
+    expect(out).toContain('"goodNull":null');
+    expect(out).not.toContain("badFunction");
+    expect(out).not.toContain("badUndefined");
+  });
+
+  it("defuses malicious options injection attempts", () => {
+    const maliciousValue = '"; console.log("PWNED"); //';
+    const out = generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "evil",
+          path: "./evil.ts",
+          options: { message: maliciousValue },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    // JSON.stringify 会自动转义特殊字符，防止代码注入
+    expect(out).toContain('import { init as init_Evil } from "./evil.ts";');
+    // 验证恶意字符串被安全转义
+    expect(out).toContain(JSON.stringify({ message: maliciousValue }));
+    // 不应该出现裸露的注入代码
+    expect(out).not.toContain('"; console.log("PWNED"); //');
+  });
+
+  it("warns about duplicate paths with different options", () => {
+    // 这个测试验证去重逻辑：相同路径只保留第一个 entry
+    const consoleWarnSpy = console.warn;
+    const warnings: string[] = [];
+    console.warn = (msg: string) => warnings.push(msg);
+
+    generateTempRuntimeFile(
+      [
+        {
+          type: "runtime-only",
+          name: "First",
+          path: "./same.ts",
+          options: { version: 1 },
+        },
+        {
+          type: "runtime-only",
+          name: "Second",
+          path: "./same.ts",
+          options: { version: 2 },
+        },
+      ],
+      mockInjectPoints,
+    );
+
+    console.warn = consoleWarnSpy;
+
+    // 应该有警告提示存在不同 options 的重复路径
+    expect(warnings.some((w) => w.includes("Duplicate entry path") && w.includes("same.ts"))).toBe(
+      true,
+    );
+  });
+});

package/src/generateTempFile.ts

@@ -0,0 +1,215 @@
+import { pascalCase } from "es-toolkit";
+import type { CustomElementEntry, RuntimeOnlyEntry, SSREntry } from "@hyacine/core";
+
+export function safeComponentName(name: string, index: number) {
+  const pc = pascalCase(name);
+  if (/^[A-Z][A-Za-z0-9]*$/.test(pc)) {
+    return pc;
+  }
+  console.warn(
+    `[hyacine] Warning: Unsafe component name "${name}" converted to safe default "HyacineComponent${index}".`,
+  );
+  return `HyacineComponent${index}`;
+}
+
+function safeImportPath(path: string): string {
+  // 使用 JSON 字符串字面量来避免引号/换行等导致的代码注入
+  // 例：import X from "...";
+  return JSON.stringify(path);
+}
+
+function safeHydrationInstruction(
+  hydration: SSREntry["clientHydrationInstruction"],
+): SSREntry["clientHydrationInstruction"] | undefined {
+  // manifest 来自外部数据时，类型约束并不等于运行时安全；这里做白名单校验。
+  if (
+    hydration === "load" ||
+    hydration === "idle" ||
+    hydration === "visible" ||
+    hydration === "media"
+  ) {
+    return hydration;
+  }
+  console.warn(
+    `[hyacine] Warning: Invalid client hydration instruction "${hydration}" detected. Ignoring it for safety.`,
+  );
+  return undefined;
+}
+
+/**
+ * 将 props 对象序列化为 Astro 组件属性字符串
+ * 例如: { title: "Hello", count: 42 } => ' title="Hello" count={42}'
+ */
+function serializeProps(props: Record<string, unknown>): string {
+  const entries = Object.entries(props);
+  if (entries.length === 0) return "";
+
+  return entries
+    .map(([key, value]) => {
+      // 校验 key 是否是安全的属性名
+      if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+        console.warn(`[hyacine] Warning: Invalid prop name "${key}" detected. Skipping this prop.`);
+        return "";
+      }
+
+      // 根据值的类型决定如何序列化
+      if (typeof value === "string") {
+        // 字符串值用双引号包裹，需要转义内部的引号和反斜杠
+        const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return ` ${key}="${escaped}"`;
+      } else if (typeof value === "number" || typeof value === "boolean") {
+        // 数字和布尔值使用 JSX 表达式语法
+        return ` ${key}={${value}}`;
+      } else if (value === null || value === undefined) {
+        // null 和 undefined 跳过
+        return "";
+      } else {
+        // 对象、数组等复杂类型使用 JSON 序列化后作为 JSX 表达式
+        try {
+          const serialized = JSON.stringify(value);
+          return ` ${key}={${serialized}}`;
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          console.warn(
+            `[hyacine] Warning: Failed to serialize prop "${key}": ${errorMessage}. Skipping this prop.`,
+          );
+          return "";
+        }
+      }
+    })
+    .filter((s) => s !== "")
+    .join("");
+}
+
+/**
+ * 将 options 对象序列化为 TypeScript/JavaScript 对象字面量字符串
+ * 用于 runtime-only 插件的 init 函数参数
+ * 例如: { theme: "dark", count: 42 } => '{"theme":"dark","count":42}'
+ */
+function serializeOptionsForRuntime(options: Record<string, unknown>): string {
+  const filteredOptions: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(options)) {
+    // 校验 key 是否是安全的属性名
+    if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+      console.warn(
+        `[hyacine] Warning: Invalid option key "${key}" detected. Skipping this option.`,
+      );
+      continue;
+    }
+
+    // 跳过 undefined 和函数（不可序列化）
+    if (value === undefined || typeof value === "function") {
+      console.warn(
+        `[hyacine] Warning: Option "${key}" has non-serializable value (${typeof value}). Skipping this option.`,
+      );
+      continue;
+    }
+
+    filteredOptions[key] = value;
+  }
+
+  try {
+    // 使用 JSON.stringify 序列化，这样可以安全地处理特殊字符和嵌套对象
+    return JSON.stringify(filteredOptions);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[hyacine] Warning: Failed to serialize options: ${errorMessage}. Using empty object.`,
+    );
+    return "{}";
+  }
+}
+
+export function generateTempAstroTemplateFile(entries: (SSREntry | CustomElementEntry)[]): string {
+  let importsArea = "";
+
+  let usageArea = "";
+
+  const seenPaths = new Set<string>();
+
+  entries.forEach((entry, index) => {
+    if (seenPaths.has(entry.path)) {
+      console.warn(
+        `[hyacine] Warning: Duplicate entry path "${entry.path}" detected. Skipping duplicate import.`,
+      );
+      return;
+    }
+    seenPaths.add(entry.path);
+
+    const componentName = safeComponentName(entry.name, index);
+    importsArea += `import ${componentName} from ${safeImportPath(entry.path)};\n`;
+
+    if (entry.type === "custom-element") {
+      usageArea += `<${componentName} style="display: none;" />\n`;
+    } else if (entry.type === "ssr") {
+      const hydration = safeHydrationInstruction(entry.clientHydrationInstruction);
+      const hydrationAttr = hydration ? ` client:${hydration}` : "";
+      const propsAttr = entry.props ? serializeProps(entry.props) : "";
+      usageArea += `<${componentName}${hydrationAttr}${propsAttr} />\n`;
+    }
+  });
+
+  return `
+  ---
+  //⚠️ This file is auto-generated by hyacine plugin system. Do not edit directly!
+  // @ts-nocheck
+  ${importsArea}
+  ---
+  <Fragment>
+    ${usageArea}
+  </Fragment>
+  `.trim();
+}
+
+export function generateTempRuntimeFile(
+  entries: RuntimeOnlyEntry[],
+  injectPoints: Record<string, string>,
+): string {
+  let importsArea = "";
+  let initArea = "";
+
+  const seenPaths = new Set<string>();
+
+  entries.forEach((entry, index) => {
+    if (seenPaths.has(entry.path)) {
+      if (entry.options && Object.keys(entry.options).length > 0) {
+        console.warn(
+          `[hyacine] Warning: Duplicate entry path "${entry.path}" with different options detected. Using the first entry's options.`,
+        );
+      }
+      return;
+    }
+    seenPaths.add(entry.path);
+
+    const componentName = safeComponentName(entry.name, index);
+    const initAlias = `init_${componentName}`;
+    importsArea += `import { init as ${initAlias} } from ${safeImportPath(entry.path)};\n`;
+
+    // 序列化 options，如果没有 options 则传空对象以保持向后兼容
+    const optionsArg = entry.options ? serializeOptionsForRuntime(entry.options) : "{}";
+    initArea += `${initAlias}(${optionsArg});\n`;
+  });
+
+  // 序列化 injectPoints 映射表
+  const serializedInjectPoints = JSON.stringify(injectPoints, null, 2);
+
+  return `
+//⚠️ This file is auto-generated by hyacine plugin system. Do not edit directly!
+// @ts-nocheck
+
+/**
+ * Runtime initialization
+ * 
+ * This file initializes the global inject points map and calls all runtime-only plugin init functions.
+ */
+
+${importsArea}
+
+// 初始化全局注入点映射表
+globalThis.__HYACINE_INJECT_POINTS__ = ${serializedInjectPoints};
+
+// 调用所有 runtime-only 插件的 init 函数
+${initArea}
+  `.trim();
+}