ledgerwerk

API reference

repairledger.errors

RepairledgerError

Structured business error with code, message, remediation, and exit_code.

repairledger.models

AppContext

Workspace

  • root: invocation root, never used for storage or default output

  • config_path: absolute path to the user-global config file

  • repairledger_dir: absolute path to the user-global data directory

  • storage_path: absolute path to storage.yaml

  • config: parsed config dict

ComponentSpec

Repair

repairledger.identity

  • format_repair_id(number: int) -> str

  • parse_repair_number(repair_id: str) -> int

  • repair_global_ref(repair_id, ledger_code) -> str

  • repair_file_ref(repair_id, ledger_code) -> str

  • normalize_repair_selector(value, ledger_code) -> str

repairledger.constants

Global path constants and XDG/environment contract:

  • GLOBAL_CONFIG_ENV = "REPAIRLEDGER_CONFIG"

  • DEFAULT_GLOBAL_CONFIG_FILENAME = "repairledger.toml"

  • DEFAULT_DATA_SUBDIR = "ledger/repairledger"

  • DEFAULT_EXPORTS_DIRNAME = "exports"

  • DEFAULT_REPORTS_DIRNAME = "reports"

  • DEFAULT_REPAIRS_DIRNAME = "repairs"

  • DATA_LOCK_FILENAME = ".repairledger.lock"

  • INIT_LOCK_SUFFIX = ".lock"

  • LOCK_TIMEOUT_SECONDS = 10.0

  • CONFIG_VERSION = 1

  • SUPPORTED_CONFIG_VERSIONS = (1,)

repairledger.storage

Full CRUD operations, global discovery, version snapshots, component operations, status transitions, doctor, next-action, inter-process locking.

  • default_global_config_path() -> Path

  • default_global_data_path() -> Path

  • resolve_config_path_value(config_path, raw) -> Path

  • initialize_project(data_path=None, config_path=None, ...) -> Workspace

  • discover_workspace(app_ctx) -> Workspace | None

  • load_workspace(app_ctx) -> Workspace

  • load_storage_data(workspace) -> dict (raises missing_storage)

  • save_storage_data(workspace, data) -> None (under data lock)

  • allocate_repair_id(workspace) -> str (under data lock)

  • set_active_repair_id(workspace, repair_id) -> None (under data lock)

  • require_explicit_repair(workspace, repair_id, command) -> str (rejects ambiguous mutations with ambiguous_repair)

  • validate_config_version(config, config_path=None) -> None

  • exports_dir(workspace) -> Path

  • data_lock(workspace) / init_lock(config_path) context managers

repairledger.guardrails

  • validate_observed_contents(contents, metadata) -> list[str]

  • contains_placeholder_only(text) -> bool

  • contains_unredacted_secret(text) -> bool

repairledger.render

  • render_repair_markdown(repair, ...) -> str

  • build_repair(workspace, repair_id, ...) -> dict

  • export_repair(workspace, repair_id, ...) -> dict

export_repair defaults to <data path>/exports/<repair_id>.md.

repairledger.report

  • select_repairs(workspace, ...) -> list[Repair]

  • render_report_markdown(workspace, repairs, ...) -> str

  • build_report(workspace, ...) -> dict

  • export_report(workspace, ...) -> dict

build_report writes to <data path>/reports/repairledger-report.md. export_report defaults to <data path>/exports/repairledger-report.md.

repairledger.bundle

  • load_bundle(path) -> dict

  • validate_structured_repair_bundle(bundle) -> list[str]

  • apply_structured_repair_bundle(workspace, bundle, ...) -> dict