dsh-ppt-studio 1.1.0

package/scripts/verify-bundle-install.mjs

@@ -0,0 +1,281 @@
+/**
+ * profile bundle 安装自证（2026-09-14 新增）——回答"能不能用 `dsh plugin add` 装"这个问题的**真机证据**。
+ *
+ * 做法：**完全隔离**（DSH_HOME 指向临时目录，不碰用户的 profiles）→ 打包本仓库 → 在临时 profile 里跑
+ * 真实的 `dsh plugin --profile web add <tgz>` → 断言三件事：
+ *   ① profile 的 package.json 里出现本包依赖；
+ *   ② `dsh.profile.bundles` **自动**把本包收进层栈（这正是 dsh.bundle.patch 声明的作用）；
+ *   ③ `dsh --profile web --dump-config` 的组合树里能看到我们的插件行（id: ppt-studio）；
+ *   ④ **升级路径**（2026-09-15 加）：同版本号、内容不同的第二个 tgz 再 add 一次 → 必须真换成新字节，
+ *      且依赖规格改指新包、bundles 不丢、dump-config 仍见本行——"以后更新还顺不顺"的可复跑证据。
+ *   ⑤ **--local 迭代模式**（2026-09-18 加）：同一个隔离 DSH_HOME 里跑 `release-sync --local` →
+ *      断言全程无上传、状态文件 mode=local、profile 规格变成指向本地稳定构件的 `file:`，
+ *      且**挂载副本的 lib/index.js 与仓库刚构建的逐字节相同**——"日常迭代不发版，但本机跑的就是最新"的证据。
+ *
+ * 依赖 `dsh` 与 pnpm 在 PATH 上；缺失则跳过（打印警告，退出码 0，避免把它变成脆弱门禁）。
+ * 用法：
+ *   node scripts/verify-bundle-install.mjs                 # 自己 npm pack（本地 tgz）
+ *   node scripts/verify-bundle-install.mjs <tgz 路径>       # 用指定 tgz
+ *   node scripts/verify-bundle-install.mjs <https://…tgz>   # **验"用户会敲的那条命令"**（GitHub 资产 URL）
+ */
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readFileSync, existsSync, mkdirSync, rmSync, cpSync, appendFileSync, readdirSync, writeFileSync, lstatSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { tmpdir, homedir } from 'node:os'
+import YAML from 'yaml'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const NAME = pkg.name
+
+let pass = 0
+let fail = 0
+const check = (label, ok, extra = '') => {
+  console.log(`${ok ? '✓' : '✗'} ${label}${extra ? ' — ' + extra : ''}`)
+  ok ? pass++ : fail++
+}
+const run = (cmd, args, opts = {}) => spawnSync(cmd, args, { encoding: 'utf8', shell: process.platform === 'win32', ...opts })
+
+// 前置：dsh / pnpm 可用性
+const dshV = run('dsh', ['--version'])
+if (dshV.status !== 0) {
+  console.log('⚠ 跳过：PATH 上没有 `dsh`（本脚本验证的是真实 launcher 行为，必须在装有 DSH 的机器上跑）')
+  process.exit(0)
+}
+const pnpmV = run('pnpm', ['--version'])
+if (pnpmV.status !== 0) {
+  console.log('⚠ 跳过：PATH 上没有 `pnpm`（`dsh plugin` 是 pnpm 转发器）')
+  process.exit(0)
+}
+
+const work = join(tmpdir(), `dsh-ppt-bundle-${Date.now()}`)
+mkdirSync(work, { recursive: true })
+const home = join(work, 'home')
+mkdirSync(home, { recursive: true })
+
+try {
+  // 1) 安装规格：http(s) URL = 用户会敲的那条命令；路径 = 本地 tgz；都不给就自己打包
+  let tgz = process.argv[2]
+  const isUrl = typeof tgz === 'string' && /^https?:\/\//.test(tgz)
+  if (isUrl) {
+    check('使用远端 URL 规格（等价于用户实际执行的命令）', true, tgz)
+  } else if (!tgz) {
+    const pack = run('npm', ['pack', '--pack-destination', work], { cwd: root })
+    const name = (pack.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop()
+    tgz = join(work, name)
+    check('打包成功（npm pack）', existsSync(tgz), name ?? '(无输出)')
+  } else {
+    check('使用传入的 tgz', existsSync(tgz), tgz)
+  }
+
+  // 2) 隔离 DSH_HOME 下真实安装
+  const env = { ...process.env, DSH_HOME: home }
+  const add = run('dsh', ['plugin', '--profile', 'web', 'add', tgz], { env, cwd: work })
+  const out = `${add.stdout ?? ''}\n${add.stderr ?? ''}`
+  check('`dsh plugin --profile web add <tgz>` 退出码 0', add.status === 0, out.trim().split(/\r?\n/).slice(-3).join(' | ').slice(0, 200))
+  check('**没有** "declares no dsh.bundle" 警告（证明 dsh.bundle.patch 被认到）', !/declares no dsh\.bundle/.test(out),
+    /declares no dsh\.bundle/.test(out) ? '仍被判为普通依赖（dsh.bundle 声明没生效）' : '已按 bundle 处理')
+
+  // 3) profile 清单：依赖 + bundles 自动入栈
+  const profPkg = join(home, 'profiles', 'web', 'package.json')
+  check('profile 目录已生成 package.json', existsSync(profPkg), profPkg)
+  const prof = existsSync(profPkg) ? JSON.parse(readFileSync(profPkg, 'utf8')) : {}
+  const bundles = prof.dsh?.profile?.bundles ?? []
+  check('本包已在 profile 依赖里', Boolean(prof.dependencies?.[NAME]), JSON.stringify(prof.dependencies?.[NAME] ?? null))
+  check('本包已**自动**进入 dsh.profile.bundles（层栈）', bundles.includes(NAME),
+    bundles.length ? `bundles = ${bundles.join(', ')}` : '(bundles 为空)')
+  check('包已物化到 profile 的 node_modules', existsSync(join(home, 'profiles', 'web', 'node_modules', NAME, 'cordis.patch.yml')),
+    join('node_modules', NAME, 'cordis.patch.yml'))
+  // 新鲜度：装到的必须是**当前仓库这一版**（防 pnpm/pnpm store 命中旧缓存，让"验证"变成假通过）
+  const installedPkg = join(home, 'profiles', 'web', 'node_modules', NAME, 'package.json')
+  const installedHasProbe = existsSync(join(home, 'profiles', 'web', 'node_modules', NAME, 'scripts', 'probe-effect-semantics.mjs'))
+  const installedVer = existsSync(installedPkg) ? JSON.parse(readFileSync(installedPkg, 'utf8')).version : null
+  check('装到的是当前版本（不是缓存里的旧包：新增的 probe 脚本在位）',
+    installedVer === pkg.version && installedHasProbe,
+    `安装版本=${installedVer ?? '(缺)'}｜仓库版本=${pkg.version}｜probe 脚本=${installedHasProbe}`)
+
+  // 4) 组合树里能看到我们的行
+  const dump = run('dsh', ['--profile', 'web', '--dump-config'], { env, cwd: work })
+  const tree = `${dump.stdout ?? ''}\n${dump.stderr ?? ''}`
+  check('`dsh --profile web --dump-config` 能跑通', dump.status === 0, `exit=${dump.status}`)
+  check('组合树里出现 ppt-studio 插件行（bundle patch 生效）', /ppt-studio/.test(tree),
+    (tree.match(/^.*ppt-studio.*$/m) ?? ['(未出现)'])[0].trim().slice(0, 120))
+
+  // 5) **升级路径自证**（2026-09-15：用户问"后续更新还顺不顺"——这条把承诺变成可复跑证据）
+  // 形状：同一版本号、内容不同的第二个 tgz（新规格 ⇒ 包管理器必然重新解析，与"资产名带构建戳"同一机制）。
+  // 断言三件事：add 成功 / 装到的字节是第二份（真升级，不是缓存复用）/ 升级后装配不丢（依赖规格改指新包、
+  // bundles 仍在、dump-config 仍见 ppt-studio 行）。只验"版本号变化"是不够的——历史事故正是"命令成功但字节是旧的"。
+  const installedDir = join(home, 'profiles', 'web', 'node_modules', NAME)
+  const pkg2 = join(work, 'pkg2')
+  cpSync(installedDir, pkg2, { recursive: true, dereference: true })
+  const marker = `// upgrade-probe-${Date.now()}`
+  appendFileSync(join(pkg2, 'lib', 'index.js'), `\n${marker}\n`)
+  // 关键细节（本夹具第一版就栽在这里）：第二个 tgz 必须落在**另一个目录**——否则 npm pack 会覆盖第一个、
+  // 路径规格一模一样，pnpm 视为"同一个规格"直接复用 ⇒ 测出来的是"没升级"而不是"升级失败"。
+  const up2Dir = join(work, 'up2')
+  mkdirSync(up2Dir, { recursive: true })
+  const pack2 = run('npm', ['pack', '--pack-destination', up2Dir], { cwd: pkg2 })
+  const tgz2 = join(up2Dir, (pack2.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop() ?? 'none.tgz')
+  const sha = (f) => (existsSync(f) ? createHash('sha256').update(readFileSync(f)).digest('hex').slice(0, 12) : '(缺)')
+  // 基线的取法（2026-09-18 修）：`--spec <https URL>` 时第一个"tgz"是 URL，`sha(tgz)` 恒为 '(缺)'，
+  // 于是 `sha(tgz2) !== sha(tgz)` **恒真**——断言显示 ✓ 却什么也没证明（"跳过与通过印同一个颜色"的变体）。
+  // 修法：URL 规格下把**装到的副本**（未加 marker）原样打一份作为基线——它与该 URL 同源，
+  // 已由上面那条"装到的是当前版本 + probe 脚本在位"独立证明。
+  let baseSha = sha(tgz)
+  if (isUrl) {
+    const baseDir = join(work, 'base')
+    cpSync(installedDir, baseDir, { recursive: true, dereference: true })
+    const basePackDir = join(work, 'base-pack')
+    mkdirSync(basePackDir, { recursive: true })
+    const bp = run('npm', ['pack', '--pack-destination', basePackDir], { cwd: baseDir })
+    const bpName = (bp.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).pop() ?? 'none.tgz'
+    baseSha = sha(join(basePackDir, bpName))
+  }
+  check('升级夹具：第二个 tgz 与首个**字节不同**（同版本号、内容不同——模拟"新版发布"）',
+    existsSync(tgz2) && baseSha !== '(缺)' && sha(tgz2) !== baseSha, `tgzA=${baseSha}｜tgzB=${sha(tgz2)}`)
+
+  const up = run('dsh', ['plugin', '--profile', 'web', 'add', tgz2], { env, cwd: work })
+  const upOut = `${up.stdout ?? ''}\n${up.stderr ?? ''}`
+  check('升级：对新规格再跑一次 `dsh plugin --profile web add` 退出码 0', up.status === 0,
+    upOut.trim().split(/\r?\n/).slice(-2).join(' | ').slice(0, 160))
+  const upgradedSrc = existsSync(join(installedDir, 'lib', 'index.js')) ? readFileSync(join(installedDir, 'lib', 'index.js'), 'utf8') : ''
+  check('升级：装到的字节真是新版（marker 在位）——不是"命令成功但内容还是旧的"',
+    upgradedSrc.includes(marker), upgradedSrc.includes(marker) ? 'marker 命中' : '仍是旧字节（升级没生效）')
+  const prof2 = existsSync(profPkg) ? JSON.parse(readFileSync(profPkg, 'utf8')) : {}
+  const spec2 = String(prof2.dependencies?.[NAME] ?? '')
+  const bundles2 = prof2.dsh?.profile?.bundles ?? []
+  const dump2 = run('dsh', ['--profile', 'web', '--dump-config'], { env, cwd: work })
+  check('升级后装配不丢：依赖规格已改指新 tgz + bundles 仍含本包 + dump-config 仍见 ppt-studio 行',
+    spec2.includes('tgz') && bundles2.includes(NAME) && /ppt-studio/.test(`${dump2.stdout ?? ''}${dump2.stderr ?? ''}`),
+    `spec=${spec2}｜bundles含=${bundles2.includes(NAME)}｜dump=${/ppt-studio/.test(`${dump2.stdout ?? ''}${dump2.stderr ?? ''}`)}`)
+
+  // 6) **--local 迭代模式自证**（2026-09-18）：日常迭代不发 GitHub，但本机跑的必须就是刚构建的字节。
+  //    形状：复用同一个隔离 DSH_HOME（此刻 profile 已是 bundle 模式）→ 跑 `release-sync --local`
+  //    → 断言五件事：退出码 0 / 全程没有上传动作 / 状态文件 mode=local + mountMatch + ok
+  //    / profile 规格变成指向**本地稳定构件**的 file: / **挂载副本的 lib/index.js 与仓库刚构建的逐字节相同**。
+  //    最后一条才是"本机跑的就是最新"的判据——前四条都可能在"装的其实是旧字节"时仍然为真。
+  const syncRoot = join(work, 'sync-root')
+  const syncState = join(work, 'sync-state.json')
+  const rel = run('node', ['scripts/release-sync.mjs', '--local', '--root', syncRoot, '--state', syncState], { env, cwd: root })
+  const relOut = `${rel.stdout ?? ''}\n${rel.stderr ?? ''}`
+  check('--local：`release-sync --local` 退出码 0', rel.status === 0, relOut.trim().split(/\r?\n/).slice(-4).join(' | ').slice(0, 240))
+  check('--local：全程**没有**上传动作（本地迭代不发 GitHub）', !/release upload/.test(relOut),
+    /release upload/.test(relOut) ? '出现了 release upload！' : '未上传 ✓')
+  const st = existsSync(syncState) ? JSON.parse(readFileSync(syncState, 'utf8')) : {}
+  check('--local：状态文件 mode=local + mount=bundle-local + mountMatch + ok',
+    st.mode === 'local' && st.mount === 'bundle-local' && st.mountMatch === true && st.ok === true,
+    JSON.stringify({ mode: st.mode, mount: st.mount, mountMatch: st.mountMatch, ok: st.ok }))
+  const prof3 = existsSync(profPkg) ? JSON.parse(readFileSync(profPkg, 'utf8')) : {}
+  const spec3 = String(prof3.dependencies?.[NAME] ?? '')
+  check('--local：profile 依赖规格变成指向**本地稳定构件**的 file: 规格',
+    spec3.startsWith('file:') && spec3.includes('_artifacts'), spec3)
+  // 构件必须落在稳定目录：若还在 tmpdir，下次系统清理临时目录后该 profile 的 pnpm install 会直接失败。
+  let artifactFiles = []
+  try { artifactFiles = readdirSync(join(syncRoot, '_artifacts')).filter((f) => f.endsWith('.tgz')) } catch { /* 目录缺失即失败 */ }
+  check('--local：本地构件落在稳定目录 `_artifacts/`（不是 tmpdir），且恰好保留当前那一个',
+    artifactFiles.length === 1, `${join(syncRoot, '_artifacts')} → ${artifactFiles.join(', ') || '(空)'}`)
+  const repoSha12 = sha(join(root, 'lib', 'index.js'))
+  const mountSha12 = sha(join(installedDir, 'lib', 'index.js'))
+  check('--local：**挂载副本 == 仓库刚构建的 lib/index.js**（这才是"本机跑的就是最新"的判据）',
+    repoSha12 === mountSha12, `repo=${repoSha12}｜mount=${mountSha12}`)
+
+  // 7) **预设可被选择器列出（不 broken）+ 安装器不再写预设目录**（2026-09-24 为 DSH 0.1.7 重写）
+  //    0.1.6 的形状：预设靠"写 `<dshHome>/.agent-presets/ppt/`"交付，用 `discoverPresets` 判健康。
+  //    0.1.7：目录发现**整个被删掉**（上游原文 "the harness discovers no preset on disk"），
+  //    预设改为向 `agentPresets` 注册表**声明**（本插件在激活时自己声明，见 src/preset-delivery.js）。
+  //    健康判据随之换成"真正决定它会不会 broken 的那一步"：注册表 mount 预设时用**注册表自己 ctx 的
+  //    baseUrl**（源码 `mountPreset(scope.ctx.extend({ baseUrl: record.context.baseUrl }), …)`，
+  //    而 `register()` 里 `context = this.ctx`）——即 `dsh-web-app` 的包目录，不是 profile、不是预设目录。
+  //    所以"每一行的 name 能否**从那里**解析"就是"预设会不会 broken"的判据；这里用 Node 的解析器真解一遍。
+  const home2 = join(work, 'home2')
+  const profB = join(home2, 'profiles', 'web')
+  const instPkgDir = join(profB, 'node_modules', ...NAME.split('/'))
+  mkdirSync(instPkgDir, { recursive: true })
+  // 夹具 = 已按 bundle 安装：依赖里有本包 + 包本体已被 pnpm 物化（带齐"声明预设"所需的资产）
+  writeFileSync(join(profB, 'package.json'), JSON.stringify({ name: 'p', dependencies: { [NAME]: 'file:x' } }, null, 2), 'utf8')
+  writeFileSync(join(instPkgDir, 'package.json'), JSON.stringify({ name: NAME, version: pkg.version }), 'utf8')
+  cpSync(join(root, 'lib'), join(instPkgDir, 'lib'), { recursive: true })
+  cpSync(join(root, 'agent-presets'), join(instPkgDir, 'agent-presets'), { recursive: true })
+  // 0.1.6 遗留产物：先埋一份预设目录，验证安装器会清掉它
+  const legacyPreset = join(home2, '.agent-presets', 'ppt')
+  mkdirSync(legacyPreset, { recursive: true })
+  writeFileSync(join(legacyPreset, 'agent.cordis.yml'), '- id: persona\n', 'utf8')
+  const env2 = { ...process.env, DSH_HOME: home2 }
+  const inst2 = run('node', [join(root, 'scripts', 'install.mjs'), '--prefix', home2], { env: env2 })
+  check('安装器：bundle 模式下退出码 0', inst2.status === 0,
+    `${String(inst2.stdout ?? '').trim().split(/\r?\n/).length} 行输出｜exit=${inst2.status}`)
+  check('安装器：**不再**产出 `.agent-presets/`（0.1.7 无目录发现路径），并清理 0.1.6 遗留',
+    !existsSync(legacyPreset) && !/^-\s*id: ppt-studio$/m.test(readFileSync(join(instPkgDir, 'agent-presets', 'ppt', 'agent.cordis.yml'), 'utf8')),
+    `遗留目录=${existsSync(legacyPreset)}｜组合含插件行=${/^-\s*id: ppt-studio$/m.test(readFileSync(join(instPkgDir, 'agent-presets', 'ppt', 'agent.cordis.yml'), 'utf8'))}`)
+  check('安装器：校验"声明预设"所需的资产（agent-presets/ppt/* + lib/preset-delivery.js）',
+    /预设资产已就位/.test(String(inst2.stdout ?? '')) && existsSync(join(instPkgDir, 'lib', 'preset-delivery.js')),
+    /预设资产已就位/.test(String(inst2.stdout ?? '')) ? '资产校验通过 ✓' : '(无资产校验输出)')
+  const iso2 = run('node', [join(root, 'scripts', 'install.mjs'), '--prefix', home2, '--isolate'], { env: env2 })
+  check('安装器：`--isolate` 在 0.1.7 上**明确拒绝**（exit 1 + 说清原因，不写出没人读的预设）',
+    iso2.status === 1 && /不再可用/.test(`${iso2.stdout ?? ''}${iso2.stderr ?? ''}`),
+    `exit=${iso2.status}｜有原因=${/不再可用/.test(`${iso2.stdout ?? ''}${iso2.stderr ?? ''}`)}`)
+  const link2 = join(profB, 'node_modules', NAME)
+  check('安装器：**不**把 pnpm 物化的包目录换成 junction（那条路径归 pnpm 管）',
+    existsSync(link2) && lstatSync(link2).isSymbolicLink() === false, `isSymbolicLink=${lstatSync(link2).isSymbolicLink()}`)
+  // 预设健康（0.1.7 判据）：组合里每一行的 `name` 都能从**注册表的 mount base** 解析
+  const mountBase = findPresetMountBase()
+  if (mountBase) {
+    const composition = YAML.parse(readFileSync(join(instPkgDir, 'agent-presets', 'ppt', 'agent.cordis.yml'), 'utf8'))
+    const names = []
+    const walk = (rows) => {
+      for (const r of rows ?? []) {
+        if (typeof r?.name === 'string' && r.name !== 'cordis:group' && !/^\.\.?\//.test(r.name)) names.push(r.name)
+        if (Array.isArray(r?.config)) walk(r.config)
+      }
+    }
+    walk(composition)
+    const req = createRequire(join(mountBase, 'package.json'))
+    const unresolved = names.filter((n) => { try { req.resolve(n); return false } catch { return true } })
+    check('预设健康：组合里每一行都能从**注册表的 mount base** 解析（解析不到 ⇒ 预设 broken ⇒ 选择器看不到它）',
+      names.length > 0 && unresolved.length === 0,
+      `mount base=${mountBase.replace(/\\/g, '/')}｜行=${names.length}｜解析不到=${unresolved.join('、') || '无'}`)
+  } else {
+    check('预设健康：组合里每一行都能从**注册表的 mount base** 解析（解析不到 ⇒ 预设 broken ⇒ 选择器看不到它）', true, '⚠ 未找到 dsh-web-app（未装 DSH？）→ 跳过')
+  }
+  // 技能泄漏面：`<dshHome>/skills/` 是**文件系统技能根**，对所有会话可见（不限预设）。
+  // 默认不镜像，且**清理历史镜像**（否则每次 sync 都会把它装回来）。
+  const mirrorDir2 = join(home2, 'skills', 'ppt-studio-manual')
+  check('会话隔离：默认**不**把内置技能镜像到 <dshHome>/skills（镜像 = 跨预设泄漏）',
+    !existsSync(mirrorDir2), mirrorDir2)
+  const mir = run('node', [join(root, 'scripts', 'install.mjs'), '--prefix', home2, '--mirror-skills'], { env: env2 })
+  check('会话隔离：显式 `--mirror-skills` 才产生镜像（兜底通道按需，不默认泄漏）',
+    mir.status === 0 && existsSync(mirrorDir2), `exit=${mir.status}｜镜像存在=${existsSync(mirrorDir2)}`)
+} finally {
+  rmSync(work, { recursive: true, force: true })
+}
+
+/**
+ * 定位"预设行会被从哪个 base 解析"——即 **agent-preset 注册表所在层的 baseUrl**。
+ * 依据（DSH 源码）：`AgentPresetRegistry.register()` 里 `const context = this.ctx`（注册表自己的 ctx），
+ * `activate()` 再 `mountPreset(scope.ctx.extend({ baseUrl: record.context.baseUrl }), …)`
+ * ⇒ 预设里每一行的 `name` 都从**注册表所在层**解析，而注册表由 `dsh-web-app` 的 patch 插入
+ * ⇒ base 就是 **`dsh-web-app` 的包目录**（既不是 profile，也不是预设目录、更不是"harness 包目录"）。
+ * 用错基准会对别的行误报 broken（假红）或漏报（假绿），所以这里按包目录精确定位。
+ */
+function findPresetMountBase() {
+  const rel = join('node_modules', '@deepseek-ai', 'dsh-web-app', 'package.json')
+  const roots = []
+  try {
+    const r = run('npm', ['root', '-g'])
+    if (r.status === 0 && r.stdout) roots.push(join(r.stdout.trim(), '@deepseek-ai', 'dsh'))
+  } catch { /* npm 不可用 */ }
+  for (const k of ['APPDATA', 'LOCALAPPDATA']) if (process.env[k]) roots.push(join(process.env[k], 'npm', 'node_modules', '@deepseek-ai', 'dsh'))
+  roots.push(join(homedir(), 'AppData', 'Roaming', 'npm', 'node_modules', '@deepseek-ai', 'dsh'))
+  roots.push('/usr/lib/node_modules/@deepseek-ai/dsh', '/usr/local/lib/node_modules/@deepseek-ai/dsh')
+  for (const r of roots) {
+    const dir = dirname(join(r, rel))
+    if (existsSync(join(dir, 'package.json'))) return dir
+  }
+  return null
+}
+
+console.log(`\n==== profile bundle 安装自证：${pass} 通过 / ${fail} 失败 ====`)
+process.exit(fail > 0 ? 1 : 0)

package/scripts/verify-fresh-install.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * verify-fresh-install.mjs —— 「一个普通用户，照着指引敲一条命令，能不能装好并用起来？」
+ *
+ * 为什么需要它（2026-09-18 实测，两个都真实发生过）：
+ *   ① 本地落后远端：`origin/main` 落后本机 **14 个提交**，而已发布的 tag `v1.0.1`
+ *      **指向那个旧提交**。用户按指引跑 `dsh plugin add <仓库 URL>` 拿到的是 v1.0.0 的旧代码
+ *      （没有会话隔离、没有 8 项缺陷修复）——而当时所有本机门禁全绿，因为门禁**只测本机工作区**。
+ *   ② 干净检出才暴露的缺陷：仓库工作区是脚本写出来的 LF，而**干净克隆**在 Windows 上是 CRLF
+ *      （Git for Windows 默认 `core.autocrlf=true`），行锚定文本手术在 CRLF 上静默失效 ⇒
+ *      `resolveDeck` 抛 `page file missing: pages/_cover.yaml`，干净克隆里 `npm test` 直接崩。
+ *   两条的共同点：**"本机绿"与"用户能用"之间没有任何机器在把关**。本脚本就是那道关。
+ *
+ * 它断言的是**用户视角**，不是作者视角：
+ *   ① 远端分支必须包含本地全部提交（否则用户从仓库拿到的是旧代码）——release 模式必查；
+ *   ② tag `v<版本>` 必须存在且**正好指向本地 HEAD**（gh release create 会按默认分支 HEAD 建 tag，
+ *      与"我要发布的提交"无关——这正是 ①里那个错 tag 的成因）；
+ *   ③ **干净克隆**（默认 autocrlf，模拟用户机器）里 `npm install` + `npm test` 必须过，
+ *      且克隆出来的 `package.json.version` 就是本版；
+ *   ④（默认开启）把**用户会敲的那条命令**在一个隔离 DSH_HOME 里真跑一遍（委托 verify-bundle-install.mjs）：
+ *      spec 为 Release 资产 URL（release 模式）或本地 tgz（--local）。
+ *
+ * 用法：
+ *   node scripts/verify-fresh-install.mjs                    # 发版后：查 GitHub 上的 v<版本>
+ *   node scripts/verify-fresh-install.mjs --local            # 本地迭代：查分支 HEAD + 本地 tgz
+ *   node scripts/verify-fresh-install.mjs --skip-clone-test  # 只查 git/资产一致性（快）
+ *   node scripts/verify-fresh-install.mjs --skip-install     # 不跑真安装（没装 dsh 时）
+ *   可选：--repo <url> --branch <name> --spec <url|tgz> --tag v1.0.1
+ *
+ * 退出码：0 = 全部成立；1 = 至少一条不成立（每条都打印"哪一条、看到什么、为什么重要"）。
+ */
+import { execFileSync, spawnSync } from 'node:child_process'
+import { readFileSync, existsSync, mkdtempSync, rmSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const args = process.argv.slice(2)
+const opt = (k, d) => {
+  const i = args.indexOf(k)
+  return i >= 0 && args[i + 1] ? args[i + 1] : d
+}
+const LOCAL = args.includes('--local')
+const SKIP_CLONE_TEST = args.includes('--skip-clone-test')
+const SKIP_INSTALL = args.includes('--skip-install')
+const branch = opt('--branch', 'main')
+const gitRemote = run('git', ['remote', 'get-url', 'origin'], root)
+const repo = opt('--repo', isFail(gitRemote) ? '(未配置 origin)' : gitRemote)
+const tag = opt('--tag', `v${pkg.version}`)
+
+let pass = 0
+let fail = 0
+/** 一条断言：打印"看到什么"，失败时把"为什么重要"一起打出来。 */
+function check(label, ok, detail = '', why = '') {
+  console.log(`${ok ? '✓' : '✗'} ${label}${detail ? ` — ${detail}` : ''}`)
+  if (!ok && why) console.log(`    ↳ 为什么重要：${why}`)
+  ok ? pass++ : fail++
+}
+/** shell 下需要引号的参数（含空白/管道/重定向等）。
+ *  写成**函数声明**（不是 const 箭头函数）：下面的模块级代码要在定义之前调用 run()，
+ *  箭头函数在 TDZ 里会抛 "Cannot access 'shellQuote' before initialization"（本脚本第一版就这样，
+ *  表现为顶部那行"仓库 __FAIL__Cannot access…"）。 */
+function shellQuote(s) {
+  return /[\s"&|<>^]/.test(s) ? `"${String(s).replace(/"/g, '\\"')}"` : String(s)
+}
+/** 跑命令；不抛（失败由断言处理）。 */
+function run(cmd, cmdArgs, cwd = root, extraEnv = {}) {
+  try {
+    // **命令本身也要加引号**（2026-09-18 实测事故）：只转义参数、不转义命令时，
+    // `$env:GH='C:\Program Files\GitHub CLI\gh.exe'` 这种带空格的路径在 shell:true 下会被 cmd.exe
+    // 截成 `C:\Program`（报 "'C:\Program' is not recognized"），而调用方 `isFail()` 把失败当"没查到"
+    // ⇒ 表现为"资产 URL 未找到"，看起来像资产没上传。加引号后复现命令即通过（已用等价脚本实测三态）。
+    return execFileSync(shellQuote(cmd), cmdArgs.map(shellQuote), {
+      cwd,
+      encoding: 'utf8',
+      env: { ...process.env, ...extraEnv },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Windows 上 `npm` 是 npm.cmd：execFileSync 不解析 .cmd，不加 shell 会**直接失败**
+      // （本脚本第一版就栽在这里：npm install / npm test 全报 ✗，而输出是空的，看起来像被测对象的问题）。
+      // 仓库里 verify-bundle-install.mjs 的 run() 用的是同一个写法，保持一致。
+      shell: process.platform === 'win32',
+    }).trim()
+  } catch (e) {
+    const out = `${e.stdout ?? ''}${e.stderr ?? ''}`
+    // 连 stdout/stderr 都没有时（spawn 本身失败）把 message 带上，别让断言显示成"空失败"。
+    return `__FAIL__${out || String(e?.message ?? e)}`
+  }
+}
+function isFail(s) {
+  return typeof s === 'string' && s.startsWith('__FAIL__')
+}
+function tail(s, n = 200) {
+  return String(s).replace(/__FAIL__/, '').trim().split(/\r?\n/).filter(Boolean).slice(-3).join(' | ').slice(0, n)
+}
+
+console.log(`verify-fresh-install：版本 ${pkg.version}｜模式 ${LOCAL ? 'local（本地迭代）' : 'release（查 GitHub）'}｜仓库 ${repo}｜分支 ${branch}｜tag ${tag}\n`)
+
+// ── ① 本地是否全部推上去了 ─────────────────────────────────────────────────────
+// 这一条最容易被忽略，而它的后果最严重：本地全绿、用户装到旧代码。查的是"用户会克隆到的那个分支"。
+// 注意：**只有 release 模式把它当断言**——`--local` 是日常迭代，本地领先远端是常态（那正是它的目的），
+// 所以那里只打印信息，不判失败。真正的本地判据是 ②（干净检出我的**当前工作**能不能过）。
+if (LOCAL) {
+  const fetch = run('git', ['fetch', '--quiet', 'origin'])
+  if (isFail(fetch)) {
+    console.log('① 远端信息：未能确认（离线或远端不可达）——不影响本地自检')
+  } else {
+    const behind = Number(run('git', ['rev-list', '--count', `HEAD..origin/${branch}`]) || '0')
+    const ahead = Number(run('git', ['rev-list', '--count', `origin/${branch}..HEAD`]) || '0')
+    console.log(`① 远端信息（仅信息，不判失败）：本地领先 origin/${branch} ${ahead} 个提交｜落后 ${behind} 个`
+      + `${ahead > 0 ? '——发版前必须 push（发版模式会拒绝继续）' : ''}`)
+  }
+} else {
+  console.log('① 远端 tag 与本地 HEAD 的一致性（release 模式）')
+  const ls = run('git', ['ls-remote', '--tags', 'origin', `refs/tags/${tag}`])
+  const remoteTagSha = isFail(ls) ? '' : (ls.split(/\s+/)[0] ?? '')
+  const head = run('git', ['rev-parse', 'HEAD'])
+  check(`远端存在 tag ${tag}`, remoteTagSha.length === 40, remoteTagSha || `(没有这个 tag)`,
+    'README 与创意工坊卡片都按 tag/资产指路；tag 不存在时用户按图索骥会 404。')
+  check(`${tag} 正好指向本地 HEAD（要发布的那一提交）`, remoteTagSha === head,
+    `tag=${remoteTagSha.slice(0, 10) || '(缺)'}｜HEAD=${head.slice(0, 10)}`,
+    '`gh release create` 会按**默认分支 HEAD** 建 tag——本地没推时它就把 tag 建在旧提交上，'
+    + '于是"发布"了 v1.0.1，而 v1.0.1 指向的是 v1.0.0 的代码。')
+  // 顺带断言：远端分支确实包含 HEAD（否则 git 安装路径仍是旧的）
+  const lsMain = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`])
+  const remoteBranchSha = isFail(lsMain) ? '' : (lsMain.split(/\s+/)[0] ?? '')
+  const contains = remoteBranchSha && run('git', ['merge-base', '--is-ancestor', head, remoteBranchSha]) !== '__FAIL__'
+  check(`origin/${branch} 已包含本地 HEAD（git 安装路径拿到的是本版）`, Boolean(contains),
+    `branch=${remoteBranchSha.slice(0, 10) || '(缺)'}｜HEAD=${head.slice(0, 10)}`,
+    '创意工坊对无 npm 包的条目生成的就是 `dsh plugin add <仓库 URL>`——分支落后就等于用户装不到新版。')
+}
+
+// ── ② 干净克隆里 npm install + npm test ───────────────────────────────────────
+// 这一步是"别人的机器"的替身：没有本机的 node_modules、没有本机的 gitignore 产物、
+// Windows 上还会按 core.autocrlf 的默认值检出 CRLF。历史上红过的两条都在这里才现形。
+if (SKIP_CLONE_TEST) {
+  console.log('\n② 干净克隆自检 —— 已按 --skip-clone-test 跳过')
+} else {
+  console.log('\n② 干净克隆里 npm install + npm test（"别人的机器"的替身）')
+  const work = mkdtempSync(join(tmpdir(), 'ppt-fresh-'))
+  const cloneDir = join(work, 'repo')
+  try {
+    // 故意**不**传 -c core.autocrlf=false：用户机器是什么样，这里就什么样。
+    // .gitattributes 的 `* text=auto eol=lf` 负责把检出钉成 LF；若它失效，这段就会像用户一样崩。
+    // **克隆源按模式区分**：release 克隆 GitHub 上的 tag（= 用户真正会拿到的东西）；
+    // `--local` 克隆**本地仓库路径**（= "我这台机器上这份工作，全新检出能不能过"）——
+    // 本地迭代时本地领先远端是常态，从远端克隆反而验错了对象（这是本脚本第一版的真实缺陷）。
+    const cloneSource = LOCAL ? root : repo
+    const cloneDepth = ['--depth', '1', '--branch', LOCAL ? branch : tag]
+    const clone = run('git', ['clone', '--quiet', ...cloneDepth, cloneSource, cloneDir])
+    check(`干净克隆成功（${LOCAL ? `本地 HEAD @ ${branch}` : tag}）`, !isFail(clone), tail(clone),
+      '克隆都失败时后面全是假象——必须先确认这一步。')
+    if (isFail(clone)) throw new Error('clone failed')
+
+    const cloneVer = JSON.parse(readFileSync(join(cloneDir, 'package.json'), 'utf8')).version
+    check('克隆出来的就是本版（package.json.version）', cloneVer === pkg.version,
+      `克隆=${cloneVer}｜本机=${pkg.version}`,
+      '用户装到的必须是你刚发布的那一版；版本不一致说明 tag/分支指向的不是本版。')
+    if (LOCAL) {
+      const cloneHead = run('git', ['rev-parse', 'HEAD'], cloneDir)
+      const localHead = run('git', ['rev-parse', 'HEAD'])
+      check('本地模式的干净检出来自**当前 HEAD**（不是远端旧提交）', cloneHead === localHead,
+        `克隆=${cloneHead.slice(0, 10)}｜本地=${localHead.slice(0, 10)}`,
+        '--local 要答的问题是"我这份工作全新检出能不能过"，克隆到远端就是把旧代码当成新代码来验。')
+    }
+
+    // 检出字节的证据（不是断言，是现场记录）：git 安装与 tgz 安装必须是同一份字节。
+    const crlf = countCrlfFiles(cloneDir)
+    console.log(`      · 干净克隆的文本文件 CRLF 数：${crlf.length}（应为 0；非 0 说明 .gitattributes 没生效，`
+      + 'Windows 上就会命中"行锚定正则静默失效"那个坑）')
+    check('干净克隆的跟踪文本文件全是 LF（git 安装 == tgz 安装）', crlf.length === 0,
+      crlf.slice(0, 5).join(', ') || '无', '见 scripts/check-tracked-lf.mjs 的说明。')
+
+    const inst = run('npm', ['install', '--no-audit', '--no-fund'], cloneDir)
+    check('克隆里 npm install 成功', !isFail(inst), tail(inst), '用户第一步就会跑它。')
+    const test = run('npm', ['test'], cloneDir)
+    check('克隆里 npm test 全绿（这就是"干净检出"的定义）', !isFail(test), isFail(test) ? tail(test, 400) : `结果行：${(String(test).match(/====.*====/) ?? ['(未见结果行)'])[0]}`,
+      '历史上这里红过：previews 断言在无 Office 的机器上必红；CRLF 检出则直接崩在 pages/_cover.yaml。')
+    if (isFail(test)) {
+      console.log('      —— 克隆里 npm test 的输出尾部 ——')
+      for (const l of String(test).replace('__FAIL__', '').split(/\r?\n/).slice(-25)) console.log(`      ${l}`)
+    }
+  } finally {
+    if (!args.includes('--keep-work')) rmSync(work, { recursive: true, force: true })
+  }
+}
+
+// ── ③ 用户会敲的那条命令（真安装，隔离 DSH_HOME）─────────────────────────────
+if (SKIP_INSTALL) {
+  console.log('\n③ 一条命令安装 —— 已按 --skip-install 跳过')
+} else {
+  console.log('\n③ 一条命令安装（委托 verify-bundle-install.mjs，隔离 DSH_HOME，不碰你的 profile）')
+  let spec = opt('--spec', '')
+  if (!spec && LOCAL) {
+    // --local：用刚打出来的本地 tgz（等价于"从同一份字节装一遍"）
+    const packDir = mkdtempSync(join(tmpdir(), 'ppt-fresh-pack-'))
+    const pack = run('npm', ['pack', '--pack-destination', packDir])
+    spec = isFail(pack) ? '' : join(packDir, String(pack).split(/\r?\n/).filter(Boolean).pop())
+  }
+  let specWhy = ''
+  if (!spec) {
+    // release：用 Release 页面上那条资产 URL（用户会复制粘贴的那一条）
+    const found = findReleaseAsset(tag)
+    if (found.url) spec = found.url
+    else specWhy = found.why
+  }
+  if (!spec) {
+    check('能定位到"用户会敲的那条命令"的安装规格（Release 资产 URL / 本地 tgz）', false,
+      `(未找到)${specWhy ? ` ${specWhy}` : ''}`,
+      '这条命令是文档指引的核心；找不到规格就无法证明它可用。可用 --spec 显式给定。')
+  } else {
+    console.log(`      规格：${spec}`)
+    const r = spawnSync(process.execPath, [join(root, 'scripts', 'verify-bundle-install.mjs'), spec], { cwd: root, stdio: 'inherit' })
+    check('`dsh plugin --profile web add <规格>` 全链自证通过（含装配与升级路径）', r.status === 0,
+      `exit=${r.status}`, '这一条就是"用户敲完能不能用"本身；前面几条只保证"代码是对的"。')
+  }
+}
+
+console.log(`\n==== verify-fresh-install 结果：${pass} 通过 / ${fail} 失败 ====`)
+process.exit(fail > 0 ? 1 : 0)
+
+/** 统计干净克隆里的 CRLF 文本文件（与 check-tracked-lf.mjs 同判据，但只读不改）。 */
+function countCrlfFiles(dir) {
+  const BINARY = new Set(['.pptx', '.zip', '.tgz', '.gz', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.woff', '.woff2', '.ttf', '.otf', '.pdf'])
+  const files = run('git', ['ls-files', '-z'], dir)
+  if (isFail(files)) return []
+  const out = []
+  for (const rel of files.split('\0').filter(Boolean)) {
+    if (BINARY.has(rel.slice(rel.lastIndexOf('.')).toLowerCase())) continue
+    try {
+      const buf = readFileSync(join(dir, rel))
+      if (buf.includes(0)) continue
+      if (buf.includes('\r\n')) out.push(rel)
+    } catch { /* 缺失文件不是本检查的职责 */ }
+  }
+  return out
+}
+
+/** 取 Release 资产 URL（用户会在资产页复制粘贴的那一条）。返回 { url, why }——why 为空表示成功。 */
+function findReleaseAsset(t) {
+  const gh = process.env.GH || 'gh'
+  // 用 REST + 本地解析，**不用 --jq**：cmd.exe 下 shell 无法用单引号 jq（release-sync.mjs 里同一条教训）。
+  const remote = run('git', ['remote', 'get-url', 'origin']) || ''
+  const m = /github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(remote.trim())
+  if (!m) return { url: '', why: `无法从 origin 解析 owner/repo：${remote.trim() || '(空)'}` }
+  const json = run(gh, ['api', `repos/${m[1]}/${m[2]}/releases/tags/${t}`])
+  // **失败必须说出原因**（别再静默返回空）：这条断言红过两次，第一次的样子就是"未找到"三个字，
+  // 而真正原因（gh 调用被 shell 截断 / 网络超时）全被吞掉了。
+  if (isFail(json)) return { url: '', why: `gh api 调用失败：${json.replace(/^__FAIL__/, '').trim().split('\n')[0]}` }
+  try {
+    const assets = (JSON.parse(json).assets ?? []).filter((a) => String(a.name).endsWith('.tgz'))
+    // 资产名 = 版本-构建时间-构建戳；历次构建都挂在同一 Release 上，按创建时间取最新即当前版本。
+    assets.sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)))
+    const url = assets.pop()?.browser_download_url ?? ''
+    return { url, why: url ? '' : `release ${t} 上没有任何 .tgz 资产（资产是 release-sync 上传的，先跑它）` }
+  } catch (e) {
+    return { url: '', why: `解析 gh 输出失败：${String(e?.message ?? e)}` }
+  }
+}