@godv61/dsh-task-engine 0.23.4 → 0.23.5

package/docs/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 按版本查阅功能变化。当前使用方式以[项目首页](../README.md)和使用指南为准；历史条目中的实现方式、限制与测试数量可能已被后续版本替代。
 
+## 0.23.5
+
+- **修复 `scripts/` 未随包发布，导致两条已声明的 npm script 在安装后无法执行**。`package.json` 声明了 `verify:package` 与 `verify:dsh`，但 `files` 白名单不含 `scripts/**`，用户装包后运行它们会直接 `MODULE_NOT_FOUND`。该问题早于 0.23.3 存在（`verify:package` 一直如此），0.23.4 新增的 `verify:dsh` 只是沿用了同一模式。现在把 `scripts/**` 纳入白名单，并在 `verify:package` 中加断言：包内必须能找到每一条 `package.json` 里声明的 `node <file>` script 目标。
+
 ## 0.23.4
 
 - **关闭两处 Remote 路径边界漏洞**。`checkedPath` 此前用**原始字符串**比对禁止前缀，`D:/proj/../../Windows` 不匹配任何前缀，却被后续 `join()` 解析到 `C:/Windows`；实测 8 个越界样本中旧实现放过 7 个。现在先 `resolve()` 归一化再判断，禁止列表不再绑定盘符（`D:/Windows`、`E:/Program Files` 同样拒绝），并拒绝裸盘符根（`D:/`、`C:/`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godv61/dsh-task-engine",
-  "version": "0.23.4",
+  "version": "0.23.5",
   "description": "Preset-workflow engineering delivery engine for DeepSeek Harness: a `dev_task` tool that hard-gates stage transitions and commit scope/message, per-node skill/rule bindings with progressive disclosure, a workbench to pick a flow preset and mount skills/rules, and preset-scoped activation — the tool and skills activate only for sessions on a preset that names the agent row.",
   "type": "module",
   "main": "lib/index.js",
@@ -33,6 +33,7 @@
     "skills/**",
     "rules/**",
     "preset/**",
+    "scripts/**",
     "docs/**",
     "README.md",
     ".p0-test.mjs",
@@ -83,7 +84,6 @@
     "@types/react": "~18.3.1",
     "esbuild": "^0.24.0",
     "react": "^18.2.0",
-    "semver": "^7.6.0",
     "typescript": "^5.7.2",
     "zod": "^3.23.8"
   },

package/scripts/verify-dsh-compat.mjs

@@ -0,0 +1,145 @@
+/**
+ * DSH codec-contract compatibility check.
+ *
+ * The plugin's Typert Remote contribution must satisfy whichever strict-codec
+ * contract the installed DSH expects. DSH 0.1.6-alpha.2 replaced the
+ * materialized `schema` field with a lazy `create: () => TypertSchema` factory
+ * and rejects the old shape at plugin load, which took the whole contribution
+ * down at boot — a failure the unit tests could not see, because they never
+ * load the descriptors through a real registry.
+ *
+ * npm semver cannot wildcard prereleases, so the peer range enumerates them and
+ * a new DSH alpha silently falls outside it; pnpm only warns at install time.
+ * This check runs against a real DSH checkout, where the contract actually
+ * lives, and fails loudly when the two drift apart again.
+ *
+ * Run: `node scripts/verify-dsh-compat.mjs [path-to-dsh-checkout]`
+ * @module dsh-task-engine/scripts/verify-dsh-compat
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DEFAULT_DSH_ROOT = 'D:/dsharness/deepseek-harness'
+
+const problems = []
+function check(name, ok, detail = '') {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${name}${detail === '' ? '' : `: ${detail}`}`)
+  if (!ok) problems.push(name)
+}
+
+/** Locate the typert protocol package inside a DSH checkout. */
+function protocolDir(root) {
+  const candidates = [
+    join(root, 'packages', 'typert', 'protocol'),
+    join(root, 'node_modules', '@deepseek-ai', 'dsh-typert-protocol'),
+  ]
+  return candidates.find(dir => existsSync(join(dir, 'package.json')))
+}
+
+const dshRoot = process.argv[2] ?? DEFAULT_DSH_ROOT
+console.log(`DSH checkout: ${dshRoot}`)
+
+if (!existsSync(dshRoot)) {
+  // Absent checkout is not a failure: this script is advisory outside CI.
+  console.log('ok   (skipped) no DSH checkout at that path')
+  process.exit(0)
+}
+
+const dir = protocolDir(dshRoot)
+if (dir === undefined) {
+  check('locate the typert protocol package', false, 'not found under the DSH checkout')
+  process.exit(1)
+}
+const protocol = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+console.log(`     typert protocol version: ${protocol.version}`)
+
+// 1. Which contract does this DSH expect? Read the type, not a guess.
+const typesPath = [
+  join(dir, 'src', 'types.ts'),
+  join(dir, 'lib', 'types', 'types.d.ts'),
+].find(path => existsSync(path))
+const typesText = typesPath === undefined ? '' : readFileSync(typesPath, 'utf8')
+const wantsCreate = /readonly create: \(\) => TypertSchema/u.test(typesText)
+const wantsSchema = /readonly schema: TypertSchema/u.test(typesText)
+console.log(`     contract: ${wantsCreate ? 'create() factory' : wantsSchema ? 'schema field' : 'unknown'}`)
+
+// 2. Our descriptors must satisfy it. Import the built contribution and inspect
+//    every strict codec exactly as the DSH registry would.
+const pluginRoot = fileURLToPath(new URL('..', import.meta.url))
+const clientBundle = join(pluginRoot, 'lib', 'client.js')
+if (!existsSync(clientBundle)) {
+  check('built client bundle exists', false, 'run `npm run build` first')
+  process.exit(1)
+}
+const bundleText = readFileSync(clientBundle, 'utf8')
+const strictCodecs = (bundleText.match(/mode:\s*"strict"/gu) ?? []).length
+const withCreate = (bundleText.match(/create:\s*\(\)\s*=>/gu) ?? []).length
+const withSchema = (bundleText.match(/schema:/gu) ?? []).length
+
+check('the bundle carries strict codecs', strictCodecs > 0, `${strictCodecs} found`)
+if (wantsCreate) {
+  check('every strict codec provides create()', withCreate >= strictCodecs,
+    `${withCreate} of ${strictCodecs}`)
+}
+if (wantsSchema) {
+  check('every strict codec provides schema', withSchema >= strictCodecs,
+    `${withSchema} of ${strictCodecs}`)
+}
+
+// 3. The peer range must actually admit the installed DSH version, because npm
+//    semver will not match a prerelease the range does not name. Implemented
+//    here rather than via the `semver` package: that is a devDependency, so a
+//    consumer running this script from the installed tarball has no copy, and
+//    the whole point of this check is to run against whatever DSH is present.
+const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'))
+const range = pkg.peerDependencies['@deepseek-ai/dsh-typert-protocol'] ?? ''
+check(`peer range admits DSH ${protocol.version}`, rangeAdmits(range, protocol.version), range)
+
+/**
+ * Whether one of a `||`-joined range's comparators admits `version`.
+ *
+ * npm semver matches a prerelease only when the comparator names a prerelease
+ * on the SAME major.minor.patch, which is why enumerating versions is the only
+ * way to cover a DSH alpha. This mirrors that rule for the caret and exact
+ * forms the manifest actually uses; it is deliberately conservative, and an
+ * unrecognized comparator reports `false` so the check fails loudly rather than
+ * passing by accident.
+ * @param range - the peer range expression.
+ * @param version - the installed DSH version to test.
+ * @returns true when the range admits the version.
+ */
+function rangeAdmits(range, version) {
+  const parse = text => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u.exec(text.trim())
+    return match === null
+      ? undefined
+      : { major: +match[1], minor: +match[2], patch: +match[3], pre: match[4] }
+  }
+  const target = parse(version)
+  if (target === undefined) return false
+  for (const part of range.split('||').map(text => text.trim()).filter(Boolean)) {
+    const caret = /^\^(.+)$/u.exec(part)
+    const lower = parse(caret === null ? part : caret[1])
+    if (lower === undefined) continue
+    // Same prerelease tuple, or a plain release on the same caret line.
+    const sameTuple = target.major === lower.major
+      && target.minor === lower.minor
+      && target.patch === lower.patch
+    if (lower.pre !== undefined) {
+      if (sameTuple) return true
+    } else if (target.pre === undefined && target.major === lower.major) {
+      if (caret === null ? sameTuple : target.minor >= lower.minor) return true
+    }
+  }
+  return false
+}
+
+if (problems.length > 0) {
+  console.error(`\n${problems.length} DSH compatibility problem(s)`)
+  console.error('A new DSH alpha likely changed the Typert contract. Update src/client/remote.ts')
+  console.error('and add the version to peerDependencies before releasing.')
+  process.exit(1)
+}
+console.log('\nDSH compatibility verified')

package/scripts/verify-package.mjs

@@ -0,0 +1,136 @@
+/**
+ * Black-box verification of the npm tarball before publishing: packs the
+ * package, extracts it into a clean temp dir, and proves the published entry
+ * points actually work — main import, browser client registration, the bundled
+ * `.p0-test.mjs`, the CLI, and the `files` whitelist.
+ *
+ * Run: `npm run verify:package`
+ * @module dsh-task-engine/scripts/verify-package
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
+const failures = []
+function check(name, ok, detail = '') {
+  console.log(`${ok ? 'ok  ' : 'FAIL'} ${name}${detail !== '' ? `: ${detail}` : ''}`)
+  if (!ok) failures.push(name)
+}
+
+// 1. pack
+let tgzName
+try {
+  const packed = JSON.parse(execSync('npm pack --json', { cwd: pkgRoot, encoding: 'utf8' }))
+  tgzName = packed[0]?.filename
+} catch (error) {
+  check('npm pack', false, String(error))
+  process.exit(1)
+}
+check('npm pack', typeof tgzName === 'string', tgzName)
+
+// 2. extract into a clean temp dir
+const tmp = mkdtempSync(join(tmpdir(), 'dsh-pkg-verify-'))
+const tgzPath = join(pkgRoot, tgzName)
+execSync(`tar -xzf "${tgzPath}"`, { cwd: tmp, stdio: 'pipe' })
+const pkgDir = join(tmp, 'package')
+const listing = execSync(`tar -tzf "${tgzPath}"`, { encoding: 'utf8' })
+  .trim().split(/\r?\n/u).map(line => line.replace(/^package\//u, ''))
+check('extract', existsSync(join(pkgDir, 'package.json')))
+
+// 3. files whitelist sanity
+for (const required of ['hooks/commit-msg', 'lib/index.js', 'lib/client.js', 'lib/client.d.ts', '.p0-test.mjs', 'preset/enable.mjs', 'README.md', '.resource-test.mjs', '.workflow-test.mjs', '.hook-test.mjs']) {
+  check(`tarball contains ${required}`, listing.includes(required))
+}
+check('tarball excludes src sources', !listing.some(line => line.startsWith('src/')))
+check('tarball excludes build scripts', !listing.some(line => line.endsWith('build-client.mjs') || line.endsWith('build-hook.mjs')))
+
+// Every `node <file>` script the manifest declares must actually ship, EXCEPT
+// the build-time ones that `prepare` needs in the source tree only. A script
+// whose target is absent from `files` installs fine and then dies with
+// MODULE_NOT_FOUND — which is exactly what verify:package and verify:dsh did
+// until this assertion existed, because neither scripts/ path was published.
+{
+  const manifest = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+  // Scripts that legitimately run only before publishing, never from a consumer.
+  const BUILD_ONLY = new Set(['prepare', 'build'])
+  const missing = []
+  for (const [name, command] of Object.entries(manifest.scripts ?? {})) {
+    if (BUILD_ONLY.has(name)) continue
+    for (const match of String(command).matchAll(/\bnode\s+(?:--[^\s]+\s+)*([^\s&|]+)/gu)) {
+      const target = match[1].replace(/^\.\//u, '')
+      if (!target.endsWith('.mjs') && !target.endsWith('.js')) continue
+      if (!listing.includes(target)) missing.push(`${name} -> ${target}`)
+    }
+  }
+  check('every declared node script ships in the tarball', missing.length === 0, missing.join(', '))
+}
+
+// 3b. install the tarball into a clean project so peer dependencies resolve,
+// exactly like a real consumer's `npm install`.
+const installDir = mkdtempSync(join(tmpdir(), 'dsh-pkg-install-'))
+import { writeFileSync } from 'node:fs'
+writeFileSync(join(installDir, 'package.json'), JSON.stringify({ name: 'probe', private: true, type: 'module' }))
+try {
+  execSync(`npm install "${tgzPath}" --no-audit --no-fund`, { cwd: installDir, encoding: 'utf8', stdio: 'pipe' })
+  check('npm install tarball', true)
+} catch (error) {
+  check('npm install tarball', false, String(error.stderr ?? error))
+  process.exit(1)
+}
+const installedDir = join(installDir, 'node_modules', '@godv61', 'dsh-task-engine')
+
+// 4. main entry imports
+try {
+  await import(pathToFileURL(join(installedDir, 'lib/index.js')).href)
+  check('import main entry', true)
+} catch (error) {
+  check('import main entry', false, error instanceof Error ? error.message : String(error))
+}
+
+// 5. browser client registers through the DSH module loader
+try {
+  const registry = { loaded: undefined }
+  globalThis.window = { __ModuleLoader__: { load(reg) { registry.loaded = reg } } }
+  await import(pathToFileURL(join(installedDir, 'lib/client.js')).href)
+  check('client bundle registers via ModuleLoader', registry.loaded?.id === '@godv61/dsh-task-engine')
+} catch (error) {
+  check('client bundle registers via ModuleLoader', false, error instanceof Error ? error.message : String(error))
+}
+
+// 6. in-package acceptance test
+try {
+  const out = execSync('node .p0-test.mjs', { cwd: installedDir, encoding: 'utf8', stdio: 'pipe' })
+  check('in-package .p0-test.mjs', /passed/u.test(out), out.trim().split('\n').at(-1))
+} catch (error) {
+  check('in-package .p0-test.mjs', false, String(error.stderr ?? error))
+}
+
+// Resource package behavior from the installed artifact, including the commit
+// hook running for real inside throwaway repositories.
+try {
+  const out = execSync('node --test --test-reporter=tap .resource-test.mjs .workflow-test.mjs .hook-test.mjs', { cwd: installedDir, encoding: 'utf8', stdio: 'pipe' })
+  check('in-package resource, workflow and hook behavior', /# fail 0/u.test(out))
+} catch (error) { check('in-package resource, workflow and hook behavior', false, String(error.stderr ?? error)) }
+
+// 7. CLI parses
+try {
+  const cli = join(installedDir, 'preset', 'enable.mjs')
+  execSync(`node --check "${cli}"`, { stdio: 'pipe' })
+  check('CLI enable.mjs parses', true)
+} catch (error) {
+  check('CLI enable.mjs parses', false, String(error.stderr ?? error))
+}
+
+rmSync(tmp, { recursive: true, force: true })
+rmSync(installDir, { recursive: true, force: true })
+try { rmSync(tgzPath, { force: true }) } catch { /* keep the tarball when the FS declines */ }
+
+if (failures.length > 0) {
+  console.error(`\n${failures.length} failure(s)`)
+  process.exit(1)
+}
+console.log('\npackage black-box verification passed')