create-linkdesk-plugin 0.1.12 → 0.1.14

package/README.md

@@ -30,7 +30,7 @@ my-cool-plugin/
 ├── .github/workflows/ci.yml   # CI that runs `npm run verify` on every push
 ├── scripts/ci-verify.mjs      # the strict tier CI runs (lint + tests + declaration self-checks)
 ├── vitest.config.ts      # test config (jsdom + globals; @linkdesk/ui is inlined so its CSS import resolves)
-├── vitest.setup.ts       # test runtime ground — mocks window.linkdesk (no Electron preload under vitest)
+├── vitest.setup.ts       # one-line pointer to the shared test ground in @linkdesk/plugin-sdk (the window.linkdesk mock)
 ├── .vscode/settings.json      # plugin.json is treated as jsonc (comments do not light up red)
 ├── resources/
 │   └── icon.svg          # placeholder icon — replace it with your own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-linkdesk-plugin",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "LinkDesk 插件脚手架——`npm create linkdesk-plugin@latest my-cool-plugin` 一行生成你的第一个插件项目（对标 yo code）。",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -47,6 +47,15 @@ npm run publish    # ⑧ publish to your own GitHub repo (first step of listing)
 - **This project is its own git repo** (the scaffold ran `git init -b main` plus one initial commit). `publish` uses `origin` to create the Release ⇒ pushing to GitHub is just two commands: `git remote add origin <your repo>` + `git push -u origin main`.
 - **Keep the version numbers in step**: `plugin.json`'s `version` and `package.json`'s `version` **must match**; and every bump needs a matching `## v<new version>（YYYY-MM-DD）` section in `CHANGELOG.md`, or the plugin's detail page will show "no changelog provided for this version".
 
+## 6. Tests in this repo
+
+- **The toolchain is preinstalled** (`vitest` / `jsdom` / `@testing-library/react` are already declared) — write a `*.test.ts` file and run `npm run test`.
+- **The shared test ground comes from the SDK**: the minimal `window.linkdesk` mock lives in `@linkdesk/plugin-sdk/vitest-setup`, and this repo's `vitest.setup.ts` is a **one-line pointer** to it. **Do not paste a second copy in here** — a copied mock drifts from the shared one and nothing would notice.
+- **Pure logic should be tested**: a `src/**/*.ts` unit that touches neither React nor `window.linkdesk` should get a `src/__tests__/<same name>.test.ts`. Views and hooks are worth testing **when it pays off** — nothing measures that today.
+- **Plugin-specific stubs stay in your own test files**: if your code calls something the shared mock does not cover (say `window.linkdesk.serial`), set that stub up with `vi.fn()` in the test. Do not ask the shared mock to grow a branch for your plugin.
+- **Declarative plugins** (pure JSON / themes / language packs) have **no testable units** — their gate is the structure and declaration checks in `npm run verify`. "It has no tests" is not a defect there.
+- **Older projects can migrate whenever they like**: replacing the full mock body with the one-line pointer plus one `npm install` is the whole move (upside: mock upgrades then ride along with the SDK).
+
 ---
 
 > Author: {{author}} ｜ Generated: {{date}}

package/template/README.md

@@ -18,7 +18,7 @@ You do not need to pre-create empty folders (git does not track them). **Create
 | `plugin.json` | The plugin manifest | **Always** |
 | `README.md` | Description — the data source for the marketplace **Details** tab | Strongly recommended |
 | `CHANGELOG.md` | Release notes — the data source for the marketplace **Changelog** tab | Strongly recommended |
-| `resources/` | Assets: `icon.svg` / `cover.svg` / images referenced from the README | Once you have images |
+| `resources/` | Assets — **three preset placeholders, each with a job comment inside**: `icon.svg` (small in-app icon) / `icon-bar.svg` (Icon Bar single-colour glyph) / `cover.svg` (README cover), plus any images referenced from the README | Always (replace the placeholders) |
 | `i18n/` | `en.json` (key = the source string; **do not create `zh.json`**) | Once you have UI text |
 | `themes/` · `languages/` · `snippets/` | Payloads for data-only plugins | Data-only plugins |
 | `src/index.tsx` | Entry (the `entry` in `plugin.json`) | Always for view plugins |
@@ -26,7 +26,7 @@ You do not need to pre-create empty folders (git does not track them). **Create
 | `src/components/` | Components reused inside this plugin | When needed |
 | `src/services/` | Domain logic / IPC wrappers / data layer | When needed |
 | `src/styles/` | **Multiple** CSS files — keep them together here (a single file next to the entry is fine too) | When needed |
