feat(workspace): owner-downloadable full-workspace zip export (#320)

[ikrasovytskyi]

What & why

StoryOS is a no-lock-in, Fibery-like tool — so a workspace owner should be able to take everything out. This adds an owner-facing full-workspace export as a single streamed .zip (#320).

Access control

Admin/owner only, gated exactly like the other owner-level actions:

GET /api/v1/workspaces/:ws/export/workspace.zip

@UseGuards(AuthGuard, WorkspaceAccessGuard) + @MinRole('admin') (a regular member/guest gets 403) + @RequiresScope('admin') for API tokens. An unknown workspace 404s (never leaks existence).

Format / folder layout

Documented in docs/architecture/workspace-export.md. Layout:

manifest.json                          # workspace meta, format version (1), timestamp, index of spaces/databases
spaces/<space-slug>/<database-slug>.json   # field SCHEMA (types + config + select options) + all records
relations.json                         # relation defs + links, by stable record id
attachments/<attachment-id>/<filename> # the actual attachment files

• Records carry values keyed by field id (the stable uuid, raw stored form — ADR-0002), plus title, number, timestamps, and an attachments[] array whose path points into attachments/.
• Relations are reconstructable from stable record ids: relations.json has the relation definitions (schema edges) and every { relation_id, from_record_id, to_record_id } link.
• Select values stay resolvable because each field's options[] are exported alongside it.
• Archive paths are sanitised (no separators/control chars/..) and de-duplicated — zip-slip safe.

A future import is intentionally left possible (stable uuid keys, schema-with-data, a format_version to gate on) but not built now.

Streaming

The .zip is built lazily with archiver: per-database JSON is streamed page-by-page (500 records at a time) and attachment bytes are pulled one at a time as the HTTP response is read — a large workspace is never buffered into memory. Structural metadata (spaces/databases/fields/relations/attachment metadata) is read eagerly; only record bytes and file bytes stream.

Attachments via the storage seam

Files are read through the shared getStorage() abstraction (MN-029), so the export works identically on a local-disk (ATTACHMENTS_DIR) or an S3/MinIO (STORAGE_DRIVER=s3) deployment. A missing object (deleted underneath the export) is skipped rather than aborting the whole archive.

Web

An admin-only Export section in workspace settings (/w/:ws/settings/export) with a streaming download link (a plain <a href>, credentials via cookie — same approach as the existing CSV export).

Migration

None.

Verified how

• Backend integration test (apps/api/test/workspace-export.test.ts): admin can export; a non-admin member is refused (403); unknown workspace 404s; the zip is unzipped in-test and asserted — manifest.json indexes the databases, each database file carries its field schema (incl. select options) and records with values, relations.json resolves the link to real record ids, and the attachment bytes round-trip byte-for-byte (local-disk storage driver).
• Full local CI green: lint, typecheck, test (1591 passed / 1 skipped), build, docs:check, pnpm install --frozen-lockfile. SDK regenerated + committed for the new endpoint.
• Interactive browser check NOT done — blocked by known issue #355 (better-auth useSession hang in split-origin dev; worktree lacks .env). Not fabricating a screenshot; the endpoint is covered by the integration test and the web bundle compiles (route /w/[ws]/settings/export built).

Follow-ups (not in this PR)

• Async/background export job for very large workspaces — v1 is a synchronous stream, which is acceptable but a background job (with a downloadable artifact) is the sensible next step.
• Broaden scope in a future format_version: views, standalone space documents, record rich-text document bodies, comments, activity history.

Closes #320.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	storyos-docs	02c98e3	Commit Preview URL Branch Preview URL	Jul 25 2026, 09:05 PM