create-linkdesk-plugin 0.1.1 → 0.1.3

package/template/src/index.tsx

@@ -1,35 +1,35 @@
-/**
- * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
- *
- * 视图插件契约（E5.8，见 docs/03-插件制造/01-API契约.md）：壳以 { isActive, tabId?, sourceId? }
- * 渲染本文件 default 导出的组件：
- *   - isActive  本标签当前是否聚焦。keep-alive 下非聚焦标签仍在渲染，isActive 只用于
- *               gate「聚焦才跑」的副作用（如自动保存），切勿用它整块 blank 掉内容。
- *   - tabId     本标签页 id。
- *   - sourceId  上下文数据（文件路径 / 数据源等），编辑器类插件用它定位内容。
- *
- * 样式：LinkDesk 主题色一律走 CSS 变量 var(--xxx)（见 index.css 示例），禁硬编码 hex。
- * 文案：用 t() 读——key 就是中文原文，英文译文放 i18n/en.json（见 05-UI写法规约.md）。
- * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
- */
-
-import { useTranslation } from "react-i18next";
-import "./index.css";
-
-export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
-  const { t } = useTranslation();
-
-  return (
-    <div className="starter">
-      <h2 className="starter__title">{t("插件跑起来了 ✨")}</h2>
-      <p className="starter__text">{t("这是你的第一个 LinkDesk 插件。")}</p>
-      <p className="starter__hint">
-        <code>src/index.tsx</code> {t("是插件本体——改它，浏览器预览即时刷新。")}
-      </p>
-      <p className="starter__hint">
-        <code>npm run build</code> {t("打包出分发文件，可装进 LinkDesk 或发布到市场。")}
-      </p>
-      <p className="starter__hint">{t("目录该放哪、发布怎么做，都写在 README.md 里。")}</p>
-    </div>
-  );
-}
+/**
+ * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
+ *
+ * 视图插件契约（E5.8，见 docs/03-插件制造/01-API契约.md）：壳以 { isActive, tabId?, sourceId? }
+ * 渲染本文件 default 导出的组件：
+ *   - isActive  本标签当前是否聚焦。keep-alive 下非聚焦标签仍在渲染，isActive 只用于
+ *               gate「聚焦才跑」的副作用（如自动保存），切勿用它整块 blank 掉内容。
+ *   - tabId     本标签页 id。
+ *   - sourceId  上下文数据（文件路径 / 数据源等），编辑器类插件用它定位内容。
+ *
+ * 样式：LinkDesk 主题色一律走 CSS 变量 var(--xxx)（见 index.css 示例），禁硬编码 hex。
+ * 文案：用 t() 读——key 就是中文原文，英文译文放 i18n/en.json（见 05-UI写法规约.md）。
+ * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
+ */
+
+import { useTranslation } from "react-i18next";
+import "./index.css";
+
+export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="starter">
+      <h2 className="starter__title">{t("插件跑起来了 ✨")}</h2>
+      <p className="starter__text">{t("这是你的第一个 LinkDesk 插件。")}</p>
+      <p className="starter__hint">
+        <code>src/index.tsx</code> {t("是插件本体——改它，浏览器预览即时刷新。")}
+      </p>
+      <p className="starter__hint">
+        <code>npm run build</code> {t("打包出分发文件，可装进 LinkDesk 或发布到市场。")}
+      </p>
+      <p className="starter__hint">{t("目录该放哪、发布怎么做，都写在 README.md 里。")}</p>
+    </div>
+  );
+}

package/template/vitest.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * 插件工程测试环境（E6#102 §二）。
+ *
+ * 🔴 这份配置**逐项对齐壳仓 `vitest.config.ts`**：`globals` / `environment: "jsdom"` /
+ * `setupFiles` 三条是**静默生效**的配置——缺了会报错（那还算好），配错了则是「本地绿、CI 红」，
+ * 是这类迁移最典型的坑。改这里前先看壳仓那份，别让两边环境分叉。
+ *
+ * 两条**刻意不抄**壳仓的地方（写了就是错）：
+ *   - **不设 `@src` / `@` 别名**：壳仓别名是给「与壳同仓的插件」用的；插件源码已外移，
+ *     `@src` 在本仓物理不可达。插件代码只经 `window.linkdesk.*` 与 `@linkdesk/ui` 拿能力。
+ *   - **不 include `plugins/**`**：本仓就是一只插件，源码在 `src/`。
+ *
+ * 🔴 **`server.deps.inline` 是为「仓外形态」新加的一条**（壳仓没有、也不需要）：壳仓里
+ *   `@linkdesk/ui` 解析到**同仓源码**，CSS 由 Vite 顺手处理；插件仓解析到**已发布的 dist**，
+ *   而 `dist/index.js` 里有 `import "./index.css"` —— Node 的外部依赖加载器读不了 `.css`，
+ *   于是凡经 `@linkdesk/ui` 的测试全部倒在
+ *   `TypeError: Unknown file extension ".css"`（E6#102 实测：marketplace 6 个文件 / 12 例）。
+ *   把 `@linkdesk/ui` 交给 Vite 内联处理后即恢复。**别删这一条**——删了只会在有 UI 组件的
+ *   仓里以「莫名其妙的环境错」重现。
+ *
+ * `passWithNoTests`：还没有测试的工程跑 `vitest run` 不该红——它是「没写」不是「写错了」。
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "jsdom",
+    setupFiles: ["./vitest.setup.ts"],
+    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
+    passWithNoTests: true,
+    server: { deps: { inline: ["@linkdesk/ui"] } },
+  },
+});

