prjct-cli 1.22.0 → 1.24.0

package/core/agentic/template-executor.ts

@@ -1,272 +0,0 @@
-/**
- * Template Executor
- *
- * Executes templates as the entry point for agentic command execution.
- * TypeScript provides infrastructure (paths, reads/writes).
- * Claude takes all agentic decisions via templates.
- *
- * @module agentic/template-executor
- * @version 1.0.0
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import configManager from '../infrastructure/config-manager'
-import pathManager from '../infrastructure/path-manager'
-import { isNotFoundError } from '../types/fs'
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface TemplateExecutionContext {
-  projectPath: string
-  projectId: string
-  globalPath: string
-  command: string
-  args: string
-
-  // Agent information
-  agentName: string
-  agentSettingsPath: string
-
-  // Paths for agent (not content)
-  paths: {
-    orchestrator: string
-    agentRouting: string
-    taskFragmentation: string
-    commandTemplate: string
-    repoAnalysis: string
-    agentsDir: string
-    skillsDir: string
-    stateJson: string
-  }
-}
-
-export interface AgenticPromptInfo {
-  prompt: string
-  context: TemplateExecutionContext
-  requiresOrchestration: boolean
-}
-
-// Commands that require orchestration (task routing, fragmentation)
-const ORCHESTRATED_COMMANDS = ['task', 'done', 'ship', 'resume', 'bug', 'enrich']
-
-// Commands that do NOT need orchestration
-const SIMPLE_COMMANDS = ['init', 'sync', 'pause', 'next', 'dash', 'history', 'undo', 'redo']
-
-// =============================================================================
-// Template Executor Class
-// =============================================================================
-
-export class TemplateExecutor {
-  /**
-   * Get npm root for templates path
-   */
-  private async getNpmRoot(): Promise<string> {
-    // Get the templates path relative to this module
-    // In production, templates are in the npm package
-    const moduleDir = path.dirname(require.resolve('prjct-cli/package.json'))
-    return moduleDir
-  }
-
-  /**
-   * Get project ID from local config
-   */
-  private async getProjectId(projectPath: string): Promise<string> {
-    return configManager.getProjectId(projectPath)
-  }
-
-  /**
-   * Build execution context with paths only
-   * Claude reads files agentically - we don't inject content
-   */
-  async buildContext(
-    command: string,
-    args: string,
-    projectPath: string
-  ): Promise<TemplateExecutionContext> {
-    const projectId = await this.getProjectId(projectPath)
-    const globalPath = pathManager.getGlobalProjectPath(projectId)
-    const aiProvider = require('../infrastructure/ai-provider')
-    const activeProvider = await aiProvider.getActiveProvider()
-
-    // Get templates directory - use local path during development
-    let templatesDir: string
-    try {
-      const npmRoot = await this.getNpmRoot()
-      templatesDir = path.join(npmRoot, 'templates')
-    } catch {
-      // Fallback to local templates during development
-      templatesDir = path.join(__dirname, '..', '..', 'templates')
-    }
-
-    return {
-      projectPath,
-      projectId,
-      globalPath,
-      command,
-      args,
-      agentName: activeProvider.displayName,
-      agentSettingsPath: await pathManager.getAgentSettingsPath(),
-      paths: {
-        orchestrator: path.join(templatesDir, 'agentic', 'orchestrator.md'),
-        agentRouting: path.join(templatesDir, 'agentic', 'agent-routing.md'),
-        taskFragmentation: path.join(templatesDir, 'agentic', 'task-fragmentation.md'),
-        commandTemplate: path.join(templatesDir, 'commands', `${command}.md`),
-        repoAnalysis: path.join(globalPath, 'analysis', 'repo-analysis.json'),
-        agentsDir: path.join(globalPath, 'agents'),
-        skillsDir: activeProvider.skillsDir,
-        stateJson: path.join(globalPath, 'storage', 'state.json'),
-      },
-    }
-  }
-
-  /**
-   * Check if a command requires orchestration
-   */
-  requiresOrchestration(command: string): boolean {
-    if (ORCHESTRATED_COMMANDS.includes(command)) return true
-    if (SIMPLE_COMMANDS.includes(command)) return false
-    // Default: assume orchestration needed for unknown commands
-    return true
-  }
-
-  /**
-   * Check if agents exist for the project
-   */
-  async hasAgents(projectPath: string): Promise<boolean> {
-    try {
-      const projectId = await this.getProjectId(projectPath)
-      const agentsDir = path.join(pathManager.getGlobalProjectPath(projectId), 'agents')
-      const files = await fs.readdir(agentsDir)
-      return files.some((f) => f.endsWith('.md'))
-    } catch (error) {
-      if (isNotFoundError(error)) return false
-      return false
-    }
-  }
-
-  /**
-   * Get list of available agent names
-   */
-  async getAvailableAgents(projectPath: string): Promise<string[]> {
-    try {
-      const projectId = await this.getProjectId(projectPath)
-      const agentsDir = path.join(pathManager.getGlobalProjectPath(projectId), 'agents')
-      const files = await fs.readdir(agentsDir)
-      return files.filter((f) => f.endsWith('.md')).map((f) => f.replace('.md', ''))
-    } catch {
-      return []
-    }
-  }
-
-  /**
-   * Build prompt that tells agent to execute templates agentically
-   */
-  buildAgenticPrompt(context: TemplateExecutionContext): AgenticPromptInfo {
-    const requiresOrchestration = this.requiresOrchestration(context.command)
-
-    const prompt = `
-## Agentic Execution Mode
-
-You are executing a prjct command as ${context.agentName}. Follow the template-first approach.
-
-### Context
-- Agent: ${context.agentName}
-- Settings: ${context.agentSettingsPath}
-- Command: ${context.command}
-- Args: ${context.args}
-- Project: ${context.projectPath}
-- Project ID: ${context.projectId}
-
-### Paths (Read as needed)
-- Orchestrator: ${context.paths.orchestrator}
-- Agent Routing: ${context.paths.agentRouting}
-- Task Fragmentation: ${context.paths.taskFragmentation}
-- Command Template: ${context.paths.commandTemplate}
-- Repo Analysis: ${context.paths.repoAnalysis}
-- Agents Directory: ${context.paths.agentsDir}
-- Skills Directory: ${context.paths.skillsDir}
-- State JSON: ${context.paths.stateJson}
-
-### Instructions
-
-1. **Read the command template** (${context.paths.commandTemplate})
-
-2. **Check if orchestration is needed**
-   - This command ${requiresOrchestration ? 'REQUIRES' : 'does NOT require'} orchestration
-   ${
-     requiresOrchestration
-       ? `
-3. **Orchestration steps:**
-   - Read: ${context.paths.orchestrator}
-   - Read: ${context.paths.repoAnalysis} to understand project technologies
-   - Analyze the task: "${context.args}"
-   - Determine which domains are ACTUALLY relevant based on:
-     a) What the task requires
-     b) What technologies exist in this project
-     c) What agents are available in ${context.paths.agentsDir}
-
-   - **IMPORTANT**: The agents in ${context.paths.agentsDir} are already project-specific
-     (they were generated during p. sync with the actual project technologies)
-
-   - 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}
-`
-       : `
-3. **Simple execution:**
-   - Execute the command template directly
-   - No agent routing needed
-`
-   }
-
-4. **Execute the command template** with full context
-
-5. **Return results**
-
-### Agentic Decision Making
-
-YOU decide:
-- Whether to run orchestration (based on command type)
-- Which domains the task involves (frontend, backend, database, etc.)
-- Whether to fragment the task into subtasks
-- Which specialist agents to delegate to
-
-ALWAYS:
-- Use specialist agents when they exist (they're already project-specific)
-- Delegate subtasks to the appropriate specialist via Task tool
-- Let specialists handle their domain (they have the project patterns)
-- Generate and store summaries when subtasks complete
-
-ONLY use generalist when:
-- No specialist agent exists for that domain
-- Task is completely outside project scope
-- Extreme edge case
-
-### Subtask Management
-
-When fragmenting tasks:
-1. Store subtasks in state.json under currentTask.subtasks
-2. Track progress: currentSubtaskIndex, subtaskProgress
-3. Each completed subtask generates a summary
-4. Pass summary to next agent for context handoff
-`
-
-    return {
-      prompt,
-      context,
-      requiresOrchestration,
-    }
-  }
-}
-
-// =============================================================================
-// Singleton Export
-// =============================================================================
-
-export const templateExecutor = new TemplateExecutor()
-export default templateExecutor

package/core/agentic/template-loader.ts

@@ -1,109 +0,0 @@
-/**
- * Template Loader
- * Loads and parses command templates with frontmatter.
- *
- * @module agentic/template-loader
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import { TemplateError } from '../errors'
-import type { Frontmatter, ParsedTemplate } from '../types'
-
-// ============ Module State (LRU Cache) ============
-
-const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'commands')
-const MAX_CACHE_SIZE = 50
-
-const cache = new Map<string, ParsedTemplate>()
-const cacheOrder: string[] = []
-
-// ============ Cache Helpers ============
-
-function updateLruOrder(key: string): void {
-  const index = cacheOrder.indexOf(key)
-  if (index > -1) cacheOrder.splice(index, 1)
-  cacheOrder.push(key)
-}
-
-function evictLru(): void {
-  while (cache.size >= MAX_CACHE_SIZE && cacheOrder.length > 0) {
-    const oldest = cacheOrder.shift()
-    if (oldest) cache.delete(oldest)
-  }
-}
-
-// ============ Parsing Functions ============
-
-export function parseFrontmatter(content: string): ParsedTemplate {
-  const frontmatterRegex = /^---\n([\s\S]+?)\n---\n([\s\S]*)$/
-  const match = content.match(frontmatterRegex)
-
-  if (!match) {
-    return { frontmatter: {}, content: content.trim() }
-  }
-
-  const [, frontmatterText, mainContent] = match
-  const frontmatter: Frontmatter = {}
-
-  frontmatterText.split('\n').forEach((line) => {
-    const [key, ...valueParts] = line.split(':')
-    if (key && valueParts.length > 0) {
-      const value = valueParts.join(':').trim()
-
-      // Parse arrays
-      if (value.startsWith('[') && value.endsWith(']')) {
-        frontmatter[key.trim()] = value
-          .slice(1, -1)
-          .split(',')
-          .map((v) => v.trim())
-      } else {
-        // Remove quotes if present
-        frontmatter[key.trim()] = value.replace(/^["']|["']$/g, '')
-      }
-    }
-  })
-
-  return { frontmatter, content: mainContent.trim() }
-}
-
-// ============ Main Functions ============
-
-export async function load(commandName: string): Promise<ParsedTemplate> {
-  // Check cache first
-  if (cache.has(commandName)) {
-    updateLruOrder(commandName)
-    return cache.get(commandName)!
-  }
-
-  const templatePath = path.join(TEMPLATES_DIR, `${commandName}.md`)
-
-  try {
-    const rawContent = await fs.readFile(templatePath, 'utf-8')
-    const parsed = parseFrontmatter(rawContent)
-
-    // Evict LRU if needed before adding
-    evictLru()
-
-    // Cache result
-    cache.set(commandName, parsed)
-    cacheOrder.push(commandName)
-
-    return parsed
-  } catch (_error) {
-    throw TemplateError.notFound(commandName)
-  }
-}
-
-export async function getAllowedTools(commandName: string): Promise<string[]> {
-  const template = await load(commandName)
-  return template.frontmatter['allowed-tools'] || []
-}
-
-export function clearCache(): void {
-  cache.clear()
-  cacheOrder.length = 0
-}
-
-const templateLoader = { load, parseFrontmatter, getAllowedTools, clearCache }
-export default templateLoader

package/core/agentic/token-budget.ts

@@ -1,226 +0,0 @@
-/**
- * Token Budget Coordinator
- *
- * Centrally manages the global token budget across all context-loading components.
- * Ensures the combined prompt stays within the model's context window
- * and reserves space for the output.
- *
- * Budget formula: inputBudget = modelContextWindow * 0.65
- * Priority: state (P1) > injection context (P2) > file content (P3)
- *
- * @see PRJ-266
- */
-
-// =============================================================================
-// Model Context Windows
-// =============================================================================
-
-/** Context window sizes by model identifier (in tokens) */
-export const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
-  // Claude models (short names from model.ts)
-  opus: 200_000,
-  sonnet: 200_000,
-  haiku: 200_000,
-  // Gemini models
-  '2.5-pro': 1_000_000,
-  '2.5-flash': 1_000_000,
-  '2.0-flash': 1_000_000,
-  // Full model IDs (for direct API usage)
-  'claude-opus-4.5': 200_000,
-  'claude-sonnet-4.5': 200_000,
-  'claude-haiku-4.5': 200_000,
-  'claude-opus-4-6': 200_000,
-  // Default fallback
-  default: 200_000,
-}
-
-/** Ratio of context window reserved for input (rest for output) */
-export const INPUT_RATIO = 0.65
-
-// =============================================================================
-// Budget Categories
-// =============================================================================
-
-/** Budget category identifiers ordered by priority */
-export type BudgetCategory = 'state' | 'injection' | 'files'
-
-/** Budget allocation result for each category */
-export interface BudgetAllocation {
-  state: number
-  injection: number
-  files: number
-  inputBudget: number
-  outputReserve: number
-  contextWindow: number
-}
-
-/** Usage tracking per category */
-export interface BudgetUsage {
-  category: BudgetCategory
-  allocated: number
-  used: number
-  remaining: number
-}
-
-// =============================================================================
-// Default Allocation Ratios (within input budget)
-// =============================================================================
-
-interface AllocationConfig {
-  ratio: number
-  minimum: number
-}
-
-const ALLOCATION_CONFIG: Record<BudgetCategory, AllocationConfig> = {
-  /** P1: State — current task, queue, patterns (highest priority) */
-  state: { ratio: 0.02, minimum: 1_500 },
-  /** P2: Injection — agents, skills, modules, checklists */
-  injection: { ratio: 0.08, minimum: 8_000 },
-  /** P3: Files — codebase file content (lowest priority, gets remainder) */
-  files: { ratio: 0.9, minimum: 20_000 },
-}
-
-/** Priority order for budget distribution */
-const PRIORITY_ORDER: BudgetCategory[] = ['state', 'injection', 'files']
-
-// =============================================================================
-// TokenBudgetCoordinator
-// =============================================================================
-
-export class TokenBudgetCoordinator {
-  private readonly _contextWindow: number
-  private readonly _inputBudget: number
-  private readonly _outputReserve: number
-  private readonly _allocations: Map<BudgetCategory, number> = new Map()
-  private readonly _used: Map<BudgetCategory, number> = new Map()
-
-  constructor(model?: string) {
-    this._contextWindow = getContextWindow(model)
-    this._inputBudget = Math.floor(this._contextWindow * INPUT_RATIO)
-    this._outputReserve = this._contextWindow - this._inputBudget
-    this.distributeBudget()
-  }
-
-  /** Distribute input budget across categories by priority */
-  private distributeBudget(): void {
-    let remaining = this._inputBudget
-
-    for (const category of PRIORITY_ORDER) {
-      const config = ALLOCATION_CONFIG[category]
-
-      if (category === 'files') {
-        // Lowest priority gets whatever remains
-        this._allocations.set(category, Math.max(remaining, 0))
-      } else {
-        const allocation = Math.max(config.minimum, Math.floor(this._inputBudget * config.ratio))
-        const granted = Math.min(allocation, remaining)
-        this._allocations.set(category, granted)
-        remaining -= granted
-      }
-
-      this._used.set(category, 0)
-    }
-  }
-
-  /** Get the full budget allocation */
-  getAllocation(): BudgetAllocation {
-    return {
-      state: this._allocations.get('state') ?? 0,
-      injection: this._allocations.get('injection') ?? 0,
-      files: this._allocations.get('files') ?? 0,
-      inputBudget: this._inputBudget,
-      outputReserve: this._outputReserve,
-      contextWindow: this._contextWindow,
-    }
-  }
-
-  /**
-   * Request tokens from a category.
-   * Returns actual tokens granted (may be less than requested if budget is exhausted).
-   */
-  request(category: BudgetCategory, requestedTokens: number): number {
-    const allocated = this._allocations.get(category) ?? 0
-    const currentUsed = this._used.get(category) ?? 0
-    const available = Math.max(0, allocated - currentUsed)
-    const granted = Math.min(requestedTokens, available)
-    this._used.set(category, currentUsed + granted)
-    return granted
-  }
-
-  /** Record token usage for a category */
-  record(category: BudgetCategory, tokensUsed: number): void {
-    const current = this._used.get(category) ?? 0
-    this._used.set(category, current + tokensUsed)
-  }
-
-  /** Get usage details for a category */
-  getUsage(category: BudgetCategory): BudgetUsage {
-    const allocated = this._allocations.get(category) ?? 0
-    const used = this._used.get(category) ?? 0
-    return {
-      category,
-      allocated,
-      used,
-      remaining: Math.max(0, allocated - used),
-    }
-  }
-
-  /** Get allocation for a specific category */
-  getAllocationFor(category: BudgetCategory): number {
-    return this._allocations.get(category) ?? 0
-  }
-
-  /** Get total remaining input budget across all categories */
-  get totalRemaining(): number {
-    let totalUsed = 0
-    for (const v of this._used.values()) {
-      totalUsed += v
-    }
-    return Math.max(0, this._inputBudget - totalUsed)
-  }
-
-  /** Check if total usage exceeds input budget */
-  get isOverBudget(): boolean {
-    let totalUsed = 0
-    for (const v of this._used.values()) {
-      totalUsed += v
-    }
-    return totalUsed > this._inputBudget
-  }
-
-  /** Context window size */
-  get contextWindow(): number {
-    return this._contextWindow
-  }
-
-  /** Total input budget */
-  get inputBudget(): number {
-    return this._inputBudget
-  }
-
-  /** Output token reserve */
-  get outputReserve(): number {
-    return this._outputReserve
-  }
-}
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/** Get context window size for a model identifier */
-export function getContextWindow(model?: string): number {
-  if (!model) return MODEL_CONTEXT_WINDOWS.default
-  return MODEL_CONTEXT_WINDOWS[model] ?? MODEL_CONTEXT_WINDOWS.default
-}
-
-/** Calculate input budget for a model */
-export function calculateInputBudget(model?: string): number {
-  return Math.floor(getContextWindow(model) * INPUT_RATIO)
-}
-
-/** Calculate output reserve for a model */
-export function calculateOutputReserve(model?: string): number {
-  const contextWindow = getContextWindow(model)
-  return contextWindow - Math.floor(contextWindow * INPUT_RATIO)
-}