@aigne/doc-smith 0.9.3-beta.1 → 0.9.3-beta.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.3-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.3-beta.1...v0.9.3-beta.2) (2025-11-13)
+
+
+### Features
+
+* allow manual triggering of the publish docs process ([#306](https://github.com/AIGNE-io/aigne-doc-smith/issues/306)) ([9a76a49](https://github.com/AIGNE-io/aigne-doc-smith/commit/9a76a491c1511397b32b60db62142896637dfed2))
+* move ensure document icons to sub-agent ([#305](https://github.com/AIGNE-io/aigne-doc-smith/issues/305)) ([f139070](https://github.com/AIGNE-io/aigne-doc-smith/commit/f1390706cda9348de094c9f5e592a4c34a1b1389))
+
 ## [0.9.3-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.3-beta...v0.9.3-beta.1) (2025-11-13)
 
 

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

@@ -4,7 +4,6 @@ import {
   validateAddDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
 import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
-import generateDocumentIconIfNeeded from "../../utils/generate-document-icon-if-needed.mjs";
 
 export default async function addDocument(input, options) {
   // Validate input using Zod schema
@@ -61,12 +60,9 @@ export default async function addDocument(input, options) {
   // Streamline document titles if needed (will streamline the new document if title > 18 characters)
   await streamlineDocumentTitlesIfNeeded({ documentStructure: [newDocument] }, options);
 
-  // Add the document to the structure first
+  // Add the document to the structure
   const updatedStructure = [...documentStructure, newDocument];
 
-  // Generate icon for root-level documents if needed
-  await generateDocumentIconIfNeeded({ documentStructure: updatedStructure }, options);
-
   const successMessage = `addDocument executed successfully.
   Successfully added document '${title}' with path '${path}'.
   Check if the latest version of documentStructure meets user feedback, if so, just return 'success'.`;

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

@@ -4,7 +4,6 @@ import {
   validateUpdateDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
 import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
-import generateDocumentIconIfNeeded from "../../utils/generate-document-icon-if-needed.mjs";
 
 export default async function updateDocument(input, options) {
   // Validate input using Zod schema
@@ -56,16 +55,6 @@ export default async function updateDocument(input, options) {
   const updatedStructure = [...documentStructure];
   updatedStructure[documentIndex] = updatedDocument;
 
-  // Generate/update icon for root-level documents if needed
-  // Pass original document for comparison to detect title/description changes
-  await generateDocumentIconIfNeeded(
-    {
-      documentStructure: updatedStructure,
-      originalItems: [originalDocument],
-    },
-    options,
-  );
-
   const updates = [];
   if (title !== undefined) updates.push(`title to '${title}'`);
   if (description !== undefined) updates.push("description");

package/agents/create/index.yaml

@@ -24,6 +24,7 @@ skills:
         $get: outputDir
       fileName: structure-plan.json
   - ../utils/save-sidebar.mjs
+  - ../utils/ensure-document-icons.mjs
   - type: transform
     name: transformData
     task_render_mode: hide

package/agents/publish/index.yaml

@@ -11,6 +11,7 @@ skills:
       checkOnly: true
   - url: ../init/check.mjs
   - url: ../utils/load-sources.mjs
+  - ../utils/ensure-document-icons.mjs
   - translate-meta.mjs
   - publish-docs.mjs
 input_schema:

package/agents/update/index.yaml

@@ -31,6 +31,7 @@ skills:
     default_input:
       requiredFeedback: false
   - ../utils/format-document-structure.mjs
+  - ../utils/ensure-document-icons.mjs
   - ../media/load-media-description.mjs
   - ../update/check-update-is-single.mjs
   - ../update/save-and-translate-document.mjs

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

@@ -0,0 +1,129 @@
+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/aigne.yaml

@@ -83,7 +83,6 @@ agents:
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
   - ./agents/utils/document-icon-generate.yaml
-  - ./agents/utils/generate-document-icon-if-needed.mjs
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.3-beta.1",
+  "version": "0.9.3-beta.2",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/common/document-structure/document-structure-rules.md

@@ -28,12 +28,6 @@ Structural planning rules:
 
 2. Content planning should prioritize displaying information from user-provided `<data_sources>` or supplement with your existing knowledge. Do not arbitrarily fabricate information.
 
-3. **Document Icon Generation:**
-   - For root-level nodes (where `parentPath` is null or empty), add an `icon` attribute
-   - Format: `lucide:icon-name` (only Lucide icons supported)
-   - Choose icons that semantically match the document's purpose based on title and description
-   - Common icons: `lucide:book` (documentation), `lucide:rocket` (quick start), `lucide:code` (API), `lucide:settings` (configuration), `lucide:graduation-cap` (tutorials), `lucide:folder-open` (overview), `lucide:users` (user guides), `lucide:shield` (security), `lucide:cloud` (deployment)
-
 {% ifAsync docsType == 'general' %}
 {% include "../../structure/document-rules.md" %}
 {% endif %}

package/agents/utils/generate-document-icon-if-needed.mjs

@@ -1,93 +0,0 @@
-/**
- * Generate icons for root-level document structure items if they don't have one or if title/description changed
- * Reusable function for generating document icons in various contexts
- * Can be called as a standalone function with { documentStructure, originalItems? } or as a function skill with (input, options)
- * @param {Object|Array} inputOrParams - Either input from previous step (with documentStructure) or params object with documentStructure and optional originalItems
- * @param {Object} options - Agent options with context
- * @param {Array<{path: string, title?: string, description?: string}>} [inputOrParams.originalItems] - Original items for comparison (optional, used to detect title/description changes)
- * @returns {Promise<Object>} - Returns input unchanged (modifies documentStructure in place)
- */
-export default async function generateDocumentIconIfNeeded(inputOrParams, options) {
-  // Handle both calling patterns:
-  // 1. As function skill: (input, options) where input.documentStructure exists
-  // 2. As standalone function: ({ documentStructure, originalItems? }, options)
-  const documentStructure =
-    inputOrParams?.documentStructure || (Array.isArray(inputOrParams) ? inputOrParams : null);
-  const originalItems = inputOrParams?.originalItems || [];
-
-  if (!documentStructure || !Array.isArray(documentStructure)) {
-    // Return input unchanged if no documentStructure to process
-    return inputOrParams || {};
-  }
-
-  // Create a map of original items by path for quick lookup
-  const originalItemsMap = new Map(
-    originalItems.map((item) => [item.path, { title: item.title, description: item.description }]),
-  );
-
-  // Filter root-level items that need icon generation or update
-  const itemsNeedingIcon = documentStructure.filter((item) => {
-    // Only process root-level items (parentId is null, undefined, or empty string)
-    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;
-
-    // Check if icon is missing
-    const hasNoIcon = !item.icon;
-
-    // Check if title or description changed (if original item exists)
-    const originalItem = originalItemsMap.get(item.path);
-    const titleChanged = originalItem && originalItem.title !== item.title;
-    const descriptionChanged = originalItem && originalItem.description !== item.description;
-    const contentChanged = titleChanged || descriptionChanged;
-
-    // Generate/update icon if: missing icon OR content changed
-    return hasNoIcon || contentChanged;
-  });
-
-  if (itemsNeedingIcon.length === 0) {
-    return;
-  }
-
-  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;
-  }
-
-  try {
-    const iconResult = await options.context.invoke(iconAgent, {
-      documentList,
-    });
-
-    // Update the 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]));
-
-      for (const item of documentStructure) {
-        const iconData = iconMap.get(item.path);
-        if (iconData?.icon) {
-          item.icon = iconData.icon;
-        }
-      }
-    }
-  } 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 || {};
-}
-
-generateDocumentIconIfNeeded.taskTitle = "Generate document icons if needed";
-generateDocumentIconIfNeeded.description =
-  "Generate appropriate Lucide icons for root-level document structure items based on their title and description, or update icon if title/description changed";