mcp-docs-service 0.3.9 → 0.4.0

package/dist/schemas/index.d.ts

@@ -0,0 +1 @@
+export * from "./tools.js";

package/dist/schemas/index.js

@@ -0,0 +1 @@
+export * from "./tools.js";

package/dist/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,cAAc,YAAY,CAAC"}

package/dist/schemas/tools.d.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+export declare const ToolInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+}, {
+    path?: string | undefined;
+}>;
+export declare const ReadDocumentSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    path: z.ZodString;
+}>, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+export declare const ListDocumentsSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+}>, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}>;
+export declare const GetStructureSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+}>, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}>;
+export declare const GetNavigationSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+}>, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+}>;
+export declare const GetDocsKnowledgeBaseSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+    includeSummaries: z.ZodOptional<z.ZodBoolean>;
+    maxSummaryLength: z.ZodOptional<z.ZodNumber>;
+}>, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+    includeSummaries?: boolean | undefined;
+    maxSummaryLength?: number | undefined;
+}, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+    includeSummaries?: boolean | undefined;
+    maxSummaryLength?: number | undefined;
+}>;
+export declare const WriteDocumentSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    path: z.ZodString;
+    content: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}>, "strip", z.ZodTypeAny, {
+    content: string;
+    path: string;
+    metadata?: Record<string, any> | undefined;
+}, {
+    content: string;
+    path: string;
+    metadata?: Record<string, any> | undefined;
+}>;
+export declare const EditDocumentSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    path: z.ZodString;
+    edits: z.ZodArray<z.ZodObject<{
+        oldText: z.ZodString;
+        newText: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        oldText: string;
+        newText: string;
+    }, {
+        oldText: string;
+        newText: string;
+    }>, "many">;
+}>, "strip", z.ZodTypeAny, {
+    path: string;
+    edits: {
+        oldText: string;
+        newText: string;
+    }[];
+}, {
+    path: string;
+    edits: {
+        oldText: string;
+        newText: string;
+    }[];
+}>;
+export declare const DeleteDocumentSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    path: z.ZodString;
+}>, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+export declare const SearchDocumentsSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    excludePatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodOptional<z.ZodString>;
+}>, "strip", z.ZodTypeAny, {
+    tags?: string[] | undefined;
+    status?: string | undefined;
+    path?: string | undefined;
+    basePath?: string | undefined;
+    query?: string | undefined;
+    excludePatterns?: string[] | undefined;
+}, {
+    tags?: string[] | undefined;
+    status?: string | undefined;
+    path?: string | undefined;
+    basePath?: string | undefined;
+    query?: string | undefined;
+    excludePatterns?: string[] | undefined;
+}>;
+export declare const CheckDocumentationHealthSchema: z.ZodObject<z.objectUtil.extendShape<{
+    path: z.ZodOptional<z.ZodString>;
+}, {
+    basePath: z.ZodOptional<z.ZodString>;
+    checkLinks: z.ZodOptional<z.ZodBoolean>;
+    checkMetadata: z.ZodOptional<z.ZodBoolean>;
+    checkOrphans: z.ZodOptional<z.ZodBoolean>;
+    requiredMetadataFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}>, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+    checkLinks?: boolean | undefined;
+    checkMetadata?: boolean | undefined;
+    checkOrphans?: boolean | undefined;
+    requiredMetadataFields?: string[] | undefined;
+}, {
+    path?: string | undefined;
+    basePath?: string | undefined;
+    checkLinks?: boolean | undefined;
+    checkMetadata?: boolean | undefined;
+    checkOrphans?: boolean | undefined;
+    requiredMetadataFields?: string[] | undefined;
+}>;

package/dist/schemas/tools.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+// Base schema for tool inputs
+export const ToolInputSchema = z.object({
+    path: z.string().optional(),
+});
+// Documentation schemas
+export const ReadDocumentSchema = ToolInputSchema.extend({
+    path: z.string(),
+});
+export const ListDocumentsSchema = ToolInputSchema.extend({
+    basePath: z.string().optional(),
+    recursive: z.boolean().default(false),
+});
+export const GetStructureSchema = ToolInputSchema.extend({
+    basePath: z.string().optional(),
+});
+export const GetNavigationSchema = ToolInputSchema.extend({
+    basePath: z.string().optional(),
+});
+export const GetDocsKnowledgeBaseSchema = ToolInputSchema.extend({
+    basePath: z.string().optional(),
+    includeSummaries: z.boolean().optional(),
+    maxSummaryLength: z.number().optional(),
+});
+export const WriteDocumentSchema = ToolInputSchema.extend({
+    path: z.string(),
+    content: z.string(),
+    createDirectories: z.boolean().default(true),
+});
+export const EditDocumentSchema = ToolInputSchema.extend({
+    path: z.string(),
+    edits: z.array(z.object({
+        oldText: z.string(),
+        newText: z.string(),
+    })),
+    dryRun: z.boolean().default(false),
+});
+export const DeleteDocumentSchema = ToolInputSchema.extend({
+    path: z.string(),
+});
+export const SearchDocumentsSchema = ToolInputSchema.extend({
+    query: z.string(),
+    basePath: z.string().optional().default(""),
+});
+export const CheckDocumentationHealthSchema = ToolInputSchema.extend({
+    basePath: z.string().optional().default(""),
+});

package/dist/schemas/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/schemas/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8BAA8B;AAC9B,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH,wBAAwB;AACxB,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,eAAe,CAAC,MAAM,CAAC;IAC/D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACxC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC;IACxD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC,MAAM,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,KAAK,CACZ,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;KACpB,CAAC,CACH;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC,MAAM,CAAC;IACzD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC,MAAM,CAAC;IAC1D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC/C,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,eAAe,CAAC,MAAM,CAAC;IACnE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAClC,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACrC,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACpC,sBAAsB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC"}

package/dist/types/docs.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Metadata for documentation files
+ */
+export interface DocumentMetadata {
+    title?: string;
+    order?: number;
+    description?: string;
+    author?: string;
+    date?: Date;
+    tags?: string[];
+    status?: string;
+    [key: string]: any;
+}
+/**
+ * Entry for a documentation file
+ */
+export interface DocumentEntry {
+    path: string;
+    name: string;
+    metadata: DocumentMetadata;
+}
+/**
+ * Tree entry for documentation structure
+ */
+export interface TreeEntry {
+    name: string;
+    path: string;
+    type: string;
+    metadata?: DocumentMetadata;
+    children: TreeEntry[];
+    error?: string;
+}
+/**
+ * Navigation item for documentation
+ */
+export interface NavigationItem {
+    title: string;
+    path: string | null;
+    order: number;
+    items?: NavigationItem[];
+}
+/**
+ * Navigation section for documentation
+ */
+export interface NavigationSection {
+    title: string;
+    path: string | null;
+    items: NavigationItem[];
+    order: number;
+}
+/**
+ * Health issue for documentation
+ */
+export interface HealthIssue {
+    path: string;
+    type: "missing_metadata" | "broken_link" | "orphaned" | "missing_reference";
+    severity: "error" | "warning" | "info";
+    message: string;
+    details?: any;
+}
+/**
+ * Health check result for documentation
+ */
+export interface HealthCheckResult {
+    score: number;
+    totalDocuments: number;
+    issues: HealthIssue[];
+    metadataCompleteness: number;
+    brokenLinks: number;
+    orphanedDocuments: number;
+    missingReferences: number;
+    documentsByStatus?: Record<string, number>;
+    documentsByTag?: Record<string, number>;
+}

package/dist/types/docs.js

@@ -0,0 +1 @@
+export {};

package/dist/types/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/types/docs.ts"],"names":[],"mappings":""}

package/dist/types/file.d.ts

@@ -0,0 +1,21 @@
+/**
+ * File information structure
+ */
+export interface FileInfo {
+    size: number;
+    created: Date;
+    modified: Date;
+    accessed: Date;
+    isDirectory: boolean;
+    isFile: boolean;
+    permissions: string;
+}
+/**
+ * Tree entry for directory structure
+ */
+export interface FileTreeEntry {
+    name: string;
+    path: string;
+    type: "file" | "directory";
+    children?: FileTreeEntry[];
+}

package/dist/types/file.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file.js.map

package/dist/types/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/types/file.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -0,0 +1,44 @@
+export interface DocumentMetadata {
+    title?: string;
+    order?: number;
+    description?: string;
+    author?: string;
+    date?: Date;
+    tags?: string[];
+    status?: string;
+    [key: string]: any;
+}
+export interface DocumentEntry {
+    path: string;
+    name: string;
+    metadata: DocumentMetadata;
+}
+export interface TreeEntry {
+    name: string;
+    path: string;
+    type: string;
+    metadata?: DocumentMetadata;
+    children: TreeEntry[];
+    error?: string;
+}
+export interface NavigationItem {
+    title: string;
+    path: string | null;
+    order: number;
+}
+export interface NavigationSection {
+    title: string;
+    path: string | null;
+    items: NavigationItem[];
+    order: number;
+}
+export type ToolResponse = {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    metadata?: Record<string, any>;
+    isError?: boolean;
+};
+export * from "./docs.js";
+export * from "./tools.js";

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "./docs.js";
+export * from "./tools.js";

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAiDA,+CAA+C;AAC/C,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/types/tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Standard response format for tools
+ */
+export type ToolResponse = {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    metadata?: Record<string, any>;
+    isError?: boolean;
+};

