feat: enhance pull functionality with force options and local change detection

- Added new commands `pull:dev:force` and `pull:prod:force` to allow users to overwrite local changes with platform state.
- Updated the README to reflect the new pull commands and their behavior, including descriptions for preserving or overwriting local changes.
- Implemented logic in the pull process to detect locally changed files and skip them during pulls unless forced, improving user control over resource management.

Author: vtkovapi

README.md

@@ -62,8 +62,10 @@ echo "VAPI_TOKEN=your-token-here" > .env.dev
 | Command | Description |
 |---------|-------------|
 | `npm run build` | Type-check the codebase |
-| `npm run pull:dev` | Pull platform state, merge with local changes |
-| `npm run pull:prod` | Pull from prod, merge with local changes |
+| `npm run pull:dev` | Pull platform state, preserve local changes |
+| `npm run pull:dev:force` | Pull platform state, overwrite everything |
+| `npm run pull:prod` | Pull from prod, preserve local changes |
+| `npm run pull:prod:force` | Pull from prod, overwrite everything |
 | `npm run push:dev` | Push local files to Vapi (dev) |
 | `npm run push:prod` | Push local files to Vapi (prod) |
 | `npm run apply:dev` | Pull → Merge → Push in one shot (dev) |
@@ -76,50 +78,51 @@ echo "VAPI_TOKEN=your-token-here" > .env.dev
 ### Basic Workflow
 
 ```bash
-# First time: pull existing resources from Vapi
-npm run pull:dev
+# First time: pull all resources from Vapi
+npm run pull:dev:force
 
 # Commit the initial state
 git add . && git commit -m "initial pull"
 
 # Make changes to YAML/MD files...
 
-# Safe sync: pull latest platform changes, merge, push
-npm run apply:dev
+# Push changes to Vapi
+npm run push:dev
 ```
 
-#### Pull → Edit → Push (manual two-step)
+#### Pulling Without Losing Local Work
 
-If you want more control over each step:
+By default, `pull` preserves any files you've locally modified or deleted:
 
 ```bash
-# Pull platform state (auto-merges with your local changes via git stash/pop)
-npm run pull:dev
+# Edit an assistant locally...
 
-# Review the merged result, make further edits...
-
-# Push to platform
-npm run push:dev
+npm run pull:dev
+# ⏭️  my-assistant (locally changed, skipping)
+# ✨  new-tool -> resources/tools/new-tool.yml
+# Your edits are preserved, new platform resources are downloaded
 ```
 
-#### Handling Merge Conflicts
+#### Force Pull (Platform as Source of Truth)
 
-If platform changes conflict with your local edits, `pull` will leave standard git conflict markers in the affected files and exit:
+When you want the platform version of everything, overwriting all local files:
 
 ```bash
-npm run pull:dev
-# ⚠️  Merge conflicts detected!
+npm run pull:dev:force
+# ⚡ Force mode: overwriting all local files with platform state
+```
 
-# See which files have conflicts
-git diff --name-only --diff-filter=U
+#### Reviewing Platform Changes
 
-# Edit files to resolve conflicts (remove <<<< ==== >>>> markers)
+```bash
+# Pull platform state (your local changes are preserved)
+npm run pull:dev
 
-# Push resolved state
-npm run push:dev
+# See what changed on the platform vs your last commit
+git diff
 
-# Clean up the stash
-git stash drop
+# Accept platform changes for a specific file
+git checkout -- resources/tools/some-tool.yml
 ```
 
 ### Selective Push (Partial Sync)
@@ -471,30 +474,24 @@ model:
 
 ### Sync Workflow
 
-The engine uses git's merge capabilities to safely combine local and platform changes:
+Your local files are the source of truth. The engine respects that:
 
 ```
-┌─────────┐     ┌──────────┐     ┌──────────┐
-│  pull    │ ──▸ │  merge   │ ──▸ │  push    │
-│ platform │     │ (git     │     │ to       │
-│ state    │     │  stash/  │     │ platform │
-│          │     │  pop)    │     │          │
-└─────────┘     └──────────┘     └──────────┘
+pull (default)     pull --force        push
+─────────────      ─────────────       ─────────────
+Download from      Download from       Upload local
+platform, skip     platform, overwrite files to
+locally changed    everything          platform
+files
 ```
 
-**`pull`** does the heavy lifting:
-1. Detects local uncommitted changes → `git stash`
-2. Downloads fresh platform state (overwrites resource files)
-3. Reapplies local changes on top → `git stash pop`
-4. Git's three-way merge reconciles both sets of changes
-5. If conflicts: leaves standard `<<<<<<<` markers, exits for manual resolution
-6. If clean: working tree has merged files ready to push
+**`pull`** downloads platform state. In default mode (git repo required), it detects locally modified or deleted files and skips them — your local work is preserved. New platform resources are still downloaded. Use `--force` to overwrite everything.
 
