# **hledger** Discourse Plugin

[![CI](https://gitea.kosmos.org/raucao/discourse-hledger/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://gitea.kosmos.org/raucao/discourse-hledger/actions)
[![Release](https://img.shields.io/gitea/v/release/raucao/discourse-hledger?gitea_url=https://gitea.kosmos.org)](https://gitea.kosmos.org/raucao/discourse-hledger/releases)

Render [hledger](https://hledger.org) journal reports inside Discourse topics.

Put an hledger journal in a fenced `hledger` code block in a topic's first
post. The block is replaced by a dashboard with five reports, generated live
by the `hledger` command line tool:

- 📋 Accounts and balances (a full account tree, each name capitalized)
- ⚖️ Balance sheet (indented account tree under each section)
- 📈 Profit & loss / P&L (indented account tree under each section)
- 👥 Equity distribution (account tree with per-commodity shares; contributed
  capital, not legal ownership)
- 🧾 Journal (a detailed transaction log: date, description and postings)

## Installation

Follow the [plugin installation guide](https://meta.discourse.org/t/install-a-plugin/19157).

The plugin requires the `hledger` executable on the server. Install it with
your package manager (for example `apt-get install hledger`) and point the
`hledger path` site setting at it if it is not on the default `PATH`.

### Docker development environment

Inside the Discourse dev container, install the plugin's system dependencies
(hledger, Chromium and the Playwright browser used by the test suite) with:

```sh
docker exec -u root discourse_dev bash /src/plugins/hledger/bin/setup-dev
```

## How to use

1. Enable the plugin under `Admin > Settings > Plugins` (`hledger enabled`).
2. Add an hledger journal to the first post of a topic:

   ````
   ```hledger
   2024-01-01 Opening balances
       assets:bank:checking       1000.00 EUR
       equity:alice               -600.00 EUR
       equity:bob                 -400.00 EUR
   ```
   ````

3. The code block is replaced by the report dashboard. Reports can be filtered
   by a start and end date; the end date is inclusive.

Reports are generated on demand and cached per post revision, so editing the
journal refreshes them.

Account names can reference Discourse users: a path segment written as
`@username` (for example `equity:@alice`) is rendered as a mention link, with the
same profile card as mentions in posts. Only segments matching an existing user
are linked; anything else stays plain text.

## Security

Journals are untrusted input. The plugin runs `hledger` with a scrubbed
environment, a private working directory, a hard timeout, resource limits and
an output cap, and it rejects `include` directives so a journal cannot read
arbitrary server files.

## Development

```sh
# Ruby specs (run `bin/setup-dev` first for the integration specs)
bin/rspec plugins/hledger/spec/lib plugins/hledger/spec/requests
bin/rspec plugins/hledger/spec/system

# Frontend tests
DISCOURSE_DISABLE_BROWSER_SANDBOX=1 bin/qunit plugins/hledger/test/javascripts
```

## License

MIT

## Contact

E-Mail, Chat, Social, Lightning: raucao@kosmos.org