vite-plugin-siyuan 0.1.0 → 0.2.0

package/README.md

@@ -18,7 +18,8 @@ import { defineConfig } from 'vite';
 import siyuan from 'vite-plugin-siyuan';
 
 export default defineConfig({
-  plugins: [siyuan()],
+  // entry 必填：主题指向 CSS，插件指向 TS/JS
+  plugins: [siyuan({ entry: 'src/main.css' })],
 });
 ```
 
@@ -32,9 +33,12 @@ pnpm vite build --watch
 
 | 选项 | 说明 |
 |---|---|
-| `kind` | `'theme'` / `'plugin'`；缺省时在 `public/`、`dist/`、项目根依次查找 `theme.json` / `plugin.json` 推断 |
+| `entry` | **必填**。构建入口，相对项目根。主题指向 CSS，插件指向 TS/JS |
+| `kind` | `'theme'` / `'plugin'`；缺省时在 `public/`、项目根依次查找 `theme.json` / `plugin.json` 推断 |
 | `outDir` | 产物目录；缺省 `./dev`（watch）/ `./dist`（生产） |
-| `entry` | 构建入口，相对项目根；缺省保留项目自己的 `input` / `lib` |
+
+> `entry` 必填是因为产物名是固定契约（主题 `theme.css`、插件 `index.js`）。
+> 入口猜错不会报错，只会静默产出思源加载不到的东西——所以宁可要求显式指定。
 
 ## 做什么
 
@@ -42,8 +46,8 @@ pnpm vite build --watch
 
 ### watch（`vite build --watch`）
 
-1. **注入构建配置**：主题产出 `theme.css`；插件在给了 `entry` 时走 `lib` CJS 单文件产出 `index.js`。`base: './'` 保证宿主下资源不 404。用 `mergeConfig` 合并，**用户已写的值优先**。
-2. **链接产物**：把 `dev/` 链接到 `<workspace>/data/themes|plugins/<name>`。插件目录必须是真 symlink（思源 Go 运行时按 `ModeSymlink` 判定），主题可用 junction 兜底。
+1. **注入构建配置**：主题产出 `theme.css`；插件走 `lib` CJS 单文件产出 `index.js`。`base: './'` 保证宿主下资源不 404。用 `mergeConfig` 合并，**用户已写的值优先**。
+2. **链接产物**：把 `dev/` 链接到 `{workspace}/data/themes|plugins/{name}`。插件目录必须是真 symlink（思源 Go 运行时按 `ModeSymlink` 判定），主题可用 junction 兜底。
 3. **激活**：主题调 `setAppearance` 选中它；插件调 `setPetalEnabled` 启用。
 4. **热重载**：产物变化后合并 250ms 广播 `reloadUI`，思源整页刷新。
 
@@ -74,8 +78,8 @@ watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览
 | 变量 | 说明 |
 |---|---|
 | `SIYUAN_PORT` | kernel 端口；缺省用 kernel 进程 PID 匹配 `port.json`，再探测记录端口与 6806–6809 |
-| `SIYUAN_THEME_DIR` | 主题安装父目录（`<workspace>/data/themes`），实际装到 `<它>/<name>` |
-| `SIYUAN_PLUGIN_DIR` | 插件安装父目录（`<workspace>/data/plugins`），同上 |
+| `SIYUAN_THEME_DIR` | 主题安装父目录（`{workspace}/data/themes`），实际装到 `{该目录}/{name}` |
+| `SIYUAN_PLUGIN_DIR` | 插件安装父目录（`{workspace}/data/plugins`），同上 |
 | `SIYUAN_TOKEN` | 开了 API token 时使用 |
 | `SIYUAN_NO_ELEVATION=1` | 不弹 UAC 提权（CI 环境自动不弹） |
 | `SIYUAN_DEBUG=1` | 输出 debug 级日志 |

package/dist/artifact/verify.js

@@ -29,10 +29,9 @@ function findDoubleWrappedColors(css) {
 export function verifyTarget(kind, { root, outDir }) {
     const spec = kindSpec(kind);
     const issues = [];
-    const declaredOutDir = isAbsolute(outDir) ? outDir : join(root, outDir);
     // 只校验本次构建的产物目录。不做「产物目录不存在就改扫项目根」的兜底：
     // 插件永远在真实构建之后校验，那种兜底只会把 node_modules 当成产物扫进来。
-    const absOutDir = declaredOutDir;
+    const absOutDir = isAbsolute(outDir) ? outDir : join(root, outDir);
     const walked = walkFiles(absOutDir);
     const files = walked.map((file) => file.name);
     const byName = new Map(walked.map((file) => [file.name, file.path]));
@@ -46,7 +45,7 @@ export function verifyTarget(kind, { root, outDir }) {
     // ---- 通用：清单存在与形状 ----
     if (!manifest) {
         issues.push({
-            message: `读不到清单：${spec.manifestName}（找过 public/、dist/、项目根）`,
+            message: `读不到清单：${spec.manifestName}（找过 public/、项目根与产物目录）`,
             hint: '思源按清单识别主题/插件，缺了它不会出现在列表里。',
         });
     }

package/dist/config.d.ts

@@ -4,8 +4,8 @@ import type { Kind } from './siyuan/kinds.ts';
 export interface BuildSpecInput {
     kind: Kind;
     watch: boolean;
-    /** 入口文件绝对路径；不给则保留项目自己的 input/lib。 */
-    entry: string | null;
+    /** 入口文件绝对路径。必填：产物名是固定契约，入口不能靠猜。 */
+    entry: string;
     /** 插件选项里显式给的产物目录。 */
     outDir: string | null;
 }

package/dist/config.js

@@ -35,9 +35,7 @@ function optionsKey(userConfig) {
 export function buildSpecFor(input) {
     const spec = kindSpec(input.kind);
     const outDir = input.outDir ?? (input.watch ? './dev' : './dist');
-    const options = {};
-    if (input.entry)
-        options.input = input.entry;
+    const options = { input: input.entry };
     if (input.kind === 'plugin') {
         options.external = ['siyuan', 'process'];
         options.output = {
@@ -55,7 +53,7 @@ export function buildSpecFor(input) {
         // watch 不压缩（便于直接看落盘产物），生产用默认压缩器。
         minify: !input.watch,
     };
-    if (input.entry && input.kind === 'plugin') {
+    if (input.kind === 'plugin') {
         // 插件入口是 `export default class ...`，必须走 lib：lib cjs 产出
         // `module.exports = 类`；普通 input 只得到 `exports.default`，思源报
         // "plugin xxx has no export"。

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 import type { Plugin } from 'vite';
 import type { Kind } from './siyuan/kinds.ts';
 export interface SiYuanOptions {
+    /**
+     * 构建入口，相对项目根。必填：主题要产出固定名 `theme.css`、插件要产出
+     * CJS 单文件 `index.js`，产物名是思源加载机制决定的契约，入口不能靠猜——
+     * 猜错不会报错，只会静默产出思源加载不到的东西。
+     */
+    entry: string;
     /** 被测类型（theme / plugin）；缺省从清单推断。 */
     kind?: Kind | null;
     /** 产物目录；缺省 `./dev`（watch）/ `./dist`（生产）。 */
     outDir?: string | null;
-    /** 构建入口，相对项目根；缺省保留项目自己写的 input/lib。 */
-    entry?: string | null;
 }
-export default function siyuan(options?: SiYuanOptions): Plugin;
+export default function siyuan(options: SiYuanOptions): Plugin;

package/dist/index.js

@@ -16,6 +16,7 @@
  *   closeBundle    校验 + 打包 + 汇报 + 构建完成日志
  *   closeWatcher   释放定时器
  */
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { applyBuildConfig } from './config.js';
 import { detectKind } from './siyuan/kinds.js';
@@ -23,7 +24,7 @@ import { createTaggedLogger } from './output/log.js';
 import { createBuildSession } from './session.js';
 import { describeError, UserError } from './support/errors.js';
 const NAME = 'vite-plugin-siyuan';
-export default function siyuan(options = {}) {
+export default function siyuan(options) {
     const log = createTaggedLogger(NAME);
     let session = null;
     let kind = options.kind ?? null;
@@ -32,6 +33,10 @@ export default function siyuan(options = {}) {
         apply: 'build',
         config(userConfig) {
             const root = typeof userConfig.root === 'string' ? resolve(userConfig.root) : process.cwd();
+            const entry = resolve(root, options.entry);
+            if (!existsSync(entry)) {
+                throw new UserError(`entry 指向的文件不存在：${entry}（选项值：${options.entry}）`);
+            }
             try {
                 kind ??= detectKind(root);
             }
@@ -41,7 +46,6 @@ export default function siyuan(options = {}) {
                 return undefined;
             }
             const watch = Boolean(userConfig.build?.watch);
-            const entry = options.entry ? resolve(root, options.entry) : null;
             return applyBuildConfig(userConfig, { kind, watch, entry, outDir: options.outDir ?? null });
         },
         configResolved(resolvedConfig) {
@@ -49,7 +53,6 @@ export default function siyuan(options = {}) {
             const outDir = resolvedConfig.build.outDir;
             const publicDir = resolvedConfig.publicDir;
             const watch = resolvedConfig.command === 'build' && Boolean(resolvedConfig.build.watch);
-            kind ??= options.kind ?? null;
             if (!kind) {
                 log('识别不到被测类型，跳过链接与校验', 'warn');
                 return;

package/dist/siyuan/kinds.d.ts

@@ -17,7 +17,7 @@ export interface KindSpec {
 }
 export declare function kindSpec(kind: Kind): KindSpec;
 /**
- * 从项目目录推断类型：看 public/、dist/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 public/ 或项目根存在哪份清单。
  * 同时存在多种时必须让人指定——装错类型的产物名会静默加载不到。
  */
 export declare function detectKind(root: string): Kind;

package/dist/siyuan/kinds.js

@@ -33,7 +33,7 @@ export function kindSpec(kind) {
 }
 const KIND_NAMES = ['theme', 'plugin'];
 /**
- * 从项目目录推断类型：看 public/、dist/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 public/ 或项目根存在哪份清单。
  * 同时存在多种时必须让人指定——装错类型的产物名会静默加载不到。
  */
 export function detectKind(root) {
@@ -42,7 +42,7 @@ export function detectKind(root) {
     if (matches.length === 1 && only !== undefined)
         return only;
     throw new UserError(matches.length === 0
-        ? `在 ${root} 的 public/、dist/ 或项目根下找不到 theme.json / plugin.json；请用 kind 选项显式指定类型`
+        ? `在 ${root} 的 public/ 或项目根下找不到 theme.json / plugin.json；请用 kind 选项显式指定类型`
         : `同时匹配到多种类型：${matches.join('、')}；请用 kind 选项显式指定`);
 }
 /** 读被测对象的名字；读不到抛可读错误，不猜默认值。 */

package/dist/siyuan/manifest.js

@@ -1,15 +1,16 @@
 /**
  * 清单文件的读取。
  *
- * 清单可能出现在三处：`public/`（源码）、`dist/`（构建产物）、项目根
- * （解包后的 `package.zip` 就是这种布局）。
+ * 清单可能出现在两处：`public/`（源码）或项目根（官方 sample 的布局）。
+ * 构建产物里的清单由调用方通过 `extraDirs` 显式传入，不作为默认候选——
+ * 否则上一次构建留下的 `dist/theme.json` 会盖住源码里的新清单。
  */
 import { join } from 'node:path';
 import { readJsonFile } from '../support/fs.js';
 import { isRecord } from '../support/guards.js';
 /** 清单候选路径，按优先级排列。 */
 export function manifestCandidates(root, manifest, extraDirs = []) {
-    const dirs = [join(root, 'public'), join(root, 'dist'), root, ...extraDirs];
+    const dirs = [join(root, 'public'), root, ...extraDirs];
     return dirs.map((dir) => join(dir, manifest));
 }
 /** 读一份清单与其路径；都读不到返回 null。 */

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "vite-plugin-siyuan",
-  "version": "0.1.0",
-  "description": "Vite plugin for SiYuan theme/plugin development: config injection, link to workspace, hot reload, verify and package",
-  "keywords": [
-    "siyuan",
-    "siyuan-theme",
-    "siyuan-plugin",
-    "vite-plugin",
-    "hot-reload"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.18.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.build.json",
-    "type-check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "check": "pnpm run type-check && pnpm run test"
-  },
-  "dependencies": {
-    "consola": "^3.4.2",
-    "fflate": "^0.8.3",
-    "ps-list": "^9.0.0",
-    "semver": "^7.8.6",
-    "zod": "^4.6.7"
-  },
-  "peerDependencies": {
-    "vite": ">=6"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.6",
-    "@types/semver": "^7.8.0",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.5",
-    "vitest": "^5.0.5"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/svchord/vite-plugin-siyuan.git"
-  },
-  "author": "svchord",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "vite-plugin-siyuan",
+  "version": "0.2.0",
+  "description": "Vite plugin for SiYuan theme/plugin development: config injection, link to workspace, hot reload, verify and package",
+  "keywords": [
+    "siyuan",
+    "siyuan-theme",
+    "siyuan-plugin",
+    "vite-plugin",
+    "hot-reload"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "consola": "^3.4.2",
+    "fflate": "^0.8.3",
+    "ps-list": "^9.0.0",
+    "semver": "^7.8.6",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/semver": "^7.8.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svchord/vite-plugin-siyuan.git"
+  },
+  "author": "svchord",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run type-check && pnpm run test"
+  }
+}