Home Mac app guides Workspace Link GUI

Workspace Link GUI

Last updated on Jul 12, 2026

Purpose

Workspace Link associates a Firestruct project with a local Firebase workspace. It lets users view local project configuration, inspect rules/index files, diff local vs remote state, and prepare guarded deploy prep/dry-run command-shape workflows.

Inputs

  • local workspace path
  • firebase.json
  • .firebaserc
  • Firestore rules and indexes
  • Storage rules where configured
  • selected Firebase project

Actions

Users can:

  • link a local workspace path
  • inspect workspace files
  • view rules/index contents
  • compare local configuration against remote project state
  • prepare task-backed deploy dry-run/real-deploy command shapes with explicit confirmation when enabled

The module is useful before any rules or indexes change because it keeps local files, Firebase aliases, selected project metadata, and remote state in the same review surface. A user should be able to see which checkout is linked, which Firebase project will be affected, and what differs before deciding whether a deploy is appropriate.

Diff views should favor deterministic output over interpretation. Show the local file path, remote resource, changed sections, missing files, parse errors, and any Firebase API errors separately so a developer can fix local config or permissions without guessing which layer failed. Current diff cards surface a machine-readable reason label and diagnostics for local missing files, remote missing state, content changes, malformed firestore.indexes JSON, and remote credential/API failures. Firebase Rules and Firestore Indexes REST failures should name the service, HTTP status, backend message, and access-token/IAM remediation hint.

Safety

  • Workspace link persistence is Pro-gated.
  • Deploy is Pro-gated.
  • Real deploys reject read-only projects before queueing work.
  • Production real deploys require explicit typed confirmation.
  • Production deploys must label target project/environment clearly.
  • Deploy operations must run through Tasks and expose errors.

Current Verification

  • WorkspaceLinkRemoteServiceTests/testWorkspaceConfigDiffServiceClassifiesMissingAndParseStates covers deterministic diff reasons for remote-missing, local-missing, both-missing, and parse-error states.
  • WorkspaceLinkRemoteServiceTests/testFetchDeployedConfigSurfacesActionableCredentialAndAPIErrors covers actionable Firebase Rules and Firestore Indexes REST failure logs.
  • FirestructCLIIntegrationTests/testWorkspaceLinkCLIInspectsAndDiffsLocalFirebaseWorkspace covers local workspace link/status/diff output against a real temporary Firebase workspace and explicit comparison files.
  • WorkspaceDeployTaskTests/testWorkspaceDryRunDeployQueuesTaskAndCapturesCLIOutput covers the macOS dry-run deploy task path, task counters, command shape, and captured output through a deterministic command runner.
  • WorkspaceDeployTaskTests/testWorkspaceDryRunDeployFailureCapturesCommandAndFirebaseOutput covers failed dry-run task output, preserving the exact Firebase CLI command, stdout JSON, stderr text, and zero processed operations in app errors/logs.
  • WorkspaceDeployTaskTests/testWorkspaceRealDeployRequiresProAccessBeforeQueueingTask, testWorkspaceRealDeployRejectsReadOnlyProjectBeforeQueueingTask, and testWorkspaceProductionRealDeployRequiresTypedConfirmationBeforeQueueingTask cover real deploy guardrails before task enqueue or CLI execution.
  • A local 2026-06-26 real Firebase CLI dry-run attempt against demo-firestruct reached Firebase and returned project-not-found JSON; this validates failure-output capture but is not successful dry-run proof. Real successful Firebase CLI dry-run output against a valid local workspace/project and approved live deploy proof remain open before deploy completion can be claimed.

Source Anchors

  • Sources/FirestructApp/Features/WorkspaceLink/UI/WorkspaceLinkView.swift
  • Sources/FirestructApp/Features/WorkspaceLink/Services/AppModel+WorkspaceLinkActions.swift
  • Sources/FirestructApp/Features/WorkspaceLink/Model/WorkspaceLinkStore.swift
  • Sources/FirestructCore/WorkspaceLinkRemoteService.swift
  • Sources/FirestructCore/WorkspaceLinkRemoteService+Operations.swift
  • Sources/FirestructCore/ProjectRegistry+WorkspaceServices.swift