@aigne/doc-smith 0.8.11-beta → 0.8.11-beta.2

package/utils/deploy.mjs

@@ -1,410 +1,106 @@
+import { BrokerClient, STEPS } from "@blocklet/payment-broker-client/node";
 import chalk from "chalk";
-import { joinURL } from "ufo";
-import { getComponentInfo, getComponentInfoWithMountPoint } from "./blocklet.mjs";
-import { PAYMENT_KIT_DID } from "./constants.mjs";
+import open from "open";
+import { getOfficialAccessToken } from "./auth-utils.mjs";
 import { saveValueToConfig } from "./utils.mjs";
 
-// ==================== URL Configuration ====================
+// ==================== 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: Website startup timeout (5 minutes)
+const SUCCESS_MESSAGE = {
+  en: "Congratulations! Your website has been successfully installed. You can return to the command-line tool to continue the next steps.",
+  zh: "恭喜您，你的网站已安装成功！可以返回命令行工具继续后续操作！",
 };
 
-// ==================== 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 Website and return the installation URL
- * @returns {Promise<string>} - The URL of the deployed Website
+ * @param {string} id - Cached checkout ID (optional)
+ * @param {string} cachedUrl - Cached payment URL (optional)
+ * @returns {Promise<Object>} - The deployment result with URLs
  */
 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(`⏳ Step 1/4: Waiting for payment...`);
-  console.log(`🔗 Payment link: ${chalk.cyan(paymentUrl)}\n`);
-  await pollPaymentStatus(checkoutId);
-  await saveValueToConfig("checkoutId", checkoutId, "Checkout ID for document deployment website");
-  await saveValueToConfig("paymentUrl", paymentUrl, "Payment URL for document deployment website");
-
-  // Step 3: Wait for website installation
-  console.log(`📦 Step 2/4: Installing Website...`);
-  const readyVendors = await waitInstallation(checkoutId);
-
-  // Step 4: Wait for website startup
-  console.log(`🚀 Step 3/4: Starting Website...`);
-  const runningVendors = await waitWebsiteRunning(readyVendors);
-
-  // Step 5: Get final URL
-  console.log(`🌐 Step 4/4: Getting Website URL...`);
-  const urlInfo = await getDashboardAndUrl(checkoutId, runningVendors);
-  const { appUrl, homeUrl, token, subscriptionUrl } = urlInfo || {};
-
-  console.log(`\n🔗 Your website is available at: ${chalk.cyan(homeUrl || appUrl)}`);
-
-  if (subscriptionUrl) {
-    console.log(`🔗 Your subscription management URL: ${chalk.cyan(subscriptionUrl)}\n`);
-  } else {
-    // just log one space line
-    console.log("");
-  }
-
-  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) {
-    await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment website");
-    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;
+  const authToken = await getOfficialAccessToken(BASE_URL);
 
-    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}`);
+  if (!authToken) {
+    throw new Error("Failed to get official access token");
   }
-}
-
-/**
- * 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
+  const client = new BrokerClient({
+    baseUrl: BASE_URL,
+    authToken,
+    paymentLinkKey: "PAYMENT_LINK_ID",
+    timeout: 300000,
+    polling: {
+      interval: 3000,
+      maxAttempts: 100,
+      backoffStrategy: "linear",
     },
-    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();
+  console.log(`🚀 Starting deployment...`);
 
-      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
+  const result = await client.deploy({
+    cachedCheckoutId: id,
+    cachedPaymentUrl: cachedUrl,
+    pageInfo: {
+      successMessage: SUCCESS_MESSAGE,
     },
-    maxAttempts: Math.ceil((TIMEOUTS.installation * 1000) / INTERVAL_MS),
-    intervalMs: INTERVAL_MS,
-    timeoutMessage: "Installation timeout - website failed to install within 5 minutes",
-    stepName: "Installation",
-  });
-}
-
-/**
- * Wait for Website to start running - Step 4
- */
-async function waitWebsiteRunning(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;
+    hooks: {
+      [STEPS.PAYMENT_PENDING]: async ({ sessionId, paymentUrl, isResuming }) => {
+        console.log(`⏳ Step 1/4: Waiting for payment...`);
+        console.log(`🔗 Payment link: ${chalk.cyan(paymentUrl)}\n`);
+
+        await saveValueToConfig(
+          "checkoutId",
+          sessionId,
+          "Checkout ID for document deployment website",
+        );
+        await saveValueToConfig(
+          "paymentUrl",
+          paymentUrl,
+          "Payment URL for document deployment website",
+        );
+
+        if (!isResuming) {
+          await open(paymentUrl);
         }
-      });
-
-      const results = await Promise.all(vendorChecks);
-      const runningVendors = results.filter((vendor) => vendor !== null);
-
-      if (runningVendors.length === readyVendors.length) {
-        return runningVendors;
-      }
+      },
+
+      [STEPS.INSTALLATION_STARTING]: () => {
+        console.log(`📦 Step 2/4: Installing Website...`);
+      },
+
+      [STEPS.SERVICE_STARTING]: () => {
+        console.log(`🚀 Step 3/4: Starting Website...`);
+      },
+
+      [STEPS.ACCESS_PREPARING]: () => {
+        console.log(`🌐 Step 4/4: Getting Website URL...`);
+      },
+
+      [STEPS.ACCESS_READY]: async ({ appUrl, homeUrl, subscriptionUrl }) => {
+        console.log(`\n🔗 Your website is available at: ${chalk.cyan(homeUrl || appUrl)}`);
+        if (subscriptionUrl) {
+          console.log(`🔗 Your subscription management URL: ${chalk.cyan(subscriptionUrl)}\n`);
+        } else {
+          console.log("");
+        }
+      },
+    },
 
-      return null; // Not ready yet, continue polling
+    onError: (error, step) => {
+      console.error(`${chalk.red("❌")} Deployment failed at ${step || "unknown step"}:`);
+      console.error(`   ${error.message}`);
     },
-    maxAttempts: Math.ceil((TIMEOUTS.serviceStart * 1000) / INTERVAL_MS),
-    intervalMs: INTERVAL_MS,
-    timeoutMessage: "Website start timeout - website failed to start within 5 minutes",
-    stepName: "Website 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");
-    }
+  const { appUrl, homeUrl, subscriptionUrl, dashboardUrl, vendors } = result;
+  const token = vendors?.[0]?.token;
 
-    // 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,
-      subscriptionUrl: data.subscriptionUrl,
-      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,
-    };
-  }
+  return {
+    appUrl,
+    homeUrl,
+    dashboardUrl,
+    subscriptionUrl,
+    token,
+  };
 }
-
-export default deploy;

package/utils/evaluate/report-utils.mjs

@@ -0,0 +1,131 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { toRelativePath } from "../utils.mjs";
+
+/**
+ * Create report structure with evaluation data
+ * @param {Object} params - Parameters for creating the report
+ * @param {string} params.timestamp - Report generation timestamp
+ * @param {Object} params.metadata - Additional metadata for the report
+ * @param {Object} params.structureEvaluation - Structure evaluation results
+ * @param {Array} params.documentEvaluations - Individual document evaluations
+ * @param {string} params.projectName - Name of the project
+ * @param {string} params.projectDesc - Project description
+ * @param {string} params.projectLogo - Project logo URL
+ * @param {string} params.documentPurpose - Purpose of the documentation
+ * @param {Array} params.targetAudienceTypes - Types of target audience
+ * @param {string} params.readerKnowledgeLevel - Expected reader knowledge level
+ * @param {string} params.documentationDepth - Depth of documentation
+ * @param {string} params.targetAudience - Target audience description
+ * @returns {Object} Complete report structure
+ */
+export function createReportStructure({
+  timestamp,
+  metadata,
+  structureEvaluation,
+  documentEvaluations,
+  projectName,
+  projectDesc,
+  projectLogo,
+  documentPurpose,
+  targetAudienceTypes,
+  readerKnowledgeLevel,
+  documentationDepth,
+  targetAudience,
+}) {
+  return {
+    documentInfo: {
+      projectName,
+      projectDesc,
+      projectLogo,
+      documentPurpose,
+      targetAudienceTypes,
+      readerKnowledgeLevel,
+      documentationDepth,
+      targetAudience,
+    },
+    metadata: {
+      version: "0.1.0",
+      generatedBy: "AIGNE Doc Smith",
+      generatedAt: timestamp,
+      documentCount: documentEvaluations.length,
+      ...metadata,
+    },
+    structureEvaluation: {
+      type: "document-structure",
+      results: structureEvaluation,
+    },
+    documentEvaluations: {
+      type: "document-content",
+      results: documentEvaluations,
+    },
+  };
+}
+
+/**
+ * Ensure directory exists, create if it doesn't
+ * @param {string} dirPath - Directory path to ensure exists
+ */
+export async function ensureDirectoryExists(dirPath) {
+  if (!existsSync(dirPath)) {
+    await mkdir(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Generate timestamp formatted for folder names
+ * @param {Date} [date] - Date object, defaults to current date
+ * @returns {string} Formatted timestamp string
+ */
+export function generateTimestampForFolder(date = new Date()) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+
+  return `${year}-${month}-${day}_${hours}-${minutes}`;
+}
+
+/**
+ * Copy HTML report template to the report directory
+ * @param {string} targetDir - Target directory for the HTML report
+ * @returns {Promise<string>} Path to the copied HTML file
+ */
+export async function copyHtmlReportTemplate(targetDir, data) {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+
+  // Path to the HTML template
+  const templatePath = join(__dirname, "../../", "assets", "report-template", "report.html");
+  const targetPath = join(targetDir, "integrity-report.html");
+
+  const templateReport = await readFile(templatePath, "utf-8");
+  const templateData = templateReport.replace("window.__REPORT_DATA__", JSON.stringify(data));
+  await writeFile(targetPath, templateData);
+  return toRelativePath(targetPath);
+}
+
+/**
+ * Generate success message with report links
+ * @param {string} jsonReportPath - Path to the JSON report
+ * @param {string} htmlReportPath - Path to the HTML report
+ * @returns {string} Success message with links
+ */
+export function generateReportSuccessMessage(jsonReportPath, htmlReportPath) {
+  return `# ✅ Documentation Evaluation Report Generated Successfully!
+
+Generated evaluation report and saved to:
+
+\`${jsonReportPath}\`
+
+## 📊 View HTML Report
+
+Open in your browser to view detailed analysis:
+
+\`${htmlReportPath}\`
+
+`;
+}

package/utils/file-utils.mjs

@@ -1,5 +1,5 @@
 import { execSync } from "node:child_process";
-import { access, readFile } from "node:fs/promises";
+import { access, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { glob } from "glob";
 
@@ -208,3 +208,38 @@ export async function getFilesWithGlob(dir, includePatterns, excludePatterns, gi
     return [];
   }
 }
+
+/**
+ * Check if a path exists
+ * @param {string} targetPath - Path to check
+ * @returns {Promise<boolean>} True if path exists
+ */
+export async function pathExists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/**
+ * Convert absolute path to display path relative to current working directory
+ * @param {string} targetPath - Absolute path to convert
+ * @returns {string} Display path (relative or absolute)
+ */
+export function toDisplayPath(targetPath) {
+  const rel = path.relative(process.cwd(), targetPath);
+  return rel.startsWith("..") ? targetPath : rel || ".";
+}
+
+/**
+ * Resolve path to absolute path
+ * @param {string} value - Path to resolve
+ * @returns {string|undefined} Absolute path or undefined if no value provided
+ */
+export function resolveToAbsolute(value) {
+  if (!value) return undefined;
+  return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
+}

package/utils/kroki-utils.mjs

@@ -12,7 +12,7 @@ import {
   KROKI_CONCURRENCY,
   TMP_ASSETS_DIR,
   TMP_DIR,
-} from "./constants.mjs";
+} from "./constants/index.mjs";
 import { getContentHash } from "./utils.mjs";
 
 const debug = Debug("doc-smith");