@vincenthanxiaodu/pi-web 1.202608.1

package/examples/workspace-provider-plugin/README.md

@@ -0,0 +1,52 @@
+# PI WEB dual-entry workspace-provider example
+
+This standalone package is a copyable starting point for a trusted PI WEB plugin with both browser API v2 and server API v1 entries. It claims only projects that opt in with a marker file, publishes non-secret metadata to the browser, and demonstrates a browser request routed to the server provider that owns the workspace.
+
+The example imports only the supported package declarations:
+
+- `@vincenthanxiaodu/pi-web/plugin-api`
+- `@vincenthanxiaodu/pi-web/server-plugin-api`
+
+It requires PI WEB `1.202608.1` or newer, the first release that provides those entrypoints and browser API v2.
+
+## Build and install
+
+Copy `examples/workspace-provider-plugin/` out of the PI WEB repository or installed `@vincenthanxiaodu/pi-web` package, then run:
+
+```bash
+npm install
+npm run build
+mkdir -p ~/.pi-web/plugins
+ln -s "$PWD" ~/.pi-web/plugins/example-workspaces
+```
+
+If `PI_WEB_DATA_DIR` is set, link into `$PI_WEB_DATA_DIR/plugins` instead. The link name must be a valid plugin id and must not collide with another package.
+
+Opt one registered PI WEB project into this example provider:
+
+```bash
+mkdir -p /absolute/path/to/project/.pi-web
+touch /absolute/path/to/project/.pi-web/example-workspace-provider
+```
+
+Then restart the target session daemon and reload the browser:
+
+```bash
+systemctl --user restart pi-web-sessiond
+```
+
+Restarting `pi-web-sessiond.service` may interrupt active sessions and runtime ownership. A browser or web/API restart alone does not activate a server entry.
+
+Open the opted-in project. The **Example Provider** panel displays the public marker metadata and its button calls the owning server provider's `summary` operation. Remove the marker and restart sessiond (or trigger a later workspace resolution) to stop claiming that project.
+
+## Boundary demonstrated by the package
+
+`package.json` declares:
+
+- browser module `dist/browser/index.js` with `browserRoot: "dist/browser"`;
+- server module `dist/server.js`, outside the browser root;
+- `machineSpecific: true`, required for a dual browser/server entry.
+
+Only files under `dist/browser/` can be served through this plugin's browser asset route. Source, package metadata, the server module, and dependencies remain outside that route. Keep secrets out of `publicMetadata`: it is visible to every browser script and API consumer.
+
+The server provider intentionally does not advertise workspace removal. See the canonical plugin guide for removal-plan shell and completion semantics, package limits, federation behavior, and the complete API contract: <https://pi-web.dev/plugins>.

package/examples/workspace-provider-plugin/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pi-web-example-workspace-provider",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@vincenthanxiaodu/pi-web": "^1.202608.1",
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3"
+  },
+  "piWeb": {
+    "plugins": [
+      {
+        "id": "example-workspaces",
+        "browserRoot": "dist/browser",
+        "module": "dist/browser/index.js",
+        "serverModule": "dist/server.js",
+        "machineSpecific": true
+      }
+    ]
+  }
+}

package/examples/workspace-provider-plugin/src/browser/index.ts

@@ -0,0 +1,69 @@
+import type { JsonObject, PiWebPlugin, WorkspacePanelContext } from "@vincenthanxiaodu/pi-web/plugin-api";
+
+const summaries = new Map<string, string>();
+
+const plugin: PiWebPlugin = {
+  apiVersion: 2,
+  name: "Example Workspace Provider",
+  activate: ({ pluginId, runtimePluginId, html }) => ({
+    contributions: {
+      actions: [
+        {
+          id: "workspace.open",
+          title: "Open Example Workspace Provider",
+          enabled: ({ state }) => state.selectedWorkspace?.provider?.pluginId === pluginId,
+          run: ({ selectWorkspaceTool }) => {
+            selectWorkspaceTool(`${runtimePluginId}:workspace.example-provider`);
+          },
+        },
+      ],
+      workspacePanels: [
+        {
+          id: "workspace.example-provider",
+          title: "Example Provider",
+          visible: ({ workspace }) => workspace.provider?.pluginId === pluginId,
+          render: (context) => {
+            const marker = stringMetadata(context.workspace.provider?.metadata, "marker") ?? "unknown";
+            const summary = summaries.get(workspaceKey(context)) ?? "Request a summary from the owning server plugin.";
+            return html`
+              <section class="toolbar"><strong>Example workspace provider</strong></section>
+              <section class="viewer">
+                <p>This workspace is owned by <code>${pluginId}</code>.</p>
+                <p class="muted">Claim marker: <code>${marker}</code></p>
+                <button
+                  ?disabled=${context.backend === undefined}
+                  @click=${() => { void refreshSummary(context); }}
+                >Request backend summary</button>
+                <p aria-live="polite">${summary}</p>
+              </section>
+            `;
+          },
+        },
+      ],
+    },
+  }),
+};
+
+export default plugin;
+
+async function refreshSummary(context: WorkspacePanelContext): Promise<void> {
+  const key = workspaceKey(context);
+  try {
+    if (context.backend === undefined) throw new Error("The paired workspace backend is unavailable");
+    const result = await context.backend.request("summary", null);
+    if (typeof result !== "string") throw new Error("The workspace backend returned an invalid summary");
+    summaries.set(key, result);
+  } catch (error) {
+    summaries.set(key, error instanceof Error ? error.message : String(error));
+  }
+  context.host.requestRender();
+}
+
+function workspaceKey(context: WorkspacePanelContext): string {
+  return `${context.machine.id}:${context.workspace.id}`;
+}
+
+function stringMetadata(metadata: JsonObject | undefined, key: string): string | undefined {
+  const value = metadata?.[key];
+  return typeof value === "string" ? value : undefined;
+}

package/examples/workspace-provider-plugin/src/server.ts

@@ -0,0 +1,64 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  PiWebServerPlugin,
+  ProjectInput,
+  ProviderClaim,
+  ProviderRequestContext,
+  ProviderWorkspace,
+  WorkspaceProvider,
+} from "@vincenthanxiaodu/pi-web/server-plugin-api";
+
+const markerPath = ".pi-web/example-workspace-provider";
+
+const plugin: PiWebServerPlugin = {
+  apiVersion: 1,
+  name: "Example Workspace Provider",
+  activate({ pluginId, logger }) {
+    logger.info("Activating example workspace provider", { pluginId });
+    return { workspaceProvider: createWorkspaceProvider(pluginId) };
+  },
+};
+
+export default plugin;
+
+function createWorkspaceProvider(pluginId: string): WorkspaceProvider {
+  return {
+    async probe(project: ProjectInput, signal: AbortSignal): Promise<ProviderClaim> {
+      signal.throwIfAborted();
+      try {
+        await access(join(project.path, markerPath));
+        signal.throwIfAborted();
+        return "claim";
+      } catch (error) {
+        if (isMissingFile(error)) return "pass";
+        throw error;
+      }
+    },
+    async list(project: ProjectInput, signal: AbortSignal): Promise<ProviderWorkspace[]> {
+      signal.throwIfAborted();
+      return [{
+        key: "main",
+        path: project.path,
+        label: project.name,
+        isMain: true,
+        // This object is visible to every browser script and API consumer.
+        publicMetadata: { kind: "example", marker: markerPath },
+      }];
+    },
+    request(context: ProviderRequestContext) {
+      context.signal.throwIfAborted();
+      if (context.operation !== "summary") {
+        throw new Error(`Unsupported example workspace operation: ${context.operation}`);
+      }
+      return Promise.resolve(`${pluginId} owns ${context.workspace.label} at ${context.workspace.path}`);
+    },
+  };
+}
+
+function isMissingFile(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "code" in error
+    && Reflect.get(error, "code") === "ENOENT";
+}

