prjct-cli 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.7.1] - 2026-02-07
+
+### Bug Fixes
+
+- add Zod validation on all storage reads (PRJ-279) (#140)
+
+
+## [1.7.1] - 2026-02-07
+
+### Bug Fix
+- **Add Zod validation on all storage reads (PRJ-279)**: Created `safeRead<T>()` utility that wraps `JSON.parse` + `schema.safeParse()`. All 5 `StorageManager` subclasses (state, queue, ideas, shipped, metrics) now validate reads against their Zod schemas. Corrupted files produce a logged warning + `.backup` file instead of silently crashing downstream.
+
+### Implementation Details
+Created `core/storage/safe-reader.ts` with a `ValidationSchema` interface decoupled from Zod generics to avoid strict type parameter matching. The `StorageManager` base class accepts an optional schema via constructor — subclasses pass their Zod schema with a single import + arg change. `safeRead` returns the raw parsed JSON (not Zod-transformed `result.data`) to preserve extra fields for forward compatibility. Also fixed `ShippedJsonSchema` which used `items` instead of `shipped` (pre-existing schema bug), and made `changes` optional to match actual data.
+
+### Learnings
+- Zod's default `strip` mode silently drops unknown keys from `result.data` — must return raw JSON to preserve extra state.json fields (projectId, stack, domains, etc.)
+- `ShippedJsonSchema` had `items` instead of `shipped` as the array key — pre-existing schema/data mismatch
+- `ValidationSchema` interface avoids Zod generic constraints while still providing type-safe validation
+
+### Test Plan
+
+#### For QA
+1. Create a valid `state.json` — verify it reads correctly with no warnings
+2. Corrupt a storage file with invalid JSON — verify `.backup` is created and defaults returned
+3. Write valid JSON with wrong schema — verify `.backup` and defaults
+4. Add extra fields not in schema — verify they are preserved after read
+5. Run `bun test` — verify all 438 tests pass (16 new for `safeRead`)
+
+#### For Users
+**What changed:** Storage reads are now validated against Zod schemas. Corrupted files no longer cause silent crashes.
+**How to use:** No action needed — automatic.
+**Breaking changes:** None.
+
 ## [1.7.0] - 2026-02-07
 
 ### Features
@@ -7,7 +41,6 @@
 - use relative timestamps to reduce token waste (PRJ-274) (#139)
 - use relative timestamps to reduce token waste (PRJ-274)
 
-
 ## [1.6.16] - 2026-02-07
 
 ### Improvement

package/core/__tests__/storage/safe-reader.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Safe Reader Tests
+ *
+ * Tests for Zod-validated storage reads:
+ * - Valid data passes through
+ * - Corrupted JSON creates .backup + returns null
+ * - Valid JSON with wrong schema creates .backup + returns null
+ * - Missing files return null (no backup)
+ * - Extra fields are preserved (forward compatibility)
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { z } from 'zod'
+import { safeRead } from '../../storage/safe-reader'
+
+// =============================================================================
+// Test Schema
+// =============================================================================
+
+const TestSchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  items: z.array(z.string()),
+})
+
+type TestData = z.infer<typeof TestSchema>
+
+// =============================================================================
+// Setup
+// =============================================================================
+
+let tmpDir: string
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'prjct-safe-reader-test-'))
+})
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true })
+})
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('safeRead', () => {
+  describe('valid data', () => {
+    it('should return validated data for valid JSON matching schema', async () => {
+      const filePath = path.join(tmpDir, 'valid.json')
+      const data: TestData = { name: 'test', count: 42, items: ['a', 'b'] }
+      await fs.writeFile(filePath, JSON.stringify(data, null, 2))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toEqual(data)
+    })
+
+    it('should preserve extra fields not in schema', async () => {
+      const filePath = path.join(tmpDir, 'extra-fields.json')
+      const data = {
+        name: 'test',
+        count: 1,
+        items: [],
+        extraField: 'preserved',
+        nested: { deep: true },
+      }
+      await fs.writeFile(filePath, JSON.stringify(data, null, 2))
+
+      const result = await safeRead<typeof data>(filePath, TestSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.name).toBe('test')
+      expect(result!.extraField).toBe('preserved')
+      expect(result!.nested).toEqual({ deep: true })
+    })
+
+    it('should not create .backup for valid data', async () => {
+      const filePath = path.join(tmpDir, 'no-backup.json')
+      const data: TestData = { name: 'ok', count: 0, items: [] }
+      await fs.writeFile(filePath, JSON.stringify(data))
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(false)
+    })
+  })
+
+  describe('missing files', () => {
+    it('should return null for non-existent file', async () => {
+      const result = await safeRead<TestData>(path.join(tmpDir, 'missing.json'), TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should not create .backup for missing file', async () => {
+      const filePath = path.join(tmpDir, 'missing.json')
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(false)
+    })
+  })
+
+  describe('corrupted JSON', () => {
+    it('should return null for malformed JSON', async () => {
+      const filePath = path.join(tmpDir, 'malformed.json')
+      await fs.writeFile(filePath, 'not valid json {{{')
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should create .backup for malformed JSON', async () => {
+      const filePath = path.join(tmpDir, 'malformed.json')
+      const badContent = 'not valid json {{{'
+      await fs.writeFile(filePath, badContent)
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backup = await fs.readFile(`${filePath}.backup`, 'utf-8')
+      expect(backup).toBe(badContent)
+    })
+
+    it('should return null for empty file', async () => {
+      const filePath = path.join(tmpDir, 'empty.json')
+      await fs.writeFile(filePath, '')
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('valid JSON with wrong schema', () => {
+    it('should return null when required field is missing', async () => {
+      const filePath = path.join(tmpDir, 'missing-field.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test' })) // missing count and items
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should create .backup when schema validation fails', async () => {
+      const filePath = path.join(tmpDir, 'wrong-schema.json')
+      const data = { name: 123, count: 'not a number', items: 'not an array' }
+      await fs.writeFile(filePath, JSON.stringify(data))
+
+      await safeRead<TestData>(filePath, TestSchema)
+
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(true)
+    })
+
+    it('should return null when field has wrong type', async () => {
+      const filePath = path.join(tmpDir, 'wrong-type.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 42, count: 1, items: [] }))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+
+    it('should return null when array contains wrong types', async () => {
+      const filePath = path.join(tmpDir, 'wrong-array.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test', count: 1, items: [1, 2, 3] }))
+
+      const result = await safeRead<TestData>(filePath, TestSchema)
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('optional fields and defaults', () => {
+    it('should handle schema with optional fields', async () => {
+      const OptionalSchema = z.object({
+        name: z.string(),
+        description: z.string().optional(),
+      })
+
+      const filePath = path.join(tmpDir, 'optional.json')
+      await fs.writeFile(filePath, JSON.stringify({ name: 'test' }))
+
+      const result = await safeRead<z.infer<typeof OptionalSchema>>(filePath, OptionalSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.name).toBe('test')
+      expect(result!.description).toBeUndefined()
+    })
+
+    it('should handle schema with nullable fields', async () => {
+      const NullableSchema = z.object({
+        currentTask: z.object({ id: z.string() }).nullable(),
+        lastUpdated: z.string(),
+      })
+
+      const filePath = path.join(tmpDir, 'nullable.json')
+      await fs.writeFile(filePath, JSON.stringify({ currentTask: null, lastUpdated: '2026-01-01' }))
+
+      const result = await safeRead<z.infer<typeof NullableSchema>>(filePath, NullableSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.currentTask).toBeNull()
+    })
+  })
+
+  describe('integration with StorageManager pattern', () => {
+    it('should work with real StateJsonSchema', async () => {
+      // Import the actual schema used in production
+      const { StateJsonSchema } = await import('../../schemas/state')
+
+      const filePath = path.join(tmpDir, 'state.json')
+      const stateData = {
+        currentTask: null,
+        lastUpdated: '2026-02-07T00:00:00.000Z',
+        // Extra fields that exist in real state.json but not in schema
+        projectId: 'test-123',
+        stack: { language: 'TypeScript', framework: 'Hono' },
+      }
+      await fs.writeFile(filePath, JSON.stringify(stateData, null, 2))
+
+      const result = await safeRead<typeof stateData>(filePath, StateJsonSchema)
+
+      expect(result).not.toBeNull()
+      expect(result!.currentTask).toBeNull()
+      expect(result!.projectId).toBe('test-123') // Extra field preserved
+    })
+
+    it('should reject corrupted state data', async () => {
+      const { StateJsonSchema } = await import('../../schemas/state')
+
+      const filePath = path.join(tmpDir, 'bad-state.json')
+      // currentTask should be an object or null, not a number
+      const badData = { currentTask: 42, lastUpdated: '2026-02-07' }
+      await fs.writeFile(filePath, JSON.stringify(badData))
+
+      const result = await safeRead(filePath, StateJsonSchema)
+
+      expect(result).toBeNull()
+      // Backup should exist
+      const backupExists = await fs
+        .access(`${filePath}.backup`)
+        .then(() => true)
+        .catch(() => false)
+      expect(backupExists).toBe(true)
+    })
+  })
+})

package/core/schemas/shipped.ts

@@ -56,7 +56,7 @@ export const ShippedItemSchema = z.object({
   type: ShipTypeSchema,
   agent: z.string().optional(), // "fe+be", "be", "fe"
   description: z.string().optional(),
-  changes: z.array(ShipChangeSchema),
+  changes: z.array(ShipChangeSchema).optional(),
   codeSnippets: z.array(z.string()).optional(),
   commit: CommitInfoSchema.optional(),
   codeMetrics: CodeMetricsSchema.optional(),
@@ -69,7 +69,7 @@ export const ShippedItemSchema = z.object({
 })
 
 export const ShippedJsonSchema = z.object({
-  items: z.array(ShippedItemSchema),
+  shipped: z.array(ShippedItemSchema),
   lastUpdated: z.string(),
 })
 
@@ -104,6 +104,6 @@ export const safeParseShipped = (data: unknown) => ShippedJsonSchema.safeParse(d
 // =============================================================================
 
 export const DEFAULT_SHIPPED: ShippedJson = {
-  items: [],
+  shipped: [],
   lastUpdated: '',
 }

package/core/storage/ideas-storage.ts

@@ -6,13 +6,14 @@
  */
 
 import { generateUUID } from '../schemas'
+import { IdeasJsonSchema } from '../schemas/ideas'
 import type { Idea, IdeaPriority, IdeaStatus, IdeasJson } from '../types'
 import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class IdeasStorage extends StorageManager<IdeasJson> {
   constructor() {
-    super('ideas.json')
+    super('ideas.json', IdeasJsonSchema)
   }
 
   protected getDefault(): IdeasJson {

package/core/storage/metrics-storage.ts

@@ -18,13 +18,14 @@ import {
   estimateCostSaved,
   formatCost,
   type MetricsJson,
+  MetricsJsonSchema,
 } from '../schemas/metrics'
 import { getTimestamp } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class MetricsStorage extends StorageManager<MetricsJson> {
   constructor() {
-    super('metrics.json')
+    super('metrics.json', MetricsJsonSchema)
   }
 
   protected getDefault(): MetricsJson {

package/core/storage/queue-storage.ts

@@ -7,12 +7,13 @@
 
 import { generateUUID } from '../schemas'
 import type { Priority, QueueJson, QueueTask, TaskSection } from '../schemas/state'
+import { QueueJsonSchema } from '../schemas/state'
 import { getTimestamp } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class QueueStorage extends StorageManager<QueueJson> {
   constructor() {
-    super('queue.json')
+    super('queue.json', QueueJsonSchema)
   }
 
   protected getDefault(): QueueJson {

package/core/storage/safe-reader.ts

@@ -0,0 +1,105 @@
+/**
+ * Safe Reader
+ *
+ * Wraps JSON.parse + Zod schema.safeParse() for validated storage reads.
+ * On corruption: logs warning, creates .backup, returns null.
+ *
+ * Uses schema for structural validation only — returns the raw parsed
+ * data (not Zod-transformed) to preserve extra fields that may exist
+ * in storage files but aren't in the schema yet (forward compatibility).
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'node:fs/promises'
+import type { ZodError } from 'zod'
+import { isNotFoundError } from '../types/fs'
+
+/**
+ * Minimal interface for Zod-like validation.
+ * Decoupled from Zod generics to avoid strict type parameter matching.
+ */
+export interface ValidationSchema {
+  safeParse(data: unknown): { success: boolean; error?: ZodError }
+}
+
+/**
+ * Read and validate a JSON file against a Zod schema.
+ *
+ * Flow:
+ * 1. Read file → if missing, return null
+ * 2. JSON.parse → if malformed JSON, backup + return null
+ * 3. schema.safeParse → if valid, return raw parsed data as T
+ * 4. If invalid but parseable JSON, backup + return null
+ *
+ * Returns raw parsed JSON (not Zod-transformed) to preserve extra fields.
+ *
+ * @returns Validated data or null if file is missing/corrupted
+ */
+export async function safeRead<T>(filePath: string, schema: ValidationSchema): Promise<T | null> {
+  let content: string
+
+  // Step 1: Read file
+  try {
+    content = await fs.readFile(filePath, 'utf-8')
+  } catch (error) {
+    if (isNotFoundError(error)) {
+      return null
+    }
+    throw error
+  }
+
+  // Step 2: JSON.parse
+  let raw: unknown
+  try {
+    raw = JSON.parse(content)
+  } catch {
+    // Malformed JSON — backup and return null
+    await createBackup(filePath, content)
+    logCorruption(filePath, 'Malformed JSON')
+    return null
+  }
+
+  // Step 3: Validate against schema
+  const result = schema.safeParse(raw)
+  if (result.success) {
+    // Return raw data to preserve extra fields not in schema
+    return raw as T
+  }
+
+  // Step 4: Validation failed — backup and return null
+  await createBackup(filePath, content)
+  logCorruption(filePath, formatZodError(result.error!))
+  return null
+}
+
+/**
+ * Create a .backup of a corrupted file
+ */
+async function createBackup(filePath: string, content: string): Promise<void> {
+  const backupPath = `${filePath}.backup`
+  try {
+    await fs.writeFile(backupPath, content, 'utf-8')
+  } catch {
+    // Best-effort backup — don't throw if it fails
+  }
+}
+
+/**
+ * Log corruption warning to stderr
+ */
+function logCorruption(filePath: string, reason: string): void {
+  console.error(`[prjct] Warning: Corrupted storage file: ${filePath}`)
+  console.error(`[prjct]   Reason: ${reason}`)
+  console.error(`[prjct]   A .backup file has been created. Returning defaults.`)
+}
+
+/**
+ * Format Zod error into a readable string
+ */
+function formatZodError(error: ZodError): string {
+  return error.issues
+    .slice(0, 3)
+    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+    .join('; ')
+}

package/core/storage/shipped-storage.ts

@@ -6,13 +6,14 @@
  */
 
 import { generateUUID } from '../schemas'
+import { ShippedJsonSchema } from '../schemas/shipped'
 import type { ShippedFeature, ShippedJson } from '../types'
 import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class ShippedStorage extends StorageManager<ShippedJson> {
   constructor() {
-    super('shipped.json')
+    super('shipped.json', ShippedJsonSchema)
   }
 
   protected getDefault(): ShippedJson {

package/core/storage/state-storage.ts

@@ -16,13 +16,14 @@ import type {
   Subtask,
   SubtaskSummary,
 } from '../schemas/state'
+import { StateJsonSchema } from '../schemas/state'
 import { getTimestamp, toRelative } from '../utils/date-helper'
 import { md } from '../utils/markdown-builder'
 import { StorageManager } from './storage-manager'
 
 class StateStorage extends StorageManager<StateJson> {
   constructor() {
-    super('state.json')
+    super('state.json', StateJsonSchema)
   }
 
   protected getDefault(): StateJson {

package/core/storage/storage-manager.ts

@@ -16,14 +16,17 @@ import pathManager from '../infrastructure/path-manager'
 import { isNotFoundError } from '../types/fs'
 import { TTLCache } from '../utils/cache'
 import { getTimestamp } from '../utils/date-helper'
+import { safeRead, type ValidationSchema } from './safe-reader'
 
 export abstract class StorageManager<T> {
   protected filename: string
   protected cache: TTLCache<T>
+  protected schema: ValidationSchema | null
 
-  constructor(filename: string) {
+  constructor(filename: string, schema?: ValidationSchema) {
     this.filename = filename
     this.cache = new TTLCache<T>({ ttl: 5000, maxSize: 50 })
+    this.schema = schema ?? null
   }
 
   /**
@@ -69,7 +72,9 @@ export abstract class StorageManager<T> {
   protected abstract getEventType(action: 'update' | 'create' | 'delete'): string
 
   /**
-   * Read data from storage
+   * Read data from storage with optional Zod validation.
+   * When a schema is provided (via constructor), validates after JSON.parse.
+   * On corruption: creates .backup file, logs warning, returns default.
    */
   async read(projectId: string): Promise<T> {
     // Check cache first (with expiration)
@@ -80,13 +85,24 @@ export abstract class StorageManager<T> {
 
     const filePath = this.getStoragePath(projectId)
 
+    if (this.schema) {
+      // Validated read path
+      const data = await safeRead<T>(filePath, this.schema)
+      if (data !== null) {
+        this.cache.set(projectId, data)
+        return data
+      }
+      // File missing or corrupted — return default
+      return this.getDefault()
+    }
+
+    // Unvalidated fallback (for subclasses without a schema)
     try {
       const content = await fs.readFile(filePath, 'utf-8')
       const data = JSON.parse(content) as T
       this.cache.set(projectId, data)
       return data
     } catch (error) {
-      // Return default if file doesn't exist or is invalid JSON
       if (isNotFoundError(error) || error instanceof SyntaxError) {
         return this.getDefault()
       }

package/core/utils/file-helper.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { safeRead, type ValidationSchema } from '../storage/safe-reader'
 import { isNotFoundError } from '../types/fs'
 
 /**
@@ -18,12 +19,19 @@ interface ListFilesOptions {
 }
 
 /**
- * Read JSON file and parse
+ * Read JSON file and parse.
+ * When a Zod schema is provided, validates the data and creates a .backup on corruption.
  */
 export async function readJson<T = unknown>(
   filePath: string,
-  defaultValue: T | null = null
+  defaultValue: T | null = null,
+  schema?: ValidationSchema
 ): Promise<T | null> {
+  if (schema) {
+    const data = await safeRead<T>(filePath, schema)
+    return data ?? defaultValue
+  }
+
   try {
     const content = await fs.readFile(filePath, 'utf-8')
     return JSON.parse(content) as T