@davia/agent 0.1.0

package/dist/agent/tools.js

@@ -0,0 +1,303 @@
+import { tool } from "langchain";
+import { z } from "zod";
+import fs from "fs-extra";
+import * as path from "path";
+import chalk from "chalk";
+import { WRITE_TOOL_DESCRIPTION, SEARCH_REPLACE_TOOL_DESCRIPTION, MULTI_EDIT_TOOL_DESCRIPTION, } from "./prompts/tool_descriptions.js";
+import { getFileCreationMessage, resolveFilePath, parseMermaidWithPuppeteer, robustSearchReplace, getAssetsPath, getBaseDestinationPath, } from "./helpers/tools.js";
+/**
+ * Tool for writing content to a file
+ */
+export const writeTool = tool(async ({ filePath, content }, runtime) => {
+    try {
+        if (!runtime.context) {
+            throw new Error("Runtime context is required");
+        }
+        const context = runtime.context;
+        // Check if this is a mermaid file that needs conversion
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === ".mermaid" || ext === ".mmd") {
+            console.log(chalk.blue("Parsing mermaid to Excalidraw"));
+            // Parse mermaid to Excalidraw using Puppeteer headless browser
+            try {
+                const { elements, files } = await parseMermaidWithPuppeteer(content);
+                // Create JSON file path by replacing extension
+                const jsonFilePath = filePath.replace(/\.(mermaid|mmd)$/, ".json");
+                const absoluteJsonPath = resolveFilePath(jsonFilePath, context);
+                // Write the JSON file with elements (ensureDir is handled by outputJson)
+                const result = {
+                    elements,
+                };
+                if (files)
+                    result.files = files;
+                await fs.outputJson(absoluteJsonPath, result, { spaces: 2 });
+                console.log(chalk.dim(`  → Converted mermaid to Excalidraw: ${jsonFilePath}`));
+                return `Converted mermaid to Excalidraw diagram. JSON saved to: ${jsonFilePath}`;
+            }
+            catch (error) {
+                console.error(chalk.red("Error parsing mermaid to Excalidraw:"), error instanceof Error ? error.message : String(error));
+                throw new Error(`Error parsing mermaid to Excalidraw. Generate JSON instead.`);
+            }
+        }
+        // For isUpdate mode, ensure file exists in assets first
+        if (context.isUpdate) {
+            const assetsPath = getAssetsPath(context.projectPath);
+            const assetsFilePath = path.join(assetsPath, filePath);
+            // Check if file exists in assets, create it if it doesn't
+            const fileExists = await fs.pathExists(assetsFilePath);
+            if (!fileExists) {
+                await fs.outputFile(assetsFilePath, "");
+            }
+        }
+        // Resolve the absolute path (will use proposed or assets based on isUpdate)
+        const absolutePath = resolveFilePath(filePath, context);
+        // Write the file (ensureDir is handled by outputFile)
+        await fs.outputFile(absolutePath, content, "utf-8");
+        const message = getFileCreationMessage(filePath, context);
+        // getFileCreationMessage already includes chalk formatting, so just log it
+        console.log(message);
+        return `Successfully wrote content to ${filePath}`;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error writing '${filePath}': ${errorMessage}`);
+    }
+}, {
+    name: "write_file",
+    description: WRITE_TOOL_DESCRIPTION,
+    schema: z.object({
+        filePath: z
+            .string()
+            .describe("The relative path to the file to write (e.g., 'page1/page2/file.html', not '/page1/page2/file.html')"),
+        content: z.string().describe("The content to write to the file"),
+    }),
+});
+/**
+ * Tool for searching and replacing text in a file
+ */
+export const searchReplaceTool = tool(async ({ filePath, oldString, newString, replaceAll = false }, runtime) => {
+    try {
+        if (!runtime.context) {
+            throw new Error("Runtime context is required");
+        }
+        const context = runtime.context;
+        // Resolve the absolute path (will use proposed or assets based on isUpdate)
+        const absolutePath = resolveFilePath(filePath, context);
+        // Read the file
+        const originalContent = await fs.readFile(absolutePath, "utf-8");
+        // Perform robust search and replace
+        const { newContent, success, errorMessage } = robustSearchReplace(originalContent, oldString, newString, replaceAll);
+        if (!success) {
+            throw new Error(`Failed to replace string in file '${filePath}': ${errorMessage}`);
+        }
+        // Write the updated content back
+        await fs.writeFile(absolutePath, newContent, "utf-8");
+        return `File '${filePath}' has been edited`;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error editing '${filePath}': ${errorMessage}`);
+    }
+}, {
+    name: "search_replace",
+    description: SEARCH_REPLACE_TOOL_DESCRIPTION,
+    schema: z.object({
+        filePath: z
+            .string()
+            .describe("The relative path to the file to modify (e.g., 'page1/page2/file.html', not '/page1/page2/file.html')"),
+        oldString: z
+            .string()
+            .describe("The exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code)"),
+        newString: z
+            .string()
+            .describe("The exact literal text to replace old_string with (including all whitespace, indentation, newlines, and surrounding code)"),
+        replaceAll: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Replace all occurrences of old_string (default false)"),
+    }),
+});
+/**
+ * Tool for reading file contents
+ */
+export const readFileTool = tool(async ({ filePath }, runtime) => {
+    try {
+        if (!runtime.context) {
+            throw new Error("Runtime context is required");
+        }
+        const context = runtime.context;
+        // If isUpdate, try to read from proposed first, then fallback to assets
+        if (context.isUpdate) {
+            // Files are at projectPath/.davia/proposed or projectPath/.davia/assets
+            const proposedPath = getBaseDestinationPath(context.projectPath, true);
+            const proposedFilePath = path.join(proposedPath, filePath);
+            try {
+                // Try to read from proposed first
+                const content = await fs.readFile(proposedFilePath, "utf-8");
+                return content;
+            }
+            catch {
+                // Fallback to assets
+                const assetsPath = getAssetsPath(context.projectPath);
+                const assetsFilePath = path.join(assetsPath, filePath);
+                const content = await fs.readFile(assetsFilePath, "utf-8");
+                return content;
+            }
+        }
+        // If not isUpdate, read from assets directly
+        const assetsPath = getAssetsPath(context.projectPath);
+        const assetsFilePath = path.join(assetsPath, filePath);
+        const content = await fs.readFile(assetsFilePath, "utf-8");
+        return content;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error(`Path '${filePath}' not found`);
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error reading '${filePath}': ${errorMessage}`);
+    }
+}, {
+    name: "read_file",
+    description: "Reads and returns the complete contents of a specified file. Use this tool to read the content of a file from the filesystem. This tool reads the entire content of a file and returns it as a string. If the file is not found, it returns an error message.",
+    schema: z.object({
+        filePath: z
+            .string()
+            .describe("The relative path to the file to read (e.g., 'page1/page2/file.html', not '/page1/page2/file.html')"),
+    }),
+});
+/**
+ * Tool for deleting a file
+ */
+export const deleteTool = tool(async ({ filePath }, runtime) => {
+    try {
+        if (!runtime.context) {
+            throw new Error("Runtime context is required");
+        }
+        const context = runtime.context;
+        let deleted = false;
+        // Delete from proposed if exists
+        if (context.isUpdate) {
+            const proposedPath = getBaseDestinationPath(context.projectPath, true);
+            const proposedFilePath = path.join(proposedPath, filePath);
+            try {
+                await fs.unlink(proposedFilePath);
+                deleted = true;
+            }
+            catch {
+                // File doesn't exist in proposed, continue
+            }
+        }
+        // Delete from assets
+        const assetsPath = getAssetsPath(context.projectPath);
+        const assetsFilePath = path.join(assetsPath, filePath);
+        try {
+            await fs.unlink(assetsFilePath);
+            deleted = true;
+        }
+        catch {
+            // File doesn't exist in assets
+        }
+        if (!deleted) {
+            throw new Error(`Path '${filePath}' not found`);
+        }
+        return `File '${filePath}' has been deleted`;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new Error(`Path '${filePath}' not found`);
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error deleting '${filePath}': ${errorMessage}`);
+    }
+}, {
+    name: "delete_file",
+    description: "Permanently deletes a specified file from the filesystem. Use this tool to delete a file from the filesystem at the specified path.",
+    schema: z.object({
+        filePath: z
+            .string()
+            .describe("The relative path to the file to delete (e.g., 'page1/page2/file.html', not '/page1/page2/file.html')"),
+    }),
+});
+/**
+ * Tool for making multiple edits to a single file
+ */
+export const multiEditTool = tool(async ({ filePath, edits }, runtime) => {
+    try {
+        if (!runtime.context) {
+            throw new Error("Runtime context is required");
+        }
+        const context = runtime.context;
+        // Validate that edits array is not empty
+        if (!edits || edits.length === 0) {
+            throw new Error("At least one edit operation must be provided");
+        }
+        // Validate each edit operation
+        for (let i = 0; i < edits.length; i++) {
+            const edit = edits[i];
+            if (!edit) {
+                throw new Error(`Edit ${i + 1} is undefined`);
+            }
+            if (!edit.oldString || !edit.newString) {
+                throw new Error(`Edit ${i + 1} must contain 'oldString' and 'newString' fields`);
+            }
+            if (edit.oldString === edit.newString) {
+                throw new Error(`Edit ${i + 1}: oldString and newString must be different`);
+            }
+        }
+        // Resolve the absolute path (will use proposed or assets based on isUpdate)
+        const absolutePath = resolveFilePath(filePath, context);
+        // Read the file once
+        let currentContent = await fs.readFile(absolutePath, "utf-8");
+        // Apply edits sequentially
+        for (let i = 0; i < edits.length; i++) {
+            const edit = edits[i];
+            if (!edit) {
+                throw new Error(`Edit ${i + 1} is undefined`);
+            }
+            const { oldString, newString, replaceAll = false } = edit;
+            const { newContent, success, errorMessage } = robustSearchReplace(currentContent, oldString, newString, replaceAll);
+            if (!success) {
+                throw new Error(`Edit operation ${i + 1} failed: ${errorMessage}`);
+            }
+            // Update current content for next iteration
+            currentContent = newContent;
+        }
+        // Write the final content
+        await fs.writeFile(absolutePath, currentContent, "utf-8");
+        const editCount = edits.length;
+        return `File '${filePath}' has been edited with ${editCount} operation${editCount > 1 ? "s" : ""}`;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error editing '${filePath}': ${errorMessage}`);
+    }
+}, {
+    name: "multi_edit",
+    description: MULTI_EDIT_TOOL_DESCRIPTION,
+    schema: z.object({
+        filePath: z
+            .string()
+            .describe("The relative path to the file to modify (e.g., 'page1/page2/file.html', not '/page1/page2/file.html')"),
+        edits: z
+            .array(z.object({
+            oldString: z
+                .string()
+                .describe("The exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code)"),
+            newString: z
+                .string()
+                .describe("The exact literal text to replace old_string with (including all whitespace, indentation, newlines, and surrounding code)"),
+            replaceAll: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Replace all occurrences of old_string (default false)"),
+        }))
+            .describe("Array of edit operations to perform sequentially on the file"),
+    }),
+});

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maximum number of files to read from a repository
+ */
+export declare const MAX_FILES = 1000;
+/**
+ * Maximum tokens allowed for the entire repository content
+ * Uses the rule of thumb: 4 characters = 1 token
+ */
+export declare const MAX_TOKENS = 130000;
+/**
+ * Maximum number of graph recursion steps for LangGraph agent
+ * Default is 25, we increase it for complex documentation generation tasks
+ */
+export declare const GRAPH_RECURSION_LIMIT = 1000;
+export declare const EXCLUDED_FILE_EXTENSIONS: string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,SAAS,OAAQ,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,UAAU,SAAU,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,eAAO,MAAM,wBAAwB,UA6FpC,CAAC"}

package/dist/config.js

@@ -0,0 +1,108 @@
+/**
+ * Maximum number of files to read from a repository
+ */
+export const MAX_FILES = 1_000;
+/**
+ * Maximum tokens allowed for the entire repository content
+ * Uses the rule of thumb: 4 characters = 1 token
+ */
+export const MAX_TOKENS = 130_000;
+/**
+ * Maximum number of graph recursion steps for LangGraph agent
+ * Default is 25, we increase it for complex documentation generation tasks
+ */
+export const GRAPH_RECURSION_LIMIT = 1000;
+export const EXCLUDED_FILE_EXTENSIONS = [
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".tiff",
+    ".tif",
+    ".webp",
+    ".svg",
+    ".ico",
+    ".ttf",
+    ".otf",
+    ".woff",
+    ".woff2",
+    ".eot",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".bin",
+    ".obj",
+    ".o",
+    ".a",
+    ".lib",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".bz2",
+    ".7z",
+    ".rar",
+    ".xz",
+    ".mp3",
+    ".mp4",
+    ".avi",
+    ".mov",
+    ".wmv",
+    ".flv",
+    ".mkv",
+    ".webm",
+    ".wav",
+    ".flac",
+    ".aac",
+    ".ogg",
+    ".m4a",
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".xls",
+    ".xlsx",
+    ".ppt",
+    ".pptx",
+    ".db",
+    ".sqlite",
+    ".sqlite3",
+    ".mdb",
+    ".accdb",
+    ".log",
+    ".logs",
+    ".cache",
+    ".tmp",
+    ".temp",
+    ".swp",
+    ".swo",
+    ".bak",
+    ".pyc",
+    ".min.js",
+    ".min.css",
+    ".bundle.js",
+    ".chunk.js",
+    ".dat",
+    ".data",
+    ".dump",
+    ".backup",
+    ".pem",
+    ".key",
+    ".crt",
+    ".cer",
+    ".p12",
+    ".pfx",
+    ".csv",
+    ".tsv",
+    ".json",
+    ".xml",
+    ".vscode",
+    ".idea",
+    ".sublime-project",
+    ".sublime-workspace",
+    ".DS_Store",
+    "Thumbs.db",
+    ".directory",
+    ".lock",
+    ".pid",
+];

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { runAgent } from "./main.js";
+export { createDaviaAgent } from "./agent/agent.js";
+export * from "./agent/prompts/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { runAgent } from "./main.js";
+export { createDaviaAgent } from "./agent/agent.js";
+export * from "./agent/prompts/index.js";

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export declare function runAgent(projectId: string, projectPath: string, isUpdate: boolean, model: "anthropic" | "openai" | "google", additionalInstructions?: string): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAIA,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,EACxC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiDf"}

package/dist/main.js

@@ -0,0 +1,44 @@
+import { createDaviaAgent } from "./agent/agent.js";
+import { GRAPH_RECURSION_LIMIT } from "./config.js";
+import chalk from "chalk";
+export async function runAgent(projectId, projectPath, isUpdate, model, additionalInstructions) {
+    console.log(chalk.blue.bold("\n🚀 Starting Davia Agent"));
+    console.log(chalk.dim(`   Project Path: ${projectPath}`));
+    console.log(chalk.dim(`   Model: ${chalk.bold(model)}`));
+    try {
+        // Create the agent with the specified model
+        const agent = await createDaviaAgent(model);
+        // Build the user message
+        let userMessage = `Please analyze the source files, perform any necessary transformations, and write the results following the guidelines.`;
+        // Append user's documentation goal if provided
+        if (additionalInstructions) {
+            const goalPrefix = isUpdate
+                ? "User's documentation update goal:"
+                : "User's documentation goal:";
+            userMessage += `\n\n**${goalPrefix}** ${additionalInstructions}\n\nPlease prioritize and incorporate this context when generating the documentation.`;
+        }
+        // Invoke the agent with the initial task
+        await agent.invoke({
+            messages: [
+                {
+                    role: "user",
+                    content: userMessage,
+                },
+            ],
+        }, {
+            recursionLimit: GRAPH_RECURSION_LIMIT,
+            context: {
+                projectId,
+                projectPath,
+                isUpdate,
+                modelName: model,
+            },
+        });
+        console.log(chalk.green.bold("\n✅ Agent completed successfully!"));
+    }
+    catch (error) {
+        console.error(chalk.red.bold("\n❌ Agent failed with error:"));
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@davia/agent",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "AI agent for Davia documentation",
+  "homepage": "https://davia.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davia-labs/davia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davialabs/davia/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@langchain/anthropic": "^1.1.0",
+    "@langchain/core": "^1.0.6",
+    "@langchain/google-genai": "^1.0.2",
+    "@langchain/langgraph": "^1.0.2",
+    "@langchain/openai": "^1.1.2",
+    "chalk": "^5.6.2",
+    "fs-extra": "^11.3.2",
+    "ignore": "^7.0.5",
+    "langchain": "^1.0.6",
+    "puppeteer": "^24.29.1",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.15.3",
+    "eslint": "^9.38.0",
+    "tsx": "^4.19.2",
+    "typescript": "5.9.2",
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "lint": "eslint --max-warnings 0",
+    "check-types": "tsc --noEmit"
+  }
+}