prjct-cli 1.4.0 → 1.5.1

package/core/commands/uninstall.ts

@@ -8,7 +8,6 @@
  */
 
 import { execSync } from 'node:child_process'
-import fsSync from 'node:fs'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
@@ -17,6 +16,7 @@ import chalk from 'chalk'
 import { getProviderPaths } from '../infrastructure/command-installer'
 import pathManager from '../infrastructure/path-manager'
 import type { CommandResult, UninstallOptions } from '../types'
+import { fileExists } from '../utils/fs-helpers'
 import { PrjctCommandsBase } from './base'
 
 // Markers for prjct section in CLAUDE.md
@@ -135,7 +135,7 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 1. ~/.prjct-cli/ (main data directory)
   const prjctCliPath = pathManager.getGlobalBasePath()
-  const prjctCliExists = fsSync.existsSync(prjctCliPath)
+  const prjctCliExists = await fileExists(prjctCliPath)
   const projectCount = prjctCliExists
     ? await countDirectoryItems(path.join(prjctCliPath, 'projects'))
     : 0
@@ -152,12 +152,12 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 2. ~/.claude/CLAUDE.md (prjct section only)
   const claudeMdPath = path.join(providerPaths.claude.config, 'CLAUDE.md')
-  const claudeMdExists = fsSync.existsSync(claudeMdPath)
+  const claudeMdExists = await fileExists(claudeMdPath)
   let hasPrjctSection = false
 
   if (claudeMdExists) {
     try {
-      const content = fsSync.readFileSync(claudeMdPath, 'utf-8')
+      const content = await fs.readFile(claudeMdPath, 'utf-8')
       hasPrjctSection = content.includes(PRJCT_START_MARKER) && content.includes(PRJCT_END_MARKER)
     } catch {
       // Can't read file
@@ -173,7 +173,7 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 3. ~/.claude/commands/p/ (prjct commands)
   const claudeCommandsPath = providerPaths.claude.commands
-  const claudeCommandsExists = fsSync.existsSync(claudeCommandsPath)
+  const claudeCommandsExists = await fileExists(claudeCommandsPath)
   const claudeCommandsSize = claudeCommandsExists ? await getDirectorySize(claudeCommandsPath) : 0
 
   items.push({
@@ -186,7 +186,7 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 4. ~/.claude/commands/p.md (router)
   const claudeRouterPath = providerPaths.claude.router
-  const claudeRouterExists = fsSync.existsSync(claudeRouterPath)
+  const claudeRouterExists = await fileExists(claudeRouterPath)
 
   items.push({
     path: claudeRouterPath,
@@ -197,7 +197,7 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 5. ~/.claude/prjct-statusline.sh (status line script)
   const statusLinePath = path.join(providerPaths.claude.config, 'prjct-statusline.sh')
-  const statusLineExists = fsSync.existsSync(statusLinePath)
+  const statusLineExists = await fileExists(statusLinePath)
 
   items.push({
     path: statusLinePath,
@@ -208,7 +208,7 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 6. ~/.gemini/commands/p.toml (Gemini router, if exists)
   const geminiRouterPath = providerPaths.gemini.router
-  const geminiRouterExists = fsSync.existsSync(geminiRouterPath)
+  const geminiRouterExists = await fileExists(geminiRouterPath)
 
   items.push({
     path: geminiRouterPath,
@@ -219,12 +219,12 @@ async function gatherUninstallItems(): Promise<UninstallItem[]> {
 
   // 7. ~/.gemini/GEMINI.md (prjct section only, if exists)
   const geminiMdPath = path.join(providerPaths.gemini.config, 'GEMINI.md')
-  const geminiMdExists = fsSync.existsSync(geminiMdPath)
+  const geminiMdExists = await fileExists(geminiMdPath)
   let hasGeminiPrjctSection = false
 
   if (geminiMdExists) {
     try {
-      const content = fsSync.readFileSync(geminiMdPath, 'utf-8')
+      const content = await fs.readFile(geminiMdPath, 'utf-8')
       hasGeminiPrjctSection =
         content.includes(PRJCT_START_MARKER) && content.includes(PRJCT_END_MARKER)
     } catch {
@@ -288,7 +288,7 @@ async function createBackup(): Promise<string | null> {
 
     const prjctCliPath = pathManager.getGlobalBasePath()
 
-    if (fsSync.existsSync(prjctCliPath)) {
+    if (await fileExists(prjctCliPath)) {
       // Copy entire .prjct-cli directory
       await copyDirectory(prjctCliPath, path.join(backupDir, '.prjct-cli'))
     }

package/core/index.ts

@@ -7,7 +7,6 @@
 import { PrjctCommands } from './commands/index'
 import { commandRegistry } from './commands/registry'
 import './commands/register' // Ensure commands are registered
-import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import chalk from 'chalk'
@@ -15,6 +14,8 @@ import type { CommandMeta } from './commands/registry'
 import { detectAllProviders, detectAntigravity } from './infrastructure/ai-provider'
 import configManager from './infrastructure/config-manager'
 import { sessionTracker } from './services/session-tracker'
+import { getError } from './utils/error-messages'
+import { fileExists } from './utils/fs-helpers'
 import out from './utils/output'
 
 interface ParsedCommandArgs {
@@ -34,7 +35,7 @@ async function main(): Promise<void> {
 
   if (['-v', '--version', 'version'].includes(commandName)) {
     const packageJson = await import('../package.json')
-    displayVersion(packageJson.version)
+    await displayVersion(packageJson.version)
     process.exit(0)
   }
 
@@ -53,27 +54,34 @@ async function main(): Promise<void> {
     const cmd = commandRegistry.getByName(commandName)
 
     if (!cmd) {
-      console.error(`Unknown command: ${commandName}`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      const suggestion = findClosestCommand(commandName)
+      const hint = suggestion
+        ? `Did you mean 'prjct ${suggestion}'? Run 'prjct --help' for all commands`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint(
+        getError('UNKNOWN_COMMAND', { message: `Unknown command: ${commandName}`, hint })
+      )
       out.end()
       process.exit(1)
     }
 
     // 2. Check if deprecated
     if (cmd.deprecated) {
-      console.error(`Command '${commandName}' is deprecated.`)
-      if (cmd.replacedBy) {
-        console.error(`Use 'prjct ${cmd.replacedBy}' instead.`)
-      }
+      const hint = cmd.replacedBy
+        ? `Use 'prjct ${cmd.replacedBy}' instead`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint({ message: `Command '${commandName}' is deprecated`, hint })
       out.end()
       process.exit(1)
     }
 
     // 3. Check if implemented
     if (!cmd.implemented) {
-      console.error(`Command '${commandName}' exists but is not yet implemented.`)
-      console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      out.failWithHint({
+        message: `Command '${commandName}' is not yet implemented`,
+        hint: "Run 'prjct --help' to see available commands",
+        docs: 'https://github.com/jlopezlira/prjct-cli',
+      })
       out.end()
       process.exit(1)
     }
@@ -81,7 +89,15 @@ async function main(): Promise<void> {
     // 4. Parse arguments
     const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs)
 
-    // 4.5. Session tracking — touch/create session before command execution
+    // 4.5. Validate required params
+    const paramError = validateCommandParams(cmd, parsedArgs)
+    if (paramError) {
+      out.failWithHint(paramError)
+      out.end()
+      process.exit(1)
+    }
+
+    // 4.6. Session tracking — touch/create session before command execution
     let projectId: string | null = null
     const commandStartTime = Date.now()
     try {
@@ -193,6 +209,71 @@ async function main(): Promise<void> {
   }
 }
 
+/**
+ * Validate that required params are provided
+ * Parses CommandMeta.params: <required> vs [optional]
+ */
+function validateCommandParams(
+  cmd: CommandMeta,
+  parsedArgs: string[]
+): import('./utils/error-messages').ErrorWithHint | null {
+  if (!cmd.params) return null
+
+  // Extract required params: tokens wrapped in <angle brackets>
+  const requiredParams = cmd.params.match(/<[^>]+>/g)
+  if (!requiredParams || requiredParams.length === 0) return null
+
+  // Check if enough positional args provided
+  if (parsedArgs.length < requiredParams.length) {
+    const paramNames = requiredParams.map((p) => p.slice(1, -1)).join(', ')
+    const usage = cmd.usage.terminal || `prjct ${cmd.name} ${cmd.params}`
+    return getError('MISSING_PARAM', {
+      message: `Missing required parameter: ${paramNames}`,
+      hint: `Usage: ${usage}`,
+    })
+  }
+
+  return null
+}
+
+/**
+ * Find closest matching command name for did-you-mean suggestions
+ * Uses Levenshtein edit distance — suggests if distance <= 2
+ */
+function findClosestCommand(input: string): string | null {
+  const allNames = commandRegistry.getAll().map((c) => c.name)
+  let best: string | null = null
+  let bestDist = Infinity
+
+  for (const name of allNames) {
+    const dist = editDistance(input.toLowerCase(), name.toLowerCase())
+    if (dist < bestDist) {
+      bestDist = dist
+      best = name
+    }
+  }
+
+  // Only suggest if edit distance is at most 2
+  return bestDist <= 2 ? best : null
+}
+
+function editDistance(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0))
+  for (let i = 0; i <= m; i++) dp[i][0] = i
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    }
+  }
+  return dp[m][n]
+}
+
 /**
  * Parse command arguments dynamically
  */
@@ -226,18 +307,21 @@ function parseCommandArgs(_cmd: CommandMeta, rawArgs: string[]): ParsedCommandAr
 /**
  * Display version with provider status
  */
-function displayVersion(version: string): void {
-  const detection = detectAllProviders()
+async function displayVersion(version: string): Promise<void> {
+  const detection = await detectAllProviders()
 
   // Check if prjct commands are installed for each provider
   const claudeCommandPath = path.join(os.homedir(), '.claude', 'commands', 'p.md')
   const geminiCommandPath = path.join(os.homedir(), '.gemini', 'commands', 'p.toml')
-  const claudeConfigured = fs.existsSync(claudeCommandPath)
-  const geminiConfigured = fs.existsSync(geminiCommandPath)
+  const [claudeConfigured, geminiConfigured, cursorConfigured, cursorExists] = await Promise.all([
+    fileExists(claudeCommandPath),
+    fileExists(geminiCommandPath),
+    fileExists(path.join(process.cwd(), '.cursor', 'commands', 'sync.md')),
+    fileExists(path.join(process.cwd(), '.cursor')),
+  ])
 
-  // Check current project for Cursor
-  const cursorConfigured = fs.existsSync(path.join(process.cwd(), '.cursor', 'commands', 'sync.md'))
-  const cursorExists = fs.existsSync(path.join(process.cwd(), '.cursor'))
+  // Antigravity status (global, skills-based)
+  const antigravityDetection = await detectAntigravity()
 
   console.log(`
 ${chalk.cyan('p/')} prjct v${version}
@@ -263,8 +347,6 @@ ${chalk.dim('Providers:')}`)
     console.log(`  Gemini CLI    ${chalk.dim('○ not installed')}`)
   }
 
-  // Antigravity status (global, skills-based)
-  const antigravityDetection = detectAntigravity()
   if (antigravityDetection.installed) {
     const status = antigravityDetection.skillInstalled
       ? chalk.green('✓ ready')

package/core/infrastructure/agent-detector.ts

@@ -5,9 +5,9 @@
  * @module infrastructure/agent-detector
  */
 
-import fs from 'node:fs'
 import path from 'node:path'
 import type { DetectedAgent } from '../types'
+import { fileExists } from '../utils/fs-helpers'
 
 declare const global: typeof globalThis & {
   mcp?: { filesystem?: unknown }
@@ -79,7 +79,7 @@ const TERMINAL_AGENT: DetectedAgent = {
 
 // ============ Detection Functions ============
 
-export function isClaudeEnvironment(): boolean {
+export async function isClaudeEnvironment(): Promise<boolean> {
   // Environment variables
   if (process.env.CLAUDE_AGENT || process.env.ANTHROPIC_CLAUDE) return true
 
@@ -88,11 +88,11 @@ export function isClaudeEnvironment(): boolean {
 
   // Configuration files
   const projectRoot = process.cwd()
-  if (fs.existsSync(path.join(projectRoot, 'CLAUDE.md'))) return true
+  if (await fileExists(path.join(projectRoot, 'CLAUDE.md'))) return true
 
   // Claude directory in home
   const homeDir = process.env.HOME || process.env.USERPROFILE || ''
-  if (fs.existsSync(path.join(homeDir, '.claude'))) return true
+  if (await fileExists(path.join(homeDir, '.claude'))) return true
 
   // Filesystem paths
   const cwd = process.cwd()
@@ -112,7 +112,7 @@ export function getTerminalAgent(): DetectedAgent {
 export async function detect(): Promise<DetectedAgent> {
   if (cachedAgent) return cachedAgent
 
-  cachedAgent = isClaudeEnvironment() ? getClaudeAgent() : getTerminalAgent()
+  cachedAgent = (await isClaudeEnvironment()) ? getClaudeAgent() : getTerminalAgent()
   return cachedAgent
 }
 
@@ -125,13 +125,13 @@ export function reset(): void {
   cachedAgent = null
 }
 
-export function isClaude(): boolean {
+export async function isClaude(): Promise<boolean> {
   if (cachedAgent) return cachedAgent.type === 'claude'
   return isClaudeEnvironment()
 }
 
-export function isTerminal(): boolean {
-  return !isClaude()
+export async function isTerminal(): Promise<boolean> {
+  return !(await isClaude())
 }
 
 // ============ Default Export (backwards compat) ============

package/core/infrastructure/ai-provider.ts

@@ -17,10 +17,14 @@
  * @see https://docs.windsurf.com/windsurf/cascade/memories
  */
 
-import { execSync } from 'node:child_process'
-import fs from 'node:fs'
+import { exec } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
+import { promisify } from 'node:util'
+import { fileExists } from '../utils/fs-helpers'
+
+const execAsync = promisify(exec)
+
 import type {
   AIProviderConfig,
   AIProviderName,
@@ -173,10 +177,10 @@ export const Providers: Record<AIProviderName, AIProviderConfig> = {
 /**
  * Check if a CLI command is available
  */
-function whichCommand(command: string): string | null {
+async function whichCommand(command: string): Promise<string | null> {
   try {
-    const result = execSync(`which ${command}`, { stdio: 'pipe', encoding: 'utf-8' })
-    return result.trim()
+    const { stdout } = await execAsync(`which ${command}`)
+    return stdout.trim()
   } catch {
     return null
   }
@@ -185,12 +189,12 @@ function whichCommand(command: string): string | null {
 /**
  * Get CLI version
  */
-function getCliVersion(command: string): string | null {
+async function getCliVersion(command: string): Promise<string | null> {
   try {
-    const result = execSync(`${command} --version`, { stdio: 'pipe', encoding: 'utf-8' })
+    const { stdout } = await execAsync(`${command} --version`)
     // Extract version number from output (e.g., "claude 1.0.0" -> "1.0.0")
-    const match = result.match(/\d+\.\d+\.\d+/)
-    return match ? match[0] : result.trim()
+    const match = stdout.match(/\d+\.\d+\.\d+/)
+    return match ? match[0] : stdout.trim()
   } catch {
     return null
   }
@@ -200,7 +204,7 @@ function getCliVersion(command: string): string | null {
  * Detect if a specific CLI-based provider is installed
  * Note: Cursor is NOT a CLI, use detectCursorProject() instead
  */
-export function detectProvider(provider: AIProviderName): ProviderDetectionResult {
+export async function detectProvider(provider: AIProviderName): Promise<ProviderDetectionResult> {
   const config = Providers[provider]
 
   // Cursor is not a CLI - return not installed for CLI detection
@@ -208,13 +212,13 @@ export function detectProvider(provider: AIProviderName): ProviderDetectionResul
     return { installed: false }
   }
 
-  const cliPath = whichCommand(config.cliCommand)
+  const cliPath = await whichCommand(config.cliCommand)
 
   if (!cliPath) {
     return { installed: false }
   }
 
-  const version = getCliVersion(config.cliCommand)
+  const version = await getCliVersion(config.cliCommand)
 
   return {
     installed: true,
@@ -227,14 +231,12 @@ export function detectProvider(provider: AIProviderName): ProviderDetectionResul
  * Detect all available CLI-based providers
  * Note: Cursor detection is project-level, use detectCursorProject() separately
  */
-export function detectAllProviders(): {
+export async function detectAllProviders(): Promise<{
   claude: ProviderDetectionResult
   gemini: ProviderDetectionResult
-} {
-  return {
-    claude: detectProvider('claude'),
-    gemini: detectProvider('gemini'),
-  }
+}> {
+  const [claude, gemini] = await Promise.all([detectProvider('claude'), detectProvider('gemini')])
+  return { claude, gemini }
 }
 
 /**
@@ -245,14 +247,16 @@ export function detectAllProviders(): {
  * 2. Auto-detect single installed provider
  * 3. Default to Claude if both installed (backward compatibility)
  */
-export function getActiveProvider(projectProvider?: AIProviderName): AIProviderConfig {
+export async function getActiveProvider(
+  projectProvider?: AIProviderName
+): Promise<AIProviderConfig> {
   // If project has a saved preference, use it
   if (projectProvider && Providers[projectProvider]) {
     return Providers[projectProvider]
   }
 
   // Auto-detect
-  const detection = detectAllProviders()
+  const detection = await detectAllProviders()
 
   // If only one is installed, use it
   if (detection.claude.installed && !detection.gemini.installed) {
@@ -270,12 +274,12 @@ export function getActiveProvider(projectProvider?: AIProviderName): AIProviderC
  * Check if config directory exists for a provider
  * Returns false for project-level providers (Cursor)
  */
-export function hasProviderConfig(provider: AIProviderName): boolean {
+export async function hasProviderConfig(provider: AIProviderName): Promise<boolean> {
   const config = Providers[provider]
   if (!config.configDir) {
     return false // Cursor has no global config directory
   }
-  return fs.existsSync(config.configDir)
+  return fileExists(config.configDir)
 }
 
 // =============================================================================
@@ -313,13 +317,15 @@ export function getProviderBranding(provider: AIProviderName): ProviderBranding
  * Cursor has NO global config (~/.cursor/ doesn't exist).
  * Detection is based on project-level .cursor/ directory.
  */
-export function detectCursorProject(projectRoot: string): CursorProjectDetection {
+export async function detectCursorProject(projectRoot: string): Promise<CursorProjectDetection> {
   const cursorDir = path.join(projectRoot, '.cursor')
   const rulesDir = path.join(cursorDir, 'rules')
   const routerPath = path.join(rulesDir, 'prjct.mdc')
 
-  const detected = fs.existsSync(cursorDir)
-  const routerInstalled = fs.existsSync(routerPath)
+  const [detected, routerInstalled] = await Promise.all([
+    fileExists(cursorDir),
+    fileExists(routerPath),
+  ])
 
   return {
     detected,
@@ -331,8 +337,8 @@ export function detectCursorProject(projectRoot: string): CursorProjectDetection
 /**
  * Check if Cursor routers need to be regenerated
  */
-export function needsCursorRouterRegeneration(projectRoot: string): boolean {
-  const detection = detectCursorProject(projectRoot)
+export async function needsCursorRouterRegeneration(projectRoot: string): Promise<boolean> {
+  const detection = await detectCursorProject(projectRoot)
 
   // Only check if .cursor/ exists (project uses Cursor)
   // and prjct router is missing
@@ -349,13 +355,17 @@ export function needsCursorRouterRegeneration(projectRoot: string): boolean {
  * Windsurf has NO global config (~/.windsurf/ doesn't exist).
  * Detection is based on project-level .windsurf/ directory.
  */
-export function detectWindsurfProject(projectRoot: string): WindsurfProjectDetection {
+export async function detectWindsurfProject(
+  projectRoot: string
+): Promise<WindsurfProjectDetection> {
   const windsurfDir = path.join(projectRoot, '.windsurf')
   const rulesDir = path.join(windsurfDir, 'rules')
   const routerPath = path.join(rulesDir, 'prjct.md')
 
-  const detected = fs.existsSync(windsurfDir)
-  const routerInstalled = fs.existsSync(routerPath)
+  const [detected, routerInstalled] = await Promise.all([
+    fileExists(windsurfDir),
+    fileExists(routerPath),
+  ])
 
   return {
     detected,
@@ -367,8 +377,8 @@ export function detectWindsurfProject(projectRoot: string): WindsurfProjectDetec
 /**
  * Check if Windsurf routers need to be regenerated
  */
-export function needsWindsurfRouterRegeneration(projectRoot: string): boolean {
-  const detection = detectWindsurfProject(projectRoot)
+export async function needsWindsurfRouterRegeneration(projectRoot: string): Promise<boolean> {
+  const detection = await detectWindsurfProject(projectRoot)
 
   // Only check if .windsurf/ exists (project uses Windsurf)
   // and prjct router is missing
@@ -399,15 +409,17 @@ export interface AntigravityDetection {
  * Antigravity is NOT a CLI command - it's a GUI platform.
  * Detection is based on ~/.gemini/antigravity/ directory.
  */
-export function detectAntigravity(): AntigravityDetection {
+export async function detectAntigravity(): Promise<AntigravityDetection> {
   const configPath = AntigravityProvider.configDir
   if (!configPath) {
     return { installed: false, skillInstalled: false }
   }
 
-  const installed = fs.existsSync(configPath)
   const skillPath = path.join(configPath, 'skills', 'prjct', 'SKILL.md')
-  const skillInstalled = fs.existsSync(skillPath)
+  const [installed, skillInstalled] = await Promise.all([
+    fileExists(configPath),
+    fileExists(skillPath),
+  ])
 
   return {
     installed,
@@ -475,8 +487,8 @@ export function getProjectCommandsPath(provider: AIProviderName, projectRoot: st
  * Determine which provider to use during setup
  * Returns selection result with detection details
  */
-export function selectProvider(): ProviderSelectionResult {
-  const detection = detectAllProviders()
+export async function selectProvider(): Promise<ProviderSelectionResult> {
+  const detection = await detectAllProviders()
 
   const claudeInstalled = detection.claude.installed
   const geminiInstalled = detection.gemini.installed

package/core/infrastructure/command-installer.ts

@@ -159,11 +159,11 @@ export async function installDocs(): Promise<{ success: boolean; error?: string
  */
 export async function installGlobalConfig(): Promise<GlobalConfigResult> {
   const aiProvider = require('./ai-provider')
-  const activeProvider = aiProvider.getActiveProvider()
+  const activeProvider = await aiProvider.getActiveProvider()
   const providerName = activeProvider.name
 
   // Check if provider is installed
-  const detection = aiProvider.detectProvider(providerName)
+  const detection = await aiProvider.detectProvider(providerName)
   if (!detection.installed && !activeProvider.configDir) {
     return {
       success: false,
@@ -289,15 +289,21 @@ export async function installGlobalConfig(): Promise<GlobalConfigResult> {
 
 export class CommandInstaller {
   homeDir: string
-  claudeCommandsPath: string
-  claudeConfigPath: string
+  claudeCommandsPath = ''
+  claudeConfigPath = ''
   templatesDir: string
+  private _initialized = false
 
   constructor() {
     this.homeDir = os.homedir()
+    this.templatesDir = path.join(getPackageRoot(), 'templates', 'commands')
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (this._initialized) return
 
     const aiProvider = require('./ai-provider')
-    const activeProvider = aiProvider.getActiveProvider()
+    const activeProvider = await aiProvider.getActiveProvider()
 
     // Command paths are provider-specific
     if (activeProvider.name === 'gemini') {
@@ -308,13 +314,14 @@ export class CommandInstaller {
     }
 
     this.claudeConfigPath = activeProvider.configDir
-    this.templatesDir = path.join(getPackageRoot(), 'templates', 'commands')
+    this._initialized = true
   }
 
   /**
    * Detect if active provider is installed
    */
   async detectActiveProvider(): Promise<boolean> {
+    await this.ensureInit()
     try {
       await fs.access(this.claudeConfigPath)
       return true
@@ -372,7 +379,7 @@ export class CommandInstaller {
   async installCommands(): Promise<InstallResult> {
     const providerDetected = await this.detectActiveProvider()
     const aiProvider = require('./ai-provider')
-    const activeProvider = aiProvider.getActiveProvider()
+    const activeProvider = await aiProvider.getActiveProvider()
 
     if (!providerDetected) {
       return {
@@ -522,7 +529,8 @@ export class CommandInstaller {
   /**
    * Get installation path for Claude commands
    */
-  getInstallPath(): string {
+  async getInstallPath(): Promise<string> {
+    await this.ensureInit()
     return this.claudeCommandsPath
   }
 
@@ -548,7 +556,7 @@ export class CommandInstaller {
    */
   async installRouter(): Promise<boolean> {
     const aiProvider = require('./ai-provider')
-    const activeProvider = aiProvider.getActiveProvider()
+    const activeProvider = await aiProvider.getActiveProvider()
     const routerFile = activeProvider.name === 'gemini' ? 'p.toml' : 'p.md'
 
     try {
@@ -575,7 +583,7 @@ export class CommandInstaller {
    */
   async removeLegacyCommands(): Promise<number> {
     const aiProvider = require('./ai-provider')
-    const activeProvider = aiProvider.getActiveProvider()
+    const activeProvider = await aiProvider.getActiveProvider()
     const commandsRoot = path.join(activeProvider.configDir, 'commands')
 
     let removed = 0