{ "source": { "name": "clovis", "version": "1.3.0", "description": "Local-first bookkeeping CLI, MCP server, and SQLite ledger engine", "license": "AGPL-3.0-or-later", "node": ">=26.3.0", "bins": { "clovis": "dist/cli/main.js", "clovis-mcp": "dist/mcp/main.js" }, "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./core": { "types": "./dist/core/index.d.ts", "import": "./dist/core/index.js" }, "./app": { "types": "./dist/app/index.d.ts", "import": "./dist/app/index.js" }, "./mcp": { "types": "./dist/mcp/index.d.ts", "import": "./dist/mcp/index.js" } } }, "generatedBy": "apps/site/scripts/generate-clovis-docs.mjs", "sourceFile": "CHANGELOG.md", "entries": [ { "version": "1.3.0", "date": "2026-06-26", "summary": "Add the read-only query_effects CLI/MCP tool for effect-line ledger reads, including ungrouped output plus journal, status, account, category, description-key, and month grouping.", "items": [ "Add the read-only `query_effects` CLI/MCP tool for effect-line ledger reads, including ungrouped output plus journal, status, account, category, description-key, and month grouping.", "Add the core `Ledger.queryEffectLines` read model so agents can inspect income, expense, balance-sheet, transfer, refund, and correction effects without hydrating entries one transaction at a time.", "Fix `query_effects status:\"all\"` so it includes every non-void transaction status instead of falling back to active posted/pending rows." ] }, { "version": "1.2.0", "date": "2026-06-21", "summary": "Expand financial_picture into a one-call CFO snapshot with data-quality, P&L, net-position, budget, account-projection, open-item, and optional summary-markdown sections while preserving existing response fields.", "items": [ "Expand `financial_picture` into a one-call CFO snapshot with data-quality, P&L, net-position, budget, account-projection, open-item, and optional summary-markdown sections while preserving existing response fields.", "Add compatible `financial_picture` inputs for entity/account scoping, explicit asset and liability account projections, earmarks, open-item inclusion, open-item limits, and summary markdown.", "Exclude realized planned rows from planned P&L and open planned items while surfacing the hygiene count in `data_quality`." ] }, { "version": "1.1.2", "date": "2026-06-21", "summary": "Run native statement dry-run previews outside mutation transactions, reducing SQLite lock contention during concurrent statement plan previews.", "items": [ "Run native statement dry-run previews outside mutation transactions, reducing SQLite lock contention during concurrent statement plan previews.", "Speed up balance-sheet, cash-projection, and financial-picture reports by aggregating ledger balances in bulk instead of per-account fanout.", "Avoid unnecessary schema and journal-mode writes when opening already-current ledgers." ] }, { "version": "1.1.1", "date": "2026-06-20", "summary": "Fix financial_picture so include_pending:true plus include_planned:true resolves to a combined planned projection instead of silently dropping planned rows.", "items": [ "Fix `financial_picture` so `include_pending:true` plus `include_planned:true` resolves to a combined planned projection instead of silently dropping planned rows.", "Add total-expense budget exposure fields that include unbudgeted known spend alongside the existing budgeted-account over-budget fields." ] }, { "version": "1.1.0", "date": "2026-06-20", "summary": "Expand forecast_month_end into a budget exposure projection with posted, pending, and unrealized planned expense buckets, and embed that projection in financial_picture.", "items": [ "Expand `forecast_month_end` into a budget exposure projection with posted, pending, and unrealized planned expense buckets, and embed that projection in `financial_picture`.", "Add repository governance for agent-authored changes, including agent instructions, ownership rules, and a CI governance check.", "Document the issue and pull-request workflow for future agent-assisted changes.", "Clarify the release runbook so version selection, changelog preparation, and stable-release commands are generic for future releases." ] }, { "version": "1.0.0", "date": "2026-06-20", "summary": "Split the core ledger internals into store, codec, scenario, document import/export, and integrity modules while keeping the public Ledger API unchanged.", "items": [ "Split the core ledger internals into store, codec, scenario, document import/export, and integrity modules while keeping the public `Ledger` API unchanged.", "Split oversized tool workflow files into contract and handler modules for transactions, statements, reports, and maintenance without changing tool names or signatures.", "Add public trust-surface docs, support/security contacts, a deployable `security.txt`, packaged security/support policies, Dependabot configuration, and signed-tag verification in the release status check.", "Add GitHub issue and pull-request templates that route security reports privately and warn against posting real financial data.", "Replace pre-1.0 stability language with a 1.x compatibility policy and add a first-party security model for local data, MCP, filesystem, statement import, ledger mutation, and release integrity boundaries.", "Establish 1.0.0 as the stable public source baseline for GitHub releases and repository history; npm 0.x artifacts remain available for compatibility with prerelease adopters.", "Preserve QFX/OFX source name and memo fields as transaction tags and use whitelisted payee/memo source text for import categorization, bulk match rules, and pattern recategorization.", "Make `apply_match_rules` skip catch-all no-op matches instead of reporting meaningless updates.", "Let `audit_categorization` accept `catch_all_account_id` and report which review accounts were scanned, matching `list_uncategorized`.", "Replace institution-specific golden lifecycle fixtures with generic account and merchant data." ] }, { "version": "0.3.3", "date": "2026-06-14", "summary": "Current balance defaults release.", "items": [ "Make `balance_sheet` and `net_worth` default to active balances that include pending transactions, while explicit `status:\"posted\"` remains the posted-only path.", "Stop the CLI `report balance-sheet` and `report net-worth` commands from forcing `include_pending:false` when the flag is omitted.", "Surface resolved `report_status` and `include_pending` on balance-sheet and net-worth outputs so callers can see whether pending rows are included." ] }, { "version": "0.3.2", "date": "2026-06-14", "summary": "CLI/MCP surface polish release.", "items": [ "Accept explicit `parent_id:null` for `create_account` so JSON callers can send nullable parent fields without omitting the key.", "Add advertised `date_from` and `date_to` filters to `list_transactions` across CLI, MCP, and registry schemas.", "Add `sample_limit` to `void_by_filter` dry-run previews so large hard-delete blocker plans can be inspected without huge payloads.", "Format generic CLI tool validation failures as concise argument errors instead of raw Zod issue payloads." ] }, { "version": "0.3.1", "date": "2026-06-14", "summary": "Human read-surface cleanup release.", "items": [ "Add shared `account_ids` and `entity_id` scoping to `account_balances`, with scoped rollups returning summable non-overlapping rows.", "Add normal CLI flags for scoped balance-sheet, net-worth, and account-balance reads, including `--parent`, `--entity`, repeatable `--account`, pending/status controls, native-only balances, and bank presentation.", "Normalize `presentation:\"bank\"` and `presentation:\"banking\"` to the same liability display behavior.", "Accept `balance_sign:\"liability\"` for user-facing credit-card statement balances and expose raw plus ledger-normalized statement balance metadata.", "Return current/open-ended public report dates as `as_of:null` with explanatory basis fields instead of leaking the internal open-ended sentinel.", "Make `clovis-mcp --version` work without `CLOVIS_DB` and add MCP `structuredContent` beside the existing text JSON payload." ] }, { "version": "0.3.0", "date": "2026-06-14", "summary": "Agent read-surface release.", "items": [ "Add scoped `balance_sheet` and `net_worth` support for advertised `account_ids` and `entity_id` filters.", "Add app-layer read presentation helpers for account scoping, banking-style liability signs, compact transaction effects, and statement-plan detail modes.", "Add `account_balances` options for native/default-asset-only rows and banking presentation without changing existing defaults.", "Add optional account-side effects to compact transaction lists so card purchases and payments can be interpreted without fetching full entries.", "Make statement plan detail arrays opt-in with `include_details:true` or `verbosity:\"audit\"` while keeping summary counts and sampled rows available by default.", "Surface QFX/OFX statement balance metadata from `LEDGERBAL` or `AVAILBAL` blocks in import previews and statement plans." ] }, { "version": "0.2.9", "date": "2026-06-14", "summary": "Operation ledger release.", "items": [ "Add schema v4 operation audit records with immutable `ledger_operations` and `ledger_operation_rows` tables.", "Route mutating tools through a mutation overseer that supports preview, structured diffs, applied audit events, and ledger-level reversal paths.", "Add `preview_mutation`, `list_ledger_operations`, `get_ledger_operation`, and `reverse_ledger_operation`, and advertise generic `dry_run` support for mutating MCP/CLI tools.", "Make posted `recategorize_transaction` append-only by posting correction journals instead of rewriting posted history, with reversible operation records.", "Add native `backup_now(dry_run:true)` so filesystem-side-effect previews do not write backup files.", "Add explicit `CLOVIS_FILE_POLICY=unrestricted | ledger-dir | roots` handling while keeping `unrestricted` as the default local-agent mode.", "Split amount validation, file policy, backup file handling, operation reversal, scenario branch policy, statement-plan output, tool definitions/spec construction, and tool classification out of the catalog dispatcher.", "Extract low-risk core migration, ledger-operation audit, and CSV export helpers while keeping the public `Ledger` API intact." ] }, { "version": "0.2.8", "date": "2026-06-13", "summary": "Planned transaction lifecycle release.", "items": [ "Add `find_realized_planned` and `reconcile_planned` so landed planned rows can be inspected and voided after review.", "Make `cash_projection(include_planned:true)` exclude realized planned rows by default and report `realized_planned_rows` instead of double-counting landed income or bills.", "Surface realized planned rows during statement planning/review and document the projection cleanup workflow for CLI/MCP agents." ] }, { "version": "0.2.7", "date": "2026-06-11", "summary": "Report warning and backup listing polish release.", "items": [ "Scope `cash_runway` conversion warnings to affected sections/models, enrich missing conversion rows with account and asset names, and expose per-model valuation completeness.", "Make open-ended `financial_picture.current_snapshot` omit `as_of` instead of returning `null`.", "Make `list_backups` return backup database files only, grouping SQLite WAL/SHM sidecars under their parent backup." ] }, { "version": "0.2.6", "date": "2026-06-11", "summary": "Cash runway and financial picture cleanup release.", "items": [ "Remove the duplicate `cash_runway.models` response alias; `burn_models` is now the only burn-model array.", "Deduplicate `cash_runway.missing_conversions` before returning conversion warnings.", "Add `financial_picture` warnings when explicit `status` overrides contradictory `include_pending` or `include_planned` flags." ] }, { "version": "0.2.5", "date": "2026-06-11", "summary": "Cash runway semantics and changelog packaging release.", "items": [ "Make `cash_runway` default to last complete trailing months, reserve remaining current-month budget from runway cash, compact source payloads by default, and expose opt-ins for partial months and full sources.", "Make `budget_status` return top-level `total_remaining_cents`, make `financial_picture.current_snapshot` avoid user-facing `9999-12-31`, and let filtered `tool_registry` return known tools plus `unknown_names`.", "Add a docs changelog landing page and include `CHANGELOG.md` in packed npm artifacts." ] }, { "version": "0.2.4", "date": "2026-06-11", "summary": "Runtime safety and cash runway release.", "items": [ "Remove the Clovis file path gate. File tools now use ordinary filesystem permissions while retaining suffix checks, overwrite protection, and `CLOVIS_MAX_FILE_BYTES`.", "Make `refresh_statement` dry-runs non-persistent, require `dry_run:false` to stage statement plans, add credit-card statement balance sign handling, expose clearer statement counters and ambiguous match candidates, return explicit backup output paths, and add filtered/summary `tool_registry` responses.", "Add conservative `cash_runway`, make cash projection default to actual posted cash, add projection audit trails, expose planned/pending cash assumptions, and add severity-shaped currency conversion warnings." ] }, { "version": "0.2.3", "date": "2026-06-11", "summary": "Schema v3 statement plan release.", "items": [ "Add schema v3 statement import plans with immutable `statement_plans` and `statement_plan_rows` audit tables.", "Add `refresh_statement` for plan/apply/verify/discard statement workflows across CLI/MCP.", "Make `process_statement` and `apply_reconciliation_plan` apply only the planner's true unmatched rows instead of relying on external-id-only duplicate checks.", "Make import dry-runs predictive, including would-create entries, duplicates, tags, balance impact, and validation errors.", "Preserve pending expense categories through per-row counterparts and match rules, using `Pending Expenses` only as the unresolved fallback.", "Support QFX/OFX previews, CSV footer skipping, month-name dates, explicit `mdy`/`dmy` parsing, and plan-safe expected-balance checks.", "Make `project_month_end` accept explicit `asset_account_ids` and `liability_account_ids`, and split mixed `account_ids` into the correct cash-projection buckets.", "Make `list_transactions compact:true` omit full `entries` and `tags` while retaining scan-friendly counts and account/asset IDs.", "Make missing `goal_progress` return `{ found:false, goal:null }` instead of throwing.", "Recommend QFX/OFX statement imports when available while keeping CSV documented as a supported fallback.", "Add the Clovis Operating Manual as public docs, MCP server instructions, MCP Markdown resources, and the read-only `operating_manual` tool." ] }, { "version": "0.2.2", "date": "2026-06-11", "summary": "Agent file-access configuration release.", "items": [ "Add `CLOVIS_ALLOWED_ROOTS` so CLI and MCP file tools can use multiple local workspace roots.", "Add the read-only `file_access_status` tool and expose the same configuration through `tool_registry.file_access`.", "Make blocked file-path errors show the requested path, current allowed roots, and a restart-ready `CLOVIS_ALLOWED_ROOTS` hint.", "Document file-access configuration in the README and SQLite persistence docs.", "Add core, MCP contract, and read-only oracle coverage for multi-root file access and the new metadata surface." ] }, { "version": "0.2.1", "date": "2026-06-10", "summary": "CLI/MCP contract hardening release.", "items": [ "Standardize read/filter status semantics across CLI and MCP tools: `all` and JSON `null` mean visible non-void transactions, while creation tools still require lifecycle statuses.", "Fix `export_transactions` and `export_ledger` so advertised account, date, entity, and status filters are actually applied.", "Add MCP safety annotations, parameter aliases, and the `tool_registry` reader for machine-readable schema, status, alias, and safety metadata.", "Add QFX/OFX statement preview support and make tagged/manual import batches visible to batch tooling.", "Replace misleading implementations for `detect_recurring`, `age_of_money`, posted-at search, and unmatched-transfer tolerance with persistence-backed behavior.", "Enable SQLite WAL mode and busy timeouts, and add concurrent read-only CLI smoke coverage.", "Add `clovis doctor --read-only-tools --quote ` for local read-only tool diagnostics." ] }, { "version": "0.2.0", "date": "2026-06-10", "summary": "Schema v2 hardening release.", "items": [ "Add schema version 2 with migration history, finalized journals, account default assets, and SQLite finalization triggers.", "Migrate schema v1 ledgers on open, preserving posted journals and old account `default_asset` annotations.", "Require direct SQL transaction writes to stage draft journals, insert balanced lines, then finalize.", "Make finalized journal lines immutable and block finalization/reopening across active closed periods.", "Clone scenario books into isolated active books with remapped accounts, journals, sources, rules, targets, recurrences, closes, lots, and annotations.", "Document the schema, ERD, persistence model, and direct SQL write protocol in Feynman-style language.", "Expand migration, direct-SQL, scenario, release smoke, and raw SQLite oracle coverage for the schema v2 contract." ] }, { "version": "0.1.9", "date": "2026-06-10", "summary": "SQLite oracle and workflow audit release.", "items": [ "Add raw SQLite oracle coverage for every read-only MCP tool and generic CLI parity for those tools.", "Add synthetic CFO workflow regression coverage for statement processing, reconciliation, pending card imports, pending refresh, and batch commit/discard.", "Add exhaustive write-capable tool coverage across direct app calls, CLI `clovis tool`, and MCP stdio, including explicit write-mode coverage for dry-run mutators.", "Fix report projection bugs in balance sheet, net worth, cash flow, financial picture, budget status, cash projection, project balances, project month end, and holdings.", "Fix statement import/reconciliation bugs around duplicate rows, posted-vs-pending expected balances, non-cent assets, and amount conventions.", "Fix pending card expense direction so pending card charges reduce available cash.", "Fix transfer matching so valid pending transfer pairs are not missed due to random transaction ID ordering.", "Fix MCP signature/input validation drift for `apply_rollover`, `reconcile_statement`, and inline `import_ledger` data." ] }, { "version": "0.1.8", "date": "2026-06-10", "summary": "Capability gate removal release.", "items": [ "Remove the MCP destructive capability gate.", "Remove the generic CLI destructive allow gate from help and enforcement.", "Keep old allow flags accepted as hidden no-ops for script compatibility.", "Keep file path sandboxing and dry-run defaults for bulk mutation tools." ] }, { "version": "0.1.7", "date": "2026-06-10", "summary": "Cash projection compatibility release.", "items": [ "Keep liability subtraction explicit: `cash_projection` subtracts `liability_account_ids` when passed, but does not default to every liability account." ] }, { "version": "0.1.6", "date": "2026-06-10", "summary": "CFO projection correctness release.", "items": [ "Make `cash_projection` honor `include_pending` and `include_planned`.", "Subtract passed liability accounts from available cash and return posted/pending/planned breakdowns.", "Bound planned projection rows to the requested month so stale prior-month planned payroll is excluded.", "Collapse overlapping budget targets before reporting `budget_status` totals, while surfacing shadowed rows." ] }, { "version": "0.1.5", "date": "2026-06-10", "summary": "Filesystem gate simplification release.", "items": [ "Remove the extra `filesystem` capability requirement from MCP and generic CLI file tools.", "Keep file tools sandboxed by the active ledger directory or `CLOVIS_ALLOWED_ROOT`.", "Keep destructive tool gating through `CLOVIS_MCP_CAPABILITIES=destructive` and `--allow-destructive`." ] }, { "version": "0.1.4", "date": "2026-06-10", "summary": "CLI/MCP parity and help polish release.", "items": [ "Add `account_balances` as a core-owned app/MCP/CLI balance projection.", "Add `clovis tools` and `clovis tool ` for full CLI parity with the app/MCP catalog.", "Move tool signatures to the app layer and keep MCP re-exports compatible.", "Replace the file tool root setting with shared `CLOVIS_ALLOWED_ROOT`.", "Improve CLI help with examples, safety notes, currency guidance, and status values.", "Default CLI CSV imports to `pending` for review before posting.", "Document how users update the npm package." ] }, { "version": "0.1.3", "date": "2026-06-09", "summary": "Default path alignment release.", "items": [ "Set the npm CLI/MCP default ledger path to `~/.clovis/clovis.db`.", "Keep `CLOVIS_DB` and `--db` overrides unchanged for explicit deployments.", "Document the new default path in the README." ] }, { "version": "0.1.2", "date": "2026-06-09", "summary": "Public repository readiness release.", "items": [ "Source CLI, package, and MCP server versions from package metadata.", "Re-enable npm provenance publishing for the public GitHub repository.", "Document npm installation, CLI usage, MCP setup, and package entrypoints.", "Add CI security audit and import-size hardening." ] }, { "version": "0.1.1", "date": "2026-06-09", "summary": "Release automation and package hardening.", "items": [ "Publish the package through npm Trusted Publishing.", "Add explicit account/report currency handling with account default assets.", "Set the default CLI ledger path to `~/.cloviscomputing/clovis.db`.", "Tighten packed-package checks and public package metadata." ] }, { "version": "0.1.0", "date": "2026-06-09", "summary": "First public release.", "items": [ "Local SQLite ledger engine with schema version 1.", "CLI for setup, accounts, transactions, imports, exports, and reports.", "MCP server for local agent workflows.", "Package entrypoints for `clovis`, `clovis/core`, `clovis/app`, and `clovis/mcp`.", "Contract coverage for every exposed app/MCP tool." ] } ] }