prjct-cli 0.45.5 → 0.47.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [0.47.0] - 2026-01-30
+
+### Features
+
+- Complete and improve help text documentation - PRJ-133 (#73)
+- Workflow hooks via natural language - PRJ-137 (#72)
+- Subtask progress dashboard with domain colors - PRJ-138 (#71)
+
+
+## [0.48.1] - 2026-01-30
+
+### Improved
+
+- **Complete and improve help text documentation** (PRJ-133)
+  - New structured help system with `prjct help <command>` support
+  - Per-command help with usage, parameters, and features
+  - Commands grouped by category with `prjct help commands`
+  - Clean visual formatting with Quick Start, Terminal Commands, AI Agent Commands sections
+
+
+## [0.48.0] - 2026-01-29
+
+### Added
+
+- **Workflow hooks via natural language** (PRJ-137)
+  - Configure hooks with `p. workflow "antes de ship corre los tests"`
+  - Supports before/after hooks for task, done, ship, sync commands
+  - Three scopes: permanent (persisted), session, one-time
+  - Uses existing memory system for storage
+  - No JSON config needed - just talk to the LLM
+
+
+## [0.47.0] - 2026-01-29
+
+### Added
+
+- **Subtask progress dashboard with domain-specific colors** (PRJ-138)
+  - Each domain (frontend, backend, database, etc.) displays in unique color
+  - Hash-based color assignment ensures consistency across sessions
+  - Integrated into command execution flow for visual task tracking
+
+
+## [0.46.0] - 2026-01-30
+
+### Features
+
+- preserve user customizations during sync - PRJ-115 (#70)
+
+
+## [0.46.0] - 2026-01-30
+
+### Added
+
+- **Preserve user customizations during sync** (PRJ-115)
+  - Wrap custom content in `<!-- prjct:preserve -->` markers
+  - Content survives `p. sync` regeneration
+  - Supports named sections: `<!-- prjct:preserve:my-rules -->`
+  - Works with CLAUDE.md, .cursorrules, and all context files
+
+
 ## [0.45.5] - 2026-01-30
 
 ### Bug Fixes

package/bin/prjct.ts

@@ -184,53 +184,9 @@ if (args[0] === 'start' || args[0] === 'setup') {
   }
 } else if (args[0] === 'help' || args[0] === '-h' || args[0] === '--help') {
   // Show help - bypass setup check to always show help
-  console.log(`
-prjct - Context layer for AI coding agents
-Works with Claude Code, Gemini CLI, Antigravity, Cursor IDE, and more.
-
-QUICK START
------------
-  Claude/Gemini:
-    1. prjct start              Configure your AI provider
-    2. cd my-project && prjct init
-    3. Open in Claude Code or Gemini CLI
-    4. Type: p. sync            Analyze project
-
-  Cursor IDE:
-    1. cd my-project && prjct init
-    2. Open in Cursor
-    3. Type: /sync              Analyze project
-
-COMMANDS (inside your AI agent)
--------------------------------
-  Claude/Gemini          Cursor            Description
-  ─────────────────────────────────────────────────────
-  p. sync                /sync             Analyze project
-  p. task "desc"         /task "desc"      Start a task
-  p. done                /done             Complete subtask
-  p. ship "name"         /ship "name"      Ship with PR
-
-TERMINAL COMMANDS (this CLI)
-----------------------------
-  prjct start            First-time setup (Claude/Gemini global config)
-  prjct init             Initialize project (required for Cursor)
-  prjct setup            Reconfigure installations
-  prjct sync             Sync project state
-  prjct watch            Auto-sync on file changes (Ctrl+C to stop)
-  prjct doctor           Check system health and dependencies
-  prjct uninstall        Complete system removal of prjct
-
-FLAGS
------
-  --quiet, -q            Suppress all output (only errors to stderr)
-  --version, -v          Show version
-  --help, -h             Show this help
-
-MORE INFO
----------
-  Documentation:  https://prjct.app
-  GitHub:         https://github.com/jlopezlira/prjct-cli
-`)
+  const { getHelp } = await import('../core/utils/help')
+  const topic = args[1] // Optional: prjct help <command>
+  console.log(getHelp(topic))
   process.exitCode = 0
 } else if (args[0] === 'version' || args[0] === '-v' || args[0] === '--version') {
   // Show version with provider status

package/core/__tests__/utils/preserve-sections.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  extractPreservedContent,
+  extractPreservedSections,
+  hasPreservedSections,
+  mergePreservedSections,
+  stripPreservedSections,
+  validatePreserveBlocks,
+  wrapInPreserveMarkers,
+} from '../../utils/preserve-sections'
+
+describe('preserve-sections', () => {
+  describe('extractPreservedSections', () => {
+    it('should extract a single preserved section', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+My custom content
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].content).toContain('My custom content')
+    })
+
+    it('should extract multiple preserved sections', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+First section
+<!-- /prjct:preserve -->
+
+Some content
+
+<!-- prjct:preserve -->
+Second section
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(2)
+      expect(sections[0].content).toContain('First section')
+      expect(sections[1].content).toContain('Second section')
+    })
+
+    it('should handle named sections', () => {
+      const content = `<!-- prjct:preserve:custom-rules -->
+My rules
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].id).toBe('custom-rules')
+    })
+
+    it('should return empty array when no preserved sections', () => {
+      const content = '# Just normal content'
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+
+    it('should ignore unclosed preserve blocks', () => {
+      const content = `<!-- prjct:preserve -->
+No closing tag here`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+  })
+
+  describe('extractPreservedContent', () => {
+    it('should extract inner content without markers', () => {
+      const content = `<!-- prjct:preserve -->
+My content
+<!-- /prjct:preserve -->`
+
+      const inner = extractPreservedContent(content)
+      expect(inner).toHaveLength(1)
+      expect(inner[0]).toBe('My content')
+    })
+  })
+
+  describe('hasPreservedSections', () => {
+    it('should return true when preserved sections exist', () => {
+      const content = '<!-- prjct:preserve -->content<!-- /prjct:preserve -->'
+      expect(hasPreservedSections(content)).toBe(true)
+    })
+
+    it('should return false when no preserved sections', () => {
+      const content = '# Normal markdown'
+      expect(hasPreservedSections(content)).toBe(false)
+    })
+  })
+
+  describe('mergePreservedSections', () => {
+    it('should append preserved sections to new content', () => {
+      const oldContent = `# Old Header
+
+<!-- prjct:preserve -->
+# My Rules
+- Use tabs
+<!-- /prjct:preserve -->`
+
+      const newContent = `# New Generated Content
+
+This is fresh.`
+
+      const merged = mergePreservedSections(newContent, oldContent)
+
+      expect(merged).toContain('# New Generated Content')
+      expect(merged).toContain('My Rules')
+      expect(merged).toContain('Use tabs')
+      expect(merged).toContain('prjct:preserve')
+    })
+
+    it('should return new content unchanged when no preserved sections', () => {
+      const oldContent = '# Old content without preserve markers'
+      const newContent = '# New content'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toBe(newContent)
+    })
+
+    it('should preserve multiple sections', () => {
+      const oldContent = `<!-- prjct:preserve -->
+Section 1
+<!-- /prjct:preserve -->
+
+<!-- prjct:preserve -->
+Section 2
+<!-- /prjct:preserve -->`
+
+      const newContent = '# New'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toContain('Section 1')
+      expect(merged).toContain('Section 2')
+    })
+  })
+
+  describe('wrapInPreserveMarkers', () => {
+    it('should wrap content with default markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content)
+
+      expect(wrapped).toContain('<!-- prjct:preserve -->')
+      expect(wrapped).toContain('My content')
+      expect(wrapped).toContain('<!-- /prjct:preserve -->')
+    })
+
+    it('should wrap content with named markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content, 'custom')
+
+      expect(wrapped).toContain('<!-- prjct:preserve:custom -->')
+    })
+  })
+
+  describe('stripPreservedSections', () => {
+    it('should remove preserved sections from content', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+Custom stuff
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toContain('# Header')
+      expect(stripped).toContain('# Footer')
+      expect(stripped).not.toContain('Custom stuff')
+      expect(stripped).not.toContain('prjct:preserve')
+    })
+
+    it('should return content unchanged when no preserved sections', () => {
+      const content = '# Normal content'
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toBe(content)
+    })
+  })
+
+  describe('validatePreserveBlocks', () => {
+    it('should validate correct blocks', () => {
+      const content = `<!-- prjct:preserve -->
+Content
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(true)
+      expect(result.errors).toHaveLength(0)
+    })
+
+    it('should detect mismatched markers', () => {
+      const content = `<!-- prjct:preserve -->
+Content without closing`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should detect nested blocks', () => {
+      const content = `<!-- prjct:preserve -->
+<!-- prjct:preserve -->
+Nested
+<!-- /prjct:preserve -->
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.some((e) => e.includes('Nested'))).toBe(true)
+    })
+  })
+})

package/core/agentic/command-executor.ts

@@ -18,6 +18,7 @@ import type {
   SimpleExecutionResult,
 } from '../types'
 import { agentStream } from '../utils/agent-stream'
+import { printSubtaskProgress, type SubtaskDisplay } from '../utils/subtask-table'
 import chainOfThought from './chain-of-thought'
 import contextBuilder from './context-builder'
 import groundTruth from './ground-truth'
@@ -192,7 +193,13 @@ export class CommandExecutor {
 
           // Show subtasks if fragmented
           if (orchestratorContext.requiresFragmentation && orchestratorContext.subtasks) {
-            agentStream.status('📋', `${orchestratorContext.subtasks.length} subtasks planned`)
+            const subtaskDisplay: SubtaskDisplay[] = orchestratorContext.subtasks.map((s) => ({
+              id: s.id,
+              domain: s.domain,
+              description: s.description,
+              status: s.status,
+            }))
+            printSubtaskProgress(subtaskDisplay)
           }
         } catch (error) {
           // Orchestration failed - log warning but continue without it

package/core/ai-tools/generator.ts

@@ -7,6 +7,7 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { mergePreservedSections } from '../utils/preserve-sections'
 import { getFormatter, type ProjectContext } from './formatters'
 import { AI_TOOLS, type AIToolConfig, DEFAULT_AI_TOOLS, getAIToolConfig } from './registry'
 
@@ -71,7 +72,7 @@ async function generateForTool(
 
   try {
     // Generate content
-    const content = formatter(context, config)
+    let content = formatter(context, config)
 
     // Determine output path
     let outputPath: string
@@ -84,6 +85,14 @@ async function generateForTool(
     // Ensure directory exists
     await fs.mkdir(path.dirname(outputPath), { recursive: true })
 
+    // Read existing file to preserve user customizations
+    try {
+      const existingContent = await fs.readFile(outputPath, 'utf-8')
+      content = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
     // Write file
     await fs.writeFile(outputPath, content, 'utf-8')
 

package/core/commands/command-data.ts

@@ -285,6 +285,22 @@ export const COMMANDS: CommandMeta[] = [
     requiresProject: true,
     isOptional: true,
   },
+  {
+    name: 'workflow',
+    group: 'optional',
+    description: 'Configure workflow hooks via natural language',
+    usage: { claude: '/p:workflow ["config"]', terminal: 'prjct workflow ["config"]' },
+    params: '["natural language config"]',
+    implemented: true,
+    hasTemplate: true,
+    requiresProject: true,
+    isOptional: true,
+    features: [
+      'Natural language configuration',
+      'Before/after hooks for task, done, ship, sync',
+      'Permanent, session, or one-time preferences',
+    ],
+  },
 
   // ===== SETUP COMMANDS =====
   {

package/core/commands/commands.ts

@@ -90,6 +90,13 @@ class PrjctCommands {
     return this.workflow.resume(taskId, projectPath)
   }
 
+  async workflowPrefs(
+    input: string | null = null,
+    projectPath: string = process.cwd()
+  ): Promise<CommandResult> {
+    return this.workflow.workflow(input, projectPath)
+  }
+
   // ========== Planning Commands ==========
 
   async init(

package/core/commands/register.ts

@@ -58,6 +58,7 @@ export function registerAllCommands(): void {
   commandRegistry.registerMethod('next', workflow, 'next', getMeta('next'))
   commandRegistry.registerMethod('pause', workflow, 'pause', getMeta('pause'))
   commandRegistry.registerMethod('resume', workflow, 'resume', getMeta('resume'))
+  commandRegistry.registerMethod('workflow', workflow, 'workflow', getMeta('workflow'))
 
   // Planning commands
   commandRegistry.registerMethod('init', planning, 'init', getMeta('init'))

package/core/commands/setup.ts

@@ -50,9 +50,9 @@ export class SetupCommands extends PrjctCommandsBase {
 
     if ((result.errors?.length ?? 0) > 0) {
       console.log(`\n⚠️  ${result.errors?.length ?? 0} errors:`)
-      result.errors?.forEach((e: { file: string; error: string }) =>
+      for (const e of result.errors ?? []) {
         console.log(`   - ${e.file}: ${e.error}`)
-      )
+      }
     }
 
     console.log('\n🎉 Setup complete!')
@@ -92,9 +92,9 @@ export class SetupCommands extends PrjctCommandsBase {
 
     if ((result.errors?.length ?? 0) > 0) {
       console.log(`\n⚠️  ${result.errors?.length ?? 0} errors:`)
-      result.errors?.forEach((e: { file: string; error: string }) =>
+      for (const e of result.errors ?? []) {
         console.log(`   - ${e.file}: ${e.error}`)
-      )
+      }
     }
 
     console.log('\n📝 Installing global configuration...')

package/core/commands/shipping.ts

@@ -10,6 +10,7 @@ import type { CommandResult } from '../types'
 import { isNotFoundError } from '../types/fs'
 import { showNextSteps } from '../utils/next-steps'
 import { detectProjectCommands } from '../utils/project-commands'
+import { runWorkflowHooks } from '../workflow/workflow-preferences'
 import { configManager, dateHelper, fileHelper, out, PrjctCommandsBase, toolRegistry } from './base'
 
 export class ShippingCommands extends PrjctCommandsBase {
@@ -48,13 +49,20 @@ export class ShippingCommands extends PrjctCommandsBase {
   /**
    * /p:ship - Ship feature with complete automated workflow
    */
-  async ship(feature: string | null, projectPath: string = process.cwd()): Promise<CommandResult> {
+  async ship(
+    feature: string | null,
+    projectPath: string = process.cwd(),
+    options: { skipHooks?: boolean } = {}
+  ): Promise<CommandResult> {
     try {
       const initResult = await this.ensureProjectInit(projectPath)
       if (!initResult.success) return initResult
 
-      const config = await configManager.readConfig(projectPath)
-      const projectId = config!.projectId
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        out.fail('no project ID')
+        return { success: false, error: 'No project ID found' }
+      }
 
       let featureName = feature
       if (!featureName) {
@@ -63,6 +71,15 @@ export class ShippingCommands extends PrjctCommandsBase {
         featureName = currentTask?.description || 'current work'
       }
 
+      // Run before_ship hooks (using memory-based preferences)
+      const beforeResult = await runWorkflowHooks(projectId, 'before', 'ship', {
+        projectPath,
+        skipHooks: options.skipHooks,
+      })
+      if (!beforeResult.success) {
+        return { success: false, error: `Hook failed: ${beforeResult.failed}` }
+      }
+
       // Ship steps with progress indicator
       out.step(1, 5, `Linting ${featureName}...`)
       const lintResult = await this._runLint(projectPath)
@@ -108,6 +125,12 @@ export class ShippingCommands extends PrjctCommandsBase {
         })
       }
 
+      // Run after_ship hooks
+      await runWorkflowHooks(projectId, 'after', 'ship', {
+        projectPath,
+        skipHooks: options.skipHooks,
+      })
+
       out.done(`v${newVersion} shipped`)
       showNextSteps('ship')
 

package/core/commands/workflow.ts

@@ -16,6 +16,16 @@ import { queueStorage, stateStorage } from '../storage'
 import type { CommandResult } from '../types'
 import { showNextSteps, showStateInfo } from '../utils/next-steps'
 import { getLinearApiKey, getProjectCredentials } from '../utils/project-credentials'
+import {
+  formatWorkflowPreferences,
+  type HookCommand,
+  type HookPhase,
+  listWorkflowPreferences,
+  type PreferenceScope,
+  removeWorkflowPreference,
+  runWorkflowHooks,
+  setWorkflowPreference,
+} from '../workflow/workflow-preferences'
 import { configManager, dateHelper, out, PrjctCommandsBase } from './base'
 
 export class WorkflowCommands extends PrjctCommandsBase {
@@ -24,7 +34,8 @@ export class WorkflowCommands extends PrjctCommandsBase {
    */
   async now(
     task: string | null = null,
-    projectPath: string = process.cwd()
+    projectPath: string = process.cwd(),
+    options: { skipHooks?: boolean } = {}
   ): Promise<CommandResult> {
     try {
       const initResult = await this.ensureProjectInit(projectPath)
@@ -37,6 +48,15 @@ export class WorkflowCommands extends PrjctCommandsBase {
       }
 
       if (task) {
+        // Run before_task hooks (using memory-based preferences)
+        const beforeResult = await runWorkflowHooks(projectId, 'before', 'task', {
+          projectPath,
+          skipHooks: options.skipHooks,
+        })
+        if (!beforeResult.success) {
+          return { success: false, error: `Hook failed: ${beforeResult.failed}` }
+        }
+
         // AGENTIC: Use CommandExecutor for full orchestration support
         const result = await commandExecutor.execute('task', { task }, projectPath)
 
@@ -97,6 +117,12 @@ export class WorkflowCommands extends PrjctCommandsBase {
           timestamp: dateHelper.getTimestamp(),
         })
 
+        // Run after_task hooks
+        await runWorkflowHooks(projectId, 'after', 'task', {
+          projectPath,
+          skipHooks: options.skipHooks,
+        })
+
         return {
           // Include full CommandExecutor result first (orchestratorContext, prompt, etc.)
           ...result,
@@ -127,7 +153,10 @@ export class WorkflowCommands extends PrjctCommandsBase {
   /**
    * /p:done - Complete current task
    */
-  async done(projectPath: string = process.cwd()): Promise<CommandResult> {
+  async done(
+    projectPath: string = process.cwd(),
+    options: { skipHooks?: boolean } = {}
+  ): Promise<CommandResult> {
     try {
       const initResult = await this.ensureProjectInit(projectPath)
       if (!initResult.success) return initResult
@@ -146,6 +175,15 @@ export class WorkflowCommands extends PrjctCommandsBase {
         return { success: true, message: 'No active task to complete' }
       }
 
+      // Run before_done hooks (using memory-based preferences)
+      const beforeResult = await runWorkflowHooks(projectId, 'before', 'done', {
+        projectPath,
+        skipHooks: options.skipHooks,
+      })
+      if (!beforeResult.success) {
+        return { success: false, error: `Hook failed: ${beforeResult.failed}` }
+      }
+
       const task = currentTask.description
       let duration = ''
       if (currentTask.startedAt) {
@@ -184,6 +222,13 @@ export class WorkflowCommands extends PrjctCommandsBase {
         duration,
         timestamp: dateHelper.getTimestamp(),
       })
+
+      // Run after_done hooks
+      await runWorkflowHooks(projectId, 'after', 'done', {
+        projectPath,
+        skipHooks: options.skipHooks,
+      })
+
       return { success: true, task, duration }
     } catch (error) {
       out.fail((error as Error).message)
@@ -312,4 +357,62 @@ export class WorkflowCommands extends PrjctCommandsBase {
       return { success: false, error: (error as Error).message }
     }
   }
+
+  /**
+   * /p:workflow - View and manage workflow preferences
+   *
+   * When called without arguments, shows current preferences.
+   * With arguments, parses natural language and updates preferences.
+   */
+  async workflow(
+    input: string | null = null,
+    projectPath: string = process.cwd()
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        out.fail('no project ID')
+        return { success: false, error: 'No project ID found' }
+      }
+
+      if (!input) {
+        // Show current preferences
+        const preferences = await listWorkflowPreferences(projectId)
+        console.log(formatWorkflowPreferences(preferences))
+        return { success: true, preferences }
+      }
+
+      // Return info for template-based processing
+      // The template/LLM will parse the natural language and call the appropriate functions
+      return {
+        success: true,
+        projectId,
+        input,
+        // Export functions for template use
+        setWorkflowPreference: async (pref: {
+          hook: HookPhase
+          command: HookCommand
+          action: string
+          scope: PreferenceScope
+        }) => {
+          await setWorkflowPreference(projectId, {
+            ...pref,
+            createdAt: dateHelper.getTimestamp(),
+          })
+        },
+        removeWorkflowPreference: async (hook: HookPhase, command: HookCommand) => {
+          await removeWorkflowPreference(projectId, hook, command)
+        },
+        listWorkflowPreferences: async () => {
+          return listWorkflowPreferences(projectId)
+        },
+      }
+    } catch (error) {
+      out.fail((error as Error).message)
+      return { success: false, error: (error as Error).message }
+    }
+  }
 }