4.2 KiB
Starting a project: the commands and the rule
These commands are on your PATH as office, board, merge, review, triage and
project-reset. Each is a two-line wrapper in ~/.local/bin that runs the real script in this
repository — a wrapper, not a symlink, because a symlinked script resolves its own directory to
~/.local/bin and then cannot find its siblings. The previous project's wrappers were moved to
~/.local/bin/.old-harness/, not deleted.
Replaces the previous project's four commands. There are three now, and one rule that removes most of the confusion.
The rule
The folder and the session live on the same machine. If you are typing inside a session, on the machine that owns the folder, you type
bin/office <folder>and nothing else.
--host exists for exactly one case: the folder is on a different machine from the shell you are
typing in. It is stated once; after that the project file remembers it.
The three commands
| What you want | Command |
|---|---|
| adopt a folder | bin/office <folder> --project "<Paperclip project name>" |
| adopt a folder Paperclip has never seen | bin/office <folder> --new "<Name>" |
| adopt a folder that lives on another machine | bin/office <folder> --project "<Name>" --host nixos-desktop |
| repair or rebuild the panes | bin/board, bin/board --replace, bin/board --reset |
| close everything and start again | bin/project-reset <folder> |
Nothing else is needed. In particular you do not create the session by hand any more: the
previous design needed tuios new --host … because office could not create a session. This one
can, through the daemon's own verb, so the second command is gone.
What bin/office does, in order
- Reads the folder. If another machine is named, checks first whether that name is this
machine, and runs locally if it is. (The previous version once tried to
sshto itself.) - Resolves a host name to an address ssh can reach:
nixos-desktop/.13→192.168.20.13,sam-4screen-desktop/.27→192.168.20.27,sam-thinkpad/.51→192.168.20.51. - If it really is another machine: tests the login with
ssh -o BatchMode=yes <address> true, then runs the same command there, and prints how to attach. - On the machine that owns the folder: creates the Paperclip project if
--newwas given, or adopts the existing one; writes.harness/harness.toml,check.sh,NOTES.md— never overwriting anything that exists. Before the remote run it copies this folder's commands to the other machine at~/.local/share/paperclip-harness/bin/and leaves a short~/.local/bin/officethere, so nothing has to be installed by hand. On.27and.51~/.local/binis not onPATHyet, so there the command is called by its full path. - Creates the session if it is missing, on that machine's daemon.
- Builds the eight panes, in order, each pane claimed by workspace name.
The last step it cannot do is show you the session. A program may not move your client: the
daemon refuses switch-session from a pane. Switch with TUIOS's own session switcher, or
tuios attach --host <machine> <session>.
The three rebuild levels
| Command | What it does |
|---|---|
bin/board |
creates what is missing, closes nothing |
bin/board --replace |
closes this project's panes, then builds all eight again |
bin/board --reset |
closes every pane in the session, waits for none to remain, clears the workspace names, then builds |
--reset exists because --replace on a half-built session can run out of workspace slots and
leave pages missing.
Inside a pane, R in Repair>repair rebuilds everything; B only adds what is missing.
Traps this design keeps from the previous one
- A pane's command must carry the project, or a rebuild shows the wrong one.
- Compare a host name against this machine's own names and addresses before ssh, or you log in to yourself.
- Never store a workspace number; TUIOS deletes an emptied workspace and renumbers the rest.
- A pane that never exits keeps a workspace alive.
Shell>shellis that pane here. - Scripts resolve their own directory with
realpath, so a symlinked wrapper still finds its siblings.