@leeguoo/yapi-mcp 0.3.22 → 0.3.24

package/dist/yapi-cli.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
@@ -12,12 +13,38 @@ const readline_1 = __importDefault(require("readline"));
 const markdown_1 = require("./docs/markdown");
 const install_1 = require("./skill/install");
 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");
@@ -32,6 +59,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 "";
@@ -122,6 +201,162 @@ function resolveToken(tokenValue, projectId) {
     }
     return tokenValue;
 }
+function resolveLocalBin(binName) {
+    const baseName = process.platform === "win32" ? `${binName}.cmd` : binName;
+    const localBin = path_1.default.resolve(__dirname, "..", "node_modules", ".bin", baseName);
+    if (fs_1.default.existsSync(localBin))
+        return localBin;
+    return binName;
+}
+function parseJsonLoose(text) {
+    const raw = String(text || "").trim();
+    if (!raw)
+        return null;
+    const direct = parseJsonMaybe(raw);
+    if (direct !== null)
+        return direct;
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const parsed = parseJsonMaybe(lines[i]);
+        if (parsed !== null)
+            return parsed;
+    }
+    const firstBrace = raw.indexOf("{");
+    const firstBracket = raw.indexOf("[");
+    const starts = [firstBrace, firstBracket].filter((n) => n >= 0);
+    if (!starts.length)
+        return null;
+    const start = Math.min(...starts);
+    const lastBrace = raw.lastIndexOf("}");
+    const lastBracket = raw.lastIndexOf("]");
+    const end = Math.max(lastBrace, lastBracket);
+    if (end <= start)
+        return null;
+    const sliced = raw.slice(start, end + 1);
+    return parseJsonMaybe(sliced);
+}
+function extractCookiesFromPayload(payload) {
+    const queue = [payload];
+    const visited = new Set();
+    while (queue.length) {
+        const current = queue.shift();
+        if (current === null || current === undefined)
+            continue;
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        if (Array.isArray(current)) {
+            if (current.every((item) => item && typeof item === "object")) {
+                return current;
+            }
+            continue;
+        }
+        if (typeof current !== "object")
+            continue;
+        const obj = current;
+        if (Array.isArray(obj.cookies))
+            return obj.cookies;
+        if (Array.isArray(obj.data))
+            return obj.data;
+        if (obj.data && typeof obj.data === "object")
+            queue.push(obj.data);
+        if (obj.result && typeof obj.result === "object")
+            queue.push(obj.result);
+        if (obj.payload && typeof obj.payload === "object")
+            queue.push(obj.payload);
+    }
+    return [];
+}
+function normalizeCookieExpiresMs(raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return n > 1_000_000_000_000 ? n : n * 1000;
+}
+function runAgentBrowser(args, options = {}) {
+    const bins = [
+        resolveLocalBin("agent-browser-stealth"),
+        resolveLocalBin("agent-browser"),
+        "agent-browser-stealth",
+        "agent-browser",
+    ];
+    const uniq = Array.from(new Set(bins));
+    let lastError = null;
+    for (const bin of uniq) {
+        try {
+            if (options.captureOutput) {
+                const output = (0, child_process_1.execFileSync)(bin, args, {
+                    encoding: "utf8",
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                return String(output || "");
+            }
+            (0, child_process_1.execFileSync)(bin, args, { stdio: "inherit" });
+            return "";
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                lastError = error;
+                continue;
+            }
+            if (options.ignoreError)
+                return "";
+            throw error;
+        }
+    }
+    if (lastError?.code === "ENOENT") {
+        throw new Error("未找到 agent-browser-stealth。请先执行: pnpm -C packages/yapi-mcp add agent-browser-stealth && pnpm -C packages/yapi-mcp exec agent-browser-stealth install");
+    }
+    throw new Error("启动 agent-browser-stealth 失败");
+}
+async function loginByBrowserAndReadCookie(baseUrl, loginUrlOption) {
+    const normalizedBase = String(baseUrl || "").replace(/\/+$/, "");
+    const defaultLoginUrl = normalizedBase;
+    let loginUrl = String(loginUrlOption || "").trim();
+    if (!loginUrl) {
+        const answer = await promptText(`YApi page URL [${defaultLoginUrl}]: `);
+        loginUrl = answer.trim() || defaultLoginUrl;
+    }
+    try {
+        const parsed = new URL(loginUrl);
+        loginUrl = parsed.toString();
+    }
+    catch {
+        throw new Error(`invalid login url: ${loginUrl}`);
+    }
+    const sessionName = `yapi-login-${Date.now()}-${crypto_1.default.randomBytes(4).toString("hex")}`;
+    console.log(`opening browser for login: ${loginUrl}`);
+    console.log(`browser session name: ${sessionName}`);
+    runAgentBrowser(["open", loginUrl, "--headed", "--session-name", sessionName]);
+    await promptText("请在浏览器完成登录，然后按回车继续...");
+    let cookies = [];
+    try {
+        const output = runAgentBrowser(["cookies", "--json", "--session-name", sessionName], {
+            captureOutput: true,
+        });
+        const payload = parseJsonLoose(output);
+        cookies = extractCookiesFromPayload(payload);
+    }
+    finally {
+        runAgentBrowser(["close", "--session-name", sessionName], { ignoreError: true });
+    }
+    if (!cookies.length) {
+        throw new Error(`未读取到浏览器 cookie。请确认登录完成后再回车；如果仍失败，请先自检:\nagent-browser-stealth cookies --json --session-name ${sessionName}`);
+    }
+    const tokenCookie = cookies.find((item) => String(item?.name || "") === "_yapi_token");
+    const uidCookie = cookies.find((item) => String(item?.name || "") === "_yapi_uid");
+    const yapiToken = String(tokenCookie?.value || "").trim();
+    if (!yapiToken) {
+        throw new Error("未找到 _yapi_token，请确认登录站点是目标 YApi 域名");
+    }
+    const yapiUid = String(uidCookie?.value || "").trim() || undefined;
+    const expiresAt = normalizeCookieExpiresMs(tokenCookie?.expiresAt) ?? normalizeCookieExpiresMs(tokenCookie?.expires);
+    return { yapiToken, yapiUid, expiresAt };
+}
 async function fetchWithTimeout(url, options, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -184,6 +419,14 @@ function parseArgs(argv) {
             options.baseUrl = arg.slice(11);
             continue;
         }
+        if (arg === "--login-url") {
+            options.loginUrl = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--login-url=")) {
+            options.loginUrl = arg.slice(12);
+            continue;
+        }
         if (arg === "--token") {
             options.token = argv[++i];
             continue;
@@ -208,6 +451,10 @@ function parseArgs(argv) {
             options.authMode = arg.slice(12);
             continue;
         }
+        if (arg === "--browser") {
+            options.browser = true;
+            continue;
+        }
         if (arg === "--email") {
             options.email = argv[++i];
             continue;
@@ -640,6 +887,7 @@ function usage() {
         "  yapi docs-sync [options] [dir...]",
         "  yapi docs-sync bind <action> [options]",
         "  yapi login [options]",
+        "  yapi logout [options]",
         "  yapi whoami [options]",
         "  yapi search [options]",
         "  yapi install-skill [options]",
@@ -740,12 +988,24 @@ function loginUsage() {
         "Options:",
         "  --config <path>        config file path (default: ~/.yapi/config.toml)",
         "  --base-url <url>       YApi base URL",
+        "  --login-url <url>      page URL for browser login (default: <base-url>)",
+        "  --browser              force browser login and cookie sync",
         "  --email <email>        login email for global mode",
         "  --password <pwd>       login password for global mode",
         "  --timeout <ms>         request timeout in ms",
         "  -h, --help             show help",
     ].join("\n");
 }
+function logoutUsage() {
+    return [
+        "Usage:",
+        "  yapi logout [options]",
+        "Options:",
+        "  --config <path>        config file path (default: ~/.yapi/config.toml)",
+        "  --base-url <url>       YApi base URL",
+        "  -h, --help             show help",
+    ].join("\n");
+}
 function whoamiUsage() {
     return [
         "Usage:",
@@ -1141,6 +1401,8 @@ async function runLogin(rawArgs) {
     let baseUrl = options.baseUrl || config.base_url || "";
     let email = options.email || config.email || "";
     let password = options.password || config.password || "";
+    const projectId = options.projectId || config.project_id || "";
+    const token = options.token || config.token || "";
     let updated = false;
     if (!baseUrl) {
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -1150,21 +1412,50 @@ async function runLogin(rawArgs) {
         baseUrl = await promptRequired("YApi base URL: ", false);
         updated = true;
     }
-    if (!email) {
+    const useBrowserLogin = Boolean(options.browser) || !email || !password;
+    if (useBrowserLogin) {
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
-            console.error("missing --email or config email");
+            console.error("browser login requires interactive terminal");
             return 2;
         }
-        email = await promptRequired("YApi email: ", false);
-        updated = true;
-    }
-    if (!password) {
-        if (!process.stdin.isTTY || !process.stdout.isTTY) {
-            console.error("missing --password or config password");
+        try {
+            const session = await loginByBrowserAndReadCookie(baseUrl, options.loginUrl);
+            const cache = new authCache_1.YApiAuthCache(baseUrl, "warn");
+            cache.saveSession({
+                yapiToken: session.yapiToken,
+                yapiUid: session.yapiUid,
+                expiresAt: session.expiresAt,
+                updatedAt: Date.now(),
+            });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
             return 2;
         }
-        password = await promptRequired("YApi password: ", true);
-        updated = true;
+        const shouldWriteConfig = updated || !fs_1.default.existsSync(configPath) || config.auth_mode !== "global";
+        if (shouldWriteConfig) {
+            const mergedConfig = {
+                base_url: baseUrl,
+                auth_mode: "global",
+                email,
+                password,
+                token,
+                project_id: projectId,
+            };
+            writeConfig(configPath, mergedConfig);
+        }
+        console.log("login success (cookie synced from browser to ~/.yapi-mcp/auth-*.json)");
+        return 0;
+    }
+    try {
+        const authService = new auth_1.YApiAuthService(baseUrl, email, password, "warn", {
+            timeoutMs: options.timeout || 30000,
+        });
+        await authService.getCookieHeaderWithLogin({ forceLogin: true });
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
     }
     const shouldWriteConfig = updated || !fs_1.default.existsSync(configPath) || config.auth_mode !== "global";
     if (shouldWriteConfig) {
@@ -1173,22 +1464,36 @@ async function runLogin(rawArgs) {
             auth_mode: "global",
             email,
             password,
-            token: options.token || config.token || "",
-            project_id: options.projectId || config.project_id || "",
+            token,
+            project_id: projectId,
         };
         writeConfig(configPath, mergedConfig);
     }
-    try {
-        const authService = new auth_1.YApiAuthService(baseUrl, email, password, "warn", {
-            timeoutMs: options.timeout || 30000,
-        });
-        await authService.getCookieHeaderWithLogin({ forceLogin: true });
+    console.log("login success (cookie cached in ~/.yapi-mcp/auth-*.json)");
+    return 0;
+}
+async function runLogout(rawArgs) {
+    const options = parseArgs(rawArgs);
+    if (options.help) {
+        console.log(logoutUsage());
+        return 0;
     }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
+    if (options.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    const configPath = options.config || globalConfigPath();
+    const config = fs_1.default.existsSync(configPath)
+        ? parseSimpleToml(fs_1.default.readFileSync(configPath, "utf8"))
+        : {};
+    const baseUrl = options.baseUrl || config.base_url || "";
+    if (!baseUrl) {
+        console.error("missing --base-url or config base_url");
         return 2;
     }
-    console.log("login success (cookie cached in ~/.yapi-mcp/auth-*.json)");
+    const cache = new authCache_1.YApiAuthCache(baseUrl, "warn");
+    cache.clearSession();
+    console.log("logout success (session cleared from ~/.yapi-mcp/auth-*.json)");
     return 0;
 }
 async function runWhoami(rawArgs) {
@@ -1477,6 +1782,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");
 }
@@ -1591,6 +1910,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) {
@@ -1868,6 +2225,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);
@@ -1894,10 +2304,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"}`);
@@ -1919,14 +2326,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;
@@ -1940,43 +2352,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;
             },
@@ -1984,15 +2387,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 = {};
@@ -2167,7 +2611,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);
@@ -2190,7 +2634,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) {
@@ -2398,7 +2852,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}`);
@@ -2414,7 +2868,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);
@@ -2439,12 +2893,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) {
@@ -2460,10 +2918,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;
@@ -2489,6 +2951,9 @@ async function main() {
     if (rawArgs[0] === "login") {
         return await runLogin(rawArgs.slice(1));
     }
+    if (rawArgs[0] === "logout") {
+        return await runLogout(rawArgs.slice(1));
+    }
     if (rawArgs[0] === "whoami") {
         return await runWhoami(rawArgs.slice(1));
     }
@@ -2631,7 +3096,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;