prjct-cli 1.6.7 → 1.6.8

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [1.6.8] - 2026-02-07
+
+### Refactoring
+
+- standardize export patterns to ESM (PRJ-99) (#132)
+
+
+## [1.6.9] - 2026-02-07
+
+### Refactor
+- **Standardize export patterns to ESM (PRJ-99)**: Removed redundant `export default { ... }` CJS-compat patterns from 33 files across `core/`. Updated 19 import sites to use namespace imports (`import * as X`). Cleaned 3 barrel re-exports in `agentic/index.ts`, `bus/index.ts`, and `storage/index.ts`. 3 function-collection modules (chain-of-thought, ground-truth, template-loader) retain proper singleton defaults for test mocking compatibility. Net reduction of 274 lines.
+
+### Implementation Details
+Removed the redundant pattern where files had both named exports (`export function X`) and a CJS-compat default export object (`export default { X, Y, Z }`). All 33 cleaned files already had proper named exports, making the default objects unnecessary. Import sites referencing removed defaults were converted to `import * as X from` namespace imports, which preserves the `X.method()` usage pattern.
+
+### Learnings
+- Bun enforces read-only properties on ESM namespace objects (`import * as X`) — direct property assignment for test mocking fails at runtime
+- Function-collection modules that need test mocking should export a named singleton object as default, consistent with class-instance modules like `pathManager`, `loopDetector`
+- Barrel file (`index.ts`) re-exports of `default` must be updated when removing default exports from source modules
+
+### Test Plan
+
+#### For QA
+1. Run `bun run build` — should complete with no errors
+2. Run `bun run test` — all 416 tests should pass (1 pre-existing timeout flake in DependencyValidator)
+3. Run `bun run lint` — no lint errors
+4. Run `npx tsc -p core/tsconfig.json --noEmit` — no type errors
+5. Verify `prjct sync --yes` still works end-to-end
+
+#### For Users
+**What changed:** Internal refactor only — no API or CLI behavior changes.
+**How to use:** No user action needed.
+**Breaking changes:** None.
+
+## [1.6.8] - 2026-02-07
+
+### Documentation
+- **Add JSDoc to CachedStore class methods (PRJ-91)**: Enhanced all 12 public/protected methods on the `CachedStore<T>` base class with comprehensive JSDoc including `@param`, `@returns`, `@throws`, `@example`, and `@typeParam` annotations. Improved class-level documentation with usage example and cross-references to subclasses.
+
+### Test Plan
+
+#### For QA
+1. Build (`bun run build`) — should succeed
+2. Typecheck (`npx tsc -p core/tsconfig.json --noEmit`) — should pass
+3. Verify JSDoc renders in IDE hover tooltips for CachedStore methods
+
+#### For Users
+**What changed:** Better IDE documentation for CachedStore internals.
+**Breaking changes:** None
+
+
 ## [1.6.7] - 2026-02-07
 
 ### Bug Fixes
@@ -787,7 +838,7 @@ Added visual workflow status template showing:
 - add automatic npm publication and update detection system
 - publish prjct-cli to npm registry
 - remove bun and homebrew installation methods
-- add natural language interface with English and Spanish support
+- add natural language interface with multi-language support
 - add interactive workflow system with capability detection and installation
 - release v0.3.0 with interactive editor selection and codebase analysis
 - add project management workflows for analyzing, tracking, and fixing tasks
@@ -810,7 +861,7 @@ Added visual workflow status template showing:
 - make Linear/JIRA templates explicitly ignore MCP tools
 - remove MCP inheritance from Linear/JIRA templates
 - standardize confirmation pattern across all commands (#85)
-- LLM debe manejar los prompts, no el CLI - PRJ-149 (#84)
+- LLM must handle the prompts, not the CLI - PRJ-149 (#84)
 - Claude over-plans simple commands like p. sync - PRJ-148 (#83)
 - implement silent memory application - PRJ-103 (#69)
 - ignore tar warning in release workflow - PRJ-147
@@ -1436,14 +1487,14 @@ Implemented hierarchical agent resolution allowing AGENTS.md files at any direct
 
 ### Bug Fixes
 
-- LLM debe manejar los prompts, no el CLI - PRJ-149 (#84)
+- LLM must handle the prompts, not the CLI - PRJ-149 (#84)
 
 
 ## [0.55.3] - 2026-01-30
 
 ### Fixed
 
-- **LLM debe manejar los prompts, no el CLI** (PRJ-149)
+- **LLM must handle the prompts, not the CLI** (PRJ-149)
   - Added `--json` flag to `prjct sync` for non-interactive mode
   - CLI now detects non-TTY mode and outputs structured JSON instead of interactive prompts
   - Updated `sync.md` template so LLM uses AskUserQuestion for confirmation
@@ -1653,7 +1704,7 @@ Implemented hierarchical agent resolution allowing AGENTS.md files at any direct
 ### Added
 
 - **Workflow hooks via natural language** (PRJ-137)
-  - Configure hooks with `p. workflow "antes de ship corre los tests"`
+  - Configure hooks with `p. workflow "before ship run the tests"`
   - Supports before/after hooks for task, done, ship, sync commands
   - Three scopes: permanent (persisted), session, one-time
   - Uses existing memory system for storage

package/core/agentic/chain-of-thought.ts

@@ -229,4 +229,6 @@ function formatPlan(result: ReasoningResult): string {
 }
 
 export { requiresReasoning, reason, formatPlan, REASONING_REQUIRED_COMMANDS }
-export default { requiresReasoning, reason, formatPlan }
+
+const chainOfThought = { requiresReasoning, reason, formatPlan, REASONING_REQUIRED_COMMANDS }
+export default chainOfThought

package/core/agentic/ground-truth.ts

@@ -686,14 +686,21 @@ export function requiresVerification(commandName: string): boolean {
   return ['done', 'ship', 'feature', 'spec', 'now', 'init', 'sync', 'analyze'].includes(commandName)
 }
 
-// =============================================================================
-// Default Export
-// =============================================================================
-
-export default {
+const groundTruth = {
   verify,
   prepareCommand,
   requiresVerification,
   verifiers,
   formatWarnings,
+  formatDuration,
+  escapeRegex,
+  verifyDone,
+  verifyShip,
+  verifyFeature,
+  verifyNow,
+  verifyInit,
+  verifySync,
+  verifyAnalyze,
+  verifySpec,
 }
+export default groundTruth

package/core/agentic/index.ts

@@ -104,7 +104,13 @@ export type {
 export { default as AgentRouter } from './agent-router'
 // ============ Utilities ============
 // Chain of thought, services
-export { default as chainOfThought } from './chain-of-thought'
+export {
+  default as chainOfThought,
+  formatPlan,
+  REASONING_REQUIRED_COMMANDS,
+  reason,
+  requiresReasoning,
+} from './chain-of-thought'
 // ============ Execution ============
 // Command execution, loop detection
 export {
@@ -174,7 +180,13 @@ export { default as promptBuilder } from './prompt-builder'
 export { default as services } from './services'
 export { default as smartContext } from './smart-context'
 export { default as templateExecutor, TemplateExecutor } from './template-executor'
-export { default as templateLoader } from './template-loader'
+export {
+  clearCache,
+  default as templateLoader,
+  getAllowedTools,
+  load,
+  parseFrontmatter,
+} from './template-loader'
 // ============ Tools ============
 // Tool and template management
 export { default as toolRegistry } from './tool-registry'

package/core/agentic/memory-system.ts

@@ -65,17 +65,26 @@ import { calculateConfidence, MEMORY_TAGS } from '../types/memory'
 // =============================================================================
 
 /**
- * CachedStore - Abstract base class for memory system stores
+ * Abstract base class for project-scoped, disk-backed stores with in-memory caching.
  *
- * Eliminates duplicated cache/load/save patterns across:
- * - PatternStore (~40 lines of boilerplate)
- * - SemanticMemories (~40 lines of boilerplate)
+ * Provides lazy loading, automatic directory creation on save, and project-scoped
+ * cache invalidation. Subclasses only need to define the filename, default data
+ * structure, and optionally a subdirectory or post-load normalization hook.
  *
- * Provides:
- * - Lazy loading with project-scoped cache
- * - Automatic directory creation on save
- * - Reset functionality
- * - Path management via pathManager
+ * Extended by {@link PatternStore} and {@link SemanticMemories}.
+ *
+ * @typeParam T - The shape of the stored data (e.g., `Patterns`, `MemoryDatabase`)
+ *
+ * @example
+ * ```ts
+ * class MyStore extends CachedStore<MyData> {
+ *   protected getFilename() { return 'my-data.json' }
+ *   protected getDefault() { return { items: [] } }
+ * }
+ *
+ * const store = new MyStore()
+ * const data = await store.load('project-id')
+ * ```
  */
 export abstract class CachedStore<T> {
   private _data: T | null = null
@@ -83,24 +92,33 @@ export abstract class CachedStore<T> {
   private _projectId: string | null = null
 
   /**
-   * Get the filename for this store (e.g., 'patterns.json', 'memories.json')
+   * Return the filename for this store (e.g., `'patterns.json'`).
+   * @returns The JSON filename used for disk persistence
    */
   protected abstract getFilename(): string
 
   /**
-   * Get default data structure when file doesn't exist
+   * Return the default data structure when the file does not exist on disk.
+   * @returns A fresh default instance of `T`
    */
   protected abstract getDefault(): T
 
   /**
-   * Optional: subdirectory within memory folder
+   * Optional subdirectory within the project's `memory/` folder.
+   * Override to nest the store file under a subfolder.
+   *
+   * @returns Subdirectory name, or `null` to store directly in `memory/`
    */
   protected getSubdirectory(): string | null {
     return null
   }
 
   /**
-   * Get full path for the store file
+   * Build the full filesystem path for this store's JSON file.
+   *
+   * @param projectId - The project identifier used for path resolution
+   * @returns Absolute path to the store file
+   *   (e.g., `~/.prjct-cli/projects/{id}/memory/patterns.json`)
    */
   protected getPath(projectId: string): string {
     const basePath = path.join(pathManager.getGlobalProjectPath(projectId), 'memory')
@@ -114,8 +132,20 @@ export abstract class CachedStore<T> {
   }
 
   /**
-   * Load data from disk (with caching)
-   * Returns cached data if same project and already loaded
+   * Load data from disk with project-scoped caching.
+   *
+   * Returns cached data immediately if already loaded for the same project.
+   * Otherwise reads from disk, falling back to {@link getDefault} when the
+   * file does not exist. Calls {@link afterLoad} after a successful disk read.
+   *
+   * @param projectId - The project identifier
+   * @returns The loaded (or cached) data
+   * @throws {Error} If the file read fails for reasons other than ENOENT
+   *
+   * @example
+   * ```ts
+   * const patterns = await patternStore.load('my-project-id')
+   * ```
    */
   async load(projectId: string): Promise<T> {
     // Return cached if same project and loaded
@@ -146,15 +176,25 @@ export abstract class CachedStore<T> {
   }
 
   /**
-   * Hook for subclasses to normalize data after loading
-   * E.g., ensuring all index keys exist
+   * Hook for subclasses to normalize or migrate data after loading from disk.
+   *
+   * Called once per disk read (not on cache hits). Override to ensure
+   * structural invariants — e.g., adding missing index keys.
+   *
+   * @param _data - The freshly loaded data to normalize (mutate in place)
    */
   protected afterLoad(_data: T): void {
     // Override in subclass if needed
   }
 
   /**
-   * Save data to disk
+   * Persist the current in-memory data to disk.
+   *
+   * Creates parent directories automatically if they don't exist.
+   * No-op if no data has been loaded yet.
+   *
+   * @param projectId - The project identifier for path resolution
+   * @throws {Error} If the file write fails
    */
   async save(projectId: string): Promise<void> {
     if (!this._data) return
@@ -165,21 +205,39 @@ export abstract class CachedStore<T> {
   }
 
   /**
-   * Get cached data without loading (may be null)
+   * Access the cached data without triggering a disk read.
+   *
+   * @returns The cached data, or `null` if nothing has been loaded
    */
   protected getData(): T | null {
     return this._data
   }
 
   /**
-   * Set data directly (for subclass modifications)
+   * Replace the in-memory data directly. Does not persist to disk —
+   * call {@link save} afterwards if persistence is needed.
+   *
+   * @param data - The new data to cache
    */
   protected setData(data: T): void {
     this._data = data
   }
 
   /**
-   * Update data with a transform function, then save
+   * Atomically load, transform, and save data in one operation.
+   *
+   * @param projectId - The project identifier
+   * @param updater - Pure function that receives current data and returns updated data
+   * @returns The updated data after saving
+   * @throws {Error} If load or save fails
+   *
+   * @example
+   * ```ts
+   * await store.update('my-project', (data) => ({
+   *   ...data,
+   *   count: data.count + 1,
+   * }))
+   * ```
    */
   async update(projectId: string, updater: (data: T) => T): Promise<T> {
     const data = await this.load(projectId)
@@ -190,7 +248,11 @@ export abstract class CachedStore<T> {
   }
 
   /**
-   * Check if data has been loaded for a project
+   * Check whether data has been loaded into the cache.
+   *
+   * @param projectId - If provided, checks that data is loaded for this specific project.
+   *   If omitted, returns `true` if any project's data is cached.
+   * @returns `true` if data is loaded (and matches the project, when specified)
    */
   isLoaded(projectId?: string): boolean {
     if (projectId) {
@@ -200,7 +262,8 @@ export abstract class CachedStore<T> {
   }
 
   /**
-   * Reset cache (forces reload on next access)
+   * Clear the in-memory cache, forcing a fresh disk read on the next {@link load} call.
+   * Does not delete or modify the file on disk.
    */
   reset(): void {
     this._data = null

package/core/agentic/services.ts

@@ -12,7 +12,7 @@
  * import { services } from './services'
  *
  * // Instead of:
- * import templateLoader from './template-loader'
+ * import * as templateLoader from './template-loader'
  * import contextBuilder from './context-builder'
  * // ... 12 more imports
  *

package/core/agentic/template-executor.ts

@@ -208,11 +208,11 @@ You are executing a prjct command as ${context.agentName}. Follow the template-f
      b) What technologies exist in this project
      c) What agents are available in ${context.paths.agentsDir}
 
-   - **IMPORTANTE**: Los agentes en ${context.paths.agentsDir} YA son específicos del proyecto
-     (fueron generados durante p. sync con las tecnologías reales)
+   - **IMPORTANT**: The agents in ${context.paths.agentsDir} are already project-specific
+     (they were generated during p. sync with the actual project technologies)
 
-   - SIEMPRE usar el especialista si existe para el dominio
-   - Solo usar generalista si NO existe agente para ese dominio
+   - ALWAYS use the specialist if one exists for the domain
+   - Only use the generalist if there is NO agent for that domain
 
    - Check if task should be fragmented (read: ${context.paths.taskFragmentation})
    - If agents loaded, check their skills and load from ${context.paths.skillsDir}

package/core/agentic/template-loader.ts

@@ -105,11 +105,5 @@ export function clearCache(): void {
   cacheOrder.length = 0
 }
 
-// ============ Default Export (backwards compat) ============
-
-export default {
-  load,
-  parseFrontmatter,
-  getAllowedTools,
-  clearCache,
-}
+const templateLoader = { load, parseFrontmatter, getAllowedTools, clearCache }
+export default templateLoader

package/core/bus/bus.ts

@@ -288,4 +288,3 @@ const emit = {
 }
 
 export { EventBus, eventBus, emit }
-export default { EventBus, EventTypes, eventBus, emit }

package/core/bus/index.ts

@@ -5,4 +5,4 @@
  */
 
 export { type BusEventType, type EventCallback, type EventData, EventTypes } from '../types'
-export { default, EventBus, emit, eventBus } from './bus'
+export { EventBus, emit, eventBus } from './bus'

package/core/cli/start.ts

@@ -384,5 +384,3 @@ export async function runStart(): Promise<void> {
   // Show completion
   showCompletion(selectedProviders)
 }
-
-export default { runStart }

package/core/commands/base.ts

@@ -20,9 +20,9 @@ import type {
   CommandResult,
   ProjectContext,
 } from '../types'
-import dateHelper from '../utils/date-helper'
+import * as dateHelper from '../utils/date-helper'
 import * as fileHelper from '../utils/file-helper'
-import jsonlHelper from '../utils/jsonl-helper'
+import * as jsonlHelper from '../utils/jsonl-helper'
 import out from '../utils/output'
 
 /**

package/core/commands/planning.ts

@@ -4,7 +4,7 @@
  */
 
 import path from 'node:path'
-import authorDetector from '../infrastructure/author-detector'
+import * as authorDetector from '../infrastructure/author-detector'
 import commandInstaller from '../infrastructure/command-installer'
 import { generateUUID } from '../schemas'
 import type { Priority, TaskSection, TaskType } from '../schemas/state'

package/core/constants/index.ts

@@ -323,6 +323,25 @@ export const EVENT_LIMITS = {
   HISTORY_MAX: 100,
 } as const
 
+// =============================================================================
+// Workflow Help Strings (user-facing, no magic strings)
+// =============================================================================
+
+/**
+ * Example commands shown in workflow preferences help.
+ * Keeps UI copy in English and centralized.
+ */
+export const WORKFLOW_HELP = {
+  /** Message when no workflow preferences are configured */
+  NO_PREFERENCES: 'No workflow preferences configured.',
+  /** Example: set a before-ship hook to run tests */
+  SET_EXAMPLE: 'p. workflow before ship run the tests',
+  /** Example: modify workflow to run npm test */
+  MODIFY_EXAMPLE: 'p. workflow before ship run npm test',
+  /** Example: remove the ship hook */
+  REMOVE_EXAMPLE: 'p. workflow remove the ship hook',
+} as const
+
 // =============================================================================
 // Combined Exports
 // =============================================================================

package/core/context/generator.ts

@@ -366,5 +366,3 @@ async function generateSummaryMd(
 
   await fs.writeFile(path.join(contextPath, 'summary.md'), content, 'utf-8')
 }
-
-export default { generateContext }

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

@@ -575,9 +575,3 @@ function isTestFile(filePath: string): boolean {
     lower.endsWith('_test.py')
   )
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default { findRelevantFiles }

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

@@ -395,9 +395,3 @@ async function buildDependencyTree(
 
   return node
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default { analyzeImports }

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

@@ -299,9 +299,3 @@ function shouldIgnore(filePath: string): boolean {
 
   return false
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default { getRecentFiles }

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

@@ -493,9 +493,3 @@ function cleanSignature(signature: string): string {
     .replace(/\s+/g, ' ') // Normalize whitespace
     .trim()
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default { extractSignatures, extractDirectorySignatures }

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

@@ -299,9 +299,3 @@ function buildSummaryText(
 
   return parts.join('\n')
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default { summarizeFile, summarizeDirectory }

package/core/context-tools/token-counter.ts

@@ -271,16 +271,3 @@ export function formatCompressionRate(rate: number): string {
 // =============================================================================
 
 export { formatCostSaved }
-
-export default {
-  countTokens,
-  measureCompression,
-  noCompression,
-  combineMetrics,
-  formatTokenCount,
-  formatCompressionRate,
-  formatCostSaved,
-  CHARS_PER_TOKEN,
-  MODEL_PRICING,
-  DEFAULT_MODEL,
-}

package/core/infrastructure/agent-detector.ts

@@ -133,16 +133,3 @@ export async function isClaude(): Promise<boolean> {
 export async function isTerminal(): Promise<boolean> {
   return !(await isClaude())
 }
-
-// ============ Default Export (backwards compat) ============
-
-export default {
-  detect,
-  isClaudeEnvironment,
-  getClaudeAgent,
-  getTerminalAgent,
-  setAgent,
-  reset,
-  isClaude,
-  isTerminal,
-}

package/core/infrastructure/ai-provider.ts

@@ -529,32 +529,3 @@ export async function selectProvider(): Promise<ProviderSelectionResult> {
     detection,
   }
 }
-
-// =============================================================================
-// Exports
-// =============================================================================
-
-export default {
-  Providers,
-  ClaudeProvider,
-  GeminiProvider,
-  CursorProvider,
-  AntigravityProvider,
-  WindsurfProvider,
-  detectProvider,
-  detectAllProviders,
-  detectAntigravity,
-  getActiveProvider,
-  hasProviderConfig,
-  getProviderBranding,
-  getGlobalContextPath,
-  getGlobalSettingsPath,
-  getSkillsPath,
-  getCommandsDir,
-  getProjectCommandsPath,
-  selectProvider,
-  detectCursorProject,
-  needsCursorRouterRegeneration,
-  detectWindsurfProject,
-  needsWindsurfRouterRegeneration,
-}

package/core/infrastructure/author-detector.ts

@@ -131,17 +131,3 @@ export function formatAuthor(author: DetectedAuthorInfo): string {
 
   return parts.join(' ') || 'Unknown'
 }
-
-// ============ Default Export (backwards compat) ============
-
-export default {
-  detect,
-  detectAuthorForLogs,
-  detectGitHubUsername,
-  detectGitName,
-  detectGitEmail,
-  isGitHubCLIAvailable,
-  isGitConfigured,
-  getConfigStatus,
-  formatAuthor,
-}

package/core/infrastructure/config-manager.ts

@@ -18,7 +18,7 @@ import type { Author, GlobalConfig, LocalConfig } from '../types'
 import { isNotFoundError } from '../types/fs'
 import { getTimestamp } from '../utils/date-helper'
 import { VERSION } from '../utils/version'
-import authorDetector from './author-detector'
+import * as authorDetector from './author-detector'
 import pathManager from './path-manager'
 
 // Re-export types for convenience

package/core/infrastructure/setup.ts

@@ -249,9 +249,6 @@ export async function run(): Promise<SetupResults> {
   return results
 }
 
-// Default export for CommonJS require
-export default { run }
-
 /**
  * Install the p.toml router for Gemini CLI
  */

package/core/plugin/hooks.ts

@@ -313,5 +313,3 @@ const hooks = {
 }
 
 export { HookSystem, HookPoints, hookSystem, hooks }
-
-export default { HookSystem, HookPoints, hookSystem, hooks }