@aigne/doc-smith 0.8.4 → 0.8.6

package/agents/structure-planning.yaml

@@ -1,5 +1,5 @@
 name: structurePlanGenerator
-description: 通用结构规划生成器，支持网站、文档、书籍、演示文稿等多种场景
+description: Plan the structure and organization of your documentation
 instructions:
   url: ../prompts/structure-planning.md
 input_schema:
@@ -7,31 +7,31 @@ input_schema:
   properties:
     rules:
       type: string
-      description: 用户的结构规划的要求
+      description: Your specific requirements for documentation structure
     locale:
       type: string
-      description: 用户语言，如 zh、en
+      description: Primary language for documentation (e.g., zh, en, ja)
     datasources:
       type: string
-      description: 结构规划的上下文，用于辅助结构规划
+      description: Project content and context to help plan structure
     targetAudience:
       type: string
-      description: 结构规划的目标受众
+      description: Target audience for the documentation
     nodeName:
       type: string
-      description: 结构规划的节点名称
+      description: Specific section or page name to focus on
     glossary:
       type: string
-      description: 术语表
+      description: Glossary for consistent terminology
     feedback:
       type: string
-      description: 结构规划的反馈
+      description: Tell us how to improve the documentation structure
     userPreferences:
       type: string
-      description: 用户偏好规则，YAML格式的结构规划和全局范围偏好
+      description: Your saved preferences for structure and documentation style
     docsType:
       type: string
-      description: 文档类型，支持：general、getting-started、reference、faq
+      description: "Documentation type (options: general, getting-started, reference, faq)"
       default: general
   required:
     - rules
@@ -41,18 +41,18 @@ output_schema:
   properties:
     projectName:
       type: string
-      description: 根据 DataSources 分析项目名称，注意是原始项目名称
+      description: Project name identified from your content sources
     projectDesc:
       type: string
-      description: 根据 DataSources 分析生成当前项目描述，为原始项目生成描述，描述简洁，不超过 50 个单词
+      description: Brief project description generated from content analysis (under 50 words)
     structurePlan: ./schema/structure-plan.yaml
     structurePlanTree:
       type: string
       description: |
-        结构规划的树形结构，用于展示结构规划的层级关系，每一级有不同的缩进，方便用户直观查看结构规划的层级关系,参考格式：
+        Visual tree structure showing documentation hierarchy with indented levels for easy review:
         ```
-        - 首页
-          - 产品
-            - 产品详情
-              - 产品介绍
+        - Home
+          - Getting Started
+            - Installation
+              - Requirements
         ```

package/agents/team-publish-docs.yaml

@@ -3,7 +3,7 @@ name: publish
 alias:
   - pub
   - p
-description: Publish the documentation to Discuss Kit
+description: Publish your documentation online
 skills:
   - url: ./input-generator.mjs
     default_input:
@@ -15,4 +15,4 @@ input_schema:
   properties:
     appUrl:
       type: string
-      description: target website URL where the documentation will be published (optional - if not provided, will prompt for interactive input)
+      description: Website URL where docs will be published (optional - leave empty for interactive setup)

package/agents/translate.yaml

@@ -1,5 +1,5 @@
 name: translateDoc
-description: Translate the wiki article to another language
+description: Translate content to another language
 instructions:
   url: ../prompts/translator.md
 input_schema:
@@ -7,16 +7,16 @@ input_schema:
   properties:
     language:
       type: string
-      description: Language to translate the article into (e.g., 'zh_CN' for Chinese)
+      description: Target language (e.g., 'zh' for Chinese, 'ja' for Japanese)
     content:
       type: string
-      description: Content to translate
+      description: Text content to translate
     glossary:
       type: string
-      description: 术语表
+      description: Glossary for consistent terminology
     feedback:
       type: string
-      description: Feedback for translation improvement
+      description: Tell us how to improve the translation style
   required:
     - language
     - content
@@ -25,7 +25,7 @@ output_schema:
   properties:
     translation:
       type: string
-      description: Translation of the content
+      description: Translated text
     language:
       type: string
-      description: Language of the translation
+      description: Language code of the translation

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/docs/cli-reference.md

@@ -89,7 +89,7 @@ Analyzes your source code and generates a complete set of documentation based on
 
 | Option | Type | Description |
 |---|---|---|
-| `--feedback` | string | Provides feedback to adjust and refine the overall document structure plan. |
+| `--feedback` | string | Provides feedback to adjust and refine the overall documentation structure. |
 | `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch. |
 | `--model` | string | Specifies a particular LLM to use for generation (e.g., `openai:gpt-4o`). Overrides the default model. |
 | `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |

package/docs/features-generate-documentation.md

@@ -90,7 +90,7 @@ While the default `generate` command is sufficient for most use cases, you can u
 | Option              | Description                                                                                                                              | Example                                                              |
 |---------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
 | `--forceRegenerate` | Deletes all existing documents and regenerates them from scratch. Use this after making significant changes to your source code or configuration. | `aigne doc generate --forceRegenerate`                                 |
-| `--feedback`        | Provides high-level feedback to refine the overall document structure plan, such as adding, removing, or reorganizing sections.           | `aigne doc generate --feedback "Add an API Reference section"`         |
+| `--feedback`        | Provides high-level feedback to refine the overall documentation structure, such as adding, removing, or reorganizing sections.           | `aigne doc generate --feedback "Add an API Reference section"`         |
 | `--model`           | Specifies a particular Large Language Model from AIGNE Hub to use for content generation, allowing you to switch between models.       | `aigne doc generate --model claude:claude-3-5-sonnet`                |
 
 ## What's Next?

package/docs/features-update-and-refine.md

@@ -123,12 +123,12 @@ Key parameters for the `update` command:
 
 ## Optimizing the Overall Structure
 
-Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to the structure planning agent using the `generate` command with the `--feedback` flag.
+Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to improve the documentation structure using the `generate` command with the `--feedback` flag.
 
 This command instructs DocSmith to reconsider the entire document plan based on your new input.
 
 ```bash
-# Regenerate the structure plan with specific feedback
+# Regenerate the documentation structure with specific feedback
 aigne doc generate --feedback "Remove the 'About' section and add a more detailed 'API Reference'."
 ```
 

package/package.json

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

package/tests/deploy.test.mjs

@@ -0,0 +1,376 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
+
+// Create mock functions for blocklet module only
+const mockGetComponentInfoWithMountPoint = mock();
+const mockGetComponentInfo = mock();
+
+// Mock only the blocklet module globally (it's safe as it's specific to this functionality)
+mock.module("../utils/blocklet.mjs", () => ({
+  getComponentInfoWithMountPoint: mockGetComponentInfoWithMountPoint,
+  getComponentInfo: mockGetComponentInfo,
+}));
+
+// Mock the open module to prevent opening browser during tests
+const mockOpenDefault = mock(() => Promise.resolve());
+mock.module("open", () => ({
+  default: mockOpenDefault,
+}));
+
+// Import the real utils module and deploy function
+import { deploy } from "../utils/deploy.mjs";
+import * as utils from "../utils/utils.mjs";
+
+describe("deploy function", () => {
+  let originalFetch;
+  let originalConsole;
+  let consoleOutput;
+  let saveValueToConfigSpy;
+  let originalSetTimeout;
+
+  beforeEach(async () => {
+    // Reset environment
+    process.env.DOC_SMITH_BASE_URL = "https://test.example.com";
+    process.env.NODE_ENV = "test";
+
+    // Mock console to capture output
+    consoleOutput = [];
+    originalConsole = {
+      log: console.log,
+      error: console.error,
+    };
+    console.log = (...args) => consoleOutput.push({ type: "log", args });
+    console.error = (...args) => consoleOutput.push({ type: "error", args });
+
+    // Mock setTimeout to make tests run instantly
+    originalSetTimeout = global.setTimeout;
+    global.setTimeout = (callback, _delay) => {
+      // Call immediately in tests
+      return originalSetTimeout(callback, 0);
+    };
+
+    // Mock fetch
+    originalFetch = global.fetch;
+
+    // Use spyOn to mock saveValueToConfig without affecting other tests
+    saveValueToConfigSpy = spyOn(utils, "saveValueToConfig").mockResolvedValue();
+
+    // Reset blocklet mocks
+    mockGetComponentInfoWithMountPoint.mockReset();
+    mockGetComponentInfo.mockReset();
+
+    // Set default mock implementations
+    mockGetComponentInfoWithMountPoint.mockResolvedValue({
+      mountPoint: "/payment",
+      PAYMENT_LINK_ID: "test-payment-id",
+    });
+
+    mockGetComponentInfo.mockResolvedValue({
+      status: "running",
+    });
+  });
+
+  afterEach(() => {
+    // Restore originals
+    global.fetch = originalFetch;
+    global.setTimeout = originalSetTimeout;
+    console.log = originalConsole.log;
+    console.error = originalConsole.error;
+
+    // Restore spies
+    if (saveValueToConfigSpy) {
+      saveValueToConfigSpy.mockRestore();
+    }
+
+    // Reset open mock
+    mockOpenDefault.mockReset();
+
+    // Reset environment
+    delete process.env.NODE_ENV;
+  });
+
+  test("successful deployment flow", async () => {
+    // Mock API responses for the complete flow
+    let callCount = 0;
+    global.fetch = mock(async (url) => {
+      callCount++;
+
+      // Step 1: Create payment session
+      if (url.includes("/api/checkout-sessions/start")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            checkoutSession: { id: "checkout-123" },
+            paymentUrl: "https://payment.test/checkout-123",
+          }),
+        };
+      }
+
+      // Step 2-4: Poll payment/installation/service status
+      if (url.includes("/api/vendors/order/checkout-123/status")) {
+        if (callCount <= 2) {
+          // First call: payment completed, installation in progress
+          return {
+            ok: true,
+            status: 200,
+            json: async () => ({
+              payment_status: "paid",
+              vendors: [{ id: "vendor-1", progress: 50, appUrl: null }],
+            }),
+          };
+        } else {
+          // Subsequent calls: installation complete
+          return {
+            ok: true,
+            status: 200,
+            json: async () => ({
+              payment_status: "paid",
+              vendors: [{ id: "vendor-1", progress: 100, appUrl: "https://app.test" }],
+            }),
+          };
+        }
+      }
+
+      // Step 5: Get order details
+      if (url.includes("/api/vendors/order/checkout-123/detail")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            vendors: [
+              {
+                appUrl: "https://app.test",
+                dashboardUrl: "https://dashboard.test",
+                homeUrl: "https://home.test",
+                token: "auth-token-123",
+              },
+            ],
+          }),
+        };
+      }
+
+      throw new Error(`Unexpected URL: ${url}`);
+    });
+
+    const result = await deploy();
+
+    // Verify result
+    expect(result).toEqual({
+      appUrl: "https://app.test",
+      homeUrl: "https://home.test",
+      token: "auth-token-123",
+    });
+
+    // Verify saveValueToConfig was called
+    expect(saveValueToConfigSpy).toHaveBeenCalledWith(
+      "checkoutId",
+      "checkout-123",
+      "Checkout ID for document deployment service",
+    );
+    expect(saveValueToConfigSpy).toHaveBeenCalledWith(
+      "paymentUrl",
+      expect.stringContaining("payment"),
+      "Payment URL for document deployment service",
+    );
+
+    // Verify console output shows progress
+    const logs = consoleOutput.filter((o) => o.type === "log").map((o) => o.args.join(" "));
+    expect(logs.some((log) => log.includes("Step 1/4: Waiting for payment"))).toBe(true);
+    expect(logs.some((log) => log.includes("Step 2/4: Installing service"))).toBe(true);
+    expect(logs.some((log) => log.includes("Step 3/4: Starting service"))).toBe(true);
+    expect(logs.some((log) => log.includes("Step 4/4: Getting service URL"))).toBe(true);
+    expect(logs.some((log) => log.includes("Your website is available at"))).toBe(true);
+  });
+
+  test("handles missing payment link ID", async () => {
+    mockGetComponentInfoWithMountPoint.mockResolvedValue({
+      mountPoint: "/payment",
+      PAYMENT_LINK_ID: null,
+    });
+
+    await expect(deploy()).rejects.toThrow("Payment link ID not found");
+  });
+
+  test("handles payment session creation failure", async () => {
+    global.fetch = mock(async (url) => {
+      if (url.includes("/api/checkout-sessions/start")) {
+        return {
+          ok: false,
+          status: 400,
+          json: async () => ({ error: "Payment creation failed" }),
+        };
+      }
+    });
+
+    await expect(deploy()).rejects.toThrow("Failed to create payment session");
+
+    const errors = consoleOutput.filter((o) => o.type === "error");
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  test("handles network errors gracefully", async () => {
+    global.fetch = mock(async () => {
+      throw new Error("Network connection failed");
+    });
+
+    await expect(deploy()).rejects.toThrow("Failed to create payment session");
+  });
+
+  test("handles browser opening failure gracefully", async () => {
+    // Mock successful API flow
+    global.fetch = mock(async (url) => {
+      if (url.includes("/api/checkout-sessions/start")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            checkoutSession: { id: "checkout-123" },
+            paymentUrl: "https://payment.test/checkout-123",
+          }),
+        };
+      }
+
+      if (url.includes("/status")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            payment_status: "paid",
+            vendors: [{ id: "vendor-1", progress: 100, appUrl: "https://app.test" }],
+          }),
+        };
+      }
+
+      if (url.includes("/detail")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            vendors: [
+              {
+                appUrl: "https://app.test",
+                homeUrl: "https://home.test",
+                token: "auth-token-123",
+              },
+            ],
+          }),
+        };
+      }
+    });
+
+    // Mock open to fail
+    mockOpenDefault.mockRejectedValue(new Error("Cannot open browser"));
+
+    // Call deploy without cached parameters - should still succeed
+    const result = await deploy();
+
+    // Should still complete successfully despite browser opening failure
+    expect(result.appUrl).toBe("https://app.test");
+    expect(result.homeUrl).toBe("https://home.test");
+    expect(result.token).toBe("auth-token-123");
+  });
+
+  test("handles cached checkout ID", async () => {
+    // Mock successful status check for cached ID
+    global.fetch = mock(async (url) => {
+      if (url.includes("/status")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            payment_status: "paid",
+            vendors: [{ id: "vendor-1", progress: 100, appUrl: "https://app.test" }],
+          }),
+        };
+      }
+
+      if (url.includes("/detail")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            vendors: [
+              {
+                appUrl: "https://app.test",
+                homeUrl: "https://home.test",
+                token: "auth-token-123",
+              },
+            ],
+          }),
+        };
+      }
+    });
+
+    const result = await deploy("existing-checkout-id", "https://cached-payment.url");
+
+    expect(result.appUrl).toBe("https://app.test");
+
+    // Should not call open since using cached checkout
+    expect(mockOpenDefault).not.toHaveBeenCalled();
+  });
+
+  test("clears checkout ID when cache check fails", async () => {
+    // Mock successful responses for the complete flow after cache check fails
+    let callCount = 0;
+    global.fetch = mock(async (url) => {
+      callCount++;
+
+      // First call: cache check fails
+      if (callCount === 1 && url.includes("/status")) {
+        throw new Error("Network error during cache check");
+      }
+
+      // Create payment session
+      if (url.includes("/api/checkout-sessions/start")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            checkoutSession: { id: "new-checkout-123" },
+            paymentUrl: "https://payment.test/new-checkout-123",
+          }),
+        };
+      }
+
+      // Subsequent status checks and detail calls
+      if (url.includes("/status")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            payment_status: "paid",
+            vendors: [{ id: "vendor-1", progress: 100, appUrl: "https://app.test" }],
+          }),
+        };
+      }
+
+      if (url.includes("/detail")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            vendors: [
+              {
+                appUrl: "https://app.test",
+                homeUrl: "https://home.test",
+                token: "auth-token-123",
+              },
+            ],
+          }),
+        };
+      }
+    });
+
+    // Call deploy with invalid cached checkout ID - should clear it and create new one
+    const result = await deploy("invalid-checkout-id");
+
+    expect(result.appUrl).toBe("https://app.test");
+
+    // Verify that checkoutId was cleared due to cache check failure
+    expect(saveValueToConfigSpy).toHaveBeenCalledWith(
+      "checkoutId",
+      "",
+      "Checkout ID for document deployment service",
+    );
+  });
+});

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);
@@ -1307,7 +1307,9 @@ describe("init", () => {
             if (options.message.includes("[1/8]") && options.validate) {
               // Test the validation function directly
               const validationResult = options.validate([]);
-              expect(validationResult).toBe("Please select at least one purpose.");
+              expect(validationResult).toBe(
+                "Please choose at least one goal for your documentation.",
+              );
               validateCalled = true;
               // Return valid result after testing validation
               return Promise.resolve(["getStarted"]);
@@ -1346,7 +1348,7 @@ describe("init", () => {
             if (options.message.includes("[2/8]") && options.validate) {
               // Test the validation function for target audience
               const validationResult = options.validate([]);
-              expect(validationResult).toBe("Please select at least one audience.");
+              expect(validationResult).toBe("Please choose at least one audience.");
               audienceValidateCalled = true;
               return Promise.resolve(["developers"]); // Valid result after testing
             }
@@ -1385,11 +1387,11 @@ describe("init", () => {
             if (options.message.includes("Which is most important?") && options.validate) {
               // Test validation for empty selection
               let validationResult = options.validate([]);
-              expect(validationResult).toBe("Please select at least one priority.");
+              expect(validationResult).toBe("Please choose at least one priority.");
 
               // Test validation for too many selections
               validationResult = options.validate(["getStarted", "completeTasks", "findAnswers"]);
-              expect(validationResult).toBe("Please select maximum 2 priorities.");
+              expect(validationResult).toBe("Please choose maximum 2 priorities.");
 
               // Test validation for valid selection
               validationResult = options.validate(["getStarted", "completeTasks"]);

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);
 
@@ -88,11 +88,18 @@ export async function getAccessToken(appUrl) {
     const result = await createConnect({
       connectUrl: connectUrl,
       connectAction: "gen-simple-access-key",
-      source: `AIGNE DocSmith connect to Discuss Kit`,
+      source: `AIGNE DocSmith connect to website`,
       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;