sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

office --host with the host table and self-check; board --reset; startup commands written down

Browse Source
This commit is contained in:
Sam
2026-11-12 11:33:47 +11:00
parent e02b04196f
commit 7b2cccf2ff
4 changed files with 142 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/STARTUP.md Normal file
View File

@@ -0,0 +1,68 @@
# Starting a project: the three commands and the rule
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
1. 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 `ssh` to itself.)
2. 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`.
3. 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.
4. On the machine that owns the folder: creates the Paperclip project if `--new` was given, or
adopts the existing one; writes `.harness/harness.toml`, `check.sh`, `NOTES.md` — never
overwriting anything that exists.
5. Creates the session if it is missing, on that machine's daemon.
6. 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>shell` is that pane here.
- Scripts resolve their own directory with `realpath`, so a symlinked wrapper still finds its
siblings.