diff --git a/.conductor/setup.sh b/.conductor/setup.sh index ffc2a84..5d94212 100755 --- a/.conductor/setup.sh +++ b/.conductor/setup.sh @@ -98,14 +98,15 @@ done shopt -u nullglob # --- 4. Copy state files ---------------------------------------------------- -# .vapi-state..json is tracked in git (worktrees inherit it automatically), -# but copy any untracked variants too. `npm run pull` rewrites these locally — -# copying lets a worktree experiment without touching root. +# state// is tracked in git (worktrees inherit it automatically), but +# copy any untracked variants too, and the root-level .vapi-state..json +# of a repository that has not moved its state yet. `npm run pull` rewrites +# these locally — copying lets a worktree experiment without touching root. log "Copying Vapi GitOps state files from root checkout" shopt -s nullglob -for state_file in "$ROOT"/.vapi-state*.json; do +for state_file in "$ROOT"/state/*/state.json "$ROOT"/state/*/org.json "$ROOT"/.vapi-state*.json; do [[ -e "$state_file" ]] || continue - copy_if_present "$(basename "$state_file")" + copy_if_present "${state_file#"$ROOT"/}" done shopt -u nullglob @@ -185,7 +186,7 @@ fi log "Setup complete" cat <<'INFO' Common commands in this workspace: - npm run pull # sync state from Vapi (writes .vapi-state..json) + npm run pull # sync state from Vapi (writes state//state.json) npm run push # push local resources to Vapi npm run call # interactive test call against an assistant or squad npm test # repo tests diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6834ccf..eaeae8f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,6 +39,28 @@ jobs: - run: npm test + repository: + # The tests that start a test runner of their own: the suite run inside + # copies of a repository, with every file compared before and after. Only + # in the engine's own repository; a repository built from this one has no + # use for it. + name: The suite leaves its repository alone + if: github.repository == 'VapiAI/gitops' + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + + - run: npm ci + + - run: npm run test:repository + actionlint: name: Lint workflows (actionlint) runs-on: ubuntu-latest diff --git a/.github/workflows/promotion.yml b/.github/workflows/promotion.yml index 343295d..fa78c08 100644 --- a/.github/workflows/promotion.yml +++ b/.github/workflows/promotion.yml @@ -102,7 +102,18 @@ jobs: PROMOTION_OUTCOME: ${{ steps.promotion.outcome }} run: | set -euo pipefail - git add -A -- ':(glob).vapi-state.*.json' + # Engine state lives in state/ (state//local/ is gitignored). + # A repository that has not moved its state there yet still has + # .vapi-state..json at its root. Stage both places, removals + # included, so a move commits the old file's removal and the new + # file together. Each is skipped when it holds nothing, because + # git add fails on a pathspec that matches no file. + if [[ -n "$(git ls-files --cached --others --exclude-standard -- state)" ]]; then + git add -A -- state + fi + if [[ -n "$(git ls-files --cached --others -- ':(glob).vapi-state.*.json')" ]]; then + git add -A -- ':(glob).vapi-state.*.json' + fi if [[ "$PROMOTION_OUTCOME" == "success" ]]; then git add -A -- resources elif [[ -s tmp/promotion-applied.txt ]]; then diff --git a/.gitignore b/.gitignore index 7e16615..fcd0516 100644 --- a/.gitignore +++ b/.gitignore @@ -23,13 +23,19 @@ Thumbs.db tmp/ -# Local snapshots written by `npm run push` for `npm run rollback` recovery. -# Operator-local; not shared. +# Engine state lives in state// and is committed (see state/README.md), +# except what each machine keeps for itself under state//local/: +# baselines/ "the last platform state I saw" per resource, for drift +# detection. Committing it would make one developer's baseline +# everyone's. +# snapshots/ copies written by `npm run push` for `npm run rollback`. +state/*/local/ + +# The same two stores where they sit while a repository's state is still in +# the layout from before state/ existed. For an org whose state is in state/ +# the engine moves them on the next pull, push or apply; either way they +# stay out of git. .vapi-state.*.snapshots/ - -# Per-developer drift baseline store (.vapi-state-hash//). -# Holds "the last platform state I saw" per resource. Local, not shared — -# committing it would make one developer's baseline everyone's. .vapi-state-hash/ # Dashboard-backup copies written by the push conflict prompt for manual diff --git a/AGENTS.md b/AGENTS.md index 1de7998..1f7faa8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,12 +110,15 @@ wizard needs a terminal. Instead: - Authoring from scratch → `npm run setup -- --resources none` (state only, no files). Add `--region eu` for EU orgs if auto-detection picks the wrong one. 4. Verify: `npm run validate -- ` passes, and `resources//` plus - `.vapi-state..json` exist. -5. Commit `resources//` (including `.vapi-org.json`) and `.vapi-state..json`. Never commit `.env.`. + `state//state.json` exist. +5. Commit `resources//` and `state//`. Never commit `.env.`. + +`resources//` is hand-written: edit it. `state//` is written by the +engine: never edit or delete anything in it (see [state/README.md](state/README.md)). If a command stops because the key "belongs to Vapi org …, but resources// is pinned to org …", the key is for another org. Stop and tell the human. -Never delete or edit `.vapi-org.json` to get past it: that file is the only +Never delete or edit `state//org.json` to get past it: that file is the only thing tying the folder to its org. If setup says the org is "already set up locally", don't delete anything to @@ -123,7 +126,7 @@ work around it — run `npm run pull -- `, or ask the human. **Working in an existing repository for the first time?** Run a plain `npm run pull -- ` before your first deploy. It seeds your local drift -baselines (`.vapi-state-hash/`, which is per-developer and gitignored); +baselines (`state//local/baselines/`, which is per-developer and gitignored); until then, the engine can't tell your edits from dashboard edits as precisely. @@ -145,7 +148,7 @@ precisely. `.env.`, run `VAPI_PRIVATE_API_KEY=validate-only npm run validate -- `; never ask for a real key just to validate. Don't weaken the check or the workflow to get past it, and never edit the state file, `.vapi-ignore` or - `.vapi-org.json` to make a reference resolve: fix the name, or pull. + `state//org.json` to make a reference resolve: fix the name, or pull. 4. **Build PR checks offline** if `vapi-checks.yml` exists: `npm run check -- --all --dry-run`. Fix anything it reports. 5. **Review the dry-run Name collisions list**, then **deploy only with a yes** @@ -155,7 +158,7 @@ precisely. scoped to files: `npm run apply -- resources//assistants/my-agent.md`. 6. **Verify** with the human's agreement: `npm run call -- -a ` or `npm run sim -- --suite --target `. -7. **Commit** the resource files and `.vapi-state..json`. +7. **Commit** the resource files and `state//`. **Why `apply`, not `push`:** `apply` pulls the platform's current state, merges your local edits, then pushes, so it never silently overwrites changes made in @@ -372,6 +375,14 @@ For changes under `src/`, `tests/` or `.github/`: use a local HTTP stub, as the existing tests do. - Run `npx biome check ` before you finish. It uses the pinned local Biome version and the config in `biome.json`. +- An engine test file's first import is `import "./engine-sandbox.ts";`. It + makes the engine work in a temporary directory and stops the test changing + files in the repository. A test of your own, for your own repository, + leaves it out and works in the repository as before. The suite asks for + the import only in CI for `VapiAI/gitops` itself, so a clone on your + machine is never asked. +- A test that starts a test runner of its own goes in `tests/repository/` + and runs with `npm run test:repository`, not with `npm test`. - Changing a command's flags or behaviour? Update [`docs/guides/commands.md`](docs/guides/commands.md) and the README command table in the same change. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 081b726..cee2a08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,8 +26,18 @@ learnings are all welcome. 3. Make your change, with tests for any behaviour change. Tests use `node:test` and live in `tests/`; they never call the real Vapi API. -4. Run `npx biome check `, `npm run build` and `npm test`, then - open a pull request. + Start every new test file with `import "./engine-sandbox.ts";`, before + any other import. It gives the engine a temporary directory to work in + and stops the test changing files in the repository. CI on your pull + request fails when a test file is missing it; `npm test` on your machine + doesn't ask, so that a test of your own in a clone is left alone. To ask + locally, run `GITHUB_REPOSITORY=VapiAI/gitops npm test`. +4. Run `npx biome check `, `npm run build` and `npm test`, then open a pull request. + If you changed a test, or code that writes or removes files, also run + `npm run test:repository`. It runs the suite inside copies of a + repository and checks that no file in them changed. It takes a few + minutes, so it is not part of `npm test`; CI runs it on every pull + request here. Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix(pull): …`, `feat(check): …`, `docs: …`). diff --git a/README.md b/README.md index 2b3e0d2..7d370df 100644 --- a/README.md +++ b/README.md @@ -137,11 +137,11 @@ org can keep using `VAPI_PRIVATE_API_KEY`. | Option | Default | Meaning | | --- | --- | --- | | `--region us\|eu` | `VAPI_BASE_URL` if set, else auto-detect (US, then EU) | Which Vapi API to use | -| `--resources all\|none` | `all` | `all` downloads every resource into `resources//`; `none` only seeds `.vapi-state..json` (use when you'll author from scratch) | +| `--resources all\|none` | `all` | `all` downloads every resource into `resources//`; `none` only seeds `state//state.json` (use when you'll author from scratch) | The private API key is never accepted as a command-line flag (it would leak into shell history and agent transcripts). Non-interactive setup also refuses to run if `resources//` or -`.vapi-state..json` already exists — use `npm run pull -- ` to refresh an existing org. +`state//state.json` already exists — use `npm run pull -- ` to refresh an existing org. ### 4. Make a change and deploy @@ -153,7 +153,7 @@ npm run validate -- my-org # schema check, no network npm run apply -- my-org # pull the latest, merge, push ``` -Commit the changed files and `.vapi-state.my-org.json` so your team shares the +Commit the changed files and `state/my-org/state.json` so your team shares the same name → UUID mappings. Every pull request runs the same validator for every org in CI (the **Validate resources** check), so a config `apply` would refuse fails before it merges. @@ -176,7 +176,7 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec - **Resources refer to each other by ID.** A resource's ID is its path under the type folder, without the extension: `tools/lookup-patient.yml` is `lookup-patient`. Never paste UUIDs into resource files. -- **The state file maps IDs to UUIDs.** `.vapi-state..json` records which +- **The state file maps IDs to UUIDs.** `state//state.json` records which platform resource each file is, per org. It is committed and holds no secrets. - **Secrets stay out of git.** API keys live in `.env.` (gitignored) or @@ -194,7 +194,7 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec resource; an unlinked file otherwise creates a new one. `apply` uses the same folder behavior in its push phase. - **Each folder is pinned to its org.** The first command that can see which - org a key belongs to records it in `resources//.vapi-org.json`. After + org a key belongs to records it in `state//org.json`. After that, every command checks the key against it before any request, and stops if the key belongs to a different org, so a wrong key can't pull another org's resources into the folder or push the folder into another org. @@ -204,11 +204,15 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec | Path | Committed? | What it is | | --- | --- | --- | -| `resources//` | Yes | Your resources, and `.vapi-org.json`, the org the folder belongs to | -| `.vapi-state..json` | Yes | Name → UUID mappings for the org | +| `resources//` | Yes | Your resources. Hand-written: this is what you edit | +| `state//state.json` | Yes | Name → UUID mappings for the org | +| `state//org.json` | Yes | The Vapi org the folder belongs to | +| `state//local/` | No | This machine's baselines for detecting dashboard edits, and pre-deploy snapshots for `npm run rollback` | | `.env.` | **No** | API key and generated binding IDs | -| `.vapi-state-hash/` | No | Your local baseline for detecting dashboard edits | -| `.vapi-state..snapshots/` | No | Pre-deploy snapshots for `npm run rollback` | + +Everything under `state/` is written by the engine. Don't edit or delete it by +hand: without `state.json` the next push creates every resource again as a +duplicate. [state/README.md](state/README.md) says what each file is. More detail: [How the engine works](docs/guides/how-it-works.md). @@ -286,7 +290,7 @@ object. API references: [Assistants](https://docs.vapi.ai/api-reference/assistan ## Staying up to date The engine (`src/`, `tests/`, `.github/workflows/`, `package*.json`) comes from -upstream. Your configuration (`resources/`, `.vapi-state.*.json`, +upstream. Your configuration (`resources/`, `state/`, `promotion.yml`, `vapi-checks.yml`) is yours; upstream only ships `*.example` files there. Avoid editing engine files, so updates merge cleanly. @@ -300,6 +304,9 @@ If you started from **Use this template**, add the remote first with `git remote add upstream https://github.com/VapiAI/gitops.git`; the first merge also needs `--allow-unrelated-histories`, and you'll resolve conflicts once. +If your repository still has `.vapi-state..json` files at its root, see +[Upgrading from an older version](docs/guides/commands.md#upgrading-from-an-older-version). + ## Security Never commit API keys: `.env.*` files are gitignored, and the CLI never accepts diff --git a/SECURITY.md b/SECURITY.md index ff2f61d..5100d72 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,7 +15,7 @@ acknowledge the report and keep you updated as we investigate. - **Never commit API keys.** Keys live in `.env.` files, which are gitignored, or in CI secrets. The tools never accept a key as a command-line flag, so it can't leak into shell history. -- **Committed state contains IDs, not secrets.** `.vapi-state..json` maps +- **Committed state contains IDs, not secrets.** `state//state.json` maps resource names to Vapi UUIDs. Credential secrets and phone-number provisioning are never written to the repository. - **`.ts` resource files run code.** Loading a TypeScript resource executes its diff --git a/docs/guides/commands.md b/docs/guides/commands.md index 796e34d..414a7a8 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -14,7 +14,7 @@ The other commands are direct only. | `npm run apply` | `npm run apply -- [types or paths] [--adopt [=]]` | **The default deploy:** pull, merge, then push. The push preflight below runs before remote writes. See [workflows](workflows.md). | | `npm run pull` | `npm run pull -- [--force] [--bootstrap]` | Sync platform changes down; never overwrites local edits unless `--force`. | | `npm run push` | `npm run push -- [--dry-run] [--json] [--strict] [--adopt [=]]` | Push without pulling first. Prefer `apply`. Preflight blocks validation errors and unresolved credential names in the write plan (selected resources plus auto-applied dependencies) before any remote mutation, including deletions. `--dry-run` uses the same gate. `--strict` additionally blocks error-severity findings outside the plan; warnings remain advisory. Bootstrap reads may run before preflight. | -| `npm run rollback` | `npm run rollback -- --list` or `--to ` | Restore a pre-deploy snapshot from `.vapi-state..snapshots/`. | +| `npm run rollback` | `npm run rollback -- --list` or `--to ` | Restore a pre-deploy snapshot from `state//local/snapshots/`. | | `npm run cleanup` | `npm run cleanup -- [--force --confirm ]` | List platform resources with no file; delete them only with both flags. | | `npm run audit` | `npm run audit -- [--type ]` | Report drift between files, state and the platform. Exits 1 on any finding, so it can run in CI. | | `npm run call` | `npm run call -- -a ` or `-s ` | Talk to an assistant or squad from your terminal. | @@ -23,6 +23,7 @@ The other commands are direct only. | `npm run promote` | `npm run promote -- --pipeline

--from --to [--apply]` | Plan, or apply, a [promotion](promotion.md) between orgs. | | `npm run build` | `npm run build` | Type-check the code and tests. | | `npm test` | `npm test` | Run the test suite. | +| `npm run test:repository` | `npm run test:repository` | For work on the engine itself: run the test suite inside copies of a repository and check that no file in them changed. Takes a few minutes. | Pull and push never automatically rename UUID-suffixed state keys to match local files. A local file without a UUID mapping remains subject to the @@ -193,14 +194,193 @@ The test-call CLI cleans its terminal output for the developer loop: ## Upgrading from an older version -Repositories created before the state-file format changed need a one-time -migration. `pull`, `push` and `apply` refuse to run until it's done: +Upgrading the engine does not change where your state is kept. A repository +with `.vapi-state..json` at its root keeps it there: `pull`, `push`, +`apply` and `promote` read and write it in place, on your machine and in CI, +for as long as you like. Each of those commands prints one line saying the +newer layout exists. + +`npm run migrate` is the only command that moves state. It needs no org and +no API key, and it's safe to run more than once: ```bash npm run migrate +git add -A -- state ':(glob).vapi-state.*.json' resources +git commit -m "chore: move engine state into state/" +``` + +It does three things. + +**Says what your commit step has to stage, before it moves anything.** A +promotion or apply run in CI writes the state file and leaves committing it +to a later step. If that step stages only the old file, moved state drops out +of git: every run still passes, and the next one creates every resource +again. Once state is in `state/`, whatever commits state after a run has to +stage both of these: + +```bash +git add -A -- state # the new folder +git add -A -- ':(glob).vapi-state.*.json' # the old files, so their removal is committed +``` + +A commit action or a script needs the same two paths. Upstream's +`.github/workflows/promotion.yml` has both. + +**Moves engine files into `state//`,** when it can see that step or you +tell it. Nothing changes inside the files. + +| Before | Now | +| --- | --- | +| `.vapi-state..json` | `state//state.json` | +| `resources//.vapi-org.json` | `state//org.json` | +| `.vapi-state-hash//` | `state//local/baselines/` | +| `.vapi-state..snapshots/` | `state//local/snapshots/` | + +What it does depends on what it reads in `.github/workflows/`: + +- **Every commit step there stages `state/`.** It moves every org. +- **A step stages `.vapi-state.*.json` and nothing that could be `state/`.** + It moves nothing and names the workflow. Take upstream's `promotion.yml` + workflow, or add `git add -A -- state` to your own commit step, then run + `npm run migrate` again. +- **Anything else.** A step that stages through a script, a commit action or + a variable, a repository with no workflow, or a pipeline in another CI + system. It moves nothing and asks you. When your step stages both paths, + say so: + + ```bash + npm run migrate -- --commit-step-stages-state + ``` + + That writes `state/commit-step.json` and moves every org. Commit it with + the move. + +> **`--commit-step-stages-state` is your word, and the engine can't check +> it.** If you pass it and your commit step does not stage `state/`, +> promotion runs pass while `state//state.json` is never committed, and +> a later run creates the same resources again. The flag is refused only when +> a workflow is plainly seen to stage the old file alone. To take it back, +> delete `state/commit-step.json`. + +**Rewrites a legacy-format state file.** Repositories created before the +state-file format changed carry per-resource hashes in the state file, and +`pull`, `push` and `apply` refuse to run until they're gone. `migrate` +rewrites each file to the current `{ "name": { "uuid": … } }` format and +seeds this machine's drift baselines from the old file. + +### What the engine reads as a commit step + +The engine reads the workflow files in `.github/workflows/` and nothing else. +It counts a `git add` as staging `state/` only where it can tell what the +command stages: + +- It is a command of its own in a `run:` step that runs `bash` or `sh` at + the repository root. +- It names `state` (also `state/` or `state/**`), or it stages everything: + `git add -A`, `git add --all`, `git add .`. +- An `if` around it is fine when it names `state`, because that is how a step + guards a folder that may not exist yet. + +Everything else counts for nothing: a `git add` after a `cd`, in a step with +a `working-directory`, after `||`, inside a loop, a function or a quoted +string, with `-u`, with a variable or an exclusion in its paths, or a +`git add -A` inside an `if`. A step like that may well work. The engine just +can't tell, so `migrate` asks for the flag. + +Every job that shows a commit step has to pass, in every workflow file. A job +shows none when its `permissions` keep `contents` read-only and it runs no +`git add`, `git commit` or `git push`, so upstream's `ci.yml` and +`vapi-checks.yml` don't get in the way. + +A pipeline the engine has no file for is never read: another CI system, or a +script that commits with its own token. Check it yourself against the two +lines above before you run `migrate`. + +### When a CI run stops + +A CI run stops, before it sends any request, when the workflow running it is +seen not to commit what it would write: + +- State is in `state/`, and the commit step stages only the old file. +- State is in `state/`, the commit step can't be read, and there is no + `state/commit-step.json`. +- State is still at the root, and the commit step stages only `state/`. + +In GitHub Actions the engine checks the workflow that is running it. Anywhere +else it checks every workflow in the repository. + +If both the old and the new file exist for an org and they disagree, every +writing command stops before it changes anything and names the two files. If +they hold the same content, the engine reads the one in `state/`, keeps the +old copy identical, and says that `npm run migrate` removes it. + +### A repository with no state yet + +A new repository starts in `state/` when a workflow in `.github/workflows/` +is seen to stage it, as upstream's `promotion.yml` does, or when +`state/commit-step.json` says your commit step does. Otherwise the first state +file is written at the root, as `.vapi-state..json`, where every older +commit step looks for it, and the command says so in one line: + +``` +ℹ️ No engine state in this repository yet: it goes to .vapi-state..json at the repository root, because … Whatever commits state after a run has to stage .vapi-state.*.json. … +``` + +If your commit step stages only `state/` and the engine can't read it (a +script, a commit action, another CI system), that file would never be +committed. Before the first `pull`, either make the step stage +`.vapi-state.*.json` as well, or tell the engine the step stages `state/` and +commit the file it writes: + +```bash +npm run migrate -- --commit-step-stages-state +git add state/commit-step.json +``` + +### What you'll see after upgrading + +- **`ℹ️ Engine state here is in the older layout …`**, one line per writing + command, until you run `npm run migrate`. Nothing else changes. +- **A dashboard edit can arrive one pull late, once.** On a machine with no + baselines yet, the first `pull` after upgrading keeps every local file, and + an edit made in the dashboard comes down on the next `pull`. Nothing is + lost. + +After `npm run migrate`: + +- **`📦 Moved … into state//`**, once per org, from `migrate` itself. +- **Nothing new from `pull` before you commit the move.** Git shows the old + org pin, `resources//.vapi-org.json`, as deleted until you commit. Pull + doesn't count that, or any other file the engine writes, as an edit of + yours, so it does nothing differently because of it. +- **`📦 Moved .vapi-state-hash// … into state//local/`**, once, on + each teammate's machine after they pull your commit. Those are that + machine's own baselines and snapshots, which are not in git. + +### Going back to an older engine + +A repository that never ran `npm run migrate` has nothing to move back: its +state is where an older engine looks for it. + +An engine from before `state/` doesn't read the folder. If you revert the +engine after state has moved, it finds no state file: `pull` adopts every +resource again under a new file name, and promotion creates each resource a +second time. Move the state files back first, in the same commit as the +revert: + +```bash +for dir in state/*/; do + org=$(basename "$dir") + if [ -f "state/$org/state.json" ]; then mv "state/$org/state.json" ".vapi-state.$org.json"; fi + if [ -f "state/$org/org.json" ]; then mv "state/$org/org.json" "resources/$org/.vapi-org.json"; fi + # This machine's baselines and snapshots. They are not in git, so everyone + # who has pulled or pushed since the move runs these two on their machine. + if [ -d "state/$org/local/baselines" ]; then mkdir -p .vapi-state-hash && mv "state/$org/local/baselines" ".vapi-state-hash/$org"; fi + if [ -d "state/$org/local/snapshots" ]; then mv "state/$org/local/snapshots" ".vapi-state.$org.snapshots"; fi +done +git add -A -- state ':(glob).vapi-state.*.json' resources ``` -It rewrites every org's `.vapi-state..json` to the current -`{ "name": { "uuid": … } }` format and seeds your local -`.vapi-state-hash/` drift baseline from the old file. It's safe to run more -than once. Commit the rewritten state files. +Then revert the engine and commit. The older engine ignores whatever is left +under `state/`. A commit step that was changed to stage only `state/` has to +stage `.vapi-state.*.json` again. diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index cffbc5d..79779fd 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -49,9 +49,16 @@ Set these in GitHub under **Settings → Secrets and variables → Actions**. | --- | --- | | `promotion.yml` | Promotion pipelines between orgs. Start from `promotion.example.yml`. | | `vapi-checks.yml` | PR checks. Start from `vapi-checks.example.yml`. | -| `resources//.vapi-org.json` | The Vapi org ID the folder belongs to. Written by the first command that can see the key's org, then checked by every command before any request: a key for another org stops the command. If a folder genuinely moves to another org, delete the file in a reviewed commit. | | `resources//.vapi-ignore` | Platform resources this repo shouldn't manage, as glob patterns. See `resources/.vapi-ignore.example` and [YAML conventions](../learnings/yaml-conventions.md). | +These are hand-written. The files the engine writes live apart from them, in +`state//`, and are not configuration: don't edit them. + +| File | Purpose | +| --- | --- | +| `state//state.json` | Which platform resource (UUID) each file under `resources//` is. | +| `state//org.json` | The Vapi org ID the folder belongs to. Written by the first command that can see the key's org, then checked by every command before any request: a key for another org stops the command. If a folder genuinely moves to another org, delete the file in a reviewed commit. | + ## Other environment variables | Variable | Description | diff --git a/docs/guides/how-it-works.md b/docs/guides/how-it-works.md index 83ebce1..ca78a0a 100644 --- a/docs/guides/how-it-works.md +++ b/docs/guides/how-it-works.md @@ -5,16 +5,24 @@ Resources are scoped by organization, with names you choose (not fixed `dev`/`stg`/`prod`). Each org gets: - `.env.` — private API key and base URL -- `.vapi-state..json` — resource ID ↔ UUID mappings and optional origin (committed) -- `.vapi-state-hash//` — last-seen platform content hash per resource, used for drift detection (per-developer, gitignored) -- `resources//` — all resource files +- `resources//` — all resource files. Hand-written: this is what you edit +- `state//` — what the engine generates and tracks. Never edit or delete it by hand ([state/README.md](../../state/README.md)) + - `state.json` — resource ID ↔ UUID mappings and optional origin (committed) + - `org.json` — the Vapi org the folder is pinned to (committed) + - `local/baselines/` — last-seen platform content hash per resource, used for drift detection (per-developer, gitignored) + - `local/snapshots/` — pre-deploy snapshots for `npm run rollback` (per-developer, gitignored) ``` vapi-gitops/ ├── .env.my-org # Private API key for my-org ├── .env.production # Private API key for production -├── .vapi-state.my-org.json # State file for my-org -├── .vapi-state.production.json # State file for production +├── state/ # Written by the engine; don't edit by hand +│ ├── my-org/ +│ │ ├── state.json # Name → UUID mappings for my-org +│ │ ├── org.json # The Vapi org my-org is pinned to +│ │ └── local/ # This machine only (gitignored) +│ └── production/ +│ └── (same structure) ├── resources/ │ ├── my-org/ # Dev/test org resources │ │ ├── assistants/ @@ -93,7 +101,7 @@ authorize new name-based links. Existing exact-key legacy links remain intact. Conflict handling is **per resource, never umbrella**: apply defaults to `--resolve=defer`, so the pull stage preserves local files and the drift baselines for genuinely conflicted resources, and the push stage then asks one interactive question per conflicted resource (push mine / keep dashboard / save a `.bkp` copy for manual merge). Clean and one-sided changes flow silently in their obvious direction. The full scenario matrix lives in `docs/learnings/sync-behavior.md`. Explicit `--resolve=ours|theirs|fail` keep non-interactive (CI) semantics. -Before updating a resource, push GETs its current dashboard payload, hashes it, and compares against the stored baseline (`.vapi-state-hash//`): +Before updating a resource, push GETs its current dashboard payload, hashes it, and compares against the stored baseline (`state//local/baselines/`): - **Hashes match** → your local edit is the natural next step in the change chain → pushed silently, and the baseline is refreshed from the PATCH **response** (what the platform actually stored). - **Hashes differ** → someone else published changes since your last sync. In a terminal, push asks **for that resource only**: ① push my local version (take ownership) ② keep the dashboard version (skip, local untouched) ③ save the dashboard version as `..bkp.` beside your file and skip, for a manual merge. In CI / piped runs the resource is blocked instead (use `--overwrite` to push unconditionally). @@ -215,7 +223,7 @@ requests themselves; there is no separate telemetry. | Path | What it is | | --- | --- | | `resources//` | Your resources, one folder per org | -| `.vapi-state..json` | Name → UUID mappings per org (committed) | +| `state//` | What the engine generates and tracks: name → UUID mappings and the org pin (committed), plus `local/` (gitignored). Not edited by hand | | `.env.` | API key and generated binding IDs (gitignored) | | `promotion.yml`, `vapi-checks.yml` | Promotion pipelines and PR checks (copy from the `*.example.yml` files) | | `resources//.vapi-ignore` | Platform resources this repo shouldn't manage (see `resources/.vapi-ignore.example`) | diff --git a/docs/guides/pr-checks.md b/docs/guides/pr-checks.md index 58b514f..5f4403f 100644 --- a/docs/guides/pr-checks.md +++ b/docs/guides/pr-checks.md @@ -151,7 +151,7 @@ promoted out of it: set `orgs..check: ` in `promotion.yml` (see 2. Create the credentials your agents need there, with the same names as production. 3. `npm run pull -- my-ci-org --bootstrap --bindings-only`, then commit - `.vapi-state.my-ci-org.json` so the state knows those credentials. The PR + `state/my-ci-org/state.json` so the state knows those credentials. The PR workflow refreshes bindings on every live run. 4. Add `runOrg: my-ci-org` (and `baseUrl` for EU) to the check, and optionally `bindings:` (same shape as `promotion.yml`). Phone numbers are diff --git a/docs/guides/promotion.md b/docs/guides/promotion.md index e5b9efc..1d9bae1 100644 --- a/docs/guides/promotion.md +++ b/docs/guides/promotion.md @@ -11,8 +11,8 @@ left alone. 1. Configure every org with `npm run setup`, using one stable slug per org (for example `acme-dev`, `acme-staging`, and `acme-prod`). 2. Run `npm run pull -- --bootstrap` for every org. Commit each - `.vapi-state..json`; never commit `.env.` or - `.vapi-state-hash/`. + `state//` folder; never commit `.env.` (`state//local/` + is gitignored already). 3. Copy `promotion.example.yml` to `promotion.yml`. List orgs in forward-only release order and set the correct `baseUrl` for each region. 4. Give each pipeline the narrowest resource globs it owns. A pattern is both @@ -35,7 +35,7 @@ npm run promote -- --pipeline release --from dev --to staging --apply Promotion copies logical references, not physical UUIDs. Dependencies such as tools and structured outputs are included before assistants, and the normal destination push resolves every logical name through -`.vapi-state..json`. Existing credentials and phone numbers use +`state//state.json`. Existing credentials and phone numbers use the destination org's binding; their secret material is never copied or provisioned. diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index 78ccecc..4876762 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -70,7 +70,7 @@ README's quick start), then run a plain pull before your first deploy: npm run pull -- ``` -This seeds your local drift baselines (`.vapi-state-hash/`, per developer and +This seeds your local drift baselines (`state//local/baselines/`, per developer and gitignored), so later pulls and deploys can tell your edits from changes made in the dashboard. @@ -85,7 +85,7 @@ npm run validate -- npm run apply -- ``` -On a fresh org, `apply`'s pull phase creates `.vapi-state..json` from +On a fresh org, `apply`'s pull phase creates `state//state.json` from the empty dashboard before pushing your new resources. ## Create new resources after the first deploy @@ -160,7 +160,7 @@ Detection works in three layers, so it covers both day-to-day and fresh-clone workflows: 1. **Content baseline (primary)** — each resource's last-seen platform hash - lives in the per-developer `.vapi-state-hash//` store + lives in the per-developer `state//local/baselines/` store (gitignored). Comparing local / baseline / dashboard hashes classifies every resource as clean, local-ahead (preserved ⬆️), dashboard-ahead (synced down ⬇️ — local was unchanged, nothing to lose), or both-diverged @@ -169,10 +169,13 @@ fresh-clone workflows: 2. **Git-tracked changes** — when no baseline exists yet, files that show up in `git status` (modified, deleted, or individually untracked) are preserved. -3. **mtime fallback** — if git can't help (no commits yet, the resource tree - isn't tracked at all, or git just had nothing to say), files that are - newer than `.vapi-state..json` are still preserved. This is the safety - net for the "fresh clone, edit a file, run pull again" case. +3. **Last-save fallback** — if git can't help (no commits yet, the resource + tree isn't tracked at all, or git just had nothing to say), a file is + still preserved unless the engine has saved this org's state on this + machine since the file was last written. A fresh clone has no such save + yet, so its first pull keeps every file: a change merged in git and not + yet on the platform is not overwritten, whatever order the checkout wrote + the files in. Interactive `npm run pull` is local-first too: it asks `Overwrite locally modified files?` (default `No`). Pass `--force` (or answer @@ -188,7 +191,7 @@ npm run pull -- --bootstrap npm run pull -- --type squads --id ``` -`--bootstrap` refreshes `.vapi-state..json`, credential mappings, and the +`--bootstrap` refreshes `state//state.json`, credential mappings, and the generated credential and phone-number block in `.env.`, and leaves `resources//` untouched. Setup and ordinary pulls do the same binding refresh, and `push` runs it automatically when the state looks empty or @@ -229,7 +232,7 @@ npm run cleanup -- --force --confirm ``` Cleanup treats every platform resource that isn't in -`.vapi-state..json` as unmanaged, except those matched by +`state//state.json` as unmanaged, except those matched by `resources//.vapi-ignore`: it lists those as retained and never deletes them. Still read the dry-run list before a destructive run. diff --git a/docs/learnings/simulations.md b/docs/learnings/simulations.md index b751eb7..e68a0f0 100644 --- a/docs/learnings/simulations.md +++ b/docs/learnings/simulations.md @@ -145,7 +145,7 @@ If your post-call analytics structured output uses `type: object` with nested sc ## Simulation File Names After Push -Simulation resource files use placeholder UUIDs (`a0000000`) locally. After the first push, the gitops engine creates platform resources and maps local filenames to platform UUIDs in `.vapi-state..json`. The local filename is a stable handle and is **not** rewritten to match the platform `name` — once a UUID is tracked in state, pull and bootstrap preserve the existing filename and only update file content. (Older engine versions renamed files to match the platform name and emitted `name_mismatch` warnings; that behavior was removed — see `improvements.md` #22.) +Simulation resource files use placeholder UUIDs (`a0000000`) locally. After the first push, the gitops engine creates platform resources and maps local filenames to platform UUIDs in `state//state.json`. The local filename is a stable handle and is **not** rewritten to match the platform `name` — once a UUID is tracked in state, pull and bootstrap preserve the existing filename and only update file content. (Older engine versions renamed files to match the platform name and emitted `name_mismatch` warnings; that behavior was removed — see `improvements.md` #22.) --- diff --git a/docs/learnings/squads.md b/docs/learnings/squads.md index 07fb1c6..8184080 100644 --- a/docs/learnings/squads.md +++ b/docs/learnings/squads.md @@ -234,7 +234,7 @@ See also [structured-outputs.md → Squad `membersOverrides` vs standalone struc `assistantOverrides.model.toolIds` in squad members must use **Vapi platform UUIDs**, not local filenames. The gitops engine resolves filenames to UUIDs for base assistant `model.toolIds`, but it does **not** resolve them inside squad `assistantOverrides`. If you use a local filename, the push will fail with `each value in toolIds must be a UUID`. -**Workaround:** Look up the tool's UUID from `.vapi-state..json` and use it directly. +**Workaround:** Look up the tool's UUID from `state//state.json` and use it directly. ```yaml # WRONG — filename, will fail in assistantOverrides diff --git a/docs/learnings/sync-behavior.md b/docs/learnings/sync-behavior.md index 60501a2..54d1b14 100644 --- a/docs/learnings/sync-behavior.md +++ b/docs/learnings/sync-behavior.md @@ -15,8 +15,8 @@ function of which of them exist and whether their contents agree. | Artifact | Where | Committed? | Meaning | |---|---|---|---| | **Local file** (`L`) | `resources///.md\|yml` | yes | The declarative source of truth you edit | -| **State entry** (`S`) | `.vapi-state..json` → `{ "": { "uuid": … } }` | yes | The ONLY thing state stores: which platform UUID a local name is bound to | -| **Baseline** (`B`) | `.vapi-state-hash//` | **no** (per-developer, gitignored) | sha256 of the last platform content *you* saw (last pull or push) | +| **State entry** (`S`) | `state//state.json` → `{ "": { "uuid": … } }` | yes | The ONLY thing state stores: which platform UUID a local name is bound to | +| **Baseline** (`B`) | `state//local/baselines/` | **no** (per-developer, gitignored) | sha256 of the last platform content *you* saw (last pull or push) | | **Dashboard resource** (`D`) | Vapi platform | n/a | What's live | **One letter per artifact — the same letter for the thing and for its hash.** @@ -194,7 +194,7 @@ sweep, which consume the resources today without consuming the verdict. | Command | Behavior | |---|---| -| `pull` | direction unknown (`no-baseline`) → falls back to git/mtime modified-detection: modified files ✏️ preserved; unmodified files 📝 rewritten — and the baseline is seeded. **Run a plain pull first on any fresh clone.** | +| `pull` | direction unknown (`no-baseline`) → falls back to git modified-detection, then to the last-save rule: a file is ✏️ preserved unless the engine has saved this org's state on this machine since the file was written. A fresh clone has no save yet, so its first pull preserves every file; after that, an untouched file is 📝 rewritten and its baseline seeded. **Run a plain pull first on any fresh clone.** | | `push` (without pulling first) | drift check skipped with a warning, PATCH proceeds, baseline seeded from the response. Risk window: this one push cannot detect dashboard drift. | | `audit` | `no-baseline` info findings (do not block CI) | @@ -202,8 +202,8 @@ sweep, which consume the resources today without consuming the verdict. `pull`, `push`, and `apply` all **hard-refuse** with `Run \`npm run migrate\` first.` The migration (no org argument, no token -needed) slims every `.vapi-state..json` to `name → { uuid }` and seeds -each org's `.vapi-state-hash/` from the legacy hashes. Idempotent. +needed) slims every `state//state.json` to `name → { uuid }` and seeds +each org's `state//local/baselines/` from the legacy hashes. Idempotent. ### G. Local file renamed @@ -232,7 +232,7 @@ does not deploy the source org itself. A safe deletion therefore has two separate lifecycles: 1. Delete the source resource file in a reviewed Git change, but retain its - `.vapi-state..json` entry. The entry is the deletion tombstone. + `state//state.json` entry. The entry is the deletion tombstone. 2. Review `npm run promote` and merge or apply it. Only matching destination paths are removed, in reverse dependency order. 3. An automatic `--all --apply` run carries that authorization through every diff --git a/examples/cross-org-promotion/README.md b/examples/cross-org-promotion/README.md index a68ba36..5ec70c3 100644 --- a/examples/cross-org-promotion/README.md +++ b/examples/cross-org-promotion/README.md @@ -13,12 +13,13 @@ This fixture shows the shape of a linear `example-dev` → `example-staging` → The example state files intentionally assign different UUIDs to the same logical resources in each org. They are reference material only. Never copy -them into the repository root or use them with a real Vapi organization. +them into the repository's `state/` folder or use them with a real Vapi +organization. ## What the promotion engine does The engine resolves tools, structured outputs, assistants, and credentials -through each org's own `.vapi-state..json`. `npm run promote` mirrors only +through each org's own `state//state.json`. `npm run promote` mirrors only the resource patterns reviewed in `promotion.yml`, includes referenced managed dependencies, and lets the destination push mint or reuse that org's UUIDs. Source-org managed UUIDs are never copied as destination references. @@ -85,7 +86,7 @@ Use real disposable orgs, not the fake IDs in this directory. After the first successful apply, compare the three generated state files: ```bash -node -e 'for (const org of ["example-dev", "example-staging", "example-production"]) { const s = require(`./.vapi-state.${org}.json`); console.log(org, { credential: s.credentials["crm-api"].uuid, tool: s.tools["customer-lookup"].uuid, assistant: s.assistants["support-assistant"].uuid }); }' +node -e 'for (const org of ["example-dev", "example-staging", "example-production"]) { const s = require(`./state/${org}/state.json`); console.log(org, { credential: s.credentials["crm-api"].uuid, tool: s.tools["customer-lookup"].uuid, assistant: s.assistants["support-assistant"].uuid }); }' ``` The aliases should be identical while every org's physical IDs are different. diff --git a/examples/cross-org-promotion/state/.vapi-state.example-dev.json.example b/examples/cross-org-promotion/state/example-dev/state.json.example similarity index 100% rename from examples/cross-org-promotion/state/.vapi-state.example-dev.json.example rename to examples/cross-org-promotion/state/example-dev/state.json.example diff --git a/examples/cross-org-promotion/state/.vapi-state.example-production.json.example b/examples/cross-org-promotion/state/example-production/state.json.example similarity index 100% rename from examples/cross-org-promotion/state/.vapi-state.example-production.json.example rename to examples/cross-org-promotion/state/example-production/state.json.example diff --git a/examples/cross-org-promotion/state/.vapi-state.example-staging.json.example b/examples/cross-org-promotion/state/example-staging/state.json.example similarity index 100% rename from examples/cross-org-promotion/state/.vapi-state.example-staging.json.example rename to examples/cross-org-promotion/state/example-staging/state.json.example diff --git a/examples/starter/.vapi-state.starter.json b/examples/starter/state/starter/state.json similarity index 100% rename from examples/starter/.vapi-state.starter.json rename to examples/starter/state/starter/state.json diff --git a/improvements.md b/improvements.md index 0d98ca7..c7a2ce6 100644 --- a/improvements.md +++ b/improvements.md @@ -109,6 +109,7 @@ you which stack PR closes the row.** | 36 | `cleanup` deletes resources excluded by `.vapi-ignore` | A destructive cleanup can delete resources another team owns | None | RESOLVED 2026-10-03 | | 37 | Resource validation ran only at deploy time, after merge | A config `apply` refuses could merge and block deploys and promotion | #32 | RESOLVED 2026-10-03 (#76) | | 38 | Promotion can't carry a simulation that uses a stock personality by UUID | Gated orgs, and any promoted tests, need local personality files | None | Open | +| 39 | Engine state looked like temp files and sat in three places | Deleting the state file makes the next push duplicate every resource | None | RESOLVED 2026-11-17 (#97) | **Active backlog after cleanup:** `#2`, `#6`, `#8`, `#12`, `#20`, `#24–#26`, `#31`, and the open remainder of `#27` (wiring the listing-completeness verdict into push/delete/audit, and moving `cleanup.ts` onto the shared pager). Resolved entries stay in this file as historical incident notes per the maintenance directive; stale superseded backlog rows are not duplicated. @@ -2081,6 +2082,127 @@ dependency check, as `check-payload.ts` already does. --- +## 39. Engine state looked like temp files and sat in three places + +**[RESOLVED 2026-11-17] (#97)** + +**Discovered:** 2026-11-17, from a user asking which of the generated +dot-files were safe to delete. + +### Problem + +Everything the engine generates and tracks sat under dot-names in three +places: `.vapi-state..json`, `.vapi-state..snapshots/` and +`.vapi-state-hash/` at the repository root, and `.vapi-org.json` inside +`resources//` beside the hand-written `.vapi-ignore`. Nothing told a +person which of those files they own and which the engine owns, and the root +files read as leftovers. + +### Current behavior before the fix (Verified) + +- `src/config.ts` built `.vapi-state..json` at the root, and eleven + other modules rebuilt the same path inline. +- `src/org-pin.ts` wrote `resources//.vapi-org.json`. +- `src/hash-store.ts` and `src/snapshot.ts` each built their own root folder. + +### Risk + +Deleting the state file is silent until the next push, which then creates +every resource again as a duplicate. Deleting the pin removes the check that +stops a key for another org. + +### Current mitigation + +None needed once the fix below lands. + +### Possible fix (landed) + +One folder, `state//`, holds the state file (`state.json`), the org pin +(`org.json`) and, under a gitignored `local/`, this machine's baselines and +snapshots. `state/README.md` says the engine writes it and what breaks when a +file goes missing. `resources//` now holds hand-written files only. +`src/state-paths.ts` is the one module that knows both layouts. + +An older repository keeps working exactly as it did: an org is in one layout, +decided by where its committed state file is, and every command reads and +writes the layout it finds, on a person's machine and in CI. No command moves +committed state as a side effect. Only `npm run migrate` does, with one +rename per file, after saying what the step that commits state after a run +has to stage. It moves state when every commit step in `.github/workflows/` +is seen to stage `state/`. It moves nothing while a workflow stages +`.vapi-state.*.json` and nothing that could be `state/`, or while no commit +step can be read (a script, a commit action, no workflow, a pipeline outside +GitHub Actions), until a person says theirs stages `state/` with +`npm run migrate -- --commit-step-stages-state`. + +The reader of commit steps (`src/commit-step.ts`) fails closed: a `git add` +counts only as a plain command at the repository root that names `state` or +stages everything. A CI run stops before any request when the workflow +running it is seen not to commit what it would write. The promotion workflow +stages both places. `tests/state-layout.test.ts`, +`tests/state-layout-unseen-commit.test.ts`, +`tests/state-move-second-round.test.ts` and +`tests/promotion-workflow-commit.test.ts` cover each path. + +Pull had one rule that depended on where the state file sat. With no baseline +and nothing changed in git it kept a file only when the file was newer than +the state file, and in a fresh clone that is the order git wrote the files +in: every file was kept with state at the root, and every file would have +been overwritten with state in `state/`. Pull now compares against the moment +this machine's engine last saved state, kept beside the baselines, and a +clone with no such save keeps every file. The same rule is off whenever git +shows a change under `resources//`, and the engine keeps files of its own +there in the older layout. Pull leaves those out (`engineFiles` in +`src/state-paths.ts`, built from the list `migrate` moves), so a file the +engine wrote, or one `migrate` moved and git shows as deleted, is never +counted as a person's edit. + +A repository with no state at all, whose commit step can't be read, gets its +first state file at the root. A step that stages only `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 in `state/` +instead. + +The engine's test suite never works in the repository it runs in. Every +module takes the engine's directory from `src/base-dir.ts` +(`tests/base-dir.test.ts` fails when one works it out for itself). Every +engine test file imports `tests/engine-sandbox.ts` first, which points the +engine at a temporary directory and makes every `node:fs` change inside the +repository throw, so the protection holds however the file is started. In +CI for the engine's own repository a test file without that import fails the +suite; on a person's machine that check is skipped, so a clone that holds a +test of its owner's behaves as it did before. +`tests/repository/suite-leaves-the-repository.test.ts` runs the engine's +whole suite inside a copy of a customer-shaped repository in each layout and +compares every file, tracked, untracked and ignored, before and after. It +and the other tests that start a test runner of their own are not part of +`npm test`, which takes about as long as it did before them: they run with +`npm run test:repository` and as a CI job in the engine's own repository. + +The engine itself never asks whether a test runner is above it. A test that +doesn't import the sandbox, such as one a repository built from this one +keeps under `tests/`, is untouched: the commands it starts and the modules +it imports work in that repository, and it writes where it likes +(`tests/repository/own-tests-as-before.test.ts`). + +Two limits remain. The flag is a person's word: if it is given and the commit +step does not stage `state/`, promotion runs pass while state is never +committed. And the engine reads `.github/workflows/` only: a pipeline it has +no file for is not read, which is why `migrate` always prints the two lines +first. + +Two things stay where they were, on purpose. Dashboard backups +(`..bkp.md`) stay beside the resource they shadow: a person +opens them next to the file to merge by hand, nothing reads them back, and +they are gitignored. `tmp/promotion-applied.txt` stays in `tmp/`: it is one +run's hand-off to the workflow, and an older workflow reads it there. + +### Status + +**RESOLVED 2026-11-17.** + +--- + ## Out of scope (intentionally not improvements) - **State file is identity-only and not git-ignored.** It's intentionally diff --git a/package.json b/package.json index e9a003f..a93ada9 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,8 @@ "rollback": "tsx src/rollback-cmd.ts", "promote": "tsx src/promote-cmd.ts", "build": "tsc --noEmit", - "test": "node --import tsx --import ./tests/no-vapi-api.ts --test tests/*.test.ts" + "test": "node --import tsx --import ./tests/no-vapi-api.ts --test tests/*.test.ts", + "test:repository": "node --import tsx --import ./tests/no-vapi-api.ts --test --test-concurrency=1 tests/repository/*.test.ts" }, "devDependencies": { "@biomejs/biome": "2.4.15", diff --git a/src/api.ts b/src/api.ts index 6ea7e20..9dc3451 100644 --- a/src/api.ts +++ b/src/api.ts @@ -6,7 +6,7 @@ import { VAPI_TOKEN, VAPI_TOKEN_SOURCE, } from "./config.ts"; -import { ORG_PIN_FILE, OrgPinMismatchError, orgPinCheck } from "./org-pin.ts"; +import { OrgPinMismatchError, orgPinCheck, orgPinLabel } from "./org-pin.ts"; import type { VapiResponse } from "./types.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; import { @@ -33,7 +33,7 @@ const DRY_RUN_COUNTS = { POST: 0, PATCH: 0, DELETE: 0 }; let orgPinChecked: Promise | undefined; /** - * Check the key against resources//.vapi-org.json once per process, + * Check the key against state//org.json once per process, * before the first request (see org-pin.ts). A mismatch exits instead of * throwing, because several callers catch request errors and retry or carry * on, and none of them should reach the wrong org. @@ -54,11 +54,11 @@ export function orgPinGuard(): Promise { }); if (outcome.kind === "pinned") console.log( - `📌 Pinned resources/${VAPI_ENV}/ to Vapi org ${outcome.orgId} (${ORG_PIN_FILE}). Commit it with the folder.`, + `📌 Pinned resources/${VAPI_ENV}/ to Vapi org ${outcome.orgId} (${orgPinLabel(BASE_DIR, VAPI_ENV)}). Commit that file.`, ); if (outcome.kind === "unverified") console.warn( - `⚠️ Couldn't confirm which Vapi org the key belongs to, so it wasn't checked against resources/${VAPI_ENV}/${ORG_PIN_FILE}.`, + `⚠️ Couldn't confirm which Vapi org the key belongs to, so it wasn't checked against ${orgPinLabel(BASE_DIR, VAPI_ENV)}.`, ); } catch (error) { if (error instanceof OrgPinMismatchError) { @@ -71,7 +71,6 @@ export function orgPinGuard(): Promise { return orgPinChecked; } - export function getDryRunCounts(): { POST: number; PATCH: number; diff --git a/src/apply.ts b/src/apply.ts index b50057f..e4af462 100644 --- a/src/apply.ts +++ b/src/apply.ts @@ -1,8 +1,14 @@ import { execSync } from "child_process"; -import { dirname, join, resolve } from "path"; +import { join, resolve } from "path"; import { fileURLToPath } from "url"; import { parseAdoptArgs } from "./adopt.ts"; +import { baseDir } from "./base-dir.ts"; import { assertStateMigrated } from "./migrate-hash-store.ts"; +import { + stateFileRead, + stateLayoutPrepare, + stateNoticesPrint, +} from "./state-paths.ts"; // Pins this command's User-Agent label for the pull and push it spawns. import "./user-agent.ts"; @@ -14,8 +20,7 @@ import "./user-agent.ts"; // 3. If conflicts, stop — user resolves, then runs push manually // ───────────────────────────────────────────────────────────────────────────── -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/; @@ -41,10 +46,13 @@ export async function runApply(): Promise { const hasForce = allArgs.includes("--force"); const dryRun = allArgs.includes("--dry-run"); - // Fail fast with one clear message if this org's state file is still legacy, - // rather than letting the spawned pull/push subprocess surface it later. + // Check the org's state layout once, here, and fail fast with one clear + // message if the state file is still in the legacy format, rather than + // letting the spawned pull/push subprocess surface either later. What is + // printed here is not printed again by the pull and push below. if (env && SLUG_RE.test(env)) { - assertStateMigrated(join(BASE_DIR, `.vapi-state.${env}.json`)); + stateNoticesPrint(stateLayoutPrepare(BASE_DIR, env)); + assertStateMigrated(stateFileRead(BASE_DIR, env)); } // Default drift resolution is "defer": pull preserves the local file AND diff --git a/src/audit.ts b/src/audit.ts index f5f915e..a623056 100644 --- a/src/audit.ts +++ b/src/audit.ts @@ -70,7 +70,7 @@ export interface AuditOptions { // DI seam: swap the network call. When supplied, `fetchRemote` is implied // true and the default `fetchAllResources` is not used. remoteFetcher?: (t: ResourceType) => Promise; - // DI seam: swap state loading (default reads .vapi-state..json). + // DI seam: swap state loading (default reads state//state.json). stateLoader?: () => StateFile; // DI seam: swap local-file enumeration (default walks resources///). listLocalIds?: (t: ResourceType) => string[]; @@ -80,7 +80,7 @@ export interface AuditOptions { // is accepted so tests can keep their fixtures plain-object. readAssistantTools?: (resourceId: string) => unknown[] | Promise; // DI seam: swap the drift-baseline lookup. Defaults to the per-developer - // hash store (.vapi-state-hash//), which resolves beside src/ + // hash store (state//local/baselines/), which resolves beside src/ // rather than under any temp dir — so in-process tests must inject this // instead of seeding baseline files. baselineReader?: (uuid: string) => string | undefined; diff --git a/src/base-dir.ts b/src/base-dir.ts new file mode 100644 index 0000000..1c718f0 --- /dev/null +++ b/src/base-dir.ts @@ -0,0 +1,25 @@ +// The directory the engine works in: the repository that holds src/. +// +// Every module takes it from here. tests/base-dir.test.ts fails when one +// works it out for itself; src/user-agent.ts alone reads a file from where +// it sits, the engine's own package.json, and says why. +// +// The engine's own tests each import tests/engine-sandbox.ts first, which +// names the repository they run in and a temporary directory to use in its +// place. Then nothing such a test does through the engine, and no path it +// derives from it, can reach that repository. A command a test starts from +// a copy of src/ elsewhere keeps working in its own copy. +// +// Nothing else changes the answer. In particular the engine never asks +// whether a test runner is somewhere above it: a command run as a command, +// from a test of yours or anywhere else, works in the repository that holds +// its src/. + +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +export function baseDir(): string { + const own = join(dirname(fileURLToPath(import.meta.url)), ".."); + const sandbox = process.env.VAPI_GITOPS_TEST_ROOT; + return sandbox && own === process.env.VAPI_GITOPS_TEST_REPO ? sandbox : own; +} diff --git a/src/call.ts b/src/call.ts index 21304cb..784d75b 100644 --- a/src/call.ts +++ b/src/call.ts @@ -1,10 +1,12 @@ -import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; import { execSync } from "child_process"; import { existsSync, readFileSync } from "fs"; import { createRequire } from "module"; -import { dirname, join, resolve } from "path"; +import { join, resolve } from "path"; import * as readline from "readline"; import { fileURLToPath } from "url"; +import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; +import { stateFileLabel, stateFileRead } from "./state-paths.ts"; import type { Environment, StateFile } from "./types.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; @@ -14,8 +16,7 @@ const require = createRequire(import.meta.url); // Configuration // ───────────────────────────────────────────────────────────────────────────── -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); type ResourceType = "assistant" | "squad"; @@ -268,10 +269,10 @@ function askUserConfirmation(question: string): Promise { // ───────────────────────────────────────────────────────────────────────────── function loadState(env: Environment): StateFile { - const stateFilePath = join(BASE_DIR, `.vapi-state.${env}.json`); + const stateFilePath = stateFileRead(BASE_DIR, env); if (!existsSync(stateFilePath)) { - console.error(`❌ State file not found: .vapi-state.${env}.json`); + console.error(`❌ State file not found: ${stateFileLabel(BASE_DIR, env)}`); console.error( " Run 'npm run apply -- " + env + "' first to create resources", ); diff --git a/src/check-build.ts b/src/check-build.ts index 05536eb..32d4d88 100644 --- a/src/check-build.ts +++ b/src/check-build.ts @@ -8,6 +8,7 @@ import type { CheckPayloadResult } from "./check-payload.ts"; import { checkPayloadBuild } from "./check-payload.ts"; import { promotionBindingsResolve, promotionStateParse } from "./promotion.ts"; import { orgResourcesRead } from "./resource-parse.ts"; +import { stateFileLabel, stateFileRead } from "./state-paths.ts"; import type { StateFile } from "./types.ts"; export interface CheckJob { @@ -23,10 +24,10 @@ export function checkTargetLabel(target: CheckTarget): string { } function stateRead(root: string, org: string, warnings: string[]): StateFile { - const path = join(root, `.vapi-state.${org}.json`); + const path = stateFileRead(root, org); if (!existsSync(path)) { warnings.push( - `no .vapi-state.${org}.json: references by UUID and credential bindings can't resolve`, + `no ${stateFileLabel(root, org)}: references by UUID and credential bindings can't resolve`, ); return promotionStateParse("{}"); } diff --git a/src/check-cmd.ts b/src/check-cmd.ts index 494194d..f7b0536 100644 --- a/src/check-cmd.ts +++ b/src/check-cmd.ts @@ -13,6 +13,7 @@ import { appendFileSync, mkdirSync, writeFileSync } from "node:fs"; import { dirname, join, relative, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { baseDir } from "./base-dir.ts"; import type { CheckJob } from "./check-build.ts"; import { checkJobsBuild, checkTargetLabel } from "./check-build.ts"; import type { CheckDefinition, ChecksConfig } from "./check-config.ts"; @@ -21,7 +22,7 @@ import type { CheckReportSkipped } from "./check-report.ts"; import { checkReportJson, checkReportMarkdown } from "./check-report.ts"; import type { CheckTargetResult } from "./check-run.ts"; import { checkRunAll, outcomeState } from "./check-run.ts"; -import { checkAffectedBy, changedFilesRead } from "./check-select.ts"; +import { changedFilesRead, checkAffectedBy } from "./check-select.ts"; import type { CommitStatus, GitHubStatusEnv } from "./check-status.ts"; import { AGGREGATE_CONTEXT, @@ -293,7 +294,12 @@ async function liveRun( const vapiClient = vapiClientGet("check"); const vapi = (job: CheckJob): VapiConnection => { const connection = connections.get(job.check.runOrg)!; - return { token: connection.token, baseUrl: connection.baseUrl!, userAgent, vapiClient }; + return { + token: connection.token, + baseUrl: connection.baseUrl!, + userAgent, + vapiClient, + }; }; const post = async (status: CommitStatus) => { if (statusEnv) await commitStatusPost(statusEnv, status); @@ -398,10 +404,7 @@ async function checksRun( export async function checkCommandRun( args = process.argv.slice(2), - root = resolve( - process.env.VAPI_GITOPS_ROOT ?? - fileURLToPath(new URL("..", import.meta.url)), - ), + root = resolve(process.env.VAPI_GITOPS_ROOT ?? baseDir()), ): Promise { let parsed: CheckArgs; try { diff --git a/src/check-select.ts b/src/check-select.ts index f3d91da..f2848e6 100644 --- a/src/check-select.ts +++ b/src/check-select.ts @@ -40,6 +40,7 @@ export function checkPatterns(check: CheckDefinition): string[] { ...ENGINE_PATTERNS, ...orgs.flatMap((org) => [ `resources/${org}/**`, + `state/${org}/**`, `.vapi-state.${org}.json`, ]), ...check.paths, diff --git a/src/commit-step.ts b/src/commit-step.ts new file mode 100644 index 0000000..60cbf8f --- /dev/null +++ b/src/commit-step.ts @@ -0,0 +1,459 @@ +// What the engine can read of the step that commits state after a run. +// +// A run in CI writes state and leaves committing it to a later step the +// engine can't watch. `npm run migrate` moves state into state/ without being +// told to only when a workflow is seen to stage state/, and a CI run stops +// when the workflow running it is seen not to. So this reader fails closed: a +// job counts as staging state/ only for a `git add` it can place, which means +// a plain command in a `run:` step, run from the repository root, that names +// `state` or stages everything. Whatever it can't place counts for nothing: a +// `git add` after a `cd`, inside a quoted string, behind a variable, in a +// helper script or in a commit action. +// +// Config-free, like state-paths.ts. + +import { existsSync, readdirSync, readFileSync } from "fs"; +import { join } from "path"; +import { parse as parseYaml } from "yaml"; + +export type CommitStep = + /** Every job that shows a commit step is seen to stage state/. */ + | { kind: "seen"; stagesOld: boolean } + /** A job is seen to stage the old state file and nothing that could be state/. */ + | { kind: "stale"; file: string } + /** A job may commit state after a run, and it isn't seen to stage state/. */ + | { kind: "unseen"; file: string } + /** No workflow here shows a commit step at all. */ + | { kind: "none" }; + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +// ── A `run:` script, one command at a time ─────────────────────────────── + +interface ShellWord { + text: string; + /** Holds a variable or a command substitution, so its value isn't known. */ + dynamic: boolean; +} + +interface ShellCommand { + words: ShellWord[]; + /** The operator between the command before and this one. */ + after: string; +} + +// The end of a "$(" or "(" that opens at `open`, skipping quoted text. +function parenEnd(text: string, open: number): number { + let depth = 0; + for (let i = open; i < text.length; i++) { + const ch = text[i]; + if (ch === "\\") i++; + else if (ch === "'") { + i = text.indexOf("'", i + 1); + if (i < 0) return -1; + } else if (ch === '"') { + i = doubleQuoteEnd(text, i); + if (i < 0) return -1; + } else if (ch === "(") depth++; + else if (ch === ")" && --depth === 0) return i; + } + return -1; +} + +// The closing quote of a double-quoted string that opens at `open`. A "$(" +// inside it can hold quotes of its own. +function doubleQuoteEnd(text: string, open: number): number { + for (let i = open + 1; i < text.length; i++) { + const ch = text[i]; + if (ch === "\\") i++; + else if (ch === '"') return i; + else if (ch === "$" && text[i + 1] === "(") { + i = parenEnd(text, i + 1); + if (i < 0) return -1; + } + } + return -1; +} + +// Split a script into its commands. `complete` is false when the script holds +// something this doesn't read (a here-document, an unclosed quote): what +// follows it is not returned. +function shellCommandsRead(script: string): { + commands: ShellCommand[]; + complete: boolean; +} { + const text = script.replace(/\\\r?\n/g, ""); + const commands: ShellCommand[] = []; + let words: ShellWord[] = []; + let word: ShellWord | undefined; + let after = "\n"; + const put = (chunk: string, dynamic = false): void => { + word ??= { text: "", dynamic: false }; + word.text += chunk; + word.dynamic ||= dynamic; + }; + const wordEnd = (): void => { + if (word) words.push(word); + word = undefined; + }; + const commandEnd = (operator: string): void => { + wordEnd(); + if (words.length > 0) commands.push({ words, after }); + words = []; + after = operator; + }; + const cut = (): { commands: ShellCommand[]; complete: boolean } => { + commandEnd(""); + return { commands, complete: false }; + }; + let i = 0; + while (i < text.length) { + const ch = text[i]!; + const two = text.slice(i, i + 2); + let end = -1; + if (ch === "'") { + end = text.indexOf("'", i + 1); + if (end < 0) return cut(); + put(text.slice(i + 1, end)); + } else if (ch === '"') { + end = doubleQuoteEnd(text, i); + if (end < 0) return cut(); + const inner = text.slice(i + 1, end); + put(inner, /[$`]/.test(inner)); + } else if (ch === "`") { + end = text.indexOf("`", i + 1); + if (end < 0) return cut(); + put("", true); + } else if (text.startsWith("${{", i)) { + end = text.indexOf("}}", i); + if (end < 0) return cut(); + end += 1; + put("", true); + } else if (two === "$(") { + end = parenEnd(text, i + 1); + if (end < 0) return cut(); + put("", true); + } else if (two === "${") { + end = text.indexOf("}", i); + if (end < 0) return cut(); + put("", true); + } else if (two === "$'") { + end = text.indexOf("'", i + 2); + if (end < 0) return cut(); + put(text.slice(i + 2, end)); + } + if (end >= 0) { + i = end + 1; + continue; + } + if (ch === "\\") { + put(text[i + 1] ?? ""); + i += 2; + } else if (ch === "$") { + put("$", true); + i++; + } else if (ch === "#" && !word) { + const eol = text.indexOf("\n", i); + i = eol < 0 ? text.length : eol; + } else if (two === "<<" && text[i + 2] !== "<") { + return cut(); + } else if (ch === "\n") { + commandEnd("\n"); + i++; + } else if (/\s/.test(ch)) { + wordEnd(); + i++; + } else if (two === "&&" || two === "||" || two === ";;") { + commandEnd(two); + i += 2; + } else if (ch === "&" && (text[i - 1] === ">" || text[i + 1] === ">")) { + put(ch); + i++; + } else if (ch === ";" || ch === "|" || ch === "&") { + commandEnd(ch); + i++; + } else if (ch === "(" || ch === ")") { + commandEnd(after); + commands.push({ words: [{ text: ch, dynamic: false }], after }); + after = ch; + i++; + } else { + put(ch); + i++; + } + } + commandEnd(""); + return { commands, complete: true }; +} + +// ── What a `git add` stages ────────────────────────────────────────────── + +interface GitAdd { + /** Stages state/, when run from the repository root. */ + state: boolean; + /** Stages .vapi-state.*.json, when run from the repository root. */ + old: boolean; + /** Stages everything, so it only counts as a command of its own. */ + everything: boolean; + /** Every pathspec was read and none of them could be part of state/. */ + plain: boolean; +} + +const UNREAD: GitAdd = { + state: false, + old: false, + everything: false, + plain: false, +}; + +// Flags that don't change which paths are staged. +const ADD_FLAGS = new Set(["-A", "--all", "-f", "--force", "-v", "--verbose"]); + +function gitAddRead(args: ShellWord[]): GitAdd { + let all = false; + let pathsOnly = false; + const paths: string[] = []; + for (let i = 0; i < args.length; i++) { + const { text, dynamic } = args[i]!; + // A redirection, with its target attached or as the next word. + if (/^(\d*(>>?|<)|&>>?)$/.test(text)) i++; + else if (/^(\d*[<>]|&>)/.test(text)) continue; + else if (dynamic) return UNREAD; + else if (!pathsOnly && text === "--") pathsOnly = true; + else if (!pathsOnly && text.startsWith("-")) { + if (!ADD_FLAGS.has(text)) return UNREAD; + if (text === "-A" || text === "--all") all = true; + } else paths.push(text); + } + if (paths.length === 0) + return all + ? { state: true, old: true, everything: true, plain: true } + : UNREAD; + const read: GitAdd = { + state: false, + old: false, + everything: false, + plain: true, + }; + for (let path of paths) { + const magic = /^:\(([a-z,]*)\)/.exec(path); + if (magic) { + if (!/^(glob|top|literal|,)*$/.test(magic[1]!)) return UNREAD; + path = path.slice(magic[0].length); + } else if (path.startsWith(":/")) path = path.slice(2); + else if (path.startsWith(":")) return UNREAD; + path = path.replace(/^(\.\/)+/, "").replace(/\/+$/, ""); + if (path === "" || path === ".") + read.state = read.old = read.everything = true; + else if (/^state(\/\*\*)?$/.test(path)) read.state = true; + else if (/^\.vapi-state\.[^/]*\.json$/.test(path)) read.old = true; + else if (/^state\//.test(path) || /^[*?[]/.test(path)) read.plain = false; + } + return read; +} + +const BLOCK_OPEN = new Map([ + ["if", "if"], + ["for", "loop"], + ["while", "loop"], + ["until", "loop"], + ["select", "loop"], + ["case", "case"], +]); +const BLOCK_CLOSE = new Map([ + ["fi", "if"], + ["done", "loop"], + ["esac", "case"], + ["}", "brace"], +]); + +// Every `git add` a script runs, read as run from the repository root unless +// `atRoot` is false. One counts only as a command of its own: not after a +// change of directory, not after "||" or a pipe, not inside a loop, a +// function, a group or a subshell. An `if` around it is allowed when it names +// its paths, because that is how a step guards a path that may not exist. +function scriptAddsRead(script: string, atRoot: boolean): GitAdd[] { + const { commands, complete } = shellCommandsRead(script); + const adds: GitAdd[] = []; + const blocks: string[] = []; + let placed = atRoot; + let condition = false; + for (const command of commands) { + let words = command.words; + let first = words[0]!.text; + if (first === "(") blocks.push("paren"); + else if (first === ")" && blocks.at(-1) === "paren") blocks.pop(); + else if (BLOCK_CLOSE.has(first) && blocks.at(-1) === BLOCK_CLOSE.get(first)) + blocks.pop(); + const opened = BLOCK_OPEN.get(first); + if (opened) { + blocks.push(opened); + condition = first !== "for" && first !== "select" && first !== "case"; + continue; + } + if (first === "elif") condition = true; + if (first === "then" || first === "do" || first === "else") { + condition = false; + words = words.slice(1); + } + while (words[0]?.text === "{" || words[0]?.text === "function") { + blocks.push("brace"); + words = words.slice(words[0].text === "{" ? 1 : words.length); + } + if (words.length > 1 && words.at(-1)!.text === "{") blocks.push("brace"); + if (words[0]?.text === "builtin" || words[0]?.text === "command") + words = words.slice(1); + first = words[0]?.text ?? ""; + // From here on the script may be somewhere else, or in another repository. + if ( + ["cd", "pushd", "popd", "source", ".", "eval"].includes(first) || + words.some((word) => /^GIT_(DIR|WORK_TREE|INDEX_FILE)=/.test(word.text)) + ) + placed = false; + if (first !== "git" || words[1]?.text !== "add" || words[1].dynamic) + continue; + const add = gitAddRead(words.slice(2)); + const alone = + placed && + !condition && + command.after !== "||" && + command.after !== "|" && + blocks.every((block) => block === "if") && + (!add.everything || blocks.length === 0); + adds.push(alone ? add : UNREAD); + } + // What follows a here-document or an unclosed quote was not read. + if (!complete) adds.push(UNREAD); + return adds; +} + +// ── A job, a workflow, the repository ───────────────────────────────────── + +type JobRead = "stages-both" | "stages" | "stale" | "unseen" | "quiet"; + +const GIT_ADD = /\bgit\b(?:\s+-\S+(?:\s+[^-\s]\S*)?)*\s+add\b/g; + +function permissionsWrite(permissions: unknown): boolean | undefined { + if (permissions === undefined) return undefined; + return ( + permissions === "write-all" || + (isRecord(permissions) && permissions.contents === "write") + ); +} + +function workingDirectory(holder: unknown): unknown { + if (!isRecord(holder) || !isRecord(holder.defaults)) return undefined; + return isRecord(holder.defaults.run) + ? holder.defaults.run["working-directory"] + : undefined; +} + +function jobRead(job: unknown, workflow: Record): JobRead { + if (!isRecord(job)) return "unseen"; + const steps = Array.isArray(job.steps) ? job.steps.filter(isRecord) : []; + // A checkout into a sub-folder, or a default working directory, means no + // step of this job runs at the repository root. + const jobAtRoot = + workingDirectory(job) === undefined && + workingDirectory(workflow) === undefined && + !steps.some( + (step) => + typeof step.uses === "string" && + step.uses.startsWith("actions/checkout") && + isRecord(step.with) && + step.with.path !== undefined, + ) && + !/GIT_(DIR|WORK_TREE|INDEX_FILE)/.test(JSON.stringify(job.env ?? {})) && + !/GIT_(DIR|WORK_TREE|INDEX_FILE)/.test(JSON.stringify(workflow.env ?? {})); + const adds: GitAdd[] = []; + let mentions = 0; + let commits = false; + for (const step of steps) { + if (typeof step.run !== "string") continue; + // Counted outside comments, to compare with the ones that were read. + mentions += step.run.replace(/^\s*#.*$/gm, "").match(GIT_ADD)?.length ?? 0; + if (/\bgit\b[^\n]*\b(add|commit|push)\b/.test(step.run)) commits = true; + const shell = typeof step.shell === "string" ? step.shell : "bash"; + const atRoot = + jobAtRoot && + step["working-directory"] === undefined && + !/GIT_(DIR|WORK_TREE|INDEX_FILE)/.test(JSON.stringify(step.env ?? {})) && + /^(bash|sh)\b/.test(shell); + adds.push(...scriptAddsRead(step.run, atRoot)); + } + if (adds.some((add) => add.state)) + return adds.some((add) => add.old) ? "stages-both" : "stages"; + // Seen to stage the old file, with every `git add` in the job read and + // none of them able to stage state/. + if ( + adds.some((add) => add.old) && + adds.every((add) => add.plain) && + adds.length === mentions + ) + return "stale"; + // A job whose token can't write and that runs no git command to commit + // with shows no commit step. Anything else may commit in a way not read. + const writes = + permissionsWrite(job.permissions) ?? permissionsWrite(workflow.permissions); + return writes === false && !commits ? "quiet" : "unseen"; +} + +// A file that doesn't parse may commit in a way not read. +function workflowJobsRead(path: string): JobRead[] { + let doc: unknown; + try { + doc = parseYaml(readFileSync(path, "utf8")); + } catch { + return ["unseen"]; + } + if (!isRecord(doc) || !isRecord(doc.jobs)) return ["unseen"]; + const workflow = doc; + return Object.values(doc.jobs).map((job) => jobRead(job, workflow)); +} + +function workflowsRead(rootDir: string): { file: string; jobs: JobRead[] }[] { + const dir = join(rootDir, ".github", "workflows"); + if (!existsSync(dir)) return []; + return readdirSync(dir) + .filter((name) => /\.ya?ml$/.test(name)) + .sort() + .map((name) => ({ + file: `.github/workflows/${name}`, + jobs: workflowJobsRead(join(dir, name)), + })); +} + +/** + * What is seen of the step that commits state after a run. In GitHub Actions + * the engine knows which workflow is running it and reads that one alone; + * anywhere else it reads every workflow in .github/workflows/. + * + * "seen" needs every job that shows a commit step to stage state/. A pipeline + * the engine has no file for (another CI system, a script that commits with + * its own token) is not read at all, which is why `npm run migrate` always + * says what the commit step has to stage. + */ +export function commitStepRead( + rootDir: string, + env: NodeJS.ProcessEnv = process.env, +): CommitStep { + const every = workflowsRead(rootDir); + const running = + env.GITHUB_ACTIONS === "true" + ? /\.github\/workflows\/[^@]+/.exec(env.GITHUB_WORKFLOW_REF ?? "")?.[0] + : undefined; + const own = every.filter((workflow) => workflow.file === running); + const workflows = own.length > 0 ? own : every; + const stale = workflows.find((workflow) => workflow.jobs.includes("stale")); + if (stale) return { kind: "stale", file: stale.file }; + const unseen = workflows.find((workflow) => workflow.jobs.includes("unseen")); + if (unseen) return { kind: "unseen", file: unseen.file }; + const staging = workflows.flatMap((workflow) => + workflow.jobs.filter((job) => job !== "quiet"), + ); + return staging.length > 0 + ? { kind: "seen", stagesOld: staging.every((job) => job === "stages-both") } + : { kind: "none" }; +} diff --git a/src/config.ts b/src/config.ts index 047960f..53911fd 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1,8 +1,8 @@ import { existsSync, readFileSync } from "fs"; -import { basename, dirname, join, relative, resolve } from "path"; -import { fileURLToPath } from "url"; +import { basename, join, relative, resolve } from "path"; import { parseAdoptArgs } from "./adopt.ts"; import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; import { ignorePatternsRead, matchesIgnore as matchesIgnorePatterns, @@ -235,8 +235,7 @@ function loadEnvFile(env: string, baseDir: string): Record { // ───────────────────────────────────────────────────────────────────────────── // Base directory for the gitops project -const __dirname = dirname(fileURLToPath(import.meta.url)); -export const BASE_DIR = join(__dirname, ".."); +export const BASE_DIR = baseDir(); // Parse environment, flags, and load env files export const VAPI_ENV = parseEnvironment(); @@ -282,7 +281,6 @@ process.env.VAPI_TOKEN = VAPI_TOKEN; // Paths export const RESOURCES_DIR = join(BASE_DIR, "resources", VAPI_ENV); -export const STATE_FILE_PATH = join(BASE_DIR, `.vapi-state.${VAPI_ENV}.json`); // ───────────────────────────────────────────────────────────────────────────── // Update Exclusions - Keys to remove when updating resources (PATCH) diff --git a/src/drift.ts b/src/drift.ts index 18449e4..d7bb365 100644 --- a/src/drift.ts +++ b/src/drift.ts @@ -126,7 +126,7 @@ export async function checkDriftForUpdate(options: { reason: "no-baseline", message: ` ⚠️ drift check skipped for ${resourceLabel} ${resourceId}: ` + - `no baseline in .vapi-state-hash. Run \`npm run pull\` to establish one.`, + `no baseline on this machine. Run \`npm run pull\` to establish one.`, }; } diff --git a/src/hash-store.ts b/src/hash-store.ts index 1c9712f..d35868b 100644 --- a/src/hash-store.ts +++ b/src/hash-store.ts @@ -1,8 +1,9 @@ // Per-developer drift baseline store. // // The "last known platform state" content hash for each resource lives here, -// in `.vapi-state-hash//` — one file per resource, filename is the -// platform UUID, contents are the sha256 baseline hash. This is the hash a +// in `state//local/baselines/` (`.vapi-state-hash//` +// while the org's state is still in the old layout) — one file per resource, +// filename is the platform UUID, contents are the sha256 baseline hash. This is the hash a // push compares against the live dashboard to decide whether someone changed // the resource out of band since I last pulled or pushed it. // @@ -19,40 +20,64 @@ import { existsSync, mkdirSync, readFileSync } from "fs"; import { rename, writeFile } from "fs/promises"; -import { dirname, join } from "path"; -import { fileURLToPath } from "url"; +import { join } from "path"; +import { baseDir } from "./base-dir.ts"; +import { + baselinesDir, + baselinesLegacyDir, + baselinesWriteDir, +} from "./state-paths.ts"; // Same expression as config.ts: the repo root is one level up from src/. -const BASE_DIR = join(dirname(fileURLToPath(import.meta.url)), ".."); +const BASE_DIR = baseDir(); -// Top-level store directory. Per-org subfolders live beneath it. Exported so -// the migration can locate every org's baselines and so `.gitignore` reasoning -// stays in one place. -export const HASH_STORE_ROOT = join(BASE_DIR, ".vapi-state-hash"); +// Exported so the migration works on the same repository root. +export const HASH_STORE_BASE_DIR = BASE_DIR; // Guard against a UUID that would escape its org folder. Platform UUIDs never // contain these, but reading them straight into a path warrants a check. function assertSafeUuid(uuid: string): void { - if (!uuid || uuid.includes("/") || uuid.includes("\\") || uuid.includes("..")) { - throw new Error(`Refusing to use unsafe hash-store key: ${JSON.stringify(uuid)}`); + if ( + !uuid || + uuid.includes("/") || + uuid.includes("\\") || + uuid.includes("..") + ) { + throw new Error( + `Refusing to use unsafe hash-store key: ${JSON.stringify(uuid)}`, + ); } } +// Where baselines are written: state//local/baselines/, or +// .vapi-state-hash// while the org's state is still in the old layout. export function hashStoreDir(org: string): string { - return join(HASH_STORE_ROOT, org); + return baselinesWriteDir(BASE_DIR, org); } -function baselinePath(org: string, uuid: string): string { +// Every place a baseline can be, the one that is written first. +function baselinePaths(org: string, uuid: string): string[] { assertSafeUuid(uuid); - return join(hashStoreDir(org), uuid); + const dirs = new Set([ + hashStoreDir(org), + baselinesDir(BASE_DIR, org), + baselinesLegacyDir(BASE_DIR, org), + ]); + return [...dirs].map((dir) => join(dir, uuid)); } // Read the baseline hash for a resource, or undefined if none has been // recorded yet (fresh clone, never pulled/pushed). Undefined maps to the // `no-baseline` drift direction — the caller proceeds without blocking. +// +// After `npm run migrate` on another machine, this machine's baselines still +// sit in .vapi-state-hash// until its next pull, push or apply moves the +// folder. Read from both places, so a read-only command sees the same drift. export function readBaseline(org: string, uuid: string): string | undefined { - const path = baselinePath(org, uuid); - if (!existsSync(path)) return undefined; + const path = baselinePaths(org, uuid).find((candidate) => + existsSync(candidate), + ); + if (!path) return undefined; const contents = readFileSync(path, "utf-8").trim(); return contents.length > 0 ? contents : undefined; } @@ -66,7 +91,7 @@ export async function writeBaseline( uuid: string, hash: string, ): Promise { - const path = baselinePath(org, uuid); + const path = baselinePaths(org, uuid)[0]!; mkdirSync(hashStoreDir(org), { recursive: true }); const tmpPath = `${path}.tmp`; await writeFile(tmpPath, `${hash}\n`); @@ -77,8 +102,6 @@ export async function writeBaseline( // no longer exists on the platform), mirroring the existing // `delete stateSection[resourceId]` recovery. Missing file is a no-op. export async function deleteBaseline(org: string, uuid: string): Promise { - const path = baselinePath(org, uuid); - if (!existsSync(path)) return; const { rm } = await import("fs/promises"); - await rm(path, { force: true }); + for (const path of baselinePaths(org, uuid)) await rm(path, { force: true }); } diff --git a/src/interactive.ts b/src/interactive.ts index 67eb822..71bfb1b 100644 --- a/src/interactive.ts +++ b/src/interactive.ts @@ -1,13 +1,14 @@ -import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; import { confirm, select } from "@inquirer/prompts"; import { execSync } from "child_process"; import { existsSync, readdirSync, readFileSync, statSync } from "fs"; -import { dirname, extname, join, relative } from "path"; -import { fileURLToPath } from "url"; +import { extname, join, relative } from "path"; +import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js"; // slug-utils is config-free (no config.ts side effects) — safe to import in // the launcher, which runs before any org/token is selected. import { isBackupCopyFile } from "./slug-utils.ts"; +import { stateFileLabel, stateFileRead } from "./state-paths.ts"; import type { StateFile } from "./types.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; @@ -15,8 +16,7 @@ import { userAgentGet, vapiClientGet } from "./user-agent.ts"; // Constants // ───────────────────────────────────────────────────────────────────────────── -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/; @@ -417,7 +417,7 @@ function gitStatusLabel(code: GitStatusCode): string { // ───────────────────────────────────────────────────────────────────────────── function loadKnownUuids(slug: string): Set { - const statePath = join(BASE_DIR, `.vapi-state.${slug}.json`); + const statePath = stateFileRead(BASE_DIR, slug); if (!existsSync(statePath)) return new Set(); try { const raw = readFileSync(statePath, "utf-8"); @@ -1085,10 +1085,10 @@ export async function runInteractiveCall(): Promise { const slug = await selectOrg("call"); - const stateFile = join(BASE_DIR, `.vapi-state.${slug}.json`); + const stateFile = stateFileRead(BASE_DIR, slug); if (!existsSync(stateFile)) { console.log( - c.yellow(`\n No state file found (.vapi-state.${slug}.json).`), + c.yellow(`\n No state file found (${stateFileLabel(BASE_DIR, slug)}).`), ); console.log(c.yellow(" Run pull first to populate resource mappings.\n")); return; diff --git a/src/migrate-cmd.ts b/src/migrate-cmd.ts index 2789592..a3c955c 100644 --- a/src/migrate-cmd.ts +++ b/src/migrate-cmd.ts @@ -1,30 +1,61 @@ // CLI entry: `npm run migrate` // -// One-time migration of every `.vapi-state..json` in the repo from the -// legacy fat state file to the slim `name → { uuid }` form + the -// `.vapi-state-hash//` baseline store. Takes NO org argument and +// One-time migration of every org's state: from the legacy fat state file to +// the slim `name → { uuid }` form + the per-machine baseline store, and +// from the old root-level files into `state//`. Takes NO org argument and // needs NO VAPI_TOKEN — it's a pure local file operation, so it deliberately // does not import `config.ts` (which would force an org + token at load). // // Idempotent: re-running after migration seeds nothing and rewrites nothing. +// +// This is the only command that moves committed state. Before it moves +// anything it says what the step that commits state after a run has to stage. +// +// `--commit-step-stages-state` is a person's word that whatever commits state +// after a run stages state/. It is only needed where the engine can't see +// that for itself, and without it nothing moves there. import { resolve } from "path"; import { fileURLToPath } from "url"; -import { migrateAll } from "./migrate-hash-store.ts"; +import { HASH_STORE_BASE_DIR } from "./hash-store.ts"; +import { migrateAll, migrateMovedLine } from "./migrate-hash-store.ts"; +import { + COMMIT_STEP_FLAG, + commitStepAcknowledge, + stateLayout, + stateMoveRead, + stateOrgsList, +} from "./state-paths.ts"; async function main(): Promise { console.log( "═══════════════════════════════════════════════════════════════", ); - console.log("🧬 Vapi GitOps Migrate — state file → hash store"); + console.log("🧬 Vapi GitOps Migrate — state files → state//"); console.log( "═══════════════════════════════════════════════════════════════\n", ); + const args = process.argv.slice(2); + const unknown = args.filter((arg) => arg !== COMMIT_STEP_FLAG); + if (unknown.length > 0) + throw new Error( + `Unrecognized argument: ${unknown.join(" ")}. The only option is ${COMMIT_STEP_FLAG}.`, + ); + + if (args.includes(COMMIT_STEP_FLAG)) + console.log(`${commitStepAcknowledge(HASH_STORE_BASE_DIR)}\n`); + // Said before anything moves, and only when there is something to move. + const toMove = stateOrgsList(HASH_STORE_BASE_DIR).some( + (org) => stateLayout(HASH_STORE_BASE_DIR, org) === "root", + ); + const move = stateMoveRead(HASH_STORE_BASE_DIR); + if (toMove) console.log(`${move.lines.join("\n")}\n`); + const result = await migrateAll(); if (result.orgs.length === 0) { - console.log(" No .vapi-state..json files found — nothing to migrate."); + console.log(" No state files found — nothing to migrate."); return; } @@ -39,13 +70,18 @@ async function main(): Promise { `${status} — seeded ${org.seeded} baseline(s)` + (org.skipped > 0 ? `, ${org.skipped} already present` : ""), ); + const moved = migrateMovedLine(org); + if (moved) console.log(` ${moved}`); } console.log( `\n✅ Migration complete: ${result.orgs.length} org(s), ` + - `${totalSlimmed} state file(s) slimmed, ${totalSeeded} baseline(s) seeded ` + - `into .vapi-state-hash/.`, + `${totalSlimmed} state file(s) slimmed, ${totalSeeded} baseline(s) seeded.`, ); + if (toMove && !move.open) + console.log( + "⚠️ State stays where it is. What the commit step needs first is above.", + ); } const isMainModule = diff --git a/src/migrate-hash-store.ts b/src/migrate-hash-store.ts index 94ce990..d82b24e 100644 --- a/src/migrate-hash-store.ts +++ b/src/migrate-hash-store.ts @@ -1,5 +1,6 @@ // One-time migration from the legacy fat state file to the slim -// `name → { uuid }` state file + `.vapi-state-hash//` baseline store. +// `name → { uuid }` state file + the per-machine baseline store, and from +// the old file locations into `state//` (see state-paths.ts). // // This whole module is a REMOVABLE SEAM. When the migration is no longer // needed, delete this file + `migrate-cmd.ts`, remove the `assertStateMigrated` @@ -7,20 +8,29 @@ // script. Nothing else references it. // // CONFIG-FREE by design (no `config.ts` import): `migrate` runs without an org -// argument or a VAPI_TOKEN, across every `.vapi-state..json` in the repo -// at once. +// argument or a VAPI_TOKEN, across every org's state file in the repo at once. -import { existsSync, readdirSync, readFileSync } from "fs"; +import { existsSync, readFileSync } from "fs"; import { rename, writeFile } from "fs/promises"; -import { basename, dirname, join } from "path"; -import { HASH_STORE_ROOT, readBaseline, writeBaseline } from "./hash-store.ts"; +import { relative } from "path"; +import { + HASH_STORE_BASE_DIR, + readBaseline, + writeBaseline, +} from "./hash-store.ts"; +import { + commitStepAsk, + STATE_DIR, + stateFileRead, + stateMove, + stateMoveRead, + stateOrgsList, +} from "./state-paths.ts"; import { asResourceState, sortedKeysReplacer } from "./state-serialize.ts"; import type { ResourceState } from "./types.ts"; -// Repo root, derived from the hash store's known location (single source). -const BASE_DIR = dirname(HASH_STORE_ROOT); - -const STATE_FILE_RE = /^\.vapi-state\.(.+)\.json$/; +// Repo root, shared with the hash store (single source). +const BASE_DIR = HASH_STORE_BASE_DIR; export interface OrgMigrationResult { org: string; @@ -28,10 +38,13 @@ export interface OrgMigrationResult { seeded: number; // baselines written into the hash store skipped: number; // legacy hashes ignored because a baseline already existed slimmed: boolean; // whether the state file was rewritten to slim form + moved: string[]; // what moved into state//; empty when nothing did } export interface MigrationResult { orgs: OrgMigrationResult[]; + /** Set when nothing moved: what the commit step has to stage first. */ + commitStepAsk?: string[]; } // A legacy entry is anything that isn't already exactly `{ uuid: string }`: @@ -72,22 +85,12 @@ function isSection(value: unknown): value is Record { return !!value && typeof value === "object" && !Array.isArray(value); } -function discoverStateFiles( - baseDir: string, -): Array<{ org: string; path: string }> { - const out: Array<{ org: string; path: string }> = []; - for (const name of readdirSync(baseDir)) { - const m = STATE_FILE_RE.exec(name); - if (!m || !m[1]) continue; - out.push({ org: m[1], path: join(baseDir, name) }); - } - return out.sort((a, b) => a.org.localeCompare(b.org)); -} - async function migrateOne( + baseDir: string, org: string, - stateFilePath: string, + move: boolean, ): Promise { + const stateFilePath = stateFileRead(baseDir, org); const raw = JSON.parse(readFileSync(stateFilePath, "utf-8")) as Record< string, unknown @@ -135,28 +138,48 @@ async function migrateOne( await rename(tmpPath, stateFilePath); } + // Slim first, in place, then move: each step leaves one complete state + // file. + const moved = move ? stateMove(baseDir, org) : []; return { org, - stateFile: basename(stateFilePath), + stateFile: relative(baseDir, stateFileRead(baseDir, org)), seeded, skipped, slimmed: needsSlim, + moved, }; } -// Migrate every `.vapi-state..json` in the repo root: seed missing -// baselines from legacy hashes, then rewrite each state file to slim form. -// Idempotent — re-running on already-slim files seeds nothing and rewrites -// nothing. +// Migrate every org's state file, in either location: seed missing baselines +// from legacy hashes, rewrite the file to slim form, then move the org's +// engine files into `state//`. Idempotent — re-running on a migrated +// repo seeds nothing, rewrites nothing and moves nothing. +// +// This is the only place committed state moves. It moves when every commit +// step in .github/workflows/ is seen to stage state/, or when a person has +// said theirs does (commitStepAcknowledge). Otherwise files are slimmed in +// place and nothing moves. export async function migrateAll( baseDir: string = BASE_DIR, ): Promise { - const files = discoverStateFiles(baseDir); + const { open } = stateMoveRead(baseDir); const orgs: OrgMigrationResult[] = []; - for (const { org, path } of files) { - orgs.push(await migrateOne(org, path)); + for (const org of stateOrgsList(baseDir)) { + orgs.push(await migrateOne(baseDir, org, open)); } - return { orgs }; + return { orgs, commitStepAsk: commitStepAsk(baseDir) }; +} + +/** The line `npm run migrate` prints for what moved for one org. */ +export function migrateMovedLine(org: OrgMigrationResult): string | undefined { + if (org.moved.length === 0) return undefined; + return ( + `📦 Moved ${org.moved.join(", ")} into ${STATE_DIR}/${org.org}/.` + + (org.moved.some((label) => !label.endsWith("/")) + ? " Commit the removal together with the new folder." + : "") + ); } // Guard called at the entry of pull/push/apply. Throws if the given state file @@ -165,7 +188,8 @@ export async function migrateAll( // must not be blocked). Shape-only check — never inspects the hash store. // // The path is passed in (rather than read from config) so this module stays -// config-free; org-scoped callers already have STATE_FILE_PATH loaded. +// config-free; callers pass stateFileRead(), which names the file in +// whichever layout the org is in. export function assertStateMigrated(stateFilePath: string): void { if (!existsSync(stateFilePath)) return; @@ -188,8 +212,7 @@ export function assertStateMigrated(stateFilePath: string): void { throw new Error( `State file ${stateFilePath} is in the legacy format ` + `(carries per-resource hashes/timestamps). Run \`npm run migrate\` ` + - `first to slim every state file and seed the .vapi-state-hash/ ` + - `baseline store.`, + `first to slim every state file and seed the drift baselines.`, ); } } diff --git a/src/org-pin.ts b/src/org-pin.ts index 6ed9935..1df67af 100644 --- a/src/org-pin.ts +++ b/src/org-pin.ts @@ -4,27 +4,28 @@ // command reads and writes. A key for the wrong org (an exported variable, a // copied .env file, a mislabelled CI secret) would pull another org's // resources into the folder, or push this folder into another org. The first -// command that can see the key's org records it in resources//.vapi-org.json, -// which is committed with the folder. Every later command checks the key -// against it and refuses a mismatch before any request. +// command that can see the key's org records it in state//org.json, +// which is committed. Every later command checks the key against it and +// refuses a mismatch before any request. A pin written before state/ existed +// sits in resources//.vapi-org.json and is read from there until the +// next pull, push or apply moves it (state-paths.ts). // // A private key can't ask which org it belongs to (/org and /org/me reject // private keys), so the org ID comes from the first resource the key can -// list. Promotion skips dotfiles, so the pin never travels to another org. +// list. The pin lives outside resources/, so it never travels to another org. // // Config-free so rollback and tests can check any org. -import { existsSync, readFileSync, writeFileSync } from "node:fs"; -import { join } from "node:path"; +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { dirname, join, relative } from "node:path"; import { orgApiKeyVar } from "./api-key.ts"; +import { orgPinFileRead, orgPinFileWrite } from "./state-paths.ts"; import { - type VapiConnection, VapiApiError, + type VapiConnection, vapiFetchJson, } from "./vapi-client.ts"; -export const ORG_PIN_FILE = ".vapi-org.json"; - // Cheap one-item list calls, most likely non-empty first. Every item carries // the orgId it belongs to. export const ORG_PROBE_ENDPOINTS = [ @@ -70,13 +71,14 @@ const probeFetchDefault: OrgProbeFetch = (connection, endpoint) => maxRetries: 2, }); -export function orgPinPath(rootDir: string, org: string): string { - return join(rootDir, "resources", org, ORG_PIN_FILE); +/** The pin file as a person names it: its path from the repository root. */ +export function orgPinLabel(rootDir: string, org: string): string { + return relative(rootDir, orgPinFileRead(rootDir, org)).replaceAll("\\", "/"); } /** The org ID this folder is pinned to, if any. A corrupt pin file throws. */ export function orgPinRead(rootDir: string, org: string): string | undefined { - const path = orgPinPath(rootDir, org); + const path = orgPinFileRead(rootDir, org); if (!existsSync(path)) return undefined; let parsed: unknown; try { @@ -84,7 +86,7 @@ export function orgPinRead(rootDir: string, org: string): string | undefined { } catch (error) { const reason = error instanceof Error ? error.message : String(error); throw new Error( - `Can't read resources/${org}/${ORG_PIN_FILE}: ${reason}. Restore it from git.`, + `Can't read ${orgPinLabel(rootDir, org)}: ${reason}. Restore it from git.`, ); } const orgId = (parsed as { orgId?: unknown } | null)?.orgId; @@ -133,12 +135,14 @@ export interface OrgPinCheckArgs { } /** - * Check the key against resources//.vapi-org.json. Pins an unpinned + * Check the key against state//org.json. Pins an unpinned * folder to the key's org on first sight. Throws OrgPinMismatchError when the * key belongs to another org, or to an empty org while the folder is pinned * to one that had resources. */ -export async function orgPinCheck(args: OrgPinCheckArgs): Promise { +export async function orgPinCheck( + args: OrgPinCheckArgs, +): Promise { const { rootDir, org, connection, keySource } = args; // Set only by tests/no-vapi-api.ts: tests that stub fetch count requests. if (process.env.VAPI_GITOPS_ORG_PIN === "off") return { kind: "unpinned" }; @@ -149,21 +153,24 @@ export async function orgPinCheck(args: OrgPinCheckArgs): Promise if (!pinned && !folderExists) return { kind: "unpinned" }; const keyOrg = await keyOrgFetch(connection, args.probeFetch); const folder = `resources/${org}/`; + const pinLabel = orgPinLabel(rootDir, org); const fix = ` Use ${org}'s own key, for example by exporting ${orgApiKeyVar(org)}.\n` + - ` If this folder really moved to another org, delete ${folder}${ORG_PIN_FILE}\n` + + ` If this folder really moved to another org, delete ${pinLabel}\n` + ` in a reviewed commit and run the command again.`; if (keyOrg.kind === "found") { if (pinned === keyOrg.orgId) return { kind: "match" }; if (pinned) throw new OrgPinMismatchError( - `The API key from ${keySource} belongs to Vapi org ${keyOrg.orgId}, but ${folder} is pinned to org ${pinned} (${ORG_PIN_FILE}).\n` + + `The API key from ${keySource} belongs to Vapi org ${keyOrg.orgId}, but ${folder} is pinned to org ${pinned} (${pinLabel}).\n` + ` Stopped before reading or changing anything.\n${fix}`, ); if (!folderExists) return { kind: "unpinned" }; + const pinPath = orgPinFileWrite(rootDir, org); + mkdirSync(dirname(pinPath), { recursive: true }); writeFileSync( - orgPinPath(rootDir, org), + pinPath, `${JSON.stringify({ orgId: keyOrg.orgId }, null, 2)}\n`, ); return { kind: "pinned", orgId: keyOrg.orgId }; @@ -175,7 +182,7 @@ export async function orgPinCheck(args: OrgPinCheckArgs): Promise // emptied out, and pushing would fill it with this folder's resources. if (keyOrg.kind === "empty") throw new OrgPinMismatchError( - `The API key from ${keySource} belongs to an org with no resources, but ${folder} is pinned to org ${pinned} (${ORG_PIN_FILE}).\n` + + `The API key from ${keySource} belongs to an org with no resources, but ${folder} is pinned to org ${pinned} (${pinLabel}).\n` + ` Stopped before reading or changing anything.\n${fix}`, ); return { kind: "unverified" }; diff --git a/src/promote-cmd.ts b/src/promote-cmd.ts index a219b17..f1cc39b 100644 --- a/src/promote-cmd.ts +++ b/src/promote-cmd.ts @@ -2,16 +2,11 @@ import { execFileSync } from "node:child_process"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { baseDir } from "./base-dir.ts"; import type { CheckDefinition } from "./check-config.ts"; import type { OrgConnection } from "./org-connection.ts"; import { childRun, connectionLoad, tokensParse } from "./org-connection.ts"; import type { PromotionConfig, PromotionPipeline } from "./promotion.ts"; -import type { PromotionGateResult } from "./promotion-gate.ts"; -import { - promotionChecksLoad, - promotionGatePlanLine, - promotionGateRun, -} from "./promotion-gate.ts"; import { promotionConfigParse, promotionPlanApply, @@ -19,6 +14,18 @@ import { promotionStateParse, promotionTransitionValidate, } from "./promotion.ts"; +import type { PromotionGateResult } from "./promotion-gate.ts"; +import { + promotionChecksLoad, + promotionGatePlanLine, + promotionGateRun, +} from "./promotion-gate.ts"; +import { + OLD_LAYOUT_NOTICE, + stateFileRead, + stateLayout, + stateNoticesPrint, +} from "./state-paths.ts"; interface PromotionArguments { pipeline?: string; @@ -35,9 +42,7 @@ interface PromotionTransition { definition: PromotionPipeline; } -const ROOT_DIR = resolve( - process.env.VAPI_GITOPS_ROOT ?? fileURLToPath(new URL("..", import.meta.url)), -); +const ROOT_DIR = resolve(process.env.VAPI_GITOPS_ROOT ?? baseDir()); // Files that transitions which finished applying left changed, one // `\t` line each: the content as it stood when that transition @@ -219,7 +224,7 @@ function appliedPathsRecord(org: string): void { } function stateLoad(org: string) { - const path = resolve(ROOT_DIR, `.vapi-state.${org}.json`); + const path = stateFileRead(ROOT_DIR, org); if (!existsSync(path)) throw new Error( `Missing state for ${org}; run promotion with --apply to bootstrap bindings first`, @@ -327,6 +332,13 @@ export async function promotionCommandRun( const file = resolve(ROOT_DIR, APPLIED_PATHS_FILE); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, ""); + // Said once here, so the pull and push of each org don't repeat it. + const orgs = transitionsBuild(config, parsed).flatMap((transition) => [ + transition.source, + transition.target, + ]); + if (orgs.some((org) => stateLayout(ROOT_DIR, org) === "root")) + stateNoticesPrint([OLD_LAYOUT_NOTICE]); } // Applying a deletion removes the intermediate org's state entry. Carry the // reviewed authorization forward so the same deletion can reach later orgs. diff --git a/src/pull.ts b/src/pull.ts index 95a8c86..ec7d2a3 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -22,7 +22,6 @@ import { loadIgnorePatterns, matchesIgnore, RESOURCES_DIR, - STATE_FILE_PATH, VAPI_BASE_URL, VAPI_ENV, VAPI_TOKEN, @@ -34,7 +33,6 @@ import { formatDriftLabel, } from "./drift.ts"; import { readBaseline, writeBaseline } from "./hash-store.ts"; -import { assertStateMigrated } from "./migrate-hash-store.ts"; import { FOLDER_MAP, hashLocalResource, @@ -42,7 +40,14 @@ import { resolvePullScopeFromFilePaths, } from "./resources.ts"; import { extractBaseSlug, isBackupCopyFile, slugify } from "./slug-utils.ts"; -import { hashPayload, loadState, saveState, upsertState } from "./state.ts"; +import { + hashPayload, + loadState, + saveState, + stateWritePrepare, + upsertState, +} from "./state.ts"; +import { engineFiles, stateSavedStampPath } from "./state-paths.ts"; import type { ResourceState, ResourceType, StateFile } from "./types.ts"; // Map resource types to their API endpoints @@ -861,7 +866,7 @@ export async function pullResourceType( // The drift baseline now lives in the hash store, NOT in the state // section that gets wholesale-replaced at end-of-loop. So the // preserve branches just write the `{ uuid }` mapping and leave the - // `.vapi-state-hash//` file untouched — the baseline + // `state//local/baselines/` file untouched — the baseline // survives by construction, no carry-forward needed. if (direction === "both-diverged") { bothDiverged?.push({ @@ -954,7 +959,11 @@ export async function pullResourceType( } } - // Skip locally edited files even without git (mtime-based detection). + // With no baseline and nothing changed in git, keep the file unless this + // machine's engine has saved state since the file was last written. That + // moment comes from the engine's own stamp, never from the state file's + // timestamp: after a clone or a checkout that is only the order git wrote + // the files in. A fresh clone has no stamp, so it keeps every file. if ( !skipLegacyPreserveChecks && !bootstrap && @@ -969,19 +978,18 @@ export async function pullResourceType( join(dir, `${resourceId}.yaml`), ].find((p) => existsSync(p)); if (localFile) { - const stateFilePath = join(BASE_DIR, `.vapi-state.${VAPI_ENV}.json`); - if (existsSync(stateFilePath)) { - const localMtime = statSync(localFile).mtimeMs; - const stateMtime = statSync(stateFilePath).mtimeMs; - if (localMtime > stateMtime) { - console.log(` ✏️ ${resourceId} (locally modified, preserving)`); - upsertState(newStateSection, resourceId, { - uuid: resource.id, - origin: "pulled", - }); - skipped++; - continue; - } + const stamp = stateSavedStampPath(BASE_DIR, VAPI_ENV); + if ( + !existsSync(stamp) || + statSync(localFile).mtimeMs > statSync(stamp).mtimeMs + ) { + console.log(` ✏️ ${resourceId} (locally modified, preserving)`); + upsertState(newStateSection, resourceId, { + uuid: resource.id, + origin: "pulled", + }); + skipped++; + continue; } } } @@ -1243,7 +1251,7 @@ function printDriftSummary(counts: DriftDirectionCounts): void { // ───────────────────────────────────────────────────────────────────────────── export async function runPull(options: PullOptions = {}): Promise { - assertStateMigrated(STATE_FILE_PATH); + stateWritePrepare(); const force = options.force ?? process.argv.includes("--force"); const bootstrap = options.bootstrap ?? BOOTSTRAP_SYNC; const bindingsOnly = @@ -1315,9 +1323,14 @@ export async function runPull(options: PullOptions = {}): Promise { if (gitEnabled) { changedFiles = getLocallyChangedFiles(); - // Only keep resource files — non-resource changes don't matter + // Only keep resource files — non-resource changes don't matter. Neither + // do the files the engine keeps in that folder itself (the org pin and + // its records in the older layout): a person didn't edit those, whether + // git shows them as new, changed, or deleted by `npm run migrate`. + const engineOwn = engineFiles(BASE_DIR, VAPI_ENV); for (const f of changedFiles) { - if (!f.startsWith(`resources/${VAPI_ENV}/`)) changedFiles.delete(f); + if (!f.startsWith(`resources/${VAPI_ENV}/`) || engineOwn.has(f)) + changedFiles.delete(f); } } diff --git a/src/push.ts b/src/push.ts index 75b1ce6..c507dbd 100644 --- a/src/push.ts +++ b/src/push.ts @@ -13,7 +13,6 @@ import { OVERWRITE_DRIFT, RESOURCES_DIR, removeExcludedKeys, - STATE_FILE_PATH, STRICT_VALIDATION, VAPI_BASE_URL, VAPI_ENV, @@ -26,7 +25,6 @@ import { import { checkDriftForUpdate, type DriftCheckResult } from "./drift.ts"; import { deleteBaseline, writeBaseline } from "./hash-store.ts"; import { prepareResourceLinks } from "./link-preflight.ts"; -import { assertStateMigrated } from "./migrate-hash-store.ts"; import { NameCollisionReport } from "./name-collisions.ts"; import { computePushPlan, pushBlockingFindings } from "./push-plan.ts"; import { reconcileStateKeyForResource } from "./reconcile-state-key.ts"; @@ -83,7 +81,14 @@ import { parseResourceFilePath, pathMatchesFolder, } from "./resources.ts"; -import { hashPayload, loadState, saveState, upsertState } from "./state.ts"; +import { + hashPayload, + loadState, + saveState, + stateWritePrepare, + upsertState, +} from "./state.ts"; +import { stateFileLabel } from "./state-paths.ts"; import type { LoadedResources, ResourceFile, @@ -1622,7 +1627,7 @@ async function main(): Promise { : undefined; // Guard here (not only in runPush): apply spawns `tsx src/push.ts` directly, // which enters via the isMainModule block below and never calls runPush. - assertStateMigrated(STATE_FILE_PATH); + stateWritePrepare({ dryRun: DRY_RUN }); const partial = isPartialApply(); @@ -2309,7 +2314,7 @@ async function main(): Promise { if (DRY_RUN) { console.log( "\n🧪 [dry-run] Skipping state file write (would have written to " + - `.vapi-state.${VAPI_ENV}.json)`, + `${stateFileLabel(BASE_DIR, VAPI_ENV)})`, ); console.log(`\n${await dryRunCollisions!.format()}`); } else if (preflightComplete) { diff --git a/src/rollback-cmd.ts b/src/rollback-cmd.ts index 193c6f3..c9eac6f 100644 --- a/src/rollback-cmd.ts +++ b/src/rollback-cmd.ts @@ -1,23 +1,23 @@ // CLI entry: `npm run rollback -- --to ` | // `npm run rollback -- --list` // -// Reads .vapi-state..snapshots///.json +// Reads state//local/snapshots///.json // and re-applies the captured *platform* payload via PATCH, restoring the // dashboard to its state at that snapshot moment. // // Self-contained (does not import config.ts) so it can run in isolation // without triggering the global CLI parser. -import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; import { existsSync, readFileSync } from "fs"; -import { dirname, join } from "path"; -import { fileURLToPath } from "url"; -import { ORG_PIN_FILE, OrgPinMismatchError, orgPinCheck } from "./org-pin.ts"; +import { join } from "path"; +import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; +import { OrgPinMismatchError, orgPinCheck, orgPinLabel } from "./org-pin.ts"; import { listSnapshotTimestamps, loadSnapshot } from "./snapshot.ts"; +import { stateFileRead } from "./state-paths.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); interface RollbackEnv { env: string; @@ -72,7 +72,7 @@ function printUsage(): void { " npm run rollback -- --to ", "", "Snapshots are written automatically before each `npm run push` operation", - "to .vapi-state..snapshots//. Use --list to inspect available", + "to state//local/snapshots//. Use --list to inspect available", "timestamps; use --to to re-apply the platform payloads from that snapshot.", ].join("\n"), ); @@ -147,12 +147,17 @@ async function main(): Promise { const outcome = await orgPinCheck({ rootDir: BASE_DIR, org: args.env, - connection: { token: cfg.token, baseUrl: cfg.baseUrl, userAgent: userAgentGet(), vapiClient: vapiClientGet() }, + connection: { + token: cfg.token, + baseUrl: cfg.baseUrl, + userAgent: userAgentGet(), + vapiClient: vapiClientGet(), + }, keySource: cfg.source, }); if (outcome.kind === "unverified") console.warn( - `⚠️ Couldn't confirm which Vapi org the key belongs to, so it wasn't checked against resources/${args.env}/${ORG_PIN_FILE}.`, + `⚠️ Couldn't confirm which Vapi org the key belongs to, so it wasn't checked against ${orgPinLabel(BASE_DIR, args.env)}.`, ); } catch (error) { if (!(error instanceof OrgPinMismatchError)) throw error; @@ -169,7 +174,7 @@ async function main(): Promise { // Snapshot files don't store the UUID directly because the snapshot is // keyed by resourceId; the same resourceId points at the same UUID across // pushes (unless renamed, in which case the snapshot is stale anyway). - const stateFile = join(BASE_DIR, `.vapi-state.${args.env}.json`); + const stateFile = stateFileRead(BASE_DIR, args.env); if (!existsSync(stateFile)) { console.error(`❌ State file not found: ${stateFile}`); process.exit(1); diff --git a/src/setup-args.ts b/src/setup-args.ts index e700aaf..ffd7566 100644 --- a/src/setup-args.ts +++ b/src/setup-args.ts @@ -37,7 +37,7 @@ Options (non-interactive): --region us|eu Vapi region. Default: VAPI_BASE_URL if set, else auto-detect (tries US, then EU). --resources all|none all = download every resource into resources// (default) - none = seed .vapi-state..json only, no resource files + none = seed state//state.json only, no resource files -h, --help Show this help Needs a Vapi PRIVATE API key, from https://dashboard.vapi.ai/org/api-keys @@ -119,7 +119,8 @@ export function parseSetupArgs(argv: string[]): SetupArgs { if (slug === undefined) { return { mode: "error", - message: "Non-interactive setup needs an org name: npm run setup -- ", + message: + "Non-interactive setup needs an org name: npm run setup -- ", }; } @@ -131,7 +132,9 @@ export function readEnvValue(content: string, key: string): string | undefined { for (const rawLine of content.split("\n")) { const line = rawLine.trim(); if (!line || line.startsWith("#")) continue; - const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/); + const match = line.match( + /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/, + ); if (!match || match[1] !== key) continue; let value = match[2]!.trim(); if ( diff --git a/src/setup.ts b/src/setup.ts index 0050ad1..dc1b10c 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -2,8 +2,7 @@ import { confirm, input, password, select } from "@inquirer/prompts"; import { execSync } from "child_process"; import { existsSync, readdirSync, readFileSync } from "fs"; import { mkdir, readFile, rm, writeFile } from "fs/promises"; -import { dirname, join } from "path"; -import { fileURLToPath } from "url"; +import { join } from "path"; import { API_KEY_VAR, API_KEYS_URL, @@ -11,6 +10,7 @@ import { orgApiKeyVar, resolveOrgApiKey, } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; import { updateEnvConnection } from "./bindings.ts"; import { typeArgFor } from "./resource-type-args.ts"; import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js"; @@ -21,14 +21,19 @@ import { SETUP_USAGE, } from "./setup-args.ts"; import { slugify } from "./slug-utils.ts"; +import { + stateFileLabel, + stateFileLegacyPath, + stateFileRead, + stateOrgDir, +} from "./state-paths.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; // ───────────────────────────────────────────────────────────────────────────── // Constants // ───────────────────────────────────────────────────────────────────────────── -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); const VAPI_REGIONS: Record = { us: "https://api.vapi.ai", eu: "https://api.eu.vapi.ai", @@ -290,14 +295,13 @@ async function writeEnvFile( async function deleteExistingOrg(slug: string): Promise { const resourceDir = join(BASE_DIR, "resources", slug); - const stateFile = join(BASE_DIR, `.vapi-state.${slug}.json`); if (existsSync(resourceDir)) { await rm(resourceDir, { recursive: true, force: true }); } - if (existsSync(stateFile)) { - await rm(stateFile); - } + // Both layouts: the wizard starts the org over, wherever its state sits. + await rm(stateOrgDir(BASE_DIR, slug), { recursive: true, force: true }); + await rm(stateFileLegacyPath(BASE_DIR, slug), { force: true }); } // ───────────────────────────────────────────────────────────────────────────── @@ -412,16 +416,18 @@ async function runDirectSetup(options: DirectSetupOptions): Promise { const { slug, region, resources } = options; const envPath = join(BASE_DIR, `.env.${slug}`); const resourceDir = join(BASE_DIR, "resources", slug); - const stateFile = join(BASE_DIR, `.vapi-state.${slug}.json`); + const stateFile = stateFileRead(BASE_DIR, slug); - console.log(c.bold(`\n Vapi GitOps — non-interactive setup for "${slug}"\n`)); + console.log( + c.bold(`\n Vapi GitOps — non-interactive setup for "${slug}"\n`), + ); // Never clobber an org that already has local state. Re-running setup is // a destructive operation in the wizard (it deletes and re-pulls), and an // agent should not do that without a human deciding to. if (existsSync(resourceDir) || existsSync(stateFile)) { fail( - `Org "${slug}" is already set up locally (resources/${slug}/ or .vapi-state.${slug}.json exists).\n` + + `Org "${slug}" is already set up locally (resources/${slug}/ or ${stateFileLabel(BASE_DIR, slug)} exists).\n` + ` To refresh it, run: npm run pull -- ${slug}\n` + ` To start over, a human should run the interactive wizard: npm run setup`, ); @@ -447,7 +453,9 @@ async function runDirectSetup(options: DirectSetupOptions): Promise { // Setup writes the key into .env. and downloads that org, so a key // that may belong to another org is a hard stop here, not a warning. if (resolved.warning) { - fail(`${resolved.warning}\n Setup stopped before writing .env.${slug} or downloading anything.`); + fail( + `${resolved.warning}\n Setup stopped before writing .env.${slug} or downloading anything.`, + ); } const otherOrg = orgWithKey(slug, resolved.token); if (otherOrg) { @@ -567,7 +575,9 @@ async function main(): Promise { // so explain the non-interactive path instead. if (!process.stdin.isTTY) { console.error( - c.red("\n ✗ The setup wizard needs an interactive terminal (stdin is not a TTY).\n"), + c.red( + "\n ✗ The setup wizard needs an interactive terminal (stdin is not a TTY).\n", + ), ); console.error(SETUP_USAGE); process.exit(1); @@ -671,7 +681,7 @@ async function main(): Promise { // Check if org already exists locally const resourceDir = join(BASE_DIR, "resources", slug); - const stateFile = join(BASE_DIR, `.vapi-state.${slug}.json`); + const stateFile = stateFileRead(BASE_DIR, slug); if (existsSync(resourceDir) || existsSync(stateFile)) { console.log(c.yellow(`\n ⚠ Org "${slug}" already exists locally.`)); @@ -811,17 +821,12 @@ async function main(): Promise { await writeEnvFile(slug, trimmedKey, vapiBaseUrl); console.log(c.green(` ✓ Created .env.${slug}\n`)); // Before the first pull, as non-interactive setup does: the org pin - // (.vapi-org.json) is only written into a folder that already exists. + // (state//org.json) is only written for a folder that already exists. await mkdir(resourceDir, { recursive: true }); console.log(c.bold(" Downloading...\n")); - invokePull( - slug, - downloadAll ? "all" : selectedIds, - trimmedKey, - vapiBaseUrl, - ); + invokePull(slug, downloadAll ? "all" : selectedIds, trimmedKey, vapiBaseUrl); // ── Done ────────────────────────────────────────────────────────────── @@ -840,7 +845,7 @@ function printSummary(slug: string): void { console.log(""); console.log(` 📁 Resources: resources/${slug}/`); console.log(` 🔑 Env file: .env.${slug}`); - console.log(` 📄 State file: .vapi-state.${slug}.json`); + console.log(` 📄 State file: ${stateFileLabel(BASE_DIR, slug)}`); console.log(""); console.log(" Next steps:"); console.log( diff --git a/src/sim.ts b/src/sim.ts index f376cd3..1bf4cb9 100644 --- a/src/sim.ts +++ b/src/sim.ts @@ -4,28 +4,28 @@ // triggering the CLI argument parser in `config.ts`. Env-loading is inlined // here (rather than importing from `config.ts`) for the same reason. -import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; import { existsSync, readFileSync } from "fs"; -import { dirname, join } from "path"; -import { fileURLToPath } from "url"; +import { join } from "path"; +import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; +import { baseDir } from "./base-dir.ts"; import { - simRunItemTerminal, - simRunVerdict, type SimRun, type SimRunItem, type SimRunItemCounts, type SimRunVerdict, + simRunItemTerminal, + simRunVerdict, } from "./sim-result.ts"; +import { stateFileLabel, stateFileRead } from "./state-paths.ts"; import type { StateFile } from "./types.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; import { VapiApiError, - vapiFetchJson, type VapiConnection, + vapiFetchJson, } from "./vapi-client.ts"; -const __dirname = dirname(fileURLToPath(import.meta.url)); -const BASE_DIR = join(__dirname, ".."); +const BASE_DIR = baseDir(); export interface SimEnv { env: string; @@ -113,10 +113,10 @@ export function loadEnvFile(env: string): SimEnv { } export function loadStateFile(env: string): StateFile { - const stateFile = join(BASE_DIR, `.vapi-state.${env}.json`); + const stateFile = stateFileRead(BASE_DIR, env); if (!existsSync(stateFile)) { throw new Error( - `State file not found: .vapi-state.${env}.json. Run 'npm run pull -- ${env} --bootstrap' first.`, + `State file not found: ${stateFileLabel(BASE_DIR, env)}. Run 'npm run pull -- ${env} --bootstrap' first.`, ); } const state = JSON.parse(readFileSync(stateFile, "utf-8")) as StateFile; diff --git a/src/snapshot.ts b/src/snapshot.ts index 30153bf..f7a6bb2 100644 --- a/src/snapshot.ts +++ b/src/snapshot.ts @@ -4,7 +4,7 @@ // Before each PATCH, write the *outgoing* (local) payload AND the *current // platform* payload to a per-push directory: // -// .vapi-state..snapshots///.json +// state//local/snapshots///.json // // `npm run rollback -- --to ` re-applies each // `platform` payload as a PATCH, restoring the dashboard to its state at @@ -18,10 +18,28 @@ import { existsSync } from "fs"; import { mkdir, readdir, readFile, writeFile } from "fs/promises"; import { join } from "path"; +import { + snapshotsDir, + snapshotsLegacyDir, + snapshotsWriteDir, +} from "./state-paths.ts"; import { sortedKeysReplacer } from "./state-serialize.ts"; +// Where snapshots are written: state//local/snapshots/, or +// .vapi-state..snapshots/ while the org's state is in the old layout. export function snapshotsRoot(baseDir: string, env: string): string { - return join(baseDir, `.vapi-state.${env}.snapshots`); + return snapshotsWriteDir(baseDir, env); +} + +// Snapshots are read from both places, so a rollback still works on a machine +// whose snapshots have not moved yet. +function snapshotRoots(baseDir: string, env: string): string[] { + const roots = new Set([ + snapshotsRoot(baseDir, env), + snapshotsDir(baseDir, env), + snapshotsLegacyDir(baseDir, env), + ]); + return [...roots].filter((root) => existsSync(root)); } let activeRunDir: string | null = null; @@ -79,13 +97,11 @@ export async function listSnapshotTimestamps( baseDir: string, env: string, ): Promise { - const root = snapshotsRoot(baseDir, env); - if (!existsSync(root)) return []; - const entries = await readdir(root, { withFileTypes: true }); - return entries - .filter((e) => e.isDirectory()) - .map((e) => e.name) - .sort(); + const names = new Set(); + for (const root of snapshotRoots(baseDir, env)) + for (const entry of await readdir(root, { withFileTypes: true })) + if (entry.isDirectory()) names.add(entry.name); + return [...names].sort(); } export interface SnapshotEntry { @@ -99,7 +115,11 @@ export async function loadSnapshot( env: string, timestamp: string, ): Promise { - const dir = join(snapshotsRoot(baseDir, env), timestamp); + const dir = + snapshotRoots(baseDir, env) + .map((root) => join(root, timestamp)) + .find((candidate) => existsSync(candidate)) ?? + join(snapshotsRoot(baseDir, env), timestamp); if (!existsSync(dir)) { throw new Error(`Snapshot not found: ${dir}`); } diff --git a/src/state-paths.ts b/src/state-paths.ts new file mode 100644 index 0000000..3032c1d --- /dev/null +++ b/src/state-paths.ts @@ -0,0 +1,608 @@ +// Where the engine keeps what it generates and tracks. +// +// state//state.json resource name → Vapi UUID (committed) +// state//org.json the Vapi org this folder is pinned to (committed) +// state//local/baselines/ drift baselines, one file per UUID (this machine only) +// state//local/snapshots/ push snapshots for rollback (this machine only) +// state/commit-step.json a person's word that their commit step stages state/ (committed) +// +// Everything under state/ is written by the engine. Hand-written files +// (.vapi-ignore and the resources themselves) stay under resources//. +// +// Until this folder existed the same files sat at the repository root and in +// resources// under dot-names. This module is the only place that knows +// both layouts. An org is in one of them, decided by where its committed +// state file is. Every command reads the layout it finds and writes back to +// the same one. Only `npm run migrate` moves an org from the old layout to +// this one: a commit step that stages only the old place would otherwise +// leave moved state out of git, with every run still passing. +// +// Config-free on purpose, so `npm run migrate` and tests can import it +// without an org argument or a token. + +import { + existsSync, + mkdirSync, + readdirSync, + readFileSync, + renameSync, + rmdirSync, + rmSync, + unlinkSync, + writeFileSync, +} from "fs"; +import { dirname, join, relative } from "path"; +import { commitStepRead } from "./commit-step.ts"; + +export { commitStepRead }; + +export const STATE_DIR = "state"; + +/** The flag on `npm run migrate` by which a person says their commit step stages state/. */ +export const COMMIT_STEP_FLAG = "--commit-step-stages-state"; + +/** Where that word is kept, so every later run on any machine can read it. */ +export function commitStepFilePath(rootDir: string): string { + return join(rootDir, STATE_DIR, "commit-step.json"); +} + +export function stateOrgDir(rootDir: string, org: string): string { + return join(rootDir, STATE_DIR, org); +} + +export function stateFilePath(rootDir: string, org: string): string { + return join(stateOrgDir(rootDir, org), "state.json"); +} + +export function stateFileLegacyPath(rootDir: string, org: string): string { + return join(rootDir, `.vapi-state.${org}.json`); +} + +export function orgPinFilePath(rootDir: string, org: string): string { + return join(stateOrgDir(rootDir, org), "org.json"); +} + +export function orgPinFileLegacyPath(rootDir: string, org: string): string { + return join(rootDir, "resources", org, ".vapi-org.json"); +} + +export function baselinesDir(rootDir: string, org: string): string { + return join(stateOrgDir(rootDir, org), "local", "baselines"); +} + +export function baselinesLegacyDir(rootDir: string, org: string): string { + return join(rootDir, ".vapi-state-hash", org); +} + +export function snapshotsDir(rootDir: string, org: string): string { + return join(stateOrgDir(rootDir, org), "local", "snapshots"); +} + +export function snapshotsLegacyDir(rootDir: string, org: string): string { + return join(rootDir, `.vapi-state.${org}.snapshots`); +} + +/** Orgs that have a state file in either layout, sorted. */ +export function stateOrgsList(rootDir: string): string[] { + const orgs = new Set(); + for (const name of readdirSync(rootDir)) { + const match = /^\.vapi-state\.(.+)\.json$/.exec(name); + if (match?.[1]) orgs.add(match[1]); + } + const stateRoot = join(rootDir, STATE_DIR); + if (existsSync(stateRoot)) + for (const entry of readdirSync(stateRoot, { withFileTypes: true })) + if (entry.isDirectory() && existsSync(stateFilePath(rootDir, entry.name))) + orgs.add(entry.name); + return [...orgs].sort((a, b) => a.localeCompare(b)); +} + +// ── Which layout an org is in ──────────────────────────────────────────── + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +/** Whether a person has said, with `npm run migrate -- --commit-step-stages-state`, that their commit step stages state/. */ +export function commitStepAcknowledged(rootDir: string): boolean { + try { + const parsed: unknown = JSON.parse( + readFileSync(commitStepFilePath(rootDir), "utf8"), + ); + return isRecord(parsed) && parsed.stagesStateFolder === true; + } catch { + return false; + } +} + +export type StateLayout = "folder" | "root"; + +/** + * The layout an org's engine files are in: "folder" for state//, "root" + * for the files from before state/ existed. + * + * Where the org's state file is decides it, or its org pin when it has no + * state file. An org with neither goes where the repository's other orgs + * keep their state. In a repository with no + * state at all, state/ is used only when the commit step is seen to stage it + * or a person has said it does; otherwise the first state file is written + * where every older commit step looks for it. That reading is of every + * workflow, on any machine, so whoever writes first picks the same place. + */ +export function stateLayout(rootDir: string, org: string): StateLayout { + if (existsSync(stateFilePath(rootDir, org))) return "folder"; + if (existsSync(stateFileLegacyPath(rootDir, org))) return "root"; + if (existsSync(orgPinFilePath(rootDir, org))) return "folder"; + if (existsSync(orgPinFileLegacyPath(rootDir, org))) return "root"; + const orgs = stateOrgsList(rootDir); + if (orgs.some((other) => !existsSync(stateFilePath(rootDir, other)))) + return "root"; + if (orgs.length > 0) return "folder"; + const step = commitStepRead(rootDir, {}); + return step.kind === "seen" || + (step.kind !== "stale" && commitStepAcknowledged(rootDir)) + ? "folder" + : "root"; +} + +// A file that exists is read and written where it is. A file that doesn't +// exist yet goes where the org's layout puts it. +function fileInLayout( + next: string, + legacy: string, + rootDir: string, + org: string, +): string { + if (existsSync(next)) return next; + if (existsSync(legacy)) return legacy; + return stateLayout(rootDir, org) === "folder" ? next : legacy; +} + +/** The org's state file: where it is, else where its first write goes. */ +export function stateFileRead(rootDir: string, org: string): string { + return fileInLayout( + stateFilePath(rootDir, org), + stateFileLegacyPath(rootDir, org), + rootDir, + org, + ); +} + +/** The state file to write: the one that is read. */ +export const stateFileWrite = stateFileRead; + +/** The org pin: where it is, else beside the state file in the org's layout. */ +export function orgPinFileRead(rootDir: string, org: string): string { + return fileInLayout( + orgPinFilePath(rootDir, org), + orgPinFileLegacyPath(rootDir, org), + rootDir, + org, + ); +} + +/** The org pin to write: the one that is read. */ +export const orgPinFileWrite = orgPinFileRead; + +/** The state file as a person names it: its path from the repository root. */ +export function stateFileLabel(rootDir: string, org: string): string { + return relative(rootDir, stateFileRead(rootDir, org)).replaceAll("\\", "/"); +} + +/** Where this machine's baselines for the org are written. */ +export function baselinesWriteDir(rootDir: string, org: string): string { + return stateLayout(rootDir, org) === "folder" + ? baselinesDir(rootDir, org) + : baselinesLegacyDir(rootDir, org); +} + +/** Where this machine's push snapshots for the org are written. */ +export function snapshotsWriteDir(rootDir: string, org: string): string { + return stateLayout(rootDir, org) === "folder" + ? snapshotsDir(rootDir, org) + : snapshotsLegacyDir(rootDir, org); +} + +/** + * A file the engine touches each time it saves the org's state file on this + * machine. It sits with the baselines, so it is never committed and a fresh + * clone has none. Pull reads "has the engine synced here since this file was + * written" from it rather than from the state file's own timestamp, which + * after a clone or a checkout is only the order git wrote the files in. + */ +export function stateSavedStampPath(rootDir: string, org: string): string { + return join(baselinesWriteDir(rootDir, org), ".state-saved"); +} + +// ── The committed files, in both places ────────────────────────────────── + +interface CommittedFile { + legacy: string; + next: string; + legacyLabel: string; + nextLabel: string; +} + +function committedFiles(rootDir: string, org: string): CommittedFile[] { + return [ + { + legacy: stateFileLegacyPath(rootDir, org), + next: stateFilePath(rootDir, org), + legacyLabel: `.vapi-state.${org}.json`, + nextLabel: `${STATE_DIR}/${org}/state.json`, + }, + { + legacy: orgPinFileLegacyPath(rootDir, org), + next: orgPinFilePath(rootDir, org), + legacyLabel: `resources/${org}/.vapi-org.json`, + nextLabel: `${STATE_DIR}/${org}/org.json`, + }, + ]; +} + +/** + * Every committed file the engine writes for an org, in both layouts, as + * paths from the repository root. The engine wrote them, so a change git + * reports in one of them is never a person's edit. Built from the list + * `npm run migrate` moves, so a file added there is covered here. + */ +export function engineFiles(rootDir: string, org: string): Set { + return new Set( + committedFiles(rootDir, org).flatMap((file) => [ + file.legacyLabel, + file.nextLabel, + ]), + ); +} + +export class StateLayoutError extends Error {} + +function jsonStable(value: unknown): unknown { + if (value === null || typeof value !== "object") return value; + if (Array.isArray(value)) return value.map(jsonStable); + const record = value as Record; + return Object.fromEntries( + Object.keys(record) + .sort() + .map((key) => [key, jsonStable(record[key])]), + ); +} + +function sameJson(a: string, b: string): boolean { + const left = readFileSync(a, "utf8"); + const right = readFileSync(b, "utf8"); + if (left === right) return true; + try { + return ( + JSON.stringify(jsonStable(JSON.parse(left))) === + JSON.stringify(jsonStable(JSON.parse(right))) + ); + } catch { + return false; + } +} + +// Files that sit in both places. They must hold the same content: a copy +// that differs may carry an entry the other lacks, and reading either one +// alone would lose it. +function committedInBothPlaces(rootDir: string, org: string): CommittedFile[] { + const both = committedFiles(rootDir, org).filter( + (file) => existsSync(file.legacy) && existsSync(file.next), + ); + for (const file of both) + if (!sameJson(file.legacy, file.next)) + throw new StateLayoutError( + `${file.legacyLabel} and ${file.nextLabel} both exist and disagree.\n` + + ` Stopped before reading or changing anything.\n` + + ` ${file.nextLabel} is the current location. Compare the two, copy across any entry\n` + + ` only the old file has, then delete ${file.legacyLabel}.`, + ); + return both; +} + +/** + * The old state file, when the org also has one in state// with the same + * content (a move cut short, or a merge that brought the old file back). The + * engine keeps it identical to the one it reads, so whichever of the two the + * commit step stages is complete, until `npm run migrate` removes it. + */ +export function stateFileLeftover( + rootDir: string, + org: string, +): string | undefined { + const legacy = stateFileLegacyPath(rootDir, org); + return existsSync(legacy) && existsSync(stateFilePath(rootDir, org)) + ? legacy + : undefined; +} + +// ── A command that writes state ────────────────────────────────────────── + +export function stateRunIsCi(env: NodeJS.ProcessEnv = process.env): boolean { + return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true"; +} + +function notSeenReason(file: string | undefined): string { + return file + ? `${file} can commit to this repository and is not seen to stage ${STATE_DIR}/` + : `no workflow in .github/workflows/ is seen to stage ${STATE_DIR}/`; +} + +const NO_STATE_YET = "ℹ️ No engine state in this repository yet"; + +/** + * The line a command prints instead of the older-layout one when it is about + * to write a repository's first state file at the root: where the file goes, + * why, and what has to stage it. A commit step the engine can't read may + * stage only state/, and then this file would never be committed. + */ +function firstStateNotice(rootDir: string, org: string): string { + const step = commitStepRead(rootDir, {}); + const file = `.vapi-state.${org}.json`; + if (step.kind === "stale") + return `${NO_STATE_YET}: it goes to ${file} at the repository root, which ${step.file} stages.`; + return ( + `${NO_STATE_YET}: it goes to ${file} at the repository root, because ${notSeenReason(step.kind === "unseen" ? step.file : undefined)}. ` + + `Whatever commits state after a run has to stage .vapi-state.*.json. If it stages ${STATE_DIR}/ instead, run \`npm run migrate -- ${COMMIT_STEP_FLAG}\` first and commit ${STATE_DIR}/commit-step.json, so state starts in ${STATE_DIR}/.` + ); +} + +/** The one line a command prints while an org's state is still in the old layout. */ +export const OLD_LAYOUT_NOTICE = `ℹ️ Engine state here is in the older layout (.vapi-state..json at the repository root). \`npm run migrate\` moves it into ${STATE_DIR}/ and says what the commit step has to stage first.`; + +// Move a folder of machine-local files. Where both sides hold an entry the +// new one wins: it was written after the old layout stopped being written. +function localDirMove(legacy: string, next: string): boolean { + if (!existsSync(legacy)) return false; + mkdirSync(dirname(next), { recursive: true }); + if (!existsSync(next)) { + renameSync(legacy, next); + return true; + } + for (const name of readdirSync(legacy)) { + if (existsSync(join(next, name))) + rmSync(join(legacy, name), { recursive: true, force: true }); + else renameSync(join(legacy, name), join(next, name)); + } + rmdirSync(legacy); + return true; +} + +/** + * Move this machine's baselines and snapshots into state//local/, for an + * org whose committed state is already in state//. They are gitignored + * in both places, so no commit step can lose them. + */ +export function stateLocalMove(rootDir: string, org: string): string[] { + const moved: string[] = []; + if ( + localDirMove(baselinesLegacyDir(rootDir, org), baselinesDir(rootDir, org)) + ) { + moved.push(`.vapi-state-hash/${org}/`); + const root = join(rootDir, ".vapi-state-hash"); + if (readdirSync(root).length === 0) rmdirSync(root); + } + if ( + localDirMove(snapshotsLegacyDir(rootDir, org), snapshotsDir(rootDir, org)) + ) + moved.push(`.vapi-state.${org}.snapshots/`); + return moved; +} + +/** + * Run before a command writes anything for an org. Moves no committed file: + * the org stays in the layout it is in. Returns the lines to print. + * + * Throws StateLayoutError, before anything is read or changed, when the two + * places hold a file and disagree, or when a CI run would write state where + * the workflow running it is seen not to stage it. + */ +export function stateLayoutPrepare( + rootDir: string, + org: string, + env: NodeJS.ProcessEnv = process.env, +): string[] { + const both = committedInBothPlaces(rootDir, org); + const layout = stateLayout(rootDir, org); + const notices: string[] = []; + + if (stateRunIsCi(env)) { + const step = commitStepRead(rootDir, env); + const said = commitStepAcknowledged(rootDir); + const stopped = + "Stopped before reading or changing anything: UUIDs recorded by this run would be lost."; + if (layout === "folder" && step.kind === "stale") + throw new StateLayoutError( + `${step.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so it won't commit ${STATE_DIR}/${org}/.\n` + + ` ${stopped}\n Add \`git add -A -- ${STATE_DIR}\` to that step.`, + ); + if (layout === "folder" && step.kind === "unseen" && !said) + throw new StateLayoutError( + `${notSeenReason(step.file)}, so ${STATE_DIR}/${org}/ may never be committed.\n` + + ` ${stopped}\n` + + ` Make the step that commits state stage \`${STATE_DIR}\`. If it already does, run \`npm run migrate -- ${COMMIT_STEP_FLAG}\` on your machine and commit ${STATE_DIR}/commit-step.json.`, + ); + // The mirror case: state still at the old place, under a commit step + // that has moved on to state/. + if (layout === "root" && existsSync(stateFileLegacyPath(rootDir, org))) { + const why = + step.kind === "seen" && !step.stagesOld + ? `this repository's workflow stages ${STATE_DIR}/ but not .vapi-state.*.json` + : step.kind === "unseen" && said + ? `${STATE_DIR}/commit-step.json says the commit step stages ${STATE_DIR}/` + : undefined; + if (why) + throw new StateLayoutError( + `.vapi-state.${org}.json is still at the repository root, and ${why}, so what this run records in it may never be committed.\n` + + " Stopped before reading or changing anything.\n" + + " Run `npm run migrate` on your machine and commit the result, so the file is where the commit step looks.", + ); + } + if (layout === "folder" && step.kind !== "seen" && said) + notices.push( + `ℹ️ ${STATE_DIR}/commit-step.json says this run's commit step stages ${STATE_DIR}/. The engine can't see that step: if it doesn't, what this run records in ${STATE_DIR}/${org}/ is lost.`, + ); + } + + if (layout === "root") + return [ + ...notices, + stateOrgsList(rootDir).length === 0 && + !existsSync(orgPinFileLegacyPath(rootDir, org)) + ? firstStateNotice(rootDir, org) + : OLD_LAYOUT_NOTICE, + ]; + + const moved = stateLocalMove(rootDir, org); + if (moved.length > 0) + notices.push( + `📦 Moved ${moved.join(", ")} into ${STATE_DIR}/${org}/local/. Both places are gitignored.`, + ); + if (both.length > 0) + notices.push( + `ℹ️ ${both.map((file) => file.legacyLabel).join(" and ")} is still here beside its copy in ${STATE_DIR}/${org}/. \`npm run migrate\` removes it.`, + ); + return notices; +} + +/** + * Print a command's layout notices. The older-layout line prints once per + * command, also across the pull and push that apply and promote start. + */ +export function stateNoticesPrint( + notices: string[], + env: NodeJS.ProcessEnv = process.env, +): void { + for (const notice of notices) { + if (notice === OLD_LAYOUT_NOTICE || notice.startsWith(NO_STATE_YET)) { + if (env.VAPI_GITOPS_OLD_LAYOUT_NOTICE === "shown") continue; + env.VAPI_GITOPS_OLD_LAYOUT_NOTICE = "shown"; + } + console.log(notice); + } +} + +// ── npm run migrate: the only thing that moves committed state ────────── + +export interface StateMoveRead { + /** Whether `npm run migrate` moves committed state in this repository. */ + open: boolean; + /** What it prints before anything moves. */ + lines: string[]; +} + +const COMMIT_STEP_NEEDS = [ + " Once state is in state/, whatever commits state after a run has to stage both of these:", + ` git add -A -- ${STATE_DIR} the new folder: each org's state.json, org.json and records`, + " git add -A -- ':(glob).vapi-state.*.json' the old files, so the commit that moves them records their removal", + ` A commit action or a script needs the same two paths: ${STATE_DIR} and .vapi-state.*.json.`, + " Upstream's .github/workflows/promotion.yml has both, guarded for a repository where one matches nothing.", +]; + +/** + * Whether `npm run migrate` may move committed state, and what it says first. + * It moves state when every commit step in .github/workflows/ is seen to + * stage state/, or when a person has said theirs does. It never guesses that + * nothing commits state: a pipeline the engine has no file for is not seen. + */ +export function stateMoveRead(rootDir: string): StateMoveRead { + const step = commitStepRead(rootDir, {}); + if (step.kind === "stale") + return { + open: false, + lines: [ + ...COMMIT_STEP_NEEDS, + `⚠️ Nothing moves into ${STATE_DIR}/: ${step.file} stages .vapi-state.*.json but not ${STATE_DIR}/.`, + ` Add \`git add -A -- ${STATE_DIR}\` to that step, then run \`npm run migrate\` again.`, + ], + }; + if (step.kind === "seen") + return { + open: true, + lines: [ + ...COMMIT_STEP_NEEDS, + `✅ Every commit step in .github/workflows/ is seen to stage ${STATE_DIR}/. A pipeline the engine has no file for (another CI system, a script that commits with its own token) is not read and needs the same two lines.`, + ], + }; + if (commitStepAcknowledged(rootDir)) + return { + open: true, + lines: [ + ...COMMIT_STEP_NEEDS, + `✍️ ${STATE_DIR}/commit-step.json says the commit step stages ${STATE_DIR}/. The engine can't check a step it can't read, so it takes that word.`, + ], + }; + return { + open: false, + lines: [ + `⚠️ Nothing moves into ${STATE_DIR}/ yet: ${notSeenReason(step.kind === "unseen" ? step.file : undefined)}.`, + ...COMMIT_STEP_NEEDS, + " When your step does that, say so. This writes that down and moves every org:", + ` npm run migrate -- ${COMMIT_STEP_FLAG}`, + ` The engine can't check a step it can't read. From then on it takes your word, kept in ${STATE_DIR}/commit-step.json.`, + ], + }; +} + +/** + * What the commit step has to stage before state can move, when nothing is + * seen to stage state/ and nobody has said it does. Undefined when + * `npm run migrate` would move state, or when a workflow is seen to stage + * only the old file. + */ +export function commitStepAsk(rootDir: string): string[] | undefined { + const step = commitStepRead(rootDir, {}); + if (step.kind === "stale" || step.kind === "seen") return undefined; + return commitStepAcknowledged(rootDir) + ? undefined + : stateMoveRead(rootDir).lines; +} + +/** + * Record a person's word that their commit step stages state/. Refused while + * a workflow is seen to stage only the old file: that is seen to be untrue. + * Returns the line to print. + */ +export function commitStepAcknowledge(rootDir: string): string { + const step = commitStepRead(rootDir, {}); + if (step.kind === "stale") + throw new StateLayoutError( + `${step.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so ${COMMIT_STEP_FLAG} is not true yet.\n` + + ` Add \`git add -A -- ${STATE_DIR}\` to that step first. Nothing was changed.`, + ); + if (step.kind === "seen") + return `ℹ️ ${COMMIT_STEP_FLAG} is not needed here: every commit step in .github/workflows/ is seen to stage ${STATE_DIR}/.`; + if (commitStepAcknowledged(rootDir)) + return `ℹ️ ${STATE_DIR}/commit-step.json already says the commit step stages ${STATE_DIR}/.`; + const path = commitStepFilePath(rootDir); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync( + path, + `${JSON.stringify({ stagesStateFolder: true }, null, 2)}\n`, + ); + return `✍️ Wrote ${STATE_DIR}/commit-step.json: you said the commit step stages ${STATE_DIR}/. Commit it together with the move.`; +} + +/** + * Move one org's engine files into state//. Only `npm run migrate` calls + * this, after stateMoveRead says the move is open. Returns what moved. + * + * Each committed file moves by one rename, so the full state is always in + * exactly one of the two places. Throws StateLayoutError before changing + * anything when both places hold a file and they disagree. + */ +export function stateMove(rootDir: string, org: string): string[] { + const moved: string[] = []; + // Same content in both places: the old copy carries nothing. + for (const file of committedInBothPlaces(rootDir, org)) { + unlinkSync(file.legacy); + moved.push(file.legacyLabel); + } + for (const file of committedFiles(rootDir, org)) { + if (!existsSync(file.legacy)) continue; + mkdirSync(dirname(file.next), { recursive: true }); + renameSync(file.legacy, file.next); + moved.push(file.legacyLabel); + } + return [...moved, ...stateLocalMove(rootDir, org)]; +} diff --git a/src/state.ts b/src/state.ts index 502e096..87cba5b 100644 --- a/src/state.ts +++ b/src/state.ts @@ -1,6 +1,16 @@ -import { existsSync, readFileSync } from "fs"; -import { rename, writeFile } from "fs/promises"; -import { STATE_FILE_PATH, VAPI_ENV } from "./config.ts"; +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"; +import { copyFile, rename, writeFile } from "fs/promises"; +import { dirname } from "path"; +import { BASE_DIR, VAPI_ENV } from "./config.ts"; +import { assertStateMigrated } from "./migrate-hash-store.ts"; +import { + stateFileLeftover, + stateFileRead, + stateFileWrite, + stateLayoutPrepare, + stateNoticesPrint, + stateSavedStampPath, +} from "./state-paths.ts"; import { asResourceState, hashPayload, @@ -63,22 +73,35 @@ export function createEmptyState(): StateFile { }; } +/** + * Run at the start of a command that writes state, before any request: stop + * when the org's state can't be written safely where it is (state-paths.ts), + * then refuse a state file still in the legacy per-resource-hash format. + */ +export function stateWritePrepare(options: { dryRun?: boolean } = {}): void { + // A dry run writes nothing, so there is nothing to check or say. + if (!options.dryRun) + stateNoticesPrint(stateLayoutPrepare(BASE_DIR, VAPI_ENV)); + assertStateMigrated(stateFileRead(BASE_DIR, VAPI_ENV)); +} + export function loadState(): StateFile { - if (!existsSync(STATE_FILE_PATH)) { + const statePath = stateFileRead(BASE_DIR, VAPI_ENV); + if (!existsSync(statePath)) { console.log(`📄 Creating new state file for environment: ${VAPI_ENV}`); return createEmptyState(); } let content: unknown; try { - content = JSON.parse(readFileSync(STATE_FILE_PATH, "utf-8")); + content = JSON.parse(readFileSync(statePath, "utf-8")); } catch (error) { // Failing loudly here is deliberate. If we silently fall back to an empty // state on a corrupted file, a subsequent push would treat every remote // resource as new and create duplicates across the entire org. const msg = error instanceof Error ? error.message : String(error); throw new Error( - `Failed to parse state file at ${STATE_FILE_PATH}: ${msg}\n` + + `Failed to parse state file at ${statePath}: ${msg}\n` + `Refusing to continue — falling back to empty state would cause duplicate ` + `resources on next push. Restore the file from git, or delete it manually ` + `to start fresh after confirming the environment has no tracked resources.`, @@ -120,8 +143,17 @@ export async function saveState(state: StateFile): Promise { // A crash or SIGINT mid-write leaves the original state intact rather than // truncating it. A truncated state file would silently wipe all UUID // mappings on the next load. - const tmpPath = `${STATE_FILE_PATH}.tmp`; + const statePath = stateFileWrite(BASE_DIR, VAPI_ENV); + mkdirSync(dirname(statePath), { recursive: true }); + const tmpPath = `${statePath}.tmp`; await writeFile(tmpPath, JSON.stringify(state, sortedKeysReplacer, 2) + "\n"); - await rename(tmpPath, STATE_FILE_PATH); - console.log(`💾 Saved state file: ${STATE_FILE_PATH}`); + await rename(tmpPath, statePath); + // An old copy left beside it is kept identical until migrate removes it. + const leftover = stateFileLeftover(BASE_DIR, VAPI_ENV); + if (leftover) await copyFile(statePath, leftover); + // Pull compares a file against this moment when it has no baseline for it. + const stamp = stateSavedStampPath(BASE_DIR, VAPI_ENV); + mkdirSync(dirname(stamp), { recursive: true }); + writeFileSync(stamp, `${new Date().toISOString()}\n`); + console.log(`💾 Saved state file: ${statePath}`); } diff --git a/src/types.ts b/src/types.ts index 8da6fba..da34c84 100644 --- a/src/types.ts +++ b/src/types.ts @@ -8,7 +8,7 @@ // // The "last known platform state" content hash that drives drift detection // lives OUTSIDE this file, in the gitignored per-developer hash store at -// `.vapi-state-hash//` (see `hash-store.ts`). Keeping hashes out +// `state//local/baselines/` (see `hash-store.ts`). Keeping hashes out // of the committed state file means the state diff is purely semantic // (added/removed/re-bound resources) and the drift baseline is local to each // developer's working copy. @@ -23,7 +23,7 @@ export interface ResourceState { origin?: "pushed" | "pulled" | "adopted"; } -// `StateFile` is the on-disk shape of `.vapi-state..json`. Each section +// `StateFile` is the on-disk shape of `state//state.json`. Each section // carries `Record` instead of bare strings. // `loadState()` migrates legacy data automatically. export interface StateFile { diff --git a/src/user-agent.ts b/src/user-agent.ts index b3dbffb..1612eca 100644 --- a/src/user-agent.ts +++ b/src/user-agent.ts @@ -32,6 +32,10 @@ import { readFileSync } from "node:fs"; import { basename, dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; +// The engine's own package.json, for its version. Deliberately not +// baseDir() (src/base-dir.ts): in an engine test that is a temporary +// directory with no package.json, and the version sent has to be the real +// one. This is the one module that finds a file from its own location. const PACKAGE_JSON_PATH = join( dirname(fileURLToPath(import.meta.url)), "..", diff --git a/src/validate-cmd.ts b/src/validate-cmd.ts index edbd88c..67ee142 100644 --- a/src/validate-cmd.ts +++ b/src/validate-cmd.ts @@ -8,14 +8,10 @@ import { existsSync } from "fs"; import { relative, resolve } from "path"; import { fileURLToPath } from "url"; -import { - BASE_DIR, - loadIgnorePatterns, - STATE_FILE_PATH, - VAPI_ENV, -} from "./config.ts"; +import { BASE_DIR, loadIgnorePatterns, VAPI_ENV } from "./config.ts"; import { loadResources } from "./resources.ts"; import { createEmptyState, loadState } from "./state.ts"; +import { stateFileRead } from "./state-paths.ts"; import type { LoadedResources, ResourceType } from "./types.ts"; import { findingAnnotation, @@ -53,7 +49,7 @@ async function main(): Promise { }; // References resolve through the committed state file, as they do on push. - const stateExists = existsSync(STATE_FILE_PATH); + const stateExists = existsSync(stateFileRead(BASE_DIR, VAPI_ENV)); if (!stateExists) console.log("📄 No state file yet: references must name local files."); const state = stateExists ? loadState() : createEmptyState(); diff --git a/state/README.md b/state/README.md new file mode 100644 index 0000000..f3e5a8d --- /dev/null +++ b/state/README.md @@ -0,0 +1,28 @@ +# state/ + +The engine writes everything in this folder. Don't edit or delete these files by hand. Commit them whenever a command changes them. + +| Path | What it holds | In git | +| --- | --- | --- | +| `state//state.json` | Which Vapi resource (UUID) each file under `resources//` is. | Yes | +| `state//org.json` | The Vapi org that `resources//` belongs to. A command run with another org's key stops before it reads or changes anything. | Yes | +| `state//local/baselines/` | The last version of each resource this machine saw on the platform, used to notice dashboard edits. | No | +| `state//local/snapshots/` | A copy of each resource taken before a push, for `npm run rollback`. | No | +| `state/commit-step.json` | Only in a repository whose own pipeline commits state in a way the engine can't read. It is that repository's word, given with `npm run migrate -- --commit-step-stages-state`, that the pipeline stages this folder. | Yes | + +## What happens if a file goes missing + +- **`state.json`**: the engine no longer knows which resources already exist, so the next push creates every one of them again as a duplicate. Restore the file from git (`git checkout -- state//state.json`). Never rebuild it by hand. +- **`org.json`**: the next command pins the folder again to whichever org its key belongs to, so the protection against a wrong key is gone until then. Restore it from git. +- **`commit-step.json`**: nothing is lost. A CI run under that pipeline stops before it changes anything and says how to put the file back. +- **`local/`**: nothing breaks. The next pull records new baselines. Snapshots taken so far are gone, so there is nothing to roll back to until the next push. + +## What is yours to edit + +Everything under `resources//`, including `resources//.vapi-ignore`, is hand-written and yours. This folder is the engine's. + +## Repositories created before this folder existed + +The same files used to sit elsewhere: `.vapi-state..json` and `.vapi-state..snapshots/` at the repository root, `.vapi-state-hash//`, and `resources//.vapi-org.json`. The engine keeps reading and writing them there, on your machine and in CI, for as long as you leave them. + +Only `npm run migrate` moves them here. Before it moves anything it says what the step that commits state after a run has to stage, and it moves nothing while it can't see that step stage this folder, unless you tell it yours does. Commit the removal of the old files together with the new folder. See [Upgrading from an older version](../docs/guides/commands.md#upgrading-from-an-older-version). diff --git a/tests/adopt.test.ts b/tests/adopt.test.ts index cf15b55..57378ed 100644 --- a/tests/adopt.test.ts +++ b/tests/adopt.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { adoptResources, parseAdoptArgs } from "../src/adopt.ts"; diff --git a/tests/agent-docs.test.ts b/tests/agent-docs.test.ts index 921cfc2..5186a87 100644 --- a/tests/agent-docs.test.ts +++ b/tests/agent-docs.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; diff --git a/tests/api-key.test.ts b/tests/api-key.test.ts index 465d316..c5dbf21 100644 --- a/tests/api-key.test.ts +++ b/tests/api-key.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { @@ -31,14 +32,20 @@ test("resolveApiKey: earlier source wins regardless of variable name", () => { // process.env (legacy name) beats a .env file (canonical name), preserving // the engine's "real environment overrides .env files" rule. assert.equal( - resolveApiKey({ VAPI_TOKEN: "from-env" }, { VAPI_PRIVATE_API_KEY: "from-file" }), + resolveApiKey( + { VAPI_TOKEN: "from-env" }, + { VAPI_PRIVATE_API_KEY: "from-file" }, + ), "from-env", ); }); test("resolveApiKey: blank values are ignored", () => { assert.equal( - resolveApiKey({ VAPI_PRIVATE_API_KEY: " ", VAPI_TOKEN: "" }, { VAPI_TOKEN: "x" }), + resolveApiKey( + { VAPI_PRIVATE_API_KEY: " ", VAPI_TOKEN: "" }, + { VAPI_TOKEN: "x" }, + ), "x", ); assert.equal(resolveApiKey({}, {}), undefined); @@ -60,24 +67,27 @@ test("missingApiKeyMessage points at the dashboard and the canonical name", () = // different .env. key is reported. test("orgApiKeyVar upper-cases the slug and turns hyphens into underscores", () => { - assert.deepEqual( - ["acme", "acme-dev", "team2-prod"].map(orgApiKeyVar), - [ - "VAPI_PRIVATE_API_KEY_ACME", - "VAPI_PRIVATE_API_KEY_ACME_DEV", - "VAPI_PRIVATE_API_KEY_TEAM2_PROD", - ], - ); + assert.deepEqual(["acme", "acme-dev", "team2-prod"].map(orgApiKeyVar), [ + "VAPI_PRIVATE_API_KEY_ACME", + "VAPI_PRIVATE_API_KEY_ACME_DEV", + "VAPI_PRIVATE_API_KEY_TEAM2_PROD", + ]); }); test("resolveOrgApiKey: the org's own variable beats the generic one and the file", () => { assert.deepEqual( resolveOrgApiKey( "acme-dev", - { VAPI_PRIVATE_API_KEY_ACME_DEV: "org-key", VAPI_PRIVATE_API_KEY: "generic-key" }, + { + VAPI_PRIVATE_API_KEY_ACME_DEV: "org-key", + VAPI_PRIVATE_API_KEY: "generic-key", + }, { VAPI_PRIVATE_API_KEY: "file-key" }, ), - { token: "org-key", source: "the VAPI_PRIVATE_API_KEY_ACME_DEV environment variable" }, + { + token: "org-key", + source: "the VAPI_PRIVATE_API_KEY_ACME_DEV environment variable", + }, ); }); @@ -94,7 +104,11 @@ test("resolveOrgApiKey: another org's variable is ignored", () => { test("resolveOrgApiKey: a generic key matching the file has no warning", () => { assert.deepEqual( - resolveOrgApiKey("acme-dev", { VAPI_PRIVATE_API_KEY: "same" }, { VAPI_PRIVATE_API_KEY: "same" }), + resolveOrgApiKey( + "acme-dev", + { VAPI_PRIVATE_API_KEY: "same" }, + { VAPI_PRIVATE_API_KEY: "same" }, + ), { token: "same", source: "the VAPI_PRIVATE_API_KEY environment variable" }, ); }); @@ -106,8 +120,14 @@ test("resolveOrgApiKey: a generic key overriding a different file key warns", () { VAPI_PRIVATE_API_KEY: "prod-key" }, ); assert.equal(resolved?.token, "dev-key"); - assert.match(resolved?.warning ?? "", /not the different key in \.env\.acme-prod/); - assert.match(resolved?.warning ?? "", /export VAPI_PRIVATE_API_KEY_ACME_PROD/); + assert.match( + resolved?.warning ?? "", + /not the different key in \.env\.acme-prod/, + ); + assert.match( + resolved?.warning ?? "", + /export VAPI_PRIVATE_API_KEY_ACME_PROD/, + ); }); test("resolveOrgApiKey: the warning never contains either key", () => { @@ -138,6 +158,9 @@ test("resolveOrgApiKey: a placeholder in the file doesn't trigger the warning", { VAPI_PRIVATE_API_KEY: "real-key" }, { VAPI_PRIVATE_API_KEY: "your-vapi-private-key-here" }, ), - { token: "real-key", source: "the VAPI_PRIVATE_API_KEY environment variable" }, + { + token: "real-key", + source: "the VAPI_PRIVATE_API_KEY environment variable", + }, ); }); diff --git a/tests/apply-scoped-pull.test.ts b/tests/apply-scoped-pull.test.ts index bae62d0..d375ab2 100644 --- a/tests/apply-scoped-pull.test.ts +++ b/tests/apply-scoped-pull.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/assistant-folder.test.ts b/tests/assistant-folder.test.ts index 618fd21..1db6c7f 100644 --- a/tests/assistant-folder.test.ts +++ b/tests/assistant-folder.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { cpSync, mkdtempSync, rmSync, symlinkSync } from "node:fs"; diff --git a/tests/audit.test.ts b/tests/audit.test.ts index 72cac00..fb18813 100644 --- a/tests/audit.test.ts +++ b/tests/audit.test.ts @@ -1,8 +1,8 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdirSync, rmSync, writeFileSync } from "node:fs"; -import { dirname, join } from "node:path"; +import { join } from "node:path"; import test from "node:test"; -import { fileURLToPath } from "node:url"; // audit.ts → config.ts: config.ts asserts argv[2] / VAPI_TOKEN at module load // time. Prime both before importing the module under test — same trick used in @@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url"; process.argv = ["node", "test", "test-fixture-org"]; process.env.VAPI_TOKEN = process.env.VAPI_TOKEN || "test-token-not-used"; -const { _resetIgnoreCache } = await import("../src/config.ts"); +const { _resetIgnoreCache, RESOURCES_DIR } = await import("../src/config.ts"); const { formatFinding, runAudit, summarizeFindings } = await import( "../src/audit.ts" ); @@ -391,14 +391,11 @@ test("dashboard-orphan: .vapi-ignore matching the candidate slug suppresses the // matchesIgnore reads patterns from resources//.vapi-ignore via a // module-private cache. There is no DI seam for patterns on the audit // path, so prime the cache by writing a real fixture and resetting - // between/around the test. Cleanup runs in finally so a thrown assertion - // still scrubs the filesystem. - const __dirname = dirname(fileURLToPath(import.meta.url)); - const repoRoot = join(__dirname, ".."); - const ignoreDir = join(repoRoot, "resources", "test-fixture-org"); - const ignorePath = join(ignoreDir, ".vapi-ignore"); - - mkdirSync(ignoreDir, { recursive: true }); + // between/around the test. The file goes where the engine reads it: under + // the temporary directory it works in during tests (tests/no-vapi-api.ts). + const ignorePath = join(RESOURCES_DIR, ".vapi-ignore"); + + mkdirSync(RESOURCES_DIR, { recursive: true }); writeFileSync(ignorePath, "assistants/wild-bot\n", "utf-8"); _resetIgnoreCache(); try { @@ -413,12 +410,6 @@ test("dashboard-orphan: .vapi-ignore matching the candidate slug suppresses the assert.equal(orphans.length, 0); } finally { rmSync(ignorePath, { force: true }); - // Best-effort dir cleanup; ignore failure if other tests populated it. - try { - rmSync(ignoreDir, { recursive: false }); - } catch { - /* dir not empty — fine */ - } _resetIgnoreCache(); } }); diff --git a/tests/base-dir.test.ts b/tests/base-dir.test.ts new file mode 100644 index 0000000..9e1d073 --- /dev/null +++ b/tests/base-dir.test.ts @@ -0,0 +1,45 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// The engine's directory comes from src/base-dir.ts and nowhere else. A +// module that worked it out for itself would work in the repository while +// every other module worked in a test's temporary directory. + +const SRC = fileURLToPath(new URL("../src", import.meta.url)); + +// A line that finds the module's own location, or the directory the command +// was started in. +const LOCATES = + /import\.meta\.(url|dirname|filename)|\b__dirname\b|\b__filename\b|process\.cwd\(\)/; + +// The lines allowed to: asking whether this file is the script being run, +// loading a CommonJS dependency, and src/user-agent.ts, the one deliberate +// exception. It reads the engine's own package.json for the version it +// sends, and in an engine test baseDir() is a temporary directory with no +// package.json in it. +function allowed(file: string, line: string): boolean { + return ( + file === "base-dir.ts" || + line.includes("process.argv[1]") || + line.includes("createRequire(import.meta.url)") || + file === "user-agent.ts" + ); +} + +test("no module under src/ works out the repository's directory for itself", () => { + const found: string[] = []; + for (const file of readdirSync(SRC, { recursive: true, encoding: "utf8" })) { + if (!file.endsWith(".ts")) continue; + readFileSync(join(SRC, file), "utf8") + .split("\n") + .forEach((line, index) => { + if (LOCATES.test(line) && !allowed(file, line)) + found.push(`src/${file}:${index + 1}`); + }); + } + assert.deepEqual(found, []); +}); diff --git a/tests/bindings.test.ts b/tests/bindings.test.ts index 2820f3d..22f5dc1 100644 --- a/tests/bindings.test.ts +++ b/tests/bindings.test.ts @@ -1,9 +1,10 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { fetchAllPhoneNumbers, - updateEnvConnection, updateBindingEnv, + updateEnvConnection, } from "../src/bindings.ts"; test("updateEnvConnection replaces auth settings without clobbering bindings", () => { @@ -43,18 +44,12 @@ test("updateBindingEnv preserves manual env values and exports org-local binding const result = updateBindingEnv( existing, { "crm-api": { uuid: "credential-1" } }, - [ - { id: "phone-1", name: "Renamed Support Line" }, - { id: "phone-2" }, - ], + [{ id: "phone-1", name: "Renamed Support Line" }, { id: "phone-2" }], ); assert.match(result.content, /^VAPI_TOKEN=secret$/m); assert.match(result.content, /^CUSTOM_SETTING=keep-me$/m); - assert.match( - result.content, - /^VAPI_CREDENTIAL_CRM_API=credential-1$/m, - ); + assert.match(result.content, /^VAPI_CREDENTIAL_CRM_API=credential-1$/m); assert.match( result.content, /^VAPI_PHONE_NUMBER_OLD_NAME=phone-1$/m, @@ -72,10 +67,7 @@ test("manual bindings outside the generated block win without duplication", () = [], ); - assert.equal( - result.content.match(/^VAPI_CREDENTIAL_CRM_API=/gm)?.length, - 1, - ); + assert.equal(result.content.match(/^VAPI_CREDENTIAL_CRM_API=/gm)?.length, 1); assert.match(result.content, /^VAPI_CREDENTIAL_CRM_API=manual-id$/m); assert.match(result.warnings[0]!, /keeping the manually managed value/i); }); @@ -107,10 +99,7 @@ test("a previously confirmed phone alias wins over a new duplicate name", () => ], ); - assert.match( - result.content, - /^VAPI_PHONE_NUMBER_SUPPORT_LINE=phone-a$/m, - ); + assert.match(result.content, /^VAPI_PHONE_NUMBER_SUPPORT_LINE=phone-a$/m); assert.doesNotMatch(result.content, /=phone-b$/m); assert.match(result.warnings[0]!, /already confirmed/i); }); @@ -136,7 +125,9 @@ test("fetchAllPhoneNumbers follows v2 pagination", async () => { const result = await fetchAllPhoneNumbers(async (endpoint) => { requested.push(endpoint); - const page = Number(new URL(endpoint, "https://example.test").searchParams.get("page")); + const page = Number( + new URL(endpoint, "https://example.test").searchParams.get("page"), + ); return pages.get(page); }, 1); diff --git a/tests/check-cmd.test.ts b/tests/check-cmd.test.ts index 1fb8f50..bd7abcc 100644 --- a/tests/check-cmd.test.ts +++ b/tests/check-cmd.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; import { @@ -130,11 +131,13 @@ test("usage, config and selection errors exit 2", async () => { test("a missing state file is a warning, not an error", async () => { const root = parityCopy(); try { - rmSync(join(root, ".vapi-state.parity.json")); + rmSync(join(root, "state/parity/state.json")); const result = await run(["core", "--dry-run"], root); assert.deepEqual( [ result.code, + // Named where its first write would go: with no state anywhere and + // no commit step seen to stage state/, that is the repository root. result.out.includes("⚠️ no .vapi-state.parity.json"), existsSync(join(root, "tmp")), ], diff --git a/tests/check-config.test.ts b/tests/check-config.test.ts index c5ba4ae..dd8b20b 100644 --- a/tests/check-config.test.ts +++ b/tests/check-config.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; diff --git a/tests/check-mocks.test.ts b/tests/check-mocks.test.ts index aa40094..6f3c586 100644 --- a/tests/check-mocks.test.ts +++ b/tests/check-mocks.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { checksConfigParse } from "../src/check-config.ts"; diff --git a/tests/check-payload.test.ts b/tests/check-payload.test.ts index 7c1e884..6b0f489 100644 --- a/tests/check-payload.test.ts +++ b/tests/check-payload.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; diff --git a/tests/check-report.test.ts b/tests/check-report.test.ts index d0363a8..8c10ead 100644 --- a/tests/check-report.test.ts +++ b/tests/check-report.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import type { CheckJob } from "../src/check-build.ts"; diff --git a/tests/check-run.test.ts b/tests/check-run.test.ts index 0186d57..1faa07d 100644 --- a/tests/check-run.test.ts +++ b/tests/check-run.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { createServer } from "node:http"; import type { AddressInfo } from "node:net"; @@ -13,7 +14,14 @@ import { checkRunAll, MIN_START_MS } from "../src/check-run.ts"; // assistant's name picks the stub's behaviour for that run. type Behaviour = - "pass" | "fail" | "skipped" | "hang" | "slow" | "unmocked" | "402" | "502"; + | "pass" + | "fail" + | "skipped" + | "hang" + | "slow" + | "unmocked" + | "402" + | "502"; interface StubRun { id: string; diff --git a/tests/check-select.test.ts b/tests/check-select.test.ts index 3647e41..9b575a3 100644 --- a/tests/check-select.test.ts +++ b/tests/check-select.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; @@ -26,6 +27,8 @@ test("a check is affected by its org's files, its run org, its state, the engine undefined, "resources/acme-ci/tools/t.yml", ], + ["state/acme/state.json", "state/acme/state.json", undefined], + // A repository that has not moved its state into state/ yet. [".vapi-state.acme.json", ".vapi-state.acme.json", undefined], ["vapi-checks.yml", "vapi-checks.yml", "vapi-checks.yml"], ["src/push.ts", "src/push.ts", "src/push.ts"], diff --git a/tests/check-status.test.ts b/tests/check-status.test.ts index c19643f..7a5d8bd 100644 --- a/tests/check-status.test.ts +++ b/tests/check-status.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { createServer } from "node:http"; import type { AddressInfo } from "node:net"; diff --git a/tests/ci-validate-workflow.test.ts b/tests/ci-validate-workflow.test.ts index daebddb..e7a1c19 100644 --- a/tests/ci-validate-workflow.test.ts +++ b/tests/ci-validate-workflow.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { diff --git a/tests/clean-resource.test.ts b/tests/clean-resource.test.ts index effe9a2..48aa5e1 100644 --- a/tests/clean-resource.test.ts +++ b/tests/clean-resource.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/cleanup-ignore.test.ts b/tests/cleanup-ignore.test.ts index f93e301..0f974a4 100644 --- a/tests/cleanup-ignore.test.ts +++ b/tests/cleanup-ignore.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; import { @@ -14,6 +15,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // `npm run cleanup` deletes platform resources that aren't in the state // file. Resources excluded by .vapi-ignore are never written to state, so @@ -66,7 +68,7 @@ async function cleanupRun( symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir"); writeFileSync(join(dir, `.env.${ORG}`), "VAPI_TOKEN=fake-token-not-used\n"); writeFileSync( - join(dir, `.vapi-state.${ORG}.json`), + stateFixturePath(dir, ORG), JSON.stringify({ assistants: { "front-desk": { uuid: TRACKED } } }), ); mkdirSync(join(dir, "resources", ORG), { recursive: true }); @@ -99,58 +101,54 @@ async function cleanupRun( } } -test( - "a destructive cleanup deletes only true orphans and keeps .vapi-ignore matches", - { timeout: 60_000 }, - async () => { - const result = await cleanupRun(["--force", "--confirm", ORG]); - assert.deepEqual( - { - code: result.code, - deletes: result.deletes, - retainedAssistant: result.output.includes( - "Legacy Bot retained (matched .vapi-ignore: assistants/legacy-*)", - ), - retainedTool: result.output.includes( - "legacy_lookup retained (matched .vapi-ignore: tools/legacy-*)", - ), - }, - { - code: 0, - deletes: [`/assistant/${ORPHAN}`], - retainedAssistant: true, - retainedTool: true, - }, - ); - }, -); +test("a destructive cleanup deletes only true orphans and keeps .vapi-ignore matches", { + timeout: 60_000, +}, async () => { + const result = await cleanupRun(["--force", "--confirm", ORG]); + assert.deepEqual( + { + code: result.code, + deletes: result.deletes, + retainedAssistant: result.output.includes( + "Legacy Bot retained (matched .vapi-ignore: assistants/legacy-*)", + ), + retainedTool: result.output.includes( + "legacy_lookup retained (matched .vapi-ignore: tools/legacy-*)", + ), + }, + { + code: 0, + deletes: [`/assistant/${ORPHAN}`], + retainedAssistant: true, + retainedTool: true, + }, + ); +}); -test( - "a dry run lists ignored resources as kept, not as orphans", - { timeout: 60_000 }, - async () => { - const result = await cleanupRun([]); - assert.deepEqual( - { - code: result.code, - deletes: result.deletes, - orphanListed: result.output.includes( - `assistants: Old Experiment (${ORPHAN})`, - ), - ignoredListed: - result.output.includes(IGNORED_ASSISTANT) && - result.output.includes("🗑️ assistants: Legacy Bot"), - keptSummary: result.output.includes( - "2 resource(s) not in state were kept because they match .vapi-ignore", - ), - }, - { - code: 0, - deletes: [], - orphanListed: true, - ignoredListed: false, - keptSummary: true, - }, - ); - }, -); +test("a dry run lists ignored resources as kept, not as orphans", { + timeout: 60_000, +}, async () => { + const result = await cleanupRun([]); + assert.deepEqual( + { + code: result.code, + deletes: result.deletes, + orphanListed: result.output.includes( + `assistants: Old Experiment (${ORPHAN})`, + ), + ignoredListed: + result.output.includes(IGNORED_ASSISTANT) && + result.output.includes("🗑️ assistants: Legacy Bot"), + keptSummary: result.output.includes( + "2 resource(s) not in state were kept because they match .vapi-ignore", + ), + }, + { + code: 0, + deletes: [], + orphanListed: true, + ignoredListed: false, + keptSummary: true, + }, + ); +}); diff --git a/tests/cleanup-safety.test.ts b/tests/cleanup-safety.test.ts index 08749c9..08a6910 100644 --- a/tests/cleanup-safety.test.ts +++ b/tests/cleanup-safety.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -11,6 +12,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // Regression tests for P0-4. // @@ -51,7 +53,7 @@ function setupFixture(stateContent: object | null): Fixture { ); if (stateContent !== null) { writeFileSync( - join(dir, ".vapi-state.test-cleanup-org.json"), + stateFixturePath(dir, "test-cleanup-org"), JSON.stringify(stateContent), ); } diff --git a/tests/cli-arg-parsing.test.ts b/tests/cli-arg-parsing.test.ts index 8066ddb..b8077a1 100644 --- a/tests/cli-arg-parsing.test.ts +++ b/tests/cli-arg-parsing.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { diff --git a/tests/config-api-key.test.ts b/tests/config-api-key.test.ts index 05d5368..5d5e861 100644 --- a/tests/config-api-key.test.ts +++ b/tests/config-api-key.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -35,9 +36,18 @@ function validateRun( const result = spawnSync( process.execPath, ["--import", "tsx", "src/validate-cmd.ts", "acme-prod"], - { cwd: dir, encoding: "utf8", timeout: 30_000, env: { ...process.env, ...env } }, + { + cwd: dir, + encoding: "utf8", + timeout: 30_000, + env: { ...process.env, ...env }, + }, ); - return { code: result.status, stdout: result.stdout, stderr: result.stderr }; + return { + code: result.status, + stdout: result.stdout, + stderr: result.stderr, + }; } finally { rmSync(dir, { recursive: true, force: true }); } @@ -66,6 +76,9 @@ test("the org's own variable is used and named, with no warning", () => { test("a key only in .env. is used quietly", () => { const run = validateRun("VAPI_PRIVATE_API_KEY=prod-key\n", {}); - assert.doesNotMatch(`${run.stdout}${run.stderr}`, /Using the API key|different key/); + assert.doesNotMatch( + `${run.stdout}${run.stderr}`, + /Using the API key|different key/, + ); assert.equal(run.code, 0); }); diff --git a/tests/conflict-timing.test.ts b/tests/conflict-timing.test.ts index 9771af4..ac9fbd8 100644 --- a/tests/conflict-timing.test.ts +++ b/tests/conflict-timing.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; @@ -64,7 +65,9 @@ test("one side alone still produces a usable line", () => { // A resource with no local file, or an unreadable stat, must not blank the // whole report. assert.match( - conflictTimingHint({ dashboardUpdatedAt: new Date(T0).toISOString() }) as string, + conflictTimingHint({ + dashboardUpdatedAt: new Date(T0).toISOString(), + }) as string, /^dashboard changed 2026-08-01 12:00Z$/, ); assert.match( @@ -77,8 +80,14 @@ test("no usable timestamp yields no line at all", () => { // The caller appends this to an existing bullet, so an empty hint has to be // distinguishable from a hint that happens to be short. assert.equal(conflictTimingHint({}), undefined); - assert.equal(conflictTimingHint({ dashboardUpdatedAt: 1754049600000 }), undefined); - assert.equal(conflictTimingHint({ dashboardUpdatedAt: "not a date" }), undefined); + assert.equal( + conflictTimingHint({ dashboardUpdatedAt: 1754049600000 }), + undefined, + ); + assert.equal( + conflictTimingHint({ dashboardUpdatedAt: "not a date" }), + undefined, + ); assert.equal(conflictTimingHint({ localModifiedMs: Number.NaN }), undefined); }); diff --git a/tests/credentials.test.ts b/tests/credentials.test.ts index 2864cd4..ae7464f 100644 --- a/tests/credentials.test.ts +++ b/tests/credentials.test.ts @@ -1,9 +1,10 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { credentialForwardMap as forwardMap, - credentialReverseMap as reverseMap, replaceCredentialRefs, + credentialReverseMap as reverseMap, } from "../src/credentials.ts"; import type { StateFile } from "../src/types.ts"; diff --git a/tests/dep-dedup.test.ts b/tests/dep-dedup.test.ts index f7319f5..3f4000b 100644 --- a/tests/dep-dedup.test.ts +++ b/tests/dep-dedup.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { diff --git a/tests/docs-commands.test.ts b/tests/docs-commands.test.ts index 974e278..1a877f9 100644 --- a/tests/docs-commands.test.ts +++ b/tests/docs-commands.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; diff --git a/tests/docs-links.test.ts b/tests/docs-links.test.ts index b72abd1..80ae69f 100644 --- a/tests/docs-links.test.ts +++ b/tests/docs-links.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { dirname, join, normalize, relative } from "node:path"; diff --git a/tests/drift.test.ts b/tests/drift.test.ts index ae90704..bdd1425 100644 --- a/tests/drift.test.ts +++ b/tests/drift.test.ts @@ -1,19 +1,17 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; +import { + deleteBaseline, + readBaseline, + writeBaseline, +} from "../src/hash-store.ts"; import { checkPronunciationDictDrop, hashPayload, upsertState, } from "../src/state-serialize.ts"; import type { ResourceState } from "../src/types.ts"; -import { - deleteBaseline, - hashStoreDir, - readBaseline, - writeBaseline, -} from "../src/hash-store.ts"; -import { rmSync } from "node:fs"; -import { after } from "node:test"; // Stack G — drift unit tests. // `checkDriftForUpdate` itself fires GET against the Vapi platform; a unit @@ -64,27 +62,27 @@ process.env.VAPI_TOKEN = process.env.VAPI_TOKEN || "test-token-not-used"; const driftModule = await import("../src/drift.ts"); const { classifyDrift, formatDriftLabel, checkDriftForUpdate } = driftModule as unknown as { - classifyDrift?: (input: { - localHash: string; - lastPulledHash?: string; - platformHash: string; - }) => string; - formatDriftLabel?: (direction: string) => string; - checkDriftForUpdate?: (options: { - endpoint: string; - resourceLabel: string; - resourceType: string; - resourceId: string; - state: Record>; - env: string; - overwrite: boolean; - }) => Promise<{ - ok: boolean; - reason: string; - message?: string; - platformHash?: string; - }>; -}; + classifyDrift?: (input: { + localHash: string; + lastPulledHash?: string; + platformHash: string; + }) => string; + formatDriftLabel?: (direction: string) => string; + checkDriftForUpdate?: (options: { + endpoint: string; + resourceLabel: string; + resourceType: string; + resourceId: string; + state: Record>; + env: string; + overwrite: boolean; + }) => Promise<{ + ok: boolean; + reason: string; + message?: string; + platformHash?: string; + }>; + }; // Full StateFile shape (all sections present) — `canonicalizeForHash` walks // every resource-type section via buildReverseMap and `credentialReverseMap` @@ -107,13 +105,10 @@ function driftState( } as Record>; } -// Drift baselines live in the hash store (.vapi-state-hash//), which -// resolves beside src/ rather than under a temp dir. Seed them under an org slug -// no real checkout uses, and remove the whole folder when the file finishes. +// Drift baselines live in the hash store, in the temporary directory the +// engine works in under test (tests/no-vapi-api.ts), which is removed whole +// when this file's process exits. const HASH_STORE_TEST_ENV = `drift-test-${process.pid}`; -after(() => { - rmSync(hashStoreDir(HASH_STORE_TEST_ENV), { recursive: true, force: true }); -}); test("checkPronunciationDictDrop: warns when prior had ID and new lost it", () => { const prior = { @@ -516,7 +511,11 @@ test("checkDriftForUpdate: drift-blocked message includes a bracketed direction // dashboard-ahead (local clean, platform moved). const remote = { name: "intake-bot", systemPrompt: "hello" }; // A baseline that cannot equal the canonicalized platform hash → drift. - await writeBaseline(HASH_STORE_TEST_ENV, "test-uuid", "stale-baseline-hash-deadbeef"); + await writeBaseline( + HASH_STORE_TEST_ENV, + "test-uuid", + "stale-baseline-hash-deadbeef", + ); const originalFetch = globalThis.fetch; globalThis.fetch = makeFetchStub(remote) as typeof globalThis.fetch; @@ -581,7 +580,11 @@ test("checkDriftForUpdate: canonicalizes the platform payload (tool UUID → res name: "intake-bot", model: { provider: "openai", toolIds: ["my-tool-abc12345"] }, }; - await writeBaseline(HASH_STORE_TEST_ENV, "assistant-uuid", hashPayload(canonicalForm)); + await writeBaseline( + HASH_STORE_TEST_ENV, + "assistant-uuid", + hashPayload(canonicalForm), + ); const originalFetch = globalThis.fetch; globalThis.fetch = makeFetchStub(remoteRaw) as typeof globalThis.fetch; @@ -692,7 +695,11 @@ test("canonicalizeForHash: applies _platformDefault when orgId === null", () => emptyState, emptyCredReverse, ); - assert.equal(result._platformDefault, true, "_platformDefault marker must be injected for null orgId"); + assert.equal( + result._platformDefault, + true, + "_platformDefault marker must be injected for null orgId", + ); }); test("canonicalizeForHash: applies _platformDefault when orgId is undefined", () => { @@ -728,8 +735,12 @@ test("canonicalizeForHash: deterministic — same input produces same hash", () voice: { provider: "11labs", voiceId: "v1" }, model: { provider: "openai", model: "gpt-4" }, }; - const a = hashPayload(canonicalizeForHash!(input, emptyState, emptyCredReverse)); - const b = hashPayload(canonicalizeForHash!(input, emptyState, emptyCredReverse)); + const a = hashPayload( + canonicalizeForHash!(input, emptyState, emptyCredReverse), + ); + const b = hashPayload( + canonicalizeForHash!(input, emptyState, emptyCredReverse), + ); assert.equal(a, b, "canonicalizeForHash must be deterministic"); }); diff --git a/tests/engine-sandbox.test.ts b/tests/engine-sandbox.test.ts new file mode 100644 index 0000000..075c405 --- /dev/null +++ b/tests/engine-sandbox.test.ts @@ -0,0 +1,177 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + cpSync, + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { SANDBOX, SANDBOX_FROM_FOLDER, testFiles } from "./engine-tests.ts"; + +// Two things keep an engine test out of the repository it runs in. Both come +// from tests/engine-sandbox.ts, which every engine test imports first: the +// engine gets a temporary directory to work in, and every node:fs change +// inside the repository throws. They travel with the test file, so they hold +// however the file is started. +// +// `npm run test:repository` checks the result from the outside: it runs the +// suite inside copies of a repository and compares every file. + +const REPO = join(dirname(fileURLToPath(import.meta.url)), ".."); + +test("a test can't create, change or remove anything in the repository it runs in", async () => { + const inside = /inside the repository it runs in/; + assert.throws(() => writeFileSync(join(REPO, "x.txt"), "x"), inside); + assert.throws(() => mkdirSync(join(REPO, "tmp")), inside); + assert.throws(() => rmSync(REPO, { recursive: true, force: true }), inside); + assert.throws( + () => rmSync(join(REPO, "src", ".."), { recursive: true, force: true }), + inside, + ); + assert.throws( + () => renameSync(join(REPO, "package.json"), join(tmpdir(), "p.json")), + inside, + ); + assert.throws( + () => cpSync(join(REPO, "package.json"), join(REPO, "copy.json")), + inside, + ); + await assert.rejects(async () => writeFile(join(REPO, "x.txt"), "x"), inside); + await assert.rejects( + async () => rm(join(REPO, "src"), { recursive: true }), + inside, + ); + // Reading is fine, and so is anything under a temporary directory. + assert.ok(readFileSync(join(REPO, "package.json"), "utf8").length > 0); + const own = mkdtempSync(join(tmpdir(), "suite-guard-")); + writeFileSync(join(own, "a"), "a"); + rmSync(own, { recursive: true }); +}); + +// Where the engine says it works, asked from a new process in this +// repository. +function where( + change: (env: NodeJS.ProcessEnv) => void, + program = 'import { baseDir } from "./src/base-dir.ts"; console.log(baseDir());', + cwd = REPO, +): string { + const env: NodeJS.ProcessEnv = { ...process.env }; + change(env); + const run = spawnSync( + process.execPath, + ["--import", "tsx", "--input-type=module", "-e", program], + { cwd, env, encoding: "utf8" }, + ); + return run.status === 0 ? run.stdout.trim() : run.stderr; +} +const unsandboxed = (env: NodeJS.ProcessEnv) => { + delete env.VAPI_GITOPS_TEST_ROOT; + delete env.VAPI_GITOPS_TEST_REPO; +}; + +test("the engine works in a temporary directory for an engine test and what it starts, and in its repository for everything else", () => { + const sandbox = process.env.VAPI_GITOPS_TEST_ROOT; + assert.ok(sandbox && !sandbox.startsWith(REPO)); + // A copy of the engine somewhere else, as a test builds to run a command + // in a repository of its own making. + const copy = realpathSync(mkdtempSync(join(tmpdir(), "engine-copy-"))); + mkdirSync(join(copy, "src")); + cpSync(join(REPO, "src/base-dir.ts"), join(copy, "src/base-dir.ts")); + cpSync(join(REPO, "package.json"), join(copy, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(copy, "node_modules"), "dir"); + const fromCopy = where(() => {}, undefined, copy); + rmSync(copy, { recursive: true, force: true }); + assert.deepEqual( + [ + // A command this test starts from that copy: the copy, though the + // sandbox is in its environment. + fromCopy, + // A command this test starts: the temporary directory. + where(() => {}), + // A command nobody's test started: the repository that holds src/. + where((env) => { + unsandboxed(env); + delete env.NODE_TEST_CONTEXT; + }), + // A command started under a test runner by a test that isn't the + // engine's. The runner leaves this variable behind, and the engine + // doesn't look at it. + where((env) => { + unsandboxed(env); + env.NODE_TEST_CONTEXT = "child-v8"; + }), + ], + [copy, sandbox, REPO, REPO], + ); +}); + +test("an engine test started by hand, without the preload npm test adds, still works in a temporary directory", () => { + // What a test file does at its top: the sandbox first, then the engine. + // hash-store.ts settles its directory while it loads, so this fails if the + // sandbox were not finished by then. + const at = where((env) => { + unsandboxed(env); + delete env.NODE_TEST_CONTEXT; + }, [ + 'import "./tests/engine-sandbox.ts";', + 'import { hashStoreDir } from "./src/hash-store.ts";', + 'console.log(hashStoreDir("acme"));', + ].join("\n")); + assert.deepEqual( + [at.startsWith(REPO), at.includes("vapi-gitops-test-"), /acme$/.test(at)], + [false, true, true], + at, + ); +}); + +// Whether this is CI for the engine's own repository, by the name GitHub +// gives the runner. Anywhere else, a person's machine included, a test file +// without the import is that repository's own test, whatever origin says: a +// repository cloned straight from the engine's keeps its origin. +function engineRepositoryCi(): boolean { + return process.env.GITHUB_REPOSITORY?.toLowerCase() === "vapiai/gitops"; +} + +test("in CI for the engine's own repository, every test file imports the sandbox first", { + skip: engineRepositoryCi() + ? false + : "not CI for the engine's own repository: a test file without the import is this repository's own", +}, () => { + const other = [ + ...testFiles(join(REPO, "tests")).other, + ...testFiles(join(REPO, "tests/repository"), SANDBOX_FROM_FOLDER).other.map( + (name) => `repository/${name}`, + ), + ]; + assert.deepEqual( + other, + [], + `Every engine test file starts with ${SANDBOX} (${SANDBOX_FROM_FOLDER} under tests/repository/) and these don't: ${other.join(", ")}. This is asked because GITHUB_REPOSITORY is VapiAI/gitops; anywhere else a test file without the import is left alone.`, + ); +}); + +// A suite inside a suite is slow, and reaches the time limits some tests +// give a command sooner. A test that starts a test runner of its own lives +// in tests/repository/ and runs with `npm run test:repository`, so `npm test` +// takes what it took before those tests existed. +test("no test that npm test runs starts a test runner of its own", () => { + // Spelled in two halves so this file doesn't match itself. + const runnerFlag = ["--", "test"].join(""); + assert.deepEqual( + testFiles(join(REPO, "tests")).engine.filter((name) => + readFileSync(join(REPO, "tests", name), "utf8").includes(runnerFlag), + ), + [], + ); +}); diff --git a/tests/engine-sandbox.ts b/tests/engine-sandbox.ts new file mode 100644 index 0000000..5acd61d --- /dev/null +++ b/tests/engine-sandbox.ts @@ -0,0 +1,110 @@ +// The first import of every test file that belongs to the engine: +// +// import "./engine-sandbox.ts"; +// +// (`"../engine-sandbox.ts"` from tests/repository/.) +// +// A test must never read, write or remove anything in the repository it runs +// in. Importing this module, before anything from src/, does two things in +// the test's own process, however the test was started. +// +// It gives the engine a temporary directory to work in. The engine loaded +// from this repository's src/ resolves its state, baselines, snapshots and +// resources there (src/base-dir.ts), and so does any path a test derives +// from them. No test cleans the engine's folders up: the whole directory is +// removed when the process exits. +// +// And it makes every node:fs call that creates, changes or removes something +// throw when its target is inside the repository, for a test that builds a +// path to the repository itself. A test's files belong in a directory it +// made under os.tmpdir(). +// +// A test file that doesn't import this module gets neither. That is how a +// test of your own, in a repository built from this one, keeps working in +// that repository as it always has. +// +// Keep this module free of top-level await: it has to finish before the +// imports that follow it are evaluated. +import fs, { mkdirSync, mkdtempSync, rmSync } from "node:fs"; +import { syncBuiltinESMExports } from "node:module"; +import { tmpdir } from "node:os"; +import { dirname, join, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; + +const repository = join(dirname(fileURLToPath(import.meta.url)), ".."); +const box = mkdtempSync(join(tmpdir(), "vapi-gitops-test-")); +const root = join(box, "repo"); +mkdirSync(root); +process.env.VAPI_GITOPS_TEST_REPO = repository; +process.env.VAPI_GITOPS_TEST_ROOT = root; +process.on("exit", () => rmSync(box, { recursive: true, force: true })); + +function inRepository(target: unknown): boolean { + if (typeof target !== "string" && !(target instanceof URL)) return false; + const path = resolve(target instanceof URL ? fileURLToPath(target) : target); + return ( + (path === repository || path.startsWith(repository + sep)) && + !path.startsWith(join(repository, "node_modules") + sep) + ); +} + +// Each name with the positions of the paths it changes. +const CHANGES: Record = { + appendFile: [0], + chmod: [0], + copyFile: [1], + cp: [1], + createWriteStream: [0], + link: [1], + mkdir: [0], + mkdtemp: [0], + rename: [0, 1], + rm: [0], + rmdir: [0], + symlink: [1], + truncate: [0], + unlink: [0], + utimes: [0], + writeFile: [0], +}; + +function guard(holder: Record, name: string, at: number[]) { + const real = holder[name]; + if (typeof real !== "function") return; + holder[name] = function (this: unknown, ...args: unknown[]) { + for (const index of at) + if (inRepository(args[index])) + throw new Error( + `A test called ${name} on ${String(args[index])}, inside the repository it runs in. Tests work in a directory they create under os.tmpdir().`, + ); + return real.apply(this, args); + }; +} + +for (const [name, at] of Object.entries(CHANGES)) { + guard(fs as unknown as Record, name, at); + guard(fs as unknown as Record, `${name}Sync`, at); + guard(fs.promises as unknown as Record, name, at); +} +// Opening a file to write it is a change too. +for (const [holder, name] of [ + [fs, "open"], + [fs, "openSync"], + [fs.promises, "open"], +] as const) { + const real = ( + holder as unknown as Record unknown> + )[name]!; + (holder as unknown as Record)[name] = function ( + this: unknown, + ...args: unknown[] + ) { + const flags = typeof args[1] === "string" ? args[1] : "r"; + if (flags !== "r" && inRepository(args[0])) + throw new Error( + `A test opened ${String(args[0])} for writing, inside the repository it runs in. Tests work in a directory they create under os.tmpdir().`, + ); + return real.apply(this, args); + }; +} +syncBuiltinESMExports(); diff --git a/tests/engine-tests.ts b/tests/engine-tests.ts new file mode 100644 index 0000000..d49c2ef --- /dev/null +++ b/tests/engine-tests.ts @@ -0,0 +1,28 @@ +import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +// An engine test is a test file whose first import is the sandbox, +// tests/engine-sandbox.ts. Any other test file in tests/ belongs to the +// repository it is in, and is left alone. +export const SANDBOX = 'import "./engine-sandbox.ts";'; +// The same import from tests/repository/, which holds the engine tests that +// start a test runner of their own (`npm run test:repository`). +export const SANDBOX_FROM_FOLDER = 'import "../engine-sandbox.ts";'; + +function firstImport(path: string): string | undefined { + return readFileSync(path, "utf8") + .split("\n") + .find((line) => /^import\b/.test(line)); +} + +export function testFiles( + dir: string, + sandbox = SANDBOX, +): { engine: string[]; other: string[] } { + if (!existsSync(dir)) return { engine: [], other: [] }; + const names = readdirSync(dir).filter((name) => name.endsWith(".test.ts")); + const engine = names.filter( + (name) => firstImport(join(dir, name)) === sandbox, + ); + return { engine, other: names.filter((name) => !engine.includes(name)) }; +} diff --git a/tests/examples.test.ts b/tests/examples.test.ts index 93e015d..58feca2 100644 --- a/tests/examples.test.ts +++ b/tests/examples.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -112,7 +113,7 @@ test("the starter example's PR check builds with no errors or warnings", async ( readFileSync(join(root, "vapi-checks.yml"), "utf8"), ).checks.core!; const state = promotionStateParse( - readFileSync(join(root, ".vapi-state.starter.json"), "utf8"), + readFileSync(join(root, "state/starter/state.json"), "utf8"), ); const result = checkPayloadBuild({ check, diff --git a/tests/first-state-file.test.ts b/tests/first-state-file.test.ts new file mode 100644 index 0000000..1926b4f --- /dev/null +++ b/tests/first-state-file.test.ts @@ -0,0 +1,245 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawn } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { + OLD_LAYOUT_NOTICE, + stateFileLegacyPath, + stateFilePath, + stateFileWrite, + stateLayoutPrepare, + stateNoticesPrint, +} from "../src/state-paths.ts"; + +// A repository with no engine state at all gets its first state file at the +// root unless a workflow is seen to stage state/, or a person has said their +// commit step does. A commit step the engine can't read (a script, a commit +// action, another CI system) might stage only state/, and then that first +// file would never be committed. The engine can't tell, so the run says +// where state goes and what has to stage it. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); +const ORG = "dev"; +const CI = { CI: "true" }; +const WORKFLOW = ".github/workflows/promote.yml"; + +const workflow = (run: string): string => + [ + "name: promote", + "on: push", + "permissions:", + " contents: write", + "jobs:", + " run:", + " runs-on: ubuntu-latest", + " steps:", + " - uses: actions/checkout@v4", + ` - run: ${run}`, + "", + ].join("\n"); + +const SCRIPT = workflow("./scripts/commit-state.sh"); +const OLD_FILE_ONLY = workflow( + "git add -A -- ':(glob).vapi-state.*.json' resources && git commit -m state && git push", +); +const BOTH = workflow( + "git add -A -- state ':(glob).vapi-state.*.json' && git commit -m state && git push", +); + +function repo(files: Record = {}): string { + const root = mkdtempSync(join(tmpdir(), "first-state-")); + for (const [path, content] of Object.entries(files)) { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); + } + return root; +} + +function read(files: Record, env: NodeJS.ProcessEnv = {}) { + const root = repo(files); + try { + const notices = stateLayoutPrepare(root, ORG, env); + return { + notices, + atRoot: stateFileWrite(root, ORG) === stateFileLegacyPath(root, ORG), + }; + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +test("a first state file written at the root says where it goes and what has to stage it", () => { + for (const env of [{}, CI]) { + const script = read({ [WORKFLOW]: SCRIPT }, env); + const none = read({}, env); + const [line] = script.notices; + assert.deepEqual( + [ + script.notices.length, + script.atRoot, + line?.includes("\n"), + line?.includes(".vapi-state.dev.json at the repository root"), + // Why: which file may commit, and that it isn't seen to stage state/. + line?.includes( + `${WORKFLOW} can commit to this repository and is not seen to stage state/`, + ), + // What has to stage it. + line?.includes("has to stage .vapi-state.*.json"), + // What to do when the step stages state/ instead. + line?.includes("npm run migrate -- --commit-step-stages-state"), + none.notices.length, + none.atRoot, + none.notices[0]?.includes( + "no workflow in .github/workflows/ is seen to stage state/", + ), + none.notices[0]?.includes("has to stage .vapi-state.*.json"), + ], + [1, true, false, true, true, true, true, 1, true, true, true], + ); + } +}); + +test("a workflow seen to stage the old file gets the short line, and one seen to stage state/ gets none", () => { + const stale = read({ [WORKFLOW]: OLD_FILE_ONLY }); + const seen = read({ [WORKFLOW]: BOTH }); + const said = read({ + [WORKFLOW]: SCRIPT, + "state/commit-step.json": '{\n "stagesStateFolder": true\n}\n', + }); + assert.deepEqual( + [ + stale.notices, + stale.atRoot, + seen.notices, + seen.atRoot, + said.notices, + said.atRoot, + ], + [ + [ + `ℹ️ No engine state in this repository yet: it goes to .vapi-state.dev.json at the repository root, which ${WORKFLOW} stages.`, + ], + true, + [], + false, + [], + false, + ], + ); +}); + +test("once a state file exists the line is the older-layout one, for that org and for a new one", () => { + const root = repo({ + [WORKFLOW]: SCRIPT, + ".vapi-state.dev.json": '{\n "assistants": {}\n}\n', + }); + try { + assert.deepEqual( + [stateLayoutPrepare(root, ORG, {}), stateLayoutPrepare(root, "prod", {})], + [[OLD_LAYOUT_NOTICE], [OLD_LAYOUT_NOTICE]], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a command prints one layout line, also when its first step writes the first state file", () => { + const root = repo({ [WORKFLOW]: SCRIPT }); + const printed: string[] = []; + const log = console.log; + console.log = (line: string) => void printed.push(line); + try { + const [first] = stateLayoutPrepare(root, ORG, {}); + // apply prints the line, then its pull writes the state file and its + // push would print the older-layout line. + const command: NodeJS.ProcessEnv = {}; + stateNoticesPrint([first!], command); + stateNoticesPrint([OLD_LAYOUT_NOTICE], command); + assert.deepEqual(printed, [first]); + } finally { + console.log = log; + rmSync(root, { recursive: true, force: true }); + } +}); + +// One pull, end to end, in a new repository whose workflow commits through a +// script. +async function pull(root: string): Promise { + const server = createServer((_request, response) => { + response.setHeader("content-type", "application/json"); + response.end("[]"); + }); + await new Promise((done) => server.listen(0, "127.0.0.1", done)); + try { + const env: NodeJS.ProcessEnv = { + ...process.env, + VAPI_PRIVATE_API_KEY: "test-key", + VAPI_BASE_URL: + "http://127.0.0.1:" + (server.address() as AddressInfo).port, + VAPI_GITOPS_ORG_PIN: "off", + VAPI_GITOPS_OLD_LAYOUT_NOTICE: "", + }; + delete env.CI; + delete env.GITHUB_ACTIONS; + const child = spawn( + process.execPath, + ["--import", "tsx", "src/pull-cmd.ts", ORG], + { cwd: root, stdio: ["ignore", "pipe", "pipe"], env }, + ); + let out = ""; + child.stdout.on("data", (chunk) => (out += String(chunk))); + child.stderr.on("data", (chunk) => (out += String(chunk))); + const code = await new Promise((done) => + child.on("close", done), + ); + assert.equal(code, 0, out); + return out; + } finally { + await new Promise((done) => server.close(done)); + } +} + +test("the first pull in a new repository prints the line once, and the next pull prints the older-layout line", async () => { + const root = repo({ [WORKFLOW]: SCRIPT, ".gitignore": "node_modules\n" }); + try { + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root }); + const count = (out: string, text: string) => out.split(text).length - 1; + const first = await pull(root); + const wrote = [ + existsSync(stateFileLegacyPath(root, ORG)), + existsSync(stateFilePath(root, ORG)), + ]; + const second = await pull(root); + assert.deepEqual( + [ + count(first, "No engine state in this repository yet"), + count(first, "has to stage .vapi-state.*.json"), + count(first, OLD_LAYOUT_NOTICE), + wrote, + count(second, "No engine state in this repository yet"), + count(second, OLD_LAYOUT_NOTICE), + ], + [1, 1, 0, [true, false], 0, 1], + first + second, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/tests/fixtures/check-parity/.vapi-state.parity.json b/tests/fixtures/check-parity/state/parity/state.json similarity index 100% rename from tests/fixtures/check-parity/.vapi-state.parity.json rename to tests/fixtures/check-parity/state/parity/state.json diff --git a/tests/list-pagination.test.ts b/tests/list-pagination.test.ts index 41d95c5..c02c936 100644 --- a/tests/list-pagination.test.ts +++ b/tests/list-pagination.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { createServer } from "node:http"; import type { AddressInfo } from "node:net"; @@ -100,9 +101,7 @@ test("a short first page is complete: no second request, no warning", async () = test("a full first page is paged through until a short page arrives", async () => { reset((url) => - url.includes("createdAtLe") - ? { body: page(4, 100) } - : { body: page(100) }, + url.includes("createdAtLe") ? { body: page(4, 100) } : { body: page(100) }, ); const { result, warnings } = await capturingWarnings(() => fetchAllResources("tools"), @@ -119,7 +118,10 @@ test("the cursor is inclusive, so items sharing the boundary timestamp survive", // Resources created in bulk do collide on `createdAt`, and a dropped item then // looks deleted to anything that infers absence. const shared = new Date(BASE - 99 * 60_000).toISOString(); - const firstPage = [...page(99), { id: "boundary-a", name: "a", createdAt: shared }]; + const firstPage = [ + ...page(99), + { id: "boundary-a", name: "a", createdAt: shared }, + ]; const secondPage = [ { id: "boundary-a", name: "a", createdAt: shared }, // re-read, deduped { id: "boundary-b", name: "b", createdAt: shared }, // would be lost by `Lt` @@ -130,8 +132,15 @@ test("the cursor is inclusive, so items sharing the boundary timestamp survive", const result = await fetchAllResources("tools"); const ids = result.map((r) => r.id); - assert.equal(new Set(ids).size, ids.length, "the boundary item is not duplicated"); - assert.ok(ids.includes("boundary-b"), "the co-timestamped item is not dropped"); + assert.equal( + new Set(ids).size, + ids.length, + "the boundary item is not duplicated", + ); + assert.ok( + ids.includes("boundary-b"), + "the co-timestamped item is not dropped", + ); }); test("an endpoint that ignores the cursor is reported, not looped on", async () => { @@ -149,14 +158,21 @@ test("an endpoint that ignores the cursor is reported, not looped on", async () test("a page with no usable createdAt cannot be paged, and says so", async () => { reset(() => ({ - body: Array.from({ length: 100 }, (_, i) => ({ id: `x-${i}`, name: `x ${i}` })), + body: Array.from({ length: 100 }, (_, i) => ({ + id: `x-${i}`, + name: `x ${i}`, + })), })); const { result, warnings } = await capturingWarnings(() => fetchAllResources("tools"), ); assert.equal(result.length, 100); - assert.equal(requests.length, 1, "no cursor is guessable, so no second request"); + assert.equal( + requests.length, + 1, + "no cursor is guessable, so no second request", + ); assert.match(warnings, /listing may be incomplete/); }); @@ -212,6 +228,9 @@ test("the cursor advances across several pages, not just one", async () => { const ids = new Set(result.map((r) => r.id)); assert.equal(ids.size, result.length, "no duplicates across pages"); assert.equal(result.length, 250, "every item across three pages is returned"); - assert.ok(requests.length >= 3, `expected a multi-page walk, made ${requests.length}`); + assert.ok( + requests.length >= 3, + `expected a multi-page walk, made ${requests.length}`, + ); assert.doesNotMatch(warnings, /incomplete/); }); diff --git a/tests/name-collisions.test.ts b/tests/name-collisions.test.ts index b4883b6..e932ec2 100644 --- a/tests/name-collisions.test.ts +++ b/tests/name-collisions.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { NameCollisionReport } from "../src/name-collisions.ts"; diff --git a/tests/new-file-gate.test.ts b/tests/new-file-gate.test.ts index 855a23a..4527584 100644 --- a/tests/new-file-gate.test.ts +++ b/tests/new-file-gate.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -13,6 +14,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // new-file-gate.ts → pull.ts → config.ts: config.ts asserts argv[2] / // VAPI_TOKEN at module load. Prime both before importing the module under @@ -439,7 +441,7 @@ function setupFixture(init: FixtureInit = {}): Fixture { init.state === null ? null : (init.state ?? defaultState); if (stateToWrite !== null) { writeFileSync( - join(dir, `.vapi-state.${env}.json`), + stateFixturePath(dir, env), JSON.stringify(stateToWrite, null, 2), ); } @@ -644,7 +646,7 @@ test("integration: bootstrap UUID-suffixed mapping never takes over a local slug state, }); try { - const statePath = join(fx.dir, `.vapi-state.${fx.env}.json`); + const statePath = stateFixturePath(fx.dir, fx.env); const before = readFileSync(statePath, "utf8"); const res = runPush(fx, []); assert.equal(res.code, 1, res.stdout + res.stderr); diff --git a/tests/org-connection.test.ts b/tests/org-connection.test.ts index 747d9e9..28aad10 100644 --- a/tests/org-connection.test.ts +++ b/tests/org-connection.test.ts @@ -1,9 +1,10 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { - mkdirSync, mkdtempSync, readFileSync, rmSync, + symlinkSync, writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; @@ -17,13 +18,14 @@ import { tokensParse, } from "../src/org-connection.ts"; -// childRun starts `node --import tsx` in rootDir, so child fixtures live -// under the repo (gitignored tmp/) where tsx resolves. -const REPO_TMP = fileURLToPath(new URL("../tmp/", import.meta.url)); +// childRun starts `node --import tsx` in rootDir, and tsx resolves from +// there: a temporary directory with a link to this repository's node_modules. +const NODE_MODULES = fileURLToPath(new URL("../node_modules", import.meta.url)); function repoTempDir(): string { - mkdirSync(REPO_TMP, { recursive: true }); - return mkdtempSync(join(REPO_TMP, "org-connection-")); + const root = mkdtempSync(join(tmpdir(), "org-connection-")); + symlinkSync(NODE_MODULES, join(root, "node_modules"), "dir"); + return root; } function withEnv(name: string, value: string | undefined, run: () => T): T { @@ -202,8 +204,15 @@ test("childRun throws when the script fails", () => { test("connectionLoad uses VAPI_PRIVATE_API_KEY_ before .env.", () => { const root = mkdtempSync(join(tmpdir(), "org-connection-")); try { - writeFileSync(join(root, ".env.acme-dev"), "VAPI_PRIVATE_API_KEY=file-key\n"); - const base = { rootDir: root, org: "acme-dev", tokensEnvName: "TEST_TOKENS" }; + writeFileSync( + join(root, ".env.acme-dev"), + "VAPI_PRIVATE_API_KEY=file-key\n", + ); + const base = { + rootDir: root, + org: "acme-dev", + tokensEnvName: "TEST_TOKENS", + }; assert.deepEqual( withEnv("VAPI_PRIVATE_API_KEY_ACME_DEV", "org-var-key", () => [ connectionLoad({ ...base, tokens: new Map([["acme-dev", "map-key"]]) }), diff --git a/tests/org-pin.test.ts b/tests/org-pin.test.ts index c58ec41..2675137 100644 --- a/tests/org-pin.test.ts +++ b/tests/org-pin.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; import { @@ -18,23 +19,28 @@ import test from "node:test"; import { fileURLToPath } from "node:url"; import { keyOrgFetch, - ORG_PIN_FILE, OrgPinMismatchError, type OrgProbeFetch, orgPinCheck, orgPinRead, } from "../src/org-pin.ts"; +import { orgPinFilePath, stateFilePath } from "../src/state-paths.ts"; import { VapiApiError } from "../src/vapi-client.ts"; // Nothing used to tie resources// to a Vapi org, so a key for the wrong // org read and wrote that org without a word. The folder now records its org -// in .vapi-org.json, and every command checks the key against it first. +// in state//org.json, and every command checks the key against it first. // tests/no-vapi-api.ts turns the check off for the rest of the suite. delete process.env.VAPI_GITOPS_ORG_PIN; const REPO = fileURLToPath(new URL("..", import.meta.url)); -const CONNECTION = { token: "test-token-not-used", baseUrl: "http://stub", userAgent: "test", vapiClient: "test" }; +const CONNECTION = { + token: "test-token-not-used", + baseUrl: "http://stub", + userAgent: "test", + vapiClient: "test", +}; const SOURCE = "the VAPI_PRIVATE_API_KEY_ACME environment variable"; // A probe stub: endpoint (without the query) → response or error. @@ -56,19 +62,32 @@ function orgDir(options: { folder: boolean; pin?: string }): string { const root = mkdtempSync(join(tmpdir(), "org-pin-")); if (options.folder || options.pin !== undefined) mkdirSync(join(root, "resources", "acme"), { recursive: true }); - if (options.pin !== undefined) - writeFileSync(join(root, "resources", "acme", ORG_PIN_FILE), options.pin); + if (options.pin !== undefined) { + mkdirSync(join(root, "state", "acme"), { recursive: true }); + writeFileSync(orgPinFilePath(root, "acme"), options.pin); + } return root; } const serverError = new VapiApiError("GET", "/tool", 503, "unavailable", ""); -const unauthorized = new VapiApiError("GET", "/assistant", 401, "Unauthorized", ""); +const unauthorized = new VapiApiError( + "GET", + "/assistant", + 401, + "Unauthorized", + "", +); // ── Finding the key's org ──────────────────────────────────────────────── test("keyOrgFetch reads orgId from the first resource listed", async () => { - const { probeFetch, seen } = probes({ "/assistant": [{ id: "a1", orgId: "org-a" }] }); - assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { kind: "found", orgId: "org-a" }); + const { probeFetch, seen } = probes({ + "/assistant": [{ id: "a1", orgId: "org-a" }], + }); + assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { + kind: "found", + orgId: "org-a", + }); assert.deepEqual(seen, ["/assistant?limit=1"]); }); @@ -76,12 +95,17 @@ test("keyOrgFetch moves on from empty lists and reads { results } pages", async const { probeFetch, seen } = probes({ "/structured-output": { results: [{ id: "s1", orgId: "org-a" }] }, }); - assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { kind: "found", orgId: "org-a" }); + assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { + kind: "found", + orgId: "org-a", + }); assert.equal(seen.length, 6); }); test("keyOrgFetch reports an org that lists nothing as empty", async () => { - assert.deepEqual(await keyOrgFetch(CONNECTION, probes({}).probeFetch), { kind: "empty" }); + assert.deepEqual(await keyOrgFetch(CONNECTION, probes({}).probeFetch), { + kind: "empty", + }); }); test("keyOrgFetch reports unknown when a probe fails and none finds an org", async () => { @@ -93,7 +117,9 @@ test("keyOrgFetch reports unknown when a probe fails and none finds an org", asy test("keyOrgFetch stops at a rejected key", async () => { const { probeFetch, seen } = probes({ "/assistant": unauthorized }); - assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { kind: "unknown" }); + assert.deepEqual(await keyOrgFetch(CONNECTION, probeFetch), { + kind: "unknown", + }); assert.deepEqual(seen, ["/assistant?limit=1"]); }); @@ -102,11 +128,20 @@ test("keyOrgFetch stops at a rejected key", async () => { test("orgPinCheck pins an unpinned folder to the key's org", async () => { const root = orgDir({ folder: true }); try { + // The org's state is in state/acme/, so its pin goes beside it. + mkdirSync(join(root, "state", "acme"), { recursive: true }); + writeFileSync(stateFilePath(root, "acme"), "{}\n"); const { probeFetch } = probes({ "/assistant": [{ orgId: "org-a" }] }); - const outcome = await orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch }); + const outcome = await orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch, + }); assert.deepEqual(outcome, { kind: "pinned", orgId: "org-a" }); assert.equal( - readFileSync(join(root, "resources", "acme", ORG_PIN_FILE), "utf8"), + readFileSync(orgPinFilePath(root, "acme"), "utf8"), '{\n "orgId": "org-a"\n}\n', ); } finally { @@ -118,7 +153,13 @@ test("orgPinCheck makes no request for an org with no folder and no pin", async const root = orgDir({ folder: false }); try { const { probeFetch, seen } = probes({ "/assistant": [{ orgId: "org-a" }] }); - const outcome = await orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch }); + const outcome = await orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch, + }); assert.deepEqual(outcome, { kind: "unpinned" }); assert.deepEqual(seen, []); assert.equal(existsSync(join(root, "resources")), false); @@ -132,7 +173,13 @@ test("orgPinCheck passes a key for the pinned org", async () => { try { const { probeFetch } = probes({ "/assistant": [{ orgId: "org-a" }] }); assert.deepEqual( - await orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch }), + await orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch, + }), { kind: "match" }, ); } finally { @@ -145,12 +192,21 @@ test("orgPinCheck refuses a key for another org, naming both orgs and the source try { const { probeFetch } = probes({ "/assistant": [{ orgId: "org-b" }] }); await assert.rejects( - orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch }), + orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch, + }), (error: Error) => { assert.ok(error instanceof OrgPinMismatchError); assert.match(error.message, /belongs to Vapi org org-b/); assert.match(error.message, /pinned to org org-a/); - assert.match(error.message, /VAPI_PRIVATE_API_KEY_ACME environment variable/); + assert.match( + error.message, + /VAPI_PRIVATE_API_KEY_ACME environment variable/, + ); assert.doesNotMatch(error.message, /test-token-not-used/); return true; }, @@ -164,7 +220,13 @@ test("orgPinCheck refuses a key whose org is empty when the folder is pinned", a const root = orgDir({ folder: true, pin: '{"orgId":"org-a"}' }); try { await assert.rejects( - orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch: probes({}).probeFetch }), + orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch: probes({}).probeFetch, + }), /belongs to an org with no resources/, ); } finally { @@ -177,7 +239,13 @@ test("orgPinCheck can't verify when the probes fail, and says so", async () => { try { const { probeFetch } = probes({ "/assistant": serverError }); assert.deepEqual( - await orgPinCheck({ rootDir: root, org: "acme", connection: CONNECTION, keySource: SOURCE, probeFetch }), + await orgPinCheck({ + rootDir: root, + org: "acme", + connection: CONNECTION, + keySource: SOURCE, + probeFetch, + }), { kind: "unverified" }, ); } finally { @@ -188,7 +256,7 @@ test("orgPinCheck can't verify when the probes fail, and says so", async () => { test("orgPinRead names the file when the pin is corrupt", () => { const root = orgDir({ folder: true, pin: "{not json" }); try { - assert.throws(() => orgPinRead(root, "acme"), /resources\/acme\/\.vapi-org\.json/); + assert.throws(() => orgPinRead(root, "acme"), /state\/acme\/org\.json/); } finally { rmSync(root, { recursive: true, force: true }); } @@ -211,20 +279,36 @@ test("pull stops before listing anything when the key belongs to another org", a cpSync(join(REPO, "package.json"), join(dir, "package.json")); symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir"); mkdirSync(join(dir, "resources", "acme"), { recursive: true }); - writeFileSync(join(dir, "resources", "acme", ORG_PIN_FILE), '{"orgId":"org-a"}\n'); - writeFileSync(join(dir, ".env.acme"), "VAPI_PRIVATE_API_KEY=wrong-org-key\n"); - const env: NodeJS.ProcessEnv = { ...process.env, VAPI_BASE_URL: `http://127.0.0.1:${port}` }; + mkdirSync(join(dir, "state", "acme"), { recursive: true }); + writeFileSync(orgPinFilePath(dir, "acme"), '{"orgId":"org-a"}\n'); + writeFileSync( + join(dir, ".env.acme"), + "VAPI_PRIVATE_API_KEY=wrong-org-key\n", + ); + const env: NodeJS.ProcessEnv = { + ...process.env, + VAPI_BASE_URL: `http://127.0.0.1:${port}`, + }; delete env.VAPI_GITOPS_ORG_PIN; // Async spawn: the stub server runs in this process. - const result = await new Promise<{ code: number | null; output: string }>((resolve) => { - const child = spawn(process.execPath, ["--import", "tsx", "src/pull.ts", "acme"], { cwd: dir, env }); - let output = ""; - child.stdout.on("data", (chunk) => (output += chunk)); - child.stderr.on("data", (chunk) => (output += chunk)); - child.on("close", (code) => resolve({ code, output })); - }); + const result = await new Promise<{ code: number | null; output: string }>( + (resolve) => { + const child = spawn( + process.execPath, + ["--import", "tsx", "src/pull.ts", "acme"], + { cwd: dir, env }, + ); + let output = ""; + child.stdout.on("data", (chunk) => (output += chunk)); + child.stderr.on("data", (chunk) => (output += chunk)); + child.on("close", (code) => resolve({ code, output })); + }, + ); assert.equal(result.code, 1); - assert.match(result.output, /belongs to Vapi org org-b, but resources\/acme\/ is pinned to org org-a/); + assert.match( + result.output, + /belongs to Vapi org org-b, but resources\/acme\/ is pinned to org org-a/, + ); assert.doesNotMatch(result.output, /wrong-org-key/); // Only the probe went out: no listing, no writes. assert.deepEqual(seen, ["/assistant?limit=1"]); diff --git a/tests/path-matching.test.ts b/tests/path-matching.test.ts index 43eed5b..c8c9b1e 100644 --- a/tests/path-matching.test.ts +++ b/tests/path-matching.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/promote-cmd.test.ts b/tests/promote-cmd.test.ts index 40da4fe..ca2c385 100644 --- a/tests/promote-cmd.test.ts +++ b/tests/promote-cmd.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; import { @@ -16,8 +17,9 @@ import test from "node:test"; // file; each test resets it. const ROOT = mkdtempSync(join(tmpdir(), "promote-cmd-")); process.env.VAPI_GITOPS_ROOT = ROOT; -const { APPLIED_PATHS_FILE, promotionCommandRun } = - await import("../src/promote-cmd.ts"); +const { APPLIED_PATHS_FILE, promotionCommandRun } = await import( + "../src/promote-cmd.ts" +); function git(...args: string[]): string { return execFileSync( @@ -40,7 +42,7 @@ function fixtureReset(): void { "version: 1\norgs:\n a: {}\n b: {}\n c: {}\npipelines:\n release:\n orgs: [a, b, c]\n resources: ['**/*']\n", ); write("resources/a/assistants/intake.yml", "name: Intake\n"); - for (const org of ["a", "b", "c"]) write(`.vapi-state.${org}.json`, "{}\n"); + for (const org of ["a", "b", "c"]) write(`state/${org}/state.json`, "{}\n"); write(".gitignore", "tmp/\n.env.*\n"); git("init", "-q", "-b", "main"); git("add", "-A"); diff --git a/tests/promotion-gate.test.ts b/tests/promotion-gate.test.ts index ede1899..64d20fc 100644 --- a/tests/promotion-gate.test.ts +++ b/tests/promotion-gate.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; import { @@ -11,13 +12,13 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import test from "node:test"; import type { CheckDefinition } from "../src/check-config.ts"; +import { promotionConfigParse } from "../src/promotion.ts"; import type { PromotionGateResult } from "../src/promotion-gate.ts"; import { gateBudgetMinutes, gateDeadline, gateResultReduce, } from "../src/promotion-gate.ts"; -import { promotionConfigParse } from "../src/promotion.ts"; // promote-cmd.ts binds its root at import: one fixture repo for the file, // rebuilt per test. @@ -67,7 +68,7 @@ function fixture(args: FixtureArgs): void { if (args.checks !== undefined) write("vapi-checks.yml", `version: 1\nchecks:\n${args.checks}`); for (const org of Object.keys(args.orgs)) - write(`.vapi-state.${org}.json`, "{}\n"); + write(`state/${org}/state.json`, "{}\n"); for (const [path, content] of Object.entries(args.files ?? {})) write(path, content); write(".gitignore", "tmp/\n.env.*\n"); diff --git a/tests/promotion-golden.test.ts b/tests/promotion-golden.test.ts index ef5e824..d94c39e 100644 --- a/tests/promotion-golden.test.ts +++ b/tests/promotion-golden.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdir, diff --git a/tests/promotion-workflow-commit.test.ts b/tests/promotion-workflow-commit.test.ts index 765916d..353b55c 100644 --- a/tests/promotion-workflow-commit.test.ts +++ b/tests/promotion-workflow-commit.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync, spawnSync } from "node:child_process"; import { @@ -12,6 +13,12 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { parse as parseYaml } from "yaml"; +import { migrateAll } from "../src/migrate-hash-store.ts"; +import { + OLD_LAYOUT_NOTICE, + StateLayoutError, + stateLayoutPrepare, +} from "../src/state-paths.ts"; // Runs the promotion workflow's real "Commit reconciled files and UUID // state" step (read from .github/workflows/promotion.yml, run with bash -e) @@ -73,7 +80,14 @@ function repoReset( "promotion.yml", `version: 1\norgs:\n${orgs.map((org) => ` ${org}: {}`).join("\n")}\npipelines:\n${pipelineYaml}\n`, ); - for (const org of orgs) write(`.vapi-state.${org}.json`, "{}\n"); + for (const org of orgs) write(`state/${org}/state.json`, "{}\n"); + // The repository carries the workflow whose commit step runs here: + // `npm run migrate` moves state only under a commit step it can see + // stages state/. + write( + ".github/workflows/promotion.yml", + readFileSync(join(REPO, ".github/workflows/promotion.yml"), "utf8"), + ); write(".gitignore", "tmp/\n.env.*\n"); for (const [path, content] of Object.entries(files)) write(path, content); git(CLONE, "add", "-A"); @@ -83,7 +97,10 @@ function repoReset( // promote --all --apply: every apply writes its org's state (as apply.ts // does), and the `failAt`-th apply (1-based) then fails. -async function promote(failAt?: number): Promise { +async function promote( + failAt?: number, + statePath = (org: string) => `state/${org}/state.json`, +): Promise { let applies = 0; process.env.VAPI_PROMOTION_TOKENS = '{"a":"t","b":"t","c":"t"}'; const log = console.log; @@ -93,7 +110,7 @@ async function promote(failAt?: number): Promise { childRun: (script: string, org: string) => { if (script !== "src/apply.ts") return; write( - `.vapi-state.${org}.json`, + statePath(org), `{"assistants":{"intake":{"uuid":"uuid-${org}"}}}\n`, ); if (++applies === failAt) @@ -149,8 +166,8 @@ test("a failed promotion still pushes state and the files of transitions that ap code: step.code, b: originFile("resources/b/assistants/intake.yml"), c: originFile("resources/c/assistants/intake.yml"), - bState: originFile(".vapi-state.b.json"), - cState: originFile(".vapi-state.c.json"), + bState: originFile("state/b/state.json"), + cState: originFile("state/c/state.json"), }, { failure: "src/apply.ts failed for c", @@ -196,7 +213,7 @@ test("a successful promotion commits every resource change and the state", async failure, step.code, originFile("resources/b/assistants/intake.yml"), - originFile(".vapi-state.b.json"), + originFile("state/b/state.json"), ], [ undefined, @@ -230,4 +247,210 @@ test("a promotion that changed nothing pushes nothing", async () => { ); }); +// ── Repositories that still keep state at the root ─────────────────────── + +const OLD_STATE = (org: string) => `.vapi-state.${org}.json`; + +// The fixture as a repository looked before state/ existed. +function repoResetOldLayout(): void { + repoReset( + ["a", "b"], + { release: ["a", "b"] }, + { "resources/a/assistants/intake.yml": INTAKE("a") }, + ); + for (const org of ["a", "b"]) + git(CLONE, "mv", `state/${org}/state.json`, OLD_STATE(org)); + git(CLONE, "commit", "-qm", "old layout"); + git(CLONE, "push", "-q", "origin", "main"); +} + +test("a repository that has not moved its state still commits the root state file", async () => { + repoResetOldLayout(); + // A CI run writes state in place (tests/state-layout.test.ts). + const failure = await promote(undefined, OLD_STATE); + const step = commitStep("success"); + assert.deepEqual( + [ + failure, + step.code, + originFile(OLD_STATE("b")), + originFile("state/b/state.json"), + originFile("resources/b/assistants/intake.yml"), + ], + [ + undefined, + 0, + '{"assistants":{"intake":{"uuid":"uuid-b"}}}\n', + undefined, + INTAKE("a"), + ], + step.output, + ); +}); + +test("a move is committed whole: the old file's removal and the new file in one commit", async () => { + repoResetOldLayout(); + const base = git(ORIGIN, "rev-parse", "main").trim(); + // `npm run migrate`, then a promotion, committed by the same run. + await migrateAll(CLONE); + const failure = await promote(); + const step = commitStep("success"); + assert.deepEqual( + { + failure, + code: step.code, + commits: git(ORIGIN, "rev-list", "--count", `${base}..main`).trim(), + old: [originFile(OLD_STATE("a")), originFile(OLD_STATE("b"))], + a: originFile("state/a/state.json"), + b: originFile("state/b/state.json"), + }, + { + failure: undefined, + code: 0, + commits: "1", + old: [undefined, undefined], + a: "{}\n", + b: '{"assistants":{"intake":{"uuid":"uuid-b"}}}\n', + }, + step.output, + ); +}); + +test("a failed promotion after a move still commits the move whole", async () => { + repoResetOldLayout(); + await migrateAll(CLONE); + const failure = await promote(1); + const step = commitStep("failure"); + assert.deepEqual( + [ + failure, + step.code, + originFile(OLD_STATE("b")), + originFile("state/b/state.json"), + originFile("state/a/state.json"), + ], + [ + "src/apply.ts failed for b", + 0, + undefined, + '{"assistants":{"intake":{"uuid":"uuid-b"}}}\n', + "{}\n", + ], + step.output, + ); +}); + +// The step as it was before state/ existed. It stages only the root files, +// so on a moved repository it would commit their removal and nothing else. +const OLD_COMMIT_STEP = [ + "set -euo pipefail", + "git add -A -- ':(glob).vapi-state.*.json'", + "git add -A -- resources", + 'git commit -qm "chore: record promoted Vapi state [skip promotion]"', +].join("\n"); + +test("the step from before state/ can't commit a moved repository, so the engine refuses to run under it", async () => { + repoReset( + ["a", "b"], + { release: ["a", "b"] }, + { "resources/a/assistants/intake.yml": INTAKE("a") }, + ); + const head = git(ORIGIN, "rev-parse", "main"); + await promote(); + const old = spawnSync("bash", ["-e", "-c", OLD_COMMIT_STEP], { + cwd: CLONE, + encoding: "utf8", + }); + write( + ".github/workflows/promotion.yml", + `jobs:\n promote:\n steps:\n - run: |\n${OLD_COMMIT_STEP.replace(/^/gm, " ")}\n`, + ); + assert.deepEqual( + [ + // git add fails on a pathspec that matches no file: nothing is + // committed, and the UUIDs this run recorded never reach git. + old.status, + git(ORIGIN, "rev-parse", "main"), + (() => { + try { + stateLayoutPrepare(CLONE, "b", { CI: "true" }); + return "ran"; + } catch (error) { + return error instanceof StateLayoutError ? "stopped" : "other"; + } + })(), + ], + [128, head, "stopped"], + `${old.stdout}${old.stderr}`, + ); +}); + +// A repository whose own commit step stages the old state file through a +// script. The engine can't read that, so it must leave state where that +// script looks for it, on a person's machine and in the run. +const HELPER_COMMIT_STEP = [ + "set -euo pipefail", + "./scripts/stage-state.sh", + "git add -A -- resources", + 'git commit -qm "chore: record promoted Vapi state [skip promotion]"', + "git push -q origin main", +].join("\n"); + +test("under a commit step the engine can't read, state stays at the root and keeps being committed", async () => { + repoResetOldLayout(); + write( + ".github/workflows/promotion.yml", + `jobs:\n promote:\n steps:\n - run: |\n${HELPER_COMMIT_STEP.replace(/^/gm, " ")}\n`, + ); + write( + "scripts/stage-state.sh", + "#!/bin/bash\ngit add -A -- ':(glob).vapi-state.*.json'\n", + ); + spawnSync("chmod", ["+x", join(CLONE, "scripts/stage-state.sh")]); + git(CLONE, "add", "-A"); + git(CLONE, "commit", "-qm", "ci: our own commit step"); + git(CLONE, "push", "-q", "origin", "main"); + // A command on a person's machine, `npm run migrate` without the flag, + // then the run in CI. + const local = ["a", "b"].flatMap((org) => stateLayoutPrepare(CLONE, org, {})); + const migrated = (await migrateAll(CLONE)).orgs.flatMap((org) => org.moved); + const run = ["a", "b"].flatMap((org) => + stateLayoutPrepare(CLONE, org, { CI: "true" }), + ); + const failure = await promote(undefined, OLD_STATE); + const step = spawnSync( + "bash", + [ + "-e", + "-c", + `git config user.name t && git config user.email t@example.com\n${HELPER_COMMIT_STEP}`, + ], + { cwd: CLONE, encoding: "utf8" }, + ); + assert.deepEqual( + { + held: [...local, ...run].every((line) => line === OLD_LAYOUT_NOTICE), + notices: [local.length, run.length], + migrated, + failure, + code: step.status, + b: originFile(OLD_STATE("b")), + folder: originFile("state/b/state.json"), + // Nothing the run wrote is left uncommitted. + leftovers: git(CLONE, "status", "--porcelain"), + }, + { + held: true, + notices: [2, 2], + migrated: [], + failure: undefined, + code: 0, + b: '{"assistants":{"intake":{"uuid":"uuid-b"}}}\n', + folder: undefined, + leftovers: "", + }, + `${step.stdout}${step.stderr}`, + ); +}); + test.after(() => rmSync(WORK, { recursive: true, force: true })); diff --git a/tests/promotion.test.ts b/tests/promotion.test.ts index 615efbb..6fc041f 100644 --- a/tests/promotion.test.ts +++ b/tests/promotion.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; @@ -410,12 +411,12 @@ test("promote CLI dry run uses the reviewed config without writing target files" await put(fx.root, "promotion.yml", configText); await put( fx.root, - ".vapi-state.source.json", + "state/source/state.json", `${JSON.stringify(state(), null, 2)}\n`, ); await put( fx.root, - ".vapi-state.target.json", + "state/target/state.json", `${JSON.stringify(state(), null, 2)}\n`, ); await put(fx.root, "resources/source/tools/t.yml", "type: function\n"); @@ -462,6 +463,10 @@ test("promotionConfigParse reads an org's optional check gate and rejects a non- const parsed = promotionConfigParse(config("dev-core")); assert.deepEqual( [parsed.orgs.dev?.check, parsed.orgs.prod?.check, error], - ["dev-core", undefined, "org dev.check must be a check name from vapi-checks.yml"], + [ + "dev-core", + undefined, + "org dev.check must be a check name from vapi-checks.yml", + ], ); }); diff --git a/tests/pull-rename-preserves-filename.test.ts b/tests/pull-rename-preserves-filename.test.ts index 7405380..fe4b6e7 100644 --- a/tests/pull-rename-preserves-filename.test.ts +++ b/tests/pull-rename-preserves-filename.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -16,6 +17,7 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { Worker } from "node:worker_threads"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // ───────────────────────────────────────────────────────────────────────────── // Regression test: a dashboard RENAME of an already-tracked resource must NOT @@ -136,12 +138,12 @@ test("pull: dashboard rename of tracked resource preserves the local filename (n // The drift baseline lives in the hash store, not the state file. The // engine runs from the copied src/, so its store resolves under `dir`. - const hashStore = join(dir, ".vapi-state-hash", ENV); + const hashStore = baselinesDir(dir, ENV); mkdirSync(hashStore, { recursive: true }); writeFileSync(join(hashStore, UUID_X), "stale-hash-X\n"); writeFileSync( - join(dir, `.vapi-state.${ENV}.json`), + stateFixturePath(dir, ENV), JSON.stringify( { credentials: {}, @@ -230,7 +232,7 @@ test("pull: dashboard rename of tracked resource preserves the local filename (n // State must remain keyed by the original slug → X. const finalState = JSON.parse( - readFileSync(join(dir, `.vapi-state.${ENV}.json`), "utf-8"), + readFileSync(stateFixturePath(dir, ENV), "utf-8"), ); assert.equal( finalState.assistants[TRACKED_SLUG]?.uuid, diff --git a/tests/pull-same-name-clobber.test.ts b/tests/pull-same-name-clobber.test.ts index a6bb7c5..4514eba 100644 --- a/tests/pull-same-name-clobber.test.ts +++ b/tests/pull-same-name-clobber.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -18,6 +19,7 @@ import { fileURLToPath } from "node:url"; import { Worker } from "node:worker_threads"; import { parseResourceDataFromFile } from "../src/resource-parse.ts"; import { hashPayload } from "../src/state-serialize.ts"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // ───────────────────────────────────────────────────────────────────────────── // Integration test for the state-aware adoption fix in pull.ts. @@ -167,12 +169,12 @@ async function runClobberScenario( // Seed state: slug `riley` already maps to UUID A. // The drift baseline lives in the hash store, not the state file. The // engine runs from the copied src/, so its store resolves under `dir`. - const hashStore = join(dir, ".vapi-state-hash", ENV); + const hashStore = baselinesDir(dir, ENV); mkdirSync(hashStore, { recursive: true }); writeFileSync(join(hashStore, UUID_A), "stale-hash-A\n"); writeFileSync( - join(dir, `.vapi-state.${ENV}.json`), + stateFixturePath(dir, ENV), JSON.stringify( { credentials: {}, @@ -295,7 +297,7 @@ async function runClobberScenario( // ── State assertions ───────────────────────────────────────────────── const finalState = JSON.parse( - readFileSync(join(dir, `.vapi-state.${ENV}.json`), "utf-8"), + readFileSync(stateFixturePath(dir, ENV), "utf-8"), ); assert.equal( finalState.assistants.riley?.uuid, diff --git a/tests/push-dry-run.test.ts b/tests/push-dry-run.test.ts index 408fd0e..a9872e4 100644 --- a/tests/push-dry-run.test.ts +++ b/tests/push-dry-run.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -13,6 +14,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; +import { stateFilePath } from "../src/state-paths.ts"; // Stack C — push --dry-run regression coverage. // @@ -100,9 +102,9 @@ test("--dry-run prints the dry-run banner so the operator sees it", () => { test("--dry-run does NOT write the state file", () => { const fx = setupFixture(); try { - const stateFilePath = join(fx.dir, ".vapi-state.test-dry-run.json"); + const statePath = stateFilePath(fx.dir, "test-dry-run"); assert.equal( - existsSync(stateFilePath), + existsSync(statePath), false, "precondition: state file should not exist before run", ); @@ -112,7 +114,7 @@ test("--dry-run does NOT write the state file", () => { // would normally write the state file with refreshed credentials/UUIDs; // in dry-run we want zero filesystem mutation. assert.equal( - existsSync(stateFilePath), + existsSync(statePath), false, `state file must not be created in dry-run; stdout=${res.stdout}`, ); diff --git a/tests/push-preflight.test.ts b/tests/push-preflight.test.ts index 63991f4..a77769c 100644 --- a/tests/push-preflight.test.ts +++ b/tests/push-preflight.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; import { diff --git a/tests/push-stale-baseline-noop.test.ts b/tests/push-stale-baseline-noop.test.ts index 882ce3d..c828d36 100644 --- a/tests/push-stale-baseline-noop.test.ts +++ b/tests/push-stale-baseline-noop.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -13,6 +14,7 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { Worker } from "node:worker_threads"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // ───────────────────────────────────────────────────────────────────────────── // Regression: a STALE `lastPulledHash` (written in an older hash basis) must @@ -119,7 +121,11 @@ test("push: stale lastPulledHash does not block when local and dashboard agree", cpSync(join(REPO_ROOT, "src"), join(dir, "src"), { recursive: true }); cpSync(join(REPO_ROOT, "package.json"), join(dir, "package.json")); - symlinkSync(join(REPO_ROOT, "node_modules"), join(dir, "node_modules"), "dir"); + symlinkSync( + join(REPO_ROOT, "node_modules"), + join(dir, "node_modules"), + "dir", + ); const assistantsDir = join(dir, "resources", ENV, "assistants"); mkdirSync(assistantsDir, { recursive: true }); @@ -129,12 +135,12 @@ test("push: stale lastPulledHash does not block when local and dashboard agree", // engine runs from the copied src/, so its store resolves under `dir`. // It is deliberately stale: it equals neither the local file's hash nor // the canonicalized dashboard hash. - const hashStore = join(dir, ".vapi-state-hash", ENV); + const hashStore = baselinesDir(dir, ENV); mkdirSync(hashStore, { recursive: true }); writeFileSync(join(hashStore, UUID), "stale-older-basis-hash\n"); writeFileSync( - join(dir, `.vapi-state.${ENV}.json`), + stateFixturePath(dir, ENV), JSON.stringify( { // A non-empty credentials section keeps push from treating state as @@ -160,16 +166,26 @@ test("push: stale lastPulledHash does not block when local and dashboard agree", // Route order matters: the by-id GET must match before the list GET. const { worker, port } = await startStub([ - { method: "GET", pathStartsWith: `/assistant/${UUID}`, body: dashboardBody() }, - { method: "PATCH", pathStartsWith: `/assistant/${UUID}`, body: dashboardBody() }, + { + method: "GET", + pathStartsWith: `/assistant/${UUID}`, + body: dashboardBody(), + }, + { + method: "PATCH", + pathStartsWith: `/assistant/${UUID}`, + body: dashboardBody(), + }, { method: "GET", pathStartsWith: "/assistant", body: [dashboardBody()] }, ]); writeFileSync( join(dir, `.env.${ENV}`), - ["VAPI_TOKEN=fake-token-not-used", `VAPI_BASE_URL=http://127.0.0.1:${port}`, ""].join( - "\n", - ), + [ + "VAPI_TOKEN=fake-token-not-used", + `VAPI_BASE_URL=http://127.0.0.1:${port}`, + "", + ].join("\n"), ); try { @@ -195,11 +211,7 @@ test("push: stale lastPulledHash does not block when local and dashboard agree", ); const out = `${res.stdout}\n${res.stderr}`; - assert.equal( - res.status, - 0, - `push must exit 0 (no phantom block)\n${out}`, - ); + assert.equal(res.status, 0, `push must exit 0 (no phantom block)\n${out}`); assert.doesNotMatch( out, /Bootstrap state sync required/, diff --git a/tests/reconcile-state-key.test.ts b/tests/reconcile-state-key.test.ts index 1141e96..bde79f7 100644 --- a/tests/reconcile-state-key.test.ts +++ b/tests/reconcile-state-key.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/repository/engine-beside-a-test-runner.test.ts b/tests/repository/engine-beside-a-test-runner.test.ts new file mode 100644 index 0000000..7fc2144 --- /dev/null +++ b/tests/repository/engine-beside-a-test-runner.test.ts @@ -0,0 +1,177 @@ +import "../engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + cpSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// A repository that doesn't use the engine's test sandbox has to behave as +// it did before the sandbox existed. Two things once did not. +// +// 1. The engine refused to start when NODE_TEST_CONTEXT was in its +// environment and no sandbox was. Node's test runner sets +// NODE_TEST_CONTEXT for every process it starts, so an engine command +// started from a repository's own test exited 1. +// +// 2. The preload npm test adds, tests/no-vapi-api.ts, pointed the engine at +// an empty temporary directory and made node:fs refuse every write inside +// the repository, for every test file. A repository's own test under +// tests/ that ran the engine on that repository, or wrote a file into it, +// failed: the engine it started found no resources and no key. +// +// The sandbox is now a module the engine's own tests import +// (tests/engine-sandbox.ts), and the engine never looks at what a test +// runner leaves in the environment. +// +// Each case works in a throwaway copy in a folder of its own. + +const REPO = fileURLToPath(new URL("../..", import.meta.url)); + +function put(root: string, path: string, content: string): void { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); +} + +// A small repository of a customer's: one org, one assistant, its state file +// and its key file, with the engine and its test preload as shipped. +function customerRepository(): { root: string; drop: () => void } { + const box = mkdtempSync(join(tmpdir(), "own-tests-")); + const root = join(box, "repo"); + mkdirSync(join(root, "tests"), { recursive: true }); + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + cpSync( + join(REPO, "tests", "no-vapi-api.ts"), + join(root, "tests", "no-vapi-api.ts"), + ); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + put( + root, + "resources/dev/assistants/riley.md", + "---\nname: Riley\nmodel:\n provider: openai\n model: gpt-4o\n---\n\nAnswer the phone.\n", + ); + put( + root, + ".vapi-state.dev.json", + JSON.stringify( + { + assistants: { riley: { uuid: "11111111-1111-4111-8111-111111111111" } }, + }, + null, + 2, + ) + "\n", + ); + put(root, ".env.dev", "VAPI_PRIVATE_API_KEY=not-a-real-key\n"); + return { root, drop: () => rmSync(box, { recursive: true, force: true }) }; +} + +// The environment of a shell that is not this test process: none of what the +// test runner and the preload put into ours. +function shellEnv(extra: Record = {}): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + delete env.VAPI_GITOPS_TEST_ROOT; + delete env.VAPI_GITOPS_TEST_REPO; + delete env.CI; + delete env.GITHUB_ACTIONS; + return { ...env, ...extra }; +} + +function validate(env: NodeJS.ProcessEnv): { + exit: number | null; + passed: boolean; +} { + const repository = customerRepository(); + try { + const run = spawnSync( + process.execPath, + ["--import", "tsx", "src/validate-cmd.ts", "dev"], + { cwd: repository.root, encoding: "utf8", env }, + ); + return { + exit: run.status, + passed: /Validation passed/.test(run.stdout + run.stderr), + }; + } finally { + repository.drop(); + } +} + +// Run one test file of the customer's own the way npm test runs it. +function ownTest(body: string): { exit: number | null; ran: boolean } { + const repository = customerRepository(); + try { + put(repository.root, "tests/our-own.test.ts", body); + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + "tests/our-own.test.ts", + ], + { cwd: repository.root, encoding: "utf8", env: shellEnv() }, + ); + return { exit: run.status, ran: /^# pass 1$/m.test(run.stdout) }; + } finally { + repository.drop(); + } +} + +const OWN_HEAD = + 'import assert from "node:assert/strict";\n' + + 'import { spawnSync } from "node:child_process";\n' + + 'import { mkdirSync, writeFileSync } from "node:fs";\n' + + 'import { join } from "node:path";\n' + + 'import test from "node:test";\n' + + 'import { fileURLToPath } from "node:url";\n' + + 'const REPO = fileURLToPath(new URL("..", import.meta.url));\n'; + +test("control: validate runs in a plain shell", () => { + assert.deepEqual(validate(shellEnv()), { exit: 0, passed: true }); +}); + +test("an engine command runs as on main when NODE_TEST_CONTEXT is in its environment", () => { + assert.deepEqual(validate(shellEnv({ NODE_TEST_CONTEXT: "child-v8" })), { + exit: 0, + passed: true, + }); +}); + +test("a customer's own test that runs validate on its repository passes as on main", () => { + assert.deepEqual( + ownTest( + OWN_HEAD + + 'test("our dev org validates", () => {\n' + + ' const run = spawnSync(process.execPath, ["--import", "tsx", "src/validate-cmd.ts", "dev"], { cwd: REPO, encoding: "utf8" });\n' + + " assert.equal(run.status, 0, run.stdout + run.stderr);\n" + + " assert.match(run.stdout, /Validation passed/);\n" + + "});\n", + ), + { exit: 0, ran: true }, + ); +}); + +test("a customer's own test that writes a report into its repository passes as on main", () => { + assert.deepEqual( + ownTest( + OWN_HEAD + + 'test("we keep a report of the run", () => {\n' + + ' mkdirSync(join(REPO, "tmp"), { recursive: true });\n' + + ' writeFileSync(join(REPO, "tmp/our-test-report.json"), "{}\\n");\n' + + "});\n", + ), + { exit: 0, ran: true }, + ); +}); diff --git a/tests/repository/import-check.test.ts b/tests/repository/import-check.test.ts new file mode 100644 index 0000000..1ba1c42 --- /dev/null +++ b/tests/repository/import-check.test.ts @@ -0,0 +1,130 @@ +import "../engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawnSync } from "node:child_process"; +import { + cpSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// tests/engine-sandbox.test.ts fails when a test file doesn't import the +// sandbox first, in CI for the engine's own repository and nowhere else: +// anywhere else such a file is that repository's own test. That includes a +// person's clone of the engine's repository, which keeps its origin and may +// hold a test of its owner's. Each case below asks that check in a small +// repository that holds one test file without the import, named each way a +// repository can be. + +const REPO = fileURLToPath(new URL("../..", import.meta.url)); + +const GIT_ENV = { + ...process.env, + GIT_CONFIG_GLOBAL: "/dev/null", + GIT_CONFIG_NOSYSTEM: "1", + GIT_AUTHOR_NAME: "t", + GIT_AUTHOR_EMAIL: "t@example.invalid", + GIT_COMMITTER_NAME: "t", + GIT_COMMITTER_EMAIL: "t@example.invalid", +}; +const git = (cwd: string, ...args: string[]): string => + execFileSync("git", args, { cwd, env: GIT_ENV, encoding: "utf8" }); + +function importCheckIn(named: { runner?: string; origin?: string }): string { + const root = mkdtempSync(join(tmpdir(), "import-check-")); + try { + mkdirSync(join(root, "tests")); + for (const file of [ + "engine-sandbox.test.ts", + "engine-sandbox.ts", + "engine-tests.ts", + ]) + cpSync(join(REPO, "tests", file), join(root, "tests", file)); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + writeFileSync( + join(root, "tests/own.test.ts"), + 'import test from "node:test";\n\ntest("own", () => {});\n', + ); + git(root, "init", "-q", "-b", "main"); + if (named.origin) git(root, "remote", "add", "origin", named.origin); + const env: NodeJS.ProcessEnv = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + delete env.GITHUB_REPOSITORY; + if (named.runner) env.GITHUB_REPOSITORY = named.runner; + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--test", + "--test-name-pattern", + "every test file imports the sandbox first", + "tests/engine-sandbox.test.ts", + ], + { cwd: root, env, encoding: "utf8" }, + ); + if (/^# skipped 1$/m.test(run.stdout)) return "not asked"; + if (run.status === 0) return "passed"; + return /own\.test\.ts/.test(run.stdout) + ? "own.test.ts lacks the import" + : run.stdout + run.stderr; + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +test("the import check is asked in CI for the engine's own repository, and nowhere else", () => { + const fork = "acme/voice-agents"; + assert.deepEqual( + { + "a runner in the engine's repository": importCheckIn({ + runner: "VapiAI/gitops", + origin: "https://github.com/VapiAI/gitops", + }), + "a runner in the engine's repository, named in lower case": importCheckIn( + { runner: "vapiai/gitops", origin: "https://github.com/vapiai/gitops" }, + ), + "a clone of the engine's repository over https": importCheckIn({ + origin: "https://github.com/VapiAI/gitops.git", + }), + "a clone of the engine's repository over ssh": importCheckIn({ + origin: "git@github.com:VapiAI/gitops.git", + }), + "a runner in a fork": importCheckIn({ + runner: fork, + origin: `https://github.com/${fork}`, + }), + "a runner in a repository that kept the engine's origin": importCheckIn({ + runner: fork, + origin: "https://github.com/VapiAI/gitops.git", + }), + "a runner in a fork that kept the name": importCheckIn({ + runner: "acme/gitops", + origin: "https://github.com/acme/gitops.git", + }), + "a clone of a fork": importCheckIn({ + origin: `git@github.com:${fork}.git`, + }), + "a repository with no origin": importCheckIn({}), + }, + { + "a runner in the engine's repository": "own.test.ts lacks the import", + "a runner in the engine's repository, named in lower case": + "own.test.ts lacks the import", + "a clone of the engine's repository over https": "not asked", + "a clone of the engine's repository over ssh": "not asked", + "a runner in a fork": "not asked", + "a runner in a repository that kept the engine's origin": "not asked", + "a runner in a fork that kept the name": "not asked", + "a clone of a fork": "not asked", + "a repository with no origin": "not asked", + }, + ); +}); diff --git a/tests/repository/own-tests-as-before.test.ts b/tests/repository/own-tests-as-before.test.ts new file mode 100644 index 0000000..2fc6f78 --- /dev/null +++ b/tests/repository/own-tests-as-before.test.ts @@ -0,0 +1,108 @@ +import "../engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// A repository built from this one can hold tests of its own under tests/, +// and `npm test` runs them with the engine's. Such a test is not sandboxed: +// it doesn't import tests/engine-sandbox.ts, so the engine it starts or +// imports works in the repository, and it can write where it likes, exactly +// as before the sandbox existed. +// +// The case below is such a repository and such a test, run the way +// `npm test` runs it. The test runner leaves NODE_TEST_CONTEXT in the +// environment of the test and of every command the test starts, and the +// engine must not care. + +const REPO = join(dirname(fileURLToPath(import.meta.url)), "..", ".."); + +const OWN_TEST = `import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; +import test from "node:test"; +import { baseDir } from "../src/base-dir.ts"; + +test("an engine command started from here validates this repository's org", () => { + const run = spawnSync("npm", ["run", "validate", "--", "dev"], { + encoding: "utf8", + }); + assert.equal(run.status, 0, run.stdout + run.stderr); + assert.match(run.stdout, /Validation passed/); +}); + +test("a report can be written into the repository", () => { + mkdirSync("tmp", { recursive: true }); + writeFileSync("tmp/own-report.json", '{"ok":true}\\n'); + assert.equal(readFileSync("tmp/own-report.json", "utf8"), '{"ok":true}\\n'); +}); + +test("an engine module imported here works in this repository", () => { + assert.equal(realpathSync(baseDir()), realpathSync(process.cwd())); +}); +`; + +test("a repository's own test runs as it did before the sandbox: its engine commands, its files, its imports", () => { + const root = mkdtempSync(join(tmpdir(), "own-tests-")); + try { + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + mkdirSync(join(root, "tests")); + for (const name of ["no-vapi-api.ts", "engine-sandbox.ts"]) + cpSync(join(REPO, "tests", name), join(root, "tests", name)); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + mkdirSync(join(root, "resources/dev/assistants"), { recursive: true }); + writeFileSync( + join(root, "resources/dev/assistants/riley.md"), + "---\nname: Riley\nmodel:\n provider: openai\n model: gpt-4o\n---\n\nYou are Riley.\n", + ); + // validate needs a key to be configured, and sends nothing. + writeFileSync( + join(root, ".env.dev"), + "VAPI_PRIVATE_API_KEY=not-a-real-key\n", + ); + writeFileSync(join(root, "tests/own-flows.test.ts"), OWN_TEST); + + // As `npm test` starts it in that repository. Nothing of this test's own + // sandbox goes along, and the runner inside sets NODE_TEST_CONTEXT again. + const env: NodeJS.ProcessEnv = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + delete env.VAPI_GITOPS_TEST_ROOT; + delete env.VAPI_GITOPS_TEST_REPO; + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + "tests/own-flows.test.ts", + ], + { cwd: root, env, encoding: "utf8", timeout: 120_000 }, + ); + assert.deepEqual( + { + exit: run.status, + pass: /^# pass (\d+)/m.exec(run.stdout)?.[1], + fail: /^# fail (\d+)/m.exec(run.stdout)?.[1], + report: existsSync(join(root, "tmp/own-report.json")), + }, + { exit: 0, pass: "3", fail: "0", report: true }, + run.stdout + run.stderr, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/tests/repository/suite-keeps-the-repository.test.ts b/tests/repository/suite-keeps-the-repository.test.ts new file mode 100644 index 0000000..5a21e85 --- /dev/null +++ b/tests/repository/suite-keeps-the-repository.test.ts @@ -0,0 +1,116 @@ +import "../engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + readdirSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// A test's cleanup once removed the repository it ran in. tests/drift.test.ts +// and tests/tool-assistant-cycle.test.ts cleaned up with +// +// rmSync(dirname(dirname(hashStoreDir(env))), { recursive: true, force: true }) +// +// which assumed hashStoreDir was state//local/baselines. With any +// .vapi-state..json at the root, hashStoreDir is .vapi-state-hash/, +// and two folders up from that is the repository root: src/, resources/, +// .git and every .env file. The run still reported every test as passed. +// +// Each case below runs one of those test files inside a throwaway copy, in a +// folder of its own, so nothing outside the copy can be removed, and compares +// every path in the copy before and after. +// suite-leaves-the-repository.test.ts, beside this file, does the same with +// the whole suite and compares every file's content. + +const REPO = fileURLToPath(new URL("../..", import.meta.url)); + +function paths(root: string): string[] { + return (readdirSync(root, { recursive: true }) as string[]) + .filter((p) => !p.startsWith("node_modules")) + .sort(); +} + +function fileLeavesRepository( + file: string, + stateFiles: Record, +): { exit: number | null; ran: boolean; kept: boolean; same: boolean } { + const box = mkdtempSync(join(tmpdir(), "suite-keeps-repo-")); + const root = join(box, "repo"); + try { + mkdirSync(root, { recursive: true }); + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "tests"), join(root, "tests"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + for (const [path, content] of Object.entries(stateFiles)) { + mkdirSync(join(root, path, ".."), { recursive: true }); + writeFileSync(join(root, path), content); + } + writeFileSync(join(root, ".env.acme"), "VAPI_PRIVATE_API_KEY=not-a-key\n"); + const before = paths(root); + // A test runner started from inside another one runs nothing unless this + // is cleared, and the case would pass without having run. The two names + // this file's sandbox set are cleared too, so the copy's test sets its own. + const env = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + delete env.VAPI_GITOPS_TEST_ROOT; + delete env.VAPI_GITOPS_TEST_REPO; + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + "tests/" + file, + ], + { cwd: root, encoding: "utf8", env }, + ); + const kept = + existsSync(join(root, "package.json")) && existsSync(join(root, "src")); + return { + exit: run.status, + ran: /^# pass [1-9]/m.test(run.stdout), + kept, + same: kept && JSON.stringify(paths(root)) === JSON.stringify(before), + }; + } finally { + rmSync(box, { recursive: true, force: true }); + } +} + +const STATE = '{\n "assistants": {}\n}\n'; +const LAYOUTS: Record> = { + "no state at all": {}, + "state in state/acme/": { "state/acme/state.json": STATE }, + "state at the root (.vapi-state.acme.json)": { + ".vapi-state.acme.json": STATE, + }, +}; +const GOOD = { exit: 0, ran: true, kept: true, same: true }; + +for (const file of ["drift.test.ts", "tool-assistant-cycle.test.ts"]) + test( + file + + " leaves every file of the repository it runs in, wherever its state is", + () => { + const seen: Record = {}; + const want: Record = {}; + for (const [name, files] of Object.entries(LAYOUTS)) { + seen[name] = fileLeavesRepository(file, files); + want[name] = GOOD; + } + assert.deepEqual(seen, want); + }, + ); diff --git a/tests/repository/suite-leaves-the-repository.test.ts b/tests/repository/suite-leaves-the-repository.test.ts new file mode 100644 index 0000000..3369b27 --- /dev/null +++ b/tests/repository/suite-leaves-the-repository.test.ts @@ -0,0 +1,228 @@ +import "../engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawn } from "node:child_process"; +import { createHash } from "node:crypto"; +import { + cpSync, + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { availableParallelism, tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { testFiles } from "../engine-tests.ts"; + +// Running the test suite must not change the repository it runs in: not a +// tracked file, not an untracked one, not an ignored one, not .git. +// +// Each case below builds a repository shaped like a customer's (resources, a +// gitignored .env file with a key in it, a test of their own, engine state, +// this machine's baselines and snapshots, a commit), runs the engine's whole +// suite inside it, and compares every file and folder before and after. The +// three cases are the three places engine state can be: the layout from +// before state/, state/, and nowhere yet. +// +// The copies live in temporary directories of their own, so a suite that did +// remove its repository would remove a copy. +// +// This file is not part of `npm test`. It runs the suite three more times, +// which is slow, and a suite inside a suite reaches the time limits some +// tests give a command sooner. `npm run test:repository` runs it, by itself, +// and so does a CI job in the engine's own repository. + +const REPO = join(dirname(fileURLToPath(import.meta.url)), "..", ".."); + +const UUID = "11111111-1111-4111-8111-111111111111"; +const STATE = `${JSON.stringify({ assistants: { riley: { uuid: UUID } } }, null, 2)}\n`; +const PIN = `${JSON.stringify({ orgId: "org-acme" }, null, 2)}\n`; + +const CUSTOMER: Record = { + "resources/acme/assistants/riley.md": + "---\nname: Riley\nmodel:\n provider: openai\n model: gpt-4o\n---\n\nYou are Riley.\n", + "resources/acme/.vapi-ignore": "assistants/scratch-*\n", + // Gitignored, and the one file here a person can't get back from git. + ".env.acme": "VAPI_PRIVATE_API_KEY=not-a-real-key\n", + // A test of the customer's own. It is not the engine's, so the run below + // leaves it out; if it ran, the report it writes would show up as a change. + "tests/own-report.test.ts": + 'import { mkdirSync, writeFileSync } from "node:fs";\nimport test from "node:test";\n\ntest("writes a report", () => {\n mkdirSync("tmp", { recursive: true });\n writeFileSync("tmp/own-report.json", "{}\\n");\n});\n', +}; + +const LAYOUTS: Record> = { + "state in the layout from before state/": { + ".vapi-state.acme.json": STATE, + "resources/acme/.vapi-org.json": PIN, + [`.vapi-state-hash/acme/${UUID}`]: "0123456789abcdef\n", + ".vapi-state.acme.snapshots/2026-01-01T00-00-00-000Z/riley.json": "{}\n", + }, + "state in state/": { + "state/acme/state.json": STATE, + "state/acme/org.json": PIN, + [`state/acme/local/baselines/${UUID}`]: "0123456789abcdef\n", + "state/acme/local/snapshots/2026-01-01T00-00-00-000Z/riley.json": "{}\n", + }, + "no state at all": {}, +}; + +const GIT_ENV = { + ...process.env, + GIT_CONFIG_GLOBAL: "/dev/null", + GIT_CONFIG_NOSYSTEM: "1", + GIT_AUTHOR_NAME: "t", + GIT_AUTHOR_EMAIL: "t@example.invalid", + GIT_COMMITTER_NAME: "t", + GIT_COMMITTER_EMAIL: "t@example.invalid", +}; +const git = (cwd: string, ...args: string[]): string => + execFileSync("git", args, { cwd, env: GIT_ENV, encoding: "utf8" }); + +// What the suite needs from this repository: every file git doesn't ignore. +// Outside a git checkout, everything but dependencies and env files. +function engineFiles(): string[] { + try { + return git( + REPO, + "ls-files", + "-z", + "--cached", + "--others", + "--exclude-standard", + ) + .split("\0") + .filter( + (path) => + // node_modules can be a link, which an ignore rule for the folder + // doesn't match. A tracked file can be missing from the checkout. + !/^node_modules(\/|$)/.test(path) && + (lstatSync(join(REPO, path), { throwIfNoEntry: false })?.isFile() ?? + false), + ); + } catch { + return readdirSync(REPO, { recursive: true, encoding: "utf8" }).filter( + (path) => + !/^(node_modules|\.git)(\/|$)/.test(path) && + !/(^|\/)\.env/.test(path) && + lstatSync(join(REPO, path)).isFile(), + ); + } +} + +// Every file's content and every folder's existence under root, .git and +// ignored files included. node_modules is a link to this repository's own. +function tree(root: string): Map { + const seen = new Map(); + const walk = (dir: string) => { + for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) { + const path = join(dir, entry.name); + if (path === "node_modules") continue; + if (entry.isDirectory()) { + seen.set(`${path}/`, "folder"); + walk(path); + } else + seen.set( + path, + createHash("sha256") + .update(readFileSync(join(root, path))) + .digest("hex"), + ); + } + }; + walk(""); + return seen; +} + +function changes(before: Map, after: Map) { + const out: string[] = []; + for (const [path, hash] of before) + if (!after.has(path)) out.push(`removed ${path}`); + else if (after.get(path) !== hash) out.push(`changed ${path}`); + for (const path of after.keys()) + if (!before.has(path)) out.push(`added ${path}`); + return out.sort(); +} + +async function suiteRunIn(state: Record) { + const box = mkdtempSync(join(tmpdir(), "suite-in-a-copy-")); + const root = join(box, "repo"); + try { + for (const path of engineFiles()) { + mkdirSync(dirname(join(root, path)), { recursive: true }); + cpSync(join(REPO, path), join(root, path)); + } + for (const [path, content] of Object.entries({ ...CUSTOMER, ...state })) { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); + } + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + git(root, "init", "-q", "-b", "main"); + git(root, "add", "-A"); + git(root, "commit", "-q", "-m", "a customer's repository"); + + const before = tree(root); + // A test runner started from inside another one runs nothing unless + // NODE_TEST_CONTEXT is cleared. + const env: NodeJS.ProcessEnv = { + ...process.env, + // The copy is a customer's repository, on a runner too. + GITHUB_REPOSITORY: "acme/voice-agents", + }; + delete env.NODE_TEST_CONTEXT; + const files = testFiles(join(root, "tests")).engine.map( + (name) => `tests/${name}`, + ); + const child = spawn( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + // Half the cores: the copy's suite is not the only thing running, + // and its tests give a command twenty seconds to answer. + `--test-concurrency=${Math.max(1, Math.floor(availableParallelism() / 2))}`, + ...files, + ], + { cwd: root, env, stdio: ["ignore", "pipe", "pipe"] }, + ); + let out = ""; + child.stdout.on("data", (chunk) => (out += String(chunk))); + child.stderr.on("data", (chunk) => (out += String(chunk))); + const exit = await new Promise((done) => + child.on("close", done), + ); + return { + exit, + // The copy's suite ran this many test files' worth of tests and none failed. + passed: Number(/^# pass (\d+)/m.exec(out)?.[1] ?? 0) > 100, + failed: [...out.matchAll(/^not ok \d+ - (.*)$/gm)].map((m) => m[1]), + changes: changes(before, tree(root)), + }; + } finally { + rmSync(box, { recursive: true, force: true }); + } +} + +test("the whole suite, run inside a customer's repository, leaves every file as it was", async () => { + const names = Object.keys(LAYOUTS); + // One copy at a time. Three suites at once starve the tests that give a + // CLI twenty seconds to answer. + const results: Awaited>[] = []; + for (const name of names) results.push(await suiteRunIn(LAYOUTS[name]!)); + assert.deepEqual( + Object.fromEntries(names.map((name, i) => [name, results[i]])), + Object.fromEntries( + names.map((name) => [ + name, + { exit: 0, passed: true, failed: [], changes: [] }, + ]), + ), + ); +}); diff --git a/tests/resource-parse.test.ts b/tests/resource-parse.test.ts index 05af45d..2905c8f 100644 --- a/tests/resource-parse.test.ts +++ b/tests/resource-parse.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; diff --git a/tests/resource-type-args.test.ts b/tests/resource-type-args.test.ts index df40eda..09b5456 100644 --- a/tests/resource-type-args.test.ts +++ b/tests/resource-type-args.test.ts @@ -1,9 +1,7 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; -import { - resolveResourceTypes, - typeArgFor, -} from "../src/resource-type-args.ts"; +import { resolveResourceTypes, typeArgFor } from "../src/resource-type-args.ts"; import { VALID_RESOURCE_TYPES } from "../src/types.ts"; // The setup wizard downloads what you pick one type at a time, with diff --git a/tests/setup-noninteractive.test.ts b/tests/setup-noninteractive.test.ts index 3f8c88c..6034483 100644 --- a/tests/setup-noninteractive.test.ts +++ b/tests/setup-noninteractive.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -93,7 +94,10 @@ test("readEnvValue handles quotes, export, comments, and missing keys", () => { "OTHER=1", ].join("\n"); assert.equal(readEnvValue(content, "VAPI_TOKEN"), "abc-123"); - assert.equal(readEnvValue(content, "VAPI_BASE_URL"), "https://api.eu.vapi.ai"); + assert.equal( + readEnvValue(content, "VAPI_BASE_URL"), + "https://api.eu.vapi.ai", + ); assert.equal(readEnvValue(content, "MISSING"), undefined); assert.equal(readEnvValue("VAPI_TOKEN=\n", "VAPI_TOKEN"), undefined); }); @@ -109,25 +113,37 @@ function sandbox(): { dir: string; cleanup: () => void } { const dir = mkdtempSync(join(tmpdir(), "vapi-setup-test-")); cpSync(join(REPO_ROOT, "src"), join(dir, "src"), { recursive: true }); cpSync(join(REPO_ROOT, "package.json"), join(dir, "package.json")); - symlinkSync(join(REPO_ROOT, "node_modules"), join(dir, "node_modules"), "dir"); + symlinkSync( + join(REPO_ROOT, "node_modules"), + join(dir, "node_modules"), + "dir", + ); return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) }; } -function runSetup(cwd: string, args: string[], env: Record = {}) { +function runSetup( + cwd: string, + args: string[], + env: Record = {}, +) { const baseEnv = { ...process.env }; delete baseEnv.VAPI_TOKEN; delete baseEnv.VAPI_PRIVATE_API_KEY; delete baseEnv.VAPI_BASE_URL; for (const name of Object.keys(baseEnv)) if (name.startsWith("VAPI_PRIVATE_API_KEY_")) delete baseEnv[name]; - const result = spawnSync("node", ["--import", "tsx", "src/setup.ts", ...args], { - cwd, - env: { ...baseEnv, ...env }, - // stdin is a pipe, not a TTY — exactly what an agent's shell looks like. - input: "", - encoding: "utf-8", - timeout: 20_000, - }); + const result = spawnSync( + "node", + ["--import", "tsx", "src/setup.ts", ...args], + { + cwd, + env: { ...baseEnv, ...env }, + // stdin is a pipe, not a TTY — exactly what an agent's shell looks like. + input: "", + encoding: "utf-8", + timeout: 20_000, + }, + ); return { code: result.status, output: `${result.stdout || ""}${result.stderr || ""}`, @@ -180,7 +196,9 @@ test("direct setup refuses to touch an org that already exists locally", () => { const fx = sandbox(); try { mkdirSync(join(fx.dir, "resources", "my-org"), { recursive: true }); - const res = runSetup(fx.dir, ["my-org"], { VAPI_PRIVATE_API_KEY: "fake-not-used" }); + const res = runSetup(fx.dir, ["my-org"], { + VAPI_PRIVATE_API_KEY: "fake-not-used", + }); assert.equal(res.code, 1); assert.match(res.output, /already set up locally/); assert.match(res.output, /npm run pull -- my-org/); @@ -198,8 +216,13 @@ test("direct setup refuses to touch an org that already exists locally", () => { test("direct setup refuses a generic exported key that differs from .env.", () => { const fx = sandbox(); try { - writeFileSync(join(fx.dir, ".env.my-org"), "VAPI_PRIVATE_API_KEY=my-org-key\n"); - const res = runSetup(fx.dir, ["my-org"], { VAPI_PRIVATE_API_KEY: "other-org-key" }); + writeFileSync( + join(fx.dir, ".env.my-org"), + "VAPI_PRIVATE_API_KEY=my-org-key\n", + ); + const res = runSetup(fx.dir, ["my-org"], { + VAPI_PRIVATE_API_KEY: "other-org-key", + }); assert.equal(res.code, 1); assert.match(res.output, /not the different key in \.env\.my-org/); assert.match(res.output, /VAPI_PRIVATE_API_KEY_MY_ORG/); @@ -213,8 +236,13 @@ test("direct setup refuses a generic exported key that differs from .env.", test("direct setup refuses a key another org's .env file already holds", () => { const fx = sandbox(); try { - writeFileSync(join(fx.dir, ".env.acme-dev"), "VAPI_PRIVATE_API_KEY=dev-key\n"); - const res = runSetup(fx.dir, ["acme-prod"], { VAPI_PRIVATE_API_KEY: "dev-key" }); + writeFileSync( + join(fx.dir, ".env.acme-dev"), + "VAPI_PRIVATE_API_KEY=dev-key\n", + ); + const res = runSetup(fx.dir, ["acme-prod"], { + VAPI_PRIVATE_API_KEY: "dev-key", + }); assert.equal(res.code, 1); assert.match(res.output, /already the key in \.env\.acme-dev/); assert.doesNotMatch(res.output, /Validating against/); @@ -226,7 +254,10 @@ test("direct setup refuses a key another org's .env file already holds", () => { test("direct setup uses the org's own variable over a generic key and the file", () => { const fx = sandbox(); try { - writeFileSync(join(fx.dir, ".env.my-org"), "VAPI_PRIVATE_API_KEY=stale-key\n"); + writeFileSync( + join(fx.dir, ".env.my-org"), + "VAPI_PRIVATE_API_KEY=stale-key\n", + ); const res = runSetup(fx.dir, ["my-org"], { VAPI_PRIVATE_API_KEY: "other-org-key", VAPI_PRIVATE_API_KEY_MY_ORG: "my-org-key", diff --git a/tests/sim-result.test.ts b/tests/sim-result.test.ts index 4bea397..4c8da3a 100644 --- a/tests/sim-result.test.ts +++ b/tests/sim-result.test.ts @@ -1,10 +1,11 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { - simRunItemTerminal, - simRunVerdict, type SimRunItem, type SimRunItemCounts, + simRunItemTerminal, + simRunVerdict, } from "../src/sim-result.ts"; // The verdict `npm run sim` and the PR check share. It must never report a diff --git a/tests/sim-run.test.ts b/tests/sim-run.test.ts index 71c858e..2f106e4 100644 --- a/tests/sim-run.test.ts +++ b/tests/sim-run.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { createServer, type IncomingMessage } from "node:http"; import type { AddressInfo } from "node:net"; diff --git a/tests/sim.test.ts b/tests/sim.test.ts index 9b6ff5f..64dcb72 100644 --- a/tests/sim.test.ts +++ b/tests/sim.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { resolveSelection, resolveTarget } from "../src/sim.ts"; @@ -123,8 +124,7 @@ test("resolveTarget: still accepts a legacy bare-string state value", () => { // `loadStateFile` reads the state JSON without migrating it, so a legacy // file can still hold `name → "uuid"`. The resolver accepts both shapes. const state = makeState(); - (state.assistants as Record)["legacy-agent"] = - "uuid-legacy"; + (state.assistants as Record)["legacy-agent"] = "uuid-legacy"; const target = resolveTarget(state, { assistant: "legacy-agent" }); assert.equal(target.id, "uuid-legacy"); }); diff --git a/tests/slug-utils.test.ts b/tests/slug-utils.test.ts index 1ca56f9..5ae2c5a 100644 --- a/tests/slug-utils.test.ts +++ b/tests/slug-utils.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/snapshot.test.ts b/tests/snapshot.test.ts index 839fbd8..28bddde 100644 --- a/tests/snapshot.test.ts +++ b/tests/snapshot.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdtempSync, readFileSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; diff --git a/tests/so-assistant-omit.test.ts b/tests/so-assistant-omit.test.ts index a8f74b9..622b868 100644 --- a/tests/so-assistant-omit.test.ts +++ b/tests/so-assistant-omit.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; @@ -49,7 +50,11 @@ test("one unresolved ref among the authored assistant_ids drops the whole assist !("assistantIds" in result), "the key must be absent so PATCH leaves the platform value untouched", ); - assert.equal(result.name, "intake-schema", "the rest of the payload survives"); + assert.equal( + result.name, + "intake-schema", + "the rest of the payload survives", + ); }); test("a fully resolved assistantIds array is sent unchanged", () => { @@ -242,9 +247,7 @@ test("updateStructuredOutputAssistantRefs: an untracked raw UUID counts as unres assert.equal(fetchCalls.length, 0); assert.ok( warnings.some((args) => - args.some( - (arg) => typeof arg === "string" && arg.includes(UUID_2), - ), + args.some((arg) => typeof arg === "string" && arg.includes(UUID_2)), ), "the untracked UUID should be named in the warning", ); diff --git a/tests/state-fixture.ts b/tests/state-fixture.ts new file mode 100644 index 0000000..331619c --- /dev/null +++ b/tests/state-fixture.ts @@ -0,0 +1,16 @@ +// Where a test fixture puts engine state: the same places the engine does. +// Fixtures that seed the pre-state/ layout on purpose live in +// state-layout.test.ts. + +import { mkdirSync } from "node:fs"; +import { dirname } from "node:path"; +import { baselinesDir, stateFilePath } from "../src/state-paths.ts"; + +/** state//state.json under `root`, with its folder created. */ +export function stateFixturePath(root: string, org: string): string { + const path = stateFilePath(root, org); + mkdirSync(dirname(path), { recursive: true }); + return path; +} + +export { baselinesDir }; diff --git a/tests/state-key-order.test.ts b/tests/state-key-order.test.ts index 3ca83ca..58026c7 100644 --- a/tests/state-key-order.test.ts +++ b/tests/state-key-order.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { sortedKeysReplacer } from "../src/state-serialize.ts"; diff --git a/tests/state-layout-unseen-commit.test.ts b/tests/state-layout-unseen-commit.test.ts new file mode 100644 index 0000000..9054270 --- /dev/null +++ b/tests/state-layout-unseen-commit.test.ts @@ -0,0 +1,810 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawnSync } from "node:child_process"; +import { + chmodSync, + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { migrateAll } from "../src/migrate-hash-store.ts"; +import { + COMMIT_STEP_FLAG, + commitStepAcknowledge, + commitStepAsk, + commitStepFilePath, + commitStepRead, + OLD_LAYOUT_NOTICE, + orgPinFileLegacyPath, + orgPinFileWrite, + StateLayoutError, + stateFileLegacyPath, + stateFilePath, + stateFileWrite, + stateLayoutPrepare, + stateMoveRead, +} from "../src/state-paths.ts"; + +// A promotion run writes the state file and leaves committing it to a later +// step. When that step stages the state file in a way the engine can't read +// (a helper script, a commit action with a file pattern, a pipeline outside +// GitHub Actions), a move into state/ would go unnoticed by it: every run +// would pass while state//state.json is never committed, and the next +// run would create every resource again. +// +// So no command moves committed state by itself, and the reader of commit +// steps fails closed. `npm run migrate` moves state only when every commit +// step it can read is seen to stage state/, or when a person says theirs +// does. A `git add` counts as seen only where the reader can place it: a +// plain command, run from the repository root, that names `state` or stages +// everything. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); +const ORG = "acme"; +const STATE = JSON.stringify({ + assistants: { a: { uuid: "11111111-1111-4111-8111-111111111111" } }, +}); +const OLD_STATE = ".vapi-state." + ORG + ".json"; +const CI: NodeJS.ProcessEnv = { CI: "true" }; +const WORD = '{\n "stagesStateFolder": true\n}\n'; + +function repo(files: Record): string { + const root = mkdtempSync(join(tmpdir(), "state-commit-step-")); + for (const [path, content] of Object.entries(files)) { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); + if (path.endsWith(".sh")) chmodSync(join(root, path), 0o755); + } + return root; +} + +function workflow(commitLines: string[], permissions?: string): string { + return [ + "name: Promote", + "on: { push: { branches: [main] } }", + ...(permissions ? ["permissions:", " contents: " + permissions] : []), + "jobs:", + " promote:", + " runs-on: ubuntu-latest", + " steps:", + " - run: npm run promote -- --all --apply", + ...commitLines, + "", + ].join("\n"); +} + +// A commit step that stages the old state file through a script. +const HELPER_WORKFLOW = workflow([ + " - run: |", + " ./scripts/stage-state.sh", + " git add -A -- resources", + ' git commit -m "chore: record promoted Vapi state"', + " git push", +]); +const HELPER_SCRIPT = + "#!/bin/bash\ngit add -A -- ':(glob).vapi-state.*.json' 2>/dev/null || true\n"; + +function helperRepo(files: Record = {}): string { + return repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": HELPER_WORKFLOW, + "scripts/stage-state.sh": HELPER_SCRIPT, + ...files, + }); +} + +function moved(root: string): boolean { + return ( + existsSync(stateFilePath(root, ORG)) && + !existsSync(stateFileLegacyPath(root, ORG)) + ); +} + +function assertHeldBack(root: string): void { + try { + stateLayoutPrepare(root, ORG, {}); + assert.ok( + existsSync(stateFileLegacyPath(root, ORG)), + "the old state file must stay: this workflow would not commit state/", + ); + assert.ok(!existsSync(stateFilePath(root, ORG))); + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +// Whether a command on a person's machine moves the old state file. +function movesByItself(files: Record): boolean { + const root = repo({ [OLD_STATE]: STATE, ...files }); + try { + stateLayoutPrepare(root, ORG, {}); + return moved(root); + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +function thrown(run: () => unknown): string { + try { + run(); + return "ran"; + } catch (error) { + return error instanceof StateLayoutError ? error.message : "other error"; + } +} + +// ── A commit step the engine can't read holds the move back ────────────── + +test("staging the state file in a helper script holds the move back", () => { + assertHeldBack( + repo({ + [".vapi-state." + ORG + ".json"]: STATE, + ".github/workflows/promotion.yml": workflow([ + " - run: |", + " ./scripts/stage-state.sh", + " git add -A -- resources", + ' git commit -m "chore: record promoted Vapi state"', + " git push", + ]), + "scripts/stage-state.sh": + "#!/bin/bash\ngit add -A -- ':(glob).vapi-state.*.json' 2>/dev/null || true\n", + }), + ); +}); + +test("a commit action with a file pattern for the state file holds the move back", () => { + assertHeldBack( + repo({ + [".vapi-state." + ORG + ".json"]: STATE, + ".github/workflows/promotion.yml": workflow([ + " - uses: stefanzweifel/git-auto-commit-action@v5", + " with:", + ' commit_message: "chore: record promoted Vapi state"', + ' file_pattern: ".vapi-state.*.json resources"', + ]), + }), + ); +}); + +test("no command moves state by itself, whatever is or isn't in the repository", () => { + assert.deepEqual( + [ + // A promotion pipeline outside GitHub Actions can't be read at all. + movesByItself({ "promotion.yml": "version: 1\n" }), + // No promotion and no workflow: an apply job in another CI system + // still commits state after a run. + movesByItself({}), + // Even a commit step that is seen to stage state/ doesn't move it. + movesByItself({ + ".github/workflows/promotion.yml": workflow( + [" - run: git add -A && git commit -m state && git push"], + "write", + ), + }), + ], + [false, false, false], + ); +}); + +// ── What the reader counts as staging state/ ───────────────────────────── + +const OLD_GLOB = "git add -A -- ':(glob).vapi-state.*.json'"; +const TAIL = [ + "if git diff --cached --quiet; then exit 0; fi", + 'git commit -q -m "chore: record promoted Vapi state"', +]; + +// Each commit step, and how the reader has to read it. +const STEPS: Array<[kind: string, name: string, run: string[]]> = [ + [ + "seen", + "upstream's step: both places, each guarded", + [ + "if [ -d state ]; then git add -A -- state; fi", + 'if compgen -G ".vapi-state.*.json" > /dev/null; then ' + + OLD_GLOB + + "; fi", + "git add -A -- resources", + ], + ], + ["seen", "git add -A", ["git add -A"]], + ["seen", "git add .", ["git add ."]], + ["seen", "git add --all", ["git add --all"]], + ["seen", "git add -A -- state", ["git add -A -- state"]], + ["seen", "git add ./state/ resources", ["git add ./state/ resources"]], + [ + "seen", + "git add with a redirect and || true", + ["git add -A . 2>/dev/null || true"], + ], + ["seen", "git add after &&", ["true && git add -A"]], + [ + "stale", + "the step from before state/", + [OLD_GLOB, "git add -A -- resources"], + ], + ["unseen", "git add -u", ["git add -u"]], + ["unseen", "git add -u .", ["git add -u ."]], + ["unseen", "git add --dry-run -A", ["git add --dry-run -A"]], + ["unseen", "no git add at all", []], + [ + "unseen", + "state files named one by one", + ["git add state/*/state.json resources"], + ], + ["unseen", "one org's folder", ["git add -A -- state/acme resources"]], + ["unseen", "a variable", ['PATHS="state resources"', "git add -A -- $PATHS"]], + ["unseen", "paths from a command", ["git add -A -- $(cat paths.txt)"]], + ["unseen", "git -C", ['git -C "$PWD" add -A']], + ["unseen", "a helper script", ["./scripts/stage-state.sh"]], + ["unseen", "everything but state/", ["git add -A -- . ':!state'"]], + [ + "unseen", + "git add . after cd", + [OLD_GLOB, "cd resources && git add . && cd .."], + ], + [ + "unseen", + "git add -A after pushd", + ["pushd resources", "git add -A", "popd"], + ], + [ + "unseen", + "git add -A in a subshell that changed directory", + ["(cd resources; git add -A)"], + ], + [ + "unseen", + "git add -A after sourcing a script", + ["source ./scripts/stage-state.sh", "git add -A"], + ], + [ + "unseen", + "git add -A against another repository", + ["GIT_DIR=/tmp/elsewhere/.git git add -A"], + ], + ["unseen", "git add -A after ||", ["true || git add -A"]], + [ + "unseen", + "git add -A inside an if", + ['if [ "${DEPLOY:-}" = yes ]; then git add -A; fi'], + ], + [ + "unseen", + "git add -A as the if's own test", + ["if git add -A -- nothing-here; then true; fi"], + ], + [ + "unseen", + "git add as part of an if's test", + ["if false && git add -A -- state; then true; fi"], + ], + [ + "unseen", + "a loop that may not run", + ["for org in $ORGS; do git add -A -- state; done"], + ], + ["unseen", "a function nobody calls", ["stage() { git add -A -- state; }"]], + [ + "unseen", + "inside an echo", + [ + 'echo "staged by the helper, not by: git add -A -- state"', + "./scripts/stage-state.sh", + ], + ], + [ + "unseen", + "inside a here-document", + ["cat > /dev/null <<'EOF'", "git add -A -- state", "EOF"], + ], +]; + +// Run the commit step for real, after a run changed state//state.json, +// and report whether the commit it makes holds the new state. +function stepCommitsStateFolder(run: string[]): boolean { + const GIT_ENV = { + ...process.env, + GIT_CONFIG_GLOBAL: "/dev/null", + GIT_CONFIG_NOSYSTEM: "1", + GIT_AUTHOR_NAME: "t", + GIT_AUTHOR_EMAIL: "t@example.invalid", + GIT_COMMITTER_NAME: "t", + GIT_COMMITTER_EMAIL: "t@example.invalid", + }; + const git = (cwd: string, ...args: string[]): string => + execFileSync("git", args, { cwd, env: GIT_ENV, encoding: "utf8" }); + const root = repo({ + ["state/" + ORG + "/state.json"]: STATE, + "resources/acme/assistants/a.md": "one\n", + "scripts/stage-state.sh": HELPER_SCRIPT, + }); + try { + git(root, "init", "-q", "-b", "main"); + git(root, "add", "-A"); + git(root, "commit", "-q", "-m", "init"); + const next = STATE.replace("1111", "2222"); + writeFileSync(stateFilePath(root, ORG), next); + writeFileSync(join(root, "resources/acme/assistants/a.md"), "two\n"); + spawnSync("bash", ["-eo", "pipefail", "-c", [...run, ...TAIL].join("\n")], { + cwd: root, + env: GIT_ENV, + }); + return git(root, "show", "HEAD:state/" + ORG + "/state.json") === next; + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +test("a commit step is read as staging state/ only where the reader can place its git add", () => { + const read: Record = {}; + const expected: Record = {}; + for (const [kind, name, run] of STEPS) { + const root = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": workflow( + [ + " - run: |", + ...[...run, ...TAIL].map((line) => " " + line), + ], + "write", + ), + }); + read[name] = commitStepRead(root, {}).kind; + expected[name] = kind; + rmSync(root, { recursive: true, force: true }); + } + assert.deepEqual(read, expected); +}); + +test("every step read as staging state/ commits state/ when it is run", () => { + const seen = STEPS.filter(([kind]) => kind === "seen"); + assert.deepEqual( + seen.map(([, name, run]) => [name, stepCommitsStateFolder(run)]), + seen.map(([, name]) => [name, true]), + ); +}); + +test("where a step runs decides whether its git add counts", () => { + const kind = (step: string[], job: string[] = []) => { + const root = repo({ + ".github/workflows/promotion.yml": [ + "on: push", + "permissions:", + " contents: write", + "jobs:", + " promote:", + ...job, + " steps:", + " - uses: actions/checkout@v4", + ...step, + "", + ].join("\n"), + }); + try { + return commitStepRead(root, {}).kind; + } finally { + rmSync(root, { recursive: true, force: true }); + } + }; + assert.deepEqual( + { + "at the repository root": kind([ + " - run: git add -A && git commit -m s", + ]), + "a step's working-directory": kind([ + " - run: git add -A && git commit -m s", + " working-directory: resources", + ]), + "the job's default working-directory": kind( + [" - run: git add -A && git commit -m s"], + [" defaults:", " run:", " working-directory: resources"], + ), + "a shell that isn't bash or sh": kind([ + " - run: git add -A && git commit -m s", + " shell: pwsh", + ]), + "a checkout into a sub-folder": kind([ + " - uses: actions/checkout@v4", + " with:", + " path: site", + " - run: git add -A && git commit -m s", + ]), + "another repository's git folder": kind( + [" - run: git add -A && git commit -m s"], + [" env:", " GIT_DIR: /tmp/elsewhere/.git"], + ), + }, + { + "at the repository root": "seen", + "a step's working-directory": "unseen", + "the job's default working-directory": "unseen", + "a shell that isn't bash or sh": "unseen", + "a checkout into a sub-folder": "unseen", + "another repository's git folder": "unseen", + }, + ); +}); + +// ── Which jobs have to be seen ─────────────────────────────────────────── + +const SEEN_WORKFLOW = workflow( + [ + " - run: |", + " git add -A -- state ':(glob).vapi-state.*.json' resources", + " git commit -m state && git push", + ], + "write", +); +const job = (name: string, lines: string[]) => [ + " " + name + ":", + " runs-on: ubuntu-latest", + ...lines, +]; + +test("every job that shows a commit step has to be seen, in every workflow", () => { + const kind = (files: Record, env: NodeJS.ProcessEnv = {}) => { + const root = repo(files); + try { + const step = commitStepRead(root, env); + return step.kind + ("file" in step ? " " + step.file : ""); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }; + const lint = (permissions: string[]) => + [ + "on: pull_request", + ...permissions, + "jobs:", + ...job("lint", [" steps:", " - run: npm ci && npm run lint"]), + "", + ].join("\n"); + const readOnly = ["permissions:", " contents: read"]; + const actions = (file: string): NodeJS.ProcessEnv => ({ + GITHUB_ACTIONS: "true", + GITHUB_WORKFLOW_REF: `acme/repo/.github/workflows/${file}@refs/heads/main`, + }); + const both = { + ".github/workflows/promotion.yml": SEEN_WORKFLOW, + ".github/workflows/lint.yml": lint([]), + }; + assert.deepEqual( + { + "no workflow at all": kind({}), + "one job, seen": kind({ + ".github/workflows/promotion.yml": SEEN_WORKFLOW, + }), + "a second job in the same file that stages in its own folder": kind({ + ".github/workflows/promotion.yml": + workflow( + [" - run: ./scripts/stage-state.sh && git commit -m s"], + "write", + ) + + job("docs", [ + " steps:", + " - run: cd site && git init -q && git add -A && git commit -q -m docs", + ]).join("\n") + + "\n", + }), + "a second job in the same file with nothing to read": kind({ + ".github/workflows/promotion.yml": + SEEN_WORKFLOW + + job("deploy", [" steps:", " - run: ./deploy.sh"]).join("\n") + + "\n", + }), + "a second workflow whose token can't write and that runs no git": kind({ + ".github/workflows/promotion.yml": SEEN_WORKFLOW, + ".github/workflows/lint.yml": lint(readOnly), + }), + "a second workflow with no permissions block": kind(both), + "a read-only token, alone": kind({ + ".github/workflows/lint.yml": lint(readOnly), + }), + "a read-only token that runs git commit": kind({ + ".github/workflows/lint.yml": lint(readOnly).replace( + "npm run lint", + "git commit -am x", + ), + }), + "a workflow that doesn't parse": kind({ + ".github/workflows/broken.yml": "jobs: [", + }), + // In GitHub Actions the run is judged by the workflow running it. + "in Actions, the seen workflow": kind(both, actions("promotion.yml")), + "in Actions, the other workflow": kind(both, actions("lint.yml")), + "in Actions, with no workflow named": kind(both, { + GITHUB_ACTIONS: "true", + }), + }, + { + "no workflow at all": "none", + "one job, seen": "seen", + "a second job in the same file that stages in its own folder": + "unseen .github/workflows/promotion.yml", + "a second job in the same file with nothing to read": + "unseen .github/workflows/promotion.yml", + "a second workflow whose token can't write and that runs no git": "seen", + "a second workflow with no permissions block": + "unseen .github/workflows/lint.yml", + "a read-only token, alone": "none", + "a read-only token that runs git commit": + "unseen .github/workflows/lint.yml", + "a workflow that doesn't parse": "unseen .github/workflows/broken.yml", + "in Actions, the seen workflow": "seen", + "in Actions, the other workflow": "unseen .github/workflows/lint.yml", + "in Actions, with no workflow named": "unseen .github/workflows/lint.yml", + }, + ); +}); + +test("the workflows this repository ships are read as staging both places", () => { + assert.deepEqual(commitStepRead(REPO, {}), { kind: "seen", stagesOld: true }); +}); + +// ── npm run migrate ────────────────────────────────────────────────────── + +test("migrate moves nothing until a commit step is seen or a person says theirs stages state/", async () => { + const repos: Record[] = [ + // A helper script, and no workflow at all: neither is seen. + { + ".github/workflows/promotion.yml": HELPER_WORKFLOW, + "scripts/stage-state.sh": HELPER_SCRIPT, + }, + {}, + ]; + for (const files of repos) { + const root = repo({ [OLD_STATE]: STATE, ...files }); + try { + const asked = commitStepAsk(root)?.join("\n") ?? ""; + const first = await migrateAll(root); + const heldBack = !moved(root) && !existsSync(join(root, "state")); + const said = commitStepAcknowledge(root); + const second = await migrateAll(root); + assert.deepEqual( + { + asked: [ + /Nothing moves into state\/ yet/.test(asked), + asked.includes("git add -A -- state "), + asked.includes("git add -A -- ':(glob).vapi-state.*.json'"), + asked.includes("npm run migrate -- " + COMMIT_STEP_FLAG), + /takes your word/.test(asked), + ], + first: [ + first.orgs[0]!.moved, + first.commitStepAsk !== undefined, + heldBack, + ], + said: /^✍️ {2}Wrote state\/commit-step\.json/.test(said), + word: existsSync(commitStepFilePath(root)), + second: [second.orgs[0]!.moved, second.commitStepAsk, moved(root)], + // Said again before a later move, with the limit of a person's word. + later: /takes that word/.test(stateMoveRead(root).lines.join("\n")), + }, + { + asked: [true, true, true, true, true], + first: [[], true, true], + said: true, + word: true, + second: [[OLD_STATE], undefined, true], + later: true, + }, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } + } +}); + +test("the flag writes nothing where the engine can see for itself", () => { + const root = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": SEEN_WORKFLOW, + }); + try { + assert.deepEqual( + [ + /is not needed here/.test(commitStepAcknowledge(root)), + existsSync(commitStepFilePath(root)), + commitStepAsk(root), + stateMoveRead(root).open, + ], + [true, false, undefined, true], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +function migrateCommand(root: string, ...args: string[]) { + if (!existsSync(join(root, "src"))) { + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + } + const result = spawnSync( + process.execPath, + ["--import", "tsx", "src/migrate-cmd.ts", ...args], + { + cwd: root, + encoding: "utf8", + env: { ...process.env, CI: "", GITHUB_ACTIONS: "" }, + }, + ); + return { code: result.status, out: `${result.stdout}${result.stderr}` }; +} + +test("npm run migrate holds an unread commit step back, exits 0, and rejects an option it doesn't know", () => { + const root = helperRepo(); + try { + const plain = migrateCommand(root); + const heldAfterPlain = !moved(root); + const typo = migrateCommand(root, "--commit-step-stages-stat"); + const heldAfterTypo = !moved(root); + const told = migrateCommand(root, COMMIT_STEP_FLAG); + assert.deepEqual( + { + plain: [ + plain.code, + plain.out.includes("git add -A -- state "), + plain.out.includes("git add -A -- ':(glob).vapi-state.*.json'"), + plain.out.includes("npm run migrate -- --commit-step-stages-state"), + plain.out.includes("State stays where it is"), + heldAfterPlain, + ], + typo: [ + typo.code, + typo.out.includes("Unrecognized argument: --commit-step-stages-stat"), + heldAfterTypo, + ], + told: [told.code, told.out.includes("📦 Moved"), moved(root)], + }, + { + plain: [0, true, true, true, true, true], + typo: [1, true, true], + told: [0, true, true], + }, + plain.out + typo.out + told.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("npm run migrate says what the commit step has to stage before it moves anything", () => { + const root = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": SEEN_WORKFLOW, + }); + try { + const first = migrateCommand(root); + const again = migrateCommand(root); + const at = (needle: string) => first.out.indexOf(needle); + assert.deepEqual( + [ + first.code, + moved(root), + at("git add -A -- state ") > 0, + at("git add -A -- ':(glob).vapi-state.*.json'") > 0, + at("is not read and needs the same two lines") > 0, + at("git add -A -- state ") < at("📦 Moved"), + // Nothing left to move, so nothing to say about the commit step. + again.out.includes("git add -A -- state "), + ], + [0, true, true, true, true, true, false], + first.out + again.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +// ── A CI run ───────────────────────────────────────────────────────────── + +test("a CI run on the old layout keeps working under a commit step the engine can't read", () => { + const root = helperRepo(); + try { + assert.deepEqual( + [ + stateLayoutPrepare(root, ORG, CI), + existsSync(stateFileLegacyPath(root, ORG)), + existsSync(join(root, "state")), + stateFileWrite(root, ORG), + // A new org is written where the others are. + stateFileWrite(root, "new-org"), + orgPinFileWrite(root, "new-org"), + ], + [ + [OLD_LAYOUT_NOTICE], + true, + false, + stateFileLegacyPath(root, ORG), + stateFileLegacyPath(root, "new-org"), + orgPinFileLegacyPath(root, "new-org"), + ], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a CI run stops before it writes state/ that its commit step isn't seen to stage", () => { + const files = { + ["state/" + ORG + "/state.json"]: STATE, + ".github/workflows/promotion.yml": HELPER_WORKFLOW, + "scripts/stage-state.sh": HELPER_SCRIPT, + }; + const root = repo(files); + const saidSo = repo({ ...files, "state/commit-step.json": WORD }); + // A pipeline the engine has no file for shows nothing to judge. + const elsewhere = repo({ + ["state/" + ORG + "/state.json"]: STATE, + ".gitlab-ci.yml": "deploy:\n script:\n - npm run apply -- acme\n", + }); + try { + const stopped = thrown(() => stateLayoutPrepare(root, ORG, CI)); + assert.deepEqual( + [ + /promotion\.yml can commit to this repository and is not seen to stage state\//.test( + stopped, + ), + /Stopped before reading or changing anything/.test(stopped), + stopped.includes("npm run migrate -- " + COMMIT_STEP_FLAG), + // On a person's machine the same checkout runs. + stateLayoutPrepare(root, ORG, {}), + // With a person's word the run goes on, and says whose word it is. + stateLayoutPrepare(saidSo, ORG, CI).map((line) => + /commit-step\.json says this run's commit step stages state\//.test( + line, + ), + ), + stateLayoutPrepare(elsewhere, ORG, CI), + ], + [true, true, true, [], [true], []], + ); + } finally { + for (const dir of [root, saidSo, elsewhere]) + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("a CI run stops when the old file it would write is no longer what the commit step stages", () => { + // The workflow moved on to state/ and the state file was left behind. + const ahead = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": workflow( + [" - run: git add -A -- state && git commit -m state && git push"], + "write", + ), + }); + // The same, where the workflow can't be read and a person gave their word. + const saidSo = helperRepo({ "state/commit-step.json": WORD }); + try { + assert.deepEqual( + [ahead, saidSo].map((root) => { + const message = thrown(() => stateLayoutPrepare(root, ORG, CI)); + return [ + /is still at the repository root/.test(message), + /Run `npm run migrate` on your machine/.test(message), + existsSync(stateFileLegacyPath(root, ORG)), + stateLayoutPrepare(root, ORG, {}), + ]; + }), + [ + [true, true, true, [OLD_LAYOUT_NOTICE]], + [true, true, true, [OLD_LAYOUT_NOTICE]], + ], + ); + } finally { + for (const dir of [ahead, saidSo]) + rmSync(dir, { recursive: true, force: true }); + } +}); diff --git a/tests/state-layout.test.ts b/tests/state-layout.test.ts new file mode 100644 index 0000000..dd09c25 --- /dev/null +++ b/tests/state-layout.test.ts @@ -0,0 +1,886 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { spawn } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + rmSync, + symlinkSync, + utimesSync, + writeFileSync, +} from "node:fs"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { assertStateMigrated, migrateAll } from "../src/migrate-hash-store.ts"; +import { + baselinesDir, + commitStepAcknowledge, + OLD_LAYOUT_NOTICE, + orgPinFilePath, + orgPinFileRead, + orgPinFileWrite, + StateLayoutError, + snapshotsDir, + stateFileLeftover, + stateFilePath, + stateFileRead, + stateFileWrite, + stateLayout, + stateLayoutPrepare, + stateNoticesPrint, + stateOrgsList, +} from "../src/state-paths.ts"; + +// Engine state used to sit under dot-names at the repository root and in +// resources//. It now lives in state//. Losing or half-moving the +// state file makes the next push create every resource again, and a commit +// step that stages only the old place would leave moved state out of git. +// So an org is in one layout, every command reads and writes the layout it +// finds, and only `npm run migrate` moves an org. These tests pin that: an +// old repository left exactly where it is on a person's machine and in CI, +// a moved one, one cut short, two places in disagreement, and the move. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); +const ORG = "acme"; +const UUID = "11111111-1111-4111-8111-111111111111"; +const STATE = `${JSON.stringify({ assistants: { intake: { uuid: UUID } } }, null, 2)}\n`; +const PIN = '{\n "orgId": "org-a"\n}\n'; +const LOCAL: NodeJS.ProcessEnv = {}; +const CI: NodeJS.ProcessEnv = { CI: "true" }; + +// The step every repository had before state/ existed. +const OLD_WORKFLOW = [ + "jobs:", + " promote:", + " steps:", + " - name: Commit reconciled files and UUID state", + " run: |", + " git add -A -- ':(glob).vapi-state.*.json'", + " git add -A -- resources", + ' git commit -m "chore: record promoted Vapi state [skip promotion]"', + "", +].join("\n"); + +function put(root: string, path: string, content: string): void { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); +} + +function read(root: string, path: string): string | undefined { + return existsSync(join(root, path)) + ? readFileSync(join(root, path), "utf8") + : undefined; +} + +// A repository as it looked before state/ existed. +function oldRepo(): string { + const root = mkdtempSync(join(tmpdir(), "state-layout-")); + put(root, `.vapi-state.${ORG}.json`, STATE); + put(root, `resources/${ORG}/.vapi-org.json`, PIN); + put(root, `.vapi-state-hash/${ORG}/${UUID}`, "baseline-hash\n"); + put( + root, + `.vapi-state.${ORG}.snapshots/2026-01-01T00-00-00-000Z/assistants/intake.json`, + "{}\n", + ); + return root; +} + +// The workflows this repository ships, whose commit step stages state/. +function shippedWorkflows(root: string): void { + cpSync(join(REPO, ".github/workflows"), join(root, ".github/workflows"), { + recursive: true, + }); +} + +function layout(root: string): Record { + return { + oldState: read(root, `.vapi-state.${ORG}.json`), + oldPin: read(root, `resources/${ORG}/.vapi-org.json`), + oldBaseline: read(root, `.vapi-state-hash/${ORG}/${UUID}`), + oldSnapshot: read( + root, + `.vapi-state.${ORG}.snapshots/2026-01-01T00-00-00-000Z/assistants/intake.json`, + ), + state: read(root, `state/${ORG}/state.json`), + pin: read(root, `state/${ORG}/org.json`), + baseline: read(root, `state/${ORG}/local/baselines/${UUID}`), + snapshot: read( + root, + `state/${ORG}/local/snapshots/2026-01-01T00-00-00-000Z/assistants/intake.json`, + ), + }; +} + +const OLD = { + oldState: STATE, + oldPin: PIN, + oldBaseline: "baseline-hash\n", + oldSnapshot: "{}\n", + state: undefined, + pin: undefined, + baseline: undefined, + snapshot: undefined, +}; + +const MOVED = { + oldState: undefined, + oldPin: undefined, + oldBaseline: undefined, + oldSnapshot: undefined, + state: STATE, + pin: PIN, + baseline: "baseline-hash\n", + snapshot: "{}\n", +}; + +function withRepo(root: string, body: () => void | Promise) { + return Promise.resolve() + .then(body) + .finally(() => rmSync(root, { recursive: true, force: true })); +} + +function emptyRepo(files: Record = {}): string { + const root = mkdtempSync(join(tmpdir(), "state-layout-")); + for (const [path, content] of Object.entries(files)) put(root, path, content); + return root; +} + +// ── Which layout an org is in ──────────────────────────────────────────── + +test("orgs are listed from both layouts", () => { + const root = oldRepo(); + return withRepo(root, () => { + put(root, "state/beta/state.json", "{}\n"); + put(root, "state/README.md", "# state\n"); + put(root, "state/no-state-file/local/baselines/x", "h\n"); + assert.deepEqual(stateOrgsList(root), ["acme", "beta"]); + }); +}); + +test("a file is read and written where it is", () => { + const root = oldRepo(); + return withRepo(root, () => { + const before = [stateFileRead(root, ORG), orgPinFileRead(root, ORG)]; + put(root, `state/${ORG}/state.json`, STATE); + put(root, `state/${ORG}/org.json`, PIN); + assert.deepEqual( + [ + before, + stateFileRead(root, ORG), + orgPinFileRead(root, ORG), + stateFileWrite === stateFileRead, + orgPinFileWrite === orgPinFileRead, + ], + [ + [ + join(root, `.vapi-state.${ORG}.json`), + join(root, `resources/${ORG}/.vapi-org.json`), + ], + stateFilePath(root, ORG), + orgPinFilePath(root, ORG), + true, + true, + ], + ); + }); +}); + +test("an org with no state yet goes where the repository's other orgs keep theirs", () => { + const old = oldRepo(); + const moved = emptyRepo({ "state/beta/state.json": STATE }); + const mixed = emptyRepo({ + "state/beta/state.json": STATE, + ".vapi-state.gamma.json": STATE, + }); + try { + assert.deepEqual( + [ + stateLayout(old, "new-org"), + stateFileWrite(old, "new-org"), + orgPinFileWrite(old, "new-org"), + stateLayout(moved, "new-org"), + stateFileWrite(moved, "new-org"), + orgPinFileWrite(moved, "new-org"), + // One org still at the root means the commit step may still be the + // old one, so a new org goes where that step looks. + stateLayout(mixed, "new-org"), + ], + [ + "root", + join(old, ".vapi-state.new-org.json"), + join(old, "resources/new-org/.vapi-org.json"), + "folder", + stateFilePath(moved, "new-org"), + orgPinFilePath(moved, "new-org"), + "root", + ], + ); + } finally { + for (const root of [old, moved, mixed]) + rmSync(root, { recursive: true, force: true }); + } +}); + +test("an org's pin decides its layout while it has no state file", () => { + // Each org's pin says the opposite of where the other org keeps its state. + const pinnedOld = emptyRepo({ + "state/beta/state.json": STATE, + [`resources/${ORG}/.vapi-org.json`]: PIN, + }); + const pinnedNew = emptyRepo({ + ".vapi-state.gamma.json": STATE, + [`state/${ORG}/org.json`]: PIN, + }); + try { + assert.deepEqual( + [stateLayout(pinnedOld, ORG), stateLayout(pinnedNew, ORG)], + ["root", "folder"], + ); + } finally { + for (const root of [pinnedOld, pinnedNew]) + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a repository with no state at all uses state/ only where the commit step is seen or said to stage it", () => { + const layoutOf = (files: Record, shipped = false) => { + const root = emptyRepo(files); + if (shipped) shippedWorkflows(root); + try { + return stateLayout(root, ORG); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }; + const word = '{\n "stagesStateFolder": true\n}\n'; + assert.deepEqual( + { + "no workflow": layoutOf({}), + "the workflows this repository ships": layoutOf({}, true), + "the step from before state/": layoutOf({ + ".github/workflows/promotion.yml": OLD_WORKFLOW, + }), + "no workflow, and a person's word": layoutOf({ + "state/commit-step.json": word, + }), + "the step from before state/, and a person's word": layoutOf({ + ".github/workflows/promotion.yml": OLD_WORKFLOW, + "state/commit-step.json": word, + }), + }, + { + "no workflow": "root", + "the workflows this repository ships": "folder", + "the step from before state/": "root", + "no workflow, and a person's word": "folder", + "the step from before state/, and a person's word": "root", + }, + ); +}); + +// ── A command leaves committed state where it is ───────────────────────── + +test("a command leaves an old repository exactly where it is, on any machine and under any workflow", () => { + for (const env of [LOCAL, CI, { GITHUB_ACTIONS: "true" }]) { + for (const shipped of [false, true]) { + const root = oldRepo(); + if (shipped) shippedWorkflows(root); + const first = stateLayoutPrepare(root, ORG, env); + const second = stateLayoutPrepare(root, ORG, env); + const after = layout(root); + const stateFolder = existsSync(join(root, "state")); + rmSync(root, { recursive: true, force: true }); + assert.deepEqual( + { first, second, after, stateFolder }, + { + first: [OLD_LAYOUT_NOTICE], + second: [OLD_LAYOUT_NOTICE], + after: OLD, + stateFolder: false, + }, + ); + } + } +}); + +test("the older-layout line is one line, printed once per command", () => { + const printed: string[] = []; + const log = console.log; + console.log = (line: string) => void printed.push(line); + try { + // apply prints it, then starts a pull and a push with the same environment. + const command: NodeJS.ProcessEnv = {}; + stateNoticesPrint([OLD_LAYOUT_NOTICE], command); + stateNoticesPrint([OLD_LAYOUT_NOTICE, "something else"], command); + stateNoticesPrint([OLD_LAYOUT_NOTICE], command); + // The next command starts with a fresh environment. + stateNoticesPrint([OLD_LAYOUT_NOTICE], {}); + } finally { + console.log = log; + } + assert.deepEqual( + [ + printed, + OLD_LAYOUT_NOTICE.includes("\n"), + /npm run migrate/.test(OLD_LAYOUT_NOTICE), + ], + [[OLD_LAYOUT_NOTICE, "something else", OLD_LAYOUT_NOTICE], false, true], + ); +}); + +test("a repository in state/ gets no notice, and a new org joins it there", () => { + const root = emptyRepo({ [`state/${ORG}/state.json`]: STATE }); + return withRepo(root, () => { + assert.deepEqual( + [ + stateLayoutPrepare(root, ORG, LOCAL), + stateLayoutPrepare(root, ORG, CI), + stateLayoutPrepare(root, "new-org", CI), + stateFileWrite(root, "new-org") === stateFilePath(root, "new-org"), + ], + [[], [], [], true], + ); + }); +}); + +test("for an org in state/, this machine's baselines and snapshots follow, newest side winning", () => { + // What a teammate's machine holds after someone else ran migrate. + const root = oldRepo(); + return withRepo(root, () => { + rmSync(join(root, `.vapi-state.${ORG}.json`)); + rmSync(join(root, `resources/${ORG}/.vapi-org.json`)); + put(root, `state/${ORG}/state.json`, STATE); + put(root, `state/${ORG}/org.json`, PIN); + put(root, `state/${ORG}/local/baselines/${UUID}`, "newer-hash\n"); + put(root, `.vapi-state-hash/${ORG}/other`, "other-hash\n"); + const notices = stateLayoutPrepare(root, ORG, LOCAL); + assert.deepEqual( + [ + notices, + readdirSync(baselinesDir(root, ORG)).sort(), + read(root, `state/${ORG}/local/baselines/${UUID}`), + existsSync(join(root, ".vapi-state-hash")), + readdirSync(snapshotsDir(root, ORG)), + stateLayoutPrepare(root, ORG, LOCAL), + ], + [ + [ + `📦 Moved .vapi-state-hash/${ORG}/, .vapi-state.${ORG}.snapshots/ into state/${ORG}/local/. Both places are gitignored.`, + ], + [UUID, "other"].sort(), + "newer-hash\n", + false, + ["2026-01-01T00-00-00-000Z"], + [], + ], + ); + }); +}); + +// ── A CI run under a workflow that would not commit what it writes ─────── + +test("a CI run stops before it writes state/ its workflow would not commit", () => { + const root = emptyRepo({ + [`state/${ORG}/state.json`]: STATE, + ".github/workflows/promotion.yml": OLD_WORKFLOW, + }); + return withRepo(root, () => { + assert.throws( + () => stateLayoutPrepare(root, ORG, CI), + (error: unknown) => + error instanceof StateLayoutError && + /promotion\.yml stages \.vapi-state\.\*\.json but not state\//.test( + error.message, + ) && + /Stopped before reading or changing anything/.test(error.message), + ); + // The same checkout on a person's machine runs: whoever commits there + // sees what they stage. + assert.deepEqual(stateLayoutPrepare(root, ORG, LOCAL), []); + }); +}); + +// ── Cut short, or in both places ───────────────────────────────────────── + +test("a move cut short between two files is read where each file is, and migrate finishes it", async () => { + const root = oldRepo(); + shippedWorkflows(root); + try { + // The state file moved; the run died before the pin did. + put(root, `state/${ORG}/state.json`, STATE); + rmSync(join(root, `.vapi-state.${ORG}.json`)); + stateLayoutPrepare(root, ORG, LOCAL); + const cut = [ + stateFileRead(root, ORG), + orgPinFileWrite(root, ORG), + layout(root).oldPin, + layout(root).pin, + ]; + await migrateAll(root); + assert.deepEqual( + [cut, layout(root)], + [ + [ + stateFilePath(root, ORG), + join(root, `resources/${ORG}/.vapi-org.json`), + PIN, + undefined, + ], + MOVED, + ], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("the same content in both places: state/ is read, the old copy stays, and only migrate removes it", async () => { + // Same mapping, different key order and spacing: a merge or a formatter. + const copy = `{"assistants":{"intake":{"uuid":"${UUID}"}}}`; + for (const env of [LOCAL, CI]) { + const root = oldRepo(); + shippedWorkflows(root); + put(root, `state/${ORG}/state.json`, copy); + const notices = stateLayoutPrepare(root, ORG, env); + const held = layout(root); + const leftover = stateFileLeftover(root, ORG); + await migrateAll(root); + const after = layout(root); + rmSync(root, { recursive: true, force: true }); + assert.deepEqual( + { + notice: notices.at(-1), + read: [held.oldState, held.state], + leftover: leftover?.endsWith(`.vapi-state.${ORG}.json`), + afterMigrate: [after.oldState, after.state, after.pin], + }, + { + notice: + "ℹ️ .vapi-state.acme.json is still here beside its copy in state/acme/. `npm run migrate` removes it.", + read: [STATE, copy], + leftover: true, + afterMigrate: [undefined, copy, PIN], + }, + ); + } +}); + +test("two state files that disagree stop the command with both intact", () => { + for (const [path, next] of [ + [`state/${ORG}/state.json`, '{"assistants":{}}\n'], + [`state/${ORG}/org.json`, '{"orgId":"org-b"}\n'], + ] as const) { + const root = oldRepo(); + put(root, path, next); + let message = ""; + try { + stateLayoutPrepare(root, ORG, LOCAL); + } catch (error) { + message = + error instanceof StateLayoutError ? error.message : "wrong error"; + } + const after = layout(root); + rmSync(root, { recursive: true, force: true }); + assert.deepEqual( + [ + /both exist and disagree/.test(message), + message.includes(path), + after.oldState, + after.oldPin, + path.endsWith("state.json") ? after.state : after.pin, + // Nothing else moved either: the stop comes first. + after.baseline, + ], + [true, true, STATE, PIN, next, undefined], + ); + } +}); + +// ── npm run migrate and the legacy-format guard ────────────────────────── + +const FAT_STATE = `${JSON.stringify({ assistants: { intake: { uuid: UUID, origin: "pulled", lastPulledAt: "2026-01-01T00:00:00Z" } } })}\n`; + +test("the legacy-format guard reads the state file in either place", () => { + const root = mkdtempSync(join(tmpdir(), "state-layout-")); + return withRepo(root, () => { + put(root, ".vapi-state.old.json", FAT_STATE); + put(root, "state/new/state.json", FAT_STATE); + put(root, "state/fine/state.json", STATE); + assert.deepEqual( + ["old", "new", "fine"].map((org) => { + try { + assertStateMigrated(stateFileRead(root, org)); + return "ok"; + } catch (error) { + return /legacy format/.test((error as Error).message) + ? "legacy" + : "other"; + } + }), + ["legacy", "legacy", "ok"], + ); + }); +}); + +test("under a commit step seen to stage state/, migrate slims and moves every org, in a CI run too", async () => { + const root = oldRepo(); + const ci = process.env.CI; + process.env.CI = "true"; + try { + shippedWorkflows(root); + put(root, `.vapi-state.${ORG}.json`, FAT_STATE); + put(root, "state/beta/state.json", STATE); + const result = await migrateAll(root); + const after = layout(root); + assert.deepEqual( + { + orgs: result.orgs.map((org) => [ + org.org, + org.stateFile, + org.slimmed, + org.moved, + ]), + after: { ...after, state: JSON.parse(after.state!) }, + rootLeftovers: readdirSync(root).filter((name) => + name.startsWith(".vapi-state"), + ), + again: (await migrateAll(root)).orgs.map((org) => [ + org.slimmed, + org.moved, + ]), + }, + { + orgs: [ + [ + ORG, + "state/acme/state.json", + true, + [ + `.vapi-state.${ORG}.json`, + `resources/${ORG}/.vapi-org.json`, + `.vapi-state-hash/${ORG}/`, + `.vapi-state.${ORG}.snapshots/`, + ], + ], + ["beta", "state/beta/state.json", false, []], + ], + after: { + ...MOVED, + state: { assistants: { intake: { uuid: UUID, origin: "pulled" } } }, + }, + rootLeftovers: [], + again: [ + [false, []], + [false, []], + ], + }, + ); + } finally { + if (ci === undefined) delete process.env.CI; + else process.env.CI = ci; + rmSync(root, { recursive: true, force: true }); + } +}); + +test("migrate slims in place and moves nothing while a workflow would drop state/, whatever a person says", async () => { + const root = oldRepo(); + try { + put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); + put(root, `.vapi-state.${ORG}.json`, FAT_STATE); + const result = await migrateAll(root); + let refusal = ""; + try { + commitStepAcknowledge(root); + } catch (error) { + refusal = error instanceof StateLayoutError ? error.message : "other"; + } + assert.deepEqual( + [ + result.orgs[0]!.stateFile, + result.orgs[0]!.slimmed, + result.orgs[0]!.moved, + JSON.parse(layout(root).oldState!), + layout(root).state, + /is not true yet/.test(refusal), + existsSync(join(root, "state")), + ], + [ + ".vapi-state.acme.json", + true, + [], + { assistants: { intake: { uuid: UUID, origin: "pulled" } } }, + undefined, + true, + false, + ], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +// ── Real commands against a stub API ───────────────────────────────────── + +const ON_PLATFORM = "What the platform holds."; +const ASSISTANT = (id: string, name: string) => ({ + id, + orgId: "org-a", + name, + model: { + provider: "openai", + model: "gpt-4o", + messages: [{ role: "system", content: ON_PLATFORM }], + }, + voice: { provider: "11labs", voiceId: "burt" }, +}); +const UUID_NEW = "22222222-2222-4222-8222-222222222222"; + +async function engineRun( + root: string, + args: string[], + env: NodeJS.ProcessEnv, +): Promise<{ code: number | null; out: string; requests: string[] }> { + const requests: string[] = []; + const server = createServer((req, res) => { + requests.push(`${req.method} ${req.url}`); + res.writeHead(200, { "Content-Type": "application/json" }); + res.end( + JSON.stringify( + req.url?.startsWith("/assistant") + ? [ASSISTANT(UUID, "Intake"), ASSISTANT(UUID_NEW, "Second")] + : [], + ), + ); + }); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const { port } = server.address() as AddressInfo; + if (!existsSync(join(root, "src"))) { + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + } + put(root, `.env.${ORG}`, "VAPI_TOKEN=fake-token-not-used\n"); + const childEnv: NodeJS.ProcessEnv = { + ...process.env, + VAPI_BASE_URL: `http://127.0.0.1:${port}`, + CI: "", + GITHUB_ACTIONS: "", + VAPI_GITOPS_OLD_LAYOUT_NOTICE: "", + ...env, + }; + try { + return await new Promise((resolve) => { + const child = spawn(process.execPath, ["--import", "tsx", ...args], { + cwd: root, + env: childEnv, + }); + let out = ""; + child.stdout.on("data", (chunk) => (out += chunk)); + child.stderr.on("data", (chunk) => (out += chunk)); + child.on("close", (code) => resolve({ code, out, requests })); + }); + } finally { + await new Promise((resolve) => server.close(resolve)); + } +} + +const count = (text: string, needle: string) => text.split(needle).length - 1; + +test("pull leaves an old repository where it is and keeps every mapping, on a person's machine and in CI", async () => { + for (const env of [LOCAL, CI]) { + const root = oldRepo(); + try { + shippedWorkflows(root); + const first = await engineRun(root, ["src/pull.ts", ORG, "--force"], env); + const second = await engineRun( + root, + ["src/pull.ts", ORG, "--force"], + env, + ); + const state = JSON.parse(layout(root).oldState ?? "{}"); + assert.deepEqual( + { + codes: [first.code, second.code], + told: [ + count(first.out, OLD_LAYOUT_NOTICE), + count(second.out, OLD_LAYOUT_NOTICE), + ], + moved: count(first.out + second.out, "📦 Moved"), + pin: [layout(root).oldPin, layout(root).pin], + // The tracked resource kept its UUID; the new one was added beside it. + tracked: state.assistants?.intake, + uuids: Object.values( + (state.assistants ?? {}) as Record, + ) + .map((entry) => entry.uuid) + .sort(), + // Nothing of the engine's is written under state/, baselines included. + stateFolder: existsSync(join(root, "state")), + newBaseline: existsSync( + join(root, ".vapi-state-hash", ORG, UUID_NEW), + ), + }, + { + codes: [0, 0], + told: [1, 1], + moved: 0, + pin: [PIN, undefined], + tracked: { uuid: UUID }, + uuids: [UUID, UUID_NEW], + stateFolder: false, + newBaseline: true, + }, + first.out + second.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } + } +}); + +test("pull keeps an old copy of the state file identical to the one in state/", async () => { + const root = oldRepo(); + try { + put(root, `state/${ORG}/state.json`, STATE); + const run = await engineRun(root, ["src/pull.ts", ORG, "--force"], LOCAL); + const after = layout(root); + assert.deepEqual( + [ + run.code, + after.oldState === after.state, + Object.keys(JSON.parse(after.state ?? "{}").assistants ?? {}).length, + ], + [0, true, 2], + run.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("pull stops before any request when the two state files disagree", async () => { + const root = oldRepo(); + try { + put(root, `state/${ORG}/state.json`, '{"assistants":{}}\n'); + const run = await engineRun(root, ["src/pull.ts", ORG, "--force"], LOCAL); + assert.deepEqual( + [ + run.code === 0, + run.requests, + /both exist and disagree/.test(run.out), + layout(root).oldState, + layout(root).state, + ], + [false, [], true, STATE, '{"assistants":{}}\n'], + run.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a dry-run push changes nothing", async () => { + const root = oldRepo(); + try { + await engineRun(root, ["src/push.ts", ORG, "--dry-run"], LOCAL); + assert.deepEqual(layout(root), OLD); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a baseline is read from the old folder, where an old repository keeps it", async () => { + const root = oldRepo(); + try { + put( + root, + "probe.ts", + `import { readBaseline } from "./src/hash-store.ts";\nconsole.log("baseline=" + readBaseline("${ORG}", "${UUID}"));\n`, + ); + const run = await engineRun(root, ["probe.ts"], LOCAL); + assert.deepEqual( + [ + run.out.includes("baseline=baseline-hash"), + existsSync(join(root, ".vapi-state-hash", ORG, UUID)), + ], + [true, true], + run.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +// ── A file pull has no baseline for ────────────────────────────────────── +// +// With no baseline and nothing changed in git, pull has to pick between the +// file and the platform's copy. It keeps the file unless this machine's +// engine has saved state since the file was last written. It used to read +// that from the state file's timestamp, which in a fresh clone is only the +// order git wrote the files in: state at the root is written before +// resources/ and state//state.json after it. + +const LOCAL_EDIT = "Edited here, not on the platform yet."; +const intakeFile = (prompt: string) => + "---\nname: Intake\nmodel:\n provider: openai\n model: gpt-4o\nvoice:\n provider: 11labs\n voiceId: burt\n---\n\n" + + prompt + + "\n"; + +for (const where of ["at the root", "in state/"] as const) { + test(`with state ${where}, pull keeps a file it has no baseline for until this machine has saved state after it`, async () => { + const root = emptyRepo({ + [where === "at the root" + ? `.vapi-state.${ORG}.json` + : `state/${ORG}/state.json`]: STATE, + }); + const file = join(root, `resources/${ORG}/assistants/intake.md`); + const kept = () => readFileSync(file, "utf8").includes(LOCAL_EDIT); + try { + put( + root, + `resources/${ORG}/assistants/intake.md`, + intakeFile(LOCAL_EDIT), + ); + // Written long before the state file, as a checkout may leave it. + utimesSync(file, new Date("2020-01-01"), new Date("2020-01-01")); + const first = await engineRun(root, ["src/pull.ts", ORG], LOCAL); + const afterFirst = kept(); + // Edited again after the engine saved state: still the person's. + const later = new Date(Date.now() + 60_000); + utimesSync(file, later, later); + const second = await engineRun(root, ["src/pull.ts", ORG], LOCAL); + const afterSecond = kept(); + // Untouched since the engine last saved state here: the platform's copy. + utimesSync(file, new Date("2020-01-01"), new Date("2020-01-01")); + const third = await engineRun(root, ["src/pull.ts", ORG], LOCAL); + assert.deepEqual( + { + codes: [first.code, second.code, third.code], + "no save here yet": afterFirst, + "written after the last save": afterSecond, + "older than the last save": kept(), + platform: readFileSync(file, "utf8").includes(ON_PLATFORM), + }, + { + codes: [0, 0, 0], + "no save here yet": true, + "written after the last save": true, + "older than the last save": false, + platform: true, + }, + first.out + second.out + third.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); +} diff --git a/tests/state-merge.test.ts b/tests/state-merge.test.ts index f3dd643..8bd43fe 100644 --- a/tests/state-merge.test.ts +++ b/tests/state-merge.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { mergeScoped, type TouchedSets } from "../src/state-merge.ts"; diff --git a/tests/state-migration.test.ts b/tests/state-migration.test.ts index ea8c219..1cc7f08 100644 --- a/tests/state-migration.test.ts +++ b/tests/state-migration.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { @@ -11,7 +12,7 @@ import type { ResourceState } from "../src/types.ts"; // Stack F — state schema migration coverage. // // Each state value is a ResourceState — a pure `{ uuid }`. Drift baselines -// moved to the per-developer hash store (.vapi-state-hash/), so the helpers +// moved to the per-developer hash store (state//local/baselines/), so the helpers // must strip any legacy hash/timestamp field rather than carry it forward: // saveState must never re-emit one. These specs pin the behavior of the public // helpers without importing the full state.ts module (which loads config.ts diff --git a/tests/state-move-second-round.test.ts b/tests/state-move-second-round.test.ts new file mode 100644 index 0000000..592b6a0 --- /dev/null +++ b/tests/state-move-second-round.test.ts @@ -0,0 +1,311 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawn, spawnSync } from "node:child_process"; +import { + chmodSync, + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { + commitStepRead, + stateFileLegacyPath, + stateFilePath, + stateLayoutPrepare, +} from "../src/state-paths.ts"; + +// Three things a repository that worked before state/ existed could lose once +// its state was in state//. Each was first seen end to end, in a +// pipeline where every CI run was green. +// +// 1. A CI runner's fresh clone. With no baselines and a clean git status, +// pull keeps a file only when it is newer than the state file. Git writes +// a checkout in path order: ".vapi-state..json" comes before +// "resources/", "state//state.json" comes after it. So on main a +// fresh clone keeps every file, and after the move it overwrites every +// file with the platform's copy. A change merged to git and applied by CI +// ("apply on merge") never reaches the platform, and the commit step then +// commits the overwritten file, undoing the merge. +// 2. The commit-step reader counts any "git add ." or "git add -A" in the +// workflow text as staging the whole repository, whatever directory it +// runs in and whether it runs at all. +// 3. With no workflow that can commit and no promotion.yml, the first command +// on a person's machine moves state by itself. A pipeline outside GitHub +// Actions that stages .vapi-state.*.json then never commits state again. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); +const ORG = "dev"; +const UUID = "11111111-1111-4111-8111-111111111111"; +const STATE = + JSON.stringify({ assistants: { riley: { uuid: UUID } } }, null, 2) + "\n"; +const GIT_ENV = { + ...process.env, + GIT_CONFIG_GLOBAL: "/dev/null", + GIT_CONFIG_NOSYSTEM: "1", + GIT_AUTHOR_NAME: "t", + GIT_AUTHOR_EMAIL: "t@example.invalid", + GIT_COMMITTER_NAME: "t", + GIT_COMMITTER_EMAIL: "t@example.invalid", +}; +const git = (cwd: string, ...args: string[]): string => + execFileSync("git", args, { cwd, env: GIT_ENV, encoding: "utf8" }); + +function put(root: string, path: string, content: string): void { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); + if (path.endsWith(".sh")) chmodSync(join(root, path), 0o755); +} + +// ── 1. A merged change in a fresh clone ────────────────────────────────── + +const MERGED = "Merged in git, not on the platform yet."; +const ON_PLATFORM = "What the platform holds."; +const rileyFile = (prompt: string): string => + "---\nname: Riley\nmodel:\n provider: openai\n model: gpt-4o\n---\n\n" + + prompt + + "\n"; + +// What a CI runner has: a clone of the committed repository and nothing else. +function freshClone(layout: "root" | "folder"): { + root: string; + drop: () => void; +} { + const source = mkdtempSync(join(tmpdir(), "fresh-clone-src-")); + const root = mkdtempSync(join(tmpdir(), "fresh-clone-")); + cpSync(join(REPO, "src"), join(source, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(source, "package.json")); + put( + source, + ".gitignore", + "node_modules\nstate/*/local/\n.vapi-state-hash/\n", + ); + put(source, "resources/dev/assistants/riley.md", rileyFile(MERGED)); + put( + source, + layout === "root" ? ".vapi-state.dev.json" : "state/dev/state.json", + STATE, + ); + git(source, "init", "-q", "-b", "main"); + git(source, "add", "-A"); + git(source, "commit", "-q", "-m", "a merged change"); + rmSync(root, { recursive: true, force: true }); + git(tmpdir(), "clone", "-q", source, root); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + return { + root, + drop: () => { + rmSync(source, { recursive: true, force: true }); + rmSync(root, { recursive: true, force: true }); + }, + }; +} + +async function pullInFreshClone(layout: "root" | "folder"): Promise { + const server = createServer((request, response) => { + response.setHeader("content-type", "application/json"); + response.end( + JSON.stringify( + (request.url ?? "").startsWith("/assistant") + ? [ + { + id: UUID, + orgId: "org-test", + name: "Riley", + model: { + provider: "openai", + model: "gpt-4o", + messages: [{ role: "system", content: ON_PLATFORM }], + }, + }, + ] + : [], + ), + ); + }); + await new Promise((done) => server.listen(0, "127.0.0.1", done)); + const { root, drop } = freshClone(layout); + try { + const child = spawn( + process.execPath, + ["--import", "tsx", "src/pull-cmd.ts", ORG], + { + cwd: root, + stdio: ["ignore", "pipe", "pipe"], + env: { + ...process.env, + CI: "true", + VAPI_PRIVATE_API_KEY: "test-key", + VAPI_BASE_URL: + "http://127.0.0.1:" + (server.address() as AddressInfo).port, + VAPI_GITOPS_ORG_PIN: "off", + }, + }, + ); + let out = ""; + child.stdout.on("data", (chunk) => (out += String(chunk))); + child.stderr.on("data", (chunk) => (out += String(chunk))); + const code = await new Promise((done) => + child.on("close", done), + ); + assert.equal(code, 0, out); + return readFileSync( + join(root, "resources/dev/assistants/riley.md"), + "utf8", + ); + } finally { + drop(); + await new Promise((done) => server.close(done)); + } +} + +test("pull in a fresh clone keeps a merged change, wherever the state file is", async () => { + const kept = { + "state at the root": (await pullInFreshClone("root")).includes(MERGED), + "state in state/dev/": (await pullInFreshClone("folder")).includes(MERGED), + }; + assert.deepEqual(kept, { + "state at the root": true, + "state in state/dev/": true, + }); +}); + +// ── 2. A git add that does not stage state/ ────────────────────────────── + +function workflow(run: string[], extraJob: string[] = []): string { + return [ + "name: Promotion", + "on: push", + "permissions:", + " contents: write", + "jobs:", + " promote:", + " runs-on: ubuntu-latest", + " steps:", + " - run: npm run promote -- --all --apply", + " - run: |", + ...run.map((line) => " " + line), + ...extraJob, + "", + ].join("\n"); +} + +const TAIL = [ + "if git diff --cached --quiet; then exit 0; fi", + 'git commit -q -m "chore: record promoted Vapi state"', +]; +const HELPER = + "#!/bin/bash\ngit add -A -- ':(glob).vapi-state.*.json' 2>/dev/null || true\ngit add -A -- resources\n"; + +const STEPS: Record = { + "git add . after cd resources": { + run: [ + "git add .vapi-state.*.json 2>/dev/null || true", + "cd resources && git add . && cd ..", + ...TAIL, + ], + }, + "git add -A in another job's folder": { + run: ["./scripts/stage-state.sh", ...TAIL], + extraJob: [ + " docs:", + " runs-on: ubuntu-latest", + " steps:", + " - run: cd site && git init -q && git add -A && git commit -q -m docs", + ], + }, + "git add -A -- state inside an echo": { + run: [ + 'echo "state is staged by the helper, not by: git add -A -- state"', + "./scripts/stage-state.sh", + ...TAIL, + ], + }, +}; + +// Run the commit step for real, after a run changed state/dev/state.json, and +// report whether the commit it makes holds the new state. +function stepCommitsStateFolder(run: string[]): boolean { + const root = mkdtempSync(join(tmpdir(), "commit-step-")); + try { + put(root, "state/dev/state.json", STATE); + put(root, "resources/dev/assistants/riley.md", rileyFile("one")); + put(root, "scripts/stage-state.sh", HELPER); + git(root, "init", "-q", "-b", "main"); + git(root, "add", "-A"); + git(root, "commit", "-q", "-m", "init"); + const next = STATE.replace(UUID, "22222222-2222-4222-8222-222222222222"); + put(root, "state/dev/state.json", next); + put(root, "resources/dev/assistants/riley.md", rileyFile("two")); + spawnSync("bash", ["-eo", "pipefail", "-c", run.join("\n")], { + cwd: root, + env: GIT_ENV, + }); + return git(root, "show", "HEAD:state/dev/state.json") === next; + } finally { + rmSync(root, { recursive: true, force: true }); + } +} + +test("a git add that leaves state/ out is not read as staging state/", () => { + const seen: Record = {}; + const expected: typeof seen = {}; + for (const [name, step] of Object.entries(STEPS)) { + const root = mkdtempSync(join(tmpdir(), "commit-step-read-")); + try { + put(root, ".vapi-state.dev.json", STATE); + put(root, "promotion.yml", "version: 1\n"); + put( + root, + ".github/workflows/promotion.yml", + workflow(step.run, step.extraJob), + ); + const read = commitStepRead(root, {}).kind; + seen[name] = { + commitsState: stepCommitsStateFolder(step.run), + readAs: read === "seen" ? "seen" : "not seen", + }; + expected[name] = { commitsState: false, readAs: "not seen" }; + } finally { + rmSync(root, { recursive: true, force: true }); + } + } + assert.deepEqual(seen, expected); +}); + +// ── 3. A pipeline the engine has no file for ───────────────────────────── + +test("with nothing seen to stage state/, a command that is not migrate leaves committed state where it is", () => { + const root = mkdtempSync(join(tmpdir(), "no-workflow-")); + try { + // An apply-on-merge job in another CI system: no .github/workflows, no + // promotion.yml, and a script that stages .vapi-state.*.json. + put(root, ".vapi-state.dev.json", STATE); + put( + root, + ".gitlab-ci.yml", + "deploy:\n script:\n - npm run apply -- dev\n - ./scripts/commit-state.sh\n", + ); + put(root, "scripts/commit-state.sh", HELPER); + stateLayoutPrepare(root, ORG, {}); + assert.deepEqual( + { + root: existsSync(stateFileLegacyPath(root, ORG)), + folder: existsSync(stateFilePath(root, ORG)), + }, + { root: true, folder: false }, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/tests/state-records-third-round.test.ts b/tests/state-records-third-round.test.ts new file mode 100644 index 0000000..8379d68 --- /dev/null +++ b/tests/state-records-third-round.test.ts @@ -0,0 +1,210 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, spawn } from "node:child_process"; +import { + cpSync, + mkdirSync, + mkdtempSync, + readFileSync, + renameSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; + +// Pull keeps a committed file it has no baseline for (a fresh clone, or a +// change that arrived through git and is not applied yet) only while git +// reports nothing changed under resources//. In the older layout the +// engine keeps files of its own in that folder, and none of them is a +// person's edit: +// +// resources//.vapi-org.json shown as deleted between migrate and its commit +// +// If pull counted one as a local edit, the keep rule would be off and pull +// would overwrite the committed change with the platform's copy. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); +const ORG = "dev"; +const UUID = "11111111-1111-4111-8111-111111111111"; +const STATE = + JSON.stringify({ assistants: { riley: { uuid: UUID } } }, null, 2) + "\n"; +const GIT_ENV = { + ...process.env, + GIT_CONFIG_GLOBAL: "/dev/null", + GIT_CONFIG_NOSYSTEM: "1", + GIT_AUTHOR_NAME: "t", + GIT_AUTHOR_EMAIL: "t@example.invalid", + GIT_COMMITTER_NAME: "t", + GIT_COMMITTER_EMAIL: "t@example.invalid", +}; +const git = (cwd: string, ...args: string[]): string => + execFileSync("git", args, { cwd, env: GIT_ENV, encoding: "utf8" }); + +function put(root: string, path: string, content: string): void { + mkdirSync(dirname(join(root, path)), { recursive: true }); + writeFileSync(join(root, path), content); +} + +const MERGED = "Merged in git, not on the platform yet."; +const ON_PLATFORM = "What the platform holds."; +const rileyFile = (prompt: string): string => + "---\nname: Riley\nmodel:\n provider: openai\n model: gpt-4o\n---\n\n" + + prompt + + "\n"; + +interface Clone { + root: string; + drop: () => void; +} + +// A clone of the committed repository, with no baselines: what a teammate or +// a CI runner starts from. committed holds extra files in the first commit. +function freshClone( + layout: "root" | "folder", + committed: Record = {}, +): Clone { + const source = mkdtempSync(join(tmpdir(), "records-src-")); + const root = mkdtempSync(join(tmpdir(), "records-")); + cpSync(join(REPO, "src"), join(source, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(source, "package.json")); + put( + source, + ".gitignore", + "node_modules\nstate/*/local/\n.vapi-state-hash/\n", + ); + put(source, "resources/dev/assistants/riley.md", rileyFile(MERGED)); + put( + source, + layout === "root" ? ".vapi-state.dev.json" : "state/dev/state.json", + STATE, + ); + for (const [path, content] of Object.entries(committed)) + put(source, path, content); + git(source, "init", "-q", "-b", "main"); + git(source, "add", "-A"); + git(source, "commit", "-q", "-m", "a merged change"); + rmSync(root, { recursive: true, force: true }); + git(tmpdir(), "clone", "-q", source, root); + symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"), "dir"); + return { + root, + drop: () => { + rmSync(source, { recursive: true, force: true }); + rmSync(root, { recursive: true, force: true }); + }, + }; +} + +// Run pull on a person's machine and return the resource file afterwards. +async function pullKeepsMerged( + clone: Clone, + before: (root: string) => void, +): Promise { + const server = createServer((request, response) => { + response.setHeader("content-type", "application/json"); + response.end( + JSON.stringify( + (request.url ?? "").startsWith("/assistant") + ? [ + { + id: UUID, + orgId: "org-test", + name: "Riley", + model: { + provider: "openai", + model: "gpt-4o", + messages: [{ role: "system", content: ON_PLATFORM }], + }, + }, + ] + : [], + ), + ); + }); + await new Promise((done) => server.listen(0, "127.0.0.1", done)); + try { + before(clone.root); + const env: NodeJS.ProcessEnv = { + ...process.env, + VAPI_PRIVATE_API_KEY: "test-key", + VAPI_BASE_URL: + "http://127.0.0.1:" + (server.address() as AddressInfo).port, + VAPI_GITOPS_ORG_PIN: "off", + }; + delete env.CI; + delete env.GITHUB_ACTIONS; + const child = spawn( + process.execPath, + ["--import", "tsx", "src/pull-cmd.ts", ORG], + { cwd: clone.root, stdio: ["ignore", "pipe", "pipe"], env }, + ); + let out = ""; + child.stdout.on("data", (chunk) => (out += String(chunk))); + child.stderr.on("data", (chunk) => (out += String(chunk))); + const code = await new Promise((done) => + child.on("close", done), + ); + assert.equal(code, 0, out); + return readFileSync( + join(clone.root, "resources/dev/assistants/riley.md"), + "utf8", + ).includes(MERGED); + } finally { + clone.drop(); + await new Promise((done) => server.close(done)); + } +} + +const PIN = "resources/dev/.vapi-org.json"; + +test("control: with nothing uncommitted, pull keeps a merged change in both layouts", async () => { + assert.deepEqual( + { + root: await pullKeepsMerged(freshClone("root"), () => {}), + folder: await pullKeepsMerged(freshClone("folder"), () => {}), + }, + { root: true, folder: true }, + ); +}); + +test("older layout: an org pin the engine wrote, not committed yet, is not a local edit", async () => { + // A first pull with a real key writes the pin. Until it is committed git + // shows it as untracked. + const kept = await pullKeepsMerged(freshClone("root"), (root) => + put(root, PIN, '{\n "orgId": "org-test"\n}\n'), + ); + assert.equal(kept, true, "pull overwrote the merged change"); +}); + +test("unchanged: a person's own uncommitted file in that folder still switches the keep rule off", async () => { + // Only the engine's files are left out. Anything else under + // resources// counts as before, .vapi-ignore included. + const kept = await pullKeepsMerged(freshClone("root"), (root) => + put(root, "resources/dev/.vapi-ignore", "assistants/scratch-*\n"), + ); + assert.equal(kept, false); +}); + +test("after migrate, before the move is committed, the old pin shown as deleted is not a local edit", async () => { + // The upgrade guide: "Pull does nothing differently because of it." + // What migrate leaves until the commit: the state file and the pin gone + // from their old places, and state/dev/ untracked. + const kept = await pullKeepsMerged( + freshClone("root", { [PIN]: '{\n "orgId": "org-test"\n}\n' }), + (root) => { + mkdirSync(join(root, "state/dev"), { recursive: true }); + renameSync( + join(root, ".vapi-state.dev.json"), + join(root, "state/dev/state.json"), + ); + renameSync(join(root, PIN), join(root, "state/dev/org.json")); + }, + ); + assert.equal(kept, true, "pull overwrote the merged change"); +}); diff --git a/tests/stop-report.test.ts b/tests/stop-report.test.ts index 37bca6e..fcce685 100644 --- a/tests/stop-report.test.ts +++ b/tests/stop-report.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { diff --git a/tests/tool-assistant-cycle.test.ts b/tests/tool-assistant-cycle.test.ts index c0c5ee4..3dc5fe0 100644 --- a/tests/tool-assistant-cycle.test.ts +++ b/tests/tool-assistant-cycle.test.ts @@ -1,5 +1,6 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; -import test, { after } from "node:test"; +import test from "node:test"; // ───────────────────────────────────────────────────────────────────────────── // Tools are applied before assistants because assistants reference tools. But a @@ -26,7 +27,6 @@ const { updateToolAssistantRefs, } = await import("../src/push.ts"); -import { deleteBaseline } from "../src/hash-store.ts"; import type { ResourceFile, StateFile } from "../src/types.ts"; const UUID = "8f14e45f-ceea-467a-9f1b-1a1b2c3d4e5f"; @@ -34,7 +34,8 @@ const UUID = "8f14e45f-ceea-467a-9f1b-1a1b2c3d4e5f"; // updateToolAssistantRefs records a drift baseline for every PATCH it sends, and // the hash store resolves beside src/ — not under a temp dir — so remove the // one these tests write rather than leave it in the developer's real store. -after(() => deleteBaseline("test-fixture-org", UUID)); +// The push under test records a baseline in the temporary directory the +// engine works in under test (tests/no-vapi-api.ts). test("an unresolved assistant destination drops the whole destinations key", async () => { // Unresolved = resolution left the slug exactly as written, because the diff --git a/tests/user-agent-coverage.test.ts b/tests/user-agent-coverage.test.ts index 72ea69d..4ce6921 100644 --- a/tests/user-agent-coverage.test.ts +++ b/tests/user-agent-coverage.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { readdirSync, readFileSync } from "node:fs"; import { createServer } from "node:http"; @@ -74,7 +75,9 @@ test("api.ts requests carry the command's User-Agent", async () => { delete process.env.GITHUB_ACTIONS; try { const { vapiGet } = await import("../src/api.ts"); - const { userAgentGet, vapiClientGet } = await import("../src/user-agent.ts"); + const { userAgentGet, vapiClientGet } = await import( + "../src/user-agent.ts" + ); await vapiGet("/assistant"); assert.deepEqual(seen, [userAgentGet()]); assert.match(seen[0] ?? "", /^vapi-gitops-apply\/[^ ]+$/); diff --git a/tests/user-agent.test.ts b/tests/user-agent.test.ts index d060e24..b564c11 100644 --- a/tests/user-agent.test.ts +++ b/tests/user-agent.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; import { createServer } from "node:http"; diff --git a/tests/validate-refs.test.ts b/tests/validate-refs.test.ts index 3d2d5d0..29dbb5d 100644 --- a/tests/validate-refs.test.ts +++ b/tests/validate-refs.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import type { LoadedResources, ResourceType, StateFile } from "../src/types.ts"; diff --git a/tests/validate.test.ts b/tests/validate.test.ts index 762c090..c6ffc4b 100644 --- a/tests/validate.test.ts +++ b/tests/validate.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; diff --git a/tests/vapi-checks-workflow.test.ts b/tests/vapi-checks-workflow.test.ts index 1882b90..f35f1e9 100644 --- a/tests/vapi-checks-workflow.test.ts +++ b/tests/vapi-checks-workflow.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync, spawnSync } from "node:child_process"; import { diff --git a/tests/vapi-ignore-push.test.ts b/tests/vapi-ignore-push.test.ts index 79df1e2..5a9a187 100644 --- a/tests/vapi-ignore-push.test.ts +++ b/tests/vapi-ignore-push.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -13,6 +14,7 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { Worker } from "node:worker_threads"; +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; // ───────────────────────────────────────────────────────────────────────────── // Spec for `.vapi-ignore` symmetry on push + apply. @@ -151,7 +153,7 @@ async function setupFixture(init: FixtureInit = {}): Promise { // engine treats it as a fresh org. if (init.state !== null && init.state !== undefined) { writeFileSync( - join(dir, `.vapi-state.${env}.json`), + stateFixturePath(dir, env), JSON.stringify(init.state, null, 2), ); } diff --git a/tests/version-metadata.test.ts b/tests/version-metadata.test.ts index 815baaf..2d20013 100644 --- a/tests/version-metadata.test.ts +++ b/tests/version-metadata.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import test from "node:test"; import { diff --git a/vapi-checks.example.yml b/vapi-checks.example.yml index 5c50b9d..8ff0617 100644 --- a/vapi-checks.example.yml +++ b/vapi-checks.example.yml @@ -25,7 +25,7 @@ checks: simulations: [] # optional: extra resources/example-dev/simulations/tests/ # A check that runs in a separate CI org. Credentials are bound by name, - # the same way promotion.yml binds them, using .vapi-state..json. + # the same way promotion.yml binds them, using state//state.json. # staging-core: # org: example-staging # runOrg: example-ci