prjct-cli 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.16.0] - 2025-12-15
+
+### Dead Code Cleanup
+
+Aggressive removal of ~6,600 lines of unused/legacy code for a cleaner, leaner codebase.
+
+- **Domain Modules Removed (6 files)**
+  - `agent-matcher.ts` - Replaced by template-based routing
+  - `product-standards.ts` - Unused domain standards
+  - `smart-cache.ts`, `task-analyzer.ts`, `agent-validator.ts`, `architect-session.ts`
+
+- **Agentic Modules Removed (6 files)**
+  - `semantic-compression.ts` - Exported but never called
+  - `response-templates.ts`, `think-blocks.ts`, `parallel-tools.ts`
+  - `context-filter.ts`, `validation-rules.ts`
+
+- **Legacy Migration Code Removed**
+  - `legacy-installer-detector/` directory (curl-to-npm migration)
+  - `migrator/` directory (version migrations)
+  - `uuid-migration.ts` (750 lines)
+  - `bin/migrate-to-json.js`, `bin/generate-views.js`
+  - `/p:migrate`, `/p:migrate-all` command templates
+
+- **Code Cleanup**
+  - Simplified `services.ts` facade (removed 6 unused exports)
+  - Simplified `setup.ts` (removed migration steps)
+  - Removed deprecated methods from `base.ts`
+  - Cleaned `command-executor.ts` (removed dead module usage)
+
+- **Impact**
+  - Lines removed: ~6,600
+  - Files deleted: ~25
+  - Build: Passing
+  - Tests: 131 pass
+
+## [0.15.1] - 2025-12-15
+
+### MCP Setup Documentation
+
+Enhanced setup template with MCP server installation documentation.
+
+- **Setup Template Updates**
+  - Added MCP server installation step documentation
+  - Context7 library documentation lookup integration
+  - Updated success output examples
+
+- **MCP Config Enhancements**
+  - Added description field for Context7 server
+  - Added usage guidelines with when/tools/examples
+  - Better documentation for resolve-library-id and get-library-docs
+
 ## [0.15.0] - 2025-12-15
 
 ### Template Optimization - Aggressive Consolidation

package/bin/dev.js

