dsh-plugin-worktrees 0.1.0

package/lib/tools/worktree-create.js

@@ -0,0 +1,212 @@
+/**
+ * `worktree_create` tool (T07, DESIGN §5.3).
+ *
+ * Thin tool layer — parameters schema, the §5.2.0 repo-gate call, and a
+ * projection of the WorktreeService.create record into the §5.3 return
+ * shape. No git calls and no state writes happen here: the engine is the
+ * injected `service` (lib/worktree-service.js) and the repo gate is the
+ * injected `resolveRepo` (or a real resolveRepoRoot binding built from the
+ * injected `git` port + `cfg`), exactly the deps T10's apply() assembles.
+ *
+ * deps contract:
+ *  - service     (required) createWorktreeService() product;
+ *  - resolveRepo (optional) async ({ repoArg, sessionCwd }) =>
+ *                 { canonical, repoKey } — a T10-prebound §5.2.0 gate;
+ *  - git + cfg   (fallback) when resolveRepo is absent, the REAL gate is
+ *                 bound here from the injected GitPort plus
+ *                 cfg.workspacePaths / cfg.allowedRoots;
+ *  - sessionCwd  (optional) fallback when the calling exec carries no
+ *                 session header cwd;
+ *  - sessionId   (optional) fallback when exec.agent.session.id is absent.
+ *
+ * json-safe discipline (E3): the return object is built with conditional
+ * spreads only — no key ever carries an `undefined` value.
+ *
+ * Error policy: engine/gate errors already start with a machine-matchable
+ * code (`branch_exists — …`, `repo_not_registered: …`) and are re-thrown
+ * untouched; anything uncoded gets a `worktree_create:` prefix so the
+ * surfaced message always names the tool.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { resolveRepoRoot } from '../repo-gate.js'
+
+/** Registered tool name (DESIGN §5.3). */
+const TOOL_NAME = 'worktree_create'
+
+/** A message already starting with a stable snake_case code stays verbatim. */
+const CODED_MESSAGE = /^[a-z][a-z0-9_]*(\s*—|:)/
+
+/**
+ * Error surfacing (DESIGN §5.3 error family): coded engine/gate errors pass
+ * through unchanged; uncoded ones (e.g. a TypeError from a bad wiring) get
+ * the tool-name prefix.
+ */
+function surfaceError(error) {
+  const message = String(error instanceof Error ? error.message : error)
+  if (CODED_MESSAGE.test(message)) throw error
+  throw new Error(`${TOOL_NAME}: ${message}`)
+}
+
+/**
+ * Bind the §5.2.0 repo gate. Prefer a T10-injected `resolveRepo`; otherwise
+ * build the real `resolveRepoRoot` binding from the injected git port and
+ * cfg. This module never spawns git itself — the gate is the only seam.
+ */
+function makeRepoResolver(deps) {
+  if (typeof deps.resolveRepo === 'function') return deps.resolveRepo
+  const { git, cfg = {} } = deps
+  if (!git || typeof git.isGitRepo !== 'function') {
+    throw new Error(
+      `${TOOL_NAME}: deps must carry either resolveRepo(opts) or a git port with isGitRepo(cwd) so the repo gate can be bound`,
+    )
+  }
+  return (opts) =>
+    resolveRepoRoot({
+      repoArg: opts.repoArg,
+      sessionCwd: opts.sessionCwd,
+      workspacePaths: cfg.workspacePaths,
+      allowedRoots: cfg.allowedRoots,
+      git,
+    })
+}
+
+/** §5.3 composition example, appended verbatim to the description. */
+const COMPOSITION_EXAMPLE =
+  'Composition example: '
+  + '1. worktree_create(task: "api-types") → path P1; '
+  + '2. worktree_create(task: "docs-refresh") → path P2; '
+  + '3. subagent(prompt: "…implement X…", cwd: P1) and subagent(prompt: "…update docs…", cwd: P2) in parallel — each task writes in its own worktree, no overlap; '
+  + '4. worktree_merge(worktree_id: id1) → succeeded; '
+  + '5. worktree_merge(worktree_id: id2) → conflicted (conflict list + retained scene); '
+  + '6. worktree_queue(action: "list") → observe, resolve out-of-band in the retained worktree; '
+  + '7. worktree_queue(action: "resolve", job_id: …) → release the integration branch; '
+  + '8. worktree_queue(action: "retry", job_id: …) → re-queue (optional alternative); '
+  + '9. worktree_cleanup(worktree_id: id1) → remove the merged worktree and its branch.'
+
+/**
+ * Register the `worktree_create` tool (DESIGN §5.3).
+ *
+ * @param {Object} ctx host ctx (needs ctx.tools.register)
+ * @param {Object} deps see the module header for the contract
+ */
+export function registerWorktreeCreateTool(ctx, deps = {}) {
+  const { service } = deps
+  if (!service || typeof service.create !== 'function') {
+    throw new Error(
+      `${TOOL_NAME}: deps.service must be a WorktreeService (createWorktreeService product)`,
+    )
+  }
+  const resolveRepo = makeRepoResolver(deps)
+
+  ctx.tools.register(defineTool({
+    name: TOOL_NAME,
+    description:
+      'Create an isolated git worktree for ONE parallel task: a dedicated branch dsh-wt/<session-short>/<task> checked out at a private path under the plugin worktree root, so concurrently dispatched subagents never write into the same working directory. '
+      + 'The base ref is resolved to a concrete commit oid at create time (never a mutable HEAD), and the returned path is where the task must do all of its work. '
+      + COMPOSITION_EXAMPLE,
+    parameters: {
+      task: {
+        type: 'string',
+        required: true,
+        description:
+          'Short task slug identifying the parallel task this worktree isolates (e.g. "refactor-auth", "fix-231"). Sanitized into the branch name dsh-wt/<session>/<task>.',
+      },
+      repo_root: {
+        type: 'string',
+        description:
+          'Absolute git repository root. Defaults to the current session working directory. Must resolve inside a registered workspace, the session cwd subtree, or a configured allowedRoot.',
+      },
+      base_ref: {
+        type: 'string',
+        description:
+          'Git ref to branch from (branch / tag / commit oid / HEAD). Defaults to HEAD of the repository. Never falls back to a mutable HEAD when the queue expects a fixed base.',
+      },
+      integration_branch: {
+        type: 'string',
+        description:
+          'Branch that worktree_merge will integrate into (default: dsh-wt/integration/<session>, bootstrapped from repo HEAD on first merge). Must not be a branch already checked out in another worktree of this repo.',
+      },
+      note: {
+        type: 'string',
+        description: 'Optional free-text note stored on the worktree record.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          kind: { type: 'string', required: true, const: 'worktree' },
+          id: { type: 'string', required: true },
+          repo_root: { type: 'string', required: true },
+          branch: { type: 'string', required: true },
+          path: { type: 'string', required: true },
+          base_commit: { type: 'string', required: true },
+          integration_branch: { type: 'string', required: true },
+          delegate_hint: { type: 'string', required: true },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `created worktree ${value.id} (branch ${value.branch}) at ${value.path}; delegate via the subagent tool with cwd: ${value.path}`,
+      }],
+    },
+    // State write with a check-then-act section (the maxWorktrees gate), so
+    // sibling calls must not overlap (undeclared would mean the same — this
+    // is just explicit; DESIGN §7.2 reserves the writeup for worktree_merge).
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      try {
+        const session = exec && exec.agent ? exec.agent.session : undefined
+        const sessionCwd =
+          (session && session.header && session.header.cwd) || deps.sessionCwd
+
+        // §5.2.0 gate FIRST (its repo_unresolved / repo_unknown /
+        // not_a_git_repo / repo_not_registered codes are the tool's front
+        // door), then the session-id requirement the branch name derives
+        // from.
+        const { canonical, repoKey } = await resolveRepo({
+          repoArg: args.repo_root,
+          ...(sessionCwd !== undefined ? { sessionCwd } : {}),
+        })
+
+        const sessionId = (session && session.id) || deps.sessionId
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+          throw new Error(
+            `${TOOL_NAME}: session_unresolved — no calling agent session id (exec.agent.session.id) and none injected; the task branch name derives from it`,
+          )
+        }
+
+        const record = await service.create({
+          task: args.task,
+          repoRoot: canonical,
+          repoKey,
+          ...(args.base_ref !== undefined ? { baseRef: args.base_ref } : {}),
+          ...(args.integration_branch !== undefined
+            ? { integrationBranch: args.integration_branch }
+            : {}),
+          ...(args.note !== undefined ? { note: args.note } : {}),
+          sessionId,
+        })
+
+        return {
+          kind: 'worktree',
+          id: record.id,
+          repo_root: record.repoRoot,
+          branch: record.branch,
+          path: record.path,
+          base_commit: record.baseCommit,
+          integration_branch: record.integrationBranch,
+          delegate_hint:
+            `Delegate parallel work here via the subagent tool with cwd: ${record.path} `
+            + '(each parallel task gets its own worktree; integrate with worktree_merge).',
+          ...(typeof record.note === 'string' ? { note: record.note } : {}),
+        }
+      } catch (error) {
+        surfaceError(error)
+      }
+    },
+  }))
+}

