mcp-google-map 0.4.0 → 0.6.0

package/dist/cli.js

@@ -2,14 +2,177 @@
 import {
   Logger,
   PlacesSearcher
-} from "./chunk-K27FX5QH.js";
+} from "./chunk-NAUIQEK4.js";
 
 // src/cli.ts
-import { config as dotenvConfig } from "dotenv";
-import { resolve } from "path";
+import { config as dotenvConfig2 } from "dotenv";
+import { resolve as resolve5 } from "path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
+// src/utils/configResolver.ts
+import { config as dotenvConfig } from "dotenv";
+import { existsSync } from "fs";
+
+// src/utils/autoUpdate.ts
+var AUTO_UPDATE_DISABLED_ENV = "MCP_AUTO_UPDATE_DISABLED";
+var DEFAULT_PACKAGE_NAME = "mcp-google-map";
+var DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+var DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 2e3;
+async function probeLatestVersion(deps = {}) {
+  const env = deps.env ?? process.env;
+  if (isAutoUpdateDisabled(env)) {
+    return { status: "disabled" };
+  }
+  const currentVersion = deps.currentVersion;
+  if (!currentVersion) {
+    return { status: "unknown-version" };
+  }
+  const packageName = deps.packageName ?? DEFAULT_PACKAGE_NAME;
+  const registryBaseUrl = deps.registryBaseUrl ?? DEFAULT_REGISTRY_BASE_URL;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  try {
+    const response = await fetchImpl(`${registryBaseUrl}/${packageName}/latest`, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      return {
+        status: "error",
+        message: `registry responded with HTTP ${response.status}.`
+      };
+    }
+    const payload = await response.json();
+    if (typeof payload?.version !== "string") {
+      return {
+        status: "error",
+        message: "registry response has no version field."
+      };
+    }
+    if (!isNewerVersion(payload.version, currentVersion)) {
+      return { status: "current", currentVersion };
+    }
+    return { status: "newer", currentVersion, latestVersion: payload.version };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { status: "error", message };
+  }
+}
+function isAutoUpdateDisabled(env = process.env) {
+  const raw = env[AUTO_UPDATE_DISABLED_ENV];
+  return typeof raw === "string" && /^(1|true|yes)$/i.test(raw.trim());
+}
+function isNewerVersion(candidate, current) {
+  const toSegments = (version) => version.trim().split(".").map((segment) => /^\d+$/.test(segment) ? Number(segment) : Number.NaN);
+  const candidateSegments = toSegments(candidate);
+  const currentSegments = toSegments(current);
+  if (candidateSegments.some((segment) => !Number.isInteger(segment)) || currentSegments.some((segment) => !Number.isInteger(segment))) {
+    return false;
+  }
+  const length = Math.max(candidateSegments.length, currentSegments.length);
+  for (let index = 0; index < length; index += 1) {
+    const candidatePart = candidateSegments[index] ?? 0;
+    const currentPart = currentSegments[index] ?? 0;
+    if (candidatePart !== currentPart) {
+      return candidatePart > currentPart;
+    }
+  }
+  return false;
+}
+
+// src/utils/configResolver.ts
+var NODE_ENGINE_FLOOR = 22;
+var DEFAULT_HTTP_HOST = "127.0.0.1";
+var DEFAULT_HTTP_PORT = 3e3;
+function resolveRuntimeConfig(env = process.env, overrides = {}) {
+  const envPort = env.MCP_SERVER_PORT?.trim() || void 0;
+  let port;
+  let portRaw;
+  let portSource;
+  if (overrides.port !== void 0) {
+    port = overrides.port;
+    portRaw = String(overrides.port);
+    portSource = "flag";
+  } else if (envPort !== void 0) {
+    const parsed = Number(envPort);
+    port = Number.isFinite(parsed) ? parsed : void 0;
+    portRaw = envPort;
+    portSource = "environment";
+  } else {
+    port = DEFAULT_HTTP_PORT;
+    portRaw = void 0;
+    portSource = "default";
+  }
+  const apiKey = overrides.apiKey ?? env.GOOGLE_MAPS_API_KEY;
+  const enabledToolsRaw = env.GOOGLE_MAPS_ENABLED_TOOLS?.trim() || void 0;
+  return {
+    apiKey,
+    apiKeySource: overrides.apiKey !== void 0 ? "flag" : apiKey ? "environment" : "none",
+    host: overrides.host ?? env.MCP_SERVER_HOST ?? DEFAULT_HTTP_HOST,
+    hostSource: overrides.host !== void 0 ? "flag" : env.MCP_SERVER_HOST ? "environment" : "default",
+    port,
+    portRaw,
+    portSource,
+    enabledToolsRaw,
+    enabledToolsSource: enabledToolsRaw ? "environment" : "default",
+    autoUpdateDisabled: isAutoUpdateDisabled(env),
+    envFile: overrides.envFile
+  };
+}
+function maskSecret(value) {
+  if (!value) {
+    return "unset";
+  }
+  if (value.length <= 8) {
+    return "****";
+  }
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+function describeRuntimeConfig(config) {
+  return {
+    apiKey: { value: maskSecret(config.apiKey), source: config.apiKeySource },
+    httpHost: { value: config.host, source: config.hostSource },
+    httpPort: {
+      value: config.port ?? null,
+      raw: config.portRaw ?? null,
+      source: config.portSource
+    },
+    enabledTools: { value: config.enabledToolsRaw ?? "*", source: config.enabledToolsSource },
+    autoUpdateCheck: { enabled: !config.autoUpdateDisabled },
+    envFile: { value: config.envFile ?? null }
+  };
+}
+function formatConfigDiagnostics(diagnostics) {
+  return [
+    `host=${diagnostics.httpHost.value} (${diagnostics.httpHost.source})`,
+    `port=${diagnostics.httpPort.value ?? "invalid"} (raw: ${diagnostics.httpPort.raw ?? "n/a"}, ${diagnostics.httpPort.source})`,
+    `apiKey=${diagnostics.apiKey.value} (${diagnostics.apiKey.source})`,
+    `enabledTools=${diagnostics.enabledTools.value} (${diagnostics.enabledTools.source})`,
+    `updateCheck=${diagnostics.autoUpdateCheck.enabled ? "enabled" : "disabled"}`
+  ].join("; ");
+}
+function applyExplicitEnvFile(path) {
+  if (!existsSync(path)) {
+    return { ok: false, error: `env file not found: ${path}` };
+  }
+  dotenvConfig({ path });
+  return { ok: true };
+}
+function resolveEnabledToolNames(allToolNames, raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed || trimmed === "*") {
+    return { names: [...allToolNames], matched: allToolNames.length, fallback: false, requested: [] };
+  }
+  const requested = trimmed.split(",").map((item) => item.trim()).filter(Boolean);
+  const enabled = new Set(requested);
+  const names = allToolNames.filter((name) => enabled.has(name));
+  if (names.length === 0) {
+    return { names: [...allToolNames], matched: 0, fallback: true, requested };
+  }
+  return { names, matched: names.length, fallback: false, requested };
+}
+
 // src/tools/maps/searchNearby.ts
 import { z } from "zod";
 
@@ -1023,18 +1186,19 @@ var serverConfigs = [
   }
 ];
 function filterTools(tools) {
-  const raw = process.env.GOOGLE_MAPS_ENABLED_TOOLS?.trim();
-  if (!raw || raw === "*") return tools;
-  const enabled = new Set(
-    raw.split(",").map((s) => s.trim()).filter(Boolean)
+  const resolution = resolveEnabledToolNames(
+    tools.map((tool) => tool.name),
+    process.env.GOOGLE_MAPS_ENABLED_TOOLS
   );
-  const filtered = tools.filter((t) => enabled.has(t.name));
-  if (filtered.length === 0) {
+  if (resolution.fallback) {
     Logger.error(`GOOGLE_MAPS_ENABLED_TOOLS matched 0 tools. Available: ${tools.map((t) => t.name).join(", ")}`);
     return tools;
   }
-  Logger.log(`GOOGLE_MAPS_ENABLED_TOOLS: ${filtered.length}/${tools.length} tools active`);
-  return filtered;
+  if (resolution.matched !== tools.length) {
+    Logger.log(`GOOGLE_MAPS_ENABLED_TOOLS: ${resolution.matched}/${tools.length} tools active`);
+  }
+  const enabled = new Set(resolution.names);
+  return tools.filter((tool) => enabled.has(tool.name));
 }
 var config_default = serverConfigs;
 
@@ -1140,7 +1304,20 @@ var BaseMcpServer = class {
     };
     Logger.log(`${this.serverName} connected and ready to process requests`);
   }
-  async startHttpServer(port, host = "0.0.0.0") {
+  /**
+   * @brief Starts the Streamable HTTP listener and resolves once it is accepting connections.
+   * @details Builds the Express app with the `/mcp` POST/GET/DELETE handlers,
+   * then wraps `app.listen` in a Promise that resolves from the listen callback
+   * and rejects on the server `error` event (e.g. EADDRINUSE), so callers get
+   * a reliable startup outcome instead of an unhandled error. Default host is
+   * loopback `127.0.0.1` (REQ-008); pass `0.0.0.0` to bind all interfaces.
+   * @param port {number} TCP port to listen on (1-65535).
+   * @param host {string} Bind address; defaults to `127.0.0.1`.
+   * @return {Promise<void>} Resolves when listening; rejects with the listen error.
+   * @throws {Error} Rejects when the HTTP listener emits an error (port in use, permission denied).
+   * @satisfies REQ-008, REQ-095
+   */
+  async startHttpServer(port, host = "127.0.0.1") {
     const app = express();
     app.use(express.json());
     app.post("/mcp", async (req, res) => {
@@ -1212,42 +1389,53 @@ var BaseMcpServer = class {
     app.get("/mcp", handleSessionRequest);
     app.delete("/mcp", handleSessionRequest);
     const displayHost = host === "0.0.0.0" ? "localhost" : host;
-    this.httpServer = app.listen(port, host, () => {
-      Logger.log(`[${this.serverName}] HTTP server listening on ${host}:${port}`);
-      Logger.log(`[${this.serverName}] MCP endpoint available at http://${displayHost}:${port}/mcp`);
+    await new Promise((resolve6, reject) => {
+      this.httpServer = app.listen(port, host, () => {
+        Logger.log(`[${this.serverName}] HTTP server listening on ${host}:${port}`);
+        Logger.log(`[${this.serverName}] MCP endpoint available at http://${displayHost}:${port}/mcp`);
+        resolve6();
+      });
+      this.httpServer.on("error", (error) => reject(error));
     });
   }
   async startStdio() {
     const transport = new StdioServerTransport();
     await this.connect(transport);
   }
+  /**
+   * @brief Stops the HTTP listener and closes every session transport in order.
+   * @details Idempotent: when no listener exists it logs and resolves. Otherwise
+   * it detaches the server reference, clears the session map, awaits
+   * `transport.close()` for every session (errors tolerated via allSettled),
+   * calls `closeAllConnections` when available, and finally closes the socket.
+   * Wired to SIGINT/SIGTERM through `installShutdownHandlers` (REQ-096).
+   * @return {Promise<void>} Resolves after the socket closes; rejects when `server.close` errors.
+   * @throws {Error} Rejects with the `server.close` error.
+   * @satisfies REQ-096
+   */
   async stopHttpServer() {
-    if (!this.httpServer) {
+    const server = this.httpServer;
+    if (!server) {
       Logger.error(`[${this.serverName}] HTTP server is not running or already stopped.`);
       return;
     }
-    return new Promise((resolve2, reject) => {
-      this.httpServer.close((err) => {
+    this.httpServer = null;
+    const closingSessions = Object.values(this.sessions);
+    this.sessions = {};
+    await Promise.allSettled(closingSessions.map((context) => context.transport.close()));
+    if (closingSessions.length > 0) {
+      Logger.log(`[${this.serverName}] All transports closed.`);
+    }
+    return new Promise((resolve6, reject) => {
+      server.closeAllConnections?.();
+      server.close((err) => {
         if (err) {
           Logger.error(`[${this.serverName}] Error stopping HTTP server:`, err);
           reject(err);
           return;
         }
         Logger.log(`[${this.serverName}] HTTP server stopped.`);
-        this.httpServer = null;
-        const closingSessions = Object.values(this.sessions).map((context) => {
-          if (context.transport.sessionId) {
-            delete this.sessions[context.transport.sessionId];
-          }
-          return Promise.resolve();
-        });
-        Promise.all(closingSessions).then(() => {
-          Logger.log(`[${this.serverName}] All transports closed.`);
-          resolve2();
-        }).catch((transportCloseErr) => {
-          Logger.error(`[${this.serverName}] Error during bulk transport closing:`, transportCloseErr);
-          reject(transportCloseErr);
-        });
+        resolve6();
       });
     });
   }
@@ -1255,90 +1443,851 @@ var BaseMcpServer = class {
 
 // src/cli.ts
 import { fileURLToPath } from "url";
-import { dirname } from "path";
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { dirname as dirname2 } from "path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "fs";
 import { createInterface } from "readline";
 
-// src/utils/autoUpdate.ts
-var AUTO_UPDATE_DISABLED_ENV = "MCP_AUTO_UPDATE_DISABLED";
-var DEFAULT_PACKAGE_NAME = "mcp-google-map";
-var DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
-var DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 2e3;
-function isAutoUpdateDisabled(env = process.env) {
-  const raw = env[AUTO_UPDATE_DISABLED_ENV];
-  return typeof raw === "string" && /^(1|true|yes)$/i.test(raw.trim());
+// src/utils/upgradeManager.ts
+import { spawnSync } from "child_process";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { dirname, join as join2 } from "path";
+
+// src/utils/cliSettings.ts
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+var SETTINGS_PROGRAM_NAME = "mcp-google-map";
+var CLI_SETTINGS_RELATIVE = [".config", SETTINGS_PROGRAM_NAME, "config.json"];
+var MCP_SERVER_NAME = "mcp-google-map";
+function resolveCliSettingsPath(home) {
+  const root = home ?? (process.env.HOME ?? process.cwd());
+  return resolve(root, ...CLI_SETTINGS_RELATIVE);
 }
-function isNewerVersion(candidate, current) {
-  const toSegments = (version) => version.trim().split(".").map((segment) => /^\d+$/.test(segment) ? Number(segment) : Number.NaN);
-  const candidateSegments = toSegments(candidate);
-  const currentSegments = toSegments(current);
-  if (candidateSegments.some((segment) => !Number.isInteger(segment)) || currentSegments.some((segment) => !Number.isInteger(segment))) {
-    return false;
+function uniqueStrings(value) {
+  if (!Array.isArray(value)) return [];
+  const result = [];
+  for (const item of value) {
+    if (typeof item === "string" && item.length > 0 && !result.includes(item)) {
+      result.push(item);
+    }
   }
-  const length = Math.max(candidateSegments.length, currentSegments.length);
-  for (let index = 0; index < length; index += 1) {
-    const candidatePart = candidateSegments[index] ?? 0;
-    const currentPart = currentSegments[index] ?? 0;
-    if (candidatePart !== currentPart) {
-      return candidatePart > currentPart;
+  return result;
+}
+function loadCliSettings(home) {
+  try {
+    const raw = JSON.parse(readFileSync(resolveCliSettingsPath(home), "utf-8"));
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return { enabled: [] };
     }
+    return { enabled: uniqueStrings(raw.enabled) };
+  } catch {
+    return { enabled: [] };
   }
-  return false;
 }
-async function checkForUpdates(deps = {}) {
-  const logger = deps.logger ?? Logger;
-  const env = deps.env ?? process.env;
+function saveCliSettings(settings, home) {
+  const path = resolveCliSettingsPath(home);
+  const temporary = `${path}.tmp`;
   try {
-    if (isAutoUpdateDisabled(env)) {
-      return null;
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(temporary, JSON.stringify({ enabled: uniqueStrings(settings.enabled) }, null, 2) + "\n", "utf-8");
+    renameSync(temporary, path);
+  } catch (error) {
+    throw new Error(`settings write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return path;
+}
+
+// src/utils/upgradeManager.ts
+var ANSI_GREEN = "\x1B[92m";
+var ANSI_RED = "\x1B[91m";
+var ANSI_RESET = "\x1B[0m";
+var green = (text) => `${ANSI_GREEN}${text}${ANSI_RESET}`;
+var red = (text) => `${ANSI_RED}${text}${ANSI_RESET}`;
+var IDLE_CACHE_DIR_NAME = "mcp-google-map";
+var IDLE_CACHE_FILE_NAME = "check_version_idle-time.json";
+var IDLE_WINDOW_NEWER_MS = 60 * 60 * 1e3;
+var IDLE_WINDOW_DEFAULT_MS = 24 * 60 * 60 * 1e3;
+var PACKAGE_UPGRADE_COMMAND = [
+  "npm",
+  "install",
+  "-g",
+  `${DEFAULT_PACKAGE_NAME}@latest`
+];
+var PACKAGE_UNINSTALL_COMMAND = [
+  "npm",
+  "uninstall",
+  "-g",
+  DEFAULT_PACKAGE_NAME
+];
+var POST_UPGRADE_INSTALL_COMMAND = [
+  "npx",
+  "-y",
+  DEFAULT_PACKAGE_NAME,
+  "install"
+];
+function resolveIdleCachePath(home) {
+  return join2(home ?? homedir(), ".cache", IDLE_CACHE_DIR_NAME, IDLE_CACHE_FILE_NAME);
+}
+function loadIdleCache(cachePath, fs = {}) {
+  try {
+    const readFile = fs.readFile ?? ((path) => readFileSync2(path, "utf-8"));
+    const raw = readFile(cachePath);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
     }
-    const currentVersion = deps.currentVersion;
-    if (!currentVersion) {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check skipped: running package version is unknown.`
+    const record = parsed;
+    const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+    return {
+      last_success_epoch: isFiniteNumber(record.last_success_epoch) ? record.last_success_epoch : void 0,
+      last_success_human: typeof record.last_success_human === "string" ? record.last_success_human : void 0,
+      idle_time_epoch: isFiniteNumber(record.idle_time_epoch) ? record.idle_time_epoch : void 0,
+      idle_time_human: typeof record.idle_time_human === "string" ? record.idle_time_human : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function persistIdleCache(cachePath, lastSuccess, idleUntil, fs = {}, logger = Logger) {
+  const toIso = (epoch) => epoch === void 0 ? null : new Date(epoch).toISOString();
+  const data = {
+    last_success_epoch: lastSuccess ?? null,
+    last_success_human: toIso(lastSuccess),
+    idle_time_epoch: idleUntil,
+    idle_time_human: toIso(idleUntil)
+  };
+  try {
+    const mkdir = fs.mkdir ?? ((path) => mkdirSync2(path, { recursive: true }));
+    const writeFile = fs.writeFile ?? ((path, data2) => writeFileSync2(path, data2));
+    mkdir(dirname(cachePath));
+    writeFile(cachePath, JSON.stringify(data, null, 2) + "\n");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(red(`Version cache error: ${message}`));
+  }
+}
+async function checkVersionIdle(deps = {}) {
+  const logger = deps.logger ?? Logger;
+  const now = deps.now ?? (() => Date.now());
+  const cachePath = deps.cachePath ?? resolveIdleCachePath();
+  const cache = loadIdleCache(cachePath, deps.fs);
+  if (deps.force !== true) {
+    const idle = cache.idle_time_epoch;
+    if (typeof idle === "number" && idle > now()) {
+      return { checked: false, status: "idle" };
+    }
+  }
+  const probe = await probeLatestVersion(deps);
+  if (probe.status === "disabled") {
+    return { checked: false, status: "disabled" };
+  }
+  let delayMs = IDLE_WINDOW_DEFAULT_MS;
+  let lastSuccess = typeof cache.last_success_epoch === "number" ? cache.last_success_epoch : void 0;
+  const result = { checked: true, status: probe.status };
+  switch (probe.status) {
+    case "unknown-version":
+      logger.error(red("Version check error: running package version is unknown."));
+      break;
+    case "error":
+      logger.error(red(`Version check error: ${probe.message}`));
+      break;
+    case "current":
+      lastSuccess = now();
+      result.currentVersion = probe.currentVersion;
+      logger.error(red("Version check: no newer version available."));
+      break;
+    case "newer": {
+      lastSuccess = now();
+      delayMs = IDLE_WINDOW_NEWER_MS;
+      result.currentVersion = probe.currentVersion;
+      result.latestVersion = probe.latestVersion;
+      logger.log(
+        green(
+          `Available Version: ${probe.latestVersion} | Installed Version: ${probe.currentVersion}`
+        )
       );
-      return null;
+      logger.log(
+        green(
+          `Upgrade with: npm install -g ${DEFAULT_PACKAGE_NAME}@latest (or run: ${DEFAULT_PACKAGE_NAME} --upgrade)`
+        )
+      );
+      break;
     }
-    const packageName = deps.packageName ?? DEFAULT_PACKAGE_NAME;
-    const registryBaseUrl = deps.registryBaseUrl ?? DEFAULT_REGISTRY_BASE_URL;
-    const timeoutMs = deps.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS;
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const response = await fetchImpl(`${registryBaseUrl}/${packageName}/latest`, {
-      headers: { accept: "application/vnd.npm.install-v1+json" },
-      signal: AbortSignal.timeout(timeoutMs)
+  }
+  const finishedAt = now();
+  const idleUntil = finishedAt + delayMs;
+  persistIdleCache(cachePath, lastSuccess, idleUntil, deps.fs, logger);
+  result.idleUntilEpoch = idleUntil;
+  result.lastSuccessEpoch = lastSuccess;
+  return result;
+}
+function parseManagementCommand(args) {
+  if (args.length !== 1) {
+    return void 0;
+  }
+  const arg = args[0];
+  if (arg === "--ver" || arg === "--version" || arg === "--upgrade" || arg === "--uninstall") {
+    return arg;
+  }
+  return void 0;
+}
+function runPackageManagerCommand(command, deps = {}) {
+  const logger = deps.logger ?? Logger;
+  const spawnImpl = deps.spawn ?? spawnSync;
+  const reportSpawnFailure = (message) => {
+    logger.error(`Error executing ${command[0]}: ${message}`);
+    logger.log(`Warning: run this command manually: ${command.join(" ")}`);
+    return 1;
+  };
+  try {
+    const result = spawnImpl(command[0], [...command.slice(1)], {
+      stdio: "inherit",
+      shell: process.platform === "win32"
     });
-    if (!response.ok) {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: registry responded with HTTP ${response.status}.`
-      );
-      return null;
+    if (result.error) {
+      return reportSpawnFailure(result.error.message);
     }
-    const payload = await response.json();
-    if (typeof payload?.version !== "string") {
-      logger.error(
-        `\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: registry response has no version field.`
+    return result.status ?? 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return reportSpawnFailure(message);
+  }
+}
+function runPostUpgradeSkillInstall(options, deps = {}) {
+  const enabled = loadCliSettings(options.home).enabled;
+  if (enabled.length === 0) {
+    return 0;
+  }
+  return runPackageManagerCommand(POST_UPGRADE_INSTALL_COMMAND, deps);
+}
+async function runVersionCommand(options, deps = {}) {
+  await checkVersionIdle({
+    ...deps.idleCheck,
+    force: true,
+    currentVersion: options.currentVersion
+  });
+  const stdout = deps.stdout ?? process.stdout;
+  stdout.write(`${options.currentVersion}
+`);
+  return 0;
+}
+function runUpgradeCommand(options, deps = {}) {
+  const upgraded = runPackageManagerCommand(PACKAGE_UPGRADE_COMMAND, deps);
+  if (upgraded !== 0) {
+    return upgraded;
+  }
+  return runPostUpgradeSkillInstall(options, deps);
+}
+function runUninstallCommand(deps = {}) {
+  return runPackageManagerCommand(PACKAGE_UNINSTALL_COMMAND, deps);
+}
+async function runManagementCommand(command, options, deps = {}) {
+  switch (command) {
+    case "--ver":
+    case "--version":
+      return runVersionCommand(options, deps);
+    case "--upgrade":
+      return runUpgradeCommand(options, deps);
+    case "--uninstall":
+      return runUninstallCommand(deps);
+  }
+}
+
+// src/utils/toolProfiles.ts
+var TOOL_API_PROFILES = {
+  maps_geocode: { tool: "maps_geocode", apis: ["geocoding"], dependsOnTools: [] },
+  maps_reverse_geocode: { tool: "maps_reverse_geocode", apis: ["geocoding"], dependsOnTools: [] },
+  maps_batch_geocode: { tool: "maps_batch_geocode", apis: ["geocoding"], dependsOnTools: ["maps_geocode"] },
+  maps_search_nearby: {
+    tool: "maps_search_nearby",
+    apis: ["places-new", "geocoding"],
+    dependsOnTools: ["maps_geocode"]
+  },
+  maps_search_places: { tool: "maps_search_places", apis: ["places-new"], dependsOnTools: [] },
+  maps_place_details: { tool: "maps_place_details", apis: ["places-new"], dependsOnTools: [] },
+  maps_directions: { tool: "maps_directions", apis: ["routes"], dependsOnTools: [] },
+  maps_distance_matrix: { tool: "maps_distance_matrix", apis: ["routes"], dependsOnTools: [] },
+  maps_elevation: { tool: "maps_elevation", apis: ["elevation"], dependsOnTools: [] },
+  maps_timezone: { tool: "maps_timezone", apis: ["timezone"], dependsOnTools: [] },
+  maps_weather: { tool: "maps_weather", apis: ["weather"], dependsOnTools: [] },
+  maps_air_quality: { tool: "maps_air_quality", apis: ["air-quality"], dependsOnTools: [] },
+  maps_static_map: { tool: "maps_static_map", apis: ["static-maps"], dependsOnTools: [] },
+  maps_explore_area: {
+    tool: "maps_explore_area",
+    apis: ["places-new", "geocoding"],
+    dependsOnTools: ["maps_geocode", "maps_search_nearby", "maps_place_details"]
+  },
+  maps_plan_route: {
+    tool: "maps_plan_route",
+    apis: ["routes", "geocoding", "places-new"],
+    dependsOnTools: ["maps_geocode", "maps_search_places", "maps_directions"]
+  },
+  maps_compare_places: {
+    tool: "maps_compare_places",
+    apis: ["places-new", "routes"],
+    dependsOnTools: ["maps_search_places", "maps_place_details", "maps_distance_matrix"]
+  },
+  maps_search_along_route: {
+    tool: "maps_search_along_route",
+    apis: ["routes", "places-new"],
+    dependsOnTools: ["maps_directions", "maps_search_places"]
+  },
+  maps_local_rank_tracker: {
+    tool: "maps_local_rank_tracker",
+    apis: ["places-new"],
+    dependsOnTools: ["maps_place_details", "maps_search_places"]
+  }
+};
+function describeToolsProfile(toolNames) {
+  const tools = [];
+  const apiOrder = [];
+  const seenApis = /* @__PURE__ */ new Set();
+  const seenTools = /* @__PURE__ */ new Set();
+  for (const name of toolNames) {
+    if (seenTools.has(name)) {
+      continue;
+    }
+    const profile = TOOL_API_PROFILES[name];
+    if (!profile) {
+      continue;
+    }
+    seenTools.add(name);
+    tools.push({
+      tool: profile.tool,
+      apis: [...profile.apis],
+      dependsOnTools: [...profile.dependsOnTools]
+    });
+    for (const api of profile.apis) {
+      if (!seenApis.has(api)) {
+        seenApis.add(api);
+        apiOrder.push(api);
+      }
+    }
+  }
+  return { toolCount: tools.length, apis: apiOrder, tools };
+}
+
+// src/utils/clientSnippets.ts
+var API_KEY_PLACEHOLDER = "<your-google-maps-api-key>";
+var SNIPPET_DEFAULT_HOST = "127.0.0.1";
+var SNIPPET_DEFAULT_PORT = 3e3;
+var SNIPPET_CLIENT_TARGETS = {
+  generic: "your MCP client configuration file",
+  claude: "Claude Desktop: claude_desktop_config.json",
+  cursor: "Cursor: .cursor/mcp.json",
+  pi: "pi CLI: ~/.pi/agent/mcp.json (user) or .pi/mcp.json (project)"
+};
+function renderClientSnippet(options = {}) {
+  const client = options.client ?? "generic";
+  const transport = options.transport ?? "stdio";
+  const serverName = options.serverName ?? "mcp-google-map";
+  const notes = [`Paste this snippet into ${SNIPPET_CLIENT_TARGETS[client]}.`];
+  notes.push("This command prints the snippet only; it never writes or edits configuration files.");
+  let entry;
+  if (transport === "http") {
+    const host = options.host ?? SNIPPET_DEFAULT_HOST;
+    const port = options.port ?? SNIPPET_DEFAULT_PORT;
+    entry = { url: `http://${host}:${port}/mcp` };
+    notes.push(`Start the server first: mcp-google-map --host ${host} --port ${port}.`);
+  } else {
+    const launcher = options.launcher ?? "npx";
+    if (launcher === "node" && !options.commandPath) {
+      throw new Error("--launcher node requires --command <path> pointing at dist/cli.js");
+    }
+    const command = launcher === "npx" ? "npx" : launcher === "bin" ? "mcp-google-map" : "node";
+    const args = launcher === "npx" ? ["-y", "mcp-google-map", "--stdio"] : launcher === "bin" ? ["--stdio"] : [options.commandPath, "--stdio"];
+    if (launcher === "npx") {
+      notes.push("The npx launcher runs the published package; npm must be available on PATH.");
+    }
+    const apiKeyValue = options.envKey ? `\${${options.envKey}}` : API_KEY_PLACEHOLDER;
+    entry = { command, args, env: { GOOGLE_MAPS_API_KEY: apiKeyValue } };
+    if (options.envKey) {
+      notes.push(
+        `Variable references (\${${options.envKey}}) are client-specific: confirm your client expands environment variables before relying on them.`
       );
-      return null;
+    } else {
+      notes.push(`Replace ${API_KEY_PLACEHOLDER} with your Google Maps API key.`);
     }
-    if (!isNewerVersion(payload.version, currentVersion)) {
-      return null;
+  }
+  const json = JSON.stringify({ mcpServers: { [serverName]: entry } }, null, 2);
+  return { json, notes };
+}
+
+// src/utils/cliTargets.ts
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
+  readdirSync,
+  renameSync as renameSync2,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { join as join3, relative } from "path";
+function homeRoot(home) {
+  return home ?? (process.env.HOME ?? process.cwd());
+}
+var PI_TARGET = {
+  id: "pi",
+  configFormat: "json",
+  mcpConfigPath: (home) => join3(homeRoot(home), ".pi", "agent", "mcp.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".pi", "agent", "skills")
+};
+var OPENCLAW_TARGET = {
+  id: "openclaw",
+  configFormat: "json",
+  mcpConfigPath: (home) => join3(homeRoot(home), ".openclaw", "openclaw.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".openclaw", "workspace", "skills")
+};
+var CODEX_TARGET = {
+  id: "codex",
+  configFormat: "toml",
+  mcpConfigPath: (home) => join3(homeRoot(home), ".codex", "config.toml"),
+  skillsDir: (home) => join3(homeRoot(home), ".codex", "skills")
+};
+var ANTIGRAVITY_TARGET = {
+  id: "antigravity",
+  configFormat: "json",
+  mcpConfigPath: (home) => join3(homeRoot(home), ".gemini", "settings.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".gemini", "config", "skills")
+};
+var CLAUDE_TARGET = {
+  id: "claude",
+  configFormat: "json",
+  mcpConfigPath: (home) => join3(homeRoot(home), ".claude.json"),
+  skillsDir: (home) => join3(homeRoot(home), ".claude", "skills")
+};
+var CLI_TARGETS = {
+  pi: PI_TARGET,
+  openclaw: OPENCLAW_TARGET,
+  codex: CODEX_TARGET,
+  antigravity: ANTIGRAVITY_TARGET,
+  claude: CLAUDE_TARGET
+};
+function resolveCliTarget(name) {
+  return CLI_TARGETS[name.trim().toLowerCase()];
+}
+function supportedCliNames() {
+  return Object.keys(CLI_TARGETS).join(", ");
+}
+function readJsonConfig(configPath) {
+  if (!existsSync2(configPath)) return {};
+  const parsed = JSON.parse(readFileSync3(configPath, "utf-8"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`configuration is not a JSON object: ${configPath}`);
+  }
+  return parsed;
+}
+function writeJsonConfig(configPath, value) {
+  const temporary = `${configPath}.tmp`;
+  mkdirSync3(join3(configPath, ".."), { recursive: true });
+  writeFileSync3(temporary, JSON.stringify(value, null, 2) + "\n", "utf-8");
+  renameSync2(temporary, configPath);
+}
+function writeJsonMcpServerEntry(configPath, serverName, entry) {
+  const config = readJsonConfig(configPath);
+  const mcpServers = config.mcpServers ?? {};
+  if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`mcpServers is not an object: ${configPath}`);
+  }
+  mcpServers[serverName] = entry;
+  config.mcpServers = mcpServers;
+  writeJsonConfig(configPath, config);
+}
+function removeJsonMcpServerEntry(configPath, serverName) {
+  if (!existsSync2(configPath)) return false;
+  const config = readJsonConfig(configPath);
+  const mcpServers = config.mcpServers;
+  if (mcpServers === void 0) return false;
+  if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`mcpServers is not an object: ${configPath}`);
+  }
+  const map = mcpServers;
+  if (!(serverName in map)) return false;
+  delete map[serverName];
+  config.mcpServers = map;
+  writeJsonConfig(configPath, config);
+  return true;
+}
+function readJsonMcpServerEntry(configPath, serverName) {
+  try {
+    const config = readJsonConfig(configPath);
+    const mcpServers = config.mcpServers;
+    if (mcpServers === null || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+      return void 0;
     }
-    logger.log(
-      `\u26A0\uFE0F  Update available: ${packageName} ${currentVersion} \u2192 ${payload.version}. Upgrade with: npm install -g ${packageName}@latest (or run npx -y ${packageName}@latest).`
-    );
-    return { currentVersion, latestVersion: payload.version };
+    return mcpServers[serverName];
+  } catch {
+    return void 0;
+  }
+}
+function tomlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function tomlSectionHeader(serverName) {
+  return `[mcp_servers.${serverName}]`;
+}
+function removeTomlSection(content, serverName) {
+  const lines = content.split("\n");
+  const header = tomlSectionHeader(serverName);
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (skipping) {
+      if (line.trimStart().startsWith("[")) {
+        skipping = false;
+      } else {
+        continue;
+      }
+    } else if (line.trim() === header) {
+      skipping = true;
+      while (kept.length > 0 && kept[kept.length - 1].trim() === "") {
+        kept.pop();
+      }
+      continue;
+    }
+    kept.push(line);
+  }
+  while (kept.length > 0 && kept[kept.length - 1].trim() === "") {
+    kept.pop();
+  }
+  return kept.length > 0 ? kept.join("\n") + "\n" : "";
+}
+function hasTomlSection(content, serverName) {
+  return content.split("\n").some((line) => line.trim() === tomlSectionHeader(serverName));
+}
+function registrationToTomlLines(entry) {
+  const lines = [`command = ${tomlString(entry.command)}`];
+  if (entry.args !== void 0) {
+    lines.push(`args = [${entry.args.map((arg) => tomlString(arg)).join(", ")}]`);
+  }
+  if (entry.env !== void 0) {
+    const pairs = Object.entries(entry.env).map(([key, value]) => `${tomlString(key)} = ${tomlString(value)}`);
+    if (pairs.length > 0) lines.push(`env = { ${pairs.join(", ")} }`);
+  }
+  return lines;
+}
+function writeTomlMcpServerSection(configPath, serverName, entry) {
+  const previous = existsSync2(configPath) ? readFileSync3(configPath, "utf-8") : "";
+  const base = removeTomlSection(previous, serverName);
+  const table = [tomlSectionHeader(serverName), ...registrationToTomlLines(entry), ""].join("\n");
+  const content = base.length > 0 ? base.replace(/\n*$/, "\n") + table : table;
+  const temporary = `${configPath}.tmp`;
+  mkdirSync3(join3(configPath, ".."), { recursive: true });
+  writeFileSync3(temporary, content, "utf-8");
+  renameSync2(temporary, configPath);
+}
+function removeTomlMcpServerSection(configPath, serverName) {
+  if (!existsSync2(configPath)) return false;
+  const previous = readFileSync3(configPath, "utf-8");
+  if (!hasTomlSection(previous, serverName)) return false;
+  const content = removeTomlSection(previous, serverName);
+  const temporary = `${configPath}.tmp`;
+  writeFileSync3(temporary, content, "utf-8");
+  renameSync2(temporary, configPath);
+  return true;
+}
+function hasTomlMcpServerSection(configPath, serverName) {
+  if (!existsSync2(configPath)) return false;
+  return hasTomlSection(readFileSync3(configPath, "utf-8"), serverName);
+}
+function listFilesRecursive(root) {
+  if (!existsSync2(root)) return [];
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join3(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        files.push(relative(root, full).split("\\").join("/"));
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+function syncSkillTree(source, destination) {
+  mkdirSync3(destination, { recursive: true });
+  cpSync(source, destination, { recursive: true, force: true });
+  const expected = new Set(listFilesRecursive(source));
+  const existing = listFilesRecursive(destination);
+  existing.sort((a, b) => b.length - a.length);
+  for (const rel of existing) {
+    if (expected.has(rel)) continue;
+    rmSync(join3(destination, rel), { recursive: true, force: true });
+  }
+}
+function removeSkillDir(skillDir) {
+  rmSync(skillDir, { recursive: true, force: true });
+}
+function compareSkillTree(source, destination) {
+  const packaged = listFilesRecursive(source);
+  if (packaged.length === 0) return "MISSING";
+  if (!existsSync2(destination)) return "MISSING";
+  for (const rel of packaged) {
+    const target = join3(destination, ...rel.split("/"));
+    if (!existsSync2(target)) return "MISSING";
+    if (readFileSync3(target).toString("utf-8") !== readFileSync3(join3(source, ...rel.split("/"))).toString("utf-8")) {
+      return "STALE";
+    }
+  }
+  return "OK";
+}
+function isServerRegistered(target, serverName, home) {
+  const configPath = target.mcpConfigPath(home);
+  if (target.configFormat === "toml") {
+    return hasTomlMcpServerSection(configPath, serverName);
+  }
+  return readJsonMcpServerEntry(configPath, serverName) !== void 0;
+}
+function applyServerRegistration(target, serverName, entry, home) {
+  const configPath = target.mcpConfigPath(home);
+  if (target.configFormat === "toml") {
+    if (entry === void 0) {
+      removeTomlMcpServerSection(configPath, serverName);
+    } else {
+      writeTomlMcpServerSection(configPath, serverName, entry);
+    }
+    return;
+  }
+  if (entry === void 0) {
+    removeJsonMcpServerEntry(configPath, serverName);
+  } else {
+    writeJsonMcpServerEntry(configPath, serverName, entry);
+  }
+}
+
+// src/utils/cliInstaller.ts
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { join as join4, resolve as resolve3 } from "path";
+function buildServerRegistration(apiKey) {
+  const env = {};
+  if (apiKey !== void 0 && apiKey.length > 0) {
+    env.GOOGLE_MAPS_API_KEY = apiKey;
+  }
+  return { command: "npx", args: ["-y", MCP_SERVER_NAME, "--stdio"], env };
+}
+function resolveSkillsResourcesRoot(packageRoot) {
+  const candidate = resolve3(packageRoot, "src", "resources", "skills");
+  if (!existsSync3(candidate)) {
+    throw new Error(`skills resources root not found: ${candidate}`);
+  }
+  return candidate;
+}
+function loadSkillsManifest(resourcesRoot) {
+  const manifestPath = join4(resourcesRoot, "manifest.json");
+  if (!existsSync3(manifestPath)) {
+    throw new Error(`skills manifest not found: ${manifestPath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync4(manifestPath, "utf-8"));
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(`\u26A0\uFE0F  [${DEFAULT_PACKAGE_NAME}] Automatic update check failed: ${message}`);
-    return null;
+    throw new Error(`skills manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const skills = parsed?.skills;
+  if (!Array.isArray(skills)) {
+    throw new Error(`skills manifest has no skills array: ${manifestPath}`);
   }
+  return skills.map((entry) => {
+    const skill = entry;
+    if (typeof skill.id !== "string" || typeof skill.path !== "string") {
+      throw new Error(`skills manifest entry is missing id or path: ${manifestPath}`);
+    }
+    if (!existsSync3(join4(resourcesRoot, skill.path))) {
+      throw new Error(`manifest skill file not found: ${join4(resourcesRoot, skill.path)}`);
+    }
+    return {
+      id: skill.id,
+      name: skill.name ?? skill.id,
+      version: skill.version ?? "",
+      path: skill.path,
+      description: skill.description ?? ""
+    };
+  });
+}
+function installEnabledCliResources(options) {
+  const manifest = loadSkillsManifest(options.resourcesRoot);
+  const entry = buildServerRegistration(options.apiKey);
+  const result = { summaries: [], errors: [] };
+  for (const cli of loadCliSettings(options.home).enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) {
+      result.errors.push(`Unsupported CLI: ${cli}`);
+      continue;
+    }
+    try {
+      applyServerRegistration(target, MCP_SERVER_NAME, entry, options.home);
+      let skills = 0;
+      for (const skill of manifest) {
+        syncSkillTree(join4(options.resourcesRoot, skill.id), join4(target.skillsDir(options.home), skill.id));
+        skills += 1;
+      }
+      result.summaries.push({ cli: target.id, server: 1, skills });
+    } catch (error) {
+      result.errors.push(`${target.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return result;
+}
+function uninstallEnabledCliResources(options) {
+  const manifest = loadSkillsManifest(options.resourcesRoot);
+  const result = { summaries: [], errors: [] };
+  for (const cli of loadCliSettings(options.home).enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) {
+      result.errors.push(`Unsupported CLI: ${cli}`);
+      continue;
+    }
+    try {
+      applyServerRegistration(target, MCP_SERVER_NAME, void 0, options.home);
+      let skills = 0;
+      for (const skill of manifest) {
+        removeSkillDir(join4(target.skillsDir(options.home), skill.id));
+        skills += 1;
+      }
+      result.summaries.push({ cli: target.id, server: 0, skills });
+    } catch (error) {
+      result.errors.push(`${target.id}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return result;
+}
+
+// src/utils/cliShow.ts
+import { join as join5 } from "path";
+import { relative as relative2, resolve as resolve4 } from "path";
+var MAX_CELL_WIDTH = 48;
+var STATUS_OK = "OK";
+var STATUS_MISSING = "MISSING";
+function wrapCell(text, width) {
+  const normalized = String(text).split(/\s+/).filter((word) => word.length > 0);
+  if (normalized.length === 0) return [""];
+  const lines = [];
+  let current = "";
+  for (let word of normalized) {
+    while (word.length > width) {
+      if (current.length > 0) {
+        lines.push(current);
+        current = "";
+      }
+      lines.push(word.slice(0, width));
+      word = word.slice(width);
+    }
+    if (current.length === 0) {
+      current = word;
+    } else if (current.length + 1 + word.length <= width) {
+      current = `${current} ${word}`;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines.length > 0 ? lines : [""];
+}
+function renderAsciiTable(headers, rows, maxWidth = MAX_CELL_WIDTH) {
+  const widths = headers.map((header, index) => {
+    const lengths = [header.length, ...rows.map((row) => (row[index] ?? "").length)];
+    return Math.max(1, Math.min(Math.max(...lengths), Math.max(1, maxWidth)));
+  });
+  const border = "+" + widths.map((width) => "-".repeat(width + 2)).join("+") + "+";
+  const renderRow = (cells) => {
+    const wrapped = cells.map((cell, index) => wrapCell(cell ?? "", widths[index]));
+    const height = Math.max(...wrapped.map((part) => part.length));
+    const lines = [];
+    for (let line = 0; line < height; line += 1) {
+      const parts = wrapped.map((part, index) => (part[line] ?? "").padEnd(widths[index]));
+      lines.push("| " + parts.join(" | ") + " |");
+    }
+    return lines;
+  };
+  const output = [border, ...renderRow(headers), border];
+  for (const row of rows) {
+    output.push(...renderRow(row));
+    output.push(border);
+  }
+  return output.join("\n");
+}
+function buildCliRows(home) {
+  const root = home ?? (process.env.HOME ?? process.cwd());
+  const enabled = new Set(loadCliSettings(home).enabled);
+  return Object.keys(CLI_TARGETS).map((id) => {
+    const target = CLI_TARGETS[id];
+    return [
+      target.id,
+      enabled.has(id) ? "yes" : "no",
+      relative2(resolve4(root), resolve4(target.mcpConfigPath(home))).split("\\").join("/"),
+      relative2(resolve4(root), resolve4(target.skillsDir(home))).split("\\").join("/")
+    ];
+  });
+}
+function buildInstallRows(home, resourcesRoot) {
+  const enabled = loadCliSettings(home).enabled;
+  const manifest = loadSkillsManifest(resourcesRoot);
+  const rows = [];
+  for (const cli of enabled) {
+    const target = CLI_TARGETS[cli];
+    if (target === void 0) continue;
+    rows.push([
+      "Server",
+      MCP_SERVER_NAME,
+      target.id,
+      "yes",
+      isServerRegistered(target, MCP_SERVER_NAME, home) ? STATUS_OK : STATUS_MISSING
+    ]);
+    for (const skill of manifest) {
+      rows.push([
+        "Skill",
+        skill.id,
+        target.id,
+        "yes",
+        compareSkillTree(join5(resourcesRoot, skill.id), join5(target.skillsDir(home), skill.id))
+      ]);
+    }
+  }
+  return rows;
+}
+function buildCliShowReport(options) {
+  return [
+    "CLI Configuration",
+    renderAsciiTable(["CLI", "Enabled", "MCP Config Path", "Skills Config Path"], buildCliRows(options.home)),
+    "",
+    "Installation Status",
+    renderAsciiTable(["Type", "Name", "CLI", "Enabled", "Installed"], buildInstallRows(options.home, options.resourcesRoot))
+  ].join("\n");
 }
 
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
-dotenvConfig({ path: resolve(process.cwd(), ".env") });
-dotenvConfig({ path: resolve(__dirname, "../.env") });
+var __dirname = dirname2(__filename);
+function extractEnvFileOption(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--env-file" && i + 1 < argv.length) {
+      return argv[i + 1];
+    }
+    if (arg.startsWith("--env-file=")) {
+      return arg.slice("--env-file=".length);
+    }
+  }
+  return void 0;
+}
+function loadEnvironment(envFile) {
+  if (envFile !== void 0) {
+    const result = applyExplicitEnvFile(envFile);
+    if (!result.ok) {
+      process.stderr.write(JSON.stringify({ error: result.error }, null, 2) + "\n");
+      process.exit(1);
+    }
+    return;
+  }
+  dotenvConfig2({ path: resolve5(process.cwd(), ".env") });
+  dotenvConfig2({ path: resolve5(__dirname, "../.env") });
+}
 async function startServer(port, apiKey, host) {
   if (port) {
     process.env.MCP_SERVER_PORT = port.toString();
@@ -1355,36 +2304,69 @@ async function startServer(port, apiKey, host) {
     "\u2139\uFE0F  Reminder: enable Places API (New) in https://console.cloud.google.com before using the new Place features."
   );
   Logger.log("");
-  const startPromises = config_default.map(async (config) => {
-    const portString = process.env[config.portEnvVar];
-    if (!portString) {
-      Logger.error(`\u26A0\uFE0F  [${config.name}] Port environment variable ${config.portEnvVar} not set.`);
-      Logger.log(`\u{1F4A1} Please set ${config.portEnvVar} in your .env file or use --port parameter.`);
-      Logger.log(`   Example: ${config.portEnvVar}=3000 or --port 3000`);
-      return;
-    }
-    const serverPort = Number(portString);
-    if (isNaN(serverPort) || serverPort <= 0) {
-      Logger.error(`\u274C [${config.name}] Invalid port number "${portString}" defined in ${config.portEnvVar}.`);
-      return;
-    }
-    try {
-      const server = new BaseMcpServer(config.name, filterTools(config.tools));
-      const serverHost = process.env.MCP_SERVER_HOST || "0.0.0.0";
-      Logger.log(`\u{1F527} [${config.name}] Initializing MCP Server in HTTP mode on ${serverHost}:${serverPort}...`);
-      await server.startHttpServer(serverPort, serverHost);
-      const displayHost = serverHost === "0.0.0.0" ? "localhost" : serverHost;
-      Logger.log(`\u2705 [${config.name}] MCP Server started successfully!`);
-      Logger.log(`   \u{1F310} Endpoint: http://${displayHost}:${serverPort}/mcp`);
-      Logger.log(`   \u{1F4DA} Tools: ${config.tools.length} available`);
-    } catch (error) {
-      Logger.error(`\u274C [${config.name}] Failed to start MCP Server on port ${serverPort}:`, error);
-    }
-  });
-  await Promise.allSettled(startPromises);
+  const servers = [];
+  let started = 0;
+  let failed = 0;
+  await Promise.all(
+    config_default.map(async (config) => {
+      const portString = process.env[config.portEnvVar];
+      if (!portString) {
+        Logger.error(`\u26A0\uFE0F  [${config.name}] Port environment variable ${config.portEnvVar} not set.`);
+        Logger.log(`\u{1F4A1} Please set ${config.portEnvVar} in your .env file or use --port parameter.`);
+        Logger.log(`   Example: ${config.portEnvVar}=3000 or --port 3000`);
+        failed++;
+        return;
+      }
+      const serverPort = Number(portString);
+      if (!Number.isInteger(serverPort) || serverPort < 1 || serverPort > 65535) {
+        Logger.error(
+          `\u274C [${config.name}] Invalid port number "${portString}" defined in ${config.portEnvVar} (expected integer 1-65535).`
+        );
+        failed++;
+        return;
+      }
+      try {
+        const activeTools = filterTools(config.tools);
+        const server = new BaseMcpServer(config.name, activeTools);
+        const serverHost = process.env.MCP_SERVER_HOST || "127.0.0.1";
+        Logger.log(`\u{1F527} [${config.name}] Initializing MCP Server in HTTP mode on ${serverHost}:${serverPort}...`);
+        await server.startHttpServer(serverPort, serverHost);
+        servers.push(server);
+        started++;
+        const displayHost = serverHost === "0.0.0.0" ? "localhost" : serverHost;
+        Logger.log(`\u2705 [${config.name}] MCP Server started successfully!`);
+        Logger.log(`   \u{1F310} Endpoint: http://${displayHost}:${serverPort}/mcp`);
+        Logger.log(`   \u{1F4DA} Tools: ${activeTools.length} available`);
+      } catch (error) {
+        Logger.error(`\u274C [${config.name}] Failed to start MCP Server on port ${serverPort}:`, error);
+        failed++;
+      }
+    })
+  );
+  if (started > 0) {
+    installShutdownHandlers(servers);
+  }
   Logger.log("");
-  Logger.log("\u{1F389} Server initialization completed!");
+  Logger.log(started > 0 ? "\u{1F389} Server initialization completed!" : "\u274C No MCP server instance started.");
   Logger.log("\u{1F4A1} Need help? Check the README.md for configuration details.");
+  return { started, failed, servers };
+}
+function createShutdownHandler(servers, exitHook = (code) => process.exit(code)) {
+  let invoked = false;
+  return async (signal) => {
+    if (invoked) {
+      return;
+    }
+    invoked = true;
+    Logger.log(`\u{1F4F6} Received ${signal}; shutting down MCP HTTP server...`);
+    await Promise.allSettled(servers.map((server) => server.stopHttpServer()));
+    exitHook(0);
+  };
+}
+function installShutdownHandlers(servers) {
+  const handler = createShutdownHandler(servers);
+  process.on("SIGINT", () => void handler("SIGINT"));
+  process.on("SIGTERM", () => void handler("SIGTERM"));
 }
 var EXEC_TOOLS = [
   "geocode",
@@ -1550,13 +2532,58 @@ async function runExecCommand(toolName, params, apiKey, runner = execTool, strea
     return 1;
   }
 }
-async function runDoctor(packageVersion, apiKey, live = false, runner = execTool) {
-  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+var DOCTOR_PROBES = [
+  { id: "geocoding", name: "geocoding-api", tool: "geocode", params: { address: "Tokyo Tower" } },
+  { id: "places-new", name: "places-api-new", tool: "search-places", params: { query: "Tokyo Tower" } },
+  {
+    id: "routes",
+    name: "routes-api",
+    tool: "directions",
+    params: { origin: "Tokyo Tower", destination: "Tokyo Station", mode: "walking" }
+  }
+];
+var DOCTOR_PROBE_ALIASES = {
+  geocoding: "geocoding",
+  "geocoding-api": "geocoding",
+  "places-new": "places-new",
+  places: "places-new",
+  "places-api-new": "places-new",
+  routes: "routes",
+  "routes-api": "routes"
+};
+function parseDoctorProbes(raw) {
+  if (raw === void 0) {
+    return { probes: void 0 };
+  }
+  const items = raw.split(",").map((item) => item.trim().toLowerCase()).filter(Boolean);
+  if (items.length === 0) {
+    return { probes: void 0, error: "--probes received no probe names (expected: geocoding, places-new, routes)" };
+  }
+  const probes = [];
+  for (const item of items) {
+    const id = DOCTOR_PROBE_ALIASES[item];
+    if (!id) {
+      return { probes: [], error: `unknown probe "${item}" (expected: geocoding, places-new, routes)` };
+    }
+    if (!probes.includes(id)) {
+      probes.push(id);
+    }
+  }
+  return { probes };
+}
+async function runDoctor(packageVersion, apiKey, live = false, runner = execTool, options = {}) {
+  const nodeVersion = options.nodeVersion ?? process.versions.node;
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  const config = options.config ?? resolveRuntimeConfig(process.env);
+  const allToolNames = options.allToolNames ?? config_default[0].tools.map((tool) => tool.name);
+  const toolsResolution = resolveEnabledToolNames(allToolNames, config.enabledToolsRaw);
+  const diagnostics = describeRuntimeConfig(config);
+  const toolsProfile = describeToolsProfile(toolsResolution.names);
   const checks = [
     {
       name: "node",
-      status: nodeMajor >= 18 ? "pass" : "fail",
-      detail: `Node.js ${process.versions.node} detected; version 18 or newer is required.`
+      status: nodeMajor >= NODE_ENGINE_FLOOR ? "pass" : "fail",
+      detail: `Node.js ${nodeVersion} detected; version ${NODE_ENGINE_FLOOR} or newer is required (package.json engines).`
     },
     {
       name: "package",
@@ -1567,6 +2594,21 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
       name: "api-key",
       status: apiKey ? "pass" : "fail",
       detail: apiKey ? "GOOGLE_MAPS_API_KEY is configured (value hidden)." : "GOOGLE_MAPS_API_KEY is not configured. Set it in the environment before making API calls."
+    },
+    {
+      name: "config",
+      status: toolsResolution.fallback ? "fail" : "pass",
+      detail: toolsResolution.fallback ? `GOOGLE_MAPS_ENABLED_TOOLS matched 0 tools; the server falls back to all ${allToolNames.length} tools. Effective configuration: ${formatConfigDiagnostics(diagnostics)}` : `Effective configuration: ${formatConfigDiagnostics(diagnostics)}`
+    },
+    {
+      name: "env-file",
+      status: "pass",
+      detail: config.envFile ? `Explicit environment file loaded: ${config.envFile}` : "No explicit --env-file requested; implicit .env discovery (current directory, then package directory) applies."
+    },
+    {
+      name: "tools",
+      status: "pass",
+      detail: `${toolsProfile.toolCount} tool(s) enabled; Google APIs: ${toolsProfile.apis.join(", ") || "none"}; per-tool: ${toolsProfile.tools.map((tool) => `${tool.tool}[${tool.apis.join("+")}]`).join(", ")}`
     }
   ];
   if (!live) {
@@ -1582,16 +2624,8 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
       detail: "Live API checks require GOOGLE_MAPS_API_KEY."
     });
   } else {
-    const liveChecks = [
-      { name: "geocoding-api", tool: "geocode", params: { address: "Tokyo Tower" } },
-      { name: "places-api-new", tool: "search-places", params: { query: "Tokyo Tower" } },
-      {
-        name: "routes-api",
-        tool: "directions",
-        params: { origin: "Tokyo Tower", destination: "Tokyo Station", mode: "walking" }
-      }
-    ];
-    for (const check of liveChecks) {
+    const selected = options.probes ? DOCTOR_PROBES.filter((probe) => options.probes.includes(probe.id)) : DOCTOR_PROBES;
+    for (const check of selected) {
       try {
         const result = await runner(check.tool, check.params, apiKey);
         if (isExecFailureResponse(result)) {
@@ -1623,241 +2657,591 @@ async function runDoctor(packageVersion, apiKey, live = false, runner = execTool
     checks
   };
 }
+async function runSetup(options, deps = {}) {
+  const fsImpl = deps.fs ?? {
+    existsSync: (path) => existsSync4(path),
+    readFileSync: (path, encoding) => readFileSync5(path, encoding),
+    writeFileSync: (path, data, encoding) => writeFileSync4(path, data, encoding)
+  };
+  const nodeVersion = deps.nodeVersion ?? process.versions.node;
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  const config = deps.config ?? resolveRuntimeConfig(process.env);
+  const examplePath = resolve5(options.packageDir, ".env.example");
+  const envPath = resolve5(options.targetDir, ".env");
+  const checks = [
+    {
+      name: "node",
+      status: nodeMajor >= NODE_ENGINE_FLOOR ? "pass" : "fail",
+      detail: `Node.js ${nodeVersion} detected; version ${NODE_ENGINE_FLOOR} or newer is required (package.json engines).`
+    },
+    {
+      name: "env-template",
+      status: fsImpl.existsSync(examplePath) ? "pass" : "fail",
+      detail: fsImpl.existsSync(examplePath) ? `Template found: ${examplePath}` : `Template missing: ${examplePath} (expected next to the installed package).`
+    }
+  ];
+  let created = false;
+  if (options.writeEnv) {
+    if (fsImpl.existsSync(envPath)) {
+      checks.push({
+        name: "env-file",
+        status: "pass",
+        detail: `${envPath} already exists; left untouched (no overwrite).`
+      });
+    } else if (!fsImpl.existsSync(examplePath)) {
+      checks.push({
+        name: "env-file",
+        status: "fail",
+        detail: `Cannot create ${envPath}: template ${examplePath} is missing.`
+      });
+    } else {
+      try {
+        fsImpl.writeFileSync(envPath, fsImpl.readFileSync(examplePath, "utf-8"), "utf-8");
+        created = true;
+        checks.push({
+          name: "env-file",
+          status: "pass",
+          detail: `Created ${envPath} from template; edit it and set GOOGLE_MAPS_API_KEY.`
+        });
+      } catch (error) {
+        checks.push({
+          name: "env-file",
+          status: "fail",
+          detail: `Failed to create ${envPath}: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+    }
+  } else {
+    checks.push({
+      name: "env-file",
+      status: fsImpl.existsSync(envPath) ? "pass" : "skip",
+      detail: fsImpl.existsSync(envPath) ? `${envPath} found.` : `${envPath} not found; rerun with --write-env to create it from the template.`
+    });
+  }
+  checks.push({
+    name: "api-key",
+    status: config.apiKey ? "pass" : "fail",
+    detail: config.apiKey ? `GOOGLE_MAPS_API_KEY is configured (source: ${config.apiKeySource}, value hidden).` : "GOOGLE_MAPS_API_KEY is not configured. Set it in the environment or in .env after scaffolding."
+  });
+  return {
+    success: checks.every((check) => check.status !== "fail"),
+    created,
+    checks
+  };
+}
+function runSnippetCommand(options, streams = { stdout: process.stdout, stderr: process.stderr }) {
+  try {
+    const snippet = renderClientSnippet(options);
+    streams.stdout.write(snippet.json + "\n");
+    for (const note of snippet.notes) {
+      streams.stderr.write(`[snippet] ${note}
+`);
+    }
+    return 0;
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2) + "\n"
+    );
+    return 1;
+  }
+}
+function runEnableDisableCliCommand(name, enable, options = {}) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  const target = resolveCliTarget(name);
+  if (target === void 0) {
+    streams.stderr.write(
+      JSON.stringify({ error: `Unsupported CLI: ${name}. Supported: ${supportedCliNames()}.` }, null, 2) + "\n"
+    );
+    return 2;
+  }
+  const settings = loadCliSettings(options.home);
+  const already = settings.enabled.includes(target.id);
+  if (enable === already) {
+    streams.stdout.write(
+      JSON.stringify({ cli: target.id, enabled: enable, message: `${target.id} is already ${enable ? "enabled" : "disabled"}.` }, null, 2) + "\n"
+    );
+    return 0;
+  }
+  settings.enabled = enable ? [...settings.enabled, target.id] : settings.enabled.filter((item) => item !== target.id);
+  saveCliSettings(settings, options.home);
+  streams.stdout.write(
+    JSON.stringify({ cli: target.id, enabled: enable, message: `${enable ? "Enabled" : "Disabled"} ${target.id}.` }, null, 2) + "\n"
+  );
+  return 0;
+}
+function runInstallUninstallCommand(operation, options) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  if (loadCliSettings(options.home).enabled.length === 0) {
+    streams.stdout.write(
+      JSON.stringify(
+        {
+          success: true,
+          message: "No CLI enabled. Use 'mcp-google-map enable <cli name>' first.",
+          summaries: [],
+          errors: []
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 0;
+  }
+  let result;
+  try {
+    result = operation === "install" ? installEnabledCliResources({ home: options.home, apiKey: options.apiKey, resourcesRoot: options.resourcesRoot }) : uninstallEnabledCliResources({ home: options.home, resourcesRoot: options.resourcesRoot });
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ success: false, errors: [error instanceof Error ? error.message : String(error)] }, null, 2) + "\n"
+    );
+    return 1;
+  }
+  streams.stdout.write(
+    JSON.stringify({ success: result.errors.length === 0, operation, summaries: result.summaries, errors: result.errors }, null, 2) + "\n"
+  );
+  return result.errors.length > 0 ? 1 : 0;
+}
+function runShowCommand(options) {
+  const streams = options.streams ?? { stdout: process.stdout, stderr: process.stderr };
+  try {
+    streams.stdout.write(buildCliShowReport(options) + "\n");
+    return 0;
+  } catch (error) {
+    streams.stderr.write(
+      JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2) + "\n"
+    );
+    return 1;
+  }
+}
 var isRunDirectly = process.argv[1] && (process.argv[1].endsWith("cli.ts") || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("mcp-google-map") || process.argv[1].includes("mcp-google-map"));
 var isMainModule = import.meta.url === `file://${process.argv[1]}`;
 if (isRunDirectly || isMainModule) {
+  loadEnvironment(extractEnvFileOption(process.argv));
   let packageVersion = "0.0.0";
   try {
-    const packageJsonPath = resolve(__dirname, "../package.json");
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const packageJsonPath = resolve5(__dirname, "../package.json");
+    const packageJson = JSON.parse(readFileSync5(packageJsonPath, "utf-8"));
     packageVersion = packageJson.version;
   } catch (e) {
     packageVersion = "0.0.0";
   }
-  yargs(hideBin(process.argv)).command(
-    "doctor",
-    "Check standalone CLI readiness without starting an MCP server",
-    (yargs2) => yargs2.option("live", {
-      type: "boolean",
-      default: false,
-      description: "Make billable test requests to Geocoding, Places (New), and Routes APIs"
-    }).option("apikey", {
-      alias: "k",
-      type: "string",
-      description: "Google Maps API key (prefer GOOGLE_MAPS_API_KEY to avoid shell history exposure)",
-      default: process.env.GOOGLE_MAPS_API_KEY
-    }).example([
-      ["$0 doctor", "Check local runtime and API key configuration without network calls"],
-      ["$0 doctor --live", "Also verify three Google Maps APIs with billable requests"]
-    ]),
-    async (argv) => {
-      const report = await runDoctor(packageVersion, argv.apikey, argv.live);
-      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
-      process.exitCode = report.success ? 0 : 1;
-    }
-  ).command(
-    "exec <tool> [params]",
-    "Execute a tool directly and output JSON",
-    (yargs2) => {
-      return yargs2.positional("tool", {
-        type: "string",
-        describe: `Tool name: ${EXEC_TOOLS.join(", ")}`
-      }).positional("params", {
+  const managementCommand = parseManagementCommand(hideBin(process.argv));
+  if (managementCommand !== void 0) {
+    void runManagementCommand(managementCommand, { currentVersion: packageVersion }).then((code) => {
+      process.exitCode = code;
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(JSON.stringify({ error: message }, null, 2) + "\n");
+      process.exitCode = 1;
+    });
+  } else {
+    yargs(hideBin(process.argv)).command(
+      "doctor",
+      "Check standalone CLI readiness without starting an MCP server",
+      (yargs2) => yargs2.option("live", {
+        type: "boolean",
+        default: false,
+        description: "Make billable test requests to Geocoding, Places (New), and Routes APIs"
+      }).option("probes", {
         type: "string",
-        describe: "JSON parameters string"
+        description: "Comma-separated subset of live probes: geocoding, places-new, routes (default: all three)"
       }).option("apikey", {
         alias: "k",
         type: "string",
-        description: "Google Maps API key",
+        description: "Google Maps API key (prefer GOOGLE_MAPS_API_KEY to avoid shell history exposure)",
         default: process.env.GOOGLE_MAPS_API_KEY
       }).example([
-        [`$0 exec geocode '{"address":"Tokyo Tower"}'`, "Geocode an address"],
-        [
-          `$0 exec search-nearby '{"center":{"value":"35.68,139.74","isCoordinates":true},"keyword":"restaurant"}'`,
-          "Search nearby"
-        ],
-        [`$0 exec search-places '{"query":"ramen in Tokyo"}'`, "Text search"]
-      ]);
-    },
-    async (argv) => {
-      if (!argv.apikey) {
-        process.stderr.write(
-          JSON.stringify(
-            {
-              error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable."
-            },
-            null,
-            2
-          ) + "\n"
-        );
-        process.exitCode = 1;
-        return;
+        ["$0 doctor", "Check local runtime and API key configuration without network calls"],
+        ["$0 doctor --live", "Also verify three Google Maps APIs with billable requests"],
+        ["$0 doctor --live --probes geocoding,routes", "Probe only the selected APIs"]
+      ]),
+      async (argv) => {
+        const parsedProbes = parseDoctorProbes(argv.probes);
+        if (parsedProbes.error) {
+          process.stderr.write(JSON.stringify({ error: parsedProbes.error }, null, 2) + "\n");
+          process.exitCode = 1;
+          return;
+        }
+        const report = await runDoctor(packageVersion, argv.apikey, argv.live, void 0, {
+          probes: parsedProbes.probes,
+          config: resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) })
+        });
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        process.exitCode = report.success ? 0 : 1;
       }
-      try {
-        const params = argv.params ? JSON.parse(argv.params) : {};
-        process.exitCode = await runExecCommand(argv.tool, params, argv.apikey);
-      } catch (error) {
-        process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
-        process.exitCode = 1;
+    ).command(
+      "setup",
+      "Non-interactive onboarding: verify local readiness, optionally scaffold .env",
+      (yargs2) => yargs2.option("write-env", {
+        type: "boolean",
+        default: false,
+        description: "Create .env from .env.example in --env-dir when it does not exist (never overwrites)"
+      }).option("env-dir", {
+        type: "string",
+        default: process.cwd(),
+        description: "Directory where .env is looked up / created"
+      }).example([
+        ["$0 setup", "Check readiness without writing anything"],
+        ["$0 setup --write-env", "Also scaffold .env from the package template"]
+      ]),
+      async (argv) => {
+        const report = await runSetup({
+          packageDir: resolve5(__dirname, ".."),
+          targetDir: argv.envDir,
+          writeEnv: argv.writeEnv
+        });
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        process.exitCode = report.success ? 0 : 1;
       }
-    }
-  ).command(
-    "batch-geocode",
-    "Geocode multiple addresses from a file (one address per line)",
-    (yargs2) => {
-      return yargs2.option("input", {
-        alias: "i",
+    ).command(
+      "snippet",
+      "Print an MCP client registration snippet (JSON on stdout; never writes files)",
+      (yargs2) => yargs2.option("client", {
+        type: "string",
+        choices: ["generic", "claude", "cursor", "pi"],
+        default: "generic",
+        description: "Target client (selects the documented target file)"
+      }).option("transport", {
         type: "string",
-        describe: "Input file path (one address per line). Use - for stdin.",
-        demandOption: true
-      }).option("output", {
-        alias: "o",
+        choices: ["stdio", "http"],
+        default: "stdio",
+        description: "MCP transport of the snippet"
+      }).option("launcher", {
         type: "string",
-        describe: "Output file path (JSON). Defaults to stdout."
-      }).option("concurrency", {
-        alias: "c",
+        choices: ["npx", "node", "bin"],
+        default: "npx",
+        description: "stdio launcher command"
+      }).option("command", {
+        type: "string",
+        description: "Absolute path to dist/cli.js (required for --launcher node)"
+      }).option("host", {
+        type: "string",
+        default: "127.0.0.1",
+        description: "Host used in the URL (transport http)"
+      }).option("port", {
         type: "number",
-        describe: "Max parallel requests",
-        default: 20
+        default: 3e3,
+        description: "Port used in the URL (transport http)"
+      }).option("env-key", {
+        type: "string",
+        description: "Emit a ${NAME} variable reference instead of a literal placeholder (expansion is client-specific)"
+      }).option("name", {
+        type: "string",
+        default: "mcp-google-map",
+        description: "Server name inside mcpServers"
+      }).example([
+        ["$0 snippet --client claude", "stdio snippet using the npx launcher"],
+        ["$0 snippet --client pi --launcher node --command /abs/path/dist/cli.js", "stdio snippet with an explicit artifact"],
+        ["$0 snippet --transport http --port 3100", "HTTP URL snippet"]
+      ]),
+      (argv) => {
+        process.exitCode = runSnippetCommand({
+          client: argv.client,
+          transport: argv.transport,
+          launcher: argv.launcher,
+          commandPath: argv.command,
+          host: argv.host,
+          port: argv.port,
+          envKey: argv.envKey,
+          serverName: argv.name
+        });
+      }
+    ).command(
+      "enable <cli>",
+      "Enable MCP-server and skill installation for a supported CLI",
+      (yargs2) => yargs2.positional("cli", {
+        type: "string",
+        describe: `CLI name: ${supportedCliNames()}`
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for the settings file (default: user home)"
+      }).example([["$0 enable pi", "Enable pi for install/uninstall/show"]]),
+      (argv) => {
+        process.exitCode = runEnableDisableCliCommand(argv.cli, true, {
+          home: argv.home
+        });
+      }
+    ).command(
+      "disable <cli>",
+      "Disable MCP-server and skill installation for a supported CLI",
+      (yargs2) => yargs2.positional("cli", {
+        type: "string",
+        describe: `CLI name: ${supportedCliNames()}`
+      }).option("home", {
+        type: "string",
+        description: "Home-directory override for the settings file (default: user home)"
+      }).example([["$0 disable claude", "Disable claude for install/uninstall/show"]]),
+      (argv) => {
+        process.exitCode = runEnableDisableCliCommand(argv.cli, false, {
+          home: argv.home
+        });
+      }
+    ).command(
+      "install",
+      "Register the mcp-google-map stdio server and install packaged skills for every enabled CLI",
+      (yargs2) => yargs2.option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
       }).option("apikey", {
         alias: "k",
         type: "string",
-        description: "Google Maps API key",
-        default: process.env.GOOGLE_MAPS_API_KEY
-      }).example([
-        ["$0 batch-geocode -i addresses.txt", "Geocode to stdout"],
-        ["$0 batch-geocode -i addresses.txt -o results.json", "Geocode to file"],
-        ["cat addresses.txt | $0 batch-geocode -i -", "Geocode from stdin"]
-      ]);
-    },
-    async (argv) => {
-      if (!argv.apikey) {
-        console.error("Error: GOOGLE_MAPS_API_KEY not set. Use --apikey or set env var.");
-        process.exit(1);
+        description: "Google Maps API key embedded in the registered entry (prefer GOOGLE_MAPS_API_KEY)",
+        default: resolveRuntimeConfig(process.env, { envFile: extractEnvFileOption(process.argv) }).apiKey
+      }).example([["$0 install", "Register the server and skills in every enabled CLI"]]),
+      (argv) => {
+        process.exitCode = runInstallUninstallCommand("install", {
+          home: argv.home,
+          apiKey: argv.apikey,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      let lines;
-      if (argv.input === "-") {
-        const rl = createInterface({ input: process.stdin });
-        lines = [];
-        for await (const line of rl) {
-          const trimmed = line.trim();
-          if (trimmed) lines.push(trimmed);
-        }
-      } else {
-        if (!existsSync(argv.input)) {
-          console.error(`Error: File not found: ${argv.input}`);
-          process.exit(1);
-        }
-        lines = readFileSync(argv.input, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    ).command(
+      "uninstall",
+      "Remove the mcp-google-map server entry and managed skills from every enabled CLI",
+      (yargs2) => yargs2.option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
+      }).example([["$0 uninstall", "Reciprocal removal of install for every enabled CLI"]]),
+      (argv) => {
+        process.exitCode = runInstallUninstallCommand("uninstall", {
+          home: argv.home,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      if (lines.length === 0) {
-        console.error("Error: No addresses found in input.");
-        process.exit(1);
+    ).command(
+      "show",
+      "Show CLI configuration and installation status tables (human-readable)",
+      (yargs2) => yargs2.option("home", {
+        type: "string",
+        description: "Home-directory override for CLI configuration paths (default: user home)"
+      }).example([["$0 show", "Print CLI Configuration and Installation Status tables"]]),
+      (argv) => {
+        process.exitCode = runShowCommand({
+          home: argv.home,
+          resourcesRoot: resolveSkillsResourcesRoot(resolve5(__dirname, ".."))
+        });
       }
-      const searcher = new PlacesSearcher(argv.apikey);
-      const concurrency = Math.min(Math.max(argv.concurrency, 1), 50);
-      const results = [];
-      let completed = 0;
-      const semaphore = async (tasks2, limit) => {
-        const executing = [];
-        for (const task of tasks2) {
-          const p = task().then(() => {
-            executing.splice(executing.indexOf(p), 1);
-          });
-          executing.push(p);
-          if (executing.length >= limit) {
-            await Promise.race(executing);
-          }
+    ).command(
+      "exec <tool> [params]",
+      "Execute a tool directly and output JSON",
+      (yargs2) => {
+        return yargs2.positional("tool", {
+          type: "string",
+          describe: `Tool name: ${EXEC_TOOLS.join(", ")}`
+        }).positional("params", {
+          type: "string",
+          describe: "JSON parameters string"
+        }).option("apikey", {
+          alias: "k",
+          type: "string",
+          description: "Google Maps API key",
+          default: process.env.GOOGLE_MAPS_API_KEY
+        }).example([
+          [`$0 exec geocode '{"address":"Tokyo Tower"}'`, "Geocode an address"],
+          [
+            `$0 exec search-nearby '{"center":{"value":"35.68,139.74","isCoordinates":true},"keyword":"restaurant"}'`,
+            "Search nearby"
+          ],
+          [`$0 exec search-places '{"query":"ramen in Tokyo"}'`, "Text search"]
+        ]);
+      },
+      async (argv) => {
+        if (!argv.apikey) {
+          process.stderr.write(
+            JSON.stringify(
+              {
+                error: "GOOGLE_MAPS_API_KEY not set. Use --apikey or set GOOGLE_MAPS_API_KEY environment variable."
+              },
+              null,
+              2
+            ) + "\n"
+          );
+          process.exitCode = 1;
+          return;
         }
-        await Promise.all(executing);
-      };
-      const tasks = lines.map((address, index) => async () => {
         try {
-          const result = await searcher.geocode(address);
-          results[index] = { address, ...result };
+          const params = argv.params ? JSON.parse(argv.params) : {};
+          process.exitCode = await runExecCommand(argv.tool, params, argv.apikey);
         } catch (error) {
-          results[index] = { address, success: false, error: error.message };
+          process.stderr.write(JSON.stringify({ error: error.message }, null, 2) + "\n");
+          process.exitCode = 1;
         }
-        completed++;
-        if (!argv.output) return;
-        process.stderr.write(`\r  ${completed}/${lines.length} geocoded`);
-      });
-      await semaphore(tasks, concurrency);
-      if (argv.output) {
-        process.stderr.write("\n");
-      }
-      const succeeded = results.filter((r) => r.success).length;
-      const failed = results.filter((r) => !r.success).length;
-      const summary = { total: lines.length, succeeded, failed, results };
-      const json = JSON.stringify(summary, null, 2);
-      if (argv.output) {
-        writeFileSync(argv.output, json, "utf-8");
-        console.error(`Done: ${succeeded}/${lines.length} succeeded. Output: ${argv.output}`);
-      } else {
-        console.log(json);
       }
-      process.exit(failed > 0 ? 1 : 0);
-    }
-  ).command(
-    "$0",
-    "Start the MCP server (HTTP by default, --stdio for stdio mode)",
-    (yargs2) => {
-      return yargs2.option("port", {
-        alias: "p",
-        type: "number",
-        description: "Port to run the MCP server on",
-        default: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 3e3
-      }).option("host", {
-        type: "string",
-        description: "Hostname to bind the server to (e.g. 0.0.0.0 for all interfaces)",
-        default: process.env.MCP_SERVER_HOST || "0.0.0.0"
-      }).option("apikey", {
-        alias: "k",
-        type: "string",
-        description: "Google Maps API key",
-        default: process.env.GOOGLE_MAPS_API_KEY
-      }).option("stdio", {
-        type: "boolean",
-        description: "Use stdio transport instead of HTTP",
-        default: false
-      }).example([
-        ["$0", "Start HTTP server with default settings"],
-        ['$0 --port 3000 --apikey "your_api_key"', "Start HTTP with custom port and API key"],
-        ["$0 --host 0.0.0.0 --port 3000", "Start HTTP accessible from all interfaces"],
-        ["$0 --stdio", "Start in stdio mode (for Claude Desktop, Cursor, etc.)"]
-      ]);
-    },
-    async (argv) => {
-      if (argv.apikey) {
-        process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
-      }
-      void checkForUpdates({ currentVersion: packageVersion }).catch(() => void 0);
-      const tools = filterTools(config_default[0].tools);
-      if (argv.stdio) {
-        const server = new BaseMcpServer(config_default[0].name, tools);
-        await server.startStdio();
-      } else {
-        Logger.log("\u{1F5FA}\uFE0F  Google Maps MCP Server");
-        Logger.log("   A Model Context Protocol server for Google Maps services");
-        Logger.log("");
+    ).command(
+      "batch-geocode",
+      "Geocode multiple addresses from a file (one address per line)",
+      (yargs2) => {
+        return yargs2.option("input", {
+          alias: "i",
+          type: "string",
+          describe: "Input file path (one address per line). Use - for stdin.",
+          demandOption: true
+        }).option("output", {
+          alias: "o",
+          type: "string",
+          describe: "Output file path (JSON). Defaults to stdout."
+        }).option("concurrency", {
+          alias: "c",
+          type: "number",
+          describe: "Max parallel requests",
+          default: 20
+        }).option("apikey", {
+          alias: "k",
+          type: "string",
+          description: "Google Maps API key",
+          default: process.env.GOOGLE_MAPS_API_KEY
+        }).example([
+          ["$0 batch-geocode -i addresses.txt", "Geocode to stdout"],
+          ["$0 batch-geocode -i addresses.txt -o results.json", "Geocode to file"],
+          ["cat addresses.txt | $0 batch-geocode -i -", "Geocode from stdin"]
+        ]);
+      },
+      async (argv) => {
         if (!argv.apikey) {
-          Logger.log("\u26A0\uFE0F  Google Maps API Key not found!");
-          Logger.log("   Please provide --apikey parameter or set GOOGLE_MAPS_API_KEY in your .env file");
-          Logger.log("");
+          console.error("Error: GOOGLE_MAPS_API_KEY not set. Use --apikey or set env var.");
+          process.exit(1);
+        }
+        let lines;
+        if (argv.input === "-") {
+          const rl = createInterface({ input: process.stdin });
+          lines = [];
+          for await (const line of rl) {
+            const trimmed = line.trim();
+            if (trimmed) lines.push(trimmed);
+          }
+        } else {
+          if (!existsSync4(argv.input)) {
+            console.error(`Error: File not found: ${argv.input}`);
+            process.exit(1);
+          }
+          lines = readFileSync5(argv.input, "utf-8").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
         }
-        startServer(argv.port, argv.apikey, argv.host).catch((error) => {
-          Logger.error("\u274C Failed to start server:", error);
+        if (lines.length === 0) {
+          console.error("Error: No addresses found in input.");
           process.exit(1);
+        }
+        const searcher = new PlacesSearcher(argv.apikey);
+        const concurrency = Math.min(Math.max(argv.concurrency, 1), 50);
+        const results = [];
+        let completed = 0;
+        const semaphore = async (tasks2, limit) => {
+          const executing = [];
+          for (const task of tasks2) {
+            const p = task().then(() => {
+              executing.splice(executing.indexOf(p), 1);
+            });
+            executing.push(p);
+            if (executing.length >= limit) {
+              await Promise.race(executing);
+            }
+          }
+          await Promise.all(executing);
+        };
+        const tasks = lines.map((address, index) => async () => {
+          try {
+            const result = await searcher.geocode(address);
+            results[index] = { address, ...result };
+          } catch (error) {
+            results[index] = { address, success: false, error: error.message };
+          }
+          completed++;
+          if (!argv.output) return;
+          process.stderr.write(`\r  ${completed}/${lines.length} geocoded`);
         });
+        await semaphore(tasks, concurrency);
+        if (argv.output) {
+          process.stderr.write("\n");
+        }
+        const succeeded = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        const summary = { total: lines.length, succeeded, failed, results };
+        const json = JSON.stringify(summary, null, 2);
+        if (argv.output) {
+          writeFileSync4(argv.output, json, "utf-8");
+          console.error(`Done: ${succeeded}/${lines.length} succeeded. Output: ${argv.output}`);
+        } else {
+          console.log(json);
+        }
+        process.exit(failed > 0 ? 1 : 0);
       }
-    }
-  ).version(packageVersion).alias("version", "v").help().parse();
+    ).command(
+      "$0",
+      "Start the MCP server (HTTP by default, --stdio for stdio mode)",
+      (yargs2) => {
+        return yargs2.option("port", {
+          alias: "p",
+          type: "number",
+          description: "Port to run the MCP server on",
+          default: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 3e3
+        }).option("host", {
+          type: "string",
+          description: "Hostname to bind the server to (default 127.0.0.1 loopback; 0.0.0.0 for all interfaces)",
+          default: process.env.MCP_SERVER_HOST || "127.0.0.1"
+        }).option("apikey", {
+          alias: "k",
+          type: "string",
+          description: "Google Maps API key",
+          default: process.env.GOOGLE_MAPS_API_KEY
+        }).option("stdio", {
+          type: "boolean",
+          description: "Use stdio transport instead of HTTP",
+          default: false
+        }).example([
+          ["$0", "Start HTTP server with default settings"],
+          ['$0 --port 3000 --apikey "your_api_key"', "Start HTTP with custom port and API key"],
+          ["$0 --host 0.0.0.0 --port 3000", "Start HTTP accessible from all interfaces"],
+          ["$0 --stdio", "Start in stdio mode (for Claude Desktop, Cursor, etc.)"]
+        ]);
+      },
+      async (argv) => {
+        if (argv.apikey) {
+          process.env.GOOGLE_MAPS_API_KEY = argv.apikey;
+        }
+        void checkVersionIdle({ currentVersion: packageVersion }).catch(() => void 0);
+        const tools = filterTools(config_default[0].tools);
+        if (argv.stdio) {
+          const server = new BaseMcpServer(config_default[0].name, tools);
+          await server.startStdio();
+        } else {
+          Logger.log("\u{1F5FA}\uFE0F  Google Maps MCP Server");
+          Logger.log("   A Model Context Protocol server for Google Maps services");
+          Logger.log("");
+          if (!argv.apikey) {
+            Logger.log("\u26A0\uFE0F  Google Maps API Key not found!");
+            Logger.log("   Please provide --apikey parameter or set GOOGLE_MAPS_API_KEY in your .env file");
+            Logger.log("");
+          }
+          startServer(argv.port, argv.apikey, argv.host).then((outcome) => {
+            if (outcome.started === 0) {
+              process.exit(1);
+            }
+          }).catch((error) => {
+            Logger.error("\u274C Failed to start server:", error);
+            process.exit(1);
+          });
+        }
+      }
+    ).version(packageVersion).alias("version", "v").option("env-file", {
+      type: "string",
+      global: true,
+      description: "Load environment variables from this exact file (error if missing; no implicit .env fallback)"
+    }).help().parse();
+  }
 }
 export {
+  DOCTOR_PROBES,
   EXEC_TOOLS,
+  createShutdownHandler,
   execTool,
+  extractEnvFileOption,
+  installShutdownHandlers,
+  parseDoctorProbes,
   runDoctor,
+  runEnableDisableCliCommand,
   runExecCommand,
+  runInstallUninstallCommand,
+  runSetup,
+  runShowCommand,
+  runSnippetCommand,
   startServer
 };
 //# sourceMappingURL=cli.js.map