prjct-cli 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.59.0] - 2026-02-05
+
+### Features
+
+- add staleness detection for CLAUDE.md context (PRJ-120) (#97)
+
+
 ## [0.58.0] - 2026-02-05
 
 ### Features

package/core/__tests__/services/staleness-checker.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Staleness Checker Tests (PRJ-120)
+ *
+ * Tests for the StalenessChecker service:
+ * - Fresh context detection
+ * - Stale context detection (commits, days, significant files)
+ * - No sync history handling
+ * - Output formatting
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import pathManager from '../../infrastructure/path-manager'
+import { createStalenessChecker, type StalenessStatus } from '../../services/staleness-checker'
+
+// =============================================================================
+// Test Setup
+// =============================================================================
+
+let tmpRoot: string | null = null
+let testProjectId: string
+const originalGetGlobalProjectPath = pathManager.getGlobalProjectPath.bind(pathManager)
+
+describe('StalenessChecker', () => {
+  beforeEach(async () => {
+    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'prjct-staleness-test-'))
+    testProjectId = 'staleness-test-project'
+
+    // Mock pathManager to use temp directory
+    pathManager.getGlobalProjectPath = (projectId: string) => {
+      return path.join(tmpRoot!, projectId)
+    }
+  })
+
+  afterEach(async () => {
+    pathManager.getGlobalProjectPath = originalGetGlobalProjectPath
+
+    if (tmpRoot) {
+      await fs.rm(tmpRoot, { recursive: true, force: true })
+      tmpRoot = null
+    }
+  })
+
+  // ===========================================================================
+  // No Sync History Tests
+  // ===========================================================================
+
+  describe('no sync history', () => {
+    it('should report stale when no project.json exists', async () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status = await checker.check(testProjectId)
+
+      expect(status.isStale).toBe(true)
+      expect(status.reason).toContain('No sync history found')
+    })
+
+    it('should report stale when no lastSyncCommit in project.json', async () => {
+      // Create project.json without lastSyncCommit
+      const projectPath = path.join(tmpRoot!, testProjectId)
+      await fs.mkdir(projectPath, { recursive: true })
+      await fs.writeFile(
+        path.join(projectPath, 'project.json'),
+        JSON.stringify({ name: 'test', lastSync: new Date().toISOString() })
+      )
+
+      const checker = createStalenessChecker(process.cwd())
+      const status = await checker.check(testProjectId)
+
+      expect(status.isStale).toBe(true)
+      expect(status.reason).toContain('No sync commit recorded')
+    })
+  })
+
+  // ===========================================================================
+  // Status Formatting Tests
+  // ===========================================================================
+
+  describe('formatStatus', () => {
+    it('should format fresh status correctly', () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status: StalenessStatus = {
+        isStale: false,
+        reason: 'Context is up to date',
+        lastSyncCommit: 'abc123',
+        currentCommit: 'abc123',
+        commitsSinceSync: 0,
+        daysSinceSync: 0,
+        changedFiles: [],
+        significantChanges: [],
+      }
+
+      const formatted = checker.formatStatus(status)
+
+      expect(formatted).toContain('✓ Fresh')
+      expect(formatted).toContain('Last sync:')
+      expect(formatted).toContain('abc123')
+      expect(formatted).not.toContain('Run `prjct sync`')
+    })
+
+    it('should format stale status with sync prompt', () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status: StalenessStatus = {
+        isStale: true,
+        reason: '15 commits since last sync (threshold: 10)',
+        lastSyncCommit: 'abc123',
+        currentCommit: 'def456',
+        commitsSinceSync: 15,
+        daysSinceSync: 2,
+        changedFiles: ['src/index.ts', 'package.json'],
+        significantChanges: ['package.json'],
+      }
+
+      const formatted = checker.formatStatus(status)
+
+      expect(formatted).toContain('⚠️  STALE')
+      expect(formatted).toContain('15')
+      expect(formatted).toContain('Significant changes')
+      expect(formatted).toContain('package.json')
+      expect(formatted).toContain('Run `prjct sync`')
+    })
+  })
+
+  // ===========================================================================
+  // Warning Message Tests
+  // ===========================================================================
+
+  describe('getWarning', () => {
+    it('should return null for fresh status', () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status: StalenessStatus = {
+        isStale: false,
+        reason: 'Context is up to date',
+        lastSyncCommit: 'abc123',
+        currentCommit: 'abc123',
+        commitsSinceSync: 0,
+        daysSinceSync: 0,
+        changedFiles: [],
+        significantChanges: [],
+      }
+
+      const warning = checker.getWarning(status)
+      expect(warning).toBeNull()
+    })
+
+    it('should return commit-based warning', () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status: StalenessStatus = {
+        isStale: true,
+        reason: '15 commits since last sync',
+        lastSyncCommit: 'abc123',
+        currentCommit: 'def456',
+        commitsSinceSync: 15,
+        daysSinceSync: 0,
+        changedFiles: [],
+        significantChanges: [],
+      }
+
+      const warning = checker.getWarning(status)
+      expect(warning).toContain('15 commits behind')
+      expect(warning).toContain('prjct sync')
+    })
+
+    it('should return days-based warning', () => {
+      const checker = createStalenessChecker(process.cwd())
+      const status: StalenessStatus = {
+        isStale: true,
+        reason: '5 days since last sync',
+        lastSyncCommit: 'abc123',
+        currentCommit: 'abc123',
+        commitsSinceSync: 0,
+        daysSinceSync: 5,
+        changedFiles: [],
+        significantChanges: [],
+      }
+
+      const warning = checker.getWarning(status)
+      expect(warning).toContain('5 days old')
+      expect(warning).toContain('prjct sync')
+    })
+  })
+
+  // ===========================================================================
+  // Configuration Tests
+  // ===========================================================================
+
+  describe('configuration', () => {
+    it('should use default thresholds', () => {
+      const checker = createStalenessChecker(process.cwd())
+      // Default commitThreshold is 10, dayThreshold is 3
+      expect(checker).toBeDefined()
+    })
+
+    it('should accept custom thresholds', () => {
+      const checker = createStalenessChecker(process.cwd(), {
+        commitThreshold: 5,
+        dayThreshold: 1,
+        significantFiles: ['custom.config.js'],
+      })
+      expect(checker).toBeDefined()
+    })
+  })
+})

package/core/__tests__/storage/storage-manager.test.ts

@@ -0,0 +1,379 @@
+/**
+ * Storage Manager Tests
+ *
+ * Tests for the base StorageManager class:
+ * - Read/write JSON operations
+ * - Missing file handling
+ * - Directory creation
+ * - Cache behavior
+ * - State consistency
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import pathManager from '../../infrastructure/path-manager'
+import { StorageManager } from '../../storage/storage-manager'
+
+// =============================================================================
+// Test Implementation
+// =============================================================================
+
+interface TestData {
+  value: string
+  count: number
+  items: string[]
+}
+
+/**
+ * Concrete implementation for testing the abstract StorageManager
+ */
+class TestStorageManager extends StorageManager<TestData> {
+  constructor() {
+    super('test-data.json')
+  }
+
+  protected getLayer(): string {
+    return 'context'
+  }
+
+  protected getDefault(): TestData {
+    return { value: '', count: 0, items: [] }
+  }
+
+  protected toMarkdown(data: TestData): string {
+    return `# Test Data\n\nValue: ${data.value}\nCount: ${data.count}\nItems: ${data.items.join(', ')}`
+  }
+
+  protected getMdFilename(): string {
+    return 'test-data.md'
+  }
+
+  protected getEventType(action: 'update' | 'create' | 'delete'): string {
+    return `test.${action}`
+  }
+}
+
+// =============================================================================
+// Test Setup
+// =============================================================================
+
+let tmpRoot: string | null = null
+let testProjectId: string
+let manager: TestStorageManager
+
+// Mock pathManager to use temp directory
+const originalGetGlobalProjectPath = pathManager.getGlobalProjectPath.bind(pathManager)
+const originalGetStoragePath = pathManager.getStoragePath.bind(pathManager)
+const originalGetFilePath = pathManager.getFilePath.bind(pathManager)
+
+describe('StorageManager', () => {
+  beforeEach(async () => {
+    // Create temp directory for test isolation
+    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'prjct-storage-test-'))
+    testProjectId = 'test-project-123'
+
+    // Mock pathManager to use temp directory
+    pathManager.getGlobalProjectPath = (projectId: string) => {
+      return path.join(tmpRoot!, projectId)
+    }
+
+    pathManager.getStoragePath = (projectId: string, filename: string) => {
+      return path.join(tmpRoot!, projectId, 'storage', filename)
+    }
+
+    pathManager.getFilePath = (projectId: string, layer: string, filename: string) => {
+      return path.join(tmpRoot!, projectId, layer, filename)
+    }
+
+    // Create fresh manager instance
+    manager = new TestStorageManager()
+  })
+
+  afterEach(async () => {
+    // Restore original pathManager methods
+    pathManager.getGlobalProjectPath = originalGetGlobalProjectPath
+    pathManager.getStoragePath = originalGetStoragePath
+    pathManager.getFilePath = originalGetFilePath
+
+    // Clean up temp directory
+    if (tmpRoot) {
+      await fs.rm(tmpRoot, { recursive: true, force: true })
+      tmpRoot = null
+    }
+  })
+
+  // ===========================================================================
+  // Read/Write Tests
+  // ===========================================================================
+
+  describe('read/write', () => {
+    it('should write and read JSON correctly', async () => {
+      const testData: TestData = {
+        value: 'hello',
+        count: 42,
+        items: ['a', 'b', 'c'],
+      }
+
+      await manager.write(testProjectId, testData)
+      const result = await manager.read(testProjectId)
+
+      expect(result).toEqual(testData)
+    })
+
+    it('should create storage file with correct JSON format', async () => {
+      const testData: TestData = {
+        value: 'test',
+        count: 1,
+        items: ['item1'],
+      }
+
+      await manager.write(testProjectId, testData)
+
+      // Verify file exists and has correct content
+      const storagePath = path.join(tmpRoot!, testProjectId, 'storage', 'test-data.json')
+      const content = await fs.readFile(storagePath, 'utf-8')
+      const parsed = JSON.parse(content)
+
+      expect(parsed).toEqual(testData)
+    })
+
+    it('should create context markdown file', async () => {
+      const testData: TestData = {
+        value: 'markdown-test',
+        count: 5,
+        items: ['x', 'y'],
+      }
+
+      await manager.write(testProjectId, testData)
+
+      // Verify markdown file exists
+      const contextPath = path.join(tmpRoot!, testProjectId, 'context', 'test-data.md')
+      const content = await fs.readFile(contextPath, 'utf-8')
+
+      expect(content).toContain('# Test Data')
+      expect(content).toContain('Value: markdown-test')
+      expect(content).toContain('Count: 5')
+      expect(content).toContain('Items: x, y')
+    })
+
+    it('should overwrite existing data', async () => {
+      const data1: TestData = { value: 'first', count: 1, items: [] }
+      const data2: TestData = { value: 'second', count: 2, items: ['new'] }
+
+      await manager.write(testProjectId, data1)
+      await manager.write(testProjectId, data2)
+
+      const result = await manager.read(testProjectId)
+      expect(result).toEqual(data2)
+    })
+  })
+
+  // ===========================================================================
+  // Missing File Handling
+  // ===========================================================================
+
+  describe('missing file handling', () => {
+    it('should return default when file does not exist', async () => {
+      const result = await manager.read('non-existent-project')
+
+      expect(result).toEqual({ value: '', count: 0, items: [] })
+    })
+
+    it('should return default for invalid JSON', async () => {
+      // Create invalid JSON file
+      const storagePath = path.join(tmpRoot!, testProjectId, 'storage', 'test-data.json')
+      await fs.mkdir(path.dirname(storagePath), { recursive: true })
+      await fs.writeFile(storagePath, 'not valid json {{{', 'utf-8')
+
+      const result = await manager.read(testProjectId)
+
+      expect(result).toEqual({ value: '', count: 0, items: [] })
+    })
+
+    it('should report exists=false for missing file', async () => {
+      const exists = await manager.exists('non-existent-project')
+      expect(exists).toBe(false)
+    })
+
+    it('should report exists=true after write', async () => {
+      await manager.write(testProjectId, { value: 'test', count: 1, items: [] })
+
+      const exists = await manager.exists(testProjectId)
+      expect(exists).toBe(true)
+    })
+  })
+
+  // ===========================================================================
+  // Directory Creation
+  // ===========================================================================
+
+  describe('directory creation', () => {
+    it('should create storage directory if it does not exist', async () => {
+      const testData: TestData = { value: 'dir-test', count: 1, items: [] }
+
+      // Directory shouldn't exist yet
+      const storageDir = path.join(tmpRoot!, testProjectId, 'storage')
+      await expect(fs.access(storageDir)).rejects.toThrow()
+
+      // Write should create it
+      await manager.write(testProjectId, testData)
+
+      // Now it should exist
+      const stat = await fs.stat(storageDir)
+      expect(stat.isDirectory()).toBe(true)
+    })
+
+    it('should create context directory if it does not exist', async () => {
+      const testData: TestData = { value: 'ctx-test', count: 1, items: [] }
+
+      // Directory shouldn't exist yet
+      const contextDir = path.join(tmpRoot!, testProjectId, 'context')
+      await expect(fs.access(contextDir)).rejects.toThrow()
+
+      // Write should create it
+      await manager.write(testProjectId, testData)
+
+      // Now it should exist
+      const stat = await fs.stat(contextDir)
+      expect(stat.isDirectory()).toBe(true)
+    })
+
+    it('should create nested directories', async () => {
+      const deepProjectId = 'deep/nested/project'
+      const testData: TestData = { value: 'nested', count: 1, items: [] }
+
+      await manager.write(deepProjectId, testData)
+
+      const result = await manager.read(deepProjectId)
+      expect(result).toEqual(testData)
+    })
+  })
+
+  // ===========================================================================
+  // Cache Behavior
+  // ===========================================================================
+
+  describe('cache behavior', () => {
+    it('should cache read results', async () => {
+      const testData: TestData = { value: 'cached', count: 1, items: [] }
+      await manager.write(testProjectId, testData)
+
+      // First read
+      const result1 = await manager.read(testProjectId)
+
+      // Modify file directly (bypass manager)
+      const storagePath = path.join(tmpRoot!, testProjectId, 'storage', 'test-data.json')
+      await fs.writeFile(
+        storagePath,
+        JSON.stringify({ value: 'modified', count: 2, items: [] }),
+        'utf-8'
+      )
+
+      // Second read should return cached value
+      const result2 = await manager.read(testProjectId)
+      expect(result2).toEqual(result1)
+    })
+
+    it('should clear cache for specific project', async () => {
+      const testData: TestData = { value: 'to-clear', count: 1, items: [] }
+      await manager.write(testProjectId, testData)
+
+      // Read to populate cache
+      await manager.read(testProjectId)
+
+      // Modify file directly
+      const storagePath = path.join(tmpRoot!, testProjectId, 'storage', 'test-data.json')
+      const newData = { value: 'updated', count: 99, items: ['new'] }
+      await fs.writeFile(storagePath, JSON.stringify(newData), 'utf-8')
+
+      // Clear cache
+      manager.clearCache(testProjectId)
+
+      // Now read should get fresh data
+      const result = await manager.read(testProjectId)
+      expect(result).toEqual(newData)
+    })
+
+    it('should clear all cache', async () => {
+      // Write to multiple projects
+      await manager.write('project-a', { value: 'a', count: 1, items: [] })
+      await manager.write('project-b', { value: 'b', count: 2, items: [] })
+
+      // Read to populate cache
+      await manager.read('project-a')
+      await manager.read('project-b')
+
+      // Clear all cache
+      manager.clearCache()
+
+      // Verify cache stats
+      const stats = manager.getCacheStats()
+      expect(stats.size).toBe(0)
+    })
+
+    it('should return cache stats', async () => {
+      const stats = manager.getCacheStats()
+
+      expect(stats).toHaveProperty('size')
+      expect(stats).toHaveProperty('maxSize')
+      expect(stats).toHaveProperty('ttl')
+      expect(typeof stats.size).toBe('number')
+      expect(typeof stats.maxSize).toBe('number')
+      expect(typeof stats.ttl).toBe('number')
+    })
+  })
+
+  // ===========================================================================
+  // State Consistency (Update Operations)
+  // ===========================================================================
+
+  describe('state consistency', () => {
+    it('should update data atomically with updater function', async () => {
+      const initial: TestData = { value: 'initial', count: 0, items: [] }
+      await manager.write(testProjectId, initial)
+
+      const result = await manager.update(testProjectId, (current) => ({
+        ...current,
+        count: current.count + 1,
+        items: [...current.items, 'new-item'],
+      }))
+
+      expect(result.count).toBe(1)
+      expect(result.items).toEqual(['new-item'])
+
+      // Verify persisted
+      manager.clearCache(testProjectId)
+      const persisted = await manager.read(testProjectId)
+      expect(persisted).toEqual(result)
+    })
+
+    it('should handle multiple sequential updates', async () => {
+      await manager.write(testProjectId, { value: 'start', count: 0, items: [] })
+
+      // Multiple updates
+      for (let i = 0; i < 5; i++) {
+        await manager.update(testProjectId, (current) => ({
+          ...current,
+          count: current.count + 1,
+        }))
+      }
+
+      const result = await manager.read(testProjectId)
+      expect(result.count).toBe(5)
+    })
+
+    it('should maintain data integrity after failed read during update', async () => {
+      // Start with no file (will use default)
+      const result = await manager.update(testProjectId, (current) => ({
+        ...current,
+        value: 'from-default',
+        count: 100,
+      }))
+
+      expect(result.value).toBe('from-default')
+      expect(result.count).toBe(100)
+    })
+  })
+})

