@aigne/doc-smith 0.9.10 → 0.9.11-beta

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

@@ -1,114 +0,0 @@
-import { DOC_ACTION } from "../../utils/constants/index.mjs";
-import {
-  fileNameToFlatPath,
-  findItemByFlatName,
-  findItemByPath as findItemByPathUtil,
-  getActionText,
-  getMainLanguageFiles,
-  readFileContent,
-} from "../../utils/docs-finder-utils.mjs";
-
-export default async function findItemByPath(
-  { doc, documentStructure, boardId, docsDir, isTranslate, feedback, locale },
-  options,
-) {
-  let foundItem = null;
-  let selectedFileContent = null;
-  let docPath = doc;
-  const docAction = isTranslate ? DOC_ACTION.translate : DOC_ACTION.update;
-
-  // If docPath is empty, let user select from available documents
-  if (!docPath) {
-    try {
-      // Get all main language .md files in docsDir
-      const mainLanguageFiles = await getMainLanguageFiles(docsDir, locale, documentStructure);
-
-      if (mainLanguageFiles.length === 0) {
-        throw new Error("No documents found in the docs directory");
-      }
-
-      // Let user select a file
-      const selectedFile = await options.prompts.search({
-        message: getActionText("Select a document to {action}:", docAction),
-        source: async (input) => {
-          if (!input || input.trim() === "") {
-            return mainLanguageFiles.map((file) => ({
-              name: file,
-              value: file,
-            }));
-          }
-
-          const searchTerm = input.trim().toLowerCase();
-          const filteredFiles = mainLanguageFiles.filter((file) =>
-            file.toLowerCase().includes(searchTerm),
-          );
-
-          return filteredFiles.map((file) => ({
-            name: file,
-            value: file,
-          }));
-        },
-      });
-
-      if (!selectedFile) {
-        throw new Error("No document selected");
-      }
-
-      // Read the selected .md file content
-      selectedFileContent = await readFileContent(docsDir, selectedFile);
-
-      // Convert filename back to path
-      const flatName = fileNameToFlatPath(selectedFile);
-
-      // Try to find matching item by comparing flattened paths
-      const foundItemByFile = findItemByFlatName(documentStructure, flatName);
-
-      if (!foundItemByFile) {
-        throw new Error("No document found");
-      }
-
-      docPath = foundItemByFile.path;
-    } catch (error) {
-      console.debug(error?.message);
-      throw new Error(
-        getActionText(
-          "Please run 'aigne doc create' first to create documents, then select which document to {action}",
-          docAction,
-        ),
-      );
-    }
-  }
-
-  // Use the utility function to find item and read content
-  foundItem = await findItemByPathUtil(documentStructure, docPath, boardId, docsDir, locale);
-
-  if (!foundItem) {
-    throw new Error(`Item with path "${docPath}" not found in documentStructure`);
-  }
-
-  // Prompt for feedback if not provided
-  let userFeedback = feedback;
-  if (!userFeedback) {
-    const feedbackMessage = "How should we improve this document? (press Enter to skip):";
-    userFeedback = await options.prompts.input({
-      message: feedbackMessage,
-    });
-  }
-
-  // Merge the found item and ensure content is available
-  const result = {
-    ...foundItem,
-  };
-
-  // Add content if we read it from user selection (takes precedence over utility method content)
-  if (selectedFileContent !== null) {
-    result.content = selectedFileContent;
-  }
-
-  // Add feedback to result if provided
-  if (userFeedback?.trim()) {
-    result.feedback = userFeedback.trim();
-  }
-
-  return result;
-}

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

@@ -1,37 +0,0 @@
-import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
-
-export default async function findUserPreferencesByPath({ path, scope }) {
-  // Get global rules (always applicable)
-  const globalRules = getActiveRulesForScope("global", []);
-
-  // Get scope-specific rules (document/translation based on scope parameter)
-  const scopeRules = getActiveRulesForScope(scope, path ? [path] : []);
-
-  // Combine all applicable rules
-  const allApplicableRules = [...globalRules, ...scopeRules];
-
-  // Extract only rule text and join with double newlines
-  const ruleTexts = allApplicableRules.map((rule) => rule.rule);
-  const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
-
-  return {
-    userPreferences,
-  };
-}
-
-findUserPreferencesByPath.input_schema = {
-  type: "object",
-  properties: {
-    path: {
-      type: "string",
-      description: "Document path to find preferences for",
-    },
-    scope: {
-      type: "string",
-      description:
-        "Preference scope: 'document' for update operations, 'translation' for translate operations",
-      enum: ["document", "translation"],
-    },
-  },
-  required: ["scope"],
-};

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

@@ -1,35 +0,0 @@
-import { stringify } from "yaml";
-
-export default async function formatDocumentStructure({
-  documentStructure,
-  originalDocumentStructure,
-}) {
-  if (!documentStructure && !originalDocumentStructure) {
-    return {
-      documentStructureYaml: "",
-      documentStructure: [],
-    };
-  }
-
-  // Extract required fields from each item in documentStructure
-  const formattedData = (documentStructure || originalDocumentStructure)?.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/utils/generate-document-or-skip.mjs

@@ -1,41 +0,0 @@
-/**
- * Conditionally call generateDocument. If we already have content for diagram-only intents,
- * skip LLM generation and pass through the existing content.
- */
-export default async function generateDocumentOrSkip(input, options) {
-  const { intentType, content, skipGenerateDocument } = input;
-
-  const isDiagramIntent =
-    intentType && ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType);
-  const shouldSkip = Boolean(skipGenerateDocument || (isDiagramIntent && content));
-
-  if (shouldSkip) {
-    // Return the existing content and mark the generation as skipped
-    return {
-      ...input,
-      content,
-      documentContent: content,
-      originalContent: content,
-      reviewContent: content,
-    };
-  }
-
-  const generateAgent = options.context?.agents?.["generateDocument"];
-  if (!generateAgent) {
-    throw new Error("generateDocument agent not found");
-  }
-
-  const result = await options.context.invoke(generateAgent, input);
-  const generatedContent = result?.content ?? result;
-
-  return {
-    ...input,
-    ...result,
-    content: generatedContent,
-    documentContent: generatedContent,
-    originalContent: generatedContent,
-    reviewContent: generatedContent,
-  };
-}
-
-generateDocumentOrSkip.task_render_mode = "hide";

package/agents/utils/handle-diagram-operations.mjs

