prjct-cli 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [0.64.0] - 2026-02-05
+
+### Features
+
+- add input source tagging for context items (PRJ-102) (#106)
+
+
+## [0.63.2] - 2026-02-05
+
+### Added
+
+- **Input source tagging (PRJ-102)**: Context items now support origin tracking via `_source` metadata
+
+### Implementation Details
+
+Added `InputSource` type with 10 standardized source categories (user_explicit, user_file, system_detected, system_generated, system_inferred, learned, external, inherited, cached, unknown). Created `SourceMetadata` interface with capturedAt timestamp and optional confidence/sourcePath fields. Added `SourcedItem` base interface and `createSourceMetadata()` helper function. Extended key context interfaces (AgentInfo, FeatureInfo, PatternInfo, GatheredInfo, LoadedAgent) to support source tracking. Updated MemoryMetadata with inputSource field for consistency.
+
+### Learnings
+
+- Anthropic pattern: always track origin of all data for traceability and debugging
+- Using optional `_source` field allows backward-compatible adoption
+
+### Test Plan
+
+#### For QA
+1. Run `bun run typecheck` - passes with new types
+2. Run `bun test` - all 368 tests pass
+3. Verify `InputSource` type is exported from `core/types`
+
+#### For Users
+- Context items now support source tracking via `_source` metadata
+- Use `createSourceMetadata()` when creating context items
+- No breaking changes
+
+
+## [0.63.1] - 2026-02-05
+
+### Added
+
+- **Unit tests for smart-context.ts (PRJ-84)**: 57 tests covering domain detection, file filtering, and type mappings
+
+### Implementation Details
+
+Created comprehensive test suite for SmartContext class: `detectDomain()` tests for all 6 domains (frontend, backend, devops, docs, testing, general), `filterFiles()` tests for file pattern matching, `estimateSize()` tests for token estimation, and type mapping function tests.
+
+### Learnings
+
+- Keyword detection uses substring matching - "be" in "better" matches backend keyword
+- Frontend file pattern `/\.(tsx?|jsx?)$/` also matches plain `.ts` files (known behavior)
+- Confidence scoring caps at 0.95 regardless of keyword count
+
+### Test Plan
+
+#### For QA
+1. Run `bun test core/__tests__/agentic/smart-context.test.ts` - all 57 tests pass
+2. Run `bun test` - full suite passes (368 tests)
+
+#### For Users
+- No user-facing changes (test coverage improvement)
+
+
+## [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/__tests__/agentic/smart-context.test.ts

@@ -0,0 +1,372 @@
+/**
+ * Smart Context Tests
+ * PRJ-84: Unit tests for smart-context.ts
+ */
+
+import { describe, expect, it } from 'bun:test'
+import smartContext, { SmartContext } from '../../agentic/smart-context'
+import type { ContextDomain, TaskType } from '../../types'
+
+describe('SmartContext PRJ-84', () => {
+  describe('detectDomain', () => {
+    describe('frontend detection', () => {
+      it('should detect frontend from UI keywords', () => {
+        const result = smartContext.detectDomain('Add a new button component')
+        expect(result.primary).toBe('frontend')
+        expect(result.confidence).toBeGreaterThan(0.5)
+      })
+
+      it('should detect frontend from React keywords', () => {
+        const result = smartContext.detectDomain('Create React component for user profile')
+        expect(result.primary).toBe('frontend')
+      })
+
+      it('should detect frontend from styling keywords', () => {
+        const result = smartContext.detectDomain('Fix CSS layout for responsive design')
+        expect(result.primary).toBe('frontend')
+      })
+
+      it('should detect frontend from TSX/JSX keywords', () => {
+        const result = smartContext.detectDomain('Update tsx file for modal animation')
+        expect(result.primary).toBe('frontend')
+      })
+    })
+
+    describe('backend detection', () => {
+      it('should detect backend from API keywords', () => {
+        const result = smartContext.detectDomain('Create new API endpoint for users')
+        expect(result.primary).toBe('backend')
+        expect(result.confidence).toBeGreaterThan(0.5)
+      })
+
+      it('should detect backend from database keywords', () => {
+        const result = smartContext.detectDomain('Add database query for orders')
+        expect(result.primary).toBe('backend')
+      })
+
+      it('should detect backend from service keywords', () => {
+        const result = smartContext.detectDomain('Implement auth service handler')
+        expect(result.primary).toBe('backend')
+      })
+
+      it('should detect backend from GraphQL keywords', () => {
+        const result = smartContext.detectDomain('Add GraphQL resolver for products')
+        expect(result.primary).toBe('backend')
+      })
+    })
+
+    describe('devops detection', () => {
+      it('should detect devops from Docker keywords', () => {
+        const result = smartContext.detectDomain('Create Docker container for deployment')
+        expect(result.primary).toBe('devops')
+        expect(result.confidence).toBeGreaterThan(0.5)
+      })
+
+      it('should detect devops from Kubernetes keywords', () => {
+        const result = smartContext.detectDomain('Update k8s deployment configuration')
+        expect(result.primary).toBe('devops')
+      })
+
+      it('should detect devops from CI/CD keywords', () => {
+        const result = smartContext.detectDomain('Fix CI pipeline for build process')
+        expect(result.primary).toBe('devops')
+      })
+
+      it('should detect devops from infrastructure keywords', () => {
+        const result = smartContext.detectDomain('Configure AWS infrastructure with terraform')
+        expect(result.primary).toBe('devops')
+      })
+    })
+
+    describe('docs detection', () => {
+      it('should detect docs from documentation keywords', () => {
+        // Note: "documentation" alone triggers docs domain
+        const result = smartContext.detectDomain('Update documentation for users')
+        expect(result.primary).toBe('docs')
+        expect(result.confidence).toBeGreaterThan(0.5)
+      })
+
+      it('should detect docs from README keywords', () => {
+        const result = smartContext.detectDomain('Add readme section for installation')
+        expect(result.primary).toBe('docs')
+      })
+
+      it('should detect docs from changelog keywords', () => {
+        const result = smartContext.detectDomain('Update changelog for new release')
+        expect(result.primary).toBe('docs')
+      })
+
+      it('should detect docs from jsdoc keywords', () => {
+        const result = smartContext.detectDomain('Add jsdoc comments to functions')
+        expect(result.primary).toBe('docs')
+      })
+    })
+
+    describe('testing detection', () => {
+      it('should detect testing from test keywords', () => {
+        const result = smartContext.detectDomain('Add unit test for user service')
+        expect(result.primary).toBe('testing')
+        expect(result.confidence).toBeGreaterThan(0.5)
+      })
+
+      it('should detect testing from Jest keywords', () => {
+        const result = smartContext.detectDomain('Write jest spec for validation')
+        expect(result.primary).toBe('testing')
+      })
+
+      it('should detect testing from e2e keywords', () => {
+        const result = smartContext.detectDomain('Add e2e integration tests')
+        expect(result.primary).toBe('testing')
+      })
+
+      it('should detect testing from coverage keywords', () => {
+        const result = smartContext.detectDomain('Improve test coverage for auth module')
+        expect(result.primary).toBe('testing')
+      })
+
+      it('should detect testing from mock/fixture keywords', () => {
+        const result = smartContext.detectDomain('Create mock fixtures for API tests')
+        expect(result.primary).toBe('testing')
+      })
+    })
+
+    describe('general/fallback detection', () => {
+      it('should return general for ambiguous tasks', () => {
+        const result = smartContext.detectDomain('Refactor code')
+        expect(result.primary).toBe('general')
+        expect(result.confidence).toBe(0.5)
+      })
+
+      it('should return general for empty descriptions', () => {
+        const result = smartContext.detectDomain('')
+        expect(result.primary).toBe('general')
+      })
+
+      it('should return general for non-technical descriptions', () => {
+        // Note: "be" in "better" matches backend keyword, so use different text
+        const result = smartContext.detectDomain('Improve this somehow')
+        expect(result.primary).toBe('general')
+      })
+    })
+
+    describe('secondary domains', () => {
+      it('should detect secondary domains for mixed tasks', () => {
+        const result = smartContext.detectDomain('Add API endpoint with React frontend component')
+        expect(result.primary).toBeDefined()
+        expect(result.secondary.length).toBeGreaterThan(0)
+      })
+
+      it('should limit secondary domains to max 2', () => {
+        const result = smartContext.detectDomain(
+          'Add API endpoint with React component and Docker deploy with test coverage'
+        )
+        expect(result.secondary.length).toBeLessThanOrEqual(2)
+      })
+    })
+
+    describe('confidence scoring', () => {
+      it('should have higher confidence for strong domain signals', () => {
+        const strong = smartContext.detectDomain('Create React component with jsx tsx ui')
+        const weak = smartContext.detectDomain('Fix bug in component')
+        // Strong has multiple matching keywords, weak has fewer
+        expect(strong.confidence).toBeGreaterThanOrEqual(weak.confidence)
+      })
+
+      it('should cap confidence at 0.95', () => {
+        const result = smartContext.detectDomain(
+          'ui component react vue angular css style button form modal layout responsive animation dom html frontend jsx tsx'
+        )
+        expect(result.confidence).toBeLessThanOrEqual(0.95)
+      })
+    })
+  })
+
+  describe('filterFiles', () => {
+    const testFiles = [
+      'src/components/Button.tsx',
+      'src/components/Modal.jsx',
+      'src/api/users.ts',
+      'src/services/auth.ts',
+      'src/models/User.ts',
+      'docker/Dockerfile',
+      '.github/workflows/ci.yml',
+      'deploy/k8s/deployment.yaml',
+      'docs/README.md',
+      'docs/api.md',
+      'tests/unit/auth.test.ts',
+      '__tests__/components/Button.test.tsx',
+      'package.json',
+      'tsconfig.json',
+      'vite.config.ts',
+    ]
+
+    // Access private method via class instance
+    const smartContextInstance = new SmartContext()
+    const filterFiles = (files: string[], domain: ContextDomain) => {
+      // @ts-expect-error - accessing private method for testing
+      return smartContextInstance.filterFiles(files, domain)
+    }
+
+    describe('frontend filtering', () => {
+      it('should include component files', () => {
+        const result = filterFiles(testFiles, 'frontend')
+        expect(result).toContain('src/components/Button.tsx')
+        expect(result).toContain('src/components/Modal.jsx')
+      })
+
+      it('should include config files', () => {
+        const result = filterFiles(testFiles, 'frontend')
+        expect(result).toContain('package.json')
+        expect(result).toContain('tsconfig.json')
+      })
+
+      it('should exclude non-code files', () => {
+        const result = filterFiles(testFiles, 'frontend')
+        // Note: .ts files match frontend pattern /\.(tsx?|jsx?)$/ because tsx? = ts or tsx
+        // So backend .ts files are included - this is a known quirk
+        expect(result).not.toContain('docker/Dockerfile')
+        expect(result).not.toContain('docs/README.md')
+      })
+    })
+
+    describe('backend filtering', () => {
+      it('should include API and service files', () => {
+        const result = filterFiles(testFiles, 'backend')
+        expect(result).toContain('src/api/users.ts')
+        expect(result).toContain('src/services/auth.ts')
+        expect(result).toContain('src/models/User.ts')
+      })
+
+      it('should include config files', () => {
+        const result = filterFiles(testFiles, 'backend')
+        expect(result).toContain('package.json')
+      })
+    })
+
+    describe('devops filtering', () => {
+      it('should include Docker and CI files', () => {
+        const result = filterFiles(testFiles, 'devops')
+        expect(result).toContain('docker/Dockerfile')
+        expect(result).toContain('.github/workflows/ci.yml')
+        expect(result).toContain('deploy/k8s/deployment.yaml')
+      })
+    })
+
+    describe('docs filtering', () => {
+      it('should include markdown files', () => {
+        const result = filterFiles(testFiles, 'docs')
+        expect(result).toContain('docs/README.md')
+        expect(result).toContain('docs/api.md')
+      })
+    })
+
+    describe('testing filtering', () => {
+      it('should include test files', () => {
+        const result = filterFiles(testFiles, 'testing')
+        expect(result).toContain('tests/unit/auth.test.ts')
+        expect(result).toContain('__tests__/components/Button.test.tsx')
+      })
+    })
+
+    describe('general filtering', () => {
+      it('should return all files for general domain', () => {
+        const result = filterFiles(testFiles, 'general')
+        expect(result).toEqual(testFiles)
+      })
+    })
+  })
+
+  describe('estimateSize', () => {
+    // @ts-expect-error - accessing private method for testing
+    const estimateSize = smartContext.estimateSize.bind(smartContext)
+
+    it('should return minimum 100 for empty context', () => {
+      const result = estimateSize({})
+      expect(result).toBe(100)
+    })
+
+    it('should estimate agents at ~50 tokens each', () => {
+      const result = estimateSize({ agents: [{}, {}, {}] })
+      expect(result).toBe(150) // 3 * 50
+    })
+
+    it('should estimate roadmap items at ~50 tokens each', () => {
+      const result = estimateSize({ roadmap: [{}, {}] })
+      expect(result).toBe(100) // 2 * 50
+    })
+
+    it('should estimate patterns at ~30 tokens each', () => {
+      const result = estimateSize({ patterns: [{}, {}, {}, {}] })
+      expect(result).toBe(120) // 4 * 30
+    })
+
+    it('should estimate stack at 100 tokens', () => {
+      const result = estimateSize({ stack: {} })
+      expect(result).toBe(100)
+    })
+
+    it('should estimate files at ~10 tokens each', () => {
+      const result = estimateSize({ files: ['a', 'b', 'c', 'd', 'e'] })
+      expect(result).toBe(100) // 5 * 10 = 50, min 100
+    })
+
+    it('should estimate state at 200 tokens', () => {
+      const result = estimateSize({ state: {} })
+      expect(result).toBe(200)
+    })
+
+    it('should combine all estimates', () => {
+      const result = estimateSize({
+        agents: [{}, {}], // 100
+        roadmap: [{}], // 50
+        patterns: [{}], // 30
+        stack: {}, // 100
+        files: ['a'], // 10
+        state: {}, // 200
+      })
+      expect(result).toBe(490)
+    })
+  })
+
+  describe('taskTypeToContextDomain', () => {
+    const testCases: Array<{ input: TaskType; expected: ContextDomain }> = [
+      { input: 'frontend', expected: 'frontend' },
+      { input: 'backend', expected: 'backend' },
+      { input: 'devops', expected: 'devops' },
+      { input: 'database', expected: 'backend' },
+      { input: 'testing', expected: 'testing' },
+      { input: 'documentation', expected: 'docs' },
+      { input: 'refactoring', expected: 'general' },
+      { input: 'bugfix', expected: 'general' },
+      { input: 'feature', expected: 'general' },
+      { input: 'design', expected: 'frontend' },
+      { input: 'other', expected: 'general' },
+    ]
+
+    for (const { input, expected } of testCases) {
+      it(`should map ${input} to ${expected}`, () => {
+        expect(smartContext.taskTypeToContextDomain(input)).toBe(expected)
+      })
+    }
+  })
+
+  describe('contextDomainToTaskType (via getRecommendedContext)', () => {
+    // Test the private method indirectly through detectDomain verification
+    it('should have consistent bidirectional mapping for core domains', () => {
+      // Frontend maps to frontend
+      const frontendResult = smartContext.detectDomain('Create React component')
+      expect(frontendResult.primary).toBe('frontend')
+      expect(smartContext.taskTypeToContextDomain('frontend')).toBe('frontend')
+
+      // Backend maps to backend
+      const backendResult = smartContext.detectDomain('Add API endpoint')
+      expect(backendResult.primary).toBe('backend')
+      expect(smartContext.taskTypeToContextDomain('backend')).toBe('backend')
+
+      // Testing maps to testing
+      const testingResult = smartContext.detectDomain('Add unit test')
+      expect(testingResult.primary).toBe('testing')
+      expect(smartContext.taskTypeToContextDomain('testing')).toBe('testing')
+    })
+  })
+})

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/core/types/agentic.ts

@@ -5,6 +5,66 @@
 
 import type { CommandParams, ContextPaths } from './core'
 
+// =============================================================================
+// Input Source Types (PRJ-102)
+// =============================================================================
+
+/**
+ * Source of context data - tracks origin for traceability.
+ * Pattern from Anthropic: always track where data comes from.
+ *
+ * @see PRJ-102
+ */
+export type InputSource =
+  | 'user_explicit' // User directly provided this (e.g., task description, idea)
+  | 'user_file' // From a user-created file (e.g., PRJCT.md, custom agents)
+  | 'system_detected' // Automatically detected (e.g., stack detection, git analysis)
+  | 'system_generated' // Generated by the system (e.g., now.md, analysis)
+  | 'system_inferred' // Inferred from other data (e.g., domain detection)
+  | 'learned' // Learned from patterns/history
+  | 'external' // From external service (e.g., Linear, JIRA)
+  | 'inherited' // Inherited from parent context (monorepo)
+  | 'cached' // From cache (may be stale)
+  | 'unknown' // Source not tracked (legacy data)
+
+/**
+ * Metadata about data source and freshness.
+ */
+export interface SourceMetadata {
+  /** Where this data came from */
+  source: InputSource
+  /** When this was captured/detected */
+  capturedAt: string
+  /** Confidence in this data (0-1) */
+  confidence?: number
+  /** Path to source file if applicable */
+  sourcePath?: string
+  /** Whether this might be stale */
+  mayBeStale?: boolean
+}
+
+/**
+ * Base interface for any item with source tracking.
+ */
+export interface SourcedItem {
+  /** Metadata about where this item came from */
+  _source?: SourceMetadata
+}
+
+/**
+ * Create source metadata with current timestamp.
+ */
+export function createSourceMetadata(
+  source: InputSource,
+  options: Partial<Omit<SourceMetadata, 'source'>> = {}
+): SourceMetadata {
+  return {
+    source,
+    capturedAt: new Date().toISOString(),
+    ...options,
+  }
+}
+
 // =============================================================================
 // Tool Registry Types
 // =============================================================================
@@ -73,21 +133,21 @@ export interface FilteredContext {
   metrics: FilterMetrics
 }
 
-export interface AgentInfo {
+export interface AgentInfo extends SourcedItem {
   name: string
   domain: ContextDomain
   skills: string[]
   successRate?: number
 }
 
-export interface FeatureInfo {
+export interface FeatureInfo extends SourcedItem {
   id: string
   name: string
   relatedTo: ContextDomain[]
   status: string
 }
 
-export interface PatternInfo {
+export interface PatternInfo extends SourcedItem {
   description: string
   domain: ContextDomain
   confidence: number
@@ -211,11 +271,14 @@ export interface PlanParams extends CommandParams {
   verbose?: boolean
 }
 
-export interface GatheredInfo {
+export interface GatheredInfo extends SourcedItem {
   type: GatheredInfoType
+  /** Path or identifier of the source */
   source: string
   data: string | GatheredFileData | GatheredAnalysisData
   gatheredAt: string
+  /** Input source category for traceability */
+  inputSource?: InputSource
 }
 
 export type GatheredInfoType =
@@ -580,7 +643,7 @@ export interface LearnedPatterns {
 /**
  * A loaded agent with its content
  */
-export interface LoadedAgent {
+export interface LoadedAgent extends SourcedItem {
   name: string
   domain: string
   content: string

package/core/types/index.ts

@@ -50,6 +50,8 @@ export type {
   GroundTruthContext,
   HallucinationPattern,
   HallucinationResult,
+  // Input Source types (PRJ-102)
+  InputSource,
   LearnedPatterns,
   LearnedPatternsRecord,
   LoadedAgent,
@@ -81,6 +83,9 @@ export type {
   SimpleExecutionResult,
   SkillContext,
   SmartContextProjectState,
+  // Source tracking types (PRJ-102)
+  SourcedItem,
+  SourceMetadata,
   StackInfo,
   Template,
   ThinkBlock,
@@ -92,6 +97,7 @@ export type {
   VerificationResult,
   Verifier,
 } from './agentic'
+export { createSourceMetadata } from './agentic'
 // =============================================================================
 // Agent Types
 // =============================================================================
@@ -248,6 +254,7 @@ export type {
   Decision,
   HistoryEntry,
   HistoryEventType,
+  LegacyMemorySource,
   Memory,
   MemoryContext,
   MemoryContextParams,

package/core/types/memory.ts

@@ -3,6 +3,8 @@
  * Types for the memory system that tracks user preferences and patterns.
  */
 
+import type { InputSource } from './agentic'
+
 /**
  * Semantic tags for memory categorization.
  * Use these constants instead of raw strings.
@@ -49,6 +51,12 @@ export interface Memory {
   observationCount?: number
 }
 
+/**
+ * Legacy source type - use InputSource for new code.
+ * @deprecated Use InputSource from agentic.ts instead
+ */
+export type LegacyMemorySource = 'user' | 'system' | 'learned'
+
 /**
  * Metadata associated with a memory entry.
  */
@@ -61,8 +69,10 @@ export interface MemoryMetadata {
   taskId?: string
   /** Related feature name */
   feature?: string
-  /** Source of the memory */
-  source?: 'user' | 'system' | 'learned'
+  /** Source of the memory (legacy - use inputSource for new code) */
+  source?: LegacyMemorySource
+  /** Input source category for traceability (PRJ-102) */
+  inputSource?: InputSource
 }
 
 /**

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");
   }
 });
 
@@ -12393,6 +12419,13 @@ var init_plan_mode = __esm({
   }
 });
 
+// core/types/agentic.ts
+var init_agentic = __esm({
+  "core/types/agentic.ts"() {
+    "use strict";
+  }
+});
+
 // core/types/bus.ts
 var init_bus = __esm({
   "core/types/bus.ts"() {
@@ -12419,6 +12452,7 @@ var init_integrations = __esm({
 var init_types3 = __esm({
   "core/types/index.ts"() {
     "use strict";
+    init_agentic();
     init_bus();
     init_fs();
     init_integrations();
@@ -15844,6 +15878,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 +22782,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 +23420,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 +26845,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.62.0",
+      version: "0.64.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.64.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {