prjct-cli 0.44.1 → 0.45.0

package/core/context-tools/types.ts

@@ -0,0 +1,253 @@
+/**
+ * Context Tools Types
+ *
+ * Shared interfaces for all context filtering tools.
+ * These tools are designed for AI agents to efficiently explore
+ * codebases WITHOUT consuming tokens for filtering.
+ *
+ * @module context-tools/types
+ * @version 1.0.0
+ */
+
+// =============================================================================
+// Token Measurement Types
+// =============================================================================
+
+/**
+ * Cost savings breakdown by model
+ */
+export interface CostBreakdown {
+  model: string
+  inputSaved: number      // $ saved on input tokens
+  outputPotential: number // $ potential savings on output (estimated)
+  total: number           // Combined savings
+}
+
+/**
+ * Token measurement result
+ */
+export interface TokenMetrics {
+  tokens: {
+    original: number
+    filtered: number
+    saved: number
+  }
+  compression: number     // 0-1 (e.g., 0.90 = 90% reduction)
+  cost: {
+    saved: number         // $ saved (using default model)
+    formatted: string     // Human-readable (e.g., "$0.02")
+    byModel: CostBreakdown[] // Breakdown by popular models
+  }
+}
+
+// =============================================================================
+// Files Tool Types
+// =============================================================================
+
+/**
+ * Relevance score reasons
+ */
+export type ScoreReason =
+  | `keyword:${string}` // Matched keyword in path
+  | `domain:${string}` // Matched domain pattern
+  | `recent:${string}` // Recently modified (e.g., "3d" = 3 days)
+  | `import:${number}` // Import distance from entry point
+  | `extension:${string}` // File extension match
+
+/**
+ * File with relevance score
+ */
+export interface ScoredFile {
+  path: string
+  score: number // 0-1
+  reasons: ScoreReason[]
+}
+
+/**
+ * Files tool output
+ */
+export interface FilesToolOutput {
+  files: ScoredFile[]
+  metrics: {
+    filesScanned: number
+    filesReturned: number
+    scanDuration: number // ms
+  }
+}
+
+// =============================================================================
+// Signatures Tool Types
+// =============================================================================
+
+/**
+ * Code signature types
+ */
+export type SignatureType =
+  | 'function'
+  | 'method'
+  | 'class'
+  | 'interface'
+  | 'type'
+  | 'enum'
+  | 'const'
+  | 'variable'
+  | 'export'
+  | 'import'
+
+/**
+ * Extracted code signature
+ */
+export interface CodeSignature {
+  type: SignatureType
+  name: string
+  signature: string // Full signature string (e.g., "(token: string) => Promise<User>")
+  exported: boolean
+  line: number
+  docstring?: string
+}
+
+/**
+ * Signatures tool output
+ */
+export interface SignaturesToolOutput {
+  file: string
+  language: string
+  signatures: CodeSignature[]
+  fallback: boolean // True if full file was returned (no grammar)
+  fallbackReason?: string
+  metrics: TokenMetrics
+}
+
+// =============================================================================
+// Imports Tool Types
+// =============================================================================
+
+/**
+ * Import relationship
+ */
+export interface ImportRelation {
+  source: string // Import path (e.g., "./types", "lodash")
+  resolved: string | null // Resolved file path (null for external)
+  isExternal: boolean
+  importedNames?: string[] // Named imports
+  isDefault?: boolean
+  isNamespace?: boolean // import * as X
+}
+
+/**
+ * File that imports the target
+ */
+export interface ImportedBy {
+  file: string
+  importedNames?: string[]
+}
+
+/**
+ * Dependency tree node
+ */
+export interface DependencyNode {
+  file: string
+  imports: DependencyNode[]
+  depth: number
+}
+
+/**
+ * Imports tool output
+ */
+export interface ImportsToolOutput {
+  file: string
+  imports: ImportRelation[]
+  importedBy: ImportedBy[]
+  dependencyTree?: DependencyNode
+  metrics: {
+    totalImports: number
+    externalImports: number
+    internalImports: number
+    importedByCount: number
+  }
+}
+
+// =============================================================================
+// Recent Tool Types
+// =============================================================================
+
+/**
+ * Hot file from git analysis
+ */
+export interface HotFile {
+  path: string
+  changes: number // Number of commits touching this file
+  heatScore: number // 0-1 normalized score
+  lastChanged: string // Human-readable (e.g., "2h ago", "3d ago")
+  lastChangedAt: string // ISO timestamp
+}
+
+/**
+ * Recent tool output
+ */
+export interface RecentToolOutput {
+  hotFiles: HotFile[]
+  branchOnlyFiles: string[] // Files only changed in current branch
+  metrics: {
+    commitsAnalyzed: number
+    totalFilesChanged: number
+    filesReturned: number
+    analysisWindow: string // e.g., "30 commits", "main..HEAD"
+  }
+}
+
+// =============================================================================
+// Summary Tool Types
+// =============================================================================
+
+/**
+ * Public API entry
+ */
+export interface PublicAPIEntry {
+  name: string
+  type: SignatureType
+  signature: string
+  description?: string // From JSDoc/docstring
+}
+
+/**
+ * Summary tool output
+ */
+export interface SummaryToolOutput {
+  file: string
+  purpose: string // Short description of file purpose
+  publicAPI: PublicAPIEntry[]
+  dependencies: string[] // Key dependencies
+  metrics: TokenMetrics
+}
+
+// =============================================================================
+// Context Tool Usage Tracking
+// =============================================================================
+
+/**
+ * Tool usage record for metrics
+ */
+export interface ContextToolUsage {
+  tool: 'files' | 'signatures' | 'imports' | 'recent' | 'summary'
+  timestamp: string
+  inputArgs: string
+  tokensSaved: number
+  compressionRate: number
+  duration: number // ms
+}
+
+// =============================================================================
+// Main Tool Result Type
+// =============================================================================
+
+/**
+ * Union type for all tool outputs
+ */
+export type ContextToolOutput =
+  | { tool: 'files'; result: FilesToolOutput }
+  | { tool: 'signatures'; result: SignaturesToolOutput }
+  | { tool: 'imports'; result: ImportsToolOutput }
+  | { tool: 'recent'; result: RecentToolOutput }
+  | { tool: 'summary'; result: SummaryToolOutput }
+  | { tool: 'error'; result: { error: string; code: string } }

