prjct-cli 1.7.5 → 1.9.0

package/core/domain/fibonacci.ts

@@ -0,0 +1,128 @@
+/**
+ * Fibonacci Estimation Module
+ *
+ * Provides Fibonacci-based story point estimation with
+ * points-to-time conversion and historical suggestion.
+ */
+
+import outcomeRecorder from '../outcomes/recorder'
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Valid Fibonacci story points */
+export const FIBONACCI_POINTS = [1, 2, 3, 5, 8, 13, 21] as const
+export type FibonacciPoint = (typeof FIBONACCI_POINTS)[number]
+
+/** Default points-to-minutes mapping */
+const DEFAULT_MINUTES_MAP: Record<FibonacciPoint, { min: number; max: number; typical: number }> = {
+  1: { min: 5, max: 15, typical: 10 },
+  2: { min: 15, max: 30, typical: 20 },
+  3: { min: 30, max: 60, typical: 45 },
+  5: { min: 60, max: 120, typical: 90 },
+  8: { min: 120, max: 240, typical: 180 },
+  13: { min: 240, max: 480, typical: 360 },
+  21: { min: 480, max: 960, typical: 720 },
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/** Check if a number is a valid Fibonacci point */
+export const isValidPoint = (n: number): n is FibonacciPoint =>
+  FIBONACCI_POINTS.includes(n as FibonacciPoint)
+
+// =============================================================================
+// Points-to-Time Conversion
+// =============================================================================
+
+/** Get the time range for a given point value */
+export const pointsToMinutes = (
+  points: FibonacciPoint
+): { min: number; max: number; typical: number } => {
+  return DEFAULT_MINUTES_MAP[points]
+}
+
+/** Format a minute count as a human-readable duration */
+export const formatMinutes = (minutes: number): string => {
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  const mins = minutes % 60
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`
+}
+
+/** Get a human-readable time range for a point value */
+export const pointsToTimeRange = (points: FibonacciPoint): string => {
+  const range = pointsToMinutes(points)
+  return `${formatMinutes(range.min)}–${formatMinutes(range.max)}`
+}
+
+// =============================================================================
+// Historical Suggestion
+// =============================================================================
+
+/**
+ * Suggest a point estimate based on historical outcomes for similar task types.
+ * Returns null if not enough data (< 3 outcomes).
+ */
+export const suggestFromHistory = async (
+  projectId: string,
+  taskType: string
+): Promise<{ points: FibonacciPoint; basedOn: number } | null> => {
+  const outcomes = await outcomeRecorder.getAll(projectId)
+
+  // Filter by task type tag
+  const relevant = outcomes.filter((o) => o.tags?.includes(taskType))
+
+  if (relevant.length < 3) return null
+
+  // Calculate average actual duration in minutes
+  const totalMinutes = relevant.reduce((sum, o) => {
+    return sum + parseDuration(o.actualDuration)
+  }, 0)
+  const avgMinutes = totalMinutes / relevant.length
+
+  // Find closest Fibonacci point by typical time
+  const closest = findClosestPoint(avgMinutes)
+
+  return { points: closest, basedOn: relevant.length }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Find the Fibonacci point whose typical time is closest to the given minutes */
+export const findClosestPoint = (minutes: number): FibonacciPoint => {
+  let closest: FibonacciPoint = 1
+  let smallestDiff = Number.POSITIVE_INFINITY
+
+  for (const point of FIBONACCI_POINTS) {
+    const diff = Math.abs(DEFAULT_MINUTES_MAP[point].typical - minutes)
+    if (diff < smallestDiff) {
+      smallestDiff = diff
+      closest = point
+    }
+  }
+
+  return closest
+}
+
+/** Parse a duration string like "2h 30m" to minutes */
+const parseDuration = (duration: string): number => {
+  let minutes = 0
+
+  const hourMatch = duration.match(/(\d+)h/)
+  if (hourMatch) {
+    minutes += Number.parseInt(hourMatch[1], 10) * 60
+  }
+
+  const minMatch = duration.match(/(\d+)m/)
+  if (minMatch) {
+    minutes += Number.parseInt(minMatch[1], 10)
+  }
+
+  return minutes
+}

package/core/index.ts

@@ -13,6 +13,7 @@ import chalk from 'chalk'
 import type { CommandMeta } from './commands/registry'
 import { detectAllProviders, detectAntigravity } from './infrastructure/ai-provider'
 import configManager from './infrastructure/config-manager'
+import performanceTracker from './infrastructure/performance-tracker'
 import { sessionTracker } from './services/session-tracker'
 import { getErrorMessage, getErrorStack } from './types/fs'
 import { getError } from './utils/error-messages'
@@ -154,6 +155,7 @@ async function main(): Promise<void> {
             json: options.json === true,
           }),
         help: (p) => commands.help(p || ''),
+        perf: (p) => commands.perf(p || '7'),
         // Maintenance
         recover: () => commands.recover(),
         undo: () => commands.undo(),
@@ -181,7 +183,7 @@ async function main(): Promise<void> {
       }
     }
 
-    // 7. Track command in session
+    // 7. Track command in session + performance metrics
     if (projectId) {
       const durationMs = Date.now() - commandStartTime
       try {
@@ -189,6 +191,28 @@ async function main(): Promise<void> {
       } catch {
         // Non-critical
       }
+
+      // Performance tracking (non-critical)
+      try {
+        // Record command duration
+        await performanceTracker.recordTiming(projectId, 'command_duration', durationMs, {
+          command: commandName,
+        })
+
+        // Record startup time (from bin/prjct.ts marker if available)
+        const perfStartNs = (globalThis as Record<string, unknown>).__perfStartNs as
+          | bigint
+          | undefined
+        if (perfStartNs) {
+          const startupMs = Number(process.hrtime.bigint() - perfStartNs) / 1_000_000
+          await performanceTracker.recordTiming(projectId, 'startup_time', startupMs)
+        }
+
+        // Record memory snapshot
+        await performanceTracker.recordMemory(projectId, { command: commandName })
+      } catch {
+        // Performance tracking is non-critical
+      }
     }
 
     // 8. Display result

package/core/infrastructure/ai-provider.ts

@@ -21,6 +21,7 @@ import { exec } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
+import { compareSemver } from '../schemas/model'
 import { fileExists } from '../utils/fs-helpers'
 import { readProviderCache, writeProviderCache } from '../utils/provider-cache'
 
@@ -58,6 +59,9 @@ export const ClaudeProvider: AIProviderConfig = {
   ignoreFile: '.claudeignore',
   websiteUrl: 'https://www.anthropic.com/claude',
   docsUrl: 'https://docs.anthropic.com/claude-code',
+  defaultModel: 'sonnet',
+  supportedModels: ['opus', 'sonnet', 'haiku'],
+  minCliVersion: '1.0.0',
 }
 
 /**
@@ -77,6 +81,9 @@ export const GeminiProvider: AIProviderConfig = {
   ignoreFile: '.geminiignore',
   websiteUrl: 'https://geminicli.com',
   docsUrl: 'https://geminicli.com/docs',
+  defaultModel: '2.5-flash',
+  supportedModels: ['2.5-pro', '2.5-flash', '2.0-flash'],
+  minCliVersion: '1.0.0',
 }
 
 /**
@@ -100,6 +107,9 @@ export const AntigravityProvider: AIProviderConfig = {
   ignoreFile: '.agentignore', // Assumed
   websiteUrl: 'https://gemini.google.com/app/antigravity',
   docsUrl: 'https://gemini.google.com/app/antigravity',
+  defaultModel: null, // Platform-managed
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -129,6 +139,9 @@ export const CursorProvider: AIProviderConfig = {
   isProjectLevel: true, // Config is project-level only
   websiteUrl: 'https://cursor.com',
   docsUrl: 'https://cursor.com/docs',
+  defaultModel: null, // Multi-model IDE, user selects
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -159,6 +172,9 @@ export const WindsurfProvider: AIProviderConfig = {
   isProjectLevel: true, // Config is project-level only
   websiteUrl: 'https://windsurf.com',
   docsUrl: 'https://docs.windsurf.com',
+  defaultModel: null, // Multi-model IDE, user selects
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -221,14 +237,33 @@ export async function detectProvider(provider: AIProviderName): Promise<Provider
   }
 
   const version = await getCliVersion(config.cliCommand)
+  const versionWarning = validateCliVersion(provider, version || undefined)
 
   return {
     installed: true,
     version: version || undefined,
     path: cliPath,
+    versionWarning: versionWarning || undefined,
   }
 }
 
+/**
+ * Validate that a detected CLI version meets the provider's minimum requirement.
+ * Returns a warning message if the version is below minimum, or null if OK.
+ */
+export function validateCliVersion(
+  provider: AIProviderName,
+  version: string | undefined
+): string | null {
+  const config = Providers[provider]
+  if (!config.minCliVersion || !version) return null
+
+  if (compareSemver(version, config.minCliVersion) < 0) {
+    return `⚠️ ${config.displayName} v${version} is below minimum v${config.minCliVersion}. Some features may not work correctly.`
+  }
+  return null
+}
+
 /**
  * Detect all available CLI-based providers
  * Results are cached to disk with a 10-minute TTL to avoid redundant shell spawns.

package/core/infrastructure/performance-tracker.ts

@@ -0,0 +1,326 @@
+/**
+ * PerformanceTracker - Measures CLI performance metrics
+ *
+ * Instruments startup time, memory usage, context correctness,
+ * subtask handoff rate, and command durations.
+ *
+ * Storage: ~/.prjct-cli/projects/{projectId}/storage/performance.jsonl
+ * Rotation: 5MB (via jsonl-helper)
+ *
+ * @see PRJ-297
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type {
+  ContextCorrectness,
+  MemorySnapshot,
+  MetricName,
+  PerformanceEntry,
+  PerformanceMetric,
+  PerformanceReport,
+  SubtaskHandoff,
+} from '../schemas/performance'
+import { getTimestamp } from '../utils/date-helper'
+import { appendJsonLineWithRotation, filterJsonLines } from '../utils/jsonl-helper'
+import pathManager from './path-manager'
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const PERF_FILENAME = 'performance.jsonl'
+const ROTATION_SIZE_MB = 5
+
+// =============================================================================
+// PERFORMANCE TRACKER
+// =============================================================================
+
+class PerformanceTracker {
+  private marks: Map<string, bigint> = new Map()
+
+  /**
+   * Get the performance.jsonl path for a project
+   */
+  private getPath(projectId: string): string {
+    return pathManager.getStoragePath(projectId, PERF_FILENAME)
+  }
+
+  /**
+   * Ensure the storage directory exists
+   */
+  private async ensureDir(projectId: string): Promise<void> {
+    const filePath = this.getPath(projectId)
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+  }
+
+  // ===========================================================================
+  // Timing
+  // ===========================================================================
+
+  /**
+   * Mark the start of a timing measurement.
+   * Uses process.hrtime.bigint() for nanosecond precision.
+   */
+  markStart(label: string): void {
+    this.marks.set(label, process.hrtime.bigint())
+  }
+
+  /**
+   * Mark the end of a timing measurement and return duration in ms.
+   * Returns null if no matching start mark exists.
+   */
+  markEnd(label: string): number | null {
+    const start = this.marks.get(label)
+    if (start === undefined) return null
+
+    const end = process.hrtime.bigint()
+    this.marks.delete(label)
+    return Number(end - start) / 1_000_000 // ns → ms
+  }
+
+  /**
+   * Record a timing metric to storage
+   */
+  async recordTiming(
+    projectId: string,
+    metric: MetricName,
+    durationMs: number,
+    context?: Record<string, unknown>
+  ): Promise<void> {
+    await this.ensureDir(projectId)
+
+    const entry: PerformanceMetric = {
+      timestamp: getTimestamp(),
+      metric,
+      value: Math.round(durationMs * 100) / 100, // 2 decimal places
+      unit: 'ms',
+      context,
+    }
+
+    await appendJsonLineWithRotation(this.getPath(projectId), entry, ROTATION_SIZE_MB)
+  }
+
+  // ===========================================================================
+  // Memory
+  // ===========================================================================
+
+  /**
+   * Take a memory snapshot using process.memoryUsage()
+   */
+  snapshotMemory(): MemorySnapshot {
+    const mem = process.memoryUsage()
+    return {
+      heapUsed: mem.heapUsed,
+      heapTotal: mem.heapTotal,
+      rss: mem.rss,
+      external: mem.external,
+    }
+  }
+
+  /**
+   * Record a memory snapshot to storage
+   */
+  async recordMemory(
+    projectId: string,
+    context?: Record<string, unknown>
+  ): Promise<MemorySnapshot> {
+    await this.ensureDir(projectId)
+
+    const snapshot = this.snapshotMemory()
+    const filePath = this.getPath(projectId)
+    const ts = getTimestamp()
+
+    const entries: PerformanceMetric[] = [
+      { timestamp: ts, metric: 'heap_used', value: snapshot.heapUsed, unit: 'bytes', context },
+      { timestamp: ts, metric: 'heap_total', value: snapshot.heapTotal, unit: 'bytes', context },
+      { timestamp: ts, metric: 'rss', value: snapshot.rss, unit: 'bytes', context },
+      {
+        timestamp: ts,
+        metric: 'external_memory',
+        value: snapshot.external,
+        unit: 'bytes',
+        context,
+      },
+    ]
+
+    for (const entry of entries) {
+      await appendJsonLineWithRotation(filePath, entry, ROTATION_SIZE_MB)
+    }
+
+    return snapshot
+  }
+
+  // ===========================================================================
+  // Context Correctness
+  // ===========================================================================
+
+  /**
+   * Record whether a task received sync context
+   */
+  async recordContextCorrectness(
+    projectId: string,
+    data: Omit<ContextCorrectness, 'timestamp' | 'metric'>
+  ): Promise<void> {
+    await this.ensureDir(projectId)
+
+    const entry: ContextCorrectness = {
+      timestamp: getTimestamp(),
+      metric: 'context_correctness',
+      ...data,
+    }
+
+    await appendJsonLineWithRotation(this.getPath(projectId), entry, ROTATION_SIZE_MB)
+  }
+
+  // ===========================================================================
+  // Subtask Handoff
+  // ===========================================================================
+
+  /**
+   * Record whether a subtask's output field was populated on completion
+   */
+  async recordSubtaskHandoff(
+    projectId: string,
+    data: Omit<SubtaskHandoff, 'timestamp' | 'metric'>
+  ): Promise<void> {
+    await this.ensureDir(projectId)
+
+    const entry: SubtaskHandoff = {
+      timestamp: getTimestamp(),
+      metric: 'subtask_handoff',
+      ...data,
+    }
+
+    await appendJsonLineWithRotation(this.getPath(projectId), entry, ROTATION_SIZE_MB)
+  }
+
+  // ===========================================================================
+  // Report Generation
+  // ===========================================================================
+
+  /**
+   * Read all metrics for a project within a date range
+   */
+  async getMetrics(projectId: string, sinceDate?: Date): Promise<PerformanceEntry[]> {
+    const filePath = this.getPath(projectId)
+
+    if (!sinceDate) {
+      // Default: last 7 days
+      sinceDate = new Date()
+      sinceDate.setDate(sinceDate.getDate() - 7)
+    }
+
+    const sinceIso = sinceDate.toISOString()
+
+    return filterJsonLines<PerformanceEntry>(filePath, (entry) => {
+      return entry.timestamp >= sinceIso
+    })
+  }
+
+  /**
+   * Generate a performance report for a project
+   */
+  async getReport(projectId: string, days: number = 7): Promise<PerformanceReport> {
+    const sinceDate = new Date()
+    sinceDate.setDate(sinceDate.getDate() - days)
+
+    const entries = await this.getMetrics(projectId, sinceDate)
+    const report: PerformanceReport = {
+      period: `${days}d`,
+    }
+
+    // Startup time
+    const startupEntries = entries.filter(
+      (e): e is PerformanceMetric => 'metric' in e && e.metric === 'startup_time'
+    )
+    if (startupEntries.length > 0) {
+      const values = startupEntries.map((e) => e.value)
+      report.startup = {
+        avg: Math.round(values.reduce((a, b) => a + b, 0) / values.length),
+        min: Math.min(...values),
+        max: Math.max(...values),
+        count: values.length,
+        unit: 'ms',
+      }
+    }
+
+    // Memory
+    const heapEntries = entries.filter(
+      (e): e is PerformanceMetric => 'metric' in e && e.metric === 'heap_used'
+    )
+    const rssEntries = entries.filter(
+      (e): e is PerformanceMetric => 'metric' in e && e.metric === 'rss'
+    )
+    if (heapEntries.length > 0) {
+      const toMB = (bytes: number) => Math.round((bytes / (1024 * 1024)) * 10) / 10
+      const heapValues = heapEntries.map((e) => e.value)
+      const rssValues = rssEntries.map((e) => e.value)
+      report.memory = {
+        avgHeapMB: toMB(heapValues.reduce((a, b) => a + b, 0) / heapValues.length),
+        peakHeapMB: toMB(Math.max(...heapValues)),
+        avgRssMB:
+          rssValues.length > 0 ? toMB(rssValues.reduce((a, b) => a + b, 0) / rssValues.length) : 0,
+      }
+    }
+
+    // Context correctness
+    const contextEntries = entries.filter(
+      (e): e is ContextCorrectness => 'metric' in e && e.metric === 'context_correctness'
+    )
+    if (contextEntries.length > 0) {
+      const received = contextEntries.filter((e) => e.receivedSync).length
+      report.contextCorrectness = {
+        total: contextEntries.length,
+        receivedSync: received,
+        rate: Math.round((received / contextEntries.length) * 100),
+      }
+    }
+
+    // Subtask handoff
+    const handoffEntries = entries.filter(
+      (e): e is SubtaskHandoff => 'metric' in e && e.metric === 'subtask_handoff'
+    )
+    if (handoffEntries.length > 0) {
+      const populated = handoffEntries.filter((e) => e.outputPopulated).length
+      report.subtaskHandoff = {
+        total: handoffEntries.length,
+        outputPopulated: populated,
+        rate: Math.round((populated / handoffEntries.length) * 100),
+      }
+    }
+
+    // Command durations
+    const cmdEntries = entries.filter(
+      (e): e is PerformanceMetric => 'metric' in e && e.metric === 'command_duration'
+    )
+    if (cmdEntries.length > 0) {
+      const byCommand: Record<string, number[]> = {}
+      for (const e of cmdEntries) {
+        const cmd = (e.context?.command as string) || 'unknown'
+        if (!byCommand[cmd]) byCommand[cmd] = []
+        byCommand[cmd].push(e.value)
+      }
+
+      report.commandDurations = {}
+      for (const [cmd, values] of Object.entries(byCommand)) {
+        report.commandDurations[cmd] = {
+          avg: Math.round(values.reduce((a, b) => a + b, 0) / values.length),
+          min: Math.min(...values),
+          max: Math.max(...values),
+          count: values.length,
+          unit: 'ms',
+        }
+      }
+    }
+
+    return report
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const performanceTracker = new PerformanceTracker()
+export default performanceTracker

package/core/schemas/analysis.ts

@@ -4,6 +4,8 @@
  * Defines the structure for analysis.json - repository analysis.
  */
 
+import type { ModelMetadata } from './model'
+
 export interface CodePattern {
   name: string
   description: string
@@ -28,6 +30,8 @@ export interface AnalysisSchema {
   patterns: CodePattern[]
   antiPatterns: AntiPattern[]
   analyzedAt: string // ISO8601
+  /** Which AI model was used for this analysis (PRJ-265) */
+  modelMetadata?: ModelMetadata
 }
 
 export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {