@howaboua/pi-pet 0.1.1

package/extensions/desktop-command.ts

@@ -0,0 +1,249 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  CONFIG_DIR_NAME,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { parseDesktopConfig, parseDeviceName, parseSshTarget } from "../src/desktop/config.ts";
+import { type RepositoryPetConfig, readRepositoryPetConfig, writeRepositoryPetConfig } from "../src/pet-storage.ts";
+import {
+  type DeviceRegistryConfig,
+  type PetDevice,
+  readDeviceRegistry,
+  writeDeviceRegistry,
+} from "./desktop-config.ts";
+import { DesktopDeviceFleet } from "./desktop-launcher.ts";
+import { GippityUnavailableError, isMissingGippity } from "./gippity.ts";
+
+const ACTIONS = ["attach", "detach", "restart", "status"] as const;
+const ARGUMENT_SEPARATOR = /\s+/;
+const MAX_AUTHORING_REQUEST_BYTES = 8 * 1024;
+const AUTHORING_GUIDE = fileURLToPath(new URL("../authoring/PET-GUIDE.md", import.meta.url));
+
+type PetCommand =
+  | { action: "attach"; device: string; gippityUrl?: string | undefined }
+  | { action: "detach"; device: string }
+  | { action: "restart" }
+  | { action: "status" }
+  | { action: "author"; request: string };
+
+function usage(): string {
+  return "Usage: /pet attach <local|device> [gippity-url] | detach <device> | restart | status";
+}
+
+function projectConfigPath(cwd: string): string {
+  return join(cwd, CONFIG_DIR_NAME, "pi-pet.json");
+}
+
+function selectedDeviceNames(registry: DeviceRegistryConfig, project: RepositoryPetConfig | undefined): string[] {
+  const names = project?.devices ?? registry.defaultDevices;
+  const missing = names.find((name) => !Object.hasOwn(registry.devices, name));
+  if (missing) throw new Error(`Pi Pet device is selected but not registered: ${missing}.`);
+  return names;
+}
+
+function formatStatus(names: string[], fleet: DesktopDeviceFleet): string {
+  const running = new Set(fleet.deviceNames());
+  if (names.length === 0) return "Pi Pet is active with no devices attached for this folder.";
+  return [...names]
+    .sort()
+    .map((name) => `${name}: ${running.has(name) ? "running" : "stopped"}`)
+    .join("\n");
+}
+
+function showDevicePhase(context: ExtensionContext | undefined, phases: Map<string, string>): void {
+  const current = [...phases.entries()].at(-1);
+  context?.ui.setStatus("pi-pet-device", current ? `Pi Pet ${current[0]}: ${current[1]}` : undefined);
+}
+
+function authoringCommand(request: string): PetCommand {
+  if (Buffer.byteLength(request) > MAX_AUTHORING_REQUEST_BYTES) {
+    throw new Error(`Pi Pet authoring request exceeds ${MAX_AUTHORING_REQUEST_BYTES} bytes.`);
+  }
+  return { action: "author", request };
+}
+
+function parsePetCommand(rawArgs: string): PetCommand {
+  const request = rawArgs.trim();
+  const tokens = request ? request.split(ARGUMENT_SEPARATOR) : ["status"];
+  const [rawAction, rawDevice, rawUrl, ...extra] = tokens;
+  const action = rawAction?.toLowerCase();
+  if (!(action && ACTIONS.includes(action as (typeof ACTIONS)[number]))) {
+    return authoringCommand(request);
+  }
+  if (extra.length > 0) throw new Error(usage());
+  const validAction = action as (typeof ACTIONS)[number];
+  if (validAction === "status" || validAction === "restart") {
+    if (rawDevice || rawUrl) throw new Error(usage());
+    return { action: validAction };
+  }
+  if (!rawDevice) throw new Error(usage());
+  const device = parseDeviceName(rawDevice);
+  if (validAction === "detach") {
+    if (rawUrl) throw new Error(usage());
+    return { action: validAction, device };
+  }
+  const gippityUrl = rawUrl ? parseDesktopConfig({ schemaVersion: 1, gippityUrl: rawUrl }).gippityUrl : undefined;
+  return { action: "attach", device, ...(gippityUrl ? { gippityUrl } : {}) };
+}
+
+function petAuthoringPrompt(request: string): string {
+  return `Read and follow the Pi Pet guide at ${JSON.stringify(AUTHORING_GUIDE)} for this request:\n\n${request}`;
+}
+
+function deviceForAttach(name: string, existing: PetDevice | undefined, gippityUrl?: string): PetDevice {
+  if (name === "local") {
+    if (existing?.kind === "ssh") throw new Error("The reserved local device cannot be an SSH device.");
+    const url = gippityUrl ?? existing?.gippityUrl;
+    return { kind: "local", ...(url ? { gippityUrl: url } : {}) };
+  }
+  if (existing) {
+    const url = gippityUrl ?? existing.gippityUrl;
+    return { ...existing, ...(url ? { gippityUrl: url } : {}) };
+  }
+  return {
+    kind: "ssh",
+    target: parseSshTarget(name),
+    ...(gippityUrl ? { gippityUrl } : {}),
+  };
+}
+
+async function startDevices(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  fleet: DesktopDeviceFleet,
+  registry: DeviceRegistryConfig,
+  names: string[],
+): Promise<string> {
+  let status: { running: boolean; urls: string[] };
+  try {
+    const { ensureGippityLan } = await import("@howaboua/pi-gippity-control/lan-service");
+    status = await ensureGippityLan(pi, ctx);
+  } catch (error) {
+    if (isMissingGippity(error)) throw new GippityUnavailableError();
+    throw error;
+  }
+  const automaticUrl = parseDesktopConfig({ schemaVersion: 1, gippityUrl: status.urls[0] }).gippityUrl;
+  await Promise.all(names.map((name) => fleet.start(name, registry.devices[name] as PetDevice, automaticUrl)));
+  return automaticUrl;
+}
+
+async function executeCommand(
+  pi: ExtensionAPI,
+  command: PetCommand,
+  fleet: DesktopDeviceFleet,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  if (command.action === "author") {
+    await access(AUTHORING_GUIDE);
+    await ctx.waitForIdle();
+    pi.sendUserMessage(petAuthoringPrompt(command.request));
+    return;
+  }
+  const path = projectConfigPath(ctx.cwd);
+  const registry = await readDeviceRegistry();
+  const project = readRepositoryPetConfig(path);
+  const selected = selectedDeviceNames(registry, project);
+  if (command.action === "status") {
+    ctx.ui.notify(formatStatus(selected, fleet), "info");
+    return;
+  }
+  if (command.action === "restart") {
+    await fleet.stopAll();
+    if (selected.length > 0) await startDevices(pi, ctx, fleet, registry, selected);
+    ctx.ui.notify("Pi Pet devices for this folder restarted.", "info");
+    return;
+  }
+  if (command.action === "detach") {
+    if (!selected.includes(command.device)) {
+      throw new Error(`Pi Pet device ${command.device} is not attached to this folder.`);
+    }
+    const devices = selected.filter((name) => name !== command.device);
+    await writeRepositoryPetConfig({ ...project, schemaVersion: 1, devices }, path);
+    await fleet.stop(command.device);
+    ctx.ui.notify(`Pi Pet device ${command.device} detached from this folder.`, "info");
+    return;
+  }
+  const device = deviceForAttach(command.device, registry.devices[command.device], command.gippityUrl);
+  const nextRegistry: DeviceRegistryConfig = {
+    ...registry,
+    devices: { ...registry.devices, [command.device]: device },
+  };
+  const automaticUrl = await startDevices(pi, ctx, fleet, nextRegistry, [command.device]);
+  try {
+    await writeDeviceRegistry(nextRegistry);
+    await writeRepositoryPetConfig(
+      {
+        ...project,
+        schemaVersion: 1,
+        devices: [...new Set([...selected, command.device])],
+      },
+      path,
+    );
+  } catch (error) {
+    await fleet.stop(command.device);
+    throw error;
+  }
+  ctx.ui.notify(
+    `Pi Pet device ${command.device} attached to this folder through ${command.gippityUrl ?? automaticUrl}.`,
+    "info",
+  );
+}
+
+export function registerPetDevices(pi: ExtensionAPI): void {
+  let context: ExtensionContext | undefined;
+  const phases = new Map<string, string>();
+  const fleet = new DesktopDeviceFleet({
+    onPhase(device, phase) {
+      phases.delete(device);
+      phases.set(device, phase);
+      showDevicePhase(context, phases);
+    },
+    onExit(device, error) {
+      phases.delete(device);
+      showDevicePhase(context, phases);
+      if (error && context?.hasUI) context.ui.notify(`Pi Pet device ${device}: ${error.message}`, "warning");
+    },
+  });
+
+  pi.registerCommand("pet", {
+    description: "Control devices or start Pi Pet authoring",
+    getArgumentCompletions: (prefix) =>
+      ACTIONS.filter((action) => action.startsWith(prefix.trim().toLowerCase())).map((value) => ({
+        label: value,
+        value,
+      })),
+    handler: async (rawArgs, ctx) => {
+      try {
+        await executeCommand(pi, parsePetCommand(rawArgs), fleet, ctx);
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    context = ctx;
+    try {
+      const registry = await readDeviceRegistry();
+      const project = readRepositoryPetConfig(projectConfigPath(ctx.cwd));
+      const selected = selectedDeviceNames(registry, project);
+      if (selected.length > 0) await startDevices(pi, ctx, fleet, registry, selected);
+    } catch (error) {
+      if (!(error instanceof GippityUnavailableError)) {
+        ctx.ui.notify(
+          `Pi Pet devices could not start: ${error instanceof Error ? error.message : String(error)}`,
+          "warning",
+        );
+      }
+    }
+  });
+  pi.on("session_shutdown", async () => {
+    context = undefined;
+    phases.clear();
+    await fleet.stopAll();
+  });
+}

package/extensions/desktop-config.ts

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { type FileHandle, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { MAX_PET_DEVICES, parseDesktopConfig, parseDeviceName, parseSshTarget } from "../src/desktop/config.ts";
+
+export type PetDevice =
+  | { kind: "local"; gippityUrl?: string | undefined }
+  | { kind: "ssh"; target: string; gippityUrl?: string | undefined };
+
+export interface DeviceRegistryConfig {
+  schemaVersion: 1;
+  devices: Record<string, PetDevice>;
+  defaultDevices: string[];
+}
+
+const ROOT_KEYS = new Set(["schemaVersion", "devices", "defaultDevices"]);
+const DEVICE_KEYS = new Set(["kind", "target", "gippityUrl"]);
+const LEGACY_ROOT_KEYS = new Set(["schemaVersion", "displays"]);
+const LEGACY_DISPLAY_KEYS = new Set(["gippityUrl"]);
+const MAX_CONFIG_BYTES = 32 * 1024;
+
+function agentDirectory(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  return env["PI_CODING_AGENT_DIR"]?.trim() || join(home, ".pi", "agent");
+}
+
+function deviceRegistryPath(env: NodeJS.ProcessEnv = process.env, home = homedir()): string {
+  return join(agentDirectory(env, home), "pi-pet.json");
+}
+
+function parseOptionalUrl(value: unknown): string | undefined {
+  return value === undefined ? undefined : parseDesktopConfig({ schemaVersion: 1, gippityUrl: value }).gippityUrl;
+}
+
+function parseDevice(name: string, value: unknown): PetDevice {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Pi Pet device ${name} must be an object.`);
+  }
+  const input = value as Record<string, unknown>;
+  const unknown = Object.keys(input).find((key) => !DEVICE_KEYS.has(key));
+  if (unknown) throw new Error(`Pi Pet device ${name} has unknown field: ${unknown}.`);
+  const gippityUrl = parseOptionalUrl(input["gippityUrl"]);
+  if (input["kind"] === "local") {
+    if (name !== "local" || input["target"] !== undefined)
+      throw new Error('The local Pi Pet device must be named "local" and cannot have an SSH target.');
+    return { kind: "local", ...(gippityUrl ? { gippityUrl } : {}) };
+  }
+  if (input["kind"] !== "ssh") throw new Error(`Pi Pet device ${name} kind must be local or ssh.`);
+  const target = parseSshTarget(input["target"]);
+  return { kind: "ssh", target, ...(gippityUrl ? { gippityUrl } : {}) };
+}
+
+function parseDeviceNames(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.length > MAX_PET_DEVICES) {
+    throw new Error(`${label} must be an array of at most ${MAX_PET_DEVICES} device names.`);
+  }
+  const names = value.map(parseDeviceName);
+  if (new Set(names).size !== names.length) throw new Error(`${label} must contain unique device names.`);
+  return names;
+}
+
+function parseLegacyRegistry(input: Record<string, unknown>): DeviceRegistryConfig {
+  const unknownRoot = Object.keys(input).find((key) => !LEGACY_ROOT_KEYS.has(key));
+  if (unknownRoot) throw new Error(`Pi Pet device registry has unknown field: ${unknownRoot}.`);
+  const rawDisplays = input["displays"];
+  if (!rawDisplays || typeof rawDisplays !== "object" || Array.isArray(rawDisplays)) {
+    throw new Error("Legacy Pi Pet displays must be an object.");
+  }
+  const entries = Object.entries(rawDisplays);
+  if (entries.length > MAX_PET_DEVICES) throw new Error(`Pi Pet supports at most ${MAX_PET_DEVICES} devices.`);
+  const devices: DeviceRegistryConfig["devices"] = {};
+  for (const [rawName, rawDisplay] of entries) {
+    const name = parseDeviceName(rawName);
+    if (name === "local") throw new Error("Legacy SSH display local conflicts with the reserved local device.");
+    if (!rawDisplay || typeof rawDisplay !== "object" || Array.isArray(rawDisplay)) {
+      throw new Error(`Legacy Pi Pet display ${name} must be an object.`);
+    }
+    const display = rawDisplay as Record<string, unknown>;
+    const unknown = Object.keys(display).find((key) => !LEGACY_DISPLAY_KEYS.has(key));
+    if (unknown) throw new Error(`Legacy Pi Pet display ${name} has unknown field: ${unknown}.`);
+    const gippityUrl = parseOptionalUrl(display["gippityUrl"]);
+    devices[name] = { kind: "ssh", target: parseSshTarget(name), ...(gippityUrl ? { gippityUrl } : {}) };
+  }
+  return { schemaVersion: 1, devices, defaultDevices: Object.keys(devices) };
+}
+
+export function parseDeviceRegistry(value: unknown): DeviceRegistryConfig {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Pi Pet device registry must be an object.");
+  }
+  const input = value as Record<string, unknown>;
+  if (input["schemaVersion"] !== 1) throw new Error("Unsupported Pi Pet device registry schemaVersion.");
+  if (input["displays"] !== undefined) return parseLegacyRegistry(input);
+  const unknownRoot = Object.keys(input).find((key) => !ROOT_KEYS.has(key));
+  if (unknownRoot) throw new Error(`Pi Pet device registry has unknown field: ${unknownRoot}.`);
+  const rawDevices = input["devices"];
+  if (!rawDevices || typeof rawDevices !== "object" || Array.isArray(rawDevices)) {
+    throw new Error("Pi Pet devices must be an object.");
+  }
+  const entries = Object.entries(rawDevices);
+  if (entries.length > MAX_PET_DEVICES) throw new Error(`Pi Pet supports at most ${MAX_PET_DEVICES} devices.`);
+  const devices: DeviceRegistryConfig["devices"] = {};
+  for (const [rawName, rawDevice] of entries) {
+    const name = parseDeviceName(rawName);
+    devices[name] = parseDevice(name, rawDevice);
+  }
+  const defaultDevices = parseDeviceNames(input["defaultDevices"] ?? [], "Pi Pet defaultDevices");
+  const missing = defaultDevices.find((name) => !Object.hasOwn(devices, name));
+  if (missing) throw new Error(`Pi Pet default device is not registered: ${missing}.`);
+  return { schemaVersion: 1, devices, defaultDevices };
+}
+
+export async function readDeviceRegistry(path = deviceRegistryPath()): Promise<DeviceRegistryConfig> {
+  let handle: FileHandle;
+  try {
+    handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return { schemaVersion: 1, devices: {}, defaultDevices: [] };
+    if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+      throw new Error(`Pi Pet device registry must not be a symbolic link: ${path}`);
+    }
+    throw error;
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > MAX_CONFIG_BYTES) {
+      throw new Error(`Pi Pet device registry must be a bounded regular file: ${path}`);
+    }
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+      throw new Error(`Pi Pet device registry must have mode 0600: ${path}`);
+    }
+    return parseDeviceRegistry(JSON.parse(await handle.readFile("utf8")) as unknown);
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function writeDeviceRegistry(config: DeviceRegistryConfig, path = deviceRegistryPath()): Promise<void> {
+  const normalized = parseDeviceRegistry(config);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await rm(temporary, { force: true });
+    await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}