|
| 1 | +// Per-developer drift baseline store. |
| 2 | +// |
| 3 | +// The "last known platform state" content hash for each resource lives here, |
| 4 | +// in `.vapi-state-hash/<org>/<uuid>` — one file per resource, filename is the |
| 5 | +// platform UUID, contents are the sha256 baseline hash. This is the hash a |
| 6 | +// push compares against the live dashboard to decide whether someone changed |
| 7 | +// the resource out of band since I last pulled or pushed it. |
| 8 | +// |
| 9 | +// Design constraints: |
| 10 | +// - GITIGNORED, per-developer. The baseline is "what *I* last saw on the |
| 11 | +// platform," not a shared fact — it must not be committed. |
| 12 | +// - CONFIG-FREE. This module must NOT import `config.ts`, which parses a |
| 13 | +// single org and `process.exit(1)`s at module load if no VAPI_TOKEN is |
| 14 | +// set. The migration command needs to operate on every org without a |
| 15 | +// token, so the org is always passed in explicitly and BASE_DIR is |
| 16 | +// computed here the same way `config.ts` computes it. |
| 17 | +// - The filename (UUID) is purely organizational. The hash is computed over |
| 18 | +// canonical resource CONTENT by callers; this module never inspects it. |
| 19 | + |
| 20 | +import { existsSync, mkdirSync, readFileSync } from "fs"; |
| 21 | +import { rename, writeFile } from "fs/promises"; |
| 22 | +import { dirname, join } from "path"; |
| 23 | +import { fileURLToPath } from "url"; |
| 24 | + |
| 25 | +// Same expression as config.ts: the repo root is one level up from src/. |
| 26 | +const BASE_DIR = join(dirname(fileURLToPath(import.meta.url)), ".."); |
| 27 | + |
| 28 | +// Top-level store directory. Per-org subfolders live beneath it. Exported so |
| 29 | +// the migration can locate every org's baselines and so `.gitignore` reasoning |
| 30 | +// stays in one place. |
| 31 | +export const HASH_STORE_ROOT = join(BASE_DIR, ".vapi-state-hash"); |
| 32 | + |
| 33 | +// Guard against a UUID that would escape its org folder. Platform UUIDs never |
| 34 | +// contain these, but reading them straight into a path warrants a check. |
| 35 | +function assertSafeUuid(uuid: string): void { |
| 36 | + if (!uuid || uuid.includes("/") || uuid.includes("\\") || uuid.includes("..")) { |
| 37 | + throw new Error(`Refusing to use unsafe hash-store key: ${JSON.stringify(uuid)}`); |
| 38 | + } |
| 39 | +} |
| 40 | + |
| 41 | +export function hashStoreDir(org: string): string { |
| 42 | + return join(HASH_STORE_ROOT, org); |
| 43 | +} |
| 44 | + |
| 45 | +function baselinePath(org: string, uuid: string): string { |
| 46 | + assertSafeUuid(uuid); |
| 47 | + return join(hashStoreDir(org), uuid); |
| 48 | +} |
| 49 | + |
| 50 | +// Read the baseline hash for a resource, or undefined if none has been |
| 51 | +// recorded yet (fresh clone, never pulled/pushed). Undefined maps to the |
| 52 | +// `no-baseline` drift direction — the caller proceeds without blocking. |
| 53 | +export function readBaseline(org: string, uuid: string): string | undefined { |
| 54 | + const path = baselinePath(org, uuid); |
| 55 | + if (!existsSync(path)) return undefined; |
| 56 | + const contents = readFileSync(path, "utf-8").trim(); |
| 57 | + return contents.length > 0 ? contents : undefined; |
| 58 | +} |
| 59 | + |
| 60 | +// Write (or overwrite) the baseline hash for a resource. Atomic: emit to a |
| 61 | +// sibling temp file then rename over the target, so a crash mid-write can't |
| 62 | +// leave a truncated hash that would manufacture phantom drift. Creates the |
| 63 | +// org subfolder on demand. |
| 64 | +export async function writeBaseline( |
| 65 | + org: string, |
| 66 | + uuid: string, |
| 67 | + hash: string, |
| 68 | +): Promise<void> { |
| 69 | + const path = baselinePath(org, uuid); |
| 70 | + mkdirSync(hashStoreDir(org), { recursive: true }); |
| 71 | + const tmpPath = `${path}.tmp`; |
| 72 | + await writeFile(tmpPath, `${hash}\n`); |
| 73 | + await rename(tmpPath, path); |
| 74 | +} |
| 75 | + |
| 76 | +// Remove a baseline. Used when a stale state mapping is dropped (the resource |
| 77 | +// no longer exists on the platform), mirroring the existing |
| 78 | +// `delete stateSection[resourceId]` recovery. Missing file is a no-op. |
| 79 | +export async function deleteBaseline(org: string, uuid: string): Promise<void> { |
| 80 | + const path = baselinePath(org, uuid); |
| 81 | + if (!existsSync(path)) return; |
| 82 | + const { rm } = await import("fs/promises"); |
| 83 | + await rm(path, { force: true }); |
| 84 | +} |
0 commit comments