prjct-cli 0.8.4 → 0.8.8

package/CHANGELOG.md

@@ -7,6 +7,121 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.8] - 2025-10-06
+
+### Added
+
+- **System timestamp tools** - LLM now gets real date/time from system instead of guessing
+  - ✅ `GetTimestamp()` tool - Returns ISO timestamp from system clock
+  - ✅ `GetDate()` tool - Returns YYYY-MM-DD from system clock
+  - ✅ `GetDateTime()` tool - Returns full date/time object with components
+  - 🐛 **Bug fixed**: Tasks no longer show January 1st dates when it's October
+  - 📊 Impact: Session files now use correct dates, analytics work properly
+
+- **Template optimization** - Phase 1 complete: Top 7 critical templates optimized
+  - ✅ Reduced from 2006 → 605 lines (69.8% reduction, saved 1401 lines)
+  - ✅ All templates now in English only (removed Spanish examples)
+  - ✅ Preserved 100% of business logic and decision-making patterns
+  - ✅ Removed verbose examples, success criteria, redundant explanations
+  - 📊 Impact: Faster LLM processing, lower token usage, clearer instructions
+
+- **Legacy installation cleanup** - Automatic detection and removal of curl-based installations
+  - ✅ Detects legacy `~/.prjct-cli/` from curl install.sh (pre-v0.8.2)
+  - ✅ Migrates project data to npm global location automatically
+  - ✅ Removes legacy installation files (bin/, core/, templates/, etc.)
+  - ✅ Preserves user data (projects/ directory migrated safely)
+  - ✅ Cleans up shell PATH entries (bash/zsh/PowerShell)
+  - ✅ Removes legacy symlinks on Unix systems
+  - 🎯 **Impact**: Users on old curl installations automatically migrate to npm
+  - 🔧 **Windows compatible**: Handles PowerShell profiles, skips Unix-only operations
+
+### Changed
+
+- **Critical timestamp rule in CLAUDE.md** - Added prominent warning about LLM timestamp limitations
+  - LLM knowledge cutoff is January 2025, cannot generate accurate timestamps
+  - All templates now include `timestamp-rule` in frontmatter
+  - Templates updated: feature.md, ship.md, now.md, build.md, idea.md
+  - Hardcoded example dates replaced with GetTimestamp()/GetDate() tool calls
+
+- **Templates optimized** (Phase 1 - Top 7)
+  - suggest.md: 555 → 96 lines (82.7% reduction)
+  - ask.md: 386 → 73 lines (81.1% reduction)
+  - help.md: 348 → 90 lines (74.1% reduction)
+  - feature.md: 239 → 93 lines (61.1% reduction)
+  - init.md: 210 → 113 lines (46.2% reduction)
+  - ship.md: 148 → 79 lines (46.6% reduction)
+  - migrate-all.md: 120 → 61 lines (49.2% reduction)
+
+- **context-builder.js** - Enhanced timestamp documentation
+  - Clarified that timestamps come from system clock, not LLM
+  - Added inline comments explaining ISO format and YYYY-MM-DD format
+
+- **install.sh deprecation** - Enhanced messaging with legacy detection
+  - Now detects if user has legacy curl installation
+  - Shows version and location of legacy install
+  - Provides clear migration instructions
+  - Explains automatic cleanup process
+
+- **All Spanish removed from codebase** - 100% English documentation
+  - Updated all JSDoc comments to English
+  - Removed Spanish examples from templates
+  - Fixed: setup.js, postinstall.js, AGENTS.md
+
+### Fixed
+
+- **Session date accuracy** - All session files now use correct system date
+  - Previously: LLM generated timestamps (often January 1st)
+  - Now: System clock provides accurate timestamps via GetTimestamp() tool
+  - Duration calculations now accurate
+  - Progress tracking and analytics now reliable
+
+- **Windows compatibility** - Full cross-platform support
+  - Legacy installer detector works on Windows
+  - Platform detection via `process.platform === 'win32'`
+  - PowerShell profile cleanup (instead of bash/zsh)
+  - Skips symlink cleanup on Windows (Unix-only feature)
+  - Cross-platform path handling with `os.homedir()` and `path.join()`
+  - Command installer already works on Windows (no changes needed)
+
+## [0.8.6] - 2025-10-05
+
+### Fixed
+
+- **Critical: Command update system** - Fixed command synchronization to ALWAYS update to latest version
+  - ✅ Removed mtime comparison (was causing commands to stay outdated)
+  - ✅ ALWAYS overwrites existing commands with latest templates
+  - ✅ Guarantees all clients get updated commands on `npm update`
+  - ✅ Preserves legacy commands (removed: always 0)
+  - 🐛 **Bug fixed**: `now.md`, `done.md` and other commands now update correctly across all client installations
+
+- **Setup architecture redesigned** - Dual-defense strategy for reliable setup
+  - ✅ First-use setup check in `bin/prjct` (guaranteed execution)
+  - ✅ Optional postinstall optimization (when scripts enabled)
+  - ✅ Works in CI/CD environments with `--ignore-scripts`
+  - ✅ Version tracking via `editors-config.js`
+  - ✅ Zero manual steps required
+
+### Changed
+
+- **Command sync behavior** (`syncCommands()`)
+  - Previous: Compared mtime, only updated if source newer → ❌ Unreliable
+  - Now: ALWAYS overwrites existing commands → ✅ Always latest version
+  - Preserves legacy/custom commands not in templates
+  - Result: `{ added: X, updated: Y, removed: 0 }`
+
+- **Setup flow**
+  - Centralized all logic in `core/infrastructure/setup.js`
+  - `bin/prjct` checks version on every execution
+  - `scripts/postinstall.js` simplified to optional helper
+  - Auto-setup triggers on version mismatch or first use
+
+### Technical
+
+- Reduced `scripts/postinstall.js` from 250 → 69 lines
+- Created `core/infrastructure/setup.js` (167 lines) - single source of truth
+- Modified `bin/prjct` to include version check (34 lines)
+- Removed `.setup-complete` marker (using JSON version tracking instead)
+
 ## [0.8.2] - 2025-10-05
 
 ### Changed

package/CLAUDE.md

@@ -6,6 +6,40 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **prjct-cli** is a developer momentum tool for solo builders, indie hackers, and small teams (2-5 people). Just ship. No BS. Track progress through slash commands without meetings, ceremonies, or traditional PM overhead.
 
+## ⚠️ CRITICAL: Timestamp Management
+
+**LLM DOES NOT KNOW CURRENT DATE/TIME** - Your knowledge cutoff is January 2025, and you cannot generate accurate timestamps.
+
+### Timestamp Tools (MUST USE)
+
+**ALWAYS use these tools for ALL timestamps and dates:**
+
+- `GetTimestamp()` → Returns current system time in ISO format (e.g., "2025-10-07T14:30:00.000Z")
+- `GetDate()` → Returns current date in YYYY-MM-DD format (e.g., "2025-10-07")
+- `GetDateTime()` → Returns object with timestamp, date, year, month, day
+
+### Rules
+
+1. **NEVER generate timestamps manually** - All dates like "2025-10-04" or "2025-01-01" are WRONG
+2. **ALWAYS call GetTimestamp()** when writing to session files (*.jsonl)
+3. **ALWAYS call GetDate()** when adding entries to index files (shipped.md, roadmap.md, ideas.md)
+4. **Templates have `timestamp-rule`** in frontmatter - READ AND FOLLOW IT
+5. **Session files are organized by date** - Use system date to determine correct file path
+
+### Example (CORRECT)
+
+```jsonl
+{"ts":"{GetTimestamp()}","type":"feature_add","name":"auth","tasks":5}
+```
+
+### Example (WRONG - DO NOT DO THIS)
+
+```jsonl
+{"ts":"2025-10-04T14:30:00Z","type":"feature_add","name":"auth","tasks":5}
+```
+
+**Why this matters**: Without system timestamps, all session data shows January 1st dates, making analytics and progress tracking completely broken.
+
 ## 🚀 Real-World Workflow (Simplified)
 
 prjct follows your **actual** development workflow with 5 essential commands:

package/bin/prjct

@@ -1,181 +1,34 @@
 #!/usr/bin/env node
 
 /**
- * prjct CLI - 100% Agentic Entry Point
+ * prjct CLI entry point
  *
- * Uses command-registry as single source of truth.
- * Zero hardcoded logic - all commands resolved dynamically.
+ * Auto-setup on first use (like Astro, Vite, etc.)
  */
 
