@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/server/src/routes/editor-routes.ts

@@ -0,0 +1,86 @@
+/**
+ * REST routes for editor (code-server) lifecycle management.
+ */
+import type { FastifyInstance } from "fastify";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { EditorManager } from "../editor-manager.js";
+import type { NetworkGuard } from "./route-deps.js";
+
+export function registerEditorRoutes(
+  fastify: FastifyInstance,
+  editorManager: EditorManager,
+  deps: { networkGuard: NetworkGuard },
+) {
+  const { networkGuard } = deps;
+  // Start or return existing editor instance
+  fastify.post<{ Body: { cwd?: string; theme?: "dark" | "light" } }>(
+    "/api/editor/start",
+    { preHandler: networkGuard },
+    async (request) => {
+      const { cwd, theme } = request.body ?? {};
+      if (!cwd) {
+        return { success: false, error: "cwd required" } satisfies ApiResponse;
+      }
+
+      try {
+        const info = await editorManager.start(cwd, theme);
+        return { success: true, data: info } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // Heartbeat to keep instance alive
+  fastify.post<{ Params: { id: string } }>(
+    "/api/editor/:id/heartbeat",
+    { preHandler: networkGuard },
+    async (request) => {
+      const { id } = request.params;
+      const inst = editorManager.get(id);
+      if (!inst) {
+        return { success: false, error: "instance not found" } satisfies ApiResponse;
+      }
+      editorManager.heartbeat(id);
+      return { success: true } satisfies ApiResponse;
+    },
+  );
+
+  // Stop an editor instance
+  fastify.post<{ Params: { id: string } }>(
+    "/api/editor/:id/stop",
+    { preHandler: networkGuard },
+    async (request) => {
+      const { id } = request.params;
+      editorManager.stop(id);
+      return { success: true } satisfies ApiResponse;
+    },
+  );
+
+  // Update theme for a running editor instance
+  fastify.post<{ Params: { id: string }; Body: { theme?: "dark" | "light" } }>(
+    "/api/editor/:id/theme",
+    { preHandler: networkGuard },
+    async (request) => {
+      const { id } = request.params;
+      const { theme } = request.body ?? {};
+      const inst = editorManager.get(id);
+      if (!inst) {
+        return { success: false, error: "instance not found" } satisfies ApiResponse;
+      }
+      if (theme) {
+        editorManager.setTheme(inst.cwd, theme);
+      }
+      return { success: true } satisfies ApiResponse;
+    },
+  );
+
+  // List all editor instances
+  fastify.get(
+    "/api/editor/status",
+    { preHandler: networkGuard },
+    async () => {
+      return { success: true, data: editorManager.list() } satisfies ApiResponse;
+    },
+  );
+}

package/packages/server/src/routes/file-routes.ts

@@ -0,0 +1,116 @@
+/**
+ * File, directory browse, and README REST API routes (localhost-only).
+ */
+import type { FastifyInstance } from "fastify";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { NetworkGuard } from "./route-deps.js";
+import { listDirectories } from "../browse.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+export function registerFileRoutes(
+  fastify: FastifyInstance,
+  deps: {
+    sessionManager: SessionManager;
+    preferencesStore: PreferencesStore;
+    networkGuard: NetworkGuard;
+  },
+) {
+  const { sessionManager, preferencesStore, networkGuard } = deps;
+
+  // Directory browse endpoint
+  fastify.get<{ Querystring: { path?: string } }>(
+    "/api/browse",
+    { preHandler: networkGuard },
+    async (request) => {
+      try {
+        const result = await listDirectories(request.query.path || undefined);
+        return { success: true, data: result } satisfies ApiResponse;
+      } catch {
+        return { success: false, error: "directory not found" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // File read endpoint — read file content or list directory
+  fastify.get<{ Querystring: { cwd?: string; path?: string } }>(
+    "/api/file",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      const relPath = request.query.path;
+      if (!cwd || !relPath) {
+        reply.code(400);
+        return { success: false, error: "cwd and path parameters required" } satisfies ApiResponse;
+      }
+
+      const allSessions = sessionManager.listAll();
+      if (!allSessions.some((s) => s.cwd === cwd)) {
+        reply.code(403);
+        return { success: false, error: "unknown session path" } satisfies ApiResponse;
+      }
+
+      const resolved = path.resolve(cwd, relPath);
+      if (!resolved.startsWith(cwd + path.sep) && resolved !== cwd) {
+        reply.code(403);
+        return { success: false, error: "path outside working directory" } satisfies ApiResponse;
+      }
+
+      try {
+        const stat = await fs.stat(resolved);
+        if (stat.isDirectory()) {
+          const entries = await fs.readdir(resolved);
+          entries.sort();
+          return { success: true, data: { type: "directory", entries } } satisfies ApiResponse;
+        }
+        const content = await fs.readFile(resolved, "utf-8");
+        return { success: true, data: { type: "file", content } } satisfies ApiResponse;
+      } catch {
+        reply.code(404);
+        return { success: false, error: "not found" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // README endpoint — read README.md from a directory
+  fastify.get<{ Querystring: { cwd?: string; check?: string } }>(
+    "/api/readme",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd parameter required" } satisfies ApiResponse;
+      }
+
+      const allSessions = sessionManager.listAll();
+      const knownCwds = new Set(allSessions.map((s) => s.cwd));
+      for (const dir of preferencesStore.getPinnedDirectories()) knownCwds.add(dir);
+
+      if (!knownCwds.has(cwd)) {
+        reply.code(403);
+        return { success: false, error: "unknown directory" } satisfies ApiResponse;
+      }
+
+      const readmePath = path.join(cwd, "README.md");
+      try {
+        if (request.query.check) {
+          await fs.access(readmePath);
+          return { success: true, data: { exists: true } } satisfies ApiResponse;
+        }
+        const content = await fs.readFile(readmePath, "utf-8");
+        return { success: true, data: { content } } satisfies ApiResponse;
+      } catch {
+        reply.code(404);
+        return { success: false, error: "README.md not found" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // Pinned directories endpoint
+  fastify.get("/api/pinned-dirs", async () => {
+    return { success: true, data: preferencesStore.getPinnedDirectories() } satisfies ApiResponse;
+  });
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Git operation REST API routes (localhost-only).
+ */
+import type { FastifyInstance } from "fastify";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { NetworkGuard } from "./route-deps.js";
+import { isGitRepo, listBranches, checkoutBranch, gitInit, stashPop } from "../git-operations.js";
+
+export function registerGitRoutes(fastify: FastifyInstance, deps: { networkGuard: NetworkGuard }) {
+  const { networkGuard } = deps;
+  fastify.get<{ Querystring: { cwd?: string } }>(
+    "/api/git/branches",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd parameter required" } satisfies ApiResponse;
+      }
+      if (!isGitRepo(cwd)) {
+        return { success: false, error: "not a git repository" } satisfies ApiResponse;
+      }
+      try {
+        const data = listBranches(cwd);
+        return { success: true, data } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message ?? "failed to list branches" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  fastify.post<{ Body: { cwd?: string; branch?: string; stash?: boolean } }>(
+    "/api/git/checkout",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd, branch, stash } = request.body ?? {};
+      if (!cwd || !branch) {
+        reply.code(400);
+        return { success: false, error: "cwd and branch required" } satisfies ApiResponse;
+      }
+      try {
+        const result = checkoutBranch(cwd, branch, stash ?? false);
+        if (!result.success) {
+          reply.code(409);
+          return result;
+        }
+        return { success: true, data: { stashed: result.stashed } } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message ?? "checkout failed" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  fastify.post<{ Body: { cwd?: string } }>(
+    "/api/git/init",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd } = request.body ?? {};
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd required" } satisfies ApiResponse;
+      }
+      try {
+        gitInit(cwd);
+        return { success: true } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message ?? "init failed" } satisfies ApiResponse;
+      }
+    },
+  );
+
+  fastify.post<{ Body: { cwd?: string } }>(
+    "/api/git/stash-pop",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd } = request.body ?? {};
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd required" } satisfies ApiResponse;
+      }
+      try {
+        const result = stashPop(cwd);
+        return { success: true, data: result } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message ?? "stash pop failed" } satisfies ApiResponse;
+      }
+    },
+  );
+}

package/packages/server/src/routes/openspec-routes.ts

@@ -0,0 +1,99 @@
+/**
+ * OpenSpec and Pi Resources REST API routes (localhost-only).
+ */
+import type { FastifyInstance } from "fastify";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { DirectoryService } from "../directory-service.js";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { NetworkGuard } from "./route-deps.js";
+import { scanOpenSpecArchive } from "../openspec-archive.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+export function registerOpenSpecRoutes(
+  fastify: FastifyInstance,
+  deps: {
+    sessionManager: SessionManager;
+    preferencesStore: PreferencesStore;
+    directoryService: DirectoryService;
+    networkGuard: NetworkGuard;
+  },
+) {
+  const { sessionManager, preferencesStore, directoryService, networkGuard } = deps;
+
+  // OpenSpec archive listing endpoint
+  fastify.get<{ Querystring: { cwd?: string } }>(
+    "/api/openspec-archive",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "Missing cwd" } satisfies ApiResponse;
+      }
+      const data = await scanOpenSpecArchive(cwd);
+      return { success: true, data } satisfies ApiResponse;
+    },
+  );
+
+  // Pi Resources endpoint — returns discovered extensions, skills, prompts
+  fastify.get<{ Querystring: { cwd?: string; refresh?: string } }>(
+    "/api/pi-resources",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd parameter required" } satisfies ApiResponse;
+      }
+      const forceRefresh = request.query.refresh === "true" || request.query.refresh === "1";
+      let data = forceRefresh ? undefined : directoryService.getPiResources(cwd);
+      if (!data) {
+        data = await directoryService.refreshPiResources(cwd);
+      }
+      return { success: true, data } satisfies ApiResponse;
+    },
+  );
+
+  // Pi Resource file endpoint — reads files from allowed pi resource locations
+  fastify.get<{ Querystring: { path?: string } }>(
+    "/api/pi-resource-file",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const filePath = request.query.path;
+      if (!filePath) {
+        reply.code(400);
+        return { success: false, error: "path parameter required" } satisfies ApiResponse;
+      }
+
+      const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+      const globalPiDir = path.join(homeDir, ".pi", "agent");
+      const allSessions = sessionManager.listAll();
+      const knownCwds = new Set(allSessions.map((s) => s.cwd));
+      for (const dir of preferencesStore.getPinnedDirectories()) knownCwds.add(dir);
+
+      const normalizedPath = path.resolve(filePath);
+      const isAllowed =
+        normalizedPath.startsWith(globalPiDir + path.sep) ||
+        [...knownCwds].some(
+          (cwd) => normalizedPath.startsWith(path.join(cwd, ".pi") + path.sep),
+        ) ||
+        normalizedPath.includes(path.join(".pi", "git") + path.sep) ||
+        normalizedPath.includes("node_modules" + path.sep);
+
+      if (!isAllowed) {
+        reply.code(403);
+        return { success: false, error: "path not in allowed resource location" } satisfies ApiResponse;
+      }
+
+      try {
+        const content = await fs.readFile(normalizedPath, "utf-8");
+        return { success: true, data: { type: "file", content } } satisfies ApiResponse;
+      } catch {
+        reply.code(404);
+        return { success: false, error: "not found" } satisfies ApiResponse;
+      }
+    },
+  );
+}

