prjct-cli 0.44.1 → 0.45.3

package/core/storage/metrics-storage.ts

@@ -0,0 +1,320 @@
+/**
+ * Metrics Storage
+ *
+ * Manages value dashboard metrics via storage/metrics.json
+ * Generates context/metrics.md for Claude
+ *
+ * Tracks:
+ * - Token savings (compression)
+ * - Sync performance
+ * - Agent usage
+ * - Daily trends for visualization
+ */
+
+import {
+  type AgentUsage,
+  type DailyStats,
+  DEFAULT_METRICS,
+  estimateCostSaved,
+  formatCost,
+  type MetricsJson,
+} from '../schemas/metrics'
+import { getTimestamp } from '../utils/date-helper'
+import { StorageManager } from './storage-manager'
+
+class MetricsStorage extends StorageManager<MetricsJson> {
+  constructor() {
+    super('metrics.json')
+  }
+
+  protected getDefault(): MetricsJson {
+    return { ...DEFAULT_METRICS }
+  }
+
+  protected getMdFilename(): string {
+    return 'metrics.md'
+  }
+
+  protected getLayer(): string {
+    return 'context'
+  }
+
+  protected getEventType(action: 'update' | 'create' | 'delete'): string {
+    return `metrics.${action}d`
+  }
+
+  protected toMarkdown(data: MetricsJson): string {
+    const lines = ['# Value Dashboard 📊', '']
+
+    if (data.syncCount === 0) {
+      lines.push('_No metrics yet. Run `prjct sync` to start tracking._')
+      lines.push('')
+      return lines.join('\n')
+    }
+
+    // Token Savings
+    lines.push('## 💰 Token Savings')
+    lines.push('')
+    lines.push(`- **Total saved**: ${this.formatTokens(data.totalTokensSaved)} tokens`)
+    lines.push(
+      `- **Compression**: ${(data.avgCompressionRate * 100).toFixed(0)}% average reduction`
+    )
+    lines.push(
+      `- **Estimated cost saved**: ${formatCost(estimateCostSaved(data.totalTokensSaved))}`
+    )
+    lines.push('')
+
+    // Performance
+    lines.push('## ⚡ Performance')
+    lines.push('')
+    lines.push(`- **Syncs completed**: ${data.syncCount.toLocaleString()}`)
+    lines.push(`- **Avg sync time**: ${this.formatDuration(data.avgSyncDuration)}`)
+    if (data.watchTriggers > 0) {
+      lines.push(`- **Watch triggers**: ${data.watchTriggers.toLocaleString()} auto-syncs`)
+    }
+    lines.push('')
+
+    // Agent Usage
+    if (data.agentUsage.length > 0) {
+      lines.push('## 🤖 Agent Usage')
+      lines.push('')
+      const sortedAgents = [...data.agentUsage].sort((a, b) => b.usageCount - a.usageCount)
+      const totalUsage = sortedAgents.reduce((sum, a) => sum + a.usageCount, 0)
+
+      sortedAgents.slice(0, 5).forEach((agent) => {
+        const pct = totalUsage > 0 ? ((agent.usageCount / totalUsage) * 100).toFixed(0) : 0
+        lines.push(`- **${agent.agentName}**: ${pct}% (${agent.usageCount} uses)`)
+      })
+      lines.push('')
+    }
+
+    // Trend (last 30 days)
+    if (data.dailyStats.length > 0) {
+      lines.push('## 📈 30-Day Trend')
+      lines.push('')
+      const last30 = this.getLast30Days(data.dailyStats)
+      const totalLast30 = last30.reduce((sum, d) => sum + d.tokensSaved, 0)
+      lines.push(`- **Tokens saved**: ${this.formatTokens(totalLast30)}`)
+      lines.push(`- **Syncs**: ${last30.reduce((sum, d) => sum + d.syncs, 0)}`)
+      lines.push('')
+      lines.push('```')
+      lines.push(this.generateSparkline(last30))
+      lines.push('```')
+      lines.push('')
+    }
+
+    // Footer
+    lines.push('---')
+    lines.push('')
+    if (data.firstSync) {
+      lines.push(`_Tracking since ${new Date(data.firstSync).toLocaleDateString()}_`)
+    }
+    lines.push('')
+
+    return lines.join('\n')
+  }
+
+  // =========== Domain Methods ===========
+
+  /**
+   * Record a sync event with metrics
+   */
+  async recordSync(
+    projectId: string,
+    metrics: {
+      originalSize: number // Tokens before compression
+      filteredSize: number // Tokens after compression
+      duration: number // Sync duration in ms
+      isWatch?: boolean // From watch mode?
+      agents?: string[] // Agents used
+    }
+  ): Promise<void> {
+    const tokensSaved = Math.max(0, metrics.originalSize - metrics.filteredSize)
+    const compressionRate = metrics.originalSize > 0 ? tokensSaved / metrics.originalSize : 0
+
+    const today = new Date().toISOString().split('T')[0]
+
+    await this.update(projectId, (data) => {
+      // Update totals
+      const newSyncCount = data.syncCount + 1
+      const newTotalTokensSaved = data.totalTokensSaved + tokensSaved
+      const newTotalDuration = data.totalSyncDuration + metrics.duration
+
+      // Running average for compression rate
+      const newAvgCompression =
+        data.syncCount === 0
+          ? compressionRate
+          : (data.avgCompressionRate * data.syncCount + compressionRate) / newSyncCount
+
+      // Update daily stats
+      const dailyStats = [...data.dailyStats]
+      const todayIndex = dailyStats.findIndex((d) => d.date === today)
+
+      if (todayIndex >= 0) {
+        const existing = dailyStats[todayIndex]
+        dailyStats[todayIndex] = {
+          ...existing,
+          tokensSaved: existing.tokensSaved + tokensSaved,
+          syncs: existing.syncs + 1,
+          avgCompressionRate:
+            (existing.avgCompressionRate * existing.syncs + compressionRate) / (existing.syncs + 1),
+          totalDuration: existing.totalDuration + metrics.duration,
+        }
+      } else {
+        dailyStats.push({
+          date: today,
+          tokensSaved,
+          syncs: 1,
+          avgCompressionRate: compressionRate,
+          totalDuration: metrics.duration,
+        })
+      }
+
+      // Keep only last 90 days
+      const cutoff = new Date()
+      cutoff.setDate(cutoff.getDate() - 90)
+      const cutoffStr = cutoff.toISOString().split('T')[0]
+      const trimmedStats = dailyStats.filter((d) => d.date >= cutoffStr)
+
+      // Update agent usage
+      const agentUsage = [...data.agentUsage]
+      if (metrics.agents) {
+        for (const agentName of metrics.agents) {
+          const idx = agentUsage.findIndex((a) => a.agentName === agentName)
+          if (idx >= 0) {
+            agentUsage[idx] = {
+              ...agentUsage[idx],
+              usageCount: agentUsage[idx].usageCount + 1,
+              tokensSaved:
+                agentUsage[idx].tokensSaved + Math.floor(tokensSaved / metrics.agents.length),
+            }
+          } else {
+            agentUsage.push({
+              agentName,
+              usageCount: 1,
+              tokensSaved: Math.floor(tokensSaved / metrics.agents.length),
+            })
+          }
+        }
+      }
+
+      return {
+        totalTokensSaved: newTotalTokensSaved,
+        avgCompressionRate: newAvgCompression,
+        syncCount: newSyncCount,
+        watchTriggers: data.watchTriggers + (metrics.isWatch ? 1 : 0),
+        avgSyncDuration: newTotalDuration / newSyncCount,
+        totalSyncDuration: newTotalDuration,
+        agentUsage,
+        dailyStats: trimmedStats,
+        firstSync: data.firstSync || getTimestamp(),
+        lastUpdated: getTimestamp(),
+      }
+    })
+  }
+
+  /**
+   * Get metrics summary for dashboard
+   */
+  async getSummary(projectId: string): Promise<{
+    totalTokensSaved: number
+    estimatedCostSaved: number
+    compressionRate: number
+    syncCount: number
+    avgSyncDuration: number
+    topAgents: AgentUsage[]
+    last30DaysTokens: number
+    trend: number // Percentage change vs previous 30 days
+  }> {
+    const data = await this.read(projectId)
+
+    const last30 = this.getLast30Days(data.dailyStats)
+    const prev30 = this.getPrev30Days(data.dailyStats)
+
+    const last30Tokens = last30.reduce((sum, d) => sum + d.tokensSaved, 0)
+    const prev30Tokens = prev30.reduce((sum, d) => sum + d.tokensSaved, 0)
+
+    const trend = prev30Tokens > 0 ? ((last30Tokens - prev30Tokens) / prev30Tokens) * 100 : 0
+
+    return {
+      totalTokensSaved: data.totalTokensSaved,
+      estimatedCostSaved: estimateCostSaved(data.totalTokensSaved),
+      compressionRate: data.avgCompressionRate,
+      syncCount: data.syncCount,
+      avgSyncDuration: data.avgSyncDuration,
+      topAgents: [...data.agentUsage].sort((a, b) => b.usageCount - a.usageCount).slice(0, 5),
+      last30DaysTokens: last30Tokens,
+      trend,
+    }
+  }
+
+  /**
+   * Get daily stats for a period
+   */
+  async getDailyStats(projectId: string, days: number = 30): Promise<DailyStats[]> {
+    const data = await this.read(projectId)
+    const cutoff = new Date()
+    cutoff.setDate(cutoff.getDate() - days)
+    const cutoffStr = cutoff.toISOString().split('T')[0]
+
+    return data.dailyStats
+      .filter((d) => d.date >= cutoffStr)
+      .sort((a, b) => a.date.localeCompare(b.date))
+  }
+
+  // =========== Helper Methods ===========
+
+  private getLast30Days(dailyStats: DailyStats[]): DailyStats[] {
+    const cutoff = new Date()
+    cutoff.setDate(cutoff.getDate() - 30)
+    const cutoffStr = cutoff.toISOString().split('T')[0]
+    return dailyStats.filter((d) => d.date >= cutoffStr)
+  }
+
+  private getPrev30Days(dailyStats: DailyStats[]): DailyStats[] {
+    const end = new Date()
+    end.setDate(end.getDate() - 30)
+    const start = new Date()
+    start.setDate(start.getDate() - 60)
+
+    const startStr = start.toISOString().split('T')[0]
+    const endStr = end.toISOString().split('T')[0]
+
+    return dailyStats.filter((d) => d.date >= startStr && d.date < endStr)
+  }
+
+  private formatTokens(tokens: number): string {
+    if (tokens >= 1_000_000) {
+      return `${(tokens / 1_000_000).toFixed(1)}M`
+    }
+    if (tokens >= 1_000) {
+      return `${(tokens / 1_000).toFixed(1)}K`
+    }
+    return tokens.toLocaleString()
+  }
+
+  private formatDuration(ms: number): string {
+    if (ms < 1000) {
+      return `${Math.round(ms)}ms`
+    }
+    return `${(ms / 1000).toFixed(1)}s`
+  }
+
+  private generateSparkline(dailyStats: DailyStats[]): string {
+    if (dailyStats.length === 0) return ''
+
+    const chars = '▁▂▃▄▅▆▇█'
+    const values = dailyStats.map((d) => d.tokensSaved)
+    const max = Math.max(...values, 1)
+
+    return values
+      .map((v) => {
+        const idx = Math.min(Math.floor((v / max) * (chars.length - 1)), chars.length - 1)
+        return chars[idx]
+      })
+      .join('')
+  }
+}
+
+export const metricsStorage = new MetricsStorage()
+export default metricsStorage