package/dist/types/tools.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":""}

package/dist/utils/file.d.ts

@@ -0,0 +1,24 @@
+import { FileInfo } from "../types/file.js";
+/**
+ * Gets file statistics and information
+ */
+export declare function getFileStats(filePath: string): Promise<FileInfo>;
+/**
+ * Searches for files matching a pattern
+ */
+export declare function searchFiles(rootPath: string, pattern: string, excludePatterns?: string[]): Promise<string[]>;
+/**
+ * Normalizes line endings to LF
+ */
+export declare function normalizeLineEndings(text: string): string;
+/**
+ * Creates a unified diff between two text contents
+ */
+export declare function createUnifiedDiff(originalContent: string, newContent: string, filepath?: string): string;
+/**
+ * Applies edits to a file
+ */
+export declare function applyFileEdits(filePath: string, edits: Array<{
+    oldText: string;
+    newText: string;
+}>, dryRun?: boolean): Promise<string>;

package/dist/utils/file.js

@@ -0,0 +1,94 @@
+import fs from "fs/promises";
+import path from "path";
+import { createTwoFilesPatch } from "diff";
+import { minimatch } from "minimatch";
+/**
+ * Gets file statistics and information
+ */
+export async function getFileStats(filePath) {
+    const stats = await fs.stat(filePath);
+    // Convert file mode to permission string (e.g., "rwxr-xr-x")
+    const mode = stats.mode;
+    const permissions = [
+        stats.mode & 0o400 ? "r" : "-",
+        stats.mode & 0o200 ? "w" : "-",
+        stats.mode & 0o100 ? "x" : "-",
+        stats.mode & 0o040 ? "r" : "-",
+        stats.mode & 0o020 ? "w" : "-",
+        stats.mode & 0o010 ? "x" : "-",
+        stats.mode & 0o004 ? "r" : "-",
+        stats.mode & 0o002 ? "w" : "-",
+        stats.mode & 0o001 ? "x" : "-",
+    ].join("");
+    return {
+        size: stats.size,
+        created: stats.birthtime,
+        modified: stats.mtime,
+        accessed: stats.atime,
+        isDirectory: stats.isDirectory(),
+        isFile: stats.isFile(),
+        permissions,
+    };
+}
+/**
+ * Searches for files matching a pattern
+ */
+export async function searchFiles(rootPath, pattern, excludePatterns = []) {
+    const results = [];
+    async function search(currentPath) {
+        const entries = await fs.readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(currentPath, entry.name);
+            const relativePath = path.relative(rootPath, entryPath);
+            // Check if path should be excluded
+            if (excludePatterns.some((excludePattern) => minimatch(relativePath, excludePattern))) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await search(entryPath);
+            }
+            else if (minimatch(relativePath, pattern)) {
+                results.push(entryPath);
+            }
+        }
+    }
+    await search(rootPath);
+    return results;
+}
+/**
+ * Normalizes line endings to LF
+ */
+export function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, "\n");
+}
+/**
+ * Creates a unified diff between two text contents
+ */
+export function createUnifiedDiff(originalContent, newContent, filepath = "file") {
+    return createTwoFilesPatch(filepath, filepath, normalizeLineEndings(originalContent), normalizeLineEndings(newContent), "", "", { context: 3 });
+}
+/**
+ * Applies edits to a file
+ */
+export async function applyFileEdits(filePath, edits, dryRun = false) {
+    let content = await fs.readFile(filePath, "utf-8");
+    content = normalizeLineEndings(content);
+    // Apply all edits
+    for (const edit of edits) {
+        const { oldText, newText } = edit;
+        const normalizedOldText = normalizeLineEndings(oldText);
+        if (!content.includes(normalizedOldText)) {
+            throw new Error(`Edit failed: Could not find text to replace in ${filePath}`);
+        }
+        content = content.replace(normalizedOldText, normalizeLineEndings(newText));
+    }
+    // Create a diff to show changes
+    const originalContent = await fs.readFile(filePath, "utf-8");
+    const diff = createUnifiedDiff(originalContent, content, filePath);
+    // Write the changes if not a dry run
+    if (!dryRun) {
+        await fs.writeFile(filePath, content);
+    }
+    return diff;
+}
+//# sourceMappingURL=file.js.map

package/dist/utils/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/utils/file.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./path.js";

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from "./path.js";
+export * from "./logging.js";

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,cAAc,WAAW,CAAC"}

package/dist/utils/logging.js

