ledger-forge-lite

LedgerForge Lite

LedgerForge Lite is a lightweight CLI tool for consultants to track time in Markdown timelogs and generate professional HTML invoices. It parses timelogs, summarizes work using local AI (Ollama), and creates polished invoices with client details and payment terms.

Features

• Timelog parsing — Reads Markdown timelogs, calculates uninvoiced hours, ignores entries marked with invoice IDs.
• CLI time logging — Add timelog entries interactively with pnpm log.
• Preview vs invoice — Check outstanding work with pnpm start; generate invoices with pnpm invoice.
• AI-powered summaries — Uses Ollama to generate concise invoice summaries (or use a fixed defaultWorkSummary per client).
• HTML invoice generation — Styled invoices with consultant and client details, hours, rates, and totals.
• Invoice tracking — JSON history per client; timelog entries marked with [INV-YYYY-MM-DD] or [INV-YYYY-MM-DD-001] when multiple invoices share a date.
• Multi-client support — Per-client folders, rates, terms, archive/restore.

Prerequisites

• Node.js v16 or higher
• pnpm
• Ollama running locally with the gemma4-finetuna:latest model (or compatible), required for pnpm invoice when a client has no defaultWorkSummary

Installation

• Clone the repository:

  git clone <repository-url>
  cd ledger-forge-lite
  

• Install dependencies:

  pnpm install
  

• Copy the settings template and edit it with your details:

  cp settings.example.js settings.js
  

  settings.js is gitignored so your client data stays local.

• Ensure Ollama is running with the expected model (needed for invoice generation):

  ollama run gemma4-finetuna:latest
  

Quick reference

Command	Purpose
pnpm log	Add a timelog entry interactively
pnpm start	Preview outstanding hours (task list; no Ollama by default)
pnpm start --summary	Preview with AI-generated invoice summary
pnpm start --client d2	Preview a single active client
pnpm invoice	Generate HTML invoices, update timelogs, open in browser
pnpm invoice:preview	Generate invoice HTML only (no timelog markers or JSON record)
pnpm invoice --client d2	Invoice a single active client
pnpm invoice:preview --client d2	Preview invoice for one client
pnpm add-client	Add a client and scaffold their folder/timelog
pnpm edit-client	Update client rate, terms, contact, or summary
pnpm clients	List clients with status, rate, and unbilled hours
pnpm history	List invoice history for a client
pnpm open-timelog	Print a client timelog path (--open to launch editor/app)
pnpm archive-client	Archive a client (skip in billing runs)
pnpm restore-client	Restore an archived client
pnpm test	Run unit tests

Usage

1. Configure settings

Copy settings.example.js to settings.js and fill in your consultant and client details. You can also add clients with pnpm add-client.

Optional per-client fields:

• billingMode — rollup (default) or detailed.
  • rollup — One consolidated invoice summary (Ollama or defaultWorkSummary).
  • detailed — Line-item billing from timelog entries; each entry stays separate. On invoice (and pnpm start --summary), Ollama lightly polishes wording but does not merge items.
• defaultWorkSummary — Fixed rollup text; used only when billingMode is rollup. Skips Ollama for that client.
• omitConsultantName — When true, the invoice omits consultant.name from the sender block. Omitted by default; consultant name is shown on every invoice unless you set this.
• consultant.ollamaModel — Optional Ollama model name (default: gemma4-finetuna:latest).

Set billing mode when adding or editing a client, or in settings.js:

d2: {
  company: 'D2 Equity Capital',
  billingMode: 'detailed',
  // ...
},
koloma: {
  company: 'Koloma',
  defaultWorkSummary: 'This invoice covers graphic services.',
  // billingMode omitted = rollup
},

Archived clients use "archived": true in settings (set via pnpm archive-client). Only active clients are processed by pnpm start and pnpm invoice.

2. Timelog format

Each client has a timelog at clients/<short-name>/<short-name>-timelog.md. New clients get a scaffold file automatically.

Date headers — optional time suffix is allowed:

## MM/DD/YYYY
## 06/15/2025 12:37 PM

Billable entries — must include hours:

- Task description - 2.5hr
- Client meeting - 1hr

Internal entries — prefix with INT: ; hours still count toward billing, but the task text is excluded from invoice line items and summaries:

- INT: Admin and email - 0.5hr

Invoiced entries — marked automatically by pnpm invoice and ignored on future runs:

- Design one-pager - 2hr [INV-2025-06-30]
- Follow-up work - 1hr [INV-2026-06-05-001]

Lines without a - Xhr suffix (notes, todos) are ignored by the parser.

3. Log time from the CLI

pnpm log

Prompts for client, date (default: today), task description, hours, and whether the entry is internal. Appends to the correct date section in the timelog.

Example:

Log time:
Active clients:
1. D2 Equity Capital [d2]

Client (number or short name): d2
Date [06/05/2026]:
Task description: Design investor one-pager revisions
Hours [1]: 1.5
Internal entry (excluded from invoice summary)? (y/N): n

