diff options
| -rw-r--r-- | .agents/skills/pardes-9p/SKILL.md | 18 | ||||
| -rw-r--r-- | docs/fs.md | 16 | ||||
| -rw-r--r-- | src/fs-help.txt | 38 |
3 files changed, 48 insertions, 24 deletions
diff --git a/.agents/skills/pardes-9p/SKILL.md b/.agents/skills/pardes-9p/SKILL.md index 6fea5838..daf4c279 100644 --- a/.agents/skills/pardes-9p/SKILL.md +++ b/.agents/skills/pardes-9p/SKILL.md @@ -33,7 +33,9 @@ the `pid`, `version` and `panes` of a session new enough to serve it. `/mnt/9p/pardes` is the registry of posted sessions, mounted once for the machine. It is not the per-pane kernel mount the `Tty9p` builtin makes, which gives one pane's shell `$PARDES_MOUNT`; see [docs/v9fs.md](../../../docs/v9fs.md) -for that. Either mountpoint serves the same tree. +for that. Either mountpoint serves the same tree. A `9ns --unix SOCKET -- cmd` +mount exists only inside `cmd`'s private namespace; to share one, use the +registry (`9ns --mntgen`). A running session serves whatever binary started it. If a listing does not match this document, that session predates the change; restart it. @@ -59,7 +61,9 @@ $m/ctl the settings, one a line as a write takes them; write a setting or and the column words Delcol, Collapse, which act on that pane's column) go to $m/pane/<n>/ctl $m/commands every builtin: `Word`, `Word arg`, then `root` or `pane` (which ctl takes it) -$m/pane/new open it to make a pane, read names it; rmdir $m/pane/<n> closes it +$m/pane/new open it to make a pane (a scratch named <dir>/+New), read names it; + rmdir $m/pane/<n> closes it; closing a column's last pane leaves a +New there +$m/pane/<n>/errors write-only: text appended to the +Errors pane of the pane's directory $m/os/ the host filesystem ``` @@ -74,7 +78,8 @@ n=$(cat "$m/pane/new") # make one, take its serial printf 'text\n' > "$m/pane/$n/body" # append cat "$m/pane/$n/tag" # what its tagline offers echo notes.txt > "$m/pane/$n/name" # rename the buffer -echo Save > "$m/pane/$n/exec" # save it +echo Save > "$m/pane/$n/exec" # save it (or to its ctl) +echo Tty > "$m/pane/$n/ctl" # a terminal in its directory echo "/etc/hosts:3" > "$m/look"; cat "$m/look" # open a file, see where it landed rmdir "$m/pane/$n" # close it, dirty or not ``` @@ -104,7 +109,12 @@ active pane from the root and at that pane from `$m/pane/<n>/look` and `$m/pane/<n>/exec`. Reading any of them answers the serials the last command made, or the pane it focused or acted on. A command that fails is reported in the editor, not as a write error, so inspect the resulting pane, index, message -or screen; only a malformed line fails the write itself. +or screen; only a malformed line fails the write itself. A word no builtin +knows (a typo included) is typed into a terminal -- the pane itself if it is a +terminal at its prompt, else one in the pane's directory, made if need be -- +and is not reported as an error. Every refused 9P write adds an `err <serial|-> +<file>: <why>` record to `$m/log`; through a mount the write itself only says +`Invalid argument`. ## Edit through addresses, dot and the flag files @@ -59,6 +59,14 @@ private namespace: 9ns --unix "$PARDES_9P" -- sh -c 'cat "$NINE_MOUNT/index"' ``` +A `9ns --unix` mount lives in the private namespace of the command it runs, +and nothing outside that command sees it. The mount everyone on the machine +shares is the registry one, `9ns --mntgen` (default `/mnt/9p`): every running +editor posts itself there, so `/mnt/9p/pardes/<pid>/` is that editor's tree +for any process. A new pane made through `pane/new` is a scratch named +`<dir>/+New` until it is given a name, and closing a column's last pane +leaves such a `+New` in its place (`Delcol` closes the column). + For [Linux v9fs](https://www.kernel.org/doc/html/latest/filesystems/9p.html), use `version=9p2000,cache=none,access=any` and `trans=unix`, or `trans=tcp` with `port=5640`. Set `uname`, `dfltuid`, and `dfltgid` for the local user. @@ -194,7 +202,13 @@ same tree without leaving the process. - a line written to `exec` is a middle click: a command word from `src/builtins.zig` (`Save`, `Del`, `New`, `Newcol`, `Mount NAME DIAL`, `Unmount NAME`, `Dump`, `Restore`, `Msg TEXT`, `Find`, `Grep`, `Tty`, ...), - or anything else, which runs in the pane's terminal. + or anything else, which is typed into a terminal: the pane itself when it + is a terminal at its prompt, otherwise a terminal in the pane's directory + that is at its prompt, and failing both a new one made below the last + column. That is not an error, whatever the shell makes of the line, and a + misspelled builtin word ends up there too (whether it should is an open + question, docs/open-questions.md). `echo Tty > pane/<n>/ctl` makes a + terminal in that pane's directory outright. The root's pair clicks at the active pane and `/pane/<n>/look` and `/pane/<n>/exec` at that pane. Blank lines are skipped, and every other line diff --git a/src/fs-help.txt b/src/fs-help.txt index 3f7357d4..8db1e288 100644 --- a/src/fs-help.txt +++ b/src/fs-help.txt @@ -1,45 +1,45 @@ Pardes control filesystem ========================= README this guide -index one line per pane: serial, kind (text|term|pdf|image), dirty flag, name +index one line per pane: serial, kind (text|term|pdf|image), dirty flag, name (+New if unnamed) status pid, version and pane count look write a line: a right click on it at the active pane; read: the serials it touched exec write a line: a middle click, an editor command word or a shell line; read the same -log recent events: new/del/rename/save <serial> <name>, msg <serial|-> <text>; write follow to wait +log events: new/del/rename/save <serial> <name>, msg <serial|-> <text>, err <serial|-> <why> screen rendered screen as JSON, frozen from open to close listeners the session's dial addresses focus the serial of the pane with the keyboard; write a serial to give it the keyboard ctl the settings, one a line as a write takes them; write one, or Newcol, Dump; Kill QUITS commands every builtin: its word, arg if it takes one, and root or pane: which ctl takes it -pane/new open it to make a pane; the read answers that pane's serial -pane/<n>/ name body tag ctl addr dot limit data xdata sel dirty mark scroll - errors event look exec, and pty/ for terminals; rmdir closes it +pane/new open it to make a pane (named +New); the read answers that pane's serial +pane/<n>/ name body tag ctl addr dot limit data xdata sel dirty mark scroll errors (write-only: + appended to its directory's +Errors pane) event look exec, pty/ on terminals; rmdir closes os/, src/ the host filesystem; the editor's own sources (-Dembed-sources=true builds only) -Below, $m is the mount point (PARDES_MOUNT in a Tty9p shell; 9ns and 9p work too): +Below, $m is the mount (/mnt/9p/pardes/<pid> via 9ns --mntgen; PARDES_MOUNT in a Tty9p shell): cat $m/index which panes exist n=$(cat $m/pane/new) make a pane, take its serial echo /etc/hosts:3 > $m/look; cat $m/look open a file, see the pane it went to - printf 'text\n' > $m/pane/$n/body append to a pane (>| truncates first) - cat $m/pane/$n/name; echo notes.txt > $m/pane/$n/name read, then rename - echo Save > $m/pane/$n/exec save it; rmdir $m/pane/$n closes it + printf 'text\n' >> $m/pane/$n/body append to a pane (> replaces it all) + echo notes.txt > $m/pane/$n/name; echo Save > $m/pane/$n/ctl rename, then save it echo 'Msg hello' > $m/exec show text in the editor - echo '#0,#5' > $m/pane/$n/addr; printf NEW >> $m/pane/$n/data replace bytes 0..5 + echo '/^fn/' > $m/pane/$n/addr; printf NEW > $m/pane/$n/data replace what addr matched cp $m/pane/$n/addr $m/pane/$n/dot; cat $m/pane/$n/sel select the range, read it exec 3<>$m/log; echo follow >&3; cat <&3 what happened lately, then wait for more cat $m/pane/$n/event hold it open to own that pane's clicks - echo exec > $m/pane/$n/pty/ctl restart a shell; also winsize C R, sig INT + echo Tty > $m/pane/$n/ctl; cat $m/index a terminal in that pane's directory exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3 exit N then its output; or busy, or error printf 'ls\r' > $m/pane/$n/pty/data type into a terminal; pty/status: cols rows busy + echo 'sig INT' > $m/pane/$n/pty/ctl interrupt it; also winsize C R, and exec to restart Pitfalls, one each: - Each open of pane/new makes another pane (ls, stat, find never do); a reread names the same. - rmdir closes a pane even when it is dirty; index and pane/<n>/dirty show the flag. - addr, dot and limit read the same pair of offsets they take, so cp between them works. - dirty, mark and scroll read "0" or "1" and take "0" or "1"; truncating limit lifts it. - body: >> appends, > replaces it all. data: > replaces (and : > deletes) just the addr range. - tag reads path++text; writes append to the text (newlines too); truncating clears it, and dot or addr. + Each open of pane/new makes another pane (ls, stat, find never do); rmdir closes even a dirty one. + addr takes #n,#m or sam-style /regexp/ (^ $ per line); a failed one makes data refuse until reset. + data: > replaces just the addr range and : > deletes it; body: > empties the whole buffer. + tag reads the path, then the tag's own text; writes append to that text; truncating clears it. A terminal's body is a history snapshot frozen per open; pty/data is the live stream. - A failing command is reported in the editor and in log, not as a write error; a bad line fails the write. - pane/<n>/ctl: acme's status line + current; takes get, lock/unlock (on a held fd) and pane builtins (Del). + exec: a word no builtin knows is typed into a terminal in the pane's directory, and not an error. + A refused write reads as EINVAL through a mount: the log's err record says why. + lock/unlock on a pane's ctl need a held fd (exec 3>ctl); a lock someone holds fails: retry. + Closing a column's last pane leaves a +New in its place; Delcol closes the column. |