prjct-cli 0.44.1 → 0.45.3

package/core/types/storage.ts

@@ -146,3 +146,52 @@ export interface IdeasJson {
   ideas: Idea[]
   lastUpdated: string
 }
+
+// =============================================================================
+// Metrics Storage Types
+// =============================================================================
+
+/**
+ * Daily stats for trend analysis
+ */
+export interface DailyStats {
+  date: string // YYYY-MM-DD
+  tokensSaved: number // Tokens saved that day
+  syncs: number // Number of syncs
+  avgCompressionRate: number // Average compression rate (0-1)
+  totalDuration: number // Total sync time in ms
+}
+
+/**
+ * Agent usage tracking
+ */
+export interface AgentUsage {
+  agentName: string // e.g., "backend", "frontend"
+  usageCount: number // Times invoked
+  tokensSaved: number // Tokens saved by this agent
+}
+
+/**
+ * Metrics collection for value dashboard
+ */
+export interface MetricsJson {
+  // Token metrics
+  totalTokensSaved: number
+  avgCompressionRate: number // 0-1 (e.g., 0.63 = 63% reduction)
+
+  // Sync metrics
+  syncCount: number
+  watchTriggers: number // Auto-syncs from watch mode
+  avgSyncDuration: number // Average in ms
+  totalSyncDuration: number // Total in ms
+
+  // Agent usage
+  agentUsage: AgentUsage[]
+
+  // Time series for trends
+  dailyStats: DailyStats[]
+
+  // Metadata
+  firstSync: string // ISO8601 - when tracking started
+  lastUpdated: string // ISO8601
+}

package/core/types/utils.ts

@@ -5,12 +5,12 @@
 
 // Re-export file system types
 export {
-  NodeError,
-  isNotFoundError,
-  isPermissionError,
   isDirNotEmptyError,
   isFileExistsError,
   isNodeError,
+  isNotFoundError,
+  isPermissionError,
+  NodeError,
 } from './fs'
 
 export type AsyncFunction<T = unknown> = (...args: unknown[]) => Promise<T>

package/core/utils/agent-stream.ts

