prjct-cli 1.4.0 → 1.5.1

package/core/infrastructure/update-checker.ts

@@ -4,11 +4,12 @@
  * @version 0.5.0
  */
 
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 import https from 'node:https'
 import os from 'node:os'
 import path from 'node:path'
 import chalk from 'chalk'
+import { fileExists } from '../utils/fs-helpers'
 
 interface UpdateCache {
   lastCheck: number
@@ -37,10 +38,10 @@ class UpdateChecker {
   /**
    * Get current installed version from package.json
    */
-  getCurrentVersion(): string | null {
+  async getCurrentVersion(): Promise<string | null> {
     try {
       const packageJsonPath = path.join(__dirname, '..', '..', 'package.json')
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+      const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'))
       return packageJson.version
     } catch (error) {
       console.error('Error reading package version:', (error as Error).message)
@@ -119,10 +120,10 @@ class UpdateChecker {
   /**
    * Read cache file
    */
-  readCache(): UpdateCache | null {
+  async readCache(): Promise<UpdateCache | null> {
     try {
-      if (fs.existsSync(this.cacheFile)) {
-        const cache = JSON.parse(fs.readFileSync(this.cacheFile, 'utf8'))
+      if (await fileExists(this.cacheFile)) {
+        const cache = JSON.parse(await fs.readFile(this.cacheFile, 'utf8'))
         return cache
       }
     } catch (_error) {
@@ -134,14 +135,14 @@ class UpdateChecker {
   /**
    * Write cache file
    */
-  writeCache(data: UpdateCache): void {
+  async writeCache(data: UpdateCache): Promise<void> {
     try {
       // Ensure cache directory exists
-      if (!fs.existsSync(this.cacheDir)) {
-        fs.mkdirSync(this.cacheDir, { recursive: true })
+      if (!(await fileExists(this.cacheDir))) {
+        await fs.mkdir(this.cacheDir, { recursive: true })
       }
 
-      fs.writeFileSync(this.cacheFile, JSON.stringify(data, null, 2), 'utf8')
+      await fs.writeFile(this.cacheFile, JSON.stringify(data, null, 2), 'utf8')
     } catch (_error) {
       // Fail silently - cache is not critical
     }
@@ -153,13 +154,13 @@ class UpdateChecker {
    */
   async checkForUpdates(): Promise<UpdateResult | null> {
     try {
-      const currentVersion = this.getCurrentVersion()
+      const currentVersion = await this.getCurrentVersion()
       if (!currentVersion) {
         return null
       }
 
       // Check cache first
-      const cache = this.readCache()
+      const cache = await this.readCache()
       const now = Date.now()
 
       if (cache?.lastCheck && now - cache.lastCheck < this.checkInterval) {
@@ -182,7 +183,7 @@ class UpdateChecker {
       const latestVersion = await this.getLatestVersion()
 
       // Update cache
-      this.writeCache({
+      await this.writeCache({
         lastCheck: now,
         latestVersion,
       })

package/core/integrations/linear/sync.ts

@@ -14,7 +14,6 @@
  *   state.json.currentTask.linearId ← DIRECT LINK
  */
 
-import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import {
@@ -25,6 +24,7 @@ import {
   type SyncResult,
 } from '../../schemas/issues'
 import { getProjectPath } from '../../schemas/schemas'
+import { fileExists } from '../../utils/fs-helpers'
 import type { Issue } from '../issue-tracker/types'
 import { linearService } from './service'
 
@@ -41,7 +41,7 @@ export class LinearSync {
     const issuesPath = join(storagePath, 'issues.json')
 
     // Ensure storage directory exists
-    if (!existsSync(storagePath)) {
+    if (!(await fileExists(storagePath))) {
       await mkdir(storagePath, { recursive: true })
     }
 
@@ -241,7 +241,7 @@ export class LinearSync {
   private async loadIssues(projectId: string): Promise<IssuesJson | null> {
     const issuesPath = join(getProjectPath(projectId), 'storage', 'issues.json')
 
-    if (!existsSync(issuesPath)) {
+    if (!(await fileExists(issuesPath))) {
       return null
     }
 
@@ -260,7 +260,7 @@ export class LinearSync {
     const storagePath = join(getProjectPath(projectId), 'storage')
     const issuesPath = join(storagePath, 'issues.json')
 
-    if (!existsSync(storagePath)) {
+    if (!(await fileExists(storagePath))) {
       await mkdir(storagePath, { recursive: true })
     }
 

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import pathManager from '../infrastructure/path-manager'
+import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
 import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 import { NestedContextResolver } from './nested-context-resolver'
@@ -103,13 +104,14 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<string[]> {
     const contextPath = path.join(this.config.globalPath, 'context')
 
     // Generate all context files IN PARALLEL
     await Promise.all([
-      this.generateClaudeMd(contextPath, git, stats, commands, agents),
+      this.generateClaudeMd(contextPath, git, stats, commands, agents, sources),
       this.generateNowMd(contextPath),
       this.generateNextMd(contextPath),
       this.generateIdeasMd(contextPath),
@@ -137,10 +139,12 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<void> {
     const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
     const domainAgents = agents.filter((a) => a.type === 'domain').map((a) => a.name)
+    const s = sources || defaultSources()
 
     const content = `# ${stats.name} - Project Rules
 <!-- projectId: ${this.config.projectId} -->
@@ -149,11 +153,13 @@ export class ContextFileGenerator {
 
 ## THIS PROJECT (${stats.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${stats.projectType}
 **Path:** ${this.config.projectPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${commands.install}\` |
@@ -165,7 +171,9 @@ export class ContextFileGenerator {
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${stats.languages.join(', ') || 'Not detected'}
+${cite(s.frameworks)}
 - **Frameworks**: ${stats.frameworks.join(', ') || 'Not detected'}
 
 ---
@@ -193,6 +201,7 @@ p. sync → p. task "desc" → [work] → p. done → p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${stats.name} |

package/core/services/hooks-service.ts

@@ -11,10 +11,11 @@
  * @module services/hooks-service
  */
 
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 import path from 'node:path'
 import chalk from 'chalk'
 import configManager from '../infrastructure/config-manager'
+import { fileExists } from '../utils/fs-helpers'
 import out from '../utils/output'
 
 // ============================================================================
@@ -129,27 +130,27 @@ exit 0
 /**
  * Detect which hook managers are available in the project
  */
-function detectHookManagers(projectPath: string): HookStrategy[] {
+async function detectHookManagers(projectPath: string): Promise<HookStrategy[]> {
   const detected: HookStrategy[] = []
 
   // Check for lefthook
   if (
-    fs.existsSync(path.join(projectPath, 'lefthook.yml')) ||
-    fs.existsSync(path.join(projectPath, 'lefthook.yaml'))
+    (await fileExists(path.join(projectPath, 'lefthook.yml'))) ||
+    (await fileExists(path.join(projectPath, 'lefthook.yaml')))
   ) {
     detected.push('lefthook')
   }
 
   // Check for husky
   if (
-    fs.existsSync(path.join(projectPath, '.husky')) ||
-    fs.existsSync(path.join(projectPath, '.husky', '_'))
+    (await fileExists(path.join(projectPath, '.husky'))) ||
+    (await fileExists(path.join(projectPath, '.husky', '_')))
   ) {
     detected.push('husky')
   }
 
   // Direct .git/hooks is always available if it's a git repo
-  if (fs.existsSync(path.join(projectPath, '.git'))) {
+  if (await fileExists(path.join(projectPath, '.git'))) {
     detected.push('direct')
   }
 
@@ -173,13 +174,13 @@ function selectStrategy(detected: HookStrategy[]): HookStrategy {
 /**
  * Install hooks via lefthook (append to existing config)
  */
-function installLefthook(projectPath: string, hooks: HookName[]): boolean {
-  const configFile = fs.existsSync(path.join(projectPath, 'lefthook.yml'))
+async function installLefthook(projectPath: string, hooks: HookName[]): Promise<boolean> {
+  const configFile = (await fileExists(path.join(projectPath, 'lefthook.yml')))
     ? 'lefthook.yml'
     : 'lefthook.yaml'
   const configPath = path.join(projectPath, configFile)
 
-  let content = fs.readFileSync(configPath, 'utf-8')
+  let content = await fs.readFile(configPath, 'utf-8')
 
   for (const hook of hooks) {
     const sectionName = hook // e.g. "post-commit"
@@ -212,29 +213,29 @@ ${sectionName}:
     }
   }
 
-  fs.writeFileSync(configPath, content, 'utf-8')
+  await fs.writeFile(configPath, content, 'utf-8')
   return true
 }
 
 /**
  * Install hooks via husky
  */
-function installHusky(projectPath: string, hooks: HookName[]): boolean {
+async function installHusky(projectPath: string, hooks: HookName[]): Promise<boolean> {
   const huskyDir = path.join(projectPath, '.husky')
 
   for (const hook of hooks) {
     const hookPath = path.join(huskyDir, hook)
     const script = hook === 'post-commit' ? getPostCommitScript() : getPostCheckoutScript()
 
-    if (fs.existsSync(hookPath)) {
+    if (await fileExists(hookPath)) {
       // Append to existing hook if not already present
-      const existing = fs.readFileSync(hookPath, 'utf-8')
+      const existing = await fs.readFile(hookPath, 'utf-8')
       if (existing.includes('prjct sync')) {
         continue
       }
-      fs.appendFileSync(hookPath, '\n# prjct auto-sync\nprjct sync --quiet --yes &\n')
+      await fs.appendFile(hookPath, '\n# prjct auto-sync\nprjct sync --quiet --yes &\n')
     } else {
-      fs.writeFileSync(hookPath, script, { mode: 0o755 })
+      await fs.writeFile(hookPath, script, { mode: 0o755 })
     }
   }
 
@@ -244,26 +245,29 @@ function installHusky(projectPath: string, hooks: HookName[]): boolean {
 /**
  * Install hooks directly into .git/hooks/
  */
-function installDirect(projectPath: string, hooks: HookName[]): boolean {
+async function installDirect(projectPath: string, hooks: HookName[]): Promise<boolean> {
   const hooksDir = path.join(projectPath, '.git', 'hooks')
 
-  if (!fs.existsSync(hooksDir)) {
-    fs.mkdirSync(hooksDir, { recursive: true })
+  if (!(await fileExists(hooksDir))) {
+    await fs.mkdir(hooksDir, { recursive: true })
   }
 
   for (const hook of hooks) {
     const hookPath = path.join(hooksDir, hook)
     const script = hook === 'post-commit' ? getPostCommitScript() : getPostCheckoutScript()
 
-    if (fs.existsSync(hookPath)) {
-      const existing = fs.readFileSync(hookPath, 'utf-8')
+    if (await fileExists(hookPath)) {
+      const existing = await fs.readFile(hookPath, 'utf-8')
       if (existing.includes('prjct sync')) {
         continue // Already installed
       }
       // Append to existing hook
-      fs.appendFileSync(hookPath, `\n# prjct auto-sync\n${script.split('\n').slice(1).join('\n')}`)
+      await fs.appendFile(
+        hookPath,
+        `\n# prjct auto-sync\n${script.split('\n').slice(1).join('\n')}`
+      )
     } else {
-      fs.writeFileSync(hookPath, script, { mode: 0o755 })
+      await fs.writeFile(hookPath, script, { mode: 0o755 })
     }
   }
 
@@ -274,15 +278,15 @@ function installDirect(projectPath: string, hooks: HookName[]): boolean {
 // UNINSTALL STRATEGIES
 // ============================================================================
 
-function uninstallLefthook(projectPath: string): boolean {
-  const configFile = fs.existsSync(path.join(projectPath, 'lefthook.yml'))
+async function uninstallLefthook(projectPath: string): Promise<boolean> {
+  const configFile = (await fileExists(path.join(projectPath, 'lefthook.yml')))
     ? 'lefthook.yml'
     : 'lefthook.yaml'
   const configPath = path.join(projectPath, configFile)
 
-  if (!fs.existsSync(configPath)) return false
+  if (!(await fileExists(configPath))) return false
 
-  let content = fs.readFileSync(configPath, 'utf-8')
+  let content = await fs.readFile(configPath, 'utf-8')
 
   // Remove prjct-sync commands
   content = content.replace(/\s*prjct-sync-[\w-]+:[\s\S]*?(?=\n\S|\n*$)/g, '')
@@ -290,18 +294,18 @@ function uninstallLefthook(projectPath: string): boolean {
   // Clean up empty sections
   content = content.replace(/^(post-commit|post-checkout):\s*commands:\s*$/gm, '')
 
-  fs.writeFileSync(configPath, `${content.trimEnd()}\n`, 'utf-8')
+  await fs.writeFile(configPath, `${content.trimEnd()}\n`, 'utf-8')
   return true
 }
 
-function uninstallHusky(projectPath: string): boolean {
+async function uninstallHusky(projectPath: string): Promise<boolean> {
   const huskyDir = path.join(projectPath, '.husky')
 
   for (const hook of ['post-commit', 'post-checkout'] as HookName[]) {
     const hookPath = path.join(huskyDir, hook)
-    if (!fs.existsSync(hookPath)) continue
+    if (!(await fileExists(hookPath))) continue
 
-    const content = fs.readFileSync(hookPath, 'utf-8')
+    const content = await fs.readFile(hookPath, 'utf-8')
     if (!content.includes('prjct sync')) continue
 
     // Remove prjct lines
@@ -312,35 +316,35 @@ function uninstallHusky(projectPath: string): boolean {
 
     if (cleaned.trim() === '#!/bin/sh' || cleaned.trim() === '#!/usr/bin/env sh') {
       // Hook is now empty, remove it
-      fs.unlinkSync(hookPath)
+      await fs.unlink(hookPath)
     } else {
-      fs.writeFileSync(hookPath, cleaned, { mode: 0o755 })
+      await fs.writeFile(hookPath, cleaned, { mode: 0o755 })
     }
   }
 
   return true
 }
 
-function uninstallDirect(projectPath: string): boolean {
+async function uninstallDirect(projectPath: string): Promise<boolean> {
   const hooksDir = path.join(projectPath, '.git', 'hooks')
 
   for (const hook of ['post-commit', 'post-checkout'] as HookName[]) {
     const hookPath = path.join(hooksDir, hook)
-    if (!fs.existsSync(hookPath)) continue
+    if (!(await fileExists(hookPath))) continue
 
-    const content = fs.readFileSync(hookPath, 'utf-8')
+    const content = await fs.readFile(hookPath, 'utf-8')
     if (!content.includes('prjct sync')) continue
 
     if (content.includes('Installed by: prjct hooks install')) {
       // Entirely ours, remove it
-      fs.unlinkSync(hookPath)
+      await fs.unlink(hookPath)
     } else {
       // Shared hook, just remove our lines
       const cleaned = content
         .split('\n')
         .filter((line) => !line.includes('prjct sync') && !line.includes('prjct auto-sync'))
         .join('\n')
-      fs.writeFileSync(hookPath, cleaned, { mode: 0o755 })
+      await fs.writeFile(hookPath, cleaned, { mode: 0o755 })
     }
   }
 
@@ -362,7 +366,7 @@ class HooksService {
     const hooks: HookName[] = options.hooks || ['post-commit', 'post-checkout']
 
     // Detect available managers
-    const detected = detectHookManagers(projectPath)
+    const detected = await detectHookManagers(projectPath)
 
     if (detected.length === 0) {
       return {
@@ -380,13 +384,13 @@ class HooksService {
 
       switch (strategy) {
         case 'lefthook':
-          success = installLefthook(projectPath, hooks)
+          success = await installLefthook(projectPath, hooks)
           break
         case 'husky':
-          success = installHusky(projectPath, hooks)
+          success = await installHusky(projectPath, hooks)
           break
         case 'direct':
-          success = installDirect(projectPath, hooks)
+          success = await installDirect(projectPath, hooks)
           break
       }
 
@@ -428,13 +432,13 @@ class HooksService {
 
       switch (strategy) {
         case 'lefthook':
-          success = uninstallLefthook(projectPath)
+          success = await uninstallLefthook(projectPath)
           break
         case 'husky':
-          success = uninstallHusky(projectPath)
+          success = await uninstallHusky(projectPath)
           break
         case 'direct':
-          success = uninstallDirect(projectPath)
+          success = await uninstallDirect(projectPath)
           break
       }
 
@@ -457,15 +461,17 @@ class HooksService {
    * Get hook installation status
    */
   async status(projectPath: string): Promise<HooksStatusResult> {
-    const detected = detectHookManagers(projectPath)
+    const detected = await detectHookManagers(projectPath)
     const config = await this.getHookConfig(projectPath)
 
     const hookNames: HookName[] = ['post-commit', 'post-checkout']
-    const hooks = hookNames.map((name) => ({
-      name,
-      installed: this.isHookInstalled(projectPath, name, config?.strategy || null),
-      path: this.getHookPath(projectPath, name, config?.strategy || null),
-    }))
+    const hooks = await Promise.all(
+      hookNames.map(async (name) => ({
+        name,
+        installed: await this.isHookInstalled(projectPath, name, config?.strategy || null),
+        path: await this.getHookPath(projectPath, name, config?.strategy || null),
+      }))
+    )
 
     return {
       installed: hooks.some((h) => h.installed),
@@ -506,7 +512,7 @@ class HooksService {
     out.start()
     out.section('Git Hooks Installation')
 
-    const detected = detectHookManagers(projectPath)
+    const detected = await detectHookManagers(projectPath)
     const strategy = selectStrategy(detected)
 
     console.log(`  Strategy: ${chalk.cyan(strategy)}`)
@@ -589,36 +595,40 @@ class HooksService {
   // HELPERS
   // ==========================================================================
 
-  private isHookInstalled(
+  private async isHookInstalled(
     projectPath: string,
     hook: HookName,
     strategy: HookStrategy | null
-  ): boolean {
+  ): Promise<boolean> {
     if (strategy === 'lefthook') {
-      const configFile = fs.existsSync(path.join(projectPath, 'lefthook.yml'))
+      const configFile = (await fileExists(path.join(projectPath, 'lefthook.yml')))
         ? 'lefthook.yml'
         : 'lefthook.yaml'
       const configPath = path.join(projectPath, configFile)
-      if (!fs.existsSync(configPath)) return false
-      const content = fs.readFileSync(configPath, 'utf-8')
+      if (!(await fileExists(configPath))) return false
+      const content = await fs.readFile(configPath, 'utf-8')
       return content.includes(`prjct-sync-${hook}`)
     }
 
     if (strategy === 'husky') {
       const hookPath = path.join(projectPath, '.husky', hook)
-      if (!fs.existsSync(hookPath)) return false
-      return fs.readFileSync(hookPath, 'utf-8').includes('prjct sync')
+      if (!(await fileExists(hookPath))) return false
+      return (await fs.readFile(hookPath, 'utf-8')).includes('prjct sync')
     }
 
     // Direct
     const hookPath = path.join(projectPath, '.git', 'hooks', hook)
-    if (!fs.existsSync(hookPath)) return false
-    return fs.readFileSync(hookPath, 'utf-8').includes('prjct sync')
+    if (!(await fileExists(hookPath))) return false
+    return (await fs.readFile(hookPath, 'utf-8')).includes('prjct sync')
   }
 
-  private getHookPath(projectPath: string, hook: HookName, strategy: HookStrategy | null): string {
+  private async getHookPath(
+    projectPath: string,
+    hook: HookName,
+    strategy: HookStrategy | null
+  ): Promise<string> {
     if (strategy === 'lefthook') {
-      return fs.existsSync(path.join(projectPath, 'lefthook.yml'))
+      return (await fileExists(path.join(projectPath, 'lefthook.yml')))
         ? 'lefthook.yml'
         : 'lefthook.yaml'
     }
@@ -640,8 +650,8 @@ class HooksService {
         projectId,
         'project.json'
       )
-      if (!fs.existsSync(projectJsonPath)) return null
-      const project = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'))
+      if (!(await fileExists(projectJsonPath))) return null
+      const project = JSON.parse(await fs.readFile(projectJsonPath, 'utf-8'))
       return project.hooks || null
     } catch {
       return null
@@ -660,11 +670,11 @@ class HooksService {
         projectId,
         'project.json'
       )
-      if (!fs.existsSync(projectJsonPath)) return
+      if (!(await fileExists(projectJsonPath))) return
 
-      const project = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'))
+      const project = JSON.parse(await fs.readFile(projectJsonPath, 'utf-8'))
       project.hooks = config
-      fs.writeFileSync(projectJsonPath, JSON.stringify(project, null, 2))
+      await fs.writeFile(projectJsonPath, JSON.stringify(project, null, 2))
     } catch {
       // Non-fatal
     }