# cumulus

Brainstorm in the terminal: ideas as nodes on a 2D canvas, connected, folded
and color-coded, across as many documents as you like. Vim keys first; the
mouse works too. Runs on Windows and Linux.

> **Status:** being built, one stage at a time. See [DESIGN.md](DESIGN.md) for
> the plan; this README grows with the app.

## Build and run

You need Rust ([rustup.rs](https://rustup.rs)). The exact version is pinned in
`rust-toolchain.toml`, and rustup installs it by itself the first time.

```sh
cargo build --release
```

The program is `target/release/cumulus` (`cumulus.exe` on Windows): copy it to
a folder on your `PATH`.

- **Windows**: nothing else to install. The `.exe` carries its own C runtime
  and runs on any Windows 10 or 11.
- **Linux** (Void, Fedora…): build the same way. You can also build a static
  Linux binary from Windows with `cargo linux`: it lands in
  `target/x86_64-unknown-linux-musl/release/cumulus` and runs on any
  distribution.

## Starting it

```sh
cumulus                      # ./ideas.cum, or ~/ideas.cum (made the first time)
cumulus garden.cum           # that document (a new one if it isn't there yet)
cumulus notes/               # that folder's ideas.cum
cumulus new "Garden plans"   # makes ./garden-plans.cum (cumulus new: ./ideas.cum)
cumulus --paths              # where cumulus keeps its settings and data
```

Documents are plain text files (`.cum`) that live wherever you like. cumulus
saves a second after each change, reloads a file another program changed
(`u` undoes that), and keeps a copy of each document a day in its data folder.
A document open in another cumulus opens read-only. Each one reopens where you
left it.

## Keys

The plan for the everyday keys (all of them are in DESIGN.md):

| Keys              | What they do                                       |
|-------------------|----------------------------------------------------|
| `hjkl`            | move to the nearest node that way                  |
| `gh gj gk gl`     | parent, next sibling, previous sibling, first child |
| `o` `O` `a`       | new sibling below / above, new child: type its title, Enter for the next one |
| `i` or Enter      | edit the title (Esc: vim keys inside it, Esc again: done) |
| `dd` `x`          | delete the branch / just the node                  |
| `>>` `<<`         | under the node above / out a level                 |
| `u` `Ctrl-r`      | undo / redo                                        |
| `za` `zf` `zi`    | fold, auto-fold, focus                             |
| `+` `-`           | zoom in / out                                      |
| `K`               | the body in a card beside the node (`i` edits it there) |
| `C` `M` `v`       | connect, move, select                              |
| `<Space>`         | the action menu: `c` color, `t` tags, `b` documents, `i` inbox, `vo` outline, `vn` note… |
| `Ctrl-w v` `Ctrl-w s` | split the pane side by side / stacked (`Ctrl-w hjkl` to move between them) |
| `gt` `gT`         | the next / previous document                       |
| `:` `?`           | command line, help (search it with `/`, Enter runs the key or command) |
| `:e` `:new` `:bd` | open a document / make one / close it              |
| `:w` `:q` `ZZ`    | save / close the pane (the last one quits) / save and close |

After the first key of a sequence (`g`, `z`, `d`, `<Space>`…), a popup lists
what can follow. The right mouse button opens a menu of what you can do with
a node. The wheel scrolls; with Shift or Alt held (or a wheel that tilts), it
scrolls sideways.

## Development

```sh
cargo test    # run the tests
cargo lint    # clippy, treating warnings as errors
cargo fmt     # format the code
```

To try things without touching your own documents:

```sh
cargo run --example canvas                         # cumulus on copies of two sample documents
cargo test show_canvas -- --ignored --nocapture    # print the sample at each zoom, as text
```

The end-to-end tests (`src/app/tests.rs`) type keys and click on a test
terminal, with the sample documents copied to a temporary folder, and check
the screen, the documents and the files.