@firstpick/pi-package-webui 0.1.4 → 0.1.5

package/README.md

@@ -17,6 +17,22 @@ This package provides:
 - Pi available through this package dependency or as `pi` on `PATH`
 - A modern browser with Server-Sent Events support
 
+## Optional companion packages
+
+The Web UI declares its companion Pi packages as npm `optionalDependencies`. A normal npm/Pi install will install them, while minimal installs can skip them with npm's optional-dependency controls such as `npm install --omit=optional`.
+
+At startup, the browser checks loaded Pi capabilities directly through RPC-visible commands and live widget events; it does not inspect npm package folders. That means locally symlinked/dev packages and separately installed Pi packages work as long as their commands/widgets are loaded in the active Pi tab.
+
+The side panel shows each optional feature as enabled, disabled, or install-needed. Disabling a feature is Web UI-local and hides Web UI affordances/specialized renderers without uninstalling or unloading the underlying Pi package. Installing a missing feature is an explicit, warned action: the server runs npm install for the whitelisted package from localhost only, then prompts you to `/reload` the active Pi tab so newly installed resources can load.
+
+Optional companions:
+
+- `@firstpick/pi-prompts-git-pr` for the guided Git workflow's `/git-staged-msg` prompt.
+- `@firstpick/pi-extension-release-npm` and `@firstpick/pi-extension-release-aur` for Publish menu commands and live release widgets.
+- `@firstpick/pi-extension-todo-progress` for the specialized todo-progress widget.
+- `@firstpick/pi-extension-git-footer-status` and `@firstpick/pi-extension-stats` for richer Pi status/footer and stats commands.
+- `@firstpick/pi-themes-bundle` for theme resources used by the browser theme picker and Pi themes.
+
 ## Quick start
 
 Install the package from npm into Pi, then restart Pi so `/webui-start` (also available as `/start-webui`) and `/webui-status` are loaded:
@@ -67,7 +83,7 @@ pi-webui --cwd /path/to/project
 - Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, with queued post-run submission that asks Pi to create/update a LEARNING
 - Basic extension UI bridge for `notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`, `select`, `confirm`, `input`, and `editor`
 - Specialized `/release-npm` and `/release-aur` widget rendering with scrollable live logs plus toggle/abort actions
-- Side-panel theme picker backed by the bundled `@firstpick/pi-themes-bundle` themes
+- Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded
 - PWA metadata, icons, and service worker for install-to-home-screen support when served from a secure context
 - Static frontend: no bundler, no frontend install step
 
@@ -91,7 +107,7 @@ Options:
   --port <port>      HTTP port (default: 31415)
   --no-open          Do not open the browser automatically
   --no-session       Start Pi RPC with --no-session
-  --name <name>      Initial Pi session name
+  --name <name>      Initial Web UI tab display name
   -- <pi args...>    Extra arguments forwarded to Pi RPC
 ```
 
@@ -130,7 +146,7 @@ Options:
   --cwd <path>        Default working directory for Pi tabs (default: current dir)
   --pi <command>      Pi executable to spawn (default: bundled dependency, then "pi")
   --no-session        Start Pi RPC with --no-session
-  --name <name>       Initial Pi session name
+  --name <name>       Initial Web UI tab display name
   -h, --help          Show help
   -v, --version       Print version
 ```
@@ -159,7 +175,7 @@ The browser button runs a native local workflow in the Web UI server process:
 4. Commit with either the short message (`git commit -m ...`) or the long message (`git commit -F ...`).
 5. Run `git push`.
 
-This workflow assumes `/git-staged-msg` is available in the Pi session and writes the two `dev/COMMIT/` files above. It can be cancelled between steps; active native git commands are terminated on cancel where possible.
+This workflow requires `/git-staged-msg` from `@firstpick/pi-prompts-git-pr`, which writes the two `dev/COMMIT/` files above. The Web UI enables the Git workflow button only when that command is loaded in the active Pi tab. If package resources are filtered or optional dependencies were omitted, make sure `/git-staged-msg` remains enabled. The workflow can be cancelled between steps; active native git commands are terminated on cancel where possible.
 
 ## How it works
 
@@ -172,9 +188,11 @@ pi --mode rpc
 With options, each spawned command becomes:
 
 ```bash
-pi --mode rpc [--no-session] [--name <name>] [...extra Pi args]
+pi --mode rpc [--no-session] [...extra Pi args]
 ```
 
+Web UI tab titles are stored in Web UI metadata instead of being forwarded as Pi CLI `--name` flags, so multiple tabs remain compatible with bundled Pi CLI versions that do not support session naming.
+
 The local server exposes:
 
 - static files from `public/`
@@ -182,7 +200,8 @@ The local server exposes:
 - `GET /api/directories?tab=<tabId>&path=<path>` for the browser cwd picker
 - `GET /api/path-suggestions?tab=<tabId>&query=<path>` for `@` file/path reference autocomplete in the prompt composer
 - `GET /api/path-fast-picks` and `POST /api/path-fast-picks` for cwd picker fast picks persisted across browser tabs, Pi terminal tabs, and Web UI server restarts
-- `GET /api/themes` for bundled theme data from `@firstpick/pi-themes-bundle`
+- `GET /api/themes` for optional theme data from `@firstpick/pi-themes-bundle` when available
+- localhost-only `POST /api/optional-feature-install` for explicit, warned installation of whitelisted optional feature packages
 - `GET /api/network` and localhost-only `POST /api/network/open` for local-network exposure status/control
 - `GET /api/webui-status?detailed=1` for slash-command status reporting
 - `POST /api/shutdown` for localhost-only graceful restarts from `/webui-start`/`/start-webui`; restart captures detailed tab status first so open and recently closed tabs can be restored with their session files

package/bin/pi-webui.mjs

@@ -104,6 +104,15 @@ const NATIVE_SLASH_COMMANDS = [
   { name: "quit", description: "Quit Pi" },
 ].map((command) => ({ ...command, source: "native", location: "Pi" }));
 const NATIVE_SLASH_COMMAND_NAMES = new Set(NATIVE_SLASH_COMMANDS.map((command) => command.name));
+const OPTIONAL_FEATURE_PACKAGES = new Map([
+  ["gitWorkflow", "@firstpick/pi-prompts-git-pr"],
+  ["releaseNpm", "@firstpick/pi-extension-release-npm"],
+  ["releaseAur", "@firstpick/pi-extension-release-aur"],
+  ["todoProgressWidget", "@firstpick/pi-extension-todo-progress"],
+  ["gitFooterStatus", "@firstpick/pi-extension-git-footer-status"],
+  ["statsCommand", "@firstpick/pi-extension-stats"],
+  ["themeBundle", "@firstpick/pi-themes-bundle"],
+]);
 
 function usage() {
   console.log(`pi-webui ${packageJson.version}
@@ -119,7 +128,7 @@ Options:
   --cwd <path>        Working directory for the Pi session (default: current dir)
   --pi <command>      Pi executable to spawn (default: bundled dependency, then "pi")
   --no-session        Start Pi RPC with --no-session
-  --name <name>       Initial Pi session name
+  --name <name>       Initial Web UI tab display name
   -h, --help          Show this help
   -v, --version       Print version
 
@@ -232,6 +241,10 @@ function sanitizeError(error) {
   return error.stack || error.message || String(error);
 }
 
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 class PiRpcProcess {
   constructor({ command, args, displayCommand, cwd }) {
     this.command = command;
@@ -274,6 +287,10 @@ class PiRpcProcess {
     this.emit({ type: "pi_process_start", pid: this.child.pid, cwd: this.cwd, command: this.displayCommand, args: this.args });
   }
 
+  isRunning() {
+    return !!this.child && this.child.exitCode === null && !this.child.killed;
+  }
+
   onEvent(listener) {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -344,7 +361,7 @@ class PiRpcProcess {
   }
 
   send(command, timeoutMs = REQUEST_TIMEOUT_MS) {
-    if (!this.child || !this.child.stdin || this.child.exitCode !== null) {
+    if (!this.isRunning() || !this.child?.stdin) {
       return Promise.reject(new Error("Pi RPC process is not running"));
     }
 
@@ -367,7 +384,7 @@ class PiRpcProcess {
   }
 
   async writeRaw(command) {
-    if (!this.child || !this.child.stdin || this.child.exitCode !== null) {
+    if (!this.isRunning() || !this.child?.stdin) {
       throw new Error("Pi RPC process is not running");
     }
 
@@ -634,6 +651,49 @@ function runCommand(command, args, { cwd, timeoutMs = 2000, maxOutputLength = 20
   });
 }
 
+function optionalDependencyInstallRoot() {
+  const parts = packageRoot.split(path.sep);
+  const nodeModulesIndex = parts.lastIndexOf("node_modules");
+  if (nodeModulesIndex >= 0) {
+    const root = parts.slice(0, nodeModulesIndex).join(path.sep);
+    return root || path.parse(packageRoot).root;
+  }
+  return packageRoot;
+}
+
+function formatCommandForDisplay(command, args) {
+  return [command, ...args].map((part) => (/\s/.test(part) ? JSON.stringify(part) : part)).join(" ");
+}
+
+async function installOptionalFeaturePackage(featureId) {
+  const packageName = OPTIONAL_FEATURE_PACKAGES.get(featureId);
+  if (!packageName) throw makeHttpError(400, `Unknown optional feature: ${featureId}`);
+
+  const installRoot = optionalDependencyInstallRoot();
+  const npmCommand = process.env.PI_WEBUI_NPM_BIN || "npm";
+  const args = ["install", "--prefix", installRoot, packageName];
+  const result = await runCommand(npmCommand, args, {
+    cwd: installRoot,
+    timeoutMs: 5 * 60 * 1000,
+    maxOutputLength: 80000,
+  });
+  const command = formatCommandForDisplay(npmCommand, args);
+  const ok = result.exitCode === 0 && !result.timedOut && !result.error;
+  if (!ok) {
+    const details = [result.error, result.timedOut ? "timed out" : undefined, result.stderr?.trim(), result.stdout?.trim()].filter(Boolean).join("\n");
+    throw makeHttpError(500, `Optional feature install failed: ${command}${details ? `\n${details}` : ""}`);
+  }
+  return {
+    featureId,
+    packageName,
+    installRoot,
+    command,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    message: `Installed optional feature package ${packageName}. Reload the active Pi tab to load new resources.`,
+  };
+}
+
 function displayPath(cwd) {
   const normalized = cwd.replace(/\\/g, "/");
   const home = (process.env.USERPROFILE || process.env.HOME || "").replace(/\\/g, "/");
@@ -809,9 +869,9 @@ function resolveScopedModelsFromPatterns(patterns, models) {
 async function getScopedModelData(tab) {
   const { patterns, source } = await configuredScopedModelPatterns(tab.cwd);
   if (!patterns.length) return { models: [], patterns, source };
-  const response = await tab.rpc.send({ type: "get_available_models" });
+  const response = await safeRpcResponse(tab, { type: "get_available_models" });
   if (response.success === false) throw makeHttpError(400, response.error || "failed to load available models");
-  return { models: resolveScopedModelsFromPatterns(patterns, response.data?.models || []), patterns, source };
+  return { models: resolveScopedModelsFromPatterns(patterns, response.data?.models || []), patterns, source, rpcRunning: response.rpcRunning !== false };
 }
 
 function pathPickerRoots(activeCwd, viewedCwd) {
@@ -1449,9 +1509,9 @@ function buildPiArgsForTab(tabIndex, title) {
   const args = ["--mode", "rpc"];
   if (options.noSession) args.push("--no-session");
 
-  const sessionName = tabIndex === 1 ? options.name : title;
-  if (sessionName) args.push("--name", sessionName);
-
+  // Keep tab naming inside Web UI metadata. Some bundled Pi CLI versions do not
+  // support --name, and passing Web UI-generated tab titles through to child
+  // RPC processes makes every tab after the first exit immediately.
   args.push(...options.piArgs);
   return args;
 }
@@ -1729,6 +1789,18 @@ function defaultTabTitle(tabIndex) {
   return `Terminal ${tabIndex}`;
 }
 
+async function primeTabRpc(tab) {
+  try {
+    const response = await tab.rpc.send({ type: "get_state" }, 1500);
+    if (response.success !== false) {
+      rememberTabState(tab, response.data);
+      reconcileTabActivityFromState(tab, response.data);
+    }
+  } catch (error) {
+    if (!/Timed out waiting for RPC response/i.test(sanitizeError(error))) throw error;
+  }
+}
+
 function attachRpcToTab(tab, rpc) {
   tab.rpcUnsubscribe?.();
   tab.rpc = rpc;
@@ -1777,6 +1849,15 @@ async function createTab({ id: requestedId, index, title, titleSource, conversat
   attachRpcToTab(tab, rpc);
   tabs.set(id, tab);
   rpc.start();
+  try {
+    await primeTabRpc(tab);
+  } catch (error) {
+    if (!tab.rpc.isRunning()) {
+      tab.rpcUnsubscribe?.();
+      tabs.delete(id);
+      throw new Error(`Pi RPC process failed while starting ${tabTitle}: ${sanitizeError(error)}`);
+    }
+  }
   if (sessionFile && !options.noSession) {
     recordEvent({ type: "webui_tab_restored", tabId: tab.id, tabTitle: tab.title, cwd: tab.cwd });
   }
@@ -1799,7 +1880,7 @@ function tabMeta(tab) {
     createdAt: tab.createdAt,
     startedAt: tab.rpc.startedAt,
     pid: tab.rpc.child?.pid,
-    running: !!tab.rpc.child && tab.rpc.child.exitCode === null,
+    running: tab.rpc.isRunning(),
     command: tab.rpc.displayCommand,
     clientCount: tab.sseClients.size,
     pendingExtensionUiRequestCount: pendingExtensionUiRequests(tab).length,
@@ -1968,10 +2049,67 @@ async function restartTabRpc(tab, reason = "reload") {
   return tab;
 }
 
+function rpcUnavailableMessage(tab) {
+  return `Pi RPC process for ${tab?.title || "terminal"} is not running`;
+}
+
+function fallbackRpcResponse(tab, command, error) {
+  const message = sanitizeError(error) || rpcUnavailableMessage(tab);
+  const base = { type: "response", command: command.type, success: true, rpcRunning: false, error: message };
+  switch (command.type) {
+    case "get_state":
+      return {
+        ...base,
+        data: {
+          model: null,
+          thinkingLevel: "off",
+          isStreaming: false,
+          isCompacting: false,
+          steeringMode: "one-at-a-time",
+          followUpMode: "one-at-a-time",
+          sessionFile: tab?.sessionFile,
+          sessionId: tab?.id,
+          sessionName: tab?.title,
+          autoCompactionEnabled: false,
+          messageCount: 0,
+          pendingMessageCount: 0,
+          rpcRunning: false,
+          rpcError: message,
+        },
+      };
+    case "get_messages":
+      return { ...base, data: { messages: [] } };
+    case "get_available_models":
+      return { ...base, data: { models: [] } };
+    case "get_session_stats":
+      return { ...base, data: null };
+    case "get_last_assistant_text":
+      return { ...base, data: { text: "" } };
+    default:
+      return { ...base, success: false, error: message };
+  }
+}
+
+async function safeRpcResponse(tab, command, timeoutMs = REQUEST_TIMEOUT_MS) {
+  try {
+    return await tab.rpc.send(command, timeoutMs);
+  } catch (error) {
+    const message = sanitizeError(error);
+    if (/Pi RPC process is not running/i.test(message)) return fallbackRpcResponse(tab, command, error);
+    throw error;
+  }
+}
+
 async function getCommandData(tab) {
-  const response = await tab.rpc.send({ type: "get_commands" });
-  if (response.success === false) throw makeHttpError(400, response.error || "failed to load commands");
-  return { commands: [...NATIVE_SLASH_COMMANDS, ...(response.data?.commands || [])] };
+  try {
+    const response = await tab.rpc.send({ type: "get_commands" });
+    if (response.success === false) throw makeHttpError(400, response.error || "failed to load commands");
+    return { commands: [...NATIVE_SLASH_COMMANDS, ...(response.data?.commands || [])], rpcRunning: true };
+  } catch (error) {
+    const message = sanitizeError(error);
+    if (!/Pi RPC process is not running/i.test(message)) throw error;
+    return { commands: [...NATIVE_SLASH_COMMANDS], rpcRunning: false, error: message };
+  }
 }
 
 function formatSessionOutput(tab, state, stats) {
@@ -2080,6 +2218,23 @@ async function closeTab(id) {
   return tab;
 }
 
+async function closeTabs(ids) {
+  const uniqueIds = [...new Set((Array.isArray(ids) ? ids : []).map((id) => String(id || "").trim()).filter(Boolean))];
+  const targetTabs = uniqueIds.map((id) => tabs.get(id)).filter(Boolean);
+  if (!targetTabs.length) return [];
+
+  if (targetTabs.length >= tabs.size) {
+    await createTab({ cwd: targetTabs[0]?.cwd || options.cwd });
+  }
+
+  const closed = [];
+  for (const tab of targetTabs) {
+    if (!tabs.has(tab.id)) continue;
+    closed.push(await closeTab(tab.id));
+  }
+  return closed;
+}
+
 function requestedTabId(req, url, body) {
   const header = req.headers["x-pi-webui-tab"];
   const headerValue = Array.isArray(header) ? header[0] : header;
@@ -2362,6 +2517,13 @@ const server = createServer(async (req, res) => {
       return;
     }
 
+    if (url.pathname === "/api/tabs/close" && req.method === "POST") {
+      const body = await readJsonBody(req);
+      const closed = await closeTabs(body.ids || body.tabIds || []);
+      sendJson(res, 200, { ok: true, data: { closedIds: closed.map((tab) => tab.id), tabs: listTabs(), activeTabId: firstTab()?.id || null } });
+      return;
+    }
+
     if (url.pathname.startsWith("/api/tabs/") && req.method === "PATCH") {
       const id = decodeURIComponent(url.pathname.slice("/api/tabs/".length));
       const body = await readJsonBody(req);
@@ -2511,6 +2673,14 @@ const server = createServer(async (req, res) => {
       return;
     }
 
+    if (url.pathname === "/api/optional-feature-install" && req.method === "POST") {
+      if (!isLocalAddress(req.socket.remoteAddress)) throw makeHttpError(403, "Installing optional Web UI features is only allowed from localhost");
+      const body = await readJsonBody(req);
+      const data = await installOptionalFeaturePackage(String(body.featureId || ""));
+      sendJson(res, 200, { ok: true, data });
+      return;
+    }
+
     if (url.pathname === "/api/commands" && req.method === "GET") {
       const tab = getRequestedTab(req, url);
       sendJson(res, 200, { type: "response", command: "get_commands", success: true, data: await getCommandData(tab) });
@@ -2558,7 +2728,7 @@ const server = createServer(async (req, res) => {
     const getCommand = req.method === "GET" ? commandFromGet(url.pathname) : undefined;
     if (getCommand) {
       const tab = getRequestedTab(req, url);
-      const response = await tab.rpc.send(getCommand);
+      const response = await safeRpcResponse(tab, getCommand);
       sendJson(res, response.success === false ? 400 : 200, response);
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-webui",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Pi Web UI companion package with a local browser UI CLI plus /webui-start and /webui-status commands.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,29 @@
   ],
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "../pi-extension-git-footer-status/index.ts",
+      "../pi-extension-release-aur/index.ts",
+      "../pi-extension-release-npm/index.ts",
+      "../pi-extension-stats/index.ts",
+      "../pi-extension-todo-progress/index.ts",
+      "node_modules/@firstpick/pi-extension-git-footer-status/index.ts",
+      "node_modules/@firstpick/pi-extension-release-aur/index.ts",
+      "node_modules/@firstpick/pi-extension-release-npm/index.ts",
+      "node_modules/@firstpick/pi-extension-stats/index.ts",
+      "node_modules/@firstpick/pi-extension-todo-progress/index.ts"
+    ],
+    "skills": [
+      "../pi-extension-release-aur/skills",
+      "node_modules/@firstpick/pi-extension-release-aur/skills"
+    ],
+    "prompts": [
+      "../pi-package-prompts-git-pr/prompts",
+      "node_modules/@firstpick/pi-prompts-git-pr/prompts"
+    ],
+    "themes": [
+      "../pi-package-themes-bundle/themes",
+      "node_modules/@firstpick/pi-themes-bundle/themes"
     ]
   },
   "bin": {
@@ -26,8 +48,16 @@
     "test": "node tests/mobile-static.test.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@firstpick/pi-themes-bundle": "^0.1.0"
+    "@earendil-works/pi-coding-agent": "^0.78.0"
+  },
+  "optionalDependencies": {
+    "@firstpick/pi-extension-git-footer-status": "^0.2.1",
+    "@firstpick/pi-extension-release-aur": "^0.1.3",
+    "@firstpick/pi-extension-release-npm": "^0.3.3",
+    "@firstpick/pi-extension-stats": "^0.2.0",
+    "@firstpick/pi-extension-todo-progress": "^0.1.7",
+    "@firstpick/pi-prompts-git-pr": "^0.1.0",
+    "@firstpick/pi-themes-bundle": "^0.1.1"
   },
   "files": [
     "index.ts",