@decocms/start 2.0.1 → 2.1.1

package/src/daemon/fs.ts

@@ -0,0 +1,238 @@
+/**
+ * Filesystem REST API — read, patch, delete .deco/ files.
+ *
+ * The admin UI reads individual files via GET /fs/file/<path>.
+ * This is separate from the volumes/realtime WebSocket API.
+ *
+ * Ported from: deco-cx/deco daemon/fs/api.ts
+ */
+import { readFile, writeFile, rm, stat, mkdir } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import fjp from "fast-json-patch";
+import type { Operation } from "fast-json-patch";
+import { inferMetadata, broadcastFSEvent, type Metadata } from "./watch.ts";
+
+const cwd = process.cwd();
+const toPosix = (p: string) => p.replaceAll(sep, "/");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function safePath(untrusted: string): string | null {
+  const resolved = resolve(cwd, untrusted.startsWith("/") ? `.${untrusted}` : untrusted);
+  if (!resolved.startsWith(cwd + sep) && resolved !== cwd) return null;
+  return resolved;
+}
+
+function extractFilePath(url: string): string {
+  // URL: /fs/file/.deco/blocks/site.json
+  const [, ...segments] = url.split("/file");
+  return segments.join("/file") || "/";
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+async function mtimeFor(filepath: string): Promise<number> {
+  try {
+    const stats = await stat(filepath);
+    return stats.mtimeMs;
+  } catch {
+    return Date.now();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Patch application — matches daemon/fs/common.ts
+// ---------------------------------------------------------------------------
+
+interface Patch {
+  type: "json" | "text";
+  payload: Operation[];
+}
+
+function applyPatch(
+  content: string | null,
+  patch: Patch,
+): { conflict: boolean; content?: string } {
+  try {
+    if (patch.type === "json") {
+      const result = patch.payload.reduce(
+        fjp.applyReducer,
+        JSON.parse(content ?? "{}"),
+      );
+      return { conflict: false, content: JSON.stringify(result, null, 2) };
+    }
+    if (patch.type === "text") {
+      const result = patch.payload.reduce(
+        fjp.applyReducer,
+        content?.split("\n") ?? [],
+      );
+      return { conflict: false, content: (result as string[]).join("\n") };
+    }
+  } catch (err: unknown) {
+    if (
+      err instanceof fjp.JsonPatchError &&
+      err.name === "TEST_OPERATION_FAILED"
+    ) {
+      return { conflict: true };
+    }
+    throw err;
+  }
+  return { conflict: true };
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+export function createFSHandler() {
+  return async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: () => void,
+  ): Promise<void> => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const { pathname } = url;
+
+    // Only handle /fs/file/* paths
+    if (!pathname.startsWith("/fs/file")) {
+      // Also handle /fs/grep (admin search)
+      if (pathname === "/fs/grep") {
+        // Minimal grep stub — return empty results
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ matches: [], totalMatches: 0 }));
+        return;
+      }
+      next();
+      return;
+    }
+
+    const filePath = extractFilePath(pathname);
+    const systemPath = safePath(filePath);
+
+    if (!systemPath) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Path traversal denied" }));
+      return;
+    }
+
+    // GET /fs/file/* — read file
+    if (req.method === "GET") {
+      try {
+        const [content, metadata, mtime] = await Promise.all([
+          readFile(systemPath, "utf-8"),
+          inferMetadata(systemPath),
+          mtimeFor(systemPath),
+        ]);
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ content, metadata, timestamp: mtime }));
+      } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ timestamp: Date.now() }));
+          return;
+        }
+        throw err;
+      }
+      return;
+    }
+
+    // PATCH /fs/file/* — apply JSON patch
+    if (req.method === "PATCH") {
+      const raw = await readBody(req);
+      let body: { patch: Patch; timestamp: number };
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON" }));
+        return;
+      }
+
+      const mtimeBefore = await mtimeFor(systemPath);
+      let content: string | null;
+      try {
+        content = await readFile(systemPath, "utf-8");
+      } catch {
+        content = null;
+      }
+
+      const result = applyPatch(content, body.patch);
+
+      if (!result.conflict && result.content != null) {
+        const dir = join(systemPath, "..");
+        await mkdir(dir, { recursive: true });
+        await writeFile(systemPath, result.content, "utf-8");
+      }
+
+      const [metadata, mtimeAfter] = await Promise.all([
+        inferMetadata(systemPath),
+        mtimeFor(systemPath),
+      ]);
+
+      // Broadcast change for SSE listeners
+      broadcastFSEvent({
+        type: "fs-sync",
+        detail: {
+          metadata,
+          timestamp: mtimeAfter,
+          filepath: toPosix(systemPath.replace(cwd, "")),
+        },
+      });
+
+      const update = result.conflict
+        ? { conflict: true, metadata, timestamp: mtimeAfter, content }
+        : {
+            conflict: false,
+            metadata,
+            timestamp: mtimeAfter,
+            content: mtimeBefore !== body.timestamp ? result.content : undefined,
+          };
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(update));
+      return;
+    }
+
+    // DELETE /fs/file/*
+    if (req.method === "DELETE") {
+      try {
+        await rm(systemPath, { force: true });
+      } catch {
+        // ignore
+      }
+
+      broadcastFSEvent({
+        type: "fs-sync",
+        detail: {
+          metadata: null,
+          timestamp: Date.now(),
+          filepath: toPosix(systemPath.replace(cwd, "")),
+        },
+      });
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          conflict: false,
+          metadata: null,
+          timestamp: Date.now(),
+        }),
+      );
+      return;
+    }
+
+    res.writeHead(405);
+    res.end();
+  };
+}

package/src/daemon/index.ts

@@ -0,0 +1,8 @@
+export { startTunnel } from "./tunnel.ts";
+export type { TunnelOptions, TunnelConnection } from "./tunnel.ts";
+export { createAuthMiddleware, verifyAdminJwt, tokenIsValid } from "./auth.ts";
+export type { JwtPayload } from "./auth.ts";
+export { createDaemonMiddleware } from "./middleware.ts";
+export type { DaemonOptions } from "./middleware.ts";
+export { createVolumesHandler } from "./volumes.ts";
+export { createWatchHandler, watchFS, broadcastFSEvent } from "./watch.ts";

package/src/daemon/middleware.ts

@@ -0,0 +1,156 @@
+/**
+ * Daemon middleware — intercepts x-daemon-api requests, applies auth,
+ * and routes to volumes API or watch SSE.
+ *
+ * Admin runtime routes (/live/_meta, /.decofile) are NOT handled here —
+ * they fall through to Vite SSR (worker-entry.ts) where setMetaData()
+ * and setBlocks() have populated shared state. The daemon middleware loads
+ * modules via native import() which creates separate module instances.
+ *
+ * Ported from: deco-cx/deco daemon/daemon.ts
+ */
+import type { IncomingMessage, ServerResponse, Server as HttpServer } from "node:http";
+import { createAuthMiddleware } from "./auth.ts";
+import { createFSHandler } from "./fs.ts";
+import { createVolumesHandler } from "./volumes.ts";
+import { createWatchHandler, watchFS } from "./watch.ts";
+
+const DAEMON_API_SPECIFIER = "x-daemon-api";
+const HYPERVISOR_API_SPECIFIER = "x-hypervisor-api";
+
+export interface DaemonOptions {
+  /** Site name for JWT validation. */
+  site: string;
+  /** Vite dev server instance. */
+  server: {
+    httpServer: HttpServer | null;
+    watcher: { on(event: string, cb: (...args: unknown[]) => void): void };
+  };
+}
+
+// Creates a Connect-style middleware that:
+// 1. Checks for x-daemon-api or x-hypervisor-api header
+// 2. Applies JWT auth
+// 3. Routes to volumes API or SSE watch
+// 4. Falls through to Vite for other daemon requests (admin routes)
+export function createDaemonMiddleware(opts: DaemonOptions) {
+  const auth = createAuthMiddleware(opts.site);
+  const httpServer = opts.server.httpServer;
+
+  // Volumes handler (includes WebSocket upgrade registration)
+  const volumes = httpServer
+    ? createVolumesHandler({
+        httpServer,
+        watcher: opts.server.watcher,
+      })
+    : null;
+
+  // FS REST API handler (/fs/file/* — read, patch, delete)
+  const fs = createFSHandler();
+
+  // SSE watch handler — lazy port resolver for /live/_meta fetch
+  const watch = createWatchHandler({
+    getPort: () => {
+      const addr = httpServer?.address();
+      return typeof addr === "object" && addr ? addr.port : 5173;
+    },
+  });
+
+  // Wire Vite's file watcher to the broadcast channel
+  watchFS(opts.server.watcher);
+
+  // Version reported to admin.deco.cx — must satisfy admin's minimum version check.
+  // Admin compares against deco-cx/deco versions (e.g. 1.177.x), not @decocms/start versions.
+  const VERSION = "1.177.5";
+
+  return (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next: () => void,
+  ): void => {
+    let pathname: string;
+    try {
+      pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    } catch {
+      pathname = req.url ?? "/";
+    }
+
+    // Healthcheck — no auth required, admin uses this to verify env is reachable
+    if (pathname === "/_healthcheck") {
+      res.writeHead(200, {
+        "Content-Type": "text/plain",
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET",
+        "Access-Control-Allow-Headers": "Content-Type",
+      });
+      res.end(VERSION);
+      return;
+    }
+
+    // Admin runtime routes (/live/_meta, /.decofile) are NOT handled here.
+    // They fall through to Vite SSR (worker-entry.ts / TanStack routes) where
+    // setMetaData() and setBlocks() have already populated the shared state.
+    // The daemon middleware loads modules via native import() which creates
+    // separate module instances from Vite SSR — they don't share state.
+
+    const isDaemonAPI =
+      req.headers[DAEMON_API_SPECIFIER] ??
+      req.headers[HYPERVISOR_API_SPECIFIER] ??
+      false;
+
+    // Also check query param: ?x-daemon-api=true
+    if (!isDaemonAPI) {
+      try {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.searchParams.get(DAEMON_API_SPECIFIER) !== "true") {
+          next();
+          return;
+        }
+      } catch {
+        next();
+        return;
+      }
+    }
+
+    // Add CORS headers for admin.deco.cx
+    const origin = req.headers.origin;
+    if (origin) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, x-daemon-api, x-hypervisor-api");
+      res.setHeader("Access-Control-Allow-Credentials", "true");
+    }
+
+    // Handle CORS preflight
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // Auth → then route
+    auth(req, res, () => {
+      // FS REST API: /fs/file/* (read, patch, delete .deco/ files)
+      if (pathname.startsWith("/fs/")) {
+        fs(req, res, next);
+        return;
+      }
+
+      // Volumes API: /volumes/:id/files/*
+      if (pathname.includes("/volumes/") && pathname.includes("/files") && volumes) {
+        volumes(req, res, next);
+        return;
+      }
+
+      // SSE watch: /watch or root /
+      if (pathname === "/watch" || pathname === "/") {
+        watch(req, res, next);
+        return;
+      }
+
+      // Everything else falls through to Vite/TanStack admin routes
+      // (e.g., /live/_meta, /.decofile, /live/previews, /deco/invoke)
+      next();
+    });
+  };
+}

package/src/daemon/tunnel.ts

@@ -0,0 +1,129 @@
+/**
+ * Tunnel registration — connects local dev server to deco.cx admin
+ * via a WebSocket reverse proxy (@deco-cx/warp-node).
+ *
+ * Ported from: deco-cx/deco daemon/tunnel.ts
+ */
+import { connect } from "@deco-cx/warp-node";
+
+export interface TunnelOptions {
+  /** Environment name (DECO_ENV_NAME). */
+  env: string;
+  /** Site name (DECO_SITE_NAME). */
+  site: string;
+  /** Local dev server port. */
+  port: number;
+  /** Use deco.host relay (true) or simpletunnel.deco.site (false). Default true. */
+  decoHost?: boolean;
+}
+
+export interface TunnelConnection {
+  close: () => void;
+  domain: string;
+}
+
+const VERBOSE = process.env.VERBOSE;
+
+export async function startTunnel(
+  opts: TunnelOptions,
+): Promise<TunnelConnection> {
+  const { env, site, port, decoHost = true } = opts;
+
+  const decoHostDomain = `${env}--${site}.deco.host`;
+  const { server, domain } = decoHost
+    ? { server: `wss://${decoHostDomain}`, domain: decoHostDomain }
+    : {
+        server: "wss://simpletunnel.deco.site",
+        domain: `${env}--${site}.deco.site`,
+      };
+
+  const localAddr = `http://localhost:${port}`;
+  const apiKey =
+    process.env.DECO_TUNNEL_SERVER_TOKEN ??
+    "c309424a-2dc4-46fe-bfc7-a7c10df59477";
+
+  let closed = false;
+  let activeConn: Awaited<ReturnType<typeof connect>> | null = null;
+
+  async function doConnect(): Promise<void> {
+    if (closed) return;
+
+    let r: Awaited<ReturnType<typeof connect>>;
+    try {
+      r = await connect({ domain, localAddr, server, apiKey });
+      activeConn = r;
+    } catch (err) {
+      if (closed) return;
+      console.log(
+        "[deco] tunnel connect failed, retrying in 500ms…",
+        VERBOSE ? err : "",
+      );
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      return doConnect();
+    }
+
+    r.registered
+      .then(() => {
+        const adminUrl = new URL(
+          `/sites/${site}/spaces/dashboard?env=${env}`,
+          "https://admin.deco.cx",
+        );
+        console.log(
+          `\n[deco] tunnel connected — env \x1b[32m${env}\x1b[0m for site \x1b[34m${site}\x1b[0m` +
+            `\n   -> Preview: \x1b[36mhttps://${domain}\x1b[0m` +
+            `\n   -> Admin:   \x1b[36m${adminUrl.href}\x1b[0m\n`,
+        );
+      })
+      .catch((err) => {
+        console.error("[deco] tunnel registration failed:", err);
+      });
+
+    r.closed
+      .then(async (reason) => {
+        if (closed) return;
+        if (
+          reason &&
+          typeof reason === "object" &&
+          "intentional" in reason &&
+          (reason as Record<string, unknown>).intentional
+        )
+          return;
+        console.log(
+          "[deco] tunnel disconnected, retrying in 500ms…",
+          VERBOSE ? reason : "",
+        );
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return doConnect();
+      })
+      .catch(async (err: unknown) => {
+        if (closed) return;
+        if (
+          err &&
+          typeof err === "object" &&
+          "intentional" in err &&
+          (err as Record<string, unknown>).intentional
+        )
+          return;
+        console.log(
+          "[deco] tunnel error, retrying in 500ms…",
+          VERBOSE ? err : "",
+        );
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return doConnect();
+      });
+  }
+
+  await doConnect();
+
+  return {
+    close() {
+      closed = true;
+      activeConn?.closed?.catch(() => {});
+      // warp-node's connect() returns a Connected object; closing the
+      // underlying WebSocket is handled internally when the process exits.
+      // Setting closed=true prevents reconnection attempts.
+      activeConn = null;
+    },
+    domain,
+  };
+}