@aigne/doc-smith 0.8.14 → 0.8.15-beta.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.8.15-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta...v0.8.15-beta.1) (2025-10-23)
+
+
+### Features
+
+* support openapi datasource, generate better api docs ([#212](https://github.com/AIGNE-io/aigne-doc-smith/issues/212)) ([6a683f1](https://github.com/AIGNE-io/aigne-doc-smith/commit/6a683f117aa94f265383be6e1b3b957803004032))
+
+## [0.8.15-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14...v0.8.15-beta) (2025-10-21)
+
+
+### Features
+
+* update document publish prompt for better user experience ([#208](https://github.com/AIGNE-io/aigne-doc-smith/issues/208)) ([0726c23](https://github.com/AIGNE-io/aigne-doc-smith/commit/0726c23ed2d47b2126c0896d71922860b7436895))
+
+
+### Bug Fixes
+
+* enforce stricter rules for x-field component and markdown ([#210](https://github.com/AIGNE-io/aigne-doc-smith/issues/210)) ([d69ee53](https://github.com/AIGNE-io/aigne-doc-smith/commit/d69ee53dbd113859a822d3391cc6cbf2f02bb75e))
+
 ## [0.8.14](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.2...v0.8.14) (2025-10-19)
 
 ## [0.8.14-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.1...v0.8.14-beta.2) (2025-10-19)

package/agents/update/check-document.mjs

@@ -2,6 +2,7 @@ import { access, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TeamAgent } from "@aigne/core";
+
 import checkDetailResult from "../utils/check-detail-result.mjs";
 
 // Get current script directory
@@ -102,6 +103,19 @@ export default async function checkDocument(
       options.context.agents["saveSingleDoc"],
     ],
   });
+  let openAPISpec = null;
+
+  if (options.context?.userContext?.openAPISpec?.sourceId) {
+    const matchingDocument = originalDocumentStructure.find((item) => {
+      if (item.path === path) {
+        return item.sourceIds.find((x) => x === options.context.userContext.openAPISpec.sourceId);
+      }
+      return false;
+    });
+    if (matchingDocument) {
+      openAPISpec = options.context.userContext.openAPISpec;
+    }
+  }
 
   const result = await options.context.invoke(teamAgent, {
     ...rest,
@@ -112,6 +126,7 @@ export default async function checkDocument(
     originalDocumentStructure,
     documentStructure,
     detailFeedback: contentValidationFailed ? validationResult.detailFeedback : "",
+    openAPISpec,
   });
 
   return {

package/agents/update/index.yaml

@@ -36,7 +36,7 @@ skills:
   - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs
     default_input:
-      action: "✅ Documents updated successfully"
+      action: "✅ Documents updated successfully!\n💡 Looks good? Run `aigne doc publish` to go live."
 input_schema:
   type: object
   properties:

package/agents/utils/choose-docs.mjs

@@ -50,7 +50,12 @@ export default async function chooseDocs(
         });
 
         // Use title if available, otherwise fall back to filename
-        const displayName = docItem?.title || file;
+        let displayName = docItem?.title;
+        if (displayName) {
+          displayName = `${displayName} (${file})`;
+        } else {
+          displayName = file;
+        }
 
         return {
           name: displayName,

package/agents/utils/load-sources.mjs

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { statSync } from "node:fs";
 import path from "node:path";
 import imageSize from "image-size";
 import {
@@ -7,6 +8,7 @@ import {
   loadFilesFromPaths,
   readFileContents,
   getMimeType,
+  checkIsRemoteFile,
 } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,
@@ -18,28 +20,63 @@ import {
   DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_INCLUDE_PATTERNS,
 } from "../../utils/constants/index.mjs";
-
-export default async function loadSources({
-  sources = [],
-  sourcesPath = [],
-  includePatterns,
-  excludePatterns,
-  outputDir,
-  docsDir,
-  "doc-path": docPath,
-  boardId,
-  useDefaultPatterns = true,
-  lastGitHead,
-  reset = false,
-  media,
-} = {}) {
+import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
+
+export default async function loadSources(
+  {
+    sources = [],
+    sourcesPath = [],
+    includePatterns,
+    excludePatterns,
+    outputDir,
+    docsDir,
+    "doc-path": docPath,
+    boardId,
+    useDefaultPatterns = true,
+    lastGitHead,
+    reset = false,
+    media,
+  } = {},
+  options,
+) {
   let files = Array.isArray(sources) ? [...sources] : [];
   const { minImageWidth } = media || { minImageWidth: 800 };
 
   if (sourcesPath) {
-    const allFiles = await loadFilesFromPaths(sourcesPath, {
+    const sourcesPathList = Array.isArray(sourcesPath) ? sourcesPath : [sourcesPath];
+    const pickSourcesPath = [];
+    const omitSourcesPath = [];
+    sourcesPathList.forEach((x) => {
+      if (typeof x !== "string" || !x) {
+        return;
+      }
+      if (x.startsWith("!")) {
+        omitSourcesPath.push(x.substring(1));
+      } else {
+        pickSourcesPath.push(x);
+      }
+    });
+
+    const customExcludePatterns = omitSourcesPath
+      .map((x) => {
+        try {
+          const stats = statSync(x);
+          if (stats.isFile()) {
+            return x;
+          }
+          if (stats.isDirectory()) {
+            return `${x}/**`;
+          }
+          return null;
+        } catch (error) {
+          console.warn(`Failed to stat path ${x}: ${error.message}`);
+          return null;
+        }
+      })
+      .filter(Boolean);
+    const allFiles = await loadFilesFromPaths(pickSourcesPath, {
       includePatterns,
-      excludePatterns,
+      excludePatterns: [...new Set([...(excludePatterns || []), ...customExcludePatterns])],
       useDefaultPatterns,
       defaultIncludePatterns: DEFAULT_INCLUDE_PATTERNS,
       defaultExcludePatterns: DEFAULT_EXCLUDE_PATTERNS,
@@ -50,9 +87,6 @@ export default async function loadSources({
 
   files = [...new Set(files)];
 
-  // all files path
-  const allFilesPaths = files.map((file) => `- ${toRelativePath(file)}`).join("\n");
-
   // Define media file extensions
   const mediaExtensions = [
     ".jpg",
@@ -110,7 +144,7 @@ export default async function loadSources({
     files.map(async (file) => {
       const ext = path.extname(file).toLowerCase();
 
-      if (mediaExtensions.includes(ext)) {
+      if (mediaExtensions.includes(ext) && !checkIsRemoteFile(file)) {
         // This is a media file
         const relativePath = path.relative(docsDir, file);
         const fileName = path.basename(file);
@@ -161,7 +195,7 @@ export default async function loadSources({
   }
 
   // Read all source files using the utility function
-  const sourceFiles = await readFileContents(sourceFilesPaths, process.cwd());
+  let sourceFiles = await readFileContents(sourceFilesPaths, process.cwd());
 
   // Count tokens and lines using utility function
   const { totalTokens, totalLines } = calculateFileStats(sourceFiles);
@@ -169,8 +203,32 @@ export default async function loadSources({
   // check if totalTokens is too large
   const isLargeContext = totalTokens > INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD;
 
+  // filter OpenAPI doc should after check isLargeContext
+  sourceFiles = sourceFiles.filter((file) => {
+    if (options?.context?.userContext.openAPISpec) return true;
+
+    const isOpenAPI = isOpenAPISpecFile(file.content);
+    if (isOpenAPI && options?.context?.userContext) {
+      options.context.userContext.openAPISpec = file;
+    }
+    return !isOpenAPI;
+  });
+
+  const httpFileList = [];
+
+  sourceFiles.forEach((file) => {
+    if (checkIsRemoteFile(file.sourceId)) {
+      httpFileList.push(file);
+    }
+  });
+  if (options?.context?.userContext) {
+    options.context.userContext.httpFileList = httpFileList;
+  }
+
   // Build allSources string using utility function
   const allSources = buildSourcesContent(sourceFiles, isLargeContext);
+  // all files path
+  const allFilesPaths = sourceFiles.map((x) => `- ${toRelativePath(x.sourceId)}`).join("\n");
 
   // Get the last documentation structure
   let originalDocumentStructure;

package/agents/utils/transform-detail-datasources.mjs

@@ -1,11 +1,30 @@
 import fs from "node:fs";
 import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
+import { checkIsRemoteFile } from "../../utils/file-utils.mjs";
 
-export default function transformDetailDatasources({ sourceIds }) {
+export default function transformDetailDatasources({ sourceIds }, options = {}) {
   // Read file content for each sourceId, ignoring failures
+  let openAPISpec;
+  const httpFileList = options?.context?.userContext?.httpFileList || [];
   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 (checkIsRemoteFile(id)) {
+          const findFile = httpFileList.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);
@@ -17,7 +36,10 @@ export default function transformDetailDatasources({ sourceIds }) {
     })
     .filter(Boolean);
 
-  return { detailDataSources: contents.join("") };
+  return {
+    detailDataSources: contents.join(""),
+    openAPISpec,
+  };
 }
 
 transformDetailDatasources.task_render_mode = "hide";

package/package.json

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