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

package/agents/create/user-remove-document/remove-documents-from-structure.mjs

@@ -0,0 +1,96 @@
+import chooseDocs from "../../utils/choose-docs.mjs";
+import deleteDocument from "../document-structure-tools/delete-document.mjs";
+import { DOC_ACTION } from "../../../utils/constants/index.mjs";
+import addTranslatesToStructure from "../../utils/add-translates-to-structure.mjs";
+
+export default async function removeDocumentsFromStructure(input = {}, options = {}) {
+  const { docsDir, locale = "en", translateLanguages = [], originalDocumentStructure } = input;
+
+  if (!Array.isArray(originalDocumentStructure) || originalDocumentStructure.length === 0) {
+    console.warn(
+      "🗑️ Remove Documents\n  • No document structure found. Please generate documents first.",
+    );
+    process.exit(0);
+  }
+
+  const { documentExecutionStructure } = addTranslatesToStructure({
+    originalDocumentStructure,
+    translateLanguages,
+  });
+
+  // Initialize currentStructure in userContext
+  options.context.userContext.currentStructure = [...originalDocumentStructure];
+
+  // Use chooseDocs to select documents to delete
+  const chooseResult = await chooseDocs(
+    {
+      docs: [],
+      documentExecutionStructure,
+      docsDir,
+      locale,
+      isTranslate: false,
+      feedback: "no feedback",
+      requiredFeedback: false,
+      action: DOC_ACTION.clear,
+    },
+    options,
+  );
+
+  if (!chooseResult?.selectedDocs || chooseResult.selectedDocs.length === 0) {
+    console.log("No documents selected for removal.");
+    process.exit(0);
+  }
+
+  // Delete each selected document
+  const deletedDocuments = [];
+  const errors = [];
+
+  for (const selectedDoc of chooseResult.selectedDocs) {
+    try {
+      const deleteResult = await deleteDocument(
+        {
+          path: selectedDoc.path,
+          recursive: true,
+        },
+        options,
+      );
+
+      if (deleteResult.error) {
+        errors.push({
+          path: selectedDoc.path,
+          error: deleteResult.error.message,
+        });
+      } else {
+        // deletedDocuments is now always an array
+        deletedDocuments.push(...deleteResult.deletedDocuments);
+      }
+    } catch (error) {
+      errors.push({
+        path: selectedDoc.path,
+        error: error.message,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    console.warn(
+      `🗑️ Remove Documents\n  • Failed to remove documents:\n${errors
+        .map((e) => `    - ${e.path}: ${e.error}`)
+        .join("\n")}`,
+    );
+    process.exit(0);
+  }
+
+  // Get updated document structure
+  const updatedStructure = options.context.userContext.currentStructure;
+
+  return {
+    documentStructure: updatedStructure,
+    originalDocumentStructure: JSON.parse(JSON.stringify(updatedStructure)),
+    deletedDocuments,
+  };
+}
+
+removeDocumentsFromStructure.taskTitle = "Remove documents from structure";
+removeDocumentsFromStructure.description =
+  "Select and remove documents from the documentation structure";

package/agents/create/user-remove-document/review-documents-with-invalid-links.mjs

@@ -0,0 +1,116 @@
+import { buildAllowedLinksFromStructure } from "../../../utils/docs-finder-utils.mjs";
+
+/**
+ * Generate feedback message for fixing invalid links in a document
+ */
+function generateInvalidLinksFeedback(invalidLinks, documentPath, documentExecutionStructure) {
+  const invalidLinksList = invalidLinks.map((link) => `- ${link}`).join("\n");
+
+  // Build allowed links from document structure for replacement suggestions
+  const allowedLinks = buildAllowedLinksFromStructure(documentExecutionStructure);
+  const allowedLinksArray = Array.from(allowedLinks)
+    .filter((link) => link !== documentPath) // Exclude current document path
+    .sort();
+
+  const allowedLinksList =
+    allowedLinksArray.length > 0
+      ? allowedLinksArray.map((link) => `- ${link}`).join("\n")
+      : "(No available links)";
+
+  return `This document contains invalid links that need to be fixed. Please handle them according to the following instructions:
+
+**Invalid Links Found:**
+${invalidLinksList}
+
+**Available Valid Links:**
+${allowedLinksList}
+
+**Instructions for fixing invalid links:**
+
+1. For each invalid link found in the document:
+   - Using the document context and the list of available valid links, try to find a suitable replacement link from the available valid links.
+   - When choosing a replacement, exclude the current document path (${documentPath}); linking to the current document is not logical.
+   - **Do not consider the original invalid link or its related text**; they are outdated and should be replaced.
+
+2. If a suitable replacement link is found:
+   - Update **all related fields** associated with the invalid link (e.g., link URL, link text, surrounding context) according to the matched link from the available valid links.
+   - Ensure that after updating the link, the surrounding content remains consistent and natural. If there is a mismatch, update the corresponding content to keep everything aligned.
+
+3. If no suitable replacement link can be found:
+   - Remove the invalid link completely, including the link text and any associated content that only makes sense with that link.
+   - **Do not affect other unrelated content** in the document; only remove content that is directly tied to the invalid link.
+
+4. Ensure the document remains coherent and readable after the changes.`;
+}
+
+export default async function reviewDocumentsWithInvalidLinks(input = {}, options = {}) {
+  const { documentsWithInvalidLinks = [], documentExecutionStructure = [] } = input;
+
+  // If no documents with invalid links, return empty array
+  if (!Array.isArray(documentsWithInvalidLinks) || documentsWithInvalidLinks.length === 0) {
+    return {
+      documentsWithInvalidLinks: [],
+    };
+  }
+
+  // Create choices for user selection, default all checked
+  const choices = documentsWithInvalidLinks.map((doc) => {
+    const invalidLinksText =
+      doc.invalidLinks && doc.invalidLinks.length > 0
+        ? ` (${doc.invalidLinks.length} invalid link${doc.invalidLinks.length > 1 ? "s" : ""})`
+        : "";
+
+    return {
+      name: `${doc.title || doc.path}${invalidLinksText}`,
+      value: doc.path,
+      checked: true, // Default all selected
+      description: `Invalid Links: ${doc.invalidLinks.join(", ")}`,
+    };
+  });
+
+  // Let user select documents (default all selected)
+  const selectedPaths = await options.prompts.checkbox({
+    message:
+      "Select documents with invalid links to fix (all selected by default, press Enter to confirm, or unselect all to skip):",
+    choices,
+  });
+
+  // Filter documents based on user selection
+  const selectedPathsSet = new Set(selectedPaths);
+  const filteredDocs = documentsWithInvalidLinks.filter((doc) => selectedPathsSet.has(doc.path));
+
+  if (filteredDocs.length === 0) {
+    return {
+      documentsWithInvalidLinks: [],
+      documentsToUpdate: [],
+    };
+  }
+
+  // Prepare documents: add necessary fields for update (without content)
+  const preparedDocs = [];
+
+  for (const doc of filteredDocs) {
+    if (!doc.path) continue;
+
+    // Find corresponding document in documentStructure to get additional fields
+    const structureDoc = documentExecutionStructure.find((item) => item.path === doc.path);
+
+    // Generate feedback message for fixing invalid links
+    const feedback = generateInvalidLinksFeedback(
+      doc.invalidLinks,
+      doc.path,
+      documentExecutionStructure,
+    );
+
+    preparedDocs.push({
+      ...structureDoc,
+      feedback,
+      invalidLinks: doc.invalidLinks,
+    });
+  }
+
+  return {
+    documentsWithInvalidLinks: preparedDocs, // for print summary
+    documentsToUpdate: JSON.parse(JSON.stringify(preparedDocs)), // for batch update
+  };
+}

package/agents/create/user-review-document-structure.mjs

@@ -1,47 +1,8 @@
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { recordUpdate } from "../../utils/history-utils.mjs";
-import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
+import { printDocumentStructure } from "../../utils/docs-finder-utils.mjs";
 import equal from "fast-deep-equal";
 
-function formatDocumentStructure(structure) {
-  const { rootNodes } = buildDocumentTree(structure);
-
-  function printNode(node, depth = 0) {
-    const INDENT_SPACES = "  ";
-    const FOLDER_ICON = "  📁";
-    const FILE_ICON = "  📄";
-    const indent = INDENT_SPACES.repeat(depth);
-    const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
-
-    console.log(`${indent}${prefix} ${node.title}`);
-
-    if (node.children && node.children.length > 0) {
-      node.children.forEach((child) => {
-        printNode(child, depth + 1);
-      });
-    }
-  }
-
-  return { rootNodes, printNode };
-}
-
-function printDocumentStructure(structure) {
-  console.log(`\n  ${"-".repeat(50)}`);
-  console.log("  Current Documentation Structure");
-  console.log(`  ${"-".repeat(50)}`);
-
-  const { rootNodes, printNode } = formatDocumentStructure(structure);
-
-  if (rootNodes.length === 0) {
-    console.log("  No documentation structure found.");
-  } else {
-    rootNodes.forEach((node) => {
-      printNode(node);
-    });
-  }
-  console.log();
-}
-
 export default async function userReviewDocumentStructure({ documentStructure, ...rest }, options) {
   // Check if documentation structure exists
   if (!documentStructure || !Array.isArray(documentStructure) || documentStructure.length === 0) {

package/agents/create/utils/init-current-content.mjs

@@ -0,0 +1,38 @@
+import {
+  generateFileName,
+  pathToFlatName,
+  readFileContent,
+} from "../../../utils/docs-finder-utils.mjs";
+import { userContextAt } from "../../../utils/utils.mjs";
+
+/**
+ * Initialize currentContents in userContext for document update
+ * Reads document content from file system and sets it in userContext
+ */
+export default async function initCurrentContent(input, options) {
+  const { path, docsDir, locale = "en" } = input;
+
+  if (!path) {
+    return {};
+  }
+
+  // Generate filename from document path
+  const flatName = pathToFlatName(path);
+  const fileName = generateFileName(flatName, locale);
+
+  // Read document content
+  const content = docsDir ? await readFileContent(docsDir, fileName) : null;
+
+  if (!content) {
+    console.warn(`⚠️  Could not read content from ${fileName}`);
+    return {};
+  }
+
+  // Initialize currentContents[path] in userContext
+  const contentContext = userContextAt(options, `currentContents.${path}`);
+  contentContext.set(content);
+
+  return {};
+}
+
+initCurrentContent.task_render_mode = "hide";

package/agents/update/document-tools/update-document-content.mjs

@@ -4,15 +4,9 @@ import {
   getUpdateDocumentContentOutputJsonSchema,
   validateUpdateDocumentContentInput,
 } from "../../../types/document-schema.mjs";
+import { userContextAt } from "../../../utils/utils.mjs";
 
 export default async function updateDocumentContent(input, options) {
-  // Get originalContent from shared context, fallback to input
-  let originalContent = options?.context?.userContext?.currentContent;
-
-  if (!originalContent) {
-    originalContent = input.originalContent;
-  }
-
   // Validate input using Zod schema
   const validation = validateUpdateDocumentContentInput(input);
   if (!validation.success) {
@@ -22,7 +16,15 @@ export default async function updateDocumentContent(input, options) {
     };
   }
 
-  const { diffPatch } = validation.data;
+  const { diffPatch, path } = validation.data;
+
+  // Get originalContent from shared context using path, fallback to input
+  const contentContext = userContextAt(options, `currentContents.${path}`);
+  let originalContent = contentContext.get();
+
+  if (!originalContent) {
+    originalContent = input.originalContent;
+  }
 
   try {
     // Parse and validate diff patch
@@ -56,10 +58,8 @@ export default async function updateDocumentContent(input, options) {
       };
     }
 
-    // Update shared context with new content if options is provided
-    if (options?.context?.userContext) {
-      options.context.userContext.currentContent = result;
-    }
+    // Update shared context with new content using path
+    contentContext.set(result);
 
     return {
       success: true,

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

@@ -3,7 +3,7 @@ name: updateDocumentDetail
 description: Update and optimize document content based on user feedback using diff patches
 task_render_mode: collapse
 skills:
-  - url: ../utils/analyze-feedback-intent.yaml
+  - url: ../utils/analyze-document-feedback-intent.yaml
   - type: ai
     instructions:
       - role: system
@@ -48,9 +48,13 @@ skills:
         needDataSources:
           type: boolean
           description: Whether data sources are needed for content modifications
+        path:
+          type: string
+          description: Document path
       required:
         - originalContent
         - feedback
+        - path
     output_key: message
     afs:
       modules:

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

@@ -2,6 +2,7 @@ import { AIAgent } from "@aigne/core";
 import { pick } from "@aigne/core/utils/type-utils.js";
 import z from "zod";
 import { DIAGRAM_PLACEHOLDER, replacePlaceholder } from "../../../utils/d2-utils.mjs";
+import { userContextAt } from "../../../utils/utils.mjs";
 
 async function getIntentType(input, options) {
   const instructions = `<role>
@@ -47,19 +48,24 @@ async function saveDoc(input, options, { content }) {
 }
 
 async function addDiagram(input, options) {
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+  const currentContent = contentContext.get();
   const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
   const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
     ...pick(input, ["locale", "path", "diagramming", "feedback"]),
-    documentContent: options.context.userContext.currentContent,
+    documentContent: currentContent,
   });
   const content = generateDiagramResult.content;
+  contentContext.set(content);
   await saveDoc(input, options, { content });
   return { content };
 }
 
 async function updateDiagram(input, options) {
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+  const currentContent = contentContext.get();
   let [content, previousDiagramContent] = replacePlaceholder({
-    content: options.context.userContext.currentContent,
+    content: currentContent,
   });
   const generateAgent = options.context?.agents?.["generateDiagram"];
   const { diagramSourceCode } = await options.context.invoke(generateAgent, {
@@ -69,13 +75,16 @@ async function updateDiagram(input, options) {
     feedback: input.feedback,
   });
   content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
+  contentContext.set(content);
   await saveDoc(input, options, { content });
   return { content };
 }
 
 async function deleteDiagram(input, options) {
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+  const currentContent = contentContext.get();
   const [documentContent] = replacePlaceholder({
-    content: options.context.userContext.currentContent,
+    content: currentContent,
   });
   const instructions = `<role>
 Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (based on the user's feedback) to make it easier to understand.
@@ -103,22 +112,28 @@ Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (b
     documentContent,
     feedback: input.feedback,
   });
+  contentContext.set(content);
   await saveDoc(input, options, { content });
 
   return { content };
 }
 
 async function updateDocument(input, options) {
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+  const currentContent = contentContext.get();
   const updateAgent = options.context.agents["updateDocumentDetail"];
   const updateResult = await options.context.invoke(updateAgent, {
     ...input,
-    originalContent: options.context.userContext.currentContent,
+    originalContent: currentContent,
   });
   if (updateResult.message === "success") {
-    await saveDoc(input, options, { content: options.context.userContext.currentContent });
+    const updatedContent = contentContext.get();
+
+    contentContext.set(updatedContent);
+    await saveDoc(input, options, { content: updatedContent });
   }
   return {
-    content: options.context.userContext.currentContent,
+    content: contentContext.get(),
   };
 }
 

package/agents/update/user-review-document.mjs

@@ -1,6 +1,7 @@
 import { marked } from "marked";
 import markedTerminal from "marked-terminal";
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
+import { userContextAt } from "../../utils/utils.mjs";
 
 function extractMarkdownHeadings(content) {
   if (!content || typeof content !== "string") {
@@ -136,8 +137,9 @@ export default async function userReviewDocument({ content, description, ...rest
     printDocumentHeadings(content, title || "Untitled Document");
   }
 
-  // Initialize shared context with current content
-  options.context.userContext.currentContent = content;
+  // Initialize shared context with current content using path
+  const contentContext = userContextAt(options, `currentContents.${rest.path}`);
+  contentContext.set(content);
 
   const MAX_ITERATIONS = 100;
   const feedbacks = [];
@@ -174,10 +176,7 @@ export default async function userReviewDocument({ content, description, ...rest
       if (action === "finish") {
         break;
       } else if (action === "view") {
-        await showDocumentDetail(
-          options.context.userContext.currentContent,
-          title || "Untitled Document",
-        );
+        await showDocumentDetail(contentContext.get(), title || "Untitled Document");
       }
 
       // Ask for feedback
@@ -218,14 +217,15 @@ export default async function userReviewDocument({ content, description, ...rest
 
     try {
       // Call updateDocument agent with feedback
+      const currentContent = contentContext.get();
       const result = await options.context.invoke(updateAgent, {
         ...rest,
-        originalContent: options.context.userContext.currentContent,
+        originalContent: currentContent,
         feedback: feedback.trim(),
         userPreferences,
         title,
       });
-      options.context.userContext.currentContent = result.content;
+      contentContext.set(result.content);
 
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
@@ -242,10 +242,7 @@ export default async function userReviewDocument({ content, description, ...rest
       }
 
       // Print updated document headings structure
-      printDocumentHeadings(
-        options.context.userContext.currentContent,
-        title || "Untitled Document",
-      );
+      printDocumentHeadings(contentContext.get(), title || "Untitled Document");
 
       if (rest.isChat) {
         break;
@@ -267,7 +264,7 @@ export default async function userReviewDocument({ content, description, ...rest
     title,
     description,
     ...rest,
-    content: options.context.userContext.currentContent,
+    content: contentContext.get(),
     feedback: feedbacks.join(". "),
   };
 }

package/agents/utils/add-translates-to-structure.mjs

@@ -0,0 +1,29 @@
+export default function addTranslatesToStructure({
+  originalDocumentStructure = [],
+  translateLanguages = [],
+}) {
+  const documentExecutionStructure = (originalDocumentStructure || []).map((item) => ({
+    ...item,
+    translates: (translateLanguages || []).map((lang) => ({ language: lang })),
+  }));
+
+  return {
+    documentExecutionStructure,
+  };
+}
+
+addTranslatesToStructure.inputSchema = {
+  type: "object",
+  properties: {
+    originalDocumentStructure: { type: "array", items: { type: "object" } },
+    translateLanguages: { type: "array", items: { type: "string" } },
+  },
+  required: ["originalDocumentStructure", "translateLanguages"],
+};
+addTranslatesToStructure.outputSchema = {
+  type: "object",
+  properties: {
+    documentExecutionStructure: { type: "array" },
+  },
+};
+addTranslatesToStructure.task_render_mode = "hide";

package/agents/utils/{analyze-feedback-intent.yaml → analyze-document-feedback-intent.yaml}

@@ -1,8 +1,8 @@
-name: analyzeFeedbackIntent
+name: analyzeDocumentFeedbackIntent
 description: Analyze user feedback to determine if data sources are needed for content modifications
 task_render_mode: hide
 instructions:
-  url: ../../prompts/utils/analyze-feedback-intent.md
+  url: ../../prompts/utils/analyze-document-feedback-intent.md
 input_schema:
   type: object
   properties:
@@ -23,6 +23,9 @@ output_schema:
     reason:
       type: string
       description: Explanation of why data sources are or aren't needed
+    error: 
+      type: boolean
+      description: If an error occurs during the analysis process
   required:
     - needDataSources
     - intentType

package/agents/utils/analyze-structure-feedback-intent.yaml

@@ -0,0 +1,29 @@
+name: analyzeStructureFeedbackIntent
+description: Analyze user feedback to determine if data sources are needed for structure modifications
+task_render_mode: hide
+instructions:
+  url: ../../prompts/utils/analyze-structure-feedback-intent.md
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User feedback for structure modifications
+  required:
+    - feedback
+output_schema:
+  type: object
+  properties:
+    needDataSources:
+      type: boolean
+      description: Whether data sources are needed - true for add/edit operations that need context, false for delete/move/reorder operations
+    intentType:
+      type: string
+      description: The primary type of user intention
+    reason:
+      type: string
+      description: Explanation of why data sources are or aren't needed
+  required:
+    - needDataSources
+    - intentType
+    - reason

package/agents/utils/check-detail-result.mjs

@@ -1,4 +1,5 @@
 import { checkMarkdown } from "../../utils/markdown-checker.mjs";
+import { buildAllowedLinksFromStructure } from "../../utils/docs-finder-utils.mjs";
 
 export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
   if (!reviewContent || reviewContent.trim() === "") {
@@ -12,20 +13,7 @@ export default async function checkDetailResult({ documentStructure, reviewConte
   const detailFeedback = [];
 
   // Create a set of allowed links, including both original paths and processed .md paths
-  const allowedLinks = new Set();
-  documentStructure.forEach((item) => {
-    // Add original path
-    allowedLinks.add(item.path);
-
-    // Add processed .md path (same logic as processContent in utils.mjs)
-    let processedPath = item.path;
-    if (processedPath.startsWith(".")) {
-      processedPath = processedPath.replace(/^\./, "");
-    }
-    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
-    flatPath = `./${flatPath}.md`;
-    allowedLinks.add(flatPath);
-  });
+  const allowedLinks = buildAllowedLinksFromStructure(documentStructure);
 
   // Run comprehensive markdown validation with all checks
   try {

package/aigne.yaml

@@ -68,6 +68,7 @@ agents:
   - ./agents/clear/clear-media-description.mjs
 
   # Utilities
+  - ./agents/utils/add-translates-to-structure.mjs
   - ./agents/utils/load-sources.mjs
   - ./agents/utils/post-generate.mjs
   - ./agents/utils/save-sidebar.mjs
@@ -79,7 +80,8 @@ agents:
   - ./agents/utils/find-item-by-path.mjs
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
-  - ./agents/utils/analyze-feedback-intent.yaml
+  - ./agents/utils/analyze-structure-feedback-intent.yaml
+  - ./agents/utils/analyze-document-feedback-intent.yaml
 
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
@@ -126,6 +128,13 @@ cli:
         - url: ./agents/history/view.mjs
           name: view
           alias: ["log", "list"]
+    - name: add-document
+      alias: ["add"]
+      url: ./agents/create/user-add-document/index.yaml
+    - name: remove-document
+      alias: ["rm"]
+      url: ./agents/create/user-remove-document/index.yaml
+    - ./agents/clear/index.yaml
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.6-beta",
+  "version": "0.9.6-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"