prjct-cli 0.11.4 → 0.12.0

package/core/agentic/command-executor/types.ts

@@ -0,0 +1,79 @@
+/**
+ * Command Executor Types
+ */
+
+import type loopDetector from '../loop-detector'
+
+export interface ExecutionResult {
+  success: boolean
+  error?: string
+  escalation?: ReturnType<typeof loopDetector.getEscalationInfo>
+  isLoopDetected?: boolean
+  suggestion?: string
+  validation?: unknown
+  isValidationError?: boolean
+  template?: unknown
+  context?: unknown
+  state?: unknown
+  prompt?: string
+  agenticDelegation?: boolean
+  agentsPath?: string
+  agentRoutingPath?: string
+  reasoning?: unknown
+  thinkBlock?: unknown
+  groundTruth?: unknown
+  compressionMetrics?: unknown
+  learnedPatterns?: unknown
+  relevantMemories?: unknown
+  formatResponse?: (data: unknown) => string
+  formatThinkBlock?: (verbose: boolean) => string
+  parallel?: {
+    execute: (toolCalls: unknown[]) => Promise<unknown>
+    readAll: (paths: string[]) => Promise<Map<string, string | null>>
+    canParallelize: (tools: string[]) => boolean
+    getMetrics: () => unknown
+  }
+  memory?: {
+    create: (memory: unknown) => Promise<string>
+    autoRemember: (type: string, value: string, ctx?: string) => Promise<void>
+    search: (query: string) => Promise<unknown[]>
+    findByTags: (tags: string[]) => Promise<unknown[]>
+    getStats: () => Promise<unknown>
+  }
+  plan?: {
+    active: unknown
+    isPlanning: boolean
+    isDestructive: boolean
+    requiresApproval: boolean
+    recordInfo: (info: unknown) => void
+    setAnalysis: (analysis: unknown) => void
+    propose: (plan: unknown) => unknown
+    approve: (feedback?: string | null) => unknown
+    reject: (reason?: string | null) => unknown
+    getApprovalPrompt: () => unknown
+    startExecution: () => unknown
+    getNextStep: () => unknown
+    completeStep: (result?: unknown) => unknown
+    failStep: (error: string) => unknown
+    abort: (reason?: string) => unknown
+    getStatus: () => string
+    getAllowedTools: () => string[]
+  }
+  attemptNumber?: number
+  isLooping?: boolean
+}
+
+export interface SimpleExecutionResult {
+  success: boolean
+  result?: unknown
+  error?: string
+}
+
+export type ExecutionToolsFn = (
+  tools: {
+    read: (path: string) => Promise<unknown>
+    write: (path: string, content: string) => Promise<unknown>
+    bash: (cmd: string) => Promise<unknown>
+  },
+  context: unknown
+) => Promise<unknown>

package/core/agentic/command-executor.ts

@@ -0,0 +1,8 @@
+/**
+ * Command Executor
+ * Re-exports from command-executor/index.ts for backwards compatibility.
+ */
+
+import commandExecutor from './command-executor/index'
+export * from './command-executor/index'
+export default commandExecutor

package/core/agentic/{context-builder.js → context-builder.ts}

@@ -1,21 +1,54 @@
 /**
  * Context Builder
- * Builds project context for Claude to make decisions
- * NO if/else logic - just data collection
+ * Builds project context for Claude with smart caching.
  *
- * OPTIMIZATION (P0.1): Smart Context Caching
- * - Parallel file reads with Promise.all()
- * - Session-based caching to avoid redundant reads
- * - Selective loading based on command needs
- *
- * Source: Windsurf, Cursor patterns
+ * @module agentic/context-builder
+ * @version 0.1
  */
 
-const fs = require('fs').promises
-const pathManager = require('../infrastructure/path-manager')
-const configManager = require('../infrastructure/config-manager')
+import fs from 'fs/promises'
+import pathManager from '../infrastructure/path-manager'
+import configManager from '../infrastructure/config-manager'
+
+interface Paths {
+  now: string
+  next: string
+  context: string
+  shipped: string
+  metrics: string
+  ideas: string
+  roadmap: string
+  specs: string
+  memory: string
+  patterns: string
+  analysis: string
+  codePatterns: string
+}
 
