dsh-plugin-worktrees 0.1.0

package/lib/index.js

@@ -0,0 +1,402 @@
+/**
+ * dsh-worktrees — apply() assembly (T10, DESIGN §3 / §7.3 / §8.1 / §8.4).
+ *
+ * Single instance: git port / StateStore / WorktreeService / MergeQueue are
+ * created exactly once inside the apply() closure (red line: shared state is
+ * held by the single instance — the same discipline as the engine layer's
+ * "no host service imports" seam for a future dag-orchestrator, §10).
+ *
+ * apply() order (DESIGN §3 diagram + §7.3 "before tool registration"):
+ *
+ *   a. validateConfig (lib/config.js zod strict; unknown keys fail loud);
+ *   b. assertSingleDshToolsInstance — the @deepseek-ai/dsh-tools dual-
+ *      instance self-check (§8.4, pattern carried over verbatim from
+ *      dsh-plugin-subagents lib/index.js): the host ToolRuntime carries its
+ *      scheduler under the dsh-tools module-level TOOL_RUNTIME_SCHEDULER
+ *      Symbol; a second physical copy of the package makes
+ *      `ctx.tools[Symbol]` undefined and every tool call dies with
+ *      "Cannot read properties of undefined (reading 'prepare')" — fatal at
+ *      apply time, with the setup:peer re-link hint;
+ *   c. createGitPort (timeoutMs = gitTimeoutMs) + createStateStore +
+ *      store.load() (a corrupt state file aborts the boot loudly);
+ *   d. reconcile — the crash reconciliation (§7.3), BEFORE any tool is
+ *      registered, so the first model-visible call already sees a truthful
+ *      state: per repo — unreachable repo ⇒ `orphaned: true` MARKER on its
+ *      worktree records (state kept verbatim — orphaned is a §5.4 flag, not
+ *      a §5.2.2 state) + applying jobs failed; reachable repo ⇒ records
+ *      whose path left `git worktree list` become `vanished`, applying jobs
+ *      become failed (their still-live integration worktree retained for
+ *      inspection), conflicted jobs survive verbatim, and orphan
+ *      `.integration/` worktrees are best-effort removed;
+ *   e. createWorktreeService + createMergeQueue over the SAME store/git,
+ *      then provide the §10 `worktreesEngine` service face (the DAG
+ *      composition seam) over those same singletons;
+ *   f. the §5.2.0 gate prebound once (workspaceRegistry probed OPTIONALLY —
+ *      it is not in `inject`, so headless hosts degrade to the session-cwd
+ *      + allowedRoots arms) and shared by all six tools;
+ *   g. register the six tools per the register switches (default all on).
+ *
+ * Return value: ALWAYS undefined — the loader treats the plugin callback's
+ * return as a disposable (a non-nullable non-function fails real boots with
+ * "TypeError: Invalid effect"). Introspection goes through the registered
+ * tools (fake ctx) or the internal modules, never the return value.
+ */
+
+import { TOOL_RUNTIME_SCHEDULER } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { realpathSync } from 'node:fs'
+import { validateConfig } from './config.js'
+import { createGitPort } from './git-port.js'
+import { createStateStore, ACTIVE_JOB_STATES } from './state-store.js'
+import { createWorktreeService } from './worktree-service.js'
+import { createMergeQueue } from './merge-queue.js'
+import { createEngineFace } from './engine-face.js'
+import { resolveRepoRoot } from './repo-gate.js'
+import { registerWorktreeCreateTool } from './tools/worktree-create.js'
+import { registerWorktreeListTool } from './tools/worktree-list.js'
+import { registerWorktreeStatusTool } from './tools/worktree-status.js'
+import { registerWorktreeMergeTool } from './tools/worktree-merge.js'
+import { registerWorktreeQueueTool } from './tools/worktree-queue.js'
+import { registerWorktreeCleanupTool } from './tools/worktree-cleanup.js'
+
+export const name = 'dsh-worktrees'
+
+// workspaceRegistry is used through OPTIONAL probing (§8.2 peer-face
+// minimisation: headless hosts without a workspace registry still boot) —
+// only `tools` is a hard injection.
+export const inject = ['tools']
+
+/** Error message of an unknown throw. */
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error ?? '')
+}
+
+/** realpath() that yields null instead of throwing (missing-path probe). */
+function realPathBestEffort(target) {
+  try {
+    return realpathSync(target)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * dsh-tools dual-instance self-check (§8.4; the verbatim probe pattern from
+ * dsh-plugin-subagents lib/index.js):
+ *
+ *   1. `ctx.tools[TOOL_RUNTIME_SCHEDULER] !== undefined` → same physical
+ *      module — healthy;
+ *   2. Symbol absent but ctx.tools looks like a real ToolRuntime
+ *      (view + schemas) → a true second copy: logger.fatal + throw (apply
+ *      failing beats every tool call dying after load), pointing at the
+ *      peer re-link (npm run setup:peer);
+ *   3. anything else (fake ctx / an unseen host shape) → cannot reliably
+ *      judge; warn only. Tests and non-standard hosts must not be killed by
+ *      a false positive.
+ */
+function assertSingleDshToolsInstance(ctx) {
+  const tools = ctx && ctx.tools
+  if (!tools || typeof tools.register !== 'function') return
+  if (tools[TOOL_RUNTIME_SCHEDULER] !== undefined) return // same physical module — healthy
+  const looksLikeToolRuntime =
+    typeof tools.view === 'function' && typeof tools.schemas === 'function'
+  if (looksLikeToolRuntime) {
+    const detail =
+      'dsh-worktrees: detected a second @deepseek-ai/dsh-tools module instance — '
+      + "every tool call from this plugin would die with \"Cannot read properties of undefined (reading 'prepare')\". "
+      + 'Run npm run setup:peer (scripts/link-harness-dsh-tools.sh) in the dsh-worktrees package '
+      + 'so its dsh-tools copy resolves to the live harness root, then restart dsh.'
+    if (ctx.logger && typeof ctx.logger.fatal === 'function') ctx.logger.fatal(detail)
+    throw new Error(detail)
+  }
+  if (ctx.logger && typeof ctx.logger.warn === 'function') {
+    ctx.logger.warn(
+      'dsh-worktrees: could not reliably verify the @deepseek-ai/dsh-tools single-instance invariant '
+        + 'from this ctx (no scheduler symbol, no ToolRuntime shape) — run npm run setup:peer to check the dedupe link',
+    )
+  }
+}
+
+/**
+ * Probe the OPTIONAL workspace registry (§5.2.0 gate arm b): absent host
+ * face, non-array result, or a throwing list() all degrade to [] (the gate
+ * then runs on the session-cwd + allowedRoots arms alone).
+ */
+function probeWorkspacePaths(ctx) {
+  try {
+    const list = ctx && ctx.workspaceRegistry ? ctx.workspaceRegistry.list : undefined
+    if (typeof list !== 'function') return []
+    const entries = list.call(ctx.workspaceRegistry)
+    if (!Array.isArray(entries)) return []
+    return entries
+      .map((entry) => (entry && typeof entry === 'object' ? entry.path : undefined))
+      .filter((p) => typeof p === 'string' && p.length > 0)
+  } catch {
+    return []
+  }
+}
+
+/** True when a stored path matches the live set (raw OR realpath form). */
+function pathInLiveSet(storedPath, liveSet) {
+  if (liveSet.has(storedPath)) return true
+  const real = realPathBestEffort(storedPath)
+  return real !== null && liveSet.has(real)
+}
+
+/**
+ * Crash reconciliation for ONE repo (DESIGN §7.3, step by step).
+ *
+ * Marking only — the ONE destructive action is the best-effort removal of
+ * orphan integration worktrees; everything destructive stays behind the
+ * explicit worktree_cleanup tool.
+ *
+ * @param {object} args { ctx, cfg, git, store, repoKey, repoRoot }
+ */
+async function reconcileRepo({ ctx, cfg, git, store, repoKey, repoRoot }) {
+  const recordsOfRepo = () =>
+    Object.values(store.worktrees).filter((record) => record.repoKey === repoKey)
+  const jobsOfRepo = () => Object.values(store.jobs).filter((job) => job.repoKey === repoKey)
+
+  // §7.3 branch 1 — repo unreachable (deleted / unmounted / not a git repo):
+  // every worktree record gets the `orphaned: true` MARKER with its state
+  // kept verbatim (orphaned is the §5.4 flag, not a §5.2.2 state — writing
+  // it into `state` would break the state machine), and applying jobs fail
+  // with the restart provenance.
+  if (!(await git.isGitRepo(repoRoot))) {
+    for (const record of recordsOfRepo()) {
+      if (record.orphaned === true) continue
+      store.upsertWorktree({ ...record, orphaned: true })
+    }
+    for (const job of jobsOfRepo()) {
+      if (job.state !== 'applying') continue
+      store.upsertJob({ ...job, state: 'failed', error: 'host restart; repo unreachable' })
+    }
+    return
+  }
+
+  // §7.3 branch 2 — repo reachable: reconcile against the LIVE worktree
+  // list (git-port returns the parsed entries already).
+  const live = await git.listWorktrees(repoRoot)
+  const livePaths = new Set(live.map((entry) => entry.path))
+
+  // (a) vanished: record present, scene gone (manual prune / disk cleared).
+  // A record that is live again sheds a stale persisted orphaned marker
+  // (the marker would otherwise leak through every later list projection).
+  for (const record of recordsOfRepo()) {
+    const liveNow = pathInLiveSet(record.path, livePaths)
+    if (!liveNow) {
+      if (record.state !== 'vanished') {
+        store.upsertWorktree({ ...record, state: 'vanished' })
+      }
+    } else if (record.orphaned !== undefined) {
+      const { orphaned, ...rest } = record
+      void orphaned
+      store.upsertWorktree({ ...rest, state: rest.state })
+    }
+  }
+
+  // (b) applying jobs: the apply died with the host. Failed + provenance;
+  // a still-live integration worktree is RETAINED and annotated (§6.3's
+  // write-ahead means the record already points at the partial scene — the
+  // operator may inspect it). The task record mirrors merging → active,
+  // the same transition the engine's own failure path makes (markFailedOutcome).
+  const retainedForInspection = new Set()
+  for (const job of jobsOfRepo()) {
+    if (job.state !== 'applying') continue
+    let error =
+      'host restarted during apply — the recorded integrationWorktree may hold a partial state'
+    if (
+      typeof job.integrationWorktree === 'string'
+      && job.integrationWorktree.length > 0
+      && pathInLiveSet(job.integrationWorktree, livePaths)
+    ) {
+      retainedForInspection.add(
+        realPathBestEffort(job.integrationWorktree) ?? job.integrationWorktree,
+      )
+      error += `; the integration worktree is retained at ${job.integrationWorktree} for inspection`
+    }
+    store.upsertJob({ ...job, state: 'failed', error })
+    const taskRecord = job.worktreeId ? store.worktrees[job.worktreeId] : undefined
+    if (taskRecord !== undefined && taskRecord.repoKey === repoKey && taskRecord.state === 'merging') {
+      store.upsertWorktree({ ...taskRecord, state: 'active' })
+    }
+  }
+
+  // (c) conflicted jobs survive verbatim — the retained scene IS the job's
+  // state (source semantics); nothing to do, stated explicitly.
+
+  // (d) orphan integration worktrees: live paths inside OUR
+  // `<worktreeRoot>/<repoKey>/.integration` namespace (realpath-compared —
+  // git reports realpaths while worktreeRoot may be a symlinked prefix)
+  // that no non-terminal job references. Best-effort removal, failures
+  // swallowed. Worktrees referenced by a job failed in THIS pass are
+  // protected: the error text just promised the operator an inspection
+  // scene — deleting it in the same breath would falsify it. On a later
+  // run (no applying jobs) such a path is a plain orphan and is reclaimed,
+  // mirroring the engine's releaseStaleIntegrationHolds (only live
+  // conflicted scenes persist indefinitely).
+  const namespaceReal = realPathBestEffort(path.join(cfg.worktreeRoot, repoKey, '.integration'))
+  if (namespaceReal !== null) {
+    const referenced = new Set(retainedForInspection)
+    for (const job of jobsOfRepo()) {
+      if (!ACTIVE_JOB_STATES.has(job.state)) continue
+      if (typeof job.integrationWorktree === 'string' && job.integrationWorktree.length > 0) {
+        referenced.add(realPathBestEffort(job.integrationWorktree) ?? job.integrationWorktree)
+      }
+    }
+    for (const entry of live) {
+      if (path.dirname(entry.path) !== namespaceReal) continue
+      if (referenced.has(entry.path)) continue
+      await git.removeWorktree(repoRoot, entry.path).catch(() => {})
+    }
+  }
+}
+
+/**
+ * The crash reconciliation pass (§7.3): per-repo reconcile with per-repo
+ * isolation — one broken repo (a probe failure, a git error) logs a warning
+ * and never aborts the whole apply. One persist at the end flushes every
+ * marking this pass made.
+ */
+async function reconcile({ ctx, cfg, git, store }) {
+  for (const [repoKey, repo] of Object.entries(store.repos)) {
+    const repoRoot = repo && typeof repo.root === 'string' ? repo.root : ''
+    if (repoRoot === '') {
+      ctx.logger?.warn?.(`dsh-worktrees: reconcile skipped for repo ${repoKey} (no root recorded)`)
+      continue
+    }
+    try {
+      await reconcileRepo({ ctx, cfg, git, store, repoKey, repoRoot })
+    } catch (error) {
+      ctx.logger?.warn?.(
+        `dsh-worktrees: reconcile skipped for repo ${repoKey} (${repoRoot}): ${errorText(error)}`,
+      )
+    }
+  }
+  store.persist()
+}
+
+/**
+ * Plugin entry (T10). See the module header for the assembly order.
+ *
+ * @param {Object} ctx Cordis ctx (needs ctx.tools.register; logger +
+ *                     workspaceRegistry are optional faces)
+ * @param {Object} [config] raw plugin config (validated here; zod strict)
+ * @returns {Promise<undefined>} always undefined — the loader treats the
+ *          plugin callback's return value as a disposable
+ */
+export async function apply(ctx, config = {}) {
+  // a. config (zod strict, defaults resolved — lib/config.js)
+  const cfg = validateConfig(config)
+
+  // b. peer dual-instance defence (§8.4)
+  assertSingleDshToolsInstance(ctx)
+
+  // c. engine singletons — created exactly once per apply() closure
+  const git = createGitPort({ timeoutMs: cfg.gitTimeoutMs })
+  const store = createStateStore({ path: cfg.statePath })
+  store.load() // loud on a corrupt state file: a bad boot beats silent garbage
+
+  // d. crash reconciliation BEFORE any tool registration (§7.3)
+  await reconcile({ ctx, cfg, git, store })
+
+  // e. shared engines over the same store/git singletons. The queue's
+  // swallowed background-drain failures surface through the host logger.
+  const service = createWorktreeService({ git, store, config: cfg })
+  const queue = createMergeQueue({
+    git,
+    store,
+    config: {
+      ...cfg,
+      onError: (message) => {
+        try {
+          ctx.logger?.warn?.(message)
+        } catch {
+          /* logging must never throw */
+        }
+      },
+    },
+  })
+
+  // e2. the §10 composition seam: provide `worktreesEngine` on the ctx so
+  //     dsh-dag-orchestrator's opportunistic `ctx.get('worktreesEngine')`
+  //     probe finds the SAME service/queue singletons the tools use (red
+  //     line 10: no second write entrance). The face adapts the DAG's
+  //     four-key enqueue / five-state DrainOutcome dialect on top of the
+  //     live engines (lib/engine-face.js) — the tool-layer contracts stay
+  //     untouched. provide() is probed: a host ctx without the service
+  //     face (fakes) degrades silently.
+  try {
+    if (ctx && typeof ctx.provide === 'function') {
+      ctx.provide(
+        'worktreesEngine',
+        createEngineFace({ service, queue, store, git, engineSessionId: 'dsh-dag-engine' }),
+      )
+    }
+  } catch (error) {
+    ctx.logger?.warn?.(
+      `dsh-worktrees: could not provide the worktreesEngine service face: ${errorText(error)}`,
+    )
+  }
+
+  // f. the §5.2.0 gate, prebound ONCE and shared by every tool. The tools
+  // pass { repoArg, sessionCwd } (sessionCwd extracted from their exec);
+  // workspacePaths comes from the OPTIONAL registry probe. With
+  // requireWorkspaceRegistration === false the workspace arm is disabled —
+  // an empty list can never admit, which is exactly "skip that tier" (the
+  // session-cwd and allowedRoots arms still apply; fail-closed default).
+  const workspacePaths = probeWorkspacePaths(ctx)
+  const gatedWorkspacePaths = cfg.requireWorkspaceRegistration === false ? [] : workspacePaths
+  const resolveRepo = (opts) =>
+    resolveRepoRoot({
+      repoArg: opts.repoArg,
+      sessionCwd: opts.sessionCwd,
+      workspacePaths: gatedWorkspacePaths,
+      allowedRoots: cfg.allowedRoots,
+      git,
+    })
+
+  // g. register the six tools per the register switches (default all on).
+  // deps shape per each tool's own contract (service/queue/store +
+  // resolveRepo; the git+cfg fallback stays available for parity).
+  const shared = {
+    service,
+    queue,
+    store,
+    git,
+    cfg: { workspacePaths: gatedWorkspacePaths, allowedRoots: cfg.allowedRoots },
+    resolveRepo,
+  }
+  let registered = 0
+  if (cfg.register.create) {
+    registerWorktreeCreateTool(ctx, shared)
+    registered += 1
+  }
+  if (cfg.register.list) {
+    registerWorktreeListTool(ctx, shared)
+    registered += 1
+  }
+  if (cfg.register.status) {
+    registerWorktreeStatusTool(ctx, shared)
+    registered += 1
+  }
+  if (cfg.register.merge) {
+    registerWorktreeMergeTool(ctx, shared)
+    registered += 1
+  }
+  if (cfg.register.queue) {
+    registerWorktreeQueueTool(ctx, shared)
+    registered += 1
+  }
+  if (cfg.register.cleanup) {
+    registerWorktreeCleanupTool(ctx, shared)
+    registered += 1
+  }
+
+  ctx.logger?.info?.(
+    `dsh-worktrees: applied (${registered} tool${registered === 1 ? '' : 's'}; `
+      + `state ${cfg.statePath}; worktree root ${cfg.worktreeRoot})`,
+  )
+
+  return undefined
+}