@juspay/neurolink 9.95.0 → 9.95.1

package/dist/cli/factories/commandFactory.js

@@ -24,7 +24,7 @@ import { initializeCliParser } from "../parser.js";
 import { formatFileSize, saveAudioToFile } from "../utils/audioFileUtils.js";
 import { playAudio } from "../utils/audioPlayer.js";
 import { resolveFilePaths } from "../utils/pathResolver.js";
-import { validateCliInputFiles, validateCsvMaxRows, } from "../utils/inputValidation.js";
+import { validateCliInputFiles, validateCsvMaxRows, validatePromptsFilePath, } from "../utils/inputValidation.js";
 import { animatedWrite } from "../utils/typewriter.js";
 import { createStreamAbortHandler } from "../utils/abortHandler.js";
 import { formatVideoFileSize, getVideoMetadataSummary, saveVideoToFile, } from "../utils/videoFileUtils.js";
@@ -742,11 +742,18 @@ export class CLICommandFactory {
             alias: "skills-dir",
         },
     };
-    // Helper method to build options for commands
-    static buildOptions(yargs, additionalOptions = {}) {
+    // Helper method to build options for commands. `excludeOptions` drops
+    // common flags from registration entirely (not just from validation) —
+    // #1191 round-5: batch uses this to omit `commonOptions.file` so `--file`
+    // isn't a recognized flag at all, since it would collide with the
+    // `<file>` positional (the prompts list).
+    static buildOptions(yargs, additionalOptions = {}, excludeOptions = []) {
+        const baseOptions = excludeOptions.length === 0
+            ? CLICommandFactory.commonOptions
+            : Object.fromEntries(Object.entries(CLICommandFactory.commonOptions).filter(([key]) => !excludeOptions.includes(key)));
         return (yargs
             .options({
-            ...CLICommandFactory.commonOptions,
+            ...baseOptions,
             ...additionalOptions,
         })
             // NEW9: implies relationships so users who pass --stt-provider or
@@ -1543,11 +1550,19 @@ export class CLICommandFactory {
      */
     static createBatchCommand() {
         return {
-            command: "batch <file>",
+            // #1191 round-5: the positional is named `promptsFile`, not `file` —
+            // yargs implicitly accepts `--<positionalName>` as a flag alias for
+            // any positional regardless of whether it's separately registered via
+            // `.options()`, so a positional literally named `file` would let
+            // `--file` silently pass strictOptions() even after removing
+            // `commonOptions.file` below. Renaming the key (invocation syntax is
+            // unaffected — it's still just `neurolink batch prompts.txt`) is what
+            // actually makes `--file` an unknown argument.
+            command: "batch <promptsFile>",
             describe: "Process multiple prompts from a file",
             builder: (yargs) => {
                 return CLICommandFactory.buildOptions(yargs
-                    .positional("file", {
+                    .positional("promptsFile", {
                     type: "string",
                     description: "File with prompts (one per line)",
                     demandOption: true,
@@ -1555,7 +1570,11 @@ export class CLICommandFactory {
                     .example("$0 batch prompts.txt", "Process prompts from file")
                     .example("$0 batch questions.txt --format json", "Export results as JSON")
                     .example("$0 batch tasks.txt -p vertex --delay 2000", "Use Vertex AI with 2s delay")
-                    .example("$0 batch batch.txt --output results.json", "Save results to file"));
+                    .example("$0 batch batch.txt --output results.json", "Save results to file"), {}, 
+                // `--file` is not a batch flag — the positional above is the
+                // prompts-list path. Omit it from registration so it's rejected
+                // as unknown rather than silently accepted then ignored.
+                ["file"]);
             },
             handler: async (argv) => await CLICommandFactory.executeBatch(argv),
         };
@@ -3349,13 +3368,30 @@ export class CLICommandFactory {
         CLICommandFactory.validateAnthropicSubscriptionOptions(options);
         const spinner = options.quiet ? null : ora().start();
         try {
-            if (!argv.file) {
+            if (!argv.promptsFile) {
                 throw new Error("No file specified");
             }
-            if (!fs.existsSync(argv.file)) {
-                throw new Error(`File not found: ${argv.file}`);
-            }
-            const buffer = fs.readFileSync(argv.file);
+            // #291/round-4 #1191: validate multimodal flags and resolve their
+            // paths *before* the prompts file is read/parsed below, mirroring
+            // generate/stream (which validate all inputs before any processing).
+            // Previously this ran after `fs.readFileSync(resolvedPromptsPath)`,
+            // so a large prompts file paired with an invalid --image path paid
+            // the read/parse cost before the flag error ever surfaced. `--file`
+            // (the common auto-detect flag) isn't registered on batch at all —
+            // see createBatchCommand — so `argv.file` can never be set here; no
+            // exclusion needed to protect the (differently-named) positional.
+            validateCliInputFiles(argv);
+            const batchImages = CLICommandFactory.processCliImages(argv.image);
+            const batchCsvFiles = CLICommandFactory.processCliCSVFiles(argv.csv);
+            const batchPdfFiles = CLICommandFactory.processCliPDFFiles(argv.pdf);
+            const batchVideoFiles = CLICommandFactory.processCliVideoFiles(argv.video);
+            // #291: route the prompts-list positional through the same friendly
+            // aggregated-error path as the multimodal flags above (not found /
+            // unreadable / directory / malformed file:// URL), instead of a raw
+            // existsSync+readFileSync that throws an unfriendly EISDIR when
+            // pointed at a directory.
+            const resolvedPromptsPath = validatePromptsFilePath(argv.promptsFile);
+            const buffer = fs.readFileSync(resolvedPromptsPath);
             const prompts = buffer
                 .toString("utf8")
                 .split("\n")
@@ -3390,6 +3426,19 @@ export class CLICommandFactory {
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };
             const sessionId = globalSession.getCurrentSessionId();
+            // batchImages/batchCsvFiles/batchPdfFiles/batchVideoFiles were already
+            // validated and resolved above, before the prompts file was read.
+            if (batchImages?.length ||
+                batchCsvFiles?.length ||
+                batchPdfFiles?.length ||
+                batchVideoFiles?.length) {
+                // Pause the spinner so the notice isn't swallowed by its re-renders.
+                // Safety-relevant, so always visible (not gated behind --quiet) and
+                // written to stderr so `--format json` output on stdout stays parseable.
+                spinner?.stop();
+                logger.alwaysStderr(chalk.yellow("⚠️  Multimodal files (--image/--csv/--pdf/--video) are attached to ALL prompts in this batch."));
+                spinner?.start();
+            }
             for (let i = 0; i < prompts.length; i++) {
                 if (spinner) {
                     spinner.text = `Processing ${i + 1}/${prompts.length}: ${prompts[i].substring(0, 30)}...`;
@@ -3425,7 +3474,33 @@ export class CLICommandFactory {
                         ? { ...contextMetadata, sessionId }
                         : contextMetadata;
                     const runBatchGenerate = () => sdk.generate({
-                        input: { text: inputText },
+                        input: {
+                            text: inputText,
+                            ...(batchImages?.length && { images: batchImages }),
+                            ...(batchCsvFiles?.length && { csvFiles: batchCsvFiles }),
+                            ...(batchPdfFiles?.length && { pdfFiles: batchPdfFiles }),
+                            ...(batchVideoFiles?.length && {
+                                videoFiles: batchVideoFiles,
+                            }),
+                        },
+                        // Only construct these when the corresponding files are
+                        // actually attached — batch has no CSV/video mode to opt into,
+                        // unlike generate/stream, so an empty options object here is
+                        // pure noise on every prompt of every batch run.
+                        ...(batchCsvFiles?.length && {
+                            csvOptions: {
+                                maxRows: argv.csvMaxRows,
+                                formatStyle: argv.csvFormat,
+                            },
+                        }),
+                        ...(batchVideoFiles?.length && {
+                            videoOptions: {
+                                frames: argv.videoFrames,
+                                quality: argv.videoQuality,
+                                format: argv.videoFormat,
+                                transcribeAudio: argv.transcribeAudio,
+                            },
+                        }),
                         provider: enhancedOptions.provider,
                         model: enhancedOptions.model,
                         temperature: enhancedOptions.temperature,

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

@@ -1,12 +1,13 @@
 /**
  * CLI Input Validation Utilities
  *
- * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
- * --csv-max-rows before a generate/stream/batch run starts, so bad input
- * fails fast with a clear message instead of surfacing deep inside provider
- * calls. Exported as standalone functions (rather than private statics on
- * CLICommandFactory) so callers — including tests — can import and invoke
- * them directly, without reaching into the class via an `unknown` cast.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, and --csv-max-rows before a
+ * generate/stream/batch run starts, so bad input fails fast with a clear
+ * message instead of surfacing deep inside provider calls. Exported as
+ * standalone functions (rather than private statics on CLICommandFactory)
+ * so callers — including tests — can import and invoke them directly,
+ * without reaching into the class via an `unknown` cast.
  */
 /**
  * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
@@ -24,11 +25,23 @@ export declare const CLI_SOFT_LIMITS_MB: {
 };
 /**
  * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
- * starts: every local path must exist, must not be a directory, and — for
- * the flags with a soft limit — triggers a size warning above the
- * threshold. URLs/data URIs skip both existence and size checks (#319).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export declare function validateCliInputFiles(argv: Record<string, unknown>): void;
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export declare function validatePromptsFilePath(rawPath: string): string;
 /**
  * #310: validate --csv-max-rows is a positive integer in the range
  * 1-100000, matching the documented option range (the value previously

package/dist/cli/utils/inputValidation.js

@@ -1,17 +1,20 @@
 /**
  * CLI Input Validation Utilities
  *
- * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
- * --csv-max-rows before a generate/stream/batch run starts, so bad input
- * fails fast with a clear message instead of surfacing deep inside provider
- * calls. Exported as standalone functions (rather than private statics on
- * CLICommandFactory) so callers — including tests — can import and invoke
- * them directly, without reaching into the class via an `unknown` cast.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, and --csv-max-rows before a
+ * generate/stream/batch run starts, so bad input fails fast with a clear
+ * message instead of surfacing deep inside provider calls. Exported as
+ * standalone functions (rather than private statics on CLICommandFactory)
+ * so callers — including tests — can import and invoke them directly,
+ * without reaching into the class via an `unknown` cast.
  */
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { logger } from "../../lib/utils/logger.js";
-import { resolveFilePaths } from "./pathResolver.js";
+import { redactUrlForError } from "../../lib/utils/logSanitize.js";
+import { resolveFilePath } from "./pathResolver.js";
 /**
  * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
  * defined here rather than reusing `lib/processors/config/sizeLimits.ts`'s
@@ -26,18 +29,126 @@ export const CLI_SOFT_LIMITS_MB = {
     PDF_MAX_MB: 100,
     VIDEO_MAX_MB: 500,
 };
+// `file://` is intentionally excluded here: it addresses a local path, so it
+// must still go through directory/missing-path validation below (via
+// tryResolveFileUrl in validateSingleLocalPath). Only genuine remote/inline
+// references (http(s), data URIs) skip validation entirely (#319).
 function isNonLocalFileReference(filePath) {
     const lower = filePath.toLowerCase();
     return (lower.startsWith("http://") ||
         lower.startsWith("https://") ||
-        lower.startsWith("file://") ||
         lower.startsWith("data:"));
 }
+// #291: a `file://` URL still points at something on disk, so validation
+// needs the real filesystem path. Returns undefined (instead of throwing)
+// for a malformed URL so the caller can report a friendly error.
+function tryResolveFileUrl(filePath) {
+    if (!filePath.toLowerCase().startsWith("file://")) {
+        return filePath;
+    }
+    try {
+        return fileURLToPath(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Shared aggregated-error format for any invalid local file path (missing,
+ * unreadable, a directory, or a malformed `file://` URL). Used by both the
+ * flag-based loop in `validateCliInputFiles` and the batch `<promptsFile>`
+ * positional check in `validatePromptsFilePath`, so every caller gets the
+ * same clear error + troubleshooting hints instead of a raw exception.
+ */
+function buildInvalidFileError(errors) {
+    return new Error("❌ One or more input files are invalid:\n" +
+        `${errors.join("\n")}\n` +
+        "💡 Troubleshooting:\n" +
+        "  • Check the path is correct and relative to your current directory, or pass an absolute path / URL.\n" +
+        `  • Check your working directory (${process.cwd()}).\n` +
+        "  • For remote resources, prefix the value with http:// or https://.\n" +
+        "  • If you pointed at a folder, point at the file inside it instead.");
+}
+/**
+ * Validate a single raw path/URL value for `option`, pushing a friendly
+ * message onto `errors` instead of letting fs calls throw a raw exception
+ * (ENOENT, EACCES/EPERM TOCTOU, a directory, or a malformed `file://` URL).
+ * Returns the resolved local filesystem path on success (or the original
+ * value unchanged for a skipped http(s)/data: reference), and `undefined`
+ * when an error was pushed.
+ *
+ * `rawPath` is redacted via `redactUrlForError` before ever being
+ * interpolated into a message — a `file://` value can carry a sensitive
+ * query string, fragment, or embedded `user:pass@` credentials that must
+ * never be echoed back verbatim. This is a no-op for ordinary filesystem
+ * paths (they aren't parseable as a URL, so the redaction fallback simply
+ * returns them unchanged).
+ */
+function validateSingleLocalPath(option, rawPath, errors, warnAtMB) {
+    const resolvedPath = resolveFilePath(rawPath);
+    if (isNonLocalFileReference(resolvedPath)) {
+        // URLs / data: refs skip both existence and size checks (#319).
+        return resolvedPath;
+    }
+    const safeRawPath = redactUrlForError(rawPath);
+    // #291: `file://` URLs are local paths in disguise — validate the decoded
+    // filesystem path so a directory or missing path is still caught here
+    // instead of failing cryptically deep in processing.
+    const pathToValidate = tryResolveFileUrl(resolvedPath);
+    if (pathToValidate === undefined) {
+        errors.push(`${option} is not a valid file:// URL: ${safeRawPath}`);
+        return undefined;
+    }
+    const safeResolvedPath = redactUrlForError(pathToValidate);
+    // Single statSync covers existence, directory rejection, and the size
+    // warning below — avoids a second syscall and closes the TOCTOU gap a
+    // separate existsSync()+statSync() pair would leave.
+    let stat;
+    try {
+        stat = fs.statSync(pathToValidate);
+    }
+    catch (err) {
+        // Only ENOENT actually means "not found" — EACCES (permission denied),
+        // ELOOP (symlink loop), ENOTDIR, etc. are real failures that get masked
+        // (and made undebuggable) if we blanket-label every statSync error the
+        // same way.
+        const code = err?.code;
+        if (code === "ENOENT") {
+            errors.push(`${option} path not found: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        }
+        else {
+            const reason = err instanceof Error ? err.message : String(err);
+            errors.push(`${option} path could not be accessed: ${safeRawPath} (resolved to ${safeResolvedPath}) — ` +
+                `${code ? `${code}: ` : ""}${reason}`);
+        }
+        return undefined;
+    }
+    // #288: reject a directory before it fails cryptically deep in processing
+    // (readFileSync on a dir throws a raw EISDIR).
+    if (stat.isDirectory()) {
+        errors.push(`${option} path is a directory, not a file: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        return undefined;
+    }
+    // #319: warn (not error) when a local multimodal file is unusually large
+    // so the user isn't surprised by slow processing / token blowups. Safety-
+    // relevant, so always visible (not gated behind --quiet) and written to
+    // stderr — never stdout — so `--format json` output stays parseable.
+    if (warnAtMB !== undefined) {
+        const sizeMB = stat.size / (1024 * 1024);
+        if (sizeMB > warnAtMB) {
+            logger.alwaysStderr(chalk.yellow(`⚠️  ${option} file ${safeRawPath} is ${sizeMB.toFixed(1)}MB ` +
+                `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
+                `or exceed provider token/size limits.`));
+        }
+    }
+    return pathToValidate;
+}
 /**
  * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
- * starts: every local path must exist, must not be a directory, and — for
- * the flags with a soft limit — triggers a size warning above the
- * threshold. URLs/data URIs skip both existence and size checks (#319).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export function validateCliInputFiles(argv) {
     const fileArgs = [
@@ -63,64 +174,39 @@ export function validateCliInputFiles(argv) {
         },
         { option: "--file", value: argv.file },
     ];
-    const missingPaths = [];
+    const errors = [];
     for (const { option, value, warnAtMB } of fileArgs) {
         if (!value) {
             continue;
         }
         const rawPaths = Array.isArray(value) ? value : [value];
-        const resolvedPaths = resolveFilePaths(rawPaths);
-        for (let i = 0; i < resolvedPaths.length; i++) {
-            const resolvedPath = resolvedPaths[i];
-            // URLs / data: refs skip both existence and size checks (#319).
-            if (isNonLocalFileReference(resolvedPath)) {
-                continue;
-            }
-            // Single statSync covers existence, directory rejection, and the
-            // size warning below — avoids a second syscall and closes the
-            // TOCTOU gap a separate existsSync()+statSync() pair would leave.
-            let stat;
-            try {
-                stat = fs.statSync(resolvedPath);
-            }
-            catch (err) {
-                // Only ENOENT actually means "not found" — EACCES (permission
-                // denied), ELOOP (symlink loop), ENOTDIR, etc. are real failures
-                // that get masked (and made undebuggable) if we blanket-label
-                // every statSync error the same way.
-                const code = err?.code;
-                if (code === "ENOENT") {
-                    missingPaths.push(`${option} path not found: ${rawPaths[i]} (resolved to ${resolvedPath})`);
-                }
-                else {
-                    const reason = err instanceof Error ? err.message : String(err);
-                    missingPaths.push(`${option} path could not be accessed: ${rawPaths[i]} (resolved to ${resolvedPath}) — ` +
-                        `${code ? `${code}: ` : ""}${reason}`);
-                }
-                continue;
-            }
-            if (stat.isDirectory()) {
-                missingPaths.push(`${option} path is a directory, not a file: ${rawPaths[i]} (resolved to ${resolvedPath})`);
-                continue;
-            }
-            // #319: warn (not error) when a local multimodal file is unusually
-            // large so the user isn't surprised by slow processing / token blowups.
-            if (warnAtMB !== undefined) {
-                const sizeMB = stat.size / (1024 * 1024);
-                if (sizeMB > warnAtMB) {
-                    logger.always(chalk.yellow(`⚠️  ${option} file ${rawPaths[i]} is ${sizeMB.toFixed(1)}MB ` +
-                        `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
-                        `or exceed provider token/size limits.`));
-                }
-            }
+        for (const rawPath of rawPaths) {
+            validateSingleLocalPath(option, rawPath, errors, warnAtMB);
         }
     }
-    if (missingPaths.length > 0) {
-        throw new Error("❌ One or more input files are invalid:\n" +
-            `${missingPaths.join("\n")}\n` +
-            "💡 Check the path is correct and relative to your current directory, " +
-            "or pass an absolute path / URL.");
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
+    }
+}
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export function validatePromptsFilePath(rawPath) {
+    const errors = [];
+    const resolved = validateSingleLocalPath("<file>", rawPath, errors);
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
     }
+    // `errors` is empty here, so `validateSingleLocalPath` did not return
+    // undefined.
+    return resolved;
 }
 /**
  * #310: validate --csv-max-rows is a positive integer in the range

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

@@ -138,8 +138,8 @@ export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClass
  * Batch command arguments
  */
 export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
-    /** Input file path */
-    file?: string;
+    /** Prompts-list file path (the `<promptsFile>` positional) */
+    promptsFile?: string;
     /** AI provider to use */
     provider?: string;
     /** Model name */
@@ -1684,3 +1684,8 @@ export type CliAudioPlayerCommand = {
     command: string;
     args: string[];
 };
+/**
+ * The CLI flags validated by `validateCliInputFiles` before a
+ * generate/stream/batch run starts (--image/--csv/--pdf/--video/--file).
+ */
+export type CliValidatedFileOption = "--image" | "--csv" | "--pdf" | "--video" | "--file";

package/dist/lib/utils/logger.d.ts

@@ -162,6 +162,17 @@ declare class NeuroLinkLogger {
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args: unknown[]): void;
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -200,6 +211,7 @@ export declare const logger: {
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
+    alwaysStderr: (...args: unknown[]) => void;
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;

package/dist/lib/utils/logger.js

@@ -347,6 +347,19 @@ class NeuroLinkLogger {
     always(...args) {
         console.log(...args);
     }
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args) {
+        console.error(...args);
+    }
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -436,6 +449,9 @@ export const logger = {
     always: (...args) => {
         neuroLinkLogger.always(...args);
     },
+    alwaysStderr: (...args) => {
+        neuroLinkLogger.alwaysStderr(...args);
+    },
     table: (data) => {
         neuroLinkLogger.table(data);
     },

package/dist/types/cli.d.ts

@@ -138,8 +138,8 @@ export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClass
  * Batch command arguments
  */
 export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
-    /** Input file path */
-    file?: string;
+    /** Prompts-list file path (the `<promptsFile>` positional) */
+    promptsFile?: string;
     /** AI provider to use */
     provider?: string;
     /** Model name */
@@ -1684,3 +1684,8 @@ export type CliAudioPlayerCommand = {
     command: string;
     args: string[];
 };
+/**
+ * The CLI flags validated by `validateCliInputFiles` before a
+ * generate/stream/batch run starts (--image/--csv/--pdf/--video/--file).
+ */
+export type CliValidatedFileOption = "--image" | "--csv" | "--pdf" | "--video" | "--file";

package/dist/utils/logger.d.ts

@@ -162,6 +162,17 @@ declare class NeuroLinkLogger {
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args: unknown[]): void;
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -200,6 +211,7 @@ export declare const logger: {
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
+    alwaysStderr: (...args: unknown[]) => void;
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;

package/dist/utils/logger.js

@@ -347,6 +347,19 @@ class NeuroLinkLogger {
     always(...args) {
         console.log(...args);
     }
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args) {
+        console.error(...args);
+    }
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -436,6 +449,9 @@ export const logger = {
     always: (...args) => {
         neuroLinkLogger.always(...args);
     },
+    alwaysStderr: (...args) => {
+        neuroLinkLogger.alwaysStderr(...args);
+    },
     table: (data) => {
         neuroLinkLogger.table(data);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.95.0",
+  "version": "9.95.1",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {