@oneentry/mcp-platform-server 0.1.0 → 0.1.1

package/dist/knowledge/github.js

@@ -0,0 +1,214 @@
+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) => {
+    try {
+        const parsed = JSON.parse(readFileSync(stateFile(source), 'utf8'));
+        if (!isRecord(parsed) ||
+            typeof parsed['sha'] !== 'string' ||
+            typeof parsed['ref'] !== 'string' ||
+            typeof parsed['checkedAt'] !== 'number') {
+            return undefined;
+        }
+        return { ref: parsed['ref'], sha: parsed['sha'], checkedAt: parsed['checkedAt'] };
+    }
+    catch {
+        return undefined;
+    }
+};
+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) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    };
+    visit(root);
+    return out.sort();
+};
+const exists = (path) => {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Читает распакованное дерево из кэша. */
+const readCached = (source, sha) => {
+    const dir = join(repoCacheDir(source), sha, ROOT);
+    if (!exists(dir)) {
+        return undefined;
+    }
+    return walkMarkdown(dir).map((file) => ({
+        path: relative(dir, file).split(sep).join('/'),
+        content: readFileSync(file, 'utf8'),
+    }));
+};
+/**
+ * Записывает дерево в кэш и удаляет каталоги остальных sha.
+ * Кэш адресуется коммитом, поэтому старые версии не нужны никогда:
+ * запись неизменяема, и «протухнуть» она не может.
+ */
+const writeCache = (source, sha, files) => {
+    const base = repoCacheDir(source);
+    const target = join(base, sha, ROOT);
+    for (const file of files) {
+        const full = join(target, file.path);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, file.content);
+    }
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== sha) {
+            rmSync(join(base, entry.name), { recursive: true, force: true });
+        }
+    }
+};
+const headers = (source, accept) => ({
+    accept,
+    'user-agent': 'oneentry-mcp-platform',
+    ...(source.token ? { authorization: `Bearer ${source.token}` } : {}),
+});
+/**
+ * Расшифровывает код ответа GitHub в причину, по которой ref не превратился в коммит.
+ * Голый статус здесь бесполезен: 404 и 409 — это разные ошибки настройки, и обе
+ * встречаются при первом подключении к новому репозиторию знаний.
+ */
+const shaFailureHint = (status) => {
+    switch (status) {
+        case 403: {
+            return ' (rate limit — set ONEENTRY_GITHUB_TOKEN)';
+        }
+        case 404: {
+            return ' (no such repository or ref — check ONEENTRY_MCP_KNOWLEDGE_REPO, and set ONEENTRY_GITHUB_TOKEN if it is private)';
+        }
+        case 409: {
+            return ' (the repository is empty — it has no commits yet)';
+        }
+        default: {
+            return '';
+        }
+    }
+};
+/**
+ * Превращает ref в конкретный коммит. Ответ — голый sha, поэтому запрос дешёвый:
+ * его можно делать при каждом запуске, не скачивая архив.
+ */
+const resolveSha = async (source) => {
+    const url = `https://api.github.com/repos/${source.repo}/commits/${encodeURIComponent(source.ref)}`;
+    const response = await fetch(url, {
+        headers: headers(source, 'application/vnd.github.sha'),
+        signal: AbortSignal.timeout(source.timeoutMs),
+    });
+    if (!response.ok) {
+        throw new Error(`GitHub answered ${String(response.status)} for ${source.repo}@${source.ref}` +
+            shaFailureHint(response.status));
+    }
+    const sha = (await response.text()).trim();
+    if (!/^[0-9a-f]{7,40}$/.test(sha)) {
+        throw new Error(`GitHub returned an unexpected commit id for ${source.repo}@${source.ref}`);
+    }
+    return sha;
+};
+/**
+ * Отбирает из архива только документацию.
+ * Всё, что вне `knowledge/`, и любой путь с `..` отбрасываются: архив приходит
+ * из сети, и он не должен решать, куда мы пишем.
+ */
+const selectDocs = (entries) => {
+    const prefix = `${ROOT}/`;
+    return entries
+        .filter((entry) => entry.path.startsWith(prefix) &&
+        entry.path.endsWith('.md') &&
+        !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, {
+        headers: headers(source, 'application/octet-stream'),
+        signal: AbortSignal.timeout(source.timeoutMs),
+    });
+    if (!response.ok) {
+        throw new Error(`GitHub answered ${String(response.status)} for the ${source.repo} archive`);
+    }
+    const files = selectDocs(readTarGz(Buffer.from(await response.arrayBuffer())));
+    if (files.length === 0) {
+        throw new Error(`${source.repo}@${sha} has no ${ROOT}/**/*.md — wrong repository or layout?`);
+    }
+    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' };
+    }
+    if (source.offline) {
+        throw new Error(`offline: no cached copy of ${source.repo}@${source.ref}`);
+    }
+    let sha;
+    try {
+        sha = await resolveSha(source);
+    }
+    catch (error) {
+        if (cache) {
+            /** Сеть недоступна, но кэш есть — работаем на нём, это не отказ. */
+            return { files: cache.files, sha: cache.state.sha, source: 'cache' };
+        }
+        throw error;
+    }
+    if (cache && cache.state.sha === sha) {
+        writeState(source, { ref: source.ref, sha, checkedAt: Date.now() });
+        return { files: cache.files, sha, source: 'cache' };
+    }
+    const downloaded = await download(source, sha);
+    writeCache(source, sha, downloaded);
+    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)) {
+        throw new Error(`Knowledge path "${path}" does not exist`);
+    }
+    return walkMarkdown(root).map((file) => ({
+        path: relative(root, file).split(sep).join('/'),
+        content: readFileSync(file, 'utf8'),
+    }));
+};
+//# sourceMappingURL=github.js.map

package/dist/knowledge/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/knowledge/github.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAChG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAiCrC,gEAAgE;AAChE,MAAM,IAAI,GAAG,WAAW,CAAC;AAUzB,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,yFAAyF;AACzF,MAAM,YAAY,GAAG,CAAC,MAAuB,EAAU,EAAE,CACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAE3D,MAAM,SAAS,GAAG,CAAC,MAAuB,EAAU,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,CAAC;AAElG,MAAM,SAAS,GAAG,CAAC,MAAuB,EAA0B,EAAE;IACpE,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5E,IACE,CAAC,QAAQ,CAAC,MAAM,CAAC;YACjB,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ;YACjC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ;YACjC,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,QAAQ,EACvC,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,MAAuB,EAAE,KAAiB,EAAQ,EAAE;IACtE,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAY,EAAE;IACrD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,KAAK,GAAG,CAAC,GAAW,EAAQ,EAAE;QAClC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,CAAC;YACd,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,CAAC;IACZ,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,CAAC,IAAY,EAAW,EAAE;IACvC,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,UAAU,GAAG,CAAC,MAAuB,EAAE,GAAW,EAA+B,EAAE;IACvF,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtC,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC9C,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;KACpC,CAAC,CAAC,CAAC;AACN,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,MAAuB,EAAE,GAAW,EAAE,KAA+B,EAAQ,EAAE;IACjG,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YAC9C,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,MAAuB,EAAE,MAAc,EAA0B,EAAE,CAAC,CAAC;IACpF,MAAM;IACN,YAAY,EAAE,uBAAuB;IACrC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CACrE,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,cAAc,GAAG,CAAC,MAAc,EAAU,EAAE;IAChD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,OAAO,2CAA2C,CAAC;QACrD,CAAC;QACD,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,OAAO,kHAAkH,CAAC;QAC5H,CAAC;QACD,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,OAAO,oDAAoD,CAAC;QAC9D,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,GAAG,KAAK,EAAE,MAAuB,EAAmB,EAAE;IACpE,MAAM,GAAG,GAAG,gCAAgC,MAAM,CAAC,IAAI,YAAY,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACpG,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAChC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,4BAA4B,CAAC;QACtD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,GAAG,EAAE;YAC3E,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAClC,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,+CAA+C,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,OAAiC,EAAmB,EAAE;IACxE,MAAM,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC;IAC1B,OAAO,OAAO;SACX,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC1B,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CACxC;SACA,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACzF,CAAC,CAAC;AAEF,uFAAuF;AACvF,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAuB,EAAE,GAAW,EAA4B,EAAE;IACxF,MAAM,GAAG,GAAG,+BAA+B,MAAM,CAAC,IAAI,WAAW,GAAG,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAChC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,0BAA0B,CAAC;QACpD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,MAAM,CAAC,IAAI,UAAU,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,GAAG,WAAW,IAAI,wCAAwC,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EAAE,MAAuB,EAA0B,EAAE;IAC1F,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,IAAI,KAAK,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5F,4EAA4E;IAC5E,MAAM,KAAK,GAAG,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5D,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1F,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACvE,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,EAAE,CAAC;YACV,oEAAoE;YACpE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;QACrC,UAAU,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;IACpC,UAAU,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtD,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAmB,EAAE;IAC7D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,kBAAkB,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC/C,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC;KACpC,CAAC,CAAC,CAAC;AACN,CAAC,CAAC"}

package/dist/knowledge/loader.d.ts

@@ -1,27 +1,54 @@
-import type { KnowledgePack } from './types.js';
-/** Каталог со собственными знаниями пакета (operating-rules.md и т.п.). */
-export declare const ownKnowledgeDir: () => string;
-/** Каталог со собранными данными пакета (knowledge.json, catalog.json). */
+import { type KnowledgeFile } from './github.js';
+import type { KnowledgeOrigin, KnowledgePack } from './types.js';
+/** Настройки источника знаний, как их отдаёт конфигурация. */
+export interface KnowledgeConfig {
+    repo: string;
+    ref: string;
+    /** Локальный клон репозитория знаний: приоритетнее сети. */
+    path?: string;
+    cacheDir: string;
+    refreshTtlMs: number;
+    offline: boolean;
+    token?: string;
+    timeoutMs: number;
+}
+/** Каталог с вшитым минимумом знаний (`operating-rules.md`). */
+export declare const seedDir: () => string;
+/** Каталог со сгенерированными данными пакета (`permissions.json`). */
 export declare const dataDir: () => string;
 /**
- * Собирает пакет знаний из чекаутов. Используется и сборкой снапшота,
- * и live-режимом, поэтому результат в обоих случаях идентичен по структуре.
+ * docId из пути внутри `knowledge/`.
+ * `<имя>/index.md` даёт docId `<имя>`: это позволяет разрезать большой документ
+ * на каталог из мелких файлов, не меняя идентификатор, на который уже ссылаются
+ * `docLinks` каталога операций и золотые запросы тестов.
  */
