prjct-cli 0.44.1 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.45.0] - 2026-01-29
+
+### Feature: Smart Context Filtering Tools (PRJ-127)
+
+Terminal tools for AI agents to explore codebases efficiently **without consuming tokens for filtering**.
+
+**New Command: `prjct context <tool>`**
+
+| Tool | Purpose | Compression |
+|------|---------|-------------|
+| `files <task>` | Find relevant files for a task | 93% fewer files |
+| `signatures <path>` | Extract code structure only | ~92% token reduction |
+| `imports <file>` | Analyze dependency graphs | - |
+| `recent [commits]` | Find hot files from git | - |
+| `summary <path>` | Intelligent file summary | ~96% token reduction |
+
+**Real Cost Savings (multi-model support)**
+
+```json
+"cost": {
+  "saved": 2.32,
+  "byModel": [
+    { "model": "claude-sonnet-4.5", "inputSaved": 0.93, "outputPotential": 1.39 },
+    { "model": "gpt-4o", "inputSaved": 0.77, "outputPotential": 0.93 }
+  ]
+}
+```
+
+**Example: Full codebase signatures**
+```bash
+prjct context signatures core/ --recursive
+# 336K → 26K tokens (92% compression)
+# Saves $2.32/call (Sonnet) or $3.87/call (Opus)
+```
+
+**New Files:**
+- `core/context-tools/` - Complete module (7 files)
+- `core/schemas/metrics.ts` - Updated pricing (Jan 2026)
+
 ## [0.44.1] - 2026-01-29
 
 ### Fixed: Workflow Templates with Mandatory Steps (PRJ-143)

package/bin/prjct.ts

@@ -85,6 +85,20 @@ if (args[0] === 'start' || args[0] === 'setup') {
     console.error('Server error:', (error as Error).message)
     process.exitCode = 1
   }
