@oneentry/mcp-platform-server 0.1.1 → 0.1.3

package/dist/api/types.d.ts

@@ -1,25 +1,13 @@
-/** HTTP-методы, встречающиеся в Admin API. */
 export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
-/**
- * Класс риска операции. Определяется на сборке каталога, а не в рантайме,
- * чтобы политику доступа нельзя было обойти хитрым аргументом.
- */
 export type RiskLevel = 'read' | 'write' | 'destructive';
-/** Параметр операции (path / query / header). */
 export interface OperationParam {
     name: string;
     location: 'path' | 'query' | 'header';
     required: boolean;
     description?: string;
-    /** Нормализованная JSON-схема параметра. */
     schema: JsonSchema;
     example?: unknown;
 }
-/**
- * Нормализованная JSON-схема. Swagger проекта содержит 311 TypeScript-подобных
- * значений `type` (`Record<string, any>`, `CommonLocalizeInfos`, `image`…),
- * поэтому «схема» здесь — результат приведения, а не исходник.
- */
 export interface JsonSchema {
     type?: string;
     format?: string;
@@ -29,28 +17,19 @@ export interface JsonSchema {
     items?: JsonSchema;
     properties?: Record<string, JsonSchema>;
     required?: string[];
-    /** Тип не удалось привести к JSON Schema: доверять следует `example`. */
     'x-loose'?: boolean;
-    /** Исходный TypeScript-подобный тип из swagger — сохранён как подсказка. */
     'x-source-type'?: string;
-    /** Схема была урезана по размеру. */
     'x-truncated'?: boolean;
 }
-/** Одна операция Admin API в каталоге. */
 export interface Operation {
-    /** `operationId` из swagger, например `AdminPagesController_findAllRoot`. */
     opId: string;
     method: HttpMethod;
-    /** Путь без префикса API, например `/pages/{id}`. */
     path: string;
-    /** Полный путь как в swagger, например `/api/admin/pages/{id}`. */
     fullPath: string;
     tag: string;
     summary: string;
-    /** Требуемое право из `AdminPermissionsEnum`, если объявлено в контроллере. */
     permission?: string;
     risk: RiskLevel;
-    /** Операция навсегда остаётся за подтверждением, независимо от уровня allow. */
     alwaysConfirm: boolean;
     params: OperationParam[];
     body?: {
@@ -59,27 +38,14 @@ export interface Operation {
         required: boolean;
     };
     responseSummary?: string;
-    /** Идентификаторы разделов документации (`<docId>#<anchor>`), объясняющих операцию. */
-    docLinks: string[];
-    /** Склеенный текст для поиска по каталогу. */
     searchText: string;
 }
-/** Собранный каталог: результат `buildCatalog` — swagger стенда плюс карта прав. */
 export interface Catalog {
     version: 1;
     builtAt: string;
-    /** Префикс путей из swagger (`/api/admin`) — проверяется при сборке. */
     apiPrefix: string;
-    /** Хэш исходного swagger.json — виден в cms_whoami, ловит рассинхрон. */
     swaggerHash: string;
-    /** Полный список значений `AdminPermissionsEnum`. */
     permissions: string[];
-    /**
-     * Замечания сборки — прежде всего признаки устаревшего swagger.json.
-     * Показываются в `cms_whoami`: рассинхрон каталога и реального API должен быть
-     * виден агенту, а не выясняться по 404.
-     */
     warnings: string[];
     operations: Operation[];
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/api/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/bin/cli.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.js

@@ -24,7 +24,7 @@ Knowledge (documentation is fetched from GitHub, not bundled)
   --knowledge-ref <ref>   branch, tag or commit, default main
   --knowledge-path <dir>  read a local clone instead of GitHub (fast edit loop)
   --knowledge-ttl <ms>    how long a cached commit stays fresh, default 3600000
-  --cache-dir <path>      where the knowledge tree and the stand's swagger are cached
+  --cache-dir <path>      where the knowledge tree and the API document are cached
   --offline               never touch the network: cache and bundled rules only
 
 Environment
@@ -47,10 +47,6 @@ const main = async () => {
     await runStdio(config);
 };
 main().catch((error) => {
-    /**
-     * В stdio-режиме stdout занят протоколом, поэтому любая диагностика идёт в stderr.
-     */
     process.stderr.write(`oneentry-mcp-platform: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
 });
-//# sourceMappingURL=cli.js.map

package/dist/config/config.d.ts

@@ -1,33 +1,14 @@
 import { z } from 'zod';
-/**
- * Уровень разрешённых операций.
- * Читаем по умолчанию: агент не может ничего испортить, пока человек явно не разрешил.
- */
 export declare const AllowLevelSchema: z.ZodEnum<["read", "write", "destructive"]>;
 export type AllowLevel = z.infer<typeof AllowLevelSchema>;
-/**
- * Режим работы сервера. Определяется транспортом, а не отдельным флагом:
- * stdio -> local (агент и CMS на одной машине), streamable HTTP -> remote (сервис).
- */
 export declare const ServerModeSchema: z.ZodEnum<["local", "remote"]>;
 export type ServerMode = z.infer<typeof ServerModeSchema>;
-/**
- * Откуда брать документацию. Знания живут в отдельном публичном репозитории GitHub
- * и скачиваются в рантайме, а не вшиваются в пакет: иначе правка одной строки
- * документации требовала бы перевыпуска npm-пакета.
- */
 export declare const KnowledgeConfigSchema: z.ZodObject<{
-    /** `owner/name` репозитория знаний. */
     repo: z.ZodString;
-    /** Ветка, тег или коммит. Пин на тег — способ зафиксировать знания для стенда. */
     ref: z.ZodString;
-    /** Локальный клон репозитория знаний: читать его вместо сети. */
     path: z.ZodOptional<z.ZodString>;
-    /** Сколько считать закэшированный коммит свежим, не спрашивая GitHub. */
     refreshTtlMs: z.ZodNumber;
-    /** Не ходить в сеть: только кэш и вшитые правила. */
     offline: z.ZodBoolean;
-    /** Токен GitHub — только чтобы поднять лимит API. Репозиторий публичный. */
     token: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     repo: string;
@@ -45,33 +26,19 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     token?: string | undefined;
 }>;
 export type KnowledgeSettings = z.infer<typeof KnowledgeConfigSchema>;
-/**
- * Полная конфигурация сервера после слияния источников.
- * Все дальнейшие слои получают её как зависимость и не читают process.env сами —
- * это то, что позволяет держать один и тот же код для local и remote.
- */
 export declare const ConfigSchema: z.ZodObject<{
     mode: z.ZodEnum<["local", "remote"]>;
-    /** Базовый URL Admin API, всегда с префиксом /api/admin и без завершающего слэша. */
     baseUrl: z.ZodString;
     allow: z.ZodEnum<["read", "write", "destructive"]>;
-    /** Логин/пароль админа. В remote-режиме могут отсутствовать — тогда их даёт сессия. */
     login: z.ZodOptional<z.ZodString>;
     password: z.ZodOptional<z.ZodString>;
-    /** Готовый access-токен вместо логина/пароля. */
     token: z.ZodOptional<z.ZodString>;
     knowledge: z.ZodObject<{
-        /** `owner/name` репозитория знаний. */
         repo: z.ZodString;
-        /** Ветка, тег или коммит. Пин на тег — способ зафиксировать знания для стенда. */
         ref: z.ZodString;
-        /** Локальный клон репозитория знаний: читать его вместо сети. */
         path: z.ZodOptional<z.ZodString>;
-        /** Сколько считать закэшированный коммит свежим, не спрашивая GitHub. */
         refreshTtlMs: z.ZodNumber;
-        /** Не ходить в сеть: только кэш и вшитые правила. */
         offline: z.ZodBoolean;
-        /** Токен GitHub — только чтобы поднять лимит API. Репозиторий публичный. */
         token: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         repo: string;
@@ -88,18 +55,13 @@ export declare const ConfigSchema: z.ZodObject<{
         path?: string | undefined;
         token?: string | undefined;
     }>;
-    /** Каталог кэша: распакованный репозиторий знаний и снимок swagger стенда. */
     cacheDir: z.ZodString;
-    /** Файл JSONL-аудита. В remote-режиме обязателен. */
     auditPath: z.ZodOptional<z.ZodString>;
-    /** Таймаут одного запроса к Admin API, мс. */
     requestTimeoutMs: z.ZodNumber;
-    /** Максимальный размер сериализованного ответа, отдаваемого модели, в байтах. */
     maxResponseBytes: z.ZodNumber;
     http: z.ZodObject<{
         port: z.ZodNumber;
         host: z.ZodString;
-        /** Разрешённые Origin для remote-режима. Пустой список = принимать только запросы без Origin. */
         allowedOrigins: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
         port: number;
@@ -160,23 +122,7 @@ export declare const ConfigSchema: z.ZodObject<{
     auditPath?: string | undefined;
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
-/** Разобранные аргументы командной строки. */
 export type CliFlags = Record<string, string | boolean>;
-/**
- * Минимальный разбор argv: поддерживаются `--flag`, `--key=value` и `--key value`.
- * Своя реализация вместо зависимости — набор флагов маленький и стабильный.
- */
 export declare const parseFlags: (argv: readonly string[]) => CliFlags;
-/**
- * Нормализует базовый URL: убирает завершающий слэш и требует префикс Admin API.
- * Сервер работает только с админским API — это гарантия, а не соглашение,
- * поэтому проверка живёт здесь, а не в клиенте.
- */
 export declare const normalizeBaseUrl: (raw: string) => string;
-/**
- * Собирает конфигурацию по приоритету: флаги > переменные окружения > ./oneentry-mcp-platform.json > дефолты.
- * Валидация одна и та же для обоих режимов; отличается только то, что в remote-режиме
- * обязателен путь аудита, а документация всегда берётся из снапшота.
- */
 export declare const loadConfig: (argv: readonly string[], env?: NodeJS.ProcessEnv, cwd?: string) => Config;
-//# sourceMappingURL=config.d.ts.map

package/dist/config/config.js

@@ -2,63 +2,31 @@ import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { z } from 'zod';
-/**
- * Уровень разрешённых операций.
- * Читаем по умолчанию: агент не может ничего испортить, пока человек явно не разрешил.
- */
 export const AllowLevelSchema = z.enum(['read', 'write', 'destructive']);
-/**
- * Режим работы сервера. Определяется транспортом, а не отдельным флагом:
- * stdio -> local (агент и CMS на одной машине), streamable HTTP -> remote (сервис).
- */
 export const ServerModeSchema = z.enum(['local', 'remote']);
-/**
- * Откуда брать документацию. Знания живут в отдельном публичном репозитории GitHub
- * и скачиваются в рантайме, а не вшиваются в пакет: иначе правка одной строки
- * документации требовала бы перевыпуска npm-пакета.
- */
 export const KnowledgeConfigSchema = z.object({
-    /** `owner/name` репозитория знаний. */
     repo: z.string().regex(/^[\w.-]+\/[\w.-]+$/, 'knowledge repo must look like "owner/name"'),
-    /** Ветка, тег или коммит. Пин на тег — способ зафиксировать знания для стенда. */
     ref: z.string().min(1),
-    /** Локальный клон репозитория знаний: читать его вместо сети. */
     path: z.string().optional(),
-    /** Сколько считать закэшированный коммит свежим, не спрашивая GitHub. */
     refreshTtlMs: z.number().int().nonnegative(),
-    /** Не ходить в сеть: только кэш и вшитые правила. */
     offline: z.boolean(),
-    /** Токен GitHub — только чтобы поднять лимит API. Репозиторий публичный. */
     token: z.string().min(1).optional(),
 });
-/**
- * Полная конфигурация сервера после слияния источников.
- * Все дальнейшие слои получают её как зависимость и не читают process.env сами —
- * это то, что позволяет держать один и тот же код для local и remote.
- */
 export const ConfigSchema = z.object({
     mode: ServerModeSchema,
-    /** Базовый URL Admin API, всегда с префиксом /api/admin и без завершающего слэша. */
     baseUrl: z.string().url(),
     allow: AllowLevelSchema,
-    /** Логин/пароль админа. В remote-режиме могут отсутствовать — тогда их даёт сессия. */
     login: z.string().min(1).optional(),
     password: z.string().min(1).optional(),
-    /** Готовый access-токен вместо логина/пароля. */
     token: z.string().min(1).optional(),
     knowledge: KnowledgeConfigSchema,
-    /** Каталог кэша: распакованный репозиторий знаний и снимок swagger стенда. */
     cacheDir: z.string().min(1),
-    /** Файл JSONL-аудита. В remote-режиме обязателен. */
     auditPath: z.string().optional(),
-    /** Таймаут одного запроса к Admin API, мс. */
     requestTimeoutMs: z.number().int().positive(),
-    /** Максимальный размер сериализованного ответа, отдаваемого модели, в байтах. */
     maxResponseBytes: z.number().int().positive(),
     http: z.object({
         port: z.number().int().min(1).max(65535),
         host: z.string().min(1),
-        /** Разрешённые Origin для remote-режима. Пустой список = принимать только запросы без Origin. */
         allowedOrigins: z.array(z.string()),
     }),
 });
@@ -71,13 +39,8 @@ const DEFAULTS = {
     httpHost: '127.0.0.1',
     knowledgeRepo: 'ONEENTRY-PLATFORM/oneentry-platform-rules',
     knowledgeRef: 'main',
-    /** Час: достаточно редко, чтобы цикл перезапусков не упирался в лимит API GitHub. */
     knowledgeTtlMs: 3_600_000,
 };
-/**
- * Минимальный разбор argv: поддерживаются `--flag`, `--key=value` и `--key value`.
- * Своя реализация вместо зависимости — набор флагов маленький и стабильный.
- */
 export const parseFlags = (argv) => {
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
@@ -103,10 +66,6 @@ export const parseFlags = (argv) => {
     return flags;
 };
 const asString = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
-/**
- * Булев флаг из трёх источников. Голый `--offline` — это `true`, поэтому
- * значение флага может быть и строкой, и признаком присутствия.
- */
 const asBoolean = (value, fallback) => {
     if (value === undefined) {
         return fallback;
@@ -116,10 +75,6 @@ const asBoolean = (value, fallback) => {
     }
     return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
 };
-/**
- * Каталог кэша по умолчанию: XDG, с откатом на `~/.cache`.
- * Кэш обязан пережить перезапуск процесса, поэтому временный каталог не годится.
- */
 const defaultCacheDir = (env) => {
     const xdg = asString(env['XDG_CACHE_HOME']);
     return resolve(xdg ?? resolve(homedir(), '.cache'), 'oneentry-mcp-platform');
@@ -134,11 +89,6 @@ const asNumber = (value, fallback) => {
     }
     return parsed;
 };
-/**
- * Нормализует базовый URL: убирает завершающий слэш и требует префикс Admin API.
- * Сервер работает только с админским API — это гарантия, а не соглашение,
- * поэтому проверка живёт здесь, а не в клиенте.
- */
 export const normalizeBaseUrl = (raw) => {
     const trimmed = raw.replace(/\/+$/, '');
     if (!trimmed.includes('/api/admin')) {
@@ -163,11 +113,6 @@ const readConfigFile = (cwd) => {
         throw error;
     }
 };
-/**
- * Собирает конфигурацию по приоритету: флаги > переменные окружения > ./oneentry-mcp-platform.json > дефолты.
- * Валидация одна и та же для обоих режимов; отличается только то, что в remote-режиме
- * обязателен путь аудита, а документация всегда берётся из снапшота.
- */
 export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
     const flags = parseFlags(argv);
     const file = readConfigFile(cwd);
@@ -202,7 +147,6 @@ export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
             path: pickKnowledge('knowledge-path', 'ONEENTRY_MCP_KNOWLEDGE_PATH', 'path'),
             refreshTtlMs: asNumber(pickKnowledge('knowledge-ttl', 'ONEENTRY_MCP_KNOWLEDGE_TTL_MS', 'refreshTtlMs'), DEFAULTS.knowledgeTtlMs),
             offline: asBoolean(flags['offline'] ?? env['ONEENTRY_MCP_OFFLINE'], false),
-            /** Только из окружения: секрет не должен попадать ни в argv, ни в файл конфигурации. */
             token: asString(env['ONEENTRY_GITHUB_TOKEN']),
         },
         cacheDir: pick('cache-dir', 'ONEENTRY_MCP_CACHE_DIR', 'cacheDir') ?? defaultCacheDir(env),
@@ -216,9 +160,6 @@ export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
         },
     };
     const config = ConfigSchema.parse(candidate);
-    /**
-     * Пароль через флаг не принимаем ни в каком режиме: argv видно в списке процессов.
-     */
     if (asString(flags['password'])) {
         throw new Error('Refusing --password: pass ONEENTRY_CMS_PASSWORD via the environment instead.');
     }
@@ -227,4 +168,3 @@ export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
     }
     return config;
 };
-//# sourceMappingURL=config.js.map

package/dist/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * Публичный API пакета: всё, что нужно, чтобы встроить сервер в свой процесс
- * или собрать его иначе, чем это делает CLI.
- */
 export { loadConfig, parseFlags, normalizeBaseUrl, ConfigSchema } from './config/config.js';
 export type { Config, AllowLevel, ServerMode } from './config/config.js';
 export { createServer, createSharedDeps } from './server.js';
@@ -27,4 +23,3 @@ export { runStdio } from './transports/stdio.js';
 export { runHttp } from './transports/http.js';
 export type { Catalog, Operation, JsonSchema, RiskLevel } from './api/types.js';
 export type { KnowledgeChunk, KnowledgeDoc, KnowledgeOrigin, KnowledgePack, } from './knowledge/types.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,3 @@
-/**
- * Публичный API пакета: всё, что нужно, чтобы встроить сервер в свой процесс
- * или собрать его иначе, чем это делает CLI.
- */
 export { loadConfig, parseFlags, normalizeBaseUrl, ConfigSchema } from './config/config.js';
 export { createServer, createSharedDeps } from './server.js';
 export { Session } from './session.js';
@@ -19,4 +15,3 @@ export { buildCatalog } from './api/build-catalog.js';
 export { fetchSwagger } from './api/swagger-source.js';
 export { runStdio } from './transports/stdio.js';
 export { runHttp } from './transports/http.js';
-//# sourceMappingURL=index.js.map

package/dist/knowledge/chunk.d.ts

@@ -1,27 +1,13 @@
 import type { KnowledgeChunk, KnowledgeDoc } from './types.js';
-/**
- * Слаг заголовка в стиле GitHub: нижний регистр, пробелы в дефисы,
- * пунктуация выброшена. Кириллица сохраняется — документация в проекте русскоязычная.
- */
 export declare const slugify: (heading: string) => string;
 interface Section {
     title: string;
     lines: string[];
 }
-/**
- * Режет markdown по заголовкам `##` и `###`.
- * Преамбула до первого `##` становится разделом с пустым anchor — в ней обычно
- * лежит самое важное описание модуля, терять его нельзя.
- */
 export declare const splitSections: (markdown: string) => {
     docTitle: string;
     sections: Section[];
 };
-/**
- * Превращает один markdown-файл в документ + его разделы.
- * Anchor'ы дедуплицируются суффиксом, иначе два одинаковых `## Схема`
- * в одном файле стали бы неразличимы для cms_docs_read.
- */
 export declare const chunkDocument: (params: {
     docId: string;
     repo: KnowledgeChunk["repo"];
@@ -32,4 +18,3 @@ export declare const chunkDocument: (params: {
     chunks: KnowledgeChunk[];
 };
 export {};
-//# sourceMappingURL=chunk.d.ts.map

package/dist/knowledge/chunk.js

@@ -1,20 +1,10 @@
-/**
- * Слаг заголовка в стиле GitHub: нижний регистр, пробелы в дефисы,
- * пунктуация выброшена. Кириллица сохраняется — документация в проекте русскоязычная.
- */
 export const slugify = (heading) => heading
     .toLowerCase()
     .replace(/`|\*|_|\[|\]|\(|\)|:|,|\.|\/|\\|«|»|"|'|\?|!|;/g, '')
     .trim()
     .replace(/\s+/g, '-')
     .slice(0, 80);
-/** Строки внутри огороженных блоков кода не считаются заголовками. */
 const isFence = (line) => line.startsWith('```') || line.startsWith('~~~');
-/**
- * Режет markdown по заголовкам `##` и `###`.
- * Преамбула до первого `##` становится разделом с пустым anchor — в ней обычно
- * лежит самое важное описание модуля, терять его нельзя.
- */
 export const splitSections = (markdown) => {
     const lines = markdown.split('\n');
     let docTitle = '';
@@ -43,11 +33,6 @@ export const splitSections = (markdown) => {
         sections: sections.filter((s) => s.title !== '' || s.lines.join('').trim() !== ''),
     };
 };
-/**
- * Превращает один markdown-файл в документ + его разделы.
- * Anchor'ы дедуплицируются суффиксом, иначе два одинаковых `## Схема`
- * в одном файле стали бы неразличимы для cms_docs_read.
- */
 export const chunkDocument = (params) => {
     const { docTitle, sections } = splitSections(params.markdown);
     const seen = new Map();
@@ -84,4 +69,3 @@ export const chunkDocument = (params) => {
         chunks,
     };
 };
-//# sourceMappingURL=chunk.js.map

package/dist/knowledge/github.d.ts

@@ -1,46 +1,21 @@
-/** Откуда и как забирать репозиторий знаний. */
 export interface KnowledgeSource {
-    /** `owner/name` публичного репозитория GitHub. */
     repo: string;
-    /** Ветка, тег или sha. */
     ref: string;
     cacheDir: string;
-    /** Как долго считать закэшированный sha свежим, не спрашивая GitHub. */
     refreshTtlMs: number;
-    /** Не ходить в сеть вовсе: только кэш. */
     offline: boolean;
-    /** Токен GitHub — только чтобы поднять лимит API; репозиторий публичный. */
     token?: string;
     timeoutMs: number;
 }
-/** Файл документации, вынутый из репозитория. */
 export interface KnowledgeFile {
-    /** Путь относительно каталога `knowledge/`, например `back/docs/menus-module.md`. */
     path: string;
     content: string;
 }
-/** Результат получения дерева знаний. */
 export interface KnowledgeTree {
     files: KnowledgeFile[];
     sha: string;
-    /** `github` — только что скачано, `cache` — взято с диска. */
     source: 'github' | 'cache';
 }
-/** Рекурсивно собирает `*.md` каталога. Используется и кэшем, и локальным клоном. */
 export declare const walkMarkdown: (root: string) => string[];
-/**
- * Отдаёт дерево знаний, предпочитая кэш.
- * Порядок такой: свежий кэш -> сверка sha -> скачивание. Пока запись кэша моложе
- * `refreshTtlMs`, сеть не трогается вообще — иначе цикл перезапусков сервера
- * упирался бы в лимит анонимного API GitHub.
- * Бросает исключение, если знания взять неоткуда; решение о запасном варианте
- * принимает вызывающий.
- */
 export declare const fetchKnowledgeTree: (source: KnowledgeSource) => Promise<KnowledgeTree>;
-/**
- * Читает знания из локального клона репозитория.
- * Принимает и корень клона, и сам каталог `knowledge/` — путать их слишком легко,
- * а разница видна по наличию подкаталога.
- */
 export declare const readLocalTree: (path: string) => KnowledgeFile[];
-//# sourceMappingURL=github.d.ts.map

package/dist/knowledge/github.js

@@ -1,10 +1,8 @@
 import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { readTarGz } from './tar.js';
-/** Каталог внутри репозитория, в котором лежит документация. */
 const ROOT = 'knowledge';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-/** Каталог кэша одного репозитория. Слэш в имени заменён, чтобы это был один уровень. */
 const repoCacheDir = (source) => resolve(source.cacheDir, source.repo.replace('/', '--'));
 const stateFile = (source) => join(repoCacheDir(source), 'current.json');
 const readState = (source) => {
@@ -26,7 +24,6 @@ const writeState = (source, state) => {
     mkdirSync(repoCacheDir(source), { recursive: true });
     writeFileSync(stateFile(source), `${JSON.stringify(state)}\n`);
 };
-/** Рекурсивно собирает `*.md` каталога. Используется и кэшем, и локальным клоном. */
 export const walkMarkdown = (root) => {
     const out = [];
     const visit = (dir) => {
@@ -52,7 +49,6 @@ const exists = (path) => {
         return false;
     }
 };
-/** Читает распакованное дерево из кэша. */
 const readCached = (source, sha) => {
     const dir = join(repoCacheDir(source), sha, ROOT);
     if (!exists(dir)) {
@@ -63,11 +59,6 @@ const readCached = (source, sha) => {
         content: readFileSync(file, 'utf8'),
     }));
 };
-/**
- * Записывает дерево в кэш и удаляет каталоги остальных sha.
- * Кэш адресуется коммитом, поэтому старые версии не нужны никогда:
- * запись неизменяема, и «протухнуть» она не может.
- */
 const writeCache = (source, sha, files) => {
     const base = repoCacheDir(source);
     const target = join(base, sha, ROOT);
@@ -87,11 +78,6 @@ const headers = (source, accept) => ({
     'user-agent': 'oneentry-mcp-platform',
     ...(source.token ? { authorization: `Bearer ${source.token}` } : {}),
 });
-/**
- * Расшифровывает код ответа GitHub в причину, по которой ref не превратился в коммит.
- * Голый статус здесь бесполезен: 404 и 409 — это разные ошибки настройки, и обе
- * встречаются при первом подключении к новому репозиторию знаний.
- */
 const shaFailureHint = (status) => {
     switch (status) {
         case 403: {
@@ -108,10 +94,6 @@ const shaFailureHint = (status) => {
         }
     }
 };
-/**
- * Превращает ref в конкретный коммит. Ответ — голый sha, поэтому запрос дешёвый:
- * его можно делать при каждом запуске, не скачивая архив.
- */
 const resolveSha = async (source) => {
     const url = `https://api.github.com/repos/${source.repo}/commits/${encodeURIComponent(source.ref)}`;
     const response = await fetch(url, {
@@ -128,11 +110,6 @@ const resolveSha = async (source) => {
     }
     return sha;
 };
-/**
- * Отбирает из архива только документацию.
- * Всё, что вне `knowledge/`, и любой путь с `..` отбрасываются: архив приходит
- * из сети, и он не должен решать, куда мы пишем.
- */
 const selectDocs = (entries) => {
     const prefix = `${ROOT}/`;
     return entries
@@ -141,7 +118,6 @@ const selectDocs = (entries) => {
         !entry.path.split('/').includes('..'))
         .map((entry) => ({ path: entry.path.slice(prefix.length), content: entry.content }));
 };
-/** Скачивает архив репозитория на конкретном коммите. Один запрос, лимитов API нет. */
 const download = async (source, sha) => {
     const url = `https://codeload.github.com/${source.repo}/tar.gz/${sha}`;
     const response = await fetch(url, {
@@ -157,18 +133,9 @@ const download = async (source, sha) => {
     }
     return files;
 };
-/**
- * Отдаёт дерево знаний, предпочитая кэш.
- * Порядок такой: свежий кэш -> сверка sha -> скачивание. Пока запись кэша моложе
- * `refreshTtlMs`, сеть не трогается вообще — иначе цикл перезапусков сервера
- * упирался бы в лимит анонимного API GitHub.
- * Бросает исключение, если знания взять неоткуда; решение о запасном варианте
- * принимает вызывающий.
- */
 export const fetchKnowledgeTree = async (source) => {
     const state = readState(source);
     const files = state && state.ref === source.ref ? readCached(source, state.sha) : undefined;
-    /** Кэш годен только целиком: и запись о коммите, и распакованное дерево. */
     const cache = state && files ? { state, files } : undefined;
     if (cache && (source.offline || Date.now() - cache.state.checkedAt < source.refreshTtlMs)) {
         return { files: cache.files, sha: cache.state.sha, source: 'cache' };
@@ -182,7 +149,6 @@ export const fetchKnowledgeTree = async (source) => {
     }
     catch (error) {
         if (cache) {
-            /** Сеть недоступна, но кэш есть — работаем на нём, это не отказ. */
             return { files: cache.files, sha: cache.state.sha, source: 'cache' };
         }
         throw error;
@@ -196,11 +162,6 @@ export const fetchKnowledgeTree = async (source) => {
     writeState(source, { ref: source.ref, sha, checkedAt: Date.now() });
     return { files: downloaded, sha, source: 'github' };
 };
-/**
- * Читает знания из локального клона репозитория.
- * Принимает и корень клона, и сам каталог `knowledge/` — путать их слишком легко,
- * а разница видна по наличию подкаталога.
- */
 export const readLocalTree = (path) => {
     const root = exists(join(path, ROOT)) ? join(path, ROOT) : path;
     if (!exists(root)) {
@@ -211,4 +172,3 @@ export const readLocalTree = (path) => {
         content: readFileSync(file, 'utf8'),
     }));
 };
-//# sourceMappingURL=github.js.map