Repository navigation
cli-v0.2.0
·
276 commits
to main
since this release
Added
- The
pencerecommand, released for the first time. It makes apps for
pencere: programs that show a view in the pane of the
terminal they run in. An app is a Lua program and a page;pencere buildmakes one executable of
it, which runs on any machine of its kind with nothing installed, and the same executable, with
no app inside it, ispencere.pencere new <name> [--lang lua|ts|rust] [--page lua|web]starts a project: Lua with a page of
the kit or with a web page (HTML and JavaScript, no npm and no build step), TypeScript or Rust.
Every project has one layout: the program insrc/program/, the page insrc/view/and the
pictures insrc/assets/; builds go todist/, and nothing generated is undersrc/.pencere devruns the app in this pane and runs it again when a script changes; when the page
or a picture changes, the view is closed and shown again without ending the program.pencere buildmakesdist/<name>, one file.--targetmakes it for another machine (Apple
silicon and Intel Macs, Linux on arm64 and x86_64, static, so on any distribution) without the
toolchain of that machine; a Mac's executable is signed ad hoc.--web DIRpacks a page from
the directory a tool built it into (a React page, say),--namenames the executable and the
app in its own messages,-osays where it goes.- A built app runs by itself, and
app --log FILEsends what it prints, and its errors, to a
file, since the terminal is under the view while it is up.
- A page of the kit can be several files. The page,
src/view/page.lua, mayrequirethe
other.luaand.luaufiles ofsrc/view/by Luau's own rules (require("./screens/logs"),
require("../parts/table"), a directory with aninit.luau), and nothing outside the view: the
scripts go into the view's bundle with the paths the page writes them by, typed as scripts, in
pencere devand in a built app alike.pencere devshows the view again when one of them
changes, andpencere buildrefuses one that does not compile. - How to get it. One line installs the newest release in
~/.local/bin
(curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh: see the
README), after checking the file against theSHA256SUMSof its release. Each release carries
the four executables, namedpencere-<version>-<target>, with their sums; they are built by the
release workflow, which attests where each was built (gh attestation verify).
cargo install --git https://github.com/bateri/pencere pencere-cli --lockedbuilds it from the
source. - What an app can do, with
require("pencere")and nothing else to install:serveshows the
view (a page of the kit, a web page with anaccessfor what it may reach, or both in the order
the app prefers) and answers its calls and feeds its topics;process.spawnandprocess.run
start programs;handoffgives the terminal to a program, such as the person's shell, and shows
the view again when it ends;fs(withwatch, which polls nothing),json,hash.sha256,
text,regex,time,os,env,args,path,io.write,io.read_lineandexit.
There is one thread and one loop for the terminal, the timers and the pipes of the programs an
app starts;process.run,time.sleepandservewait without holding it. - For an app that is a filter in a pipeline, such as a picker:
serve{ filter = true }shows the
view on the controlling terminal whatever the standard streams are, so that stdin and stdout stay
the pipeline's;io.read_stdin(on_data[, on_end])reads standard input as it arrives, a piece at
a time and exactly as written, without holding the app (:stop(),:active(),:wait());
io.is_terminal("stdin" | "stdout" | "stderr");close_view()ends the view from the app's
side, so that what was chosen is written with the pane given back; andprocess.spawn/run
withsession = truestart a program with no controlling terminal, for a command that must not
reach the pane. - For an app that edits files, such as an editor:
fs.create(a new file, where nothing is: it
does not truncate a file or write through a link),fs.rename,fs.writable,linkin
fs.list;process.runwithraw(output that is not text, exactly as written) and
max_output;json.null;os.hostnameandos.username;text(names in the order people
read them, and a text counted in UTF-16 units);serve{ icons }(an icon for each background and
size).
Changed
cli-v0.1.0was not this command. That release was the TypeScript@pencere/cli, which
this replaces: a TypeScript program shows its view with@pencere/sdknow, and
pencere new --lang tsstarts one. The command's first release is 0.2.0.
Security
- A program that
process.spawnorprocess.runstarts runs in a group of its own, andkill, a
timeout,max_outputand the end of the app signal the whole group, so a shell's pipeline does
not outlive its shell.max_outputcounts the bytes as they are read, line ends included, and
keeps nothing past the limit. An app that shows nothing and is ended by ⌃C or a hangup asks the
programs it started to end first, andon_exitis told whether the program was ended for saying
too much. regexuses an engine that does not backtrack, so a pattern a person typed or a page sent cannot
hold the app. Back-references and look-ahead or look-behind are refused ("this pattern uses a
back-reference, which search does not support");whole_wordis checked in code around the
match.pencere buildrefuses a Mac runner without the room in its header for the app's section, and a
Mac's runner is linked with that room, so an app cannot be written over its first functions.