prjct-cli 0.60.2 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.61.0] - 2026-02-05
+
+### Features
+
+- add .prjct-state.md local state file for persistence (PRJ-112) (#102)
+
+
+## [0.61.0] - 2026-02-05
+
+### Features
+
+- **Local state file (PRJ-112)**: New `.prjct-state.md` file generated in project root for local persistence
+
+### Implementation Details
+
+Created `LocalStateGenerator` service that generates a markdown file showing current task state. Integrated via write-through pattern - `StateStorage.write()` now also generates the local state file. Also hooks into `sync-service.ts` for state.json updates during sync.
+
+### Learnings
+
+- Write-through pattern: JSON storage triggers MD generation automatically
+- State can be written from multiple entry points (storage class + sync service) - need hooks in both places
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on any project - verify `.prjct-state.md` is generated in project root
+2. Start a task with `p. task "test"` - verify `.prjct-state.md` updates with task info
+3. Check that subtasks, progress, and status are displayed correctly
+4. Verify the file has "DO NOT EDIT" header comment
+
+#### For Users
+- New `.prjct-state.md` file in project root shows current task state
+- Automatic - file updates whenever prjct state changes
+- No breaking changes
+
+
 ## [0.60.2] - 2026-02-05
 
 ### Performance

package/core/services/local-state-generator.ts

@@ -0,0 +1,158 @@
+/**
+ * Local State Generator
+ *
+ * Generates .prjct-state.md in the project root for local persistence.
+ * This provides a quick reference to current task state without needing
+ * to access global storage.
+ *
+ * @see PRJ-112
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { StateJson } from '../schemas/state'
+import { isNotFoundError } from '../types/fs'
+
+const LOCAL_STATE_FILENAME = '.prjct-state.md'
+
+// Extended runtime types (state.json has fields not in strict schema)
+interface RuntimeTask {
+  description: string
+  startedAt: string
+  linearId?: string
+  branch?: string
+  status?: string
+  subtasks?: Array<{
+    description: string
+    status: string
+  }>
+  currentSubtaskIndex?: number
+}
+
+interface RuntimePreviousTask {
+  description: string
+  status: string
+  prUrl?: string
+}
+
+class LocalStateGenerator {
+  /**
+   * Generate .prjct-state.md in the project root
+   */
+  async generate(projectPath: string, state: StateJson): Promise<void> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    const content = this.toMarkdown(state)
+    await fs.writeFile(filePath, content, 'utf-8')
+  }
+
+  /**
+   * Remove local state file
+   */
+  async remove(projectPath: string): Promise<void> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    try {
+      await fs.unlink(filePath)
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error
+    }
+  }
+
+  /**
+   * Check if local state file exists
+   */
+  async exists(projectPath: string): Promise<boolean> {
+    const filePath = path.join(projectPath, LOCAL_STATE_FILENAME)
+    try {
+      await fs.access(filePath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Convert state to markdown format
+   * Note: Uses runtime types since state.json has fields not in strict Zod schema
+   */
+  private toMarkdown(state: StateJson): string {
+    const lines: string[] = [
+      '<!-- Auto-generated by prjct - DO NOT EDIT -->',
+      '<!-- This file provides local state persistence for AI tools -->',
+      '',
+      '# prjct State',
+      '',
+    ]
+
+    if (state.currentTask) {
+      // Cast to runtime type (state.json has additional fields)
+      const task = state.currentTask as unknown as RuntimeTask
+      lines.push('## Current Task')
+      lines.push('')
+      lines.push(`**${task.description}**`)
+      lines.push('')
+      lines.push(`- Started: ${task.startedAt}`)
+      if (task.linearId) {
+        lines.push(`- Linear: ${task.linearId}`)
+      }
+      if (task.branch) {
+        lines.push(`- Branch: ${task.branch}`)
+      }
+      lines.push(`- Status: ${task.status || 'active'}`)
+      lines.push('')
+
+      // Subtasks
+      if (task.subtasks && task.subtasks.length > 0) {
+        lines.push('### Subtasks')
+        lines.push('')
+
+        task.subtasks.forEach((subtask, index) => {
+          const statusIcon =
+            subtask.status === 'completed' ? '✅' : subtask.status === 'in_progress' ? '▶️' : '⏳'
+          const isActive = index === task.currentSubtaskIndex ? ' ← **Active**' : ''
+          lines.push(`${index + 1}. ${statusIcon} ${subtask.description}${isActive}`)
+        })
+
+        lines.push('')
+
+        // Progress
+        const completed = task.subtasks.filter((s) => s.status === 'completed').length
+        const total = task.subtasks.length
+        const percentage = Math.round((completed / total) * 100)
+        lines.push(`**Progress**: ${completed}/${total} (${percentage}%)`)
+        lines.push('')
+      }
+    } else {
+      lines.push('*No active task*')
+      lines.push('')
+      lines.push('Start a task with `p. task "description"`')
+      lines.push('')
+    }
+
+    // Previous task info
+    if (state.previousTask) {
+      // Cast to runtime type
+      const prevTask = state.previousTask as unknown as RuntimePreviousTask
+      lines.push('---')
+      lines.push('')
+      lines.push('## Previous Task')
+      lines.push('')
+      lines.push(`**${prevTask.description}**`)
+      lines.push('')
+      lines.push(`- Status: ${prevTask.status}`)
+      if (prevTask.prUrl) {
+        lines.push(`- PR: ${prevTask.prUrl}`)
+      }
+      lines.push('')
+    }
+
+    // Footer
+    lines.push('---')
+    lines.push(`*Last updated: ${state.lastUpdated || new Date().toISOString()}*`)
+    lines.push('')
+
+    return lines.join('\n')
+  }
+}
+
+export const localStateGenerator = new LocalStateGenerator()
+export default localStateGenerator

package/core/services/sync-service.ts

@@ -33,6 +33,7 @@ import { metricsStorage } from '../storage/metrics-storage'
 import dateHelper from '../utils/date-helper'
 import { ContextFileGenerator } from './context-generator'
 import type { SyncDiff } from './diff-generator'
+import { localStateGenerator } from './local-state-generator'
 import { type StackDetection, StackDetector } from './stack-detector'
 
 const execAsync = promisify(exec)
@@ -826,6 +827,16 @@ You are the ${name} expert for this project. Apply best practices for the detect
     }
 
     await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf-8')
+
+    // Also generate local .prjct-state.md (PRJ-112)
+    try {
+      await localStateGenerator.generate(
+        this.projectPath,
+        state as import('../schemas/state').StateJson
+      )
+    } catch {
+      // Silently fail - local state is optional
+    }
   }
 
   // ==========================================================================

package/core/storage/state-storage.ts

@@ -3,6 +3,9 @@
  *
  * Manages current task state via storage/state.json
  * Generates context/now.md for Claude
+ *
+ * Note: Local .prjct-state.md is generated by sync-service which has access
+ * to projectPath. This class only has projectId.
  */
 
 import { generateUUID } from '../schemas'