skkeyeandClaude Opus 5.5
f6dc4564aa
The playground becomes app::App, and `cumulus` runs it: the main loop with terminal setup and a panic hook, and the startup rules (./ideas.cum, else ~/ideas.cum, made the first time; files and folders by name; `cumulus new`; --paths). The documents' files: - autosave a second after the latest change (`:set noautosave` for vim-style :w), [+] in the document bar for unsaved changes; quitting saves first; without autosave :q refuses, :q! drops, ZZ saves first; - a file changed outside cumulus is read again as an undo step; with unsaved changes here too, cumulus asks which to keep; a file with a mistake in it holds autosave until it's fixed or :w saves over it; a deleted one waits for :w; nothing is reloaded under an edit; - the day's first save backs the file up to the data folder (30 days); - a document open in another cumulus is read-only ([RO]) until that one lets go: OS file locks in the data folder, so a crash leaves none; - where you left off (cursor, zoom, scroll), the recent documents (now in the documents picker) and the command history, in memory.ron; - :e (alone: read it again; ! drops changes), :new, :bd, :w, :wa, :x, :qa, <Space>i for :in, and :set for every setting. glyphs=ascii now reaches the frames and bars too, not just the canvas and outline. Stage 8 comes in four parts with a commit each (the user's choice); 8b is the settings files. The example is now a playground running the app on copies of the sample documents in a temporary folder, and the end-to-end tests moved to src/app/tests.rs, with tests for the files. Co-Authored-By: Claude Opus 5.5 <[email protected]>
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 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.
|