From 2e6777e06e3f3e9d59ec847b98e0cb676d04296a Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:15:28 -0300 Subject: main: the command line is commands that describe themselves, over the tree that does The user: "the cli should be like a living documentation, similar to 9p and maybe even share the source code but with different sinks", rex's CLI the model. pardes [flags] [FILE] opens, starts or pages as it did; a first word naming a command is that command (a file named so is ./ps, or after --): ps, attach [NAME], kill NAME|--all, new [flags] [FILE] for sessions; do WORD [ARG] and words [GROUP] for the builtins; fs VERB [PATH] for the tree; help [CMD|WORD|PATH], completion SHELL, skill, version. One definition, several sinks. main.zig's `cmds` (an EnumArray over the Cmd enum: group, args, first-screen line, doc, examples, see-also) is both what args[1] is matched against and every command's help; `flags` (over the Flag enum: what it takes, its doc, session/open/old) is both the flag loop's parser and `help new`. The 70-line help_text and the flag enum kept apart from it are gone; every flag behaves as before, and --ps, --attach[=NAME], --kill=NAME, --kill-all, -h/--help and --version are the commands' old spellings for a release (EDITOR='pardes --wait' unchanged). What a word or a file does is the tree's to say: words, help WORD, help PATH, fs and the completions read /commands and /README over cloud9's Fsys, from the session (-s NAME, else $PARDES_9P, else the only one whose socket answers) or, with none, from a core this process makes (Pardes.create, never stepped: no shell, file or socket) and serves on one end of a socket pair to an Fsys on the other (`Here`: cloud9's engine, one thread), so both are the same client over the same tree. With no session, fs ls/stat/help/complete and a read of README, commands or ctl answer; a read of anything else, or a write, says it is a running session's and how to start one. do picks the ctl by /commands' scope (a pane's word needs $PARDES_PANE or -p N) and prints a refusal in the session's words. completion prints a bash, fish or zsh script that asks `pardes completion -- WORDS` back. skill prints src/skill.txt, the recipes and traps, which leaves the inventory to pardes help. version adds the 9P the tree speaks. The reference's "The pardes command" includes docs/typ/command-line.txt, `pardes help --all` (never a session's), which the builtins-json step (-Dplatform=tui) now writes too; a main.zig test fails when it is stale. test/process/cli.zig: five cases through the binary, with and without a session; flags' eight pass unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- build.zig | 15 +- docs/typ/command-line.txt | 300 ++++++++++++ docs/typ/reference.typ | 13 + src/CHANGELOG.md | 16 + src/main.zig | 1114 +++++++++++++++++++++++++++++++++++++++------ src/skill.txt | 47 ++ test/process.zig | 2 +- test/process/cli.zig | 144 ++++++ test/process_test.zig | 1 + 9 files changed, 1499 insertions(+), 153 deletions(-) create mode 100644 docs/typ/command-line.txt create mode 100644 src/skill.txt create mode 100644 test/process/cli.zig diff --git a/build.zig b/build.zig index 7bd43795..71c8637b 100644 --- a/build.zig +++ b/build.zig @@ -878,7 +878,7 @@ pub fn build(b: *std.Build) void { // `typst compile` reads it too; a unit test fails when it is stale. // A terminal build writes builtins-tui.json and a window build // builtins-gui.json; style.typ merges the two into one glossary. - const builtins_json_step = b.step("builtins-json", "rewrite docs/typ/builtins-.json from the builtin registry (-Dplatform=tui or gui)"); + const builtins_json_step = b.step("builtins-json", "rewrite docs/typ/builtins-.json from the builtin registry, and with tui docs/typ/command-line.txt from pardes help --all (-Dplatform=tui or gui)"); if (requested_platform == .tui or requested_platform == .gui) { const gen = b.addExecutable(.{ .name = "pardes-gen-builtins-json", .root_module = b.createModule(.{ .target = target, @@ -1184,6 +1184,19 @@ pub fn build(b: *std.Build) void { .root_module = root_mod, }); installHome(b, exe, home_bin); + // docs/typ/command-line.txt: `pardes help --all`, the commands' + // help and the tree's README as this build prints them (never a + // session's), which the reference's "The pardes command" shows; + // main.zig's test fails when it is stale. The terminal's build + // writes it, the window's prints the same. + if (requested_platform == .tui) { + const run_help = b.addRunArtifact(exe); + run_help.addArgs(&.{ "help", "--all" }); + const update = b.addUpdateSourceFiles(); + update.addCopyFileToSource(run_help.captureStdOut(.{}), "docs/typ/command-line.txt"); + builtins_json_step.dependOn(&update.step); + for (doc_renders) |r| if (r) |run| run.step.dependOn(&update.step); + } // The addons, a step each: the default install is the binaries // alone, and `zig build image pdf` (or `addons`) puts the libraries // where the start scan finds them, /lib/pardes/addons (and diff --git a/docs/typ/command-line.txt b/docs/typ/command-line.txt new file mode 100644 index 00000000..21b218c7 --- /dev/null +++ b/docs/typ/command-line.txt @@ -0,0 +1,300 @@ +pardes: an editor, a terminal multiplexer, and the file tree that scripts both. + +Usage: + pardes [flags] [FILE[:LINE] | DIR | -] open, start a session, or page stdin + pardes COMMAND [ARGS] [-s NAME] a file named like a command: pardes ./ps + +Open: + FILE[:LINE] open it; in a pane, in that pane's session + -w, --wait FILE open it, return when its pane closes (EDITOR='pardes -w') + - stdin into a +Pager, its colours kept + DIR start in it + +Sessions: + ps the daemon's sessions, their clients and shells + attach [NAME] show a detached session here (HOST:NAME: over ssh) + kill NAME end a session and its shells (--all: every one) + new [flags] [FILE] start one: --detach=NAME --9p=NAME -n 3 (help new) + +Words: + do WORD [ARG] run a builtin at this pane, or the session's: do Newcol + words [GROUP] the builtins by group, or one group's: words column + +Files: + fs VERB [PATH] ls read write ask follow stat help complete, on the session's tree + +Self: + help [CMD|WORD|PATH] this, a command, a builtin, or a file of the tree + completion SHELL bash, fish or zsh + skill the guide an agent reads + version this build, its session wire and its 9P + +Flags: + -s, --session NAME the session to act on ($PARDES_9P, else the only one) + -p N the pane, for do ($PARDES_PANE) + +The old spellings --ps, --attach[=NAME], --kill=NAME, --kill-all, -h and +--version still work, for a release. + +== pardes help ps + +What the per-user daemon keeps: each session with its name, pid, kind +(tty or gui) and whether one is attached; under it its clients and its +shells; then the shells no session holds, which Adopt takes. /sessions +is the same list, read from inside a session. + +Usage: + pardes ps + +Examples: + pardes ps every session, client and shell + +See also: attach, kill, /sessions + +== pardes help attach + +Show a detached session here: in this terminal for pardes, a window +for pardes-gui. Bare, the one detached session (with none, the one +session). One attached already, or of the other kind, is joined as a +client. HOST:NAME is a client of session NAME on another machine, +over `ssh -L` to its pardes-replica.sock ($PARDES_SSH: the ssh +command, default ssh; $PARDES_REMOTE_RUNTIME: its runtime directory, +if not this one's path); SOCK:NAME goes through a socket forwarded +already (a path, with a '/'). Returns when the session detaches or +ends. + +Usage: + pardes attach [NAME] + +Examples: + pardes attach the one detached session + pardes attach notes the one started with --detach=notes + pardes attach box:notes on host box, over ssh -L + pardes attach /run/x.sock:notes through a socket forwarded already + +See also: ps, kill, new --detach, the Detach word + +== pardes help kill + +End session NAME (its --9p or --detach name, else its pid) and its +shells: TERM, then KILL 2 s later. Unsaved changes are lost. --all +ends every session and every shell the daemon keeps. + +Usage: + pardes kill NAME + +Examples: + pardes kill notes the session started with --detach=notes + pardes kill --all every session and shell + +See also: ps, attach + +== pardes help new + +Start a session here, even in a pane of another: in this terminal for +pardes, a window for pardes-gui, or with --detach none until one +attaches. Bare `pardes` takes the same flags, and starts one unless +it is in a pane (where it hands its FILE to that session). + +Usage: + pardes new [flags] [FILE] + +Flags: + --tty start as one shell pane already in tty mode + -n COUNT shell panes to start with: 1 (default) or 3 (classic); a FILE boots just that file + --tty-toggle KEY Ctrl-KEY toggles tty and editor mode + -l DUMP load a dump of another instance (see Dump) + --nested a session of its own in a pane of another, serving none of its children + --9p=NAME name the 9P socket (else the --detach name, else the pid); under $XDG_RUNTIME_DIR, else ~/.local/state/pardes: a directory of yours alone + --9p-tcp=tcp!IP!PORT also serve 9P there, a numeric address + --mount=NAME=DIAL a 9P session or Unix/TCP endpoint under /n/NAME; repeat for more; os and self are reserved + --geometry=WxH[+X+Y] the window's size in points, and where it goes where the display lets a window say (X11) + --detach[=NAME] no terminal (no window) until one attaches; panes, shells and files stay; NAME (one path component) rather than the pid. One pardes --daemon per user keeps sessions (PARDES_DAEMON=off: none) + -w, --wait in a pane, hand FILE to its session and return once its pane is deleted: 0, or 1 if the session goes (EDITOR='pardes --wait') + -- the end of the flags: pardes -- -name opens -name + +Examples: + pardes new a session here, its shell pane in tty mode + pardes new --detach=notes one with no terminal, named notes + pardes new -n 3 src/ three shell panes in src/ + pardes new --mount=peer=notes with session notes under /n/peer + +See also: attach, kill, --nested + +== pardes help do + +Write WORD and its ARG to the ctl that takes it, as the session's +/commands says: the root's /ctl for a session's word, a pane's +pane/N/ctl for a pane's, that pane being this shell's ($PARDES_PANE) +or -p N. A refusal prints the session's own words, and the exit is 1. +The session is -s NAME, else $PARDES_9P, else the only one running. + +Usage: + pardes do WORD [ARG] + +Examples: + pardes do Newcol an empty column + pardes do Save -p 3 save pane 3 + pardes do Edit ',x/foo/c/bar/' -p 3 sam's Edit on pane 3 + pardes do Wrap -s notes at session notes + +See also: words, help WORD, /commands + +== pardes help words + +The session's builtins, as its /commands lists them, grouped by the +first key after the leader (SPC f is file, SPC c column): with no key, +a setting, a session's word (its root ctl's) or a text word (a +pane's). An addon's words are the addon group. With no session, the +ones this build has. + +Usage: + pardes words [GROUP] + +Examples: + pardes words every builtin, by group + pardes words column the column words + +See also: do, help WORD, /commands + +== pardes help fs + +The session's file tree, through a 9P client in this binary: the +files a mount or 9p(1) reaches, with a refusal in the session's own +words (a mount says only EINVAL). With no session, ls, stat, help and +complete, and a read of README, commands or ctl, ask a core made in +this process; the rest are a running session's, and say so. + +Usage: + pardes fs VERB [PATH] + +usage: fs ls [PATH] the names in a directory, a / after each directory + fs read PATH the file, to its end (a held read streams) + fs write PATH [WORDS...] the words and a newline, else stdin, as > would + fs ask PATH WORDS... write the words and read the answer on the same open + fs follow PATH [WORDS...] ask, or read: what comes, as it comes, for as long + fs stat PATH mode length uid gid mtime name + fs help [PATH] what the tree's README says of PATH + fs complete [PREFIX] the paths that go on from PREFIX, for a shell + +Examples: + pardes fs ls pane/1 what a pane serves + pardes fs read index a line per pane + pardes fs write pane/3/ctl 'Edit ,x/foo/c/bar/' a write, refused in words + pardes fs ask pane/3/pty/run make exit N, then the output + pardes fs follow log follow events as they come + +See also: help PATH, /README + +== pardes help help + +Bare, this map. A command: what it does, with examples. A builtin: +its /commands line, its key, and how to run it. A path of the tree: +what the tree's README says of it and of what is under it. --all: +every command's help and the README whole, as this build has them +(never a session's), which the reference prints. + +Usage: + pardes help [CMD|WORD|PATH] + +Examples: + pardes help attach a command + pardes help Newcol a builtin + pardes help pane/3/addr a file of the tree + +See also: words, fs help + +== pardes help completion + +A completion script for SHELL, printed, never installed. It asks this +binary back for each word (`pardes completion -- WORDS`): commands, +the builtins after do, sessions after attach and kill, the tree's +paths after fs. + +Usage: + pardes completion SHELL + +Examples: + pardes completion fish | source in fish, for this shell + source <(pardes completion bash) in bash + source <(pardes completion zsh) in zsh + +== pardes help skill + +The guide for an agent that drives pardes, from this binary, so it +matches what it runs: recipes and traps. What is there it leaves to +`pardes help`. + +Usage: + pardes skill + +Examples: + pardes skill + +== pardes help version + +This build's version; the semantics a replica must share with its +session; the 9P its tree speaks. + +Usage: + pardes version + +Examples: + pardes version + +== the old spellings + + --attach[=NAME] pardes attach NAME + --ps pardes ps + --kill=NAME pardes kill NAME + --kill-all pardes kill --all + -h, --help pardes help + --version pardes version + +== pardes help /: the tree's README + +Pardes virtual filesystem +========================= +README this summary; the pardes book's Scripting and Reference chapters have the rest +index a line per pane: serial kind(text|term|cmd|pdf|image|an addon's) dirty name column; names hold blanks: rsplit(maxsplit=1) +status pid, version and pane count +look write a line: a right click on it at the pane with the keyboard; read: the serials it touched (this open's) +exec write a line: a middle click, a builtin or a shell line; read the same (every exec file) +pager write a directory: its one +Pager, made or emptied; read the same open: its serial (pardes -) +log events: new del rename save newcol delcol run exit send ask answer changed dump restore restored restoredcol msg err +screen the rendered screen as JSON, frozen from open to close +listeners the session's dial addresses +sessions the pardes daemon's, as pardes --ps: daemon ; session tty|gui attached|detached ; shell ; orphan +focus the serial of the pane with the keyboard (empty on a column tag); write one to give it the keyboard +kbdin write runes: keys typed at the pane with the keyboard, done before the write answers (\x1b Esc, \n Enter) +mousein write `m col row buttons` (1 left, 2 middle, 4 right): the mouse as it now is; m 10 5 4, m 10 5 0 is a right click +ctl settings a line; or Newcol, Dump [export f], Restore [label|f], Exit (refuses once over unsaved panes), Kill [w], size C R +commands every builtin: word, arg, root|pane|both (the ctl that takes it), -- what it does; addons: the kinds of pane here +recent files opened lately, closed ones too: open|closed +dumps the dumps the state file keeps, the newest first: