create-linkdesk-plugin 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# create-linkdesk-plugin
+
+LinkDesk 插件脚手架——一行命令生成你的第一个插件项目（对标 `yo code`）。
+
+```bash
+npm create linkdesk-plugin my-cool-plugin
+```
+
+不带名字则交互式询问：
+
+```bash
+npm create linkdesk-plugin
+```
+
+## 生成什么
+
+```
+my-cool-plugin/
+├── plugin.json          # 插件清单（JSONC：可注释/尾逗号，字段分节示范，VS Code $schema 校验）
+├── package.json         # scripts: dev / build / validate；依赖 @linkdesk/plugin-sdk
+├── tsconfig.json        # jsx: react-jsx + window.linkdesk.* 类型（@linkdesk/plugin-sdk）
+├── .vscode/settings.json # plugin.json 按 jsonc 识别（注释不标红）
+├── src/
+│   ├── index.tsx        # 视图组件 default 导出——壳以 { isActive, tabId?, sourceId? } 渲染
+│   └── index.css        # 样式示例——主题色走 var(--xxx)
+└── i18n/
+    └── en.json
+```
+
+然后：
+
+```bash
+cd my-cool-plugin
+npm install
+npm run build     # 产出 <pluginId>.linkdesk-plugin——可装进 LinkDesk / 发布
+```
+
+> 说明：插件作者工作流（dev 热预览 / build / 发布全链路）的完整文档见
+> [00-第三方作者旅程](../../docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)。

package/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * create-linkdesk-plugin——LinkDesk 插件脚手架 CLI（纯 Node，零依赖，对标 yo code）。
+ *
+ * 用法：
+ *   npm create linkdesk-plugin my-cool-plugin   # 直接给名字（kebab-case，非交互）
+ *   npm create linkdesk-plugin                  # 不带参数 → 交互式询问插件名
+ *
+ * 行为：把同目录 template/ 复制到 <cwd>/<name>，把占位符替换成真实值，打印下一步提示。
+ * 占位符：{{pluginName}} {{displayName}} {{author}}（递归替换所有模板文件）。
+ *
+ * 生成产物契约：见 docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
+
+/** kebab-case——同时满足插件 id / viewsContainers key / npm 包名惯例（SAFE_PLUGIN_ID 的形状子集） */
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/** my-cool-plugin → My Cool Plugin */
+function toDisplayName(name) {
+  return name
+    .split("-")
+    .map((s) => (s ? s[0].toUpperCase() + s.slice(1) : s))
+    .join(" ");
+}
+
+/** 作者默认值 = git config user.name；读不到（无 git/无配置）→ "you"（作者生成后自改） */
+function gitUserName() {
+  try {
+    const r = spawnSync("git", ["config", "user.name"], { encoding: "utf8", timeout: 3000 });
+    const v = (r.stdout || "").trim();
+    return v || "you";
+  } catch {
+    return "you";
+  }
+}
+
+/** 交互式单问——返回去除首尾空白的答案 */
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function replacePlaceholders(file, values) {
+  let text = readFileSync(file, "utf8");
+  for (const [key, value] of Object.entries(values)) {
+    text = text.split(`{{${key}}}`).join(value);
+  }
+  writeFileSync(file, text);
+}
+
+/** 递归替换目录内全部文件（模板全是文本文件，无需跳过二进制） */
+function walkReplace(dir, values) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkReplace(full, values);
+    else replacePlaceholders(full, values);
+  }
+}
+
+async function main() {
+  let name = (process.argv[2] || "").trim();
+  if (!name) {
+    name = await ask("插件名（kebab-case，如 my-cool-plugin）: ");
+  }
+  name = name.trim();
+  if (!NAME_RE.test(name)) {
+    console.error(`✖ 插件名须为 kebab-case（小写字母/数字/连字符），收到：${JSON.stringify(name)}`);
+    process.exit(1);
+  }
+
+  const target = join(process.cwd(), name);
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`✖ ${name}/ 已存在且非空——换个名字，或清空后重跑`);
+    process.exit(1);
+  }
+
+  mkdirSync(target, { recursive: true });
+  cpSync(TEMPLATE_DIR, target, { recursive: true });
+
+  const values = { pluginName: name, displayName: toDisplayName(name), author: gitUserName() };
+  walkReplace(target, values);
+
+  console.log("");
+  console.log(`✔ ${name}/ 已创建`);
+  console.log("");
+  console.log("  接下来：");
+  console.log(`    cd ${name}`);
+  console.log("    npm install");
+  console.log("    npm run validate   # 校验 plugin.json（$schema / 字段 / i18n 文件）");
+  console.log("    npm run build      # 产出 <pluginId>.linkdesk-plugin，可装进 LinkDesk / 发布");
+  console.log("");
+  console.log("  编辑 plugin.json 的 name / description / author，src/index.tsx 是你的插件本体。");
+  console.log("  更多插件能力（侧栏视图 / 命令 / 设置 / 协议……）见 docs/03-插件制造/ 与 plugin.schema.json。");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "create-linkdesk-plugin",
+  "version": "0.1.0",
+  "description": "LinkDesk 插件脚手架——`npm create linkdesk-plugin my-cool-plugin` 一行生成你的第一个插件项目（对标 yo code）。",
+  "type": "module",
+  "bin": {
+    "create-linkdesk-plugin": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "linkdesk",
+    "plugin",
+    "scaffold",
+    "create"
+  ],
+  "license": "MIT"
+}

