prjct-cli 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,12 +1,134 @@
 # Changelog
 
+## [1.5.1] - 2026-02-06
+
+### Refactoring
+
+- standardize on fs/promises across codebase (PRJ-93) (#118)
+
+
+## [1.5.1] - 2026-02-06
+
+### Changed
+
+- **Standardize on fs/promises across codebase (PRJ-93)**: Replaced all synchronous `fs` operations (`existsSync`, `readFileSync`, `writeFileSync`, `mkdirSync`, etc.) with async `fs/promises` equivalents across 22 files
+
+### Implementation Details
+
+- Created shared `fileExists()` utility in `core/utils/fs-helpers.ts` replacing `existsSync` with `fs.access`
+- Converted all detection functions in `ai-provider.ts` to async with `Promise.all` for parallel checks
+- Applied lazy initialization pattern in `CommandInstaller` to handle async `getActiveProvider()` in constructor
+- Replaced `execSync` with `promisify(exec)` in `registry.ts` and `ai-provider.ts`
+- Converted `setup.ts` (~60 sync ops), `hooks-service.ts` (~30 sync ops), and all command/CLI files
+- Updated prompt-builder and command-executor tests to handle async `build()` and `signalStart/End()`
+- Intentional exceptions: `version.ts` (module-level constants), `jsonl-helper.ts` (`createReadStream`), test files
+
+### Learnings
+
+- Module-level constants (`VERSION`, `PACKAGE_ROOT`) cannot use async — sync reads at import time are a valid exception
+- `createReadStream` is inherently sync (returns a stream) — the correct pattern for streaming reads
+- Making a function async cascades to all callers — `ai-provider.ts` changes rippled to 10+ files
+- Constructor methods can't be async — solved with lazy `ensureInit()` pattern in `CommandInstaller`
+
+### Test Plan
+
+#### For QA
+1. Run `bun run build` — verify clean build with no errors
+2. Run `bun test` — verify all 416 tests pass
+3. Run `prjct sync` on a project — verify async fs operations work correctly
+4. Run `prjct start` — verify setup flow works with async file operations
+5. Verify `prjct linear list` works (uses converted linear/sync.ts)
+
+#### For Users
+**What changed:** Internal refactor — no user-facing API changes. All sync filesystem operations replaced with async equivalents for better performance.
+**How to use:** No changes needed. All commands work identically.
+**Breaking changes:** None
+
+## [1.5.0] - 2026-02-06
+
+### Features
+
+- add citation format for context sources in templates (PRJ-113) (#117)
+
+## [1.4.2] - 2026-02-06
+
+### Features
+
+- **Source citations in context files (PRJ-113)**: All generated context files now include `<!-- source: file, type -->` HTML comments showing where each section's data was detected from
+
+### Implementation Details
+
+- Added `SourceInfo` type and `ContextSources` interface with `cite()` helper (`core/utils/citations.ts`)
+- Extended `ProjectContext` with optional `sources` field — backward compatible, falls back to `defaultSources()`
+- Added `buildSources()` to `sync-service.ts` — maps detected ecosystem/commands data to their source files (package.json, lock files, Cargo.toml, etc.)
+- Citations added to 4 markdown formatters: Claude, Cursor, Windsurf, Copilot. Continue.dev skipped (JSON has no comment syntax)
+- Context generator CLAUDE.md also updated with citation support
+- Source types: `detected` (from files), `user-defined` (from config), `inferred` (from heuristics)
+
+### Learnings
+
+- `context-generator.ts` and `formatters.ts` both independently generate CLAUDE.md content — both must be updated for consistent citations
+- Sources can be determined post-detection from data values rather than threading metadata through every detection method
+- Optional fields with fallback defaults (`sources?`) maintain backward compatibility without breaking existing callers
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` — verify generated context files contain `<!-- source: ... -->` comments
+2. Check CLAUDE.md citations before: THIS PROJECT, Commands, Code Conventions, PROJECT STATE
+3. Check `.cursor/rules/prjct.mdc` citations before Tech Stack and Commands
+4. Check `.windsurf/rules/prjct.md` citations before Stack and Commands
+5. Check `.github/copilot-instructions.md` citations before Project Info and Commands
+6. Verify `.continue/config.json` unchanged (JSON has no comments)
+7. Run `bun test` — all 416 tests pass
+
+#### For Users
+**What changed:** Context files now show where data came from via HTML comments
+**How to use:** Run `p. sync` — citations appear automatically
+**Breaking changes:** None
+
+## [1.4.1] - 2026-02-06
+
+### Improvements
+
+- **Better error messages for invalid commands (PRJ-98)**: Consistent, helpful CLI errors with did-you-mean suggestions and required parameter validation
+
+### Implementation Details
+
+- Added `UNKNOWN_COMMAND` and `MISSING_PARAM` error codes to centralized error catalog (`core/utils/error-messages.ts`)
+- Added `validateCommandParams()` — parses `CommandMeta.params` convention (`<required>` vs `[optional]`) and validates against actual CLI args before command execution
+- Added `findClosestCommand()` with Levenshtein edit distance (threshold ≤ 2) for did-you-mean suggestions on typos
+- All error paths now use `out.failWithHint()` for consistent formatting with hints, docs links, and file references
+- Deprecated and unimplemented command errors also upgraded to use `failWithHint()`
+
+### Learnings
+
+- `bin/prjct.ts` intercepts many commands (start, context, hooks, doctor, etc.) before `core/index.ts` — changes to dispatch only affect commands that reach core
+- Template-only commands (e.g. `task`) are defined in `command-data.ts` but not registered in the command registry — they don't get param validation via CLI
+- Levenshtein edit distance is simple to implement (~15 lines) and effective for CLI typo suggestions
+
+### Test Plan
+
+#### For QA
+1. `prjct xyzzy` → "Unknown command: xyzzy" with help hint
+2. `prjct snyc` → "Did you mean 'prjct sync'?"
+3. `prjct shp` → "Did you mean 'prjct ship'?"
+4. `prjct bug` (no args) → "Missing required parameter: description" with usage
+5. `prjct idea` (no args) → "Missing required parameter: description" with usage
+6. `prjct sync --yes` → works normally (no regression)
+7. `prjct dash compact` → works normally (no regression)
+
+#### For Users
+**What changed:** CLI now shows helpful error messages with suggestions when you mistype a command or forget a required argument.
+**How to use:** Just use prjct normally — errors are now more helpful automatically.
+**Breaking changes:** None
+
 ## [1.4.0] - 2026-02-06
 
 ### Features
 
 - programmatic verification checks for sync workflow (PRJ-106) (#115)
 
-
 ## [1.3.1] - 2026-02-06
 
 ### Features

package/bin/prjct.ts

@@ -8,7 +8,6 @@
  * auto-install on first CLI use. This is the reliable path.
  */
 
-import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import chalk from 'chalk'
@@ -16,20 +15,21 @@ import { detectAllProviders } from '../core/infrastructure/ai-provider'
 import configManager from '../core/infrastructure/config-manager'
 import editorsConfig from '../core/infrastructure/editors-config'
 import { DEFAULT_PORT, startServer } from '../core/server/server'
+import { fileExists } from '../core/utils/fs-helpers'
 import { VERSION } from '../core/utils/version'
 
 /**
  * Check if routers are installed for detected providers
  * Returns true if at least one provider has its router installed
  */
-function checkRoutersInstalled(): boolean {
+async function checkRoutersInstalled(): Promise<boolean> {
   const home = os.homedir()
-  const detection = detectAllProviders()
+  const detection = await detectAllProviders()
 
   // Check Claude router
   if (detection.claude.installed) {
     const claudeRouter = path.join(home, '.claude', 'commands', 'p.md')
-    if (!fs.existsSync(claudeRouter)) {
+    if (!(await fileExists(claudeRouter))) {
       return false
     }
   }
@@ -37,7 +37,7 @@ function checkRoutersInstalled(): boolean {
   // Check Gemini router
   if (detection.gemini.installed) {
     const geminiRouter = path.join(home, '.gemini', 'commands', 'p.toml')
-    if (!fs.existsSync(geminiRouter)) {
+    if (!(await fileExists(geminiRouter))) {
       return false
     }
   }
@@ -218,15 +218,24 @@ if (args[0] === 'start' || args[0] === 'setup') {
   process.exitCode = 0
 } else if (args[0] === 'version' || args[0] === '-v' || args[0] === '--version') {
   // Show version with provider status
-  const detection = detectAllProviders()
+  const detection = await detectAllProviders()
   const home = os.homedir()
   const cwd = process.cwd()
-  const claudeConfigured = fs.existsSync(path.join(home, '.claude', 'commands', 'p.md'))
-  const geminiConfigured = fs.existsSync(path.join(home, '.gemini', 'commands', 'p.toml'))
-  const cursorDetected = fs.existsSync(path.join(cwd, '.cursor'))
-  const cursorConfigured = fs.existsSync(path.join(cwd, '.cursor', 'rules', 'prjct.mdc'))
-  const windsurfDetected = fs.existsSync(path.join(cwd, '.windsurf'))
-  const windsurfConfigured = fs.existsSync(path.join(cwd, '.windsurf', 'rules', 'prjct.md'))
+  const [
+    claudeConfigured,
+    geminiConfigured,
+    cursorDetected,
+    cursorConfigured,
+    windsurfDetected,
+    windsurfConfigured,
+  ] = await Promise.all([
+    fileExists(path.join(home, '.claude', 'commands', 'p.md')),
+    fileExists(path.join(home, '.gemini', 'commands', 'p.toml')),
+    fileExists(path.join(cwd, '.cursor')),
+    fileExists(path.join(cwd, '.cursor', 'rules', 'prjct.mdc')),
+    fileExists(path.join(cwd, '.windsurf')),
+    fileExists(path.join(cwd, '.windsurf', 'rules', 'prjct.md')),
+  ])
 
   console.log(`
 ${chalk.cyan('p/')} prjct v${VERSION}
@@ -276,9 +285,9 @@ ${chalk.cyan('https://prjct.app')}
 } else {
   // Check if setup has been done
   const configPath = path.join(os.homedir(), '.prjct-cli', 'config', 'installed-editors.json')
-  const routersInstalled = checkRoutersInstalled()
+  const routersInstalled = await checkRoutersInstalled()
 
-  if (!fs.existsSync(configPath) || !routersInstalled) {
+  if (!(await fileExists(configPath)) || !routersInstalled) {
     // First time - prompt to run start
     console.log(`
 ${chalk.cyan.bold('  Welcome to prjct!')}

package/core/__tests__/agentic/command-executor.test.ts

@@ -106,40 +106,40 @@ describe('CommandExecutor', () => {
       }
     })
 
-    it('should create status file with command name', () => {
-      signalStart('test-command')
+    it('should create status file with command name', async () => {
+      await signalStart('test-command')
 
       expect(fs.existsSync(RUNNING_FILE)).toBe(true)
       const content = fs.readFileSync(RUNNING_FILE, 'utf-8')
       expect(content).toBe('/p:test-command')
     })
 
-    it('should overwrite existing status file', () => {
-      signalStart('first-command')
-      signalStart('second-command')
+    it('should overwrite existing status file', async () => {
+      await signalStart('first-command')
+      await signalStart('second-command')
 
       const content = fs.readFileSync(RUNNING_FILE, 'utf-8')
       expect(content).toBe('/p:second-command')
     })
 
-    it('should handle filesystem errors gracefully', () => {
+    it('should handle filesystem errors gracefully', async () => {
       // This test verifies that errors are silently ignored
       // We can't easily simulate fs errors, but we can verify the function doesn't throw
-      expect(() => signalStart('test-command')).not.toThrow()
+      await expect(signalStart('test-command')).resolves.toBeUndefined()
     })
   })
 
   describe('signalEnd', () => {
-    it('should remove status file if it exists', () => {
+    it('should remove status file if it exists', async () => {
       // Create the file first
-      signalStart('test-command')
+      await signalStart('test-command')
       expect(fs.existsSync(RUNNING_FILE)).toBe(true)
 
-      signalEnd()
+      await signalEnd()
       expect(fs.existsSync(RUNNING_FILE)).toBe(false)
     })
 
-    it('should not throw if file does not exist', () => {
+    it('should not throw if file does not exist', async () => {
       // Ensure file doesn't exist
       try {
         fs.unlinkSync(RUNNING_FILE)
@@ -147,7 +147,7 @@ describe('CommandExecutor', () => {
         // Ignore
       }
 
-      expect(() => signalEnd()).not.toThrow()
+      await expect(signalEnd()).resolves.toBeUndefined()
     })
   })
 
@@ -158,20 +158,20 @@ describe('CommandExecutor', () => {
       executor = new CommandExecutor()
     })
 
-    it('should have signalStart method that calls module function', () => {
-      executor.signalStart('class-test')
+    it('should have signalStart method that calls module function', async () => {
+      await executor.signalStart('class-test')
 
       expect(fs.existsSync(RUNNING_FILE)).toBe(true)
       const content = fs.readFileSync(RUNNING_FILE, 'utf-8')
       expect(content).toBe('/p:class-test')
 
       // Cleanup
-      executor.signalEnd()
+      await executor.signalEnd()
     })
 
-    it('should have signalEnd method that calls module function', () => {
-      executor.signalStart('class-test')
-      executor.signalEnd()
+    it('should have signalEnd method that calls module function', async () => {
+      await executor.signalStart('class-test')
+      await executor.signalEnd()
 
       expect(fs.existsSync(RUNNING_FILE)).toBe(false)
     })
@@ -336,7 +336,7 @@ describe('execute', () => {
     memorySystem.getRelevantMemories = mock(() => Promise.resolve([]))
 
     // Mock promptBuilder
-    promptBuilder.build = mock(() => 'built prompt')
+    promptBuilder.build = mock(() => Promise.resolve('built prompt'))
   })
 
   afterEach(() => {

package/core/__tests__/agentic/prompt-builder.test.ts

@@ -96,7 +96,7 @@ describe('PromptBuilder', () => {
   })
 
   describe('Context Filtering by Command Type', () => {
-    it('should include patterns for code commands', () => {
+    it('should include patterns for code commands', async () => {
       const template = {
         frontmatter: { description: 'Build feature', name: 'p:build' },
         content: '## Flow\nBuild something',
@@ -105,13 +105,13 @@ describe('PromptBuilder', () => {
       const context = { projectPath: '/test', files: ['file1.js'] }
       const state = { analysis: 'Stack: Node.js, React' }
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt).toContain('PATTERNS')
       expect(prompt).toContain('Node.js')
     })
 
-    it('should NOT include patterns for non-code commands', () => {
+    it('should NOT include patterns for non-code commands', async () => {
       const template = {
         frontmatter: { description: 'Show current task', name: 'p:now' },
         content: '## Flow\nShow task',
@@ -120,14 +120,14 @@ describe('PromptBuilder', () => {
       const context = { projectPath: '/test', files: ['file1.js'] }
       const state = { analysis: 'Stack: Node.js, React' }
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt).not.toContain('## PATTERNS')
     })
   })
 
   describe('Project Files Listing', () => {
-    it('should list available files when context has files', () => {
+    it('should list available files when context has files', async () => {
       const template = {
         frontmatter: { description: 'Test command' },
         content: '## Flow\nDo something',
@@ -140,7 +140,7 @@ describe('PromptBuilder', () => {
 
       const state = {}
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt).toContain('## FILES:')
       expect(prompt).toContain('3 available')
@@ -148,7 +148,7 @@ describe('PromptBuilder', () => {
       expect(prompt).toContain('Read')
     })
 
-    it('should show project path when no files listed', () => {
+    it('should show project path when no files listed', async () => {
       const template = {
         frontmatter: { description: 'Test command' },
         content: '## Flow\nDo something',
@@ -157,7 +157,7 @@ describe('PromptBuilder', () => {
       const context = { projectPath: '/test/project' }
       const state = {}
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt).toContain('## PROJECT:')
       expect(prompt).toContain('/test/project')
@@ -165,7 +165,7 @@ describe('PromptBuilder', () => {
   })
 
   describe('Build Complete Prompt', () => {
-    it('should include all critical sections', () => {
+    it('should include all critical sections', async () => {
       const template = {
         frontmatter: {
           description: 'Test command',
@@ -182,7 +182,7 @@ describe('PromptBuilder', () => {
 
       const state = { now: '# NOW\n\n**Current task**' }
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt).toContain('TASK:')
       expect(prompt).toContain('TOOLS:')
@@ -191,7 +191,7 @@ describe('PromptBuilder', () => {
       expect(prompt).toContain('## FILES:')
     })
 
-    it('should be concise (under 2000 chars for simple prompt)', () => {
+    it('should be concise (under 2000 chars for simple prompt)', async () => {
       const template = {
         frontmatter: { description: 'Test', 'allowed-tools': ['Read'] },
         content: '## Flow\n1. Test',
@@ -200,14 +200,14 @@ describe('PromptBuilder', () => {
       const context = { projectPath: '/test', files: ['a.js'] }
       const state = {}
 
-      const prompt = builder.build(template, context, state)
+      const prompt = await builder.build(template, context, state)
 
       expect(prompt.length).toBeLessThan(2000)
     })
   })
 
   describe('Plan Mode (Compressed)', () => {
-    it('should include compact plan mode instructions', () => {
+    it('should include compact plan mode instructions', async () => {
       const template = {
         frontmatter: { description: 'Test' },
         content: '## Flow\nTest',
@@ -217,14 +217,14 @@ describe('PromptBuilder', () => {
       const state = {}
       const planInfo = { isPlanning: true, allowedTools: ['Read', 'Glob'] }
 
-      const prompt = builder.build(template, context, state, null, null, null, null, planInfo)
+      const prompt = await builder.build(template, context, state, null, null, null, null, planInfo)
 
       expect(prompt).toContain('PLAN MODE')
       expect(prompt).toContain('Read-only')
       expect(prompt).toContain('Tools: Read, Glob')
     })
 
-    it('should include approval required section', () => {
+    it('should include approval required section', async () => {
       const template = {
         frontmatter: { description: 'Test' },
         content: '## Flow\nTest',
@@ -234,7 +234,7 @@ describe('PromptBuilder', () => {
       const state = {}
       const planInfo = { requiresApproval: true }
 
-      const prompt = builder.build(template, context, state, null, null, null, null, planInfo)
+      const prompt = await builder.build(template, context, state, null, null, null, null, planInfo)
 
       expect(prompt).toContain('APPROVAL REQUIRED')
       expect(prompt).toContain('confirmation')

package/core/__tests__/ai-tools/formatters.test.ts

@@ -2,6 +2,7 @@
  * Tests for AI Tools Formatters
  *
  * @see PRJ-122
+ * @see PRJ-113 (citation support)
  */
 
 import { describe, expect, test } from 'bun:test'
@@ -15,6 +16,7 @@ import {
   type ProjectContext,
 } from '../../ai-tools/formatters'
 import { AI_TOOLS, getAIToolConfig } from '../../ai-tools/registry'
+import { type ContextSources, cite, defaultSources } from '../../utils/citations'
 
 // =============================================================================
 // Test Fixtures
@@ -356,3 +358,119 @@ describe('Formatter Edge Cases', () => {
     expect(claudeResult).toContain('@scope/my-project')
   })
 })
+
+// =============================================================================
+// Citation Tests (PRJ-113)
+// =============================================================================
+
+const mockSources: ContextSources = {
+  name: { file: 'package.json', type: 'detected' },
+  version: { file: 'package.json', type: 'detected' },
+  ecosystem: { file: 'package.json', type: 'detected' },
+  languages: { file: 'package.json', type: 'detected' },
+  frameworks: { file: 'package.json', type: 'detected' },
+  commands: { file: 'bun.lockb', type: 'detected' },
+  projectType: { file: 'file count + frameworks', type: 'inferred' },
+  git: { file: 'git', type: 'detected' },
+}
+
+const ctxWithSources: ProjectContext = {
+  ...mockContext,
+  sources: mockSources,
+}
+
+describe('cite() helper', () => {
+  test('generates HTML comment with file and type', () => {
+    const result = cite({ file: 'package.json', type: 'detected' })
+    expect(result).toBe('<!-- source: package.json, detected -->')
+  })
+
+  test('supports inferred type', () => {
+    const result = cite({ file: 'file count + frameworks', type: 'inferred' })
+    expect(result).toBe('<!-- source: file count + frameworks, inferred -->')
+  })
+
+  test('supports user-defined type', () => {
+    const result = cite({ file: 'prjct.yaml', type: 'user-defined' })
+    expect(result).toBe('<!-- source: prjct.yaml, user-defined -->')
+  })
+})
+
+describe('defaultSources()', () => {
+  test('returns all source fields', () => {
+    const sources = defaultSources()
+    expect(sources.name).toBeDefined()
+    expect(sources.version).toBeDefined()
+    expect(sources.ecosystem).toBeDefined()
+    expect(sources.languages).toBeDefined()
+    expect(sources.frameworks).toBeDefined()
+    expect(sources.commands).toBeDefined()
+    expect(sources.projectType).toBeDefined()
+    expect(sources.git).toBeDefined()
+  })
+
+  test('git source is always "git"', () => {
+    const sources = defaultSources()
+    expect(sources.git.file).toBe('git')
+    expect(sources.git.type).toBe('detected')
+  })
+})
+
+describe('Citation integration', () => {
+  test('Claude format includes source citations', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Cursor format includes source citations', () => {
+    const result = formatForCursor(ctxWithSources, AI_TOOLS.cursor)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Windsurf format includes source citations', () => {
+    const result = formatForWindsurf(ctxWithSources, AI_TOOLS.windsurf)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Copilot format includes source citations', () => {
+    const result = formatForCopilot(ctxWithSources, AI_TOOLS.copilot)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('formatters work without sources (backward compatible)', () => {
+    const ctxNoSources = { ...mockContext }
+    delete ctxNoSources.sources
+
+    // Should not throw
+    expect(() => formatForClaude(ctxNoSources, AI_TOOLS.claude)).not.toThrow()
+    expect(() => formatForCursor(ctxNoSources, AI_TOOLS.cursor)).not.toThrow()
+    expect(() => formatForWindsurf(ctxNoSources, AI_TOOLS.windsurf)).not.toThrow()
+    expect(() => formatForCopilot(ctxNoSources, AI_TOOLS.copilot)).not.toThrow()
+
+    // Should still contain default citation comments
+    const result = formatForClaude(ctxNoSources, AI_TOOLS.claude)
+    expect(result).toContain('<!-- source:')
+  })
+
+  test('Claude format has citations before each major section', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    // Ecosystem citation before project type
+    const ecosystemIdx = result.indexOf('<!-- source: package.json, detected -->')
+    const projectTypeIdx = result.indexOf('**Type:**')
+    expect(ecosystemIdx).toBeLessThan(projectTypeIdx)
+
+    // Commands citation before commands table
+    const commandsCiteIdx = result.indexOf('<!-- source: bun.lockb, detected -->')
+    const commandsTableIdx = result.indexOf('| Action | Command |')
+    expect(commandsCiteIdx).toBeLessThan(commandsTableIdx)
+  })
+})