prjct-cli 0.46.0 → 0.48.0

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/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/agentic/context-builder.ts

@@ -15,10 +15,10 @@ import { isNotFoundError } from '../types/fs'
 // Re-export types for convenience
 export type { ContextPaths, ContextState, ProjectContext } from '../types'
 
-// Local type aliases for backward compatibility
-type Paths = ContextPaths
-type Context = ProjectContext
-type State = ContextState
+// Type aliases exported for backward compatibility (used by external consumers)
+export type Paths = ContextPaths
+export type Context = ProjectContext
+export type State = ContextState
 
 /**
  * Builds and caches project context for Claude decisions.

package/core/agentic/memory-system.ts

@@ -574,7 +574,9 @@ export class SemanticMemories extends CachedStore<MemoryDatabase> {
       const matchingIds = new Set<string>()
       for (const tag of parsedTags) {
         const ids = db.index[tag]
-        ids.forEach((id: string) => matchingIds.add(id))
+        for (const id of ids) {
+          matchingIds.add(id)
+        }
       }
       return db.memories.filter((m) => matchingIds.has(m.id))
     }

package/core/agentic/prompt-builder.ts

@@ -502,10 +502,14 @@ class PromptBuilder {
       parts.push('\n## THINK FIRST (reasoning from analysis)\n')
       if (thinkBlock.conclusions && thinkBlock.conclusions.length > 0) {
         parts.push('Conclusions:\n')
-        thinkBlock.conclusions.forEach((c) => parts.push(`  → ${c}\n`))
+        for (const c of thinkBlock.conclusions) {
+          parts.push(`  → ${c}\n`)
+        }
       }
       parts.push('Plan:\n')
-      thinkBlock.plan.forEach((p, i) => parts.push(`  ${i + 1}. ${p}\n`))
+      for (let i = 0; i < thinkBlock.plan.length; i++) {
+        parts.push(`  ${i + 1}. ${thinkBlock.plan[i]}\n`)
+      }
       parts.push(`Confidence: ${Math.round((thinkBlock.confidence || 0.5) * 100)}%\n`)
     }
 

package/core/agentic/smart-context.ts

@@ -32,8 +32,8 @@ export type {
   StackInfo,
 } from '../types'
 
-// Local type alias for backward compatibility
-type ProjectState = SmartContextProjectState
+// Type alias exported for backward compatibility (used by external consumers)
+export type ProjectState = SmartContextProjectState
 
 /**
  * SmartContext - Intelligent context filtering.

package/core/ai-tools/generator.ts

@@ -7,7 +7,7 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import { mergePreservedSections } from '../utils/preserve-sections'
+import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 import { getFormatter, type ProjectContext } from './formatters'
 import { AI_TOOLS, type AIToolConfig, DEFAULT_AI_TOOLS, getAIToolConfig } from './registry'
 
@@ -88,6 +88,16 @@ async function generateForTool(
     // Read existing file to preserve user customizations
     try {
       const existingContent = await fs.readFile(outputPath, 'utf-8')
+
+      // Validate existing preserved blocks
+      const validation = validatePreserveBlocks(existingContent)
+      if (!validation.valid) {
+        console.warn(`⚠️  ${config.outputFile} has invalid preserve blocks:`)
+        for (const error of validation.errors) {
+          console.warn(`   ${error}`)
+        }
+      }
+
       content = mergePreservedSections(content, existingContent)
     } catch {
       // File doesn't exist yet - use generated content as-is

package/core/cli/linear.ts

@@ -24,6 +24,7 @@
  * All output is JSON for easy parsing by Claude.
  */
 
