prjct-cli 1.3.0 → 1.5.0

package/core/services/sync-service.ts

@@ -30,11 +30,13 @@ import commandInstaller from '../infrastructure/command-installer'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
 import { metricsStorage } from '../storage/metrics-storage'
+import { type ContextSources, defaultSources, type SourceInfo } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
 import { ContextFileGenerator } from './context-generator'
 import type { SyncDiff } from './diff-generator'
 import { localStateGenerator } from './local-state-generator'
 import { type StackDetection, StackDetector } from './stack-detector'
+import { syncVerifier, type VerificationReport } from './sync-verifier'
 
 const execAsync = promisify(exec)
 
@@ -106,6 +108,7 @@ interface SyncResult {
   contextFiles: string[]
   aiTools: AIToolResult[]
   syncMetrics?: SyncMetrics
+  verification?: VerificationReport
   error?: string
   // Preview mode fields
   isPreview?: boolean
@@ -200,7 +203,8 @@ class SyncService {
       // 4. Generate all files (depends on gathered data)
       const agents = await this.generateAgents(stack, stats)
       const skills = this.configureSkills(agents)
-      const contextFiles = await this.generateContextFiles(git, stats, commands, agents)
+      const sources = this.buildSources(stats, commands)
+      const contextFiles = await this.generateContextFiles(git, stats, commands, agents, sources)
 
       // 5. Generate AI tool context files (multi-agent output)
       const projectContext: ProjectContext = {
@@ -221,6 +225,7 @@ class SyncService {
           workflow: agents.filter((a) => a.type === 'workflow').map((a) => a.name),
           domain: agents.filter((a) => a.type === 'domain').map((a) => a.name),
         },
+        sources,
       }
 
       const aiToolResults = await generateAIToolContexts(
@@ -246,6 +251,19 @@ class SyncService {
       await commandInstaller.installGlobalConfig()
       await commandInstaller.syncCommands()
 
+      // 11. Run verification checks (built-in + custom from config)
+      let verification: VerificationReport | undefined
+      try {
+        const localConfig = await configManager.readConfig(this.projectPath)
+        verification = await syncVerifier.verify(
+          this.projectPath,
+          this.globalPath,
+          localConfig?.verification
+        )
+      } catch {
+        // Verification is non-critical — don't fail sync
+      }
+
       return {
         success: true,
         projectId: this.projectId,
@@ -263,6 +281,7 @@ class SyncService {
           success: r.success,
         })),
         syncMetrics,
+        verification,
       }
     } catch (error) {
       return {
@@ -519,6 +538,54 @@ class SyncService {
     return commands
   }
 
+  // ==========================================================================
+  // SOURCE CITATIONS
+  // ==========================================================================
+
+  private buildSources(stats: ProjectStats, commands: Commands): ContextSources {
+    const sources = defaultSources()
+
+    // Determine ecosystem source file
+    const ecosystemFiles: Record<string, string> = {
+      JavaScript: 'package.json',
+      Rust: 'Cargo.toml',
+      Go: 'go.mod',
+      Python: 'pyproject.toml',
+    }
+    const ecosystemFile = ecosystemFiles[stats.ecosystem] || 'filesystem'
+    const detected = (file: string): SourceInfo => ({ file, type: 'detected' })
+    const inferred = (file: string): SourceInfo => ({ file, type: 'inferred' })
+
+    sources.ecosystem = detected(ecosystemFile)
+    sources.name = detected(ecosystemFile)
+    sources.version = detected(ecosystemFile)
+    sources.languages = detected(ecosystemFile)
+    sources.frameworks = detected(ecosystemFile)
+
+    // Commands source is the lock file or ecosystem file
+    if (commands.install.startsWith('bun')) {
+      sources.commands = detected('bun.lockb')
+    } else if (commands.install.startsWith('pnpm')) {
+      sources.commands = detected('pnpm-lock.yaml')
+    } else if (commands.install === 'yarn') {
+      sources.commands = detected('yarn.lock')
+    } else if (commands.install.startsWith('cargo')) {
+      sources.commands = detected('Cargo.toml')
+    } else if (commands.install.startsWith('go')) {
+      sources.commands = detected('go.mod')
+    } else {
+      sources.commands = detected('package.json')
+    }
+
+    // Project type is inferred from file count + framework count
+    sources.projectType = inferred('file count + frameworks')
+
+    // Git is always from git
+    sources.git = detected('git')
+
+    return sources
+  }
+
   // ==========================================================================
   // STACK DETECTION
   // ==========================================================================
@@ -741,7 +808,8 @@ You are the ${name} expert for this project. Apply best practices for the detect
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<string[]> {
     const generator = new ContextFileGenerator({
       projectId: this.projectId!,
@@ -749,7 +817,13 @@ You are the ${name} expert for this project. Apply best practices for the detect
       globalPath: this.globalPath,
     })
 
-    return generator.generate({ branch: git.branch, commits: git.commits }, stats, commands, agents)
+    return generator.generate(
+      { branch: git.branch, commits: git.commits },
+      stats,
+      commands,
+      agents,
+      sources
+    )
   }
 
   // ==========================================================================

package/core/services/sync-verifier.ts

@@ -0,0 +1,273 @@
+/**
+ * SyncVerifier - Programmatic verification checks for sync workflow
+ *
+ * Runs configurable checks after sync to validate generated output.
+ * Supports built-in checks and custom user commands.
+ *
+ * @see PRJ-106
+ */
+
+import { exec } from 'node:child_process'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { promisify } from 'node:util'
+import { isNotFoundError } from '../types/fs'
+
+const execAsync = promisify(exec)
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface VerificationCheck {
+  name: string
+  command?: string
+  script?: string
+  enabled?: boolean
+}
+
+export interface VerificationConfig {
+  checks?: VerificationCheck[]
+  failFast?: boolean
+}
+
+export interface CheckResult {
+  name: string
+  passed: boolean
+  output?: string
+  error?: string
+  durationMs: number
+}
+
+export interface VerificationReport {
+  passed: boolean
+  checks: CheckResult[]
+  totalMs: number
+  failedCount: number
+  passedCount: number
+  skippedCount: number
+}
+
+// =============================================================================
+// BUILT-IN CHECKS
+// =============================================================================
+
+const BUILTIN_CHECKS = {
+  /**
+   * Verify all expected context files exist after sync
+   */
+  async contextFilesExist(globalPath: string): Promise<CheckResult> {
+    const start = Date.now()
+    const expected = ['context/CLAUDE.md']
+    const missing: string[] = []
+
+    for (const file of expected) {
+      const filePath = path.join(globalPath, file)
+      try {
+        await fs.access(filePath)
+      } catch {
+        missing.push(file)
+      }
+    }
+
+    return {
+      name: 'Context files exist',
+      passed: missing.length === 0,
+      output: missing.length === 0 ? `${expected.length} files verified` : undefined,
+      error: missing.length > 0 ? `Missing: ${missing.join(', ')}` : undefined,
+      durationMs: Date.now() - start,
+    }
+  },
+
+  /**
+   * Verify generated JSON files are valid
+   */
+  async jsonFilesValid(globalPath: string): Promise<CheckResult> {
+    const start = Date.now()
+    const jsonFiles = ['storage/state.json']
+    const invalid: string[] = []
+
+    for (const file of jsonFiles) {
+      const filePath = path.join(globalPath, file)
+      try {
+        const content = await fs.readFile(filePath, 'utf-8')
+        JSON.parse(content)
+      } catch (error) {
+        if (!isNotFoundError(error)) {
+          invalid.push(`${file}: ${error instanceof SyntaxError ? 'invalid JSON' : 'read error'}`)
+        }
+      }
+    }
+
+    return {
+      name: 'JSON files valid',
+      passed: invalid.length === 0,
+      output: invalid.length === 0 ? `${jsonFiles.length} files validated` : undefined,
+      error: invalid.length > 0 ? invalid.join('; ') : undefined,
+      durationMs: Date.now() - start,
+    }
+  },
+
+  /**
+   * Verify no sensitive data leaked into context files
+   */
+  async noSensitiveData(globalPath: string): Promise<CheckResult> {
+    const start = Date.now()
+    const contextDir = path.join(globalPath, 'context')
+    const patterns = [
+      /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{10,}/i,
+      /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]{4,}/i,
+      /(?:secret|token)\s*[:=]\s*['"][^'"]{10,}/i,
+    ]
+    const violations: string[] = []
+
+    try {
+      const files = await fs.readdir(contextDir)
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue
+        const content = await fs.readFile(path.join(contextDir, file), 'utf-8')
+        for (const pattern of patterns) {
+          if (pattern.test(content)) {
+            violations.push(`${file}: potential sensitive data detected`)
+            break
+          }
+        }
+      }
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        return {
+          name: 'No sensitive data',
+          passed: false,
+          error: `Could not scan: ${(error as Error).message}`,
+          durationMs: Date.now() - start,
+        }
+      }
+    }
+
+    return {
+      name: 'No sensitive data',
+      passed: violations.length === 0,
+      output: violations.length === 0 ? 'No sensitive patterns found' : undefined,
+      error: violations.length > 0 ? violations.join('; ') : undefined,
+      durationMs: Date.now() - start,
+    }
+  },
+}
+
+// =============================================================================
+// SYNC VERIFIER
+// =============================================================================
+
+class SyncVerifier {
+  /**
+   * Run all verification checks (built-in + custom)
+   */
+  async verify(
+    projectPath: string,
+    globalPath: string,
+    config?: VerificationConfig
+  ): Promise<VerificationReport> {
+    const totalStart = Date.now()
+    const checks: CheckResult[] = []
+    const failFast = config?.failFast ?? false
+    let skipped = 0
+
+    // 1. Run built-in checks
+    const builtinChecks = [
+      BUILTIN_CHECKS.contextFilesExist(globalPath),
+      BUILTIN_CHECKS.jsonFilesValid(globalPath),
+      BUILTIN_CHECKS.noSensitiveData(globalPath),
+    ]
+
+    for (const checkPromise of builtinChecks) {
+      const result = await checkPromise
+      checks.push(result)
+      if (!result.passed && failFast) {
+        skipped = config?.checks?.filter((c) => c.enabled !== false).length ?? 0
+        break
+      }
+    }
+
+    // 2. Run custom checks (if configured and not fail-fast-stopped)
+    const shouldContinue = !failFast || checks.every((c) => c.passed)
+    if (shouldContinue && config?.checks) {
+      for (const check of config.checks) {
+        if (check.enabled === false) {
+          skipped++
+          continue
+        }
+
+        const result = await this.runCustomCheck(check, projectPath)
+        checks.push(result)
+
+        if (!result.passed && failFast) {
+          // Count remaining enabled checks as skipped
+          const remaining = config.checks.slice(config.checks.indexOf(check) + 1)
+          skipped += remaining.filter((c) => c.enabled !== false).length
+          break
+        }
+      }
+    }
+
+    const failedCount = checks.filter((c) => !c.passed).length
+    const passedCount = checks.filter((c) => c.passed).length
+
+    return {
+      passed: failedCount === 0,
+      checks,
+      totalMs: Date.now() - totalStart,
+      failedCount,
+      passedCount,
+      skippedCount: skipped,
+    }
+  }
+
+  /**
+   * Run a single custom verification check
+   */
+  private async runCustomCheck(
+    check: VerificationCheck,
+    projectPath: string
+  ): Promise<CheckResult> {
+    const start = Date.now()
+    const command = check.command || (check.script ? `sh ${check.script}` : null)
+
+    if (!command) {
+      return {
+        name: check.name,
+        passed: false,
+        error: 'No command or script specified',
+        durationMs: Date.now() - start,
+      }
+    }
+
+    try {
+      const { stdout, stderr } = await execAsync(command, {
+        cwd: projectPath,
+        timeout: 30_000,
+      })
+
+      return {
+        name: check.name,
+        passed: true,
+        output: (stdout.trim() || stderr.trim()).slice(0, 200) || undefined,
+        durationMs: Date.now() - start,
+      }
+    } catch (error) {
+      const execError = error as { stdout?: string; stderr?: string; message: string }
+      return {
+        name: check.name,
+        passed: false,
+        error: (execError.stderr?.trim() || execError.message).slice(0, 200),
+        durationMs: Date.now() - start,
+      }
+    }
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const syncVerifier = new SyncVerifier()
+export default syncVerifier

package/core/types/config.ts

@@ -18,6 +18,20 @@ export interface LocalConfig {
    * @see PRJ-70
    */
   showMetrics?: boolean
+  /**
+   * Verification checks to run after sync.
+   * Built-in checks always run; custom checks are additive.
+   * @see PRJ-106
+   */
+  verification?: {
+    checks?: Array<{
+      name: string
+      command?: string
+      script?: string
+      enabled?: boolean
+    }>
+    failFast?: boolean
+  }
 }
 
 /**

package/core/utils/citations.ts

@@ -0,0 +1,53 @@
+/**
+ * Citation utilities for context source tracking
+ *
+ * Generates HTML comments indicating where each section's data came from.
+ * Source types: detected (from files), user-defined (from config), inferred (from heuristics)
+ *
+ * @see PRJ-113
+ */
+
+export type SourceType = 'detected' | 'user-defined' | 'inferred'
+
+export interface SourceInfo {
+  file: string
+  type: SourceType
+}
+
+export interface ContextSources {
+  name: SourceInfo
+  version: SourceInfo
+  ecosystem: SourceInfo
+  languages: SourceInfo
+  frameworks: SourceInfo
+  commands: SourceInfo
+  projectType: SourceInfo
+  git: SourceInfo
+}
+
+/**
+ * Generate an HTML citation comment
+ *
+ * @example cite({ file: 'package.json', type: 'detected' })
+ * // => '<!-- source: package.json, detected -->'
+ */
+export function cite(source: SourceInfo): string {
+  return `<!-- source: ${source.file}, ${source.type} -->`
+}
+
+/**
+ * Create default sources (all unknown) - used as fallback
+ */
+export function defaultSources(): ContextSources {
+  const unknown: SourceInfo = { file: 'unknown', type: 'detected' }
+  return {
+    name: { ...unknown },
+    version: { ...unknown },
+    ecosystem: { ...unknown },
+    languages: { ...unknown },
+    frameworks: { ...unknown },
+    commands: { ...unknown },
+    projectType: { ...unknown },
+    git: { file: 'git', type: 'detected' },
+  }
+}

package/core/utils/error-messages.ts

@@ -128,6 +128,17 @@ export const ERRORS = {
     hint: "Run 'prjct start' to configure your provider",
   },
 
+  // Command errors
+  UNKNOWN_COMMAND: {
+    message: 'Unknown command',
+    hint: "Run 'prjct --help' to see available commands",
+  },
+
+  MISSING_PARAM: {
+    message: 'Missing required parameter',
+    hint: 'Check command usage below',
+  },
+
   // Generic
   UNKNOWN: {
     message: 'An unexpected error occurred',