Stateory

Pick up development work on another computer with the context you left behind.

Getting started · Contributing · Development · Security

Stateory is a privacy-first IDE extension that records a filtered snapshot of your development context and synchronizes it between computers. It helps you see the device, branch, commit, uncommitted file names, environment differences, runtimes, and tools from your last session without uploading source code or secrets.

[!IMPORTANT] Stateory is pre-1.0. The extension works, but its data model and setup flow may change while the first public release is tested.

What Stateory syncs

Area	Included metadata
Project	Account-scoped repository fingerprint and display name
Git	Branch, commit, ahead/behind counts, and repository-relative changed file names
Environment	`.env*` file names, variable names, and one-way whole-file fingerprints
Device	Device name, IDE name/version, operating system, and installation identifier
Tooling	Detected runtimes, package managers, tools, and installed IDE extensions
Activity	Last-active time, active/idle state, and environment profile hash

Stateory never syncs source contents, diffs, terminal history, secrets, environment values, full local paths, or raw Git remotes. Every collected category can be previewed before sync, and Git/environment collection can be disabled independently.

Features

Resume work using the latest context from another registered device.
Match clones of the same Git repository without uploading the raw remote.
See staged, unstaged, untracked, and conflicted file names without transferring their contents.
Compare missing .env* files and variable names without exposing values.
Compare runtimes, tools, IDE extensions, and environment profiles.
Link an account through a one-time browser approval flow that returns to the requesting IDE.
Preview the exact allowlisted sync payload, pause collection, export local metadata, and delete local project data.
Develop and test the complete Firebase boundary locally with emulators.

Getting started

Requirements

Node.js 22
npm
Java JDK 21 for the Firestore emulator
A compatible desktop IDE that can run VS Code extensions

Run from source

git clone https://github.com/Llewellyn500/stateory.git
cd stateory
npm ci
npm --prefix functions ci

Create the local emulator configuration:

Copy-Item .env.example .env.local

On macOS or Linux, use cp .env.example .env.local instead. The example contains safe demo identifiers and does not grant access to the live Firebase project.

Open the repository in your IDE, press F5, and choose Run Extension. In the Extension Development Host, open the Stateory view or run a Stateory command from the Command Palette.

For browser account-linking and cloud-sync testing, start the Firebase emulators first:

npm run firebase:emulators

See the development guide for the complete emulator walkthrough, testing commands, VSIX packaging, and troubleshooting.

Validate a contribution

Install both dependency sets, then run the same check used by CI:

npm ci
npm --prefix functions ci
npm run validate

npm run validate checks the Functions boundary, type-checks and lints the extension and hosted page, builds both clients, and runs the IDE integration suite. The first integration run downloads an isolated IDE test runtime.

Privacy and security design

Stateory uses an account-scoped SHA-256 fingerprint of the normalized Git remote to match clones. The raw remote is never uploaded. All synced metadata passes through authenticated Cloud Functions, while Firestore rules deny direct client reads and writes.

During browser account linking:

The extension holds a high-entropy verifier in memory.
The browser receives only the public approval code and safe device details.
The public code and verifier are exchanged once.
Custom and ID tokens stay in memory.
Only the Firebase refresh token is stored in IDE Secret Storage.
Signing out removes the refresh token and downloaded remote contexts while retaining local metadata.

Read SECURITY.md before reporting a vulnerability. Never place service-account keys, refresh tokens, private keys, or Functions secrets in .env.local.

Project structure

Path	Purpose
`src/`	Extension state, collectors, Firebase client, UI, and tests
`functions/`	Authenticated Cloud Functions boundary and tests
`web/src/`	Hosted device-link page
`media/`	Source branding and generated extension/browser assets
`firestore.rules`	Deny-all direct client access policy
`docs/`	Contributor development and maintainer release guides
`.github/`	CI, issue forms, pull-request template, and ownership rules

Documentation

Development guide — setup, emulators, local testing, commands, and troubleshooting.
Maintainer guide — repository settings, Firebase deployment, live QA, packaging, and publishing.
Contributing — contribution workflow and privacy requirements.
Support — where to ask questions or report bugs.
Security policy — private vulnerability reporting.
Changelog — release history and unreleased work.

Current limitations

Automatic cross-device matching requires the same normalized Git remote and Firebase account.
Stateory reports uncommitted file names but does not transfer uncommitted code.
Commit objects still need to be pushed to a Git remote before another computer can fetch them.
Environment values must be copied through a trusted secret-sharing method.
Browser-hosted IDEs and separate native IDE adapters are not implemented yet.
Remote runtime/tool collection for SSH, WSL, containers, and Codespaces is planned for a later adapter phase.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, keep changes focused, and preserve Stateory's privacy boundaries. Questions and bug reports should use the repository issue forms.

Stateory for VS Code

Llewellyn Adonteng Paintsil