@leeguoo/yapi-mcp 0.3.23 → 0.3.25

package/dist/yapi-cli.js

@@ -12,14 +12,40 @@ const path_1 = __importDefault(require("path"));
 const readline_1 = __importDefault(require("readline"));
 const markdown_1 = require("./docs/markdown");
 const install_1 = require("./skill/install");
+const metadata_1 = require("./skill/metadata");
 const auth_1 = require("./services/yapi/auth");
 const authCache_1 = require("./services/yapi/authCache");
+class HttpStatusError extends Error {
+    status;
+    statusText;
+    body;
+    endpoint;
+    constructor(endpoint, status, statusText, body) {
+        super(`request failed: ${status} ${statusText} ${body}`);
+        this.name = "HttpStatusError";
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.endpoint = endpoint;
+    }
+}
 function parseKeyValue(raw) {
     if (!raw || !raw.includes("="))
         throw new Error("expected key=value");
     const idx = raw.indexOf("=");
     return [raw.slice(0, idx), raw.slice(idx + 1)];
 }
+function parseQueryArg(raw) {
+    const trimmed = String(raw || "").trim().replace(/^\?/, "");
+    if (!trimmed)
+        throw new Error("expected key=value");
+    if (!trimmed.includes("&"))
+        return [parseKeyValue(trimmed)];
+    const items = Array.from(new URLSearchParams(trimmed).entries()).filter(([key]) => Boolean(key));
+    if (items.length)
+        return items;
+    return [parseKeyValue(trimmed)];
+}
 function parseHeader(raw) {
     if (!raw || !raw.includes(":"))
         throw new Error("expected Header:Value");
@@ -34,6 +60,58 @@ function parseJsonMaybe(text) {
         return null;
     }
 }
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 B";
+    const units = ["B", "KiB", "MiB", "GiB"];
+    let value = bytes;
+    let index = 0;
+    while (value >= 1024 && index < units.length - 1) {
+        value /= 1024;
+        index += 1;
+    }
+    return `${value >= 10 || index === 0 ? value.toFixed(0) : value.toFixed(2)} ${units[index]}`;
+}
+function parseByteSize(raw) {
+    const text = String(raw || "");
+    const bytesMatch = text.match(/(\d+)\s*bytes?/i);
+    if (bytesMatch)
+        return Number(bytesMatch[1]);
+    const unitMatch = text.match(/(\d+(?:\.\d+)?)\s*(kib|kb|mib|mb|gib|gb)\b/i);
+    if (!unitMatch)
+        return null;
+    const value = Number(unitMatch[1]);
+    if (!Number.isFinite(value))
+        return null;
+    const unit = unitMatch[2].toLowerCase();
+    const factors = {
+        kb: 1000,
+        kib: 1024,
+        mb: 1000 * 1000,
+        mib: 1024 * 1024,
+        gb: 1000 * 1000 * 1000,
+        gib: 1024 * 1024 * 1024,
+    };
+    return Math.round(value * (factors[unit] || 1));
+}
+function parsePayloadLimit(text) {
+    const match = String(text || "").match(/(?:limit|max(?:imum)?(?:\s+body)?(?:\s+size)?)[^0-9]{0,12}(\d+(?:\.\d+)?\s*(?:bytes?|kib|kb|mib|mb|gib|gb))/i);
+    if (match)
+        return parseByteSize(match[1]);
+    return parseByteSize(text);
+}
+function findGitRoot(startDir) {
+    let current = path_1.default.resolve(startDir);
+    while (true) {
+        const candidate = path_1.default.join(current, ".git");
+        if (fs_1.default.existsSync(candidate))
+            return current;
+        const parent = path_1.default.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 function getPayloadMessage(payload) {
     if (!payload || typeof payload !== "object")
         return "";
@@ -814,6 +892,7 @@ function usage() {
         "  yapi whoami [options]",
         "  yapi search [options]",
         "  yapi install-skill [options]",
+        "  yapi self-update",
         "Options:",
         "  --config <path>        config file path (default: ~/.yapi/config.toml)",
         "  --base-url <url>       YApi base URL",
@@ -858,6 +937,9 @@ function usage() {
         "  -h, --help             show help",
     ].join("\n");
 }
+function selfUpdateUsage() {
+    return ["Usage:", "  yapi self-update", "", "Install the latest @leeguoo/yapi-mcp globally with npm."].join("\n");
+}
 function docsSyncUsage() {
     return [
         "Usage:",
@@ -1705,6 +1787,20 @@ function resolveDocsSyncHome(startDir, ensure) {
     ensureDocsSyncReadme(home);
     return home;
 }
+function globalYapiHomeDir() {
+    return path_1.default.resolve(process.env.YAPI_HOME || path_1.default.join(os_1.default.homedir(), ".yapi"));
+}
+function normalizeComparablePath(targetPath) {
+    try {
+        return fs_1.default.realpathSync.native(targetPath);
+    }
+    catch {
+        return path_1.default.resolve(targetPath);
+    }
+}
+function isGlobalDocsSyncHome(homeDir) {
+    return normalizeComparablePath(homeDir) === normalizeComparablePath(globalYapiHomeDir());
+}
 function docsSyncConfigPath(homeDir) {
     return path_1.default.join(homeDir, "docs-sync.json");
 }
@@ -1819,6 +1915,44 @@ function normalizeBindingDir(rootDir, bindingDir) {
         return resolved;
     return relative;
 }
+function getBindingBaseDir(homeDir, rootDir, cwd) {
+    if (!isGlobalDocsSyncHome(homeDir)) {
+        return { baseDir: rootDir, gitRoot: findGitRoot(cwd), usedGitRoot: false };
+    }
+    const gitRoot = findGitRoot(cwd);
+    if (gitRoot) {
+        return { baseDir: gitRoot, gitRoot, usedGitRoot: true };
+    }
+    return { baseDir: path_1.default.resolve(cwd), gitRoot: null, usedGitRoot: false };
+}
+function normalizeBindingDirForContext(homeDir, rootDir, cwd, bindingDir) {
+    const context = getBindingBaseDir(homeDir, rootDir, cwd);
+    const resolved = path_1.default.isAbsolute(bindingDir)
+        ? bindingDir
+        : path_1.default.resolve(context.baseDir, bindingDir);
+    const relative = path_1.default.relative(rootDir, resolved);
+    if (!relative || relative === ".")
+        return ".";
+    if (relative.startsWith("..") || path_1.default.isAbsolute(relative))
+        return resolved;
+    return relative;
+}
+function resolveBindingDirForContext(homeDir, rootDir, cwd, bindingDir) {
+    if (!bindingDir)
+        return rootDir;
+    if (path_1.default.isAbsolute(bindingDir))
+        return bindingDir;
+    const direct = path_1.default.resolve(rootDir, bindingDir);
+    if (!isGlobalDocsSyncHome(homeDir))
+        return direct;
+    if (fs_1.default.existsSync(direct))
+        return direct;
+    const { baseDir } = getBindingBaseDir(homeDir, rootDir, cwd);
+    const contextual = path_1.default.resolve(baseDir, bindingDir);
+    if (fs_1.default.existsSync(contextual))
+        return contextual;
+    return direct;
+}
 function suggestDocsSyncDir(startDir) {
     const candidates = ["docs", "doc", "documentation", "release-notes"];
     for (const candidate of candidates) {
@@ -2028,6 +2162,37 @@ async function checkForUpdates(options) {
     }
     writeUpdateCache(cache);
 }
+function warnIfInstalledSkillsOutdated(options) {
+    if (options.skip)
+        return;
+    const currentVersion = readVersion();
+    if (!currentVersion || currentVersion === "unknown")
+        return;
+    const outdated = (0, metadata_1.findOutdatedSkillInstalls)(currentVersion);
+    if (!outdated.length)
+        return;
+    const summary = outdated
+        .map((item) => `${item.label}@${item.installedVersion || "unknown"}`)
+        .join(", ");
+    console.warn(`skill update available: installed ${summary}, current ${currentVersion}. Run: yapi install-skill --force`);
+}
+function runSelfUpdate(rawArgs) {
+    if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
+        console.log(selfUpdateUsage());
+        return 0;
+    }
+    try {
+        (0, child_process_1.execFileSync)(resolveLocalBin("npm"), ["install", "-g", "@leeguoo/yapi-mcp@latest"], {
+            stdio: "inherit",
+        });
+        console.log("Updated yapi CLI to latest.");
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+}
 async function fetchProjectInfo(projectId, baseUrl, request) {
     if (!projectId)
         return null;
@@ -2096,6 +2261,59 @@ function buildAddPayload(template, title, apiPath, catId, projectId) {
         tag: template.tag || [],
     };
 }
+function buildUpdatePayload(docId, title, markdown, html) {
+    const payload = { id: docId, markdown, desc: html };
+    if (title) {
+        payload.title = title;
+    }
+    return payload;
+}
+function pickLargestMermaid(metrics) {
+    return metrics
+        .filter((item) => item.renderer === "mermaid")
+        .sort((a, b) => b.renderedBytes - a.renderedBytes)[0];
+}
+function buildDocsSyncPreviewLine(item) {
+    const parts = [
+        `file=${item.fileName}`,
+        `action=${item.action}`,
+        `markdown=${formatBytes(item.markdownBytes)}`,
+        `html=${formatBytes(item.htmlBytes)}`,
+        `payload=${formatBytes(item.payloadBytes)}`,
+        `path=${item.apiPath}`,
+    ];
+    if (item.docId) {
+        parts.push(`doc_id=${item.docId}`);
+    }
+    if (item.largestMermaid) {
+        parts.push(`largest_mermaid=#${item.largestMermaid.index}`, `largest_mermaid_svg=${formatBytes(item.largestMermaid.renderedBytes)}`);
+    }
+    return `preview ${parts.join(" ")}`;
+}
+function buildDocsSyncPayloadTooLargeMessage(fileName, preview, error) {
+    const lines = [
+        `413 Payload Too Large while syncing ${fileName}`,
+        `- request payload: ${formatBytes(preview.payloadBytes)}`,
+        `- markdown size: ${formatBytes(preview.markdownBytes)}`,
+        `- rendered html size: ${formatBytes(preview.htmlBytes)}`,
+    ];
+    const limitBytes = parsePayloadLimit(error.body || error.message);
+    if (limitBytes) {
+        lines.push(`- server limit: ${formatBytes(limitBytes)}`);
+    }
+    else {
+        lines.push("- server limit: unknown (response did not expose an exact value)");
+    }
+    if (preview.largestMermaid) {
+        lines.push(`- largest Mermaid block: #${preview.largestMermaid.index} -> ${formatBytes(preview.largestMermaid.renderedBytes)}`);
+    }
+    else {
+        lines.push("- largest Mermaid block: none");
+    }
+    lines.push("- suggestion: run `yapi docs-sync --dry-run ...` to preview all files before upload");
+    lines.push("- suggestion: split oversized Mermaid diagrams or move them into separate docs");
+    return lines.join("\n");
+}
 async function addInterface(title, apiPath, mapping, request) {
     const projectId = Number(mapping.project_id || 0);
     const catId = Number(mapping.catid || 0);
@@ -2122,10 +2340,7 @@ async function addInterface(title, apiPath, mapping, request) {
     return Number(newId);
 }
 async function updateInterface(docId, title, markdown, html, request) {
-    const payload = { id: docId, markdown, desc: html };
-    if (title) {
-        payload.title = title;
-    }
+    const payload = buildUpdatePayload(docId, title, markdown, html);
     const resp = await request("/api/interface/up", "POST", {}, payload);
     if (resp?.errcode !== 0) {
         throw new Error(`interface up failed: ${resp?.errmsg || "unknown error"}`);
@@ -2147,14 +2362,19 @@ async function syncDocsDir(dirPath, mapping, options, request) {
         mapping.catid = Number(envCatId);
     if (!mapping.template_id && envTemplateId)
         mapping.template_id = Number(envTemplateId);
-    if (!mapping.project_id || !mapping.catid) {
+    const hasTarget = Boolean(mapping.project_id && mapping.catid);
+    if (!hasTarget && !options.dryRun) {
         throw new Error("缺少 project_id/catid。请先绑定或配置：yapi docs-sync bind add --name <binding> --dir <path> --project-id <id> --catid <id>，或在目录下添加 .yapi.json，或设置环境变量 YAPI_PROJECT_ID/YAPI_CATID。");
     }
-    const { byPath, byTitle, byId } = await listExistingInterfaces(Number(mapping.catid), request);
+    const { byPath, byTitle, byId } = hasTarget
+        ? await listExistingInterfaces(Number(mapping.catid), request)
+        : { byPath: {}, byTitle: {}, byId: {} };
     let updated = 0;
     let created = 0;
     let skipped = 0;
+    let previewOnly = 0;
     const fileInfos = {};
+    const previews = [];
     const files = resolveSourceFiles(dirPath, mapping);
     for (const mdPath of files) {
         const stem = path_1.default.parse(mdPath).name;
@@ -2168,43 +2388,34 @@ async function syncDocsDir(dirPath, mapping, options, request) {
             if (docId)
                 mapping.files[relName] = docId;
         }
-        if (!docId) {
+        let action = docId ? "update" : hasTarget ? "create" : "preview-only";
+        if (!docId && hasTarget) {
             created += 1;
             if (!options.dryRun) {
                 docId = await addInterface(desiredTitle, apiPath, mapping, request);
                 mapping.files[relName] = docId;
             }
         }
+        if (!docId && !hasTarget) {
+            previewOnly += 1;
+        }
         if (docId) {
             const resolvedPath = byId[String(docId)]?.path || apiPath;
             fileInfos[relName] = { docId: Number(docId), apiPath: resolvedPath };
         }
-        const contentHash = buildDocsSyncHash(markdown, options);
-        const previousHash = mapping.file_hashes[relName];
-        const currentTitle = docId ? byId[String(docId)]?.title : "";
-        const titleToUpdate = !docId
-            ? undefined
-            : !currentTitle || currentTitle !== desiredTitle
-                ? desiredTitle
-                : undefined;
-        const shouldSyncTitle = Boolean(titleToUpdate);
-        if (!options.force &&
-            docId &&
-            previousHash &&
-            previousHash === contentHash &&
-            !shouldSyncTitle) {
-            skipped += 1;
-            continue;
-        }
         const logPrefix = `[docs-sync:${relName}]`;
         let mermaidFailed = false;
         let diagramFailed = false;
+        const diagramMetrics = [];
         const html = (0, markdown_1.renderMarkdownToHtml)(markdown, {
             noMermaid: options.noMermaid,
             logMermaid: true,
             mermaidLook: options.mermaidLook,
             mermaidHandDrawnSeed: options.mermaidHandDrawnSeed,
             logger: (message) => console.log(`${logPrefix} ${message}`),
+            onDiagramRendered: (metric) => {
+                diagramMetrics.push(metric);
+            },
             onMermaidError: () => {
                 mermaidFailed = true;
             },
@@ -2212,15 +2423,56 @@ async function syncDocsDir(dirPath, mapping, options, request) {
                 diagramFailed = true;
             },
         });
-        if (!options.dryRun && docId) {
-            await updateInterface(docId, titleToUpdate, markdown, html, request);
+        const contentHash = buildDocsSyncHash(markdown, options);
+        const previousHash = mapping.file_hashes[relName];
+        const currentTitle = docId ? byId[String(docId)]?.title : "";
+        const titleToUpdate = !docId
+            ? undefined
+            : !currentTitle || currentTitle !== desiredTitle
+                ? desiredTitle
+                : undefined;
+        const shouldSyncTitle = Boolean(titleToUpdate);
+        if (!options.force &&
+            docId &&
+            previousHash &&
+            previousHash === contentHash &&
+            !shouldSyncTitle) {
+            action = "skip";
+            skipped += 1;
+        }
+        const payloadObject = docId && action !== "create"
+            ? buildUpdatePayload(docId, titleToUpdate, markdown, html)
+            : buildAddPayload({}, desiredTitle, apiPath, Number(mapping.catid || 0), Number(mapping.project_id || 0));
+        const preview = {
+            fileName: relName,
+            action,
+            markdownBytes: Buffer.byteLength(markdown, "utf8"),
+            htmlBytes: Buffer.byteLength(html, "utf8"),
+            payloadBytes: Buffer.byteLength(JSON.stringify(payloadObject), "utf8"),
+            apiPath: docId ? fileInfos[relName]?.apiPath || apiPath : apiPath,
+            docId: docId ? Number(docId) : undefined,
+            largestMermaid: pickLargestMermaid(diagramMetrics),
+        };
+        previews.push(preview);
+        if (!options.dryRun && docId && action !== "skip") {
+            try {
+                await updateInterface(docId, titleToUpdate, markdown, html, request);
+            }
+            catch (error) {
+                if (error instanceof HttpStatusError && error.status === 413) {
+                    throw new Error(buildDocsSyncPayloadTooLargeMessage(relName, preview, error));
+                }
+                throw error;
+            }
         }
         if (docId && !mermaidFailed && !diagramFailed) {
             mapping.file_hashes[relName] = contentHash;
         }
-        updated += 1;
+        if (action !== "skip") {
+            updated += 1;
+        }
     }
-    return { updated, created, skipped, files: fileInfos };
+    return { updated, created, skipped, previewOnly, files: fileInfos, previews };
 }
 function buildEnvUrls(projectInfo, apiPath) {
     const urls = {};
@@ -2395,7 +2647,7 @@ async function runDocsSyncBindings(rawArgs) {
         file_hashes: existing.file_hashes ? { ...existing.file_hashes } : {},
     };
     if (options.dir) {
-        next.dir = normalizeBindingDir(rootDir, options.dir);
+        next.dir = normalizeBindingDirForContext(homeDir, rootDir, process.cwd(), options.dir);
     }
     if (options.projectId !== undefined && Number.isFinite(options.projectId)) {
         next.project_id = Number(options.projectId);
@@ -2418,7 +2670,17 @@ async function runDocsSyncBindings(rawArgs) {
     }
     config.bindings[options.name] = next;
     saveDocsSyncConfig(homeDir, config);
+    const resolvedDir = resolveBindingDirForContext(homeDir, rootDir, process.cwd(), next.dir);
     console.log(`${action === "add" ? "binding added" : "binding updated"}: ${options.name}`);
+    console.log(`stored_dir=${next.dir}`);
+    console.log(`resolved_dir=${resolvedDir}`);
+    const gitRoot = findGitRoot(process.cwd());
+    if (gitRoot) {
+        console.log(`git_root=${gitRoot}`);
+    }
+    else if (isGlobalDocsSyncHome(homeDir)) {
+        console.warn("warning: no git root detected, relative --dir was resolved from current working directory");
+    }
     return 0;
 }
 async function runDocsSync(rawArgs) {
@@ -2626,7 +2888,7 @@ async function runDocsSync(rawArgs) {
                 result = await sendOnce();
             }
             if (!result.response.ok) {
-                throw new Error(`request failed: ${result.response.status} ${result.response.statusText} ${result.text}`);
+                throw new HttpStatusError(endpoint, result.response.status, result.response.statusText, result.text);
             }
             if (!result.json) {
                 throw new Error(`invalid JSON response from ${endpoint}`);
@@ -2642,7 +2904,7 @@ async function runDocsSync(rawArgs) {
                 if (!binding) {
                     throw new Error(`binding not found: ${name}`);
                 }
-                const dirPath = resolveBindingDir(rootDir, binding.dir);
+                const dirPath = resolveBindingDirForContext(docsSyncHome, rootDir, process.cwd(), binding.dir);
                 const existing = dirToBindings.get(dirPath) || [];
                 existing.push(name);
                 dirToBindings.set(dirPath, existing);
@@ -2667,12 +2929,16 @@ async function runDocsSync(rawArgs) {
                 if (!binding) {
                     throw new Error(`binding not found: ${name}`);
                 }
-                const dirPath = resolveBindingDir(rootDir, binding.dir);
+                const dirPath = resolveBindingDirForContext(docsSyncHome, rootDir, process.cwd(), binding.dir);
                 if (!fs_1.default.existsSync(dirPath) || !fs_1.default.statSync(dirPath).isDirectory()) {
                     throw new Error(`dir not found for binding ${name}: ${dirPath}`);
                 }
                 const result = await syncDocsDir(dirPath, binding, options, request);
-                console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} binding=${name} dir=${dirPath}`);
+                if (options.dryRun) {
+                    console.log(`dry-run preview binding=${name}`);
+                    result.previews.forEach((item) => console.log(buildDocsSyncPreviewLine(item)));
+                }
+                console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} preview_only=${result.previewOnly} binding=${name} dir=${dirPath}`);
                 bindingResults[name] = { binding, files: result.files };
             }
             if (!options.dryRun) {
@@ -2688,10 +2954,14 @@ async function runDocsSync(rawArgs) {
                 }
                 const { mapping, mappingPath } = loadMapping(dirPath);
                 const result = await syncDocsDir(dirPath, mapping, options, request);
+                if (options.dryRun) {
+                    console.log(`dry-run preview dir=${dirPath}`);
+                    result.previews.forEach((item) => console.log(buildDocsSyncPreviewLine(item)));
+                }
                 if (!options.dryRun) {
                     saveMapping(mapping, mappingPath);
                 }
-                console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} dir=${dirPath}`);
+                console.log(`synced=${result.updated} created=${result.created} skipped=${result.skipped} preview_only=${result.previewOnly} dir=${dirPath}`);
             }
         }
         return 0;
@@ -2704,12 +2974,21 @@ async function runDocsSync(rawArgs) {
 async function main() {
     const rawArgs = process.argv.slice(2);
     const parsedForUpdate = parseArgs(rawArgs);
+    const subcommand = rawArgs[0] || "";
     const skipUpdateCheck = parsedForUpdate.version ||
         parsedForUpdate.help ||
         parsedForUpdate.noUpdate ||
         rawArgs.includes("-h") ||
         rawArgs.includes("--help");
     await checkForUpdates({ noUpdate: parsedForUpdate.noUpdate, skip: skipUpdateCheck });
+    const skipSkillWarning = skipUpdateCheck ||
+        subcommand === "install-skill" ||
+        subcommand === "self-update" ||
+        process.env.YAPI_NO_SKILL_UPDATE_CHECK === "1";
+    warnIfInstalledSkillsOutdated({ skip: skipSkillWarning });
+    if (subcommand === "self-update") {
+        return runSelfUpdate(rawArgs.slice(1));
+    }
     if (rawArgs[0] === "install-skill") {
         await (0, install_1.runInstallSkill)(rawArgs.slice(1));
         return 0;
@@ -2862,7 +3141,7 @@ async function main() {
     }
     const queryItems = [];
     for (const query of options.query || []) {
-        queryItems.push(parseKeyValue(query));
+        queryItems.push(...parseQueryArg(query));
     }
     const url = buildUrl(baseUrl, endpoint, queryItems, authMode === "token" ? token : "", options.tokenParam || "token");
     let dataRaw = null;