@civilization/dsh-git-workbench 0.0.0-stage → 0.4.0

package/src/index.ts

@@ -0,0 +1,220 @@
+/**
+ * Host entry for the Git Workbench & source control plugin.
+ * Provides RPC endpoints for the Client right-sidebar viewer, status bar, and model tools for Agents.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  getGitAllBranches,
+  getGitCommitDetails,
+  getGitDiff,
+  getGitLog,
+  getGitStatus,
+  getGitTags,
+  gitCheckout,
+  gitCommit,
+  gitCreateTag,
+  gitDeleteTag,
+  gitDiscard,
+  gitFetch,
+  gitPull,
+  gitPush,
+  gitStage,
+  gitUnstage,
+} from './git-executor.ts'
+import { registerGitTool } from './tool.ts'
+
+export type * from './types.ts'
+
+/** Cordis plugin name */
+export const name = '@civilization/dsh-git-workbench'
+
+/** Required host services */
+export const inject = ['connection', 'webServer']
+
+interface HostServices {
+  connection: {
+    rpc: {
+      handle: (
+        channel: string,
+        handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>
+      ) => () => void
+    }
+  }
+  webServer?: {
+    register: (route: unknown) => () => void
+  }
+  sessions?: {
+    get: (id: string) => { header?: { cwd?: string } } | undefined
+  }
+  sandboxPolicy?: {
+    workspaceRoot?: string
+  }
+}
+
+/**
+ * Apply the Git host plugin.
+ * Sets up authenticated RPC handlers under `/git/*` and registers the model tool.
+ * @param ctx - Context carrying the connection and optional session services.
+ */
+export function apply(ctx: Context): void {
+  const host = ctx as any as HostServices
+  const resolveTargetDir = (sessionId?: string): string => {
+    if (sessionId) {
+      const liveCwd = host.sessions?.get(sessionId)?.header?.cwd
+      if (liveCwd) return liveCwd
+    }
+    const workspaceRoot = host.sandboxPolicy?.workspaceRoot
+    return workspaceRoot ?? process.cwd()
+  }
+
+  // Register dedicated /git RPC channel
+  host.connection.rpc.handle(
+    '/git',
+    async (endpoint: string, payload: unknown, _signal: AbortSignal) => {
+      const body = (typeof payload === 'object' && payload !== null ? payload : {}) as Record<string, unknown>
+      const sessionId = typeof body.sessionId === 'string' ? body.sessionId : undefined
+      const cwd = typeof body.path === 'string' ? body.path : resolveTargetDir(sessionId)
+
+      try {
+        if (endpoint === 'status') {
+          const status = await getGitStatus(cwd)
+          return { ok: true, value: status }
+        }
+
+        if (endpoint === 'log') {
+          const maxCount = typeof body.maxCount === 'number' ? body.maxCount : 50
+          const commits = await getGitLog(cwd, maxCount)
+          return { ok: true, value: commits }
+        }
+
+        if (endpoint === 'commitDetails') {
+          const commit = typeof body.commit === 'string' ? body.commit : ''
+          const details = await getGitCommitDetails(cwd, commit)
+          return { ok: true, value: details }
+        }
+
+        if (endpoint === 'diff') {
+          const path = typeof body.filePath === 'string' ? body.filePath : undefined
+          const staged = typeof body.staged === 'boolean' ? body.staged : false
+          const commit = typeof body.commit === 'string' ? body.commit : undefined
+          const diff = await getGitDiff(cwd, {
+            ...path !== undefined ? { path } : {},
+            staged,
+            ...commit !== undefined ? { commit } : {},
+          })
+          return { ok: true, value: diff }
+        }
+
+        if (endpoint === 'branches') {
+          const branches = await getGitAllBranches(cwd)
+          return { ok: true, value: branches }
+        }
+
+        if (endpoint === 'checkout') {
+          const branch = typeof body.branch === 'string' ? body.branch : ''
+          const createNew = typeof body.create === 'boolean' ? body.create : false
+          const result = await gitCheckout(cwd, branch, createNew)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'stage') {
+          const paths = Array.isArray(body.paths)
+            ? (body.paths as string[])
+            : body.paths === 'all'
+              ? 'all'
+              : typeof body.path === 'string'
+                ? [body.path]
+                : 'all'
+          const result = await gitStage(cwd, paths)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'unstage') {
+          const paths = Array.isArray(body.paths)
+            ? (body.paths as string[])
+            : body.paths === 'all'
+              ? 'all'
+              : typeof body.path === 'string'
+                ? [body.path]
+                : 'all'
+          const result = await gitUnstage(cwd, paths)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'discard') {
+          const paths = Array.isArray(body.paths)
+            ? (body.paths as string[])
+            : typeof body.path === 'string'
+              ? [body.path]
+              : []
+          const result = await gitDiscard(cwd, paths)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'commit') {
+          const message = typeof body.message === 'string' ? body.message : ''
+          const result = await gitCommit(cwd, message)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'fetch') {
+          const result = await gitFetch(cwd)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'pull') {
+          const result = await gitPull(cwd)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'push') {
+          const result = await gitPush(cwd)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'tags') {
+          const tags = await getGitTags(cwd)
+          return { ok: true, value: tags }
+        }
+
+        if (endpoint === 'createTag') {
+          const name = typeof body.name === 'string' ? body.name : ''
+          const commit = typeof body.commit === 'string' ? body.commit : undefined
+          const message = typeof body.message === 'string' ? body.message : undefined
+          const result = await gitCreateTag(cwd, name, commit, message)
+          return { ok: true, value: result }
+        }
+
+        if (endpoint === 'deleteTag') {
+          const name = typeof body.name === 'string' ? body.name : ''
+          const result = await gitDeleteTag(cwd, name)
+          return { ok: true, value: result }
+        }
+
+
+        return {
+          ok: false,
+          error: {
+            code: 'git/not_found',
+            message: `Unknown git RPC endpoint: ${endpoint}`,
+            details: {},
+          },
+        }
+      } catch (error) {
+        return {
+          ok: false,
+          error: {
+            code: 'git/error',
+            message: error instanceof Error ? error.message : String(error),
+            details: {},
+          },
+        }
+      }
+    },
+  )
+
+
+  // Register the agent tool
+  registerGitTool(ctx, resolveTargetDir)
+}

package/src/tool.ts

@@ -0,0 +1,299 @@
+/**
+ * Agent model tool for inspecting Git repository status, commits, and diffs.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: JsonValue }
+  | JsonValue[]
+import {
+  getGitAllBranches,
+  getGitCommitDetails,
+  getGitDiff,
+  getGitLog,
+  getGitStatus,
+  getGitTags,
+  gitCheckout,
+  gitCreateTag,
+  gitDeleteTag,
+} from './git-executor.ts'
+
+/**
+ * Register git model tools (git_view and git_checkout) in the tools service.
+ * @param ctx - Context carrying the tools service.
+ * @param resolveDir - Resolver for the current agent or session working directory.
+ */
+export function registerGitTool(ctx: Context, resolveDir: (sessionId?: string) => string): void {
+  ctx.inject(['tools'], (scope) => {
+    // 1. Tool for inspecting git status, DAG history, diff, and branches
+    scope.effect(() => scope.tools.register(defineTool({
+      name: 'git_view',
+      description: 'Inspect the current project Git repository status, changed files, DAG commit tree, branch list, or code diffs.',
+      parameters: {
+        action: {
+          type: 'string',
+          enum: ['status', 'log', 'diff', 'branches', 'commit', 'tags'],
+          description: 'The Git query action: "status" (changes and branch info), "log" (commits with DAG topology rails), "diff" (code diffs), "branches" (branch list), "commit" (commit details), or "tags" (all repository tags).',
+        },
+        path: {
+          type: 'string',
+          description: 'Optional file path filter for diff or status inspection.',
+        },
+        staged: {
+          type: 'boolean',
+          description: 'Whether to check staged changes when viewing diff (defaults to false for working tree changes).',
+        },
+        maxCount: {
+          type: 'number',
+          description: 'Maximum number of commits to retrieve when action is "log" (defaults to 30).',
+        },
+        commit: {
+          type: 'string',
+          description: 'Specific commit hash to inspect diff or details for.',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+      },
+      async execute(args, exec): Promise<Record<string, JsonValue>> {
+        const cwd = resolveDir(exec.agent?.session.id)
+        const action = args.action ?? 'status'
+
+        switch (action) {
+          case 'log': {
+            const rawCommits = await getGitLog(cwd, args.maxCount ?? 30)
+            const commits = rawCommits.map(c => ({
+              hash: c.hash,
+              shortHash: c.shortHash,
+              author: c.author,
+              authorEmail: c.authorEmail,
+              relativeDate: c.relativeDate,
+              date: c.date,
+              subject: c.subject,
+              parents: c.parents ? [...c.parents] : [],
+              refs: c.refs ? [...c.refs] : [],
+              ...c.lane !== undefined ? { lane: c.lane } : {},
+              ...c.laneColor !== undefined ? { laneColor: c.laneColor } : {},
+            }))
+            return { action: 'log', count: commits.length, commits }
+          }
+          case 'commit': {
+            if (!args.commit) {
+              return { action: 'commit', error: 'Missing commit parameter' }
+            }
+            const details = await getGitCommitDetails(cwd, args.commit)
+            if (!details) return { action: 'commit', found: false }
+            return {
+              action: 'commit',
+              found: true,
+              commit: {
+                hash: details.commit.hash,
+                shortHash: details.commit.shortHash,
+                author: details.commit.author,
+                date: details.commit.date,
+                subject: details.commit.subject,
+              },
+              files: details.files.map(f => ({
+                path: f.path,
+                status: f.status,
+                additions: f.additions,
+                deletions: f.deletions,
+              })),
+              totalAdditions: details.totalAdditions,
+              totalDeletions: details.totalDeletions,
+            }
+          }
+          case 'diff': {
+            const diff = await getGitDiff(cwd, {
+              ...args.path !== undefined ? { path: args.path } : {},
+              ...args.staged !== undefined ? { staged: args.staged } : {},
+              ...args.commit !== undefined ? { commit: args.commit } : {},
+            })
+            const files = diff.files.map(f => ({ path: f.path, additions: f.additions, deletions: f.deletions }))
+            return { action: 'diff', files, rawDiff: diff.rawDiff }
+          }
+          case 'branches': {
+            const summary = await getGitAllBranches(cwd)
+            return {
+              action: 'branches',
+              ...summary.current !== undefined ? { current: summary.current } : {},
+              local: summary.local.map(b => ({
+                name: b.name,
+                isCurrent: b.isCurrent,
+                ...b.upstream !== undefined ? { upstream: b.upstream } : {},
+                ...b.ahead !== undefined ? { ahead: b.ahead } : {},
+                ...b.behind !== undefined ? { behind: b.behind } : {},
+              })),
+              remote: summary.remote.map(b => ({
+                name: b.name,
+                isCurrent: b.isCurrent,
+              })),
+            }
+          }
+          case 'tags': {
+            const rawTags = await getGitTags(cwd)
+            return {
+              action: 'tags',
+              total: rawTags.length,
+              tags: rawTags.map(t => ({
+                name: t.name,
+                commitHash: t.commitHash,
+                shortHash: t.shortHash,
+                date: t.date,
+                relativeDate: t.relativeDate,
+                message: t.message,
+                author: t.author,
+                isAnnotated: t.isAnnotated,
+              })),
+            }
+          }
+          case 'status':
+          default: {
+            const status = await getGitStatus(cwd)
+            return {
+              action: 'status',
+              isRepo: status.isRepo,
+              ...status.rootPath !== undefined ? { rootPath: status.rootPath } : {},
+              ...status.branch !== undefined ? { branch: status.branch } : {},
+              ...status.upstream !== undefined ? { upstream: status.upstream } : {},
+              ahead: status.ahead,
+              behind: status.behind,
+              staged: status.staged.map(f => ({ path: f.path, status: f.status, staged: f.staged })),
+              unstaged: status.unstaged.map(f => ({ path: f.path, status: f.status, staged: f.staged })),
+              untracked: status.untracked.map(f => ({ path: f.path, status: f.status, staged: f.staged })),
+              totalChanges: status.totalChanges,
+            }
+          }
+        }
+      },
+      presentCall: args => ({ card: 'generic', title: `git_view (${args.action ?? 'status'})`, rawInput: args }),
+    })), 'experimental-git: register git_view tool')
+
+    // 2. Dedicated tool for checking out or creating branches
+    scope.effect(() => scope.tools.register(defineTool({
+      name: 'git_checkout',
+      description: 'Switch branch or create and checkout a new branch in the current project Git repository.',
+      parameters: {
+        branch: {
+          type: 'string',
+          required: true,
+          description: 'The target branch name to switch to (e.g. "feature/auth", "dev", "master").',
+        },
+        create: {
+          type: 'boolean',
+          description: 'Whether to create a new branch from current HEAD and check it out (-b). Defaults to false.',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        render: (_args, val) => {
+          const value = val as { success?: boolean; branch?: string; message?: string }
+          return [{
+            type: 'text',
+            text: value.success
+              ? `Successfully checked out branch '${value.branch ?? ''}'.`
+              : `Failed to checkout branch '${value.branch ?? ''}': ${value.message ?? ''}`,
+          }]
+        },
+      },
+
+      async execute(args, exec): Promise<Record<string, JsonValue>> {
+        const cwd = resolveDir(exec.agent?.session.id)
+        const branch = args.branch.trim()
+        const createNew = args.create ?? false
+        const result = await gitCheckout(cwd, branch, createNew)
+
+        return {
+          success: result.success,
+          branch,
+          message: result.message ?? '',
+        }
+      },
+      presentCall: args => ({
+        card: 'generic',
+        title: `git_checkout ${args.create ? '-b ' : ''}${args.branch}`,
+        rawInput: args,
+      }),
+    })), 'experimental-git: register git_checkout tool')
+
+    // 3. Dedicated tool for creating or deleting git tags
+    scope.effect(() => scope.tools.register(defineTool({
+      name: 'git_tag',
+      description: 'Create or delete a Git tag in the current project repository.',
+      parameters: {
+        name: {
+          type: 'string',
+          required: true,
+          description: 'The tag name (e.g. "v1.0.0", "release-20261020").',
+        },
+        action: {
+          type: 'string',
+          enum: ['create', 'delete'],
+          description: 'Tag operation: "create" (default) or "delete".',
+        },
+        commit: {
+          type: 'string',
+          description: 'Target commit hash to place the tag on when creating (defaults to current HEAD).',
+        },
+        message: {
+          type: 'string',
+          description: 'Optional annotation message for an annotated tag (git tag -a -m).',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: true,
+        },
+        render: (_args, val) => {
+          const value = val as { success?: boolean; name?: string; message?: string }
+          return [{
+            type: 'text',
+            text: value.message ?? (value.success ? 'Success' : 'Failed'),
+          }]
+        },
+      },
+      async execute(args, exec): Promise<Record<string, JsonValue>> {
+        const cwd = resolveDir(exec.agent?.session.id)
+        const name = args.name.trim()
+        const action = args.action ?? 'create'
+
+        if (action === 'delete') {
+          const result = await gitDeleteTag(cwd, name)
+          return {
+            success: result.success,
+            name,
+            action: 'delete',
+            message: result.message ?? '',
+          }
+        }
+
+        const result = await gitCreateTag(cwd, name, args.commit, args.message)
+        return {
+          success: result.success,
+          name,
+          action: 'create',
+          message: result.message ?? '',
+        }
+      },
+      presentCall: args => ({
+        card: 'generic',
+        title: `git_tag ${args.action ?? 'create'} ${args.name}`,
+        rawInput: args,
+      }),
+    })), 'experimental-git: register git_tag tool')
+  })
+}

package/src/types.ts

@@ -0,0 +1,187 @@
+/**
+ * Core type declarations for the experimental Git plugin.
+ * Shared across the Host RPC handlers and Client UI viewers.
+ */
+
+/** File change status representation in git */
+export type GitFileStatusCode = 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked' | 'copied'
+
+/** One changed file entry in the working directory or staging area */
+export interface GitFileStatus {
+  /** Relative file path from the repository root */
+  readonly path: string
+  /** Previous path if the file was renamed */
+  readonly originalPath?: string
+  /** Normalized status kind */
+  readonly status: GitFileStatusCode
+  /** Whether the change has been staged to index */
+  readonly staged: boolean
+}
+
+/** Information about one local git branch */
+export interface GitBranchInfo {
+  /** Branch name (e.g. 'main', 'master', 'feature/xyz') */
+  readonly name: string
+  /** Whether this branch is currently checked out */
+  readonly isCurrent: boolean
+  /** Upstream tracking branch if configured */
+  readonly upstream?: string
+  /** Number of commits ahead of upstream */
+  readonly ahead?: number
+  /** Number of commits behind upstream */
+  readonly behind?: number
+}
+
+/** Full status summary of the workspace repository */
+export interface GitStatusSummary {
+  /** Whether the checked directory is inside a Git worktree/repository */
+  readonly isRepo: boolean
+  /** Absolute root directory of the repository */
+  readonly rootPath?: string
+  /** Current branch name, or commit hash if detached */
+  readonly branch?: string
+  /** Upstream branch name */
+  readonly upstream?: string
+  /** Commits ahead of upstream */
+  readonly ahead: number
+  /** Commits behind upstream */
+  readonly behind: number
+  /** Latest commit summary on current HEAD */
+  readonly headCommit?: {
+    readonly hash: string
+    readonly shortHash: string
+    readonly message: string
+  }
+  /** Staged changes in index */
+  readonly staged: readonly GitFileStatus[]
+  /** Unstaged changes in working tree */
+  readonly unstaged: readonly GitFileStatus[]
+  /** Untracked new files */
+  readonly untracked: readonly GitFileStatus[]
+  /** Total count of all changed/untracked files */
+  readonly totalChanges: number
+  /** Total count of commits in the current repository */
+  readonly totalCommitsCount?: number
+}
+
+/** One commit log entry with optional DAG topology metadata */
+export interface GitCommitItem {
+  /** Full 40-character commit hash */
+  readonly hash: string
+  /** Abbreviated 7-character commit hash */
+  readonly shortHash: string
+  /** Author name */
+  readonly author: string
+  /** Author email address */
+  readonly authorEmail: string
+  /** Human-readable relative date (e.g. '2 hours ago') */
+  readonly relativeDate: string
+  /** ISO date string */
+  readonly date: string
+  /** Commit subject/first line of commit message */
+  readonly subject: string
+  /** Full multiline commit body message (excluding subject) */
+  readonly body?: string
+  /** Parent commit hashes */
+  readonly parents?: readonly string[]
+  /** Git branch / tag reference names */
+  readonly refs?: readonly string[]
+  /** Topological vertical lane column index (0-based) */
+  readonly lane?: number
+  /** Color hex code for the current commit's lane */
+  readonly laneColor?: string
+  /** Connecting graph rails to parent commits */
+  readonly paths?: readonly GitGraphLanePath[]
+}
+
+/** Vector path connecting lanes in the DAG graph visualization */
+export interface GitGraphLanePath {
+  /** Starting lane index (from this commit) */
+  readonly fromLane: number
+  /** Target lane index (to parent commit or pass-through) */
+  readonly toLane: number
+  /** Type of track: pass-through, fork out, or merge in */
+  readonly kind: 'straight' | 'fork' | 'merge'
+  /** Color of this track line */
+  readonly color: string
+}
+
+/** Detail information for a single commit including changed files */
+export interface GitCommitDetail {
+  readonly commit: GitCommitItem
+  readonly body?: string
+  readonly parents?: readonly string[]
+  readonly files: readonly {
+    readonly path: string
+    readonly oldPath?: string
+    readonly status: GitFileStatusCode
+    readonly additions: number
+    readonly deletions: number
+  }[]
+  readonly totalAdditions: number
+  readonly totalDeletions: number
+}
+
+/** Complete log query summary including commits and total count */
+export interface GitLogSummary {
+  readonly commits: readonly GitCommitItem[]
+  readonly totalCount: number
+}
+
+/** One Git tag entry */
+export interface GitTagItem {
+  /** Tag name (e.g. 'v1.0.0', 'dsh-v0.2.1-rc.2') */
+  readonly name: string
+  /** Target commit full 40-character SHA hash */
+  readonly commitHash: string
+  /** Target commit abbreviated 7-character hash */
+  readonly shortHash: string
+  /** ISO 8601 date string of tag or commit */
+  readonly date: string
+  /** Human-readable relative date (e.g. '3 days ago') */
+  readonly relativeDate: string
+  /** Tag annotation message or commit subject */
+  readonly message: string
+  /** Author or tagger name */
+  readonly author: string
+  /** Whether this is an annotated tag (git tag -a) */
+  readonly isAnnotated: boolean
+}
+
+/** Aggregated local and remote branches */
+export interface GitBranchesSummary {
+  readonly current?: string
+  readonly local: readonly GitBranchInfo[]
+  readonly remote: readonly GitBranchInfo[]
+}
+
+/** Generic result of executing a git mutative operation */
+export interface GitOperationResult {
+  readonly success: boolean
+  readonly message?: string
+  readonly output?: string
+}
+
+/** One file's diff result */
+export interface GitDiffFile {
+  /** File path */
+  readonly path: string
+  /** Old file path if renamed */
+  readonly oldPath?: string
+  /** Change status */
+  readonly status: GitFileStatusCode
+  /** Raw unified diff patch lines */
+  readonly diffText: string
+  /** Count of added lines */
+  readonly additions: number
+  /** Count of removed lines */
+  readonly deletions: number
+}
+
+/** Complete diff result summary */
+export interface GitDiffSummary {
+  /** List of parsed diff files */
+  readonly files: readonly GitDiffFile[]
+  /** Complete raw unified diff output */
+  readonly rawDiff: string
+}