@aigne/doc-smith 0.9.9-beta → 0.9.9-beta.1

package/agents/localize/translate-multilingual.yaml

@@ -1,7 +1,10 @@
 type: team
 name: translateMultilingual
-description: Batch translate documents to multiple languages
+description: Batch translate documents to multiple languages. Use --diagram to translate only diagram images without translating document content.
 skills:
+  # Step 1: Check --diagram flag and determine if we should translate diagrams only
+  - url: ./translate-or-skip-diagram.mjs
+  # Translate document content (only if translation is not already set)
   - type: team
     task_render_mode: collapse
     name: translate
@@ -9,20 +12,20 @@ skills:
       - url: ../utils/find-user-preferences-by-path.mjs
         default_input:
           scope: translation
-      - ../localize/translate-document.yaml
-      - type: transform
-        jsonata: |
-          $merge([
-            $,
-            { "reviewContent": translation }
-          ])
+      # Step 2: Cache diagram images for translation (before document translation)
+      # Checks --diagram flag and timestamps to determine if images need translation
+      - url: ../../utils/translate-diagram-images.mjs
+      # Step 3: Translate document content
+      - url: ./translate-document-wrapper.mjs
+      # Step 4: Replace cached diagram images and set review content
+      - url: ./set-review-content.mjs
     reflection:
       reviewer: ../utils/check-detail-result.mjs
       is_approved: isApproved
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Translate '{{ title }}' to '{{ language }}'
-  - ../utils/save-doc-translation.mjs
+  - url: ./save-doc-translation-or-skip.mjs
 input_schema:
   type: object
   properties:
@@ -35,6 +38,9 @@ input_schema:
             type: string
     content:
       type: string
+    diagram:
+      type: boolean
+      description: Translate only diagram images without translating document content
 output_schema:
   type: object
   properties:

package/agents/localize/translate-or-skip-diagram.mjs

@@ -0,0 +1,52 @@
+import { debug } from "../../utils/debug.mjs";
+
+/**
+ * Check --diagram flag and conditionally translate document
+ * If --diagram is set, skip document translation and only translate images
+ * Otherwise, proceed with normal document translation
+ */
+export default async function translateOrSkipDiagram(input) {
+  // Check if --diagram flag is set
+  let shouldTranslateDiagramsOnly = false;
+
+  if (process.argv) {
+    const hasDiagramFlag = process.argv.some((arg) => arg === "--diagram" || arg === "-d");
+    if (hasDiagramFlag) {
+      shouldTranslateDiagramsOnly = true;
+    }
+  }
+
+  if (input.diagram === true || input.diagram === "true") {
+    shouldTranslateDiagramsOnly = true;
+  }
+
+  if (
+    process.env.DOC_SMITH_TRANSLATE_DIAGRAMS_ONLY === "true" ||
+    process.env.DOC_SMITH_TRANSLATE_DIAGRAMS_ONLY === "1"
+  ) {
+    shouldTranslateDiagramsOnly = true;
+  }
+
+  // If --diagram flag is set, skip document translation
+  if (shouldTranslateDiagramsOnly) {
+    debug("⏭️  --diagram flag set: skipping document translation, only translating images");
+    // Set translation to content to skip actual translation
+    // Also set isApproved to true to skip reflection check
+    return {
+      ...input,
+      shouldTranslateDiagramsOnly: true,
+      translation: input.content || "",
+      reviewContent: input.content || "",
+      isApproved: true, // Skip reflection check
+    };
+  }
+
+  // Otherwise, proceed with normal translation
+  // Don't call translateDocument here - let translate-document-wrapper.mjs handle it
+  return {
+    ...input,
+    shouldTranslateDiagramsOnly: false,
+  };
+}
+
+translateOrSkipDiagram.task_render_mode = "hide";

package/agents/publish/translate-meta.mjs

@@ -6,6 +6,8 @@ import { parse as yamlParse, stringify as yamlStringify } from "yaml";
 import z from "zod";
 
 import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
