refactor: enhance error handling and improve command usage messages

- Updated error handling in audio context and microphone initialization to provide more specific warnings based on the encountered issues.
- Modified command usage messages across various scripts to standardize the format and improve clarity, ensuring users understand the correct syntax for commands.
- Added support for new resource types in interactive prompts and improved the handling of locally modified files during resource pulls.
- Introduced a new grouping mechanism in the searchable checkbox for better organization of choices in interactive prompts.

Author: vtkovapi

src/call.ts

@@ -3,8 +3,11 @@ import { join, dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { execSync } from "child_process";
 import * as readline from "readline";
+import { createRequire } from "module";
 import type { Environment, StateFile } from "./types.ts";
 
+const require = createRequire(import.meta.url);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Configuration
 // ─────────────────────────────────────────────────────────────────────────────
@@ -205,7 +208,7 @@ async function checkMicrophonePermission(): Promise<boolean> {
         "   If prompted, please grant microphone permission in System Preferences.",
       );
       console.log(
-        "   System Preferences > Security & Privacy > Privacy > Microphone\n",
+        "   System Settings > Privacy & Security > Microphone\n",
       );
 
       // Ask user to continue anyway
@@ -269,7 +272,7 @@ function loadState(env: Environment): StateFile {
   if (!existsSync(stateFilePath)) {
     console.error(`❌ State file not found: .vapi-state.${env}.json`);
     console.error(
-      "   Run 'npm run apply:" + env + "' first to create resources",
+      "   Run 'npm run apply -- " + env + "' first to create resources",
     );
     process.exit(1);
   }
@@ -468,11 +471,21 @@ async function connectWebSocket(
       }
     };
 
-    ws.onmessage = (event) => {
-      if (event.data instanceof Buffer || event.data instanceof ArrayBuffer) {
-        // Binary audio data from assistant
+    ws.onmessage = async (event) => {
+      const data = event.data;
+      // Binary audio data from assistant
+      if (data instanceof Buffer || data instanceof ArrayBuffer) {
+        if (audioContext) {
+          audioContext.playAudio(data);
+        }
+      } else if (typeof Blob !== "undefined" && data instanceof Blob) {
+        if (audioContext) {
+          const arrayBuffer = await data.arrayBuffer();
+          audioContext.playAudio(arrayBuffer);
+        }
+      } else if (ArrayBuffer.isView(data)) {
         if (audioContext) {
-          audioContext.playAudio(event.data);
+          audioContext.playAudio(data.buffer as ArrayBuffer);
         }
       } else {
         // Control message (JSON)
@@ -539,7 +552,20 @@ function handleControlMessage(
     }
     case "call-ended": {
       const cm = message as CallEndedMessage;
-      console.log(`\n📞 Call ended: ${cm.reason || "unknown reason"}`);
+      const reasonLabels: Record<string, string> = {
+        "silence-timed-out": "Silence timeout (no speech detected)",
+        "assistant-ended-call": "Assistant ended the call",
+        "customer-ended-call": "Customer ended the call",
+        "max-duration-reached": "Maximum call duration reached",
+        "assistant-error": "Assistant error",
+        "pipeline-error": "Pipeline error",
+        "voicemail-reached": "Voicemail detected",
+        "customer-did-not-answer": "No answer",
+        "assistant-request-returned-error": "Assistant request error",
+        "assistant-not-found": "Assistant not found",
+      };
+      const label = cm.reason ? (reasonLabels[cm.reason] ?? cm.reason) : "unknown reason";
+      console.log(`\n📞 Call ended: ${label}`);
       break;
     }
     default:
@@ -584,23 +610,27 @@ function createAudioContext(): {
   playAudio: (data: Buffer | ArrayBuffer) => void;
   close: () => void;
 } {
-  // Lazy load speaker module
   let Speaker: SpeakerConstructor | null = null;
   let speakerInstance: SpeakerInstance | null = null;
 
   try {
-    // Dynamic import for optional dependency
     Speaker = require("speaker") as SpeakerConstructor;
     speakerInstance = new Speaker!({
       channels: 1,
       bitDepth: 16,
       sampleRate: 16000,
     });
-  } catch {
-    console.warn(
-      "⚠️  'speaker' module not installed. Audio playback disabled.",
-    );
-    console.warn("   Install with: npm install speaker");
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("Cannot find module")) {
+      console.warn("⚠️  'speaker' module not installed. Audio playback disabled.");
+      console.warn("   Install with: npm install speaker");
+    } else if (msg.includes("Could not locate the bindings file") || msg.includes("NODE_MODULE_VERSION")) {
+      console.warn("⚠️  'speaker' native bindings not built for this Node version.");
+      console.warn("   Rebuild with: npm rebuild speaker");
+    } else {
+      console.warn(`⚠️  Could not initialize speaker: ${msg}`);
+    }
   }
 
   return {
@@ -647,9 +677,16 @@ function createMicrophoneStream(onData: (data: Buffer) => void): {
 
     micInstance!.start();
   } catch (error) {
-    console.warn("⚠️  'mic' module not installed or microphone unavailable.");
-    console.warn("   Install with: npm install mic");
-    console.warn("   Error:", error);
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("Cannot find module")) {
+      console.warn("⚠️  'mic' module not installed. Microphone input disabled.");
+      console.warn("   Install with: npm install mic");
+    } else if (msg.includes("sox") || msg.includes("rec")) {
+      console.warn("⚠️  sox/rec not found. Required for microphone input.");
+      console.warn("   Install with: brew install sox (macOS) or apt install sox (Linux)");
+    } else {
+      console.warn(`⚠️  Could not initialize microphone: ${msg}`);
+    }
   }
 
   return {

src/cleanup.ts

@@ -203,7 +203,7 @@ async function main(): Promise<void> {
     );
     console.log("🔒 DRY-RUN MODE - No resources were deleted");
     console.log("   To actually delete, run:");
-    console.log(`   npm run cleanup:${VAPI_ENV} -- --force`);
+    console.log(`   npm run cleanup -- ${VAPI_ENV} --force`);
     console.log(
       "═══════════════════════════════════════════════════════════════\n",
     );

src/config.ts

@@ -39,7 +39,7 @@ function parseEnvironment(): Environment {
 
   if (!envArg) {
     console.error("❌ Environment / org name argument is required");
-    console.error("   Usage: npm run push <org>  |  npm run push:dev");
+    console.error("   Usage: npm run push -- <org>");
     console.error("   Flags: --force (enable deletions)");
     console.error(
       "          --type <type> (apply only specific resource type, repeatable)",

src/delete.ts

@@ -220,7 +220,7 @@ export async function deleteOrphanedResources(
     }
     console.log("  ℹ️  These resources exist in Vapi but not in your local files.");
     console.log("  ℹ️  To delete them, run with --force flag:");
-    console.log("     npm run apply:dev:force\n");
+    console.log("     npm run push -- <org> --force\n");
     return;
   }
 

src/eval.ts

@@ -38,7 +38,7 @@ function printUsage(): void {
   console.error("       tsx src/eval.ts <env> -a <assistant-name> [options]");
   console.error("");
   console.error("Runs Vapi Evals (mock conversation tests) against a transient or stored assistant/squad.");
-  console.error("Evals must be pushed first (npm run push:dev evals). Assistants/squads can be transient.");
+  console.error("Evals must be pushed first (npm run push -- <org> evals). Assistants/squads can be transient.");
   console.error("");
   console.error("Options:");
   console.error("  -s <name>         Target squad (by resource filename, loaded as transient)");
@@ -135,7 +135,7 @@ function loadState(env: Environment): StateFile {
   const stateFile = join(BASE_DIR, `.vapi-state.${env}.json`);
   if (!existsSync(stateFile)) {
     console.error(`❌ State file not found: .vapi-state.${env}.json`);
-    console.error("   Run 'npm run push:dev evals' first to create eval resources");
+    console.error("   Run 'npm run push -- <org> evals' first to create eval resources");
     process.exit(1);
   }
   const content = readFileSync(stateFile, "utf-8");
@@ -494,7 +494,7 @@ async function main(): Promise<void> {
   const evals = loadEvals(state, config.evalFilter);
   if (evals.length === 0) {
     console.error("❌ No evals found in state" + (config.evalFilter ? ` matching "${config.evalFilter}"` : ""));
-    console.error("   Push evals first: npm run push:dev evals");
+    console.error("   Push evals first: npm run push -- <org> evals");
     console.error("   Eval files go in: resources/evals/");
     process.exit(1);
   }

src/interactive.ts

@@ -61,6 +61,12 @@ const RESOURCE_TYPES: ResourceTypeDef[] = [
     endpoint: "/eval/simulation/suite",
     folder: "simulations/suites",
   },
+  {
+    key: "evals",
+    label: "Evals",
+    endpoint: "/eval",
+    folder: "evals",
+  },
 ];
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -485,6 +491,7 @@ export async function runInteractivePull(): Promise<void> {
 
         console.log(c.dim("  Fetching remote resources...\n"));
 
+        let fetchFailed = false;
         snapshots = await Promise.all(
           RESOURCE_TYPES.map(
             async (type): Promise<ResourceSnapshot> => {
@@ -495,13 +502,24 @@ export async function runInteractivePull(): Promise<void> {
                   label: type.label,
                   resources: normaliseList(data),
                 };
-              } catch {
+              } catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                if (msg.includes("401") || msg.includes("403") || msg.includes("authentication") || msg.includes("unauthorized")) {
+                  fetchFailed = true;
+                }
+                console.log(c.red(`  ✗ Failed to fetch ${type.label}: ${msg}`));
                 return { key: type.key, label: type.label, resources: [] };
               }
             },
           ),
         );
 
+        if (fetchFailed) {
+          console.log(c.red("\n  ⚠ API authentication failed. Check your VAPI_TOKEN in .env." + slug));
+          console.log(c.red("  Run \"npm run setup\" to reconfigure.\n"));
+          return;
+        }
+
         nonEmpty = snapshots.filter((s) => s.resources.length > 0);
         totalCount = nonEmpty.reduce(
           (n, s) => n + s.resources.length,
@@ -981,24 +999,17 @@ export async function runInteractiveCleanup(): Promise<void> {
     ),
   );
 
-  const dryFirst = await confirm({
-    message: "Run dry-run first to preview what would be deleted?",
-    default: true,
-  });
-
-  if (dryFirst) {
-    console.log(c.dim("\n  Running dry-run...\n"));
-    spawnScript(["src/cleanup.ts", slug]);
+  console.log(c.dim("\n  Running dry-run preview...\n"));
+  spawnScript(["src/cleanup.ts", slug]);
 
-    const proceed = await confirm({
-      message: "Proceed with actual deletion?",
-      default: false,
-    });
+  const proceed = await confirm({
+    message: "Proceed with actual deletion?",
+    default: false,
+  });
 
-    if (!proceed) {
-      console.log(c.dim("\n  Cancelled.\n"));
-      return;
-    }
+  if (!proceed) {
+    console.log(c.dim("\n  Cancelled.\n"));
+    return;
   }
 
   console.log(c.dim("\n  Running cleanup with --force...\n"));

src/pull.ts

@@ -1,5 +1,5 @@
 import { execSync } from "child_process";
-import { existsSync, readdirSync } from "fs";
+import { existsSync, readdirSync, statSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { join, dirname, relative, resolve } from "path";
 import { fileURLToPath } from "url";
@@ -686,8 +686,30 @@ export async function pullResourceType(
       }
     }
 
+    // Skip locally edited files even without git (mtime-based detection)
+    // If the resource file is newer than the state file, it was locally modified
+    if (!bootstrap && !force && !isNew && !changedFiles) {
+      const folderPath = FOLDER_MAP[resourceType];
+      const dir = join(RESOURCES_DIR, folderPath);
+      const localFile =
+        [join(dir, `${resourceId}.md`), join(dir, `${resourceId}.yml`), join(dir, `${resourceId}.yaml`)]
+          .find((p) => existsSync(p));
+      if (localFile) {
+        const stateFilePath = join(BASE_DIR, `.vapi-state.${VAPI_ENV}.json`);
+        if (existsSync(stateFilePath)) {
+          const localMtime = statSync(localFile).mtimeMs;
+          const stateMtime = statSync(stateFilePath).mtimeMs;
+          if (localMtime > stateMtime) {
+            console.log(`   ⏭️  ${resourceId} (locally modified, skipping)`);
+            newStateSection[resourceId] = resource.id;
+            skipped++;
+            continue;
+          }
+        }
+      }
+    }
+
     // Skip resources whose local file was deleted (works without git)
-    // A resource that was previously tracked (in state) but has no local file = intentional deletion
     if (!bootstrap && !force && !isNew) {
       const folderPath = FOLDER_MAP[resourceType];
       const dir = join(RESOURCES_DIR, folderPath);
@@ -762,7 +784,7 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
   if (resourceIds?.length) {
     if (!typeFilter?.length || typeFilter.length !== 1) {
       throw new Error(
-        "Single-resource pull requires exactly one resource type. Example: npm run pull:dev -- squads --id <uuid>",
+        "Single-resource pull requires exactly one resource type. Example: npm run pull -- <org> --type squads --id <uuid>",
       );
     }
   }
@@ -929,7 +951,7 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
 
   if (totalSkipped > 0) {
     console.log(`\n   ℹ️  ${totalSkipped} file(s) preserved (locally changed)`);
-    console.log("   Run with --force to overwrite: npm run pull:dev:force");
+    console.log("   Run with --force to overwrite: npm run pull -- <org> --force");
   }
 
   return { state, stats, force, bootstrap };

src/push.ts

@@ -6,6 +6,7 @@ import {
   VAPI_BASE_URL,
   FORCE_DELETE,
   APPLY_FILTER,
+  BASE_DIR,
   removeExcludedKeys,
 } from "./config.ts";
 import { loadState, saveState } from "./state.ts";
@@ -628,13 +629,14 @@ function filterResourcesByPaths<T>(
 ): ResourceFile<T>[] {
   if (!APPLY_FILTER.filePaths?.length) return resources;
 
-  // Get all resourceIds that match the file paths for this type
   const matchingIds = new Set<string>();
 
   for (const filePath of APPLY_FILTER.filePaths) {
-    // Try to match the file path to a resourceId
+    const resolvedInput = resolve(BASE_DIR, filePath);
+
     for (const resource of resources) {
       if (
+        resource.filePath === resolvedInput ||
         resource.filePath.endsWith(filePath) ||
         filePath.endsWith(resource.resourceId + ".yml") ||
         filePath.endsWith(resource.resourceId + ".yaml") ||