@aigne/doc-smith 0.8.12-beta.6 → 0.8.12-beta.8

package/prompts/structure/update/user-prompt.md

@@ -20,3 +20,27 @@ Initial Documentation Structure:
 <user_feedback>
 {{ feedback }}
 </user_feedback>
+
+{% include "../../common/afs/afs-tools-usage.md" %}
+
+<instructions>
+
+Objectives:
+  - Create a clear and logical structural plan that comprehensively presents information from the user-provided context while providing users with intuitive navigation paths.
+  - Each {{nodeName}} should include: a {{nodeName}} title, a one-sentence introduction describing its main content, with presentation and organization methods tailored to the target audience.
+
+Processing workflow:
+
+- If user feedback is not in English, translate it to English first to better understand user intent
+- Analyze user feedback to understand the specific intent (add, delete, update, or move sections)
+- Determine which tools to use based on the user's requirements
+- Execute the appropriate operations using available tools
+- Ensure all modifications maintain documentation structure integrity
+- Return 'success' when the latest version of websiteStructure meets user feedback
+
+Rules:
+** All changes must be made using Tools. **
+** Carefully check if the latest version of documentStructure data meets user requirements, must avoid duplicate Tool calls. **
+
+{% include "../../common/afs/use-afs-instruction.md" %}
+</instructions>

package/tests/agents/history/view.test.mjs

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, test, mock, spyOn } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DOC_SMITH_DIR } from "../../../utils/constants/index.mjs";
+import viewHistory from "../../../agents/history/view.mjs";
+
+const TEST_DIR = join(process.cwd(), `${DOC_SMITH_DIR}-test`);
+const ORIGINAL_CWD = process.cwd();
+
+describe("History View", () => {
+  let consoleLogMock;
+
+  beforeEach(async () => {
+    // Clean up test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+
+    // Change to test directory
+    process.chdir(TEST_DIR);
+
+    // Spy on console.log
+    consoleLogMock = spyOn(console, "log");
+  });
+
+  afterEach(() => {
+    // Restore original directory
+    process.chdir(ORIGINAL_CWD);
+
+    // Clean up
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+
+    mock.restore();
+  });
+
+  test("should display message when no history exists", () => {
+    // No history file exists
+    const result = viewHistory();
+
+    expect(result).toEqual({});
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("No update history found"));
+  });
+
+  test("should display formatted history entries", async () => {
+    // Create history file with sample data
+    const historyPath = join(process.cwd(), DOC_SMITH_DIR, "history.yaml");
+    mkdirSync(join(process.cwd(), DOC_SMITH_DIR), { recursive: true });
+
+    const historyData = {
+      entries: [
+        {
+          timestamp: "2023-01-01T00:00:00.000Z",
+          operation: "document_update",
+          feedback: "Updated documentation",
+          documentPath: "/readme.md",
+        },
+        {
+          timestamp: "2023-01-02T00:00:00.000Z",
+          operation: "structure_update",
+          feedback: "Reorganized sections",
+        },
+      ],
+    };
+
+    // Use YAML format instead of JSON
+    const { stringify } = await import("yaml");
+    writeFileSync(historyPath, stringify(historyData), "utf8");
+
+    const result = viewHistory();
+
+    expect(result).toEqual({});
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("📜 Update History"));
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("document_update"));
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("structure_update"));
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("Updated documentation"));
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("Reorganized sections"));
+  });
+
+  test("should handle empty history entries", async () => {
+    // Create history file with empty entries
+    const historyPath = join(process.cwd(), DOC_SMITH_DIR, "history.yaml");
+    mkdirSync(join(process.cwd(), DOC_SMITH_DIR), { recursive: true });
+
+    const historyData = { entries: [] };
+    // Use YAML format instead of JSON
+    const { stringify } = await import("yaml");
+    writeFileSync(historyPath, stringify(historyData), "utf8");
+
+    const result = viewHistory();
+
+    expect(result).toEqual({});
+    expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining("No update history found"));
+  });
+});

package/tests/utils/history-utils.test.mjs

@@ -1,14 +1,17 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test, mock, spyOn } from "bun:test";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
-import { getHistory, isGitAvailable, recordUpdate } from "../../utils/history-utils.mjs";
+import { recordUpdate, getHistory } from "../../utils/history-utils.mjs";
 
+// Mock the child_process module
 const TEST_DIR = join(process.cwd(), `${DOC_SMITH_DIR}-test`);
 const ORIGINAL_CWD = process.cwd();
 
-describe("History Utils - Unified", () => {
-  beforeEach(() => {
+describe("History Utils", () => {
+  let execSyncMock;
+
+  beforeEach(async () => {
     // Clean up test directory
     if (existsSync(TEST_DIR)) {
       rmSync(TEST_DIR, { recursive: true });
@@ -17,6 +20,9 @@ describe("History Utils - Unified", () => {
 
     // Change to test directory
     process.chdir(TEST_DIR);
+
+    // Get the mocked execSync
+    execSyncMock = spyOn(await import("node:child_process"), "execSync");
   });
 
   afterEach(() => {
@@ -27,11 +33,8 @@ describe("History Utils - Unified", () => {
     if (existsSync(TEST_DIR)) {
       rmSync(TEST_DIR, { recursive: true });
     }
-  });
 
-  test("detects git availability", () => {
-    const hasGit = isGitAvailable();
-    expect(typeof hasGit).toBe("boolean");
+    mock.restore();
   });
 
   test("skips recording on empty feedback", () => {
@@ -46,133 +49,158 @@ describe("History Utils - Unified", () => {
     expect(history.entries.length).toBe(0);
   });
 
-  test("records update in YAML", () => {
+  test("git not available - write to YAML only", () => {
+    // Mock git as not available
+    execSyncMock.mockImplementation((command) => {
+      if (command === "git --version") {
+        throw new Error("git: command not found");
+      }
+      throw new Error("Unknown command");
+    });
+
+    // Record update
     recordUpdate({
-      operation: "structure_update",
+      operation: "document_update",
       feedback: "Test feedback",
+      documentPath: "/test",
     });
 
+    // Verify YAML record was created
     const history = getHistory();
     expect(history.entries.length).toBe(1);
     expect(history.entries[0].feedback).toBe("Test feedback");
-    expect(history.entries[0].operation).toBe("structure_update");
+    expect(history.entries[0].operation).toBe("document_update");
+    expect(history.entries[0].documentPath).toBe("/test");
     expect(history.entries[0].timestamp).toBeDefined();
-  });
-
-  test("records document path when provided as string", () => {
-    recordUpdate({
-      operation: "document_update",
-      feedback: "Update document",
-      documentPath: "/getting-started",
-    });
 
-    const history = getHistory();
-    expect(history.entries.length).toBe(1);
-    expect(history.entries[0].documentPath).toBe("/getting-started");
+    // Verify no git repository was created
+    const gitDir = join(process.cwd(), DOC_SMITH_DIR, ".git");
+    expect(existsSync(gitDir)).toBe(false);
   });
 
-  test("records single document path for each update", () => {
-    recordUpdate({
-      operation: "document_update",
-      feedback: "Update single document",
-      documentPath: "/getting-started",
+  test("current directory is git repo - skip git integration", () => {
+    // Mock git as available and in repo
+    execSyncMock.mockImplementation((command) => {
+      if (command === "git --version") {
+        return "git version 2.30.0";
+      }
+      if (command === "git rev-parse --is-inside-work-tree") {
+        return "true";
+      }
+      throw new Error("Unknown command");
     });
 
-    const history = getHistory();
-    expect(history.entries.length).toBe(1);
-    expect(history.entries[0].feedback).toBe("Update single document");
-    expect(history.entries[0].documentPath).toBe("/getting-started");
-  });
-
-  test("does not include documentPath field when documentPath is null", () => {
+    // Record update
     recordUpdate({
       operation: "structure_update",
-      feedback: "Update structure",
-      documentPath: null,
+      feedback: "Structure update",
     });
 
+    // Verify YAML record was created
     const history = getHistory();
     expect(history.entries.length).toBe(1);
-    expect(history.entries[0].documentPath).toBeUndefined();
+    expect(history.entries[0].feedback).toBe("Structure update");
+
+    // Verify no new git repository was created (since we're already in a git repo)
+    const gitDir = join(process.cwd(), DOC_SMITH_DIR, ".git");
+    expect(existsSync(gitDir)).toBe(false);
   });
 
-  test("maintains chronological order (newest first)", () => {
-    recordUpdate({ operation: "structure_update", feedback: "First" });
-    // Small delay to ensure different timestamps
-    const now = Date.now();
-    while (Date.now() === now) {
-      // Wait for next millisecond
-    }
-    recordUpdate({ operation: "document_update", feedback: "Second" });
+  test("write YAML records and commit to git", () => {
+    // Ensure the DOC_SMITH_DIR exists
+    const docSmithDir = join(process.cwd(), DOC_SMITH_DIR);
+    mkdirSync(docSmithDir, { recursive: true });
+
+    // Mock git as available but not in repo
+    execSyncMock.mockImplementation((command) => {
+      if (command === "git --version") {
+        return "git version 2.30.0";
+      }
+      if (command === "git rev-parse --is-inside-work-tree") {
+        throw new Error("not a git repository");
+      }
+      if (command === "git init") {
+        return "Initialized empty Git repository";
+      }
+      if (command === 'git add .gitignore && git commit -m "Initialize doc-smith history"') {
+        return "Initial commit";
+      }
+      if (command === "git add docs/ config.yaml preferences.yml history.yaml") {
+        return "Files added";
+      }
+      if (command === "git diff --cached --quiet") {
+        throw new Error("Has changes");
+      }
+      if (command === 'git commit -m "First update"') {
+        return "Commit successful";
+      }
+      if (command === 'git commit -m "Second update"') {
+        return "Commit successful";
+      }
+      throw new Error("Unknown command: ", command);
+    });
 
-    const history = getHistory();
-    expect(history.entries.length).toBe(2);
-    expect(history.entries[0].feedback).toBe("Second");
-    expect(history.entries[1].feedback).toBe("First");
-  });
+    // Record multiple updates - this should trigger git repo creation and commits
+    recordUpdate({
+      operation: "document_update",
+      feedback: "First update",
+      documentPath: "/first",
+    });
 
-  test("handles multiple updates", () => {
-    recordUpdate({ operation: "structure_update", feedback: "Update 1" });
-    recordUpdate({ operation: "document_update", feedback: "Update 2", documentPath: "/home" });
-    recordUpdate({ operation: "document_update", feedback: "Update 3", documentPath: "/about" });
     recordUpdate({
       operation: "translation_update",
-      feedback: "Update 4",
-      documentPath: "/api",
+      feedback: "Second update",
+      documentPath: "/second",
     });
 
+    // Verify YAML records
     const history = getHistory();
-    expect(history.entries.length).toBe(4);
-    expect(history.entries[0].feedback).toBe("Update 4");
-    expect(history.entries[0].documentPath).toBe("/api");
-    expect(history.entries[1].feedback).toBe("Update 3");
-    expect(history.entries[1].documentPath).toBe("/about");
-    expect(history.entries[2].feedback).toBe("Update 2");
-    expect(history.entries[2].documentPath).toBe("/home");
-    expect(history.entries[3].feedback).toBe("Update 1");
+    expect(history.entries.length).toBe(2);
+    expect(history.entries[0].feedback).toBe("Second update"); // Newest first
+    expect(history.entries[1].feedback).toBe("First update");
+
+    // Verify git commands were called
+    expect(execSyncMock).toHaveBeenCalledWith("git --version", { stdio: "ignore" });
+    expect(execSyncMock).toHaveBeenCalledWith("git rev-parse --is-inside-work-tree", {
+      cwd: process.cwd(),
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    expect(execSyncMock).toHaveBeenCalledWith("git init", {
+      cwd: join(process.cwd(), DOC_SMITH_DIR),
+      stdio: "ignore",
+    });
   });
 
-  test("returns empty history when file does not exist", () => {
-    const history = getHistory();
+  test("query history.yaml - handle various scenarios", () => {
+    // Test empty history
+    let history = getHistory();
     expect(history.entries).toBeDefined();
     expect(history.entries.length).toBe(0);
-  });
 
-  test("handles corrupted history file gracefully", () => {
-    // Create corrupted YAML file
+    // Test corrupted YAML file
     const historyPath = join(process.cwd(), DOC_SMITH_DIR, "history.yaml");
     mkdirSync(join(process.cwd(), DOC_SMITH_DIR), { recursive: true });
-    writeFileSync(historyPath, "invalid: yaml: content: [[[", "utf8");
+    writeFileSync(historyPath, "invalid: yaml: content: 「「「", "utf8");
 
-    const history = getHistory();
+    history = getHistory();
     expect(history.entries).toBeDefined();
     expect(history.entries.length).toBe(0);
-  });
-
-  test(`creates ${DOC_SMITH_DIR} directory if not exists`, () => {
-    recordUpdate({
-      operation: "document_update",
-      feedback: "Test",
-    });
 
-    const docSmithDir = join(process.cwd(), DOC_SMITH_DIR);
-    expect(existsSync(docSmithDir)).toBe(true);
-  });
-
-  test("timestamp is in ISO 8601 format", () => {
-    recordUpdate({
-      operation: "structure_update",
-      feedback: "Test timestamp",
-    });
-
-    const history = getHistory();
-    const timestamp = history.entries[0].timestamp;
-
-    // Validate ISO 8601 format
-    expect(timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
-
-    // Validate it's a valid date
-    const date = new Date(timestamp);
-    expect(date.toISOString()).toBe(timestamp);
+    // Test valid history
+    const validHistory = {
+      entries: [
+        {
+          timestamp: "2023-01-01T00:00:00.000Z",
+          operation: "document_update",
+          feedback: "Valid entry",
+        },
+      ],
+    };
+    writeFileSync(historyPath, JSON.stringify(validHistory), "utf8");
+
+    history = getHistory();
+    expect(history.entries.length).toBe(1);
+    expect(history.entries[0].feedback).toBe("Valid entry");
   });
 });

package/utils/constants/index.mjs

@@ -548,110 +548,3 @@ export const DOC_SMITH_DIR = ".aigne/doc-smith";
 export const TMP_DIR = ".tmp";
 export const TMP_DOCS_DIR = "docs";
 export const TMP_ASSETS_DIR = "assets";
-
-// Default evaluation scoring weights
-export const DEFAULT_EVALUATION_WEIGHTS = {
-  evaluationConfig: {
-    accuracy: {
-      weight: 0.35,
-      description: "Technical correctness of the documentation.",
-      subDimensions: {
-        signatureConsistency: {
-          weight: 0.5,
-          description:
-            "Function signatures match the source code (e.g., OpenAPI spec, TypeScript types).",
-        },
-        linkValidity: {
-          weight: 0.25,
-          description: "No broken internal links or invalid cross-references.",
-        },
-        codeExampleIntegrity: {
-          weight: 0.25,
-          description:
-            "All code blocks are syntactically valid and labeled with the correct language.",
-        },
-      },
-    },
-    coverage: {
-      weight: 0.35,
-      description: "Completeness of documentation for all public components.",
-      subDimensions: {
-        apiCoverage: {
-          weight: 0.4,
-          description: "Percentage of exported functions/classes documented.",
-        },
-        paramReturnCoverage: {
-          weight: 0.3,
-          description: "Percentage of function parameters and return values described.",
-        },
-        changeTracking: {
-          weight: 0.3,
-          description:
-            "All new or modified code since the last commit is reflected in the documentation.",
-        },
-      },
-    },
-    readability: {
-      weight: 0.15,
-      description: "Ease of understanding for human readers.",
-      subDimensions: {
-        clarityScore: {
-          weight: 0.28,
-          description:
-            "Overall clarity including reading coherence, logical flow and translation quality.",
-        },
-        consistency: {
-          weight: 0.12,
-          description: "Terminology, style and formatting are unified and professional.",
-        },
-        contentQuality: {
-          weight: 0.24,
-          description:
-            "Accurate and complete content that adds value with sufficient detail and examples.",
-        },
-        purposeAlignment: {
-          weight: 0.14,
-          description:
-            "Content matches the intended purpose such as quick start, API reference or troubleshooting.",
-        },
-        audienceAlignment: {
-          weight: 0.12,
-          description:
-            "Language and examples match the target audience (e.g., developers, non-technical users).",
-        },
-        knowledgeLevelAlignment: {
-          weight: 0.1,
-          description: "Depth and difficulty fit the readers' knowledge level.",
-        },
-      },
-    },
-    structure: {
-      weight: 0.15,
-      description: "Organization and navigability of the documentation.",
-      subDimensions: {
-        navigability: {
-          weight: 0.2,
-          description: "Table of contents entries correctly link to headings.",
-        },
-        informationScent: {
-          weight: 0.2,
-          description:
-            "Key pages such as Quick Start can be reached within three clicks from the homepage.",
-        },
-        purposeCoverage: {
-          weight: 0.25,
-          description:
-            "Structure covers all selected documentation goals without forcing them into a single page.",
-        },
-        audienceCoverage: {
-          weight: 0.2,
-          description: "Structure covers the main intended audience groups.",
-        },
-        coverageDepthAlignment: {
-          weight: 0.15,
-          description: "Overall balance of conciseness, depth and breadth meets user expectations.",
-        },
-      },
-    },
-  },
-};

package/utils/file-utils.mjs

@@ -12,7 +12,7 @@ import { INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD } from "./constants/index.mjs";
  * @param {string} dir - Directory path to check
  * @returns {boolean} True if inside a git repository
  */
-function isInGitRepository(dir) {
+export function isInGitRepository(dir) {
   try {
     execSync("git rev-parse --is-inside-work-tree", {
       cwd: dir,
@@ -558,3 +558,44 @@ export function getStructurePlanPath(workDir) {
   const cwd = workDir || process.cwd();
   return path.join(cwd, ".aigne", "doc-smith", "output", "structure-plan.json");
 }
+
+/**
+ * Get MIME type from file path based on extension
+ * @param {string} filePath - File path
+ * @returns {string} MIME type
+ */
+export function getMimeType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeTypes = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".mp4": "video/mp4",
+    ".mpeg": "video/mpeg",
+    ".mpg": "video/mpg",
+    ".mov": "video/mov",
+    ".avi": "video/avi",
+    ".flv": "video/x-flv",
+    ".mkv": "video/x-matroska",
+    ".webm": "video/webm",
+    ".wmv": "video/wmv",
+    ".m4v": "video/x-m4v",
+    ".3gpp": "video/3gpp",
+  };
+  return mimeTypes[ext] || "application/octet-stream";
+}
+
+/**
+ * Get media description cache file path
+ * @returns {string} Absolute path to media-description.yaml
+ */
+export function getMediaDescriptionCachePath() {
+  const cwd = process.cwd();
+  return path.join(cwd, ".aigne", "doc-smith", "media-description.yaml");
+}

package/utils/history-utils.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { DOC_SMITH_DIR } from "./constants/index.mjs";
+import { isInGitRepository } from "./file-utils.mjs";
 
 const HISTORY_FILE = "history.yaml";
 
@@ -161,9 +162,8 @@ export function recordUpdate({ operation, feedback, documentPath = null }) {
   // Always record in YAML
   recordUpdateYaml({ operation, feedback, documentPath });
 
-  // Also record in git if available
-  if (isGitAvailable()) {
-    // Initialize git repo on first update if not exists
+  // Also record in git if git is available and not in a git repository
+  if (isGitAvailable() && !isInGitRepository(process.cwd())) {
     ensureGitRepo();
     recordUpdateGit({ feedback });
   } else {