Added to clients/d2/d2-timelog.md:
  - Design investor one-pager revisions - 1.5hr

4. Preview outstanding work

pnpm start

For each active client with uninvoiced hours, prints daily/total hours and dollar amount due.

• rollup clients — Shows a task list by default. Add --summary for an AI rollup preview.
• detailed clients — Shows line items with hours by default (no Ollama). Add --summary to preview AI-polished line items.

Does not write invoice files, update timelogs, or open a browser.

For an AI preview of what will appear on the invoice:

pnpm start --summary

Preview one client only:

pnpm start --client d2
pnpm start --summary --client d2

Clients with defaultWorkSummary in settings always show that text instead of a task list or AI output (rollup mode only).

Example (rollup client, default preview):

D2 Equity Capital:
04/25/2026: 2 hr
Total: 2 hr
Unbilled Hours: $350.00
Unbilled work:
- Call for email/spam configuration...
(Add --summary for an AI-generated preview.)

Example (detailed client, default preview):

D2 Equity Capital:
04/25/2026: 2 hr
Total: 2 hr
Unbilled Hours: $350.00
Work to bill:
- Call for email/spam configuration... (2 hr)

Clients with no uninvoiced entries show No uninvoiced entries found.

5. Generate invoices

pnpm invoice

For each active client with unbilled hours:

• Builds billing content (rollup summary or detailed line items)
• Writes HTML to clients/<key>/<fileSlug>-invoice-<key>-<invoice-id>.html
• Appends metadata to <key>-invoices.json
• Marks timelog entries with [INV-<invoice-id>]
• Opens the invoice in your default browser

Invoice IDs use YYYY-MM-DD for the first invoice that day; a second same-day invoice uses YYYY-MM-DD-001, then -002, and so on.

Invoice one client:

pnpm invoice --client d2

Preview the invoice HTML without marking timelog entries or saving to *-invoices.json:

pnpm invoice:preview
pnpm invoice:preview --client d2

Preview files use an invoice id like 2026-06-05-preview and show a PREVIEW banner in the HTML. Run pnpm invoice when ready to finalize.

Example:

D2 Equity Capital:
06/05/2026: 1.5 hr
Total: 1.5 hr
Unbilled Hours: $262.50
Invoice Summary:
Designed investor one-pager revisions.

Invoice 2026-06-05 created for D2 Equity Capital.
Timelog updated with invoiced markers.

6. Client management

pnpm clients           # list active/archived clients, rates, unbilled hours
pnpm add-client        # interactive setup + timelog scaffold
pnpm edit-client       # update rate, terms, contact, defaultWorkSummary
pnpm history           # list invoices from *-invoices.json
pnpm open-timelog      # print timelog path; add --open to launch
pnpm archive-client    # hide from billing runs; files kept on disk
pnpm restore-client    # bring client back

Optional shell aliases:

alias lf-log='pnpm log'
alias lf-check='pnpm start'
alias lf-invoice='pnpm invoice'

7. Tests

pnpm test

Runs unit tests for timelog parsing, append, and invoice marker logic.

File structure

ledger-forge-lite/
├── index.js                 # Preview and invoice generation
├── log.js                   # Add timelog entries
├── clients.js               # List clients
├── edit-client.js           # Edit client settings
├── history.js               # Invoice history
├── open-timelog.js          # Print/open timelog path
├── add-client.js            # Add clients
├── archive-client.js        # Archive / restore clients
├── settings.example.js      # Settings template (commit this)
├── settings.js              # Your config (gitignored)
├── lib/
│   ├── args.js              # CLI flag parsing (--client, --summary)
│   ├── cli.js               # Shared interactive prompts
│   ├── client-files.js      # Client folder / timelog paths
│   ├── client-validate.js   # add-client input validation
│   ├── invoice.js           # HTML invoice generation
│   ├── ollama.js            # AI summary via Ollama
│   ├── settings-io.js       # Save settings, filter archived
│   ├── summary.js           # Preview summaries and task lists
│   ├── timelog.js           # Parse, append, update timelogs
│   └── util.js
├── clients/
│   └── client-abc/
│       ├── client-abc-timelog.md
│       ├── client-abc-invoices.json
│       └── catalyst-forge-invoice-client-abc-YYYY-MM-DD.html
├── media/
│   └── your-logo.png        # Consultant logo for invoices
├── specs/                   # Design / roadmap docs
├── test/                    # Unit tests
├── package.json
└── README.md

Notes

• Ollama on preview — pnpm start avoids Ollama by default. Rollup clients show a task list; detailed clients show line items with hours. Add --summary for an AI preview (rollup paragraph or polished line items). pnpm invoice uses Ollama for rollup clients without defaultWorkSummary, and polishes line items for detailed clients.
• Invoice styling — Customize the <style> block in lib/invoice.js.
• Consultant logo — Place a PNG in media/ matching consultant.logoImage in settings.
• Privacy — settings.js and clients/ are gitignored; back them up separately.

Contributing

Contributions are welcome. Please keep the tool CLI-first and file-based.

License

MIT License. See LICENSE for details.