@aigne/doc-smith 0.9.7 → 0.9.8-beta

package/agents/init/index.mjs

@@ -7,6 +7,7 @@ import {
   DEFAULT_REASONING_EFFORT_LEVEL,
   DEFAULT_THINKING_EFFORT_LEVEL,
   DEPTH_RECOMMENDATION_LOGIC,
+  DIAGRAM_STYLES,
   DOCUMENT_STYLES,
   DOCUMENTATION_DEPTH,
   PURPOSE_TO_KNOWLEDGE_MAPPING,
@@ -621,6 +622,21 @@ ${modelSection}
   }).trim();
   yaml += `# minImageWidth: Only images wider than this value (in pixels) will be used in the page generation.\n${mediaInfoSection}\n`;
 
+  // Diagramming configuration
+  yaml += "\n# Diagramming Configuration\n";
+  yaml +=
+    "# diagramming.effort: AI effort level for diagramming, 0-10, larger value means fewer diagrams\n";
+  yaml += "diagramming:\n";
+  yaml += "  effort: 5  # AI effort level for diagramming, 0-10, large is less diagram\n";
+  yaml +=
+    "  # Default diagram style: The primary style to use when no style is specified in feedback\n";
+  yaml += "  # This style will be applied if feedback doesn't specify a different style\n";
+  yaml += "  # Available options:\n";
+  Object.entries(DIAGRAM_STYLES).forEach(([key, style]) => {
+    yaml += `  #   ${key.padEnd(16)} - ${style.name}: ${style.description}\n`;
+  });
+  yaml += '  # style: "modern"\n';
+
   return yaml;
 }
 

package/agents/media/batch-generate-media-description.yaml

@@ -25,6 +25,8 @@ input_schema:
             type: string
           type:
             type: string
+          svgContent:
+            type: string
           mediaFile:
             type: array
             items:

package/agents/media/generate-media-description.yaml

@@ -29,6 +29,9 @@ input_schema:
     type:
       type: string
       description: Media type (image/video)
+    svgContent:
+      type: string
+      description: SVG content
     mediaFile:
       type: array
       items:

package/agents/media/load-media-description.mjs

@@ -6,6 +6,7 @@ import { parse, stringify } from "yaml";
 import { getMediaDescriptionCachePath } from "../../utils/file-utils.mjs";
 
 const SIZE_THRESHOLD = 10 * 1024 * 1024; // 10MB
