Skip to content

Releases

wtctl 0.7.0

Choose a tag to compare

@ysamtme ysamtme released this 18 Oct 15:50

files.delete и files.list работают в wt_data и trash, когда сервер хранит эти папки в базе данных: файл, записанный files.write, виден в списке и удаляется тем же вызовом, что в веб-админке. Кроме того, исправлены исходы записи: native.physicalDocuments.createFromXml после сброса сессии не создаёт второй документ, objects.patch и objects.delete с id и url разных объектов отвечают отказом, а не правят объект по url, а 0x… считается ID только у целых полей формы. Значения заголовков авторизации и cookie в тексте ошибки закрываются целиком, а MCP-сервер без настроек проверяет первый вызов по его аргументам. Скрипты, которые правят документ объекта через files.write, нужно сверить с разделом «Несовместимые изменения».

Несовместимые изменения:

  • files.delete и files.write в любой папке отклоняют адрес документа объекта (x-local://<папка>/objects/<14 hex>/<2 hex>.xml): FILE_IS_DOCUMENT, исход not_sent. Подсказка называет objects.delete, objects.patch и native.lds.putDoc. Раньше запись по такому адресу меняла документ, но не строку каталога. files.read читает документ по адресу, как прежде.
  • native.physicalDocuments.createFromXml выполняет runtime (HcmClient, CLI, MCP-сервер); NativeGateway из wtctl/native её больше не перечисляет и не вызывает. В wtctl/protocol остаётся session.physicalDocuments.createFromXml.

Добавлено:

  • files.delete удаляет файлы в wt_data и trash, если сервер хранит эти папки в базе данных (DB-STORE-HOOK в его настройках), — тем же вызовом, что веб-админка, под правом write. Раньше там был отказ FILE_NOT_DELETABLE до отправки. Теперь FILE_NOT_DELETABLE с исходом indeterminate означает, что по адресу остался файл или пустая папка на диске сервера: с диска сервер по адресу ничего не удаляет. Адрес длиннее 256 знаков в такой папке — INVALID_ARGUMENT до отправки.
  • files.list в wt_data и trash, если сервер хранит эти папки в базе данных, показывает и файлы из базы: файл — с размером, «папку» — если в базе есть адреса глубже неё. Файл с копией в базе и на диске — одна строка, размер — копии из базы, которую отдаёт files.read. FOLDER_NOT_FOUND — только если по адресу нет ни папки на диске, ни файлов в базе. Раньше список показывал только диск: файла, записанного files.write, в нём не было, а папка с одними такими файлами отвечала FOLDER_NOT_FOUND.

Изменения:

  • web.resources.getImage и native.resources.getImage принимают ID ресурса и в записи 0x…, в которой его отдают каталоги, и сами переводят его в десятичную запись для сервера. Раньше такой ID отклонялся с «значение записано неверно».
  • files.delete в папке данных сначала проверяет адрес не длиннее 256 знаков: если по нему ничего нет, ответ — FILE_NOT_FOUND с исходом not_sent, на сервер ничего не уходит. В папке в базе данных подсказка говорит, что вложенных папок там нет и файлы удаляются по одному. Раньше в обычной папке данных сервер отвечал отказом HTTP 500.

Исправления:

  • native.physicalDocuments.createFromXml после сброса сессии сервером входит заново и повторяет только отклонённый запрос: документ записывается один раз, ответ — ok с его ID. Раньше клиент повторял всю операцию и создавал второй документ, а если сессию открыл сам вызов — отвечал not_sent при записанном документе. Если после записи войти заново не удалось, исход — indeterminate, и details.url называет адрес документа.
  • Отказ отправленного rpc.call даёт UNKNOWN_RPC_TARGET и not_sent, только когда библиотека прочитана целиком и функции в ней нет или такой библиотеки нет на сервере. Если файл библиотеки прочитать не удалось или он лежит в базе данных, остаётся ошибка сервера и исход indeterminate: функция могла выполниться.
  • Запись и код с исходом indeterminate после обрыва соединения, таймаута или потери связи подсказывают проверить, прошла ли запись, прежде чем повторять; у таймаута — ещё увеличить timeoutMs подключения. Раньше подсказка советовала повторить.
  • Шаг записи в runtime.batch, который отказал до отправки из-за неразрешимой $ref, получает mutationOutcome:"not_sent".
  • objects.get, objects.patch и objects.delete с id и url разных объектов отвечают TARGET_MISMATCH до записи и у документов без <id> или с пустым <id>, как у штатных справочников: id сверяется с ID в адресе документа. Если и адрес ID не называет, сверить нечем — тоже TARGET_MISMATCH. Раньше такой вызов правил и удалял объект по url, а отвечал с ID из id. Сообщение называет ID объекта из документа или адреса.
  • objects.create и objects.patch без formUrl берут форму, которую сервер объявляет для типа, как schema.get. Объекты типов тестирования (assessment и других), форма которых лежит вне x-local://wtv, создаются без formUrl; раньше создание отказывало.
  • 0x… и десятичная запись считаются одним ID только у целых полей формы. У строкового поля значения сравниваются как есть: objects.patch с ключом [code=0x1F] не трогает элемент с ключом 31, замена 31 на 0x1F записывается, условие runtime.query со значением "0x10" ищет строку. В contains значение всегда строка. Раньше 0x… превращалось в число у любого поля. Если форму прочитать не удалось, ID узнаётся по виду значения, как прежде.
  • Временный отказ чтения формы, файла языка, переводов названий типов и документа с настраиваемыми полями не запоминается: следующий вызов читает их заново. Раньше после такого отказа MCP-сервер не видел восстановления сервера до перезапуска.
  • runtime.check (hcm_check, wtctl check) отвечает на шаге query failed с причиной «база данных отвергла запрос; причина — в логе spxml_unibridge», если база отвергла пробный запрос. Раньше такой шаг считался пройденным.
  • schema.types, если документ с настраиваемыми полями прочитать не удалось, не показывает в строках customFields и называет это в notes. Раньше у всех типов было customFields: 0.
  • hcm_script с файлом не в UTF-8 отвечает mcp.file_unreadable «Файл с кодом должен быть текстом UTF-8.» и ничего не отправляет на сервер, как wtctl exec --input-file. BOM в начале файла убирается. Раньше кириллица файла в Windows-1251 молча превращалась в знаки U+FFFD и уходила на сервер, а BOM оставался в коде.
  • Значения заголовков Authorization, Proxy-Authorization, Cookie и Set-Cookie в тексте ошибки сервера — в details.scriptError, сообщении и SOAP Fault — закрываются до конца строки. Раньше закрывалось только первое слово: от Authorization: Bearer … оставался токен, от Cookie — все пары после первой.
  • MCP-сервер, запущенный без настроек, с первого вызова проверяет инструмент по эффекту вызова с его аргументами: hcm_api_read с native.lds.loadDoc и tryLock:true отвечает mcp.effect_mismatch и ничего не отправляет на сервер. Раньше первый вызов после появления настроек проверялся без аргументов, и блокировка проходила через инструмент чтения в обход одобрения записи в приложении. Одновременные первые вызовы такого сервера создают одно подключение, а не по одному на вызов; при закрытии сервера оно закрывается.
  • Превью сохранённого ответа runtime.batch помещается в outputLimitBytes: в preview.results — сводки первых шагов, пока помещаются, а подсказка говорит, сколько их из всех, как у списка items. Раньше превью пакета из многих шагов перечисляло все шаги и бывало больше предела.
  • Сохранённый ответ пакета из одного шага читается по шагам и выгружается в jsonl одной строкой. Раньше results.export с format:"jsonl" отвечал INVALID_RESULT_FORMAT. Шаг больше страницы results.read назван в blockedItem, и ответ называет список results.
  • XML-аргумент rpc.call и native.*, который начинается с декларации <?xml …?>, как документ, прочитанный через files.read, уходит внутри SOAP без неё; во вложении (native.lds.putDoc) и в загружаемом файле декларация остаётся как есть. Декларация в другом месте аргумента — INVALID_ARGUMENT до отправки, исход not_sent. Раньше декларация попадала внутрь SOAP, и сервер получал неверный XML. В wtctl/protocol декларацию не в начале так же отклоняет rawXml().
  • maxResponseBytes в параметрах отдельного вызова wtctl/protocol действует у всех SOAP-вызовов (lds, rpc, фоновые задачи) и у страницы /admin: меньший предел отклоняет большой ответ, Infinity снимает предел клиента. Раньше у этих вызовов работал только предел клиента.
  • rpc.list и rpc.describe читают файл библиотеки в той кодировке, которую выбирает сервер: по метке порядка байтов, иначе по encoding в объявлении <?xml …?>, иначе как UTF-8. Библиотека в Windows-1251 с кириллицей больше не попадает в skipped. rpc.describe функции из библиотеки, файл которой прочитать не удалось, отвечает «Библиотеку … прочитать не удалось, описания функции … нет.» и подсказывает, что rpc.call вызывает функцию и без описания. Раньше сообщение говорило, что такой библиотеки на сервере нет.
  • schema.get и schema.types, если файл языка прочитать не удалось, не показывают заголовков, которые берутся из него, и говорят об этом одним примечанием в notes: «Файл языка … прочитать не удалось: заголовков из него в ответе нет.» Примечание есть и у пустого ответа поиска schema.types: тип мог не найтись по такому заголовку. Заголовки, записанные в форме, и переводы названий типов остаются. Раньше вместо заголовка показывался ключ (title: "const=c_person"), schema.types искал по нему и примечания не давал.
  • CLI называет пропущенную или неизвестную команду так, как её набрали, и перечисляет, какие есть, в порядке справки: wtctl server отвечает «Не указана команда после wtctl server: есть info.», wtctl object foo — «Команды wtctl object foo нет: есть get, create, patch, delete.», wtctl srever — «Команды wtctl srever нет.» с подсказкой «Похожие: server.». Раньше ответ был «Неизвестная команда server.», будто нет самой команды server, а wtctl result foo и wtctl rpc foo отвечали «Не хватает аргументов команды.». wtctl help srever отв...
Read more

wtctl 0.6.0

Choose a tag to compare

@ysamtme ysamtme released this 16 Oct 07:39

Файлы любого размера: files.write пишет их путём настольной админки и сверяет после записи, files.read сохраняет файл сервера на диск, а своих пределов размера ввода, кода и загрузки у клиента больше нет. Кроме того, точнее стали ошибки и подсказки: отказ загрузки по политике сервера — UPLOAD_REFUSED, сбой части загрузки не выдаётся за недоступный сервер, отказы по именам предлагают похожие, hcm_types видит каталоги базы trash. Настройки приложений и скрипты, которые работают с инструментами логов, objects.patch или schema.types, нужно сверить с разделом «Несовместимые изменения».

Несовместимые изменения:

  • Инструменты MCP hcm_log_read и hcm_log_follow называются hcm_logs_read и hcm_logs_follow, как hcm_logs_list, hcm_logs_search и команды wtctl logs …. Вызов по старому имени отвечает mcp.unknown_tool, подсказка называет новое имя. Разрешение, выданное в приложении по старому имени инструмента, нужно выдать заново.
  • objects.patch отклоняет remove с путём, которому в документе ничего не соответствует: PATCH_PATH_MISSING, сообщение называет путь, ничего не записано, даже если другие пути вызова нашлись. С preview:true — тот же отказ. Раньше такой путь молча пропускался, и опечатку в ключе элемента было не отличить от «удалять нечего». Скрипт, который удаляет элемент, не зная, есть ли он, должен сначала прочитать объект.
  • before и after у структуры в changes ответа objects.patch — объект с полями первого уровня; вложенные структуры и списки по-прежнему названы, а не скопированы. Раньше это была строка с именами полей: "{collaborator_id}". Предпросмотр удаления элемента списка показывает его ключ и поля.
  • В ответе schema.types (hcm_types, wtctl types) нет поля catalogs с числом каталогов: каталоги без своего типа объекта теперь перечислены в самом списке и входят в total. В SDK у строк types поля type и customFields необязательные.
  • Если сервер не сообщил списки папок, files.write требует права execute для любой папки: без списков клиент не отличает папку данных от папки кода. Раньше такая запись шла с одним write.

Добавлено:

  • Загрузка (web.pages.uploadFile, web.pages.uploadChunk, wtctl file upload), которую сервер отклонил по своей политике загрузки, отвечает UPLOAD_REFUSED. Подсказка называет, какие имена обычно принимает загрузка, и что файл по своему адресу записывает files.write. У загрузки частями в сообщении текст отказа сервера; на загрузку одним запросом сервер текст в ответе не передаёт, только пишет в свой лог. Раньше отказ был PLATFORM_HTTP с HTTP 415 или 500 без причины.

  • schema.types перечисляет после типов каталоги без своего типа объекта (group_collaborators, event_collaborators, trash_docs и другие) строками {catalog} без type, и поиск находит их по имени. Строки таких каталогов строит сервер, документов у них нет; искать в них можно через hcm_query. Раньше ответ давал только их число, а имя называл, только когда поиск находил его или тип с тем же началом имени.

  • files.write принимает file — полный путь к файлу на компьютере, где работает клиент (у MCP-сервера — где он запущен). Файл читается с диска частями, содержимое не идёт через вызов, и память клиента не растёт с размером файла. wtctl files write АДРЕС --input-file ФАЙЛ передаёт операции путь, в SDK — writeFile({ url, file }).

  • files.read с file сохраняет файл сервера на диск байт в байт, текст или двоичный, любого размера: файл не проходит через ответ, maxResponseBytes на него не действует, и память клиента не растёт с размером файла. Ответ — {bytes, file} с полным путём. Существующий файл заменяется только с overwrite:true, иначе FILE_EXISTS; недочитанный файл под своим именем не появляется. В CLI — wtctl files read АДРЕС --to ФАЙЛ [--overwrite], в SDK — readFile({ url, file, overwrite }).

  • Предпросмотр objects.patch называет в serverFilled поля правки, которые сервер заполняет сам при сохранении документа, например position_name у сотрудника: записанное значение он, скорее всего, заменит. Клиент узнаёт такие поля по коду формы, поэтому список бывает и лишним, и неполным. READ_BACK_MISMATCH по такому полю называет причину и поле, которое менять вместо него: position_id вместо position_name.

Изменения:

  • files.write пишет файл любого размера в любую папку данных и папку кода, в том числе в wt_data и trash, тем же способом, что настольная админка. Запись в папку кода больше не идёт через код на сервере, но по-прежнему требует права execute: файл там — код сервера. Пределы 750 КБ текста и 580 КБ двоичных данных убраны, запись больше не отвечает FILE_TOO_LARGE.
  • После записи files.write читает файл с сервера и сверяет с отправленным: confirmed значит, что на сервере ровно отправленные байты, а расхождение — READ_BACK_MISMATCH. Прерванная запись отвечает indeterminate с сообщением, что файл на сервере может быть пустым или недописанным и запись можно повторить целиком. Если файл записан, а прочитать его для сверки не удалось (например, истёк timeoutMs), ответ — тоже indeterminate, но сообщение говорит именно это: содержимое на сервере не проверено.
  • files.read получает файл потоком байт, а не в base64 внутри XML: ответ приходит быстрее, и клиенту нужно меньше памяти. Без file предел maxResponseBytes считается по размеру самого файла, а файл больше предела отвечает FILE_TOO_LARGE с подсказкой сохранить его через file. Раньше такой файл отвечал PLATFORM_PROTOCOL «Ответ сервера не соответствует ожидаемому виду».
  • У клиента нет своих пределов размера. Ввод команды wtctl (--input-file, --stdin, --params-file) больше 8 МБ, код для выполнения больше 1 МБ и загрузка web.pages.uploadFile больше 8 МБ проходят; ошибки SCRIPT_TOO_LARGE больше нет, а maxResponseBytes загрузку не ограничивает. Размер ограничивают сервер, память и диск компьютера и timeoutMs: см. раздел «Размер файлов и данных» в docs/configuration.md.
  • Запись files.write в сотни мегабайт идёт втрое быстрее, а код на сервере в мегабайт уходит вдвое быстрее: клиент не проверяет заново XML, который собрал сам, и быстрее проверяет большие строки.
  • SCRIPT_FAILED ставит исход not_sent только на отказ разбора кода в том виде, в каком его присылают 2025.1 и 2025.2; любая другая ошибка в коде — indeterminate. Подсказка при indeterminate говорит, что код, который только читал, можно повторить, а код, который менял данные, — сначала проверить.
  • Отказы по именам типов, каталогов и операций предлагают похожие имена и при опечатке в одну букву. У INVALID_FILTER_OPERATOR появилась подсказка, а rpc.list, скрыв функции, которые вызываются только из кода на сервере, подсказывает all:true.
  • Подсказка отказа обрезается на 1000 знаках вместо 500, обрезанные сообщение и подсказка кончаются многоточием. Превью сохранённого ответа показывает столько элементов списка, сколько помещается, а подсказка говорит, сколько из них показано: «первые 40 из 1000».

Исправления:

  • schema.types (hcm_types) называет каталог и у типов, каталог которых лежит в базе trash: user_data — user_datas, active_web_template, profiling_record. schema.get по такому типу отмечает поля каталога query:true. Раньше у них не было поля catalog, а гайд говорил, что каталога нет вовсе.
  • Отказ files.delete в wt_data и trash (FILE_NOT_DELETABLE) больше не говорит, что сервер там не удаляет файлы: файл, который записал files.write, сервер хранит не на диске, и клиент не отличает его от файла на диске. Сообщение — «В папке wt_data файлы и папки не удаляются.», подсказка советует писать временные файлы в share.
  • Сбой части загрузки на сервере (web.pages.uploadChunk, HTTP 501–503) больше не выдаётся за недоступный сервер. Ответ — PLATFORM_HTTP «Сервер не записал часть файла (HTTP 502).» или, на последней части, «Сервер не собрал файл из частей (HTTP 503).», подсказка — повторить загрузку целиком. Текст сервера не показывается: в нём бывают пути сервера.
  • mcp.invalid_arguments называет лишний аргумент: «Аргументы не подходят инструменту: лишний аргумент query.», несколько — «лишние аргументы query, foo». В details.validation у этой причины — keys с именами. Раньше сообщение было общим, а у причины был пустой path.
  • Подсказка WRITE_DISABLED и EXECUTE_DISABLED у копии подключения в SDK ({ ...loadConfig(), timeoutMs }) называет подключение и где включить право, как у самого подключения; раньше подсказка была общей. Фраза «MCP-сервер видит правку после перезапуска» осталась только у MCP-сервера: в CLI и SDK её больше нет.
  • files.read без file держит в памяти меньше копий файла: у файла 64 МБ пик памяти клиента — около 300 МБ, раньше около 500 МБ. Ответ и сохранённый результат прежние.
  • files.write больше 2 МБ в папку данных записывал обрезанный файл и отвечал confirmed.
  • Запись files.write в wt_data не доходила до сервера: ответ был confirmed, а files.read отдавал прежнее содержимое.
  • Файл в сотни мегабайт files.read не читал и с большим maxResponseBytes: клиенту не хватало памяти.
  • Двоичные данные {base64} примерно от 3 МБ в загрузке (web.pages.uploadFile, web.pages.uploadChunk) и в native.lds.putUrl отвечали INTERNAL_ERROR: проверка base64 в клиенте переполняла стек.
  • Время запроса, истёкшее посреди ответа сервера, называется таймаутом с подсказкой про timeoutMs. Раньше ответ говорил, что соединение оборвалось.
  • Отказ диска при сохранении файла на этом компьютере (results.export, files.read с file) — нет прав, места или путь не годится — отвечает FILE_SAVE_FAILED с кодом системы. Раньше ответ был INTERNAL_ERROR с подсказкой, что это дефект клиента.
  • Подключение с usernameEnv или passwordEnv, чья переменная не задана или пуста, отклоняется с INVALID_CONFIG, и сообщение называет переменную. Раньше ответ говорил «не задан пароль», а без обеих переменных подключение открывалось без учётных данных. config init --password-env с нез...
Read more

wtctl 0.5.0

Choose a tag to compare

@ysamtme ysamtme released this 14 Oct 23:01

Три темы. Скрипты на команде wtctl и SDK: неполный ответ даёт код выхода 3, SDK перебирает строки запроса методом queryRows, его имена описаны по-русски в подсказках редактора и в справочнике docs/sdk-reference.md, в docs/cli.md — рецепты для PowerShell. Локальные файлы клиента: сохранённые результаты и журнал записей держатся в пределах размера и срока. Ошибки: точнее коды, исходы записи и подсказки, тексты без английских слов. Скрипт, который брал из точки входа wtctl HcmRuntime, LogReader или withHcm, нужно поправить: см. «Несовместимые изменения».

Несовместимые изменения:

  • Убраны пять низкоуровневых операций, которые повторяли другие: native.lds.openSession и web.lds.openSession — вместо них native.session.open и web.session.open; native.lds.closeSession и web.lds.closeSession — вместо них native.session.close и web.session.close; native.spxml.call — вместо неё native.rpc.call. Вызов убранного ID отвечает UNKNOWN_OPERATION. Ответ *.session.* содержит ещё поле profile. В wtctl/protocol у NativeSession убрано поле spxml: это был тот же объект, что rpc.
  • В SDK убрано поле status у операций: оно у всех было implemented и ничего не значило. Его больше нет в ответе getNativeOperations(), listHcmOperations() и describeHcmOperation() и в типе OperationDefinition; убраны фильтр status у listHcmOperations() и флаг --status у wtctl api list.
  • В SDK у LogReader убраны поля-константы с английскими пояснениями: semantics и consistency у ответа read(), severityDetection и lineNumbers у search(), semantics у follow(). Их нет и в типах LogReadData, LogSearchData, LogFollowData. В ответы logs.* они и раньше не попадали.
  • Команда wtctl завершается с кодом 3, когда ответ не поместился в outputLimitBytes и сохранён локально: в stdout прежний JSON с ok:true, meta.truncated и meta.resultId, но данных в нём только начало. Раньше код был 0, и скрипт мог принять начало за весь ответ. Скрипт, который считает ошибкой любой ненулевой код, теперь остановится и на таком ответе: дочитать его — wtctl result read или wtctl result export, получить сразу целиком — --output ФАЙЛ, с ним код 0. Операция при коде 3 выполнена: запись или код на сервере повторять не нужно.
  • Точка входа wtctl отдаёт только то, что описано для вызывающего: HcmClient, withHcmClient, loadConfig, unwrap, getCleanupError, HcmError, HcmOperationError, HcmStoredResultError, HcmCleanupError, listHcmOperations, describeHcmOperation и типы аргументов и ответов. Убраны HcmRuntime, NativeGateway, getNativeOperations, LogReader, LogReadUnavailableError, RpcCatalog, withHcm, parseFileExists, parseServerInfo, configExample и типы HcmSdkRuntime, NativeConfig, NativeOperation, LogFile, LogEvent, LogListData, LogReadData, LogSearchData, LogFollowData. Убран HcmClient.fromRuntime; конструктор HcmClient в типах принимает только подключение, поля runtime в типах нет. NativeGateway и getNativeOperations по-прежнему есть в wtctl/native. Вместо withHcm — withHcmClient, вместо LogReader — client.listLogs, readLog, searchLogs, followLog.
  • Поле verification в ответе objects.delete — server или catalog, как другие значения протокола клиента. Раньше было server acknowledgement и catalog absence. Тип DeletedObjectData.verification в SDK — "server" | "catalog".

Добавлено:

  • Клиент сам удаляет старые сохранённые результаты, когда сохраняет новый: старше resultsMaxAgeDays (по умолчанию 7 дней), затем самые старые, пока результаты подключения больше resultsMaxBytes (1 ГБ). Результаты моложе часа остаются, поэтому предел приблизительный. Чтение удалённого результата отвечает RESULT_NOT_FOUND с подсказкой повторить запрос. Раньше папка результатов только росла.
  • Журнал записей mutations.jsonl не больше journalMaxBytes (10 МБ): переполненный файл становится mutations.1.jsonl, новые строки идут в новый файл. Журнал описан в docs/configuration.md.
  • 0 в resultsMaxBytes, resultsMaxAgeDays и journalMaxBytes снимает предел.
  • Переменные WTCTL_MAX_RESPONSE_BYTES, WTCTL_OUTPUT_LIMIT_BYTES, WTCTL_RESULTS_MAX_BYTES, WTCTL_RESULTS_MAX_AGE_DAYS и WTCTL_JOURNAL_MAX_BYTES: теперь все поля подключения, кроме адреса, учётных данных и прав, задаются и без файла, в том числе в env MCP-сервера. Как и WTCTL_TIMEOUT_MS, они действуют и при файле с разделом connections. Ошибка в значении называет поле и переменную. Число в переменной и в файле записывается только цифрами: 5e3 и пробелы вокруг числа больше не принимаются.
  • loadConfig({ settings }) в SDK задаёт те же поля кодом, с той же проверкой; settings сильнее переменных и файла. Адрес, учётные данные и права подключения из файла или переменных settings не меняет. settings с baseUrl — отдельное подключение без файла и переменных, права по умолчанию выключены.
  • wtctl object get, patch и delete принимают ID без типа: wtctl object get 0x… --fields login. Тип перед ID по-прежнему можно указать, тогда команда проверяет тип объекта.
  • У каждого имени, которое экспортирует wtctl, у методов HcmClient и у полей их аргументов и ответов в типах пакета есть описание по-русски: что делает метод, что значит поле, когда unwrap бросает. Его показывает подсказка редактора. Новые имена типов вместо безымянных: GetManyInput, GetManyData, RunAgentInput, FileListInput, ResultExportData, LogResetReason. docs/sdk.md перечисляет функции и классы пакета.
  • Справочник SDK docs/sdk-reference.md: каждая функция, метод HcmClient, ошибка и тип с аргументами, полями ответа и описанием — тот же текст, что в подсказке редактора. Таблица типов методов в docs/sdk.md заменена ссылкой на него.
  • client.queryRows(args) в SDK перебирает строки каталога или запроса XQuery одним for await: аргументы те же, что у query, страницы метод листает сам. Страница с incomplete:true бросает HcmOperationError с кодом QUERY_INCOMPLETE и подсказкой сервера, а не выглядит как конец данных. Большой ответ бросает HcmStoredResultError, как unwrap.
  • В docs/cli.md раздел «Скрипты»: выгрузка в CSV постранично в PowerShell с проверкой кода выхода, объект со списком и добавление элемента по ключу, перевод сотрудника в другое подразделение, код с параметрами из файла, какие значения приходят в ответе и что учесть в Windows PowerShell 5.1. Новый пример examples/export-csv.ps1; examples/sdk.mjs перебирает строки через queryRows. В docs/sdk.md — queryRows вместо своего цикла по страницам и раздел «Значения».
  • docs/installation.md описывает, как включить плагин в Claude Code только в отдельных проектах: --scope local и --scope project.
  • docs/compatibility.md: загрузка частями оставляет на сервере пустую папку filechunk/<fileId>, как и загрузка большого файла в админке.

Исправления:

  • У ошибок SDK в name имя класса: HcmStoredResultError, HcmOperationError, HcmCleanupError. Раньше у всех было HcmError. Подсказка HcmStoredResultError называет методы SDK readResult и exportResult и loadConfig({ settings: { outputLimitBytes } }), а не операции и инструменты MCP.
  • Сбой в коде самого клиента отвечает INTERNAL_ERROR. Раньше часть таких сбоев приходила как INVALID_ARGUMENT с английским сообщением движка JavaScript и подсказкой про аргументы, хотя аргументы были в порядке. Отказы по аргументам остались INVALID_ARGUMENT с прежними текстами. Подсказка у INTERNAL_ERROR говорит, что это дефект клиента и подбирать аргументы не нужно; то же сказано в теме гайда errors.
  • Отказы по аргументу, у которых был английский текст Node, получили русский: неверные path и headers у *.experimental.rawRequest, значение в params у execute.script, которое нельзя записать как JSON, нулевой символ в path у results.export. Неверный method у *.experimental.rawRequest отклоняется до запроса как INVALID_ARGUMENT, а не как PLATFORM_HTTP. objects.get по адресу файла не в UTF-8 отвечает INVALID_XML с подсказкой про files.read.
  • Неизвестный ID операции CLI и MCP-сервер называют в ошибке так, как его передали, а похожие на него — ID операций. Раньше в них подставлялись имена команд или инструментов: wtctl api call api.list отвечал «Операции wtctl api list нет». Ошибки, которые CLI получает до вызова операции, тоже называют команды CLI.
  • Подсказка TARGET_MISMATCH не говорит «Запись не отправлена»: так было и у objects.get, где записи нет, и после записи с исходом indeterminate. Подсказка CATALOG_MISMATCH у objects.delete тоже больше не говорит об исходе. Его сообщает mutationOutcome.
  • Отказы по аргументу, которые шлюз находит до отправки, у низкоуровневых операций записи и выполнения кода отвечают mutationOutcome: not_sent, а не indeterminate: недопустимый в XML символ у native.lds.* и web.lds.*, path, headers и method у *.experimental.rawRequest, dbName у native.physicalDocuments.createFromXml.
  • native.resources.getImage и web.resources.getImage не оставляют соединение, которое сервер закрывает после картинки. Раньше на только что запущенном сервере следующий запрос в это соединение обрывался: PLATFORM_HTTP «Соединение оборвалось». Так бывало на серверах 2025.1.1171 и 2025.1.1333.
  • objects.create с dbName, которого нет на сервере, отвечает INVALID_ARGUMENT до выдачи ID, исход — not_sent; подсказка называет базы сервера. Раньше сервер выдавал ID, запись отвечала HTTP 500 с исходом indeterminate, а подсказка говорила о значении поля.
  • wtctl query --fields id,fullname без кавычек работает в PowerShell: списки --fields, --ids, --order, --origin и --include делятся и по запятой, и по пробелу. Раньше PowerShell передавал id,fullname команде через обёртку npm как id fullname, и поиск отвечал INVALID_FIELDS. В --order desc и asc остаются при поле перед ними.
  • Поля строки ответа query идут в по...
Read more

wtctl 0.4.0

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 20:45

Все тексты клиента — по-русски. Имена инструментов, команд, операций и аргументов, коды ошибок и ответы операций не менялись.

Изменения:

  • Описания низкоуровневых операций в api list, api describe и инструментах hcm_api_* написаны по-русски; раньше они были английскими. У пяти операций в api describe появилось поле details с полным описанием. Страница api list вмещает на несколько карточек меньше: её предел считается в байтах.
  • Сообщения ошибок клиента, шлюза и слоя протокола и сообщения CLI написаны по-русски. Коды ошибок, условия отказов и исходы записи прежние: программе нужно сравнивать error.code, а не текст.
  • Комментарии в объявлениях типов пакета (.d.ts) написаны по-русски.
  • Описание пакета в package.json написано по-русски; английская строка в начале README убрана.
  • Внутреннее устройство клиента: каждая операция описана одним определением вместе со своим обработчиком, runtime держит только конвейер вызова. Тип ответа методов SDK сверяется с обработчиком операции при сборке. На проверенных серверах ответы CLI и MCP-сервера совпали с 0.3.1.

wtctl 0.3.1

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 14:17

Исправление исхода записи и переработка внутреннего устройства клиента без изменения операций.

Исправления:

  • Запись, которую сервер принял, а проверочное чтение отклонил отказом во входе, даёт indeterminate, а не not_sent; подсказка говорит, что запрос на запись уже ушёл и что запись нужно проверить, прежде чем повторять. Отказ во входе на первом же запросе по-прежнему даёт not_sent.

Изменения:

  • Внутреннее устройство клиента переработано: все запросы к серверу идут через один модуль, исход записи считает один модуль, ответ собирает один модуль. Операции, их аргументы и ответы прежние: на серверах 2025.1.1171 — 2025.2.1535 ответы CLI и MCP-сервера совпали с ответами 0.3.0.
  • В типах пакета у конструктора HcmRuntime появился необязательный второй параметр — способ обращения к серверу. Без него всё работает как раньше.

wtctl 0.3.0

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 08:32

Чистка операций по итогам прогона на проверенных серверах и уточнение прав.

Несовместимые изменения:

  • Убраны шесть операций, которые отказывали на всех проверенных серверах: native.lds.getModDeletedObjects, native.lds.createDoc, web.pages.createDoc, web.pages.getIcon, web.experimental.getUiTemplate, web.lifecycle.logout2.
  • Убраны операции больших полей: native.lds.loadLargeField, native.lds.putLargeField, native.lds.deleteLargeField, web.spxml.putLargeField, web.spxml.putLargeFieldFromUrl. На проверенных серверах полей с адресом x-db-obj:// нет, и ни одна из этих операций ни разу не отработала.
  • Убрана группа native.experimental.spxml (восемь операций): она повторяла web.spxml.*. Вместо неё — web.spxml.callMethodAsync, getAsyncMethodStatus, killAsyncMethod, getBackgroundTasksByName, getDoc, putDoc.
  • native.lds.getNewObjectId требует права write и вызывается через hcm_api_write: каждый вызов расходует ID.
  • files.delete в папках wt_data и trash отказывает до отправки (FILE_NOT_DELETABLE): сервер там файлы и папки по адресу не удаляет. В 0.2.2 запрос уходил, и операция отвечала READ_BACK_MISMATCH.
  • wtctl/protocol: убраны методы и типы ушедших операций и класс NativeExperimentalSpXmlApi.

Изменения:

  • rawRequest с методом GET или HEAD считается чтением и не требует прав write и execute; признак unsafe: true нужен по-прежнему.
  • MCP SDK обновлён до 1.31.0.

wtctl 0.2.2

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 02:21

Исправления:

  • files.delete проверяет адрес после ответа сервера. В папках базы сервера wt_data и trash сервер отвечает на удаление файла и пустой папки как на успешное, а файл остаётся: раньше операция отвечала deleted:true с исходом confirmed, теперь — READ_BACK_MISMATCH с исходом indeterminate. Проверено на 2025.1.1333 — 2025.2.1535; в остальных папках данных удаление работает как раньше.

Документация:

  • Гайд по файлам и страница совместимости: wt_data и trash сервер читает через память. Файл и папка там по адресу не удаляются, а после перезаписи файла files.read может отдать прежнее содержимое.

wtctl 0.2.1

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 01:35

Несовместимые изменения:

  • Убраны операции web.spxml.getLargeField и native.experimental.spxml.getLargeField. На сервере 2025.2.1535 вызов с адресом x-db-obj:// типа, у которого нет хранилища больших полей, завершал процесс сервера. Операция числилась чтением и не требовала прав write и execute; ни на одном проверенном сервере она не отработала. В версиях до 0.2.1 её лучше не вызывать.
  • wtctl/protocol: убраны методы getLargeField и тип GetLargeFieldRequest.

Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно.

wtctl 0.2.0

Choose a tag to compare

@ysamtme ysamtme released this 13 Oct 01:11

Файлы сервера: запись и удаление в любой папке, куда сервер принимает файлы, и список папки. Убраны операции, которые не работали.

Несовместимые изменения:

  • Операции с файлом по адресу убраны: native.lds.loadUrl, native.lds.putUrl, native.lds.deleteUrl, native.lds.unlockUrl, web.lds.deleteUrl, web.pages.copyUrl. Вместо них — files.read, files.write, files.delete, files.list; копия файла — чтение и запись по новому адресу.
  • Команды wtctl file get, file put, file delete убраны: их заменяют wtctl files read, files write, files delete. wtctl file upload осталась.
  • Убраны 16 операций, на всех проверенных серверах они отвечали отказом или не использовались: группа legacy.xhttp (9 операций), legacy.session.open, legacy.session.close, legacy.experimental.rawRequest, native.lds.eval, web.lds.eval, native.experimental.readDirectory, web.pages.putUrl. Профиль legacy убран целиком.
  • Ключи подключения installationId и installationIdFile, переменные WTCTL_INSTALLATION_ID и WTCTL_INSTALLATION_ID_FILE убраны; оставшиеся в файле подключений ключи игнорируются.
  • wtctl/protocol: убраны LegacySession, XHttpBinaryResponse, типы LegacyCatalogKey и XHttpResult, методы клиента openLegacySession и withLegacySession, вид ошибки xhttp-result, методы NativeLdsApi.unlockUrl, WebLdsApi.deleteUrl, WebPageApi.copyUrl. У двоичного результата больше нет поля records.

Новое:

  • files.write и files.delete работают в любой папке, куда сервер принимает файлы. Путь клиент выбирает до отправки, по спискам папок самого сервера: в папке данных (share, wt_data и других) хватает права write; в папке кода (wt, wtv, custom и других) файл записывает и удаляет код на сервере, нужны write и execute; в остальные папки запрос не отправляется. files.delete в папке данных удаляет и пустую папку.
  • files.list — один уровень папки: файлы с размером и вложенные папки; search оставляет имена с заданной частью. Нужно право execute.
  • server.info называет папки подключённого сервера: dataFolders, codeFolders.
  • CLI: wtctl files write, files delete, files list. SDK: writeFile, deleteFile, listFiles.
  • Страница docs/compatibility.md: что отличается между версиями сервера и базами, что не работает ни на одном проверенном сервере, что не проверено.

Исправления:

  • Синтаксическая ошибка во всём коде для сервера даёт исход not_sent: такой код сервер не выполняет. Раньше подсказка говорила то же, а исход был indeterminate.
  • files.delete по адресу без файла в папке кода отвечает FILE_NOT_FOUND.
  • results.export с путём к папке вместо файла отвечает INVALID_ARGUMENT, а не внутренней ошибкой.

Прочее:

  • scripts/generate-native-registry.mjs --check сверяет src/native/generated.ts с кодом протокола; проверка входит в npm run verify.

Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно.

wtctl 0.1.2

Choose a tag to compare

@ysamtme ysamtme released this 12 Oct 23:35

Только тексты, код не менялся.

  • Гайд по файлам: native.lds.putUrl и native.lds.deleteUrl работают только в папках данных сервера. Как положить и удалить файл в папке кода и получить список папки кодом на сервере.
  • docs/security.md: write без execute — не запрет на код: объекты с кодом, например агенты сервера, сервер запускает сам.
  • README: что проверено на файловой базе.

Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно и может её пропустить.