dsh-plugin-worktrees 0.1.0

package/lib/tools/worktree-queue.js

@@ -0,0 +1,330 @@
+/**
+ * `worktree_queue` tool (T09, DESIGN §5.7).
+ *
+ * Thin tool layer over the MergeQueue engine's four commands:
+ *  - `list`    → listJobs + branchHolders projections (§5.7 list shape);
+ *  - `cancel` / `retry` / `resolve` → the command state machine (idempotent
+ *    where the source is; invalid transitions throw invalid_job_state which
+ *    this layer re-throws with its code so the host maps it to isError).
+ *
+ * No git calls, no direct state writes — the engine is the injected
+ * `queue`; the repo_root filter goes through the §5.2.0 gate (injected
+ * `resolveRepo`, or the real binding built from `git` + `cfg`).
+ *
+ * deps contract:
+ *  - queue       (required) createMergeQueue() product;
+ *  - 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; the optional
+ * job fields (conflict_files / integrated_commit / error) appear ONLY when
+ * they carry a value.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { resolveRepoRoot } from '../repo-gate.js'
+import { MergeError } from '../merge-queue.js'
+
+/** Registered tool name (DESIGN §5.7). */
+const TOOL_NAME = 'worktree_queue'
+
+/** A message already starting with a stable snake_case code stays verbatim. */
+const CODED_MESSAGE = /^[a-z][a-z0-9_]*(\s*—|:)/
+
+/**
+ * Error surfacing: MergeError codes prefix the re-thrown message
+ * (`invalid_job_state — …`); 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}`)
+}
+
+/** 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,
+    })
+}
+
+/**
+ * §5.7 job row projection: the DESIGN key set with conditional optional
+ * keys (conflict_files / integrated_commit / error) — repoRoot null maps to
+ * a JSON null (the engine enriches unknown repos as null, and a null is a
+ * value, not an undefined hole).
+ */
+function jobRow(job) {
+  return {
+    job_id: job.id,
+    worktree_id: job.worktreeId,
+    task: job.task ?? null,
+    repo_root: job.repoRoot ?? null,
+    integration_branch: job.integrationBranch,
+    state: job.state,
+    order_index: Number(job.orderIndex) || 0,
+    ...(Array.isArray(job.conflictFiles) && job.conflictFiles.length > 0
+      ? { conflict_files: [...job.conflictFiles] }
+      : {}),
+    ...(job.integratedCommit !== undefined && job.integratedCommit !== null
+      ? { integrated_commit: job.integratedCommit }
+      : {}),
+    ...(job.error !== undefined && job.error !== null ? { error: job.error } : {}),
+    created_at: Number(job.createdAt) || 0,
+  }
+}
+
+/**
+ * §5.7 branch_holders projection: the jobs currently holding a branch slot
+ * (queued/applying/conflicted) — who is blocking the queue, at a glance.
+ */
+function holderRow(holder) {
+  return {
+    repo_root: holder.repoRoot ?? null,
+    integration_branch: holder.integrationBranch,
+    job_id: holder.jobId,
+    state: holder.state,
+  }
+}
+
+/**
+ * Whether a command RELEASED the branch (the engine's resolve/retry then
+ * kick a background drain): `true` only when the job HELD the branch slot
+ * before the command (conflicted) and left the active set after it
+ * (resolved/queued — queued jobs sit waiting, they do not hold a blockage;
+ * cancel's queued job never did either). Idempotent repeats change nothing
+ * → false.
+ *
+ * Both arguments are SCALAR states captured around the command dispatch —
+ * never job-record references: `store.jobs[id]` hands out the live record,
+ * so a `before` reference would alias `after` whenever a command (or a
+ * future engine change) mutated the record in place, silently collapsing
+ * `released` to false.
+ */
+function releasedBranch(stateBefore, stateAfter) {
+  const heldBefore = stateBefore === 'conflicted'
+  const activeAfter = stateAfter === 'conflicted' || stateAfter === 'applying'
+  return heldBefore && !activeAfter
+}
+
+/**
+ * Register the `worktree_queue` tool (DESIGN §5.7).
+ *
+ * @param {Object} ctx host ctx (needs ctx.tools.register)
+ * @param {Object} deps see the module header for the contract
+ */
+export function registerWorktreeQueueTool(ctx, deps = {}) {
+  const { queue } = deps
+  const required = ['listJobs', 'branchHolders', 'cancel', 'retry', 'resolve']
+  for (const method of required) {
+    if (!queue || typeof queue[method] !== 'function') {
+      throw new Error(
+        `${TOOL_NAME}: deps.queue must be a MergeQueue (createMergeQueue product: ${required.join('/')})`,
+      )
+    }
+  }
+  const store = deps.store
+  if (
+    !store
+    || 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 (jobs map + findActiveJob/findQueuedJobs for the released probe)`,
+    )
+  }
+  const resolveRepo = makeRepoResolver(deps)
+
+  ctx.tools.register(defineTool({
+    name: TOOL_NAME,
+    description:
+      'Inspect or command the merge queue: list merge jobs (with per-repo/branch filters) plus the branch_holders view of who currently holds each integration branch (queued/applying/conflicted); cancel a queued job; retry a failed/conflicted job (re-queues at the tail; the old retained integration worktree is left for the operator); or resolve a conflicted job whose conflicts were fixed out-of-band in its retained integration worktree (releases the branch so queued jobs proceed). '
+      + 'Commands are idempotent on their terminal state and reject invalid transitions (invalid_job_state) — e.g. cancel only works on a queued job.',
+    parameters: {
+      action: {
+        type: 'string',
+        required: true,
+        enum: ['list', 'cancel', 'retry', 'resolve'],
+        description: 'Queue operation: list jobs + branch holders, or command one job.',
+      },
+      repo_root: {
+        type: 'string',
+        description: 'list: filter by repo (default all).',
+      },
+      integration_branch: {
+        type: 'string',
+        description: 'list: filter by integration branch.',
+      },
+      job_id: {
+        type: 'string',
+        description: 'cancel/retry/resolve: the merge job id.',
+      },
+    },
+    output: {
+      schema: {
+        oneOf: [
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'queue' },
+              jobs: {
+                type: 'array',
+                required: true,
+                items: {
+                  type: 'object',
+                  additionalProperties: true,
+                  properties: {
+                    job_id: { type: 'string', required: true },
+                    worktree_id: { type: 'string', required: true },
+                    task: {
+                      required: true,
+                      oneOf: [{ type: 'string' }, { type: 'null' }],
+                    },
+                    repo_root: {
+                      required: true,
+                      oneOf: [{ type: 'string' }, { type: 'null' }],
+                    },
+                    integration_branch: { type: 'string', required: true },
+                    state: { type: 'string', required: true },
+                    order_index: { type: 'integer', required: true },
+                    conflict_files: { type: 'array', items: { type: 'string' } },
+                    integrated_commit: { type: 'string' },
+                    error: { type: 'string' },
+                    created_at: { type: 'integer', required: true },
+                  },
+                },
+              },
+              branch_holders: {
+                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 },
+                  },
+                },
+              },
+            },
+          },
+          {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              kind: { type: 'string', required: true, const: 'queue_command' },
+              action: {
+                type: 'string',
+                required: true,
+                enum: ['cancel', 'retry', 'resolve'],
+              },
+              job_id: { type: 'string', required: true },
+              state: { type: 'string', required: true },
+              released: { type: 'boolean', required: true },
+            },
+          },
+        ],
+      },
+      render: (_args, value) => {
+        if (value.kind === 'queue') {
+          const byState = {}
+          for (const job of value.jobs) byState[job.state] = (byState[job.state] ?? 0) + 1
+          const summary = Object.entries(byState).map(([s, n]) => `${s}=${n}`).join(' ')
+          return [{
+            type: 'text',
+            text: `queue: ${value.jobs.length} job(s)${summary ? ` (${summary})` : ''}; ${value.branch_holders.length} branch holder(s)`,
+          }]
+        }
+        return [{
+          type: 'text',
+          text: `queue ${value.action} ${value.job_id}: ${value.state}${value.released ? ' (branch released, drain kicked)' : ''}`,
+        }]
+      },
+    },
+    // Mutates shared queue state (command transitions + the release drain);
+    // list is read-mostly but shares the declaration for simplicity and
+    // safety — a stale list interleaved with a command would mislead.
+    isConcurrencySafe: () => false,
+    async execute(args, exec) {
+      try {
+        if (args.action === 'list') {
+          let repoKey
+          if (args.repo_root !== undefined) {
+            const session = exec && exec.agent ? exec.agent.session : undefined
+            const sessionCwd =
+              (session && session.header && session.header.cwd) || deps.sessionCwd
+            repoKey = (
+              await resolveRepo({
+                repoArg: args.repo_root,
+                ...(sessionCwd !== undefined ? { sessionCwd } : {}),
+              })
+            ).repoKey
+          }
+          const jobs = queue.listJobs({
+            ...(repoKey !== undefined ? { repoKey } : {}),
+            ...(args.integration_branch !== undefined
+              ? { integrationBranch: args.integration_branch }
+              : {}),
+          })
+          return {
+            kind: 'queue',
+            jobs: jobs.map(jobRow),
+            branch_holders: queue.branchHolders().map(holderRow),
+          }
+        }
+
+        // cancel / retry / resolve: job_id is REQUIRED (the compiled schema
+        // cannot express "required only when action != list", so the tool
+        // enforces it loudly).
+        if (typeof args.job_id !== 'string' || args.job_id.length === 0) {
+          throw new Error(
+            `${TOOL_NAME}: job_id_missing — action "${args.action}" requires the merge job id (get one from action "list")`,
+          )
+        }
+        const command = { cancel: queue.cancel, retry: queue.retry, resolve: queue.resolve }[
+          args.action
+        ]
+        // Scalar snapshots around the dispatch (see releasedBranch): a
+        // record reference would alias the post-command record.
+        const stateBefore = store.jobs[args.job_id]?.state
+        const result = command({ jobId: args.job_id })
+        const stateAfter = store.jobs[args.job_id]?.state
+        return {
+          kind: 'queue_command',
+          action: args.action,
+          job_id: result.jobId,
+          state: result.state,
+          released: releasedBranch(stateBefore, stateAfter),
+        }
+      } catch (error) {
+        surfaceError(error)
+      }
+    },
+  }))
+}

package/lib/tools/worktree-status.js

@@ -0,0 +1,194 @@
+/**
+ * `worktree_status` tool (T07, DESIGN §5.5).
+ *
+ * Thin tool layer: parameters schema, worktree_id-or-path input resolution,
+ * the §5.5 status projection, and the `merge` projection from the StateStore
+ * job records (the service's status() does not read jobs). No git calls, no
+ * state writes.
+ *
+ * deps contract:
+ *  - service (required) createWorktreeService() product;
+ *  - store   (required) the SAME StateStore instance the service was built
+ *             with (read-only access for the merge-job projection);
+ *  - cfg     (optional) reserved for T10 wiring parity (unused today).
+ *
+ * json-safe discipline (E3): conditional spreads everywhere; `merge` is
+ * ALWAYS present — either a projection object or an explicit `null`
+ * (never an undefined-valued key).
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** Registered tool name (DESIGN §5.5). */
+const TOOL_NAME = 'worktree_status'
+
+/** 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}`)
+}
+
+/**
+ * §5.5 merge projection: the LATEST job whose worktreeId matches (createdAt
+ * desc, insertion-order tiebreak) — a record's mergeJobId points at its
+ * current job, but a re-queued task accumulates history and the caller wants
+ * the freshest state. No matching job → `null` (never undefined).
+ */
+function mergeProjection(store, worktreeId) {
+  let best = null
+  let bestAt = -Infinity
+  let bestSeq = -1
+  const jobs = Object.values(store.jobs)
+  for (let index = 0; index < jobs.length; index += 1) {
+    const job = jobs[index]
+    if (job.worktreeId !== worktreeId) continue
+    const at = Number(job.createdAt) || 0
+    if (at > bestAt || (at === bestAt && index > bestSeq)) {
+      best = job
+      bestAt = at
+      bestSeq = index
+    }
+  }
+  if (best === null) return null
+  return {
+    job_id: best.id,
+    state: best.state,
+    ...(Array.isArray(best.conflictFiles) && best.conflictFiles.length > 0
+      ? { conflict_files: [...best.conflictFiles] }
+      : {}),
+    ...(best.integratedCommit !== undefined ? { integrated_commit: best.integratedCommit } : {}),
+    ...(best.integrationWorktree !== undefined
+      ? { integration_worktree: best.integrationWorktree }
+      : {}),
+  }
+}
+
+/**
+ * Register the `worktree_status` tool (DESIGN §5.5).
+ *
+ * @param {Object} ctx host ctx (needs ctx.tools.register)
+ * @param {Object} deps see the module header for the contract
+ */
+export function registerWorktreeStatusTool(ctx, deps = {}) {
+  const { service, store } = deps
+  if (!service || typeof service.status !== 'function') {
+    throw new Error(
+      `${TOOL_NAME}: deps.service must be a WorktreeService (createWorktreeService product)`,
+    )
+  }
+  if (!store || typeof store.jobs !== 'object') {
+    throw new Error(
+      `${TOOL_NAME}: deps.store must be the StateStore the service was built with (merge-job projection reads store.jobs)`,
+    )
+  }
+
+  ctx.tools.register(defineTool({
+    name: TOOL_NAME,
+    description:
+      'Report the live git status of one managed worktree: its record state, current HEAD, whether the tree is dirty, the per-file change list (porcelain-mapped: added / modified / deleted / renamed), whether HEAD has moved past the recorded base commit, and the state of its merge job (merge: null while it has never been queued). '
+      + 'Use this before worktree_merge to review uncommitted work, and after a conflicted merge to inspect the retained scene. `vanished: true` in the result means the worktree directory disappeared (crash or manual removal).',
+    parameters: {
+      worktree_id: {
+        type: 'string',
+        description: 'Worktree id from worktree_create (alternative to path).',
+      },
+      path: {
+        type: 'string',
+        description: 'Absolute worktree path (alternative to worktree_id).',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          kind: { type: 'string', required: true, const: 'status' },
+          id: { type: 'string', required: true },
+          branch: { type: 'string', required: true },
+          path: { type: 'string', required: true },
+          state: { type: 'string', required: true },
+          head: { type: 'string' },
+          dirty: { type: 'boolean' },
+          base_commit: { type: 'string' },
+          ahead_of_base: { type: 'boolean' },
+          changes: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                path: { type: 'string', required: true },
+                status: { type: 'string', required: true },
+              },
+            },
+          },
+          merge: {
+            required: true,
+            oneOf: [
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  job_id: { type: 'string', required: true },
+                  state: { type: 'string', required: true },
+                  conflict_files: { type: 'array', items: { type: 'string' } },
+                  integrated_commit: { type: 'string' },
+                  integration_worktree: { type: 'string' },
+                },
+              },
+              { type: 'null' },
+            ],
+          },
+          vanished: { type: 'boolean' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `worktree ${value.id} (${value.branch}) state=${value.state}`
+          + ` dirty=${value.dirty === undefined ? 'unknown' : value.dirty}`
+          + ` changes=${value.changes.length}`
+          + ` merge=${value.merge === null ? 'none' : `${value.merge.state} (${value.merge.job_id})`}`,
+      }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      try {
+        const idOrPath =
+          args.worktree_id !== undefined ? args.worktree_id : args.path
+        if (idOrPath === undefined || idOrPath === '') {
+          throw new Error(
+            `${TOOL_NAME}: worktree_id_or_path_missing — pass worktree_id (from worktree_create) or the absolute worktree path`,
+          )
+        }
+
+        const s = await service.status(idOrPath)
+        const merge = mergeProjection(store, s.id)
+
+        return {
+          kind: 'status',
+          id: s.id,
+          branch: s.branch,
+          path: s.path,
+          state: s.state,
+          ...(s.head !== undefined ? { head: s.head } : {}),
+          ...(s.dirty !== undefined ? { dirty: s.dirty } : {}),
+          ...(s.baseCommit !== undefined ? { base_commit: s.baseCommit } : {}),
+          ...(s.ahead_of_base !== undefined ? { ahead_of_base: s.ahead_of_base } : {}),
+          changes: (Array.isArray(s.changes) ? s.changes : []).map((entry) => ({
+            path: entry.path,
+            status: entry.status,
+          })),
+          merge,
+          ...(s.vanished !== undefined ? { vanished: s.vanished } : {}),
+        }
+      } catch (error) {
+        surfaceError(error)
+      }
+    },
+  }))
+}