+import type { CreateIssueInput, Issue } from '../integrations/issue-tracker/types'
 import { linearService, linearSync } from '../integrations/linear'
 import {
   getCredentialSource,
@@ -140,7 +141,7 @@ async function main(): Promise<void> {
 
         // Use team issues if teamId is configured, otherwise assigned issues
         const creds = await getProjectCredentials(projectId!)
-        let issues
+        let issues: Issue[]
         if (creds.linear?.teamId) {
           issues = await linearService.fetchTeamIssues(creds.linear.teamId, { limit })
         } else {
@@ -254,7 +255,7 @@ async function main(): Promise<void> {
           error('JSON input required. Usage: create \'{"title":"...", "teamId":"..."}\'')
         }
 
-        let input
+        let input: Record<string, unknown>
         try {
           input = JSON.parse(inputJson)
         } catch {
@@ -274,7 +275,7 @@ async function main(): Promise<void> {
           }
         }
 
-        const issue = await linearService.createIssue(input)
+        const issue = await linearService.createIssue(input as unknown as CreateIssueInput)
         output(issue)
         break
       }
@@ -291,7 +292,7 @@ async function main(): Promise<void> {
           error('JSON input required. Usage: update <id> \'{"description":"..."}\'')
         }
 
-        let input
+        let input: Record<string, unknown>
         try {
           input = JSON.parse(inputJson)
         } catch {

package/core/commands/analytics.ts

@@ -256,7 +256,9 @@ export class AnalyticsCommands extends PrjctCommandsBase {
 
         if (command.features) {
           console.log('\nFeatures:')
-          command.features.forEach((f) => console.log(`  • ${f}`))
+          for (const f of command.features) {
+            console.log(`  • ${f}`)
+          }
         }
 
         console.log(`\n${'═'.repeat(50)}\n`)

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(
@@ -213,7 +220,7 @@ class PrjctCommands {
   }
 
   showAsciiArt(): void {
-    return this.setupCmds.showAsciiArt()
+    this.setupCmds.showAsciiArt()
   }
 
   // ========== Delegated Base Methods ==========

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/registry.ts

@@ -117,10 +117,11 @@ export class CommandRegistry {
     const wrapper: HandlerFn<unknown> = async (params, context) => {
       // Legacy commands expect (param?, projectPath) signature
       // Most commands use first param + projectPath
+      type LegacyMethod = (...args: unknown[]) => Promise<CommandResult>
       if (params !== undefined && params !== null) {
-        return (method as Function).call(instance, params, context.projectPath)
+        return (method as LegacyMethod).call(instance, params, context.projectPath)
       }
-      return (method as Function).call(instance, context.projectPath)
+      return (method as LegacyMethod).call(instance, context.projectPath)
     }
 
     this.handlerFns.set(name, wrapper)

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 }
+    }
+  }
 }

package/core/constants/index.ts

@@ -108,7 +108,9 @@ export const ROADMAP = {
     const lines = [`## ${feature}`, '', `Status: ${ROADMAP_STATUS[status]}`]
     if (tasks && tasks.length > 0) {
       lines.push('', '### Tasks', '')
-      tasks.forEach((task) => lines.push(`- [ ] ${task}`))
+      for (const task of tasks) {
+        lines.push(`- [ ] ${task}`)
+      }
     }
     return `${lines.join('\n')}\n\n`
   },

package/core/context-tools/imports-tool.ts

@@ -229,7 +229,7 @@ function extractImports(
   for (const patternDef of patterns) {
     patternDef.pattern.lastIndex = 0
 
-    let match
+    let match: RegExpExecArray | null
     while ((match = patternDef.pattern.exec(content)) !== null) {
       const source = match[patternDef.sourceIndex]
       if (!source || seen.has(source)) continue

package/core/context-tools/signatures-tool.ts

@@ -439,7 +439,7 @@ function extractFromContent(content: string, patterns: ExtractionPattern[]): Cod
     // Reset lastIndex for global regex
     patternDef.pattern.lastIndex = 0
 
-    let match
+    let match: RegExpExecArray | null
     while ((match = patternDef.pattern.exec(content)) !== null) {
       const name = match[patternDef.nameIndex]
       if (!name) continue

package/core/plugin/hooks.ts

@@ -40,7 +40,7 @@ const HookPoints = {
   TRANSFORM_METRICS: 'transform:metrics',
 } as const
 
-type HookPoint = (typeof HookPoints)[keyof typeof HookPoints]
+export type HookPoint = (typeof HookPoints)[keyof typeof HookPoints]
 type HookHandler = (data: unknown, context?: unknown) => unknown | Promise<unknown>
 
 interface HookEntry {