+import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
+import { saveValueToConfig } from "../../utils/utils.mjs";
 
 export default async function translateMeta(
   { projectName, projectDesc, locale, translateLanguages = [] },
@@ -13,6 +15,41 @@ export default async function translateMeta(
 ) {
   const languages = [...new Set([...(locale ? [locale] : []), ...(translateLanguages || [])])];
 
+  // If projectDesc is empty, first try to load overview.md, then fallback to structure-plan.json
+  let finalProjectDesc = projectDesc;
+  if (!finalProjectDesc || finalProjectDesc.trim() === "") {
+    // First, try to read overview.md
+    const overviewFilePath = join(DOC_SMITH_DIR, "docs", "overview.md");
+    const overviewExists = await fs.pathExists(overviewFilePath);
+
+    if (overviewExists) {
+      try {
+        const overviewContent = await fs.readFile(overviewFilePath, "utf-8");
+        finalProjectDesc = overviewContent;
+      } catch {
+        // If reading fails, fallback to structure-plan.json
+        finalProjectDesc = "";
+      }
+    } else {
+      try {
+        const outputDir = join(DOC_SMITH_DIR, "output");
+        const documentStructure = await loadDocumentStructure(outputDir);
+        if (documentStructure && Array.isArray(documentStructure)) {
+          const overviewItem =
+            documentStructure.find(
+              (item) => item.title === "Overview" || item.path === "/overview",
+            ) || documentStructure[0];
+          if (overviewItem?.description) {
+            finalProjectDesc = overviewItem.description;
+          }
+        }
+      } catch {
+        // If structure-plan.json doesn't exist or parsing fails, keep empty desc
+        finalProjectDesc = "";
+      }
+    }
+  }
+
   const translationCacheFilePath = join(DOC_SMITH_DIR, "translation-cache.yaml");
   await fs.ensureFile(translationCacheFilePath);
   const translationCache = await fs.readFile(translationCacheFilePath, "utf-8");
@@ -43,15 +80,19 @@ export default async function translateMeta(
     inputKey: "message",
     outputSchema: z.object({
       title: titleTranslationSchema.describe("Translated titles with language codes as keys"),
-      desc: descTranslationSchema.describe("Translated descriptions with language codes as keys"),
+      desc: descTranslationSchema.describe(
+        "Translated descriptions with language codes as keys. Each description MUST be within 100 characters.",
+      ),
     }),
   });
   if (titleLanguages.length > 0 || descLanguages.length > 0) {
     const translatedMetadata = await options.context.invoke(agent, {
       message: `Translate the following title and description into all target languages except the source language. Provide the translations in a JSON object with the language codes as keys. If the project title or description is empty, return an empty string for that field.
 
+**IMPORTANT**: The description translations MUST be concise and within 100 characters. If the source description is long, extract and translate only the key points or create a brief summary that captures the essence.
+
 Project Title: ${projectName || ""}
-Project Description: ${projectDesc || ""}
+Project Description: ${finalProjectDesc || ""}
 
 Target Languages: { title: ${titleLanguages.join(", ")}, desc: ${descLanguages.join(", ")} }
 Source Language: ${locale}
@@ -64,12 +105,18 @@ Respond with a JSON object in the following format:
     ...
   },
   "desc": {
-    "fr": "Translated Project Description in French",
-    "es": "Translated Project Description in Spanish",
+    "fr": "Translated Project Description in French (max 100 characters)",
+    "es": "Translated Project Description in Spanish (max 100 characters)",
     ...
   }
 }
 
+**Requirements for description translations:**
+- Each description MUST be 100 characters or less
+- Be concise and capture the core essence of the project
+- Use natural, fluent language appropriate for the target culture
+- If the source is very long, create a brief summary instead of a full translation
+
 If no translation is needed, respond with:
 {
   "title": {},
@@ -87,17 +134,22 @@ If no translation is needed, respond with:
       }
     });
   }
+
+  if (!projectDesc && finalProjectDesc) {
+    await saveValueToConfig("projectDesc", finalProjectDesc, "Project description");
+  }
+
   const saveResult = {
     ...parsedTranslationCache,
     [projectName]: titleTranslation,
-    [projectDesc]: descTranslation,
+    [finalProjectDesc]: descTranslation,
   };
   await fs.writeFile(translationCacheFilePath, yamlStringify(saveResult), { encoding: "utf8" });
 
   return {
     translatedMetadata: {
       title: saveResult[projectName] || {},
-      desc: saveResult[projectDesc] || {},
+      desc: saveResult[finalProjectDesc] || {},
     },
   };
 }

package/agents/update/generate-diagram.yaml

@@ -4,14 +4,17 @@ name: generateDiagram
 skills:
   # 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)
+  # Step 2: Transform output for image generation agent (map aspectRatio to ratio, add size, pass existingImage and feedback)
   - type: transform
     jsonata: |
       $merge([
         $,
         {
           "ratio": aspectRatio,
-          "size": "1K"
+          "size": "1K",
+          "existingImage": existingImage,
+          "useImageToImage": useImageToImage,
+          "feedback": feedback
         }
       ])
   # Step 3: Generate diagram image directly with unified agent
@@ -39,18 +42,32 @@ input_schema:
       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)
+    intentAnalysis:
+      type: object
+      description: Analysis results from analyzeFeedbackIntent containing intentType, diagramInfo, generationMode, and changes
+      properties:
+        intentType:
+          type: string
+          enum: ["addDiagram", "updateDiagram", "deleteDiagram", "updateDocument"]
+        diagramInfo:
+          type: object
+          nullable: true
+          properties:
+            path: { type: "string" }
+            index: { type: "number" }
+            markdown: { type: "string" }
+        generationMode:
+          type: string
+          enum: ["image-to-image", "text-only", "add-new", "remove-image"]
+        changes:
+          type: array
+          items: { type: "string" }
   required:
     - documentContent
 output_schema:

package/agents/update/index.yaml

@@ -2,7 +2,7 @@ type: team
 name: update
 alias:
   - up
-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.
+description: Update specific documents and their translations. Use --diagram to filter and select documents with diagrams, or --diagram-all to auto-update all diagrams.
 skills:
   - url: ../init/index.mjs
     default_input:
@@ -21,16 +21,12 @@ skills:
       ])
   # 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
@@ -59,9 +55,6 @@ input_schema:
     "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/save-and-translate-document.mjs

@@ -58,12 +58,16 @@ export default async function saveAndTranslateDocument(input, options) {
         // Clear feedback to ensure translation is not affected by update feedback
         doc.feedback = "";
 
+        // Extract input properties excluding diagram to avoid passing invalid value
+        const { diagram, ...inputWithoutDiagram } = input;
+
         await options.context.invoke(translateAgent, {
-          ...input, // context is required
+          ...inputWithoutDiagram, // context is required (without diagram)
           content: doc.content,
           title: doc.title,
           path: doc.path,
           docsDir,
+          diagram: `${diagram}` === "true",
         });
       } catch (error) {
         console.error(`❌ Failed to translate document ${doc.path}:`, error.message);

package/agents/update/update-single/update-single-document-detail.mjs

@@ -9,6 +9,25 @@ import {
 import { userContextAt } from "../../../utils/utils.mjs";
 
 async function getIntentType(input, options) {
+  // Single document mode: Get current document content and perform full analysis
+  // This is called AFTER userReviewDocument has collected the feedback
+  const analyzeFeedbackIntentAgent = options.context?.agents?.["analyzeFeedbackIntent"];
+  if (analyzeFeedbackIntentAgent) {
+    const contentContext = userContextAt(options, `currentContents.${input.path}`);
+    const currentContent = contentContext.get();
+
+    const result = await options.context.invoke(analyzeFeedbackIntentAgent, {
+      feedback: input.feedback,
+      documentContent: currentContent,
+      shouldUpdateDiagrams: false,
+    });
+
+    return result;
+  }
+
+  console.warn("[getIntentType] analyzeFeedbackIntent agent not found, using fallback");
+
+  // Fallback to old method if analyzeFeedbackIntent agent not available
   const instructions = `<role>
 You are a feedback intent analyzer. Your task is to determine which type of content modifications are needed based on the user's feedback.
 
@@ -113,7 +132,7 @@ async function addDiagram(input, options) {
   const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
     ...pick(input, ["locale", "path", "docsDir", "diagramming", "feedback"]),
     documentContent: currentContent,
-    originalContent: currentContent,
+    intentAnalysis: input.intentAnalysis, // Pass intent analysis from first layer
   });
   const content = generateDiagramResult.content;
   contentContext.set(content);
@@ -134,9 +153,9 @@ async function updateDiagram(input, options) {
     locale: input.locale,
     diagramming: input.diagramming || {},
     feedback: input.feedback,
-    originalContent: currentContent, // Pass original content to find existing diagrams
     path: input.path,
     docsDir: input.docsDir,
+    intentAnalysis: input.intentAnalysis, // Pass intent analysis from first layer
   });
 
   // generateDiagram now returns { content } with image already inserted
@@ -248,18 +267,42 @@ async function updateDocument(input, options) {
 }
 
 export default async function updateSingleDocumentDetail(input, options) {
-  // Use intentType from input if available (analyzed in parent flow),
-  // otherwise fall back to analyzing it here (for backward compatibility)
+  // Get intent analysis (may include full analysis result with diagramInfo, generationMode, etc.)
+  // Note: This is called AFTER userReviewDocument has collected the feedback
+  let intentAnalysis = input.intentAnalysis;
   let intentType = input.intentType;
-  if (!intentType && input.feedback) {
-    intentType = await getIntentType(input, options);
+
+  // If intentAnalysis not provided, analyze it here (with feedback from userReviewDocument)
+  if (!intentAnalysis && input.feedback) {
+    const analysisResult = await getIntentType(input, options);
+
+    // Check if result is the new format (with diagramInfo) or old format (just intentType)
+    if (analysisResult && typeof analysisResult === "object" && "intentType" in analysisResult) {
+      intentAnalysis = analysisResult;
+      intentType = analysisResult.intentType;
+    } else {
+      // Old format: just intentType string
+      intentType = analysisResult;
+      intentAnalysis = {
+        intentType: analysisResult,
+        diagramInfo: null,
+        generationMode: null,
+        changes: [],
+      };
+    }
   }
 
   // If intentType is still null or undefined, default to updateDocument
-  // This ensures that some operation is always performed, even if intent analysis failed
-  // or no explicit intent was provided
   if (!intentType) {
     intentType = "updateDocument";
+    if (!intentAnalysis) {
+      intentAnalysis = {
+        intentType: "updateDocument",
+        diagramInfo: null,
+        generationMode: null,
+        changes: [],
+      };
+    }
   }
 
   const fnMap = {
@@ -270,8 +313,7 @@ export default async function updateSingleDocumentDetail(input, options) {
   };
 
   if (fnMap[intentType]) {
-    const result = await fnMap[intentType](input, options);
-    return result;
+    return await fnMap[intentType]({ ...input, intentAnalysis }, options);
   }
 
   // Fallback: if intentType is not in fnMap, default to updateDocument