Pi Pocket 0.23.0: in-app updates with rollback, and phone layout fixes

Pi Pocket can now update itself from the app, and goes back by itself when a new version does not start. On a phone, Stop now stays in the message box while Pi works, and every rail button can be reached.

Important

To update: pull (no npm install is needed), then quit Pi Pocket and start it again (npm start). Menu → Restart server is not enough this once: the launcher must start again to get its rollback. There is no migration and no new dependency. Details under Updating.

Highlights

• Update Pi Pocket from the app. Menu → Update Pi Pocket shows the newest release and its notes, and updates and restarts with one tap. If the new version does not start, Pi Pocket goes back to the one before by itself.

New

• Update Pi Pocket. For a git checkout run with npm start; the owner's alone.
  • A notice says once when a new version is out. Pi Pocket looks 2 minutes after it starts, then every 6 hours.
  • The sheet says what stands in the way: changes that are not committed, local commits, a Node.js or git that is too old, or a file of yours where the release adds one.
  • It installs new packages only when the release changes them, and puts them in place before the restart.
  • A release whose notes have a warning asks you to confirm that you read it, and is not undone by itself. So does a release whose notes Pi Pocket could not read because GitHub did not answer.
  • Install new versions by themselves is off by default (Menu → Extensions → Installed → Pi Pocket updates). It waits until no session has worked for 10 minutes, and never takes a release with a warning, or one that failed before.
  • Nothing of yours is overwritten: if an update stops part way, anything that is not Pi Pocket's own goes to .pocket-update/kept/, and the message says where.

Fixed

• Every rail button can be reached. Extensions' rail buttons no longer hide in a small box that scrolls on its own: the whole rail scrolls when it does not fit, and fades at the edge where more is. The folded rail keeps up to a third of the window for its sessions. (#156)
• Stop stays in the message box on a phone. Attach steps aside on a 360 px screen while Pi works, and the labels of Steer, Queue, and Interrupt shorten before Stop leaves the box. (#154, by @piromagnus)
• Send stays in the message box with extension buttons. On a phone, buttons that extensions add take a line of their own under the row when they would push Send or Stop out. (#159)
• The drawer fits a phone on its side. Its foot no longer falls below the screen. (#159)

Security

• Updates trust the release repository. An update runs the release's code and npm ci, as a manual git pull and npm install do. Only the owner can start one. The release repository must be an https, ssh, or local address, so its setting can never pass git an option.

For theme and extension authors

• New reserved name: updates. A drop-in named updates.ts no longer loads; rename it.
• Rail buttons have no height limit of their own. All of a module's rail buttons show, and the rail scrolls as a whole when they do not fit. (#156)
• pocket.composerButton buttons take a line of their own under the row in a narrow message box: 2 or more up to 480 px wide, 1 up to 340 px. A single button in a box from 341 to 480 px steps aside while Pi works, as the model chip does. (experimental, #154, #159)
• Release notes drive the updater. A [!WARNING] or [!CAUTION] alert makes the app ask before it updates, and keeps it from installing or going back by itself. Notes the app cannot read count as such an alert. Release notes now say to put every manual or one-way step there.

Updating

1. git pull in your checkout. No npm install is needed: the packages did not change.
2. Quit Pi Pocket (q in its terminal, or stop its service), and start it again (npm start, or systemctl start).
3. From 0.23.0 on, Menu → Update Pi Pocket installs the next releases. Under systemd, the service user must own the checkout, or the sheet only tells you a new version is out.

Going back to 0.22.0 is safe: it ignores .pocket-update/ and the new module's settings.

How this release was checked

• npm run check, npm run lint, Prettier, the docs-site build, and npm test on the release branch: 625 of 626 pass. One artifact UI test that this release does not touch timed out under load, and passed 3 times out of 3 alone. 30 new tests, in updates.test.ts and updates-routes.test.ts, and more in extension-loader and extension-ui.
• Updates (#153).

  • End to end with the real launcher on a throwaway clone: an update with a real npm ci and package swap, and a broken release rolled back by itself.

  • Checked at phone size: the sheet before an update, during it, and after a rollback.

  • A core review in 7 rounds found ways an update or a rollback could lose an owner's file: ignored files, a branch switched meanwhile, folders, links, clean filters, and files that only the old version tracks. All are fixed, each with a test.

  • A final swarm of 4 reviewers (security, processes, git edge cases, the experience and its tests) found:

    • a repository address that git could take as an option;
    • a lock git leaves, which failed every start;
    • a new version that hangs and is never rolled back;
    • a busy port that undid a good update;
    • CRLF checkouts, submodules, and too old a git.

    All are fixed, with tests.

• A final swarm (#159): 2 reviewers and 2 live testers.
  • The updater, live with the real launcher, passed every case: a plain update, new packages, a crash and a 5-minute hang that both roll back, a package rollback, each blocker, and a failed install.
  • The web changes passed at 3 phone and 2 desktop sizes, with 0 to 10 rail buttons and 0 to 3 composer buttons.
  • Fixed, each with a test where one can catch it:
    • a release whose notes GitHub did not give looked safe, and could be rolled back over a one-way change;
    • recovery failed where a release made a folder from a file and the owner wrote into it;
    • a failed npm ci showed its help text instead of its cause;
    • Send went out of a phone's message box with 2 or more extension buttons;
    • the drawer was cut off on a phone on its side.
  • npm test: 628 of 630 pass. The 2 that fail are known to fail under load and passed on their own.
• Rail (#156). A new browser test, with 8 extension buttons in a short window, fails without the change. All browser UI tests pass (107). Checked by hand on a desktop window, folded and unfolded, on a phone, and on a phone on its side.
• Message box (#154).
  • The bug is real: on main, the new test fails at 320 px with three extension buttons.
  • Review found that the fix clipped the taller tap area of Steer, Queue, and Interrupt on touch screens. It now cuts sideways only, and the test taps above and below each mode.
• Not tested:
  • an install by itself end to end, since it needs 10 quiet minutes;
  • Windows;
  • updates under systemd on a real machine;
  • the message-box follow-up in Firefox;
  • the rail's fade in Safari and Firefox.
• Known limits:
  • A file written in the instant while a recovery restores the old version can be overwritten. Recovery runs only while the server is down.
  • An update is not durable against a power cut while it runs.

Thanks to @piromagnus for the message-box fix.

Full changes: v0.22.0...v0.23.0