@vanshbhardwaj/worklog 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+# WorkLog
+
+> **Engineering Context Manager** — *Git stores code. WorkLog stores engineering context.*
+
+---
+### Links:
+- 📖 [Architecture Design Manual](ARCHITECTURE.md)
+- 💾 [Advanced Installation Guide](INSTALLATION.md)
+---
+
+WorkLog is a local-first, offline-first command-line tool designed to capture the **why**, the **blockers**, the **decisions**, and the **meaningful progress** of your daily engineering work. It helps you keep track of what you are doing so you never have to ask yourself, *"What was I doing yesterday?"*
+
+---
+
+## Technical Stack
+
+- **Language:** TypeScript
+- **Runtime:** Node.js (v20+ recommended)
+- **CLI Framework:** Commander.js
+- **Database:** SQLite (via `better-sqlite3` native drivers)
+- **Validation:** Zod
+- **Logging:** Pino (saved to `.worklog/worklog.log`)
+
+---
+
+## Installation
+
+WorkLog is configured to install and run locally.
+
+1. Ensure you have **pnpm** and Node.js installed.
+2. Clone this repository.
+3. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+4. Build the application:
+   ```bash
+   pnpm build
+   ```
+5. Link the command globally (optional):
+   ```bash
+   pnpm link --global
+   ```
+
+Now you can invoke WorkLog with:
+```bash
+worklog --help
+```
+
+---
+
+## Core Philosophy
+
+- **Local Scope:** Every project initializes its own database in a `.worklog/` directory (just like `.git` in Git).
+- **Fast Interactive Prompts:** If you omit arguments, `worklog add` automatically prompts you through choices.
+- **Machine Readable:** Add the `--json` flag to print structured data for IDE plugins or scripts.
+- **Dedicated Exporters:** Supports Markdown, CSV, and JSON outputs for clean copy-pasting.
+
+---
+
+## CLI Usage & Reference
+
+### 1. Initialize a Project (`init` / `i`)
+Initializes a new context tracker in the current directory.
+
+```bash
+worklog init
+# or
+worklog i
+```
+
+**Output:**
+```
+Initialized empty WorkLog repository in /path/to/project/.worklog/
+```
+
+---
+
+### 2. Create a Work Unit (`add` / `a`)
+Create an entry representing a Feature, Bug, Refactor, Spike, Research, or Decision.
+
+**Non-Interactive Mode:**
+```bash
+worklog add --title "Setup authentication endpoint" --type Feature --status "In Progress" --module Auth --tags backend,security
+# or
+worklog a -t "Fix connection leak" --type Bug --status Completed
+```
+
+**Interactive Mode:**
+Simply run `worklog add` (or `worklog a`) without flags in a TTY terminal, and it will guide you:
+```
+? Title: › Setup auth
+? Type: › Feature
+? Status: › Planned
+? Description (optional): › Initial JWT setup
+? Module (optional): › auth
+? Tags (comma-separated, optional): › backend,security
+? Next Step (optional): › write unit tests
+```
+
+---
+
+### 3. List Work Units (`list` / `ls`)
+Lists recent entries.
+
+```bash
+worklog list
+# or
+worklog ls
+```
+
+**Output:**
+```
+ID   Title                      Type    Status      Module Priority Created At
+#2   Fix connection leak        Bug     Completed   -      -        Jul 26
+#1   Setup authentication...    Feature In Progress Auth   -        Jul 26
+```
+
+**Options:**
+- `-l, --limit <count>`: Limit output (default is 20).
+- `-s, --status <status>`: Filter list by status.
+- `-t, --type <type>`: Filter list by type.
+- `--json`: Output machine-readable JSON array.
+
+---
+
+### 4. Show Details (`show` / `sh`)
+Displays detailed card information for a single Work Unit.
+
+```bash
+worklog show 1
+# or
+worklog sh 1
+```
+
+---
+
+### 5. Multi-criteria Search (`search` / `s`)
+Perform case-insensitive text search querying the SQLite FTS5 virtual table, combined with category filters.
+
+```bash
+# Search text
+worklog search "connection leak"
+
+# Search by tags and module
+worklog search --tag backend --module auth
+
+# Combined keyword and status query
+worklog search "setup" --status "In Progress"
+```
+
+**Options:**
+- `--tag <tag>`: Filter results by tag.
+- `--module <module>`: Filter results by module.
+- `--status <status>`: Filter results by status.
+- `--type <type>`: Filter results by type.
+- `--json`: Return structured matches as JSON.
+
+---
+
+### 6. Today's Progress (`today` / `t`)
+Display work units created or updated today since midnight.
+
+```bash
+worklog today
+# or
+worklog t
+```
+
+---
+
+### 7. Weekly Summary (`week` / `w`)
+Provides a weekly summary of progress grouped by engineering categories (features completed, bugs fixed, decisions made, blockers encountered, research performed) and prints status/type distribution counts.
+
+```bash
+worklog week
+# or
+worklog w
+```
+
+---
+
+### 8. Project Dashboard (`dashboard` / `db`)
+Displays a focused overview answering three core developer questions:
+1. *What am I currently working on?* (In Progress items)
+2. *What needs attention?* (Blocked or Planned items)
+3. *What changed recently?* (Recently updated items)
+
+```bash
+worklog dashboard
+# or
+worklog db
+```
+
+---
+
+### 9. Resume Last Work (`continue` / `co`)
+Resumes the most recently touched unfinished task (Planned, In Progress, Blocked), shifting its status to `In Progress` and updating its time marker.
+If multiple unfinished units exist, it prompts you to select one (sorted by update date, most recent first).
+
+```bash
+worklog continue
+# or
+worklog co
+```
+
+---
+
+### 10. Analytical Insights (`stats` / `st`)
+Shows high-level metrics (totals, category distributions, and daily activity logs over the past 7 days) in clean text bars.
+
+```bash
+worklog stats
+# or
+worklog st
+```
+
+---
+
+### 11. Export Context (`export` / `ex`)
+Exports log entries to Markdown, CSV, or JSON. Supports writing directly to files or stdout piping.
+
+```bash
+# Export everything to markdown file
+worklog export --format markdown --output docs/summary.md
+
+# Pipe CSV data
+worklog export --format csv > data_export.csv
+
+# Export a single work unit
+worklog export --id 1 --format markdown
+```
+
+**Options:**
+- `-f, --format <format>`: Output format (`markdown` / `md`, `csv`, `json`). Defaults to `markdown`.
+- `-o, --output <file>`: Writes data to a physical file.
+- `--id <id>`: Exports only the unit matching this ID.
+
+---
+
+## Error Codes
+
+The CLI will exit with:
+- `0` on successful operation execution.
+- `1` on user/validation errors (e.g. invalid arguments, missing fields, not in a repository).
+- `2` on system/database failures (e.g. SQLite corruption, unhandled crashes).

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release of WorkLog is actively supported for security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| v0.1.x  | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please **do not** open a public issue. Instead, report it privately to the maintainers.
+
+Please send security disclosures and details of the vulnerability to:
+- **Email:** security@worklog.local (placeholder, replace with actual security contact)
+
+We will endeavor to respond to your report within 48 hours and outline a plan for remediation.

