@aigne/doc-smith 0.9.6-beta → 0.9.6-beta.1

package/prompts/structure/find-documents-to-add-links.md

@@ -0,0 +1,52 @@
+# Task: Find Documents to Add Links
+
+Determine which existing documents should link to newly added documents.
+
+## Input
+
+<documentStructure>
+{{originalDocumentStructure}}
+</documentStructure>
+
+<newDocuments>
+{{newDocuments}}
+</newDocuments>
+
+<userFeedback>
+{{allFeedback}}
+</userFeedback>
+
+## Steps
+
+1. **Check <userFeedback> first.**  
+   - If users explicitly specify linking (e.g., “link FAQ from About”), follow exactly.
+2. **Analyze <documentStructure>.**  
+   Identify existing documents that should link to those in <newDocuments> using the rules below.
+3. For each qualifying document, add a non-empty `newLinks` array containing new document paths.
+4. Output only these updated documents (subset of <documentStructure>) as `documentsWithNewLinks`.
+
+Each item in `documentsWithNewLinks` must:
+- Be an existing document from <documentStructure>
+- Retain all original properties (`path`, `title`, `description`, `parentId`, `icon`, `sourceIds`)
+- Include `newLinks: string[]`
+
+## Linking Rules (in priority order)
+
+1. **User Instructions** — Follow explicit <userFeedback>.  
+2. **Parent–Child** — If a new document’s `parentId` equals a document’s `path`, the parent links to it.  
+3. **Semantic Similarity** — Link thematically related documents (e.g., “About” ↔ “Team”).  
+4. **Navigation Context** — Documents in the same navigation group may link.  
+5. **Hierarchy** — Sibling or section documents may cross-link.  
+6. **Relevance** — Add links only when it improves navigation logically.
+
+## Output Format
+
+```json
+{
+  "documentsWithNewLinks": [
+    {
+      "path": "/existing-document",
+      "newLinks": ["/new-document-1", "/new-document-2"]
+    }
+  ]
+}

package/prompts/utils/analyze-document-feedback-intent.md

@@ -0,0 +1,54 @@
+<role>
+You are a feedback intent analyzer for **document content modifications**. Your task is to determine the intent type of user feedback regarding content-level operations inside a document, and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+If the feedback contains any document-level (structure) operations, return an error (document content edits cannot include structure changes).
+
+Scope: Only analyze feedback related to document content (e.g. sections, text, images).  
+
+**Intent types:**
+
+1. add - Adding new sections or content inside a document
+2. edit - Modifying existing content, titles, descriptions, components
+3. delete - Removing sections or content
+4. move - Moving sections to different positions within the document
+5. reorder - Changing the order of sections at the same level
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document content operations.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Normal output:
+
+{
+  "error": false,
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on page content operations."
+}
+
+Error output (if document-level operations are detected):
+
+{
+  "error": true,
+  "needDataSources": false,
+  "reason": "Feedback mixes document-content edits with document-structure operations. When analyzing document content, structure changes are not allowed. Please split into separate feedback items."
+}
+</output_rules>

package/prompts/utils/analyze-structure-feedback-intent.md

@@ -0,0 +1,43 @@
+<role>
+You are a feedback intent analyzer for **document structure modifications**. Your task is to determine the intent type of user feedback regarding document-level operations and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+Scope: Only analyze feedback related to document structure. Ignore any content-level operations inside document (e.g. sections, text, images).
+
+**intent types:**
+
+1. add - Adding new documents
+2. edit - Modifying document-level properties (e.g., path, parentId, title of the document itself)
+3. delete - Removing documents
+4. move - Moving documents to different positions or parent sections
+5. reorder - Changing the order of documents
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document-level operations in the feedback.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Return a JSON object:
+
+{
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on document-level operations."
+}
+</output_rules>

package/types/document-schema.mjs

@@ -4,6 +4,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 // Update document content schemas
 export const updateDocumentContentInputSchema = z.object({
   diffPatch: z.string().min(1, "Diff patch is required"),
+  path: z.string().min(1, "Path is required for concurrent document updates"),
 });
 
 export const updateDocumentContentOutputSchema = z.object({
@@ -18,6 +19,7 @@ export const getUpdateDocumentContentInputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentContentInputSchema);
   if (schema.properties) {
     schema.properties.diffPatch.description = "Diff patch string to apply to the original content";
+    schema.properties.path.description = "Document path";
   }
   return schema;
 };

package/types/document-structure-schema.mjs

@@ -33,12 +33,13 @@ export const addDocumentOutputSchema = z.object({
 // Delete document schemas
 export const deleteDocumentInputSchema = z.object({
   path: z.string().min(1, "Path is required"),
+  recursive: z.boolean().optional(),
 });
 
 export const deleteDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
   message: z.string().optional(),
-  deletedDocument: documentItemSchema.optional(),
+  deletedDocuments: z.array(documentItemSchema).optional(),
   error: z.object({ message: z.string() }).optional(),
 });
 
@@ -113,6 +114,8 @@ export const getDeleteDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(deleteDocumentInputSchema);
   if (schema.properties) {
     schema.properties.path.description = "URL path of the document to delete";
+    schema.properties.recursive.description =
+      "If true, recursively delete all child documents. If false or not provided, deletion will fail if child documents exist.";
   }
   return schema;
 };
@@ -123,7 +126,8 @@ export const getDeleteDocumentOutputJsonSchema = () => {
     schema.properties.documentStructure.description =
       "Updated documentation structure array with the document removed";
     schema.properties.message.description = "Success message describing the operation result";
-    schema.properties.deletedDocument.description = "The deleted document object";
+    schema.properties.deletedDocuments.description =
+      "Array of deleted document objects (includes all recursively deleted child documents if recursive=true)";
     schema.properties.error.description =
       "Error object containing error message if operation failed";
   }

package/utils/docs-finder-utils.mjs

@@ -324,6 +324,40 @@ export async function loadDocumentStructure(outputDir) {
   }
 }
 
+/**
+ * Build allowed links set from document structure
+ * Includes both original paths and processed .md paths for link validation
+ * @param {Array} documentStructure - Array of documentation structure items with path property
+ * @returns {Set<string>} Set of allowed link paths
+ */
+export function buildAllowedLinksFromStructure(documentStructure) {
+  const allowedLinks = new Set();
+
+  if (!Array.isArray(documentStructure)) {
+    return allowedLinks;
+  }
+
+  documentStructure.forEach((item) => {
+    if (!item?.path) {
+      return;
+    }
+
+    // Add original path
+    allowedLinks.add(item.path);
+
+    // Add processed .md path (same logic as processContent in utils.mjs)
+    let processedPath = item.path;
+    if (processedPath.startsWith(".")) {
+      processedPath = processedPath.replace(/^\./, "");
+    }
+    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
+    flatPath = `./${flatPath}.md`;
+    allowedLinks.add(flatPath);
+  });
+
+  return allowedLinks;
+}
+
 /**
  * Build a tree structure from a flat document structure array using parentId
  * @param {Array} documentStructure - Flat array of document structure items with path and parentId
@@ -358,3 +392,51 @@ export function buildDocumentTree(documentStructure) {
 
   return { rootNodes, nodeMap };
 }
+
+/**
+ * Format document structure for printing
+ * @param {Array} structure - Document structure array
+ * @returns {Object} Object containing rootNodes and printNode function
+ */
+function formatDocumentStructure(structure) {
+  const { rootNodes } = buildDocumentTree(structure);
+
+  function printNode(node, depth = 0) {
+    const INDENT_SPACES = "  ";
+    const FOLDER_ICON = "  📁";
+    const FILE_ICON = "  📄";
+    const indent = INDENT_SPACES.repeat(depth);
+    const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
+
+    console.log(`${indent}${prefix} ${node.title}`);
+
+    if (node.children && node.children.length > 0) {
+      node.children.forEach((child) => {
+        printNode(child, depth + 1);
+      });
+    }
+  }
+
+  return { rootNodes, printNode };
+}
+
+/**
+ * Print document structure in a user-friendly format
+ * @param {Array} structure - Document structure array
+ */
+export function printDocumentStructure(structure) {
+  console.log(`\n  ${"-".repeat(50)}`);
+  console.log("  Current Documentation Structure");
+  console.log(`  ${"-".repeat(50)}`);
+
+  const { rootNodes, printNode } = formatDocumentStructure(structure);
+
+  if (rootNodes.length === 0) {
+    console.log("  No documentation structure found.");
+  } else {
+    rootNodes.forEach((node) => {
+      printNode(node);
+    });
+  }
+  console.log();
+}

package/utils/markdown-checker.mjs

@@ -59,6 +59,9 @@ function countTableColumns(line) {
   return columns.length;
 }
 
+const linkPattern = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
+const hrefPattern = /<x-card[^>]*\s+data-href\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/gi;
+
 /**
  * Check for dead links in markdown content
  * @param {string} markdown - The markdown content
@@ -67,16 +70,33 @@ function countTableColumns(line) {
  * @param {Array} errorMessages - Array to push error messages to
  */
 function checkDeadLinks(markdown, source, allowedLinks, errorMessages) {
-  const linkRegex = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
-  let match;
+  const links = [];
 
+  // Collect Markdown format links: [text](link)
+  const linkRegex = new RegExp(linkPattern.source, linkPattern.flags);
+  let match;
   while (true) {
     match = linkRegex.exec(markdown);
     if (match === null) break;
+    links.push({ trimLink: match[2].trim(), display: `[${match[1]}](${match[2].trim()})` });
+  }
 
-    const link = match[2];
-    const trimLink = link.trim();
+  // Collect data-href attribute values from <x-card> elements
+  const hrefRegex = new RegExp(hrefPattern.source, hrefPattern.flags);
+  let attrMatch;
+  while (true) {
+    attrMatch = hrefRegex.exec(markdown);
+    if (attrMatch === null) break;
+    const attrValue = (attrMatch[1] || attrMatch[2] || attrMatch[3] || "").trim();
+    if (attrValue) {
+      // Preserve original format with quotes if present
+      const originalMatch = attrMatch[0];
+      links.push({ trimLink: attrValue, display: originalMatch });
+    }
+  }
 
+  // Process all collected links with the same logic
+  for (const { trimLink, display } of links) {
     // Only check links that processContent would process
     // Exclude external links and mailto
     if (/^(https?:\/\/|mailto:)/.test(trimLink)) continue;
@@ -90,12 +110,37 @@ function checkDeadLinks(markdown, source, allowedLinks, errorMessages) {
     // Check if this link is in the allowed links set
     if (!allowedLinks.has(path)) {
       errorMessages.push(
-        `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the documentation structure path`,
+        `Found a dead link in ${source}: ${display}, ensure the link exists in the documentation structure path`,
       );
     }
   }
 }
 
+/**
+ * Extract link from error message
+ * @param {string} error - The error message
+ * @returns {string} - The link
+ */
+export function getLinkFromError(error) {
+  if (!error || !error.includes("Found a dead link in")) {
+    return "";
+  }
+
+  const linkRegex = new RegExp(linkPattern.source, linkPattern.flags);
+  let match = linkRegex.exec(error);
+  if (match) {
+    return match[2].trim();
+  }
+
+  const hrefRegex = new RegExp(hrefPattern.source, hrefPattern.flags);
+  match = hrefRegex.exec(error);
+  if (match) {
+    return (match[1] || match[2] || match[3] || "").trim();
+  }
+
+  return "";
+}
+
 /**
  * Check code block content for indentation consistency issues
  * @param {Array} codeBlockContent - Array of {line, lineNumber} objects from the code block

package/utils/utils.mjs

@@ -1225,3 +1225,106 @@ export function getContentHash(str, { trim = true } = {}) {
   const input = trim && typeof str === "string" ? str.trim() : str;
   return crypto.createHash("sha256").update(input).digest("hex");
 }
+
+function toPath(path) {
+  if (Array.isArray(path)) return path;
+
+  const result = [];
+  path.replace(/[^.[\]]+|\[(\d+|(["'])(.*?)\2)\]/g, (match, bracketContent, quote, quotedKey) => {
+    if (quote) {
+      // ["key"] or ['key']
+      result.push(quotedKey);
+    } else if (bracketContent !== undefined) {
+      // [123]
+      result.push(bracketContent);
+    } else {
+      // dot notation
+      result.push(match);
+    }
+  });
+  return result;
+}
+
+/**
+ * Deeply get the value at a given path from an object, or return a default value if missing.
+ * @param {object} obj - The object to query.
+ * @param {string|Array<string|number>} path - The path to get, as a string or array.
+ * @param {*} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {*} The value at the path or defaultValue.
+ */
+export function dget(obj, path, defaultValue) {
+  const parts = toPath(path);
+
+  let current = obj;
+  for (const key of parts) {
+    if (current == null || !(key in current)) return defaultValue;
+    current = current[key];
+  }
+  return current;
+}
+
+/**
+ * Deeply set the value at a given path in an object.
+ * @param {object} obj - The object to modify.
+ * @param {string|Array<string|number>} path - The path to set, as a string or array.
+ * @param {*} value - The value to set.
+ * @returns {object} The modified object.
+ */
+export function dset(obj, path, value) {
+  const parts = toPath(path);
+
+  let current = obj;
+  for (let i = 0; i < parts.length; i++) {
+    const key = parts[i];
+
+    if (i === parts.length - 1) {
+      current[key] = value;
+    } else {
+      if (current[key] == null || typeof current[key] !== "object") {
+        current[key] = String(parts[i + 1]).match(/^\d+$/) ? [] : {};
+      }
+      current = current[key];
+    }
+  }
+  return obj;
+}
+
+/**
+ * Create a context path manager that provides get/set/clear operations
+ * @param {object} options - The options object containing user context
+ * @param {string} path - The context path (e.g., 'currentPageDetails./about' or 'lastToolInputs./about')
+ * @returns {object} An object with { get, set } methods and a contextPath method for sub-paths
+ */
+export function userContextAt(options, path) {
+  const userContext = options?.context?.userContext || null;
+  if (!userContext) {
+    throw new Error("userContext is not available");
+  }
+
+  return {
+    /**
+     * Get a value from the context path
+     * @param {string} [key] - Optional key for nested access (e.g., 'updateMeta' for lastToolInputs)
+     * @returns {*} The value at the path, or undefined if not found
+     */
+    get(key) {
+      if (key !== undefined) {
+        return dget(userContext, `${path}.${key}`);
+      }
+      return dget(userContext, path);
+    },
+
+    /**
+     * Set a value in the context path
+     * @param {string|*} key - If key is provided, this is the key; otherwise this is the value
+     * @param {*} [value] - The value to set (required if first param is a key)
+     */
+    set(key, value) {
+      if (value !== undefined) {
+        dset(userContext, `${path}.${key}`, value);
+      } else {
+        dset(userContext, path, key);
+      }
+    },
+  };
+}

package/prompts/utils/analyze-feedback-intent.md

@@ -1,55 +0,0 @@
-<role>
-You are a feedback intent analyzer. Your task is to determine whether data sources are needed to fulfill the user's feedback about content modifications.
-</role>
-
-<input>
-- feedback: {{feedback}}
-</input>
-
-<analysis_rules>
-**Determining Data Source Necessity:**
-
-You need to analyze the user's feedback and categorize it into different intent types. Based on the intent type, determine if data sources are required.
-
-This analyzer is generic and can be used for any content modification scenarios (documentation structure, document content, translations, etc.).
-
-**Intent Types:**
-
-1. **add** - Adding new items, sections, or content
-   - Requires data sources: **YES**
-   - Reason: Need sufficient context from codebase or related materials to generate accurate new content
-
-2. **edit** - Modifying existing content, descriptions, titles, or properties
-   - Requires data sources: **YES**
-   - Reason: Need context to ensure modifications are accurate and contextually appropriate
-
-3. **delete** - Removing items, sections, or content
-   - Requires data sources: **NO**
-   - Reason: Deletion only needs to identify what to remove, no new content generation needed
-
-4. **move** - Moving items to different positions or parent sections
-   - Requires data sources: **NO**
-   - Reason: Only changing item location in the structure, no content changes needed
-
-5. **reorder** - Changing the order of items at the same level
-   - Requires data sources: **NO**
-   - Reason: Only rearranging sequence, no content generation needed
-
-6. **mixed** - Combination of multiple intent types
-   - Requires data sources: **Depends on whether add/edit operations are included**
-   - Reason: If the feedback includes any add or edit operations, data sources are needed
-
-**Decision Logic:**
-- If the feedback contains ANY add or edit operations → `needDataSources = true`
-- If the feedback ONLY contains delete, move, or reorder operations → `needDataSources = false`
-- When in doubt, default to `needDataSources = true` to ensure sufficient context
-</analysis_rules>
-
-<output_rules>
-Return a JSON object with:
-- `needDataSources`: boolean indicating if data sources are required
-- `intentType`: the primary intent type (add, edit, delete, move, reorder, or mixed)
-- `reason`: clear explanation of why data sources are or aren't needed
-
-Analyze the feedback carefully and be conservative - when uncertain, prefer `needDataSources: true` to ensure sufficient context is available.
-</output_rules>