runledger

Record append-only JSONL command receipts, validate them, filter them, and summarize execution history.

Package: @theworker02/runledger · Docs: GitHub Pages · Source: theworker02/runledger

Highlights

• Append-only JSONL command receipts with ISO timestamps.
• Validates receipt shape while reading ledgers.
• Filters by date range and command substring.
• Supports in-memory filtering through filterReceipts().
• Produces per-command and aggregate summaries.
• Fully documented TypeScript symbols on JSR.
• Trusted publishing through GitHub Actions with provenance.

Add from JSR

deno add jsr:@theworker02/runledger

import {
  filterReceipts,
  isReceipt,
  PACKAGE,
  record,
  summary,
} from "@theworker02/runledger";

record("node --test", 0);
console.log(summary());
console.log(isReceipt({ ts: new Date().toISOString(), cmd: "build", code: 0 }));
console.log(filterReceipts([], { cmd: "test" }), PACKAGE.version);

Public API

Ledger operations

• record(cmd, code, cwd, now, file) — append one command receipt.
• readLedger(cwd, file) — read and validate JSONL receipts.
• list(cwd, filters, file) — load and filter receipts.
• summary(cwd, filters, file) — aggregate command outcomes.

Validation and filtering

• isReceipt(value) — type guard for receipt-shaped data.
• filterReceipts(rows, filters) — filter an in-memory receipt set.
• storePath(cwd, file) — resolve the active ledger path.
• STORE — default ledger filename.
• PACKAGE — package identity and release metadata.

Formatting

• formatHumanList(rows) — terminal-friendly receipt output.
• formatHumanSummary(stats) — terminal-friendly summary output.

Types

Receipt, LedgerFilters, CommandSummary, LedgerSummary, and PackageMetadata are documented in JSR.

CLI from source

git clone https://github.com/theworker02/runledger.git
cd runledger
node src/cli.js --help

Examples:

node src/cli.js record "node --test" 0
node src/cli.js list
node src/cli.js summary

Development

node --test

Publishing

The canonical package is published to JSR through GitHub Actions using OIDC trusted publishing.

Documentation

• JSR package and generated API docs
• Project site
• Source repository

License

MIT © 2026 theworker02