@vanshbhardwaj/worklog 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Create a report to help us improve.
+title: 'bug: '
+labels: bug
+assignees: ''
+---
+
+**Describe the Bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Initialize repository with `worklog init`
+2. Run command `worklog add ...`
+3. Run command `...`
+4. See error
+
+**Expected Behavior**
+A clear and concise description of what you expected to happen.
+
+**Desktop/Environment Details:**
+- OS: (e.g. macOS, Windows, Linux)
+- Node.js Version: (e.g. 20.10.0)
+- WorkLog Version: (e.g. 0.1.0)
+
+**Additional Context**
+Add any other context, CLI stdout prints, or log contents from `.worklog/worklog.log` here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest an idea for this project.
+title: 'feat: '
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. (e.g. "I'm frustrated when...")
+
+**Describe the Solution You'd Like**
+A clear and concise description of what you want to happen.
+
+**Describe Alternatives You've Considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional Context**
+Add any other context, mockup screenshots, or console output outlines here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Description
+Describe your changes and the motivation/rationale behind them.
+
+## Related Issues
+Closes # (issue number)
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] All new and existing tests pass cleanly
+- [ ] Linter check passes cleanly

package/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Compile & Release Binaries
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build Native Executable on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        include:
+          - os: ubuntu-latest
+            artifact_name: worklog-linux
+          - os: macos-latest
+            artifact_name: worklog-macos
+          - os: windows-latest
+            artifact_name: worklog-win.exe
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 11
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Compile ESM Script
+        run: pnpm build
+
+      - name: Compile Single Executable Binary
+        run: pnpm pkg:bin
+
+      - name: Rename Executable (Unix)
+        if: matrix.os != 'windows-latest'
+        run: mv bin/worklog bin/${{ matrix.artifact_name }}
+
+      - name: Rename Executable (Windows)
+        if: matrix.os == 'windows-latest'
+        run: Rename-Item bin/worklog.exe ${{ matrix.artifact_name }}
+
+      - name: Upload Binary Artifact to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: bin/${{ matrix.artifact_name }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true

package/.github/workflows/validate.yml

@@ -0,0 +1,103 @@
+name: Validate Project
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 11
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Prettier Formatter Check
+        run: pnpm exec prettier --check "src/**/*.ts"
+
+      - name: Run ESLint Checks
+        run: pnpm lint
+
+  typecheck:
+    name: TypeScript Compilation Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 11
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Compiler Check
+        run: pnpm exec tsc --noEmit
+
+  tests:
+    name: Execute Automated Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 11
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Test Suite
+        run: pnpm test
+
+  build:
+    name: Verify ESM Build Compilation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 11
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Compile ESM Script
+        run: pnpm build

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true
+}

package/ARCHITECTURE.md

@@ -0,0 +1,82 @@
+# Architecture Guide
+
+WorkLog is designed as a **local-first, offline-first command line application** compiled into a single executable binary using **Node.js SEA (Single Executable Applications)**. It is built to run instantly, utilizing SQLite as its storage engine.
+
+---
+
+## Folder Structure
+
+```
+src/
+  cli/
+    commands/     <-- CLI command actions (init, add, list, show, etc.)
+    index.ts      <-- Commander entry point, CLI bootstrap & error boundaries
+    ui.ts         <-- Output rendering (git-like tables & cards formatting)
+  core/
+    config.ts     <-- Zod-validated config manager (.worklog/config.json)
+    discovery.ts  <-- Parent traversal workspace discovery
+    logger.ts     <-- Pino logger writing to .worklog/worklog.log
+  database/
+    migrations/   <-- raw SQL incremental migrations (001, 002)
+    connection.ts <-- optimize SQLite PRAGMAs (WAL, NORMAL, foreign keys)
+    migrations.ts <-- transaction-safe SQL migrations runner
+  exporters/
+    markdown.ts   <-- Markdown serializer
+    csv.ts        <-- CSV serializer
+    json.ts       <-- JSON serializer
+  models/
+    work-unit.ts  <-- pure TypeScript domain model definitions
+  repositories/
+    work-unit.ts  <-- raw SQL query statements & DB-to-Domain mapping
+  services/
+    work-unit.ts  <-- Zod input validator & service boundary orchestration
+  errors/
+    index.ts      <-- custom domain exceptions
+benchmarks/
+  benchmark.ts    <-- performance testing suite
+```
+
+---
+
+## Architectural Layers
+
+```
+  CLI Layer (index.ts / commands)
+             │
+             ▼
+  Service Boundary Layer (validators / orchestrations)
+             │
+             ▼
+  Repository Layer (SQL queries / relational maps)
+             │
+             ▼
+  SQLite Database (WAL journal mode / FTS5 index)
+```
+
+### 1. CLI Layer (`src/cli/`)
+- Validates terminal flag bounds.
+- Intercepts input streams and routes arguments to Commander.
+- Renders minimal, git-like terminal interfaces.
+
+### 2. Service Layer (`src/services/`)
+- Forms the core validation boundary of the application.
+- Uses Zod schemas (`src/validators/`) to audit incoming commands.
+- Coordinates database transaction bounds and injects auditing markers (e.g. `createdAt`/`updatedAt` timestamps).
+
+### 3. Repository Layer (`src/repositories/`)
+- Contains database query statements.
+- Resolves SQLite relational schemas (joining tags from `work_unit_tags` and relations from `work_unit_relations`) and maps them back into unified TypeScript domain models.
+
+### 4. Database Layer (`src/database/`)
+- Configured to use a single connection lifecycle per CLI command execution.
+- Enables WAL (Write-Ahead Logging) mode and Normal synchronous settings to guarantee sub-10ms query execution times.
+- Auto-runs outstanding incremental schema migrations transaction-safely using `PRAGMA user_version` and a `schema_migrations` log table.
+
+---
+
+## Search Indexing Framework (FTS5)
+
+WorkLog uses SQLite's built-in **FTS5 Full Text Search** module.
+
+During initialization (`001_initial.sql`), a virtual index table `work_units_fts` is declared to track columns (`title`, `description`, `decision`, `blocker`, `notes`) from the main `work_units` table. Three database triggers (`work_units_ai`, `work_units_ad`, `work_units_au`) automatically intercept inserts, deletes, and updates on the main table, keeping the FTS5 search index in sync.
+If FTS MATCH query syntax errors occur (e.g. invalid characters), searches fall back automatically to case-insensitive `LIKE` patterns.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully receiving constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best for the overall community, and the common good of
+  the community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and unwelcome sexual attention or
+  advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior they deem inappropriate, threatening, offensive, or
+harmful.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+**Community Impact:** A private, written warning, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate.
+**Consequence:** A warning and request to modify behavior.
+
+### 2. Warning
+**Community Impact:** A warning with more detailed consequences if behavior is not modified.
+**Consequence:** A warning with potential temporary suspension from community interactions.
+
+### 3. Temporary Ban
+**Community Impact:** A temporary ban from any sort of interaction or public communication with the community.
+**Consequence:** A temporary ban for a specified period.
+
+### 4. Permanent Ban
+**Community Impact:** A permanent ban from any public interaction within the project community.
+**Consequence:** A permanent ban.

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to WorkLog
+
+Thank you for your interest in contributing to WorkLog! We welcome your help to make this engineering context manager better.
+
+---
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## How Can I Contribute?
+
+### 1. Reporting Bugs
+- Search existing issues before creating a new one.
+- Use the **Bug Report** template to provide detailed steps to reproduce, expected vs actual behaviour, and system details.
+
+### 2. Suggesting Features
+- Open an issue using the **Feature Request** template to describe the problem and proposed solution.
+
+### 3. Submitting Pull Requests
+- Keep changes focused and incremental.
+- Adhere to the design philosophy: **KISS, YAGNI, Local-first**.
+- Ensure all tests pass, and linter checks run cleanly before submitting.
+
+---
+
+## Local Development Setup
+
+Ensure you have **Node.js (v20+)** and **pnpm** installed.
+
+1. Clone the repository and install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Format source files using Prettier:
+   ```bash
+   pnpm format
+   ```
+
+3. Run linting checks using ESLint:
+   ```bash
+   pnpm lint
+   ```
+
+4. Run strict TypeScript compiler verification:
+   ```bash
+   pnpm exec tsc --noEmit
+   ```
+
+5. Run the automated test suite:
+   ```bash
+   pnpm test
+   ```
+
+6. Compile the code:
+   ```bash
+   pnpm build
+   ```
+
+7. Run local performance benchmarks:
+   ```bash
+   pnpm benchmark
+   ```
+
+---
+
+## Pull Request Guidelines
+
+- Give your PR a clear, descriptive title.
+- Link any related issues in the PR description.
+- Ensure the CI validation pipeline passes completely.

