prjct-cli 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [1.11.0] - 2026-02-09
+
+### Features
+
+- implement sealable analysis with commit-hash signature (PRJ-263) (#153)
+
+
+## [1.11.0] - 2026-02-08
+
+### Features
+- **Sealable Analysis**: 3-state lifecycle (draft/verified/sealed) with SHA-256 commit-hash signatures (PRJ-263)
+- **Dual Storage**: Re-sync creates drafts without destroying sealed analysis — only sealed feeds task context
+- **Staleness Detection**: Warns when HEAD moves past the sealed commit hash
+- **Seal & Verify Commands**: `prjct seal` locks draft analysis, `prjct verify` checks integrity
+
+### Implementation Details
+New `analysis-storage.ts` extends StorageManager with dual storage (draft + sealed). Analysis schema rewritten as Zod schemas with runtime validation. Sync service writes drafts in parallel with existing writes. Canonical JSON representation ensures deterministic SHA-256 signatures.
+
+Key changes:
+- `core/schemas/analysis.ts` — Full rewrite: plain interfaces → Zod schemas with `AnalysisStatusSchema`, `AnalysisItemSchema`
+- `core/storage/analysis-storage.ts` — New: dual storage, sealing, verification, staleness detection
+- `core/services/sync-service.ts` — Added `saveDraftAnalysis()` to parallel writes
+- `core/commands/analysis.ts` — Added `seal()` and `verify()` command methods
+- `core/commands/register.ts`, `core/index.ts` — Registered new commands
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` — verify draft analysis is created in storage
+2. Run `prjct seal` — verify analysis is locked with SHA-256 signature
+3. Run `prjct verify` — verify signature matches
+4. Run `prjct sync` again — verify sealed analysis is preserved, new draft created
+5. Make a commit, run `prjct status` — verify staleness detection warns about diverged commits
+
+#### For Users
+- **What changed:** Analysis results can now be locked (sealed) so re-syncing doesn't overwrite verified context
+- **How to use:** Run `prjct seal` after reviewing sync results, `prjct verify` to check integrity
+- **Breaking changes:** None — old analysis files parse with `status: 'draft'` default
+
 ## [1.10.0] - 2026-02-08
 
 ### Features

package/core/__tests__/storage/analysis-storage.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Analysis Storage Tests (PRJ-263)
+ *
+ * Tests for sealable analysis lifecycle:
+ * - Schema validation (draft/verified/sealed)
+ * - Signature computation and verification
+ * - Staleness detection
+ * - Draft preservation on re-sync
+ * - Backward compatibility
+ */
+
+import { describe, expect, it } from 'bun:test'
+import {
+  AnalysisItemSchema,
+  AnalysisStatusSchema,
+  parseAnalysis,
+  safeParseAnalysis,
+} from '../../schemas/analysis'
+
+// =============================================================================
+// Schema Validation
+// =============================================================================
+
+describe('AnalysisStatusSchema', () => {
+  it('should accept valid statuses', () => {
+    expect(AnalysisStatusSchema.parse('draft')).toBe('draft')
+    expect(AnalysisStatusSchema.parse('verified')).toBe('verified')
+    expect(AnalysisStatusSchema.parse('sealed')).toBe('sealed')
+  })
+
+  it('should reject invalid statuses', () => {
+    expect(() => AnalysisStatusSchema.parse('pending')).toThrow()
+    expect(() => AnalysisStatusSchema.parse('active')).toThrow()
+    expect(() => AnalysisStatusSchema.parse('')).toThrow()
+  })
+})
+
+describe('AnalysisItemSchema', () => {
+  const validDraft = {
+    projectId: 'test-project-123',
+    languages: ['TypeScript'],
+    frameworks: ['Hono'],
+    configFiles: ['tsconfig.json'],
+    fileCount: 295,
+    patterns: [{ name: 'Service pattern', description: 'Classes with dependency injection' }],
+    antiPatterns: [],
+    analyzedAt: '2026-02-08T20:00:00.000Z',
+    status: 'draft' as const,
+    commitHash: 'abc1234',
+  }
+
+  it('should parse a valid draft analysis', () => {
+    const result = AnalysisItemSchema.parse(validDraft)
+    expect(result.status).toBe('draft')
+    expect(result.commitHash).toBe('abc1234')
+    expect(result.projectId).toBe('test-project-123')
+  })
+
+  it('should default status to draft when not provided', () => {
+    const { status, ...withoutStatus } = validDraft
+    const result = AnalysisItemSchema.parse(withoutStatus)
+    expect(result.status).toBe('draft')
+  })
+
+  it('should parse a sealed analysis with signature', () => {
+    const sealed = {
+      ...validDraft,
+      status: 'sealed' as const,
+      signature: 'sha256-abc123def456',
+      sealedAt: '2026-02-08T21:00:00.000Z',
+    }
+    const result = AnalysisItemSchema.parse(sealed)
+    expect(result.status).toBe('sealed')
+    expect(result.signature).toBe('sha256-abc123def456')
+    expect(result.sealedAt).toBe('2026-02-08T21:00:00.000Z')
+  })
+
+  it('should accept optional fields as undefined', () => {
+    const minimal = {
+      projectId: 'test',
+      languages: [],
+      frameworks: [],
+      configFiles: [],
+      fileCount: 0,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2026-02-08T20:00:00.000Z',
+    }
+    const result = AnalysisItemSchema.parse(minimal)
+    expect(result.status).toBe('draft')
+    expect(result.commitHash).toBeUndefined()
+    expect(result.signature).toBeUndefined()
+    expect(result.sealedAt).toBeUndefined()
+    expect(result.modelMetadata).toBeUndefined()
+  })
+
+  it('should reject missing required fields', () => {
+    expect(() => AnalysisItemSchema.parse({})).toThrow()
+    expect(() => AnalysisItemSchema.parse({ projectId: 'test' })).toThrow()
+  })
+})
+
+describe('parseAnalysis / safeParseAnalysis', () => {
+  it('should parse valid data', () => {
+    const data = {
+      projectId: 'test',
+      languages: ['TypeScript'],
+      frameworks: [],
+      configFiles: [],
+      fileCount: 10,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2026-02-08T20:00:00.000Z',
+    }
+    const result = parseAnalysis(data)
+    expect(result.projectId).toBe('test')
+    expect(result.status).toBe('draft')
+  })
+
+  it('should return success for safeParseAnalysis with valid data', () => {
+    const data = {
+      projectId: 'test',
+      languages: [],
+      frameworks: [],
+      configFiles: [],
+      fileCount: 0,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2026-02-08T20:00:00.000Z',
+    }
+    const result = safeParseAnalysis(data)
+    expect(result.success).toBe(true)
+  })
+
+  it('should return failure for safeParseAnalysis with invalid data', () => {
+    const result = safeParseAnalysis({ invalid: true })
+    expect(result.success).toBe(false)
+  })
+})
+
+// =============================================================================
+// Staleness Detection (pure function tests)
+// =============================================================================
+
+describe('staleness detection', () => {
+  // Test checkStaleness method from AnalysisStorage
+  it('should detect stale analysis when commits differ', () => {
+    const { analysisStorage } = require('../../storage/analysis-storage')
+    const result = analysisStorage.checkStaleness('abc1234', 'def5678')
+    expect(result.isStale).toBe(true)
+    expect(result.sealedCommit).toBe('abc1234')
+    expect(result.currentCommit).toBe('def5678')
+  })
+
+  it('should detect fresh analysis when commits match', () => {
+    const { analysisStorage } = require('../../storage/analysis-storage')
+    const result = analysisStorage.checkStaleness('abc1234', 'abc1234')
+    expect(result.isStale).toBe(false)
+  })
+
+  it('should handle null sealed commit', () => {
+    const { analysisStorage } = require('../../storage/analysis-storage')
+    const result = analysisStorage.checkStaleness(null, 'abc1234')
+    expect(result.isStale).toBe(false)
+    expect(result.message).toContain('No sealed analysis')
+  })
+
+  it('should handle null current commit', () => {
+    const { analysisStorage } = require('../../storage/analysis-storage')
+    const result = analysisStorage.checkStaleness('abc1234', null)
+    expect(result.isStale).toBe(true)
+    expect(result.message).toContain('Cannot determine')
+  })
+})
+
+// =============================================================================
+// Signature Computation (determinism test)
+// =============================================================================
+
+describe('signature computation', () => {
+  it('should produce deterministic signatures for same input', () => {
+    const { createHash } = require('node:crypto')
+
+    const analysis = {
+      projectId: 'test',
+      languages: ['TypeScript'],
+      frameworks: ['Hono'],
+      configFiles: [],
+      fileCount: 100,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2026-02-08T20:00:00.000Z',
+      commitHash: 'abc1234',
+    }
+
+    const canonical = {
+      projectId: analysis.projectId,
+      languages: analysis.languages,
+      frameworks: analysis.frameworks,
+      packageManager: undefined,
+      sourceDir: undefined,
+      testDir: undefined,
+      configFiles: analysis.configFiles,
+      fileCount: analysis.fileCount,
+      patterns: analysis.patterns,
+      antiPatterns: analysis.antiPatterns,
+      analyzedAt: analysis.analyzedAt,
+      commitHash: analysis.commitHash,
+    }
+
+    const sig1 = createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+    const sig2 = createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+
+    expect(sig1).toBe(sig2)
+    expect(sig1).toHaveLength(64) // SHA-256 hex = 64 chars
+  })
+
+  it('should produce different signatures for different inputs', () => {
+    const { createHash } = require('node:crypto')
+
+    const data1 = JSON.stringify({ projectId: 'a', fileCount: 1 })
+    const data2 = JSON.stringify({ projectId: 'b', fileCount: 2 })
+
+    const sig1 = createHash('sha256').update(data1).digest('hex')
+    const sig2 = createHash('sha256').update(data2).digest('hex')
+
+    expect(sig1).not.toBe(sig2)
+  })
+})
+
+// =============================================================================
+// Backward Compatibility
+// =============================================================================
+
+describe('backward compatibility', () => {
+  it('should parse old analysis.json without seal fields', () => {
+    const oldFormat = {
+      projectId: 'old-project',
+      languages: ['JavaScript'],
+      frameworks: ['Express'],
+      configFiles: ['package.json'],
+      fileCount: 50,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2025-12-01T00:00:00.000Z',
+      // No status, commitHash, signature, sealedAt
+    }
+
+    const result = AnalysisItemSchema.parse(oldFormat)
+    expect(result.status).toBe('draft') // Default
+    expect(result.commitHash).toBeUndefined()
+    expect(result.signature).toBeUndefined()
+    expect(result.sealedAt).toBeUndefined()
+  })
+
+  it('should parse old analysis with modelMetadata but no seal fields', () => {
+    const oldWithModel = {
+      projectId: 'old-project',
+      languages: ['TypeScript'],
+      frameworks: [],
+      configFiles: [],
+      fileCount: 10,
+      patterns: [],
+      antiPatterns: [],
+      analyzedAt: '2026-01-15T00:00:00.000Z',
+      modelMetadata: {
+        provider: 'claude',
+        model: 'sonnet',
+        recordedAt: '2026-01-15T00:00:00.000Z',
+      },
+    }
+
+    const result = AnalysisItemSchema.parse(oldWithModel)
+    expect(result.status).toBe('draft')
+    expect(result.modelMetadata?.provider).toBe('claude')
+  })
+})

package/core/commands/analysis.ts

@@ -12,6 +12,7 @@ import commandInstaller from '../infrastructure/command-installer'
 import { formatCost } from '../schemas/metrics'
 import { createStalenessChecker, memoryService, syncService } from '../services'
 import { formatDiffPreview, formatFullDiff, generateSyncDiff } from '../services/diff-generator'
+import { analysisStorage } from '../storage/analysis-storage'
 import { metricsStorage } from '../storage/metrics-storage'
 import type { AnalyzeOptions, CommandResult, ProjectContext } from '../types'
 import { getErrorMessage } from '../types/fs'
@@ -805,6 +806,9 @@ export class AnalysisCommands extends PrjctCommandsBase {
       // Get session info
       const sessionInfo = await checker.getSessionInfo(projectId)
 
+      // Get analysis status (PRJ-263)
+      const analysisStatus = await analysisStorage.getStatus(projectId)
+
       // JSON output mode
       if (options.json) {
         console.log(
@@ -812,9 +816,13 @@ export class AnalysisCommands extends PrjctCommandsBase {
             success: true,
             ...status,
             session: sessionInfo,
+            analysis: analysisStatus,
           })
         )
-        return { success: true, data: { ...status, session: sessionInfo } }
+        return {
+          success: true,
+          data: { ...status, session: sessionInfo, analysis: analysisStatus },
+        }
       }
 
       // Human-readable output
@@ -822,9 +830,22 @@ export class AnalysisCommands extends PrjctCommandsBase {
       console.log(checker.formatStatus(status))
       console.log('')
       console.log(checker.formatSessionInfo(sessionInfo))
+
+      // Show analysis status (PRJ-263)
+      if (analysisStatus.hasSealed || analysisStatus.hasDraft) {
+        console.log('')
+        console.log('Analysis:')
+        if (analysisStatus.hasSealed) {
+          console.log(`  Sealed: ${analysisStatus.sealedCommit} (${analysisStatus.sealedAt})`)
+        }
+        if (analysisStatus.hasDraft) {
+          console.log(`  Draft: ${analysisStatus.draftCommit} (pending seal)`)
+        }
+      }
+
       console.log('')
 
-      return { success: true, data: { ...status, session: sessionInfo } }
+      return { success: true, data: { ...status, session: sessionInfo, analysis: analysisStatus } }
     } catch (error) {
       const errMsg = getErrorMessage(error)
       if (options.json) {
@@ -836,6 +857,100 @@ export class AnalysisCommands extends PrjctCommandsBase {
     }
   }
 
+  /**
+   * prjct seal - Seal the current draft analysis (PRJ-263)
+   *
+   * Locks the current draft with a SHA-256 signature.
+   * Only sealed analysis feeds task context.
+   */
+  async seal(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: 'No project ID found' }))
+        }
+        return { success: false, error: 'No project ID found' }
+      }
+
+      const result = await analysisStorage.seal(projectId)
+
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            success: result.success,
+            signature: result.signature,
+            error: result.error,
+          })
+        )
+        return { success: result.success, error: result.error }
+      }
+
+      if (!result.success) {
+        out.fail(result.error || 'Seal failed')
+        return { success: false, error: result.error }
+      }
+
+      out.done('Analysis sealed')
+      console.log(`  Signature: ${result.signature?.substring(0, 16)}...`)
+      console.log('')
+
+      return { success: true, data: { signature: result.signature } }
+    } catch (error) {
+      const errMsg = getErrorMessage(error)
+      if (options.json) {
+        console.log(JSON.stringify({ success: false, error: errMsg }))
+      } else {
+        out.fail(errMsg)
+      }
+      return { success: false, error: errMsg }
+    }
+  }
+
+  /**
+   * prjct verify - Verify integrity of sealed analysis (PRJ-263)
+   */
+  async verify(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        return { success: false, error: 'No project ID found' }
+      }
+
+      const result = await analysisStorage.verify(projectId)
+
+      if (options.json) {
+        console.log(JSON.stringify(result))
+        return { success: result.valid }
+      }
+
+      if (result.valid) {
+        out.done(result.message)
+      } else {
+        out.fail(result.message)
+      }
+      console.log('')
+
+      return { success: result.valid, data: result }
+    } catch (error) {
+      const errMsg = getErrorMessage(error)
+      out.fail(errMsg)
+      return { success: false, error: errMsg }
+    }
+  }
+
   /**
    * Get session activity stats from today's events
    * @see PRJ-89

package/core/commands/command-data.ts

@@ -218,6 +218,35 @@ export const COMMANDS: CommandMeta[] = [
       'Configurable staleness thresholds',
     ],
   },
+  {
+    name: 'seal',
+    group: 'core',
+    description: 'Seal the current draft analysis with a commit-hash signature',
+    usage: { claude: '/p:seal', terminal: 'prjct seal' },
+    params: '[--json]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Locks draft analysis with SHA-256 signature',
+      'Only sealed analysis feeds task context',
+      'Detects staleness when HEAD moves past sealed commit',
+    ],
+  },
+  {
+    name: 'verify',
+    group: 'core',
+    description: 'Verify integrity of sealed analysis',
+    usage: { claude: '/p:verify', terminal: 'prjct verify' },
+    params: '[--json]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Recomputes SHA-256 signature and compares',
+      'Detects if sealed analysis was modified',
+    ],
+  },
   {
     name: 'help',
     group: 'core',

package/core/commands/commands.ts

@@ -218,6 +218,20 @@ class PrjctCommands {
     return this.analysis.status(projectPath, options)
   }
 
+  async seal(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    return this.analysis.seal(projectPath, options)
+  }
+
+  async verify(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    return this.analysis.verify(projectPath, options)
+  }
+
   // ========== Context Commands ==========
 
   async context(

package/core/commands/register.ts

@@ -91,6 +91,8 @@ export function registerAllCommands(): void {
   commandRegistry.registerMethod('sync', analysis, 'sync', getMeta('sync'))
   commandRegistry.registerMethod('stats', analysis, 'stats', getMeta('stats'))
   commandRegistry.registerMethod('status', analysis, 'status', getMeta('status'))
+  commandRegistry.registerMethod('seal', analysis, 'seal', getMeta('seal'))
+  commandRegistry.registerMethod('verify', analysis, 'verify', getMeta('verify'))
 
   // Setup commands
   commandRegistry.registerMethod('start', setup, 'start', getMeta('start'))

package/core/index.ts

@@ -170,6 +170,8 @@ async function main(): Promise<void> {
             json: options.json === true,
             package: options.package ? String(options.package) : undefined,
           }),
+        seal: () => commands.seal(process.cwd(), { json: options.json === true }),
+        verify: () => commands.verify(process.cwd(), { json: options.json === true }),
         start: () => commands.start(),
         // Context (for Claude templates)
         context: (p) => commands.context(p),

package/core/schemas/analysis.ts

@@ -2,37 +2,80 @@
  * Analysis Schema
  *
  * Defines the structure for analysis.json - repository analysis.
+ * Supports a 3-state lifecycle: DRAFT → VERIFIED → SEALED (PRJ-263).
  */
 
-import type { ModelMetadata } from './model'
+import { z } from 'zod'
+import { ModelMetadataSchema } from './model'
 
-export interface CodePattern {
-  name: string
-  description: string
-  location?: string
-}
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
 
-export interface AntiPattern {
-  issue: string
-  file: string
-  suggestion: string
-}
+export const AnalysisStatusSchema = z.enum(['draft', 'verified', 'sealed'])
+
+export const CodePatternSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  location: z.string().optional(),
+})
 
-export interface AnalysisSchema {
-  projectId: string
-  languages: string[]
-  frameworks: string[]
-  packageManager?: string
-  sourceDir?: string
-  testDir?: string
-  configFiles: string[]
-  fileCount: number
-  patterns: CodePattern[]
-  antiPatterns: AntiPattern[]
-  analyzedAt: string // ISO8601
+export const AntiPatternSchema = z.object({
+  issue: z.string(),
+  file: z.string(),
+  suggestion: z.string(),
+})
+
+export const AnalysisItemSchema = z.object({
+  projectId: z.string(),
+  languages: z.array(z.string()),
+  frameworks: z.array(z.string()),
+  packageManager: z.string().optional(),
+  sourceDir: z.string().optional(),
+  testDir: z.string().optional(),
+  configFiles: z.array(z.string()),
+  fileCount: z.number(),
+  patterns: z.array(CodePatternSchema),
+  antiPatterns: z.array(AntiPatternSchema),
+  analyzedAt: z.string(), // ISO8601
   /** Which AI model was used for this analysis (PRJ-265) */
-  modelMetadata?: ModelMetadata
-}
+  modelMetadata: ModelMetadataSchema.optional(),
+
+  // Sealable analysis fields (PRJ-263)
+  /** Lifecycle status: draft (regenerable), verified (confirmed correct), sealed (locked) */
+  status: AnalysisStatusSchema.default('draft'),
+  /** Git commit hash at the time of analysis */
+  commitHash: z.string().optional(),
+  /** SHA-256 signature of analysis content + commit hash */
+  signature: z.string().optional(),
+  /** When the analysis was sealed */
+  sealedAt: z.string().optional(), // ISO8601
+  /** When the analysis was verified */
+  verifiedAt: z.string().optional(), // ISO8601
+})
+
+// =============================================================================
+// Inferred Types - Backward Compatible
+// =============================================================================
+
+export type AnalysisStatus = z.infer<typeof AnalysisStatusSchema>
+export type CodePattern = z.infer<typeof CodePatternSchema>
+export type AntiPattern = z.infer<typeof AntiPatternSchema>
+/** Use z.input so optional fields with defaults (like status) remain optional in creation */
+export type AnalysisSchema = z.input<typeof AnalysisItemSchema>
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Parse and validate analysis.json content */
+export const parseAnalysis = (data: unknown): z.infer<typeof AnalysisItemSchema> =>
+  AnalysisItemSchema.parse(data)
+export const safeParseAnalysis = (data: unknown) => AnalysisItemSchema.safeParse(data)
+
+// =============================================================================
+// Defaults
+// =============================================================================
 
 export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {
   languages: [],
@@ -42,4 +85,5 @@ export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {
   patterns: [],
   antiPatterns: [],
   analyzedAt: new Date().toISOString(),
+  status: 'draft',
 }