@howaboua/pi-pet 0.1.1

package/src/desktop/attention.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+type AttentionMode = "normal" | "quiet";
+export type PetSize = "small" | "medium" | "large";
+
+export interface AttentionPreferences {
+  schemaVersion: 1;
+  mode: AttentionMode;
+  petSize: PetSize;
+  snoozedUntil: string | null;
+}
+
+const ATTENTION_KEYS = new Set(["schemaVersion", "mode", "petSize", "snoozedUntil"]);
+const MAX_ATTENTION_BYTES = 4_096;
+const MAX_SNOOZE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function defaultAttentionPreferences(): AttentionPreferences {
+  return { schemaVersion: 1, mode: "normal", petSize: "medium", snoozedUntil: null };
+}
+
+function parsePetSize(value: unknown): PetSize {
+  const petSize = value ?? "medium";
+  if (petSize !== "small" && petSize !== "medium" && petSize !== "large") {
+    throw new Error("Desktop petSize must be small, medium, or large.");
+  }
+  return petSize;
+}
+
+export function parseAttentionPreferences(value: unknown): AttentionPreferences {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Desktop attention preferences must be an object.");
+  }
+  const input = value as Record<string, unknown>;
+  const unknown = Object.keys(input).find((key) => !ATTENTION_KEYS.has(key));
+  if (unknown) throw new Error(`Desktop attention preferences have unknown field: ${unknown}.`);
+  if (input["schemaVersion"] !== 1) throw new Error("Unsupported desktop attention schemaVersion.");
+  if (input["mode"] !== "normal" && input["mode"] !== "quiet") {
+    throw new Error("Desktop attention mode must be normal or quiet.");
+  }
+  const petSize = parsePetSize(input["petSize"]);
+  if (input["snoozedUntil"] !== null && typeof input["snoozedUntil"] !== "string") {
+    throw new Error("Desktop snoozedUntil must be an ISO timestamp or null.");
+  }
+  if (typeof input["snoozedUntil"] === "string") {
+    const snoozedUntil = Date.parse(input["snoozedUntil"]);
+    if (!Number.isFinite(snoozedUntil)) throw new Error("Desktop snoozedUntil must be a valid ISO timestamp.");
+    if (snoozedUntil - Date.now() > MAX_SNOOZE_MS) {
+      throw new Error("Desktop snoozedUntil cannot be more than seven days away.");
+    }
+  }
+  return { schemaVersion: 1, mode: input["mode"], petSize, snoozedUntil: input["snoozedUntil"] };
+}
+
+export async function loadAttentionPreferences(path: string): Promise<AttentionPreferences> {
+  try {
+    const raw = await readFile(path, "utf8");
+    if (Buffer.byteLength(raw) > MAX_ATTENTION_BYTES) throw new Error("Attention preferences are too large.");
+    return parseAttentionPreferences(JSON.parse(raw) as unknown);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return defaultAttentionPreferences();
+    throw new Error(`Invalid desktop attention preferences at ${path}: ${(error as Error).message}`);
+  }
+}
+
+export async function saveAttentionPreferences(path: string, value: AttentionPreferences): Promise<void> {
+  const preferences = parseAttentionPreferences(value);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(preferences)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw error;
+  }
+}
+
+export function snoozeUntilTomorrow(now = new Date()): Date {
+  return new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 8);
+}
+
+export function remainingSnoozeMs(preferences: AttentionPreferences, now = Date.now()): number {
+  if (!preferences.snoozedUntil) return 0;
+  return Math.max(0, Date.parse(preferences.snoozedUntil) - now);
+}

package/src/desktop/bridge.ts

