snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'main' into review-issue-48

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-07-13 19:48:21 +02:00
committed by GitHub
parent 050b053d23 6174cf381c
commit 4df7f430d4
50 changed files with 5012 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/faq.html
+12 -8
View File
@@ -131,8 +131,9 @@
<h2>Tools are failing, node is not found, or Pi cannot find commands</h2>
<p>
The shell environment needs to be set up so login shells have the required PATH entries for PI WEB, Pi,
and any tools your agents need. PI WEB services run commands through a non-interactive login shell, so
an interactive terminal can work while services fail.
and any tools your agents need. PI WEB services run commands through a non-interactive login shell owned
by systemd or launchd, so an interactive terminal—or even a caller-invoked login shell—can work while the
native service fails.
</p>
<div class="code-card">
<div class="copy-row">
@@ -156,14 +157,17 @@
<article id="doctor-fails" class="faq-item">
<h2>What does <code>pi-web doctor</code> check?</h2>
<p>
It checks whether the service shell and native service environment can find Node 22+, npm, Pi, and the Pi
Web binaries. It also prints installed and running PI WEB versions when available, reports optional ripgrep
availability for faster all-file <code>@</code>-mention suggestions, uses a bounded filesystem fallback when
ripgrep is unavailable, and reports user service lingering when relevant for server-style installs.
It keeps two kinds of checks separate. General login-shell readiness covers Node 22+, npm, Pi, and optional
ripgrep. Native-service diagnostics validate only the exact prerequisites of the selected service plan in
the real systemd user-manager or launchd <code>gui/&lt;uid&gt;</code> context. Development installs follow their
installed checkout plan; production checks are clearly labelled prospective when the installed executable
strategy cannot be reconstructed safely.
</p>
<p>
If something works in your terminal but fails in doctor, treat that as a login-shell PATH mismatch and
move the setup earlier in your shell startup chain.
Missing plan requirements fail doctor and include login-file guidance. Manager, timeout, malformed-output,
and cleanup failures are reported as probe infrastructure problems rather than being mislabeled as PATH
drift. On unsupported/manual-only platforms, native-service drift checks are skipped. Doctor also prints
installed and running PI WEB versions and reports systemd lingering when relevant.
</p>
</article>
docs/index.html
+2 -2
View File
@@ -138,8 +138,8 @@
# laptop, phone, tablet — same live sessions
<span class="prompt">$</span> pi-web doctor
✓ login shell can find node >= 22
✓ native service shell can find pi
✓ caller login shell can find node >= 22
✓ native-service plan requirements pass in manager context
✓ ready for persistent agent work</code></pre>
</aside>
</div>
docs/install.html
+6 -2
View File
@@ -112,8 +112,11 @@
</ul>
<div class="callout warning">
<strong>Important PATH detail:</strong>
PI WEB services run through your login shell with <code>-lc</code>. Setup that only lives in interactive shell
files or prompt hooks may not be visible to services. Run <code>pi-web doctor</code> after installing.
PI WEB services run through a non-interactive login shell with <code>-lc</code>. Setup that only lives in
interactive shell files or prompt hooks may not be visible to the systemd or launchd manager. The installer
probes the safely verifiable requirements of the exact candidate plan in that manager context before changing
config or replacing services. Arbitrary configured command overrides are preserved but not executed by
preflight; run <code>pi-web doctor</code> later to repeat plan-specific diagnostics.
</div>
</section>
@@ -134,6 +137,7 @@
<span class="prompt">$</span> pi-web doctor</code></pre>
</div>
<p>Then open <a href="http://127.0.0.1:8504">http://127.0.0.1:8504</a>.</p>
<p>If preflight fails, no config or existing services are changed. Follow the detected shell guidance: zsh services read <code>~/.zprofile</code>, not interactive-only <code>~/.zshrc</code>; bash uses <code>~/.bash_profile</code> or <code>~/.profile</code>.</p>
<p>On Linux servers, also consider <code>sudo loginctl enable-linger "$USER"</code> so user services survive logout/reboot.</p>
</section>
docs/plugins.html
+5 -2
View File
@@ -250,11 +250,14 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
<h3>Updates</h3>
<p>
<strong>Updates</strong> adds a conditional <strong>Updates</strong> workspace tab with PI WEB update,
restart, and installed-service guidance. It is built into PI WEB, enabled by default, and uses the
selected machine's plugin copy when machine federation is active.
restart, and installed-service guidance, plus a <strong>Check for PI WEB Updates</strong> action. It is
built into PI WEB, enabled by default, and uses the selected machine's plugin copy when machine
federation is active.
</p>
<ul>
<li>Plugin id: <code>updates</code></li>
<li>Selected-machine status refreshes every 15 minutes while a browser tab is connected.</li>
<li>Automatic npm release lookups are cached for six hours; the action bypasses the caches and checks immediately.</li>
</ul>
<div class="code-card">
<div class="copy-row">
docs/plugins.md
+15 -3
View File
@@ -202,9 +202,11 @@ Built-in plugins can be managed from **Settings → PI WEB plugins** or with the
### Updates
**Plugin id:** `updates`
**What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance.
**What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance, plus a **Check for PI WEB Updates** action for the selected machine.
Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab only appears for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → PI WEB plugins** or set:
While a browser tab is connected, PI WEB refreshes the selected machine's status every 15 minutes. npm release lookups are cached on that machine for six hours, so the automatic refresh normally contacts npm at most once in that window. Run **Check for PI WEB Updates** from the action palette to bypass both caches and check immediately. Operator settings that skip remote version checks, such as `PI_WEB_OFFLINE`, are still respected.
Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab and action only appear for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → PI WEB plugins** or set:
```json
{
@@ -347,7 +349,15 @@ A plugin can fetch its own static assets with URLs under:
/pi-web-plugins/<plugin-id>/<path-inside-plugin-root>
```
PI WEB prevents asset path traversal outside the plugin root. JavaScript, JSON, CSS, and HTML get appropriate content types; other files are served as octet-stream.
Prefer module-relative asset URLs so they also work for remote machine plugins. For example, a built plugin module can reference an SVG shipped beside it:
```js
const iconUrl = new URL("./assets/icon.svg", import.meta.url);
```
The final installed plugin package must contain `assets/icon.svg` at that path relative to the final built module. PI WEB serves files that already exist in the package; it does not copy a source `public/` directory or apply Vite-style public-directory semantics. Configure the plugin build and package contents to emit or copy the asset into its final module-relative location.
PI WEB prevents asset path traversal outside the plugin root. JavaScript, JSON, CSS, HTML, and SVG files get appropriate content types; unknown file types are served as octet-stream.
## Plugin module shape
@@ -466,6 +476,7 @@ interface PluginRuntimeContext {
openTerminal: (options?: { terminalId?: string }) => void;
refreshFiles: () => void | Promise<void>;
refreshGit: () => void | Promise<void>;
checkForPiWebUpdates?: () => void | Promise<void>;
startSession: () => void | Promise<void>;
archiveSession: () => void | Promise<void>;
stopActiveWork: () => void | Promise<void>;
@@ -480,6 +491,7 @@ Notes:
- `enabled` is evaluated when the action palette asks for actions.
- `selectWorkspaceTool()` expects a qualified panel id such as `my-plugin:workspace.info`.
- `openTerminal()` switches to the built-in terminal panel. Pass `{ terminalId }` to deep-link to a specific terminal.
- `checkForPiWebUpdates()` forces a fresh update check on the selected machine and refreshes `state.piWebStatus`. It is optional so plugins remain compatible with older PI WEB hosts.
- Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. Anything else is experimental: it may become public API later, change shape, or disappear.
### Prompt editor API