pi-pocket 0.30.0-beta.1 → 0.30.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/docs/desktop-app.md +54 -0
- package/docs/features.md +1 -1
- package/docs/index.md +1 -0
- package/docs/macos.md +19 -8
- package/docs/map.md +5 -2
- package/docs/windows.md +20 -8
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
- package/src/launcher/desktop.ts +45 -0
- package/src/launcher/main.ts +47 -1
- package/src/launcher/options.ts +27 -0
- package/src/server/auth.ts +40 -0
- package/src/server/background.ts +109 -241
- package/src/server/design/scan-fig-container.ts +3 -2
- package/src/server/design/scan-files.ts +3 -11
- package/src/server/design/system.ts +3 -4
- package/src/server/design/tokens-io.ts +2 -3
- package/src/server/extensions/artifacts.ts +2 -6
- package/src/server/extensions/pocket-relay/files.ts +3 -3
- package/src/server/http/api.ts +11 -0
- package/src/server/http/conversation-routes.ts +4 -3
- package/src/server/http/events.ts +2 -1
- package/src/server/http/sign-in.ts +9 -3
- package/src/server/no-follow.ts +67 -0
- package/src/server/processes.ts +1480 -0
- package/src/server/themes.ts +2 -4
- package/src/server/worktrees.ts +16 -17
- package/web/store.js +76 -1
package/README.md
CHANGED
|
@@ -56,11 +56,11 @@ While it runs: **q** quit · **r** restart server · **a** change access · **o*
|
|
|
56
56
|
|
|
57
57
|
### Windows installer
|
|
58
58
|
|
|
59
|
-
Download `Pi-Pocket-Setup-<version>.exe` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and run it. It needs no admin rights and no Node.js: it installs its own Node.js and Pi Pocket in `%LOCALAPPDATA%\Pi Pocket`, adds **Pi Pocket** to the Start menu, and can start it when you sign in. The installer is not code-signed yet, so SmartScreen warns: select **More info**, then **Run anyway**. Menu → **Update Pi Pocket** updates it. The uninstaller asks before it deletes your data. See [docs/windows.md](docs/windows.md).
|
|
59
|
+
Download `Pi-Pocket-Setup-<version>.exe` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and run it. It needs no admin rights and no Node.js: it installs its own Node.js and Pi Pocket in `%LOCALAPPDATA%\Pi Pocket`, adds **Pi Pocket** to the Start menu, and can start it when you sign in. Pi Pocket opens as a desktop app: a window of its own, already signed in, and an icon in the notification area, with no console window. **Pi Pocket (console)** has the access modes, tunnels, and the sign-in QR code. The installer is not code-signed yet, so SmartScreen warns: select **More info**, then **Run anyway**. Menu → **Update Pi Pocket** updates it. The uninstaller asks before it deletes your data. See [docs/windows.md](docs/windows.md) and [docs/desktop-app.md](docs/desktop-app.md).
|
|
60
60
|
|
|
61
61
|
### macOS package
|
|
62
62
|
|
|
63
|
-
Download `Pi-Pocket-<version>.pkg` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and open it. It needs no admin password and no Node.js: it installs its own Node.js and Pi Pocket in `~/Library/Application Support/Pi Pocket` for your user only, adds **Pi Pocket.app** to `~/Applications`, and can start it when you sign in. The package is not signed yet, so Gatekeeper blocks it: open System Settings → Privacy & Security, then select **Open Anyway**. Menu → **Update Pi Pocket** updates it. Its uninstaller asks before it deletes your data. See [docs/macos.md](docs/macos.md).
|
|
63
|
+
Download `Pi-Pocket-<version>.pkg` from the [releases](https://github.com/TannerMidd/pi-pocket/releases) and open it. It needs no admin password and no Node.js: it installs its own Node.js and Pi Pocket in `~/Library/Application Support/Pi Pocket` for your user only, adds **Pi Pocket.app** to `~/Applications`, and can start it when you sign in. Pi Pocket.app opens a window of its own, already signed in, with an item in the menu bar and no Terminal window. **Pi Pocket (console).app** has the access modes, tunnels, and the sign-in QR code. The package is not signed yet, so Gatekeeper blocks it: open System Settings → Privacy & Security, then select **Open Anyway**. Menu → **Update Pi Pocket** updates it. Its uninstaller asks before it deletes your data. See [docs/macos.md](docs/macos.md) and [docs/desktop-app.md](docs/desktop-app.md).
|
|
64
64
|
|
|
65
65
|
### Other ways to run it
|
|
66
66
|
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# The desktop apps
|
|
2
|
+
|
|
3
|
+
The Windows installer and the macOS package install a desktop app: **Pi Pocket**. It opens like any other app, with no console or Terminal window. It runs the server on this computer only, shows Pi Pocket in a window of its own that is already signed in, and puts an icon in the notification area (Windows) or the menu bar (macOS) with **Open**, **Restart server**, and **Quit**. [windows.md](windows.md) and [macos.md](macos.md) say how to install and remove it; this page says how it works.
|
|
4
|
+
|
|
5
|
+
The console launcher stays, as **Pi Pocket (console)**: it has the access menu (the local network, a Cloudflare tunnel, Tailscale), the keys, and the sign-in QR code.
|
|
6
|
+
|
|
7
|
+
## How it opens
|
|
8
|
+
|
|
9
|
+
| | Windows | macOS |
|
|
10
|
+
| --------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
11
|
+
| The app | `Pi Pocket.exe`, C# for the .NET Framework 4.x that Windows has | `Pi Pocket.app`, Swift and AppKit, one file for Apple silicon and Intel |
|
|
12
|
+
| Its source | [`packaging/windows/PiPocket.cs`](../packaging/windows/PiPocket.cs) | [`packaging/macos/app/main.swift`](../packaging/macos/app/main.swift) |
|
|
13
|
+
| The window | Edge in app mode (`msedge --app`), with a profile of its own | A `WKWebView` window, with the app bridge ([embedders.md](embedders.md)): badge, notifications |
|
|
14
|
+
| Its icon | The notification area. A click opens the window | **π** in the menu bar. Closing the window keeps it there; the Dock icon goes with the window |
|
|
15
|
+
| At sign-in (optional) | The Startup shortcut runs `Pi Pocket.exe --hidden`: the icon only | A LaunchAgent runs `open -g -a Pi Pocket.app --args --hidden`: the menu bar item only |
|
|
16
|
+
| The log | `%LOCALAPPDATA%\Pi Pocket\launcher.log`, and `launcher.old.log` from the run before | `~/Library/Logs/Pi Pocket/launcher.log`, and `launcher.old.log` |
|
|
17
|
+
|
|
18
|
+
1. **One app per user.** A second start (the Start menu again, Spotlight, the Dock) asks the first one to show its window, then exits. Windows uses a named mutex and event in the session's `Local\` namespace; macOS a distributed notification. `--quit` asks the running one to quit, as its **Quit** does; the installers use it.
|
|
19
|
+
2. **A server that runs already is used.** Each launcher writes `launcher-running.json` in the data folder when its server is ready, and removes it when it quits ([`src/launcher/desktop.ts`](../src/launcher/desktop.ts)): its process, the server's local address, and whether a desktop app started it. The app uses that server when the process is there and `GET /api/pocket/info` answers. **Quit** then leaves it running: another launcher, such as Pi Pocket (console), started it.
|
|
20
|
+
3. **Otherwise the app starts a launcher**, `pi-pocket --desktop`, with the install's own Node.js. `--desktop` means: this device only (unless `--access` says otherwise), no access menu, no keys, no sign-in link and no QR code in its output, and the choice is not saved as the console's last one. It stops when its standard input closes. The app holds that input: **Quit** closes it, and so does the end of the app, also when it crashes.
|
|
21
|
+
4. **The window signs in.** See below.
|
|
22
|
+
|
|
23
|
+
On Windows the launcher and everything it starts (the server, the commands of the agents, the Edge window) are in a job object that ends with the app, so nothing runs on after it, even when the app is killed. Edge's window closes on **Quit**, with the server it shows. Without Edge, the default browser opens the one-time link; it is not in the job, and stays.
|
|
24
|
+
|
|
25
|
+
On macOS the app starts the launcher through the user's login shell (`zsh -l`, or the user's own `bash`, `sh`, `ksh`, or `dash`), so the `PATH` of `~/.zprofile` (Homebrew, for example) reaches the sessions, as it does in Terminal. **Quit**, a logout, and a `SIGTERM` (from the installer) close the launcher's input and send it `SIGTERM`; after 20 seconds it gets `SIGKILL`.
|
|
26
|
+
|
|
27
|
+
## Sign-in
|
|
28
|
+
|
|
29
|
+
The owner's token is the key to the whole server, so it is never on a command line, in a window title, in the log, or in a crash report. The app reads it from `config.json` in the data folder, which only this user can read, and asks the server for a one-time sign-in link:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
POST /api/sign-in-link Authorization: Bearer <owner token>, X-Pocket: 1
|
|
33
|
+
→ { "path": "/login?once=<code>", "expiresInMs": 60000 }
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Only the owner can ask. The code is 32 random bytes, works once, and ends after a minute; the server keeps it only in memory, and at most 8 wait at once. `GET /login?once=<code>` sets the owner's sign-in cookie and goes on to the app, like the owner's `/login?token=` link. It does not ask before it switches a browser that is signed in as someone else (that question would put the token in the page): the app's window is the owner's own.
|
|
37
|
+
|
|
38
|
+
On Windows the one-time link is on Edge's command line, and only there: it is spent within a second, and then worth nothing. Edge's profile (`%LOCALAPPDATA%\Pi Pocket\Edge profile`) keeps the cookie, as a browser does; the uninstaller deletes it. On macOS the link goes straight into the window. `WKWebView` keeps the cookie in the app's own website data.
|
|
39
|
+
|
|
40
|
+
**Restart server** sends `POST /api/restart` with the same bearer token.
|
|
41
|
+
|
|
42
|
+
## What the apps rely on
|
|
43
|
+
|
|
44
|
+
A newer installer replaces the app; Menu → **Update Pi Pocket** does not. So an installed app runs against newer `pi-pocket` packages, and these stay as they are: `--desktop`, `launcher-running.json` (its fields only grow), `/api/pocket/info`, `/api/sign-in-link`, `/login?once=`, and `/api/restart`.
|
|
45
|
+
|
|
46
|
+
## What the window does not do yet
|
|
47
|
+
|
|
48
|
+
- macOS: no Web Push in a `WKWebView`, so notifications come through the app bridge while the app runs. Approvals in a notification have no **Allow** or **Deny** buttons: a click opens the session.
|
|
49
|
+
- Windows: Edge's app window is Edge. It has Edge's notifications, downloads, and file dialogs.
|
|
50
|
+
- A server on a Unix socket (`--socket`) has no address for the window: the app cannot use it, and its own launcher cannot start while that one runs.
|
|
51
|
+
|
|
52
|
+
## How it is tested
|
|
53
|
+
|
|
54
|
+
[`test/launcher-desktop.test.ts`](../test/launcher-desktop.test.ts) runs `--desktop`: `launcher-running.json`, the one-time link, no token in the output, and the stop when its input closes. On each pull request, [`windows.yml`](../.github/workflows/windows.yml) and [`macos.yml`](../.github/workflows/macos.yml) install the app, open it as the Start menu or Finder does, and check: no console or Terminal window, the server on this computer only, a window that signed in (on Windows, Edge spent the one-time link; on macOS, the window's own `/api/me` answers 200), no token in the log or on a command line, one instance only, and **Quit** that stops the launcher, the server, and the window. They also take a screenshot of the window. Nobody has tried them yet on a real PC or Mac, only on GitHub's runners.
|
package/docs/features.md
CHANGED
|
@@ -27,7 +27,7 @@ The full tour. For setup, see the [README](../README.md).
|
|
|
27
27
|
- **Mention files.** Type `@` in the message box to pick a file or folder from the session's folder: `@` alone lists its top, `@src/` a folder's own files, and anything else matches across the whole folder (`@srvapp` finds `src/server/app.ts`). Tab or Enter (or a tap) puts the path in, and a folder opens to its files. Pi gets the message as written, `@src/server/app.ts` and all, and reads what it names; or tap **Send them along** above the box to send the files' contents with the message, as Claude Code does (text files up to 100 KB each, images as images when the model takes them). The list is git's in a repository (so ignored files stay out), and a walk that skips hidden and dependency folders elsewhere; your browser fetches it once and matches as you type, so suggestions never wait on the network.
|
|
28
28
|
- **Shell commands.** `!git status` runs in the session's folder, and Pi sees the command and what it printed with your next message, as in Pi's terminal app; `!!git status` shows it only to the people here. While it runs, a row says so, with Stop (it is in Running now too). A restart while it runs does not run it again: its entry says it was cut off. With Lancet Guard on, a command from anyone but the owner must be one the guard allows outright. A command Pi sees counts as its person's message: Pi works for them from there, as for a steer. These are a person's own commands, not Pi's: plan mode does not hold them back. Stop one from its row, or from Running now on any device.
|
|
29
29
|
- **Quiet commands stop (since 0.29.0).** A bash command of Pi's that prints nothing for 15 minutes is stopped with the processes it started, and the call ends as timed out with what it printed, so a hung test run cannot hold a session or a subagent for good. A command that keeps printing, such as a long build, runs on, and Pi can give a call its own `timeout` instead. The owner changes the time in Menu → Extensions, under Background tasks (0: no limit); while Background tasks is off, the time last set there stays in force.
|
|
30
|
-
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. Tasks that end together go as one message, which joins the run in flight at its next pause rather than starting another turn (a steer, as a subagent's report is): several ending cost Pi one turn, not one each, and the answer it was writing keeps its place. A task Pi stops is not told about; one a person stops (in Running now) is, as Pi may wait for it (since 0.29.0). A task that prints nothing for 60 minutes is stopped, and Pi is told why; Pi starts a server or a watcher with `quietMinutes: 0` for no limit (since 0.29.0). In the conversation, that message shows as a card each, a group for several: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background**, its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). A tap on that count opens **Background** (Menu → **Background** opens it too, also when nothing runs): the session's commands, the newest first, and what the open one printed, as it comes. It asks again once a second while the task runs, so a dev server's log scrolls by itself; a scroll back up stops it following, and **Jump to the end** goes on. A tap on another command in the row above the log switches to it. **Stop** is there for anyone who may steer. Watching a task takes nothing from Pi: what it reads next stays where it was, so Pi still gets every line it has not read. Past the 20,000 characters the sheet keeps, or past what the log still holds, it says how many bytes it did not show. Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. Linux
|
|
30
|
+
- **Background tasks.** Since 0.24.0, Pi's `background` tool starts a command without waiting for it: a dev server, a watcher, a long build or test run. It runs in the session's folder, reads what the command printed since it last looked (the last 20,000 characters at most), lists the session's tasks and how they ended, and stops one: every process it started, politely, then by force after 4 seconds. A task runs while any process of its group runs, so a command that starts a server in the background and exits keeps its task running. A daemon that leaves the group (a build tool's) does not keep it running: the task ends, says which processes it left, and a stop ends them too. When a task ends by itself, Pi gets a message that starts with `[background]`, with its exit code and the end of its output, as data; Pi can start one without it. Tasks that end together go as one message, which joins the run in flight at its next pause rather than starting another turn (a steer, as a subagent's report is): several ending cost Pi one turn, not one each, and the answer it was writing keeps its place. A task Pi stops is not told about; one a person stops (in Running now) is, as Pi may wait for it (since 0.29.0). A task that prints nothing for 60 minutes is stopped, and Pi is told why; Pi starts a server or a watcher with `quietMinutes: 0` for no limit (since 0.29.0). In the conversation, that message shows as a card each, a group for several: the task's id, how it ended and how long it took, its command, and the last 8 lines of its output as printed, with the rest behind **Show all** (a person who types `[background]` themselves keeps their message as theirs). Each command runs detached from the server, with its output in a log in the data folder (`background/`, in 4 MB segments), so it goes on across a restart from the app; stopping the whole service (systemd) ends it. A durable task watches each one, and after a restart finds the same processes again by their pid, start time, and a marker in their environment. A start is reserved before its process starts, so a tool call run again after a crash never starts the command twice: the watch adopts the processes it finds by their marker; with none left, it tells Pi the exit code the command left, or that how it went cannot be known. A start passes Lancet Guard as a bash command does, and plan mode blocks it (listing, reading, and stopping stay allowed). Each task shows in Running now, where anyone who may steer the session can stop it. While any runs, the session's status line shows **N in background**, its row in the session list shows a terminal mark with the count, and the rail's Running now button counts the session (since 0.25.0). A tap on that count opens **Background** (Menu → **Background** opens it too, also when nothing runs): the session's commands, the newest first, and what the open one printed, as it comes. It asks again once a second while the task runs, so a dev server's log scrolls by itself; a scroll back up stops it following, and **Jump to the end** goes on. A tap on another command in the row above the log switches to it. **Stop** is there for anyone who may steer. Watching a task takes nothing from Pi: what it reads next stays where it was, so Pi still gets every line it has not read. Past the 20,000 characters the sheet keeps, or past what the log still holds, it says how many bytes it did not show. Limits: 10 running at once in a session (the owner changes it in Menu → Extensions, under Background tasks); a log past 50 MB loses its oldest segments, whole, and a command that writes more than 200 MB in a quarter of a second, or more than 500 MB in 10 seconds, is stopped at once, and Pi is told why; the last 20 ended tasks of a session stay readable. Sessions only: not subagents or PiP. It needs bash and `split`. Since 0.30.0 it runs on Linux, macOS, and Windows (before, Linux only). Each platform knows a process by its pid and its start time together, so a stop never hits a process that took a task's pid later. Linux reads `/proc`, and macOS reads `ps`: a task is its process group, and a process that left the group is found by its marker. Windows has no process groups or signals: a task is its first process and what it starts (by parent and start time), held in a job object while the server runs, through a small PowerShell helper; it needs Git Bash, and a stop ends the processes by force at once. On Windows, a process in a task cannot leave its job, a process started outside it (through a service) is not followed, and a task does not say what it left running ([Windows](windows.md) lists what is weaker there).
|
|
31
31
|
- **Extensions' commands.** A module can add commands to the message box (`/clock-zone Europe/Berlin`), which do something without asking Pi: show a status, change a setting. They show in the suggestions with the app's own, after them; a prompt template of the same name wins. What one gives back is a notice for you alone, or a card of plain text in the conversation for everyone there, which Pi never sees and which does not change whom Pi works for; Find in session and export include it. A conversation command is for whoever may steer (whoever drives, while people take turns); a global one is the owner's, also while someone else drives; viewers get none. Each run is a durable task: sending the same text again after a lost reply gets the first run's result, a restart never runs one again, and Running now shows and stops it. See [Writing extensions](extensions/commands.md).
|
|
32
32
|
- **A person's role and the page's scroll, for extensions.** Since 0.27.0, two experimental members. `host.roleOf(personId)` gives a person's role (`owner`, `guest`, or `viewer`), or `undefined` for an id that is not a person here. It reads the role that core already uses, so a module that guards owner-only things can ask whether Pi works for the owner (`host.requesterOf` gives the id). The snapshot of `host.browser` has a `scroll` field, `{ y, viewport, height }` in CSS pixels, the same numbers that Pi's `browser` tool shows as "scrolled 0 of 800px". See [Writing extensions](extensions/host.md).
|
|
33
33
|
- **Folded inputs.** An extension can send a message the conversation shows as one line: a short label, and a summary when the message has one. Tap the line to read the message. Tap the message for its sheet, where **Show**, **Fold**, and **Hide** choose how every input of that kind shows in this browser: as a message, as the line (the usual choice), or hidden until Find jumps to it. A hidden message still starts its turn. An extension's browser code can pick one for you until you choose. The queue shows the same line. Export keeps the whole message in a folded block. Find searches the label, the summary, and the whole message, however long; Copy text copies all of it. An input the extension stored as its own kind is not a message you can send again. Peek tiles and PiP show the one line. The model still reads the whole message. Since 0.28.0.
|
package/docs/index.md
CHANGED
|
@@ -42,6 +42,7 @@ A drop-in extension stays when Pi Pocket updates, and the owner can turn it off
|
|
|
42
42
|
- [embedders.md](embedders.md): the app bridge, for an embedder (an app that shows Pi Pocket inside itself, such as an Electron or Tauri wrapper): `/api/pocket/info`, `window.pocketHost`, and notifications without Web Push.
|
|
43
43
|
- [docker.md](docker.md): running Pi Pocket in a container, with extensions, themes, Pi's folder, and the workspace mounted from the host.
|
|
44
44
|
- [systemd.md](systemd.md): running Pi Pocket as a systemd service, with a template unit whose instance name is the access mode.
|
|
45
|
+
- [desktop-app.md](desktop-app.md): the desktop apps of the Windows installer and the macOS package: the window, the tray or menu bar icon, `--desktop`, `launcher-running.json`, and the one-time sign-in link.
|
|
45
46
|
- [windows.md](windows.md): the Windows installer: SmartScreen, where it installs, updates, uninstall, and how it is built and tested.
|
|
46
47
|
- [macos.md](macos.md): the macOS package: Gatekeeper, where it installs, updates, uninstall, and how it is built and tested.
|
|
47
48
|
- [map.md](map.md): where each part of the code is, and how to add the usual things.
|
package/docs/macos.md
CHANGED
|
@@ -26,7 +26,7 @@ The installer has one place to install: **Install for me only**. Everything goes
|
|
|
26
26
|
| `node/` | Node.js, from the official `darwin-arm64` and `darwin-x64` tarballs. The build checks each against the SHA256 pinned in [`packaging/macos/build.sh`](../packaging/macos/build.sh), and joins their two `node` files into one universal file; each half is the official file, byte for byte, with its signature. |
|
|
27
27
|
| `app/` | A private npm prefix that holds the `pi-pocket` package. It is yours, so updates from the app work. |
|
|
28
28
|
| `pi-pocket` | Starts the launcher with that Node.js and prefix. Arguments go to `pi-pocket` (`pi-pocket --help`). |
|
|
29
|
-
| `Pi Pocket.command
|
|
29
|
+
| `Pi Pocket.command` | What Terminal runs for Pi Pocket (console). |
|
|
30
30
|
| `uninstall.sh`, `login-item.sh`, `stop-pi-pocket.sh` | The uninstaller, the switch of the sign-in item, and what stops a running Pi Pocket for the installer and the uninstaller. |
|
|
31
31
|
| `install-app.mjs` | Installs the `pi-pocket` npm package into `app/` during the install. |
|
|
32
32
|
| `npm-cache/`, `install.log` | npm's cache, and what npm printed during the install. |
|
|
@@ -37,14 +37,16 @@ Your data (sessions, sign-ins, settings, extensions) stays in `~/.pi-pocket`, as
|
|
|
37
37
|
|
|
38
38
|
The package also makes:
|
|
39
39
|
|
|
40
|
-
- **Pi Pocket.app** in the Applications folder of your home folder (`~/Applications`)
|
|
41
|
-
-
|
|
40
|
+
- **Pi Pocket.app** in the Applications folder of your home folder (`~/Applications`), the desktop app. It opens Pi Pocket in a window of its own, already signed in, with no Terminal window, and puts **π** in the menu bar with **Open Pi Pocket**, **Restart Server**, and **Quit Pi Pocket**. The server listens on this Mac only. To sign in your phone, use Menu → **Sign in another device** in the window. Close the window and Pi Pocket keeps running in the menu bar; open the app again to show it. A second server never starts. The window shows the Dock badge and notifications while the app runs. It starts the launcher in your login shell, so your `PATH` from `~/.zprofile` (Homebrew, for example) reaches the sessions. [desktop-app.md](desktop-app.md) says how it works.
|
|
41
|
+
- **Pi Pocket (console).app** beside it, which opens the launcher in a Terminal window, as Pi Pocket.app did before: there you choose how other devices reach Pi Pocket (the local network, a Cloudflare tunnel, Tailscale), and it shows the sign-in link and its QR code. Press **q** in the Terminal window, or close it, to stop it. When it runs, Pi Pocket.app uses its server instead of starting one.
|
|
42
|
+
- If another app of either name is in `~/Applications`, the installer leaves it, and Pi Pocket's app stays in the install folder. Spotlight and Launchpad find both. New sessions start in your home folder.
|
|
43
|
+
- with the choice **Start Pi Pocket when I sign in** (off by default, and on when an earlier install has it on; select **Customize** on the Installation Type page), a LaunchAgent, `~/Library/LaunchAgents/io.github.tannermidd.pi-pocket.plist`. From the next sign-in, it starts Pi Pocket.app in the menu bar, without a window. macOS lists it in System Settings → General → Login Items. To turn it on or off later:
|
|
42
44
|
|
|
43
45
|
```sh
|
|
44
46
|
"$HOME/Library/Application Support/Pi Pocket/login-item.sh" on # or off
|
|
45
47
|
```
|
|
46
48
|
|
|
47
|
-
|
|
49
|
+
**Quit Pi Pocket** (in the menu bar, or ⌘Q) stops the server, with each command that its agents run, and closes the window. A GUI install opens Pi Pocket.app at the end. The app's log is `~/Library/Logs/Pi Pocket/launcher.log`; it has no sign-in link.
|
|
48
50
|
|
|
49
51
|
Inside sessions, `node` and `npm` are the package's own, and a global npm install (`npm install -g …`) goes into Pi Pocket's prefix. Pi's tools work best with git: macOS asks to install the Xcode Command Line Tools the first time something runs `git`, or run `xcode-select --install`.
|
|
50
52
|
|
|
@@ -60,7 +62,7 @@ A macOS package has no uninstaller of its own. Run this in Terminal:
|
|
|
60
62
|
"$HOME/Library/Application Support/Pi Pocket/uninstall.sh"
|
|
61
63
|
```
|
|
62
64
|
|
|
63
|
-
Run it in Terminal, not from a Pi Pocket session: it must stop Pi Pocket, so it refuses to run inside it. It asks first. It stops a running Pi Pocket, with each command that its agents run, and removes `~/Library/Application Support/Pi Pocket`, Pi Pocket.app, the sign-in item, and the package receipts. Then it asks whether to delete your data in `~/.pi-pocket`. The default is No: your sessions and settings stay for the next install. `--yes` skips the first question; without a terminal it asks nothing and keeps the data, unless you add `--delete-data`. Only the default data folder is offered: one chosen with `PI_POCKET_DIR` or `--data` stays. Another Pi Pocket install on the same account (npm, or a git checkout) uses the same `~/.pi-pocket`: the question says so, and a yes deletes it for that install too.
|
|
65
|
+
Run it in Terminal, not from a Pi Pocket session: it must stop Pi Pocket, so it refuses to run inside it. It asks first. It quits Pi Pocket.app, stops a running Pi Pocket, with each command that its agents run, and removes `~/Library/Application Support/Pi Pocket`, Pi Pocket.app, Pi Pocket (console).app, the sign-in item, and the package receipts. Then it asks whether to delete your data in `~/.pi-pocket`. The default is No: your sessions and settings stay for the next install. `--yes` skips the first question; without a terminal it asks nothing and keeps the data, unless you add `--delete-data`. Only the default data folder is offered: one chosen with `PI_POCKET_DIR` or `--data` stays. Another Pi Pocket install on the same account (npm, or a git checkout) uses the same `~/.pi-pocket`: the question says so, and a yes deletes it for that install too.
|
|
64
66
|
|
|
65
67
|
## Install from Terminal
|
|
66
68
|
|
|
@@ -72,8 +74,17 @@ No `sudo`: the package refuses to install as root. For the sign-in item too, pas
|
|
|
72
74
|
|
|
73
75
|
## How it is built
|
|
74
76
|
|
|
75
|
-
[`.github/workflows/macos-installer.yml`](../.github/workflows/macos-installer.yml) builds it on GitHub's macOS runner for each published release with `pkgbuild` and `productbuild`, and attaches it to the release. It runs beside the npm publish and does not wait for it. Only a release build is signed, and only when the `macos-signing` environment has the "Developer ID Installer" certificate that the workflow names; with the notary secrets too, it is notarized and stapled. Limit that environment to `v*` tags and give it a reviewer.
|
|
77
|
+
[`.github/workflows/macos-installer.yml`](../.github/workflows/macos-installer.yml) builds it on GitHub's macOS runner for each published release with `pkgbuild` and `productbuild`, and attaches it to the release. Pi Pocket.app is compiled there with `swiftc` for arm64 and x86_64, joined with `lipo`, and signed ad hoc, unless the `macos-signing` environment also has a "Developer ID Application" certificate (`MACOS_APPLICATION_CERTIFICATE` and `MACOS_APPLICATION_PASSWORD`): then it is signed with it and the hardened runtime. Without that certificate the package is not notarized, as notarization refuses code that is signed ad hoc. It runs beside the npm publish and does not wait for it. Only a release build is signed, and only when the `macos-signing` environment has the "Developer ID Installer" certificate that the workflow names; with the notary secrets too, it is notarized and stapled. Limit that environment to `v*` tags and give it a reviewer.
|
|
76
78
|
|
|
77
|
-
[`.github/workflows/macos.yml`](../.github/workflows/macos.yml) runs on each pull request, on Apple silicon and on Intel: it builds the package with a package packed from the pull request, installs it without `sudo`, starts
|
|
79
|
+
[`.github/workflows/macos.yml`](../.github/workflows/macos.yml) runs on each pull request, on Apple silicon and on Intel: it builds the package with a package packed from the pull request, installs it without `sudo`, starts the console launcher, checks that it answers HTTP and that the sign-in link works, and uninstalls it while it runs. Then it installs it again with the sign-in item and opens Pi Pocket.app: it checks that no Terminal opens, that the window signed in with a one-time link, that a second start opens the first, and that **Quit** stops everything. It starts the sign-in item, installs over the running Pi Pocket (which keeps the sign-in item), and uninstalls it with the data. It also runs `npm run check` and the test suite, without the tests that do not pass on macOS yet. The workflow skips them by name, and `test/pip-board-ui.test.ts` as a whole:
|
|
78
80
|
|
|
79
|
-
|
|
81
|
+
- Tests that press Ctrl or Alt for a shortcut. On a Mac the app takes ⌘ and Option instead (`APPLE` in `web/ui.js`), so the shortcut does not come. The PiP board tests stop at their first Alt+A, and each later test in that file needs the page that it left.
|
|
82
|
+
- Time limits and animations: the performance limits of the design lint and the RSS parser, the stall limits of helpers, and the glide of new rows. The macOS runner is slower than these limits allow.
|
|
83
|
+
- Some browser tests of the design workspace, drafts, linked sessions, and Markdown extension points, which time out on the runner. Nobody has looked into them yet.
|
|
84
|
+
- 4 tests that passed in one run on the runner and failed in the next (a deck's keys, design versions, the gallery scan's time limit, and the limit wait's Retry now): they are flaky there, not wrong on a Mac.
|
|
85
|
+
|
|
86
|
+
Tests that need Linux's `/proc` skip by themselves on macOS.
|
|
87
|
+
|
|
88
|
+
Background tasks work on macOS since 0.30.0: Pi Pocket reads the process table with `ps`, and the environment of your own processes with `ps -E`, to follow a task's processes.
|
|
89
|
+
|
|
90
|
+
The install through the Installer app (a double-click), the Gatekeeper steps, signing, and notarization are not tested in CI, and the app has been tried only on GitHub's runners, not yet on a Mac of its own.
|
package/docs/map.md
CHANGED
|
@@ -4,7 +4,7 @@ Where things are in Pi Pocket, for agents working on it. [index.md](index.md) li
|
|
|
4
4
|
|
|
5
5
|
## Processes
|
|
6
6
|
|
|
7
|
-
`bin/pi-pocket.js` checks Node, then runs `src/launcher/main.ts`. In an npm install, Node strips no types from files in `node_modules`: `bin/strip-types.js` does it for Pi Pocket's own files there, in the launcher and (with `--import`) in the server. The launcher reads its options (`options.ts`), asks how devices connect (`access.ts`: this device, LAN, Cloudflare quick tunnel, Tailscale, Tailscale Serve), runs the server (`src/server/main.ts`) as a child (on a Unix socket with `--socket`, for a reverse proxy, with no access mode), restarts it on exit code 75 or a crash, and keeps the tunnel up. When a server stops before it is ready while an update from the app is under way, it goes back to the version before: the commit and packages of a git checkout, or the kept copy of a global npm install (`rollBackUpdate` in `src/server/update-state.ts`; it also imports `lock.ts`, and `socket-path.ts` to check `--socket`). `term.ts` draws its menu, panel, and QR code in the terminal. `serve.ts` drives the Tailscale CLI for Serve mode: every call has a timeout, the mount is checked before it is made, and it is taken down when the launcher quits unless it found the mount already in place (an adopted mount may be the owner's own `tailscale serve`). A receipt in the data folder (`serve-mount.json`) names a mount the launcher made, so the next start clears one a killed run left behind; a start in another mode on that port stops when it cannot, and leaving the mode from the menu keeps the mode when the mount stays. The launcher takes `launcher.lock` for its whole life and the server takes `harness.lock`. The server then opens one `PocketApp` and serves it with `http.ts`.
|
|
7
|
+
`bin/pi-pocket.js` checks Node, then runs `src/launcher/main.ts`. In an npm install, Node strips no types from files in `node_modules`: `bin/strip-types.js` does it for Pi Pocket's own files there, in the launcher and (with `--import`) in the server. The launcher reads its options (`options.ts`), asks how devices connect (`access.ts`: this device, LAN, Cloudflare quick tunnel, Tailscale, Tailscale Serve), runs the server (`src/server/main.ts`) as a child (on a Unix socket with `--socket`, for a reverse proxy, with no access mode), restarts it on exit code 75 or a crash, and keeps the tunnel up. When a server stops before it is ready while an update from the app is under way, it goes back to the version before: the commit and packages of a git checkout, or the kept copy of a global npm install (`rollBackUpdate` in `src/server/update-state.ts`; it also imports `lock.ts`, and `socket-path.ts` to check `--socket`). `term.ts` draws its menu, panel, and QR code in the terminal. `desktop.ts` writes `launcher-running.json`, which tells the desktop apps where its server answers; `--desktop` runs it for them, with no menu, keys, or sign-in link, until its input closes ([desktop-app.md](desktop-app.md)). `serve.ts` drives the Tailscale CLI for Serve mode: every call has a timeout, the mount is checked before it is made, and it is taken down when the launcher quits unless it found the mount already in place (an adopted mount may be the owner's own `tailscale serve`). A receipt in the data folder (`serve-mount.json`) names a mount the launcher made, so the next start clears one a killed run left behind; a start in another mode on that port stops when it cannot, and leaving the mode from the menu keeps the mode when the mount stays. The launcher takes `launcher.lock` for its whole life and the server takes `harness.lock`. The server then opens one `PocketApp` and serves it with `http.ts`.
|
|
8
8
|
|
|
9
9
|
## Data (`~/.pi-pocket/`, or `PI_POCKET_DIR`)
|
|
10
10
|
|
|
@@ -12,6 +12,7 @@ Where things are in Pi Pocket, for agents working on it. [index.md](index.md) li
|
|
|
12
12
|
- `config.json`: people, roles, hashed tokens, settings. `push.json`: VAPID keys and push subscriptions. `provider-limits.json`: the limits that runs wait for now, kept only as a hint (a missing or damaged file means no limit is known).
|
|
13
13
|
- `launcher.json`: the launcher's access choice. `serve-mount.json`: the Tailscale Serve mount the launcher made, named by port, so a later start can clear it.
|
|
14
14
|
- `launcher.lock` and `harness.lock` (each with a `.identity` file): one launcher per data folder, and one server per data folder.
|
|
15
|
+
- `launcher-running.json`: the launcher that runs, and its server's local address, for the desktop apps ([desktop-app.md](desktop-app.md)).
|
|
15
16
|
- `uploads/<conversation>/`, `worktrees/` (sessions' git worktrees), `extensions/` (the owner's drop-ins), `themes/` (the owner's theme folders, and `.removed/` for removed ones), `browser/profile/` (the built-in browser's profile; each session's cookies live in memory only).
|
|
16
17
|
|
|
17
18
|
## Server: `src/server/`
|
|
@@ -39,6 +40,7 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
39
40
|
| `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
|
|
40
41
|
| `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
|
|
41
42
|
| `lock.ts` | One process per data folder |
|
|
43
|
+
| `no-follow.ts` | Opens a file never through a link as its last part, also on Windows, which has no `O_NOFOLLOW` |
|
|
42
44
|
| `socket-path.ts` | `--socket`: the Unix socket's path checked, its folder and the folders above it checked before listening, a stale socket replaced (never anything else), the socket opened to the folder's group (0660), and removed on stop (by Node, as the server closes); the launcher imports `parseSocketPath` and `socketArgument` |
|
|
43
45
|
| `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
|
|
44
46
|
| `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
|
|
@@ -68,6 +70,7 @@ A module split into parts keeps its name for the part others import, with the re
|
|
|
68
70
|
| `deadline.ts` | The quiet limit of commands: an environment wrapper that stops a command with no output for too long, unless the call gives its own `timeout` |
|
|
69
71
|
| `stall-facts.ts` | Pure helpers of the stall watches (subagents, Agent Teams): what changes while a conversation makes progress, what it waits on, times in words |
|
|
70
72
|
| `background.ts` | Background tasks: commands Pi runs detached, each watched by a durable task until it ends, and their ends go to Pi as one message, steered into the run in flight |
|
|
73
|
+
| `processes.ts` | How background tasks find, follow, and stop their processes on Linux (`/proc`), macOS (`ps`), and Windows (a PowerShell helper with job objects), each process known by its pid and start time |
|
|
71
74
|
| `schedules.ts`, `when.ts` | Scheduled messages (a durable task) and their time grammar |
|
|
72
75
|
| `goals.ts` | "Done when" checks |
|
|
73
76
|
| `titles.ts` | A short title for a session with a long first message, or one that runs a skill or prompt template, from the session's own model |
|
|
@@ -206,7 +209,7 @@ The agent's side of Design mode. `extensions/design.ts` installs it (see Extensi
|
|
|
206
209
|
| `updates.ts`, `update-state.ts`, `npm-install.ts`, `npm-update.ts` | Updates of Pi Pocket itself (`app.updates`, `host.updates`): how the copy was installed (`installKind`), the newest version (the registry's `latest` for npm, and `beta` too with the beta channel on; GitHub for the notes and for a git checkout; `versions.ts`'s `compareReleases` orders pre-releases for it), what stands in the way, packages installed beside the checkout or a package staged beside a global npm install, the move forward or the swap, the restart, and `recover`; `update-state.ts` keeps `.pocket-update/` and the copy kept for a swap back, and the launcher imports it to go back; `npm-install.ts` tells how the copy was installed and whether npm's folders can be written, and `npm-update.ts` stages a version beside a global install |
|
|
207
210
|
| `versions.ts` | Pi Pocket's versions compared, for gallery entries' and themes' `minPocket` (a pre-release counts as its release), and `compareReleases`, which orders pre-releases for updates |
|
|
208
211
|
|
|
209
|
-
Outside `src/`: `flake.nix` and `nix/` build Pi Pocket with Nix (`nix/package.nix`) and run it as a NixOS service (`nix/module.nix`, with `nix/manage-extensions.sh` to copy declared drop-ins). `nix/tests/` runs only under Nix; `npm test` skips it. The container build is `docker/Dockerfile` and `docker/entrypoint.sh` (with `.dockerignore` for the build context), `docker-compose.yml` runs it, and `.env.example` lists the host-side variables for Compose; [docker.md](docker.md) explains them. `packaging/windows/` is the Windows installer (`pi-pocket.iss` for Inno Setup, `build.ps1`, the `pi-pocket.cmd` start script, and `install-app.mjs`, which installs the npm package); `.github/workflows/windows-installer.yml` builds it for each release and `windows.yml` tests it, and [windows.md](windows.md) explains it. `packaging/macos/` is the macOS package (`build.sh` for `pkgbuild` and `productbuild`, `distribution.xml`, the package scripts in `scripts/`, the `pi-pocket` launcher and its `.command`
|
|
212
|
+
Outside `src/`: `flake.nix` and `nix/` build Pi Pocket with Nix (`nix/package.nix`) and run it as a NixOS service (`nix/module.nix`, with `nix/manage-extensions.sh` to copy declared drop-ins). `nix/tests/` runs only under Nix; `npm test` skips it. The container build is `docker/Dockerfile` and `docker/entrypoint.sh` (with `.dockerignore` for the build context), `docker-compose.yml` runs it, and `.env.example` lists the host-side variables for Compose; [docker.md](docker.md) explains them. `packaging/windows/` is the Windows installer (`pi-pocket.iss` for Inno Setup, `build.ps1`, the desktop app `PiPocket.cs` with its manifest, the `pi-pocket.cmd` start script, `stop-pi-pocket.ps1`, and `install-app.mjs`, which installs the npm package); `.github/workflows/windows-installer.yml` builds it for each release and `windows.yml` tests it, and [windows.md](windows.md) explains it. `packaging/macos/` is the macOS package (`build.sh` for `pkgbuild` and `productbuild`, `distribution.xml`, the package scripts in `scripts/`, the desktop app `app/main.swift`, the `pi-pocket` launcher and its `.command` file for Terminal, `install-app.mjs`, `uninstall.sh`, and `login-item.sh`); `.github/workflows/macos-installer.yml` builds it for each release and `macos.yml` tests it, and [macos.md](macos.md) explains it. [desktop-app.md](desktop-app.md) explains the two desktop apps.
|
|
210
213
|
|
|
211
214
|
## Extensions: `src/server/extensions/`
|
|
212
215
|
|
package/docs/windows.md
CHANGED
|
@@ -20,7 +20,11 @@ Everything goes in `%LOCALAPPDATA%\Pi Pocket` (`C:\Users\<you>\AppData\Local\Pi
|
|
|
20
20
|
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
21
|
| `node\` | A portable Node.js LTS, the official `win-x64` zip. The build checks its SHA256 against the value pinned in [`packaging/windows/build.ps1`](../packaging/windows/build.ps1). |
|
|
22
22
|
| `app\` | A private npm prefix that holds the `pi-pocket` package. It is yours, so updates from the app work. |
|
|
23
|
-
| `
|
|
23
|
+
| `Pi Pocket.exe` | The desktop app ([desktop-app.md](desktop-app.md)): the icon in the notification area and the window. Setup's build compiles it from `PiPocket.cs`. |
|
|
24
|
+
| `pi-pocket.cmd` | Starts the launcher with that Node.js and prefix, in a console. Arguments go to `pi-pocket` (`pi-pocket.cmd --help`). |
|
|
25
|
+
| `stop-pi-pocket.ps1` | What stops a running Pi Pocket for Setup and the uninstaller: the app, its launcher and server with the agents' commands, the window's Edge, and the tunnel. |
|
|
26
|
+
| `Edge profile\` | The Edge profile of the app's window, with its sign-in cookie. |
|
|
27
|
+
| `launcher.log` | What the app's launcher and server print, and `launcher.old.log` from the run before. It has no sign-in link. |
|
|
24
28
|
| `npm-cache\`, `install.log` | npm's cache, and what npm printed during Setup. |
|
|
25
29
|
|
|
26
30
|
Setup always uses its own Node.js, also when you have one: an update of your Node.js, or its removal, does not break Pi Pocket, and in-app updates always have a prefix that they can write. Your own Node.js and npm are not changed.
|
|
@@ -29,20 +33,28 @@ Your data (sessions, sign-ins, settings, extensions) stays in `%USERPROFILE%\.pi
|
|
|
29
33
|
|
|
30
34
|
Setup also makes:
|
|
31
35
|
|
|
32
|
-
- a Start menu entry, **Pi Pocket**,
|
|
33
|
-
-
|
|
36
|
+
- a Start menu entry, **Pi Pocket**, the desktop app. It opens Pi Pocket in a window of its own, already signed in, with no console window, and puts Pi Pocket's icon in the notification area: click it to open the window, or right-click it for **Open Pi Pocket**, **Restart server**, and **Quit Pi Pocket**. The server listens on this PC only. To sign in your phone, use Menu → **Sign in another device** in the window. Opening Pi Pocket again shows the window that runs; a second server never starts. The window is Microsoft Edge in app mode, with a profile of its own; without Edge, your default browser opens Pi Pocket. [desktop-app.md](desktop-app.md) says how it works.
|
|
37
|
+
- a Start menu entry, **Pi Pocket (console)**, which opens the launcher in a console window, as before: there you choose how other devices reach Pi Pocket (the local network, a Cloudflare tunnel, Tailscale), and it shows the sign-in link and its QR code. Close the console window, or press **q** in it, to stop it. When it runs, the app uses its server instead of starting one.
|
|
38
|
+
- with the task **Start Pi Pocket when I sign in to Windows** (off by default), a shortcut in your Startup folder. It starts the app with its icon only, without a window.
|
|
34
39
|
|
|
35
|
-
|
|
40
|
+
New sessions start in your user folder. **Quit Pi Pocket** stops the server, with each command that its agents run, and closes the window.
|
|
36
41
|
|
|
37
42
|
Inside sessions, `node` and `npm` are the installer's own, and a global npm install (`npm install -g …`) goes into Pi Pocket's prefix. Pi's `bash` tool needs [Git for Windows](https://git-scm.com/download/win), or another `bash.exe` on `PATH` (Pi's own Windows guide is `docs/windows.md` in the `@earendil-works/pi-coding-agent` package). Setup says so at the end when it cannot find Git Bash.
|
|
38
43
|
|
|
44
|
+
Background tasks (Pi's `background` tool) work on Windows since 0.30.0, with Git Bash. Windows has no process groups or signals, so Pi Pocket follows a task's processes another way: a small Windows PowerShell helper (no admin rights) reads the process table, puts each task in a job object, and ends a process only after it checks the process's start time. What is weaker than on Linux and macOS:
|
|
45
|
+
|
|
46
|
+
- A stop ends the processes by force at once, with no polite stop first.
|
|
47
|
+
- A task's job does not let its processes leave it (Git Bash leaves a job that allows it), so a program in a task that asks to start a process outside its job gets "access denied". A process started outside the task (through a service or the Task Scheduler) is not followed, and a task does not say what it left running.
|
|
48
|
+
- The task's first process holds a handle to its job, so a restarted server finds the job again while that process runs. Once it ended, a restarted server knows the processes found before the restart, and what they start directly; a process started through Git Bash (which starts a program as a new process) is then not followed.
|
|
49
|
+
- A PowerShell in Constrained Language mode (a locked-down machine) cannot load the helper: then background tasks do not start, and say why.
|
|
50
|
+
|
|
39
51
|
## Updates
|
|
40
52
|
|
|
41
53
|
Menu → **Update Pi Pocket** updates the package in `app\`, as for any global npm install, and restarts. The Node.js in `node\` stays the one that Setup installed. A newer installer brings a newer Node.js; run it over the old install. It stops a running Pi Pocket first (it asks), and it keeps a newer package that the app already updated to.
|
|
42
54
|
|
|
43
55
|
## Uninstall
|
|
44
56
|
|
|
45
|
-
Settings → Apps → Installed apps → **Pi Pocket** → Uninstall. It stops a running Pi Pocket, with each command that its agents run, and removes `%LOCALAPPDATA%\Pi Pocket` and the shortcuts. Then it asks whether to delete your data in `%USERPROFILE%\.pi-pocket`. The default is No: your sessions and settings stay for the next install. A silent uninstall (`unins000.exe /VERYSILENT`) always keeps them. Only the default data folder is offered: one chosen with `PI_POCKET_DIR` or `--data` stays, and so does a `.pi-pocket` that another Pi Pocket install on the same account uses.
|
|
57
|
+
Settings → Apps → Installed apps → **Pi Pocket** → Uninstall. It quits the app, stops a running Pi Pocket, with each command that its agents run, and removes `%LOCALAPPDATA%\Pi Pocket` (with the window's Edge profile) and the shortcuts. Then it asks whether to delete your data in `%USERPROFILE%\.pi-pocket`. The default is No: your sessions and settings stay for the next install. A silent uninstall (`unins000.exe /VERYSILENT`) always keeps them. Only the default data folder is offered: one chosen with `PI_POCKET_DIR` or `--data` stays, and so does a `.pi-pocket` that another Pi Pocket install on the same account uses.
|
|
46
58
|
|
|
47
59
|
## Silent install
|
|
48
60
|
|
|
@@ -54,8 +66,8 @@ Leave out `/TASKS=startup` for no sign-in shortcut. The exit code is 20 when the
|
|
|
54
66
|
|
|
55
67
|
## How it is built
|
|
56
68
|
|
|
57
|
-
[`.github/workflows/windows-installer.yml`](../.github/workflows/windows-installer.yml) builds it on GitHub's Windows runner for each published release, with Inno Setup (its installer checked against a pinned SHA256 too), and attaches it to the release. It runs beside the npm publish and does not wait for it. Only a release build is signed, and only when the `windows-signing` environment has the signing secrets that the workflow names; limit that environment to `v*` tags and give it a reviewer.
|
|
69
|
+
[`.github/workflows/windows-installer.yml`](../.github/workflows/windows-installer.yml) builds it on GitHub's Windows runner for each published release, with Inno Setup (its installer checked against a pinned SHA256 too), and attaches it to the release. `Pi Pocket.exe` is compiled with the C# compiler of the .NET Framework 4.x in Windows itself (`csc.exe`), so it needs no download. It runs beside the npm publish and does not wait for it. Only a release build is signed, and only when the `windows-signing` environment has the signing secrets that the workflow names; limit that environment to `v*` tags and give it a reviewer.
|
|
58
70
|
|
|
59
|
-
[`.github/workflows/windows.yml`](../.github/workflows/windows.yml) runs on each pull request: it builds the installer with a package packed from the pull request, installs it silently, starts
|
|
71
|
+
[`.github/workflows/windows.yml`](../.github/workflows/windows.yml) runs on each pull request: it builds the installer with a package packed from the pull request, installs it silently, starts the console launcher, checks that it answers HTTP and that the sign-in link works, and stops it. Then it opens the app from its Start menu entry, and checks that no console window shows, that Edge's window signed in with a one-time link, that a second start opens the first, and that **Quit** stops everything; it starts the app as the Startup shortcut does, and uninstalls it while it runs. It also runs `npm run check` and the part of the test suite that passes on Windows.
|
|
60
72
|
|
|
61
|
-
Windows is still the least tested platform. The browser tests and most of the test suite do not run on Windows yet.
|
|
73
|
+
Windows is still the least tested platform. The browser tests and most of the test suite do not run on Windows yet, and the app has been tried only on GitHub's runners, not yet on a PC of its own.
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-pocket",
|
|
3
|
-
"version": "0.30.0-beta.
|
|
3
|
+
"version": "0.30.0-beta.2",
|
|
4
4
|
"lockfileVersion": 3,
|
|
5
5
|
"requires": true,
|
|
6
6
|
"packages": {
|
|
7
7
|
"": {
|
|
8
8
|
"name": "pi-pocket",
|
|
9
|
-
"version": "0.30.0-beta.
|
|
9
|
+
"version": "0.30.0-beta.2",
|
|
10
10
|
"license": "MIT",
|
|
11
11
|
"dependencies": {
|
|
12
12
|
"@earendil-works/chord": "1.6.0",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-pocket",
|
|
3
|
-
"version": "0.30.0-beta.
|
|
3
|
+
"version": "0.30.0-beta.2",
|
|
4
4
|
"description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi",
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"start": "node bin/pi-pocket.js",
|
|
45
45
|
"dev": "node bin/pi-pocket.js --cwd .",
|
|
46
46
|
"check": "tsc --noEmit -p . && node test/types-file.ts && node docs-site/check-reference.mjs",
|
|
47
|
-
"test": "node --test --test-concurrency=4 test/*.test.ts",
|
|
47
|
+
"test": "node --test --test-concurrency=4 --test-timeout=600000 test/*.test.ts",
|
|
48
48
|
"site:publish": "gh workflow run pages.yml",
|
|
49
49
|
"format": "eslint --fix . && prettier --write .",
|
|
50
50
|
"format:check": "prettier --check . && eslint .",
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the desktop apps (packaging/windows, packaging/macos) read from a launcher: `launcher-running.json` in the data folder
|
|
3
|
+
* says which launcher runs and where its server answers on this machine. The launcher writes it each time its server
|
|
4
|
+
* is ready and removes it when it quits. It holds no secret: the apps sign in with a one-time link
|
|
5
|
+
* (docs/desktop-app.md). Installed apps read it across versions, so its fields only ever grow.
|
|
6
|
+
*/
|
|
7
|
+
import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
8
|
+
import { join } from "node:path";
|
|
9
|
+
|
|
10
|
+
export const RUNNING_FILE = "launcher-running.json";
|
|
11
|
+
|
|
12
|
+
export interface Running {
|
|
13
|
+
version: 1;
|
|
14
|
+
/** The launcher's process. */
|
|
15
|
+
pid: number;
|
|
16
|
+
/** The server's address for a browser on this machine, such as `http://127.0.0.1:8787`; null on a Unix socket. */
|
|
17
|
+
url: string | null;
|
|
18
|
+
/** Started by a desktop app (`--desktop`), which stops it when it quits. */
|
|
19
|
+
desktop: boolean;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function writeRunning(data: string, running: Running): void {
|
|
23
|
+
const file = join(data, RUNNING_FILE);
|
|
24
|
+
const temp = `${file}.${process.pid}.tmp`;
|
|
25
|
+
|
|
26
|
+
writeFileSync(temp, `${JSON.stringify(running)}\n`, { mode: 0o600 });
|
|
27
|
+
renameSync(temp, file);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export function readRunning(data: string): Running | undefined {
|
|
31
|
+
try {
|
|
32
|
+
const running = JSON.parse(readFileSync(join(data, RUNNING_FILE), "utf8")) as Running;
|
|
33
|
+
|
|
34
|
+
return Number.isInteger(running?.pid) ? running : undefined;
|
|
35
|
+
} catch {
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Remove the file if launcher `pid` wrote it: a launcher that failed to start must not remove the running one's. */
|
|
41
|
+
export function removeRunning(data: string, pid: number): void {
|
|
42
|
+
if (readRunning(data)?.pid === pid) {
|
|
43
|
+
rmSync(join(data, RUNNING_FILE), { force: true });
|
|
44
|
+
}
|
|
45
|
+
}
|
package/src/launcher/main.ts
CHANGED
|
@@ -31,6 +31,7 @@ import {
|
|
|
31
31
|
TAILSCALE_MISSING_MESSAGE,
|
|
32
32
|
tailscaleAddress,
|
|
33
33
|
} from "./access.ts";
|
|
34
|
+
import { RUNNING_FILE, removeRunning, writeRunning } from "./desktop.ts";
|
|
34
35
|
import { fail, parseArgs } from "./options.ts";
|
|
35
36
|
import { removeStaleServe, TailscaleServe } from "./serve.ts";
|
|
36
37
|
// The two server modules the launcher runs itself: both import only Node's own, so an update cannot break the launcher.
|
|
@@ -133,6 +134,11 @@ function loadSettings(): { access?: AccessMode } {
|
|
|
133
134
|
}
|
|
134
135
|
|
|
135
136
|
function saveSettings(access: AccessMode): void {
|
|
137
|
+
// The desktop app's own choice (this device only, unless it says otherwise) is not the console's last choice.
|
|
138
|
+
if (options.desktop) {
|
|
139
|
+
return;
|
|
140
|
+
}
|
|
141
|
+
|
|
136
142
|
try {
|
|
137
143
|
writeFileSync(settingsFile, `${JSON.stringify({ access }, null, "\t")}\n`, { mode: 0o600 });
|
|
138
144
|
} catch (error) {
|
|
@@ -576,6 +582,14 @@ function maybeShowPanel(): void {
|
|
|
576
582
|
}
|
|
577
583
|
|
|
578
584
|
state.panelPending = false;
|
|
585
|
+
|
|
586
|
+
// No sign-in link and no QR code: what the desktop app prints goes to a log file. Its window signs in by itself.
|
|
587
|
+
if (options.desktop) {
|
|
588
|
+
log(green(` ✓ Pi Pocket is ready at ${localUrl()}.`));
|
|
589
|
+
|
|
590
|
+
return;
|
|
591
|
+
}
|
|
592
|
+
|
|
579
593
|
void showPanel(true);
|
|
580
594
|
}
|
|
581
595
|
|
|
@@ -651,6 +665,7 @@ function startServer(first: boolean): void {
|
|
|
651
665
|
|
|
652
666
|
state.everReady = true;
|
|
653
667
|
sendAccess();
|
|
668
|
+
noteRunning();
|
|
654
669
|
|
|
655
670
|
if (state.panelPending) {
|
|
656
671
|
maybeShowPanel();
|
|
@@ -746,6 +761,20 @@ function startServer(first: boolean): void {
|
|
|
746
761
|
});
|
|
747
762
|
}
|
|
748
763
|
|
|
764
|
+
/** Say in the data folder where this launcher's server answers, for the desktop app (`desktop.ts`). */
|
|
765
|
+
function noteRunning(): void {
|
|
766
|
+
try {
|
|
767
|
+
writeRunning(options.data, {
|
|
768
|
+
version: 1,
|
|
769
|
+
pid: process.pid,
|
|
770
|
+
url: state.mode === "socket" ? null : localUrl(),
|
|
771
|
+
desktop: options.desktop,
|
|
772
|
+
});
|
|
773
|
+
} catch (error) {
|
|
774
|
+
log(yellow(` Could not write ${RUNNING_FILE}: ${(error as Error).message}`));
|
|
775
|
+
}
|
|
776
|
+
}
|
|
777
|
+
|
|
749
778
|
function restartServer(): void {
|
|
750
779
|
if (child === undefined) {
|
|
751
780
|
return;
|
|
@@ -1115,9 +1144,24 @@ if (process.platform !== "win32") {
|
|
|
1115
1144
|
|
|
1116
1145
|
process.on("exit", () => {
|
|
1117
1146
|
restoreTerminal();
|
|
1147
|
+
|
|
1148
|
+
try {
|
|
1149
|
+
removeRunning(options.data, process.pid);
|
|
1150
|
+
} catch {
|
|
1151
|
+
// The desktop app checks that the launcher it names still runs.
|
|
1152
|
+
}
|
|
1153
|
+
|
|
1118
1154
|
releaseLauncherLock();
|
|
1119
1155
|
});
|
|
1120
1156
|
|
|
1157
|
+
// The desktop app holds the other end of standard input: when it quits, or crashes, the launcher stops with it.
|
|
1158
|
+
if (options.desktop) {
|
|
1159
|
+
process.stdin.on("error", () => {});
|
|
1160
|
+
process.stdin.on("end", () => void quit(0));
|
|
1161
|
+
process.stdin.on("close", () => void quit(0));
|
|
1162
|
+
process.stdin.resume();
|
|
1163
|
+
}
|
|
1164
|
+
|
|
1121
1165
|
// ─── Start ──────────────────────────────────────────────────────────────
|
|
1122
1166
|
|
|
1123
1167
|
async function main(): Promise<void> {
|
|
@@ -1244,7 +1288,9 @@ async function main(): Promise<void> {
|
|
|
1244
1288
|
startTunnel(binary);
|
|
1245
1289
|
}
|
|
1246
1290
|
|
|
1247
|
-
|
|
1291
|
+
if (!options.desktop) {
|
|
1292
|
+
onKeys(onRunKey);
|
|
1293
|
+
}
|
|
1248
1294
|
} catch (error) {
|
|
1249
1295
|
stopServe();
|
|
1250
1296
|
|
package/src/launcher/options.ts
CHANGED
|
@@ -27,6 +27,9 @@ Usage: pi-pocket [options]
|
|
|
27
27
|
address and an access mode. Its folder must be owned by you or root and writable
|
|
28
28
|
by no one else (see Remote access in the README)
|
|
29
29
|
--rotate-token Replace the owner sign-in link, signing out the devices that used it
|
|
30
|
+
--desktop For the desktop app: this device only (unless --access says otherwise), no menu,
|
|
31
|
+
no keys, no sign-in link or QR code, and it stops when its input closes. The
|
|
32
|
+
access choice is not saved
|
|
30
33
|
-h, --help Show this help
|
|
31
34
|
|
|
32
35
|
Environment: PI_POCKET_ACCESS, PI_POCKET_PORT, PI_POCKET_DIR, PI_POCKET_HOST, PI_POCKET_SOCKET,
|
|
@@ -41,6 +44,7 @@ export interface Options {
|
|
|
41
44
|
cwd: string;
|
|
42
45
|
data: string;
|
|
43
46
|
rotateToken: boolean;
|
|
47
|
+
desktop: boolean;
|
|
44
48
|
}
|
|
45
49
|
|
|
46
50
|
export function parseArgs(argv: string[]): Options {
|
|
@@ -54,7 +58,11 @@ export function parseArgs(argv: string[]): Options {
|
|
|
54
58
|
cwd: process.cwd(),
|
|
55
59
|
data: resolve(process.env.PI_POCKET_DIR ?? join(homedir(), ".pi-pocket")),
|
|
56
60
|
rotateToken: false,
|
|
61
|
+
desktop: false,
|
|
57
62
|
};
|
|
63
|
+
let accessGiven = false;
|
|
64
|
+
let hostGiven = false;
|
|
65
|
+
let socketGiven = false;
|
|
58
66
|
const tcpFlags: string[] = [];
|
|
59
67
|
|
|
60
68
|
for (let index = 0; index < argv.length; index++) {
|
|
@@ -78,16 +86,20 @@ export function parseArgs(argv: string[]): Options {
|
|
|
78
86
|
}
|
|
79
87
|
|
|
80
88
|
options.access = mode as AccessMode;
|
|
89
|
+
accessGiven = true;
|
|
81
90
|
tcpFlags.push(arg);
|
|
82
91
|
} else if (arg === "--yes" || arg === "-y") {
|
|
83
92
|
options.yes = true;
|
|
84
93
|
} else if (arg === "--host") {
|
|
85
94
|
options.host = value();
|
|
95
|
+
hostGiven = true;
|
|
86
96
|
tcpFlags.push(arg);
|
|
87
97
|
} else if (arg === "--port" || arg === "-p") {
|
|
88
98
|
options.port = Number(value());
|
|
89
99
|
tcpFlags.push(arg);
|
|
90
100
|
} else if (arg === "--socket") {
|
|
101
|
+
socketGiven = true;
|
|
102
|
+
|
|
91
103
|
try {
|
|
92
104
|
options.socket = socketArgument(value());
|
|
93
105
|
} catch (error) {
|
|
@@ -99,6 +111,8 @@ export function parseArgs(argv: string[]): Options {
|
|
|
99
111
|
options.data = resolve(value());
|
|
100
112
|
} else if (arg === "--rotate-token") {
|
|
101
113
|
options.rotateToken = true;
|
|
114
|
+
} else if (arg === "--desktop") {
|
|
115
|
+
options.desktop = true;
|
|
102
116
|
} else if (arg === "--help" || arg === "-h") {
|
|
103
117
|
console.log(HELP);
|
|
104
118
|
process.exit(0);
|
|
@@ -107,6 +121,19 @@ export function parseArgs(argv: string[]): Options {
|
|
|
107
121
|
}
|
|
108
122
|
}
|
|
109
123
|
|
|
124
|
+
if (options.desktop) {
|
|
125
|
+
if (socketGiven) {
|
|
126
|
+
fail("--desktop cannot be combined with --socket: the app window needs an address");
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// The app window is on this machine: it shares nothing with other devices unless its own arguments say so. The
|
|
130
|
+
// environment of a login shell (PI_POCKET_ACCESS, PI_POCKET_HOST, PI_POCKET_SOCKET) does not count.
|
|
131
|
+
options.yes = true;
|
|
132
|
+
options.access = accessGiven ? options.access : "local";
|
|
133
|
+
options.host = hostGiven ? options.host : undefined;
|
|
134
|
+
options.socket = undefined;
|
|
135
|
+
}
|
|
136
|
+
|
|
110
137
|
try {
|
|
111
138
|
options.socket = parseSocketPath(options.socket);
|
|
112
139
|
} catch (error) {
|