@hienlh/ppm 0.1.0

package/src/server/routes/chat.ts

@@ -0,0 +1,153 @@
+import { Hono } from "hono";
+import { resolve, join, basename } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { chatService } from "../../services/chat.service.ts";
+import { providerRegistry } from "../../providers/registry.ts";
+import { listSlashItems } from "../../services/slash-items.service.ts";
+import { fetchClaudeUsage } from "../../services/claude-usage.service.ts";
+import { ok, err } from "../../types/api.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const chatRoutes = new Hono<Env>();
+
+/** GET /chat/slash-items — list available slash commands and skills for the project */
+chatRoutes.get("/slash-items", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const items = listSlashItems(projectPath);
+    return c.json(ok(items));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /chat/usage — get current usage/rate-limit info via ccburn */
+chatRoutes.get("/usage", async (c) => {
+  try {
+    const usage = await fetchClaudeUsage();
+    return c.json(ok({
+      fiveHour: usage.session?.utilization,
+      sevenDay: usage.weekly?.utilization,
+      fiveHourResetsAt: usage.session?.resetsAt,
+      sevenDayResetsAt: usage.weekly?.resetsAt,
+      // Extra detail for popup
+      session: usage.session,
+      weekly: usage.weekly,
+      weeklyOpus: usage.weeklyOpus,
+      weeklySonnet: usage.weeklySonnet,
+    }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /chat/providers — list available AI providers */
+chatRoutes.get("/providers", (c) => {
+  try {
+    return c.json(ok(providerRegistry.list()));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /chat/sessions — list chat sessions filtered by project from context */
+chatRoutes.get("/sessions", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const providerId = c.req.query("providerId");
+    const sessions = await chatService.listSessions(providerId, projectPath);
+    return c.json(ok(sessions));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /chat/sessions/:id/messages — get message history */
+chatRoutes.get("/sessions/:id/messages", async (c) => {
+  try {
+    const id = c.req.param("id");
+    const providerId = c.req.query("providerId") ?? "claude-sdk";
+    const messages = await chatService.getMessages(providerId, id);
+    return c.json(ok(messages));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /chat/sessions — create a new session for the project in context */
+chatRoutes.post("/sessions", async (c) => {
+  try {
+    const projectName = c.get("projectName");
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ providerId?: string; title?: string }>();
+    const session = await chatService.createSession(body.providerId, {
+      projectName,
+      projectPath,
+      title: body.title,
+    });
+    return c.json(ok(session), 201);
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** DELETE /chat/sessions/:id — delete a session */
+chatRoutes.delete("/sessions/:id", async (c) => {
+  try {
+    const id = c.req.param("id");
+    const providerId = c.req.query("providerId") ?? "claude-sdk";
+    await chatService.deleteSession(providerId, id);
+    return c.json(ok({ deleted: id }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 404);
+  }
+});
+
+/** POST /chat/upload — upload files for chat attachments, returns server-side paths */
+chatRoutes.post("/upload", async (c) => {
+  try {
+    const body = await c.req.parseBody({ all: true });
+    const files = Array.isArray(body["files"]) ? body["files"] : body["files"] ? [body["files"]] : [];
+    if (files.length === 0) return c.json(err("No files provided"), 400);
+
+    const uploadDir = resolve(tmpdir(), "ppm-uploads");
+    if (!existsSync(uploadDir)) mkdirSync(uploadDir, { recursive: true });
+
+    const results: Array<{ name: string; path: string; type: string; size: number }> = [];
+    for (const entry of files) {
+      if (!(entry instanceof File)) continue;
+      const id = crypto.randomUUID().slice(0, 8);
+      const safeName = entry.name.replace(/[^a-zA-Z0-9._-]/g, "_");
+      const dest = join(uploadDir, `${id}-${safeName}`);
+      const buf = await entry.arrayBuffer();
+      await Bun.write(dest, buf);
+      results.push({ name: entry.name, path: dest, type: entry.type, size: entry.size });
+    }
+    return c.json(ok(results), 201);
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /chat/uploads/:filename — serve uploaded files (images, etc.) for preview */
+chatRoutes.get("/uploads/:filename", async (c) => {
+  try {
+    const filename = c.req.param("filename");
+    // Sanitize: only allow simple filenames, no path traversal
+    if (!filename || filename.includes("/") || filename.includes("..")) {
+      return c.json(err("Invalid filename"), 400);
+    }
+    const uploadDir = resolve(tmpdir(), "ppm-uploads");
+    const filePath = join(uploadDir, filename);
+    if (!existsSync(filePath)) return c.json(err("Not found"), 404);
+
+    const file = Bun.file(filePath);
+    return new Response(file.stream(), {
+      headers: { "Content-Type": file.type || "application/octet-stream" },
+    });
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/server/routes/files.ts

@@ -0,0 +1,168 @@
+import { Hono } from "hono";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import {
+  fileService,
+  SecurityError,
+  NotFoundError,
+  ValidationError,
+} from "../../services/file.service.ts";
+import { ok, err } from "../../types/api.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const fileRoutes = new Hono<Env>();
+
+/** Map error type to HTTP status code */
+function errorStatus(e: unknown): ContentfulStatusCode {
+  if (e instanceof SecurityError) return 403;
+  if (e instanceof NotFoundError) return 404;
+  if (e instanceof ValidationError) return 400;
+  return 500;
+}
+
+/** GET /files/tree?depth=3 */
+fileRoutes.get("/tree", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const depth = parseInt(c.req.query("depth") ?? "3", 10);
+    const tree = fileService.getTree(projectPath, depth);
+    return c.json(ok(tree));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** GET /files/raw?path=... — serve file directly as binary (for PDF viewer, images, etc.) */
+fileRoutes.get("/raw", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const filePath = c.req.query("path");
+    if (!filePath) return c.json(err("Missing query parameter: path"), 400);
+
+    // Resolve safely (reuse service's security check)
+    const absPath = resolve(projectPath, filePath);
+    if (!absPath.startsWith(projectPath)) {
+      return c.json(err("Access denied"), 403);
+    }
+    if (!existsSync(absPath)) return c.json(err("File not found"), 404);
+
+    const file = Bun.file(absPath);
+    return new Response(file.stream(), {
+      headers: {
+        "Content-Type": file.type || "application/octet-stream",
+        "Content-Disposition": "inline",
+      },
+    });
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** GET /files/read?path=... */
+fileRoutes.get("/read", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const filePath = c.req.query("path");
+    if (!filePath) {
+      return c.json(err("Missing query parameter: path"), 400);
+    }
+    const result = fileService.readFile(projectPath, filePath);
+    return c.json(ok(result));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** PUT /files/write — body: { path, content } */
+fileRoutes.put("/write", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ path: string; content: string }>();
+    if (!body.path || body.content === undefined) {
+      return c.json(err("Missing required fields: path, content"), 400);
+    }
+    fileService.writeFile(projectPath, body.path, body.content);
+    return c.json(ok({ written: body.path }));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** POST /files/create — body: { path, type } */
+fileRoutes.post("/create", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ path: string; type: "file" | "directory" }>();
+    if (!body.path || !body.type) {
+      return c.json(err("Missing required fields: path, type"), 400);
+    }
+    fileService.createFile(projectPath, body.path, body.type);
+    return c.json(ok({ created: body.path, type: body.type }), 201);
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** DELETE /files/delete — body: { path } */
+fileRoutes.delete("/delete", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ path: string }>();
+    if (!body.path) {
+      return c.json(err("Missing required field: path"), 400);
+    }
+    fileService.deleteFile(projectPath, body.path);
+    return c.json(ok({ deleted: body.path }));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** GET /files/compare?file1=path1&file2=path2 */
+fileRoutes.get("/compare", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const file1 = c.req.query("file1");
+    const file2 = c.req.query("file2");
+    if (!file1 || !file2) {
+      return c.json(err("Missing query parameters: file1, file2"), 400);
+    }
+    const original = fileService.readFile(projectPath, file1);
+    const modified = fileService.readFile(projectPath, file2);
+    return c.json(ok({ original: original.content, modified: modified.content }));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** POST /files/rename — body: { oldPath, newPath } */
+fileRoutes.post("/rename", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ oldPath: string; newPath: string }>();
+    if (!body.oldPath || !body.newPath) {
+      return c.json(err("Missing required fields: oldPath, newPath"), 400);
+    }
+    fileService.renameFile(projectPath, body.oldPath, body.newPath);
+    return c.json(ok({ renamed: { from: body.oldPath, to: body.newPath } }));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/** POST /files/move — body: { source, destination } */
+fileRoutes.post("/move", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const body = await c.req.json<{ source: string; destination: string }>();
+    if (!body.source || !body.destination) {
+      return c.json(err("Missing required fields: source, destination"), 400);
+    }
+    fileService.moveFile(projectPath, body.source, body.destination);
+    return c.json(ok({ moved: { from: body.source, to: body.destination } }));
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});

package/src/server/routes/git.ts

@@ -0,0 +1,261 @@
+import { Hono } from "hono";
+import { gitService } from "../../services/git.service.ts";
+import { ok, err } from "../../types/api.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const gitRoutes = new Hono<Env>();
+
+/** GET /git/status */
+gitRoutes.get("/status", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const status = await gitService.status(projectPath);
+    return c.json(ok(status));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/diff?ref1=&ref2= */
+gitRoutes.get("/diff", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const ref1 = c.req.query("ref1") || undefined;
+    const ref2 = c.req.query("ref2") || undefined;
+    const diff = await gitService.diff(projectPath, ref1, ref2);
+    return c.json(ok({ diff }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/diff-stat?ref1=&ref2= — file list with +/- counts */
+gitRoutes.get("/diff-stat", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const ref1 = c.req.query("ref1") || undefined;
+    const ref2 = c.req.query("ref2") || undefined;
+    const files = await gitService.diffStat(projectPath, ref1, ref2);
+    return c.json(ok(files));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/file-diff?file=&ref= */
+gitRoutes.get("/file-diff", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const file = c.req.query("file");
+    if (!file) return c.json(err("Missing query: file"), 400);
+    const ref = c.req.query("ref") || undefined;
+    const diff = await gitService.fileDiff(projectPath, file, ref);
+    return c.json(ok({ diff }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/graph?max=200 */
+gitRoutes.get("/graph", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const max = parseInt(c.req.query("max") ?? "200", 10);
+    const data = await gitService.graphData(projectPath, max);
+    return c.json(ok(data));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/branches */
+gitRoutes.get("/branches", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const branches = await gitService.branches(projectPath);
+    return c.json(ok(branches));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** GET /git/pr-url?branch= */
+gitRoutes.get("/pr-url", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const branch = c.req.query("branch");
+    if (!branch) return c.json(err("Missing query: branch"), 400);
+    const url = await gitService.getCreatePrUrl(projectPath, branch);
+    return c.json(ok({ url }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/discard { files } — discard unstaged changes (checkout tracked, clean untracked) */
+gitRoutes.post("/discard", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { files } = await c.req.json<{ files: string[] }>();
+    if (!files?.length) return c.json(err("Missing: files"), 400);
+    await gitService.discardChanges(projectPath, files);
+    return c.json(ok({ discarded: files }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/stage { files } */
+gitRoutes.post("/stage", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { files } = await c.req.json<{ files: string[] }>();
+    if (!files?.length) return c.json(err("Missing: files"), 400);
+    await gitService.stage(projectPath, files);
+    return c.json(ok({ staged: files }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/unstage { files } */
+gitRoutes.post("/unstage", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { files } = await c.req.json<{ files: string[] }>();
+    if (!files?.length) return c.json(err("Missing: files"), 400);
+    await gitService.unstage(projectPath, files);
+    return c.json(ok({ unstaged: files }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/commit { message } */
+gitRoutes.post("/commit", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { message } = await c.req.json<{ message: string }>();
+    if (!message) return c.json(err("Missing: message"), 400);
+    const hash = await gitService.commit(projectPath, message);
+    return c.json(ok({ hash }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/push { remote?, branch? } */
+gitRoutes.post("/push", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { remote, branch } = await c.req.json<{ remote?: string; branch?: string }>();
+    await gitService.push(projectPath, remote, branch);
+    return c.json(ok({ pushed: true }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/pull { remote?, branch? } */
+gitRoutes.post("/pull", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { remote, branch } = await c.req.json<{ remote?: string; branch?: string }>();
+    await gitService.pull(projectPath, remote, branch);
+    return c.json(ok({ pulled: true }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/branch/create { name, from? } */
+gitRoutes.post("/branch/create", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { name, from } = await c.req.json<{ name: string; from?: string }>();
+    if (!name) return c.json(err("Missing: name"), 400);
+    await gitService.createBranch(projectPath, name, from);
+    return c.json(ok({ created: name }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/checkout { ref } */
+gitRoutes.post("/checkout", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { ref } = await c.req.json<{ ref: string }>();
+    if (!ref) return c.json(err("Missing: ref"), 400);
+    await gitService.checkout(projectPath, ref);
+    return c.json(ok({ checkedOut: ref }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/branch/delete { name, force? } */
+gitRoutes.post("/branch/delete", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { name, force } = await c.req.json<{ name: string; force?: boolean }>();
+    if (!name) return c.json(err("Missing: name"), 400);
+    await gitService.deleteBranch(projectPath, name, force);
+    return c.json(ok({ deleted: name }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/merge { source } */
+gitRoutes.post("/merge", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { source } = await c.req.json<{ source: string }>();
+    if (!source) return c.json(err("Missing: source"), 400);
+    await gitService.merge(projectPath, source);
+    return c.json(ok({ merged: source }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/cherry-pick { hash } */
+gitRoutes.post("/cherry-pick", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { hash } = await c.req.json<{ hash: string }>();
+    if (!hash) return c.json(err("Missing: hash"), 400);
+    await gitService.cherryPick(projectPath, hash);
+    return c.json(ok({ cherryPicked: hash }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/revert { hash } */
+gitRoutes.post("/revert", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { hash } = await c.req.json<{ hash: string }>();
+    if (!hash) return c.json(err("Missing: hash"), 400);
+    await gitService.revert(projectPath, hash);
+    return c.json(ok({ reverted: hash }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /git/tag { name, hash? } */
+gitRoutes.post("/tag", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const { name, hash } = await c.req.json<{ name: string; hash?: string }>();
+    if (!name) return c.json(err("Missing: name"), 400);
+    await gitService.createTag(projectPath, name, hash);
+    return c.json(ok({ tagged: name }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/server/routes/project-scoped.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import { resolveProjectPath } from "../helpers/resolve-project.ts";
+import { chatRoutes } from "./chat.ts";
+import { gitRoutes } from "./git.ts";
+import { fileRoutes } from "./files.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const projectScopedRouter = new Hono<Env>();
+
+/** Middleware: resolve :projectName param to absolute project path */
+projectScopedRouter.use("*", async (c, next) => {
+  const name = c.req.param("projectName");
+  if (!name) return c.json({ ok: false, error: "Missing project name" }, 400);
+  try {
+    const projectPath = resolveProjectPath(name);
+    c.set("projectPath", projectPath);
+    c.set("projectName", name);
+    await next();
+  } catch (e) {
+    return c.json({ ok: false, error: (e as Error).message }, 404);
+  }
+});
+
+projectScopedRouter.route("/chat", chatRoutes);
+projectScopedRouter.route("/git", gitRoutes);
+projectScopedRouter.route("/files", fileRoutes);

package/src/server/routes/projects.ts

@@ -0,0 +1,57 @@
+import { Hono } from "hono";
+import { projectService } from "../../services/project.service.ts";
+import { searchGitDirs } from "../../services/git-dirs.service.ts";
+import { ok, err } from "../../types/api.ts";
+
+export const projectRoutes = new Hono();
+
+/** GET /api/projects — list all registered projects */
+projectRoutes.get("/", (c) => {
+  try {
+    const projects = projectService.list();
+    return c.json(ok(projects));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** POST /api/projects — add a project { path, name? } */
+projectRoutes.post("/", async (c) => {
+  try {
+    const body = await c.req.json<{ path: string; name?: string }>();
+    if (!body.path) {
+      return c.json(err("Missing required field: path"), 400);
+    }
+    const project = projectService.add(body.path, body.name);
+    return c.json(ok(project), 201);
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/**
+ * GET /api/projects/suggest-dirs?path=/some/dir&q=search
+ * Deep-scan `path` (default: home dir) for directories containing .git.
+ * Results are cached for 5 minutes. Use `q` to filter by name/path.
+ */
+projectRoutes.get("/suggest-dirs", (c) => {
+  try {
+    const root = c.req.query("path") || undefined;
+    const query = c.req.query("q") ?? "";
+    const results = searchGitDirs(query, root);
+    return c.json(ok(results));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** DELETE /api/projects/:name — remove a project by name */
+projectRoutes.delete("/:name", (c) => {
+  try {
+    const name = c.req.param("name");
+    projectService.remove(name);
+    return c.json(ok({ removed: name }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 404);
+  }
+});

package/src/server/routes/static.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono";
+import { serveStatic } from "hono/bun";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const staticRoutes = new Hono();
+
+const DIST_DIR = resolve(import.meta.dir, "../../../dist/web");
+
+/** Serve static files from dist/web/ with SPA fallback */
+staticRoutes.use(
+  "*",
+  serveStatic({
+    root: existsSync(DIST_DIR) ? DIST_DIR : undefined,
+    rewriteRequestPath: (path) => path,
+  }),
+);
+
+/** SPA fallback — serve index.html for all unmatched routes */
+staticRoutes.get("*", (c) => {
+  const indexPath = resolve(DIST_DIR, "index.html");
+  if (existsSync(indexPath)) {
+    return c.html(Bun.file(indexPath).text());
+  }
+  return c.text("Frontend not built. Run: bun run build:web", 404);
+});