prjct-cli 0.47.0 → 0.49.0

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

@@ -39,7 +39,7 @@ export class AnalyticsCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -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/cleanup.ts

@@ -79,7 +79,7 @@ export async function cleanup(
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 

package/core/commands/commands.ts

@@ -220,7 +220,7 @@ class PrjctCommands {
   }
 
   showAsciiArt(): void {
-    return this.setupCmds.showAsciiArt()
+    this.setupCmds.showAsciiArt()
   }
 
   // ========== Delegated Base Methods ==========

package/core/commands/planning.ts

@@ -254,7 +254,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -325,7 +325,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -485,7 +485,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -562,7 +562,7 @@ Generated: ${new Date().toLocaleString()}
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

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

@@ -60,7 +60,7 @@ export class ShippingCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

package/core/commands/snapshots.ts

@@ -28,7 +28,7 @@ export async function recover(projectPath: string = process.cwd()): Promise<Comm
   try {
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -85,7 +85,7 @@ export async function undo(projectPath: string = process.cwd()): Promise<Command
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -147,7 +147,7 @@ export async function undo(projectPath: string = process.cwd()): Promise<Command
       out.done('changes stashed (use /p:redo to restore)')
       return { success: true, snapshotId: stashMessage }
     } catch (gitError) {
-      out.fail('git operation failed')
+      out.failWithHint('GIT_OPERATION_FAILED')
       return { success: false, error: (gitError as Error).message }
     }
   } catch (error) {
@@ -165,7 +165,7 @@ export async function redo(projectPath: string = process.cwd()): Promise<Command
 
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 
@@ -231,7 +231,7 @@ export async function redo(projectPath: string = process.cwd()): Promise<Command
       out.done('changes restored')
       return { success: true }
     } catch (gitError) {
-      out.fail('git operation failed')
+      out.failWithHint('GIT_OPERATION_FAILED')
       return { success: false, error: (gitError as Error).message }
     }
   } catch (error) {
@@ -247,7 +247,7 @@ export async function history(projectPath: string = process.cwd()): Promise<Comm
   try {
     const projectId = await configManager.getProjectId(projectPath)
     if (!projectId) {
-      out.fail('no project ID')
+      out.failWithHint('NO_PROJECT_ID')
       return { success: false, error: 'No project ID found' }
     }
 

package/core/commands/workflow.ts

@@ -43,7 +43,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -163,7 +163,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -246,7 +246,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -278,7 +278,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -323,7 +323,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 
@@ -374,7 +374,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const projectId = await configManager.getProjectId(projectPath)
       if (!projectId) {
-        out.fail('no project ID')
+        out.failWithHint('NO_PROJECT_ID')
         return { success: false, error: 'No project ID found' }
       }
 

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 {

package/core/services/agent-generator.ts

@@ -9,6 +9,11 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import {
+  hasPreservedSections,
+  mergePreservedSections,
+  validatePreserveBlocks,
+} from '../utils/preserve-sections'
 import type { StackDetection } from './stack-detector'
 
 // ============================================================================
@@ -65,21 +70,68 @@ export class AgentGenerator {
   }
 
   /**
-   * Remove existing agent files
+   * Cache of existing agent content (for preserving user sections)
+   */
+  private existingAgents: Map<string, string> = new Map()
+
+  /**
+   * Read existing agents and cache their content for preservation
+   * Then remove the files (they'll be regenerated with preserved sections)
    */
   private async purgeOldAgents(): Promise<void> {
+    this.existingAgents.clear()
+
     try {
       const files = await fs.readdir(this.agentsPath)
+      const mdFiles = files.filter((file) => file.endsWith('.md'))
+
+      // Read all existing agent files BEFORE deleting
       await Promise.all(
-        files
-          .filter((file) => file.endsWith('.md'))
-          .map((file) => fs.unlink(path.join(this.agentsPath, file)))
+        mdFiles.map(async (file) => {
+          const filePath = path.join(this.agentsPath, file)
+          try {
+            const content = await fs.readFile(filePath, 'utf-8')
+            // Only cache if it has user-preserved sections
+            if (hasPreservedSections(content)) {
+              this.existingAgents.set(file, content)
+            }
+          } catch {
+            // File read failed, skip
+          }
+        })
       )
+
+      // Now delete the files
+      await Promise.all(mdFiles.map((file) => fs.unlink(path.join(this.agentsPath, file))))
     } catch {
       // Directory might not exist yet
     }
   }
 
+  /**
+   * Write agent file, preserving user sections from previous version
+   */
+  private async writeAgentWithPreservation(filename: string, content: string): Promise<void> {
+    const existingContent = this.existingAgents.get(filename)
+
+    let finalContent = content
+    if (existingContent) {
+      // Validate existing preserved blocks
+      const validation = validatePreserveBlocks(existingContent)
+      if (!validation.valid) {
+        console.warn(`⚠️  Agent ${filename} has invalid preserve blocks:`)
+        for (const error of validation.errors) {
+          console.warn(`   ${error}`)
+        }
+      }
+
+      // Merge preserved sections from old content
+      finalContent = mergePreservedSections(content, existingContent)
+    }
+
+    await fs.writeFile(path.join(this.agentsPath, filename), finalContent, 'utf-8')
+  }
+
   /**
    * Generate workflow agents (always included)
    */
@@ -143,7 +195,7 @@ export class AgentGenerator {
       content = this.generateMinimalWorkflowAgent(name)
     }
 
-    await fs.writeFile(path.join(this.agentsPath, `${name}.md`), content, 'utf-8')
+    await this.writeAgentWithPreservation(`${name}.md`, content)
   }
 
   /**
@@ -169,7 +221,7 @@ export class AgentGenerator {
       content = this.generateMinimalDomainAgent(name, stats, stack)
     }
 
-    await fs.writeFile(path.join(this.agentsPath, `${name}.md`), content, 'utf-8')
+    await this.writeAgentWithPreservation(`${name}.md`, content)
   }
 
   /**

package/core/services/context-generator.ts

@@ -12,7 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import dateHelper from '../utils/date-helper'
-import { mergePreservedSections } from '../utils/preserve-sections'
+import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 
 // ============================================================================
 // TYPES
@@ -65,6 +65,35 @@ export class ContextFileGenerator {
     this.config = config
   }
 
+  /**
+   * Write file with preserved sections from existing content
+   * This ensures user customizations survive regeneration
+   */
+  private async writeWithPreservation(filePath: string, content: string): Promise<void> {
+    let finalContent = content
+
+    try {
+      const existingContent = await fs.readFile(filePath, 'utf-8')
+
+      // Validate existing preserved blocks
+      const validation = validatePreserveBlocks(existingContent)
+      if (!validation.valid) {
+        const filename = path.basename(filePath)
+        console.warn(`⚠️  ${filename} has invalid preserve blocks:`)
+        for (const error of validation.errors) {
+          console.warn(`   ${error}`)
+        }
+      }
+
+      // Merge preserved sections from existing content
+      finalContent = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
+    await fs.writeFile(filePath, finalContent, 'utf-8')
+  }
+
   /**
    * Generate all context files in parallel
    */
@@ -181,17 +210,8 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Domain**: ${domainAgents.join(', ') || 'none'}
 `
 
-    // Preserve user customizations from existing file
     const claudePath = path.join(contextPath, 'CLAUDE.md')
-    let finalContent = content
-    try {
-      const existingContent = await fs.readFile(claudePath, 'utf-8')
-      finalContent = mergePreservedSections(content, existingContent)
-    } catch {
-      // File doesn't exist yet - use generated content as-is
-    }
-
-    await fs.writeFile(claudePath, finalContent, 'utf-8')
+    await this.writeWithPreservation(claudePath, content)
   }
 
   /**
@@ -222,7 +242,7 @@ _No active task_
 Use \`p. task "description"\` to start working.
 `
 
-    await fs.writeFile(path.join(contextPath, 'now.md'), content, 'utf-8')
+    await this.writeWithPreservation(path.join(contextPath, 'now.md'), content)
   }
 
   /**
@@ -248,7 +268,7 @@ ${
 }
 `
 
-    await fs.writeFile(path.join(contextPath, 'next.md'), content, 'utf-8')
+    await this.writeWithPreservation(path.join(contextPath, 'next.md'), content)
   }
 
   /**
@@ -272,7 +292,7 @@ ${
 }
 `
 
-    await fs.writeFile(path.join(contextPath, 'ideas.md'), content, 'utf-8')
+    await this.writeWithPreservation(path.join(contextPath, 'ideas.md'), content)
   }
 
   /**
@@ -303,7 +323,7 @@ ${
 **Total shipped:** ${shipped.shipped.length}
 `
 
-    await fs.writeFile(path.join(contextPath, 'shipped.md'), content, 'utf-8')
+    await this.writeWithPreservation(path.join(contextPath, 'shipped.md'), content)
   }
 }