Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions .conductor/setup.sh
Original file line number Diff line number Diff line change
Expand Up @@ -98,14 +98,15 @@ done
shopt -u nullglob

# --- 4. Copy state files ----------------------------------------------------
# .vapi-state.<org>.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/<org>/ is tracked in git (worktrees inherit it automatically), but
# copy any untracked variants too, and the root-level .vapi-state.<org>.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

Expand Down Expand Up @@ -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.<org>.json)
npm run pull # sync state from Vapi (writes state/<org>/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
Expand Down
22 changes: 22 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 12 additions & 1 deletion .github/workflows/promotion.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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/<org>/local/ is gitignored).
# A repository that has not moved its state there yet still has
# .vapi-state.<org>.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
Expand Down
18 changes: 12 additions & 6 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/<org>/ and is committed (see state/README.md),
# except what each machine keeps for itself under state/<org>/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/<org>/<uuid>).
# 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
Expand Down
23 changes: 17 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,20 +110,23 @@ wizard needs a terminal. Instead:
- Authoring from scratch → `npm run setup -- <org> --resources none` (state only, no files).
Add `--region eu` for EU orgs if auto-detection picks the wrong one.
4. Verify: `npm run validate -- <org>` passes, and `resources/<org>/` plus
`.vapi-state.<org>.json` exist.
5. Commit `resources/<org>/` (including `.vapi-org.json`) and `.vapi-state.<org>.json`. Never commit `.env.<org>`.
`state/<org>/state.json` exist.
5. Commit `resources/<org>/` and `state/<org>/`. Never commit `.env.<org>`.

`resources/<org>/` is hand-written: edit it. `state/<org>/` 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/<org>/
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>/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
work around it — run `npm run pull -- <org>`, or ask the human.

**Working in an existing repository for the first time?** Run a plain
`npm run pull -- <org>` before your first deploy. It seeds your local drift
baselines (`.vapi-state-hash/`, which is per-developer and gitignored);
baselines (`state/<org>/local/baselines/`, which is per-developer and gitignored);
until then, the engine can't tell your edits from dashboard edits as
precisely.

Expand All @@ -145,7 +148,7 @@ precisely.
`.env.<org>`, run `VAPI_PRIVATE_API_KEY=validate-only npm run validate -- <org>`;
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>/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**
Expand All @@ -155,7 +158,7 @@ precisely.
scoped to files: `npm run apply -- <org> resources/<org>/assistants/my-agent.md`.
6. **Verify** with the human's agreement: `npm run call -- <org> -a <name>` or
`npm run sim -- <org> --suite <name> --target <name>`.
7. **Commit** the resource files and `.vapi-state.<org>.json`.
7. **Commit** the resource files and `state/<org>/`.

**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
Expand Down Expand Up @@ -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 <changed files>` 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.
Expand Down
14 changes: 12 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <changed files>`, `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 <changed files>`, `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: …`).
Expand Down
27 changes: 17 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<org>/`; `none` only seeds `.vapi-state.<org>.json` (use when you'll author from scratch) |
| `--resources all\|none` | `all` | `all` downloads every resource into `resources/<org>/`; `none` only seeds `state/<org>/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/<org>/` or
`.vapi-state.<org>.json` already exists — use `npm run pull -- <org>` to refresh an existing org.
`state/<org>/state.json` already exists — use `npm run pull -- <org>` to refresh an existing org.

### 4. Make a change and deploy

Expand All @@ -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.
Expand All @@ -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.<org>.json` records which
- **The state file maps IDs to UUIDs.** `state/<org>/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.<org>` (gitignored) or
Expand All @@ -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/<org>/.vapi-org.json`. After
org a key belongs to records it in `state/<org>/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.
Expand All @@ -204,11 +204,15 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec

| Path | Committed? | What it is |
| --- | --- | --- |
| `resources/<org>/` | Yes | Your resources, and `.vapi-org.json`, the org the folder belongs to |
| `.vapi-state.<org>.json` | Yes | Name → UUID mappings for the org |
| `resources/<org>/` | Yes | Your resources. Hand-written: this is what you edit |
| `state/<org>/state.json` | Yes | Name → UUID mappings for the org |
| `state/<org>/org.json` | Yes | The Vapi org the folder belongs to |
| `state/<org>/local/` | No | This machine's baselines for detecting dashboard edits, and pre-deploy snapshots for `npm run rollback` |
| `.env.<org>` | **No** | API key and generated binding IDs |
| `.vapi-state-hash/` | No | Your local baseline for detecting dashboard edits |
| `.vapi-state.<org>.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).

Expand Down Expand Up @@ -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.

Expand All @@ -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.<org>.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
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ acknowledge the report and keep you updated as we investigate.
- **Never commit API keys.** Keys live in `.env.<org>` 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.<org>.json` maps
- **Committed state contains IDs, not secrets.** `state/<org>/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
Expand Down
Loading
Loading