prjct-cli 0.15.1 → 0.18.0

package/core/commands/base.ts

@@ -2,8 +2,6 @@
  * Base class and helpers for PrjctCommands
  */
 
-import path from 'path'
-
 import commandExecutor from '../agentic/command-executor'
 import contextBuilder from '../agentic/context-builder'
 import toolRegistry from '../agentic/tool-registry'
@@ -12,7 +10,6 @@ import pathManager from '../infrastructure/path-manager'
 import configManager from '../infrastructure/config-manager'
 import authorDetector from '../infrastructure/author-detector'
 import agentDetector from '../infrastructure/agent-detector'
-import migrator from '../infrastructure/migrator'
 import UpdateChecker from '../infrastructure/update-checker'
 import dateHelper from '../utils/date-helper'
 import jsonlHelper from '../utils/jsonl-helper'
@@ -24,10 +21,23 @@ import type {
   AgentInfo,
   Author,
   AgentAssignmentResult,
-  ComplexityResult,
-  HealthResult,
   Context
 } from './types'
+import { ProjectError, AgentError } from '../errors'
+
+// Valid agent types - whitelist for security (prevents path traversal)
+const VALID_AGENT_TYPES = ['claude'] as const
+type ValidAgentType = typeof VALID_AGENT_TYPES[number]
+
+// Lazy-loaded to avoid circular dependencies
+let _planningCommands: import('./planning').PlanningCommands | null = null
+async function getPlanningCommands(): Promise<import('./planning').PlanningCommands> {
+  if (!_planningCommands) {
+    const { PlanningCommands } = await import('./planning')
+    _planningCommands = new PlanningCommands()
+  }
+  return _planningCommands
+}
 
 /**
  * Base class with shared state and utilities
@@ -62,10 +72,16 @@ export class PrjctCommandsBase {
     this.agentInfo = await agentDetector.detect()
 
     if (!this.agentInfo.isSupported) {
-      throw new Error('Unsupported agent. Please use Claude Code, Claude Desktop, or Terminal.')
+      throw AgentError.notSupported(this.agentInfo.type)
+    }
+
+    // Security: validate agent type against whitelist to prevent path traversal
+    const agentType = this.agentInfo.type as ValidAgentType
+    if (!VALID_AGENT_TYPES.includes(agentType)) {
+      throw AgentError.notSupported(this.agentInfo.type)
     }
 
-    const { default: Agent } = await import(`../infrastructure/agents/${this.agentInfo.type}-agent`)
+    const { default: Agent } = await import(`../infrastructure/agents/${agentType}-agent`)
     this.agent = new Agent()
 
     return this.agent
@@ -80,8 +96,8 @@ export class PrjctCommandsBase {
     }
 
     out.spin('initializing project...')
-    // Note: init() will be implemented in planning module
-    const initResult = await (this as unknown as { init: (idea: string | null, projectPath: string) => Promise<CommandResult> }).init(null, projectPath)
+    const planning = await getPlanningCommands()
+    const initResult = await planning.init(null, projectPath)
     if (!initResult.success) {
       return initResult
     }
@@ -107,13 +123,12 @@ export class PrjctCommandsBase {
    * Get global project path
    */
   async getGlobalProjectPath(projectPath: string): Promise<string> {
-    if (await migrator.needsMigration(projectPath)) {
-      throw new Error('Project needs migration. Run /p:migrate first.')
-    }
-
     const projectId = await configManager.getProjectId(projectPath)
-    await pathManager.ensureProjectStructure(projectId!)
-    return pathManager.getGlobalProjectPath(projectId!)
+    if (!projectId) {
+      throw ProjectError.notInitialized()
+    }
+    await pathManager.ensureProjectStructure(projectId)
+    return pathManager.getGlobalProjectPath(projectId)
   }
 
   /**
@@ -174,64 +189,6 @@ export class PrjctCommandsBase {
     }
   }
 
-  /**
-   * Assign agent for a task
-   */
-  async _assignAgentForTask(taskDescription: string, projectPath: string, _context: Context): Promise<AgentAssignmentResult> {
-    try {
-      const projectId = await configManager.getProjectId(projectPath)
-      const agentsPath = pathManager.getFilePath(projectId!, 'agents', '')
-      const agentFiles = await fileHelper.listFiles(agentsPath, { extension: '.md' })
-      const agents = agentFiles.map(f => f.replace('.md', ''))
-
-      return {
-        agent: { name: agents[0] || 'generalist', domain: 'auto' },
-        routing: {
-          confidence: 0.8,
-          reason: 'Claude assigns via templates/agent-assignment.md',
-          availableAgents: agents
-        },
-        _agenticNote: 'Use templates/agent-assignment.md for actual assignment'
-      }
-    } catch {
-      return {
-        agent: { name: 'generalist', domain: 'general' },
-        routing: { confidence: 0.5, reason: 'Fallback - no agents found' }
-      }
-    }
-  }
-
-  /**
-   * Detect task complexity
-   */
-  _detectComplexity(_task: string): ComplexityResult {
-    return { level: 'medium', hours: 4, type: 'feature' }
-  }
-
-  /**
-   * Calculate project health score
-   */
-  _calculateHealth(stats: { activeTask: boolean; featuresShipped: number }): HealthResult {
-    const hasActivity = stats.activeTask || stats.featuresShipped > 0
-    return {
-      score: hasActivity ? 70 : 50,
-      message: hasActivity ? '🟢 Active' : '🟡 Ready to start',
-    }
-  }
-
-  /**
-   * Render ASCII progress bar
-   */
-  _renderProgressBar(label: string, value: number, max: number): void {
-    const percentage = Math.min(100, Math.round((value / max) * 100))
-    const barLength = 30
-    const filled = Math.round((percentage / 100) * barLength)
-    const empty = barLength - filled
-
-    const bar = '█'.repeat(filled) + '░'.repeat(empty)
-    console.log(`   ${label}: [${bar}] ${percentage}%`)
-  }
-
   /**
    * Breakdown feature into tasks
    */