package/template/vitest.setup.ts

@@ -0,0 +1,96 @@
+/**
+ * vitest setup——mock window.linkdesk API。
+ * 测试跑在 Node.js/jsdom，没有 Electron preload 注入的 window.linkdesk。
+ * 迁移到 linkdesk.* API 后，插件代码直接依赖它——测试环境需提供最小 mock。
+ *
+ * 🔴 E6#102（L7 第 7.5 轮）：**本文件是壳仓 `vitest.setup.ts` 的逐字副本**（除本头注五条）。
+ *   它不是「配置」，是插件测试的**运行时地基**——下半部的六个命名空间与 `__ldkConfigStore`
+ *   少了任何一个，凡碰 `window.linkdesk` 的测试都会报错、或更糟：静默走错分支。
+ *   改壳仓那份时把这里一起改（两处同源）。「由 @linkdesk/plugin-sdk 提供共享版本、
+ *   本文件改成一行 re-export」已登记为待收的账——那时这五条注记一并删掉。
+ */
+
+// path 纯函数——直接实现，不走 IPC
+const pathMock = {
+  normalize: (p: string) => p.replace(/\\/g, "/"),
+  join: (...parts: string[]) =>
+    parts.map((p) => String(p).replace(/\\/g, "/")).join("/").replace(/\/+/g, "/"),
+  basename: (p: string) => {
+    const s = p.replace(/\\/g, "/").split("/");
+    return s[s.length - 1] || "";
+  },
+  dirname: (p: string) => {
+    const s = p.replace(/\\/g, "/").split("/");
+    s.pop();
+    return s.join("/") || ".";
+  },
+  extname: (p: string) => {
+    const b = p.replace(/\\/g, "/").split("/").pop() || "";
+    const i = b.lastIndexOf(".");
+    return i > 0 ? b.slice(i) : "";
+  },
+};
+
+// E5.7#98：测试全局窄类型 cast——替代 (globalThis as any)（__ldkConfigStore 由本文件声明、测试文件消费）
+type TestGlobal = { window?: Window; __ldkConfigStore?: Map<string, unknown> };
+const _g = globalThis as TestGlobal;
+
+// configuration——默认返回 null，测试中按需 mock。
+// __ldkConfigStore 暴露给测试——测试可直接设置值控制 get() 返回。
+const _configStore = (_g.__ldkConfigStore = new Map<string, unknown>());
+const configurationMock = {
+  get: async (key: string) => _configStore.get(key) ?? null,
+  set: async (key: string, v: unknown) => { _configStore.set(key, v); },
+  onChange: (_key: string, _cb: (v: unknown) => void) => {
+    return () => {}; // no-op unsubscribe
+  },
+};
+
+// workspace——默认返回空工作区
+const workspaceMock = {
+  getFolders: async () => [] as { uri: string; name: string }[],
+  getActive: async () => undefined as string | undefined,
+};
+
+// filesystem——可替换的最小 stub。测试可覆盖 lk.filesystem.xxx = vi.fn() 按需定制
+const filesystemMock = {
+  readTextFile: async (_p: string) => "",
+  writeTextFile: async (_p: string, _d: string) => {},
+  readBinaryFile: async (_p: string) => new Uint8Array(),
+  writeBinaryFile: async (_p: string, _d: Uint8Array) => {},
+  listDir: async (_p: string) => [] as { path: string; name: string; isDirectory: boolean; isFile: boolean }[],
+  exists: async (_p: string) => false,
+  mkdir: async (_p: string) => {},
+  copy: async (_src: string, _dest: string) => {},
+  remove: async (_p: string) => {},
+  watch: async (_dirPath: string, _onEvent: (e: unknown) => void) => {
+    return () => {}; // unsubscribe
+  },
+};
+
+// tabs——最小 stub
+const tabsMock = {
+  create: async (_type: string, _opts?: Record<string, unknown>) => "tab-1",
+  openOrFocus: async (_type: string, _opts?: Record<string, unknown>) => "tab-1",
+  focus: async (_tabId: string) => {},
+  close: async (_tabId: string) => {},
+  focusBySourceId: async (_sourceId: string) => {},
+  updateLabelBySourceId: async (_sourceId: string, _label: string) => {},
+  closeBySourceId: async (_sourceId: string) => {},
+};
+
+// 最小 mock——故意不满足 LinkDeskAPI 全契约（测试按需覆盖），经 linkdesk?: object 窄口赋值
+_g.window = _g.window ?? ({} as Window);
+(_g.window as Window & { linkdesk?: object }).linkdesk = {
+  path: pathMock,
+  configuration: configurationMock,
+  config: configurationMock,
+  workspace: workspaceMock,
+  filesystem: filesystemMock,
+  tabs: tabsMock,
+  // event stubs
+  events: {
+    on: () => () => {},
+    emit: () => {},
+  },
+};