@aigne/doc-smith 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.4...v0.8.5) (2025-09-10)
+
+
+### Features
+
+* support publish docs to enterprise spaces ([#82](https://github.com/AIGNE-io/aigne-doc-smith/issues/82)) ([35b577a](https://github.com/AIGNE-io/aigne-doc-smith/commit/35b577ac0f2c1b860a23185054a55bada3742e8e))
+
+
+### Miscellaneous Chores
+
+* release 0.8.5 ([7a60a03](https://github.com/AIGNE-io/aigne-doc-smith/commit/7a60a03f91a20f378e94b12dd32a6a8b0a4bede5))
+
 ## [0.8.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.3...v0.8.4) (2025-09-09)
 
 

package/agents/input-generator.mjs

@@ -385,12 +385,18 @@ export function generateYAML(input) {
   // Generate comments and structure
   let yaml = "# Project information for documentation publishing\n";
 
-  // Serialize the project info section safely
-  const projectSection = yamlStringify({
-    projectName: config.projectName,
-    projectDesc: config.projectDesc,
-    projectLogo: config.projectLogo,
-  }).trim();
+  // Serialize the project info section safely with string quoting
+  const projectSection = yamlStringify(
+    {
+      projectName: config.projectName,
+      projectDesc: config.projectDesc,
+      projectLogo: config.projectLogo,
+    },
+    {
+      quotingType: '"',
+      defaultStringType: "QUOTE_DOUBLE",
+    },
+  ).trim();
 
   yaml += `${projectSection}\n\n`;
 

package/agents/publish-docs.mjs

@@ -5,6 +5,7 @@ import fs from "fs-extra";
 
 import { getAccessToken } from "../utils/auth-utils.mjs";
 import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../utils/constants.mjs";
+import { deploy } from "../utils/deploy.mjs";
 import { beforePublishHook, ensureTmpDir } from "../utils/kroki-utils.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
@@ -17,6 +18,8 @@ export default async function publishDocs(
   // move work dir to tmp-dir
   await ensureTmpDir();
 
+  const hasDocSmithBaseUrl = !!process.env.DOC_SMITH_BASE_URL;
+
   const docsDir = join(".aigne", "doc-smith", TMP_DIR, TMP_DOCS_DIR);
   await fs.rm(docsDir, { recursive: true, force: true });
   await fs.mkdir(docsDir, {
@@ -42,18 +45,41 @@ export default async function publishDocs(
   const isDefaultAppUrl = appUrl === DEFAULT_APP_URL;
   const hasAppUrlInConfig = config?.appUrl;
 
+  let token = "";
+
   if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
+    const hasCachedCheckoutId = !!config?.checkoutId;
     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",
+          name:
+            chalk.blue("Publish to docsmith.aigne.io") +
+            " - free, but your documents will be publicly accessible, recommended for open-source projects",
           value: "default",
         },
         {
-          name: "Publish to your own website - you will need to run Discuss Kit by your self ",
+          name: `${chalk.blue("Publish to your existing website")} - use your current website`,
           value: "custom",
         },
+        ...(hasCachedCheckoutId && hasDocSmithBaseUrl
+          ? [
+              {
+                name:
+                  chalk.yellow("Continue your previous website setup") +
+                  " - resume from where you left off",
+                value: "new-instance-continue",
+              },
+            ]
+          : []),
+        ...(hasDocSmithBaseUrl
+          ? [
+              {
+                name: `${chalk.blue("Publish to a new website")} - we'll help you set up a new website`,
+                value: "new-instance",
+              },
+            ]
+          : []),
       ],
     });
 
@@ -63,7 +89,7 @@ export default async function publishDocs(
           `Start here to run your own website:\n${chalk.cyan(DISCUSS_KIT_STORE_URL)}\n`,
       );
       const userInput = await options.prompts.input({
-        message: "Please enter your Discuss Kit platform URL:",
+        message: "Please enter your website URL:",
         validate: (input) => {
           try {
             // Check if input contains protocol, if not, prepend https://
@@ -77,10 +103,31 @@ export default async function publishDocs(
       });
       // Ensure appUrl has protocol
       appUrl = userInput.includes("://") ? userInput : `https://${userInput}`;
+    } else if (hasDocSmithBaseUrl && ["new-instance", "new-instance-continue"].includes(choice)) {
+      // Deploy a new Discuss Kit service
+      try {
+        let id = "";
+        let paymentUrl = "";
+        if (choice === "new-instance-continue") {
+          id = config?.checkoutId;
+          paymentUrl = config?.paymentUrl;
+          console.log(`\nResuming your previous website setup...`);
+        } else {
+          console.log(`\nCreating a new doc website for your documentation...`);
+        }
+        const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentUrl)) || {};
+
+        appUrl = homeUrl;
+        token = ltToken;
+      } catch (error) {
+        const errorMsg = error?.message || "Unknown error occurred";
+        console.error(`${chalk.red("❌ Failed to publish to website:")} ${errorMsg}`);
+        return { message: `❌ Publish failed: ${errorMsg}` };
+      }
     }
   }
 
-  const accessToken = await getAccessToken(appUrl);
+  const accessToken = await getAccessToken(appUrl, token);
 
   process.env.DOC_ROOT_DIR = docsDir;
 
@@ -138,6 +185,8 @@ export default async function publishDocs(
   } catch (error) {
     message = `❌ Failed to publish docs: ${error.message}`;
   }
+  saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+
   // clean up tmp work dir
   await fs.rm(docsDir, { recursive: true, force: true });
   return message ? { message } : {};

package/docs/_sidebar.md

@@ -14,4 +14,4 @@
 * [Advanced Topics](/advanced.md)
   * [How It Works](/advanced-how-it-works.md)
   * [Quality Assurance](/advanced-quality-assurance.md)
-* [Changelog](/changelog.md)
+* [Changelog](/changelog.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "",
   "publishConfig": {
     "access": "public"

package/tests/input-generator.test.mjs

@@ -913,7 +913,7 @@ describe("generateYAML", () => {
         // Should always include these sections
         expect(result).toContain("# Project information for documentation publishing");
         expect(result).toContain("# Documentation Configuration");
-        expect(result).toContain("projectName:");
+        expect(result).toContain('"projectName":');
         expect(result).toContain("documentPurpose:");
         expect(result).toContain("targetAudienceTypes:");
         expect(result).toContain("locale:");
@@ -1287,7 +1287,7 @@ describe("init", () => {
 
         // Config should be generated since original was empty
         const configContent = await fs.readFile(configPath, "utf8");
-        expect(configContent).toContain("projectName:");
+        expect(configContent).toContain('"projectName":');
         expect(configContent).toContain("locale: en");
       } finally {
         await cleanupTempDir(tempDir);

package/utils/auth-utils.mjs

@@ -25,7 +25,7 @@ const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
  * @param {string} appUrl - The application URL
  * @returns {Promise<string>} - The access token
  */
-export async function getAccessToken(appUrl) {
+export async function getAccessToken(appUrl, ltToken = "") {
   const DOC_SMITH_ENV_FILE = join(homedir(), ".aigne", "doc-smith-connected.yaml");
   const { hostname } = new URL(appUrl);
 
@@ -92,7 +92,14 @@ export async function getAccessToken(appUrl) {
       closeOnSuccess: true,
       appName: "AIGNE DocSmith",
       appLogo: "https://docsmith.aigne.io/image-bin/uploads/a7910a71364ee15a27e86f869ad59009.svg",
-      openPage: (pageUrl) => open(pageUrl),
+      openPage: (pageUrl) => {
+        const url = new URL(pageUrl);
+        if (ltToken) {
+          url.searchParams.set("__lt", ltToken);
+        }
+
+        open(url.toString());
+      },
     });
 
     accessToken = result.accessKeySecret;

package/utils/blocklet.mjs

@@ -1,3 +1,5 @@
+import { joinURL } from "ufo";
+
 /**
  * Custom error class for invalid blocklet application URLs
  */
@@ -23,17 +25,14 @@ export class ComponentNotFoundError extends Error {
   }
 }
 
-export async function getComponentMountPoint(appUrl, did) {
-  const url = new URL(appUrl);
-  const blockletJsUrl = `${url.origin}/__blocklet__.js?type=json`;
+export async function getComponentInfo(appUrl) {
+  const blockletJsUrl = joinURL(appUrl, "__blocklet__.js?type=json");
 
   let blockletJs;
   try {
     blockletJs = await fetch(blockletJsUrl, {
       method: "GET",
-      headers: {
-        Accept: "application/json",
-      },
+      headers: { Accept: "application/json" },
     });
   } catch (error) {
     throw new InvalidBlockletError(appUrl, null, error.message);
@@ -50,6 +49,12 @@ export async function getComponentMountPoint(appUrl, did) {
     throw new InvalidBlockletError(appUrl, null, "Invalid JSON response");
   }
 
+  return config;
+}
+
+export async function getComponentMountPoint(appUrl, did) {
+  const config = await getComponentInfo(appUrl);
+
   const component = config.componentMountPoints?.find((component) => component.did === did);
   if (!component) {
     throw new ComponentNotFoundError(did, appUrl);
@@ -57,3 +62,17 @@ export async function getComponentMountPoint(appUrl, did) {
 
   return component.mountPoint;
 }
+
+export async function getComponentInfoWithMountPoint(appUrl, did) {
+  const config = await getComponentInfo(appUrl);
+
+  const component = config.componentMountPoints?.find((component) => component.did === did);
+  if (!component) {
+    throw new ComponentNotFoundError(did, appUrl);
+  }
+
+  return {
+    ...config,
+    mountPoint: component.mountPoint,
+  };
+}

package/utils/constants.mjs

@@ -330,6 +330,8 @@ export const DEPTH_RECOMMENDATION_LOGIC = {
 // Component mount point ID for Discuss Kit
 export const DISCUSS_KIT_DID = "z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";
 
+export const PAYMENT_KIT_DID = "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk";
+
 // Discuss Kit related URLs
 export const DISCUSS_KIT_STORE_URL =
   "https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu";

package/utils/deploy.mjs

@@ -0,0 +1,404 @@
+import chalk from "chalk";
+import { joinURL } from "ufo";
+import { getComponentInfo, getComponentInfoWithMountPoint } from "./blocklet.mjs";
+import { PAYMENT_KIT_DID } from "./constants.mjs";
+import { saveValueToConfig } from "./utils.mjs";
+
+// ==================== URL Configuration ====================
+const BASE_URL = process.env.DOC_SMITH_BASE_URL || "";
+
+// ==================== Timeout Configuration ====================
+const INTERVAL_MS = 3000; // 3 seconds between each check
+const TIMEOUTS = {
+  paymentWait: 300, // Step 2: Payment wait timeout (5 minutes)
+  installation: 300, // Step 3: Installation timeout (5 minutes)
+  serviceStart: 300, // Step 4: Service startup timeout (5 minutes)
+};
+
+// ==================== Utility Functions ====================
+
+/**
+ * Generic polling utility with timeout and retry logic
+ * @param {Object} options - Polling configuration
+ * @param {Function} options.checkCondition - Async function that returns result if condition met, null/false if not
+ * @param {number} options.maxAttempts - Maximum number of attempts
+ * @param {number} options.intervalMs - Interval between attempts in milliseconds
+ * @param {string} options.timeoutMessage - Error message for timeout
+ * @param {string} options.stepName - Name of the step for logging (optional)
+ * @returns {Promise<any>} Result from checkCondition when successful
+ */
+async function pollWithTimeout({
+  checkCondition,
+  maxAttempts,
+  intervalMs = INTERVAL_MS,
+  timeoutMessage,
+  stepName = "Operation",
+}) {
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    attempts++;
+
+    try {
+      const result = await checkCondition();
+      if (result !== null && result !== false) {
+        return result;
+      }
+    } catch (_error) {
+      // Log error for debugging but continue retrying unless it's the last attempt
+      if (attempts === maxAttempts) {
+        throw new Error(`${timeoutMessage} (${stepName} failed after ${maxAttempts} attempts)`);
+      }
+      // Continue retrying for non-fatal errors
+    }
+
+    // If this is the last attempt, don't wait - just exit the loop
+    if (attempts === maxAttempts) {
+      break;
+    }
+
+    // Wait before retry
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  // If we reach here, all attempts were exhausted
+  throw new Error(`${timeoutMessage} (${stepName} timed out after ${maxAttempts} attempts)`);
+}
+
+// ==================== API Endpoints ====================
+const API_ENDPOINTS = {
+  createCheckout: `/api/checkout-sessions/start`,
+  paymentPage: `/checkout/pay/{id}`,
+  orderStatus: `/api/vendors/order/{id}/status`,
+  orderDetail: `/api/vendors/order/{id}/detail`,
+};
+
+let prefix = "";
+let paymentLinkId = "";
+/**
+ * Deploy a new Discuss Kit service and return the installation URL
+ * @returns {Promise<string>} - The URL of the deployed service
+ */
+export async function deploy(id, cachedUrl) {
+  const { mountPoint, PAYMENT_LINK_ID } = await getComponentInfoWithMountPoint(
+    BASE_URL,
+    PAYMENT_KIT_DID,
+  );
+  prefix = mountPoint;
+  paymentLinkId = PAYMENT_LINK_ID;
+
+  if (!PAYMENT_LINK_ID) {
+    const { PAYMENT_LINK_ID: id } = await getComponentInfoWithMountPoint(
+      joinURL(BASE_URL, mountPoint),
+      PAYMENT_KIT_DID,
+    );
+    paymentLinkId = id;
+  }
+
+  // Step 1: Create payment link and open
+  const cachedCheckoutId = await checkCacheCheckoutId(id);
+  let checkoutId = cachedCheckoutId;
+  let paymentUrl = cachedUrl;
+  if (!cachedCheckoutId) {
+    const { checkoutId: newCheckoutId, paymentUrl: newPaymentUrl } = await createPaymentSession();
+    checkoutId = newCheckoutId;
+    paymentUrl = newPaymentUrl;
+  }
+
+  if (!paymentUrl) {
+    paymentUrl = joinURL(BASE_URL, prefix, API_ENDPOINTS.paymentPage.replace("{id}", checkoutId));
+  }
+  if (cachedCheckoutId !== checkoutId) {
+    await openBrowser(paymentUrl);
+  }
+
+  // Step 2: Wait for payment completion
+  console.log(`${chalk.blue("⏳")} Step 1/4: Waiting for payment...`);
+  console.log(`${chalk.blue("🔗")} Payment link: ${chalk.cyan(paymentUrl)}\n`);
+  await pollPaymentStatus(checkoutId);
+  saveValueToConfig("checkoutId", checkoutId, "Checkout ID for document deployment service");
+  saveValueToConfig("paymentUrl", paymentUrl, "Payment URL for document deployment service");
+
+  // Step 3: Wait for service installation
+  console.log(`${chalk.blue("📦")} Step 2/4: Installing service...`);
+  const readyVendors = await waitInstallation(checkoutId);
+
+  // Step 4: Wait for service startup
+  console.log(`${chalk.blue("🚀")} Step 3/4: Starting service...`);
+  const runningVendors = await waitServiceRunning(readyVendors);
+
+  // Step 5: Get final URL
+  console.log(`${chalk.blue("🌐")} Step 4/4: Getting service URL...`);
+  const urlInfo = await getDashboardAndUrl(checkoutId, runningVendors);
+  const { appUrl, homeUrl, token } = urlInfo || {};
+
+  console.log(
+    `\n${chalk.blue("🔗")} Your website is available at: ${chalk.cyan(homeUrl || appUrl)}\n`,
+  );
+
+  return {
+    appUrl,
+    homeUrl,
+    token,
+  };
+}
+
+/**
+ * Check if there is a cached checkoutId
+ */
+async function checkCacheCheckoutId(checkoutId) {
+  try {
+    if (!checkoutId) {
+      return "";
+    }
+
+    const orderStatusUrl = joinURL(
+      BASE_URL,
+      prefix,
+      API_ENDPOINTS.orderStatus.replace("{id}", checkoutId),
+    );
+    const response = await fetch(orderStatusUrl);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    if (data.error) {
+      throw new Error(data.error);
+    }
+
+    // Check payment status and vendors status
+    const isPaid = data.payment_status === "paid";
+
+    return isPaid ? checkoutId : "";
+  } catch (_error) {
+    saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+    return "";
+  }
+}
+
+/**
+ * Create payment session - Step 1
+ */
+async function createPaymentSession() {
+  // 1. Call payment API
+  if (!paymentLinkId) {
+    throw new Error("Payment link ID not found");
+  }
+
+  const createCheckoutId = joinURL(BASE_URL, prefix, API_ENDPOINTS.createCheckout, paymentLinkId);
+  try {
+    const response = await fetch(createCheckoutId, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        needShortUrl: true,
+        metadata: {
+          page_info: {
+            has_vendor: true,
+            success_message: {
+              en: "Congratulations! Your website has been successfully installed. You can return to the command-line tool to continue the next steps.",
+              zh: "恭喜您，你的网站已安装成功！可以返回命令行工具继续后续操作！",
+            },
+          },
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const data = await response.json();
+    const checkoutId = data.checkoutSession.id;
+    const paymentUrl = data.paymentUrl;
+
+    return { checkoutId, paymentUrl };
+  } catch (error) {
+    console.error(
+      `${chalk.red("❌")} Failed to create payment session:`,
+      error.message,
+      createCheckoutId,
+    );
+    throw new Error(`Failed to create payment session: ${error.message}`);
+  }
+}
+
+/**
+ * Open browser with payment URL
+ */
+async function openBrowser(paymentUrl) {
+  const { default: open } = await import("open");
+  try {
+    await open(paymentUrl);
+  } catch (_error) {
+    console.log(`${chalk.yellow("⚠️  Could not open browser automatically.")}`);
+    console.log(`${chalk.blue("Please manually open this URL:")} ${chalk.cyan(paymentUrl)}`);
+  }
+}
+
+/**
+ * Wait for payment completion - Step 2 (5 minute timeout)
+ */
+async function pollPaymentStatus(checkoutId) {
+  return pollWithTimeout({
+    checkCondition: async () => {
+      const orderStatusUrl = joinURL(
+        BASE_URL,
+        prefix,
+        API_ENDPOINTS.orderStatus.replace("{id}", checkoutId),
+      );
+      const response = await fetch(orderStatusUrl);
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+
+      if (data.error) {
+        throw new Error(data.error);
+      }
+
+      // Check payment status and vendors status
+      const isPaid = data.payment_status === "paid";
+      if (isPaid) {
+        return data.vendors;
+      }
+
+      return null; // Not ready yet, continue polling
+    },
+    maxAttempts: Math.ceil((TIMEOUTS.paymentWait * 1000) / INTERVAL_MS),
+    intervalMs: INTERVAL_MS,
+    timeoutMessage: "Payment timeout - please complete payment within 5 minutes",
+    stepName: "Payment",
+  });
+}
+
+/**
+ * Wait for installation completion - Step 3
+ */
+async function waitInstallation(checkoutId) {
+  return pollWithTimeout({
+    checkCondition: async () => {
+      const orderStatusUrl = joinURL(
+        BASE_URL,
+        prefix,
+        API_ENDPOINTS.orderStatus.replace("{id}", checkoutId),
+      );
+      const response = await fetch(orderStatusUrl);
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+
+      if (data.error) {
+        throw new Error(data.error);
+      }
+
+      // Check if all vendors meet conditions: progress >= 80 and appUrl exists
+      const isInstalled = data.vendors?.every((vendor) => vendor.progress >= 80 && vendor.appUrl);
+      if (isInstalled) {
+        return data.vendors;
+      }
+
+      return null; // Not ready yet, continue polling
+    },
+    maxAttempts: Math.ceil((TIMEOUTS.installation * 1000) / INTERVAL_MS),
+    intervalMs: INTERVAL_MS,
+    timeoutMessage: "Installation timeout - services failed to install within 5 minutes",
+    stepName: "Installation",
+  });
+}
+
+/**
+ * Wait for service to start running - Step 4
+ */
+async function waitServiceRunning(readyVendors) {
+  return pollWithTimeout({
+    checkCondition: async () => {
+      // Check running status of all vendors concurrently
+      const vendorChecks = readyVendors.map(async (vendor) => {
+        try {
+          const blockletInfo = await getComponentInfo(vendor.appUrl);
+
+          if (blockletInfo.status === "running") {
+            return vendor;
+          }
+          return null;
+        } catch (_error) {
+          return null;
+        }
+      });
+
+      const results = await Promise.all(vendorChecks);
+      const runningVendors = results.filter((vendor) => vendor !== null);
+
+      if (runningVendors.length === readyVendors.length) {
+        return runningVendors;
+      }
+
+      return null; // Not ready yet, continue polling
+    },
+    maxAttempts: Math.ceil((TIMEOUTS.serviceStart * 1000) / INTERVAL_MS),
+    intervalMs: INTERVAL_MS,
+    timeoutMessage: "Service start timeout - services failed to start within 5 minutes",
+    stepName: "Service Start",
+  });
+}
+
+/**
+ * Get final URL - Step 5
+ */
+async function getDashboardAndUrl(checkoutId, runningVendors) {
+  try {
+    // 5. Get order details
+    const orderDetailUrl = joinURL(
+      BASE_URL,
+      prefix,
+      API_ENDPOINTS.orderDetail.replace("{id}", checkoutId),
+    );
+    const response = await fetch(orderDetailUrl);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    if (data.vendors.length === 0) {
+      throw new Error("No vendors found in order details");
+    }
+
+    // Wait 3 seconds
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    // Return the appUrl of the first vendor (usually only one)
+    const appUrl = runningVendors[0]?.appUrl;
+    if (!appUrl) {
+      throw new Error("No app URL found in order details");
+    }
+
+    return {
+      appUrl,
+      dashboardUrl: data.vendors[0]?.dashboardUrl,
+      homeUrl: data.vendors[0]?.homeUrl,
+      token: data.vendors[0]?.token,
+    };
+  } catch (error) {
+    console.error(`${chalk.red("❌")} Failed to get order details:`, error.message);
+    // If getting details fails, use the appUrl of running vendor
+    return {
+      appUrl: runningVendors[0]?.appUrl || null,
+      dashboardUrl: runningVendors[0]?.dashboardUrl || null,
+      homeUrl: runningVendors[0]?.homeUrl || null,
+      token: runningVendors[0]?.token || null,
+    };
+  }
+}
+
+export default deploy;