prjct-cli 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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

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,7 @@ 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'
@@ -91,15 +92,28 @@ async function installAICLI(provider: AIProviderConfig): Promise<boolean> {
   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) {
-    console.log(
-      `${YELLOW}⚠️  Failed to install ${provider.displayName}: ${(error as Error).message}${NC}`
-    )
+    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}`)

package/core/services/git-analyzer.ts

@@ -12,6 +12,7 @@
 
 import { exec } from 'node:child_process'
 import { promisify } from 'node:util'
+import { getTimeout } from '../constants'
 import { dependencyValidator } from './dependency-validator'
 
 const execAsync = promisify(exec)
@@ -99,6 +100,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync('git branch --show-current', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       return stdout.trim() || 'main'
     } catch {
@@ -113,6 +115,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync('git rev-list --count HEAD', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       return parseInt(stdout.trim(), 10) || 0
     } catch {
@@ -128,6 +131,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync('git shortlog -sn --all', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       // Count non-empty lines instead of piping to wc -l
       const lines = stdout.trim().split('\n').filter(Boolean)
@@ -156,6 +160,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync('git status --porcelain', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       const lines = stdout.trim().split('\n').filter(Boolean)
       result.hasChanges = lines.length > 0
@@ -188,7 +193,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync(
         `git log --oneline -${count} --pretty=format:"%h|%s|%ad" --date=short`,
-        { cwd: this.projectPath }
+        { cwd: this.projectPath, timeout: getTimeout('GIT_OPERATION') }
       )
 
       return stdout
@@ -211,6 +216,7 @@ export class GitAnalyzer {
     try {
       const { stdout } = await execAsync('git log --oneline --since="1 week ago"', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       // Count non-empty lines instead of piping to wc -l
       const lines = stdout.trim().split('\n').filter(Boolean)
@@ -227,6 +233,7 @@ export class GitAnalyzer {
     try {
       await execAsync('git rev-parse --is-inside-work-tree', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       return true
     } catch {
@@ -243,6 +250,7 @@ export class GitAnalyzer {
       // Try to get from remote
       const { stdout } = await execAsync('git symbolic-ref refs/remotes/origin/HEAD', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       // Use JS replace instead of piping to sed
       const branch = stdout.trim().replace(/^refs\/remotes\/origin\//, '')
@@ -255,6 +263,7 @@ export class GitAnalyzer {
     try {
       await execAsync('git show-ref --verify --quiet refs/heads/main', {
         cwd: this.projectPath,
+        timeout: getTimeout('GIT_OPERATION'),
       })
       return 'main'
     } catch {

package/core/services/skill-installer.ts

@@ -20,6 +20,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import { glob } from 'glob'
+import { getTimeout } from '../constants'
 import { dependencyValidator } from './dependency-validator'
 import type { SkillLockEntry } from './skill-lock'
 import { skillLock } from './skill-lock'
@@ -252,13 +253,17 @@ async function installFromGitHub(source: ParsedSource): Promise<InstallResult> {
 
   try {
     // Clone with depth 1 for speed
+    // PRJ-111: Configurable timeout (default: 60s, override via PRJCT_TIMEOUT_GIT_CLONE)
     const cloneUrl = `https://github.com/${source.owner}/${source.repo}.git`
-    await exec(`git clone --depth 1 ${cloneUrl} ${tmpDir}`, { timeout: 60_000 })
+    await exec(`git clone --depth 1 ${cloneUrl} ${tmpDir}`, { timeout: getTimeout('GIT_CLONE') })
 
     // Get the commit SHA
     let sha: string | undefined
     try {
-      const { stdout } = await exec('git rev-parse HEAD', { cwd: tmpDir, timeout: 5_000 })
+      const { stdout } = await exec('git rev-parse HEAD', {
+        cwd: tmpDir,
+        timeout: getTimeout('TOOL_CHECK'),
+      })
       sha = stdout.trim()
     } catch {
       // Non-critical

package/core/sync/sync-client.ts

@@ -3,8 +3,11 @@
  *
  * Handles communication with the backend API for push/pull operations.
  * Uses native fetch API (available in Node 18+ and Bun).
+ *
+ * PRJ-111: Includes configurable timeout support via AbortController.
  */
 
+import { getTimeout } from '../constants'
 import type { SyncEvent } from '../events'
 import type { SyncBatchResult, SyncClientError, SyncPullResult, SyncStatus } from '../types'
 import authConfig from './auth-config'
@@ -114,10 +117,15 @@ class SyncClient {
    * Test connection to the API
    */
   async testConnection(): Promise<boolean> {
+    // PRJ-111: Add timeout to connection test
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), getTimeout('API_REQUEST'))
+
     try {
       const { apiUrl, apiKey } = await this.getAuthHeaders()
 
       if (!apiKey) {
+        clearTimeout(timeoutId)
         return false
       }
 
@@ -126,11 +134,14 @@ class SyncClient {
         headers: {
           'X-Api-Key': apiKey,
         },
+        signal: controller.signal,
       })
 
+      clearTimeout(timeoutId)
       return response.ok
     } catch (_error) {
-      // Network error or other issue - expected
+      // Network error, timeout, or other issue - expected
+      clearTimeout(timeoutId)
       return false
     }
   }
@@ -156,8 +167,17 @@ class SyncClient {
     options: RequestInit,
     retryCount = 0
   ): Promise<Response> {
+    // PRJ-111: Add AbortController-based timeout (default: 30s, configurable via PRJCT_TIMEOUT_API_REQUEST)
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), getTimeout('API_REQUEST'))
+
     try {
-      const response = await fetch(url, options)
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      })
+
+      clearTimeout(timeoutId)
 
       // Retry on server errors (5xx) but not client errors (4xx)
       if (response.status >= 500 && retryCount < this.retryConfig.maxRetries) {
@@ -171,6 +191,16 @@ class SyncClient {
 
       return response
     } catch (error) {
+      clearTimeout(timeoutId)
+
+      // Check if this is a timeout (AbortError)
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw this.createError(
+          'NETWORK_ERROR',
+          `Request timed out. Try increasing PRJCT_TIMEOUT_API_REQUEST (current: ${getTimeout('API_REQUEST')}ms)`
+        )
+      }
+
       // Retry on network errors
       if (retryCount < this.retryConfig.maxRetries) {
         const delay = Math.min(

package/dist/bin/prjct.mjs

@@ -11952,7 +11952,18 @@ var init_orchestrator_executor = __esm({
 });
 
 // core/constants/index.ts
-var PLAN_STATUS, PLAN_REQUIRED_COMMANDS, DESTRUCTIVE_COMMANDS, PLANNING_TOOLS;
+function getTimeout(key) {
+  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];
+}
+var PLAN_STATUS, PLAN_REQUIRED_COMMANDS, DESTRUCTIVE_COMMANDS, PLANNING_TOOLS, TIMEOUTS;
 var init_constants = __esm({
   "core/constants/index.ts"() {
     "use strict";
@@ -11997,6 +12008,21 @@ var init_constants = __esm({
       "GetDate",
       "GetDateTime"
     ];
+    TIMEOUTS = {
+      /** Tool availability checks (git --version, npm --version) */
+      TOOL_CHECK: 5e3,
+      /** Standard git operations (status, add, commit) */
+      GIT_OPERATION: 1e4,
+      /** Git clone with --depth 1 */
+      GIT_CLONE: 6e4,
+      /** HTTP fetch/API requests */
+      API_REQUEST: 3e4,
+      /** npm install -g (CLI installation) - 2 minutes */
+      NPM_INSTALL: 12e4,
+      /** User-defined workflow hooks */
+      WORKFLOW_HOOK: 6e4
+    };
+    __name(getTimeout, "getTimeout");
   }
 });
 
@@ -15844,6 +15870,7 @@ var execAsync2;
 var init_git_analyzer = __esm({
   "core/services/git-analyzer.ts"() {
     "use strict";
+    init_constants();
     init_dependency_validator();
     execAsync2 = promisify6(exec6);
   }
@@ -22747,15 +22774,26 @@ async function installAICLI(provider) {
   try {
     console.log(`${YELLOW4}\u{1F4E6} ${provider.displayName} not found. Installing...${NC}`);
     console.log("");
-    execSync7(`npm install -g ${packageName}`, { stdio: "inherit" });
+    execSync7(`npm install -g ${packageName}`, {
+      stdio: "inherit",
+      timeout: getTimeout("NPM_INSTALL")
+    });
     console.log("");
     console.log(`${GREEN4}\u2713${NC} ${provider.displayName} installed successfully`);
     console.log("");
     return true;
   } catch (error) {
-    console.log(
-      `${YELLOW4}\u26A0\uFE0F  Failed to install ${provider.displayName}: ${error.message}${NC}`
-    );
+    const err = error;
+    const isTimeout = err.killed && err.signal === "SIGTERM";
+    if (isTimeout) {
+      console.log(`${YELLOW4}\u26A0\uFE0F  Installation timed out for ${provider.displayName}${NC}`);
+      console.log("");
+      console.log(`${DIM4}The npm install took too long. Try:${NC}`);
+      console.log(`${DIM4}  \u2022 Set PRJCT_TIMEOUT_NPM_INSTALL=300000 for 5 minutes${NC}`);
+      console.log(`${DIM4}  \u2022 Run manually: npm install -g ${packageName}${NC}`);
+    } else {
+      console.log(`${YELLOW4}\u26A0\uFE0F  Failed to install ${provider.displayName}: ${err.message}${NC}`);
+    }
     console.log("");
     console.log(`${DIM4}Alternative installation methods:${NC}`);
     console.log(`${DIM4}  \u2022 npm:  npm install -g ${packageName}${NC}`);
@@ -23374,6 +23412,7 @@ var GREEN4, YELLOW4, DIM4, NC, setup_default, isDirectRun;
 var init_setup = __esm({
   "core/infrastructure/setup.ts"() {
     "use strict";
+    init_constants();
     init_dependency_validator();
     init_fs();
     init_version();
@@ -26798,7 +26837,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.62.0",
+      version: "0.63.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/dist/core/infrastructure/setup.js

@@ -409,6 +409,34 @@ var import_node_fs3 = __toESM(require("node:fs"));
 var import_node_os4 = __toESM(require("node:os"));
 var import_node_path5 = __toESM(require("node:path"));
 
+// core/constants/index.ts
+var TIMEOUTS = {
+  /** Tool availability checks (git --version, npm --version) */
+  TOOL_CHECK: 5e3,
+  /** Standard git operations (status, add, commit) */
+  GIT_OPERATION: 1e4,
+  /** Git clone with --depth 1 */
+  GIT_CLONE: 6e4,
+  /** HTTP fetch/API requests */
+  API_REQUEST: 3e4,
+  /** npm install -g (CLI installation) - 2 minutes */
+  NPM_INSTALL: 12e4,
+  /** User-defined workflow hooks */
+  WORKFLOW_HOOK: 6e4
+};
+function getTimeout(key) {
+  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];
+}
+__name(getTimeout, "getTimeout");
+
 // core/services/dependency-validator.ts
 var import_node_child_process = require("node:child_process");
 
@@ -1382,15 +1410,26 @@ async function installAICLI(provider) {
   try {
     console.log(`${YELLOW}\u{1F4E6} ${provider.displayName} not found. Installing...${NC}`);
     console.log("");
-    (0, import_node_child_process3.execSync)(`npm install -g ${packageName}`, { stdio: "inherit" });
+    (0, import_node_child_process3.execSync)(`npm install -g ${packageName}`, {
+      stdio: "inherit",
+      timeout: getTimeout("NPM_INSTALL")
+    });
     console.log("");
     console.log(`${GREEN}\u2713${NC} ${provider.displayName} installed successfully`);
     console.log("");
     return true;
   } catch (error) {
-    console.log(
-      `${YELLOW}\u26A0\uFE0F  Failed to install ${provider.displayName}: ${error.message}${NC}`
-    );
+    const err = error;
+    const isTimeout = err.killed && err.signal === "SIGTERM";
+    if (isTimeout) {
+      console.log(`${YELLOW}\u26A0\uFE0F  Installation timed out for ${provider.displayName}${NC}`);
+      console.log("");
+      console.log(`${DIM}The npm install took too long. Try:${NC}`);
+      console.log(`${DIM}  \u2022 Set PRJCT_TIMEOUT_NPM_INSTALL=300000 for 5 minutes${NC}`);
+      console.log(`${DIM}  \u2022 Run manually: npm install -g ${packageName}${NC}`);
+    } else {
+      console.log(`${YELLOW}\u26A0\uFE0F  Failed to install ${provider.displayName}: ${err.message}${NC}`);
+    }
     console.log("");
     console.log(`${DIM}Alternative installation methods:${NC}`);
     console.log(`${DIM}  \u2022 npm:  npm install -g ${packageName}${NC}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {