@aigne/doc-smith 0.8.11-beta.6 → 0.8.11

package/agents/update/fs-tools/read-file.mjs

@@ -0,0 +1,307 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Detects if a file is likely binary by checking for null bytes
+ */
+function isBinaryFile(buffer) {
+  // Check first 8KB for null bytes
+  const checkLength = Math.min(buffer.length, 8192);
+  for (let i = 0; i < checkLength; i++) {
+    if (buffer[i] === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Gets MIME type based on file extension
+ */
+function getMimeType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeTypes = {
+    // Text files
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".ts": "text/typescript",
+    ".tsx": "text/typescript",
+    ".jsx": "text/javascript",
+    ".py": "text/x-python",
+    ".java": "text/x-java",
+    ".cpp": "text/x-c",
+    ".c": "text/x-c",
+    ".h": "text/x-c",
+    ".css": "text/css",
+    ".html": "text/html",
+    ".xml": "text/xml",
+    ".yaml": "text/yaml",
+    ".yml": "text/yaml",
+    ".toml": "text/plain",
+    ".ini": "text/plain",
+    ".cfg": "text/plain",
+    ".conf": "text/plain",
+    ".sh": "text/x-shellscript",
+    ".bash": "text/x-shellscript",
+    ".zsh": "text/x-shellscript",
+    ".fish": "text/x-shellscript",
+
+    // Image files
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+
+    // Document files
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+
+    // Other
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+  };
+
+  return mimeTypes[ext] || "application/octet-stream";
+}
+
+/**
+ * Validates file path and checks accessibility
+ */
+function validateFilePath(filePath) {
+  if (!filePath || typeof filePath !== "string" || filePath.trim() === "") {
+    return "File path parameter is required and cannot be empty";
+  }
+
+  if (!path.isAbsolute(filePath)) {
+    return `File path must be absolute, but was relative: ${filePath}`;
+  }
+
+  try {
+    const stats = fs.statSync(filePath);
+    if (stats.isDirectory()) {
+      return `Path is a directory, not a file: ${filePath}`;
+    }
+    return null;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return `File does not exist: ${filePath}`;
+    } else if (error.code === "EACCES") {
+      return `Permission denied: ${filePath}`;
+    }
+    return `Cannot access file: ${filePath} (${error.message})`;
+  }
+}
+
+/**
+ * Reads file content with proper handling for different file types
+ */
+async function readFileContent(filePath, offset = 0, limit = null, encoding = "utf8") {
+  const stats = await fsPromises.stat(filePath);
+  const fileSize = stats.size;
+  const mimeType = getMimeType(filePath);
+
+  // Handle binary files differently
+  if (
+    mimeType.startsWith("image/") ||
+    mimeType === "application/pdf" ||
+    fileSize > 10 * 1024 * 1024
+  ) {
+    return {
+      content: `[Binary file: ${path.basename(filePath)}]`,
+      mimeType,
+      fileSize,
+      isBinary: true,
+      encoding: null,
+      lineCount: null,
+      isTruncated: false,
+    };
+  }
+
+  // Read file as buffer first to check if it's binary
+  const buffer = await fsPromises.readFile(filePath);
+
+  if (isBinaryFile(buffer)) {
+    return {
+      content: `[Binary file: ${path.basename(filePath)}]`,
+      mimeType,
+      fileSize,
+      isBinary: true,
+      encoding: null,
+      lineCount: null,
+      isTruncated: false,
+    };
+  }
+
+  // Convert buffer to text
+  let content = buffer.toString(encoding);
+  const lines = content.split(/\r?\n/);
+  const totalLines = lines.length;
+  let isTruncated = false;
+  let linesShown = [1, totalLines];
+
+  // Handle offset and limit for text files
+  if (offset > 0 || limit !== null) {
+    const startLine = Math.max(0, offset);
+    const endLine = limit !== null ? Math.min(startLine + limit, totalLines) : totalLines;
+
+    if (startLine >= totalLines) {
+      return {
+        content: "",
+        mimeType,
+        fileSize,
+        isBinary: false,
+        encoding,
+        lineCount: totalLines,
+        isTruncated: false,
+        linesShown: [startLine + 1, startLine + 1],
+        message: `Offset ${offset} is beyond file end (file has ${totalLines} lines)`,
+      };
+    }
+
+    const selectedLines = lines.slice(startLine, endLine);
+    content = selectedLines.join("\n");
+    isTruncated = startLine > 0 || endLine < totalLines;
+    linesShown = [startLine + 1, endLine];
+  }
+
+  // Auto-truncate very large files (more than 10000 lines)
+  const maxLines = 10000;
+  if (limit === null && totalLines > maxLines) {
+    const selectedLines = lines.slice(0, maxLines);
+    content = selectedLines.join("\n");
+    isTruncated = true;
+    linesShown = [1, maxLines];
+  }
+
+  return {
+    content,
+    mimeType,
+    fileSize,
+    isBinary: false,
+    encoding,
+    lineCount: totalLines,
+    isTruncated,
+    linesShown,
+  };
+}
+
+export default async function readFile({ path: filePath, offset, limit, encoding = "utf8" }) {
+  let result = {};
+  let error = null;
+
+  try {
+    // Validate file path first (this checks if it's absolute)
+    const pathError = validateFilePath(filePath);
+    if (pathError) {
+      throw new Error(pathError);
+    }
+
+    // Now we know filePath is valid and absolute
+
+    // Validate numeric parameters
+    if (offset !== undefined && (typeof offset !== "number" || offset < 0)) {
+      throw new Error("Offset must be a non-negative number");
+    }
+
+    if (limit !== undefined && (typeof limit !== "number" || limit <= 0)) {
+      throw new Error("Limit must be a positive number");
+    }
+
+    // Read file content
+    const fileResult = await readFileContent(filePath, offset, limit, encoding);
+
+    // Build success result
+    result = {
+      content: fileResult.content,
+      metadata: {
+        path: filePath,
+        mimeType: fileResult.mimeType,
+        fileSize: fileResult.fileSize,
+        isBinary: fileResult.isBinary,
+        encoding: fileResult.encoding,
+        lineCount: fileResult.lineCount,
+      },
+    };
+
+    // Add truncation info if applicable
+    if (fileResult.isTruncated) {
+      result.truncated = {
+        isTruncated: true,
+        linesShown: fileResult.linesShown,
+        totalLines: fileResult.lineCount,
+        nextOffset: fileResult.linesShown[1],
+      };
+
+      // Add helpful message for truncated content
+      const [start, end] = fileResult.linesShown;
+      const nextOffset = end;
+      result.message =
+        `Content truncated. Showing lines ${start}-${end} of ${fileResult.lineCount} total lines. ` +
+        `To read more, use offset: ${nextOffset}.`;
+    }
+
+    // Add message if provided
+    if (fileResult.message) {
+      result.message = fileResult.message;
+    }
+  } catch (err) {
+    error = err;
+    result = {
+      content: null,
+      metadata: {
+        path: filePath,
+        mimeType: null,
+        fileSize: null,
+        isBinary: null,
+        encoding: null,
+        lineCount: null,
+      },
+      message: `Error reading file: ${err.message}`,
+    };
+  }
+
+  return {
+    command: "read_file",
+    arguments: {
+      path: filePath,
+      offset,
+      limit,
+      encoding,
+    },
+    result,
+    error: error && { message: error.message },
+  };
+}
+
+readFile.input_schema = {
+  type: "object",
+  properties: {
+    path: {
+      type: "string",
+      description: "The path to the file to read (for backwards compatibility)",
+    },
+    offset: {
+      type: "number",
+      description: "Optional: The 0-based line number to start reading from",
+    },
+    limit: {
+      type: "number",
+      description: "Optional: Maximum number of lines to read",
+    },
+    encoding: {
+      type: "string",
+      description: "Optional: File encoding (defaults to utf8)",
+    },
+  },
+  required: ["path"],
+};

package/agents/update/generate-document.yaml

@@ -41,14 +41,11 @@ input_schema:
     - rules
     - datasources
     - originalDocumentStructure
-output_schema:
-  type: object
-  properties:
-    content:
-      type: string
-  required:
-    - content
+output_key: content
 skills:
+  - fs-tools/glob.mjs
+  - fs-tools/grep.mjs
+  - fs-tools/read-file.mjs
   - type: team
     task_render_mode: collapse
     name: generateD2DiagramContent

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

@@ -39,14 +39,10 @@ input_schema:
   required:
     - originalContent
     - feedback
-output_schema:
-  type: object
-  properties:
-    updatedContent:
-      type: string
-      description: Final updated markdown content after applying modifications
-    operationSummary:
-      type: string
-      description: Summary of the operations performed on the document content
+output_key: message
 skills:
-  - ./document-tools/update-document-content.mjs
+  - ./document-tools/update-document-content.mjs
+  - ./fs-tools/glob.mjs
+  - ./fs-tools/grep.mjs
+  - ./fs-tools/read-file.mjs
+task_render_mode: collapse

package/agents/update/user-review-document.mjs

@@ -134,7 +134,8 @@ export default async function userReviewDocument(
   // Print current document headings structure
   printDocumentHeadings(content, title || "Untitled Document");
 
-  let currentContent = content;
+  // Initialize shared context with current content
+  options.context.userContext.currentContent = content;
 
   const MAX_ITERATIONS = 100;
   let iterationCount = 0;
@@ -163,7 +164,10 @@ export default async function userReviewDocument(
     if (action === "finish") {
       break;
     } else if (action === "view") {
-      await showDocumentDetail(currentContent, title || "Untitled Document");
+      await showDocumentDetail(
+        options.context.userContext.currentContent,
+        title || "Untitled Document",
+      );
     }
 
     // Ask for feedback
@@ -200,20 +204,13 @@ export default async function userReviewDocument(
 
     try {
       // Call updateDocument agent with feedback
-      const result = await options.context.invoke(updateAgent, {
+      await options.context.invoke(updateAgent, {
         ...rest,
-        originalContent: currentContent,
+        originalContent: options.context.userContext.currentContent,
         feedback: feedback.trim(),
         userPreferences,
       });
 
-      if (result.updatedContent) {
-        currentContent = result.updatedContent;
-        console.log(`\n✅ ${result.operationSummary || "Document updated successfully"}\n`);
-      } else {
-        console.log("\n❌ We couldn't update the document. Please try rephrasing your feedback.\n");
-      }
-
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
       if (feedbackRefinerAgent) {
@@ -229,7 +226,10 @@ export default async function userReviewDocument(
       }
 
       // Print updated document headings structure
-      printDocumentHeadings(currentContent, title || "Untitled Document");
+      printDocumentHeadings(
+        options.context.userContext.currentContent,
+        title || "Untitled Document",
+      );
     } catch (error) {
       console.error("Error processing your feedback:");
       console.error(`Type: ${error.name}`);
@@ -242,7 +242,7 @@ export default async function userReviewDocument(
     }
   }
 
-  return { content: currentContent };
+  return { content: options.context.userContext.currentContent };
 }
 
 userReviewDocument.taskTitle = "User review and modify document content";

package/docs/advanced-how-it-works.ja.md

@@ -1,63 +1,63 @@
 # 仕組み
 
-AIGNE DocSmithは、AIGNEフレームワーク内に構築されたマルチAgentシステムで動作します。単一のモノリシックなプロセスではなく、専門的なAI Agentのパイプラインを編成し、各Agentが特定のタスクを担当します。このアプローチにより、ソースコードを完全なドキュメンテーションに変換するための、構造化されたモジュラーなプロセスが可能になります。
+AIGNE DocSmithは、マルチagentシステムで動作します。単一のモノリシックなプロセスではなく、専門のAI agentのパイプラインを編成し、各agentが特定のタスクを担当します。このアプローチにより、ソースコードを完全なドキュメントに変換するための構造化されたモジュラーなプロセスが可能になります。
 
-このツールは、AIアプリケーションの開発とデプロイのためのプラットフォームを提供する、より大きなAIGNEエコシステムの不可欠な部分です。
+このツールは、AIアプリケーションを開発・展開するためのプラットフォームを提供する、より大きなAIGNEエコシステムの不可欠な部分です。
 
 ![AIGNEエコシステムのアーキテクチャ](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
-## ドキュメンテーション生成パイプライン
+## ドキュメント生成パイプライン
 
-DocSmithの中核は、ソースコードをいくつかの異なるステージを通じて処理するパイプラインです。各ステージは、1つ以上の専用Agentによって管理されます。通常 `aigne doc generate` コマンドによって開始される主要なワークフローは、次のように視覚化できます。
+DocSmithの中核は、ソースコードをいくつかの異なるステージを通して処理するパイプラインです。各ステージは1つ以上の専用agentによって管理されます。通常、`aigne doc generate`コマンドによって開始される主要なワークフローは、次のように視覚化できます。
 
 ```d2
 direction: down
 
 Input: {
-  label: "Source Code & Config"
+  label: "ソースコードと設定"
   shape: rectangle
 }
 
 Pipeline: {
-  label: "Core Generation Pipeline"
+  label: "コア生成パイプライン"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
 
   Structure-Planning: {
-    label: "1. Structure Planning"
+    label: "1. 構造計画"
     shape: rectangle
   }
 
   Content-Generation: {
-    label: "2. Content Generation"
+    label: "2. コンテンツ生成"
     shape: rectangle
   }
 
   Saving: {
-    label: "3. Save Documents"
+    label: "3. ドキュメント保存"
     shape: rectangle
   }
 }
 
 User-Feedback: {
-  label: "User Feedback Loop\n(via --feedback flag)"
+  label: "ユーザーフィードバックループ\n(--feedbackフラグ経由)"
   shape: rectangle
 }
 
 Optional-Steps: {
-  label: "Optional Post-Generation Steps"
+  label: "オプションの生成後ステップ"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
   
   Translation: {
-    label: "Translate\n(aigne doc translate)"
+    label: "翻訳\n(aigne doc translate)"
     shape: rectangle
   }
 
   Publishing: {
-    label: "Publish\n(aigne doc publish)"
+    label: "公開\n(aigne doc publish)"
     shape: rectangle
   }
 }
@@ -67,35 +67,35 @@ Pipeline.Structure-Planning -> Pipeline.Content-Generation
 Pipeline.Content-Generation -> Pipeline.Saving
 Pipeline.Saving -> Optional-Steps
 
-User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
-User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
+User-Feedback -> Pipeline.Structure-Planning: "構造の改良"
+User-Feedback -> Pipeline.Content-Generation: "コンテンツの再生成"
 ```
 
-1.  **入力分析**: Agentがソースコードとプロジェクト設定（`aigne.yaml`）を読み込むと、プロセスが開始されます。
+1.  **入力分析**: このプロセスは、agentがソースコードとプロジェクト設定（`aigne.yaml`）を読み込むことから始まります。
 
-2.  **構造計画**: Agentがコードベースを分析し、論理的なドキュメント構造を提案します。プロジェクトの構成と指定されたルールに基づいてアウトラインを作成します。
+2.  **構造計画**: あるagentがコードベースを分析し、論理的なドキュメント構造を提案します。プロジェクトの構成と指定されたルールに基づいてアウトラインを作成します。
 
-3.  **コンテンツ生成**: 構造が確定すると、コンテンツ生成Agentがドキュメント計画の各セクションに詳細なテキスト、コード例、説明を埋め込みます。
+3.  **コンテンツ生成**: 構造が決定されると、コンテンツ生成agentがドキュメントプランの各セクションに詳細なテキスト、コード例、説明を埋め込んでいきます。
 
-4.  **改良と更新**: `aigne doc update` または `aigne doc generate --feedback` を介して入力を提供すると、特定のAgentがアクティブになり、個々のドキュメントを更新したり、全体的な構造を調整したりします。
+4.  **改良と更新**: `aigne doc update`または`aigne doc generate --feedback`を介して入力が提供されると、特定のagentがアクティブになり、個々のドキュメントを更新したり、全体の構造を調整したりします。
 
-5.  **翻訳と公開**: 主要なコンテンツが生成された後、オプションのAgentが多言語翻訳や最終的なドキュメンテーションをウェブプラットフォームに公開するなどのタスクを処理します。
+5.  **翻訳と公開**: 主要なコンテンツが生成された後、オプションのagentが多言語翻訳や最終的なドキュメントをウェブプラットフォームに公開するなどのタスクを処理します。
 
 ## 主要なAI Agent
 
-DocSmithの機能は、プロジェクトの設定で定義されたAgentのコレクションによって提供されます。各Agentには特定の役割があります。以下の表は、主要なAgentとその機能の一部をリストアップしたものです。
+DocSmithの機能は、プロジェクトの設定で定義されたagentのコレクションによって提供されます。各agentには特定の役割があります。以下の表は、主要なagentとその機能の一部をリストアップしたものです。
 
-| 機能的役割               | 主要なAgentファイル                                  | 説明                                                                         |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **構造計画**             | `generate/generate-structure.yaml`                   | ソースコードを分析し、初期のドキュメントアウトラインを提案します。                         |
-| **構造の改良**           | `generate/refine-document-structure.yaml`            | ユーザーのフィードバックに基づいてドキュメント構造を修正します。                             |
-| **コンテンツ生成**         | `update/batch-generate-document.yaml`, `generate-document.yaml` | 各セクションの詳細なコンテンツでドキュメント構造を埋めます。                                 |
-| **翻訳**                 | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 生成されたドキュメンテーションを複数のターゲット言語に翻訳します。                           |
-| **公開**                 | `publish/publish-docs.mjs`                           | Discuss Kitインスタンスへのドキュメント公開プロセスを管理します。                           |
-| **データI/O**              | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | ソースファイルの読み取りと最終的なマークダウンドキュメントのディスクへの書き込みを担当します。 |
+| 機能的役割 | 主要なAgentファイル | 説明 |
+| :--- | :--- | :--- |
+| **構造計画** | `generate/generate-structure.yaml` | ソースコードを分析し、最初のドキュメントアウトラインを提案します。 |
+| **構造の改良** | `generate/refine-document-structure.yaml` | ユーザーのフィードバックに基づいてドキュメントの構造を修正します。 |
+| **コンテンツ生成** | `update/batch-generate-document.yaml`, `update/generate-document.yaml` | ドキュメント構造の各セクションに詳細なコンテンツを埋め込みます。 |
+| **翻訳** | `translate/translate-document.yaml`, `translate/translate-multilingual.yaml` | 生成されたドキュメントを複数のターゲット言語に翻訳します。 |
+| **公開** | `publish/publish-docs.mjs` | ドキュメントをDiscuss Kitインスタンスに公開するプロセスを管理します。 |
+| **データI/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | ソースファイルの読み込みと、最終的なマークダウンドキュメントのディスクへの書き込みを担当します。 |
 
-このAgentベースのアーキテクチャにより、ドキュメンテーションプロセスの各ステップを専門ツールで処理でき、構造化され保守可能なワークフローが保証されます。
+このagentベースのアーキテクチャにより、ドキュメント化プロセスの各ステップを専門のツールで処理できるため、構造化され、保守可能なワークフローが保証されます。
 
 ---
 
-DocSmithが出力の正確性とフォーマットを保証するために講じる対策を理解するには、[品質保証](./advanced-quality-assurance.md)のセクションに進んでください。
+DocSmithが出力の正確性と形式を保証するために講じている対策を理解するには、[品質保証](./advanced-quality-assurance.md)のセクションに進んでください。

package/docs/advanced-how-it-works.md

@@ -1,6 +1,6 @@
 # How It Works
 
-AIGNE DocSmith operates on a multi-agent system built within the AIGNE Framework. Instead of a single monolithic process, it orchestrates a pipeline of specialized AI agents, where each agent is responsible for a specific task. This approach allows for a structured and modular process that transforms source code into complete documentation.
+AIGNE DocSmith operates on a multi-agent system. Instead of a single monolithic process, it orchestrates a pipeline of specialized AI agents, where each agent is responsible for a specific task. This approach allows for a structured and modular process that transforms source code into complete documentation.
 
 The tool is an integral part of the larger AIGNE ecosystem, which provides a platform for developing and deploying AI applications.
 
@@ -85,14 +85,14 @@ User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 
 DocSmith's functionality is provided by a collection of agents defined in the project's configuration. Each agent has a specific role. The table below lists some of the key agents and their functions.
 
-| Functional Role          | Key Agent Files                                      | Description                                                                          |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **Structure Planning**   | `generate/generate-structure.yaml`                   | Analyzes source code to propose the initial document outline.                        |
-| **Structure Refinement** | `generate/refine-document-structure.yaml`            | Modifies the documentation structure based on user feedback.                              |
-| **Content Generation**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | Populates the documentation structure with detailed content for each section.             |
-| **Translation**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | Translates generated documentation into multiple target languages.                   |
-| **Publishing**           | `publish/publish-docs.mjs`                           | Manages the process of publishing documents to Discuss Kit instances.                |
-| **Data I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | Responsible for reading source files and writing the final markdown documents to disk. |
+| Functional Role | Key Agent Files | Description |
+| :--- | :--- | :--- |
+| **Structure Planning** | `generate/generate-structure.yaml` | Analyzes source code to propose the initial document outline. |
+| **Structure Refinement** | `generate/refine-document-structure.yaml` | Modifies the documentation structure based on user feedback. |
+| **Content Generation** | `update/batch-generate-document.yaml`, `update/generate-document.yaml` | Populates the documentation structure with detailed content for each section. |
+| **Translation** | `translate/translate-document.yaml`, `translate/translate-multilingual.yaml` | Translates generated documentation into multiple target languages. |
+| **Publishing** | `publish/publish-docs.mjs` | Manages the process of publishing documents to Discuss Kit instances. |
+| **Data I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | Responsible for reading source files and writing the final markdown documents to disk. |
 
 This agent-based architecture allows each step of the documentation process to be handled by a specialized tool, ensuring a structured and maintainable workflow.