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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.9.6-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.6-beta...v0.9.6-beta.1) (2025-11-19)
+
+
+### Features
+
+* support for add document and remove document ([#323](https://github.com/AIGNE-io/aigne-doc-smith/issues/323)) ([2672942](https://github.com/AIGNE-io/aigne-doc-smith/commit/26729424ca820eb962e79b4746c069887dd5a649))
+
+## [0.9.6-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5...v0.9.6-beta) (2025-11-18)
+
+
+### Features
+
+* smaller granularity of updated single-document ([#320](https://github.com/AIGNE-io/aigne-doc-smith/issues/320)) ([588b924](https://github.com/AIGNE-io/aigne-doc-smith/commit/588b924649f5f116a07586a1f6760ee6f7e79953))
+
+
+### Bug Fixes
+
+* always use short url during doc publish process ([#319](https://github.com/AIGNE-io/aigne-doc-smith/issues/319)) ([5fcf067](https://github.com/AIGNE-io/aigne-doc-smith/commit/5fcf067c2caf822576ee60e3f58a69040e5813f4))
+* tune document detail update output constraint ([#322](https://github.com/AIGNE-io/aigne-doc-smith/issues/322)) ([6ac8aa4](https://github.com/AIGNE-io/aigne-doc-smith/commit/6ac8aa49e9bb761164c60ccddc4b601b9c612203))
+
 ## [0.9.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5-beta.1...v0.9.5) (2025-11-14)
 
 ## [0.9.5-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5-beta...v0.9.5-beta.1) (2025-11-14)

package/agents/create/document-structure-tools/delete-document.mjs

@@ -16,7 +16,7 @@ export default async function deleteDocument(input, options) {
     };
   }
 
-  const { path } = validation.data;
+  const { path, recursive = false } = validation.data;
   let documentStructure = options?.context?.userContext?.currentStructure;
 
   if (!documentStructure) {
@@ -36,10 +36,27 @@ export default async function deleteDocument(input, options) {
 
   const documentToDelete = documentStructure[documentIndex];
 
-  // Check if any other documents have this document as parent
-  const childDocuments = documentStructure.filter((item) => item.parentId === path);
-  if (childDocuments.length > 0) {
-    const errorMessage = `Cannot delete document: Document '${path}' has ${childDocuments.length} child document(s): ${childDocuments.map((p) => p.path).join(", ")}. Please first move or delete these child documents.`;
+  // Find all child documents (direct and indirect)
+  const findAllChildren = (parentPath, structure) => {
+    const children = structure.filter((item) => item.parentId === parentPath);
+    const allChildren = [...children];
+    for (const child of children) {
+      allChildren.push(...findAllChildren(child.path, structure));
+    }
+    return allChildren;
+  };
+
+  const childDocuments = findAllChildren(path, documentStructure);
+
+  // If recursive is false and there are child documents, return error
+  if (!recursive && childDocuments.length > 0) {
+    const errorMessage = `Cannot delete document: Document '${path}' has ${
+      childDocuments.length
+    } child document(s): ${childDocuments
+      .map((p) => p.path)
+      .join(
+        ", ",
+      )}. Please first move or delete these child documents, or set recursive=true to delete them all.`;
     console.log(`⚠️  ${errorMessage}`);
     return {
       documentStructure,
@@ -47,11 +64,17 @@ export default async function deleteDocument(input, options) {
     };
   }
 
-  // Remove the document from the structure
-  const updatedStructure = documentStructure.filter((_, index) => index !== documentIndex);
+  // Collect all documents to delete (children first, then parent)
+  const documentsToDelete = recursive ? [...childDocuments, documentToDelete] : [documentToDelete];
+  const pathsToDelete = new Set(documentsToDelete.map((doc) => doc.path));
+  const deletedCount = pathsToDelete.size - 1;
+
+  // Remove all documents from the structure
+  const updatedStructure = documentStructure.filter((item) => !pathsToDelete.has(item.path));
 
+  // Build success message
   const successMessage = `deleteDocument executed successfully.
-  Successfully deleted document '${documentToDelete.title}' with path '${path}'.
+  Successfully deleted document '${documentToDelete.title}' with path '${path}'${recursive && deletedCount > 0 ? ` along with ${deletedCount} child document(s)` : ""}.
   Check if the latest version of documentStructure meets user feedback, if so, just return 'success'.`;
 
   // update shared document structure
@@ -62,7 +85,7 @@ export default async function deleteDocument(input, options) {
   return {
     documentStructure: updatedStructure,
     message: successMessage,
-    deletedDocument: documentToDelete,
+    deletedDocuments: documentsToDelete,
   };
 }
 

package/agents/create/update-document-structure.yaml

@@ -2,7 +2,7 @@ type: team
 name: updateDocumentStructure
 description: Update documentation structure based on user feedback and intentions using structure modification tools
 skills:
-  - url: ../utils/analyze-feedback-intent.yaml
+  - url: ../utils/analyze-structure-feedback-intent.yaml
   - type: ai
     instructions:
       - role: system

package/agents/create/user-add-document/add-documents-to-structure.mjs

@@ -0,0 +1,96 @@
+import { getActiveRulesForScope } from "../../../utils/preferences-utils.mjs";
+import { printDocumentStructure } from "../../../utils/docs-finder-utils.mjs";
+import addTranslatesToStructure from "../../utils/add-translates-to-structure.mjs";
+
+export default async function addDocumentsToStructure(input = {}, options = {}) {
+  const { originalDocumentStructure = [], translateLanguages = [] } = input;
+  const analyzeIntent = options.context?.agents?.["analyzeStructureFeedbackIntent"];
+  const updateDocumentStructure = options.context?.agents?.["updateDocumentStructure"];
+  const allFeedback = [];
+  let currentStructure = [...originalDocumentStructure];
+  let isFirstAdd = true;
+
+  printDocumentStructure(originalDocumentStructure);
+
+  // update website structure
+  if (!options.context.userContext) {
+    options.context.userContext = {};
+  }
+
+  // Add document
+  while (true) {
+    let feedback = await options.prompts.input({
+      message: isFirstAdd
+        ? "You can add a new document.\n" +
+          "  • e.g. Add a new document 'Troubleshooting'\n\n" +
+          "Press Enter to finish:"
+        : "You can continue adding documents, or press Enter to finish:",
+    });
+
+    feedback = feedback.trim();
+
+    // end the loop
+    if (!feedback) {
+      break;
+    }
+
+    try {
+      // validate feedback
+      const { intentType } = await options.context.invoke(analyzeIntent, {
+        feedback,
+      });
+
+      if (intentType !== "add") {
+        console.log(`⚠️  You can only add documents at this stage.`);
+        continue;
+      }
+      options.context.userContext.currentStructure = currentStructure;
+
+      const structureRules = getActiveRulesForScope("structure", []);
+      const globalRules = getActiveRulesForScope("global", []);
+      const allApplicableRules = [...structureRules, ...globalRules];
+      const userPreferences = allApplicableRules.map((rule) => rule.rule).join("\n\n");
+
+      await options.context.invoke(updateDocumentStructure, {
+        ...input,
+        dataSourceChunk: input.dataSources[0].dataSourceChunk,
+        feedback,
+        documentStructure: currentStructure,
+        needDataSources: true,
+        userPreferences,
+      });
+
+      allFeedback.push(feedback);
+
+      currentStructure = options.context.userContext.currentStructure;
+      printDocumentStructure(currentStructure);
+      isFirstAdd = false;
+    } catch (error) {
+      console.error("Error processing feedback:", {
+        type: error.name,
+        message: error.message,
+      });
+      process.exit(0);
+    }
+  }
+
+  if (currentStructure.length > originalDocumentStructure.length) {
+    const originalPaths = new Set(originalDocumentStructure.map((doc) => doc.path));
+    const { documentExecutionStructure } = addTranslatesToStructure({
+      originalDocumentStructure: currentStructure,
+      translateLanguages,
+    });
+    const newDocuments = documentExecutionStructure.filter((doc) => !originalPaths.has(doc.path));
+
+    return {
+      originalDocumentStructure: currentStructure,
+      documentStructure: JSON.parse(JSON.stringify(currentStructure)),
+      documentExecutionStructure,
+      newDocuments,
+      allFeedback,
+    };
+  } else {
+    console.log("No documents were added");
+    process.exit(0);
+  }
+}

package/agents/create/user-add-document/find-documents-to-add-links.yaml

@@ -0,0 +1,47 @@
+name: findDocumentsToAddLinks
+description: Use AI to analyze document structure and determine which documents should reference newly added documents
+task_render_mode: hide
+instructions:
+  - role: system
+    url: ../../../prompts/structure/find-documents-to-add-links.md
+input_schema:
+  type: object
+  properties:
+    originalDocumentStructure:
+      type: array
+      description: Original document structure before adding documents
+    documentStructure:
+      type: array
+      description: Updated document structure after adding documents
+    newDocuments:
+      type: array
+      description: Array of newly added documents
+  required:
+    - originalDocumentStructure
+    - documentStructure
+    - newDocuments
+output_schema:
+  type: object
+  properties:
+    documentsWithNewLinks:
+      type: array
+      description: Array of existing documents that should add links to new documents
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: The path of the existing document that should be updated
+          newLinks:
+            type: array
+            description: Array of new document paths that should be added as links to this document
+            items:
+              type: string
+        required:
+          - path
+          - newLinks
+  required:
+    - documentsWithNewLinks
+
+
+

package/agents/create/user-add-document/index.yaml

@@ -0,0 +1,46 @@
+type: team
+name: userAddDocument
+description: Add documents to the documentation structure
+skills:
+  - url: ../../init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../../utils/load-sources.mjs
+  - ./add-documents-to-structure.mjs
+  - url: ../../utils/save-output.mjs
+    default_input:
+      saveKey: documentStructure
+      savePath:
+        $get: outputDir
+      fileName: structure-plan.json
+  - ../../utils/save-sidebar.mjs
+  - ../../utils/ensure-document-icons.mjs
+  - ../../utils/format-document-structure.mjs
+  - ../../media/load-media-description.mjs
+  - type: team
+    skills:
+      - ../../update/check-document.mjs
+    iterate_on: newDocuments
+    concurrency: 5
+  - ./find-documents-to-add-links.yaml
+  - ./review-documents-with-new-links.mjs
+  - type: team
+    name: batchAddNewLinks
+    description: Batch add new links to documents
+    skills:
+      - ../utils/init-current-content.mjs
+      - ../../utils/transform-detail-data-sources.mjs
+      - ../../update/update-single/update-single-document-detail.mjs
+    iterate_on: documentsToUpdate
+    concurrency: 5
+  - ./prepare-documents-to-translate.mjs
+  - type: team
+    name: batchTranslateDocuments
+    description: Batch translate documents to multiple languages
+    skills:
+      - ../../localize/translate-multilingual.yaml
+    iterate_on: documentsToTranslate
+    concurrency: 5
+  - ../../utils/post-generate.mjs
+  - ./print-add-document-summary.mjs
+mode: sequential

package/agents/create/user-add-document/prepare-documents-to-translate.mjs

@@ -0,0 +1,22 @@
+export default async function prepareDocumentsToTranslate(input, options) {
+  const { documentsWithNewLinks = [] } = input;
+  const documentsToTranslate = [];
+
+  documentsWithNewLinks.forEach((doc) => {
+    const content = options.context.userContext.currentContents[doc.path];
+
+    if (content) {
+      documentsToTranslate.push({
+        ...doc,
+        content,
+      });
+    } else {
+      console.warn(`⚠️  Could not find content from userContext at path: ${doc.path}`);
+    }
+  });
+
+  return {
+    documentsToUpdate: [], // clear, reduce token consumption
+    documentsToTranslate,
+  };
+}

package/agents/create/user-add-document/print-add-document-summary.mjs

@@ -0,0 +1,56 @@
+import chalk from "chalk";
+
+/**
+ * Print summary of added documents and documents with new links
+ */
+export default async function printAddDocumentSummary({
+  newDocuments = [],
+  documentsWithNewLinks = [],
+}) {
+  let message = `\n${"=".repeat(80)}\n`;
+  message += `${chalk.bold.cyan("📊 Summary")}\n`;
+  message += `${"=".repeat(80)}\n\n`;
+
+  // Display added documents
+  if (newDocuments && newDocuments.length > 0) {
+    message += `✨ Added Documents:\n`;
+    message += `   Total: ${newDocuments.length} document(s)\n\n`;
+    newDocuments.forEach((doc, index) => {
+      message += `   ${chalk.cyan(`${index + 1}. ${doc.path}`)}`;
+      if (doc.title && doc.title !== doc.path) {
+        message += ` - ${chalk.yellow(doc.title)}`;
+      }
+      message += `\n\n`;
+    });
+  } else {
+    message += `✨ Added Documents:\n`;
+    message += `${chalk.gray("   No documents were added.\n\n")}`;
+  }
+
+  // Display documents with new links
+  if (documentsWithNewLinks && documentsWithNewLinks.length > 0) {
+    message += `✅ Documents updated (Added new links):\n`;
+    message += `   Total: ${documentsWithNewLinks.length} document(s)\n\n`;
+    documentsWithNewLinks.forEach((doc, index) => {
+      message += `   ${chalk.cyan(`${index + 1}. ${doc.path}`)}`;
+      if (doc.title && doc.title !== doc.path) {
+        message += ` - ${chalk.yellow(doc.title)}`;
+      }
+      message += `\n`;
+      if (doc.newLinks && doc.newLinks.length > 0) {
+        message += `      New links added: ${chalk.gray(doc.newLinks.join(", "))}\n`;
+      }
+      message += `\n`;
+    });
+  } else {
+    message += `✅ Documents updated (Added new links):\n`;
+    message += `${chalk.gray("   No documents needed to be updated.\n\n")}`;
+  }
+
+  message += `${"=".repeat(80)}\n\n`;
+
+  return { message };
+}
+
+printAddDocumentSummary.taskTitle = "Print add document summary";
+printAddDocumentSummary.description = "Display summary of added documents";

package/agents/create/user-add-document/review-documents-with-new-links.mjs

@@ -0,0 +1,73 @@
+/**
+ * Review documentsWithNewLinks and let user select which documents should be updated
+ */
+export default async function reviewDocumentsWithNewLinks(
+  { documentsWithNewLinks = [], documentExecutionStructure = [] },
+  options,
+) {
+  // If no documents to review, return empty array
+  if (!documentsWithNewLinks || documentsWithNewLinks.length === 0) {
+    return { documentsWithNewLinks: [] };
+  }
+
+  // Let user select which documents to update (default: all selected)
+  const selectedDocs = await options.prompts.checkbox({
+    message:
+      "Select documents that need new links added (all selected by default, press Enter to confirm, or unselect all to skip):",
+    choices: documentsWithNewLinks.map((document, index) => ({
+      name: `${document.path} → ${document.newLinks.join(", ")}`,
+      value: index,
+      checked: true, // Default to all selected
+    })),
+  });
+
+  // Filter documentsWithNewLinks based on user selection
+  const filteredDocs = selectedDocs.map((index) => documentsWithNewLinks[index]).filter(Boolean);
+
+  if (filteredDocs.length === 0) {
+    console.log(`\n⚠️  No documents selected. Skipping link updates.\n`);
+  } else {
+    console.log(
+      `\n✅ Selected ${filteredDocs.length} out of ${documentsWithNewLinks.length} documents to update.\n`,
+    );
+  }
+
+  // save original documentsWithNewLinks to user context
+  options.context.userContext.originalDocumentsWithNewLinks = filteredDocs;
+
+  if (filteredDocs.length === 0) {
+    return {
+      documentsWithNewLinks: [],
+      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 adding new links
+    const newLinksList = doc.newLinks.join(", ");
+    const feedback = `Add the following links to this document: ${newLinksList}. Identify suitable places within the existing content — such as relevant sections, navigation items — and insert the links naturally to maintain context and readability.`;
+
+    preparedDocs.push({
+      ...structureDoc,
+      feedback,
+      newLinks: doc.newLinks,
+    });
+  }
+
+  return {
+    documentsWithNewLinks: preparedDocs, // for print summary
+    documentsToUpdate: JSON.parse(JSON.stringify(preparedDocs)), // for batch update
+  };
+}
+
+reviewDocumentsWithNewLinks.taskTitle = "Review documents to update";
+reviewDocumentsWithNewLinks.description =
+  "Let the user review and select which documents should be updated with new links";

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

@@ -0,0 +1,67 @@
+import {
+  buildAllowedLinksFromStructure,
+  generateFileName,
+  pathToFlatName,
+  readFileContent,
+} from "../../../utils/docs-finder-utils.mjs";
+import { checkMarkdown, getLinkFromError } from "../../../utils/markdown-checker.mjs";
+
+export default async function findDocumentsWithInvalidLinks({
+  documentStructure = [],
+  docsDir,
+  locale = "en",
+}) {
+  if (!Array.isArray(documentStructure) || documentStructure.length === 0) {
+    return {
+      documentsWithInvalidLinks: [],
+    };
+  }
+
+  if (!docsDir) {
+    return {
+      documentsWithInvalidLinks: [],
+      error: "docsDir is required to check document links",
+    };
+  }
+
+  // Check each document for invalid links
+  const allowedLinks = buildAllowedLinksFromStructure(documentStructure);
+  const documentsWithInvalidLinks = [];
+
+  for (const doc of documentStructure) {
+    if (!doc.path) continue;
+
+    // Generate filename from document path
+    const flatName = pathToFlatName(doc.path);
+    const fileName = generateFileName(flatName, locale);
+
+    // Read document content
+    const content = await readFileContent(docsDir, fileName);
+
+    if (!content) {
+      // Skip if content cannot be read
+      continue;
+    }
+
+    // Use checkMarkdown to check for dead links
+    const allErrors = await checkMarkdown(content, doc.path, {
+      allowedLinks,
+      baseDir: docsDir,
+    });
+
+    // Filter only dead link errors and extract invalid links
+    const invalidLinks = allErrors.map(getLinkFromError).filter(Boolean);
+
+    if (invalidLinks.length > 0) {
+      documentsWithInvalidLinks.push({
+        path: doc.path,
+        title: doc.title || doc.path,
+        invalidLinks,
+      });
+    }
+  }
+
+  return {
+    documentsWithInvalidLinks,
+  };
+}

package/agents/create/user-remove-document/index.yaml

@@ -0,0 +1,41 @@
+type: team
+name: userRemoveDocument
+description: Remove documents from the documentation structure
+skills:
+  - url: ../../init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../../utils/load-sources.mjs
+  - ./remove-documents-from-structure.mjs
+  - url: ../../utils/save-output.mjs
+    default_input:
+      saveKey: documentStructure
+      savePath:
+        $get: outputDir
+      fileName: structure-plan.json
+  - ../../utils/save-sidebar.mjs
+  - ./find-documents-with-invalid-links.mjs
+  - ../../utils/add-translates-to-structure.mjs
+  - ./review-documents-with-invalid-links.mjs
+  - ../../utils/format-document-structure.mjs
+  - ../../media/load-media-description.mjs
+  - type: team
+    name: batchRemoveInvalidLinks
+    description: Batch remove invalid links from documents
+    skills:
+      - ../utils/init-current-content.mjs
+      - ../../utils/transform-detail-data-sources.mjs
+      - ../../update/update-single/update-single-document-detail.mjs
+    iterate_on: documentsToUpdate
+    concurrency: 5
+  - ./prepare-documents-to-translate.mjs
+  - type: team
+    name: batchTranslateDocuments
+    description: Batch translate documents to multiple languages
+    skills:
+      - ../../localize/translate-multilingual.yaml
+    iterate_on: documentsToTranslate
+    concurrency: 5
+  - ../../utils/post-generate.mjs
+  - ./print-remove-document-summary.mjs
+mode: sequential

package/agents/create/user-remove-document/prepare-documents-to-translate.mjs

@@ -0,0 +1,22 @@
+export default async function prepareDocumentsToTranslate(input, options) {
+  const { documentsWithInvalidLinks = [] } = input;
+  const documentsToTranslate = [];
+
+  documentsWithInvalidLinks.forEach((doc) => {
+    const content = options.context.userContext.currentContents[doc.path];
+
+    if (content) {
+      documentsToTranslate.push({
+        ...doc,
+        content,
+      });
+    } else {
+      console.warn(`⚠️  Could not find content from userContext at path: ${doc.path}`);
+    }
+  });
+
+  return {
+    documentsToUpdate: [], // clear, reduce token consumption
+    documentsToTranslate,
+  };
+}

package/agents/create/user-remove-document/print-remove-document-summary.mjs

@@ -0,0 +1,56 @@
+import chalk from "chalk";
+
+/**
+ * Print summary of removed documents and documents with invalid links
+ */
+export default async function printRemoveDocumentSummary({
+  deletedDocuments = [],
+  documentsWithInvalidLinks = [],
+}) {
+  let message = `\n${"=".repeat(80)}\n`;
+  message += `${chalk.bold.cyan("📊 Summary")}\n`;
+  message += `${"=".repeat(80)}\n\n`;
+
+  // Display removed documents
+  if (deletedDocuments && deletedDocuments.length > 0) {
+    message += `🗑️  Removed Documents:\n`;
+    message += `   Total: ${deletedDocuments.length} document(s)\n\n`;
+    deletedDocuments.forEach((doc, index) => {
+      message += `   ${chalk.cyan(`${index + 1}. ${doc.path}`)}`;
+      if (doc.title && doc.title !== doc.path) {
+        message += ` - ${chalk.yellow(doc.title)}`;
+      }
+      message += `\n\n`;
+    });
+  } else {
+    message += `🗑️  Removed Documents:\n`;
+    message += `${chalk.gray("   No documents were removed.\n\n")}`;
+  }
+
+  // Display documents with invalid links
+  if (documentsWithInvalidLinks && documentsWithInvalidLinks.length > 0) {
+    message += `✅ Documents fixed (Removed invalid links):\n`;
+    message += `   Total: ${documentsWithInvalidLinks.length} document(s)\n\n`;
+    documentsWithInvalidLinks.forEach((doc, index) => {
+      message += `   ${chalk.cyan(`${index + 1}. ${doc.path}`)}`;
+      if (doc.title && doc.title !== doc.path) {
+        message += ` - ${chalk.yellow(doc.title)}`;
+      }
+      message += `\n`;
+      if (doc.invalidLinks && doc.invalidLinks.length > 0) {
+        message += `      Invalid links fixed: ${chalk.gray(doc.invalidLinks.join(", "))}\n`;
+      }
+      message += `\n`;
+    });
+  } else {
+    message += `✅ Documents fixed (Removed invalid links):\n`;
+    message += `${chalk.gray("   No documents needed to be fixed.\n\n")}`;
+  }
+
+  message += `${"=".repeat(80)}\n\n`;
+
+  return { message };
+}
+
+printRemoveDocumentSummary.taskTitle = "Print remove document summary";
+printRemoveDocumentSummary.description = "Display summary of removed documents";