@leeguoo/yapi-mcp 0.3.26 → 0.4.0

package/dist/cli/commands/docs-sync.js

@@ -0,0 +1,1011 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDocsSyncBindings = runDocsSyncBindings;
+exports.runDocsSync = runDocsSync;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("../utils");
+const http_1 = require("../http");
+const markdown_1 = require("../../docs/markdown");
+const auth_1 = require("../../services/yapi/auth");
+function findDocsSyncHome(startDir) {
+    let current = path_1.default.resolve(startDir);
+    while (true) {
+        const candidate = path_1.default.join(current, ".yapi");
+        if (fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+        const parent = path_1.default.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function resolveDocsSyncHome(startDir, ensure) {
+    const found = findDocsSyncHome(startDir);
+    if (found)
+        return found;
+    if (!ensure)
+        return null;
+    const home = path_1.default.join(path_1.default.resolve(startDir), ".yapi");
+    fs_1.default.mkdirSync(home, { recursive: true });
+    ensureDocsSyncReadme(home);
+    return home;
+}
+function globalYapiHomeDir() {
+    return path_1.default.resolve(process.env.YAPI_HOME || path_1.default.join(require("os").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");
+}
+function docsSyncLinksPath(homeDir) {
+    return path_1.default.join(homeDir, "docs-sync.links.json");
+}
+function docsSyncProjectsPath(homeDir) {
+    return path_1.default.join(homeDir, "docs-sync.projects.json");
+}
+function docsSyncDeploymentsPath(homeDir) {
+    return path_1.default.join(homeDir, "docs-sync.deployments.json");
+}
+const DOCS_SYNC_README = [
+    "# YApi Docs Sync",
+    "",
+    "This folder is generated by the yapi docs-sync tool.",
+    "Extra caches are written when running docs-sync with bindings.",
+    "",
+    "Project: https://github.com/leeguooooo/cross-request-master",
+    "",
+    "Files:",
+    "- docs-sync.json: bindings and file-to-doc ID mapping.",
+    "- docs-sync.links.json: local docs to YApi doc URLs.",
+    "- docs-sync.projects.json: cached project metadata/envs.",
+    "- docs-sync.deployments.json: local docs to deployed URLs.",
+].join("\n");
+function ensureDocsSyncReadme(homeDir) {
+    const readmePath = path_1.default.join(homeDir, "README.md");
+    if (fs_1.default.existsSync(readmePath))
+        return;
+    fs_1.default.writeFileSync(readmePath, `${DOCS_SYNC_README}\n`, "utf8");
+}
+function loadDocsSyncConfig(homeDir) {
+    const configPath = docsSyncConfigPath(homeDir);
+    if (!fs_1.default.existsSync(configPath)) {
+        return { version: 1, bindings: {} };
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const bindings = parsed.bindings && typeof parsed.bindings === "object" ? parsed.bindings : {};
+    return {
+        version: typeof parsed.version === "number" ? parsed.version : 1,
+        bindings: bindings,
+    };
+}
+function saveDocsSyncConfig(homeDir, config) {
+    const configPath = docsSyncConfigPath(homeDir);
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+function loadDocsSyncLinks(homeDir) {
+    const configPath = docsSyncLinksPath(homeDir);
+    if (!fs_1.default.existsSync(configPath)) {
+        return { version: 1, bindings: {} };
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const bindings = parsed.bindings && typeof parsed.bindings === "object" ? parsed.bindings : {};
+    return {
+        version: typeof parsed.version === "number" ? parsed.version : 1,
+        bindings: bindings,
+    };
+}
+function saveDocsSyncLinks(homeDir, config) {
+    const configPath = docsSyncLinksPath(homeDir);
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+function loadDocsSyncProjects(homeDir) {
+    const configPath = docsSyncProjectsPath(homeDir);
+    if (!fs_1.default.existsSync(configPath)) {
+        return { version: 1, projects: {} };
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const projects = parsed.projects && typeof parsed.projects === "object" ? parsed.projects : {};
+    return {
+        version: typeof parsed.version === "number" ? parsed.version : 1,
+        projects: projects,
+    };
+}
+function saveDocsSyncProjects(homeDir, config) {
+    const configPath = docsSyncProjectsPath(homeDir);
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+function loadDocsSyncDeployments(homeDir) {
+    const configPath = docsSyncDeploymentsPath(homeDir);
+    if (!fs_1.default.existsSync(configPath)) {
+        return { version: 1, bindings: {} };
+    }
+    const raw = fs_1.default.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const bindings = parsed.bindings && typeof parsed.bindings === "object" ? parsed.bindings : {};
+    return {
+        version: typeof parsed.version === "number" ? parsed.version : 1,
+        bindings: bindings,
+    };
+}
+function saveDocsSyncDeployments(homeDir, config) {
+    const configPath = docsSyncDeploymentsPath(homeDir);
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+function resolveBindingDir(rootDir, bindingDir) {
+    if (!bindingDir)
+        return rootDir;
+    return path_1.default.isAbsolute(bindingDir) ? bindingDir : path_1.default.resolve(rootDir, bindingDir);
+}
+function normalizeBindingDir(rootDir, bindingDir) {
+    const resolved = resolveBindingDir(rootDir, 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 getBindingBaseDir(homeDir, rootDir, cwd) {
+    if (!isGlobalDocsSyncHome(homeDir)) {
+        return { baseDir: rootDir, gitRoot: (0, utils_1.findGitRoot)(cwd), usedGitRoot: false };
+    }
+    const gitRoot = (0, utils_1.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) {
+        const candidatePath = path_1.default.resolve(startDir, candidate);
+        if (fs_1.default.existsSync(candidatePath) && fs_1.default.statSync(candidatePath).isDirectory()) {
+            const relative = path_1.default.relative(startDir, candidatePath);
+            return relative && relative !== "." ? relative : candidate;
+        }
+    }
+    return null;
+}
+function loadMapping(dirPath) {
+    const mappingPath = path_1.default.join(dirPath, ".yapi.json");
+    if (!fs_1.default.existsSync(mappingPath)) {
+        return { mapping: {}, mappingPath };
+    }
+    const raw = fs_1.default.readFileSync(mappingPath, "utf8");
+    const mapping = JSON.parse(raw);
+    return { mapping, mappingPath };
+}
+function saveMapping(mapping, mappingPath) {
+    fs_1.default.writeFileSync(mappingPath, `${JSON.stringify(mapping, null, 2)}\n`, "utf8");
+}
+function resolveSourceFiles(dirPath, mapping) {
+    const sources = Array.isArray(mapping.source_files) ? mapping.source_files : [];
+    if (!sources.length) {
+        return fs_1.default
+            .readdirSync(dirPath)
+            .filter((name) => name.endsWith(".md") && name !== "README.md")
+            .map((name) => path_1.default.join(dirPath, name))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    return sources.map((source) => {
+        const resolved = path_1.default.isAbsolute(source) ? source : path_1.default.resolve(dirPath, source);
+        if (!fs_1.default.existsSync(resolved) || !fs_1.default.statSync(resolved).isFile()) {
+            throw new Error(`source file not found: ${resolved}`);
+        }
+        return resolved;
+    });
+}
+async function listExistingInterfaces(catId, request) {
+    const resp = await request("/api/interface/list_cat", "GET", {
+        catid: catId,
+        page: 1,
+        limit: 10000,
+    });
+    if (resp?.errcode !== 0) {
+        throw new Error(`list_cat failed: ${resp?.errmsg || "unknown error"}`);
+    }
+    const items = resp?.data?.list || [];
+    const byPath = {};
+    const byTitle = {};
+    const byId = {};
+    for (const item of items) {
+        const apiPath = item?.path;
+        const title = item?.title;
+        const itemId = item?._id;
+        if (apiPath && itemId)
+            byPath[apiPath] = Number(itemId);
+        if (title && itemId)
+            byTitle[title] = Number(itemId);
+        if (itemId) {
+            byId[String(itemId)] = { path: apiPath || "", title: title || "" };
+        }
+    }
+    return { byPath, byTitle, byId };
+}
+function buildAddPayload(template, title, apiPath, catId, projectId) {
+    return {
+        title,
+        path: apiPath,
+        method: template.method || "GET",
+        catid: catId,
+        project_id: projectId,
+        status: template.status || "undone",
+        type: template.type || "static",
+        api_opened: template.api_opened || false,
+        req_query: template.req_query || [],
+        req_headers: template.req_headers || [],
+        req_params: template.req_params || [],
+        req_body_type: template.req_body_type || "json",
+        req_body_form: template.req_body_form || [],
+        req_body_is_json_schema: template.req_body_is_json_schema ?? true,
+        res_body_type: template.res_body_type || "json",
+        res_body: template.res_body || '{"type":"object","title":"title","properties":{}}',
+        res_body_is_json_schema: template.res_body_is_json_schema ?? true,
+        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=${(0, utils_1.formatBytes)(item.markdownBytes)}`,
+        `html=${(0, utils_1.formatBytes)(item.htmlBytes)}`,
+        `payload=${(0, utils_1.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=${(0, utils_1.formatBytes)(item.largestMermaid.renderedBytes)}`);
+    }
+    return `preview ${parts.join(" ")}`;
+}
+function buildDocsSyncPayloadTooLargeMessage(fileName, preview, error) {
+    const lines = [
+        `413 Payload Too Large while syncing ${fileName}`,
+        `- request payload: ${(0, utils_1.formatBytes)(preview.payloadBytes)}`,
+        `- markdown size: ${(0, utils_1.formatBytes)(preview.markdownBytes)}`,
+        `- rendered html size: ${(0, utils_1.formatBytes)(preview.htmlBytes)}`,
+    ];
+    const limitBytes = (0, utils_1.parsePayloadLimit)(error.body || error.message);
+    if (limitBytes) {
+        lines.push(`- server limit: ${(0, utils_1.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} -> ${(0, utils_1.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);
+    if (!projectId || !catId) {
+        throw new Error("project_id and catid are required to create new docs");
+    }
+    let template = {};
+    if (mapping.template_id) {
+        const resp = await request("/api/interface/get", "GET", { id: mapping.template_id });
+        if (resp?.errcode !== 0) {
+            throw new Error(`interface get failed: ${resp?.errmsg || "unknown error"}`);
+        }
+        template = resp?.data || {};
+    }
+    const payload = buildAddPayload(template, title, apiPath, catId, projectId);
+    const resp = await request("/api/interface/add", "POST", {}, payload);
+    if (resp?.errcode !== 0) {
+        throw new Error(`interface add failed: ${resp?.errmsg || "unknown error"}`);
+    }
+    const newId = resp?.data?._id;
+    if (!newId) {
+        throw new Error("interface add succeeded but missing id");
+    }
+    return Number(newId);
+}
+async function updateInterface(docId, title, markdown, html, request) {
+    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"}`);
+    }
+}
+async function syncDocsDir(dirPath, mapping, options, request) {
+    if (!mapping.files || typeof mapping.files !== "object") {
+        mapping.files = {};
+    }
+    if (!mapping.file_hashes || typeof mapping.file_hashes !== "object") {
+        mapping.file_hashes = {};
+    }
+    const envProjectId = process.env.YAPI_PROJECT_ID;
+    const envCatId = process.env.YAPI_CATID;
+    const envTemplateId = process.env.YAPI_TEMPLATE_ID;
+    if (!mapping.project_id && envProjectId)
+        mapping.project_id = Number(envProjectId);
+    if (!mapping.catid && envCatId)
+        mapping.catid = Number(envCatId);
+    if (!mapping.template_id && envTemplateId)
+        mapping.template_id = Number(envTemplateId);
+    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 } = 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;
+        const relName = path_1.default.basename(mdPath);
+        const apiPath = `/${stem}`;
+        const markdown = fs_1.default.readFileSync(mdPath, "utf8");
+        const desiredTitle = (0, markdown_1.extractFirstMarkdownH1Title)(markdown).trim() || stem;
+        let docId = mapping.files[relName];
+        if (!docId) {
+            docId = byPath[apiPath] || byTitle[desiredTitle] || byTitle[stem];
+            if (docId)
+                mapping.files[relName] = 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 = (0, utils_1.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);
+        const shouldSkipUnchanged = !options.force &&
+            docId &&
+            previousHash &&
+            previousHash === contentHash &&
+            !shouldSyncTitle;
+        if (shouldSkipUnchanged && !options.dryRun) {
+            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;
+            },
+            onDiagramError: () => {
+                diagramFailed = true;
+            },
+        });
+        if (shouldSkipUnchanged) {
+            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 http_1.HttpStatusError && error.status === 413) {
+                    throw new Error(buildDocsSyncPayloadTooLargeMessage(relName, preview, error));
+                }
+                throw error;
+            }
+        }
+        if (docId && !mermaidFailed && !diagramFailed) {
+            mapping.file_hashes[relName] = contentHash;
+        }
+        if (action !== "skip") {
+            updated += 1;
+        }
+    }
+    return { updated, created, skipped, previewOnly, files: fileInfos, previews };
+}
+async function fetchProjectInfo(projectId, baseUrl, request) {
+    if (!projectId)
+        return null;
+    const resp = await request("/api/project/get", "GET", { id: projectId });
+    if (resp?.errcode !== 0) {
+        throw new Error(`project get failed: ${resp?.errmsg || "unknown error"}`);
+    }
+    const data = resp?.data || {};
+    const name = typeof data.name === "string" ? data.name : "";
+    const basepath = typeof data.basepath === "string" ? data.basepath : "";
+    const envs = (0, utils_1.normalizeProjectEnvs)(data.env || data.envs);
+    return {
+        project_id: Number(projectId),
+        name,
+        basepath,
+        envs,
+        base_url: baseUrl,
+    };
+}
+function buildEnvUrls(projectInfo, apiPath) {
+    const urls = {};
+    if (!projectInfo || !projectInfo.envs || !projectInfo.envs.length)
+        return urls;
+    const basepath = projectInfo.basepath || "";
+    projectInfo.envs.forEach((env, index) => {
+        const rawKey = env.name || env.domain || `env${index + 1}`;
+        const url = (0, utils_1.buildEnvUrl)(env.domain, basepath, apiPath);
+        if (!url)
+            return;
+        let key = rawKey;
+        let suffix = 1;
+        while (urls[key]) {
+            suffix += 1;
+            key = `${rawKey}-${suffix}`;
+        }
+        urls[key] = url;
+    });
+    return urls;
+}
+async function updateDocsSyncCaches(homeDir, baseUrl, bindingResults, request) {
+    const linksConfig = loadDocsSyncLinks(homeDir);
+    const projectsConfig = loadDocsSyncProjects(homeDir);
+    const deploymentsConfig = loadDocsSyncDeployments(homeDir);
+    const projectCache = new Map();
+    const resolveProjectInfo = async (projectId) => {
+        if (!projectId)
+            return null;
+        if (projectCache.has(projectId))
+            return projectCache.get(projectId) || null;
+        const existing = projectsConfig.projects[String(projectId)] || null;
+        try {
+            const fresh = await fetchProjectInfo(projectId, baseUrl, request);
+            if (fresh) {
+                projectsConfig.projects[String(projectId)] = fresh;
+                projectCache.set(projectId, fresh);
+                return fresh;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`project get failed (project_id=${projectId}): ${message}`);
+        }
+        projectCache.set(projectId, existing);
+        return existing;
+    };
+    for (const [name, result] of Object.entries(bindingResults)) {
+        const binding = result.binding;
+        const projectId = Number(binding.project_id || 0);
+        const linkFiles = {};
+        const deploymentFiles = {};
+        const projectInfo = await resolveProjectInfo(projectId);
+        for (const [fileName, fileInfo] of Object.entries(result.files)) {
+            const docUrl = projectId ? (0, utils_1.buildInterfaceWebUrl)(baseUrl, projectId, fileInfo.docId) : "";
+            linkFiles[fileName] = {
+                doc_id: fileInfo.docId,
+                api_path: fileInfo.apiPath,
+                url: docUrl,
+            };
+            deploymentFiles[fileName] = {
+                api_path: fileInfo.apiPath,
+                env_urls: buildEnvUrls(projectInfo, fileInfo.apiPath),
+            };
+        }
+        linksConfig.bindings[name] = {
+            dir: binding.dir,
+            project_id: projectId || undefined,
+            catid: binding.catid,
+            files: linkFiles,
+        };
+        deploymentsConfig.bindings[name] = {
+            dir: binding.dir,
+            project_id: projectId || undefined,
+            files: deploymentFiles,
+        };
+    }
+    saveDocsSyncLinks(homeDir, linksConfig);
+    saveDocsSyncProjects(homeDir, projectsConfig);
+    saveDocsSyncDeployments(homeDir, deploymentsConfig);
+}
+async function runDocsSyncBindings(action, args) {
+    if (args.help) {
+        return 0;
+    }
+    const writeActions = new Set(["add", "update", "remove", "rm", "delete", "del"]);
+    const readActions = new Set(["list", "get"]);
+    if (!writeActions.has(action) && !readActions.has(action)) {
+        console.error(`unknown docs-sync bind action: ${action}`);
+        return 2;
+    }
+    const homeDir = resolveDocsSyncHome(process.cwd(), writeActions.has(action));
+    if (!homeDir) {
+        if (action === "list") {
+            console.log("no docs-sync bindings (missing .yapi/docs-sync.json)");
+            return 0;
+        }
+        console.error("missing .yapi/docs-sync.json (run in project root or create one with docs-sync bind add)");
+        return 2;
+    }
+    const rootDir = path_1.default.dirname(homeDir);
+    const config = loadDocsSyncConfig(homeDir);
+    if (action === "list") {
+        const entries = Object.entries(config.bindings).sort(([a], [b]) => a.localeCompare(b));
+        if (!entries.length) {
+            console.log("no docs-sync bindings");
+            return 0;
+        }
+        for (const [name, binding] of entries) {
+            const filesCount = binding.files ? Object.keys(binding.files).length : 0;
+            console.log(`${name} dir=${binding.dir} project_id=${binding.project_id ?? ""} catid=${binding.catid ?? ""}` +
+                (binding.template_id ? ` template_id=${binding.template_id}` : "") +
+                ` files=${filesCount}`);
+        }
+        return 0;
+    }
+    if (!args.name) {
+        console.error("missing --name for docs-sync bind action");
+        return 2;
+    }
+    if (action === "get") {
+        const binding = config.bindings[args.name];
+        if (!binding) {
+            console.error(`binding not found: ${args.name}`);
+            return 2;
+        }
+        console.log(JSON.stringify(binding, null, 2));
+        return 0;
+    }
+    if (action === "remove" || action === "rm" || action === "delete" || action === "del") {
+        if (!config.bindings[args.name]) {
+            console.error(`binding not found: ${args.name}`);
+            return 2;
+        }
+        delete config.bindings[args.name];
+        saveDocsSyncConfig(homeDir, config);
+        console.log(`binding removed: ${args.name}`);
+        return 0;
+    }
+    const hasExisting = Boolean(config.bindings[args.name]);
+    if (action === "add" && hasExisting) {
+        console.error(`binding already exists: ${args.name}`);
+        return 2;
+    }
+    if (action === "update" && !hasExisting) {
+        console.error(`binding not found: ${args.name}`);
+        return 2;
+    }
+    if (action === "add") {
+        if (!args.dir ||
+            !Number.isFinite(args.projectId ?? NaN) ||
+            !Number.isFinite(args.catId ?? NaN)) {
+            console.error("add requires --dir, --project-id, and --catid");
+            return 2;
+        }
+    }
+    const existing = config.bindings[args.name] || {};
+    const next = {
+        dir: existing.dir || "",
+        project_id: existing.project_id,
+        catid: existing.catid,
+        template_id: existing.template_id,
+        source_files: existing.source_files ? [...existing.source_files] : undefined,
+        files: existing.files ? { ...existing.files } : {},
+        file_hashes: existing.file_hashes ? { ...existing.file_hashes } : {},
+    };
+    if (args.dir) {
+        next.dir = normalizeBindingDirForContext(homeDir, rootDir, process.cwd(), args.dir);
+    }
+    if (args.projectId !== undefined && Number.isFinite(args.projectId)) {
+        next.project_id = Number(args.projectId);
+    }
+    if (args.catId !== undefined && Number.isFinite(args.catId)) {
+        next.catid = Number(args.catId);
+    }
+    if (args.templateId !== undefined && Number.isFinite(args.templateId)) {
+        next.template_id = Number(args.templateId);
+    }
+    if (args.clearSourceFiles) {
+        next.source_files = [];
+    }
+    else if (args.sourceFiles && args.sourceFiles.length) {
+        next.source_files = args.sourceFiles;
+    }
+    if (!next.dir || !next.project_id || !next.catid) {
+        console.error("binding requires dir/project_id/catid");
+        return 2;
+    }
+    config.bindings[args.name] = next;
+    saveDocsSyncConfig(homeDir, config);
+    const resolvedDir = resolveBindingDirForContext(homeDir, rootDir, process.cwd(), next.dir);
+    console.log(`${action === "add" ? "binding added" : "binding updated"}: ${args.name}`);
+    console.log(`stored_dir=${next.dir}`);
+    console.log(`resolved_dir=${resolvedDir}`);
+    const gitRoot = (0, utils_1.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(options) {
+    try {
+        if (!(0, markdown_1.isPandocAvailable)()) {
+            console.warn("pandoc not found, fallback to markdown-it renderer.");
+            console.warn("Install pandoc (macOS): brew install pandoc");
+            console.warn("More info: https://pandoc.org/installing.html");
+        }
+        if (!options.noMermaid && !(0, markdown_1.isMmdcAvailable)()) {
+            console.warn("mmdc not found, Mermaid blocks will stay as code.");
+            console.warn("Install mermaid-cli: npm i -g @mermaid-js/mermaid-cli");
+        }
+        if (!(0, markdown_1.isPlantUmlAvailable)()) {
+            console.warn("plantuml not found, PlantUML blocks will be removed from HTML.");
+            console.warn("Install PlantUML (macOS): brew install plantuml");
+        }
+        if (!(0, markdown_1.isGraphvizAvailable)()) {
+            console.warn("graphviz (dot) not found, Graphviz blocks will be removed from HTML.");
+            console.warn("Install Graphviz (macOS): brew install graphviz");
+        }
+        if (!(0, markdown_1.isD2Available)()) {
+            console.warn("d2 not found, D2 blocks will be removed from HTML.");
+            console.warn("Install D2 (macOS): brew install d2");
+        }
+        if (options.bindings.length && options.dirs.length) {
+            console.error("use --binding or --dir, not both");
+            return 2;
+        }
+        const docsSyncHome = resolveDocsSyncHome(process.cwd(), false);
+        const docsSyncConfig = docsSyncHome ? loadDocsSyncConfig(docsSyncHome) : null;
+        let bindingNames = options.bindings;
+        let useBindings = bindingNames.length > 0;
+        if (!useBindings &&
+            !options.dirs.length &&
+            docsSyncConfig &&
+            Object.keys(docsSyncConfig.bindings).length) {
+            useBindings = true;
+            bindingNames = Object.keys(docsSyncConfig.bindings);
+        }
+        if (useBindings && (!docsSyncHome || !docsSyncConfig)) {
+            console.error("missing .yapi/docs-sync.json (run docs-sync bind add or use --dir)");
+            return 2;
+        }
+        if (useBindings && !bindingNames.length) {
+            console.error("no docs-sync bindings found (run docs-sync bind add or use --dir)");
+            return 2;
+        }
+        const usingDefaultDir = !useBindings && !options.dirs.length;
+        const dirs = useBindings ? [] : options.dirs.length ? options.dirs : ["docs/release-notes"];
+        if (!useBindings) {
+            const missingDirs = dirs.filter((dir) => {
+                const dirPath = path_1.default.resolve(dir);
+                return !fs_1.default.existsSync(dirPath) || !fs_1.default.statSync(dirPath).isDirectory();
+            });
+            if (missingDirs.length) {
+                const firstMissing = path_1.default.resolve(missingDirs[0]);
+                console.error(`dir not found: ${firstMissing}`);
+                if (usingDefaultDir) {
+                    const suggestion = suggestDocsSyncDir(process.cwd());
+                    if (suggestion) {
+                        console.error(`hint: pass --dir ${suggestion}`);
+                    }
+                    console.error("hint: or bind a directory with yapi docs-sync bind add");
+                }
+                else {
+                    console.error("hint: pass --dir <existing_dir> or bind a directory");
+                }
+                return 2;
+            }
+        }
+        let config = {};
+        let configPath = options.config || "";
+        if (options.config) {
+            if (fs_1.default.existsSync(configPath)) {
+                config = (0, utils_1.parseSimpleToml)(fs_1.default.readFileSync(configPath, "utf8"));
+            }
+            else {
+                const init = await (0, utils_1.initConfigIfMissing)(options);
+                if (init) {
+                    config = init.config;
+                    configPath = init.configPath;
+                }
+                else {
+                    console.error(`missing config file: ${configPath}`);
+                    return 2;
+                }
+            }
+        }
+        else {
+            const globalPath = (0, utils_1.globalConfigPath)();
+            if (fs_1.default.existsSync(globalPath)) {
+                configPath = globalPath;
+                config = (0, utils_1.parseSimpleToml)(fs_1.default.readFileSync(globalPath, "utf8"));
+            }
+            else {
+                const init = await (0, utils_1.initConfigIfMissing)(options);
+                if (init) {
+                    config = init.config;
+                    configPath = init.configPath;
+                }
+                else {
+                    console.error("missing config: create ~/.yapi/config.toml or pass --config");
+                    return 2;
+                }
+            }
+        }
+        const baseUrl = options.baseUrl || config.base_url || "";
+        if (!baseUrl) {
+            console.error("missing --base-url or config base_url");
+            return 2;
+        }
+        const projectId = options.projectId || config.project_id || "";
+        const rawToken = options.token || config.token || "";
+        const token = (0, utils_1.resolveToken)(rawToken, projectId);
+        let authMode = (options.authMode || config.auth_mode || "").trim().toLowerCase();
+        if (!authMode) {
+            authMode = token
+                ? "token"
+                : options.email || options.password || config.email || config.password
+                    ? "global"
+                    : "token";
+        }
+        if (authMode !== "token" && authMode !== "global") {
+            console.error("invalid --auth-mode (use token or global)");
+            return 2;
+        }
+        const headers = {};
+        const email = options.email || config.email || "";
+        const password = options.password || config.password || "";
+        const authService = authMode === "global"
+            ? new auth_1.YApiAuthService(baseUrl, email || "", password || "", "warn", {
+                timeoutMs: options.timeout || 30000,
+            })
+            : null;
+        const canRelogin = authMode === "global" &&
+            Boolean(authService) &&
+            Boolean(email) &&
+            Boolean(password) &&
+            !options.cookie;
+        if (options.cookie) {
+            headers.Cookie = options.cookie;
+        }
+        else if (authMode === "global") {
+            const cachedCookie = authService?.getCachedCookieHeader();
+            if (cachedCookie) {
+                headers.Cookie = cachedCookie;
+            }
+            else if (email && password && authService) {
+                try {
+                    headers.Cookie = await authService.getCookieHeaderWithLogin();
+                }
+                catch (error) {
+                    console.error(error instanceof Error ? error.message : String(error));
+                    return 2;
+                }
+            }
+            else {
+                console.error("missing email/password for global auth");
+                return 2;
+            }
+        }
+        const request = async (endpoint, method, query = {}, data) => {
+            const queryItems = [];
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null) {
+                    queryItems.push([key, String(value)]);
+                }
+            }
+            const url = (0, http_1.buildUrl)(baseUrl, endpoint, queryItems, authMode === "token" ? token : "", options.tokenParam || "token");
+            let body;
+            if (data !== undefined) {
+                body = JSON.stringify(data);
+            }
+            const sendOnce = async () => {
+                const requestHeaders = { ...headers };
+                if (body !== undefined) {
+                    requestHeaders["Content-Type"] = "application/json;charset=UTF-8";
+                }
+                const response = await (0, http_1.fetchWithTimeout)(url, {
+                    method,
+                    headers: requestHeaders,
+                    body,
+                }, options.timeout || 30000);
+                const text = await response.text();
+                return { response, text, json: (0, utils_1.parseJsonMaybe)(text) };
+            };
+            let result = await sendOnce();
+            if (canRelogin && (0, utils_1.looksLikeAuthError)(result.response.status, result.json)) {
+                try {
+                    headers.Cookie = await authService.getCookieHeaderWithLogin({ forceLogin: true });
+                }
+                catch (error) {
+                    throw new Error(error instanceof Error ? error.message : String(error));
+                }
+                result = await sendOnce();
+            }
+            if (!result.response.ok) {
+                throw new http_1.HttpStatusError(endpoint, result.response.status, result.response.statusText, result.text);
+            }
+            if (!result.json) {
+                throw new Error(`invalid JSON response from ${endpoint}`);
+            }
+            return result.json;
+        };
+        if (useBindings) {
+            const rootDir = path_1.default.dirname(docsSyncHome);
+            const configForBindings = docsSyncConfig;
+            const dirToBindings = new Map();
+            for (const name of bindingNames) {
+                const binding = configForBindings.bindings[name];
+                if (!binding) {
+                    throw new Error(`binding not found: ${name}`);
+                }
+                const dirPath = resolveBindingDirForContext(docsSyncHome, rootDir, process.cwd(), binding.dir);
+                const existing = dirToBindings.get(dirPath) || [];
+                existing.push(name);
+                dirToBindings.set(dirPath, existing);
+            }
+            const duplicates = Array.from(dirToBindings.entries()).filter(([, names]) => names.length > 1);
+            if (duplicates.length) {
+                const lines = [];
+                lines.push("invalid docs-sync bindings: multiple bindings share the same dir");
+                duplicates.forEach(([dirPath, names]) => {
+                    lines.push(`- dir=${dirPath} bindings=${names.join(", ")}`);
+                });
+                lines.push("");
+                lines.push("Fix: split docs into separate directories (recommended).");
+                lines.push("Example:");
+                lines.push("  yapi docs-sync bind update --name <bindingA> --dir docs/yapi-sync/<bindingA>");
+                lines.push("  yapi docs-sync bind update --name <bindingB> --dir docs/yapi-sync/<bindingB>");
+                throw new Error(lines.join("\n"));
+            }
+            const bindingResults = {};
+            for (const name of bindingNames) {
+                const binding = configForBindings.bindings[name];
+                if (!binding) {
+                    throw new Error(`binding not found: ${name}`);
+                }
+                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);
+                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) {
+                saveDocsSyncConfig(docsSyncHome, configForBindings);
+                await updateDocsSyncCaches(docsSyncHome, baseUrl, bindingResults, request);
+            }
+        }
+        else {
+            for (const dir of dirs) {
+                const dirPath = path_1.default.resolve(dir);
+                if (!fs_1.default.existsSync(dirPath) || !fs_1.default.statSync(dirPath).isDirectory()) {
+                    throw new Error(`dir not found: ${dirPath}`);
+                }
+                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} preview_only=${result.previewOnly} dir=${dirPath}`);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+}
+//# sourceMappingURL=docs-sync.js.map