@@ -118,7 +118,9 @@ class AgentStream {
   complete(taskName: string, totalDuration?: number): void {
     if (this.quiet) return
 
-    const durationStr = totalDuration ? ` ${chalk.dim(`[${this.formatDuration(totalDuration)}]`)}` : ''
+    const durationStr = totalDuration
+      ? ` ${chalk.dim(`[${this.formatDuration(totalDuration)}]`)}`
+      : ''
     console.log(chalk.green(`✅ ${taskName}${durationStr}`))
   }
 

package/core/utils/animations.ts

@@ -132,15 +132,15 @@ function sleep(ms: number): Promise<void> {
 
 export async function animate(frameList: string[], duration = 100): Promise<void> {
   for (const frame of frameList) {
-    process.stdout.write('\r' + frame)
+    process.stdout.write(`\r${frame}`)
     await sleep(duration)
   }
-  process.stdout.write('\r' + ' '.repeat(30) + '\r')
+  process.stdout.write(`\r${' '.repeat(30)}\r`)
 }
 
 export async function typeWriter(text: string, delay = 30): Promise<void> {
   for (let i = 0; i <= text.length; i++) {
-    process.stdout.write('\r' + text.slice(0, i) + (i < text.length ? '▋' : ''))
+    process.stdout.write(`\r${text.slice(0, i)}${i < text.length ? '▋' : ''}`)
     await sleep(delay)
   }
   process.stdout.write('\n')
@@ -154,8 +154,8 @@ export async function progressBar(duration = 1000, label = 'Processing'): Promis
     const percent = Math.round((i / steps) * 100)
     const filled = '▓'.repeat(i)
     const empty = '░'.repeat(steps - i)
-    const bar = `${colors.dim(label)} [${colors.primary(filled)}${colors.dim(empty)}] ${colors.text(percent + '%')}`
-    process.stdout.write('\r' + bar)
+    const bar = `${colors.dim(label)} [${colors.primary(filled)}${colors.dim(empty)}] ${colors.text(`${percent}%`)}`
+    process.stdout.write(`\r${bar}`)
     await sleep(stepDuration)
   }
   process.stdout.write('\n')
@@ -168,9 +168,9 @@ export async function sparkle(message: string): Promise<void> {
   for (let i = 0; i < 3; i++) {
     const spark = sparkles[Math.floor(Math.random() * sparkles.length)]
     output = `${spark} ${message} ${spark}`
-    process.stdout.write('\r' + output)
+    process.stdout.write(`\r${output}`)
     await sleep(200)
-    process.stdout.write('\r' + ' '.repeat(output.length))
+    process.stdout.write(`\r${' '.repeat(output.length)}`)
     await sleep(100)
   }
 
@@ -216,13 +216,17 @@ ${colors.dim('Added to your ideas backlog')}
   `
 }
 
-export function formatCleanup(filesRemoved: number, tasksArchived: number, spaceFeed: number): string {
+export function formatCleanup(
+  filesRemoved: number,
+  tasksArchived: number,
+  spaceFeed: number
+): string {
   return `
 ${banners.cleanup}
 
 ${colors.text('🗑️  Files removed:')} ${colors.success.bold(String(filesRemoved))}
 ${colors.text('📦 Tasks archived:')} ${colors.success.bold(String(tasksArchived))}
-${colors.text('💾 Space freed:')} ${colors.success.bold(spaceFeed + ' MB')}
+${colors.text('💾 Space freed:')} ${colors.success.bold(`${spaceFeed} MB`)}
 
 ${colors.celebrate('✨ Your project is clean and lean!')}
   `
@@ -261,6 +265,5 @@ export default {
   formatError,
   formatIdea,
   formatCleanup,
-  formatRecap
+  formatRecap,
 }
-

package/core/utils/branding.ts

@@ -6,8 +6,8 @@
  */
 
 import chalk from 'chalk'
+import { getProviderBranding } from '../infrastructure/ai-provider'
 import type { AIProviderName } from '../types/provider'
-import { getProviderBranding, Providers } from '../infrastructure/ai-provider'
 
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
 const SPINNER_SPEED = 80
@@ -48,21 +48,21 @@ const branding: Branding = {
   // Spinner config
   spinner: {
     frames: SPINNER_FRAMES,
-    speed: SPINNER_SPEED
+    speed: SPINNER_SPEED,
   },
 
   // CLI output (with chalk colors)
   cli: {
-    header: () => chalk.cyan.bold('⚡') + ' ' + chalk.cyan('prjct'),
+    header: () => `${chalk.cyan.bold('⚡')} ${chalk.cyan('prjct')}`,
     footer: () => chalk.dim('⚡ prjct'),
     spin: (frame: number, msg?: string) =>
-      chalk.cyan('⚡') + ' ' + chalk.cyan('prjct') + ' ' + chalk.cyan(SPINNER_FRAMES[frame % 10]) + ' ' + chalk.dim(msg || '')
+      `${chalk.cyan('⚡')} ${chalk.cyan('prjct')} ${chalk.cyan(SPINNER_FRAMES[frame % 10])} ${chalk.dim(msg || '')}`,
   },
 
   // Template (plain text)
   template: {
     header: '⚡ prjct',
-    footer: '⚡ prjct'
+    footer: '⚡ prjct',
   },
 
   // Default Git commit footer (generic)
@@ -71,7 +71,7 @@ const branding: Branding = {
   // URLs
   urls: {
     website: 'https://prjct.app',
-    docs: 'https://prjct.app/docs'
+    docs: 'https://prjct.app/docs',
   },
 
   // Provider-aware commit footer
@@ -82,7 +82,7 @@ const branding: Branding = {
   // Provider-aware signature
   getSignature: (provider: AIProviderName = 'claude') => {
     return getProviderBranding(provider).signature
-  }
+  },
 }
 
 export default branding

package/core/utils/cache.ts

@@ -91,9 +91,7 @@ export class TTLCache<T> {
   private evictOldEntries(): void {
     if (this.cache.size <= this.maxSize) return
 
-    const entries = Array.from(this.cache.entries()).sort(
-      (a, b) => a[1].timestamp - b[1].timestamp
-    )
+    const entries = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp)
 
     const toRemove = entries.slice(0, this.cache.size - this.maxSize)
     for (const [key] of toRemove) {

package/core/utils/collection-filters.ts

@@ -29,33 +29,21 @@ export const SECTION_ORDER: Record<TaskSection, number> = {
 /**
  * Filter items by a specific field value
  */
-export function filterByField<T, K extends keyof T>(
-  items: T[],
-  field: K,
-  value: T[K]
-): T[] {
+export function filterByField<T, K extends keyof T>(items: T[], field: K, value: T[K]): T[] {
   return items.filter((item) => item[field] === value)
 }
 
 /**
  * Filter items by multiple field values (OR logic)
  */
-export function filterByFieldIn<T, K extends keyof T>(
-  items: T[],
-  field: K,
-  values: T[K][]
-): T[] {
+export function filterByFieldIn<T, K extends keyof T>(items: T[], field: K, values: T[K][]): T[] {
   return items.filter((item) => values.includes(item[field]))
 }
 
 /**
  * Filter items excluding a specific field value
  */
-export function filterByFieldNot<T, K extends keyof T>(
-  items: T[],
-  field: K,
-  value: T[K]
-): T[] {
+export function filterByFieldNot<T, K extends keyof T>(items: T[], field: K, value: T[K]): T[] {
   return items.filter((item) => item[field] !== value)
 }
 

package/core/utils/date-helper.ts

@@ -97,11 +97,7 @@ export function getDateRange(fromDate: Date, toDate: Date): Date[] {
 
   while (current <= toDate) {
     dates.push(new Date(current))
-    current = new Date(
-      current.getFullYear(),
-      current.getMonth(),
-      current.getDate() + 1,
-    )
+    current = new Date(current.getFullYear(), current.getMonth(), current.getDate() + 1)
   }
 
   return dates
@@ -186,6 +182,5 @@ export default {
   formatDuration,
   calculateDuration,
   getStartOfDay,
-  getEndOfDay
+  getEndOfDay,
 }
-

package/core/utils/file-helper.ts

@@ -1,6 +1,6 @@
-import fs from 'fs/promises'
-import path from 'path'
-import { type NodeError, isNotFoundError } from '../types/fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { isNotFoundError } from '../types/fs'
 
 /**
  * File Helper - Centralized file operations with error handling
@@ -20,7 +20,10 @@ interface ListFilesOptions {
 /**
  * Read JSON file and parse
  */
-export async function readJson<T = unknown>(filePath: string, defaultValue: T | null = null): Promise<T | null> {
+export async function readJson<T = unknown>(
+  filePath: string,
+  defaultValue: T | null = null
+): Promise<T | null> {
   try {
     const content = await fs.readFile(filePath, 'utf-8')
     return JSON.parse(content) as T
@@ -87,7 +90,7 @@ export async function appendToFile(filePath: string, content: string): Promise<v
 export async function appendLine(filePath: string, line: string): Promise<void> {
   const dir = path.dirname(filePath)
   await fs.mkdir(dir, { recursive: true })
-  await fs.appendFile(filePath, line + '\n', 'utf-8')
+  await fs.appendFile(filePath, `${line}\n`, 'utf-8')
 }
 
 /**
@@ -176,7 +179,10 @@ export async function deleteDir(dirPath: string): Promise<boolean> {
 /**
  * List files in directory
  */
-export async function listFiles(dirPath: string, options: ListFilesOptions = {}): Promise<string[]> {
+export async function listFiles(
+  dirPath: string,
+  options: ListFilesOptions = {}
+): Promise<string[]> {
   try {
     const entries = await fs.readdir(dirPath, { withFileTypes: true })
     let files = entries
@@ -285,6 +291,5 @@ export default {
   readLines,
   writeLines,
   getFileExtension,
-  getFileNameWithoutExtension
+  getFileNameWithoutExtension,
 }
-

package/core/utils/jsonl-helper.ts

@@ -1,7 +1,7 @@
-import fs from 'fs/promises'
-import fsSync from 'fs'
-import readline from 'readline'
-import path from 'path'
+import fsSync from 'node:fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import readline from 'node:readline'
 import { isNotFoundError } from '../types/fs'
 
 /**
@@ -46,7 +46,7 @@ export function parseJsonLines<T = Record<string, unknown>>(content: string): T[
  * Convert array of objects to JSONL string
  */
 export function stringifyJsonLines(objects: unknown[]): string {
-  return objects.map((obj) => JSON.stringify(obj)).join('\n') + '\n'
+  return `${objects.map((obj) => JSON.stringify(obj)).join('\n')}\n`
 }
 
 /**
@@ -77,7 +77,7 @@ export async function writeJsonLines(filePath: string, objects: unknown[]): Prom
  * Uses append mode for efficiency (no full file read/write)
  */
 export async function appendJsonLine(filePath: string, object: unknown): Promise<void> {
-  const line = JSON.stringify(object) + '\n'
+  const line = `${JSON.stringify(object)}\n`
   await fs.appendFile(filePath, line, 'utf-8')
 }
 
@@ -144,7 +144,9 @@ export async function getFirstJsonLines<T = Record<string, unknown>>(
  * Merge multiple JSONL files into one array
  * Useful for reading multiple sessions
  */
-export async function mergeJsonLines<T = Record<string, unknown>>(filePaths: string[]): Promise<T[]> {
+export async function mergeJsonLines<T = Record<string, unknown>>(
+  filePaths: string[]
+): Promise<T[]> {
   const allEntries: T[] = []
 
   for (const filePath of filePaths) {
@@ -240,7 +242,9 @@ export async function rotateJsonLinesIfNeeded(filePath: string, maxSizeMB = 10):
   // Move file to archive
   await fs.rename(filePath, archivePath)
 
-  console.log(`📦 Rotated ${path.basename(filePath)} (${sizeMB.toFixed(1)}MB) → ${path.basename(archivePath)}`)
+  console.log(
+    `📦 Rotated ${path.basename(filePath)} (${sizeMB.toFixed(1)}MB) → ${path.basename(archivePath)}`
+  )
 
   return true
 }
@@ -299,6 +303,5 @@ export default {
   getFileSizeMB,
   rotateJsonLinesIfNeeded,
   appendJsonLineWithRotation,
-  checkFileSizeWarning
+  checkFileSizeWarning,
 }
-

package/core/utils/keychain.ts

@@ -5,8 +5,8 @@
  * Falls back to environment variables if keychain is not available.
  */
 
-import { exec } from 'child_process'
-import { promisify } from 'util'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
 
 const execAsync = promisify(exec)
 
@@ -30,9 +30,7 @@ export async function setCredential(key: CredentialKey, value: string): Promise<
     )
 
     // Add new entry
-    await execAsync(
-      `security add-generic-password -s "${SERVICE_NAME}" -a "${key}" -w "${value}"`
-    )
+    await execAsync(`security add-generic-password -s "${SERVICE_NAME}" -a "${key}" -w "${value}"`)
 
     return true
   } catch (error) {
@@ -70,9 +68,7 @@ export async function deleteCredential(key: CredentialKey): Promise<boolean> {
   }
 
   try {
-    await execAsync(
-      `security delete-generic-password -s "${SERVICE_NAME}" -a "${key}" 2>/dev/null`
-    )
+    await execAsync(`security delete-generic-password -s "${SERVICE_NAME}" -a "${key}" 2>/dev/null`)
     return true
   } catch (_error) {
     // Not found in keychain - expected

package/core/utils/logger.ts

@@ -79,7 +79,7 @@ const logger: Logger = {
   isEnabled: () => currentLevel >= 0,
 
   // Get current level name (pre-computed, no runtime lookup)
-  level: () => currentLevelName
+  level: () => currentLevelName,
 }
 
 export default logger

package/core/utils/next-steps.ts

@@ -6,7 +6,7 @@
  */
 
 import chalk from 'chalk'
-import { workflowStateMachine, type WorkflowState } from '../workflow/state-machine'
+import { type WorkflowState, workflowStateMachine } from '../workflow/state-machine'
 
 interface NextStep {
   cmd: string
@@ -59,7 +59,7 @@ export function showNextSteps(command: string, options: { quiet?: boolean } = {}
 
   if (validCommands.length === 0) return
 
-  const steps: NextStep[] = validCommands.map(cmd => ({
+  const steps: NextStep[] = validCommands.map((cmd) => ({
     cmd: `p. ${cmd}`,
     desc: CMD_DESCRIPTIONS[cmd] || cmd,
   }))
@@ -78,7 +78,7 @@ export function getNextSteps(command: string): NextStep[] {
   const resultingState = COMMAND_TO_STATE[command] || 'idle'
   const validCommands = workflowStateMachine.getValidCommands(resultingState)
 
-  return validCommands.map(cmd => ({
+  return validCommands.map((cmd) => ({
     cmd: `p. ${cmd}`,
     desc: CMD_DESCRIPTIONS[cmd] || cmd,
   }))

package/core/utils/output.ts

@@ -2,27 +2,56 @@
  * Minimal Output System for prjct-cli
  * Spinner while working → Single line result
  * With prjct branding
+ *
+ * Supports --quiet mode for CI/CD and scripting
  */
 
 import chalk from 'chalk'
 import branding from './branding'
 
-const FRAMES = branding.spinner.frames
+const _FRAMES = branding.spinner.frames
 const SPEED = branding.spinner.speed
 
 let interval: ReturnType<typeof setInterval> | null = null
 let frame = 0
 
+// Quiet mode - suppress all stdout except errors
+let quietMode = false
+
+/**
+ * Enable quiet mode (no stdout, only stderr for errors)
+ */
+export function setQuietMode(enabled: boolean): void {
+  quietMode = enabled
+}
+
+/**
+ * Check if quiet mode is enabled
+ */
+export function isQuietMode(): boolean {
+  return quietMode
+}
+
 const truncate = (s: string | undefined | null, max = 50): string =>
-  s && s.length > max ? s.slice(0, max - 1) + '…' : s || ''
+  s && s.length > max ? `${s.slice(0, max - 1)}…` : s || ''
 
-const clear = (): boolean => process.stdout.write('\r' + ' '.repeat(80) + '\r')
+const clear = (): boolean => process.stdout.write(`\r${' '.repeat(80)}\r`)
+
+/**
+ * Metrics to display after command completion
+ * Shows value provided by prjct (compression, agent count, etc.)
+ */
+interface OutputMetrics {
+  agents?: number // Number of agents used
+  reduction?: number // Context reduction percentage
+  tokens?: number // Token count (in thousands)
+}
 
 interface Output {
   start(): Output
   end(): Output
   spin(msg: string): Output
-  done(msg: string): Output
+  done(msg: string, metrics?: OutputMetrics): Output
   fail(msg: string): Output
   warn(msg: string): Output
   stop(): Output
@@ -33,18 +62,19 @@ interface Output {
 const out: Output = {
   // Branding: Show header at start
   start() {
-    console.log(branding.cli.header())
+    if (!quietMode) console.log(branding.cli.header())
     return this
   },
 
   // Branding: Show footer at end
   end() {
-    console.log(branding.cli.footer())
+    if (!quietMode) console.log(branding.cli.footer())
     return this
   },
 
   // Branded spinner: prjct message...
   spin(msg: string) {
+    if (quietMode) return this
     this.stop()
     interval = setInterval(() => {
       process.stdout.write(`\r${branding.cli.spin(frame++, truncate(msg, 45))}`)
@@ -52,21 +82,35 @@ const out: Output = {
     return this
   },
 
-  done(msg: string) {
+  done(msg: string, metrics?: OutputMetrics) {
     this.stop()
-    console.log(`${chalk.green('✓')} ${truncate(msg, 65)}`)
+    if (!quietMode) {
+      // Build metrics suffix if provided: [2a | 97% | 45K]
+      let suffix = ''
+      if (metrics) {
+        const parts: string[] = []
+        if (metrics.agents !== undefined) parts.push(`${metrics.agents}a`)
+        if (metrics.reduction !== undefined) parts.push(`${metrics.reduction}%`)
+        if (metrics.tokens !== undefined) parts.push(`${Math.round(metrics.tokens)}K`)
+        if (parts.length > 0) {
+          suffix = chalk.dim(` [${parts.join(' | ')}]`)
+        }
+      }
+      console.log(`${chalk.green('✓')} ${truncate(msg, 50)}${suffix}`)
+    }
     return this
   },
 
+  // Errors go to stderr even in quiet mode
   fail(msg: string) {
     this.stop()
-    console.log(`${chalk.red('✗')} ${truncate(msg, 65)}`)
+    console.error(`${chalk.red('✗')} ${truncate(msg, 65)}`)
     return this
   },
 
   warn(msg: string) {
     this.stop()
-    console.log(`${chalk.yellow('⚠')} ${truncate(msg, 65)}`)
+    if (!quietMode) console.log(`${chalk.yellow('⚠')} ${truncate(msg, 65)}`)
     return this
   },
 
@@ -81,6 +125,7 @@ const out: Output = {
 
   // Step counter: [3/7] Running tests...
   step(current: number, total: number, msg: string) {
+    if (quietMode) return this
     this.stop()
     const counter = chalk.dim(`[${current}/${total}]`)
     interval = setInterval(() => {
@@ -91,6 +136,7 @@ const out: Output = {
 
   // Progress bar: [████░░░░] 50% Analyzing...
   progress(current: number, total: number, msg?: string) {
+    if (quietMode) return this
     this.stop()
     const percent = Math.round((current / total) * 100)
     const filled = Math.round(percent / 10)
@@ -101,7 +147,8 @@ const out: Output = {
       process.stdout.write(`\r${branding.cli.spin(frame++, `[${bar}] ${percent}%${text}`)}`)
     }, SPEED)
     return this
-  }
+  },
 }
 
+export type { OutputMetrics }
 export default out

package/core/utils/project-commands.ts

@@ -1,7 +1,6 @@
-import path from 'path'
-
-import * as fileHelper from './file-helper'
+import path from 'node:path'
 import type { DetectedProjectCommands } from '../types'
+import * as fileHelper from './file-helper'
 
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
 type DetectedStack = 'js' | 'python' | 'go' | 'rust' | 'dotnet' | 'java' | 'unknown'
@@ -21,7 +20,10 @@ interface PackageJson {
  *
  * Reason: installed users may not have Bun, and many projects use pnpm/yarn.
  */
-async function detectPackageManager(projectPath: string, pkg: PackageJson | null): Promise<PackageManager> {
+async function detectPackageManager(
+  projectPath: string,
+  pkg: PackageJson | null
+): Promise<PackageManager> {
   const declared = pkg?.packageManager?.trim().toLowerCase()
   if (declared?.startsWith('pnpm@')) return 'pnpm'
   if (declared?.startsWith('yarn@')) return 'yarn'
@@ -128,5 +130,3 @@ export async function detectProjectCommands(projectPath: string): Promise<Detect
 
   return { stack: 'unknown' }
 }
-
-

package/core/utils/project-credentials.ts

@@ -11,10 +11,10 @@
  * This allows different projects to use different Linear workspaces.
  */
 
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { getCredential, type CredentialKey } from './keychain'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { type CredentialKey, getCredential } from './keychain'
 
 interface LinearCredentials {
   apiKey: string
@@ -31,14 +31,7 @@ export interface ProjectCredentials {
  * Get path to project credentials file
  */
 function getCredentialsPath(projectId: string): string {
-  return path.join(
-    os.homedir(),
-    '.prjct-cli',
-    'projects',
-    projectId,
-    'config',
-    'credentials.json'
-  )
+  return path.join(os.homedir(), '.prjct-cli', 'projects', projectId, 'config', 'credentials.json')
 }
 
 /**