-const PrjctCommands = require('../core/commands')
-const registry = require('../core/command-registry')
-
-async function main() {
-  const [commandName, ...rawArgs] = process.argv.slice(2)
-
-  // === SPECIAL COMMANDS (version, help) ===
-
-  if (['-v', '--version', 'version'].includes(commandName)) {
-    const packageJson = require('../package.json')
-    console.log(`prjct-cli v${packageJson.version}`)
-    process.exit(0)
-  }
-
-  if (['-h', '--help', 'help', undefined].includes(commandName)) {
-    displayHelp()
-    process.exit(0)
-  }
-
-  // === DYNAMIC COMMAND EXECUTION ===
+const { VERSION } = require('../core/utils/version')
+const editorsConfig = require('../core/infrastructure/editors-config')
 
+// Ensure setup has run for this version
+;(async function ensureSetup() {
   try {
-    // 1. Find command in registry
-    const cmd = registry.getByName(commandName)
-
-    if (!cmd) {
-      console.error(`Unknown command: ${commandName}`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
-      process.exit(1)
-    }
-
-    // 2. Check if deprecated (before checking implemented)
-    if (cmd.deprecated) {
-      console.error(`Command '${commandName}' is deprecated.`)
-      if (cmd.replacedBy) {
-        console.error(`Use 'prjct ${cmd.replacedBy}' instead.`)
-      }
-      process.exit(1)
-    }
-
-    // 3. Check if implemented
-    if (!cmd.implemented) {
-      console.error(`Command '${commandName}' exists but is not yet implemented.`)
-      console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
-      process.exit(1)
-    }
-
-    // 4. Parse arguments based on command definition
-    const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs)
-
-    // 5. Instantiate commands handler
-    const commands = new PrjctCommands()
+    const lastVersion = await editorsConfig.getLastVersion()
 
-    // 6. Execute command
-    let result
+    if (!lastVersion || lastVersion !== VERSION) {
+      console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')
+      console.log('🔧 One-time setup (v' + VERSION + ')...')
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n')
 
-    // Commands with special option handling
-    if (commandName === 'design') {
-      const target = parsedArgs.join(' ')
-      result = await commands.design(target, options)
-    } else if (commandName === 'analyze') {
-      result = await commands.analyze(options)
-    } else if (commandName === 'cleanup') {
-      result = await commands.cleanup(options)
-    } else if (commandName === 'setup') {
-      result = await commands.setup(options)
-    } else if (commandName === 'migrate-all') {
-      result = await commands.migrateAll(options)
-    } else if (commandName === 'progress') {
-      const period = parsedArgs[0] || 'week'
-      result = await commands.progress(period)
-    } else if (commandName === 'build') {
-      const taskOrNumber = parsedArgs.join(' ')
-      result = await commands.build(taskOrNumber)
-    } else {
-      // Standard commands (most common case)
-      const param = parsedArgs.join(' ') || null
-      result = await commands[commandName](param)
-    }
+      const setup = require('../core/infrastructure/setup')
+      await setup.run()
 
-    // 7. Display result
-    if (result && result.message) {
-      console.log(result.message)
+      console.log('✓ Setup complete!\n')
     }
-
-    process.exit(result && result.success ? 0 : 1)
   } catch (error) {
-    console.error('Error:', error.message)
-    if (process.env.DEBUG) {
-      console.error(error.stack)
-    }
-    process.exit(1)
+    console.error('\n⚠️  Setup warning:', error.message)
+    console.error('You can run setup manually: prjct setup\n')
   }
-}
 
-/**
- * Parse command arguments dynamically
- */
-function parseCommandArgs(cmd, rawArgs) {
-  const parsedArgs = []
-  const options = {}
-
-  for (let i = 0; i < rawArgs.length; i++) {
-    const arg = rawArgs[i]
-
-    if (arg.startsWith('--')) {
-      // Handle flags
-      const flagName = arg.slice(2)
-
-      // Check if next arg is a value (doesn't start with --)
-      if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
-        options[flagName] = rawArgs[++i]
-      } else {
-        options[flagName] = true
-      }
-    } else {
-      parsedArgs.push(arg)
-    }
-  }
-
-  return { parsedArgs, options }
-}
-
-/**
- * Display help using registry
- */
-function displayHelp() {
-  const categories = registry.getCategories()
-  const categorizedCommands = {}
-
-  // Group commands by category (exclude deprecated)
-  registry.getTerminalCommands().forEach((cmd) => {
-    if (cmd.deprecated) return
-
-    if (!categorizedCommands[cmd.category]) {
-      categorizedCommands[cmd.category] = []
-    }
-    categorizedCommands[cmd.category].push(cmd)
-  })
-
-  console.log('prjct - Developer momentum tool for solo builders')
-  console.log('\nAvailable commands:\n')
-
-  // Display commands by category
-  Object.entries(categorizedCommands).forEach(([categoryKey, cmds]) => {
-    const categoryInfo = categories[categoryKey]
-    console.log(`  ${categoryInfo.title}:`)
-
-    cmds.forEach((cmd) => {
-      const params = cmd.params ? ` ${cmd.params}` : ''
-      const spacing = ' '.repeat(Math.max(20 - cmd.name.length - params.length, 1))
-      const impl = cmd.implemented ? '' : ' (not implemented)'
-      console.log(`    ${cmd.name}${params}${spacing}${cmd.description}${impl}`)
-    })
-
-    console.log('')
-  })
-
-  const stats = registry.getStats()
-  console.log(`Total: ${stats.implemented} implemented / ${stats.total} commands`)
-  console.log('\nFor more info: https://prjct.app')
-}
-
-// Run CLI
-main().catch((error) => {
-  console.error('Fatal error:', error.message)
-  if (process.env.DEBUG) {
-    console.error(error.stack)
-  }
-  process.exit(1)
-})
+  // Continue to main CLI logic
+  require('../core/index')
+})()

