@brianmichel/pi-noodle 0.1.0

package/src/web/manager.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const RUN_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "run.ts");
+const STATE_PATH = join(homedir(), ".pi", "noodle", "explorer.json");
+
+export type ExplorerState = {
+  pid: number;
+  port: number;
+  dev?: boolean;
+};
+
+export function explorerStatePath(): string {
+  return STATE_PATH;
+}
+
+export function readExplorerState(): ExplorerState | null {
+  if (!existsSync(STATE_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, "utf8")) as ExplorerState;
+  } catch {
+    return null;
+  }
+}
+
+export function clearExplorerState(): void {
+  try {
+    unlinkSync(STATE_PATH);
+  } catch {
+    /* already gone */
+  }
+}
+
+export function isExplorerRunning(): boolean {
+  const state = readExplorerState();
+  if (!state) return false;
+  try {
+    process.kill(state.pid, 0);
+    return true;
+  } catch {
+    clearExplorerState();
+    return false;
+  }
+}
+
+export function openExplorerBrowser(port: number): void {
+  const url = `http://localhost:${port}`;
+  const cmd =
+    platform === "darwin"
+      ? "open"
+      : platform === "win32"
+        ? "start"
+        : "xdg-open";
+  spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+}
+
+export function spawnExplorer(port: number, dev = false): ExplorerState | null {
+  if (isExplorerRunning()) {
+    return readExplorerState();
+  }
+
+  const args = [RUN_SCRIPT, String(port)];
+  if (dev) args.push("--dev");
+
+  const child = spawn("bun", args, {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+
+  if (!child.pid) return null;
+  child.unref();
+  return { pid: child.pid, port, dev };
+}
+
+export function stopExplorer(): boolean {
+  const state = readExplorerState();
+  if (!state) return false;
+
+  try {
+    process.kill(state.pid, "SIGTERM");
+  } catch {
+    /* process may already be gone */
+  }
+
+  clearExplorerState();
+  return true;
+}

package/src/web/run.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { memoryService } from "../memory/runtime.ts";
+import {
+  clearExplorerState,
+  explorerStatePath,
+  type ExplorerState,
+} from "./manager.ts";
+import { startMemoryExplorer } from "./server.ts";
+
+const port = parseInt(process.argv[2] ?? "3000", 10);
+const dev = process.argv.includes("--dev");
+
+mkdirSync(dirname(explorerStatePath()), { recursive: true });
+const state: ExplorerState = { pid: process.pid, port, dev };
+writeFileSync(explorerStatePath(), JSON.stringify(state));
+
+function cleanup(): void {
+  clearExplorerState();
+}
+
+const server = startMemoryExplorer(memoryService, port, { dev, openBrowser: true });
+
+function shutdown(): void {
+  cleanup();
+  server.stop();
+  process.exit(0);
+}
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+process.on("exit", cleanup);

package/src/web/server.ts

@@ -0,0 +1,212 @@
+import { readFileSync, watch } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+import { fileURLToPath } from "node:url";
+import type { ServerWebSocket } from "bun";
+import type { MemoryRecord } from "../memory/types.ts";
+
+const WEB_DIR = dirname(fileURLToPath(import.meta.url));
+const HTML_PATH = join(WEB_DIR, "index.html");
+
+const PING_INTERVAL_MS = 4_000;
+const STALE_TIMEOUT_MS = 12_000;
+const SHUTDOWN_DELAY_MS = 1_500;
+
+export type MemoryExplorerOptions = {
+  dev?: boolean;
+  openBrowser?: boolean;
+};
+
+export function startMemoryExplorer(
+  service: {
+    list: () => Promise<MemoryRecord[]>;
+    update: (id: string, input: { text?: string; metadata?: Record<string, unknown> }) => Promise<void>;
+    delete: (id: string) => Promise<void>;
+  },
+  port = 3000,
+  options: MemoryExplorerOptions = {},
+): ReturnType<typeof Bun.serve> {
+  const dev = options.dev ?? false;
+  const openBrowser = options.openBrowser ?? !dev;
+  let shutdownTimer: ReturnType<typeof setTimeout> | null = null;
+  let html = readFileSync(HTML_PATH, "utf8");
+  const sockets = new Set<ServerWebSocket<unknown>>();
+  const lastSeen = new Map<ServerWebSocket<unknown>, number>();
+
+  function scheduleShutdownIfIdle(): void {
+    if (dev) return;
+    if (sockets.size > 0) {
+      if (shutdownTimer) {
+        clearTimeout(shutdownTimer);
+        shutdownTimer = null;
+      }
+      return;
+    }
+    if (shutdownTimer) return;
+    shutdownTimer = setTimeout(() => {
+      shutdownTimer = null;
+      if (sockets.size > 0) return;
+      console.log("All tabs closed. Shutting down.");
+      server.stop();
+      process.exit(0);
+    }, SHUTDOWN_DELAY_MS);
+  }
+
+  function touch(ws: ServerWebSocket<unknown>): void {
+    lastSeen.set(ws, Date.now());
+  }
+
+  function pruneStaleSockets(): void {
+    const now = Date.now();
+    for (const ws of sockets) {
+      if (now - (lastSeen.get(ws) ?? 0) > STALE_TIMEOUT_MS) {
+        ws.close(1000, "stale");
+      }
+    }
+  }
+
+  function broadcastReload(): void {
+    const payload = JSON.stringify({ type: "reload" });
+    for (const ws of sockets) {
+      ws.send(payload);
+    }
+  }
+
+  function invalidateAndReload(): void {
+    html = readFileSync(HTML_PATH, "utf8");
+    console.log("[dev] UI updated — reloading browser");
+    broadcastReload();
+  }
+
+  if (dev) {
+    let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+    watch(WEB_DIR, { recursive: true }, (_event, filename) => {
+      if (!filename || filename === "server.ts" || filename === "dev.ts")
+        return;
+      if (reloadTimer) clearTimeout(reloadTimer);
+      reloadTimer = setTimeout(() => {
+        reloadTimer = null;
+        invalidateAndReload();
+      }, 100);
+    });
+  }
+
+  const server = Bun.serve({
+    port,
+    fetch: async (req, server) => {
+      const url = new URL(req.url);
+      if (server.upgrade(req)) return;
+
+      if (url.pathname === "/") {
+        return new Response(html, {
+          headers: {
+            "Content-Type": "text/html",
+            ...(dev ? { "Cache-Control": "no-store" } : {}),
+          },
+        });
+      }
+
+      if (url.pathname === "/api/memories" && req.method === "GET") {
+        try {
+          const memories = (await service.list()).map(memoryToApi);
+          return Response.json(memories);
+        } catch (err) {
+          return Response.json({ error: String(err) }, { status: 500 });
+        }
+      }
+
+      const match = url.pathname.match(/^\/api\/memories\/([^/]+)$/);
+      if (match && req.method === "PATCH") {
+        try {
+          const body = await req.json().catch(() => ({}));
+          const text = typeof body?.text === "string" ? body.text.trim() : undefined;
+          if (!text) return Response.json({ error: "text is required" }, { status: 400 });
+          await service.update(decodeURIComponent(match[1] ?? ""), { text });
+          return Response.json({ updated: true });
+        } catch (err) {
+          return Response.json({ error: String(err) }, { status: 500 });
+        }
+      }
+
+      if (match && req.method === "DELETE") {
+        try {
+          await service.delete(decodeURIComponent(match[1] ?? ""));
+          return Response.json({ deleted: true });
+        } catch (err) {
+          return Response.json({ error: String(err) }, { status: 500 });
+        }
+      }
+
+      return new Response("Not found", { status: 404 });
+    },
+    websocket: {
+      open(ws) {
+        touch(ws);
+        sockets.add(ws);
+        if (shutdownTimer) {
+          clearTimeout(shutdownTimer);
+          shutdownTimer = null;
+        }
+      },
+      close(ws) {
+        sockets.delete(ws);
+        lastSeen.delete(ws);
+        scheduleShutdownIfIdle();
+      },
+      message(ws, raw) {
+        touch(ws);
+        try {
+          const msg = JSON.parse(String(raw)) as { type?: string };
+          if (msg.type === "ping") {
+            ws.send(JSON.stringify({ type: "pong" }));
+            return;
+          }
+          if (msg.type === "bye") {
+            ws.close(1000, "client bye");
+          }
+        } catch {
+          /* ignore malformed messages */
+        }
+      },
+    },
+  });
+
+  if (!dev) {
+    setInterval(() => {
+      pruneStaleSockets();
+      scheduleShutdownIfIdle();
+    }, PING_INTERVAL_MS);
+  }
+
+  const url = `http://localhost:${port}`;
+  console.log(`Memory Explorer: ${url}${dev ? " (dev — hot reload on)" : ""}`);
+
+  if (openBrowser) {
+    setTimeout(() => {
+      const cmd =
+        platform === "darwin"
+          ? "open"
+          : platform === "win32"
+            ? "start"
+            : "xdg-open";
+      spawn(cmd, [url], { stdio: "ignore", detached: true });
+    }, 100);
+  }
+
+  return server;
+}
+
+function memoryToApi(memory: MemoryRecord): Record<string, unknown> {
+  return {
+    id: memory.id,
+    text: memory.text,
+    category: memory.category,
+    categories: memory.categories,
+    scope: memory.scope ?? {},
+    metadata: memory.metadata,
+    createdAt: memory.createdAt ?? null,
+    retrievalCount: memory.retrievalCount ?? 0,
+    lastRetrieved: memory.lastRetrieved ?? null,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node", "bun"]
+  },
+  "include": ["index.ts", "src/**/*.ts", "test/**/*.ts"]
+}