feat: add Git merge support for local changes during pull

- Implemented functionality to stash local changes before pulling platform state and reapply them afterward.
- Added utility functions to check if the current directory is a Git repository and to determine the presence of local changes.
- Enhanced logging to inform users about the stashing and merging process, including conflict resolution guidance.
- Updated comments for clarity on the new Git integration within the resource pulling workflow.

Author: vtkovapi

src/pull.ts

@@ -1,7 +1,8 @@
+import { execSync } from "child_process";
 import { mkdir, writeFile } from "fs/promises";
 import { join, dirname } from "path";
 import { stringify } from "yaml";
-import { VAPI_ENV, VAPI_BASE_URL, VAPI_TOKEN, RESOURCES_DIR } from "./config.ts";
+import { VAPI_ENV, VAPI_BASE_URL, VAPI_TOKEN, RESOURCES_DIR, BASE_DIR } from "./config.ts";
 import { loadState, saveState } from "./state.ts";
 import type { StateFile, ResourceType } from "./types.ts";
 
@@ -28,10 +29,6 @@ const EXCLUDED_FIELDS = [
   "workflowIds",           // Server-managed: workflows are a separate resource type
 ];
 
-// ─────────────────────────────────────────────────────────────────────────────
-// API Functions
-// ─────────────────────────────────────────────────────────────────────────────
-
 // Map resource types to their API endpoints
 const ENDPOINT_MAP: Record<ResourceType, string> = {
   tools: "/tool",
@@ -56,6 +53,34 @@ const FOLDER_MAP: Record<ResourceType, string> = {
   simulationSuites: "simulations/suites",
 };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Git Helpers (merge support — stash local changes before pull, reapply after)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function gitCmd(args: string): string {
+  return execSync(`git ${args}`, {
+    cwd: BASE_DIR,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+function isGitRepo(): boolean {
+  try { gitCmd("rev-parse --is-inside-work-tree"); return true; } catch { return false; }
+}
+
+function gitHasCommits(): boolean {
+  try { gitCmd("rev-parse HEAD"); return true; } catch { return false; }
+}
+
+function gitHasChanges(): boolean {
+  return gitCmd("status --porcelain").length > 0;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
 export async function fetchAllResources(resourceType: ResourceType): Promise<VapiResource[]> {
   const endpoint = ENDPOINT_MAP[resourceType];
   const url = `${VAPI_BASE_URL}${endpoint}`;
@@ -406,6 +431,18 @@ async function main(): Promise<void> {
   console.log(`   API: ${VAPI_BASE_URL}`);
   console.log("═══════════════════════════════════════════════════════════════");
 
+  // Git merge support: stash local changes before overwriting with platform state
+  const gitEnabled = isGitRepo() && gitHasCommits();
+  const hadLocalChanges = gitEnabled && gitHasChanges();
+
+  if (hadLocalChanges) {
+    console.log("\n📦 Stashing local changes before pull...");
+    gitCmd('stash push -m "gitops: stash before pull"');
+    console.log("   ✅ Local changes stashed\n");
+  } else if (gitEnabled) {
+    console.log("\n📦 No local changes to stash\n");
+  }
+
   const state = loadState();
 
   const stats: Record<string, PullStats> = {
@@ -419,14 +456,7 @@ async function main(): Promise<void> {
     simulationSuites: { created: 0, updated: 0 },
   };
 
-  // Pull in dependency order:
-  // 1. Base resources (tools, structuredOutputs)
-  // 2. Assistants (references tools, structuredOutputs)
-  // 3. Squads (references assistants)
-  // 4. Simulation building blocks (personalities, scenarios - no cross-dependencies)
-  // 5. Simulations (references personalities, scenarios)
-  // 6. Simulation suites (references simulations)
-  
+  // Pull in dependency order
   stats.tools = await pullResourceType("tools", state);
   stats.structuredOutputs = await pullResourceType("structuredOutputs", state);
   stats.assistants = await pullResourceType("assistants", state);
@@ -436,9 +466,32 @@ async function main(): Promise<void> {
   stats.simulations = await pullResourceType("simulations", state);
   stats.simulationSuites = await pullResourceType("simulationSuites", state);
 
-  // Save updated state
+  // Reapply local changes on top of pulled platform state
+  let hasConflicts = false;
+  if (hadLocalChanges) {
+    console.log("\n📦 Reapplying local changes...");
+    try {
+      gitCmd("stash pop");
+      console.log("   ✅ Local changes merged cleanly\n");
+    } catch {
+      hasConflicts = true;
+    }
+  }
+
+  // Always save state last — overwrites any stash-induced changes to the state file
   await saveState(state);
 
+  if (hasConflicts) {
+    console.error("\n⚠️  Merge conflicts detected!");
+    console.error("   Platform changes conflict with your local changes.\n");
+    console.error("   To see conflicted files:");
+    console.error("     git diff --name-only --diff-filter=U\n");
+    console.error("   After resolving conflicts:");
+    console.error(`     npm run push:${VAPI_ENV}    # push to platform`);
+    console.error("     git stash drop              # clean up the stash\n");
+    process.exit(1);
+  }
+
   // Summary
   console.log("\n═══════════════════════════════════════════════════════════════");
   console.log("✅ Pull complete!");