package/core/index.ts

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

package/core/schemas/metrics.ts

@@ -0,0 +1,143 @@
+/**
+ * Metrics Schema
+ *
+ * Defines the structure for metrics.json - value dashboard metrics.
+ * Tracks token savings, sync performance, and usage trends.
+ *
+ * Uses Zod for runtime validation and TypeScript type inference.
+ * @version 1.0.0
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
+
+/**
+ * Daily stats for trend analysis
+ */
+export const DailyStatsSchema = z.object({
+  date: z.string(),                    // YYYY-MM-DD
+  tokensSaved: z.number(),             // Tokens saved that day
+  syncs: z.number(),                   // Number of syncs
+  avgCompressionRate: z.number(),      // Average compression rate (0-1)
+  totalDuration: z.number(),           // Total sync time in ms
+})
+
+/**
+ * Agent usage tracking
+ */
+export const AgentUsageSchema = z.object({
+  agentName: z.string(),               // e.g., "backend", "frontend"
+  usageCount: z.number(),              // Times invoked
+  tokensSaved: z.number(),             // Tokens saved by this agent
+})
+
+/**
+ * Main metrics JSON structure
+ */
+export const MetricsJsonSchema = z.object({
+  // Token metrics
+  totalTokensSaved: z.number(),
+  avgCompressionRate: z.number(),      // 0-1 (e.g., 0.63 = 63% reduction)
+
+  // Sync metrics
+  syncCount: z.number(),
+  watchTriggers: z.number(),           // Auto-syncs from watch mode
+  avgSyncDuration: z.number(),         // Average in ms
+  totalSyncDuration: z.number(),       // Total in ms
+
+  // Agent usage
+  agentUsage: z.array(AgentUsageSchema),
+
+  // Time series for trends
+  dailyStats: z.array(DailyStatsSchema),
+
+  // Metadata
+  firstSync: z.string(),               // ISO8601 - when tracking started
+  lastUpdated: z.string(),             // ISO8601
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type DailyStats = z.infer<typeof DailyStatsSchema>
+export type AgentUsage = z.infer<typeof AgentUsageSchema>
+export type MetricsJson = z.infer<typeof MetricsJsonSchema>
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Parse and validate metrics.json content */
+export const parseMetrics = (data: unknown): MetricsJson => MetricsJsonSchema.parse(data)
+
+/** Safe parse with error result */
+export const safeParseMetrics = (data: unknown) => MetricsJsonSchema.safeParse(data)
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_METRICS: MetricsJson = {
+  totalTokensSaved: 0,
+  avgCompressionRate: 0,
+  syncCount: 0,
+  watchTriggers: 0,
+  avgSyncDuration: 0,
+  totalSyncDuration: 0,
+  agentUsage: [],
+  dailyStats: [],
+  firstSync: '',
+  lastUpdated: '',
+}
+
+// =============================================================================
+// Cost Calculation Constants (January 2026 Pricing)
+// =============================================================================
+
+/**
+ * Token costs per 1000 tokens (INPUT pricing)
+ * Source: https://docs.anthropic.com/en/docs/about-claude/models
+ *
+ * Used for estimating cost savings from context compression
+ */
+export const TOKEN_COSTS = {
+  // Current models (2026)
+  'claude-opus-4.5': 0.005,      // $5/M input - flagship
+  'claude-sonnet-4.5': 0.003,    // $3/M input - balanced
+  'claude-haiku-4.5': 0.001,     // $1/M input - fastest
+  // Legacy models
+  'claude-opus-4': 0.015,        // $15/M input
+  'claude-sonnet-4': 0.003,      // $3/M input
+  'claude-3-opus': 0.015,        // $15/M input (deprecated)
+  'claude-3-sonnet': 0.003,      // $3/M input (deprecated)
+  // Other providers
+  'gpt-4o': 0.0025,              // $2.50/M input
+  'gpt-4': 0.01,                 // $10/M input (legacy)
+  'gemini-pro': 0.00125,         // $1.25/M input
+  // Default: Claude Sonnet (most common for Claude Code)
+  default: 0.003,                // $3/M input
+} as const
+
+export type ModelName = keyof typeof TOKEN_COSTS
+
+/**
+ * Calculate estimated cost saved based on tokens
+ */
+export function estimateCostSaved(tokens: number, model: ModelName = 'default'): number {
+  const costPer1k = TOKEN_COSTS[model] || TOKEN_COSTS.default
+  return (tokens / 1000) * costPer1k
+}
+
+/**
+ * Format cost as currency string
+ */
+export function formatCost(cost: number): string {
+  if (cost < 0.01) {
+    return `$${(cost * 100).toFixed(2)}¢`
+  }
+  return `$${cost.toFixed(2)}`
+}

package/core/services/sync-service.ts

@@ -22,6 +22,7 @@ import { promisify } from 'util'
 import pathManager from '../infrastructure/path-manager'
 import configManager from '../infrastructure/config-manager'
 import dateHelper from '../utils/date-helper'
+import { metricsStorage } from '../storage/metrics-storage'
 import {
   generateAIToolContexts,
   DEFAULT_AI_TOOLS,
@@ -91,6 +92,13 @@ interface AIToolResult {
   success: boolean
 }
 
+interface SyncMetrics {
+  duration: number           // Sync duration in ms
+  originalSize: number       // Estimated tokens before compression
+  filteredSize: number       // Actual tokens in context files
+  compressionRate: number    // Percentage saved
+}
+
 interface SyncResult {
   success: boolean
   projectId: string
@@ -103,6 +111,7 @@ interface SyncResult {
   skills: { agent: string; skill: string }[]
   contextFiles: string[]
   aiTools: AIToolResult[]
+  syncMetrics?: SyncMetrics
   error?: string
 }
 
@@ -129,6 +138,7 @@ class SyncService {
    */
   async sync(projectPath: string = process.cwd(), options: SyncOptions = {}): Promise<SyncResult> {
     this.projectPath = projectPath
+    const startTime = Date.now()
 
     // Resolve AI tools: supports 'auto', 'all', or specific list
     let aiToolIds: string[]
@@ -217,6 +227,15 @@ class SyncService {
       // 8. Log to memory
       await this.logToMemory(git, stats)
 
+      // 9. Record metrics for value dashboard
+      const duration = Date.now() - startTime
+      const syncMetrics = await this.recordSyncMetrics(
+        stats,
+        contextFiles,
+        agents,
+        duration
+      )
+
       return {
         success: true,
         projectId: this.projectId,
@@ -233,6 +252,7 @@ class SyncService {
           outputFile: r.outputFile,
           success: r.success,
         })),
+        syncMetrics,
       }
     } catch (error) {
       return {
@@ -1067,6 +1087,85 @@ ${
     await fs.appendFile(memoryPath, JSON.stringify(event) + '\n', 'utf-8')
   }
 
+  // ==========================================================================
+  // METRICS RECORDING
+  // ==========================================================================
+
+  /**
+   * Record sync metrics for the value dashboard
+   *
+   * Calculates token savings by comparing:
+   * - Original: Estimated tokens if we sent all source files
+   * - Filtered: Actual tokens in generated context files
+   *
+   * Token estimation: ~4 chars per token (industry standard)
+   */
+  private async recordSyncMetrics(
+    stats: ProjectStats,
+    contextFiles: string[],
+    agents: AgentInfo[],
+    duration: number
+  ): Promise<SyncMetrics> {
+    const CHARS_PER_TOKEN = 4
+
+    // Calculate filtered size (actual context files generated)
+    let filteredChars = 0
+    for (const file of contextFiles) {
+      try {
+        const filePath = path.join(this.globalPath, file)
+        const content = await fs.readFile(filePath, 'utf-8')
+        filteredChars += content.length
+      } catch {
+        // File might not exist, skip
+      }
+    }
+
+    // Also count agent files
+    for (const agent of agents) {
+      try {
+        const agentPath = path.join(this.globalPath, 'agents', `${agent.name}.md`)
+        const content = await fs.readFile(agentPath, 'utf-8')
+        filteredChars += content.length
+      } catch {
+        // Skip if not found
+      }
+    }
+
+    const filteredSize = Math.floor(filteredChars / CHARS_PER_TOKEN)
+
+    // Estimate original size (what it would take without prjct)
+    // Conservative estimate: avg 500 tokens per source file
+    // Plus overhead for manually creating context
+    const avgTokensPerFile = 500
+    const originalSize = stats.fileCount * avgTokensPerFile
+
+    // Calculate compression rate
+    const compressionRate = originalSize > 0
+      ? Math.max(0, (originalSize - filteredSize) / originalSize)
+      : 0
+
+    // Record to storage
+    try {
+      await metricsStorage.recordSync(this.projectId!, {
+        originalSize,
+        filteredSize,
+        duration,
+        isWatch: false,
+        agents: agents.filter(a => a.type === 'domain').map(a => a.name),
+      })
+    } catch (error) {
+      // Non-blocking - metrics are nice to have
+      console.error('Warning: Failed to record metrics:', (error as Error).message)
+    }
+
+    return {
+      duration,
+      originalSize,
+      filteredSize,
+      compressionRate,
+    }
+  }
+
   // ==========================================================================
   // HELPERS
   // ==========================================================================

package/core/storage/index.ts

@@ -40,6 +40,7 @@ export { stateStorage } from './state-storage'
 export { queueStorage } from './queue-storage'
 export { ideasStorage } from './ideas-storage'
 export { shippedStorage } from './shipped-storage'
+export { metricsStorage } from './metrics-storage'
 
 // ========== GRANULAR STORAGE (Legacy) ==========
 export { getStorage, default } from './storage'
@@ -53,4 +54,7 @@ export type {
   IdeaPriority,
   ShippedFeature,
   ShippedJson,
+  DailyStats,
+  AgentUsage,
+  MetricsJson,
 } from '../types'