prjct-cli 0.11.4 → 0.11.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.11.5] - 2025-12-09
+
+### Fixed - Production Server Mode
+
+Critical bug fix: `prjct serve` now runs in production mode instead of development mode.
+
+- **Server Mode** - Changed from dev to production
+  - Default port: 3000 → 9472 (avoids conflicts)
+  - Mode: `npm run dev` → `npm run start:prod` with `NODE_ENV=production`
+  - Auto-build on first run if `.next/` doesn't exist
+  - All features now work correctly (were broken in dev mode)
+
+- **packages/web/package.json** - Added `start:prod` script
+
 ## [0.11.0] - 2025-12-08
 
 ### Added - Web Application & Server Components

package/bin/serve.js

@@ -20,7 +20,7 @@ const webDir = path.join(packagesDir, 'web')
 // Parse arguments
 const args = process.argv.slice(2)
 const portArg = args.find((a) => a.startsWith('--port='))
-const port = portArg ? portArg.split('=')[1] : '3000'
+const port = portArg ? portArg.split('=')[1] : '9472'
 
 // Check if web package exists
 if (!fs.existsSync(webDir)) {
@@ -144,21 +144,37 @@ console.log(`
 ║                                                           ║
 ║   ⚡ prjct - Developer Momentum                          ║
 ║                                                           ║
-║   Starting web server...                                  ║
+║   Production server ready                                 ║
 ║                                                           ║
-║   Web:     http://localhost:${port}                          ║
+║   Web:     http://localhost:${port}                         ║
 ║                                                           ║
 ║   Using your Claude subscription - $0 API costs           ║
 ║                                                           ║
 ╚═══════════════════════════════════════════════════════════╝
 `)
 
-// Start web dev server
-const web = spawn('npm', ['run', 'dev'], {
+// Build for production if needed (first run)
+const nextDir = path.join(webDir, '.next')
+if (!fs.existsSync(nextDir)) {
+  console.log('🔨 Building for production (first run)...\n')
+  const buildResult = spawnSync('npm', ['run', 'build'], {
+    cwd: webDir,
+    stdio: 'inherit',
+    shell: true,
+  })
+  if (buildResult.status !== 0) {
+    console.error('❌ Build failed')
+    process.exit(1)
+  }
+  console.log('✅ Build complete!\n')
+}
+
+// Start web server in production mode
+const web = spawn('npm', ['run', 'start:prod'], {
   cwd: webDir,
   stdio: 'inherit',
   shell: true,
-  env: { ...process.env, PORT: port },
+  env: { ...process.env, PORT: port, NODE_ENV: 'production' },
 })
 
 // Open browser after a short delay

package/core/__tests__/utils/date-helper.test.js

@@ -0,0 +1,416 @@
+/**
+ * Date Helper Tests
+ * Tests for centralized date operations and formatting
+ */
+
+const {
+  formatDate,
+  formatMonth,
+  getTodayKey,
+  getDateKey,
+  getYearMonthDay,
+  parseDate,
+  getTimestamp,
+  getDaysAgo,
+  getDaysFromNow,
+  getDateRange,
+  isToday,
+  isWithinLastDays,
+  formatDuration,
+  calculateDuration,
+  getStartOfDay,
+  getEndOfDay,
+} = require('../../utils/date-helper')
+
+describe('DateHelper', () => {
+  describe('formatDate', () => {
+    it('should format date to YYYY-MM-DD', () => {
+      const date = new Date(2025, 9, 4) // Oct 4, 2025
+      expect(formatDate(date)).toBe('2025-10-04')
+    })
+
+    it('should pad single digit months', () => {
+      const date = new Date(2025, 0, 15) // Jan 15, 2025
+      expect(formatDate(date)).toBe('2025-01-15')
+    })
+
+    it('should pad single digit days', () => {
+      const date = new Date(2025, 11, 5) // Dec 5, 2025
+      expect(formatDate(date)).toBe('2025-12-05')
+    })
+
+    it('should handle year boundaries', () => {
+      const date = new Date(2024, 11, 31) // Dec 31, 2024
+      expect(formatDate(date)).toBe('2024-12-31')
+    })
+  })
+
+  describe('formatMonth', () => {
+    it('should format date to YYYY-MM', () => {
+      const date = new Date(2025, 9, 15) // Oct 15, 2025
+      expect(formatMonth(date)).toBe('2025-10')
+    })
+
+    it('should pad single digit months', () => {
+      const date = new Date(2025, 2, 1) // Mar 1, 2025
+      expect(formatMonth(date)).toBe('2025-03')
+    })
+
+    it('should handle December', () => {
+      const date = new Date(2025, 11, 25) // Dec 25, 2025
+      expect(formatMonth(date)).toBe('2025-12')
+    })
+  })
+
+  describe('getTodayKey', () => {
+    it('should return today in YYYY-MM-DD format', () => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2025, 5, 15)) // June 15, 2025
+
+      expect(getTodayKey()).toBe('2025-06-15')
+
+      vi.useRealTimers()
+    })
+  })
+
+  describe('getDateKey', () => {
+    it('should return date in YYYY-MM-DD format (alias for formatDate)', () => {
+      const date = new Date(2025, 7, 20) // Aug 20, 2025
+      expect(getDateKey(date)).toBe('2025-08-20')
+    })
+  })
+
+  describe('getYearMonthDay', () => {
+    it('should return separate year, month, day strings', () => {
+      const date = new Date(2025, 9, 4) // Oct 4, 2025
+      const result = getYearMonthDay(date)
+
+      expect(result.year).toBe('2025')
+      expect(result.month).toBe('10')
+      expect(result.day).toBe('04')
+    })
+
+    it('should pad month values', () => {
+      const date = new Date(2025, 0, 15) // Jan 15, 2025
+      const result = getYearMonthDay(date)
+
+      expect(result.month).toBe('01')
+    })
+
+    it('should pad day values', () => {
+      const date = new Date(2025, 5, 7) // June 7, 2025
+      const result = getYearMonthDay(date)
+
+      expect(result.day).toBe('07')
+    })
+  })
+
+  describe('parseDate', () => {
+    it('should parse YYYY-MM-DD format', () => {
+      const result = parseDate('2025-10-04')
+      expect(result.getFullYear()).toBe(2025)
+      expect(result.getMonth()).toBe(9) // 0-indexed
+      expect(result.getDate()).toBe(4)
+    })
+
+    it('should parse ISO strings', () => {
+      const result = parseDate('2025-10-04T14:30:00.000Z')
+      expect(result.getFullYear()).toBe(2025)
+      expect(result.getMonth()).toBe(9)
+    })
+  })
+
+  describe('getTimestamp', () => {
+    it('should return ISO timestamp', () => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2025-10-04T14:30:00.000Z'))
+
+      expect(getTimestamp()).toBe('2025-10-04T14:30:00.000Z')
+
+      vi.useRealTimers()
+    })
+
+    it('should include milliseconds', () => {
+      const timestamp = getTimestamp()
+      expect(timestamp).toMatch(/\.\d{3}Z$/)
+    })
+  })
+
+  describe('getDaysAgo', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2025, 9, 15)) // Oct 15, 2025
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('should calculate past dates correctly', () => {
+      const result = getDaysAgo(5)
+      expect(formatDate(result)).toBe('2025-10-10')
+    })
+
+    it('should handle month boundaries', () => {
+      const result = getDaysAgo(20)
+      expect(formatDate(result)).toBe('2025-09-25')
+    })
+
+    it('should return today for 0 days ago', () => {
+      const result = getDaysAgo(0)
+      expect(formatDate(result)).toBe('2025-10-15')
+    })
+  })
+
+  describe('getDaysFromNow', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2025, 9, 15)) // Oct 15, 2025
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('should calculate future dates correctly', () => {
+      const result = getDaysFromNow(5)
+      expect(formatDate(result)).toBe('2025-10-20')
+    })
+
+    it('should handle month boundaries', () => {
+      const result = getDaysFromNow(20)
+      expect(formatDate(result)).toBe('2025-11-04')
+    })
+
+    it('should return today for 0 days from now', () => {
+      const result = getDaysFromNow(0)
+      expect(formatDate(result)).toBe('2025-10-15')
+    })
+  })
+
+  describe('getDateRange', () => {
+    it('should return array of dates in range', () => {
+      const from = new Date(2025, 9, 1) // Oct 1
+      const to = new Date(2025, 9, 5) // Oct 5
+
+      const result = getDateRange(from, to)
+
+      expect(result.length).toBe(5)
+      expect(formatDate(result[0])).toBe('2025-10-01')
+      expect(formatDate(result[4])).toBe('2025-10-05')
+    })
+
+    it('should include start and end dates', () => {
+      const from = new Date(2025, 9, 10)
+      const to = new Date(2025, 9, 12)
+
+      const result = getDateRange(from, to)
+
+      expect(formatDate(result[0])).toBe('2025-10-10')
+      expect(formatDate(result[result.length - 1])).toBe('2025-10-12')
+    })
+
+    it('should return single date if from equals to', () => {
+      const date = new Date(2025, 9, 15)
+      const result = getDateRange(date, date)
+
+      expect(result.length).toBe(1)
+      expect(formatDate(result[0])).toBe('2025-10-15')
+    })
+
+    it('should handle month boundaries', () => {
+      const from = new Date(2025, 9, 30) // Oct 30
+      const to = new Date(2025, 10, 2) // Nov 2
+
+      const result = getDateRange(from, to)
+
+      expect(result.length).toBe(4)
+      expect(formatDate(result[0])).toBe('2025-10-30')
+      expect(formatDate(result[3])).toBe('2025-11-02')
+    })
+
+    it('should return empty array if from is after to', () => {
+      const from = new Date(2025, 9, 15)
+      const to = new Date(2025, 9, 10)
+
+      const result = getDateRange(from, to)
+
+      expect(result.length).toBe(0)
+    })
+  })
+
+  describe('isToday', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2025, 9, 15)) // Oct 15, 2025
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('should return true for today', () => {
+      const today = new Date(2025, 9, 15)
+      expect(isToday(today)).toBe(true)
+    })
+
+    it('should return false for yesterday', () => {
+      const yesterday = new Date(2025, 9, 14)
+      expect(isToday(yesterday)).toBe(false)
+    })
+
+    it('should return false for tomorrow', () => {
+      const tomorrow = new Date(2025, 9, 16)
+      expect(isToday(tomorrow)).toBe(false)
+    })
+
+    it('should ignore time component', () => {
+      const todayLate = new Date(2025, 9, 15, 23, 59, 59)
+      expect(isToday(todayLate)).toBe(true)
+    })
+  })
+
+  describe('isWithinLastDays', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date(2025, 9, 15, 12, 0, 0)) // Oct 15, 2025 at noon
+    })
+
+    afterEach(() => {
+      vi.useRealTimers()
+    })
+
+    it('should return true for dates within range', () => {
+      const recent = new Date(2025, 9, 12) // 3 days ago
+      expect(isWithinLastDays(recent, 7)).toBe(true)
+    })
+
+    it('should return false for dates outside range', () => {
+      const old = new Date(2025, 9, 1) // 14 days ago
+      expect(isWithinLastDays(old, 7)).toBe(false)
+    })
+
+    it('should include today', () => {
+      const today = new Date(2025, 9, 15)
+      expect(isWithinLastDays(today, 7)).toBe(true)
+    })
+
+    it('should include boundary date', () => {
+      const boundary = new Date(2025, 9, 8) // exactly 7 days ago
+      expect(isWithinLastDays(boundary, 7)).toBe(true)
+    })
+  })
+
+  describe('formatDuration', () => {
+    it('should format seconds', () => {
+      expect(formatDuration(5000)).toBe('5s')
+      expect(formatDuration(45000)).toBe('45s')
+    })
+
+    it('should format minutes', () => {
+      expect(formatDuration(60000)).toBe('1m')
+      expect(formatDuration(120000)).toBe('2m')
+      expect(formatDuration(90000)).toBe('1m') // 1.5 min rounds down
+    })
+
+    it('should format hours and minutes', () => {
+      expect(formatDuration(3600000)).toBe('1h 0m')
+      expect(formatDuration(5400000)).toBe('1h 30m')
+      expect(formatDuration(7200000)).toBe('2h 0m')
+    })
+
+    it('should format days and hours', () => {
+      expect(formatDuration(86400000)).toBe('1d 0h')
+      expect(formatDuration(90000000)).toBe('1d 1h')
+      expect(formatDuration(172800000)).toBe('2d 0h')
+    })
+
+    it('should handle zero', () => {
+      expect(formatDuration(0)).toBe('0s')
+    })
+  })
+
+  describe('calculateDuration', () => {
+    it('should calculate duration between two dates', () => {
+      const start = new Date('2025-10-15T10:00:00.000Z')
+      const end = new Date('2025-10-15T12:30:00.000Z')
+
+      expect(calculateDuration(start, end)).toBe('2h 30m')
+    })
+
+    it('should default to now if no end date', () => {
+      vi.useFakeTimers()
+      vi.setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+
+      const start = new Date('2025-10-15T10:00:00.000Z')
+      expect(calculateDuration(start)).toBe('2h 0m')
+
+      vi.useRealTimers()
+    })
+
+    it('should handle short durations', () => {
+      const start = new Date('2025-10-15T10:00:00.000Z')
+      const end = new Date('2025-10-15T10:00:30.000Z')
+
+      expect(calculateDuration(start, end)).toBe('30s')
+    })
+  })
+
+  describe('getStartOfDay', () => {
+    it('should set time to 00:00:00.000', () => {
+      const date = new Date(2025, 9, 15, 14, 30, 45, 500)
+      const result = getStartOfDay(date)
+
+      expect(result.getHours()).toBe(0)
+      expect(result.getMinutes()).toBe(0)
+      expect(result.getSeconds()).toBe(0)
+      expect(result.getMilliseconds()).toBe(0)
+    })
+
+    it('should preserve the date', () => {
+      const date = new Date(2025, 9, 15, 23, 59, 59)
+      const result = getStartOfDay(date)
+
+      expect(result.getFullYear()).toBe(2025)
+      expect(result.getMonth()).toBe(9)
+      expect(result.getDate()).toBe(15)
+    })
+
+    it('should not mutate original date', () => {
+      const original = new Date(2025, 9, 15, 14, 30)
+      getStartOfDay(original)
+
+      expect(original.getHours()).toBe(14)
+      expect(original.getMinutes()).toBe(30)
+    })
+  })
+
+  describe('getEndOfDay', () => {
+    it('should set time to 23:59:59.999', () => {
+      const date = new Date(2025, 9, 15, 10, 0, 0, 0)
+      const result = getEndOfDay(date)
+
+      expect(result.getHours()).toBe(23)
+      expect(result.getMinutes()).toBe(59)
+      expect(result.getSeconds()).toBe(59)
+      expect(result.getMilliseconds()).toBe(999)
+    })
+
+    it('should preserve the date', () => {
+      const date = new Date(2025, 9, 15, 0, 0, 0)
+      const result = getEndOfDay(date)
+
+      expect(result.getFullYear()).toBe(2025)
+      expect(result.getMonth()).toBe(9)
+      expect(result.getDate()).toBe(15)
+    })
+
+    it('should not mutate original date', () => {
+      const original = new Date(2025, 9, 15, 10, 30)
+      getEndOfDay(original)
+
+      expect(original.getHours()).toBe(10)
+      expect(original.getMinutes()).toBe(30)
+    })
+  })
+})

