@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/utils/afs-factory.mjs

@@ -0,0 +1,183 @@
+import {
+  detectWorkspaceMode,
+  loadConfig,
+  DOC_SMITH_DIR,
+  SOURCES_DIR,
+  WORKSPACE_MODES,
+} from "./workspace.mjs";
+
+// AIGNE framework placeholder for current working directory
+const CWD = "$" + "{CWD}";
+
+/**
+ * Generate base AFS modules (workspace and sources)
+ * @param {string} mode - Workspace mode (project | standalone)
+ * @returns {Array} - AFS module configuration array
+ */
+function generateBaseModules(mode) {
+  const modules = [];
+
+  if (mode === WORKSPACE_MODES.PROJECT) {
+    // Project mode: workspace is .aigne/doc-smith, sources is CWD
+    modules.push({
+      module: "local-fs",
+      options: {
+        name: "workspace",
+        localPath: `${CWD}/${DOC_SMITH_DIR}`,
+        description:
+          "Doc-smith workspace directory\n" +
+          "- Read-write access to documentation files\n" +
+          "- Use absolute path for file operations",
+      },
+    });
+
+    modules.push({
+      module: "local-fs",
+      options: {
+        name: "sources",
+        localPath: CWD,
+        description:
+          "Source code directory (project root)\n" +
+          "- Read-only access to source files\n" +
+          "- Used for documentation generation",
+      },
+    });
+  } else {
+    // Standalone mode: workspace is CWD, sources is CWD/sources
+    modules.push({
+      module: "local-fs",
+      options: {
+        name: "workspace",
+        localPath: CWD,
+        description:
+          "Doc-smith workspace directory\n" +
+          "- Read-write access to documentation files\n" +
+          "- Use absolute path for file operations",
+      },
+    });
+
+    modules.push({
+      module: "local-fs",
+      options: {
+        name: "sources",
+        localPath: `${CWD}/${SOURCES_DIR}`,
+        description:
+          "Source code directory\n" +
+          "- Read-only access to source files\n" +
+          "- Used for documentation generation",
+      },
+    });
+  }
+
+  return modules;
+}
+
+/**
+ * Generate skill module configuration
+ * @param {string} skillName - Skill name
+ * @param {string} skillPath - Skill relative path
+ * @param {string} description - Skill description
+ * @returns {Object} - AFS module configuration
+ */
+function generateSkillModule(skillName, skillPath, description) {
+  return {
+    module: "local-fs",
+    options: {
+      agentSkills: true,
+      name: skillName,
+      localPath: skillPath,
+      description:
+        description +
+        "\n- Read-only access to skill definition files\n" +
+        "- Do NOT modify files in this directory",
+    },
+  };
+}
+
+/**
+ * Generate history module configuration
+ * @returns {Object} - History module configuration
+ */
+function generateHistoryModule() {
+  return {
+    module: "history",
+    options: {
+      storage: {
+        url: "file:./.aigne/history.db",
+      },
+    },
+  };
+}
+
+/**
+ * Generate complete AFS module configuration
+ * @param {Object} options - Configuration options
+ * @param {Object} options.workspace - Workspace info { mode, configPath }
+ * @param {string} options.skillName - Skill name
+ * @param {string} options.skillPath - Skill relative path
+ * @param {string} options.skillDescription - Skill description
+ * @param {boolean} options.includeHistory - Whether to include history module
+ * @returns {Promise<Array>} - AFS module configuration array
+ */
+export async function generateAfsModules({
+  workspace,
+  skillName,
+  skillPath,
+  skillDescription = "Agent skill for document operations",
+  includeHistory = false,
+} = {}) {
+  // Determine workspace mode
+  let mode;
+  if (workspace) {
+    const config = await loadConfig(workspace.configPath);
+    mode = config?.mode || workspace.mode;
+  } else {
+    const detected = await detectWorkspaceMode();
+    mode = detected?.mode || WORKSPACE_MODES.STANDALONE;
+  }
+
+  const modules = [];
+
+  // Add history module (if needed)
+  if (includeHistory) {
+    modules.push(generateHistoryModule());
+  }
+
+  // Add base modules (workspace and sources)
+  modules.push(...generateBaseModules(mode));
+
+  // Add skill module
+  if (skillName && skillPath) {
+    modules.push(generateSkillModule(skillName, skillPath, skillDescription));
+  }
+
+  return modules;
+}
+
+/**
+ * Generate AFS modules for doc-smith main agent
+ * @param {Object} workspace - Workspace info
+ * @returns {Promise<Array>} - AFS module configuration array
+ */
+export async function generateDocSmithAfsModules(workspace) {
+  return generateAfsModules({
+    workspace,
+    skillName: "doc-smith",
+    skillPath: "../../skills/doc-smith",
+    skillDescription: "Agent skill for document operations",
+    includeHistory: true,
+  });
+}
+
+/**
+ * Generate AFS modules for doc-smith-docs-detail agent
+ * @returns {Promise<Array>} - AFS module configuration array
+ */
+export async function generateDocsDetailAfsModules() {
+  return generateAfsModules({
+    skillName: "doc-smith-docs-detail",
+    skillPath: "../../skills/doc-smith-docs-detail",
+    skillDescription: "Agent skill for document detail generation",
+    includeHistory: false,
+  });
+}

package/utils/agent-constants.mjs

@@ -0,0 +1,97 @@
+import { resolve } from "node:path";
+import { detectWorkspaceModeSync } from "./workspace.mjs";
+
+// Use unified workspace detection logic
+const { workspaceBase: WORKSPACE_BASE } = detectWorkspaceModeSync();
+
+/**
+ * Path constants definition
+ * All paths are absolute paths based on workspace
+ */
+export const PATHS = {
+  // Workspace root directory
+  WORKSPACE_BASE,
+
+  // Temp directory
+  TMP_DIR: resolve(WORKSPACE_BASE, ".tmp"),
+
+  // Cache directory
+  CACHE: resolve(WORKSPACE_BASE, "cache"),
+
+  // Document structure file
+  DOCUMENT_STRUCTURE: resolve(WORKSPACE_BASE, "planning/document-structure.yaml"),
+
+  // Documents directory
+  DOCS_DIR: resolve(WORKSPACE_BASE, "docs"),
+
+  // Assets directory (images, etc.)
+  ASSETS_DIR: resolve(WORKSPACE_BASE, "assets"),
+
+  // Config file
+  CONFIG: resolve(WORKSPACE_BASE, "config.yaml"),
+
+  // Glossary
+  GLOSSARY: resolve(WORKSPACE_BASE, "intent/GLOSSARY.md"),
+
+  // Planning directory
+  PLANNING_DIR: resolve(WORKSPACE_BASE, "planning"),
+};
+
+/**
+ * Error code constants
+ * Unified management of error types
+ */
+export const ERROR_CODES = {
+  // File system related
+  FILE_NOT_FOUND: "FILE_NOT_FOUND",
+  FILE_READ_ERROR: "FILE_READ_ERROR",
+  FILE_WRITE_ERROR: "FILE_WRITE_ERROR",
+  FILE_OPERATION_ERROR: "FILE_OPERATION_ERROR",
+
+  // Document structure related
+  MISSING_STRUCTURE_FILE: "MISSING_STRUCTURE_FILE",
+  INVALID_STRUCTURE_FILE: "INVALID_STRUCTURE_FILE",
+
+  // Config related
+  MISSING_CONFIG_FILE: "MISSING_CONFIG_FILE",
+  MISSING_LOCALE: "MISSING_LOCALE",
+
+  // Content related
+  EMPTY_CONTENT: "EMPTY_CONTENT",
+  INVALID_CONTENT: "INVALID_CONTENT",
+
+  // Path related
+  INVALID_PATH: "INVALID_PATH",
+  PATH_NOT_IN_STRUCTURE: "PATH_NOT_IN_STRUCTURE",
+  INVALID_DOC_PATHS: "INVALID_DOC_PATHS",
+
+  // Language related
+  INVALID_LANGUAGE: "INVALID_LANGUAGE",
+  MISSING_LANGS: "MISSING_LANGS",
+  MISSING_SOURCE_FILE: "MISSING_SOURCE_FILE",
+
+  // Content validation related
+  SOURCE_LOCALE_MISMATCH: "SOURCE_LOCALE_MISMATCH",
+  MISSING_TRANSLATE_LANGUAGE: "MISSING_TRANSLATE_LANGUAGE",
+  INVALID_LINK_FORMAT: "INVALID_LINK_FORMAT",
+
+  // Other
+  SAVE_ERROR: "SAVE_ERROR",
+  UNEXPECTED_ERROR: "UNEXPECTED_ERROR",
+};
+
+/**
+ * File type constants
+ */
+export const FILE_TYPES = {
+  META: ".meta.yaml",
+  MARKDOWN: ".md",
+  YAML: ".yaml",
+};
+
+/**
+ * Document metadata defaults
+ */
+export const DOC_META_DEFAULTS = {
+  KIND: "doc",
+};

package/utils/{auth-utils.mjs → auth.mjs}

@@ -5,11 +5,7 @@ import { createConnect } from "@aigne/cli/utils/aigne-hub/credential.js";
 import chalk from "chalk";
 import open from "open";
 import { joinURL, withQuery } from "ufo";
-import {
-  ComponentNotFoundError,
-  getComponentMountPoint,
-  InvalidBlockletError,
-} from "./blocklet.mjs";
+import { ComponentNotFoundError, getComponentMountPoint, InvalidBlockletError } from "./http.mjs";
 import {
   BLOCKLET_ADD_COMPONENT_DOCS,
   CLOUD_SERVICE_URL_PROD,
@@ -17,7 +13,7 @@ import {
   DISCUSS_KIT_DID,
   DISCUSS_KIT_STORE_URL,
   PAYMENT_KIT_DID,
-} from "./constants/index.mjs";
+} from "./constants.mjs";
 import { createStore } from "./store/index.mjs";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
@@ -156,12 +152,13 @@ export async function getAccessToken(appUrl, ltToken = "", locale = "en") {
 
     // Save the access token to config file
     await saveTokenToConfigFile(targetHostname, { DOC_DISCUSS_KIT_ACCESS_TOKEN: accessToken });
-  } catch {
+  } catch (error) {
+    console.error(error.message);
     throw new Error(
       `${chalk.yellow("⚠️ Failed to obtain access token. This may be due to network issues or authorization timeout.")}\n\n` +
         `${chalk.bold("💡 Solution:")}\n` +
         `  • Step 1: Ensure your network can access the service URL: ${chalk.cyan(targetOrigin)}\n` +
-        `  • Step 2: Run ${chalk.cyan("aigne doc publish")} again\n` +
+        `  • Step 2: Re-run the document publishing process\n` +
         `  • Step 3: If prompted, select ${chalk.cyan("Resume previous website setup")} to continue from where you left off\n\n`,
     );
   }
@@ -245,7 +242,7 @@ export async function getOfficialAccessToken(baseUrl, openPage = true, locale =
       `${chalk.yellow("⚠️ Failed to obtain official access token. This may be due to network issues or authorization timeout.")}\n\n` +
         `${chalk.bold("💡 Solution:")}\n` +
         `  • Step 1: Ensure your network can access the official service URL: ${chalk.cyan(targetOrigin)}\n` +
-        `  • Step 2: Run ${chalk.cyan("aigne doc publish")} again\n\n`,
+        `  • Step 2: Re-run the document publishing process\n`,
     );
   }
 

package/{agents/utils/update-branding.mjs → utils/branding.mjs}

