Skip to content

Per-entity file storage format for git-backed workspaces (envs / collections / scripts) #148

Closed

Description

@thomas-stegemann

Why

For #58 + #147 to deliver real "git-native workspace" parity with Bruno, the workspace state needs to live as per-entity files, not as opaque bundles. Today:

  • Environments live as one big JSON blob (bowire_environments_shared → single file when persisted). Renaming one env or editing two of its vars produces a single-line diff that touches the whole blob.
  • Collections same shape — collections.json is a bundle.
  • Scripts (pre / post / assertion) are embedded as strings inside the method or collection JSON. Multi-line code as JSON-escaped strings is unreviewable.

Bruno's .bru model: each request is its own file (Login.bru), syntax-highlighted natively, diff-friendly, mergeable across PRs. We need the same shape.

Proposal — per-entity files under the workspace root

<workspaceRoot>/
  workspace.json                    # manifest (name, color, settings, schema version)
  environments/
    staging.json                    # one file per env; filename = name
    production.json
  globals.json                      # globals stays a single file (no per-key benefit)
  collections/
    payments/
      collection.json               # collection metadata
      Login.req.json                # one file per request
      RefundFlow.req.json
      pre-request.js                # collection-scope pre-script
      post-response.js
  scripts/
    Auth.Login.pre.js               # service.method scope
    Pets.GetById.post.js
    Pets.GetById.assert.js
  recordings/                       # already per-recording dir from #144
    <recordingId>/
  flows/
    payments-refund.flow.json
  trash/
    environments/...                # mirrors the live shape

Format choices

  • Pretty-printed JSON with deterministic key ordering (already done elsewhere).
  • Filenames mirror entity names, sanitised for path-safe characters. Renames in the UI rename the file.
  • Scripts as .js files, not JSON-escaped strings. Tools (editors, linters, code-review) work natively.
  • Trailing newline on every file so git doesn't flag "no newline at end of file".
  • Stable IDs still live inside each entity for cross-references (e.g. step.serviceId); filenames are operator-visible identity.

Migration

  • One-shot migration on first load when a workspace's storageRoot is set (or when the operator explicitly runs the migration via bowire workspace migrate-format).
  • Reads the legacy bundles, splits into per-file shape, leaves the bundles next to a .legacy suffix so a downgrade can still read them.
  • Marker workspace-format-version: 2 on the manifest prevents re-running.

Acceptance

  • Environments stored one file per env under environments/.
  • Globals stay as a single globals.json (justified — no per-key benefit).
  • Collections become a directory: collection.json for metadata + <requestName>.req.json per request.
  • Pre / post / assertion scripts saved as .js files (one per service.method or per collection).
  • Renaming an entity renames its file.
  • Deletes move the file to trash/<entity-type>/<name> with deletedAt metadata for the Uniform delete affordances on every list sidebar (single / multi-select / all) #143 trash bin.
  • Manifest carries workspaceFormatVersion; migration runs once + marks done.
  • Round-trip: read → write → diff produces zero bytes of change.

Composes with

Out of scope

  • .toml, YAML, or proprietary .bru-style DSL — JSON stays the format. The benefit is per-entity, not the syntax.
  • Symlink resolution / extends-other-workspace — too niche for v1.

Activity

  1. added a commit that references this issue on Jun 13, 2026
  2. thomas-stegemann commented on Jun 13, 2026

    @thomas-stegemann
    MemberAuthor

    Phase 1 shipped in eb2bf1c — see #196 for the Phase 2 acceptance:

    Phase 2 (runtime wiring of storageRoot in the workbench, full per-entity reader/writer with bundle→per-entity migration, FS-watch SSE + reconcile UI, secret-file merge at resolve time, .bowire.lock concurrent-writer guard) lives in #196 → v2.1.

  3. added a commit that references this issue on Jun 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    • Status
      Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions