@springbrand/space 0.1.0-alpha.1

package/src/space/inspector-wrapper.ts

@@ -0,0 +1,141 @@
+// ─── Inspector wrapper module ──────────────────────────────────────────────
+//
+// The DB-viewer tab needs to read SQL from the user's App Durable Object,
+// but the Facet's storage is fully isolated from the supervisor (SpaceDO).
+// The only way to read it is via methods on the App class itself.
+//
+// Rather than asking the LLM to paste ~60 lines of inspector boilerplate
+// into every app, we inject a small wrapper module into the dynamic
+// worker. The wrapper:
+//   1. imports the user's App class,
+//   2. re-exports every other named export unchanged,
+//   3. exports a subclass `App` (shadowing the user's) that extends the
+//      user's App and adds `__vibeInspectListTables` / `__vibeInspectRead`.
+//
+// SpaceDO loads this wrapper as the main module and `getDurableObjectClass
+// ("App")` returns the subclass. The subclass shares the user's `ctx`,
+// `ctx.storage`, and any state — so the inspector reads the same SQLite
+// database the user's App writes to.
+
+export const VIBE_APP_MODULE = "__vibe_app__.js"
+
+/**
+ * Build the wrapper source. `userMainModule` is the key in `modules`
+ * holding the LLM's compiled main (which must `export class App
+ * extends DurableObject`).
+ */
+export function buildInspectorWrapperSource(userMainModule: string): string {
+  return `import * as __vibeUserModule from ${JSON.stringify(userMainModule)}
+
+// Re-export everything from the user's module first. We then shadow the
+// \`App\` export below with the subclass.
+export * from ${JSON.stringify(userMainModule)}
+
+const __VIBE_UserApp = __vibeUserModule.App
+if (typeof __VIBE_UserApp !== "function") {
+  throw new Error(
+    "Your main module must export a class named \`App\` extending DurableObject. " +
+    "See the cloudflare-bundler-apps skill for the required app structure."
+  )
+}
+
+const __VIBE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const __VIBE_MAX_PAGE_SIZE = 200
+
+function __vibeIsSafeIdentifier(name) {
+  return typeof name === "string" && __VIBE_IDENT_RE.test(name)
+}
+
+function __vibeQuote(name) {
+  return '"' + String(name).replace(/"/g, '""') + '"'
+}
+
+export class App extends __VIBE_UserApp {
+  async __vibeInspectListTables() {
+    const sql = this.ctx.storage.sql
+    const tableRows = sql.exec(
+      "SELECT name FROM sqlite_master " +
+      "WHERE type = 'table' " +
+      "  AND name NOT LIKE 'sqlite_%' " +
+      "  AND name NOT LIKE '_cf_%' " +
+      "ORDER BY name"
+    ).toArray()
+    const out = []
+    for (const row of tableRows) {
+      const name = row.name
+      if (!__vibeIsSafeIdentifier(name)) continue
+      const columns = sql.exec(
+        "PRAGMA table_info(" + __vibeQuote(name) + ")"
+      ).toArray().map((c) => ({
+        name: c.name, type: c.type, notnull: c.notnull, pk: c.pk,
+      }))
+      let rowCount = 0
+      try {
+        const cnt = sql.exec(
+          "SELECT COUNT(*) AS c FROM " + __vibeQuote(name)
+        ).one()
+        rowCount = Number(cnt.c)
+      } catch {
+        rowCount = 0
+      }
+      out.push({ name, rowCount, columns })
+    }
+    return out
+  }
+
+  async __vibeInspectRead(table, opts) {
+    opts = opts || {}
+    if (!__vibeIsSafeIdentifier(table)) {
+      throw new Error("Invalid table name: " + table)
+    }
+    const sql = this.ctx.storage.sql
+    const exists = sql.exec(
+      "SELECT COUNT(*) AS c FROM sqlite_master WHERE type='table' AND name = ?",
+      table
+    ).one().c
+    if (!exists) throw new Error("Unknown table: " + table)
+    const columns = sql.exec(
+      "PRAGMA table_info(" + __vibeQuote(table) + ")"
+    ).toArray().map((c) => c.name)
+    const limit = Math.max(1, Math.min(__VIBE_MAX_PAGE_SIZE, opts.limit || 50))
+    const offset = Math.max(0, opts.offset || 0)
+    let orderClause = ""
+    if (opts.orderBy) {
+      if (!columns.includes(opts.orderBy)) {
+        throw new Error("Unknown column: " + opts.orderBy)
+      }
+      const dir = opts.orderDir === "desc" ? "DESC" : "ASC"
+      orderClause = " ORDER BY " + __vibeQuote(opts.orderBy) + " " + dir
+    }
+    const totalCount = Number(sql.exec(
+      "SELECT COUNT(*) AS c FROM " + __vibeQuote(table)
+    ).one().c)
+    const rows = sql.exec(
+      "SELECT * FROM " + __vibeQuote(table) + orderClause + " LIMIT ? OFFSET ?",
+      limit, offset
+    ).toArray()
+    return { columns, rows, totalCount }
+  }
+
+  async __vibeWipe() {
+    // Drop every user table. The next request recreates whatever
+    // CREATE TABLE IF NOT EXISTS the App runs on startup.
+    const sql = this.ctx.storage.sql
+    const tableRows = sql.exec(
+      "SELECT name FROM sqlite_master " +
+      "WHERE type = 'table' " +
+      "  AND name NOT LIKE 'sqlite_%' " +
+      "  AND name NOT LIKE '_cf_%'"
+    ).toArray()
+    this.ctx.storage.transactionSync(() => {
+      for (const row of tableRows) {
+        const name = row.name
+        if (!__vibeIsSafeIdentifier(name)) continue
+        sql.exec("DROP TABLE IF EXISTS " + __vibeQuote(name))
+      }
+    })
+    return { ok: true }
+  }
+}
+`
+}