package/lib/tools/worktree-list.js

@@ -0,0 +1,234 @@
+/**
+ * `worktree_list` tool (T07, DESIGN §5.4).
+ *
+ * Thin tool layer: parameters schema, the §5.2.0 repo-gate call (repo_root
+ * is resolved + admitted so the filter is a canonical path), the §5.4
+ * worktree/queue projections, and the `include_integration` extension that
+ * surfaces conflict-retained integration worktrees. No git calls, no state
+ * writes — `service.list` (engine) and the injected `store` (read-only
+ * projections the service does not expose) are the only collaborators.
+ *
+ * deps contract:
+ *  - service     (required) createWorktreeService() product;
+ *  - store       (optional, needed for include_integration) the SAME
+ *                 StateStore instance the service was built with (read-only
+ *                 access for the retained-worktree projection);
+ *  - resolveRepo (optional) prebound §5.2.0 gate ({ repoArg, sessionCwd });
+ *  - git + cfg   (fallback) real resolveRepoRoot binding when resolveRepo
+ *                 is absent;
+ *  - sessionCwd  (optional) fallback when the calling exec has no session
+ *                 header cwd.
+ *
+ * json-safe discipline (E3): conditional spreads everywhere; a canonical
+ * repo_root key only appears when the caller supplied repo_root.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { resolveRepoRoot } from '../repo-gate.js'
+
+/** Registered tool name (DESIGN §5.4). */
+const TOOL_NAME = 'worktree_list'
+
+/** A message already starting with a stable snake_case code stays verbatim. */
+const CODED_MESSAGE = /^[a-z][a-z0-9_]*(\s*—|:)/
+
+/** Coded engine/gate errors pass through; uncoded ones get the tool prefix. */
+function surfaceError(error) {
+  const message = String(error instanceof Error ? error.message : error)
+  if (CODED_MESSAGE.test(message)) throw error
+  throw new Error(`${TOOL_NAME}: ${message}`)
+}
+
+/** Bind the §5.2.0 gate: injected prebound resolver, else the real gate. */
+function makeRepoResolver(deps) {
+  if (typeof deps.resolveRepo === 'function') return deps.resolveRepo
+  const { git, cfg = {} } = deps
+  if (!git || typeof git.isGitRepo !== 'function') {
+    throw new Error(
+      `${TOOL_NAME}: deps must carry either resolveRepo(opts) or a git port with isGitRepo(cwd) so the repo gate can be bound`,
+    )
+  }
+  return (opts) =>
+    resolveRepoRoot({
+      repoArg: opts.repoArg,
+      sessionCwd: opts.sessionCwd,
+      workspacePaths: cfg.workspacePaths,
+      allowedRoots: cfg.allowedRoots,
+      git,
+    })
+}
+
+/**
+ * Conflict-retained integration worktrees, deduped, ascending by path:
+ * every conflicted job's recorded integrationWorktree (a `.integration/`
+ * path retained as the live conflict scene; DESIGN §6.3 step 10).
+ */
+function retainedIntegrationWorktrees(store) {
+  const paths = new Set()
+  for (const job of Object.values(store.jobs)) {
+    if (job.state !== 'conflicted') continue
+    if (typeof job.integrationWorktree === 'string' && job.integrationWorktree.length > 0) {
+      paths.add(job.integrationWorktree)
+    }
+  }
+  return [...paths].sort()
+}
+
+/**
+ * Register the `worktree_list` tool (DESIGN §5.4).
+ *
+ * @param {Object} ctx host ctx (needs ctx.tools.register)
+ * @param {Object} deps see the module header for the contract
+ */
+export function registerWorktreeListTool(ctx, deps = {}) {
+  const { service } = deps
+  if (!service || typeof service.list !== 'function') {
+    throw new Error(
+      `${TOOL_NAME}: deps.service must be a WorktreeService (createWorktreeService product)`,
+    )
+  }
+  const resolveRepo = makeRepoResolver(deps)
+
+  ctx.tools.register(defineTool({
+    name: TOOL_NAME,
+    description:
+      'List the git worktrees managed by this plugin (optionally filtered by repository) with each record\'s state and an `orphaned` flag when the path no longer appears in `git worktree list` (crash / manual removal), plus a merge-queue summary. '
+      + 'Use this after worktree_create to review the fleet, and before worktree_cleanup to find records worth pruning. Set include_integration true to also list temporary integration worktrees retained from conflicts (their scenes are out-of-band resolvable; see worktree_queue).',
+    parameters: {
+      repo_root: {
+        type: 'string',
+        description:
+          'Filter by repository (defaults: all repos known to the state store).',
+      },
+      include_integration: {
+        type: 'boolean',
+        description:
+          'Also list temporary integration worktrees retained from conflicts (default false).',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          kind: { type: 'string', required: true, const: 'list' },
+          repo_root: { type: 'string' },
+          worktrees: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: true,
+              properties: {
+                id: { type: 'string', required: true },
+                task: { type: 'string', required: true },
+                branch: { type: 'string', required: true },
+                path: { type: 'string', required: true },
+                state: { type: 'string', required: true },
+                head_commit: { type: 'string' },
+                dirty: { type: 'boolean' },
+                merge_state: { type: 'string' },
+                orphaned: { type: 'boolean' },
+              },
+            },
+          },
+          retained_integration_worktrees: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+          queue_summary: {
+            type: 'object',
+            required: true,
+            additionalProperties: false,
+            properties: {
+              active_jobs: {
+                type: 'array',
+                required: true,
+                items: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    repo_root: {
+                      required: true,
+                      oneOf: [{ type: 'string' }, { type: 'null' }],
+                    },
+                    integration_branch: { type: 'string', required: true },
+                    job_id: { type: 'string', required: true },
+                    state: { type: 'string', required: true },
+                  },
+                },
+              },
+              queued_count: { type: 'integer', required: true },
+            },
+          },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `${value.worktrees.length} worktree(s)`
+          + (value.retained_integration_worktrees
+            ? `; ${value.retained_integration_worktrees.length} retained integration worktree(s)`
+            : '')
+          + `; queue: ${value.queue_summary.queued_count} queued`,
+      }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      try {
+        let canonical
+        if (args.repo_root !== undefined) {
+          const session = exec && exec.agent ? exec.agent.session : undefined
+          const sessionCwd =
+            (session && session.header && session.header.cwd) || deps.sessionCwd
+          canonical = (await resolveRepo({
+            repoArg: args.repo_root,
+            ...(sessionCwd !== undefined ? { sessionCwd } : {}),
+          })).canonical
+        }
+
+        const { worktrees, queueSummary } = await service.list(
+          canonical !== undefined ? { repoRoot: canonical } : {},
+        )
+
+        let retained
+        if (args.include_integration === true) {
+          const store = deps.store
+          if (!store || typeof store.jobs !== 'object') {
+            throw new Error(
+              `${TOOL_NAME}: deps.store (the StateStore the service was built with) is required for include_integration`,
+            )
+          }
+          retained = retainedIntegrationWorktrees(store)
+        }
+
+        return {
+          kind: 'list',
+          ...(canonical !== undefined ? { repo_root: canonical } : {}),
+          worktrees: worktrees.map((record) => ({
+            id: record.id,
+            task: record.task,
+            branch: record.branch,
+            path: record.path,
+            state: record.state,
+            ...(record.headCommit !== undefined ? { head_commit: record.headCommit } : {}),
+            ...(record.dirty !== undefined ? { dirty: record.dirty } : {}),
+            ...(record.mergeJobId !== undefined ? { merge_state: record.mergeJobId } : {}),
+            ...(record.orphaned !== undefined ? { orphaned: record.orphaned } : {}),
+          })),
+          ...(retained !== undefined ? { retained_integration_worktrees: retained } : {}),
+          queue_summary: {
+            active_jobs: queueSummary.activeJobs.map((job) => ({
+              repo_root: job.repoRoot ?? null,
+              integration_branch: job.integrationBranch,
+              job_id: job.jobId,
+              state: job.state,
+            })),
+            queued_count: queueSummary.queuedCount,
+          },
+        }
+      } catch (error) {
+        surfaceError(error)
+      }
+    },
+  }))
+}