prjct-cli 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.53.0] - 2026-01-30
+
+### Features
+
+- Lazy template loading with TTL cache - PRJ-76 (#79)
+
+
+## [0.53.0] - 2026-01-30
+
+### Features
+
+- Lazy template loading with TTL cache - PRJ-76
+
+
+## [0.53.0] - 2026-01-30
+
+### Added
+
+- **Lazy template loading with TTL cache** (PRJ-76)
+  - Templates now loaded on-demand with 60-second TTL cache
+  - Added `getTemplate()` method with per-file caching
+  - `loadChecklists()` and `loadChecklistRouting()` now use TTL cache
+  - Added `clearTemplateCache()` method for testing/forced refresh
+  - Reduces disk I/O for frequently accessed templates
+
+
 ## [0.52.0] - 2026-01-30
 
 ### Features

package/core/agentic/prompt-builder.ts

@@ -43,17 +43,73 @@ type Agent = PromptAgent
 type Context = PromptContext
 type State = PromptState
 
+/**
+ * Cached template entry with TTL support
+ * @see PRJ-76
+ */
+interface CachedTemplate {
+  content: string
+  loadedAt: number
+}
+
 /**
  * Builds prompts for Claude using templates, context, and learned patterns.
  * Supports plan mode, think blocks, and quality checklists.
  * Auto-injects unified state and performance insights.
+ *
+ * Uses lazy loading for templates with 60s TTL cache.
+ * @see PRJ-76
  */
 class PromptBuilder {
   private _checklistsCache: Record<string, string> | null = null
+  private _checklistsCacheTime: number = 0
   private _checklistRoutingCache: string | null = null
+  private _checklistRoutingCacheTime: number = 0
   private _currentContext: Context | null = null
   private _stateCache: Map<string, { state: ProjectState; timestamp: number }> = new Map()
   private _stateCacheTTL = 5000 // 5 seconds
+  private _templateCache: Map<string, CachedTemplate> = new Map()
+  private readonly TEMPLATE_CACHE_TTL_MS = 60_000 // 60 seconds
+
+  /**
+   * Get a template with TTL caching.
+   * Returns cached content if within TTL, otherwise loads from disk.
+   * @see PRJ-76
+   */
+  getTemplate(templatePath: string): string | null {
+    const cached = this._templateCache.get(templatePath)
+    const now = Date.now()
+
+    if (cached && now - cached.loadedAt < this.TEMPLATE_CACHE_TTL_MS) {
+      return cached.content
+    }
+
+    try {
+      if (fs.existsSync(templatePath)) {
+        const content = fs.readFileSync(templatePath, 'utf-8')
+        this._templateCache.set(templatePath, { content, loadedAt: now })
+        return content
+      }
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        console.error(`Template loading warning: ${(error as Error).message}`)
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Clear the template cache (for testing or forced refresh)
+   * @see PRJ-76
+   */
+  clearTemplateCache(): void {
+    this._templateCache.clear()
+    this._checklistsCache = null
+    this._checklistsCacheTime = 0
+    this._checklistRoutingCache = null
+    this._checklistRoutingCacheTime = 0
+  }
 
   /**
    * Reset context (for testing)
@@ -71,9 +127,16 @@ class PromptBuilder {
 
   /**
    * Load quality checklists from templates/checklists/
+   * Uses lazy loading with TTL cache.
+   * @see PRJ-76
    */
   loadChecklists(): Record<string, string> {
-    if (this._checklistsCache) return this._checklistsCache
+    const now = Date.now()
+
+    // Check if cache is still valid
+    if (this._checklistsCache && now - this._checklistsCacheTime < this.TEMPLATE_CACHE_TTL_MS) {
+      return this._checklistsCache
+    }
 
     const checklistsDir = path.join(__dirname, '..', '..', 'templates', 'checklists')
     const checklists: Record<string, string> = {}
@@ -83,8 +146,12 @@ class PromptBuilder {
         const files = fs.readdirSync(checklistsDir).filter((f) => f.endsWith('.md'))
         for (const file of files) {
           const name = file.replace('.md', '')
-          const content = fs.readFileSync(path.join(checklistsDir, file), 'utf-8')
-          checklists[name] = content
+          const templatePath = path.join(checklistsDir, file)
+          // Use getTemplate for individual files to leverage per-file caching
+          const content = this.getTemplate(templatePath)
+          if (content) {
+            checklists[name] = content
+          }
         }
       }
     } catch (error) {
@@ -95,6 +162,7 @@ class PromptBuilder {
     }
 
     this._checklistsCache = checklists
+    this._checklistsCacheTime = now
     return checklists
   }
 
@@ -215,9 +283,19 @@ class PromptBuilder {
 
   /**
    * Load checklist routing template for Claude to decide which checklists apply
+   * Uses lazy loading with TTL cache.
+   * @see PRJ-76
    */
   loadChecklistRouting(): string | null {
-    if (this._checklistRoutingCache) return this._checklistRoutingCache
+    const now = Date.now()
+
+    // Check if cache is still valid
+    if (
+      this._checklistRoutingCache &&
+      now - this._checklistRoutingCacheTime < this.TEMPLATE_CACHE_TTL_MS
+    ) {
+      return this._checklistRoutingCache
+    }
 
     const routingPath = path.join(
       __dirname,
@@ -228,15 +306,11 @@ class PromptBuilder {
       'checklist-routing.md'
     )
 
-    try {
-      if (fs.existsSync(routingPath)) {
-        this._checklistRoutingCache = fs.readFileSync(routingPath, 'utf-8')
-      }
-    } catch (error) {
-      // Silent fail - checklist routing is optional
-      if (!isNotFoundError(error)) {
-        console.error(`Checklist routing warning: ${(error as Error).message}`)
-      }
+    // Use getTemplate for consistent caching behavior
+    const content = this.getTemplate(routingPath)
+    if (content) {
+      this._checklistRoutingCache = content
+      this._checklistRoutingCacheTime = now
     }
 
     return this._checklistRoutingCache || null

package/dist/bin/prjct.mjs

@@ -12332,11 +12332,51 @@ var init_prompt_builder = __esm({
         __name(this, "PromptBuilder");
       }
       _checklistsCache = null;
+      _checklistsCacheTime = 0;
       _checklistRoutingCache = null;
+      _checklistRoutingCacheTime = 0;
       _currentContext = null;
       _stateCache = /* @__PURE__ */ new Map();
       _stateCacheTTL = 5e3;
       // 5 seconds
+      _templateCache = /* @__PURE__ */ new Map();
+      TEMPLATE_CACHE_TTL_MS = 6e4;
+      // 60 seconds
+      /**
+       * Get a template with TTL caching.
+       * Returns cached content if within TTL, otherwise loads from disk.
+       * @see PRJ-76
+       */
+      getTemplate(templatePath) {
+        const cached = this._templateCache.get(templatePath);
+        const now = Date.now();
+        if (cached && now - cached.loadedAt < this.TEMPLATE_CACHE_TTL_MS) {
+          return cached.content;
+        }
+        try {
+          if (fs25.existsSync(templatePath)) {
+            const content = fs25.readFileSync(templatePath, "utf-8");
+            this._templateCache.set(templatePath, { content, loadedAt: now });
+            return content;
+          }
+        } catch (error) {
+          if (!isNotFoundError(error)) {
+            console.error(`Template loading warning: ${error.message}`);
+          }
+        }
+        return null;
+      }
+      /**
+       * Clear the template cache (for testing or forced refresh)
+       * @see PRJ-76
+       */
+      clearTemplateCache() {
+        this._templateCache.clear();
+        this._checklistsCache = null;
+        this._checklistsCacheTime = 0;
+        this._checklistRoutingCache = null;
+        this._checklistRoutingCacheTime = 0;
+      }
       /**
        * Reset context (for testing)
        */
@@ -12351,9 +12391,14 @@ var init_prompt_builder = __esm({
       }
       /**
        * Load quality checklists from templates/checklists/
+       * Uses lazy loading with TTL cache.
+       * @see PRJ-76
        */
       loadChecklists() {
-        if (this._checklistsCache) return this._checklistsCache;
+        const now = Date.now();
+        if (this._checklistsCache && now - this._checklistsCacheTime < this.TEMPLATE_CACHE_TTL_MS) {
+          return this._checklistsCache;
+        }
         const checklistsDir = path25.join(__dirname, "..", "..", "templates", "checklists");
         const checklists = {};
         try {
@@ -12361,8 +12406,11 @@ var init_prompt_builder = __esm({
             const files = fs25.readdirSync(checklistsDir).filter((f) => f.endsWith(".md"));
             for (const file of files) {
               const name = file.replace(".md", "");
-              const content = fs25.readFileSync(path25.join(checklistsDir, file), "utf-8");
-              checklists[name] = content;
+              const templatePath = path25.join(checklistsDir, file);
+              const content = this.getTemplate(templatePath);
+              if (content) {
+                checklists[name] = content;
+              }
             }
           }
         } catch (error) {
@@ -12371,6 +12419,7 @@ var init_prompt_builder = __esm({
           }
         }
         this._checklistsCache = checklists;
+        this._checklistsCacheTime = now;
         return checklists;
       }
       /**
@@ -12468,9 +12517,14 @@ var init_prompt_builder = __esm({
       }
       /**
        * Load checklist routing template for Claude to decide which checklists apply
+       * Uses lazy loading with TTL cache.
+       * @see PRJ-76
        */
       loadChecklistRouting() {
-        if (this._checklistRoutingCache) return this._checklistRoutingCache;
+        const now = Date.now();
+        if (this._checklistRoutingCache && now - this._checklistRoutingCacheTime < this.TEMPLATE_CACHE_TTL_MS) {
+          return this._checklistRoutingCache;
+        }
         const routingPath = path25.join(
           __dirname,
           "..",
@@ -12479,14 +12533,10 @@ var init_prompt_builder = __esm({
           "agentic",
           "checklist-routing.md"
         );
-        try {
-          if (fs25.existsSync(routingPath)) {
-            this._checklistRoutingCache = fs25.readFileSync(routingPath, "utf-8");
-          }
-        } catch (error) {
-          if (!isNotFoundError(error)) {
-            console.error(`Checklist routing warning: ${error.message}`);
-          }
+        const content = this.getTemplate(routingPath);
+        if (content) {
+          this._checklistRoutingCache = content;
+          this._checklistRoutingCacheTime = now;
         }
         return this._checklistRoutingCache || null;
       }
@@ -24664,7 +24714,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.52.0",
+      version: "0.53.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {