pencere

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 for page:answer(m, result), and page: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) is page:logged(): the lines in order, each { level =, text = }, as the page said them to its program, whichever program that is; they are not among page:calls(). A program of the app’s own writes them to its log behind view: , which page: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, and get_by_id for 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() and locator:get_by_… narrow it.
  • Doing: click, double_click, right_click, hover, drag_to, wheel, fill, and press("cmd+f"), type, paste, compose for the keyboard; advance, step, idle for 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. .never turns any of them round.
  • Structure: test.describe, before_each, after_each, test.skip, test.only (refused when CI is set), { timeout = }, test.temp_dir(), and a test file’s helpers in test/, 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_ACTIONS makes it an annotation; --junit writes 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 --jobs workers.

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 build copies 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 lua page 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, and PENCERE_TUI=0 or 1 does 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 runs fallback, 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-features is the one without) and copies itself for its own kind, which is what it makes unless --terminal or --no-terminal says the other: the other kind is pencere-no-terminal-<version>-<target> of the release, when the release carries it, or the file --runner FILE names (in a checkout, make runner TARGET=<target> KIND=no-terminal builds it). The kinds are not for a Cargo package (--no-terminal is refused for one): that program has the terminal’s screen or not by what it depends on.
  • Another target without its toolchain. --target fetches the same version’s runner of that target from the release (curl, checked against the release’s SHA256SUMS, kept in the cache), and --runner FILE uses 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 into target/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, and pencere new --lang ts|rust starts one. For a Rust program dev and build are 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.