@vobs/cli 1.7.4 → 1.7.7

package/dist/utils/file.d.ts

@@ -8,7 +8,7 @@ declare function writeFile(dir: string, filename: string, content: string): void
 declare function ensureDir(dir: string): void;
 /** Check if a path exists */
 declare function pathExists(path: string): boolean;
-/** Scaffold a project from the basic template */
-declare function scaffoldProject(targetDir: string, context: Record<string, unknown>): Promise<void>;
+/** Scaffold a project from a named template under `src/templates`. */
+declare function scaffoldProject(targetDir: string, context: Record<string, unknown>, template?: string): Promise<void>;
 
 export { ensureDir, getTemplatesDir, pathExists, renderTemplate, scaffoldProject, writeFile };

package/dist/utils/file.js

@@ -56,8 +56,11 @@ async function copyDirRecursive(srcDir, destDir, context) {
   }
 }
 __name(copyDirRecursive, "copyDirRecursive");
-async function scaffoldProject(targetDir, context) {
-  const templateDir = resolve(TEMPLATES_ROOT, "basic");
+async function scaffoldProject(targetDir, context, template = "basic") {
+  const templateDir = resolve(TEMPLATES_ROOT, template);
+  if (!existsSync(templateDir)) {
+    throw new Error(`\u6A21\u677F\u4E0D\u5B58\u5728: ${template}\uFF08\u53EF\u7528\u6A21\u677F\u89C1 ${TEMPLATES_ROOT}\uFF09`);
+  }
   ensureDir(targetDir);
   await copyDirRecursive(templateDir, targetDir, context);
 }

package/dist/utils/file.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/file.ts"],"sourcesContent":["import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport Handlebars from 'handlebars'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\nconst TEMPLATES_ROOT = resolve(__dirname, '..', 'templates')\n\n/** Get the absolute path to the templates directory */\nexport function getTemplatesDir(): string {\n  return TEMPLATES_ROOT\n}\n\n/** Read a template file and compile it with Handlebars */\nexport function renderTemplate(\n  templatePath: string,\n  context: Record<string, unknown>\n): string {\n  const source = readFileSync(templatePath, 'utf-8')\n  const template = Handlebars.compile(source)\n  return template(context)\n}\n\n/** Write a file, creating parent directories if needed */\nexport function writeFile(dir: string, filename: string, content: string): void {\n  const filePath = resolve(dir, filename)\n  mkdirSync(dirname(filePath), { recursive: true })\n  writeFileSync(filePath, content, 'utf-8')\n}\n\n/** Ensure a directory exists */\nexport function ensureDir(dir: string): void {\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true })\n  }\n}\n\n/** Check if a path exists */\nexport function pathExists(path: string): boolean {\n  return existsSync(path)\n}\n\n/** Copy a template directory recursively, rendering each .hbs file */\nasync function copyDirRecursive(srcDir: string, destDir: string, context: Record<string, unknown>): Promise<void> {\n  const { readdirSync } = await import('node:fs')\n  const { join } = await import('node:path')\n\n  const entries = readdirSync(srcDir, { withFileTypes: true })\n\n  for (const entry of entries) {\n    const srcPath = join(srcDir, entry.name)\n    const isHbs = entry.name.endsWith('.hbs')\n    const destName = isHbs ? entry.name.slice(0, -4) : entry.name\n    const destPath = join(destDir, destName)\n\n    if (entry.isDirectory()) {\n      ensureDir(destPath)\n      await copyDirRecursive(srcPath, destPath, context)\n    } else if (isHbs) {\n      const content = renderTemplate(srcPath, context)\n      writeFile(destDir, destName, content)\n    } else {\n      const content = readFileSync(srcPath, 'utf-8')\n      writeFile(destDir, destName, content)\n    }\n  }\n}\n\n/** Scaffold a project from the basic template */\nexport async function scaffoldProject(\n  targetDir: string,\n  context: Record<string, unknown>\n): Promise<void> {\n  const templateDir = resolve(TEMPLATES_ROOT, 'basic')\n  ensureDir(targetDir)\n  await copyDirRecursive(templateDir, targetDir, context)\n}"],"mappings":";;;;AAAA,SAAS,YAAY,WAAW,eAAe,oBAAoB;AACnE,SAAS,SAAS,eAAe;AACjC,SAAS,qBAAqB;AAC9B,OAAO,gBAAgB;AAEvB,IAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AACxD,IAAM,iBAAiB,QAAQ,WAAW,MAAM,WAAW;AAGpD,SAAS,kBAA0B;AACxC,SAAO;AACT;AAFgB;AAKT,SAAS,eACd,cACA,SACQ;AACR,QAAM,SAAS,aAAa,cAAc,OAAO;AACjD,QAAM,WAAW,WAAW,QAAQ,MAAM;AAC1C,SAAO,SAAS,OAAO;AACzB;AAPgB;AAUT,SAAS,UAAU,KAAa,UAAkB,SAAuB;AAC9E,QAAM,WAAW,QAAQ,KAAK,QAAQ;AACtC,YAAU,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAChD,gBAAc,UAAU,SAAS,OAAO;AAC1C;AAJgB;AAOT,SAAS,UAAU,KAAmB;AAC3C,MAAI,CAAC,WAAW,GAAG,GAAG;AACpB,cAAU,KAAK,EAAE,WAAW,KAAK,CAAC;AAAA,EACpC;AACF;AAJgB;AAOT,SAAS,WAAW,MAAuB;AAChD,SAAO,WAAW,IAAI;AACxB;AAFgB;AAKhB,eAAe,iBAAiB,QAAgB,SAAiB,SAAiD;AAChH,QAAM,EAAE,YAAY,IAAI,MAAM,OAAO,IAAS;AAC9C,QAAM,EAAE,KAAK,IAAI,MAAM,OAAO,MAAW;AAEzC,QAAM,UAAU,YAAY,QAAQ,EAAE,eAAe,KAAK,CAAC;AAE3D,aAAW,SAAS,SAAS;AAC3B,UAAM,UAAU,KAAK,QAAQ,MAAM,IAAI;AACvC,UAAM,QAAQ,MAAM,KAAK,SAAS,MAAM;AACxC,UAAM,WAAW,QAAQ,MAAM,KAAK,MAAM,GAAG,EAAE,IAAI,MAAM;AACzD,UAAM,WAAW,KAAK,SAAS,QAAQ;AAEvC,QAAI,MAAM,YAAY,GAAG;AACvB,gBAAU,QAAQ;AAClB,YAAM,iBAAiB,SAAS,UAAU,OAAO;AAAA,IACnD,WAAW,OAAO;AAChB,YAAM,UAAU,eAAe,SAAS,OAAO;AAC/C,gBAAU,SAAS,UAAU,OAAO;AAAA,IACtC,OAAO;AACL,YAAM,UAAU,aAAa,SAAS,OAAO;AAC7C,gBAAU,SAAS,UAAU,OAAO;AAAA,IACtC;AAAA,EACF;AACF;AAvBe;AA0Bf,eAAsB,gBACpB,WACA,SACe;AACf,QAAM,cAAc,QAAQ,gBAAgB,OAAO;AACnD,YAAU,SAAS;AACnB,QAAM,iBAAiB,aAAa,WAAW,OAAO;AACxD;AAPsB;","names":[]}
+{"version":3,"sources":["../../src/utils/file.ts"],"sourcesContent":["import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport Handlebars from 'handlebars'\n\nconst __dirname = dirname(fileURLToPath(import.meta.url))\nconst TEMPLATES_ROOT = resolve(__dirname, '..', 'templates')\n\n/** Get the absolute path to the templates directory */\nexport function getTemplatesDir(): string {\n  return TEMPLATES_ROOT\n}\n\n/** Read a template file and compile it with Handlebars */\nexport function renderTemplate(\n  templatePath: string,\n  context: Record<string, unknown>\n): string {\n  const source = readFileSync(templatePath, 'utf-8')\n  const template = Handlebars.compile(source)\n  return template(context)\n}\n\n/** Write a file, creating parent directories if needed */\nexport function writeFile(dir: string, filename: string, content: string): void {\n  const filePath = resolve(dir, filename)\n  mkdirSync(dirname(filePath), { recursive: true })\n  writeFileSync(filePath, content, 'utf-8')\n}\n\n/** Ensure a directory exists */\nexport function ensureDir(dir: string): void {\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true })\n  }\n}\n\n/** Check if a path exists */\nexport function pathExists(path: string): boolean {\n  return existsSync(path)\n}\n\n/** Copy a template directory recursively, rendering each .hbs file */\nasync function copyDirRecursive(srcDir: string, destDir: string, context: Record<string, unknown>): Promise<void> {\n  const { readdirSync } = await import('node:fs')\n  const { join } = await import('node:path')\n\n  const entries = readdirSync(srcDir, { withFileTypes: true })\n\n  for (const entry of entries) {\n    const srcPath = join(srcDir, entry.name)\n    const isHbs = entry.name.endsWith('.hbs')\n    const destName = isHbs ? entry.name.slice(0, -4) : entry.name\n    const destPath = join(destDir, destName)\n\n    if (entry.isDirectory()) {\n      ensureDir(destPath)\n      await copyDirRecursive(srcPath, destPath, context)\n    } else if (isHbs) {\n      const content = renderTemplate(srcPath, context)\n      writeFile(destDir, destName, content)\n    } else {\n      const content = readFileSync(srcPath, 'utf-8')\n      writeFile(destDir, destName, content)\n    }\n  }\n}\n\n/** Scaffold a project from a named template under `src/templates`. */\nexport async function scaffoldProject(\n  targetDir: string,\n  context: Record<string, unknown>,\n  template = 'basic'\n): Promise<void> {\n  const templateDir = resolve(TEMPLATES_ROOT, template)\n  if (!existsSync(templateDir)) {\n    throw new Error(`模板不存在: ${template}（可用模板见 ${TEMPLATES_ROOT}）`)\n  }\n  ensureDir(targetDir)\n  await copyDirRecursive(templateDir, targetDir, context)\n}"],"mappings":";;;;AAAA,SAAS,YAAY,WAAW,eAAe,oBAAoB;AACnE,SAAS,SAAS,eAAe;AACjC,SAAS,qBAAqB;AAC9B,OAAO,gBAAgB;AAEvB,IAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AACxD,IAAM,iBAAiB,QAAQ,WAAW,MAAM,WAAW;AAGpD,SAAS,kBAA0B;AACxC,SAAO;AACT;AAFgB;AAKT,SAAS,eACd,cACA,SACQ;AACR,QAAM,SAAS,aAAa,cAAc,OAAO;AACjD,QAAM,WAAW,WAAW,QAAQ,MAAM;AAC1C,SAAO,SAAS,OAAO;AACzB;AAPgB;AAUT,SAAS,UAAU,KAAa,UAAkB,SAAuB;AAC9E,QAAM,WAAW,QAAQ,KAAK,QAAQ;AACtC,YAAU,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAChD,gBAAc,UAAU,SAAS,OAAO;AAC1C;AAJgB;AAOT,SAAS,UAAU,KAAmB;AAC3C,MAAI,CAAC,WAAW,GAAG,GAAG;AACpB,cAAU,KAAK,EAAE,WAAW,KAAK,CAAC;AAAA,EACpC;AACF;AAJgB;AAOT,SAAS,WAAW,MAAuB;AAChD,SAAO,WAAW,IAAI;AACxB;AAFgB;AAKhB,eAAe,iBAAiB,QAAgB,SAAiB,SAAiD;AAChH,QAAM,EAAE,YAAY,IAAI,MAAM,OAAO,IAAS;AAC9C,QAAM,EAAE,KAAK,IAAI,MAAM,OAAO,MAAW;AAEzC,QAAM,UAAU,YAAY,QAAQ,EAAE,eAAe,KAAK,CAAC;AAE3D,aAAW,SAAS,SAAS;AAC3B,UAAM,UAAU,KAAK,QAAQ,MAAM,IAAI;AACvC,UAAM,QAAQ,MAAM,KAAK,SAAS,MAAM;AACxC,UAAM,WAAW,QAAQ,MAAM,KAAK,MAAM,GAAG,EAAE,IAAI,MAAM;AACzD,UAAM,WAAW,KAAK,SAAS,QAAQ;AAEvC,QAAI,MAAM,YAAY,GAAG;AACvB,gBAAU,QAAQ;AAClB,YAAM,iBAAiB,SAAS,UAAU,OAAO;AAAA,IACnD,WAAW,OAAO;AAChB,YAAM,UAAU,eAAe,SAAS,OAAO;AAC/C,gBAAU,SAAS,UAAU,OAAO;AAAA,IACtC,OAAO;AACL,YAAM,UAAU,aAAa,SAAS,OAAO;AAC7C,gBAAU,SAAS,UAAU,OAAO;AAAA,IACtC;AAAA,EACF;AACF;AAvBe;AA0Bf,eAAsB,gBACpB,WACA,SACA,WAAW,SACI;AACf,QAAM,cAAc,QAAQ,gBAAgB,QAAQ;AACpD,MAAI,CAAC,WAAW,WAAW,GAAG;AAC5B,UAAM,IAAI,MAAM,mCAAU,QAAQ,wCAAU,cAAc,QAAG;AAAA,EAC/D;AACA,YAAU,SAAS;AACnB,QAAM,iBAAiB,aAAa,WAAW,OAAO;AACxD;AAXsB;","names":[]}

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/vobsjs/vobs.git"
   },
