pi-webdesk 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Pi Webdesk
+
+An opinionated web UI for Pi.
+
+Webdesk is a local-first browser workspace built specifically for [Pi](https://pi.dev/). It gives a solo developer a calm, worktree-first place to run several coding tasks, inspect changes, validate them, and explicitly decide what gets committed or merged.
+
+Pi remains the agent runtime and the source of truth for sessions, models, authentication, settings, skills, extensions, prompts, themes, and packages.
+
+## Status
+
+The core vertical slice is runnable locally, including through Pi's package manager: an authenticated localhost browser can register repositories, create isolated task worktrees, run supervised Pi runtimes with policy approvals, stream and steer prompts, and reconnect with exact event replay or a Pi-reconstructed canonical snapshot. Tasks provide live bounded Git review, explicit validation, snapshot commit approval, local merge approval, and non-destructive archive/restore. Durable runtime ownership lets a restarted daemon terminate verified orphan process groups before accepting traffic; ambiguous ownership blocks only the affected task, and interrupted prompts are never resumed automatically. The current UI includes formatted conversations, expandable tool and skill-file activity with canonical reload recovery, proposed edit previews, compact session branches, persistent task selection, read-only Pi configuration/resource discovery, and schema-bound Webdesk appearance preferences.
+
+- [Product brief](docs/product-brief.md)
+- [Architecture](docs/architecture.md)
+- [Roadmap](ROADMAP.md)
+- [Runtime boundary decision](docs/decisions/0001-pi-runtime-boundary.md)
+
+## Install in Pi
+
+Install the public preview through Pi's package manager:
+
+Requires Node.js **22.19+**, npm, Git **2.38+**, and an existing Pi setup. macOS is the primary platform; Linux uses `xdg-open` when available.
+
+```sh
+pi install npm:pi-webdesk
+```
+
+Restart Pi, or run `/reload` in an existing interactive session. Then:
+
+```text
+/webdesk          Start Webdesk in the background and open its browser workspace
+/webdesk status   Show whether the daemon is running
+/webdesk stop     Gracefully stop the daemon and its active task runtimes
+```
+
+The npm package includes the compiled browser app and daemon. Pi loads only the launcher extension; loading or reloading it never starts a daemon. `/webdesk` opens a fresh one-time login link to `http://127.0.0.1:4517` (valid for 15 minutes). If the browser cannot open automatically, copy the link from Pi. Repeating `/webdesk` reuses the running daemon and replaces any unused login link.
+
+The daemon keeps running when Pi or the browser closes. `/webdesk stop` preserves task worktrees, metadata, and Pi sessions; it stops active execution without replaying interrupted prompts. Use it before updating or removing the package, then restart Pi or `/reload` to load the updated launcher. Removing the Pi package does not remove `~/.pita` or Pi's files. Webdesk opens its workspace; your current terminal conversation is not moved automatically. Existing sessions can be continued through Webdesk's session workflow.
+
+After stopping Webdesk, update it from your terminal:
+
+```sh
+pi update npm:pi-webdesk
+```
+
+Then restart Pi or `/reload`, and run `/webdesk` again. Package updates are managed by Pi; Webdesk's resource UI is read-only.
+
+You can also install the current GitHub source with `pi install https://github.com/luka-zivkovic/pi-webdesk`. This runs `npm install --omit=dev` and builds the package automatically. If switching from a Git installation to npm, stop Webdesk and run `pi remove https://github.com/luka-zivkovic/pi-webdesk` before the npm install to avoid duplicate launcher extensions. Your worktrees and sessions are preserved.
+
+Configuration is inherited from the environment that starts Pi:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PITA_PORT` | `4517` | Loopback HTTP port |
+| `PITA_STATE_DIR` | `~/.pita` | Private state directory, worktrees, and background log (`daemon.log`) |
+| `PITA_PI_EXECUTABLE` | Package's tested Pi runtime | Explicit Pi executable override |
+
+Webdesk keeps its tested Pi runtime dependency alongside the application and uses Pi's existing configuration, authentication, resources, and session formats. Set Pi's own `PI_CODING_AGENT_DIR` to use a different Pi configuration directory. Binding to other interfaces is not supported.
+
+To install a local development checkout:
+
+```sh
+pnpm install
+pnpm build
+pi install "$PWD"
+```
+
+The distribution also includes a `pi-webdesk` executable for npm installations. From a built checkout, run `node dist/apps/daemon/src/cli.js --no-browser` to serve the UI in the foreground; Ctrl+C stops it. `open`, `status`, and `stop` are also available as CLI commands. Pi package installation does not add this executable to your shell's global PATH.
+
+### Existing Pita installations
+
+Webdesk was previously named Pita. `/pita` remains an alias for `/webdesk`. The existing `~/.pita` data directory and `PITA_*` environment variables retain their names, so tasks, worktrees, sessions, preferences, and launch configuration continue to work without moving data. Existing browser storage and internal protocol identifiers are also preserved.
+
+## Development and verification
+
+```sh
+pnpm install
+pnpm --filter @pita/daemon start   # terminal 1
+pnpm --filter @pita/web dev       # terminal 2
+```
+
+The development daemon prints a login link for the Vite origin, `http://localhost:5173`. `PITA_ALLOWED_ORIGIN` configures that development origin; `PITA_DAEMON_PORT` configures Vite's proxy when using a different daemon port.
+
+```sh
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm test:package
+```
+
+The package check performs a fresh npm source install, packs and installs production dependencies into an isolated directory, registers the package with an isolated Pi configuration, verifies the launcher and real Pi policy handshake, and checks browser authentication and daemon restart. It makes no model calls. `npm pack` rebuilds the distribution. Only the root `pi-webdesk` package is published; internal workspace packages stay private.
+
+For a release, run the checks above plus `pnpm test:process`, then pack and test the exact archive before publishing it:
+
+```sh
+npm pack
+WEBDESK_PACKAGE_TARBALL="$PWD/pi-webdesk-0.1.0.tgz" pnpm test:package
+npm publish ./pi-webdesk-0.1.0.tgz --access public --ignore-scripts
+```
+
+Use the version from `package.json` in the archive name. `WEBDESK_PACKAGE_TARBALL` makes the package check install that archive while still verifying a fresh Git-source build.
+
+## Locked technology direction
+
+- Browser UI: React, TypeScript, Vite
+- Styling and components: Tailwind CSS v4, shadcn/ui on Base UI, Lucide icons
+- Local service: Node.js/TypeScript daemon bound to localhost
+- Runtime: one supervised Pi runtime per active task
+- Repository model: one Git worktree per task
+
+The first implementation milestone is a thin vertical slice: open a repository, create a task worktree, talk to Pi with streamed events, survive a browser reconnect, and inspect the resulting diff.

package/dist/apps/daemon/src/appearance-preferences.js

@@ -0,0 +1,218 @@
+// apps/daemon/src/appearance-preferences.ts
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import {
+  PITA_PREFERENCES_SCHEMA_VERSION,
+  PROTOCOL_VERSION,
+  pitaAppearancePreferencesSchema,
+  pitaPreferencesSnapshotSchema
+} from "../../../packages/protocol/src/index.js";
+var PITA_PREFERENCES_FILE = "preferences-v1.json";
+var STALE_TEMP_FILE = /^\.preferences-v1\.json\.\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i;
+var MAX_REPOSITORY_PREFERENCES = 1e3;
+var DEFAULT_PITA_APPEARANCE = {
+  palette: "warm-sand",
+  mode: "system",
+  density: "comfortable",
+  sidebarWidth: 264,
+  sidebarVisible: true,
+  contextPanel: "right"
+};
+var preferencesDocumentSchema = z.object({
+  schemaVersion: z.literal(PITA_PREFERENCES_SCHEMA_VERSION),
+  global: pitaAppearancePreferencesSchema,
+  repositories: z.record(z.uuid(), pitaAppearancePreferencesSchema)
+}).strict().refine(
+  (document) => Object.keys(document.repositories).length <= MAX_REPOSITORY_PREFERENCES,
+  "Too many repository appearance overrides."
+);
+var PitaPreferencesOperationError = class extends Error {
+  name = "PitaPreferencesOperationError";
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+};
+function initialDocument() {
+  return {
+    schemaVersion: PITA_PREFERENCES_SCHEMA_VERSION,
+    global: { ...DEFAULT_PITA_APPEARANCE },
+    repositories: {}
+  };
+}
+function errorCode(error) {
+  return error !== null && typeof error === "object" && "code" in error ? String(error.code) : void 0;
+}
+function createPitaPreferencesService(options) {
+  const stateDir = path.resolve(options.stateDir);
+  const filePath = path.join(stateDir, PITA_PREFERENCES_FILE);
+  let document = null;
+  let initialization = null;
+  let mutationQueue = Promise.resolve();
+  let invalidDocument = false;
+  async function persist(next) {
+    await mkdir(stateDir, { recursive: true, mode: 448 });
+    const tempPath = path.join(
+      stateDir,
+      `.${PITA_PREFERENCES_FILE}.${process.pid}.${randomUUID()}.tmp`
+    );
+    let handle = null;
+    try {
+      handle = await open(tempPath, "wx", 384);
+      await handle.writeFile(`${JSON.stringify(next, null, 2)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      await rename(tempPath, filePath);
+      let directory = null;
+      try {
+        directory = await open(stateDir, "r");
+        await directory.sync();
+      } catch {
+      } finally {
+        await directory?.close().catch(() => void 0);
+      }
+    } catch (error) {
+      await handle?.close().catch(() => void 0);
+      await unlink(tempPath).catch(() => void 0);
+      throw new PitaPreferencesOperationError(
+        "preferences-unavailable",
+        `Could not persist Webdesk appearance preferences: ${errorCode(error) ?? "write failed"}.`,
+        503
+      );
+    }
+  }
+  async function load() {
+    await mkdir(stateDir, { recursive: true, mode: 448 });
+    for (const name of await readdir(stateDir)) {
+      if (STALE_TEMP_FILE.test(name)) {
+        await unlink(path.join(stateDir, name)).catch(() => void 0);
+      }
+    }
+    let raw;
+    try {
+      raw = await readFile(filePath, "utf8");
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") {
+        const initial = initialDocument();
+        await persist(initial);
+        document = initial;
+        return;
+      }
+      throw new PitaPreferencesOperationError(
+        "preferences-unavailable",
+        "Webdesk appearance preferences could not be read. The existing file was left untouched.",
+        503
+      );
+    }
+    try {
+      document = preferencesDocumentSchema.parse(JSON.parse(raw));
+    } catch {
+      invalidDocument = true;
+      throw new PitaPreferencesOperationError(
+        "preferences-unavailable",
+        "Webdesk appearance preferences are invalid. The existing file was preserved for recovery.",
+        503
+      );
+    }
+  }
+  async function read() {
+    initialization ??= load();
+    await initialization;
+    return preferencesDocumentSchema.parse(document);
+  }
+  function toSnapshot(current, repositoryId) {
+    const repository = repositoryId === null ? null : current.repositories[repositoryId] ?? null;
+    return pitaPreferencesSnapshotSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "pita-preferences-snapshot",
+      schemaVersion: PITA_PREFERENCES_SCHEMA_VERSION,
+      repositoryId,
+      global: current.global,
+      repository,
+      effective: repository ?? current.global
+    });
+  }
+  async function update(request) {
+    const operation = mutationQueue.then(async () => {
+      let current;
+      try {
+        current = await read();
+      } catch (error) {
+        if (!invalidDocument || request.scope !== "global" || request.action !== "reset") {
+          throw error;
+        }
+        const recoveryPath = path.join(
+          stateDir,
+          `${PITA_PREFERENCES_FILE}.invalid.${Date.now()}.${randomUUID()}.json`
+        );
+        try {
+          await copyFile(filePath, recoveryPath, 0);
+        } catch (copyError) {
+          throw new PitaPreferencesOperationError(
+            "preferences-unavailable",
+            `Could not preserve the invalid appearance file for recovery: ${errorCode(copyError) ?? "copy failed"}.`,
+            503
+          );
+        }
+        const recovered = initialDocument();
+        await persist(recovered);
+        document = recovered;
+        invalidDocument = false;
+        initialization = Promise.resolve();
+        return toSnapshot(recovered, request.repositoryId);
+      }
+      const repositories = { ...current.repositories };
+      let global = current.global;
+      if (request.scope === "global") {
+        global = request.action === "reset" ? { ...DEFAULT_PITA_APPEARANCE } : pitaAppearancePreferencesSchema.parse(request.preferences);
+      } else {
+        const repositoryId = request.repositoryId;
+        if (repositoryId === null) {
+          throw new PitaPreferencesOperationError(
+            "invalid-request",
+            "Choose a repository before changing repository appearance.",
+            400
+          );
+        }
+        if (request.action === "reset") {
+          delete repositories[repositoryId];
+        } else {
+          repositories[repositoryId] = pitaAppearancePreferencesSchema.parse(request.preferences);
+        }
+      }
+      const next = preferencesDocumentSchema.parse({
+        schemaVersion: PITA_PREFERENCES_SCHEMA_VERSION,
+        global,
+        repositories
+      });
+      await persist(next);
+      document = next;
+      return toSnapshot(next, request.repositoryId);
+    });
+    mutationQueue = operation.then(
+      () => void 0,
+      () => void 0
+    );
+    return operation;
+  }
+  return {
+    filePath,
+    async snapshot(repositoryId) {
+      return toSnapshot(await read(), repositoryId);
+    },
+    update
+  };
+}
+export {
+  DEFAULT_PITA_APPEARANCE,
+  PITA_PREFERENCES_FILE,
+  PitaPreferencesOperationError,
+  createPitaPreferencesService
+};

package/dist/apps/daemon/src/auth.js

@@ -0,0 +1,88 @@
+// apps/daemon/src/auth.ts
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+var SESSION_COOKIE_NAME = "pita_session";
+var TOKEN_VERSION = "v1";
+var MAC_CONTEXT = `pita-session-${TOKEN_VERSION}.`;
+var sessionClaimsSchema = z.object({
+  sid: z.string().min(1),
+  iat: z.number().int().min(0),
+  exp: z.number().int().min(0)
+});
+function generateBootstrapToken() {
+  return randomBytes(32).toString("hex");
+}
+function tokensMatch(expected, provided) {
+  const a = createHash("sha256").update(expected, "utf8").digest();
+  const b = createHash("sha256").update(provided, "utf8").digest();
+  return timingSafeEqual(a, b);
+}
+function sign(secret, payload) {
+  return createHmac("sha256", secret).update(MAC_CONTEXT + payload, "utf8").digest("base64url");
+}
+function createSessionToken(secret, init) {
+  const expiresAt = init.nowMs + init.ttlMs;
+  const payload = Buffer.from(
+    JSON.stringify({
+      sid: randomBytes(16).toString("hex"),
+      iat: init.nowMs,
+      exp: expiresAt
+    }),
+    "utf8"
+  ).toString("base64url");
+  return {
+    token: `${TOKEN_VERSION}.${payload}.${sign(secret, payload)}`,
+    expiresAt
+  };
+}
+function verifySessionToken(secret, token, nowMs) {
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[0] !== TOKEN_VERSION) {
+    return null;
+  }
+  const [, payload, mac] = parts;
+  if (payload === void 0 || mac === void 0) {
+    return null;
+  }
+  const expected = sign(secret, payload);
+  const macBuffer = Buffer.from(mac, "utf8");
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  if (macBuffer.length !== expectedBuffer.length || !timingSafeEqual(macBuffer, expectedBuffer)) {
+    return null;
+  }
+  let claims;
+  try {
+    claims = sessionClaimsSchema.parse(
+      JSON.parse(Buffer.from(payload, "base64url").toString("utf8"))
+    );
+  } catch {
+    return null;
+  }
+  if (claims.exp <= nowMs) {
+    return null;
+  }
+  return { sid: claims.sid, expiresAt: claims.exp };
+}
+function readCookie(header, name) {
+  if (header === void 0) {
+    return null;
+  }
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) {
+      continue;
+    }
+    if (part.slice(0, separator).trim() === name) {
+      return part.slice(separator + 1).trim();
+    }
+  }
+  return null;
+}
+export {
+  SESSION_COOKIE_NAME,
+  createSessionToken,
+  generateBootstrapToken,
+  readCookie,
+  tokensMatch,
+  verifySessionToken
+};

package/dist/apps/daemon/src/bin.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+// apps/daemon/src/bin.ts
+import os from "node:os";
+import path from "node:path";
+import { accessSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createDaemonServer, DaemonConfigError } from "./server.js";
+import { DaemonStateError } from "./secret.js";
+import { DaemonStateLockError } from "./state-lock.js";
+import { RuntimeProcessRecoveryError } from "./runtime-process.js";
+import { WorkspaceStateError } from "./workspace-store.js";
+import { PitaPreferencesOperationError } from "./appearance-preferences.js";
+import { listenLauncherControl } from "./launcher-control.js";
+import { openBrowser } from "./launcher.js";
+var DEFAULT_PORT = 4517;
+var DEFAULT_ORIGIN = "http://localhost:5173";
+function readPort(raw) {
+  if (raw === void 0 || raw === "") {
+    return DEFAULT_PORT;
+  }
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new DaemonConfigError(`PITA_PORT must be an integer in 1-65535, got ${raw}`);
+  }
+  return port;
+}
+function readOrigin(raw, fallback = DEFAULT_ORIGIN) {
+  if (raw === void 0 || raw === "") {
+    return fallback;
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new DaemonConfigError(`PITA_ALLOWED_ORIGIN must be a URL origin, got ${raw}`);
+  }
+  if (url.origin !== raw) {
+    throw new DaemonConfigError(
+      `PITA_ALLOWED_ORIGIN must be exactly an origin (no path), e.g. ${url.origin}`
+    );
+  }
+  return url.origin;
+}
+async function runDaemon(options = {}) {
+  const stateDir = path.resolve(
+    process.env.PITA_STATE_DIR ?? path.join(os.homedir(), ".pita")
+  );
+  const port = readPort(process.env.PITA_PORT);
+  const allowedOrigin = readOrigin(process.env.PITA_ALLOWED_ORIGIN, options.packaged ? `http://127.0.0.1:${port}` : DEFAULT_ORIGIN);
+  const webDirectory = options.packaged ? fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../../../dist/web/" : "../../../web/", import.meta.url)) : void 0;
+  if (webDirectory) accessSync(path.join(webDirectory, "index.html"));
+  const server = createDaemonServer({
+    stateDir,
+    allowedOrigin,
+    port,
+    ...webDirectory === void 0 ? {} : { webDirectory }
+  });
+  const bound = await server.listen();
+  const printBootstrapLink = (token) => {
+    process.stderr.write(
+      `open this one-time link in your browser (valid for 15 minutes):
+  ${allowedOrigin}/?pita_bootstrap=${token}
+`
+    );
+  };
+  process.stderr.write(
+    `Webdesk daemon listening on http://${bound.address}:${bound.port} (state: ${stateDir})
+run \`kill -USR2 ${process.pid}\` to print a fresh one-time link
+`
+  );
+  let closing = false;
+  let closeControl;
+  const shutdown = () => {
+    if (closing) {
+      return;
+    }
+    closing = true;
+    void (async () => {
+      try {
+        await closeControl?.();
+      } finally {
+        await server.close();
+      }
+    })().then(
+      () => process.exit(0),
+      () => process.exit(1)
+    );
+  };
+  try {
+    closeControl = await listenLauncherControl(stateDir, (command) => ({
+      version: 1,
+      status: command === "stop" ? "stopping" : "running",
+      origin: allowedOrigin,
+      ...command === "open" ? { token: server.rotateBootstrapToken() } : {}
+    }), shutdown);
+  } catch (error) {
+    await server.close();
+    throw error;
+  }
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  process.on("SIGUSR2", () => {
+    if (!closing) {
+      printBootstrapLink(server.rotateBootstrapToken());
+    }
+  });
+  if (process.env.PITA_BACKGROUND !== "1") {
+    printBootstrapLink(server.bootstrapToken);
+    if (options.open && !await openBrowser(`${allowedOrigin}/?pita_bootstrap=${server.bootstrapToken}`)) {
+      process.stderr.write("Could not open a browser automatically. Use the link above.\n");
+    }
+  }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) runDaemon().catch((error) => {
+  const message = error instanceof DaemonStateError || error instanceof DaemonStateLockError || error instanceof DaemonConfigError || error instanceof RuntimeProcessRecoveryError || error instanceof WorkspaceStateError || error instanceof PitaPreferencesOperationError ? error.message : String(error);
+  process.stderr.write(`Webdesk daemon failed to start: ${message}
+`);
+  process.exit(1);
+});
+export {
+  runDaemon
+};

package/dist/apps/daemon/src/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+// apps/daemon/src/cli.ts
+import { bootstrapUrl, launchPita, launcherStateDir, openBrowser } from "./launcher.js";
+import { requestLauncherControl } from "./launcher-control.js";
+var HELP = `Usage: pi-webdesk [serve|open|status|stop] [--no-browser]
+
+  serve    Run in this terminal (default); Ctrl+C stops the daemon and runtimes
+  open     Start a background daemon or open the running workspace
+  status   Show whether Webdesk is running
+  stop     Gracefully stop the daemon and its task runtimes
+
+Environment: PITA_PORT (4517), PITA_STATE_DIR (~/.pita), PITA_PI_EXECUTABLE
+Webdesk listens only on 127.0.0.1. State and Pi sessions survive stopping.
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const noBrowser = args.includes("--no-browser");
+  const positional = args.filter((arg) => arg !== "--no-browser");
+  const command = positional[0] ?? "serve";
+  if (positional.length > 1 || !["serve", "open", "status", "stop"].includes(command)) throw new Error(HELP);
+  if (command === "serve") {
+    const { runDaemon } = await import("./bin.js");
+    await runDaemon({ packaged: true, open: !noBrowser });
+    return;
+  }
+  if (command === "open") {
+    const reply2 = await launchPita();
+    const url = bootstrapUrl(reply2);
+    process.stdout.write(`Open this one-time link (valid for 15 minutes):
+${url}
+`);
+    if (!noBrowser && !await openBrowser(url)) process.stderr.write("Could not open a browser automatically. Use the link above.\n");
+    return;
+  }
+  const reply = await requestLauncherControl(launcherStateDir(), command);
+  process.stdout.write(reply ? `Webdesk ${reply.status} at ${reply.origin}
+` : "Webdesk is not running.\n");
+}
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});