prjct-cli 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.57.0] - 2026-02-05
+
+### Features
+
+- monorepo support with nested PRJCT.md inheritance (PRJ-118) (#94)
+
+
+## [0.57.0] - 2026-02-05
+
+### Features
+
+- **Monorepo support (PRJ-118)**: Support nested PRJCT.md files for monorepo subdirectories
+  - Detect monorepos (pnpm, npm, yarn, lerna, nx, turborepo, rush)
+  - Discover packages with workspace patterns
+  - Nested PRJCT.md inheritance (deeper files take precedence)
+  - Per-package CLAUDE.md generation with merged context
+  - `prjct sync --package=<name>` for single package sync
+
+### Added
+
+- `NestedContextResolver` service for PRJCT.md discovery and inheritance
+- `detectMonorepo()` and `discoverMonorepoPackages()` in PathManager
+- `generateMonorepoContexts()` in ContextFileGenerator
+
+## [0.56.1] - 2026-02-05
+
+### Bug Fixes
+
+- **Context injection**: Fixed template paths in CLAUDE.md - now correctly points to `~/.claude/commands/p/` instead of `templates/commands/`
+- **Agent loading**: Added clear instructions for loading domain agents before SMART commands (task, ship, bug, done)
+
 ## [0.56.0] - 2026-02-05
 
 ### Features

package/core/commands/analysis.ts

@@ -227,7 +227,13 @@ export class AnalysisCommands extends PrjctCommandsBase {
    */
   async sync(
     projectPath: string = process.cwd(),
-    options: { aiTools?: string[]; preview?: boolean; yes?: boolean; json?: boolean } = {}
+    options: {
+      aiTools?: string[]
+      preview?: boolean
+      yes?: boolean
+      json?: boolean
+      package?: string
+    } = {}
   ): Promise<CommandResult> {
     try {
       const initResult = await this.ensureProjectInit(projectPath)
@@ -242,6 +248,45 @@ export class AnalysisCommands extends PrjctCommandsBase {
       const globalPath = pathManager.getGlobalProjectPath(projectId)
       const startTime = Date.now()
 
+      // Handle package-specific sync for monorepos
+      if (options.package) {
+        const monoInfo = await pathManager.detectMonorepo(projectPath)
+        if (!monoInfo.isMonorepo) {
+          return {
+            success: false,
+            error: 'Not a monorepo. --package flag only works in monorepos.',
+          }
+        }
+
+        const pkg = monoInfo.packages.find(
+          (p) => p.name === options.package || p.relativePath === options.package
+        )
+        if (!pkg) {
+          const available = monoInfo.packages.map((p) => p.name).join(', ')
+          return {
+            success: false,
+            error: `Package "${options.package}" not found. Available: ${available}`,
+          }
+        }
+
+        // Sync only the specified package
+        const result = await syncService.sync(projectPath, {
+          aiTools: options.aiTools,
+          packagePath: pkg.path,
+          packageName: pkg.name,
+        })
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({ success: result.success, package: pkg.name, path: pkg.relativePath })
+          )
+        } else {
+          out.done(`Synced package: ${pkg.name}`)
+        }
+
+        return { success: result.success }
+      }
+
       // Generate diff preview if we have existing context
       const claudeMdPath = path.join(globalPath, 'context', 'CLAUDE.md')
       let existingContent: string | null = null

package/core/commands/command-data.ts

@@ -166,10 +166,15 @@ export const COMMANDS: CommandMeta[] = [
     name: 'sync',
     group: 'core',
     description: 'Sync project state and update workflow agents',
-    usage: { claude: '/p:sync', terminal: 'prjct sync' },
+    usage: { claude: '/p:sync', terminal: 'prjct sync [--package=<name>]' },
     implemented: true,
     hasTemplate: true,
     requiresProject: true,
+    features: [
+      'Monorepo support: --package=<name> for single package sync',
+      'Nested PRJCT.md inheritance',
+      'Per-package CLAUDE.md generation',
+    ],
   },
   {
     name: 'suggest',

package/core/commands/commands.ts

@@ -184,7 +184,13 @@ class PrjctCommands {
 
   async sync(
     projectPath: string = process.cwd(),
-    options: { aiTools?: string[]; preview?: boolean; yes?: boolean; json?: boolean } = {}
+    options: {
+      aiTools?: string[]
+      preview?: boolean
+      yes?: boolean
+      json?: boolean
+      package?: string
+    } = {}
   ): Promise<CommandResult> {
     return this.analysis.sync(projectPath, options)
   }

package/core/index.ts

@@ -129,6 +129,7 @@ async function main(): Promise<void> {
             preview: options.preview === true,
             yes: options.yes === true,
             json: options.json === true,
+            package: options.package ? String(options.package) : undefined,
           }),
         start: () => commands.start(),
         // Context (for Claude templates)

package/core/infrastructure/path-manager.ts

@@ -13,10 +13,28 @@ import crypto from 'node:crypto'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
+import { globSync } from 'glob'
 import type { SessionInfo } from '../types'
 import * as dateHelper from '../utils/date-helper'
 import * as fileHelper from '../utils/file-helper'
 
+/**
+ * Monorepo detection result
+ */
+export interface MonorepoInfo {
+  isMonorepo: boolean
+  type: 'pnpm' | 'npm' | 'yarn' | 'lerna' | 'nx' | 'rush' | 'turborepo' | null
+  rootPath: string
+  packages: MonorepoPackage[]
+}
+
+export interface MonorepoPackage {
+  name: string
+  path: string
+  relativePath: string
+  hasPrjctMd: boolean
+}
+
 class PathManager {
   globalBaseDir: string
   globalProjectsDir: string
@@ -360,6 +378,207 @@ class PathManager {
   getContextPath(projectId: string): string {
     return path.join(this.getGlobalProjectPath(projectId), 'context')
   }
+
+  // ===========================================================================
+  // Monorepo Detection
+  // ===========================================================================
+
+  /**
+   * Detect if a project is a monorepo and get package information
+   */
+  async detectMonorepo(projectPath: string): Promise<MonorepoInfo> {
+    const result: MonorepoInfo = {
+      isMonorepo: false,
+      type: null,
+      rootPath: projectPath,
+      packages: [],
+    }
+
+    // Check for various monorepo configurations
+    const checks = [
+      { file: 'pnpm-workspace.yaml', type: 'pnpm' as const },
+      { file: 'lerna.json', type: 'lerna' as const },
+      { file: 'nx.json', type: 'nx' as const },
+      { file: 'rush.json', type: 'rush' as const },
+      { file: 'turbo.json', type: 'turborepo' as const },
+    ]
+
+    for (const check of checks) {
+      const filePath = path.join(projectPath, check.file)
+      if (await fileHelper.fileExists(filePath)) {
+        result.isMonorepo = true
+        result.type = check.type
+        break
+      }
+    }
+
+    // Check package.json for workspaces (npm/yarn)
+    if (!result.isMonorepo) {
+      const packageJsonPath = path.join(projectPath, 'package.json')
+      if (await fileHelper.fileExists(packageJsonPath)) {
+        try {
+          const content = await fs.readFile(packageJsonPath, 'utf-8')
+          const pkg = JSON.parse(content)
+          if (pkg.workspaces) {
+            result.isMonorepo = true
+            result.type = 'npm' // Could be yarn too, but npm is more generic
+          }
+        } catch {
+          // Invalid package.json, ignore
+        }
+      }
+    }
+
+    // If it's a monorepo, discover packages
+    if (result.isMonorepo) {
+      result.packages = await this.discoverMonorepoPackages(projectPath, result.type)
+    }
+
+    return result
+  }
+
+  /**
+   * Discover all packages in a monorepo
+   */
+  async discoverMonorepoPackages(
+    rootPath: string,
+    type: MonorepoInfo['type']
+  ): Promise<MonorepoPackage[]> {
+    const packages: MonorepoPackage[] = []
+    let patterns: string[] = []
+
+    try {
+      if (type === 'pnpm') {
+        // Read pnpm-workspace.yaml
+        const yaml = await fs.readFile(path.join(rootPath, 'pnpm-workspace.yaml'), 'utf-8')
+        // Simple YAML parsing for packages array
+        const match = yaml.match(/packages:\s*\n((?:\s*-\s*.+\n?)+)/)
+        if (match) {
+          patterns = match[1]
+            .split('\n')
+            .map((line) => line.replace(/^\s*-\s*['"]?|['"]?\s*$/g, ''))
+            .filter(Boolean)
+        }
+      } else if (type === 'npm' || type === 'lerna') {
+        // Read from package.json workspaces or lerna.json
+        const packageJsonPath = path.join(rootPath, 'package.json')
+        const content = await fs.readFile(packageJsonPath, 'utf-8')
+        const pkg = JSON.parse(content)
+        if (Array.isArray(pkg.workspaces)) {
+          patterns = pkg.workspaces
+        } else if (pkg.workspaces?.packages) {
+          patterns = pkg.workspaces.packages
+        }
+
+        // Also check lerna.json
+        if (type === 'lerna') {
+          const lernaPath = path.join(rootPath, 'lerna.json')
+          if (await fileHelper.fileExists(lernaPath)) {
+            const lernaContent = await fs.readFile(lernaPath, 'utf-8')
+            const lerna = JSON.parse(lernaContent)
+            if (lerna.packages) {
+              patterns = lerna.packages
+            }
+          }
+        }
+      } else if (type === 'nx') {
+        // NX uses apps/* and libs/* by default
+        patterns = ['apps/*', 'libs/*', 'packages/*']
+      } else if (type === 'turborepo') {
+        // Turborepo reads from package.json workspaces
+        const packageJsonPath = path.join(rootPath, 'package.json')
+        const content = await fs.readFile(packageJsonPath, 'utf-8')
+        const pkg = JSON.parse(content)
+        if (Array.isArray(pkg.workspaces)) {
+          patterns = pkg.workspaces
+        }
+      }
+
+      // If no patterns found, use common defaults
+      if (patterns.length === 0) {
+        patterns = ['packages/*', 'apps/*', 'libs/*']
+      }
+
+      // Expand glob patterns to find packages
+      for (const pattern of patterns) {
+        // Skip negation patterns for now
+        if (pattern.startsWith('!')) continue
+
+        const matches = globSync(pattern, {
+          cwd: rootPath,
+          absolute: false,
+        })
+
+        for (const match of matches) {
+          const packagePath = path.join(rootPath, match)
+          const packageJsonPath = path.join(packagePath, 'package.json')
+
+          // Only include directories with package.json
+          if (await fileHelper.fileExists(packageJsonPath)) {
+            try {
+              const content = await fs.readFile(packageJsonPath, 'utf-8')
+              const pkg = JSON.parse(content)
+              const prjctMdPath = path.join(packagePath, 'PRJCT.md')
+
+              packages.push({
+                name: pkg.name || path.basename(match),
+                path: packagePath,
+                relativePath: match,
+                hasPrjctMd: await fileHelper.fileExists(prjctMdPath),
+              })
+            } catch {
+              // Invalid package.json, skip
+            }
+          }
+        }
+      }
+    } catch {
+      // Error reading monorepo config, return empty
+    }
+
+    return packages
+  }
+
+  /**
+   * Check if current path is within a monorepo package
+   * Returns the package info if found, null otherwise
+   */
+  async findContainingPackage(
+    currentPath: string,
+    monoInfo: MonorepoInfo
+  ): Promise<MonorepoPackage | null> {
+    if (!monoInfo.isMonorepo) return null
+
+    const normalizedCurrent = path.resolve(currentPath)
+
+    for (const pkg of monoInfo.packages) {
+      const normalizedPkg = path.resolve(pkg.path)
+      if (normalizedCurrent.startsWith(normalizedPkg)) {
+        return pkg
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Find monorepo root from any subdirectory
+   * Walks up the directory tree looking for monorepo markers
+   */
+  async findMonorepoRoot(startPath: string): Promise<string | null> {
+    let currentPath = path.resolve(startPath)
+    const root = path.parse(currentPath).root
+
+    while (currentPath !== root) {
+      const monoInfo = await this.detectMonorepo(currentPath)
+      if (monoInfo.isMonorepo) {
+        return currentPath
+      }
+      currentPath = path.dirname(currentPath)
+    }
+
+    return null
+  }
 }
 
 const pathManager = new PathManager()

package/core/services/context-generator.ts

@@ -11,8 +11,10 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import pathManager from '../infrastructure/path-manager'
 import dateHelper from '../utils/date-helper'
 import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
+import { NestedContextResolver } from './nested-context-resolver'
 
 // ============================================================================
 // TYPES
@@ -325,6 +327,135 @@ ${
 
     await this.writeWithPreservation(path.join(contextPath, 'shipped.md'), content)
   }
+
+  // ==========================================================================
+  // MONOREPO SUPPORT
+  // ==========================================================================
+
+  /**
+   * Generate CLAUDE.md files for each package in a monorepo
+   * Each package gets its own context file with inherited + package-specific rules
+   */
+  async generateMonorepoContexts(
+    git: GitData,
+    stats: ProjectStats,
+    commands: Commands,
+    agents: AgentInfo[]
+  ): Promise<string[]> {
+    const monoInfo = await pathManager.detectMonorepo(this.config.projectPath)
+
+    if (!monoInfo.isMonorepo) {
+      return []
+    }
+
+    const generatedFiles: string[] = []
+    const resolver = new NestedContextResolver(this.config.projectPath)
+    await resolver.initialize()
+
+    // Generate CLAUDE.md for each package that has PRJCT.md
+    for (const pkg of monoInfo.packages) {
+      if (!pkg.hasPrjctMd) continue
+
+      const resolvedCtx = await resolver.getPackageContext(pkg.name)
+      if (!resolvedCtx) continue
+
+      const content = await this.generatePackageClaudeMd(
+        pkg,
+        resolvedCtx,
+        git,
+        stats,
+        commands,
+        agents
+      )
+
+      // Write to the package directory
+      const claudePath = path.join(pkg.path, 'CLAUDE.md')
+      await this.writeWithPreservation(claudePath, content)
+      generatedFiles.push(path.relative(this.config.projectPath, claudePath))
+    }
+
+    return generatedFiles
+  }
+
+  /**
+   * Generate CLAUDE.md content for a specific package
+   */
+  private async generatePackageClaudeMd(
+    pkg: { name: string; path: string; relativePath: string },
+    resolvedCtx: { content: string; sources: string[]; overrides: string[] },
+    git: GitData,
+    stats: ProjectStats,
+    commands: Commands,
+    agents: AgentInfo[]
+  ): Promise<string> {
+    const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
+    const domainAgents = agents.filter((a) => a.type === 'domain').map((a) => a.name)
+
+    // Try to read package-specific info
+    let pkgVersion = stats.version
+    let pkgName = pkg.name
+    try {
+      const pkgJsonPath = path.join(pkg.path, 'package.json')
+      const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf-8'))
+      pkgVersion = pkgJson.version || stats.version
+      pkgName = pkgJson.name || pkg.name
+    } catch {
+      // Use defaults
+    }
+
+    return `# ${pkgName} - Package Rules
+<!-- package: ${pkg.relativePath} -->
+<!-- monorepo: ${stats.name} -->
+<!-- Generated: ${dateHelper.getTimestamp()} -->
+<!-- Sources: ${resolvedCtx.sources.join(' → ')} -->
+
+## THIS PACKAGE
+
+**Name:** ${pkgName}
+**Path:** ${pkg.relativePath}
+**Version:** ${pkgVersion}
+**Monorepo:** ${stats.name}
+
+---
+
+## INHERITED CONTEXT
+
+${resolvedCtx.content || '_No PRJCT.md rules defined_'}
+
+${resolvedCtx.overrides.length > 0 ? `\n**Overrides:** ${resolvedCtx.overrides.join(', ')}\n` : ''}
+
+---
+
+## COMMANDS
+
+| Action | Command |
+|--------|---------|
+| Install | \`${commands.install}\` |
+| Dev | \`${commands.dev}\` |
+| Test | \`${commands.test}\` |
+| Build | \`${commands.build}\` |
+
+---
+
+## PROJECT STATE
+
+| Field | Value |
+|-------|-------|
+| Package | ${pkgName} |
+| Monorepo | ${stats.name} |
+| Branch | ${git.branch} |
+| Ecosystem | ${stats.ecosystem} |
+
+---
+
+## AGENTS
+
+Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
+
+**Workflow**: ${workflowAgents.join(', ')}
+**Domain**: ${domainAgents.join(', ') || 'none'}
+`
+  }
 }
 
 export default ContextFileGenerator

package/core/services/index.ts

@@ -32,6 +32,9 @@ export type { GitData } from './git-analyzer'
 // Git Analyzer - Extracted from sync-service (PRJ-85)
 export { GitAnalyzer, getEmptyGitData, gitAnalyzer } from './git-analyzer'
 export { MemoryService, memoryService } from './memory-service'
+export type { ContextSection, NestedContext, ResolvedContext } from './nested-context-resolver'
+// Nested Context Resolver - Monorepo PRJCT.md inheritance (PRJ-118)
+export { NestedContextResolver } from './nested-context-resolver'
 export type { IndexOptions, RelevantContext, ScanResult } from './project-index'
 // Project Index - Persistent scanning with scoring
 export { createProjectIndexer, ProjectIndexer, RELEVANCE_THRESHOLD } from './project-index'