prjct-cli 0.20.0 → 0.21.0

package/core/schemas/shipped.ts

@@ -2,80 +2,107 @@
  * Shipped Schema
  *
  * Defines the structure for shipped.json - completed/shipped items.
+ * Uses Zod for runtime validation and TypeScript type inference.
  * ZERO DATA LOSS - captures ALL fields from MD files.
+ *
+ * @version 2.0.0
  */
 
-export type ShipType = 'feature' | 'fix' | 'improvement' | 'refactor'
-export type CheckStatus = 'pass' | 'warning' | 'fail' | 'skipped'
-export type AgentType = 'fe' | 'be' | 'fe+be' | 'devops' | 'ai' | string
+import { z } from 'zod'
 
-// Duration object for parsed time strings like "13h 38m"
-export interface Duration {
-  hours: number
-  minutes: number
-  totalMinutes: number
-}
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
 
-// Code metrics from "Files: 4 | +160/-31 | Commits: 0"
-export interface CodeMetrics {
-  filesChanged?: number | null
-  linesAdded?: number | null
-  linesRemoved?: number | null
-  commits?: number | null
-}
+export const ShipTypeSchema = z.enum(['feature', 'fix', 'improvement', 'refactor'])
+export const CheckStatusSchema = z.enum(['pass', 'warning', 'fail', 'skipped'])
+export const ChangeTypeSchema = z.enum(['added', 'changed', 'fixed', 'removed'])
 
-export interface ShipChange {
-  description: string
-  type?: 'added' | 'changed' | 'fixed' | 'removed'
-}
+export const DurationSchema = z.object({
+  hours: z.number(),
+  minutes: z.number(),
+  totalMinutes: z.number(),
+})
 
-export interface QualityMetrics {
-  lintStatus?: CheckStatus | null
-  lintDetails?: string
-  testStatus?: CheckStatus | null
-  testDetails?: string
-}
+export const CodeMetricsSchema = z.object({
+  filesChanged: z.number().nullable().optional(),
+  linesAdded: z.number().nullable().optional(),
+  linesRemoved: z.number().nullable().optional(),
+  commits: z.number().nullable().optional(),
+})
 
-// Git commit information
-export interface CommitInfo {
-  hash?: string                 // "0a7bbea"
-  message?: string              // "feat(security): Multi-tenant..."
-  branch?: string               // "main"
-}
+export const ShipChangeSchema = z.object({
+  description: z.string(),
+  type: ChangeTypeSchema.optional(),
+})
 
-export interface ShippedItemSchema {
-  id: string                    // ship_xxxxxxxx
-  name: string
-  version?: string | null       // "0.11.6" extracted from MD
-  type: ShipType
-  // Agent who worked on this
-  agent?: AgentType             // "fe+be", "be", "fe"
-  // Full description (narrative text, not just bullet points)
-  description?: string          // "CRITICAL: Multi-tenant isolation hardening..."
-  // Changelog from bullet points
-  changes: ShipChange[]
-  // Code snippets if any
-  codeSnippets?: string[]       // TypeScript/code examples from MD
-  // Git commit info
-  commit?: CommitInfo
-  // Enriched fields from MD
-  codeMetrics?: CodeMetrics
-  qualityMetrics?: QualityMetrics
-  quantitativeImpact?: string   // "81% (1,079 → 204 lines)"
-  duration?: Duration           // parsed from "13h 38m"
-  tasksCompleted?: number | null
-  shippedAt: string             // ISO8601
-  featureId?: string
-}
+export const QualityMetricsSchema = z.object({
+  lintStatus: CheckStatusSchema.nullable().optional(),
+  lintDetails: z.string().optional(),
+  testStatus: CheckStatusSchema.nullable().optional(),
+  testDetails: z.string().optional(),
+})
 