@@ -153,7 +153,6 @@ async function main() {
     cwd: WEB_PATH,
     env: { ...process.env, PORT: PORT.toString() },
     stdio: ['ignore', 'pipe', 'pipe'],
-    shell: true
   })
 
   webProc.stdout.on('data', (data) => {

package/bin/serve.js

@@ -138,7 +138,6 @@ if (sharedCheck.needed || webCheck.needed) {
     const sharedInstall = spawnSync('npm', ['install'], {
       cwd: sharedDir,
       stdio: 'inherit',
-      shell: true,
     })
 
     if (sharedInstall.status !== 0) {
@@ -151,7 +150,6 @@ if (sharedCheck.needed || webCheck.needed) {
     const sharedBuild = spawnSync('npm', ['run', 'build'], {
       cwd: sharedDir,
       stdio: 'inherit',
-      shell: true,
     })
 
     if (sharedBuild.status !== 0) {
@@ -167,7 +165,6 @@ if (sharedCheck.needed || webCheck.needed) {
     const webInstall = spawnSync('npm', ['install'], {
       cwd: webDir,
       stdio: 'inherit',
-      shell: true,
     })
 
     if (webInstall.status !== 0) {
@@ -189,6 +186,7 @@ if (sharedCheck.needed || webCheck.needed) {
 function isPrjctWebProcess(pid) {
   try {
     if (process.platform === 'win32') {
+      // Windows: wmic needs shell for proper command parsing
       const result = spawnSync('wmic', ['process', 'where', `processid=${pid}`, 'get', 'commandline'], {
         shell: true,
         encoding: 'utf8',
@@ -197,10 +195,9 @@ function isPrjctWebProcess(pid) {
     } else {
       // macOS / Linux - check process command line
       const result = spawnSync('ps', ['-p', pid, '-o', 'command='], {
-        shell: true,
         encoding: 'utf8',
       })
-      const cmd = result.stdout.trim()
+      const cmd = result.stdout?.trim() || ''
       return cmd.includes('server.ts') || cmd.includes('prjct') || cmd.includes('next')
     }
   } catch {
@@ -214,9 +211,10 @@ function isPrjctWebProcess(pid) {
 function getPortPids(portToCheck) {
   try {
     if (process.platform === 'win32') {
-      const result = spawnSync('netstat', ['-ano'], { shell: true, encoding: 'utf8' })
+      // Windows: netstat works without shell
+      const result = spawnSync('netstat', ['-ano'], { encoding: 'utf8' })
       const pids = []
-      const lines = result.stdout.split('\n')
+      const lines = (result.stdout || '').split('\n')
       for (const line of lines) {
         if (line.includes(`:${portToCheck}`) && line.includes('LISTENING')) {
           const parts = line.trim().split(/\s+/)
@@ -226,11 +224,11 @@ function getPortPids(portToCheck) {
       }
       return pids
     } else {
+      // macOS / Linux
       const result = spawnSync('lsof', ['-ti', `:${portToCheck}`], {
-        shell: true,
         encoding: 'utf8',
       })
-      return result.stdout.trim().split('\n').filter(Boolean)
+      return (result.stdout || '').trim().split('\n').filter(Boolean)
     }
   } catch {
     return []
@@ -244,9 +242,11 @@ function killPids(pids) {
   for (const pid of pids) {
     try {
       if (process.platform === 'win32') {
-        spawnSync('taskkill', ['/F', '/PID', pid], { shell: true })
+        // Windows: taskkill works without shell
+        spawnSync('taskkill', ['/F', '/PID', pid])
       } else {
-        spawnSync('kill', ['-9', pid], { shell: true })
+        // Unix: kill works without shell
+        spawnSync('kill', ['-9', pid])
       }
     } catch {
       // Ignore individual kill errors
@@ -258,13 +258,14 @@ function killPids(pids) {
  * Open URL in browser
  */
 function openBrowser(url) {
-  const openCmd =
-    process.platform === 'darwin'
-      ? 'open'
-      : process.platform === 'win32'
-        ? 'start'
-        : 'xdg-open'
-  spawn(openCmd, [url], { shell: true, detached: true }).unref()
+  if (process.platform === 'darwin') {
+    spawn('open', [url], { detached: true, stdio: 'ignore' }).unref()
+  } else if (process.platform === 'win32') {
+    // Windows 'start' is a shell builtin, requires shell: true
+    spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref()
+  } else {
+    spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref()
+  }
 }
 
 // Check if port is in use and handle accordingly
@@ -324,7 +325,6 @@ if (!fs.existsSync(nextDir)) {
   const buildResult = spawnSync('npm', ['run', 'build'], {
     cwd: webDir,
     stdio: 'inherit',
-    shell: true,
   })
   if (buildResult.status !== 0) {
     console.error('❌ Build failed')
@@ -337,7 +337,6 @@ if (!fs.existsSync(nextDir)) {
 const web = spawn('npm', ['run', 'start'], {
   cwd: webDir,
   stdio: 'inherit',
-  shell: true,
   env: { ...process.env, PORT: port, NODE_ENV: 'production' },
 })
 

package/core/agentic/agent-router.ts

@@ -2,8 +2,14 @@
  * Agent Router
  * Orchestrates agent loading and context building for Claude delegation.
  *
+ * Loads agents from two locations:
+ * 1. {projectPath}/.claude/agents/ - Claude Code sub-agents (PRIMARY, per-project)
+ * 2. ~/.prjct-cli/projects/{id}/agents/ - Legacy agents (fallback)
+ *
+ * Claude Code sub-agents are prioritized as they're more specific to the project.
+ *
  * @module agentic/agent-router
- * @version 2.0.0
+ * @version 3.0.0
  */
 
 import fs from 'fs/promises'
@@ -14,6 +20,7 @@ import pathManager from '../infrastructure/path-manager'
 interface Agent {
   name: string
   content: string
+  source: 'claude-code' | 'legacy'
 }
 
 interface AssignmentContext {
@@ -30,29 +37,42 @@ interface AssignmentContext {
  */
 class AgentRouter {
   projectId: string | null = null
-  agentsPath: string | null = null
+  projectPath: string | null = null
+  legacyAgentsPath: string | null = null
+
+  /**
+   * Get path to Claude Code sub-agents directory
+   */
+  getClaudeCodeAgentsPath(): string | null {
+    if (!this.projectPath) return null
+    return path.join(this.projectPath, '.claude', 'agents')
+  }
 
   /**
    * Initialize router with project context
    */
   async initialize(projectPath: string): Promise<void> {
     this.projectId = await configManager.getProjectId(projectPath)
-    this.agentsPath = pathManager.getPath(this.projectId!, 'agents')
+    this.projectPath = projectPath
+    this.legacyAgentsPath = pathManager.getPath(this.projectId!, 'agents')
   }
 
   /**
-   * Load all available agents from project
+   * Load agents from a specific directory
    */
-  async loadAvailableAgents(): Promise<Agent[]> {
+  private async loadAgentsFromPath(
+    agentsPath: string,
+    source: 'claude-code' | 'legacy'
+  ): Promise<Agent[]> {
     try {
-      const files = await fs.readdir(this.agentsPath!)
+      const files = await fs.readdir(agentsPath)
       const agents: Agent[] = []
 
       for (const file of files) {
         if (file.endsWith('.md')) {
           const name = file.replace('.md', '')
-          const content = await fs.readFile(path.join(this.agentsPath!, file), 'utf-8')
-          agents.push({ name, content })
+          const content = await fs.readFile(path.join(agentsPath, file), 'utf-8')
+          agents.push({ name, content, source })
         }
       }
 
@@ -62,6 +82,33 @@ class AgentRouter {
     }
   }
 
+  /**
+   * Load all available agents from both Claude Code and legacy locations
+   * Claude Code sub-agents take priority over legacy agents with same name
+   */
+  async loadAvailableAgents(): Promise<Agent[]> {
+    const agentMap = new Map<string, Agent>()
+
+    // Load legacy agents first (lower priority)
+    if (this.legacyAgentsPath) {
+      const legacyAgents = await this.loadAgentsFromPath(this.legacyAgentsPath, 'legacy')
+      for (const agent of legacyAgents) {
+        agentMap.set(agent.name, agent)
+      }
+    }
+
+    // Load Claude Code sub-agents (higher priority - overwrites legacy)
+    const claudeCodePath = this.getClaudeCodeAgentsPath()
+    if (claudeCodePath) {
+      const claudeCodeAgents = await this.loadAgentsFromPath(claudeCodePath, 'claude-code')
+      for (const agent of claudeCodeAgents) {
+        agentMap.set(agent.name, agent)
+      }
+    }
+
+    return Array.from(agentMap.values())
+  }
+
   /**
    * Get list of available agent names
    */
@@ -72,15 +119,33 @@ class AgentRouter {
 
   /**
    * Load a specific agent by name
+   * Checks Claude Code sub-agents first, then falls back to legacy
    */
   async loadAgent(name: string): Promise<Agent | null> {
-    try {
-      const filePath = path.join(this.agentsPath!, `${name}.md`)
-      const content = await fs.readFile(filePath, 'utf-8')
-      return { name, content }
-    } catch {
-      return null
+    // Try Claude Code sub-agents first (higher priority)
+    const claudeCodePath = this.getClaudeCodeAgentsPath()
+    if (claudeCodePath) {
+      try {
+        const filePath = path.join(claudeCodePath, `${name}.md`)
+        const content = await fs.readFile(filePath, 'utf-8')
+        return { name, content, source: 'claude-code' }
+      } catch {
+        // Not found in Claude Code path, try legacy
+      }
+    }
+
+    // Fall back to legacy agents
+    if (this.legacyAgentsPath) {
+      try {
+        const filePath = path.join(this.legacyAgentsPath, `${name}.md`)
+        const content = await fs.readFile(filePath, 'utf-8')
+        return { name, content, source: 'legacy' }
+      } catch {
+        // Not found
+      }
     }
+
+    return null
   }
 
   /**

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

@@ -9,15 +9,10 @@ import templateLoader from '../template-loader'
 import contextBuilder from '../context-builder'
 import promptBuilder from '../prompt-builder'
 import toolRegistry from '../tool-registry'
-import { validate, formatError } from '../validation-rules'
 import loopDetector from '../loop-detector'
 import chainOfThought from '../chain-of-thought'
-import semanticCompression from '../semantic-compression'
-import responseTemplates from '../response-templates'
 import memorySystem from '../memory-system'
 import groundTruth from '../ground-truth'
-import thinkBlocks from '../think-blocks'
-import parallelTools from '../parallel-tools'
 import planMode from '../plan-mode'
 import { signalStart, signalEnd } from './status-signal'
 import type { ExecutionResult, SimpleExecutionResult, ExecutionToolsFn } from './types'
@@ -71,18 +66,6 @@ export class CommandExecutor {
       // 2. Build METADATA context only (lazy loading - no file reads yet)
       const metadataContext = await contextBuilder.build(projectPath, params)
 
-      // 2.5. VALIDATE: Pre-flight checks with specific errors
-      const validation = await validate(commandName, metadataContext as unknown as Parameters<typeof validate>[1])
-      if (!validation.valid) {
-        this.signalEnd()
-        return {
-          success: false,
-          error: formatError(validation),
-          validation,
-          isValidationError: true,
-        }
-      }
-
       // 2.55. P3.4 PLAN MODE: Check if command requires planning
       const requiresPlanning = planMode.requiresPlanning(commandName)
       const isDestructive = planMode.isDestructive(commandName)
@@ -112,29 +95,6 @@ export class CommandExecutor {
         }
       }
 
-      // 2.7. THINK BLOCKS (P3.1): Dynamic reasoning based on triggers
-      let thinkBlock = null
-      const preThinkState =
-        groundTruthResult?.actual || (await contextBuilder.loadStateForCommand(metadataContext, commandName))
-      const thinkTrigger = thinkBlocks.detectTrigger(
-        commandName,
-        metadataContext as unknown as Parameters<typeof thinkBlocks.detectTrigger>[1],
-        preThinkState as Parameters<typeof thinkBlocks.detectTrigger>[2]
-      )
-      if (thinkTrigger) {
-        thinkBlock = await thinkBlocks.generate(
-          thinkTrigger,
-          commandName,
-          metadataContext as unknown as Parameters<typeof thinkBlocks.generate>[2],
-          preThinkState as Parameters<typeof thinkBlocks.generate>[3]
-        )
-
-        // Log think block if in debug mode
-        if (process.env.PRJCT_DEBUG === 'true') {
-          console.log(thinkBlocks.format(thinkBlock, true))
-        }
-      }
-
       // 2.8. CHAIN OF THOUGHT: Reasoning for critical commands
       let reasoning = null
       if (chainOfThought.requiresReasoning(commandName)) {
@@ -164,29 +124,7 @@ export class CommandExecutor {
       }
 
       // 6. Load state with filtered context
-      const rawState = await contextBuilder.loadState(metadataContext)
-
-      // 6.5. SEMANTIC COMPRESSION: Compress state for reduced token usage
-      const compressedState: Record<string, unknown> = {}
-      for (const [key, content] of Object.entries(rawState)) {
-        if (content) {
-          const compressed = semanticCompression.compress(content, key)
-          compressedState[key] = {
-            raw: content,
-            summary: compressed.summary,
-            compressed,
-          }
-        } else {
-          compressedState[key] = { raw: null, summary: 'Empty', compressed: null }
-        }
-      }
-
-      // Use compressed summaries for prompt, keep raw for tool execution
-      const state = {
-        ...rawState,
-        _compressed: compressedState,
-        _compressionMetrics: semanticCompression.getMetrics(),
-      }
+      const state = await contextBuilder.loadState(metadataContext)
 
       // 7. MEMORY: Load learned patterns AND relevant memories for this command
       let learnedPatterns = null
@@ -224,7 +162,7 @@ export class CommandExecutor {
         state,
         null,
         learnedPatterns,
-        thinkBlock,
+        null,
         relevantMemories,
         planInfo
       )
@@ -248,19 +186,9 @@ export class CommandExecutor {
         agentsPath: context.agentsPath as string,
         agentRoutingPath: context.agentRoutingPath as string,
         reasoning,
-        thinkBlock,
         groundTruth: groundTruthResult,
-        compressionMetrics: state._compressionMetrics,
         learnedPatterns,
         relevantMemories,
-        formatResponse: (data: unknown) => responseTemplates.format(commandName, data as Parameters<typeof responseTemplates.format>[1]),
-        formatThinkBlock: (verbose: boolean) => thinkBlocks.format(thinkBlock, verbose),
-        parallel: {
-          execute: (toolCalls: unknown[]) => parallelTools.execute(toolCalls as Parameters<typeof parallelTools.execute>[0]),
-          readAll: (paths: string[]) => parallelTools.readAll(paths),
-          canParallelize: (tools: string[]) => parallelTools.canParallelize(tools),
-          getMetrics: () => parallelTools.getMetrics(),
-        },
         memory: {
           create: (memory: unknown) =>
             memorySystem.createMemory(metadataContext.projectId!, memory as Parameters<typeof memorySystem.createMemory>[1]),

package/core/agentic/services.ts

@@ -29,14 +29,8 @@ import toolRegistry from './tool-registry'
 import loopDetector from './loop-detector'
 import memorySystem from './memory-system'
 import groundTruth from './ground-truth'
-import semanticCompression from './semantic-compression'
-import responseTemplates from './response-templates'
 import chainOfThought from './chain-of-thought'
-import thinkBlocks from './think-blocks'
-import parallelTools from './parallel-tools'
 import planMode from './plan-mode'
-import contextFilter from './context-filter'
-import validationRules from './validation-rules'
 import agentRouter from './agent-router'
 import smartContext from './smart-context'
 import { mdManagers } from '../data'
@@ -90,54 +84,18 @@ export interface AgenticServices {
    */
   truth: typeof groundTruth
 
-  /**
-   * Semantic compression - compresses context to fit token limits
-   * @see semanticCompression
-   */
-  compression: typeof semanticCompression
-
-  /**
-   * Response templates - generates formatted responses
-   * @see responseTemplates
-   */
-  responses: typeof responseTemplates
-
   /**
    * Chain of thought - adds reasoning to responses
    * @see chainOfThought
    */
   reasoning: typeof chainOfThought
 
-  /**
-   * Think blocks - generates think block content
-   * @see thinkBlocks
-   */
-  thinking: typeof thinkBlocks
-
-  /**
-   * Parallel tools - executes tools in parallel
-   * @see parallelTools
-   */
-  parallel: typeof parallelTools
-
   /**
    * Plan mode - handles planning workflow
    * @see planMode
    */
   planning: typeof planMode
 
-  /**
-   * Context filter - filters context for relevance
-   * @see contextFilter
-   */
-  filter: typeof contextFilter
-
-  /**
-   * Validation rules - validates command inputs
-   * @see validationRules
-   */
-  validation: typeof validationRules
-
   /**
    * Agent router - routes tasks to appropriate agents
    * @see agentRouter
@@ -187,14 +145,8 @@ export const services: AgenticServices = {
   loops: loopDetector,
   memory: memorySystem,
   truth: groundTruth,
-  compression: semanticCompression,
-  responses: responseTemplates,
   reasoning: chainOfThought,
-  thinking: thinkBlocks,
-  parallel: parallelTools,
   planning: planMode,
-  filter: contextFilter,
-  validation: validationRules,
   router: agentRouter,
   smartContext: smartContext,
   data: mdManagers,

package/core/agentic/template-loader.ts

@@ -8,6 +8,7 @@
 
 import fs from 'fs/promises'
 import path from 'path'
+import { TemplateError } from '../errors'
 
 interface Frontmatter {
   name?: string
@@ -24,14 +25,42 @@ interface ParsedTemplate {
 /**
  * Loads command templates from templates/commands/ with caching.
  * Parses YAML-like frontmatter for metadata extraction.
+ * Uses LRU cache with size limit to prevent memory leaks.
  */
 class TemplateLoader {
   templatesDir: string
   cache: Map<string, ParsedTemplate>
+  cacheOrder: string[] // Track access order for LRU eviction
+  maxCacheSize: number
 
   constructor() {
     this.templatesDir = path.join(__dirname, '..', '..', 'templates', 'commands')
     this.cache = new Map()
+    this.cacheOrder = []
+    this.maxCacheSize = 50 // More than enough for all commands
+  }
+
+  /**
+   * Update LRU order - move key to end (most recently used)
+   */
+  private updateLruOrder(key: string): void {
+    const index = this.cacheOrder.indexOf(key)
+    if (index > -1) {
+      this.cacheOrder.splice(index, 1)
+    }
+    this.cacheOrder.push(key)
+  }
+
+  /**
+   * Evict least recently used entry if cache exceeds max size
+   */
+  private evictLru(): void {
+    while (this.cache.size >= this.maxCacheSize && this.cacheOrder.length > 0) {
+      const oldest = this.cacheOrder.shift()
+      if (oldest) {
+        this.cache.delete(oldest)
+      }
+    }
   }
 
   /**
@@ -40,6 +69,7 @@ class TemplateLoader {
   async load(commandName: string): Promise<ParsedTemplate> {
     // Check cache first
     if (this.cache.has(commandName)) {
+      this.updateLruOrder(commandName)
       return this.cache.get(commandName)!
     }
 
@@ -49,12 +79,16 @@ class TemplateLoader {
       const rawContent = await fs.readFile(templatePath, 'utf-8')
       const parsed = this.parseFrontmatter(rawContent)
 
+      // Evict LRU if needed before adding
+      this.evictLru()
+
       // Cache result
       this.cache.set(commandName, parsed)
+      this.cacheOrder.push(commandName)
 
       return parsed
     } catch {
-      throw new Error(`Template not found: ${commandName}.md`)
+      throw TemplateError.notFound(commandName)
     }
   }