@vanshbhardwaj/worklog 1.0.0

package/src/core/discovery.ts

@@ -0,0 +1,38 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { NotInitializedError } from '../errors/index.js';
+
+/**
+ * Searches upward from the starting directory to find the `.worklog` directory.
+ * Returns the absolute path of the directory containing `.worklog`.
+ * Returns null if not found.
+ */
+export function findWorkspaceRoot(startDir: string = process.cwd()): string | null {
+  let current = path.resolve(startDir);
+  const rootPath = path.parse(current).root;
+
+  while (true) {
+    const candidate = path.join(current, '.worklog');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return current;
+    }
+
+    if (current === rootPath) {
+      break;
+    }
+    current = path.dirname(current);
+  }
+
+  return null;
+}
+
+/**
+ * Finds the workspace root or throws a NotInitializedError.
+ */
+export function getWorkspaceRoot(startDir: string = process.cwd()): string {
+  const root = findWorkspaceRoot(startDir);
+  if (!root) {
+    throw new NotInitializedError();
+  }
+  return root;
+}

package/src/core/logger.ts

@@ -0,0 +1,53 @@
+import pino from 'pino';
+import * as path from 'path';
+import * as fs from 'fs';
+
+let loggerInstance: pino.Logger | null = null;
+
+/**
+ * Returns the current logger instance or a silent fallback if not initialized.
+ */
+export function getLogger(): pino.Logger {
+  if (loggerInstance) {
+    return loggerInstance;
+  }
+
+  // Silent fallback before repository discovery
+  loggerInstance = pino({
+    level: 'silent',
+  });
+  return loggerInstance;
+}
+
+/**
+ * Initializes the logger to write to the `.worklog/worklog.log` file in the workspace.
+ */
+export function initLogger(workspaceRoot: string): pino.Logger {
+  const logDir = path.join(workspaceRoot, '.worklog');
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  const logFile = path.join(logDir, 'worklog.log');
+
+  loggerInstance = pino(
+    {
+      level: process.env.WORKLOG_LOG_LEVEL || 'info',
+      base: undefined, // remove pid/hostname for clean local logs
+      timestamp: () => `,"time":"${new Date().toISOString()}"`,
+    },
+    pino.destination({
+      dest: logFile,
+      sync: true, // synchronous write to guarantee flush before CLI exit
+    }),
+  );
+
+  return loggerInstance;
+}
+
+export const logger = {
+  info: (obj: any, msg?: string, ...args: any[]) => getLogger().info(obj, msg, ...args),
+  error: (obj: any, msg?: string, ...args: any[]) => getLogger().error(obj, msg, ...args),
+  debug: (obj: any, msg?: string, ...args: any[]) => getLogger().debug(obj, msg, ...args),
+  warn: (obj: any, msg?: string, ...args: any[]) => getLogger().warn(obj, msg, ...args),
+};

package/src/database/connection.ts

@@ -0,0 +1,95 @@
+import { createRequire } from 'module';
+import * as path from 'path';
+import * as fs from 'fs';
+import { DatabaseError } from '../errors/index.js';
+import { logger } from '../core/logger.js';
+import type DatabaseType from 'better-sqlite3';
+
+// Construct dynamic disk require to bypass Node SEA embedded require constraints
+let DatabaseConstructor: any;
+try {
+  const contextPath =
+    typeof import.meta !== 'undefined' && import.meta.url
+      ? import.meta.url
+      : typeof __filename !== 'undefined'
+        ? __filename
+        : process.cwd() + '/package.json';
+
+  const requireFromDisk = createRequire(contextPath);
+  DatabaseConstructor = requireFromDisk('better-sqlite3');
+} catch {
+  try {
+    // Fallback: resolve from the current working directory
+    const requireFromDisk = createRequire(process.cwd() + '/package.json');
+    DatabaseConstructor = requireFromDisk('better-sqlite3');
+  } catch {
+    // Fallback: resolve from the directory of the executable
+    const execDir = path.dirname(process.execPath);
+    const requireFromDisk = createRequire(execDir + '/package.json');
+    DatabaseConstructor = requireFromDisk('better-sqlite3');
+  }
+}
+
+let dbInstance: DatabaseType.Database | null = null;
+
+/**
+ * Connects to the SQLite database located at `<workspaceRoot>/.worklog/worklog.db`.
+ * Optimizes SQLite performance parameters for local CLI use.
+ */
+export function connectDatabase(workspaceRoot: string): DatabaseType.Database {
+  if (dbInstance) {
+    return dbInstance;
+  }
+
+  const dbDir = path.join(workspaceRoot, '.worklog');
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+
+  const dbPath = path.join(dbDir, 'worklog.db');
+
+  try {
+    const db = new DatabaseConstructor(dbPath);
+
+    // Performance optimizations for local development CLI
+    db.pragma('foreign_keys = ON');
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('temp_store = MEMORY');
+
+    dbInstance = db;
+    logger.debug({ dbPath }, 'Connected to SQLite database successfully');
+    return db;
+  } catch (error: any) {
+    logger.error({ error, dbPath }, 'Failed to connect to SQLite database');
+    throw new DatabaseError('Failed to connect to database', error.message);
+  }
+}
+
+/**
+ * Returns the currently active database instance.
+ * Throws if the database has not been initialized.
+ */
+export function getDatabase(): DatabaseType.Database {
+  const db = dbInstance;
+  if (!db) {
+    throw new DatabaseError('Database is not initialized. Call connectDatabase first.');
+  }
+  return db;
+}
+
+/**
+ * Closes the database connection cleanly.
+ */
+export function closeDatabase(): void {
+  if (dbInstance) {
+    try {
+      dbInstance.close();
+      logger.debug('Database connection closed');
+    } catch (error: any) {
+      logger.error({ error }, 'Error closing database connection');
+    } finally {
+      dbInstance = null;
+    }
+  }
+}

package/src/database/migration-data.ts

@@ -0,0 +1,71 @@
+export const MIGRATIONS: Record<string, string> = {
+  '001_initial.sql': `
+CREATE TABLE IF NOT EXISTS work_units (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  priority TEXT,
+  module TEXT,
+  description TEXT,
+  next_step TEXT,
+  decision TEXT,
+  blocker TEXT,
+  notes TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- Full Text Search Index Table
+CREATE VIRTUAL TABLE IF NOT EXISTS work_units_fts USING fts5(
+  title,
+  description,
+  decision,
+  blocker,
+  notes,
+  content=work_units,
+  content_rowid=id
+);
+
+-- Auto-sync Insert Trigger
+CREATE TRIGGER IF NOT EXISTS work_units_ai AFTER INSERT ON work_units BEGIN
+  INSERT INTO work_units_fts(rowid, title, description, decision, blocker, notes)
+  VALUES (new.id, new.title, new.description, new.decision, new.blocker, new.notes);
+END;
+
+-- Auto-sync Delete Trigger
+CREATE TRIGGER IF NOT EXISTS work_units_ad AFTER DELETE ON work_units BEGIN
+  INSERT INTO work_units_fts(work_units_fts, rowid, title, description, decision, blocker, notes)
+  VALUES('delete', old.id, old.title, old.description, old.decision, old.blocker, old.notes);
+END;
+
+-- Auto-sync Update Trigger
+CREATE TRIGGER IF NOT EXISTS work_units_au AFTER UPDATE ON work_units BEGIN
+  INSERT INTO work_units_fts(work_units_fts, rowid, title, description, decision, blocker, notes)
+  VALUES('delete', old.id, old.title, old.description, old.decision, old.blocker, old.notes);
+  INSERT INTO work_units_fts(rowid, title, description, decision, blocker, notes)
+  VALUES (new.id, new.title, new.description, new.decision, new.blocker, new.notes);
+END;
+  `,
+  '002_relational_tables.sql': `
+-- Junction table for tags
+CREATE TABLE IF NOT EXISTS work_unit_tags (
+  work_unit_id INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  PRIMARY KEY (work_unit_id, tag),
+  FOREIGN KEY (work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE
+);
+
+-- Index for tag filtering performance
+CREATE INDEX IF NOT EXISTS idx_work_unit_tags_tag ON work_unit_tags(tag);
+
+-- Junction table for bidirectional relation mapping
+CREATE TABLE IF NOT EXISTS work_unit_relations (
+  work_unit_id INTEGER NOT NULL,
+  related_work_unit_id INTEGER NOT NULL,
+  PRIMARY KEY (work_unit_id, related_work_unit_id),
+  FOREIGN KEY (work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE,
+  FOREIGN KEY (related_work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE
+);
+  `,
+};

