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

package/agents/utils/read-current-document-content.mjs

@@ -1,46 +0,0 @@
-import { readFileContent } from "../../utils/docs-finder-utils.mjs";
-import { getFileName } from "../../utils/utils.mjs";
-
-/**
- * Read current document content from file system
- * Used when skipping document generation (e.g., for diagram-only updates)
- * Only reads content if intentType is diagram-related, otherwise returns input unchanged
- */
-export default async function readCurrentDocumentContent(input) {
-  const { path, docsDir, locale = "en", intentType } = input;
-
-  // Only read content if intentType is diagram-related
-  // Otherwise, return input unchanged to allow document generation to proceed
-  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
-    return input;
-  }
-
-  if (!path || !docsDir) {
-    return input;
-  }
-
-  try {
-    // Read document content using the same utility as other parts of the system
-    const fileName = getFileName(path, locale);
-    const content = await readFileContent(docsDir, fileName);
-
-    if (!content) {
-      console.warn(`⚠️  Could not read content from ${fileName}`);
-      return input;
-    }
-
-    // Return content as both content, documentContent, and originalContent
-    // This matches the structure expected by downstream agents
-    return {
-      ...input,
-      content,
-      documentContent: content,
-      originalContent: content,
-    };
-  } catch (error) {
-    console.warn(`Failed to read current content for ${path}: ${error.message}`);
-    return input;
-  }
-}
-
-readCurrentDocumentContent.task_render_mode = "hide";

package/agents/utils/save-doc-translation.mjs

@@ -1,61 +0,0 @@
-import { saveDocTranslation as _saveDocTranslation } from "../../utils/utils.mjs";
-import { readFileContent } from "../../utils/docs-finder-utils.mjs";
-import { getFileName } from "../../utils/utils.mjs";
-import { debug } from "../../utils/debug.mjs";
-import { syncDiagramToTranslations } from "../../utils/sync-diagram-to-translations.mjs";
-
-export default async function saveDocTranslation({
-  path,
-  docsDir,
-  translation,
-  language,
-  labels,
-  isShowMessage = false,
-  locale,
-}) {
-  await _saveDocTranslation({
-    path,
-    docsDir,
-    language,
-    translation,
-    labels,
-  });
-
-  // Sync diagram images from main document to translations
-  // This ensures all images (including diagrams) in the main document are synced to translation files
-  if (path && docsDir && locale) {
-    try {
-      // Read main document content (it should already be saved)
-      const mainFileName = getFileName(path, locale);
-      const mainContent = await readFileContent(docsDir, mainFileName);
-
-      if (mainContent) {
-        const syncResult = await syncDiagramToTranslations(
-          mainContent,
-          path,
-          docsDir,
-          locale,
-          "sync",
-        );
-
-        if (syncResult.updated > 0) {
-          debug(
-            `✅ Synced diagram images to ${syncResult.updated} translation file(s) after translation`,
-          );
-        }
-      }
-    } catch (error) {
-      // Don't fail the translation if sync fails
-      debug(`⚠️  Failed to sync diagram images after translation: ${error.message}`);
-    }
-  }
-
-  if (isShowMessage) {
-    const message = `✅ Translation completed successfully.`;
-    return { message };
-  }
-
-  return {};
-}
-
-saveDocTranslation.task_render_mode = "hide";

package/agents/utils/save-doc.mjs

@@ -1,88 +0,0 @@
-import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
-import { saveDoc as _saveDoc } from "../../utils/utils.mjs";
-import { debug } from "../../utils/debug.mjs";
-
-export default async function saveDoc({
-  path,
-  content,
-  docsDir,
-  labels,
-  locale,
-  feedback,
-  isShowMessage = false,
-  intentType,
-  originalContent,
-  ...rest
-}) {
-  await _saveDoc({
-    path,
-    content,
-    docsDir,
-    labels,
-    locale,
-  });
-
-  // Sync diagram changes to translation documents if needed
-  // Only sync for diagram-related operations (addDiagram, updateDiagram, deleteDiagram)
-  if (
-    docsDir &&
-    path &&
-    intentType &&
-    ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)
-  ) {
-    try {
-      const { syncDiagramToTranslations } = await import(
-        "../../utils/sync-diagram-to-translations.mjs"
-      );
-
-      // Determine operation type for sync
-      // deleteDiagram -> "delete" (process even if 0 diagrams)
-      // addDiagram/updateDiagram -> "update" (skip if 0 diagrams)
-      const operationType = intentType === "deleteDiagram" ? "delete" : "update";
-
-      const syncResult = await syncDiagramToTranslations(
-        content,
-        path,
-        docsDir,
-        locale || "en",
-        operationType,
-      );
-
-      if (syncResult.updated > 0) {
-        debug(
-          `✅ Synced diagram changes to ${syncResult.updated} translation file(s) for ${intentType}`,
-        );
-      }
-    } catch (error) {
-      // Don't fail the operation if sync fails
-      debug(`⚠️  Failed to sync diagram to translations: ${error.message}`);
-    }
-  }
-
-  if (isShowMessage) {
-    // Shutdown mermaid worker pool to ensure clean exit
-    try {
-      await shutdownMermaidWorkerPool();
-    } catch (error) {
-      console.warn("Failed to shutdown mermaid worker pool:", error.message);
-    }
-
-    const message = `✅ Document updated successfully.`;
-    return { message };
-  }
-
-  return {
-    path,
-    content,
-    docsDir,
-    labels,
-    locale,
-    feedback,
-    isShowMessage,
-    intentType,
-    originalContent,
-    ...rest,
-  };
-}
-
-saveDoc.task_render_mode = "hide";

package/agents/utils/save-output.mjs

@@ -1,26 +0,0 @@
-import { promises as fs } from "node:fs";
-import { join } from "node:path";
-
-export default async function saveOutput({ savePath, fileName, saveKey, ...rest }) {
-  if (!(saveKey in rest)) {
-    console.warn(`saveKey "${saveKey}" not found in input, skip saving.`);
-    return {
-      saveOutputStatus: false,
-      saveOutputPath: null,
-    };
-  }
-
-  const value = rest[saveKey];
-  const content =
-    typeof value === "object" && value !== null ? JSON.stringify(value, null, 2) : String(value);
-  await fs.mkdir(savePath, { recursive: true });
-  const filePath = join(savePath, fileName);
-  await fs.writeFile(filePath, content, "utf8");
-
-  return {
-    saveOutputStatus: true,
-    saveOutputPath: filePath,
-  };
-}
-
-saveOutput.task_render_mode = "hide";

package/agents/utils/save-sidebar.mjs

@@ -1,51 +0,0 @@
-import { join } from "node:path";
-import fs from "fs-extra";
-import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
-
-export default async function saveSidebar({
-  documentStructure,
-  originalDocumentStructure,
-  docsDir,
-}) {
-  // Generate _sidebar.md
-  try {
-    const sidebar = generateSidebar(documentStructure || originalDocumentStructure);
-    const sidebarPath = join(docsDir, "_sidebar.md");
-
-    await fs.ensureDir(docsDir);
-    await fs.writeFile(sidebarPath, sidebar, "utf8");
-  } catch (err) {
-    console.error("Failed to save _sidebar.md:", err.message);
-  }
-  return {};
-}
-
-// Recursively generate sidebar text
-function walk(nodes, indent = "") {
-  let out = "";
-  for (const node of nodes) {
-    const realIndent = node.parentId === null ? "" : indent;
-
-    // If path already ends with .md, use it directly
-    let linkPath;
-    if (node.path.endsWith(".md")) {
-      linkPath = node.path.startsWith("/") ? node.path : `/${node.path}`;
-    } else {
-      // Otherwise, convert to flattened file name
-      const relPath = node.path.replace(/^\//, "");
-      linkPath = `/${relPath.split("/").join("-")}.md`;
-    }
-
-    out += `${realIndent}* [${node.title}](${linkPath})\n`;
-
-    if (node.children && node.children.length > 0) {
-      out += walk(node.children, `${indent}  `);
-    }
-  }
-  return out;
-}
-
-function generateSidebar(documentStructure) {
-  const { rootNodes } = buildDocumentTree(documentStructure);
-  return walk(rootNodes).replace(/\n+$/, "");
-}

package/agents/utils/skip-if-content-exists.mjs

@@ -1,27 +0,0 @@
-/**
- * Determine whether to skip document generation when the document already exists.
- * If intentType is diagram-related *and* content is already present, mark that
- * generation should be skipped so downstream agents can short-circuit.
- */
-export default async function skipIfContentExists(input) {
-  const { intentType, content } = input;
-
-  const isDiagramIntent =
-    intentType && ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType);
-  const shouldSkipGeneration = Boolean(isDiagramIntent && content);
-
-  return {
-    ...input,
-    skipGenerateDocument: shouldSkipGeneration,
-    // Ensure downstream steps have content available when skipping
-    ...(shouldSkipGeneration
-      ? {
-          content,
-          documentContent: content,
-          originalContent: content,
-        }
-      : {}),
-  };
-}
-
-skipIfContentExists.task_render_mode = "hide";

