prjct-cli 0.60.2 → 0.62.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [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
+
+- add .prjct-state.md local state file for persistence (PRJ-112) (#102)
+
+
+## [0.61.0] - 2026-02-05
+
+### Features
+
+- **Local state file (PRJ-112)**: New `.prjct-state.md` file generated in project root for local persistence
+
+### Implementation Details
+
+Created `LocalStateGenerator` service that generates a markdown file showing current task state. Integrated via write-through pattern - `StateStorage.write()` now also generates the local state file. Also hooks into `sync-service.ts` for state.json updates during sync.
+
+### Learnings
+
+- Write-through pattern: JSON storage triggers MD generation automatically
+- State can be written from multiple entry points (storage class + sync service) - need hooks in both places
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on any project - verify `.prjct-state.md` is generated in project root
+2. Start a task with `p. task "test"` - verify `.prjct-state.md` updates with task info
+3. Check that subtasks, progress, and status are displayed correctly
+4. Verify the file has "DO NOT EDIT" header comment
+
+#### For Users
+- New `.prjct-state.md` file in project root shows current task state
+- Automatic - file updates whenever prjct state changes
+- No breaking changes
+
+
 ## [0.60.2] - 2026-02-05
 
 ### Performance

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/infrastructure/setup.ts

@@ -21,6 +21,7 @@ import { execSync } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+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,11 +68,26 @@ 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('')
@@ -84,7 +100,14 @@ async function installAICLI(provider: AIProviderConfig): Promise<boolean> {
     console.log(
       `${YELLOW}⚠️  Failed to install ${provider.displayName}: ${(error as Error).message}${NC}`
     )
-    console.log(`${DIM}Please install manually: npm install -g ${packageName}${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(
+      `${DIM}  • brew: brew install ${provider.name === 'claude' ? 'claude' : 'gemini'}${NC}`
+    )
     console.log('')
     return false
   }

package/core/services/dependency-validator.ts

@@ -0,0 +1,318 @@
+/**
+ * Dependency Validator
+ *
+ * Provides graceful degradation for missing system dependencies.
+ * Checks tool availability before operations and provides helpful
+ * recovery hints when tools are missing.
+ *
+ * Pattern from Google Gemini CLI: "Never assumes library availability.
+ * Checks --help before using unknown flags."
+ *
+ * @see PRJ-114
+ */
+
+import { execSync } from 'node:child_process'
+import { createError, type ErrorWithHint } from '../utils/error-messages'
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ToolDefinition {
+  name: string
+  command: string // Command to check availability (e.g., 'git --version')
+  versionRegex?: RegExp // Regex to extract version from output
+  required: boolean // If false, missing tool is a warning, not error
+  installHint: string // How to install if missing
+  docs?: string // Documentation URL
+}
+
+export interface ToolStatus {
+  available: boolean
+  version?: string
+  error?: ErrorWithHint
+}
+
+// ============================================================================
+// TOOL DEFINITIONS
+// ============================================================================
+
+/**
+ * Known tools that prjct depends on
+ */
+export const TOOLS: Record<string, ToolDefinition> = {
+  git: {
+    name: 'git',
+    command: 'git --version',
+    versionRegex: /git version ([\d.]+)/,
+    required: true,
+    installHint: 'Install Git: https://git-scm.com/downloads',
+    docs: 'https://git-scm.com/doc',
+  },
+  node: {
+    name: 'node',
+    command: 'node --version',
+    versionRegex: /v([\d.]+)/,
+    required: true,
+    installHint: 'Install Node.js: https://nodejs.org',
+    docs: 'https://nodejs.org/docs',
+  },
+  bun: {
+    name: 'bun',
+    command: 'bun --version',
+    versionRegex: /([\d.]+)/,
+    required: false,
+    installHint: 'Install Bun: curl -fsSL https://bun.sh/install | bash',
+    docs: 'https://bun.sh/docs',
+  },
+  gh: {
+    name: 'gh',
+    command: 'gh --version',
+    versionRegex: /gh version ([\d.]+)/,
+    required: false,
+    installHint: 'Install GitHub CLI: https://cli.github.com',
+    docs: 'https://cli.github.com/manual',
+  },
+  npm: {
+    name: 'npm',
+    command: 'npm --version',
+    versionRegex: /([\d.]+)/,
+    required: false,
+    installHint: 'npm comes with Node.js: https://nodejs.org',
+  },
+  claude: {
+    name: 'claude',
+    command: 'claude --version',
+    versionRegex: /claude ([\d.]+)/,
+    required: false,
+    installHint: 'Install Claude Code: npm install -g @anthropic-ai/claude-code',
+    docs: 'https://docs.anthropic.com/claude-code',
+  },
+  gemini: {
+    name: 'gemini',
+    command: 'gemini --version',
+    versionRegex: /gemini ([\d.]+)/,
+    required: false,
+    installHint: 'Install Gemini CLI: npm install -g @google/gemini-cli',
+    docs: 'https://ai.google.dev/gemini-api/docs',
+  },
+}
+
+// ============================================================================
+// DEPENDENCY VALIDATOR
+// ============================================================================
+
+class DependencyValidator {
+  private cache = new Map<string, ToolStatus>()
+  private cacheTimeout = 60_000 // 1 minute cache
+  private cacheTimestamps = new Map<string, number>()
+
+  /**
+   * Check if a tool is available
+   * Uses caching to avoid repeated execSync calls
+   */
+  checkTool(toolName: string): ToolStatus {
+    // Check cache first
+    const cached = this.getCached(toolName)
+    if (cached) return cached
+
+    const definition = TOOLS[toolName]
+    if (!definition) {
+      // Unknown tool - try to check directly
+      return this.checkUnknownTool(toolName)
+    }
+
+    const status = this.executeCheck(definition)
+    this.setCache(toolName, status)
+    return status
+  }
+
+  /**
+   * Ensure a tool is available, throw helpful error if not
+   * Use this before operations that require a specific tool
+   */
+  ensureTool(toolName: string): void {
+    const status = this.checkTool(toolName)
+
+    if (!status.available) {
+      const definition = TOOLS[toolName]
+      const error = status.error || {
+        message: `${toolName} is not available`,
+        hint: definition?.installHint || `Install ${toolName} and try again`,
+        docs: definition?.docs,
+      }
+
+      throw new DependencyError(error)
+    }
+  }
+
+  /**
+   * Ensure multiple tools are available
+   */
+  ensureTools(toolNames: string[]): void {
+    const missing: string[] = []
+
+    for (const name of toolNames) {
+      const status = this.checkTool(name)
+      if (!status.available) {
+        missing.push(name)
+      }
+    }
+
+    if (missing.length > 0) {
+      const hints = missing
+        .map((name) => {
+          const def = TOOLS[name]
+          return def ? `  ${name}: ${def.installHint}` : `  ${name}: Install and try again`
+        })
+        .join('\n')
+
+      throw new DependencyError({
+        message: `Missing required tools: ${missing.join(', ')}`,
+        hint: `Install the following:\n${hints}`,
+      })
+    }
+  }
+
+  /**
+   * Check if tool is available (boolean convenience method)
+   */
+  isAvailable(toolName: string): boolean {
+    return this.checkTool(toolName).available
+  }
+
+  /**
+   * Get tool version if available
+   */
+  getVersion(toolName: string): string | undefined {
+    return this.checkTool(toolName).version
+  }
+
+  /**
+   * Check multiple tools and return summary
+   */
+  checkAll(toolNames?: string[]): Map<string, ToolStatus> {
+    const names = toolNames || Object.keys(TOOLS)
+    const results = new Map<string, ToolStatus>()
+
+    for (const name of names) {
+      results.set(name, this.checkTool(name))
+    }
+
+    return results
+  }
+
+  /**
+   * Clear the cache (useful for tests or after installations)
+   */
+  clearCache(): void {
+    this.cache.clear()
+    this.cacheTimestamps.clear()
+  }
+
+  // ==========================================================================
+  // PRIVATE METHODS
+  // ==========================================================================
+
+  private executeCheck(definition: ToolDefinition): ToolStatus {
+    try {
+      const output = execSync(definition.command, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000, // 5 second timeout
+      })
+
+      let version: string | undefined
+      if (definition.versionRegex) {
+        const match = output.match(definition.versionRegex)
+        version = match ? match[1] : undefined
+      }
+
+      return { available: true, version }
+    } catch {
+      return {
+        available: false,
+        error: createError(
+          `${definition.name} is not installed or not in PATH`,
+          definition.installHint,
+          { docs: definition.docs }
+        ),
+      }
+    }
+  }
+
+  private checkUnknownTool(toolName: string): ToolStatus {
+    try {
+      // Try running with --version (common convention)
+      execSync(`${toolName} --version`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000,
+      })
+      return { available: true }
+    } catch {
+      // Try running with -v
+      try {
+        execSync(`${toolName} -v`, {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 5000,
+        })
+        return { available: true }
+      } catch {
+        return {
+          available: false,
+          error: createError(
+            `${toolName} is not installed or not in PATH`,
+            `Install ${toolName} and try again`
+          ),
+        }
+      }
+    }
+  }
+
+  private getCached(toolName: string): ToolStatus | null {
+    const timestamp = this.cacheTimestamps.get(toolName)
+    if (!timestamp) return null
+
+    // Check if cache is expired
+    if (Date.now() - timestamp > this.cacheTimeout) {
+      this.cache.delete(toolName)
+      this.cacheTimestamps.delete(toolName)
+      return null
+    }
+
+    return this.cache.get(toolName) || null
+  }
+
+  private setCache(toolName: string, status: ToolStatus): void {
+    this.cache.set(toolName, status)
+    this.cacheTimestamps.set(toolName, Date.now())
+  }
+}
+
+// ============================================================================
+// CUSTOM ERROR
+// ============================================================================
+
+/**
+ * Error thrown when a required dependency is missing
+ */
+export class DependencyError extends Error {
+  readonly hint?: string
+  readonly docs?: string
+
+  constructor(error: ErrorWithHint) {
+    super(error.message)
+    this.name = 'DependencyError'
+    this.hint = error.hint
+    this.docs = error.docs
+  }
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export const dependencyValidator = new DependencyValidator()
+export default dependencyValidator