prjct-cli 0.44.1 → 0.45.3

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/schemas/outcomes.ts

@@ -32,7 +32,7 @@ export const VarianceReasonSchema = z.enum([
   'requirements_changed',
   'optimistic_estimate',
   'team_changes',
-  'other'
+  'other',
 ])
 
 // -----------------------------------------------------------------------------
@@ -50,11 +50,11 @@ export const EffortComparisonSchema = z.object({
     commits: z.number().optional(),
     linesAdded: z.number().optional(),
     linesRemoved: z.number().optional(),
-    sessions: z.number().optional(),  // Number of work sessions
+    sessions: z.number().optional(), // Number of work sessions
   }),
   variance: z.object({
-    hours: z.number(),          // actual - estimated
-    percentage: z.number(),     // ((actual - estimated) / estimated) * 100
+    hours: z.number(), // actual - estimated
+    percentage: z.number(), // ((actual - estimated) / estimated) * 100
     reason: VarianceReasonSchema.optional(),
     explanation: z.string().optional(),
   }),
@@ -70,8 +70,8 @@ export const MetricResultSchema = z.object({
   target: z.number(),
   actual: z.number(),
   unit: z.string(),
-  achieved: z.boolean(),        // actual >= target (or <= for decrease metrics)
-  percentOfTarget: z.number(),  // (actual / target) * 100
+  achieved: z.boolean(), // actual >= target (or <= for decrease metrics)
+  percentOfTarget: z.number(), // (actual / target) * 100
 })
 
 export const AcceptanceCriteriaResultSchema = z.object({
@@ -84,7 +84,7 @@ export const SuccessTrackingSchema = z.object({
   metrics: z.array(MetricResultSchema),
   acceptanceCriteria: z.array(AcceptanceCriteriaResultSchema),
   overallSuccess: SuccessLevelSchema,
-  successScore: z.number().min(0).max(100),  // Percentage of metrics/criteria met
+  successScore: z.number().min(0).max(100), // Percentage of metrics/criteria met
 })
 
 // -----------------------------------------------------------------------------
@@ -100,11 +100,11 @@ export const LearningSchema = z.object({
     'tooling',
     'architecture',
     'testing',
-    'other'
+    'other',
   ]),
   insight: z.string(),
   actionable: z.boolean(),
-  action: z.string().optional(),  // What to do differently next time
+  action: z.string().optional(), // What to do differently next time
 })
 
 export const LearningsSchema = z.object({
@@ -119,7 +119,7 @@ export const LearningsSchema = z.object({
 // -----------------------------------------------------------------------------
 
 export const ROIAssessmentSchema = z.object({
-  valueDelivered: z.number().min(1).max(10),    // Subjective 1-10 score
+  valueDelivered: z.number().min(1).max(10), // Subjective 1-10 score
   userImpact: z.enum(['none', 'low', 'medium', 'high', 'critical']),
   businessImpact: z.enum(['none', 'low', 'medium', 'high', 'critical']),
 
@@ -140,7 +140,7 @@ export const ROIAssessmentSchema = z.object({
 // -----------------------------------------------------------------------------
 
 export const TaskOutcomeSchema = z.object({
-  id: z.string(),                 // out_task_xxxxxxxx
+  id: z.string(), // out_task_xxxxxxxx
   taskId: z.string(),
   description: z.string(),
 
@@ -167,12 +167,12 @@ export const TaskOutcomeSchema = z.object({
 // -----------------------------------------------------------------------------
 
 export const FeatureOutcomeSchema = z.object({
-  id: z.string(),                 // out_feat_xxxxxxxx
+  id: z.string(), // out_feat_xxxxxxxx
 
   // Links
   featureId: z.string(),
   featureName: z.string(),
-  prdId: z.string().nullable(),   // null for legacy features
+  prdId: z.string().nullable(), // null for legacy features
 
   // Version info
   version: z.string().optional(),
@@ -200,11 +200,11 @@ export const FeatureOutcomeSchema = z.object({
   // Timestamps
   startedAt: z.string(),
   shippedAt: z.string(),
-  reviewedAt: z.string().optional(),  // When impact was captured
+  reviewedAt: z.string().optional(), // When impact was captured
 
   // Metadata
-  reviewedBy: z.string().optional(),  // Who filled out the impact review
-  legacy: z.boolean().optional(),     // Legacy feature (no PRD)
+  reviewedBy: z.string().optional(), // Who filled out the impact review
+  legacy: z.boolean().optional(), // Legacy feature (no PRD)
 })
 
 // -----------------------------------------------------------------------------
@@ -213,8 +213,8 @@ export const FeatureOutcomeSchema = z.object({
 
 export const AggregateMetricsSchema = z.object({
   totalFeatures: z.number(),
-  averageEstimationAccuracy: z.number(),  // Percentage
-  averageSuccessRate: z.number(),         // Percentage
+  averageEstimationAccuracy: z.number(), // Percentage
+  averageSuccessRate: z.number(), // Percentage
   averageROI: z.number(),
 
   // By category
@@ -226,17 +226,21 @@ export const AggregateMetricsSchema = z.object({
   }),
 
   // Variance patterns
-  variancePatterns: z.array(z.object({
-    reason: VarianceReasonSchema,
-    count: z.number(),
-    averageVariance: z.number(),
-  })),
+  variancePatterns: z.array(
+    z.object({
+      reason: VarianceReasonSchema,
+      count: z.number(),
+      averageVariance: z.number(),
+    })
+  ),
 
   // Top learnings (aggregated)
-  topLearnings: z.array(z.object({
-    insight: z.string(),
-    frequency: z.number(),
-  })),
+  topLearnings: z.array(
+    z.object({
+      insight: z.string(),
+      frequency: z.number(),
+    })
+  ),
 })
 
 // -----------------------------------------------------------------------------
@@ -245,7 +249,7 @@ export const AggregateMetricsSchema = z.object({
 
 export const OutcomesJsonSchema = z.object({
   outcomes: z.array(FeatureOutcomeSchema),
-  taskOutcomes: z.array(TaskOutcomeSchema).optional(),  // Standalone task outcomes
+  taskOutcomes: z.array(TaskOutcomeSchema).optional(), // Standalone task outcomes
   aggregates: AggregateMetricsSchema.optional(),
   lastUpdated: z.string(),
   lastAggregated: z.string().optional(),
@@ -286,7 +290,8 @@ export const parseOutcomes = (data: unknown): OutcomesJson => OutcomesJsonSchema
 export const safeParseOutcomes = (data: unknown) => OutcomesJsonSchema.safeParse(data)
 
 /** Parse a single feature outcome */
-export const parseFeatureOutcome = (data: unknown): FeatureOutcome => FeatureOutcomeSchema.parse(data)
+export const parseFeatureOutcome = (data: unknown): FeatureOutcome =>
+  FeatureOutcomeSchema.parse(data)
 export const safeParseFeatureOutcome = (data: unknown) => FeatureOutcomeSchema.safeParse(data)
 
 // =============================================================================
@@ -335,7 +340,7 @@ export const calculateVariance = (
  */
 export const calculateROIScore = (valueDelivered: number, actualHours: number): number => {
   if (actualHours <= 0) return valueDelivered * 10
-  return Math.round((valueDelivered * 10 / actualHours) * 100) / 100
+  return Math.round(((valueDelivered * 10) / actualHours) * 100) / 100
 }
 
 /**
@@ -348,8 +353,8 @@ export const calculateSuccessScore = (
   const totalItems = metrics.length + acceptanceCriteria.length
   if (totalItems === 0) return 100
 
-  const metMetrics = metrics.filter(m => m.achieved).length
-  const metCriteria = acceptanceCriteria.filter(ac => ac.met).length
+  const metMetrics = metrics.filter((m) => m.achieved).length
+  const metCriteria = acceptanceCriteria.filter((ac) => ac.met).length
 
   return Math.round(((metMetrics + metCriteria) / totalItems) * 100)
 }
@@ -389,34 +394,33 @@ export const aggregateOutcomes = (outcomes: FeatureOutcome[]): AggregateMetrics
   }
 
   // Calculate averages
-  const accuracies = outcomes.map(o =>
-    calculateEstimationAccuracy(o.effort.variance.percentage)
-  )
-  const successRates = outcomes
-    .filter(o => o.success)
-    .map(o => o.success!.successScore)
-  const rois = outcomes.map(o => o.roi.roiScore)
+  const accuracies = outcomes.map((o) => calculateEstimationAccuracy(o.effort.variance.percentage))
+  const successRates = outcomes.filter((o) => o.success).map((o) => o.success!.successScore)
+  const rois = outcomes.map((o) => o.roi.roiScore)
 
   // Count by success level
   const bySuccessLevel = {
-    exceeded: outcomes.filter(o => o.success?.overallSuccess === 'exceeded').length,
-    met: outcomes.filter(o => o.success?.overallSuccess === 'met').length,
-    partial: outcomes.filter(o => o.success?.overallSuccess === 'partial').length,
-    failed: outcomes.filter(o => o.success?.overallSuccess === 'failed').length,
+    exceeded: outcomes.filter((o) => o.success?.overallSuccess === 'exceeded').length,
+    met: outcomes.filter((o) => o.success?.overallSuccess === 'met').length,
+    partial: outcomes.filter((o) => o.success?.overallSuccess === 'partial').length,
+    failed: outcomes.filter((o) => o.success?.overallSuccess === 'failed').length,
   }
 
   // Variance patterns
   const varianceReasons = outcomes
-    .filter(o => o.effort.variance.reason)
-    .reduce((acc, o) => {
-      const reason = o.effort.variance.reason!
-      if (!acc[reason]) {
-        acc[reason] = { count: 0, totalVariance: 0 }
-      }
-      acc[reason].count++
-      acc[reason].totalVariance += o.effort.variance.percentage
-      return acc
-    }, {} as Record<VarianceReason, { count: number; totalVariance: number }>)
+    .filter((o) => o.effort.variance.reason)
+    .reduce(
+      (acc, o) => {
+        const reason = o.effort.variance.reason!
+        if (!acc[reason]) {
+          acc[reason] = { count: 0, totalVariance: 0 }
+        }
+        acc[reason].count++
+        acc[reason].totalVariance += o.effort.variance.percentage
+        return acc
+      },
+      {} as Record<VarianceReason, { count: number; totalVariance: number }>
+    )
 
   const variancePatterns = Object.entries(varianceReasons).map(([reason, data]) => ({
     reason: reason as VarianceReason,
@@ -425,14 +429,17 @@ export const aggregateOutcomes = (outcomes: FeatureOutcome[]): AggregateMetrics
   }))
 
   // Top learnings
-  const allLearnings = outcomes.flatMap(o => [
+  const allLearnings = outcomes.flatMap((o) => [
     ...o.learnings.whatWorked,
     ...o.learnings.whatDidnt,
   ])
-  const learningCounts = allLearnings.reduce((acc, learning) => {
-    acc[learning] = (acc[learning] || 0) + 1
-    return acc
-  }, {} as Record<string, number>)
+  const learningCounts = allLearnings.reduce(
+    (acc, learning) => {
+      acc[learning] = (acc[learning] || 0) + 1
+      return acc
+    },
+    {} as Record<string, number>
+  )
 
   const topLearnings = Object.entries(learningCounts)
     .sort((a, b) => b[1] - a[1])
@@ -444,10 +451,11 @@ export const aggregateOutcomes = (outcomes: FeatureOutcome[]): AggregateMetrics
     averageEstimationAccuracy: Math.round(
       accuracies.reduce((a, b) => a + b, 0) / accuracies.length
     ),
-    averageSuccessRate: successRates.length > 0
-      ? Math.round(successRates.reduce((a, b) => a + b, 0) / successRates.length)
-      : 0,
-    averageROI: Math.round(rois.reduce((a, b) => a + b, 0) / rois.length * 100) / 100,
+    averageSuccessRate:
+      successRates.length > 0
+        ? Math.round(successRates.reduce((a, b) => a + b, 0) / successRates.length)
+        : 0,
+    averageROI: Math.round((rois.reduce((a, b) => a + b, 0) / rois.length) * 100) / 100,
     bySuccessLevel,
     variancePatterns,
     topLearnings,

package/core/schemas/permissions.ts

@@ -38,11 +38,13 @@ export const PermissionsConfigSchema = z.object({
   bash: BashPermissionSchema.optional(),
 
   /** File operation permissions - glob patterns */
-  files: z.object({
-    read: FilePermissionSchema.optional(),
-    write: FilePermissionSchema.optional(),
-    delete: FilePermissionSchema.optional(),
-  }).optional(),
+  files: z
+    .object({
+      read: FilePermissionSchema.optional(),
+      write: FilePermissionSchema.optional(),
+      delete: FilePermissionSchema.optional(),
+    })
+    .optional(),
 
   /** Web fetch permissions */
   web: WebPermissionSchema.optional(),
@@ -51,10 +53,12 @@ export const PermissionsConfigSchema = z.object({
   skills: z.record(z.string(), PermissionLevelSchema).optional(),
 
   /** Doom loop protection - prevent infinite retries */
-  doomLoop: z.object({
-    enabled: z.boolean().default(true),
-    maxRetries: z.number().default(3),
-  }).optional(),
+  doomLoop: z
+    .object({
+      enabled: z.boolean().default(true),
+      maxRetries: z.number().default(3),
+    })
+    .optional(),
 
   /** External directory access */
   externalDirectories: PermissionLevelSchema.default('ask'),
@@ -117,7 +121,7 @@ export const DEFAULT_BASH_ASK: string[] = [
 export const DEFAULT_BASH_DENY: string[] = [
   'rm -rf /*',
   'rm -rf ~/*',
-  ':(){ :|:& };:*',  // Fork bomb
+  ':(){ :|:& };:*', // Fork bomb
   'mkfs*',
   'dd if=*of=/dev/*',
 ]
@@ -167,8 +171,7 @@ export function buildDefaultPermissions(): PermissionsConfig {
 export const parsePermissions = (data: unknown): PermissionsConfig =>
   PermissionsConfigSchema.parse(data)
 
-export const safeParsePermissions = (data: unknown) =>
-  PermissionsConfigSchema.safeParse(data)
+export const safeParsePermissions = (data: unknown) => PermissionsConfigSchema.safeParse(data)
 
 // =============================================================================
 // Defaults

package/core/schemas/prd.ts

@@ -16,7 +16,13 @@ import { z } from 'zod'
 // Zod Schemas - Source of Truth
 // =============================================================================
 
-export const PRDStatusSchema = z.enum(['draft', 'approved', 'in_progress', 'completed', 'cancelled'])
+export const PRDStatusSchema = z.enum([
+  'draft',
+  'approved',
+  'in_progress',
+  'completed',
+  'cancelled',
+])
 export const PRDSizeSchema = z.enum(['XS', 'S', 'M', 'L', 'XL'])
 export const ImpactLevelSchema = z.enum(['critical', 'high', 'medium', 'low'])
 export const ConfidenceLevelSchema = z.enum(['low', 'medium', 'high'])
@@ -87,10 +93,14 @@ export const APIEndpointSchema = z.object({
   auth: z.enum(['required', 'optional', 'none']),
   input: z.record(z.string()).optional(),
   output: z.record(z.string()).optional(),
-  errors: z.array(z.object({
-    code: z.number(),
-    description: z.string(),
-  })).optional(),
+  errors: z
+    .array(
+      z.object({
+        code: z.number(),
+        description: z.string(),
+      })
+    )
+    .optional(),
 })
 
 export const APIContractsSchema = z.object({
@@ -180,10 +190,10 @@ export const ImplementationPhaseSchema = z.object({
 })
 
 export const MVPScopeSchema = z.object({
-  p0: z.array(z.string()),  // Must-have
-  p1: z.array(z.string()),  // Should-have
-  p2: z.array(z.string()),  // Nice-to-have
-  p3: z.array(z.string()),  // Future
+  p0: z.array(z.string()), // Must-have
+  p1: z.array(z.string()), // Should-have
+  p2: z.array(z.string()), // Nice-to-have
+  p3: z.array(z.string()), // Future
 })
 
 export const ImplementationRoadmapSchema = z.object({
@@ -265,7 +275,7 @@ export const PRDOutcomesSchema = z.object({
 // -----------------------------------------------------------------------------
 
 export const PRDItemSchema = z.object({
-  id: z.string(),                           // prd_xxxxxxxx
+  id: z.string(), // prd_xxxxxxxx
   title: z.string(),
   status: PRDStatusSchema,
   size: PRDSizeSchema,
@@ -286,9 +296,9 @@ export const PRDItemSchema = z.object({
   value: ValueAssessmentSchema.optional(),
 
   // Links (for integration)
-  featureId: z.string().nullable(),         // Link to roadmap feature
-  phase: z.string().nullable(),             // P0, P1, etc.
-  quarter: z.string().nullable(),           // Q1-2026, etc.
+  featureId: z.string().nullable(), // Link to roadmap feature
+  phase: z.string().nullable(), // P0, P1, etc.
+  quarter: z.string().nullable(), // Q1-2026, etc.
 
   // Metadata
   createdAt: z.string(),
@@ -358,7 +368,10 @@ export const safeParsePRD = (data: unknown) => PRDItemSchema.safeParse(data)
 // Defaults
 // =============================================================================
 
-export const DEFAULT_PRD: Omit<PRDItem, 'id' | 'title' | 'problem' | 'roadmap' | 'estimation' | 'successCriteria'> = {
+export const DEFAULT_PRD: Omit<
+  PRDItem,
+  'id' | 'title' | 'problem' | 'roadmap' | 'estimation' | 'successCriteria'
+> = {
   status: 'draft',
   size: 'M',
   featureId: null,

package/core/schemas/project.ts

@@ -23,8 +23,8 @@ export const ProjectItemSchema = z.object({
   techStack: z.array(z.string()),
   fileCount: z.number(),
   commitCount: z.number(),
-  createdAt: z.string(),        // ISO8601
-  lastSync: z.string(),         // ISO8601
+  createdAt: z.string(), // ISO8601
+  lastSync: z.string(), // ISO8601
 })
 
 // =============================================================================
@@ -50,5 +50,5 @@ export const DEFAULT_PROJECT: Omit<ProjectSchema, 'projectId' | 'name' | 'repoPa
   fileCount: 0,
   commitCount: 0,
   createdAt: new Date().toISOString(),
-  lastSync: new Date().toISOString()
+  lastSync: new Date().toISOString(),
 }