From 8920e9d99f9e8e86403e61efda1fa4b739a39d93 Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Tue, 17 Nov 2026 13:17:07 -0800 Subject: [PATCH 01/10] feat(state): keep engine state in state// 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//. It now lives in state//: state.json and org.json are committed, local/baselines and local/snapshots stay on the machine. An older repository keeps working. Every command reads the old places. The next pull, push or apply on a person's machine moves the org, one rename per file, and prints one line. The move is held back in a CI run and while a workflow stages .vapi-state.*.json but not state/, because either would commit the old file's removal without the new file. The promotion workflow stages both places. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- .conductor/setup.sh | 13 +- .github/workflows/promotion.yml | 13 +- .gitignore | 16 +- examples/cross-org-promotion/README.md | 7 +- .../state.json.example} | 0 .../state.json.example} | 0 .../state.json.example} | 0 .../starter/state.json} | 0 src/api.ts | 8 +- src/apply.ts | 9 +- src/audit.ts | 4 +- src/call.ts | 5 +- src/check-build.ts | 5 +- src/check-select.ts | 1 + src/config.ts | 1 - src/drift.ts | 2 +- src/hash-store.ts | 31 +- src/interactive.ts | 7 +- src/migrate-cmd.ts | 14 +- src/migrate-hash-store.ts | 74 +- src/org-pin.ts | 39 +- src/promote-cmd.ts | 3 +- src/pull.ts | 17 +- src/push.ts | 14 +- src/rollback-cmd.ts | 11 +- src/setup-args.ts | 2 +- src/setup.ts | 23 +- src/sim.ts | 5 +- src/snapshot.ts | 31 +- src/state-paths.ts | 336 +++++++++ src/state.ts | 39 +- src/types.ts | 4 +- src/validate-cmd.ts | 10 +- state/README.md | 26 + tests/check-cmd.test.ts | 4 +- tests/check-select.test.ts | 2 + tests/cleanup-ignore.test.ts | 3 +- tests/cleanup-safety.test.ts | 3 +- tests/drift.test.ts | 2 +- tests/examples.test.ts | 2 +- .../parity/state.json} | 0 tests/new-file-gate.test.ts | 3 +- tests/org-pin.test.ts | 27 +- tests/promote-cmd.test.ts | 2 +- tests/promotion-gate.test.ts | 2 +- tests/promotion-workflow-commit.test.ts | 154 +++- tests/promotion.test.ts | 4 +- tests/pull-rename-preserves-filename.test.ts | 7 +- tests/pull-same-name-clobber.test.ts | 7 +- tests/push-dry-run.test.ts | 7 +- tests/push-stale-baseline-noop.test.ts | 5 +- tests/state-fixture.ts | 16 + tests/state-layout.test.ts | 681 ++++++++++++++++++ tests/state-migration.test.ts | 2 +- tests/vapi-ignore-push.test.ts | 3 +- vapi-checks.example.yml | 2 +- 56 files changed, 1510 insertions(+), 198 deletions(-) rename examples/cross-org-promotion/state/{.vapi-state.example-dev.json.example => example-dev/state.json.example} (100%) rename examples/cross-org-promotion/state/{.vapi-state.example-production.json.example => example-production/state.json.example} (100%) rename examples/cross-org-promotion/state/{.vapi-state.example-staging.json.example => example-staging/state.json.example} (100%) rename examples/starter/{.vapi-state.starter.json => state/starter/state.json} (100%) create mode 100644 src/state-paths.ts create mode 100644 state/README.md rename tests/fixtures/check-parity/{.vapi-state.parity.json => state/parity/state.json} (100%) create mode 100644 tests/state-fixture.ts create mode 100644 tests/state-layout.test.ts 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/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..7b5a5f6 100644 --- a/.gitignore +++ b/.gitignore @@ -23,13 +23,17 @@ 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 sat before state/ existed. The engine moves +# them on the next pull, push or apply; until then 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/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/src/api.ts b/src/api.ts index 6ea7e20..b841bd9 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) { diff --git a/src/apply.ts b/src/apply.ts index b50057f..5981108 100644 --- a/src/apply.ts +++ b/src/apply.ts @@ -3,6 +3,7 @@ import { dirname, join, resolve } from "path"; import { fileURLToPath } from "url"; import { parseAdoptArgs } from "./adopt.ts"; import { assertStateMigrated } from "./migrate-hash-store.ts"; +import { stateFileRead, stateLayoutPrepare } from "./state-paths.ts"; // Pins this command's User-Agent label for the pull and push it spawns. import "./user-agent.ts"; @@ -41,10 +42,12 @@ 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. + // Move an old-layout state file into state// once, here, and fail fast + // with one clear message if it is still in the legacy format, rather than + // letting the spawned pull/push subprocess surface either later. if (env && SLUG_RE.test(env)) { - assertStateMigrated(join(BASE_DIR, `.vapi-state.${env}.json`)); + for (const line of stateLayoutPrepare(BASE_DIR, env)) console.log(line); + 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/call.ts b/src/call.ts index 21304cb..4e316f0 100644 --- a/src/call.ts +++ b/src/call.ts @@ -5,6 +5,7 @@ import { createRequire } from "module"; import { dirname, join, resolve } from "path"; import * as readline from "readline"; import { fileURLToPath } from "url"; +import { stateFileLabel, stateFileRead } from "./state-paths.ts"; import type { Environment, StateFile } from "./types.ts"; import { userAgentGet, vapiClientGet } from "./user-agent.ts"; @@ -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-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/config.ts b/src/config.ts index 047960f..de8f23b 100644 --- a/src/config.ts +++ b/src/config.ts @@ -282,7 +282,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..23d27c1 100644 --- a/src/hash-store.ts +++ b/src/hash-store.ts @@ -1,7 +1,7 @@ // 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 +// in `state//local/baselines/` — 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. @@ -21,14 +21,13 @@ import { existsSync, mkdirSync, readFileSync } from "fs"; import { rename, writeFile } from "fs/promises"; import { dirname, join } from "path"; import { fileURLToPath } from "url"; +import { baselinesDir, baselinesLegacyDir } 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)), ".."); -// 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. @@ -39,7 +38,7 @@ function assertSafeUuid(uuid: string): void { } export function hashStoreDir(org: string): string { - return join(HASH_STORE_ROOT, org); + return baselinesDir(BASE_DIR, org); } function baselinePath(org: string, uuid: string): string { @@ -47,12 +46,23 @@ function baselinePath(org: string, uuid: string): string { return join(hashStoreDir(org), uuid); } +function baselineLegacyPath(org: string, uuid: string): string { + assertSafeUuid(uuid); + return join(baselinesLegacyDir(BASE_DIR, org), 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. +// +// A baseline written before state/ existed sits in .vapi-state-hash// +// until the next pull, push or apply moves the folder. Read it from there +// meanwhile, so a read-only command sees the same drift as before. export function readBaseline(org: string, uuid: string): string | undefined { - const path = baselinePath(org, uuid); - if (!existsSync(path)) return undefined; + const path = [baselinePath(org, uuid), baselineLegacyPath(org, uuid)].find( + (candidate) => existsSync(candidate), + ); + if (!path) return undefined; const contents = readFileSync(path, "utf-8").trim(); return contents.length > 0 ? contents : undefined; } @@ -77,8 +87,7 @@ 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 }); + await rm(baselinePath(org, uuid), { force: true }); + await rm(baselineLegacyPath(org, uuid), { force: true }); } diff --git a/src/interactive.ts b/src/interactive.ts index 67eb822..d0ac1fd 100644 --- a/src/interactive.ts +++ b/src/interactive.ts @@ -8,6 +8,7 @@ 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"; @@ -417,7 +418,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 +1086,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..81fe046 100644 --- a/src/migrate-cmd.ts +++ b/src/migrate-cmd.ts @@ -1,8 +1,8 @@ // 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). // @@ -16,7 +16,7 @@ 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", ); @@ -24,7 +24,7 @@ async function main(): Promise { 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,12 +39,12 @@ async function main(): Promise { `${status} — seeded ${org.seeded} baseline(s)` + (org.skipped > 0 ? `, ${org.skipped} already present` : ""), ); + for (const notice of org.notices) console.log(` ${notice}`); } 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.`, ); } diff --git a/src/migrate-hash-store.ts b/src/migrate-hash-store.ts index 94ce990..e1753e9 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,26 @@ // 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 { + stateFileRead, + stateLayoutPrepare, + 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,6 +35,7 @@ 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 + notices: string[]; // what moved into state//, or why it stayed } export interface MigrationResult { @@ -72,22 +80,11 @@ 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, ): Promise { + const stateFilePath = stateFileRead(baseDir, org); const raw = JSON.parse(readFileSync(stateFilePath, "utf-8")) as Record< string, unknown @@ -135,26 +132,35 @@ async function migrateOne( await rename(tmpPath, stateFilePath); } + // Slim first, in place, then move: each step leaves one complete state + // file. An explicit migrate moves state even in a CI run, because whoever + // runs it there commits the result; a workflow that would drop state/ from + // its commit still stops the move. + const notices = stateLayoutPrepare(baseDir, org, { + ...process.env, + CI: "", + GITHUB_ACTIONS: "", + }); return { org, - stateFile: basename(stateFilePath), + stateFile: relative(baseDir, stateFileRead(baseDir, org)), seeded, skipped, slimmed: needsSlim, + notices, }; } -// 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. export async function migrateAll( baseDir: string = BASE_DIR, ): Promise { - const files = discoverStateFiles(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)); } return { orgs }; } @@ -165,7 +171,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 +195,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..be3ed2f 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, 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,7 +135,7 @@ 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. @@ -149,21 +151,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 +180,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..dfd6564 100644 --- a/src/promote-cmd.ts +++ b/src/promote-cmd.ts @@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import type { CheckDefinition } from "./check-config.ts"; import type { OrgConnection } from "./org-connection.ts"; +import { stateFileRead } from "./state-paths.ts"; import { childRun, connectionLoad, tokensParse } from "./org-connection.ts"; import type { PromotionConfig, PromotionPipeline } from "./promotion.ts"; import type { PromotionGateResult } from "./promotion-gate.ts"; @@ -219,7 +220,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`, diff --git a/src/pull.ts b/src/pull.ts index 95a8c86..00c1a4d 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 { stateFileRead } 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({ @@ -969,7 +974,7 @@ export async function pullResourceType( join(dir, `${resourceId}.yaml`), ].find((p) => existsSync(p)); if (localFile) { - const stateFilePath = join(BASE_DIR, `.vapi-state.${VAPI_ENV}.json`); + const stateFilePath = stateFileRead(BASE_DIR, VAPI_ENV); if (existsSync(stateFilePath)) { const localMtime = statSync(localFile).mtimeMs; const stateMtime = statSync(stateFilePath).mtimeMs; @@ -1243,7 +1248,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 = diff --git a/src/push.ts b/src/push.ts index 75b1ce6..5edd085 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, @@ -83,7 +82,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 +1628,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 +2315,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..ed2886d 100644 --- a/src/rollback-cmd.ts +++ b/src/rollback-cmd.ts @@ -1,7 +1,7 @@ // 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. // @@ -12,8 +12,9 @@ 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 { 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)); @@ -72,7 +73,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"), ); @@ -152,7 +153,7 @@ async function main(): Promise { }); 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 +170,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..17d2a16 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 diff --git a/src/setup.ts b/src/setup.ts index 0050ad1..dcbff62 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -3,6 +3,12 @@ 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 { + stateFileLabel, + stateFileLegacyPath, + stateFileRead, + stateOrgDir, +} from "./state-paths.ts"; import { fileURLToPath } from "url"; import { API_KEY_VAR, @@ -290,14 +296,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,7 +417,7 @@ 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`)); @@ -421,7 +426,7 @@ async function runDirectSetup(options: DirectSetupOptions): Promise { // 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`, ); @@ -671,7 +676,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,7 +816,7 @@ 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")); @@ -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..3fbc4e5 100644 --- a/src/sim.ts +++ b/src/sim.ts @@ -16,6 +16,7 @@ import { type SimRunItemCounts, type 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 { @@ -113,10 +114,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..81c2241 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,19 @@ import { existsSync } from "fs"; import { mkdir, readdir, readFile, writeFile } from "fs/promises"; import { join } from "path"; +import { snapshotsDir, snapshotsLegacyDir } from "./state-paths.ts"; import { sortedKeysReplacer } from "./state-serialize.ts"; export function snapshotsRoot(baseDir: string, env: string): string { - return join(baseDir, `.vapi-state.${env}.snapshots`); + return snapshotsDir(baseDir, env); +} + +// Snapshots written before state/ existed stay readable until the next pull, +// push or apply moves them, so a rollback right after upgrading still works. +function snapshotRoots(baseDir: string, env: string): string[] { + return [snapshotsDir(baseDir, env), snapshotsLegacyDir(baseDir, env)].filter( + (root) => existsSync(root), + ); } let activeRunDir: string | null = null; @@ -79,13 +88,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 +106,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..b91f095 --- /dev/null +++ b/src/state-paths.ts @@ -0,0 +1,336 @@ +// 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) +// +// 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: it reads the old one, and moves it when that is safe. +// +// 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, +} from "fs"; +import { dirname, join } from "path"; + +export const STATE_DIR = "state"; + +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`); +} + +/** The state file as a person names it: its path from the repository root. */ +export function stateFileLabel(rootDir: string, org: string): string { + return existsSync(stateFilePath(rootDir, org)) || + !existsSync(stateFileLegacyPath(rootDir, org)) + ? `${STATE_DIR}/${org}/state.json` + : `.vapi-state.${org}.json`; +} + +function firstExisting(next: string, legacy: string): string { + return existsSync(next) || !existsSync(legacy) ? next : legacy; +} + +/** The state file to read: state//state.json, else the old root file. */ +export function stateFileRead(rootDir: string, org: string): string { + return firstExisting( + stateFilePath(rootDir, org), + stateFileLegacyPath(rootDir, org), + ); +} + +/** The org pin to read: state//org.json, else the old file in resources/. */ +export function orgPinFileRead(rootDir: string, org: string): string { + return firstExisting( + orgPinFilePath(rootDir, org), + orgPinFileLegacyPath(rootDir, org), + ); +} + +/** 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)); +} + +export type StateMoveBlocker = + | { kind: "workflow"; file: string } + | { kind: "ci" }; + +// A workflow that stages .vapi-state.*.json but not state/ would commit the +// old file's removal without the new one, so the UUID map would leave git. +function staleWorkflowFind(rootDir: string): string | undefined { + const dir = join(rootDir, ".github", "workflows"); + if (!existsSync(dir)) return undefined; + for (const name of readdirSync(dir).sort()) { + if (!/\.ya?ml$/.test(name)) continue; + const adds = readFileSync(join(dir, name), "utf8") + .split("\n") + .filter((line) => /\bgit add\b/.test(line) && !/^\s*#/.test(line)); + const stagesOld = adds.some((line) => line.includes(".vapi-state.")); + const stagesNew = adds.some((line) => + /(?/, except in a checkout that still follows the old layout. +function legacyLayoutKept( + rootDir: string, + org: string, + env: NodeJS.ProcessEnv, +): boolean { + if (existsSync(stateFilePath(rootDir, org))) return false; + if (existsSync(stateFileLegacyPath(rootDir, org))) return true; + return stateMoveBlocker(rootDir, env)?.kind === "workflow"; +} + +/** The state file to write. Call stateLayoutPrepare first in a command that writes. */ +export function stateFileWrite( + rootDir: string, + org: string, + env: NodeJS.ProcessEnv = process.env, +): string { + return legacyLayoutKept(rootDir, org, env) + ? stateFileLegacyPath(rootDir, org) + : stateFilePath(rootDir, org); +} + +/** The org pin to write: beside the state file, in whichever layout it uses. */ +export function orgPinFileWrite( + rootDir: string, + org: string, + env: NodeJS.ProcessEnv = process.env, +): string { + const next = orgPinFilePath(rootDir, org); + const legacy = orgPinFileLegacyPath(rootDir, org); + if (existsSync(next)) return next; + if (existsSync(legacy)) return legacy; + return legacyLayoutKept(rootDir, org, env) ? legacy : next; +} + +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; + } +} + +// 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/. + * They are gitignored in both places, so no workflow 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; +} + +/** + * Bring one org's engine files into state// when that is safe, before a + * command writes anything. Returns the lines to print. + * + * Each committed file moves by one rename, so the full state is always in + * exactly one of the two places. Throws StateLayoutError, before anything is + * read or changed, when both places hold a file and they disagree, or when a + * CI run would write state its workflow won't commit. + */ +export function stateLayoutPrepare( + rootDir: string, + org: string, + env: NodeJS.ProcessEnv = process.env, +): string[] { + const files = [ + { + 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`, + }, + ].filter((file) => existsSync(file.legacy)); + + for (const file of files) + if (existsSync(file.next) && !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}.`, + ); + + const notices: string[] = []; + const blocker = stateMoveBlocker(rootDir, env); + if (blocker?.kind === "workflow" && existsSync(stateFilePath(rootDir, org))) { + const problem = `${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so it won't commit ${STATE_DIR}/${org}/.`; + const fix = `Add \`git add -A -- ${STATE_DIR}\` to that step.`; + if (stateRunIsCi(env)) + throw new StateLayoutError( + `${problem}\n Stopped before reading or changing anything: UUIDs recorded by this run would be lost.\n ${fix}`, + ); + notices.push(`⚠️ ${problem} ${fix}`); + } + + const moved = stateLocalMove(rootDir, org); + // Same content in both places: an earlier move was cut short, or a merge + // brought the old file back unchanged. The old copy carries nothing. + for (const file of files.filter((entry) => existsSync(entry.next))) { + unlinkSync(file.legacy); + moved.push(file.legacyLabel); + } + const pending = files.filter((file) => !existsSync(file.next)); + const committedMoved = pending.length > 0 && !blocker; + if (committedMoved) + for (const file of pending) { + mkdirSync(dirname(file.next), { recursive: true }); + renameSync(file.legacy, file.next); + moved.push(file.legacyLabel); + } + if (moved.length > 0) + notices.push( + `📦 Moved ${moved.join(", ")} into ${STATE_DIR}/${org}/.` + + (moved.some((label) => !label.endsWith("/")) + ? " Commit the removal together with the new folder." + : ""), + ); + if (pending.length > 0 && blocker) { + const where = pending.map((file) => file.legacyLabel).join(" and "); + notices.push( + blocker.kind === "ci" + ? `ℹ️ ${where} stays where it is: a CI run never moves state. Run \`npm run migrate\` on your machine and commit the result to move it into ${STATE_DIR}/${org}/.` + : `⚠️ ${where} stays where it is: ${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/. Add \`git add -A -- ${STATE_DIR}\` to that step, then run \`npm run migrate\`.`, + ); + } + return notices; +} diff --git a/src/state.ts b/src/state.ts index 502e096..0e7581f 100644 --- a/src/state.ts +++ b/src/state.ts @@ -1,6 +1,13 @@ -import { existsSync, readFileSync } from "fs"; +import { existsSync, mkdirSync, readFileSync } from "fs"; import { rename, writeFile } from "fs/promises"; -import { STATE_FILE_PATH, VAPI_ENV } from "./config.ts"; +import { dirname } from "path"; +import { BASE_DIR, VAPI_ENV } from "./config.ts"; +import { assertStateMigrated } from "./migrate-hash-store.ts"; +import { + stateFileRead, + stateFileWrite, + stateLayoutPrepare, +} from "./state-paths.ts"; import { asResourceState, hashPayload, @@ -63,22 +70,36 @@ export function createEmptyState(): StateFile { }; } +/** + * Run at the start of a command that writes state, before any request: move + * the old layout into state// when that is safe (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 it leaves the old layout where it is. + if (!options.dryRun) + for (const line of stateLayoutPrepare(BASE_DIR, VAPI_ENV)) + console.log(line); + 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 +141,10 @@ 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); + 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/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..ab27bef --- /dev/null +++ b/state/README.md @@ -0,0 +1,26 @@ +# 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 | + +## 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. +- **`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 still reads them there. The next `npm run pull`, `npm run push` or `npm run apply` on your machine moves them here and says so in one line. Commit the removal of the old file together with the new folder. `npm run migrate` moves every org at once. + +A CI run never moves them, because only a workflow that commits both places can record the move. See [Upgrading from an older version](../docs/guides/commands.md#upgrading-from-an-older-version). diff --git a/tests/check-cmd.test.ts b/tests/check-cmd.test.ts index 1fb8f50..57b1fd3 100644 --- a/tests/check-cmd.test.ts +++ b/tests/check-cmd.test.ts @@ -130,12 +130,12 @@ 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, - result.out.includes("⚠️ no .vapi-state.parity.json"), + result.out.includes("⚠️ no state/parity/state.json"), existsSync(join(root, "tmp")), ], [0, true, false], diff --git a/tests/check-select.test.ts b/tests/check-select.test.ts index 3647e41..6d147b2 100644 --- a/tests/check-select.test.ts +++ b/tests/check-select.test.ts @@ -26,6 +26,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/cleanup-ignore.test.ts b/tests/cleanup-ignore.test.ts index f93e301..930254a 100644 --- a/tests/cleanup-ignore.test.ts +++ b/tests/cleanup-ignore.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; import { @@ -66,7 +67,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 }); diff --git a/tests/cleanup-safety.test.ts b/tests/cleanup-safety.test.ts index 08749c9..7a37f56 100644 --- a/tests/cleanup-safety.test.ts +++ b/tests/cleanup-safety.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -51,7 +52,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/drift.test.ts b/tests/drift.test.ts index ae90704..f95b558 100644 --- a/tests/drift.test.ts +++ b/tests/drift.test.ts @@ -107,7 +107,7 @@ function driftState( } as Record>; } -// Drift baselines live in the hash store (.vapi-state-hash//), which +// Drift baselines live in the hash store (state//local/baselines/), 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. const HASH_STORE_TEST_ENV = `drift-test-${process.pid}`; diff --git a/tests/examples.test.ts b/tests/examples.test.ts index 93e015d..28990c2 100644 --- a/tests/examples.test.ts +++ b/tests/examples.test.ts @@ -112,7 +112,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/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/new-file-gate.test.ts b/tests/new-file-gate.test.ts index 855a23a..e35a513 100644 --- a/tests/new-file-gate.test.ts +++ b/tests/new-file-gate.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -439,7 +440,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), ); } diff --git a/tests/org-pin.test.ts b/tests/org-pin.test.ts index c58ec41..79ee40e 100644 --- a/tests/org-pin.test.ts +++ b/tests/org-pin.test.ts @@ -18,17 +18,17 @@ 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 } 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; @@ -56,8 +56,10 @@ 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; } @@ -106,7 +108,7 @@ test("orgPinCheck pins an unpinned folder to the key's org", async () => { 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 { @@ -188,7 +190,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,9 +213,16 @@ 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) => { diff --git a/tests/promote-cmd.test.ts b/tests/promote-cmd.test.ts index 40da4fe..6428d29 100644 --- a/tests/promote-cmd.test.ts +++ b/tests/promote-cmd.test.ts @@ -40,7 +40,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..dc20546 100644 --- a/tests/promotion-gate.test.ts +++ b/tests/promotion-gate.test.ts @@ -67,7 +67,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-workflow-commit.test.ts b/tests/promotion-workflow-commit.test.ts index 765916d..82a8648 100644 --- a/tests/promotion-workflow-commit.test.ts +++ b/tests/promotion-workflow-commit.test.ts @@ -12,6 +12,7 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { parse as parseYaml } from "yaml"; +import { 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 +74,7 @@ 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"); write(".gitignore", "tmp/\n.env.*\n"); for (const [path, content] of Object.entries(files)) write(path, content); git(CLONE, "add", "-A"); @@ -83,7 +84,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 +97,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 +153,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 +200,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 +234,142 @@ 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(); + // What `npm run migrate` does before the promotion in the same run. + for (const org of ["a", "b"]) stateLayoutPrepare(CLONE, org, {}); + 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(); + for (const org of ["a", "b"]) stateLayoutPrepare(CLONE, org, {}); + 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}`, + ); +}); + test.after(() => rmSync(WORK, { recursive: true, force: true })); diff --git a/tests/promotion.test.ts b/tests/promotion.test.ts index 615efbb..c93022d 100644 --- a/tests/promotion.test.ts +++ b/tests/promotion.test.ts @@ -410,12 +410,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"); diff --git a/tests/pull-rename-preserves-filename.test.ts b/tests/pull-rename-preserves-filename.test.ts index 7405380..7a6592b 100644 --- a/tests/pull-rename-preserves-filename.test.ts +++ b/tests/pull-rename-preserves-filename.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -136,12 +137,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 +231,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..52b1077 100644 --- a/tests/pull-same-name-clobber.test.ts +++ b/tests/pull-same-name-clobber.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -167,12 +168,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 +296,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..9feee9d 100644 --- a/tests/push-dry-run.test.ts +++ b/tests/push-dry-run.test.ts @@ -1,3 +1,4 @@ +import { stateFilePath } from "../src/state-paths.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -100,9 +101,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 +113,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-stale-baseline-noop.test.ts b/tests/push-stale-baseline-noop.test.ts index 882ce3d..ebe0637 100644 --- a/tests/push-stale-baseline-noop.test.ts +++ b/tests/push-stale-baseline-noop.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -129,12 +130,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 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-layout.test.ts b/tests/state-layout.test.ts new file mode 100644 index 0000000..e56ae07 --- /dev/null +++ b/tests/state-layout.test.ts @@ -0,0 +1,681 @@ +import assert from "node:assert/strict"; +import { spawn } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + readdirSync, + 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 { assertStateMigrated, migrateAll } from "../src/migrate-hash-store.ts"; +import { + StateLayoutError, + baselinesDir, + orgPinFilePath, + orgPinFileRead, + orgPinFileWrite, + snapshotsDir, + stateFilePath, + stateFileRead, + stateFileWrite, + stateLayoutPrepare, + stateMoveBlocker, + 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, so these tests +// pin every way an older repository reaches the new layout: read in place, +// moved by a command on a person's machine, held back in CI and under a +// workflow that would not commit the move, cut short, and in disagreement. + +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; +} + +function layout(root: string): Record { + return { + oldState: read(root, `.vapi-state.${ORG}.json`), + oldPin: read(root, `resources/${ORG}/.vapi-org.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 MOVED = { + oldState: undefined, + oldPin: 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 })); +} + +// ── Reading ────────────────────────────────────────────────────────────── + +test("orgs are listed from both layouts, and an org with no state yet reads from state/", () => { + 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), + stateFileRead(root, "fresh") === stateFilePath(root, "fresh"), + ], + [["acme", "beta"], true], + ); + }); +}); + +test("reads fall back to the old file only while the new one is absent", () => { + 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)], + [ + [ + join(root, `.vapi-state.${ORG}.json`), + join(root, `resources/${ORG}/.vapi-org.json`), + ], + stateFilePath(root, ORG), + orgPinFilePath(root, ORG), + ], + ); + }); +}); + +// ── Moving on a person's machine ───────────────────────────────────────── + +test("a command on a person's machine moves everything and says so in one line", () => { + const root = oldRepo(); + return withRepo(root, () => { + const notices = stateLayoutPrepare(root, ORG, LOCAL); + assert.deepEqual( + { + notices, + layout: layout(root), + leftovers: existsSync(join(root, ".vapi-state-hash")), + }, + { + notices: [ + `📦 Moved .vapi-state-hash/${ORG}/, .vapi-state.${ORG}.snapshots/, .vapi-state.${ORG}.json, resources/${ORG}/.vapi-org.json into state/${ORG}/. Commit the removal together with the new folder.`, + ], + layout: MOVED, + leftovers: false, + }, + ); + }); +}); + +test("a second run moves nothing and says nothing", () => { + const root = oldRepo(); + return withRepo(root, () => { + stateLayoutPrepare(root, ORG, LOCAL); + assert.deepEqual( + [stateLayoutPrepare(root, ORG, LOCAL), layout(root)], + [[], MOVED], + ); + }); +}); + +test("a repository that never had the old layout is left alone", () => { + const root = mkdtempSync(join(tmpdir(), "state-layout-")); + return withRepo(root, () => { + put(root, `state/${ORG}/state.json`, STATE); + assert.deepEqual( + [ + stateLayoutPrepare(root, ORG, LOCAL), + stateLayoutPrepare(root, ORG, CI), + stateFileWrite(root, ORG, CI) === stateFilePath(root, ORG), + stateFileWrite(root, "new-org", CI) === stateFilePath(root, "new-org"), + orgPinFileWrite(root, "new-org", CI) === + orgPinFilePath(root, "new-org"), + ], + [[], [], true, true, true], + ); + }); +}); + +test("machine-local files merge into a folder that already exists, newest side winning", () => { + const root = oldRepo(); + return withRepo(root, () => { + put(root, `state/${ORG}/local/baselines/${UUID}`, "newer-hash\n"); + put(root, `.vapi-state-hash/${ORG}/other`, "other-hash\n"); + stateLayoutPrepare(root, ORG, LOCAL); + assert.deepEqual( + [ + readdirSync(baselinesDir(root, ORG)).sort(), + read(root, `state/${ORG}/local/baselines/${UUID}`), + existsSync(join(root, ".vapi-state-hash")), + readdirSync(snapshotsDir(root, ORG)), + ], + [ + [UUID, "other"].sort(), + "newer-hash\n", + false, + ["2026-01-01T00-00-00-000Z"], + ], + ); + }); +}); + +// ── Held back ──────────────────────────────────────────────────────────── + +test("a CI run leaves committed state where it is and writes it in place", () => { + const root = oldRepo(); + return withRepo(root, () => { + const notices = stateLayoutPrepare(root, ORG, CI); + assert.deepEqual( + { + notices, + layout: layout(root), + stateWrite: stateFileWrite(root, ORG, CI), + pinWrite: orgPinFileWrite(root, ORG, CI), + }, + { + notices: [ + `📦 Moved .vapi-state-hash/${ORG}/, .vapi-state.${ORG}.snapshots/ into state/${ORG}/.`, + "ℹ️ .vapi-state.acme.json and resources/acme/.vapi-org.json stays where it is: a CI run never moves state. Run `npm run migrate` on your machine and commit the result to move it into state/acme/.", + ], + // Gitignored files move anywhere: no workflow can lose them. + layout: { + ...MOVED, + oldState: STATE, + oldPin: PIN, + state: undefined, + pin: undefined, + }, + stateWrite: join(root, `.vapi-state.${ORG}.json`), + pinWrite: join(root, `resources/${ORG}/.vapi-org.json`), + }, + ); + }); +}); + +test("GITHUB_ACTIONS counts as a CI run", () => { + const root = oldRepo(); + return withRepo(root, () => { + stateLayoutPrepare(root, ORG, { GITHUB_ACTIONS: "true" }); + assert.equal(layout(root).oldState, STATE); + }); +}); + +test("a workflow that stages only the old file holds the move back, on any machine", () => { + const root = oldRepo(); + return withRepo(root, () => { + put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); + const notices = stateLayoutPrepare(root, ORG, LOCAL); + assert.deepEqual( + { + blocker: stateMoveBlocker(root, LOCAL), + warned: notices.at(-1), + oldState: layout(root).oldState, + state: layout(root).state, + // A new org follows the layout the workflow commits. + newOrgState: stateFileWrite(root, "new-org", LOCAL), + newOrgPin: orgPinFileWrite(root, "new-org", LOCAL), + }, + { + blocker: { kind: "workflow", file: ".github/workflows/promotion.yml" }, + warned: + "⚠️ .vapi-state.acme.json and resources/acme/.vapi-org.json stays where it is: .github/workflows/promotion.yml stages .vapi-state.*.json but not state/. Add `git add -A -- state` to that step, then run `npm run migrate`.", + oldState: STATE, + state: undefined, + newOrgState: join(root, ".vapi-state.new-org.json"), + newOrgPin: join(root, "resources/new-org/.vapi-org.json"), + }, + ); + }); +}); + +test("the workflow this repository ships does not hold the move back", () => { + const root = oldRepo(); + return withRepo(root, () => { + cpSync(join(REPO, ".github/workflows"), join(root, ".github/workflows"), { + recursive: true, + }); + assert.deepEqual( + [stateMoveBlocker(root, LOCAL), stateMoveBlocker(root, CI)], + [undefined, { kind: "ci" }], + ); + }); +}); + +test("a CI run stops before it writes state its workflow would not commit", () => { + const root = mkdtempSync(join(tmpdir(), "state-layout-")); + return withRepo(root, () => { + put(root, `state/${ORG}/state.json`, STATE); + put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); + 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 is warned, not stopped. + assert.match( + stateLayoutPrepare(root, ORG, LOCAL)[0]!, + /^⚠️ {2}\.github\/workflows\/promotion\.yml/, + ); + }); +}); + +// ── Cut short, or in disagreement ──────────────────────────────────────── + +test("a move cut short between two files finishes on the next run", () => { + const root = oldRepo(); + return withRepo(root, () => { + // 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); + assert.deepEqual(layout(root), MOVED); + }); +}); + +test("the same content in both places is one state: the old copy goes, even in CI", () => { + for (const env of [LOCAL, CI]) { + const root = oldRepo(); + // Same mapping, different key order and spacing: a merge or a formatter. + put( + root, + `state/${ORG}/state.json`, + `{"assistants":{"intake":{"uuid":"${UUID}"}}}`, + ); + stateLayoutPrepare(root, ORG, env); + const after = layout(root); + rmSync(root, { recursive: true, force: true }); + assert.deepEqual( + [after.oldState, after.state], + [undefined, `{"assistants":{"intake":{"uuid":"${UUID}"}}}`], + ); + } +}); + +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, lastPulledHash: "h" } } })}\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("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 { + put(root, `.vapi-state.${ORG}.json`, FAT_STATE); + put(root, "state/beta/state.json", STATE); + const result = await migrateAll(root); + assert.deepEqual( + { + orgs: result.orgs.map((org) => [ + org.org, + org.stateFile, + org.slimmed, + org.notices.length, + ]), + oldState: layout(root).oldState, + state: JSON.parse(layout(root).state!), + pin: layout(root).pin, + again: (await migrateAll(root)).orgs.map((org) => [ + org.slimmed, + org.notices, + ]), + }, + { + orgs: [ + [ORG, "state/acme/state.json", true, 1], + ["beta", "state/beta/state.json", false, 0], + ], + oldState: undefined, + state: { assistants: { intake: { uuid: UUID } } }, + pin: PIN, + again: [ + [false, []], + [false, []], + ], + }, + ); + } finally { + if (ci === undefined) delete process.env.CI; + else process.env.CI = ci; + rmSync(root, { recursive: true, force: true }); + } +}); + +test("migrate does not move state while a workflow would drop it", async () => { + const root = oldRepo(); + try { + put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); + const result = await migrateAll(root); + assert.deepEqual( + [result.orgs[0]!.stateFile, layout(root).oldState, layout(root).state], + [".vapi-state.acme.json", STATE, undefined], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +// ── Real commands against a stub API ───────────────────────────────────── + +const ASSISTANT = (id: string, name: string) => ({ + id, + orgId: "org-a", + name, + model: { + provider: "openai", + model: "gpt-4o", + messages: [{ role: "system", content: "hi" }], + }, + 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: "", + ...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 on a person's machine moves an old repository once and keeps every mapping", async () => { + const root = oldRepo(); + try { + const first = await engineRun(root, ["src/pull.ts", ORG, "--force"], LOCAL); + const state = JSON.parse(layout(root).state ?? "{}"); + const second = await engineRun( + root, + ["src/pull.ts", ORG, "--force"], + LOCAL, + ); + assert.deepEqual( + { + codes: [first.code, second.code], + moved: [count(first.out, "📦 Moved"), count(second.out, "📦 Moved")], + oldState: layout(root).oldState, + oldPin: layout(root).oldPin, + pin: 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(), + rootLeftovers: readdirSync(root).filter((name) => + name.startsWith(".vapi-state"), + ), + }, + { + codes: [0, 0], + moved: [1, 0], + oldState: undefined, + oldPin: undefined, + pin: PIN, + tracked: { uuid: UUID }, + uuids: [UUID, UUID_NEW], + rootLeftovers: [], + }, + first.out + second.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("pull in a CI run updates an old repository's state file in place", async () => { + const root = oldRepo(); + try { + const run = await engineRun(root, ["src/pull.ts", ORG, "--force"], CI); + const state = JSON.parse(layout(root).oldState ?? "{}"); + assert.deepEqual( + { + code: run.code, + told: count(run.out, "a CI run never moves state"), + state: layout(root).state, + pin: [layout(root).oldPin, layout(root).pin], + tracked: state.assistants?.intake, + uuids: Object.values( + (state.assistants ?? {}) as Record, + ) + .map((entry) => entry.uuid) + .sort(), + }, + { + code: 0, + told: 1, + state: undefined, + pin: [PIN, undefined], + tracked: { uuid: UUID }, + uuids: [UUID, UUID_NEW], + }, + 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 moves nothing", async () => { + const root = oldRepo(); + try { + const run = await engineRun(root, ["src/push.ts", ORG, "--dry-run"], LOCAL); + assert.deepEqual( + [count(run.out, "📦 Moved"), layout(root).oldState, layout(root).state], + [0, STATE, undefined], + run.out, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a baseline is still read from the old folder until it moves", 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 }); + } +}); diff --git a/tests/state-migration.test.ts b/tests/state-migration.test.ts index ea8c219..232cb13 100644 --- a/tests/state-migration.test.ts +++ b/tests/state-migration.test.ts @@ -11,7 +11,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/vapi-ignore-push.test.ts b/tests/vapi-ignore-push.test.ts index 79df1e2..41ba275 100644 --- a/tests/vapi-ignore-push.test.ts +++ b/tests/vapi-ignore-push.test.ts @@ -1,3 +1,4 @@ +import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -151,7 +152,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/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 From 54b9b300d6b6d4bd7505feaf23bd20bed0b3884d Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Tue, 17 Nov 2026 13:17:08 -0800 Subject: [PATCH 02/10] docs: describe the state/ folder and how an older repository moves into it Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- AGENTS.md | 15 ++++---- README.md | 27 ++++++++------ SECURITY.md | 2 +- docs/guides/commands.md | 47 +++++++++++++++++++++---- docs/guides/configuration.md | 9 ++++- docs/guides/how-it-works.md | 22 ++++++++---- docs/guides/pr-checks.md | 2 +- docs/guides/promotion.md | 6 ++-- docs/guides/workflows.md | 12 +++---- docs/learnings/simulations.md | 2 +- docs/learnings/squads.md | 2 +- docs/learnings/sync-behavior.md | 10 +++--- improvements.md | 62 +++++++++++++++++++++++++++++++++ 13 files changed, 169 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1de7998..a1885f5 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 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..006478d 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. | @@ -193,14 +193,47 @@ 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: +`npm run migrate` brings an older repository up to date. 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 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. +It does two things. + +**Moves engine files into `state//`.** They used to sit under dot-names +in three places. 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/` | + +You don't have to run it for this: the engine keeps reading the old places, +and the next `pull`, `push` or `apply` on your machine moves that org and +says so in one line. Either way, commit the removal of the old file together +with the new folder. + +The move is held back in two cases, and the command tells you which: + +- **In a CI run.** State stays where it is and is updated in place. Only a + workflow that commits both places can record a move, so run + `npm run migrate` on your machine and commit the result. +- **When a workflow under `.github/workflows/` stages `.vapi-state.*.json` but + not `state/`.** That workflow would commit the old file's removal without + the new one. Take upstream's `promotion.yml` workflow, or add + `git add -A -- state` to your own commit step, then run `npm run migrate`. + +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. + +**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. 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..21a8c46 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 @@ -171,7 +171,7 @@ fresh-clone workflows: 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 + newer than `state//state.json` are still preserved. This is the safety net for the "fresh clone, edit a file, run pull again" case. Interactive `npm run pull` is local-first too: it asks @@ -188,7 +188,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 +229,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..9fee1d2 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.** @@ -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/improvements.md b/improvements.md index 0d98ca7..192679e 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 (#PR_NUMBER) | **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,67 @@ dependency check, as `check-payload.ts` already does. --- +## 39. Engine state looked like temp files and sat in three places + +**[RESOLVED 2026-11-17] (#PR_NUMBER)** + +**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: every command reads the old places, and +the next `pull`, `push` or `apply` on a person's machine moves the org with +one rename per file and prints one line. The move is held back in a CI run +and while a workflow stages `.vapi-state.*.json` but not `state/`, because +either would commit the old file's removal without the new file. The +promotion workflow stages both places. `tests/state-layout.test.ts` and +`tests/promotion-workflow-commit.test.ts` cover each path. + +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 From f9e3628a95811b3716c0bd1432b1976162c2b9fd Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Tue, 17 Nov 2026 13:20:28 -0800 Subject: [PATCH 03/10] docs(improvements): point entry 39 at its pull request Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- improvements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/improvements.md b/improvements.md index 192679e..107635a 100644 --- a/improvements.md +++ b/improvements.md @@ -109,7 +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 (#PR_NUMBER) | +| 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. @@ -2084,7 +2084,7 @@ dependency check, as `check-payload.ts` already does. ## 39. Engine state looked like temp files and sat in three places -**[RESOLVED 2026-11-17] (#PR_NUMBER)** +**[RESOLVED 2026-11-17] (#97)** **Discovered:** 2026-11-17, from a user asking which of the generated dot-files were safe to delete. From b0352d20072f7efc18b714aa12776658c92579ed Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Tue, 17 Nov 2026 13:29:12 -0800 Subject: [PATCH 04/10] test: leave state/ as it was after a test run Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- tests/drift.test.ts | 7 ++++++- tests/state-layout.test.ts | 2 +- tests/tool-assistant-cycle.test.ts | 14 ++++++++++++-- 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/tests/drift.test.ts b/tests/drift.test.ts index f95b558..bc64c98 100644 --- a/tests/drift.test.ts +++ b/tests/drift.test.ts @@ -1,4 +1,5 @@ import assert from "node:assert/strict"; +import { dirname } from "node:path"; import test from "node:test"; import { checkPronunciationDictDrop, @@ -112,7 +113,11 @@ function driftState( // no real checkout uses, and remove the whole folder when the file finishes. const HASH_STORE_TEST_ENV = `drift-test-${process.pid}`; after(() => { - rmSync(hashStoreDir(HASH_STORE_TEST_ENV), { recursive: true, force: true }); + // state//local/baselines → state/ + rmSync(dirname(dirname(hashStoreDir(HASH_STORE_TEST_ENV))), { + recursive: true, + force: true, + }); }); test("checkPronunciationDictDrop: warns when prior had ID and new lost it", () => { diff --git a/tests/state-layout.test.ts b/tests/state-layout.test.ts index e56ae07..969d3db 100644 --- a/tests/state-layout.test.ts +++ b/tests/state-layout.test.ts @@ -397,7 +397,7 @@ test("two state files that disagree stop the command with both intact", () => { // ── npm run migrate and the legacy-format guard ────────────────────────── -const FAT_STATE = `${JSON.stringify({ assistants: { intake: { uuid: UUID, lastPulledHash: "h" } } })}\n`; +const FAT_STATE = `${JSON.stringify({ assistants: { intake: { uuid: UUID, 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-")); diff --git a/tests/tool-assistant-cycle.test.ts b/tests/tool-assistant-cycle.test.ts index c0c5ee4..7db38e5 100644 --- a/tests/tool-assistant-cycle.test.ts +++ b/tests/tool-assistant-cycle.test.ts @@ -1,4 +1,6 @@ import assert from "node:assert/strict"; +import { rmSync } from "node:fs"; +import { dirname } from "node:path"; import test, { after } from "node:test"; // ───────────────────────────────────────────────────────────────────────────── @@ -26,7 +28,7 @@ const { updateToolAssistantRefs, } = await import("../src/push.ts"); -import { deleteBaseline } from "../src/hash-store.ts"; +import { deleteBaseline, hashStoreDir } from "../src/hash-store.ts"; import type { ResourceFile, StateFile } from "../src/types.ts"; const UUID = "8f14e45f-ceea-467a-9f1b-1a1b2c3d4e5f"; @@ -34,7 +36,15 @@ 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 this checkout's state/ folder. +// Remove it and the folders it created, so a test run leaves state/ as it was. +after(async () => { + await deleteBaseline("test-fixture-org", UUID); + rmSync(dirname(dirname(hashStoreDir("test-fixture-org"))), { + recursive: true, + force: true, + }); +}); test("an unresolved assistant destination drops the whole destinations key", async () => { // Unresolved = resolution left the slug exactly as written, because the From 2866322fbb79e460a059a1fe5929c6956abae3cf Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Wed, 18 Nov 2026 09:39:38 -0800 Subject: [PATCH 05/10] fix(state): move state only under a commit step seen to stage state/ The guard that holds the move back looked for one known-bad pattern: a "git add" line naming .vapi-state. with none naming state. A commit step it couldn't read (a helper script, a commit action with a file pattern, a pipeline outside GitHub Actions) passed as safe. A command on a person's machine then moved state, and every later promotion run passed while state//state.json was never committed, so resources were created again as duplicates. The move now fails closed. State moves by itself only when a workflow is seen to stage state/, or when nothing in the repository commits state after a run: no workflow that can write to the repository, and no root promotion.yml. A CI run stops before any request when it would write state in a place its commit step isn't seen to stage. In GitHub Actions it reads the workflow that is running it. npm run migrate, where nothing is seen to stage state/, prints the two paths the commit step has to stage and moves nothing. A person who has updated their step says so with --commit-step-stages-state, which is recorded in state/commit-step.json. The engine can't check that word. Docs: what counts as seen, the limit of the flag, what a customer sees after upgrading, and how to go back to an older engine without creating duplicates. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/guides/commands.md | 88 +++- improvements.md | 18 +- src/migrate-cmd.ts | 18 +- src/migrate-hash-store.ts | 24 +- src/state-paths.ts | 304 ++++++++++-- state/README.md | 4 +- tests/promotion-workflow-commit.test.ts | 70 +++ tests/state-layout-unseen-commit.test.ts | 594 +++++++++++++++++++++++ 8 files changed, 1075 insertions(+), 45 deletions(-) create mode 100644 tests/state-layout-unseen-commit.test.ts diff --git a/docs/guides/commands.md b/docs/guides/commands.md index 006478d..fcd7514 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -219,15 +219,60 @@ and the next `pull`, `push` or `apply` on your machine moves that org and says so in one line. Either way, commit the removal of the old file together with the new folder. -The move is held back in two cases, and the command tells you which: +**State moves only when the engine can see it will still be committed.** A +promotion run in CI writes the state file and leaves committing it to a later +step. If that step stages only the old file, a move takes the UUID map out of +git: every run still passes, and the next one creates every resource again. +So the move is held back in three cases, and the command tells you which: -- **In a CI run.** State stays where it is and is updated in place. Only a - workflow that commits both places can record a move, so run +- **In a CI run.** State stays where it is and is updated in place. Run `npm run migrate` on your machine and commit the result. - **When a workflow under `.github/workflows/` stages `.vapi-state.*.json` but not `state/`.** That workflow would commit the old file's removal without the new one. Take upstream's `promotion.yml` workflow, or add `git add -A -- state` to your own commit step, then run `npm run migrate`. +- **When something may commit state and the engine can't see it stage + `state/`.** That is a workflow that can write to the repository and has no + `git add` line for `state` (it stages through a script, a commit action or + a variable), or a root `promotion.yml` with no workflow in the repository + that stages `state/` (the pipeline runs somewhere the engine can't read). + `npm run migrate` then moves nothing and prints what the commit step has to + stage: + + ```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. When your step + stages both, 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. + +What counts as seen: a `git add` line in a workflow file that names `state` +(or `state/`, `state/**`), or one that stages everything (`git add -A`, +`git add .`). A workflow whose `permissions` keep `contents` read-only, and +that never runs `git commit` or `git push`, is not a commit step, so +upstream's `ci.yml` and `vapi-checks.yml` hold nothing back. + +A CI run also stops, before it sends any request, when it would write state +in a place its commit step isn't seen to stage: state already in `state/` +under a step that stages only the old file or can't be read, or state still +at the root under a step that stages only `state/`. In GitHub Actions the +engine checks the workflow that is running it. Anywhere else it checks every +workflow in the repository. + +> **`--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`. 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. @@ -237,3 +282,40 @@ 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 you'll see after upgrading + +- **`📦 Moved … into state//`**, once per org, on the first `pull`, + `push` or `apply` on your machine. +- **`📦 1 locally modified file(s) will be preserved`** on the first `pull` + after the move. The file is the old org pin, + `resources//.vapi-org.json`. It moved to `state//org.json`, so git + shows it as deleted until you commit. Pull does nothing differently because + of it. +- **`… stays where it is: …`** on every writing command while the move is + held back. The line says why. + +### Going back to an older engine + +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 +``` + +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/improvements.md b/improvements.md index 107635a..cb0c85d 100644 --- a/improvements.md +++ b/improvements.md @@ -2125,12 +2125,22 @@ file goes missing. `resources//` now holds hand-written files only. An older repository keeps working: every command reads the old places, and the next `pull`, `push` or `apply` on a person's machine moves the org with -one rename per file and prints one line. The move is held back in a CI run -and while a workflow stages `.vapi-state.*.json` but not `state/`, because -either would commit the old file's removal without the new file. The -promotion workflow stages both places. `tests/state-layout.test.ts` and +one rename per file and prints one line. The move fails closed: it happens +only when a workflow is seen to stage `state/`, or when nothing in the +repository commits state after a run. It is held back in a CI run, while a +workflow stages `.vapi-state.*.json` but not `state/`, and while a commit +step can't be read (a script, a commit action, a pipeline outside GitHub +Actions) until a person says it stages `state/` with +`npm run migrate -- --commit-step-stages-state`. A CI run stops before any +request when it would write state where its commit step isn't seen to look. +The promotion workflow stages both places. `tests/state-layout.test.ts`, +`tests/state-layout-unseen-commit.test.ts` and `tests/promotion-workflow-commit.test.ts` cover each path. +One limit remains. 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. The engine can't see a step it can't read. + 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 diff --git a/src/migrate-cmd.ts b/src/migrate-cmd.ts index 81fe046..65a5dcf 100644 --- a/src/migrate-cmd.ts +++ b/src/migrate-cmd.ts @@ -7,10 +7,15 @@ // does not import `config.ts` (which would force an org + token at load). // // Idempotent: re-running after migration seeds nothing and rewrites nothing. +// +// `--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 { COMMIT_STEP_FLAG } from "./state-paths.ts"; async function main(): Promise { console.log( @@ -21,7 +26,17 @@ async function main(): Promise { "═══════════════════════════════════════════════════════════════\n", ); - const result = await migrateAll(); + 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}.`, + ); + + const result = await migrateAll(undefined, { + commitStepStagesState: args.includes(COMMIT_STEP_FLAG), + }); + if (result.acknowledged) console.log(` ${result.acknowledged}\n`); if (result.orgs.length === 0) { console.log(" No state files found — nothing to migrate."); @@ -46,6 +61,7 @@ async function main(): Promise { `\n✅ Migration complete: ${result.orgs.length} org(s), ` + `${totalSlimmed} state file(s) slimmed, ${totalSeeded} baseline(s) seeded.`, ); + if (result.commitStepAsk) console.log(`\n${result.commitStepAsk.join("\n")}`); } const isMainModule = diff --git a/src/migrate-hash-store.ts b/src/migrate-hash-store.ts index e1753e9..acb8296 100644 --- a/src/migrate-hash-store.ts +++ b/src/migrate-hash-store.ts @@ -19,6 +19,8 @@ import { writeBaseline, } from "./hash-store.ts"; import { + commitStepAcknowledge, + commitStepAsk, stateFileRead, stateLayoutPrepare, stateOrgsList, @@ -40,6 +42,15 @@ export interface OrgMigrationResult { export interface MigrationResult { orgs: OrgMigrationResult[]; + /** What was written down when the person said their commit step stages state/. */ + acknowledged?: string; + /** Set when nothing moved: what the commit step has to stage first. */ + commitStepAsk?: string[]; +} + +export interface MigrationOptions { + /** The person says the step that commits state stages state/ (`--commit-step-stages-state`). */ + commitStepStagesState?: boolean; } // A legacy entry is anything that isn't already exactly `{ uuid: string }`: @@ -134,8 +145,8 @@ async function migrateOne( // Slim first, in place, then move: each step leaves one complete state // file. An explicit migrate moves state even in a CI run, because whoever - // runs it there commits the result; a workflow that would drop state/ from - // its commit still stops the move. + // runs it there commits the result; a commit step that would drop state/, + // or isn't seen to stage it, still stops the move. const notices = stateLayoutPrepare(baseDir, org, { ...process.env, CI: "", @@ -155,14 +166,21 @@ async function migrateOne( // 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. +// +// Where nothing is seen to stage state/ after a run, files are slimmed in +// place and nothing moves until the person says their commit step stages it. export async function migrateAll( baseDir: string = BASE_DIR, + options: MigrationOptions = {}, ): Promise { + const acknowledged = options.commitStepStagesState + ? commitStepAcknowledge(baseDir) + : undefined; const orgs: OrgMigrationResult[] = []; for (const org of stateOrgsList(baseDir)) { orgs.push(await migrateOne(baseDir, org)); } - return { orgs }; + return { orgs, acknowledged, commitStepAsk: commitStepAsk(baseDir) }; } // Guard called at the entry of pull/push/apply. Throws if the given state file diff --git a/src/state-paths.ts b/src/state-paths.ts index b91f095..8201962 100644 --- a/src/state-paths.ts +++ b/src/state-paths.ts @@ -4,6 +4,7 @@ // 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//. @@ -24,11 +25,21 @@ import { rmdirSync, rmSync, unlinkSync, + writeFileSync, } from "fs"; import { dirname, join } from "path"; +import { parse as parseYaml } from "yaml"; 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); } @@ -108,51 +119,238 @@ export function stateOrgsList(rootDir: string): string[] { return [...orgs].sort((a, b) => a.localeCompare(b)); } -export type StateMoveBlocker = - | { kind: "workflow"; file: string } - | { kind: "ci" }; +// ── Who commits state after a run ──────────────────────────────────────── +// +// A run in CI writes the state file and leaves committing it to a later step +// the engine can't watch. If that step stages only the place state used to +// be, moving state takes the UUID map out of git: every run still passes, and +// the next one creates every resource again. So state moves by itself only +// when a workflow is seen to stage state/, or when nothing in the repository +// can commit state after a run. A step the engine can't read is not seen. + +interface WorkflowRead { + file: string; + /** A `git add` line stages state/. */ + stagesNew: boolean; + /** A `git add` line stages .vapi-state.*.json. */ + stagesOld: boolean; + /** False only when the file is read as unable to write to the repository. */ + canCommit: boolean; +} + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +// What a workflow's `git add` lines stage. A pathspec the engine can't read +// (a variable, one org's folder) counts for nothing. +function gitAddsRead(text: string): { stagesNew: boolean; stagesOld: boolean } { + let stagesNew = false; + let stagesOld = false; + for (const line of text.replace(/\\\r?\n/g, " ").split("\n")) { + if (/^\s*#/.test(line)) continue; + for (const command of line.replace(/\s#.*$/, "").split(/&&|\|\||;/)) { + const at = command.search(/\bgit add\b/); + if (at < 0) continue; + const args = command + .slice(at + "git add".length) + .split(/\s+/) + .filter(Boolean) + .map((arg) => arg.replace(/^["']|["']$/g, "")); + const paths = args + .filter((arg) => !arg.startsWith("-")) + .map((path) => path.replace(/^:\([a-z,]*\)/, "").replace(/^\.\//, "")); + const everything = + paths.length === 0 + ? args.some((arg) => arg === "--all" || /^-[a-zA-Z]*A/.test(arg)) + : paths.some((path) => path === "." || path === ":/"); + if (everything || paths.some((path) => /^state(\/\**)?$/.test(path))) + stagesNew = true; + if (everything || paths.some((path) => path.includes(".vapi-state."))) + stagesOld = true; + } + } + return { stagesNew, stagesOld }; +} + +// Only a workflow whose permissions keep `contents` read-only in every job, +// and that never runs `git commit` or `git push`, is read as unable to commit. +// A file that doesn't parse, or sets no permissions, can. +function workflowCanCommit(text: string): boolean { + if (/\bgit\s+(commit|push)\b/.test(text)) return true; + let doc: unknown; + try { + doc = parseYaml(text); + } catch { + return true; + } + if (!isRecord(doc) || !isRecord(doc.jobs)) return true; + const writes = (permissions: unknown): boolean | undefined => + permissions === undefined + ? undefined + : permissions === "write-all" || + (isRecord(permissions) && permissions.contents === "write"); + const top = writes(doc.permissions); + return Object.values(doc.jobs).some( + (job) => + (isRecord(job) ? writes(job.permissions) : undefined) ?? top ?? true, + ); +} -// A workflow that stages .vapi-state.*.json but not state/ would commit the -// old file's removal without the new one, so the UUID map would leave git. -function staleWorkflowFind(rootDir: string): string | undefined { +function workflowsRead(rootDir: string): WorkflowRead[] { const dir = join(rootDir, ".github", "workflows"); - if (!existsSync(dir)) return undefined; - for (const name of readdirSync(dir).sort()) { - if (!/\.ya?ml$/.test(name)) continue; - const adds = readFileSync(join(dir, name), "utf8") - .split("\n") - .filter((line) => /\bgit add\b/.test(line) && !/^\s*#/.test(line)); - const stagesOld = adds.some((line) => line.includes(".vapi-state.")); - const stagesNew = adds.some((line) => - /(? /\.ya?ml$/.test(name)) + .sort() + .map((name) => { + const text = readFileSync(join(dir, name), "utf8"); + return { + file: `.github/workflows/${name}`, + ...gitAddsRead(text), + canCommit: workflowCanCommit(text), + }; + }); +} + +export type CommitStep = + /** A workflow is seen to stage the old state file and not state/. */ + | { kind: "stale"; file: string } + /** Something may commit state after a run, and it isn't seen to stage state/. */ + | { kind: "unseen"; file?: string } + /** Every workflow that can commit is seen to stage state/. */ + | { kind: "seen"; stagesOld: boolean } + /** Nothing here commits state after a run. */ + | { kind: "none" }; + +/** + * 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/. With no + * workflow that can commit, a root promotion.yml still means some pipeline + * runs promotion and commits what it records. + */ +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((w) => w.stagesOld && !w.stagesNew); + if (stale) return { kind: "stale", file: stale.file }; + const unseen = workflows.find((w) => w.canCommit && !w.stagesNew); + if (unseen) return { kind: "unseen", file: unseen.file }; + if (workflows.some((w) => w.stagesNew)) + return { kind: "seen", stagesOld: workflows.some((w) => w.stagesOld) }; + return own.length === 0 && existsSync(join(rootDir, "promotion.yml")) + ? { kind: "unseen" } + : { kind: "none" }; +} + +/** 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"), ); - if (stagesOld && !stagesNew) return `.github/workflows/${name}`; + return isRecord(parsed) && parsed.stagesStateFolder === true; + } catch { + return false; } - return undefined; } +function unseenReason(file: string | undefined): string { + return file + ? `${file} can commit to this repository and is not seen to stage ${STATE_DIR}/` + : `promotion.yml is set up and no workflow in .github/workflows/ is seen to stage ${STATE_DIR}/`; +} + +export type StateMoveBlocker = + | { kind: "workflow"; file: string } + | { kind: "unseen"; file?: string } + | { kind: "ci" }; + export function stateRunIsCi(env: NodeJS.ProcessEnv = process.env): boolean { return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true"; } /** - * Why committed state must stay where it is for now. A CI run never moves it: - * only a workflow that stages both places could commit the move, and the - * engine can't see which workflow is running it. + * Why committed state must stay where it is for now. A workflow seen to stage + * only the old file holds it, and so does a commit step that isn't seen to + * stage state/ until a person says it does. A CI run never moves state: only + * the person who changes the commit step can commit the move with it. */ export function stateMoveBlocker( rootDir: string, env: NodeJS.ProcessEnv = process.env, ): StateMoveBlocker | undefined { - const file = staleWorkflowFind(rootDir); - if (file) return { kind: "workflow", file }; + const step = commitStepRead(rootDir, env); + if (step.kind === "stale") return { kind: "workflow", file: step.file }; + if (step.kind === "unseen" && !commitStepAcknowledged(rootDir)) + return { kind: "unseen", file: step.file }; return stateRunIsCi(env) ? { kind: "ci" } : undefined; } +/** + * What the commit step has to stage before state can move, when nothing is + * seen to stage state/ and nobody has said it does. For `npm run migrate`. + */ +export function commitStepAsk(rootDir: string): string[] | undefined { + const blocker = stateMoveBlocker(rootDir, {}); + if (blocker?.kind !== "unseen") return undefined; + return [ + `⚠️ Nothing moved into ${STATE_DIR}/: ${unseenReason(blocker.file)}.`, + " Whatever commits state after a run in this repository 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.", + " 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.`, + ]; +} + +/** + * 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 !== "unseen") + return `ℹ️ ${COMMIT_STEP_FLAG} is not needed here: ${step.kind === "seen" ? `a workflow is seen to stage ${STATE_DIR}/` : "nothing in this repository commits state after a run"}.`; + 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.`; +} + +// A repository that has any old root state file still follows the old layout. +function legacyStateExists(rootDir: string): boolean { + return readdirSync(rootDir).some((name) => + /^\.vapi-state\..+\.json$/.test(name), + ); +} + // A file that exists is written in place. A file that doesn't exist yet goes -// to state//, except in a checkout that still follows the old layout. +// to state//, except where the commit step is seen to stage only the old +// place, or isn't seen at all in a repository that still has old state files. function legacyLayoutKept( rootDir: string, org: string, @@ -160,7 +358,9 @@ function legacyLayoutKept( ): boolean { if (existsSync(stateFilePath(rootDir, org))) return false; if (existsSync(stateFileLegacyPath(rootDir, org))) return true; - return stateMoveBlocker(rootDir, env)?.kind === "workflow"; + const blocker = stateMoveBlocker(rootDir, env); + if (blocker?.kind === "workflow") return true; + return blocker?.kind === "unseen" && legacyStateExists(rootDir); } /** The state file to write. Call stateLayoutPrepare first in a command that writes. */ @@ -259,7 +459,7 @@ export function stateLocalMove(rootDir: string, org: string): string[] { * Each committed file moves by one rename, so the full state is always in * exactly one of the two places. Throws StateLayoutError, before anything is * read or changed, when both places hold a file and they disagree, or when a - * CI run would write state its workflow won't commit. + * CI run would write state in a place its commit step isn't seen to stage. */ export function stateLayoutPrepare( rootDir: string, @@ -292,15 +492,51 @@ export function stateLayoutPrepare( const notices: string[] = []; const blocker = stateMoveBlocker(rootDir, env); - if (blocker?.kind === "workflow" && existsSync(stateFilePath(rootDir, org))) { - const problem = `${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so it won't commit ${STATE_DIR}/${org}/.`; - const fix = `Add \`git add -A -- ${STATE_DIR}\` to that step.`; - if (stateRunIsCi(env)) + const ci = stateRunIsCi(env); + const step = commitStepRead(rootDir, env); + const inFolder = + stateFileWrite(rootDir, org, env) === stateFilePath(rootDir, org); + if ( + inFolder && + (blocker?.kind === "workflow" || blocker?.kind === "unseen") + ) { + const problem = + blocker.kind === "workflow" + ? `${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so it won't commit ${STATE_DIR}/${org}/.` + : `${unseenReason(blocker.file)}, so ${STATE_DIR}/${org}/ may never be committed.`; + const fix = + blocker.kind === "workflow" + ? `Add \`git add -A -- ${STATE_DIR}\` to that step.` + : `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.`; + if (ci) throw new StateLayoutError( `${problem}\n Stopped before reading or changing anything: UUIDs recorded by this run would be lost.\n ${fix}`, ); - notices.push(`⚠️ ${problem} ${fix}`); + // With only a promotion.yml to go on there may be no pipeline at all, so + // a person's machine isn't warned on every command. A CI run still stops. + if (blocker.kind === "workflow" || blocker.file) + notices.push(`⚠️ ${problem} ${fix}`); } + // The mirror case: state still at the old place, under a commit step that + // has moved on to state/. + if (ci && !inFolder && 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" && commitStepAcknowledged(rootDir) + ? `${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 (ci && inFolder && step.kind === "unseen") + 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.`, + ); const moved = stateLocalMove(rootDir, org); // Same content in both places: an earlier move was cut short, or a merge @@ -329,7 +565,9 @@ export function stateLayoutPrepare( notices.push( blocker.kind === "ci" ? `ℹ️ ${where} stays where it is: a CI run never moves state. Run \`npm run migrate\` on your machine and commit the result to move it into ${STATE_DIR}/${org}/.` - : `⚠️ ${where} stays where it is: ${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/. Add \`git add -A -- ${STATE_DIR}\` to that step, then run \`npm run migrate\`.`, + : blocker.kind === "workflow" + ? `⚠️ ${where} stays where it is: ${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/. Add \`git add -A -- ${STATE_DIR}\` to that step, then run \`npm run migrate\`.` + : `ℹ️ ${where} stays where it is: ${unseenReason(blocker.file)}. \`npm run migrate\` says what the commit step has to stage before it can move.`, ); } return notices; diff --git a/state/README.md b/state/README.md index ab27bef..8c18083 100644 --- a/state/README.md +++ b/state/README.md @@ -8,11 +8,13 @@ The engine writes everything in this folder. Don't edit or delete these files by | `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 @@ -23,4 +25,4 @@ Everything under `resources//`, including `resources//.vapi-ignore`, i 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 still reads them there. The next `npm run pull`, `npm run push` or `npm run apply` on your machine moves them here and says so in one line. Commit the removal of the old file together with the new folder. `npm run migrate` moves every org at once. -A CI run never moves them, because only a workflow that commits both places can record the move. See [Upgrading from an older version](../docs/guides/commands.md#upgrading-from-an-older-version). +A CI run never moves them, and no command does while the engine can't see that the step committing state after a run stages this folder. See [Upgrading from an older version](../docs/guides/commands.md#upgrading-from-an-older-version). diff --git a/tests/promotion-workflow-commit.test.ts b/tests/promotion-workflow-commit.test.ts index 82a8648..3ba3211 100644 --- a/tests/promotion-workflow-commit.test.ts +++ b/tests/promotion-workflow-commit.test.ts @@ -75,6 +75,12 @@ function repoReset( `version: 1\norgs:\n${orgs.map((org) => ` ${org}: {}`).join("\n")}\npipelines:\n${pipelineYaml}\n`, ); for (const org of orgs) write(`state/${org}/state.json`, "{}\n"); + // The repository carries the workflow whose commit step runs here: the + // engine 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"); @@ -372,4 +378,68 @@ test("the step from before state/ can't commit a moved repository, so the engine ); }); +// 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, then the run in CI. + const local = ["a", "b"].flatMap((org) => stateLayoutPrepare(CLONE, org, {})); + 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) => /stays where it is/.test(line)), + notices: [local.length, run.length], + 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], + 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/state-layout-unseen-commit.test.ts b/tests/state-layout-unseen-commit.test.ts new file mode 100644 index 0000000..b32313f --- /dev/null +++ b/tests/state-layout-unseen-commit.test.ts @@ -0,0 +1,594 @@ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + cpSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + 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, + StateLayoutError, + commitStepFilePath, + commitStepRead, + orgPinFileLegacyPath, + orgPinFileWrite, + stateFileLegacyPath, + stateFilePath, + stateFileWrite, + stateLayoutPrepare, +} 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 the move fails closed. Committed state stays where it is until a +// workflow is seen to stage state/, or a person says their commit step does. +// A CI run never writes state in a place its commit step isn't seen to stage. + +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" }; + +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); + } + return root; +} + +function workflow(commitLines: string[]): string { + return [ + "name: Promote", + "on: { push: { branches: [main] } }", + "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("promotion set up with no workflow in the repository holds the move back", () => { + // promotion.yml at the root means some pipeline runs promotion, and one + // outside GitHub Actions can't be read at all. + assert.deepEqual( + [ + movesByItself({ "promotion.yml": "version: 1\n" }), + // No promotion and no workflow: nothing commits state after a run. + movesByItself({}), + ], + [false, true], + ); + // With state already in state/, a CI run of that pipeline stops. A person + // promoting from their own machine is not warned on every command. + const root = repo({ + ["state/" + ORG + "/state.json"]: STATE, + "promotion.yml": "version: 1\n", + }); + try { + assert.deepEqual( + [ + /promotion\.yml is set up and no workflow in \.github\/workflows\/ is seen to stage state\//.test( + thrown(() => stateLayoutPrepare(root, ORG, CI)), + ), + stateLayoutPrepare(root, ORG, {}), + ], + [true, []], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("only a git add line that stages state/ or everything counts as seen", () => { + const seen = (line: string) => + movesByItself({ + ".github/workflows/promotion.yml": workflow([ + " - run: |", + ` ${line}`, + " git commit -m state && git push", + ]), + }); + assert.deepEqual( + { + folder: seen("git add -A -- state"), + folderSlash: seen("git add state/"), + folderGlob: seen("git add -A -- ':(glob)state/**'"), + both: seen("git add -A -- state ':(glob).vapi-state.*.json' resources"), + everything: seen("git add -A"), + everythingLong: seen("git add --all"), + dot: seen("git add ."), + chained: seen("git add resources && git add -A -- state"), + // Not seen: something else, one org only, a variable, tracked files only. + resources: seen("git add -A -- resources"), + oneOrg: seen("git add -A -- state/acme"), + variable: seen('git add -A -- "$STATE_PATHS"'), + tracked: seen("git add -u"), + commented: seen("# git add -A -- state"), + lookalike: seen("git add -A -- estate statement"), + }, + { + folder: true, + folderSlash: true, + folderGlob: true, + both: true, + everything: true, + everythingLong: true, + dot: true, + chained: true, + resources: false, + oneOrg: false, + variable: false, + tracked: false, + commented: false, + lookalike: false, + }, + ); +}); + +test("a workflow that can't write to the repository is not a commit step", () => { + const withWorkflow = (lines: string[]) => + movesByItself({ ".github/workflows/ci.yml": `${lines.join("\n")}\n` }); + const job = ["jobs:", " test:", " steps:", " - run: npm test"]; + assert.deepEqual( + { + readOnly: withWorkflow(["permissions:", " contents: read", ...job]), + noContents: withWorkflow(["permissions:", " statuses: write", ...job]), + readAll: withWorkflow(["permissions: read-all", ...job]), + // Anything that may be able to commit is not ruled out. + noPermissions: withWorkflow(job), + writes: withWorkflow(["permissions:", " contents: write", ...job]), + writeAll: withWorkflow(["permissions: write-all", ...job]), + jobWrites: withWorkflow([ + "permissions:", + " contents: read", + ...job, + " permissions:", + " contents: write", + ]), + pushesAnyway: withWorkflow([ + "permissions:", + " contents: read", + ...job, + " - run: git push https://example.invalid/repo.git", + ]), + unreadable: withWorkflow(["jobs: [", " not yaml"]), + }, + { + readOnly: true, + noContents: true, + readAll: true, + noPermissions: false, + writes: false, + writeAll: false, + jobWrites: false, + pushesAnyway: false, + unreadable: false, + }, + ); +}); + +test("the workflows this repository ships are read as staging both places", () => { + const root = repo({}); + try { + cpSync(join(REPO, ".github/workflows"), join(root, ".github/workflows"), { + recursive: true, + }); + assert.deepEqual(commitStepRead(root, {}), { + kind: "seen", + stagesOld: true, + }); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +// ── npm run migrate ────────────────────────────────────────────────────── + +test("migrate says what the commit step has to stage and moves nothing until the person says it does", async () => { + const root = helperRepo({ + ["resources/" + ORG + "/.vapi-org.json"]: '{"orgId":"org-a"}\n', + }); + try { + const first = await migrateAll(root); + const afterFirst = [moved(root), existsSync(commitStepFilePath(root))]; + const second = await migrateAll(root, { commitStepStagesState: true }); + assert.deepEqual( + { + ask: first.commitStepAsk?.filter((line) => + /git add|npm run migrate|Nothing moved/.test(line), + ), + afterFirst, + acknowledged: second.acknowledged, + secondAsk: second.commitStepAsk, + moved: moved(root), + pinMoved: !existsSync(orgPinFileLegacyPath(root, ORG)), + file: readFileSync(commitStepFilePath(root), "utf8"), + // From here on a command on a person's machine has nothing to say. + later: stateLayoutPrepare(root, ORG, {}), + }, + { + ask: [ + "⚠️ Nothing moved into state/: .github/workflows/promotion.yml can commit to this repository and is not seen to stage state/.", + " git add -A -- state 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", + " npm run migrate -- --commit-step-stages-state", + ], + afterFirst: [false, false], + acknowledged: + "✍️ Wrote state/commit-step.json: you said the commit step stages state/. Commit it together with the move.", + secondAsk: undefined, + moved: true, + pinMoved: true, + file: '{\n "stagesStateFolder": true\n}\n', + later: [], + }, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("the flag is refused while a workflow is seen to stage only the old file", async () => { + const root = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": workflow([ + " - run: |", + " git add -A -- ':(glob).vapi-state.*.json'", + " git commit -m state && git push", + ]), + }); + try { + const message = await migrateAll(root, { + commitStepStagesState: true, + }).then( + () => "ran", + (error: unknown) => + error instanceof StateLayoutError ? error.message : "other error", + ); + assert.deepEqual( + [ + /promotion\.yml stages \.vapi-state\.\*\.json but not state\/, so --commit-step-stages-state is not true yet/.test( + message, + ), + existsSync(commitStepFilePath(root)), + moved(root), + ], + [true, false, false], + message, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("the flag writes nothing where the engine can see for itself", async () => { + const root = repo({ [OLD_STATE]: STATE }); + try { + const result = await migrateAll(root, { commitStepStagesState: true }); + assert.deepEqual( + [result.acknowledged, existsSync(commitStepFilePath(root)), moved(root)], + [ + "ℹ️ --commit-step-stages-state is not needed here: nothing in this repository commits state after a run.", + false, + true, + ], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("npm run migrate prints the two paths, exits 0, and rejects an option it doesn't know", () => { + const root = helperRepo(); + 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"); + const run = (...args: string[]) => { + 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}` }; + }; + const plain = run(); + const heldAfterPlain = !moved(root); + const typo = run("--commit-step-stages-stat"); + const heldAfterTypo = !moved(root); + const told = run(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"), + 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], + typo: [1, true, true], + told: [0, true, true], + }, + plain.out + typo.out + told.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 { + const notices = stateLayoutPrepare(root, ORG, CI); + assert.deepEqual( + { + notices, + moved: moved(root), + writes: stateFileWrite(root, ORG, CI), + // An org this run creates goes where the commit step already looks. + newOrg: stateFileWrite(root, "new-org", CI), + newOrgPin: orgPinFileWrite(root, "new-org", CI), + }, + { + notices: [ + "ℹ️ .vapi-state.acme.json stays where it is: .github/workflows/promotion.yml can commit to this repository and is not seen to stage state/. `npm run migrate` says what the commit step has to stage before it can move.", + ], + moved: false, + writes: stateFileLegacyPath(root, ORG), + newOrg: stateFileLegacyPath(root, "new-org"), + newOrgPin: orgPinFileLegacyPath(root, "new-org"), + }, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a CI run stops before it writes state/ that nothing is seen to commit", () => { + const root = repo({ + ["state/" + ORG + "/state.json"]: STATE, + ".github/workflows/promotion.yml": HELPER_WORKFLOW, + }); + try { + const stopped = thrown(() => stateLayoutPrepare(root, ORG, CI)); + // An org with no state yet would be written into state/ too. + const newOrg = thrown(() => stateLayoutPrepare(root, "new-org", CI)); + const onAMachine = stateLayoutPrepare(root, ORG, {}); + writeFileSync(commitStepFilePath(root), '{"stagesStateFolder":true}\n'); + assert.deepEqual( + { + stopped: [ + /promotion\.yml can commit to this repository and is not seen to stage state\/, so state\/acme\/ may never be committed/.test( + stopped, + ), + /Stopped before reading or changing anything/.test(stopped), + stopped.includes("npm run migrate -- --commit-step-stages-state"), + ], + newOrg: /so state\/new-org\/ may never be committed/.test(newOrg), + // The same checkout on a person's machine is warned, not stopped. + onAMachine: onAMachine.map((line) => line.slice(0, 2)), + // Once a person has said the step stages state/, the run goes ahead + // and says whose word it is taking. + acknowledged: stateLayoutPrepare(root, ORG, CI), + }, + { + stopped: [true, true, true], + newOrg: true, + onAMachine: ["⚠️"], + acknowledged: [ + "ℹ️ state/commit-step.json says this run's commit step stages state/. The engine can't see that step: if it doesn't, what this run records in state/acme/ is lost.", + ], + }, + stopped, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("a CI run stops when the old file it would write is no longer what the commit step stages", () => { + const newOnly = repo({ + [OLD_STATE]: STATE, + ".github/workflows/promotion.yml": workflow([ + " - run: |", + " git add -A -- state", + " git commit -m state && git push", + ]), + }); + const saidSo = helperRepo({ + "state/commit-step.json": '{"stagesStateFolder":true}\n', + }); + try { + const first = thrown(() => stateLayoutPrepare(newOnly, ORG, CI)); + const second = thrown(() => stateLayoutPrepare(saidSo, ORG, CI)); + assert.deepEqual( + [ + /\.vapi-state\.acme\.json is still at the repository root, and this repository's workflow stages state\/ but not \.vapi-state\.\*\.json/.test( + first, + ), + /state\/commit-step\.json says the commit step stages state\//.test( + second, + ), + existsSync(stateFileLegacyPath(newOnly, ORG)), + existsSync(stateFileLegacyPath(saidSo, ORG)), + // On a person's machine both simply move. + stateLayoutPrepare(newOnly, ORG, {}).length, + moved(newOnly), + stateLayoutPrepare(saidSo, ORG, {}).length, + moved(saidSo), + ], + [true, true, true, true, 1, true, 1, true], + first + second, + ); + } finally { + rmSync(newOnly, { recursive: true, force: true }); + rmSync(saidSo, { recursive: true, force: true }); + } +}); + +test("in GitHub Actions the run is judged by the workflow that is running it", () => { + const root = repo({ + ["state/" + ORG + "/state.json"]: STATE, + ".github/workflows/promotion.yml": workflow([ + " - run: |", + " git add -A -- state ':(glob).vapi-state.*.json'", + " git commit -m state && git push", + ]), + // Another workflow that can commit and stages nothing the engine reads. + ".github/workflows/deploy.yml": workflow([" - run: ./deploy.sh"]), + }); + const actions = (file: string): NodeJS.ProcessEnv => ({ + GITHUB_ACTIONS: "true", + GITHUB_WORKFLOW_REF: `acme/repo/.github/workflows/${file}@refs/heads/main`, + }); + try { + assert.deepEqual( + [ + thrown(() => stateLayoutPrepare(root, ORG, actions("promotion.yml"))), + /deploy\.yml can commit to this repository and is not seen to stage state\//.test( + thrown(() => stateLayoutPrepare(root, ORG, actions("deploy.yml"))), + ), + // With no workflow named, every workflow has to be seen. + /deploy\.yml/.test( + thrown(() => + stateLayoutPrepare(root, ORG, { GITHUB_ACTIONS: "true" }), + ), + ), + ], + ["ran", true, true], + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); From c6262a8999ea8b52bd961244b195bede36e44aba Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Wed, 18 Nov 2026 11:13:25 -0800 Subject: [PATCH 06/10] fix(state): only migrate moves committed state An org is in one layout, decided by where its committed state file is. Pull, push, apply and promote read and write the layout they find, on a person's machine and in CI, and print one line saying the newer one exists. npm run migrate is the only command that moves state, after saying what the commit step has to stage. The commit-step reader fails closed: a git add counts only as a plain command at the repository root that names state or stages everything. With nothing seen, migrate asks for --commit-step-stages-state. Pull no longer reads "edited since the last sync" off the state file's timestamp, which in a fresh clone is the order git wrote the files in. It compares against the moment this machine's engine last saved state, and a clone with no such save keeps every file. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- .gitignore | 6 +- docs/guides/commands.md | 152 ++-- docs/guides/workflows.md | 11 +- docs/learnings/sync-behavior.md | 2 +- improvements.md | 45 +- src/apply.ts | 15 +- src/commit-step.ts | 459 +++++++++++++ src/hash-store.ts | 45 +- src/migrate-cmd.ts | 36 +- src/migrate-hash-store.ts | 53 +- src/promote-cmd.ts | 14 +- src/pull.ts | 30 +- src/snapshot.ts | 23 +- src/state-paths.ts | 715 ++++++++++--------- src/state.ts | 25 +- state/README.md | 4 +- tests/check-cmd.test.ts | 4 +- tests/org-pin.test.ts | 5 +- tests/promotion-workflow-commit.test.ts | 26 +- tests/state-layout-unseen-commit.test.ts | 837 ++++++++++++++--------- tests/state-layout.test.ts | 692 ++++++++++++------- tests/state-move-second-round.test.ts | 286 ++++++++ 22 files changed, 2389 insertions(+), 1096 deletions(-) create mode 100644 src/commit-step.ts create mode 100644 tests/state-move-second-round.test.ts diff --git a/.gitignore b/.gitignore index 7b5a5f6..fcd0516 100644 --- a/.gitignore +++ b/.gitignore @@ -31,8 +31,10 @@ tmp/ # snapshots/ copies written by `npm run push` for `npm run rollback`. state/*/local/ -# The same two stores where they sat before state/ existed. The engine moves -# them on the next pull, push or apply; until then they stay out of git. +# 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/ .vapi-state-hash/ diff --git a/docs/guides/commands.md b/docs/guides/commands.md index fcd7514..db196bd 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -193,7 +193,13 @@ The test-call CLI cleans its terminal output for the developer loop: ## Upgrading from an older version -`npm run migrate` brings an older repository up to date. It needs no org and +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 @@ -202,10 +208,25 @@ git add -A -- state ':(glob).vapi-state.*.json' resources git commit -m "chore: move engine state into state/" ``` -It does two things. +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: -**Moves engine files into `state//`.** They used to sit under dot-names -in three places. Nothing changes inside the files. +```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 | | --- | --- | @@ -214,38 +235,17 @@ in three places. Nothing changes inside the files. | `.vapi-state-hash//` | `state//local/baselines/` | | `.vapi-state..snapshots/` | `state//local/snapshots/` | -You don't have to run it for this: the engine keeps reading the old places, -and the next `pull`, `push` or `apply` on your machine moves that org and -says so in one line. Either way, commit the removal of the old file together -with the new folder. - -**State moves only when the engine can see it will still be committed.** A -promotion run in CI writes the state file and leaves committing it to a later -step. If that step stages only the old file, a move takes the UUID map out of -git: every run still passes, and the next one creates every resource again. -So the move is held back in three cases, and the command tells you which: - -- **In a CI run.** State stays where it is and is updated in place. Run - `npm run migrate` on your machine and commit the result. -- **When a workflow under `.github/workflows/` stages `.vapi-state.*.json` but - not `state/`.** That workflow would commit the old file's removal without - the new one. Take upstream's `promotion.yml` workflow, or add - `git add -A -- state` to your own commit step, then run `npm run migrate`. -- **When something may commit state and the engine can't see it stage - `state/`.** That is a workflow that can write to the repository and has no - `git add` line for `state` (it stages through a script, a commit action or - a variable), or a root `promotion.yml` with no workflow in the repository - that stages `state/` (the pipeline runs somewhere the engine can't read). - `npm run migrate` then moves nothing and prints what the commit step has to - stage: - - ```bash - git add -A -- state # the new folder - git add -A -- ':(glob).vapi-state.*.json' # the old files, so their removal is committed - ``` +What it does depends on what it reads in `.github/workflows/`: - A commit action or a script needs the same two paths. When your step - stages both, say so: +- **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 @@ -254,19 +254,6 @@ So the move is held back in three cases, and the command tells you which: That writes `state/commit-step.json` and moves every org. Commit it with the move. -What counts as seen: a `git add` line in a workflow file that names `state` -(or `state/`, `state/**`), or one that stages everything (`git add -A`, -`git add .`). A workflow whose `permissions` keep `contents` read-only, and -that never runs `git commit` or `git push`, is not a commit step, so -upstream's `ci.yml` and `vapi-checks.yml` hold nothing back. - -A CI run also stops, before it sends any request, when it would write state -in a place its commit step isn't seen to stage: state already in `state/` -under a step that stages only the old file or can't be read, or state still -at the root under a step that stages only `state/`. In GitHub Actions the -engine checks the workflow that is running it. Anywhere else it checks every -workflow in the repository. - > **`--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 @@ -274,29 +261,80 @@ workflow in the repository. > a workflow is plainly seen to stage the old file alone. To take it back, > delete `state/commit-step.json`. -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. - **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. + ### What you'll see after upgrading -- **`📦 Moved … into state//`**, once per org, on the first `pull`, - `push` or `apply` on your machine. -- **`📦 1 locally modified file(s) will be preserved`** on the first `pull` - after the move. The file is the old org pin, +- **`ℹ️ Engine state here is in the older layout …`**, one line per writing + command, until you run `npm run migrate`. Nothing else changes. + +After `npm run migrate`: + +- **`📦 Moved … into state//`**, once per org, from `migrate` itself. +- **`📦 1 locally modified file(s) will be preserved`** on a `pull` before you + commit the move. The file is the old org pin, `resources//.vapi-org.json`. It moved to `state//org.json`, so git shows it as deleted until you commit. Pull does nothing differently because of it. -- **`… stays where it is: …`** on every writing command while the move is - held back. The line says why. +- **`📦 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 diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index 21a8c46..4876762 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -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 `state//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 diff --git a/docs/learnings/sync-behavior.md b/docs/learnings/sync-behavior.md index 9fee1d2..54d1b14 100644 --- a/docs/learnings/sync-behavior.md +++ b/docs/learnings/sync-behavior.md @@ -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) | diff --git a/improvements.md b/improvements.md index cb0c85d..c366b10 100644 --- a/improvements.md +++ b/improvements.md @@ -2123,23 +2123,40 @@ 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: every command reads the old places, and -the next `pull`, `push` or `apply` on a person's machine moves the org with -one rename per file and prints one line. The move fails closed: it happens -only when a workflow is seen to stage `state/`, or when nothing in the -repository commits state after a run. It is held back in a CI run, while a -workflow stages `.vapi-state.*.json` but not `state/`, and while a commit -step can't be read (a script, a commit action, a pipeline outside GitHub -Actions) until a person says it stages `state/` with -`npm run migrate -- --commit-step-stages-state`. A CI run stops before any -request when it would write state where its commit step isn't seen to look. -The promotion workflow stages both places. `tests/state-layout.test.ts`, -`tests/state-layout-unseen-commit.test.ts` and +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. -One limit remains. The flag is a person's word. If it is given and the commit +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. + +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. The engine can't see a step it can't read. +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 diff --git a/src/apply.ts b/src/apply.ts index 5981108..579fd5b 100644 --- a/src/apply.ts +++ b/src/apply.ts @@ -3,7 +3,11 @@ import { dirname, join, resolve } from "path"; import { fileURLToPath } from "url"; import { parseAdoptArgs } from "./adopt.ts"; import { assertStateMigrated } from "./migrate-hash-store.ts"; -import { stateFileRead, stateLayoutPrepare } from "./state-paths.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"; @@ -42,11 +46,12 @@ export async function runApply(): Promise { const hasForce = allArgs.includes("--force"); const dryRun = allArgs.includes("--dry-run"); - // Move an old-layout state file into state// once, here, and fail fast - // with one clear message if it is still in the legacy format, rather than - // letting the spawned pull/push subprocess surface either 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)) { - for (const line of stateLayoutPrepare(BASE_DIR, env)) console.log(line); + stateNoticesPrint(stateLayoutPrepare(BASE_DIR, env)); assertStateMigrated(stateFileRead(BASE_DIR, env)); } 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/hash-store.ts b/src/hash-store.ts index 23d27c1..6740569 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 `state//local/baselines/` — 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. // @@ -21,7 +22,11 @@ import { existsSync, mkdirSync, readFileSync } from "fs"; import { rename, writeFile } from "fs/promises"; import { dirname, join } from "path"; import { fileURLToPath } from "url"; -import { baselinesDir, baselinesLegacyDir } from "./state-paths.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)), ".."); @@ -37,30 +42,33 @@ function assertSafeUuid(uuid: string): void { } } +// 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 baselinesDir(BASE_DIR, 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); -} - -function baselineLegacyPath(org: string, uuid: string): string { - assertSafeUuid(uuid); - return join(baselinesLegacyDir(BASE_DIR, 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. // -// A baseline written before state/ existed sits in .vapi-state-hash// -// until the next pull, push or apply moves the folder. Read it from there -// meanwhile, so a read-only command sees the same drift as before. +// 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), baselineLegacyPath(org, uuid)].find( - (candidate) => existsSync(candidate), + const path = baselinePaths(org, uuid).find((candidate) => + existsSync(candidate), ); if (!path) return undefined; const contents = readFileSync(path, "utf-8").trim(); @@ -76,7 +84,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`); @@ -88,6 +96,5 @@ export async function writeBaseline( // `delete stateSection[resourceId]` recovery. Missing file is a no-op. export async function deleteBaseline(org: string, uuid: string): Promise { const { rm } = await import("fs/promises"); - await rm(baselinePath(org, uuid), { force: true }); - await rm(baselineLegacyPath(org, uuid), { force: true }); + for (const path of baselinePaths(org, uuid)) await rm(path, { force: true }); } diff --git a/src/migrate-cmd.ts b/src/migrate-cmd.ts index 65a5dcf..a3c955c 100644 --- a/src/migrate-cmd.ts +++ b/src/migrate-cmd.ts @@ -8,14 +8,24 @@ // // 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 { COMMIT_STEP_FLAG } from "./state-paths.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( @@ -33,10 +43,16 @@ async function main(): Promise { `Unrecognized argument: ${unknown.join(" ")}. The only option is ${COMMIT_STEP_FLAG}.`, ); - const result = await migrateAll(undefined, { - commitStepStagesState: args.includes(COMMIT_STEP_FLAG), - }); - if (result.acknowledged) console.log(` ${result.acknowledged}\n`); + 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 state files found — nothing to migrate."); @@ -54,14 +70,18 @@ async function main(): Promise { `${status} — seeded ${org.seeded} baseline(s)` + (org.skipped > 0 ? `, ${org.skipped} already present` : ""), ); - for (const notice of org.notices) console.log(` ${notice}`); + 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.`, ); - if (result.commitStepAsk) console.log(`\n${result.commitStepAsk.join("\n")}`); + 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 acb8296..60e14a6 100644 --- a/src/migrate-hash-store.ts +++ b/src/migrate-hash-store.ts @@ -19,10 +19,11 @@ import { writeBaseline, } from "./hash-store.ts"; import { - commitStepAcknowledge, + STATE_DIR, commitStepAsk, stateFileRead, - stateLayoutPrepare, + stateMove, + stateMoveRead, stateOrgsList, } from "./state-paths.ts"; import { asResourceState, sortedKeysReplacer } from "./state-serialize.ts"; @@ -37,22 +38,15 @@ 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 - notices: string[]; // what moved into state//, or why it stayed + moved: string[]; // what moved into state//; empty when nothing did } export interface MigrationResult { orgs: OrgMigrationResult[]; - /** What was written down when the person said their commit step stages state/. */ - acknowledged?: string; /** Set when nothing moved: what the commit step has to stage first. */ commitStepAsk?: string[]; } -export interface MigrationOptions { - /** The person says the step that commits state stages state/ (`--commit-step-stages-state`). */ - commitStepStagesState?: boolean; -} - // A legacy entry is anything that isn't already exactly `{ uuid: string }`: // a bare string (oldest form) or an object carrying extra fields // (lastPulledHash / lastPulledAt / lastPushedHash / platformVersionId). @@ -94,6 +88,7 @@ function isSection(value: unknown): value is Record { async function migrateOne( baseDir: string, org: string, + move: boolean, ): Promise { const stateFilePath = stateFileRead(baseDir, org); const raw = JSON.parse(readFileSync(stateFilePath, "utf-8")) as Record< @@ -144,21 +139,15 @@ async function migrateOne( } // Slim first, in place, then move: each step leaves one complete state - // file. An explicit migrate moves state even in a CI run, because whoever - // runs it there commits the result; a commit step that would drop state/, - // or isn't seen to stage it, still stops the move. - const notices = stateLayoutPrepare(baseDir, org, { - ...process.env, - CI: "", - GITHUB_ACTIONS: "", - }); + // file. + const moved = move ? stateMove(baseDir, org) : []; return { org, stateFile: relative(baseDir, stateFileRead(baseDir, org)), seeded, skipped, slimmed: needsSlim, - notices, + moved, }; } @@ -167,20 +156,30 @@ async function migrateOne( // engine files into `state//`. Idempotent — re-running on a migrated // repo seeds nothing, rewrites nothing and moves nothing. // -// Where nothing is seen to stage state/ after a run, files are slimmed in -// place and nothing moves until the person says their commit step stages it. +// 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, - options: MigrationOptions = {}, ): Promise { - const acknowledged = options.commitStepStagesState - ? commitStepAcknowledge(baseDir) - : undefined; + const { open } = stateMoveRead(baseDir); const orgs: OrgMigrationResult[] = []; for (const org of stateOrgsList(baseDir)) { - orgs.push(await migrateOne(baseDir, org)); + orgs.push(await migrateOne(baseDir, org, open)); } - return { orgs, acknowledged, commitStepAsk: commitStepAsk(baseDir) }; + 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 diff --git a/src/promote-cmd.ts b/src/promote-cmd.ts index dfd6564..da1b31b 100644 --- a/src/promote-cmd.ts +++ b/src/promote-cmd.ts @@ -4,7 +4,12 @@ import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import type { CheckDefinition } from "./check-config.ts"; import type { OrgConnection } from "./org-connection.ts"; -import { stateFileRead } from "./state-paths.ts"; +import { + OLD_LAYOUT_NOTICE, + stateFileRead, + stateLayout, + stateNoticesPrint, +} from "./state-paths.ts"; import { childRun, connectionLoad, tokensParse } from "./org-connection.ts"; import type { PromotionConfig, PromotionPipeline } from "./promotion.ts"; import type { PromotionGateResult } from "./promotion-gate.ts"; @@ -328,6 +333,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 00c1a4d..83742dd 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -47,7 +47,7 @@ import { stateWritePrepare, upsertState, } from "./state.ts"; -import { stateFileRead } from "./state-paths.ts"; +import { stateSavedStampPath } from "./state-paths.ts"; import type { ResourceState, ResourceType, StateFile } from "./types.ts"; // Map resource types to their API endpoints @@ -959,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 && @@ -974,19 +978,15 @@ export async function pullResourceType( join(dir, `${resourceId}.yaml`), ].find((p) => existsSync(p)); if (localFile) { - const stateFilePath = stateFileRead(BASE_DIR, VAPI_ENV); - 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; } } } diff --git a/src/snapshot.ts b/src/snapshot.ts index 81c2241..f7a6bb2 100644 --- a/src/snapshot.ts +++ b/src/snapshot.ts @@ -18,19 +18,28 @@ import { existsSync } from "fs"; import { mkdir, readdir, readFile, writeFile } from "fs/promises"; import { join } from "path"; -import { snapshotsDir, snapshotsLegacyDir } from "./state-paths.ts"; +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 snapshotsDir(baseDir, env); + return snapshotsWriteDir(baseDir, env); } -// Snapshots written before state/ existed stay readable until the next pull, -// push or apply moves them, so a rollback right after upgrading still works. +// 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[] { - return [snapshotsDir(baseDir, env), snapshotsLegacyDir(baseDir, env)].filter( - (root) => existsSync(root), - ); + const roots = new Set([ + snapshotsRoot(baseDir, env), + snapshotsDir(baseDir, env), + snapshotsLegacyDir(baseDir, env), + ]); + return [...roots].filter((root) => existsSync(root)); } let activeRunDir: string | null = null; diff --git a/src/state-paths.ts b/src/state-paths.ts index 8201962..65e72ad 100644 --- a/src/state-paths.ts +++ b/src/state-paths.ts @@ -11,7 +11,11 @@ // // 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: it reads the old one, and moves it when that is safe. +// 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. @@ -27,8 +31,10 @@ import { unlinkSync, writeFileSync, } from "fs"; -import { dirname, join } from "path"; -import { parse as parseYaml } from "yaml"; +import { dirname, join, relative } from "path"; +import { commitStepRead } from "./commit-step.ts"; + +export { commitStepRead }; export const STATE_DIR = "state"; @@ -76,34 +82,6 @@ export function snapshotsLegacyDir(rootDir: string, org: string): string { return join(rootDir, `.vapi-state.${org}.snapshots`); } -/** The state file as a person names it: its path from the repository root. */ -export function stateFileLabel(rootDir: string, org: string): string { - return existsSync(stateFilePath(rootDir, org)) || - !existsSync(stateFileLegacyPath(rootDir, org)) - ? `${STATE_DIR}/${org}/state.json` - : `.vapi-state.${org}.json`; -} - -function firstExisting(next: string, legacy: string): string { - return existsSync(next) || !existsSync(legacy) ? next : legacy; -} - -/** The state file to read: state//state.json, else the old root file. */ -export function stateFileRead(rootDir: string, org: string): string { - return firstExisting( - stateFilePath(rootDir, org), - stateFileLegacyPath(rootDir, org), - ); -} - -/** The org pin to read: state//org.json, else the old file in resources/. */ -export function orgPinFileRead(rootDir: string, org: string): string { - return firstExisting( - orgPinFilePath(rootDir, org), - orgPinFileLegacyPath(rootDir, org), - ); -} - /** Orgs that have a state file in either layout, sorted. */ export function stateOrgsList(rootDir: string): string[] { const orgs = new Set(); @@ -119,139 +97,12 @@ export function stateOrgsList(rootDir: string): string[] { return [...orgs].sort((a, b) => a.localeCompare(b)); } -// ── Who commits state after a run ──────────────────────────────────────── -// -// A run in CI writes the state file and leaves committing it to a later step -// the engine can't watch. If that step stages only the place state used to -// be, moving state takes the UUID map out of git: every run still passes, and -// the next one creates every resource again. So state moves by itself only -// when a workflow is seen to stage state/, or when nothing in the repository -// can commit state after a run. A step the engine can't read is not seen. - -interface WorkflowRead { - file: string; - /** A `git add` line stages state/. */ - stagesNew: boolean; - /** A `git add` line stages .vapi-state.*.json. */ - stagesOld: boolean; - /** False only when the file is read as unable to write to the repository. */ - canCommit: boolean; -} +// ── Which layout an org is in ──────────────────────────────────────────── function isRecord(value: unknown): value is Record { return value !== null && typeof value === "object" && !Array.isArray(value); } -// What a workflow's `git add` lines stage. A pathspec the engine can't read -// (a variable, one org's folder) counts for nothing. -function gitAddsRead(text: string): { stagesNew: boolean; stagesOld: boolean } { - let stagesNew = false; - let stagesOld = false; - for (const line of text.replace(/\\\r?\n/g, " ").split("\n")) { - if (/^\s*#/.test(line)) continue; - for (const command of line.replace(/\s#.*$/, "").split(/&&|\|\||;/)) { - const at = command.search(/\bgit add\b/); - if (at < 0) continue; - const args = command - .slice(at + "git add".length) - .split(/\s+/) - .filter(Boolean) - .map((arg) => arg.replace(/^["']|["']$/g, "")); - const paths = args - .filter((arg) => !arg.startsWith("-")) - .map((path) => path.replace(/^:\([a-z,]*\)/, "").replace(/^\.\//, "")); - const everything = - paths.length === 0 - ? args.some((arg) => arg === "--all" || /^-[a-zA-Z]*A/.test(arg)) - : paths.some((path) => path === "." || path === ":/"); - if (everything || paths.some((path) => /^state(\/\**)?$/.test(path))) - stagesNew = true; - if (everything || paths.some((path) => path.includes(".vapi-state."))) - stagesOld = true; - } - } - return { stagesNew, stagesOld }; -} - -// Only a workflow whose permissions keep `contents` read-only in every job, -// and that never runs `git commit` or `git push`, is read as unable to commit. -// A file that doesn't parse, or sets no permissions, can. -function workflowCanCommit(text: string): boolean { - if (/\bgit\s+(commit|push)\b/.test(text)) return true; - let doc: unknown; - try { - doc = parseYaml(text); - } catch { - return true; - } - if (!isRecord(doc) || !isRecord(doc.jobs)) return true; - const writes = (permissions: unknown): boolean | undefined => - permissions === undefined - ? undefined - : permissions === "write-all" || - (isRecord(permissions) && permissions.contents === "write"); - const top = writes(doc.permissions); - return Object.values(doc.jobs).some( - (job) => - (isRecord(job) ? writes(job.permissions) : undefined) ?? top ?? true, - ); -} - -function workflowsRead(rootDir: string): WorkflowRead[] { - const dir = join(rootDir, ".github", "workflows"); - if (!existsSync(dir)) return []; - return readdirSync(dir) - .filter((name) => /\.ya?ml$/.test(name)) - .sort() - .map((name) => { - const text = readFileSync(join(dir, name), "utf8"); - return { - file: `.github/workflows/${name}`, - ...gitAddsRead(text), - canCommit: workflowCanCommit(text), - }; - }); -} - -export type CommitStep = - /** A workflow is seen to stage the old state file and not state/. */ - | { kind: "stale"; file: string } - /** Something may commit state after a run, and it isn't seen to stage state/. */ - | { kind: "unseen"; file?: string } - /** Every workflow that can commit is seen to stage state/. */ - | { kind: "seen"; stagesOld: boolean } - /** Nothing here commits state after a run. */ - | { kind: "none" }; - -/** - * 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/. With no - * workflow that can commit, a root promotion.yml still means some pipeline - * runs promotion and commits what it records. - */ -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((w) => w.stagesOld && !w.stagesNew); - if (stale) return { kind: "stale", file: stale.file }; - const unseen = workflows.find((w) => w.canCommit && !w.stagesNew); - if (unseen) return { kind: "unseen", file: unseen.file }; - if (workflows.some((w) => w.stagesNew)) - return { kind: "seen", stagesOld: workflows.some((w) => w.stagesOld) }; - return own.length === 0 && existsSync(join(rootDir, "promotion.yml")) - ? { kind: "unseen" } - : { kind: "none" }; -} - /** 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 { @@ -264,127 +115,129 @@ export function commitStepAcknowledged(rootDir: string): boolean { } } -function unseenReason(file: string | undefined): string { - return file - ? `${file} can commit to this repository and is not seen to stage ${STATE_DIR}/` - : `promotion.yml is set up and no workflow in .github/workflows/ is seen to stage ${STATE_DIR}/`; -} - -export type StateMoveBlocker = - | { kind: "workflow"; file: string } - | { kind: "unseen"; file?: string } - | { kind: "ci" }; - -export function stateRunIsCi(env: NodeJS.ProcessEnv = process.env): boolean { - return env.CI === "true" || env.CI === "1" || env.GITHUB_ACTIONS === "true"; -} +export type StateLayout = "folder" | "root"; /** - * Why committed state must stay where it is for now. A workflow seen to stage - * only the old file holds it, and so does a commit step that isn't seen to - * stage state/ until a person says it does. A CI run never moves state: only - * the person who changes the commit step can commit the move with it. + * 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 stateMoveBlocker( - rootDir: string, - env: NodeJS.ProcessEnv = process.env, -): StateMoveBlocker | undefined { - const step = commitStepRead(rootDir, env); - if (step.kind === "stale") return { kind: "workflow", file: step.file }; - if (step.kind === "unseen" && !commitStepAcknowledged(rootDir)) - return { kind: "unseen", file: step.file }; - return stateRunIsCi(env) ? { kind: "ci" } : undefined; +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"; } -/** - * What the commit step has to stage before state can move, when nothing is - * seen to stage state/ and nobody has said it does. For `npm run migrate`. - */ -export function commitStepAsk(rootDir: string): string[] | undefined { - const blocker = stateMoveBlocker(rootDir, {}); - if (blocker?.kind !== "unseen") return undefined; - return [ - `⚠️ Nothing moved into ${STATE_DIR}/: ${unseenReason(blocker.file)}.`, - " Whatever commits state after a run in this repository 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.", - " 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.`, - ]; +// 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; } -/** - * 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 !== "unseen") - return `ℹ️ ${COMMIT_STEP_FLAG} is not needed here: ${step.kind === "seen" ? `a workflow is seen to stage ${STATE_DIR}/` : "nothing in this repository commits state after a run"}.`; - 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`, +/** 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, ); - return `✍️ Wrote ${STATE_DIR}/commit-step.json: you said the commit step stages ${STATE_DIR}/. Commit it together with the move.`; } -// A repository that has any old root state file still follows the old layout. -function legacyStateExists(rootDir: string): boolean { - return readdirSync(rootDir).some((name) => - /^\.vapi-state\..+\.json$/.test(name), +/** 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, ); } -// A file that exists is written in place. A file that doesn't exist yet goes -// to state//, except where the commit step is seen to stage only the old -// place, or isn't seen at all in a repository that still has old state files. -function legacyLayoutKept( - rootDir: string, - org: string, - env: NodeJS.ProcessEnv, -): boolean { - if (existsSync(stateFilePath(rootDir, org))) return false; - if (existsSync(stateFileLegacyPath(rootDir, org))) return true; - const blocker = stateMoveBlocker(rootDir, env); - if (blocker?.kind === "workflow") return true; - return blocker?.kind === "unseen" && legacyStateExists(rootDir); +/** 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("\\", "/"); } -/** The state file to write. Call stateLayoutPrepare first in a command that writes. */ -export function stateFileWrite( - rootDir: string, - org: string, - env: NodeJS.ProcessEnv = process.env, -): string { - return legacyLayoutKept(rootDir, org, env) - ? stateFileLegacyPath(rootDir, org) - : stateFilePath(rootDir, org); +/** 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); } -/** The org pin to write: beside the state file, in whichever layout it uses. */ -export function orgPinFileWrite( - rootDir: string, - org: string, - env: NodeJS.ProcessEnv = process.env, -): string { - const next = orgPinFilePath(rootDir, org); - const legacy = orgPinFileLegacyPath(rootDir, org); - if (existsSync(next)) return next; - if (existsSync(legacy)) return legacy; - return legacyLayoutKept(rootDir, org, env) ? legacy : next; +/** 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`, + }, + ]; } export class StateLayoutError extends Error {} @@ -414,6 +267,55 @@ function sameJson(a: string, b: string): boolean { } } +// 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}/`; +} + +/** 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 { @@ -433,8 +335,9 @@ function localDirMove(legacy: string, next: string): boolean { } /** - * Move this machine's baselines and snapshots into state//local/. - * They are gitignored in both places, so no workflow can lose them. + * 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[] = []; @@ -453,122 +356,212 @@ export function stateLocalMove(rootDir: string, org: string): string[] { } /** - * Bring one org's engine files into state// when that is safe, before a - * command writes anything. Returns the lines to print. + * 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. * - * Each committed file moves by one rename, so the full state is always in - * exactly one of the two places. Throws StateLayoutError, before anything is - * read or changed, when both places hold a file and they disagree, or when a - * CI run would write state in a place its commit step isn't seen to stage. + * 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 files = [ - { - 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`, - }, - ].filter((file) => existsSync(file.legacy)); + const both = committedInBothPlaces(rootDir, org); + const layout = stateLayout(rootDir, org); + const notices: string[] = []; - for (const file of files) - if (existsSync(file.next) && !sameJson(file.legacy, file.next)) + 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( - `${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}.`, + `${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.`, ); - - const notices: string[] = []; - const blocker = stateMoveBlocker(rootDir, env); - const ci = stateRunIsCi(env); - const step = commitStepRead(rootDir, env); - const inFolder = - stateFileWrite(rootDir, org, env) === stateFilePath(rootDir, org); - if ( - inFolder && - (blocker?.kind === "workflow" || blocker?.kind === "unseen") - ) { - const problem = - blocker.kind === "workflow" - ? `${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/, so it won't commit ${STATE_DIR}/${org}/.` - : `${unseenReason(blocker.file)}, so ${STATE_DIR}/${org}/ may never be committed.`; - const fix = - blocker.kind === "workflow" - ? `Add \`git add -A -- ${STATE_DIR}\` to that step.` - : `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.`; - if (ci) + if (layout === "folder" && step.kind === "unseen" && !said) throw new StateLayoutError( - `${problem}\n Stopped before reading or changing anything: UUIDs recorded by this run would be lost.\n ${fix}`, + `${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.`, ); - // With only a promotion.yml to go on there may be no pipeline at all, so - // a person's machine isn't warned on every command. A CI run still stops. - if (blocker.kind === "workflow" || blocker.file) - notices.push(`⚠️ ${problem} ${fix}`); - } - // The mirror case: state still at the old place, under a commit step that - // has moved on to state/. - if (ci && !inFolder && 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" && commitStepAcknowledged(rootDir) - ? `${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.", + // 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 (ci && inFolder && step.kind === "unseen") - 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, OLD_LAYOUT_NOTICE]; const moved = stateLocalMove(rootDir, org); - // Same content in both places: an earlier move was cut short, or a merge - // brought the old file back unchanged. The old copy carries nothing. - for (const file of files.filter((entry) => existsSync(entry.next))) { - unlinkSync(file.legacy); - moved.push(file.legacyLabel); - } - const pending = files.filter((file) => !existsSync(file.next)); - const committedMoved = pending.length > 0 && !blocker; - if (committedMoved) - for (const file of pending) { - mkdirSync(dirname(file.next), { recursive: true }); - renameSync(file.legacy, file.next); - moved.push(file.legacyLabel); - } if (moved.length > 0) notices.push( - `📦 Moved ${moved.join(", ")} into ${STATE_DIR}/${org}/.` + - (moved.some((label) => !label.endsWith("/")) - ? " Commit the removal together with the new folder." - : ""), + `📦 Moved ${moved.join(", ")} into ${STATE_DIR}/${org}/local/. Both places are gitignored.`, ); - if (pending.length > 0 && blocker) { - const where = pending.map((file) => file.legacyLabel).join(" and "); + if (both.length > 0) notices.push( - blocker.kind === "ci" - ? `ℹ️ ${where} stays where it is: a CI run never moves state. Run \`npm run migrate\` on your machine and commit the result to move it into ${STATE_DIR}/${org}/.` - : blocker.kind === "workflow" - ? `⚠️ ${where} stays where it is: ${blocker.file} stages .vapi-state.*.json but not ${STATE_DIR}/. Add \`git add -A -- ${STATE_DIR}\` to that step, then run \`npm run migrate\`.` - : `ℹ️ ${where} stays where it is: ${unseenReason(blocker.file)}. \`npm run migrate\` says what the commit step has to stage before it can move.`, + `ℹ️ ${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) { + 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 0e7581f..87cba5b 100644 --- a/src/state.ts +++ b/src/state.ts @@ -1,12 +1,15 @@ -import { existsSync, mkdirSync, readFileSync } from "fs"; -import { rename, writeFile } from "fs/promises"; +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, @@ -71,15 +74,14 @@ export function createEmptyState(): StateFile { } /** - * Run at the start of a command that writes state, before any request: move - * the old layout into state// when that is safe (state-paths.ts), then - * refuse a state file still in the legacy per-resource-hash format. + * 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 it leaves the old layout where it is. + // A dry run writes nothing, so there is nothing to check or say. if (!options.dryRun) - for (const line of stateLayoutPrepare(BASE_DIR, VAPI_ENV)) - console.log(line); + stateNoticesPrint(stateLayoutPrepare(BASE_DIR, VAPI_ENV)); assertStateMigrated(stateFileRead(BASE_DIR, VAPI_ENV)); } @@ -146,5 +148,12 @@ export async function saveState(state: StateFile): Promise { const tmpPath = `${statePath}.tmp`; await writeFile(tmpPath, JSON.stringify(state, sortedKeysReplacer, 2) + "\n"); 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/state/README.md b/state/README.md index 8c18083..f3e5a8d 100644 --- a/state/README.md +++ b/state/README.md @@ -23,6 +23,6 @@ Everything under `resources//`, including `resources//.vapi-ignore`, i ## 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 still reads them there. The next `npm run pull`, `npm run push` or `npm run apply` on your machine moves them here and says so in one line. Commit the removal of the old file together with the new folder. `npm run migrate` moves every org at once. +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. -A CI run never moves them, and no command does while the engine can't see that the step committing state after a run stages this folder. See [Upgrading from an older version](../docs/guides/commands.md#upgrading-from-an-older-version). +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/check-cmd.test.ts b/tests/check-cmd.test.ts index 57b1fd3..91b4503 100644 --- a/tests/check-cmd.test.ts +++ b/tests/check-cmd.test.ts @@ -135,7 +135,9 @@ test("a missing state file is a warning, not an error", async () => { assert.deepEqual( [ result.code, - result.out.includes("⚠️ no state/parity/state.json"), + // 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")), ], [0, true, false], diff --git a/tests/org-pin.test.ts b/tests/org-pin.test.ts index 79ee40e..4034d6a 100644 --- a/tests/org-pin.test.ts +++ b/tests/org-pin.test.ts @@ -23,7 +23,7 @@ import { orgPinCheck, orgPinRead, } from "../src/org-pin.ts"; -import { orgPinFilePath } from "../src/state-paths.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 @@ -104,6 +104,9 @@ 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 }); assert.deepEqual(outcome, { kind: "pinned", orgId: "org-a" }); diff --git a/tests/promotion-workflow-commit.test.ts b/tests/promotion-workflow-commit.test.ts index 3ba3211..46d795e 100644 --- a/tests/promotion-workflow-commit.test.ts +++ b/tests/promotion-workflow-commit.test.ts @@ -12,7 +12,12 @@ import { dirname, join } from "node:path"; import test from "node:test"; import { fileURLToPath } from "node:url"; import { parse as parseYaml } from "yaml"; -import { StateLayoutError, stateLayoutPrepare } from "../src/state-paths.ts"; +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) @@ -75,8 +80,9 @@ function repoReset( `version: 1\norgs:\n${orgs.map((org) => ` ${org}: {}`).join("\n")}\npipelines:\n${pipelineYaml}\n`, ); for (const org of orgs) write(`state/${org}/state.json`, "{}\n"); - // The repository carries the workflow whose commit step runs here: the - // engine moves state only under a commit step it can see stages state/. + // 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"), @@ -284,8 +290,8 @@ test("a repository that has not moved its state still commits the root state fil 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(); - // What `npm run migrate` does before the promotion in the same run. - for (const org of ["a", "b"]) stateLayoutPrepare(CLONE, org, {}); + // `npm run migrate`, then a promotion, committed by the same run. + await migrateAll(CLONE); const failure = await promote(); const step = commitStep("success"); assert.deepEqual( @@ -311,7 +317,7 @@ test("a move is committed whole: the old file's removal and the new file in one test("a failed promotion after a move still commits the move whole", async () => { repoResetOldLayout(); - for (const org of ["a", "b"]) stateLayoutPrepare(CLONE, org, {}); + await migrateAll(CLONE); const failure = await promote(1); const step = commitStep("failure"); assert.deepEqual( @@ -403,8 +409,10 @@ test("under a commit step the engine can't read, state stays at the root and kee 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, then the run in CI. + // 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" }), ); @@ -420,8 +428,9 @@ test("under a commit step the engine can't read, state stays at the root and kee ); assert.deepEqual( { - held: [...local, ...run].every((line) => /stays where it is/.test(line)), + held: [...local, ...run].every((line) => line === OLD_LAYOUT_NOTICE), notices: [local.length, run.length], + migrated, failure, code: step.status, b: originFile(OLD_STATE("b")), @@ -432,6 +441,7 @@ test("under a commit step the engine can't read, state stays at the root and kee { held: true, notices: [2, 2], + migrated: [], failure: undefined, code: 0, b: '{"assistants":{"intake":{"uuid":"uuid-b"}}}\n', diff --git a/tests/state-layout-unseen-commit.test.ts b/tests/state-layout-unseen-commit.test.ts index b32313f..5f24c17 100644 --- a/tests/state-layout-unseen-commit.test.ts +++ b/tests/state-layout-unseen-commit.test.ts @@ -1,11 +1,11 @@ import assert from "node:assert/strict"; -import { spawnSync } from "node:child_process"; +import { execFileSync, spawnSync } from "node:child_process"; import { + chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, - readFileSync, rmSync, symlinkSync, writeFileSync, @@ -17,7 +17,10 @@ import { fileURLToPath } from "node:url"; import { migrateAll } from "../src/migrate-hash-store.ts"; import { COMMIT_STEP_FLAG, + OLD_LAYOUT_NOTICE, StateLayoutError, + commitStepAcknowledge, + commitStepAsk, commitStepFilePath, commitStepRead, orgPinFileLegacyPath, @@ -26,6 +29,7 @@ import { stateFilePath, stateFileWrite, stateLayoutPrepare, + stateMoveRead, } from "../src/state-paths.ts"; // A promotion run writes the state file and leaves committing it to a later @@ -35,9 +39,12 @@ import { // would pass while state//state.json is never committed, and the next // run would create every resource again. // -// So the move fails closed. Committed state stays where it is until a -// workflow is seen to stage state/, or a person says their commit step does. -// A CI run never writes state in a place its commit step isn't seen to stage. +// 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"; @@ -46,20 +53,23 @@ const STATE = JSON.stringify({ }); 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[]): string { +function workflow(commitLines: string[], permissions?: string): string { return [ "name: Promote", "on: { push: { branches: [main] } }", + ...(permissions ? ["permissions:", " contents: " + permissions] : []), "jobs:", " promote:", " runs-on: ubuntu-latest", @@ -163,260 +173,482 @@ test("a commit action with a file pattern for the state file holds the move back ); }); -test("promotion set up with no workflow in the repository holds the move back", () => { - // promotion.yml at the root means some pipeline runs promotion, and one - // outside GitHub Actions can't be read at all. +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: nothing commits state after a run. + // 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, true], + [false, false, false], ); - // With state already in state/, a CI run of that pipeline stops. A person - // promoting from their own machine is not warned on every command. +}); + +// ── 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, - "promotion.yml": "version: 1\n", + "resources/acme/assistants/a.md": "one\n", + "scripts/stage-state.sh": HELPER_SCRIPT, }); try { - assert.deepEqual( - [ - /promotion\.yml is set up and no workflow in \.github\/workflows\/ is seen to stage state\//.test( - thrown(() => stateLayoutPrepare(root, ORG, CI)), - ), - stateLayoutPrepare(root, ORG, {}), - ], - [true, []], - ); + 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("only a git add line that stages state/ or everything counts as seen", () => { - const seen = (line: string) => - movesByItself({ - ".github/workflows/promotion.yml": workflow([ - " - run: |", - ` ${line}`, - " git commit -m state && git push", - ]), +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( { - folder: seen("git add -A -- state"), - folderSlash: seen("git add state/"), - folderGlob: seen("git add -A -- ':(glob)state/**'"), - both: seen("git add -A -- state ':(glob).vapi-state.*.json' resources"), - everything: seen("git add -A"), - everythingLong: seen("git add --all"), - dot: seen("git add ."), - chained: seen("git add resources && git add -A -- state"), - // Not seen: something else, one org only, a variable, tracked files only. - resources: seen("git add -A -- resources"), - oneOrg: seen("git add -A -- state/acme"), - variable: seen('git add -A -- "$STATE_PATHS"'), - tracked: seen("git add -u"), - commented: seen("# git add -A -- state"), - lookalike: seen("git add -A -- estate statement"), + "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"], + ), }, { - folder: true, - folderSlash: true, - folderGlob: true, - both: true, - everything: true, - everythingLong: true, - dot: true, - chained: true, - resources: false, - oneOrg: false, - variable: false, - tracked: false, - commented: false, - lookalike: false, + "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", }, ); }); -test("a workflow that can't write to the repository is not a commit step", () => { - const withWorkflow = (lines: string[]) => - movesByItself({ ".github/workflows/ci.yml": `${lines.join("\n")}\n` }); - const job = ["jobs:", " test:", " steps:", " - run: npm test"]; +// ── 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( { - readOnly: withWorkflow(["permissions:", " contents: read", ...job]), - noContents: withWorkflow(["permissions:", " statuses: write", ...job]), - readAll: withWorkflow(["permissions: read-all", ...job]), - // Anything that may be able to commit is not ruled out. - noPermissions: withWorkflow(job), - writes: withWorkflow(["permissions:", " contents: write", ...job]), - writeAll: withWorkflow(["permissions: write-all", ...job]), - jobWrites: withWorkflow([ - "permissions:", - " contents: read", - ...job, - " permissions:", - " contents: write", - ]), - pushesAnyway: withWorkflow([ - "permissions:", - " contents: read", - ...job, - " - run: git push https://example.invalid/repo.git", - ]), - unreadable: withWorkflow(["jobs: [", " not yaml"]), + "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", + }), }, { - readOnly: true, - noContents: true, - readAll: true, - noPermissions: false, - writes: false, - writeAll: false, - jobWrites: false, - pushesAnyway: false, - unreadable: false, + "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", () => { - const root = repo({}); - try { - cpSync(join(REPO, ".github/workflows"), join(root, ".github/workflows"), { - recursive: true, - }); - assert.deepEqual(commitStepRead(root, {}), { - kind: "seen", - stagesOld: true, - }); - } finally { - rmSync(root, { recursive: true, force: true }); - } + assert.deepEqual(commitStepRead(REPO, {}), { kind: "seen", stagesOld: true }); }); // ── npm run migrate ────────────────────────────────────────────────────── -test("migrate says what the commit step has to stage and moves nothing until the person says it does", async () => { - const root = helperRepo({ - ["resources/" + ORG + "/.vapi-org.json"]: '{"orgId":"org-a"}\n', - }); - try { - const first = await migrateAll(root); - const afterFirst = [moved(root), existsSync(commitStepFilePath(root))]; - const second = await migrateAll(root, { commitStepStagesState: true }); - assert.deepEqual( - { - ask: first.commitStepAsk?.filter((line) => - /git add|npm run migrate|Nothing moved/.test(line), - ), - afterFirst, - acknowledged: second.acknowledged, - secondAsk: second.commitStepAsk, - moved: moved(root), - pinMoved: !existsSync(orgPinFileLegacyPath(root, ORG)), - file: readFileSync(commitStepFilePath(root), "utf8"), - // From here on a command on a person's machine has nothing to say. - later: stateLayoutPrepare(root, ORG, {}), - }, - { - ask: [ - "⚠️ Nothing moved into state/: .github/workflows/promotion.yml can commit to this repository and is not seen to stage state/.", - " git add -A -- state 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", - " npm run migrate -- --commit-step-stages-state", - ], - afterFirst: [false, false], - acknowledged: - "✍️ Wrote state/commit-step.json: you said the commit step stages state/. Commit it together with the move.", - secondAsk: undefined, - moved: true, - pinMoved: true, - file: '{\n "stagesStateFolder": true\n}\n', - later: [], - }, - ); - } finally { - rmSync(root, { recursive: true, force: true }); +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 is refused while a workflow is seen to stage only the old file", async () => { +test("the flag writes nothing where the engine can see for itself", () => { const root = repo({ [OLD_STATE]: STATE, - ".github/workflows/promotion.yml": workflow([ - " - run: |", - " git add -A -- ':(glob).vapi-state.*.json'", - " git commit -m state && git push", - ]), + ".github/workflows/promotion.yml": SEEN_WORKFLOW, }); try { - const message = await migrateAll(root, { - commitStepStagesState: true, - }).then( - () => "ran", - (error: unknown) => - error instanceof StateLayoutError ? error.message : "other error", - ); assert.deepEqual( [ - /promotion\.yml stages \.vapi-state\.\*\.json but not state\/, so --commit-step-stages-state is not true yet/.test( - message, - ), + /is not needed here/.test(commitStepAcknowledge(root)), existsSync(commitStepFilePath(root)), - moved(root), + commitStepAsk(root), + stateMoveRead(root).open, ], - [true, false, false], - message, + [true, false, undefined, true], ); } finally { rmSync(root, { recursive: true, force: true }); } }); -test("the flag writes nothing where the engine can see for itself", async () => { - const root = repo({ [OLD_STATE]: STATE }); - try { - const result = await migrateAll(root, { commitStepStagesState: true }); - assert.deepEqual( - [result.acknowledged, existsSync(commitStepFilePath(root)), moved(root)], - [ - "ℹ️ --commit-step-stages-state is not needed here: nothing in this repository commits state after a run.", - false, - 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 prints the two paths, exits 0, and rejects an option it doesn't know", () => { +test("npm run migrate holds an unread commit step back, exits 0, and rejects an option it doesn't know", () => { const root = helperRepo(); 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"); - const run = (...args: string[]) => { - 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}` }; - }; - const plain = run(); + const plain = migrateCommand(root); const heldAfterPlain = !moved(root); - const typo = run("--commit-step-stages-stat"); + const typo = migrateCommand(root, "--commit-step-stages-stat"); const heldAfterTypo = !moved(root); - const told = run(COMMIT_STEP_FLAG); + const told = migrateCommand(root, COMMIT_STEP_FLAG); assert.deepEqual( { plain: [ @@ -424,6 +656,7 @@ test("npm run migrate prints the two paths, exits 0, and rejects an option it do 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: [ @@ -434,7 +667,7 @@ test("npm run migrate prints the two paths, exits 0, and rejects an option it do told: [told.code, told.out.includes("📦 Moved"), moved(root)], }, { - plain: [0, true, true, true, true], + plain: [0, true, true, true, true, true], typo: [1, true, true], told: [0, true, true], }, @@ -445,150 +678,132 @@ test("npm run migrate prints the two paths, exits 0, and rejects an option it do } }); -// ── 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(); +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 notices = stateLayoutPrepare(root, ORG, CI); + const first = migrateCommand(root); + const again = migrateCommand(root); + const at = (needle: string) => first.out.indexOf(needle); assert.deepEqual( - { - notices, - moved: moved(root), - writes: stateFileWrite(root, ORG, CI), - // An org this run creates goes where the commit step already looks. - newOrg: stateFileWrite(root, "new-org", CI), - newOrgPin: orgPinFileWrite(root, "new-org", CI), - }, - { - notices: [ - "ℹ️ .vapi-state.acme.json stays where it is: .github/workflows/promotion.yml can commit to this repository and is not seen to stage state/. `npm run migrate` says what the commit step has to stage before it can move.", - ], - moved: false, - writes: stateFileLegacyPath(root, ORG), - newOrg: stateFileLegacyPath(root, "new-org"), - newOrgPin: orgPinFileLegacyPath(root, "new-org"), - }, + [ + 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 }); } }); -test("a CI run stops before it writes state/ that nothing is seen to commit", () => { - const root = repo({ - ["state/" + ORG + "/state.json"]: STATE, - ".github/workflows/promotion.yml": HELPER_WORKFLOW, - }); +// ── 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 { - const stopped = thrown(() => stateLayoutPrepare(root, ORG, CI)); - // An org with no state yet would be written into state/ too. - const newOrg = thrown(() => stateLayoutPrepare(root, "new-org", CI)); - const onAMachine = stateLayoutPrepare(root, ORG, {}); - writeFileSync(commitStepFilePath(root), '{"stagesStateFolder":true}\n'); assert.deepEqual( - { - stopped: [ - /promotion\.yml can commit to this repository and is not seen to stage state\/, so state\/acme\/ may never be committed/.test( - stopped, - ), - /Stopped before reading or changing anything/.test(stopped), - stopped.includes("npm run migrate -- --commit-step-stages-state"), - ], - newOrg: /so state\/new-org\/ may never be committed/.test(newOrg), - // The same checkout on a person's machine is warned, not stopped. - onAMachine: onAMachine.map((line) => line.slice(0, 2)), - // Once a person has said the step stages state/, the run goes ahead - // and says whose word it is taking. - acknowledged: stateLayoutPrepare(root, ORG, CI), - }, - { - stopped: [true, true, true], - newOrg: true, - onAMachine: ["⚠️"], - acknowledged: [ - "ℹ️ state/commit-step.json says this run's commit step stages state/. The engine can't see that step: if it doesn't, what this run records in state/acme/ is lost.", - ], - }, - stopped, + [ + 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 when the old file it would write is no longer what the commit step stages", () => { - const newOnly = repo({ - [OLD_STATE]: STATE, - ".github/workflows/promotion.yml": workflow([ - " - run: |", - " git add -A -- state", - " git commit -m state && git push", - ]), - }); - const saidSo = helperRepo({ - "state/commit-step.json": '{"stagesStateFolder":true}\n', +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 first = thrown(() => stateLayoutPrepare(newOnly, ORG, CI)); - const second = thrown(() => stateLayoutPrepare(saidSo, ORG, CI)); + const stopped = thrown(() => stateLayoutPrepare(root, ORG, CI)); assert.deepEqual( [ - /\.vapi-state\.acme\.json is still at the repository root, and this repository's workflow stages state\/ but not \.vapi-state\.\*\.json/.test( - first, + /promotion\.yml can commit to this repository and is not seen to stage state\//.test( + stopped, ), - /state\/commit-step\.json says the commit step stages state\//.test( - second, + /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, + ), ), - existsSync(stateFileLegacyPath(newOnly, ORG)), - existsSync(stateFileLegacyPath(saidSo, ORG)), - // On a person's machine both simply move. - stateLayoutPrepare(newOnly, ORG, {}).length, - moved(newOnly), - stateLayoutPrepare(saidSo, ORG, {}).length, - moved(saidSo), + stateLayoutPrepare(elsewhere, ORG, CI), ], - [true, true, true, true, 1, true, 1, true], - first + second, + [true, true, true, [], [true], []], ); } finally { - rmSync(newOnly, { recursive: true, force: true }); - rmSync(saidSo, { recursive: true, force: true }); + for (const dir of [root, saidSo, elsewhere]) + rmSync(dir, { recursive: true, force: true }); } }); -test("in GitHub Actions the run is judged by the workflow that is running it", () => { - const root = repo({ - ["state/" + ORG + "/state.json"]: STATE, - ".github/workflows/promotion.yml": workflow([ - " - run: |", - " git add -A -- state ':(glob).vapi-state.*.json'", - " git commit -m state && git push", - ]), - // Another workflow that can commit and stages nothing the engine reads. - ".github/workflows/deploy.yml": workflow([" - run: ./deploy.sh"]), - }); - const actions = (file: string): NodeJS.ProcessEnv => ({ - GITHUB_ACTIONS: "true", - GITHUB_WORKFLOW_REF: `acme/repo/.github/workflows/${file}@refs/heads/main`, +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, {}), + ]; + }), [ - thrown(() => stateLayoutPrepare(root, ORG, actions("promotion.yml"))), - /deploy\.yml can commit to this repository and is not seen to stage state\//.test( - thrown(() => stateLayoutPrepare(root, ORG, actions("deploy.yml"))), - ), - // With no workflow named, every workflow has to be seen. - /deploy\.yml/.test( - thrown(() => - stateLayoutPrepare(root, ORG, { GITHUB_ACTIONS: "true" }), - ), - ), + [true, true, true, [OLD_LAYOUT_NOTICE]], + [true, true, true, [OLD_LAYOUT_NOTICE]], ], - ["ran", true, true], ); } finally { - rmSync(root, { recursive: true, force: true }); + 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 index 969d3db..7e14a6b 100644 --- a/tests/state-layout.test.ts +++ b/tests/state-layout.test.ts @@ -9,6 +9,7 @@ import { readdirSync, rmSync, symlinkSync, + utimesSync, writeFileSync, } from "node:fs"; import { createServer } from "node:http"; @@ -19,26 +20,32 @@ import test from "node:test"; import { fileURLToPath } from "node:url"; import { assertStateMigrated, migrateAll } from "../src/migrate-hash-store.ts"; import { + OLD_LAYOUT_NOTICE, StateLayoutError, baselinesDir, + commitStepAcknowledge, orgPinFilePath, orgPinFileRead, orgPinFileWrite, snapshotsDir, + stateFileLeftover, stateFilePath, stateFileRead, stateFileWrite, + stateLayout, stateLayoutPrepare, - stateMoveBlocker, + 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, so these tests -// pin every way an older repository reaches the new layout: read in place, -// moved by a command on a person's machine, held back in CI and under a -// workflow that would not commit the move, cut short, and in disagreement. +// 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"; @@ -86,10 +93,22 @@ function oldRepo(): string { 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}`), @@ -100,9 +119,22 @@ function layout(root: string): Record { }; } +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", @@ -115,32 +147,38 @@ function withRepo(root: string, body: () => void | Promise) { .finally(() => rmSync(root, { recursive: true, force: true })); } -// ── Reading ────────────────────────────────────────────────────────────── +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; +} -test("orgs are listed from both layouts, and an org with no state yet reads from state/", () => { +// ── 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), - stateFileRead(root, "fresh") === stateFilePath(root, "fresh"), - ], - [["acme", "beta"], true], - ); + assert.deepEqual(stateOrgsList(root), ["acme", "beta"]); }); }); -test("reads fall back to the old file only while the new one is absent", () => { +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)], + [ + before, + stateFileRead(root, ORG), + orgPinFileRead(root, ORG), + stateFileWrite === stateFileRead, + orgPinFileWrite === orgPinFileRead, + ], [ [ join(root, `.vapi-state.${ORG}.json`), @@ -148,173 +186,213 @@ test("reads fall back to the old file only while the new one is absent", () => { ], stateFilePath(root, ORG), orgPinFilePath(root, ORG), + true, + true, ], ); }); }); -// ── Moving on a person's machine ───────────────────────────────────────── - -test("a command on a person's machine moves everything and says so in one line", () => { - const root = oldRepo(); - return withRepo(root, () => { - const notices = stateLayoutPrepare(root, ORG, LOCAL); +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( - { - notices, - layout: layout(root), - leftovers: existsSync(join(root, ".vapi-state-hash")), - }, - { - notices: [ - `📦 Moved .vapi-state-hash/${ORG}/, .vapi-state.${ORG}.snapshots/, .vapi-state.${ORG}.json, resources/${ORG}/.vapi-org.json into state/${ORG}/. Commit the removal together with the new folder.`, - ], - layout: MOVED, - leftovers: false, - }, + [ + 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("a second run moves nothing and says nothing", () => { - const root = oldRepo(); - return withRepo(root, () => { - stateLayoutPrepare(root, ORG, LOCAL); +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( - [stateLayoutPrepare(root, ORG, LOCAL), layout(root)], - [[], MOVED], + [stateLayout(pinnedOld, ORG), stateLayout(pinnedNew, ORG)], + ["root", "folder"], ); - }); + } finally { + for (const root of [pinnedOld, pinnedNew]) + rmSync(root, { recursive: true, force: true }); + } }); -test("a repository that never had the old layout is left alone", () => { - const root = mkdtempSync(join(tmpdir(), "state-layout-")); +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, () => { - put(root, `state/${ORG}/state.json`, STATE); assert.deepEqual( [ stateLayoutPrepare(root, ORG, LOCAL), stateLayoutPrepare(root, ORG, CI), - stateFileWrite(root, ORG, CI) === stateFilePath(root, ORG), - stateFileWrite(root, "new-org", CI) === stateFilePath(root, "new-org"), - orgPinFileWrite(root, "new-org", CI) === - orgPinFilePath(root, "new-org"), + stateLayoutPrepare(root, "new-org", CI), + stateFileWrite(root, "new-org") === stateFilePath(root, "new-org"), ], - [[], [], true, true, true], + [[], [], [], true], ); }); }); -test("machine-local files merge into a folder that already exists, newest side winning", () => { +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"); - stateLayoutPrepare(root, ORG, LOCAL); + 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"], + [], ], ); }); }); -// ── Held back ──────────────────────────────────────────────────────────── +// ── A CI run under a workflow that would not commit what it writes ─────── -test("a CI run leaves committed state where it is and writes it in place", () => { - const root = oldRepo(); - return withRepo(root, () => { - const notices = stateLayoutPrepare(root, ORG, CI); - assert.deepEqual( - { - notices, - layout: layout(root), - stateWrite: stateFileWrite(root, ORG, CI), - pinWrite: orgPinFileWrite(root, ORG, CI), - }, - { - notices: [ - `📦 Moved .vapi-state-hash/${ORG}/, .vapi-state.${ORG}.snapshots/ into state/${ORG}/.`, - "ℹ️ .vapi-state.acme.json and resources/acme/.vapi-org.json stays where it is: a CI run never moves state. Run `npm run migrate` on your machine and commit the result to move it into state/acme/.", - ], - // Gitignored files move anywhere: no workflow can lose them. - layout: { - ...MOVED, - oldState: STATE, - oldPin: PIN, - state: undefined, - pin: undefined, - }, - stateWrite: join(root, `.vapi-state.${ORG}.json`), - pinWrite: join(root, `resources/${ORG}/.vapi-org.json`), - }, - ); +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, }); -}); - -test("GITHUB_ACTIONS counts as a CI run", () => { - const root = oldRepo(); - return withRepo(root, () => { - stateLayoutPrepare(root, ORG, { GITHUB_ACTIONS: "true" }); - assert.equal(layout(root).oldState, STATE); - }); -}); - -test("a workflow that stages only the old file holds the move back, on any machine", () => { - const root = oldRepo(); return withRepo(root, () => { - put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); - const notices = stateLayoutPrepare(root, ORG, LOCAL); - assert.deepEqual( - { - blocker: stateMoveBlocker(root, LOCAL), - warned: notices.at(-1), - oldState: layout(root).oldState, - state: layout(root).state, - // A new org follows the layout the workflow commits. - newOrgState: stateFileWrite(root, "new-org", LOCAL), - newOrgPin: orgPinFileWrite(root, "new-org", LOCAL), - }, - { - blocker: { kind: "workflow", file: ".github/workflows/promotion.yml" }, - warned: - "⚠️ .vapi-state.acme.json and resources/acme/.vapi-org.json stays where it is: .github/workflows/promotion.yml stages .vapi-state.*.json but not state/. Add `git add -A -- state` to that step, then run `npm run migrate`.", - oldState: STATE, - state: undefined, - newOrgState: join(root, ".vapi-state.new-org.json"), - newOrgPin: join(root, "resources/new-org/.vapi-org.json"), - }, - ); - }); -}); - -test("the workflow this repository ships does not hold the move back", () => { - const root = oldRepo(); - return withRepo(root, () => { - cpSync(join(REPO, ".github/workflows"), join(root, ".github/workflows"), { - recursive: true, - }); - assert.deepEqual( - [stateMoveBlocker(root, LOCAL), stateMoveBlocker(root, CI)], - [undefined, { kind: "ci" }], - ); - }); -}); - -test("a CI run stops before it writes state its workflow would not commit", () => { - const root = mkdtempSync(join(tmpdir(), "state-layout-")); - return withRepo(root, () => { - put(root, `state/${ORG}/state.json`, STATE); - put(root, ".github/workflows/promotion.yml", OLD_WORKFLOW); assert.throws( () => stateLayoutPrepare(root, ORG, CI), (error: unknown) => @@ -324,42 +402,73 @@ test("a CI run stops before it writes state its workflow would not commit", () = ) && /Stopped before reading or changing anything/.test(error.message), ); - // The same checkout on a person's machine is warned, not stopped. - assert.match( - stateLayoutPrepare(root, ORG, LOCAL)[0]!, - /^⚠️ {2}\.github\/workflows\/promotion\.yml/, - ); + // 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 disagreement ──────────────────────────────────────── +// ── Cut short, or in both places ───────────────────────────────────────── -test("a move cut short between two files finishes on the next run", () => { +test("a move cut short between two files is read where each file is, and migrate finishes it", async () => { const root = oldRepo(); - return withRepo(root, () => { + 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); - assert.deepEqual(layout(root), MOVED); - }); + 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 is one state: the old copy goes, even in CI", () => { +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(); - // Same mapping, different key order and spacing: a merge or a formatter. - put( - root, - `state/${ORG}/state.json`, - `{"assistants":{"intake":{"uuid":"${UUID}"}}}`, - ); - stateLayoutPrepare(root, ORG, env); + 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( - [after.oldState, after.state], - [undefined, `{"assistants":{"intake":{"uuid":"${UUID}"}}}`], + { + 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], + }, ); } }); @@ -421,38 +530,53 @@ test("the legacy-format guard reads the state file in either place", () => { }); }); -test("migrate slims and moves every org, in a CI run too", async () => { +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.notices.length, + org.moved, ]), - oldState: layout(root).oldState, - state: JSON.parse(layout(root).state!), - pin: layout(root).pin, + 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.notices, + org.moved, ]), }, { orgs: [ - [ORG, "state/acme/state.json", true, 1], - ["beta", "state/beta/state.json", false, 0], + [ + 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, []], ], - oldState: undefined, - state: { assistants: { intake: { uuid: UUID } } }, - pin: PIN, + after: { + ...MOVED, + state: { assistants: { intake: { uuid: UUID } } }, + }, + rootLeftovers: [], again: [ [false, []], [false, []], @@ -466,14 +590,37 @@ test("migrate slims and moves every org, in a CI run too", async () => { } }); -test("migrate does not move state while a workflow would drop it", async () => { +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, layout(root).oldState, layout(root).state], - [".vapi-state.acme.json", STATE, undefined], + [ + 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 } } }, + undefined, + true, + false, + ], ); } finally { rmSync(root, { recursive: true, force: true }); @@ -482,6 +629,7 @@ test("migrate does not move state while a workflow would drop it", async () => { // ── Real commands against a stub API ───────────────────────────────────── +const ON_PLATFORM = "What the platform holds."; const ASSISTANT = (id: string, name: string) => ({ id, orgId: "org-a", @@ -489,7 +637,7 @@ const ASSISTANT = (id: string, name: string) => ({ model: { provider: "openai", model: "gpt-4o", - messages: [{ role: "system", content: "hi" }], + messages: [{ role: "system", content: ON_PLATFORM }], }, voice: { provider: "11labs", voiceId: "burt" }, }); @@ -525,6 +673,7 @@ async function engineRun( VAPI_BASE_URL: `http://127.0.0.1:${port}`, CI: "", GITHUB_ACTIONS: "", + VAPI_GITOPS_OLD_LAYOUT_NOTICE: "", ...env, }; try { @@ -545,77 +694,71 @@ async function engineRun( const count = (text: string, needle: string) => text.split(needle).length - 1; -test("pull on a person's machine moves an old repository once and keeps every mapping", async () => { - const root = oldRepo(); - try { - const first = await engineRun(root, ["src/pull.ts", ORG, "--force"], LOCAL); - const state = JSON.parse(layout(root).state ?? "{}"); - const second = await engineRun( - root, - ["src/pull.ts", ORG, "--force"], - LOCAL, - ); - assert.deepEqual( - { - codes: [first.code, second.code], - moved: [count(first.out, "📦 Moved"), count(second.out, "📦 Moved")], - oldState: layout(root).oldState, - oldPin: layout(root).oldPin, - pin: 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(), - rootLeftovers: readdirSync(root).filter((name) => - name.startsWith(".vapi-state"), - ), - }, - { - codes: [0, 0], - moved: [1, 0], - oldState: undefined, - oldPin: undefined, - pin: PIN, - tracked: { uuid: UUID }, - uuids: [UUID, UUID_NEW], - rootLeftovers: [], - }, - first.out + second.out, - ); - } finally { - rmSync(root, { recursive: true, force: true }); +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 in a CI run updates an old repository's state file in place", async () => { +test("pull keeps an old copy of the state file identical to the one in state/", async () => { const root = oldRepo(); try { - const run = await engineRun(root, ["src/pull.ts", ORG, "--force"], CI); - const state = JSON.parse(layout(root).oldState ?? "{}"); + put(root, `state/${ORG}/state.json`, STATE); + const run = await engineRun(root, ["src/pull.ts", ORG, "--force"], LOCAL); + const after = layout(root); assert.deepEqual( - { - code: run.code, - told: count(run.out, "a CI run never moves state"), - state: layout(root).state, - pin: [layout(root).oldPin, layout(root).pin], - tracked: state.assistants?.intake, - uuids: Object.values( - (state.assistants ?? {}) as Record, - ) - .map((entry) => entry.uuid) - .sort(), - }, - { - code: 0, - told: 1, - state: undefined, - pin: [PIN, undefined], - tracked: { uuid: UUID }, - uuids: [UUID, UUID_NEW], - }, + [ + run.code, + after.oldState === after.state, + Object.keys(JSON.parse(after.state ?? "{}").assistants ?? {}).length, + ], + [0, true, 2], run.out, ); } finally { @@ -644,21 +787,17 @@ test("pull stops before any request when the two state files disagree", async () } }); -test("a dry-run push moves nothing", async () => { +test("a dry-run push changes nothing", async () => { const root = oldRepo(); try { - const run = await engineRun(root, ["src/push.ts", ORG, "--dry-run"], LOCAL); - assert.deepEqual( - [count(run.out, "📦 Moved"), layout(root).oldState, layout(root).state], - [0, STATE, undefined], - run.out, - ); + 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 still read from the old folder until it moves", async () => { +test("a baseline is read from the old folder, where an old repository keeps it", async () => { const root = oldRepo(); try { put( @@ -679,3 +818,68 @@ test("a baseline is still read from the old folder until it moves", async () => 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-move-second-round.test.ts b/tests/state-move-second-round.test.ts new file mode 100644 index 0000000..50ba20a --- /dev/null +++ b/tests/state-move-second-round.test.ts @@ -0,0 +1,286 @@ +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 }); + } +}); From 6348a6f1ec7b299a507ad780b58c8d4cc5a19768 Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Wed, 18 Nov 2026 13:29:26 -0800 Subject: [PATCH 07/10] fix: keep the test suite out of the repository it runs in, and engine files out of pull's local edits Running the test suite in a repository with a state file at its root removed the repository: two tests cleaned up two folders above the engine's baselines folder, and in the older layout that is the repository root. The engine's directory now comes from one place, src/base-dir.ts. The test preload points it at a temporary directory, makes every node:fs change inside the repository throw, and the engine refuses a test started without the preload. A new test runs the whole suite inside a copy of a customer-shaped repository in the older layout, in state/, and with no state, and compares every tracked, untracked and ignored file before and after. That run found one more writer, tests/org-connection.test.ts, which created tmp/ in the repository. Pull's keep rule for a file with no baseline is off whenever git shows a change under resources//. The engine's own files there (the org pin in the older layout, also shown as deleted between migrate and its commit) are no longer counted. A repository with no state whose commit step can't be read still gets its first state file at the root, and the command now says where the file goes, why, and what has to stage it. The upgrade guide gains one line: on a machine with no baselines, the first pull after upgrading can bring a dashboard edit down one pull late. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/guides/commands.md | 36 ++- improvements.md | 21 +- src/apply.ts | 6 +- src/base-dir.ts | 24 ++ src/call.ts | 6 +- src/check-cmd.ts | 4 +- src/config.ts | 7 +- src/hash-store.ts | 6 +- src/interactive.ts | 7 +- src/promote-cmd.ts | 5 +- src/pull.ts | 11 +- src/rollback-cmd.ts | 7 +- src/setup.ts | 7 +- src/sim.ts | 7 +- src/state-paths.ts | 45 +++- tests/audit.test.ts | 24 +- tests/drift.test.ts | 17 +- tests/first-state-file.test.ts | 244 ++++++++++++++++++ tests/no-vapi-api.ts | 100 +++++++- tests/org-connection.test.ts | 13 +- tests/state-records-third-round.test.ts | 209 ++++++++++++++++ tests/suite-keeps-the-repository.test.ts | 102 ++++++++ tests/suite-leaves-the-repository.test.ts | 291 ++++++++++++++++++++++ tests/tool-assistant-cycle.test.ts | 16 +- 24 files changed, 1117 insertions(+), 98 deletions(-) create mode 100644 src/base-dir.ts create mode 100644 tests/first-state-file.test.ts create mode 100644 tests/state-records-third-round.test.ts create mode 100644 tests/suite-keeps-the-repository.test.ts create mode 100644 tests/suite-leaves-the-repository.test.ts diff --git a/docs/guides/commands.md b/docs/guides/commands.md index db196bd..da9f567 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -313,19 +313,45 @@ 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. -- **`📦 1 locally modified file(s) will be preserved`** on a `pull` before you - commit the move. The file is the old org pin, - `resources//.vapi-org.json`. It moved to `state//org.json`, so git - shows it as deleted until you commit. Pull does nothing differently because - of it. +- **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. diff --git a/improvements.md b/improvements.md index c366b10..6939fb2 100644 --- a/improvements.md +++ b/improvements.md @@ -2150,7 +2150,26 @@ 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. +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 test suite never works in the repository it runs in. Every module takes +the engine's directory from `src/base-dir.ts`, `tests/no-vapi-api.ts` points +it at a temporary directory and makes every `node:fs` change inside the +repository throw, and a test started without that file is refused. +`tests/suite-leaves-the-repository.test.ts` runs the whole suite inside a +copy of a customer-shaped repository in each layout and compares every file, +tracked, untracked and ignored, before and after. 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 diff --git a/src/apply.ts b/src/apply.ts index 579fd5b..e4af462 100644 --- a/src/apply.ts +++ b/src/apply.ts @@ -1,7 +1,8 @@ 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, @@ -19,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])?$/; diff --git a/src/base-dir.ts b/src/base-dir.ts new file mode 100644 index 0000000..c3fbe5a --- /dev/null +++ b/src/base-dir.ts @@ -0,0 +1,24 @@ +// The directory the engine works in: the repository that holds src/. +// +// Every module takes it from here, so the test suite can give the engine a +// temporary directory instead. tests/no-vapi-api.ts names the repository the +// suite runs in and a temporary directory to use in its place. Then nothing +// a test does through the engine, and no path a test derives from it, can +// reach that repository. A CLI a test starts from a copy of src/ elsewhere +// keeps working in its own copy. + +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; + if (sandbox) return own === process.env.VAPI_GITOPS_TEST_REPO ? sandbox : own; + // Node's test runner sets this for every test file it runs. Without the + // sandbox a test would read and write the real repository: refuse. + if (process.env.NODE_TEST_CONTEXT) + throw new Error( + "The engine was loaded by a test without tests/no-vapi-api.ts, so it would work in this repository instead of a temporary directory. Run tests with `npm test` or `node --import tsx --import ./tests/no-vapi-api.ts --test `.", + ); + return own; +} diff --git a/src/call.ts b/src/call.ts index 4e316f0..0a1a545 100644 --- a/src/call.ts +++ b/src/call.ts @@ -2,9 +2,10 @@ 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 { 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"; @@ -15,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"; diff --git a/src/check-cmd.ts b/src/check-cmd.ts index 494194d..373d16e 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"; @@ -399,8 +400,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)), + process.env.VAPI_GITOPS_ROOT ?? baseDir(), ), ): Promise { let parsed: CheckArgs; diff --git a/src/config.ts b/src/config.ts index de8f23b..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(); diff --git a/src/hash-store.ts b/src/hash-store.ts index 6740569..b5eb64c 100644 --- a/src/hash-store.ts +++ b/src/hash-store.ts @@ -20,8 +20,8 @@ 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, @@ -29,7 +29,7 @@ import { } 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(); // Exported so the migration works on the same repository root. export const HASH_STORE_BASE_DIR = BASE_DIR; diff --git a/src/interactive.ts b/src/interactive.ts index d0ac1fd..26d46ba 100644 --- a/src/interactive.ts +++ b/src/interactive.ts @@ -2,8 +2,8 @@ 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 { 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. @@ -16,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])?$/; diff --git a/src/promote-cmd.ts b/src/promote-cmd.ts index da1b31b..083cf36 100644 --- a/src/promote-cmd.ts +++ b/src/promote-cmd.ts @@ -2,6 +2,7 @@ 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 { @@ -41,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 diff --git a/src/pull.ts b/src/pull.ts index 83742dd..ca199fd 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -47,7 +47,7 @@ import { stateWritePrepare, upsertState, } from "./state.ts"; -import { stateSavedStampPath } from "./state-paths.ts"; +import { engineFiles, stateSavedStampPath } from "./state-paths.ts"; import type { ResourceState, ResourceType, StateFile } from "./types.ts"; // Map resource types to their API endpoints @@ -1320,9 +1320,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/rollback-cmd.ts b/src/rollback-cmd.ts index ed2886d..a1c66d6 100644 --- a/src/rollback-cmd.ts +++ b/src/rollback-cmd.ts @@ -10,15 +10,14 @@ 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 { 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; diff --git a/src/setup.ts b/src/setup.ts index dcbff62..a4b5e07 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -2,14 +2,14 @@ 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 { join } from "path"; +import { baseDir } from "./base-dir.ts"; import { stateFileLabel, stateFileLegacyPath, stateFileRead, stateOrgDir, } from "./state-paths.ts"; -import { fileURLToPath } from "url"; import { API_KEY_VAR, API_KEYS_URL, @@ -33,8 +33,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 VAPI_REGIONS: Record = { us: "https://api.vapi.ai", eu: "https://api.eu.vapi.ai", diff --git a/src/sim.ts b/src/sim.ts index 3fbc4e5..5eabdda 100644 --- a/src/sim.ts +++ b/src/sim.ts @@ -6,8 +6,8 @@ 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 { baseDir } from "./base-dir.ts"; import { simRunItemTerminal, simRunVerdict, @@ -25,8 +25,7 @@ import { type VapiConnection, } 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; diff --git a/src/state-paths.ts b/src/state-paths.ts index 65e72ad..3032c1d 100644 --- a/src/state-paths.ts +++ b/src/state-paths.ts @@ -240,6 +240,21 @@ function committedFiles(rootDir: string, org: string): CommittedFile[] { ]; } +/** + * 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 { @@ -313,6 +328,25 @@ function notSeenReason(file: string | undefined): string { : `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.`; @@ -410,7 +444,14 @@ export function stateLayoutPrepare( ); } - if (layout === "root") return [...notices, OLD_LAYOUT_NOTICE]; + 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) @@ -433,7 +474,7 @@ export function stateNoticesPrint( env: NodeJS.ProcessEnv = process.env, ): void { for (const notice of notices) { - if (notice === OLD_LAYOUT_NOTICE) { + 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"; } diff --git a/tests/audit.test.ts b/tests/audit.test.ts index 72cac00..f45d371 100644 --- a/tests/audit.test.ts +++ b/tests/audit.test.ts @@ -1,8 +1,7 @@ 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 +9,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 +390,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 +409,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/drift.test.ts b/tests/drift.test.ts index bc64c98..cff96ff 100644 --- a/tests/drift.test.ts +++ b/tests/drift.test.ts @@ -1,5 +1,4 @@ import assert from "node:assert/strict"; -import { dirname } from "node:path"; import test from "node:test"; import { checkPronunciationDictDrop, @@ -9,12 +8,9 @@ import { 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 @@ -108,17 +104,10 @@ function driftState( } as Record>; } -// Drift baselines live in the hash store (state//local/baselines/), 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(() => { - // state//local/baselines → state/ - rmSync(dirname(dirname(hashStoreDir(HASH_STORE_TEST_ENV))), { - recursive: true, - force: true, - }); -}); test("checkPronunciationDictDrop: warns when prior had ID and new lost it", () => { const prior = { diff --git a/tests/first-state-file.test.ts b/tests/first-state-file.test.ts new file mode 100644 index 0000000..aed2d05 --- /dev/null +++ b/tests/first-state-file.test.ts @@ -0,0 +1,244 @@ +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/no-vapi-api.ts b/tests/no-vapi-api.ts index 29d0955..99e73b5 100644 --- a/tests/no-vapi-api.ts +++ b/tests/no-vapi-api.ts @@ -1,6 +1,13 @@ -// Loaded before every test file (package.json's test script), and inherited -// by every CLI a test spawns: tests must never reach the real Vapi API or use -// a developer's real key. A test that needs a key sets a fake one itself. +// Loaded before every test file (package.json's test script). What it sets +// in the environment is inherited by every CLI a test spawns. +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"; + +// Tests must never reach the real Vapi API or use a developer's real key. A +// test that needs a key sets a fake one itself. process.env.VAPI_BASE_URL = "http://127.0.0.1:9"; delete process.env.VAPI_PRIVATE_API_KEY; delete process.env.VAPI_TOKEN; @@ -10,3 +17,90 @@ process.env.VAPI_GITOPS_ORG_PIN = "off"; // Per-org keys (VAPI_PRIVATE_API_KEY_) a developer exports in their shell. for (const name of Object.keys(process.env)) if (name.startsWith("VAPI_PRIVATE_API_KEY_")) delete process.env[name]; + +// Tests must never read, write or remove anything in the repository they run +// in. The engine loaded from this repository's src/ works in a temporary +// directory instead (src/base-dir.ts), so its state, baselines, snapshots and +// resources all resolve there, and so does any path a test derives from them. +// No test cleans the engine's folders up: this removes the whole directory. +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 })); + +// A test can also build a path to the repository itself. So in a test +// process, every node:fs call that creates, changes or removes something +// throws when its target is inside the repository. A test's files belong in +// a directory it made under os.tmpdir(). +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/org-connection.test.ts b/tests/org-connection.test.ts index 747d9e9..d1d9121 100644 --- a/tests/org-connection.test.ts +++ b/tests/org-connection.test.ts @@ -1,9 +1,9 @@ import assert from "node:assert/strict"; import { - mkdirSync, mkdtempSync, readFileSync, rmSync, + symlinkSync, writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; @@ -17,13 +17,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 { diff --git a/tests/state-records-third-round.test.ts b/tests/state-records-third-round.test.ts new file mode 100644 index 0000000..796dc89 --- /dev/null +++ b/tests/state-records-third-round.test.ts @@ -0,0 +1,209 @@ +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/suite-keeps-the-repository.test.ts b/tests/suite-keeps-the-repository.test.ts new file mode 100644 index 0000000..182f269 --- /dev/null +++ b/tests/suite-keeps-the-repository.test.ts @@ -0,0 +1,102 @@ +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 { 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 +// 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 tests/drift.test.ts inside a throwaway copy, in a +// folder of its own, so nothing outside the copy can be removed. +// tests/suite-leaves-the-repository.test.ts does the same with the whole +// suite and compares every file. + +const REPO = fileURLToPath(new URL("..", import.meta.url)); + +function suiteLeavesRepository(stateFiles: Record): { + exit: number | null; + ran: boolean; + kept: boolean; +} { + const box = mkdtempSync(join(tmpdir(), "suite-keeps-repo-")); + const root = join(box, "repo"); + try { + mkdirSync(join(root, "tests"), { recursive: true }); + cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); + cpSync(join(REPO, "package.json"), join(root, "package.json")); + for (const name of ["drift.test.ts", "no-vapi-api.ts"]) + cpSync(join(REPO, "tests", name), join(root, "tests", name)); + 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); + } + // A test runner started from inside another one runs nothing unless this + // is cleared, and the case would pass without having run. + const env = { ...process.env }; + delete env.NODE_TEST_CONTEXT; + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + "tests/drift.test.ts", + ], + { cwd: root, encoding: "utf8", env }, + ); + return { + exit: run.status, + ran: /^# pass [1-9]/m.test(run.stdout), + kept: + existsSync(join(root, "package.json")) && existsSync(join(root, "src")), + }; + } finally { + rmSync(box, { recursive: true, force: true }); + } +} + +const STATE = '{\n "assistants": {}\n}\n'; + +test("the drift tests leave the repository in place, wherever its state is", () => { + assert.deepEqual( + { + "no state at all": suiteLeavesRepository({}), + "state in state/acme/": suiteLeavesRepository({ + "state/acme/state.json": STATE, + }), + "state at the root (.vapi-state.acme.json)": suiteLeavesRepository({ + ".vapi-state.acme.json": STATE, + }), + }, + { + "no state at all": { exit: 0, ran: true, kept: true }, + "state in state/acme/": { exit: 0, ran: true, kept: true }, + "state at the root (.vapi-state.acme.json)": { + exit: 0, + ran: true, + kept: true, + }, + }, + ); +}); diff --git a/tests/suite-leaves-the-repository.test.ts b/tests/suite-leaves-the-repository.test.ts new file mode 100644 index 0000000..27d7095 --- /dev/null +++ b/tests/suite-leaves-the-repository.test.ts @@ -0,0 +1,291 @@ +import assert from "node:assert/strict"; +import { execFileSync, spawn, spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { + cpSync, + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + 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"; + +// 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, engine state, this machine's +// baselines and snapshots, a commit), runs the 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. + +const REPO = join(dirname(fileURLToPath(import.meta.url)), ".."); +// The suite run inside a copy includes this file. It must not start again. +const NESTED = "VAPI_GITOPS_SUITE_IN_A_COPY"; + +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", +}; + +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, [NESTED]: "1" }; + delete env.NODE_TEST_CONTEXT; + const files = readdirSync(join(root, "tests")) + .filter((name) => name.endsWith(".test.ts")) + .map((name) => `tests/${name}`); + const child = spawn( + process.execPath, + [ + "--import", + "tsx", + "--import", + "./tests/no-vapi-api.ts", + "--test", + ...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", { + skip: process.env[NESTED] === "1", +}, async () => { + const names = Object.keys(LAYOUTS); + // One copy at a time. Three suites at once, beside the one running this + // test, 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: [] }, + ]), + ), + ); +}); + +// Two things keep a test out of the repository before that comparison has +// anything to find. tests/no-vapi-api.ts gives the engine a temporary +// directory to work in and makes every node:fs change inside the repository +// throw; src/base-dir.ts refuses to work in a test that was started without +// it. + +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 }); +}); + +test("the engine works in the temporary directory a test run gives it, and refuses a test run that gives it none", () => { + const where = (change: (env: NodeJS.ProcessEnv) => void) => { + const env: NodeJS.ProcessEnv = { ...process.env }; + change(env); + const run = spawnSync( + process.execPath, + [ + "--import", + "tsx", + "--input-type=module", + "-e", + 'import { baseDir } from "./src/base-dir.ts"; console.log(baseDir());', + ], + { cwd: REPO, env, encoding: "utf8" }, + ); + return run.status === 0 ? run.stdout.trim() : run.stderr; + }; + const sandbox = process.env.VAPI_GITOPS_TEST_ROOT; + assert.ok(sandbox && !sandbox.startsWith(REPO)); + assert.deepEqual( + [ + // In a test run: the temporary directory. + where(() => {}), + // Outside one: the repository that holds src/. + where((env) => { + delete env.VAPI_GITOPS_TEST_ROOT; + delete env.NODE_TEST_CONTEXT; + }), + // A test started without tests/no-vapi-api.ts. + /without tests\/no-vapi-api\.ts/.test( + where((env) => { + delete env.VAPI_GITOPS_TEST_ROOT; + env.NODE_TEST_CONTEXT = "child-v8"; + }), + ), + ], + [sandbox, REPO, true], + ); +}); diff --git a/tests/tool-assistant-cycle.test.ts b/tests/tool-assistant-cycle.test.ts index 7db38e5..9e96412 100644 --- a/tests/tool-assistant-cycle.test.ts +++ b/tests/tool-assistant-cycle.test.ts @@ -1,7 +1,5 @@ import assert from "node:assert/strict"; -import { rmSync } from "node:fs"; -import { dirname } from "node:path"; -import test, { after } from "node:test"; +import test from "node:test"; // ───────────────────────────────────────────────────────────────────────────── // Tools are applied before assistants because assistants reference tools. But a @@ -28,7 +26,6 @@ const { updateToolAssistantRefs, } = await import("../src/push.ts"); -import { deleteBaseline, hashStoreDir } from "../src/hash-store.ts"; import type { ResourceFile, StateFile } from "../src/types.ts"; const UUID = "8f14e45f-ceea-467a-9f1b-1a1b2c3d4e5f"; @@ -36,15 +33,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. -// The push under test records a baseline in this checkout's state/ folder. -// Remove it and the folders it created, so a test run leaves state/ as it was. -after(async () => { - await deleteBaseline("test-fixture-org", UUID); - rmSync(dirname(dirname(hashStoreDir("test-fixture-org"))), { - recursive: true, - force: true, - }); -}); +// 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 From b575bbd43b7cb83a3379b56d83e29cd2a3ade7a6 Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Thu, 19 Nov 2026 02:27:01 -0800 Subject: [PATCH 08/10] fix: the test sandbox travels with each engine test, and the engine ignores the test runner The engine refused to start when NODE_TEST_CONTEXT was in its environment without a sandbox, and the preload npm test adds sandboxed every test file. Node's test runner sets that variable for every process it starts, so an engine command started from a repository's own test exited 1, and such a test could no longer run the engine on its repository or write a file into it. Both worked before the sandbox existed. The sandbox is now a module, tests/engine-sandbox.ts, that every engine test file imports first: the temporary directory for the engine and the node:fs guard on the repository. It holds however the file is started, by hand without the preload included. tests/no-vapi-api.ts is what it was before the sandbox, and src/base-dir.ts never looks at the test runner's environment. A test file that doesn't import the module is left alone: the commands it starts and the engine modules it imports work in its repository, and it writes where it likes. In the engine's own repository (a runner whose GITHUB_REPOSITORY is VapiAI/gitops, or a clone whose origin is) a test file without the import fails the suite. In any other repository that check is skipped. tests/base-dir.test.ts fails when a module under src/ works out the repository's directory for itself. npm test no longer starts a test runner inside a test. The suite run inside copies of a customer-shaped repository, and the other tests that start a runner of their own, move to tests/repository/ and run with npm run test:repository, one file at a time, and as a CI job in the engine's own repository. A suite inside a suite tripled the time npm test took and reached the twenty-second limits some tests give a command sooner on a slow machine. Each copy now holds a test of the customer's own and runs the engine's test files only. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- .github/workflows/ci.yml | 22 +++ AGENTS.md | 7 + CONTRIBUTING.md | 12 +- docs/guides/commands.md | 1 + improvements.md | 26 ++- package.json | 3 +- src/base-dir.ts | 29 +-- src/user-agent.ts | 4 + tests/agent-docs.test.ts | 1 + tests/api-key.test.ts | 1 + tests/apply-scoped-pull.test.ts | 1 + tests/audit.test.ts | 1 + tests/base-dir.test.ts | 45 +++++ tests/bindings.test.ts | 1 + tests/check-cmd.test.ts | 1 + tests/check-config.test.ts | 1 + tests/check-mocks.test.ts | 1 + tests/check-payload.test.ts | 1 + tests/check-report.test.ts | 1 + tests/check-run.test.ts | 1 + tests/check-select.test.ts | 1 + tests/check-status.test.ts | 1 + tests/ci-validate-workflow.test.ts | 1 + tests/clean-resource.test.ts | 1 + tests/cleanup-ignore.test.ts | 1 + tests/cleanup-safety.test.ts | 1 + tests/cli-arg-parsing.test.ts | 1 + tests/config-api-key.test.ts | 1 + tests/conflict-timing.test.ts | 1 + tests/credentials.test.ts | 1 + tests/dep-dedup.test.ts | 1 + tests/docs-commands.test.ts | 1 + tests/docs-links.test.ts | 1 + tests/drift.test.ts | 1 + tests/engine-sandbox.test.ts | 187 ++++++++++++++++++ tests/engine-sandbox.ts | 110 +++++++++++ tests/engine-tests.ts | 28 +++ tests/examples.test.ts | 1 + tests/first-state-file.test.ts | 1 + tests/list-pagination.test.ts | 1 + tests/new-file-gate.test.ts | 1 + tests/no-vapi-api.ts | 100 +--------- tests/org-connection.test.ts | 1 + tests/org-pin.test.ts | 1 + tests/path-matching.test.ts | 1 + tests/promote-cmd.test.ts | 1 + tests/promotion-gate.test.ts | 1 + tests/promotion-golden.test.ts | 1 + tests/promotion-workflow-commit.test.ts | 1 + tests/promotion.test.ts | 1 + tests/pull-rename-preserves-filename.test.ts | 1 + tests/pull-same-name-clobber.test.ts | 1 + tests/push-dry-run.test.ts | 1 + tests/push-stale-baseline-noop.test.ts | 1 + tests/reconcile-state-key.test.ts | 1 + .../engine-beside-a-test-runner.test.ts | 177 +++++++++++++++++ tests/repository/import-check.test.ts | 126 ++++++++++++ tests/repository/own-tests-as-before.test.ts | 108 ++++++++++ .../suite-keeps-the-repository.test.ts | 116 +++++++++++ .../suite-leaves-the-repository.test.ts | 129 ++++-------- tests/resource-parse.test.ts | 1 + tests/resource-type-args.test.ts | 1 + tests/setup-noninteractive.test.ts | 1 + tests/sim-result.test.ts | 1 + tests/sim-run.test.ts | 1 + tests/sim.test.ts | 1 + tests/slug-utils.test.ts | 1 + tests/snapshot.test.ts | 1 + tests/so-assistant-omit.test.ts | 1 + tests/state-key-order.test.ts | 1 + tests/state-layout-unseen-commit.test.ts | 1 + tests/state-layout.test.ts | 1 + tests/state-merge.test.ts | 1 + tests/state-migration.test.ts | 1 + tests/state-move-second-round.test.ts | 1 + tests/state-records-third-round.test.ts | 1 + tests/suite-keeps-the-repository.test.ts | 102 ---------- tests/tool-assistant-cycle.test.ts | 1 + tests/user-agent-coverage.test.ts | 1 + tests/user-agent.test.ts | 1 + tests/validate-refs.test.ts | 1 + tests/validate.test.ts | 1 + tests/vapi-checks-workflow.test.ts | 1 + tests/vapi-ignore-push.test.ts | 1 + tests/version-metadata.test.ts | 1 + 85 files changed, 1079 insertions(+), 319 deletions(-) create mode 100644 tests/base-dir.test.ts create mode 100644 tests/engine-sandbox.test.ts create mode 100644 tests/engine-sandbox.ts create mode 100644 tests/engine-tests.ts create mode 100644 tests/repository/engine-beside-a-test-runner.test.ts create mode 100644 tests/repository/import-check.test.ts create mode 100644 tests/repository/own-tests-as-before.test.ts create mode 100644 tests/repository/suite-keeps-the-repository.test.ts rename tests/{ => repository}/suite-leaves-the-repository.test.ts (63%) delete mode 100644 tests/suite-keeps-the-repository.test.ts 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/AGENTS.md b/AGENTS.md index a1885f5..21f18b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -375,6 +375,13 @@ 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 where `origin` is `VapiAI/gitops` itself. +- 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..49e596c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,8 +26,16 @@ 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. `npm test` fails + here when a test file is missing it. +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/docs/guides/commands.md b/docs/guides/commands.md index da9f567..414a7a8 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -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 diff --git a/improvements.md b/improvements.md index 6939fb2..241c8c2 100644 --- a/improvements.md +++ b/improvements.md @@ -2163,13 +2163,25 @@ 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 test suite never works in the repository it runs in. Every module takes -the engine's directory from `src/base-dir.ts`, `tests/no-vapi-api.ts` points -it at a temporary directory and makes every `node:fs` change inside the -repository throw, and a test started without that file is refused. -`tests/suite-leaves-the-repository.test.ts` runs the whole suite inside a -copy of a customer-shaped repository in each layout and compares every file, -tracked, untracked and ignored, before and after. +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 +the engine's own repository a test file without that import fails the suite. +`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 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/base-dir.ts b/src/base-dir.ts index c3fbe5a..1c718f0 100644 --- a/src/base-dir.ts +++ b/src/base-dir.ts @@ -1,11 +1,19 @@ // The directory the engine works in: the repository that holds src/. // -// Every module takes it from here, so the test suite can give the engine a -// temporary directory instead. tests/no-vapi-api.ts names the repository the -// suite runs in and a temporary directory to use in its place. Then nothing -// a test does through the engine, and no path a test derives from it, can -// reach that repository. A CLI a test starts from a copy of src/ elsewhere -// keeps working in its own copy. +// 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"; @@ -13,12 +21,5 @@ 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; - if (sandbox) return own === process.env.VAPI_GITOPS_TEST_REPO ? sandbox : own; - // Node's test runner sets this for every test file it runs. Without the - // sandbox a test would read and write the real repository: refuse. - if (process.env.NODE_TEST_CONTEXT) - throw new Error( - "The engine was loaded by a test without tests/no-vapi-api.ts, so it would work in this repository instead of a temporary directory. Run tests with `npm test` or `node --import tsx --import ./tests/no-vapi-api.ts --test `.", - ); - return own; + return sandbox && own === process.env.VAPI_GITOPS_TEST_REPO ? sandbox : own; } 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/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..811108b 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 { 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/audit.test.ts b/tests/audit.test.ts index f45d371..fb18813 100644 --- a/tests/audit.test.ts +++ b/tests/audit.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdirSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; 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..6afcb00 100644 --- a/tests/bindings.test.ts +++ b/tests/bindings.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/check-cmd.test.ts b/tests/check-cmd.test.ts index 91b4503..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 { 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..6e53a2b 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"; diff --git a/tests/check-select.test.ts b/tests/check-select.test.ts index 6d147b2..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"; 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 930254a..df8e040 100644 --- a/tests/cleanup-ignore.test.ts +++ b/tests/cleanup-ignore.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; diff --git a/tests/cleanup-safety.test.ts b/tests/cleanup-safety.test.ts index 7a37f56..3d7218f 100644 --- a/tests/cleanup-safety.test.ts +++ b/tests/cleanup-safety.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; 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..cd93654 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 { diff --git a/tests/conflict-timing.test.ts b/tests/conflict-timing.test.ts index 9771af4..4077526 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"; diff --git a/tests/credentials.test.ts b/tests/credentials.test.ts index 2864cd4..971b304 100644 --- a/tests/credentials.test.ts +++ b/tests/credentials.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/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 cff96ff..337a9f8 100644 --- a/tests/drift.test.ts +++ b/tests/drift.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/engine-sandbox.test.ts b/tests/engine-sandbox.test.ts new file mode 100644 index 0000000..627f0cd --- /dev/null +++ b/tests/engine-sandbox.test.ts @@ -0,0 +1,187 @@ +import "./engine-sandbox.ts"; +import assert from "node:assert/strict"; +import { execFileSync, 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 the engine's own repository: on a runner by its name, on a +// person's machine by where origin points, over https or ssh. Anywhere else a +// test file without the import is that repository's own test. +function engineRepository(): boolean { + const named = process.env.GITHUB_REPOSITORY; + if (named) return named.toLowerCase() === "vapiai/gitops"; + try { + const origin = execFileSync( + "git", + ["config", "--get", "remote.origin.url"], + { cwd: REPO, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }, + ).trim(); + return /[/:]vapiai\/gitops(\.git)?\/?$/i.test(origin); + } catch { + return false; + } +} + +test("in the engine's own repository, every test file imports the sandbox first", { + skip: engineRepository() + ? false + : "not 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 origin is VapiAI/gitops; in a repository of your own, with its own origin, a test of your own 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 28990c2..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 { diff --git a/tests/first-state-file.test.ts b/tests/first-state-file.test.ts index aed2d05..1926b4f 100644 --- a/tests/first-state-file.test.ts +++ b/tests/first-state-file.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync, spawn } from "node:child_process"; import { diff --git a/tests/list-pagination.test.ts b/tests/list-pagination.test.ts index 41d95c5..4750a4d 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"; diff --git a/tests/new-file-gate.test.ts b/tests/new-file-gate.test.ts index e35a513..df6fe0d 100644 --- a/tests/new-file-gate.test.ts +++ b/tests/new-file-gate.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; diff --git a/tests/no-vapi-api.ts b/tests/no-vapi-api.ts index 99e73b5..29d0955 100644 --- a/tests/no-vapi-api.ts +++ b/tests/no-vapi-api.ts @@ -1,13 +1,6 @@ -// Loaded before every test file (package.json's test script). What it sets -// in the environment is inherited by every CLI a test spawns. -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"; - -// Tests must never reach the real Vapi API or use a developer's real key. A -// test that needs a key sets a fake one itself. +// Loaded before every test file (package.json's test script), and inherited +// by every CLI a test spawns: tests must never reach the real Vapi API or use +// a developer's real key. A test that needs a key sets a fake one itself. process.env.VAPI_BASE_URL = "http://127.0.0.1:9"; delete process.env.VAPI_PRIVATE_API_KEY; delete process.env.VAPI_TOKEN; @@ -17,90 +10,3 @@ process.env.VAPI_GITOPS_ORG_PIN = "off"; // Per-org keys (VAPI_PRIVATE_API_KEY_) a developer exports in their shell. for (const name of Object.keys(process.env)) if (name.startsWith("VAPI_PRIVATE_API_KEY_")) delete process.env[name]; - -// Tests must never read, write or remove anything in the repository they run -// in. The engine loaded from this repository's src/ works in a temporary -// directory instead (src/base-dir.ts), so its state, baselines, snapshots and -// resources all resolve there, and so does any path a test derives from them. -// No test cleans the engine's folders up: this removes the whole directory. -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 })); - -// A test can also build a path to the repository itself. So in a test -// process, every node:fs call that creates, changes or removes something -// throws when its target is inside the repository. A test's files belong in -// a directory it made under os.tmpdir(). -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/org-connection.test.ts b/tests/org-connection.test.ts index d1d9121..946cefe 100644 --- a/tests/org-connection.test.ts +++ b/tests/org-connection.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { mkdtempSync, diff --git a/tests/org-pin.test.ts b/tests/org-pin.test.ts index 4034d6a..f94f068 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 { 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 6428d29..e97cfa7 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 { diff --git a/tests/promotion-gate.test.ts b/tests/promotion-gate.test.ts index dc20546..7b5b251 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 { 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 46d795e..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 { diff --git a/tests/promotion.test.ts b/tests/promotion.test.ts index c93022d..e4822c8 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"; diff --git a/tests/pull-rename-preserves-filename.test.ts b/tests/pull-rename-preserves-filename.test.ts index 7a6592b..d3285b5 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 { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; diff --git a/tests/pull-same-name-clobber.test.ts b/tests/pull-same-name-clobber.test.ts index 52b1077..81a71d8 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 { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; diff --git a/tests/push-dry-run.test.ts b/tests/push-dry-run.test.ts index 9feee9d..182b0da 100644 --- a/tests/push-dry-run.test.ts +++ b/tests/push-dry-run.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import { stateFilePath } from "../src/state-paths.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; diff --git a/tests/push-stale-baseline-noop.test.ts b/tests/push-stale-baseline-noop.test.ts index ebe0637..e46274e 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 { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; 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..cfed564 --- /dev/null +++ b/tests/repository/import-check.test.ts @@ -0,0 +1,126 @@ +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 the engine's own repository and in no other: anywhere +// else such a file is that repository's own test. 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 the engine's own repository, however it is named, and in no other", () => { + 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 clone over https": importCheckIn({ + origin: "https://github.com/VapiAI/gitops.git", + }), + "a clone over https, typed in lower case and without .git": importCheckIn( + { origin: "https://github.com/vapiai/gitops" }, + ), + "a clone over ssh": importCheckIn({ + origin: "git@github.com:VapiAI/gitops.git", + }), + "a runner in a fork": importCheckIn({ + runner: fork, + origin: `https://github.com/${fork}`, + }), + "a clone of a fork over https": importCheckIn({ + origin: `https://github.com/${fork}.git`, + }), + "a clone of a fork over ssh": importCheckIn({ + origin: `git@github.com:${fork}.git`, + }), + "a fork that kept the name": importCheckIn({ + origin: "https://github.com/acme/gitops.git", + }), + "a repository with no origin": importCheckIn({}), + }, + { + "a runner in the engine's repository": "own.test.ts lacks the import", + "a clone over https": "own.test.ts lacks the import", + "a clone over https, typed in lower case and without .git": + "own.test.ts lacks the import", + "a clone over ssh": "own.test.ts lacks the import", + "a runner in a fork": "not asked", + "a clone of a fork over https": "not asked", + "a clone of a fork over ssh": "not asked", + "a fork that kept the name": "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/suite-leaves-the-repository.test.ts b/tests/repository/suite-leaves-the-repository.test.ts similarity index 63% rename from tests/suite-leaves-the-repository.test.ts rename to tests/repository/suite-leaves-the-repository.test.ts index 27d7095..3369b27 100644 --- a/tests/suite-leaves-the-repository.test.ts +++ b/tests/repository/suite-leaves-the-repository.test.ts @@ -1,5 +1,6 @@ +import "../engine-sandbox.ts"; import assert from "node:assert/strict"; -import { execFileSync, spawn, spawnSync } from "node:child_process"; +import { execFileSync, spawn } from "node:child_process"; import { createHash } from "node:crypto"; import { cpSync, @@ -8,33 +9,35 @@ import { mkdtempSync, readdirSync, readFileSync, - renameSync, rmSync, symlinkSync, writeFileSync, } from "node:fs"; -import { rm, writeFile } from "node:fs/promises"; -import { tmpdir } from "node:os"; +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, engine state, this machine's -// baselines and snapshots, a commit), runs the 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. +// 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)), ".."); -// The suite run inside a copy includes this file. It must not start again. -const NESTED = "VAPI_GITOPS_SUITE_IN_A_COPY"; +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`; @@ -46,6 +49,10 @@ const CUSTOMER: Record = { "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> = { @@ -161,11 +168,15 @@ async function suiteRunIn(state: Record) { 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, [NESTED]: "1" }; + 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 = readdirSync(join(root, "tests")) - .filter((name) => name.endsWith(".test.ts")) - .map((name) => `tests/${name}`); + const files = testFiles(join(root, "tests")).engine.map( + (name) => `tests/${name}`, + ); const child = spawn( process.execPath, [ @@ -174,6 +185,9 @@ async function suiteRunIn(state: Record) { "--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"] }, @@ -196,12 +210,10 @@ async function suiteRunIn(state: Record) { } } -test("the whole suite, run inside a customer's repository, leaves every file as it was", { - skip: process.env[NESTED] === "1", -}, async () => { +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, beside the one running this - // test, starve the tests that give a CLI twenty seconds to answer. + // 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( @@ -214,78 +226,3 @@ test("the whole suite, run inside a customer's repository, leaves every file as ), ); }); - -// Two things keep a test out of the repository before that comparison has -// anything to find. tests/no-vapi-api.ts gives the engine a temporary -// directory to work in and makes every node:fs change inside the repository -// throw; src/base-dir.ts refuses to work in a test that was started without -// it. - -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 }); -}); - -test("the engine works in the temporary directory a test run gives it, and refuses a test run that gives it none", () => { - const where = (change: (env: NodeJS.ProcessEnv) => void) => { - const env: NodeJS.ProcessEnv = { ...process.env }; - change(env); - const run = spawnSync( - process.execPath, - [ - "--import", - "tsx", - "--input-type=module", - "-e", - 'import { baseDir } from "./src/base-dir.ts"; console.log(baseDir());', - ], - { cwd: REPO, env, encoding: "utf8" }, - ); - return run.status === 0 ? run.stdout.trim() : run.stderr; - }; - const sandbox = process.env.VAPI_GITOPS_TEST_ROOT; - assert.ok(sandbox && !sandbox.startsWith(REPO)); - assert.deepEqual( - [ - // In a test run: the temporary directory. - where(() => {}), - // Outside one: the repository that holds src/. - where((env) => { - delete env.VAPI_GITOPS_TEST_ROOT; - delete env.NODE_TEST_CONTEXT; - }), - // A test started without tests/no-vapi-api.ts. - /without tests\/no-vapi-api\.ts/.test( - where((env) => { - delete env.VAPI_GITOPS_TEST_ROOT; - env.NODE_TEST_CONTEXT = "child-v8"; - }), - ), - ], - [sandbox, REPO, true], - ); -}); 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..e4518d7 100644 --- a/tests/resource-type-args.test.ts +++ b/tests/resource-type-args.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/setup-noninteractive.test.ts b/tests/setup-noninteractive.test.ts index 3f8c88c..b4e675b 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 { diff --git a/tests/sim-result.test.ts b/tests/sim-result.test.ts index 4bea397..0aaa0fa 100644 --- a/tests/sim-result.test.ts +++ b/tests/sim-result.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/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..6870ec8 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"; 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..852bf00 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"; 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 index 5f24c17..39d0801 100644 --- a/tests/state-layout-unseen-commit.test.ts +++ b/tests/state-layout-unseen-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 { diff --git a/tests/state-layout.test.ts b/tests/state-layout.test.ts index 7e14a6b..cdbe56d 100644 --- a/tests/state-layout.test.ts +++ b/tests/state-layout.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/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 232cb13..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 { diff --git a/tests/state-move-second-round.test.ts b/tests/state-move-second-round.test.ts index 50ba20a..dd5ddb0 100644 --- a/tests/state-move-second-round.test.ts +++ b/tests/state-move-second-round.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync, spawn, spawnSync } from "node:child_process"; import { diff --git a/tests/state-records-third-round.test.ts b/tests/state-records-third-round.test.ts index 796dc89..8379d68 100644 --- a/tests/state-records-third-round.test.ts +++ b/tests/state-records-third-round.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import assert from "node:assert/strict"; import { execFileSync, spawn } from "node:child_process"; import { diff --git a/tests/suite-keeps-the-repository.test.ts b/tests/suite-keeps-the-repository.test.ts deleted file mode 100644 index 182f269..0000000 --- a/tests/suite-keeps-the-repository.test.ts +++ /dev/null @@ -1,102 +0,0 @@ -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 { 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 -// 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 tests/drift.test.ts inside a throwaway copy, in a -// folder of its own, so nothing outside the copy can be removed. -// tests/suite-leaves-the-repository.test.ts does the same with the whole -// suite and compares every file. - -const REPO = fileURLToPath(new URL("..", import.meta.url)); - -function suiteLeavesRepository(stateFiles: Record): { - exit: number | null; - ran: boolean; - kept: boolean; -} { - const box = mkdtempSync(join(tmpdir(), "suite-keeps-repo-")); - const root = join(box, "repo"); - try { - mkdirSync(join(root, "tests"), { recursive: true }); - cpSync(join(REPO, "src"), join(root, "src"), { recursive: true }); - cpSync(join(REPO, "package.json"), join(root, "package.json")); - for (const name of ["drift.test.ts", "no-vapi-api.ts"]) - cpSync(join(REPO, "tests", name), join(root, "tests", name)); - 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); - } - // A test runner started from inside another one runs nothing unless this - // is cleared, and the case would pass without having run. - const env = { ...process.env }; - delete env.NODE_TEST_CONTEXT; - const run = spawnSync( - process.execPath, - [ - "--import", - "tsx", - "--import", - "./tests/no-vapi-api.ts", - "--test", - "tests/drift.test.ts", - ], - { cwd: root, encoding: "utf8", env }, - ); - return { - exit: run.status, - ran: /^# pass [1-9]/m.test(run.stdout), - kept: - existsSync(join(root, "package.json")) && existsSync(join(root, "src")), - }; - } finally { - rmSync(box, { recursive: true, force: true }); - } -} - -const STATE = '{\n "assistants": {}\n}\n'; - -test("the drift tests leave the repository in place, wherever its state is", () => { - assert.deepEqual( - { - "no state at all": suiteLeavesRepository({}), - "state in state/acme/": suiteLeavesRepository({ - "state/acme/state.json": STATE, - }), - "state at the root (.vapi-state.acme.json)": suiteLeavesRepository({ - ".vapi-state.acme.json": STATE, - }), - }, - { - "no state at all": { exit: 0, ran: true, kept: true }, - "state in state/acme/": { exit: 0, ran: true, kept: true }, - "state at the root (.vapi-state.acme.json)": { - exit: 0, - ran: true, - kept: true, - }, - }, - ); -}); diff --git a/tests/tool-assistant-cycle.test.ts b/tests/tool-assistant-cycle.test.ts index 9e96412..3dc5fe0 100644 --- a/tests/tool-assistant-cycle.test.ts +++ b/tests/tool-assistant-cycle.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/user-agent-coverage.test.ts b/tests/user-agent-coverage.test.ts index 72ea69d..4dae029 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"; 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 41ba275..56fde76 100644 --- a/tests/vapi-ignore-push.test.ts +++ b/tests/vapi-ignore-push.test.ts @@ -1,3 +1,4 @@ +import "./engine-sandbox.ts"; import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; 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 { From 73b29be3aaf83a032fddc24ae2266aa3b6db3bb6 Mon Sep 17 00:00:00 2001 From: Dhruva Reddy Date: Thu, 19 Nov 2026 05:33:46 -0800 Subject: [PATCH 09/10] test: ask for the sandbox import only in CI for the engine's own repository The check that every test file imports tests/engine-sandbox.ts first was also asked on a person's machine, wherever origin pointed at VapiAI/gitops. A repository cloned straight from the engine's keeps that origin, so a test of its owner's under tests/ made one engine test fail in npm test. Before the sandbox existed it passed. The check is now asked only where GITHUB_REPOSITORY is VapiAI/gitops, which is CI for the engine's own repository. A contributor who leaves the import out finds out on the pull request. GITHUB_REPOSITORY=VapiAI/gitops npm test asks it on a machine. Tests and docs only. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- AGENTS.md | 3 +- CONTRIBUTING.md | 6 ++-- improvements.md | 4 ++- tests/engine-sandbox.test.ts | 32 ++++++------------ tests/repository/import-check.test.ts | 48 +++++++++++++++------------ 5 files changed, 46 insertions(+), 47 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 21f18b4..1f7faa8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -379,7 +379,8 @@ For changes under `src/`, `tests/` or `.github/`: 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 where `origin` is `VapiAI/gitops` itself. + 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 49e596c..cee2a08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,8 +28,10 @@ learnings are all welcome. `node:test` and live in `tests/`; they never call the real Vapi API. 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. `npm test` fails - here when a test file is missing it. + 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 diff --git a/improvements.md b/improvements.md index 241c8c2..c7a2ce6 100644 --- a/improvements.md +++ b/improvements.md @@ -2169,7 +2169,9 @@ module takes the engine's directory from `src/base-dir.ts` 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 -the engine's own repository a test file without that import fails the suite. +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 diff --git a/tests/engine-sandbox.test.ts b/tests/engine-sandbox.test.ts index 627f0cd..075c405 100644 --- a/tests/engine-sandbox.test.ts +++ b/tests/engine-sandbox.test.ts @@ -1,6 +1,6 @@ import "./engine-sandbox.ts"; import assert from "node:assert/strict"; -import { execFileSync, spawnSync } from "node:child_process"; +import { spawnSync } from "node:child_process"; import { cpSync, mkdirSync, @@ -135,28 +135,18 @@ test("an engine test started by hand, without the preload npm test adds, still w ); }); -// Whether this is the engine's own repository: on a runner by its name, on a -// person's machine by where origin points, over https or ssh. Anywhere else a -// test file without the import is that repository's own test. -function engineRepository(): boolean { - const named = process.env.GITHUB_REPOSITORY; - if (named) return named.toLowerCase() === "vapiai/gitops"; - try { - const origin = execFileSync( - "git", - ["config", "--get", "remote.origin.url"], - { cwd: REPO, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }, - ).trim(); - return /[/:]vapiai\/gitops(\.git)?\/?$/i.test(origin); - } catch { - return false; - } +// 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 the engine's own repository, every test file imports the sandbox first", { - skip: engineRepository() +test("in CI for the engine's own repository, every test file imports the sandbox first", { + skip: engineRepositoryCi() ? false - : "not the engine's own repository: a test file without the import is this repository's own", + : "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, @@ -167,7 +157,7 @@ test("in the engine's own repository, every test file imports the sandbox first" 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 origin is VapiAI/gitops; in a repository of your own, with its own origin, a test of your own is left alone.`, + `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.`, ); }); diff --git a/tests/repository/import-check.test.ts b/tests/repository/import-check.test.ts index cfed564..1ba1c42 100644 --- a/tests/repository/import-check.test.ts +++ b/tests/repository/import-check.test.ts @@ -15,10 +15,12 @@ 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 the engine's own repository and in no other: anywhere -// else such a file is that repository's own test. 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. +// 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)); @@ -78,7 +80,7 @@ function importCheckIn(named: { runner?: string; origin?: string }): string { } } -test("the import check is asked in the engine's own repository, however it is named, and in no other", () => { +test("the import check is asked in CI for the engine's own repository, and nowhere else", () => { const fork = "acme/voice-agents"; assert.deepEqual( { @@ -86,40 +88,42 @@ test("the import check is asked in the engine's own repository, however it is na runner: "VapiAI/gitops", origin: "https://github.com/VapiAI/gitops", }), - "a clone over https": importCheckIn({ + "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 over https, typed in lower case and without .git": importCheckIn( - { origin: "https://github.com/vapiai/gitops" }, - ), - "a clone over ssh": importCheckIn({ + "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 clone of a fork over https": importCheckIn({ - origin: `https://github.com/${fork}.git`, - }), - "a clone of a fork over ssh": importCheckIn({ - origin: `git@github.com:${fork}.git`, + "a runner in a repository that kept the engine's origin": importCheckIn({ + runner: fork, + origin: "https://github.com/VapiAI/gitops.git", }), - "a fork that kept the name": importCheckIn({ + "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 clone over https": "own.test.ts lacks the import", - "a clone over https, typed in lower case and without .git": + "a runner in the engine's repository, named in lower case": "own.test.ts lacks the import", - "a clone over ssh": "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 clone of a fork over https": "not asked", - "a clone of a fork over ssh": "not asked", - "a fork that kept the name": "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", }, ); From 69fb957d99ff9774a95dd5837c561d89b98c484f Mon Sep 17 00:00:00 2001 From: dhruva Date: Sat, 21 Nov 2026 03:40:23 +0000 Subject: [PATCH 10/10] fix(state): integrate rebased state layout with main Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- src/api.ts | 1 - src/call.ts | 2 +- src/check-cmd.ts | 13 ++- src/hash-store.ts | 11 +- src/interactive.ts | 2 +- src/migrate-hash-store.ts | 2 +- src/org-pin.ts | 6 +- src/promote-cmd.ts | 24 ++-- src/pull.ts | 5 +- src/push.ts | 1 - src/rollback-cmd.ts | 9 +- src/setup-args.ts | 7 +- src/setup.ts | 33 +++--- src/sim.ts | 8 +- tests/adopt.test.ts | 1 + tests/api-key.test.ts | 54 ++++++--- tests/assistant-folder.test.ts | 1 + tests/bindings.test.ts | 26 ++--- tests/check-run.test.ts | 9 +- tests/cleanup-ignore.test.ts | 106 ++++++++--------- tests/cleanup-safety.test.ts | 2 +- tests/config-api-key.test.ts | 18 ++- tests/conflict-timing.test.ts | 14 ++- tests/credentials.test.ts | 2 +- tests/drift.test.ts | 78 ++++++++----- tests/list-pagination.test.ts | 36 ++++-- tests/name-collisions.test.ts | 1 + tests/new-file-gate.test.ts | 4 +- tests/org-connection.test.ts | 11 +- tests/org-pin.test.ts | 115 +++++++++++++++---- tests/promote-cmd.test.ts | 5 +- tests/promotion-gate.test.ts | 2 +- tests/promotion.test.ts | 6 +- tests/pull-rename-preserves-filename.test.ts | 2 +- tests/pull-same-name-clobber.test.ts | 2 +- tests/push-dry-run.test.ts | 2 +- tests/push-preflight.test.ts | 1 + tests/push-stale-baseline-noop.test.ts | 34 ++++-- tests/resource-type-args.test.ts | 5 +- tests/setup-noninteractive.test.ts | 64 ++++++++--- tests/sim-result.test.ts | 4 +- tests/sim.test.ts | 3 +- tests/so-assistant-omit.test.ts | 10 +- tests/state-layout-unseen-commit.test.ts | 4 +- tests/state-layout.test.ts | 12 +- tests/state-move-second-round.test.ts | 38 ++++-- tests/stop-report.test.ts | 1 + tests/user-agent-coverage.test.ts | 4 +- tests/vapi-ignore-push.test.ts | 2 +- 49 files changed, 523 insertions(+), 280 deletions(-) diff --git a/src/api.ts b/src/api.ts index b841bd9..9dc3451 100644 --- a/src/api.ts +++ b/src/api.ts @@ -71,7 +71,6 @@ export function orgPinGuard(): Promise { return orgPinChecked; } - export function getDryRunCounts(): { POST: number; PATCH: number; diff --git a/src/call.ts b/src/call.ts index 0a1a545..784d75b 100644 --- a/src/call.ts +++ b/src/call.ts @@ -1,10 +1,10 @@ -import { missingApiKeyMessage, resolveOrgApiKey } from "./api-key.ts"; import { execSync } from "child_process"; import { existsSync, readFileSync } from "fs"; import { createRequire } from "module"; 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"; diff --git a/src/check-cmd.ts b/src/check-cmd.ts index 373d16e..f7b0536 100644 --- a/src/check-cmd.ts +++ b/src/check-cmd.ts @@ -22,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, @@ -294,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); @@ -399,9 +404,7 @@ async function checksRun( export async function checkCommandRun( args = process.argv.slice(2), - root = resolve( - process.env.VAPI_GITOPS_ROOT ?? baseDir(), - ), + root = resolve(process.env.VAPI_GITOPS_ROOT ?? baseDir()), ): Promise { let parsed: CheckArgs; try { diff --git a/src/hash-store.ts b/src/hash-store.ts index b5eb64c..d35868b 100644 --- a/src/hash-store.ts +++ b/src/hash-store.ts @@ -37,8 +37,15 @@ 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)}`, + ); } } diff --git a/src/interactive.ts b/src/interactive.ts index 26d46ba..71bfb1b 100644 --- a/src/interactive.ts +++ b/src/interactive.ts @@ -1,8 +1,8 @@ -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 { 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 diff --git a/src/migrate-hash-store.ts b/src/migrate-hash-store.ts index 60e14a6..d82b24e 100644 --- a/src/migrate-hash-store.ts +++ b/src/migrate-hash-store.ts @@ -19,8 +19,8 @@ import { writeBaseline, } from "./hash-store.ts"; import { - STATE_DIR, commitStepAsk, + STATE_DIR, stateFileRead, stateMove, stateMoveRead, diff --git a/src/org-pin.ts b/src/org-pin.ts index be3ed2f..1df67af 100644 --- a/src/org-pin.ts +++ b/src/org-pin.ts @@ -21,8 +21,8 @@ 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"; @@ -140,7 +140,9 @@ export interface OrgPinCheckArgs { * 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" }; diff --git a/src/promote-cmd.ts b/src/promote-cmd.ts index 083cf36..f1cc39b 100644 --- a/src/promote-cmd.ts +++ b/src/promote-cmd.ts @@ -5,20 +5,8 @@ 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 { - OLD_LAYOUT_NOTICE, - stateFileRead, - stateLayout, - stateNoticesPrint, -} from "./state-paths.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, @@ -26,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; diff --git a/src/pull.ts b/src/pull.ts index ca199fd..ec7d2a3 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -984,7 +984,10 @@ export async function pullResourceType( statSync(localFile).mtimeMs > statSync(stamp).mtimeMs ) { console.log(` ✏️ ${resourceId} (locally modified, preserving)`); - upsertState(newStateSection, resourceId, { uuid: resource.id, origin: "pulled" }); + upsertState(newStateSection, resourceId, { + uuid: resource.id, + origin: "pulled", + }); skipped++; continue; } diff --git a/src/push.ts b/src/push.ts index 5edd085..c507dbd 100644 --- a/src/push.ts +++ b/src/push.ts @@ -25,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"; diff --git a/src/rollback-cmd.ts b/src/rollback-cmd.ts index a1c66d6..c9eac6f 100644 --- a/src/rollback-cmd.ts +++ b/src/rollback-cmd.ts @@ -8,9 +8,9 @@ // 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 { 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"; @@ -147,7 +147,12 @@ 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") diff --git a/src/setup-args.ts b/src/setup-args.ts index 17d2a16..ffd7566 100644 --- a/src/setup-args.ts +++ b/src/setup-args.ts @@ -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 a4b5e07..dc1b10c 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -3,13 +3,6 @@ import { execSync } from "child_process"; import { existsSync, readdirSync, readFileSync } from "fs"; import { mkdir, readFile, rm, writeFile } from "fs/promises"; import { join } from "path"; -import { baseDir } from "./base-dir.ts"; -import { - stateFileLabel, - stateFileLegacyPath, - stateFileRead, - stateOrgDir, -} from "./state-paths.ts"; import { API_KEY_VAR, API_KEYS_URL, @@ -17,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"; @@ -27,6 +21,12 @@ 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"; // ───────────────────────────────────────────────────────────────────────────── @@ -418,7 +418,9 @@ async function runDirectSetup(options: DirectSetupOptions): Promise { const resourceDir = join(BASE_DIR, "resources", slug); 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 @@ -451,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) { @@ -571,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); @@ -820,12 +826,7 @@ async function main(): Promise { console.log(c.bold(" Downloading...\n")); - invokePull( - slug, - downloadAll ? "all" : selectedIds, - trimmedKey, - vapiBaseUrl, - ); + invokePull(slug, downloadAll ? "all" : selectedIds, trimmedKey, vapiBaseUrl); // ── Done ────────────────────────────────────────────────────────────── diff --git a/src/sim.ts b/src/sim.ts index 5eabdda..1bf4cb9 100644 --- a/src/sim.ts +++ b/src/sim.ts @@ -4,25 +4,25 @@ // 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 { 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 BASE_DIR = baseDir(); 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/api-key.test.ts b/tests/api-key.test.ts index 811108b..c5dbf21 100644 --- a/tests/api-key.test.ts +++ b/tests/api-key.test.ts @@ -32,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); @@ -61,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", + }, ); }); @@ -95,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" }, ); }); @@ -107,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", () => { @@ -139,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/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/bindings.test.ts b/tests/bindings.test.ts index 6afcb00..22f5dc1 100644 --- a/tests/bindings.test.ts +++ b/tests/bindings.test.ts @@ -3,8 +3,8 @@ 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", () => { @@ -44,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, @@ -73,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); }); @@ -108,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); }); @@ -137,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-run.test.ts b/tests/check-run.test.ts index 6e53a2b..1faa07d 100644 --- a/tests/check-run.test.ts +++ b/tests/check-run.test.ts @@ -14,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/cleanup-ignore.test.ts b/tests/cleanup-ignore.test.ts index df8e040..0f974a4 100644 --- a/tests/cleanup-ignore.test.ts +++ b/tests/cleanup-ignore.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawn } from "node:child_process"; import { @@ -16,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 @@ -101,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 3d7218f..08a6910 100644 --- a/tests/cleanup-safety.test.ts +++ b/tests/cleanup-safety.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -13,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. // diff --git a/tests/config-api-key.test.ts b/tests/config-api-key.test.ts index cd93654..5d5e861 100644 --- a/tests/config-api-key.test.ts +++ b/tests/config-api-key.test.ts @@ -36,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 }); } @@ -67,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 4077526..ac9fbd8 100644 --- a/tests/conflict-timing.test.ts +++ b/tests/conflict-timing.test.ts @@ -65,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( @@ -78,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 971b304..ae7464f 100644 --- a/tests/credentials.test.ts +++ b/tests/credentials.test.ts @@ -3,8 +3,8 @@ 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/drift.test.ts b/tests/drift.test.ts index 337a9f8..bdd1425 100644 --- a/tests/drift.test.ts +++ b/tests/drift.test.ts @@ -1,17 +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, - readBaseline, - writeBaseline, -} from "../src/hash-store.ts"; // Stack G — drift unit tests. // `checkDriftForUpdate` itself fires GET against the Vapi platform; a unit @@ -62,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` @@ -511,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; @@ -576,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; @@ -687,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", () => { @@ -723,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/list-pagination.test.ts b/tests/list-pagination.test.ts index 4750a4d..c02c936 100644 --- a/tests/list-pagination.test.ts +++ b/tests/list-pagination.test.ts @@ -101,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"), @@ -120,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` @@ -131,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 () => { @@ -150,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/); }); @@ -213,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 df6fe0d..4527584 100644 --- a/tests/new-file-gate.test.ts +++ b/tests/new-file-gate.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -15,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 @@ -646,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 946cefe..28aad10 100644 --- a/tests/org-connection.test.ts +++ b/tests/org-connection.test.ts @@ -204,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 f94f068..2675137 100644 --- a/tests/org-pin.test.ts +++ b/tests/org-pin.test.ts @@ -35,7 +35,12 @@ import { VapiApiError } from "../src/vapi-client.ts"; 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. @@ -65,13 +70,24 @@ function orgDir(options: { folder: boolean; pin?: string }): string { } 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"]); }); @@ -79,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 () => { @@ -96,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"]); }); @@ -109,7 +132,13 @@ test("orgPinCheck pins an unpinned folder to the key's org", async () => { 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(orgPinFilePath(root, "acme"), "utf8"), @@ -124,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); @@ -138,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 { @@ -151,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; }, @@ -170,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 { @@ -183,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 { @@ -229,15 +291,24 @@ test("pull stops before listing anything when the key belongs to another org", a }; 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/promote-cmd.test.ts b/tests/promote-cmd.test.ts index e97cfa7..ca2c385 100644 --- a/tests/promote-cmd.test.ts +++ b/tests/promote-cmd.test.ts @@ -17,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( diff --git a/tests/promotion-gate.test.ts b/tests/promotion-gate.test.ts index 7b5b251..64d20fc 100644 --- a/tests/promotion-gate.test.ts +++ b/tests/promotion-gate.test.ts @@ -12,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. diff --git a/tests/promotion.test.ts b/tests/promotion.test.ts index e4822c8..6fc041f 100644 --- a/tests/promotion.test.ts +++ b/tests/promotion.test.ts @@ -463,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 d3285b5..fe4b6e7 100644 --- a/tests/pull-rename-preserves-filename.test.ts +++ b/tests/pull-rename-preserves-filename.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -18,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 diff --git a/tests/pull-same-name-clobber.test.ts b/tests/pull-same-name-clobber.test.ts index 81a71d8..4514eba 100644 --- a/tests/pull-same-name-clobber.test.ts +++ b/tests/pull-same-name-clobber.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -20,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. diff --git a/tests/push-dry-run.test.ts b/tests/push-dry-run.test.ts index 182b0da..a9872e4 100644 --- a/tests/push-dry-run.test.ts +++ b/tests/push-dry-run.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { stateFilePath } from "../src/state-paths.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -15,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. // 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 e46274e..c828d36 100644 --- a/tests/push-stale-baseline-noop.test.ts +++ b/tests/push-stale-baseline-noop.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -15,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 @@ -121,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 }); @@ -162,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 { @@ -197,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/resource-type-args.test.ts b/tests/resource-type-args.test.ts index e4518d7..09b5456 100644 --- a/tests/resource-type-args.test.ts +++ b/tests/resource-type-args.test.ts @@ -1,10 +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 b4e675b..6034483 100644 --- a/tests/setup-noninteractive.test.ts +++ b/tests/setup-noninteractive.test.ts @@ -94,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); }); @@ -110,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 || ""}`, @@ -181,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/); @@ -199,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/); @@ -214,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/); @@ -227,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 0aaa0fa..4c8da3a 100644 --- a/tests/sim-result.test.ts +++ b/tests/sim-result.test.ts @@ -2,10 +2,10 @@ 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.test.ts b/tests/sim.test.ts index 6870ec8..64dcb72 100644 --- a/tests/sim.test.ts +++ b/tests/sim.test.ts @@ -124,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/so-assistant-omit.test.ts b/tests/so-assistant-omit.test.ts index 852bf00..622b868 100644 --- a/tests/so-assistant-omit.test.ts +++ b/tests/so-assistant-omit.test.ts @@ -50,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", () => { @@ -243,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-layout-unseen-commit.test.ts b/tests/state-layout-unseen-commit.test.ts index 39d0801..9054270 100644 --- a/tests/state-layout-unseen-commit.test.ts +++ b/tests/state-layout-unseen-commit.test.ts @@ -18,14 +18,14 @@ import { fileURLToPath } from "node:url"; import { migrateAll } from "../src/migrate-hash-store.ts"; import { COMMIT_STEP_FLAG, - OLD_LAYOUT_NOTICE, - StateLayoutError, commitStepAcknowledge, commitStepAsk, commitStepFilePath, commitStepRead, + OLD_LAYOUT_NOTICE, orgPinFileLegacyPath, orgPinFileWrite, + StateLayoutError, stateFileLegacyPath, stateFilePath, stateFileWrite, diff --git a/tests/state-layout.test.ts b/tests/state-layout.test.ts index cdbe56d..dd09c25 100644 --- a/tests/state-layout.test.ts +++ b/tests/state-layout.test.ts @@ -6,8 +6,8 @@ import { existsSync, mkdirSync, mkdtempSync, - readFileSync, readdirSync, + readFileSync, rmSync, symlinkSync, utimesSync, @@ -21,13 +21,13 @@ import test from "node:test"; import { fileURLToPath } from "node:url"; import { assertStateMigrated, migrateAll } from "../src/migrate-hash-store.ts"; import { - OLD_LAYOUT_NOTICE, - StateLayoutError, baselinesDir, commitStepAcknowledge, + OLD_LAYOUT_NOTICE, orgPinFilePath, orgPinFileRead, orgPinFileWrite, + StateLayoutError, snapshotsDir, stateFileLeftover, stateFilePath, @@ -507,7 +507,7 @@ test("two state files that disagree stop the command with both intact", () => { // ── npm run migrate and the legacy-format guard ────────────────────────── -const FAT_STATE = `${JSON.stringify({ assistants: { intake: { uuid: UUID, lastPulledAt: "2026-01-01T00:00:00Z" } } })}\n`; +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-")); @@ -575,7 +575,7 @@ test("under a commit step seen to stage state/, migrate slims and moves every or ], after: { ...MOVED, - state: { assistants: { intake: { uuid: UUID } } }, + state: { assistants: { intake: { uuid: UUID, origin: "pulled" } } }, }, rootLeftovers: [], again: [ @@ -617,7 +617,7 @@ test("migrate slims in place and moves nothing while a workflow would drop state ".vapi-state.acme.json", true, [], - { assistants: { intake: { uuid: UUID } } }, + { assistants: { intake: { uuid: UUID, origin: "pulled" } } }, undefined, true, false, diff --git a/tests/state-move-second-round.test.ts b/tests/state-move-second-round.test.ts index dd5ddb0..592b6a0 100644 --- a/tests/state-move-second-round.test.ts +++ b/tests/state-move-second-round.test.ts @@ -77,12 +77,19 @@ const rileyFile = (prompt: string): string => "\n"; // What a CI runner has: a clone of the committed repository and nothing else. -function freshClone(layout: "root" | "folder"): { root: string; drop: () => void } { +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, + ".gitignore", + "node_modules\nstate/*/local/\n.vapi-state-hash/\n", + ); put(source, "resources/dev/assistants/riley.md", rileyFile(MERGED)); put( source, @@ -197,11 +204,16 @@ 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 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], + 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], @@ -213,7 +225,11 @@ const STEPS: Record = { ], }, "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: [ + 'echo "state is staged by the helper, not by: git add -A -- state"', + "./scripts/stage-state.sh", + ...TAIL, + ], }, }; @@ -249,7 +265,11 @@ test("a git add that leaves state/ out is not read as staging state/", () => { 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)); + put( + root, + ".github/workflows/promotion.yml", + workflow(step.run, step.extraJob), + ); const read = commitStepRead(root, {}).kind; seen[name] = { commitsState: stepCommitsStateFolder(step.run), @@ -271,7 +291,11 @@ test("with nothing seen to stage state/, a command that is not migrate leaves co // 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, + ".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( 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/user-agent-coverage.test.ts b/tests/user-agent-coverage.test.ts index 4dae029..4ce6921 100644 --- a/tests/user-agent-coverage.test.ts +++ b/tests/user-agent-coverage.test.ts @@ -75,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/vapi-ignore-push.test.ts b/tests/vapi-ignore-push.test.ts index 56fde76..5a9a187 100644 --- a/tests/vapi-ignore-push.test.ts +++ b/tests/vapi-ignore-push.test.ts @@ -1,5 +1,4 @@ import "./engine-sandbox.ts"; -import { baselinesDir, stateFixturePath } from "./state-fixture.ts"; import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import { @@ -15,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.