@zvec/zvec-grep 0.1.4 → 0.1.6

package/dist/cli/args.js

@@ -1,27 +1,45 @@
 import { VALID_SYMBOL_TYPES } from "./types.js";
+import { parseMcpToolset } from "../mcp/toolset.js";
 const RG_OPTIONS_WITH_VALUE = new Set([
+    "--dfa-size-limit",
     "--encoding",
     "--engine",
-    "--ignore-file",
-    "--max-depth",
-    "--type",
-    "--type-not",
+    "--max-columns",
+    "--max-count",
+    "--regex-size-limit",
+    "--threads",
 ]);
 const RG_OPTIONS_WITHOUT_VALUE = new Set([
     "--auto-hybrid-regex",
     "--case-sensitive",
-    "--glob-case-insensitive",
+    "--binary",
+    "--crlf",
+    "--invert-match",
+    "--line-regexp",
+    "--mmap",
     "--multiline",
     "--multiline-dotall",
+    "--no-crlf",
+    "--no-fixed-strings",
     "--no-ignore",
     "--no-ignore-dot",
     "--no-ignore-files",
     "--no-ignore-global",
     "--no-ignore-parent",
     "--no-ignore-vcs",
+    "--no-config",
+    "--no-mmap",
+    "--no-multiline",
+    "--no-search-zip",
     "--pcre2",
+    "--one-file-system",
     "--search-zip",
     "--smart-case",
+    "--stop-on-nonmatch",
+    "--text",
+    "--unicode",
+    "--no-unicode",
+    "--glob-case-insensitive",
 ]);
 const MANAGED_RG_OUTPUT_OPTIONS = new Set([
     "--count",
@@ -29,18 +47,76 @@ const MANAGED_RG_OUTPUT_OPTIONS = new Set([
     "--files",
     "--files-with-matches",
     "--files-without-match",
+    "--column",
+    "--byte-offset",
+    "--no-column",
+    "--colors",
+    "--context-separator",
+    "--field-context-separator",
+    "--field-match-separator",
     "--json",
+    "--heading",
+    "--no-heading",
+    "--no-filename",
+    "--no-line-number",
     "--only-matching",
+    "--passthru",
+    "--path-separator",
+    "--quiet",
+    "--pretty",
     "--replace",
+    "--stats",
+    "--trim",
     "--vimgrep",
     "-c",
+    "-b",
+    "-I",
     "-l",
+    "-N",
     "-o",
+    "-p",
+    "-q",
+    "-r",
 ]);
 export function parseArgs(args) {
+    const commandInput = parseCommand(args);
+    if (commandInput.command === "help" || commandInput.command === "version") {
+        return {
+            command: commandInput.command,
+            options: {},
+            positionals: [],
+            ...(commandInput.helpTopic ? { helpTopic: commandInput.helpTopic } : {}),
+        };
+    }
     const options = {};
     const positionals = [];
-    for (let index = 0; index < args.length; index++) {
+    let startIndex = 1;
+    if (commandInput.command === "config") {
+        if (args[1] === "model" && args[2] === "set") {
+            options.configAction = "model-set";
+            startIndex = 3;
+        }
+        else if (args[1] === "provider" && args[2] === "set") {
+            options.configAction = "provider-set";
+            startIndex = 3;
+        }
+    }
+    else if (commandInput.command === "auth") {
+        if (args[1] === "grant" || args[1] === "status" || args[1] === "revoke") {
+            options.authAction = args[1];
+            startIndex = 2;
+        }
+    }
+    else if (commandInput.command === "server") {
+        if (args[1] === "on" ||
+            args[1] === "off" ||
+            args[1] === "status" ||
+            args[1] === "run") {
+            options.serverAction = args[1];
+            startIndex = 2;
+        }
+    }
+    for (let index = startIndex; index < args.length; index++) {
         const arg = args[index];
         if (arg === "--") {
             positionals.push(...args.slice(index + 1));
@@ -51,22 +127,85 @@ export function parseArgs(args) {
             continue;
         }
         if (arg === "--help" || arg === "-h") {
-            options.help = true;
+            return {
+                command: "help",
+                options: {},
+                positionals: [],
+                helpTopic: commandInput.command,
+            };
+        }
+        else if (arg === "--version") {
+            throw new Error(`${arg} must be used without a command`);
+        }
+        else if (isLongOptionWithValue(arg, "--mode")) {
+            options.mode = parseClientMode(valueFromLongOption(arg));
+        }
+        else if (arg === "--mode") {
+            options.mode = parseClientMode(readOptionValue(args, ++index, arg));
+        }
+        else if (arg === "--force-direct") {
+            options.forceDirect = true;
+        }
+        else if (isLongOptionWithValue(arg, "--mcp-toolset")) {
+            options.mcpToolset = parseMcpToolset(valueFromLongOption(arg));
+        }
+        else if (arg === "--mcp-toolset") {
+            options.mcpToolset = parseMcpToolset(readOptionValue(args, ++index, arg));
+        }
+        else if (isLongOptionWithValue(arg, "--listen")) {
+            options.listen = valueFromLongOption(arg);
+        }
+        else if (arg === "--listen") {
+            options.listen = readOptionValue(args, ++index, arg);
+        }
+        else if (isLongOptionWithValue(arg, "--token-file")) {
+            options.serverTokenFile = valueFromLongOption(arg);
+        }
+        else if (arg === "--token-file") {
+            options.serverTokenFile = readOptionValue(args, ++index, arg);
+        }
+        else if (isLongOptionWithValue(arg, "--target")) {
+            options.installTargets = appendInstallTargets(options.installTargets, valueFromLongOption(arg));
         }
-        else if (arg === "--version" || arg === "-v") {
-            options.version = true;
+        else if (arg === "--target") {
+            options.installTargets = appendInstallTargets(options.installTargets, readOptionValue(args, ++index, arg));
         }
-        else if (arg === "--index") {
-            options.index = true;
+        else if (isLongOptionWithValue(arg, "--mcp-tool-timeout")) {
+            options.installMcpToolTimeoutSeconds = parsePositiveInteger(valueFromLongOption(arg), "--mcp-tool-timeout");
         }
-        else if (arg === "--disable-index") {
-            options.disableIndex = true;
+        else if (arg === "--mcp-tool-timeout") {
+            options.installMcpToolTimeoutSeconds = parsePositiveInteger(readOptionValue(args, ++index, arg), arg);
         }
-        else if (arg === "--status") {
-            options.status = true;
+        else if (isLongOptionWithValue(arg, "--mcp-token-env")) {
+            options.installMcpTokenEnv = parseEnvironmentVariable(valueFromLongOption(arg), "--mcp-token-env");
         }
-        else if (arg === "--collections") {
-            options.collections = true;
+        else if (arg === "--mcp-token-env") {
+            options.installMcpTokenEnv = parseEnvironmentVariable(readOptionValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--yes") {
+            options.yes = true;
+        }
+        else if (isLongOptionWithValue(arg, "--allow-remote")) {
+            throw allowRemoteValueError();
+        }
+        else if (arg === "--allow-remote") {
+            const legacyScope = args[index + 1];
+            if (legacyScope === "once" || legacyScope === "workspace") {
+                throw allowRemoteValueError();
+            }
+            options.allowRemote = true;
+        }
+        else if (isLongOptionWithValue(arg, "--capability")) {
+            options.authorizationCapability = parseAuthorizationCapability(valueFromLongOption(arg));
+        }
+        else if (arg === "--capability") {
+            options.authorizationCapability = parseAuthorizationCapability(readOptionValue(args, ++index, arg));
+        }
+        else if (isLongOptionWithValue(arg, "--scope")) {
+            options.authorizationScope = parseAuthorizationScope(valueFromLongOption(arg));
+        }
+        else if (arg === "--scope") {
+            options.authorizationScope = parseAuthorizationScope(readOptionValue(args, ++index, arg));
         }
         else if (arg === "--rg") {
             options.rg = true;
@@ -80,6 +219,9 @@ export function parseArgs(args) {
         else if (arg === "--human") {
             options.human = true;
         }
+        else if (arg === "--check-ready") {
+            options.checkReady = true;
+        }
         else if (isLongOptionWithValue(arg, "--preview")) {
             options.preview = parsePreviewMode(valueFromLongOption(arg));
         }
@@ -95,21 +237,27 @@ export function parseArgs(args) {
         else if (arg === "--rebuild") {
             options.rebuild = true;
         }
+        else if (arg === "--drop") {
+            options.drop = true;
+        }
+        else if (arg === "--force") {
+            options.force = true;
+        }
         else if (arg === "--reset-paths") {
             options.resetPaths = true;
         }
-        else if (arg === "--no-fallback") {
-            options.noFallback = true;
+        else if (arg === "--default") {
+            options.defaultModel = true;
+        }
+        else if (isLongOptionWithValue(arg, "--refresh")) {
+            options.refresh = parseQueryRefreshMode(valueFromLongOption(arg));
         }
-        else if (arg === "--no-auto-update") {
-            options.noAutoUpdate = true;
+        else if (arg === "--refresh") {
+            options.refresh = parseQueryRefreshMode(readOptionValue(args, ++index, arg));
         }
         else if (arg === "--prefer-symbol") {
             options.preferSymbol = true;
         }
-        else if (arg === "--collection") {
-            options.collection = readOptionValue(args, ++index, arg);
-        }
         else if (arg === "--home") {
             options.home = readOptionValue(args, ++index, arg);
         }
@@ -119,17 +267,8 @@ export function parseArgs(args) {
         else if (arg === "--model-cache") {
             options.modelCacheDir = readOptionValue(args, ++index, arg);
         }
-        else if (arg === "--gpu") {
-            options.llamaGpu = "auto";
-        }
-        else if (arg === "--no-gpu") {
-            options.llamaGpu = false;
-        }
-        else if (arg === "--llama-gpu") {
-            options.llamaGpu = parseLlamaGpu(readOptionValue(args, ++index, arg));
-        }
-        else if (arg === "--embedding-parallelism") {
-            options.embeddingParallelism = parsePositiveInteger(readOptionValue(args, ++index, arg), arg);
+        else if (arg === "--device") {
+            options.device = parseDevice(readOptionValue(args, ++index, arg));
         }
         else if (arg === "--api-key") {
             options.apiKey = readOptionValue(args, ++index, arg);
@@ -143,57 +282,99 @@ export function parseArgs(args) {
         else if (arg === "--embedding-concurrency") {
             options.embeddingConcurrency = parsePositiveInteger(readOptionValue(args, ++index, arg), arg);
         }
+        else if (isLongOptionWithValue(arg, "--hybrid")) {
+            options.hybridQueries = appendQuery(options.hybridQueries, valueFromLongOption(arg), "--hybrid");
+        }
+        else if (arg === "--hybrid") {
+            options.hybridQueries = appendQuery(options.hybridQueries, readOptionValue(args, ++index, arg), arg);
+        }
+        else if (isLongOptionWithValue(arg, "--fts")) {
+            options.routes = appendRoute(options.routes, "fts", valueFromLongOption(arg), "--fts");
+        }
         else if (arg === "--fts") {
-            const routeValues = readRouteOptionValues(args, index + 1, arg);
-            options.routes = appendRoutes(options.routes, "fts", routeValues.values);
-            index = routeValues.nextIndex - 1;
+            options.routes = appendRoute(options.routes, "fts", readOptionValue(args, ++index, arg), arg);
+        }
+        else if (isLongOptionWithValue(arg, "--vector")) {
+            options.routes = appendRoute(options.routes, "vector", valueFromLongOption(arg), "--vector");
         }
         else if (arg === "--vector") {
-            const routeValues = readRouteOptionValues(args, index + 1, arg);
-            options.routes = appendRoutes(options.routes, "vector", routeValues.values);
-            index = routeValues.nextIndex - 1;
+            options.routes = appendRoute(options.routes, "vector", readOptionValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--fuse") {
+            options.fuse = true;
         }
         else if (arg === "--color") {
             options.color = parseColorMode(readOptionValue(args, ++index, arg));
         }
-        else if (isLongOptionWithValue(arg, "--include")) {
-            options.includePaths = appendPathFilters(options.includePaths, valueFromLongOption(arg));
+        else if (isLongOptionWithValue(arg, "--glob")) {
+            options.globs = appendValue(options.globs, valueFromLongOption(arg), "--glob");
+        }
+        else if (arg === "--glob" || arg === "-g") {
+            options.globs = appendValue(options.globs, readOptionValue(args, ++index, arg), arg);
         }
-        else if (arg === "--include") {
-            options.includePaths = appendPathFilters(options.includePaths, readOptionValue(args, ++index, arg));
+        else if (isLongOptionWithValue(arg, "--iglob")) {
+            options.insensitiveGlobs = appendValue(options.insensitiveGlobs, valueFromLongOption(arg), "--iglob");
         }
-        else if (isLongOptionWithValue(arg, "--exclude")) {
-            options.excludePaths = appendPathFilters(options.excludePaths, valueFromLongOption(arg));
+        else if (arg === "--iglob") {
+            options.insensitiveGlobs = appendValue(options.insensitiveGlobs, readOptionValue(args, ++index, arg), arg);
         }
-        else if (arg === "--exclude") {
-            options.excludePaths = appendPathFilters(options.excludePaths, readOptionValue(args, ++index, arg));
+        else if (isLongOptionWithValue(arg, "--type")) {
+            options.fileTypes = appendValue(options.fileTypes, valueFromLongOption(arg), "--type");
+        }
+        else if (arg === "--type" || arg === "-t") {
+            options.fileTypes = appendValue(options.fileTypes, readOptionValue(args, ++index, arg), arg);
+        }
+        else if (isLongOptionWithValue(arg, "--type-not")) {
+            options.excludedFileTypes = appendValue(options.excludedFileTypes, valueFromLongOption(arg), "--type-not");
+        }
+        else if (arg === "--type-not" || arg === "-T") {
+            options.excludedFileTypes = appendValue(options.excludedFileTypes, readOptionValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--hidden") {
+            options.hidden = true;
+        }
+        else if (arg === "--no-ignore") {
+            options.noIgnore = true;
+        }
+        else if (isLongOptionWithValue(arg, "--ignore-file")) {
+            options.ignoreFiles = appendValue(options.ignoreFiles, valueFromLongOption(arg), "--ignore-file");
+        }
+        else if (arg === "--ignore-file") {
+            options.ignoreFiles = appendValue(options.ignoreFiles, readOptionValue(args, ++index, arg), arg);
+        }
+        else if (isLongOptionWithValue(arg, "--max-depth")) {
+            options.maxDepth = parseNonNegativeInteger(valueFromLongOption(arg), "--max-depth");
+        }
+        else if (arg === "--max-depth") {
+            options.maxDepth = parseNonNegativeInteger(readOptionValue(args, ++index, arg), arg);
+        }
+        else if (isLongOptionWithValue(arg, "--max-filesize")) {
+            options.maxFileSizeBytes = parseByteSize(valueFromLongOption(arg), "--max-filesize");
+        }
+        else if (arg === "--max-filesize") {
+            options.maxFileSizeBytes = parseByteSize(readOptionValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--follow" || arg === "-L") {
+            options.follow = true;
         }
         else if (arg === "--ignore-case") {
-            options.rgOptions = {
-                ...(options.rgOptions ?? {}),
-                ignoreCase: true,
-            };
+            options.rgOptions = appendRgExtraArgs(options.rgOptions, [arg]);
             markRgCompatibilityOption(options, arg);
         }
         else if (arg === "--word-regexp") {
-            options.rgOptions = {
-                ...(options.rgOptions ?? {}),
-                wordRegexp: true,
-            };
+            options.rgOptions = appendRgExtraArgs(options.rgOptions, [arg]);
             markRgCompatibilityOption(options, arg);
         }
         else if (arg === "--fixed-strings") {
-            options.rgOptions = {
-                ...(options.rgOptions ?? {}),
-                fixedStrings: true,
-            };
+            options.rgOptions = appendRgExtraArgs(options.rgOptions, [arg]);
             markRgCompatibilityOption(options, arg);
         }
-        else if (arg === "--hidden") {
-            options.rgOptions = {
-                ...(options.rgOptions ?? {}),
-                hidden: true,
-            };
+        else if (isLongOptionWithValue(arg, "--file")) {
+            options.rgOptions = appendRgPatternFile(options.rgOptions, valueFromLongOption(arg), "--file");
+            markRgCompatibilityOption(options, "--file");
+        }
+        else if (arg === "--file") {
+            options.rgOptions = appendRgPatternFile(options.rgOptions, readOptionValue(args, ++index, arg), arg);
             markRgCompatibilityOption(options, arg);
         }
         else if (isRgFlagWithValue(arg)) {
@@ -215,7 +396,9 @@ export function parseArgs(args) {
             options.rgOptions = appendRgExtraArgs(options.rgOptions, [arg]);
             markRgCompatibilityOption(options, arg);
         }
-        else if (arg === "--recursive" || arg === "--line-number" || arg === "--with-filename") {
+        else if (arg === "--recursive" ||
+            arg === "--line-number" ||
+            arg === "--with-filename") {
             markRgCompatibilityOption(options, arg);
         }
         else if (isLongOptionWithValue(arg, "--regexp")) {
@@ -250,18 +433,6 @@ export function parseArgs(args) {
             options.rgOptions = setRgContext(options.rgOptions, "after", readOptionValue(args, ++index, arg), arg);
             markRgCompatibilityOption(options, arg);
         }
-        else if (isLongOptionWithValue(arg, "--glob")) {
-            appendRgGlobFilter(options, valueFromLongOption(arg));
-            markRgCompatibilityOption(options, "--glob");
-        }
-        else if (arg === "--glob") {
-            appendRgGlobFilter(options, readOptionValue(args, ++index, arg));
-            markRgCompatibilityOption(options, arg);
-        }
-        else if (arg === "-g") {
-            appendRgGlobFilter(options, readOptionValue(args, ++index, arg));
-            markRgCompatibilityOption(options, arg);
-        }
         else if (isManagedRgOutputOption(arg)) {
             throw new Error(`${arg} changes rg output and cannot be used with managed --rg`);
         }
@@ -275,83 +446,357 @@ export function parseArgs(args) {
             options.modifiedBefore = parseModifiedTime(readOptionValue(args, ++index, arg), arg);
         }
         else if (arg === "--symbol-type") {
-            options.symbolTypes = [...(options.symbolTypes ?? []), parseSymbolType(readOptionValue(args, ++index, arg))];
+            options.symbolTypes = [
+                ...(options.symbolTypes ?? []),
+                parseSymbolType(readOptionValue(args, ++index, arg)),
+            ];
         }
         else {
             throw new Error(`Unknown option: ${arg}`);
         }
     }
-    validateCliShape(options);
-    return { options, positionals };
+    validateCliShape(commandInput.command, options, positionals);
+    return { command: commandInput.command, options, positionals };
 }
-function validateCliShape(options) {
-    if (options.index && options.collections) {
-        throw new Error("--index and --collections cannot be used together");
+function parseCommand(args) {
+    const [first, ...rest] = args;
+    if (first === undefined ||
+        first === "help" ||
+        first === "-h" ||
+        first === "--help") {
+        if (first !== "help" && rest.length > 0) {
+            throw new Error(`${first} does not accept arguments`);
+        }
+        if (first === "help" && rest.length > 1) {
+            throw new Error("zg help accepts at most one command or topic");
+        }
+        return {
+            command: "help",
+            ...(first === "help" && rest[0] ? { helpTopic: rest[0] } : {}),
+        };
     }
-    if (options.disableIndex && options.collections) {
-        throw new Error("--disable-index and --collections cannot be used together");
+    if (first === "version" || first === "-v" || first === "--version") {
+        const acceptsVersionFlag = first === "version" &&
+            rest.length === 1 &&
+            (rest[0] === "-v" || rest[0] === "--version");
+        if (rest.length > 0 && !acceptsVersionFlag) {
+            throw new Error(`${first} does not accept arguments`);
+        }
+        return { command: "version" };
     }
-    if (options.disableIndex && options.index) {
-        throw new Error("--disable-index and --index cannot be used together");
+    if (first === "query" ||
+        first === "index" ||
+        first === "status" ||
+        first === "install" ||
+        first === "uninstall" ||
+        first === "config" ||
+        first === "auth" ||
+        first === "server") {
+        return { command: first };
     }
-    if (options.disableIndex && options.status) {
-        throw new Error("--disable-index and --status cannot be used together");
+    if (first === "serve") {
+        throw new Error("zg serve has been removed; use zg server on and Streamable HTTP MCP");
     }
-    if (options.status && options.collections) {
-        throw new Error("--status and --collections cannot be used together");
+    throw new Error(`Unknown command: ${first}`);
+}
+function validateCliShape(command, options, positionals) {
+    if (command === "auth") {
+        if (!options.authAction) {
+            throw new Error("zg auth requires grant, status, or revoke");
+        }
+        if (positionals.length > 1) {
+            throw new Error(`zg auth ${options.authAction} accepts at most one root`);
+        }
+        if (options.authAction !== "grant" &&
+            (options.authorizationCapability || options.authorizationScope)) {
+            throw new Error(`--capability and --scope can only be used with zg auth grant`);
+        }
     }
-    if (options.status && options.index) {
-        throw new Error("--status and --index cannot be used together");
+    else if (options.authorizationCapability || options.authorizationScope) {
+        throw new Error("--capability and --scope can only be used with zg auth");
     }
-    if (options.status && options.collection) {
-        throw new Error("--status does not accept --collection; use --collections info <name>");
+    if (options.allowRemote && command !== "query" && command !== "index") {
+        throw new Error("--allow-remote can only be used with query or index commands");
     }
-    if (options.index && options.collection) {
-        throw new Error("--index does not accept --collection");
+    const queryOnly = firstEnabledOption([
+        [options.rg, "--rg"],
+        [options.hybridQueries?.length, "--hybrid"],
+        [options.routes?.length, "--fts/--vector"],
+        [options.fuse, "--fuse"],
+        [options.debug, "--debug"],
+        [options.trace, "--trace"],
+        [options.human, "--human"],
+        [options.preview, "--preview"],
+        [options.limit, "--limit"],
+        [options.refresh, "--refresh"],
+        [options.preferSymbol, "--prefer-symbol"],
+        [options.symbolTypes?.length, "--symbol-type"],
+        [options.modifiedAfter, "--modified-after"],
+        [options.modifiedBefore, "--modified-before"],
+        [options.rgCompatibilityOptions?.length, "ripgrep options"],
+    ]);
+    if (command !== "query" && queryOnly) {
+        throw new Error(`${queryOnly} can only be used with zg query`);
     }
-    if (options.disableIndex && options.collection) {
-        throw new Error("--disable-index does not accept --collection");
+    const sharedSelection = firstEnabledOption([
+        [options.globs?.length, "--glob"],
+        [options.insensitiveGlobs?.length, "--iglob"],
+        [options.fileTypes?.length, "--type"],
+        [options.excludedFileTypes?.length, "--type-not"],
+    ]);
+    if (sharedSelection && command !== "query" && command !== "index") {
+        throw new Error(`${sharedSelection} can only be used with query or index commands`);
     }
-    if (options.rg && options.collection) {
-        throw new Error("--rg does not accept --collection");
+    const discoveryOption = firstEnabledOption([
+        [options.hidden, "--hidden"],
+        [options.noIgnore, "--no-ignore"],
+        [options.ignoreFiles?.length, "--ignore-file"],
+        [options.maxDepth, "--max-depth"],
+        [options.maxFileSizeBytes, "--max-filesize"],
+        [options.follow, "--follow"],
+    ]);
+    if (discoveryOption &&
+        command !== "index" &&
+        !(command === "query" && options.rg)) {
+        throw new Error(`${discoveryOption} can only be used with index commands or zg query --rg`);
     }
-    if (options.collections && options.collection) {
-        throw new Error("--collections and --collection cannot be used together");
+    if (command === "config") {
+        if (!options.configAction) {
+            throw new Error("zg config requires provider set or model set");
+        }
+        const unsupported = firstEnabledOption([
+            [options.installTargets?.length, "--target"],
+            [options.installMcpToolTimeoutSeconds, "--mcp-tool-timeout"],
+            [options.installMcpTokenEnv, "--mcp-token-env"],
+            [options.yes, "--yes"],
+            [options.rg, "--rg"],
+            [options.home, "--home"],
+            [options.embedding, "--embedding"],
+            [
+                options.configAction === "model-set" ? options.apiKey : undefined,
+                "--api-key",
+            ],
+            [
+                options.configAction === "provider-set" ? options.endpoint : undefined,
+                "--endpoint",
+            ],
+            [
+                options.configAction === "provider-set" ? options.device : undefined,
+                "--device",
+            ],
+            [
+                options.configAction === "provider-set"
+                    ? options.defaultModel
+                    : undefined,
+                "--default",
+            ],
+            [options.mode, "--mode"],
+            [options.listen, "--listen"],
+            [options.serverTokenFile, "--token-file"],
+        ]);
+        if (unsupported) {
+            throw new Error(`zg config ${options.configAction === "model-set" ? "model" : "provider"} set does not accept ${unsupported}`);
+        }
     }
-    if ((options.index || options.disableIndex || options.status || options.collections) && hasExplicitRoutes(options)) {
-        throw new Error("--fts and --vector can only be used with query commands");
+    else if (options.defaultModel) {
+        throw new Error("--default can only be used with zg config model set");
     }
-    if ((options.index || options.disableIndex || options.status || options.collections) && options.rg) {
-        throw new Error("--rg can only be used with query commands");
+    if (command === "server") {
+        if (!options.serverAction) {
+            throw new Error("zg server requires on, off, status, or run");
+        }
+        if (options.listen !== undefined &&
+            options.serverAction !== "run" &&
+            options.serverAction !== "on") {
+            throw new Error("--listen can only be used with zg server on or run");
+        }
+        if (options.serverTokenFile !== undefined &&
+            options.serverAction === "status") {
+            throw new Error("--token-file cannot be used with zg server status");
+        }
+        if (options.mcpToolset !== undefined &&
+            options.serverAction !== "on" &&
+            options.serverAction !== "run") {
+            throw new Error("--mcp-toolset can only be used with zg server on or run");
+        }
+    }
+    else if (options.mcpToolset !== undefined) {
+        throw new Error("--mcp-toolset can only be used with zg server on or run");
     }
-    if ((options.index || options.disableIndex || options.status || options.collections) && options.preview) {
-        throw new Error("--preview can only be used with query commands");
+    if (options.rg &&
+        (hasExplicitRoutes(options) || options.hybridQueries?.length)) {
+        throw new Error("--rg cannot be combined with --hybrid, --fts, or --vector");
     }
-    if ((options.index || options.disableIndex || options.status || options.collections) && options.noAutoUpdate) {
-        throw new Error("--no-auto-update can only be used with query commands");
+    if (options.rg && options.fuse) {
+        throw new Error("--rg cannot be combined with --fuse");
     }
-    if (options.rg && hasExplicitRoutes(options)) {
-        throw new Error("--rg cannot be combined with --fts or --vector");
+    if (options.forceDirect && options.mode !== "direct") {
+        throw new Error("--force-direct requires --mode direct");
     }
     if (options.rg && options.preview) {
         throw new Error("--preview is not supported with --rg; use -A/-B/-C for rg context");
     }
-    if (options.rg && options.noFallback) {
-        throw new Error("--rg cannot be combined with --no-fallback");
-    }
     if (options.rg && options.trace) {
         throw new Error("--rg cannot be combined with --trace");
     }
     if (options.rg && (options.preferSymbol || options.symbolTypes?.length)) {
         throw new Error("--rg cannot be combined with indexed symbol options");
     }
-    if (options.resetPaths && !options.index && !options.collections) {
-        throw new Error("--reset-paths can only be used with --index or --collections index");
+    if (options.rg &&
+        (options.refresh || options.embeddingConcurrency !== undefined)) {
+        throw new Error("--rg cannot be combined with indexed refresh options");
     }
     if (!options.rg && (options.rgCompatibilityOptions?.length ?? 0) > 0) {
         const [option] = options.rgCompatibilityOptions;
         throw new Error(`${option} can only be used with --rg`);
     }
+    if (options.mode !== undefined &&
+        command !== "query" &&
+        command !== "index" &&
+        command !== "status") {
+        throw new Error("--mode can only be used with query, index, or status");
+    }
+    if (options.checkReady &&
+        command !== "status" &&
+        !(command === "server" && options.serverAction === "status")) {
+        throw new Error("--check-ready can only be used with zg status or zg server status");
+    }
+    if (options.listen !== undefined && command !== "server") {
+        throw new Error("--listen can only be used with zg server on or run");
+    }
+    if (options.serverTokenFile !== undefined && command !== "server") {
+        throw new Error("--token-file can only be used with zg server");
+    }
+    if (options.installTargets?.length &&
+        command !== "install" &&
+        command !== "uninstall") {
+        throw new Error("--target can only be used with zg install or zg uninstall");
+    }
+    if (options.installMcpToolTimeoutSeconds !== undefined &&
+        command !== "install") {
+        throw new Error("--mcp-tool-timeout can only be used with zg install");
+    }
+    if (options.installMcpTokenEnv !== undefined && command !== "install") {
+        throw new Error("--mcp-token-env can only be used with zg install");
+    }
+    if (options.force && command !== "install") {
+        throw new Error("--force can only be used with zg install");
+    }
+    if (command === "install" || command === "uninstall") {
+        const unsupported = firstEnabledOption([
+            [options.color, "--color"],
+            [options.home, "--home"],
+            [options.embedding, "--embedding"],
+            [options.modelCacheDir, "--model-cache"],
+            [options.device, "--device"],
+            [options.apiKey, "--api-key"],
+            [options.endpoint, "--endpoint"],
+            [options.rebuild, "--rebuild"],
+            [options.drop, "--drop"],
+            [options.resetPaths, "--reset-paths"],
+            [options.globs?.length, "--glob"],
+            [options.insensitiveGlobs?.length, "--iglob"],
+            [options.fileTypes?.length, "--type"],
+            [options.excludedFileTypes?.length, "--type-not"],
+            [options.hidden, "--hidden"],
+            [options.noIgnore, "--no-ignore"],
+            [options.ignoreFiles?.length, "--ignore-file"],
+            [options.maxDepth, "--max-depth"],
+            [options.maxFileSizeBytes, "--max-filesize"],
+            [options.follow, "--follow"],
+            [options.embeddingConcurrency, "--embedding-concurrency"],
+        ]);
+        if (unsupported) {
+            throw new Error(`${unsupported} is not supported with zg ${command}`);
+        }
+    }
+    if (options.yes &&
+        command !== "install" &&
+        command !== "uninstall" &&
+        !(command === "index" && options.drop)) {
+        throw new Error("--yes is only valid for install, uninstall, or index --drop");
+    }
+    if (options.drop && command !== "index") {
+        throw new Error("--drop can only be used with zg index");
+    }
+    if (options.rebuild && command !== "index") {
+        throw new Error("--rebuild can only be used with zg index");
+    }
+    if (options.resetPaths && command !== "index") {
+        throw new Error("--reset-paths can only be used with zg index");
+    }
+    if (options.drop &&
+        (options.rebuild ||
+            options.resetPaths ||
+            options.home ||
+            options.embedding ||
+            options.modelCacheDir ||
+            options.device !== undefined ||
+            options.apiKey ||
+            options.endpoint ||
+            options.globs?.length ||
+            options.insensitiveGlobs?.length ||
+            options.fileTypes?.length ||
+            options.excludedFileTypes?.length ||
+            options.hidden ||
+            options.noIgnore ||
+            options.ignoreFiles?.length ||
+            options.maxDepth !== undefined ||
+            options.maxFileSizeBytes !== undefined ||
+            options.follow ||
+            options.embeddingConcurrency)) {
+        throw new Error("zg index --drop cannot be combined with indexing options");
+    }
+    if (command === "query") {
+        const unsupported = firstEnabledOption([
+            [options.embedding, "--embedding"],
+            [options.endpoint, "--endpoint"],
+            [options.embeddingConcurrency, "--embedding-concurrency"],
+        ]);
+        if (unsupported) {
+            throw new Error(`${unsupported} is not supported with zg query`);
+        }
+    }
+    if (command === "query" && !options.rg) {
+        const queryCount = positionals.length +
+            (options.hybridQueries?.length ?? 0) +
+            (options.routes?.length ?? 0);
+        if (queryCount === 0) {
+            throw new Error("zg query requires a query or --hybrid/--fts/--vector route");
+        }
+    }
+}
+function firstEnabledOption(candidates) {
+    return candidates.find(([value]) => Array.isArray(value) ? value.length > 0 : value !== undefined)?.[1];
+}
+function parseClientMode(value) {
+    if (value === "direct" || value === "server" || value === "auto")
+        return value;
+    throw new Error("--mode must be direct, server, or auto");
+}
+function parseQueryRefreshMode(value) {
+    if (value === "background" || value === "wait" || value === "off") {
+        return value;
+    }
+    throw new Error("--refresh must be background, wait, or off");
+}
+function allowRemoteValueError() {
+    return new Error([
+        "--allow-remote does not accept a value.",
+        "It authorizes Remote Embedding for the current command only.",
+        "For persistent authorization, use:",
+        "  zg auth grant --capability embedding --scope workspace",
+    ].join("\n"));
+}
+function parseAuthorizationCapability(value) {
+    if (value === "embedding")
+        return value;
+    throw new Error("--capability currently supports only embedding");
+}
+function parseAuthorizationScope(value) {
+    if (value === "workspace")
+        return value;
+    throw new Error("zg auth supports only workspace scope");
 }
 function readOptionValue(args, index, option) {
     const value = args[index];
@@ -380,9 +825,7 @@ function isManagedRgOutputOption(arg) {
     return MANAGED_RG_OUTPUT_OPTIONS.has(option);
 }
 function isShortRgOptionGroup(arg) {
-    return /^-[A-Za-z].*$/.test(arg)
-        && arg !== "-h"
-        && arg !== "-v";
+    return /^-[A-Za-z].*$/.test(arg) && arg !== "-h";
 }
 function parseShortRgOptionGroup(args, index, options) {
     const arg = args[index];
@@ -395,35 +838,32 @@ function parseShortRgOptionGroup(args, index, options) {
                 markRgCompatibilityOption(options, flag);
                 break;
             case "F":
-                options.rgOptions = {
-                    ...(options.rgOptions ?? {}),
-                    fixedStrings: true,
-                };
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [flag]);
                 markRgCompatibilityOption(options, flag);
                 break;
             case "i":
-                options.rgOptions = {
-                    ...(options.rgOptions ?? {}),
-                    ignoreCase: true,
-                };
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [flag]);
                 markRgCompatibilityOption(options, flag);
                 break;
             case "w":
-                options.rgOptions = {
-                    ...(options.rgOptions ?? {}),
-                    wordRegexp: true,
-                };
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [flag]);
                 markRgCompatibilityOption(options, flag);
                 break;
             case "P":
             case "S":
             case "s":
+            case "a":
             case "u":
             case "U":
+            case "v":
+            case "x":
             case "z":
                 options.rgOptions = appendRgExtraArgs(options.rgOptions, [flag]);
                 markRgCompatibilityOption(options, flag);
                 break;
+            case "L":
+                options.follow = true;
+                break;
             case "e": {
                 const value = readShortOptionValue(args, index, offset, arg, flag);
                 options.rgOptions = appendRgPattern(options.rgOptions, value.value);
@@ -432,15 +872,52 @@ function parseShortRgOptionGroup(args, index, options) {
             }
             case "g": {
                 const value = readShortOptionValue(args, index, offset, arg, flag);
-                appendRgGlobFilter(options, value.value);
+                options.globs = appendValue(options.globs, value.value, flag);
+                return value.nextIndex;
+            }
+            case "E": {
+                const value = readShortOptionValue(args, index, offset, arg, flag);
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [
+                    flag,
+                    value.value,
+                ]);
                 markRgCompatibilityOption(options, flag);
                 return value.nextIndex;
             }
             case "t":
-            case "T":
-            case "E": {
+            case "T": {
+                const value = readShortOptionValue(args, index, offset, arg, flag);
+                if (option === "t") {
+                    options.fileTypes = appendValue(options.fileTypes, value.value, flag);
+                }
+                else {
+                    options.excludedFileTypes = appendValue(options.excludedFileTypes, value.value, flag);
+                }
+                return value.nextIndex;
+            }
+            case "f": {
+                const value = readShortOptionValue(args, index, offset, arg, flag);
+                options.rgOptions = appendRgPatternFile(options.rgOptions, value.value, flag);
+                markRgCompatibilityOption(options, flag);
+                return value.nextIndex;
+            }
+            case "m": {
+                const value = readShortOptionValue(args, index, offset, arg, flag);
+                parseNonNegativeInteger(value.value, flag);
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [
+                    flag,
+                    value.value,
+                ]);
+                markRgCompatibilityOption(options, flag);
+                return value.nextIndex;
+            }
+            case "j": {
                 const value = readShortOptionValue(args, index, offset, arg, flag);
-                options.rgOptions = appendRgExtraArgs(options.rgOptions, [flag, value.value]);
+                parseNonNegativeInteger(value.value, flag);
+                options.rgOptions = appendRgExtraArgs(options.rgOptions, [
+                    flag,
+                    value.value,
+                ]);
                 markRgCompatibilityOption(options, flag);
                 return value.nextIndex;
             }
@@ -448,11 +925,7 @@ function parseShortRgOptionGroup(args, index, options) {
             case "B":
             case "C": {
                 const value = readShortOptionValue(args, index, offset, arg, flag);
-                const direction = option === "A"
-                    ? "after"
-                    : option === "B"
-                        ? "before"
-                        : "both";
+                const direction = option === "A" ? "after" : option === "B" ? "before" : "both";
                 options.rgOptions = setRgContext(options.rgOptions, direction, value.value, flag);
                 markRgCompatibilityOption(options, flag);
                 return value.nextIndex;
@@ -488,12 +961,25 @@ function markRgCompatibilityOption(options, option) {
 function appendRgPattern(existing, value) {
     return {
         ...(existing ?? {}),
-        patterns: [
-            ...(existing?.patterns ?? []),
-            value,
-        ],
+        patterns: [...(existing?.patterns ?? []), value],
     };
 }
+function appendRgPatternFile(existing, value, option) {
+    return {
+        ...(existing ?? {}),
+        patternFiles: appendValue(existing?.patternFiles, value, option),
+    };
+}
+function appendInstallTargets(existing, value) {
+    const targets = value
+        .split(/[,\s]+/)
+        .map((target) => target.trim())
+        .filter((target) => target.length > 0);
+    if (targets.length === 0) {
+        throw new Error("--target requires at least one agent name");
+    }
+    return [...(existing ?? []), ...targets];
+}
 function setRgContext(existing, direction, value, option) {
     const parsed = parseNonNegativeInteger(value, option);
     return {
@@ -509,47 +995,53 @@ function setRgContext(existing, direction, value, option) {
 function appendRgExtraArgs(existing, args) {
     return {
         ...(existing ?? {}),
-        extraArgs: [
-            ...(existing?.extraArgs ?? []),
-            ...args,
-        ],
+        extraArgs: [...(existing?.extraArgs ?? []), ...args],
     };
 }
-function appendRgGlobFilter(options, value) {
-    if (value.startsWith("!")) {
-        options.excludePaths = appendPathFilters(options.excludePaths, value.slice(1));
-        return;
+function parsePositiveInteger(value, option) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${option} requires a positive integer`);
     }
-    options.includePaths = appendPathFilters(options.includePaths, value);
-}
-function readRouteOptionValues(args, index, option) {
-    const values = [];
-    let nextIndex = index;
-    while (nextIndex < args.length) {
-        const value = args[nextIndex];
-        if (value.startsWith("-") && value !== "-") {
-            break;
-        }
-        if (value.trim().length > 0) {
-            values.push(value);
-        }
-        nextIndex++;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error(`${option} requires a positive integer`);
     }
-    if (values.length === 0) {
-        throw new Error(`${option} requires at least one query`);
+    return parsed;
+}
+function parseEnvironmentVariable(value, option) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+        throw new Error(`${option} requires a valid environment variable name`);
     }
-    return { values, nextIndex };
+    return value;
 }
-function parsePositiveInteger(value, option) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isInteger(parsed) || parsed < 1) {
-        throw new Error(`${option} requires a positive integer`);
+function parseByteSize(value, option) {
+    const match = value.trim().match(/^(\d+)([KMGT])?$/i);
+    if (!match) {
+        throw new Error(`${option} requires bytes or an integer K/M/G/T size`);
     }
-    return parsed;
+    const amount = Number.parseInt(match[1], 10);
+    const suffix = match[2]?.toUpperCase();
+    const multiplier = suffix === "K"
+        ? 1024
+        : suffix === "M"
+            ? 1024 ** 2
+            : suffix === "G"
+                ? 1024 ** 3
+                : suffix === "T"
+                    ? 1024 ** 4
+                    : 1;
+    const bytes = amount * multiplier;
+    if (!Number.isSafeInteger(bytes)) {
+        throw new Error(`${option} is too large`);
+    }
+    return bytes;
 }
 function parseNonNegativeInteger(value, option) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isInteger(parsed) || parsed < 0) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${option} requires a non-negative integer`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
         throw new Error(`${option} requires a non-negative integer`);
     }
     return parsed;
@@ -566,24 +1058,33 @@ function parsePreviewMode(value) {
     }
     throw new Error(`Unsupported preview mode: ${value}`);
 }
-function parseLlamaGpu(value) {
+export function parseDevice(value) {
     const normalized = value.trim().toLowerCase();
-    if (normalized === "auto" || normalized === "metal" || normalized === "vulkan" || normalized === "cuda") {
+    if (normalized === "auto" ||
+        normalized === "cpu" ||
+        normalized === "metal" ||
+        normalized === "vulkan" ||
+        normalized === "cuda") {
         return normalized;
     }
-    if (["false", "off", "none", "disable", "disabled", "0"].includes(normalized)) {
-        return false;
-    }
-    throw new Error(`Unsupported llama GPU mode: ${value}`);
+    throw new Error(`Unsupported device: ${value}`);
 }
 function hasExplicitRoutes(options) {
     return (options.routes?.length ?? 0) > 0;
 }
-function appendRoutes(existing, mode, queries) {
-    return [
-        ...(existing ?? []),
-        ...queries.map((query) => ({ mode, query })),
-    ];
+function appendRoute(existing, mode, query, option) {
+    const normalized = query.trim();
+    if (!normalized) {
+        throw new Error(`${option} requires a non-empty query`);
+    }
+    return [...(existing ?? []), { mode, query: normalized }];
+}
+function appendQuery(existing, query, option) {
+    const normalized = query.trim();
+    if (!normalized) {
+        throw new Error(`${option} requires a non-empty query`);
+    }
+    return [...(existing ?? []), normalized];
 }
 function parseSymbolType(value) {
     if (VALID_SYMBOL_TYPES.has(value)) {
@@ -591,14 +1092,61 @@ function parseSymbolType(value) {
     }
     throw new Error(`Unsupported symbol type: ${value}`);
 }
-function appendPathFilters(existing, value) {
-    const values = value
-        .split(",")
-        .map((item) => item.trim())
-        .filter((item) => item.length > 0);
-    return [...(existing ?? []), ...values];
+export function splitPathFilters(value) {
+    const filters = [];
+    let start = 0;
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let escaped = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === "[") {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === "]" && bracketDepth > 0) {
+            bracketDepth -= 1;
+            continue;
+        }
+        if (bracketDepth === 0 && character === "{") {
+            braceDepth += 1;
+            continue;
+        }
+        if (bracketDepth === 0 && character === "}" && braceDepth > 0) {
+            braceDepth -= 1;
+            continue;
+        }
+        if (character !== "," || braceDepth > 0 || bracketDepth > 0) {
+            continue;
+        }
+        const filter = value.slice(start, index).trim();
+        if (filter.length > 0) {
+            filters.push(filter);
+        }
+        start = index + 1;
+    }
+    const finalFilter = value.slice(start).trim();
+    if (finalFilter.length > 0) {
+        filters.push(finalFilter);
+    }
+    return filters;
+}
+function appendValue(existing, value, option) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error(`${option} requires a non-empty value`);
+    }
+    return [...(existing ?? []), normalized];
 }
-function parseModifiedTime(value, option) {
+export function parseModifiedTime(value, option) {
     if (/^\d+$/.test(value)) {
         const parsed = Number.parseInt(value, 10);
         if (Number.isSafeInteger(parsed) && parsed >= 0) {
@@ -611,9 +1159,9 @@ function parseModifiedTime(value, option) {
         const month = Number.parseInt(dateOnly[2], 10);
         const day = Number.parseInt(dateOnly[3], 10);
         const date = new Date(year, month - 1, day);
-        if (date.getFullYear() === year
-            && date.getMonth() === month - 1
-            && date.getDate() === day) {
+        if (date.getFullYear() === year &&
+            date.getMonth() === month - 1 &&
+            date.getDate() === day) {
             return date.getTime();
         }
     }