dsh-plugin-worktrees 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dsh-plugin-worktrees",
+  "version": "0.1.0",
+  "description": "git worktree parallel write isolation + serial merge integration plugin for the DeepSeek Harness",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib/",
+    "scripts/",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "AGENTS.md",
+    "SECURITY.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node scripts/lint.js",
+    "setup:peer": "bash scripts/link-harness-dsh-tools.sh"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "cordis",
+    "git",
+    "worktree",
+    "merge-queue"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Luck9Star/dsh-worktrees.git"
+  },
+  "homepage": "https://github.com/Luck9Star/dsh-worktrees#readme",
+  "bugs": {
+    "url": "https://github.com/Luck9Star/dsh-worktrees/issues"
+  }
+}

package/scripts/link-harness-dsh-tools.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# link-harness-dsh-tools.sh — symlink the RUNNING harness's @deepseek-ai/dsh-tools
+# into this repo's node_modules.
+#
+# Why: @deepseek-ai/dsh-tools is a peerDependency. dsh-tools registers its
+# tool-runtime scheduler under a module-level Symbol (TOOL_RUNTIME_SCHEDULER),
+# so a second physical copy of the package (e.g. hoisted into a profile tree by
+# a regular dependency, or installed here for development) is a SECOND module
+# instance with a SECOND Symbol. The agent loop then fails every tool call:
+#   Cannot read properties of undefined (reading 'prepare')
+# Linking to the copy the harness itself runs keeps a single instance.
+#
+# Re-run after a dsh upgrade (new npx cache dir) or an `npm install` here.
+#
+# Note: dsh-worktrees carries NO patches/ directory (zero host patches — the
+# plugin patches nothing into the harness), so the resolve_live_root logic from
+# the dsh-plugin-subagents family's patches/resolve-root.sh is INLINED below
+# (red line 11 stays intact: no hardcoded cache-hash paths, no
+# `ls ~/.npm/_npx/* | tail -1` pick-a-root heuristics). resolve_live_root walks
+# `command -v dsh` -> realpath -> upward to the node_modules parent (or honors
+# DSH_HARNESS_ROOT), and the peer package is read from that root. Use this
+# script (or the explicit HARNESS_DSH_TOOLS override) to keep dsh-tools in sync
+# after a harness move.
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TARGET="${REPO_DIR}/node_modules/@deepseek-ai/dsh-tools"
+
+# --- inline resolve_live_root (this plugin has no patches/ dir) --------------
+# Resolves the live dsh harness root: the parent of the node_modules directory
+# that holds the `dsh` binary currently on PATH.
+resolve_live_root() {
+  # 1. An explicit DSH_HARNESS_ROOT beats PATH resolution.
+  if [ -n "${DSH_HARNESS_ROOT:-}" ]; then
+    _rr_root="${DSH_HARNESS_ROOT}"
+  else
+    # 2. `command -v dsh` -> realpath -> walk up to the node_modules parent.
+    _rr_bin="$(command -v dsh 2>/dev/null || true)"
+    if [ -z "${_rr_bin}" ]; then
+      printf 'resolve-root: ERROR: dsh not found on PATH — is the harness installed?\n' >&2
+      return 1
+    fi
+    if ! _rr_real="$(realpath "${_rr_bin}" 2>/dev/null)"; then
+      printf 'resolve-root: ERROR: realpath failed for %s\n' "${_rr_bin}" >&2
+      return 1
+    fi
+    _rr_dir="$(dirname "${_rr_real}")"
+    _rr_root=""
+    while [ -n "${_rr_dir}" ] && [ "${_rr_dir}" != "/" ]; do
+      if [ "$(basename "${_rr_dir}")" = "node_modules" ]; then
+        _rr_root="$(dirname "${_rr_dir}")"
+        break
+      fi
+      _rr_dir="$(dirname "${_rr_dir}")"
+    done
+    if [ -z "${_rr_root}" ]; then
+      printf 'resolve-root: ERROR: %s is not under any node_modules — this is not a live dsh harness root\n' "${_rr_real}" >&2
+      return 1
+    fi
+  fi
+  # 3. Self-verification: the root must actually carry a dsh-tools peer.
+  if [ ! -d "${_rr_root}/node_modules/@deepseek-ai/dsh-tools" ]; then
+    printf 'resolve-root: ERROR: %s/node_modules/@deepseek-ai/dsh-tools does not exist — this is not a live dsh harness root\n' "${_rr_root}" >&2
+    return 1
+  fi
+  printf '%s\n' "${_rr_root}"
+}
+# -----------------------------------------------------------------------------
+
+# Allow an explicit override: HARNESS_DSH_TOOLS=/path/to/dsh-tools ./scripts/link-harness-dsh-tools.sh
+if [ -n "${HARNESS_DSH_TOOLS:-}" ]; then
+  HARNESS_TOOLS="${HARNESS_DSH_TOOLS}"
+else
+  LIVE_ROOT="$(resolve_live_root)" || {
+    echo "ERROR: cannot resolve the live dsh harness root (see resolve-root diagnostics above)" >&2
+    echo "Hint: HARNESS_DSH_TOOLS=/path/to/dsh-tools $0" >&2
+    exit 1
+  }
+  HARNESS_TOOLS="${LIVE_ROOT}/node_modules/@deepseek-ai/dsh-tools"
+fi
+
+if [ ! -d "${HARNESS_TOOLS}" ]; then
+  echo "ERROR: ${HARNESS_TOOLS} is not a directory" >&2
+  echo "Hint: point HARNESS_DSH_TOOLS at the live dsh-tools package, e.g. HARNESS_DSH_TOOLS=\$(npm root -g)/@deepseek-ai/dsh-tools $0" >&2
+  exit 1
+fi
+
+mkdir -p "${REPO_DIR}/node_modules/@deepseek-ai"
+if [ -L "${TARGET}" ] && [ "$(readlink "${TARGET}")" = "${HARNESS_TOOLS}" ]; then
+  echo "OK: ${TARGET} -> ${HARNESS_TOOLS} (already correct)"
+  exit 0
+fi
+rm -rf "${TARGET}"
+ln -s "${HARNESS_TOOLS}" "${TARGET}"
+echo "LINKED: ${TARGET} -> ${HARNESS_TOOLS}"

package/scripts/lint.js

@@ -0,0 +1,142 @@
+// dsh-worktrees lint: cross-platform syntax check + git-exit discipline (T12).
+//
+// 1. `node --check` every .js/.mjs under lib/ and test/ (as before, T01).
+// 2. A static git-exit audit over lib/ (DESIGN §11.3 red line 1 = §12 rule 1):
+//    the ONLY module that may invoke a process-spawning call (`spawn(`,
+//    `spawnSync(`, `exec(`, `execSync(`, `execFile(`, `execFileSync(`) is
+//    lib/git-port.js. Every other module must go through GitPort — this is a
+//    mechanical guard that keeps the "unique git ingress" red line intact.
+// 3. An embedded self-test asserts the audit fires on a positive sample
+//    (a non-git-port module calling spawn()) and stays silent on the negative
+//    sample (git-port.js calling spawn()) — pinning the audit's own behaviour.
+//
+// Comments are scanned too (the static discipline is intentionally
+// conservative), but only REAL call shapes are flagged: the regex requires an
+// identifier followed by `(`, so prose that merely mentions the word ("this
+// module never spawns git itself", "spawn failure") does not trip it. Only a
+// genuine `name(` after one of the spawn/exec method names is a violation.
+import { execFileSync } from 'node:child_process'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const root = fileURLToPath(new URL('..', import.meta.url))
+
+// The single module that owns every git subprocess. All other lib/ modules
+// must inject a GitPort (or be pure) and never spawn git themselves.
+const GIT_PORT_FILE = 'git-port.js'
+
+// Real spawn/exec call forms: `name(` where name is one of the node:child_process
+// launchers (case-sensitive; lower-case `spawn` triggers on both `spawn(` and
+// method receivers like `this.spawn(` because `\b` boundary lets the dot separate).
+// An explicit `\s*\(` ensures only an actual call (open paren) is a violation —
+// bare mentions ("never spawns git itself", "spawn failure") stay clean.
+const EXIT_RE = /\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(/g
+
+// Line of match start within a source string.
+function lineAt(src, index) {
+  return (src.slice(0, index).match(/\n/g) || []).length + 1
+}
+
+// Audit a set of sources ({filePath: source}). Returns violations of the git-exit
+// discipline: [{ file, line, snippet }]. git-port.js is exempt (the sole git exit).
+export function checkGitExitDiscipline(sources) {
+  const violations = []
+  for (const file of Object.keys(sources)) {
+    if (join(file).endsWith(GIT_PORT_FILE)) continue // the one sanctioned exit
+    const src = sources[file]
+    EXIT_RE.lastIndex = 0
+    let m
+    while ((m = EXIT_RE.exec(src)) !== null) {
+      const line = lineAt(src, m.index)
+      const lineStart = src.lastIndexOf('\n', m.index) + 1
+      const lineEnd = src.indexOf('\n', m.index)
+      const snippet = src.slice(lineStart, lineEnd === -1 ? src.length : lineEnd).trim()
+      violations.push({ file, line, snippet })
+    }
+  }
+  return violations
+}
+
+// Embedded self-test (T12): pin the audit's behaviour with one positive and one
+// negative sample. Returns 0 on pass, throws/returns non-zero on failure.
+export function selfTest() {
+  const positive = {
+    'lib/tools/worktree-x.js':
+      "import { spawn } from 'node:child_process'\n" +
+      'const child = spawn("git", ["merge", "--abort"])  // must be flagged\n',
+  }
+  const negative = {
+    'lib/git-port.js': "import { spawn } from 'node:child_process'\nconst c = spawn('git', [])\n",
+  }
+
+  const pos = checkGitExitDiscipline(positive)
+  if (pos.length !== 1) {
+    throw new Error(
+      `self-test FAIL: positive sample (spawn in non-git-port lib module) ` +
+        `expected 1 violation, got ${pos.length}`,
+    )
+  }
+  const exp = /lib[/\\]tools[/\\]worktree-x\.js/
+  if (pos[0].file !== 'lib/tools/worktree-x.js' || !pos[0].line || !pos[0].snippet) {
+    throw new Error(`self-test FAIL: positive sample flagged wrong record: ${JSON.stringify(pos[0])}`)
+  }
+  if (!exp.test(pos[0].file)) {
+    throw new Error(`self-test FAIL: expected a lib/tools violation, got ${pos[0].file}`)
+  }
+
+  const neg = checkGitExitDiscipline(negative)
+  if (neg.length !== 0) {
+    throw new Error(
+      `self-test FAIL: negative sample (spawn in git-port.js) expected 0 violations, ` +
+        `got ${neg.length}: ${JSON.stringify(neg)}`,
+    )
+  }
+  return 0
+}
+
+function walk(dir, files) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name)
+    if (entry.isDirectory()) walk(p, files)
+    else if (entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) {
+      files.push(p)
+    }
+  }
+}
+
+function run() {
+  // 1. Syntax-check every module under lib/ and test/.
+  const files = []
+  walk(join(root, 'lib'), files)
+  walk(join(root, 'test'), files)
+  for (const file of files) {
+    execFileSync(process.execPath, ['--check', file], { stdio: 'inherit' })
+  }
+
+  // 2. Git-exit discipline audit over lib/ (all files, including lib/tools/).
+  const dirFiles = []
+  walk(join(root, 'lib'), dirFiles)
+  const sources = {}
+  for (const file of dirFiles) {
+    sources[file] = readFileSync(file, 'utf8')
+  }
+  const violations = checkGitExitDiscipline(sources)
+  if (violations.length > 0) {
+    console.error(`git-exit discipline violation (only ${GIT_PORT_FILE} may spawn):`)
+    for (const { file, line, snippet } of violations) {
+      console.error(`  ${file}:${line}: ${snippet}`)
+    }
+    process.exit(1)
+  }
+
+  // 3. Pin the audit's own behaviour with the embedded positive/negative samples.
+  selfTest()
+
+  console.log(
+    `lint ok: ${files.length} files syntax-checked, ` +
+      `${dirFiles.length} lib sources git-exit-clean, self-test passed`,
+  )
+}
+
+run()