prjct-cli 1.22.0 → 1.23.0

package/core/utils/help.ts

@@ -1,314 +0,0 @@
-/**
- * Help System - Structured help output for prjct CLI
- *
- * Provides consistent, well-formatted help text for all commands.
- *
- * @see PRJ-133
- * @module utils/help
- */
-
-import chalk from 'chalk'
-import { CATEGORIES, COMMANDS } from '../commands/command-data'
-import { VERSION } from './version'
-
-/**
- * Terminal commands that run directly in the shell
- */
-const TERMINAL_COMMANDS = [
-  {
-    name: 'start',
-    description: 'First-time setup wizard',
-    example: 'prjct start',
-  },
-  {
-    name: 'init',
-    description: 'Initialize project in current directory',
-    example: 'prjct init',
-  },
-  {
-    name: 'sync',
-    description: 'Sync project state and update context files',
-    example: 'prjct sync',
-  },
-  {
-    name: 'watch',
-    description: 'Auto-sync on file changes',
-    example: 'prjct watch',
-    options: ['--verbose', '--debounce=<ms>', '--interval=<sec>'],
-  },
-  {
-    name: 'hooks',
-    description: 'Manage git hooks for auto-sync',
-    example: 'prjct hooks install',
-    subcommands: ['install', 'uninstall', 'status'],
-  },
-  {
-    name: 'doctor',
-    description: 'Check system health and dependencies',
-    example: 'prjct doctor',
-  },
-  {
-    name: 'serve',
-    description: 'Start web dashboard server',
-    example: 'prjct serve [port]',
-  },
-  {
-    name: 'context',
-    description: 'Smart context filtering tools for AI',
-    example: 'prjct context files "add auth"',
-    subcommands: ['files', 'signatures', 'imports', 'recent', 'summary'],
-  },
-  {
-    name: 'linear',
-    description: 'Linear issue tracker CLI',
-    example: 'prjct linear list',
-    subcommands: ['list', 'get', 'create', 'update'],
-  },
-  {
-    name: 'uninstall',
-    description: 'Complete system removal of prjct',
-    example: 'prjct uninstall --backup',
-    options: ['--force', '--backup', '--dry-run', '--keep-package'],
-  },
-]
-
-/**
- * Global CLI flags
- */
-const GLOBAL_FLAGS = [
-  { flag: '-q, --quiet', description: 'Suppress all output (errors to stderr only)' },
-  { flag: '-v, --version', description: 'Show version and provider status' },
-  { flag: '-h, --help', description: 'Show this help message' },
-]
-
-/**
- * Format the main help output
- */
-export function formatMainHelp(): string {
-  const lines: string[] = []
-
-  // Header
-  lines.push('')
-  lines.push(`${chalk.cyan.bold('prjct')} v${VERSION} - Context layer for AI coding agents`)
-  lines.push(chalk.dim('Works with Claude Code, Gemini CLI, Cursor, Windsurf, and more.'))
-  lines.push('')
-
-  // Quick Start
-  lines.push(chalk.bold('QUICK START'))
-  lines.push(chalk.dim('─'.repeat(60)))
-  lines.push(
-    `  ${chalk.green('1.')} prjct start              ${chalk.dim('# Configure AI providers')}`
-  )
-  lines.push(`  ${chalk.green('2.')} cd my-project && prjct init`)
-  lines.push(`  ${chalk.green('3.')} Open in Claude Code / Gemini CLI / Cursor`)
-  lines.push(`  ${chalk.green('4.')} p. sync                  ${chalk.dim('# Analyze project')}`)
-  lines.push('')
-
-  // Terminal Commands
-  lines.push(chalk.bold('TERMINAL COMMANDS'))
-  lines.push(chalk.dim('─'.repeat(60)))
-  for (const cmd of TERMINAL_COMMANDS) {
-    const name = `prjct ${cmd.name}`.padEnd(22)
-    lines.push(`  ${name} ${cmd.description}`)
-  }
-  lines.push('')
-
-  // AI Agent Commands
-  lines.push(`${chalk.bold('AI AGENT COMMANDS')} ${chalk.dim('(inside Claude/Gemini/Cursor)')}`)
-  lines.push(chalk.dim('─'.repeat(60)))
-  lines.push(`  ${'Command'.padEnd(22)} Description`)
-  lines.push(`  ${chalk.dim('─'.repeat(56))}`)
-
-  // Core commands
-  const coreCommands = COMMANDS.filter((c) => c.group === 'core' && c.usage?.claude)
-  for (const cmd of coreCommands.slice(0, 10)) {
-    const usage = `p. ${cmd.name}`.padEnd(22)
-    lines.push(`  ${usage} ${cmd.description}`)
-  }
-  lines.push(
-    `  ${chalk.dim(`... and ${coreCommands.length - 10} more (run 'prjct help commands')`)}`
-  )
-  lines.push('')
-
-  // Global Flags
-  lines.push(chalk.bold('FLAGS'))
-  lines.push(chalk.dim('─'.repeat(60)))
-  for (const flag of GLOBAL_FLAGS) {
-    lines.push(`  ${flag.flag.padEnd(22)} ${flag.description}`)
-  }
-  lines.push('')
-
-  // More Info
-  lines.push(chalk.bold('MORE INFO'))
-  lines.push(chalk.dim('─'.repeat(60)))
-  lines.push(`  Documentation:  ${chalk.cyan('https://prjct.app')}`)
-  lines.push(`  GitHub:         ${chalk.cyan('https://github.com/jlopezlira/prjct-cli')}`)
-  lines.push(`  Per-command:    prjct help <command>`)
-  lines.push('')
-
-  return lines.join('\n')
-}
-
-/**
- * Format help for a specific terminal command
- */
-export function formatTerminalCommandHelp(commandName: string): string | null {
-  const cmd = TERMINAL_COMMANDS.find((c) => c.name === commandName)
-  if (!cmd) return null
-
-  const lines: string[] = []
-
-  lines.push('')
-  lines.push(`${chalk.cyan.bold(`prjct ${cmd.name}`)} - ${cmd.description}`)
-  lines.push('')
-
-  lines.push(chalk.bold('USAGE'))
-  lines.push(`  ${cmd.example}`)
-  lines.push('')
-
-  if (cmd.options) {
-    lines.push(chalk.bold('OPTIONS'))
-    for (const opt of cmd.options) {
-      lines.push(`  ${opt}`)
-    }
-    lines.push('')
-  }
-
-  if (cmd.subcommands) {
-    lines.push(chalk.bold('SUBCOMMANDS'))
-    for (const sub of cmd.subcommands) {
-      lines.push(`  ${sub}`)
-    }
-    lines.push('')
-  }
-
-  return lines.join('\n')
-}
-
-/**
- * Format help for an AI agent command
- */
-export function formatAgentCommandHelp(commandName: string): string | null {
-  const cmd = COMMANDS.find((c) => c.name === commandName)
-  if (!cmd) return null
-
-  const lines: string[] = []
-
-  lines.push('')
-  lines.push(`${chalk.cyan.bold(`p. ${cmd.name}`)} - ${cmd.description}`)
-  lines.push('')
-
-  lines.push(chalk.bold('USAGE'))
-  if (cmd.usage?.claude) {
-    lines.push(`  Claude/Gemini:  ${cmd.usage.claude.replace('/p:', 'p. ')}`)
-  }
-  if (cmd.usage?.terminal) {
-    lines.push(`  Terminal:       ${cmd.usage.terminal}`)
-  }
-  lines.push('')
-
-  if (cmd.params) {
-    lines.push(chalk.bold('PARAMETERS'))
-    lines.push(`  ${cmd.params}`)
-    lines.push('')
-  }
-
-  if (cmd.features && cmd.features.length > 0) {
-    lines.push(chalk.bold('FEATURES'))
-    for (const feature of cmd.features) {
-      lines.push(`  • ${feature}`)
-    }
-    lines.push('')
-  }
-
-  if (cmd.blockingRules) {
-    lines.push(chalk.bold('REQUIREMENTS'))
-    lines.push(`  ${chalk.yellow('⚠')} ${cmd.blockingRules.check}`)
-    lines.push('')
-  }
-
-  // Category info
-  const category = CATEGORIES[cmd.group]
-  if (category) {
-    lines.push(chalk.dim(`Category: ${category.title}`))
-    if (cmd.isOptional) {
-      lines.push(chalk.dim('This is an optional command.'))
-    }
-    lines.push('')
-  }
-
-  return lines.join('\n')
-}
-
-/**
- * Format help for a specific command (auto-detect type)
- */
-export function formatCommandHelp(commandName: string): string {
-  // Try terminal command first
-  const terminalHelp = formatTerminalCommandHelp(commandName)
-  if (terminalHelp) return terminalHelp
-
-  // Try agent command
-  const agentHelp = formatAgentCommandHelp(commandName)
-  if (agentHelp) return agentHelp
-
-  // Command not found
-  return `
-${chalk.yellow(`Command '${commandName}' not found.`)}
-
-Run 'prjct help' to see all available commands.
-`
-}
-
-/**
- * Format list of all commands grouped by category
- */
-export function formatCommandList(): string {
-  const lines: string[] = []
-
-  lines.push('')
-  lines.push(chalk.cyan.bold('All Commands'))
-  lines.push('')
-
-  // Group by category
-  const categories = Object.entries(CATEGORIES).sort((a, b) => a[1].order - b[1].order)
-
-  for (const [categoryKey, category] of categories) {
-    const categoryCommands = COMMANDS.filter((c) => c.group === categoryKey)
-    if (categoryCommands.length === 0) continue
-
-    lines.push(
-      `${chalk.bold(category.title)} ${chalk.dim(`(${categoryCommands.length} commands)`)}`
-    )
-    lines.push(chalk.dim(category.description))
-    lines.push('')
-
-    for (const cmd of categoryCommands) {
-      const name = `p. ${cmd.name}`.padEnd(18)
-      const desc =
-        cmd.description.length > 45 ? `${cmd.description.slice(0, 42)}...` : cmd.description
-      lines.push(`  ${name} ${desc}`)
-    }
-    lines.push('')
-  }
-
-  lines.push(chalk.dim("Run 'prjct help <command>' for detailed help on a specific command."))
-  lines.push('')
-
-  return lines.join('\n')
-}
-
-/**
- * Get help output based on topic
- */
-export function getHelp(topic?: string): string {
-  if (!topic) {
-    return formatMainHelp()
-  }
-
-  if (topic === 'commands' || topic === 'all') {
-    return formatCommandList()
-  }
-
-  return formatCommandHelp(topic)
-}

package/core/utils/jsonl-helper.ts

@@ -1,290 +0,0 @@
-import fsSync from 'node:fs'
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import readline from 'node:readline'
-import { STORAGE_LIMITS } from '../constants'
-import { isNotFoundError } from '../types/fs'
-
-/**
- * JSONL Helper - Centralized JSONL parsing and writing
- *
- * Eliminates duplicated JSONL logic across:
- * - session-manager.ts (_parseJsonLines)
- * - commands.ts (inline parsing)
- * - analyzer.ts (inline parsing)
- *
- * JSONL Format: One JSON object per line, newline-separated
- * Example:
- * {"ts":"2025-10-04T14:30:00Z","type":"feature_add","name":"auth"}
- * {"ts":"2025-10-04T15:00:00Z","type":"task_start","task":"JWT"}
- */
-
-interface FileSizeWarning {
-  sizeMB: number
-  isLarge: boolean
-}
-
-/**
- * Parse JSONL content into array of objects
- * Handles malformed lines gracefully (skips them)
- */
-export function parseJsonLines<T = Record<string, unknown>>(content: string): T[] {
-  const lines = content.split('\n').filter((line) => line.trim())
-  const entries: T[] = []
-
-  for (const line of lines) {
-    try {
-      entries.push(JSON.parse(line) as T)
-    } catch (_error) {
-      // Skip malformed lines silently (JSON parse error expected)
-    }
-  }
-
-  return entries
-}
-
-/**
- * Convert array of objects to JSONL string
- */
-export function stringifyJsonLines(objects: unknown[]): string {
-  return `${objects.map((obj) => JSON.stringify(obj)).join('\n')}\n`
-}
-
-/**
- * Read and parse JSONL file
- */
-export async function readJsonLines<T = Record<string, unknown>>(filePath: string): Promise<T[]> {
-  try {
-    const content = await fs.readFile(filePath, 'utf-8')
-    return parseJsonLines<T>(content)
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      return [] // File doesn't exist, return empty array
-    }
-    throw error
-  }
-}
-
-/**
- * Write array of objects to JSONL file (overwrites)
- */
-export async function writeJsonLines(filePath: string, objects: unknown[]): Promise<void> {
-  const content = stringifyJsonLines(objects)
-  await fs.writeFile(filePath, content, 'utf-8')
-}
-
-/**
- * Append a single object to JSONL file
- * 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`
-  await fs.appendFile(filePath, line, 'utf-8')
-}
-
-/**
- * Append multiple objects to JSONL file
- */
-export async function appendJsonLines(filePath: string, objects: unknown[]): Promise<void> {
-  const content = stringifyJsonLines(objects)
-  await fs.appendFile(filePath, content, 'utf-8')
-}
-
-/**
- * Filter JSONL file entries by predicate
- * Reads all entries, filters, returns matching ones
- */
-export async function filterJsonLines<T = Record<string, unknown>>(
-  filePath: string,
-  predicate: (entry: T) => boolean
-): Promise<T[]> {
-  const entries = await readJsonLines<T>(filePath)
-  return entries.filter(predicate)
-}
-
-/**
- * Count lines in JSONL file (non-empty, parseable lines)
- */
-export async function countJsonLines(filePath: string): Promise<number> {
-  try {
-    const content = await fs.readFile(filePath, 'utf-8')
-    const lines = content.split('\n').filter((line) => line.trim())
-    return lines.length
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      return 0
-    }
-    throw error
-  }
-}
-
-/**
- * Get last N entries from JSONL file
- * Efficient for large files (reads whole file but only returns last N)
- */
-export async function getLastJsonLines<T = Record<string, unknown>>(
-  filePath: string,
-  n: number
-): Promise<T[]> {
-  const entries = await readJsonLines<T>(filePath)
-  return entries.slice(-n)
-}
-
-/**
- * Get first N entries from JSONL file
- */
-export async function getFirstJsonLines<T = Record<string, unknown>>(
-  filePath: string,
-  n: number
-): Promise<T[]> {
-  const entries = await readJsonLines<T>(filePath)
-  return entries.slice(0, n)
-}
-
-/**
- * Merge multiple JSONL files into one array
- * Useful for reading multiple sessions
- */
-export async function mergeJsonLines<T = Record<string, unknown>>(
-  filePaths: string[]
-): Promise<T[]> {
-  const allEntries: T[] = []
-
-  for (const filePath of filePaths) {
-    const entries = await readJsonLines<T>(filePath)
-    allEntries.push(...entries)
-  }
-
-  return allEntries
-}
-
-/**
- * Check if JSONL file is empty or doesn't exist
- */
-export async function isJsonLinesEmpty(filePath: string): Promise<boolean> {
-  const count = await countJsonLines(filePath)
-  return count === 0
-}
-
-/**
- * Read JSONL file with streaming (memory-efficient for large files)
- * Only reads last N lines instead of loading entire file
- */
-export async function readJsonLinesStreaming<T = Record<string, unknown>>(
-  filePath: string,
-  maxLines: number = STORAGE_LIMITS.JSONL_MAX_LINES
-): Promise<T[]> {
-  try {
-    const fileStream = fsSync.createReadStream(filePath)
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity,
-    })
-
-    const lines: T[] = []
-
-    for await (const line of rl) {
-      if (line.trim()) {
-        try {
-          lines.push(JSON.parse(line) as T)
-        } catch (_error) {
-          // Skip malformed lines (JSON parse error expected)
-        }
-
-        // Keep only last maxLines
-        if (lines.length > maxLines) {
-          lines.shift()
-        }
-      }
-    }
-
-    return lines
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      return []
-    }
-    throw error
-  }
-}
-
-/**
- * Get file size in MB
- */
-export async function getFileSizeMB(filePath: string): Promise<number> {
-  try {
-    const stats = await fs.stat(filePath)
-    return stats.size / (1024 * 1024)
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      return 0
-    }
-    throw error
-  }
-}
-
-/**
- * Rotate JSONL file if it exceeds size limit
- * Moves large file to archive with timestamp
- */
-export async function rotateJsonLinesIfNeeded(
-  filePath: string,
-  maxSizeMB: number = STORAGE_LIMITS.ROTATION_SIZE_MB
-): Promise<boolean> {
-  const sizeMB = await getFileSizeMB(filePath)
-
-  if (sizeMB < maxSizeMB) {
-    return false // No rotation needed
-  }
-
-  // Generate archive filename with timestamp
-  const timestamp = new Date().toISOString().split('T')[0] // YYYY-MM-DD
-  const dir = path.dirname(filePath)
-  const ext = path.extname(filePath)
-  const base = path.basename(filePath, ext)
-  const archivePath = path.join(dir, `${base}-${timestamp}${ext}`)
-
-  // Move file to archive
-  await fs.rename(filePath, archivePath)
-
-  console.log(
-    `📦 Rotated ${path.basename(filePath)} (${sizeMB.toFixed(1)}MB) → ${path.basename(archivePath)}`
-  )
-
-  return true
-}
-
-/**
- * Append JSON line with automatic rotation
- * Checks file size before append and rotates if needed
- */
-export async function appendJsonLineWithRotation(
-  filePath: string,
-  object: unknown,
-  maxSizeMB: number = STORAGE_LIMITS.ROTATION_SIZE_MB
-): Promise<void> {
-  // Rotate if needed (before appending)
-  await rotateJsonLinesIfNeeded(filePath, maxSizeMB)
-
-  // Append normally
-  await appendJsonLine(filePath, object)
-}
-
-/**
- * Warn if file is large before reading
- * Returns size and whether it's considered large
- */
-export async function checkFileSizeWarning(
-  filePath: string,
-  warnThresholdMB: number = STORAGE_LIMITS.LARGE_FILE_WARN_MB
-): Promise<FileSizeWarning> {
-  const sizeMB = await getFileSizeMB(filePath)
-  const isLarge = sizeMB > warnThresholdMB
-
-  if (isLarge) {
-    console.warn(
-      `⚠️  Large file detected: ${path.basename(filePath)} (${sizeMB.toFixed(1)}MB). Reading may use significant memory.`
-    )
-  }
-
-  return { sizeMB, isLarge }
-}