@aigne/doc-smith 0.9.7-beta.3 → 0.9.8-alpha.0

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
@@ -33,20 +39,32 @@ skills:
 input_schema:
   type: object
   properties:
-    glossary:
-      type: string
-      description: Glossary file for consistent terminology (use @filename.md)
+    # glossary:
+    #   type: string
+    #   description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Documents to update
+      description: Documents to update, use document path in document structure to specify, eg ["/getting-started", "/overview"]
     feedback:
       type: string
       description: Tell us what to change in this content
-    reset:
+    isChat:
       type: boolean
-      description: Start fresh - ignore previous versions
+      description: Whether the update is from chat
+    # 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:

package/agents/update/sync-images-and-exit.mjs

@@ -0,0 +1,148 @@
+import { syncDiagramToTranslations } from "../../utils/sync-diagram-to-translations.mjs";
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName } from "../../utils/utils.mjs";
+import { debug } from "../../utils/debug.mjs";
+
+/**
+ * Sync images to translations and exit if shouldSyncImages is true
+ * Otherwise, passes through input for normal update flow
+ *
+ * This agent combines:
+ * - Image synchronization logic
+ * - Flow routing (sync vs normal update)
+ * - Early exit handling
+ */
+export default async function syncImagesAndExit(input, options) {
+  // If shouldSyncImages is false, pass through for normal update flow
+  if (!input.shouldSyncImages) {
+    return input;
+  }
+
+  // Sync images flow
+  const { selectedDocs = [], docsDir, locale = "en" } = input;
+
+  if (!docsDir) {
+    throw new Error("docsDir is required for image sync. Please ensure config is loaded.");
+  }
+
+  if (!Array.isArray(selectedDocs) || selectedDocs.length === 0) {
+    const actionSuccessAgent = options.context?.agents?.["actionSuccess"];
+    if (actionSuccessAgent) {
+      await options.context.invoke(actionSuccessAgent, {
+        action: "ℹ️  No documents selected for image sync",
+      });
+    }
+    // Exit normally to prevent passing to next steps
+    process.exit(0);
+  }
+
+  const results = {
+    updated: 0,
+    skipped: 0,
+    errors: [],
+  };
+
+  // Process each document
+  for (const doc of selectedDocs) {
+    try {
+      // Use content from doc if available, otherwise read from file
+      let mainContent = doc.content;
+      if (!mainContent) {
+        const mainFileName = getFileName(doc.path, locale);
+        mainContent = await readFileContent(docsDir, mainFileName);
+      }
+
+      if (!mainContent) {
+        debug(`⚠️  Could not read main document: ${doc.path}`);
+        results.skipped++;
+        continue;
+      }
+
+      // Sync images to translation documents
+      const syncResult = await syncDiagramToTranslations(mainContent, doc.path, docsDir, locale);
+
+      results.updated += syncResult.updated;
+      results.skipped += syncResult.skipped;
+      results.errors.push(...syncResult.errors);
+
+      if (syncResult.updated > 0) {
+        debug(`✅ Synced images from ${doc.path} to ${syncResult.updated} translation file(s)`);
+      } else if (syncResult.skipped > 0) {
+        debug(
+          `⏭️  No changes needed for ${doc.path} (${syncResult.skipped} translation file(s) already in sync)`,
+        );
+      }
+    } catch (error) {
+      debug(`❌ Error syncing images for ${doc.path}: ${error.message}`);
+      results.errors.push({
+        doc: doc.path,
+        error: error.message,
+      });
+    }
+  }
+
+  // Generate success message
+  const message = `✅ Image sync completed: ${results.updated} translation file(s) updated, ${results.skipped} skipped${
+    results.errors.length > 0 ? `, ${results.errors.length} error(s)` : ""
+  }`;
+
+  // Show success message
+  const actionSuccessAgent = options.context?.agents?.["actionSuccess"];
+  if (actionSuccessAgent) {
+    await options.context.invoke(actionSuccessAgent, {
+      action: message,
+    });
+  }
+
+  // Exit normally to prevent passing to next steps and avoid validation errors
+  // This ensures a clean exit after successful image sync
+  process.exit(0);
+}
+
+syncImagesAndExit.input_schema = {
+  type: "object",
+  properties: {
+    shouldSyncImages: {
+      type: "boolean",
+      description: "Whether to trigger image sync to translations",
+    },
+    selectedDocs: {
+      type: "array",
+      description: "Array of selected documents to sync images from",
+    },
+    docsDir: {
+      type: "string",
+      description: "Documentation directory where documents are stored",
+    },
+    locale: {
+      type: "string",
+      description: "Main language locale (e.g., 'en', 'zh')",
+      default: "en",
+    },
+  },
+  required: ["shouldSyncImages"],
+};
+
+syncImagesAndExit.output_schema = {
+  type: "object",
+  properties: {
+    message: {
+      type: "string",
+      description: "Summary message of the sync operation",
+    },
+    updated: {
+      type: "number",
+      description: "Number of translation files successfully updated",
+    },
+    skipped: {
+      type: "number",
+      description: "Number of translation files skipped (no changes needed)",
+    },
+    errors: {
+      type: "array",
+      description: "Array of errors encountered during sync",
+    },
+  },
+};
+
+syncImagesAndExit.task_render_mode = "hide";