@aigne/doc-smith 0.4.5 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.6.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.5.1...v0.6.0) (2025-08-27)
+
+
+### Features
+
+* complete support for media processing before publish ([#63](https://github.com/AIGNE-io/aigne-doc-smith/issues/63)) ([5257ca1](https://github.com/AIGNE-io/aigne-doc-smith/commit/5257ca1756f47487b65a1813949e547b6fc51aca))
+
+## [0.5.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.5.0...v0.5.1) (2025-08-26)
+
+
+### Miscellaneous Chores
+
+* release 0.5.1 ([892d96e](https://github.com/AIGNE-io/aigne-doc-smith/commit/892d96e939a6404a42e8d2521f95bb7acfeabe27))
+
+## [0.5.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.4.5...v0.5.0) (2025-08-26)
+
+
+### Features
+
+* support persistent user feedback as preferences ([#57](https://github.com/AIGNE-io/aigne-doc-smith/issues/57)) ([761a583](https://github.com/AIGNE-io/aigne-doc-smith/commit/761a583297b397a12d848d10d26cd5b675f8a9e7))
+
+
+### Bug Fixes
+
+* polish init question copy ([#65](https://github.com/AIGNE-io/aigne-doc-smith/issues/65)) ([d4e8762](https://github.com/AIGNE-io/aigne-doc-smith/commit/d4e8762f26fd757bde43427860a0c1dade384269))
+
 ## [0.4.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.4.4...v0.4.5) (2025-08-25)
 
 

package/agents/batch-translate.yaml

@@ -6,6 +6,9 @@ skills:
     task_render_mode: collapse
     name: translate
     skills:
+      - url: ./find-user-preferences-by-path.mjs
+        default_input:
+          scope: translation
       - ./translate.yaml
       - type: transform
         jsonata: |

package/agents/check-detail-result.mjs

@@ -1,6 +1,6 @@
 import { checkMarkdown } from "../utils/markdown-checker.mjs";
 
-export default async function checkDetailResult({ structurePlan, reviewContent }) {
+export default async function checkDetailResult({ structurePlan, reviewContent, docsDir }) {
   let isApproved = true;
   const detailFeedback = [];
 
@@ -24,6 +24,7 @@ export default async function checkDetailResult({ structurePlan, reviewContent }
   try {
     const markdownErrors = await checkMarkdown(reviewContent, "result", {
       allowedLinks,
+      baseDir: docsDir,
     });
 
     if (markdownErrors.length > 0) {

package/agents/check-detail.mjs

@@ -85,6 +85,7 @@ export default async function checkDetail(
     const validationResult = await checkDetailResult({
       structurePlan,
       reviewContent: fileContent,
+      docsDir,
     });
 
     if (!validationResult.isApproved) {

package/agents/check-feedback-refiner.mjs

@@ -0,0 +1,79 @@
+import { stringify } from "yaml";
+import { addPreferenceRule, readPreferences } from "../utils/preferences-utils.mjs";
+
+export default async function checkFeedbackRefiner(
+  { feedback, stage, selectedPaths, structurePlanFeedback },
+  options,
+) {
+  // If feedback is empty, no need to save user preferences
+  if (!feedback && !structurePlanFeedback) {
+    return {};
+  }
+
+  // Read existing preferences as context for deduplication
+  const existingPreferences = readPreferences();
+  const activePreferences = existingPreferences.rules?.filter((rule) => rule.active) || [];
+
+  // Convert active preferences to YAML string format for passing
+  const activePreferencesYaml =
+    activePreferences.length > 0 ? stringify({ rules: activePreferences }, { indent: 2 }) : "";
+
+  const feedbackToUse = feedback || structurePlanFeedback;
+  const result = await options.context.invoke(options.context.agents["feedbackRefiner"], {
+    feedback: feedbackToUse,
+    stage,
+    paths: selectedPaths,
+    existingPreferences: activePreferencesYaml,
+  });
+
+  // If preferences need to be saved, save them to the preference file
+  if (result?.save) {
+    try {
+      const savedRule = addPreferenceRule(result, feedbackToUse, selectedPaths);
+
+      // Add saved preference information to the return result
+      result.savedPreference = {
+        id: savedRule.id,
+        saved: true,
+      };
+    } catch (error) {
+      console.error(
+        "Failed to save user preference rule:",
+        error.message,
+        "\nFeedback:",
+        feedbackToUse,
+      );
+      result.savedPreference = {
+        saved: false,
+        error: error.message,
+      };
+    }
+  }
+
+  return result;
+}
+
+checkFeedbackRefiner.input_schema = {
+  type: "object",
+  properties: {
+    feedback: {
+      type: "string",
+      description: "User feedback to refine",
+    },
+    structurePlanFeedback: {
+      type: "string",
+      description: "Feedback from structure planning stage",
+    },
+    stage: {
+      type: "string",
+      description: "Stage of the feedback",
+    },
+    selectedPaths: {
+      type: "array",
+      items: {
+        type: "string",
+      },
+      description: "Selected paths of documents",
+    },
+  },
+};

package/agents/check-structure-plan.mjs

@@ -1,5 +1,6 @@
 import { access } from "node:fs/promises";
 import { join } from "node:path";
+import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
 import {
   getCurrentGitHead,
   getProjectInfo,
@@ -15,6 +16,7 @@ export default async function checkStructurePlan(
   // Check if we need to regenerate structure plan
   let shouldRegenerate = false;
   let finalFeedback = feedback;
+  let submittedFeedback = feedback;
 
   // Prompt for feedback if originalStructurePlan exists and no feedback provided
   if (originalStructurePlan && !feedback) {
@@ -24,6 +26,7 @@ export default async function checkStructurePlan(
 
     if (userFeedback?.trim()) {
       finalFeedback = userFeedback.trim();
+      submittedFeedback = userFeedback.trim();
     }
   }
 
@@ -84,9 +87,21 @@ export default async function checkStructurePlan(
 
   const panningAgent = options.context.agents["structurePlanning"];
 
+  // Get user preferences for structure planning and global scope
+  const structureRules = getActiveRulesForScope("structure", []);
+  const globalRules = getActiveRulesForScope("global", []);
+
+  // Combine structure and global rules, extract only rule text
+  const allApplicableRules = [...structureRules, ...globalRules];
+  const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+
+  // Convert rule texts to string format for passing to the agent
+  const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
   const result = await options.context.invoke(panningAgent, {
     feedback: finalFeedback || "",
     originalStructurePlan,
+    userPreferences,
     ...rest,
   });
 
@@ -140,6 +155,7 @@ export default async function checkStructurePlan(
   return {
     ...result,
     feedback: "", // clear feedback
+    structurePlanFeedback: submittedFeedback,
     projectInfoMessage: message,
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan

package/agents/detail-generator-and-translate.yaml

@@ -7,6 +7,9 @@ skills:
     task_render_mode: collapse
     name: detailGenerate
     skills:
+      - url: ./find-user-preferences-by-path.mjs
+        default_input:
+          scope: document
       - ./content-detail-generator.yaml
       - type: transform
         jsonata: |

package/agents/detail-regenerator.yaml

@@ -34,6 +34,9 @@ skills:
       - ./detail-generator-and-translate.yaml
     iterate_on: selectedDocs
     concurrency: 3
+  - url: ./check-feedback-refiner.mjs
+    default_input:
+      stage: document_refine
   - url: ./action-success.mjs
     default_input:
       action: "Document updated"

package/agents/docs-generator.yaml

@@ -37,6 +37,9 @@ skills:
       ])
   - ./format-structure-plan.mjs
   - ./batch-docs-detail-generator.yaml
+  - url: ./check-feedback-refiner.mjs
+    default_input:
+      stage: structure_planning
   - ./save-docs.mjs
 
 input_schema:

package/agents/feedback-refiner.yaml

@@ -0,0 +1,48 @@
+name: feedbackRefiner
+description: Analyzes a user's specific feedback on generated documentation and refines it into a general, reusable preference rule for future use.
+
+# The instructions file contains the core logic (the prompt) for this Agent.
+instructions:
+  url: ../prompts/feedback-refiner.md
+
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User's original feedback
+    stage:
+      type: string
+      description: The command/scenario that generated the feedback (used to infer scope), possible values. structure_planning, document_refine, translation_refine
+    paths:
+      type: array
+      items:
+        type: string
+      description: Optional. Document paths specified by the user in the current command
+    existingPreferences:
+      type: string
+      description: Optional. YAML format string of currently saved user preference rules, used to avoid duplicate saving of similar rules
+  required: 
+    - feedback
+    - stage
+
+output_schema:
+  type: object
+  properties:
+    rule:
+      type: string
+      description: Refine and summarize user feedback into a general rule
+    scope:
+      type: string
+      description: Rule scope. global, structure, document, translation
+    save:
+      type: boolean
+      description: Whether to save as persistent preference (true=save; false=one-time, do not save)
+    limitToInputPaths:
+      type: boolean
+      description: Whether to limit to the "paths specified in current input" when used subsequently
+  required:
+    - rule
+    - scope
+    - save
+    - limitToInputPaths

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

@@ -95,5 +95,9 @@ export default async function selectedDocs(
   // Add feedback to all results if provided
   foundItems = addFeedbackToItems(foundItems, userFeedback);
 
-  return { selectedDocs: foundItems };
+  return {
+    selectedDocs: foundItems,
+    feedback: userFeedback,
+    selectedPaths: foundItems.map((item) => item.path),
+  };
 }

package/agents/find-user-preferences-by-path.mjs

@@ -0,0 +1,37 @@
+import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+
+export default async function findUserPreferencesByPath({ path, scope }) {
+  // Get global rules (always applicable)
+  const globalRules = getActiveRulesForScope("global", []);
+
+  // Get scope-specific rules (document/translation based on scope parameter)
+  const scopeRules = getActiveRulesForScope(scope, path ? [path] : []);
+
+  // Combine all applicable rules
+  const allApplicableRules = [...globalRules, ...scopeRules];
+
+  // Extract only rule text and join with double newlines
+  const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+  const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
+  return {
+    userPreferences,
+  };
+}
+
+findUserPreferencesByPath.input_schema = {
+  type: "object",
+  properties: {
+    path: {
+      type: "string",
+      description: "Document path to find preferences for",
+    },
+    scope: {
+      type: "string",
+      description:
+        "Preference scope: 'document' for update operations, 'translation' for translate operations",
+      enum: ["document", "translation"],
+    },
+  },
+  required: ["scope"],
+};

package/agents/input-generator.mjs

@@ -47,8 +47,7 @@ export default async function init(
 
   // 1. Primary purpose - what's the main outcome you want readers to achieve?
   const purposeChoices = await options.prompts.checkbox({
-    message:
-      "📝 Step 1/8: What's the main outcome you want readers to achieve? (Select all that apply)",
+    message: "📝 [1/8]: What is the primary goal for your readers? (Select all that apply)",
     choices: Object.entries(DOCUMENT_STYLES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, style]) => ({
@@ -96,7 +95,7 @@ export default async function init(
 
   // 2. Target audience - who will be reading this most often?
   const audienceChoices = await options.prompts.checkbox({
-    message: "👥 Step 2/8: Who will be reading this most often? (Select all that apply)",
+    message: "👥 [2/8]: Who is the primary audience for this documentation?",
     choices: Object.entries(TARGET_AUDIENCES)
       .filter(([key]) => key !== "custom") // Remove custom option for multiselect
       .map(([key, audience]) => ({
@@ -130,7 +129,7 @@ export default async function init(
   );
 
   const knowledgeChoice = await options.prompts.select({
-    message: "🧠 Step 3/8: What do readers typically know when they arrive?",
+    message: "🧠 [3/8]: What is your reader's typical starting knowledge level?",
     choices: Object.entries(filteredKnowledgeOptions).map(([key, level]) => ({
       name: `${level.name}`,
       description: level.description,
@@ -175,7 +174,7 @@ export default async function init(
   );
 
   const depthChoice = await options.prompts.select({
-    message: "📊 Step 4/8: How comprehensive should the documentation be?",
+    message: "📊 [4/8]: How comprehensive should the documentation be?",
     choices: Object.entries(filteredDepthOptions).map(([key, depth]) => ({
       name: `${depth.name}`,
       description: depth.description,
@@ -193,7 +192,7 @@ export default async function init(
 
   // Let user select primary language from supported list
   const primaryLanguageChoice = await options.prompts.select({
-    message: "🌐 Step 5/8: Choose primary documentation language:",
+    message: "🌐 [5/8]: Choose primary documentation language:",
     choices: SUPPORTED_LANGUAGES.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -210,7 +209,7 @@ export default async function init(
   );
 
   const translateLanguageChoices = await options.prompts.checkbox({
-    message: "🔄 Step 6/8: Select translation languages:",
+    message: "🔄 [6/8]: Select translation languages:",
     choices: availableTranslationLanguages.map((lang) => ({
       name: `${lang.label} - ${lang.sample}`,
       value: lang.code,
@@ -221,13 +220,13 @@ export default async function init(
 
   // 7. Documentation directory
   const docsDirInput = await options.prompts.input({
-    message: `📁 Step 7/8: Where to save generated docs:`,
+    message: `📁 [7/8]: Where to save generated docs:`,
     default: `${outputPath}/docs`,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
   // 8. Source code paths
-  console.log("\n🔍 Step 8/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("💡 If no paths are configured, './' will be used as default");
 

package/agents/load-sources.mjs

@@ -86,17 +86,55 @@ export default async function loadSources({
   }
 
   files = [...new Set(files)];
+
+  // Define media file extensions
+  const mediaExtensions = [
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".svg",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".webm",
+    ".m4v",
+  ];
+
+  // Separate source files from media files
+  const sourceFiles = [];
+  const mediaFiles = [];
   let allSources = "";
-  const sourceFiles = await Promise.all(
+
+  await Promise.all(
     files.map(async (file) => {
-      const content = await readFile(file, "utf8");
-      // Convert absolute path to relative path from project root
-      const relativePath = path.relative(process.cwd(), file);
-      allSources += `// sourceId: ${relativePath}\n${content}\n`;
-      return {
-        sourceId: relativePath,
-        content,
-      };
+      const ext = path.extname(file).toLowerCase();
+
+      if (mediaExtensions.includes(ext)) {
+        // This is a media file
+        const relativePath = path.relative(docsDir, file);
+        const fileName = path.basename(file);
+        const description = path.parse(fileName).name;
+
+        mediaFiles.push({
+          name: fileName,
+          path: relativePath,
+          description,
+        });
+      } else {
+        // This is a source file
+        const content = await readFile(file, "utf8");
+        const relativePath = path.relative(process.cwd(), file);
+        allSources += `// sourceId: ${relativePath}\n${content}\n`;
+
+        sourceFiles.push({
+          sourceId: relativePath,
+          content,
+        });
+      }
     }),
   );
 
@@ -164,6 +202,17 @@ export default async function loadSources({
     }
   }
 
+  // Generate assets content from media files
+  let assetsContent = "# Available Media Assets for Documentation\n\n";
+
+  if (mediaFiles.length > 0) {
+    const mediaMarkdown = mediaFiles
+      .map((file) => `![${file.description}](${file.path})`)
+      .join("\n\n");
+
+    assetsContent += mediaMarkdown;
+  }
+
   // Count words and lines in allSources
   let totalWords = 0;
   let totalLines = 0;
@@ -188,6 +237,7 @@ export default async function loadSources({
     modifiedFiles,
     totalWords,
     totalLines,
+    assetsContent,
   };
 }
 
@@ -257,6 +307,10 @@ loadSources.output_schema = {
       items: { type: "string" },
       description: "Array of modified files since last generation",
     },
+    assetsContent: {
+      type: "string",
+      description: "Markdown content for available media assets",
+    },
   },
 };