postgresai 0.15.0-dev.6 → 0.15.0-dev.9

package/dist/bin/postgres-ai.js

@@ -6,25 +6,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -80,7 +98,7 @@ var require_argument = __commonJS((exports) => {
           this._name = name;
           break;
       }
-      if (this._name.length > 3 && this._name.slice(-3) === "...") {
+      if (this._name.endsWith("...")) {
         this.variadic = true;
         this._name = this._name.slice(0, -3);
       }
@@ -88,11 +106,12 @@ var require_argument = __commonJS((exports) => {
     name() {
       return this._name;
     }
-    _concatValue(value, previous) {
+    _collectValue(value, previous) {
       if (previous === this.defaultValue || !Array.isArray(previous)) {
         return [value];
       }
-      return previous.concat(value);
+      previous.push(value);
+      return previous;
     }
     default(value, description) {
       this.defaultValue = value;
@@ -110,7 +129,7 @@ var require_argument = __commonJS((exports) => {
           throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(", ")}.`);
         }
         if (this.variadic) {
-          return this._concatValue(arg, previous);
+          return this._collectValue(arg, previous);
         }
         return arg;
       };
@@ -140,10 +159,14 @@ var require_help = __commonJS((exports) => {
   class Help {
     constructor() {
       this.helpWidth = undefined;
+      this.minWidthToWrap = 40;
       this.sortSubcommands = false;
       this.sortOptions = false;
       this.showGlobalOptions = false;
     }
+    prepareContext(contextOptions) {
+      this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
+    }
     visibleCommands(cmd) {
       const visibleCommands = cmd.commands.filter((cmd2) => !cmd2._hidden);
       const helpCommand = cmd._getHelpCommand();
@@ -218,22 +241,22 @@ var require_help = __commonJS((exports) => {
     }
     longestSubcommandTermLength(cmd, helper) {
       return helper.visibleCommands(cmd).reduce((max, command) => {
-        return Math.max(max, helper.subcommandTerm(command).length);
+        return Math.max(max, this.displayWidth(helper.styleSubcommandTerm(helper.subcommandTerm(command))));
       }, 0);
     }
     longestOptionTermLength(cmd, helper) {
       return helper.visibleOptions(cmd).reduce((max, option) => {
-        return Math.max(max, helper.optionTerm(option).length);
+        return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
       }, 0);
     }
     longestGlobalOptionTermLength(cmd, helper) {
       return helper.visibleGlobalOptions(cmd).reduce((max, option) => {
-        return Math.max(max, helper.optionTerm(option).length);
+        return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
       }, 0);
     }
     longestArgumentTermLength(cmd, helper) {
       return helper.visibleArguments(cmd).reduce((max, argument) => {
-        return Math.max(max, helper.argumentTerm(argument).length);
+        return Math.max(max, this.displayWidth(helper.styleArgumentTerm(helper.argumentTerm(argument))));
       }, 0);
     }
     commandUsage(cmd) {
@@ -271,7 +294,11 @@ var require_help = __commonJS((exports) => {
         extraInfo.push(`env: ${option.envVar}`);
       }
       if (extraInfo.length > 0) {
-        return `${option.description} (${extraInfo.join(", ")})`;
+        const extraDescription = `(${extraInfo.join(", ")})`;
+        if (option.description) {
+          return `${option.description} ${extraDescription}`;
+        }
+        return extraDescription;
       }
       return option.description;
     }
@@ -284,102 +311,202 @@ var require_help = __commonJS((exports) => {
         extraInfo.push(`default: ${argument.defaultValueDescription || JSON.stringify(argument.defaultValue)}`);
       }
       if (extraInfo.length > 0) {
-        const extraDescripton = `(${extraInfo.join(", ")})`;
+        const extraDescription = `(${extraInfo.join(", ")})`;
         if (argument.description) {
-          return `${argument.description} ${extraDescripton}`;
+          return `${argument.description} ${extraDescription}`;
         }
-        return extraDescripton;
+        return extraDescription;
       }
       return argument.description;
     }
+    formatItemList(heading, items, helper) {
+      if (items.length === 0)
+        return [];
+      return [helper.styleTitle(heading), ...items, ""];
+    }
+    groupItems(unsortedItems, visibleItems, getGroup) {
+      const result = new Map;
+      unsortedItems.forEach((item) => {
+        const group = getGroup(item);
+        if (!result.has(group))
+          result.set(group, []);
+      });
+      visibleItems.forEach((item) => {
+        const group = getGroup(item);
+        if (!result.has(group)) {
+          result.set(group, []);
+        }
+        result.get(group).push(item);
+      });
+      return result;
+    }
     formatHelp(cmd, helper) {
       const termWidth = helper.padWidth(cmd, helper);
-      const helpWidth = helper.helpWidth || 80;
-      const itemIndentWidth = 2;
-      const itemSeparatorWidth = 2;
-      function formatItem(term, description) {
-        if (description) {
-          const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`;
-          return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth);
-        }
-        return term;
-      }
-      function formatList(textArray) {
-        return textArray.join(`
-`).replace(/^/gm, " ".repeat(itemIndentWidth));
+      const helpWidth = helper.helpWidth ?? 80;
+      function callFormatItem(term, description) {
+        return helper.formatItem(term, termWidth, description, helper);
       }
-      let output = [`Usage: ${helper.commandUsage(cmd)}`, ""];
+      let output = [
+        `${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(cmd))}`,
+        ""
+      ];
       const commandDescription = helper.commandDescription(cmd);
       if (commandDescription.length > 0) {
         output = output.concat([
-          helper.wrap(commandDescription, helpWidth, 0),
+          helper.boxWrap(helper.styleCommandDescription(commandDescription), helpWidth),
           ""
         ]);
       }
       const argumentList = helper.visibleArguments(cmd).map((argument) => {
-        return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument));
+        return callFormatItem(helper.styleArgumentTerm(helper.argumentTerm(argument)), helper.styleArgumentDescription(helper.argumentDescription(argument)));
       });
-      if (argumentList.length > 0) {
-        output = output.concat(["Arguments:", formatList(argumentList), ""]);
-      }
-      const optionList = helper.visibleOptions(cmd).map((option) => {
-        return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+      output = output.concat(this.formatItemList("Arguments:", argumentList, helper));
+      const optionGroups = this.groupItems(cmd.options, helper.visibleOptions(cmd), (option) => option.helpGroupHeading ?? "Options:");
+      optionGroups.forEach((options, group) => {
+        const optionList = options.map((option) => {
+          return callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option)));
+        });
+        output = output.concat(this.formatItemList(group, optionList, helper));
       });
-      if (optionList.length > 0) {
-        output = output.concat(["Options:", formatList(optionList), ""]);
-      }
-      if (this.showGlobalOptions) {
+      if (helper.showGlobalOptions) {
         const globalOptionList = helper.visibleGlobalOptions(cmd).map((option) => {
-          return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+          return callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option)));
         });
-        if (globalOptionList.length > 0) {
-          output = output.concat([
-            "Global Options:",
-            formatList(globalOptionList),
-            ""
-          ]);
-        }
+        output = output.concat(this.formatItemList("Global Options:", globalOptionList, helper));
       }
-      const commandList = helper.visibleCommands(cmd).map((cmd2) => {
-        return formatItem(helper.subcommandTerm(cmd2), helper.subcommandDescription(cmd2));
+      const commandGroups = this.groupItems(cmd.commands, helper.visibleCommands(cmd), (sub) => sub.helpGroup() || "Commands:");
+      commandGroups.forEach((commands, group) => {
+        const commandList = commands.map((sub) => {
+          return callFormatItem(helper.styleSubcommandTerm(helper.subcommandTerm(sub)), helper.styleSubcommandDescription(helper.subcommandDescription(sub)));
+        });
+        output = output.concat(this.formatItemList(group, commandList, helper));
       });
-      if (commandList.length > 0) {
-        output = output.concat(["Commands:", formatList(commandList), ""]);
-      }
       return output.join(`
 `);
     }
+    displayWidth(str) {
+      return stripColor(str).length;
+    }
+    styleTitle(str) {
+      return str;
+    }
+    styleUsage(str) {
+      return str.split(" ").map((word) => {
+        if (word === "[options]")
+          return this.styleOptionText(word);
+        if (word === "[command]")
+          return this.styleSubcommandText(word);
+        if (word[0] === "[" || word[0] === "<")
+          return this.styleArgumentText(word);
+        return this.styleCommandText(word);
+      }).join(" ");
+    }
+    styleCommandDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleOptionDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleSubcommandDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleArgumentDescription(str) {
+      return this.styleDescriptionText(str);
+    }
+    styleDescriptionText(str) {
+      return str;
+    }
+    styleOptionTerm(str) {
+      return this.styleOptionText(str);
+    }
+    styleSubcommandTerm(str) {
+      return str.split(" ").map((word) => {
+        if (word === "[options]")
+          return this.styleOptionText(word);
+        if (word[0] === "[" || word[0] === "<")
+          return this.styleArgumentText(word);
+        return this.styleSubcommandText(word);
+      }).join(" ");
+    }
+    styleArgumentTerm(str) {
+      return this.styleArgumentText(str);
+    }
+    styleOptionText(str) {
+      return str;
+    }
+    styleArgumentText(str) {
+      return str;
+    }
+    styleSubcommandText(str) {
+      return str;
+    }
+    styleCommandText(str) {
+      return str;
+    }
     padWidth(cmd, helper) {
       return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
     }
-    wrap(str, width, indent, minColumnWidth = 40) {
-      const indents = " \\f\\t\\v   -   　\uFEFF";
-      const manualIndent = new RegExp(`[\\n][${indents}]+`);
-      if (str.match(manualIndent))
-        return str;
-      const columnWidth = width - indent;
-      if (columnWidth < minColumnWidth)
+    preformatted(str) {
+      return /\n[^\S\r\n]/.test(str);
+    }
+    formatItem(term, termWidth, description, helper) {
+      const itemIndent = 2;
+      const itemIndentStr = " ".repeat(itemIndent);
+      if (!description)
+        return itemIndentStr + term;
+      const paddedTerm = term.padEnd(termWidth + term.length - helper.displayWidth(term));
+      const spacerWidth = 2;
+      const helpWidth = this.helpWidth ?? 80;
+      const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+      let formattedDescription;
+      if (remainingWidth < this.minWidthToWrap || helper.preformatted(description)) {
+        formattedDescription = description;
+      } else {
+        const wrappedDescription = helper.boxWrap(description, remainingWidth);
+        formattedDescription = wrappedDescription.replace(/\n/g, `
+` + " ".repeat(termWidth + spacerWidth));
+      }
+      return itemIndentStr + paddedTerm + " ".repeat(spacerWidth) + formattedDescription.replace(/\n/g, `
+${itemIndentStr}`);
+    }
+    boxWrap(str, width) {
+      if (width < this.minWidthToWrap)
         return str;
-      const leadingStr = str.slice(0, indent);
-      const columnText = str.slice(indent).replace(`\r
-`, `
-`);
-      const indentString = " ".repeat(indent);
-      const zeroWidthSpace = "​";
-      const breaks = `\\s${zeroWidthSpace}`;
-      const regex = new RegExp(`
-|.{1,${columnWidth - 1}}([${breaks}]|$)|[^${breaks}]+?([${breaks}]|$)`, "g");
-      const lines = columnText.match(regex) || [];
-      return leadingStr + lines.map((line, i) => {
-        if (line === `
-`)
-          return "";
-        return (i > 0 ? indentString : "") + line.trimEnd();
-      }).join(`
+      const rawLines = str.split(/\r\n|\n/);
+      const chunkPattern = /[\s]*[^\s]+/g;
+      const wrappedLines = [];
+      rawLines.forEach((line) => {
+        const chunks = line.match(chunkPattern);
+        if (chunks === null) {
+          wrappedLines.push("");
+          return;
+        }
+        let sumChunks = [chunks.shift()];
+        let sumWidth = this.displayWidth(sumChunks[0]);
+        chunks.forEach((chunk) => {
+          const visibleWidth = this.displayWidth(chunk);
+          if (sumWidth + visibleWidth <= width) {
+            sumChunks.push(chunk);
+            sumWidth += visibleWidth;
+            return;
+          }
+          wrappedLines.push(sumChunks.join(""));
+          const nextChunk = chunk.trimStart();
+          sumChunks = [nextChunk];
+          sumWidth = this.displayWidth(nextChunk);
+        });
+        wrappedLines.push(sumChunks.join(""));
+      });
+      return wrappedLines.join(`
 `);
     }
   }
+  function stripColor(str) {
+    const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
+    return str.replace(sgrPattern, "");
+  }
   exports.Help = Help;
+  exports.stripColor = stripColor;
 });
 
 // node_modules/commander/lib/option.js
@@ -410,6 +537,7 @@ var require_option = __commonJS((exports) => {
       this.argChoices = undefined;
       this.conflictsWith = [];
       this.implied = undefined;
+      this.helpGroupHeading = undefined;
     }
     default(value, description) {
       this.defaultValue = value;
@@ -448,11 +576,12 @@ var require_option = __commonJS((exports) => {
       this.hidden = !!hide;
       return this;
     }
-    _concatValue(value, previous) {
+    _collectValue(value, previous) {
       if (previous === this.defaultValue || !Array.isArray(previous)) {
         return [value];
       }
-      return previous.concat(value);
+      previous.push(value);
+      return previous;
     }
     choices(values) {
       this.argChoices = values.slice();
@@ -461,7 +590,7 @@ var require_option = __commonJS((exports) => {
           throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(", ")}.`);
         }
         if (this.variadic) {
-          return this._concatValue(arg, previous);
+          return this._collectValue(arg, previous);
         }
         return arg;
       };
@@ -474,7 +603,14 @@ var require_option = __commonJS((exports) => {
       return this.short.replace(/^-/, "");
     }
     attributeName() {
-      return camelcase(this.name().replace(/^no-/, ""));
+      if (this.negate) {
+        return camelcase(this.name().replace(/^no-/, ""));
+      }
+      return camelcase(this.name());
+    }
+    helpGroup(heading) {
+      this.helpGroupHeading = heading;
+      return this;
     }
     is(arg) {
       return this.short === arg || this.long === arg;
@@ -519,14 +655,38 @@ var require_option = __commonJS((exports) => {
   function splitOptionFlags(flags) {
     let shortFlag;
     let longFlag;
-    const flagParts = flags.split(/[ |,]+/);
-    if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1]))
+    const shortFlagExp = /^-[^-]$/;
+    const longFlagExp = /^--[^-]/;
+    const flagParts = flags.split(/[ |,]+/).concat("guard");
+    if (shortFlagExp.test(flagParts[0]))
       shortFlag = flagParts.shift();
-    longFlag = flagParts.shift();
-    if (!shortFlag && /^-[^-]$/.test(longFlag)) {
+    if (longFlagExp.test(flagParts[0]))
+      longFlag = flagParts.shift();
+    if (!shortFlag && shortFlagExp.test(flagParts[0]))
+      shortFlag = flagParts.shift();
+    if (!shortFlag && longFlagExp.test(flagParts[0])) {
       shortFlag = longFlag;
-      longFlag = undefined;
-    }
+      longFlag = flagParts.shift();
+    }
+    if (flagParts[0].startsWith("-")) {
+      const unsupportedFlag = flagParts[0];
+      const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;
+      if (/^-[^-][^-]/.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- a short flag is a single dash and a single character
+  - either use a single dash and a single character (for a short flag)
+  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`);
+      if (shortFlagExp.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- too many short flags`);
+      if (longFlagExp.test(unsupportedFlag))
+        throw new Error(`${baseError}
+- too many long flags`);
+      throw new Error(`${baseError}
+- unrecognised flag format`);
+    }
+    if (shortFlag === undefined && longFlag === undefined)
+      throw new Error(`option creation failed due to no flags found in '${flags}'.`);
     return { shortFlag, longFlag };
   }
   exports.Option = Option;
@@ -615,7 +775,7 @@ var require_command = __commonJS((exports) => {
   var process2 = __require("node:process");
   var { Argument, humanReadableArgName } = require_argument();
   var { CommanderError } = require_error();
-  var { Help } = require_help();
+  var { Help, stripColor } = require_help();
   var { Option, DualOptions } = require_option();
   var { suggestSimilar } = require_suggestSimilar();
 
@@ -626,7 +786,7 @@ var require_command = __commonJS((exports) => {
       this.options = [];
       this.parent = null;
       this._allowUnknownOption = false;
-      this._allowExcessArguments = true;
+      this._allowExcessArguments = false;
       this.registeredArguments = [];
       this._args = this.registeredArguments;
       this.args = [];
@@ -653,18 +813,25 @@ var require_command = __commonJS((exports) => {
       this._lifeCycleHooks = {};
       this._showHelpAfterError = false;
       this._showSuggestionAfterError = true;
+      this._savedState = null;
       this._outputConfiguration = {
         writeOut: (str) => process2.stdout.write(str),
         writeErr: (str) => process2.stderr.write(str),
+        outputError: (str, write) => write(str),
         getOutHelpWidth: () => process2.stdout.isTTY ? process2.stdout.columns : undefined,
         getErrHelpWidth: () => process2.stderr.isTTY ? process2.stderr.columns : undefined,
-        outputError: (str, write) => write(str)
+        getOutHasColors: () => useColor() ?? (process2.stdout.isTTY && process2.stdout.hasColors?.()),
+        getErrHasColors: () => useColor() ?? (process2.stderr.isTTY && process2.stderr.hasColors?.()),
+        stripColor: (str) => stripColor(str)
       };
       this._hidden = false;
       this._helpOption = undefined;
       this._addImplicitHelpCommand = undefined;
       this._helpCommand = undefined;
       this._helpConfiguration = {};
+      this._helpGroupHeading = undefined;
+      this._defaultCommandGroup = undefined;
+      this._defaultOptionGroup = undefined;
     }
     copyInheritedSettings(sourceCommand) {
       this._outputConfiguration = sourceCommand._outputConfiguration;
@@ -729,7 +896,10 @@ var require_command = __commonJS((exports) => {
     configureOutput(configuration) {
       if (configuration === undefined)
         return this._outputConfiguration;
-      Object.assign(this._outputConfiguration, configuration);
+      this._outputConfiguration = {
+        ...this._outputConfiguration,
+        ...configuration
+      };
       return this;
     }
     showHelpAfterError(displayHelp = true) {
@@ -760,12 +930,12 @@ var require_command = __commonJS((exports) => {
     createArgument(name, description) {
       return new Argument(name, description);
     }
-    argument(name, description, fn, defaultValue) {
+    argument(name, description, parseArg, defaultValue) {
       const argument = this.createArgument(name, description);
-      if (typeof fn === "function") {
-        argument.default(defaultValue).argParser(fn);
+      if (typeof parseArg === "function") {
+        argument.default(defaultValue).argParser(parseArg);
       } else {
-        argument.default(fn);
+        argument.default(parseArg);
       }
       this.addArgument(argument);
       return this;
@@ -778,7 +948,7 @@ var require_command = __commonJS((exports) => {
     }
     addArgument(argument) {
       const previousArgument = this.registeredArguments.slice(-1)[0];
-      if (previousArgument && previousArgument.variadic) {
+      if (previousArgument?.variadic) {
         throw new Error(`only the last argument can be variadic '${previousArgument.name()}'`);
       }
       if (argument.required && argument.defaultValue !== undefined && argument.parseArg === undefined) {
@@ -790,10 +960,13 @@ var require_command = __commonJS((exports) => {
     helpCommand(enableOrNameAndArgs, description) {
       if (typeof enableOrNameAndArgs === "boolean") {
         this._addImplicitHelpCommand = enableOrNameAndArgs;
+        if (enableOrNameAndArgs && this._defaultCommandGroup) {
+          this._initCommandGroup(this._getHelpCommand());
+        }
         return this;
       }
-      enableOrNameAndArgs = enableOrNameAndArgs ?? "help [command]";
-      const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
+      const nameAndArgs = enableOrNameAndArgs ?? "help [command]";
+      const [, helpName, helpArgs] = nameAndArgs.match(/([^ ]+) *(.*)/);
       const helpDescription = description ?? "display help for command";
       const helpCommand = this.createCommand(helpName);
       helpCommand.helpOption(false);
@@ -803,6 +976,8 @@ var require_command = __commonJS((exports) => {
         helpCommand.description(helpDescription);
       this._addImplicitHelpCommand = true;
       this._helpCommand = helpCommand;
+      if (enableOrNameAndArgs || description)
+        this._initCommandGroup(helpCommand);
       return this;
     }
     addHelpCommand(helpCommand, deprecatedDescription) {
@@ -812,6 +987,7 @@ var require_command = __commonJS((exports) => {
       }
       this._addImplicitHelpCommand = true;
       this._helpCommand = helpCommand;
+      this._initCommandGroup(helpCommand);
       return this;
     }
     _getHelpCommand() {
@@ -891,6 +1067,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         throw new Error(`Cannot add option '${option.flags}'${this._name && ` to command '${this._name}'`} due to conflicting flag '${matchingFlag}'
 -  already used by option '${matchingOption.flags}'`);
       }
+      this._initOptionGroup(option);
       this.options.push(option);
     }
     _registerCommand(command) {
@@ -903,6 +1080,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const newCmd = knownBy(command).join("|");
         throw new Error(`cannot add command '${newCmd}' as already have command '${existingCmd}'`);
       }
+      this._initCommandGroup(command);
       this.commands.push(command);
     }
     addOption(option) {
@@ -925,7 +1103,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (val !== null && option.parseArg) {
           val = this._callParseArg(option, val, oldValue, invalidValueMessage);
         } else if (val !== null && option.variadic) {
-          val = option._concatValue(val, oldValue);
+          val = option._collectValue(val, oldValue);
         }
         if (val == null) {
           if (option.negate) {
@@ -1090,15 +1268,53 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return userArgs;
     }
     parse(argv, parseOptions) {
+      this._prepareForParse();
       const userArgs = this._prepareUserArgs(argv, parseOptions);
       this._parseCommand([], userArgs);
       return this;
     }
     async parseAsync(argv, parseOptions) {
+      this._prepareForParse();
       const userArgs = this._prepareUserArgs(argv, parseOptions);
       await this._parseCommand([], userArgs);
       return this;
     }
+    _prepareForParse() {
+      if (this._savedState === null) {
+        this.saveStateBeforeParse();
+      } else {
+        this.restoreStateBeforeParse();
+      }
+    }
+    saveStateBeforeParse() {
+      this._savedState = {
+        _name: this._name,
+        _optionValues: { ...this._optionValues },
+        _optionValueSources: { ...this._optionValueSources }
+      };
+    }
+    restoreStateBeforeParse() {
+      if (this._storeOptionsAsProperties)
+        throw new Error(`Can not call parse again when storeOptionsAsProperties is true.
+- either make a new Command for each call to parse, or stop storing options as properties`);
+      this._name = this._savedState._name;
+      this._scriptPath = null;
+      this.rawArgs = [];
+      this._optionValues = { ...this._savedState._optionValues };
+      this._optionValueSources = { ...this._savedState._optionValueSources };
+      this.args = [];
+      this.processedArgs = [];
+    }
+    _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
+      if (fs.existsSync(executableFile))
+        return;
+      const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
+      const executableMissing = `'${executableFile}' does not exist
+ - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
+ - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
+ - ${executableDirMessage}`;
+      throw new Error(executableMissing);
+    }
     _executeSubCommand(subcommand, args) {
       args = args.slice();
       let launchWithNode = false;
@@ -1122,7 +1338,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let resolvedScriptPath;
         try {
           resolvedScriptPath = fs.realpathSync(this._scriptPath);
-        } catch (err) {
+        } catch {
           resolvedScriptPath = this._scriptPath;
         }
         executableDir = path.resolve(path.dirname(resolvedScriptPath), executableDir);
@@ -1148,6 +1364,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           proc = childProcess.spawn(executableFile, args, { stdio: "inherit" });
         }
       } else {
+        this._checkForMissingExecutable(executableFile, executableDir, subcommand._name);
         args.unshift(executableFile);
         args = incrementNodeInspectorPort(process2.execArgv).concat(args);
         proc = childProcess.spawn(process2.execPath, args, { stdio: "inherit" });
@@ -1173,12 +1390,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       });
       proc.on("error", (err) => {
         if (err.code === "ENOENT") {
-          const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
-          const executableMissing = `'${executableFile}' does not exist
- - if '${subcommand._name}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
- - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
- - ${executableDirMessage}`;
-          throw new Error(executableMissing);
+          this._checkForMissingExecutable(executableFile, executableDir, subcommand._name);
         } else if (err.code === "EACCES") {
           throw new Error(`'${executableFile}' not executable`);
         }
@@ -1196,6 +1408,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       const subCommand = this._findCommand(commandName);
       if (!subCommand)
         this.help({ error: true });
+      subCommand._prepareForParse();
       let promiseChain;
       promiseChain = this._chainOrCallSubCommandHook(promiseChain, subCommand, "preSubcommand");
       promiseChain = this._chainOrCall(promiseChain, () => {
@@ -1265,7 +1478,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this.processedArgs = processedArgs;
     }
     _chainOrCall(promise, fn) {
-      if (promise && promise.then && typeof promise.then === "function") {
+      if (promise?.then && typeof promise.then === "function") {
         return promise.then(() => fn());
       }
       return fn();
@@ -1342,7 +1555,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         promiseChain = this._chainOrCallHooks(promiseChain, "postAction");
         return promiseChain;
       }
-      if (this.parent && this.parent.listenerCount(commandEvent)) {
+      if (this.parent?.listenerCount(commandEvent)) {
         checkForUnknownOptions();
         this._processArguments();
         this.parent.emit(commandEvent, operands, unknown);
@@ -1404,24 +1617,31 @@ Expecting one of '${allowedValues.join("', '")}'`);
         cmd._checkForConflictingLocalOptions();
       });
     }
-    parseOptions(argv) {
+    parseOptions(args) {
       const operands = [];
       const unknown = [];
       let dest = operands;
-      const args = argv.slice();
       function maybeOption(arg) {
         return arg.length > 1 && arg[0] === "-";
       }
+      const negativeNumberArg = (arg) => {
+        if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(arg))
+          return false;
+        return !this._getCommandAndAncestors().some((cmd) => cmd.options.map((opt) => opt.short).some((short) => /^-\d$/.test(short)));
+      };
       let activeVariadicOption = null;
-      while (args.length) {
-        const arg = args.shift();
+      let activeGroup = null;
+      let i = 0;
+      while (i < args.length || activeGroup) {
+        const arg = activeGroup ?? args[i++];
+        activeGroup = null;
         if (arg === "--") {
           if (dest === unknown)
             dest.push(arg);
-          dest.push(...args);
+          dest.push(...args.slice(i));
           break;
         }
-        if (activeVariadicOption && !maybeOption(arg)) {
+        if (activeVariadicOption && (!maybeOption(arg) || negativeNumberArg(arg))) {
           this.emit(`option:${activeVariadicOption.name()}`, arg);
           continue;
         }
@@ -1430,14 +1650,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
           const option = this._findOption(arg);
           if (option) {
             if (option.required) {
-              const value = args.shift();
+              const value = args[i++];
               if (value === undefined)
                 this.optionMissingArgument(option);
               this.emit(`option:${option.name()}`, value);
             } else if (option.optional) {
               let value = null;
-              if (args.length > 0 && !maybeOption(args[0])) {
-                value = args.shift();
+              if (i < args.length && (!maybeOption(args[i]) || negativeNumberArg(args[i]))) {
+                value = args[i++];
               }
               this.emit(`option:${option.name()}`, value);
             } else {
@@ -1454,7 +1674,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
               this.emit(`option:${option.name()}`, arg.slice(2));
             } else {
               this.emit(`option:${option.name()}`);
-              args.unshift(`-${arg.slice(2)}`);
+              activeGroup = `-${arg.slice(2)}`;
             }
             continue;
           }
@@ -1467,31 +1687,24 @@ Expecting one of '${allowedValues.join("', '")}'`);
             continue;
           }
         }
-        if (maybeOption(arg)) {
+        if (dest === operands && maybeOption(arg) && !(this.commands.length === 0 && negativeNumberArg(arg))) {
           dest = unknown;
         }
         if ((this._enablePositionalOptions || this._passThroughOptions) && operands.length === 0 && unknown.length === 0) {
           if (this._findCommand(arg)) {
             operands.push(arg);
-            if (args.length > 0)
-              unknown.push(...args);
+            unknown.push(...args.slice(i));
             break;
           } else if (this._getHelpCommand() && arg === this._getHelpCommand().name()) {
-            operands.push(arg);
-            if (args.length > 0)
-              operands.push(...args);
+            operands.push(arg, ...args.slice(i));
             break;
           } else if (this._defaultCommandName) {
-            unknown.push(arg);
-            if (args.length > 0)
-              unknown.push(...args);
+            unknown.push(arg, ...args.slice(i));
             break;
           }
         }
         if (this._passThroughOptions) {
-          dest.push(arg);
-          if (args.length > 0)
-            dest.push(...args);
+          dest.push(arg, ...args.slice(i));
           break;
         }
         dest.push(arg);
@@ -1702,6 +1915,32 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._name = str;
       return this;
     }
+    helpGroup(heading) {
+      if (heading === undefined)
+        return this._helpGroupHeading ?? "";
+      this._helpGroupHeading = heading;
+      return this;
+    }
+    commandsGroup(heading) {
+      if (heading === undefined)
+        return this._defaultCommandGroup ?? "";
+      this._defaultCommandGroup = heading;
+      return this;
+    }
+    optionsGroup(heading) {
+      if (heading === undefined)
+        return this._defaultOptionGroup ?? "";
+      this._defaultOptionGroup = heading;
+      return this;
+    }
+    _initOptionGroup(option) {
+      if (this._defaultOptionGroup && !option.helpGroupHeading)
+        option.helpGroup(this._defaultOptionGroup);
+    }
+    _initCommandGroup(cmd) {
+      if (this._defaultCommandGroup && !cmd.helpGroup())
+        cmd.helpGroup(this._defaultCommandGroup);
+    }
     nameFromFilename(filename) {
       this._name = path.basename(filename, path.extname(filename));
       return this;
@@ -1714,23 +1953,38 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     helpInformation(contextOptions) {
       const helper = this.createHelp();
-      if (helper.helpWidth === undefined) {
-        helper.helpWidth = contextOptions && contextOptions.error ? this._outputConfiguration.getErrHelpWidth() : this._outputConfiguration.getOutHelpWidth();
-      }
-      return helper.formatHelp(this, helper);
+      const context = this._getOutputContext(contextOptions);
+      helper.prepareContext({
+        error: context.error,
+        helpWidth: context.helpWidth,
+        outputHasColors: context.hasColors
+      });
+      const text = helper.formatHelp(this, helper);
+      if (context.hasColors)
+        return text;
+      return this._outputConfiguration.stripColor(text);
     }
-    _getHelpContext(contextOptions) {
+    _getOutputContext(contextOptions) {
       contextOptions = contextOptions || {};
-      const context = { error: !!contextOptions.error };
-      let write;
-      if (context.error) {
-        write = (arg) => this._outputConfiguration.writeErr(arg);
+      const error = !!contextOptions.error;
+      let baseWrite;
+      let hasColors;
+      let helpWidth;
+      if (error) {
+        baseWrite = (str) => this._outputConfiguration.writeErr(str);
+        hasColors = this._outputConfiguration.getErrHasColors();
+        helpWidth = this._outputConfiguration.getErrHelpWidth();
       } else {
-        write = (arg) => this._outputConfiguration.writeOut(arg);
-      }
-      context.write = contextOptions.write || write;
-      context.command = this;
-      return context;
+        baseWrite = (str) => this._outputConfiguration.writeOut(str);
+        hasColors = this._outputConfiguration.getOutHasColors();
+        helpWidth = this._outputConfiguration.getOutHelpWidth();
+      }
+      const write = (str) => {
+        if (!hasColors)
+          str = this._outputConfiguration.stripColor(str);
+        return baseWrite(str);
+      };
+      return { error, write, hasColors, helpWidth };
     }
     outputHelp(contextOptions) {
       let deprecatedCallback;
@@ -1738,35 +1992,44 @@ Expecting one of '${allowedValues.join("', '")}'`);
         deprecatedCallback = contextOptions;
         contextOptions = undefined;
       }
-      const context = this._getHelpContext(contextOptions);
-      this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", context));
-      this.emit("beforeHelp", context);
-      let helpInformation = this.helpInformation(context);
+      const outputContext = this._getOutputContext(contextOptions);
+      const eventContext = {
+        error: outputContext.error,
+        write: outputContext.write,
+        command: this
+      };
+      this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", eventContext));
+      this.emit("beforeHelp", eventContext);
+      let helpInformation = this.helpInformation({ error: outputContext.error });
       if (deprecatedCallback) {
         helpInformation = deprecatedCallback(helpInformation);
         if (typeof helpInformation !== "string" && !Buffer.isBuffer(helpInformation)) {
           throw new Error("outputHelp callback must return a string or a Buffer");
         }
       }
-      context.write(helpInformation);
+      outputContext.write(helpInformation);
       if (this._getHelpOption()?.long) {
         this.emit(this._getHelpOption().long);
       }
-      this.emit("afterHelp", context);
-      this._getCommandAndAncestors().forEach((command) => command.emit("afterAllHelp", context));
+      this.emit("afterHelp", eventContext);
+      this._getCommandAndAncestors().forEach((command) => command.emit("afterAllHelp", eventContext));
     }
     helpOption(flags, description) {
       if (typeof flags === "boolean") {
         if (flags) {
-          this._helpOption = this._helpOption ?? undefined;
+          if (this._helpOption === null)
+            this._helpOption = undefined;
+          if (this._defaultOptionGroup) {
+            this._initOptionGroup(this._getHelpOption());
+          }
         } else {
           this._helpOption = null;
         }
         return this;
       }
-      flags = flags ?? "-h, --help";
-      description = description ?? "display help for command";
-      this._helpOption = this.createOption(flags, description);
+      this._helpOption = this.createOption(flags ?? "-h, --help", description ?? "display help for command");
+      if (flags || description)
+        this._initOptionGroup(this._helpOption);
       return this;
     }
     _getHelpOption() {
@@ -1777,11 +2040,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     addHelpOption(option) {
       this._helpOption = option;
+      this._initOptionGroup(option);
       return this;
     }
     help(contextOptions) {
       this.outputHelp(contextOptions);
-      let exitCode = process2.exitCode || 0;
+      let exitCode = Number(process2.exitCode ?? 0);
       if (exitCode === 0 && contextOptions && typeof contextOptions !== "function" && contextOptions.error) {
         exitCode = 1;
       }
@@ -1846,7 +2110,15 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return arg;
     });
   }
+  function useColor() {
+    if (process2.env.NO_COLOR || process2.env.FORCE_COLOR === "0" || process2.env.FORCE_COLOR === "false")
+      return false;
+    if (process2.env.FORCE_COLOR || process2.env.CLICOLOR_FORCE !== undefined)
+      return true;
+    return;
+  }
   exports.Command = Command;
+  exports.useColor = useColor;
 });
 
 // node_modules/commander/index.js
@@ -13151,7 +13423,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.15.0-dev.6",
+  version: "0.15.0-dev.9",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -13179,7 +13451,7 @@ var package_default = {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
     "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
     "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
-    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
+    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -13192,7 +13464,7 @@ var package_default = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.20.2",
-    commander: "^12.1.0",
+    commander: "^14.0.3",
     "js-yaml": "^4.1.0",
     pg: "^8.16.3"
   },
@@ -13202,7 +13474,7 @@ var package_default = {
     "@types/pg": "^8.15.6",
     ajv: "^8.17.1",
     "ajv-formats": "^3.0.1",
-    typescript: "^5.9.3"
+    typescript: "^6.0.2"
   },
   publishConfig: {
     access: "public"
@@ -15982,7 +16254,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.15.0-dev.6";
+var version = "0.15.0-dev.9";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16013,7 +16285,7 @@ var package_default2 = {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
     "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
     "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
-    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
+    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql && cp ../instances.demo.yml ./instances.demo.yml`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
@@ -16026,7 +16298,7 @@ var package_default2 = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.20.2",
-    commander: "^12.1.0",
+    commander: "^14.0.3",
     "js-yaml": "^4.1.0",
     pg: "^8.16.3"
   },
@@ -16036,7 +16308,7 @@ var package_default2 = {
     "@types/pg": "^8.15.6",
     ajv: "^8.17.1",
     "ajv-formats": "^3.0.1",
-    typescript: "^5.9.3"
+    typescript: "^6.0.2"
   },
   publishConfig: {
     access: "public"
@@ -25439,8 +25711,9 @@ function isSslNegotiationError(err) {
 }
 async function connectWithSslFallback(ClientClass, adminConn, verbose) {
   const tryConnect = async (config2) => {
-    const client = new ClientClass(config2);
+    const client = new ClientClass({ ...config2, connectionTimeoutMillis: 1e4 });
     await client.connect();
+    await client.query("SET statement_timeout = '30s'");
     return client;
   };
   if (!adminConn.sslFallbackEnabled) {
@@ -25909,7 +26182,12 @@ async function verifyInitSetup(params) {
     if (!schemaExistsRes.rows?.[0]?.ok) {
       missingRequired.push("USAGE on schema postgres_ai");
     }
-    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
+    const viewExistsRes = await params.client.query(`
+      select case
+        when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+        else to_regclass('postgres_ai.pg_statistic') is not null
+      end as ok
+    `);
     if (!viewExistsRes.rows?.[0]?.ok) {
       missingRequired.push("view postgres_ai.pg_statistic exists");
     } else {
@@ -25993,6 +26271,119 @@ async function verifyInitSetup(params) {
     } catch {}
   }
 }
+async function checkCurrentUserPermissions(client) {
+  const sql = `
+    with permission_checks as (
+      select
+        format('connect on database %I', current_database()) as permission_name,
+        'required' as status,
+        has_database_privilege(current_user, current_database(), 'connect') as granted
+
+      union all
+
+      select
+        'pg_monitor role membership' as permission_name,
+        'required' as status,
+        -- CASE guarantees evaluation order: pg_has_role() is only called if the
+        -- pg_monitor role exists, avoiding ERROR on PostgreSQL < 10 or when dropped.
+        case
+          when not exists (select from pg_roles where rolname = 'pg_monitor')
+          then false
+          else pg_has_role(current_user, 'pg_monitor', 'member')
+        end as granted
+
+      union all
+
+      select
+        'select on pg_catalog.pg_index' as permission_name,
+        'required' as status,
+        has_table_privilege(current_user, 'pg_catalog.pg_index', 'select') as granted
+
+      union all
+
+      select
+        'postgres_ai.pg_statistic view exists' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as granted
+
+      union all
+
+      select
+        'select on postgres_ai.pg_statistic' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          when to_regclass('postgres_ai.pg_statistic') is null then null
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
+        end as granted
+    )
+    select
+      permission_name,
+      status,
+      granted,
+      case
+        when status = 'required' and not coalesce(granted, false) then
+          case
+            when permission_name like 'connect%' then
+              format('grant connect on database %I to %I;', current_database(), current_user)
+            when permission_name = 'pg_monitor role membership' then
+              format('grant pg_monitor to %I;', current_user)
+            when permission_name like 'select on pg_catalog.pg_index' then
+              format('grant select on pg_catalog.pg_index to %I;', current_user)
+          end
+        when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
+          '-- create postgres_ai.pg_statistic view (see setup script)'
+        when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
+          format('grant select on postgres_ai.pg_statistic to %I;', current_user)
+        else null
+      end as fix_command
+    from permission_checks
+    order by
+      case status when 'required' then 1 else 2 end,
+      permission_name;
+  `;
+  const res = await client.query(sql);
+  const rows = res.rows;
+  const missingRequired = rows.filter((r) => r.status === "required" && r.granted !== true);
+  const missingOptional = rows.filter((r) => r.status === "optional" && r.granted === false);
+  return {
+    ok: missingRequired.length === 0,
+    rows,
+    missingRequired,
+    missingOptional
+  };
+}
+function formatPermissionCheckMessages(result) {
+  const warnings = [];
+  const errors3 = [];
+  for (const row of result.missingOptional) {
+    const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
+    warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
+  }
+  if (!result.ok) {
+    errors3.push(`Error: the database user is missing required permissions.
+`);
+    errors3.push("Missing permissions:");
+    for (const row of result.missingRequired) {
+      errors3.push(`  - ${row.permission_name}`);
+    }
+    const fixes = result.missingRequired.map((r) => r.fix_command).filter(Boolean);
+    if (fixes.length > 0) {
+      errors3.push(`
+To fix, run the following as a superuser:
+`);
+      for (const fix of fixes) {
+        errors3.push(`  ${fix}`);
+      }
+    }
+    errors3.push(`
+Alternatively, run 'postgresai prepare-db' to set up permissions automatically.`);
+  }
+  return { failed: !result.ok, warnings, errors: errors3 };
+}
 
 // lib/supabase.ts
 var SUPABASE_API_BASE = "https://api.supabase.com";
@@ -26155,6 +26546,9 @@ class SupabaseClient {
   }
 }
 async function fetchPoolerDatabaseUrl(config2, username) {
+  if (!isValidProjectRef(config2.projectRef)) {
+    throw new Error(`Invalid Supabase project reference format: "${config2.projectRef}". Expected 10-30 alphanumeric characters.`);
+  }
   const url = `${SUPABASE_API_BASE}/v1/projects/${encodeURIComponent(config2.projectRef)}/config/database/pooler`;
   const suffix = `.${config2.projectRef}`;
   const effectiveUsername = username.endsWith(suffix) ? username : `${username}${suffix}`;
@@ -26327,7 +26721,10 @@ async function verifyInitSetupViaSupabase(params) {
       missingRequired.push("USAGE on schema postgres_ai");
     }
   }
-  const viewExistsRes = await params.client.query("SELECT to_regclass('postgres_ai.pg_statistic') IS NOT NULL as ok", true);
+  const viewExistsRes = await params.client.query(`SELECT CASE
+      WHEN NOT has_schema_privilege(current_user, 'postgres_ai', 'USAGE') THEN NULL
+      ELSE to_regclass('postgres_ai.pg_statistic') IS NOT NULL
+    END as ok`, true);
   if (!viewExistsRes.rows?.[0]?.ok) {
     missingRequired.push("view postgres_ai.pg_statistic exists");
   } else {
@@ -27472,6 +27869,65 @@ limit 1000
     },
     gauges: ["real_size_mib", "table_size_mib", "extra_size", "extra_pct", "fillfactor", "bloat_size", "bloat_pct", "is_na", "reltuples"],
     statement_timeout_seconds: 15
+  },
+  pg_stat_io: {
+    description: "Collects I/O statistics from the PostgreSQL `pg_stat_io` view (available in PostgreSQL 16+). Provides insights into read and write operations by backend type, including the number of operations, MiB transferred (divided by 1048576), and time spent on I/O. This metric is essential for monitoring I/O performance and identifying potential bottlenecks in disk operations. The data is aggregated by backend type with a total row included via ROLLUP.",
+    sqls: {
+      11: "; -- pg_stat_io only available in PostgreSQL 16+",
+      16: `select /* pgwatch_generated */
+    (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+    current_database() as tag_datname,
+    coalesce(backend_type, 'total') as tag_backend_type,
+    sum(coalesce(reads, 0))::int8 as reads,
+    (sum(coalesce(reads, 0) * op_bytes) / 1048576.0)::int8 as read_bytes_mb,
+    sum(coalesce(read_time, 0))::int8 as read_time_ms,
+    sum(coalesce(writes, 0))::int8 as writes,
+    (sum(coalesce(writes, 0) * op_bytes) / 1048576.0)::int8 as write_bytes_mb,
+    sum(coalesce(write_time, 0))::int8 as write_time_ms,
+    sum(coalesce(writebacks, 0))::int8 as writebacks,
+    (sum(coalesce(writebacks, 0) * op_bytes) / 1048576.0)::int8 as writeback_bytes_mb,
+    sum(coalesce(writeback_time, 0))::int8 as writeback_time_ms,
+    sum(coalesce(fsyncs, 0))::int8 as fsyncs,
+    sum(coalesce(fsync_time, 0))::int8 as fsync_time_ms,
+    sum(coalesce(extends, 0))::int8 as extends,
+    (sum(coalesce(extends, 0) * op_bytes) / 1048576.0)::int8 as extend_bytes_mb,
+    sum(coalesce(hits, 0))::int8 as hits,
+    sum(coalesce(evictions, 0))::int8 as evictions,
+    sum(coalesce(reuses, 0))::int8 as reuses,
+    max(extract(epoch from now() - stats_reset)::int) as stats_reset_s
+from
+    pg_stat_io
+group by
+    rollup (backend_type)`,
+      18: `select /* pgwatch_generated */
+    (extract(epoch from now()) * 1e9)::int8 as epoch_ns,
+    current_database() as tag_datname,
+    coalesce(backend_type, 'total') as tag_backend_type,
+    sum(coalesce(reads, 0))::int8 as reads,
+    (sum(coalesce(read_bytes, 0)) / 1048576.0)::int8 as read_bytes_mb,
+    sum(coalesce(read_time, 0))::int8 as read_time_ms,
+    sum(coalesce(writes, 0))::int8 as writes,
+    (sum(coalesce(write_bytes, 0)) / 1048576.0)::int8 as write_bytes_mb,
+    sum(coalesce(write_time, 0))::int8 as write_time_ms,
+    sum(coalesce(writebacks, 0))::int8 as writebacks,
+    -- PostgreSQL 18 has no writeback_bytes column; rows with NULL op_bytes contribute zero by design.
+    (sum(coalesce(writebacks, 0) * coalesce(op_bytes, 0)) / 1048576.0)::int8 as writeback_bytes_mb,
+    sum(coalesce(writeback_time, 0))::int8 as writeback_time_ms,
+    sum(coalesce(fsyncs, 0))::int8 as fsyncs,
+    sum(coalesce(fsync_time, 0))::int8 as fsync_time_ms,
+    sum(coalesce(extends, 0))::int8 as extends,
+    (sum(coalesce(extend_bytes, 0)) / 1048576.0)::int8 as extend_bytes_mb,
+    sum(coalesce(hits, 0))::int8 as hits,
+    sum(coalesce(evictions, 0))::int8 as evictions,
+    sum(coalesce(reuses, 0))::int8 as reuses,
+    max(extract(epoch from now() - stats_reset)::int) as stats_reset_s
+from
+    pg_stat_io
+group by
+    rollup (backend_type)`
+    },
+    gauges: ["*"],
+    statement_timeout_seconds: 15
   }
 };
 
@@ -27497,7 +27953,8 @@ var METRIC_NAMES = {
   settings: "settings",
   dbStats: "db_stats",
   dbSize: "db_size",
-  statsReset: "stats_reset"
+  statsReset: "stats_reset",
+  I001: "pg_stat_io"
 };
 function transformMetricRow(row) {
   const result = {};
@@ -29044,6 +29501,140 @@ async function generateG003(client, nodeName) {
   };
   return report;
 }
+async function getIOStatistics(client, pgMajorVersion = 0, metricSqlOverride) {
+  if (pgMajorVersion < 16) {
+    return [];
+  }
+  try {
+    const sql = metricSqlOverride ?? getMetricSql(METRIC_NAMES.I001, pgMajorVersion);
+    if (!sql || sql.trim().startsWith(";")) {
+      return [];
+    }
+    const result = await client.query(sql);
+    return result.rows.map((row) => {
+      const transformed = transformMetricRow(row);
+      return {
+        backend_type: String(transformed.backend_type || "unknown"),
+        reads: parseInt(String(transformed.reads || 0), 10),
+        read_bytes_mb: parseInt(String(transformed.read_bytes_mb || 0), 10),
+        read_time_ms: parseInt(String(transformed.read_time_ms || 0), 10),
+        writes: parseInt(String(transformed.writes || 0), 10),
+        write_bytes_mb: parseInt(String(transformed.write_bytes_mb || 0), 10),
+        write_time_ms: parseInt(String(transformed.write_time_ms || 0), 10),
+        writebacks: parseInt(String(transformed.writebacks || 0), 10),
+        writeback_bytes_mb: parseInt(String(transformed.writeback_bytes_mb || 0), 10),
+        writeback_time_ms: parseInt(String(transformed.writeback_time_ms || 0), 10),
+        fsyncs: parseInt(String(transformed.fsyncs || 0), 10),
+        fsync_time_ms: parseInt(String(transformed.fsync_time_ms || 0), 10),
+        extends: parseInt(String(transformed.extends || 0), 10),
+        extend_bytes_mb: parseInt(String(transformed.extend_bytes_mb || 0), 10),
+        hits: parseInt(String(transformed.hits || 0), 10),
+        evictions: parseInt(String(transformed.evictions || 0), 10),
+        reuses: parseInt(String(transformed.reuses || 0), 10)
+      };
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.log(`[I001] Error fetching I/O statistics: ${errorMsg}`);
+    return [];
+  }
+}
+async function generateI001(client, nodeName) {
+  const report = createBaseReport("I001", "I/O statistics (pg_stat_io)", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const parsedPgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
+  const pgMajorVersion = Number.isFinite(parsedPgMajorVersion) ? parsedPgMajorVersion : 0;
+  if (pgMajorVersion < 16) {
+    report.results[nodeName] = {
+      data: {
+        available: false,
+        min_version_required: "16",
+        by_backend_type: [],
+        analysis: {
+          total_read_mb: 0,
+          total_write_mb: 0,
+          total_io_time_ms: 0,
+          read_hit_ratio_pct: 0,
+          avg_read_time_ms: null,
+          avg_write_time_ms: null
+        },
+        stats_reset_s: null
+      },
+      postgres_version: postgresVersion
+    };
+    return report;
+  }
+  const ioStats = await getIOStatistics(client, pgMajorVersion);
+  ioStats.sort((a, b) => {
+    if (a.backend_type === "total")
+      return -1;
+    if (b.backend_type === "total")
+      return 1;
+    return a.backend_type.localeCompare(b.backend_type);
+  });
+  let totalStats = ioStats.find((s) => s.backend_type === "total");
+  if (!totalStats && ioStats.length > 0) {
+    totalStats = {
+      backend_type: "total",
+      reads: ioStats.reduce((sum, s) => sum + s.reads, 0),
+      read_bytes_mb: ioStats.reduce((sum, s) => sum + s.read_bytes_mb, 0),
+      read_time_ms: ioStats.reduce((sum, s) => sum + s.read_time_ms, 0),
+      writes: ioStats.reduce((sum, s) => sum + s.writes, 0),
+      write_bytes_mb: ioStats.reduce((sum, s) => sum + s.write_bytes_mb, 0),
+      write_time_ms: ioStats.reduce((sum, s) => sum + s.write_time_ms, 0),
+      writebacks: ioStats.reduce((sum, s) => sum + s.writebacks, 0),
+      writeback_bytes_mb: ioStats.reduce((sum, s) => sum + s.writeback_bytes_mb, 0),
+      writeback_time_ms: ioStats.reduce((sum, s) => sum + s.writeback_time_ms, 0),
+      fsyncs: ioStats.reduce((sum, s) => sum + s.fsyncs, 0),
+      fsync_time_ms: ioStats.reduce((sum, s) => sum + s.fsync_time_ms, 0),
+      extends: ioStats.reduce((sum, s) => sum + (s.extends || 0), 0),
+      extend_bytes_mb: ioStats.reduce((sum, s) => sum + (s.extend_bytes_mb || 0), 0),
+      hits: ioStats.reduce((sum, s) => sum + s.hits, 0),
+      evictions: ioStats.reduce((sum, s) => sum + s.evictions, 0),
+      reuses: ioStats.reduce((sum, s) => sum + s.reuses, 0)
+    };
+  }
+  const totalReadMb = totalStats?.read_bytes_mb || 0;
+  const totalWriteMb = totalStats?.write_bytes_mb || 0;
+  const totalReadTime = totalStats?.read_time_ms || 0;
+  const totalWriteTime = totalStats?.write_time_ms || 0;
+  const totalIoTimeMs = totalReadTime + totalWriteTime;
+  const totalReads = totalStats?.reads || 0;
+  const totalWrites = totalStats?.writes || 0;
+  const totalHits = totalStats?.hits || 0;
+  const totalRequests = totalHits + totalReads;
+  const readHitRatioPct = totalRequests > 0 ? Math.round(totalHits / totalRequests * 1e4) / 100 : 0;
+  const avgReadTimeMs = totalReads > 0 ? Math.round(totalReadTime / totalReads * 1000) / 1000 : null;
+  const avgWriteTimeMs = totalWrites > 0 ? Math.round(totalWriteTime / totalWrites * 1000) / 1000 : null;
+  let statsResetS = null;
+  try {
+    const resetResult = await client.query(`
+      select max(extract(epoch from now() - stats_reset)::int) as stats_reset_s
+      from pg_stat_io
+    `);
+    if (resetResult.rows.length > 0 && resetResult.rows[0].stats_reset_s !== null) {
+      const parsedStatsResetS = parseInt(resetResult.rows[0].stats_reset_s, 10);
+      statsResetS = Number.isFinite(parsedStatsResetS) ? parsedStatsResetS : null;
+    }
+  } catch (err) {}
+  report.results[nodeName] = {
+    data: {
+      available: ioStats.length > 0,
+      by_backend_type: ioStats,
+      analysis: {
+        total_read_mb: totalReadMb,
+        total_write_mb: totalWriteMb,
+        total_io_time_ms: totalIoTimeMs,
+        read_hit_ratio_pct: readHitRatioPct,
+        avg_read_time_ms: avgReadTimeMs,
+        avg_write_time_ms: avgWriteTimeMs
+      },
+      stats_reset_s: statsResetS
+    },
+    postgres_version: postgresVersion
+  };
+  return report;
+}
 var REPORT_GENERATORS = {
   A002: generateA002,
   A003: generateA003,
@@ -29059,7 +29650,8 @@ var REPORT_GENERATORS = {
   G003: generateG003,
   H001: generateH001,
   H002: generateH002,
-  H004: generateH004
+  H004: generateH004,
+  I001: generateI001
 };
 var CHECK_INFO = (() => {
   const fullMap = buildCheckInfoMap();
@@ -29095,6 +29687,7 @@ function getCheckupEntry(code) {
 }
 
 // lib/checkup-api.ts
+import * as http2 from "http";
 import * as https from "https";
 import { URL as URL3 } from "url";
 var DEFAULT_RETRY_CONFIG = {
@@ -29224,7 +29817,15 @@ async function postRpc(params) {
         clearTimeout(timeoutId);
       resolve6(value);
     };
-    const req = https.request(url, {
+    if (url.protocol === "http:") {
+      const hostname = url.hostname.replace(/^\[|\]$/g, "");
+      const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(hostname);
+      if (!isLoopback && process.env.CHECKUP_ALLOW_HTTP !== "1") {
+        throw new Error(`Refusing to send API key over plaintext HTTP to '${url.host}'. ` + `Use https://, a loopback hostname, or set CHECKUP_ALLOW_HTTP=1.`);
+      }
+    }
+    const transport = url.protocol === "http:" ? http2 : https;
+    const req = transport.request(url, {
       method: "POST",
       headers,
       signal: controller.signal
@@ -29594,18 +30195,13 @@ function closeReadline() {
     rl = null;
   }
 }
-async function execPromise(command) {
-  return new Promise((resolve7, reject) => {
-    childProcess.exec(command, (error2, stdout, stderr) => {
-      if (error2) {
-        const err = error2;
-        err.code = typeof error2.code === "number" ? error2.code : 1;
-        reject(err);
-      } else {
-        resolve7({ stdout, stderr });
-      }
-    });
-  });
+function stripMatchingQuotes(value) {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  if (trimmed.length >= 2 && (quote === '"' || quote === "'") && trimmed.endsWith(quote)) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
 }
 async function execFilePromise(file, args) {
   return new Promise((resolve7, reject) => {
@@ -29891,7 +30487,7 @@ async function ensureDefaultMonitoringProject() {
       throw new Error(`Failed to bootstrap docker-compose.yml: ${msg}`);
     }
   }
-  if (fs6.existsSync(instancesFile) && fs6.statSync(instancesFile).isDirectory()) {
+  if (fs6.existsSync(instancesFile) && fs6.lstatSync(instancesFile).isDirectory()) {
     fs6.rmSync(instancesFile, { recursive: true, force: true });
   }
   if (!fs6.existsSync(instancesFile)) {
@@ -30963,6 +31559,20 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
     spinner.update("Connecting to Postgres");
     const connResult = await connectWithSslFallback(Client, adminConn);
     client = connResult.client;
+    spinner.update("Checking database permissions");
+    const permCheck = await checkCurrentUserPermissions(client);
+    const permMessages = formatPermissionCheckMessages(permCheck);
+    for (const w of permMessages.warnings) {
+      console.error(w);
+    }
+    if (permMessages.failed) {
+      spinner.stop();
+      for (const e of permMessages.errors) {
+        console.error(e);
+      }
+      process.exitCode = 1;
+      return;
+    }
     let reports;
     if (checkId === "ALL") {
       reports = await generateAllReports(client, opts.nodeName, (p) => {
@@ -31270,12 +31880,12 @@ async function runCompose(args, grafanaPassword) {
       if (!env.VM_AUTH_USERNAME) {
         const m = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
         if (m)
-          env.VM_AUTH_USERNAME = m[1].trim().replace(/^["']|["']$/g, "");
+          env.VM_AUTH_USERNAME = stripMatchingQuotes(m[1]);
       }
       if (!env.VM_AUTH_PASSWORD) {
         const m = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
         if (m)
-          env.VM_AUTH_PASSWORD = m[1].trim().replace(/^["']|["']$/g, "");
+          env.VM_AUTH_PASSWORD = stripMatchingQuotes(m[1]);
       }
     } catch (err) {
       if (process.env.DEBUG) {
@@ -31322,6 +31932,9 @@ mon.command("local-install").description("install local monitoring stack (genera
   const envFile = path6.resolve(projectDir, ".env");
   let existingRegistry = null;
   let existingPassword = null;
+  let existingReplicatorPassword = null;
+  let existingVmAuthUsername = null;
+  let existingVmAuthPassword = null;
   if (fs6.existsSync(envFile)) {
     const existingEnv = fs6.readFileSync(envFile, "utf8");
     const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
@@ -31330,6 +31943,15 @@ mon.command("local-install").description("install local monitoring stack (genera
     const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
     if (pwdMatch)
       existingPassword = pwdMatch[1].trim();
+    const replicatorPwdMatch = existingEnv.match(/^REPLICATOR_PASSWORD=(.+)$/m);
+    if (replicatorPwdMatch)
+      existingReplicatorPassword = replicatorPwdMatch[1].trim();
+    const vmAuthUserMatch = existingEnv.match(/^VM_AUTH_USERNAME=(.+)$/m);
+    if (vmAuthUserMatch)
+      existingVmAuthUsername = stripMatchingQuotes(vmAuthUserMatch[1]);
+    const vmAuthPasswordMatch = existingEnv.match(/^VM_AUTH_PASSWORD=(.+)$/m);
+    if (vmAuthPasswordMatch)
+      existingVmAuthPassword = stripMatchingQuotes(vmAuthPasswordMatch[1]);
   }
   const imageTag = opts.tag || package_default.version;
   const envLines = [`PGAI_TAG=${imageTag}`];
@@ -31339,6 +31961,9 @@ mon.command("local-install").description("install local monitoring stack (genera
   if (existingPassword) {
     envLines.push(`GF_SECURITY_ADMIN_PASSWORD=${existingPassword}`);
   }
+  envLines.push(`REPLICATOR_PASSWORD=${existingReplicatorPassword || crypto2.randomBytes(32).toString("hex")}`);
+  envLines.push(`VM_AUTH_USERNAME=${existingVmAuthUsername || "vmauth"}`);
+  envLines.push(`VM_AUTH_PASSWORD=${existingVmAuthPassword || crypto2.randomBytes(18).toString("base64")}`);
   fs6.writeFileSync(envFile, envLines.join(`
 `) + `
 `, { encoding: "utf8", mode: 384 });
@@ -31462,18 +32087,23 @@ Use demo mode without API key: postgres-ai mon local-install --demo`);
       console.log(`\u2713 Monitoring target '${instanceName}' added
 `);
       console.log("Testing connection to the added instance...");
-      try {
-        const client = new Client({ connectionString: connStr });
-        await client.connect();
-        const result = await client.query("select version();");
-        console.log("\u2713 Connection successful");
-        console.log(`${result.rows[0].version}
+      {
+        let testClient = null;
+        try {
+          testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 1e4 });
+          await testClient.connect();
+          const result = await testClient.query("select version();");
+          console.log("\u2713 Connection successful");
+          console.log(`${result.rows[0].version}
 `);
-        await client.end();
-      } catch (error2) {
-        const message = error2 instanceof Error ? error2.message : String(error2);
-        console.error(`\u2717 Connection failed: ${message}
+        } catch (error2) {
+          const message = error2 instanceof Error ? error2.message : String(error2);
+          console.error(`\u2717 Connection failed: ${message}
 `);
+        } finally {
+          if (testClient)
+            await testClient.end();
+        }
       }
     } else if (opts.yes) {
       console.log("Auto-yes mode: no database URL provided, skipping database setup");
@@ -31517,18 +32147,23 @@ You can provide either:`);
             console.log(`\u2713 Monitoring target '${instanceName}' added
 `);
             console.log("Testing connection to the added instance...");
-            try {
-              const client = new Client({ connectionString: connStr });
-              await client.connect();
-              const result = await client.query("select version();");
-              console.log("\u2713 Connection successful");
-              console.log(`${result.rows[0].version}
+            {
+              let testClient = null;
+              try {
+                testClient = new Client({ connectionString: connStr, connectionTimeoutMillis: 1e4 });
+                await testClient.connect();
+                const result = await testClient.query("select version();");
+                console.log("\u2713 Connection successful");
+                console.log(`${result.rows[0].version}
 `);
-              await client.end();
-            } catch (error2) {
-              const message = error2 instanceof Error ? error2.message : String(error2);
-              console.error(`\u2717 Connection failed: ${message}
+              } catch (error2) {
+                const message = error2 instanceof Error ? error2.message : String(error2);
+                console.error(`\u2717 Connection failed: ${message}
 `);
+              } finally {
+                if (testClient)
+                  await testClient.end();
+              }
             }
           }
         } else {
@@ -31549,15 +32184,17 @@ You can provide either:`);
     ];
     const demoSrc = demoCandidates.find((p) => fs6.existsSync(p));
     if (demoSrc) {
-      if (fs6.existsSync(instancesPath) && fs6.statSync(instancesPath).isDirectory()) {
+      if (fs6.existsSync(instancesPath) && fs6.lstatSync(instancesPath).isDirectory()) {
         fs6.rmSync(instancesPath, { recursive: true, force: true });
       }
       fs6.copyFileSync(demoSrc, instancesPath);
       console.log(`\u2713 Demo monitoring target configured
 `);
     } else {
-      console.error(`\u26A0 instances.demo.yml not found \u2014 demo target not configured (searched: ${demoCandidates.join(", ")})
+      console.error(`Error: instances.demo.yml not found \u2014 cannot configure demo target.
+Searched: ${demoCandidates.join(", ")}
 `);
+      process.exit(1);
     }
   }
   console.log(opts.demo ? "Step 3: Updating configuration..." : "Step 3: Updating configuration...");
@@ -31586,9 +32223,8 @@ You can provide either:`);
     }
     if (!grafanaPassword) {
       console.log("Generating secure Grafana password...");
-      const { stdout: password } = await execPromise(`openssl rand -base64 12 | tr -d '
-'`);
-      grafanaPassword = password.trim();
+      const { stdout: password } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
+      grafanaPassword = password.trim().replace(/\n/g, "");
       let configContent = "";
       if (fs6.existsSync(cfgPath)) {
         const stats = fs6.statSync(cfgPath);
@@ -31617,17 +32253,16 @@ You can provide either:`);
       const userMatch = envContent.match(/^VM_AUTH_USERNAME=([^\r\n]+)/m);
       const passMatch = envContent.match(/^VM_AUTH_PASSWORD=([^\r\n]+)/m);
       if (userMatch)
-        vmAuthUsername = userMatch[1].trim().replace(/^["']|["']$/g, "");
+        vmAuthUsername = stripMatchingQuotes(userMatch[1]);
       if (passMatch)
-        vmAuthPassword = passMatch[1].trim().replace(/^["']|["']$/g, "");
+        vmAuthPassword = stripMatchingQuotes(passMatch[1]);
     }
     if (!vmAuthUsername || !vmAuthPassword) {
       console.log("Generating VictoriaMetrics auth credentials...");
       vmAuthUsername = vmAuthUsername || "vmauth";
       if (!vmAuthPassword) {
-        const { stdout: vmPass } = await execPromise(`openssl rand -base64 12 | tr -d '
-'`);
-        vmAuthPassword = vmPass.trim();
+        const { stdout: vmPass } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
+        vmAuthPassword = vmPass.trim().replace(/\n/g, "");
       }
       let envContent = "";
       if (fs6.existsSync(envFile2)) {
@@ -31845,7 +32480,7 @@ mon.command("config").description("show monitoring services configuration").acti
   console.log(`Project Directory: ${projectDir}`);
   console.log(`Docker Compose File: ${composeFile}`);
   console.log(`Instances File: ${instancesFile}`);
-  if (fs6.existsSync(instancesFile) && !fs6.statSync(instancesFile).isDirectory()) {
+  if (fs6.existsSync(instancesFile) && !fs6.lstatSync(instancesFile).isDirectory()) {
     console.log(`
 Instances configuration:
 `);
@@ -31871,12 +32506,12 @@ mon.command("update").description("update monitoring stack").action(async () =>
       return;
     }
     console.log("Fetching latest changes...");
-    await execPromise("git fetch origin");
-    const { stdout: branch } = await execPromise("git rev-parse --abbrev-ref HEAD");
+    await execFilePromise("git", ["fetch", "origin"]);
+    const { stdout: branch } = await execFilePromise("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
     const currentBranch = branch.trim();
     console.log(`Current branch: ${currentBranch}`);
     console.log("Pulling latest changes...");
-    const { stdout: pullOut } = await execPromise("git pull origin " + currentBranch);
+    const { stdout: pullOut } = await execFilePromise("git", ["pull", "origin", currentBranch]);
     console.log(pullOut);
     console.log(`
 Updating Docker images...`);
@@ -32020,7 +32655,7 @@ mon.command("check").description("monitoring services system readiness check").a
 var targets = mon.command("targets").description("manage databases to monitor");
 targets.command("list").description("list monitoring target databases").action(async () => {
   const { instancesFile: instancesPath, projectDir } = await resolveOrInitPaths();
-  if (!fs6.existsSync(instancesPath) || fs6.statSync(instancesPath).isDirectory()) {
+  if (!fs6.existsSync(instancesPath) || fs6.lstatSync(instancesPath).isDirectory()) {
     console.error(`instances.yml not found in ${projectDir}`);
     process.exitCode = 1;
     return;
@@ -32075,7 +32710,7 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
   const db = m[5];
   const instanceName = name && name.trim() ? name.trim() : `${host}-${db}`.replace(/[^a-zA-Z0-9-]/g, "-");
   try {
-    if (fs6.existsSync(file) && !fs6.statSync(file).isDirectory()) {
+    if (fs6.existsSync(file) && !fs6.lstatSync(file).isDirectory()) {
       const content2 = fs6.readFileSync(file, "utf8");
       const instances = load(content2) || [];
       if (Array.isArray(instances)) {
@@ -32088,15 +32723,16 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
       }
     }
   } catch (err) {
-    const isFile = fs6.existsSync(file) && !fs6.statSync(file).isDirectory();
+    const isFile = fs6.existsSync(file) && !fs6.lstatSync(file).isDirectory();
     const content2 = isFile ? fs6.readFileSync(file, "utf8") : "";
-    if (new RegExp(`^- name: ${instanceName}$`, "m").test(content2)) {
+    const escapedName = instanceName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`^- name: ${escapedName}$`, "m").test(content2)) {
       console.error(`Monitoring target '${instanceName}' already exists`);
       process.exitCode = 1;
       return;
     }
   }
-  if (fs6.existsSync(file) && fs6.statSync(file).isDirectory()) {
+  if (fs6.existsSync(file) && fs6.lstatSync(file).isDirectory()) {
     fs6.rmSync(file, { recursive: true, force: true });
   }
   const body = `- name: ${instanceName}
@@ -32118,7 +32754,7 @@ targets.command("add [connStr] [name]").description("add monitoring target datab
 });
 targets.command("remove <name>").description("remove monitoring target database").action(async (name) => {
   const { instancesFile: file } = await resolveOrInitPaths();
-  if (!fs6.existsSync(file) || fs6.statSync(file).isDirectory()) {
+  if (!fs6.existsSync(file) || fs6.lstatSync(file).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;
@@ -32147,7 +32783,7 @@ targets.command("remove <name>").description("remove monitoring target database"
 });
 targets.command("test <name>").description("test monitoring target database connectivity").action(async (name) => {
   const { instancesFile: instancesPath } = await resolveOrInitPaths();
-  if (!fs6.existsSync(instancesPath) || fs6.statSync(instancesPath).isDirectory()) {
+  if (!fs6.existsSync(instancesPath) || fs6.lstatSync(instancesPath).isDirectory()) {
     console.error("instances.yml not found");
     process.exitCode = 1;
     return;
@@ -32172,7 +32808,7 @@ targets.command("test <name>").description("test monitoring target database conn
       return;
     }
     console.log(`Testing connection to monitoring target '${name}'...`);
-    const client = new Client({ connectionString: instance.conn_str });
+    const client = new Client({ connectionString: instance.conn_str, connectionTimeoutMillis: 1e4 });
     try {
       await client.connect();
       const result = await client.query("select version();");
@@ -32441,9 +33077,8 @@ mon.command("generate-grafana-password").description("generate Grafana password
   const { projectDir } = await resolveOrInitPaths();
   const cfgPath = path6.resolve(projectDir, ".pgwatch-config");
   try {
-    const { stdout: password } = await execPromise(`openssl rand -base64 12 | tr -d '
-'`);
-    const newPassword = password.trim();
+    const { stdout: password } = await execFilePromise("openssl", ["rand", "-base64", "12"]);
+    const newPassword = password.trim().replace(/\n/g, "");
     if (!newPassword) {
       console.error("Failed to generate password");
       process.exitCode = 1;
@@ -32522,8 +33157,8 @@ Grafana credentials:`);
     if (vmUser && vmPass) {
       console.log(`
 VictoriaMetrics credentials:`);
-      console.log(`  Username: ${vmUser[1].trim().replace(/^["']|["']$/g, "")}`);
-      console.log(`  Password: ${vmPass[1].trim().replace(/^["']|["']$/g, "")}`);
+      console.log(`  Username: ${stripMatchingQuotes(vmUser[1])}`);
+      console.log(`  Password: ${stripMatchingQuotes(vmPass[1])}`);
     }
   }
   console.log("");
@@ -33262,7 +33897,7 @@ mcp.command("install [client]").description("install MCP server configuration fo
   try {
     let pgaiPath;
     try {
-      const execPath = await execPromise("which pgai");
+      const execPath = await execFilePromise("which", ["pgai"]);
       pgaiPath = execPath.stdout.trim();
     } catch {
       pgaiPath = "pgai";
@@ -33270,7 +33905,7 @@ mcp.command("install [client]").description("install MCP server configuration fo
     if (client === "claude-code") {
       console.log("Installing PostgresAI MCP server for Claude Code...");
       try {
-        const { stdout, stderr } = await execPromise(`claude mcp add -s user postgresai ${pgaiPath} mcp start`);
+        const { stdout, stderr } = await execFilePromise("claude", ["mcp", "add", "-s", "user", "postgresai", pgaiPath, "mcp", "start"]);
         if (stdout)
           console.log(stdout);
         if (stderr)