@aigne/doc-smith 0.8.12 → 0.8.13-beta

package/utils/auth-utils.mjs

@@ -53,7 +53,7 @@ export async function getAccessToken(appUrl, ltToken = "") {
         }
       }
     } catch (error) {
-      console.warn("Failed to read config file:", error.message);
+      console.warn("Could not read the configuration file:", error.message);
     }
   }
 
@@ -69,25 +69,25 @@ export async function getAccessToken(appUrl, ltToken = "") {
     const storeLink = chalk.cyan(DISCUSS_KIT_STORE_URL);
     if (error instanceof InvalidBlockletError) {
       throw new Error(
-        `${chalk.yellow("⚠️  The provided URL is not a valid website on ArcBlock platform")}\n\n` +
-          `${chalk.bold("💡 Solution:")} Start here to run your own website that can host your docs:\n${storeLink}\n\n`,
+        `${chalk.yellow("⚠️  The provided URL is not a valid ArcBlock-powered website.")}\n\n` +
+          `${chalk.bold("💡 Solution:")} To host your documentation, you can get a website from the ArcBlock store:\n${storeLink}\n\n`,
       );
     } else if (error instanceof ComponentNotFoundError) {
       const docsLink = chalk.cyan(BLOCKLET_ADD_COMPONENT_DOCS);
       throw new Error(
-        `${chalk.yellow("⚠️  This website does not have required components for publishing")}\n\n` +
+        `${chalk.yellow("⚠️ This website is missing the required components for publishing.")}\n\n` +
           `${chalk.bold(
             "💡 Solution:",
-          )} Please refer to the documentation to add Discuss Kit component:\n${docsLink}\n\n`,
+          )} Please refer to the documentation to add the Discuss Kit component:\n${docsLink}\n\n`,
       );
     } else {
       throw new Error(
-        `❌ Unable to connect to: ${chalk.cyan(appUrl)}\n\n` +
+        `❌ Could not connect to: ${chalk.cyan(appUrl)}\n\n` +
           `${chalk.bold("Possible causes:")}\n` +
-          `• Network connection issues\n` +
-          `• Server temporarily unavailable\n` +
-          `• Incorrect URL address\n\n` +
-          `${chalk.green("Suggestion:")} Please check your network connection and URL, then try again`,
+          `• There may be a network issue.\n` +
+          `• The server may be temporarily unavailable.\n` +
+          `• The URL may be incorrect.\n\n` +
+          `${chalk.green("Suggestion:")} Please check your network connection and the URL, then try again.`,
       );
     }
   }
@@ -145,7 +145,7 @@ export async function getAccessToken(appUrl, ltToken = "") {
   } catch (error) {
     console.debug(error);
     throw new Error(
-      "Failed to obtain access token. Please check your network connection and try again later.",
+      "Could not get an access token. Please check your network connection and try again.",
     );
   }
 
@@ -153,14 +153,13 @@ export async function getAccessToken(appUrl, ltToken = "") {
 }
 
 /**
- * Get official access token from environment, config file, or prompt user for authorization.
- * @param {string} baseUrl - The official service URL
- * @returns {Promise<string>} - The access token
+ * Gets the official access token from the environment, config file, or prompts the user to authorize.
+ * @param {string} baseUrl - The official service URL.
+ * @returns {Promise<string>} The access token.
  */
 export async function getOfficialAccessToken(baseUrl, openPage = true) {
-  // Early parameter validation
   if (!baseUrl) {
-    throw new Error("baseUrl parameter is required for getOfficialAccessToken.");
+    throw new Error("The baseUrl parameter is required for getOfficialAccessToken.");
   }
 
   // Parse URL once and reuse
@@ -183,7 +182,7 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
         }
       }
     } catch (_error) {
-      // ignore
+      // Ignore errors
     }
   }
 
@@ -205,7 +204,7 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
       appLogo: "https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg",
       openPage: (pageUrl) => {
         console.log(
-          "🔗 Please open this URL in your browser to authorize access: ",
+          "🔗 Please open the following URL in your browser to authorize access: ",
           chalk.cyan(pageUrl),
           "\n",
         );
@@ -226,7 +225,7 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
   } catch (error) {
     console.debug(error);
     throw new Error(
-      "Failed to obtain official access token. Please check your network connection and try again later.",
+      "Could not get an official access token. Please check your network connection and try again.",
     );
   }
 
@@ -234,11 +233,11 @@ export async function getOfficialAccessToken(baseUrl, openPage = true) {
 }
 
 /**
- * Helper function to save access token to config file
- * @param {string} configFile - Path to config file
- * @param {string} hostname - Hostname key
- * @param {string} tokenKey - Token key name
- * @param {string} tokenValue - Token value
+ * Saves the access token to the configuration file.
+ * @param {string} configFile - The path to the config file.
+ * @param {string} hostname - The hostname key.
+ * @param {string} tokenKey - The token key name.
+ * @param {string} tokenValue - The token value.
  */
 async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue) {
   try {
@@ -266,7 +265,7 @@ async function saveTokenToConfigFile(configFile, hostname, tokenKey, tokenValue)
       }),
     );
   } catch (error) {
-    console.warn(`Failed to save token to config file ${configFile}: ${error.message}`, error);
-    // Don't throw here, as the token is already obtained and set in env
+    console.warn(`Could not save the token to the configuration file: ${error.message}`, error);
+    // The token is already in the environment, so we don't need to throw an error here.
   }
 }

package/utils/blocklet.mjs

@@ -1,11 +1,11 @@
 import { joinURL } from "ufo";
 
 /**
- * Custom error class for invalid blocklet application URLs
+ * Custom error class for invalid blocklet application URLs.
  */
 export class InvalidBlockletError extends Error {
   constructor(url, status, statusText) {
-    super(`Invalid application URL: "${url}". Unable to fetch configuration.`);
+    super(`The application URL "${url}" is invalid. I was unable to fetch the configuration.`);
     this.name = "InvalidBlockletError";
     this.url = url;
     this.status = status;
@@ -14,20 +14,42 @@ export class InvalidBlockletError extends Error {
 }
 
 /**
- * Custom error class for missing component mount points
+ * Custom error class for missing component mount points.
  */
 export class ComponentNotFoundError extends Error {
   constructor(did, appUrl) {
-    super(`Your website "${appUrl}" missing required component to host your docs.`);
+    super(`Your website "${appUrl}" is missing a required component to host your documentation.`);
     this.name = "ComponentNotFoundError";
     this.did = did;
     this.appUrl = appUrl;
   }
 }
 
+const BLOCKLET_INFO_CACHE = {};
+
+// Export for testing purposes
+export function clearBlockletCache() {
+  Object.keys(BLOCKLET_INFO_CACHE).forEach((key) => {
+    delete BLOCKLET_INFO_CACHE[key];
+  });
+}
+
 export async function getComponentInfo(appUrl) {
   const blockletJsUrl = joinURL(appUrl, "__blocklet__.js?type=json");
 
+  const cacheInfo = BLOCKLET_INFO_CACHE[appUrl];
+
+  // Cache for 10 min
+  if (cacheInfo) {
+    if (Date.now() > cacheInfo.__blocklet_info_cache_timestamp + 1000 * 60 * 10) {
+      delete BLOCKLET_INFO_CACHE[appUrl];
+    } else {
+      // Return a copy without the cache timestamp
+      const { __blocklet_info_cache_timestamp, ...config } = cacheInfo;
+      return config;
+    }
+  }
+
   let blockletJs;
   try {
     blockletJs = await fetch(blockletJsUrl, {
@@ -45,8 +67,12 @@ export async function getComponentInfo(appUrl) {
   let config;
   try {
     config = await blockletJs.json();
+    BLOCKLET_INFO_CACHE[appUrl] = {
+      ...config,
+      __blocklet_info_cache_timestamp: Date.now(),
+    };
   } catch {
-    throw new InvalidBlockletError(appUrl, null, "Invalid JSON response");
+    throw new InvalidBlockletError(appUrl, null, "The server returned an invalid JSON response.");
   }
 
   return config;

package/utils/conflict-detector.mjs

@@ -135,13 +135,15 @@ export function generateConflictResolutionRules(conflicts) {
   rules.push("");
   rules.push("Conflict Resolution Principles:");
   rules.push(
-    "1. Meet diverse needs through intelligent structural design, not simple concatenation",
+    "1. Meet diverse needs through intelligent structural design, not by simply concatenating information.",
   );
-  rules.push("2. Create clear navigation paths for different purposes and audiences");
+  rules.push("2. Create clear navigation paths for different purposes and audiences.");
   rules.push(
-    "3. Ensure content hierarchy is reasonable, avoid information duplication or contradiction",
+    "3. Ensure a reasonable content hierarchy that avoids information duplication and contradiction.",
+  );
+  rules.push(
+    "4. Prioritize the user experience by enabling users to quickly find the information they need.",
   );
-  rules.push("4. Prioritize user experience, enable users to quickly find needed information");
 
   return rules.join("\n");
 }

package/utils/constants/index.mjs

@@ -329,6 +329,7 @@ export const DEPTH_RECOMMENDATION_LOGIC = {
 
 // 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";
 

package/utils/d2-utils.mjs

@@ -32,12 +32,12 @@ export async function getChart({ content, strict }) {
   try {
     const { diagram, renderOptions, graph } = await d2.compile(contentWithBase64Img);
 
-    // Ignore stroke-dash in sequence diagram
+    // Do not apply a stroke-dash to sequence diagrams.
     if (
       graph?.root?.attributes?.shape &&
       graph.root.attributes.shape.value !== "sequence_diagram"
     ) {
-      // Save first level container
+      // Save the first-level container.
       const firstLevelContainer = new Set();
       diagram.shapes.forEach((x) => {
         const idList = x.id.split(".");
@@ -50,7 +50,7 @@ export async function getChart({ content, strict }) {
       });
       firstLevelContainer.forEach((shape) => {
         if (!shape.strokeDash) {
-          // NOTICE: The data structure here is different from the d2 source code.
+          // Note: The data structure here is different from the d2 source code.
           shape.strokeDash = 3;
         }
       });
@@ -69,7 +69,6 @@ export async function getChart({ content, strict }) {
   }
 }
 
-// Helper: save d2 svg assets alongside document
 export async function saveAssets({ markdown, docsDir }) {
   if (!markdown) {
     return markdown;
@@ -87,10 +86,10 @@ export async function saveAssets({ markdown, docsDir }) {
       const svgPath = path.join(assetDir, fileName);
 
       if (await fs.pathExists(svgPath)) {
-        debug("Found assets cache, skipping generation", svgPath);
+        debug("Asset cache found, skipping generation", svgPath);
       } else {
         try {
-          debug("start generate d2 diagram", svgPath);
+          debug("Generating d2 diagram", svgPath);
           if (debug.enabled) {
             const d2FileName = `${getContentHash(d2Content)}.d2`;
             const d2Path = path.join(assetDir, d2FileName);
@@ -115,7 +114,7 @@ export async function saveAssets({ markdown, docsDir }) {
 }
 
 export async function beforePublishHook({ docsDir }) {
-  // Example: process each markdown file (replace with your logic)
+  // Process each markdown file to save d2 svg assets.
   const mdFilePaths = await glob("**/*.md", { cwd: docsDir });
   await pMap(
     mdFilePaths,
@@ -176,7 +175,7 @@ export async function checkContent({ content: _content }) {
   }
 
   if (await fs.pathExists(svgPath)) {
-    debug("Found assets cache, skipping generation", svgPath);
+    debug("Asset cache found, skipping generation", svgPath);
     return;
   }
 

package/utils/deploy.mjs

@@ -5,24 +5,23 @@ import { getOfficialAccessToken } from "./auth-utils.mjs";
 import { CLOUD_SERVICE_URL_PROD } from "./constants/index.mjs";
 import { saveValueToConfig } from "./utils.mjs";
 
-// ==================== Configuration ====================
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 const SUCCESS_MESSAGE = {
-  en: "Congratulations! Your website has been successfully installed. You can return to the command-line tool to continue the next steps.",
+  en: "Congratulations! Your website has been successfully installed. You can now return to the command-line tool to continue.",
   zh: "恭喜您，你的网站已安装成功！可以返回命令行工具继续后续操作！",
 };
 
 /**
- * Deploy a new Discuss Kit Website and return the installation URL
- * @param {string} id - Cached checkout ID (optional)
- * @param {string} cachedUrl - Cached payment URL (optional)
- * @returns {Promise<Object>} - The deployment result with URLs
+ * Deploys a new Discuss Kit Website and returns the installation URL.
+ * @param {string} id - The cached checkout ID (optional).
+ * @param {string} cachedUrl - The cached payment URL (optional).
+ * @returns {Promise<Object>} The deployment result with URLs.
  */
 export async function deploy(id, cachedUrl) {
   const authToken = await getOfficialAccessToken(BASE_URL);
 
   if (!authToken) {
-    throw new Error("Failed to get official access token");
+    throw new Error("Could not get an official access token.");
   }
 
   const client = new BrokerClient({ baseUrl: BASE_URL, authToken });
@@ -55,15 +54,15 @@ export async function deploy(id, cachedUrl) {
       },
 
       [STEPS.INSTALLATION_STARTING]: () => {
-        console.log(`📦 Step 2/4: Installing Website...`);
+        console.log(`📦 Step 2/4: Installing the website...`);
       },
 
       [STEPS.SERVICE_STARTING]: () => {
-        console.log(`🚀 Step 3/4: Starting Website...`);
+        console.log(`🚀 Step 3/4: Starting the website...`);
       },
 
       [STEPS.ACCESS_PREPARING]: () => {
-        console.log(`🌐 Step 4/4: Getting Website URL...`);
+        console.log(`🌐 Step 4/4: Getting the website URL...`);
       },
 
       [STEPS.ACCESS_READY]: async ({ appUrl, homeUrl, subscriptionUrl }) => {

package/utils/history-utils.mjs

@@ -8,7 +8,7 @@ import { isInGitRepository } from "./file-utils.mjs";
 const HISTORY_FILE = "history.yaml";
 
 /**
- * Check if git is available in the system
+ * Checks if Git is available in the system.
  */
 export function isGitAvailable() {
   try {
@@ -20,7 +20,7 @@ export function isGitAvailable() {
 }
 
 /**
- * Initialize git repo in DOC_SMITH_DIR if not exists
+ * Initializes a Git repository in the DOC_SMITH_DIR if it doesn't already exist.
  */
 export function ensureGitRepo() {
   if (!isGitAvailable()) return false;
@@ -43,10 +43,10 @@ export function ensureGitRepo() {
         stdio: "ignore",
       });
 
-      console.log("✔ Git history tracking initialized");
+      console.log("✔ Git history tracking has been initialized.");
       return true;
     } catch (error) {
-      console.warn("Failed to initialize git history:", error.message);
+      console.warn("Could not initialize the Git history:", error.message);
       return false;
     }
   }
@@ -76,10 +76,10 @@ function recordUpdateGit({ feedback }) {
     // Check if there are changes to commit
     try {
       execSync("git diff --cached --quiet", { cwd, stdio: "ignore" });
-      console.log("✔ No update history changes to commit");
-      return; // No changes
+      console.log("✔ No update history changes to commit.");
+      return;
     } catch {
-      // Has changes, continue
+      // There are changes, so we'll continue.
     }
 
     // Build commit message (only user feedback)
@@ -90,14 +90,14 @@ function recordUpdateGit({ feedback }) {
       cwd,
       stdio: "ignore",
     });
-    console.log("✔ Update history committed successfully");
+    console.log("✔ The update history has been committed successfully.");
   } catch (error) {
-    console.warn("Update history commit failed:", error.message);
+    console.warn("The update history commit failed:", error.message);
   }
 }
 
 /**
- * Record update in YAML file (always)
+ * Records an update in the YAML file.
  */
 function recordUpdateYaml({ operation, feedback, documentPath = null }) {
   try {
@@ -114,7 +114,7 @@ function recordUpdateYaml({ operation, feedback, documentPath = null }) {
         const content = readFileSync(historyPath, "utf8");
         history = parse(content) || { entries: [] };
       } catch (error) {
-        console.warn("Failed to read history file:", error.message);
+        console.warn("Could not read the history file:", error.message);
       }
     }
 
@@ -142,18 +142,18 @@ function recordUpdateYaml({ operation, feedback, documentPath = null }) {
 
     writeFileSync(historyPath, yamlContent, "utf8");
   } catch (error) {
-    console.warn("YAML history tracking failed:", error.message);
+    console.warn("The YAML history tracking failed:", error.message);
   }
 }
 
 /**
- * Record an update after user feedback
- * - Always writes to YAML
- * - Also commits to git if available
+ * Records an update after user feedback.
+ * - Always writes to YAML.
+ * - Also commits to Git if available.
  * @param {Object} params
- * @param {string} params.operation - Type of operation (e.g., 'document_update', 'structure_update', 'translation_update')
- * @param {string} params.feedback - User feedback text
- * @param {string} params.documentPath - Document path - should be a string
+ * @param {string} params.operation - The type of operation (e.g., 'document_update', 'structure_update', 'translation_update').
+ * @param {string} params.feedback - The user's feedback text.
+ * @param {string} params.documentPath - The document path.
  */
 export function recordUpdate({ operation, feedback, documentPath = null }) {
   // Skip if no feedback
@@ -167,12 +167,12 @@ export function recordUpdate({ operation, feedback, documentPath = null }) {
     ensureGitRepo();
     recordUpdateGit({ feedback });
   } else {
-    console.warn("Git is not available, skipping git based update history");
+    console.warn("Git is not available, so I am skipping the Git-based update history.");
   }
 }
 
 /**
- * Get history entries from YAML
+ * Gets the history entries from YAML.
  */
 export function getHistory() {
   const historyPath = join(process.cwd(), DOC_SMITH_DIR, HISTORY_FILE);
@@ -185,7 +185,7 @@ export function getHistory() {
     const content = readFileSync(historyPath, "utf8");
     return parse(content) || { entries: [] };
   } catch (error) {
-    console.warn("Failed to read history:", error.message);
+    console.warn("Could not read the history:", error.message);
     return { entries: [] };
   }
 }

package/utils/kroki-utils.mjs

@@ -31,7 +31,7 @@ export async function getChart({ chart = "d2", format = "svg", content, strict }
       },
     });
     if (strict && !res.ok) {
-      throw new Error(`Failed to fetch chart: ${res.status} ${res.statusText}`);
+      throw new Error(`Could not fetch the chart: ${res.status} ${res.statusText}`);
     }
 
     const data = await res.text();
@@ -39,7 +39,7 @@ export async function getChart({ chart = "d2", format = "svg", content, strict }
   } catch (err) {
     if (strict) throw err;
 
-    console.error("Failed to generate chart from:", baseUrl, err);
+    console.error(`Could not generate the chart from: ${baseUrl}`, err);
     return null;
   }
 }
@@ -54,7 +54,6 @@ export async function getD2Svg({ content, strict = false }) {
   return svgContent;
 }
 
-// Helper: save d2 svg assets alongside document
 export async function saveD2Assets({ markdown, docsDir }) {
   if (!markdown) {
     return markdown;
@@ -74,10 +73,10 @@ export async function saveD2Assets({ markdown, docsDir }) {
       const svgPath = path.join(assetDir, fileName);
 
       if (await fs.pathExists(svgPath)) {
-        debug("Found assets cache, skipping generation", svgPath);
+        debug("Asset cache found, skipping generation", svgPath);
       } else {
         try {
-          debug("Start generate d2 diagram", svgPath);
+          debug("Generating d2 diagram", svgPath);
           if (debug.enabled) {
             const d2FileName = `${getContentHash(d2Content)}.d2`;
             const d2Path = path.join(assetDir, d2FileName);
@@ -89,7 +88,7 @@ export async function saveD2Assets({ markdown, docsDir }) {
             await fs.writeFile(svgPath, svg, { encoding: "utf8" });
           }
         } catch (error) {
-          debug("Failed to generate D2 diagram:", error);
+          debug("Could not generate the D2 diagram:", error);
           return _code;
         }
       }
@@ -102,7 +101,7 @@ export async function saveD2Assets({ markdown, docsDir }) {
 }
 
 export async function beforePublishHook({ docsDir }) {
-  // Example: process each markdown file (replace with your logic)
+  // Process each markdown file to save the d2 svg assets.
   const mdFilePaths = await glob("**/*.md", { cwd: docsDir });
   await pMap(
     mdFilePaths,
@@ -158,7 +157,7 @@ export async function checkD2Content({ content }) {
   }
 
   if (await fs.pathExists(svgPath)) {
-    debug("Found assets cache, skipping generation", svgPath);
+    debug("Asset cache found, skipping generation", svgPath);
     return;
   }
 

package/utils/load-config.mjs

@@ -10,9 +10,9 @@ export default async function loadConfig({ config, appUrl }) {
     // Check if config file exists
     await fs.access(configPath);
   } catch (_error) {
-    console.log(`Config file not found: ${configPath}`);
-    console.log("Please run 'aigne doc init' to create the config file.");
-    throw new Error(`Config file not found: ${configPath}`);
+    console.log(`The config file was not found at: ${configPath}`);
+    console.log("You can run 'aigne doc init' to create a new config file.");
+    throw new Error(`The config file was not found at: ${configPath}`);
   }
 
   try {
@@ -36,7 +36,7 @@ export default async function loadConfig({ config, appUrl }) {
       ...processedConfig,
     };
   } catch (error) {
-    console.error(`Error parsing config file: ${error.message}`);
-    throw new Error(`Failed to parse config file: ${error.message}`);
+    console.error(`I encountered an error while parsing the config file: ${error.message}`);
+    throw new Error(`I could not parse the config file: ${error.message}`);
   }
 }

package/utils/upload-files.mjs

@@ -6,7 +6,7 @@ import pLimit from "p-limit";
 import pRetry from "p-retry";
 
 import { getComponentMountPoint } from "./blocklet.mjs";
-import { DISCUSS_KIT_DID } from "./constants/index.mjs";
+import { DISCUSS_KIT_DID, MEDIA_KIT_DID } from "./constants/index.mjs";
 import { getMimeType } from "./file-utils.mjs";
 
 /**
@@ -143,7 +143,7 @@ export async function uploadFiles(options) {
   }
 
   const url = new URL(appUrl);
-  const mountPoint = await getComponentMountPoint(appUrl, DISCUSS_KIT_DID);
+  const mountPoint = await getComponentMountPoint(appUrl, MEDIA_KIT_DID);
 
   // Use custom endpoint or default to discuss kit media endpoint
   const uploadEndpoint = endpoint || `${url.origin}${mountPoint}/api/uploads`;