prjct-cli 1.6.10 → 1.6.12

package/CHANGELOG.md

@@ -1,12 +1,77 @@
 # Changelog
 
+## [1.6.12] - 2026-02-07
+
+### Bug Fixes
+
+- replace sync I/O in imports-tool hot path (PRJ-290) (#137)
+
+
+## [1.6.14] - 2026-02-07
+
+### Bug Fixes
+- **Replace sync I/O in imports-tool hot path (PRJ-290)**: Converted `tryResolve`/`resolveImport`/`extractImports` from sync `require('node:fs')` with `existsSync`+`statSync` to async `fs.stat()` from `node:fs/promises`. Also replaced repeated `getPackageRoot()` calls with the pre-resolved `PACKAGE_ROOT` constant in prompt-builder, command-installer, and setup modules.
+
+### Implementation Details
+The `imports-tool.ts` file had an inline `require('node:fs')` call inside `tryResolve()` that used `existsSync` and `statSync` in a loop — a true hot path during import analysis. Converted the entire chain (`tryResolve` → `resolveImport` → `extractImports`) to async, using the already-imported `fs` from `node:fs/promises`. `version.ts` was kept sync intentionally: esbuild CJS output (used for postinstall) doesn't support top-level await, and its I/O runs once at cold start with results cached.
+
+### Learnings
+- esbuild CJS format does not support top-level `await` — async module exports require ESM format
+- `version.ts` cold-start I/O is negligible (runs once, cached) vs `imports-tool.ts` which resolves extensions in a loop per import
+- Using pre-resolved `PACKAGE_ROOT` constant avoids repeated sync function calls across modules
+
+### Test Plan
+
+#### For QA
+1. Run `prjct context imports <file>` — verify import resolution works correctly (resolves `.ts`, `.tsx`, `.js` extensions and `/index.ts` barrel imports)
+2. Run `prjct sync` — verify command-installer and setup find templates via `PACKAGE_ROOT`
+3. Run `bun run build` — verify all 5 build targets compile without errors
+4. Verify no `fs.*Sync()` calls remain in `imports-tool.ts`
+
+#### For Users
+**What changed:** Import analysis is now fully async, eliminating sync file system calls in the hot path.
+**How to use:** No changes needed — `prjct context imports` works the same way.
+**Breaking changes:** None.
+
+## [1.6.11] - 2026-02-07
+
+### Performance
+
+- cache provider detection to eliminate redundant shell spawns (PRJ-289) (#136)
+
+## [1.6.13] - 2026-02-07
+
+### Improvements
+- **Cache provider detection to eliminate redundant shell spawns (PRJ-289)**: Provider detection results (Claude, Gemini CLI availability) are now cached to `~/.prjct-cli/cache/providers.json` with a 10-minute TTL. Subsequent CLI commands skip shell spawns entirely. Added 2-second timeout on `which`/`--version` spawns to prevent hangs. Added `--refresh` flag to force re-detection.
+
+### Implementation Details
+Created `core/utils/provider-cache.ts` with `readProviderCache()`, `writeProviderCache()`, and `invalidateProviderCache()`. Wired into `detectAllProviders()` — checks cache first, falls through to shell detection on miss or expiry, writes cache after detection. `bin/prjct.ts` parses `--refresh` early (like `--quiet`), invalidates cache, and passes refresh flag to detection.
+
+### Learnings
+- `execAsync` accepts a `timeout` option (milliseconds) that kills the child process on expiry — ideal for preventing hangs on broken CLI installations.
+- Biome enforces `Array#indexOf()` over `Array#findIndex()` for simple equality checks (`useIndexOf` rule).
+- Separating cache logic into its own module keeps `ai-provider.ts` focused on detection logic.
+
+### Test Plan
+
+#### For QA
+1. Run `prjct --version` twice — second run should be near-instant (cache hit)
+2. Delete `~/.prjct-cli/cache/providers.json`, run `prjct --version` — should re-detect and recreate cache
+3. Run `prjct --version --refresh` — should take ~2s (forced re-detection)
+4. Edit cache file to set timestamp 11 minutes ago — next command should re-detect (TTL expired)
+5. Run `prjct sync` — should use cached providers, no shell spawns
+
+#### For Users
+**What changed:** Provider detection is now cached for 10 minutes. CLI startup is ~30x faster for cached commands (~66ms vs ~2100ms).
+**How to use:** Automatic. Use `--refresh` to force re-detection after installing a new CLI.
+**Breaking changes:** None.
+
 ## [1.6.10] - 2026-02-07
 
 ### Bug Fixes
 
 - resolve signal handler and EventBus listener accumulation leaks (PRJ-287) (#135)
 
-
 ## [1.6.12] - 2026-02-07
 
 ### Bug Fixes

package/bin/prjct.ts

@@ -16,6 +16,7 @@ import configManager from '../core/infrastructure/config-manager'
 import editorsConfig from '../core/infrastructure/editors-config'
 import { DEFAULT_PORT, startServer } from '../core/server/server'
 import { fileExists } from '../core/utils/fs-helpers'
+import { invalidateProviderCache } from '../core/utils/provider-cache'
 import { VERSION } from '../core/utils/version'
 
 /**
@@ -62,6 +63,14 @@ if (isQuietMode) {
   setQuietMode(true)
 }
 
+// Parse --refresh flag (force re-detection of providers, invalidate cache)
+const refreshIndex = args.indexOf('--refresh')
+const isRefresh = refreshIndex !== -1
+if (isRefresh) {
+  args.splice(refreshIndex, 1)
+  await invalidateProviderCache()
+}
+
 // Colors for output (chalk respects NO_COLOR env)
 
 // Session tracking for commands that bypass core/index.ts
@@ -217,8 +226,8 @@ if (args[0] === 'start' || args[0] === 'setup') {
   console.log(getHelp(topic))
   process.exitCode = 0
 } else if (args[0] === 'version' || args[0] === '-v' || args[0] === '--version') {
-  // Show version with provider status
-  const detection = await detectAllProviders()
+  // Show version with provider status (uses cached detection unless --refresh)
+  const detection = await detectAllProviders(isRefresh)
   const home = os.homedir()
   const cwd = process.cwd()
   const [

package/core/agentic/prompt-builder.ts

@@ -27,7 +27,7 @@ import type {
 } from '../types'
 import { getErrorMessage, isNotFoundError } from '../types/fs'
 import { fileExists } from '../utils/fs-helpers'
-import { getPackageRoot } from '../utils/version'
+import { PACKAGE_ROOT } from '../utils/version'
 
 // Re-export types for convenience
 export type {
@@ -132,7 +132,7 @@ class PromptBuilder {
    * These modules extend the base global CLAUDE.md for complex operations
    */
   async loadModule(moduleName: string): Promise<string | null> {
-    const modulePath = path.join(getPackageRoot(), 'templates/global/modules', moduleName)
+    const modulePath = path.join(PACKAGE_ROOT, 'templates/global/modules', moduleName)
     return this.getTemplate(modulePath)
   }
 

package/core/context-tools/imports-tool.ts

@@ -178,7 +178,7 @@ export async function analyzeImports(
   const patterns = IMPORT_PATTERNS[language] || []
 
   // Extract imports
-  const imports = extractImports(content, patterns, absolutePath, projectPath)
+  const imports = await extractImports(content, patterns, absolutePath, projectPath)
 
   // Get reverse imports if requested
   let importedBy: ImportedBy[] = []
@@ -217,12 +217,12 @@ export async function analyzeImports(
 /**
  * Extract imports from file content
  */
-function extractImports(
+async function extractImports(
   content: string,
   patterns: ImportPattern[],
   absolutePath: string,
   projectPath: string
-): ImportRelation[] {
+): Promise<ImportRelation[]> {
   const imports: ImportRelation[] = []
   const seen = new Set<string>()
 
@@ -254,7 +254,7 @@ function extractImports(
       // Resolve internal imports
       let resolved: string | null = null
       if (!isExternal) {
-        resolved = resolveImport(source, absolutePath, projectPath)
+        resolved = await resolveImport(source, absolutePath, projectPath)
       }
 
       imports.push({
@@ -274,7 +274,11 @@ function extractImports(
 /**
  * Resolve a relative import to an absolute path
  */
-function resolveImport(source: string, fromFile: string, projectPath: string): string | null {
+async function resolveImport(
+  source: string,
+  fromFile: string,
+  projectPath: string
+): Promise<string | null> {
   const fileDir = path.dirname(fromFile)
 
   // Handle path alias like @/
@@ -291,15 +295,14 @@ function resolveImport(source: string, fromFile: string, projectPath: string): s
 /**
  * Try to resolve a path, adding extensions if needed
  */
-function tryResolve(basePath: string, projectPath: string): string | null {
+async function tryResolve(basePath: string, projectPath: string): Promise<string | null> {
   const extensions = ['', '.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.js']
 
   for (const ext of extensions) {
     const fullPath = basePath + ext
     try {
-      // Check synchronously (we're in a hot path)
-      const fs = require('node:fs')
-      if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+      const stat = await fs.stat(fullPath)
+      if (stat.isFile()) {
         return path.relative(projectPath, fullPath)
       }
     } catch {}

package/core/infrastructure/ai-provider.ts

@@ -22,8 +22,10 @@ import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import { fileExists } from '../utils/fs-helpers'
+import { readProviderCache, writeProviderCache } from '../utils/provider-cache'
 
 const execAsync = promisify(exec)
+const SPAWN_TIMEOUT_MS = 2000
 
 import type {
   AIProviderConfig,
@@ -179,7 +181,7 @@ export const Providers: Record<AIProviderName, AIProviderConfig> = {
  */
 async function whichCommand(command: string): Promise<string | null> {
   try {
-    const { stdout } = await execAsync(`which ${command}`)
+    const { stdout } = await execAsync(`which ${command}`, { timeout: SPAWN_TIMEOUT_MS })
     return stdout.trim()
   } catch {
     return null
@@ -191,7 +193,7 @@ async function whichCommand(command: string): Promise<string | null> {
  */
 async function getCliVersion(command: string): Promise<string | null> {
   try {
-    const { stdout } = await execAsync(`${command} --version`)
+    const { stdout } = await execAsync(`${command} --version`, { timeout: SPAWN_TIMEOUT_MS })
     // Extract version number from output (e.g., "claude 1.0.0" -> "1.0.0")
     const match = stdout.match(/\d+\.\d+\.\d+/)
     return match ? match[0] : stdout.trim()
@@ -229,14 +231,24 @@ export async function detectProvider(provider: AIProviderName): Promise<Provider
 
 /**
  * Detect all available CLI-based providers
- * Note: Cursor detection is project-level, use detectCursorProject() separately
+ * Results are cached to disk with a 10-minute TTL to avoid redundant shell spawns.
+ * Pass refresh=true to force re-detection.
  */
-export async function detectAllProviders(): Promise<{
+export async function detectAllProviders(refresh = false): Promise<{
   claude: ProviderDetectionResult
   gemini: ProviderDetectionResult
 }> {
+  if (!refresh) {
+    const cached = await readProviderCache()
+    if (cached) return cached
+  }
+
   const [claude, gemini] = await Promise.all([detectProvider('claude'), detectProvider('gemini')])
-  return { claude, gemini }
+  const detection = { claude, gemini }
+
+  await writeProviderCache(detection).catch(() => {})
+
+  return detection
 }
 
 /**

package/core/infrastructure/command-installer.ts

@@ -23,7 +23,7 @@ import type {
   UninstallResult,
 } from '../types'
 import { getErrorMessage, isNotFoundError } from '../types/fs'
-import { getPackageRoot } from '../utils/version'
+import { PACKAGE_ROOT } from '../utils/version'
 
 // =============================================================================
 // Module Types
@@ -51,7 +51,7 @@ interface ModuleConfig {
  */
 async function loadModuleConfig(): Promise<ModuleConfig | null> {
   try {
-    const configPath = path.join(getPackageRoot(), 'templates/global/modules/module-config.json')
+    const configPath = path.join(PACKAGE_ROOT, 'templates/global/modules/module-config.json')
     const content = await fs.readFile(configPath, 'utf-8')
     return JSON.parse(content) as ModuleConfig
   } catch {
@@ -66,11 +66,11 @@ async function loadModuleConfig(): Promise<ModuleConfig | null> {
  */
 export async function composeGlobalTemplate(profile?: string): Promise<string> {
   const config = await loadModuleConfig()
-  const modulesDir = path.join(getPackageRoot(), 'templates/global/modules')
+  const modulesDir = path.join(PACKAGE_ROOT, 'templates/global/modules')
 
   // Fallback to legacy template if config not found
   if (!config) {
-    const legacyPath = path.join(getPackageRoot(), 'templates/global/CLAUDE.md')
+    const legacyPath = path.join(PACKAGE_ROOT, 'templates/global/CLAUDE.md')
     return fs.readFile(legacyPath, 'utf-8')
   }
 
@@ -81,7 +81,7 @@ export async function composeGlobalTemplate(profile?: string): Promise<string> {
     // Fallback to default profile
     const defaultProfile = config.profiles[config.default]
     if (!defaultProfile) {
-      const legacyPath = path.join(getPackageRoot(), 'templates/global/CLAUDE.md')
+      const legacyPath = path.join(PACKAGE_ROOT, 'templates/global/CLAUDE.md')
       return fs.readFile(legacyPath, 'utf-8')
     }
   }
@@ -130,7 +130,7 @@ export async function getProfileForCommand(command: string): Promise<string> {
 export async function installDocs(): Promise<{ success: boolean; error?: string }> {
   try {
     const docsDir = path.join(os.homedir(), '.prjct-cli', 'docs')
-    const templateDocsDir = path.join(getPackageRoot(), 'templates/global/docs')
+    const templateDocsDir = path.join(PACKAGE_ROOT, 'templates/global/docs')
 
     // Ensure docs directory exists
     await fs.mkdir(docsDir, { recursive: true })
@@ -177,12 +177,7 @@ export async function installGlobalConfig(): Promise<GlobalConfigResult> {
     await fs.mkdir(activeProvider.configDir, { recursive: true })
 
     const globalConfigPath = path.join(activeProvider.configDir, activeProvider.contextFile)
-    const templatePath = path.join(
-      getPackageRoot(),
-      'templates',
-      'global',
-      activeProvider.contextFile
-    )
+    const templatePath = path.join(PACKAGE_ROOT, 'templates', 'global', activeProvider.contextFile)
 
     // Read template content - use modular composition (PRJ-94)
     let templateContent = ''
@@ -196,12 +191,12 @@ export async function installGlobalConfig(): Promise<GlobalConfigResult> {
           templateContent = await composeGlobalTemplate('standard')
         } catch {
           // Final fallback to legacy template
-          const fallbackTemplatePath = path.join(getPackageRoot(), 'templates/global/CLAUDE.md')
+          const fallbackTemplatePath = path.join(PACKAGE_ROOT, 'templates/global/CLAUDE.md')
           templateContent = await fs.readFile(fallbackTemplatePath, 'utf-8')
         }
       } else {
         // Fallback for other providers
-        const fallbackTemplatePath = path.join(getPackageRoot(), 'templates/global/CLAUDE.md')
+        const fallbackTemplatePath = path.join(PACKAGE_ROOT, 'templates/global/CLAUDE.md')
         templateContent = await fs.readFile(fallbackTemplatePath, 'utf-8')
         // If it is Gemini, we should rename Claude to Gemini in the fallback content
         if (providerName === 'gemini') {
@@ -296,7 +291,7 @@ export class CommandInstaller {
 
   constructor() {
     this.homeDir = os.homedir()
-    this.templatesDir = path.join(getPackageRoot(), 'templates', 'commands')
+    this.templatesDir = path.join(PACKAGE_ROOT, 'templates', 'commands')
   }
 
   private async ensureInit(): Promise<void> {

package/core/infrastructure/setup.ts

@@ -28,7 +28,7 @@ import { getErrorMessage, isNotFoundError } from '../types/fs'
 import type { AIProviderConfig, AIProviderName } from '../types/provider'
 import { fileExists } from '../utils/fs-helpers'
 import log from '../utils/logger'
-import { getPackageRoot, VERSION } from '../utils/version'
+import { PACKAGE_ROOT, VERSION } from '../utils/version'
 import {
   detectAllProviders,
   detectAntigravity,
@@ -255,7 +255,7 @@ export async function run(): Promise<SetupResults> {
 async function installGeminiRouter(): Promise<boolean> {
   try {
     const geminiCommandsDir = path.join(os.homedir(), '.gemini', 'commands')
-    const routerSource = path.join(getPackageRoot(), 'templates', 'commands', 'p.toml')
+    const routerSource = path.join(PACKAGE_ROOT, 'templates', 'commands', 'p.toml')
     const routerDest = path.join(geminiCommandsDir, 'p.toml')
 
     // Ensure commands directory exists
@@ -280,7 +280,7 @@ async function installGeminiGlobalConfig(): Promise<{ success: boolean; action:
   try {
     const geminiDir = path.join(os.homedir(), '.gemini')
     const globalConfigPath = path.join(geminiDir, 'GEMINI.md')
-    const templatePath = path.join(getPackageRoot(), 'templates', 'global', 'GEMINI.md')
+    const templatePath = path.join(PACKAGE_ROOT, 'templates', 'global', 'GEMINI.md')
 
     // Ensure ~/.gemini directory exists
     await fs.mkdir(geminiDir, { recursive: true })
@@ -361,7 +361,7 @@ export async function installAntigravitySkill(): Promise<{
     const antigravitySkillsDir = path.join(os.homedir(), '.gemini', 'antigravity', 'skills')
     const prjctSkillDir = path.join(antigravitySkillsDir, 'prjct')
     const skillMdPath = path.join(prjctSkillDir, 'SKILL.md')
-    const templatePath = path.join(getPackageRoot(), 'templates', 'antigravity', 'SKILL.md')
+    const templatePath = path.join(PACKAGE_ROOT, 'templates', 'antigravity', 'SKILL.md')
 
     // Ensure skills directory exists
     await fs.mkdir(prjctSkillDir, { recursive: true })
@@ -431,8 +431,8 @@ export async function installCursorProject(projectRoot: string): Promise<{
 
     const routerMdcDest = path.join(rulesDir, 'prjct.mdc')
 
-    const routerMdcSource = path.join(getPackageRoot(), 'templates', 'cursor', 'router.mdc')
-    const cursorCommandsSource = path.join(getPackageRoot(), 'templates', 'cursor', 'commands')
+    const routerMdcSource = path.join(PACKAGE_ROOT, 'templates', 'cursor', 'router.mdc')
+    const cursorCommandsSource = path.join(PACKAGE_ROOT, 'templates', 'cursor', 'commands')
 
     // Ensure directories exist
     await fs.mkdir(rulesDir, { recursive: true })
@@ -574,13 +574,8 @@ export async function installWindsurfProject(projectRoot: string): Promise<{
 
     const routerDest = path.join(rulesDir, 'prjct.md')
 
-    const routerSource = path.join(getPackageRoot(), 'templates', 'windsurf', 'router.md')
-    const windsurfWorkflowsSource = path.join(
-      getPackageRoot(),
-      'templates',
-      'windsurf',
-      'workflows'
-    )
+    const routerSource = path.join(PACKAGE_ROOT, 'templates', 'windsurf', 'router.md')
+    const windsurfWorkflowsSource = path.join(PACKAGE_ROOT, 'templates', 'windsurf', 'workflows')
 
     // Ensure directories exist
     await fs.mkdir(rulesDir, { recursive: true })
@@ -785,7 +780,7 @@ async function installStatusLine(): Promise<void> {
     const prjctConfigPath = path.join(prjctStatusLineDir, 'config.json')
 
     // Source assets (from the package)
-    const assetsDir = path.join(getPackageRoot(), 'assets', 'statusline')
+    const assetsDir = path.join(PACKAGE_ROOT, 'assets', 'statusline')
     const sourceScript = path.join(assetsDir, 'statusline.sh')
     const sourceThemeDir = path.join(assetsDir, 'themes')
     const sourceLibDir = path.join(assetsDir, 'lib')

package/core/utils/provider-cache.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import type { ProviderDetectionResult } from '../types/provider'
+
+const CACHE_DIR = path.join(os.homedir(), '.prjct-cli', 'cache')
+const CACHE_FILE = path.join(CACHE_DIR, 'providers.json')
+const TTL_MS = 10 * 60 * 1000 // 10 minutes
+
+interface ProviderCache {
+  timestamp: string
+  detection: {
+    claude: ProviderDetectionResult
+    gemini: ProviderDetectionResult
+  }
+}
+
+export async function readProviderCache(): Promise<ProviderCache['detection'] | null> {
+  try {
+    const raw = await fs.readFile(CACHE_FILE, 'utf-8')
+    const cache: ProviderCache = JSON.parse(raw)
+
+    if (!cache.timestamp || !cache.detection) return null
+
+    const age = Date.now() - new Date(cache.timestamp).getTime()
+    if (age > TTL_MS) return null
+
+    return cache.detection
+  } catch {
+    return null
+  }
+}
+
+export async function writeProviderCache(detection: ProviderCache['detection']): Promise<void> {
+  const cache: ProviderCache = {
+    timestamp: new Date().toISOString(),
+    detection,
+  }
+  await fs.mkdir(CACHE_DIR, { recursive: true })
+  await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2))
+}
+
+export async function invalidateProviderCache(): Promise<void> {
+  try {
+    await fs.unlink(CACHE_FILE)
+  } catch {
+    // File doesn't exist — fine
+  }
+}

package/core/utils/version.ts

@@ -7,6 +7,9 @@ import { getErrorMessage } from '../types/fs'
  *
  * Reads version from package.json dynamically to ensure consistency
  * across the entire application.
+ *
+ * Uses sync I/O intentionally: runs once at cold start, results cached.
+ * CJS build (postinstall) requires sync module-level exports.
  */
 
 interface PackageJson {