@@ -252,11 +209,73 @@ export class PrjctCommandsBase {
   }
 
   /**
-   * Auto-assign agent based on task (deprecated)
+   * Assign agent for a task using AgentRouter
+   * Returns agent info for Claude to delegate work
    */
-  _autoAssignAgent(_task: string): string {
-    console.warn('DEPRECATED: Use _assignAgentForTask() for proper agent routing')
-    return 'generalist'
+  async _assignAgentForTask(
+    task: string,
+    projectPath: string,
+    _context: Context
+  ): Promise<AgentAssignmentResult> {
+    try {
+      await this.agentRouter.initialize(projectPath)
+      const agents = await this.agentRouter.getAgentNames()
+
+      if (agents.length === 0) {
+        return {
+          agent: { name: 'generalist' },
+          routing: {
+            confidence: 1.0,
+            reason: 'No specialized agents available',
+            availableAgents: [],
+          },
+        }
+      }
+
+      // Simple keyword matching for agent assignment
+      // Claude will make the final decision via templates
+      const taskLower = task.toLowerCase()
+      let bestMatch = 'generalist'
+
+      for (const agentName of agents) {
+        const nameLower = agentName.toLowerCase()
+        if (taskLower.includes(nameLower) || nameLower.includes('general')) {
+          bestMatch = agentName
+          break
+        }
+        // Common domain keywords
+        if ((nameLower.includes('fe') || nameLower.includes('frontend')) &&
+            (taskLower.includes('ui') || taskLower.includes('component') || taskLower.includes('react'))) {
+          bestMatch = agentName
+          break
+        }
+        if ((nameLower.includes('be') || nameLower.includes('backend')) &&
+            (taskLower.includes('api') || taskLower.includes('server') || taskLower.includes('database'))) {
+          bestMatch = agentName
+          break
+        }
+      }
+
+      await this.agentRouter.logUsage(task, bestMatch, projectPath)
+
+      return {
+        agent: { name: bestMatch },
+        routing: {
+          confidence: 0.7,
+          reason: 'Keyword-based agent matching',
+          availableAgents: agents,
+        },
+        _agenticNote: 'Claude should verify this assignment using agent context',
+      }
+    } catch {
+      return {
+        agent: { name: 'generalist' },
+        routing: {
+          confidence: 1.0,
+          reason: 'Agent routing unavailable',
+        },
+      }
+    }
   }
 }
 

package/core/commands/planning.ts

@@ -22,6 +22,16 @@ import { queueStorage, ideasStorage } from '../storage'
 import authorDetector from '../infrastructure/author-detector'
 import commandInstaller from '../infrastructure/command-installer'
 
+// Lazy-loaded to avoid circular dependencies
+let _analysisCommands: import('./analysis').AnalysisCommands | null = null
+async function getAnalysisCommands(): Promise<import('./analysis').AnalysisCommands> {
+  if (!_analysisCommands) {
+    const { AnalysisCommands } = await import('./analysis')
+    _analysisCommands = new AnalysisCommands()
+  }
+  return _analysisCommands
+}
+
 export class PlanningCommands extends PrjctCommandsBase {
   /**
    * /p:init - Initialize prjct project
@@ -82,11 +92,12 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       if (hasCode || !isEmpty) {
         out.spin('analyzing project...')
-        const analysisResult = await (this as unknown as { analyze: (options: AnalyzeOptions, projectPath: string) => Promise<CommandResult> }).analyze({}, projectPath)
+        const analysis = await getAnalysisCommands()
+        const analysisResult = await analysis.analyze({}, projectPath)
 
         if (analysisResult.success) {
           out.spin('generating agents...')
-          await (this as unknown as { sync: (projectPath: string) => Promise<CommandResult> }).sync(projectPath)
+          await analysis.sync(projectPath)
           out.done('initialized')
           return { success: true, mode: 'existing', projectId }
         }

package/core/commands/setup.ts

@@ -1,21 +1,15 @@
 /**
- * Setup Commands: start, setup, migrateAll, installStatusLine, showAsciiArt
+ * Setup Commands: start, setup, installStatusLine, showAsciiArt
  */
 
 import path from 'path'
 import fs from 'fs'
-import { promises as fsPromises } from 'fs'
 import os from 'os'
 import chalk from 'chalk'
 
-import migrator from '../infrastructure/migrator'
 import commandInstaller from '../infrastructure/command-installer'
-import type { CommandResult, SetupOptions, MigrateOptions, GlobalConfig, MigrationResult } from './types'
-import {
-  PrjctCommandsBase,
-  configManager,
-  dateHelper
-} from './base'
+import type { CommandResult, SetupOptions } from './types'
+import { PrjctCommandsBase } from './base'
 import { VERSION } from '../utils/version'
 
 export class SetupCommands extends PrjctCommandsBase {
@@ -225,80 +219,4 @@ fi
     console.log('')
   }
 
-  /**
-   * Migrate all legacy projects
-   */
-  async migrateAll(options: MigrateOptions = {}): Promise<CommandResult> {
-    console.log('🔄 Scanning for legacy prjct projects...\n')
-
-    const homeDir = os.homedir()
-    const globalRoot = path.join(homeDir, '.prjct-cli', 'projects')
-
-    let projectIds: string[] = []
-    try {
-      const dirs = await fsPromises.readdir(globalRoot)
-      projectIds = dirs.filter((d: string) => !d.startsWith('.'))
-    } catch {
-      return {
-        success: false,
-        message: '❌ No prjct projects found',
-      }
-    }
-
-    console.log(`📁 Found ${projectIds.length} projects in global storage\n`)
-
-    const migrated: { projectId: string; path: string }[] = []
-    const failed: { projectId: string; path: string; error: string }[] = []
-    const skipped: { projectId: string; reason: string }[] = []
-
-    for (const projectId of projectIds) {
-      const globalConfig = await configManager.readGlobalConfig(projectId) as GlobalConfig | null
-      if (!globalConfig || !globalConfig.projectPath) {
-        skipped.push({ projectId, reason: 'No project path in config' })
-        continue
-      }
-
-      const projectPath = globalConfig.projectPath!
-
-      if (!(await migrator.needsMigration(projectPath))) {
-        skipped.push({ projectId, reason: 'Already migrated' })
-        continue
-      }
-
-      console.log(`🔄 Migrating: ${projectPath}`)
-
-      try {
-        const result = await migrator.migrate(projectPath, options) as MigrationResult
-
-        if (result.success) {
-          migrated.push({ projectId, path: projectPath })
-          console.log(`   ✅ Migrated successfully`)
-        } else {
-          const issues = result.issues?.join(', ') || 'Unknown error'
-          failed.push({ projectId, path: projectPath, error: issues })
-          console.log(`   ❌ ${issues}`)
-        }
-      } catch (error) {
-        failed.push({ projectId, path: projectPath, error: (error as Error).message })
-        console.log(`   ❌ ${(error as Error).message}`)
-      }
-
-      console.log('')
-    }
-
-    console.log('\n📊 Migration Summary:')
-    console.log(`   ✅ Migrated: ${migrated.length}`)
-    console.log(`   ⏭️  Skipped: ${skipped.length}`)
-    console.log(`   ❌ Failed: ${failed.length}`)
-
-    if (failed.length > 0) {
-      console.log('\n❌ Failed migrations:')
-      failed.forEach((f) => console.log(`   - ${f.path}: ${f.error}`))
-    }
-
-    return {
-      success: failed.length === 0,
-      message: '',
-    }
-  }
 }

