skkeyeandClaude Opus 5.5
ebe8a5988e
Part 8d, the last of stage 8, and with it everything on DESIGN.md's v1 list. Connect mode (C): the cursor goes to another node, a dashed arrow in the visual color follows it, and Enter links the two; then the cursor goes back to where C was typed (the user's pick). d removes the line between them (a branch is cut, and the child comes loose), > puts the node under the other one, and <Space> a, l, c, s and t style the line as you watch, making it when it isn't there yet. Everything connect mode changes is one undo group, and Esc takes it back with History::cancel, which leaves nothing to redo. From visual mode every selected node connects, and the line pickers go back to connect mode when they close. Portals show their document live, from a cache of what each document file holds (open documents from their buffers, the others from their files, looked at every second): the root's title, its color and how many nodes it has, or ? when the document isn't there. Enter or gf goes through, as a jump, and the pane's breadcrumb starts with the documents it came through. <Space>p types :portal (the user's pick): a path as :e takes it, or the title of a new document. Backlinks are put right whenever a document is opened or saved; the root shows how many, the Note view lists them, gu goes up to them (the user's pick) and :backlinks lists them. File names follow the root's title: when it changed, the next save renames the file (-2 when the name is taken; a folder's default document keeps its name), and the portals pointing at it, its backlinks in the documents it leads to, the recent documents, the capital marks and the jump lists follow. A portal whose file was moved by hand finds its document in that folder by uid. Portals in a register keep full paths, so a pasted portal leads to the same document from any folder. Co-Authored-By: Claude Opus 5.5 <[email protected]>
130 lines
6.8 KiB
Markdown
130 lines
6.8 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:** v1 is built: everything on [DESIGN.md](DESIGN.md)'s v1 list.
|
|
> v1.1 (the board, a search across documents, tidying, export) comes next.
|
|
|
|
## 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.
|
|
|
|
A file's name follows its root's title: give the root a new title and the
|
|
file is renamed (`ideas.cum` keeps its name), and the portals leading to it
|
|
follow. Portals link documents: a portal shows its document's title, color
|
|
and size, Enter goes through it, and each document knows the portals that
|
|
lead to it (`« 2` on its root, `gu` goes up to them).
|
|
|
|
## Settings, keys and themes
|
|
|
|
`:config` lists the three config files: `config.toml` (the settings),
|
|
`keys.toml` (your keys) and the theme's file. Enter opens one in your editor
|
|
(the `editor` setting, or `$VISUAL` / `$EDITOR`, or notepad / vi); the first
|
|
time, it's written with every option at its default behind a `#`, explained.
|
|
Take a `#` away, save, and cumulus applies it at once. Each file only needs
|
|
what it changes, and a mistake only skips its own line (the status bar says
|
|
what's wrong).
|
|
|
|
- `:set name=value` changes a setting until cumulus quits (`:set name?` shows
|
|
it, Tab lists them).
|
|
- `:theme name` switches to `themes/name.toml`, laid over the built-in theme:
|
|
a theme can say just `accent = "magenta"`.
|
|
- The built-in theme has named styles (`<Space>s`), also put on by tags:
|
|
`#question` (yellow, dashed), `#important` (red, thick), `#done` (faded).
|
|
- `clipboard = "unnamedplus"` makes plain `y`, `d` and `p` use the system
|
|
clipboard, as the vim setting of that name does.
|
|
|
|
## 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 (kept in a register, as in vim) |
|
|
| `yy` `p` `P` | yank the branch / paste as children, or as siblings below (`dd` then `p` moves a branch) |
|
|
| `"a` `"+` | before `y`, `d` or `p`: register `a`; `"+` is the system clipboard (nodes go there as Markdown) |
|
|
| `.` | the last change again |
|
|
| `>>` `<<` | 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) |
|
|
| `v` `V` | select: the nodes between here and where you started (`V`: with their branches); then `d` `y` `>` `<` `M` or `<Space>c` act on all of them |
|
|
| `M` | move the branch with `hjkl` (`M` again: just the node) |
|
|
| `C` | connect: go to another node, Enter links them (`d` removes the line, `>` puts it under that node, `<Space>` `a` `l` `c` `s` `t` style it, Esc takes it all back) |
|
|
| `/` `n` `N` | search: titles, tags and bodies, fuzzily, with the note of each match beside it / the next match / the previous one |
|
|
| `Ctrl-o` `Tab` | back to where you jumped from / forward again (across documents) |
|
|
| `ma` `'a` `mA` | mark a node / go back to it / a capital mark: from any document |
|
|
| `gd` | follow a cross-link |
|
|
| `<Space>p` | a portal to another document (`:portal file`, or a new document's title) |
|
|
| Enter or `gf` `gu` | through a portal / up to the portals that lead here |
|
|
| `<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 |
|
|
| `:marks` `:jumps` `:registers` | what they hold: Enter goes there (or pastes) |
|
|
| `: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. Ctrl+click picks nodes one by one, and Ctrl+drag on the empty canvas
|
|
picks the ones in its rectangle. 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.
|