prjct-cli 0.45.5 → 0.47.0

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import dateHelper from '../utils/date-helper'
+import { mergePreservedSections } from '../utils/preserve-sections'
 
 // ============================================================================
 // TYPES
@@ -180,7 +181,17 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Domain**: ${domainAgents.join(', ') || 'none'}
 `
 
-    await fs.writeFile(path.join(contextPath, 'CLAUDE.md'), content, 'utf-8')
+    // Preserve user customizations from existing file
+    const claudePath = path.join(contextPath, 'CLAUDE.md')
+    let finalContent = content
+    try {
+      const existingContent = await fs.readFile(claudePath, 'utf-8')
+      finalContent = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
+    await fs.writeFile(claudePath, finalContent, 'utf-8')
   }
 
   /**

package/core/utils/help.ts

@@ -0,0 +1,321 @@
+/**
+ * Help System - Structured help output for prjct CLI
+ *
+ * Provides consistent, well-formatted help text for all commands.
+ *
+ * @see PRJ-133
+ * @module utils/help
+ */
+
+import { CATEGORIES, COMMANDS } from '../commands/command-data'
+import type { CommandMeta } from '../types'
+import { VERSION } from './version'
+
+// ANSI colors
+const CYAN = '\x1b[36m'
+const DIM = '\x1b[2m'
+const BOLD = '\x1b[1m'
+const RESET = '\x1b[0m'
+const GREEN = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+
+/**
+ * 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: '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(`${CYAN}${BOLD}prjct${RESET} v${VERSION} - Context layer for AI coding agents`)
+  lines.push(`${DIM}Works with Claude Code, Gemini CLI, Cursor, Windsurf, and more.${RESET}`)
+  lines.push('')
+
+  // Quick Start
+  lines.push(`${BOLD}QUICK START${RESET}`)
+  lines.push(`${DIM}${'─'.repeat(60)}${RESET}`)
+  lines.push(`  ${GREEN}1.${RESET} prjct start              ${DIM}# Configure AI providers${RESET}`)
+  lines.push(`  ${GREEN}2.${RESET} cd my-project && prjct init`)
+  lines.push(`  ${GREEN}3.${RESET} Open in Claude Code / Gemini CLI / Cursor`)
+  lines.push(`  ${GREEN}4.${RESET} p. sync                  ${DIM}# Analyze project${RESET}`)
+  lines.push('')
+
+  // Terminal Commands
+  lines.push(`${BOLD}TERMINAL COMMANDS${RESET}`)
+  lines.push(`${DIM}${'─'.repeat(60)}${RESET}`)
+  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(`${BOLD}AI AGENT COMMANDS${RESET} ${DIM}(inside Claude/Gemini/Cursor)${RESET}`)
+  lines.push(`${DIM}${'─'.repeat(60)}${RESET}`)
+  lines.push(`  ${'Command'.padEnd(22)} Description`)
+  lines.push(`  ${DIM}${'─'.repeat(56)}${RESET}`)
+
+  // 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(`  ${DIM}... and ${coreCommands.length - 10} more (run 'prjct help commands')${RESET}`)
+  lines.push('')
+
+  // Global Flags
+  lines.push(`${BOLD}FLAGS${RESET}`)
+  lines.push(`${DIM}${'─'.repeat(60)}${RESET}`)
+  for (const flag of GLOBAL_FLAGS) {
+    lines.push(`  ${flag.flag.padEnd(22)} ${flag.description}`)
+  }
+  lines.push('')
+
+  // More Info
+  lines.push(`${BOLD}MORE INFO${RESET}`)
+  lines.push(`${DIM}${'─'.repeat(60)}${RESET}`)
+  lines.push(`  Documentation:  ${CYAN}https://prjct.app${RESET}`)
+  lines.push(`  GitHub:         ${CYAN}https://github.com/jlopezlira/prjct-cli${RESET}`)
+  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(`${CYAN}${BOLD}prjct ${cmd.name}${RESET} - ${cmd.description}`)
+  lines.push('')
+
+  lines.push(`${BOLD}USAGE${RESET}`)
+  lines.push(`  ${cmd.example}`)
+  lines.push('')
+
+  if (cmd.options) {
+    lines.push(`${BOLD}OPTIONS${RESET}`)
+    for (const opt of cmd.options) {
+      lines.push(`  ${opt}`)
+    }
+    lines.push('')
+  }
+
+  if (cmd.subcommands) {
+    lines.push(`${BOLD}SUBCOMMANDS${RESET}`)
+    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(`${CYAN}${BOLD}p. ${cmd.name}${RESET} - ${cmd.description}`)
+  lines.push('')
+
+  lines.push(`${BOLD}USAGE${RESET}`)
+  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(`${BOLD}PARAMETERS${RESET}`)
+    lines.push(`  ${cmd.params}`)
+    lines.push('')
+  }
+
+  if (cmd.features && cmd.features.length > 0) {
+    lines.push(`${BOLD}FEATURES${RESET}`)
+    for (const feature of cmd.features) {
+      lines.push(`  • ${feature}`)
+    }
+    lines.push('')
+  }
+
+  if (cmd.blockingRules) {
+    lines.push(`${BOLD}REQUIREMENTS${RESET}`)
+    lines.push(`  ${YELLOW}⚠${RESET} ${cmd.blockingRules.check}`)
+    lines.push('')
+  }
+
+  // Category info
+  const category = CATEGORIES[cmd.group]
+  if (category) {
+    lines.push(`${DIM}Category: ${category.title}${RESET}`)
+    if (cmd.isOptional) {
+      lines.push(`${DIM}This is an optional command.${RESET}`)
+    }
+    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 `
+${YELLOW}Command '${commandName}' not found.${RESET}
+
+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(`${CYAN}${BOLD}All Commands${RESET}`)
+  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(
+      `${BOLD}${category.title}${RESET} ${DIM}(${categoryCommands.length} commands)${RESET}`
+    )
+    lines.push(`${DIM}${category.description}${RESET}`)
+    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(`${DIM}Run 'prjct help <command>' for detailed help on a specific command.${RESET}`)
+  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)
+}
+
+export default {
+  formatMainHelp,
+  formatCommandHelp,
+  formatCommandList,
+  formatTerminalCommandHelp,
+  formatAgentCommandHelp,
+  getHelp,
+}

package/core/utils/preserve-sections.ts

@@ -0,0 +1,218 @@
+/**
+ * Preserve Sections Utility
+ *
+ * Extracts and preserves user-customized sections during file regeneration.
+ * Users can mark sections with preserve markers to survive sync.
+ *
+ * Usage in CLAUDE.md or other context files:
+ * ```markdown
+ * <!-- prjct:preserve -->
+ * # My Custom Rules
+ * - Always use tabs
+ * - Prefer functional patterns
+ * <!-- /prjct:preserve -->
+ * ```
+ *
+ * @see PRJ-115
+ * @module utils/preserve-sections
+ */
+
+export interface PreservedSection {
+  id: string
+  content: string
+  startIndex: number
+  endIndex: number
+}
+
+// Markers for preserved sections
+const PRESERVE_START = '<!-- prjct:preserve -->'
+const PRESERVE_END = '<!-- /prjct:preserve -->'
+const PRESERVE_END_PATTERN = '<!-- /prjct:preserve -->'
+
+// Named section markers (optional identifier) - create fresh regex each time
+// Uses [\w-]+ to allow hyphens in section names (e.g., "custom-rules")
+function createPreserveStartRegex(): RegExp {
+  return /<!-- prjct:preserve(?::([\w-]+))? -->/g
+}
+
+/**
+ * Extract all preserved sections from content
+ */
+export function extractPreservedSections(content: string): PreservedSection[] {
+  const sections: PreservedSection[] = []
+  const regex = createPreserveStartRegex()
+
+  let match: RegExpExecArray | null
+  let sectionIndex = 0
+
+  while ((match = regex.exec(content)) !== null) {
+    const startIndex = match.index
+    const startTag = match[0]
+    const sectionId = match[1] || `section-${sectionIndex++}`
+
+    // Find the closing tag
+    const endTagStart = content.indexOf(PRESERVE_END_PATTERN, startIndex + startTag.length)
+
+    if (endTagStart === -1) {
+      // No closing tag found - skip this section
+      continue
+    }
+
+    const endIndex = endTagStart + PRESERVE_END_PATTERN.length
+
+    // Extract the content between markers (including markers)
+    const fullContent = content.substring(startIndex, endIndex)
+
+    sections.push({
+      id: sectionId,
+      content: fullContent,
+      startIndex,
+      endIndex,
+    })
+  }
+
+  return sections
+}
+
+/**
+ * Extract the inner content of preserved sections (without markers)
+ */
+export function extractPreservedContent(content: string): string[] {
+  const sections = extractPreservedSections(content)
+
+  return sections.map((section) => {
+    // Remove the markers to get just the inner content
+    let inner = section.content
+    inner = inner.replace(createPreserveStartRegex(), '').replace(PRESERVE_END_PATTERN, '')
+    return inner.trim()
+  })
+}
+
+/**
+ * Check if content has any preserved sections
+ */
+export function hasPreservedSections(content: string): boolean {
+  return content.includes(PRESERVE_START) || createPreserveStartRegex().test(content)
+}
+
+/**
+ * Merge preserved sections from old content into new content
+ *
+ * Strategy:
+ * 1. Extract preserved sections from old content
+ * 2. Append them to the end of new content
+ * 3. Ensure proper spacing
+ *
+ * @param newContent - Freshly generated content
+ * @param oldContent - Previous content with user customizations
+ * @returns Merged content with preserved sections
+ */
+export function mergePreservedSections(newContent: string, oldContent: string): string {
+  const preservedSections = extractPreservedSections(oldContent)
+
+  if (preservedSections.length === 0) {
+    return newContent
+  }
+
+  // Build the merged content
+  let merged = newContent.trimEnd()
+
+  // Add separator before preserved sections
+  merged += '\n\n---\n\n'
+  merged += '## Your Customizations\n\n'
+  merged += '_The sections below are preserved during sync. Edit freely._\n\n'
+
+  // Append each preserved section
+  for (const section of preservedSections) {
+    merged += section.content
+    merged += '\n\n'
+  }
+
+  return merged.trimEnd() + '\n'
+}
+
+/**
+ * Create an empty preserve block for users to customize
+ */
+export function createEmptyPreserveBlock(title?: string): string {
+  const header = title ? `\n# ${title}\n` : '\n'
+  return `${PRESERVE_START}${header}<!-- Add your custom instructions here -->\n${PRESERVE_END}`
+}
+
+/**
+ * Wrap content in preserve markers
+ */
+export function wrapInPreserveMarkers(content: string, id?: string): string {
+  const startTag = id ? `<!-- prjct:preserve:${id} -->` : PRESERVE_START
+  return `${startTag}\n${content}\n${PRESERVE_END}`
+}
+
+/**
+ * Remove all preserved sections from content
+ * (Useful for getting the auto-generated portion only)
+ */
+export function stripPreservedSections(content: string): string {
+  const sections = extractPreservedSections(content)
+
+  if (sections.length === 0) {
+    return content
+  }
+
+  // Remove sections in reverse order to preserve indices
+  let result = content
+  for (let i = sections.length - 1; i >= 0; i--) {
+    const section = sections[i]
+    result = result.substring(0, section.startIndex) + result.substring(section.endIndex)
+  }
+
+  // Clean up any resulting double newlines
+  result = result.replace(/\n{3,}/g, '\n\n')
+
+  return result.trim()
+}
+
+/**
+ * Validate that all preserve blocks are properly closed
+ */
+export function validatePreserveBlocks(content: string): {
+  valid: boolean
+  errors: string[]
+} {
+  const errors: string[] = []
+
+  const startMatches = content.match(/<!-- prjct:preserve(?::\w+)? -->/g) || []
+  const endMatches = content.match(/<!-- \/prjct:preserve -->/g) || []
+
+  if (startMatches.length !== endMatches.length) {
+    errors.push(
+      `Mismatched preserve markers: ${startMatches.length} opening, ${endMatches.length} closing`
+    )
+  }
+
+  // Check for nested blocks (not supported)
+  let depth = 0
+  let maxDepth = 0
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/<!-- prjct:preserve(?::\w+)? -->/.test(line)) {
+      depth++
+      maxDepth = Math.max(maxDepth, depth)
+    }
+    if (line.includes(PRESERVE_END_PATTERN)) {
+      depth--
+    }
+    if (depth > 1) {
+      errors.push(`Nested preserve blocks detected at line ${i + 1} (not supported)`)
+    }
+    if (depth < 0) {
+      errors.push(`Unexpected closing marker at line ${i + 1}`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}