@@ -2,14 +2,13 @@ import { stat } from "node:fs/promises";
 import chalk from "chalk";
 import { joinURL } from "ufo";
 
-import { getComponentInfoWithMountPoint } from "../../utils/blocklet.mjs";
+import { getComponentInfoWithMountPoint, requestWithAuthToken } from "./http.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";
+} from "./constants.mjs";
+import { uploadFiles } from "./upload.mjs";
 
 export default async function updateBranding({ appUrl, projectInfo, accessToken, finalPath }) {
   try {

package/utils/config.mjs

@@ -0,0 +1,261 @@
+import { existsSync, mkdirSync } from "node:fs";
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import { parse, stringify as yamlStringify } from "yaml";
+import { PATHS, ERROR_CODES } from "./agent-constants.mjs";
+
+/**
+ * Load config from config.yaml file
+ * @returns {Promise<Object|null>} - The config object or null if file doesn't exist
+ */
+export async function loadConfigFromFile() {
+  try {
+    if (!existsSync(PATHS.CONFIG)) {
+      return null;
+    }
+
+    const configContent = await fs.readFile(PATHS.CONFIG, "utf8");
+    return parse(configContent);
+  } catch (error) {
+    console.warn("Failed to read config file:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Handle string value formatting and updating in YAML config
+ * @param {string} key - The configuration key
+ * @param {string} value - The string value to save
+ * @param {string} comment - Optional comment
+ * @param {string} fileContent - Current file content
+ * @returns {string} Updated file content
+ */
+function handleStringValueUpdate(key, value, comment, fileContent) {
+  // Skip if key is empty to avoid "Empty regular expressions are not allowed" error
+  if (!key || !key.trim()) {
+    return fileContent;
+  }
+
+  const yamlObject = { [key]: value };
+  const yamlContent = yamlStringify(yamlObject).trim();
+  const formattedValue = yamlContent.substring(yamlContent.indexOf(":") + 1).trim();
+
+  const lines = fileContent.split("\n");
+  const keyRegex = new RegExp(`^${key}:\\s*`);
+  const keyIndex = lines.findIndex((line) => line.match(keyRegex));
+
+  if (keyIndex !== -1) {
+    lines[keyIndex] = `${key}: ${formattedValue}`;
+  } else {
+    if (comment) {
+      lines.push(`# ${comment}`);
+    }
+    lines.push(`${key}: ${formattedValue}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Handle array value formatting and updating in YAML config
+ * @param {string} key - The configuration key
+ * @param {Array} value - The array value to save
+ * @param {string} comment - Optional comment
+ * @param {string} fileContent - Current file content
+ * @returns {string} Updated file content
+ */
+function handleArrayValueUpdate(key, value, comment, fileContent) {
+  if (!key || !key.trim()) {
+    return fileContent;
+  }
+
+  const yamlObject = { [key]: value };
+  const yamlContent = yamlStringify(yamlObject).trim();
+  const formattedValue = yamlContent;
+
+  const lines = fileContent.split("\n");
+  const keyStartIndex = lines.findIndex((line) => line.match(new RegExp(`^${key}:\\s*`)));
+
+  if (keyStartIndex !== -1) {
+    let keyEndIndex = keyStartIndex;
+    for (let i = keyStartIndex + 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (line === "" || line.startsWith("#") || (!line.startsWith("- ") && !line.match(/^\w+:/))) {
+        if (!line.startsWith("- ")) {
+          keyEndIndex = i - 1;
+          break;
+        }
+      } else if (line.match(/^\w+:/)) {
+        keyEndIndex = i - 1;
+        break;
+      } else if (line.startsWith("- ")) {
+        keyEndIndex = i;
+      }
+    }
+
+    if (keyEndIndex === keyStartIndex) {
+      const keyLine = lines[keyStartIndex];
+      if (keyLine.includes("[") || !keyLine.endsWith(":")) {
+        keyEndIndex = keyStartIndex;
+      } else {
+        for (let i = keyStartIndex + 1; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (line.startsWith("- ")) {
+            keyEndIndex = i;
+          } else if (line !== "" && !line.startsWith("#")) {
+            break;
+          }
+        }
+      }
+    }
+
+    const replacementLines = formattedValue.split("\n");
+    lines.splice(keyStartIndex, keyEndIndex - keyStartIndex + 1, ...replacementLines);
+
+    if (comment && keyStartIndex > 0 && !lines[keyStartIndex - 1].trim().startsWith("# ")) {
+      lines.splice(keyStartIndex, 0, `# ${comment}`);
+    }
+  } else {
+    if (comment) {
+      lines.push(`# ${comment}`);
+    }
+    const formattedLines = formattedValue.split("\n");
+    lines.push(...formattedLines);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Save value to config.yaml file
+ * @param {string} key - The config key to save
+ * @param {string|Array} value - The value to save (can be string or array)
+ * @param {string} [comment] - Optional comment to add above the key
+ */
+export async function saveValueToConfig(key, value, comment) {
+  if (value === undefined) {
+    return;
+  }
+
+  try {
+    const workspaceDir = PATHS.WORKSPACE_BASE;
+    if (!existsSync(workspaceDir)) {
+      mkdirSync(workspaceDir, { recursive: true });
+    }
+
+    let fileContent = "";
+
+    if (existsSync(PATHS.CONFIG)) {
+      fileContent = await fs.readFile(PATHS.CONFIG, "utf8");
+    }
+
+    let updatedContent;
+    if (Array.isArray(value)) {
+      updatedContent = handleArrayValueUpdate(key, value, comment, fileContent);
+    } else {
+      updatedContent = handleStringValueUpdate(key, value, comment, fileContent);
+    }
+
+    await fs.writeFile(PATHS.CONFIG, updatedContent);
+  } catch (error) {
+    console.warn(`Failed to save ${key} to config.yaml:`, error.message);
+  }
+}
+
+/**
+ * Generate configuration YAML content
+ * @param {Object} input - Input configuration object
+ * @returns {string} - YAML configuration string
+ */
+export function generateConfigYAML(input) {
+  const config = {
+    workspaceVersion: input.workspaceVersion || "1.0",
+    createdAt: input.createdAt || new Date().toISOString(),
+    projectName: (input.projectName || "").trim(),
+    projectDesc: (input.projectDesc || "").trim(),
+    projectLogo: input.projectLogo || "",
+    locale: input.locale || "en",
+    translateLanguages: input.translateLanguages?.filter((lang) => lang.trim()) || [],
+    docsDir: input.docsDir || "./docs",
+    sourcesPath: input.sourcesPath || [],
+    source: input.source || null,
+  };
+
+  let yaml = "# Workspace metadata\n";
+  const metadataSection = yamlStringify({
+    workspaceVersion: config.workspaceVersion,
+    createdAt: config.createdAt,
+  }).trim();
+  yaml += `${metadataSection}\n\n`;
+
+  yaml += "# Project information for documentation publishing\n";
+  const projectSection = yamlStringify({
+    projectName: config.projectName,
+    projectDesc: config.projectDesc,
+    projectLogo: config.projectLogo,
+  }).trim();
+
+  yaml += `${projectSection}\n\n`;
+
+  yaml += "# Language settings\n";
+  const localeSection = yamlStringify({ locale: config.locale }).trim();
+  yaml += `${localeSection}\n`;
+
+  if (config.translateLanguages.length > 0) {
+    const translateLanguagesSection = yamlStringify({
+      translateLanguages: config.translateLanguages,
+    }).trim();
+    yaml += `${translateLanguagesSection}\n`;
+  } else {
+    yaml += "# translateLanguages:  # A list of languages to translate the documentation to.\n";
+    yaml += "#   - zh  # Example: Chinese translation\n";
+    yaml += "#   - en  # Example: English translation\n";
+  }
+
+  yaml += "\n# Source repository configuration\n";
+  if (config.source) {
+    const sourceSection = yamlStringify({ source: config.source }).trim();
+    yaml += `${sourceSection}\n`;
+  } else {
+    yaml += "# source:  # Git submodule source repository\n";
+    yaml += "#   type: git-submodule\n";
+    yaml += "#   path: sources/my-project\n";
+    yaml += "#   url: https://github.com/user/repo.git\n";
+    yaml += "#   branch: main\n";
+  }
+
+  yaml += "\n# Documentation directory and source paths\n";
+  const docsDirSection = yamlStringify({ docsDir: config.docsDir }).trim();
+  yaml += `${docsDirSection}  # The directory where the generated documentation will be saved.\n`;
+
+  const sourcesPathSection = yamlStringify({
+    sourcesPath: config.sourcesPath,
+  }).trim();
+  yaml += `${sourcesPathSection.replace(/^sourcesPath:/, "sourcesPath:  # The source code paths to analyze.")}\n`;
+
+  return yaml;
+}
+
+/**
+ * Load config file to get the primary locale
+ * @returns {Promise<string>} - Primary language code
+ * @throws {Error} - Throws when config file doesn't exist or locale field is missing
+ */
+export async function loadLocale() {
+  try {
+    await fs.access(PATHS.CONFIG, constants.F_OK | constants.R_OK);
+    const content = await fs.readFile(PATHS.CONFIG, "utf8");
+    const config = parse(content);
+
+    if (!config.locale || typeof config.locale !== "string") {
+      throw new Error(ERROR_CODES.MISSING_LOCALE);
+    }
+
+    return config.locale;
+  } catch (error) {
+    if (error.message === ERROR_CODES.MISSING_LOCALE) {
+      throw error;
+    }
+    throw new Error(ERROR_CODES.MISSING_CONFIG_FILE);
+  }
+}

package/utils/constants.mjs

@@ -0,0 +1,32 @@
+// Publishing feature related constants (minimal version)
+
+// Component mount point ID for Discuss Kit
+export const DISCUSS_KIT_DID = "z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
+export const MEDIA_KIT_DID = "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9";
+export const PAYMENT_KIT_DID = "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk";
+
+// Default application URL for the document deployment website
+export const CLOUD_SERVICE_URL_PROD = "https://docsmith.aigne.io";
+export const CLOUD_SERVICE_URL_STAGING = "https://staging.docsmith.aigne.io";
+
+// Discuss Kit related URLs
+export const DISCUSS_KIT_STORE_URL =
+  "https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
+export const BLOCKLET_ADD_COMPONENT_DOCS =
+  "https://www.arcblock.io/docs/blocklet-developer/en/7zbw0GQXgcD6sCcjVfwqqT2s";
+
+// Supported languages for documentation
+export const SUPPORTED_LANGUAGES = [
+  { code: "en", label: "English (en)", sample: "Hello" },
+  { code: "zh", label: "简体中文 (zh)", 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", label: "Português (pt)", sample: "Olá" },
+  { code: "ru", label: "Русский (ru)", sample: "Привет" },
+  { code: "it", label: "Italiano (it)", sample: "Ciao" },
+  { code: "ar", label: "العربية (ar)", sample: "مرحبا" },
+];

package/utils/deploy.mjs

@@ -1,9 +1,9 @@
 import { BrokerClient, STEPS } from "@blocklet/payment-broker-client/node";
 import chalk from "chalk";
 import open from "open";
-import { getOfficialAccessToken } from "./auth-utils.mjs";
-import { CLOUD_SERVICE_URL_PROD } from "./constants/index.mjs";
-import { saveValueToConfig } from "./utils.mjs";
+import { getOfficialAccessToken } from "./auth.mjs";
+import { CLOUD_SERVICE_URL_PROD } from "./constants.mjs";
+import { saveValueToConfig } from "./config.mjs";
 
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 const SUCCESS_MESSAGE = {