dsh-plugin-worktrees 0.1.0

package/lib/tools/worktree-merge.js

@@ -0,0 +1,396 @@
+/**
+ * `worktree_merge` tool (T09, DESIGN §5.6 — the core write tool).
+ *
+ * Thin tool layer over the MergeQueue engine: load the worktree record,
+ * `queue.collect` (auto-commit uncommitted task work; a clean tree at base
+ * is the NORMAL `no_changes` outcome), `queue.enqueue` (origin 'tool'),
+ * `queue.drain` (serial, to the branch's natural stopping point), then map
+ * THIS job's outcome into the §5.6 oneOf five-state return. No git calls
+ * and no state writes happen here — the engine is the injected `queue` and
+ * the record/job reads go through the injected `store` (the same StateStore
+ * the queue was built with).
+ *
+ * `active_job_exists` is deliberately a RETURN STATE, never a throw
+ * (DESIGN §5.6): when the drain was blocked by another conflicted/applying
+ * job while this job is still queued, the tool returns
+ * `state:'failed', error:'active_job_exists: job <id> holds <branch> …'`.
+ *
+ * deps contract:
+ *  - queue (required) createMergeQueue() product (collect/enqueue/drain);
+ *  - store (required) the SAME StateStore the queue was built with
+ *                 (worktree record lookup + post-drain job re-read);
+ *  - git   (required when integration_branch overrides are vetted) the
+ *                 GitPort — used ONLY for the P1-B validateBranch probe of
+ *                 an explicit override (never for the merge itself; that
+ *                 stays inside the queue).
+ *
+ * json-safe discipline (E3): the five return shapes are built with
+ * conditional spreads only — the `no_changes` shape simply has no job_id
+ * key (no job was created), and no key ever carries an `undefined` value.
+ *
+ * Error policy: coded engine/gate errors (`worktree_not_found — …`) pass
+ * through unchanged; MergeError from the queue is re-thrown with its
+ * machine-matchable code prefix (`git_operation_failed — …`); anything
+ * uncoded gets the tool-name prefix.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { MergeError } from '../merge-queue.js'
+
+/** Registered tool name (DESIGN §5.6). */
+const TOOL_NAME = 'worktree_merge'
+
+/** A message already starting with a stable snake_case code stays verbatim. */
+const CODED_MESSAGE = /^[a-z][a-z0-9_]*(\s*—|:)/
+
+/**
+ * Error surfacing: MergeError carries its code on `error.code` but not in
+ * the message text, so it is re-thrown WITH the code prefix (DESIGN §5.6
+ * error family is machine-matchable); coded plain errors pass through;
+ * uncoded ones get the tool-name prefix.
+ */
+function surfaceError(error) {
+  if (error instanceof MergeError) {
+    throw new Error(`${error.code} — ${error.message}`)
+  }
+  const message = String(error instanceof Error ? error.message : error)
+  if (CODED_MESSAGE.test(message)) throw error
+  throw new Error(`${TOOL_NAME}: ${message}`)
+}
+
+/** §5.6 resolution_hint — the DESIGN sentence with the retained scene path. */
+function resolutionHint(scenePath) {
+  return (
+    `The integration worktree is RETAINED at ${scenePath} with the conflict markers in place. `
+    + `Resolve out-of-band (edit there, or abandon), then worktree_queue(action:'resolve'|'retry').`
+  )
+}
+
+/**
+ * Register the `worktree_merge` tool (DESIGN §5.6).
+ *
+ * @param {Object} ctx host ctx (needs ctx.tools.register)
+ * @param {Object} deps see the module header for the contract
+ */
+export function registerWorktreeMergeTool(ctx, deps = {}) {
+  const { queue, store, git } = deps
+  if (
+    !queue
+    || typeof queue.collect !== 'function'
+    || typeof queue.enqueue !== 'function'
+    || typeof queue.drain !== 'function'
+  ) {
+    throw new Error(
+      `${TOOL_NAME}: deps.queue must be a MergeQueue (createMergeQueue product: collect/enqueue/drain)`,
+    )
+  }
+  if (
+    !store
+    || typeof store.worktrees !== 'object'
+    || typeof store.jobs !== 'object'
+    || typeof store.findActiveJob !== 'function'
+    || typeof store.findQueuedJobs !== 'function'
+  ) {
+    throw new Error(
+      `${TOOL_NAME}: deps.store must be the StateStore the queue was built with (worktrees/jobs maps + findActiveJob/findQueuedJobs)`,
+    )
+  }
+
+  ctx.tools.register(defineTool({
+    name: TOOL_NAME,
+    description:
+      'Integrate one task worktree\'s branch into its integration branch: auto-commit any uncommitted work in the task worktree, enqueue a merge job, and drain that branch\'s queue serially until it is empty or a conflict holds the branch. '
+      + 'Returns the job\'s outcome: succeeded (integrated_commit), conflicted (conflict_files + the RETAINED integration worktree with the markers in place — resolve out-of-band, then worktree_queue resolve/retry), queued (queued_ahead), no_changes (a clean tree at base — nothing to integrate), or failed (error). '
+      + 'With autoCollect=false a DIRTY worktree fails as "dirty_not_collected" — uncommitted work is never silently skipped; commit it first or enable autoCollect. '
+      + 'A branch held by another conflicted/applying job maps to failed with an "active_job_exists: …" error — resolve or retry that job first; this is an expected business state, not an exception.',
+    parameters: {
+      worktree_id: {
+        type: 'string',
+        required: true,
+        description: 'Worktree id from worktree_create whose branch should be integrated now.',
+      },
+      integration_branch: {
+        type: 'string',
+        description: 'Overrides the integration branch recorded at create time (rarely needed).',
+      },
+      message: {
+        type: 'string',
+        description:
+          'Merge commit message. Default: "dsh-worktrees: integrate <task> (<short source head>)".',
+      },
+      commit_message: {
+        type: 'string',
+        description:
+          'Commit message for the auto-collected commit of uncommitted changes in the task worktree (default: "dsh-worktrees: collect <task>").',
+      },
+    },
+    output: {
+      schema: {
+        oneOf: [
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'merge' },
+              job_id: { type: 'string', required: true },
+              worktree_id: { type: 'string', required: true },
+              state: { type: 'string', required: true, const: 'succeeded' },
+              integrated_commit: { type: 'string', required: true },
+              integration_branch: { type: 'string', required: true },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'merge' },
+              job_id: { type: 'string', required: true },
+              worktree_id: { type: 'string', required: true },
+              state: { type: 'string', required: true, const: 'conflicted' },
+              conflict_files: {
+                type: 'array',
+                required: true,
+                items: { type: 'string' },
+              },
+              integration_worktree: { type: 'string', required: true },
+              resolution_hint: { type: 'string', required: true },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'merge' },
+              job_id: { type: 'string', required: true },
+              worktree_id: { type: 'string', required: true },
+              state: { type: 'string', required: true, const: 'queued' },
+              queued_ahead: { type: 'integer', required: true },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'merge' },
+              worktree_id: { type: 'string', required: true },
+              state: { type: 'string', required: true, const: 'no_changes' },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'merge' },
+              job_id: { type: 'string', required: true },
+              worktree_id: { type: 'string', required: true },
+              state: { type: 'string', required: true, const: 'failed' },
+              error: { type: 'string', required: true },
+            },
+          },
+        ],
+      },
+      render: (_args, value) => {
+        let detail = ''
+        if (value.state === 'succeeded') {
+          detail = ` → ${value.integrated_commit} on ${value.integration_branch}`
+        } else if (value.state === 'conflicted') {
+          detail = ` — ${value.conflict_files.length} file(s) conflicted; scene retained at ${value.integration_worktree}`
+        } else if (value.state === 'queued') {
+          detail = ` (queued_ahead: ${value.queued_ahead})`
+        } else if (value.state === 'failed') {
+          detail = ` — ${value.error}`
+        }
+        return [{ type: 'text', text: `merge ${value.worktree_id}: ${value.state}${detail}` }]
+      },
+    },
+    // Shared queue state is mutated (enqueue + drain) and the whole body is
+    // a check-then-act section — sibling calls must never overlap (the
+    // engine's per-branch promise chain is the second line of defence).
+    isConcurrencySafe: () => false,
+    async execute(args) {
+      try {
+        // Step 1 (§5.6): the worktree record must exist.
+        const record = store.worktrees[args.worktree_id]
+        if (record === undefined) {
+          throw new Error(
+            `worktree_not_found — no worktree record matches id "${args.worktree_id}"`,
+          )
+        }
+        const integrationBranch =
+          typeof args.integration_branch === 'string' && args.integration_branch.length > 0
+            ? args.integration_branch
+            : record.integrationBranch
+
+        // Step 0 — the branch-holder pre-check (source applyNext step 1,
+        // L506-520 semantics, surfaced at the TOOL layer per DESIGN §5.6):
+        // an applying/conflicted job holds the integration branch, so
+        // enqueueing would only stack a job that can never apply. This is
+        // the `active_job_exists` RETURN STATE — an expected business
+        // state, never a throw. A QUEUED holder does not block (it is what
+        // our own drain would apply next).
+        const holder = store.findActiveJob(record.repoKey, integrationBranch)
+        if (holder !== undefined && holder.state !== 'queued') {
+          return {
+            kind: 'merge',
+            job_id: holder.id,
+            worktree_id: record.id,
+            state: 'failed',
+            error:
+              `active_job_exists: job ${holder.id} holds ${integrationBranch} `
+              + `(state=${holder.state}); resolve or retry it first`,
+          }
+        }
+
+        // Step 2: collect. A clean tree at base is the no_changes NORMAL
+        // outcome — return WITHOUT enqueueing (no job_id exists, so the
+        // key is simply absent from the return shape). A DIRTY tree with
+        // autoCollect=false is the explicit `dirty_not_collected` terminal
+        // (audit P2): the uncommitted files were never integrated, so
+        // proceeding to a merge of the OLD head would report a misleading
+        // succeeded. Stop loud, no job is created.
+        const collected = await queue.collect(record, args.commit_message)
+        if (collected.state === 'no_changes') {
+          return { kind: 'merge', worktree_id: record.id, state: 'no_changes' }
+        }
+        if (collected.state === 'dirty_not_collected') {
+          return {
+            kind: 'merge',
+            worktree_id: record.id,
+            state: 'failed',
+            error:
+              'dirty_not_collected: the worktree has uncommitted changes while autoCollect=false, ' +
+              'so nothing was integrated; commit the work first (or enable the autoCollect config) ' +
+              'and call worktree_merge again',
+          }
+        }
+
+        // Step 2b (audit P1-B): an EXPLICIT integration_branch override gets
+        // the same check-ref-format vetting the create entry applies — the
+        // recorded default was vetted at create time, the override arrives
+        // raw from the model and flows into `git branch <name> <startPoint>`
+        // at apply time.
+        if (
+          typeof args.integration_branch === 'string'
+          && args.integration_branch.length > 0
+          && args.integration_branch !== record.integrationBranch
+        ) {
+          if (!git || typeof git.validateBranch !== 'function') {
+            throw new Error(
+              `${TOOL_NAME}: deps.git must be a GitPort (validateBranch) to vet an integration_branch override`,
+            )
+          }
+          const valid = await git.validateBranch(record.repoRoot, args.integration_branch)
+          if (!valid) {
+            throw new Error(
+              'invalid_integration_branch — integration branch name ' +
+                `"${args.integration_branch}" is rejected by git check-ref-format --branch ` +
+                '(legal branch names: no leading "-" or "-", no "..", no ASCII control characters ' +
+                'or spaces, no trailing ".lock", no "@{"/"@"-only, no ref-component starting with ' +
+                '"."; slashes are allowed, e.g. "dsh-wt/integration/x")',
+            )
+          }
+        }
+
+        // Step 3 + 4: enqueue (origin 'tool'), then drain the branch to its
+        // natural stopping point (empty or a conflict holding the branch).
+        const job = await queue.enqueue({
+          repoKey: record.repoKey,
+          repoRoot: record.repoRoot,
+          integrationBranch,
+          worktreeId: record.id,
+          sourceBranch: record.branch,
+          sourceHead: collected.sourceHead,
+          ...(args.message !== undefined ? { message: args.message } : {}),
+          origin: 'tool',
+        })
+        const outcome = await queue.drain(record.repoKey, integrationBranch)
+
+        // Step 5: THIS job's outcome, re-read from the store (the drain may
+        // also have applied jobs enqueued by other calls).
+        const fresh = store.jobs[job.id] ?? job
+        if (fresh.state === 'succeeded') {
+          return {
+            kind: 'merge',
+            job_id: job.id,
+            worktree_id: record.id,
+            state: 'succeeded',
+            integrated_commit: fresh.integratedCommit,
+            integration_branch: integrationBranch,
+          }
+        }
+        if (fresh.state === 'conflicted') {
+          const scene = fresh.integrationWorktree
+          return {
+            kind: 'merge',
+            job_id: job.id,
+            worktree_id: record.id,
+            state: 'conflicted',
+            conflict_files: Array.isArray(fresh.conflictFiles) ? [...fresh.conflictFiles] : [],
+            integration_worktree: scene,
+            resolution_hint: resolutionHint(scene),
+          }
+        }
+        if (fresh.state === 'failed') {
+          return {
+            kind: 'merge',
+            job_id: job.id,
+            worktree_id: record.id,
+            state: 'failed',
+            error: String(fresh.error ?? 'merge failed'),
+          }
+        }
+        if (fresh.state === 'cancelled') {
+          // Defensive: an external cancel raced the drain. Map into the
+          // five-state contract instead of inventing a sixth state.
+          return {
+            kind: 'merge',
+            job_id: job.id,
+            worktree_id: record.id,
+            state: 'failed',
+            error: `merge job ${job.id} was cancelled before it could apply`,
+          }
+        }
+
+        // Our job is STILL queued — the drain stopped before reaching it.
+        // blockedBy another conflicted/applying job → active_job_exists as
+        // a RETURN STATE (DESIGN §5.6: expected business state, not throw).
+        const blocker = outcome !== undefined && outcome !== null ? outcome.blockedBy : undefined
+        if (
+          blocker !== undefined
+          && blocker !== null
+          && blocker.id !== job.id
+          && (blocker.state === 'conflicted' || blocker.state === 'applying')
+        ) {
+          return {
+            kind: 'merge',
+            job_id: job.id,
+            worktree_id: record.id,
+            state: 'failed',
+            error:
+              `active_job_exists: job ${blocker.id} holds ${integrationBranch} `
+              + `(state=${blocker.state}); resolve or retry it first`,
+          }
+        }
+
+        // Defensive fallback (unreachable with the serial chain): report
+        // the queue position — how many queued jobs sit ahead of ours.
+        const myOrder = Number(fresh.orderIndex) || 0
+        const queuedAhead = store
+          .findQueuedJobs(record.repoKey, integrationBranch)
+          .filter(
+            (other) => other.id !== job.id && (Number(other.orderIndex) || 0) < myOrder,
+          )
+          .length
+        return {
+          kind: 'merge',
+          job_id: job.id,
+          worktree_id: record.id,
+          state: 'queued',
+          queued_ahead: queuedAhead,
+        }
+      } catch (error) {
+        surfaceError(error)
+      }
+    },
+  }))
+}