+interface Context {
+  projectId: string | null
+  projectPath: string
+  globalPath: string
+  paths: Paths
+  params: Record<string, unknown>
+  timestamp: string
+  date: string
+}
+
+interface State {
+  [key: string]: string | null
+}
+
+/**
+ * Builds and caches project context for Claude decisions.
+ * Features parallel reads, selective loading, and anti-hallucination mtime checks.
+ */
 class ContextBuilder {
+  private _cache: Map<string, string | null>
+  private _cacheTimeout: number
+  private _lastCacheTime: number | null
+  private _mtimes: Map<string, number>
+
   constructor() {
     // Session cache - cleared between commands or after timeout
     this._cache = new Map()
@@ -28,11 +61,9 @@ class ContextBuilder {
 
   /**
    * Clear cache if stale or force clear
-   * @param {boolean} force - Force clear regardless of timeout
    */
-  _clearCacheIfStale(force = false) {
-    if (force || !this._lastCacheTime ||
-        Date.now() - this._lastCacheTime > this._cacheTimeout) {
+  private _clearCacheIfStale(force: boolean = false): void {
+    if (force || !this._lastCacheTime || Date.now() - this._lastCacheTime > this._cacheTimeout) {
       this._cache.clear()
       this._lastCacheTime = Date.now()
     }
@@ -40,13 +71,10 @@ class ContextBuilder {
 
   /**
    * Build full project context for Claude
-   * @param {string} projectPath - Local project path
-   * @param {Object} commandParams - Command-specific parameters
-   * @returns {Promise<Object>} Context object
    */
-  async build(projectPath, commandParams = {}) {
+  async build(projectPath: string, commandParams: Record<string, unknown> = {}): Promise<Context> {
     const projectId = await configManager.getProjectId(projectPath)
-    const globalPath = pathManager.getGlobalProjectPath(projectId)
+    const globalPath = pathManager.getGlobalProjectPath(projectId!)
 
     return {
       // Project identification
@@ -56,18 +84,18 @@ class ContextBuilder {
 
       // File paths
       paths: {
-        now: pathManager.getFilePath(projectId, 'core', 'now.md'),
-        next: pathManager.getFilePath(projectId, 'core', 'next.md'),
-        context: pathManager.getFilePath(projectId, 'core', 'context.md'),
-        shipped: pathManager.getFilePath(projectId, 'progress', 'shipped.md'),
-        metrics: pathManager.getFilePath(projectId, 'progress', 'metrics.md'),
-        ideas: pathManager.getFilePath(projectId, 'planning', 'ideas.md'),
-        roadmap: pathManager.getFilePath(projectId, 'planning', 'roadmap.md'),
-        specs: pathManager.getFilePath(projectId, 'planning', 'specs'),
-        memory: pathManager.getFilePath(projectId, 'memory', 'context.jsonl'),
-        patterns: pathManager.getFilePath(projectId, 'memory', 'patterns.json'),
-        analysis: pathManager.getFilePath(projectId, 'analysis', 'repo-summary.md'),
-        codePatterns: pathManager.getFilePath(projectId, 'analysis', 'patterns.md'),
+        now: pathManager.getFilePath(projectId!, 'core', 'now.md'),
+        next: pathManager.getFilePath(projectId!, 'core', 'next.md'),
+        context: pathManager.getFilePath(projectId!, 'core', 'context.md'),
+        shipped: pathManager.getFilePath(projectId!, 'progress', 'shipped.md'),
+        metrics: pathManager.getFilePath(projectId!, 'progress', 'metrics.md'),
+        ideas: pathManager.getFilePath(projectId!, 'planning', 'ideas.md'),
+        roadmap: pathManager.getFilePath(projectId!, 'planning', 'roadmap.md'),
+        specs: pathManager.getFilePath(projectId!, 'planning', 'specs'),
+        memory: pathManager.getFilePath(projectId!, 'memory', 'context.jsonl'),
+        patterns: pathManager.getFilePath(projectId!, 'memory', 'patterns.json'),
+        analysis: pathManager.getFilePath(projectId!, 'analysis', 'repo-summary.md'),
+        codePatterns: pathManager.getFilePath(projectId!, 'analysis', 'patterns.md'),
       },
 
       // Command parameters
@@ -83,21 +111,15 @@ class ContextBuilder {
   /**
    * Load current project state - PARALLEL VERSION
    * Uses Promise.all() for 40-60% faster file I/O
-   *
-   * @param {Object} context - Context from build()
-   * @param {string[]} onlyKeys - Optional: only load specific keys (selective loading)
-   * @returns {Promise<Object>} Current state
    */
-  async loadState(context, onlyKeys = null) {
+  async loadState(context: Context, onlyKeys: string[] | null = null): Promise<State> {
     this._clearCacheIfStale()
 
-    const state = {}
+    const state: State = {}
     const entries = Object.entries(context.paths)
 
     // Filter to only requested keys if specified
-    const filteredEntries = onlyKeys
-      ? entries.filter(([key]) => onlyKeys.includes(key))
-      : entries
+    const filteredEntries = onlyKeys ? entries.filter(([key]) => onlyKeys.includes(key)) : entries
 
     // ANTI-HALLUCINATION: Verify mtime before trusting cache
     // Files can change between commands - stale cache causes hallucinations
@@ -120,10 +142,10 @@ class ContextBuilder {
     }
 
     // Separate cached vs uncached files
-    const uncachedEntries = []
+    const uncachedEntries: [string, string][] = []
     for (const [key, filePath] of filteredEntries) {
       if (this._cache.has(filePath)) {
-        state[key] = this._cache.get(filePath)
+        state[key] = this._cache.get(filePath)!
       } else {
         uncachedEntries.push([key, filePath])
       }
@@ -133,10 +155,7 @@ class ContextBuilder {
     if (uncachedEntries.length > 0) {
       const readPromises = uncachedEntries.map(async ([key, filePath]) => {
         try {
-          const [content, stat] = await Promise.all([
-            fs.readFile(filePath, 'utf-8'),
-            fs.stat(filePath)
-          ])
+          const [content, stat] = await Promise.all([fs.readFile(filePath, 'utf-8'), fs.stat(filePath)])
           return { key, filePath, content, mtime: stat.mtimeMs }
         } catch {
           return { key, filePath, content: null, mtime: null }
@@ -161,46 +180,42 @@ class ContextBuilder {
   /**
    * Load state for specific command - optimized selective loading
    * Each command only loads what it needs
-   *
-   * @param {Object} context - Context from build()
-   * @param {string} commandName - Command name for selective loading
-   * @returns {Promise<Object>} Current state (filtered)
    */
-  async loadStateForCommand(context, commandName) {
+  async loadStateForCommand(context: Context, commandName: string): Promise<State> {
     // Command-specific file requirements
     // Minimizes context window usage
     // CRITICAL: Include 'codePatterns' for ALL code-modifying commands
-    const commandFileMap = {
+    const commandFileMap: Record<string, string[]> = {
       // Core workflow
-      'now': ['now', 'next', 'analysis', 'codePatterns'],
-      'done': ['now', 'next', 'metrics', 'analysis'],
-      'next': ['next', 'analysis'],
+      now: ['now', 'next', 'analysis', 'codePatterns'],
+      done: ['now', 'next', 'metrics', 'analysis'],
+      next: ['next', 'analysis'],
 
       // Progress
-      'ship': ['now', 'shipped', 'metrics', 'analysis'],
-      'recap': ['shipped', 'metrics', 'now', 'analysis'],
-      'progress': ['shipped', 'metrics', 'analysis'],
+      ship: ['now', 'shipped', 'metrics', 'analysis'],
+      recap: ['shipped', 'metrics', 'now', 'analysis'],
+      progress: ['shipped', 'metrics', 'analysis'],
 
       // Planning
-      'idea': ['ideas', 'next', 'analysis'],
-      'feature': ['roadmap', 'next', 'ideas', 'analysis', 'codePatterns'],
-      'roadmap': ['roadmap', 'analysis'],
-      'spec': ['roadmap', 'next', 'specs', 'analysis', 'codePatterns'],
+      idea: ['ideas', 'next', 'analysis'],
+      feature: ['roadmap', 'next', 'ideas', 'analysis', 'codePatterns'],
+      roadmap: ['roadmap', 'analysis'],
+      spec: ['roadmap', 'next', 'specs', 'analysis', 'codePatterns'],
 
       // Analysis
-      'analyze': ['analysis', 'context', 'codePatterns'],
-      'sync': ['analysis', 'context', 'now', 'codePatterns'],
+      analyze: ['analysis', 'context', 'codePatterns'],
+      sync: ['analysis', 'context', 'now', 'codePatterns'],
 
       // Code modification commands - ALWAYS need codePatterns
-      'work': ['now', 'next', 'analysis', 'context', 'codePatterns'],
-      'build': ['now', 'next', 'analysis', 'context', 'codePatterns'],
-      'design': ['analysis', 'context', 'codePatterns'],
-      'cleanup': ['analysis', 'context', 'codePatterns'],
-      'fix': ['analysis', 'context', 'codePatterns'],
-      'test': ['analysis', 'context', 'codePatterns'],
+      work: ['now', 'next', 'analysis', 'context', 'codePatterns'],
+      build: ['now', 'next', 'analysis', 'context', 'codePatterns'],
+      design: ['analysis', 'context', 'codePatterns'],
+      cleanup: ['analysis', 'context', 'codePatterns'],
+      fix: ['analysis', 'context', 'codePatterns'],
+      test: ['analysis', 'context', 'codePatterns'],
 
       // All files (fallback) - include codePatterns for any code work
-      'default': ['analysis', 'codePatterns']
+      default: ['analysis', 'codePatterns'],
     }
 
     const requiredFiles = commandFileMap[commandName] || commandFileMap.default
@@ -210,20 +225,17 @@ class ContextBuilder {
   /**
    * Batch read multiple files in parallel
    * Utility for custom file sets
-   *
-   * @param {string[]} filePaths - Array of file paths
-   * @returns {Promise<Map<string, string|null>>} Map of path -> content
    */
-  async batchRead(filePaths) {
+  async batchRead(filePaths: string[]): Promise<Map<string, string | null>> {
     this._clearCacheIfStale()
 
-    const results = new Map()
-    const uncachedPaths = []
+    const results = new Map<string, string | null>()
+    const uncachedPaths: string[] = []
 
     // Check cache first
     for (const filePath of filePaths) {
       if (this._cache.has(filePath)) {
-        results.set(filePath, this._cache.get(filePath))
+        results.set(filePath, this._cache.get(filePath)!)
       } else {
         uncachedPaths.push(filePath)
       }
@@ -253,25 +265,22 @@ class ContextBuilder {
 
   /**
    * Invalidate cache for specific file (after write)
-   * @param {string} filePath - File that was written
    */
-  invalidateCache(filePath) {
+  invalidateCache(filePath: string): void {
     this._cache.delete(filePath)
   }
 
   /**
    * Force clear entire cache
    */
-  clearCache() {
+  clearCache(): void {
     this._clearCacheIfStale(true)
   }
 
   /**
    * Check file existence
-   * @param {string} filePath - File path
-   * @returns {Promise<boolean>}
    */
-  async fileExists(filePath) {
+  async fileExists(filePath: string): Promise<boolean> {
     try {
       await fs.access(filePath)
       return true
@@ -282,15 +291,16 @@ class ContextBuilder {
 
   /**
    * Get cache stats (for debugging/metrics)
-   * @returns {Object} Cache statistics
    */
-  getCacheStats() {
+  getCacheStats(): { size: number; lastRefresh: number | null; timeout: number } {
     return {
       size: this._cache.size,
       lastRefresh: this._lastCacheTime,
-      timeout: this._cacheTimeout
+      timeout: this._cacheTimeout,
     }
   }
 }
 
-module.exports = new ContextBuilder()
+const contextBuilder = new ContextBuilder()
+export default contextBuilder
+export { ContextBuilder }