@iola_adm/iola-cli 0.2.4 → 0.2.5

package/README.md

@@ -156,6 +156,16 @@ iola ai setup gigachat --model GigaChat-2
 
 У GigaChat для физических лиц есть Freemium-лимит на токены; для больших объемов используются платные пакеты. У YandexGPT тарификация идет через Yandex Cloud по токенам и квотам аккаунта, актуальные бесплатные гранты или лимиты нужно проверять в консоли Yandex Cloud.
 
+Геокодер для пользовательских geo-skills:
+
+```bash
+iola geo key set yandex
+iola geo key doctor
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+```
+
+Инструкция по получению ключа: [Yandex Geocoder API key](https://github.com/adm-iola/iola-cli/wiki/Yandex-Geocoder-API-key).
+
 Зарубежные API-ключи:
 
 - OpenAI Platform: регистрация `https://platform.openai.com/`, ключи `https://platform.openai.com/api-keys`;
@@ -182,6 +192,8 @@ iola version --check
 - [Первый запуск](https://github.com/adm-iola/iola-cli/wiki/Первый-запуск)
 - [Мастер настройки](https://github.com/adm-iola/iola-cli/wiki/Мастер-настройки)
 - [AI-профили](https://github.com/adm-iola/iola-cli/wiki/AI-профили)
+- [Yandex Geocoder API key](https://github.com/adm-iola/iola-cli/wiki/Yandex-Geocoder-API-key)
+- [Скиллы для жителей](https://github.com/adm-iola/iola-cli/wiki/Скиллы-для-жителей)
 - [Локальный инструментальный агент](https://github.com/adm-iola/iola-cli/wiki/Локальный-инструментальный-агент)
 - [Skills и toolsets](https://github.com/adm-iola/iola-cli/wiki/Skills-и-toolsets)
 - [Локальные файлы](https://github.com/adm-iola/iola-cli/wiki/Локальные-файлы)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iola_adm/iola-cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "CLI и AI-агент городского округа Йошкар-Ола.",
   "license": "MIT",
   "homepage": "https://github.com/adm-iola/iola-cli#readme",

package/src/cli.js

@@ -440,6 +440,7 @@ const COMMANDS = new Map([
   ["health", checkHealth],
   ["layers", listLayers],
   ["data", handleData],
+  ["geo", handleGeo],
   ["schools", listSchools],
   ["kindergartens", listKindergartens],
   ["search", searchAll],
@@ -653,6 +654,9 @@ Usage:
   iola kindergartens [--limit 10] [--search TEXT] [--where FIELD=VALUE] [--columns a,b,c] [--format table|json|csv]
   iola kindergartens get --inn INN [--json]
   iola search TEXT [--limit 5] [--format table|json|csv]
+  iola geo key set yandex
+  iola geo key doctor
+  iola geo geocode "Йошкар-Ола, ул. Петрова, 15"
   iola mcp-info [--json]
   iola setup codex
   iola onboard
@@ -1881,6 +1885,7 @@ async function doctor(args = []) {
       modelAvailable: await checkConfiguredModel({ ai: activeAiProfile }),
       openaiKey: process.env.OPENAI_API_KEY ? "env" : secrets.openai?.apiKey ? "local" : "missing",
       openrouterKey: process.env.OPENROUTER_API_KEY ? "env" : secrets.openrouter?.apiKey ? "local" : "missing",
+      yandexGeocoderKey: (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) ? "env" : secrets.yandexGeocoder?.apiKey ? "local" : "missing",
       ollama: diagnostics.ollama.installed ? diagnostics.ollama.version : "not-installed",
     },
     skills: {
@@ -2565,6 +2570,8 @@ async function handleWiki(args) {
     ["Первый запуск", `${base}/Первый-запуск`],
     ["Мастер настройки", `${base}/Мастер-настройки`],
     ["AI-профили", `${base}/AI-профили`],
+    ["Yandex Geocoder API key", `${base}/Yandex-Geocoder-API-key`],
+    ["Скиллы для жителей", `${base}/Скиллы-для-жителей`],
     ["Локальный инструментальный агент", `${base}/Локальный-инструментальный-агент`],
     ["Skills и toolsets", `${base}/Skills-и-toolsets`],
     ["Локальные файлы", `${base}/Локальные-файлы`],
@@ -5323,6 +5330,176 @@ async function deleteAiKey(provider) {
   console.log(`Локальный ключ ${provider} удален.`);
 }
 
+async function handleGeo(args) {
+  const [command, subcommand, ...rest] = args;
+
+  if (command === "key") {
+    await handleGeoKey([subcommand, ...rest]);
+    return;
+  }
+
+  if (command === "geocode") {
+    await geoGeocode([subcommand, ...rest].filter(Boolean));
+    return;
+  }
+
+  if (command === "doctor" || command === "status") {
+    await printGeoKeyStatus({ check: command === "doctor" });
+    return;
+  }
+
+  throw new Error(`Команды geo:
+  iola geo key set yandex
+  iola geo key status
+  iola geo key doctor
+  iola geo key delete yandex
+  iola geo geocode "Йошкар-Ола, ул. Петрова, 15"`);
+}
+
+async function handleGeoKey(args) {
+  const [action, provider = "yandex"] = args;
+  if (provider !== "yandex") {
+    throw new Error("Сейчас поддерживается только провайдер: yandex");
+  }
+
+  if (action === "set") {
+    await setYandexGeocoderKey();
+    return;
+  }
+
+  if (action === "status") {
+    await printGeoKeyStatus();
+    return;
+  }
+
+  if (action === "doctor" || action === "check") {
+    await printGeoKeyStatus({ check: true });
+    return;
+  }
+
+  if (action === "delete") {
+    const secrets = await loadSecrets();
+    delete secrets.yandexGeocoder;
+    await saveSecrets(secrets);
+    console.log("Локальный ключ yandex geocoder удален.");
+    return;
+  }
+
+  throw new Error("Команды geo key: set yandex, status, doctor, delete yandex.");
+}
+
+async function setYandexGeocoderKey() {
+  if (!process.stdin.isTTY) {
+    throw new Error("Для сохранения ключа запустите команду в интерактивном терминале.");
+  }
+
+  const key = (await askText("Введите YANDEX_GEOCODER_API_KEY: ")).trim();
+  if (!key) throw new Error("Ключ пустой, сохранение отменено.");
+
+  const secrets = await loadSecrets();
+  secrets.yandexGeocoder = { apiKey: key };
+  await saveSecrets(secrets);
+  console.log(`Ключ yandex geocoder сохранен локально: ${SECRETS_FILE}`);
+
+  const shouldCheck = await confirm("Проверить ключ запросом к Yandex Geocoder? [Y/n] ");
+  if (shouldCheck) await checkYandexGeocoderKey({ print: true });
+}
+
+async function printGeoKeyStatus(options = {}) {
+  const key = await getYandexGeocoderKey();
+  const rows = [{
+    provider: "yandex-geocoder",
+    env: (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) ? "yes" : "no",
+    local: (await loadSecrets()).yandexGeocoder?.apiKey ? "yes" : "no",
+    status: key ? "configured" : "missing",
+  }];
+  printTable(rows, [
+    ["provider", "Провайдер"],
+    ["env", "Env"],
+    ["local", "Локально"],
+    ["status", "Статус"],
+  ]);
+  if (options.check) await checkYandexGeocoderKey({ print: true });
+}
+
+async function geoGeocode(args) {
+  const query = args.join(" ").trim();
+  if (!query) throw new Error('Адрес обязателен. Пример: iola geo geocode "Йошкар-Ола, ул. Петрова, 15"');
+  const result = await callYandexGeocoder(query);
+  if (!result) {
+    console.log("Yandex Geocoder не вернул результат.");
+    return;
+  }
+  printKeyValue(result);
+}
+
+async function checkYandexGeocoderKey(options = {}) {
+  try {
+    const result = await callYandexGeocoder("Йошкар-Ола");
+    if (!result?.coordinates) throw new Error("Yandex Geocoder вернул пустой результат.");
+    if (options.print) {
+      console.log(`Yandex Geocoder: ok (${result.name || result.address || result.coordinates})`);
+    }
+    return true;
+  } catch (error) {
+    if (options.print) {
+      console.log(`Yandex Geocoder: error - ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return false;
+  }
+}
+
+async function callYandexGeocoder(query) {
+  const apiKey = await getYandexGeocoderKey();
+  if (!apiKey) {
+    throw new Error("Yandex Geocoder API key не найден. Выполните iola geo key set yandex или задайте YANDEX_GEOCODER_API_KEY.");
+  }
+
+  const url = new URL("https://geocode-maps.yandex.ru/v1/");
+  url.searchParams.set("apikey", apiKey);
+  url.searchParams.set("geocode", query);
+  url.searchParams.set("format", "json");
+  url.searchParams.set("lang", "ru_RU");
+  url.searchParams.set("results", "1");
+
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(15000) });
+  } catch (error) {
+    throw new Error(formatProviderFetchError("Yandex Geocoder", error));
+  }
+
+  if (!response.ok) {
+    const text = await response.text();
+    if (response.status === 403 && /Invalid api key/i.test(text)) {
+      throw new Error(`Yandex Geocoder request failed: ${response.status} ${response.statusText}\nInvalid api key. Если ключ только что создан, подождите до 15 минут: Yandex указывает, что активация ключа может занять до 15 минут.`);
+    }
+    throw new Error(`Yandex Geocoder request failed: ${response.status} ${response.statusText}\n${sanitizeSecretFromText(text, apiKey)}`);
+  }
+
+  const payload = await response.json();
+  const member = payload?.response?.GeoObjectCollection?.featureMember?.[0];
+  const object = member?.GeoObject;
+  if (!object) return null;
+  const point = object.Point?.pos || "";
+  const [lon, lat] = point.split(/\s+/);
+  return {
+    name: object.name || "",
+    address: object.metaDataProperty?.GeocoderMetaData?.text || object.description || "",
+    precision: object.metaDataProperty?.GeocoderMetaData?.precision || "",
+    coordinates: lat && lon ? `${lat}, ${lon}` : point,
+    map: lat && lon ? `https://yandex.ru/maps/?pt=${lon},${lat}&z=16&l=map` : "",
+  };
+}
+
+async function getYandexGeocoderKey() {
+  if (process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY) {
+    return process.env.YANDEX_GEOCODER_API_KEY || process.env.YANDEX_MAPS_API_KEY;
+  }
+  const secrets = await loadSecrets();
+  return secrets.yandexGeocoder?.apiKey || "";
+}
+
 function openDatabase() {
   const db = new DatabaseSync(DB_FILE);
   db.exec("PRAGMA busy_timeout = 5000;");
@@ -9251,6 +9428,11 @@ async function onboard(args = []) {
       await chooseAndSaveApiModel("gigachat");
     }
   }
+  if (components.includes("yandex-geocoder")) {
+    if (process.stdin.isTTY) {
+      await setYandexGeocoderKey();
+    }
+  }
   if (components.includes("codex")) {
     await installCodexIfMissing();
     await aiSetup(["codex"]);
@@ -9299,6 +9481,7 @@ async function chooseOnboardComponents(status = null) {
       11: "index",
       12: "browser",
       13: "ollama",
+      14: "yandex-geocoder",
     };
     return [...selected].map((item) => map[item] || item).filter(Boolean);
   } finally {
@@ -9311,13 +9494,14 @@ function isOnboardExitAnswer(answer) {
 }
 
 async function getOnboardComponentStatus() {
-  const [config, readiness, browser, archive, codexVersion, ollamaVersion] = await Promise.all([
+  const [config, readiness, browser, archive, codexVersion, ollamaVersion, yandexGeocoderKey] = await Promise.all([
     loadConfig(),
     getAiReadiness(),
     getBrowserStatus(),
     findCommand(["7z", "7zz", "7za"], ["--help"]).catch(() => null),
     getCommandVersion("codex", ["--version"]),
     getOllamaVersion(),
+    getYandexGeocoderKey(),
   ]);
   const workspaceReady = existsSync(PROJECT_CONTEXT_FILE) || existsSync(PROJECT_CONTEXT_DIR_FILE) || existsSync(PROJECT_IOLA_DIR);
   const policyReady = (config.toolsets?.enabled || []).includes("analyst");
@@ -9335,6 +9519,7 @@ async function getOnboardComponentStatus() {
     archive: Boolean(archive),
     index: false,
     browser: browser.installed === "yes",
+    "yandex-geocoder": Boolean(yandexGeocoderKey),
   };
 }
 
@@ -9353,6 +9538,7 @@ function onboardComponentRows(status) {
     ["11", "index", "Индекс локальных документов", "настраивается под выбранную папку"],
     ["12", "browser", "Browser runtime", "Playwright/Chromium установлен"],
     ["13", "ollama", "Ollama", "опциональный локальный runtime"],
+    ["14", "yandex-geocoder", "Yandex Geocoder API", "ключ геокодера сохранен или есть в env"],
   ];
   return rows.map(([number, key, title, hint]) => ({ number, key, title, hint, status: status[key] ? "готово" : "не настроено" }));
 }
@@ -9367,7 +9553,7 @@ function defaultOnboardSelection(status) {
 }
 
 function defaultOnboardComponents(status) {
-  const map = { 1: "workspace", 2: "policy", 3: "iola", 4: "yandexgpt", 5: "gigachat", 6: "openai", 7: "openrouter", 8: "codex", 9: "codex-mcp", 10: "archive", 11: "index", 12: "browser", 13: "ollama" };
+  const map = { 1: "workspace", 2: "policy", 3: "iola", 4: "yandexgpt", 5: "gigachat", 6: "openai", 7: "openrouter", 8: "codex", 9: "codex-mcp", 10: "archive", 11: "index", 12: "browser", 13: "ollama", 14: "yandex-geocoder" };
   return defaultOnboardSelection(status).map((item) => map[item]).filter(Boolean);
 }
 

package/wiki/Home.md

@@ -11,6 +11,7 @@
 - выгрузка CSV/JSON;
 - работа с локальной моделью Ollama;
 - работа с YandexGPT, GigaChat, OpenAI, OpenRouter и Codex CLI;
+- geo-сценарии для жителей через Yandex Geocoder API;
 - подключение публичного MCP-сервера.
 
 Быстрый старт:
@@ -28,6 +29,8 @@ iola ask "найди школу 29"
 - [Первый запуск](Первый-запуск)
 - [Мастер настройки](Мастер-настройки)
 - [AI-профили](AI-профили)
+- [Yandex Geocoder API key](Yandex-Geocoder-API-key)
+- [Скиллы для жителей](Скиллы-для-жителей)
 - [Локальный инструментальный агент](Локальный-инструментальный-агент)
 - [Skills и toolsets](Skills-и-toolsets)
 - [Локальные файлы](Локальные-файлы)

package/wiki/Yandex-Geocoder-API-key.md

@@ -0,0 +1,72 @@
+# Yandex Geocoder API key
+
+Эта инструкция нужна для подключения геокодера Яндекса к `iola-cli`.
+
+Геокодер нужен жителям для вопросов вида:
+
+- что находится рядом с моим адресом;
+- где находится школа или детский сад;
+- какой объект ближе;
+- открыть объект на карте;
+- не перепутать Йошкар-Олу, Семеновку и другие населенные пункты.
+
+## Получение ключа
+
+1. Откройте Кабинет разработчика Яндекса: `https://developer.tech.yandex.ru/services/`.
+2. Войдите в аккаунт Яндекса.
+3. В списке `API интерфейсы` найдите `API Геокодера`.
+4. Откройте `API Геокодера`.
+5. Проверьте блок тарифа. На момент проверки 02.06.2026 в кабинете был показан тариф `Бесплатный с ограничениями` и счетчик `1000` запросов в сутки.
+6. В блоке `Ключи API` нажмите `Новый ключ`.
+7. В поле `Название ключа` введите понятное имя, например `iola-cli geocoder`.
+8. Нажмите `Добавить ключ`.
+9. После создания ключ появится в списке ключей API Геокодера.
+10. Скопируйте значение ключа. Это значение будет `YANDEX_GEOCODER_API_KEY`.
+
+Важно: новый ключ может начать работать не сразу. В документации Яндекса указано, что активация ключа может занять до 15 минут. Если CLI пишет `Invalid api key` сразу после создания ключа, подождите и повторите проверку.
+
+## Сохранение в CLI
+
+Запустите:
+
+```bash
+iola geo key set yandex
+```
+
+CLI попросит ввести:
+
+```text
+YANDEX_GEOCODER_API_KEY
+```
+
+Ключ сохраняется локально на устройстве пользователя в `~/.iola/secrets.json`.
+
+Проверить сохранение:
+
+```bash
+iola geo key status
+```
+
+Проверить рабочий запрос к API:
+
+```bash
+iola geo key doctor
+```
+
+Проверить геокодирование адреса:
+
+```bash
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+```
+
+CLI также понимает переменные окружения:
+
+- `YANDEX_GEOCODER_API_KEY`;
+- `YANDEX_MAPS_API_KEY`.
+
+## Официальные ссылки
+
+- Кабинет разработчика: `https://developer.tech.yandex.ru/services/`
+- API Геокодера: `https://developer.tech.yandex.ru/services/2`
+- Документация Geocoder API: `https://yandex.com/maps-api/docs/geocoder-api/`
+- Формат запроса: `https://yandex.com/maps-api/docs/geocoder-api/request.html`

package/wiki//320/232/320/276/320/274/320/260/320/275/320/264/321/213.md

@@ -26,6 +26,15 @@ iola card "школа 29"
 iola data schools --format csv --output schools.csv
 ```
 
+Геокодер:
+
+```bash
+iola geo key set yandex
+iola geo key status
+iola geo key doctor
+iola geo geocode "Йошкар-Ола, улица Петрова, 15"
+```
+
 Локальная БД:
 
 ```bash

package/wiki//320/234/320/260/321/201/321/202/320/265/321/200-/320/275/320/260/321/201/321/202/321/200/320/276/320/271/320/272/320/270.md

@@ -86,6 +86,14 @@ iola index folder ./docs
 
 Если runtime уже установлен, пункт показывается как `готово`.
 
+### 14. Yandex Geocoder API
+
+Сохраняет ключ Yandex Geocoder API локально у пользователя и проверяет его тестовым запросом.
+
+Нужен для будущих geo-skills: поиск объектов рядом с адресом, ссылки на карту, определение расстояний и уточнение населенного пункта.
+
+Инструкция по получению ключа: [Yandex Geocoder API key](Yandex-Geocoder-API-key).
+
 ## Повторный запуск
 
 Если компонент уже настроен, его можно не выбирать. Если нужно переустановить или обновить компонент, выберите его номер вручную.

package/wiki//320/241/320/272/320/270/320/273/320/273/321/213-/320/264/320/273/321/217-/320/266/320/270/321/202/320/265/320/273/320/265/320/271.md

@@ -0,0 +1,97 @@
+# Скиллы для жителей
+
+Эта страница фиксирует пользовательские skills, которые стоит развивать в `iola-cli`.
+
+Цель этих skills - помогать жителю города в бытовых вопросах: где находится объект, что рядом, какой объект ближе, как открыть место на карте. Это не административный аудит данных.
+
+## Geo skills
+
+Для geo skills нужен ключ `Yandex Geocoder API`.
+
+### nearby
+
+Находит городские объекты рядом с адресом пользователя.
+
+Примеры:
+
+- `какие детские сады рядом с Петрова 15`;
+- `какие школы ближе к улице Машиностроителей`;
+- `что из городских учреждений рядом с домом`.
+
+На первом этапе работает по слоям `schools` и `kindergartens`. Позже можно подключить МФЦ, поликлиники, остановки, спортобъекты и учреждения культуры.
+
+### route-context
+
+Объясняет, где находится объект, простым языком: адрес, ориентиры, что рядом, ссылка на карту.
+
+Это не полноценный навигатор и не замена маршрутизатору. Skill дает понятный контекст места для жителя.
+
+### address-to-services
+
+По адресу жителя подбирает релевантные городские объекты.
+
+Примеры:
+
+- ближайшие школы;
+- ближайшие детские сады;
+- будущие слои муниципальных услуг и учреждений.
+
+### map-link
+
+Добавляет в ответы ссылку на карту.
+
+Примеры:
+
+- открыть школу на Яндекс.Картах;
+- открыть детский сад на карте;
+- показать точку по координатам.
+
+### place-resolver
+
+Помогает понять криво написанные адреса, названия и ориентиры.
+
+Примеры:
+
+- `семеновка школа`;
+- `первомаиская 89`;
+- `садик золотой петушок`;
+- `рядом с вокзалом`.
+
+Главная задача - не подставлять похожий, но неправильный объект.
+
+### distance
+
+Считает расстояние от адреса пользователя до объекта или между объектами.
+
+Примеры:
+
+- `какой садик ближе к дому`;
+- `как далеко школа 7 от Первомайской 89`;
+- `что ближе: Пчелка или Улыбка`.
+
+### area-filter
+
+Фильтрует ответы по населенному пункту или району.
+
+Примеры:
+
+- Йошкар-Ола;
+- Семеновка;
+- другие населенные пункты городского округа, когда они появятся в слоях.
+
+Это важно, чтобы не путать объекты с одинаковыми номерами или похожими названиями.
+
+## Приоритет реализации
+
+Первый этап:
+
+1. `nearby`
+2. `place-resolver`
+3. `map-link`
+
+Второй этап:
+
+1. `distance`
+2. `area-filter`
+3. `route-context`
+4. `address-to-services`