-export interface ShippedJson {
-  items: ShippedItemSchema[]
-  lastUpdated: string
-}
+export const CommitInfoSchema = z.object({
+  hash: z.string().optional(),
+  message: z.string().optional(),
+  branch: z.string().optional(),
+})
+
+export const ShippedItemSchema = z.object({
+  id: z.string(),               // ship_xxxxxxxx
+  name: z.string(),
+  version: z.string().nullable().optional(),
+  type: ShipTypeSchema,
+  agent: z.string().optional(), // "fe+be", "be", "fe"
+  description: z.string().optional(),
+  changes: z.array(ShipChangeSchema),
+  codeSnippets: z.array(z.string()).optional(),
+  commit: CommitInfoSchema.optional(),
+  codeMetrics: CodeMetricsSchema.optional(),
+  qualityMetrics: QualityMetricsSchema.optional(),
+  quantitativeImpact: z.string().optional(),
+  duration: DurationSchema.optional(),
+  tasksCompleted: z.number().nullable().optional(),
+  shippedAt: z.string(),        // ISO8601
+  featureId: z.string().optional(),
+})
+
+export const ShippedJsonSchema = z.object({
+  items: z.array(ShippedItemSchema),
+  lastUpdated: z.string(),
+})
+
+// =============================================================================
+// Inferred Types - Backward Compatible
+// =============================================================================
+
+export type ShipType = z.infer<typeof ShipTypeSchema>
+export type CheckStatus = z.infer<typeof CheckStatusSchema>
+export type AgentType = 'fe' | 'be' | 'fe+be' | 'devops' | 'ai' | string
+export type Duration = z.infer<typeof DurationSchema>
+export type CodeMetrics = z.infer<typeof CodeMetricsSchema>
+export type ShipChange = z.infer<typeof ShipChangeSchema>
+export type QualityMetrics = z.infer<typeof QualityMetricsSchema>
+export type CommitInfo = z.infer<typeof CommitInfoSchema>
+export type ShippedItemSchema = z.infer<typeof ShippedItemSchema>
+export type ShippedJson = z.infer<typeof ShippedJsonSchema>
 
 // Legacy type for backwards compatibility
 export type ShippedSchema = ShippedItemSchema[]
 
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Parse and validate shipped.json content */
+export const parseShipped = (data: unknown): ShippedJson => ShippedJsonSchema.parse(data)
+export const safeParseShipped = (data: unknown) => ShippedJsonSchema.safeParse(data)
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
 export const DEFAULT_SHIPPED: ShippedJson = {
   items: [],
   lastUpdated: ''

package/core/schemas/state.ts

@@ -4,91 +4,131 @@
  * Defines the structure for state.json - current task state.
  * Queue is now separate in queue.json.
  *
- * Matches json-loader.ts types exactly.
+ * Uses Zod for runtime validation and TypeScript type inference.
+ * @version 2.0.0
  */
 
-export type Priority = 'low' | 'medium' | 'high' | 'critical'
-export type TaskType = 'feature' | 'bug' | 'improvement' | 'chore'
-export type TaskSection = 'active' | 'backlog' | 'previously_active'
+import { z } from 'zod'
 
-export interface CurrentTask {
-  id: string                  // task_xxxxxxxx
-  description: string
-  startedAt: string           // ISO8601
-  sessionId: string           // sess_xxxxxxxx
-  featureId?: string          // feat_xxxxxxxx
-}
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
 
-export interface PreviousTask {
-  id: string
-  description: string
-  status: 'paused'
-  startedAt: string           // ISO8601
-  pausedAt: string            // ISO8601
-  pauseReason?: string        // Optional reason for pausing
-}
+export const PrioritySchema = z.enum(['low', 'medium', 'high', 'critical'])
+export const TaskTypeSchema = z.enum(['feature', 'bug', 'improvement', 'chore'])
+export const TaskSectionSchema = z.enum(['active', 'backlog', 'previously_active'])
+export const TaskStatusSchema = z.enum(['pending', 'in_progress', 'completed', 'blocked', 'paused'])
+export const ActivityTypeSchema = z.enum(['task_completed', 'feature_shipped', 'idea_captured', 'session_started'])
 
-// StateJson is the wrapper for state.json file
-export interface StateJson {
-  currentTask: CurrentTask | null
-  previousTask?: PreviousTask | null
-  lastUpdated: string
-}
+export const CurrentTaskSchema = z.object({
+  id: z.string(),                   // task_xxxxxxxx
+  description: z.string(),
+  startedAt: z.string(),            // ISO8601
+  sessionId: z.string(),            // sess_xxxxxxxx
+  featureId: z.string().optional(), // feat_xxxxxxxx
+})
+
+export const PreviousTaskSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  status: z.literal('paused'),
+  startedAt: z.string(),            // ISO8601
+  pausedAt: z.string(),             // ISO8601
+  pauseReason: z.string().optional(),
+})
+
+export const StateJsonSchema = z.object({
+  currentTask: CurrentTaskSchema.nullable(),
+  previousTask: PreviousTaskSchema.nullable().optional(),
+  lastUpdated: z.string(),
+})
 
-// QueueJson is the wrapper for queue.json file
-export interface QueueTask {
-  id: string                  // task_xxxxxxxx
-  description: string
-  priority: Priority
-  type: TaskType              // detect from emoji 🐛=bug
-  featureId?: string
-  originFeature?: string      // from "(from: Feature Name)" pattern
-  completed: boolean
-  completedAt?: string        // ISO8601
-  createdAt: string           // ISO8601
-  section: TaskSection        // based on MD section
+export const QueueTaskSchema = z.object({
+  id: z.string(),                   // task_xxxxxxxx
+  description: z.string(),
+  priority: PrioritySchema,
+  type: TaskTypeSchema,             // detect from emoji 🐛=bug
+  featureId: z.string().optional(),
+  originFeature: z.string().optional(),
+  completed: z.boolean(),
+  completedAt: z.string().optional(),
+  createdAt: z.string(),            // ISO8601
+  section: TaskSectionSchema,
   // Additional fields for ZERO DATA LOSS
-  agent?: string              // "fe", "be", "fe + be"
-  groupName?: string          // "Sales Reports", "Stock Audits"
-  groupId?: string            // For grouping related tasks
-}
+  agent: z.string().optional(),     // "fe", "be", "fe + be"
+  groupName: z.string().optional(), // "Sales Reports", "Stock Audits"
+  groupId: z.string().optional(),   // For grouping related tasks
+})
 
-export interface QueueJson {
-  tasks: QueueTask[]
-  lastUpdated: string
-}
+export const QueueJsonSchema = z.object({
+  tasks: z.array(QueueTaskSchema),
+  lastUpdated: z.string(),
+})
 
-// Legacy types for backwards compatibility
-export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'paused'
-export type ActivityType = 'task_completed' | 'feature_shipped' | 'idea_captured' | 'session_started'
+export const StatsSchema = z.object({
+  tasksToday: z.number(),
+  tasksThisWeek: z.number(),
+  streak: z.number(),
+  velocity: z.string(),
+  avgDuration: z.string(),
+})
 
-export interface QueuedTask extends QueueTask {} // Alias
+export const RecentActivitySchema = z.object({
+  type: ActivityTypeSchema,
+  description: z.string(),
+  timestamp: z.string(),            // ISO8601
+  duration: z.string().optional(),
+})
 
-export interface Stats {
-  tasksToday: number
-  tasksThisWeek: number
-  streak: number
-  velocity: string
-  avgDuration: string
-}
+export const StateSchemaFull = z.object({
+  projectId: z.string(),
+  currentTask: CurrentTaskSchema.nullable(),
+  queue: z.array(QueueTaskSchema),
+  stats: StatsSchema,
+  recentActivity: z.array(RecentActivitySchema),
+  lastSync: z.string(),             // ISO8601
+})
 