package/core/storage/queue-storage.ts

@@ -5,10 +5,10 @@
  * Generates context/next.md for Claude
  */
 
-import { StorageManager } from './storage-manager'
 import { generateUUID } from '../schemas'
+import type { Priority, QueueJson, QueueTask, TaskSection } from '../schemas/state'
 import { getTimestamp } from '../utils/date-helper'
-import type { QueueJson, QueueTask, Priority, TaskType, TaskSection } from '../schemas/state'
+import { StorageManager } from './storage-manager'
 
 class QueueStorage extends StorageManager<QueueJson> {
   constructor() {
@@ -18,7 +18,7 @@ class QueueStorage extends StorageManager<QueueJson> {
   protected getDefault(): QueueJson {
     return {
       tasks: [],
-      lastUpdated: ''
+      lastUpdated: '',
     }
   }
 
@@ -37,9 +37,11 @@ class QueueStorage extends StorageManager<QueueJson> {
   protected toMarkdown(data: QueueJson): string {
     const lines = ['# Priority Queue', '']
 
-    const activeTasks = data.tasks.filter(t => t.section === 'active' && !t.completed)
-    const backlogTasks = data.tasks.filter(t => t.section === 'backlog' && !t.completed)
-    const previouslyActive = data.tasks.filter(t => t.section === 'previously_active' && !t.completed)
+    const activeTasks = data.tasks.filter((t) => t.section === 'active' && !t.completed)
+    const backlogTasks = data.tasks.filter((t) => t.section === 'backlog' && !t.completed)
+    const previouslyActive = data.tasks.filter(
+      (t) => t.section === 'previously_active' && !t.completed
+    )
 
     // Active section
     lines.push('## Active Tasks')
@@ -60,7 +62,7 @@ class QueueStorage extends StorageManager<QueueJson> {
     // Previously active section (if any)
     if (previouslyActive.length > 0) {
       lines.push('## Previously Active')
-      previouslyActive.forEach(task => {
+      previouslyActive.forEach((task) => {
         lines.push(`- [ ] ${task.description}`)
       })
       lines.push('')
@@ -69,7 +71,7 @@ class QueueStorage extends StorageManager<QueueJson> {
     // Backlog section
     lines.push('## Backlog')
     if (backlogTasks.length > 0) {
-      backlogTasks.forEach(task => {
+      backlogTasks.forEach((task) => {
         const priority = task.priority !== 'medium' ? ` [${task.priority.toUpperCase()}]` : ''
         const bug = task.type === 'bug' ? ' \u{1F41B}' : ''
         lines.push(`- [ ]${bug}${priority} ${task.description}`)
@@ -97,7 +99,7 @@ class QueueStorage extends StorageManager<QueueJson> {
    */
   async getActiveTasks(projectId: string): Promise<QueueTask[]> {
     const queue = await this.read(projectId)
-    return queue.tasks.filter(t => t.section === 'active' && !t.completed)
+    return queue.tasks.filter((t) => t.section === 'active' && !t.completed)
   }
 
   /**
@@ -105,7 +107,7 @@ class QueueStorage extends StorageManager<QueueJson> {
    */
   async getBacklog(projectId: string): Promise<QueueTask[]> {
     const queue = await this.read(projectId)
-    return queue.tasks.filter(t => t.section === 'backlog' && !t.completed)
+    return queue.tasks.filter((t) => t.section === 'backlog' && !t.completed)
   }
 
   /**
@@ -127,12 +129,12 @@ class QueueStorage extends StorageManager<QueueJson> {
       ...task,
       id: generateUUID(),
       createdAt: getTimestamp(),
-      completed: false
+      completed: false,
     }
 
     await this.update(projectId, (queue) => ({
       tasks: [...queue.tasks, newTask],
-      lastUpdated: getTimestamp()
+      lastUpdated: getTimestamp(),
     }))
 
     // Publish incremental event
@@ -140,7 +142,7 @@ class QueueStorage extends StorageManager<QueueJson> {
       taskId: newTask.id,
       description: newTask.description,
       priority: newTask.priority,
-      section: newTask.section
+      section: newTask.section,
     })
 
     return newTask
@@ -154,22 +156,22 @@ class QueueStorage extends StorageManager<QueueJson> {
     tasks: Omit<QueueTask, 'id' | 'createdAt' | 'completed' | 'completedAt'>[]
   ): Promise<QueueTask[]> {
     const now = getTimestamp()
-    const newTasks: QueueTask[] = tasks.map(task => ({
+    const newTasks: QueueTask[] = tasks.map((task) => ({
       ...task,
       id: generateUUID(),
       createdAt: now,
-      completed: false
+      completed: false,
     }))
 
     await this.update(projectId, (queue) => ({
       tasks: [...queue.tasks, ...newTasks],
-      lastUpdated: now
+      lastUpdated: now,
     }))
 
     // Publish event for batch add
     await this.publishEvent(projectId, 'queue.tasks_added', {
       count: newTasks.length,
-      tasks: newTasks.map(t => ({ id: t.id, description: t.description }))
+      tasks: newTasks.map((t) => ({ id: t.id, description: t.description })),
     })
 
     return newTasks
@@ -180,8 +182,8 @@ class QueueStorage extends StorageManager<QueueJson> {
    */
   async removeTask(projectId: string, taskId: string): Promise<void> {
     await this.update(projectId, (queue) => ({
-      tasks: queue.tasks.filter(t => t.id !== taskId),
-      lastUpdated: getTimestamp()
+      tasks: queue.tasks.filter((t) => t.id !== taskId),
+      lastUpdated: getTimestamp(),
     }))
 
     await this.publishEvent(projectId, 'queue.task_removed', { taskId })
@@ -194,12 +196,12 @@ class QueueStorage extends StorageManager<QueueJson> {
     let completedTask: QueueTask | null = null
 
     await this.update(projectId, (queue) => {
-      const tasks = queue.tasks.map(t => {
+      const tasks = queue.tasks.map((t) => {
         if (t.id === taskId) {
           completedTask = {
             ...t,
             completed: true,
-            completedAt: getTimestamp()
+            completedAt: getTimestamp(),
           }
           return completedTask
         }
@@ -213,7 +215,7 @@ class QueueStorage extends StorageManager<QueueJson> {
       await this.publishEvent(projectId, 'queue.task_completed', {
         taskId,
         description: task.description,
-        completedAt: task.completedAt
+        completedAt: task.completedAt,
       })
     }
 
@@ -223,32 +225,20 @@ class QueueStorage extends StorageManager<QueueJson> {
   /**
    * Move task to different section
    */
-  async moveToSection(
-    projectId: string,
-    taskId: string,
-    section: TaskSection
-  ): Promise<void> {
+  async moveToSection(projectId: string, taskId: string, section: TaskSection): Promise<void> {
     await this.update(projectId, (queue) => ({
-      tasks: queue.tasks.map(t =>
-        t.id === taskId ? { ...t, section } : t
-      ),
-      lastUpdated: getTimestamp()
+      tasks: queue.tasks.map((t) => (t.id === taskId ? { ...t, section } : t)),
+      lastUpdated: getTimestamp(),
     }))
   }
 
   /**
    * Set task priority
    */
-  async setPriority(
-    projectId: string,
-    taskId: string,
-    priority: Priority
-  ): Promise<void> {
+  async setPriority(projectId: string, taskId: string, priority: Priority): Promise<void> {
     await this.update(projectId, (queue) => ({
-      tasks: queue.tasks.map(t =>
-        t.id === taskId ? { ...t, priority } : t
-      ),
-      lastUpdated: getTimestamp()
+      tasks: queue.tasks.map((t) => (t.id === taskId ? { ...t, priority } : t)),
+      lastUpdated: getTimestamp(),
     }))
   }
 
@@ -257,11 +247,11 @@ class QueueStorage extends StorageManager<QueueJson> {
    */
   async clearCompleted(projectId: string): Promise<number> {
     const queue = await this.read(projectId)
-    const completedCount = queue.tasks.filter(t => t.completed).length
+    const completedCount = queue.tasks.filter((t) => t.completed).length
 
     await this.update(projectId, (q) => ({
-      tasks: q.tasks.filter(t => !t.completed),
-      lastUpdated: getTimestamp()
+      tasks: q.tasks.filter((t) => !t.completed),
+      lastUpdated: getTimestamp(),
     }))
 
     return completedCount
@@ -275,13 +265,13 @@ class QueueStorage extends StorageManager<QueueJson> {
       critical: 0,
       high: 1,
       medium: 2,
-      low: 3
+      low: 3,
     }
 
     const sectionOrder: Record<TaskSection, number> = {
       active: 0,
       previously_active: 1,
-      backlog: 2
+      backlog: 2,
     }
 
     return [...tasks].sort((a, b) => {

package/core/storage/shipped-storage.ts

@@ -5,10 +5,10 @@
  * Generates context/shipped.md for Claude
  */
 
-import { StorageManager } from './storage-manager'
 import { generateUUID } from '../schemas'
-import { getTimestamp } from '../utils/date-helper'
 import type { ShippedFeature, ShippedJson } from '../types'
+import { getTimestamp } from '../utils/date-helper'
+import { StorageManager } from './storage-manager'
 
 class ShippedStorage extends StorageManager<ShippedJson> {
   constructor() {
@@ -18,7 +18,7 @@ class ShippedStorage extends StorageManager<ShippedJson> {
   protected getDefault(): ShippedJson {
     return {
       shipped: [],
-      lastUpdated: ''
+      lastUpdated: '',
     }
   }
 
@@ -46,7 +46,7 @@ class ShippedStorage extends StorageManager<ShippedJson> {
     // Group by month
     const byMonth = new Map<string, ShippedFeature[]>()
 
-    data.shipped.forEach(ship => {
+    data.shipped.forEach((ship) => {
       const date = new Date(ship.shippedAt)
       const month = date.toLocaleDateString('en-US', { year: 'numeric', month: 'long' })
 
@@ -63,18 +63,18 @@ class ShippedStorage extends StorageManager<ShippedJson> {
       return dateB.getTime() - dateA.getTime()
     })
 
-    sortedMonths.forEach(month => {
+    sortedMonths.forEach((month) => {
       lines.push(`## ${month}`)
       lines.push('')
 
-      const ships = byMonth.get(month)!.sort(
-        (a, b) => new Date(b.shippedAt).getTime() - new Date(a.shippedAt).getTime()
-      )
+      const ships = byMonth
+        .get(month)!
+        .sort((a, b) => new Date(b.shippedAt).getTime() - new Date(a.shippedAt).getTime())
 
-      ships.forEach(ship => {
+      ships.forEach((ship) => {
         const date = new Date(ship.shippedAt).toLocaleDateString('en-US', {
           month: 'short',
-          day: 'numeric'
+          day: 'numeric',
         })
         const version = ship.version ? ` v${ship.version}` : ''
         const duration = ship.duration ? ` (${ship.duration})` : ''
@@ -126,12 +126,12 @@ class ShippedStorage extends StorageManager<ShippedJson> {
     const shipped: ShippedFeature = {
       ...feature,
       id: generateUUID(),
-      shippedAt: getTimestamp()
+      shippedAt: getTimestamp(),
     }
 
     await this.update(projectId, (data) => ({
       shipped: [shipped, ...data.shipped], // Prepend
-      lastUpdated: getTimestamp()
+      lastUpdated: getTimestamp(),
     }))
 
     // Publish event
@@ -139,7 +139,7 @@ class ShippedStorage extends StorageManager<ShippedJson> {
       shipId: shipped.id,
       name: shipped.name,
       version: shipped.version,
-      shippedAt: shipped.shippedAt
+      shippedAt: shipped.shippedAt,
     })
 
     return shipped
@@ -148,12 +148,9 @@ class ShippedStorage extends StorageManager<ShippedJson> {
   /**
    * Get shipped by version
    */
-  async getByVersion(
-    projectId: string,
-    version: string
-  ): Promise<ShippedFeature | undefined> {
+  async getByVersion(projectId: string, version: string): Promise<ShippedFeature | undefined> {
     const data = await this.read(projectId)
-    return data.shipped.find(s => s.version === version)
+    return data.shipped.find((s) => s.version === version)
   }
 
   /**
@@ -173,7 +170,7 @@ class ShippedStorage extends StorageManager<ShippedJson> {
     endDate: Date
   ): Promise<ShippedFeature[]> {
     const data = await this.read(projectId)
-    return data.shipped.filter(s => {
+    return data.shipped.filter((s) => {
       const date = new Date(s.shippedAt)
       return date >= startDate && date <= endDate
     })
@@ -205,7 +202,7 @@ class ShippedStorage extends StorageManager<ShippedJson> {
 
     return {
       count: shipped.length,
-      period
+      period,
     }
   }
 }