feat: support Blocks v8 (content protocol) behind a flag

apps/api/Dockerfile

@@ -58,4 +58,8 @@ ENV DATABASE_URL=file:/app/data/mesh.db
 
 # The CLI handles migrations automatically on startup
 # Use --skip-migrations if you want to manage migrations separately
-CMD ["bun", "run", "deco", "--no-tui", "--no-local-mode"]
+# Runs Studio's CLI by path, not through the `deco` bin name: another installed
+# package may declare a `deco` bin too (@decocms/blocks does), and whichever
+# wins `node_modules/.bin/deco` would start instead of Studio
+# (src/cli/deco-bin.test.ts).
+CMD ["bun", "run", "node_modules/decocms/dist/server/cli.js", "--no-tui", "--no-local-mode"]

apps/api/package.json

@@ -67,6 +67,7 @@
     "@better-auth/sso": "1.4.1",
     "@decocms/better-auth": "1.5.17",
     "@decocms/bindings": "workspace:*",
+    "@decocms/blocks": "8.1.0-next.7",
     "@decocms/mcp-utils": "workspace:*",
     "@decocms/runtime": "workspace:*",
     "@decocms/sandbox": "workspace:*",

apps/api/scripts/smoke-tarball.ts

@@ -25,7 +25,7 @@
  */
 
 import { $ } from "bun";
-import { mkdtemp, writeFile } from "fs/promises";
+import { mkdtemp, realpath, writeFile } from "fs/promises";
 import { join } from "path";
 import { tmpdir } from "os";
 
@@ -71,7 +71,25 @@ if (!(await Bun.file(clientIndex).exists())) {
 // eagerly during load, so a missing external crashes here before
 // --version prints — same symptom a real consumer would hit.
 const cliBin = join(scratch, "node_modules", ".bin", "deco");
+const studioCli = join(
+  scratch,
+  "node_modules",
+  "decocms",
+  "dist",
+  "server",
+  "cli.js",
+);
+// Another installed package with a `deco` bin (@decocms/blocks has one) can
+// win the link and start instead of Studio: the bin must be Studio's CLI.
+if ((await realpath(cliBin)) !== (await realpath(studioCli))) {
+  console.error(
+    `node_modules/.bin/deco resolves to ${await realpath(cliBin)}, not Studio's ${studioCli}`,
+  );
+  process.exit(1);
+}
 await $`${cliBin} --version`.cwd(scratch);
+// What the Docker image runs (apps/api/Dockerfile CMD): the CLI by path.
+await $`bun run node_modules/decocms/dist/server/cli.js --version`.cwd(scratch);
 
 console.log(
   "✅ Smoke test passed — browser assets are present and every external resolves at startup.",

apps/api/src/api/routes/decofile.ts

@@ -8,13 +8,25 @@
  *   PATCH  /api/:org/decofile/:virtualMcpId/:branch           write blocks (session)
  *   POST   /api/:org/decofile/:virtualMcpId/:branch/publish   merge into default (session)
  *   GET    /api/:org/decofile/:virtualMcpId/:branch/status    drift vs default (session)
+ *   POST   /api/:org/decofile/:virtualMcpId/:branch/rpc       content protocol (session, flag)
+ *   GET    /api/:org/decofile/:virtualMcpId/:branch/changes   draft changes vs production (token or session, flag)
  *
  * The surface is inert unless the virtual MCP has both a preview server URL
  * (`previewServerUrl`, legacy `productionUrl`) and a GitHub repo — what a CMS
  * session needs to render and to commit. The project's `fastPreview` switch
  * does NOT gate it; that switch only picks the runtime a NEW thread is stamped
  * with, and gating this on it would strand an already-stamped session.
  *
+ * The content-protocol routes serve next-major Blocks sites (see
+ * `decofile/repo-content-storage.ts`) and exist only behind the
+ * `site_editor_content_protocol` org flag. `rpc` doesn't need a preview
+ * server: the protocol never renders, and a project without one just has no
+ * preview. Their previews use the same Fast Preview pointer as v7, naming
+ * `changes` instead of the whole decofile: only what the branch changed
+ * against production (`decofile/draft-changes.ts`), computed on request.
+ * The editor gets that pointer's draft token and API host the v7 way, from
+ * the session-authenticated GET read above.
+ *
  * Anonymous access: `resolveOrgFromPath` lets unauthenticated requests through
  * (membership is only enforced for signed-in principals), so the GET handler
  * self-enforces the signed draft token, mirroring automation-webhooks.ts.
@@ -45,8 +57,16 @@ import {
   type DecofilePatch,
 } from "@/decofile/commit-coalescer";
 import { signDraftToken, verifyDraftToken } from "@/decofile/draft-token";
+import {
+  buildDraftChanges,
+  DraftChangesInvalidBlock,
+  DraftChangesTooLarge,
+} from "@/decofile/draft-changes";
 import { repoGitRebase } from "@/decofile/git-compat";
 import { readDecofileSnapshot } from "@/decofile/read-decofile";
+import { createRepoContentStorage } from "@/decofile/repo-content-storage";
+import { createContentHandler } from "@decocms/blocks/protocol/server";
+import { orgFlagEnabled } from "@decocms/shared/organization/schema";
 import { projectPlanningPostsForPreview } from "@/decofile/blog-draft-projection";
 import { orgHasFeature } from "@/core/plan-feature-gate";
 import type { Env } from "../hono-env";
@@ -59,6 +79,7 @@ interface DecofileScope {
   repository: RepositoryBinding;
   /** Present only for session-authenticated (member) requests. */
   userId: string | null;
+  previewServerUrl: string | null;
 }
 
 type DecofileEnv = Env & {
@@ -192,7 +213,7 @@ const resolveDecofileScope = createMiddleware<DecofileEnv>(async (c, next) => {
    *  threads, and gating the data plane on it would strand a session already
    *  stamped `cms` the moment someone flips the switch off. */
   const previewServerUrl = resolvePreviewServerUrl(metadata);
-  if (!previewServerUrl) {
+  if (!previewServerUrl && !isContentProtocolPath(c.req.path)) {
     return c.json({ error: "Project has no preview server configured" }, 404);
   }
 
@@ -211,10 +232,46 @@ const resolveDecofileScope = createMiddleware<DecofileEnv>(async (c, next) => {
     packagePath: runtime?.path?.replace(/^\/+|\/+$/g, "") || null,
     repository,
     userId,
+    previewServerUrl,
   });
   return next();
 });
 
+/** Content-protocol routes that work without a preview server. */
+function isContentProtocolPath(path: string): boolean {
+  return path.endsWith("/rpc");
+}
+
+/**
+ * The `site_editor_content_protocol` org flag, read before a content-protocol
+ * route does anything (and so before any commit). A failed read is "off":
+ * the route answers 404 and the editor stays on the v7 path.
+ */
+async function contentProtocolEnabled(
+  c: Context<DecofileEnv>,
+): Promise<boolean> {
+  const ctx = c.var.studioContext;
+  const organizationId = c.get("decofileScope").organizationId;
+  try {
+    const settings = await ctx.storage.organizationSettings.get(organizationId);
+    return orgFlagEnabled(settings?.flags, "site_editor_content_protocol");
+  } catch (error) {
+    console.error("decofile: org settings read failed; protocol off", {
+      organizationId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+
+function signScopeDraftToken(scope: DecofileScope): string {
+  return signDraftToken({
+    organizationId: scope.organizationId,
+    virtualMcpId: scope.virtualMcpId,
+    branch: scope.branch,
+  });
+}
+
 /**
  * The authority (host[:port]) the editor should bake into the `?__draft=`
  * pointer. `window.location.host` is wrong in the native app — the webview's
@@ -300,11 +357,7 @@ export function createDecofileRoutes() {
           "content-type": "application/json",
         });
       }
-      const token = signDraftToken({
-        organizationId: scope.organizationId,
-        virtualMcpId: scope.virtualMcpId,
-        branch: scope.branch,
-      });
+      const token = signScopeDraftToken(scope);
       return c.body(
         `{"version":${JSON.stringify(snapshot.sha)},"token":${JSON.stringify(token)},"apiHost":${JSON.stringify(requestApiHost(c))},"decofile":${snapshot.decofile}}`,
         200,
@@ -407,11 +460,7 @@ export function createDecofileRoutes() {
         },
         patch,
       );
-      const token = signDraftToken({
-        organizationId: scope.organizationId,
-        virtualMcpId: scope.virtualMcpId,
-        branch: scope.branch,
-      });
+      const token = signScopeDraftToken(scope);
       return c.json({ version: sha, token, apiHost: requestApiHost(c) });
     } catch (err) {
       return errorResponse(c, err);
@@ -496,5 +545,73 @@ export function createDecofileRoutes() {
     }
   });
 
+  app.post("/:virtualMcpId/:branch/rpc", async (c) => {
+    if (!(await contentProtocolEnabled(c))) {
+      return c.json({ error: "Not found" }, 404);
+    }
+    const scope = c.get("decofileScope");
+    const client = await contentClientForScope(c);
+    // Per request: the storage carries this caller's repository credential.
+    // The body cache is off for the same reason, and the blob cache under
+    // the storage already makes repeated reads cheap.
+    const handler = createContentHandler(
+      createRepoContentStorage({
+        client,
+        packagePath: scope.packagePath,
+        branch: scope.branch,
+        coAuthor: coAuthorFromStudioContext(c.var.studioContext),
+      }),
+      {
+        server: { name: "studio-github", version: "1" },
+        preview: scope.previewServerUrl
+          ? { url: new URL(scope.previewServerUrl).origin }
+          : null,
+        bodyCacheBytes: 0,
+        onError: (error) =>
+          console.error("content protocol: internal error", {
+            organizationId: scope.organizationId,
+            virtualMcpId: scope.virtualMcpId,
+            error: error instanceof Error ? error.message : String(error),
+          }),
+      },
+    );
+    return handler(c.req.raw);
+  });
+
+  /**
+   * A content-protocol draft's `?__draft=` target: what the branch changed
+   * against production, never the whole decofile (blocks docs:
+   * /next/content-delivery#draft-previews). The site's SDK reads it with the
+   * pointer's token; a branch that doesn't exist yet changed nothing.
+   */
+  app.get("/:virtualMcpId/:branch/changes", async (c) => {
+    const headers = {
+      "Cache-Control": "no-store",
+      "Access-Control-Allow-Origin": "*",
+    };
+    if (!(await contentProtocolEnabled(c))) {
+      return c.json({ error: "Not found" }, 404, headers);
+    }
+    const scope = c.get("decofileScope");
+    try {
+      const changes = await buildDraftChanges(
+        await contentClientForScope(c),
+        scope.packagePath,
+        scope.branch,
+      );
+      return c.json(changes, 200, headers);
+    } catch (err) {
+      if (err instanceof DraftChangesTooLarge) {
+        return c.json({ error: err.message }, 413, headers);
+      }
+      if (err instanceof DraftChangesInvalidBlock) {
+        return c.json({ error: err.message, file: err.file }, 422, headers);
+      }
+      const res = errorResponse(c, err);
+      for (const [k, v] of Object.entries(headers)) res.headers.set(k, v);
+      return res;
+    }
+  });
+
   return app;
 }

apps/api/src/cli/deco-bin.test.ts

@@ -0,0 +1,77 @@
+/**
+ * The published `decocms` package and its Docker image must start Studio's
+ * own CLI. `@decocms/blocks` also declares a `deco` bin: as a runtime
+ * dependency, `bun add decocms` linked whichever `deco` won into
+ * `node_modules/.bin`, and the image started the Blocks CLI
+ * (`unknown command "--no-tui"`). The server bundle inlines what it needs, so
+ * no runtime dependency may declare a `deco` bin, and the image runs the CLI
+ * by path. `scripts/smoke-tarball.ts` checks the same on the packed tarball.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const API_ROOT = join(import.meta.dir, "..", "..");
+
+interface PackageJson {
+  name: string;
+  bin?: string | Record<string, string>;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+}
+
+function readPackage(dir: string): PackageJson {
+  return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+}
+
+function binNames(pkg: PackageJson): string[] {
+  if (!pkg.bin) return [];
+  if (typeof pkg.bin === "string") return [pkg.name.split("/").pop()!];
+  return Object.keys(pkg.bin);
+}
+
+const api = readPackage(API_ROOT);
+const runtimeDeps = {
+  ...api.dependencies,
+  ...api.optionalDependencies,
+};
+
+describe("the deco bin", () => {
+  test("is Studio's CLI", () => {
+    expect(api.name).toBe("decocms");
+    expect(api.bin).toEqual({ deco: "./dist/server/cli.js" });
+  });
+
+  test("@decocms/blocks is bundled, never a runtime dependency", () => {
+    expect(Object.keys(runtimeDeps)).not.toContain("@decocms/blocks");
+  });
+
+  test("no installed runtime dependency declares another deco bin", () => {
+    const clashes = Object.keys(runtimeDeps).filter((name) => {
+      const dir = join(API_ROOT, "node_modules", name);
+      // Optional platform packages may be missing on this machine.
+      if (!existsSync(join(dir, "package.json"))) return false;
+      return binNames(readPackage(dir)).includes("deco");
+    });
+    expect(clashes).toEqual([]);
+  });
+
+  test("the Docker image runs the CLI by path", () => {
+    const dockerfile = readFileSync(join(API_ROOT, "Dockerfile"), "utf8");
+    const cmd = dockerfile
+      .split("\n")
+      .filter((line) => line.startsWith("CMD "))
+      .pop();
+    expect(cmd).toBeDefined();
+    const argv = JSON.parse(cmd!.slice("CMD ".length)) as string[];
+    // `bun add` of the tarball installs it at node_modules/decocms.
+    const cliPath = join(
+      "node_modules",
+      api.name,
+      (api.bin as Record<string, string>).deco!,
+    );
+    expect(argv.slice(0, 3)).toEqual(["bun", "run", cliPath]);
+    expect(argv).toContain("--no-tui");
+  });
+});