-export declare const buildPack: (params: {
-    backPath?: string;
-    frontPath?: string;
-    source: KnowledgePack["source"];
+export declare const docIdFromPath: (path: string) => string;
+/**
+ * Собирает пакет знаний из плоского списка файлов.
+ * Один вход для всех трёх источников — сети, кэша и локального клона, — поэтому
+ * поведение поиска не может разойтись между ними.
+ */
+export declare const packFromFiles: (params: {
+    files: readonly KnowledgeFile[];
+    source: KnowledgeOrigin;
     builtAt: string;
+    repo?: string;
+    ref?: string;
+    sha?: string;
+    warning?: string;
 }) => KnowledgePack;
-/** Читает собранный снапшот из data/knowledge.json. */
-export declare const loadSnapshot: () => KnowledgePack;
 /**
- * Выбирает источник знаний: живой чекаут, если он указан, иначе снапшот пакета.
- * Live-режим нужен, чтобы правка документации в dnk-back действовала сразу,
- * без переиздания npm-пакета.
+ * Вшитый минимум: собственные правила эксплуатации пакета.
+ * Существует только затем, чтобы сервер без сети всё равно мог ответить на вопрос
+ * «как безопасно писать в эту CMS». Всё остальное живёт в репозитории знаний.
  */
-export declare const resolveKnowledge: (params: {
-    backPath?: string;
-    frontPath?: string;
-}) => KnowledgePack;
+export declare const seedPack: (warning?: string) => KnowledgePack;
+/**
+ * Выбирает источник знаний: локальный клон -> GitHub (через кэш) -> вшитый минимум.
+ * Недоступный GitHub не мешает серверу подняться: пакет беднеет до вшитого минимума,
+ * а причина уезжает в `warning`, потому что сеть — не ошибка конфигурации.
+ * Единственное исключение бросается на нечитаемый локальный путь: его оператор указал
+ * явно, и молчаливое падение до вшитых правил выглядело бы как пустой корпус.
+ */
+export declare const resolveKnowledge: (config: KnowledgeConfig) => Promise<KnowledgePack>;
 //# sourceMappingURL=loader.d.ts.map

package/dist/knowledge/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/knowledge/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,YAAY,CAAC;AAsF9E,2EAA2E;AAC3E,eAAO,MAAM,eAAe,QAAO,MACuC,CAAC;AAE3E,2EAA2E;AAC3E,eAAO,MAAM,OAAO,QAAO,MAC0C,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB,KAAG,aA0BH,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,YAAY,QAAO,aAO/B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAG,aAUH,CAAC"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/knowledge/loader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,KAAK,EAAgC,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD,gEAAgE;AAChE,eAAO,MAAM,OAAO,QAAO,MAC+C,CAAC;AAE3E,uEAAuE;AACvE,eAAO,MAAM,OAAO,QAAO,MAC0C,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MACM,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ;IACpC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,aA2BH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,KAAG,aAWxC,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAU,QAAQ,eAAe,KAAG,OAAO,CAAC,aAAa,CA2CrF,CAAC"}

package/dist/knowledge/loader.js

@@ -1,125 +1,112 @@
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chunkDocument } from './chunk.js';
-const BACK_SOURCES = [
-    { repo: 'back', subPath: '.claude/docs', docPrefix: 'back/docs' },
-    { repo: 'back', subPath: '.claude/tests', docPrefix: 'back/tests' },
-    { repo: 'back', subPath: '.claude/rules', docPrefix: 'back/rules' },
-    { repo: 'back', subPath: '.claude/fixes', docPrefix: 'back/fixes' },
-    { repo: 'back', subPath: '.claude/CLAUDE.md', docPrefix: 'back', singleFile: true },
-];
-const FRONT_SOURCES = [
-    { repo: 'front', subPath: '.claude/docs', docPrefix: 'front/docs' },
-    { repo: 'front', subPath: '.claude/rules', docPrefix: 'front/rules' },
-    { repo: 'front', subPath: '.claude/fixes', docPrefix: 'front/fixes' },
-];
-/** Рекурсивно собирает пути всех `*.md` внутри каталога. */
-const walkMarkdown = (root) => {
-    const out = [];
-    const visit = (dir) => {
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            const full = join(dir, entry.name);
-            if (entry.isDirectory()) {
-                visit(full);
-            }
-            else if (entry.isFile() && entry.name.endsWith('.md')) {
-                out.push(full);
-            }
-        }
-    };
-    visit(root);
-    return out.sort();
-};
-const exists = (path) => {
-    try {
-        statSync(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const collectSource = (repoRoot, spec) => {
-    const target = resolve(repoRoot, spec.subPath);
+import { fetchKnowledgeTree, readLocalTree } from './github.js';
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/** Каталог с вшитым минимумом знаний (`operating-rules.md`). */
+export const seedDir = () => resolve(fileURLToPath(new URL('.', import.meta.url)), '../../knowledge');
+/** Каталог со сгенерированными данными пакета (`permissions.json`). */
+export const dataDir = () => resolve(fileURLToPath(new URL('.', import.meta.url)), '../../data');
+/**
+ * docId из пути внутри `knowledge/`.
+ * `<имя>/index.md` даёт docId `<имя>`: это позволяет разрезать большой документ
+ * на каталог из мелких файлов, не меняя идентификатор, на который уже ссылаются
+ * `docLinks` каталога операций и золотые запросы тестов.
+ */
+export const docIdFromPath = (path) => path.replace(/\.md$/, '').replace(/\/index$/, '');
+/**
+ * Собирает пакет знаний из плоского списка файлов.
+ * Один вход для всех трёх источников — сети, кэша и локального клона, — поэтому
+ * поведение поиска не может разойтись между ними.
+ */
+export const packFromFiles = (params) => {
     const docs = [];
     const chunks = [];
-    if (!exists(target)) {
-        return { docs, chunks };
-    }
-    const files = spec.singleFile ? [target] : walkMarkdown(target);
-    for (const file of files) {
-        const rel = spec.singleFile
-            ? file.split(sep).slice(-1).join('')
-            : relative(target, file);
-        const slug = rel.replace(/\.md$/, '').split(sep).join('/');
-        const docId = spec.docPrefix ? `${spec.docPrefix}/${slug}` : slug;
+    for (const file of [...params.files].sort((a, b) => a.path.localeCompare(b.path))) {
+        const docId = docIdFromPath(file.path);
         const result = chunkDocument({
             docId,
-            repo: spec.repo,
-            path: relative(repoRoot, file).split(sep).join('/'),
-            markdown: readFileSync(file, 'utf8'),
+            repo: docId.split('/')[0] ?? 'mcp',
+            path: `knowledge/${file.path}`,
+            markdown: file.content,
         });
         docs.push(result.doc);
         chunks.push(...result.chunks);
     }
-    return { docs, chunks };
+    return {
+        version: 1,
+        builtAt: params.builtAt,
+        source: params.source,
+        ...(params.repo ? { repo: params.repo } : {}),
+        ...(params.ref ? { ref: params.ref } : {}),
+        ...(params.sha ? { sha: params.sha } : {}),
+        ...(params.warning ? { warning: params.warning } : {}),
+        docs,
+        chunks,
+    };
 };
-/** Каталог со собственными знаниями пакета (operating-rules.md и т.п.). */
-export const ownKnowledgeDir = () => resolve(fileURLToPath(new URL('.', import.meta.url)), '../../knowledge');
-/** Каталог со собранными данными пакета (knowledge.json, catalog.json). */
-export const dataDir = () => resolve(fileURLToPath(new URL('.', import.meta.url)), '../../data');
 /**
- * Собирает пакет знаний из чекаутов. Используется и сборкой снапшота,
- * и live-режимом, поэтому результат в обоих случаях идентичен по структуре.
+ * Вшитый минимум: собственные правила эксплуатации пакета.
+ * Существует только затем, чтобы сервер без сети всё равно мог ответить на вопрос
+ * «как безопасно писать в эту CMS». Всё остальное живёт в репозитории знаний.
  */
-export const buildPack = (params) => {
-    const docs = [];
-    const chunks = [];
-    const own = collectSource(ownKnowledgeDir(), {
-        repo: 'mcp',
-        subPath: '.',
-        docPrefix: 'mcp',
-    });
-    docs.push(...own.docs);
-    chunks.push(...own.chunks);
-    const add = (root, specs) => {
-        if (!root) {
-            return;
+export const seedPack = (warning) => packFromFiles({
+    files: [
+        {
+            path: 'mcp/operating-rules.md',
+            content: readFileSync(resolve(seedDir(), 'operating-rules.md'), 'utf8'),
+        },
+    ],
+    source: 'seed',
+    builtAt: new Date().toISOString(),
+    ...(warning ? { warning } : {}),
+});
+/**
+ * Выбирает источник знаний: локальный клон -> GitHub (через кэш) -> вшитый минимум.
+ * Недоступный GitHub не мешает серверу подняться: пакет беднеет до вшитого минимума,
+ * а причина уезжает в `warning`, потому что сеть — не ошибка конфигурации.
+ * Единственное исключение бросается на нечитаемый локальный путь: его оператор указал
+ * явно, и молчаливое падение до вшитых правил выглядело бы как пустой корпус.
+ */
+export const resolveKnowledge = async (config) => {
+    const builtAt = new Date().toISOString();
+    if (config.path) {
+        try {
+            return packFromFiles({
+                files: readLocalTree(config.path),
+                source: 'local',
+                builtAt,
+                repo: config.path,
+            });
         }
-        for (const spec of specs) {
-            const result = collectSource(root, spec);
-            docs.push(...result.docs);
-            chunks.push(...result.chunks);
+        catch (error) {
+            throw new Error(`Local knowledge path "${config.path}" could not be read (${messageOf(error)}). ` +
+                'Fix the path, or unset it to read the knowledge repository from GitHub.');
         }
-    };
-    add(params.backPath, BACK_SOURCES);
-    add(params.frontPath, FRONT_SOURCES);
-    return { version: 1, builtAt: params.builtAt, source: params.source, docs, chunks };
-};
-/** Читает собранный снапшот из data/knowledge.json. */
-export const loadSnapshot = () => {
-    const file = resolve(dataDir(), 'knowledge.json');
-    const parsed = JSON.parse(readFileSync(file, 'utf8'));
-    if (parsed.version !== 1) {
-        throw new Error(`Unsupported knowledge pack version ${String(parsed.version)}`);
     }
-    return parsed;
-};
-/**
- * Выбирает источник знаний: живой чекаут, если он указан, иначе снапшот пакета.
- * Live-режим нужен, чтобы правка документации в dnk-back действовала сразу,
- * без переиздания npm-пакета.
- */
-export const resolveKnowledge = (params) => {
-    if (params.backPath) {
-        return buildPack({
-            backPath: params.backPath,
-            frontPath: params.frontPath,
-            source: 'live',
-            builtAt: new Date().toISOString(),
+    try {
+        const tree = await fetchKnowledgeTree({
+            repo: config.repo,
+            ref: config.ref,
+            cacheDir: config.cacheDir,
+            refreshTtlMs: config.refreshTtlMs,
+            offline: config.offline,
+            ...(config.token ? { token: config.token } : {}),
+            timeoutMs: config.timeoutMs,
+        });
+        return packFromFiles({
+            files: tree.files,
+            source: tree.source,
+            builtAt,
+            repo: config.repo,
+            ref: config.ref,
+            sha: tree.sha,
         });
     }
-    return loadSnapshot();
+    catch (error) {
+        return seedPack(`Knowledge repository ${config.repo}@${config.ref} is unavailable (${messageOf(error)}). ` +
+            'Only the bundled operating rules are available — module reference docs will not be found.');
+    }
 };
 //# sourceMappingURL=loader.js.map

package/dist/knowledge/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/knowledge/loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/knowledge/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAgBpF,MAAM,SAAS,GAAG,CAAC,KAAc,EAAU,EAAE,CAC3C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEzD,gEAAgE;AAChE,MAAM,CAAC,MAAM,OAAO,GAAG,GAAW,EAAE,CAClC,OAAO,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;AAE3E,uEAAuE;AACvE,MAAM,CAAC,MAAM,OAAO,GAAG,GAAW,EAAE,CAClC,OAAO,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE,CACpD,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAQ7B,EAAiB,EAAE;IAClB,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,MAAM,MAAM,GAAqB,EAAE,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAClF,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,aAAa,CAAC;YAC3B,KAAK;YACL,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK;YAClC,IAAI,EAAE,aAAa,IAAI,CAAC,IAAI,EAAE;YAC9B,QAAQ,EAAE,IAAI,CAAC,OAAO;SACvB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,OAAO;QACL,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,IAAI;QACJ,MAAM;KACP,CAAC;AACJ,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAgB,EAAiB,EAAE,CAC1D,aAAa,CAAC;IACZ,KAAK,EAAE;QACL;YACE,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC;SACxE;KACF;IACD,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IACjC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CAChC,CAAC,CAAC;AAEL;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,EAAE,MAAuB,EAA0B,EAAE;IACxF,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEzC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,OAAO,aAAa,CAAC;gBACnB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC;gBACjC,MAAM,EAAE,OAAO;gBACf,OAAO;gBACP,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,yBAAyB,MAAM,CAAC,IAAI,wBAAwB,SAAS,CAAC,KAAK,CAAC,KAAK;gBAC/E,yEAAyE,CAC5E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC;YACpC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,OAAO,aAAa,CAAC;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO;YACP,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,QAAQ,CACb,wBAAwB,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,GAAG,oBAAoB,SAAS,CAAC,KAAK,CAAC,KAAK;YACxF,2FAA2F,CAC9F,CAAC;IACJ,CAAC;AACH,CAAC,CAAC"}

package/dist/knowledge/search.d.ts

@@ -10,6 +10,17 @@ export interface KnowledgeHit {
     score: number;
     snippet: string;
 }
+/**
+ * Выбрасывает из запроса слова короче трёх букв.
+ * Заголовок весит вчетверо больше текста, поэтому раздел «Не входит в scope»
+ * выигрывал у описания модуля на вопросе «почему атрибут не попал в индекс»:
+ * два служебных слова совпадали с заголовком, а значащие — с телом. Предлоги и
+ * частицы (`не`, `в`, `на`, `of`, `to`) не несут смысла ни в русском запросе,
+ * ни в английском, и участвовать в ранжировании не должны.
+ * Если после отбора не осталось ничего, запрос возвращается как есть —
+ * поиск по одному короткому слову лучше поиска ни по чему.
+ */
+export declare const meaningfulQuery: (query: string) => string;
 /**
  * Поисковый индекс по разделам документации.
  * Хранит только идентификаторы в индексе, а тексты — в отдельной карте:

package/dist/knowledge/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAiCD;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa;IAkB/B,6EAA6E;IAC7E,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI5C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,IAAI,IAAI,SAAS,YAAY,EAAE;IAI/B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,YAAY,EAAE;CAwBjD"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAiCD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MAG/C,CAAC;AAqBF;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa;IAkB/B,6EAA6E;IAC7E,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI5C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,IAAI,IAAI,SAAS,YAAY,EAAE;IAI/B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,YAAY,EAAE;CAwBjD"}