Home Mac app guides Migrations GUI

Migrations GUI

Last updated on Jul 12, 2026

Purpose

The Migrations module integrates local Fireway migration files with Firestore migration records. It helps users inspect migration status, source contents, record pending migrations as applied when an external migration runner has already executed them, execute pending migration source against Firebase emulators, and verify environment alignment before any execution workflow is used.

Inputs

  • linked local workspace path
  • Fireway migration files
  • configured migration collection
  • selected project/database
  • Firestore migration records

Outputs

  • TABLE: migration status rows
  • JSON: raw migration records and file metadata
  • LOGS: local file, Firestore, parse, and comparison logs

Actions

Current GUI coverage includes listing status, source file content, a record-only "Record Pending As Applied" workflow, and an emulator-only "Execute Pending (Emulator)" workflow. The record-only action writes migration records for pending local files through the task queue; it does not execute Fireway source code.

GUI source execution is emulator-only. It runs pending Fireway-compatible JavaScript through the task queue, applies emitted Firestore mutations to the selected Firestore emulator, records migration state, refreshes status rows, and keeps rollback notes/logs visible. Production/live execution must not be claimed until approved live verification proves the workflow and guardrails.

Use this module when a release or support session needs to answer four questions before running any migration tooling: which local files exist, which Firestore migration records exist, which files appear unapplied, and which project/database is being inspected. Keeping those details in one view reduces the risk of comparing local development files against the wrong Firebase environment.

The source preview is intentionally part of the workflow. Review the migration body, file name, identifier, and remote record together before recording a pending file as applied or using the emulator execution path. If a record is missing or mismatched, use the logs output to determine whether the issue came from local file discovery, workspace-link configuration, Firestore access, or migration collection setup.

Safety

  • Recording migrations as applied is Pro-gated.
  • Read-only projects reject record-applied state writes before any task is queued.
  • Production record-applied state writes require explicit confirmation.
  • Record-applied state writes run through Tasks and surface task logs/progress.
  • Migration source execution is GUI-available for emulator projects only.
  • Non-emulator source execution rejects before task enqueue.
  • Source file content and remote records should be visible before recording state or using the emulator execution path.

Current Verification

  • MigrationWorkflowCopyTests/testMigrationWorkflowCopyDistinguishesInspectRecordAndExecute proves the GUI-facing labels distinguish status inspection, record-only state writes, emulator-only source execution, and live execution boundaries.
  • MigrationWorkflowCopyTests/testProductionRecordAppliedGuardUsesRecordOnlyWording proves production confirmation rejection uses record-applied state-write wording and does not queue logs before confirmation.
  • MigrationWorkflowCopyTests/testProductionRecordAppliedPromptNamesStateWriteNotExecution proves the production prompt says the action does not execute migration source.
  • MigrationWorkflowCopyTests/testReadOnlyRecordAppliedRejectsBeforeQueueingTask proves read-only GUI record-applied requests stop before task enqueue.
  • MigrationWorkflowCopyTests/testGUIRecordAppliedWritesPendingMigrationRecordThroughTaskQueueAgainstEmulator proves the GUI/AppModel record-applied action queues a task against real Firebase emulators, writes the migration record, refreshes applied status, records rollback notes/logs, and reads back the emulator document.
  • MigrationWorkflowCopyTests/testGUIExecutePendingMigrationSourceWritesEmulatorMutationAndRecord proves the GUI/AppModel source-execution action queues a task against real Firebase emulators, runs Fireway-compatible JavaScript, applies the emitted Firestore mutation, records migration state, refreshes applied status, and reads back both the script-written emulator document and migration record.
  • MigrationWorkflowCopyTests/testNonEmulatorMigrationExecuteRejectsBeforeQueueingTask proves GUI source execution rejects non-emulator projects before task enqueue.
  • FirestructCLIIntegrationTests/testCLICommandsRoundTripAgainstFirebaseEmulators proves emulator-backed migration status, record-applied record-only writes, and emulator-only JS apply execution with Firestore mutation and migration-record read-back evidence.

Source Anchors

  • Sources/FirestructApp/Features/Migrations/UI/MigrationExplorerView.swift
  • Sources/FirestructApp/Features/Migrations/Services/AppModel+MigrationActions.swift
  • Sources/FirestructApp/Features/Migrations/Model/MigrationStore.swift
  • Sources/FirestructApp/Features/Migrations/Model/MigrationWorkflowCopy.swift
  • Sources/FirestructCore/FirewayIntegrationService.swift
  • Sources/FirestructCore/ProjectRegistry+Migrations.swift