+} else if (args[0] === 'context') {
+  // Context tools - smart context filtering for AI agents
+  const projectPath = process.cwd()
+  const projectId = await configManager.getProjectId(projectPath)
+
+  if (!projectId) {
+    console.error('No prjct project found. Run "prjct init" first.')
+    process.exitCode = 1
+  } else {
+    const { runContextTool } = await import('../core/context-tools')
+    const result = await runContextTool(args.slice(1), projectId, projectPath)
+    console.log(JSON.stringify(result, null, 2))
+    process.exitCode = result.tool === 'error' ? 1 : 0
+  }
 } else if (args[0] === 'linear') {
   // Linear CLI subcommand - direct access to Linear SDK
   const { spawn } = await import('child_process')

package/core/commands/analysis.ts

@@ -18,6 +18,8 @@ import { generateContext } from '../context/generator'
 import commandInstaller from '../infrastructure/command-installer'
 import { syncService } from '../services'
 import { showNextSteps } from '../utils/next-steps'
+import { metricsStorage } from '../storage/metrics-storage'
+import { formatCost } from '../schemas/metrics'
 
 export class AnalysisCommands extends PrjctCommandsBase {
   /**
@@ -311,4 +313,241 @@ export class AnalysisCommands extends PrjctCommandsBase {
     }
   }
 
+  /**
+   * /p:stats - Value dashboard showing accumulated savings and impact
+   *
+   * Displays:
+   * - Token savings (total, compression rate, estimated cost)
+   * - Performance metrics (sync count, avg duration)
+   * - Agent usage breakdown
+   * - 30-day trend visualization
+   */
+  async stats(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean; export?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        return { success: false, error: 'No project ID found' }
+      }
+
+      // Get metrics summary
+      const summary = await metricsStorage.getSummary(projectId)
+      const dailyStats = await metricsStorage.getDailyStats(projectId, 30)
+
+      // JSON output mode
+      if (options.json) {
+        const jsonOutput = {
+          totalTokensSaved: summary.totalTokensSaved,
+          estimatedCostSaved: summary.estimatedCostSaved,
+          compressionRate: summary.compressionRate,
+          syncCount: summary.syncCount,
+          avgSyncDuration: summary.avgSyncDuration,
+          topAgents: summary.topAgents,
+          last30DaysTokens: summary.last30DaysTokens,
+          trend: summary.trend,
+          dailyStats,
+        }
+        console.log(JSON.stringify(jsonOutput, null, 2))
+        return { success: true, data: jsonOutput }
+      }
+
+      // Get project info for header
+      const globalPath = pathManager.getGlobalProjectPath(projectId)
+      let projectName = 'Unknown'
+      try {
+        const fs = require('fs/promises')
+        const path = require('path')
+        const projectJson = JSON.parse(
+          await fs.readFile(path.join(globalPath, 'project.json'), 'utf-8')
+        )
+        projectName = projectJson.name || 'Unknown'
+      } catch {
+        // Use fallback
+      }
+
+      // Determine first sync date
+      const metricsData = await metricsStorage.read(projectId)
+      const firstSyncDate = metricsData.firstSync
+        ? new Date(metricsData.firstSync).toLocaleDateString('en-US', {
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+          })
+        : 'N/A'
+
+      // ASCII Dashboard
+      console.log('')
+      console.log('╭─────────────────────────────────────────────────╮')
+      console.log('│  📊 prjct-cli Value Dashboard                   │')
+      console.log(`│  Project: ${projectName.padEnd(20).slice(0, 20)} | Since: ${firstSyncDate.padEnd(12).slice(0, 12)} │`)
+      console.log('╰─────────────────────────────────────────────────╯')
+      console.log('')
+
+      // Token Savings Section
+      console.log('💰 TOKEN SAVINGS')
+      console.log(`   Total saved:     ${this._formatTokens(summary.totalTokensSaved)} tokens`)
+      console.log(`   Compression:     ${(summary.compressionRate * 100).toFixed(0)}% average reduction`)
+      console.log(`   Estimated cost:  ${formatCost(summary.estimatedCostSaved)} saved`)
+      console.log('')
+
+      // Performance Section
+      console.log('⚡ PERFORMANCE')
+      console.log(`   Syncs completed: ${summary.syncCount.toLocaleString()}`)
+      console.log(`   Avg sync time:   ${this._formatDuration(summary.avgSyncDuration)}`)
+      console.log('')
+
+      // Agent Usage Section
+      if (summary.topAgents.length > 0) {
+        console.log('🤖 AGENT USAGE')
+        const totalUsage = summary.topAgents.reduce((sum, a) => sum + a.usageCount, 0)
+        for (const agent of summary.topAgents) {
+          const pct = totalUsage > 0 ? ((agent.usageCount / totalUsage) * 100).toFixed(0) : 0
+          console.log(`   ${agent.agentName.padEnd(12)}: ${pct}% (${agent.usageCount} uses)`)
+        }
+        console.log('')
+      }
+
+      // 30-Day Trend Section
+      if (dailyStats.length > 0) {
+        console.log('📈 TREND (last 30 days)')
+        const sparkline = this._generateSparkline(dailyStats)
+        console.log(`   ${sparkline} ${this._formatTokens(summary.last30DaysTokens)} tokens saved`)
+
+        if (summary.trend !== 0) {
+          const trendIcon = summary.trend > 0 ? '↑' : '↓'
+          const trendSign = summary.trend > 0 ? '+' : ''
+          console.log(`   ${trendIcon} ${trendSign}${summary.trend.toFixed(0)}% vs previous 30 days`)
+        }
+        console.log('')
+      }
+
+      // Footer
+      console.log('───────────────────────────────────────────────────')
+      console.log(`Export: prjct stats --export > stats.md`)
+      console.log('')
+
+      // Export mode - return markdown
+      if (options.export) {
+        const markdown = this._generateStatsMarkdown(summary, dailyStats, projectName, firstSyncDate)
+        console.log(markdown)
+        return { success: true, data: { markdown } }
+      }
+
+      return {
+        success: true,
+        data: summary,
+      }
+    } catch (error) {
+      console.error('❌ Error:', (error as Error).message)
+      return { success: false, error: (error as Error).message }
+    }
+  }
+
+  // =========== Stats Helper Methods ===========
+
+  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: { tokensSaved: number }[]): 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('')
+  }
+
+  private _generateStatsMarkdown(
+    summary: {
+      totalTokensSaved: number
+      estimatedCostSaved: number
+      compressionRate: number
+      syncCount: number
+      avgSyncDuration: number
+      topAgents: { agentName: string; usageCount: number }[]
+      last30DaysTokens: number
+      trend: number
+    },
+    dailyStats: { date: string; tokensSaved: number; syncs: number }[],
+    projectName: string,
+    firstSyncDate: string
+  ): string {
+    const lines: string[] = []
+
+    lines.push(`# ${projectName} - Value Dashboard`)
+    lines.push('')
+    lines.push(`_Generated: ${new Date().toLocaleString()} | Tracking since: ${firstSyncDate}_`)
+    lines.push('')
+
+    lines.push('## 💰 Token Savings')
+    lines.push('')
+    lines.push(`| Metric | Value |`)
+    lines.push(`|--------|-------|`)
+    lines.push(`| Total saved | ${this._formatTokens(summary.totalTokensSaved)} tokens |`)
+    lines.push(`| Compression | ${(summary.compressionRate * 100).toFixed(0)}% |`)
+    lines.push(`| Cost saved | ${formatCost(summary.estimatedCostSaved)} |`)
+    lines.push('')
+
+    lines.push('## ⚡ Performance')
+    lines.push('')
+    lines.push(`| Metric | Value |`)
+    lines.push(`|--------|-------|`)
+    lines.push(`| Syncs | ${summary.syncCount} |`)
+    lines.push(`| Avg time | ${this._formatDuration(summary.avgSyncDuration)} |`)
+    lines.push('')
+
+    if (summary.topAgents.length > 0) {
+      lines.push('## 🤖 Agent Usage')
+      lines.push('')
+      lines.push(`| Agent | Usage |`)
+      lines.push(`|-------|-------|`)
+      const totalUsage = summary.topAgents.reduce((sum, a) => sum + a.usageCount, 0)
+      for (const agent of summary.topAgents) {
+        const pct = totalUsage > 0 ? ((agent.usageCount / totalUsage) * 100).toFixed(0) : 0
+        lines.push(`| ${agent.agentName} | ${pct}% (${agent.usageCount}) |`)
+      }
+      lines.push('')
+    }
+
+    lines.push('## 📈 30-Day Trend')
+    lines.push('')
+    lines.push(`- Tokens saved: ${this._formatTokens(summary.last30DaysTokens)}`)
+    if (summary.trend !== 0) {
+      const trendSign = summary.trend > 0 ? '+' : ''
+      lines.push(`- Trend: ${trendSign}${summary.trend.toFixed(0)}% vs previous period`)
+    }
+    lines.push('')
+
+    lines.push('---')
+    lines.push('')
+    lines.push('_Generated with [prjct-cli](https://prjct.app)_')
+
+    return lines.join('\n')
+  }
+
 }