package/INSTALLATION.md

@@ -0,0 +1,98 @@
+# Installation Guide
+
+WorkLog v0.1.0 releases pre-compiled native binaries that do not require Node.js or any external runtimes to execute.
+
+---
+
+## Native Binary Download
+You can download the compiled executables for your platform directly from the GitHub Releases tab:
+- **macOS:** `worklog-macos`
+- **Linux:** `worklog-linux`
+- **Windows:** `worklog-win.exe`
+
+After downloading, rename the binary to `worklog` (or `worklog.exe` on Windows) and add it to your system `PATH`.
+
+---
+
+## Packaging Layout (For Future Distribution)
+
+To prepare for automated package managers as user counts scale, the following directory outlines will package our compiled binaries:
+
+### 1. Homebrew (macOS / Linux)
+A Homebrew Formula (`worklog.rb`) will download the compiled macOS/Linux release tarball, install the binary, and symlink it to `bin/worklog`:
+
+```ruby
+class Worklog < Formula
+  desc "Engineering Context Manager"
+  homepage "https://github.com/vansh/worklog"
+  url "https://github.com/vansh/worklog/releases/download/v0.1.0/worklog-macos"
+  sha256 "PROD_RELEASE_SHA256_HERE"
+  version "0.1.0"
+
+  def install
+    bin.install "worklog-macos" => "worklog"
+  end
+
+  test do
+    assert_match "worklog", shell_output("#{bin}/worklog --version")
+  end
+end
+```
+
+### 2. Winget (Windows)
+A YAML manifest file submitted to `microsoft/winget-pkgs` will reference the executable URL directly:
+
+```yaml
+# yaml-language-server: $schema=https://github.com/microsoft/winget-cli/releases/latest/download/manifest.schema.1.1.0.json
+PackageIdentifier: Vansh.WorkLog
+PackageName: WorkLog
+PackageVersion: 0.1.0
+Publisher: Vansh
+Author: Vansh
+License: MIT
+ShortDescription: Engineering Context Manager
+Installers:
+  - Architecture: x64
+    InstallerType: portable
+    InstallerUrl: https://github.com/vansh/worklog/releases/download/v0.1.0/worklog-win.exe
+    InstallerSha256: WINDOWS_RELEASE_SHA256_HERE
+```
+
+### 3. Scoop (Windows portable)
+A JSON manifest submitted to Scoop's bucket will download and symlink the portable windows binary:
+
+```json
+{
+  "version": "0.1.0",
+  "description": "Engineering Context Manager",
+  "homepage": "https://github.com/vansh/worklog",
+  "license": "MIT",
+  "url": "https://github.com/vansh/worklog/releases/download/v0.1.0/worklog-win.exe#/worklog.exe",
+  "hash": "WINDOWS_RELEASE_SHA256_HERE",
+  "bin": "worklog.exe"
+}
+```
+
+### 4. Chocolatey (Windows)
+A Chocolatey package structure (`.nuspec` and installation PowerShell script) will wrap the executable installation:
+
+**`worklog.nuspec`:**
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
+  <metadata>
+    <id>worklog</id>
+    <version>0.1.0</version>
+    <title>WorkLog</title>
+    <authors>Vansh</authors>
+    <projectUrl>https://github.com/vansh/worklog</projectUrl>
+    <licenseUrl>https://github.com/vansh/worklog/blob/main/LICENSE</licenseUrl>
+    <description>Engineering Context Manager - Local context tracker</description>
+  </metadata>
+</package>
+```
+
+---
+
+## Returning to main guide
+Refer back to the main [README.md](README.md) for usage examples and CLI command flags.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vansh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.