Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(desktop,server,web): app icons, completion notifications, single-user mode, bundled penguin CLI (#226)

Yaowei Zheng082ab08e0b15
diff --git a/packages/desktop/build/icon.png b/packages/desktop/build/icon.png
new file mode 100644
index 00000000..90beb5fc
Binary files /dev/null and b/packages/desktop/build/icon.png differ
diff --git a/packages/desktop/build/icons/128x128.png b/packages/desktop/build/icons/128x128.png
new file mode 100644
index 00000000..d786d446
Binary files /dev/null and b/packages/desktop/build/icons/128x128.png differ
diff --git a/packages/desktop/build/icons/256x256.png b/packages/desktop/build/icons/256x256.png
new file mode 100644
index 00000000..4e964b74
Binary files /dev/null and b/packages/desktop/build/icons/256x256.png differ
diff --git a/packages/desktop/build/icons/512x512.png b/packages/desktop/build/icons/512x512.png
new file mode 100644
index 00000000..9ddc4a24
Binary files /dev/null and b/packages/desktop/build/icons/512x512.png differ
diff --git a/packages/desktop/build/linux/after-install.tpl b/packages/desktop/build/linux/after-install.tpl
new file mode 100644
index 00000000..19573c83
--- /dev/null
+++ b/packages/desktop/build/linux/after-install.tpl
@@ -0,0 +1,69 @@
+#!/bin/bash
+# Deb post-install (electron-builder deb.afterInstall). Overriding the option REPLACES
+# electron-builder's default template, so this file is that default (app-builder-lib
+# templates/linux/after-install.tpl, v26.15.3) verbatim, plus the marked PenguinHarness
+# section exposing the bundled `penguin` CLI launcher on PATH. The dollar-brace forms
+# are electron-builder template macros (executable, sanitizedProductName); any other
+# all-letter dollar-brace token fails the build, so shell variables stay brace-less.
+
+if type update-alternatives >/dev/null 2>&1; then
+ # Remove previous link if it doesn't use update-alternatives
+ if [ -L '/usr/bin/${executable}' -a -e '/usr/bin/${executable}' -a "`readlink '/usr/bin/${executable}'`" != '/etc/alternatives/${executable}' ]; then
+ rm -f '/usr/bin/${executable}'
+ fi
+ update-alternatives --install '/usr/bin/${executable}' '${executable}' '/opt/${sanitizedProductName}/${executable}' 100 || ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+else
+ ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+fi
+
+# PenguinHarness: expose the bundled penguin CLI launcher on PATH. Never clobber a real
+# file of that name; replacing a (possibly stale) symlink keeps re-installs idempotent.
+if [ ! -e '/usr/bin/penguin' ] || [ -L '/usr/bin/penguin' ]; then
+ ln -sf '/opt/${sanitizedProductName}/resources/app/bin/penguin' '/usr/bin/penguin'
+fi
+
+# Check if user namespaces are supported by the kernel and working with a quick test:
+if ! { [[ -L /proc/self/ns/user ]] && unshare --user true; }; then
+ # Use SUID chrome-sandbox only on systems without user namespaces:
+ chmod 4755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+else
+ chmod 0755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+fi
+
+if hash update-mime-database 2>/dev/null; then
+ update-mime-database /usr/share/mime || true
+fi
+
+if hash update-desktop-database 2>/dev/null; then
+ update-desktop-database /usr/share/applications || true
+fi
+
+# Install apparmor profile. (Ubuntu 24+)
+# First check if the version of AppArmor running on the device supports our profile.
+# This is in order to keep backwards compatibility with Ubuntu 22.04 which does not support abi/4.0.
+# In that case, we just skip installing the profile since the app runs fine without it on 22.04.
+#
+# Those apparmor_parser flags are akin to performing a dry run of loading a profile.
+# https://wiki.debian.org/AppArmor/HowToUse#Dumping_profiles
+#
+# Unfortunately, at the moment AppArmor doesn't have a good story for backwards compatibility.
+# https://askubuntu.com/questions/1517272/writing-a-backwards-compatible-apparmor-profile
+if apparmor_status --enabled > /dev/null 2>&1; then
+ APPARMOR_PROFILE_SOURCE='/opt/${sanitizedProductName}/resources/apparmor-profile'
+ APPARMOR_PROFILE_TARGET='/etc/apparmor.d/${executable}'
+ if apparmor_parser --skip-kernel-load --debug "$APPARMOR_PROFILE_SOURCE" > /dev/null 2>&1; then
+ cp -f "$APPARMOR_PROFILE_SOURCE" "$APPARMOR_PROFILE_TARGET"
+
+ # Updating the current AppArmor profile is not possible and probably not meaningful in a chroot'ed environment.
+ # Use cases are for example environments where images for clients are maintained.
+ # There, AppArmor might correctly be installed, but live updating makes no sense.
+ if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+ # Extra flags taken from dh_apparmor:
+ # > By using '-W -T' we ensure that any abstraction updates are also pulled in.
+ # https://wiki.debian.org/AppArmor/Contribute/FirstTimeProfileImport
+ apparmor_parser --replace --write-cache --skip-read-cache "$APPARMOR_PROFILE_TARGET"
+ fi
+ else
+ echo "Skipping the installation of the AppArmor profile as this version of AppArmor does not seem to support the bundled profile"
+ fi
+fi
diff --git a/packages/desktop/build/linux/after-remove.tpl b/packages/desktop/build/linux/after-remove.tpl
new file mode 100644
index 00000000..ce2523cc
--- /dev/null
+++ b/packages/desktop/build/linux/after-remove.tpl
@@ -0,0 +1,36 @@
+#!/bin/bash
+# Deb post-remove (electron-builder deb.afterRemove). Overriding the option REPLACES
+# electron-builder's default template, so this file is that default (app-builder-lib
+# templates/linux/after-remove.tpl, v26.15.3) verbatim, plus the marked PenguinHarness
+# section removing the `penguin` CLI launcher link installed by after-install.tpl.
+
+# Delete the link to the binary
+# update-alternatives --remove <name> <path>: 'path' must be the registered alternative binary,
+# not the generic symlink — see https://man7.org/linux/man-pages/man1/update-alternatives.1.html
+if type update-alternatives >/dev/null 2>&1; then
+ update-alternatives --remove '${executable}' '/opt/${sanitizedProductName}/${executable}'
+else
+ rm -f '/usr/bin/${executable}'
+fi
+
+# PenguinHarness: remove the penguin CLI launcher link, but only if it is ours.
+if [ -L '/usr/bin/penguin' ] && [ "`readlink '/usr/bin/penguin'`" = '/opt/${sanitizedProductName}/resources/app/bin/penguin' ]; then
+ rm -f '/usr/bin/penguin'
+fi
+
+APPARMOR_PROFILE_DEST='/etc/apparmor.d/${executable}'
+
+# Remove and unload apparmor profile.
+if [ -f "$APPARMOR_PROFILE_DEST" ]; then
+ # Unload the profile from the running kernel before deleting the file so the
+ # policy is not left enforced until the next reboot. Mirror the chroot guard
+ # used in the after-install script — live AppArmor operations are not
+ # meaningful inside a chroot.
+ # https://wiki.debian.org/AppArmor/HowToUse
+ if apparmor_status --enabled > /dev/null 2>&1; then
+ if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+ apparmor_parser --remove "$APPARMOR_PROFILE_DEST" || true
+ fi
+ fi
+ rm -f "$APPARMOR_PROFILE_DEST"
+fi
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 48ed21d0..7d7068f1 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -24,6 +24,10 @@ nodeGypRebuild: false
mac:
category: public.app-category.developer-tools
+ # Brand icon (rendered from packages/web/public/penguin-logo.svg by
+ # scripts/render-icon.mjs, committed): electron-builder converts the 1024px PNG to
+ # icns itself (app-builder-lib iconConverter; >=512px required).
+ icon: build/icon.png
# No Developer ID yet (M4): identity null skips codesign instead of failing.
identity: null
# Version-less artifact names, following the CLI bundles (penguin-darwin-arm64.tar.gz):
@@ -38,6 +42,9 @@ mac:
arch: [arm64, x64]
win:
+ # Same source PNG; electron-builder converts it to the multi-size ico embedded in the
+ # exe (>=256px required).
+ icon: build/icon.png
artifactName: penguin-desktop-win32-${arch}.${ext}
target:
- target: nsis
@@ -54,6 +61,9 @@ nsis:
allowToChangeInstallationDirectory: true
linux:
+ # Pre-rendered freedesktop icon set (scripts/render-icon.mjs): a directory of NxN.png
+ # files is used as-is for AppImage/deb, no conversion step.
+ icon: build/icons
# The scoped package name is not a valid executable file name.
executableName: penguin-harness
# ${arch} expands to each Linux target's own convention — x86_64 for AppImage, amd64
@@ -68,3 +78,11 @@ linux:
arch: [x64]
- target: deb
arch: [x64]
+
+deb:
+ # Extended copies of electron-builder's default scripts (overriding REPLACES them):
+ # they additionally create/remove the /usr/bin/penguin symlink to the staged CLI
+ # launcher (resources/app/bin/penguin), so a deb install gets the `penguin` command
+ # on PATH without the in-app install flow the other formats use.
+ afterInstall: build/linux/after-install.tpl
+ afterRemove: build/linux/after-remove.tpl
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index b9537374..827aeada 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -17,6 +17,7 @@
"pack:win": "node scripts/stage.mjs && electron-builder --win"
},
"dependencies": {
+ "@prismshadow/penguin-cli": "workspace:*",
"@prismshadow/penguin-core": "workspace:*",
"@prismshadow/penguin-server": "workspace:*"
},
diff --git a/packages/desktop/scripts/render-icon.mjs b/packages/desktop/scripts/render-icon.mjs
new file mode 100644
index 00000000..d51a0ac9
--- /dev/null
+++ b/packages/desktop/scripts/render-icon.mjs
@@ -0,0 +1,72 @@
+/**
+ * Render the app icon PNGs from the brand mark (packages/web/public/penguin-logo.svg,
+ * treated as immutable — landing/docs carry byte-identical copies).
+ *
+ * Outputs (COMMITTED — regenerate only when the SVG changes):
+ * - build/icon.png 1024×1024. electron-builder converts it to icns (mac,
+ * >=512px required) and ico (win, >=256px) at pack time;
+ * also the runtime BrowserWindow icon (see src/app-icon.ts).
+ * - build/icons/<N>x<N>.png 128/256/512 freedesktop set for the Linux targets
+ * (used as-is, no conversion).
+ *
+ * Regenerate: node packages/desktop/scripts/render-icon.mjs
+ * Rasterizes via the Playwright chromium already installed for packages/landing (no new
+ * dependency; precedent: packages/landing/scripts/capture-readme-demo.mjs). Each size is
+ * rendered at its native resolution (no downscaling), with a transparent background so
+ * the SVG's rounded-rect clip keeps the corners transparent.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = path.resolve(HERE, "..");
+const REPO_ROOT = path.resolve(PKG_DIR, "..", "..");
+const SVG_PATH = path.join(REPO_ROOT, "packages", "web", "public", "penguin-logo.svg");
+const BUILD_DIR = path.join(PKG_DIR, "build");
+const ICON_SET_DIR = path.join(BUILD_DIR, "icons");
+
+// Resolve @playwright/test from the landing package's context (it is not a dependency
+// of this package, and must not become one).
+const requireLanding = createRequire(path.join(REPO_ROOT, "packages", "landing", "package.json"));
+const { chromium } = requireLanding("@playwright/test");
+
+const svgDataUrl = `data:image/svg+xml;base64,${readFileSync(SVG_PATH).toString("base64")}`;
+
+/** [size, output path]; icon.png is the 1024 master, the rest form the Linux icon set. */
+const targets = [
+ [1024, path.join(BUILD_DIR, "icon.png")],
+ [512, path.join(ICON_SET_DIR, "512x512.png")],
+ [256, path.join(ICON_SET_DIR, "256x256.png")],
+ [128, path.join(ICON_SET_DIR, "128x128.png")],
+];
+
+mkdirSync(ICON_SET_DIR, { recursive: true });
+
+const browser = await chromium.launch();
+try {
+ for (const [size, outPath] of targets) {
+ const page = await browser.newPage({
+ viewport: { width: size, height: size },
+ deviceScaleFactor: 1,
+ });
+ await page.setContent(
+ `<style>html,body{margin:0;padding:0;background:transparent}` +
+ `img{display:block;width:${size}px;height:${size}px}</style>` +
+ `<img src="${svgDataUrl}">`,
+ );
+ await page.evaluate(() => document.querySelector("img").decode());
+ const png = await page.screenshot({
+ omitBackground: true,
+ clip: { x: 0, y: 0, width: size, height: size },
+ });
+ writeFileSync(outPath, png);
+ console.log(
+ `[render-icon] ${path.relative(PKG_DIR, outPath)} (${size}x${size}, ${png.length} bytes)`,
+ );
+ await page.close();
+ }
+} finally {
+ await browser.close();
+}
diff --git a/packages/desktop/scripts/stage.mjs b/packages/desktop/scripts/stage.mjs
index b9fc3858..7d7c8e36 100644
--- a/packages/desktop/scripts/stage.mjs
+++ b/packages/desktop/scripts/stage.mjs
@@ -2,20 +2,25 @@
* Assemble the self-contained app directory electron-builder packs (stage/app).
*
* `pnpm deploy --prod` materializes this package plus its production dependency tree —
- * including the workspace packages — into a portable directory whose symlinks all stay
- * inside it (verified: the server boots from the deploy dir as-is). On top of that:
+ * including the workspace packages (@prismshadow/penguin-cli among them, so the staged
+ * node_modules carries cli + server + core + skills) — into a portable directory whose
+ * symlinks all stay inside it (verified: the server boots from the deploy dir as-is).
+ * On top of that:
* - prune dev files (sources, configs) so only dist/, node_modules/ and package.json ship;
* - copy the web build to `node_modules/@prismshadow/penguin-server/web-dist`, the npm
* package layout the server's static-hosting lookup checks first;
+ * - copy build/icon.png into the app dir (the runtime window icon, see src/app-icon.ts);
+ * - generate the `penguin` CLI launchers into `bin/` (POSIX + Windows, see
+ * src/launcher.ts): they run the bundled CLI on the app's Electron runtime as Node;
* - ensure `stage/minigit` exists (may be empty): the Windows CI job downloads MinGit
* into it, and electron-builder's win extraResources entry must always have a source.
*
- * Run from anywhere; all paths are derived from this file's location.
+ * Run from anywhere (after `pnpm -r build`); all paths derive from this file's location.
*/
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const repoRoot = path.resolve(pkgDir, "..", "..");
@@ -76,6 +81,44 @@ if (!fs.existsSync(path.join(webDist, "index.html"))) {
const serverPkg = path.join(appDir, "node_modules", "@prismshadow", "penguin-server");
fs.cpSync(webDist, path.join(serverPkg, "web-dist"), { recursive: true, dereference: true });
+// The shell forks the server by this exact path, and the CLI launchers point at the
+// CLI entry: verify both landed in the deploy tree before packing.
+const launcherModule = path.join(pkgDir, "dist", "launcher.js");
+for (const [what, file] of [
+ ["server entry", path.join(serverPkg, "dist", "index.js")],
+ [
+ "CLI entry",
+ path.join(appDir, "node_modules", "@prismshadow", "penguin-cli", "dist", "index.js"),
+ ],
+ ["launcher generator (dist/launcher.js)", launcherModule],
+]) {
+ if (!fs.existsSync(file)) {
+ console.error(`[stage] missing ${what} (${file}) — run \`pnpm -r build\` first.`);
+ process.exit(1);
+ }
+}
+
+// Runtime window icon: same app-dir-relative location as the dev run (build/icon.png),
+// so src/app-icon.ts resolves it identically in both layouts.
+const iconSrc = path.join(pkgDir, "build", "icon.png");
+if (!fs.existsSync(iconSrc)) {
+ console.error("[stage] build/icon.png is missing — run `node scripts/render-icon.mjs`.");
+ process.exit(1);
+}
+fs.mkdirSync(path.join(appDir, "build"), { recursive: true });
+fs.copyFileSync(iconSrc, path.join(appDir, "build", "icon.png"));
+
+// CLI launchers (bin/penguin, bin/penguin.cmd): generated, not committed — the script
+// text lives in src/launcher.ts so it is unit-tested with the rest of the shell.
+const { posixLauncherScript, windowsLauncherScript } = await import(
+ pathToFileURL(launcherModule).href
+);
+const binDir = path.join(appDir, "bin");
+fs.mkdirSync(binDir, { recursive: true });
+fs.writeFileSync(path.join(binDir, "penguin"), posixLauncherScript(), { mode: 0o755 });
+fs.chmodSync(path.join(binDir, "penguin"), 0o755);
+fs.writeFileSync(path.join(binDir, "penguin.cmd"), windowsLauncherScript());
+
fs.mkdirSync(path.join(stageDir, "minigit"), { recursive: true });
console.log("[stage] done:", appDir);
diff --git a/packages/desktop/src/app-icon.ts b/packages/desktop/src/app-icon.ts
new file mode 100644
index 00000000..79e58ea9
--- /dev/null
+++ b/packages/desktop/src/app-icon.ts
@@ -0,0 +1,27 @@
+/**
+ * Runtime window icon — pure path logic, no Electron imports (unit-tested).
+ *
+ * Only Linux (and Windows dev runs) need it: a packaged Windows app gets its taskbar
+ * icon from the exe resources electron-builder embeds, and macOS ignores BrowserWindow
+ * icons entirely (the Dock icon comes from the bundle's icns). The PNG lives at
+ * build/icon.png both in the source package (committed, rendered by
+ * scripts/render-icon.mjs) and in the staged app directory (copied by scripts/stage.mjs),
+ * so the same app-path-relative lookup serves dev and packaged runs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/** Window icon location relative to the app directory (dev package dir / staged app dir). */
+export const WINDOW_ICON_RELPATH = ["build", "icon.png"];
+
+/** The window-icon path for a platform, or null where window icons are not used (macOS). */
+export function windowIconPathFor(appPath: string, platform: NodeJS.Platform): string | null {
+ if (platform === "darwin") return null;
+ return path.join(appPath, ...WINDOW_ICON_RELPATH);
+}
+
+/** Same, but only when the file actually exists (a missing icon must not break windows). */
+export function resolveWindowIcon(appPath: string, platform: NodeJS.Platform): string | null {
+ const iconPath = windowIconPathFor(appPath, platform);
+ return iconPath !== null && fs.existsSync(iconPath) ? iconPath : null;
+}
diff --git a/packages/desktop/src/cli-install.ts b/packages/desktop/src/cli-install.ts
new file mode 100644
index 00000000..7070320d
--- /dev/null
+++ b/packages/desktop/src/cli-install.ts
@@ -0,0 +1,212 @@
+/**
+ * "Install 'penguin' Command" — PATH exposure for the bundled CLI launcher
+ * (<app>/bin/penguin, generated at stage time; see launcher.ts).
+ *
+ * Per platform (deb is absent on purpose — its postinst ships /usr/bin/penguin, see
+ * build/linux/after-install.tpl):
+ * - macOS: symlink /usr/local/bin/penguin → <app>/bin/penguin; on permission errors,
+ * escalate ONCE via osascript "with administrator privileges".
+ * - Windows: append <app>\bin to the user PATH (HKCU\Environment) via reg.exe,
+ * idempotently (read + compare first); new terminals pick it up.
+ * - Linux AppImage: write an executable ~/.local/bin/penguin wrapper that runs the
+ * AppImage itself as Node (see launcher.ts appImageWrapperScript).
+ *
+ * Everything is native UI (menu item + dialogs) in English: the main process stays
+ * outside the web app's i18n, and per the design the desktop shell talks to the page
+ * only through the server's HTTP API — never a private IPC channel.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { app, dialog } from "electron";
+import type { BrowserWindow } from "electron";
+import { appImageWrapperScript, cliInstallKind, mergeWindowsUserPath } from "./launcher.js";
+import type { CliInstallKind } from "./launcher.js";
+
+const execFileAsync = promisify(execFile);
+
+/** The staged launcher directory inside the packaged app. */
+function binDir(): string {
+ return path.join(app.getAppPath(), "bin");
+}
+
+/** This run's install kind, or null when there is nothing to install (dev run / deb). */
+export function currentCliInstallKind(): CliInstallKind | null {
+ return cliInstallKind({
+ packaged: app.isPackaged,
+ platform: process.platform,
+ appImagePath: process.env.APPIMAGE ?? null,
+ });
+}
+
+function showResult(win: BrowserWindow | null, ok: boolean, detail: string): void {
+ const opts = {
+ type: ok ? ("info" as const) : ("error" as const),
+ title: "PenguinHarness",
+ message: ok
+ ? "The 'penguin' command is installed."
+ : "Could not install the 'penguin' command.",
+ detail,
+ };
+ void (win !== null ? dialog.showMessageBox(win, opts) : dialog.showMessageBox(opts));
+}
+
+/** macOS: /usr/local/bin/penguin symlink, escalating once via osascript on EACCES/EPERM. */
+async function installDarwin(win: BrowserWindow | null): Promise<void> {
+ const target = path.join(binDir(), "penguin");
+ const link = "/usr/local/bin/penguin";
+ try {
+ fs.mkdirSync("/usr/local/bin", { recursive: true });
+ fs.rmSync(link, { force: true });
+ fs.symlinkSync(target, link);
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException).code;
+ if (code !== "EACCES" && code !== "EPERM") {
+ showResult(win, false, String(err));
+ return;
+ }
+ // Privileged retry; paths contain no single quotes (the bundle path is fixed and
+ // /Applications-style paths at most contain spaces).
+ const shellCmd = `mkdir -p /usr/local/bin && ln -sf '${target}' '${link}'`;
+ try {
+ await execFileAsync("osascript", [
+ "-e",
+ `do shell script "${shellCmd.replace(/"/g, '\\"')}" with administrator privileges`,
+ ]);
+ } catch (escalated) {
+ showResult(
+ win,
+ false,
+ `Administrator authorization failed or was cancelled.\n${String(escalated)}`,
+ );
+ return;
+ }
+ }
+ showResult(
+ win,
+ true,
+ `${link} now points at the app's bundled CLI. Run 'penguin' from any terminal.`,
+ );
+}
+
+/** Windows: idempotent HKCU\Environment PATH append via reg.exe. */
+async function installWindows(win: BrowserWindow | null): Promise<void> {
+ const dir = binDir();
+ let current: string | null = null;
+ try {
+ const { stdout } = await execFileAsync("reg", ["query", "HKCU\\Environment", "/v", "Path"]);
+ // Output line: " Path REG_EXPAND_SZ C:\foo;C:\bar"
+ const m = /^\s*Path\s+REG(?:_EXPAND)?_SZ\s+(.*)$/im.exec(stdout);
+ if (m) current = m[1]!.trim();
+ } catch {
+ current = null; // No user Path value yet.
+ }
+ const merged = mergeWindowsUserPath(current, dir);
+ if (merged === null) {
+ showResult(win, true, `${dir} is already on your PATH. Run 'penguin' from any terminal.`);
+ return;
+ }
+ try {
+ // REG_EXPAND_SZ keeps any %VAR% entries of the existing value expandable.
+ await execFileAsync("reg", [
+ "add",
+ "HKCU\\Environment",
+ "/v",
+ "Path",
+ "/t",
+ "REG_EXPAND_SZ",
+ "/d",
+ merged,
+ "/f",
+ ]);
+ } catch (err) {
+ showResult(win, false, String(err));
+ return;
+ }
+ showResult(
+ win,
+ true,
+ `${dir} was added to your user PATH. Open a NEW terminal (existing ones keep the old PATH) and run 'penguin'.`,
+ );
+}
+
+/** Linux AppImage: executable ~/.local/bin/penguin wrapper invoking the AppImage as Node. */
+function installAppImage(win: BrowserWindow | null): void {
+ const appImage = process.env.APPIMAGE;
+ if (!appImage) {
+ showResult(win, false, "APPIMAGE is not set; this build cannot install the command.");
+ return;
+ }
+ const dir = path.join(os.homedir(), ".local", "bin");
+ const wrapper = path.join(dir, "penguin");
+ let script: string;
+ try {
+ script = appImageWrapperScript(appImage);
+ } catch (err) {
+ showResult(win, false, String(err));
+ return;
+ }
+ try {
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(wrapper, script, { mode: 0o755 });
+ fs.chmodSync(wrapper, 0o755); // writeFileSync mode is ignored when the file existed.
+ } catch (err) {
+ showResult(win, false, String(err));
+ return;
+ }
+ showResult(
+ win,
+ true,
+ `${wrapper} now runs the CLI bundled in this AppImage. Make sure ~/.local/bin is on your PATH (most distributions add it at login), then run 'penguin' from a new terminal. Re-run this menu item if you move the AppImage.`,
+ );
+}
+
+/** Runs the platform installer (menu item and first-launch offer both land here). */
+export async function installCliCommand(win: BrowserWindow | null): Promise<void> {
+ switch (currentCliInstallKind()) {
+ case "darwin":
+ await installDarwin(win);
+ return;
+ case "windows":
+ await installWindows(win);
+ return;
+ case "appimage":
+ installAppImage(win);
+ return;
+ case null:
+ showResult(win, false, "This build has no bundled CLI to install (development run).");
+ }
+}
+
+/**
+ * One-time first-launch offer: asks once per installation whether to install the
+ * command, and never again (the app menu keeps the entry point available). The
+ * "offered" flag persists under userData next to the shell's other state files.
+ */
+export async function maybeOfferCliInstall(win: BrowserWindow | null): Promise<void> {
+ if (currentCliInstallKind() === null) return;
+ const flag = path.join(app.getPath("userData"), "cli-install-offered");
+ try {
+ if (fs.existsSync(flag)) return;
+ fs.mkdirSync(path.dirname(flag), { recursive: true });
+ fs.writeFileSync(flag, `${new Date().toISOString()}\n`);
+ } catch {
+ return; // Unreadable/unwritable userData: skip rather than re-offer forever.
+ }
+ const opts = {
+ type: "question" as const,
+ title: "PenguinHarness",
+ message: "Install the 'penguin' command line tool?",
+ detail:
+ "Makes the CLI bundled with this app available in your terminal. You can do this later from the application menu: Install 'penguin' Command.",
+ buttons: ["Install", "Not Now"],
+ defaultId: 0,
+ cancelId: 1,
+ };
+ const { response } = await (win !== null
+ ? dialog.showMessageBox(win, opts)
+ : dialog.showMessageBox(opts));
+ if (response === 0) await installCliCommand(win);
+}
diff --git a/packages/desktop/src/launcher.ts b/packages/desktop/src/launcher.ts
new file mode 100644
index 00000000..a678a186
--- /dev/null
+++ b/packages/desktop/src/launcher.ts
@@ -0,0 +1,180 @@
+/**
+ * CLI launcher generation and PATH plumbing — pure helpers, no Electron imports, so
+ * they unit-test under plain vitest AND load in plain node: scripts/stage.mjs imports
+ * the built dist/launcher.js at stage time to write the launcher scripts into the
+ * packaged app directory's bin/.
+ *
+ * The launchers run the bundled @prismshadow/penguin-cli on the app's own Electron
+ * runtime as Node (ELECTRON_RUN_AS_NODE), so an installed desktop app provides a
+ * working `penguin` command without any system Node installation. How bin/ reaches
+ * PATH is per platform (see cli-install.ts and build/linux/*.tpl for the deb variant).
+ */
+
+/** CLI entry inside the staged app directory (pnpm-deploy layout, asar off). */
+export const CLI_ENTRY_RELPATH = "node_modules/@prismshadow/penguin-cli/dist/index.js";
+
+/**
+ * Platform executable names, fixed by electron-builder.yml: productName PenguinHarness
+ * (macOS bundle executable and Windows .exe) and linux.executableName penguin-harness.
+ */
+export const MAC_EXECUTABLE = "PenguinHarness";
+export const WIN_EXECUTABLE = "PenguinHarness.exe";
+export const LINUX_EXECUTABLE = "penguin-harness";
+
+/**
+ * POSIX launcher, staged as `<app>/bin/penguin` (chmod 755). Resolves its own real
+ * location first (PATH exposure is a symlink on macOS/deb), then finds the Electron
+ * executable at the platform's fixed position relative to the app directory:
+ * - macOS: app dir is `<bundle>/Contents/Resources/app` → `../../MacOS/PenguinHarness`
+ * - Linux: app dir is `<install>/resources/app` → `../../penguin-harness`
+ */
+export function posixLauncherScript(): string {
+ return `#!/bin/sh
+# penguin CLI launcher (generated by packages/desktop/scripts/stage.mjs).
+# Runs the bundled penguin CLI on this app's Electron runtime as Node
+# (ELECTRON_RUN_AS_NODE=1) - no system Node installation required.
+
+# Resolve this script's real location; PATH exposure installs a symlink to it
+# (readlink -f is not portable to macOS, hence the loop).
+SOURCE=$0
+while [ -h "$SOURCE" ]; do
+ DIR=$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)
+ SOURCE=$(readlink "$SOURCE")
+ case $SOURCE in
+ /*) ;;
+ *) SOURCE="$DIR/$SOURCE" ;;
+ esac
+done
+BIN_DIR=$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)
+APP_DIR=$(dirname "$BIN_DIR")
+
+CLI_ENTRY="$APP_DIR/${CLI_ENTRY_RELPATH}"
+# The Electron executable sits at a fixed location relative to the app directory:
+# macOS <bundle>/Contents/Resources/app -> ../../MacOS/${MAC_EXECUTABLE};
+# Linux <install>/resources/app -> ../../${LINUX_EXECUTABLE}.
+for CANDIDATE in "$APP_DIR/../../MacOS/${MAC_EXECUTABLE}" "$APP_DIR/../../${LINUX_EXECUTABLE}"; do
+ if [ -x "$CANDIDATE" ]; then
+ export ELECTRON_RUN_AS_NODE=1
+ exec "$CANDIDATE" "$CLI_ENTRY" "$@"
+ fi
+done
+echo "penguin: could not find the PenguinHarness runtime next to $APP_DIR" >&2
+exit 1
+`;
+}
+
+/**
+ * Windows launcher, staged as `<app>\\bin\\penguin.cmd`. `%~dp0` is this script's
+ * directory (with a trailing backslash): the exe sits three levels up
+ * (bin -> app -> resources -> install root), the CLI entry one level up in the app dir.
+ * CRLF line endings on purpose - cmd.exe is unreliable with bare LF scripts.
+ */
+export function windowsLauncherScript(): string {
+ return [
+ "@echo off",
+ "rem penguin CLI launcher (generated by packages/desktop/scripts/stage.mjs).",
+ "rem Runs the bundled penguin CLI on this app's Electron runtime as Node.",
+ "setlocal",
+ 'set "ELECTRON_RUN_AS_NODE=1"',
+ `"%~dp0..\\..\\..\\${WIN_EXECUTABLE}" "%~dp0..\\${CLI_ENTRY_RELPATH.replaceAll("/", "\\")}" %*`,
+ "exit /b %errorlevel%",
+ "",
+ ].join("\r\n");
+}
+
+/**
+ * Single-line CJS bootstrap for the AppImage wrapper (`electron -e <this>`): resolves
+ * the CLI entry relative to the mounted application (process.execPath is the Electron
+ * binary inside the AppImage mount, resources/app sits next to it), splices it into
+ * argv[1] so `node -e` argv ([execPath, ...args]) becomes the [execPath, entry, ...args]
+ * shape the CLI's argv parsing expects, then imports the (ESM) entry. Must not contain
+ * single quotes: the wrapper embeds it in a single-quoted shell string.
+ */
+export function appImageBootstrapJs(): string {
+ return (
+ 'const path=require("path");' +
+ 'const cli=path.join(path.dirname(process.execPath),"resources","app",' +
+ '"node_modules","@prismshadow","penguin-cli","dist","index.js");' +
+ "process.argv.splice(1,0,cli);" +
+ "import(cli).catch((err)=>{console.error(err);process.exit(1);});"
+ );
+}
+
+/**
+ * Wrapper script installed to ~/.local/bin/penguin for the AppImage form, which has no
+ * stable install directory to symlink into: it invokes the AppImage itself as Node.
+ * The AppImage path is baked in at install time; the guard turns a moved/deleted
+ * AppImage into a clear message instead of a shell "not found".
+ */
+export function appImageWrapperScript(appImagePath: string): string {
+ if (appImagePath.includes("'")) {
+ // A quote would break out of the single-quoted assignment below; refuse rather
+ // than generate a broken (or injectable) script.
+ throw new Error(`AppImage path must not contain single quotes: ${appImagePath}`);
+ }
+ return `#!/bin/sh
+# penguin CLI launcher (generated by the PenguinHarness desktop app).
+# Runs the CLI bundled inside the AppImage by starting the AppImage's Electron
+# runtime as Node (ELECTRON_RUN_AS_NODE=1). If the AppImage moves, re-run
+# "Install 'penguin' Command" from the PenguinHarness application menu.
+APPIMAGE_PATH='${appImagePath}'
+if [ ! -x "$APPIMAGE_PATH" ]; then
+ echo "penguin: AppImage not found at $APPIMAGE_PATH (moved or deleted?)." >&2
+ echo "penguin: re-run \\"Install 'penguin' Command\\" from the PenguinHarness menu." >&2
+ exit 1
+fi
+export ELECTRON_RUN_AS_NODE=1
+# The -- ends Node option parsing: without it a leading-dash argument (penguin --help)
+# would be swallowed as a Node flag instead of reaching the CLI.
+exec "$APPIMAGE_PATH" -e '${appImageBootstrapJs()}' -- "$@"
+`;
+}
+
+/**
+ * Idempotent HKCU\\Environment PATH append: returns the new value to write, or null
+ * when `binDir` is already present (comparison ignores case, surrounding quotes and
+ * trailing slashes). The existing value is preserved verbatim — only `;binDir` is
+ * appended — so other software's entries are never rewritten.
+ */
+export function mergeWindowsUserPath(
+ current: string | null | undefined,
+ binDir: string,
+): string | null {
+ const normalize = (entry: string): string =>
+ entry
+ .trim()
+ .replace(/^"|"$/g, "")
+ .replace(/[\\/]+$/, "")
+ .toLowerCase();
+ const target = binDir.trim().replace(/[\\/]+$/, "");
+ const base = (current ?? "").trim();
+ const present = base
+ .split(";")
+ .map(normalize)
+ .some((entry) => entry !== "" && entry === normalize(target));
+ if (present) return null;
+ if (base === "") return target;
+ return base.endsWith(";") ? `${base}${target}` : `${base};${target}`;
+}
+
+export type CliInstallKind = "darwin" | "windows" | "appimage";
+
+/**
+ * Whether (and how) this run can install the `penguin` command onto PATH. Dev runs have
+ * no staged bin/; deb installs already ship a /usr/bin symlink from their postinst
+ * script (build/linux/after-install.tpl), so only the AppImage form qualifies on Linux
+ * (recognized by the APPIMAGE env var its runtime sets).
+ */
+export function cliInstallKind(opts: {
+ packaged: boolean;
+ platform: NodeJS.Platform;
+ appImagePath: string | null;
+}): CliInstallKind | null {
+ if (!opts.packaged) return null;
+ if (opts.platform === "darwin") return "darwin";
+ if (opts.platform === "win32") return "windows";
+ if (opts.platform === "linux" && opts.appImagePath !== null && opts.appImagePath !== "") {
+ return "appimage";
+ }
+ return null;
+}
diff --git a/packages/desktop/src/main.ts b/packages/desktop/src/main.ts
index 98200618..0b732353 100644
--- a/packages/desktop/src/main.ts
+++ b/packages/desktop/src/main.ts
@@ -19,6 +19,9 @@ import path from "node:path";
import { app, BrowserWindow, dialog, shell } from "electron";
import { resolveRoot } from "@prismshadow/penguin-core";
import { liveServerLock } from "@prismshadow/penguin-server/lock";
+import { resolveWindowIcon } from "./app-icon.js";
+import { installCliCommand, maybeOfferCliInstall, currentCliInstallKind } from "./cli-install.js";
+import { installAppMenu } from "./menu.js";
import { startEmbeddedServer, stopEmbeddedServer } from "./server-process.js";
import type { EmbeddedServer } from "./server-process.js";
import {
@@ -30,6 +33,10 @@ import {
} from "./util.js";
app.setName("PenguinHarness");
+// Windows toasts (the web app's task-completion notifications) need the AppUserModelID
+// of the installed shortcuts; electron-builder stamps them with the appId. Keep in sync
+// with electron-builder.yml.
+if (process.platform === "win32") app.setAppUserModelId("com.prismshadow.penguinharness");
let win: BrowserWindow | null = null;
let server: EmbeddedServer | null = null;
@@ -46,11 +53,15 @@ function fatal(context: string, err: unknown): void {
}
function createWindow(url: string): void {
+ // Linux window/taskbar icon (and Windows dev runs); packaged Windows uses the exe
+ // resources and macOS its bundle icns, so those ignore it (see app-icon.ts).
+ const iconPath = resolveWindowIcon(app.getAppPath(), process.platform);
win = new BrowserWindow({
width: 1280,
height: 860,
show: false,
autoHideMenuBar: true,
+ ...(iconPath !== null ? { icon: iconPath } : {}),
webPreferences: {
// The window is a plain browser: no Node, no preload — the minimal attack surface.
contextIsolation: true,
@@ -75,6 +86,7 @@ function createWindow(url: string): void {
width: 1100,
height: 800,
autoHideMenuBar: true,
+ ...(iconPath !== null ? { icon: iconPath } : {}),
// Same hardening as the main window: the preview is Agent-written, untrusted
// HTML and must never get Node.
webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
@@ -202,9 +214,20 @@ if (!app.requestSingleInstanceLock()) {
}
});
- void app
- .whenReady()
- .then(() => boot().catch((err) => fatal("PenguinHarness failed to start.", err)));
+ void app.whenReady().then(() =>
+ (async () => {
+ // Standard menu plus the CLI-install entry where installing makes sense
+ // (packaged macOS / Windows / AppImage; deb ships /usr/bin/penguin itself).
+ installAppMenu({
+ includeCliInstall: currentCliInstallKind() !== null,
+ onInstallCli: () => void installCliCommand(win),
+ });
+ await boot();
+ // First launch only: offer the 'penguin' command once; the menu entry remains.
+ // Skipped in smoke mode — a modal dialog would hang the automated run.
+ if (process.env.PENGUIN_DESKTOP_SMOKE !== "1") await maybeOfferCliInstall(win);
+ })().catch((err) => fatal("PenguinHarness failed to start.", err)),
+ );
}
// --- smoke hook ------------------------------------------------------------
diff --git a/packages/desktop/src/menu.ts b/packages/desktop/src/menu.ts
new file mode 100644
index 00000000..aa0d2a68
--- /dev/null
+++ b/packages/desktop/src/menu.ts
@@ -0,0 +1,54 @@
+/**
+ * Application menu. Electron's default menu cannot be extended, only replaced, so the
+ * standard structure is rebuilt here — on macOS the Edit roles are what make clipboard
+ * shortcuts work inside the window, so they must be present. The one custom entry is
+ * "Install 'penguin' Command…" (see cli-install.ts), shown only where installing makes
+ * sense (packaged macOS / Windows / AppImage; deb ships /usr/bin/penguin itself).
+ * On Windows/Linux the window uses autoHideMenuBar, so the bar appears on Alt.
+ */
+import { app, Menu } from "electron";
+import type { MenuItemConstructorOptions } from "electron";
+
+export const INSTALL_CLI_MENU_LABEL = "Install 'penguin' Command…";
+
+export function installAppMenu(opts: {
+ includeCliInstall: boolean;
+ onInstallCli: () => void;
+}): void {
+ const isMac = process.platform === "darwin";
+ const cliItems: MenuItemConstructorOptions[] = opts.includeCliInstall
+ ? [{ label: INSTALL_CLI_MENU_LABEL, click: opts.onInstallCli }]
+ : [];
+
+ const template: MenuItemConstructorOptions[] = [];
+ if (isMac) {
+ template.push({
+ label: app.name,
+ submenu: [
+ { role: "about" },
+ ...(cliItems.length > 0
+ ? ([{ type: "separator" }, ...cliItems] as MenuItemConstructorOptions[])
+ : []),
+ { type: "separator" },
+ { role: "services" },
+ { type: "separator" },
+ { role: "hide" },
+ { role: "hideOthers" },
+ { role: "unhide" },
+ { type: "separator" },
+ { role: "quit" },
+ ],
+ });
+ } else {
+ template.push({
+ label: "File",
+ submenu: [
+ ...cliItems,
+ ...(cliItems.length > 0 ? ([{ type: "separator" }] as MenuItemConstructorOptions[]) : []),
+ { role: "quit" },
+ ],
+ });
+ }
+ template.push({ role: "editMenu" }, { role: "viewMenu" }, { role: "windowMenu" });
+ Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}
diff --git a/packages/desktop/test/app-icon.test.ts b/packages/desktop/test/app-icon.test.ts
new file mode 100644
index 00000000..86d36944
--- /dev/null
+++ b/packages/desktop/test/app-icon.test.ts
@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import { resolveWindowIcon, WINDOW_ICON_RELPATH, windowIconPathFor } from "../src/app-icon.js";
+
+describe("windowIconPathFor", () => {
+ it("is null on macOS (window icons are ignored; the bundle icns owns the Dock)", () => {
+ expect(windowIconPathFor("/app", "darwin")).toBeNull();
+ });
+
+ it("resolves build/icon.png inside the app dir on Linux and Windows", () => {
+ expect(windowIconPathFor("/app", "linux")).toBe(path.join("/app", ...WINDOW_ICON_RELPATH));
+ expect(windowIconPathFor("C:\\app", "win32")).toBe(
+ path.join("C:\\app", ...WINDOW_ICON_RELPATH),
+ );
+ });
+});
+
+describe("resolveWindowIcon", () => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-desktop-icon-"));
+ afterAll(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+ it("returns the path only when the file exists", () => {
+ expect(resolveWindowIcon(tmp, "linux")).toBeNull();
+ fs.mkdirSync(path.join(tmp, "build"), { recursive: true });
+ fs.writeFileSync(path.join(tmp, "build", "icon.png"), "png");
+ expect(resolveWindowIcon(tmp, "linux")).toBe(path.join(tmp, "build", "icon.png"));
+ expect(resolveWindowIcon(tmp, "darwin")).toBeNull();
+ });
+
+ it("the committed source icon resolves for a dev run of this package", () => {
+ const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+ expect(resolveWindowIcon(pkgDir, "linux")).toBe(path.join(pkgDir, "build", "icon.png"));
+ });
+});
diff --git a/packages/desktop/test/launcher.test.ts b/packages/desktop/test/launcher.test.ts
new file mode 100644
index 00000000..a30f2ebe
--- /dev/null
+++ b/packages/desktop/test/launcher.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import {
+ appImageBootstrapJs,
+ appImageWrapperScript,
+ CLI_ENTRY_RELPATH,
+ cliInstallKind,
+ LINUX_EXECUTABLE,
+ MAC_EXECUTABLE,
+ mergeWindowsUserPath,
+ posixLauncherScript,
+ WIN_EXECUTABLE,
+ windowsLauncherScript,
+} from "../src/launcher.js";
+
+describe("posixLauncherScript", () => {
+ const script = posixLauncherScript();
+
+ it("is a /bin/sh script that resolves symlinks before locating the runtime", () => {
+ expect(script.startsWith("#!/bin/sh\n")).toBe(true);
+ expect(script).toContain('while [ -h "$SOURCE" ]');
+ expect(script).toContain("readlink");
+ });
+
+ it("targets the bundled CLI entry and both platform runtime locations", () => {
+ expect(script).toContain(`CLI_ENTRY="$APP_DIR/${CLI_ENTRY_RELPATH}"`);
+ // macOS: resources/app -> ../../MacOS/<executable>; Linux: -> ../../<executableName>.
+ expect(script).toContain(`"$APP_DIR/../../MacOS/${MAC_EXECUTABLE}"`);
+ expect(script).toContain(`"$APP_DIR/../../${LINUX_EXECUTABLE}"`);
+ });
+
+ it("execs as Node and forwards all arguments", () => {
+ expect(script).toContain("export ELECTRON_RUN_AS_NODE=1");
+ expect(script).toContain('exec "$CANDIDATE" "$CLI_ENTRY" "$@"');
+ });
+
+ it("fails with a message when no runtime is found", () => {
+ expect(script).toContain("exit 1");
+ });
+});
+
+describe("windowsLauncherScript", () => {
+ const script = windowsLauncherScript();
+
+ it("uses CRLF line endings (cmd.exe is unreliable with bare LF)", () => {
+ expect(script).toContain("\r\n");
+ expect(script.split("\r\n").join("")).not.toContain("\n");
+ });
+
+ it("finds the exe three levels up from bin\\ and the CLI entry in the app dir", () => {
+ expect(script).toContain(`"%~dp0..\\..\\..\\${WIN_EXECUTABLE}"`);
+ expect(script).toContain(`"%~dp0..\\${CLI_ENTRY_RELPATH.replaceAll("/", "\\")}"`);
+ });
+
+ it("runs as Node, forwards arguments and propagates the exit code", () => {
+ expect(script).toContain('set "ELECTRON_RUN_AS_NODE=1"');
+ expect(script).toContain(" %*");
+ expect(script).toContain("exit /b %errorlevel%");
+ });
+});
+
+describe("appImageWrapperScript", () => {
+ const appImage = "/home/user/Apps/penguin-desktop-linux-x86_64.AppImage";
+ const script = appImageWrapperScript(appImage);
+
+ it("bakes in the AppImage path and guards against it disappearing", () => {
+ expect(script).toContain(`APPIMAGE_PATH='${appImage}'`);
+ expect(script).toContain('if [ ! -x "$APPIMAGE_PATH" ]');
+ });
+
+ it("invokes the AppImage as Node with the bootstrap and forwards arguments", () => {
+ expect(script).toContain("export ELECTRON_RUN_AS_NODE=1");
+ // The -- is load-bearing: without it Node swallows leading-dash arguments
+ // (penguin --help) as its own flags instead of passing them to the CLI.
+ expect(script).toContain(`exec "$APPIMAGE_PATH" -e '${appImageBootstrapJs()}' -- "$@"`);
+ });
+
+ it("refuses paths containing single quotes (they would break the quoting)", () => {
+ expect(() => appImageWrapperScript("/tmp/it's.AppImage")).toThrow(/single quote/);
+ });
+});
+
+describe("appImageBootstrapJs", () => {
+ const js = appImageBootstrapJs();
+
+ it("contains no single quotes (embedded in a single-quoted shell string)", () => {
+ expect(js).not.toContain("'");
+ });
+
+ it("resolves the CLI entry relative to process.execPath and fixes argv", () => {
+ expect(js).toContain("process.execPath");
+ expect(js).toContain('"resources","app"');
+ expect(js).toContain('"penguin-cli","dist","index.js"');
+ // node -e argv is [execPath, ...args]; the CLI slices argv from index 2, so the
+ // entry path must be spliced in at index 1.
+ expect(js).toContain("process.argv.splice(1,0,cli)");
+ expect(js).toContain("import(cli)");
+ });
+
+ it("is valid JavaScript", () => {
+ // eslint-disable-next-line @typescript-eslint/no-implied-eval
+ expect(() => new Function(js)).not.toThrow();
+ });
+});
+
+describe("mergeWindowsUserPath", () => {
+ const bin = "C:\\Program Files\\PenguinHarness\\resources\\app\\bin";
+
+ it("appends to an existing value with a semicolon", () => {
+ expect(mergeWindowsUserPath("C:\\other", bin)).toBe(`C:\\other;${bin}`);
+ });
+
+ it("does not double the separator when the value ends with one", () => {
+ expect(mergeWindowsUserPath("C:\\other;", bin)).toBe(`C:\\other;${bin}`);
+ });
+
+ it("starts a missing or empty value with just the bin dir", () => {
+ expect(mergeWindowsUserPath(null, bin)).toBe(bin);
+ expect(mergeWindowsUserPath("", bin)).toBe(bin);
+ expect(mergeWindowsUserPath(" ", bin)).toBe(bin);
+ });
+
+ it("is idempotent: returns null when already present", () => {
+ expect(mergeWindowsUserPath(`C:\\other;${bin}`, bin)).toBeNull();
+ });
+
+ it("matches case-insensitively and ignores quotes and trailing slashes", () => {
+ expect(
+ mergeWindowsUserPath(`c:\\program files\\penguinharness\\RESOURCES\\app\\BIN`, bin),
+ ).toBeNull();
+ expect(mergeWindowsUserPath(`"${bin}"`, bin)).toBeNull();
+ expect(mergeWindowsUserPath(`${bin}\\`, bin)).toBeNull();
+ });
+
+ it("preserves the existing value verbatim (including %VAR% entries)", () => {
+ const current = "%USERPROFILE%\\bin;C:\\tools";
+ expect(mergeWindowsUserPath(current, bin)).toBe(`${current};${bin}`);
+ });
+});
+
+describe("cliInstallKind", () => {
+ it("is null for dev runs regardless of platform", () => {
+ expect(cliInstallKind({ packaged: false, platform: "darwin", appImagePath: null })).toBeNull();
+ expect(cliInstallKind({ packaged: false, platform: "win32", appImagePath: null })).toBeNull();
+ });
+
+ it("maps packaged macOS and Windows to their installers", () => {
+ expect(cliInstallKind({ packaged: true, platform: "darwin", appImagePath: null })).toBe(
+ "darwin",
+ );
+ expect(cliInstallKind({ packaged: true, platform: "win32", appImagePath: null })).toBe(
+ "windows",
+ );
+ });
+
+ it("on Linux only the AppImage form installs (deb ships /usr/bin/penguin itself)", () => {
+ expect(cliInstallKind({ packaged: true, platform: "linux", appImagePath: null })).toBeNull();
+ expect(cliInstallKind({ packaged: true, platform: "linux", appImagePath: "" })).toBeNull();
+ expect(
+ cliInstallKind({ packaged: true, platform: "linux", appImagePath: "/x/y.AppImage" }),
+ ).toBe("appimage");
+ });
+});
diff --git a/packages/desktop/tsup.config.ts b/packages/desktop/tsup.config.ts
index 788f130e..ae599615 100644
--- a/packages/desktop/tsup.config.ts
+++ b/packages/desktop/tsup.config.ts
@@ -1,7 +1,9 @@
import { defineConfig } from "tsup";
export default defineConfig({
- entry: ["src/main.ts"],
+ // launcher.ts is a second entry on purpose: scripts/stage.mjs imports dist/launcher.js
+ // at stage time (plain node, no Electron) to generate the CLI launcher scripts.
+ entry: ["src/main.ts", "src/launcher.ts"],
format: ["esm"],
target: "node22",
platform: "node",
diff --git a/packages/docs/content/server-api.en.md b/packages/docs/content/server-api.en.md
index 70573a1a..a65faac2 100644
--- a/packages/docs/content/server-api.en.md
+++ b/packages/docs/content/server-api.en.md
@@ -67,6 +67,8 @@ curl -c cookies.txt -H "Content-Type: application/json" \
| POST | /api/admin/users/:userId/password | Reset a password (invalidates all of that user's login sessions) |
| DELETE | /api/admin/users/:userId | Delete a user |
+In desktop mode (the server spawned by the desktop app) the whole surface answers `403` with code `desktop_single_user`: the desktop app is single-user, so user management is disabled — existing users in the data root are untouched.
+
### Server Settings (admin only)
| Method | Path | Description |
@@ -97,7 +99,7 @@ curl -c cookies.txt -H "Content-Type: application/json" \
| POST | /api/projects/:projectId/members | Add a member: `{userId}` |
| DELETE | /api/projects/:projectId/members/:userId | Remove a member |
-Member writes are owner-only.
+Member writes are owner-only. The member routes also answer `403 desktop_single_user` in desktop mode (see User Administration above).
### Models
diff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.md
index f96b7aae..c9b31ebe 100644
--- a/packages/docs/content/server-api.zh.md
+++ b/packages/docs/content/server-api.zh.md
@@ -67,6 +67,8 @@ curl -c cookies.txt -H "Content-Type: application/json" \
| POST | /api/admin/users/:userId/password | 重置密码(该用户全部登录会话失效) |
| DELETE | /api/admin/users/:userId | 删除用户 |
+桌面模式下(server 由桌面应用拉起)整组路由返回 `403`、错误码 `desktop_single_user`:桌面应用是单用户形态,用户管理整体停用——数据根中已有的用户不受影响。
+
### 服务端设置(仅管理员)
| 方法 | 路径 | 说明 |
@@ -97,7 +99,7 @@ curl -c cookies.txt -H "Content-Type: application/json" \
| POST | /api/projects/:projectId/members | 添加成员:`{userId}` |
| DELETE | /api/projects/:projectId/members/:userId | 移除成员 |
-成员写操作仅限 Owner。
+成员写操作仅限 Owner。成员路由在桌面模式下同样返回 `403 desktop_single_user`(见上文「用户管理」)。
### 模型
diff --git a/packages/server/src/http/routes/admin.ts b/packages/server/src/http/routes/admin.ts
index 73f6a5d2..522436f5 100644
--- a/packages/server/src/http/routes/admin.ts
+++ b/packages/server/src/http/routes/admin.ts
@@ -1,10 +1,12 @@
/**
- * Admin user-backend routes: only the built-in admin can use these (403 for non-admins).
+ * Admin user-backend routes: only the built-in admin can use these (403 for non-admins),
+ * and desktop mode rejects the whole surface (single-user; 403 `desktop_single_user`).
* GET|POST /api/admin/users, POST /api/admin/users/:userId/password, DELETE /api/admin/users/:userId.
*/
import { Hono } from "hono";
import type { AdminUserCreateResponse, AdminUsersResponse } from "../../api/types.js";
import { HttpError } from "../errors.js";
+import { rejectInDesktopMode } from "./desktop.js";
import type { AppEnv } from "../../auth/middleware.js";
import { pathParam, readJson, requireString } from "../validate.js";
import type { AppDeps } from "../../app.js";
@@ -12,6 +14,7 @@ import type { AppDeps } from "../../app.js";
export function adminUsersRoutes(deps: AppDeps): Hono<AppEnv> {
const app = new Hono<AppEnv>();
+ app.use("*", rejectInDesktopMode(deps));
app.use("*", async (c, next) => {
if (!c.var.user.isAdmin) {
throw new HttpError(403, "admin_required", "Only an admin can perform this operation.");
diff --git a/packages/server/src/http/routes/desktop.ts b/packages/server/src/http/routes/desktop.ts
index 2ee692ff..572a35b0 100644
--- a/packages/server/src/http/routes/desktop.ts
+++ b/packages/server/src/http/routes/desktop.ts
@@ -1,15 +1,37 @@
/**
- * Desktop-mode routes: POST /api/desktop/shutdown.
+ * Desktop-mode routes: POST /api/desktop/shutdown, plus the shared desktop-mode guard
+ * that turns off multi-user surfaces (see rejectInDesktopMode).
*
- * Authenticated by the shell's Bearer token, not the cookie session (the shell holds no
- * cookie), so this mounts OUTSIDE authMiddleware and only when desktop mode is enabled.
- * Responds 202 first, then triggers the graceful shutdown a beat later so the response
- * isn't cut off by the closing listener.
+ * The shutdown route is authenticated by the shell's Bearer token, not the cookie
+ * session (the shell holds no cookie), so it mounts OUTSIDE authMiddleware and only
+ * when desktop mode is enabled. Responds 202 first, then triggers the graceful
+ * shutdown a beat later so the response isn't cut off by the closing listener.
*/
import { Hono } from "hono";
+import type { MiddlewareHandler } from "hono";
import { HttpError } from "../errors.js";
import type { AppDeps } from "../../app.js";
+/**
+ * Guard for user-management surfaces (admin users, Project members): the desktop app is
+ * single-user, so the whole surface answers 403 with a dedicated code rather than being
+ * unmounted — a stray client gets a clear, localizable error instead of a 404. Existing
+ * users and memberships in the data root are untouched; only the management routes are
+ * closed while the server runs under the desktop shell.
+ */
+export function rejectInDesktopMode(deps: AppDeps): MiddlewareHandler {
+ return async (_c, next) => {
+ if (deps.desktop !== null) {
+ throw new HttpError(
+ 403,
+ "desktop_single_user",
+ "User management is disabled in the desktop app (single-user mode).",
+ );
+ }
+ await next();
+ };
+}
+
/** Delay between answering 202 and starting shutdown: lets the response flush. */
const SHUTDOWN_DELAY_MS = 50;
diff --git a/packages/server/src/http/routes/members.ts b/packages/server/src/http/routes/members.ts
index f747781e..ff75c6c4 100644
--- a/packages/server/src/http/routes/members.ts
+++ b/packages/server/src/http/routes/members.ts
@@ -2,16 +2,20 @@
* Member authorization routes:
* GET|POST /api/projects/:p/members, DELETE /api/projects/:p/members/:userId.
* Reading requires access; adding/removing is owner-only (validated inside the service).
+ * Desktop mode rejects the whole surface (single-user; 403 `desktop_single_user`).
*/
import { Hono } from "hono";
import type { MemberAddResponse, MembersResponse } from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
+import { rejectInDesktopMode } from "./desktop.js";
import { pathParam, readJson, requireString, requireValidId } from "../validate.js";
import type { AppDeps } from "../../app.js";
export function membersRoutes(deps: AppDeps): Hono<AppEnv> {
const app = new Hono<AppEnv>();
+ app.use("*", rejectInDesktopMode(deps));
+
app.get("/", (c) => {
// Defensive id validation (FD-4).
const members = deps.projectService.listMembers(
diff --git a/packages/server/test/desktop.test.ts b/packages/server/test/desktop.test.ts
index 1b636808..53a4ab7f 100644
--- a/packages/server/test/desktop.test.ts
+++ b/packages/server/test/desktop.test.ts
@@ -1,10 +1,11 @@
/**
* Desktop mode: one-shot desktop-login, Bearer-token shutdown, desktopMode in /api/me,
- * and the desktop-session password change without oldPassword.
+ * the desktop-session password change without oldPassword, and the single-user guard
+ * closing the user-management and Project-member surfaces.
*/
import { describe, expect, it } from "vitest";
import { apiClient, createTestApp, loginAdmin } from "./helpers.js";
-import type { MeResponse } from "../src/api/types.js";
+import type { ErrorBody, MeResponse } from "../src/api/types.js";
const TOKEN = "test-desktop-token";
@@ -119,6 +120,75 @@ describe("desktop shutdown endpoint", () => {
});
});
+describe("desktop single-user mode", () => {
+ async function expectSingleUser403(res: Response): Promise<void> {
+ expect(res.status).toBe(403);
+ const body = (await res.json()) as ErrorBody;
+ expect(body.error.code).toBe("desktop_single_user");
+ }
+
+ it("rejects the whole admin-users surface with desktop_single_user", async () => {
+ const t = await desktopApp();
+ try {
+ // The seeded admin signed in through the regular login form: even a fully
+ // authorized admin session gets the dedicated 403, not admin_required.
+ const admin = await loginAdmin(t.app);
+ const api = apiClient(t.app, admin.cookie);
+ await expectSingleUser403(await api.get("/api/admin/users"));
+ await expectSingleUser403(
+ await api.post("/api/admin/users", { userId: "eve", password: "password-123" }),
+ );
+ await expectSingleUser403(
+ await api.post("/api/admin/users/admin/password", { password: "password-456" }),
+ );
+ await expectSingleUser403(
+ await t.app.request("/api/admin/users/eve", {
+ method: "DELETE",
+ headers: { cookie: admin.cookie },
+ }),
+ );
+ // No user was created by the rejected POST.
+ expect(t.deps.db.prepare("SELECT COUNT(*) AS n FROM users").get()?.n).toBe(1);
+ } finally {
+ await t.cleanup();
+ }
+ });
+
+ it("rejects Project member management (reads and writes) with desktop_single_user", async () => {
+ const t = await desktopApp();
+ try {
+ const admin = await loginAdmin(t.app);
+ const api = apiClient(t.app, admin.cookie);
+ await expectSingleUser403(await api.get("/api/projects/default_project/members"));
+ await expectSingleUser403(
+ await api.post("/api/projects/default_project/members", { userId: "eve" }),
+ );
+ await expectSingleUser403(
+ await t.app.request("/api/projects/default_project/members/eve", {
+ method: "DELETE",
+ headers: { cookie: admin.cookie },
+ }),
+ );
+ } finally {
+ await t.cleanup();
+ }
+ });
+
+ it("leaves both surfaces working on a normal multi-user server", async () => {
+ const t = await createTestApp();
+ try {
+ const admin = await loginAdmin(t.app);
+ const api = apiClient(t.app, admin.cookie);
+ const users = await api.get("/api/admin/users");
+ expect(users.status).toBe(200);
+ const members = await api.get("/api/projects/default_project/members");
+ expect(members.status).toBe(200);
+ } finally {
+ await t.cleanup();
+ }
+ });
+});
+
describe("desktop-session password change", () => {
async function desktopCookie(t: Awaited<ReturnType<typeof desktopApp>>): Promise<string> {
const res = await t.app.request(`/api/auth/desktop-login?token=${TOKEN}`);
diff --git a/packages/web/src/components/layout/app-layout.tsx b/packages/web/src/components/layout/app-layout.tsx
index b2b22a89..6cfb0bc7 100644
--- a/packages/web/src/components/layout/app-layout.tsx
+++ b/packages/web/src/components/layout/app-layout.tsx
@@ -12,6 +12,7 @@ import { useVersionInfo } from "../../lib/use-version-info";
import { useAuth } from "../../state/auth";
import { useProject } from "../../state/project";
import { useSessions } from "../../state/sessions";
+import { useCompletionNotifications } from "../../state/use-completion-notifications";
import { Drawer } from "../ui/drawer";
import { GlyphIcon } from "../ui/glyph-icon";
import { NAV_ICONS } from "../ui/icons";
@@ -167,6 +168,9 @@ function CollapsedRail({ onExpand }: { onExpand: () => void }) {
export function AppLayout() {
const { user, desktopMode } = useAuth();
+ // Desktop shell only (gated inside): system notification when a task finishes while
+ // the window is unfocused.
+ useCompletionNotifications();
const [drawerOpen, setDrawerOpen] = useState(false);
const [changePasswordOpen, setChangePasswordOpen] = useState(false);
// Desktop sidebar collapse (persisted): collapsed state leaves a narrow rail to expand from.
diff --git a/packages/web/src/components/layout/project-dialogs.tsx b/packages/web/src/components/layout/project-dialogs.tsx
index 9aa2340f..bb512b9d 100644
--- a/packages/web/src/components/layout/project-dialogs.tsx
+++ b/packages/web/src/components/layout/project-dialogs.tsx
@@ -172,7 +172,7 @@ export function CreateProjectDialog({
* deletion (owner); members see the name and member list read-only.
*/
export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
- const { user } = useAuth();
+ const { user, desktopMode } = useAuth();
const { currentProject, setCurrentProjectId, projects, reloadProjects } = useProject();
const [members, setMembers] = useState<MemberInfo[] | null>(null);
const [newMemberId, setNewMemberId] = useState("");
@@ -196,14 +196,18 @@ export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClos
setConfirmDelete(false);
setName(savedName);
setNameError(undefined);
- api
- .listMembers(projectId)
- .then((res) => setMembers(res.members))
- .catch((e: unknown) => setLoadError(apiErrorText(e)));
+ // Desktop mode is single-user: the member section is hidden below and the server
+ // rejects the member routes (desktop_single_user), so nothing is fetched.
+ if (!desktopMode) {
+ api
+ .listMembers(projectId)
+ .then((res) => setMembers(res.members))
+ .catch((e: unknown) => setLoadError(apiErrorText(e)));
+ }
// savedName is read at open time only: retyping in the field must not be clobbered by a
// list refresh, and reopening the dialog re-seeds it.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [open, projectId]);
+ }, [open, projectId, desktopMode]);
if (!currentProject || !projectId) return null;
@@ -306,76 +310,85 @@ export function ProjectSettingsDialog({ open, onClose }: { open: boolean; onClos
<p className="mt-1 font-mono text-xs text-gray-400">{projectId}</p>
</div>
- <div>
- <p className="mb-2 text-xs font-medium text-gray-500">{S.project.members}</p>
- {loadError ? (
- <p className="text-xs text-red-600 dark:text-red-400">{loadError}</p>
- ) : members === null ? (
- <p className="text-xs text-gray-400">{S.common.loading}</p>
- ) : (
- // Member permission table: username / role / actions; cells never wrap.
- // Last row (owner only) = add member: small username input + add button (new members are always the member role).
- <div className="overflow-x-auto rounded-md border border-gray-200 dark:border-gray-800">
- <table className="w-full text-xs">
- <thead>
- <tr className="border-b border-gray-100 bg-gray-50 text-left text-gray-500 dark:border-gray-800 dark:bg-gray-900/60 dark:text-gray-400">
- <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
- {S.common.username}
- </th>
- <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">{S.common.role}</th>
- <th className="w-20 whitespace-nowrap px-2.5 py-1.5 text-right font-medium">
- {S.common.actions}
- </th>
- </tr>
- </thead>
- <tbody className="divide-y divide-gray-100 dark:divide-gray-800/60">
- {members.map((m) => (
- <tr key={m.userId}>
- <td className="whitespace-nowrap px-2.5 py-1.5">{m.userId}</td>
- <td className="whitespace-nowrap px-2.5 py-1.5">
- <Badge tone="gray">{m.role}</Badge>
- </td>
- <td className="whitespace-nowrap px-2.5 py-1 text-right">
- {isOwner && m.role !== "owner" && m.userId !== user?.userId && (
- <Button size="sm" variant="ghost" onClick={() => void doRemove(m.userId)}>
- {S.project.removeMember}
- </Button>
- )}
- </td>
- </tr>
- ))}
- {isOwner && (
- <tr>
- <td className="px-2.5 py-1.5">
- <Input
- placeholder={S.common.username}
- size="sm"
- value={newMemberId}
- onChange={(e) => setNewMemberId(e.target.value)}
- onKeyDown={(e) => {
- if (e.key === "Enter") void addMember();
- }}
- />
- </td>
- <td className="whitespace-nowrap px-2.5 py-1.5">
- <Badge tone="gray">member</Badge>
- </td>
- <td className="whitespace-nowrap px-2.5 py-1 text-right">
- <Button
- size="sm"
- disabled={!newMemberId.trim()}
- onClick={() => void addMember()}
- >
- {S.project.addMember}
- </Button>
- </td>
+ {/* Member management does not exist in the single-user desktop app. */}
+ {!desktopMode && (
+ <div>
+ <p className="mb-2 text-xs font-medium text-gray-500">{S.project.members}</p>
+ {loadError ? (
+ <p className="text-xs text-red-600 dark:text-red-400">{loadError}</p>
+ ) : members === null ? (
+ <p className="text-xs text-gray-400">{S.common.loading}</p>
+ ) : (
+ // Member permission table: username / role / actions; cells never wrap.
+ // Last row (owner only) = add member: small username input + add button (new members are always the member role).
+ <div className="overflow-x-auto rounded-md border border-gray-200 dark:border-gray-800">
+ <table className="w-full text-xs">
+ <thead>
+ <tr className="border-b border-gray-100 bg-gray-50 text-left text-gray-500 dark:border-gray-800 dark:bg-gray-900/60 dark:text-gray-400">
+ <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
+ {S.common.username}
+ </th>
+ <th className="whitespace-nowrap px-2.5 py-1.5 font-medium">
+ {S.common.role}
+ </th>
+ <th className="w-20 whitespace-nowrap px-2.5 py-1.5 text-right font-medium">
+ {S.common.actions}
+ </th>
</tr>
- )}
- </tbody>
- </table>
- </div>
- )}
- </div>
+ </thead>
+ <tbody className="divide-y divide-gray-100 dark:divide-gray-800/60">
+ {members.map((m) => (
+ <tr key={m.userId}>
+ <td className="whitespace-nowrap px-2.5 py-1.5">{m.userId}</td>
+ <td className="whitespace-nowrap px-2.5 py-1.5">
+ <Badge tone="gray">{m.role}</Badge>
+ </td>
+ <td className="whitespace-nowrap px-2.5 py-1 text-right">
+ {isOwner && m.role !== "owner" && m.userId !== user?.userId && (
+ <Button
+ size="sm"
+ variant="ghost"
+ onClick={() => void doRemove(m.userId)}
+ >
+ {S.project.removeMember}
+ </Button>
+ )}
+ </td>
+ </tr>
+ ))}
+ {isOwner && (
+ <tr>
+ <td className="px-2.5 py-1.5">
+ <Input
+ placeholder={S.common.username}
+ size="sm"
+ value={newMemberId}
+ onChange={(e) => setNewMemberId(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") void addMember();
+ }}
+ />
+ </td>
+ <td className="whitespace-nowrap px-2.5 py-1.5">
+ <Badge tone="gray">member</Badge>
+ </td>
+ <td className="whitespace-nowrap px-2.5 py-1 text-right">
+ <Button
+ size="sm"
+ disabled={!newMemberId.trim()}
+ onClick={() => void addMember()}
+ >
+ {S.project.addMember}
+ </Button>
+ </td>
+ </tr>
+ )}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </div>
+ )}
<ChatDefaultsSection projectId={projectId} isOwner={isOwner} />
diff --git a/packages/web/src/components/layout/sidebar.tsx b/packages/web/src/components/layout/sidebar.tsx
index 557e2cc5..e714f7fc 100644
--- a/packages/web/src/components/layout/sidebar.tsx
+++ b/packages/web/src/components/layout/sidebar.tsx
@@ -1119,8 +1119,10 @@ export function Sidebar({
)}
</button>
)}
- {/* User management is visible only to admins (the page route also has its own guard as a fallback). */}
- {user?.isAdmin && (
+ {/* User management is visible only to admins (the page route also has its own
+ guard as a fallback), and never in desktop mode: the desktop app is
+ single-user and the server rejects the routes (desktop_single_user). */}
+ {user?.isAdmin && !desktopMode && (
<button
type="button"
className={menuItemClass}
diff --git a/packages/web/src/features/admin/admin-users-page.tsx b/packages/web/src/features/admin/admin-users-page.tsx
index 5e1a1d13..2a291e06 100644
--- a/packages/web/src/features/admin/admin-users-page.tsx
+++ b/packages/web/src/features/admin/admin-users-page.tsx
@@ -23,7 +23,7 @@ import { Modal } from "../../components/ui/modal";
export function AdminUsersPage() {
useDocumentTitle(S.admin.users);
- const { user } = useAuth();
+ const { user, desktopMode } = useAuth();
const [users, setUsers] = useState<UserInfo[] | null>(null);
const [listError, setListError] = useState<string | null>(null);
const [createOpen, setCreateOpen] = useState(false);
@@ -40,11 +40,13 @@ export function AdminUsersPage() {
}, []);
useEffect(() => {
- if (user?.isAdmin) void reload();
- }, [user?.isAdmin, reload]);
+ if (user?.isAdmin && !desktopMode) void reload();
+ }, [user?.isAdmin, desktopMode, reload]);
- // Route guard fallback: non-admins are redirected back to the chat page (the sidebar has no entry point anyway).
- if (user && !user.isAdmin) return <Navigate to="/chat" replace />;
+ // Route guard fallback: non-admins are redirected back to the chat page (the sidebar has
+ // no entry point anyway); same for desktop mode, where the app is single-user and the
+ // server rejects the admin-user routes (desktop_single_user).
+ if (user && (!user.isAdmin || desktopMode)) return <Navigate to="/chat" replace />;
return (
<div className="h-full overflow-y-auto p-4 md:p-6">
diff --git a/packages/web/src/lib/completion-notify.ts b/packages/web/src/lib/completion-notify.ts
new file mode 100644
index 00000000..e6a7a765
--- /dev/null
+++ b/packages/web/src/lib/completion-notify.ts
@@ -0,0 +1,75 @@
+/**
+ * Task-completion detection over the tracked Session list (pure logic, node-testable —
+ * the desktop notification hook in state/use-completion-notifications.ts drives it).
+ *
+ * A Session is "active" while running or compacting; a completion is the transition of
+ * a KNOWN active Session to idle. First observations never fire — a freshly loaded list
+ * only states where sessions already are, it doesn't witness a finish. Because the
+ * transition flips the stored state, each run fires at most once (the per-session+run
+ * dedupe); on top of that, a short per-session cooldown swallows the flap where a stale
+ * list snapshot racing the live SSE flip briefly resurrects "running" and would
+ * otherwise double-notify the same finish.
+ */
+import type { SessionStatus } from "@prismshadow/penguin-server/api";
+
+export interface ObservedSession {
+ sessionId: string;
+ status: SessionStatus;
+}
+
+/** Whether a status counts as an in-flight run. */
+function isActive(status: SessionStatus): boolean {
+ return status === "running" || status === "compacting";
+}
+
+/** Minimum spacing between two completion firings of the same Session (see header). */
+export const COMPLETION_COOLDOWN_MS = 10_000;
+
+export interface CompletionTracker {
+ /**
+ * Feed the current Session list; returns the sessionIds whose run just completed.
+ * `now` is injectable for tests (defaults to Date.now()).
+ */
+ observe(list: readonly ObservedSession[], now?: number): string[];
+}
+
+export function createCompletionTracker(
+ cooldownMs: number = COMPLETION_COOLDOWN_MS,
+): CompletionTracker {
+ interface Entry {
+ active: boolean;
+ lastFiredAt: number | null;
+ }
+ const entries = new Map<string, Entry>();
+ return {
+ observe(list, now = Date.now()) {
+ const completed: string[] = [];
+ const seen = new Set<string>();
+ for (const s of list) {
+ // Defensive: the list is deduplicated upstream, but only the first occurrence
+ // of an id may drive the state machine.
+ if (seen.has(s.sessionId)) continue;
+ seen.add(s.sessionId);
+ const active = isActive(s.status);
+ const prev = entries.get(s.sessionId);
+ if (prev === undefined) {
+ entries.set(s.sessionId, { active, lastFiredAt: null });
+ continue;
+ }
+ if (prev.active && !active) {
+ if (prev.lastFiredAt === null || now - prev.lastFiredAt >= cooldownMs) {
+ completed.push(s.sessionId);
+ prev.lastFiredAt = now;
+ }
+ }
+ prev.active = active;
+ }
+ // Prune vanished sessions (deleted / Project switch): reappearing later counts as
+ // a fresh first observation, which never fires.
+ for (const id of [...entries.keys()]) {
+ if (!seen.has(id)) entries.delete(id);
+ }
+ return completed;
+ },
+ };
+}
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 82ea40f9..df2d9a17 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -92,6 +92,13 @@ export const en: Strings = {
adminOnly: "Only an administrator can run the update from here.",
},
+ /** Desktop task-completion notifications (window unfocused; desktop-shell sessions only). */
+ notify: {
+ taskCompleteTitle: "Task completed",
+ /** `session` is the Session title (defaultSessionTitle when unnamed). */
+ taskCompleteBody: (session: string): string => `"${session}" has finished — click to view`,
+ },
+
common: {
save: "Save",
cancel: "Cancel",
@@ -1143,6 +1150,7 @@ Scenarios:
password_mismatch: "The current password is incorrect.",
invalid_password: "Password must be at least 8 characters.",
admin_required: "Only an admin can perform this operation.",
+ desktop_single_user: "The desktop app is single-user; user management is unavailable.",
not_found: "This resource does not exist, or you do not have access.",
agent_not_found: "This agent no longer exists.",
unknown_agent: "That agent does not exist in this Project.",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 88c9f3ce..4e50adfb 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -92,6 +92,13 @@ export const zh = {
adminOnly: "只有管理员可以在这里执行更新。",
},
+ /** Desktop task-completion notifications (window unfocused; desktop-shell sessions only). */
+ notify: {
+ taskCompleteTitle: "任务完成",
+ /** `session` is the Session title (defaultSessionTitle when unnamed). */
+ taskCompleteBody: (session: string): string => `「${session}」已完成,点击查看`,
+ },
+
common: {
save: "保存",
cancel: "取消",
@@ -1117,6 +1124,7 @@ Benchmark:
password_mismatch: "当前密码不正确。",
invalid_password: "密码至少 8 位。",
admin_required: "仅管理员可执行此操作。",
+ desktop_single_user: "桌面应用为单用户模式,用户管理不可用。",
not_found: "资源不存在,或你没有访问权限。",
agent_not_found: "该 Agent 已不存在。",
unknown_agent: "该 Agent 不存在于本 Project。",
diff --git a/packages/web/src/state/use-completion-notifications.ts b/packages/web/src/state/use-completion-notifications.ts
new file mode 100644
index 00000000..04e073fe
--- /dev/null
+++ b/packages/web/src/state/use-completion-notifications.ts
@@ -0,0 +1,68 @@
+/**
+ * Desktop task-completion notifications, renderer-side only (standard Web Notification
+ * API — no preload, no private IPC, per design § "桌面端原型 · 进程模型").
+ *
+ * Watches the tracked Session list for active→idle transitions (lib/completion-notify)
+ * and, when the window is hidden or unfocused, shows a system notification with the
+ * Session's title; clicking focuses the window and opens that Session. Gated to
+ * sessionVia === "desktop": only the desktop shell's own window qualifies — there the
+ * Notification permission is granted by default, so plain browsers (which would face a
+ * permission prompt) are never touched.
+ */
+import { useEffect, useRef } from "react";
+import { useNavigate } from "react-router";
+import { S } from "../lib/strings";
+import { createCompletionTracker } from "../lib/completion-notify";
+import { useAuth } from "./auth";
+import { useProject } from "./project";
+import { useSessions } from "./sessions";
+
+export function useCompletionNotifications(): void {
+ const { sessionVia } = useAuth();
+ const { sessions } = useSessions();
+ const { setCurrentAgentId } = useProject();
+ const navigate = useNavigate();
+
+ const trackerRef = useRef(createCompletionTracker());
+ // Click handlers fire long after the effect ran: read the latest helpers via refs.
+ const navigateRef = useRef(navigate);
+ navigateRef.current = navigate;
+ const setCurrentAgentIdRef = useRef(setCurrentAgentId);
+ setCurrentAgentIdRef.current = setCurrentAgentId;
+
+ const enabled = sessionVia === "desktop";
+ useEffect(() => {
+ if (!enabled) return;
+ // The tracker must see every snapshot (also while focused): completions the user
+ // watched happen are consumed silently instead of surfacing on a later blur.
+ const completed = trackerRef.current.observe(
+ sessions.map((s) => ({ sessionId: s.sessionId, status: s.status })),
+ );
+ if (completed.length === 0) return;
+ if (!document.hidden && document.hasFocus()) return;
+ if (typeof Notification === "undefined" || Notification.permission !== "granted") return;
+ for (const sessionId of completed) {
+ const session = sessions.find((s) => s.sessionId === sessionId);
+ const title = session?.title ?? S.chat.defaultSessionTitle;
+ const agentId = session?.agentId ?? null;
+ try {
+ const notification = new Notification(S.notify.taskCompleteTitle, {
+ body: S.notify.taskCompleteBody(title),
+ // One notification per Session: a newer completion replaces the stale one.
+ tag: `penguin-task-${sessionId}`,
+ icon: "/penguin-logo.svg",
+ });
+ notification.onclick = () => {
+ notification.close();
+ window.focus();
+ // Mirrors the sidebar's openSession: the current agent follows the Session.
+ if (agentId !== null) setCurrentAgentIdRef.current(agentId);
+ navigateRef.current(`/chat/${sessionId}`);
+ };
+ } catch {
+ // Notification construction is best-effort; a platform refusing it must not
+ // break the app.
+ }
+ }
+ }, [enabled, sessions]);
+}
diff --git a/packages/web/test/completion-notify.test.ts b/packages/web/test/completion-notify.test.ts
new file mode 100644
index 00000000..7169bfe7
--- /dev/null
+++ b/packages/web/test/completion-notify.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { createCompletionTracker } from "../src/lib/completion-notify";
+import type { ObservedSession } from "../src/lib/completion-notify";
+import type { SessionStatus } from "@prismshadow/penguin-server/api";
+
+const row = (sessionId: string, status: SessionStatus): ObservedSession => ({
+ sessionId,
+ status,
+});
+
+describe("createCompletionTracker", () => {
+ it("fires when a known running session goes idle", () => {
+ const t = createCompletionTracker();
+ expect(t.observe([row("a", "running")], 0)).toEqual([]);
+ expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+ });
+
+ it("treats compacting as still active and fires only on the flip to idle", () => {
+ const t = createCompletionTracker();
+ t.observe([row("a", "running")], 0);
+ expect(t.observe([row("a", "compacting")], 100)).toEqual([]);
+ expect(t.observe([row("a", "idle")], 200)).toEqual(["a"]);
+ });
+
+ it("never fires on first observation, even an idle one after a running list load", () => {
+ const t = createCompletionTracker();
+ // A list that loads with idle sessions has witnessed nothing.
+ expect(t.observe([row("a", "idle"), row("b", "idle")], 0)).toEqual([]);
+ expect(t.observe([row("a", "idle"), row("b", "idle")], 100)).toEqual([]);
+ });
+
+ it("dedupes per run: repeated idle observations fire once", () => {
+ const t = createCompletionTracker();
+ t.observe([row("a", "running")], 0);
+ expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+ expect(t.observe([row("a", "idle")], 2000)).toEqual([]);
+ expect(t.observe([row("a", "idle")], 60_000)).toEqual([]);
+ });
+
+ it("fires again for a genuinely new run after the cooldown", () => {
+ const t = createCompletionTracker(10_000);
+ t.observe([row("a", "running")], 0);
+ expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+ t.observe([row("a", "running")], 20_000);
+ expect(t.observe([row("a", "idle")], 30_000)).toEqual(["a"]);
+ });
+
+ it("suppresses a stale-snapshot flap within the cooldown window", () => {
+ const t = createCompletionTracker(10_000);
+ t.observe([row("a", "running")], 0);
+ expect(t.observe([row("a", "idle")], 1000)).toEqual(["a"]);
+ // A stale reload snapshot resurrects "running", then the fresh state lands again:
+ // the same finish must not notify twice.
+ t.observe([row("a", "running")], 1100);
+ expect(t.observe([row("a", "idle")], 1200)).toEqual([]);
+ });
+
+ it("tracks sessions independently and reports multiple completions", () => {
+ const t = createCompletionTracker();
+ t.observe([row("a", "running"), row("b", "running"), row("c", "idle")], 0);
+ expect(t.observe([row("a", "idle"), row("b", "idle"), row("c", "idle")], 1000)).toEqual([
+ "a",
+ "b",
+ ]);
+ });
+
+ it("prunes sessions that leave the list: reappearing is a fresh first observation", () => {
+ const t = createCompletionTracker();
+ t.observe([row("a", "running")], 0);
+ // Project switch empties the list; the session's state is dropped.
+ t.observe([], 100);
+ expect(t.observe([row("a", "idle")], 200)).toEqual([]);
+ });
+
+ it("ignores duplicate ids within one observation (first occurrence wins)", () => {
+ const t = createCompletionTracker();
+ t.observe([row("a", "running")], 0);
+ expect(t.observe([row("a", "idle"), row("a", "running")], 1000)).toEqual(["a"]);
+ // The duplicate "running" row did not restart the run.
+ expect(t.observe([row("a", "idle")], 60_000)).toEqual([]);
+ });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 42574135..d351a4ff 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -114,6 +114,9 @@ importers:
packages/desktop:
dependencies:
+ '@prismshadow/penguin-cli':
+ specifier: workspace:*
+ version: file:packages/cli([email protected])
'@prismshadow/penguin-core':
specifier: workspace:*
version: file:packages/core([email protected])([email protected])