@aigne/doc-smith 0.8.12-beta.7 → 0.8.12-beta.9

package/agents/publish/publish-docs.mjs

@@ -1,10 +1,12 @@
-import { basename, join } from "node:path";
-
+import { basename, extname, join, relative } from "node:path";
+import slugify from "slugify";
 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 { getExtnameFromContentType } from "../../utils/file-utils.mjs";
+import { isHttp } from "../../utils/utils.mjs";
 import { getAccessToken, getOfficialAccessToken } from "../../utils/auth-utils.mjs";
 import {
   CLOUD_SERVICE_URL_PROD,
@@ -16,14 +18,25 @@ import {
 import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
 import { deploy } from "../../utils/deploy.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
+import updateBranding from "../utils/update-branding.mjs";
 
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 
 export default async function publishDocs(
-  { docsDir: rawDocsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
+  {
+    docsDir: rawDocsDir,
+    appUrl,
+    boardId,
+    projectName,
+    projectDesc,
+    projectLogo,
+    translatedMetadata,
+    "with-branding": withBrandingOption,
+  },
   options,
 ) {
   let message;
+  let shouldWithBranding = withBrandingOption || false;
 
   try {
     // move work dir to tmp-dir
@@ -119,6 +132,12 @@ 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 = "";
@@ -143,6 +162,7 @@ export default async function publishDocs(
     process.env.DOC_ROOT_DIR = docsDir;
 
     const sidebarPath = join(docsDir, "_sidebar.md");
+    const publishCacheFilePath = join(DOC_SMITH_DIR, "upload-cache.yaml");
 
     // Get project info from config
     const projectInfo = {
@@ -151,6 +171,39 @@ export default async function publishDocs(
       icon: projectLogo || config?.projectLogo || "",
     };
 
+    // 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);
+
+          // Update to relative path
+          projectInfo.icon = relative(join(process.cwd(), DOC_SMITH_DIR), finalPath);
+        }
+      } catch (error) {
+        console.warn(`Failed to download project logo from ${projectInfo.icon}: ${error.message}`);
+      }
+    }
+
+    if (shouldWithBranding) {
+      updateBranding({ appUrl, projectInfo, accessToken });
+    }
+
     // Construct boardMeta object
     const boardMeta = {
       category: config?.documentPurpose || [],
@@ -161,6 +214,9 @@ export default async function publishDocs(
         ...(config?.translateLanguages || []),
       ].filter((lang, index, arr) => arr.indexOf(lang) === index), // Remove duplicates
     };
+    if (translatedMetadata) {
+      boardMeta.translation = translatedMetadata;
+    }
 
     const {
       success,
@@ -177,7 +233,7 @@ export default async function publishDocs(
       boardDesc: projectInfo.description,
       boardCover: projectInfo.icon,
       mediaFolder: rawDocsDir,
-      cacheFilePath: join(DOC_SMITH_DIR, "upload-cache.yaml"),
+      cacheFilePath: publishCacheFilePath,
       boardMeta,
     });
 
@@ -193,6 +249,7 @@ export default async function publishDocs(
         await saveValueToConfig("boardId", newBoardId);
       }
       message = `✅ Documentation published successfully!`;
+      await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
       if (error?.includes("401") || error?.includes("403")) {
@@ -214,7 +271,6 @@ export default async function publishDocs(
     }
   }
 
-  await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
   return message ? { message } : {};
 }
 
@@ -234,6 +290,22 @@ publishDocs.input_schema = {
       type: "string",
       description: "The id of the board",
     },
+    "with-branding": {
+      type: "boolean",
+      description: "Update your website branding (title, description, logo)",
+    },
+    projectName: {
+      type: "string",
+      description: "The name of the project",
+    },
+    projectDesc: {
+      type: "string",
+      description: "The description of the project",
+    },
+    projectLogo: {
+      type: "string",
+      description: "The logo/icon of the project",
+    },
   },
 };
 

package/agents/publish/translate-meta.mjs

@@ -0,0 +1,103 @@
+import { join } from "node:path";
+
+import { AIAgent } from "@aigne/core";
+import fs from "fs-extra";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import z from "zod";
+
+import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
+
+export default async function translateMeta(
+  { projectName, projectDesc, locale, translateLanguages = [] },
+  options,
+) {
+  const languages = [...new Set([...(locale ? [locale] : []), ...(translateLanguages || [])])];
+
+  const translationCacheFilePath = join(DOC_SMITH_DIR, "translation-cache.yaml");
+  await fs.ensureFile(translationCacheFilePath);
+  const translationCache = await fs.readFile(translationCacheFilePath, "utf-8");
+  const parsedTranslationCache = yamlParse(translationCache || "{}");
+
+  const titleTranslation = parsedTranslationCache[projectName] || {};
+  const descTranslation = parsedTranslationCache[projectDesc] || {};
+
+  const titleLanguages = languages.filter((lang) => !titleTranslation[lang]);
+  const descLanguages = languages.filter((lang) => !descTranslation[lang]);
+  const titleTranslationSchema = z.object(
+    titleLanguages.reduce((shape, lang) => {
+      shape[lang] = z.string();
+      return shape;
+    }, {}),
+  );
+  const descTranslationSchema = z.object(
+    descLanguages.reduce((shape, lang) => {
+      shape[lang] = z.string();
+      return shape;
+    }, {}),
+  );
+
+  const agent = AIAgent.from({
+    name: "translateMeta",
+    instructions:
+      "You are an **Elite Polyglot Localization and Translation Specialist** with extensive professional experience across multiple domains. Your core mission is to produce translations that are not only **100% accurate** to the source meaning but are also **natively fluent, highly readable, and culturally appropriate** in the target language.",
+    inputKey: "message",
+    outputSchema: z.object({
+      title: titleTranslationSchema.describe("Translated titles with language codes as keys"),
+      desc: descTranslationSchema.describe("Translated descriptions with language codes as keys"),
+    }),
+  });
+  if (titleLanguages.length > 0 || descLanguages.length > 0) {
+    const translatedMetadata = await options.context.invoke(agent, {
+      message: `Translate the following title and description into all target languages except the source language. Provide the translations in a JSON object with the language codes as keys. If the project title or description is empty, return an empty string for that field.
+
+Project Title: ${projectName || ""}
+Project Description: ${projectDesc || ""}
+
+Target Languages: { title: ${titleLanguages.join(", ")}, desc: ${descLanguages.join(", ")} }
+Source Language: ${locale}
+
+Respond with a JSON object in the following format:
+{
+  "title": {
+    "fr": "Translated Project Title in French",
+    "es": "Translated Project Title in Spanish",
+    ...
+  },
+  "desc": {
+    "fr": "Translated Project Description in French",
+    "es": "Translated Project Description in Spanish",
+    ...
+  }
+}
+
+If no translation is needed, respond with:
+{
+  "title": {},
+  "desc": {}
+}`,
+    });
+    Object.keys(translatedMetadata.title || {}).forEach((lang) => {
+      if (translatedMetadata.title[lang]) {
+        titleTranslation[lang] = translatedMetadata.title[lang];
+      }
+    });
+    Object.keys(translatedMetadata.desc || {}).forEach((lang) => {
+      if (translatedMetadata.desc[lang]) {
+        descTranslation[lang] = translatedMetadata.desc[lang];
+      }
+    });
+  }
+  const saveResult = {
+    ...parsedTranslationCache,
+    [projectName]: titleTranslation,
+    [projectDesc]: descTranslation,
+  };
+  await fs.writeFile(translationCacheFilePath, yamlStringify(saveResult), { encoding: "utf8" });
+
+  return {
+    translatedMetadata: {
+      title: saveResult[projectName] || {},
+      desc: saveResult[projectDesc] || {},
+    },
+  };
+}

package/agents/update/generate-document.yaml

@@ -5,6 +5,8 @@ instructions:
     url: ../../prompts/detail/generate/system-prompt.md
   - role: user
     url: ../../prompts/detail/generate/user-prompt.md
+auto_reorder_system_messages: true
+auto_merge_system_messages: true
 input_schema:
   type: object
   properties:
@@ -54,31 +56,31 @@ afs:
         description: |
           Codebase of the project to be documented used as context for document generation,
           should search and read as needed while generating document content
-# skills:
-  # FIXME: @zhanghan temporary disable diagram tool
-  # - type: team
-  #   task_render_mode: collapse
-  #   name: generateDiagram
-  #   skills:
-  #     - ../generate/draw-diagram.yaml
-  #     - ../generate/wrap-diagram-code.mjs
-  #   reflection:
-  #     reviewer: ../generate/check-diagram.mjs
-  #     is_approved: isValid
-  #     max_iterations: 5
-  #     return_last_on_max_iterations: false
-  #     custom_error_message: "MUST NOT generate any diagram: validation failed after max iterations."
-  #   input_schema:
-  #     type: object
-  #     properties:
-  #       documentContent:
-  #         type: string
-  #         description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
-  #     required:
-  #       - documentContent
-  #   output_schema:
-  #     type: object
-  #     properties:
-  #       diagramSourceCode:
-  #         type: string
-  #         description: The **diagram source code** generated from the input text.
+keep_text_in_tool_uses: false
+skills:
+  - type: team
+    task_render_mode: collapse
+    name: generateDiagram
+    skills:
+      - ../generate/draw-diagram.yaml
+      - ../generate/wrap-diagram-code.mjs
+    reflection:
+      reviewer: ../generate/check-diagram.mjs
+      is_approved: isValid
+      max_iterations: 5
+      return_last_on_max_iterations: false
+      custom_error_message: "MUST NOT generate any diagram: validation failed after max iterations."
+    input_schema:
+      type: object
+      properties:
+        documentContent:
+          type: string
+          description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+      required:
+        - documentContent
+    output_schema:
+      type: object
+      properties:
+        diagramSourceCode:
+          type: string
+          description: The **diagram source code** generated from the input text.

package/agents/update/index.yaml

@@ -30,6 +30,7 @@ skills:
     default_input:
       requiredFeedback: false
   - ../utils/format-document-structure.mjs
+  - ../media/load-media-description.mjs
   - ../update/check-update-is-single.mjs
   - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs

package/agents/update/update-document-detail.yaml

@@ -6,7 +6,8 @@ instructions:
     url: ../../prompts/detail/update/system-prompt.md
   - role: user
     url: ../../prompts/detail/update/user-prompt.md
-
+auto_reorder_system_messages: true
+auto_merge_system_messages: true
 input_schema:
   type: object
   properties:
@@ -53,6 +54,7 @@ afs:
         description: |
           Codebase of the project to be documented used as context for document generation,
           should search and read as needed while generating document content
+keep_text_in_tool_uses: false
 skills:
   - ./document-tools/update-document-content.mjs
 task_render_mode: collapse

package/agents/utils/load-sources.mjs

@@ -1,10 +1,12 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import imageSize from "image-size";
 import {
   buildSourcesContent,
   calculateFileStats,
   loadFilesFromPaths,
   readFileContents,
+  getMimeType,
 } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,
@@ -29,8 +31,10 @@ export default async function loadSources({
   useDefaultPatterns = true,
   lastGitHead,
   reset = false,
+  media,
 } = {}) {
   let files = Array.isArray(sources) ? [...sources] : [];
+  const { minImageWidth } = media || { minImageWidth: 800 };
 
   if (sourcesPath) {
     const allFiles = await loadFilesFromPaths(sourcesPath, {
@@ -58,36 +62,102 @@ export default async function loadSources({
     ".bmp",
     ".webp",
     ".svg",
+    ".heic",
+    ".heif",
     ".mp4",
+    ".mpeg",
+    ".mpg",
     ".mov",
     ".avi",
+    ".flv",
     ".mkv",
     ".webm",
+    ".wmv",
     ".m4v",
+    ".3gpp",
   ];
 
   // Separate source files from media files
   const sourceFilesPaths = [];
   const mediaFiles = [];
 
-  for (const file of files) {
-    const ext = path.extname(file).toLowerCase();
-
-    if (mediaExtensions.includes(ext)) {
-      // This is a media file
-      const relativePath = path.relative(docsDir, file);
-      const fileName = path.basename(file);
-      const description = path.parse(fileName).name;
-
-      mediaFiles.push({
-        name: fileName,
-        path: relativePath,
-        description,
-      });
-    } else {
-      // This is a source file
-      sourceFilesPaths.push(file);
-    }
+  // Helper function to determine file type from extension
+  const getFileType = (filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+    const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".heic", ".heif"];
+    const videoExts = [
+      ".mp4",
+      ".mpeg",
+      ".mpg",
+      ".mov",
+      ".avi",
+      ".flv",
+      ".mkv",
+      ".webm",
+      ".wmv",
+      ".m4v",
+      ".3gpp",
+    ];
+
+    if (imageExts.includes(ext)) return "image";
+    if (videoExts.includes(ext)) return "video";
+    return "media";
+  };
+
+  let filteredImageCount = 0;
+
+  await Promise.all(
+    files.map(async (file) => {
+      const ext = path.extname(file).toLowerCase();
+
+      if (mediaExtensions.includes(ext)) {
+        // This is a media file
+        const relativePath = path.relative(docsDir, file);
+        const fileName = path.basename(file);
+        const description = path.parse(fileName).name;
+
+        const mediaItem = {
+          name: fileName,
+          path: relativePath,
+          type: getFileType(relativePath),
+          description,
+          mimeType: getMimeType(file),
+        };
+
+        // For image files, get dimensions and filter by width
+        if (mediaItem.type === "image") {
+          try {
+            const buffer = await readFile(file);
+            const dimensions = imageSize(buffer);
+            mediaItem.width = dimensions.width;
+            mediaItem.height = dimensions.height;
+
+            // Filter out images with width less than minImageWidth
+            if (dimensions.width < minImageWidth) {
+              filteredImageCount++;
+              console.log(
+                `Filtered image: ${fileName} (${dimensions.width}x${dimensions.height}px < ${minImageWidth}px minimum)`,
+              );
+              return;
+            }
+          } catch (err) {
+            console.warn(`⚠️  Failed to get dimensions for ${fileName}: ${err.message}`);
+          }
+        }
+
+        mediaFiles.push(mediaItem);
+      } else {
+        // This is a source file
+        sourceFilesPaths.push(file);
+      }
+    }),
+  );
+
+  // Log summary of filtered images
+  if (filteredImageCount > 0) {
+    console.log(
+      `\nTotal ${filteredImageCount} low-resolution image(s) filtered for better documentation quality (minimum width: ${minImageWidth}px)\n`,
+    );
   }
 
   // Read all source files using the utility function
@@ -179,37 +249,6 @@ export default async function loadSources({
     }
   }
 
-  // Generate assets content from media files
-  let assetsContent = "# Available Media Assets for Documentation\n\n";
-
-  if (mediaFiles.length > 0) {
-    // Helper function to determine file type from extension
-    const getFileType = (filePath) => {
-      const ext = path.extname(filePath).toLowerCase();
-      const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg"];
-      const videoExts = [".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v"];
-
-      if (imageExts.includes(ext)) return "image";
-      if (videoExts.includes(ext)) return "video";
-      return "media";
-    };
-
-    const mediaYaml = mediaFiles.map((file) => ({
-      name: file.name,
-      path: file.path,
-      type: getFileType(file.path),
-    }));
-
-    assetsContent += "```yaml\n";
-    assetsContent += "assets:\n";
-    mediaYaml.forEach((asset) => {
-      assetsContent += `  - name: "${asset.name}"\n`;
-      assetsContent += `    path: "${asset.path}"\n`;
-      assetsContent += `    type: "${asset.type}"\n`;
-    });
-    assetsContent += "```\n";
-  }
-
   return {
     datasources: allSources,
     content,
@@ -218,7 +257,7 @@ export default async function loadSources({
     modifiedFiles,
     totalTokens,
     totalLines,
-    assetsContent,
+    mediaFiles,
     isLargeContext,
     allFilesPaths,
   };
@@ -280,9 +319,20 @@ loadSources.output_schema = {
       items: { type: "string" },
       description: "Array of modified files since last generation",
     },
-    assetsContent: {
-      type: "string",
-      description: "Markdown content for available media assets",
+    mediaFiles: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          path: { type: "string" },
+          type: { type: "string" },
+          width: { type: "number" },
+          height: { type: "number" },
+          mimeType: { type: "string" },
+        },
+      },
+      description: "Array of media file objects (images/videos)",
     },
   },
 };

package/agents/utils/update-branding.mjs

@@ -0,0 +1,69 @@
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import { joinURL } from "ufo";
+
+import { getComponentInfoWithMountPoint } from "../../utils/blocklet.mjs";
+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 }) {
+  try {
+    const origin = new URL(appUrl).origin;
+    if ([CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(origin)) {
+      console.log("Skipped updating branding for official service\n");
+      return;
+    }
+
+    console.log(`🔄 Updating branding for ${chalk.cyan(origin)}`);
+
+    const componentInfo = await getComponentInfoWithMountPoint(origin, DISCUSS_KIT_DID);
+    const mountPoint = componentInfo.mountPoint || "/";
+
+    const res = await requestWithAuthToken(
+      joinURL(origin, mountPoint, "/api/branding"),
+      {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          appName: projectInfo.name,
+          appDescription: projectInfo.description,
+        }),
+      },
+      accessToken,
+    );
+
+    if (res.success) {
+      try {
+        const projectLogoPath = resolve(process.cwd(), DOC_SMITH_DIR, projectInfo.icon);
+        const projectLogoStat = await stat(projectLogoPath);
+
+        if (projectLogoStat.isFile()) {
+          // Upload to blocklet logo endpoint
+          await uploadFiles({
+            appUrl: origin,
+            filePaths: [projectLogoPath],
+            accessToken,
+            concurrency: 1,
+            endpoint: `${origin}/.well-known/service/blocklet/logo/upload/square/${componentInfo.did}`,
+          });
+        }
+        console.log("✅ Updated branding successfully!\n");
+      } catch (error) {
+        console.warn(`⚠️ Just failed to update logo: ${error.message}\n`);
+      }
+    } else {
+      console.warn(`⚠️ Failed to update branding: ${res.error}\n`);
+    }
+  } catch (error) {
+    console.warn(`⚠️ Failed to update branding: ${error.message}\n`);
+  }
+}

package/aigne.yaml

@@ -49,6 +49,11 @@ agents:
   - ./agents/publish/publish-docs.mjs
   - ./agents/publish/index.yaml
 
+  # Media
+  - ./agents/media/load-media-description.mjs
+  - ./agents/media/batch-generate-media-description.yaml
+  - ./agents/media/generate-media-description.yaml
+
   # Clear/Cleanup
   - ./agents/clear/choose-contents.mjs
   - ./agents/clear/clear-document-structure.mjs
@@ -56,6 +61,7 @@ agents:
   - ./agents/clear/clear-document-config.mjs
   - ./agents/clear/clear-auth-tokens.mjs
   - ./agents/clear/clear-deployment-config.mjs
+  - ./agents/clear/clear-media-description.mjs
 
   # Utilities
   - ./agents/utils/load-sources.mjs