@aigne/doc-smith 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.5...v0.2.6) (2025-08-12)
+
+
+### Miscellaneous Chores
+
+* release 0.2.6 ([c5b5ea5](https://github.com/AIGNE-io/aigne-doc-smith/commit/c5b5ea5c404d44f3b0d420f0b57e4ae64ae5d624))
+
 ## [0.2.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.4...v0.2.5) (2025-08-08)
 
 

package/README.md

@@ -206,6 +206,7 @@ aigne doc publish --appUrl https://your-discuss-kit-instance.com
 npx --no doc-smith run --entry-agent init
 npx --no doc-smith run --entry-agent generate
 npx --no doc-smith run --entry-agent update 
+npx --no doc-smith run --entry-agent retranslate 
 npx --no doc-smith run --entry-agent publish
 ```
 

package/agents/check-detail-result.mjs

@@ -1,11 +1,9 @@
+import { checkMarkdown } from "../utils/markdown-checker.mjs";
+
 export default async function checkDetailResult({
   structurePlan,
   reviewContent,
 }) {
-  const linkRegex = /(?<!\!)\[([^\]]+)\]\(([^)]+)\)/g;
-  const tableSeparatorRegex = /^\s*\|\s*-+\s*\|\s*$/;
-  const codeBlockRegex = /^\s+```(?:\w+)?$/;
-
   let isApproved = true;
   const detailFeedback = [];
 
@@ -25,141 +23,22 @@ export default async function checkDetailResult({
     allowedLinks.add(flatPath);
   });
 
-  const checkLinks = (text, source) => {
-    let match;
-    while ((match = linkRegex.exec(text)) !== null) {
-      const link = match[2];
-      const trimLink = link.trim();
-
-      // Only check links that processContent would process
-      // Exclude external links and mailto
-      if (/^(https?:\/\/|mailto:)/.test(trimLink)) continue;
-
-      // Preserve anchors
-      const [path, hash] = trimLink.split("#");
-
-      // Only process relative paths or paths starting with /
-      if (!path) continue;
-
-      // Check if this link is in the allowed links set
-      if (!allowedLinks.has(trimLink)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the structure plan path`
-        );
-      }
-    }
-  };
-
-  const performAllChecks = (text, source) => {
-    // Split text into lines once and perform all checks in a single pass
-    const lines = text.split("\n");
-
-    // State variables for different checks
-    let inCodeBlock = false;
-    let codeBlockIndentLevel = 0;
-    let codeBlockStartLine = 0;
-    let inMermaidBlock = false;
-    let mermaidStartLine = 0;
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      const lineNumber = i + 1;
+  // Run comprehensive markdown validation with all checks
+  try {
+    const markdownErrors = await checkMarkdown(reviewContent, "result", {
+      allowedLinks,
+    });
 
-      // Check table separators
-      if (tableSeparatorRegex.test(line)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found an incorrect table separator in ${source} at line ${lineNumber}: ${line.trim()}`
-        );
-      }
-
-      // Check code block markers and indentation
-      if (codeBlockRegex.test(line)) {
-        if (!inCodeBlock) {
-          // Starting a new code block
-          inCodeBlock = true;
-          codeBlockStartLine = lineNumber;
-          // Calculate indentation level of the code block marker
-          const match = line.match(/^(\s*)(```)/);
-          codeBlockIndentLevel = match ? match[1].length : 0;
-        } else {
-          // Ending the code block
-          inCodeBlock = false;
-          codeBlockIndentLevel = 0;
-        }
-      } else if (inCodeBlock) {
-        // If we're inside a code block, check if content has proper indentation
-        const contentIndentLevel = line.match(/^(\s*)/)[1].length;
-
-        // If code block marker has indentation, content should have at least the same indentation
-        if (
-          codeBlockIndentLevel > 0 &&
-          contentIndentLevel < codeBlockIndentLevel
-        ) {
-          isApproved = false;
-          detailFeedback.push(
-            `Found code block with inconsistent indentation in ${source} at line ${codeBlockStartLine}: code block marker has ${codeBlockIndentLevel} spaces indentation but content at line ${lineNumber} has only ${contentIndentLevel} spaces indentation`
-          );
-          // Reset to avoid multiple errors for the same code block
-          inCodeBlock = false;
-          codeBlockIndentLevel = 0;
-        }
-      }
-
-      // Check mermaid block markers
-      if (/^\s*```mermaid\s*$/.test(line)) {
-        inMermaidBlock = true;
-        mermaidStartLine = lineNumber;
-      } else if (inMermaidBlock && /^\s*```\s*$/.test(line)) {
-        inMermaidBlock = false;
-      } else if (inMermaidBlock) {
-        // If we're inside a mermaid block, check for backticks in node labels
-        // Check for node definitions with backticks in labels
-        // Pattern: A["label with backticks"] or A{"label with backticks"}
-        const nodeLabelRegex =
-          /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
-        let match;
-
-        while ((match = nodeLabelRegex.exec(line)) !== null) {
-          const label = match[1] || match[2];
-          isApproved = false;
-          detailFeedback.push(
-            `Found backticks in Mermaid node label in ${source} at line ${lineNumber}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`
-          );
-        }
-
-        // Check for edge descriptions with numbered list format
-        // Pattern: -- "1. description" --> or similar variants
-        const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
-        let edgeMatch;
-
-        while ((edgeMatch = edgeDescriptionRegex.exec(line)) !== null) {
-          const description = edgeMatch[1];
-          // Check if description starts with number followed by period
-          if (/^\d+\.\s/.test(description)) {
-            isApproved = false;
-            detailFeedback.push(
-              `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${lineNumber}: "${description}" - numbered lists in edge descriptions are not supported`
-            );
-          }
-        }
-      }
-    }
-
-    // Check single line content (this needs to be done after the loop)
-    const newlineCount = (text.match(/\n/g) || []).length;
-    if (newlineCount === 0 && text.trim().length > 0) {
+    if (markdownErrors.length > 0) {
       isApproved = false;
-      detailFeedback.push(
-        `Found single line content in ${source}: content appears to be on only one line, check for missing line breaks`
-      );
+      detailFeedback.push(...markdownErrors);
     }
-  };
-
-  // Check content
-  checkLinks(reviewContent, "result");
-  performAllChecks(reviewContent, "result");
+  } catch (error) {
+    isApproved = false;
+    detailFeedback.push(
+      `Found markdown validation error in result: ${error.message}`
+    );
+  }
 
   return {
     isApproved,

package/agents/check-structure-plan.mjs

@@ -1,10 +1,13 @@
 import {
   getCurrentGitHead,
   hasFileChangesBetweenCommits,
+  loadConfigFromFile,
+  saveValueToConfig,
+  getProjectInfo,
 } from "../utils/utils.mjs";
 
 export default async function checkStructurePlan(
-  { originalStructurePlan, feedback, lastGitHead, forceRegenerate, ...rest },
+  { originalStructurePlan, feedback, lastGitHead, ...rest },
   options
 ) {
   // Check if we need to regenerate structure plan
@@ -38,17 +41,13 @@ export default async function checkStructurePlan(
         1. 对于新增的内容，可以根据需要新增节点，或补充到原有节点展示
         2. 谨慎删除节点，除非节点关联 sourceIds 都被删除了
         3. 不能修改原有节点的 path
+        4. 根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
       `;
     }
   }
 
   // If no regeneration needed, return original structure plan
-  if (
-    originalStructurePlan &&
-    !feedback &&
-    !shouldRegenerate &&
-    !forceRegenerate
-  ) {
+  if (originalStructurePlan && !feedback && !shouldRegenerate) {
     return {
       structurePlan: originalStructurePlan,
     };
@@ -62,9 +61,59 @@ export default async function checkStructurePlan(
     ...rest,
   });
 
+  let message = "";
+
+  // Check and save project information if user hasn't modified it
+  if (result.projectName || result.projectDesc) {
+    try {
+      const currentConfig = await loadConfigFromFile();
+      const projectInfo = await getProjectInfo();
+
+      // Check if user has modified project information
+      const userModifiedProjectName =
+        currentConfig?.projectName &&
+        currentConfig.projectName !== projectInfo.name;
+      const userModifiedProjectDesc =
+        currentConfig?.projectDesc &&
+        currentConfig.projectDesc !== projectInfo.description;
+
+      // If user hasn't modified project info and it's not from GitHub, save AI output
+      if (!userModifiedProjectName && !userModifiedProjectDesc) {
+        let hasUpdated = false;
+        // Don't update if the current info is from GitHub (meaningful repository info)
+        if (
+          result.projectName &&
+          result.projectName !== projectInfo.name &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectName", result.projectName);
+          message += `Project name: \`${result.projectName}\``;
+          hasUpdated = true;
+        }
+
+        if (
+          result.projectDesc &&
+          result.projectDesc !== projectInfo.description &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectDesc", result.projectDesc);
+          message += `\nProject description: \`${result.projectDesc}\``;
+          hasUpdated = true;
+        }
+
+        if (hasUpdated) {
+          message = `\n### Auto-updated Project Info to \`.aigne/doc-smith/config.yaml\`\n\n${message}\n\n`;
+        }
+      }
+    } catch (error) {
+      console.warn("Failed to check/save project information:", error.message);
+    }
+  }
+
   return {
     ...result,
     feedback: "", // clear feedback
+    projectInfoMessage: message,
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan
       : JSON.parse(JSON.stringify(result.structurePlan || [])),

package/agents/detail-generator-and-translate.yaml

@@ -15,9 +15,15 @@ skills:
     reflection:
       reviewer: ./check-detail-result.mjs
       is_approved: isApproved
-      max_iterations: 3
+      max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate detail for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "feedback": "" }
+      ])
   - ./batch-translate.yaml
   - ./save-single-doc.mjs
 input_schema:

package/agents/detail-regenerator.yaml

@@ -27,7 +27,9 @@ skills:
       ])
   - ./find-item-by-path.mjs
   - ./format-structure-plan.mjs
-  - ./detail-generator-and-translate.yaml
+  - url: ./detail-generator-and-translate.yaml
+    default_input:
+      isShowMessage: true
 input_schema:
   type: object
   properties:

package/agents/docs-generator.yaml

@@ -30,7 +30,8 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          })
+          }),
+          "datasources": ""
         }
       ])
   - ./format-structure-plan.mjs

package/agents/find-item-by-path.mjs

@@ -1,11 +1,25 @@
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+// Helper function to get action-specific text based on isTranslate flag
+function getActionText(isTranslate, baseText) {
+  const action = isTranslate ? "retranslate" : "update";
+  return baseText.replace("{action}", action);
+}
+
 export default async function findItemByPath(
-  { "doc-path": docPath, structurePlanResult, boardId, docsDir },
+  {
+    "doc-path": docPath,
+    structurePlanResult,
+    boardId,
+    docsDir,
+    isTranslate,
+    feedback,
+  },
   options
 ) {
   let foundItem = null;
+  let selectedFileContent = null;
 
   // If docPath is empty, let user select from available documents
   if (!docPath) {
@@ -22,14 +36,12 @@ export default async function findItemByPath(
       );
 
       if (mainLanguageFiles.length === 0) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No documents found in the docs directory");
       }
 
       // Let user select a file
       const selectedFile = await options.prompts.search({
-        message: "Select a document to update:",
+        message: getActionText(isTranslate, "Select a document to {action}:"),
         source: async (input, { signal }) => {
           if (!input || input.trim() === "") {
             return mainLanguageFiles.map((file) => ({
@@ -51,9 +63,19 @@ export default async function findItemByPath(
       });
 
       if (!selectedFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
+        throw new Error("No document selected");
+      }
+
+      // Read the selected .md file content
+      try {
+        const selectedFilePath = join(docsDir, selectedFile);
+        selectedFileContent = await readFile(selectedFilePath, "utf-8");
+      } catch (readError) {
+        console.warn(
+          `⚠️  Could not read content from ${selectedFile}:`,
+          readError.message
         );
+        selectedFileContent = null;
       }
 
       // Convert filename back to path
@@ -71,15 +93,17 @@ export default async function findItemByPath(
         return itemFlattenedPath === flatName;
       });
       if (!foundItemByFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No document found");
       }
 
       docPath = foundItemByFile.path;
     } catch (error) {
+      console.error(error);
       throw new Error(
-        "Please provide a doc-path parameter to specify which document to update"
+        getActionText(
+          isTranslate,
+          "Please provide a doc-path parameter to specify which document to {action}"
+        )
       );
     }
   }
@@ -111,8 +135,33 @@ export default async function findItemByPath(
     );
   }
 
-  // Merge the found item with originalStructurePlan
-  return {
+  // Prompt for feedback if not provided
+  let userFeedback = feedback;
+  if (!userFeedback) {
+    const feedbackMessage = getActionText(
+      isTranslate,
+      "Please provide feedback for the {action} (press Enter to skip):"
+    );
+
+    userFeedback = await options.prompts.input({
+      message: feedbackMessage,
+    });
+  }
+
+  // Merge the found item with originalStructurePlan and add content if available
+  const result = {
     ...foundItem,
   };
+
+  // Add content if we read it from user selection
+  if (selectedFileContent !== null) {
+    result.content = selectedFileContent;
+  }
+
+  // Add feedback to result if provided
+  if (userFeedback && userFeedback.trim()) {
+    result.feedback = userFeedback.trim();
+  }
+
+  return result;
 }

package/agents/input-generator.mjs

@@ -1,13 +1,16 @@
 import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import chalk from "chalk";
-import { validatePath, getAvailablePaths } from "../utils/utils.mjs";
+import {
+  validatePath,
+  getAvailablePaths,
+  getProjectInfo,
+} from "../utils/utils.mjs";
 import {
   SUPPORTED_LANGUAGES,
   DOCUMENT_STYLES,
   TARGET_AUDIENCES,
 } from "../utils/constants.mjs";
-
 // UI constants
 const PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
@@ -180,6 +183,12 @@ export default async function init(
   // If no paths entered, use default
   input.sourcesPath = sourcePaths.length > 0 ? sourcePaths : ["./"];
 
+  // Save project info to config
+  const projectInfo = await getProjectInfo();
+  input.projectName = projectInfo.name;
+  input.projectDesc = projectInfo.description;
+  input.projectLogo = projectInfo.icon;
+
   // Generate YAML content
   const yamlContent = generateYAML(input, outputPath);
 
@@ -193,13 +202,17 @@ export default async function init(
 
     await writeFile(filePath, yamlContent, "utf8");
     console.log(`\n🎉 Configuration saved to: ${chalk.cyan(filePath)}`);
+    // Print YAML content for user review
+    console.log(chalk.cyan("---"));
+    console.log(chalk.cyan(yamlContent));
+    console.log(chalk.cyan("---"));
     console.log(
-      "💡 You can edit the configuration file anytime to modify settings."
+      "💡 You can edit the configuration file anytime to modify settings.\n"
     );
     console.log(
       `🚀 Run ${chalk.cyan(
         "'aigne doc generate'"
-      )} to start documentation generation!`
+      )} to start documentation generation!\n`
     );
 
     return {};
@@ -215,12 +228,18 @@ export default async function init(
 /**
  * Generate YAML configuration content
  * @param {Object} input - Input object
- * @param {string} outputPath - Output path for directory configuration
  * @returns {string} YAML string
  */
-function generateYAML(input, outputPath) {
+function generateYAML(input) {
   let yaml = "";
 
+  // Add project information at the beginning
+  yaml += `# Project information for documentation publishing\n`;
+  yaml += `projectName: ${input.projectName || ""}\n`;
+  yaml += `projectDesc: ${input.projectDesc || ""}\n`;
+  yaml += `projectLogo: ${input.projectLogo || ""}\n`;
+  yaml += `\n`;
+
   // Add rules (required field)
   yaml += `rules: |\n`;
   if (input.rules && input.rules.trim()) {

package/agents/language-selector.mjs

@@ -0,0 +1,101 @@
+import { SUPPORTED_LANGUAGES } from "../utils/constants.mjs";
+
+/**
+ * Interactive language selector for translation from configured languages
+ * @param {Object} params
+ * @param {Array<string>} [params.languages] - Pre-selected languages
+ * @param {Array<string>} params.translateLanguages - Available languages from config
+ * @param {Object} options - Options object with prompts
+ * @returns {Promise<Object>} Selected languages
+ */
+export default async function languageSelector(
+  { languages, translateLanguages },
+  options
+) {
+  let selectedLanguages = [];
+
+  // Check if translateLanguages is available from config
+  if (
+    !translateLanguages ||
+    !Array.isArray(translateLanguages) ||
+    translateLanguages.length === 0
+  ) {
+    throw new Error(
+      "No translation languages configured in config.yaml. Please add translateLanguages to your configuration."
+    );
+  }
+
+  // If languages are provided as parameter, validate against configured languages
+  if (languages && Array.isArray(languages) && languages.length > 0) {
+    const validLanguages = languages.filter((lang) =>
+      translateLanguages.includes(lang)
+    );
+
+    if (validLanguages.length > 0) {
+      selectedLanguages = validLanguages;
+    } else {
+      console.log(`⚠️  Invalid languages provided: ${languages.join(", ")}`);
+      console.log(
+        "Available configured languages:",
+        translateLanguages.join(", ")
+      );
+    }
+  }
+
+  // If no valid languages were provided, let user select from configured languages
+  if (selectedLanguages.length === 0) {
+    // Create choices from configured languages with labels
+    const choices = translateLanguages.map((langCode) => {
+      const supportedLang = SUPPORTED_LANGUAGES.find(
+        (l) => l.code === langCode
+      );
+      return {
+        name: supportedLang
+          ? `${supportedLang.label} (${supportedLang.sample})`
+          : langCode,
+        value: langCode,
+        short: langCode,
+      };
+    });
+
+    selectedLanguages = await options.prompts.checkbox({
+      message: "Select languages to translate:",
+      choices: choices,
+      validate: (answer) => {
+        if (answer.length === 0) {
+          return "Please select at least one language";
+        }
+        return true;
+      },
+    });
+  }
+
+  if (selectedLanguages.length === 0) {
+    throw new Error("No languages selected for re-translation");
+  }
+
+  return {
+    selectedLanguages,
+  };
+}
+
+languageSelector.input_schema = {
+  type: "object",
+  properties: {
+    languages: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      description: "Pre-selected languages for translation",
+    },
+    translateLanguages: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      description: "Available translation languages from config",
+    },
+  },
+  required: ["translateLanguages"],
+};