package/core/domain/agent-generator.ts

@@ -38,9 +38,9 @@ class AgentGenerator {
 
   constructor(projectId: string | null = null) {
     this.projectId = projectId
-    // NEW: Write to data/agents/ for JSON storage (OpenCode-style)
+    // Write to agents/ for MD storage (matches AgentLoader)
     this.outputDir = projectId
-      ? path.join(os.homedir(), '.prjct-cli', 'projects', projectId, 'data', 'agents')
+      ? path.join(os.homedir(), '.prjct-cli', 'projects', projectId, 'agents')
       : path.join(os.homedir(), '.prjct-cli', 'agents')
     this.loader = new AgentLoader(projectId)
   }
@@ -54,18 +54,10 @@ class AgentGenerator {
     log.debug(`Generating ${agentName} agent...`)
     await fs.mkdir(this.outputDir, { recursive: true })
 
-    // Write as JSON (OpenCode-style storage)
-    const agent = {
-      name: agentName,
-      role: config.role || agentName,
-      domain: config.domain || 'general',
-      expertise: config.expertise || '',
-      contextFilter: config.contextFilter || 'Only relevant files',
-      createdAt: new Date().toISOString()
-    }
-
-    const outputPath = path.join(this.outputDir, `${agentName}.json`)
-    await fs.writeFile(outputPath, JSON.stringify(agent, null, 2), 'utf-8')
+    // Write as MD (matches AgentLoader which reads .md files)
+    const content = this.buildAgentPrompt(agentName, config)
+    const outputPath = path.join(this.outputDir, `${agentName}.md`)
+    await fs.writeFile(outputPath, content, 'utf-8')
     log.debug(`${agentName} agent created`)
 
     return { name: agentName }
@@ -135,10 +127,10 @@ ${config.contextFilter || 'Only relevant files'}
 
     try {
       const files = await fs.readdir(this.outputDir)
-      const agentFiles = files.filter((f) => f.endsWith('.json') && !f.startsWith('.'))
+      const agentFiles = files.filter((f) => f.endsWith('.md') && !f.startsWith('.'))
 
       for (const file of agentFiles) {
-        const type = file.replace('.json', '')
+        const type = file.replace('.md', '')
 
         if (!requiredAgents.includes(type)) {
           const filePath = path.join(this.outputDir, file)
@@ -160,7 +152,7 @@ ${config.contextFilter || 'Only relevant files'}
   async listAgents(): Promise<string[]> {
     try {
       const files = await fs.readdir(this.outputDir)
-      return files.filter((f) => f.endsWith('.json') && !f.startsWith('.')).map((f) => f.replace('.json', ''))
+      return files.filter((f) => f.endsWith('.md') && !f.startsWith('.')).map((f) => f.replace('.md', ''))
     } catch {
       return []
     }

package/core/errors.ts

@@ -0,0 +1,209 @@
+/**
+ * Custom Error Hierarchy for prjct-cli
+ *
+ * Base error class with specific subclasses for different error domains.
+ * Enables typed error handling and better error messages.
+ *
+ * @module core/errors
+ * @version 1.0.0
+ */
+
+/**
+ * Base error class for all prjct errors
+ */
+export class PrjctError extends Error {
+  readonly code: string
+  readonly isOperational: boolean
+
+  constructor(message: string, code = 'PRJCT_ERROR') {
+    super(message)
+    this.name = 'PrjctError'
+    this.code = code
+    this.isOperational = true // Distinguishes from programming errors
+    Error.captureStackTrace?.(this, this.constructor)
+  }
+}
+
+/**
+ * Configuration-related errors
+ */
+export class ConfigError extends PrjctError {
+  constructor(message: string, code = 'CONFIG_ERROR') {
+    super(message, code)
+    this.name = 'ConfigError'
+  }
+
+  static notFound(path: string): ConfigError {
+    return new ConfigError(`Configuration not found: ${path}`, 'CONFIG_NOT_FOUND')
+  }
+
+  static invalid(reason: string): ConfigError {
+    return new ConfigError(`Invalid configuration: ${reason}`, 'CONFIG_INVALID')
+  }
+
+  static parseError(path: string): ConfigError {
+    return new ConfigError(`Failed to parse configuration: ${path}`, 'CONFIG_PARSE_ERROR')
+  }
+}
+
+/**
+ * Storage and file system errors
+ */
+export class StorageError extends PrjctError {
+  constructor(message: string, code = 'STORAGE_ERROR') {
+    super(message, code)
+    this.name = 'StorageError'
+  }
+
+  static readFailed(path: string): StorageError {
+    return new StorageError(`Failed to read: ${path}`, 'STORAGE_READ_FAILED')
+  }
+
+  static writeFailed(path: string): StorageError {
+    return new StorageError(`Failed to write: ${path}`, 'STORAGE_WRITE_FAILED')
+  }
+
+  static notFound(path: string): StorageError {
+    return new StorageError(`File not found: ${path}`, 'STORAGE_NOT_FOUND')
+  }
+}
+
+/**
+ * Project-related errors
+ */
+export class ProjectError extends PrjctError {
+  constructor(message: string, code = 'PROJECT_ERROR') {
+    super(message, code)
+    this.name = 'ProjectError'
+  }
+
+  static notInitialized(): ProjectError {
+    return new ProjectError('Project not initialized. Run /p:init first.', 'PROJECT_NOT_INIT')
+  }
+
+  static notFound(projectId: string): ProjectError {
+    return new ProjectError(`Project not found: ${projectId}`, 'PROJECT_NOT_FOUND')
+  }
+
+  static invalidId(projectId: string): ProjectError {
+    return new ProjectError(`Invalid project ID: ${projectId}`, 'PROJECT_INVALID_ID')
+  }
+}
+
+/**
+ * Command execution errors
+ */
+export class CommandError extends PrjctError {
+  constructor(message: string, code = 'COMMAND_ERROR') {
+    super(message, code)
+    this.name = 'CommandError'
+  }
+
+  static notFound(commandName: string): CommandError {
+    return new CommandError(`Command not found: ${commandName}`, 'COMMAND_NOT_FOUND')
+  }
+
+  static invalidParams(reason: string): CommandError {
+    return new CommandError(`Invalid parameters: ${reason}`, 'COMMAND_INVALID_PARAMS')
+  }
+
+  static executionFailed(commandName: string, reason: string): CommandError {
+    return new CommandError(`Command '${commandName}' failed: ${reason}`, 'COMMAND_EXEC_FAILED')
+  }
+}
+
+/**
+ * Template-related errors
+ */
+export class TemplateError extends PrjctError {
+  constructor(message: string, code = 'TEMPLATE_ERROR') {
+    super(message, code)
+    this.name = 'TemplateError'
+  }
+
+  static notFound(templateName: string): TemplateError {
+    return new TemplateError(`Template not found: ${templateName}.md`, 'TEMPLATE_NOT_FOUND')
+  }
+
+  static parseFailed(templateName: string): TemplateError {
+    return new TemplateError(`Failed to parse template: ${templateName}`, 'TEMPLATE_PARSE_ERROR')
+  }
+}
+
+/**
+ * Agent-related errors
+ */
+export class AgentError extends PrjctError {
+  constructor(message: string, code = 'AGENT_ERROR') {
+    super(message, code)
+    this.name = 'AgentError'
+  }
+
+  static notSupported(agentType: string): AgentError {
+    return new AgentError(`Unsupported agent type: ${agentType}`, 'AGENT_NOT_SUPPORTED')
+  }
+
+  static initFailed(reason: string): AgentError {
+    return new AgentError(`Agent initialization failed: ${reason}`, 'AGENT_INIT_FAILED')
+  }
+}
+
+/**
+ * Type guard to check if error is a PrjctError
+ */
+export function isPrjctError(error: unknown): error is PrjctError {
+  return error instanceof PrjctError
+}
+
+/**
+ * Type guard for specific error types
+ */
+export function isConfigError(error: unknown): error is ConfigError {
+  return error instanceof ConfigError
+}
+
+export function isStorageError(error: unknown): error is StorageError {
+  return error instanceof StorageError
+}
+
+export function isProjectError(error: unknown): error is ProjectError {
+  return error instanceof ProjectError
+}
+
+export function isCommandError(error: unknown): error is CommandError {
+  return error instanceof CommandError
+}
+
+export function isTemplateError(error: unknown): error is TemplateError {
+  return error instanceof TemplateError
+}
+
+export function isAgentError(error: unknown): error is AgentError {
+  return error instanceof AgentError
+}
+
+/**
+ * Extract error message safely from unknown error
+ */
+export function getErrorMessage(error: unknown): string {
+  if (isPrjctError(error)) {
+    return error.message
+  }
+  if (error instanceof Error) {
+    return error.message
+  }
+  if (typeof error === 'string') {
+    return error
+  }
+  return 'Unknown error'
+}
+
+/**
+ * Extract error code safely from unknown error
+ */
+export function getErrorCode(error: unknown): string {
+  if (isPrjctError(error)) {
+    return error.code
+  }
+  return 'UNKNOWN_ERROR'
+}

package/core/infrastructure/config-manager.ts

@@ -13,7 +13,9 @@
 import fs from 'fs/promises'
 import path from 'path'
 import pathManager from './path-manager'
+import authorDetector from './author-detector'
 import { VERSION } from '../utils/version'
+import { ConfigError, getErrorMessage } from '../errors'
 
 interface Author {
   name: string
@@ -50,7 +52,13 @@ class ConfigManager {
       const configPath = pathManager.getLocalConfigPath(projectPath)
       const content = await fs.readFile(configPath, 'utf-8')
       return JSON.parse(content)
-    } catch {
+    } catch (error) {
+      // File not found is expected - return null
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null
+      }
+      // JSON parse errors or other issues - log and return null
+      console.warn(`Warning: Could not read config at ${projectPath}: ${getErrorMessage(error)}`)
       return null
     }
   }
@@ -77,7 +85,13 @@ class ConfigManager {
       const configPath = pathManager.getGlobalProjectConfigPath(projectId)
       const content = await fs.readFile(configPath, 'utf-8')
       return JSON.parse(content)
-    } catch {
+    } catch (error) {
+      // File not found is expected for new projects
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null
+      }
+      // Log other errors for debugging
+      console.warn(`Warning: Could not read global config for ${projectId}: ${getErrorMessage(error)}`)
       return null
     }
   }
@@ -202,7 +216,12 @@ class ConfigManager {
     try {
       const coreFiles = await fs.readdir(path.join(globalPath, 'core'))
       return coreFiles.length === 0
-    } catch {
+    } catch (error) {
+      // Directory not found means migration needed
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return true
+      }
+      // Permission errors or other issues - assume migration needed
       return true
     }
   }
@@ -275,8 +294,6 @@ class ConfigManager {
    * Get current author for session (detect or get from global config)
    */
   async getCurrentAuthor(projectPath: string): Promise<string> {
-    // Dynamic import to avoid circular dependency
-    const authorDetector = (await import('./author-detector')).default
     const author = await authorDetector.detect()
 
     const projectId = await this.getProjectId(projectPath)