ai-prompt-guide-mcp 1.0.0

package/dist/markdown-tools.test.js

@@ -0,0 +1,200 @@
+/**
+ * Vitest test suite for markdown CRUD operations
+ */
+import { describe, test, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import os from 'node:os';
+import { promises as fs } from 'node:fs';
+import { readFileSnapshot, writeFileIfUnchanged } from './fsio.js';
+import { listHeadings, buildToc, validateMarkdownStructure } from './parse.js';
+import { readSection, replaceSectionBody, insertRelative, renameHeading, deleteSection } from './sections.js';
+import { titleToSlug } from './slug.js';
+import { createSilentLogger, setGlobalLogger } from './utils/logger.js';
+let tempDir;
+let TEST_FILE;
+let WORKING_FILE;
+let REL_WORKING_FILE;
+beforeAll(() => {
+    // Set up silent logger for tests
+    setGlobalLogger(createSilentLogger());
+});
+beforeEach(async () => {
+    // Create temporary directory for test files
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'markdown-tools-test-'));
+    // Configure docs base path for fsio PathHandler to use temp directory
+    process.env['MCP_WORKSPACE_PATH'] = tempDir;
+    // Set up test file paths
+    TEST_FILE = path.join(tempDir, 'final-result.md');
+    WORKING_FILE = path.join(tempDir, 'working-test.md');
+    REL_WORKING_FILE = 'working-test.md';
+    // Create sample document for tests
+    const sampleDoc = `# API Documentation
+
+## Overview
+
+The API provides REST endpoints for managing resources.
+
+### Authentication
+
+Use Bearer tokens in the Authorization header.
+
+## Endpoints
+
+### Users
+
+#### GET /users
+
+Returns a list of all users.
+
+#### POST /users
+
+Creates a new user account.
+
+### Products
+
+#### GET /products
+
+Returns a list of products.
+
+#### POST /products
+
+Creates a new product.
+`;
+    // Ensure both test files exist with consistent content
+    await fs.writeFile(TEST_FILE, sampleDoc, 'utf8');
+    await fs.writeFile(WORKING_FILE, sampleDoc, 'utf8');
+});
+afterEach(async () => {
+    // Clean up temporary directory and all its contents
+    try {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    }
+    catch {
+        // Ignore if directory doesn't exist
+    }
+});
+describe('Markdown Parsing', () => {
+    test('should parse and list headings with correct hierarchy', async () => {
+        const content = await fs.readFile(TEST_FILE, 'utf8');
+        const headings = listHeadings(content);
+        expect(headings.length).toBeGreaterThan(0);
+        expect(headings[0]?.title).toBe('API Documentation');
+        expect(headings[0]?.depth).toBe(1);
+        expect(headings[0]?.slug).toBe('api-documentation');
+    });
+    test('should build hierarchical table of contents', async () => {
+        const content = await fs.readFile(TEST_FILE, 'utf8');
+        const toc = buildToc(content);
+        expect(toc.length).toBeGreaterThan(0);
+        expect(toc[0]?.title).toBe('API Documentation');
+        expect(toc[0]?.children.length).toBeGreaterThan(0);
+    });
+    test('should validate markdown structure', async () => {
+        const content = await fs.readFile(TEST_FILE, 'utf8');
+        // Should not throw for well-formed document
+        expect(() => validateMarkdownStructure(content)).not.toThrow();
+    });
+});
+describe('Section Reading', () => {
+    test('should read sections by slug', async () => {
+        const content = await fs.readFile(TEST_FILE, 'utf8');
+        const overviewSection = readSection(content, 'overview');
+        expect(overviewSection).not.toBeNull();
+        expect(overviewSection).toContain('## Overview');
+        expect(overviewSection).toContain('REST endpoints');
+        const authSection = readSection(content, 'authentication');
+        expect(authSection).not.toBeNull();
+        expect(authSection).toContain('### Authentication');
+        expect(authSection).toContain('Bearer tokens');
+    });
+    test('should return null for non-existent sections', async () => {
+        const content = await fs.readFile(TEST_FILE, 'utf8');
+        const nonExistent = readSection(content, 'non-existent-section');
+        expect(nonExistent).toBeNull();
+    });
+});
+describe('Section Modification', () => {
+    test('should replace section body', async () => {
+        const content = await fs.readFile(WORKING_FILE, 'utf8');
+        const newContent = 'Updated authentication information.';
+        const updated = replaceSectionBody(content, 'authentication', newContent);
+        expect(updated).toContain(newContent);
+        expect(updated).toContain('### Authentication');
+    });
+    test('should insert sections relative to existing ones', async () => {
+        const content = await fs.readFile(WORKING_FILE, 'utf8');
+        const body = 'This is a new feature.';
+        const updated = insertRelative(content, 'authentication', 'insert_after', 3, 'New Feature', body);
+        expect(updated).toContain('### New Feature');
+        const headings = listHeadings(updated);
+        const authIndex = headings.findIndex(h => h.slug === 'authentication');
+        const newIndex = headings.findIndex(h => h.slug === 'new-feature');
+        expect(newIndex).toBeGreaterThan(authIndex);
+    });
+    test('should rename headings', async () => {
+        const content = await fs.readFile(WORKING_FILE, 'utf8');
+        const updated = renameHeading(content, 'authentication', 'Security');
+        expect(updated).toContain('### Security');
+        expect(updated).not.toContain('### Authentication');
+    });
+    test('should delete sections', async () => {
+        const content = await fs.readFile(WORKING_FILE, 'utf8');
+        const updated = deleteSection(content, 'authentication');
+        expect(updated).not.toContain('### Authentication');
+        expect(updated).not.toContain('Bearer tokens');
+    });
+    test('should delete sections without affecting adjacent sibling sections', () => {
+        const testDoc = `# Document Title
+
+## Overview
+This is the overview section.
+
+## Component Details
+This section has subsections.
+
+### Implementation
+This is the implementation details that we want to delete.
+
+Some implementation content here.
+
+### Usage
+This is the usage section that should remain intact.
+
+Important usage information that must not be deleted.
+
+## Styling
+This is another top-level section.
+`;
+        const result = deleteSection(testDoc, 'implementation');
+        // Implementation section should be gone
+        expect(result).not.toContain('### Implementation');
+        expect(result).not.toContain('This is the implementation details');
+        expect(result).not.toContain('Some implementation content here');
+        // Usage section should be preserved (this was the bug)
+        expect(result).toContain('### Usage');
+        expect(result).toContain('This is the usage section that should remain intact');
+        expect(result).toContain('Important usage information that must not be deleted');
+        // Other sections should be intact
+        expect(result).toContain('## Overview');
+        expect(result).toContain('## Component Details');
+        expect(result).toContain('## Styling');
+    });
+});
+describe('File Operations', () => {
+    test('should handle file mtime preconditions', async () => {
+        // Use the working file path that already exists from beforeEach
+        const snap1 = await readFileSnapshot(REL_WORKING_FILE);
+        // First write should succeed
+        await writeFileIfUnchanged(REL_WORKING_FILE, snap1.mtimeMs, 'Updated content');
+        // Second write with stale mtime should fail
+        await expect(writeFileIfUnchanged(REL_WORKING_FILE, snap1.mtimeMs, 'Another update')).rejects.toThrow('File has been modified by another process');
+    });
+});
+describe('Slug Generation', () => {
+    test('should generate correct slugs', () => {
+        expect(titleToSlug('Hello World')).toBe('hello-world');
+        expect(titleToSlug('API & Documentation')).toBe('api--documentation');
+        expect(titleToSlug('Search & Filtering')).toBe('search--filtering');
+    });
+});
+//# sourceMappingURL=markdown-tools.test.js.map

