@hyperdreamer/pi-webui 1.10.7 → 1.11.0-beta.10

package/README.md

@@ -11,7 +11,7 @@ Run agents where your code, tools, credentials, and build caches live. Supervise
 
 ![PI WEBUI](docs/assets/pi-webui-banner.png)
 
-![PI WEBUI desktop screenshot](docs/assets/pi-webui-desktop.png)
+![PI WEBUI desktop collage showing workspace projects, live session activity, system information, and memory](docs/assets/pi-webui-desktop.png)
 
 ## Why PI WEBUI?
 
@@ -36,7 +36,7 @@ Requirements:
 
 - Node.js 22.19.0 or newer
 - npm
-- Pi Coding Agent `>=0.82.1 <0.83`, configured for your user
+- Pi Coding Agent `>=0.83.0 <0.84`, configured for your user
 - git and the development tools your agents need
 
 Install PI WEBUI from npm or clone from GitHub:
@@ -117,6 +117,21 @@ Project-local PI WEBUI config lives at:
 
 Common configuration includes host/port, path access, uploads, PI WEBUI plugin enablement, shortcuts, and session daemon options. In Settings, machine-affecting config targets the selected machine; gateway host/port/allowed-hosts, remote machine registration, tokens, and keyboard shortcuts stay local.
 
+## Extra skills
+
+PI WEBUI ships two opt-in agent skills for deterministic plan authoring and
+subagent-driven execution. Nothing installs or activates them by default:
+
+```bash
+pi-webui install-extra --dry-run   # show what would change
+pi-webui install-extra             # install, after confirming
+```
+
+They install as `writing-plans` and `subagent-driven-development`, **replacing**
+any existing skills with those names. The command explains the risk, asks for
+confirmation, and backs up both skills and the skill lock file first. See
+[docs/optional-skills.md](https://github.com/hyperdreamer/pi-webui/blob/main/docs/optional-skills.md).
+
 ## Development
 
 `start.sh` (a thin wrapper around `npm run dev`) starts the complete development stack. To run its processes separately:

package/dist/cli.js

@@ -1,19 +1,21 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, userInfo } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_PORT, defaultPiWebUiConfigPath, defaultPiWebUiDataDir, effectivePiWebUiConfig, examplePiWebUiConfig } from "./config.js";
-import { packageVersion, printPiWebUiVersionReport } from "./piWebUiVersionReport.js";
-import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck } from "./server/diagnostics/nodePtySpawnHelper.js";
-import { checkNodePtyNativeModule, formatNodePtyNativeModuleCheck } from "./server/diagnostics/nodePtyNativeModule.js";
+import { DEFAULT_PORT, defaultPiWebUiConfigPath, defaultPiWebUiDataDir, effectivePiWebUiConfig, examplePiWebUiConfig, } from "./config.js";
+import { packageVersion, printPiWebUiVersionReport, } from "./piWebUiVersionReport.js";
+import { installOptionalSkills, } from "./server/skills/optionalSkillInstaller.js";
+import { checkNodePtyDarwinSpawnHelper, formatNodePtyDarwinSpawnHelperCheck, } from "./server/diagnostics/nodePtySpawnHelper.js";
+import { checkNodePtyNativeModule, formatNodePtyNativeModuleCheck, } from "./server/diagnostics/nodePtyNativeModule.js";
 import { installNativeServiceCandidate, nativeServiceInstallFailureNeedsPathAdvice, } from "./nativeServices/serviceInstall.js";
 import { minimumSupportedNodeVersion, nativeServiceManagerRefs, productionNativeServiceIds, } from "./nativeServices/servicePlan.js";
 import { formatNativeServiceDoctorResult, inferInstalledNativeServiceMode, inspectInstalledDevelopmentServiceInput, inspectInstalledProductionServiceContext, runNativeServiceDoctor, } from "./nativeServices/serviceDoctor.js";
 import { createNativeServiceAuthoritativeProbe, nativeServicePrerequisiteShellCheck, } from "./nativeServices/serviceProbe.js";
-import { renderLaunchdPlist, renderSystemdUnit } from "./nativeServices/serviceRendering.js";
+import { renderLaunchdPlist, renderSystemdUnit, } from "./nativeServices/serviceRendering.js";
 const PI_WEBUI_PACKAGE_NAME = "@hyperdreamer/pi-webui";
 const systemdServiceDir = join(homedir(), ".config", "systemd", "user");
 const launchdServiceDir = join(homedir(), "Library", "LaunchAgents");
@@ -87,18 +89,31 @@ function capture(command, args) {
     const result = spawnSync(command, args, { encoding: "utf8" });
     const errorMessage = result.error instanceof Error ? result.error.message : "";
     const stderr = outputText(result.stderr);
-    return { status: result.status ?? 1, stdout: outputText(result.stdout), stderr: stderr === "" ? errorMessage : stderr };
+    return {
+        status: result.status ?? 1,
+        stdout: outputText(result.stdout),
+        stderr: stderr === "" ? errorMessage : stderr,
+    };
 }
 function runQuiet(command, args) {
     return capture(command, args).status;
 }
 function hasCommand(command) {
-    return capture("/usr/bin/env", ["sh", "-c", `command -v ${shellSingleQuote(command)}`]).status === 0;
+    return (capture("/usr/bin/env", [
+        "sh",
+        "-c",
+        `command -v ${shellSingleQuote(command)}`,
+    ]).status === 0);
 }
 function isLingerEnabled() {
     if (!hasCommand("loginctl"))
         return undefined;
-    const result = capture("loginctl", ["show-user", userInfo().username, "-p", "Linger"]);
+    const result = capture("loginctl", [
+        "show-user",
+        userInfo().username,
+        "-p",
+        "Linger",
+    ]);
     if (result.status !== 0)
         return undefined;
     const value = result.stdout.trim();
@@ -109,7 +124,11 @@ function isLingerEnabled() {
     return undefined;
 }
 function parseInstallOptions(args) {
-    const options = { host: "127.0.0.1", port: String(DEFAULT_PORT), mode: "production" };
+    const options = {
+        host: "127.0.0.1",
+        port: String(DEFAULT_PORT),
+        mode: "production",
+    };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === undefined)
@@ -196,7 +215,9 @@ function serviceShellCommand(command, cwd) {
     return ["/usr/bin/env", detectServiceShell().executable, "-lc", fullCommand];
 }
 function serviceShellQuote(value) {
-    return detectServiceShell().name === "fish" ? fishSingleQuote(value) : shellSingleQuote(value);
+    return detectServiceShell().name === "fish"
+        ? fishSingleQuote(value)
+        : shellSingleQuote(value);
 }
 function describeServiceShell() {
     const shell = detectServiceShell();
@@ -205,7 +226,9 @@ function describeServiceShell() {
             ? "could not detect a supported login shell; using bash"
             : `detected ${shell.detectedExecutable}; using bash because PI WEBUI currently supports bash, zsh, and fish`;
     }
-    return shell.detectedExecutable === null ? shell.name : `${shell.name} (${shell.detectedExecutable})`;
+    return shell.detectedExecutable === null
+        ? shell.name
+        : `${shell.name} (${shell.detectedExecutable})`;
 }
 function configEnvironment(options, configPath) {
     return options.config === undefined ? {} : { PI_WEBUI_CONFIG: configPath };
@@ -252,7 +275,9 @@ function launchdLogPath(ref) {
     return join(logDir, ref.logName);
 }
 function installConfigPath(options) {
-    return options.config === undefined ? defaultPiWebUiConfigPath() : resolve(options.config);
+    return options.config === undefined
+        ? defaultPiWebUiConfigPath()
+        : resolve(options.config);
 }
 async function writeInitialConfig(options, configPath) {
     await mkdir(dirname(configPath), { recursive: true });
@@ -267,13 +292,17 @@ function launchdPlistPath(ref) {
     return join(launchdServiceDir, ref.launchdPlistName);
 }
 function serviceFilePath(backend, ref) {
-    return backend.kind === "systemd" ? systemdServicePath(ref) : launchdPlistPath(ref);
+    return backend.kind === "systemd"
+        ? systemdServicePath(ref)
+        : launchdPlistPath(ref);
 }
 function serviceFileExists(backend, ref) {
     return existsSync(serviceFilePath(backend, ref));
 }
 function installedServiceIds(backend) {
-    return new Set(allServiceRefs().filter((ref) => serviceFileExists(backend, ref)).map((ref) => ref.id));
+    return new Set(allServiceRefs()
+        .filter((ref) => serviceFileExists(backend, ref))
+        .map((ref) => ref.id));
 }
 function installedServiceRefs(backend) {
     const installed = startOrder(allServiceRefs().filter((ref) => serviceFileExists(backend, ref)));
@@ -302,13 +331,15 @@ function launchdServiceTarget(ref) {
     return `${launchdDomain()}/${ref.launchdLabel}`;
 }
 function launchdIsLoaded(ref) {
-    return capture("launchctl", ["print", launchdServiceTarget(ref)]).status === 0;
+    return (capture("launchctl", ["print", launchdServiceTarget(ref)]).status === 0);
 }
 function launchdBootout(ref) {
     runQuiet("launchctl", ["bootout", launchdServiceTarget(ref)]);
 }
 function launchdBootstrap(ref) {
-    run("launchctl", ["bootstrap", launchdDomain(), launchdPlistPath(ref)], { check: true });
+    run("launchctl", ["bootstrap", launchdDomain(), launchdPlistPath(ref)], {
+        check: true,
+    });
     run("launchctl", ["enable", launchdServiceTarget(ref)], { check: true });
 }
 function launchdStart(ref) {
@@ -406,14 +437,24 @@ function makeServiceRuntimeStatus(ref, health, detail, target, filePath, pid) {
 }
 function firstOutputLine(...values) {
     for (const value of values) {
-        const line = value.trim().split("\n").find((candidate) => candidate.trim() !== "");
+        const line = value
+            .trim()
+            .split("\n")
+            .find((candidate) => candidate.trim() !== "");
         if (line !== undefined)
             return line.trim();
     }
     return undefined;
 }
 function systemdMainPid(ref) {
-    const result = capture("systemctl", ["--user", "--no-pager", "show", ref.systemdName, "--property=MainPID", "--value"]);
+    const result = capture("systemctl", [
+        "--user",
+        "--no-pager",
+        "show",
+        ref.systemdName,
+        "--property=MainPID",
+        "--value",
+    ]);
     if (result.status !== 0)
         return undefined;
     const value = result.stdout.trim();
@@ -424,7 +465,12 @@ function systemdRuntimeStatus(backend, ref) {
     const filePath = serviceFilePath(backend, ref);
     if (!serviceFileExists(backend, ref))
         return makeServiceRuntimeStatus(ref, "not-installed", "not installed", target, filePath);
-    const result = capture("systemctl", ["--user", "--no-pager", "is-active", target]);
+    const result = capture("systemctl", [
+        "--user",
+        "--no-pager",
+        "is-active",
+        target,
+    ]);
     const state = firstOutputLine(result.stdout, result.stderr) ?? "unknown";
     if (result.status === 0 && state === "active")
         return makeServiceRuntimeStatus(ref, "running", "running", target, filePath, systemdMainPid(ref));
@@ -440,7 +486,9 @@ export function launchdRuntimeDetails(output) {
     const lastExitCode = parseLaunchdField(output, "last exit code");
     const detail = state === "running"
         ? "running"
-        : lastExitCode === undefined ? state : `${state} (last exit code ${lastExitCode})`;
+        : lastExitCode === undefined
+            ? state
+            : `${state} (last exit code ${lastExitCode})`;
     return { state, detail, pid };
 }
 function launchdRuntimeStatus(backend, ref) {
@@ -453,11 +501,17 @@ function launchdRuntimeStatus(backend, ref) {
         return makeServiceRuntimeStatus(ref, "stopped", firstOutputLine(result.stderr, result.stdout) ?? "not loaded", target, filePath);
     }
     const details = launchdRuntimeDetails(result.stdout);
-    const health = details.state === "running" ? "running" : details.state === "unknown" ? "unknown" : "stopped";
+    const health = details.state === "running"
+        ? "running"
+        : details.state === "unknown"
+            ? "unknown"
+            : "stopped";
     return makeServiceRuntimeStatus(ref, health, details.detail, target, filePath, details.pid);
 }
 function runtimeStatus(backend, ref) {
-    return backend.kind === "systemd" ? systemdRuntimeStatus(backend, ref) : launchdRuntimeStatus(backend, ref);
+    return backend.kind === "systemd"
+        ? systemdRuntimeStatus(backend, ref)
+        : launchdRuntimeStatus(backend, ref);
 }
 function printServiceStatus(status) {
     const icon = status.health === "running" ? "✓" : "✗";
@@ -611,7 +665,11 @@ async function uninstall() {
     console.log(`PI WEBUI ${backend.label} removed. Production and development service files were removed; config and data were left in place.`);
 }
 function systemdServiceAction(action, refs) {
-    const orderedRefs = action === "stop" ? stopOrder(refs) : action === "restart" ? restartOrder(refs) : startOrder(refs);
+    const orderedRefs = action === "stop"
+        ? stopOrder(refs)
+        : action === "restart"
+            ? restartOrder(refs)
+            : startOrder(refs);
     run("systemctl", ["--user", action, ...orderedRefs.map((ref) => ref.systemdName)], { check: true });
 }
 function launchdServiceAction(action, refs) {
@@ -649,7 +707,11 @@ function logs() {
     const backend = requireServiceBackend("pi-webui logs");
     const refs = installedServiceRefs(backend);
     if (backend.kind === "systemd") {
-        run("journalctl", ["--user", ...refs.flatMap((ref) => ["-u", ref.systemdName]), "-f"]);
+        run("journalctl", [
+            "--user",
+            ...refs.flatMap((ref) => ["-u", ref.systemdName]),
+            "-f",
+        ]);
         return;
     }
     run("tail", ["-F", ...refs.map((ref) => launchdLogPath(ref))]);
@@ -684,9 +746,18 @@ function generalDoctorChecks() {
     const shell = serviceShellLabel();
     const agentCommand = agentCommandForChecks();
     return [
-        [`Caller login ${shell} can find node >= ${minimumSupportedNodeVersion}`, serviceShellCommand(nodeVersionCheck())],
-        [`Caller login ${shell} can find npm`, serviceShellCommand(commandWithVersionCheck("npm"))],
-        [`Caller login ${shell} can find ${agentCommand}`, serviceShellCommand(commandWithVersionCheck(agentCommand))],
+        [
+            `Caller login ${shell} can find node >= ${minimumSupportedNodeVersion}`,
+            serviceShellCommand(nodeVersionCheck()),
+        ],
+        [
+            `Caller login ${shell} can find npm`,
+            serviceShellCommand(commandWithVersionCheck("npm")),
+        ],
+        [
+            `Caller login ${shell} can find ${agentCommand}`,
+            serviceShellCommand(commandWithVersionCheck(agentCommand)),
+        ],
     ];
 }
 function runChecks(checks) {
@@ -715,7 +786,12 @@ function printCheckOutput(output) {
 }
 function optionalDoctorChecks() {
     const shell = serviceShellLabel();
-    return [[`Caller login ${shell} can find optional ripgrep (rg)`, serviceShellCommand(commandCheck("rg"))]];
+    return [
+        [
+            `Caller login ${shell} can find optional ripgrep (rg)`,
+            serviceShellCommand(commandCheck("rg")),
+        ],
+    ];
 }
 function printOptionalDoctorChecks() {
     let missingOptionalTool = false;
@@ -859,7 +935,9 @@ async function doctor() {
     printOptionalDoctorChecks();
     console.log("\nNative terminal runtime readiness:");
     const nodePtyNativeModuleOk = printNodePtyNativeModuleCheck();
-    const nodePtySpawnHelperOk = nodePtyNativeModuleOk ? printNodePtyDarwinSpawnHelperCheck() : true;
+    const nodePtySpawnHelperOk = nodePtyNativeModuleOk
+        ? printNodePtyDarwinSpawnHelperCheck()
+        : true;
     let nativeServiceReport = null;
     if (backend !== undefined) {
         console.log("\nNative service plan checks (service-manager context):");
@@ -889,7 +967,8 @@ async function doctor() {
     const pathFailure = !generalReadinessOk || nativeServiceReport?.pathAdviceRecommended === true;
     if (pathFailure) {
         console.log("\nIf a command works in your terminal but fails in the service-manager check, compare the caller and manager contexts above.");
-        const adviceShell = nativeServiceReport?.pathAdviceRecommended === true && nativeServiceReport.adviceShell !== null
+        const adviceShell = nativeServiceReport?.pathAdviceRecommended === true &&
+            nativeServiceReport.adviceShell !== null
             ? nativeServiceReport.adviceShell
             : detectServiceShell();
         printPathSetupAdvice(adviceShell);
@@ -915,12 +994,161 @@ function printNodePtyDarwinSpawnHelperCheck() {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function optionalSkillsSourceRoot() {
+    return join(packageRootPath(), "optional-skills");
+}
+function globalSkillsRootPath() {
+    return join(homedir(), ".pi", "agent", "skills");
+}
+function skillLockFilePath() {
+    const xdgStateHome = process.env["XDG_STATE_HOME"];
+    return xdgStateHome !== undefined && xdgStateHome !== ""
+        ? join(xdgStateHome, "skills", ".skill-lock.json")
+        : join(homedir(), ".agents", ".skill-lock.json");
+}
+function createInstallerIo() {
+    return {
+        exists: (path) => existsSync(path),
+        listFiles: (dir) => listFilesRecursively(dir),
+        readFile: (path) => readFileSync(path, "utf8"),
+        writeFile: (path, content) => {
+            writeFileSync(path, content);
+        },
+        copyFile: (from, to) => {
+            mkdirSync(dirname(to), { recursive: true });
+            copyFileSync(from, to);
+        },
+        makeDir: (path) => {
+            mkdirSync(path, { recursive: true });
+        },
+        movePath: (from, to) => {
+            mkdirSync(dirname(to), { recursive: true });
+            renameSync(from, to);
+        },
+        removePath: (path) => {
+            rmSync(path, { recursive: true, force: true });
+        },
+        regenerateManifest: (skillDir) => {
+            const manifest = join(skillDir, "pi-webui-skill.json");
+            if (!existsSync(manifest))
+                return;
+            const result = spawnSync(process.execPath, [
+                join(skillDir, "scripts", "sdd-state.mjs"),
+                "manifest-create",
+                "--source-root",
+                skillDir,
+                "--package-json",
+                join(packageRootPath(), "package.json"),
+                "--output",
+                manifest,
+            ], { encoding: "utf8", stdio: "pipe" });
+            if (result.status !== 0) {
+                throw new Error(`failed to regenerate the runtime manifest for ${skillDir}: ${result.stderr.trim()}`);
+            }
+        },
+    };
+}
+function listFilesRecursively(dir, prefix = "") {
+    const found = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory())
+            found.push(...listFilesRecursively(join(dir, entry.name), relative));
+        else
+            found.push(relative);
+    }
+    return found;
+}
+async function confirmOptionalSkillInstall() {
+    if (!process.stdin.isTTY) {
+        throw new Error("pi-webui install-extra needs an interactive terminal to confirm. Re-run it directly, or pass --yes to skip the prompt.");
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question("Proceed? [y/N] ");
+        return /^y(es)?$/iu.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function printOptionalSkillRisk(skillsRoot, lockPath) {
+    console.log(`PI WEBUI extra skills install
+
+This installs two opt-in agent skills into:
+  ${skillsRoot}
+
+They install under the names 'writing-plans' and
+'subagent-driven-development', because other skills such as
+'brainstorming' route to those names. Any existing skill with either name
+WILL BE REPLACED.
+
+What this changes:
+  - replaces ${join(skillsRoot, "writing-plans")}
+  - replaces ${join(skillsRoot, "subagent-driven-development")}
+  - removes those two entries from ${lockPath}
+
+That directory is not version controlled, so a timestamped backup of both
+skills and the lock file is taken first, and its path is printed at the end.
+Helper scripts the controller inherits are carried over from the replaced
+skill.
+`);
+}
+async function installExtra(args) {
+    const dryRun = args.includes("--dry-run");
+    const assumeYes = args.includes("--yes") || args.includes("-y");
+    for (const arg of args) {
+        if (arg !== "--dry-run" && arg !== "--yes" && arg !== "-y") {
+            throw new Error(`Unknown install-extra option: ${arg}`);
+        }
+    }
+    const sourceRoot = optionalSkillsSourceRoot();
+    if (!existsSync(sourceRoot)) {
+        throw new Error(`This build does not ship optional skills (${sourceRoot} is missing). Install from a repository checkout instead.`);
+    }
+    const skillsRoot = globalSkillsRootPath();
+    const lockPath = skillLockFilePath();
+    printOptionalSkillRisk(skillsRoot, lockPath);
+    if (dryRun)
+        console.log("Dry run: nothing will be written.\n");
+    else if (!assumeYes && !(await confirmOptionalSkillInstall())) {
+        console.log("Aborted. Nothing was changed.");
+        return;
+    }
+    const backupRoot = join(homedir(), ".pi", "agent", `skills-backup-${timestampSlug()}`);
+    const report = installOptionalSkills(createInstallerIo(), {
+        sourceRoot,
+        skillsRoot,
+        backupRoot,
+        lockPath,
+        dryRun,
+    });
+    console.log(dryRun ? "\nWould install:" : "\nInstalled:");
+    for (const name of report.installed)
+        console.log(`  ${name}`);
+    if (report.lockEntriesRemoved.length > 0) {
+        console.log(dryRun ? "Would remove lock entries:" : "Removed lock entries:");
+        for (const name of report.lockEntriesRemoved)
+            console.log(`  ${name}`);
+    }
+    if (dryRun)
+        return;
+    console.log(`\nBackup: ${report.backupRoot}`);
+    console.log(`Restore with:\n  rm -rf ${report.installed
+        .map((n) => join(skillsRoot, n))
+        .join(" ")}\n  cp -a ${report.backupRoot}/* ${skillsRoot}/`);
+    console.log("\nType /reload in each idle PI WEBUI session to pick up the new skills.");
+}
+function timestampSlug() {
+    return new Date().toISOString().replaceAll(/[:.]/gu, "-").slice(0, 19);
+}
 function help() {
     console.log(`PI WEBUI
 
 Usage:
   pi-webui install [--dev] [--host 127.0.0.1] [--port ${String(DEFAULT_PORT)}] [--config ~/.config/pi-webui/config.json]
   pi-webui uninstall
+  pi-webui install-extra [--dry-run] [--yes]
   pi-webui start|stop|restart|status|logs
   pi-webui doctor
   pi-webui version
@@ -939,8 +1167,13 @@ async function main() {
         await install(args);
     else if (command === "uninstall")
         await uninstall();
-    else if (command === "start" || command === "stop" || command === "restart" || command === "status")
+    else if (command === "start" ||
+        command === "stop" ||
+        command === "restart" ||
+        command === "status")
         serviceAction(command);
+    else if (command === "install-extra")
+        await installExtra(args);
     else if (command === "logs")
         logs();
     else if (command === "doctor")