@@ -0,0 +1,31 @@
+export const DESKTOP_CURSOR_CHANNEL = "pi-pet:cursor-position";
+
+export interface DesktopCursorPosition {
+  x: number;
+  y: number;
+}
+
+export interface PiPetDesktopBridge {
+  onCursorPosition(listener: (position: DesktopCursorPosition | null) => void): () => void;
+}
+
+export function parseDesktopCursorPosition(value: unknown): DesktopCursorPosition | null {
+  if (value === null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Cursor position must be an object.");
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some((key) => key !== "x" && key !== "y")) {
+    throw new Error("Cursor position has an unknown field.");
+  }
+  if (
+    typeof input["x"] !== "number" ||
+    !Number.isFinite(input["x"]) ||
+    Math.abs(input["x"]) > 100_000 ||
+    typeof input["y"] !== "number" ||
+    !Number.isFinite(input["y"]) ||
+    Math.abs(input["y"]) > 100_000
+  ) {
+    throw new Error("Cursor position is invalid.");
+  }
+  return { x: input["x"], y: input["y"] };
+}

package/src/desktop/config.ts

@@ -0,0 +1,145 @@
+import { constants as fsConstants } from "node:fs";
+import { type FileHandle, open } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface DesktopConfig {
+  schemaVersion: 1;
+  gippityUrl: string;
+}
+
+const CONFIG_KEYS = new Set(["schemaVersion", "gippityUrl"]);
+const MAX_CONFIG_BYTES = 16_384;
+const DEVICE_NAME_PATTERN = /^(?!-)[a-zA-Z0-9_.@:-]{1,255}$/;
+const RESERVED_DEVICE_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+export const MAX_PET_DEVICES = 8;
+
+export function parseDeviceName(value: unknown): string {
+  if (typeof value !== "string") throw new Error("Pi Pet device name must be a string.");
+  const name = value.trim();
+  if (!DEVICE_NAME_PATTERN.test(name) || RESERVED_DEVICE_NAMES.has(name)) {
+    throw new Error("Pi Pet device name must be local or one SSH host or alias without command options.");
+  }
+  return name;
+}
+
+export function parseSshTarget(value: unknown): string {
+  const target = parseDeviceName(value);
+  if (target === "local") throw new Error("The reserved local device does not use SSH.");
+  return target;
+}
+
+function desktopConfigPath(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  home = homedir(),
+): string {
+  if (env["PI_PET_DESKTOP_CONFIG"]) return resolve(env["PI_PET_DESKTOP_CONFIG"]);
+  if (platform === "win32") {
+    return join(env["APPDATA"] || join(home, "AppData", "Roaming"), "PiPetDesktop", "config.json");
+  }
+  if (platform === "darwin") {
+    return join(home, "Library", "Application Support", "Pi Pet Desktop", "config.json");
+  }
+  return join(env["XDG_CONFIG_HOME"] || join(home, ".config"), "pi-pet-desktop", "config.json");
+}
+
+export function desktopStateDirectory(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  home = homedir(),
+): string {
+  if (platform === "win32") {
+    return join(env["LOCALAPPDATA"] || join(home, "AppData", "Local"), "PiPetDesktop", "state");
+  }
+  if (platform === "darwin") {
+    return join(home, "Library", "Application Support", "Pi Pet Desktop", "state");
+  }
+  return join(env["XDG_STATE_HOME"] || join(home, ".local", "state"), "pi-pet-desktop");
+}
+
+function parseGippityUrl(value: unknown): string {
+  if (typeof value !== "string" || value.length > 2_048) {
+    throw new Error("gippityUrl must be a bounded HTTPS URL.");
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("gippityUrl must be a valid HTTPS URL.");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new Error("gippityUrl must be an HTTPS origin without credentials, query, or fragment.");
+  }
+  if (url.pathname !== "/") throw new Error("gippityUrl must not contain a path.");
+  return url.origin;
+}
+
+export function parseDesktopConfig(value: unknown): DesktopConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Pi Pet desktop config must be an object.");
+  }
+  const input = value as Record<string, unknown>;
+  const unknown = Object.keys(input).find((key) => !CONFIG_KEYS.has(key));
+  if (unknown) throw new Error(`Pi Pet desktop config has unknown field: ${unknown}.`);
+  if (input["schemaVersion"] !== 1) throw new Error("Unsupported Pi Pet desktop config schemaVersion.");
+  return { schemaVersion: 1, gippityUrl: parseGippityUrl(input["gippityUrl"]) };
+}
+
+function configFromEnvironment(env: NodeJS.ProcessEnv): DesktopConfig | undefined {
+  const gippityUrl = env["PI_PET_GIPPITY_URL"];
+  return gippityUrl ? parseDesktopConfig({ schemaVersion: 1, gippityUrl }) : undefined;
+}
+
+async function openDesktopConfig(path: string): Promise<FileHandle> {
+  try {
+    return await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Pi Pet desktop is not configured: ${path}`);
+    }
+    if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+      throw new Error(`Pi Pet desktop config must not be a symbolic link: ${path}`);
+    }
+    throw error;
+  }
+}
+
+async function validateConfigFile(handle: FileHandle, path: string): Promise<void> {
+  const info = await handle.stat();
+  if (!info.isFile() || info.size > MAX_CONFIG_BYTES) {
+    throw new Error(`Pi Pet desktop config must be a regular file no larger than ${MAX_CONFIG_BYTES} bytes: ${path}`);
+  }
+  if (process.platform === "win32") return;
+  if ((info.mode & 0o077) !== 0) throw new Error(`Pi Pet desktop config must have mode 0600: ${path}`);
+  if (process.getuid && info.uid !== process.getuid()) {
+    throw new Error(`Pi Pet desktop config must be owned by the current user: ${path}`);
+  }
+}
+
+export async function loadDesktopConfig(
+  path = desktopConfigPath(),
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<DesktopConfig> {
+  const environmentConfig = configFromEnvironment(env);
+  if (environmentConfig) return environmentConfig;
+  const handle = await openDesktopConfig(path);
+  try {
+    await validateConfigFile(handle, path);
+    const raw = await handle.readFile("utf8");
+    return parseDesktopConfig(JSON.parse(raw) as unknown);
+  } catch (error) {
+    throw new Error(`Invalid Pi Pet desktop config at ${path}: ${(error as Error).message}`);
+  } finally {
+    await handle.close();
+  }
+}
+
+export function desktopDisplayUrl(config: DesktopConfig, attention: "normal" | "quiet" = "normal"): string {
+  const url = new URL(config.gippityUrl);
+  url.pathname = "/_gippity/apps/pi-pet/";
+  url.searchParams.set("shell", "desktop");
+  if (attention === "quiet") url.searchParams.set("attention", "quiet");
+  return url.toString();
+}

package/src/desktop/cursor-provider.ts

@@ -0,0 +1,150 @@
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import { type DesktopCursorPosition, parseDesktopCursorPosition } from "./bridge.ts";
+
+const HYPRLAND_SIGNATURE_PATTERN = /^[a-zA-Z0-9._-]{1,200}$/;
+const MAX_CURSOR_RESPONSE_BYTES = 1_024;
+const MAX_CLIENTS_RESPONSE_BYTES = 1024 * 1024;
+const CURSOR_TIMEOUT_MS = 200;
+
+export interface DesktopWindowBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export function hyprlandCursorSocket(env: NodeJS.ProcessEnv): string | undefined {
+  const runtime = env["XDG_RUNTIME_DIR"];
+  const signature = env["HYPRLAND_INSTANCE_SIGNATURE"];
+  if (!(runtime && signature && runtime.startsWith("/") && HYPRLAND_SIGNATURE_PATTERN.test(signature)))
+    return undefined;
+  return join(runtime, "hypr", signature, ".socket.sock");
+}
+
+export function parseHyprlandCursorResponse(value: string): DesktopCursorPosition {
+  const position = parseDesktopCursorPosition(JSON.parse(value) as unknown);
+  if (!position) throw new Error("Hyprland returned an empty cursor position.");
+  return position;
+}
+
+function parseCoordinatePair(value: unknown, label: string): [number, number] {
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    typeof value[0] !== "number" ||
+    !Number.isFinite(value[0]) ||
+    typeof value[1] !== "number" ||
+    !Number.isFinite(value[1])
+  ) {
+    throw new Error(`Hyprland ${label} is invalid.`);
+  }
+  return [value[0], value[1]];
+}
+
+export function parseHyprlandClientBounds(value: string, pid: number): DesktopWindowBounds {
+  const clients = JSON.parse(value) as unknown;
+  if (!Array.isArray(clients)) throw new Error("Hyprland clients response must be an array.");
+  const client = clients.find(
+    (candidate) =>
+      candidate !== null &&
+      typeof candidate === "object" &&
+      !Array.isArray(candidate) &&
+      (candidate as Record<string, unknown>)["pid"] === pid,
+  );
+  if (!client) throw new Error(`Hyprland did not report the Pi Pet window for process ${pid}.`);
+  const input = client as Record<string, unknown>;
+  const [x, y] = parseCoordinatePair(input["at"], "window position");
+  const [width, height] = parseCoordinatePair(input["size"], "window size");
+  if (width < 1 || height < 1 || width > 4_096 || height > 4_096) throw new Error("Hyprland window size is invalid.");
+  return { x, y, width, height };
+}
+
+async function readHyprlandCommand<T>(
+  path: string,
+  command: string,
+  maximumBytes: number,
+  responseComplete: (response: string) => boolean,
+  parse: (response: string) => T,
+): Promise<T> {
+  return await new Promise((resolve, reject) => {
+    const socket = createConnection(path);
+    let response = "";
+    let completed = false;
+    const fail = (error: Error): void => {
+      if (completed) return;
+      completed = true;
+      socket.destroy();
+      reject(error);
+    };
+    socket.setEncoding("utf8");
+    socket.setTimeout(CURSOR_TIMEOUT_MS);
+    socket.on("connect", () => socket.end(command));
+    socket.on("data", (chunk: string) => {
+      response += chunk;
+      if (Buffer.byteLength(response) > maximumBytes) {
+        fail(new Error("Hyprland returned an oversized IPC response."));
+        return;
+      }
+      if (!responseComplete(response.trimEnd())) return;
+      try {
+        const result = parse(response);
+        completed = true;
+        socket.destroy();
+        resolve(result);
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error("Hyprland returned an invalid IPC response."));
+      }
+    });
+    socket.on("timeout", () => fail(new Error("Hyprland cursor IPC timed out.")));
+    socket.on("error", (error) => fail(error));
+    socket.on("end", () => {
+      if (completed) return;
+      try {
+        const result = parse(response);
+        completed = true;
+        resolve(result);
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error("Hyprland returned an invalid IPC response."));
+      }
+    });
+  });
+}
+
+export async function readHyprlandCursor(path: string): Promise<DesktopCursorPosition> {
+  return await readHyprlandCommand(
+    path,
+    "j/cursorpos",
+    MAX_CURSOR_RESPONSE_BYTES,
+    (response) => response.endsWith("}"),
+    parseHyprlandCursorResponse,
+  );
+}
+
+async function readHyprlandClientBounds(path: string, pid: number): Promise<DesktopWindowBounds> {
+  return await readHyprlandCommand(
+    path,
+    "j/clients",
+    MAX_CLIENTS_RESPONSE_BYTES,
+    (response) => response.endsWith("]"),
+    (response) => parseHyprlandClientBounds(response, pid),
+  );
+}
+
+export function createCursorReader(
+  env: NodeJS.ProcessEnv,
+  fallback: () => DesktopCursorPosition,
+): () => Promise<DesktopCursorPosition> {
+  const socket = hyprlandCursorSocket(env);
+  if (socket) return async () => await readHyprlandCursor(socket);
+  return async () => fallback();
+}
+
+export function createHyprlandBoundsReader(
+  env: NodeJS.ProcessEnv,
+  pid: number,
+): (() => Promise<DesktopWindowBounds>) | undefined {
+  const socket = hyprlandCursorSocket(env);
+  if (!socket) return undefined;
+  return async () => await readHyprlandClientBounds(socket, pid);
+}