Version parity with CLI
@josephjclark is already working on this.
Since Aug 12, 2025.
- Dominant language
- Elixir
- Stars
- 296
- Forks
- 86
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 50
Description
An issue to establish version control between CLI and the App
I'm convinced this is needed for sync and sandboxes
As we change the shape of state.json and project.yaml (and I think we must!), we need a means of allowing the CLI to either sync safely with changing specs, or to throw an error with a clear warning.
What this boils down to is:
- We need a single definitive version of the state schema
- The version structure needs a version number
- All CLI requests must include a version number header
- ❌ CLI cannot pull from server if server is using a higher version.
- ✔️ CLI can pull from server is server uses a lower version. CLI must migrate the payload
- ✔️ CLI can push to server if server uses higher version. Server must migrate the payload
- ❌ CLI camnot push to server if server uses lower version.
I think this must apply to state.json and project.yaml formats. The two must be paired. I'd love to make state a simple superset of project.
It is tempting to think that some changes can be migrated. Like if Lightning adds support for a new feature, a CLI workflow which doesn't use that feature will start getting rejected by the server on pull (but push should be OK!)
The problem is we don't really know when a migration is trivial or complex, and the CLI doesn't know how to default keys its never seen before.
Github sync should be fairly robust as it'll update latest CLI each time. So it should maintain parity.
One other thing to consider is options. If we nest options under a key in the state file, we can add options without changing the schema version (or maybe just a minor bump)
I'd also consider dropping extraneous_property errors down to warnings, and just carrying any keys that are not understood. This might be OK in some circumstances. But is also incompatible with the idea of throwing if versions aren't compatible, so maybe not
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.