package/src/database/migrations/001_initial.sql

@@ -0,0 +1,60 @@
+-- Table to track database migrations
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version TEXT PRIMARY KEY,
+    applied_at TEXT NOT NULL
+);
+
+-- Core work_units table
+CREATE TABLE IF NOT EXISTS work_units (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    type TEXT NOT NULL,
+    status TEXT NOT NULL,
+    priority TEXT,
+    module TEXT,
+    description TEXT,
+    next_step TEXT,
+    decision TEXT,
+    blocker TEXT,
+    tags TEXT, -- JSON array of strings
+    related_work_units TEXT, -- JSON array of integers
+    notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+-- Performance indexes for status, type, and dates
+CREATE INDEX IF NOT EXISTS idx_work_units_status ON work_units(status);
+CREATE INDEX IF NOT EXISTS idx_work_units_type ON work_units(type);
+CREATE INDEX IF NOT EXISTS idx_work_units_created_at ON work_units(created_at);
+
+-- SQLite FTS5 Search Index Table using work_units as external content
+CREATE VIRTUAL TABLE IF NOT EXISTS work_units_fts USING fts5(
+    title,
+    description,
+    decision,
+    blocker,
+    notes,
+    content='work_units',
+    content_rowid='id'
+);
+
+-- Trigger to sync insert events to FTS
+CREATE TRIGGER IF NOT EXISTS work_units_ai AFTER INSERT ON work_units BEGIN
+    INSERT INTO work_units_fts(rowid, title, description, decision, blocker, notes)
+    VALUES (new.id, new.title, new.description, new.decision, new.blocker, new.notes);
+END;
+
+-- Trigger to sync delete events to FTS
+CREATE TRIGGER IF NOT EXISTS work_units_ad AFTER DELETE ON work_units BEGIN
+    INSERT INTO work_units_fts(work_units_fts, rowid, title, description, decision, blocker, notes)
+    VALUES('delete', old.id, old.title, old.description, old.decision, old.blocker, old.notes);
+END;
+
+-- Trigger to sync update events to FTS
+CREATE TRIGGER IF NOT EXISTS work_units_au AFTER UPDATE ON work_units BEGIN
+    INSERT INTO work_units_fts(work_units_fts, rowid, title, description, decision, blocker, notes)
+    VALUES('delete', old.id, old.title, old.description, old.decision, old.blocker, old.notes);
+    INSERT INTO work_units_fts(rowid, title, description, decision, blocker, notes)
+    VALUES (new.id, new.title, new.description, new.decision, new.blocker, new.notes);
+END;

package/src/database/migrations/002_relational_tables.sql

@@ -0,0 +1,22 @@
+-- Create work_unit_tags table for indexing and querying tags
+CREATE TABLE IF NOT EXISTS work_unit_tags (
+    work_unit_id INTEGER NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (work_unit_id, tag),
+    FOREIGN KEY (work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_work_unit_tags_tag ON work_unit_tags(tag);
+
+-- Create work_unit_relations table for modeling links between work units
+CREATE TABLE IF NOT EXISTS work_unit_relations (
+    work_unit_id INTEGER NOT NULL,
+    related_work_unit_id INTEGER NOT NULL,
+    PRIMARY KEY (work_unit_id, related_work_unit_id),
+    FOREIGN KEY (work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE,
+    FOREIGN KEY (related_work_unit_id) REFERENCES work_units(id) ON DELETE CASCADE
+);
+
+-- Drop unused JSON columns from the main work_units table
+ALTER TABLE work_units DROP COLUMN tags;
+ALTER TABLE work_units DROP COLUMN related_work_units;

package/src/database/migrations.ts

@@ -0,0 +1,65 @@
+import Database from 'better-sqlite3';
+import { logger } from '../core/logger.js';
+import { DatabaseError } from '../errors/index.js';
+import { MIGRATIONS } from './migration-data.js';
+
+/**
+ * Runs all pending migrations sequentially within a database transaction.
+ */
+export function runMigrations(db: Database.Database): void {
+  logger.debug('Starting database migrations run');
+
+  // Step 1: Ensure the schema_migrations table exists
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL
+    );
+  `);
+
+  // Step 2: Get sorted migration keys
+  const files = Object.keys(MIGRATIONS).sort();
+
+  if (files.length === 0) {
+    logger.debug('No migration definitions found');
+    return;
+  }
+
+  // Step 3: Get already applied migrations
+  const stmt = db.prepare('SELECT version FROM schema_migrations');
+  const applied: string[] = stmt.all().map((row: any) => row.version);
+
+  // Step 4: Apply outstanding migrations in order
+  for (const file of files) {
+    if (applied.includes(file)) {
+      logger.debug({ migration: file }, 'Migration already applied, skipping');
+      continue;
+    }
+
+    logger.info({ migration: file }, `Applying database migration: ${file}`);
+    const sql = MIGRATIONS[file];
+
+    // Run migrations inside a transaction
+    const runMigrationTx = db.transaction(() => {
+      db.exec(sql);
+      const insertStmt = db.prepare(
+        'INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)',
+      );
+      insertStmt.run(file, new Date().toISOString());
+    });
+
+    try {
+      runMigrationTx();
+      logger.info({ migration: file }, `Migration ${file} applied successfully`);
+    } catch (error: any) {
+      logger.error({ error, migration: file }, `Failed to apply migration: ${file}`);
+      throw new DatabaseError(`Failed to apply migration ${file}`, error.message);
+    }
+  }
+
+  logger.debug('Database migrations completed');
+}
+export function getMigrationsDir(): string {
+  // Provided for backward compatibility in tests
+  return '';
+}

package/src/errors/index.ts

@@ -0,0 +1,51 @@
+export class WorkLogDomainError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly actionRequired?: string,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class NotInitializedError extends WorkLogDomainError {
+  constructor() {
+    super(
+      'Not a WorkLog repository (or any of the parent directories): .worklog',
+      'NOT_INITIALIZED',
+      "Run 'worklog init' or 'worklog a' to initialize a new repository.",
+    );
+  }
+}
+
+export class DatabaseError extends WorkLogDomainError {
+  constructor(message: string, details?: string) {
+    super(
+      `Database error: ${message}${details ? ` (${details})` : ''}`,
+      'DATABASE_ERROR',
+      'Please check your database integrity or log files.',
+    );
+  }
+}
+
+export class ValidationError extends WorkLogDomainError {
+  constructor(message: string) {
+    super(
+      `Validation error: ${message}`,
+      'VALIDATION_ERROR',
+      'Please provide valid inputs conforming to the schema.',
+    );
+  }
+}
+
+export class ConfigError extends WorkLogDomainError {
+  constructor(message: string) {
+    super(
+      `Configuration error: ${message}`,
+      'CONFIG_ERROR',
+      'Please check if .worklog/config.json is well-formed.',
+    );
+  }
+}

package/src/exporters/csv.ts

@@ -0,0 +1,59 @@
+import { WorkUnit } from '../models/work-unit.js';
+
+function escapeCSV(val: any): string {
+  if (val === null || val === undefined) return '';
+  const str = String(val);
+  if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+/**
+ * Converts WorkUnits to a standard CSV string.
+ */
+export function exportToCSV(units: WorkUnit | WorkUnit[]): string {
+  const list = Array.isArray(units) ? units : [units];
+  const headers = [
+    'ID',
+    'Title',
+    'Type',
+    'Status',
+    'Priority',
+    'Module',
+    'Description',
+    'Next Step',
+    'Decision',
+    'Blocker',
+    'Tags',
+    'Related Work Units',
+    'Notes',
+    'Created At',
+    'Updated At',
+  ];
+
+  const lines: string[] = [headers.join(',')];
+
+  for (const u of list) {
+    const row = [
+      u.id,
+      escapeCSV(u.title),
+      escapeCSV(u.type),
+      escapeCSV(u.status),
+      escapeCSV(u.priority),
+      escapeCSV(u.module),
+      escapeCSV(u.description),
+      escapeCSV(u.nextStep),
+      escapeCSV(u.decision),
+      escapeCSV(u.blocker),
+      escapeCSV(u.tags.join(';')),
+      escapeCSV(u.relatedWorkUnits.join(';')),
+      escapeCSV(u.notes),
+      escapeCSV(u.createdAt),
+      escapeCSV(u.updatedAt),
+    ];
+    lines.push(row.join(','));
+  }
+
+  return lines.join('\n') + '\n';
+}

package/src/exporters/json.ts

@@ -0,0 +1,8 @@
+import { WorkUnit } from '../models/work-unit.js';
+
+/**
+ * Converts WorkUnits to a formatted JSON string.
+ */
+export function exportToJSON(units: WorkUnit | WorkUnit[]): string {
+  return JSON.stringify(units, null, 2) + '\n';
+}

package/src/exporters/markdown.ts

@@ -0,0 +1,71 @@
+import { WorkUnit } from '../models/work-unit.js';
+
+function formatSingleMarkdown(u: WorkUnit): string {
+  const lines: string[] = [];
+  lines.push(`# [#${u.id}] ${u.title}\n`);
+  lines.push(`- **Type:** ${u.type}`);
+  lines.push(`- **Status:** ${u.status}`);
+  if (u.priority) lines.push(`- **Priority:** ${u.priority}`);
+  if (u.module) lines.push(`- **Module:** ${u.module}`);
+  if (u.tags && u.tags.length > 0) lines.push(`- **Tags:** ${u.tags.join(', ')}`);
+  lines.push(`- **Created:** ${u.createdAt}`);
+  lines.push(`- **Updated:** ${u.updatedAt}`);
+  lines.push('');
+
+  if (u.description) {
+    lines.push('## Description');
+    lines.push(u.description);
+    lines.push('');
+  }
+  if (u.nextStep) {
+    lines.push(`## Next Step\n-> ${u.nextStep}\n`);
+  }
+  if (u.decision) {
+    lines.push(`## Decision\n✔ ${u.decision}\n`);
+  }
+  if (u.blocker) {
+    lines.push(`## Blocker\n✖ ${u.blocker}\n`);
+  }
+  if (u.notes) {
+    lines.push('## Notes');
+    lines.push(u.notes);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Converts WorkUnits to a clean Markdown string.
+ */
+export function exportToMarkdown(units: WorkUnit | WorkUnit[]): string {
+  if (!units) return 'No work units found.\n';
+
+  if (!Array.isArray(units)) {
+    return formatSingleMarkdown(units);
+  }
+
+  if (units.length === 0) {
+    return 'No work units found.\n';
+  }
+
+  const lines: string[] = [];
+  lines.push('# WorkLog Export\n');
+
+  const statuses = ['In Progress', 'Blocked', 'Planned', 'Completed', 'Cancelled'] as const;
+  for (const status of statuses) {
+    const filtered = units.filter((u) => u.status === status);
+    if (filtered.length === 0) continue;
+
+    lines.push(`## ${status}`);
+    for (const u of filtered) {
+      const moduleStr = u.module ? ` [${u.module}]` : '';
+      lines.push(`- **#${u.id}**: ${u.title}${moduleStr} (${u.type})`);
+      if (u.nextStep) {
+        lines.push(`  - *Next step:* ${u.nextStep}`);
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/models/work-unit.ts

@@ -0,0 +1,38 @@
+export type WorkUnitType =
+  | 'Feature'
+  | 'Bug'
+  | 'Spike'
+  | 'Refactor'
+  | 'Improvement'
+  | 'Research'
+  | 'Decision'
+  | 'Blocker'
+  | 'Review'
+  | 'Idea';
+
+export type WorkUnitStatus =
+  | 'Planned'
+  | 'In Progress'
+  | 'Blocked'
+  | 'Completed'
+  | 'Cancelled';
+
+export type WorkUnitPriority = 'Low' | 'Medium' | 'High';
+
+export interface WorkUnit {
+  id: number;
+  title: string;
+  type: WorkUnitType;
+  status: WorkUnitStatus;
+  priority: WorkUnitPriority | null;
+  module: string | null;
+  description: string | null;
+  nextStep: string | null;
+  decision: string | null;
+  blocker: string | null;
+  tags: string[];
+  relatedWorkUnits: number[];
+  notes: string | null;
+  createdAt: string;
+  updatedAt: string;
+}