-| `src/__tests__/` | Unit tests (run `npm i -D vitest` yourself if you want them — the scaffold does not preinstall test tooling) | When needed |
+| `src/__tests__/` | Unit tests — **test tooling is preinstalled** (`vitest` / `jsdom` / `@testing-library/react` are already in `devDependencies`); the `window.linkdesk` mock is **not** in this repo — `vitest.setup.ts` is a one-line pointer to the shared ground in `@linkdesk/plugin-sdk`, so just write tests and run `npm run test` | When needed |
 
 > 🔴 **Shared things do not belong here** — components/hooks reused across plugins come from `@linkdesk/ui` (the public package the shell provides; it is already declared in `package.json` as `"latest"`, which resolves to the shell's current version line when you install — pin it to a specific shell version if you need a floor). The shell supplies that one instance at runtime, so **do not import its css** and **do not write a second copy inside your plugin**. Only logic that belongs to this plugin stays local.
 > 🔴 **Assets always live in `resources/` — no loose images in the plugin root.** What gets into the install package is what is **referenced by the README** or **declared by `icon` / `marketIcon`**; the directory name itself has no magic.
@@ -37,6 +37,8 @@ You do not need to pre-create empty folders (git does not track them). **Create
 2. **UI text goes through `t()`** — `t("source string")`, with English in `i18n/en.json` and **no `zh.json`** (the source string is the key and is its own fallback). **Only add keys you actually read with `t()`** — an unread key is a dead key. Code identifiers (`src/index.tsx` and friends) are not copy — do not wrap them in `t()`.
 3. **Plugin identity comes only from declared fields in `plugin.json`** — declare whatever capability you need (`contributes` / `tabBehavior` / `icon` …). **Never make other people guess what your plugin is from a directory name or file location.**
 
+**Dev preview note:** the dev host (`npm run dev`) gives your view a **fixed-height root container** (`#ld-root`) — write `height: 100%` on your root element with confidence and it fills the preview. You never need ResizeObserver self-healing or a "just in case" fallback layer; if your panel still renders collapsed or transparent in the preview, report it — don't code around it.
+
 ## Publishing
 
 ```bash

package/template/plugin.json

@@ -22,7 +22,13 @@
   "minAppVersion": "0.2.13",
   "description": "{{displayName}}——我的第一个 LinkDesk 插件", // 一句话描述（插件详情页展示）
   "author": "{{author}}", // 作者名
-  "icon": "resources/icon.svg", // 图标——图标栏 / 标签页 / 市场里显示的就是它（resources/icon.svg 是占位图，换成你的）
+  // ── 图标——三图模型（完整规则见作者面 06 号《plugin.json 规范》§marketIcon）──
+  // icon = 界面小图标：标签页 [＋] 菜单 / 欢迎页等处（要进 42px 图标栏需再声明 appearsIn.iconBar；
+  //   ⚠️ 图标栏会对图强制单色染色——进图标栏的图要画单色线稿剪影，resources/icon-bar.svg 是预置占位）。
+  // marketIcon = 市场彩色身份图：市场列表行与详情页头部用（可选；缺省回落 icon）。
+  // cover = README 场景封面：只住 README 说明区，不是 manifest 字段（resources/cover.svg 已预置）。
+  "icon": "resources/icon.svg", // 占位图，换成你的
+  // "marketIcon": "resources/icon.svg", // 市场彩色身份图（可选；缺省回落 icon）——市场要彩色展示时取消注释
 
   // ── 入口（视图插件 = 此文件 default 导出一个 React 组件）──
   "entry": "src/index.tsx",
@@ -33,6 +39,16 @@
 
   // ── 贡献点（contributes：全部可选，按需增删）──
   "contributes": {
+    // ── 贡献点速查（每键一行，只指路不展开——完整语法与示例见作者面 03 号《contributes 规范》，落位见 17 号《区域地图》）──
+    // commands —— 注册命令：命令面板 / 右键菜单 / 快捷键 / 标题栏按钮的公共落脚点（id 用 "<pluginId>." 前缀防撞）
+    // keybindings —— 给命令绑快捷键：keys ＋ command ＋ when（上下文旗子，条件满足才触发）
+    // menus —— 菜单位声明（右键菜单走声明式，禁止手写右键菜单）
+    // configuration —— 声明设置项：设置页自动渲染一个分组（另见 20 号《我的插件加一条配置项》）
+    // titleBar —— 标题栏按钮：right[] / left[]，icon ＋ command（＋ when）
+    // viewsContainers / views —— 侧栏 / 底部面板的容器与视图（下面注释里有现成示例；容器 API 详见 08 号）
+    // themes / languages —— 主题包 / 语言包（数据型插件的载荷）
+    // floatingPanel —— 把你已有的某个视图声明成「可在悬浮面板打开」
+    // ⚠️ statusBar 不是 contributes 的键——它是 plugin.json **顶层**的 statusBar[] 数组（写进 contributes 无效，见 17 号 ⑦ 状态栏）
     // 自带翻译：key=语言码, value=相对插件根的 JSON 文件。UI 文案用 t() 读这里；无需 zh.json——中文 key 原文自带兜底。
     "i18n": { "en": "i18n/en.json" },
     // ── 需要「侧栏 / 底部面板 / 辅助侧栏」分区视图时：取消注释，在 src/views/ 放对应组件，

package/template/resources/cover.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" viewBox="0 0 640 320">
+  <!-- README 场景封面占位——替换成你插件的真实截图/场景图（同名覆盖即可），
+       在 README.md 顶部引用（模板 README 里已有注释好的引用行，取消注释即用）：
+         ![<插件名> cover](resources/cover.svg)
+       ⚠️ 这张图只住 README（市场详情页「详情」页签的说明区）——它不是市场列表/详情头的身份图，
+       那个位置是 marketIcon（见 plugin.json 注释 / 作者面 06 号 §marketIcon）；
+       README 放图的完整规则见作者面 12 号《README 说明区媒体契约》。 -->
+  <rect x="0" y="0" width="640" height="320" rx="12" fill="#1E293B"/>
+  <rect x="170" y="110" width="300" height="100" rx="8" fill="none" stroke="#475569" stroke-width="2" stroke-dasharray="7 5"/>
+  <text x="320" y="166" fill="#64748B" font-family="sans-serif" font-size="17" text-anchor="middle">cover.svg — your scene here</text>
+</svg>

package/template/resources/icon-bar.svg

@@ -0,0 +1,9 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <!-- 图标栏 Type-1 单色线稿剪影占位——替换成你自己插件的剪影（同名覆盖即可）。
+       用法：plugin.json 里 "appearsIn": { "iconBar": "top" } ＋ "icon": "resources/icon-bar.svg"。
+       ⚠️ 图标栏会对图强制单色染色——别放彩色图（彩色进来会糊成一团）；
+       这是独立 SVG 文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。
+       市场里要彩色身份图不归这张管——那是 marketIcon 的职责（见 plugin.json 注释 / 作者面 06 号 §marketIcon）。 -->
+  <rect x="4.5" y="4.5" width="15" height="15" rx="3.5" stroke="#9CA3AF" stroke-width="1.8" stroke-dasharray="3.5 2.5" stroke-linecap="round"/>
+  <path d="M12 9v6M9 12h6" stroke="#9CA3AF" stroke-width="1.8" stroke-linecap="round"/>
+</svg>

package/template/resources/icon.svg

@@ -1,7 +1,10 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48">
   <!-- ⚠️ 占位图——请替换成你自己插件的图标（同名同位置覆盖即可，plugin.json 的 icon 已指向本文件）。
        写法与官方插件一致：界面里以 <img src="linkdesk://<id>/resources/icon.svg"> 显示，
-       是独立文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。 -->
+       是独立文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。
+       三图模型——本文件 = 界面小图标（要进图标栏需 appearsIn.iconBar，图标栏会强制单色染色，
+       进图标栏请换 resources/icon-bar.svg 那样的单色剪影）；市场彩色身份图 = marketIcon；
+       README 场景封面 = resources/cover.svg。各管各的，详见作者面 06 号《plugin.json 规范》§marketIcon。 -->
   <defs>
     <linearGradient id="phi_bg" x1="0" y1="0" x2="1" y2="1">
       <stop offset="0" stop-color="#64748B"/>

package/template/vitest.setup.ts

@@ -1,96 +1,3 @@
-/**
- * vitest setup——mock window.linkdesk API。
- * 测试跑在 Node.js/jsdom，没有 Electron preload 注入的 window.linkdesk。
- * 迁移到 linkdesk.* API 后，插件代码直接依赖它——测试环境需提供最小 mock。
- *
- * 🔴 **本文件是壳仓 `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) : "";
-  },
-};
-
-// 测试全局窄类型 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: () => {},
-  },
-};
+// Shared test ground: the minimal `window.linkdesk` mock ships with the SDK (`@linkdesk/plugin-sdk/vitest-setup`).
+// One line on purpose — plugin-specific stubs belong in your own test files (`vi.fn()`), not in here.
+import "@linkdesk/plugin-sdk/vitest-setup";