package/core/commands/command-data.ts

@@ -142,6 +142,17 @@ export const COMMANDS: CommandMeta[] = [
     hasTemplate: true,
     requiresProject: true,
   },
+  {
+    name: 'stats',
+    group: 'core',
+    description: 'Value dashboard - token savings, performance, and impact',
+    usage: { claude: '/p:stats', terminal: 'prjct stats' },
+    params: '[--json] [--export]',
+    implemented: true,
+    hasTemplate: true,
+    requiresProject: true,
+    features: ['Token savings tracking', 'Compression metrics', 'Cost estimates', '30-day trends'],
+  },
   {
     name: 'sync',
     group: 'core',
@@ -308,13 +319,19 @@ export const COMMANDS: CommandMeta[] = [
   {
     name: 'context',
     group: 'setup',
-    description: 'Get project context as JSON for Claude templates',
-    usage: { claude: null, terminal: 'prjct context <command> [args]' },
-    params: '<command> [args]',
+    description: 'Smart context filtering tools for AI agents',
+    usage: { claude: null, terminal: 'prjct context <tool> [args]' },
+    params: '<tool> [args]',
     implemented: true,
     hasTemplate: false,
     requiresProject: true,
-    features: ['Returns JSON with project context', 'Runs orchestrator', 'Loads agents and skills'],
+    features: [
+      'files - Find relevant files for a task',
+      'signatures - Extract code structure (~90% compression)',
+      'imports - Analyze dependency graphs',
+      'recent - Find hot files from git history',
+      'summary - Intelligent file summarization',
+    ],
   },
 ]
 

package/core/commands/commands.ts

@@ -158,6 +158,10 @@ class PrjctCommands {
     return this.analysis.sync(projectPath, options)
   }
 
+  async stats(projectPath: string = process.cwd(), options: { json?: boolean; export?: boolean } = {}): Promise<CommandResult> {
+    return this.analysis.stats(projectPath, options)
+  }
+
   // ========== Context Commands ==========
 
   async context(input: string | null = null, projectPath: string = process.cwd()): Promise<CommandResult> {

package/core/commands/register.ts

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