prjct-cli 0.19.0 → 0.20.1

package/core/utils/collection-filters.ts

@@ -0,0 +1,245 @@
+/**
+ * Collection Filter Utilities
+ *
+ * Reusable filtering and sorting functions for storage collections.
+ * Eliminates duplicated filter logic across storage classes.
+ */
+
+import type { Priority, TaskSection } from '../schemas/state'
+
+/**
+ * Priority order mapping for sorting (highest priority first)
+ */
+export const PRIORITY_ORDER: Record<Priority, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+}
+
+/**
+ * Section order mapping for sorting
+ */
+export const SECTION_ORDER: Record<TaskSection, number> = {
+  active: 0,
+  previously_active: 1,
+  backlog: 2,
+}
+
+/**
+ * Filter items by a specific field value
+ */
+export function filterByField<T, K extends keyof T>(
+  items: T[],
+  field: K,
+  value: T[K]
+): T[] {
+  return items.filter((item) => item[field] === value)
+}
+
+/**
+ * Filter items by multiple field values (OR logic)
+ */
+export function filterByFieldIn<T, K extends keyof T>(
+  items: T[],
+  field: K,
+  values: T[K][]
+): T[] {
+  return items.filter((item) => values.includes(item[field]))
+}
+
+/**
+ * Filter items excluding a specific field value
+ */
+export function filterByFieldNot<T, K extends keyof T>(
+  items: T[],
+  field: K,
+  value: T[K]
+): T[] {
+  return items.filter((item) => item[field] !== value)
+}
+
+/**
+ * Combined filter: field equals value AND another field is falsy
+ * Useful for filtering active items that aren't completed
+ */
+export function filterActiveByField<T, K extends keyof T>(
+  items: T[],
+  field: K,
+  value: T[K],
+  activeField: keyof T
+): T[] {
+  return items.filter((item) => item[field] === value && !item[activeField])
+}
+
+/**
+ * Filter items where a field is truthy
+ */
+export function filterByTruthy<T, K extends keyof T>(items: T[], field: K): T[] {
+  return items.filter((item) => Boolean(item[field]))
+}
+
+/**
+ * Filter items where a field is falsy
+ */
+export function filterByFalsy<T, K extends keyof T>(items: T[], field: K): T[] {
+  return items.filter((item) => !item[field])
+}
+
+/**
+ * Sort items by priority (highest first)
+ */
+export function sortByPriority<T extends { priority: Priority }>(items: T[]): T[] {
+  return [...items].sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority])
+}
+
+/**
+ * Sort items by section, then priority
+ */
+export function sortBySectionAndPriority<T extends { section: TaskSection; priority: Priority }>(
+  items: T[]
+): T[] {
+  return [...items].sort((a, b) => {
+    const sectionDiff = SECTION_ORDER[a.section] - SECTION_ORDER[b.section]
+    if (sectionDiff !== 0) return sectionDiff
+    return PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]
+  })
+}
+
+/**
+ * Sort items by date field
+ */
+export function sortByDate<T>(
+  items: T[],
+  dateField: keyof T,
+  direction: 'asc' | 'desc' = 'desc'
+): T[] {
+  return [...items].sort((a, b) => {
+    const dateA = new Date(a[dateField] as string).getTime()
+    const dateB = new Date(b[dateField] as string).getTime()
+    return direction === 'desc' ? dateB - dateA : dateA - dateB
+  })
+}
+
+/**
+ * Filter items by date range
+ */
+export function filterByDateRange<T>(
+  items: T[],
+  dateField: keyof T,
+  startDate: Date,
+  endDate: Date
+): T[] {
+  return items.filter((item) => {
+    const date = new Date(item[dateField] as string)
+    return date >= startDate && date <= endDate
+  })
+}
+
+/**
+ * Filter items from the last N days
+ */
+export function filterByLastDays<T>(items: T[], dateField: keyof T, days: number): T[] {
+  const startDate = new Date()
+  startDate.setDate(startDate.getDate() - days)
+  return filterByDateRange(items, dateField, startDate, new Date())
+}
+
+/**
+ * Group items by a field value
+ */
+export function groupByField<T, K extends keyof T>(items: T[], field: K): Map<T[K], T[]> {
+  const groups = new Map<T[K], T[]>()
+
+  for (const item of items) {
+    const key = item[field]
+    if (!groups.has(key)) {
+      groups.set(key, [])
+    }
+    groups.get(key)!.push(item)
+  }
+
+  return groups
+}
+
+/**
+ * Count items by field value
+ */
+export function countByField<T, K extends keyof T>(items: T[], field: K): Map<T[K], number> {
+  const counts = new Map<T[K], number>()
+
+  for (const item of items) {
+    const key = item[field]
+    counts.set(key, (counts.get(key) || 0) + 1)
+  }
+
+  return counts
+}
+
+/**
+ * Get the first N items
+ */
+export function take<T>(items: T[], count: number): T[] {
+  return items.slice(0, count)
+}
+
+/**
+ * Get the last N items
+ */
+export function takeLast<T>(items: T[], count: number): T[] {
+  return items.slice(-count)
+}
+
+/**
+ * Find item by field value
+ */
+export function findByField<T, K extends keyof T>(
+  items: T[],
+  field: K,
+  value: T[K]
+): T | undefined {
+  return items.find((item) => item[field] === value)
+}
+
+/**
+ * Check if any item matches field value
+ */
+export function anyByField<T, K extends keyof T>(items: T[], field: K, value: T[K]): boolean {
+  return items.some((item) => item[field] === value)
+}
+
+/**
+ * Remove duplicates by field
+ */
+export function uniqueByField<T, K extends keyof T>(items: T[], field: K): T[] {
+  const seen = new Set<T[K]>()
+  return items.filter((item) => {
+    if (seen.has(item[field])) return false
+    seen.add(item[field])
+    return true
+  })
+}
+
+// Default export for CommonJS compatibility
+export default {
+  PRIORITY_ORDER,
+  SECTION_ORDER,
+  filterByField,
+  filterByFieldIn,
+  filterByFieldNot,
+  filterActiveByField,
+  filterByTruthy,
+  filterByFalsy,
+  sortByPriority,
+  sortBySectionAndPriority,
+  sortByDate,
+  filterByDateRange,
+  filterByLastDays,
+  groupByField,
+  countByField,
+  take,
+  takeLast,
+  findByField,
+  anyByField,
+  uniqueByField,
+}

package/core/utils/date-helper.ts

@@ -7,11 +7,7 @@
  * - commands.ts (38+ inline date operations)
  */
 
-export interface DateComponents {
-  year: string
-  month: string
-  day: string
-}
+import type { DateComponents } from '../types'
 
 /**
  * Format a date to YYYY-MM-DD format

package/core/utils/file-helper.ts

@@ -1,5 +1,6 @@
 import fs from 'fs/promises'
 import path from 'path'
+import { type NodeError, isNotFoundError } from '../types/fs'
 
 /**
  * File Helper - Centralized file operations with error handling
@@ -16,10 +17,6 @@ interface ListFilesOptions {
   extension?: string
 }
 
-interface NodeError extends Error {
-  code?: string
-}
-
 /**
  * Read JSON file and parse
  */
@@ -28,7 +25,7 @@ export async function readJson<T = unknown>(filePath: string, defaultValue: T |
     const content = await fs.readFile(filePath, 'utf-8')
     return JSON.parse(content) as T
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return defaultValue
     }
     throw error
@@ -50,7 +47,7 @@ export async function readFile(filePath: string, defaultValue = ''): Promise<str
   try {
     return await fs.readFile(filePath, 'utf-8')
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return defaultValue
     }
     throw error
@@ -84,6 +81,15 @@ export async function appendToFile(filePath: string, content: string): Promise<v
   await fs.appendFile(filePath, content, 'utf-8')
 }
 
+/**
+ * Append a single line to file (with newline and directory creation)
+ */
+export async function appendLine(filePath: string, line: string): Promise<void> {
+  const dir = path.dirname(filePath)
+  await fs.mkdir(dir, { recursive: true })
+  await fs.appendFile(filePath, line + '\n', 'utf-8')
+}
+
 /**
  * Prepend to text file (adds content at beginning)
  */
@@ -92,7 +98,7 @@ export async function prependToFile(filePath: string, content: string): Promise<
     const existing = await fs.readFile(filePath, 'utf-8')
     await fs.writeFile(filePath, content + existing, 'utf-8')
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       await fs.writeFile(filePath, content, 'utf-8')
     } else {
       throw error
@@ -139,7 +145,7 @@ export async function deleteFile(filePath: string): Promise<boolean> {
     await fs.unlink(filePath)
     return true
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return false // File didn't exist
     }
     throw error
@@ -154,7 +160,7 @@ export async function deleteDir(dirPath: string): Promise<boolean> {
     await fs.rm(dirPath, { recursive: true, force: true })
     return true
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return false
     }
     throw error
@@ -183,7 +189,7 @@ export async function listFiles(dirPath: string, options: ListFilesOptions = {})
 
     return files.map((entry) => entry.name)
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return []
     }
     throw error
@@ -257,7 +263,11 @@ export default {
   readFile,
   writeFile,
   atomicWrite,
+  appendToFile,
+  appendLine,
+  prependToFile,
   fileExists,
+  dirExists,
   ensureDir,
   deleteFile,
   deleteDir,

package/core/utils/jsonl-helper.ts

@@ -2,6 +2,7 @@ import fs from 'fs/promises'
 import fsSync from 'fs'
 import readline from 'readline'
 import path from 'path'
+import { isNotFoundError } from '../types/fs'
 
 /**
  * JSONL Helper - Centralized JSONL parsing and writing
@@ -17,10 +18,6 @@ import path from 'path'
  * {"ts":"2025-10-04T15:00:00Z","type":"task_start","task":"JWT"}
  */
 
-interface NodeError extends Error {
-  code?: string
-}
-
 interface FileSizeWarning {
   sizeMB: number
   isLarge: boolean
@@ -60,7 +57,7 @@ export async function readJsonLines<T = Record<string, unknown>>(filePath: strin
     const content = await fs.readFile(filePath, 'utf-8')
     return parseJsonLines<T>(content)
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return [] // File doesn't exist, return empty array
     }
     throw error
@@ -113,7 +110,7 @@ export async function countJsonLines(filePath: string): Promise<number> {
     const lines = content.split('\n').filter((line) => line.trim())
     return lines.length
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return 0
     }
     throw error
@@ -200,7 +197,7 @@ export async function readJsonLinesStreaming<T = Record<string, unknown>>(
 
     return lines
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return []
     }
     throw error
@@ -215,7 +212,7 @@ export async function getFileSizeMB(filePath: string): Promise<number> {
     const stats = await fs.stat(filePath)
     return stats.size / (1024 * 1024)
   } catch (error) {
-    if ((error as NodeError).code === 'ENOENT') {
+    if (isNotFoundError(error)) {
       return 0
     }
     throw error

package/core/utils/markdown-builder.ts

@@ -0,0 +1,277 @@
+/**
+ * MarkdownBuilder - Fluent API for constructing markdown documents
+ *
+ * Eliminates duplicated markdown generation across:
+ * - state-storage.ts (~35 lines)
+ * - queue-storage.ts (~45 lines)
+ * - ideas-storage.ts (~40 lines)
+ * - shipped-storage.ts (~25 lines)
+ *
+ * Usage:
+ * ```typescript
+ * const content = md()
+ *   .h1('Title')
+ *   .p('Description')
+ *   .when(hasItems, m => m.list(items))
+ *   .build()
+ * ```
+ */
+
+export class MarkdownBuilder {
+  private lines: string[] = []
+
+  /**
+   * Add H1 heading
+   */
+  h1(text: string): this {
+    this.lines.push(`# ${text}`, '')
+    return this
+  }
+
+  /**
+   * Add H2 heading
+   */
+  h2(text: string): this {
+    this.lines.push(`## ${text}`, '')
+    return this
+  }
+
+  /**
+   * Add H3 heading
+   */
+  h3(text: string): this {
+    this.lines.push(`### ${text}`)
+    return this
+  }
+
+  /**
+   * Add H4 heading
+   */
+  h4(text: string): this {
+    this.lines.push(`#### ${text}`)
+    return this
+  }
+
+  /**
+   * Add paragraph
+   */
+  p(text: string): this {
+    this.lines.push(text, '')
+    return this
+  }
+
+  /**
+   * Add bold text on its own line
+   */
+  bold(text: string): this {
+    this.lines.push(`**${text}**`)
+    return this
+  }
+
+  /**
+   * Add italic text on its own line
+   */
+  italic(text: string): this {
+    this.lines.push(`*${text}*`)
+    return this
+  }
+
+  /**
+   * Add inline code
+   */
+  code(text: string): this {
+    this.lines.push(`\`${text}\``)
+    return this
+  }
+
+  /**
+   * Add code block
+   */
+  codeBlock(code: string, lang = ''): this {
+    this.lines.push(`\`\`\`${lang}`, code, '```', '')
+    return this
+  }
+
+  /**
+   * Add list item with optional checkbox
+   */
+  li(text: string, options?: { checked?: boolean; indent?: number }): this {
+    const indent = '  '.repeat(options?.indent ?? 0)
+    if (options?.checked !== undefined) {
+      this.lines.push(`${indent}- [${options.checked ? 'x' : ' '}] ${text}`)
+    } else {
+      this.lines.push(`${indent}- ${text}`)
+    }
+    return this
+  }
+
+  /**
+   * Add numbered list item
+   */
+  oli(text: string, number: number): this {
+    this.lines.push(`${number}. ${text}`)
+    return this
+  }
+
+  /**
+   * Add multiple list items
+   */
+  list(items: string[], options?: { checked?: boolean }): this {
+    items.forEach((item) => this.li(item, options))
+    return this
+  }
+
+  /**
+   * Add multiple numbered list items
+   */
+  orderedList(items: string[]): this {
+    items.forEach((item, i) => this.oli(item, i + 1))
+    return this
+  }
+
+  /**
+   * Add horizontal rule
+   */
+  hr(): this {
+    this.lines.push('', '---', '')
+    return this
+  }
+
+  /**
+   * Add blank line
+   */
+  blank(): this {
+    this.lines.push('')
+    return this
+  }
+
+  /**
+   * Add raw line(s)
+   */
+  raw(text: string): this {
+    this.lines.push(text)
+    return this
+  }
+
+  /**
+   * Add multiple raw lines
+   */
+  rawLines(lines: string[]): this {
+    this.lines.push(...lines)
+    return this
+  }
+
+  /**
+   * Add blockquote
+   */
+  quote(text: string): this {
+    this.lines.push(`> ${text}`)
+    return this
+  }
+
+  /**
+   * Add link
+   */
+  link(text: string, url: string): this {
+    this.lines.push(`[${text}](${url})`)
+    return this
+  }
+
+  /**
+   * Add key-value pair (bold key)
+   */
+  kv(key: string, value: string): this {
+    this.lines.push(`**${key}:** ${value}`)
+    return this
+  }
+
+  /**
+   * Add table from data
+   */
+  table(headers: string[], rows: string[][]): this {
+    // Header row
+    this.lines.push(`| ${headers.join(' | ')} |`)
+    // Separator
+    this.lines.push(`| ${headers.map(() => '---').join(' | ')} |`)
+    // Data rows
+    rows.forEach((row) => {
+      this.lines.push(`| ${row.join(' | ')} |`)
+    })
+    this.blank()
+    return this
+  }
+
+  /**
+   * Conditional block - only adds content if condition is true
+   */
+  when(condition: boolean, builder: (md: MarkdownBuilder) => void): this {
+    if (condition) {
+      builder(this)
+    }
+    return this
+  }
+
+  /**
+   * Optional block - only adds content if value exists
+   */
+  maybe<T>(value: T | null | undefined, builder: (md: MarkdownBuilder, val: T) => void): this {
+    if (value != null) {
+      builder(this, value)
+    }
+    return this
+  }
+
+  /**
+   * Iterate and build for each item
+   */
+  each<T>(items: T[], builder: (md: MarkdownBuilder, item: T, index: number) => void): this {
+    items.forEach((item, i) => builder(this, item, i))
+    return this
+  }
+
+  /**
+   * Add section with heading and content
+   */
+  section(heading: string, level: 1 | 2 | 3 | 4, builder: (md: MarkdownBuilder) => void): this {
+    switch (level) {
+      case 1:
+        this.h1(heading)
+        break
+      case 2:
+        this.h2(heading)
+        break
+      case 3:
+        this.h3(heading)
+        break
+      case 4:
+        this.h4(heading)
+        break
+    }
+    builder(this)
+    return this
+  }
+
+  /**
+   * Build final markdown string
+   */
+  build(): string {
+    return this.lines.join('\n')
+  }
+
+  /**
+   * Get current line count
+   */
+  get length(): number {
+    return this.lines.length
+  }
+}
+
+/**
+ * Factory function for fluent API
+ */
+export function md(): MarkdownBuilder {
+  return new MarkdownBuilder()
+}
+
+// Default export
+export default { MarkdownBuilder, md }