@vanshbhardwaj/worklog 1.0.0

package/src/cli/index.ts

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { getWorkspaceRoot } from '../core/discovery.js';
+import { initLogger, logger } from '../core/logger.js';
+import { connectDatabase, closeDatabase } from '../database/connection.js';
+import { runMigrations } from '../database/migrations.js';
+import { WorkUnitRepository } from '../repositories/work-unit.js';
+import { WorkUnitService } from '../services/work-unit.js';
+import { initCommand } from './commands/init.js';
+import { addCommand } from './commands/add.js';
+import { listCommand } from './commands/list.js';
+import { showCommand } from './commands/show.js';
+import { searchCommand } from './commands/search.js';
+import { todayCommand } from './commands/today.js';
+import { weekCommand } from './commands/week.js';
+import { dashboardCommand } from './commands/dashboard.js';
+import { continueCommand } from './commands/continue.js';
+import { statsCommand } from './commands/stats.js';
+import { exportCommand } from './commands/export.js';
+import { WorkLogDomainError } from '../errors/index.js';
+
+const program = new Command();
+
+program
+  .name('worklog')
+  .description('WorkLog - Engineering Context Manager')
+  .version('0.1.0')
+  .option('--verbose', 'enable verbose debug logging')
+  .option('--json', 'output in machine-readable JSON format');
+
+// Helper to bootstrap database & service
+function bootstrap(): WorkUnitService {
+  const root = getWorkspaceRoot();
+  initLogger(root);
+  const db = connectDatabase(root);
+  runMigrations(db);
+  const repo = new WorkUnitRepository(db);
+  return new WorkUnitService(repo);
+}
+
+// Global error handler
+function handleError(error: any) {
+  const isVerbose = program.opts().verbose;
+  const isJson = program.opts().json;
+
+  // Database errors represent unexpected system errors rather than user input issues, so they exit with 2
+  const isUserError = error instanceof WorkLogDomainError && error.code !== 'DATABASE_ERROR';
+
+  if (isUserError) {
+    logger.error({ error, code: error.code }, 'Domain error occurred');
+    if (isJson) {
+      console.error(JSON.stringify({ success: false, code: error.code, error: error.message }));
+    } else {
+      console.error(pc.red(`Error: ${error.message}`));
+      if (error.actionRequired) {
+        console.error(pc.yellow(`Action required: ${error.actionRequired}`));
+      }
+    }
+    process.exit(1);
+  } else {
+    logger.error({ error }, 'Unexpected system error');
+    if (isJson) {
+      console.error(
+        JSON.stringify({ success: false, code: 'INTERNAL_ERROR', error: error.message }),
+      );
+    } else {
+      console.error(pc.red(`Unexpected Error: ${error.message}`));
+      if (isVerbose) {
+        console.error(pc.gray(error.stack || ''));
+      } else {
+        console.error(pc.yellow('Run with --verbose to view stack traces.'));
+      }
+    }
+    process.exit(2);
+  }
+}
+
+// Commands definition
+program
+  .command('init')
+  .alias('i')
+  .description('Initialize a new WorkLog repository')
+  .option('--name <name>', 'override default project name')
+  .action((options) => {
+    try {
+      const json = program.opts().json || options.json;
+      initCommand({ ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    }
+  });
+
+program
+  .command('add')
+  .alias('a')
+  .description('Create a new Work Unit')
+  .option('-t, --title <title>', 'title of the work unit')
+  .option(
+    '--type <type>',
+    'type of the work unit (Feature, Bug, Spike, Refactor, Improvement, Research, Decision, Blocker, Review, Idea)',
+  )
+  .option(
+    '--status <status>',
+    'status of the work unit (Planned, In Progress, Blocked, Completed, Cancelled)',
+  )
+  .option('--priority <priority>', 'priority of the work unit (Low, Medium, High)')
+  .option('--module <module>', 'associated component or code module')
+  .option('--tags <tags>', 'comma-separated tags list')
+  .option('-d, --description <desc>', 'detailed description')
+  .option('-n, --next <next>', 'next step/action')
+  .option('--notes <notes>', 'implementation notes')
+  .action(async (options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      await addCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('list')
+  .alias('ls')
+  .description('List recent Work Units')
+  .option('-l, --limit <limit>', 'limit output count', '20')
+  .option('-s, --status <status>', 'filter by status')
+  .option('-t, --type <type>', 'filter by type')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      listCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('show <id>')
+  .alias('sh')
+  .description('Show details for a specific Work Unit')
+  .action((id, options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      showCommand(service, id, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('search [query]')
+  .alias('s')
+  .description('Search Work Units by keyword and category filters')
+  .option('--tag <tag>', 'filter search results by tag')
+  .option('--module <module>', 'filter search results by module')
+  .option('--status <status>', 'filter search results by status')
+  .option('--type <type>', 'filter search results by type')
+  .action((query, options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      searchCommand(service, query, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('today')
+  .alias('t')
+  .description('Show work units updated today')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      todayCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('week')
+  .alias('w')
+  .description('Show weekly engineering summary')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      weekCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('dashboard')
+  .alias('db')
+  .description('Show clean project dashboard overview')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      dashboardCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('continue')
+  .alias('co')
+  .description('Resume work on the most recent unfinished task')
+  .action(async (options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      await continueCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('stats')
+  .alias('st')
+  .description('Show total stats and category distributions')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      const json = program.opts().json || options.json;
+      statsCommand(service, { ...options, json });
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+program
+  .command('export')
+  .alias('ex')
+  .description('Export Work Units to Markdown, CSV, or JSON')
+  .option('-f, --format <format>', 'export format (markdown, csv, json)', 'markdown')
+  .option('-o, --output <file>', 'write output directly to a file')
+  .option('--id <id>', 'export a single work unit by its ID')
+  .action((options) => {
+    try {
+      const service = bootstrap();
+      exportCommand(service, options);
+    } catch (error: any) {
+      handleError(error);
+    } finally {
+      closeDatabase();
+    }
+  });
+
+// Handle invalid / unknown command routing
+program.on('command:*', () => {
+  const isJson = program.opts().json;
+  const command = program.args.join(' ');
+
+  if (isJson) {
+    console.error(
+      JSON.stringify({ success: false, code: 'UNKNOWN_COMMAND', error: `Unknown command: ${command}` }),
+    );
+  } else {
+    console.error(pc.red(`Error: Unknown command: ${command}`));
+    console.error(`Run 'worklog --help' for a list of available commands.`);
+  }
+  process.exit(1);
+});
+
+program.parse(process.argv);

package/src/cli/ui.ts

@@ -0,0 +1,323 @@
+import pc from 'picocolors';
+import Table from 'cli-table3';
+import { WorkUnit, WorkUnitStatus, WorkUnitType, WorkUnitPriority } from '../models/work-unit.js';
+import { WorkUnitStats } from '../repositories/work-unit.js';
+
+/**
+ * Returns the width of the terminal, defaulting to 80 columns.
+ */
+export function getTerminalWidth(): number {
+  return process.stdout.columns || 80;
+}
+
+/**
+ * Truncates text and removes newlines, appending an ellipsis if exceeded.
+ */
+export function truncateText(text: string | null | undefined, maxLength: number): string {
+  if (!text) return '';
+  const clean = text.replace(/\r?\n|\r/g, ' ').trim();
+  if (clean.length <= maxLength) return clean;
+  return clean.substring(0, maxLength - 3) + '...';
+}
+
+/**
+ * Maps a WorkUnitStatus to a colored terminal string.
+ */
+export function colorStatus(status: WorkUnitStatus): string {
+  switch (status) {
+    case 'Planned':
+      return pc.gray('Planned');
+    case 'In Progress':
+      return pc.blue('In Progress');
+    case 'Blocked':
+      return pc.red('Blocked');
+    case 'Completed':
+      return pc.green('Completed');
+    case 'Cancelled':
+      return pc.strikethrough(pc.gray('Cancelled'));
+    default:
+      return status;
+  }
+}
+
+/**
+ * Maps a WorkUnitType to a colored terminal string.
+ */
+export function colorType(type: WorkUnitType): string {
+  switch (type) {
+    case 'Feature':
+      return pc.cyan('Feature');
+    case 'Bug':
+      return pc.red('Bug');
+    case 'Spike':
+      return pc.magenta('Spike');
+    case 'Refactor':
+      return pc.yellow('Refactor');
+    case 'Improvement':
+      return pc.green('Improvement');
+    case 'Research':
+      return pc.blue('Research');
+    case 'Decision':
+      return pc.cyan(pc.bold('Decision'));
+    case 'Blocker':
+      return pc.bgRed(pc.white('Blocker'));
+    case 'Review':
+      return pc.yellow('Review');
+    case 'Idea':
+      return pc.gray('Idea');
+    default:
+      return type;
+  }
+}
+
+/**
+ * Maps a WorkUnitPriority to a colored terminal string.
+ */
+export function colorPriority(priority: WorkUnitPriority | null): string {
+  if (!priority) return pc.gray('-');
+  switch (priority) {
+    case 'High':
+      return pc.red('High');
+    case 'Medium':
+      return pc.yellow('Medium');
+    case 'Low':
+      return pc.green('Low');
+    default:
+      return priority;
+  }
+}
+
+/**
+ * Formats a list of work units as a minimal, git-like text table.
+ */
+export function formatTable(workUnits: WorkUnit[]): string {
+  if (workUnits.length === 0) {
+    return 'No work units found.';
+  }
+
+  const table = new Table({
+    head: [
+      pc.bold('ID'),
+      pc.bold('Title'),
+      pc.bold('Type'),
+      pc.bold('Status'),
+      pc.bold('Module'),
+      pc.bold('Priority'),
+      pc.bold('Created At'),
+    ],
+    chars: {
+      top: '',
+      'top-mid': '',
+      'top-left': '',
+      'top-right': '',
+      bottom: '',
+      'bottom-mid': '',
+      'bottom-left': '',
+      'bottom-right': '',
+      left: '',
+      'left-mid': '',
+      mid: '',
+      'mid-mid': '',
+      right: '',
+      'right-mid': '',
+      middle: ' ',
+    },
+    style: { 'padding-left': 0, 'padding-right': 2, head: [] },
+  });
+
+  const width = getTerminalWidth();
+  // Reserve width for: ID(5) Type(14) Status(14) Module(12) Priority(10) Date(8) + spacing(12) = 75
+  const titleMaxWidth = Math.max(20, width - 75);
+
+  for (const unit of workUnits) {
+    const formattedDate = new Date(unit.createdAt).toLocaleDateString(undefined, {
+      month: 'short',
+      day: 'numeric',
+    });
+
+    table.push([
+      pc.gray(`#${unit.id}`),
+      truncateText(unit.title, titleMaxWidth),
+      colorType(unit.type),
+      colorStatus(unit.status),
+      unit.module ? pc.yellow(unit.module) : pc.gray('-'),
+      colorPriority(unit.priority),
+      pc.gray(formattedDate),
+    ]);
+  }
+
+  return table.toString();
+}
+
+/**
+ * Formats a single WorkUnit as a detail card.
+ */
+export function formatWorkUnitDetail(unit: WorkUnit): string {
+  const lines: string[] = [];
+
+  lines.push(`${pc.bold(pc.cyan(`[#${unit.id}] ${unit.title}`))}`);
+  lines.push(`${pc.gray('--------------------------------------------------')}`);
+  lines.push(`${pc.bold('Type:')}      ${colorType(unit.type)}`);
+  lines.push(`${pc.bold('Status:')}    ${colorStatus(unit.status)}`);
+
+  if (unit.priority) {
+    lines.push(`${pc.bold('Priority:')}  ${colorPriority(unit.priority)}`);
+  }
+  if (unit.module) {
+    lines.push(`${pc.bold('Module:')}    ${pc.yellow(unit.module)}`);
+  }
+
+  if (unit.tags && unit.tags.length > 0) {
+    lines.push(`${pc.bold('Tags:')}      ${unit.tags.map((t) => pc.blue(t)).join(', ')}`);
+  }
+
+  if (unit.relatedWorkUnits && unit.relatedWorkUnits.length > 0) {
+    lines.push(
+      `${pc.bold('Related:')}   ${unit.relatedWorkUnits.map((id) => pc.gray(`#${id}`)).join(', ')}`,
+    );
+  }
+
+  lines.push(`${pc.bold('Created:')}   ${new Date(unit.createdAt).toLocaleString()}`);
+  lines.push(`${pc.bold('Updated:')}   ${new Date(unit.updatedAt).toLocaleString()}`);
+
+  if (unit.description) {
+    lines.push('');
+    lines.push(`${pc.bold('Description:')}`);
+    lines.push(unit.description);
+  }
+
+  if (unit.nextStep) {
+    lines.push('');
+    lines.push(`${pc.bold('Next Step:')}`);
+    lines.push(pc.blue(`-> ${unit.nextStep}`));
+  }
+
+  if (unit.decision) {
+    lines.push('');
+    lines.push(`${pc.bold('Decision:')}`);
+    lines.push(pc.green(`✔ ${unit.decision}`));
+  }
+
+  if (unit.blocker) {
+    lines.push('');
+    lines.push(`${pc.bold('Blocker:')}`);
+    lines.push(pc.red(`✖ ${unit.blocker}`));
+  }
+
+  if (unit.notes) {
+    lines.push('');
+    lines.push(`${pc.bold('Notes:')}`);
+    lines.push(unit.notes);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats a dashboard overview screen showing current tasks, blocked work, and recent updates.
+ */
+export function formatDashboard(
+  inProgress: WorkUnit[],
+  recentlyUpdated: WorkUnit[],
+  needsAttention: WorkUnit[],
+): string {
+  const lines: string[] = [];
+
+  lines.push(pc.bold(pc.cyan('=== WORKLOG DASHBOARD ===\n')));
+
+  lines.push(pc.bold('CURRENTLY IN PROGRESS:'));
+  if (inProgress.length === 0) {
+    lines.push(pc.gray('  (No tasks currently in progress)'));
+  } else {
+    for (const u of inProgress) {
+      lines.push(
+        `  ${pc.gray(`#${u.id}`)} ${pc.bold(u.title)}${u.module ? ` [${u.module}]` : ''}`,
+      );
+      if (u.nextStep) {
+        lines.push(`    ${pc.blue('->')} ${pc.gray(u.nextStep)}`);
+      }
+    }
+  }
+  lines.push('');
+
+  lines.push(pc.bold('NEEDS ATTENTION:'));
+  if (needsAttention.length === 0) {
+    lines.push(pc.gray('  (No blocked or planned tasks requiring attention)'));
+  } else {
+    for (const u of needsAttention) {
+      const reason =
+        u.status === 'Blocked'
+          ? pc.red(`[Blocked: ${u.blocker || 'Unknown'}]`)
+          : pc.yellow('[Planned]');
+      lines.push(`  ${pc.gray(`#${u.id}`)} ${reason} ${u.title}`);
+    }
+  }
+  lines.push('');
+
+  lines.push(pc.bold('RECENTLY UPDATED:'));
+  if (recentlyUpdated.length === 0) {
+    lines.push(pc.gray('  (No recent updates)'));
+  } else {
+    for (const u of recentlyUpdated) {
+      const date = new Date(u.updatedAt).toLocaleDateString(undefined, {
+        month: 'short',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+      });
+      lines.push(
+        `  ${pc.gray(`#${u.id}`)} ${pc.gray(`[${date}]`)} ${u.title} (${colorStatus(u.status)})`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats statistics insights screen using clean text bars.
+ */
+export function formatStats(stats: WorkUnitStats): string {
+  const lines: string[] = [];
+
+  lines.push(pc.bold(pc.cyan('=== ENGINEERING INSIGHTS ===\n')));
+  lines.push(`${pc.bold('Total Work Units:')} ${stats.totalCount}\n`);
+
+  // 1. Status Distribution
+  lines.push(pc.bold('STATUS DISTRIBUTION:'));
+  for (const item of stats.statusDistribution) {
+    lines.push(`  ${item.status.padEnd(15)} : ${item.count}`);
+  }
+  lines.push('');
+
+  // 2. Type Distribution
+  lines.push(pc.bold('TYPE DISTRIBUTION:'));
+  for (const item of stats.typeDistribution) {
+    lines.push(`  ${item.type.padEnd(15)} : ${item.count}`);
+  }
+  lines.push('');
+
+  // 3. Module Distribution
+  lines.push(pc.bold('MODULE DISTRIBUTION:'));
+  if (stats.moduleDistribution.length === 0) {
+    lines.push('  No modules tracked.');
+  } else {
+    for (const item of stats.moduleDistribution) {
+      lines.push(`  ${item.module.padEnd(15)} : ${item.count}`);
+    }
+  }
+  lines.push('');
+
+  // 4. Daily Activity over past 7 days
+  lines.push(pc.bold('ACTIVITY IN THE PAST 7 DAYS:'));
+  if (stats.dailyActivity.length === 0) {
+    lines.push('  No work logged in the past 7 days.');
+  } else {
+    for (const item of stats.dailyActivity) {
+      const bar = '*'.repeat(item.count);
+      lines.push(`  ${item.day} : ${bar} (${item.count})`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/core/config.ts

@@ -0,0 +1,69 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { ConfigError } from '../errors/index.js';
+
+export const ConfigSchema = z.object({
+  projectName: z.string(),
+  createdAt: z.string(),
+  schemaVersion: z.number().default(1),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+const DEFAULT_CONFIG_FILENAME = 'config.json';
+
+/**
+ * Loads and validates the configuration file from a workspace root.
+ */
+export function loadConfig(workspaceRoot: string): Config {
+  const configPath = path.join(workspaceRoot, '.worklog', DEFAULT_CONFIG_FILENAME);
+  if (!fs.existsSync(configPath)) {
+    throw new ConfigError(`Config file not found at ${configPath}.`);
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return ConfigSchema.parse(parsed);
+  } catch (error: any) {
+    if (error instanceof z.ZodError) {
+      throw new ConfigError(
+        `Invalid config format: ${error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+      );
+    }
+    throw new ConfigError(`Failed to read config file: ${error.message}`);
+  }
+}
+
+/**
+ * Saves and validates a configuration object to a workspace root.
+ */
+export function saveConfig(workspaceRoot: string, config: Config): void {
+  const dotWorklog = path.join(workspaceRoot, '.worklog');
+  if (!fs.existsSync(dotWorklog)) {
+    fs.mkdirSync(dotWorklog, { recursive: true });
+  }
+
+  const configPath = path.join(dotWorklog, DEFAULT_CONFIG_FILENAME);
+  try {
+    const validated = ConfigSchema.parse(config);
+    fs.writeFileSync(configPath, JSON.stringify(validated, null, 2), 'utf8');
+  } catch (error: any) {
+    throw new ConfigError(`Failed to save config: ${error.message}`);
+  }
+}
+
+/**
+ * Initializes a new configuration object in the workspace root.
+ */
+export function initConfig(workspaceRoot: string, projectName?: string): Config {
+  const pName = projectName || path.basename(path.resolve(workspaceRoot));
+  const newConfig: Config = {
+    projectName: pName,
+    createdAt: new Date().toISOString(),
+    schemaVersion: 1,
+  };
+  saveConfig(workspaceRoot, newConfig);
+  return newConfig;
+}