prjct-cli 0.11.3 → 0.11.5

package/core/agentic/context-builder.js

@@ -1,20 +1,19 @@
 /**
  * Context Builder
- * Builds project context for Claude to make decisions
- * NO if/else logic - just data collection
+ * Builds project context for Claude with smart caching.
  *
- * OPTIMIZATION (P0.1): Smart Context Caching
- * - Parallel file reads with Promise.all()
- * - Session-based caching to avoid redundant reads
- * - Selective loading based on command needs
- *
- * Source: Windsurf, Cursor patterns
+ * @module agentic/context-builder
+ * @version 0.1
  */
 
 const fs = require('fs').promises
 const pathManager = require('../infrastructure/path-manager')
 const configManager = require('../infrastructure/config-manager')
 
+/**
+ * Builds and caches project context for Claude decisions.
+ * Features parallel reads, selective loading, and anti-hallucination mtime checks.
+ */
 class ContextBuilder {
   constructor() {
     // Session cache - cleared between commands or after timeout

package/core/agentic/memory-system.js

@@ -1,19 +1,9 @@
 /**
  * Layered Memory System
- * Three-tier memory for learning user patterns and preferences
+ * Three-tier memory for learning user patterns and preferences.
  *
- * OPTIMIZATION (P1.1): Pattern-Based Decision Making
- * - Tier 1: Session memory (current command context)
- * - Tier 2: Patterns (recurring decisions/preferences)
- * - Tier 3: History (append-only JSONL for audit)
- *
- * P3.3: Enhanced with semantic tags and CRUD operations
- * - Semantic tags for categorization
- * - Auto-memory from user decisions
- * - Relevance-based retrieval
- * - CRUD operations (create/update/delete)
- *
- * Source: Windsurf create_memory, Augment remember patterns
+ * @module agentic/memory-system
+ * @version 3.3
  */
 
 const fs = require('fs').promises
@@ -21,7 +11,8 @@ const path = require('path')
 const pathManager = require('../infrastructure/path-manager')
 
 /**
- * P3.3: Semantic tags for memory categorization
+ * Semantic tags for memory categorization
+ * @enum {string}
  */
 const MEMORY_TAGS = {
   // Code preferences
@@ -46,17 +37,21 @@ const MEMORY_TAGS = {
   AGENT_PREFERENCE: 'agent_preference'
 }
 
+/**
+ * Three-tier memory system for learning user patterns.
+ * Tier 1: Session (ephemeral), Tier 2: Patterns (persistent), Tier 3: History (JSONL)
+ */
 class MemorySystem {
   constructor() {
-    // Session memory (in-process, cleared on restart)
+    /** @type {Map<string, {value: any, timestamp: number}>} */
     this._sessionMemory = new Map()
-
-    // Pattern cache (loaded from disk)
+    /** @type {Object|null} */
     this._patterns = null
+    /** @type {boolean} */
     this._patternsLoaded = false
-
-    // P3.3: Memories database (semantic tagged)
+    /** @type {Object|null} */
     this._memories = null
+    /** @type {boolean} */
     this._memoriesLoaded = false
   }
 

package/core/agentic/prompt-builder.js

@@ -1,28 +1,31 @@
 /**
  * Prompt Builder
- * Builds prompts for Claude based on templates and context
- * Claude decides what to do - NO if/else logic here
+ * Builds prompts for Claude based on templates and context.
+ * Claude decides what to do - NO if/else logic here.
  *
- * P1.1: Includes learned patterns from memory system
- * P3.1: Includes think blocks for anti-hallucination
- * P3.3: Includes relevant memories from semantic database
- * P3.4: Includes plan mode instructions
- * P4.1: Includes quality checklists (Claude decides which to apply)
+ * @module agentic/prompt-builder
+ * @version 4.1
  */
 
 const fs = require('fs')
 const path = require('path')
 
+/**
+ * Builds prompts for Claude using templates, context, and learned patterns.
+ * Supports plan mode, think blocks, and quality checklists.
+ */
 class PromptBuilder {
   constructor() {
+    /** @type {Object<string, string>|null} */
     this._checklistsCache = null
+    /** @type {string|null} */
     this._checklistRoutingCache = null
   }
 
   /**
    * Load quality checklists from templates/checklists/
-   * Returns checklist content - Claude decides which to apply
-   * NO if/else logic here - just load and provide
+   *
+   * @returns {Object<string, string>} Map of checklist name to content
    */
   loadChecklists() {
     if (this._checklistsCache) return this._checklistsCache
@@ -48,8 +51,9 @@ class PromptBuilder {
   }
 
   /**
-   * Load checklist routing template
-   * Claude reads this to decide which checklists to apply
+   * Load checklist routing template for Claude to decide which checklists apply
+   *
+   * @returns {string|null} Routing template content or null if not found
    */
   loadChecklistRouting() {
     if (this._checklistRoutingCache) return this._checklistRoutingCache
@@ -67,12 +71,17 @@ class PromptBuilder {
     return this._checklistRoutingCache || null
   }
   /**
-   * Build concise prompt - only essentials
-   * CRITICAL: Includes full agent content if agent is provided
-   * P1.1: Includes learned patterns to avoid repetitive questions
-   * P3.1: Includes think blocks for critical decisions
-   * P3.3: Includes relevant memories from semantic database
-   * P3.4: Includes plan mode status and constraints
+   * Build a complete prompt for Claude from template, context, and enhancements
+   *
+   * @param {Object} template - Template with frontmatter and content
+   * @param {Object} context - Project context (projectPath, projectId, files, params)
+   * @param {Object} state - Current prjct state (now, next, analysis, etc.)
+   * @param {Object|null} [agent] - Specialized agent config (name, role, skills)
+   * @param {Object|null} [learnedPatterns] - User preferences from memory system
+   * @param {Object|null} [thinkBlock] - Reasoning block (plan, conclusions, confidence)
+   * @param {Array|null} [relevantMemories] - Past decisions from semantic database
+   * @param {Object|null} [planInfo] - Plan mode status (isPlanning, requiresApproval)
+   * @returns {string} Complete prompt ready for Claude
    */
   build(template, context, state, agent = null, learnedPatterns = null, thinkBlock = null, relevantMemories = null, planInfo = null) {
     const parts = []
@@ -233,8 +242,10 @@ class PromptBuilder {
   }
 
   /**
-   * Filter only relevant state data
-   * IMPROVED: Include more context, don't truncate critical info
+   * Filter state data to include only relevant portions for the prompt
+   *
+   * @param {Object} state - Full prjct state object
+   * @returns {string|null} Formatted relevant state or null if empty
    */
   filterRelevantState(state) {
     if (!state || Object.keys(state).length === 0) return null
@@ -264,10 +275,10 @@ class PromptBuilder {
   }
 
   /**
-   * Build analysis prompt
-   * Used for tasks that need Claude to analyze before acting
-   * @param {string} analysisType - Type of analysis
-   * @param {Object} context - Context
+   * Build an analysis prompt for pre-action investigation tasks
+   *
+   * @param {string} analysisType - Type of analysis (e.g., 'patterns', 'stack')
+   * @param {Object} context - Project context with projectPath and projectId
    * @returns {string} Analysis prompt
    */
   buildAnalysis(analysisType, context) {
@@ -285,8 +296,10 @@ class PromptBuilder {
   }
 
   /**
-   * Extract pattern summary from full patterns content
-   * OPTIMIZED: Returns only conventions + high-priority anti-patterns (800 bytes max)
+   * Extract compressed pattern summary (conventions + high-priority anti-patterns)
+   *
+   * @param {string} content - Full patterns file content
+   * @returns {string|null} Compressed summary (max 800 bytes) or null
    */
   extractPatternSummary(content) {
     if (!content) return null
@@ -317,8 +330,9 @@ class PromptBuilder {
   }
 
   /**
-   * Build critical rules - compressed anti-hallucination
-   * OPTIMIZED: From 66 lines to 12 lines (~82% reduction)
+   * Build critical anti-hallucination rules section
+   *
+   * @returns {string} Formatted rules block
    */
   buildCriticalRules() {
     const fileCount = this._currentContext?.files?.length || this._currentContext?.filteredSize || 0

package/core/agentic/template-loader.js

@@ -1,12 +1,18 @@
 /**
  * Template Loader
- * Loads command templates with frontmatter parsing
- * Templates define what Claude should do - NO if/else logic
+ * Loads and parses command templates with frontmatter.
+ *
+ * @module agentic/template-loader
+ * @version 1.0.0
  */
 
 const fs = require('fs').promises
 const path = require('path')
 
+/**
+ * Loads command templates from templates/commands/ with caching.
+ * Parses YAML-like frontmatter for metadata extraction.
+ */
 class TemplateLoader {
   constructor() {
     this.templatesDir = path.join(__dirname, '..', '..', 'templates', 'commands')

package/core/infrastructure/agent-detector.js

@@ -1,15 +1,18 @@
 /**
- * Agent Detection Module for prjct-cli
- *
- * 100% Claude-focused architecture
- * Detects Claude Code and Claude Desktop environments
+ * Agent Detector
+ * Detects Claude Code and Claude Desktop environments.
  *
+ * @module infrastructure/agent-detector
  * @version 0.5.0
  */
 
 const fs = require('fs')
 const path = require('path')
 
+/**
+ * Detects the current execution environment (Claude or Terminal).
+ * Provides appropriate capabilities and configuration for each environment.
+ */
 class AgentDetector {
   constructor() {
     this.detectedAgent = null

package/core/infrastructure/migrator.js

@@ -1,3 +1,11 @@
+/**
+ * Migrator
+ * Handles migrations between prjct versions and structures.
+ *
+ * @module infrastructure/migrator
+ * @version 0.3.0
+ */
+
 const fs = require('fs').promises
 const path = require('path')
 const pathManager = require('./path-manager')
@@ -5,19 +13,8 @@ const configManager = require('./config-manager')
 const authorDetector = require('./author-detector')
 
 /**
- * Migrator - Handles migrations between versions
- *
- * Migration process:
- * 1. Detect legacy .prjct directory (v0.1.0 → v0.2.x)
- * 2. Detect author information
- * 3. Create prjct.config.json
- * 4. Create global directory structure
- * 5. Copy all files to global location
- * 6. Move authors/version/created/lastSync to global config (v0.2.x → v0.3.0)
- * 7. Validate migration
- * 8. Optionally remove local .prjct
- *
- * @version 0.3.0
+ * Handles version migrations and project structure updates.
+ * Supports legacy → global storage migration and config version upgrades.
  */
 class Migrator {
   /**

package/core/infrastructure/session-manager.js

@@ -1,3 +1,11 @@
+/**
+ * Session Manager
+ * Manages temporal fragmentation of logs and progress data.
+ *
+ * @module infrastructure/session-manager
+ * @version 0.2.1
+ */
+
 const path = require('path')
 const pathManager = require('./path-manager')
 const { VERSION } = require('../utils/version')
@@ -6,16 +14,8 @@ const jsonlHelper = require('../utils/jsonl-helper')
 const fileHelper = require('../utils/file-helper')
 
 /**
- * SessionManager - Manages temporal fragmentation of logs and progress data
- *
- * Handles:
- * - Daily session creation and rotation
- * - Writing logs to date-specific directories
- * - Reading historical data across multiple sessions
- * - Session consolidation and queries
- * - Automatic migration from legacy single-file logs
- *
- * @version 0.2.1
+ * Manages daily sessions for logs and progress data.
+ * Handles rotation, historical queries, and legacy migration.
  */
 class SessionManager {
   constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Built for Claude - Ship fast, track progress, stay focused. Developer momentum tool for indie hackers.",
   "main": "core/index.js",
   "bin": {