@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/git-operations.ts

@@ -0,0 +1,200 @@
+/**
+ * Server-side git operations — branch listing, checkout, init, stash.
+ */
+import { execSync } from "node:child_process";
+
+const GIT_TIMEOUT = 15_000;
+
+/** Run a git command, return trimmed stdout. Throws on failure. */
+function run(command: string, cwd: string): string {
+  return execSync(command, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: GIT_TIMEOUT,
+  }).trim();
+}
+
+/** Run a git command, return trimmed stdout or undefined on failure. */
+function tryRun(command: string, cwd: string): string | undefined {
+  try {
+    return run(command, cwd);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Check if cwd is inside a git work tree. */
+export function isGitRepo(cwd: string): boolean {
+  return tryRun("git rev-parse --is-inside-work-tree", cwd) === "true";
+}
+
+/** Get list of dirty files from git status --porcelain. */
+export function getDirtyFiles(cwd: string): string[] {
+  let output: string;
+  try {
+    output = execSync("git status --porcelain", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: GIT_TIMEOUT,
+    });
+  } catch {
+    return [];
+  }
+  return output
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => line.slice(3)); // strip 2 status chars + space
+}
+
+export interface BranchInfo {
+  current: string;
+  detached: boolean;
+  branches: Array<{ name: string; isRemote: boolean; isCurrent: boolean }>;
+}
+
+/** List all local and remote branches sorted by most recent commit. */
+export function listBranches(cwd: string): BranchInfo {
+  // Detect current branch / detached HEAD
+  const headRef = tryRun("git rev-parse --abbrev-ref HEAD", cwd);
+
+  // Empty repo (no commits yet)
+  if (!headRef) {
+    // Try to read the default branch name from HEAD
+    const symbolic = tryRun("git symbolic-ref --short HEAD", cwd);
+    return {
+      current: symbolic ?? "main",
+      detached: false,
+      branches: [],
+    };
+  }
+  const detached = headRef === "HEAD";
+  const current = detached
+    ? run("git rev-parse --short HEAD", cwd)
+    : headRef;
+
+  // List all branches with committer date sorting
+  const format = "%(refname:short)%(HEAD)";
+  const rawLocal = tryRun(
+    `git branch --sort=-committerdate --format="${format}"`,
+    cwd
+  ) ?? "";
+  const rawRemote = tryRun(
+    `git branch -r --sort=-committerdate --format="${format}"`,
+    cwd
+  ) ?? "";
+
+  const localBranches: BranchInfo["branches"] = [];
+  for (const line of rawLocal.split("\n").filter(Boolean)) {
+    const isCurrent = line.includes("*");
+    const name = line.replace("*", "").trim();
+    if (!name) continue;
+    localBranches.push({ name, isRemote: false, isCurrent });
+  }
+
+  // Collect local branch names for dedup
+  const localNames = new Set(localBranches.map((b) => b.name));
+
+  const remoteBranches: BranchInfo["branches"] = [];
+  for (const line of rawRemote.split("\n").filter(Boolean)) {
+    const name = line.replace("*", "").trim();
+    // Skip HEAD pointers like "origin/HEAD"
+    if (name.endsWith("/HEAD")) continue;
+    // Skip remote branches that have a local counterpart
+    const localName = name.replace(/^[^/]+\//, ""); // "origin/foo" → "foo"
+    if (localNames.has(localName)) continue;
+    remoteBranches.push({ name, isRemote: true, isCurrent: false });
+  }
+
+  return {
+    current,
+    detached,
+    branches: [...localBranches, ...remoteBranches],
+  };
+}
+
+export interface CheckoutResult {
+  success: true;
+  stashed?: boolean;
+}
+
+export interface CheckoutDirty {
+  success: false;
+  dirty: true;
+  files: string[];
+}
+
+/** Checkout a branch. Returns dirty info if working tree is dirty and stash=false. */
+export function checkoutBranch(
+  cwd: string,
+  branch: string,
+  stash: boolean
+): CheckoutResult | CheckoutDirty {
+  // Already on this branch?
+  const headRef = tryRun("git rev-parse --abbrev-ref HEAD", cwd);
+  if (headRef === branch) return { success: true };
+
+  const dirtyFiles = getDirtyFiles(cwd);
+
+  if (dirtyFiles.length > 0 && !stash) {
+    return { success: false, dirty: true, files: dirtyFiles };
+  }
+
+  let stashed = false;
+  if (dirtyFiles.length > 0 && stash) {
+    run("git stash push -u -m \"pi-dashboard-auto-stash\"", cwd);
+    stashed = true;
+  }
+
+  // Check if this is a remote branch that needs a local tracking branch
+  const isRemote = branch.includes("/");
+  if (isRemote) {
+    const localName = branch.replace(/^[^/]+\//, "");
+    // Check if local branch exists
+    const localExists = tryRun(`git rev-parse --verify refs/heads/${localName}`, cwd);
+    if (!localExists) {
+      run(`git checkout -b ${localName} ${branch}`, cwd);
+      return { success: true, stashed };
+    }
+    // Local branch exists, just checkout
+    run(`git checkout ${localName}`, cwd);
+    return { success: true, stashed };
+  }
+
+  run(`git checkout ${branch}`, cwd);
+  return { success: true, stashed };
+}
+
+/** Initialize a git repository. Throws if already a git repo. */
+export function gitInit(cwd: string): void {
+  if (isGitRepo(cwd)) {
+    throw new Error("already a git repository");
+  }
+  run("git init", cwd);
+}
+
+export interface StashPopResult {
+  conflicts: boolean;
+}
+
+/** Pop the most recent stash. */
+export function stashPop(cwd: string): StashPopResult {
+  // Check if there are stash entries
+  const stashList = tryRun("git stash list", cwd);
+  if (!stashList) {
+    throw new Error("no stash entries");
+  }
+
+  try {
+    run("git stash pop", cwd);
+    return { conflicts: false };
+  } catch (err: any) {
+    // git stash pop exits non-zero on conflicts but still applies
+    const msg: string = [err.stdout, err.stderr, err.message].filter(Boolean).join("\n");
+    if (msg.includes("CONFLICT") || msg.includes("conflict") || msg.includes("Merge conflict")) {
+      return { conflicts: true };
+    }
+    throw err;
+  }
+}

package/packages/server/src/headless-pid-registry.ts

@@ -0,0 +1,207 @@
+/**
+ * Registry mapping headless child processes to session IDs.
+ * Tracks PID + cwd at spawn time, links to sessionId when the bridge connects.
+ * Persists entries to disk so a restarted server can clean up orphans.
+ */
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { readJsonFile, writeJsonFile } from "./json-store.js";
+import path from "node:path";
+import os from "node:os";
+
+/** Default PID file path */
+const DEFAULT_PID_FILE = path.join(os.homedir(), ".pi", "dashboard", "headless-pids.json");
+
+/** Max age before an orphan is killed (7 days) */
+const MAX_ORPHAN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface HeadlessEntry {
+  pid: number;
+  cwd: string;
+  process: ChildProcess;
+  sessionId?: string;
+  spawnedAt: number;
+}
+
+/** Serialized format for disk persistence */
+interface PersistedEntry {
+  pid: number;
+  cwd: string;
+  spawnedAt: string;
+}
+
+interface PidFileData {
+  entries: PersistedEntry[];
+}
+
+export interface HeadlessPidRegistry {
+  /** Register a newly spawned headless process. */
+  register(pid: number, cwd: string, proc: ChildProcess): void;
+  /** Link a session ID to a tracked PID by matching cwd (FIFO). */
+  linkSession(sessionId: string, cwd: string): boolean;
+  /** Get the PID linked to a session ID. */
+  getPid(sessionId: string): number | undefined;
+  /** Send SIGTERM to the process linked to a session ID. Returns true if killed. */
+  killBySessionId(sessionId: string): boolean;
+  /** Remove a tracked process by PID. */
+  remove(pid: number): void;
+  /** Kill all tracked processes (for server shutdown). */
+  killAll(): void;
+  /** Number of tracked entries (for testing). */
+  size(): number;
+  /** Clean up orphan processes from a previous server instance. */
+  cleanupOrphans(): void;
+}
+
+export interface HeadlessPidRegistryOptions {
+  pidFilePath?: string;
+}
+
+export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions): HeadlessPidRegistry {
+  const entries = new Map<number, HeadlessEntry>();
+  const pidFilePath = options?.pidFilePath ?? DEFAULT_PID_FILE;
+
+  function persist() {
+    const data: PidFileData = {
+      entries: [...entries.values()].map((e) => ({
+        pid: e.pid,
+        cwd: e.cwd,
+        spawnedAt: new Date(e.spawnedAt).toISOString(),
+      })),
+    };
+    try {
+      writeJsonFile(pidFilePath, data);
+    } catch {
+      // Non-fatal — persistence is best-effort
+    }
+  }
+
+  function loadFromDisk(): PersistedEntry[] {
+    const data = readJsonFile<PidFileData>(pidFilePath, { entries: [] });
+    return data.entries ?? [];
+  }
+
+  function isProcessAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    register(pid: number, cwd: string, proc: ChildProcess) {
+      entries.set(pid, { pid, cwd, process: proc, spawnedAt: Date.now() });
+      proc.on("exit", () => {
+        entries.delete(pid);
+        persist();
+      });
+      persist();
+    },
+
+    linkSession(sessionId: string, cwd: string): boolean {
+      for (const entry of entries.values()) {
+        if (entry.cwd === cwd && !entry.sessionId) {
+          entry.sessionId = sessionId;
+          return true;
+        }
+      }
+      return false;
+    },
+
+    getPid(sessionId: string): number | undefined {
+      for (const entry of entries.values()) {
+        if (entry.sessionId === sessionId) {
+          return entry.pid;
+        }
+      }
+      return undefined;
+    },
+
+    killBySessionId(sessionId: string): boolean {
+      for (const entry of entries.values()) {
+        if (entry.sessionId === sessionId) {
+          try {
+            // On Unix, kill the entire process group (negative PID) so the
+            // wrapper shell, sleep, and pi processes are all terminated.
+            // On Windows, process groups aren't supported — kill directly.
+            const signal = "SIGTERM";
+            const pid = process.platform === "win32" ? entry.pid : -entry.pid;
+            process.kill(pid, signal);
+            entries.delete(entry.pid);
+            persist();
+            return true;
+          } catch {
+            entries.delete(entry.pid);
+            persist();
+            return false;
+          }
+        }
+      }
+      return false;
+    },
+
+    remove(pid: number) {
+      entries.delete(pid);
+      persist();
+    },
+
+    killAll() {
+      const useGroup = process.platform !== "win32";
+      for (const [pid] of entries) {
+        try {
+          process.kill(useGroup ? -pid : pid, "SIGTERM");
+        } catch {
+          // Process may have already exited
+        }
+      }
+      entries.clear();
+      // Don't persist here — keep disk entries so cleanupOrphans() can
+      // reclaim surviving processes after a server restart.
+    },
+
+    size() {
+      return entries.size;
+    },
+
+    cleanupOrphans() {
+      const persisted = loadFromDisk();
+      const now = Date.now();
+
+      for (const entry of persisted) {
+        const spawnedAt = new Date(entry.spawnedAt).getTime();
+        const age = now - spawnedAt;
+
+        if (!isProcessAlive(entry.pid)) {
+          // Dead process — skip (will be removed from file on persist)
+          continue;
+        }
+
+        if (age > MAX_ORPHAN_AGE_MS) {
+          // Very old orphan — kill (process group on Unix, direct on Windows)
+          try {
+            const pid = process.platform === "win32" ? entry.pid : -entry.pid;
+            process.kill(pid, "SIGTERM");
+          } catch {
+            // Already dead
+          }
+          continue;
+        }
+
+        // Alive and not too old — reclaim into registry
+        // Create a dummy ChildProcess-like emitter for the entry
+        // EventEmitter imported at top level
+        const dummyProc = new EventEmitter() as ChildProcess;
+        entries.set(entry.pid, {
+          pid: entry.pid,
+          cwd: entry.cwd,
+          process: dummyProc,
+          spawnedAt,
+        });
+      }
+
+      persist();
+    },
+  };
+}

package/packages/server/src/idle-timer.ts

@@ -0,0 +1,61 @@
+/**
+ * Auto-shutdown idle timer with sleep-wake resilience.
+ * Shuts down the server when no pi sessions are connected for the configured idle period.
+ */
+import type { PiGateway } from "./pi-gateway.js";
+import type { ServerConfig } from "./server.js";
+
+export interface IdleTimer {
+  start(): void;
+  cancel(): void;
+  /** Set the stop callback (must be set before starting) */
+  setStopFn(fn: () => Promise<void>): void;
+}
+
+export function createIdleTimer(
+  config: ServerConfig,
+  piGateway: PiGateway,
+): IdleTimer {
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopServer: (() => Promise<void>) | null = null;
+  let lastConnectionTimestamp = 0;
+
+  function start() {
+    if (!config.autoShutdown) return;
+    cancel();
+    idleTimer = setTimeout(async () => {
+      const realIdleMs = Date.now() - lastConnectionTimestamp;
+      if (piGateway.connectionCount() > 0 || realIdleMs < config.shutdownIdleSeconds * 1000) {
+        start();
+        return;
+      }
+      console.log(`No pi sessions for ${config.shutdownIdleSeconds}s, shutting down...`);
+      await stopServer?.();
+      process.exit(0);
+    }, config.shutdownIdleSeconds * 1000);
+  }
+
+  function cancel() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+
+  piGateway.onEmpty = () => {
+    start();
+  };
+
+  piGateway.onConnection = () => {
+    lastConnectionTimestamp = Date.now();
+    cancel();
+  };
+
+  return {
+    start,
+    cancel,
+    setStopFn(fn: () => Promise<void>) {
+      stopServer = fn;
+    },
+  };
+}

