@aigne/doc-smith 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.8.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.5...v0.8.6) (2025-09-11)
+
+
+### Features
+
+* add deploy unit tests and improve publish workflow with better logging ([e33a94b](https://github.com/AIGNE-io/aigne-doc-smith/commit/e33a94bef5eda09398901fa1f953e662ae5fbd16))
+* **publish:** display publish url for the default publish processing ([9d1d018](https://github.com/AIGNE-io/aigne-doc-smith/commit/9d1d0180dc9c8bb0a4393a893eed2395eec300ab))
+
+
+### Bug Fixes
+
+* **deploy:** ensure log is saved after await to prevent save failure ([793343f](https://github.com/AIGNE-io/aigne-doc-smith/commit/793343fc7f96ab962e70eb310cb07f4e7eaec9e0))
+
+
+### Miscellaneous Chores
+
+* release 0.8.6 ([1e25cb4](https://github.com/AIGNE-io/aigne-doc-smith/commit/1e25cb49a26d8bcc3c83ec36120b6bad4042cadf))
+
+## [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/action-success.mjs

@@ -9,7 +9,7 @@ export default async function actionSuccess({ action }) {
   }
 
   return {
-    message: `✅ ${action} successfully`,
+    message: `${action}`,
   };
 }
 

package/agents/check-structure-plan.mjs

@@ -21,7 +21,7 @@ export default async function checkStructurePlan(
   // Prompt for feedback if originalStructurePlan exists and no feedback provided
   if (originalStructurePlan && !feedback) {
     const userFeedback = await options.prompts.input({
-      message: "Please provide feedback for structure planning (press Enter to skip):",
+      message: "How can we improve the documentation structure? (press Enter to skip):",
     });
 
     if (userFeedback?.trim()) {

package/agents/detail-regenerator.yaml

@@ -2,7 +2,7 @@ type: team
 name: update
 alias:
   - up
-description: Optimize and regenerate individual document content and translations
+description: Update specific documents and their translations
 skills:
   - url: ./input-generator.mjs
     default_input:
@@ -39,24 +39,24 @@ skills:
       stage: document_refine
   - url: ./action-success.mjs
     default_input:
-      action: "Document updated"
+      action: "✅ Documents updated successfully"
 input_schema:
   type: object
   properties:
     glossary:
       type: string
-      description: Glossary of terms for consistent terminology, use @<file> to read from a file
+      description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Document paths to translate
+      description: Documents to update
     feedback:
       type: string
-      description: Feedback for content improvement
+      description: Tell us what to change in this content
     reset:
       type: boolean
-      description: Ignore previous results and regenerate content from scratch
+      description: Start fresh - ignore previous versions
 output_schema:
   type: object
   properties:

package/agents/docs-generator.yaml

@@ -3,7 +3,7 @@ name: generate
 alias:
   - gen
   - g
-description: Automatically generates comprehensive project documentation
+description: Generate complete documentation for your project
 skills:
   - url: ./input-generator.mjs
     default_input:
@@ -47,13 +47,13 @@ input_schema:
   properties:
     glossary:
       type: string
-      description: Glossary of terms for consistent terminology, use @<file> to read from a file
+      description: Glossary file for consistent terminology (use @filename.md)
     feedback:
       type: string
-      description: Feedback for structure planning adjustments
+      description: Tell us how to improve the documentation structure
     forceRegenerate:
       type: boolean
-      description: Force regenerate all documentation
+      description: Rebuild all documentation from scratch
   required:
     - config
 mode: sequential

package/agents/feedback-refiner.yaml

@@ -1,5 +1,5 @@
 name: feedbackRefiner
-description: Analyzes a user's specific feedback on generated documentation and refines it into a general, reusable preference rule for future use.
+description: Learn from your feedback to improve future documentation
 
 # The instructions file contains the core logic (the prompt) for this Agent.
 instructions:
@@ -10,18 +10,18 @@ input_schema:
   properties:
     feedback:
       type: string
-      description: User's original feedback
+      description: Tell us what you think about the documentation
     stage:
       type: string
-      description: The command/scenario that generated the feedback (used to infer scope), possible values. structure_planning, document_refine, translation_refine
+      description: Which part of the process this feedback is about (structure_planning, document_refine, translation_refine)
     paths:
       type: array
       items:
         type: string
-      description: Optional. Document paths specified by the user in the current command
+      description: Specific documents this feedback applies to (optional)
     existingPreferences:
       type: string
-      description: Optional. YAML format string of currently saved user preference rules, used to avoid duplicate saving of similar rules
+      description: Your existing preferences to avoid duplicates (optional)
   required: 
     - feedback
     - stage
@@ -31,19 +31,19 @@ output_schema:
   properties:
     rule:
       type: string
-      description: Refine and summarize user feedback into a general rule
+      description: General rule created from your feedback
     scope:
       type: string
-      description: Rule scope. global, structure, document, translation
+      description: Where this rule applies (global, structure, document, translation)
     save:
       type: boolean
-      description: Whether to save as persistent preference (true=save; false=one-time, do not save)
+      description: Should we remember this preference for next time?
     limitToInputPaths:
       type: boolean
-      description: Whether to limit to the "paths specified in current input" when used subsequently
+      description: Apply only to the specific documents mentioned?
     reason:
       type: string
-      description: Explanation of why the save decision was made and how the rule and scope were derived
+      description: Why we made this decision and how the rule was created
   required:
     - rule
     - scope

package/agents/find-item-by-path.mjs

@@ -89,7 +89,7 @@ export default async function findItemByPath(
   if (!userFeedback) {
     const feedbackMessage = getActionText(
       isTranslate,
-      "Please provide feedback for the {action} (press Enter to skip):",
+      "How should we improve this {action}? (press Enter to skip):",
     );
 
     userFeedback = await options.prompts.input({

package/agents/find-items-by-paths.mjs

@@ -90,7 +90,7 @@ export default async function selectedDocs(
   if (!userFeedback) {
     const feedbackMessage = getActionText(
       isTranslate,
-      "Please provide feedback for the {action} (press Enter to skip):",
+      "How should we improve this {action}? (press Enter to skip):",
     );
 
     userFeedback = await options.prompts.input({

package/agents/input-generator.mjs

@@ -44,14 +44,14 @@ export default async function init(
   }
 
   console.log("🚀 Welcome to AIGNE DocSmith!");
-  console.log("Let's create your documentation configuration.\n");
+  console.log("Let's set up your documentation preferences.\n");
 
   // Collect user information
   const input = {};
 
   // 1. Primary purpose - what's the main outcome you want readers to achieve?
   const purposeChoices = await options.prompts.checkbox({
-    message: "📝 [1/8]: What is the primary goal for your readers? (Select all that apply)",
+    message: "📝 [1/8]: What should your documentation help readers achieve?",
     choices: Object.entries(DOCUMENT_STYLES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, style]) => ({
@@ -61,7 +61,7 @@ export default async function init(
       })),
     validate: (input) => {
       if (input.length === 0) {
-        return "Please select at least one purpose.";
+        return "Please choose at least one goal for your documentation.";
       }
       return true;
     },
@@ -81,10 +81,10 @@ export default async function init(
         })),
       validate: (input) => {
         if (input.length === 0) {
-          return "Please select at least one priority.";
+          return "Please choose at least one priority.";
         }
         if (input.length > 2) {
-          return "Please select maximum 2 priorities.";
+          return "Please choose maximum 2 priorities.";
         }
         return true;
       },
@@ -99,7 +99,7 @@ export default async function init(
 
   // 2. Target audience - who will be reading this most often?
   const audienceChoices = await options.prompts.checkbox({
-    message: "👥 [2/8]: Who is the primary audience for this documentation?",
+    message: "👥 [2/8]: Who will be reading your documentation?",
     choices: Object.entries(TARGET_AUDIENCES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, audience]) => ({
@@ -109,7 +109,7 @@ export default async function init(
       })),
     validate: (input) => {
       if (input.length === 0) {
-        return "Please select at least one audience.";
+        return "Please choose at least one audience.";
       }
       return true;
     },
@@ -133,7 +133,7 @@ export default async function init(
   );
 
   const knowledgeChoice = await options.prompts.select({
-    message: "🧠 [3/8]: What is your reader's typical starting knowledge level?",
+    message: "🧠 [3/8]: How much do readers already know about your project?",
     choices: Object.entries(filteredKnowledgeOptions).map(([key, level]) => ({
       name: `${level.name}`,
       description: level.description,
@@ -178,7 +178,7 @@ export default async function init(
   );
 
   const depthChoice = await options.prompts.select({
-    message: "📊 [4/8]: How comprehensive should the documentation be?",
+    message: "📊 [4/8]: How detailed should your documentation be?",
     choices: Object.entries(filteredDepthOptions).map(([key, depth]) => ({
       name: `${depth.name}`,
       description: depth.description,
@@ -196,7 +196,7 @@ export default async function init(
 
   // Let user select primary language from supported list
   const primaryLanguageChoice = await options.prompts.select({
-    message: "🌐 [5/8]: Choose primary documentation language:",
+    message: "🌐 [5/8]: What's your main documentation language?",
     choices: SUPPORTED_LANGUAGES.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -213,7 +213,7 @@ export default async function init(
   );
 
   const translateLanguageChoices = await options.prompts.checkbox({
-    message: "🔄 [6/8]: Select translation languages:",
+    message: "🔄 [6/8]: Which languages should we translate to?",
     choices: availableTranslationLanguages.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -224,21 +224,23 @@ export default async function init(
 
   // 7. Documentation directory
   const docsDirInput = await options.prompts.input({
-    message: `📁 [7/8]: Where to save generated docs:`,
+    message: `📁 [7/8]: Where should we save your documentation?`,
     default: `${outputPath}/docs`,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
-  // 8. Source code paths
-  console.log("\n🔍 [8/8]: Source Code Paths");
-  console.log("Enter paths to analyze for documentation (e.g., ./src, ./lib)");
-  console.log("💡 You can also enter glob patterns (e.g., src/**/*.js, **/*.md)");
-  console.log("💡 If no paths are configured, './' will be used as default");
+  // 8. Content sources
+  console.log("\n🔍 [8/8]: Content Sources");
+  console.log(
+    "What folders/files should we analyze for documentation? (e.g., ./src, ./docs, ./README.md)",
+  );
+  console.log("💡 Advanced: Use patterns like src/**/*.js or docs/**/*.md for specific files");
+  console.log("💡 Leave empty to scan everything");
 
   const sourcePaths = [];
   while (true) {
     const selectedPath = await options.prompts.search({
-      message: "Path or glob pattern:",
+      message: "File/folder path or pattern:",
       source: async (input) => {
         if (!input || input.trim() === "") {
           return [
@@ -330,15 +332,13 @@ export default async function init(
     await mkdir(dirPath, { recursive: true });
 
     await writeFile(filePath, yamlContent, "utf8");
-    console.log(`\n🎉 Configuration saved to: ${chalk.cyan(filePath)}`);
+    console.log(`\n✅ Setup complete! Configuration saved to: ${chalk.cyan(filePath)}`);
     // Print YAML content for user review
     console.log(chalk.cyan("---"));
     console.log(chalk.cyan(yamlContent));
     console.log(chalk.cyan("---"));
     console.log("💡 You can edit the configuration file anytime to modify settings.\n");
-    console.log(
-      `🚀 Run ${chalk.cyan("'aigne doc generate'")} to start documentation generation!\n`,
-    );
+    console.log(`🚀 Ready to generate docs? Run: ${chalk.cyan("aigne doc generate")}\n`);
 
     return {};
   } catch (error) {
@@ -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/manage-prefs.mjs

@@ -8,7 +8,7 @@ function listPreferences() {
   const preferences = readPreferences();
 
   if (preferences.rules.length === 0) {
-    return { message: "No preferences found." };
+    return { message: "No saved preferences found." };
   }
 
   let message = "# User Preferences\n\n";
@@ -53,7 +53,7 @@ async function removePreferences(id, options) {
   if (!targetIds || targetIds.length === 0) {
     // Interactive selection
     if (preferences.rules.length === 0) {
-      return { message: "No preferences found to remove." };
+      return { message: "No preferences available to remove." };
     }
 
     const choices = preferences.rules.map((rule) => ({
@@ -63,18 +63,18 @@ async function removePreferences(id, options) {
     }));
 
     targetIds = await options.prompts.checkbox({
-      message: "Select preferences to remove:",
+      message: "Choose preferences to delete:",
       choices,
       validate: (answer) => {
         if (answer.length === 0) {
-          return "Please select at least one preference to remove";
+          return "Please choose at least one preference to delete";
         }
         return true;
       },
     });
 
     if (!targetIds || targetIds.length === 0) {
-      return { message: "No preferences selected for removal." };
+      return { message: "No preferences selected for deletion." };
     }
   }
 
@@ -108,7 +108,7 @@ async function togglePreferences(id, options) {
   if (!targetIds || targetIds.length === 0) {
     // Interactive selection
     if (preferences.rules.length === 0) {
-      return { message: "No preferences found to toggle." };
+      return { message: "No preferences available to toggle." };
     }
 
     const choices = preferences.rules.map((rule) => ({
@@ -118,18 +118,18 @@ async function togglePreferences(id, options) {
     }));
 
     targetIds = await options.prompts.checkbox({
-      message: "Select preferences to toggle active status:",
+      message: "Choose preferences to enable/disable:",
       choices,
       validate: (answer) => {
         if (answer.length === 0) {
-          return "Please select at least one preference to toggle";
+          return "Please choose at least one preference to toggle";
         }
         return true;
       },
     });
 
     if (!targetIds || targetIds.length === 0) {
-      return { message: "No preferences selected for toggling." };
+      return { message: "No preferences selected to toggle." };
     }
   }
 
@@ -172,7 +172,7 @@ export default async function prefs({ list, remove, toggle, id }, options) {
     return await togglePreferences(id, options);
   }
 
-  return { message: "Please specify an action: --list, --remove, or --toggle." };
+  return { message: "Please choose an action: --list, --remove, or --toggle." };
 }
 
 prefs.input_schema = {
@@ -180,24 +180,24 @@ prefs.input_schema = {
   properties: {
     list: {
       type: "boolean",
-      description: "List all preferences",
+      description: "Show all saved preferences",
     },
     remove: {
       type: "boolean",
-      description: "Remove preferences",
+      description: "Delete saved preferences",
     },
     toggle: {
       type: "boolean",
-      description: "Toggle preferences active status",
+      description: "Enable/disable preferences",
     },
     id: {
       type: "array",
       items: {
         type: "string",
       },
-      description: "Preference IDs to manage",
+      description: "Specific preference IDs to work with",
     },
   },
 };
 
-prefs.description = "Manage user preferences learned from feedback";
+prefs.description = "Manage your saved documentation preferences";

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,37 @@ 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("DocSmith Cloud (docsmith.aigne.io)")} – ${chalk.green("Free")} hosting. Your documents will be publicly accessible. Best for open-source projects or community sharing.`,
           value: "default",
         },
         {
-          name: "Publish to your own website - you will need to run Discuss Kit by your self ",
+          name: `${chalk.blue("Your existing website")} - Integrate and publish directly on your current site (setup required)`,
           value: "custom",
         },
+        ...(hasCachedCheckoutId && hasDocSmithBaseUrl
+          ? [
+              {
+                name: `${chalk.yellow("Resume previous website setup")} - ${chalk.green("Already paid.")} Continue where you left off. Your payment is already processed.`,
+                value: "new-instance-continue",
+              },
+            ]
+          : []),
+        ...(hasDocSmithBaseUrl
+          ? [
+              {
+                name: `${chalk.blue("New website")} - ${chalk.yellow("Paid service.")} We'll help you set up a brand-new website with custom domain and hosting. Great if you want a professional presence.`,
+                value: "new-instance",
+              },
+            ]
+          : []),
       ],
     });
 
@@ -63,7 +85,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 +99,33 @@ 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 new 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);
+  console.log(`\nPublishing docs to ${chalk.cyan(appUrl)}\n`);
+
+  const accessToken = await getAccessToken(appUrl, token);
 
   process.env.DOC_ROOT_DIR = docsDir;
 
@@ -138,6 +183,8 @@ export default async function publishDocs(
   } catch (error) {
     message = `❌ Failed to publish docs: ${error.message}`;
   }
+  await saveValueToConfig("checkoutId", "", "Checkout ID for document deployment service");
+
   // clean up tmp work dir
   await fs.rm(docsDir, { recursive: true, force: true });
   return message ? { message } : {};
@@ -162,4 +209,4 @@ publishDocs.input_schema = {
   },
 };
 
-publishDocs.description = "Publish the documentation to Discuss Kit";
+publishDocs.description = "Publish the documentation to website";

package/agents/retranslate.yaml

@@ -1,6 +1,6 @@
 type: team
 name: translate
-description: Translate document content to selected languages
+description: Translate documents into other languages
 skills:
   - url: ./input-generator.mjs
     default_input:
@@ -42,24 +42,24 @@ skills:
       stage: translation_refine
   - url: ./action-success.mjs
     default_input:
-      action: "Document translated"
+      action: "✅ Translation completed"
 input_schema:
   type: object
   properties:
     glossary:
       type: string
-      description: Glossary of terms for consistent terminology, use @<file> to read from a file
+      description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Document paths to translate
+      description: Documents to translate
     langs:
       type: array
       items:
         type: string
-      description: "Languages to translate to, available languages are: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar"
+      description: "Target languages (available: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar)"
     feedback:
       type: string
-      description: Feedback for translation improvement
+      description: Tell us how to improve the translation style
 mode: sequential