@@ -1,263 +0,0 @@
-import { AIAgent } from "@aigne/core";
-import { pick } from "@aigne/core/utils/type-utils.js";
-import z from "zod";
-import {
-  DIAGRAM_PLACEHOLDER,
-  replaceD2WithPlaceholder,
-  replaceDiagramsWithPlaceholder,
-} from "../../utils/d2-utils.mjs";
-import { readFileContent } from "../../utils/docs-finder-utils.mjs";
-import { getFileName, userContextAt } from "../../utils/utils.mjs";
-import { debug } from "../../utils/debug.mjs";
-
-/**
- * Read current document content from file system
- * Reuses the same logic as initCurrentContent but returns the content
- * First checks userContext, then reads from file if not in context
- */
-async function readCurrentContent(input, options) {
-  const { path, docsDir, locale = "en" } = input;
-
-  if (!path || !docsDir) {
-    return null;
-  }
-
-  // First check if content is already in userContext
-  const contentContext = userContextAt(options, `currentContents.${path}`);
-  const existingContent = contentContext.get();
-  if (existingContent) {
-    return existingContent;
-  }
-
-  // If not in context, read from file (same logic as initCurrentContent)
-  try {
-    const fileName = getFileName(path, locale);
-    const content = await readFileContent(docsDir, fileName);
-
-    if (!content) {
-      console.warn(`⚠️  Could not read content from ${fileName}`);
-      return null;
-    }
-
-    // Set in userContext for future use
-    contentContext.set(content);
-
-    return content;
-  } catch (error) {
-    console.warn(`Failed to read current content for ${path}: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Save document content
- */
-async function saveDoc(input, options, { content, intentType }) {
-  const saveAgent = options.context?.agents?.["saveDoc"];
-  if (!saveAgent) {
-    console.warn("saveDoc agent not found");
-    return;
-  }
-  await options.context.invoke(saveAgent, {
-    ...pick(input, ["path", "docsDir", "labels", "locale"]),
-    content,
-    intentType, // Pass intentType so saveDoc can handle translation sync
-  });
-}
-
-/**
- * Handle addDiagram intent
- */
-async function addDiagram(input, options) {
-  // readCurrentContent will check userContext first, then read from file if needed
-  const currentContent = await readCurrentContent(input, options);
-  if (!currentContent) {
-    throw new Error(`Could not read current content for ${input.path}`);
-  }
-
-  const contentContext = userContextAt(options, `currentContents.${input.path}`);
-
-  const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
-  if (!generateDiagramAgent) {
-    throw new Error("checkGenerateDiagram agent not found");
-  }
-
-  const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
-    ...pick(input, ["locale", "diagramming", "feedback", "path", "docsDir"]),
-    documentContent: currentContent,
-    originalContent: currentContent,
-  });
-
-  const content = generateDiagramResult.content;
-  contentContext.set(content);
-  // Pass intentType to saveDoc so it can handle translation sync automatically
-  await saveDoc(input, options, { content, intentType: "addDiagram" });
-  return { content };
-}
-
-/**
- * Handle updateDiagram intent
- */
-async function updateDiagram(input, options) {
-  // readCurrentContent will check userContext first, then read from file if needed
-  const currentContent = await readCurrentContent(input, options);
-  if (!currentContent) {
-    throw new Error(`Could not read current content for ${input.path}`);
-  }
-
-  const contentContext = userContextAt(options, `currentContents.${input.path}`);
-
-  let [content] = replaceD2WithPlaceholder({
-    content: currentContent,
-  });
-
-  const generateAgent = options.context?.agents?.["generateDiagram"];
-  if (!generateAgent) {
-    throw new Error("generateDiagram agent not found");
-  }
-
-  const result = await options.context.invoke(generateAgent, {
-    documentContent: content,
-    locale: input.locale,
-    diagramming: input.diagramming || {},
-    feedback: input.feedback,
-    originalContent: currentContent, // Pass original content to find existing diagrams
-    path: input.path,
-    docsDir: input.docsDir,
-  });
-
-  // generateDiagram now returns { content } with image already inserted
-  // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
-  if (result?.content) {
-    content = result.content;
-  }
-
-  contentContext.set(content);
-  // Pass intentType to saveDoc so it can handle translation sync automatically
-  await saveDoc(input, options, { content, intentType: "updateDiagram" });
-  return { content };
-}
-
-/**
- * Handle deleteDiagram intent
- */
-async function deleteDiagram(input, options) {
-  // readCurrentContent will check userContext first, then read from file if needed
-  const currentContent = await readCurrentContent(input, options);
-  if (!currentContent) {
-    throw new Error(`Could not read current content for ${input.path}`);
-  }
-
-  const contentContext = userContextAt(options, `currentContents.${input.path}`);
-
-  // Extract diagram index from feedback if provided
-  // This allows deleting a specific diagram when multiple diagrams exist
-  let diagramIndex = input.diagramIndex;
-  if (diagramIndex === undefined && input.feedback) {
-    // Import extractDiagramIndexFromFeedback from replace-d2-with-image.mjs
-    const { extractDiagramIndexFromFeedback } = await import("../create/replace-d2-with-image.mjs");
-    const extractedIndex = extractDiagramIndexFromFeedback(input.feedback);
-    if (extractedIndex !== null) {
-      diagramIndex = extractedIndex;
-      debug(`Extracted diagram index ${diagramIndex} from feedback: "${input.feedback}"`);
-    }
-  }
-
-  // Replace all diagrams (D2 code blocks, generated images, Mermaid) with placeholder
-  // If diagramIndex is provided, only replace that specific diagram
-  // This ensures LLM can identify and remove the diagram regardless of its type
-  const documentContent = replaceDiagramsWithPlaceholder({
-    content: currentContent,
-    diagramIndex,
-  });
-
-  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>
-
-<output_constraints>
-- Do not provide any explanations; include only the document content itself
-</output_constraints>`;
-
-  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,
-  });
-
-  // Delete associated diagram image files
-  if (input.docsDir) {
-    try {
-      const { deleteDiagramImages } = await import("../../utils/delete-diagram-images.mjs");
-      const { deleted } = await deleteDiagramImages(currentContent, input.path, input.docsDir);
-      if (deleted > 0) {
-        debug(`Deleted ${deleted} diagram image file(s) for ${input.path}`);
-      }
-    } catch (error) {
-      // Don't fail the operation if image deletion fails
-      console.warn(`Failed to delete diagram images: ${error.message}`);
-    }
-  }
-
-  contentContext.set(content);
-  // Pass intentType to saveDoc so it can handle translation sync automatically
-  await saveDoc(input, options, { content, intentType: "deleteDiagram" });
-
-  return { content };
-}
-
-/**
- * Handle diagram operations based on intent type
- * Supports: addDiagram, updateDiagram, deleteDiagram
- */
-export default async function handleDiagramOperations(
-  { intentType, path, docsDir, locale, feedback, diagramming, labels },
-  options,
-) {
-  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
-    throw new Error(`Invalid intent type for diagram operations: ${intentType}`);
-  }
-
-  const input = {
-    path,
-    docsDir,
-    locale,
-    feedback,
-    diagramming,
-    labels,
-  };
-
-  const fnMap = {
-    addDiagram,
-    updateDiagram,
-    deleteDiagram,
-  };
-
-  if (fnMap[intentType]) {
-    const result = await fnMap[intentType](input, options);
-    return result;
-  }
-
-  throw new Error(`Unsupported intent type: ${intentType}`);
-}
-
-handleDiagramOperations.task_render_mode = "hide";

package/agents/utils/load-all-document-content.mjs

@@ -1,30 +0,0 @@
-import pMap from "p-map";
-import { findItemByPath } from "../../utils/docs-finder-utils.mjs";
-
-/**
- * Loads all document content from the file system based on the provided document structure.
- *
- * @async
- * @function loadAllDocumentContent
- * @param {Object} params - The parameters object
- * @param {string} params.docsDir - The root directory path where documents are located
- * @param {Array<Object>} params.documentStructure - The document structure array containing items with path information
- * @param {string} params.documentStructure[].path - The file path of each document item
- * @returns {Promise<Array>} returns.allDocumentContentList - An array of document content items loaded from the file system
- * @example
- * const result = await loadAllDocumentContent({
- *   docsDir: './docs',
- *   documentStructure: [{ path: 'readme.md' }, { path: 'guide.md' }]
- * });
- */
-export default async function loadAllDocumentContent({ docsDir, documentStructure = [] }) {
-  const allDocumentContentList = await pMap(documentStructure, async (item) => {
-    const itemResult = await findItemByPath(documentStructure, item.path, null, docsDir);
-    return itemResult;
-  });
-  return {
-    allDocumentContentList,
-  };
-}
-
-loadAllDocumentContent.taskRenderMode = "hide";

package/agents/utils/load-document-all-content.mjs

@@ -1,96 +0,0 @@
-import { readdirSync } from "node:fs";
-import { join } from "node:path";
-import { findItemByPath, readFileContent } from "../../utils/docs-finder-utils.mjs";
-import { pathExists } from "../../utils/file-utils.mjs";
-
-/**
- * Loads a document's content along with all its translations from the docs directory.
- *
- * This function finds a document by its path in the documentation structure, then searches
- * for all translation files in the docs directory that match the document's naming pattern.
- * Translation files are identified by the pattern: {flatName}.{language-code}.md
- *
- * @param {Object} params - The parameters object
- * @param {string} params.path - The document path to find in the structure
- * @param {string} params.docsDir - The directory containing document files and translations
- * @param {Object} params.documentStructure - The documentation structure object to search in
- * @returns {Promise<Object>} An object containing the document data with translations
- * @throws {Error} Throws an error if the document path is not found in the structure
- */
-export default async function loadDocumentAllContent({ path, docsDir, documentStructure }) {
-  // Find the document item by path in the documentation structure
-  const result = await findItemByPath(documentStructure, path, null, docsDir);
-
-  if (!result) {
-    throw new Error(`Document with path "${path}" not found in documentStructure`);
-  }
-
-  // Convert path to flat filename format (remove leading slash, replace slashes with dashes)
-  // e.g., "/api/users" becomes "api-users"
-  const flatName = result.path.replace(/^\//, "").replace(/\//g, "-");
-
-  // Arrays to store translation data in different formats
-  const translations = [];
-  const translationsString = [];
-
-  try {
-    // Read all files in the docs directory
-    const files = readdirSync(docsDir);
-
-    // Filter files to find translation files matching the pattern:
-    // - Starts with the flat name
-    // - Ends with .md
-    // - Is not the main document file (flatName.md)
-    // - Matches language pattern: .{language-code}.md (e.g., .en.md, .zh-CN.md)
-    const translationFiles = files.filter(
-      (file) =>
-        file.startsWith(`${flatName}.`) &&
-        file.endsWith(".md") &&
-        file !== `${flatName}.md` &&
-        file.match(/\.\w+(-\w+)?\.md$/),
-    );
-
-    // Process each translation file
-    // Note: translationFiles are already filtered by readdirSync, but we check existence again for safety
-    for (const file of translationFiles) {
-      const filePath = join(docsDir, file);
-
-      // Check if file exists before reading to avoid unnecessary warnings
-      // (though readdirSync should already filter existing files)
-      const fileExists = await pathExists(filePath);
-      if (!fileExists) {
-        continue;
-      }
-
-      const content = await readFileContent(docsDir, file);
-      if (content) {
-        // Extract language code from filename (e.g., "en" from "doc.en.md" or "zh-CN" from "doc.zh-CN.md")
-        const langMatch = file.match(/\.(\w+(-\w+)?)\.md$/);
-        if (langMatch) {
-          const language = langMatch[1];
-          // Store translation in structured format
-          translations.push({
-            language,
-            translation: content,
-          });
-
-          // Store translation in XML-like string format for prompt templates
-          translationsString.push(`<${language}>\n${content}\n</${language}>`);
-        }
-      }
-    }
-  } catch (error) {
-    console.warn(`⚠️  Could not read translation files from ${docsDir}:`, error.message);
-  }
-
-  // Return the original document result enhanced with translation data
-  return {
-    ...result,
-    // FIXME: @zhanghan use anthoer way to evaluate translationQuality
-    // translates: translations, // Array of translation objects with language and content
-    translationsString: translationsString.join("\n\n"), // Combined translations as formatted string
-  };
-}
-
-// Hide this function from task rendering in the UI
-loadDocumentAllContent.taskRenderMode = "hide";