package/core/agentic/agent-router.js

@@ -1,11 +1,8 @@
 /**
- * Agent Router - Orchestration Only
- *
- * AGENTIC: All decisions made by Claude via templates/agent-assignment.md
- * JS only orchestrates: load agents, build context, delegate to Claude
- *
- * NO scoring logic, NO matching algorithms, NO hardcoded mappings
+ * Agent Router
+ * Orchestrates agent loading and context building for Claude delegation.
  *
+ * @module agentic/agent-router
  * @version 2.0.0
  */
 
@@ -14,15 +11,22 @@ const path = require('path')
 const configManager = require('../infrastructure/config-manager')
 const pathManager = require('../infrastructure/path-manager')
 
+/**
+ * Routes tasks to specialized agents based on Claude's decisions.
+ * Handles agent loading, context building, and usage logging.
+ */
 class AgentRouter {
   constructor() {
+    /** @type {string|null} */
     this.projectId = null
+    /** @type {string|null} */
     this.agentsPath = null
   }
 
   /**
-   * Initialize with project context
-   * ORCHESTRATION: Just sets up paths
+   * Initialize router with project context
+   *
+   * @param {string} projectPath - Path to the project
    */
   async initialize(projectPath) {
     this.projectId = await configManager.getProjectId(projectPath)
@@ -31,7 +35,8 @@ class AgentRouter {
 
   /**
    * Load all available agents from project
-   * ORCHESTRATION: File I/O only, no logic
+   *
+   * @returns {Promise<Array<{name: string, content: string}>>} Available agents
    */
   async loadAvailableAgents() {
     try {
@@ -56,8 +61,9 @@ class AgentRouter {
   }
 
   /**
-   * Get agent names list
-   * ORCHESTRATION: Simple extraction
+   * Get list of available agent names
+   *
+   * @returns {Promise<string[]>} Agent names
    */
   async getAgentNames() {
     const agents = await this.loadAvailableAgents()
@@ -65,8 +71,10 @@ class AgentRouter {
   }
 
   /**
-   * Load specific agent by name
-   * ORCHESTRATION: File I/O only
+   * Load a specific agent by name
+   *
+   * @param {string} name - Agent name (without .md extension)
+   * @returns {Promise<{name: string, content: string}|null>} Agent or null
    */
   async loadAgent(name) {
     try {
@@ -79,10 +87,11 @@ class AgentRouter {
   }
 
   /**
-   * Build context for agent assignment
-   * ORCHESTRATION: Data gathering only
+   * Build context for Claude to decide agent assignment
    *
-   * Claude uses this context + templates/agent-assignment.md to decide
+   * @param {string|Object} task - Task description or object
+   * @param {string} projectPath - Project path
+   * @returns {Promise<Object>} Assignment context for Claude
    */
   async buildAssignmentContext(task, projectPath) {
     const agents = await this.getAgentNames()
@@ -98,8 +107,11 @@ class AgentRouter {
   }
 
   /**
-   * Log agent usage
-   * ORCHESTRATION: File I/O only
+   * Log agent usage to JSONL file
+   *
+   * @param {string|Object} task - Task description
+   * @param {string|Object} agent - Agent used
+   * @param {string} projectPath - Project path (unused, kept for API compat)
    */
   async logUsage(task, agent, projectPath) {
     try {

package/core/agentic/command-executor.js

@@ -1,21 +1,9 @@
 /**
  * Command Executor
- * 100% AGENTIC - Claude decides agent assignment via Task tool
+ * Orchestrates command execution with agentic delegation.
  *
- * NO if/else logic for agent selection here.
- * Claude reads templates/agentic/agent-routing.md and delegates via Task tool.
- *
- * JS only:
- * - Loads templates
- * - Builds context
- * - Returns prompt for Claude
- *
- * Claude:
- * - Reads agent-routing.md
- * - Decides best agent for task
- * - Delegates via Task(subagent_type='general-purpose', prompt='Read: path/to/agent.md...')
- *
- * Source: Claude Code, Devin, Augment Code patterns
+ * @module agentic/command-executor
+ * @version 3.4
  */
 
 const fs = require('fs')
@@ -45,14 +33,17 @@ const RUNNING_FILE = path.join(os.homedir(), '.prjct-cli', '.running')
 // - code-intelligence → Claude Code has native LSP integration
 // - browser-preview → Claude Code can use Bash directly
 
+/**
+ * Orchestrates prjct command execution.
+ * Handles template loading, context building, validation, and agentic delegation.
+ */
 class CommandExecutor {
-  constructor() {
-    // 100% AGENTIC: No agent router here
-    // Claude decides agent assignment via templates and Task tool
-  }
+  constructor() {}
 
   /**
    * Signal that a command is running (for status line)
+   *
+   * @param {string} commandName - Name of the running command
    */
   signalStart(commandName) {
     try {
@@ -80,7 +71,12 @@ class CommandExecutor {
   }
 
   /**
-   * Execute command with MANDATORY agent assignment
+   * Execute a prjct command with full agentic delegation
+   *
+   * @param {string} commandName - Command to execute (e.g., 'now', 'ship')
+   * @param {Object} params - Command parameters
+   * @param {string} projectPath - Path to the project
+   * @returns {Promise<Object>} Execution result with prompt, context, helpers
    */
   async execute(commandName, params, projectPath) {
     // Signal start for status line
@@ -378,12 +374,12 @@ class CommandExecutor {
   }
 
   /**
-   * Simple execution for direct tool access
-   * Used by legacy commands during migration
+   * Simple execution for direct tool access (legacy migration helper)
+   *
    * @param {string} commandName - Command name
-   * @param {Function} executionFn - Function that uses tools
+   * @param {Function} executionFn - Function receiving (tools, context)
    * @param {string} projectPath - Project path
-   * @returns {Promise<Object>}
+   * @returns {Promise<Object>} Result with success flag
    */
   async executeSimple(commandName, executionFn, projectPath) {
     try {

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