prjct-cli 0.20.0 → 0.20.1

package/core/infrastructure/path-manager.ts

@@ -15,14 +15,7 @@ import crypto from 'crypto'
 import os from 'os'
 import * as dateHelper from '../utils/date-helper'
 import * as fileHelper from '../utils/file-helper'
-
-interface SessionInfo {
-  year: string
-  month: string
-  day: string
-  path: string
-  date: Date
-}
+import type { SessionInfo } from '../types'
 
 class PathManager {
   globalBaseDir: string
@@ -30,7 +23,21 @@ class PathManager {
   globalConfigDir: string
 
   constructor() {
-    this.globalBaseDir = path.join(os.homedir(), '.prjct-cli')
+    const envOverride = process.env.PRJCT_CLI_HOME?.trim()
+    this.globalBaseDir = envOverride ? path.resolve(envOverride) : path.join(os.homedir(), '.prjct-cli')
+    this.globalProjectsDir = path.join(this.globalBaseDir, 'projects')
+    this.globalConfigDir = path.join(this.globalBaseDir, 'config')
+  }
+
+  /**
+   * Override global storage location (primarily for tests and sandboxed environments).
+   *
+   * When unset, global storage defaults to `~/.prjct-cli/`.
+   *
+   * @param {string} globalBaseDir - Base directory that will contain `projects/` and `config/`.
+   */
+  setGlobalBaseDir(globalBaseDir: string): void {
+    this.globalBaseDir = path.resolve(globalBaseDir)
     this.globalProjectsDir = path.join(this.globalBaseDir, 'projects')
     this.globalConfigDir = path.join(this.globalBaseDir, 'config')
   }
@@ -274,6 +281,49 @@ class PathManager {
   getLastSyncPath(projectId: string): string {
     return path.join(this.getGlobalProjectPath(projectId), 'sync', 'last-sync.json')
   }
+
+  /**
+   * Get the running status file path (for status signal)
+   * Used to indicate when prjct CLI is actively running
+   */
+  getRunningStatusPath(): string {
+    return path.join(this.globalBaseDir, '.running')
+  }
+
+  /**
+   * Get the docs directory path
+   * Contains documentation and help files
+   */
+  getDocsPath(): string {
+    return path.join(this.globalBaseDir, 'docs')
+  }
+
+  /**
+   * Get the agents directory path for a project
+   * If projectId is null, returns the global agents directory
+   */
+  getAgentsPath(projectId: string | null): string {
+    if (projectId) {
+      return path.join(this.getGlobalProjectPath(projectId), 'agents')
+    }
+    return path.join(this.globalBaseDir, 'agents')
+  }
+
+  /**
+   * Get the storage file path for a project
+   * Convenience method for accessing storage layer files
+   */
+  getStoragePath(projectId: string, filename: string): string {
+    return path.join(this.getGlobalProjectPath(projectId), 'storage', filename)
+  }
+
+  /**
+   * Get the context directory path for a project
+   * Contains generated markdown context files
+   */
+  getContextPath(projectId: string): string {
+    return path.join(this.getGlobalProjectPath(projectId), 'context')
+  }
 }
 
 const pathManager = new PathManager()

package/core/infrastructure/permission-manager.ts

@@ -0,0 +1,286 @@
+/**
+ * PermissionManager - Granular permission control for CLI operations
+ *
+ * Implements glob-based permission matching inspired by opencode.
+ * Checks bash commands, file operations, and web access against
+ * configurable permission rules.
+ *
+ * @version 1.0.0
+ */
+
+import {
+  type PermissionsConfig,
+  type PermissionLevel,
+  buildDefaultPermissions,
+} from '../schemas/permissions'
+import type { PermissionCheckResult } from '../types'
+
+/**
+ * Simple glob pattern matching
+ * Supports * (any chars) and ? (single char)
+ */
+function matchGlobPattern(pattern: string, text: string): boolean {
+  // Escape regex special chars except * and ?
+  const regexPattern = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+
+  const regex = new RegExp(`^${regexPattern}$`, 'i')
+  return regex.test(text)
+}
+
+/**
+ * Find the most specific matching pattern
+ * More specific = longer pattern without wildcards
+ */
+function findBestMatch(
+  patterns: Record<string, PermissionLevel>,
+  text: string
+): { pattern: string; level: PermissionLevel } | null {
+  let bestMatch: { pattern: string; level: PermissionLevel; specificity: number } | null = null
+
+  for (const [pattern, level] of Object.entries(patterns)) {
+    if (matchGlobPattern(pattern, text)) {
+      // Calculate specificity: longer patterns without wildcards are more specific
+      const wildcardCount = (pattern.match(/\*/g) || []).length
+      const specificity = pattern.length - wildcardCount * 10
+
+      if (!bestMatch || specificity > bestMatch.specificity) {
+        bestMatch = { pattern, level, specificity }
+      }
+    }
+  }
+
+  return bestMatch ? { pattern: bestMatch.pattern, level: bestMatch.level } : null
+}
+
+class PermissionManager {
+  private config: PermissionsConfig
+
+  constructor(config?: PermissionsConfig) {
+    this.config = config || buildDefaultPermissions()
+  }
+
+  /**
+   * Update the permissions configuration
+   */
+  setConfig(config: PermissionsConfig): void {
+    this.config = config
+  }
+
+  /**
+   * Merge custom permissions with defaults
+   */
+  mergeWithDefaults(custom: Partial<PermissionsConfig>): PermissionsConfig {
+    const defaults = buildDefaultPermissions()
+    return {
+      ...defaults,
+      ...custom,
+      bash: { ...defaults.bash, ...custom.bash },
+      files: {
+        read: { ...defaults.files?.read, ...custom.files?.read },
+        write: { ...defaults.files?.write, ...custom.files?.write },
+        delete: { ...defaults.files?.delete, ...custom.files?.delete },
+      },
+      web: {
+        enabled: custom.web?.enabled ?? defaults.web?.enabled ?? true,
+        allowedDomains: custom.web?.allowedDomains ?? defaults.web?.allowedDomains,
+        blockedDomains: custom.web?.blockedDomains ?? defaults.web?.blockedDomains,
+      },
+      doomLoop: {
+        enabled: custom.doomLoop?.enabled ?? defaults.doomLoop?.enabled ?? true,
+        maxRetries: custom.doomLoop?.maxRetries ?? defaults.doomLoop?.maxRetries ?? 3,
+      },
+    }
+  }
+
+  /**
+   * Check if a bash command is allowed
+   */
+  checkBashCommand(command: string): PermissionCheckResult {
+    if (!this.config.bash) {
+      return { allowed: true, level: 'allow', reason: 'No bash permissions configured' }
+    }
+
+    const match = findBestMatch(this.config.bash, command)
+
+    if (!match) {
+      // Default: allow if no pattern matches
+      return { allowed: true, level: 'allow', reason: 'No matching pattern' }
+    }
+
+    return {
+      allowed: match.level === 'allow',
+      level: match.level,
+      matchedPattern: match.pattern,
+      reason: match.level === 'deny'
+        ? `Command denied by pattern: ${match.pattern}`
+        : match.level === 'ask'
+          ? `Command requires approval: ${match.pattern}`
+          : undefined,
+    }
+  }
+
+  /**
+   * Check if a file operation is allowed
+   */
+  checkFileOperation(
+    operation: 'read' | 'write' | 'delete',
+    filePath: string
+  ): PermissionCheckResult {
+    const filePerms = this.config.files?.[operation]
+
+    if (!filePerms) {
+      return { allowed: true, level: 'allow', reason: 'No file permissions configured' }
+    }
+
+    const match = findBestMatch(filePerms, filePath)
+
+    if (!match) {
+      return { allowed: true, level: 'allow', reason: 'No matching pattern' }
+    }
+
+    return {
+      allowed: match.level === 'allow',
+      level: match.level,
+      matchedPattern: match.pattern,
+      reason: match.level === 'deny'
+        ? `File operation denied: ${operation} on ${match.pattern}`
+        : match.level === 'ask'
+          ? `File operation requires approval: ${operation}`
+          : undefined,
+    }
+  }
+
+  /**
+   * Check if web fetch is allowed for a domain
+   */
+  checkWebFetch(url: string): PermissionCheckResult {
+    const webConfig = this.config.web
+
+    if (!webConfig?.enabled) {
+      return {
+        allowed: false,
+        level: 'deny',
+        reason: 'Web fetch is disabled',
+      }
+    }
+
+    try {
+      const domain = new URL(url).hostname
+
+      // Check blocked domains
+      if (webConfig.blockedDomains?.some((d) => domain.includes(d))) {
+        return {
+          allowed: false,
+          level: 'deny',
+          matchedPattern: domain,
+          reason: `Domain is blocked: ${domain}`,
+        }
+      }
+
+      // Check allowed domains (if specified, only those are allowed)
+      if (webConfig.allowedDomains && webConfig.allowedDomains.length > 0) {
+        const isAllowed = webConfig.allowedDomains.some((d) => domain.includes(d))
+        if (!isAllowed) {
+          return {
+            allowed: false,
+            level: 'deny',
+            matchedPattern: domain,
+            reason: `Domain not in allowed list: ${domain}`,
+          }
+        }
+      }
+
+      return { allowed: true, level: 'allow' }
+    } catch {
+      return {
+        allowed: false,
+        level: 'deny',
+        reason: 'Invalid URL',
+      }
+    }
+  }
+
+  /**
+   * Check if a skill can be invoked
+   */
+  checkSkill(skillName: string): PermissionCheckResult {
+    if (!this.config.skills) {
+      return { allowed: true, level: 'allow', reason: 'No skill permissions configured' }
+    }
+
+    const match = findBestMatch(this.config.skills, skillName)
+
+    if (!match) {
+      return { allowed: true, level: 'allow', reason: 'No matching pattern' }
+    }
+
+    return {
+      allowed: match.level === 'allow',
+      level: match.level,
+      matchedPattern: match.pattern,
+    }
+  }
+
+  /**
+   * Check if external directory access is allowed
+   */
+  checkExternalDirectory(path: string, projectRoot: string): PermissionCheckResult {
+    const isExternal = !path.startsWith(projectRoot)
+
+    if (!isExternal) {
+      return { allowed: true, level: 'allow', reason: 'Path is within project' }
+    }
+
+    const level = this.config.externalDirectories || 'ask'
+
+    return {
+      allowed: level === 'allow',
+      level,
+      reason: level === 'deny'
+        ? 'External directory access denied'
+        : level === 'ask'
+          ? 'External directory access requires approval'
+          : undefined,
+    }
+  }
+
+  /**
+   * Get current permissions config
+   */
+  getConfig(): PermissionsConfig {
+    return this.config
+  }
+
+  /**
+   * Check doom loop protection
+   */
+  checkDoomLoop(retryCount: number): PermissionCheckResult {
+    const doomLoop = this.config.doomLoop
+
+    if (!doomLoop?.enabled) {
+      return { allowed: true, level: 'allow', reason: 'Doom loop protection disabled' }
+    }
+
+    const maxRetries = doomLoop.maxRetries || 3
+
+    if (retryCount >= maxRetries) {
+      return {
+        allowed: false,
+        level: 'deny',
+        reason: `Doom loop detected: ${retryCount} retries exceeded limit of ${maxRetries}`,
+      }
+    }
+
+    return { allowed: true, level: 'allow' }
+  }
+}
+
+// Singleton instance
+const permissionManager = new PermissionManager()
+export default permissionManager
+
+// Export class for testing
+export { PermissionManager }

package/core/outcomes/analyzer.ts

@@ -6,47 +6,13 @@
  */
 
 import outcomeRecorder from './recorder'
-import type { Outcome, OutcomeSummary, QualityScore } from './types'
-
-/**
- * Pattern detected from outcomes.
- */
-export interface DetectedPattern {
-  /** Pattern description */
-  description: string
-
-  /** Confidence level (0-1) */
-  confidence: number
-
-  /** Number of occurrences supporting this pattern */
-  occurrences: number
-
-  /** Suggested action based on pattern */
-  suggestedAction?: string
-}
-
-/**
- * Agent performance metrics.
- */
-export interface AgentMetrics {
-  /** Agent name */
-  agent: string
-
-  /** Number of tasks completed */
-  tasksCompleted: number
-
-  /** Success rate (0-100) */
-  successRate: number
-
-  /** Average quality score */
-  avgQualityScore: number
-
-  /** Estimate accuracy */
-  estimateAccuracy: number
-
-  /** Best task types for this agent */
-  bestFor: string[]
-}
+import type {
+  Outcome,
+  OutcomeSummary,
+  QualityScore,
+  DetectedPattern,
+  AgentMetrics,
+} from '../types'
 
 /**
  * OutcomeAnalyzer - Extracts insights from outcomes.

package/core/outcomes/index.ts

@@ -31,4 +31,4 @@
 
 export { OutcomeRecorder, default as outcomeRecorder } from './recorder'
 export { OutcomeAnalyzer, default as outcomeAnalyzer } from './analyzer'
-export * from './types'
+export * from '../types'

package/core/outcomes/recorder.ts

@@ -9,7 +9,7 @@ import path from 'path'
 import * as fileHelper from '../utils/file-helper'
 import pathManager from '../infrastructure/path-manager'
 import { generateUUID } from '../schemas'
-import type { Outcome, OutcomeInput, OutcomeFilter } from './types'
+import type { Outcome, OutcomeInput, OutcomeFilter } from '../types'
 
 const OUTCOMES_DIR = 'outcomes'
 const OUTCOMES_FILE = 'outcomes.jsonl'

package/core/{plugins → plugin/builtin}/webhook.ts

@@ -18,25 +18,9 @@
  */
 
 import crypto from 'crypto'
-import { EventTypes } from '../bus'
-import { HookPoints } from '../plugin/hooks'
-
-interface WebhookConfig {
-  url?: string
-  events?: string[]
-  secret?: string
-}
-
-interface PluginContext {
-  config: WebhookConfig
-}
-
-interface WebhookPayload {
-  event: string
-  timestamp: string
-  source: string
-  data: unknown
-}
+import { EventTypes } from '../../bus'
+import { HookPoints } from '../hooks'
+import type { WebhookConfig, WebhookPluginContext, WebhookPayload } from '../../types'
 
 const plugin = {
   name: 'webhook',
@@ -46,12 +30,12 @@ const plugin = {
   // Plugin state
   config: null as WebhookConfig | null,
   enabled: false,
-  events: [] as string[],
+  enabledEvents: [] as string[],
 
   /**
    * Activate plugin
    */
-  async activate({ config }: PluginContext): Promise<void> {
+  async activate({ config }: WebhookPluginContext): Promise<void> {
     plugin.config = config
 
     if (!config.url) {
@@ -60,7 +44,7 @@ const plugin = {
     }
 
     plugin.enabled = true
-    plugin.events = config.events || [
+    plugin.enabledEvents = config.events || [
       EventTypes.SESSION_COMPLETED,
       EventTypes.FEATURE_SHIPPED,
       EventTypes.SNAPSHOT_CREATED

package/core/plugin/loader.ts

@@ -12,7 +12,7 @@
 import fs from 'fs/promises'
 import path from 'path'
 import { hookSystem } from './hooks'
-import { eventBus } from '../bus'
+import { eventBus, type EventCallback } from '../bus'
 import pathManager from '../infrastructure/path-manager'
 
 type PluginSource = 'builtin' | 'global' | 'project'
@@ -23,7 +23,7 @@ interface Plugin {
   version?: string
   description?: string
   hooks?: Record<string, HookHandler>
-  events?: Record<string, HookHandler>
+  events?: Record<string, EventCallback>
   commands?: Record<string, { handler: () => void; description?: string }>
   priority?: number
   activate?: (context: PluginContext) => Promise<void>
@@ -83,10 +83,10 @@ class PluginLoader {
   }
 
   /**
-   * Load built-in plugins from core/plugins
+   * Load built-in plugins from core/plugin/builtin
    */
   async loadBuiltinPlugins(): Promise<void> {
-    const builtinPath = path.join(__dirname, '..', 'plugins')
+    const builtinPath = path.join(__dirname, 'builtin')
 
     try {
       const files = await fs.readdir(builtinPath)
@@ -106,7 +106,7 @@ class PluginLoader {
    * Load global plugins from ~/.prjct-cli/plugins
    */
   async loadGlobalPlugins(): Promise<void> {
-    const globalPath = path.join(pathManager.getGlobalStoragePath(), 'plugins')
+    const globalPath = path.join(pathManager.getGlobalBasePath(), 'plugins')
 
     try {
       const files = await fs.readdir(globalPath)

package/core/plugin/registry.ts

@@ -57,7 +57,7 @@ class PluginRegistry {
 
     // Global plugins
     await this.discoverFromPath(
-      path.join(pathManager.getGlobalStoragePath(), 'plugins'),
+      path.join(pathManager.getGlobalBasePath(), 'plugins'),
       'global'
     )
   }
@@ -188,7 +188,7 @@ class PluginRegistry {
    * Install a plugin (copy to global plugins)
    */
   async install(sourcePath: string, name: string | null = null): Promise<void> {
-    const globalPluginsPath = path.join(pathManager.getGlobalStoragePath(), 'plugins')
+    const globalPluginsPath = path.join(pathManager.getGlobalBasePath(), 'plugins')
     await fs.mkdir(globalPluginsPath, { recursive: true })
 
     const stat = await fs.stat(sourcePath)