prjct-cli 0.12.2 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.13.0] - 2025-12-10
+
+### Deep Sync + Cleanup migrations
+
+Major update: Deep git analysis, removed external API dependencies, MD-first architecture.
+
+- **Deep Sync (`/p:sync`)**
+  - Full git analysis: `git status`, `git log`, `git diff`, `git branch`
+  - Auto-detect completed tasks from commit messages
+  - Sync ALL MD files: now.md, next.md, shipped.md, ideas.md, roadmap.md
+  - Update project.json with real stats (fileCount, commitCount, version)
+  - Update CLAUDE.md Quick Reference table with current data
+  - Infer current task from uncommitted changes
+
+- **Sync Button in Project Detail**
+  - Prominent primary-colored button in sidebar
+  - Always visible for easy access
+  - Mobile support in command grid
+
+- **Removed External Dependencies**
+  - Removed OpenAI/OpenRouter API key management
+  - Removed migration service (no longer needed)
+  - Removed settings API route
+  - Cleaned up web package dependencies
+
+- **Ship Workflow Improvements**
+  - Language agnostic versioning (package.json, Cargo.toml, pyproject.toml, VERSION)
+  - CHANGELOG.md generation is now MANDATORY
+  - Auto-runs deep sync after shipping
+  - prjct signature in commits
+
+- **Files Removed**:
+  - `packages/web/app/api/settings/route.ts`
+  - `packages/web/app/api/migrate/route.ts`
+  - `packages/web/lib/services/migration.server.ts`
+  - `packages/web/components/MigrationGate/`
+
+- **Files Modified**:
+  - `templates/commands/sync.md` - Complete rewrite for deep analysis
+  - `templates/commands/ship.md` - Language agnostic, mandatory changelog
+  - `packages/web/app/settings/page.tsx` - Removed API keys section
+  - `packages/web/app/project/[id]/page.tsx` - Added Sync button
+
 ## [0.12.0] - 2025-12-10
 
 ### Added - JSON-First Architecture (Zero Data Loss)

package/CLAUDE.md

@@ -28,19 +28,31 @@ p. done       → Mark complete, next task
 p. ship       → Lint/test/commit/push
 ```
 
-## Architecture
+## Architecture: MD-First
+
+**MD files are the source of truth.** No JSON data files - all state is stored directly in Markdown.
 
 ### Global Storage
 ```
 ~/.prjct-cli/projects/{id}/
-├── core/           # now.md, next.md, context.md
-├── progress/       # shipped.md, metrics.md, sessions/
-├── planning/       # ideas.md, roadmap.md, sessions/
+├── core/           # now.md (current task), next.md (queue)
+├── progress/       # shipped.md, sessions/
+├── planning/       # ideas.md, roadmap.md
 ├── analysis/       # repo-summary.md
-├── memory/         # context.jsonl, sessions/
-└── agents/         # Generated specialists
+├── memory/         # context.jsonl (append-only logs)
+├── agents/         # Generated specialists
+└── project.json    # Metadata only (name, repoPath, techStack)
 ```
 
+### Key Files (Source of Truth)
+| File | Purpose |
+|------|---------|
+| `core/now.md` | Current task state |
+| `core/next.md` | Task queue |
+| `planning/ideas.md` | Ideas backlog |
+| `planning/roadmap.md` | Feature roadmap |
+| `progress/shipped.md` | Shipped features |
+
 ### Local Config
 ```
 .prjct/prjct.config.json  # Links to global data via projectId

package/core/data/index.ts

@@ -1,13 +1,21 @@
 /**
  * Data Module
  *
- * JSON file managers for all project data types.
+ * MD-First Architecture: MD files are the source of truth.
+ * JSON managers are deprecated in favor of MD managers.
  */
 
-// Base
+// Base (legacy JSON)
 export { BaseManager, ArrayManager } from './base-manager'
 
