@aigne/doc-smith 0.8.13 → 0.8.14-beta.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.8.14-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta...v0.8.14-beta.1) (2025-10-17)
+
+
+### Bug Fixes
+
+* doc review and update ([#199](https://github.com/AIGNE-io/aigne-doc-smith/issues/199)) ([0061323](https://github.com/AIGNE-io/aigne-doc-smith/commit/006132345a17a7fae10a803656b731144ecc54c9))
+* respect env vars for publish and improve reliability ([#204](https://github.com/AIGNE-io/aigne-doc-smith/issues/204)) ([bd14c2a](https://github.com/AIGNE-io/aigne-doc-smith/commit/bd14c2af54ebca89c8edb5861e3b1a6e3f76e92e))
+
+## [0.8.14-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.13...v0.8.14-beta) (2025-10-16)
+
+
+### Features
+
+* **file-utils:** add comprehensive file type detection and image upload functionality ([#200](https://github.com/AIGNE-io/aigne-doc-smith/issues/200)) ([ab7aae3](https://github.com/AIGNE-io/aigne-doc-smith/commit/ab7aae33ed9b5209e824ba91fbf9c94d37187d83))
+
+
+### Bug Fixes
+
+* use `output` field present tool result to enhance LLM understanding ([#202](https://github.com/AIGNE-io/aigne-doc-smith/issues/202)) ([511178d](https://github.com/AIGNE-io/aigne-doc-smith/commit/511178de7a88fdecf2136f90035d87957e23b23f))
+
 ## [0.8.13](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.13-beta...v0.8.13) (2025-10-16)
 
 

package/agents/publish/publish-docs.mjs

@@ -1,9 +1,8 @@
-import { basename, extname, join } from "node:path";
+import { basename, join } from "node:path";
 import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import { BrokerClient } from "@blocklet/payment-broker-client/node";
 import chalk from "chalk";
 import fs from "fs-extra";
-import slugify from "slugify";
 
 import { getAccessToken, getOfficialAccessToken } from "../../utils/auth-utils.mjs";
 import {
@@ -15,8 +14,6 @@ import {
 } from "../../utils/constants/index.mjs";
 import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
 import { deploy } from "../../utils/deploy.mjs";
-import { getExtnameFromContentType } from "../../utils/file-utils.mjs";
-import { uploadFiles } from "../../utils/upload-files.mjs";
 import {
   getGithubRepoUrl,
   isHttp,
@@ -24,6 +21,7 @@ import {
   saveValueToConfig,
 } from "../../utils/utils.mjs";
 import updateBranding from "../utils/update-branding.mjs";
+import { downloadAndUploadImage } from "../../utils/file-utils.mjs";
 
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 
@@ -59,29 +57,27 @@ export default async function publishDocs(
 
     // ----------------- main publish process flow -----------------------------
     // Check if DOC_DISCUSS_KIT_URL is set in environment variables
-    const envAppUrl = process.env.DOC_DISCUSS_KIT_URL;
-    const useEnvAppUrl = !!envAppUrl;
-
-    // Use environment variable if available, otherwise use the provided appUrl
-    if (useEnvAppUrl) {
-      appUrl = envAppUrl;
-    }
+    const useEnvAppUrl = !!(process.env.DOC_DISCUSS_KIT_URL || appUrl);
 
     // Check if appUrl is default and not saved in config (only when not using env variable)
     const config = await loadConfigFromFile();
-    const isDefaultAppUrl = appUrl === CLOUD_SERVICE_URL_PROD;
-    const hasAppUrlInConfig = config?.appUrl;
+    appUrl = process.env.DOC_DISCUSS_KIT_URL || appUrl || config?.appUrl;
+    const hasInputAppUrl = !!appUrl;
 
+    let shouldSyncBranding = void 0;
     let token = "";
+    let client = null;
+    let authToken = null;
+    let sessionId = null;
 
-    if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
-      const authToken = await getOfficialAccessToken(BASE_URL, false);
+    if (!hasInputAppUrl) {
+      authToken = await getOfficialAccessToken(BASE_URL, false);
 
-      let sessionId = "";
+      sessionId = "";
       let paymentLink = "";
 
       if (authToken) {
-        const client = new BrokerClient({ baseUrl: BASE_URL, authToken });
+        client = new BrokerClient({ baseUrl: BASE_URL, authToken });
         const info = await client.checkCacheSession({
           needShortUrl: true,
           sessionId: config?.checkoutId,
@@ -137,29 +133,60 @@ export default async function publishDocs(
         // Ensure appUrl has protocol
         appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
       } else if (["new-instance", "new-instance-continue"].includes(choice)) {
-        if (options?.prompts?.confirm) {
-          shouldWithBranding = await options.prompts.confirm({
-            message: "Would you like to update the project branding (title, description, logo)?",
-            default: true,
-          });
-        }
-        // Deploy a new Discuss Kit service
-        let id = "";
-        let paymentUrl = "";
+        // resume previous website setup
         if (choice === "new-instance-continue") {
-          id = sessionId;
-          paymentUrl = paymentLink;
-          console.log(`\nResuming your previous website setup...`);
-        } else {
-          console.log(`\nCreating a new website for your documentation...`);
+          shouldSyncBranding = config?.shouldSyncBranding ?? void 0;
+          if (shouldSyncBranding !== void 0) {
+            shouldWithBranding = shouldWithBranding ?? shouldSyncBranding;
+          }
         }
-        const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentUrl)) || {};
 
-        appUrl = homeUrl;
-        token = ltToken;
+        if (options?.prompts?.confirm) {
+          if (shouldSyncBranding === void 0) {
+            shouldSyncBranding = await options.prompts.confirm({
+              message: "Would you like to update the project branding (title, description, logo)?",
+              default: true,
+            });
+            await saveValueToConfig(
+              "shouldSyncBranding",
+              shouldSyncBranding,
+              "Should sync branding for documentation",
+            );
+            shouldWithBranding = shouldSyncBranding;
+          } else {
+            console.log(
+              `Would you like to update the project branding (title, description, logo)? ${chalk.cyan(shouldSyncBranding ? "Yes" : "No")}`,
+            );
+          }
+        }
+
+        try {
+          let id = "";
+          if (choice === "new-instance-continue") {
+            id = sessionId;
+            console.log(`\nResuming your previous website setup...`);
+          } else {
+            console.log(`\nCreating a new website for your documentation...`);
+          }
+          const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentLink)) || {};
+
+          appUrl = homeUrl;
+          token = ltToken;
+        } catch (error) {
+          const errorMsg = error?.message || "Unknown error occurred";
+          return { message: `${chalk.red("❌ Failed to create website:")} ${errorMsg}` };
+        }
       }
     }
 
+    if (sessionId) {
+      authToken = await getOfficialAccessToken(BASE_URL, false);
+      client = client || new BrokerClient({ baseUrl: BASE_URL, authToken });
+
+      const { vendors } = await client.getSessionDetail(sessionId, false);
+      token = vendors?.find((vendor) => vendor.vendorType === "launcher" && vendor.token)?.token;
+    }
+
     console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
 
     const accessToken = await getAccessToken(appUrl, token);
@@ -175,46 +202,22 @@ export default async function publishDocs(
       description: projectDesc || config?.projectDesc || "",
       icon: projectLogo || config?.projectLogo || "",
     };
+    let finalPath = null;
 
     // Handle project logo download if it's a URL
     if (projectInfo.icon && isHttp(projectInfo.icon)) {
-      const tempFilePath = join(docsDir, slugify(basename(projectInfo.icon)));
-      const initialExt = extname(projectInfo.icon);
-      let ext = initialExt;
-
-      try {
-        const response = await fetch(projectInfo.icon);
-        const blob = await response.blob();
-        const arrayBuffer = await blob.arrayBuffer();
-        const buffer = Buffer.from(arrayBuffer);
-
-        if (response.ok) {
-          if (!ext) {
-            const contentType = response.headers.get("content-type");
-            ext = getExtnameFromContentType(contentType);
-          }
-
-          const finalPath = ext ? `${tempFilePath}.${ext}` : tempFilePath;
-          fs.writeFileSync(finalPath, buffer);
-
-          const filePath = join(process.cwd(), finalPath);
-          const { results: uploadResults } = await uploadFiles({
-            appUrl,
-            filePaths: [filePath],
-            accessToken,
-            concurrency: 1,
-          });
-
-          // FIXME: 暂时保持使用绝对路径，需要修改为相对路径 @pengfei
-          projectInfo.icon = uploadResults?.[0]?.url || projectInfo.icon;
-        }
-      } catch (error) {
-        console.warn(`Failed to download project logo from ${projectInfo.icon}: ${error.message}`);
-      }
+      const { url: uploadedImageUrl, downloadFinalPath } = await downloadAndUploadImage(
+        projectInfo.icon,
+        docsDir,
+        appUrl,
+        accessToken,
+      );
+      projectInfo.icon = uploadedImageUrl;
+      finalPath = downloadFinalPath;
     }
 
     if (shouldWithBranding) {
-      updateBranding({ appUrl, projectInfo, accessToken });
+      updateBranding({ appUrl, projectInfo, accessToken, finalPath });
     }
 
     // Construct boardMeta object
@@ -263,6 +266,7 @@ export default async function publishDocs(
       }
       message = `✅ Documentation published successfully!`;
       await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+      await saveValueToConfig("shouldSyncBranding", "", "Should sync branding for documentation");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
       if (error?.includes("401") || error?.includes("403")) {
@@ -297,7 +301,6 @@ publishDocs.input_schema = {
     appUrl: {
       type: "string",
       description: "The URL of the app.",
-      default: CLOUD_SERVICE_URL_PROD,
     },
     boardId: {
       type: "string",

package/agents/utils/update-branding.mjs

@@ -1,5 +1,4 @@
 import { stat } from "node:fs/promises";
-import { resolve } from "node:path";
 import chalk from "chalk";
 import { joinURL } from "ufo";
 
@@ -8,12 +7,11 @@ import {
   CLOUD_SERVICE_URL_PROD,
   CLOUD_SERVICE_URL_STAGING,
   DISCUSS_KIT_DID,
-  DOC_SMITH_DIR,
 } from "../../utils/constants/index.mjs";
 import { requestWithAuthToken } from "../../utils/request.mjs";
 import { uploadFiles } from "../../utils/upload-files.mjs";
 
-export default async function updateBranding({ appUrl, projectInfo, accessToken }) {
+export default async function updateBranding({ appUrl, projectInfo, accessToken, finalPath }) {
   try {
     const origin = new URL(appUrl).origin;
     if ([CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(origin)) {
@@ -27,6 +25,18 @@ export default async function updateBranding({ appUrl, projectInfo, accessToken
     const componentInfo = await getComponentInfoWithMountPoint(origin, DISCUSS_KIT_DID);
     const mountPoint = componentInfo.mountPoint || "/";
 
+    if (projectInfo.name.length > 40) {
+      console.warn(
+        `⚠️ Name is too long, it should be less than 40 characters\nWill be truncated to 40 characters`,
+      );
+    }
+
+    if (projectInfo.description.length > 160) {
+      console.warn(
+        `⚠️ Description is too long, it should be less than 160 characters\nWill be truncated to 160 characters`,
+      );
+    }
+
     const res = await requestWithAuthToken(
       joinURL(origin, mountPoint, "/api/branding"),
       {
@@ -35,23 +45,27 @@ export default async function updateBranding({ appUrl, projectInfo, accessToken
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          appName: projectInfo.name,
-          appDescription: projectInfo.description,
+          appName: projectInfo.name.slice(0, 40),
+          appDescription: projectInfo.description.slice(0, 160),
         }),
       },
       accessToken,
     );
 
     if (res.success) {
+      if (!finalPath) {
+        console.warn("\n🔄 Skipped updating branding for missing logo file\n");
+        return;
+      }
+
       try {
-        const projectLogoPath = resolve(process.cwd(), DOC_SMITH_DIR, projectInfo.icon);
-        const projectLogoStat = await stat(projectLogoPath);
+        const projectLogoStat = await stat(finalPath);
 
         if (projectLogoStat.isFile()) {
           // Upload to blocklet logo endpoint
           await uploadFiles({
             appUrl: origin,
-            filePaths: [projectLogoPath],
+            filePaths: [finalPath],
             accessToken,
             concurrency: 1,
             endpoint: `${origin}/.well-known/service/blocklet/logo/upload/square/${componentInfo.did}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.13",
+  "version": "0.8.14-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -38,6 +38,7 @@
     "debug": "^4.4.1",
     "diff": "^8.0.2",
     "dompurify": "^3.2.6",
+    "file-type": "^21.0.0",
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
@@ -54,7 +55,6 @@
     "remark-gfm": "^4.0.1",
     "remark-lint": "^10.0.1",
     "remark-parse": "^11.0.0",
-    "slugify": "^1.6.6",
     "terminal-link": "^4.0.0",
     "ufo": "^1.6.1",
     "unified": "^11.0.5",

package/utils/deploy.mjs

@@ -42,11 +42,6 @@ export async function deploy(id, cachedUrl) {
           sessionId,
           "Checkout ID for document deployment website",
         );
-        await saveValueToConfig(
-          "paymentUrl",
-          paymentUrl,
-          "Payment URL for document deployment website",
-        );
 
         if (!isResuming) {
           await open(paymentUrl);

package/utils/file-utils.mjs

@@ -1,11 +1,16 @@
 import { execSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { access, readFile, stat } from "node:fs/promises";
-import path from "node:path";
+import path, { join } from "node:path";
 import { glob } from "glob";
+import fs from "fs-extra";
 import { isBinaryFile } from "isbinaryfile";
 import { encode } from "gpt-tokenizer";
+import { fileTypeFromBuffer } from "file-type";
+import { gunzipSync } from "node:zlib";
 import { isGlobPattern } from "./utils.mjs";
 import { INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD } from "./constants/index.mjs";
+import { uploadFiles } from "./upload-files.mjs";
 
 /**
  * Check if a directory is inside a git repository using git command
@@ -644,3 +649,182 @@ export function getMediaDescriptionCachePath() {
   const cwd = process.cwd();
   return path.join(cwd, ".aigne", "doc-smith", "media-description.yaml");
 }
+
+/**
+ * Detect file type from buffer with comprehensive fallback strategy
+ * @param {Buffer} buffer - File buffer
+ * @param {string} contentType - HTTP Content-Type header
+ * @param {string} url - Original URL (for fallback)
+ * @returns {Promise<{ext: string, mime: string}>} File extension and MIME type
+ */
+export async function detectFileType(buffer, contentType, url = "") {
+  // 1. Try file-type for binary images (PNG, JPG, WebP, GIF, etc.)
+  try {
+    const fileType = await fileTypeFromBuffer(buffer);
+    if (fileType) {
+      return {
+        ext: fileType.ext,
+        mime: fileType.mime,
+      };
+    }
+  } catch (error) {
+    console.debug("file-type detection failed:", error.message);
+  }
+
+  // 2. Check for SVG/SVGZ
+  const svgResult = await detectSvgType(buffer, contentType);
+  if (svgResult) {
+    return svgResult;
+  }
+
+  // 3. Fallback to Content-Type
+  if (contentType) {
+    const ext = getExtnameFromContentType(contentType);
+    if (ext) {
+      return {
+        ext,
+        mime: contentType.split(";")[0].trim(),
+      };
+    }
+  }
+
+  // 4. Fallback to URL extension
+  if (url) {
+    const urlExt = path.extname(url).toLowerCase();
+    if (urlExt) {
+      return {
+        ext: urlExt.slice(1), // Remove leading dot
+        mime: getMimeType(url),
+      };
+    }
+  }
+
+  // 5. Default fallback
+  return {
+    ext: "bin",
+    mime: "application/octet-stream",
+  };
+}
+
+/**
+ * Detect SVG/SVGZ file type
+ * @param {Buffer} buffer - File buffer
+ * @param {string} contentType - HTTP Content-Type header
+ * @returns {Promise<{ext: string, mime: string} | null>} SVG info or null
+ */
+async function detectSvgType(buffer, contentType) {
+  // Check Content-Type first
+  if (contentType?.includes("image/svg+xml")) {
+    return {
+      ext: "svg",
+      mime: "image/svg+xml",
+    };
+  }
+
+  try {
+    let text = "";
+
+    // Check if it's gzipped (SVGZ)
+    if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+      try {
+        const decompressed = gunzipSync(buffer);
+        text = decompressed.toString("utf8");
+        if (isSvgContent(text)) {
+          return {
+            ext: "svgz",
+            mime: "image/svg+xml",
+          };
+        }
+      } catch {
+        // Not gzipped, continue with regular text detection
+      }
+    }
+
+    // Try as regular text
+    if (!text) {
+      text = buffer.toString("utf8");
+    }
+
+    if (isSvgContent(text)) {
+      return {
+        ext: "svg",
+        mime: "image/svg+xml",
+      };
+    }
+  } catch (error) {
+    console.debug("SVG detection failed:", error.message);
+  }
+
+  return null;
+}
+
+/**
+ * Check if text content is SVG
+ * @param {string} text - Text content
+ * @returns {boolean} True if SVG
+ */
+function isSvgContent(text) {
+  if (!text || typeof text !== "string") return false;
+
+  // Remove BOM and trim
+  const cleanText = text.replace(/^\uFEFF/, "").trim();
+
+  // Check for SVG root element
+  return /^<\?xml\s+[^>]*>\s*<svg/i.test(cleanText) || /^<svg/i.test(cleanText);
+}
+
+/**
+ * Download and upload a remote image URL
+ * @param {string} imageUrl - The remote image URL
+ * @param {string} docsDir - Directory to save temporary files
+ * @param {string} appUrl - Application URL for upload
+ * @param {string} accessToken - Access token for upload
+ * @returns {Promise<{url: string, downloadFinalPath: string | null}>} The uploaded image URL and final path if failed
+ */
+export async function downloadAndUploadImage(imageUrl, docsDir, appUrl, accessToken) {
+  let downloadFinalPath = null;
+
+  try {
+    // 1. Download with timeout control
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout
+
+    const response = await fetch(imageUrl, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    // 2. Convert to Buffer for file type detection
+    const blob = await response.blob();
+    const arrayBuffer = await blob.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+
+    // 3. Detect file type with comprehensive fallback
+    const contentType = response.headers.get("content-type");
+    const { ext } = await detectFileType(buffer, contentType, imageUrl);
+
+    // 4. Generate random filename and save file
+    const randomId = randomBytes(16).toString("hex");
+    const tempFilePath = join(docsDir, `temp-logo-${randomId}`);
+    downloadFinalPath = ext ? `${tempFilePath}.${ext}` : tempFilePath;
+    fs.writeFileSync(downloadFinalPath, buffer);
+
+    // 5. Upload and get URL
+    const { results: uploadResults } = await uploadFiles({
+      appUrl,
+      filePaths: [downloadFinalPath],
+      accessToken,
+      concurrency: 1,
+    });
+
+    // 6. Return uploaded URL
+    return { url: uploadResults?.[0]?.url || imageUrl, downloadFinalPath };
+  } catch (error) {
+    console.warn(`Failed to download and upload image from ${imageUrl}: ${error.message}`);
+    return { url: imageUrl, downloadFinalPath: null };
+  }
+}