-**`push`** is the engine — reads local files and syncs them to the platform.
+**`push`** is the engine — reads local files and syncs them to the platform. Deleted files are removed from the platform.
 
-**`apply`** is the convenience wrapper — runs `pull` then `push` in sequence. Stops if pull has conflicts.
+**`apply`** is the convenience wrapper — runs `pull` then `push` in sequence.
 
-> **Note:** `pull` requires a git repo with at least one commit. Without git, it falls back to a simple overwrite (no merge support).
+> **Note:** The "skip locally changed files" feature requires a git repo with at least one commit. Without git, pull always overwrites (same as `--force`).
 
 ### Processing Order
 

package.json

@@ -12,7 +12,9 @@
     "push:dev:force": "tsx src/push.ts dev --force",
     "push:prod:force": "tsx src/push.ts prod --force",
     "pull:dev": "tsx src/pull.ts dev",
+    "pull:dev:force": "tsx src/pull.ts dev --force",
     "pull:prod": "tsx src/pull.ts prod",
+    "pull:prod:force": "tsx src/pull.ts prod --force",
     "call:dev": "tsx src/call.ts dev",
     "call:prod": "tsx src/call.ts prod",
     "cleanup:dev": "tsx src/cleanup.ts dev",

src/pull.ts

@@ -54,7 +54,7 @@ const FOLDER_MAP: Record<ResourceType, string> = {
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Git Helpers (merge support — stash local changes before pull, reapply after)
+// Git Helpers (detect locally changed files to skip during pull)
 // ─────────────────────────────────────────────────────────────────────────────
 
 function gitCmd(args: string): string {
@@ -73,8 +73,22 @@ function gitHasCommits(): boolean {
   try { gitCmd("rev-parse HEAD"); return true; } catch { return false; }
 }
 
-function gitHasChanges(): boolean {
-  return gitCmd("status --porcelain").length > 0;
+// Returns relative paths of all locally modified, deleted, or untracked files
+function getLocallyChangedFiles(): Set<string> {
+  const status = gitCmd("status --porcelain");
+  const files = new Set<string>();
+  for (const line of status.split("\n")) {
+    if (!line.trim()) continue;
+    // format: XY filename  (or XY "filename" for special chars)
+    let filePath = line.slice(3);
+    // Handle renames: "old -> new"
+    const arrowIdx = filePath.indexOf(" -> ");
+    if (arrowIdx !== -1) filePath = filePath.slice(arrowIdx + 4);
+    // Strip quotes if present
+    filePath = filePath.replace(/^"|"$/g, "").trim();
+    files.add(filePath);
+  }
+  return files;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -373,19 +387,21 @@ async function writeResourceFile(
 export interface PullStats {
   created: number;
   updated: number;
+  skipped: number;
 }
 
 export async function pullResourceType(
   resourceType: ResourceType,
-  state: StateFile
+  state: StateFile,
+  changedFiles?: Set<string>,
 ): Promise<PullStats> {
   console.log(`\n📥 Pulling ${resourceType}...`);
 
   const resources = await fetchAllResources(resourceType) ?? [];
 
   if (!Array.isArray(resources)) {
     console.log(`   ⚠️  No ${resourceType} found (API returned non-array)`);
-    return { created: 0, updated: 0 };
+    return { created: 0, updated: 0, skipped: 0 };
   }
 
   console.log(`   Found ${resources.length} ${resourceType} in Vapi`);
@@ -396,6 +412,7 @@ export async function pullResourceType(
 
   let created = 0;
   let updated = 0;
+  let skipped = 0;
 
   for (const resource of resources) {
     // Check if we already have this resource in state (by UUID)
@@ -406,9 +423,19 @@ export async function pullResourceType(
       // Generate new resource ID
       resourceId = generateResourceId(resource, existingIds);
       existingIds.add(resourceId);
-      created++;
-    } else {
-      updated++;
+    }
+
+    // Skip files that have been locally modified or deleted (default mode)
+    if (changedFiles) {
+      const folderPath = FOLDER_MAP[resourceType];
+      const mdPath = join("resources", folderPath, `${resourceId}.md`);
+      const ymlPath = join("resources", folderPath, `${resourceId}.yml`);
+      if (changedFiles.has(mdPath) || changedFiles.has(ymlPath)) {
+        console.log(`   ⏭️  ${resourceId} (locally changed, skipping)`);
+        newStateSection[resourceId] = resource.id;
+        skipped++;
+        continue;
+      }
     }
 
     // Detect platform defaults (orgId is null/missing — read-only, immutable)
@@ -429,95 +456,92 @@ export async function pullResourceType(
     const relPath = relative(BASE_DIR, filePath);
     console.log(`   ${icon} ${resourceId} -> ${relPath}${isPlatformDefault ? " (platform default, read-only)" : ""}`);
 
+    if (isNew) created++;
+    else updated++;
+
     // Update state
     newStateSection[resourceId] = resource.id;
   }
 
   // Update state with new mappings
   state[resourceType] = newStateSection;
 
-  return { created, updated };
+  return { created, updated, skipped };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Main Pull Engine
 // ─────────────────────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
+  const force = process.argv.includes("--force");
+
   console.log("═══════════════════════════════════════════════════════════════");
-  console.log(`🔄 Vapi GitOps Pull - Environment: ${VAPI_ENV}`);
+  console.log(`🔄 Vapi GitOps Pull - Environment: ${VAPI_ENV}${force ? " (force)" : ""}`);
   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();
+  // Default mode: skip locally changed files (local is source of truth)
+  // Force mode: overwrite everything (platform is source of truth)
+  let changedFiles: Set<string> | undefined;
+  const gitEnabled = !force && isGitRepo() && gitHasCommits();
 
-  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");
+  if (gitEnabled) {
+    changedFiles = getLocallyChangedFiles();
+    // Only keep resource files — non-resource changes don't matter
+    for (const f of changedFiles) {
+      if (!f.startsWith("resources/")) changedFiles.delete(f);
+    }
+    if (changedFiles.size > 0) {
+      console.log(`\n📦 ${changedFiles.size} locally changed file(s) will be preserved`);
+      console.log("   Use --force to overwrite all local files with platform state");
+    }
+  } else if (force) {
+    console.log("\n⚡ Force mode: overwriting all local files with platform state");
   }
 
   const state = loadState();
 
+  const zero: PullStats = { created: 0, updated: 0, skipped: 0 };
   const stats: Record<string, PullStats> = {
-    tools: { created: 0, updated: 0 },
-    structuredOutputs: { created: 0, updated: 0 },
-    assistants: { created: 0, updated: 0 },
-    squads: { created: 0, updated: 0 },
-    personalities: { created: 0, updated: 0 },
-    scenarios: { created: 0, updated: 0 },
-    simulations: { created: 0, updated: 0 },
-    simulationSuites: { created: 0, updated: 0 },
+    tools: { ...zero },
+    structuredOutputs: { ...zero },
+    assistants: { ...zero },
+    squads: { ...zero },
+    personalities: { ...zero },
+    scenarios: { ...zero },
+    simulations: { ...zero },
+    simulationSuites: { ...zero },
   };
 
   // Pull in dependency order
-  stats.tools = await pullResourceType("tools", state);
-  stats.structuredOutputs = await pullResourceType("structuredOutputs", state);
-  stats.assistants = await pullResourceType("assistants", state);
-  stats.squads = await pullResourceType("squads", state);
-  stats.personalities = await pullResourceType("personalities", state);
-  stats.scenarios = await pullResourceType("scenarios", state);
-  stats.simulations = await pullResourceType("simulations", state);
-  stats.simulationSuites = await pullResourceType("simulationSuites", 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;
-    }
-  }
+  stats.tools = await pullResourceType("tools", state, changedFiles);
+  stats.structuredOutputs = await pullResourceType("structuredOutputs", state, changedFiles);
+  stats.assistants = await pullResourceType("assistants", state, changedFiles);
+  stats.squads = await pullResourceType("squads", state, changedFiles);
+  stats.personalities = await pullResourceType("personalities", state, changedFiles);
+  stats.scenarios = await pullResourceType("scenarios", state, changedFiles);
+  stats.simulations = await pullResourceType("simulations", state, changedFiles);
+  stats.simulationSuites = await pullResourceType("simulationSuites", state, changedFiles);
 
-  // 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
+  const totalSkipped = Object.values(stats).reduce((sum, s) => sum + s.skipped, 0);
   console.log("\n═══════════════════════════════════════════════════════════════");
   console.log("✅ Pull complete!");
   console.log("═══════════════════════════════════════════════════════════════\n");
 
   console.log("📋 Summary:");
-  for (const [type, { created, updated }] of Object.entries(stats)) {
-    console.log(`   ${type}: ${created} new, ${updated} existing`);
+  for (const [type, { created, updated, skipped }] of Object.entries(stats)) {
+    const parts = [`${created} new`, `${updated} updated`];
+    if (skipped > 0) parts.push(`${skipped} skipped`);
+    console.log(`   ${type}: ${parts.join(", ")}`);
+  }
+
+  if (totalSkipped > 0) {
+    console.log(`\n   ℹ️  ${totalSkipped} file(s) preserved (locally changed)`);
+    console.log("   Run with --force to overwrite: npm run pull:dev:force");
   }
 }