-// Managers
+// MD-First Base
+export { MdBaseManager, MdArrayManager } from './md-base-manager'
+
+// MD-First Managers (NEW - use these!)
+export { mdStateManager } from './md-state-manager'
+export { mdQueueManager } from './md-queue-manager'
+
+// Legacy JSON Managers (deprecated - for backwards compatibility only)
 export { stateManager, default as stateManagerDefault } from './state-manager'
 export { projectManager, default as projectManagerDefault } from './project-manager'
 export { agentsManager, default as agentsManagerDefault } from './agents-manager'
@@ -17,7 +25,13 @@ export { shippedManager, default as shippedManagerDefault } from './shipped-mana
 export { analysisManager, default as analysisManagerDefault } from './analysis-manager'
 export { outcomesManager, default as outcomesManagerDefault } from './outcomes-manager'
 
-// Convenience object with all managers
+// MD-First managers (preferred)
+export const mdManagers = {
+  state: require('./md-state-manager').mdStateManager,
+  queue: require('./md-queue-manager').mdQueueManager
+}
+
+// Legacy JSON managers (deprecated)
 export const dataManagers = {
   state: require('./state-manager').stateManager,
   project: require('./project-manager').projectManager,
@@ -29,4 +43,4 @@ export const dataManagers = {
   outcomes: require('./outcomes-manager').outcomesManager
 }
 
-export default dataManagers
+export default mdManagers

package/core/data/md-base-manager.ts

@@ -0,0 +1,203 @@
+/**
+ * MD Base Manager
+ *
+ * Abstract base class for MD file managers.
+ * MD-First Architecture: MD is the source of truth.
+ *
+ * Each concrete manager must implement:
+ * - parse(content: string): T - Convert MD to schema
+ * - serialize(data: T): string - Convert schema to MD
+ * - getDefault(projectId: string): T - Default value when file doesn't exist
+ */
+
+import path from 'path'
+import fs from 'fs/promises'
+import * as fileHelper from '../utils/file-helper'
+import pathManager from '../infrastructure/path-manager'
+
+export abstract class MdBaseManager<T> {
+  protected filename: string
+  protected cache: Map<string, T> = new Map()
+  protected cacheTimeout = 5000 // 5 seconds
+  protected lastRead: Map<string, number> = new Map()
+
+  constructor(filename: string) {
+    this.filename = filename
+  }
+
+  /**
+   * Get file path for a project.
+   */
+  protected getFilePath(projectId: string): string {
+    const globalPath = pathManager.getGlobalProjectPath(projectId)
+    return path.join(globalPath, this.filename)
+  }
+
+  /**
+   * Get default value for this data type.
+   */
+  protected abstract getDefault(projectId: string): T
+
+  /**
+   * Parse MD content to schema.
+   */
+  protected abstract parse(content: string): T
+
+  /**
+   * Serialize schema to MD content.
+   */
+  protected abstract serialize(data: T): string
+
+  /**
+   * Read data from MD file.
+   */
+  async read(projectId: string): Promise<T> {
+    const now = Date.now()
+    const lastReadTime = this.lastRead.get(projectId) || 0
+
+    // Return cached if fresh
+    if (now - lastReadTime < this.cacheTimeout && this.cache.has(projectId)) {
+      return this.cache.get(projectId)!
+    }
+
+    const filePath = this.getFilePath(projectId)
+    const content = await fileHelper.readFile(filePath, '')
+
+    const data = content.trim() ? this.parse(content) : this.getDefault(projectId)
+
+    // Update cache
+    this.cache.set(projectId, data)
+    this.lastRead.set(projectId, now)
+
+    return data
+  }
+
+  /**
+   * Write data to MD file using atomic write (prevents partial writes).
+   */
+  async write(projectId: string, data: T): Promise<void> {
+    const filePath = this.getFilePath(projectId)
+    const content = this.serialize(data)
+
+    // Ensure directory exists
+    await fileHelper.ensureDir(path.dirname(filePath))
+
+    // Atomic write: write to temp file, then rename
+    const tempPath = `${filePath}.${Date.now()}.tmp`
+    await fs.writeFile(tempPath, content, 'utf-8')
+    await fs.rename(tempPath, filePath)
+
+    // Update cache
+    this.cache.set(projectId, data)
+    this.lastRead.set(projectId, Date.now())
+  }
+
+  /**
+   * Check if file exists.
+   */
+  async exists(projectId: string): Promise<boolean> {
+    const filePath = this.getFilePath(projectId)
+    return fileHelper.fileExists(filePath)
+  }
+
+  /**
+   * Initialize with default data.
+   */
+  async initialize(projectId: string): Promise<T> {
+    const data = this.getDefault(projectId)
+    await this.write(projectId, data)
+    return data
+  }
+
+  /**
+   * Clear cache.
+   */
+  clearCache(projectId?: string): void {
+    if (projectId) {
+      this.cache.delete(projectId)
+      this.lastRead.delete(projectId)
+    } else {
+      this.cache.clear()
+      this.lastRead.clear()
+    }
+  }
+
+  /**
+   * Update data with an updater function (read-modify-write).
+   */
+  async update(projectId: string, updater: (data: T) => T): Promise<T> {
+    const current = await this.read(projectId)
+    const updated = updater(current)
+    await this.write(projectId, updated)
+    return updated
+  }
+
+  /**
+   * Get raw MD content without parsing.
+   */
+  async readRaw(projectId: string): Promise<string> {
+    const filePath = this.getFilePath(projectId)
+    return fileHelper.readFile(filePath, '')
+  }
+
+  /**
+   * Write raw MD content without serialization.
+   */
+  async writeRaw(projectId: string, content: string): Promise<void> {
+    const filePath = this.getFilePath(projectId)
+    await fileHelper.ensureDir(path.dirname(filePath))
+    await fileHelper.atomicWrite(filePath, content)
+    this.clearCache(projectId)
+  }
+}
+
+/**
+ * Base manager for array-based MD files (like shipped, ideas).
+ */
+export abstract class MdArrayManager<T> extends MdBaseManager<T[]> {
+  protected getDefault(): T[] {
+    return []
+  }
+
+  /**
+   * Add item to array.
+   */
+  async add(projectId: string, item: T): Promise<T[]> {
+    return this.update(projectId, (data) => [...data, item])
+  }
+
+  /**
+   * Prepend item to array (add at beginning).
+   */
+  async prepend(projectId: string, item: T): Promise<T[]> {
+    return this.update(projectId, (data) => [item, ...data])
+  }
+
+  /**
+   * Remove item by predicate.
+   */
+  async remove(projectId: string, predicate: (item: T) => boolean): Promise<T[]> {
+    return this.update(projectId, (data) => data.filter((item) => !predicate(item)))
+  }
+
+  /**
+   * Find item by predicate.
+   */
+  async find(projectId: string, predicate: (item: T) => boolean): Promise<T | undefined> {
+    const data = await this.read(projectId)
+    return data.find(predicate)
+  }
+
+  /**
+   * Update item by predicate.
+   */
+  async updateItem(
+    projectId: string,
+    predicate: (item: T) => boolean,
+    updater: (item: T) => T
+  ): Promise<T[]> {
+    return this.update(projectId, (data) =>
+      data.map((item) => (predicate(item) ? updater(item) : item))
+    )
+  }
+}

package/core/data/md-queue-manager.ts

@@ -0,0 +1,179 @@
+/**
+ * MD Queue Manager
+ *
+ * MD-First Architecture: Manages queue via next.md.
+ * Source of truth is the markdown file, not JSON.
+ */
+
+import { MdBaseManager } from './md-base-manager'
+import { parseQueue, serializeQueue } from '../serializers'
+import type { QueueJson, QueueTask, Priority, TaskType, TaskSection } from '../schemas/state'
+
+class MdQueueManager extends MdBaseManager<QueueJson> {
+  constructor() {
+    super('core/next.md')
+  }
+
+  protected getDefault(): QueueJson {
+    return {
+      tasks: [],
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }
+  }
+
+  protected parse(content: string): QueueJson {
+    return parseQueue(content)
+  }
+
+  protected serialize(data: QueueJson): string {
+    return serializeQueue(data)
+  }
+
+  // =========== Queue Operations ===========
+
+  async getTasks(projectId: string): Promise<QueueTask[]> {
+    const queue = await this.read(projectId)
+    return queue.tasks
+  }
+
+  async getActiveTasks(projectId: string): Promise<QueueTask[]> {
+    const queue = await this.read(projectId)
+    return queue.tasks.filter(t => t.section === 'active' && !t.completed)
+  }
+
+  async getBacklog(projectId: string): Promise<QueueTask[]> {
+    const queue = await this.read(projectId)
+    return queue.tasks.filter(t => t.section === 'backlog' && !t.completed)
+  }
+
+  async addTask(
+    projectId: string,
+    task: Omit<QueueTask, 'id' | 'createdAt' | 'completed'>
+  ): Promise<QueueJson> {
+    const newTask: QueueTask = {
+      ...task,
+      id: `task_${Date.now()}`,
+      createdAt: new Date().toISOString(),
+      completed: false
+    }
+
+    return this.update(projectId, (queue) => ({
+      tasks: this.sortTasks([...queue.tasks, newTask]),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  async removeTask(projectId: string, taskId: string): Promise<QueueJson> {
+    return this.update(projectId, (queue) => ({
+      tasks: queue.tasks.filter(t => t.id !== taskId),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  async completeTask(projectId: string, taskId: string): Promise<QueueJson> {
+    return this.update(projectId, (queue) => ({
+      tasks: queue.tasks.map(t =>
+        t.id === taskId
+          ? { ...t, completed: true, completedAt: new Date().toISOString() }
+          : t
+      ),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  async getNextTask(projectId: string): Promise<QueueTask | null> {
+    const queue = await this.read(projectId)
+    return queue.tasks.find(t => t.section === 'active' && !t.completed) || null
+  }
+
+  async moveToSection(
+    projectId: string,
+    taskId: string,
+    section: TaskSection
+  ): Promise<QueueJson> {
+    return this.update(projectId, (queue) => ({
+      tasks: queue.tasks.map(t =>
+        t.id === taskId ? { ...t, section } : t
+      ),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  async setPriority(
+    projectId: string,
+    taskId: string,
+    priority: Priority
+  ): Promise<QueueJson> {
+    return this.update(projectId, (queue) => ({
+      tasks: this.sortTasks(
+        queue.tasks.map(t => t.id === taskId ? { ...t, priority } : t)
+      ),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  /**
+   * Add multiple tasks at once (e.g., from a feature breakdown)
+   */
+  async addTasks(
+    projectId: string,
+    tasks: Array<Omit<QueueTask, 'id' | 'createdAt' | 'completed'>>
+  ): Promise<QueueJson> {
+    const newTasks: QueueTask[] = tasks.map((task, i) => ({
+      ...task,
+      id: `task_${Date.now()}_${i}`,
+      createdAt: new Date().toISOString(),
+      completed: false
+    }))
+
+    return this.update(projectId, (queue) => ({
+      tasks: this.sortTasks([...queue.tasks, ...newTasks]),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  /**
+   * Clear completed tasks
+   */
+  async clearCompleted(projectId: string): Promise<QueueJson> {
+    return this.update(projectId, (queue) => ({
+      tasks: queue.tasks.filter(t => !t.completed),
+      lastUpdated: new Date().toISOString().split('T')[0]
+    }))
+  }
+
+  /**
+   * Sort tasks by priority then by creation date
+   */
+  private sortTasks(tasks: QueueTask[]): QueueTask[] {
+    const priorityOrder: Record<Priority, number> = {
+      critical: 0,
+      high: 1,
+      medium: 2,
+      low: 3
+    }
+
+    return tasks.sort((a, b) => {
+      // First by section (active first)
+      const sectionOrder: Record<TaskSection, number> = {
+        active: 0,
+        previously_active: 1,
+        backlog: 2
+      }
+      if (sectionOrder[a.section] !== sectionOrder[b.section]) {
+        return sectionOrder[a.section] - sectionOrder[b.section]
+      }
+
+      // Then by priority
+      if (priorityOrder[a.priority] !== priorityOrder[b.priority]) {
+        return priorityOrder[a.priority] - priorityOrder[b.priority]
+      }
+
+      // Finally by creation date
+      return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()
+    })
+  }
+}
+
+export const mdQueueManager = new MdQueueManager()
+export default mdQueueManager

package/core/data/md-state-manager.ts

@@ -0,0 +1,133 @@
+/**
+ * MD State Manager
+ *
+ * MD-First Architecture: Manages state via now.md.
+ * Source of truth is the markdown file, not JSON.
+ */
+
+import { MdBaseManager } from './md-base-manager'
+import { parseState, serializeState } from '../serializers'
+import type { StateJson, CurrentTask, PreviousTask } from '../schemas/state'
+
+class MdStateManager extends MdBaseManager<StateJson> {
+  constructor() {
+    super('core/now.md')
+  }
+
+  protected getDefault(): StateJson {
+    return {
+      currentTask: null,
+      lastUpdated: ''
+    }
+  }
+
+  protected parse(content: string): StateJson {
+    return parseState(content)
+  }
+
+  protected serialize(data: StateJson): string {
+    return serializeState(data)
+  }
+
+  // =========== Current Task ===========
+
+  async getCurrentTask(projectId: string): Promise<CurrentTask | null> {
+    const state = await this.read(projectId)
+    return state.currentTask
+  }
+
+  async setCurrentTask(projectId: string, task: CurrentTask | null): Promise<StateJson> {
+    return this.update(projectId, (state) => ({
+      ...state,
+      currentTask: task,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  async startTask(
+    projectId: string,
+    task: Omit<CurrentTask, 'startedAt'>
+  ): Promise<StateJson> {
+    const currentTask: CurrentTask = {
+      ...task,
+      startedAt: new Date().toISOString()
+    }
+
+    return this.update(projectId, () => ({
+      currentTask,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  async completeTask(projectId: string): Promise<StateJson> {
+    const state = await this.read(projectId)
+    if (!state.currentTask) {
+      throw new Error('No active task to complete')
+    }
+
+    return this.update(projectId, () => ({
+      currentTask: null,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  async pauseTask(projectId: string): Promise<StateJson> {
+    const state = await this.read(projectId)
+    if (!state.currentTask) {
+      throw new Error('No active task to pause')
+    }
+
+    const previousTask: PreviousTask = {
+      id: state.currentTask.id,
+      description: state.currentTask.description,
+      status: 'paused',
+      startedAt: state.currentTask.startedAt,
+      pausedAt: new Date().toISOString()
+    }
+
+    return this.update(projectId, () => ({
+      currentTask: null,
+      previousTask,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  async resumeTask(projectId: string): Promise<StateJson> {
+    const state = await this.read(projectId)
+    if (!state.previousTask) {
+      throw new Error('No paused task to resume')
+    }
+
+    const currentTask: CurrentTask = {
+      id: state.previousTask.id,
+      description: state.previousTask.description,
+      startedAt: new Date().toISOString(), // Reset start time
+      sessionId: `sess_${Date.now()}`
+    }
+
+    return this.update(projectId, () => ({
+      currentTask,
+      previousTask: null,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  async clearTask(projectId: string): Promise<StateJson> {
+    return this.update(projectId, () => ({
+      currentTask: null,
+      previousTask: null,
+      lastUpdated: new Date().toISOString()
+    }))
+  }
+
+  /**
+   * Check if there's an active or paused task
+   */
+  async hasTask(projectId: string): Promise<boolean> {
+    const state = await this.read(projectId)
+    return state.currentTask !== null || state.previousTask !== null
+  }
+}
+
+export const mdStateManager = new MdStateManager()
+export default mdStateManager

package/core/serializers/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Serializers Index
+ *
+ * MD-First Architecture: These serializers convert between TypeScript schemas and MD format.
+ */
+
+// State (now.md)
+export {
+  parseState,
+  serializeState,
+  createCurrentTaskMd,
+  createEmptyStateMd
+} from './state-serializer'
+
+// Queue (next.md)
+export {
+  parseQueue,
+  serializeQueue,
+  createEmptyQueueMd
+} from './queue-serializer'