prjct-cli 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,12 +1,128 @@
 # Changelog
 
+## [1.6.0] - 2026-02-06
+
+### Features
+
+- super context for agents — skills.sh, proactive codebase context, effort/model (#121)
+
+
+## [1.6.0] - 2026-02-06
+
+### Features
+
+- **Skills.sh auto-install**: During `prjct sync`, skills from skills.sh are automatically installed for generated agents. Real packages like `anthropics/skills/frontend-design`, `obra/superpowers/systematic-debugging`, and `obra/superpowers/test-driven-development` are mapped per agent domain.
+- **Proactive codebase context**: The orchestrator now gathers real context before agent execution — git state, relevant files (scored by task relevance), code signatures from top files, and recently changed files. Agents start with a complete briefing instead of exploring first.
+- **Effort/model metadata wiring**: Agent frontmatter `effort` and `model` fields are now extracted and injected into prompts, enabling per-agent reasoning depth control.
+
+### Improved
+
+- **Skill loading warnings**: Missing skills now log visible warnings with the agent that needs them and a hint to run `prjct sync`
+- **Skill content in prompts**: Increased skill content truncation from 1000 to 2000 characters for richer context
+- **Skill mappings v3**: Updated `skill-mappings.json` from generic names to real installable skills.sh packages
+
+### Implementation Details
+
+- `sync-service.ts`: New `autoInstallSkills()` method reads `skill-mappings.json`, checks if each skill is installed, and calls `skillInstaller.install()` for missing ones
+- `orchestrator-executor.ts`: New `gatherRealContext()` calls `findRelevantFiles()`, `getRecentFiles()`, and `extractSignatures()` in parallel to build a proactive briefing
+- `prompt-builder.ts`: New "CODEBASE CONTEXT" section with git state, relevant files table, code signatures, and recently changed files; plus effort/model per agent
+- `agent-loader.ts`: New `extractFrontmatterMeta()` parses YAML frontmatter for effort/model fields
+- `agentic.ts`: New `RealCodebaseContext` interface; `LoadedAgent` extended with `effort?` and `model?`
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` — verify skills auto-install (check `~/.claude/skills/`)
+2. Run `p. task "test"` — verify prompt includes git state, relevant files, signatures, effort/model
+3. Verify warnings for missing skills
+4. Build and all 416 tests pass
+
+#### For Users
+**What changed:** Agents receive proactive codebase context before starting work. Skills auto-install during sync.
+**How to use:** No action needed — automatic during `prjct sync` and `p. task`.
+**Breaking changes:** None
+
+## [1.5.2] - 2026-02-06
+
+### Improved
+
+- **TTY detection for CLI spinners**: Spinner, step, and progress animations now detect non-TTY environments (CI/CD, Claude Code, piped output) and print a single static line instead of animating
+
+### Implementation Details
+
+- Added `process.stdout.isTTY` guard to `spin()`, `step()`, and `progress()` in `core/utils/output.ts`
+- Non-TTY environments get a single line with `\n` instead of `setInterval` with `\r` carriage returns
+- Made `clear()` a no-op in non-TTY (the `\r` + spaces trick doesn't work outside terminals)
+- Updated test for `stop()` to handle non-TTY behavior in test runner
+
+### Learnings
+
+- `process.stdout.isTTY` is the reliable built-in way to detect interactive terminals in Node.js
+- Test suites (bun test) also run as non-TTY, so test assertions need to account for both paths
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` in an interactive terminal — spinner should animate normally
+2. Run `prjct sync --yes > out.txt` — output should show a single static line, no repeated frames
+3. Run inside Claude Code Bash tool — output should be clean, no spinner noise
+4. Verify `step()` and `progress()` behave the same way in both environments
+
+#### For Users
+**What changed:** CLI spinners no longer produce garbage output in non-interactive terminals
+**How to use:** No action needed — automatic TTY detection
+**Breaking changes:** None
+
+## [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

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__/utils/output.test.ts

@@ -124,7 +124,13 @@ describe('Output Module', () => {
       stdoutWriteSpy.mockClear()
       out.stop()
 
-      expect(stdoutWriteSpy).toHaveBeenCalled()
+      // In TTY, stop() writes a clear sequence; in non-TTY, spinner doesn't
+      // use setInterval so stop() is a no-op (clear skips in non-TTY)
+      if (process.stdout.isTTY) {
+        expect(stdoutWriteSpy).toHaveBeenCalled()
+      } else {
+        expect(stdoutWriteSpy).not.toHaveBeenCalled()
+      }
     })
 
     it('should be safe to call multiple times', () => {

package/core/agentic/command-executor.ts

@@ -6,7 +6,7 @@
  * @version 3.4
  */
 
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import type {
@@ -18,6 +18,7 @@ import type {
   SimpleExecutionResult,
 } from '../types'
 import { agentStream } from '../utils/agent-stream'
+import { fileExists } from '../utils/fs-helpers'
 import { printSubtaskProgress, type SubtaskDisplay } from '../utils/subtask-table'
 import chainOfThought from './chain-of-thought'
 import contextBuilder from './context-builder'
@@ -40,13 +41,13 @@ const RUNNING_FILE = path.join(os.homedir(), '.prjct-cli', '.running')
 /**
  * Signal that a command is running (for status line)
  */
-export function signalStart(commandName: string): void {
+export async function signalStart(commandName: string): Promise<void> {
   try {
     const dir = path.dirname(RUNNING_FILE)
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
+    if (!(await fileExists(dir))) {
+      await fs.mkdir(dir, { recursive: true })
     }
-    fs.writeFileSync(RUNNING_FILE, `/p:${commandName}`)
+    await fs.writeFile(RUNNING_FILE, `/p:${commandName}`)
   } catch (_error) {
     // Silently ignore - status line is optional
   }
@@ -55,10 +56,10 @@ export function signalStart(commandName: string): void {
 /**
  * Signal that command has finished (for status line)
  */
-export function signalEnd(): void {
+export async function signalEnd(): Promise<void> {
   try {
-    if (fs.existsSync(RUNNING_FILE)) {
-      fs.unlinkSync(RUNNING_FILE)
+    if (await fileExists(RUNNING_FILE)) {
+      await fs.unlink(RUNNING_FILE)
     }
   } catch (_error) {
     // Silently ignore - status line is optional
@@ -73,15 +74,15 @@ export class CommandExecutor {
   /**
    * Signal that a command is running (for status line)
    */
-  signalStart(commandName: string): void {
-    signalStart(commandName)
+  async signalStart(commandName: string): Promise<void> {
+    await signalStart(commandName)
   }
 
   /**
    * Signal that command has finished (for status line)
    */
-  signalEnd(): void {
-    signalEnd()
+  async signalEnd(): Promise<void> {
+    await signalEnd()
   }
 
   /**
@@ -93,7 +94,7 @@ export class CommandExecutor {
     projectPath: string
   ): Promise<ExecutionResult> {
     // Signal start for status line
-    this.signalStart(commandName)
+    await this.signalStart(commandName)
 
     // Context for loop detection
     const loopContext = (params.task as string) || (params.description as string) || ''
@@ -101,7 +102,7 @@ export class CommandExecutor {
     // Check if we're in a loop BEFORE attempting
     if (loopDetector.shouldEscalate(commandName, loopContext)) {
       const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
-      this.signalEnd()
+      await this.signalEnd()
       return {
         success: false,
         error: escalation?.message,
@@ -264,7 +265,7 @@ export class CommandExecutor {
       }
       // Agent is null - Claude assigns via Task tool using agent-routing.md
       // Pass orchestratorContext for domain/agent/subtask injection
-      const prompt = promptBuilder.build(
+      const prompt = await promptBuilder.build(
         template,
         context,
         state,
@@ -286,7 +287,7 @@ export class CommandExecutor {
       loopDetector.recordSuccess(commandName, loopContext)
 
       // Signal end for status line
-      this.signalEnd()
+      await this.signalEnd()
 
       return {
         success: true,
@@ -373,7 +374,7 @@ export class CommandExecutor {
       }
     } catch (error) {
       // Signal end for status line
-      this.signalEnd()
+      await this.signalEnd()
 
       // Record failed attempt for loop detection
       const attemptInfo = loopDetector.recordAttempt(commandName, loopContext, {