@springbrand/space 0.1.0-alpha.1 → 0.1.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/space",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "files": [
     "src",

package/src/space/deploy-engine.ts

@@ -1,8 +1,19 @@
 import type { Git } from "@cloudflare/shell/git"
 import type { FileSystem } from "@cloudflare/shell"
-import { createApp, createWorker, type AssetConfig, type Modules } from "@cloudflare/worker-bundler"
-import { parseWranglerConfig, WranglerConfigError } from "./wrangler-config"
+import {
+  createApp,
+  createWorker,
+  inferContentType,
+  isTextContentType,
+  type AssetConfig,
+  type Modules,
+} from "@cloudflare/worker-bundler"
 import { globInfos } from "./fileinfo"
+import {
+  parseWranglerConfig,
+  type ParsedWranglerConfig,
+  WranglerConfigError,
+} from "./wrangler-config"
 
 // ─── Deploy Engine ──────────────────────────────────────────────────────────
 
@@ -25,11 +36,25 @@ export interface BranchDeploymentBundle {
   commitHash: string
   mainModule: string
   modules: Record<string, string | Record<string, unknown>>
-  assets: Record<string, string>
+  assets: Record<string, SerializedAsset>
   assetConfig: AssetConfig | undefined
   compatibilityDate: string
 }
 
+export type SerializedAsset = string | { base64: string }
+type WebsiteAssets = Record<string, string | ArrayBuffer>
+
+const DEFAULT_COMPATIBILITY_DATE = "2025-04-01"
+const STATIC_APP_MAIN = ".springbrand/static-app.ts"
+const STATIC_APP_SOURCE = `import { DurableObject } from "cloudflare:workers"
+
+export class App extends DurableObject {
+  fetch() {
+    return new Response("Not Found", { status: 404 })
+  }
+}
+`
+
 export async function handleDeployCommand(
   ctx: DeployContext,
   cmd: string,
@@ -74,45 +99,56 @@ export function normalizeAppRoot(appRoot?: string | null): string {
 async function readBranchFiles(
   ctx: DeployContext,
   branch: string,
-  appRoot = ""
-): Promise<{ commitHash: string; files: Record<string, string> }> {
-  // Get commit log for the branch to find the commit hash
-  const log = await ctx.git.log({ ref: branch, depth: 1 })
+  appRoot = "",
+  revision?: string,
+): Promise<{
+  commitHash: string
+  files: Record<string, string>
+  assets: WebsiteAssets
+}> {
+  const log = await ctx.git.log({ ref: branch, depth: revision ? 1000 : 1 })
   if (log.length === 0) {
     throw new Error(`No commits found on branch "${branch}"`)
   }
-  const commitHash = log[0].oid
+  const commitHash = revision
+    ? log.find((entry) => entry.oid === revision)?.oid
+    : log[0].oid
+  if (!commitHash) {
+    throw new Error(`Revision "${revision}" was not found on branch "${branch}"`)
+  }
 
-  // Checkout the branch to populate working tree
-  await ctx.git.checkout({ ref: branch, force: true })
+  await ctx.git.checkout({ ref: revision ? commitHash : branch, force: true })
 
-  // Read all files recursively (readDir is non-recursive, glob is)
-  const allFiles = await globInfos(ctx.fs, "**/*")
   const files: Record<string, string> = {}
-
-  for (const fileInfo of allFiles) {
-    if (fileInfo.type !== "file") continue
-    // Skip git's object store and the ArtifactsFileSystem bookkeeping dir —
-    // neither is part of the app and must never ship in a deploy bundle.
-    if (fileInfo.path.startsWith("/.git/") || fileInfo.path === "/.git") continue
-    if (fileInfo.path.startsWith("/.afs/") || fileInfo.path === "/.afs") continue
-
-    let content: string
-    try {
-      content = await ctx.fs.readFile(fileInfo.path)
-    } catch {
-      continue
-    }
-    const path = fileInfo.path.startsWith("/") ? fileInfo.path.slice(1) : fileInfo.path
-    if (appRoot) {
-      if (path !== appRoot && !path.startsWith(`${appRoot}/`)) continue
-      files[path.slice(appRoot.length + 1)] = content
-      continue
+  const assets: WebsiteAssets = {}
+  try {
+    for (const fileInfo of await globInfos(ctx.fs, "**/*")) {
+      if (fileInfo.type !== "file") continue
+      // Skip git's object store and the ArtifactsFileSystem bookkeeping dir —
+      // neither is part of the app and must never ship in a deploy bundle.
+      if (fileInfo.path.startsWith("/.git/") || fileInfo.path === "/.git") continue
+      if (fileInfo.path.startsWith("/.afs/") || fileInfo.path === "/.afs") continue
+
+      let bytes: Uint8Array
+      try {
+        bytes = await ctx.fs.readFileBytes(fileInfo.path)
+      } catch {
+        continue
+      }
+      const path = fileInfo.path.startsWith("/") ? fileInfo.path.slice(1) : fileInfo.path
+      if (appRoot) {
+        if (path !== appRoot && !path.startsWith(`${appRoot}/`)) continue
+        const relativePath = path.slice(appRoot.length + 1)
+        addWebsiteFile(files, assets, relativePath, bytes)
+        continue
+      }
+      addWebsiteFile(files, assets, path, bytes)
     }
-    files[path] = content
+  } finally {
+    if (revision) await ctx.git.checkout({ ref: branch, force: true })
   }
 
-  return { commitHash, files }
+  return { commitHash, files, assets }
 }
 
 // ─── Deploy a branch ────────────────────────────────────────────────────────
@@ -121,7 +157,11 @@ async function deployBranch(
   ctx: DeployContext,
   request: Request
 ): Promise<Response> {
-  const body = (await request.json()) as { branch: string; appRoot?: string }
+  const body = (await request.json()) as {
+    branch: string
+    appRoot?: string
+    revision?: string
+  }
   const branch = body.branch
   if (!branch) {
     return jsonResponse({ error: "branch is required" }, 400)
@@ -129,7 +169,7 @@ async function deployBranch(
 
   let bundle: BranchDeploymentBundle
   try {
-    bundle = await buildBranchDeployment(ctx, branch, body.appRoot)
+    bundle = await buildBranchDeployment(ctx, branch, body.appRoot, body.revision)
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e)
     const separator = message.indexOf(": ")
@@ -140,6 +180,7 @@ async function deployBranch(
   }
 
   const {
+    branch: deploymentId,
     commitHash,
     mainModule,
     modules: serializedModules,
@@ -153,7 +194,7 @@ async function deployBranch(
     `INSERT OR REPLACE INTO deployments
      (branch, commit_hash, main_module, modules, assets, asset_config, compatibility_date, deployed_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-    branch,
+    deploymentId,
     commitHash,
     mainModule,
     JSON.stringify(serializedModules),
@@ -164,7 +205,7 @@ async function deployBranch(
   )
 
   return jsonResponse({
-    branch,
+    branch: deploymentId,
     commit_hash: commitHash,
     main_module: mainModule,
     has_assets: Object.keys(serializedAssets).length > 0,
@@ -176,10 +217,11 @@ async function deployBranch(
 export async function buildBranchDeployment(
   ctx: DeployContext,
   branch: string,
-  appRoot?: string | null
+  appRoot?: string | null,
+  revision?: string,
 ): Promise<BranchDeploymentBundle> {
   const root = normalizeAppRoot(appRoot)
-  const { commitHash, files } = await readBranchFiles(ctx, branch, root)
+  const { commitHash, files, assets } = await readBranchFiles(ctx, branch, root, revision)
   if (Object.keys(files).length === 0) {
     throw new Error(
       root
@@ -188,77 +230,156 @@ export async function buildBranchDeployment(
     )
   }
 
-  let wranglerCfg
   try {
-    wranglerCfg = parseWranglerConfig(files)
-  } catch (e) {
-    if (e instanceof WranglerConfigError) {
-      throw new Error(`Invalid wrangler.json: ${e.message}`)
+    const result = await buildWebsite(files, assets)
+    return {
+      branch: revision ?? branch,
+      commitHash,
+      mainModule: result.mainModule,
+      modules: result.modules,
+      assets: serializeAssets(result.assets),
+      assetConfig: result.assetConfig,
+      compatibilityDate: result.compatibilityDate,
     }
-    throw e
+  } catch (e) {
+    throw new Error(`Build failed: ${e instanceof Error ? e.message : String(e)}`)
   }
+}
 
-  if (wranglerCfg.durableObjects?.length) {
+async function buildWebsite(
+  sourceFiles: Record<string, string>,
+  sourceAssets: WebsiteAssets,
+) {
+  const { files, config } = prepareWebsite(sourceFiles, sourceAssets)
+  if (config.durableObjects?.length) {
     throw new Error(
       "Durable Object bindings are not allowed in wrangler.json: The platform runs your app as a single Durable Object (`export class App extends DurableObject` from your main module). Do not declare `durable_objects.bindings`."
     )
   }
 
-  try {
-    const assetsDir = wranglerCfg.assets?.directory?.replace(/^\.?\//, "").replace(/\/$/, "")
-    const collectedAssets = assetsDir
-      ? Object.fromEntries(
-          Object.entries(files)
-            .filter(([path]) => path === assetsDir || path.startsWith(`${assetsDir}/`))
-            .map(([path, content]) => [`/${path.slice(assetsDir.length + 1)}`, content])
-        )
-      : {}
-    const assetConfig: AssetConfig | undefined = assetsDir
-      ? {
-          ...(wranglerCfg.assets?.notFoundHandling && {
-            not_found_handling: wranglerCfg.assets.notFoundHandling,
-          }),
-          ...(wranglerCfg.assets?.htmlHandling && {
-            html_handling: wranglerCfg.assets.htmlHandling,
-          }),
-        }
-      : undefined
-
-    if (Object.keys(collectedAssets).length) {
-      const result = await createApp({
-        files,
-        assets: collectedAssets,
-        assetConfig,
-        server: wranglerCfg.main,
-      })
-      return {
-        branch,
-        commitHash,
-        mainModule: result.mainModule,
-        modules: serializeModules(result.modules),
-        assets: serializeAssets(result.assets),
-        assetConfig: result.assetConfig,
-        compatibilityDate: wranglerCfg.compatibilityDate ?? "2025-04-01",
+  const assetsDirectory = normalizeAssetsDirectory(config.assets?.directory)
+  const assets = assetsDirectory === null
+    ? {}
+    : collectAssets(sourceAssets, assetsDirectory)
+  const assetConfig: AssetConfig | undefined = assetsDirectory === null
+    ? undefined
+    : {
+        ...(config.assets?.notFoundHandling && {
+          not_found_handling: config.assets.notFoundHandling,
+        }),
+        ...(config.assets?.htmlHandling && {
+          html_handling: config.assets.htmlHandling,
+        }),
       }
-    }
 
-    const result = await createWorker({ files, entryPoint: wranglerCfg.main })
-    const modules = serializeModules(result.modules)
-    modules["__STATIC_CONTENT_MANIFEST"] ??= { text: "{}" }
+  if (Object.keys(assets).length > 0) {
+    const result = await createApp({
+      files,
+      assets,
+      assetConfig,
+      server: config.main,
+    })
     return {
-      branch,
-      commitHash,
       mainModule: result.mainModule,
-      modules,
-      assets: {},
-      assetConfig,
-      compatibilityDate: wranglerCfg.compatibilityDate ?? "2025-04-01",
+      modules: serializeModules(result.modules),
+      assets: result.assets,
+      assetConfig: result.assetConfig,
+      compatibilityDate: config.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
     }
-  } catch (e) {
-    throw new Error(`Build failed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  const result = await createWorker({ files, entryPoint: config.main })
+  const modules = serializeModules(result.modules)
+  modules["__STATIC_CONTENT_MANIFEST"] ??= { text: "{}" }
+  return {
+    mainModule: result.mainModule,
+    modules,
+    assets: {},
+    assetConfig,
+    compatibilityDate: config.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
   }
 }
 
+function prepareWebsite(
+  files: Record<string, string>,
+  assets: WebsiteAssets,
+): { files: Record<string, string>; config: ParsedWranglerConfig } {
+  let config: ParsedWranglerConfig
+  try {
+    config = parseWranglerConfig(files)
+  } catch (error) {
+    if (error instanceof WranglerConfigError) {
+      throw new Error(`Invalid wrangler.json: ${error.message}`)
+    }
+    throw error
+  }
+  if (hasWrangler(files) || config.main || config.assets?.directory) return { files, config }
+
+  const directory = assets["index.html"] !== undefined
+    ? "."
+    : assets["public/index.html"] !== undefined
+      ? "public"
+      : null
+  if (directory === null) return { files, config }
+
+  const generatedAssets = {
+    directory,
+    htmlHandling: "auto-trailing-slash" as const,
+    notFoundHandling: "404-page" as const,
+  }
+  config = {
+    main: STATIC_APP_MAIN,
+    compatibilityDate: DEFAULT_COMPATIBILITY_DATE,
+    assets: generatedAssets,
+  }
+  return {
+    files: {
+      ...files,
+      "wrangler.json": JSON.stringify({
+        main: config.main,
+        compatibility_date: config.compatibilityDate,
+        assets: {
+          directory: generatedAssets.directory,
+          html_handling: generatedAssets.htmlHandling,
+          not_found_handling: generatedAssets.notFoundHandling,
+        },
+      }),
+      [STATIC_APP_MAIN]: STATIC_APP_SOURCE,
+    },
+    config,
+  }
+}
+
+function hasWrangler(files: Record<string, string>): boolean {
+  return ["wrangler.json", "wrangler.jsonc", "wrangler.toml"]
+    .some((path) => files[path] !== undefined)
+}
+
+function normalizeAssetsDirectory(directory?: string): string | null {
+  if (directory === undefined) return null
+  const normalized = directory.replaceAll("\\", "/").replace(/^\.\//u, "").replace(/\/$/u, "")
+  return normalized === "." ? "" : normalized
+}
+
+function collectAssets(assets: WebsiteAssets, directory: string): WebsiteAssets {
+  return Object.fromEntries(
+    Object.entries(assets)
+      .filter(([path]) => !directory || path === directory || path.startsWith(`${directory}/`))
+      .map(([path, content]) => [
+        directory ? `/${path.slice(directory.length + 1)}` : `/${path}`,
+        content,
+      ]),
+  )
+}
+
+function serializeModules(modules: Modules): Record<string, string | Record<string, unknown>> {
+  const out: Record<string, string | Record<string, unknown>> = {}
+  for (const [name, value] of Object.entries(modules)) {
+    out[name] = typeof value === "string" ? value : (value as Record<string, unknown>)
+  }
+  return out
+}
+
 // ─── Get a deployment ───────────────────────────────────────────────────────
 
 async function getDeployment(
@@ -341,23 +462,43 @@ async function undeployBranch(
 
 // ─── Serialization helpers ───────────────────────────────────────────────────
 
-function serializeModules(modules: Modules): Record<string, string | Record<string, unknown>> {
-  const out: Record<string, string | Record<string, unknown>> = {}
-  for (const [name, value] of Object.entries(modules)) {
-    out[name] = typeof value === "string" ? value : (value as Record<string, unknown>)
-  }
-  return out
-}
-
 function serializeAssets(
   assets: Record<string, string | ArrayBuffer>
-): Record<string, string> {
-  const out: Record<string, string> = {}
+): Record<string, SerializedAsset> {
+  const out: Record<string, SerializedAsset> = {}
   for (const [path, content] of Object.entries(assets)) {
-    // Store text as-is; encode binary as base64
     out[path] = typeof content === "string"
       ? content
-      : btoa(String.fromCharCode(...new Uint8Array(content)))
+      : { base64: bytesToBase64(new Uint8Array(content)) }
   }
   return out
 }
+
+function addWebsiteFile(
+  files: Record<string, string>,
+  assets: WebsiteAssets,
+  path: string,
+  bytes: Uint8Array,
+): void {
+  const contentType = inferContentType(path)
+  const binary = contentType !== undefined && !isTextContentType(contentType)
+  if (binary) {
+    assets[path] = exactBuffer(bytes)
+    return
+  }
+  const text = new TextDecoder().decode(bytes)
+  files[path] = text
+  assets[path] = text
+}
+
+function exactBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000))
+  }
+  return btoa(binary)
+}

package/src/space/durable-object.ts

@@ -7,6 +7,7 @@ import {
   handleDeployCommand,
   type BranchDeploymentBundle,
   type DeployContext,
+  type SerializedAsset,
 } from "./deploy-engine"
 import { globInfos, readDirInfos, toFileInfo } from "./fileinfo"
 import { handleAssetRequest, buildAssetManifest, createMemoryStorage, type AssetConfig } from "@cloudflare/worker-bundler"
@@ -93,11 +94,37 @@ interface DeploymentRow {
   commitHash: string
   mainModule: string
   modules: Record<string, string | Record<string, unknown>>
-  assets: Record<string, string>
+  assets: Record<string, string | ArrayBuffer>
   assetConfig: AssetConfig
   compatibilityDate: string
 }
 
+function deserializeAssets(
+  assets: Record<string, SerializedAsset>,
+): Record<string, string | ArrayBuffer> {
+  return Object.fromEntries(
+    Object.entries(assets).map(([path, content]) => [
+      path,
+      typeof content === "string"
+        ? content
+        : exactArrayBuffer(base64ToBytes(content.base64)),
+    ]),
+  )
+}
+
+function exactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+  return bytes
+}
+
 // Overlay-only paths that must never leak into a deploy, rollback tree, or any
 // file listing: git's object store and the ArtifactsFileSystem bookkeeping dir.
 const isReservedPath = isReservedSpacePath
@@ -1059,7 +1086,7 @@ export class SpaceDO extends DurableObject<Env>
    * analysis Space with a spreadsheet and a script deploys nothing until
    * someone names the directory that holds a site.
    */
-  async deploy(branch: string, appRoot?: string): Promise<unknown> {
+  async deploy(branch: string, appRoot?: string, revision?: string): Promise<unknown> {
     await this.ensureInit()
     return this.lane(async () => {
       // The deploy engine reads the full branch tree, so ensure the Artifacts
@@ -1069,7 +1096,11 @@ export class SpaceDO extends DurableObject<Env>
       const fakeRequest = new Request("http://internal/?cmd=deploy", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ branch, ...(appRoot ? { appRoot } : {}) }),
+        body: JSON.stringify({
+          branch,
+          ...(appRoot ? { appRoot } : {}),
+          ...(revision ? { revision } : {}),
+        }),
       })
       const ctx: DeployContext = {
         sql: this.ctx.storage.sql,
@@ -1078,9 +1109,12 @@ export class SpaceDO extends DurableObject<Env>
       }
       const res = await handleDeployCommand(ctx, "deploy", fakeRequest)
       const data = await res.json() as Record<string, unknown>
-      data.preview_url = `/space/${this.spaceName}/preview/${encodeURIComponent(branch)}/`
+      if (typeof data.error === "string") throw new Error(data.error)
+      const deploymentId = data.branch as string
+      data.preview_url =
+        `/space/${this.spaceName}/preview/${encodeURIComponent(deploymentId)}/`
 
-      if (!data.error) await this.backend.push(branch)
+      if (!revision) await this.backend.push(branch)
 
       return data
     })
@@ -1089,6 +1123,7 @@ export class SpaceDO extends DurableObject<Env>
   async getDeploymentBundle(
     branch: string,
     appRoot?: string,
+    revision?: string,
   ): Promise<BranchDeploymentBundle> {
     await this.ensureInit()
     await this.materializeAll()
@@ -1100,6 +1135,7 @@ export class SpaceDO extends DurableObject<Env>
       },
       branch,
       appRoot,
+      revision,
     )
   }
 
@@ -1179,7 +1215,9 @@ export class SpaceDO extends DurableObject<Env>
       commitHash: r.commit_hash as string,
       mainModule: r.main_module as string,
       modules: JSON.parse(r.modules as string) as Record<string, string | Record<string, unknown>>,
-      assets: JSON.parse((r.assets as string) || "{}") as Record<string, string>,
+      assets: deserializeAssets(
+        JSON.parse((r.assets as string) || "{}") as Record<string, SerializedAsset>,
+      ),
       assetConfig: JSON.parse((r.asset_config as string) || "{}") as AssetConfig,
       compatibilityDate: (r.compatibility_date as string) || FALLBACK_COMPATIBILITY_DATE,
     }

package/src/space/workspace-port.ts

@@ -234,7 +234,7 @@ export interface SpaceControlPort {
  * and only an explicit deploy brings an app into existence.
  */
 export interface SpaceAppPort {
-  deploy(branch: string, appRoot?: string): Promise<unknown>;
+  deploy(branch: string, appRoot?: string, revision?: string): Promise<unknown>;
   undeploy(branch: string): Promise<unknown>;
   listDeployments(): Promise<unknown>;
   getDeployment(branch: string): Promise<unknown>;