latitude-mcp-server 2.2.3 → 2.2.4

package/dist/api.js

@@ -398,39 +398,221 @@ async function runDocument(path, parameters, versionUuid = 'live') {
     });
 }
 /**
- * Identify which documents fail validation by testing each one individually.
- * Used when a batch publish fails to provide actionable error messages.
+ * Pre-validate PromptL content locally to catch common issues before API call.
+ * Returns detailed, actionable error messages.
+ */
+function validatePromptLContent(content, _path) {
+    const issues = [];
+    const lines = content.split('\n');
+    // Check for YAML frontmatter
+    if (!content.startsWith('---')) {
+        issues.push({
+            type: 'error',
+            message: 'Missing YAML frontmatter',
+            rootCause: 'PromptL files must start with YAML frontmatter (---).',
+            suggestion: 'Add frontmatter at the beginning:\n---\nprovider: YourProvider\nmodel: your-model\n---',
+        });
+    }
+    // Check for nested role tags (common mistake)
+    const roleStack = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        // Check for opening role tags
+        const openMatches = line.matchAll(/<(system|user|assistant|tool)>/gi);
+        for (const match of openMatches) {
+            const tag = match[1].toLowerCase();
+            if (roleStack.length > 0) {
+                const parent = roleStack[roleStack.length - 1];
+                issues.push({
+                    type: 'error',
+                    message: `Nested role tag: <${tag}> inside <${parent.tag}>`,
+                    rootCause: `Role tags (<system>, <user>, <assistant>, <tool>) cannot be nested. Found <${tag}> at line ${lineNum} inside <${parent.tag}> that started at line ${parent.line}.`,
+                    suggestion: `Move the <${tag}> block outside of <${parent.tag}>. Each role tag must be at the top level. If showing an example, use a code block (\`\`\`yaml) instead of actual role tags.`,
+                    lineNumber: lineNum,
+                    snippet: line.trim(),
+                });
+            }
+            roleStack.push({ tag, line: lineNum });
+        }
+        // Check for closing role tags
+        const closeMatches = line.matchAll(/<\/(system|user|assistant|tool)>/gi);
+        for (const match of closeMatches) {
+            const tag = match[1].toLowerCase();
+            if (roleStack.length > 0 && roleStack[roleStack.length - 1].tag === tag) {
+                roleStack.pop();
+            }
+        }
+    }
+    // Check for unclosed role tags
+    for (const unclosed of roleStack) {
+        issues.push({
+            type: 'error',
+            message: `Unclosed role tag: <${unclosed.tag}>`,
+            rootCause: `The <${unclosed.tag}> tag opened at line ${unclosed.line} is never closed.`,
+            suggestion: `Add </${unclosed.tag}> to close the tag.`,
+            lineNumber: unclosed.line,
+        });
+    }
+    // Check frontmatter has required fields
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (frontmatterMatch) {
+        const frontmatter = frontmatterMatch[1];
+        if (!frontmatter.includes('model:') && !frontmatter.includes('model :')) {
+            issues.push({
+                type: 'error',
+                message: 'Missing model in frontmatter',
+                rootCause: 'PromptL requires a model to be specified in the frontmatter.',
+                suggestion: 'Add model field:\n---\nmodel: gpt-4\n---\n\nOr with provider:\n---\nprovider: openai\nmodel: gpt-4\n---',
+            });
+        }
+    }
+    // Check for empty content after frontmatter
+    const contentAfterFrontmatter = content.replace(/^---[\s\S]*?---/, '').trim();
+    if (!contentAfterFrontmatter) {
+        issues.push({
+            type: 'warning',
+            message: 'Empty prompt content',
+            rootCause: 'The prompt has no content after the frontmatter.',
+            suggestion: 'Add prompt content using role tags:\n<system>\nYour system prompt here\n</system>',
+        });
+    }
+    return issues;
+}
+/**
+ * Identify failing documents using binary search for efficiency.
+ * For N documents, worst case is O(N log N) API calls instead of O(N).
  */
 async function identifyFailingDocuments(changes) {
     const failed = [];
-    for (const change of changes) {
-        if (change.status === 'deleted')
-            continue; // Deletes don't have content validation
-        try {
-            // Create a test draft for this single document
-            const testDraft = await createVersion(`validation-test-${change.path}`);
-            // Push just this document
-            await pushChanges(testDraft.uuid, [change]);
-            // Try to publish - this will fail if document has validation errors
-            await publishVersion(testDraft.uuid);
-            // If we get here, document is valid - the draft was published but that's ok
-            logger.debug(`Document ${change.path} validated successfully`);
-        }
-        catch (error) {
-            // This document failed - capture the error
-            const errorMsg = error instanceof LatitudeApiError
-                ? error.message
-                : (error instanceof Error ? error.message : 'Unknown validation error');
+    const nonDeleteChanges = changes.filter(c => c.status !== 'deleted');
+    if (nonDeleteChanges.length === 0)
+        return failed;
+    // First, run local validation to catch obvious issues without API calls
+    for (const change of nonDeleteChanges) {
+        if (!change.content)
+            continue;
+        const localIssues = validatePromptLContent(change.content, change.path);
+        const errors = localIssues.filter(i => i.type === 'error');
+        if (errors.length > 0) {
+            const mainError = errors[0];
             failed.push({
                 path: change.path,
-                error: errorMsg,
-                content: change.content?.substring(0, 200) + (change.content && change.content.length > 200 ? '...' : ''),
+                error: mainError.message,
+                rootCause: mainError.rootCause,
+                suggestion: mainError.suggestion,
+                lineNumber: mainError.lineNumber,
+                snippet: mainError.snippet,
             });
-            logger.debug(`Document ${change.path} failed validation: ${errorMsg}`);
+        }
+    }
+    // If we found local validation errors, return those first
+    if (failed.length > 0) {
+        logger.info(`Found ${failed.length} document(s) with local validation errors`);
+        return failed;
+    }
+    // If local validation passed, use binary search to find API-level failures
+    logger.info(`Local validation passed, testing ${nonDeleteChanges.length} document(s) against API...`);
+    // For small batches (<=5), test individually
+    if (nonDeleteChanges.length <= 5) {
+        return await testDocumentsIndividually(nonDeleteChanges);
+    }
+    // For larger batches, use binary search
+    return await binarySearchFailures(nonDeleteChanges);
+}
+/**
+ * Test documents individually (for small batches)
+ */
+async function testDocumentsIndividually(changes) {
+    const failed = [];
+    for (const change of changes) {
+        const result = await testSingleDocument(change);
+        if (result) {
+            failed.push(result);
         }
     }
     return failed;
 }
+/**
+ * Test a single document and return failure details if it fails
+ */
+async function testSingleDocument(change) {
+    try {
+        const testDraft = await createVersion(`val-${Date.now()}-${change.path.slice(0, 20)}`);
+        await pushChanges(testDraft.uuid, [change]);
+        await publishVersion(testDraft.uuid);
+        return null; // Success
+    }
+    catch (error) {
+        const errorMsg = error instanceof LatitudeApiError
+            ? error.message
+            : (error instanceof Error ? error.message : 'Unknown error');
+        // Try to provide better root cause based on error patterns
+        let rootCause = 'The Latitude API rejected this document during publish validation.';
+        let suggestion = 'Review the document content for syntax errors or invalid configuration.';
+        if (errorMsg.includes('errors in the updated documents')) {
+            rootCause = 'The document has PromptL syntax or configuration errors that passed local validation but failed server-side validation.';
+            suggestion = 'Check for: 1) Invalid model/provider combination, 2) Malformed schema definition, 3) Invalid template syntax ({{ }}).';
+        }
+        // Run local validation to give more context
+        if (change.content) {
+            const localIssues = validatePromptLContent(change.content, change.path);
+            if (localIssues.length > 0) {
+                const warnings = localIssues.filter(i => i.type === 'warning');
+                if (warnings.length > 0) {
+                    suggestion += `\n\nAdditional observations:\n${warnings.map(w => `- ${w.message}: ${w.suggestion}`).join('\n')}`;
+                }
+            }
+        }
+        return {
+            path: change.path,
+            error: errorMsg,
+            rootCause,
+            suggestion,
+            snippet: change.content?.substring(0, 300),
+        };
+    }
+}
+/**
+ * Use binary search to efficiently find failures in large batches.
+ * Splits the batch in half, tests each half, and recurses on failing halves.
+ */
+async function binarySearchFailures(changes) {
+    // Base case: single document
+    if (changes.length === 1) {
+        const result = await testSingleDocument(changes[0]);
+        return result ? [result] : [];
+    }
+    // Test the entire batch first
+    const batchValid = await testBatch(changes);
+    if (batchValid) {
+        return []; // All documents in this batch are valid
+    }
+    // Batch has failures - split and recurse
+    const mid = Math.floor(changes.length / 2);
+    const left = changes.slice(0, mid);
+    const right = changes.slice(mid);
+    // Test both halves in parallel
+    const [leftFailures, rightFailures] = await Promise.all([
+        binarySearchFailures(left),
+        binarySearchFailures(right),
+    ]);
+    return [...leftFailures, ...rightFailures];
+}
+/**
+ * Test if a batch of documents can be published successfully
+ */
+async function testBatch(changes) {
+    try {
+        const testDraft = await createVersion(`batch-val-${Date.now()}`);
+        await pushChanges(testDraft.uuid, changes);
+        await publishVersion(testDraft.uuid);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Create a synthetic Version object for no-op deploys.
  * Returns a fully populated Version with all required fields.
@@ -511,12 +693,30 @@ async function deployToLive(changes, _versionName) {
         logger.warn('Batch publish failed, identifying problematic documents...');
         const failedDocs = await identifyFailingDocuments(actualChanges);
         if (failedDocs.length > 0) {
-            const errorDetails = failedDocs.map(f => `- ${f.path}: ${f.error}`).join('\n');
+            // Build detailed, actionable error message for LLM consumption
+            const errorLines = [];
+            for (const doc of failedDocs) {
+                errorLines.push(`\n## ❌ ${doc.path}`);
+                errorLines.push(`**Error:** ${doc.error}`);
+                errorLines.push(`**Root Cause:** ${doc.rootCause}`);
+                if (doc.lineNumber) {
+                    errorLines.push(`**Location:** Line ${doc.lineNumber}`);
+                }
+                if (doc.snippet) {
+                    errorLines.push(`**Snippet:** \`${doc.snippet}\``);
+                }
+                errorLines.push(`**Fix:** ${doc.suggestion}`);
+            }
+            const message = `${failedDocs.length} document(s) failed validation:${errorLines.join('\n')}`;
             throw new LatitudeApiError({
                 name: 'DocumentValidationError',
                 errorCode: 'DOCUMENT_VALIDATION_FAILED',
-                message: `${failedDocs.length} document(s) failed validation:\n${errorDetails}`,
-                details: { failedDocuments: failedDocs },
+                message,
+                details: {
+                    failedDocuments: failedDocs,
+                    totalFailed: failedDocs.length,
+                    failedPaths: failedDocs.map(d => d.path),
+                },
             }, 422);
         }
         // Re-throw original error if we couldn't identify specific failures

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "latitude-mcp-server",
-	"version": "2.2.3",
+	"version": "2.2.4",
 	"description": "Simplified MCP server for Latitude.so prompt management - 8 focused tools for push, pull, run, and manage prompts",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",