Repository navigation
feat(state): keep engine state in state/<org>/ - #97
Closed
dhruva-vapi wants to merge 10 commits into
Closed
dhruva-vapi wants to merge 10 commits into
dhruva-vapi wants to merge 10 commits into
Conversation
Contributor
Author
dhruva-vapi
marked this pull request as ready for review
November 20, 2026 18:24
Everything the engine generates and tracks sat under dot-names in three places: .vapi-state.<org>.json, .vapi-state.<org>.snapshots/ and .vapi-state-hash/ at the repository root, and .vapi-org.json inside resources/<org>/. It now lives in state/<org>/: state.json and org.json are committed, local/baselines and local/snapshots stay on the machine. An older repository keeps working. Every command reads the old places. The next pull, push or apply on a person's machine moves the org, one rename per file, and prints one line. The move is held back in a CI run and while a workflow stages .vapi-state.*.json but not state/, because either would commit the old file's removal without the new file. The promotion workflow stages both places. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…to it Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
The guard that holds the move back looked for one known-bad pattern: a "git add" line naming .vapi-state. with none naming state. A commit step it couldn't read (a helper script, a commit action with a file pattern, a pipeline outside GitHub Actions) passed as safe. A command on a person's machine then moved state, and every later promotion run passed while state/<org>/state.json was never committed, so resources were created again as duplicates. The move now fails closed. State moves by itself only when a workflow is seen to stage state/, or when nothing in the repository commits state after a run: no workflow that can write to the repository, and no root promotion.yml. A CI run stops before any request when it would write state in a place its commit step isn't seen to stage. In GitHub Actions it reads the workflow that is running it. npm run migrate, where nothing is seen to stage state/, prints the two paths the commit step has to stage and moves nothing. A person who has updated their step says so with --commit-step-stages-state, which is recorded in state/commit-step.json. The engine can't check that word. Docs: what counts as seen, the limit of the flag, what a customer sees after upgrading, and how to go back to an older engine without creating duplicates. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
An org is in one layout, decided by where its committed state file is. Pull, push, apply and promote read and write the layout they find, on a person's machine and in CI, and print one line saying the newer one exists. npm run migrate is the only command that moves state, after saying what the commit step has to stage. The commit-step reader fails closed: a git add counts only as a plain command at the repository root that names state or stages everything. With nothing seen, migrate asks for --commit-step-stages-state. Pull no longer reads "edited since the last sync" off the state file's timestamp, which in a fresh clone is the order git wrote the files in. It compares against the moment this machine's engine last saved state, and a clone with no such save keeps every file. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
… files out of pull's local edits Running the test suite in a repository with a state file at its root removed the repository: two tests cleaned up two folders above the engine's baselines folder, and in the older layout that is the repository root. The engine's directory now comes from one place, src/base-dir.ts. The test preload points it at a temporary directory, makes every node:fs change inside the repository throw, and the engine refuses a test started without the preload. A new test runs the whole suite inside a copy of a customer-shaped repository in the older layout, in state/, and with no state, and compares every tracked, untracked and ignored file before and after. That run found one more writer, tests/org-connection.test.ts, which created tmp/ in the repository. Pull's keep rule for a file with no baseline is off whenever git shows a change under resources/<org>/. The engine's own files there (the org pin in the older layout, also shown as deleted between migrate and its commit) are no longer counted. A repository with no state whose commit step can't be read still gets its first state file at the root, and the command now says where the file goes, why, and what has to stage it. The upgrade guide gains one line: on a machine with no baselines, the first pull after upgrading can bring a dashboard edit down one pull late. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…gnores the test runner The engine refused to start when NODE_TEST_CONTEXT was in its environment without a sandbox, and the preload npm test adds sandboxed every test file. Node's test runner sets that variable for every process it starts, so an engine command started from a repository's own test exited 1, and such a test could no longer run the engine on its repository or write a file into it. Both worked before the sandbox existed. The sandbox is now a module, tests/engine-sandbox.ts, that every engine test file imports first: the temporary directory for the engine and the node:fs guard on the repository. It holds however the file is started, by hand without the preload included. tests/no-vapi-api.ts is what it was before the sandbox, and src/base-dir.ts never looks at the test runner's environment. A test file that doesn't import the module is left alone: the commands it starts and the engine modules it imports work in its repository, and it writes where it likes. In the engine's own repository (a runner whose GITHUB_REPOSITORY is VapiAI/gitops, or a clone whose origin is) a test file without the import fails the suite. In any other repository that check is skipped. tests/base-dir.test.ts fails when a module under src/ works out the repository's directory for itself. npm test no longer starts a test runner inside a test. The suite run inside copies of a customer-shaped repository, and the other tests that start a runner of their own, move to tests/repository/ and run with npm run test:repository, one file at a time, and as a CI job in the engine's own repository. A suite inside a suite tripled the time npm test took and reached the twenty-second limits some tests give a command sooner on a slow machine. Each copy now holds a test of the customer's own and runs the engine's test files only. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…sitory The check that every test file imports tests/engine-sandbox.ts first was also asked on a person's machine, wherever origin pointed at VapiAI/gitops. A repository cloned straight from the engine's keeps that origin, so a test of its owner's under tests/ made one engine test fail in npm test. Before the sandbox existed it passed. The check is now asked only where GITHUB_REPOSITORY is VapiAI/gitops, which is CI for the engine's own repository. A contributor who leaves the import out finds out on the pull request. GITHUB_REPOSITORY=VapiAI/gitops npm test asks it on a machine. Tests and docs only. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
devin-ai-integration
Bot
force-pushed
the
feat/state-folder
branch
from
November 21, 2026 03:54
f09aad2 to
69fb957
Compare
This was referenced Nov 21, 2026
Contributor
|
Replaced by #109 (same commits rebased onto main, opened as the Devin bot so it can be approved). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Value
V.A.L.U.E. tier: small. One folder, one module that knows the old and new layout, one command that moves, tests for every path, docs.
.vapi-state.<org>.json,.vapi-state.<org>.snapshots/and.vapi-state-hash/at the repository root, and.vapi-org.jsoninsideresources/<org>/next to the hand-written.vapi-ignore. They read as leftovers. Deleting the state file is silent until the next push, which then creates every resource again as a duplicate.How it works
state/<org>/.state.json(name → UUID) andorg.json(the org pin) are committed.local/baselines/andlocal/snapshots/stay on the machine and are gitignored.state/README.mdsays the engine writes the folder and what breaks when a file goes missing.resources/<org>/is hand-written only once an org has moved..vapi-ignorestays there, beside the resources it governs. The rule a person can apply at a glance:resources/is yours,state/is the engine's.pull,push,applyandpromoteread and write the layout they find, on a person's machine and in CI, for as long as the repository stays there. They print one line per command saying the newer layout exists.src/state-paths.tsis the one module that knows both layouts.npm run migratemoves committed state. A promotion or apply run writes the state file and a later step commits it. If that step stages only the old file, moved state drops out of git while every run still passes. Somigratefirst prints the two paths that step has to stage, then moves every org with one rename per file when every commit step in.github/workflows/is seen to stagestate/. Otherwise it moves nothing and says why.npm run migrate -- --commit-step-stages-staterecords it instate/commit-step.jsonand moves every org. The flag is refused while a workflow is seen to stage only the old file.git addcounts only as a plain command in arun:step at the repository root that namesstateor stages everything. After acd, under aworking-directory, after||, in a loop, a function or a quoted string, with-u, with a variable or an exclusion in its paths: not counted. Such a step may work. The engine can't tell, somigrateasks for the flag.state/under a step that stages only the old file or can't be read (and no recorded word), or state at the root under a step that stages onlystate/. In GitHub Actions the engine reads the workflow that is running it.applysends the merged change.state/, keeps the old copy identical, andmigrateremoves it.git addexits 128 on a pathspec that matches nothing.resources/<org>/. In the older layout the engine keeps the org pin there, and betweenmigrateand its commit git shows the pin as deleted. Pull now leaves out every file on the listmigratemoves, in both places, so a fresh clone still keeps a merged change.state/would never commit it, and the engine can't tell. So the command prints one line: where the file goes, why, what has to stage it, and how to start instate/instead.src/base-dir.ts. Every engine test file importstests/engine-sandbox.tsfirst, which points that at a temporary directory and makes everynode:fschange inside the repository throw, however the file is started. A test file that doesn't import it, such as one a repository built from this one keeps undertests/, is left alone: the commands it starts and the engine modules it imports work in its repository, and it writes where it likes. The engine never looks at what a test runner leaves in the environment, and the preloadnpm testadds is what it was before this pull request.npm teststarts no test runner inside a test. The tests that do, such as the suite run inside copies of a repository with every file compared, live intests/repository/. They run withnpm run test:repositoryand as a CI job that runs only in this repository.Upgrade notes:
docs/guides/commands.md, "Upgrading from an older version".Verification
Nothing here was run against a live org. Every behaviour is covered by tests against fixtures, a real git origin, or a local stub API.
tests/state-layout.test.tspullagainst a stub API leaves an old repository where it is and keeps every UUID mapping, on a person's machine and in CIstate/, this machine's baselines and snapshots follow. A baseline is still read from the old foldermigratefinishes itstate/is read and the old copy kept identical. Different content: stop, both files intact, no request senttests/state-layout-unseen-commit.test.tsstate/, where a step runs, and every job in every workflow having to passstate/commitsstate/when it is run for realmigrateprints the two paths and moves nothing until a step is seen or a person says so. The flag is refused under a workflow that stages only the old file, and writes nothing where it isn't neededstate/under a step that isn't seen, and when state is at the root under a step that stages onlystate/tests/state-move-second-round.test.tsgit addthat leavesstate/out (aftercd resources, in another job's folder, inside anecho) is not read as staging itstate/, a command that is notmigrateleaves committed state where it istests/promotion-workflow-commit.test.tsstate/and with no state, leaves every tracked, untracked and ignored file and.gitas it was. Each copy holds a test of the customer's owntests/repository/suite-leaves-the-repository.test.tstests/repository/suite-keeps-the-repository.test.tsNODE_TEST_CONTEXTin its environment. A repository's own test that runsvalidateon its repository, or writes a report into it, passes as it does on maintests/repository/engine-beside-a-test-runner.test.tsnpm testruns it: the command it starts validates its org, its report lands in the repository, and an engine module it imports works in that repositorytests/repository/own-tests-as-before.test.tssrc/a test runs somewhere elsetests/engine-sandbox.test.tsnpm teststarts a test runnerVapiAI/gitopsand nowhere else: not in a clone of it on a person's machine over https or ssh, not on a runner in a fork, in a fork that kept the name or in a repository that kept this origin, not without an origintests/repository/import-check.test.tssrc/works out the repository's directory for itself.src/user-agent.tsis the one exception: it reads the engine's own package.json for the version it sendstests/base-dir.test.tsmigrateand its commit. A person's own uncommitted file there still counts, as beforetests/state-records-third-round.test.tsstate/gets none, and once state exists the line is the older-layout one. One line per command, also through a realpulltests/first-state-file.test.tsEach rule was also checked by breaking it. 33 one-line mutations each fail a test that names the rule: 4 of the fresh-clone rule (a clone no longer keeps its files, the save time ignored, the stamp never written, the old copy not kept identical), 17 of the commit-step reader (a
git addcounted aftercd, after||, inside anifcondition, a loop or a function, with any flag, an exclusion or a variable, in a here-document, under aworking-directory, in a checkout sub-folder, under another shell orGIT_DIR, and the job rules), and 12 of the layout andmigraterules (a command moving state when the step is seen,migratemoving with nothing seen or whatever the gate says, a CI run not stopped, a new repository always instate/, a new org ignoring the others, the notice printed every time). Eight more for the rules added after that each fail a named test too: the engine's files counted as edits again, only thestate/paths left out, every file in the folder left out, the first-state line dropped, shortened, printed beside the older-layout line or printed in a repository that has state.Sixteen for the test sandbox were run on this head, and each fails a named test: the engine ignoring the test directory, or using it from a copy of
src/somewhere else; the write guard letting everything through or missing named imports; the sandbox not naming its repository; the engine refusing to start under a test runner; the preload sandboxing every test file; a test file dropping the import, undertests/ortests/repository/, or not importing it first; a test innpm teststarting a test runner; and the import check asked in every repository, in none, on any runner, in a clone whose origin is this repository, or missing a runner named in lower case.Outside the suite, a pipeline's own shell steps were run in a fresh clone per run against a bare origin and a recording stub of the API, with a checker comparing the origin's committed state with the platform after every run:
migratesends the same requests as main, line for line, under upstream's workflow, the pre-change workflow, a helper script, a read-only token, acdbefore thegit add, and three apply-on-merge pipelines (GitHub Actions, another CI system, and one whose script stages both layouts). No state file moves and nothing is left uncommitted.applyreaches the platform from a fresh clone, with state at the root and aftermigrate.migrateunder upstream's workflow the requests are the same as main and the move is committed whole.migratestops before any request.npm run buildpasses.npm testpasses 645/645 in CI (584 on main). On a person's machine one of those, the import check, is skipped.npm run test:repositorypasses 9/9.Things to know
--commit-step-stages-stateis a person's word and the engine can't check it. If it is passed and the commit step doesn't stagestate/, promotion runs pass while state is never committed, and a later run creates resources again. It is refused only when a workflow is plainly seen to stage the old file alone. The harness shows exactly this when the word is wrong..github/workflows/and nothing else. A pipeline in another CI system, or a script that commits with its own token, is never read. That is whymigratealways prints the two paths first.git add -u) needs the flag once.state/only where a commit step is seen or said to stage it. Anywhere else its first state file goes to the root, as before this change, and the command says so in one line. A script that stages onlystate/has to be told about with--commit-step-stages-statebefore the first pull, or that file is never committed.pullafter upgrading can bring a dashboard edit down one pull late. Nothing is lost. The upgrade notes say so.npm testtakes about what it took before, for what it runs. On one Mac in one window, back to back: 113 and 116 s on main (584 tests), 159 and 164 s here (645 tests). The tests that run the suite inside copies of a repository are innpm run test:repositoryand in a CI job of their own, which a fork's CI skips.GITHUB_REPOSITORY=VapiAI/gitops npm testasks it on a machine.state/aftermigratecreates duplicates unless the state files are moved back first. The steps are in the upgrade notes.<name>.<timestamp>.bkp.md) stay beside the resource they shadow, andtmp/promotion-applied.txtstays intmp/..env.<org>is unchanged.migrate, a change to the org pin no longer triggers the promotion workflow, because the pin leftresources/.