From 91360c20923c8ce30829f19bcd192bb78a4c3918 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:15:28 -0300 Subject: build: cloud9 from the sibling checkout by path, until its client is published The command line's fs verbs are cloud9's new Fsys and verbs, which are not on sr.ht yet: build.zig.zon takes cloud9 from ../cloud9 (in the cli workspace, the c9-client line merged with main's two fs fixes the old pin 0702e33b had, so nothing it had is lost), and says the pin returns once that cloud9 is pushed. build.zig's one round of lazy fetches skips a dependency by path, which has no hash and is there already. pardes uses no API the old pin lacked but Fsys and verbs: no adaptation. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- build.zig | 6 +++++- build.zig.zon | 10 +++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/build.zig b/build.zig index d99f3985..7bd43795 100644 --- a/build.zig +++ b/build.zig @@ -250,7 +250,11 @@ pub fn build(b: *std.Build) void { // `b.dependency` below would end the configure to fetch its own alone. const ts = treeSitter(b, io, target, c_optimize, tree_sitter_grammars); inline for (.{ "cloud9", "vaxis", "ghostty", "uucode", "zstbi", "mvzr", "zstd", "xitdb" }) |name| { - if (!std.Build.package_map.get(@field(zon.dependencies, name).hash).?.available) _ = b.lazyDependency(name, .{}); + // One by path (cloud9, until its pin returns) is there already. + const dep = @field(zon.dependencies, name); + if (@hasField(@TypeOf(dep), "hash")) if (!std.Build.package_map.get(dep.hash).?.available) { + _ = b.lazyDependency(name, .{}); + }; } const cloud9 = b.dependency("cloud9", .{ .target = target, .optimize = optimize }).module("cloud9"); for (core_mods) |mod| mod.addImport("cloud9", cloud9); diff --git a/build.zig.zon b/build.zig.zon index ab6a693d..0c82860b 100644 --- a/build.zig.zon +++ b/build.zig.zon @@ -14,11 +14,11 @@ // `git@git.sr.ht:~gbrls/cloud9`; zig has no git+ssh support, so the // read-only HTTPS URL is what a manifest can carry. Re-pin with // `zig fetch --save=cloud9 git+https://git.sr.ht/~gbrls/cloud9#`. - .cloud9 = .{ - .url = "git+https://git.sr.ht/~gbrls/cloud9#0702e33bcfadf0abd9ccbaa8b681a19a84c332fe", - .hash = "cloud9-0.1.0-yt86qkExHgCRI7_eJsztRECamioWguBj2mTFsJ5N-AOn", - .lazy = true, - }, + // + // For now the sibling checkout, by path: the command line's `fs` + // verbs are cloud9's new Fsys and verbs, not published yet. The pin + // (it was 0702e33b) returns once that cloud9 is pushed. + .cloud9 = .{ .path = "../cloud9", .lazy = true }, // Pinned to the exact libvaxis commit ghostty is built against, so it // is compatible with ghostty's uucode configuration (the one we share // with it via `external_uucode` in build.zig). -- cgit v1.3 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: