@springbrand/space 0.1.0-alpha.1

package/src/space/fileinfo.ts

@@ -0,0 +1,117 @@
+/**
+ * FileInfo adapter for the plain `FileSystem` interface.
+ *
+ * The SpaceDO overlay used to be a `Workspace`, whose listing methods returned
+ * rich `FileInfo` records (mimeType, updatedAt, size). The in-memory overlay
+ * only implements the minimal `FileSystem` contract (`glob` -> string[], `stat`
+ * -> `FsStat`), so these helpers rebuild `FileInfo` from a path + `FsStat`:
+ * MIME is inferred from the extension and timestamps come from `mtime`.
+ */
+import type { FileSystem, FileInfo, FsStat } from "@cloudflare/shell"
+
+const MIME_BY_EXT: Record<string, string> = {
+  html: "text/html",
+  htm: "text/html",
+  css: "text/css",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  cjs: "text/javascript",
+  jsx: "text/javascript",
+  ts: "text/typescript",
+  tsx: "text/typescript",
+  json: "application/json",
+  jsonc: "application/json",
+  map: "application/json",
+  txt: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  xml: "application/xml",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  eot: "application/vnd.ms-fontobject",
+  wasm: "application/wasm",
+  pdf: "application/pdf",
+  zip: "application/zip",
+  webmanifest: "application/manifest+json",
+  mp3: "audio/mpeg",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  ogg: "audio/ogg",
+}
+
+const DEFAULT_MIME = "application/octet-stream"
+const DIR_MIME = "inode/directory"
+
+function basename(path: string): string {
+  const i = path.lastIndexOf("/")
+  return i >= 0 ? path.slice(i + 1) : path
+}
+
+/** Infer a MIME type from a path's extension, defaulting to octet-stream. */
+export function inferMimeType(path: string): string {
+  const name = basename(path)
+  const dot = name.lastIndexOf(".")
+  if (dot <= 0) return DEFAULT_MIME
+  return MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? DEFAULT_MIME
+}
+
+/** Build a `FileInfo` from a path and its `FsStat`. */
+export function toFileInfo(path: string, stat: FsStat): FileInfo {
+  const ms = stat.mtime.getTime()
+  return {
+    path,
+    name: basename(path),
+    type: stat.type,
+    mimeType: stat.type === "file" ? inferMimeType(path) : DIR_MIME,
+    size: stat.size,
+    createdAt: ms,
+    updatedAt: ms,
+  }
+}
+
+/** `glob` + `stat` each match into a `FileInfo[]` (skips paths that vanish). */
+export async function globInfos(fs: FileSystem, pattern: string): Promise<FileInfo[]> {
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`
+  const paths = await fs.glob(normalizedPattern)
+  const infos: FileInfo[] = []
+  for (const p of paths) {
+    try {
+      infos.push(toFileInfo(p, await fs.stat(p)))
+    } catch {
+      // Raced against a concurrent delete, or unreadable — skip.
+    }
+  }
+  return infos
+}
+
+/** List a directory's immediate children as `FileInfo[]`, with offset/limit. */
+export async function readDirInfos(
+  fs: FileSystem,
+  dir?: string,
+  opts?: { limit?: number; offset?: number },
+): Promise<FileInfo[]> {
+  const base = !dir || dir === "/" ? "/" : dir.startsWith("/") ? dir : "/" + dir
+  const entries = await fs.readdirWithFileTypes(base)
+  const infos: FileInfo[] = []
+  for (const e of entries) {
+    const full = base === "/" ? "/" + e.name : base + "/" + e.name
+    try {
+      infos.push(toFileInfo(full, await fs.stat(full)))
+    } catch {
+      // skip unreadable entry
+    }
+  }
+  const offset = opts?.offset ?? 0
+  return opts?.limit !== undefined ? infos.slice(offset, offset + opts.limit) : infos.slice(offset)
+}

package/src/space/fs-backend.ts

@@ -0,0 +1,235 @@
+import {
+  createWorkspaceStateBackend,
+  FileSystemStateBackend,
+  InMemoryFs,
+  Workspace,
+  WorkspaceFileSystem,
+  type FileSystem,
+} from "@cloudflare/shell"
+import { createGit, type Git } from "@cloudflare/shell/git"
+import type { Env } from "../env"
+import { ArtifactsFileSystem } from "./artifacts-fs"
+import { ArtifactsSync, type ArtifactsRemoteStore } from "./artifacts-sync"
+import { CheckpointStore } from "./checkpoint"
+import { createArtifactsBaseSource } from "./git-objects"
+
+export const ARTIFACTS_REMOTE_URL_KEY = "artifacts:remoteUrl"
+export const SPACE_FS_BACKEND_KEY = "space:fsBackend"
+const ARTIFACTS_BASE_BRANCH = "main"
+const ARTIFACTS_INIT_TIMEOUT_MS = 10_000
+const CHECKPOINT_DEBOUNCE_MS = 2_000
+
+export type SpaceFsBackendMode = "artifacts" | "sql"
+
+export async function resolveSpaceFsBackendMode(
+  storage: Pick<DurableObjectStorage, "get" | "put" | "sql">,
+  env: Pick<Env, "ENABLE_ARTIFACTS" | "ARTIFACTS">,
+): Promise<SpaceFsBackendMode> {
+  let mode = await storage.get<SpaceFsBackendMode>(SPACE_FS_BACKEND_KEY)
+  if (mode) return mode
+
+  const priorArtifacts = (await storage.get<string>(ARTIFACTS_REMOTE_URL_KEY)) !== undefined
+  let hasCheckpoint = false
+  try {
+    hasCheckpoint = storage.sql.exec("SELECT 1 FROM space_checkpoint LIMIT 1").toArray().length > 0
+  } catch {}
+  const artifactsEnabled = env.ENABLE_ARTIFACTS === "true" && !!env.ARTIFACTS
+  mode = priorArtifacts || hasCheckpoint || artifactsEnabled ? "artifacts" : "sql"
+  await storage.put(SPACE_FS_BACKEND_KEY, mode)
+  return mode
+}
+
+export interface SpaceFsBackend {
+  readonly fs: FileSystem
+  readonly overlay: FileSystem
+  readonly git: Git
+  readonly stateBackend: FileSystemStateBackend
+  ready(): Promise<void>
+  hydrate(path: string): Promise<void>
+  materializeAll(): Promise<void>
+  flushCheckpoint(): Promise<void>
+  push(branch: string): Promise<boolean>
+  fetch(branch: string): Promise<void>
+}
+
+function isReservedPath(path: string): boolean {
+  return path === "/.git" || path.startsWith("/.git/") || path === "/.afs" || path.startsWith("/.afs/")
+}
+
+async function withTimeout<T>(operation: Promise<T>, timeoutMs: number): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error("Operation timed out")), timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timeout) clearTimeout(timeout)
+  }
+}
+
+export class ArtifactsBackend implements SpaceFsBackend {
+  readonly overlay: FileSystem
+  readonly fs: FileSystem
+  readonly git: Git
+  readonly stateBackend: FileSystemStateBackend
+  private readonly remoteStore: ArtifactsRemoteStore
+  private readonly checkpointStore: CheckpointStore
+  private readonly checkpointDirty = new Set<string>()
+  private checkpointTimer: ReturnType<typeof setTimeout> | null = null
+  private artifactsSync?: ArtifactsSync
+
+  constructor(
+    ctx: DurableObjectState,
+    private readonly env: Env,
+    private readonly repoName: string,
+  ) {
+    if (!env.ARTIFACTS) throw new Error("SpaceDO is pinned to Artifacts but the ARTIFACTS binding is unavailable")
+
+    const overlay = new InMemoryFs()
+    this.overlay = overlay
+    this.remoteStore = {
+      read: () => ctx.storage.get<string>(ARTIFACTS_REMOTE_URL_KEY).then((value) => value ?? null),
+      write: (url) => ctx.storage.put(ARTIFACTS_REMOTE_URL_KEY, url).then(() => undefined),
+    }
+    const fetchSync = new ArtifactsSync(env.ARTIFACTS, createGit(overlay), repoName, this.remoteStore)
+    const source = createArtifactsBaseSource({
+      overlay,
+      branch: ARTIFACTS_BASE_BRANCH,
+      hasRemote: async () => (await this.remoteStore.read()) !== null,
+      fetchBranch: async () => {
+        try {
+          return await withTimeout(fetchSync.fetch(ARTIFACTS_BASE_BRANCH), ARTIFACTS_INIT_TIMEOUT_MS)
+        } catch {
+          return false
+        }
+      },
+    })
+    this.checkpointStore = new CheckpointStore(ctx.storage)
+    this.fs = new ArtifactsFileSystem(overlay, {
+      source,
+      branch: ARTIFACTS_BASE_BRANCH,
+      checkpoint: this.checkpointStore,
+      onChange: (path) => this.noteCheckpointDirty(path),
+    })
+    this.git = createGit(this.fs)
+    this.stateBackend = new FileSystemStateBackend(overlay)
+  }
+
+  async ready(): Promise<void> {
+    try {
+      await (this.fs as ArtifactsFileSystem).ready()
+    } catch {
+      // Base fetch failed this time — proceed with whatever is local.
+    }
+  }
+
+  async hydrate(path: string): Promise<void> {
+    await (this.fs as ArtifactsFileSystem).hydrate(path)
+  }
+
+  async materializeAll(): Promise<void> {
+    await (this.fs as ArtifactsFileSystem).whenFullyMaterialized()
+  }
+
+  async flushCheckpoint(): Promise<void> {
+    if (this.checkpointDirty.size === 0) return
+    const paths = [...this.checkpointDirty]
+    this.checkpointDirty.clear()
+    for (const path of paths) {
+      try {
+        if (await this.overlay.exists(path)) {
+          const stat = await this.overlay.stat(path)
+          if (stat.type !== "directory") this.checkpointStore.save(path, await this.overlay.readFileBytes(path))
+        } else {
+          this.checkpointStore.save(path, null)
+        }
+      } catch (error) {
+        console.warn(`Checkpoint flush failed for ${path}`, error)
+      }
+    }
+  }
+
+  async push(branch: string): Promise<boolean> {
+    const pushed = await this.getArtifactsSync().push(branch)
+    if (pushed) this.resetCheckpointAfterPush()
+    return pushed
+  }
+
+  async fetch(branch: string): Promise<void> {
+    await this.getArtifactsSync().fetch(branch)
+  }
+
+  private noteCheckpointDirty(path: string): void {
+    if (isReservedPath(path)) return
+    this.checkpointDirty.add(path)
+    if (this.checkpointTimer !== null) return
+    this.checkpointTimer = setTimeout(() => {
+      this.checkpointTimer = null
+      void this.flushCheckpoint()
+    }, CHECKPOINT_DEBOUNCE_MS)
+  }
+
+  private resetCheckpointAfterPush(): void {
+    try {
+      this.checkpointStore.clear()
+      void this.flushCheckpoint()
+    } catch (error) {
+      console.warn("Checkpoint reset after push failed", error)
+    }
+  }
+
+  private getArtifactsSync(): ArtifactsSync {
+    if (this.artifactsSync) return this.artifactsSync
+    this.artifactsSync = new ArtifactsSync(this.requireArtifacts(), this.git, this.repoName, this.remoteStore)
+    return this.artifactsSync
+  }
+
+  private requireArtifacts(): Artifacts {
+    const artifacts = this.env.ARTIFACTS
+    if (!artifacts) throw new Error("SpaceDO is pinned to Artifacts but the ARTIFACTS binding is unavailable")
+    return artifacts
+  }
+}
+
+/** Where a Space's spilled bytes live, kept apart from Attachment Content. */
+export function spaceR2Prefix(spaceId: string): string {
+  return `spaces/v1/${spaceId}`
+}
+
+export class SqlBackend implements SpaceFsBackend {
+  readonly overlay: FileSystem
+  readonly fs: FileSystem
+  readonly git: Git
+  readonly stateBackend: FileSystemStateBackend
+  readonly workspace: Workspace
+
+  /**
+   * Large files spill to R2 rather than to the DO's own SQLite. A Space holds
+   * spreadsheets, PDFs and images, any one of which can exceed what a SQLite
+   * row will hold — and a Space that fills its DO storage stops accepting
+   * writes for every other file too.
+   */
+  constructor(ctx: DurableObjectState, repoName: string, r2?: R2Bucket) {
+    const workspace = new Workspace({
+      sql: ctx.storage.sql,
+      name: () => repoName,
+      ...(r2 ? { r2, r2Prefix: spaceR2Prefix(repoName) } : {}),
+    })
+    this.workspace = workspace
+    const fs = new WorkspaceFileSystem(workspace)
+    this.overlay = fs
+    this.fs = fs
+    this.git = createGit(fs)
+    this.stateBackend = createWorkspaceStateBackend(workspace)
+  }
+
+  async ready(): Promise<void> {}
+  async hydrate(_path: string): Promise<void> {}
+  async materializeAll(): Promise<void> {}
+  async flushCheckpoint(): Promise<void> {}
+  async push(_branch: string): Promise<boolean> { return false }
+  async fetch(_branch: string): Promise<void> {}
+}

package/src/space/git-objects.ts

@@ -0,0 +1,315 @@
+/**
+ * Object-level git plumbing for `ArtifactsFileSystem`.
+ *
+ * The shell's `createGit` only exposes porcelain (commit/log/checkout/…), not
+ * object reads. `ArtifactsFileSystem` needs to (a) walk a fetched commit tree
+ * to build its base snapshot and (b) read individual blobs by oid to hydrate
+ * files on demand. This module wraps isomorphic-git's object APIs over a shell
+ * `FileSystem`, reusing the same fs adapter shape the shell uses so behavior
+ * (ENOENT dispatch, utf8/binary reads) matches `createGit`.
+ */
+import * as git from "isomorphic-git"
+import type { FileSystem } from "@cloudflare/shell"
+
+/** Metadata for one file in the Artifacts base tree. */
+export interface BaseEntry {
+  oid: string
+  mode: number
+  /** Byte size, or `undefined` until first computed (lazily, on demand). */
+  size?: number
+}
+
+/** A loaded base tree: the commit it came from plus its files. */
+export interface BaseSnapshot {
+  head: string
+  files: Map<string, BaseEntry>
+}
+
+export interface BaseSnapshotSource {
+  /**
+   * The base tree (head commit + absolute-path -> entry map), or `null` when no
+   * base is available (the FileSystem then behaves as a plain overlay).
+   * Implementations must ensure blobs are locally readable via `readBlob`.
+   *
+   * `null` means "legitimately empty" (no remote repo/branch yet). A transient
+   * failure (network blip, fetch timeout) must THROW instead, so callers can
+   * retry on a later access rather than caching an empty base forever.
+   */
+  loadSnapshot(): Promise<BaseSnapshot | null>
+  /** Raw bytes of a blob by oid (from the local object store). */
+  readBlob(oid: string): Promise<Uint8Array>
+}
+
+/** Node `fs.Stats`-shaped object that isomorphic-git expects from stat/lstat. */
+class GitStat {
+  private readonly type: "file" | "directory" | "symlink"
+  readonly size: number
+  readonly mtimeMs: number
+  readonly ctimeMs: number
+  readonly ino = 0
+  readonly uid = 0
+  readonly gid = 0
+  readonly dev = 0
+  readonly mode: number
+  constructor(stat: { type: "file" | "directory" | "symlink"; size: number; mtime: Date; mode?: number }) {
+    this.type = stat.type
+    this.size = stat.size
+    this.mtimeMs = stat.mtime.getTime()
+    this.ctimeMs = this.mtimeMs
+    this.mode =
+      stat.mode ?? (this.type === "directory" ? 16877 : this.type === "symlink" ? 40960 : 33188)
+  }
+  isFile() {
+    return this.type === "file"
+  }
+  isDirectory() {
+    return this.type === "directory"
+  }
+  isSymbolicLink() {
+    return this.type === "symlink"
+  }
+}
+
+interface CodedError extends Error {
+  code: string
+}
+
+/** Ensure a thrown error carries a `.code` isomorphic-git can dispatch on. */
+function fsError(path: string, cause: unknown): CodedError {
+  if (cause instanceof Error && "code" in cause && typeof (cause as CodedError).code === "string") {
+    return cause as CodedError
+  }
+  const err = new Error(cause instanceof Error ? cause.message : `ENOENT: ${path}`) as CodedError
+  err.code = "ENOENT"
+  return err
+}
+
+/**
+ * Build an isomorphic-git compatible fs (`{ promises: { … } }`) from a shell
+ * `FileSystem`. Mirrors `@cloudflare/shell`'s internal adapter so object reads
+ * behave exactly like `createGit`'s.
+ */
+export function createGitFs(fs: FileSystem): git.FsClient {
+  return {
+    promises: {
+      async readFile(path: string, options?: string | { encoding?: string }) {
+        const encoding = typeof options === "string" ? options : options?.encoding
+        try {
+          if (encoding === "utf8" || encoding === "utf-8") return await fs.readFile(path)
+          return await fs.readFileBytes(path)
+        } catch (err) {
+          throw fsError(path, err)
+        }
+      },
+      async writeFile(path: string, data: string | Uint8Array) {
+        const parent = path.replace(/\/[^/]+$/, "")
+        if (parent && parent !== "/" && parent !== path) {
+          try {
+            await fs.mkdir(parent, { recursive: true })
+          } catch {
+            // parent may already exist
+          }
+        }
+        if (typeof data === "string") await fs.writeFile(path, data)
+        else await fs.writeFileBytes(path, data)
+      },
+      async unlink(path: string) {
+        try {
+          await fs.rm(path)
+        } catch (err) {
+          throw fsError(path, err)
+        }
+      },
+      async readdir(path: string) {
+        return fs.readdir(path)
+      },
+      async mkdir(path: string, mode?: { recursive?: boolean }) {
+        const recursive = typeof mode === "object" ? Boolean(mode.recursive) : false
+        await fs.mkdir(path, { recursive })
+      },
+      async rmdir(path: string) {
+        await fs.rm(path)
+      },
+      async stat(path: string) {
+        try {
+          return new GitStat(await fs.stat(path))
+        } catch (err) {
+          throw fsError(path, err)
+        }
+      },
+      async lstat(path: string) {
+        try {
+          return new GitStat(await fs.lstat(path))
+        } catch (err) {
+          throw fsError(path, err)
+        }
+      },
+      async readlink(path: string) {
+        try {
+          return await fs.readlink(path)
+        } catch (err) {
+          throw fsError(path, err)
+        }
+      },
+      async symlink(target: string, path: string) {
+        await fs.symlink(target, path)
+      },
+      async chmod() {
+        // no-op: the Workspace FS does not track unix modes
+      },
+    },
+  } as git.FsClient
+}
+
+/** Resolve a ref (branch, remote-tracking ref, or oid) to a commit oid, or null. */
+export async function resolveHead(fs: FileSystem, ref: string): Promise<string | null> {
+  try {
+    return await git.resolveRef({ fs: createGitFs(fs), dir: "/", ref })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Walk the tree of `commitOid`, returning every file as an absolute-path ->
+ * `BaseEntry` map. Does not read blob contents (fast, index-only); `size` is
+ * left undefined and computed lazily on demand.
+ */
+export async function walkTreeFiles(
+  fs: FileSystem,
+  commitOid: string,
+): Promise<Map<string, BaseEntry>> {
+  const gitFs = createGitFs(fs)
+  const entries = (await git.walk({
+    fs: gitFs,
+    dir: "/",
+    trees: [git.TREE({ ref: commitOid })],
+    map: async (filepath, walkerEntries) => {
+      if (filepath === ".") return undefined
+      const entry = walkerEntries?.[0]
+      if (!entry) return undefined
+      if ((await entry.type()) !== "blob") return undefined
+      return {
+        path: "/" + filepath,
+        oid: await entry.oid(),
+        mode: await entry.mode(),
+      }
+    },
+  })) as Array<{ path: string; oid: string; mode: number }>
+
+  const map = new Map<string, BaseEntry>()
+  for (const e of entries) {
+    if (!e) continue
+    map.set(e.path, { oid: e.oid, mode: e.mode })
+  }
+  return map
+}
+
+/** Read a blob's bytes by oid from the local object store. */
+export async function readBlobBytes(fs: FileSystem, oid: string): Promise<Uint8Array> {
+  const { blob } = await git.readBlob({ fs: createGitFs(fs), dir: "/", oid })
+  return blob
+}
+
+/**
+ * Point the local branch at the fetched head when it is unborn (the cold-start
+ * case). isomorphic-git's `fetch` only updates the remote-tracking ref, so
+ * without this the next commit after a restart would be a ROOT commit with no
+ * ancestry — and the mirrored `push(force)` would replace the remote branch,
+ * silently destroying all earlier history/restore points. An existing local
+ * branch is never clobbered: local commits must not be lost.
+ */
+async function reconcileLocalBranch(
+  fs: FileSystem,
+  branch: string,
+  head: string,
+): Promise<void> {
+  if (await resolveHead(fs, `refs/heads/${branch}`)) return
+  await git.writeRef({
+    fs: createGitFs(fs),
+    dir: "/",
+    ref: `refs/heads/${branch}`,
+    value: head,
+    force: true,
+  })
+}
+
+/**
+ * Artifacts-backed `BaseSnapshotSource`: fetches the branch into the overlay's
+ * `.git` (via the injected `fetchBranch`, e.g. `ArtifactsSync.fetch`), then
+ * walks the fetched commit tree and serves blobs from the local object store.
+ */
+export function createArtifactsBaseSource(opts: {
+  overlay: FileSystem
+  branch: string
+  /** True when a remote repo is known to exist (e.g. a persisted remote URL). */
+  hasRemote: () => Promise<boolean>
+  /** Populate the overlay `.git` with the branch's objects. Returns success. */
+  fetchBranch: () => Promise<boolean>
+}): BaseSnapshotSource {
+  const { overlay, branch, hasRemote, fetchBranch } = opts
+  return {
+    async loadSnapshot() {
+      // No remote repo yet — a legitimately empty base (fresh app).
+      if (!(await hasRemote())) return null
+      // The repo exists but the fetch failed — transient. Throw so the caller
+      // retries on a later access instead of caching an empty base (which
+      // would hide every previously pushed file for this DO's lifetime).
+      if (!(await fetchBranch())) {
+        throw new Error(`Artifacts base fetch failed for branch "${branch}"`)
+      }
+      const head =
+        (await resolveHead(overlay, `refs/remotes/artifacts/${branch}`)) ??
+        (await resolveHead(overlay, branch))
+      // Repo exists but this branch has no commits yet — legitimately empty.
+      if (!head) return null
+      await reconcileLocalBranch(overlay, branch, head)
+      return { head, files: await walkTreeFiles(overlay, head) }
+    },
+    readBlob(oid) {
+      return readBlobBytes(overlay, oid)
+    },
+  }
+}
+
+/**
+ * Drop the git index so the next status walk re-reads file contents.
+ *
+ * Git decides a file is unchanged when its size and modification time still
+ * match the index, and only hashes it otherwise. On a real filesystem that is
+ * a safe shortcut; here it is not. A Space's files live in memory or SQLite,
+ * where an agent can rewrite a file to different content of the same length
+ * within the same millisecond — and git would then see nothing to commit. The
+ * work would be in the Space but absent from every version of it.
+ *
+ * The index is pure cache: deleting it costs one re-hash of the tree and
+ * cannot lose anything.
+ */
+async function discardIndexStatCache(fs: FileSystem): Promise<void> {
+  try {
+    await fs.rm("/.git/index", { force: true })
+  } catch {
+    // No index yet, or the backend refused; the status walk still works.
+  }
+}
+
+/**
+ * Stage the whole working tree (like the shell's `git add .`, which also
+ * stages deletions via `statusMatrix`) while skipping reserved paths — the
+ * `.afs` bookkeeping file must never enter a commit, or it lands in the
+ * Artifacts base tree and pollutes every snapshot.
+ */
+export async function stageWorkdir(
+  fs: FileSystem,
+  skip: (absPath: string) => boolean,
+): Promise<void> {
+  const gitFs = createGitFs(fs)
+  await discardIndexStatCache(fs)
+  const matrix = await git.statusMatrix({ fs: gitFs, dir: "/" })
+  for (const [filepath, head, workdir, stage] of matrix) {
+    if (skip(`/${filepath}`)) continue
+    if (`${head}${workdir}${stage}` === "111") continue
+    if (workdir === 0) await git.remove({ fs: gitFs, dir: "/", filepath })
+    else await git.add({ fs: gitFs, dir: "/", filepath })
+  }
+}