+const SVG_SIZE_THRESHOLD = 50 * 1024; // 50KB for SVG files
 
 // Supported MIME types for Gemini AI
 const SUPPORTED_IMAGE_TYPES = new Set([
@@ -16,6 +17,8 @@ const SUPPORTED_IMAGE_TYPES = new Set([
   "image/heif",
 ]);
 
+const SUPPORTED_SVG_TYPES = new Set(["image/svg+xml"]);
+
 const SUPPORTED_VIDEO_TYPES = new Set([
   "video/mp4",
   "video/mpeg",
@@ -60,10 +63,10 @@ async function calculateMediaHash(absolutePath) {
 export default async function loadMediaDescription(input, options) {
   const { mediaFiles = [], docsDir } = input;
 
-  // Filter to get image and video files with supported MIME types
+  // Filter to get image, video and svg files with supported MIME types
   const mediaFilesToProcess = mediaFiles.filter((file) => {
     if (file.type === "image") {
-      return SUPPORTED_IMAGE_TYPES.has(file.mimeType);
+      return SUPPORTED_IMAGE_TYPES.has(file.mimeType) || SUPPORTED_SVG_TYPES.has(file.mimeType);
     }
     if (file.type === "video") {
       return SUPPORTED_VIDEO_TYPES.has(file.mimeType);
@@ -101,19 +104,45 @@ export default async function loadMediaDescription(input, options) {
     mediaHashMap.set(mediaFile.path, mediaHash);
 
     if (!cache[mediaHash]) {
-      mediaToDescribe.push({
-        ...mediaFile,
-        hash: mediaHash,
-        path: mediaFile.path,
-        mediaFile: [
-          {
-            type: "local",
-            path: absolutePath,
-            filename: mediaFile.name,
-            mimeType: mediaFile.mimeType,
-          },
-        ],
-      });
+      const isSvg = SUPPORTED_SVG_TYPES.has(mediaFile.mimeType);
+
+      if (isSvg) {
+        // For SVG files, check size and read content
+        try {
+          const stats = await stat(absolutePath);
+          if (stats.size > SVG_SIZE_THRESHOLD) {
+            console.warn(
+              `SVG file ${mediaFile.path} exceeds ${SVG_SIZE_THRESHOLD / 1024}KB limit, skipping`,
+            );
+            continue;
+          }
+
+          const svgContent = await readFile(absolutePath, "utf8");
+          mediaToDescribe.push({
+            ...mediaFile,
+            hash: mediaHash,
+            path: mediaFile.path,
+            svgContent,
+          });
+        } catch (error) {
+          console.warn(`Failed to read SVG file ${mediaFile.path}:`, error.message);
+        }
+      } else {
+        // For non-SVG media files, use mediaFile field
+        mediaToDescribe.push({
+          ...mediaFile,
+          hash: mediaHash,
+          path: mediaFile.path,
+          mediaFile: [
+            {
+              type: "local",
+              path: absolutePath,
+              filename: mediaFile.name,
+              mimeType: mediaFile.mimeType,
+            },
+          ],
+        });
+      }
     }
   }
 

package/agents/publish/publish-docs.mjs

@@ -16,7 +16,7 @@ import {
   TMP_DIR,
   TMP_DOCS_DIR,
 } from "../../utils/constants/index.mjs";
-import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
+import { 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";
@@ -53,9 +53,6 @@ export default async function publishDocs(
     });
     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 useEnvAppUrl = !!(

package/agents/update/check-diagram-flag.mjs

@@ -0,0 +1,116 @@
+/**
+ * Check if --diagram or --diagram-all flag is set via command line arguments or environment variable
+ * Returns the flag values and passes through all input
+ *
+ * --diagram: Filter to show only documents with diagrams, let user select
+ * --diagram-all: Auto-select all documents with diagrams, no user selection
+ */
+export default function checkDiagramFlag(input) {
+  let shouldUpdateDiagrams = false;
+  let shouldAutoSelectDiagrams = false;
+
+  // Priority order: command line args > input params > environment variables
+  // Check command line arguments first (highest priority)
+  if (process.argv) {
+    // Check for --diagram-all or -da (exact match)
+    const hasDiagramAllFlag = process.argv.some((arg) => arg === "--diagram-all" || arg === "-da");
+
+    const hasDiagramFlag = process.argv.some((arg) => arg === "--diagram" || arg === "-d");
+
+    if (hasDiagramAllFlag) {
+      shouldUpdateDiagrams = true;
+      shouldAutoSelectDiagrams = true;
+      // Return early if CLI arg found (highest priority)
+      return {
+        ...input,
+        shouldUpdateDiagrams,
+        shouldAutoSelectDiagrams,
+      };
+    } else if (hasDiagramFlag) {
+      shouldUpdateDiagrams = true;
+      shouldAutoSelectDiagrams = false;
+      // Return early if CLI arg found (highest priority)
+      return {
+        ...input,
+        shouldUpdateDiagrams,
+        shouldAutoSelectDiagrams,
+      };
+    }
+  }
+
+  // Check input parameter (second priority - CLI framework might parse --diagram-all as separate parameter)
+  if (input["diagram-all"] === true || input["diagram-all"] === "true") {
+    shouldUpdateDiagrams = true;
+    shouldAutoSelectDiagrams = true;
+    // Return early if input param found (second priority)
+    return {
+      ...input,
+      shouldUpdateDiagrams,
+      shouldAutoSelectDiagrams,
+    };
+  } else if (input.diagram === true || input.diagram === "true") {
+    shouldUpdateDiagrams = true;
+    shouldAutoSelectDiagrams = false;
+    // Return early if input param found (second priority)
+    return {
+      ...input,
+      shouldUpdateDiagrams,
+      shouldAutoSelectDiagrams,
+    };
+  }
+
+  // Check environment variable (lowest priority)
+  if (
+    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "all" ||
+    process.env.DOC_SMITH_UPDATE_DIAGRAMS_ALL === "true" ||
+    process.env.DOC_SMITH_UPDATE_DIAGRAMS_ALL === "1"
+  ) {
+    shouldUpdateDiagrams = true;
+    shouldAutoSelectDiagrams = true;
+  } else if (
+    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "true" ||
+    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "1"
+  ) {
+    shouldUpdateDiagrams = true;
+    shouldAutoSelectDiagrams = false;
+  }
+
+  // Return all input plus the flags
+  return {
+    ...input,
+    shouldUpdateDiagrams,
+    shouldAutoSelectDiagrams,
+  };
+}
+
+checkDiagramFlag.input_schema = {
+  type: "object",
+  properties: {
+    diagram: {
+      type: ["boolean", "string"],
+      description:
+        "Flag to trigger diagram update: true for user selection (can also use --diagram CLI arg)",
+    },
+    "diagram-all": {
+      type: ["boolean", "string"],
+      description:
+        "Flag to auto-select all documents with diagrams (can also use --diagram-all CLI arg)",
+    },
+  },
+};
+
+checkDiagramFlag.output_schema = {
+  type: "object",
+  properties: {
+    shouldUpdateDiagrams: {
+      type: "boolean",
+      description: "Whether to filter and update diagrams",
+    },
+    shouldAutoSelectDiagrams: {
+      type: "boolean",
+      description:
+        "Whether to auto-select all documents with diagrams (true for --diagram-all, false for --diagram)",
+    },
+  },
+  required: ["shouldUpdateDiagrams", "shouldAutoSelectDiagrams"],
+};

package/agents/update/check-document.mjs

@@ -31,7 +31,6 @@ export default async function checkDocument(
   const filePath = join(docsDir, fileFullName);
   let detailGenerated = true;
   let fileContent = null;
-
   try {
     await access(filePath);
     // If file exists, read its content for validation

package/agents/update/check-generate-diagram.mjs

@@ -1,4 +1,4 @@
-import { DIAGRAM_PLACEHOLDER, replacePlaceholderWithD2 } from "../../utils/d2-utils.mjs";
+import { hasDiagramContent } from "../../utils/check-document-has-diagram.mjs";
 
 const DEFAULT_DIAGRAMMING_EFFORT = 5;
 const MIN_DIAGRAMMING_EFFORT = 0;
@@ -11,23 +11,39 @@ export default async function checkGenerateDiagram(
     feedback,
     detailFeedback,
     originalContent,
-    path: docPath,
     diagramming,
+    path,
+    docsDir,
+    shouldUpdateDiagrams,
   },
   options,
 ) {
   let content = documentContent;
-  let diagramSourceCode;
   let skipGenerateDiagram = false;
 
-  const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
+  // If --diagram flag is set and document already has d2 code blocks,
+  // skip preCheck and directly replace existing diagrams
+  // This is because when using --diagram/--diagram-all, the user explicitly wants to update diagrams,
+  // so we should skip the "do we need to generate diagram" check and directly proceed to replacement
+  const hasExistingDiagrams = originalContent && hasDiagramContent(originalContent);
 
-  const preCheckResult = await options.context.invoke(preCheckAgent, {
-    documentContent,
-    feedback,
-    detailFeedback,
-    previousGenerationContent: originalContent,
-  });
+  // Skip preCheck if:
+  // 1. Using --diagram/--diagram-all flag (shouldUpdateDiagrams === true) AND
+  // 2. Document already has d2 code blocks (hasExistingDiagrams === true)
+  // This means user explicitly wants to update existing diagrams, no need to check if diagram is needed
+  const shouldSkipPreCheck = shouldUpdateDiagrams === true && hasExistingDiagrams;
+
+  let preCheckResult = { details: [], content: null };
+  if (!shouldSkipPreCheck) {
+    const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
+
+    preCheckResult = await options.context.invoke(preCheckAgent, {
+      documentContent,
+      feedback,
+      detailFeedback,
+      previousGenerationContent: originalContent,
+    });
+  }
 
   const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
   if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
@@ -47,7 +63,11 @@ export default async function checkGenerateDiagram(
     );
   }
 
-  if (totalScore <= diagrammingEffort) {
+  // If we skipped preCheck because document has existing diagrams and --diagram flag is set,
+  // we should NOT skip generating diagram (we need to replace existing ones)
+  if (shouldSkipPreCheck) {
+    skipGenerateDiagram = false;
+  } else if (totalScore <= diagrammingEffort) {
     skipGenerateDiagram = true;
   }
 
@@ -56,30 +76,28 @@ export default async function checkGenerateDiagram(
   } else {
     try {
       const generateAgent = options.context?.agents?.["generateDiagram"];
-      ({ diagramSourceCode } = await options.context.invoke(generateAgent, {
+      const result = await options.context.invoke(generateAgent, {
         documentContent: content,
         locale,
-      }));
-    } catch (error) {
-      diagramSourceCode = "";
-      skipGenerateDiagram = true;
-      console.log(`⚠️  Skip generate any diagram for ${docPath}: ${error.message}`);
-    }
+        diagramming: diagramming || {},
+        feedback: feedback || "",
+        originalContent: originalContent || documentContent,
+        path,
+        docsDir,
+      });
 
-    if (diagramSourceCode && !skipGenerateDiagram) {
-      if (content.includes(DIAGRAM_PLACEHOLDER)) {
-        content = replacePlaceholderWithD2({
-          content,
-          diagramSourceCode,
-        });
+      // generateDiagram now returns { content } with image already inserted
+      // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
+      if (result?.content) {
+        content = result.content;
       } else {
-        const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
-        ({ content } = await options.context.invoke(mergeAgent, {
-          diagramSourceCode,
-          content,
-        }));
+        // Fallback: if no content returned, use original document content
+        content = documentContent;
       }
-    } else {
+    } catch (error) {
+      skipGenerateDiagram = true;
+      console.log(`⚠️  Skip generate any diagram: ${error.message}`);
+      // On error, return original document content
       content = documentContent;
     }
   }

package/agents/update/check-sync-image-flag.mjs

@@ -0,0 +1,55 @@
+/**
+ * Check if --diagram-sync flag is set via command line arguments or environment variable
+ * Returns the flag value and passes through all input
+ *
+ * --diagram-sync: Auto-select all documents with banana images and sync to translations
+ */
+export default function checkSyncImageFlag(input) {
+  let shouldSyncImages = false;
+
+  // Check command line arguments first (highest priority)
+  if (process.argv) {
+    const hasSyncImageFlag = process.argv.some((arg) => arg === "--diagram-sync" || arg === "-ds");
+    if (hasSyncImageFlag) {
+      shouldSyncImages = true;
+    }
+  }
+
+  // Check input parameter
+  if (input["diagram-sync"] === true || input.diagramSync === true) {
+    shouldSyncImages = true;
+  }
+
+  // Check environment variable
+  if (process.env.DOC_SMITH_SYNC_IMAGES === "true" || process.env.DOC_SMITH_SYNC_IMAGES === "1") {
+    shouldSyncImages = true;
+  }
+
+  // Return all input plus the flag
+  return {
+    ...input,
+    shouldSyncImages,
+  };
+}
+
+checkSyncImageFlag.input_schema = {
+  type: "object",
+  properties: {
+    "diagram-sync": {
+      type: ["boolean", "string"],
+      description:
+        "Flag to sync images to translations (can also use --diagram-sync CLI arg or DOC_SMITH_SYNC_IMAGES env var)",
+    },
+  },
+};
+
+checkSyncImageFlag.output_schema = {
+  type: "object",
+  properties: {
+    shouldSyncImages: {
+      type: "boolean",
+      description: "Whether to sync images to translations",
+    },
+  },
+  required: ["shouldSyncImages"],
+};

package/agents/update/check-update-is-single.mjs

@@ -29,6 +29,17 @@ export default async function checkUpdateIsSingle({ selectedDocs, ...rest }, opt
       ...rest,
     });
 
+    // For batch updates, preserve selectedDocs and other context for save-and-translate-document
+    // batchUpdateDocument returns an array of results, but save-and-translate-document needs selectedDocs
+    if (agentName === "batchUpdateDocument") {
+      return {
+        ...rest,
+        selectedDocs, // Preserve selectedDocs for save-and-translate-document.mjs
+        result, // Include the batch update results
+      };
+    }
+
+    // For single document updates, return result as-is
     return result;
   } catch (error) {
     console.error(

package/agents/update/generate-diagram.yaml

@@ -2,13 +2,22 @@ type: team
 task_render_mode: collapse
 name: generateDiagram
 skills:
-  - ../create/draw-diagram.yaml
-  - ../create/wrap-diagram-code.mjs
-reflection:
-  reviewer: ../create/check-diagram.mjs
-  is_approved: isValid
-  max_iterations: 5
-  return_last_on_max_iterations: false
+  # Step 1: Analyze document content to determine diagram type and style
+  - ../create/analyze-diagram-type.mjs
+  # Step 2: Transform output for image generation agent (map aspectRatio to ratio, add size)
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        {
+          "ratio": aspectRatio,
+          "size": "1K"
+        }
+      ])
+  # Step 3: Generate diagram image directly with unified agent
+  - ../create/generate-diagram-image.yaml
+  # Step 4: Replace placeholder with generated image
+  - ../create/replace-d2-with-image.mjs
 input_schema:
   type: object
   properties:
@@ -19,11 +28,36 @@ input_schema:
       type: string
       description: Language for diagram labels and text
       default: en
+    diagramming:
+      type: object
+      description: Diagramming configuration
+      properties:
+        style:
+          type: string
+          description: Default diagram style to use when no style is specified in feedback
+    feedback:
+      type: string
+      description: User feedback that may contain style or type preferences, or diagram index (e.g., 'use anthropomorphic style', 'update the second diagram')
+      default: ""
+    originalContent:
+      type: string
+      description: Original document content before modifications. Used to find existing diagrams when updating (may contain DIAGRAM_IMAGE_START, ```d2, or ```mermaid code blocks)
+    diagramIndex:
+      type: number
+      description: Index of the diagram to replace (0-based). If not provided, will try to extract from feedback.
+    path:
+      type: string
+      description: Document path (e.g., "guides/getting-started.md") used for generating image filename
+    docsDir:
+      type: string
+      description: Documentation directory where assets will be saved (relative to project root)
   required:
     - documentContent
 output_schema:
   type: object
   properties:
-    diagramSourceCode:
+    content:
       type: string
-      description: The **diagram source code** generated from the input text.
+      description: The document content with D2 code blocks replaced by generated diagram image.
+  required:
+    - content

package/agents/update/generate-document.yaml

@@ -32,6 +32,9 @@ input_schema:
       type: string
     path:
       type: string
+    originalContent:
+      type: string
+      description: The original content of the document before update
     parentId:
       type:
         - string
@@ -42,6 +45,12 @@ input_schema:
     additionalInformation:
       type: string
       description: Additional supplementary information
+    intentType:
+      type:
+        - string
+        - "null"
+      description: User intent type analyzed from feedback (addDiagram, updateDiagram, deleteDiagram, updateDocument). Can be null if not specified.
+      enum: ["addDiagram", "updateDiagram", "deleteDiagram", "updateDocument", null]
   required:
     - rules
     - detailDataSource

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

@@ -3,6 +3,10 @@ name: handleDocumentUpdate
 description: Update a document in a batch
 skills:
   - ../utils/transform-detail-data-sources.mjs
+  # Check if document generation should be skipped (if content already exists)
+  # If intentType is diagram-related and content exists, mark skipGenerateDocument so generation can be short-circuited
+  - url: ../utils/skip-if-content-exists.mjs
+  # Generate document content (skipped when skipGenerateDocument is true and content exists)
   - type: team
     task_render_mode: collapse
     name: generateDocumentContent
@@ -10,24 +14,22 @@ skills:
       - url: ../utils/find-user-preferences-by-path.mjs
         default_input:
           scope: document
-      - ../update/generate-document.yaml
-      - type: transform
-        jsonata: |
-          $merge([
-            $,
-            { "reviewContent": content }
-          ])
+      - ../utils/generate-document-or-skip.mjs
     reflection:
       reviewer: ../utils/check-detail-result.mjs
       is_approved: isApproved
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate document for '{{ title }}'
+  # Ensure content, documentContent, and originalContent are set
   - type: transform
     jsonata: |
       $merge([
         $,
-        { "documentContent": content }
+        { 
+          "documentContent": content,
+          "originalContent": content
+        }
       ])
   - ./check-generate-diagram.mjs
   # - ../generate/merge-diagram.yaml

package/agents/update/index.yaml

@@ -2,7 +2,7 @@ type: team
 name: update
 alias:
   - up
-description: Update specific documents and their translations
+description: Update specific documents and their translations. Use --diagram to filter and select documents with diagrams, --diagram-all to auto-update all diagrams, or --diagram-sync to sync existing images to translations.
 skills:
   - url: ../init/index.mjs
     default_input:
@@ -19,12 +19,18 @@ skills:
           'documentStructure': originalDocumentStructure
         }
       ])
+  # Check if --diagram or --diagram-all flag is set
+  - url: ../update/check-diagram-flag.mjs
+  # Check if --diagram-sync flag is set
+  - url: ../update/check-sync-image-flag.mjs
   - url: ../utils/choose-docs.mjs
     default_input:
       requiredFeedback: false
   - ../utils/format-document-structure.mjs
   - ../utils/ensure-document-icons.mjs
   - ../media/load-media-description.mjs
+  - ../utils/analyze-feedback-intent.mjs
+  - ../update/sync-images-and-exit.mjs
   - ../update/check-update-is-single.mjs
   - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs
@@ -47,6 +53,15 @@ input_schema:
     reset:
       type: boolean
       description: Start fresh - ignore previous versions
+    diagram:
+      type: ["boolean", "string"]
+      description: "Flag to update diagrams: true for user selection (can also use --diagram CLI arg)"
+    "diagram-all":
+      type: ["boolean", "string"]
+      description: "Flag to auto-select all documents with diagrams (can also use --diagram-all CLI arg)"
+    "diagram-sync":
+      type: ["boolean", "string"]
+      description: "Flag to sync existing banana images to translations (can also use --diagram-sync CLI arg or DOC_SMITH_SYNC_IMAGES env var)"
 output_schema:
   type: object
   properties: