@springbrand/space 0.1.0-alpha.9 → 0.2.0-alpha.0

package/README.md

@@ -1,7 +1,7 @@
 # @springbrand/space
 
-SpaceDO — a git-backed Durable Object workspace with deploy, preview and App
-Facet database inspection.
+SpaceDO — a git-backed Durable Object workspace with target-neutral deployment
+bundles, CDN-backed Preview assets, App Facet execution and database inspection.
 
 ## Provenance
 
@@ -11,14 +11,19 @@ This package is a tracked fork of the VibeSDK `space/` package.
 - Frozen at: `main@a318f08625db`
 - Licence: MIT (see `LICENSE`)
 
-Files under `src/space/` are the upstream implementation. Local additions are
-confined to the `WorkspacePort` compatibility surface on `SpaceDO`
-(`durable-object.ts`), which Agent Runtime hosts require: binary
-writes, append, conditional write, quota, full file operations, R2 spill,
-path-level restore and `destroySpace`.
+The fork retains VibeSDK's Workspace and App Facet model while replacing its
+single-row Preview assets with per-file R2 objects. One `DeploymentBundle`
+separates Worker modules, static asset metadata and deployment-level runtime
+configuration so Preview and production publishers can consume the same build.
 
 ## Boundary
 
 SpaceDO is infrastructure. It knows nothing about users, Chats or
 authorisation — the host Worker decides which Space a request belongs to and
 whether the caller may reach it.
+
+Preview publication writes static assets below one immutable R2 deployment
+prefix and returns that prefix to the host. Static requests can therefore go
+straight to a Workspace CDN; `serveApp()` is the dynamic-only path into the App
+Facet. `servePreview()` remains available for hosts that intentionally proxy
+both asset and backend traffic through SpaceDO.

package/package.json

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

package/src/index.ts

@@ -18,7 +18,17 @@ export type {
   SpaceWorkspacePort,
 } from "./space/durable-object";
 export { SPACE_RESERVED_PREFIXES } from "./space/durable-object";
-export type { BranchDeploymentBundle } from "./space/deploy-engine";
+export {
+  deploymentRuntimeConfigSource,
+  RUNTIME_CONFIG_ASSET_PATH,
+} from "./space/deploy-engine";
+export type {
+  BranchDeploymentBundle,
+  DeploymentAsset,
+  DeploymentBundle,
+  DeploymentRuntimeConfig,
+  SpaceDeploymentResult,
+} from "./space/deploy-engine";
 
 // ── Preview hardening ─────────────────────────────────────────────
 export { stripPreviewSecurityHeaders, STRIPPED_PREVIEW_HEADERS } from "./space/preview-headers";

package/src/space/deploy-engine.ts

@@ -32,18 +32,40 @@ export interface DeployContext {
   assetPrefix?: string
 }
 
-export interface BranchDeploymentBundle {
+export interface DeploymentBundle {
   branch: string
   commitHash: string
-  mainModule: string
-  modules: Record<string, string | Record<string, unknown>>
-  assets: DeploymentAsset[]
+  workerModules: {
+    mainModule: string
+    modules: Record<string, string | Record<string, unknown>>
+    compatibilityDate: string
+  }
+  staticAssets: DeploymentAsset[]
   assetConfig: AssetConfig | undefined
-  compatibilityDate: string
+  runtimeConfig: DeploymentRuntimeConfig | undefined
+}
+
+export type BranchDeploymentBundle = DeploymentBundle
+
+export interface DeploymentRuntimeConfig {
+  apiBaseUrl: string
 }
 
+export interface SpaceDeploymentResult {
+  branch: string
+  commit_hash: string
+  main_module: string
+  has_assets: boolean
+  compatibility_date: string
+  deployed_at: string
+  asset_root: string | null
+}
+
+export const RUNTIME_CONFIG_ASSET_PATH = "/.springbrand/runtime-config.js"
+
 export interface DeploymentAsset {
   path: string
+  sourcePath: string | null
   contentType: string | undefined
   etag: string
   size: number
@@ -173,6 +195,7 @@ async function readBranchFiles(
         const bytes = await ctx.fs.readFileBytes(entry.sourcePath)
         const asset: Omit<DeploymentAsset, "etag"> = {
           path: toAssetPath(entry.path, assetsDirectory!),
+          sourcePath: entry.sourcePath,
           contentType: inferContentType(entry.path),
           size: bytes.byteLength,
         }
@@ -219,6 +242,7 @@ async function deployBranch(
     branch: string
     appRoot?: string
     revision?: string
+    runtimeConfig?: DeploymentRuntimeConfig
   }
   const branch = body.branch
   if (!branch) {
@@ -257,6 +281,7 @@ async function deployBranch(
         )
         return uploaded.etag
       },
+      body.runtimeConfig,
     )
   } catch (e) {
     await discardAssetDeployment(ctx, assetDeploymentId, assetRoot).catch((cleanupError) => {
@@ -273,11 +298,13 @@ async function deployBranch(
   const {
     branch: deploymentId,
     commitHash,
-    mainModule,
-    modules: serializedModules,
-    assets,
+    workerModules: {
+      mainModule,
+      modules: serializedModules,
+      compatibilityDate: compatDate,
+    },
+    staticAssets: assets,
     assetConfig,
-    compatibilityDate: compatDate,
   } = bundle
 
   const now = Date.now()
@@ -333,6 +360,7 @@ async function deployBranch(
     has_assets: assets.length > 0,
     compatibility_date: compatDate,
     deployed_at: new Date(now).toISOString(),
+    asset_root: assets.length > 0 ? assetRoot : null,
   })
 }
 
@@ -342,6 +370,7 @@ export async function buildBranchDeployment(
   appRoot?: string | null,
   revision?: string,
   writeAsset?: AssetWriter,
+  runtimeConfig?: DeploymentRuntimeConfig,
 ): Promise<BranchDeploymentBundle> {
   const root = normalizeAppRoot(appRoot)
   const { commitHash, files, assets, config } = await readBranchFiles(
@@ -351,6 +380,22 @@ export async function buildBranchDeployment(
     revision,
     writeAsset,
   )
+  const normalizedRuntimeConfig = normalizeRuntimeConfig(runtimeConfig)
+  if (normalizedRuntimeConfig) {
+    const bytes = new TextEncoder().encode(
+      deploymentRuntimeConfigSource(normalizedRuntimeConfig),
+    )
+    const asset: Omit<DeploymentAsset, "etag"> = {
+      path: RUNTIME_CONFIG_ASSET_PATH,
+      sourcePath: null,
+      contentType: "application/javascript; charset=utf-8",
+      size: bytes.byteLength,
+    }
+    const etag = writeAsset
+      ? await writeAsset(asset, bytes)
+      : await computeAssetEtag(bytes)
+    assets.push({ ...asset, etag })
+  }
   if (Object.keys(files).length === 0) {
     throw new Error(
       root
@@ -364,17 +409,40 @@ export async function buildBranchDeployment(
     return {
       branch: revision ?? branch,
       commitHash,
-      mainModule: result.mainModule,
-      modules: result.modules,
-      assets,
+      workerModules: {
+        mainModule: result.mainModule,
+        modules: result.modules,
+        compatibilityDate: result.compatibilityDate,
+      },
+      staticAssets: assets,
       assetConfig: result.assetConfig,
-      compatibilityDate: result.compatibilityDate,
+      runtimeConfig: normalizedRuntimeConfig,
     }
   } catch (e) {
     throw new Error(`Build failed: ${e instanceof Error ? e.message : String(e)}`)
   }
 }
 
+function normalizeRuntimeConfig(
+  config: DeploymentRuntimeConfig | undefined,
+): DeploymentRuntimeConfig | undefined {
+  if (!config) return undefined
+  let url: URL
+  try {
+    url = new URL(config.apiBaseUrl)
+  } catch {
+    throw new Error("runtimeConfig.apiBaseUrl must be an absolute HTTP(S) URL ending in /")
+  }
+  if (!["http:", "https:"].includes(url.protocol) || !url.pathname.endsWith("/")) {
+    throw new Error("runtimeConfig.apiBaseUrl must be an absolute HTTP(S) URL ending in /")
+  }
+  return { apiBaseUrl: url.toString() }
+}
+
+export function deploymentRuntimeConfigSource(config: DeploymentRuntimeConfig): string {
+  return `globalThis.__APP_CONFIG__=Object.freeze(${JSON.stringify(config)});`
+}
+
 async function buildWebsite(
   sourceFiles: Record<string, string>,
   config: ParsedWranglerConfig,
@@ -463,7 +531,7 @@ function toAssetPath(path: string, directory: string): string {
 
 async function computeAssetEtag(bytes: Uint8Array): Promise<string> {
   const digest = await crypto.subtle.digest("SHA-256", exactBuffer(bytes))
-  return [...new Uint8Array(digest).slice(0, 8)]
+  return [...new Uint8Array(digest).slice(0, 16)]
     .map((byte) => byte.toString(16).padStart(2, "0"))
     .join("")
 }
@@ -490,7 +558,7 @@ async function getDeployment(
 
   const row = ctx.sql
     .exec(
-      `SELECT branch, commit_hash, main_module, modules, assets, asset_count,
+      `SELECT branch, commit_hash, main_module, modules, assets, asset_deployment_id, asset_count,
               asset_config, deployed_at
        FROM deployments WHERE branch = ?`,
       branch
@@ -503,6 +571,7 @@ async function getDeployment(
 
   const r = row[0]
   const legacyAssets = JSON.parse((r.assets as string) || "{}")
+  const assetDeploymentId = (r.asset_deployment_id as string) || ""
   return jsonResponse({
     branch: r.branch as string,
     commit_hash: r.commit_hash as string,
@@ -510,6 +579,9 @@ async function getDeployment(
     modules: JSON.parse(r.modules as string),
     has_assets: Number(r.asset_count ?? 0) > 0 || Object.keys(legacyAssets).length > 0,
     deployed_at: new Date(r.deployed_at as number).toISOString(),
+    asset_root: assetDeploymentId && ctx.assetPrefix
+      ? `${ctx.assetPrefix}/deployments/${assetDeploymentId}`
+      : null,
   })
 }
 

package/src/space/durable-object.ts

@@ -6,7 +6,9 @@ import {
   buildBranchDeployment,
   handleDeployCommand,
   type BranchDeploymentBundle,
+  type DeploymentRuntimeConfig,
   type DeployContext,
+  type SpaceDeploymentResult,
 } from "./deploy-engine"
 import { globInfos, readDirInfos, toFileInfo } from "./fileinfo"
 import {
@@ -1109,7 +1111,12 @@ 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, revision?: string): Promise<unknown> {
+  async deploy(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<SpaceDeploymentResult> {
     await this.ensureInit()
     return this.lane(async () => {
       // The deploy engine reads the full branch tree, so ensure the Artifacts
@@ -1123,6 +1130,7 @@ export class SpaceDO extends DurableObject<Env>
           branch,
           ...(appRoot ? { appRoot } : {}),
           ...(revision ? { revision } : {}),
+          ...(runtimeConfig ? { runtimeConfig } : {}),
         }),
       })
       const ctx: DeployContext = {
@@ -1142,7 +1150,7 @@ export class SpaceDO extends DurableObject<Env>
 
       if (!revision) await this.backend.push(branch)
 
-      return data
+      return spaceDeploymentResult(data)
     })
   }
 
@@ -1150,6 +1158,7 @@ export class SpaceDO extends DurableObject<Env>
     branch: string,
     appRoot?: string,
     revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
   ): Promise<BranchDeploymentBundle> {
     await this.ensureInit()
     await this.materializeAll()
@@ -1162,6 +1171,8 @@ export class SpaceDO extends DurableObject<Env>
       branch,
       appRoot,
       revision,
+      undefined,
+      runtimeConfig,
     )
   }
 
@@ -1203,6 +1214,7 @@ export class SpaceDO extends DurableObject<Env>
       sql: this.ctx.storage.sql,
       git: this.git,
       fs: this.overlay,
+      assetPrefix: spaceR2Prefix(this.spaceName),
     }
     const res = await handleDeployCommand(ctx, "get_deployment", fakeRequest)
     return res.json()
@@ -1294,6 +1306,23 @@ export class SpaceDO extends DurableObject<Env>
       if (assetResponse) return assetResponse
     }
 
+    return this.serveDeploymentApp(branch, dep, request)
+  }
+
+  async serveApp(branch: string, request: Request): Promise<Response> {
+    await this.ensureInit()
+    const dep = this.readDeployment(branch)
+    if (!dep) {
+      return new Response(`No deployment found for branch "${branch}"`, { status: 404 })
+    }
+    return this.serveDeploymentApp(branch, dep, request)
+  }
+
+  private serveDeploymentApp(
+    branch: string,
+    dep: DeploymentRow,
+    request: Request,
+  ): Response | Promise<Response> {
     let appClass: DurableObjectClass
     try {
       appClass = this.loadAppClass(dep)
@@ -1610,6 +1639,29 @@ function byteLength(content: string): number {
   return new TextEncoder().encode(content).byteLength
 }
 
+function spaceDeploymentResult(data: Record<string, unknown>): SpaceDeploymentResult {
+  if (
+    typeof data.branch !== "string" ||
+    typeof data.commit_hash !== "string" ||
+    typeof data.main_module !== "string" ||
+    typeof data.has_assets !== "boolean" ||
+    typeof data.compatibility_date !== "string" ||
+    typeof data.deployed_at !== "string" ||
+    !(typeof data.asset_root === "string" || data.asset_root === null)
+  ) {
+    throw new Error("Invalid deployment result")
+  }
+  return {
+    branch: data.branch,
+    commit_hash: data.commit_hash,
+    main_module: data.main_module,
+    has_assets: data.has_assets,
+    compatibility_date: data.compatibility_date,
+    deployed_at: data.deployed_at,
+    asset_root: data.asset_root,
+  }
+}
+
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
 interface PatchEdit {

package/src/space/workspace-port.ts

@@ -1,3 +1,9 @@
+import type {
+  BranchDeploymentBundle,
+  DeploymentRuntimeConfig,
+  SpaceDeploymentResult,
+} from "./deploy-engine";
+
 /**
  * The production Workspace contract a Space must satisfy.
  *
@@ -234,11 +240,23 @@ export interface SpaceControlPort {
  * and only an explicit deploy brings an app into existence.
  */
 export interface SpaceAppPort {
-  deploy(branch: string, appRoot?: string, revision?: string): Promise<unknown>;
+  deploy(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<SpaceDeploymentResult>;
   undeploy(branch: string): Promise<unknown>;
   listDeployments(): Promise<unknown>;
   getDeployment(branch: string): Promise<unknown>;
+  getDeploymentBundle(
+    branch: string,
+    appRoot?: string,
+    revision?: string,
+    runtimeConfig?: DeploymentRuntimeConfig,
+  ): Promise<BranchDeploymentBundle>;
   servePreview(branch: string, request: Request): Promise<Response>;
+  serveApp(branch: string, request: Request): Promise<Response>;
   listAppTables(branch: string): Promise<unknown>;
   queryAppTable(branch: string, table: string, opts?: unknown): Promise<unknown>;
   wipeAppDatabase(branch: string): Promise<{ ok: true }>;