@juspay/neurolink 9.50.2 → 9.51.0

package/dist/cli/commands/proxy.js

@@ -26,7 +26,14 @@ const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/obse
 // =============================================================================
 // STATE MANAGEMENT
 // =============================================================================
-const proxyStateManager = new StateFileManager("proxy-state.json");
+let proxyStateManager = new StateFileManager("proxy-state.json");
+/**
+ * Reinitialise the state manager with a custom base directory.
+ * Called when --dev redirects writable paths to .neurolink-dev/.
+ */
+function setProxyStateDir(baseDir) {
+    proxyStateManager = new StateFileManager("proxy-state.json", baseDir);
+}
 function saveProxyState(state) {
     proxyStateManager.save(state);
 }
@@ -333,12 +340,12 @@ async function loadProxyStartEnv(argv, spinner) {
         process.exit(1);
     }
 }
-async function createProxyNeurolinkRuntime() {
+async function createProxyNeurolinkRuntime(logsDir) {
     process.env.NEUROLINK_SKIP_MCP = "true";
     const { NeuroLink } = await import("../../lib/neurolink.js");
     const neurolink = new NeuroLink();
     const { initRequestLogger, cleanupLogs } = await import("../../lib/proxy/requestLogger.js");
-    initRequestLogger(true);
+    initRequestLogger(true, logsDir);
     cleanupLogs(7, 500);
     return { neurolink, cleanupLogs };
 }
@@ -701,7 +708,7 @@ function registerProxyShutdownHandlers(params) {
         catch {
             // non-fatal — proxy shutdown must not block on OTel
         }
-        if (signal === "SIGINT") {
+        if (signal === "SIGINT" && !params.isDev) {
             try {
                 const shutdownHost = params.host === "0.0.0.0" ? "localhost" : params.host;
                 await clearClaudeProxySettings(`http://${shutdownHost}:${params.port}`);
@@ -733,7 +740,11 @@ async function startProxyRuntime(params) {
         port: params.port,
         hostname: params.host,
     });
-    const guardPid = spawnFailOpenGuard(params.host, params.port, process.pid);
+    // Skip the fail-open guard in dev mode — it monitors the proxy and clears
+    // global Claude settings on exit, which is exactly what we want to avoid.
+    const guardPid = params.argv.dev
+        ? undefined
+        : spawnFailOpenGuard(params.host, params.port, process.pid);
     const readinessHost = params.host === "0.0.0.0" ? "127.0.0.1" : params.host;
     await waitForProxyReadiness({
         host: readinessHost,
@@ -767,10 +778,16 @@ async function startProxyRuntime(params) {
     if (params.spinner) {
         params.spinner.succeed(chalk.green("Claude proxy started successfully"));
     }
+    const isDev = params.argv.dev ?? false;
     const normalizedHost = params.host === "0.0.0.0" ? "localhost" : params.host;
     const url = `http://${normalizedHost}:${params.port}`;
     printProxyBanner(url, params.strategy);
-    logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(params.passthrough ? "passthrough" : "full")}`);
+    if (isDev) {
+        logger.always(`  ${chalk.bold("Mode:")}       ${chalk.magenta("dev (isolated — state in .neurolink-dev/)")}`);
+    }
+    else {
+        logger.always(`  ${chalk.bold("Mode:")}       ${chalk.cyan(params.passthrough ? "passthrough" : "full")}`);
+    }
     if (params.passthrough) {
         logger.always(chalk.yellow("  ! Passthrough mode forwards client auth directly to Anthropic"));
         logger.always(chalk.dim("    Stored proxy OAuth/API credentials are ignored; clients need their own valid Anthropic auth."));
@@ -778,29 +795,52 @@ async function startProxyRuntime(params) {
     if (params.loadedEnvFile) {
         logger.always(`  ${chalk.bold("Env File:")}   ${chalk.cyan(params.loadedEnvFile)}`);
     }
-    try {
-        await setClaudeProxySettings(url);
-        logger.always(chalk.green("  ✓ Auto-configured Claude Code settings"));
-        logger.always(chalk.dim("    Restart Claude Code to connect through proxy"));
+    if (!isDev) {
+        try {
+            await setClaudeProxySettings(url);
+            logger.always(chalk.green("  ✓ Auto-configured Claude Code settings"));
+            logger.always(chalk.dim("    Restart Claude Code to connect through proxy"));
+        }
+        catch (error) {
+            logger.debug("[proxy] Failed to auto-configure Claude Code: " +
+                (error instanceof Error ? error.message : String(error)));
+        }
     }
-    catch (error) {
-        logger.debug("[proxy] Failed to auto-configure Claude Code: " +
-            (error instanceof Error ? error.message : String(error)));
+    else {
+        logger.always(chalk.dim("  ⊘ Dev mode: skipping client auto-configuration"));
     }
     const maintenance = startProxyBackgroundMaintenance(params.cleanupLogs);
     registerProxyShutdownHandlers({
         server,
         host: params.host,
         port: params.port,
+        isDev,
         ...maintenance,
     });
 }
 async function startProxyCommandHandler(argv) {
     const spinner = argv.quiet ? null : ora("Starting Claude proxy...").start();
+    const isDev = argv.dev ?? false;
     try {
-        await ensureProxyStartAllowed(spinner);
+        // In dev mode: redirect writable state to .neurolink-dev/ and skip singleton check
+        let devPaths;
+        if (isDev) {
+            const { resolveProxyPaths } = await import("../../lib/proxy/proxyPaths.js");
+            devPaths = resolveProxyPaths(true);
+            setProxyStateDir(devPaths.stateDir);
+            const { initAccountQuota } = await import("../../lib/proxy/accountQuota.js");
+            initAccountQuota(devPaths.quotaFile);
+            // Ensure the dev state directory exists
+            const { mkdirSync, existsSync } = await import("fs");
+            if (!existsSync(devPaths.stateDir)) {
+                mkdirSync(devPaths.stateDir, { recursive: true, mode: 0o700 });
+            }
+        }
+        if (!isDev) {
+            await ensureProxyStartAllowed(spinner);
+        }
         const loadedEnvFile = await loadProxyStartEnv(argv, spinner);
-        const { neurolink, cleanupLogs } = await createProxyNeurolinkRuntime();
+        const { neurolink, cleanupLogs } = await createProxyNeurolinkRuntime(devPaths?.logsDir);
         const { proxyConfig, strategy, modelRouter, passthrough } = await loadProxyStartConfiguration(argv, spinner);
         if (spinner) {
             spinner.text = "Configuring server...";
@@ -904,6 +944,11 @@ export const proxyStartCommand = {
             type: "boolean",
             default: false,
             description: "Run in transparent passthrough mode (no retry, no rotation, no polyfill)",
+        })
+            .option("dev", {
+            type: "boolean",
+            default: false,
+            description: "Run in isolated dev mode — state files scoped to .neurolink-dev/ in cwd, no client auto-configuration, no singleton check",
         })
             .example("neurolink proxy start", "Start proxy on default port 55669 with fill-first strategy")
             .example("neurolink proxy start -p 8080 -s fill-first", "Start proxy on port 8080 with fill-first")

package/dist/cli/utils/serverUtils.d.ts

@@ -44,8 +44,9 @@ export declare class StateFileManager<T> {
     /**
      * Create a new state file manager
      * @param filename - Name of the state file (e.g., "serve-state.json")
+     * @param baseDir - Optional base directory (defaults to ~/.neurolink)
      */
-    constructor(filename: string);
+    constructor(filename: string, baseDir?: string);
     /**
      * Get the full path to the state file
      */

package/dist/cli/utils/serverUtils.js

@@ -92,9 +92,10 @@ export class StateFileManager {
     /**
      * Create a new state file manager
      * @param filename - Name of the state file (e.g., "serve-state.json")
+     * @param baseDir - Optional base directory (defaults to ~/.neurolink)
      */
-    constructor(filename) {
-        this.filePath = path.join(getNeuroLinkDir(), filename);
+    constructor(filename, baseDir) {
+        this.filePath = path.join(baseDir ?? getNeuroLinkDir(), filename);
     }
     /**
      * Get the full path to the state file
@@ -107,7 +108,10 @@ export class StateFileManager {
      * @param state - State object to save
      */
     save(state) {
-        ensureStateDir();
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
         fs.writeFileSync(this.filePath, JSON.stringify(state, null, 2));
     }
     /**

package/dist/lib/proxy/accountQuota.d.ts

@@ -16,6 +16,12 @@ import type { AccountQuota } from "../types/index.js";
  * Pure computation — no I/O, no blocking.
  */
 export declare function parseQuotaHeaders(headers: Headers | Record<string, string>): AccountQuota | null;
+/**
+ * Initialise the quota module with a custom file path.
+ * When set, all reads/writes go to this path instead of the default
+ * ~/.neurolink/account-quotas.json. Call before the first load/save.
+ */
+export declare function initAccountQuota(quotaFilePath: string): void;
 /**
  * Load all persisted account quotas.
  * First call reads from disk; subsequent calls return the in-memory cache.

package/dist/lib/proxy/accountQuota.js

@@ -9,7 +9,7 @@
  * updates an in-memory cache and debounces disk writes so the request/response
  * path is never blocked by file I/O.
  */
-import { join } from "path";
+import { dirname, join } from "path";
 import { homedir } from "os";
 import { promises as fs } from "fs";
 // ---------------------------------------------------------------------------
@@ -73,11 +73,32 @@ let memoryCache = {};
 let cacheLoaded = false;
 let dirty = false;
 let flushTimer = null;
+/** Custom quota file path set via initAccountQuota(). */
+let customQuotaFilePath = null;
+/**
+ * Initialise the quota module with a custom file path.
+ * When set, all reads/writes go to this path instead of the default
+ * ~/.neurolink/account-quotas.json. Call before the first load/save.
+ */
+export function initAccountQuota(quotaFilePath) {
+    customQuotaFilePath = quotaFilePath;
+    // Cancel any pending flush from a previous configuration so it does not
+    // write stale data to the new path.
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    // Reset cache so the new path is picked up on next load
+    memoryCache = {};
+    cacheLoaded = false;
+    dirty = false;
+}
 function getQuotaFilePath() {
-    return join(homedir(), ".neurolink", QUOTA_FILE);
+    return customQuotaFilePath ?? join(homedir(), ".neurolink", QUOTA_FILE);
 }
 async function ensureDir() {
-    const dir = join(homedir(), ".neurolink");
+    const filePath = getQuotaFilePath();
+    const dir = dirname(filePath);
     await fs.mkdir(dir, { recursive: true, mode: 0o700 }).catch(() => {
         // Non-fatal: directory may already exist
     });

package/dist/lib/proxy/proxyPaths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Proxy file path resolver.
+ *
+ * In normal mode, all paths resolve under ~/.neurolink/.
+ * In dev mode (--dev), writable paths resolve under <cwd>/.neurolink-dev/
+ * so a local dev proxy never touches the global proxy's state.
+ *
+ * Read-only paths (like .env) always point to the global location
+ * since credentials must be shared.
+ *
+ * NOTE: Claude Code header snapshots (~/.neurolink/header-snapshots/) are
+ * not redirected in dev mode. They are only written when a real Claude Code
+ * client connects, which typically does not happen during dev testing.
+ */
+export type ProxyPaths = {
+    /** Base directory for proxy state files */
+    stateDir: string;
+    /** logs/ — request/response logs */
+    logsDir: string;
+    /** account-quotas.json — per-account rate limit state */
+    quotaFile: string;
+    /** Whether this is a dev-mode isolated instance */
+    isDev: boolean;
+};
+export declare function resolveProxyPaths(dev: boolean): ProxyPaths;

package/dist/lib/proxy/proxyPaths.js

@@ -0,0 +1,35 @@
+/**
+ * Proxy file path resolver.
+ *
+ * In normal mode, all paths resolve under ~/.neurolink/.
+ * In dev mode (--dev), writable paths resolve under <cwd>/.neurolink-dev/
+ * so a local dev proxy never touches the global proxy's state.
+ *
+ * Read-only paths (like .env) always point to the global location
+ * since credentials must be shared.
+ *
+ * NOTE: Claude Code header snapshots (~/.neurolink/header-snapshots/) are
+ * not redirected in dev mode. They are only written when a real Claude Code
+ * client connects, which typically does not happen during dev testing.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function resolveProxyPaths(dev) {
+    if (dev) {
+        const base = join(process.cwd(), ".neurolink-dev");
+        return {
+            stateDir: base,
+            logsDir: join(base, "logs"),
+            quotaFile: join(base, "account-quotas.json"),
+            isDev: true,
+        };
+    }
+    const base = join(homedir(), ".neurolink");
+    return {
+        stateDir: base,
+        logsDir: join(base, "logs"),
+        quotaFile: join(base, "account-quotas.json"),
+        isDev: false,
+    };
+}
+//# sourceMappingURL=proxyPaths.js.map

package/dist/lib/proxy/requestLogger.d.ts

@@ -6,7 +6,7 @@
  * Useful for debugging and auditing proxy traffic.
  */
 import type { RequestAttemptLogEntry, RequestLogEntry } from "../types/index.js";
-export declare function initRequestLogger(enabled?: boolean): void;
+export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**
  * Log an upstream attempt separately from the final request outcome.

package/dist/lib/proxy/requestLogger.js

@@ -44,13 +44,13 @@ const SENSITIVE_HEADER_NAMES = new Set([
 const SENSITIVE_HEADER_PATTERN = /token|secret|key|password|credential/i;
 /** JSON keys whose values should be redacted in request/response bodies. */
 const SENSITIVE_BODY_KEYS = /("(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)"\s*:\s*)"(?:[^"\\]|\\.)*"/gi;
-export function initRequestLogger(enabled = true) {
+export function initRequestLogger(enabled = true, customLogsDir) {
     logEnabled = enabled;
     if (!enabled) {
         return;
     }
     try {
-        logDir = join(homedir(), ".neurolink", "logs");
+        logDir = customLogsDir ?? join(homedir(), ".neurolink", "logs");
         if (!existsSync(logDir)) {
             mkdirSync(logDir, { recursive: true, mode: 0o700 });
         }

package/dist/lib/types/cli.d.ts

@@ -765,6 +765,7 @@ export type ProxyStartArgs = {
     config?: string;
     envFile?: string;
     passthrough?: boolean;
+    dev?: boolean;
 };
 /** Arguments accepted by `neurolink proxy status` */
 export type ProxyStatusArgs = {

package/dist/proxy/accountQuota.d.ts

@@ -16,6 +16,12 @@ import type { AccountQuota } from "../types/index.js";
  * Pure computation — no I/O, no blocking.
  */
 export declare function parseQuotaHeaders(headers: Headers | Record<string, string>): AccountQuota | null;
+/**
+ * Initialise the quota module with a custom file path.
+ * When set, all reads/writes go to this path instead of the default
+ * ~/.neurolink/account-quotas.json. Call before the first load/save.
+ */
+export declare function initAccountQuota(quotaFilePath: string): void;
 /**
  * Load all persisted account quotas.
  * First call reads from disk; subsequent calls return the in-memory cache.

package/dist/proxy/accountQuota.js

@@ -9,7 +9,7 @@
  * updates an in-memory cache and debounces disk writes so the request/response
  * path is never blocked by file I/O.
  */
-import { join } from "path";
+import { dirname, join } from "path";
 import { homedir } from "os";
 import { promises as fs } from "fs";
 // ---------------------------------------------------------------------------
@@ -73,11 +73,32 @@ let memoryCache = {};
 let cacheLoaded = false;
 let dirty = false;
 let flushTimer = null;
+/** Custom quota file path set via initAccountQuota(). */
+let customQuotaFilePath = null;
+/**
+ * Initialise the quota module with a custom file path.
+ * When set, all reads/writes go to this path instead of the default
+ * ~/.neurolink/account-quotas.json. Call before the first load/save.
+ */
+export function initAccountQuota(quotaFilePath) {
+    customQuotaFilePath = quotaFilePath;
+    // Cancel any pending flush from a previous configuration so it does not
+    // write stale data to the new path.
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    // Reset cache so the new path is picked up on next load
+    memoryCache = {};
+    cacheLoaded = false;
+    dirty = false;
+}
 function getQuotaFilePath() {
-    return join(homedir(), ".neurolink", QUOTA_FILE);
+    return customQuotaFilePath ?? join(homedir(), ".neurolink", QUOTA_FILE);
 }
 async function ensureDir() {
-    const dir = join(homedir(), ".neurolink");
+    const filePath = getQuotaFilePath();
+    const dir = dirname(filePath);
     await fs.mkdir(dir, { recursive: true, mode: 0o700 }).catch(() => {
         // Non-fatal: directory may already exist
     });

package/dist/proxy/proxyPaths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Proxy file path resolver.
+ *
+ * In normal mode, all paths resolve under ~/.neurolink/.
+ * In dev mode (--dev), writable paths resolve under <cwd>/.neurolink-dev/
+ * so a local dev proxy never touches the global proxy's state.
+ *
+ * Read-only paths (like .env) always point to the global location
+ * since credentials must be shared.
+ *
+ * NOTE: Claude Code header snapshots (~/.neurolink/header-snapshots/) are
+ * not redirected in dev mode. They are only written when a real Claude Code
+ * client connects, which typically does not happen during dev testing.
+ */
+export type ProxyPaths = {
+    /** Base directory for proxy state files */
+    stateDir: string;
+    /** logs/ — request/response logs */
+    logsDir: string;
+    /** account-quotas.json — per-account rate limit state */
+    quotaFile: string;
+    /** Whether this is a dev-mode isolated instance */
+    isDev: boolean;
+};
+export declare function resolveProxyPaths(dev: boolean): ProxyPaths;

package/dist/proxy/proxyPaths.js

@@ -0,0 +1,34 @@
+/**
+ * Proxy file path resolver.
+ *
+ * In normal mode, all paths resolve under ~/.neurolink/.
+ * In dev mode (--dev), writable paths resolve under <cwd>/.neurolink-dev/
+ * so a local dev proxy never touches the global proxy's state.
+ *
+ * Read-only paths (like .env) always point to the global location
+ * since credentials must be shared.
+ *
+ * NOTE: Claude Code header snapshots (~/.neurolink/header-snapshots/) are
+ * not redirected in dev mode. They are only written when a real Claude Code
+ * client connects, which typically does not happen during dev testing.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function resolveProxyPaths(dev) {
+    if (dev) {
+        const base = join(process.cwd(), ".neurolink-dev");
+        return {
+            stateDir: base,
+            logsDir: join(base, "logs"),
+            quotaFile: join(base, "account-quotas.json"),
+            isDev: true,
+        };
+    }
+    const base = join(homedir(), ".neurolink");
+    return {
+        stateDir: base,
+        logsDir: join(base, "logs"),
+        quotaFile: join(base, "account-quotas.json"),
+        isDev: false,
+    };
+}

package/dist/proxy/requestLogger.d.ts

@@ -6,7 +6,7 @@
  * Useful for debugging and auditing proxy traffic.
  */
 import type { RequestAttemptLogEntry, RequestLogEntry } from "../types/index.js";
-export declare function initRequestLogger(enabled?: boolean): void;
+export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**
  * Log an upstream attempt separately from the final request outcome.

package/dist/proxy/requestLogger.js

@@ -44,13 +44,13 @@ const SENSITIVE_HEADER_NAMES = new Set([
 const SENSITIVE_HEADER_PATTERN = /token|secret|key|password|credential/i;
 /** JSON keys whose values should be redacted in request/response bodies. */
 const SENSITIVE_BODY_KEYS = /("(?:password|access_token|refresh_token|api_key|apiKey|secret|authorization|token|credential|x-api-key)"\s*:\s*)"(?:[^"\\]|\\.)*"/gi;
-export function initRequestLogger(enabled = true) {
+export function initRequestLogger(enabled = true, customLogsDir) {
     logEnabled = enabled;
     if (!enabled) {
         return;
     }
     try {
-        logDir = join(homedir(), ".neurolink", "logs");
+        logDir = customLogsDir ?? join(homedir(), ".neurolink", "logs");
         if (!existsSync(logDir)) {
             mkdirSync(logDir, { recursive: true, mode: 0o700 });
         }

package/dist/types/cli.d.ts

@@ -765,6 +765,7 @@ export type ProxyStartArgs = {
     config?: string;
     envFile?: string;
     passthrough?: boolean;
+    dev?: boolean;
 };
 /** Arguments accepted by `neurolink proxy status` */
 export type ProxyStatusArgs = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.50.2",
+  "version": "9.51.0",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {