diff --git a/AGENTS.md b/AGENTS.md index ccdb627..f8def70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -250,6 +250,17 @@ default-exports the object (safety rule 5). The engine resolves IDs and credential names to each org's UUIDs on push. +Assistant subfolders are pushed as derived `metadata.gitops.folderPath` (for example +`assistants/support/intake.yml` → `support`). Other metadata and sibling `gitops` +keys are preserved; top-level `metadata.folderPath` is a user key, left untouched. +The full subfolder path is preserved: +`assistants/support/intake/b.yml` → `support/intake`. +Root assistants send `metadata.gitops.folderPath: null`, clearing stale grouping. +Pull and drift exclude this key; don't author it locally. File moves still require the normal +filename/state mapping safeguards below. Other resource types are unchanged. +If authored, `metadata.gitops` must be a plain object. Pull removes only the +derived key, dropping `gitops` and `metadata` only if they become empty. + ### Naming and renaming - **Files you create keep their names.** Resources pulled from the platform @@ -264,7 +275,7 @@ The engine resolves IDs and credential names to each org's UUIDs on push. | To rename… | Do this | | --- | --- | | The display name | Change `name` in the file (or in the dashboard, then pull). The filename stays. | -| The file itself | A renamed file has no state entry, so the next deploy stops at the new-file check. Either keep the old filename, or (with the human's agreement) deploy it as new with `--allow-new-files` and delete the old platform resource with `npm run cleanup -- --force --confirm `. | +| The file itself | A renamed or moved file has no state entry. With the human's agreement, use `--adopt =` to keep managing the same platform resource under the new path. Without adoption, an unlinked file is created as a new resource, not matched by name. | ### Excluding resources (`.vapi-ignore`) diff --git a/README.md b/README.md index e7a7d6f..6e928eb 100644 --- a/README.md +++ b/README.md @@ -182,6 +182,17 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec - **Secrets stay out of git.** API keys live in `.env.` (gitignored) or CI secrets. Credentials are referenced by name and bound to each org's own credentials. +- **Assistant subfolders group the dashboard.** Pushing + `assistants/support/intake.yml` sets `metadata.gitops.folderPath` to + `support`, preserving other authored metadata and sibling `gitops` keys. + A top-level `metadata.folderPath` remains a user-authored key. The full + subfolder path is preserved: `assistants/support/intake/b.yml` sets + `metadata.gitops.folderPath` to `support/intake`. Root assistants send + `metadata.gitops.folderPath: null` to clear any previous folder. This derived key is omitted + on pull and ignored for drift; do not author it in YAML. Moving files still + requires explicit `--adopt =` to retain the same platform + 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 that, every command checks the key against it before any request, and stops diff --git a/docs/guides/commands.md b/docs/guides/commands.md index fc64295..f38a988 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -97,6 +97,19 @@ adoption before dependency resolution to take one over instead. ## Interactive Mode +Assistant pushes (including the push phase of `apply`) derive +`metadata.gitops.folderPath` from the full subfolder path under `assistants/`, preserving +other authored metadata and sibling `gitops` keys: +`assistants/support/intake.yml` groups under `support`. +Nested paths are preserved: `assistants/support/intake/b.yml` groups under +`support/intake`. Root files send +`metadata.gitops.folderPath: null` to clear grouping. +Pull omits this derived key, dropping empty `gitops`/`metadata` objects, and drift +comparisons ignore it. Top-level `metadata.folderPath` is a user key, left +untouched. Authored `metadata.gitops` must be a plain object. To move a file +while retaining its platform UUID, explicitly adopt it with +`--adopt =`; the subsequent push updates its folder path. + When you run a command without arguments, you get a fully interactive experience: ```bash diff --git a/src/assistant-folder.ts b/src/assistant-folder.ts new file mode 100644 index 0000000..a0af731 --- /dev/null +++ b/src/assistant-folder.ts @@ -0,0 +1,58 @@ +function isPlainObject(value: unknown): value is Record { + return ( + value !== null && + typeof value === "object" && + (Object.getPrototypeOf(value) === Object.prototype || + Object.getPrototypeOf(value) === null) + ); +} + +export function withoutAssistantFolder( + data: Record, +): Record { + const metadata = data.metadata; + if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) { + return data; + } + const gitops = (metadata as Record).gitops; + if (!isPlainObject(gitops)) return data; + const { folderPath: _, ...rest } = gitops; + const remainingMetadata = { ...(metadata as Record) }; + if (Object.keys(rest).length > 0) remainingMetadata.gitops = rest; + else delete remainingMetadata.gitops; + const result = { ...data }; + if (Object.keys(remainingMetadata).length > 0) + result.metadata = remainingMetadata; + else delete result.metadata; + return result; +} + +export function withAssistantFolder( + data: Record, + resourceId: string, +): Record { + const normalized = resourceId.replace(/\\/g, "/"); + const slash = normalized.lastIndexOf("/"); + const metadata = data.metadata; + if ( + metadata != null && + (typeof metadata !== "object" || Array.isArray(metadata)) + ) { + throw new Error("Assistant metadata must be an object"); + } + const gitops = (metadata as Record | null | undefined) + ?.gitops; + if (metadata && Object.hasOwn(metadata, "gitops") && !isPlainObject(gitops)) { + throw new Error("Assistant metadata.gitops must be a plain object"); + } + return { + ...data, + metadata: { + ...(metadata as Record | undefined), + gitops: { + ...(gitops as Record | undefined), + folderPath: slash < 0 ? null : normalized.slice(0, slash), + }, + }, + }; +} diff --git a/src/audit.ts b/src/audit.ts index 1de1992..f5f915e 100644 --- a/src/audit.ts +++ b/src/audit.ts @@ -21,12 +21,12 @@ import { readFile } from "fs/promises"; import { join } from "path"; +import { canonicalizeForHash, type VapiResource } from "./canonical.ts"; import { matchesIgnore, RESOURCES_DIR, VAPI_ENV } from "./config.ts"; import { credentialReverseMap } from "./credentials.ts"; import { classifyDrift } from "./drift.ts"; import { readBaseline } from "./hash-store.ts"; import { findOrphanResourceIds } from "./new-file-gate.ts"; -import { canonicalizeForHash, type VapiResource } from "./canonical.ts"; import { fetchAllResources, listExistingResourceIds } from "./pull.ts"; import { FOLDER_MAP, hashLocalResource } from "./resources.ts"; import { extractBaseSlug, slugify } from "./slug-utils.ts"; @@ -393,7 +393,7 @@ function checkContentDrift( // canonicalizeForHash centralizes the 3-step pipeline + _platformDefault // mutation so the hash agrees with the pull-write baseline basis. const platformHash = hashPayload( - canonicalizeForHash(remoteResource, state, credReverse), + canonicalizeForHash(remoteResource, state, credReverse, type), ); const direction = classifyDrift({ localHash, diff --git a/src/canonical.ts b/src/canonical.ts index 5c49b62..cde5306 100644 --- a/src/canonical.ts +++ b/src/canonical.ts @@ -12,6 +12,7 @@ // drift, so drift could not import back — it grew a divergent copy instead). // ───────────────────────────────────────────────────────────────────────────── +import { withoutAssistantFolder } from "./assistant-folder.ts"; import { replaceCredentialRefs } from "./credentials.ts"; import type { ResourceType, StateFile } from "./types.ts"; @@ -210,9 +211,12 @@ export function canonicalizeForHash( resource: VapiResource, state: StateFile, credReverse: Map, + resourceType?: ResourceType, ): Record { const cleaned = cleanResource(resource); - const resolved = resolveReferencesToResourceIds(cleaned, state); + const content = + resourceType === "assistants" ? withoutAssistantFolder(cleaned) : cleaned; + const resolved = resolveReferencesToResourceIds(content, state); const withCredNames = replaceCredentialRefs(resolved, credReverse); const isPlatformDefault = resource.orgId === null || resource.orgId === undefined; diff --git a/src/drift.ts b/src/drift.ts index 1b0efdf..18449e4 100644 --- a/src/drift.ts +++ b/src/drift.ts @@ -18,7 +18,7 @@ // has nothing to compare against — only PATCH (update) is drift-sensitive. // ───────────────────────────────────────────────────────────────────────────── -import { vapiGet, VapiApiError } from "./api.ts"; +import { VapiApiError, vapiGet } from "./api.ts"; import { canonicalizeForHash, type VapiResource } from "./canonical.ts"; import { credentialReverseMap } from "./credentials.ts"; import { readBaseline } from "./hash-store.ts"; @@ -144,7 +144,12 @@ export async function checkDriftForUpdate(options: { // resource hashed differently here than at pull time → phantom both-diverged. const credReverse = credentialReverseMap(state); const platformHash = hashPayload( - canonicalizeForHash(remote as VapiResource, state, credReverse), + canonicalizeForHash( + remote as VapiResource, + state, + credReverse, + resourceType, + ), ); if (platformHash === baseline) { return { ok: true, reason: "match", platformHash, platformPayload: remote }; @@ -153,8 +158,7 @@ export async function checkDriftForUpdate(options: { // On-disk hash in the same basis as the baseline. Absent a local file // (rare on an update path), fall back to the baseline so the direction is // dashboard-ahead rather than a phantom both-diverged. - const localHash = - hashLocalResource(resourceType, resourceId) ?? baseline; + const localHash = hashLocalResource(resourceType, resourceId) ?? baseline; // Local and platform are byte-identical → there is nothing to reconcile and // the PATCH is a no-op. NEVER block here, even if the baseline disagrees diff --git a/src/pull.ts b/src/pull.ts index f032294..95a8c86 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -538,6 +538,7 @@ export async function writeDashboardBackup( platformPayload, state, credReverse, + resourceType, ); // Filesystem-safe ISO timestamp: 2026-06-04T19-22-33 (no colons, no ms). const timestamp = new Date() @@ -844,7 +845,7 @@ export async function pullResourceType( // classifier, audit, and resolveBothDiverged sites. Any asymmetry here // makes every drifted file look `both-diverged` even when content matches. const platformHash = hashPayload( - canonicalizeForHash(resource, state, credReverse), + canonicalizeForHash(resource, state, credReverse, resourceType), ); // Note: classifyDrift treats live local + platform agreement as // `clean` whatever the (possibly stale) baseline says — the clean @@ -1015,7 +1016,12 @@ export async function pullResourceType( // Single canonicalization for both the file write AND the lastPulledHash // fallback. Encodes the 3-step pipeline (cleanResource → resolve refs → // replace credential UUIDs) plus the _platformDefault marker. - const withCredNames = canonicalizeForHash(resource, state, credReverse); + const withCredNames = canonicalizeForHash( + resource, + state, + credReverse, + resourceType, + ); if (bootstrap) { const icon = isPlatformDefault ? "🔒" : isNew ? "✨" : "📝"; @@ -1175,6 +1181,7 @@ async function resolveBothDivergedResources(options: { entry.resource, state, credReverse, + entry.resourceType, ); await writeResourceFile( diff --git a/src/push.ts b/src/push.ts index 0067b27..83066da 100644 --- a/src/push.ts +++ b/src/push.ts @@ -2,6 +2,7 @@ import { select } from "@inquirer/prompts"; import { relative, resolve } from "path"; import { fileURLToPath } from "url"; import { getDryRunCounts, VapiApiError, vapiRequest } from "./api.ts"; +import { withAssistantFolder } from "./assistant-folder.ts"; import { canonicalizeForHash, type VapiResource } from "./canonical.ts"; import { APPLY_FILTER, @@ -152,13 +153,19 @@ async function writeBaselineFromResponse( uuid: string, response: unknown, state: StateFile, + resourceType?: ResourceType, ): Promise { if (DRY_RUN) return; if (!response || typeof response !== "object") return; try { const credReverse = credentialReverseMap(state); const hash = hashPayload( - canonicalizeForHash(response as VapiResource, state, credReverse), + canonicalizeForHash( + response as VapiResource, + state, + credReverse, + resourceType, + ), ); await writeBaseline(VAPI_ENV, uuid, hash); } catch (err) { @@ -253,7 +260,12 @@ async function upsertResourceWithStateRecovery(options: { uuid: result.id, origin: "pushed", }); - await writeBaselineFromResponse(result.id, result, fullState); + await writeBaselineFromResponse( + result.id, + result, + fullState, + RESOURCE_LABEL_TO_TYPE[resourceLabel], + ); if (resourceLabel === "assistant") { await writeAssistantVersionMetadata({ uuid: result.id, @@ -407,7 +419,12 @@ async function upsertResourceWithStateRecovery(options: { // The PATCH response is the full resource as the platform now stores it — // the freshest possible "last known platform state." Hash it as the new // drift baseline so the next push of a further local edit is clean. - await writeBaselineFromResponse(existingUuid, result, fullState); + await writeBaselineFromResponse( + existingUuid, + result, + fullState, + RESOURCE_LABEL_TO_TYPE[resourceLabel], + ); if (resourceLabel === "assistant" && platformPayloadForSnapshot) { await writeAssistantVersionMetadata({ uuid: existingUuid, @@ -884,7 +901,10 @@ export async function applyAssistant( const existingUuid = state.assistants[resourceId]?.uuid; // Resolve tool and structured output references - const payload = resolveReferences(data as Record, state); + const payload = withAssistantFolder( + resolveReferences(data as Record, state), + resourceId, + ); return upsertResourceWithStateRecovery({ resourceLabel: "assistant", diff --git a/src/resources.ts b/src/resources.ts index 6ac5213..e47bc79 100644 --- a/src/resources.ts +++ b/src/resources.ts @@ -2,6 +2,7 @@ import { existsSync } from "fs"; import { readFile } from "fs/promises"; import { basename, extname, join, relative, resolve } from "path"; import { parse as parseYaml } from "yaml"; +import { withoutAssistantFolder } from "./assistant-folder.ts"; import { BASE_DIR, matchesIgnore, RESOURCES_DIR } from "./config.ts"; import { FOLDER_MAP, @@ -16,10 +17,10 @@ import { stateUuid } from "./state.ts"; import { hashPayload } from "./state-serialize.ts"; import type { ResourceFile, ResourceType, StateFile } from "./types.ts"; +export type { LoadOptions }; // The file-reading half lives in resource-parse.ts (config-free). These are // re-exported so existing importers keep working. export { FOLDER_MAP, VALID_EXTENSIONS }; -export type { LoadOptions }; function findLocalResourceFile( type: ResourceType, @@ -42,7 +43,10 @@ export function hashLocalResource( const filePath = findLocalResourceFile(type, resourceId); if (!filePath) return null; try { - return hashPayload(parseResourceDataFromFile(filePath)); + const data = parseResourceDataFromFile(filePath); + return hashPayload( + type === "assistants" ? withoutAssistantFolder(data) : data, + ); } catch { return null; } diff --git a/tests/assistant-folder.test.ts b/tests/assistant-folder.test.ts new file mode 100644 index 0000000..618fd21 --- /dev/null +++ b/tests/assistant-folder.test.ts @@ -0,0 +1,216 @@ +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { cpSync, mkdtempSync, rmSync, symlinkSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { + withAssistantFolder, + withoutAssistantFolder, +} from "../src/assistant-folder.ts"; +import { canonicalizeForHash } from "../src/canonical.ts"; +import { hashPayload } from "../src/state-serialize.ts"; +import type { StateFile } from "../src/types.ts"; + +const state = { + assistants: {}, + tools: {}, + squads: {}, + structuredOutputs: {}, + personalities: {}, + scenarios: {}, + simulations: {}, + simulationSuites: {}, + evals: {}, + credentials: {}, +} as StateFile; + +test("assistant POST/PATCH and response baselines share the folder-free hash basis", () => { + const root = new URL("../", import.meta.url).pathname; + const dir = mkdtempSync(join(tmpdir(), "gitops-folder-")); + try { + cpSync(join(root, "src"), join(dir, "src"), { recursive: true }); + cpSync(join(root, "package.json"), join(dir, "package.json")); + symlinkSync(join(root, "node_modules"), join(dir, "node_modules"), "dir"); + const script = ` + import assert from 'node:assert/strict'; + process.argv = ['node', 'test', 'folder-test']; + process.env.VAPI_TOKEN = 'fake'; + process.env.VAPI_GITOPS_ORG_PIN = 'off'; + const { applyAssistant } = await import('./src/push.ts'); + const { readBaseline } = await import('./src/hash-store.ts'); + const { hashPayload } = await import('./src/state-serialize.ts'); + const state = ${JSON.stringify(state)}; + const requests = []; + globalThis.fetch = async (url, options) => { + if (options.method === 'GET') return new Response(JSON.stringify({ ...data, id: 'uuid', orgId: 'org', metadata: { ...data.metadata, gitops: { owner: 'repo', folderPath: 'old' } } })); + const body = JSON.parse(options.body); + requests.push({ method: options.method, body }); + return new Response(JSON.stringify({ ...body, id: 'uuid', orgId: 'org' })); + }; + const data = { name: 'Intake', metadata: { team: 'support', folderPath: 'user', gitops: { owner: 'repo' } } }; + await applyAssistant({ resourceId: 'support/tier2/intake', filePath: '', data }, state); + assert.equal(requests[0].method, 'POST'); + assert.deepEqual(requests[0].body.metadata, { ...data.metadata, gitops: { owner: 'repo', folderPath: 'support/tier2' } }); + assert.deepEqual(state.assistants['support/tier2/intake'], { uuid: 'uuid', origin: 'pushed' }); + assert.equal(readBaseline('folder-test', 'uuid'), hashPayload(data)); + requests.length = 0; + const { adoptResources } = await import('./src/adopt.ts'); + const resources = Object.fromEntries(Object.keys(state).filter(k => k !== 'credentials').map(k => [k, []])); + resources.assistants = [{ resourceId: 'intake', filePath: '', data }]; + const touched = Object.fromEntries(Object.keys(resources).map(k => [k, new Set()])); + await adoptResources({ + targets: ['intake=uuid'], resources, state, touched, + getRemoteList: async () => [{ id: 'uuid', name: 'Intake' }], dryRun: false, + }); + assert.equal(state.assistants['support/tier2/intake'], undefined); + assert.deepEqual(state.assistants.intake, { uuid: 'uuid', origin: 'adopted' }); + await applyAssistant({ resourceId: 'intake', filePath: '', data }, state); + const patch = requests.find(r => r.method === 'PATCH' && r.body.name === 'Intake'); + assert.deepEqual(patch.body.metadata, { ...data.metadata, gitops: { owner: 'repo', folderPath: null } }); + assert.equal(readBaseline('folder-test', 'uuid'), hashPayload(data)); + const { pullResourceType } = await import('./src/pull.ts'); + const { hashLocalResource } = await import('./src/resources.ts'); + const { readFileSync, mkdirSync, writeFileSync } = await import('node:fs'); + mkdirSync('./resources/folder-test/assistants', { recursive: true }); + writeFileSync('./resources/folder-test/assistants/intake.yml', JSON.stringify(data)); + globalThis.fetch = async () => new Response(JSON.stringify([ + { ...data, id: 'uuid', orgId: 'org', metadata: { ...data.metadata, gitops: { owner: 'repo', folderPath: 'support' } } }, + ])); + const pulled = await pullResourceType('assistants', state, { force: true }); + assert.equal(pulled.created + pulled.updated, 1); + const { parse } = await import('yaml'); + const yaml = readFileSync('./resources/folder-test/assistants/intake.yml', 'utf8'); + assert.deepEqual(parse(yaml).metadata, data.metadata); + assert.equal(hashLocalResource('assistants', 'intake'), readBaseline('folder-test', 'uuid')); + `; + const result = spawnSync( + "node", + ["--import", "tsx", "--input-type=module", "-e", script], + { + cwd: dir, + env: { ...process.env, VAPI_BASE_URL: "http://127.0.0.1:9" }, + encoding: "utf8", + timeout: 20000, + }, + ); + assert.equal(result.status, 0, result.stdout + result.stderr); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("folder payloads preserve user metadata and override derived values", () => { + const data = { + name: "Intake", + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath: "old" }, + }, + }; + assert.deepEqual(withAssistantFolder(data, "support/tier2/intake"), { + name: "Intake", + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath: "support/tier2" }, + }, + }); + assert.equal(data.metadata.gitops.folderPath, "old"); + assert.deepEqual(withAssistantFolder({}, "support/intake"), { + metadata: { gitops: { folderPath: "support" } }, + }); +}); + +test("moving to root explicitly clears a stale folder without losing metadata", () => { + assert.deepEqual( + withAssistantFolder( + { metadata: { team: "support", gitops: { folderPath: "old" } } }, + "intake", + ), + { + metadata: { team: "support", gitops: { folderPath: null } }, + }, + ); + assert.deepEqual(withAssistantFolder({}, "intake"), { + metadata: { gitops: { folderPath: null } }, + }); + assert.deepEqual(withAssistantFolder({ metadata: null }, "intake"), { + metadata: { gitops: { folderPath: null } }, + }); +}); + +test("invalid assistant metadata is rejected instead of silently overwritten", () => { + for (const metadata of ["bad", 1, []]) { + assert.throws( + () => withAssistantFolder({ metadata }, "intake"), + /metadata must be an object/, + ); + } + for (const gitops of [null, undefined, "bad", 1, [], new Date()]) { + assert.throws( + () => withAssistantFolder({ metadata: { gitops } }, "intake"), + /metadata.gitops must be a plain object/, + ); + } + assert.deepEqual( + withAssistantFolder({ metadata: { gitops: {} } }, "intake"), + { + metadata: { gitops: { folderPath: null } }, + }, + ); +}); + +test("pull and drift canonical forms ignore only assistant folder metadata", () => { + for (const folderPath of ["support", "support/tier2", null]) { + const remote = { + id: "uuid", + orgId: "org", + name: "Intake", + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath }, + }, + }; + const local = { + name: "Intake", + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo" }, + }, + }; + const canonical = canonicalizeForHash( + remote, + state, + new Map(), + "assistants", + ); + assert.deepEqual(canonical, local); + assert.equal( + hashPayload(canonical), + hashPayload(withoutAssistantFolder(local)), + ); + assert.deepEqual( + canonicalizeForHash(remote, state, new Map(), "squads").metadata, + remote.metadata, + ); + assert.equal(remote.metadata.gitops.folderPath, folderPath); + } + assert.deepEqual( + withoutAssistantFolder({ metadata: { gitops: { folderPath: "support" } } }), + {}, + ); + assert.deepEqual(withoutAssistantFolder({ metadata: { gitops: {} } }), {}); + assert.deepEqual( + withoutAssistantFolder({ + metadata: { folderPath: "user", gitops: { folderPath: "support" } }, + }), + { metadata: { folderPath: "user" } }, + ); + assert.deepEqual(withoutAssistantFolder({ name: "Intake" }), { + name: "Intake", + }); +});