package/agents/utils/streamline-document-titles-if-needed.mjs

@@ -1,88 +0,0 @@
-/**
- * Check if a string contains character-based language characters (Chinese, Japanese, Korean, etc.)
- * @param {string} str - String to check
- * @returns {boolean} - True if string contains character-based language characters
- */
-function isCharacterBasedLanguage(str) {
-  if (!str) return false;
-  // Check for Chinese, Japanese, Korean, and other character-based languages
-  // Chinese: \u4e00-\u9fff (CJK Unified Ideographs)
-  // Japanese: \u3040-\u309f (Hiragana), \u30a0-\u30ff (Katakana)
-  // Korean: \uac00-\ud7a3 (Hangul Syllables)
-  // Thai: \u0e00-\u0e7f
-  // Arabic: \u0600-\u06ff
-  const characterBasedPattern =
-    /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7a3\u0e00-\u0e7f\u0600-\u06ff]/;
-  return characterBasedPattern.test(str);
-}
-
-/**
- * Get character limit based on language type
- * @param {string} title - Title to check
- * @returns {number} - Character limit (24 for English, 12 for character-based languages)
- */
-function getCharacterLimit(title) {
-  return isCharacterBasedLanguage(title) ? 12 : 24;
-}
-
-/**
- * Streamline document titles if they exceed length limits
- * Reusable function for streamlining document titles in various contexts
- * @param {Object} params
- * @param {Array<{title: string, path: string}>} params.documentStructure - Document structure array
- * @param {Object} options - Agent options with context
- * @returns {Promise<void>} - Modifies documentStructure in place
- */
-export default async function streamlineDocumentTitlesIfNeeded({ documentStructure }, options) {
-  if (!documentStructure || !Array.isArray(documentStructure)) {
-    return;
-  }
-
-  // Filter items that need streamlining based on character count and language type
-  // English: > 24 characters, Character-based languages (Chinese, Japanese, etc.): > 12 characters
-  const itemsNeedingStreamline = documentStructure.filter((item) => {
-    if (!item.title) return false;
-    const limit = getCharacterLimit(item.title);
-    return item.title.length > limit;
-  });
-
-  if (itemsNeedingStreamline.length === 0) {
-    return;
-  }
-
-  const documentList = itemsNeedingStreamline.map((item) => ({
-    path: item.path,
-    title: item.title,
-  }));
-
-  const streamlineAgent = options?.context?.agents?.["documentTitleStreamline"];
-  if (!streamlineAgent) {
-    console.warn("⚠️  documentTitleStreamline agent not found. Skipping title streamlining.");
-    return;
-  }
-
-  try {
-    const streamlineResult = await options.context.invoke(streamlineAgent, {
-      documentList,
-    });
-
-    // Update the document items with streamlined titles using path as the key
-    if (streamlineResult.documentList && Array.isArray(streamlineResult.documentList)) {
-      const streamlineMap = new Map(streamlineResult.documentList.map((item) => [item.path, item]));
-
-      for (const item of documentStructure) {
-        const streamlined = streamlineMap.get(item.path);
-        if (streamlined) {
-          item.title = streamlined.title;
-        }
-      }
-    }
-  } catch (error) {
-    console.warn("⚠️  Failed to streamline document titles:", error.message);
-    console.warn("Continuing with original titles.");
-  }
-}
-
-streamlineDocumentTitlesIfNeeded.taskTitle = "Streamline document titles if needed";
-streamlineDocumentTitlesIfNeeded.description =
-  "Shorten document titles that exceed length limits to make sidebar navigation less crowded";

package/agents/utils/transform-detail-data-sources.mjs

@@ -1,45 +0,0 @@
-import fs from "node:fs";
-import { isRemoteFile } from "../../utils/file-utils.mjs";
-import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
-
-export default function transformDetailDataSource({ sourceIds }, options = {}) {
-  // Read file content for each sourceId, ignoring failures
-  let openAPISpec;
-  const remoteFileList = options?.context?.userContext?.remoteFileList || [];
-  const contents = (sourceIds || [])
-    .filter((id) => {
-      const openApiSourceId = options?.context?.userContext?.openAPISpec?.sourceId;
-      if (openApiSourceId !== undefined && openApiSourceId === id) {
-        openAPISpec = options.context.userContext.openAPISpec;
-        return false;
-      }
-      return true;
-    })
-    .map((id) => {
-      try {
-        if (isRemoteFile(id)) {
-          const findFile = remoteFileList.find((f) => f.sourceId === id);
-          if (findFile) {
-            return `// sourceId: ${id}\n${findFile.content}\n`;
-          }
-          return null;
-        }
-
-        const normalizedId = normalizePath(id);
-        const content = fs.readFileSync(normalizedId, "utf8");
-        const relativeId = toRelativePath(id);
-        return `// sourceId: ${relativeId}\n${content}\n`;
-      } catch {
-        // Ignore files that cannot be read
-        return null;
-      }
-    })
-    .filter(Boolean);
-
-  return {
-    detailDataSource: contents.join(""),
-    openAPISpec,
-  };
-}
-
-transformDetailDataSource.task_render_mode = "hide";

package/agents/utils/update-branding.mjs

@@ -1,84 +0,0 @@
-import { stat } from "node:fs/promises";
-import chalk from "chalk";
-import { joinURL } from "ufo";
-
-import { getComponentInfoWithMountPoint } from "../../utils/blocklet.mjs";
-import {
-  CLOUD_SERVICE_URL_PROD,
-  CLOUD_SERVICE_URL_STAGING,
-  DISCUSS_KIT_DID,
-} from "../../utils/constants/index.mjs";
-import { requestWithAuthToken } from "../../utils/request.mjs";
-import { uploadFiles } from "../../utils/upload-files.mjs";
-
-export default async function updateBranding({ appUrl, projectInfo, accessToken, finalPath }) {
-  try {
-    const origin = new URL(appUrl).origin;
-    if ([CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(origin)) {
-      console.log("ℹ️ Skipped updating branding for official service\n");
-      return;
-    }
-
-    console.log(`🔄 Updating branding for ${chalk.cyan(origin)}`);
-
-    // Get component information and mount point
-    const componentInfo = await getComponentInfoWithMountPoint(origin, DISCUSS_KIT_DID);
-    const mountPoint = componentInfo.mountPoint || "/";
-
-    if (projectInfo.name.length > 40) {
-      console.warn(
-        `⚠️ Name is too long, it should be less than 40 characters\nWill be truncated to 40 characters`,
-      );
-    }
-
-    if (projectInfo.description.length > 160) {
-      console.warn(
-        `⚠️ Description is too long, it should be less than 160 characters\nWill be truncated to 160 characters`,
-      );
-    }
-
-    const res = await requestWithAuthToken(
-      joinURL(origin, mountPoint, "/api/branding"),
-      {
-        method: "PUT",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          appName: projectInfo.name.slice(0, 40),
-          appDescription: projectInfo.description.slice(0, 160),
-        }),
-      },
-      accessToken,
-    );
-
-    if (res.success) {
-      if (!finalPath) {
-        console.warn("\n🔄 Skipped updating branding for missing logo file\n");
-        return;
-      }
-
-      try {
-        const projectLogoStat = await stat(finalPath);
-
-        if (projectLogoStat.isFile()) {
-          // Upload to blocklet logo endpoint
-          await uploadFiles({
-            appUrl: origin,
-            filePaths: [finalPath],
-            accessToken,
-            concurrency: 1,
-            endpoint: `${origin}/.well-known/service/blocklet/logo/upload/square/${componentInfo.did}`,
-          });
-        }
-        console.log("✅ Branding has been successfully updated\n");
-      } catch (error) {
-        console.warn(`⚠️ Just failed to update logo: ${error.message}\n`);
-      }
-    } else {
-      console.warn(`⚠️ Failed to update branding: ${res.error}\n`);
-    }
-  } catch (error) {
-    console.warn(`⚠️ Failed to update branding: ${error.message}\n`);
-  }
-}