The pencere command
pencere
The command that 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, and pencere build makes one executable of it that runs anywhere its kind of machine does.
Install
curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh
It puts the newest release of the command in ~/.local/bin (no sudo) after checking the file
against the SHA256SUMS of that release, and tells you if the directory is not on your PATH.
PENCERE_INSTALL=<dir> installs elsewhere and PENCERE_VERSION=<x.y.z> a release other than the
newest. The files are those of the releases cli-v<version> of the repository
(releases), one for each of macOS and Linux on arm64
and x86_64, named pencere-<version>-<target>.
With Rust, cargo install --git https://github.com/bateri/pencere pencere-cli --locked builds it
from the source (the program is called pencere).
pencere upgrade replaces the command with the newest release later (--check only looks), checked
the same way; one that Cargo installed is replaced by Cargo (cargo install … --force).
A file downloaded with a browser is quarantined by macOS, which will not run it:
xattr -d com.apple.quarantine <file> lifts that. A file curl fetches, which is what the line
above does, is not.
Use
pencere new hello # a project: src/program/, src/view/, src/assets/
cd hello
pencere dev # run it in this pane; a change to a file under src/ runs it again
pencere build # dist/hello, one file
pencere build --target x86_64-unknown-linux-musl # the same app for a Linux machine
pencere build --no-terminal # the smaller kind, see "What it is, and is not"
pencere test # its tests: the page under a host with no screen (see Testing an app)
pencere new makes the project in another language, or with another view:
pencere new hello --lang ts # the program in TypeScript (--lang rust: in Rust)
pencere new hello --page web # a web page for the view (a program in TypeScript has one unless --page lua)
The same two commands work on a program written in Rust (pencere new hello --lang rust, a Cargo
package): pencere dev builds it with Cargo and runs it in the pane, shows the view again without
ending the program when the page or a picture changes, and builds and runs it again when anything
else does (outside what its tools keep: what is hidden, target, node_modules, and the dist at
the top); pencere build builds it with cargo build --release and copies it to dist/. The page
is the same page of the kit, in src/view/, carried into the program by its build script.
Releasing an app
A terminal that follows an app on its person’s behalf (spec/draft/apps.md) needs two files beside
the executable of each target: app.json, which names the release and the file and digest of every
target, and app.json.sig, the author’s signature over it. Two commands make them:
pencere key # once: makes the signing key, or prints the public half of the one there is
pencere dist 0.2.0 # dist/: a file per target, SHA256SUMS, app.json and app.json.sig
pencere key writes the secret half to ~/.config/pencere/signing.key (readable by you alone,
never inside a project, never over a key that is there) and prints the public half, which is what
app.json names in key. Keep a copy of the secret half somewhere safe: whoever has it can
release as you, and when it is lost the people who follow your app are asked again before they
follow a release signed with another key. --key FILE or PENCERE_SIGNING_KEY name another file.
pencere dist VERSION makes the executable of every target as pencere build does (a Lua app), or
takes the ones you have made: --files DIR names a directory that has <name>-<version>-<target>
for each target, which is how a Rust program is released, since each target is built on its own
machine. A target may have a second file, <name>-no-terminal-<version>-<target>, the program
built without a terminal in it (smaller, for a terminal that draws the page itself): SHA256SUMS
names both, and app.json names the one without a terminal for the target, the only one otherwise.
The files, SHA256SUMS, app.json and app.json.sig are written to dist/ (to DIR,
with --files). What the release needs, the protocol versions and the kinds of view, is not typed:
dist starts the file of this machine’s target (the one app.json names for it: the one without a
terminal where there is one) on a pty of its own, in an empty folder with a home of its own, reads
the hello the program sends as it starts and ends it. --describe-args gives a program that needs
arguments to start the ones it needs, and --describe-with FILE names another program to ask when
this machine’s target has no file.
--opens file,folder says in app.json that the program takes the path of a file, of a folder or
of both as its last argument, with +LINE before a file’s path when a line is meant, so that a
terminal can offer the program for the paths a person opens. Without it the member is not written
and the release is the same file as before.
The files are expected at https://github.com/<owner>/<repo>/releases/download/v<version>/ of the
repository’s origin (--tag changes the tag, --base the whole address). The earlier releases
that app.json lists are made from the app.json the repository released before (its
releases/latest/download/app.json, or --previous ADDRESS-OR-FILE; --previous none for a first
release); one signed with another key stops the command. dist does not upload anything:
attach all of its files to the release.
Testing an app
pencere test # every test/**/*_test.lua of the app
pencere test test/page_test.lua:12 --grep clock --reporter tap --junit report.xml
A test is Lua that opens the page of the app under a host with no screen — the page engine, its
editors and the kit’s interpreter, laid out and scrolled as a terminal does, with a clock the test
moves — and does to it what a person does, looking at what it shows. It needs no browser, no
terminal and no Node. pencere test runs the app’s tests with pencere-test, a program of its own
(it hosts the view under no terminal and links the kit with its code generator, which the command
copied into every app does not): the one beside this command, or
this version’s release file (fetched once, checked against SHA256SUMS, kept), or the one
PENCERE_TEST names. pencere new makes a project with its first test.
local test = require("pencere.test")
local expect = test.expect
test("the button shows what the program answers", function()
local page = test.open({
calls = { hello = function(params) return { message = "Hello, " .. params.name .. "!" } end },
})
expect(page):to_say("Press the button.")
page:get_by_role("button", { name = "Greet" }):click()
expect(page):to_say("Hello, pencere!")
expect(page):to_have_called("hello", { name = "pencere" })
end)
- The program of the page is a stand-in made of the calls the test answers (
calls = { m = fn }; a call with no handler waits forpage:answer(m, result), andpage:push(topic, value)speaks to what the page listens to), or the app’s own: a Lua program runs in the test’s process, in its own environment (env,cwd,args; the test’s process is never touched), a Cargo package is built once and run on a pty, and any other (command = { "deno", "run", "-A", "src/program/main.ts" }) is run on a pty as a terminal runs it. A page with a program of its own is looked at again until it shows what is expected (within, 5 seconds); with a stand-in, what is expected is there or not. - What the page prints (
print,warn) ispage:logged(): the lines in order, each{ level =, text = }, as the page said them to its program, whichever program that is; they are not amongpage:calls(). A program of the app’s own writes them to its log behindview:, whichpage:log()reads. - Finding things as a person does, not by the page’s own names:
get_by_text,get_by_role(button, field, editor, link, checkbox, heading …),get_by_field, andget_by_idfor what the page names. A locator looks again when it is used, wants exactly one match, and says what is on the page when there is none;:nth(i),:first(),:last()andlocator:get_by_…narrow it. - Doing:
click,double_click,right_click,hover,drag_to,wheel,fill, andpress("cmd+f"),type,paste,composefor the keyboard;advance,step,idlefor the clock, which only the test moves (the page’s; the program’s is the machine’s). - Looking:
expect(page):to_say,to_have_called,to_have_subscribed,to_have_link,to_have_focus;expect(locator):to_exist,to_have_count,to_be_checked,to_have_value…;expect(value):to_equal(with the difference),to_contain,to_match,to_throw..neverturns any of them round. - Structure:
test.describe,before_each,after_each,test.skip,test.only(refused whenCIis set),{ timeout = },test.temp_dir(), and a test file’s helpers intest/, found before the program’s own modules. - A failure says where, what the page said, and keeps the page: a picture
(
.pencere/test/<file>/<test>/page-1.png, each character a box, the same on every machine), its words, its messages and what the program printed.GITHUB_ACTIONSmakes it an annotation;--junitwrites a report the CI systems read, with the pictures attached. - A test that never ends is cut off at its timeout (30 seconds,
--timeout), and a file whose process dies costs that file; the files run on--jobsworkers.
An app of the simple form (its files packed as they lie) does not pack test/, so a program module
of that form cannot live in a directory of that name.
What it is, and is not
- An app is a program. It runs with the rights of whoever starts it, as any program does:
it reads and writes files, starts programs, and sees the environment. Nothing in it is
sandboxed; the view is (it reaches nothing but its program). There is no network client in the
standard library — a program that wants the network runs
curl, and the person can see which. - One file.
pencere buildcopies the runner and writes the app into it as a section of the executable, so the file is the interpreter, the script, the page and the pictures. A Mac’s file is signed ad hoc, in the process; a Linux one is static. - Two kinds of app. The command comes with the terminal in it or without it, and the app is a
copy of the command that built it. With it (the default), an app started in a terminal that hosts
no views but speaks the Kitty graphics protocol opens its
luapage there as pictures: its handlers and its program are the app’s, the same page, with the mouse and the keyboard and the colours of the terminal’s theme. The runner carries the interpreter the build compiled (no code generator) and the PDF reader.serve { tui = false }keeps an app from this, andPENCERE_TUI=0or1does the same or forces it for a person. Without it (pencere build --no-terminal) the file is smaller and links none of the kit: the app runsfallback, as a terminal that hosts no views gets from a program that has nothing of its own. A command is of one kind (a command built with--no-default-featuresis the one without) and copies itself for its own kind, which is what it makes unless--terminalor--no-terminalsays the other: the other kind ispencere-no-terminal-<version>-<target>of the release, when the release carries it, or the file--runner FILEnames (in a checkout,make runner TARGET=<target> KIND=no-terminalbuilds it). The kinds are not for a Cargo package (--no-terminalis refused for one): that program has the terminal’s screen or not by what it depends on. - Another target without its toolchain.
--targetfetches the same version’s runner of that target from the release (curl, checked against the release’sSHA256SUMS, kept in the cache), and--runner FILEuses one you have. A pencere that is not released, a commit of it, has no runners to fetch:make runner TARGET=<target>in a checkout of it builds one intotarget/runners/(Docker for Linux, a Mac for macOS). - Other languages need nothing of this to run. The protocol is bytes; the TypeScript SDK
(
@pencere/sdk,deno compile) and the Rust library (pencere) are the same program in other words, andpencere new --lang ts|ruststarts one. For a Rust programdevandbuildare a convenience over Cargo, which does the compiling: the runner is not in it.
The specification is here. Apache-2.0.
This page is a part of cli/README.md of the repository.