package/core/commands/analysis.ts

@@ -10,7 +10,7 @@ import { generateContext } from '../context/generator'
 import analyzer from '../domain/analyzer'
 import commandInstaller from '../infrastructure/command-installer'
 import { formatCost } from '../schemas/metrics'
-import { memoryService, syncService } from '../services'
+import { createStalenessChecker, memoryService, syncService } from '../services'
 import { formatDiffPreview, formatFullDiff, generateSyncDiff } from '../services/diff-generator'
 import { metricsStorage } from '../storage/metrics-storage'
 import type { AnalyzeOptions, CommandResult, ProjectContext } from '../types'
@@ -735,6 +735,64 @@ export class AnalysisCommands extends PrjctCommandsBase {
     }
   }
 
+  /**
+   * /p:status - Check if CLAUDE.md context is stale
+   *
+   * Uses git commit history to detect when significant changes
+   * have occurred since the last sync.
+   *
+   * @see PRJ-120
+   */
+  async status(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: 'No project ID found' }))
+        } else {
+          out.fail('No project ID found')
+        }
+        return { success: false, error: 'No project ID found' }
+      }
+
+      // Create staleness checker and run check
+      const checker = createStalenessChecker(projectPath)
+      const status = await checker.check(projectId)
+
+      // JSON output mode
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            success: true,
+            ...status,
+          })
+        )
+        return { success: true, data: status }
+      }
+
+      // Human-readable output
+      console.log('')
+      console.log(checker.formatStatus(status))
+      console.log('')
+
+      return { success: true, data: status }
+    } catch (error) {
+      const errMsg = (error as Error).message
+      if (options.json) {
+        console.log(JSON.stringify({ success: false, error: errMsg }))
+      } else {
+        out.fail(errMsg)
+      }
+      return { success: false, error: errMsg }
+    }
+  }
+
   /**
    * Get session activity stats from today's events
    * @see PRJ-89

package/core/commands/analytics.ts

@@ -4,6 +4,7 @@
  */
 
 import path from 'node:path'
+import { createStalenessChecker } from '../services'
 import { ideasStorage, queueStorage, shippedStorage, stateStorage } from '../storage'
 import type { CommandResult, ProjectContext } from '../types'
 import {
@@ -135,6 +136,14 @@ export class AnalyticsCommands extends PrjctCommandsBase {
       console.log(`\n📊 DASHBOARD - ${projectName}\n`)
       console.log('═'.repeat(50))
 
+      // Check staleness (PRJ-120)
+      const checker = createStalenessChecker(projectPath)
+      const stalenessStatus = await checker.check(projectId)
+      const stalenessWarning = checker.getWarning(stalenessStatus)
+      if (stalenessWarning) {
+        console.log(`\n${stalenessWarning}`)
+      }
+
       // Current task
       console.log('\n🎯 CURRENT FOCUS')
       if (currentTask) {