contextgit 0.0.1 → 0.0.2

package/packages/core/src/summarizer.ts

@@ -0,0 +1,113 @@
+// RollingSummarizer — Week 2: Claude Haiku with graceful string-truncation fallback.
+// If the API key is absent or the API call fails, falls back to string truncation.
+// The interface is stable; callers never know which implementation is running.
+
+import Anthropic from '@anthropic-ai/sdk'
+
+export interface SummarizerOptions {
+  /** Max characters for project-level summaries (~2000 tokens). */
+  maxProjectChars?: number
+  /** Max characters for branch-level summaries (~500 tokens). */
+  maxBranchChars?: number
+  /**
+   * Inject a pre-built Anthropic client (useful for tests).
+   * If omitted, one is created from ANTHROPIC_API_KEY.
+   * If ANTHROPIC_API_KEY is also absent, falls back to string truncation.
+   */
+  client?: Anthropic
+}
+
+export class RollingSummarizer {
+  private readonly maxProjectChars: number
+  private readonly maxBranchChars: number
+  private readonly client: Anthropic | null
+
+  constructor(options: SummarizerOptions = {}) {
+    this.maxProjectChars = options.maxProjectChars ?? 8000
+    this.maxBranchChars  = options.maxBranchChars  ?? 2000
+
+    if (options.client !== undefined) {
+      this.client = options.client
+    } else if (process.env['ANTHROPIC_API_KEY']) {
+      this.client = new Anthropic()
+    } else {
+      this.client = null
+    }
+  }
+
+  /**
+   * Roll `content` into `previousSummary` and return a new summary that fits
+   * within the budget for the given scope.
+   *
+   * Week 2: uses Claude Haiku for intelligent compression.
+   * Fallback: dumb truncation (newest content appended, trimmed from the start
+   * so the most-recent work is always present).
+   *
+   * Never throws — summarizer failures are silently swallowed.
+   */
+  async summarize(
+    content: string,
+    previousSummary: string,
+    budget: 'project' | 'branch',
+  ): Promise<string> {
+    const max = budget === 'project' ? this.maxProjectChars : this.maxBranchChars
+
+    if (this.client !== null) {
+      try {
+        return await this._claudeSummarize(content, previousSummary, max)
+      } catch {
+        // Graceful fallback — never propagate summarizer failure to the caller.
+      }
+    }
+
+    return this._truncateSummarize(content, previousSummary, max)
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────────────
+
+  private async _claudeSummarize(
+    content: string,
+    previousSummary: string,
+    maxChars: number,
+  ): Promise<string> {
+    const userContent = previousSummary
+      ? `Previous summary:\n${previousSummary}\n\nNew content to integrate:\n${content}`
+      : `Content to summarize:\n${content}`
+
+    const response = await this.client!.messages.create({
+      model: 'claude-haiku-4-5',
+      max_tokens: 1024,
+      system:
+        'You are a context summarizer for an AI coding agent. ' +
+        'Return only the summary text with no preamble or explanation.',
+      messages: [
+        {
+          role: 'user',
+          content:
+            userContent +
+            `\n\nCreate a concise rolling summary (max ${maxChars} characters) ` +
+            'that preserves the most important recent work and decisions. ' +
+            'Return only the summary text.',
+        },
+      ],
+    })
+
+    const text = response.content
+      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
+      .map(b => b.text)
+      .join('')
+
+    return text.slice(0, maxChars)
+  }
+
+  private _truncateSummarize(
+    content: string,
+    previousSummary: string,
+    max: number,
+  ): string {
+    const combined = previousSummary ? `${previousSummary}\n\n${content}` : content
+    if (combined.length <= max) return combined
+    // Keep the tail so recent work is never lost.
+    return combined.slice(combined.length - max)
+  }
+}

package/packages/core/src/threads.ts

@@ -0,0 +1,29 @@
+// ThreadManager — read-side helper for the open-thread immune-to-compression guarantee.
+//
+// Key invariant: open threads are stored in the `threads` table and NEVER
+// passed to the summarizer.  This file enforces that boundary by providing
+// the only sanctioned way to query open threads.
+//
+// Write-side (opening / closing threads) happens via CommitInput.threads
+// inside store.createCommit(), which is the right transactional boundary.
+
+import type { Thread } from './types.js'
+
+export interface ThreadReader {
+  listOpenThreads(projectId: string): Promise<Thread[]>
+  listOpenThreadsByBranch(branchId: string): Promise<Thread[]>
+}
+
+export class ThreadManager {
+  constructor(private readonly store: ThreadReader) {}
+
+  /** All open threads for a project, across all branches. */
+  openForProject(projectId: string): Promise<Thread[]> {
+    return this.store.listOpenThreads(projectId)
+  }
+
+  /** Open threads scoped to a single branch. */
+  openForBranch(branchId: string): Promise<Thread[]> {
+    return this.store.listOpenThreadsByBranch(branchId)
+  }
+}

package/packages/core/src/types.ts

@@ -0,0 +1,240 @@
+
+
+// ============================================
+// Primitive Types
+// ============================================
+
+export type AgentRole = 
+  | 'orchestrator' 
+  | 'dev' 
+  | 'test' 
+  | 'review' 
+  | 'background' 
+  | 'ci' 
+  | 'solo'
+
+export type WorkflowType = 
+  | 'interactive' 
+  | 'ralph-loop' 
+  | 'ci' 
+  | 'background' 
+  | 'custom'
+
+export type CommitType = 
+  | 'manual' 
+  | 'auto' 
+  | 'merge' 
+  | 'branch-init'
+
+export type BranchStatus =
+  | 'active'
+  | 'merged'
+  | 'abandoned'
+
+export type ClaimStatus =
+  | 'proposed'
+  | 'active'
+  | 'released'
+
+export type SnapshotFormat = 
+  | 'agents-md' 
+  | 'json' 
+  | 'text'
+
+export type ContextScope = 
+  | 'global' 
+  | 'branch' 
+  | 'search' 
+  | 'commit' 
+  | 'raw'
+
+// ============================================
+// Core Entities
+// ============================================
+
+export interface Project {
+  id: string
+  name: string
+  description?: string
+  githubUrl?: string
+  createdAt: Date
+}
+
+export interface Branch {
+  id: string
+  projectId: string
+  name: string
+  gitBranch: string
+  githubPrUrl?: string
+  parentBranchId?: string
+  headCommitId?: string
+  status: BranchStatus
+  createdAt: Date
+  mergedAt?: Date
+}
+
+export interface Commit {
+  id: string
+  branchId: string
+  parentId?: string
+  mergeSourceBranchId?: string
+  agentId: string
+  agentRole: AgentRole
+  tool: string
+  workflowType: WorkflowType
+  loopIteration?: number
+  ciRunId?: string
+  pipelineName?: string
+  message: string
+  content: string
+  summary: string
+  commitType: CommitType
+  gitCommitSha?: string
+  createdAt: Date
+}
+
+export interface Thread {
+  id: string
+  projectId: string
+  branchId: string
+  description: string        // max 200 chars
+  status: 'open' | 'closed'
+  workflowType?: WorkflowType
+  openedInCommit: string
+  closedInCommit?: string
+  closedNote?: string
+  createdAt: Date
+}
+
+export interface Agent {
+  id: string
+  projectId: string
+  role: AgentRole
+  tool: string
+  workflowType: WorkflowType
+  displayName?: string
+  totalCommits: number
+  lastSeen: Date
+  createdAt: Date
+}
+
+export interface Claim {
+  id: string
+  projectId: string
+  branchId: string
+  task: string
+  agentId: string
+  role: AgentRole
+  claimedAt: Date
+  status: ClaimStatus
+  ttl: number          // ms, default 7_200_000 (2h)
+  releasedAt?: Date
+}
+
+// ============================================
+// Input Types (for creating entities)
+// ============================================
+
+export interface ProjectInput {
+  id?: string           // caller-supplied ID; LocalStore generates nanoid() if omitted
+  name: string
+  description?: string
+  githubUrl?: string
+}
+
+export interface BranchInput {
+  id?: string           // caller-supplied ID; LocalStore generates nanoid() if omitted
+  projectId: string
+  name: string
+  gitBranch: string
+  parentBranchId?: string
+  githubPrUrl?: string
+}
+
+export interface CommitInput {
+  id?: string           // caller-supplied ID; LocalStore generates nanoid() if omitted
+  branchId: string
+  parentId?: string
+  agentId: string
+  agentRole: AgentRole
+  tool: string
+  workflowType: WorkflowType
+  loopIteration?: number
+  ciRunId?: string
+  pipelineName?: string
+  message: string
+  content: string
+  summary: string
+  commitType: CommitType
+  gitCommitSha?: string
+  threads?: {
+    open?: string[]
+    close?: Array<{ id: string; note: string }>
+  }
+}
+
+export interface AgentInput {
+  id: string
+  projectId: string
+  role: AgentRole
+  tool: string
+  workflowType: WorkflowType
+  displayName?: string
+}
+
+export interface ClaimInput {
+  task: string
+  agentId: string
+  role: AgentRole
+  status?: ClaimStatus   // defaults to 'proposed'
+  ttl?: number           // ms, defaults to 7_200_000 (2h)
+}
+
+// ============================================
+// Session Snapshot
+// ============================================
+
+export interface SessionSnapshot {
+  projectSummary: string       // max 2000 tokens
+  branchName: string
+  branchSummary: string        // max 500 tokens
+  recentCommits: Commit[]      // last 3
+  openThreads: Thread[]
+  activeClaims: Claim[]        // non-released, non-TTL-expired claims
+}
+
+// ============================================
+// Search
+// ============================================
+
+export interface SearchResult {
+  commit: Commit
+  score: number
+  matchType: 'semantic' | 'fulltext'
+}
+
+// ============================================
+// Config
+// ============================================
+
+export interface ContextGitConfig {
+  project: string
+  projectId: string
+  store: 'local' | string      // 'local' or remote URL
+  remote?: string              // remote ContextGit API URL for push/pull
+  agentRole: AgentRole
+  workflowType: WorkflowType
+  autoSnapshot: boolean
+  snapshotInterval: number
+  embeddingModel: 'local' | 'openai'
+  apiKey?: string
+}
+
+// ============================================
+// Pagination
+// ============================================
+
+export interface Pagination {
+  limit: number
+  offset: number
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/mcp/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@contextgit/mcp",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "contextgit-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@contextgit/core": "workspace:*",
+    "@contextgit/store": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "simple-git": "^3.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/packages/mcp/src/auto-snapshot.ts

@@ -0,0 +1,83 @@
+// auto-snapshot.ts — AutoSnapshotManager
+//
+// Tracks tool calls made to the MCP server and fires an automatic context_commit
+// after every N=10 non-commit calls. This ensures context is preserved even when
+// the agent forgets to call context_commit manually.
+//
+// Context tool semantics:
+//   context_commit  → resets the counter (manual commit = checkpoint reached)
+//   context_get     → counted (each session-start snapshot counts toward the interval)
+//   context_search  → counted
+//   any other tool  → counted (future tools)
+
+import type { ContextEngine } from '@contextgit/core'
+
+export interface AutoSnapshotOptions {
+  /** Number of non-commit tool calls before an auto-commit fires. Default: 10. */
+  interval?: number
+}
+
+export class AutoSnapshotManager {
+  private count = 0
+  private readonly interval: number
+  private readonly engine: ContextEngine
+
+  constructor(engine: ContextEngine, options: AutoSnapshotOptions = {}) {
+    this.engine = engine
+    this.interval = options.interval ?? 10
+  }
+
+  /**
+   * Record a tool call by name.
+   *
+   * - `context_commit` resets the counter (manual commit; no auto-commit fired).
+   * - All other tool names increment the counter.
+   * - When the counter reaches `interval`, an auto-commit is fired and the
+   *   counter resets to 0.
+   *
+   * Auto-commit failures are swallowed — the tool call is never blocked.
+   *
+   * @returns The new commit ID if an auto-commit was fired, otherwise undefined.
+   */
+  async onToolCall(toolName: string): Promise<string | undefined> {
+    if (toolName === 'context_commit') {
+      this.count = 0
+      return undefined
+    }
+
+    this.count++
+
+    if (this.count >= this.interval) {
+      this.count = 0
+      return this.fireAutoCommit()
+    }
+
+    return undefined
+  }
+
+  /** Current tool-call count since the last commit (manual or auto). */
+  get toolCallCount(): number {
+    return this.count
+  }
+
+  /** Manually reset the counter (e.g. after an out-of-band commit). */
+  reset(): void {
+    this.count = 0
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  private async fireAutoCommit(): Promise<string | undefined> {
+    try {
+      const commit = await this.engine.commit({
+        message: `Auto-snapshot after ${this.interval} tool calls`,
+        content: `Automatic context checkpoint triggered after ${this.interval} tool calls without a manual context_commit.`,
+        commitType: 'auto',
+      })
+      return commit.id
+    } catch {
+      // Never block a tool call due to auto-snapshot failure.
+      return undefined
+    }
+  }
+}

package/packages/mcp/src/config.ts

@@ -0,0 +1,53 @@
+// config.ts — load and validate .contextgit/config.json
+// Searches from CWD upwards until it finds the config file.
+
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import type { ContextGitConfig } from '@contextgit/core'
+
+export class ConfigNotFoundError extends Error {
+  constructor(startDir: string) {
+    super(`No .contextgit/config.json found searching upward from: ${startDir}`)
+    this.name = 'ConfigNotFoundError'
+  }
+}
+
+/**
+ * Search upward from `startDir` for `.contextgit/config.json`.
+ * Returns the first match found, or throws ConfigNotFoundError.
+ */
+export function findConfigPath(startDir: string = process.cwd()): string {
+  let current = startDir
+  while (true) {
+    const candidate = join(current, '.contextgit', 'config.json')
+    try {
+      readFileSync(candidate)
+      return candidate
+    } catch {
+      const parent = dirname(current)
+      if (parent === current) {
+        throw new ConfigNotFoundError(startDir)
+      }
+      current = parent
+    }
+  }
+}
+
+/**
+ * Load and parse `.contextgit/config.json`.
+ * Throws ConfigNotFoundError if not found, or Error if JSON is invalid.
+ */
+export function loadConfig(startDir?: string): ContextGitConfig {
+  const configPath = findConfigPath(startDir)
+  const raw = readFileSync(configPath, 'utf-8')
+  const config = JSON.parse(raw) as ContextGitConfig
+
+  if (!config.projectId) {
+    throw new Error(`Invalid config at ${configPath}: missing required field 'projectId'`)
+  }
+  if (!config.project) {
+    throw new Error(`Invalid config at ${configPath}: missing required field 'project'`)
+  }
+
+  return config
+}

package/packages/mcp/src/git-sync.ts

@@ -0,0 +1,94 @@
+// git-sync.ts — git metadata capture and hook installation.
+//
+// captureGitMetadata: used by context_commit (MCP) and commit CLI command to
+//   auto-populate gitCommitSha on every context commit.
+//
+// installGitHooks: idempotent hook installer — writes post-commit,
+//   post-checkout, post-merge scripts into .git/hooks/.
+
+import { writeFileSync, readFileSync, mkdirSync, existsSync, appendFileSync } from 'fs'
+import { join, resolve } from 'path'
+import { homedir } from 'os'
+import { simpleGit } from 'simple-git'
+
+const SENTINEL = '# contextgit'
+const HOOKS_LOG = join(homedir(), '.contextgit', 'hooks.log')
+
+// ─── captureGitMetadata ────────────────────────────────────────────────────────
+
+/**
+ * Capture the current git commit SHA and branch name.
+ * Returns null on any error — must never block a context commit.
+ */
+export async function captureGitMetadata(
+  cwd: string,
+): Promise<{ sha: string; branch: string } | null> {
+  try {
+    const git = simpleGit(cwd)
+    const [sha, branch] = await Promise.all([
+      git.revparse(['HEAD']),
+      git.revparse(['--abbrev-ref', 'HEAD']),
+    ])
+    return { sha: sha.trim(), branch: branch.trim() }
+  } catch {
+    return null
+  }
+}
+
+// ─── installGitHooks ──────────────────────────────────────────────────────────
+
+const HOOK_SCRIPTS: Record<string, string> = {
+  'post-commit': `#!/bin/sh
+${SENTINEL}
+contextgit commit -m "git: $(git log -1 --pretty=%s)" 2>>"${HOOKS_LOG}" || true
+`,
+  'post-checkout': `#!/bin/sh
+${SENTINEL}
+contextgit context --quiet 2>>"${HOOKS_LOG}" || true
+`,
+  'post-merge': `#!/bin/sh
+${SENTINEL}
+contextgit commit -m "Merged into $(git rev-parse --abbrev-ref HEAD)" 2>>"${HOOKS_LOG}" || true
+`,
+}
+
+/**
+ * Install contextgit git hooks into <projectRoot>/.git/hooks/.
+ * Idempotent: checks for the sentinel comment before appending.
+ * Hook failures are logged to ~/.contextgit/hooks.log — never to stderr.
+ */
+export async function installGitHooks(projectRoot: string): Promise<void> {
+  const hooksDir = join(resolve(projectRoot), '.git', 'hooks')
+  mkdirSync(hooksDir, { recursive: true })
+
+  for (const [hookName, script] of Object.entries(HOOK_SCRIPTS)) {
+    const hookPath = join(hooksDir, hookName)
+
+    if (existsSync(hookPath)) {
+      const existing = readFileSync(hookPath, 'utf-8')
+      if (existing.includes(SENTINEL)) continue  // already installed
+      // Append to existing hook
+      writeFileSync(hookPath, existing.trimEnd() + '\n\n' + script)
+    } else {
+      writeFileSync(hookPath, script)
+    }
+
+    // Make executable (chmod +x)
+    try {
+      const { chmodSync } = await import('fs')
+      chmodSync(hookPath, 0o755)
+    } catch {
+      logHookError(`chmod failed for ${hookPath}`)
+    }
+  }
+}
+
+function logHookError(msg: string): void {
+  try {
+    const dir = join(homedir(), '.contextgit')
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(HOOKS_LOG, `[${new Date().toISOString()}] ${msg}\n`)
+  } catch {
+    // truly silent
+  }
+}

package/packages/mcp/src/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// index.ts — entry point for the ContextGit MCP server process.
+// Started by the MCP host (Claude Desktop / Claude Code) via stdio.
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createServer } from './server.js'
+
+async function main(): Promise<void> {
+  const server = await createServer()
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  // Server is now listening on stdin/stdout — process stays alive until the
+  // host closes the connection.
+}
+
+main().catch(err => {
+  console.error('[contextgit-mcp] Fatal error:', err)
+  process.exit(1)
+})