@aigne/doc-smith 0.8.5 → 0.8.7

package/agents/{detail-regenerator.yaml → update/index.yaml}

@@ -2,21 +2,20 @@ type: team
 name: update
 alias:
   - up
-description: Optimize and regenerate individual document content and translations
+description: Update specific documents and their translations
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - ./load-config.mjs
-  - ./load-sources.mjs
+  - ../utils/load-sources.mjs
   - type: transform
     task_render_mode: hide
     jsonata: |
       $merge([
         $,
         {
-          'structurePlan': originalStructurePlan,
-          'structurePlanResult': $map(originalStructurePlan, function($item) {
+          'documentStructure': originalDocumentStructure,
+          'documentExecutionStructure': $map(originalDocumentStructure, function($item) {
             $merge([
               $item,
               {
@@ -26,37 +25,37 @@ skills:
           })
         }
       ])
-  - ./find-items-by-paths.mjs
-  - ./format-structure-plan.mjs
+  - ../utils/choose-docs.mjs
+  - ../utils/format-document-structure.mjs
   - type: team
-    name: batchDocsUpdate
+    name: batchUpdateDocument
     skills:
-      - ./detail-generator-and-translate.yaml
+      - ../update/generate-and-translate-document.yaml
     iterate_on: selectedDocs
     concurrency: 3
-  - url: ./check-feedback-refiner.mjs
+  - url: ../utils/check-feedback-refiner.mjs
     default_input:
       stage: document_refine
-  - url: ./action-success.mjs
+  - url: ../utils/action-success.mjs
     default_input:
-      action: "Document updated"
+      action: "✅ Documents updated successfully"
 input_schema:
   type: object
   properties:
     glossary:
       type: string
-      description: Glossary of terms for consistent terminology, use @<file> to read from a file
+      description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Document paths to translate
+      description: Documents to update
     feedback:
       type: string
-      description: Feedback for content improvement
+      description: Tell us what to change in this content
     reset:
       type: boolean
-      description: Ignore previous results and regenerate content from scratch
+      description: Start fresh - ignore previous versions
 output_schema:
   type: object
   properties:

package/agents/{action-success.mjs → utils/action-success.mjs}

@@ -1,4 +1,4 @@
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
 
 export default async function actionSuccess({ action }) {
   // Shutdown mermaid worker pool to ensure clean exit
@@ -9,7 +9,7 @@ export default async function actionSuccess({ action }) {
   }
 
   return {
-    message: `✅ ${action} successfully`,
+    message: `${action}`,
   };
 }
 

package/agents/{check-detail-result.mjs → utils/check-detail-result.mjs}

@@ -1,6 +1,6 @@
-import { checkMarkdown } from "../utils/markdown-checker.mjs";
+import { checkMarkdown } from "../../utils/markdown-checker.mjs";
 
-export default async function checkDetailResult({ structurePlan, reviewContent, docsDir }) {
+export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
   if (!reviewContent || reviewContent.trim() === "") {
     return {
       isApproved: false,
@@ -13,7 +13,7 @@ export default async function checkDetailResult({ structurePlan, reviewContent,
 
   // Create a set of allowed links, including both original paths and processed .md paths
   const allowedLinks = new Set();
-  structurePlan.forEach((item) => {
+  documentStructure.forEach((item) => {
     // Add original path
     allowedLinks.add(item.path);
 

package/agents/{check-feedback-refiner.mjs → utils/check-feedback-refiner.mjs}

@@ -1,12 +1,12 @@
 import { stringify } from "yaml";
-import { addPreferenceRule, readPreferences } from "../utils/preferences-utils.mjs";
+import { addPreferenceRule, readPreferences } from "../../utils/preferences-utils.mjs";
 
 export default async function checkFeedbackRefiner(
-  { feedback, stage, selectedPaths, structurePlanFeedback },
+  { feedback, stage, selectedPaths, documentStructureFeedback },
   options,
 ) {
   // If feedback is empty, no need to save user preferences
-  if (!feedback && !structurePlanFeedback) {
+  if (!feedback && !documentStructureFeedback) {
     return {};
   }
 
@@ -18,7 +18,7 @@ export default async function checkFeedbackRefiner(
   const activePreferencesYaml =
     activePreferences.length > 0 ? stringify({ rules: activePreferences }, { indent: 2 }) : "";
 
-  const feedbackToUse = feedback || structurePlanFeedback;
+  const feedbackToUse = feedback || documentStructureFeedback;
   const result = await options.context.invoke(options.context.agents["feedbackRefiner"], {
     feedback: feedbackToUse,
     stage,
@@ -60,9 +60,9 @@ checkFeedbackRefiner.input_schema = {
       type: "string",
       description: "User feedback to refine",
     },
-    structurePlanFeedback: {
+    documentStructureFeedback: {
       type: "string",
-      description: "Feedback from structure planning stage",
+      description: "Feedback from document structure stage",
     },
     stage: {
       type: "string",

package/agents/{find-items-by-paths.mjs → utils/choose-docs.mjs}

@@ -4,10 +4,19 @@ import {
   getActionText,
   getMainLanguageFiles,
   processSelectedFiles,
-} from "../utils/docs-finder-utils.mjs";
-
-export default async function selectedDocs(
-  { docs, structurePlanResult, boardId, docsDir, isTranslate, feedback, locale, reset = false },
+} from "../../utils/docs-finder-utils.mjs";
+
+export default async function chooseDocs(
+  {
+    docs,
+    documentExecutionStructure,
+    boardId,
+    docsDir,
+    isTranslate,
+    feedback,
+    locale,
+    reset = false,
+  },
   options,
 ) {
   let foundItems = [];
@@ -17,7 +26,11 @@ export default async function selectedDocs(
   if (!docs || docs.length === 0) {
     try {
       // Get all main language .md files in docsDir
-      const mainLanguageFiles = await getMainLanguageFiles(docsDir, locale, structurePlanResult);
+      const mainLanguageFiles = await getMainLanguageFiles(
+        docsDir,
+        locale,
+        documentExecutionStructure,
+      );
 
       if (mainLanguageFiles.length === 0) {
         throw new Error("No documents found in the docs directory");
@@ -49,7 +62,7 @@ export default async function selectedDocs(
       }
 
       // Process selected files and convert to found items
-      foundItems = await processSelectedFiles(selectedFiles, structurePlanResult, docsDir);
+      foundItems = await processSelectedFiles(selectedFiles, documentExecutionStructure, docsDir);
     } catch (error) {
       console.error(error);
       throw new Error(
@@ -63,7 +76,7 @@ export default async function selectedDocs(
     // Process the provided docs array
     for (const docPath of docs) {
       const foundItem = await findItemByPath(
-        structurePlanResult,
+        documentExecutionStructure,
         docPath,
         boardId,
         docsDir,
@@ -71,7 +84,7 @@ export default async function selectedDocs(
       );
 
       if (!foundItem) {
-        console.warn(`⚠️  Item with path "${docPath}" not found in structurePlanResult`);
+        console.warn(`⚠️  Item with path "${docPath}" not found in documentExecutionStructure`);
         continue;
       }
 
@@ -81,7 +94,9 @@ export default async function selectedDocs(
     }
 
     if (foundItems.length === 0) {
-      throw new Error("None of the specified document paths were found in structurePlanResult");
+      throw new Error(
+        "None of the specified document paths were found in documentExecutionStructure",
+      );
     }
   }
 
@@ -90,7 +105,7 @@ export default async function selectedDocs(
   if (!userFeedback) {
     const feedbackMessage = getActionText(
       isTranslate,
-      "Please provide feedback for the {action} (press Enter to skip):",
+      "How should we improve this {action}? (press Enter to skip):",
     );
 
     userFeedback = await options.prompts.input({

package/agents/{docs-fs.yaml → utils/docs-fs-actor.yaml}

@@ -2,7 +2,9 @@ type: team
 name: docs_fs_actor
 description: File system operations for documentation management
 skills:
-  - ./load-config.mjs
+  - url: ../init/index.mjs
+    default_input:
+      skipIfExists: true
   - url: ./fs.mjs
     default_input:
       rootDir:

package/agents/utils/feedback-refiner.yaml

@@ -0,0 +1,50 @@
+name: feedbackRefiner
+description: Learn from your feedback to improve future documentation
+instructions:
+  url: ../../prompts/utils/feedback-refiner.md
+
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: Tell us what you think about the documentation
+    stage:
+      type: string
+      description: Which part of the process this feedback is about (document_structure, document_refine, translation_refine)
+    paths:
+      type: array
+      items:
+        type: string
+      description: Specific documents this feedback applies to (optional)
+    existingPreferences:
+      type: string
+      description: Your existing preferences to avoid duplicates (optional)
+  required: 
+    - feedback
+    - stage
+
+output_schema:
+  type: object
+  properties:
+    rule:
+      type: string
+      description: General rule created from your feedback
+    scope:
+      type: string
+      description: Where this rule applies (global, structure, document, translation)
+    save:
+      type: boolean
+      description: Should we remember this preference for next time?
+    limitToInputPaths:
+      type: boolean
+      description: Apply only to the specific documents mentioned?
+    reason:
+      type: string
+      description: Why we made this decision and how the rule was created
+  required:
+    - rule
+    - scope
+    - save
+    - limitToInputPaths
+    - reason

package/agents/{find-item-by-path.mjs → utils/find-item-by-path.mjs}

@@ -5,10 +5,10 @@ import {
   getActionText,
   getMainLanguageFiles,
   readFileContent,
-} from "../utils/docs-finder-utils.mjs";
+} from "../../utils/docs-finder-utils.mjs";
 
 export default async function findItemByPath(
-  { doc, structurePlanResult, boardId, docsDir, isTranslate, feedback, locale },
+  { doc, documentExecutionStructure, boardId, docsDir, isTranslate, feedback, locale },
   options,
 ) {
   let foundItem = null;
@@ -19,7 +19,11 @@ export default async function findItemByPath(
   if (!docPath) {
     try {
       // Get all main language .md files in docsDir
-      const mainLanguageFiles = await getMainLanguageFiles(docsDir, locale, structurePlanResult);
+      const mainLanguageFiles = await getMainLanguageFiles(
+        docsDir,
+        locale,
+        documentExecutionStructure,
+      );
 
       if (mainLanguageFiles.length === 0) {
         throw new Error("No documents found in the docs directory");
@@ -59,7 +63,7 @@ export default async function findItemByPath(
       const flatName = fileNameToFlatPath(selectedFile);
 
       // Try to find matching item by comparing flattened paths
-      const foundItemByFile = findItemByFlatName(structurePlanResult, flatName);
+      const foundItemByFile = findItemByFlatName(documentExecutionStructure, flatName);
 
       if (!foundItemByFile) {
         throw new Error("No document found");
@@ -78,10 +82,16 @@ export default async function findItemByPath(
   }
 
   // Use the utility function to find item and read content
-  foundItem = await findItemByPathUtil(structurePlanResult, docPath, boardId, docsDir, locale);
+  foundItem = await findItemByPathUtil(
+    documentExecutionStructure,
+    docPath,
+    boardId,
+    docsDir,
+    locale,
+  );
 
   if (!foundItem) {
-    throw new Error(`Item with path "${docPath}" not found in structurePlanResult`);
+    throw new Error(`Item with path "${docPath}" not found in documentExecutionStructure`);
   }
 
   // Prompt for feedback if not provided
@@ -89,7 +99,7 @@ export default async function findItemByPath(
   if (!userFeedback) {
     const feedbackMessage = getActionText(
       isTranslate,
-      "Please provide feedback for the {action} (press Enter to skip):",
+      "How should we improve this {action}? (press Enter to skip):",
     );
 
     userFeedback = await options.prompts.input({

package/agents/{find-user-preferences-by-path.mjs → utils/find-user-preferences-by-path.mjs}

@@ -1,4 +1,4 @@
-import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 
 export default async function findUserPreferencesByPath({ path, scope }) {
   // Get global rules (always applicable)

package/agents/utils/format-document-structure.mjs

@@ -0,0 +1,25 @@
+import { stringify } from "yaml";
+
+export default async function formatDocumentStructure({ documentStructure }) {
+  // Extract required fields from each item in documentStructure
+  const formattedData = documentStructure.map((item) => ({
+    title: item.title,
+    path: item.path,
+    parentId: item.parentId,
+    description: item.description,
+  }));
+
+  // Convert to YAML string
+  const yamlString = stringify(formattedData, {
+    indent: 2,
+    lineWidth: 120,
+    minContentWidth: 20,
+  });
+
+  return {
+    documentStructureYaml: yamlString,
+    documentStructure,
+  };
+}
+
+formatDocumentStructure.task_render_mode = "hide";

package/agents/{load-sources.mjs → utils/load-sources.mjs}

@@ -1,12 +1,12 @@
-import { access, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../utils/constants.mjs";
-import { getFilesWithGlob, loadGitignore } from "../utils/file-utils.mjs";
+import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../../utils/constants.mjs";
+import { getFilesWithGlob, loadGitignore } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,
   getModifiedFilesBetweenCommits,
   isGlobPattern,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
 export default async function loadSources({
   sources = [],
@@ -172,48 +172,61 @@ export default async function loadSources({
     }),
   );
 
-  // Get the last structure plan result
-  let originalStructurePlan;
-  const structurePlanPath = path.join(outputDir, "structure-plan.json");
-  try {
-    await access(structurePlanPath);
-    const structurePlanResult = await readFile(structurePlanPath, "utf8");
-    if (structurePlanResult) {
-      try {
-        originalStructurePlan = JSON.parse(structurePlanResult);
-      } catch (err) {
-        console.error(`Failed to parse structure-plan.json: ${err.message}`);
+  // Get the last document structure
+  let originalDocumentStructure;
+  if (outputDir) {
+    const documentStructurePath = path.join(outputDir, "structure-plan.json");
+    try {
+      const documentExecutionStructure = await readFile(documentStructurePath, "utf8");
+      if (documentExecutionStructure?.trim()) {
+        try {
+          // Validate that the content looks like JSON before parsing
+          const trimmedContent = documentExecutionStructure.trim();
+          if (trimmedContent.startsWith("{") || trimmedContent.startsWith("[")) {
+            originalDocumentStructure = JSON.parse(documentExecutionStructure);
+          } else {
+            console.warn(`structure-plan.json contains non-JSON content, skipping parse`);
+          }
+        } catch (err) {
+          console.error(`Failed to parse structure-plan.json: ${err.message}`);
+        }
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading structure-plan.json: ${err.message}`);
       }
+      // The file does not exist or is not readable, originalDocumentStructure remains undefined
     }
-  } catch {
-    // The file does not exist, originalStructurePlan remains undefined
   }
 
   // Get the last output result of the specified path
   let content;
-  if (docPath && !reset) {
-    let fileFullName;
-
+  if (docPath && !reset && docsDir) {
     // First try direct path matching (original format)
     const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
-    fileFullName = `${flatName}.md`;
+    const fileFullName = `${flatName}.md`;
     let filePath = path.join(docsDir, fileFullName);
 
     try {
-      await access(filePath);
       content = await readFile(filePath, "utf8");
-    } catch {
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading document file ${filePath}: ${err.message}`);
+      }
+
       // If not found and boardId is provided, try boardId-flattenedPath format
       if (boardId && docPath.startsWith(`${boardId}-`)) {
         // Extract the flattened path part after boardId-
         const flattenedPath = docPath.substring(boardId.length + 1);
-        fileFullName = `${flattenedPath}.md`;
-        filePath = path.join(docsDir, fileFullName);
+        const boardIdFileFullName = `${flattenedPath}.md`;
+        filePath = path.join(docsDir, boardIdFileFullName);
 
         try {
-          await access(filePath);
           content = await readFile(filePath, "utf8");
-        } catch {
+        } catch (boardIdErr) {
+          if (boardIdErr.code !== "ENOENT") {
+            console.warn(`Error reading document file ${filePath}: ${boardIdErr.message}`);
+          }
           // The file does not exist, content remains undefined
         }
       }
@@ -286,7 +299,7 @@ export default async function loadSources({
     datasourcesList: sourceFiles,
     datasources: allSources,
     content,
-    originalStructurePlan,
+    originalDocumentStructure,
     files,
     modifiedFiles,
     totalWords,

package/agents/{save-docs.mjs → utils/save-docs.mjs}

@@ -1,17 +1,17 @@
 import { readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
-import { getCurrentGitHead, saveGitHeadToConfig } from "../utils/utils.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
+import { getCurrentGitHead, saveGitHeadToConfig } from "../../utils/utils.mjs";
 
 /**
  * @param {Object} params
- * @param {Array<{path: string, content: string, title: string}>} params.structurePlan
+ * @param {Array<{path: string, content: string, title: string}>} params.documentStructure
  * @param {string} params.docsDir
  * @param {Array<string>} [params.translateLanguages] - Translation languages
  * @returns {Promise<Array<{ path: string, success: boolean, error?: string }>>}
  */
 export default async function saveDocs({
-  structurePlanResult: structurePlan,
+  documentExecutionStructure: documentStructure,
   docsDir,
   translateLanguages = [],
   locale,
@@ -28,23 +28,23 @@ export default async function saveDocs({
 
   // Generate _sidebar.md
   try {
-    const sidebar = generateSidebar(structurePlan);
+    const sidebar = generateSidebar(documentStructure);
     const sidebarPath = join(docsDir, "_sidebar.md");
     await writeFile(sidebarPath, sidebar, "utf8");
   } catch (err) {
     console.error("Failed to save _sidebar.md:", err.message);
   }
 
-  // Clean up invalid .md files that are no longer in the structure plan
+  // Clean up invalid .md files that are no longer in the document structure
   try {
-    await cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, locale);
+    await cleanupInvalidFiles(documentStructure, docsDir, translateLanguages, locale);
   } catch (err) {
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
   const message = `## ✅ Documentation Generated Successfully!
 
-  Successfully generated **${structurePlan.length}** documents and saved to:
+  Successfully generated **${documentStructure.length}** documents and saved to:
   \`${docsDir}\`
   ${projectInfoMessage || ""}
   ### 🚀 Next Steps
@@ -100,14 +100,14 @@ function generateFileName(flatName, language) {
 }
 
 /**
- * Clean up .md files that are no longer in the structure plan
- * @param {Array<{path: string, title: string}>} structurePlan
+ * Clean up .md files that are no longer in the document structure
+ * @param {Array<{path: string, title: string}>} documentStructure
  * @param {string} docsDir
  * @param {Array<string>} translateLanguages
  * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
  * @returns {Promise<Array<{ path: string, success: boolean, error?: string }>>}
  */
-async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, locale) {
+async function cleanupInvalidFiles(documentStructure, docsDir, translateLanguages, locale) {
   const results = [];
 
   try {
@@ -115,11 +115,11 @@ async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, l
     const files = await readdir(docsDir);
     const mdFiles = files.filter((file) => file.endsWith(".md"));
 
-    // Generate expected file names from structure plan
+    // Generate expected file names from document structure
     const expectedFiles = new Set();
 
     // Add main document files
-    for (const { path } of structurePlan) {
+    for (const { path } of documentStructure) {
       const flatName = path.replace(/^\//, "").replace(/\//g, "-");
 
       // Main language file
@@ -166,11 +166,11 @@ async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, l
   return results;
 }
 
-// Generate sidebar content, support nested structure, and the order is consistent with structurePlan
-function generateSidebar(structurePlan) {
+// Generate sidebar content, support nested structure, and the order is consistent with documentStructure
+function generateSidebar(documentStructure) {
   // Build tree structure
   const root = {};
-  for (const { path, title, parentId } of structurePlan) {
+  for (const { path, title, parentId } of documentStructure) {
     const relPath = path.replace(/^\//, "");
     const segments = relPath.split("/");
     let node = root;

package/agents/{save-single-doc.mjs → utils/save-single-doc.mjs}

@@ -1,5 +1,5 @@
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
-import { saveDocWithTranslations } from "../utils/utils.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
+import { saveDocWithTranslations } from "../../utils/utils.mjs";
 
 export default async function saveSingleDoc({
   path,

package/agents/{transform-detail-datasources.mjs → utils/transform-detail-datasources.mjs}

@@ -1,4 +1,4 @@
-import { normalizePath, toRelativePath } from "../utils/utils.mjs";
+import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
 
 export default function transformDetailDatasources({ sourceIds, datasourcesList }) {
   // Build a map for fast lookup, with path normalization for compatibility