-  "version": "1.7.4",
+  "version": "1.7.7",
   "publishConfig": {
     "access": "public"
   },

package/src/cli.ts

@@ -4,6 +4,7 @@ import { devCommand } from './commands/dev.js'
 import { buildCommand } from './commands/build.js'
 import { generateCommand } from './commands/generate.js'
 import { addCommand } from './commands/add.js'
+import { dshCommand } from './commands/dsh.js'
 import { showBanner, showLogo, showDevBanner } from './banner.js'
 
 export function createCLI(): ReturnType<typeof cac> {
@@ -91,6 +92,33 @@ export function createCLI(): ReturnType<typeof cac> {
       })
     })
 
+  cli
+    .command('dsh <action> [target]', 'DSH 插件工具链（init / dev / build / check / install）')
+    .option('--dir <dir>', 'init：目标目录')
+    .option('--pm <pm>', 'init：包管理器（pnpm/npm）')
+    .option('--port <port>', 'dev：预览端口', { default: 5199 })
+    .option('--profile <name>', 'install：DSH profile 名', { default: 'desktop' })
+    .option('--spec <spec>', 'install：完整安装 spec')
+    .option('--repo <owner/name>', 'install：GitHub owner/name')
+    .option('--tag <ref>', 'install：Git tag / 分支 / commit')
+    .option('--subpath <path>', 'install：仓库内子目录')
+    .option('--from <path>', 'install：从本地目录安装')
+    .option('--dry', 'install：只打印命令，不执行')
+    .action(async (action: string, target: string | undefined, options: Record<string, unknown>) => {
+      await dshCommand(action, target, {
+        dir: options.dir as string | undefined,
+        pm: options.pm as 'pnpm' | 'npm' | undefined,
+        profile: options.profile as string | undefined,
+        spec: options.spec as string | undefined,
+        repo: options.repo as string | undefined,
+        tag: options.tag as string | undefined,
+        subpath: options.subpath as string | undefined,
+        from: options.from as string | undefined,
+        dry: options.dry === true,
+        port: options.port === undefined ? undefined : Number(options.port)
+      })
+    })
+
   cli
     .command('logo', 'Show the vobs CLI logo and version info')
     .action(() => {

package/src/commands/dsh.test.ts

@@ -0,0 +1,279 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { buildInstallSpec, buildPreviewHtml, buildShellCommand, collectIssues, resolveExport } from './dsh.js'
+
+/* ---------------------------------------------------------------- 夹具 */
+
+const tempDirs: string[] = []
+
+function makeProject(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'vobs-dsh-check-'))
+  tempDirs.push(dir)
+  for (const [relative, content] of Object.entries(files)) {
+    const target = join(dir, relative)
+    mkdirSync(join(target, '..'), { recursive: true })
+    writeFileSync(target, content, 'utf8')
+  }
+  return dir
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) rmSync(tempDirs.pop() as string, { recursive: true, force: true })
+})
+
+/** 一个各处都合法的插件项目。 */
+function healthyProject(overrides: Record<string, string> = {}): Record<string, string> {
+  return {
+    'package.json': JSON.stringify(
+      {
+        name: 'dsh-plugin-demo',
+        version: '0.1.0',
+        type: 'module',
+        main: './lib/index.js',
+        exports: {
+          '.': './lib/index.js',
+          './client': './lib/client.js',
+          './cordis.patch.yml': './cordis.patch.yml',
+          './package.json': './package.json'
+        },
+        dsh: {
+          manifestVersion: 1,
+          bundle: { patch: './cordis.patch.yml' },
+          client: { platform: 'web' }
+        }
+      },
+      null,
+      2
+    ),
+    'cordis.patch.yml': "- insert:\n    - id: dsh-plugin-demo\n      name: dsh-plugin-demo\n",
+    'lib/index.js': 'export const name = "dsh-plugin-demo"\nexport function apply() {}\n',
+    'lib/client.js':
+      '// generated\nwindow.__ModuleLoader__.load({id:"dsh-plugin-demo",factory:function(require){\n' +
+      '"use strict";var module={exports:{}};var exports=module.exports;\n' +
+      'globalThis["__VOBS_DSH_REACT__"]=require("react");\nmodule.exports={};\n}});\n',
+    ...overrides
+  }
+}
+
+/* ------------------------------------------------------------ collectIssues */
+
+describe('collectIssues', () => {
+  it('健康项目零错误', () => {
+    const result = collectIssues(makeProject(healthyProject()))
+    expect(result.errors).toEqual([])
+    expect(result.passed.length).toBeGreaterThan(4)
+  })
+
+  it('缺 dsh.bundle.patch 直接判错', () => {
+    const dir = makeProject(
+      healthyProject({
+        'package.json': JSON.stringify({ name: 'p', version: '1.0.0', exports: {} })
+      })
+    )
+    const result = collectIssues(dir)
+    expect(result.errors.join('\n')).toContain('dsh.bundle.patch')
+  })
+
+  it('patch 文件不存在判错', () => {
+    const manifest = JSON.parse(healthyProject()['package.json'] as string) as Record<string, unknown>
+    ;(manifest.dsh as Record<string, unknown>).bundle = { patch: './missing.yml' }
+    const result = collectIssues(makeProject(healthyProject({ 'package.json': JSON.stringify(manifest) })))
+    expect(result.errors.join('\n')).toContain('missing.yml')
+  })
+
+  it('patch 里没有 insert 判错', () => {
+    const result = collectIssues(makeProject(healthyProject({ 'cordis.patch.yml': '- id: other\n' })))
+    expect(result.errors.join('\n')).toContain('insert')
+  })
+
+  it('platform 不是 web 判错', () => {
+    const manifest = JSON.parse(healthyProject()['package.json'] as string) as Record<string, unknown>
+    ;(manifest.dsh as Record<string, unknown>).client = { platform: 'node' }
+    const result = collectIssues(makeProject(healthyProject({ 'package.json': JSON.stringify(manifest) })))
+    expect(result.errors.join('\n')).toContain('web')
+  })
+
+  it('声明了 prepare 判错（DSH 安装时不构建）', () => {
+    const manifest = JSON.parse(healthyProject()['package.json'] as string) as Record<string, unknown>
+    manifest.scripts = { prepare: 'vite build' }
+    const result = collectIssues(makeProject(healthyProject({ 'package.json': JSON.stringify(manifest) })))
+    expect(result.errors.join('\n')).toContain('prepare')
+  })
+
+  it('依赖里出现 workspace: 判错（Git 子目录直装解析不了）', () => {
+    const manifest = JSON.parse(healthyProject()['package.json'] as string) as Record<string, unknown>
+    manifest.devDependencies = { '@vobs/vobs': 'workspace:*' }
+    const result = collectIssues(makeProject(healthyProject({ 'package.json': JSON.stringify(manifest) })))
+    expect(result.errors.join('\n')).toContain('workspace:')
+  })
+
+  it('客户端产物缺失判错', () => {
+    const files = healthyProject()
+    delete files['lib/client.js']
+    const result = collectIssues(makeProject(files))
+    expect(result.errors.join('\n')).toContain('客户端产物')
+  })
+
+  it('产物里出现动态 import 判错', () => {
+    const code = `${healthyProject()['lib/client.js'] as string}\nconst load = () => import("./chunk.js")\n`
+    const result = collectIssues(makeProject(healthyProject({ 'lib/client.js': code })))
+    expect(result.errors.join('\n')).toContain('动态 import')
+  })
+
+  it('产物 require 了非平台模块判错', () => {
+    const code = (healthyProject()['lib/client.js'] as string).replace('require("react")', 'require("lodash")')
+    const result = collectIssues(makeProject(healthyProject({ 'lib/client.js': code })))
+    expect(result.errors.join('\n')).toContain('lodash')
+  })
+
+  it('__ModuleLoader__.load 出现多次判错', () => {
+    const code = `${healthyProject()['lib/client.js'] as string}\nwindow.__ModuleLoader__.load({id:"x",factory(){}});\n`
+    const result = collectIssues(makeProject(healthyProject({ 'lib/client.js': code })))
+    expect(result.errors.join('\n')).toContain('2 次')
+  })
+
+  it('模块 id 与包名不一致只给警告', () => {
+    const code = (healthyProject()['lib/client.js'] as string).replace(/"dsh-plugin-demo"/u, '"wrong-id"')
+    const result = collectIssues(makeProject(healthyProject({ 'lib/client.js': code })))
+    expect(result.errors).toEqual([])
+    expect(result.warnings.join('\n')).toContain('模块 id')
+  })
+
+  it('package.json 语法错误时给出明确错误', () => {
+    const result = collectIssues(makeProject({ 'package.json': '{ not json' }))
+    expect(result.errors[0]).toContain('package.json')
+  })
+})
+
+/* --------------------------------------------------------- buildInstallSpec */
+
+describe('buildInstallSpec', () => {
+  it('显式 spec 原样透传', () => {
+    expect(buildInstallSpec({ spec: 'github:a/b#v1&path:/x' }).spec).toBe('github:a/b#v1&path:/x')
+  })
+
+  it('repo 无 tag 无子目录', () => {
+    expect(buildInstallSpec({ repo: 'vobsjs/vobs' }).spec).toBe('github:vobsjs/vobs')
+  })
+
+  it('repo + tag', () => {
+    expect(buildInstallSpec({ repo: 'vobsjs/vobs', tag: 'v1.7.6' }).spec).toBe('github:vobsjs/vobs#v1.7.6')
+  })
+
+  it('repo + tag + 子目录用 & 连接', () => {
+    expect(buildInstallSpec({ repo: 'vobsjs/vobs', tag: 'v1.7.6', subpath: '/packages/dsh-console' }).spec).toBe(
+      'github:vobsjs/vobs#v1.7.6&path:/packages/dsh-console'
+    )
+  })
+
+  it('repo + 只有子目录时用 # 起头', () => {
+    expect(buildInstallSpec({ repo: 'vobsjs/vobs', subpath: '/packages/dsh-plugin' }).spec).toBe(
+      'github:vobsjs/vobs#path:/packages/dsh-plugin'
+    )
+  })
+
+  it('--from 解析成绝对路径', () => {
+    const result = buildInstallSpec({ from: '.' })
+    expect(result.error).toBeUndefined()
+    expect(result.spec?.includes(':')).toBe(true)
+  })
+
+  it('--from 指向不存在的路径时报错', () => {
+    const result = buildInstallSpec({ from: './definitely-not-here-xyz' })
+    expect(result.error).toContain('不存在')
+  })
+
+  it('什么都不给时报错并说明可选参数', () => {
+    const result = buildInstallSpec({})
+    expect(result.error).toContain('--spec')
+  })
+})
+
+/* ---------------------------------------------------------- buildShellCommand */
+
+describe('buildShellCommand', () => {
+  it('给含 & 的 spec 加引号，否则 cmd 会把它当命令分隔符', () => {
+    const command = buildShellCommand('dsh', [
+      'plugin',
+      '--profile',
+      'desktop',
+      'add',
+      'github:vobsjs/vobs#v1.7.6&path:/packages/dsh-console'
+    ])
+    expect(command).toBe(
+      'dsh plugin --profile desktop add "github:vobsjs/vobs#v1.7.6&path:/packages/dsh-console"'
+    )
+  })
+
+  it('普通参数不加多余引号', () => {
+    expect(buildShellCommand('dsh', ['plugin', '--profile', 'desktop'])).toBe('dsh plugin --profile desktop')
+  })
+
+  it('含空格的参数加引号', () => {
+    expect(buildShellCommand('dsh', ['add', 'C:/my plugins/demo'])).toBe('dsh add "C:/my plugins/demo"')
+  })
+
+  it('参数内的双引号按 cmd 规则翻倍', () => {
+    expect(buildShellCommand('dsh', ['add', 'a"b'])).toBe('dsh add "a""b"')
+  })
+})
+
+/* ------------------------------------------------------------ dev 预览页 */
+
+describe('buildPreviewHtml', () => {
+  const html = buildPreviewHtml({ packageName: 'dsh-plugin-demo' })
+
+  it('在插件 bundle 之前装 __ModuleLoader__ 垫片', () => {
+    const shimAt = html.indexOf('window.__ModuleLoader__')
+    const bundleAt = html.indexOf('<script src="/client.js">')
+    expect(shimAt).toBeGreaterThan(-1)
+    expect(bundleAt).toBeGreaterThan(shimAt)
+  })
+
+  it('垫片把 factory 收进注册表而不是执行它', () => {
+    expect(html).toContain('factories.set(entry.id, entry.factory)')
+  })
+
+  it('用 startPreview 启动并传入包名', () => {
+    expect(html).toContain("from '/preview.js'")
+    expect(html).toContain('packageName: "dsh-plugin-demo"')
+  })
+
+  it('订阅 SSE 以便重建后自动刷新', () => {
+    expect(html).toContain("new EventSource('/events')")
+    expect(html).toContain('location.reload()')
+  })
+
+  it('包名被转义，含 </script> 也不会突破 script 标签', () => {
+    const injected = buildPreviewHtml({ packageName: '</script><script>alert(1)</script>' })
+    expect(injected).toContain('packageName: "\\u003c/script>')
+    expect(injected).not.toContain('</script><script>alert(1)')
+  })
+
+  it('标题里的 HTML 元字符被剔除', () => {
+    const html = buildPreviewHtml({ packageName: 'p', title: '<img src=x onerror=alert(1)>' })
+    expect(html).toContain('<title>vobs preview · img src=x onerror=alert(1)</title>')
+    expect(html).not.toContain('<img')
+  })
+})
+
+describe('resolveExport', () => {
+  it('字符串写法直接返回', () => {
+    expect(resolveExport({ exports: { './client': './lib/client.js' } }, './client')).toBe('./lib/client.js')
+  })
+
+  it('条件对象按 default / import / require 顺序取', () => {
+    expect(resolveExport({ exports: { './client': { import: './lib/client.mjs' } } }, './client')).toBe('./lib/client.mjs')
+    expect(resolveExport({ exports: { './client': { require: './lib/client.cjs' } } }, './client')).toBe('./lib/client.cjs')
+    expect(
+      resolveExport({ exports: { './client': { types: './x.d.ts', default: './lib/client.js' } } }, './client')
+    ).toBe('./lib/client.js')
+  })
+
+  it('缺失时返回 undefined', () => {
+    expect(resolveExport({ exports: {} }, './client')).toBeUndefined()
+    expect(resolveExport({}, './client')).toBeUndefined()
+  })
+})