@vikasitai/vikasit-code 2.0.7 → 2.0.9

package/specs/claude-code-integration.md

@@ -1,563 +0,0 @@
-# Claude Code Integration Plan
-
-This document outlines the integration of Claude Code components into Vikasit Code, excluding the UI layer (React components, hooks, Ink rendering).
-
-## Architecture Mapping
-
-| Claude Code Pattern  | Vikasit Equivalent     | Integration Approach    |
-| -------------------- | ---------------------- | ----------------------- |
-| `Effect.gen()`       | `Effect.gen()`         | Direct compatibility    |
-| `Command` module     | `src/command/index.ts` | Expand command registry |
-| `Tool.ts`            | `src/tool/tool.ts`     | Extend tool definitions |
-| `services/mcp/*`     | `src/mcp/*`            | MCP service expansion   |
-| `remote/*`           | New module             | Create remote sessions  |
-| `skills/*`           | `src/skill/*`          | Expand skill system     |
-| `utils/*` (331 dirs) | `src/util/*`           | selective adoption      |
-
----
-
-## 1. Commands System
-
-**Current Vikasit:** 2 commands (init, review) via template system
-**Claude Code:** ~100 commands across 103 subdirectories
-
-### Integration Steps
-
-```typescript
-// src/command/index.ts - Expand command registry
-export const CommandRegistry = {
-  // Existing
-  INIT: "init",
-  REVIEW: "review",
-
-  // New commands to add
-  LOGIN: "login", // Auth management
-  LOGOUT: "logout",
-  CONFIG: "config", // Configuration
-  MCP: "mcp", // MCP server management
-  SKILLS: "skills", // Skill discovery/installation
-  TELEPORT: "teleport", // Session migration
-  SESSION: "session", // Session management
-  MEMORY: "memory", // Memory operations
-  COST: "cost", // Cost tracking
-  STATUS: "status", // System status
-  THEME: "theme", // Theme configuration
-  VIM: "vim", // Vim mode toggle
-  WORKTREE: "worktree", // Git worktree management
-  // ... 80+ more
-}
-```
-
-### Files to Create/Copy
-
-```
-src/command/
-  login.ts          # OAuth/API key auth
-  logout.ts
-  config.ts         # Config management
-  mcp.ts            # MCP enable/disable/list
-  skills.ts         # Skill install/list/remove
-  teleport.ts       # Session migration
-  session.ts        # Session list/archive/delete
-  memory.ts         # Memory extract/view
-  cost.ts           # Cost display
-  status.ts         # System status
-  theme.ts          # Theme switch
-  worktree.ts       # Worktree create/list
-  // ... more
-```
-
-**Estimated effort:** 2-3 days for core commands
-
----
-
-## 2. Remote Sessions
-
-**Current Vikasit:** Local sessions only
-**Claude Code:** RemoteSessionManager, SessionsWebSocket, permission bridge
-
-### Integration Steps
-
-```typescript
-// src/remote/RemoteSessionManager.ts (new)
-import { Effect, ServiceMap } from "effect"
-import { SessionID } from "@/session/schema"
-
-export namespace RemoteSessionManager {
-  export interface Interface {
-    readonly connect: (url: string) => Effect.Effect<void>
-    readonly disconnect: () => Effect.Effect<void>
-    readonly share: (sessionID: SessionID) => Effect.Effect<string>
-    readonly receive: () => Effect.Effect<RemoteMessage>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/RemoteSessionManager") {}
-}
-```
-
-```typescript
-// src/remote/SessionsWebSocket.ts (new)
-import { Instance.bind } from "@/project/instance"
-import { Bus } from "@/bus"
-
-export function createWebSocketSession(url: string) {
-  const ws = new WebSocket(url)
-
-  // Use Instance.bind for callback context restoration
-  const onMessage = Instance.bind((data) => {
-    Bus.publish(RemotionEvent, JSON.parse(data))
-  })
-
-  ws.onmessage = onMessage
-  return ws
-}
-```
-
-### Files to Create
-
-```
-src/remote/
-  RemoteSessionManager.ts
-  SessionsWebSocket.ts
-  remotePermissionBridge.ts
-  sdkMessageAdapter.ts
-```
-
-**Estimated effort:** 3-4 days
-
----
-
-## 3. MCP Expansion
-
-**Current Vikasit:** Basic auth + OAuth provider (4 files)
-**Claude Code:** 22 MCP service files + 4 MCP tools
-
-### Integration Steps
-
-```typescript
-// src/mcp/index.ts - Expand MCP module
-export namespace MCP {
-  // Existing
-  export const auth = ...
-
-  // New additions
-  export const client = ...        // MCP client wrapper
-  export const connectionManager = ...  // Connection lifecycle
-  export const elicitation = ...   // MCP elicitation handling
-  export const resources = ...     // Resource listing/reading
-  export const tools = ...         // MCP tool invocation
-  export const oauth = ...         // OAuth flow
-  export const transport = ...     // Stdio/SSE/HTTP/WebSocket
-}
-```
-
-### Files to Create/Copy
-
-```
-src/mcp/
-  client.ts              # MCP Client wrapper (3.3KB Claude Code)
-  MCPConnectionManager.ts # Connection lifecycle
-  elicitationHandler.ts  # MCP elicitation
-  oauth.ts               # OAuth flow
-  transport.ts           # Transport adapters
-  resources.ts           # Resource operations
-  tools.ts               # MCP tool invocation
-  config.ts              # MCP configuration
-  types.ts               # MCP type definitions
-  utils.ts               # MCP utilities
-```
-
-**Estimated effort:** 4-5 days
-
----
-
-## 4. Plugin Architecture
-
-**Current Vikasit:** Basic plugin module exists
-**Claude Code:** Full plugin system with CLI commands
-
-### Integration Steps
-
-```typescript
-// src/plugin/index.ts - Expand
-export namespace Plugin {
-  export interface Interface {
-    readonly install: (name: string) => Effect.Effect<void>
-    readonly uninstall: (name: string) => Effect.Effect<void>
-    readonly list: () => Effect.Effect<Plugin.Info[]>
-    readonly enable: (name: string) => Effect.Effect<void>
-    readonly disable: (name: string) => Effect.Effect<void>
-  }
-
-  // Plugin lifecycle hooks
-  export const hooks = {
-    onInstall: ...,
-    onUninstall: ...,
-    onEnable: ...,
-    onDisable: ...,
-  }
-}
-```
-
-### Files to Create
-
-```
-src/plugin/
-  cli.ts                # Plugin CLI commands
-  registry.ts           # Plugin registry
-  lifecycle.ts          # Plugin lifecycle
-  validation.ts         # Plugin validation
-```
-
-**Estimated effort:** 2-3 days
-
----
-
-## 5. Memory System
-
-**Current Vikasit:** Basic skill discovery
-**Claude Code:** SessionMemory, teamMemorySync, extractMemories
-
-### Integration Steps
-
-```typescript
-// src/service/SessionMemory.ts (new)
-import { Effect, ServiceMap } from "effect"
-import { SessionID } from "@/session/schema"
-
-export namespace SessionMemory {
-  export interface Interface {
-    readonly init: (sessionID: SessionID) => Effect.Effect<void>
-    readonly extract: () => Effect.Effect<Memory[]>
-    readonly sync: () => Effect.Effect<void>
-    readonly clear: () => Effect.Effect<void>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/SessionMemory") {}
-
-  export const layer = Layer.effect(
-    Service,
-    Effect.gen(function* () {
-      const db = yield* Database.Service
-      const session = yield* Session.Service
-
-      return {
-        init: Effect.fn("SessionMemory.init")(function* (sessionID) {
-          // Initialize memory for session
-        }),
-        extract: Effect.fn("SessionMemory.extract")(function* () {
-          // Extract memories from session
-        }),
-        // ...
-      }
-    }),
-  )
-}
-```
-
-### Files to Create
-
-```
-src/service/
-  SessionMemory.ts       # Session memory management
-  teamMemorySync.ts      # Team memory synchronization
-  extractMemories.ts     # Memory extraction logic
-```
-
-**Estimated effort:** 2-3 days
-
----
-
-## 6. Swarm/Coordinator
-
-**Current Vikasit:** Single agent model
-**Claude Code:** coordinator mode, teammate, swarm backends
-
-### Integration Steps
-
-```typescript
-// src/coordinator/coordinatorMode.ts (new)
-import { Effect, ServiceMap } from "effect"
-import { AgentID } from "@/agent/schema"
-
-export namespace CoordinatorMode {
-  export interface Interface {
-    readonly enable: () => Effect.Effect<void>
-    readonly disable: () => Effect.Effect<void>
-    readonly createTeammate: (config: TeammateConfig) => Effect.Effect<TeammateID>
-    readonly assignTask: (teammateID: TeammateID, task: string) => Effect.Effect<void>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/CoordinatorMode") {}
-}
-```
-
-### Files to Create
-
-```
-src/coordinator/
-  coordinatorMode.ts     # Coordinator mode
-  teammate.ts            # Teammate management
-  swarmBackend.ts        # Swarm orchestration
-  reconnection.ts        # Swarm reconnection
-```
-
-**Estimated effort:** 5-7 days (complex feature)
-
----
-
-## 7. Query Engine
-
-**Current Vikasit:** No query engine
-**Claude Code:** QueryEngine.ts (46KB), query.ts (68KB)
-
-### Integration Steps
-
-```typescript
-// src/query/QueryEngine.ts (new)
-import { Effect, ServiceMap } from "effect"
-
-export namespace QueryEngine {
-  export interface Interface {
-    readonly execute: (query: string) => Effect.Effect<QueryResult>
-    readonly parse: (query: string) => Effect.Effect<ParsedQuery>
-    readonly optimize: (query: ParsedQuery) => Effect.Effect<ParsedQuery>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/QueryEngine") {}
-}
-```
-
-### Files to Create
-
-```
-src/query/
-  QueryEngine.ts         # Query execution engine
-  query.ts               # Query DSL
-  parser.ts              # Query parser
-  optimizer.ts           # Query optimizer
-```
-
-**Estimated effort:** 5-7 days (complex feature)
-
----
-
-## 8. Cost Tracking
-
-**Current Vikasit:** No cost tracking
-**Claude Code:** cost-tracker.ts (10KB), costHook.ts
-
-### Integration Steps
-
-```typescript
-// src/service/CostTracker.ts (new)
-import { Effect, ServiceMap } from "effect"
-import { Decimal } from "decimal.js"
-
-export namespace CostTracker {
-  export interface Interface {
-    readonly track: (usage: Usage) => Effect.Effect<void>
-    readonly getTotal: () => Effect.Effect<Decimal>
-    readonly getRemaining: () => Effect.Effect<Decimal>
-    readonly checkThreshold: () => Effect.Effect<boolean>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/CostTracker") {}
-}
-```
-
-### Files to Create
-
-```
-src/service/
-  CostTracker.ts         # Cost tracking
-  quotaManager.ts        # Quota management
-  limits.ts              # Cost limits
-```
-
-**Estimated effort:** 1-2 days
-
----
-
-## 9. Policy Limits
-
-**Current Vikasit:** No policy system
-**Claude Code:** policyLimits, remoteManagedSettings
-
-### Integration Steps
-
-```typescript
-// src/service/PolicyLimits.ts (new)
-import { Effect, ServiceMap } from "effect"
-
-export namespace PolicyLimits {
-  export interface Interface {
-    readonly load: () => Effect.Effect<Policy>
-    readonly check: (action: string) => Effect.Effect<boolean>
-    readonly isAllowed: (tool: string, path: string) => Effect.Effect<boolean>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/PolicyLimits") {}
-}
-```
-
-### Files to Create
-
-```
-src/service/
-  PolicyLimits.ts        # Policy enforcement
-  remoteManagedSettings.ts # Remote settings
-```
-
-**Estimated effort:** 2-3 days
-
----
-
-## 10. Migration System
-
-**Current Vikasit:** Drizzle migrations only
-**Claude Code:** 13 migration modules
-
-### Integration Steps
-
-Vikasit already has Drizzle migrations. Additional migrations needed:
-
-```typescript
-// src/migrations/
-resetProToOpusDefault.ts  # Model defaults
-// ... more data migrations
-```
-
-**Estimated effort:** 1 day
-
----
-
-## 11. Worktree/tmux
-
-**Current Vikasit:** Basic worktree module exists
-**Claude Code:** worktree creation, tmux integration
-
-### Integration Steps
-
-```typescript
-// src/worktree/index.ts - Expand
-export namespace Worktree {
-  export const create = Effect.fn("Worktree.create")(function* (name: string) {
-    // Create git worktree
-    // Create tmux session
-  })
-
-  export const list = Effect.fn("Worktree.list")(function* () {
-    // List worktrees
-  })
-
-  export const tmuxSession = Effect.fn("Worktree.tmux")(function* (name: string) {
-    // Create tmux session
-  })
-}
-```
-
-### Files to Create
-
-```
-src/worktree/
-  tmux.ts                # tmux integration
-```
-
-**Estimated effort:** 1-2 days
-
----
-
-## 12. Analytics Gates
-
-**Current Vikasit:** No analytics
-**Claude Code:** GrowthBook, telemetry, event tracking
-
-### Integration Steps
-
-```typescript
-// src/service/Analytics.ts (new)
-import { Effect, ServiceMap } from "effect"
-
-export namespace Analytics {
-  export interface Interface {
-    readonly logEvent: (event: string, data: Record<string, any>) => Effect.Effect<void>
-    readonly initializeGates: () => Effect.Effect<void>
-    readonly getFeatureValue: (feature: string) => Effect.Effect<string>
-  }
-
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/Analytics") {}
-}
-```
-
-### Files to Create
-
-```
-src/service/
-  Analytics.ts           # Analytics service
-  growthbook.ts          # Feature gates
-  telemetry.ts           # Telemetry
-  eventTracking.ts       # Event tracking
-```
-
-**Estimated effort:** 2-3 days
-
----
-
-## Integration Timeline
-
-| Phase     | Components                                   | Estimated Time |
-| --------- | -------------------------------------------- | -------------- |
-| 1         | Commands, MCP expansion, Cost tracking       | 2 weeks        |
-| 2         | Remote sessions, Plugin architecture, Memory | 2 weeks        |
-| 3         | Query Engine, Policy limits                  | 2 weeks        |
-| 4         | Swarm/Coordinator, Analytics                 | 3 weeks        |
-| 5         | Worktree/tmux, Migration system              | 1 week         |
-| **Total** | **All components**                           | **10 weeks**   |
-
----
-
-## Architecture Compatibility Notes
-
-1. **Effect Compatibility:** Claude Code uses Effect.gen() pattern - direct compatibility ✓
-2. **Instance.bind:** Required for native callbacks (fs.watch, @parcel/watcher)
-3. **InstanceState:** Use for per-project state (Claude Code uses different pattern)
-4. **ServiceMap:** Vikasit's service pattern - wrap Claude Code services
-5. **Zod schemas:** Both use Zod - direct compatibility ✓
-6. **Bun shell:** Vikasit uses Bun - adapt Claude Code's bash calls
-
----
-
-## Files to Copy (Selective)
-
-From Claude Code SRC, copy these non-UI files:
-
-```
-commands/           # All command implementations (100+ files)
-services/mcp/*      # MCP services (22 files)
-remote/*            # Remote session (4 files)
-utils/mcp*          # MCP utilities (10 files)
-utils/auth.ts       # Auth utilities
-utils/worktree.ts   # Worktree utilities
-utils/proxy.ts      # Proxy utilities
-skills/*            # Skill system (5 files)
-coordinator/*       # Coordinator mode (if needed)
-query/*             # Query engine (6 files)
-```
-
-**Do NOT copy:**
-
-- components/\* (React UI - 146 dirs)
-- hooks/\* (React hooks - 87 dirs)
-- ink/\* (Terminal rendering - 50 dirs)
-- screens/\* (UI screens)
-
----
-
-## Next Steps
-
-1. Create integration branches for each component
-2. Start with Commands + MCP (highest value)
-3. Test each component independently
-4. Merge incrementally
-5. Run Vikasit tests after each integration