package/template/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "plugin.json": "jsonc"
+  }
+}

package/template/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "hello": "Hello from LinkDesk!"
+}

package/template/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{pluginName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{displayName}}——LinkDesk 插件（由 create-linkdesk-plugin 生成）",
+  "type": "module",
+  "scripts": {
+    "dev": "linkdesk-plugin-sdk dev",
+    "build": "linkdesk-plugin-sdk build",
+    "validate": "linkdesk-plugin-sdk validate"
+  },
+  "devDependencies": {
+    "@linkdesk/plugin-sdk": "^0.1.0",
+    "@types/react": "^18.3.12",
+    "typescript": "^5.6.3"
+  }
+}

package/template/plugin.json

@@ -0,0 +1,38 @@
+{
+  // ─────────────────────────────────────────────────────────────────────────
+  //  LinkDesk 插件清单 plugin.json（由 create-linkdesk-plugin 生成）
+  //
+  //  · 本文件是 JSONC：可写注释、可尾逗号（LinkDesk 与 SDK 都按 jsonc 解析，对标 VS Code package.json）。
+  //  · 完整字段以 plugin.schema.json 为准——VS Code 读 $schema 自动补全 + 校验。
+  //  · $schema 指向本工程 node_modules/@linkdesk/plugin-sdk 随包拷贝（npm install 后生效）。
+  // ─────────────────────────────────────────────────────────────────────────
+  "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json",
+
+  // ── 插件身份 ──
+  "pluginId": "{{pluginName}}", // 全局唯一 ID（kebab-case）——安装目录 / 寻址 / 命令前缀都按它
+  "name": "{{displayName}}", // 显示名——标签页 / 插件详情等 UI 出现处
+  "version": "0.1.0", // 语义化版本 x.y.z——发布更新比较靠它，改了要 +1
+  "description": "{{displayName}}——我的第一个 LinkDesk 插件", // 一句话描述（插件详情页展示）
+  "author": "{{author}}", // 作者名
+
+  // ── 入口（视图插件 = 此文件 default 导出一个 React 组件）──
+  "entry": "src/index.tsx",
+
+  // ── 出现位置：可作为主区标签页打开 ──
+  "appearsIn": { "tabBar": true },
+  "tabBehavior": { "singleton": true }, // 全局只开一个实例，避免重复标签
+
+  // ── 贡献点（contributes：全部可选，按需增删）──
+  "contributes": {
+    // 自带翻译：key=语言码, value=相对插件根的 JSON 文件。UI 文案用 t() 读这里；无需 zh.json——中文 key 原文自带兜底。
+    "i18n": { "en": "i18n/en.json" },
+    // ── 需要「侧栏 / 底部面板 / 辅助侧栏」分区视图时：取消注释，在 src/views/ 放对应组件，
+    //    容器 key 与 view id 用你的 pluginId 做前缀防撞（对标 plugins/panel-demo）──
+    // "viewsContainers": { "{{pluginName}}-sidebar": { "title": "{{displayName}}", "location": "sidebar" } },
+    // "views": {
+    //   "{{pluginName}}-sidebar": [
+    //     { "id": "main", "title": "{{displayName}}", "render": "src/views/MainView.tsx", "order": 0 }
+    //   ]
+    // }
+  },
+}

package/template/src/index.css

@@ -0,0 +1,23 @@
+/* {{displayName}} 样式示例——LinkDesk 主题色一律走 var(--xxx)，禁硬编码 hex。
+   布局/字号这类结构值用普通 px（不违反）；颜色/语义类才必须走主题变量。 */
+
+.starter {
+  padding: 24px;
+  font-family: inherit;
+}
+
+.starter__title {
+  margin: 0 0 8px;
+  color: var(--text);
+}
+
+.starter__text {
+  margin: 0 0 4px;
+  color: var(--text-muted);
+}
+
+.starter__hint {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 12px;
+}

package/template/src/index.tsx

@@ -0,0 +1,29 @@
+/**
+ * {{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。
+ * UI 文案规范化后用 t()（react-i18next，壳提供）读 i18n/en.json——见 05-UI写法规约.md。
+ * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
+ */
+
+import "./index.css";
+
+export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
+  return (
+    <div className="starter">
+      <h2 className="starter__title">{{displayName}} 跑起来了 ✨</h2>
+      <p className="starter__text">这是你的第一个 LinkDesk 插件。</p>
+      <p className="starter__hint">
+        编辑 <code>src/index.tsx</code> 即可看到变化；<code>npm run build</code> 打包出{" "}
+        <code>.linkdesk-plugin</code> 分发文件。
+      </p>
+    </div>
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": ["@linkdesk/plugin-sdk"],
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}