package/packages/server/src/json-store.ts

@@ -0,0 +1,32 @@
+/**
+ * Atomic JSON file read/write helpers.
+ * Uses write-to-tmp + rename pattern to prevent corruption on crash.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Read and parse a JSON file. Returns `fallback` if the file doesn't exist or is invalid.
+ */
+export function readJsonFile<T>(filePath: string, fallback: T): T {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    if (!raw.trim()) return fallback;
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Atomically write a JSON file (write to .tmp, then rename).
+ * Creates parent directories if needed.
+ */
+export function writeJsonFile<T>(filePath: string, data: T): void {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = filePath + ".tmp";
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmpPath, filePath);
+}

package/packages/server/src/localhost-guard.ts

@@ -0,0 +1,117 @@
+/**
+ * Network access guard for Fastify routes.
+ * Supports loopback, trusted networks (CIDR/wildcard/exact), and authenticated users.
+ */
+import type { FastifyRequest, FastifyReply } from "fastify";
+
+const LOOPBACK_ADDRESSES = new Set([
+  "127.0.0.1",
+  "::1",
+  "::ffff:127.0.0.1",
+]);
+
+export function isLoopback(ip: string): boolean {
+  return LOOPBACK_ADDRESSES.has(ip);
+}
+
+/**
+ * Returns true if the source IP matches any trusted host entry.
+ * Supports exact match, wildcard (e.g. "10.0.0.*"), and CIDR notation (e.g. "192.168.1.0/24").
+ */
+export function isBypassedHost(sourceIp: string, bypassHosts: string[]): boolean {
+  // Strip IPv4-mapped IPv6 prefix (e.g. ::ffff:192.168.1.1 → 192.168.1.1)
+  const ip = sourceIp.startsWith("::ffff:") ? sourceIp.slice(7) : sourceIp;
+  for (const entry of bypassHosts) {
+    if (entry.includes("/")) {
+      if (matchCidr(ip, entry)) return true;
+    } else if (entry.includes("*")) {
+      const pattern = new RegExp("^" + entry.replace(/\./g, "\\.").replace(/\*/g, "\\d+") + "$");
+      if (pattern.test(ip)) return true;
+    } else {
+      if (ip === entry) return true;
+    }
+  }
+  return false;
+}
+
+export function matchCidr(ip: string, cidr: string): boolean {
+  const [base, bitsStr] = cidr.split("/");
+  const bits = parseInt(bitsStr, 10);
+  if (isNaN(bits) || bits < 0 || bits > 32) return false;
+  const ipNum = ipToNum(ip);
+  const baseNum = ipToNum(base);
+  if (ipNum === null || baseNum === null) return false;
+  const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+  return (ipNum & mask) === (baseNum & mask);
+}
+
+export function ipToNum(ip: string): number | null {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (const p of parts) {
+    const n = parseInt(p, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    num = (num << 8) | n;
+  }
+  return num >>> 0;
+}
+
+/**
+ * Create a network guard that allows loopback, trusted networks, or authenticated requests.
+ * Fastify lifecycle guarantees onRequest (auth) runs before preHandler (this guard).
+ */
+export function createNetworkGuard(trustedNetworks: string[]) {
+  return async function networkGuard(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    if (isLoopback(request.ip)) return;
+    if (trustedNetworks.length > 0 && isBypassedHost(request.ip, trustedNetworks)) return;
+    if ((request as any).isAuthenticated) return;
+    reply.code(403).send({ success: false, error: "Access denied" });
+  };
+}
+
+/**
+ * Convert a netmask to CIDR prefix length.
+ * E.g. "255.255.255.0" → 24
+ */
+export function netmaskToCidrBits(netmask: string): number {
+  const num = ipToNum(netmask);
+  if (num === null) return 0;
+  let bits = 0;
+  let n = num;
+  while (n & 0x80000000) {
+    bits++;
+    n = (n << 1) >>> 0;
+  }
+  return bits;
+}
+
+/**
+ * Compute the network address from an IP and netmask.
+ * E.g. ("192.168.1.42", "255.255.255.0") → "192.168.1.0"
+ */
+export function networkAddress(ip: string, netmask: string): string {
+  const ipNum = ipToNum(ip);
+  const maskNum = ipToNum(netmask);
+  if (ipNum === null || maskNum === null) return ip;
+  const net = (ipNum & maskNum) >>> 0;
+  return [
+    (net >>> 24) & 0xff,
+    (net >>> 16) & 0xff,
+    (net >>> 8) & 0xff,
+    net & 0xff,
+  ].join(".");
+}
+
+/** Legacy localhost-only guard. Prefer createNetworkGuard() for new code. */
+export async function localhostGuard(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  if (!isLoopback(request.ip)) {
+    reply.code(403).send({ success: false, error: "localhost only" });
+  }
+}