package/examples/workspace-provider-plugin/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": false,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/extensions/README-pi-web-restart-migration.md

@@ -0,0 +1,45 @@
+# `/pi-web-restart` is now `/pi-web restart`
+
+The standalone `/pi-web-restart` command (a personal extension at
+`~/.pi/agent/extensions/pi-web-restart.ts`) is superseded by subcommands of the
+built-in `/pi-web` command.
+
+| Old | New |
+|---|---|
+| `/pi-web-restart` | `/pi-web restart` |
+| `/pi-web-restart all` | `/pi-web restart --all` |
+| `/pi-web-restart --update` | `/pi-web update` |
+| `/pi-web-restart --update all` | `/pi-web update --all` |
+| (new) | `/pi-web machines` — list machines with version and online state |
+| (new) | `/pi-web restart --machine=<name>` — one machine by name or id |
+| (new) | `/pi-web status --all` — every machine's version |
+
+## What changed beyond the name
+
+`--all` is now **hub-scoped and stated**. The old command fanned out from the
+machine list of whichever session it ran in, so the covered set depended on
+where you were standing. The new command asks the PI WEB server this session
+runs on to fan out over the machines *it* knows, and every report names that
+server plus each machine's outcome and version. Restart and update also have a
+visible home now: **Settings ▸ Machines ▸ Machines and updates**.
+
+## Removing the old extension
+
+Delete `~/.pi/agent/extensions/pi-web-restart.ts` and `/reload`. Nothing depends
+on it; the built-in command covers every case above.
+
+## Making the built-in command available
+
+The `/pi-web` command lives in this package's `extensions/` directory, which pi
+loads when the package is registered. Installing PI WEB from a release tarball
+does not register it, so the command is absent until the release directory is
+added as a local package:
+
+```
+# ~/.pi/agent/settings.json, "packages"
+"/home/you/pi-web-release/current"
+```
+
+Point it at the `current` symlink rather than a version directory, so the
+command follows the deployment instead of pinning to whichever release happened
+to be installed the day it was set up. Then `/reload`.

package/extensions/pi-web.ts

@@ -0,0 +1,324 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliPath = join(packageRoot, "dist", "cli.js");
+const serviceNames = ["pi-web-sessiond.service", "pi-web.service", "pi-web-ui-dev.service"];
+const macLogPaths = ["sessiond.log", "web.log", "ui-dev.log"].map((name) => join(homedir(), ".pi-web", "logs", name));
+
+const subcommands = [
+  "install",
+  "status",
+  "logs",
+  "restart",
+  "update",
+  "machines",
+  "start",
+  "stop",
+  "doctor",
+  "version",
+  "uninstall",
+  "open",
+  "help",
+] as const;
+
+type Subcommand = (typeof subcommands)[number];
+
+/**
+ * Subcommands that can address more than this machine.
+ *
+ * Fan-out is done by the PI WEB server, not here: the scope of "every machine"
+ * is then the machine list of one named server, which the report states, rather
+ * than whichever machine happened to own the session this command ran in.
+ */
+const FLEET_SUBCOMMANDS = new Set<Subcommand>(["restart", "update", "machines"]);
+
+interface FleetIdentity { machineId: string; name: string }
+interface FleetTargetReport extends FleetIdentity { kind: string; online: boolean; version?: string; piVersion?: string; error?: string }
+interface FleetReport { hub: FleetIdentity; machines: FleetTargetReport[] }
+interface FleetOutcome extends FleetIdentity { started: boolean; error?: string }
+interface FleetRunResponse { operation: string; hub: FleetIdentity; outcomes: FleetOutcome[] }
+
+interface ParsedFlags {
+  all: boolean;
+  machines: string[];
+  rest: string[];
+}
+
+function parseFlags(args: string[]): ParsedFlags {
+  const machines: string[] = [];
+  const rest: string[] = [];
+  let all = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index] ?? "";
+    if (arg === "--all" || arg === "all") { all = true; continue; }
+    if (arg.startsWith("--machine=")) { machines.push(arg.slice("--machine=".length)); continue; }
+    if (arg === "--machine") { const next = args[index + 1]; if (next !== undefined) { machines.push(next); index++; } continue; }
+    rest.push(arg);
+  }
+  return { all, machines, rest };
+}
+
+/**
+ * The PI WEB server this agent process can reach. A session runs on the machine
+ * that owns it, so this is that machine's server - which the report names, so a
+ * fan-out is never mistaken for one started from a different browser's hub.
+ */
+function piWebBaseUrl(): string {
+  const advertised = process.env["PI_WEB_BASE_URL"];
+  if (advertised !== undefined && advertised !== "") return advertised.replace(/\/$/, "");
+  const port = process.env["PI_WEB_PORT"];
+  return `http://127.0.0.1:${port !== undefined && port !== "" ? port : "8504"}`;
+}
+
+async function fleetRequest(path: string, init?: { method: string; body: unknown }): Promise<unknown> {
+  const response = await fetch(`${piWebBaseUrl()}${path}`, {
+    method: init?.method ?? "GET",
+    headers: { accept: "application/json", ...(init === undefined ? {} : { "content-type": "application/json" }) },
+    ...(init === undefined ? {} : { body: JSON.stringify(init.body) }),
+  });
+  if (!response.ok) throw new Error(`${init?.method ?? "GET"} ${path} failed: ${String(response.status)}`);
+  return await response.json();
+}
+
+/**
+ * Read the server's answer defensively.
+ *
+ * The response crosses a version boundary - an older or newer PI WEB may be
+ * answering - so the shape is checked rather than asserted, and a machine that
+ * does not parse is reported as such instead of rendering as "undefined".
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function readIdentity(value: unknown): FleetIdentity {
+  if (!isRecord(value)) return { machineId: "unknown", name: "unknown machine" };
+  return {
+    machineId: typeof value["machineId"] === "string" ? value["machineId"] : "unknown",
+    name: typeof value["name"] === "string" ? value["name"] : "unknown machine",
+  };
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readFleetReport(value: unknown): FleetReport {
+  const record = isRecord(value) ? value : {};
+  const machines = Array.isArray(record["machines"]) ? record["machines"] : [];
+  return {
+    hub: readIdentity(record["hub"]),
+    machines: machines.map((entry) => {
+      const machine = isRecord(entry) ? entry : {};
+      const version = readString(machine["version"]);
+      const piVersion = readString(machine["piVersion"]);
+      const error = readString(machine["error"]);
+      return {
+        ...readIdentity(entry),
+        kind: readString(machine["kind"]) ?? "unknown",
+        online: machine["online"] === true,
+        ...(version === undefined ? {} : { version }),
+        ...(piVersion === undefined ? {} : { piVersion }),
+        ...(error === undefined ? {} : { error }),
+      };
+    }),
+  };
+}
+
+function readFleetRun(value: unknown): FleetRunResponse {
+  const record = isRecord(value) ? value : {};
+  const outcomes = Array.isArray(record["outcomes"]) ? record["outcomes"] : [];
+  return {
+    operation: readString(record["operation"]) ?? "operation",
+    hub: readIdentity(record["hub"]),
+    outcomes: outcomes.map((entry) => {
+      const outcome = isRecord(entry) ? entry : {};
+      const error = readString(outcome["error"]);
+      return { ...readIdentity(entry), started: outcome["started"] === true, ...(error === undefined ? {} : { error }) };
+    }),
+  };
+}
+
+function formatFleetReport(report: FleetReport): string {
+  const rows = report.machines.map((machine) => {
+    const state = machine.online ? "online" : `offline${machine.error === undefined ? "" : ` (${machine.error})`}`;
+    const version = machine.version === undefined ? "version unknown" : `pi-web ${machine.version}`;
+    const pi = machine.piVersion === undefined ? "" : `, pi ${machine.piVersion}`;
+    return `  ${machine.name} [${machine.kind}] — ${state}, ${version}${pi}`;
+  });
+  return [`Machines known to ${report.hub.name}:`, ...rows].join("\n");
+}
+
+function formatFleetRun(response: FleetRunResponse, scope: string): string {
+  const lines = response.outcomes.map((outcome) => `  ${outcome.started ? "started" : "FAILED "} ${outcome.name}${outcome.error === undefined ? "" : ` — ${outcome.error}`}`);
+  const failed = response.outcomes.filter((outcome) => !outcome.started).length;
+  const summary = `${response.operation} on ${scope}: ${String(response.outcomes.length - failed)}/${String(response.outcomes.length)} started`;
+  // Naming the server that fanned out is the whole point: "all" means the
+  // machines *it* knows, and a different machine may know a different set.
+  return [`${summary} (fanned out from ${response.hub.name})`, ...lines].join("\n");
+}
+
+function parseArgs(args: string): string[] {
+  return args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((part) => {
+    if ((part.startsWith('"') && part.endsWith('"')) || (part.startsWith("'") && part.endsWith("'"))) {
+      return part.slice(1, -1);
+    }
+    return part;
+  }) ?? [];
+}
+
+function truncateOutput(output: string): string {
+  const trimmed = output.trim();
+  if (trimmed.length <= 3_500) return trimmed;
+  return `${trimmed.slice(0, 3_500)}\n… output truncated`;
+}
+
+function run(command: string, args: string[], env: NodeJS.ProcessEnv = {}): Promise<{ code: number; output: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      env: { ...process.env, ...env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let output = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => { output += chunk; });
+    child.stderr.on("data", (chunk: string) => { output += chunk; });
+    child.on("error", (error) => {
+      resolve({ code: 1, output: error.message });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, output });
+    });
+  });
+}
+
+async function runPiWeb(args: string[], env: NodeJS.ProcessEnv = {}): Promise<{ code: number; output: string }> {
+  if (existsSync(cliPath)) {
+    return run(process.execPath, [cliPath, ...args], env);
+  }
+  return run("pi-web", args, env);
+}
+
+function showResult(ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error" | "success"): void } }, title: string, result: { code: number; output: string }): void {
+  const body = truncateOutput(result.output) || (result.code === 0 ? "Done." : `Command failed with exit code ${String(result.code)}.`);
+  ctx.ui.notify(`${title}\n\n${body}`, result.code === 0 ? "info" : "error");
+}
+
+function isSubcommand(value: string): value is Subcommand {
+  return subcommands.some((command) => command === value);
+}
+
+async function boundedLogs(): Promise<{ code: number; output: string }> {
+  if (process.platform === "darwin") {
+    const existingLogs = macLogPaths.filter((path) => existsSync(path));
+    if (existingLogs.length === 0) return { code: 1, output: "No PI WEB log files found in ~/.pi-web/logs." };
+    return run("tail", ["-n", "100", ...existingLogs]);
+  }
+  return run("journalctl", ["--user", ...serviceNames.flatMap((serviceName) => ["-u", serviceName]), "-n", "100", "--no-pager"]);
+}
+
+export default function piWebExtension(pi: ExtensionAPI): void {
+  pi.registerCommand("pi-web", {
+    // The list is the discovery surface: a subcommand missing from here is one
+    // nobody finds. update and machines were added and left out of it.
+    description: "Manage PI WEB services and machines: status, machines, restart, update (add --all or --machine=<name>), logs, start, stop, install, doctor, version, open",
+    getArgumentCompletions(prefix: string): { value: string; label: string }[] | null {
+      const [first = ""] = parseArgs(prefix);
+      const items = subcommands
+        .filter((command) => command.startsWith(first))
+        .map((command) => ({ value: command, label: command }));
+      return items.length > 0 ? items : null;
+    },
+    async handler(args, ctx) {
+      const parsedArgs = parseArgs(args);
+      const subcommand = parsedArgs[0] ?? "help";
+      const rest = parsedArgs.slice(1);
+
+      if (subcommand === "help") {
+        ctx.ui.notify([
+          "PI WEB commands:",
+          "",
+          "  /pi-web machines                list the machines this server knows",
+          "  /pi-web restart [--all]         restart PI WEB here, or on every known machine",
+          "  /pi-web update [--all]          update PI WEB here, or on every known machine",
+          "  /pi-web restart --machine=NAME  restart one machine by name or id",
+          "  /pi-web status [--all]          service status here, or every machine's version",
+          "  /pi-web logs                    last 100 service log lines",
+          "  /pi-web install | start | stop | doctor | version | uninstall | open",
+          "",
+          "--all covers the machines known to the PI WEB server this session runs on;",
+          "every fan-out report names that server so the scope is never ambiguous.",
+        ].join("\n"), "info");
+        return;
+      }
+
+      if (subcommand === "open") {
+        ctx.ui.notify("PI WEB default URL: http://127.0.0.1:8504", "info");
+        return;
+      }
+
+      if (!isSubcommand(subcommand)) {
+        ctx.ui.notify(`Unknown pi-web command: ${subcommand}. Try /pi-web help.`, "error");
+        return;
+      }
+
+      if (subcommand === "stop" || subcommand === "uninstall") {
+        const ok = await ctx.ui.confirm(`pi-web ${subcommand}`, `Run pi-web ${subcommand}?`);
+        if (!ok) return;
+      }
+
+      if (subcommand === "logs") {
+        showResult(ctx, "pi-web logs", await boundedLogs());
+        return;
+      }
+
+      const flags = parseFlags(rest);
+      if (FLEET_SUBCOMMANDS.has(subcommand) && (subcommand === "machines" || flags.all || flags.machines.length > 0)) {
+        await runFleetCommand(ctx, subcommand, flags);
+        return;
+      }
+      if (subcommand === "status" && flags.all) {
+        await runFleetCommand(ctx, "machines", flags);
+        return;
+      }
+      if (subcommand === "machines" || subcommand === "update") {
+        // Both only exist as fleet operations; without a target they mean this
+        // machine, which the server can still answer for.
+        await runFleetCommand(ctx, subcommand, { ...flags, machines: ["local"] });
+        return;
+      }
+
+      showResult(ctx, `pi-web ${subcommand}`, await runPiWeb([subcommand, ...flags.rest]));
+    },
+  });
+}
+
+async function runFleetCommand(
+  ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error" | "success"): void } },
+  subcommand: Subcommand,
+  flags: ParsedFlags,
+): Promise<void> {
+  try {
+    if (subcommand === "machines") {
+      ctx.ui.notify(formatFleetReport(readFleetReport(await fleetRequest("/api/pi-web/fleet"))), "info");
+      return;
+    }
+    const operation = subcommand === "update" ? "update" : "restart";
+    const scope = flags.all ? "every known machine" : flags.machines.join(", ");
+    const response = readFleetRun(await fleetRequest("/api/pi-web/fleet/run", {
+      method: "POST",
+      body: { operation, ...(flags.all ? {} : { machineIds: flags.machines }) },
+    }));
+    const failed = response.outcomes.filter((outcome) => !outcome.started).length;
+    ctx.ui.notify(formatFleetRun(response, scope), failed === 0 ? "info" : "error");
+  } catch (error) {
+    ctx.ui.notify(`pi-web ${subcommand} failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+}

package/install.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+npm install -g @vincenthanxiaodu/pi-web --allow-scripts=node-pty
+pi-web install