package/packages/server/src/routes/package-routes.ts

@@ -0,0 +1,172 @@
+/**
+ * REST routes for pi package management: search, readme, installed, install, remove, update, check-updates.
+ */
+import type { FastifyInstance } from "fastify";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { PackageManagerWrapper } from "../package-manager-wrapper.js";
+import { PackageOperationBusyError } from "../package-manager-wrapper.js";
+import { searchPackages, fetchReadme, PackageNotFoundError } from "../npm-search-proxy.js";
+
+export function registerPackageRoutes(
+  fastify: FastifyInstance,
+  deps: {
+    packageManagerWrapper: PackageManagerWrapper;
+  },
+) {
+  const { packageManagerWrapper } = deps;
+
+  // ── Search npm packages ─────────────────────────────────────────
+
+  fastify.get<{ Querystring: { q?: string; type?: string } }>(
+    "/api/packages/search",
+    async (request) => {
+      const { q, type } = request.query;
+      try {
+        const result = await searchPackages({ query: q, type });
+        return { success: true, data: result } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── Fetch package README ────────────────────────────────────────
+
+  fastify.get<{ Querystring: { pkg: string } }>(
+    "/api/packages/readme",
+    async (request, reply) => {
+      const { pkg } = request.query;
+      if (!pkg) {
+        reply.code(400);
+        return { success: false, error: "pkg parameter required" } satisfies ApiResponse;
+      }
+      try {
+        const result = await fetchReadme(pkg);
+        return { success: true, data: result } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof PackageNotFoundError) {
+          reply.code(404);
+          return { success: false, error: err.message } satisfies ApiResponse;
+        }
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── List installed packages ─────────────────────────────────────
+
+  fastify.get<{ Querystring: { scope?: string; cwd?: string } }>(
+    "/api/packages/installed",
+    async (request) => {
+      const scope = request.query.scope === "local" ? "local" : "global";
+      const cwd = request.query.cwd;
+      try {
+        const packages = await packageManagerWrapper.listInstalled(scope, cwd);
+        return { success: true, data: packages } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── Install package ─────────────────────────────────────────────
+
+  fastify.post<{ Body: { source: string; scope: string; cwd?: string } }>(
+    "/api/packages/install",
+    async (request, reply) => {
+      const { source, scope, cwd } = request.body ?? {};
+      if (!source) {
+        reply.code(400);
+        return { success: false, error: "source is required" } satisfies ApiResponse;
+      }
+      const effectiveScope = scope === "local" ? "local" as const : "global" as const;
+      try {
+        const operationId = await packageManagerWrapper.run({
+          action: "install",
+          source,
+          scope: effectiveScope,
+          cwd,
+        });
+        reply.code(202);
+        return { success: true, data: { operationId } } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof PackageOperationBusyError) {
+          reply.code(409);
+          return { success: false, error: err.message } satisfies ApiResponse;
+        }
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── Remove package ──────────────────────────────────────────────
+
+  fastify.post<{ Body: { source: string; scope: string; cwd?: string } }>(
+    "/api/packages/remove",
+    async (request, reply) => {
+      const { source, scope, cwd } = request.body ?? {};
+      if (!source) {
+        reply.code(400);
+        return { success: false, error: "source is required" } satisfies ApiResponse;
+      }
+      const effectiveScope = scope === "local" ? "local" as const : "global" as const;
+      try {
+        const operationId = await packageManagerWrapper.run({
+          action: "remove",
+          source,
+          scope: effectiveScope,
+          cwd,
+        });
+        reply.code(202);
+        return { success: true, data: { operationId } } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof PackageOperationBusyError) {
+          reply.code(409);
+          return { success: false, error: err.message } satisfies ApiResponse;
+        }
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── Update packages ─────────────────────────────────────────────
+
+  fastify.post<{ Body: { source?: string; scope: string; cwd?: string } }>(
+    "/api/packages/update",
+    async (request, reply) => {
+      const { source, scope, cwd } = request.body ?? {};
+      const effectiveScope = scope === "local" ? "local" as const : "global" as const;
+      try {
+        const operationId = await packageManagerWrapper.run({
+          action: "update",
+          source: source ?? "",
+          scope: effectiveScope,
+          cwd,
+        });
+        reply.code(202);
+        return { success: true, data: { operationId } } satisfies ApiResponse;
+      } catch (err: any) {
+        if (err instanceof PackageOperationBusyError) {
+          reply.code(409);
+          return { success: false, error: err.message } satisfies ApiResponse;
+        }
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── Check for updates ───────────────────────────────────────────
+
+  fastify.post<{ Body: { cwd?: string } }>(
+    "/api/packages/check-updates",
+    async (request) => {
+      const { cwd } = request.body ?? {};
+      try {
+        const updates = await packageManagerWrapper.checkUpdates(cwd);
+        return { success: true, data: updates } satisfies ApiResponse;
+      } catch (err: any) {
+        return { success: false, error: err.message } satisfies ApiResponse;
+      }
+    },
+  );
+}