prjct-cli 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## [1.4.0] - 2026-02-06
+
+### Features
+
+- programmatic verification checks for sync workflow (PRJ-106) (#115)
+
+
+## [1.3.1] - 2026-02-06
+
+### Features
+
+- **Programmatic verification checks for sync workflow (PRJ-106)**: Post-sync validation with built-in and custom checks
+
+### Implementation Details
+
+New `SyncVerifier` service (`core/services/sync-verifier.ts`) that runs verification checks after every sync. Three built-in checks run automatically:
+- **Context files exist** — verifies `context/CLAUDE.md` was generated
+- **JSON files valid** — validates `storage/state.json` syntax
+- **No sensitive data** — scans context files for leaked API keys, passwords, secrets
+
+Custom checks configurable in `.prjct/prjct.config.json`:
+```json
+{
+  "verification": {
+    "checks": [
+      { "name": "Lint CLAUDE.md", "command": "npx markdownlint CLAUDE.md" },
+      { "name": "Custom validator", "script": ".prjct/verify.sh" }
+    ],
+    "failFast": false
+  }
+}
+```
+
+Integration: wired into `sync-service.ts` after file generation (step 11), results returned in `SyncResult.verification`. Display in `showSyncResult()` shows pass/fail per check with timing.
+
+### Learnings
+
+- Non-critical verification must be wrapped in try/catch so it never breaks the sync workflow
+- Config types must match optional fields between `LocalConfig` and `VerificationConfig` (both `checks` must be optional)
+- Built-in + custom extensibility pattern (always run built-ins, then user commands) provides good defaults with flexibility
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` — verify "Verified" section with 3 checks passing
+2. Add custom check to `.prjct/prjct.config.json` — verify it runs after sync
+3. Add failing custom check (`command: "exit 1"`) — verify `✗` with error
+4. Set `failFast: true` with failing check — verify remaining checks skipped
+5. Run `bun run build && bun run typecheck` — zero errors
+
+#### For Users
+**What changed:** `prjct sync` now validates generated output with pass/fail checks
+**How to use:** Built-in checks run automatically. Add custom checks in `.prjct/prjct.config.json`
+**Breaking changes:** None
+
 ## [1.3.0] - 2026-02-06
 
 ### Features

package/core/commands/analysis.ts

@@ -529,6 +529,28 @@ export class AnalysisCommands extends PrjctCommandsBase {
       console.log('')
     }
 
+    // ═══════════════════════════════════════════════════════════════════════
+    // VERIFICATION - Post-sync validation checks
+    // ═══════════════════════════════════════════════════════════════════════
+    if (result.verification) {
+      const v = result.verification
+      if (v.passed) {
+        const items = v.checks.map((c) => `${c.name} (${c.durationMs}ms)`)
+        out.section('Verified')
+        out.list(items, { bullet: '✓' })
+      } else {
+        out.section('Verification')
+        const items = v.checks.map((c) =>
+          c.passed ? `✓ ${c.name}` : `✗ ${c.name}${c.error ? ` — ${c.error}` : ''}`
+        )
+        out.list(items)
+        if (v.skippedCount > 0) {
+          out.warn(`${v.skippedCount} check(s) skipped (fail-fast)`)
+        }
+      }
+      console.log('')
+    }
+
     // ═══════════════════════════════════════════════════════════════════════
     // NEXT STEPS - Clear call to action
     // ═══════════════════════════════════════════════════════════════════════

package/core/services/sync-service.ts

@@ -35,6 +35,7 @@ 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 +107,7 @@ interface SyncResult {
   contextFiles: string[]
   aiTools: AIToolResult[]
   syncMetrics?: SyncMetrics
+  verification?: VerificationReport
   error?: string
   // Preview mode fields
   isPreview?: boolean
@@ -246,6 +248,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 +278,7 @@ class SyncService {
           success: r.success,
         })),
         syncMetrics,
+        verification,
       }
     } catch (error) {
       return {

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
+  }
 }
 
 /**