App Files And APIs

Use this skill when frontend code needs to read or write app files, inspect the current user, discover files by pattern, or call backend endpoints from the browser.

Core Frontend API Surface

The shared frontend runtime exposes authenticated backend helpers through space.api.

Current wrapped helpers include:

• await space.api.fileList(pathOrOptions, recursive?)
• await space.api.fileRead(pathOrFiles, encoding?)
• await space.api.fileWrite(pathOrFiles, content?, encoding?)
• await space.api.fileDelete(pathOrPaths)
• await space.api.fileCopy(pathOrEntries, toPath?)
• await space.api.fileMove(pathOrEntries, toPath?)
• await space.api.fileInfo(pathOrOptions)
• space.api.folderDownloadUrl(pathOrOptions)
• await space.api.gitHistoryList(pathOrOptions, limit?)
• await space.api.gitHistoryDiff(pathOrOptions, commitHash?, filePath?)
• await space.api.gitHistoryPreview(pathOrOptions, commitHash?, operation?, filePath?)
• await space.api.gitHistoryRollback(pathOrOptions, commitHash?)
• await space.api.gitHistoryRevert(pathOrOptions, commitHash?)
• await space.api.userSelfInfo()
• await space.api.call("endpoint_name", { method, query, body, headers, signal })

fileRead(...) accepts one logical path, one { path, encoding? } entry, or a files batch. The frontend wrapper now coalesces same-tick reads into one /api/file_read request and re-slices the returned files back to each caller, retrying individually when a combined batch fails so shorthand paths and optional missing-file reads still behave like standalone calls. Explicit batching is still best when you already have the file list, but small independent reads no longer fan out 1:1 by default.

fileWrite(...) still supports the simple replacement form fileWrite(path, content, encoding?), but object-form writes also support incremental updates: { path, content, operation: "append" }, { path, content, operation: "prepend" }, or { path, content, operation: "insert", line | before | after }. Insert writes accept exactly one anchor, use the first literal before or after match, treat line as a 1-based insertion point, and require utf8. Batch writes may set those fields per entry or once at the top level as defaults. Prefer these incremental write modes when you only need to add or place text instead of rereading and rewriting the whole file.

Use space.api.folderDownloadUrl(...) when the browser should trigger a regular authenticated folder download without buffering the ZIP file into frontend memory first.

When a UI needs user-visible download failure feedback without fetching the archive blob into memory, preflight the request with space.api.fileInfo(...) for files or space.api.call("folder_download", { method: "HEAD", query: { path } }) for folders before starting the browser download.

fileList(...) accepts { access: "write" } or { writableOnly: true } when discovery must be limited to writable paths. Use { gitRepositories: true, access: "write" } or space.api.call("file_paths", { method: "POST", body: { patterns: ["**/.git/"], gitRepositories: true, access: "write" } }) to discover writable local-history owner roots; the server returns paths such as L1/team/ and L2/alice/, not .git metadata.

gitHistoryList(...), gitHistoryDiff(...), gitHistoryPreview(...), gitHistoryRollback(...), and gitHistoryRevert(...) are available only when the backend runtime has CUSTOMWARE_GIT_HISTORY=true. They operate on writable owner roots such as ~, L2/<user>/, or L1/<group>/; list supports limit, offset, and fileFilter, preview returns affected files and optional operation-specific patches for travel or revert, diff reads one commit-file patch, rollback requires write permission and preserves ignored L2 auth files plus forward-travel refs, and revert creates a new inverse commit. The first-party #/time_travel page defaults to the authenticated user's ~ history and can switch to write-accessible L1 or L2 history roots through the repository picker.