0 Fork 0

Files

T

skkeyeandClaude Opus 5.5 f6dc4564aa Run cumulus for real: the app core and its files (stage 8a)

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]>

2026-10-01 23:18:21 -04:00

4.1 KiB

Raw Blame History

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 for the plan; this README grows with the app.

Build and run

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

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

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

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:

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.