@@ -0,0 +1,27 @@
+/**
+ * Logging utilities for the MCP Docs Service
+ *
+ * These utilities ensure that logs don't interfere with the MCP protocol communication.
+ */
+// Environment detection for different execution contexts
+export const isCursorWrapper = process.env.MCP_CURSOR_WRAPPER === "true";
+export const isNpxWrapper = process.env.MCP_NPX_WRAPPER === "true";
+export const isInspector = process.env.MCP_INSPECTOR === "true";
+/**
+ * Safe logging function that won't interfere with MCP protocol
+ * When running under Cursor or NPX, redirects all logs to stderr
+ */
+export const safeLog = (...args) => {
+    if (isCursorWrapper || isNpxWrapper) {
+        console.error(...args);
+    }
+    else {
+        console.log(...args);
+    }
+};
+/**
+ * Safe error logging function
+ */
+export const safeError = (...args) => {
+    console.error(...args);
+};

package/dist/utils/path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Normalizes a path consistently
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Expands the home directory in a path (e.g., ~/docs -> /home/user/docs)
+ */
+export declare function expandHome(p: string): string;
+/**
+ * Validates that a path is within allowed directories
+ * @param p The path to validate
+ * @param allowedDirectories Array of allowed directory paths
+ * @returns The normalized path if valid
+ * @throws Error if path is not within allowed directories
+ */
+export declare function validatePath(p: string, allowedDirectories: string[]): Promise<string>;

package/dist/utils/path.js

@@ -0,0 +1,69 @@
+import path from "path";
+import os from "os";
+import fs from "fs/promises";
+/**
+ * Normalizes a path consistently
+ */
+export function normalizePath(p) {
+    return path.normalize(p);
+}
+/**
+ * Expands the home directory in a path (e.g., ~/docs -> /home/user/docs)
+ */
+export function expandHome(p) {
+    if (!p)
+        return p;
+    if (p === "~" || p.startsWith("~/")) {
+        return p.replace(/^~/, os.homedir());
+    }
+    return p;
+}
+/**
+ * Validates that a path is within allowed directories
+ * @param p The path to validate
+ * @param allowedDirectories Array of allowed directory paths
+ * @returns The normalized path if valid
+ * @throws Error if path is not within allowed directories
+ */
+export async function validatePath(p, allowedDirectories) {
+    // Handle empty path by using the first allowed directory
+    if (!p) {
+        return allowedDirectories[0];
+    }
+    // Resolve the path
+    const normalizedPath = normalizePath(path.resolve(expandHome(p)));
+    // Check if the path is exactly an allowed directory
+    if (allowedDirectories.some((dir) => dir === normalizedPath)) {
+        return normalizedPath;
+    }
+    // Check if the path is within any of the allowed directories
+    const isAllowed = allowedDirectories.some((dir) => {
+        const relativePath = path.relative(dir, normalizedPath);
+        return (relativePath !== "" &&
+            !relativePath.startsWith("..") &&
+            !path.isAbsolute(relativePath));
+    });
+    if (!isAllowed) {
+        // Try to resolve the path relative to the allowed directories
+        for (const dir of allowedDirectories) {
+            const resolvedPath = path.resolve(dir, p);
+            try {
+                // Check if the path exists
+                await fs.access(resolvedPath);
+                // If it exists, check if it's within an allowed directory
+                const relativePath = path.relative(dir, resolvedPath);
+                if (relativePath !== "" &&
+                    !relativePath.startsWith("..") &&
+                    !path.isAbsolute(relativePath)) {
+                    return resolvedPath;
+                }
+            }
+            catch (error) {
+                // Path doesn't exist, continue to the next directory
+            }
+        }
+        // If we get here, the path is not allowed
+        throw new Error(`Access denied: ${p} is not within allowed directories. Allowed directories: ${allowedDirectories.join(", ")}`);
+    }
+    return normalizedPath;
+}

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,CAAS,EACT,kBAA4B;IAE5B,yDAAyD;IACzD,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED,mBAAmB;IACnB,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElE,oDAAoD;IACpD,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,cAAc,CAAC,EAAE,CAAC;QAC7D,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,6DAA6D;IAC7D,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QAChD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QACxD,OAAO,CACL,YAAY,KAAK,EAAE;YACnB,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC;YAC9B,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAC/B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,8DAA8D;QAC9D,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;YACrC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC1C,IAAI,CAAC;gBACH,2BAA2B;gBAC3B,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBAC9B,0DAA0D;gBAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;gBACtD,IACE,YAAY,KAAK,EAAE;oBACnB,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC;oBAC9B,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAC9B,CAAC;oBACD,OAAO,YAAY,CAAC;gBACtB,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,qDAAqD;YACvD,CAAC;QACH,CAAC;QAED,0CAA0C;QAC1C,MAAM,IAAI,KAAK,CACb,kBAAkB,CAAC,4DAA4D,kBAAkB,CAAC,IAAI,CACpG,IAAI,CACL,EAAE,CACJ,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC"}