-export interface RecentActivity {
-  type: ActivityType
-  description: string
-  timestamp: string // ISO8601
-  duration?: string
-}
+// =============================================================================
+// Inferred Types - Backward Compatible
+// =============================================================================
 
-export interface StateSchema {
-  projectId: string
-  currentTask: CurrentTask | null
-  queue: QueuedTask[]
-  stats: Stats
-  recentActivity: RecentActivity[]
-  lastSync: string // ISO8601
-}
+export type Priority = z.infer<typeof PrioritySchema>
+export type TaskType = z.infer<typeof TaskTypeSchema>
+export type TaskSection = z.infer<typeof TaskSectionSchema>
+export type TaskStatus = z.infer<typeof TaskStatusSchema>
+export type ActivityType = z.infer<typeof ActivityTypeSchema>
+
+export type CurrentTask = z.infer<typeof CurrentTaskSchema>
+export type PreviousTask = z.infer<typeof PreviousTaskSchema>
+export type StateJson = z.infer<typeof StateJsonSchema>
+export type QueueTask = z.infer<typeof QueueTaskSchema>
+export type QueueJson = z.infer<typeof QueueJsonSchema>
+export type Stats = z.infer<typeof StatsSchema>
+export type RecentActivity = z.infer<typeof RecentActivitySchema>
+export type StateSchema = z.infer<typeof StateSchemaFull>
+
+// Legacy alias
+export type QueuedTask = QueueTask
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
 
+/** Parse and validate state.json content */
+export const parseState = (data: unknown): StateJson => StateJsonSchema.parse(data)
+
+/** Parse and validate queue.json content */
+export const parseQueue = (data: unknown): QueueJson => QueueJsonSchema.parse(data)
+
+/** Safe parse with error result */
+export const safeParseState = (data: unknown) => StateJsonSchema.safeParse(data)
+export const safeParseQueue = (data: unknown) => QueueJsonSchema.safeParse(data)
+
+// =============================================================================
 // Defaults
+// =============================================================================
+
 export const DEFAULT_STATE: StateJson = {
   currentTask: null,
   lastUpdated: ''

package/core/server/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Server Module
+ *
+ * HTTP server for prjct-cli web dashboard and API.
+ *
+ * @module core/server
+ * @version 1.0.0
+ */
+
+export { createServer, startServer, DEFAULT_PORT } from './server'
+export { createRoutes } from './routes'
+export { createSSEManager, SSE_EVENTS } from './sse'
+
+// Re-export types from canonical location
+export type {
+  ServerConfig,
+  ServerInstance,
+  SSEClient,
+  SSEManager,
+  SSEEventType,
+} from '../types'

package/core/server/routes.ts

@@ -0,0 +1,165 @@
+/**
+ * REST API Routes for prjct-cli
+ *
+ * Provides endpoints for reading and managing project state.
+ *
+ * @version 1.0.0
+ */
+
+import { Hono } from 'hono'
+import fs from 'fs/promises'
+import path from 'path'
+import * as jsonc from 'jsonc-parser'
+
+// Storage paths relative to project data directory
+const STORAGE_PATHS = {
+  state: 'storage/state.json',
+  queue: 'storage/queue.json',
+  ideas: 'storage/ideas.json',
+  shipped: 'storage/shipped.json',
+  roadmap: 'planning/roadmap.json',
+}
+
+/**
+ * Read JSON file with JSONC support
+ */
+async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    const errors: jsonc.ParseError[] = []
+    const result = jsonc.parse(content, errors)
+    return errors.length > 0 ? null : result
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write JSON file
+ */
+async function writeJsonFile(filePath: string, data: unknown): Promise<boolean> {
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Get global project path
+ */
+function getProjectDataPath(projectId: string): string {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '~'
+  return path.join(homeDir, '.prjct-cli', 'projects', projectId)
+}
+
+/**
+ * Create API routes for a project
+ */
+export function createRoutes(projectId: string, _projectPath: string): Hono {
+  const api = new Hono()
+  const dataPath = getProjectDataPath(projectId)
+
+  // GET /state - Current task state
+  api.get('/state', async (c) => {
+    const data = await readJsonFile(path.join(dataPath, STORAGE_PATHS.state))
+    if (!data) {
+      return c.json({ currentTask: null, lastUpdated: '' })
+    }
+    return c.json(data)
+  })
+
+  // GET /queue - Task queue
+  api.get('/queue', async (c) => {
+    const data = await readJsonFile(path.join(dataPath, STORAGE_PATHS.queue))
+    if (!data) {
+      return c.json({ tasks: [], lastUpdated: '' })
+    }
+    return c.json(data)
+  })
+
+  // GET /ideas - Ideas backlog
+  api.get('/ideas', async (c) => {
+    const data = await readJsonFile(path.join(dataPath, STORAGE_PATHS.ideas))
+    if (!data) {
+      return c.json({ ideas: [], lastUpdated: '' })
+    }
+    return c.json(data)
+  })
+
+  // GET /roadmap - Feature roadmap
+  api.get('/roadmap', async (c) => {
+    const data = await readJsonFile(path.join(dataPath, STORAGE_PATHS.roadmap))
+    if (!data) {
+      return c.json({ features: [], backlog: [], lastUpdated: '' })
+    }
+    return c.json(data)
+  })
+
+  // GET /shipped - Shipped items
+  api.get('/shipped', async (c) => {
+    const data = await readJsonFile(path.join(dataPath, STORAGE_PATHS.shipped))
+    if (!data) {
+      return c.json({ items: [], lastUpdated: '' })
+    }
+    return c.json(data)
+  })
+
+  // GET /dashboard - Combined dashboard data
+  api.get('/dashboard', async (c) => {
+    const [state, queue, ideas, roadmap, shipped] = await Promise.all([
+      readJsonFile(path.join(dataPath, STORAGE_PATHS.state)),
+      readJsonFile(path.join(dataPath, STORAGE_PATHS.queue)),
+      readJsonFile(path.join(dataPath, STORAGE_PATHS.ideas)),
+      readJsonFile(path.join(dataPath, STORAGE_PATHS.roadmap)),
+      readJsonFile(path.join(dataPath, STORAGE_PATHS.shipped)),
+    ])
+
+    return c.json({
+      projectId,
+      state: state || { currentTask: null, lastUpdated: '' },
+      queue: queue || { tasks: [], lastUpdated: '' },
+      ideas: ideas || { ideas: [], lastUpdated: '' },
+      roadmap: roadmap || { features: [], backlog: [], lastUpdated: '' },
+      shipped: shipped || { items: [], lastUpdated: '' },
+      timestamp: new Date().toISOString(),
+    })
+  })
+
+  // POST /state - Update state (for future use)
+  api.post('/state', async (c) => {
+    try {
+      const body = await c.req.json()
+      const filePath = path.join(dataPath, STORAGE_PATHS.state)
+      const success = await writeJsonFile(filePath, body)
+      if (success) {
+        return c.json({ success: true })
+      }
+      return c.json({ success: false, error: 'Failed to write' }, 500)
+    } catch (e) {
+      return c.json({ success: false, error: String(e) }, 400)
+    }
+  })
+
+  // GET /context - Read context markdown files
+  api.get('/context/:name', async (c) => {
+    const name = c.req.param('name')
+    const allowedFiles = ['now', 'next', 'ideas', 'shipped']
+
+    if (!allowedFiles.includes(name)) {
+      return c.json({ error: 'Invalid context file' }, 400)
+    }
+
+    try {
+      const filePath = path.join(dataPath, 'context', `${name}.md`)
+      const content = await fs.readFile(filePath, 'utf-8')
+      return c.text(content, 200, { 'Content-Type': 'text/markdown' })
+    } catch {
+      return c.text('', 200, { 'Content-Type': 'text/markdown' })
+    }
+  })
+
+  return api
+}