package/core/agentic/context-builder.js

@@ -41,9 +41,10 @@ class ContextBuilder {
       // Command parameters
       params: commandParams,
 
-      // Timestamps
-      timestamp: new Date().toISOString(),
-      date: new Date().toLocaleString(),
+      // System timestamps (ALWAYS use these, NEVER generate timestamps)
+      // LLM does not know current date/time - these are from system clock
+      timestamp: new Date().toISOString(), // ISO format: "2025-10-07T14:30:00.000Z"
+      date: new Date().toISOString().split('T')[0], // YYYY-MM-DD: "2025-10-07"
     }
   }
 

package/core/agentic/tool-registry.js

@@ -9,6 +9,7 @@ const path = require('path')
 const { promisify } = require('util')
 const { exec: execCallback } = require('child_process')
 const exec = promisify(execCallback)
+const dateHelper = require('../utils/date-helper')
 
 class ToolRegistry {
   constructor() {
@@ -17,6 +18,9 @@ class ToolRegistry {
       Write: this.write.bind(this),
       Bash: this.bash.bind(this),
       Exec: this.bash.bind(this), // Alias
+      GetTimestamp: this.getTimestamp.bind(this),
+      GetDate: this.getDate.bind(this),
+      GetDateTime: this.getDateTime.bind(this),
     }
   }
 
@@ -112,6 +116,37 @@ class ToolRegistry {
       return []
     }
   }
+
+  /**
+   * Get current system timestamp (ISO format)
+   * LLM MUST use this instead of generating timestamps
+   * @returns {Promise<string>} ISO timestamp (e.g., "2025-10-07T14:30:00.000Z")
+   */
+  async getTimestamp() {
+    return dateHelper.getTimestamp()
+  }
+
+  /**
+   * Get current system date (YYYY-MM-DD)
+   * LLM MUST use this instead of generating dates
+   * @returns {Promise<string>} Date string (e.g., "2025-10-07")
+   */
+  async getDate() {
+    return dateHelper.getTodayKey()
+  }
+
+  /**
+   * Get current system date/time components
+   * @returns {Promise<Object>} Date components {timestamp, date, year, month, day}
+   */
+  async getDateTime() {
+    const now = new Date()
+    return {
+      timestamp: dateHelper.getTimestamp(),
+      date: dateHelper.getTodayKey(),
+      ...dateHelper.getYearMonthDay(now),
+    }
+  }
 }
 
 module.exports = new ToolRegistry()