package/src/space/preview-headers.ts

@@ -0,0 +1,38 @@
+// Preview response security.
+//
+// All Think previews share one browser origin (path-based on the preview
+// domain). A generated app must not be able to emit response headers that grant
+// it authority over that shared origin. Most importantly Service-Worker-Allowed
+// lets a service worker widen its scope to "/" - allowing one app's SW to
+// intercept every other user's previews. We also drop Clear-Site-Data (could
+// wipe other users' preview cookies) and Service-Worker-Navigation-Preload.
+
+export const STRIPPED_PREVIEW_HEADERS = [
+  "Service-Worker-Allowed",
+  "Service-Worker-Navigation-Preload",
+  "Clear-Site-Data",
+] as const
+
+export function stripPreviewSecurityHeaders(response: Response): Response {
+  // WebSocket upgrade responses cannot be reconstructed (no body, immutable
+  // headers); they never carry these headers, so pass them through untouched.
+  if (response.status === 101 || response.headers.get("upgrade")?.toLowerCase() === "websocket") {
+    return response
+  }
+
+  const headers = new Headers(response.headers)
+  let changed = false
+  for (const name of STRIPPED_PREVIEW_HEADERS) {
+    if (headers.has(name)) {
+      headers.delete(name)
+      changed = true
+    }
+  }
+  if (!changed) return response
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

package/src/space/workspace-port.ts

@@ -0,0 +1,245 @@
+/**
+ * The production Workspace contract a Space must satisfy.
+ *
+ * Upstream SpaceDO shipped the file surface VibeSDK's Think tools needed:
+ * text reads that throw, string-only writes and unpaginated listings. A complete
+ * Agent Runtime needs binary writes for XLSX and images, append,
+ * conditional writes for Sandbox publishing, quota, and the full set of file
+ * operations — so this module states the contract once and the Durable Object
+ * implements it verbatim.
+ *
+ * The names and semantics deliberately match `WorkspacePort` in
+ * `@springbrand/agent-runtime`: one file capability, not two competing ones.
+ */
+
+/** Metadata for a single Space directory entry. */
+export interface SpaceFileInfo {
+  path: string;
+  name: string;
+  type: "file" | "directory" | "symlink";
+  mimeType: string;
+  size: number;
+  createdAt: number;
+  updatedAt: number;
+  target?: string;
+}
+
+/**
+ * A file's identity at a point in time.
+ *
+ * Size plus modification time, because that is what both the Space backends and
+ * the Sandbox adapter can observe without hashing every published byte.
+ */
+export interface SpaceFileVersion {
+  updatedAt: number;
+  size: number;
+}
+
+export type SpaceConditionalWriteResult =
+  | { written: true; version: SpaceFileVersion }
+  | { written: false; reason: "conflict"; current: SpaceFileVersion | null };
+
+export interface SpaceUsage {
+  fileCount: number;
+  directoryCount: number;
+  totalBytes: number;
+}
+
+export interface SpaceQuota {
+  maxFiles: number | null;
+  maxTotalBytes: number | null;
+  maxFileBytes: number | null;
+}
+
+/** One Space Git commit, as the host's revision history reads it. */
+export interface SpaceCommit {
+  revision: string;
+  treeHash: string;
+  reason: string;
+  createdAt: number;
+}
+
+export interface SpaceCommitManifest {
+  revision: string;
+  treeHash: string;
+  files: readonly { path: string; size: number }[];
+}
+
+/**
+ * Paths a Space owns and callers may never write.
+ *
+ * `.git` and `.afs` are the Git object store and the Artifacts overlay's
+ * bookkeeping; a caller that could write them could rewrite history.
+ */
+export const SPACE_RESERVED_PREFIXES = ["/.git", "/.afs"] as const;
+
+/**
+ * Paths that persist in the Space but never enter a Git commit.
+ *
+ * A Space holds working data as well as deliverables: scratch files, installed
+ * dependencies and hydrated attachments are large, regenerable and worthless in
+ * history. Committing them would put multi-megabyte blobs into every revision.
+ */
+export const SPACE_UNVERSIONED_PREFIXES = [
+  "/.git",
+  "/.afs",
+  "/tmp",
+  "/node_modules",
+] as const;
+
+const DEFAULT_QUOTA: SpaceQuota = Object.freeze({
+  maxFiles: 20_000,
+  maxTotalBytes: 2 * 1024 * 1024 * 1024,
+  maxFileBytes: 256 * 1024 * 1024,
+});
+
+export function defaultSpaceQuota(): SpaceQuota {
+  return { ...DEFAULT_QUOTA };
+}
+
+export function isReservedSpacePath(path: string): boolean {
+  return SPACE_RESERVED_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  );
+}
+
+export function isUnversionedSpacePath(path: string): boolean {
+  return SPACE_UNVERSIONED_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  );
+}
+
+/**
+ * Reduce a caller-supplied path to a canonical absolute Space path.
+ *
+ * Traversal is rejected rather than resolved: a caller writing `../` means
+ * either a bug or an escape attempt, and silently clamping it to the root turns
+ * both into a file quietly landing somewhere the caller did not name.
+ */
+export function normalizeSpacePath(path: string): string {
+  if (typeof path !== "string") throw new Error("Space path must be a string");
+  const value = path.trim().replaceAll("\\", "/");
+  const parts = value.split("/").filter(Boolean);
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error("Space path traversal is not allowed");
+  }
+  return `/${parts.join("/")}`;
+}
+
+/** As `normalizeSpacePath`, and refuses paths the Space owns. */
+export function normalizeWritableSpacePath(path: string): string {
+  const normalized = normalizeSpacePath(path);
+  if (isReservedSpacePath(normalized)) {
+    throw new Error("Space metadata is not writable");
+  }
+  if (normalized === "/") throw new Error("The Space root is not a file");
+  return normalized;
+}
+
+/**
+ * Normalize a glob pattern without destroying its wildcards.
+ *
+ * `normalizeSpacePath` would reject `**` never, but it also collapses the empty
+ * segments a caller may rely on; patterns are therefore only anchored, and the
+ * traversal check is kept.
+ */
+export function normalizeSpacePattern(pattern: string): string {
+  if (typeof pattern !== "string") throw new Error("Space pattern must be a string");
+  const value = pattern.trim().replaceAll("\\", "/");
+  const parts = value.split("/").filter(Boolean);
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error("Space path traversal is not allowed");
+  }
+  return `/${parts.join("/")}`;
+}
+
+export function toBytes(data: Uint8Array | ArrayBuffer): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+
+export function versionOf(info: SpaceFileInfo | null): SpaceFileVersion | null {
+  return info?.type === "file" ? { updatedAt: info.updatedAt, size: info.size } : null;
+}
+
+/**
+ * The file capability the Agent Runtime consumes, method-for-method.
+ *
+ * Declared here so a compile error — not a production 500 — is what happens
+ * when the Durable Object and the runtime contract drift apart.
+ */
+export interface SpaceWorkspacePort {
+  readFile(path: string): Promise<string | null>;
+  readFileBytes(path: string): Promise<Uint8Array | null>;
+  writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+  writeFileBytes(
+    path: string,
+    data: Uint8Array | ArrayBuffer,
+    mimeType?: string,
+  ): Promise<void>;
+  appendFile(path: string, content: string, mimeType?: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<SpaceFileInfo | null>;
+  lstat(path: string): Promise<SpaceFileInfo | null>;
+  mkdir(path: string, opts?: { recursive?: boolean }): Promise<void>;
+  readDir(
+    dir?: string,
+    opts?: { limit?: number; offset?: number },
+  ): Promise<SpaceFileInfo[]>;
+  rm(path: string, opts?: { recursive?: boolean; force?: boolean }): Promise<void>;
+  cp(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void>;
+  mv(src: string, dest: string, opts?: { recursive?: boolean }): Promise<void>;
+  symlink(target: string, linkPath: string): Promise<void>;
+  readlink(path: string): Promise<string>;
+  glob(pattern: string): Promise<SpaceFileInfo[]>;
+}
+
+/**
+ * Everything a Space does that is not a file operation.
+ *
+ * Git, deployment, preview and the App database live here rather than beside
+ * the file methods so a caller holding a Workspace cannot reach them by
+ * accident, and so the runtime's contract stays exactly the file surface.
+ */
+export interface SpaceControlPort {
+  writeFileBytesIfUnchanged(
+    path: string,
+    data: Uint8Array,
+    mimeType: string,
+    expected: SpaceFileVersion | null,
+  ): Promise<SpaceConditionalWriteResult>;
+  getUsage(): Promise<SpaceUsage>;
+  getQuota(): Promise<SpaceQuota>;
+  commit(reason: string, prefix?: string): Promise<{
+    revision: string | null;
+    treeHash: string | null;
+    changed: boolean;
+  }>;
+  listCommits(prefix: string, limit?: number): Promise<readonly SpaceCommit[]>;
+  currentCommit(prefix: string): Promise<SpaceCommit | null>;
+  commitManifest(prefix: string, revision: string): Promise<SpaceCommitManifest>;
+  readCommitFile(prefix: string, revision: string, path: string): Promise<Uint8Array>;
+  restorePathsFromCommit(
+    prefix: string,
+    revision: string,
+    reason: string,
+  ): Promise<{ revision: string; treeHash: string }>;
+  destroySpace(): Promise<void>;
+}
+
+/**
+ * Turning a Space into a running application.
+ *
+ * Separate from the file and history surface because most Spaces never use it:
+ * a Space holding a spreadsheet and a script is complete without any of this,
+ * and only an explicit deploy brings an app into existence.
+ */
+export interface SpaceAppPort {
+  deploy(branch: string, appRoot?: string): Promise<unknown>;
+  undeploy(branch: string): Promise<unknown>;
+  listDeployments(): Promise<unknown>;
+  getDeployment(branch: string): Promise<unknown>;
+  servePreview(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 }>;
+}

package/src/space/wrangler-config.ts

@@ -0,0 +1,188 @@
+// ─── Wrangler Config Parser ──────────────────────────────────────────────────
+// Parses the child project's wrangler.toml / wrangler.json / wrangler.jsonc
+// to extract deployment-relevant configuration.
+
+export interface ParsedDurableObjectBinding {
+  name: string
+  className: string
+}
+
+export interface ParsedWranglerConfig {
+  main?: string
+  compatibilityDate?: string
+  compatibilityFlags?: string[]
+  assets?: {
+    directory?: string
+    binding?: string
+    htmlHandling?: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"
+    notFoundHandling?: "single-page-application" | "404-page" | "none"
+  }
+  /**
+   * Durable Object bindings declared by the child project (Tier-2 apps).
+   * Each binding must reference a SQLite-backed class exported from `main`.
+   * `script_name`-style externals and KV-backed (`new_classes`) DOs are
+   * rejected upstream of the parser so we keep this shape minimal.
+   */
+  durableObjects?: ParsedDurableObjectBinding[]
+}
+
+export class WranglerConfigError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "WranglerConfigError"
+  }
+}
+
+/**
+ * Try to parse wrangler config from a set of project files.
+ * Checks wrangler.json, wrangler.jsonc, then wrangler.toml.
+ */
+export function parseWranglerConfig(files: Record<string, string>): ParsedWranglerConfig {
+  const jsonContent = files["wrangler.json"] ?? files["wrangler.jsonc"]
+  if (jsonContent) return parseJsonConfig(jsonContent)
+
+  const tomlContent = files["wrangler.toml"]
+  if (tomlContent) return parseTomlConfig(tomlContent)
+
+  return {}
+}
+
+function parseJsonConfig(content: string): ParsedWranglerConfig {
+  // Strip single-line comments for jsonc support
+  const stripped = content.replace(/^\s*\/\/.*$/gm, "")
+  const raw = JSON.parse(stripped)
+
+  const cfg: ParsedWranglerConfig = {}
+  if (typeof raw.main === "string") cfg.main = raw.main
+  if (typeof raw.compatibility_date === "string") cfg.compatibilityDate = raw.compatibility_date
+  if (Array.isArray(raw.compatibility_flags)) cfg.compatibilityFlags = raw.compatibility_flags
+
+  if (raw.assets && typeof raw.assets === "object") {
+    cfg.assets = {}
+    if (typeof raw.assets.directory === "string") cfg.assets.directory = raw.assets.directory
+    if (typeof raw.assets.binding === "string") cfg.assets.binding = raw.assets.binding
+    if (typeof raw.assets.html_handling === "string") cfg.assets.htmlHandling = raw.assets.html_handling
+    if (typeof raw.assets.not_found_handling === "string") cfg.assets.notFoundHandling = raw.assets.not_found_handling
+  }
+
+  // ── Durable Objects (Tier 2) ───────────────────────────────────
+  const dos = parseDurableObjectsJson(raw)
+  if (dos && dos.length > 0) cfg.durableObjects = dos
+
+  return cfg
+}
+
+function parseDurableObjectsJson(raw: any): ParsedDurableObjectBinding[] | undefined {
+  const block = raw?.durable_objects
+  if (!block || typeof block !== "object") return undefined
+  const bindings = block.bindings
+  if (!Array.isArray(bindings) || bindings.length === 0) return undefined
+
+  // Collect the set of class names allowed by migrations.
+  const sqliteClasses = new Set<string>()
+  const nonSqliteClasses = new Set<string>()
+  const migrations = Array.isArray(raw.migrations) ? raw.migrations : []
+  for (const m of migrations) {
+    if (!m || typeof m !== "object") continue
+    if (Array.isArray(m.new_sqlite_classes)) {
+      for (const c of m.new_sqlite_classes) {
+        if (typeof c === "string") sqliteClasses.add(c)
+      }
+    }
+    if (Array.isArray(m.new_classes)) {
+      for (const c of m.new_classes) {
+        if (typeof c === "string") nonSqliteClasses.add(c)
+      }
+    }
+  }
+
+  const result: ParsedDurableObjectBinding[] = []
+  for (const b of bindings) {
+    if (!b || typeof b !== "object") continue
+    if (typeof b.script_name === "string") {
+      throw new WranglerConfigError(
+        `Durable Object binding "${b.name ?? "?"}" uses script_name. ` +
+        `Generated apps cannot reference Durable Objects from other scripts.`,
+      )
+    }
+    const name = typeof b.name === "string" ? b.name : null
+    const className = typeof b.class_name === "string" ? b.class_name : null
+    if (!name || !className) {
+      throw new WranglerConfigError(
+        `Durable Object binding must have both "name" and "class_name".`,
+      )
+    }
+    if (nonSqliteClasses.has(className)) {
+      throw new WranglerConfigError(
+        `Durable Object class "${className}" uses new_classes (KV storage). ` +
+        `Generated apps must declare it under new_sqlite_classes instead.`,
+      )
+    }
+    if (!sqliteClasses.has(className)) {
+      throw new WranglerConfigError(
+        `Durable Object class "${className}" is not declared in migrations.new_sqlite_classes. ` +
+        `Add a migration tag with new_sqlite_classes: ["${className}"].`,
+      )
+    }
+    result.push({ name, className })
+  }
+
+  return result
+}
+
+function parseTomlConfig(content: string): ParsedWranglerConfig {
+  const cfg: ParsedWranglerConfig = {}
+
+  // Top-level fields (before any [section])
+  cfg.main = extractTomlString(content, "main", true)
+  cfg.compatibilityDate = extractTomlString(content, "compatibility_date", true)
+
+  const flags = extractTomlArray(content, "compatibility_flags", true)
+  if (flags) cfg.compatibilityFlags = flags
+
+  // [assets] section
+  const assetsSection = extractTomlSection(content, "assets")
+  if (assetsSection) {
+    cfg.assets = {}
+    cfg.assets.directory = extractTomlString(assetsSection, "directory")
+    cfg.assets.binding = extractTomlString(assetsSection, "binding")
+    cfg.assets.htmlHandling = extractTomlString(assetsSection, "html_handling") as ParsedWranglerConfig["assets"] extends { htmlHandling?: infer T } ? T : never
+    cfg.assets.notFoundHandling = extractTomlString(assetsSection, "not_found_handling") as ParsedWranglerConfig["assets"] extends { notFoundHandling?: infer T } ? T : never
+  }
+
+  // TOML DO parsing is intentionally not supported; the space skill
+  // tells the LLM to use wrangler.json (the file the bundler emits). If
+  // a TOML config declares DOs, we surface a clear error so the user
+  // knows to switch to JSON.
+  if (/\[\[durable_objects\.bindings\]\]/.test(content)) {
+    throw new WranglerConfigError(
+      "Durable Object bindings in wrangler.toml are not supported. " +
+      "Use wrangler.json instead.",
+    )
+  }
+
+  return cfg
+}
+
+// ─── TOML Helpers (minimal, field-specific) ──────────────────────────────────
+
+function extractTomlSection(content: string, name: string): string | undefined {
+  const pattern = new RegExp(`^\\[${name}\\]\\s*\\n((?:(?!^\\[)[^\\n]*\\n?)*)`, "m")
+  const match = content.match(pattern)
+  return match?.[1]
+}
+
+function extractTomlString(content: string, key: string, topLevelOnly?: boolean): string | undefined {
+  // If topLevelOnly, only match before the first [section]
+  const scope = topLevelOnly ? content.split(/^\[/m)[0] : content
+  const pattern = new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m")
+  return scope.match(pattern)?.[1]
+}
+
+function extractTomlArray(content: string, key: string, topLevelOnly?: boolean): string[] | undefined {
+  const scope = topLevelOnly ? content.split(/^\[/m)[0] : content
+  const pattern = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`, "m")
+  const match = scope.match(pattern)?.[1]
+  if (!match) return undefined
+  return match.split(",").map(s => s.trim().replace(/^"|"$/g, "")).filter(Boolean)
+}