package/dist/markdown-tools.test.js.map

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

package/dist/parse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Markdown parsing utilities for heading extraction and TOC building
+ */
+import type { Heading, TocNode } from './types/index.js';
+/**
+ * Extracts all headings from markdown with hierarchy information
+ * Uses document-scoped slugger to ensure unique slugs for duplicate titles
+ */
+export declare function listHeadings(markdown: string): readonly Heading[];
+/**
+ * Builds a hierarchical table of contents from markdown
+ */
+export declare function buildToc(markdown: string): readonly TocNode[];
+/**
+ * Validates that a markdown document structure is well-formed
+ * Note: With stateful slugger, duplicate slugs are automatically handled
+ */
+export declare function validateMarkdownStructure(markdown: string): void;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAiB,MAAM,kBAAkB,CAAC;AA0CxE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAkEjE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CA+B7D;AAGD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CA2BhE"}

package/dist/parse.js

@@ -0,0 +1,144 @@
+/**
+ * Markdown parsing utilities for heading extraction and TOC building
+ */
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { toString } from 'mdast-util-to-string';
+import { visitParents } from 'unist-util-visit-parents';
+import GithubSlugger from 'github-slugger';
+import { DEFAULT_LIMITS, ERROR_CODES } from './constants/defaults.js';
+import { validateHeadingDepth } from './shared/validation-utils.js';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+/**
+ * Creates a custom error with code, context, and version information
+ */
+function createError(message, code, context) {
+    const error = new Error(message);
+    return Object.assign(error, {
+        code,
+        context: { ...context, version: packageJson.version }
+    });
+}
+/**
+ * Parses markdown text into an AST
+ */
+function parseMarkdown(markdown) {
+    if (typeof markdown !== 'string') {
+        throw createError('Markdown content must be a string', ERROR_CODES.INVALID_SECTION_CONTENT, { type: typeof markdown });
+    }
+    try {
+        return unified().use(remarkParse).parse(markdown);
+    }
+    catch (error) {
+        throw createError('Failed to parse markdown', ERROR_CODES.INVALID_SECTION_CONTENT, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/**
+ * Extracts all headings from markdown with hierarchy information
+ * Uses document-scoped slugger to ensure unique slugs for duplicate titles
+ */
+export function listHeadings(markdown) {
+    const tree = parseMarkdown(markdown);
+    const headings = [];
+    // Track parent-child relationships through AST traversal
+    let counter = -1;
+    // Use document-scoped slugger for unique slug generation
+    const slugger = new GithubSlugger();
+    visitParents(tree, 'heading', (node) => {
+        counter++;
+        // Validate heading count limit
+        if (counter >= DEFAULT_LIMITS.MAX_HEADINGS_PER_DOCUMENT) {
+            throw createError(`Too many headings in document (max: ${DEFAULT_LIMITS.MAX_HEADINGS_PER_DOCUMENT})`, ERROR_CODES.INVALID_SECTION_CONTENT, { headingCount: counter + 1, maxHeadings: DEFAULT_LIMITS.MAX_HEADINGS_PER_DOCUMENT });
+        }
+        const title = toString(node).trim();
+        // Validate title length
+        if (title.length > DEFAULT_LIMITS.MAX_HEADING_TITLE_LENGTH) {
+            throw createError(`Heading title too long (max: ${DEFAULT_LIMITS.MAX_HEADING_TITLE_LENGTH} characters)`, ERROR_CODES.INVALID_TITLE, { title, length: title.length, maxLength: DEFAULT_LIMITS.MAX_HEADING_TITLE_LENGTH });
+        }
+        if (title.length === 0) {
+            throw createError('Heading title cannot be empty', ERROR_CODES.INVALID_TITLE, { index: counter });
+        }
+        // Use stateful slugger to handle duplicates automatically
+        const slug = slugger.slug(title);
+        const depth = validateHeadingDepth(node.depth);
+        // Find parent heading (nearest previous heading with smaller depth)
+        let parentIndex = null;
+        // Look through already processed headings in reverse order
+        for (let i = headings.length - 1; i >= 0; i--) {
+            const heading = headings[i];
+            if (heading && heading.depth < depth) {
+                parentIndex = i;
+                break;
+            }
+        }
+        headings.push({
+            index: counter,
+            depth,
+            title,
+            slug,
+            parentIndex,
+        });
+    });
+    return headings;
+}
+/**
+ * Builds a hierarchical table of contents from markdown
+ */
+export function buildToc(markdown) {
+    const headings = listHeadings(markdown);
+    const nodes = [];
+    const nodesByIndex = new Map();
+    // Create TocNode for each heading
+    headings.forEach((heading) => {
+        const node = {
+            title: heading.title,
+            slug: heading.slug,
+            depth: heading.depth,
+            children: [],
+        };
+        nodesByIndex.set(heading.index, node);
+        // Add to parent or root
+        if (heading.parentIndex === null) {
+            nodes.push(node);
+        }
+        else {
+            const parent = nodesByIndex.get(heading.parentIndex);
+            if (parent) {
+                parent.children.push(node);
+            }
+            else {
+                // If parent not found, add to root (fallback)
+                nodes.push(node);
+            }
+        }
+    });
+    return nodes;
+}
+/**
+ * Validates that a markdown document structure is well-formed
+ * Note: With stateful slugger, duplicate slugs are automatically handled
+ */
+export function validateMarkdownStructure(markdown) {
+    try {
+        // Parse headings to trigger validation of limits and structure
+        const headings = listHeadings(markdown);
+        // Basic structure validation - the stateful slugger ensures unique slugs
+        // so we don't need to check for duplicates anymore
+        // Verify we have headings if this is called
+        if (headings.length === 0) {
+            // This is actually valid - documents can have no headings
+            return;
+        }
+        // Additional structural validation could be added here if needed
+        // For now, the heading parsing itself handles most validation
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error) {
+            throw error; // Re-throw our custom errors
+        }
+        throw createError('Failed to validate markdown structure', ERROR_CODES.INVALID_SECTION_CONTENT, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/prompts/__tests__/prompt-loader.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for PromptLoader with dual-directory support
+ */
+export {};
+//# sourceMappingURL=prompt-loader.test.d.ts.map

package/dist/prompts/__tests__/prompt-loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-loader.test.d.ts","sourceRoot":"","sources":["../../../src/prompts/__tests__/prompt-loader.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}