prjct-cli 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [1.2.0] - 2026-02-06
+
+### Features
+
+- git hooks integration for auto-sync (PRJ-128) (#112)
+
+
+## [1.2.0] - 2026-02-05
+
+### Added
+
+- **Git hooks integration (PRJ-128)**: New `prjct hooks` command for auto-syncing context on commit and branch checkout
+
+### Implementation Details
+
+New `prjct hooks` CLI subcommand with three operations:
+- `prjct hooks install` — auto-detects hook manager (lefthook > husky > direct `.git/hooks/`) and installs post-commit + post-checkout hooks
+- `prjct hooks uninstall` — cleanly removes only prjct hooks, preserving existing hooks
+- `prjct hooks status` — shows active hooks, strategy, and available managers
+
+Hook scripts feature:
+- **Rate limiting** — 30-second lockfile prevents over-syncing on rapid commits
+- **Background execution** — hooks run `prjct sync` in background, never blocking git
+- **Branch-only checkout** — post-checkout only fires on branch switch, not file checkout
+- **Cross-platform** — handles macOS/Linux differences in `stat` and `md5` commands
+
+Supports three installation strategies:
+- **Lefthook** — adds `prjct-sync-*` commands to existing `lefthook.yml`
+- **Husky** — appends to existing `.husky/` hook scripts
+- **Direct** — writes to `.git/hooks/` as fallback
+
+Hook configuration saved to `project.json` for persistence across sessions.
+
+### Learnings
+
+- Strategy pattern works well for hook manager abstraction (detect → select → install)
+- `stat -f%m` (macOS) vs `stat -c%Y` (Linux) for file modification time
+- Lefthook section merging needs careful regex to avoid duplicates
+- `$3` parameter in post-checkout distinguishes branch checkout (1) from file checkout (0)
+
+### Test Plan
+
+#### For QA
+1. Run `prjct hooks status` — verify shows "Not installed" with available managers
+2. Run `prjct hooks install` — verify detects manager and installs hooks
+3. Run `prjct hooks status` — verify shows "Active"
+4. Make a git commit — verify sync runs in background
+5. Switch branches — verify post-checkout triggers sync
+6. Run `prjct hooks uninstall` — verify clean removal
+7. Run `bun run build && bun run typecheck` — zero errors
+
+#### For Users
+**What changed:** New `prjct hooks` command for automatic context syncing
+**How to use:** Run `prjct hooks install` in any prjct project
+**Breaking changes:** None
+
+## [1.1.1] - 2026-02-06
+
+### Bug Fixes
+
+- visual grouping with boxes and tables for structured output (PRJ-134) (#110)
+
+## [1.1.1] - 2026-02-05
+
+### Improved
+
+- **Visual grouping for structured output (PRJ-134)**: Added `out.section()` and integrated `out.box()`, `out.table()`, `out.list()` into sync, doctor, and status commands
+
+### Implementation Details
+
+Added `out.section(title)` method to the unified output system (`core/utils/output.ts`) — bold title with dim underline, chainable, quiet-mode aware.
+
+Refactored three commands to use unified output helpers instead of raw `console.log`:
+- **Sync** (`analysis.ts`): Summary metrics in `out.box()`, generated items via `out.section()` + `out.list()`
+- **Doctor** (`doctor-service.ts`): Section headers via `out.section()`, recommendations via `out.list()`, summary via `out.done()`/`out.warn()`/`out.fail()`
+- **Status** (`staleness-checker.ts`): Key-value details wrapped in box-drawing characters
+
+### Learnings
+
+- `staleness-checker.formatStatus()` returns a string (not direct output), so `out.box()` can't be used directly — used inline box-drawing chars instead
+- Doctor service had its own icon logic for check results that was worth preserving alongside the new section headers
+- Unified output helpers reduce code while maintaining the same visual style
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` — verify boxed "Sync Summary" with metrics, "Generated" section header with underline, `✓` bullet items
+2. Run `prjct doctor` — verify bold+underline section headers for "System Tools", "Project Status", "Recommendations"
+3. Run `prjct status` — verify key-value details in box-drawing characters
+4. Run with `--quiet` flag — verify no visual output is printed
+
+#### For Users
+**What changed:** CLI output now uses visual grouping (boxes, section headers, structured lists) for better scannability
+**How to use:** No changes needed — output is automatically improved
+**Breaking changes:** None
+
 ## [1.1.0] - 2026-02-05
 
 ### Features

package/bin/prjct.ts

@@ -108,6 +108,12 @@ if (args[0] === 'start' || args[0] === 'setup') {
     console.log(JSON.stringify(result, null, 2))
     process.exitCode = result.tool === 'error' ? 1 : 0
   }
+} else if (args[0] === 'hooks') {
+  // Git hooks management
+  const { hooksService } = await import('../core/services/hooks-service')
+  const subcommand = args[1] || 'status'
+  const exitCode = await hooksService.run(process.cwd(), subcommand)
+  process.exitCode = exitCode
 } else if (args[0] === 'doctor') {
   // Health check command
   const { doctorService } = await import('../core/services/doctor-service')

package/core/commands/analysis.ts

@@ -478,67 +478,55 @@ export class AnalysisCommands extends PrjctCommandsBase {
     // ═══════════════════════════════════════════════════════════════════════
     // SUCCESS LINE - Immediate confirmation with timing
     // ═══════════════════════════════════════════════════════════════════════
-    console.log(`✅ Synced ${result.stats.name || 'project'} (${(elapsed / 1000).toFixed(1)}s)\n`)
+    out.done(`Synced ${result.stats.name || 'project'} (${(elapsed / 1000).toFixed(1)}s)`)
+    console.log('')
 
     // ═══════════════════════════════════════════════════════════════════════
-    // KEY METRICS - Single scannable line
+    // SUMMARY BOX - Key metrics grouped visually
     // ═══════════════════════════════════════════════════════════════════════
-    // Only show compression rate if meaningful (> 10%)
     const compressionPct = result.syncMetrics?.compressionRate
       ? Math.round(result.syncMetrics.compressionRate * 100)
       : 0
-    const metricsLine = [
-      `${result.stats.fileCount} files → ${contextFilesCount} context`,
-      `${agentCount} agents`,
-      compressionPct > 10 ? `${compressionPct}% reduction` : null,
-    ]
-      .filter(Boolean)
-      .join(' | ')
-    console.log(metricsLine)
-
-    // Stack and branch info
     const framework = result.stats.frameworks.length > 0 ? ` (${result.stats.frameworks[0]})` : ''
-    console.log(`Stack: ${result.stats.ecosystem}${framework} | Branch: ${result.git.branch}\n`)
+    const boxLines = [
+      `${result.stats.fileCount} files → ${contextFilesCount} context | ${agentCount} agents${compressionPct > 10 ? ` | ${compressionPct}% reduction` : ''}`,
+      `Stack: ${result.stats.ecosystem}${framework} | Branch: ${result.git.branch}`,
+    ]
+    out.box('Sync Summary', boxLines.join('\n'))
 
     // ═══════════════════════════════════════════════════════════════════════
     // CHANGES SECTION - What was generated/updated
     // ═══════════════════════════════════════════════════════════════════════
-    console.log('Generated:')
-
-    // Context files (condensed)
+    const generatedItems: string[] = []
     if (result.contextFiles.length > 0) {
-      console.log(`  ✓ ${result.contextFiles.length} context files`)
+      generatedItems.push(`${result.contextFiles.length} context files`)
     }
-
-    // AI tools
     const successTools = result.aiTools?.filter((t) => t.success) || []
     if (successTools.length > 0) {
-      const toolNames = successTools.map((t) => t.toolId).join(', ')
-      console.log(`  ✓ AI tools: ${toolNames}`)
+      generatedItems.push(`AI tools: ${successTools.map((t) => t.toolId).join(', ')}`)
     }
-
-    // Agents (show count with breakdown)
     if (agentCount > 0) {
       const agentSummary =
         domainAgentCount > 0
           ? `${agentCount} agents (${domainAgentCount} domain)`
           : `${agentCount} agents`
-      console.log(`  ✓ ${agentSummary}`)
+      generatedItems.push(agentSummary)
     }
-
-    // Skills
     if (result.skills.length > 0) {
       const skillWord = result.skills.length === 1 ? 'skill' : 'skills'
-      console.log(`  ✓ ${result.skills.length} ${skillWord}`)
+      generatedItems.push(`${result.skills.length} ${skillWord}`)
     }
 
+    out.section('Generated')
+    out.list(generatedItems, { bullet: '✓' })
     console.log('')
 
     // ═══════════════════════════════════════════════════════════════════════
     // STATUS INDICATOR - Repository state
     // ═══════════════════════════════════════════════════════════════════════
     if (result.git.hasChanges) {
-      console.log('⚠️  Uncommitted changes detected\n')
+      out.warn('Uncommitted changes detected')
+      console.log('')
     }
 
     // ═══════════════════════════════════════════════════════════════════════

package/core/commands/planning.ts

@@ -207,6 +207,7 @@ export class PlanningCommands extends PrjctCommandsBase {
     console.log('  Quick start:')
     console.log('    prjct sync     Update context after changes')
     console.log('    prjct task     Start working on a task')
+    console.log('    prjct hooks    Auto-sync on commit/checkout')
     console.log('')
 
     if (wizardResult) {

package/core/index.ts

@@ -306,6 +306,7 @@ TERMINAL COMMANDS (this CLI)
   prjct setup            Reconfigure installations
   prjct sync             Sync project state
   prjct watch            Auto-sync on file changes (Ctrl+C to stop)
+  prjct hooks            Manage git hooks for auto-sync
   prjct doctor           Check system health and dependencies
 
 EXAMPLES

package/core/services/doctor-service.ts

@@ -15,6 +15,7 @@ import path from 'node:path'
 import chalk from 'chalk'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
+import out from '../utils/output'
 import { VERSION } from '../utils/version'
 
 // ============================================================================
@@ -367,32 +368,28 @@ class DoctorService {
   // ==========================================================================
 
   private printHeader(): void {
-    console.log('')
-    console.log(chalk.bold(`prjct doctor v${VERSION}`))
-    console.log(chalk.dim('─'.repeat(40)))
+    out.section(`prjct doctor v${VERSION}`)
   }
 
   private printSection(title: string, checks: CheckResult[]): void {
-    console.log('')
-    console.log(chalk.bold(title))
+    out.section(title)
 
-    for (const check of checks) {
+    const items = checks.map((check) => {
       const icon = this.getStatusIcon(check.status, check.optional)
       const name = check.name.padEnd(14)
       const detail = check.version || check.message || ''
       const optionalTag = check.optional && check.status === 'error' ? chalk.dim(' (optional)') : ''
+      return `${icon} ${name} ${chalk.dim(detail)}${optionalTag}`
+    })
 
-      console.log(`  ${icon} ${name} ${chalk.dim(detail)}${optionalTag}`)
+    for (const item of items) {
+      console.log(`  ${item}`)
     }
   }
 
   private printRecommendations(recommendations: string[]): void {
-    console.log('')
-    console.log(chalk.bold('Recommendations'))
-
-    for (const rec of recommendations) {
-      console.log(`  ${chalk.yellow('•')} ${rec}`)
-    }
+    out.section('Recommendations')
+    out.list(recommendations, { bullet: chalk.yellow('•') })
   }
 
   private printSummary(result: DoctorResult): void {
@@ -400,11 +397,11 @@ class DoctorService {
     console.log(chalk.dim('─'.repeat(40)))
 
     if (result.hasErrors) {
-      console.log(chalk.red('✗ Some required checks failed'))
+      out.fail('Some required checks failed')
     } else if (result.hasWarnings) {
-      console.log(chalk.yellow('⚠ All required checks passed (some warnings)'))
+      out.warn('All required checks passed (some warnings)')
     } else {
-      console.log(chalk.green('✓ All checks passed'))
+      out.done('All checks passed')
     }
 
     console.log('')