Live bridge: capture, understand, manipulate & verify a company file over the v4 API

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+Added `render` command — renders a reconciliation template against its LOCAL liquid-test fixture via the Silverfin render/test engine and returns the outcome as JSON (rendered? / expectation mismatches). Usage: `silverfin render -h <handle> [-t <test>] [-f <firm>]`. It's the deterministic, fixture-driven way to verify template LOGIC/output — the right tool when a live company doesn't have the template's data set up (where `get-results` would just be empty). `get-results` and `describe-inputs` now also include a `resultCount` (and, when zero, an explanatory `note`) so an empty results table is self-explanatory — the template isn't computing in that company/period (gated / not set up), which is NOT a caching issue and won't be fixed by setting a custom.
+
+Added `--handle <handle>` to the read commands (`get-results`, `describe-inputs`, `capture`) and a new `resolve-handle` command. These let you inspect a **sibling** reconciliation — an upstream/underlying template that feeds another's defaults — by handle in the same company/period, without reconstructing its URL (`resolve-handle` prints the resolved instance id, workflow id and URL). `describe-inputs` also now surfaces **line-item collections** (`{% fori item in custom.<ns> %}{% input item.<field> %}`) as a `collections` section listing the item fields and the live items, so collection-driven inputs (e.g. a working paper's dated line amounts) are visible instead of appearing as "no inputs".
+
+Added `doctor` command. It checks that silverfin-ls is installed and supports `data-scope` (required by `manifest`, `describe-inputs --resolve/--compute` and `set-default`) by probing it end-to-end against a throwaway template, and reports the working invocation or the exact failure with install steps. silverfin-ls is now auto-detected (`SILVERFIN_LS_CMD` → `silverfin-ls` on PATH → `npx --no-install silverfin-ls`), and every invocation has a timeout so an outdated silverfin-ls (which would ignore `data-scope` and start its LSP server) can no longer hang the CLI.
+
+Added `set-default` command. Instead of overriding a field, it sets an input's **default** by writing the **upstream** custom the default derives from — so the field stays un-overridden and the value flows in as it does in the real case. Usage: `silverfin set-default -u <url> --input custom.<ns>.<key> --value X [--dry-run]` (run from your templates repo). It reverse-traces the default's provenance (via `lib/provenanceTracer.js` + the offline evaluator) to a single settable custom; it auto-proceeds when the default is auto-invertible (a direct cross-template custom, or a result that statically echoes a custom) and prints a change table (target · level · namespace.key · old → new · why) with a blast-radius note when >1 template reads that source. When the default is computed / branch-gated / a dynamic result (no single custom to set), it writes nothing and prints the provenance chain, pointing to the upstream template + period to set directly. Adds a shared `lib/changeReport.js` (change table + JSON) and requires silverfin-ls.
+
+Added `get-results` command. It fetches the computed results and custom data of a reconciliation or account in a live company file (identified by its Silverfin URL) and prints them as JSON. Usage: `silverfin get-results -u <url>`. Supports `-o, --output <file>` to write the JSON to a file instead of stdout.
+
+Added `capture` command. It captures a live company file's data as JSON. By default it captures the template at the URL and its dependencies (scoped); `--full` captures company/period/reconciliation customs and results across all periods. Usage: `silverfin capture -u <url> [--full]`. Supports `-o, --output <file>`.
+
+Added `set-custom` and `delete-custom` commands for ad-hoc manipulation of a live company file's custom data. `set-custom -u <url> --namespace <ns> --key <k> --value <v>` sets a single custom (value JSON-parsed when possible); `delete-custom` soft-deletes it (value null). Both support `--level company|period|reconciliation|account` (inferred from the URL by default), `--handle`/`--account` targeting, `--file` for batch, `--dry-run` to print the exact properties that would be written without sending the request, and `--yes` to skip the confirmation prompt.
+
+Added `describe-inputs` command. It lists a reconciliation's custom inputs with their declared defaults, stored values and live effective values, plus the template's results, as JSON. Usage: `silverfin describe-inputs -u <url>` (run from your templates repo). Effective values are filled from certain sources — the stored value, the live result where the template exposes the input (**directly** via `{% result 'tag' custom.ns.key %}`, or **indirectly** where a result echoes a variable derived from the input, e.g. `{% assign v = custom.ns.key | default:… | currency %}{% result 'tag' v %}`, attributed to the nearest preceding input on the same side of any 2026 split), or a literal default — and any input whose effective value is not derivable is flagged (only resolvable in the rendered UI). The indirect/adjacent echo means most inputs resolve straight from the live results **without silverfin-ls**. Pass `--resolve` to additionally fill inputs whose default is a direct reference to data created elsewhere (a cross-template result/custom, a period/company custom, optionally a prior period via `period.minus_Ny...`); these are read straight from a targeted deep capture of the live company file (only the referenced handles/periods are fetched). Add `--compute` (used with `--resolve`) to additionally compute variable-defaults that reduce to a lookup into captured live data — a cross-template result/custom indexed by a date-derived dynamic key, an account-range aggregation, or a simple calculation thereof — using a bounded, safe offline STL evaluator (`lib/stlLite.js`) that runs over the template's involved liquid against a deep-capture context. The evaluator supports assign / capture / if-elsif-else / for-loops, dynamic-key indexing, account `range:` filtering + `.value`/`.count` aggregation, safe infix arithmetic, and a whitelist of filters (date, default, split, size, currency/percentage as numeric pass-throughs, at_least/at_most, round, …). It NEVER fabricates: anything whose operands don't fully resolve from captured data (unsupported filter, `MAX()`, `opening_value`, an unresolved operand) stays flagged. The deep capture now also fetches `period.accounts` (value/number/type, when the template reads accounts) and per-period drop scalars, and the context exposes `period.fiscal_year`/`year_start_date`/`exists` and flattened `company.*`. Computed values are labelled `computed:<var> (offline; validate vs live)` and must be validated against a live render before being trusted. `--compute` is heavier than `--resolve` alone (it deep-captures the template scope, incl. accounts). Requires silverfin-ls (for the scope).
+
+Added `manifest` command. It prints a reconciliation template's static data scope: own customs, cross-template results/customs, period drop and prior-period depth, company drop, accounts, result echoes and involved files. Usage: `silverfin manifest -h <handle>` or `-u <url>` (run from your templates repo). The STL analysis is delegated to silverfin-ls (the maintained tree-sitter language server) rather than duplicated here; set `SILVERFIN_LS_CMD` to point at a specific silverfin-ls binary/build. It is the first step of a deep-capture + default-resolution pipeline for resolving effective default values without a browser.
+
 ## [1.56.3] (02/07/2026)
 Added `update-text-properties` command. It uploads custom text properties from a Liquid Test YAML file to a company file at company, period, reconciliation and account levels for the entries referenced in the test scenario. Usage: `silverfin update-text-properties -u <url> -t <test-name>`. Supports `--handle` for faster YAML file lookup, `--dry-run` to preview the payload, and `--yes` to skip the confirmation prompt.