@aigne/doc-smith 0.1.4 → 0.2.1

package/agents/publish-docs.mjs

@@ -9,14 +9,53 @@ import { homedir } from "node:os";
 import { parse, stringify } from "yaml";
 import { execSync } from "node:child_process";
 import { basename } from "node:path";
+import { loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
+const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 
 /**
- * Get project name from git repository or current directory
- * @returns {string} - The project name
+ * Get GitHub repository information
+ * @param {string} repoUrl - The repository URL
+ * @returns {Promise<Object>} - Repository information
  */
-function getProjectName() {
+async function getGitHubRepoInfo(repoUrl) {
+  try {
+    // Extract owner and repo from GitHub URL
+    const match = repoUrl.match(
+      /github\.com[\/:]([^\/]+)\/([^\/]+?)(?:\.git)?$/
+    );
+    if (!match) return null;
+
+    const [, owner, repo] = match;
+    const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+
+    const response = await fetch(apiUrl);
+    if (!response.ok) return null;
+
+    const data = await response.json();
+    return {
+      name: data.name,
+      description: data.description || "",
+      icon: data.owner?.avatar_url || "",
+    };
+  } catch (error) {
+    console.warn("Failed to fetch GitHub repository info:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Get project information with user confirmation
+ * @param {Object} options - Options object containing prompts
+ * @returns {Promise<Object>} - Project information including name, description, and icon
+ */
+async function getProjectInfo(options) {
+  let repoInfo = null;
+  let defaultName = basename(process.cwd());
+  let defaultDescription = "";
+  let defaultIcon = "";
+
   // Check if we're in a git repository
   try {
     const gitRemote = execSync("git remote get-url origin", {
@@ -26,11 +65,59 @@ function getProjectName() {
 
     // Extract repository name from git remote URL
     const repoName = gitRemote.split("/").pop().replace(".git", "");
-    return repoName;
+    defaultName = repoName;
+
+    // If it's a GitHub repository, try to get additional info
+    if (gitRemote.includes("github.com")) {
+      repoInfo = await getGitHubRepoInfo(gitRemote);
+      if (repoInfo) {
+        defaultDescription = repoInfo.description;
+        defaultIcon = repoInfo.icon;
+      }
+    }
   } catch (error) {
     // Not in git repository or no origin remote, use current directory name
-    return basename(process.cwd());
+    console.warn("No git repository found, using current directory name");
   }
+
+  // Prompt user for project information
+  console.log("\n📋 Project Information for Documentation Platform");
+
+  const projectName = await options.prompts.input({
+    message: "Project name:",
+    default: defaultName,
+    validate: (input) => {
+      if (!input || input.trim() === "") {
+        return "Project name cannot be empty";
+      }
+      return true;
+    },
+  });
+
+  const projectDescription = await options.prompts.input({
+    message: "Project description (optional):",
+    default: defaultDescription,
+  });
+
+  const projectIcon = await options.prompts.input({
+    message: "Project icon URL (optional):",
+    default: defaultIcon,
+    validate: (input) => {
+      if (!input || input.trim() === "") return true;
+      try {
+        new URL(input);
+        return true;
+      } catch {
+        return "Please enter a valid URL";
+      }
+    },
+  });
+
+  return {
+    name: projectName.trim(),
+    description: projectDescription.trim(),
+    icon: projectIcon.trim(),
+  };
 }
 
 /**
@@ -77,8 +164,9 @@ async function getAccessToken(appUrl) {
       const result = await createConnect({
         connectUrl: connectUrl,
         connectAction: "gen-simple-access-key",
-        source: `@aigne/cli doc-smith connect to Discuss Kit`,
+        source: `AIGNE DocSmith connect to Discuss Kit`,
         closeOnSuccess: true,
+        appName: "AIGNE DocSmith",
         openPage: (pageUrl) => open(pageUrl),
       });
 
@@ -116,77 +204,102 @@ async function getAccessToken(appUrl) {
   return accessToken;
 }
 
-/**
- * Save boardId to config.yaml file if it was auto-created
- * @param {string} boardId - The original boardId (may be empty)
- * @param {string} newBoardId - The boardId returned from publishDocsFn
- */
-async function saveBoardIdToInput(boardId, newBoardId) {
-  // Only save if boardId was auto-created
-  if (!boardId && newBoardId) {
-    try {
-      const docSmithDir = join(process.cwd(), "doc-smith");
-      if (!existsSync(docSmithDir)) {
-        mkdirSync(docSmithDir, { recursive: true });
-      }
+export default async function publishDocs(
+  { docsDir, appUrl, boardId, boardName, boardDesc, boardCover },
+  options
+) {
+  // Check if DOC_DISCUSS_KIT_URL is set in environment variables
+  const envAppUrl = process.env.DOC_DISCUSS_KIT_URL;
+  const useEnvAppUrl = !!envAppUrl;
 
-      const inputFilePath = join(docSmithDir, "config.yaml");
-      let fileContent = "";
+  // Use environment variable if available, otherwise use the provided appUrl
+  if (useEnvAppUrl) {
+    appUrl = envAppUrl;
+  }
 
-      // Read existing file content if it exists
-      if (existsSync(inputFilePath)) {
-        fileContent = await readFile(inputFilePath, "utf8");
-      }
+  // Check if appUrl is default and not saved in config (only when not using env variable)
+  const config = await loadConfigFromFile();
+  const isDefaultAppUrl = appUrl === DEFAULT_APP_URL;
+  const hasAppUrlInConfig = config && config.appUrl;
 
-      // Check if boardId already exists in the file
-      const boardIdRegex = /^boardId:\s*.*$/m;
-      const newBoardIdLine = `boardId: ${newBoardId}`;
-
-      if (boardIdRegex.test(fileContent)) {
-        // Replace existing boardId line
-        fileContent = fileContent.replace(boardIdRegex, newBoardIdLine);
-      } else {
-        // Add boardId to the end of file
-        if (fileContent && !fileContent.endsWith("\n")) {
-          fileContent += "\n";
-        }
-        fileContent += newBoardIdLine + "\n";
-      }
+  if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
+    const choice = await options.prompts.select({
+      message: "Select platform to publish your documents:",
+      choices: [
+        {
+          name: "Publish to docsmith.aigne.io - free, but your documents will be public accessible, recommended for open-source projects",
+          value: "default",
+        },
+        {
+          name: "Publish to your own website - you will need to run Discuss Kit by your self ",
+          value: "custom",
+        },
+      ],
+    });
 
-      await writeFile(inputFilePath, fileContent);
-    } catch (error) {
-      console.warn("Failed to save board ID to config.yaml:", error.message);
+    if (choice === "custom") {
+      appUrl = await options.prompts.input({
+        message: "Please enter your Discuss Kit platform URL:",
+        validate: (input) => {
+          try {
+            new URL(input);
+            return true;
+          } catch {
+            return "Please enter a valid URL";
+          }
+        },
+      });
     }
   }
-}
 
-export default async function publishDocs({ docsDir, appUrl, boardId }) {
   const accessToken = await getAccessToken(appUrl);
 
   process.env.DOC_ROOT_DIR = docsDir;
 
   const sidebarPath = join(docsDir, "_sidebar.md");
 
-  const boardName = boardId ? "" : getProjectName();
+  let projectInfo = {
+    name: boardName,
+    description: boardDesc,
+    icon: boardCover,
+  };
+
+  // Only get project info if we need to create a new board
+  if (!boardName) {
+    projectInfo = await getProjectInfo(options);
+
+    // save project info to config
+    await saveValueToConfig("boardName", projectInfo.name);
+    await saveValueToConfig("boardDesc", projectInfo.description);
+    await saveValueToConfig("boardCover", projectInfo.icon);
+  }
 
   const { success, boardId: newBoardId } = await publishDocsFn({
     sidebarPath,
     accessToken,
     appUrl,
     boardId,
-    // If boardId is empty, use project name as boardName and auto create board
-    boardName,
-    autoCreateBoard: !boardId,
+    autoCreateBoard: true,
+    // Pass additional project information if available
+    boardName: projectInfo.name,
+    boardDesc: projectInfo.description,
+    boardCover: projectInfo.icon,
   });
 
-  // Save boardId to config.yaml if it was auto-created
-  await saveBoardIdToInput(boardId, newBoardId);
+  // Save values to config.yaml if publish was successful
+  if (success) {
+    // Save appUrl to config only when not using environment variable
+    if (!useEnvAppUrl) {
+      await saveValueToConfig("appUrl", appUrl);
+    }
 
-  return {
-    publishResult: {
-      success,
-    },
-  };
+    // Save boardId to config if it was auto-created
+    if (boardId !== newBoardId) {
+      await saveValueToConfig("boardId", newBoardId);
+    }
+  }
+
+  return {};
 }
 
 publishDocs.input_schema = {
@@ -199,9 +312,7 @@ publishDocs.input_schema = {
     appUrl: {
       type: "string",
       description: "The url of the app",
-      default:
-        // "https://bbqawfllzdt3pahkdsrsone6p3wpxcwp62vlabtawfu.did.abtnet.io",
-        "https://www.staging.arcblock.io",
+      default: DEFAULT_APP_URL,
     },
     boardId: {
       type: "string",

package/agents/reflective-structure-planner.yaml

@@ -1,5 +1,5 @@
 type: team
-name: reflective-structure-planner
+name: reflectiveStructurePlanner
 description: A team of agents that plan the structure of the documentation.
 skills:
   - structure-planning.yaml

package/agents/save-docs.mjs

@@ -1,5 +1,6 @@
 import { writeFile, readdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { getCurrentGitHead, saveGitHeadToConfig } from "../utils/utils.mjs";
 
 /**
  * @param {Object} params
@@ -15,31 +16,36 @@ export default async function saveDocs({
   locale,
 }) {
   const results = [];
+  // Save current git HEAD to config.yaml for change detection
+  try {
+    const gitHead = getCurrentGitHead();
+    await saveGitHeadToConfig(gitHead);
+  } catch (err) {
+    console.warn("Failed to save git HEAD:", err.message);
+  }
 
   // Generate _sidebar.md
   try {
     const sidebar = generateSidebar(structurePlan);
     const sidebarPath = join(docsDir, "_sidebar.md");
     await writeFile(sidebarPath, sidebar, "utf8");
-    results.push({ path: sidebarPath, success: true });
   } catch (err) {
-    results.push({ path: "_sidebar.md", success: false, error: err.message });
+    console.error("Failed to save _sidebar.md:", err.message);
   }
 
   // Clean up invalid .md files that are no longer in the structure plan
   try {
-    const cleanupResults = await cleanupInvalidFiles(
+    await cleanupInvalidFiles(
       structurePlan,
       docsDir,
       translateLanguages,
       locale
     );
-    results.push(...cleanupResults);
   } catch (err) {
-    results.push({ path: "cleanup", success: false, error: err.message });
+    console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  return { saveDocsResult: results };
+  return {};
 }
 
 /**

package/agents/save-single-doc.mjs

@@ -16,5 +16,5 @@ export default async function saveSingleDoc({
     labels,
     locale,
   });
-  return { saveSingleDocResult: results };
+  return {};
 }

package/agents/structure-planning.yaml

@@ -1,4 +1,4 @@
-name: structure-planning
+name: structurePlanning
 description: 通用结构规划生成器，支持网站、文档、书籍、演示文稿等多种场景
 instructions:
   url: ../prompts/structure-planning.md

package/agents/team-publish-docs.yaml

@@ -5,6 +5,9 @@ alias:
   - p
 description: Publish the documentation to Discuss Kit
 skills:
+  - url: ./input-generator.mjs
+    default_input:
+      skipIfExists: true
   - load-config.mjs
   - publish-docs.mjs
 input_schema:

package/agents/transform-detail-datasources.mjs

@@ -1,14 +1,28 @@
+import { normalizePath, toRelativePath } from "../utils/utils.mjs";
+
 export default function transformDetailDatasources({
   sourceIds,
   datasourcesList,
 }) {
-  // Build a map for fast lookup
+  // Build a map for fast lookup, with path normalization for compatibility
   const dsMap = Object.fromEntries(
-    (datasourcesList || []).map((ds) => [ds.sourceId, ds.content])
+    (datasourcesList || []).map((ds) => {
+      const normalizedSourceId = normalizePath(ds.sourceId);
+      return [normalizedSourceId, ds.content];
+    })
   );
-  // Collect formatted contents in order
+
+  // Collect formatted contents in order, with path normalization
   const contents = (sourceIds || [])
-    .filter((id) => dsMap[id])
-    .map((id) => `// sourceId: ${id}\n${dsMap[id]}\n`);
+    .filter((id) => {
+      const normalizedId = normalizePath(id);
+      return dsMap[normalizedId];
+    })
+    .map((id) => {
+      const normalizedId = normalizePath(id);
+      const relativeId = toRelativePath(id);
+      return `// sourceId: ${relativeId}\n${dsMap[normalizedId]}\n`;
+    });
+
   return { detailDataSources: contents.join("") };
 }

package/aigne.yaml

@@ -12,12 +12,12 @@ agents:
   - ./agents/save-docs.mjs
   - ./agents/translate.yaml
   - ./agents/detail-generator-and-translate.yaml
-  - ./agents/check-detail-generated.mjs
+  - ./agents/check-detail.mjs
   - ./agents/transform-detail-datasources.mjs
   - ./agents/batch-translate.yaml
   - ./agents/save-single-doc.mjs
   - ./agents/save-output.mjs
-  - ./agents/check-structure-planning.mjs
+  - ./agents/check-structure-plan.mjs
   - ./agents/content-detail-generator.yaml
   - ./agents/reflective-structure-planner.yaml
   - ./agents/check-structure-planning-result.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,14 +12,16 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/anthropic": "^0.10.6",
-    "@aigne/cli": "^1.30.1",
-    "@aigne/core": "^1.43.0",
-    "@aigne/gemini": "^0.8.10",
-    "@aigne/openai": "^0.10.10",
+    "@aigne/anthropic": "^0.10.9",
+    "@aigne/cli": "^1.30.4",
+    "@aigne/core": "^1.45.0",
+    "@aigne/gemini": "^0.8.13",
+    "@aigne/openai": "^0.10.13",
     "@aigne/publish-docs": "^0.5.2",
+    "chalk": "^5.5.0",
     "glob": "^11.0.3",
     "open": "^10.2.0",
+    "terminal-link": "^4.0.0",
     "ufo": "^1.6.1",
     "yaml": "^2.8.0"
   },

package/prompts/check-structure-planning-result.md

@@ -17,7 +17,7 @@
 ```
 {{ feedback }}
 
-根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
+根据最新的 Data Sources 按需要更新节点的 sourceIds。
 ```
 </context>
 

package/prompts/structure-planning.md

@@ -30,7 +30,7 @@
 <structure_plan_feedback>
 {{ feedback }}
 
-根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
+根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
 </structure_plan_feedback>
 
 <review_structure_plan>

package/utils/constants.mjs

@@ -0,0 +1,105 @@
+// Default file patterns for inclusion and exclusion
+export const DEFAULT_INCLUDE_PATTERNS = [
+  "*.py",
+  "*.js",
+  "*.jsx",
+  "*.ts",
+  "*.tsx",
+  "*.go",
+  "*.java",
+  "*.pyi",
+  "*.pyx",
+  "*.c",
+  "*.cc",
+  "*.cpp",
+  "*.h",
+  "*.md",
+  "*.rst",
+  "*.json",
+  "*Dockerfile",
+  "*Makefile",
+  "*.yaml",
+  "*.yml",
+];
+
+export const DEFAULT_EXCLUDE_PATTERNS = [
+  "aigne-docs/**",
+  "doc-smith/**",
+  "assets/**",
+  "data/**",
+  "images/**",
+  "public/**",
+  "static/**",
+  "**/vendor/**",
+  "temp/**",
+  "**/*docs/**",
+  "**/*doc/**",
+  "**/*venv/**",
+  "*.venv/**",
+  "*test*",
+  "**/*test/**",
+  "**/*tests/**",
+  "**/*examples/**",
+  "**/playgrounds/**",
+  "v1/**",
+  "**/dist/**",
+  "**/*build/**",
+  "**/*experimental/**",
+  "**/*deprecated/**",
+  "**/*misc/**",
+  "**/*legacy/**",
+  ".git/**",
+  ".github/**",
+  ".next/**",
+  ".vscode/**",
+  "**/*obj/**",
+  "**/*bin/**",
+  "**/*node_modules/**",
+  "*.log",
+  "**/*test.*",
+];
+
+// Supported languages for documentation
+export const SUPPORTED_LANGUAGES = [
+  { code: "en", label: "English (en)", sample: "Hello" },
+  { code: "zh-CN", label: "简体中文 (zh-CN)", sample: "你好" },
+  { code: "zh-TW", label: "繁體中文 (zh-TW)", sample: "你好" },
+  { code: "ja", label: "日本語 (ja)", sample: "こんにちは" },
+  { code: "ko", label: "한국어 (ko)", sample: "안녕하세요" },
+  { code: "es", label: "Español (es)", sample: "Hola" },
+  { code: "fr", label: "Français (fr)", sample: "Bonjour" },
+  { code: "de", label: "Deutsch (de)", sample: "Hallo" },
+  { code: "pt-BR", label: "Português (pt-BR)", sample: "Olá" },
+  { code: "ru", label: "Русский (ru)", sample: "Привет" },
+  { code: "it", label: "Italiano (it)", sample: "Ciao" },
+  { code: "ar", label: "العربية (ar)", sample: "مرحبا" },
+];
+
+// Predefined document generation styles
+export const DOCUMENT_STYLES = {
+  developerDocs: {
+    name: "Developer Docs",
+    rules: "Steps-first; copy-paste examples; minimal context; active 'you'.",
+  },
+  userGuide: {
+    name: "User Guide",
+    rules: "Scenario-based; step-by-step; plain language; outcomes & cautions.",
+  },
+  apiReference: {
+    name: "API Reference",
+    rules: "Exact & skimmable; schema-first; clear params/errors/examples.",
+  },
+  custom: {
+    name: "Custom Rules",
+    rules: "Enter your own documentation generation rules",
+  },
+};
+
+// Predefined target audiences
+export const TARGET_AUDIENCES = {
+  actionFirst: "Developers, Implementation Engineers, DevOps",
+  conceptFirst:
+    "Architects, Technical Leads, Developers interested in principles",
+  generalUsers: "General Users",
+  custom: "Enter your own target audience",
+};