@oneentry/mcp-platform-server 0.1.1 → 0.1.3

package/dist/api/catalog.d.ts

@@ -1,7 +1,6 @@
 import type { Config } from '../config/config.js';
 import { type PermissionMap } from './build-catalog.js';
 import type { Catalog, Operation } from './types.js';
-/** Найденная операция с оценкой релевантности. */
 export interface OperationHit {
     opId: string;
     method: string;
@@ -12,40 +11,16 @@ export interface OperationHit {
     risk: Operation['risk'];
     score: number;
 }
-/**
- * Индекс каталога операций.
- * Поиск здесь примитивный — подсчёт совпадений термов по склеенной строке.
- * Это осознанно: путей 478, они короткие и хорошо самоописаны,
- * полнотекстовый движок дал бы ту же выдачу при большем весе.
- */
 export declare class OperationCatalog {
     private byOpId;
     catalog: Catalog;
     constructor(catalog: Catalog);
-    /** Карта прав — единственное, что осталось предсобранным: её нет в swagger. */
     static permissionMap(): PermissionMap;
-    /**
-     * Строит каталог из swagger подключённого стенда.
-     * Недоступный стенд не мешает серверу подняться: каталог получается пустым,
-     * а причина уходит в `warnings` и оттуда в `cms_guide` и `cms_whoami`.
-     * Пустой каталог безопасен — вызвать по нему нечего, — но молчать о нём нельзя.
-     */
     static resolve(config: Config, bearer?: string): Promise<OperationCatalog>;
-    /** Каталог не удалось собрать при старте — стенд был недоступен или закрыт авторизацией. */
     get isEmpty(): boolean;
-    /**
-     * Заменяет содержимое каталога, собранного вхолостую.
-     * Нужно remote-режиму: процесс поднимается без учётных данных, и если стенд
-     * отдаёт swagger только авторизованным, единственный шанс получить каталог —
-     * первая сессия с токеном. Каталог общий на процесс, поэтому и подмена одна.
-     */
     adopt(other: OperationCatalog): void;
     get(opId: string): Operation | undefined;
     operations(): readonly Operation[];
-    /**
-     * Подсказывает похожие `opId` — нужна для внятной ошибки, когда модель
-     * угадала имя операции вместо того, чтобы взять его из поиска.
-     */
     suggest(opId: string, limit?: number): string[];
     search(params: {
         query: string;
@@ -55,4 +30,3 @@ export declare class OperationCatalog {
         limit?: number;
     }): OperationHit[];
 }
-//# sourceMappingURL=catalog.d.ts.map

package/dist/api/catalog.js

@@ -3,12 +3,6 @@ import { resolve } from 'node:path';
 import { dataDir } from '../knowledge/loader.js';
 import { buildCatalog } from './build-catalog.js';
 import { fetchSwagger } from './swagger-source.js';
-/**
- * Индекс каталога операций.
- * Поиск здесь примитивный — подсчёт совпадений термов по склеенной строке.
- * Это осознанно: путей 478, они короткие и хорошо самоописаны,
- * полнотекстовый движок дал бы ту же выдачу при большем весе.
- */
 export class OperationCatalog {
     byOpId;
     catalog;
@@ -16,22 +10,14 @@ export class OperationCatalog {
         if (catalog.version !== 1) {
             throw new Error(`Unsupported catalog version ${String(catalog.version)}`);
         }
-        /** Каталог собирается из документа, полученного по сети: поля нормализуем на входе. */
         this.catalog = { ...catalog, warnings: catalog.warnings ?? [] };
         this.byOpId = new Map(catalog.operations.map((o) => [o.opId, o]));
     }
-    /** Карта прав — единственное, что осталось предсобранным: её нет в swagger. */
     static permissionMap() {
         const file = resolve(dataDir(), 'permissions.json');
         const parsed = JSON.parse(readFileSync(file, 'utf8'));
         return { byOpId: parsed.byOpId, permissions: parsed.permissions };
     }
-    /**
-     * Строит каталог из swagger подключённого стенда.
-     * Недоступный стенд не мешает серверу подняться: каталог получается пустым,
-     * а причина уходит в `warnings` и оттуда в `cms_guide` и `cms_whoami`.
-     * Пустой каталог безопасен — вызвать по нему нечего, — но молчать о нём нельзя.
-     */
     static async resolve(config, bearer) {
         const builtAt = new Date().toISOString();
         try {
@@ -51,7 +37,7 @@ export class OperationCatalog {
                     ...catalog,
                     warnings: [
                         ...catalog.warnings,
-                        `The stand at ${config.baseUrl} was unreachable; this catalog came from the ` +
+                        `The instance at ${config.baseUrl} was unreachable; this catalog came from the ` +
                             'on-disk cache and may not match the API that is actually running.',
                     ],
                 }
@@ -65,24 +51,17 @@ export class OperationCatalog {
                 swaggerHash: '',
                 permissions: [],
                 warnings: [
-                    `The operation catalog is EMPTY: ${config.baseUrl} did not serve its swagger ` +
+                    `The operation catalog is EMPTY: ${config.baseUrl} did not serve its API document ` +
                         `(${error instanceof Error ? error.message : String(error)}). ` +
-                        'No API operation can be searched or called until the stand is reachable.',
+                        'No API operation can be searched or called until the instance is reachable.',
                 ],
                 operations: [],
             });
         }
     }
-    /** Каталог не удалось собрать при старте — стенд был недоступен или закрыт авторизацией. */
     get isEmpty() {
         return this.catalog.operations.length === 0;
     }
-    /**
-     * Заменяет содержимое каталога, собранного вхолостую.
-     * Нужно remote-режиму: процесс поднимается без учётных данных, и если стенд
-     * отдаёт swagger только авторизованным, единственный шанс получить каталог —
-     * первая сессия с токеном. Каталог общий на процесс, поэтому и подмена одна.
-     */
     adopt(other) {
         this.catalog = other.catalog;
         this.byOpId = new Map(other.catalog.operations.map((o) => [o.opId, o]));
@@ -93,10 +72,6 @@ export class OperationCatalog {
     operations() {
         return this.catalog.operations;
     }
-    /**
-     * Подсказывает похожие `opId` — нужна для внятной ошибки, когда модель
-     * угадала имя операции вместо того, чтобы взять его из поиска.
-     */
     suggest(opId, limit = 5) {
         const needle = opId.toLowerCase();
         return this.catalog.operations
@@ -151,7 +126,6 @@ export class OperationCatalog {
         return hits.slice(0, params.limit ?? 15);
     }
 }
-/** Доля общих триграмм — грубая, но достаточная мера похожести имён операций. */
 const overlap = (a, b) => {
     const grams = (value) => {
         const out = new Set();
@@ -170,4 +144,3 @@ const overlap = (a, b) => {
     }
     return right.size === 0 ? 0 : shared / right.size;
 };
-//# sourceMappingURL=catalog.js.map

package/dist/api/client.d.ts

@@ -1,18 +1,15 @@
 import type { TokenStore } from './auth.js';
 import type { Operation } from './types.js';
-/** Аргументы вызова операции, как их присылает модель. */
 export interface CallArgs {
     path?: Record<string, string | number>;
     query?: Record<string, string | number | boolean>;
     body?: unknown;
 }
-/** Нормализованный неуспех вызова. */
 export interface NormalizedError {
     status: number;
     message: string;
     hint?: string;
 }
-/** Результат вызова: либо тело ответа, либо нормализованная ошибка. */
 export type CallResult = {
     ok: true;
     status: number;
@@ -21,29 +18,10 @@ export type CallResult = {
     ok: false;
     error: NormalizedError;
 };
-/** Ошибка на стороне вызывающего — до отправки запроса. */
 export declare class RequestBuildError extends Error {
 }
-/**
- * Возвращает тело в том виде, в каком его надо сериализовать в запрос.
- * Часть MCP-клиентов передаёт объектный аргумент уже сериализованным в строку;
- * без этой нормализации `JSON.stringify` завернул бы его второй раз, и на сервер
- * ушла бы JSON-строка вместо объекта — любая запись падала бы с невнятным 400.
- * Разворачивается только строка, которая целиком является объектом или массивом:
- * скалярная строка — законное тело, и трогать её нельзя.
- */
 export declare const normalizeBody: (body: unknown) => unknown;
-/**
- * Подставляет path-параметры и собирает query-строку.
- * Отсутствующий обязательный path-параметр — ошибка здесь, а не 404 от сервера:
- * иначе агент получает загадочный ответ вместо указания, чего не хватает.
- */
 export declare const buildUrl: (baseUrl: string, operation: Operation, args: CallArgs) => string;
-/**
- * HTTP-клиент Admin API.
- * Единственный ретрай — на 401 после обновления токена: любой другой повтор
- * на изменяющей операции рискует создать дубль, поэтому его здесь нет.
- */
 export declare class AdminApiClient {
     private readonly baseUrl;
     private readonly tokens;
@@ -54,7 +32,5 @@ export declare class AdminApiClient {
         timeoutMs: number;
     });
     call(operation: Operation, args: CallArgs): Promise<CallResult>;
-    /** Читает набор прав админа. Пустой массив означает «не удалось выяснить». */
     fetchPermissions(adminId: number): Promise<string[]>;
 }
-//# sourceMappingURL=client.d.ts.map

package/dist/api/client.js

@@ -1,14 +1,5 @@
-/** Ошибка на стороне вызывающего — до отправки запроса. */
 export class RequestBuildError extends Error {
 }
-/**
- * Возвращает тело в том виде, в каком его надо сериализовать в запрос.
- * Часть MCP-клиентов передаёт объектный аргумент уже сериализованным в строку;
- * без этой нормализации `JSON.stringify` завернул бы его второй раз, и на сервер
- * ушла бы JSON-строка вместо объекта — любая запись падала бы с невнятным 400.
- * Разворачивается только строка, которая целиком является объектом или массивом:
- * скалярная строка — законное тело, и трогать её нельзя.
- */
 export const normalizeBody = (body) => {
     if (typeof body !== 'string') {
         return body;
@@ -25,11 +16,6 @@ export const normalizeBody = (body) => {
         return body;
     }
 };
-/**
- * Подставляет path-параметры и собирает query-строку.
- * Отсутствующий обязательный path-параметр — ошибка здесь, а не 404 от сервера:
- * иначе агент получает загадочный ответ вместо указания, чего не хватает.
- */
 export const buildUrl = (baseUrl, operation, args) => {
     let path = operation.path;
     const provided = args.path ?? {};
@@ -47,7 +33,7 @@ export const buildUrl = (baseUrl, operation, args) => {
     const leftover = /\{([^}]+)\}/.exec(path);
     if (leftover) {
         throw new RequestBuildError(`Path parameter "${leftover[1] ?? ''}" of ${operation.path} was not provided and is not ` +
-            'declared in the catalog — the swagger snapshot may be stale.');
+            'declared in the catalog — the cached API document may be stale.');
     }
     const search = new URLSearchParams();
     for (const [key, value] of Object.entries(args.query ?? {})) {
@@ -58,23 +44,22 @@ export const buildUrl = (baseUrl, operation, args) => {
     const suffix = search.size > 0 ? `?${search.toString()}` : '';
     return `${baseUrl}${path}${suffix}`;
 };
-/** Подбирает подсказку по коду ответа и метаданным операции. */
 const hintFor = (status, operation) => {
     if (status === 400 || status === 422) {
         const loose = operation.body?.schema['x-loose'] === true;
         return (`Validation rejected the payload. ${loose ? 'This body has loosely typed fields — copy the shape from the example in cms_api_describe. ' : ''}` +
-            `Read ${operation.docLinks.slice(0, 2).join(', ')} with cms_docs_read before retrying.`);
+            'Search the knowledge base with cms_docs_search before retrying.');
     }
     if (status === 403) {
         return operation.permission
             ? `The admin lacks "${operation.permission}". Ask for the grant; retrying will not help.`
-            : 'Forbidden. Check the admin\'s permissions and the module visibility rules (back/docs/user-permissions).';
+            : 'Forbidden. Check the admin\'s permissions and the module visibility rules.';
     }
     if (status === 404) {
-        return 'Not found. The id may belong to another stand — prefer marker-based operations where they exist.';
+        return 'Not found. The id may belong to another instance — prefer marker-based operations where they exist.';
     }
     if (status >= 500) {
-        return 'Server-side failure. Check the dnk-back logs; do not retry blindly.';
+        return 'Server-side failure on the instance. Report it to your operator; do not retry blindly.';
     }
     return undefined;
 };
@@ -105,11 +90,6 @@ const extractMessage = (body, fallback) => {
     }
     return fallback;
 };
-/**
- * HTTP-клиент Admin API.
- * Единственный ретрай — на 401 после обновления токена: любой другой повтор
- * на изменяющей операции рискует создать дубль, поэтому его здесь нет.
- */
 export class AdminApiClient {
     baseUrl;
     tokens;
@@ -148,7 +128,7 @@ export class AdminApiClient {
                 error: {
                     status: 0,
                     message: `Request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
-                    hint: 'Is the stand reachable? In local mode dnk-back must be running with API_TYPE=/api/admin.',
+                    hint: 'Is the instance reachable at the configured base URL? It must expose the Admin API under /api/admin.',
                 },
             };
         }
@@ -166,7 +146,6 @@ export class AdminApiClient {
         }
         return { ok: true, status: response.status, body };
     }
-    /** Читает набор прав админа. Пустой массив означает «не удалось выяснить». */
     async fetchPermissions(adminId) {
         try {
             const token = await this.tokens.accessToken();
@@ -193,4 +172,3 @@ export class AdminApiClient {
         }
     }
 }
-//# sourceMappingURL=client.js.map

package/dist/api/normalize-schema.d.ts

@@ -1,14 +1,3 @@
 import type { JsonSchema } from './types.js';
-/**
- * Разворачивает `$ref` и нормализует типы за один проход.
- * Циклы (а они есть: сущности ссылаются друг на друга) обрываются заглушкой,
- * иначе разворачивание не завершится; глубина ограничена, чтобы схема осталась читаемой.
- */
 export declare const normalizeSchema: (node: unknown, components: Record<string, unknown>, depth?: number, refStack?: readonly string[]) => JsonSchema;
-/**
- * Урезает слишком большую схему до верхнего уровня свойств.
- * Схема тела запроса уходит прямо в контекст модели, и развёрнутый DTO
- * на 40 КБ вытеснит из него саму задачу.
- */
 export declare const capSchema: (schema: JsonSchema) => JsonSchema;
-//# sourceMappingURL=normalize-schema.d.ts.map

package/dist/api/normalize-schema.js

@@ -1,10 +1,4 @@
-/** Валидные типы JSON Schema. Всё остальное в этом swagger — TypeScript-выражения. */
 const VALID_TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
-/**
- * Приведение TypeScript-подобных типов из swagger к JSON Schema.
- * Проект генерирует схемы из декораторов NestJS, и `type` часто содержит
- * TS-выражение; таблица покрывает частые случаи, остальное помечается x-loose.
- */
 const TYPE_MAP = {
     date: { type: 'string', format: 'date-time' },
     Date: { type: 'string', format: 'date-time' },
@@ -30,11 +24,6 @@ const trimDescription = (value) => {
     return flat.length > MAX_DESCRIPTION ? `${flat.slice(0, MAX_DESCRIPTION)}…` : flat;
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-/**
- * Разворачивает `$ref` и нормализует типы за один проход.
- * Циклы (а они есть: сущности ссылаются друг на друга) обрываются заглушкой,
- * иначе разворачивание не завершится; глубина ограничена, чтобы схема осталась читаемой.
- */
 export const normalizeSchema = (node, components, depth = 0, refStack = []) => {
     if (!isRecord(node)) {
         return {};
@@ -51,7 +40,6 @@ export const normalizeSchema = (node, components, depth = 0, refStack = []) => {
         }
         return normalizeSchema(target, components, depth, [...refStack, name]);
     }
-    /** allOf/oneOf/anyOf в этом swagger встречаются только как обёртки — берём первый член. */
     for (const key of ['allOf', 'oneOf', 'anyOf']) {
         const variants = node[key];
         if (Array.isArray(variants) && variants.length > 0) {
@@ -123,11 +111,6 @@ export const normalizeSchema = (node, components, depth = 0, refStack = []) => {
     return out;
 };
 const MAX_SCHEMA_BYTES = 6_144;
-/**
- * Урезает слишком большую схему до верхнего уровня свойств.
- * Схема тела запроса уходит прямо в контекст модели, и развёрнутый DTO
- * на 40 КБ вытеснит из него саму задачу.
- */
 export const capSchema = (schema) => {
     if (Buffer.byteLength(JSON.stringify(schema), 'utf8') <= MAX_SCHEMA_BYTES) {
         return schema;
@@ -148,4 +131,3 @@ export const capSchema = (schema) => {
     }
     return { ...schema, properties: shallow, 'x-truncated': true };
 };
-//# sourceMappingURL=normalize-schema.js.map

package/dist/api/policy.d.ts

@@ -1,7 +1,6 @@
 import type { AllowLevel } from '../config/config.js';
 import type { AdminIdentity } from './auth.js';
 import type { Operation } from './types.js';
-/** Результат проверки политики перед выполнением операции. */
 export type PolicyDecision = {
     kind: 'allow';
 } | {
@@ -11,42 +10,20 @@ export type PolicyDecision = {
     kind: 'needsConfirm';
     reason: string;
 };
-/**
- * Одноразовые токены подтверждения для необратимых операций.
- * Токен привязан к хэшу (opId + аргументы), поэтому подтверждение одного удаления
- * нельзя переиспользовать для другого — иначе двухшаговость была бы декоративной.
- */
 export declare class ConfirmStore {
     private readonly issued;
     private static hash;
     issue(opId: string, args: unknown, now?: number): string;
-    /**
-     * Проверяет токен, не гася его.
-     * Нужна, чтобы отказ по другой причине (нет права, не тот уровень allow)
-     * не сжигал подтверждение, которое человек уже дал.
-     */
     verify(token: string, opId: string, args: unknown, now?: number): boolean;
-    /** Проверяет и немедленно гасит токен. Повторное использование невозможно. */
     consume(token: string, opId: string, args: unknown, now?: number): boolean;
     private sweep;
 }
-/**
- * Проверяет только уровень `--allow`.
- * Вынесено отдельно, чтобы вызывающий мог отказать до аутентификации:
- * обещание «no request was sent» не должно нарушаться самим логином.
- */
 export declare const checkLevel: (operation: Operation, allow: AllowLevel) => Extract<PolicyDecision, {
     kind: "deny";
 }> | undefined;
-/**
- * Решает, можно ли выполнить операцию.
- * Порядок проверок значим: уровень доступа — до прав, права — до подтверждения,
- * чтобы read-only сервер вообще не выдавал токенов подтверждения.
- */
 export declare const decide: (params: {
     operation: Operation;
     allow: AllowLevel;
     identity?: AdminIdentity;
     confirmValid: boolean;
 }) => PolicyDecision;
-//# sourceMappingURL=policy.d.ts.map

package/dist/api/shape.d.ts

@@ -1,19 +1,6 @@
-/** Результат подготовки ответа к отдаче модели. */
 export interface ShapedResponse {
     body: unknown;
     truncated: boolean;
 }
-/**
- * Приводит ответ Admin API к размеру, пригодному для контекста модели.
- * Массивы урезаются по элементам (а не обрывом JSON), поэтому результат
- * остаётся валидным и самоописанным: агент видит `_truncated` и сужает запрос.
- */
 export declare const shapeResponse: (raw: unknown, maxBytes: number) => ShapedResponse;
-/**
- * Сжимает текущее состояние цели до размера, который не топит ответ dry-run.
- * Целиком отдаётся только небольшая цель: для создания в коллекции «цель» — это весь
- * список существующих объектов, а он бывает в сотни килобайт и вытесняет собой
- * единственно нужные части плана — политику и собранный запрос.
- */
 export declare const summarizeTarget: (target: unknown) => unknown;
-//# sourceMappingURL=shape.d.ts.map

package/dist/api/shape.js

@@ -1,12 +1,9 @@
-/** Поля, значения которых бесполезны модели и раздувают ответ. */
 const BLOB_KEYS = new Set(['base64', 'buffer', 'content', 'fileContent', 'data64', 'blob']);
 const BLOB_VALUE_LIMIT = 512;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-/** Похоже ли строковое значение на base64-блоб, который незачем показывать. */
 const looksLikeBlob = (key, value) => typeof value === 'string' &&
     value.length > BLOB_VALUE_LIMIT &&
     (BLOB_KEYS.has(key) || /^data:|^[A-Za-z0-9+/=]{512,}$/.test(value));
-/** Рекурсивно заменяет блобы заглушкой с указанием исходного размера. */
 const stripBlobs = (value, key = '') => {
     if (looksLikeBlob(key, value)) {
         return `[stripped ${String(value.length)} chars]`;
@@ -23,18 +20,12 @@ const stripBlobs = (value, key = '') => {
     }
     return value;
 };
-/**
- * Приводит ответ Admin API к размеру, пригодному для контекста модели.
- * Массивы урезаются по элементам (а не обрывом JSON), поэтому результат
- * остаётся валидным и самоописанным: агент видит `_truncated` и сужает запрос.
- */
 export const shapeResponse = (raw, maxBytes) => {
     const cleaned = stripBlobs(raw);
     const size = (value) => Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
     if (size(cleaned) <= maxBytes) {
         return { body: cleaned, truncated: false };
     }
-    /** Массив верхнего уровня: оставляем префикс элементов. */
     if (Array.isArray(cleaned)) {
         const kept = takePrefix(cleaned, maxBytes);
         return {
@@ -49,7 +40,6 @@ export const shapeResponse = (raw, maxBytes) => {
             truncated: true,
         };
     }
-    /** Пагинированный объект: урезаем самый большой массив внутри него. */
     if (isRecord(cleaned)) {
         const arrayKey = Object.entries(cleaned)
             .filter(([, value]) => Array.isArray(value))
@@ -83,11 +73,8 @@ export const shapeResponse = (raw, maxBytes) => {
         truncated: true,
     };
 };
-/** Бюджет на показ текущего состояния цели в плане dry-run и в запросе подтверждения. */
 const TARGET_LIMIT = 4_000;
-/** Сколько идентификаторов списка показывать в сводке. */
 const TARGET_ID_SAMPLE = 20;
-/** Собирает опознавательные значения элементов списка: id, если он есть, иначе сам элемент. */
 const identify = (items) => items.slice(0, TARGET_ID_SAMPLE).map((item) => {
     if (!isRecord(item)) {
         return item;
@@ -95,12 +82,6 @@ const identify = (items) => items.slice(0, TARGET_ID_SAMPLE).map((item) => {
     const id = item['id'] ?? item['identifier'] ?? item['marker'];
     return id ?? Object.keys(item).slice(0, 3);
 });
-/**
- * Сжимает текущее состояние цели до размера, который не топит ответ dry-run.
- * Целиком отдаётся только небольшая цель: для создания в коллекции «цель» — это весь
- * список существующих объектов, а он бывает в сотни килобайт и вытесняет собой
- * единственно нужные части плана — политику и собранный запрос.
- */
 export const summarizeTarget = (target) => {
     if (target === undefined || target === null) {
         return null;
@@ -134,7 +115,6 @@ export const summarizeTarget = (target) => {
     }
     return { _summary: { kind: 'value', preview: String(target).slice(0, 200), hint } };
 };
-/** Берёт максимальный префикс массива, укладывающийся в бюджет байтов. */
 const takePrefix = (items, maxBytes) => {
     const kept = [];
     let used = 2;
@@ -148,4 +128,3 @@ const takePrefix = (items, maxBytes) => {
     }
     return kept;
 };
-//# sourceMappingURL=shape.js.map

package/dist/api/swagger-source.d.ts

@@ -1,22 +1,11 @@
-/** Откуда и как забирать swagger. */
 export interface SwaggerSource {
-    /** Базовый URL Admin API, уже нормализованный (с `/api/admin`, без слэша на конце). */
     baseUrl: string;
     cacheDir: string;
     timeoutMs: number;
-    /** Bearer-токен: нужен, если стенд закрывает этот эндпоинт авторизацией. */
     bearer?: string;
 }
-/** Полученный документ и то, откуда он взялся. */
 export interface FetchedSwagger {
     raw: string;
-    origin: 'stand' | 'cache';
+    origin: 'instance' | 'cache';
 }
-/**
- * Забирает swagger со стенда, с откатом на кэш.
- * Эндпоинт публичный на большинстве стендов, поэтому первый запрос идёт без
- * авторизации: в remote-режиме на момент старта процесса учётных данных может
- * не быть вовсе. Токен добавляется только если стенд ответил 401/403.
- */
 export declare const fetchSwagger: (source: SwaggerSource) => Promise<FetchedSwagger>;
-//# sourceMappingURL=swagger-source.d.ts.map

package/dist/api/swagger-source.js

@@ -1,14 +1,8 @@
 import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-/** Путь, по которому стенд отдаёт swagger админского API. */
 const SWAGGER_PATH = '/workflows/nodes/admin-api/swagger.json';
-/** Язык описаний. Английский — тот же, на котором написаны summary в каталоге. */
 const LANG_CODE = 'en_US';
-/**
- * Имя файла кэша. Ключом служит baseUrl: каталог операций одного стенда
- * нельзя показывать за каталог другого, даже если оба «тот же самый» CMS.
- */
 const cacheFile = (source) => join(source.cacheDir, 'swagger', `${createHash('sha256').update(source.baseUrl).digest('hex').slice(0, 16)}.json`);
 const readCache = (source) => {
     try {
@@ -23,12 +17,6 @@ const writeCache = (source, raw) => {
     mkdirSync(join(source.cacheDir, 'swagger'), { recursive: true });
     writeFileSync(file, raw);
 };
-/**
- * Забирает swagger со стенда, с откатом на кэш.
- * Эндпоинт публичный на большинстве стендов, поэтому первый запрос идёт без
- * авторизации: в remote-режиме на момент старта процесса учётных данных может
- * не быть вовсе. Токен добавляется только если стенд ответил 401/403.
- */
 export const fetchSwagger = async (source) => {
     const url = `${source.baseUrl}${SWAGGER_PATH}?langCode=${LANG_CODE}`;
     const request = async (bearer) => fetch(url, {
@@ -46,15 +34,10 @@ export const fetchSwagger = async (source) => {
         if (!response.ok) {
             throw new Error(`${source.baseUrl} answered ${String(response.status)} for ${SWAGGER_PATH}` +
                 (response.status === 401 || response.status === 403
-                    ? ' — the stand requires credentials to read its swagger'
+                    ? ' — the instance requires credentials to read its API document'
                     : ''));
         }
         const raw = await response.text();
-        /**
-         * Проверяем, что это вообще OpenAPI, до записи в кэш. Стенд за прокси легко
-         * отвечает страницей входа или конвертом ошибки с кодом 200; закэшировать
-         * такое — значит подсунуть агенту пустой каталог до следующей чистки кэша.
-         */
         const parsed = JSON.parse(raw);
         if (typeof parsed !== 'object' ||
             parsed === null ||
@@ -63,7 +46,7 @@ export const fetchSwagger = async (source) => {
             throw new Error(`${source.baseUrl}${SWAGGER_PATH} did not answer with an OpenAPI document`);
         }
         writeCache(source, raw);
-        return { raw, origin: 'stand' };
+        return { raw, origin: 'instance' };
     }
     catch (error) {
         const cached = readCache(source);
@@ -73,4 +56,3 @@ export const fetchSwagger = async (source) => {
         throw error instanceof Error ? error : new Error(String(error));
     }
 };
-//# sourceMappingURL=swagger-source.js.map