@aigne/doc-smith 0.9.8-alpha.2 → 0.9.8-alpha.4

package/agents/utils/ensure-document-icons.mjs

@@ -1,129 +0,0 @@
-import { promises as fs } from "node:fs";
-import { join } from "node:path";
-import { loadConfigFromFile, processConfigFields } from "../../utils/utils.mjs";
-
-/**
- * Ensure all root-level document entries have icons
- * Batch processing: Collects all entries without icons and generates them in a single call
- * Conditionally saves the updated structure if icons were generated
- * This is a reusable agent that can be used in structure planning and before publishing
- */
-export default async function ensureDocumentIcons(inputOrParams, options) {
-  // Handle multiple calling patterns:
-  // 1. As function skill: (input, options) where input.documentStructure exists
-  // 2. As function skill: (input, options) where input.originalDocumentStructure exists
-  // 3. As standalone function: ({ documentStructure }, options)
-  const documentStructure =
-    inputOrParams?.documentStructure ||
-    inputOrParams?.originalDocumentStructure ||
-    (Array.isArray(inputOrParams) ? inputOrParams : null);
-
-  if (!documentStructure || !Array.isArray(documentStructure)) {
-    // Return input unchanged if no documentStructure to process
-    return inputOrParams || {};
-  }
-
-  // Batch collect all root-level items that need icon generation
-  // Only process root-level items (parentId is null, undefined, or empty string)
-  // Only generate icons for items that don't have one
-  const itemsNeedingIcon = documentStructure.filter((item) => {
-    // Only process root-level items
-    const isRootLevel = !item.parentId || item.parentId === "null" || item.parentId === "";
-    if (!isRootLevel) return false;
-
-    // Must have title and description for icon generation
-    if (!item.title || !item.description) return false;
-
-    // Only generate if icon is missing
-    const hasNoIcon = !item.icon || !item.icon.trim();
-    return hasNoIcon;
-  });
-
-  // If all items already have icons, skip
-  if (itemsNeedingIcon.length === 0) {
-    return inputOrParams || {};
-  }
-
-  // Prepare batch list for icon generation
-  const documentList = itemsNeedingIcon.map((item) => ({
-    path: item.path,
-    title: item.title,
-    description: item.description,
-  }));
-
-  const iconAgent = options?.context?.agents?.["documentIconGenerate"];
-  if (!iconAgent) {
-    console.warn("⚠️  documentIconGenerate agent not found. Skipping icon generation.");
-    return inputOrParams || {};
-  }
-
-  let iconsGenerated = false;
-
-  try {
-    // Batch generate all missing icons in a single call
-    const iconResult = await options.context.invoke(iconAgent, {
-      documentList,
-    });
-
-    // Batch update all document items with generated icons using path as the key
-    if (iconResult.documentList && Array.isArray(iconResult.documentList)) {
-      const iconMap = new Map(iconResult.documentList.map((item) => [item.path, item.icon]));
-
-      for (const item of documentStructure) {
-        const generatedIcon = iconMap.get(item.path);
-        if (generatedIcon) {
-          item.icon = generatedIcon;
-          iconsGenerated = true;
-        }
-      }
-    }
-
-    // Conditionally save the updated structure if icons were generated
-    // Use the same save pattern as save-output.mjs for consistency
-    if (iconsGenerated) {
-      // Try to get outputDir from multiple sources (same as create flow)
-      let outputDir =
-        inputOrParams?.outputDir ||
-        options?.context?.userContext?.outputDir ||
-        options?.context?.config?.outputDir;
-
-      // If still not found, load from config file and process defaults
-      if (!outputDir) {
-        try {
-          const config = await loadConfigFromFile();
-          const processedConfig = await processConfigFields(config || {});
-          outputDir = processedConfig?.outputDir;
-        } catch {
-          // Ignore config load errors
-        }
-      }
-
-      if (outputDir) {
-        try {
-          // Use the same save pattern as save-output.mjs
-          const savePath = outputDir;
-          const fileName = "structure-plan.json";
-          const content = JSON.stringify(documentStructure, null, 2);
-
-          await fs.mkdir(savePath, { recursive: true });
-          const filePath = join(savePath, fileName);
-          await fs.writeFile(filePath, content, "utf8");
-        } catch (saveError) {
-          console.warn("⚠️  Failed to save updated structure:", saveError.message);
-          // Continue even if save fails
-        }
-      }
-    }
-  } catch (error) {
-    console.warn("⚠️  Failed to generate document icons:", error.message);
-    console.warn("Continuing without icons.");
-  }
-
-  // Return input unchanged (documentStructure is modified in place)
-  return inputOrParams || {};
-}
-
-ensureDocumentIcons.taskTitle = "Ensure document icons";
-ensureDocumentIcons.description =
-  "Check each root-level document entry for icons - if missing, generate one; if present, skip";
-ensureDocumentIcons.task_render_mode = "hide";

package/agents/utils/exit.mjs

@@ -1,6 +0,0 @@
-export default async function exit() {
-  process.exit(0);
-}
-
-exit.description =
-  "Exit the chat session. Equivalent to saying goodbye, quit, exit, close, or see you. Must print a bye message before calling this tool, as it will exit the process immediately.";

package/agents/utils/feedback-refiner.yaml

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

package/agents/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";