prjct-cli 0.58.0 → 0.59.0

package/core/commands/command-data.ts

@@ -185,6 +185,22 @@ export const COMMANDS: CommandMeta[] = [
     hasTemplate: true,
     requiresProject: true,
   },
+  {
+    name: 'status',
+    group: 'core',
+    description: 'Check if CLAUDE.md context is stale and needs resync',
+    usage: { claude: '/p:status', terminal: 'prjct status' },
+    params: '[--json]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Compares current HEAD with last sync commit',
+      'Counts commits and days since sync',
+      'Detects significant file changes',
+      'Configurable staleness thresholds',
+    ],
+  },
   {
     name: 'help',
     group: 'core',

package/core/commands/commands.ts

@@ -202,6 +202,13 @@ class PrjctCommands {
     return this.analysis.stats(projectPath, options)
   }
 
+  async status(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    return this.analysis.status(projectPath, options)
+  }
+
   // ========== Context Commands ==========
 
   async context(

package/core/commands/register.ts

@@ -85,6 +85,7 @@ export function registerAllCommands(): void {
   commandRegistry.registerMethod('analyze', analysis, 'analyze', getMeta('analyze'))
   commandRegistry.registerMethod('sync', analysis, 'sync', getMeta('sync'))
   commandRegistry.registerMethod('stats', analysis, 'stats', getMeta('stats'))
+  commandRegistry.registerMethod('status', analysis, 'status', getMeta('status'))
 
   // Setup commands
   commandRegistry.registerMethod('start', setup, 'start', getMeta('start'))

package/core/index.ts

@@ -116,6 +116,10 @@ async function main(): Promise<void> {
             json: options.json === true,
             export: options.export === true,
           }),
+        status: () =>
+          commands.status(process.cwd(), {
+            json: options.json === true,
+          }),
         help: (p) => commands.help(p || ''),
         // Maintenance
         recover: () => commands.recover(),

package/core/schemas/project.ts

@@ -25,6 +25,9 @@ export const ProjectItemSchema = z.object({
   commitCount: z.number(),
   createdAt: z.string(), // ISO8601
   lastSync: z.string(), // ISO8601
+  // Staleness tracking (PRJ-120)
+  lastSyncCommit: z.string().optional(), // Git commit hash at last sync
+  lastSyncBranch: z.string().optional(), // Git branch at last sync
 })
 
 // =============================================================================

package/core/services/index.ts

@@ -39,5 +39,8 @@ export type { IndexOptions, RelevantContext, ScanResult } from './project-index'
 // Project Index - Persistent scanning with scoring
 export { createProjectIndexer, ProjectIndexer, RELEVANCE_THRESHOLD } from './project-index'
 export { ProjectService, projectService } from './project-service'
+export type { StalenessConfig, StalenessStatus } from './staleness-checker'
+// Staleness Checker - Detect when CLAUDE.md is stale (PRJ-120)
+export { createStalenessChecker, StalenessChecker } from './staleness-checker'
 export type { SyncResult } from './sync-service'
 export { SyncService, syncService } from './sync-service'

package/core/services/staleness-checker.ts

@@ -0,0 +1,262 @@
+/**
+ * Staleness Checker Service (PRJ-120)
+ *
+ * Detects when CLAUDE.md context is stale and needs resync.
+ * Uses git commit history to determine if significant changes have occurred.
+ *
+ * Pattern from Warp Agent: "Use VCS to detect recent changes"
+ */
+
+import { exec } from 'node:child_process'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import pathManager from '../infrastructure/path-manager'
+
+const execAsync = promisify(exec)
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface StalenessStatus {
+  isStale: boolean
+  reason: string | null
+  lastSyncCommit: string | null
+  currentCommit: string | null
+  commitsSinceSync: number
+  daysSinceSync: number
+  changedFiles: string[]
+  significantChanges: string[] // Files that likely affect context (package.json, etc.)
+}
+
+export interface StalenessConfig {
+  commitThreshold: number // Number of commits before considered stale (default: 10)
+  dayThreshold: number // Days before considered stale (default: 3)
+  significantFiles: string[] // Files that trigger staleness warning
+}
+
+const DEFAULT_CONFIG: StalenessConfig = {
+  commitThreshold: 10,
+  dayThreshold: 3,
+  significantFiles: [
+    'package.json',
+    'tsconfig.json',
+    'Cargo.toml',
+    'go.mod',
+    'requirements.txt',
+    'pyproject.toml',
+    '.env.example',
+    'docker-compose.yml',
+    'Dockerfile',
+  ],
+}
+
+// =============================================================================
+// STALENESS CHECKER
+// =============================================================================
+
+export class StalenessChecker {
+  private projectPath: string
+  private config: StalenessConfig
+
+  constructor(projectPath: string, config: Partial<StalenessConfig> = {}) {
+    this.projectPath = projectPath
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  /**
+   * Check if the project context is stale
+   */
+  async check(projectId: string): Promise<StalenessStatus> {
+    const status: StalenessStatus = {
+      isStale: false,
+      reason: null,
+      lastSyncCommit: null,
+      currentCommit: null,
+      commitsSinceSync: 0,
+      daysSinceSync: 0,
+      changedFiles: [],
+      significantChanges: [],
+    }
+
+    try {
+      // Read project.json to get last sync info
+      const projectJsonPath = path.join(pathManager.getGlobalProjectPath(projectId), 'project.json')
+
+      let projectJson: Record<string, unknown> = {}
+      try {
+        projectJson = JSON.parse(await fs.readFile(projectJsonPath, 'utf-8'))
+      } catch {
+        // No project.json = definitely stale
+        status.isStale = true
+        status.reason = 'No sync history found. Run `prjct sync` to initialize.'
+        return status
+      }
+
+      status.lastSyncCommit = (projectJson.lastSyncCommit as string) || null
+      const lastSync = projectJson.lastSync as string
+
+      // Get current HEAD commit
+      try {
+        const { stdout } = await execAsync('git rev-parse --short HEAD', {
+          cwd: this.projectPath,
+        })
+        status.currentCommit = stdout.trim()
+      } catch {
+        // Not a git repo
+        status.reason = 'Not a git repository'
+        return status
+      }
+
+      // If no last sync commit, we can't compare
+      if (!status.lastSyncCommit) {
+        status.isStale = true
+        status.reason = 'No sync commit recorded. Run `prjct sync` to track.'
+        return status
+      }
+
+      // Same commit = not stale
+      if (status.lastSyncCommit === status.currentCommit) {
+        status.reason = 'Context is up to date'
+        return status
+      }
+
+      // Count commits since last sync
+      try {
+        const { stdout } = await execAsync(`git rev-list --count ${status.lastSyncCommit}..HEAD`, {
+          cwd: this.projectPath,
+        })
+        status.commitsSinceSync = parseInt(stdout.trim(), 10) || 0
+      } catch {
+        // Commit might not exist anymore (rebased, etc.)
+        status.isStale = true
+        status.reason = 'Sync commit no longer exists (history changed). Run `prjct sync`.'
+        return status
+      }
+
+      // Calculate days since sync
+      if (lastSync) {
+        const syncDate = new Date(lastSync)
+        const now = new Date()
+        status.daysSinceSync = Math.floor(
+          (now.getTime() - syncDate.getTime()) / (1000 * 60 * 60 * 24)
+        )
+      }
+
+      // Get changed files since last sync
+      try {
+        const { stdout } = await execAsync(`git diff --name-only ${status.lastSyncCommit}..HEAD`, {
+          cwd: this.projectPath,
+        })
+        status.changedFiles = stdout.trim().split('\n').filter(Boolean)
+      } catch {
+        status.changedFiles = []
+      }
+
+      // Check for significant file changes
+      status.significantChanges = status.changedFiles.filter((file) =>
+        this.config.significantFiles.some((sig) => file.endsWith(sig) || file.includes(sig))
+      )
+
+      // Determine staleness
+      if (status.commitsSinceSync >= this.config.commitThreshold) {
+        status.isStale = true
+        status.reason = `${status.commitsSinceSync} commits since last sync (threshold: ${this.config.commitThreshold})`
+      } else if (status.daysSinceSync >= this.config.dayThreshold) {
+        status.isStale = true
+        status.reason = `${status.daysSinceSync} days since last sync (threshold: ${this.config.dayThreshold})`
+      } else if (status.significantChanges.length > 0) {
+        status.isStale = true
+        status.reason = `Significant files changed: ${status.significantChanges.join(', ')}`
+      } else if (status.commitsSinceSync > 0) {
+        // Not stale yet, but has changes
+        status.reason = `${status.commitsSinceSync} commits since sync (threshold: ${this.config.commitThreshold})`
+      } else {
+        status.reason = 'Context is up to date'
+      }
+
+      return status
+    } catch (error) {
+      status.reason = `Error checking staleness: ${(error as Error).message}`
+      return status
+    }
+  }
+
+  /**
+   * Format staleness status for display
+   */
+  formatStatus(status: StalenessStatus): string {
+    const lines: string[] = []
+
+    if (status.isStale) {
+      lines.push('CLAUDE.md status: ⚠️  STALE')
+    } else {
+      lines.push('CLAUDE.md status: ✓ Fresh')
+    }
+
+    lines.push('─────────────────────────────')
+
+    if (status.lastSyncCommit) {
+      lines.push(`Last sync:      ${status.lastSyncCommit}`)
+    }
+    if (status.currentCommit) {
+      lines.push(`Current:        ${status.currentCommit}`)
+    }
+    if (status.commitsSinceSync > 0) {
+      lines.push(`Commits since:  ${status.commitsSinceSync}`)
+    }
+    if (status.daysSinceSync > 0) {
+      lines.push(`Days since:     ${status.daysSinceSync}`)
+    }
+    if (status.changedFiles.length > 0) {
+      lines.push(`Files changed:  ${status.changedFiles.length}`)
+    }
+    if (status.significantChanges.length > 0) {
+      lines.push(``)
+      lines.push(`Significant changes:`)
+      for (const file of status.significantChanges.slice(0, 5)) {
+        lines.push(`  • ${file}`)
+      }
+      if (status.significantChanges.length > 5) {
+        lines.push(`  ... and ${status.significantChanges.length - 5} more`)
+      }
+    }
+
+    if (status.reason) {
+      lines.push(``)
+      lines.push(status.reason)
+    }
+
+    if (status.isStale) {
+      lines.push(``)
+      lines.push(`Run \`prjct sync\` to update context`)
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Get a short warning message if stale (for other commands)
+   */
+  getWarning(status: StalenessStatus): string | null {
+    if (!status.isStale) return null
+
+    if (status.commitsSinceSync > 0) {
+      return `⚠️  Context stale (${status.commitsSinceSync} commits behind). Run \`prjct sync\``
+    }
+    if (status.daysSinceSync > 0) {
+      return `⚠️  Context stale (${status.daysSinceSync} days old). Run \`prjct sync\``
+    }
+    return `⚠️  Context may be stale. Run \`prjct sync\``
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const createStalenessChecker = (projectPath: string, config?: Partial<StalenessConfig>) =>
+  new StalenessChecker(projectPath, config)
+
+export default StalenessChecker

package/core/services/sync-service.ts

@@ -776,6 +776,9 @@ You are the ${name} expert for this project. Apply best practices for the detect
       hasUncommittedChanges: git.hasChanges,
       createdAt: existing.createdAt || dateHelper.getTimestamp(),
       lastSync: dateHelper.getTimestamp(),
+      // Staleness tracking (PRJ-120)
+      lastSyncCommit: git.recentCommits[0]?.hash || null,
+      lastSyncBranch: git.branch,
     }
 
     await fs.writeFile(projectJsonPath, JSON.stringify(updated, null, 2), 'utf-8')