@aigne/doc-smith 0.9.7 → 0.9.8-beta

package/agents/utils/choose-docs.mjs

@@ -5,7 +5,15 @@ import {
   getActionText,
   getMainLanguageFiles,
   processSelectedFiles,
+  readFileContent,
 } from "../../utils/docs-finder-utils.mjs";
+import {
+  hasDiagramContent,
+  hasBananaImages,
+  getDiagramTypeLabels,
+  formatDiagramTypeSuffix,
+} from "../../utils/check-document-has-diagram.mjs";
+import { debug } from "../../utils/debug.mjs";
 import { DOC_ACTION } from "../../utils/constants/index.mjs";
 
 function getFeedbackMessage(action) {
@@ -27,6 +35,9 @@ export default async function chooseDocs(
     reset = false,
     requiredFeedback = true,
     action,
+    shouldUpdateDiagrams = false,
+    shouldAutoSelectDiagrams = false,
+    shouldSyncImages = false,
   },
   options,
 ) {
@@ -48,55 +59,181 @@ export default async function chooseDocs(
         );
       }
 
-      // Convert files to choices with titles
-      const choices = mainLanguageFiles.map((file) => {
-        // Convert filename to flat path to find corresponding documentation structure item
-        const flatName = file.replace(/\.md$/, "").replace(/\.\w+(-\w+)?$/, "");
-        const docItem = documentStructure.find((item) => {
-          const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
-          return itemFlattenedPath === flatName;
-        });
+      // If --diagram-sync flag is set, filter documents by banana images only
+      if (shouldSyncImages) {
+        debug("🔄 Filtering documents with banana images...");
 
-        // Use title if available, otherwise fall back to filename
-        let displayName = docItem?.title;
-        if (displayName) {
-          displayName = `${displayName} (${file})`;
-        } else {
-          displayName = file;
+        // Read content for all files and filter by banana images only
+        const filesWithImages = [];
+        for (const fileName of mainLanguageFiles) {
+          const content = await readFileContent(docsDir, fileName);
+          if (content && hasBananaImages(content)) {
+            filesWithImages.push(fileName);
+          }
         }
 
-        return {
-          name: displayName,
-          value: file,
-        };
-      });
+        if (filesWithImages.length === 0) {
+          debug("ℹ️  No documents found with banana images (DIAGRAM_IMAGE_START markers).");
+          return {
+            selectedDocs: [],
+            feedback: "",
+            selectedPaths: [],
+          };
+        }
+
+        debug(`✅ Found ${filesWithImages.length} document(s) with banana images.`);
+        debug("📋 Auto-selecting all documents with banana images...");
+        // Show diagram types for each document
+        for (const file of filesWithImages) {
+          const content = await readFileContent(docsDir, file);
+          const diagramLabels = content ? getDiagramTypeLabels(content) : [];
+          const diagramSuffix = formatDiagramTypeSuffix(diagramLabels);
+          debug(`   • ${file}${diagramSuffix}`);
+        }
+        selectedFiles = filesWithImages;
+      }
+      // If --diagram flag is set, filter documents by diagram content
+      else if (shouldUpdateDiagrams) {
+        debug("🔄 Filtering documents with diagram content...");
 
-      // Let user select multiple files
-      selectedFiles = await options.prompts.checkbox({
-        message: getActionText("Select documents to {action}:", docAction),
-        source: (term) => {
-          if (!term) return choices;
-
-          return choices.filter((choice) => choice.name.toLowerCase().includes(term.toLowerCase()));
-        },
-        validate: (answer) => {
-          if (answer.length === 0) {
-            return "Please select at least one document";
+        // Read content for all files and filter by diagram content
+        const filesWithDiagrams = [];
+        for (const fileName of mainLanguageFiles) {
+          const content = await readFileContent(docsDir, fileName);
+          if (content && hasDiagramContent(content)) {
+            filesWithDiagrams.push(fileName);
           }
-          return true;
-        },
-      });
+        }
+
+        if (filesWithDiagrams.length === 0) {
+          debug(
+            "ℹ️  No documents found with diagram content (d2 code blocks, placeholders, or diagram images).",
+          );
+          return {
+            selectedDocs: [],
+            feedback: "",
+            selectedPaths: [],
+          };
+        }
+
+        debug(`✅ Found ${filesWithDiagrams.length} document(s) with diagram content.`);
+
+        // If --diagram-all, auto-select all; otherwise let user choose
+        if (shouldAutoSelectDiagrams) {
+          debug("📋 Auto-selecting all documents with diagrams...");
+          // Show diagram types for each document in auto-select mode
+          for (const file of filesWithDiagrams) {
+            const content = await readFileContent(docsDir, file);
+            const diagramLabels = content ? getDiagramTypeLabels(content) : [];
+            const diagramSuffix = formatDiagramTypeSuffix(diagramLabels);
+            debug(`   • ${file}${diagramSuffix}`);
+          }
+          selectedFiles = filesWithDiagrams;
+        } else {
+          // --diagram mode: show only documents with diagrams, let user select
+          const choices = await Promise.all(
+            filesWithDiagrams.map(async (file) => {
+              // Convert filename to flat path to find corresponding documentation structure item
+              const flatName = file.replace(/\.md$/, "").replace(/\.\w+(-\w+)?$/, "");
+              const docItem = documentStructure.find((item) => {
+                const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
+                return itemFlattenedPath === flatName;
+              });
 
-      if (!selectedFiles || selectedFiles.length === 0) {
-        throw new Error("No documents selected");
+              // Read content to detect diagram types
+              const content = await readFileContent(docsDir, file);
+              const diagramLabels = content ? getDiagramTypeLabels(content) : [];
+              const diagramSuffix = formatDiagramTypeSuffix(diagramLabels);
+
+              // Use title if available, otherwise fall back to filename
+              let displayName = docItem?.title;
+              if (displayName) {
+                displayName = `${displayName} (${file})${diagramSuffix}`;
+              } else {
+                displayName = `${file}${diagramSuffix}`;
+              }
+
+              return {
+                name: displayName,
+                value: file,
+              };
+            }),
+          );
+
+          // Let user select multiple files from filtered list
+          selectedFiles = await options.prompts.checkbox({
+            message: getActionText("Select documents with diagrams to {action}:", docAction),
+            source: (term) => {
+              if (!term) return choices;
+
+              return choices.filter((choice) =>
+                choice.name.toLowerCase().includes(term.toLowerCase()),
+              );
+            },
+            validate: (answer) => {
+              if (answer.length === 0) {
+                return "Please select at least one document";
+              }
+              return true;
+            },
+          });
+
+          if (!selectedFiles || selectedFiles.length === 0) {
+            throw new Error("No documents selected");
+          }
+        }
+      } else {
+        // Normal flow: let user select documents from all files
+        // Convert files to choices with titles
+        const choices = mainLanguageFiles.map((file) => {
+          // Convert filename to flat path to find corresponding documentation structure item
+          const flatName = file.replace(/\.md$/, "").replace(/\.\w+(-\w+)?$/, "");
+          const docItem = documentStructure.find((item) => {
+            const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
+            return itemFlattenedPath === flatName;
+          });
+
+          // Use title if available, otherwise fall back to filename
+          let displayName = docItem?.title;
+          if (displayName) {
+            displayName = `${displayName} (${file})`;
+          } else {
+            displayName = file;
+          }
+
+          return {
+            name: displayName,
+            value: file,
+          };
+        });
+
+        // Let user select multiple files
+        selectedFiles = await options.prompts.checkbox({
+          message: getActionText("Select documents to {action}:", docAction),
+          source: (term) => {
+            if (!term) return choices;
+
+            return choices.filter((choice) =>
+              choice.name.toLowerCase().includes(term.toLowerCase()),
+            );
+          },
+          validate: (answer) => {
+            if (answer.length === 0) {
+              return "Please select at least one document";
+            }
+            return true;
+          },
+        });
+
+        if (!selectedFiles || selectedFiles.length === 0) {
+          throw new Error("No documents selected");
+        }
       }
 
       // Process selected files and convert to found items
       foundItems = await processSelectedFiles(selectedFiles, documentStructure, docsDir);
     } catch (error) {
-      console.log(
-        getActionText(`\nFailed to select documents to {action}: ${error.message}`, docAction),
-      );
+      debug(getActionText(`\nFailed to select documents to {action}: ${error.message}`, docAction));
       process.exit(0);
     }
   } else {
@@ -105,7 +242,7 @@ export default async function chooseDocs(
       const foundItem = await findItemByPath(documentStructure, docPath, boardId, docsDir, locale);
 
       if (!foundItem) {
-        console.warn(`⚠️  Item with path "${docPath}" not found in documentStructure`);
+        debug(`⚠️  Item with path "${docPath}" not found in documentStructure`);
         continue;
       }
 
@@ -120,8 +257,14 @@ export default async function chooseDocs(
   }
 
   // Prompt for feedback if not provided
+  // Skip feedback prompt if --diagram, --diagram-all, or --diagram-sync flag is set
   let userFeedback = feedback;
-  if (!userFeedback && (requiredFeedback || foundItems?.length > 1)) {
+  if (
+    !userFeedback &&
+    (requiredFeedback || foundItems?.length > 1) &&
+    !shouldUpdateDiagrams &&
+    !shouldSyncImages
+  ) {
     const feedbackMessage = getFeedbackMessage(docAction);
 
     userFeedback = await options.prompts.input({

package/agents/utils/generate-document-or-skip.mjs

@@ -0,0 +1,41 @@
+/**
+ * Conditionally call generateDocument. If we already have content for diagram-only intents,
+ * skip LLM generation and pass through the existing content.
+ */
+export default async function generateDocumentOrSkip(input, options) {
+  const { intentType, content, skipGenerateDocument } = input;
+
+  const isDiagramIntent =
+    intentType && ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType);
+  const shouldSkip = Boolean(skipGenerateDocument || (isDiagramIntent && content));
+
+  if (shouldSkip) {
+    // Return the existing content and mark the generation as skipped
+    return {
+      ...input,
+      content,
+      documentContent: content,
+      originalContent: content,
+      reviewContent: content,
+    };
+  }
+
+  const generateAgent = options.context?.agents?.["generateDocument"];
+  if (!generateAgent) {
+    throw new Error("generateDocument agent not found");
+  }
+
+  const result = await options.context.invoke(generateAgent, input);
+  const generatedContent = result?.content ?? result;
+
+  return {
+    ...input,
+    ...result,
+    content: generatedContent,
+    documentContent: generatedContent,
+    originalContent: generatedContent,
+    reviewContent: generatedContent,
+  };
+}
+
+generateDocumentOrSkip.task_render_mode = "hide";

package/agents/utils/handle-diagram-operations.mjs

@@ -0,0 +1,263 @@
+import { AIAgent } from "@aigne/core";
+import { pick } from "@aigne/core/utils/type-utils.js";
+import z from "zod";
+import {
+  DIAGRAM_PLACEHOLDER,
+  replaceD2WithPlaceholder,
+  replaceDiagramsWithPlaceholder,
+} from "../../utils/d2-utils.mjs";
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName, userContextAt } from "../../utils/utils.mjs";
+import { debug } from "../../utils/debug.mjs";
+
+/**
+ * Read current document content from file system
+ * Reuses the same logic as initCurrentContent but returns the content
+ * First checks userContext, then reads from file if not in context
+ */
+async function readCurrentContent(input, options) {
+  const { path, docsDir, locale = "en" } = input;
+
+  if (!path || !docsDir) {
+    return null;
+  }
+
+  // First check if content is already in userContext
+  const contentContext = userContextAt(options, `currentContents.${path}`);
+  const existingContent = contentContext.get();
+  if (existingContent) {
+    return existingContent;
+  }
+
+  // If not in context, read from file (same logic as initCurrentContent)
+  try {
+    const fileName = getFileName(path, locale);
+    const content = await readFileContent(docsDir, fileName);
+
+    if (!content) {
+      console.warn(`⚠️  Could not read content from ${fileName}`);
+      return null;
+    }
+
+    // Set in userContext for future use
+    contentContext.set(content);
+
+    return content;
+  } catch (error) {
+    console.warn(`Failed to read current content for ${path}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save document content
+ */
+async function saveDoc(input, options, { content, intentType }) {
+  const saveAgent = options.context?.agents?.["saveDoc"];
+  if (!saveAgent) {
+    console.warn("saveDoc agent not found");
+    return;
+  }
+  await options.context.invoke(saveAgent, {
+    ...pick(input, ["path", "docsDir", "labels", "locale"]),
+    content,
+    intentType, // Pass intentType so saveDoc can handle translation sync
+  });
+}
+
+/**
+ * Handle addDiagram intent
+ */
+async function addDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
+  if (!generateDiagramAgent) {
+    throw new Error("checkGenerateDiagram agent not found");
+  }
+
+  const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
+    ...pick(input, ["locale", "diagramming", "feedback", "path", "docsDir"]),
+    documentContent: currentContent,
+    originalContent: currentContent,
+  });
+
+  const content = generateDiagramResult.content;
+  contentContext.set(content);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "addDiagram" });
+  return { content };
+}
+
+/**
+ * Handle updateDiagram intent
+ */
+async function updateDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  let [content] = replaceD2WithPlaceholder({
+    content: currentContent,
+  });
+
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  if (!generateAgent) {
+    throw new Error("generateDiagram agent not found");
+  }
+
+  const result = await options.context.invoke(generateAgent, {
+    documentContent: content,
+    locale: input.locale,
+    diagramming: input.diagramming || {},
+    feedback: input.feedback,
+    originalContent: currentContent, // Pass original content to find existing diagrams
+    path: input.path,
+    docsDir: input.docsDir,
+  });
+
+  // generateDiagram now returns { content } with image already inserted
+  // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
+  if (result?.content) {
+    content = result.content;
+  }
+
+  contentContext.set(content);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "updateDiagram" });
+  return { content };
+}
+
+/**
+ * Handle deleteDiagram intent
+ */
+async function deleteDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  // Extract diagram index from feedback if provided
+  // This allows deleting a specific diagram when multiple diagrams exist
+  let diagramIndex = input.diagramIndex;
+  if (diagramIndex === undefined && input.feedback) {
+    // Import extractDiagramIndexFromFeedback from replace-d2-with-image.mjs
+    const { extractDiagramIndexFromFeedback } = await import("../create/replace-d2-with-image.mjs");
+    const extractedIndex = extractDiagramIndexFromFeedback(input.feedback);
+    if (extractedIndex !== null) {
+      diagramIndex = extractedIndex;
+      debug(`Extracted diagram index ${diagramIndex} from feedback: "${input.feedback}"`);
+    }
+  }
+
+  // Replace all diagrams (D2 code blocks, generated images, Mermaid) with placeholder
+  // If diagramIndex is provided, only replace that specific diagram
+  // This ensures LLM can identify and remove the diagram regardless of its type
+  const documentContent = replaceDiagramsWithPlaceholder({
+    content: currentContent,
+    diagramIndex,
+  });
+
+  const instructions = `<role>
+Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (based on the user's feedback) to make it easier to understand.
+</role>
+
+<document_content>
+{{documentContent}}
+</document_content>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>
+
+<output_constraints>
+- Do not provide any explanations; include only the document content itself
+</output_constraints>`;
+
+  const deleteAgent = AIAgent.from({
+    name: "deleteDiagram",
+    description: "Remove a diagram from the document content",
+    task_render_mode: "hide",
+    instructions,
+    inputSchema: z.object({
+      documentContent: z.string().describe("Source content of the document"),
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputKey: "message",
+  });
+
+  const { message: content } = await options.context.invoke(deleteAgent, {
+    documentContent,
+    feedback: input.feedback,
+  });
+
+  // Delete associated diagram image files
+  if (input.docsDir) {
+    try {
+      const { deleteDiagramImages } = await import("../../utils/delete-diagram-images.mjs");
+      const { deleted } = await deleteDiagramImages(currentContent, input.path, input.docsDir);
+      if (deleted > 0) {
+        debug(`Deleted ${deleted} diagram image file(s) for ${input.path}`);
+      }
+    } catch (error) {
+      // Don't fail the operation if image deletion fails
+      console.warn(`Failed to delete diagram images: ${error.message}`);
+    }
+  }
+
+  contentContext.set(content);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "deleteDiagram" });
+
+  return { content };
+}
+
+/**
+ * Handle diagram operations based on intent type
+ * Supports: addDiagram, updateDiagram, deleteDiagram
+ */
+export default async function handleDiagramOperations(
+  { intentType, path, docsDir, locale, feedback, diagramming, labels },
+  options,
+) {
+  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
+    throw new Error(`Invalid intent type for diagram operations: ${intentType}`);
+  }
+
+  const input = {
+    path,
+    docsDir,
+    locale,
+    feedback,
+    diagramming,
+    labels,
+  };
+
+  const fnMap = {
+    addDiagram,
+    updateDiagram,
+    deleteDiagram,
+  };
+
+  if (fnMap[intentType]) {
+    const result = await fnMap[intentType](input, options);
+    return result;
+  }
+
+  throw new Error(`Unsupported intent type: ${intentType}`);
+}
+
+handleDiagramOperations.task_render_mode = "hide";

package/agents/utils/load-all-document-content.mjs

@@ -0,0 +1,30 @@
+import pMap from "p-map";
+import { findItemByPath } from "../../utils/docs-finder-utils.mjs";
+
+/**
+ * Loads all document content from the file system based on the provided document structure.
+ *
+ * @async
+ * @function loadAllDocumentContent
+ * @param {Object} params - The parameters object
+ * @param {string} params.docsDir - The root directory path where documents are located
+ * @param {Array<Object>} params.documentStructure - The document structure array containing items with path information
+ * @param {string} params.documentStructure[].path - The file path of each document item
+ * @returns {Promise<Array>} returns.allDocumentContentList - An array of document content items loaded from the file system
+ * @example
+ * const result = await loadAllDocumentContent({
+ *   docsDir: './docs',
+ *   documentStructure: [{ path: 'readme.md' }, { path: 'guide.md' }]
+ * });
+ */
+export default async function loadAllDocumentContent({ docsDir, documentStructure = [] }) {
+  const allDocumentContentList = await pMap(documentStructure, async (item) => {
+    const itemResult = await findItemByPath(documentStructure, item.path, null, docsDir);
+    return itemResult;
+  });
+  return {
+    allDocumentContentList,
+  };
+}
+
+loadAllDocumentContent.taskRenderMode = "hide";

package/agents/utils/load-sources.mjs

@@ -157,8 +157,8 @@ export default async function loadSources(
             mediaItem.width = dimensions.width;
             mediaItem.height = dimensions.height;
 
-            // Filter out images with width less than minImageWidth
-            if (dimensions.width < minImageWidth) {
+            // Filter out images with width less than minImageWidth, but not SVG images
+            if (dimensions.width < minImageWidth && mediaItem.mimeType !== "image/svg+xml") {
               filteredImageCount++;
               console.log(
                 `Ignored image: ${fileName} (${dimensions.width}x${dimensions.height}px < ${minImageWidth}px minimum)`,

package/agents/utils/read-current-document-content.mjs

@@ -0,0 +1,46 @@
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName } from "../../utils/utils.mjs";
+
+/**
+ * Read current document content from file system
+ * Used when skipping document generation (e.g., for diagram-only updates)
+ * Only reads content if intentType is diagram-related, otherwise returns input unchanged
+ */
+export default async function readCurrentDocumentContent(input) {
+  const { path, docsDir, locale = "en", intentType } = input;
+
+  // Only read content if intentType is diagram-related
+  // Otherwise, return input unchanged to allow document generation to proceed
+  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
+    return input;
+  }
+
+  if (!path || !docsDir) {
+    return input;
+  }
+
+  try {
+    // Read document content using the same utility as other parts of the system
+    const fileName = getFileName(path, locale);
+    const content = await readFileContent(docsDir, fileName);
+
+    if (!content) {
+      console.warn(`⚠️  Could not read content from ${fileName}`);
+      return input;
+    }
+
+    // Return content as both content, documentContent, and originalContent
+    // This matches the structure expected by downstream agents
+    return {
+      ...input,
+      content,
+      documentContent: content,
+      originalContent: content,
+    };
+  } catch (error) {
+    console.warn(`Failed to read current content for ${path}: ${error.message}`);
+    return input;
+  }
+}
+
+readCurrentDocumentContent.task_render_mode = "hide";