From be6b92e011dcda70ba6f2693f6783ebdeec789cc Mon Sep 17 00:00:00 2001 From: dhruva Date: Sat, 21 Nov 2026 00:13:03 +0000 Subject: [PATCH 1/3] feat(push): sync assistant subfolders as derived metadata Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 6 ++ README.md | 7 ++ docs/guides/commands.md | 6 ++ src/assistant-folder.ts | 35 +++++++ src/audit.ts | 4 +- src/canonical.ts | 6 +- src/drift.ts | 12 ++- src/pull.ts | 14 ++- src/push.ts | 28 +++++- src/resources.ts | 8 +- tests/assistant-folder.test.ts | 169 +++++++++++++++++++++++++++++++++ 11 files changed, 279 insertions(+), 16 deletions(-) create mode 100644 src/assistant-folder.ts create mode 100644 tests/assistant-folder.test.ts diff --git a/AGENTS.md b/AGENTS.md index 1a4c96d..6d81f73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -223,6 +223,12 @@ 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.folderPath` (for example +`assistants/support/intake.yml` → `support`). Other metadata keys are preserved. +Root assistants send `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. + ### Naming and renaming - **Files you create keep their names.** Resources pulled from the platform diff --git a/README.md b/README.md index 9984b3d..eaf7b9a 100644 --- a/README.md +++ b/README.md @@ -182,6 +182,13 @@ 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/tier2/intake.yml` sets `metadata.folderPath` to + `support/tier2`, preserving other authored metadata. Root assistants send + `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 + follows the normal filename/state mapping safeguards. `apply` uses the same + 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 299b12f..a2deb13 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -26,6 +26,12 @@ The other commands are direct only. ## Interactive Mode +Assistant pushes (including the push phase of `apply`) derive +`metadata.folderPath` from the file's subfolder under `assistants/`, preserving +other authored metadata. Root files send `folderPath: null` to clear grouping. +Pull omits this derived key, and drift comparisons ignore it. Moving a file +still follows the normal rename/state mapping safeguards. + 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..3a13321 --- /dev/null +++ b/src/assistant-folder.ts @@ -0,0 +1,35 @@ +export function withoutAssistantFolder( + data: Record, +): Record { + const metadata = data.metadata; + if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) { + return data; + } + const { folderPath: _, ...rest } = metadata as Record; + const result = { ...data }; + if (Object.keys(rest).length > 0) result.metadata = rest; + 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"); + } + return { + ...data, + metadata: { + ...(metadata 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 62b487f..0b4da3a 100644 --- a/src/pull.ts +++ b/src/pull.ts @@ -226,7 +226,8 @@ async function fetchPagedList( // A short first page proves we saw everything in one request — the common case // pays nothing for paging. - if (first.length < LIST_PAGE_SIZE) return { resources: first, complete: true }; + if (first.length < LIST_PAGE_SIZE) + return { resources: first, complete: true }; // A full page means the response was capped. Walk backwards through // `createdAt`, the only cursor these endpoints offer. @@ -582,6 +583,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() @@ -905,7 +907,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 @@ -1064,7 +1066,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 ? "✨" : "📝"; @@ -1218,6 +1225,7 @@ async function resolveBothDivergedResources(options: { entry.resource, state, credReverse, + entry.resourceType, ); await writeResourceFile( diff --git a/src/push.ts b/src/push.ts index c22f41d..b88c0b8 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 { ALLOW_NEW_FILES, @@ -156,13 +157,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) { @@ -243,7 +250,12 @@ async function upsertResourceWithStateRecovery(options: { if (!existingUuid) { console.log(` ✨ Creating ${resourceLabel}: ${resourceId}`); const result = await vapiRequest("POST", createEndpoint, createPayload); - 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, @@ -397,7 +409,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, @@ -874,7 +891,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..6b491fb --- /dev/null +++ b/tests/assistant-folder.test.ts @@ -0,0 +1,169 @@ +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: { team: 'support', 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' } }; + await applyAssistant({ resourceId: 'support/tier2/intake', filePath: '', data }, state); + assert.equal(requests[0].method, 'POST'); + assert.deepEqual(requests[0].body.metadata, { team: 'support', folderPath: 'support/tier2' }); + assert.equal(readBaseline('folder-test', 'uuid'), hashPayload(data)); + requests.length = 0; + state.assistants.intake = { uuid: 'uuid' }; + await applyAssistant({ resourceId: 'intake', filePath: '', data }, state); + const patch = requests.find(r => r.method === 'PATCH' && r.body.name === 'Intake'); + assert.deepEqual(patch.body.metadata, { team: 'support', 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.md', '---\\nname: Intake\\nmetadata:\\n team: support\\n---\\n'); + globalThis.fetch = async () => new Response(JSON.stringify([ + { ...data, id: 'uuid', orgId: 'org', metadata: { team: 'support', folderPath: 'support' } }, + ])); + const pulled = await pullResourceType('assistants', state, { force: true }); + assert.equal(pulled.created + pulled.updated, 1); + const yaml = readFileSync('./resources/folder-test/assistants/intake.md', 'utf8'); + assert.ok(!yaml.includes('folderPath')); + assert.ok(yaml.includes('team: support')); + 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: "old" }, + }; + assert.deepEqual(withAssistantFolder(data, "support/tier2/intake"), { + name: "Intake", + metadata: { team: "support", folderPath: "support/tier2" }, + }); + assert.equal(data.metadata.folderPath, "old"); + assert.deepEqual(withAssistantFolder({}, "support/intake"), { + metadata: { folderPath: "support" }, + }); +}); + +test("moving to root explicitly clears a stale folder without losing metadata", () => { + assert.deepEqual( + withAssistantFolder( + { metadata: { team: "support", folderPath: "old" } }, + "intake", + ), + { + metadata: { team: "support", folderPath: null }, + }, + ); + assert.deepEqual(withAssistantFolder({}, "intake"), { + metadata: { folderPath: null }, + }); + assert.deepEqual(withAssistantFolder({ metadata: null }, "intake"), { + metadata: { 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/, + ); + } +}); + +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 }, + }; + const local = { name: "Intake", metadata: { team: "support" } }; + 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.folderPath, folderPath); + } + assert.deepEqual( + withoutAssistantFolder({ metadata: { folderPath: "support" } }), + {}, + ); + assert.deepEqual(withoutAssistantFolder({ metadata: {} }), {}); + assert.deepEqual(withoutAssistantFolder({ name: "Intake" }), { + name: "Intake", + }); +}); From dd69014f6b00ffb0870690201a17fd398ea357b6 Mon Sep 17 00:00:00 2001 From: dhruva Date: Sat, 21 Nov 2026 02:10:13 +0000 Subject: [PATCH 2/3] feat(push): namespace one-level assistant folder metadata Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 13 +++-- README.md | 9 ++-- docs/guides/commands.md | 12 +++-- src/assistant-folder.ts | 36 ++++++++++++-- tests/assistant-folder.test.ts | 88 +++++++++++++++++++++++++--------- 5 files changed, 122 insertions(+), 36 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e86d7bb..d69758a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -250,11 +250,16 @@ 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.folderPath` (for example -`assistants/support/intake.yml` → `support`). Other metadata keys are preserved. -Root assistants send `folderPath: null`, clearing stale grouping. Pull and drift -exclude this key; don't author it locally. File moves still require the normal +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. +Dashboard folders are one level deep: deeper paths use the first folder only, +with a warning on push (not an error). +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 diff --git a/README.md b/README.md index 7155746..1b856d3 100644 --- a/README.md +++ b/README.md @@ -183,9 +183,12 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec CI secrets. Credentials are referenced by name and bound to each org's own credentials. - **Assistant subfolders group the dashboard.** Pushing - `assistants/support/tier2/intake.yml` sets `metadata.folderPath` to - `support/tier2`, preserving other authored metadata. Root assistants send - `folderPath: null` to clear any previous folder. This derived key is omitted + `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. Dashboard folders + are one level deep: deeper paths also group under `support`, with a warning on + push. 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 diff --git a/docs/guides/commands.md b/docs/guides/commands.md index 64ea014..25ef675 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -98,9 +98,15 @@ adoption before dependency resolution to take one over instead. ## Interactive Mode Assistant pushes (including the push phase of `apply`) derive -`metadata.folderPath` from the file's subfolder under `assistants/`, preserving -other authored metadata. Root files send `folderPath: null` to clear grouping. -Pull omits this derived key, and drift comparisons ignore it. To move a file +`metadata.gitops.folderPath` from the first folder under `assistants/`, preserving +other authored metadata and sibling `gitops` keys: +`assistants/support/intake.yml` groups under `support`. +Dashboard folders are one level deep; deeper paths group under the first folder +and print a warning, not an error. 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. diff --git a/src/assistant-folder.ts b/src/assistant-folder.ts index 3a13321..2e612d9 100644 --- a/src/assistant-folder.ts +++ b/src/assistant-folder.ts @@ -1,3 +1,12 @@ +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 { @@ -5,9 +14,15 @@ export function withoutAssistantFolder( if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) { return data; } - const { folderPath: _, ...rest } = metadata as Record; + 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(rest).length > 0) result.metadata = rest; + if (Object.keys(remainingMetadata).length > 0) + result.metadata = remainingMetadata; else delete result.metadata; return result; } @@ -17,7 +32,7 @@ export function withAssistantFolder( resourceId: string, ): Record { const normalized = resourceId.replace(/\\/g, "/"); - const slash = normalized.lastIndexOf("/"); + const slash = normalized.indexOf("/"); const metadata = data.metadata; if ( metadata != null && @@ -25,11 +40,24 @@ export function withAssistantFolder( ) { 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"); + } + if (slash >= 0 && normalized.indexOf("/", slash + 1) >= 0) { + console.warn( + ` ⚠️ ${resourceId}: dashboard folders are one level deep; grouped under "${normalized.slice(0, slash)}".`, + ); + } return { ...data, metadata: { ...(metadata as Record | undefined), - folderPath: slash < 0 ? null : normalized.slice(0, slash), + gitops: { + ...(gitops as Record | undefined), + folderPath: slash < 0 ? null : normalized.slice(0, slash), + }, }, }; } diff --git a/tests/assistant-folder.test.ts b/tests/assistant-folder.test.ts index 13acd33..ca6962d 100644 --- a/tests/assistant-folder.test.ts +++ b/tests/assistant-folder.test.ts @@ -43,15 +43,15 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas 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: { team: 'support', folderPath: 'old' } })); + 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' } }; + 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, { team: 'support', folderPath: 'support/tier2' }); + assert.deepEqual(requests[0].body.metadata, { ...data.metadata, gitops: { owner: 'repo', folderPath: 'support' } }); assert.deepEqual(state.assistants['support/tier2/intake'], { uuid: 'uuid', origin: 'pushed' }); assert.equal(readBaseline('folder-test', 'uuid'), hashPayload(data)); requests.length = 0; @@ -67,21 +67,21 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas 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, { team: 'support', folderPath: null }); + 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.md', '---\\nname: Intake\\nmetadata:\\n team: support\\n---\\n'); + writeFileSync('./resources/folder-test/assistants/intake.yml', JSON.stringify(data)); globalThis.fetch = async () => new Response(JSON.stringify([ - { ...data, id: 'uuid', orgId: 'org', metadata: { team: 'support', folderPath: 'support' } }, + { ...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 yaml = readFileSync('./resources/folder-test/assistants/intake.md', 'utf8'); - assert.ok(!yaml.includes('folderPath')); - assert.ok(yaml.includes('team: support')); + 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( @@ -95,6 +95,13 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas }, ); assert.equal(result.status, 0, result.stdout + result.stderr); + assert.equal( + result.stderr.split( + 'dashboard folders are one level deep; grouped under "support".', + ).length - 1, + 1, + result.stderr, + ); } finally { rmSync(dir, { recursive: true, force: true }); } @@ -103,33 +110,41 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas test("folder payloads preserve user metadata and override derived values", () => { const data = { name: "Intake", - metadata: { team: "support", folderPath: "old" }, + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath: "old" }, + }, }; assert.deepEqual(withAssistantFolder(data, "support/tier2/intake"), { name: "Intake", - metadata: { team: "support", folderPath: "support/tier2" }, + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath: "support" }, + }, }); - assert.equal(data.metadata.folderPath, "old"); + assert.equal(data.metadata.gitops.folderPath, "old"); assert.deepEqual(withAssistantFolder({}, "support/intake"), { - metadata: { folderPath: "support" }, + metadata: { gitops: { folderPath: "support" } }, }); }); test("moving to root explicitly clears a stale folder without losing metadata", () => { assert.deepEqual( withAssistantFolder( - { metadata: { team: "support", folderPath: "old" } }, + { metadata: { team: "support", gitops: { folderPath: "old" } } }, "intake", ), { - metadata: { team: "support", folderPath: null }, + metadata: { team: "support", gitops: { folderPath: null } }, }, ); assert.deepEqual(withAssistantFolder({}, "intake"), { - metadata: { folderPath: null }, + metadata: { gitops: { folderPath: null } }, }); assert.deepEqual(withAssistantFolder({ metadata: null }, "intake"), { - metadata: { folderPath: null }, + metadata: { gitops: { folderPath: null } }, }); }); @@ -140,6 +155,18 @@ test("invalid assistant metadata is rejected instead of silently overwritten", ( /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", () => { @@ -148,9 +175,20 @@ test("pull and drift canonical forms ignore only assistant folder metadata", () id: "uuid", orgId: "org", name: "Intake", - metadata: { team: "support", folderPath }, + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo", folderPath }, + }, + }; + const local = { + name: "Intake", + metadata: { + team: "support", + folderPath: "user", + gitops: { owner: "repo" }, + }, }; - const local = { name: "Intake", metadata: { team: "support" } }; const canonical = canonicalizeForHash( remote, state, @@ -166,13 +204,19 @@ test("pull and drift canonical forms ignore only assistant folder metadata", () canonicalizeForHash(remote, state, new Map(), "squads").metadata, remote.metadata, ); - assert.equal(remote.metadata.folderPath, folderPath); + assert.equal(remote.metadata.gitops.folderPath, folderPath); } assert.deepEqual( - withoutAssistantFolder({ metadata: { folderPath: "support" } }), + withoutAssistantFolder({ metadata: { gitops: { folderPath: "support" } } }), {}, ); - assert.deepEqual(withoutAssistantFolder({ metadata: {} }), {}); + assert.deepEqual(withoutAssistantFolder({ metadata: { gitops: {} } }), {}); + assert.deepEqual( + withoutAssistantFolder({ + metadata: { folderPath: "user", gitops: { folderPath: "support" } }, + }), + { metadata: { folderPath: "user" } }, + ); assert.deepEqual(withoutAssistantFolder({ name: "Intake" }), { name: "Intake", }); From 0f418527d0ba339f92730156ee4bb1f56ceee430 Mon Sep 17 00:00:00 2001 From: dhruva Date: Sat, 21 Nov 2026 02:13:40 +0000 Subject: [PATCH 3/3] fix(push): preserve full assistant subfolder paths Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- AGENTS.md | 4 ++-- README.md | 8 ++++---- docs/guides/commands.md | 6 +++--- src/assistant-folder.ts | 7 +------ tests/assistant-folder.test.ts | 11 ++--------- 5 files changed, 12 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d69758a..f8def70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -253,8 +253,8 @@ 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. -Dashboard folders are one level deep: deeper paths use the first folder only, -with a warning on push (not an error). +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. diff --git a/README.md b/README.md index 1b856d3..6e928eb 100644 --- a/README.md +++ b/README.md @@ -185,10 +185,10 @@ To test every pull request automatically, set up [PR checks](docs/guides/pr-chec - **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. Dashboard folders - are one level deep: deeper paths also group under `support`, with a warning on - push. Root assistants send `metadata.gitops.folderPath: null` to clear any - previous folder. This derived key is omitted + 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 diff --git a/docs/guides/commands.md b/docs/guides/commands.md index 25ef675..f38a988 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -98,11 +98,11 @@ 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 first folder under `assistants/`, preserving +`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`. -Dashboard folders are one level deep; deeper paths group under the first folder -and print a warning, not an error. Root files send +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 diff --git a/src/assistant-folder.ts b/src/assistant-folder.ts index 2e612d9..a0af731 100644 --- a/src/assistant-folder.ts +++ b/src/assistant-folder.ts @@ -32,7 +32,7 @@ export function withAssistantFolder( resourceId: string, ): Record { const normalized = resourceId.replace(/\\/g, "/"); - const slash = normalized.indexOf("/"); + const slash = normalized.lastIndexOf("/"); const metadata = data.metadata; if ( metadata != null && @@ -45,11 +45,6 @@ export function withAssistantFolder( if (metadata && Object.hasOwn(metadata, "gitops") && !isPlainObject(gitops)) { throw new Error("Assistant metadata.gitops must be a plain object"); } - if (slash >= 0 && normalized.indexOf("/", slash + 1) >= 0) { - console.warn( - ` ⚠️ ${resourceId}: dashboard folders are one level deep; grouped under "${normalized.slice(0, slash)}".`, - ); - } return { ...data, metadata: { diff --git a/tests/assistant-folder.test.ts b/tests/assistant-folder.test.ts index ca6962d..618fd21 100644 --- a/tests/assistant-folder.test.ts +++ b/tests/assistant-folder.test.ts @@ -51,7 +51,7 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas 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' } }); + 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; @@ -95,13 +95,6 @@ test("assistant POST/PATCH and response baselines share the folder-free hash bas }, ); assert.equal(result.status, 0, result.stdout + result.stderr); - assert.equal( - result.stderr.split( - 'dashboard folders are one level deep; grouped under "support".', - ).length - 1, - 1, - result.stderr, - ); } finally { rmSync(dir, { recursive: true, force: true }); } @@ -121,7 +114,7 @@ test("folder payloads preserve user metadata and override derived values", () => metadata: { team: "support", folderPath: "user", - gitops: { owner: "repo", folderPath: "support" }, + gitops: { owner: "repo", folderPath: "support/tier2" }, }, }); assert.equal(data.metadata.gitops.folderPath, "old");