package/core/commands.js

@@ -1126,6 +1126,81 @@ class PrjctCommands {
    * /p:design - Design system architecture, APIs, and components
    * AGENTIC EXECUTION
    */
+  /**
+   * Memory cleanup helper
+   * Rotates large JSONL files, archives old sessions, reports disk usage
+   * @private
+   */
+  async _cleanupMemory(projectPath) {
+    const projectId = await configManager.getProjectId(projectPath)
+    const globalPath = pathManager.getGlobalProjectPath(projectId)
+
+    console.log('📊 Analyzing disk usage...\n')
+
+    const results = {
+      rotated: [],
+      archived: [],
+      totalSize: 0,
+      freedSpace: 0,
+    }
+
+    // 1. Check and rotate large JSONL files
+    const jsonlFiles = [
+      pathManager.getFilePath(projectId, 'memory', 'context.jsonl'),
+      pathManager.getFilePath(projectId, 'progress', 'shipped.md'),
+      pathManager.getFilePath(projectId, 'planning', 'ideas.md'),
+    ]
+
+    for (const filePath of jsonlFiles) {
+      try {
+        const sizeMB = await jsonlHelper.getFileSizeMB(filePath)
+        if (sizeMB > 0) {
+          results.totalSize += sizeMB
+
+          const rotated = await jsonlHelper.rotateJsonLinesIfNeeded(filePath, 10)
+          if (rotated) {
+            results.rotated.push(path.basename(filePath))
+            results.freedSpace += sizeMB
+          }
+        }
+      } catch (error) {
+        // File doesn't exist, skip
+      }
+    }
+
+    // 2. Report disk usage
+    console.log('💾 Disk Usage Report:\n')
+    console.log(`   Total size: ${results.totalSize.toFixed(2)}MB`)
+    console.log(`   Rotated files: ${results.rotated.length}`)
+
+    if (results.rotated.length > 0) {
+      console.log(`   Freed space: ${results.freedSpace.toFixed(2)}MB\n`)
+      results.rotated.forEach((file) => console.log(`   ✓ ${file}`))
+    } else {
+      console.log('   ✓ No rotation needed - all files under 10MB\n')
+    }
+
+    // 3. Suggestions
+    console.log('\n💡 Recommendations:\n')
+    console.log('   1. Claude Code: Compact conversation regularly')
+    console.log('   2. Exclude from Spotlight: System Settings → Privacy')
+    console.log('   3. Clear npm cache: npm cache clean --force\n')
+
+    return { success: true, results }
+  }
+
+  /**
+   * Internal cleanup helper for memory during normal cleanup
+   * @private
+   */
+  async _cleanupMemoryInternal(projectPath) {
+    const projectId = await configManager.getProjectId(projectPath)
+
+    // Silently rotate large files
+    const memoryPath = pathManager.getFilePath(projectId, 'memory', 'context.jsonl')
+    await jsonlHelper.rotateJsonLinesIfNeeded(memoryPath, 10)
+  }
+
   async design(target = null, options = {}, projectPath = process.cwd()) {
     try {
       const initResult = await this.ensureProjectInit(projectPath)
@@ -1575,6 +1650,13 @@ Process flow for ${target}.
       const initResult = await this.ensureProjectInit(projectPath)
       if (!initResult.success) return initResult
 
+      const isMemoryMode = _options.memory === true || _options.type === 'memory'
+
+      if (isMemoryMode) {
+        console.log('🧹 Memory cleanup...\n')
+        return await this._cleanupMemory(projectPath)
+      }
+
       console.log('🧹 Cleaning up project...\n')
 
       const context = await contextBuilder.build(projectPath)
@@ -1649,6 +1731,8 @@ Process flow for ${target}.
       console.log('✅ Cleanup complete!\n')
       cleaned.forEach((item) => console.log(`   • ${item}`))
 
+      await this._cleanupMemoryInternal(projectPath)
+
       await this.logToMemory(projectPath, 'cleanup_performed', {
         items: cleaned.length,
         timestamp: dateHelper.getTimestamp(),