package/benchmarks/benchmark.ts

@@ -0,0 +1,149 @@
+import { describe, it } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { runMigrations } from '../src/database/migrations.js';
+import { WorkUnitRepository } from '../src/repositories/work-unit.js';
+import { WorkUnitService } from '../src/services/work-unit.js';
+import { exportToMarkdown } from '../src/exporters/markdown.js';
+import { exportToCSV } from '../src/exporters/csv.js';
+import { exportToJSON } from '../src/exporters/json.js';
+
+describe('WorkLog Performance Benchmark', () => {
+  const benchDir = path.join(process.cwd(), 'benchmarks', 'temp-bench-db');
+
+  it('should run performance metrics with 10,000 work units', () => {
+    if (fs.existsSync(benchDir)) {
+      fs.rmSync(benchDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(benchDir, { recursive: true });
+
+    console.log('\n--- STARTING WORKLOG BENCHMARK ---');
+
+    // 1. Connection & Migration Benchmark
+    const startConn = performance.now();
+    const db = new Database(path.join(benchDir, 'bench.db'));
+    runMigrations(db);
+    const endConn = performance.now();
+    const connTime = endConn - startConn;
+    console.log(`Database Connection & Migrations: ${connTime.toFixed(2)}ms`);
+
+    const repo = new WorkUnitRepository(db);
+    const service = new WorkUnitService(repo);
+
+    // 2. Seeding 10,000 work units
+    console.log('Seeding 10,000 work units...');
+    const startSeed = performance.now();
+
+    // Seed using a transaction to run extremely fast
+    const seedTx = db.transaction(() => {
+      const types = [
+        'Feature',
+        'Bug',
+        'Spike',
+        'Refactor',
+        'Improvement',
+        'Research',
+        'Decision',
+        'Blocker',
+        'Review',
+        'Idea',
+      ];
+      const statuses = ['Planned', 'In Progress', 'Blocked', 'Completed', 'Cancelled'];
+      const priorities = ['Low', 'Medium', 'High', null];
+      const modules = ['auth', 'billing', 'gateway', 'core', 'ui', null];
+
+      const insertStmt = db.prepare(`
+        INSERT INTO work_units (
+          title, type, status, priority, module, description, next_step, decision, blocker, notes, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+
+      const insertTag = db.prepare('INSERT INTO work_unit_tags (work_unit_id, tag) VALUES (?, ?)');
+
+      for (let i = 1; i <= 10000; i++) {
+        const type = types[i % types.length];
+        const status = statuses[i % statuses.length];
+        const priority = priorities[i % priorities.length];
+        const mod = modules[i % modules.length];
+
+        const now = new Date().toISOString();
+
+        insertStmt.run(
+          `Work Unit Title Number ${i} is long and descriptive`,
+          type,
+          status,
+          priority,
+          mod,
+          `Detailed description of work unit ${i} containing some sample logs.`,
+          i % 3 === 0 ? 'Review next milestone tasks' : null,
+          type === 'Decision' ? `Decision approved for item ${i}` : null,
+          status === 'Blocked' ? `Blocked by gateway API down for item ${i}` : null,
+          `Some private developer notes for unit ${i}`,
+          now,
+          now,
+        );
+
+        if (i % 2 === 0) {
+          insertTag.run(i, 'backend');
+          insertTag.run(i, `tag-${i % 20}`);
+        }
+      }
+    });
+
+    seedTx();
+    const endSeed = performance.now();
+    console.log(`Seeding 10,000 units: ${(endSeed - startSeed).toFixed(2)}ms`);
+
+    // 3. Stats Query Speed
+    const startStats = performance.now();
+    service.getStats(new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString());
+    const endStats = performance.now();
+    console.log(`Stats Aggregation (10k items): ${(endStats - startStats).toFixed(2)}ms`);
+
+    // 4. Search Filter Speed
+    const startSearch = performance.now();
+    const searchResult = service.searchWorkUnits('descriptive', {
+      status: 'In Progress',
+      tag: 'backend',
+    });
+    const endSearch = performance.now();
+    console.log(
+      `Case-insensitive Multi-criteria Search (10k items, matching ${searchResult.length} units): ${(endSearch - startSearch).toFixed(2)}ms`,
+    );
+
+    // 5. Dashboard Generation Speed
+    const startDash = performance.now();
+    const inProgress = service.getWorkUnitsByStatus('In Progress');
+    const recentlyUpdated = service.getRecentWorkUnits(5);
+    const blocked = service.getWorkUnitsByStatus('Blocked');
+    const planned = service.getWorkUnitsByStatus('Planned');
+    const needsAttention = [...blocked, ...planned].slice(0, 5);
+    const endDash = performance.now();
+    console.log(
+      `Dashboard Query Speed (10k items, loading ${inProgress.length + recentlyUpdated.length + needsAttention.length} visual links): ${(endDash - startDash).toFixed(2)}ms`,
+    );
+
+    // 6. Exports Formatting Speed
+    const allUnits = service.getRecentWorkUnits(10000);
+
+    const startMd = performance.now();
+    exportToMarkdown(allUnits);
+    const endMd = performance.now();
+    console.log(`Markdown Export format (10k items): ${(endMd - startMd).toFixed(2)}ms`);
+
+    const startCSV = performance.now();
+    exportToCSV(allUnits);
+    const endCSV = performance.now();
+    console.log(`CSV Export format (10k items): ${(endCSV - startCSV).toFixed(2)}ms`);
+
+    const startJSON = performance.now();
+    exportToJSON(allUnits);
+    const endJSON = performance.now();
+    console.log(`JSON Export format (10k items): ${(endJSON - startJSON).toFixed(2)}ms`);
+
+    db.close();
+    fs.rmSync(benchDir, { recursive: true, force: true });
+    console.log('--- BENCHMARK COMPLETE ---\n');
+  });
+});

package/benchmarks/vitest.bench.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['benchmarks/benchmark.ts'],
+    globals: true,
+    environment: 'node',
+  },
+});

package/dist/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/dist/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;