@aigne/doc-smith 0.5.1 → 0.7.0

package/agents/load-sources.mjs

@@ -2,7 +2,11 @@ import { access, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../utils/constants.mjs";
 import { getFilesWithGlob, loadGitignore } from "../utils/file-utils.mjs";
-import { getCurrentGitHead, getModifiedFilesBetweenCommits } from "../utils/utils.mjs";
+import {
+  getCurrentGitHead,
+  getModifiedFilesBetweenCommits,
+  isGlobPattern,
+} from "../utils/utils.mjs";
 
 export default async function loadSources({
   sources = [],
@@ -24,7 +28,12 @@ export default async function loadSources({
 
     for (const dir of paths) {
       try {
-        // Check if the path is a file or directory
+        if (typeof dir !== "string") {
+          console.warn(`Invalid source path: ${dir}`);
+          continue;
+        }
+
+        // First try to access as a file or directory
         const stats = await stat(dir);
 
         if (stats.isFile()) {
@@ -78,7 +87,31 @@ export default async function loadSources({
           allFiles = allFiles.concat(filesInDir);
         }
       } catch (err) {
-        if (err.code !== "ENOENT") throw err;
+        if (err.code === "ENOENT") {
+          // Path doesn't exist as file or directory, try as glob pattern
+          try {
+            // Check if it looks like a glob pattern
+            const isGlobPatternResult = isGlobPattern(dir);
+
+            if (isGlobPatternResult) {
+              // Use glob to find matching files from current working directory
+              const { glob } = await import("glob");
+              const matchedFiles = await glob(dir, {
+                absolute: true,
+                nodir: true, // Only files, not directories
+                dot: false, // Don't include hidden files
+              });
+
+              if (matchedFiles.length > 0) {
+                allFiles = allFiles.concat(matchedFiles);
+              }
+            }
+          } catch (globErr) {
+            console.warn(`Failed to process glob pattern "${dir}": ${globErr.message}`);
+          }
+        } else {
+          throw err;
+        }
       }
     }
 
@@ -86,17 +119,55 @@ export default async function loadSources({
   }
 
   files = [...new Set(files)];
+
+  // Define media file extensions
+  const mediaExtensions = [
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".svg",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".webm",
+    ".m4v",
+  ];
+
+  // Separate source files from media files
+  const sourceFiles = [];
+  const mediaFiles = [];
   let allSources = "";
-  const sourceFiles = await Promise.all(
+
+  await Promise.all(
     files.map(async (file) => {
-      const content = await readFile(file, "utf8");
-      // Convert absolute path to relative path from project root
-      const relativePath = path.relative(process.cwd(), file);
-      allSources += `// sourceId: ${relativePath}\n${content}\n`;
-      return {
-        sourceId: relativePath,
-        content,
-      };
+      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
+        const content = await readFile(file, "utf8");
+        const relativePath = path.relative(process.cwd(), file);
+        allSources += `// sourceId: ${relativePath}\n${content}\n`;
+
+        sourceFiles.push({
+          sourceId: relativePath,
+          content,
+        });
+      }
     }),
   );
 
@@ -164,6 +235,37 @@ 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";
+  }
+
   // Count words and lines in allSources
   let totalWords = 0;
   let totalLines = 0;
@@ -188,6 +290,7 @@ export default async function loadSources({
     modifiedFiles,
     totalWords,
     totalLines,
+    assetsContent,
   };
 }
 
@@ -257,6 +360,10 @@ loadSources.output_schema = {
       items: { type: "string" },
       description: "Array of modified files since last generation",
     },
+    assetsContent: {
+      type: "string",
+      description: "Markdown content for available media assets",
+    },
   },
 };
 

package/agents/publish-docs.mjs

@@ -1,16 +1,33 @@
 import { basename, join } from "node:path";
 import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import chalk from "chalk";
+import fs from "fs-extra";
+
 import { getAccessToken } from "../utils/auth-utils.mjs";
-import { DISCUSS_KIT_STORE_URL } from "../utils/constants.mjs";
+import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../utils/constants.mjs";
+import { beforePublishHook, ensureTmpDir } from "../utils/kroki-utils.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
 const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 
 export default async function publishDocs(
-  { docsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
+  { docsDir: rawDocsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
   options,
 ) {
+  // move work dir to tmp-dir
+  await ensureTmpDir();
+
+  const docsDir = join(".aigne", "doc-smith", TMP_DIR, TMP_DOCS_DIR);
+  await fs.rm(docsDir, { recursive: true, force: true });
+  await fs.mkdir(docsDir, {
+    recursive: true,
+  });
+  await fs.cp(rawDocsDir, docsDir, { recursive: true });
+
+  // ----------------- trigger beforePublishHook -----------------------------
+  await beforePublishHook({ docsDir });
+
+  // ----------------- 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;
@@ -87,6 +104,8 @@ export default async function publishDocs(
     ].filter((lang, index, arr) => arr.indexOf(lang) === index), // Remove duplicates
   };
 
+  let message;
+
   try {
     const { success, boardId: newBoardId } = await publishDocsFn({
       sidebarPath,
@@ -98,6 +117,8 @@ export default async function publishDocs(
       boardName: projectInfo.name,
       boardDesc: projectInfo.description,
       boardCover: projectInfo.icon,
+      mediaFolder: rawDocsDir,
+      cacheFilePath: join(".aigne", "doc-smith", "upload-cache.yaml"),
       boardMeta,
     });
 
@@ -112,18 +133,14 @@ export default async function publishDocs(
       if (boardId !== newBoardId) {
         await saveValueToConfig("boardId", newBoardId);
       }
-      const message = `✅ Documentation Published Successfully!`;
-      return {
-        message,
-      };
+      message = `✅ Documentation Published Successfully!`;
     }
-
-    return {};
   } catch (error) {
-    return {
-      message: `❌ Failed to publish docs: ${error.message}`,
-    };
+    message = `❌ Failed to publish docs: ${error.message}`;
   }
+  // clean up tmp work dir
+  await fs.rm(docsDir, { recursive: true, force: true });
+  return message ? { message } : {};
 }
 
 publishDocs.input_schema = {

package/agents/retranslate.yaml

@@ -58,7 +58,7 @@ input_schema:
       type: array
       items:
         type: string
-      description: Languages to translate to
+      description: "Languages to translate to, available languages are: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar"
     feedback:
       type: string
       description: Feedback for translation improvement

package/agents/team-publish-docs.yaml

@@ -13,6 +13,6 @@ skills:
 input_schema:
   type: object
   properties:
-    appUrl: 
+    appUrl:
       type: string
-      description: target website URL where the documentation will be published
+      description: target website URL where the documentation will be published (optional - if not provided, will prompt for interactive input)

package/aigne.yaml

@@ -41,6 +41,7 @@ agents:
   - ./agents/feedback-refiner.yaml
   - ./agents/manage-prefs.mjs
 cli:
+  chat: ./agents/chat.yaml
   agents:
     - ./agents/input-generator.mjs
     - ./agents/docs-generator.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,19 +12,21 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.6.9",
-    "@aigne/anthropic": "^0.11.9",
-    "@aigne/cli": "^1.41.0",
-    "@aigne/core": "^1.55.0",
-    "@aigne/gemini": "^0.9.9",
-    "@aigne/openai": "^0.12.3",
-    "@aigne/publish-docs": "^0.5.7",
+    "@aigne/aigne-hub": "^0.8.1",
+    "@aigne/anthropic": "^0.11.12",
+    "@aigne/cli": "^1.42.0",
+    "@aigne/core": "^1.57.0",
+    "@aigne/gemini": "^0.11.1",
+    "@aigne/openai": "^0.13.2",
+    "@aigne/publish-docs": "^0.8.0",
     "chalk": "^5.5.0",
     "dompurify": "^3.2.6",
+    "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "jsdom": "^26.1.0",
     "mermaid": "^11.9.0",
     "open": "^10.2.0",
+    "p-map": "^7.0.3",
     "remark-gfm": "^4.0.1",
     "remark-lint": "^10.0.1",
     "remark-parse": "^11.0.0",
@@ -40,10 +42,11 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
     "test:watch": "bun test --watch",
-    "lint": "biome check && pnpm -r run lint",
+    "lint": "biome check",
     "update:deps": "npx -y taze major -r -w -f -n '/@abtnode|@aigne|@arcblock|@blocklet|@did-connect|@did-pay|@did-space|@nft-store|@nft-studio|@ocap/' && pnpm install && pnpm run deduplicate",
     "deduplicate": "pnpm dedupe",
-    "lint:fix": "biome check --write && pnpm -r run lint"
+    "lint:fix": "biome check --write"
   }
 }

package/prompts/content-detail-generator.md

@@ -16,6 +16,11 @@
 {{ detailDataSources }}
 
 {{ additionalInformation }}
+
+<media_list>
+{{ assetsContent }}
+</media_list>
+
 </datasources>
 
 <terms>
@@ -93,18 +98,21 @@ parentId: {{parentId}}
 - 媒体资源以 markdown 格式提供，示例：![资源描述](https://xxxx)
 - 在生成结果中以 markdown 格式展示图片
 - 根据资源描述，在上下文相关的位置，合理的展示图片，让结果展示效果更丰富
-- 只使用完整的远程图片URL（如 https://example.com/image.jpg），禁止使用相对路径（如 ./images/photo.png 或 ../assets/logo.png），确保发布后图片能正常访问
 
 </media_rules>
 
-{% include "../prompts/document/detail-generator.md" %}
+{% include "document/detail-generator.md" %}
+
+{% include "document/custom-components.md" %}
+
 </rules>
 
-{% include "../prompts/document/detail-example.md" %}
+{% include "document/detail-example.md" %}
 
 <output_schema>
 
 1. 输内容为{{nodeName}}的详细文本。
 2. 直接输出{{nodeName}}内容，不要包含其他信息.
 3. 仅参考示例中的风格，**以语言 {{locale}} 输出内容 **
-   </output_schema>
+
+</output_schema>

package/prompts/document/custom-components.md

@@ -0,0 +1,80 @@
+When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
+- `<x-card>`
+- `<x-cards>`
+
+
+### 1. <x-card> Single Card Component
+Suitable for displaying individual links with a richer and more visually appealing presentation format.
+
+Example:
+
+```
+<x-card data-title="Required Title" data-image="Image URL" data-icon="Icon identifier (e.g., lucide:rocket or material-symbols:rocket-outline)" data-href="Navigation link URL" data-horizontal="true/false" data-cta="Button text" >
+  Card body content
+</x-card>
+```
+
+Attribute Rules:
+
+-	data-title (required): Card title.
+-	data-icon / data-image (choose one, at least one must be provided):
+    -	It's recommended to always provide data-icon.
+    -	Icons should prioritize Lucide (lucide:icon-name). If not available in Lucide, use Iconify (collection:icon-name, e.g., material-symbols:rocket-outline).
+-	data-image (optional): Image URL, can coexist with icon.
+-	data-href (optional): Navigation link for clicking the card or button.
+-	data-horizontal (optional): Whether to use horizontal layout.
+-	data-cta (optional): Button text (call to action).
+-	Body content: Must be written within <x-card>...</x-card> children.
+
+
+### 2. `<x-cards>` Card List Component
+
+Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
+
+Syntax:
+
+```
+<x-cards data-columns="Number of columns">
+  <x-card data-title="Title 1" data-icon="lucide:rocket">Content 1</x-card>
+  <x-card data-title="Title 2" data-icon="lucide:bolt">Content 2</x-card>
+  <x-card data-title="Title 3" data-icon="material-symbols:rocket-outline">Content 3</x-card>
+</x-cards>
+```
+
+Attribute Rules:
+-	data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
+-	Must contain multiple <x-card> elements internally.
+-	Consistency requirement: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+    -	Recommended to always provide data-icon for each card.
+    -	Or all cards should have data-image.
+    -	Avoid mixing (some with icons, some with only images).
+
+
+### 3. Examples
+
+Single card:
+
+```
+<x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
+  This is an example of a horizontal card.
+</x-card>
+```
+
+Card list (all using icons, recommended approach):
+
+```
+<x-cards data-columns="3">
+  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+  <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+</x-cards>
+```
+
+Card list (all using images):
+
+```
+<x-cards data-columns="2">
+  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+  <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+</x-cards>
+```

package/prompts/document/d2-chart/diy-examples.md

@@ -0,0 +1,44 @@
+- 结构图示例：
+  ```d2
+  App: Application
+  API: API Server
+  DB: Database
+
+  App -> API: 调用
+  API -> DB: 读写数据
+  ```
+- 流程图示例：
+  ```d2
+  start: 开始
+  input: 用户输入
+  process: 处理数据
+  output: 输出结果
+  end: 结束
+
+  start -> input -> process -> output -> end
+  ```
+- 时序图示例：
+  ```d2
+  User: 用户
+  Service: 服务
+  DB: 数据库
+
+  User -> Service: 请求
+  Service -> DB: 查询
+  DB -> Service: 返回数据
+  Service -> User: 响应
+  ```
+- 决策树示例：
+  ```d2
+  start: 开始
+  check: 是否有效？
+  yes: 是
+  no: 否
+  end: 结束
+
+  start -> check
+  check -> yes: 有效
+  check -> no: 无效
+  yes -> end
+  no -> end
+  ```