Goalmatic Source Sync for VS Code

Open a Goalmatic project in VS Code with one click, edit it with a local preview, and move changes through the project's real source authority without copying credentials.

One-click workflow

1. In Goalmatic, open a project and choose Source Sync → Open in VS Code.
2. VS Code exchanges the five-minute, single-use link for a site-scoped 90-day session stored in SecretStorage. No Firebase or browser API key is copied to the extension.
3. VS Code asks where to open the project. Reuse a detected checkout, choose any existing repository folder, or explicitly create a new clone. The selected folder is remembered for this site, and a new clone is never created silently.
4. Trust the chosen parent once. VS Code lets its project subfolders inherit that trust; Restricted Mode remains enabled for folders you have not approved.
5. Edit files. A normal package.json, yarn.lock, Vite, Vue, Tailwind CSS v4, yarn dev, editable goalmatic.seo.json, and asset manifest are included. The extension falls back to its bundled local renderer if Yarn is unavailable.
6. Open the Goalmatic Activity Bar icon and choose Sync Source. The extension commits local files, rebases onto the currently checked-out non-production branch, pushes it, then waits for Goalmatic to import that exact commit.
7. Use Pull Site Source to fast-forward the currently checked-out non-production branch.
8. main remains separate. For an App, publish an approved main commit through App Settings. A Git push never publishes the deployed App.

GitHub contributors do not need the extension. Clone the repository, run yarn install --frozen-lockfile and yarn dev, branch from preview, and target preview with the pull request. Feature branches stay isolated until selected in Site Builder or merged through GitHub; selecting one makes its exact commit the hosted editable working copy without publishing it.

If you opened a repository with VS Code's generic clone command, the extension detects .goalmatic/app.json and offers Prepare local App runtime. That action creates the missing local package and installs dependencies. Reopen the project from its Site Builder Git page when you also need secure preview sync.

If the same file changed both locally and online, the pull opens Resolve Goalmatic Conflicts instead of failing. Compare both versions side by side, keep the local file, use the online file, or open VS Code's native diff and edit a combined local result. The session survives restarts, replaced files are backed up, and local results remain clearly queued to sync.

Goalmatic sidebar

The native sidebar shows:

• direct local-preview state;
• expandable Goalmatic source changes with read-only baseline comparisons;
• persistent source conflicts with per-file resolution progress;
• current Git branch, working tree, and last commit;
• GitHub repository and sync mode;
• draft baseline and last pull.
• Workspace Trust, exact local path, dependency/runtime readiness, SEO, assets, and the last operation result.

Clicking a row opens the relevant workflow: preview opens localhost, Git opens Source Control, GitHub opens the repository or setup, and each changed file opens a read-only diff. In Git-authority projects, Sync Source owns the commit, rebase, push, and webhook-import sequence; the redundant Git-push action is hidden.

Safe by default

• The opaque, site-scoped session stays in VS Code SecretStorage and live site access is rechecked by the server on every request.
• .goalmatic/, dependencies, build output, binary files, and secret-like files never enter source sync.
• Git-authority pushes run local secret protection first. High-confidence credentials block the push, while warnings require an explicit review.
• Non-overlapping changes merge automatically; genuine same-file conflicts pause in a persistent resolver and never overwrite a choice silently.
• Replaced and remotely deleted files are recoverable from Git, .goalmatic/trash, and the conflict archive.
• Existing AGENTS.md, README.md, and Copilot instructions are never overwritten.
• Dependency installation only runs in a trusted workspace and uses the exact package manager declared by the project with install scripts disabled.
• Binary assets are copied locally for offline work, uploaded through a short-lived signed URL, and recorded in assets/goalmatic-assets.json; credentials never enter the project.
• Publishing is separate from saving and syncing. Store-gated Apps publish only through App Settings.

Development

npm install
npm run compile
npm run package

Open this extension folder in VS Code and press F5 to launch an Extension Development Host.