@aigne/doc-smith 0.9.5 → 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/init/check.mjs

@@ -11,6 +11,6 @@ export default async function checkNeedGenerate({ docsDir, locale, documentExecu
     process.exit(0);
   }
   return {
-    message: 'Documents found in the docs directory, skipping "generate" step',
+    message: 'Documents found in the docs directory, skipping "create" step',
   };
 }

package/agents/update/check-generate-diagram.mjs

@@ -1,4 +1,5 @@
-const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+import { DIAGRAM_PLACEHOLDER } from "../../utils/d2-utils.mjs";
+
 const DEFAULT_DIAGRAMMING_EFFORT = 5;
 const MIN_DIAGRAMMING_EFFORT = 0;
 const MAX_DIAGRAMMING_EFFORT = 10;
@@ -66,8 +67,8 @@ export default async function checkGenerateDiagram(
     }
 
     if (diagramSourceCode && !skipGenerateDiagram) {
-      if (content.includes(PLACEHOLDER)) {
-        content = content.replace(PLACEHOLDER, diagramSourceCode);
+      if (content.includes(DIAGRAM_PLACEHOLDER)) {
+        content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
       } else {
         const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
         ({ content } = await options.context.invoke(mergeAgent, {

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

@@ -0,0 +1,155 @@
+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>
+You are a feedback intent analyzer. Your task is to determine which type of content modifications are needed based on the user's feedback.
+</role>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>`;
+  const analyzeUpdateFeedbackIntentAgent = AIAgent.from({
+    name: "analyzeUpdateFeedbackIntent",
+    description:
+      "Analyze user feedback to determine if document are needed for content modifications",
+    task_render_mode: "hide",
+    instructions,
+    // TODO: can't set reasoningEffort
+    // modelOptions: {
+    //   reasoningEffort: 1,
+    // },
+    inputSchema: z.object({
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputSchema: z.object({
+      intentType: z
+        .enum(["addDiagram", "deleteDiagram", "updateDiagram", "updateDocument"])
+        .describe(
+          "The primary type of user intention: one of addDiagram, deleteDiagram, updateDiagram, updateDocument",
+        ),
+    }),
+  });
+  const { intentType } = await options.context.invoke(analyzeUpdateFeedbackIntentAgent, {
+    feedback: input.feedback,
+  });
+  return intentType;
+}
+
+async function saveDoc(input, options, { content }) {
+  const saveAgent = options.context?.agents?.["saveDoc"];
+  await options.context.invoke(saveAgent, {
+    ...pick(input, ["path", "docsDir", "labels", "locale"]),
+    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: 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: currentContent,
+  });
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  const { diagramSourceCode } = await options.context.invoke(generateAgent, {
+    documentContent: content,
+    locale: input.locale,
+    previousDiagramContent,
+    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: 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.
+</role>
+
+<document_content>
+{{documentContent}}
+</document_content>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>`;
+  const deleteAgent = AIAgent.from({
+    name: "deleteDiagram",
+    description: "Remove a diagram from the document content",
+    task_render_mode: "hide",
+    instructions,
+    inputSchema: z.object({
+      documentContent: z.string().describe("Source content of the document"),
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputKey: "message",
+  });
+  const { message: content } = await options.context.invoke(deleteAgent, {
+    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: currentContent,
+  });
+  if (updateResult.message === "success") {
+    const updatedContent = contentContext.get();
+
+    contentContext.set(updatedContent);
+    await saveDoc(input, options, { content: updatedContent });
+  }
+  return {
+    content: contentContext.get(),
+  };
+}
+
+export default async function updateSingleDocumentDetail(input, options) {
+  const intentType = await getIntentType(input, options);
+
+  const fnMap = {
+    addDiagram,
+    updateDiagram,
+    deleteDiagram,
+    updateDocument,
+  };
+
+  if (fnMap[intentType]) {
+    const result = await fnMap[intentType](input, options);
+    return result;
+  }
+  return {};
+}

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
@@ -200,7 +199,7 @@ export default async function userReviewDocument({ content, description, ...rest
     }
 
     // Get the updateDocument agent
-    const updateAgent = options.context.agents["handleDocumentUpdate"];
+    const updateAgent = options.context.agents["updateSingleDocumentDetail"];
     if (!updateAgent) {
       console.log(
         "We can't process your feedback right now. The document update feature is temporarily unavailable.",
@@ -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