@vanshbhardwaj/worklog 1.0.0

package/src/repositories/work-unit.ts

@@ -0,0 +1,466 @@
+import Database from 'better-sqlite3';
+import { WorkUnit, WorkUnitType, WorkUnitStatus, WorkUnitPriority } from '../models/work-unit.js';
+import { DatabaseError } from '../errors/index.js';
+import { logger } from '../core/logger.js';
+
+export interface SearchFilters {
+  tag?: string;
+  module?: string;
+  status?: string;
+  type?: string;
+}
+
+export interface WorkUnitStats {
+  totalCount: number;
+  typeDistribution: { type: string; count: number }[];
+  statusDistribution: { status: string; count: number }[];
+  moduleDistribution: { module: string; count: number }[];
+  dailyActivity: { day: string; count: number }[];
+}
+
+export class WorkUnitRepository {
+  constructor(private db: Database.Database) {}
+
+  /**
+   * Creates a new WorkUnit in the database.
+   * Inserts relations into work_unit_tags and work_unit_relations under a transaction.
+   */
+  create(workUnitData: Omit<WorkUnit, 'id'>): WorkUnit {
+    const createTx = this.db.transaction(() => {
+      // 1. Insert into main work_units table
+      const insertUnit = this.db.prepare(`
+        INSERT INTO work_units (
+          title, type, status, priority, module, description, next_step, decision, blocker, notes, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+
+      const result = insertUnit.run(
+        workUnitData.title,
+        workUnitData.type,
+        workUnitData.status,
+        workUnitData.priority,
+        workUnitData.module,
+        workUnitData.description,
+        workUnitData.nextStep,
+        workUnitData.decision,
+        workUnitData.blocker,
+        workUnitData.notes,
+        workUnitData.createdAt,
+        workUnitData.updatedAt,
+      );
+
+      const workUnitId = Number(result.lastInsertRowid);
+
+      // 2. Insert tags
+      if (workUnitData.tags && workUnitData.tags.length > 0) {
+        const insertTag = this.db.prepare(`
+          INSERT INTO work_unit_tags (work_unit_id, tag) VALUES (?, ?)
+        `);
+        for (const tag of workUnitData.tags) {
+          insertTag.run(workUnitId, tag);
+        }
+      }
+
+      // 3. Insert relations
+      if (workUnitData.relatedWorkUnits && workUnitData.relatedWorkUnits.length > 0) {
+        const insertRelation = this.db.prepare(`
+          INSERT INTO work_unit_relations (work_unit_id, related_work_unit_id) VALUES (?, ?)
+        `);
+        const checkStmt = this.db.prepare('SELECT 1 FROM work_units WHERE id = ?');
+        for (const relId of workUnitData.relatedWorkUnits) {
+          if (!checkStmt.get(relId)) {
+            throw new DatabaseError(`Related work unit with ID ${relId} does not exist.`);
+          }
+          insertRelation.run(workUnitId, relId);
+        }
+      }
+
+      return workUnitId;
+    });
+
+    try {
+      const id = createTx();
+      return this.findById(id)!;
+    } catch (error: any) {
+      if (error instanceof DatabaseError) throw error;
+      throw new DatabaseError('Failed to create work unit', error.message);
+    }
+  }
+
+  /**
+   * Fetches a WorkUnit by ID and joins related tags and relations.
+   */
+  findById(id: number): WorkUnit | null {
+    try {
+      // 1. Fetch main record
+      const selectUnit = this.db.prepare(`
+        SELECT * FROM work_units WHERE id = ?
+      `);
+      const row = selectUnit.get(id) as any;
+      if (!row) {
+        return null;
+      }
+
+      // 2. Fetch tags
+      const selectTags = this.db.prepare(`
+        SELECT tag FROM work_unit_tags WHERE work_unit_id = ? ORDER BY tag ASC
+      `);
+      const tags = selectTags.all(id).map((r: any) => r.tag);
+
+      // 3. Fetch relations
+      const selectRelations = this.db.prepare(`
+        SELECT related_work_unit_id FROM work_unit_relations WHERE work_unit_id = ? ORDER BY related_work_unit_id ASC
+      `);
+      const related = selectRelations.all(id).map((r: any) => Number(r.related_work_unit_id));
+
+      // 4. Map DB row to Domain Model
+      return {
+        id: Number(row.id),
+        title: row.title,
+        type: row.type as WorkUnitType,
+        status: row.status as WorkUnitStatus,
+        priority: row.priority as WorkUnitPriority | null,
+        module: row.module,
+        description: row.description,
+        nextStep: row.next_step,
+        decision: row.decision,
+        blocker: row.blocker,
+        tags,
+        relatedWorkUnits: related,
+        notes: row.notes,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+      };
+    } catch (error: any) {
+      throw new DatabaseError(`Failed to find work unit by ID ${id}`, error.message);
+    }
+  }
+
+  /**
+   * Updates an existing WorkUnit.
+   * Handles differential updates for fields, tags, and relations.
+   */
+  update(
+    id: number,
+    workUnitData: Partial<Omit<WorkUnit, 'id' | 'createdAt'>> & { updatedAt: string },
+  ): WorkUnit {
+    const updateTx = this.db.transaction(() => {
+      // 1. Check if exists
+      const existing = this.findById(id);
+      if (!existing) {
+        throw new DatabaseError(`Work unit with ID ${id} not found.`);
+      }
+
+      // 2. Build SET clause dynamically
+      const updates: string[] = [];
+      const values: any[] = [];
+
+      const fieldsMap: { [key: string]: string } = {
+        title: 'title',
+        type: 'type',
+        status: 'status',
+        priority: 'priority',
+        module: 'module',
+        description: 'description',
+        nextStep: 'next_step',
+        decision: 'decision',
+        blocker: 'blocker',
+        notes: 'notes',
+        updatedAt: 'updated_at',
+      };
+
+      for (const [key, dbCol] of Object.entries(fieldsMap)) {
+        if (key in workUnitData) {
+          updates.push(`${dbCol} = ?`);
+          values.push((workUnitData as any)[key]);
+        }
+      }
+
+      if (updates.length > 0) {
+        values.push(id);
+        const updateStmt = this.db.prepare(`
+          UPDATE work_units SET ${updates.join(', ')} WHERE id = ?
+        `);
+        updateStmt.run(...values);
+      }
+
+      // 3. Update tags if provided
+      if (workUnitData.tags !== undefined) {
+        const deleteTags = this.db.prepare('DELETE FROM work_unit_tags WHERE work_unit_id = ?');
+        deleteTags.run(id);
+
+        if (workUnitData.tags.length > 0) {
+          const insertTag = this.db.prepare(
+            'INSERT INTO work_unit_tags (work_unit_id, tag) VALUES (?, ?)',
+          );
+          for (const tag of workUnitData.tags) {
+            insertTag.run(id, tag);
+          }
+        }
+      }
+
+      // 4. Update relations if provided
+      if (workUnitData.relatedWorkUnits !== undefined) {
+        const deleteRelations = this.db.prepare(
+          'DELETE FROM work_unit_relations WHERE work_unit_id = ?',
+        );
+        deleteRelations.run(id);
+
+        if (workUnitData.relatedWorkUnits.length > 0) {
+          const insertRelation = this.db.prepare(
+            'INSERT INTO work_unit_relations (work_unit_id, related_work_unit_id) VALUES (?, ?)',
+          );
+          const checkStmt = this.db.prepare('SELECT 1 FROM work_units WHERE id = ?');
+          for (const relId of workUnitData.relatedWorkUnits) {
+            if (!checkStmt.get(relId)) {
+              throw new DatabaseError(`Related work unit with ID ${relId} does not exist.`);
+            }
+            insertRelation.run(id, relId);
+          }
+        }
+      }
+    });
+
+    try {
+      updateTx();
+      return this.findById(id)!;
+    } catch (error: any) {
+      if (error instanceof DatabaseError) throw error;
+      throw new DatabaseError(`Failed to update work unit by ID ${id}`, error.message);
+    }
+  }
+
+  /**
+   * Deletes a WorkUnit. Returns true if changes were made.
+   */
+  delete(id: number): boolean {
+    try {
+      const deleteStmt = this.db.prepare('DELETE FROM work_units WHERE id = ?');
+      const info = deleteStmt.run(id);
+      return info.changes > 0;
+    } catch (error: any) {
+      throw new DatabaseError(`Failed to delete work unit by ID ${id}`, error.message);
+    }
+  }
+
+  /**
+   * Finds the most recent work units, ordered by creation date descending.
+   */
+  findRecent(limit: number = 10): WorkUnit[] {
+    try {
+      const selectIds = this.db.prepare(`
+        SELECT id FROM work_units ORDER BY created_at DESC LIMIT ?
+      `);
+      const rows = selectIds.all(limit);
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError('Failed to fetch recent work units', error.message);
+    }
+  }
+
+  /**
+   * Finds work units matching a specific status.
+   */
+  findByStatus(status: WorkUnitStatus): WorkUnit[] {
+    try {
+      const selectIds = this.db.prepare(`
+        SELECT id FROM work_units WHERE status = ? ORDER BY created_at DESC
+      `);
+      const rows = selectIds.all(status);
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError(`Failed to fetch work units by status: ${status}`, error.message);
+    }
+  }
+
+  /**
+   * Finds work units matching a specific type.
+   */
+  findByType(type: WorkUnitType): WorkUnit[] {
+    try {
+      const selectIds = this.db.prepare(`
+        SELECT id FROM work_units WHERE type = ? ORDER BY created_at DESC
+      `);
+      const rows = selectIds.all(type);
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError(`Failed to fetch work units by type: ${type}`, error.message);
+    }
+  }
+
+  /**
+   * Finds all unfinished work units (Planned, In Progress, Blocked) ordered by updatedAt descending.
+   */
+  findUnfinished(): WorkUnit[] {
+    try {
+      const selectIds = this.db.prepare(`
+        SELECT id FROM work_units
+        WHERE status IN ('Planned', 'In Progress', 'Blocked')
+        ORDER BY updated_at DESC
+      `);
+      const rows = selectIds.all();
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError('Failed to fetch unfinished work units', error.message);
+    }
+  }
+
+  /**
+   * Finds work units created or updated since an ISO timestamp.
+   */
+  findCreatedOrUpdatedAfter(isoString: string): WorkUnit[] {
+    try {
+      const selectIds = this.db.prepare(`
+        SELECT id FROM work_units
+        WHERE created_at >= ? OR updated_at >= ?
+        ORDER BY created_at DESC
+      `);
+      const rows = selectIds.all(isoString, isoString);
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError(
+        `Failed to fetch work units updated after ${isoString}`,
+        error.message,
+      );
+    }
+  }
+
+  /**
+   * Runs analytical SQL queries to fetch count aggregates.
+   */
+  getStats(sinceIsoString: string): WorkUnitStats {
+    try {
+      // 1. Total Count
+      const totalCount = (
+        this.db.prepare('SELECT COUNT(*) as count FROM work_units').get() as any
+      ).count;
+
+      // 2. Type Distribution
+      const typeRows = this.db
+        .prepare(
+          'SELECT type, COUNT(*) as count FROM work_units GROUP BY type ORDER BY count DESC',
+        )
+        .all() as any[];
+      const typeDistribution = typeRows.map((r) => ({ type: r.type, count: r.count }));
+
+      // 3. Status Distribution
+      const statusRows = this.db
+        .prepare(
+          'SELECT status, COUNT(*) as count FROM work_units GROUP BY status ORDER BY count DESC',
+        )
+        .all() as any[];
+      const statusDistribution = statusRows.map((r) => ({ status: r.status, count: r.count }));
+
+      // 4. Module Distribution
+      const moduleRows = this.db
+        .prepare(`
+          SELECT module, COUNT(*) as count FROM work_units
+          WHERE module IS NOT NULL AND module != ''
+          GROUP BY module ORDER BY count DESC
+        `)
+        .all() as any[];
+      const moduleDistribution = moduleRows.map((r) => ({ module: r.module, count: r.count }));
+
+      // 5. Daily activity: Group by Date parsed from ISO string
+      const dailyRows = this.db
+        .prepare(`
+          SELECT date(created_at) as day, COUNT(*) as count FROM work_units
+          WHERE created_at >= ?
+          GROUP BY day ORDER BY day ASC
+        `)
+        .all(sinceIsoString) as any[];
+      const dailyActivity = dailyRows.map((r) => ({ day: r.day, count: r.count }));
+
+      return {
+        totalCount,
+        typeDistribution,
+        statusDistribution,
+        moduleDistribution,
+        dailyActivity,
+      };
+    } catch (error: any) {
+      throw new DatabaseError('Failed to fetch aggregate statistics', error.message);
+    }
+  }
+
+  /**
+   * Case-insensitive, structured multi-criteria search combining FTS5 and standard filters.
+   */
+  search(query: string, filters: SearchFilters = {}): WorkUnit[] {
+    try {
+      let ids: number[] = [];
+      const hasQuery = query.trim().length > 0;
+
+      if (hasQuery) {
+        const trimmed = query.trim();
+        // FTS5 MATCH format
+        const ftsQuery = `"${trimmed}" OR ${trimmed}*`;
+        try {
+          const stmt = this.db.prepare(`
+            SELECT rowid as id FROM work_units_fts WHERE work_units_fts MATCH ?
+          `);
+          ids = stmt.all(ftsQuery).map((r: any) => Number(r.id));
+        } catch (ftsError: any) {
+          logger.warn({ ftsError, query }, 'FTS MATCH failed; using fallback LIKE list');
+          // If FTS fails (due to query syntax), do a fallback retrieve of all IDs containing query in LIKE
+          const fallbackStmt = this.db.prepare(`
+            SELECT id FROM work_units
+            WHERE title LIKE ? OR description LIKE ? OR notes LIKE ? OR decision LIKE ? OR blocker LIKE ?
+          `);
+          const likeParam = `%${trimmed}%`;
+          ids = fallbackStmt
+            .all(likeParam, likeParam, likeParam, likeParam, likeParam)
+            .map((r: any) => Number(r.id));
+        }
+
+        if (ids.length === 0) {
+          return []; // no text matches, exit early
+        }
+      }
+
+      // Build conditional SQL query
+      const clauses: string[] = [];
+      const params: any[] = [];
+
+      if (hasQuery) {
+        // Chunk ID binds if too large, but for standard search length we place binds directly
+        clauses.push(`id IN (${ids.map(() => '?').join(',')})`);
+        params.push(...ids);
+      }
+
+      if (filters.module) {
+        clauses.push('LOWER(module) = LOWER(?)');
+        params.push(filters.module);
+      }
+
+      if (filters.status) {
+        clauses.push('LOWER(status) = LOWER(?)');
+        params.push(filters.status);
+      }
+
+      if (filters.type) {
+        clauses.push('LOWER(type) = LOWER(?)');
+        params.push(filters.type);
+      }
+
+      if (filters.tag) {
+        clauses.push(`id IN (
+          SELECT work_unit_id FROM work_unit_tags WHERE LOWER(tag) = LOWER(?)
+        )`);
+        params.push(filters.tag);
+      }
+
+      const whereClause = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+      const sql = `
+        SELECT id FROM work_units
+        ${whereClause}
+        ORDER BY created_at DESC
+      `;
+
+      const rows = this.db.prepare(sql).all(...params);
+      return rows.map((row: any) => this.findById(row.id) as WorkUnit);
+    } catch (error: any) {
+      throw new DatabaseError(`Search operation failed: ${error.message}`);
+    }
+  }
+}

package/src/services/work-unit.ts

@@ -0,0 +1,131 @@
+import { SearchFilters, WorkUnitRepository, WorkUnitStats } from '../repositories/work-unit.js';
+import {
+  CreateWorkUnitSchema,
+  UpdateWorkUnitSchema,
+} from '../validators/work-unit.js';
+import { WorkUnit, WorkUnitType, WorkUnitStatus } from '../models/work-unit.js';
+import { ValidationError } from '../errors/index.js';
+
+export class WorkUnitService {
+  constructor(private repo: WorkUnitRepository) {}
+
+  /**
+   * Validates creation input at the service boundary, assigns initial timestamps, and persists to database.
+   */
+  createWorkUnit(input: unknown): WorkUnit {
+    const result = CreateWorkUnitSchema.safeParse(input);
+    if (!result.success) {
+      const errorMsg = result.error.issues
+        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+        .join(', ');
+      throw new ValidationError(errorMsg);
+    }
+
+    const validated = result.data;
+    const now = new Date().toISOString();
+
+    const workUnitData: Omit<WorkUnit, 'id'> = {
+      ...validated,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    return this.repo.create(workUnitData);
+  }
+
+  /**
+   * Validates update input, updates timestamp, and runs repository update statement.
+   */
+  updateWorkUnit(id: number, input: unknown): WorkUnit {
+    if (!id || id <= 0 || !Number.isInteger(id)) {
+      throw new ValidationError('A valid positive integer ID is required.');
+    }
+
+    const result = UpdateWorkUnitSchema.safeParse(input);
+    if (!result.success) {
+      const errorMsg = result.error.issues
+        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+        .join(', ');
+      throw new ValidationError(errorMsg);
+    }
+
+    const validated = result.data;
+    const now = new Date().toISOString();
+
+    const workUnitData: Partial<Omit<WorkUnit, 'id' | 'createdAt'>> & { updatedAt: string } = {
+      ...validated,
+      updatedAt: now,
+    };
+
+    return this.repo.update(id, workUnitData);
+  }
+
+  /**
+   * Fetches a WorkUnit by its ID. Throws on negative/decimal values.
+   */
+  getWorkUnit(id: number): WorkUnit | null {
+    if (!id || id <= 0 || !Number.isInteger(id)) {
+      throw new ValidationError('A valid positive integer ID is required.');
+    }
+    return this.repo.findById(id);
+  }
+
+  /**
+   * Deletes a WorkUnit by ID. Returns true if deleted.
+   */
+  deleteWorkUnit(id: number): boolean {
+    if (!id || id <= 0 || !Number.isInteger(id)) {
+      throw new ValidationError('A valid positive integer ID is required.');
+    }
+    return this.repo.delete(id);
+  }
+
+  /**
+   * Retrieves recent WorkUnits.
+   */
+  getRecentWorkUnits(limit?: number): WorkUnit[] {
+    return this.repo.findRecent(limit);
+  }
+
+  /**
+   * Retrieves WorkUnits filtered by Status.
+   */
+  getWorkUnitsByStatus(status: WorkUnitStatus): WorkUnit[] {
+    return this.repo.findByStatus(status);
+  }
+
+  /**
+   * Retrieves WorkUnits filtered by Type.
+   */
+  getWorkUnitsByType(type: WorkUnitType): WorkUnit[] {
+    return this.repo.findByType(type);
+  }
+
+  /**
+   * Retrieves all unfinished Work Units (Planned, In Progress, Blocked) sorted by updatedAt descending.
+   */
+  getUnfinishedWorkUnits(): WorkUnit[] {
+    return this.repo.findUnfinished();
+  }
+
+  /**
+   * Retrieves Work Units created or updated since an ISO timestamp.
+   */
+  getCreatedOrUpdatedAfter(isoString: string): WorkUnit[] {
+    return this.repo.findCreatedOrUpdatedAfter(isoString);
+  }
+
+  /**
+   * Retrieves SQLite aggregated statistics.
+   */
+  getStats(sinceIsoString: string): WorkUnitStats {
+    return this.repo.getStats(sinceIsoString);
+  }
+
+  /**
+   * Searches WorkUnits by text query and structured filters.
+   */
+  searchWorkUnits(query: string, filters: SearchFilters = {}): WorkUnit[] {
+    return this.repo.search(query, filters);
+  }
+}

package/src/tests/cli/__snapshots__/cli-productivity.test.ts.snap

@@ -0,0 +1,37 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`WorkLog CLI Productivity Commands > should display dashboard (snapshot) 1`] = `
+"=== WORKLOG DASHBOARD ===
+
+CURRENTLY IN PROGRESS:
+  #2 Tags task
+
+NEEDS ATTENTION:
+  #1 [Planned] Unicode test ☕ 汉字
+
+RECENTLY UPDATED:
+  #2 [[DATE], [TIME]] Tags task (In Progress)
+  #1 [[DATE], [TIME]] Unicode test ☕ 汉字 (Planned)
+"
+`;
+
+exports[`WorkLog CLI Productivity Commands > should display stats summary (snapshot) 1`] = `
+"=== ENGINEERING INSIGHTS ===
+
+Total Work Units: 2
+
+STATUS DISTRIBUTION:
+  Planned         : 1
+  In Progress     : 1
+
+TYPE DISTRIBUTION:
+  Idea            : 1
+  Bug             : 1
+
+MODULE DISTRIBUTION:
+  No modules tracked.
+
+ACTIVITY IN THE PAST 7 DAYS:
+  [DATE] : ** (2)
+"
+`;

package/src/tests/cli/__snapshots__/cli.test.ts.snap

@@ -0,0 +1,20 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`WorkLog CLI Integration > should list work units in a beautiful table format (snapshot) 1`] = `
+"ID   Title         Type      Status        Module   Priority   Created At  
+#2   Second Task   Bug       In Progress   -        -          [DATE]      
+#1   First Task    Feature   Planned       auth     -          [DATE]      
+"
+`;
+
+exports[`WorkLog CLI Integration > should show card details for a specific unit (snapshot) 1`] = `
+"[#1] First Task
+--------------------------------------------------
+Type:      Feature
+Status:    Planned
+Module:    auth
+Tags:      login, security
+Created:   [DATE]
+Updated:   [DATE]
+"
+`;