prjct-cli 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [1.3.0] - 2026-02-06
+
+### Features
+
+- session state tracking for multi-command workflows (PRJ-109) (#114)
+
+
+## [1.3.0] - 2026-02-06
+
+### Features
+
+- session state tracking for multi-command workflows (PRJ-109)
+
+### Implementation Details
+
+New `SessionTracker` service (`core/services/session-tracker.ts`) that manages lightweight session lifecycle for tracking command sequences and file access across CLI invocations.
+
+Key behaviors:
+- **Auto-create**: Sessions start automatically on first CLI command
+- **Auto-resume**: Subsequent commands within 30 min extend the existing session
+- **Auto-expire**: Sessions expire after 30 minutes of idle time, cleaned up on next startup
+- **Command tracking**: Records command name, timestamp, and duration (up to 50 commands)
+- **File tracking**: Records file reads/writes with timestamps (up to 200 records)
+
+Integration points:
+- `core/index.ts` — touch/track in main CLI dispatch (all standard commands)
+- `bin/prjct.ts` — `trackSession()` helper for context/hooks/doctor commands
+- `core/commands/analysis.ts` — session info in `prjct status` output (JSON + human-readable)
+- `core/services/staleness-checker.ts` — `getSessionInfo()` and `formatSessionInfo()` with box-drawing display
+
+Storage: `~/.prjct-cli/projects/{projectId}/storage/session.json`
+
+### Learnings
+
+- Non-critical tracking should always be wrapped in try/catch with silent fail — session tracking must never break CLI commands
+- Touch-on-every-command pattern is simple but effective for session detection — no explicit start/stop needed
+- Box-drawing characters (`┌─┐│└─┘`) provide clean structured output without external dependencies
+
+### Test Plan
+
+#### For QA
+1. Run `prjct status` — verify "Session: ▶ Active" with duration, commands, idle timer
+2. Wait 30+ minutes, run `prjct status` — verify "Session: ○ No active session"
+3. Run multiple commands in sequence — verify command count increments
+4. Run `prjct status --json` — verify session object in JSON output
+5. Run `bun run build && bun run typecheck` — zero errors
+
+#### For Users
+**What changed:** CLI now tracks session state across commands for workflow visibility
+**How to use:** Run `prjct status` to see active session info
+**Breaking changes:** None
+
 ## [1.2.2] - 2026-02-06
 
 ### Performance

package/bin/prjct.ts

@@ -64,6 +64,26 @@ if (isQuietMode) {
 
 // Colors for output (chalk respects NO_COLOR env)
 
+// Session tracking for commands that bypass core/index.ts
+async function trackSession(command: string): Promise<() => void> {
+  const start = Date.now()
+  try {
+    const projectId = await configManager.getProjectId(process.cwd())
+    if (projectId) {
+      const { sessionTracker } = await import('../core/services/session-tracker')
+      await sessionTracker.expireIfStale(projectId)
+      await sessionTracker.touch(projectId)
+      return () => {
+        const durationMs = Date.now() - start
+        sessionTracker.trackCommand(projectId, command, durationMs).catch(() => {})
+      }
+    }
+  } catch {
+    // Non-critical
+  }
+  return () => {}
+}
+
 if (args[0] === 'start' || args[0] === 'setup') {
   // Interactive setup with beautiful UI
   const { runStart } = await import('../core/cli/start')
@@ -99,22 +119,28 @@ if (args[0] === 'start' || args[0] === 'setup') {
     console.error('No prjct project found. Run "prjct init" first.')
     process.exitCode = 1
   } else {
+    const done = await trackSession('context')
     const { runContextTool } = await import('../core/context-tools')
     const result = await runContextTool(args.slice(1), projectId, projectPath)
     console.log(JSON.stringify(result, null, 2))
     process.exitCode = result.tool === 'error' ? 1 : 0
+    done()
   }
 } else if (args[0] === 'hooks') {
   // Git hooks management
+  const done = await trackSession('hooks')
   const { hooksService } = await import('../core/services/hooks-service')
   const subcommand = args[1] || 'status'
   const exitCode = await hooksService.run(process.cwd(), subcommand)
   process.exitCode = exitCode
+  done()
 } else if (args[0] === 'doctor') {
   // Health check command
+  const done = await trackSession('doctor')
   const { doctorService } = await import('../core/services/doctor-service')
   const exitCode = await doctorService.run(process.cwd())
   process.exitCode = exitCode
+  done()
 } else if (args[0] === 'uninstall') {
   // Complete system removal
   const { uninstall } = await import('../core/commands/uninstall')

package/core/commands/analysis.ts

@@ -761,23 +761,29 @@ export class AnalysisCommands extends PrjctCommandsBase {
       const checker = createStalenessChecker(projectPath)
       const status = await checker.check(projectId)
 
+      // Get session info
+      const sessionInfo = await checker.getSessionInfo(projectId)
+
       // JSON output mode
       if (options.json) {
         console.log(
           JSON.stringify({
             success: true,
             ...status,
+            session: sessionInfo,
           })
         )
-        return { success: true, data: status }
+        return { success: true, data: { ...status, session: sessionInfo } }
       }
 
       // Human-readable output
       console.log('')
       console.log(checker.formatStatus(status))
       console.log('')
+      console.log(checker.formatSessionInfo(sessionInfo))
+      console.log('')
 
-      return { success: true, data: status }
+      return { success: true, data: { ...status, session: sessionInfo } }
     } catch (error) {
       const errMsg = (error as Error).message
       if (options.json) {

package/core/index.ts

@@ -13,6 +13,8 @@ import path from 'node:path'
 import chalk from 'chalk'
 import type { CommandMeta } from './commands/registry'
 import { detectAllProviders, detectAntigravity } from './infrastructure/ai-provider'
+import configManager from './infrastructure/config-manager'
+import { sessionTracker } from './services/session-tracker'
 import out from './utils/output'
 
 interface ParsedCommandArgs {
@@ -79,6 +81,19 @@ async function main(): Promise<void> {
     // 4. Parse arguments
     const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs)
 
+    // 4.5. Session tracking — touch/create session before command execution
+    let projectId: string | null = null
+    const commandStartTime = Date.now()
+    try {
+      projectId = await configManager.getProjectId(process.cwd())
+      if (projectId) {
+        await sessionTracker.expireIfStale(projectId)
+        await sessionTracker.touch(projectId)
+      }
+    } catch {
+      // Session tracking is non-critical — silent fail
+    }
+
     // 5. Instantiate commands handler
     const commands = new PrjctCommands()
 
@@ -149,7 +164,17 @@ async function main(): Promise<void> {
       }
     }
 
-    // 7. Display result
+    // 7. Track command in session
+    if (projectId) {
+      const durationMs = Date.now() - commandStartTime
+      try {
+        await sessionTracker.trackCommand(projectId, commandName, durationMs)
+      } catch {
+        // Non-critical
+      }
+    }
+
+    // 8. Display result
     if (result?.message) {
       console.log(result.message)
     }

package/core/services/session-tracker.ts

@@ -0,0 +1,287 @@
+/**
+ * SessionTracker - Lightweight session state tracking for multi-command workflows
+ *
+ * Tracks command sequences and file access across CLI invocations.
+ * Sessions auto-create on first command and expire after 30 min idle.
+ *
+ * Storage: ~/.prjct-cli/projects/{projectId}/storage/session.json
+ *
+ * @see PRJ-109
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import pathManager from '../infrastructure/path-manager'
+import { isNotFoundError } from '../types/fs'
+import { formatDuration, getTimestamp } from '../utils/date-helper'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface CommandRecord {
+  command: string
+  timestamp: string
+  durationMs: number
+}
+
+export interface FileRecord {
+  path: string
+  operation: 'read' | 'write'
+  timestamp: string
+}
+
+export interface SessionData {
+  id: string
+  projectId: string
+  status: 'active' | 'expired'
+  createdAt: string
+  lastActivity: string
+  commands: CommandRecord[]
+  files: FileRecord[]
+}
+
+export interface SessionFile {
+  current: SessionData | null
+  config: {
+    idleTimeoutMs: number
+  }
+}
+
+export interface SessionInfo {
+  active: boolean
+  id: string | null
+  duration: string | null
+  idleSince: string | null
+  idleMs: number
+  expiresIn: string | null
+  commandCount: number
+  commands: string[]
+  filesRead: number
+  filesWritten: number
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const SESSION_FILENAME = 'session.json'
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes
+const MAX_COMMAND_HISTORY = 50
+const MAX_FILE_HISTORY = 200
+
+// =============================================================================
+// SESSION TRACKER
+// =============================================================================
+
+class SessionTracker {
+  private getPath(projectId: string): string {
+    return pathManager.getStoragePath(projectId, SESSION_FILENAME)
+  }
+
+  /**
+   * Read session file from disk
+   */
+  private async read(projectId: string): Promise<SessionFile> {
+    const filePath = this.getPath(projectId)
+    try {
+      const content = await fs.readFile(filePath, 'utf-8')
+      return JSON.parse(content) as SessionFile
+    } catch (error) {
+      if (isNotFoundError(error) || error instanceof SyntaxError) {
+        return this.getDefault()
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Write session file to disk
+   */
+  private async write(projectId: string, data: SessionFile): Promise<void> {
+    const filePath = this.getPath(projectId)
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8')
+  }
+
+  private getDefault(): SessionFile {
+    return {
+      current: null,
+      config: {
+        idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+      },
+    }
+  }
+
+  /**
+   * Check if a session has expired based on idle timeout
+   */
+  private isExpired(session: SessionData, timeoutMs: number): boolean {
+    const lastActivity = new Date(session.lastActivity).getTime()
+    const now = Date.now()
+    return now - lastActivity > timeoutMs
+  }
+
+  /**
+   * Touch session — create new or resume existing.
+   * Called at the start of every CLI command.
+   * Returns the active session.
+   */
+  async touch(projectId: string): Promise<SessionData> {
+    const file = await this.read(projectId)
+    const now = getTimestamp()
+
+    // If active session exists and not expired, resume it
+    if (file.current && !this.isExpired(file.current, file.config.idleTimeoutMs)) {
+      file.current.lastActivity = now
+      await this.write(projectId, file)
+      return file.current
+    }
+
+    // Create new session (old one expired or doesn't exist)
+    const session: SessionData = {
+      id: crypto.randomUUID(),
+      projectId,
+      status: 'active',
+      createdAt: now,
+      lastActivity: now,
+      commands: [],
+      files: [],
+    }
+
+    file.current = session
+    await this.write(projectId, file)
+    return session
+  }
+
+  /**
+   * Record a command execution in the current session
+   */
+  async trackCommand(projectId: string, command: string, durationMs: number): Promise<void> {
+    const file = await this.read(projectId)
+    if (!file.current) return
+
+    const now = getTimestamp()
+    file.current.lastActivity = now
+    file.current.commands.push({
+      command,
+      timestamp: now,
+      durationMs,
+    })
+
+    // Trim old commands if over limit
+    if (file.current.commands.length > MAX_COMMAND_HISTORY) {
+      file.current.commands = file.current.commands.slice(-MAX_COMMAND_HISTORY)
+    }
+
+    await this.write(projectId, file)
+  }
+
+  /**
+   * Record a file access in the current session
+   */
+  async trackFile(projectId: string, filePath: string, operation: 'read' | 'write'): Promise<void> {
+    const file = await this.read(projectId)
+    if (!file.current) return
+
+    const now = getTimestamp()
+    file.current.lastActivity = now
+    file.current.files.push({
+      path: filePath,
+      operation,
+      timestamp: now,
+    })
+
+    // Trim old file records if over limit
+    if (file.current.files.length > MAX_FILE_HISTORY) {
+      file.current.files = file.current.files.slice(-MAX_FILE_HISTORY)
+    }
+
+    await this.write(projectId, file)
+  }
+
+  /**
+   * Get session info for display (used by `prjct status`)
+   */
+  async getInfo(projectId: string): Promise<SessionInfo> {
+    const file = await this.read(projectId)
+
+    if (!file.current || this.isExpired(file.current, file.config.idleTimeoutMs)) {
+      return {
+        active: false,
+        id: null,
+        duration: null,
+        idleSince: null,
+        idleMs: 0,
+        expiresIn: null,
+        commandCount: 0,
+        commands: [],
+        filesRead: 0,
+        filesWritten: 0,
+      }
+    }
+
+    const session = file.current
+    const now = Date.now()
+    const createdAt = new Date(session.createdAt).getTime()
+    const lastActivity = new Date(session.lastActivity).getTime()
+    const idleMs = now - lastActivity
+    const timeoutMs = file.config.idleTimeoutMs
+    const expiresInMs = Math.max(0, timeoutMs - idleMs)
+
+    const uniqueCommands = session.commands.map((c) => c.command)
+    const filesRead = new Set(
+      session.files.filter((f) => f.operation === 'read').map((f) => f.path)
+    ).size
+    const filesWritten = new Set(
+      session.files.filter((f) => f.operation === 'write').map((f) => f.path)
+    ).size
+
+    return {
+      active: true,
+      id: session.id,
+      duration: formatDuration(now - createdAt),
+      idleSince: session.lastActivity,
+      idleMs,
+      expiresIn: formatDuration(expiresInMs),
+      commandCount: session.commands.length,
+      commands: uniqueCommands,
+      filesRead,
+      filesWritten,
+    }
+  }
+
+  /**
+   * Expire the current session (cleanup)
+   */
+  async expire(projectId: string): Promise<void> {
+    const file = await this.read(projectId)
+    if (file.current) {
+      file.current.status = 'expired'
+      file.current = null
+      await this.write(projectId, file)
+    }
+  }
+
+  /**
+   * Check and expire stale session if needed.
+   * Called on startup to clean up leftover sessions.
+   * Returns true if a session was expired.
+   */
+  async expireIfStale(projectId: string): Promise<boolean> {
+    const file = await this.read(projectId)
+    if (file.current && this.isExpired(file.current, file.config.idleTimeoutMs)) {
+      file.current = null
+      await this.write(projectId, file)
+      return true
+    }
+    return false
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const sessionTracker = new SessionTracker()
+export default sessionTracker

package/core/services/staleness-checker.ts

@@ -12,6 +12,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import pathManager from '../infrastructure/path-manager'
+import { type SessionInfo, sessionTracker } from './session-tracker'
 
 const execAsync = promisify(exec)
 
@@ -248,6 +249,57 @@ export class StalenessChecker {
     return lines.join('\n')
   }
 
+  /**
+   * Get session info for the project
+   */
+  async getSessionInfo(projectId: string): Promise<SessionInfo> {
+    return sessionTracker.getInfo(projectId)
+  }
+
+  /**
+   * Format session info for display
+   */
+  formatSessionInfo(info: SessionInfo): string {
+    const lines: string[] = []
+
+    if (!info.active) {
+      lines.push('Session: ○ No active session')
+      return lines.join('\n')
+    }
+
+    lines.push(`Session: ▶ Active (${info.duration})`)
+
+    const details: string[] = []
+    if (info.commandCount > 0) {
+      // Show unique command sequence
+      const seen = new Set<string>()
+      const unique: string[] = []
+      for (const cmd of info.commands) {
+        if (!seen.has(cmd)) {
+          seen.add(cmd)
+          unique.push(cmd)
+        }
+      }
+      details.push(`Commands:       ${unique.join(' → ')} (${info.commandCount} total)`)
+    }
+    if (info.filesRead > 0 || info.filesWritten > 0) {
+      details.push(`Files:          ${info.filesRead} read, ${info.filesWritten} written`)
+    }
+    details.push(`Idle:           ${info.expiresIn} until timeout`)
+
+    if (details.length > 0) {
+      const maxLen = Math.max(...details.map((l) => l.length))
+      const border = '─'.repeat(maxLen + 2)
+      lines.push(`┌${border}┐`)
+      for (const detail of details) {
+        lines.push(`│ ${detail.padEnd(maxLen)} │`)
+      }
+      lines.push(`└${border}┘`)
+    }
+
+    return lines.join('\n')
+  }
+
   /**
    * Get a short warning message if stale (for other commands)
    */