prjct-cli 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## [0.63.0] - 2026-02-05
+
+### Features
+
+- add timeout management with configurable limits (PRJ-111) (#104)
+
+
+## [0.62.1] - 2026-02-05
+
+### Improved
+
+- **Timeout management (PRJ-111)**: Operations now timeout gracefully with configurable limits instead of hanging indefinitely
+
+### Implementation Details
+
+Added `TIMEOUTS` constants with `getTimeout()` helper function supporting environment variable overrides (`PRJCT_TIMEOUT_*`). Applied timeouts to: npm install (120s), git operations (10s), git clone (60s), and fetch API calls (30s via AbortController). Timeout errors now include helpful hints for increasing limits.
+
+### Learnings
+
+- AbortController is the standard way to timeout fetch() calls - create controller, set timeout to call abort(), pass signal to fetch
+- Environment variable pattern `PRJCT_TIMEOUT_*` allows user configurability without config files
+
+### Test Plan
+
+#### For QA
+1. Set `PRJCT_TIMEOUT_GIT_OPERATION=100` (100ms) and run `prjct sync` - should timeout
+2. Unset env var, run `prjct sync` on a large repo - should complete within 10s
+3. Test npm install timeout with `PRJCT_TIMEOUT_NPM_INSTALL=1000` (1s) - should timeout with helpful message
+
+#### For Users
+- Operations now timeout gracefully instead of hanging indefinitely
+- Set `PRJCT_TIMEOUT_*` env vars to customize timeouts (e.g., `export PRJCT_TIMEOUT_API_REQUEST=60000` for 60s)
+- No breaking changes
+
+
+## [0.62.0] - 2026-02-05
+
+### Features
+
+- implement graceful degradation for missing dependencies (PRJ-114) (#103)
+
+
+## [0.62.0] - 2026-02-05
+
+### Improved
+
+- **Graceful degradation (PRJ-114)**: prjct now handles missing dependencies with helpful recovery hints instead of crashing
+
+### Implementation Details
+
+Created `DependencyValidator` service with `checkTool()`, `ensureTool()`, and caching. Integrated into GitAnalyzer, SkillInstaller, and setup.ts. Replaced shell pipes (`wc -l`, `sed`) with JS string operations for cross-platform compatibility. Added alternative installation suggestions (yarn, pnpm, brew) when npm fails.
+
+### Learnings
+
+- Shell pipes like `wc -l` and `sed` aren't cross-platform - use JS string operations instead
+- execSync calls are expensive - cache results with TTL
+- npm may not be available even when node is - check separately
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on a machine without git - verify helpful error message instead of crash
+2. Run `prjct skill install owner/repo` without git - verify error suggests install methods
+3. Run `prjct start` without npm - verify suggests alternatives (yarn, pnpm, brew)
+4. Run `prjct doctor` - verify all tool checks display correctly
+
+#### For Users
+- prjct now gracefully handles missing dependencies with helpful recovery hints
+- Automatic - errors include installation suggestions
+- No breaking changes
+
+
 ## [0.61.0] - 2026-02-05
 
 ### Features

package/core/__tests__/services/dependency-validator.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Dependency Validator Tests
+ * Tests for graceful degradation when system dependencies are missing
+ *
+ * @see PRJ-114
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { DependencyError, dependencyValidator, TOOLS } from '../../services/dependency-validator'
+
+describe('DependencyValidator', () => {
+  beforeEach(() => {
+    // Clear cache before each test
+    dependencyValidator.clearCache()
+  })
+
+  describe('checkTool', () => {
+    it('should return available: true for installed tools (git)', () => {
+      const result = dependencyValidator.checkTool('git')
+      expect(result.available).toBe(true)
+      expect(result.version).toBeDefined()
+    })
+
+    it('should return available: true for installed tools (node)', () => {
+      const result = dependencyValidator.checkTool('node')
+      expect(result.available).toBe(true)
+      expect(result.version).toBeDefined()
+    })
+
+    it('should return available: false for non-existent tools', () => {
+      const result = dependencyValidator.checkTool('definitely-not-a-real-tool-xyz123')
+      expect(result.available).toBe(false)
+      expect(result.error).toBeDefined()
+      expect(result.error?.message).toContain('not installed')
+    })
+
+    it('should cache results', () => {
+      const result1 = dependencyValidator.checkTool('git')
+      const result2 = dependencyValidator.checkTool('git')
+      // Same object reference means cached
+      expect(result1).toBe(result2)
+    })
+  })
+
+  describe('isAvailable', () => {
+    it('should return true for available tools', () => {
+      expect(dependencyValidator.isAvailable('git')).toBe(true)
+      expect(dependencyValidator.isAvailable('node')).toBe(true)
+    })
+
+    it('should return false for unavailable tools', () => {
+      expect(dependencyValidator.isAvailable('fake-tool-abc')).toBe(false)
+    })
+  })
+
+  describe('getVersion', () => {
+    it('should return version string for available tools', () => {
+      const version = dependencyValidator.getVersion('git')
+      expect(version).toBeDefined()
+      expect(typeof version).toBe('string')
+      // Git version is like "2.39.0" or similar
+      expect(version).toMatch(/^\d+\.\d+/)
+    })
+
+    it('should return undefined for unavailable tools', () => {
+      const version = dependencyValidator.getVersion('fake-tool-xyz')
+      expect(version).toBeUndefined()
+    })
+  })
+
+  describe('ensureTool', () => {
+    it('should not throw for available tools', () => {
+      expect(() => dependencyValidator.ensureTool('git')).not.toThrow()
+      expect(() => dependencyValidator.ensureTool('node')).not.toThrow()
+    })
+
+    it('should throw DependencyError for unavailable tools', () => {
+      expect(() => dependencyValidator.ensureTool('fake-tool-xyz')).toThrow(DependencyError)
+    })
+
+    it('should include helpful hint in error', () => {
+      try {
+        dependencyValidator.ensureTool('fake-tool-xyz')
+      } catch (error) {
+        expect(error).toBeInstanceOf(DependencyError)
+        expect((error as DependencyError).hint).toBeDefined()
+      }
+    })
+  })
+
+  describe('ensureTools', () => {
+    it('should not throw when all tools are available', () => {
+      expect(() => dependencyValidator.ensureTools(['git', 'node'])).not.toThrow()
+    })
+
+    it('should throw when any tool is unavailable', () => {
+      expect(() => dependencyValidator.ensureTools(['git', 'fake-tool-xyz'])).toThrow(
+        DependencyError
+      )
+    })
+
+    it('should list all missing tools in error', () => {
+      try {
+        dependencyValidator.ensureTools(['fake-tool-1', 'fake-tool-2'])
+      } catch (error) {
+        expect(error).toBeInstanceOf(DependencyError)
+        expect((error as DependencyError).message).toContain('fake-tool-1')
+        expect((error as DependencyError).message).toContain('fake-tool-2')
+      }
+    })
+  })
+
+  describe('checkAll', () => {
+    it('should return status for all default tools', () => {
+      const results = dependencyValidator.checkAll()
+      expect(results.size).toBeGreaterThan(0)
+      expect(results.has('git')).toBe(true)
+      expect(results.has('node')).toBe(true)
+    })
+
+    it('should return status for specified tools', () => {
+      const results = dependencyValidator.checkAll(['git', 'node'])
+      expect(results.size).toBe(2)
+      expect(results.get('git')?.available).toBe(true)
+      expect(results.get('node')?.available).toBe(true)
+    })
+  })
+
+  describe('clearCache', () => {
+    it('should clear cached results', () => {
+      const result1 = dependencyValidator.checkTool('git')
+      dependencyValidator.clearCache()
+      const result2 = dependencyValidator.checkTool('git')
+      // Different object reference after cache clear
+      expect(result1).not.toBe(result2)
+    })
+  })
+
+  describe('TOOLS definitions', () => {
+    it('should have required tools marked as required', () => {
+      expect(TOOLS.git.required).toBe(true)
+      expect(TOOLS.node.required).toBe(true)
+    })
+
+    it('should have optional tools marked as not required', () => {
+      expect(TOOLS.bun.required).toBe(false)
+      expect(TOOLS.gh.required).toBe(false)
+    })
+
+    it('should have install hints for all tools', () => {
+      for (const tool of Object.values(TOOLS)) {
+        expect(tool.installHint).toBeDefined()
+        expect(tool.installHint.length).toBeGreaterThan(0)
+      }
+    })
+  })
+
+  describe('DependencyError', () => {
+    it('should have correct name', () => {
+      const error = new DependencyError({ message: 'test' })
+      expect(error.name).toBe('DependencyError')
+    })
+
+    it('should preserve hint and docs', () => {
+      const error = new DependencyError({
+        message: 'Tool not found',
+        hint: 'Install it',
+        docs: 'https://example.com',
+      })
+      expect(error.message).toBe('Tool not found')
+      expect(error.hint).toBe('Install it')
+      expect(error.docs).toBe('https://example.com')
+    })
+  })
+})

package/core/constants/index.ts

@@ -218,6 +218,52 @@ export const PLANNING_TOOLS = [
   'GetDateTime',
 ] as const
 
+// =============================================================================
+// Timeout Constants (PRJ-111)
+// =============================================================================
+
+/**
+ * Timeout values in milliseconds for various operations.
+ * Can be overridden via PRJCT_TIMEOUT_* environment variables.
+ */
+export const TIMEOUTS = {
+  /** Tool availability checks (git --version, npm --version) */
+  TOOL_CHECK: 5_000,
+
+  /** Standard git operations (status, add, commit) */
+  GIT_OPERATION: 10_000,
+
+  /** Git clone with --depth 1 */
+  GIT_CLONE: 60_000,
+
+  /** HTTP fetch/API requests */
+  API_REQUEST: 30_000,
+
+  /** npm install -g (CLI installation) - 2 minutes */
+  NPM_INSTALL: 120_000,
+
+  /** User-defined workflow hooks */
+  WORKFLOW_HOOK: 60_000,
+} as const
+
+export type TimeoutKey = keyof typeof TIMEOUTS
+
+/**
+ * Get timeout value with optional environment variable override.
+ * Environment variables: PRJCT_TIMEOUT_TOOL_CHECK, PRJCT_TIMEOUT_GIT_OPERATION, etc.
+ */
+export function getTimeout(key: TimeoutKey): number {
+  const envVar = `PRJCT_TIMEOUT_${key}`
+  const envValue = process.env[envVar]
+  if (envValue) {
+    const parsed = Number.parseInt(envValue, 10)
+    if (!Number.isNaN(parsed) && parsed > 0) {
+      return parsed
+    }
+  }
+  return TIMEOUTS[key]
+}
+
 // =============================================================================
 // Combined Exports
 // =============================================================================
@@ -245,3 +291,11 @@ export const PLAN = {
   DESTRUCTIVE_COMMANDS,
   TOOLS: PLANNING_TOOLS,
 } as const
+
+/**
+ * Combined timeout exports for easy import.
+ */
+export const TIMEOUT = {
+  VALUES: TIMEOUTS,
+  get: getTimeout,
+} as const

package/core/infrastructure/setup.ts

@@ -21,6 +21,8 @@ import { execSync } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { getTimeout } from '../constants'
+import { dependencyValidator } from '../services/dependency-validator'
 import { isNotFoundError } from '../types/fs'
 import type { AIProviderConfig, AIProviderName } from '../types/provider'
 import { getPackageRoot, VERSION } from '../utils/version'
@@ -67,24 +69,59 @@ async function _hasAICLI(provider: AIProviderConfig): Promise<boolean> {
 
 /**
  * Install AI CLI for the specified provider
+ * PRJ-114: Enhanced with graceful degradation and alternative install suggestions
  */
 async function installAICLI(provider: AIProviderConfig): Promise<boolean> {
   const packageName =
     provider.name === 'claude' ? '@anthropic-ai/claude-code' : '@google/gemini-cli'
 
+  // PRJ-114: Check npm availability first
+  if (!dependencyValidator.isAvailable('npm')) {
+    console.log(`${YELLOW}⚠️  npm is not available${NC}`)
+    console.log('')
+    console.log(`${DIM}Install ${provider.displayName} using one of:${NC}`)
+    console.log(`${DIM}  • Install Node.js: https://nodejs.org${NC}`)
+    console.log(
+      `${DIM}  • Use Homebrew: brew install ${provider.name === 'claude' ? 'claude' : 'gemini'}${NC}`
+    )
+    console.log(`${DIM}  • Use npx directly: npx ${packageName}${NC}`)
+    console.log('')
+    return false
+  }
+
   try {
     console.log(`${YELLOW}📦 ${provider.displayName} not found. Installing...${NC}`)
     console.log('')
-    execSync(`npm install -g ${packageName}`, { stdio: 'inherit' })
+    // PRJ-111: Add timeout to npm install (default: 2 minutes, configurable via PRJCT_TIMEOUT_NPM_INSTALL)
+    execSync(`npm install -g ${packageName}`, {
+      stdio: 'inherit',
+      timeout: getTimeout('NPM_INSTALL'),
+    })
     console.log('')
     console.log(`${GREEN}✓${NC} ${provider.displayName} installed successfully`)
     console.log('')
     return true
   } catch (error) {
+    const err = error as Error & { killed?: boolean; signal?: string }
+    const isTimeout = err.killed && err.signal === 'SIGTERM'
+
+    if (isTimeout) {
+      console.log(`${YELLOW}⚠️  Installation timed out for ${provider.displayName}${NC}`)
+      console.log('')
+      console.log(`${DIM}The npm install took too long. Try:${NC}`)
+      console.log(`${DIM}  • Set PRJCT_TIMEOUT_NPM_INSTALL=300000 for 5 minutes${NC}`)
+      console.log(`${DIM}  • Run manually: npm install -g ${packageName}${NC}`)
+    } else {
+      console.log(`${YELLOW}⚠️  Failed to install ${provider.displayName}: ${err.message}${NC}`)
+    }
+    console.log('')
+    console.log(`${DIM}Alternative installation methods:${NC}`)
+    console.log(`${DIM}  • npm:  npm install -g ${packageName}${NC}`)
+    console.log(`${DIM}  • yarn: yarn global add ${packageName}${NC}`)
+    console.log(`${DIM}  • pnpm: pnpm add -g ${packageName}${NC}`)
     console.log(
-      `${YELLOW}⚠️  Failed to install ${provider.displayName}: ${(error as Error).message}${NC}`
+      `${DIM}  • brew: brew install ${provider.name === 'claude' ? 'claude' : 'gemini'}${NC}`
     )
-    console.log(`${DIM}Please install manually: npm install -g ${packageName}${NC}`)
     console.log('')
     return false
   }