dsh-plugin-worktrees 0.1.0

package/lib/naming.js

@@ -0,0 +1,107 @@
+/**
+ * Naming — pure naming helpers for branch names and worktree paths.
+ *
+ * No IO. All functions are pure and deterministic. Layout and naming follow
+ * DESIGN.md §5.2.1:
+ *  - task branch   : `dsh-wt/<session-short>/<task-slug>`
+ *  - integration   : `dsh-wt/integration/<session-short>`
+ *  - worktree path : `<root>/<repoKey>/<session-short>/<task-slug>`
+ *  - integration worktree path: `<root>/<repoKey>/.integration/<branch-sanitized>-<jobId>`
+ *
+ * `repoIdFromRoot` is a line-for-line port of `repoIdFromRoot` in
+ * task-weaver `packages/workspaces/src/workspace-service.ts` L682-690
+ * (FNV-1a to an 8-hex string; backslash normalisation + trailing-slash strip;
+ * empty-path fallback = the empty FNV-1a result `811c9dc5`).
+ */
+
+import path from 'node:path'
+
+const BRANCH_MAX_LEN = 48
+const SESSION_SHORT_LEN = 8
+
+/**
+ * Sanitise a task slug into a branch-safe token.
+ * `[^a-zA-Z0-9_.-]` → `_`, then truncate to {@link BRANCH_MAX_LEN} chars.
+ * Semantics mirror the char-whitelist idea of merge-queue.ts `sanitize`
+ * (L174-176), length-tuned for branch names (DESIGN §5.2.1).
+ *
+ * @param {string} task raw task slug
+ * @returns {string} sanitised, truncated token
+ */
+export function sanitizeBranch(task) {
+  const tokens = String(task).replace(/[^a-zA-Z0-9_.-]/g, '_')
+  return tokens.slice(0, BRANCH_MAX_LEN)
+}
+
+/** Short stable segment of a session id: the last 8 chars. */
+export function sessionShortOf(sessionId) {
+  if (typeof sessionId !== 'string') {
+    throw new TypeError(`sessionId must be a string, got ${typeof sessionId}`)
+  }
+  return sessionId.slice(-SESSION_SHORT_LEN)
+}
+
+/** Per-task work branch: `dsh-wt/<sessionShort>/<sanitized task>`. */
+export function taskBranch(sessionShort, task) {
+  return `dsh-wt/${sessionShort}/${sanitizeBranch(task)}`
+}
+
+/** Per-session integration branch: `dsh-wt/integration/<sessionShort>`. */
+export function integrationBranch(sessionShort) {
+  return `dsh-wt/integration/${sessionShort}`
+}
+
+/**
+ * Physical worktree path: `<root>/<repoKey>/<sessionShort>/<taskSlug>`.
+ * Built entirely with node:path.join (DESIGN red line 2).
+ *
+ * @param {string} worktreeRoot base directory (e.g. `~/.dsh/worktrees/`)
+ * @param {string} repoKey stable repo id from {@link repoIdFromRoot}
+ * @param {string} sessionShort short session segment
+ * @param {string} taskSlug branch-safe task slug (already sanitised)
+ * @returns {string} joined path
+ */
+export function worktreePath(worktreeRoot, repoKey, sessionShort, taskSlug) {
+  return path.join(worktreeRoot, repoKey, sessionShort, taskSlug)
+}
+
+/**
+ * Temporary integration worktree path for one apply:
+ * `<root>/<repoKey>/.integration/<branchSanitized>-<jobId>`.
+ * Uniqueness borrows the `Date.now().toString(36) + random` idea of the source
+ * worktreePath (L638-641) but uses the deterministic jobId (DESIGN §5.2.1).
+ */
+export function integrationWorktreePath(
+  worktreeRoot,
+  repoKey,
+  branchSanitized,
+  jobId,
+) {
+  return path.join(worktreeRoot, repoKey, '.integration', `${branchSanitized}-${jobId}`)
+}
+
+/**
+ * Derive a short stable repo id from an absolute project root. Uses a
+ * truncated FNV-1a hash of the normalised path so the worktree parent
+ * directory is stable across runs but does not leak the full path.
+ *
+ * Ported verbatim from task-weaver
+ * `packages/workspaces/src/workspace-service.ts` L682-690. Backslashes are
+ * normalised to `/`, a single trailing slash is stripped, then FNV-1a
+ * (init `0x811c9dc5`, prime `0x01000193`) over UTF-16 char codes, truncated
+ * to 8 lowercase hex chars. Empty/whitespace-only path yields the empty FNV-1a
+ * initial value `811c9dc5`.
+ *
+ * @param {string} root absolute root path
+ * @returns {string} 8-char hex repo id
+ */
+export function repoIdFromRoot(root) {
+  const normalised = root.replace(/\\/g, '/').replace(/\/+$/, '')
+  let hash = 0x811c9dc5
+  for (let i = 0; i < normalised.length; i++) {
+    hash ^= normalised.charCodeAt(i)
+    hash = (hash * 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}
+

package/lib/repo-gate.js

@@ -0,0 +1,202 @@
+/**
+ * Repo root resolution + registration gate (DESIGN.md §5.2.0).
+ *
+ * SECURITY-CRITICAL: every worktree tool funnels the caller-supplied repo
+ * root through {@link resolveRepoRoot} before touching git. The gate
+ * canonicalises the path (realpath — symlinks and `..` segments collapse to
+ * the real on-disk location, same normalization as the aionui-panel
+ * workspace gate `gate.ts` L57-60), verifies it is a git work tree via the
+ * injected GitPort, and only then admits it when it lives inside the parent
+ * session cwd subtree, a registered workspace path, or an explicitly
+ * configured allowed root. Everything else fails closed.
+ *
+ * There is NO any-root switch by design (DESIGN §5.2.0: fail closed is the
+ * default; widening the gate must go through the explicit `allowedRoots`
+ * list).
+ */
+
+import { realpath } from 'node:fs/promises'
+import path from 'node:path'
+import { repoIdFromRoot } from './naming.js'
+
+/** Separator used after normalization (win32 backslashes fold onto this). */
+const SEP = '/'
+
+/**
+ * Canonical prefix check: `child` must live inside (or equal) `parent`.
+ *
+ * Ported from the aionui-panel workspace gate (`gate.ts` `isPathInside`
+ * L28-41) with the DESIGN §5.2.0 adjustment: both sides go through
+ * `path.normalize` first, then trailing separators are stripped, and on
+ * win32 backslashes fold onto `/` (path.join yields backslashes while git
+ * `rev-parse --show-toplevel` may yield forward slashes) and the comparison
+ * is case-insensitive (the Windows filesystem is case-insensitive). On POSIX
+ * the backslash is a legal filename character, so it is compared literally —
+ * the fold only happens on win32.
+ *
+ * Boundary semantics:
+ *  - `parent === child` → true (repo root == cwd is a legal scenario);
+ *  - a prefix match must land on a directory boundary — `/a/b` does NOT
+ *    contain `/a/bc` (sibling), only `/a/b/...`;
+ *  - trailing separators are normalized on both sides (`/a/b/` ≡ `/a/b`).
+ *
+ * @param {string} parent candidate container path
+ * @param {string} child candidate contained path
+ * @returns {boolean} true when child is parent or lives under parent
+ */
+export function isPathInside(parent, child) {
+  if (typeof parent !== 'string' || typeof child !== 'string') {
+    return false
+  }
+  if (parent === '' || child === '') return false
+  const norm = (value) => {
+    let n = path.normalize(value)
+    if (process.platform === 'win32') {
+      n = n.replaceAll('\\', SEP)
+    }
+    return n.replace(/\/+$/, '')
+  }
+  const p = norm(parent)
+  const c = norm(child)
+  if (process.platform === 'win32') {
+    const a = p.toLowerCase()
+    const b = c.toLowerCase()
+    if (b === a) return true
+    return b.startsWith(a + SEP)
+  }
+  if (c === p) return true
+  return c.startsWith(p + SEP)
+}
+
+/**
+ * realpath that never throws: an unresolvable root NEVER grants access
+ * (fail closed), it is simply skipped as a gate candidate.
+ *
+ * @param {unknown} p candidate path (type-vetted)
+ * @returns {Promise<string|null>} canonical path, or null when unresolvable
+ */
+async function realpathBestEffort(p) {
+  if (typeof p !== 'string' || p === '') return null
+  try {
+    return await realpath(p)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Accept an array or a single value; anything else becomes an empty list.
+ *
+ * @template T
+ * @param {T | T[] | undefined | null} v
+ * @returns {T[]}
+ */
+function toList(v) {
+  if (v === undefined || v === null) return []
+  if (Array.isArray(v)) return v
+  return [v]
+}
+
+/**
+ * Resolve and gate a repo root (DESIGN §5.2.0).
+ *
+ * Order of checks — each failure mode has a stable error-code prefix the
+ * tool layer matches on:
+ *  1. `repoArg` missing → fall back to `sessionCwd`; both missing →
+ *     `repo_unresolved` (demand an explicit repo_root);
+ *  2. `realpath(repoArg)` failure → `repo_unknown` (path does not resolve
+ *     on disk);
+ *  3. `git.isGitRepo(canonical)` false → `not_a_git_repo` (checked BEFORE
+ *     the gate so a plain directory inside an allowed subtree is still
+ *     rejected);
+ *  4. gate, in order, any pass admits:
+ *     a. canonical inside the `sessionCwd` subtree,
+ *     b. canonical inside any `workspacePaths` entry,
+ *     c. canonical inside any `allowedRoots` entry;
+ *  5. no pass → `repo_not_registered` (report canonical + guidance:
+ *     register a workspace or configure allowedRoots).
+ *
+ * Git access goes ONLY through the injected `git` port (`isGitRepo`); this
+ * module never spawns git itself.
+ *
+ * @param {{
+ *   repoArg?: string,
+ *   sessionCwd?: string,
+ *   workspacePaths?: string[],
+ *   allowedRoots?: string[],
+ *   git?: { isGitRepo: (cwd: string) => Promise<boolean> },
+ * }} opts
+ * @returns {Promise<{ canonical: string, repoKey: string }>} canonical repo
+ *   root + stable 8-hex repo key (same repo → same key across runs;
+ *   worktrees share the parent repo key)
+ * @throws {Error} message starts with `repo_unresolved` / `repo_unknown` /
+ *   `not_a_git_repo` / `repo_not_registered`
+ */
+export async function resolveRepoRoot(opts = {}) {
+  const { repoArg, sessionCwd, workspacePaths, allowedRoots, git } = opts
+
+  // 1. repoArg 缺省 → sessionCwd；仍缺 → repo_unresolved。
+  let target = repoArg
+  if (target === undefined || target === null || target === '') {
+    target = sessionCwd
+  }
+  if (target === undefined || target === null || target === '') {
+    throw new Error(
+      'repo_unresolved: no repo_root argument and no session cwd available; ' +
+        'pass an explicit repo_root (the repository root path)',
+    )
+  }
+
+  // 2. 符号链接 / `..` 规范化；磁盘上不存在 → repo_unknown。
+  let canonical
+  try {
+    canonical = await realpath(target)
+  } catch {
+    throw new Error(`repo_unknown: path does not resolve on disk: ${target}`)
+  }
+
+  // git port 是唯一 git 入口；缺席即编程错误，fail closed。
+  if (!git || typeof git.isGitRepo !== 'function') {
+    throw new Error(
+      'repo_gate: a git port with isGitRepo(cwd) must be injected',
+    )
+  }
+
+  // 3. 门禁前先查 git：普通目录即使落在允许子树内也要拒绝。
+  const isRepo = await git.isGitRepo(canonical)
+  if (!isRepo) {
+    throw new Error(`not_a_git_repo: ${canonical} is not inside a git work tree`)
+  }
+
+  // 4. 门禁按序判定（任一通过即可）。
+  //   a. 父会话 cwd 子树（cwd 同样 realpath，best-effort）。
+  if (typeof sessionCwd === 'string' && sessionCwd !== '') {
+    const cwdCanonical = await realpathBestEffort(sessionCwd)
+    if (cwdCanonical !== null && isPathInside(cwdCanonical, canonical)) {
+      return { canonical, repoKey: repoIdFromRoot(canonical) }
+    }
+  }
+
+  //   b. 任一注册 workspace 路径包含 canonical。
+  for (const workspacePath of toList(workspacePaths)) {
+    const rootCanonical = await realpathBestEffort(workspacePath)
+    if (rootCanonical !== null && isPathInside(rootCanonical, canonical)) {
+      return { canonical, repoKey: repoIdFromRoot(canonical) }
+    }
+  }
+
+  //   c. 任一 allowedRoots 根包含 canonical。
+  for (const allowedRoot of toList(allowedRoots)) {
+    const rootCanonical = await realpathBestEffort(allowedRoot)
+    if (rootCanonical !== null && isPathInside(rootCanonical, canonical)) {
+      return { canonical, repoKey: repoIdFromRoot(canonical) }
+    }
+  }
+
+  // 5. 全不通过 → fail closed（无 any-root 开关）。
+  throw new Error(
+    `repo_not_registered: ${canonical} is not inside the session cwd ` +
+      'subtree, a registered workspace path, or an allowed root; register ' +
+      'the repository as a workspace or add its parent to allowedRoots',
+  )
+}