@firstpick/pi-package-webui 0.10.6 → 0.10.8
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/DEVELOPMENT.md +95 -15
- package/README.md +1 -1
- package/TECHNICAL.md +6 -4
- package/bin/pi-webui-launcher.mjs +6 -3
- package/bin/pi-webui-native-update-guardian.mjs +37 -0
- package/bin/pi-webui-native-update-runner.mjs +148 -0
- package/bin/pi-webui-rpc-supervisor.mjs +85 -10
- package/bin/pi-webui-update-context.mjs +83 -0
- package/bin/pi-webui.mjs +537 -339
- package/lib/component-update-state.mjs +4 -4
- package/lib/rpc-supervisor-client.mjs +4 -0
- package/lib/rpc-supervisor-protocol.mjs +17 -4
- package/lib/update/coordination.mjs +207 -0
- package/lib/update/discovery.mjs +58 -0
- package/lib/update/migration.mjs +115 -0
- package/lib/update/native-jobs.mjs +215 -0
- package/lib/update/native-targets.mjs +81 -0
- package/lib/update/path-pi.mjs +76 -0
- package/lib/update/supervisor.mjs +50 -29
- package/lib/update/verification.mjs +18 -0
- package/lib/update-commands.mjs +17 -27
- package/package.json +3 -3
- package/public/app.js +170 -201
- package/public/index.html +5 -3
- package/public/styles.css +29 -1
- package/tests/browser/control-deck-component-updates.spec.mjs +90 -141
- package/tests/browser/update-reconnect.spec.mjs +37 -1
- package/tests/component-update-api-static.test.mjs +13 -11
- package/tests/control-deck-component-updates-static.test.mjs +25 -25
- package/tests/cwd-footer-reliability-static.test.mjs +4 -1
- package/tests/http-endpoints-harness.test.mjs +32 -9
- package/tests/mobile-static.test.mjs +9 -6
- package/tests/native-update-discovery.test.mjs +69 -0
- package/tests/native-update-lifecycle.test.mjs +90 -0
- package/tests/native-update-shell-survival.test.mjs +68 -0
- package/tests/native-update-verification.test.mjs +17 -0
- package/tests/rpc-supervisor-host.test.mjs +63 -1
- package/tests/rpc-supervisor-protocol.test.mjs +8 -0
- package/tests/run-all.mjs +6 -2
- package/tests/update-api-harness.test.mjs +57 -50
- package/tests/update-commands.test.mjs +29 -15
- package/tests/update-executor-process-tree-harness.test.mjs +84 -1
- package/tests/update-journal-harness.test.mjs +9 -1
- package/tests/update-lock-multiprocess-harness.test.mjs +60 -1
- package/tests/update-owners.test.mjs +32 -0
- package/tests/update-plan.test.mjs +110 -0
- package/tests/update-resolver.test.mjs +36 -0
- package/tests/update-supervisor-harness.test.mjs +74 -1
- package/tests/update-tab-restore-harness.test.mjs +9 -2
- package/bin/pi-webui-update-supervisor.mjs +0 -86
package/DEVELOPMENT.md
CHANGED
|
@@ -279,11 +279,9 @@ Control-visibility setup has no second registry or persistence path. Its five fi
|
|
|
279
279
|
|
|
280
280
|
Run focused validation with `node --check public/app.js`, the static tests above, and `npx playwright test --project=chromium tests/browser/control-deck-side-panels.spec.mjs tests/browser/persistent-ui-layout.spec.mjs tests/browser/control-visibility.spec.mjs`. Run `npm run check` and `npm test` before integration acceptance.
|
|
281
281
|
|
|
282
|
-
|
|
283
|
-
2. The confirmation names that exact plan digest. `POST /api/update/apply` accepts only its `transactionId` and `planDigest`; it never accepts paths, commands, registries, versions, or `latest` from the browser.
|
|
284
|
-
3. Apply acquires the cross-process install lock, revalidates active identities, executes with whole-process-tree timeouts, re-reads every changed target, and records ordered receipts with `success`, `partial`, `failed`, or `rolled-back` outcomes.
|
|
282
|
+
The native update API has two single-target planning requests, `{ "targets": ["pi"] }` and `{ "targets": ["webui"] }`. `POST /api/update/plan` returns an immutable plan with `transactionId`, `digest`, `requested`, `active`, `pathPi`, `context`, `targets`, `refusals` and `warning`. `pathPi` records the independently proven PATH driver's version, package root, executable and CLI, or eligibility/guidance when unproven. Each target carries `id`, `installedRoot`, `effectRoot`, `beforeVersion`, and an absolute `command` with argument array. `POST /api/update/apply` accepts only `{ transactionId, planDigest }` and returns `202` with a running job ID. It revalidates the bound context before launch. No release version or command originates in the browser. `GET /api/update/transactions/<id>` returns phase, bounded per-command receipts, verified targets, outcome and error; a missing completion receipt cannot establish success. A shared private state root fences affected work across server processes. The detached runner writes per-command receipts after native child close, and finalization selectively restarts only verified healthy changed active components after idle. Neither process exit alone nor an exit code alone certifies a healthy installation.
|
|
285
283
|
The authenticated `GET /api/interface-preferences` response includes normalized `preferences`, versioned `layout`, and an opaque `layoutRevision`. `PUT /api/interface-preferences` remains compatible with width-only `{ "sidePanelWidth": 612 }` writes. Layout patches require the latest revision in `expectedLayoutRevision`, merge only named fields, and are limited to 32 KiB; stale revisions return `409`, unsupported media types `415`, oversized bodies `413`, and invalid or unknown fields `400`. Schema v3 adds `controlVisibility.hiddenIds`: `null` means package defaults, `[]` means explicit show-all, and a bounded sorted string list stores hidden stable catalog IDs while retaining unknown future IDs. The browser applies those IDs through a preference-only CSS class and never mutates capability-owned `hidden` state. The `terminalTabs` layout record owns tab placement, custom groups, and the bounded desktop `sidebarWidth`; the client journals those subfields independently so resizing cannot overwrite concurrent group or placement changes. Browser local storage remains a non-destructive compatibility cache. Semantic file moves, prompt attachments, and follow-up queue mutations are not stored in the interface-layout envelope.
|
|
286
|
-
Pi Web UI normally runs Pi RPC tabs under a narrow detached supervisor. Restarting only the HTTP Web UI—through `/webui-start` on the same URL, **Restart**, a
|
|
284
|
+
Pi Web UI normally runs Pi RPC tabs under a narrow detached supervisor. Restarting only the HTTP Web UI—through `/webui-start` on the same URL, **Restart**, a verified native update of an affected active component, `POST /api/restart`, or a restart-safe service-manager `SIGTERM`—preserves each managed Pi PID, tab identity, cwd, session file, running state, and active model turn. Output produced while the HTTP server is absent is replayed in supervisor order. The browser rejects duplicate or older replay records; if the bounded live buffer has a gap, it refreshes tabs, state, and the durable transcript from Pi and warns that buffered live output may be incomplete.
|
|
287
285
|
- Use `/webui-status detailed`, `GET /api/health`, or `GET /api/webui-status?detailed=1` for diagnostics. Public supervisor diagnostics are limited to enabled/attached state and managed-tab count; private credentials and paths are intentionally omitted. A browser warning about incomplete buffered output means authoritative tabs/state/messages were requested, not that missing live deltas were reconstructed.
|
|
288
286
|
- Use the side-panel **Stop** action or localhost-only `POST /api/shutdown` for an explicit full stop. Explicit tab close terminates only that managed Pi child; explicit shutdown and `SIGINT` terminate the scope's managed Pi children. Do not use restart/update when the intent is to terminate active work.
|
|
289
287
|
- Normal authenticated shutdown removes the private scope state. Do not manually delete runtime files, sockets, pipes, journals, or PID records while managed tabs may be live. For cleanup, explicitly shut down first, verify the Web UI/scope has no managed tabs, and let normal startup clean stale empty state; removing private state for a live supervisor destroys the safe attachment path and can risk duplicate processes.
|
|
@@ -319,9 +317,9 @@ Compact mode keeps live output lightweight, coalesces sustained live DOM/scroll
|
|
|
319
317
|
- Detected app runner dropdown for the active tab cwd, including Cargo, Bun, npm/npx/pnpm, Python/uv, Go/Golang, Zig, C/C++, Docker Compose, root/dev/scripts shell scripts, and other common project runners with live output pinned at the top of the terminal. Stream chunks pass through a terminal-line reducer: LF/CRLF commit scrollback, bare CR replaces the current live line, backspace edits that line, and ANSI sequences remain intact for the browser's safe SGR renderer. This is line-oriented terminal behavior rather than a full VT100 cursor grid. Running app runners expose line-oriented stdin in the widget for interactive scripts. Projects can add browseable custom runners in `.pi-webui-runners.json` with a command (default `./`) plus a relative path to the file to run. The same dialog also configures project discovery paths: project-relative directories that are scanned one level deep (no subdirectories) for `.sh`, `.bash`, `.zsh`, `.fish`, and `.py` files plus extensionless files with a bash/sh, zsh, fish, or Python shebang. Python candidates use `uv run` and/or the available `python3`/`python` interpreter. Discovered scripts extend the built-in root, `dev/`, `scripts/`, and `dev/scripts/` detection and run from the resolved project root.
|
|
320
318
|
- Extension-launched Guided Git workflow for existing repos and new repos with persistent model/reasoning preferences, review-first staging, an optional manual staged repository-review gate from `aur-review`, generated or typed commit messages, explicit push/PR confirmation, and optional PR worktrees. `/git-guided-workflow` emits a transient tab-scoped activation request that the browser validates and consumes before generic status rendering; the browser requires the extension-owned native generation commands and has no prompt-only launch fallback. The HTTP server authoritatively rejects the exact command admission while the tab is streaming, compacting, has pending messages, or already has a pending Guided Git launch, bypassing generic compaction queueing. A browser-generated UUID is stored in one short-lived server record and added only to the trusted live event envelope; the canonical four-field extension payload remains unchanged, and only the browser holding the matching one-shot permit can consume the event. When the review extension is loaded/enabled, both `git add .` and accepting the current staged set send `/aur-review start --scope staged --origin guided-git` to the same tab. Only its matching approval advances to message generation. The browser and server recheck the approved domain-separated staged-content hash before message generation, commit, and PR-worktree transfer; drift, missing hashes, or hash-check errors return to Stage and require a new review. A decline returns to staging and rejects an unchanged declined staged hash until corrected content is restaged. Guided Git never stages, commits, or pushes remediation automatically. The extension remains the decision authority; direct API callers are not granted an approval by this browser workflow.
|
|
321
319
|
- Browser support for Pi extension UI prompts, widgets, status updates, `/btw` side-question output widgets with optional context transfer/live steering, browser notifications when a tab needs an extension UI response, and an optional side-panel toggle for agent-done notifications.
|
|
322
|
-
- Localhost-only
|
|
320
|
+
- Localhost-only separate Pi and Web UI native plans with digest-bound confirmation, fail-closed ownership checks, shared effect-root fencing, durable per-command receipts, partial/unknown results, and selective automatic restart after health verification. PATH Pi 0.87.1 is the initially proven command driver. Combined actions, optional-companion sweeps and managed-runtime activation are retired.
|
|
323
321
|
- Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
|
|
324
|
-
- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay
|
|
322
|
+
- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay for ordinary server restart. Native updates use an inline spinner and durable per-job status.
|
|
325
323
|
Web UI keeps a packaged parity matrix at `lib/WEBUI_TUI_NATIVE_PARITY.json` and exposes it at `GET /api/native-parity`.
|
|
326
324
|
Discovery-path rules: at most 24 paths and direct children only (no recursive walk). Shell discovery supports `.sh`, `.bash`, `.zsh`, `.fish`, and matching extensionless shebang files. Python discovery supports `.py` and extensionless Python-shebang files, exposing `uv run` and/or the available `python3`/`python` interpreter. Required interpreters must be installed locally; duplicates and built-in overlaps do not duplicate menu entries. Absolute, drive/UNC, `..`, null-byte, missing, non-directory, or symlinked-outside-the-project paths are rejected. Stale or invalid stored paths surface diagnostics in the dialog instead of being scanned. `POST /api/app-runner-config` accepts either `{ "runner": { ... } }` or `{ "searchPaths": [...] }` (not both in one request) and preserves the other field.
|
|
327
325
|
|
|
@@ -363,7 +361,7 @@ Focused checks are `node tests/session-tree-event-targets.test.mjs`, `node tests
|
|
|
363
361
|
- Localhost-only `POST /api/optional-feature-install-batch` for a bounded allowlisted `featureIds` batch. It requires the current audit `revision`, installs sequentially, reports ordered per-feature and aggregate results, and accepts `migration: true` for the combined restore flow.
|
|
364
362
|
- Localhost-only `POST /api/optional-feature-migration/recheck` for a bounded read-only audit and `POST /api/optional-feature-migration/dismiss` for persisted **Later** state.
|
|
365
363
|
- `GET /api/git-workflow/staged-content?tab=<tabId>` for the read-only bounded staged-content hash used by Guided Git approval binding.
|
|
366
|
-
- `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, `GET /api/update/transactions/<transactionId
|
|
364
|
+
- `GET /api/update-status`, localhost-only `POST /api/update/plan`, `POST /api/update/apply`, and `GET /api/update/transactions/<transactionId>` for exact planning, digest-bound apply, and durable receipts/status. The retired rollback route returns `410 Gone`; native package changes cannot be undone by switching a pointer. Legacy `POST /api/update` and `POST /api/component-update` mutation return `410 Gone`.
|
|
367
365
|
- `GET /api/network`, localhost-only `POST /api/network/open`, localhost-only `POST /api/network/close`, `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for trusted-LAN exposure and optional 4-digit PIN authentication when serving non-local browser clients.
|
|
368
366
|
On hosts with WebKit's system libraries installed, provision it and include its project explicitly with `npx playwright install webkit && PI_WEBUI_TEST_WEBKIT=1 npm run test:browser`. The browser suite is intentionally separate from `npm test`; it covers browser-only geometry, flag/rollback, and scoped axe checks without making ordinary Node/static tests download browser engines.
|
|
369
367
|
When enabled, each click obtains a fresh Turnstile token and UUID-v4, then posts only `{ schemaVersion, idempotencyKey, turnstileToken, issue }` to `POST /v1/submissions`. `issue` is the selected structured wizard state (`categoryId`, `componentId`, `templateId`, `summary`, and declared fields); editable canonical title/body, repository, labels, verdicts, callback URLs, and credentials are never sent. The returned status capability remains only in an opaque in-memory refresh handle for the open dialog. Nothing in this flow uses `localStorage`, `sessionStorage`, cookies, or draft persistence.
|
|
@@ -449,15 +447,13 @@ The extension launches its JavaScript bootstrap with the current Node executable
|
|
|
449
447
|
|
|
450
448
|
`/webui-status` reports the URL, online state, network exposure, and Remote PIN auth state. `detailed` adds tabs, sessions, models/providers, and recent backend events.
|
|
451
449
|
|
|
452
|
-
###
|
|
450
|
+
### Native Pi and Web UI updates
|
|
453
451
|
|
|
454
|
-
The
|
|
452
|
+
The browser plans one `pi` or `webui` action, confirms the returned executable/argv, installation roots and frozen execution context, then applies only the ID and digest. It observes `GET /api/update/transactions/<id>` and uses local-only update-status discovery of native jobs after reconnect. Discovery errors block new action controls. Receipts expose `changed`, `unchanged`, `failed`, or `unknown` per command; verified targets and the final phase distinguish completed native commands from healthy active installations and completed restart. A `restart-authorized` phase is waiting for idle, and `restart-pending` has not confirmed successor health. `unknown` retains exclusion for manual recovery; no inferred retry or restart.
|
|
455
453
|
|
|
456
|
-
|
|
454
|
+
Only PATH Pi 0.87.1 has verified initial CLI semantics. npm-global Web UI and Pi user npm sources may update independently. Pi user scope excludes project settings with `--no-approve`; exact pins and unsupported owners are skipped. The detached native runner and receipts live outside mutable installations. Shells use exact bound interpreters and argument arrays, not browser-supplied command strings. On Windows a private detached Node guardian owns ordinary hidden PowerShell: detached PowerShell silently skipped its command on the tested host, and ordinary PowerShell alone did not survive initiator exit. The guardian records a verified pre-shell launch refusal separately from any uncertain post-spawn completion. The context fingerprint includes scoped registries and npm-reported user/global configuration paths. Shared physical-root fences include the selected active Pi root independently of PATH Pi and keep known work idle during mutation and selective restart. Ordinary server restart holds a counted admission lease through handoff; native restart requires bounded RPC readiness and matching saved session files before releasing the fence. Native lifecycle scripts are not sandboxed, and bounded redaction cannot guarantee removal of arbitrary secrets.
|
|
457
455
|
|
|
458
|
-
The
|
|
459
|
-
|
|
460
|
-
Restart descriptors use a private owner-readable random file, are read and deleted once, and support up to 256 descriptors. Startup retries transient `EADDRINUSE` with bounded backoff. Retention preserves current, previous, locked, journal-referenced, and recent healthy runtimes; zero downtime is not promised, but automatic rollback restores the previous reachable runtime after a bounded interruption.
|
|
456
|
+
The launcher can migrate legacy `current.json` and `previous.json` pointers only to a canonical compatible equal-or-newer installed candidate after an isolated real startup and restored-tab probe. A subsequent candidate upgrade must pass the same probe and advances the accepted version floor atomically without replacing the original pointer backups. Both pointers receive immutable backups; old files and runtimes remain for fallback. An incompatible, unhealthy or older candidate retains legacy startup and needs manual attention. This migration is not native-update rollback. Ordinary tab restoration still uses the retained restart descriptor. Startup retries transient `EADDRINUSE` with bounded backoff.
|
|
461
457
|
|
|
462
458
|
## Standalone CLI
|
|
463
459
|
|
|
@@ -933,9 +929,93 @@ Keep this browser configuration disabled until the gateway's exact-origin CORS p
|
|
|
933
929
|
- **Remote browser asks for a PIN:** read it from the optional **Remote WebUI** side-panel controls, `/webui-status`, `/remote status`, or the local Web UI server log. Disable the toggle from localhost to remove the PIN gate.
|
|
934
930
|
- **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.
|
|
935
931
|
|
|
936
|
-
##
|
|
932
|
+
## Native update workflow
|
|
933
|
+
|
|
934
|
+
This diagram describes the new native-command updater in the current working tree, not a released or fully accepted implementation. The [implementation plan](plans/planned/simplify-updates.md) still lists integrated validation, independent reviews, and the completion report as pending. The UI handoff reports browser tests blocked by missing Playwright. Durable job discovery and the separate PATH Pi preview fields are now present in the server, superseding the handoff's earlier integration-gap notes.
|
|
935
|
+
|
|
936
|
+
```mermaid
|
|
937
|
+
flowchart TD
|
|
938
|
+
Start([Choose Update Pi or Update Web UI]) --> Local{Localhost request?}
|
|
939
|
+
Local -->|No| Refuse[Refuse update execution]
|
|
940
|
+
Local -->|Yes| Discover[Check durable job history]
|
|
941
|
+
Discover -->|Unsettled job or discovery error| Observe[Observe existing job or show recovery guidance<br/>Do not launch another update]
|
|
942
|
+
Discover -->|No blocking job| Action{Which action?}
|
|
943
|
+
|
|
944
|
+
Action -->|Pi| Pi[Verified PATH Pi only<br/>pi update]
|
|
945
|
+
Action -->|Web UI| Web[Proven npm-global and Pi-user Web UI copies<br/>Global first, then user copy; deduplicate roots]
|
|
946
|
+
Pi --> Eligible{Any eligible target?}
|
|
947
|
+
Web --> Eligible
|
|
948
|
+
Eligible -->|No| Manual[Show skipped targets and manual guidance<br/>No command runs]
|
|
949
|
+
Eligible -->|Yes| Preview[Preview exact commands, roots and execution context<br/>Show active versus PATH versions and script warning]
|
|
950
|
+
Preview --> Confirm{Confirm this plan?}
|
|
951
|
+
Confirm -->|No| Cancel([No update])
|
|
952
|
+
Confirm -->|Yes| Guard[Revalidate confirmed context<br/>Lock affected roots and block new affected work<br/>Require known affected work to be idle]
|
|
953
|
+
Guard -->|Stale, busy, unsafe or known launch failure| Stop[No update command started<br/>Release any safely acquired fence and show reason]
|
|
954
|
+
Guard -->|Ready| Launch[Start detached runner outside updated package roots<br/>Background PowerShell on Windows or Bash on Linux]
|
|
955
|
+
|
|
956
|
+
Launch --> Command[Recheck target and driver identity<br/>Run the next fixed command]
|
|
957
|
+
Command --> Evidence{Command completion proven?}
|
|
958
|
+
Evidence -->|No or evidence lost| Unknown[Unknown: retain update fence<br/>No retry or automatic restart<br/>Manual host recovery required]
|
|
959
|
+
Evidence -->|Yes| Receipt[Persist bounded output and command receipt<br/>Changed, unchanged or failed]
|
|
960
|
+
Receipt --> More{Another target?}
|
|
961
|
+
More -->|Yes, even after a known failure| Command
|
|
962
|
+
More -->|No| Verify[Independently verify installed identity and health<br/>Also check changed active bundled Pi dependencies]
|
|
963
|
+
Verify --> Active{Healthy changed active component?}
|
|
964
|
+
Active -->|No| Done[Release fence and retain final result<br/>Success, partial, failed or unchanged]
|
|
965
|
+
Active -->|Yes, even with another target's failure| Idle[Wait for affected work to be idle<br/>Keep the fence through restart]
|
|
966
|
+
Idle --> Restart[Reload only affected managed Pi tabs<br/>Restart Web UI only when its active copy changed<br/>Preserve sessions; leave unrelated runtimes alone]
|
|
967
|
+
Restart --> Restored{Expected runtime and sessions verified?}
|
|
968
|
+
Restored -->|Yes| Done
|
|
969
|
+
Restored -->|Uncertain or failed| Unknown
|
|
970
|
+
|
|
971
|
+
Reconnect([Browser reload or reconnect]) -.-> Discover
|
|
972
|
+
Launch -.->|Launch outcome uncertain| Unknown
|
|
973
|
+
Verify -.->|Original finalizing owner lost| Unknown
|
|
974
|
+
Observe -.->|Completion or ownership cannot be proven| Unknown
|
|
975
|
+
|
|
976
|
+
classDef normal fill:#e8f1ff,stroke:#315d92,color:#142c48;
|
|
977
|
+
classDef caution fill:#fff4d6,stroke:#9b6b12,color:#513a0b;
|
|
978
|
+
classDef blocked fill:#fde8e8,stroke:#a63c3c,color:#651e1e;
|
|
979
|
+
classDef finished fill:#e5f5ea,stroke:#37794b,color:#1b4729;
|
|
980
|
+
class Preview,Guard,Launch,Command,Receipt,Verify,Idle,Restart normal;
|
|
981
|
+
class Observe,Manual caution;
|
|
982
|
+
class Refuse,Stop,Unknown blocked;
|
|
983
|
+
class Done,Cancel finished;
|
|
984
|
+
```
|
|
985
|
+
|
|
986
|
+
### Commands and scope
|
|
987
|
+
|
|
988
|
+
These are readable command forms. Execution uses the preview's absolute, verified executable and driver, not a fresh shell PATH lookup.
|
|
989
|
+
|
|
990
|
+
| Action | Command | Scope |
|
|
991
|
+
| --- | --- | --- |
|
|
992
|
+
| Update Pi | `pi update` | Verified PATH Pi installation only. Initial automatic support is limited to proven Pi 0.87.1 semantics and ownership. |
|
|
993
|
+
| Update Web UI, npm-global | `npm -g update @firstpick/pi-package-webui` | Proven global npm prefix. |
|
|
994
|
+
| Update Web UI, Pi-user | `pi update --extension npm:@firstpick/pi-package-webui --no-approve` | Verified PATH Pi drives the configured user installation. Preserve its npm range or tag and agent directory; exclude project settings. |
|
|
995
|
+
|
|
996
|
+
- Project copies, exact pins, Git/local sources, linked or unproven installations, and unsupported command drivers receive skipped/manual guidance. There is no combined Pi/Web UI action or automatic optional-companion update.
|
|
997
|
+
- A known failure does not prevent the next independent Web UI target from being attempted after revalidation. Unknown completion stops the sequence and retains exclusion.
|
|
998
|
+
- Launch is not completion, and command exit is not health verification. An unchanged, failed or unverified active installation does not auto-restart. A Web UI dependency-only change can still require a verified active Pi reload.
|
|
999
|
+
- Reconnect observes the same durable job; it never replays commands. Server discovery, not browser storage, selects relevant jobs. If the original server owner dies before finalization, another instance does not take over automatically.
|
|
1000
|
+
- Native lifecycle scripts run with existing configuration and without automatic elevation. Scripts are not sandboxed, dependencies may change, and bounded output redaction is not a guarantee that arbitrary script output contains no secrets.
|
|
1001
|
+
|
|
1002
|
+
### Legacy startup migration
|
|
1003
|
+
|
|
1004
|
+
Migration is a separate launcher decision, not a rollback stage in the native update job.
|
|
1005
|
+
|
|
1006
|
+
```mermaid
|
|
1007
|
+
flowchart LR
|
|
1008
|
+
Boot[Start through updated launcher] --> Legacy{Legacy pointer present?}
|
|
1009
|
+
Legacy -->|No| Installed[Start installed Web UI]
|
|
1010
|
+
Legacy -->|Yes| Check{Installed candidate is compatible,<br/>equal or newer, and passes<br/>isolated startup and session restoration?}
|
|
1011
|
+
Check -->|Yes| Backup[Back up both pointer files<br/>Record migration; retain old pointers and runtimes]
|
|
1012
|
+
Backup --> Installed
|
|
1013
|
+
Check -->|No or interrupted| Fallback[Keep legacy launch path<br/>Show manual guidance]
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
The retired updater used exact-target staging, managed activation, and automatic rollback. Native package updates replace that flow and do not promise automatic rollback. Retaining legacy pointers and runtimes protects the migration fallback only.
|
|
937
1017
|
|
|
938
|
-
|
|
1018
|
+
Source references: [plan and launch](lib/update/native-jobs.mjs), [detached runner](bin/pi-webui-native-update-runner.mjs), [cross-process admission](lib/update/coordination.mjs), [job discovery](lib/update/discovery.mjs), [server verification and restart](bin/pi-webui.mjs), and [legacy migration](lib/update/migration.mjs). For user instructions, see [Pi and Web UI updates](TECHNICAL.md#pi-and-web-ui-updates).
|
|
939
1019
|
|
|
940
1020
|
## Session continuity
|
|
941
1021
|
|
package/README.md
CHANGED
|
@@ -296,7 +296,7 @@ Use the optional Remote Web UI package when you need trusted-LAN access and PIN
|
|
|
296
296
|
|
|
297
297
|
## Technical details
|
|
298
298
|
|
|
299
|
-
|
|
299
|
+
To update, select **Update Pi** or **Update Web UI** in the Control Deck. Read the preview of installations and commands, including skipped installations, before confirming. Only localhost can start an update. Finish work in affected tabs first; native package updates may run lifecycle scripts under your existing configuration and cannot be automatically rolled back. The small activity indicator and command results remain available after reconnect. If the status is unknown, check the host before trying again.
|
|
300
300
|
|
|
301
301
|
> **Before downgrading:** stop the Web UI and back up `~/.pi/webui/settings.json`. Older releases do not understand the two-sided Control Deck layout and can overwrite it. Re-upgrade before restoring the backup.
|
|
302
302
|
|
package/TECHNICAL.md
CHANGED
|
@@ -79,13 +79,15 @@ Common overrides:
|
|
|
79
79
|
|
|
80
80
|
Private runtime and recovery files should not be edited or removed while Web UI tabs are active.
|
|
81
81
|
|
|
82
|
-
##
|
|
82
|
+
## Pi and Web UI updates
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
Use **Update Pi** and **Update Web UI** separately from localhost. Each action previews the exact executable, command, affected installation roots, working directory, Pi agent directory, npm prefix where relevant, and skipped installations. Confirm only after reviewing that list. If an executable, owner, or installation changes before launch, request a new preview. A small spinner means the job is still being checked, not a percentage estimate. Its ID, bounded command output and per-installation result remain visible after reconnect.
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
**Update Pi** runs `pi update` with the verified PATH Pi, not necessarily the Pi currently running your tabs. Initial automatic support is proven only for PATH Pi 0.87.1; other versions get manual or unproven guidance. The separately selected, bundled, or explicit Pi runtime is not silently replaced. **Update Web UI** runs `npm -g update @firstpick/pi-package-webui` for a proven npm-global installation and `pi update --extension npm:@firstpick/pi-package-webui --no-approve` for a proven Pi user installation, using its configured npm range or tag. Eligible installations run in sequence. Project copies, exact pins, Git/local sources and unproven ownership need manual attention. No optional companion packages are included.
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
Finish known affected Pi work before updating. PowerShell or Bash runs in the background; a desktop terminal is not needed. Native package lifecycle scripts run with your existing configuration and are not sandboxed. The updater does not elevate permissions. Native package updates may change dependencies and cannot be automatically rolled back. The displayed output is bounded and masks common credential patterns, but arbitrary script output may still expose secrets. Do not paste it into a public issue without checking it.
|
|
89
|
+
|
|
90
|
+
A changed, verified healthy active component restarts automatically once all commands finish and affected work is idle, even when another installation failed. Unchanged, failed or unverified active installations do not auto-restart. Partial and unknown results stay visible after reconnect; unknown completion blocks retry and restart until you verify and recover on the host. A short interruption is possible; zero downtime is not promised. The launcher can migrate old managed-runtime pointers only to a validated, compatible equal-or-newer installed Web UI. It retains pointer backups and old runtimes. A failed validation or downgrade keeps the old launch path with manual guidance; this is not rollback of a native update.
|
|
89
91
|
|
|
90
92
|
## Session continuity
|
|
91
93
|
|
|
@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
|
|
|
3
3
|
import { homedir } from "node:os";
|
|
4
4
|
import path from "node:path";
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
|
6
|
-
import {
|
|
6
|
+
import { migrateLegacyBootstrap } from "../lib/update/migration.mjs";
|
|
7
7
|
|
|
8
8
|
const bootstrapRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
|
9
9
|
const bootstrapServer = path.join(bootstrapRoot, "bin", "pi-webui.mjs");
|
|
@@ -18,8 +18,11 @@ if (process.argv[2] === "agent") {
|
|
|
18
18
|
process.exitCode = 1;
|
|
19
19
|
}
|
|
20
20
|
} else {
|
|
21
|
-
const
|
|
22
|
-
|
|
21
|
+
const selection = await migrateLegacyBootstrap(agentDir, bootstrapRoot);
|
|
22
|
+
if (!selection.migrated && selection.reason !== "no-legacy-pointer") {
|
|
23
|
+
console.warn(`Pi Web UI retained the previous runtime: ${selection.reason}. Inspect the installed package and pointer backups before manual migration.`);
|
|
24
|
+
}
|
|
25
|
+
const serverEntry = selection.serverEntry || bootstrapServer;
|
|
23
26
|
const child = spawn(process.execPath, [serverEntry, ...process.argv.slice(2)], {
|
|
24
27
|
cwd: process.cwd(), env: process.env, stdio: "inherit", windowsHide: true,
|
|
25
28
|
});
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// This private capsule entry outlives the original Web UI server on Windows.
|
|
3
|
+
// PowerShell itself cannot run -Command in a detached process group here.
|
|
4
|
+
import { spawn } from "node:child_process";
|
|
5
|
+
import { open } from "node:fs/promises";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { fileURLToPath } from "node:url";
|
|
8
|
+
|
|
9
|
+
async function launch() {
|
|
10
|
+
const jobDir = process.env.PI_WEBUI_UPDATE_JOB;
|
|
11
|
+
const shell = process.env.PI_WEBUI_UPDATE_SHELL;
|
|
12
|
+
if (!jobDir || !shell || !path.isAbsolute(jobDir) || !path.isAbsolute(shell)) throw new Error("Private update guardian lacks bound paths.");
|
|
13
|
+
const args = ["-NoProfile", "-NonInteractive", "-Command",
|
|
14
|
+
"$env:PATHEXT = $env:PI_WEBUI_UPDATE_PATHEXT; & $env:PI_WEBUI_UPDATE_NODE $env:PI_WEBUI_UPDATE_RUNNER $env:PI_WEBUI_UPDATE_JOB; exit $LASTEXITCODE"];
|
|
15
|
+
const child = spawn(shell, args, { cwd: process.env.PI_WEBUI_UPDATE_CWD, env: process.env,
|
|
16
|
+
detached: false, windowsHide: true, stdio: "ignore" });
|
|
17
|
+
const started = await new Promise((resolve) => {
|
|
18
|
+
child.once("spawn", () => resolve(true));
|
|
19
|
+
child.once("error", () => resolve(false));
|
|
20
|
+
});
|
|
21
|
+
if (!started) {
|
|
22
|
+
// A pre-spawn error proves that PowerShell and all native commands never ran.
|
|
23
|
+
const handle = await open(path.join(jobDir, "guardian-launch-failed.json"), "wx", 0o600);
|
|
24
|
+
try {
|
|
25
|
+
await handle.writeFile(`${JSON.stringify({ transactionId: path.basename(jobDir), guardianPid: process.pid, noShellStarted: true })}\n`);
|
|
26
|
+
await handle.sync();
|
|
27
|
+
} finally { await handle.close(); }
|
|
28
|
+
process.exitCode = 1;
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
const exit = await new Promise((resolve) => child.once("close", (code, signal) => resolve({ code, signal })));
|
|
32
|
+
if (exit.code !== 0 || exit.signal) process.exitCode = 1;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
36
|
+
launch().catch(() => { process.exitCode = 1; });
|
|
37
|
+
}
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// This file is copied to a private location before launch: it must never import
|
|
3
|
+
// files under an installation that a command can replace.
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import { spawn } from "node:child_process";
|
|
6
|
+
import { open, readFile, rename, rm, stat } from "node:fs/promises";
|
|
7
|
+
import path from "node:path";
|
|
8
|
+
import { fileURLToPath } from "node:url";
|
|
9
|
+
import { assertSafeNodeOptions, readUpdateContext } from "./pi-webui-update-context.mjs";
|
|
10
|
+
|
|
11
|
+
const OUTPUT_LIMIT = 16_000;
|
|
12
|
+
const confidentialValues = new Set();
|
|
13
|
+
function bounded(value) {
|
|
14
|
+
let text = String(value || "").slice(-OUTPUT_LIMIT)
|
|
15
|
+
.replace(/\u001b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "")
|
|
16
|
+
.replace(/\b((?:_?auth[_-]?token|api[_-]?key|password|secret|token)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]")
|
|
17
|
+
.replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, "$1[redacted]@");
|
|
18
|
+
const sensitive = Object.entries(process.env).filter(([key, secret]) =>
|
|
19
|
+
/(?:auth|token|password|secret|api[_-]?key)/i.test(key) && secret?.length >= 6)
|
|
20
|
+
.map(([, secret]) => secret).sort((a, b) => b.length - a.length);
|
|
21
|
+
for (const secret of [...new Set([...sensitive, ...confidentialValues])].sort((a, b) => b.length - a.length)) {
|
|
22
|
+
text = text.replaceAll(secret, "[redacted]");
|
|
23
|
+
}
|
|
24
|
+
return text;
|
|
25
|
+
}
|
|
26
|
+
async function persist(file, data) {
|
|
27
|
+
const temporary = `${file}.${process.pid}.tmp`;
|
|
28
|
+
try {
|
|
29
|
+
const handle = await open(temporary, "wx", 0o600);
|
|
30
|
+
try { await handle.writeFile(`${JSON.stringify(data)}\n`); await handle.sync(); } finally { await handle.close(); }
|
|
31
|
+
await rename(temporary, file);
|
|
32
|
+
} finally { await rm(temporary, { force: true }); }
|
|
33
|
+
}
|
|
34
|
+
async function digest(file) {
|
|
35
|
+
return createHash("sha256").update(await readFile(file)).digest("hex");
|
|
36
|
+
}
|
|
37
|
+
async function runCommand(command, args, cwd, env) {
|
|
38
|
+
return new Promise((resolve) => {
|
|
39
|
+
const output = { stdout: "", stderr: "" };
|
|
40
|
+
let settled = false;
|
|
41
|
+
let launchError = null;
|
|
42
|
+
const child = spawn(command, args, { cwd, env, shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
|
|
43
|
+
child.stdout?.on("data", (chunk) => { output.stdout = bounded(output.stdout + chunk); });
|
|
44
|
+
child.stderr?.on("data", (chunk) => { output.stderr = bounded(output.stderr + chunk); });
|
|
45
|
+
const finish = (code, signal, error) => {
|
|
46
|
+
if (settled) return;
|
|
47
|
+
settled = true;
|
|
48
|
+
resolve({ exitCode: code, signal: signal || null, error: bounded(error?.message || ""), ...output });
|
|
49
|
+
};
|
|
50
|
+
child.once("error", (error) => { launchError = error; });
|
|
51
|
+
// Never treat an error event as completion. Even failed spawns emit close;
|
|
52
|
+
// a launched command's streams must finish before we write a receipt.
|
|
53
|
+
child.once("close", (code, signal) => finish(code, signal, launchError));
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export async function runUpdateJob(jobDir) {
|
|
58
|
+
const { targets, cwd, transactionId, contextDigest, settingsPath, settingsDigest, npmConfigFiles, npmConfigDigest,
|
|
59
|
+
nodeDigest, npmDriver, npmDriverDigest } =
|
|
60
|
+
JSON.parse(await readFile(path.join(jobDir, "intent.json"), "utf8"));
|
|
61
|
+
const env = process.env;
|
|
62
|
+
for (const filename of npmConfigFiles || []) {
|
|
63
|
+
let text = "";
|
|
64
|
+
try { text = await readFile(filename, "utf8"); }
|
|
65
|
+
catch (error) { if (error.code !== "ENOENT") throw error; }
|
|
66
|
+
for (const line of text.split(/\r?\n/)) {
|
|
67
|
+
const match = line.match(/^\s*[^=]*(?:_auth|token|password)[^=]*=\s*(.*?)\s*$/i);
|
|
68
|
+
if (!match) continue;
|
|
69
|
+
const value = match[1].replace(/^['"]|['"]$/g, "");
|
|
70
|
+
const expanded = value.replace(/\$\{([^}]+)\}/g, (_, name) => env[name] || "");
|
|
71
|
+
if (expanded.length >= 6) confidentialValues.add(expanded);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
assertSafeNodeOptions(env);
|
|
75
|
+
if (env.BASH_ENV || env.ENV || !nodeDigest || await digest(process.execPath) !== nodeDigest) {
|
|
76
|
+
throw new Error("Confirmed Node interpreter or startup configuration changed.");
|
|
77
|
+
}
|
|
78
|
+
if (!/^[A-Za-z0-9._-]{1,128}$/.test(transactionId) || !Array.isArray(targets) || targets.length < 1 || targets.length > 2 || typeof cwd !== "string") {
|
|
79
|
+
throw new Error("Invalid private update intent.");
|
|
80
|
+
}
|
|
81
|
+
if (await stat(path.join(jobDir, "complete.json")).then(() => true, (error) => {
|
|
82
|
+
if (error.code === "ENOENT") return false;
|
|
83
|
+
throw error;
|
|
84
|
+
})) throw new Error("This update job already completed; replay is prohibited.");
|
|
85
|
+
let heartbeat = Promise.resolve();
|
|
86
|
+
const pulse = () => { heartbeat = heartbeat.then(() => persist(path.join(jobDir, "heartbeat.json"),
|
|
87
|
+
{ transactionId, pid: process.pid, at: new Date().toISOString() })); };
|
|
88
|
+
pulse();
|
|
89
|
+
const timer = setInterval(pulse, 1_000);
|
|
90
|
+
const receipts = [];
|
|
91
|
+
try {
|
|
92
|
+
for (let i = 0; i < targets.length; i++) {
|
|
93
|
+
const target = targets[i];
|
|
94
|
+
const receiptPath = path.join(jobDir, `${i}.receipt.json`);
|
|
95
|
+
// A started command without a receipt may still be running after a crash.
|
|
96
|
+
const started = await open(path.join(jobDir, `${i}.started.json`), "wx", 0o600);
|
|
97
|
+
try { await started.writeFile(`${JSON.stringify({ transactionId, id: target.id, at: new Date().toISOString() })}\n`); await started.sync(); }
|
|
98
|
+
finally { await started.close(); }
|
|
99
|
+
let result;
|
|
100
|
+
try {
|
|
101
|
+
const actualContext = await readUpdateContext({ env, settingsPath, npmConfigFiles });
|
|
102
|
+
if (actualContext.contextDigest !== contextDigest) throw new Error("Confirmed environment changed; no command was run.");
|
|
103
|
+
if (actualContext.settingsDigest !== settingsDigest) throw new Error("Confirmed Pi settings changed; no command was run.");
|
|
104
|
+
if (actualContext.npmConfigDigest !== npmConfigDigest) throw new Error("Confirmed npm routing configuration changed; no command was run.");
|
|
105
|
+
if (npmDriver && (!path.isAbsolute(npmDriver) || await digest(npmDriver) !== npmDriverDigest)) {
|
|
106
|
+
throw new Error("Confirmed npm driver changed; no command was run.");
|
|
107
|
+
}
|
|
108
|
+
if (!path.isAbsolute(target.command.command) || !Array.isArray(target.command.args) || !path.isAbsolute(target.driver) ||
|
|
109
|
+
await digest(target.driver) !== target.driverDigest) {
|
|
110
|
+
throw new Error("Confirmed command driver changed before launch; no command was run.");
|
|
111
|
+
}
|
|
112
|
+
const before = JSON.parse(await readFile(target.manifestPath, "utf8"));
|
|
113
|
+
if (before.name !== target.packageName || before.version !== target.beforeVersion) {
|
|
114
|
+
throw new Error("Confirmed installed package changed before launch; no command was run.");
|
|
115
|
+
}
|
|
116
|
+
result = await runCommand(target.command.command, target.command.args, cwd, env);
|
|
117
|
+
if (result.signal || (result.exitCode === null && !result.error)) {
|
|
118
|
+
result.status = "unknown";
|
|
119
|
+
result.error = "Native command termination could not be proven; update exclusion remains active.";
|
|
120
|
+
} else if (result.exitCode === 0 && !result.error) {
|
|
121
|
+
const after = JSON.parse(await readFile(target.manifestPath, "utf8"));
|
|
122
|
+
if (after.name !== target.packageName || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(after.version)) {
|
|
123
|
+
result.status = "failed";
|
|
124
|
+
result.error = "The installed package identity or version could not be verified.";
|
|
125
|
+
} else {
|
|
126
|
+
result.afterVersion = after.version;
|
|
127
|
+
result.status = after.version !== before.version ? "changed" : "unchanged";
|
|
128
|
+
}
|
|
129
|
+
} else result.status = "failed";
|
|
130
|
+
} catch (error) {
|
|
131
|
+
result = { status: "failed", error: bounded(error.message) };
|
|
132
|
+
}
|
|
133
|
+
const receipt = { transactionId, id: target.id, at: new Date().toISOString(), ...result };
|
|
134
|
+
await persist(receiptPath, receipt);
|
|
135
|
+
receipts.push(receipt);
|
|
136
|
+
if (receipt.status === "unknown") return receipts;
|
|
137
|
+
}
|
|
138
|
+
await persist(path.join(jobDir, "complete.json"), { transactionId, receipts: receipts.map(({ id, status, afterVersion }) => ({ id, status, afterVersion })) });
|
|
139
|
+
return receipts;
|
|
140
|
+
} finally {
|
|
141
|
+
clearInterval(timer);
|
|
142
|
+
await heartbeat;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
147
|
+
runUpdateJob(process.argv[2]).catch((error) => { console.error(bounded(error.message)); process.exitCode = 1; });
|
|
148
|
+
}
|