seomd-cli 1.0.0

package/src/utils/writeback.js

@@ -0,0 +1,130 @@
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
+import { writeSeoMd } from './parser.js';
+
+/**
+ * Merges platform analysis blocks back into the SEO.md YAML document.
+ * 
+ * @param {YAML.Document} doc - The YAML Document of SEO.md
+ * @param {any} response - The API response from analyze/sync
+ * @param {string} cwd - Current working directory
+ */
+export async function writeAnalysisToSeoMd(doc, response, cwd) {
+    const lastAnalyzed = response.aeo_analysis.last_analyzed;
+    const nextAnalysis = response.aeo_analysis.next_analysis;
+
+    // 1. Update AEO analysis
+    doc.setIn(['aeo', '_analysis', 'source'], 'foxcite');
+    doc.setIn(['aeo', '_analysis', 'overall_citation_rate'], response.aeo_analysis.overall_citation_rate);
+    doc.setIn(['aeo', '_analysis', 'overall_gap_score'], response.aeo_analysis.overall_gap_score);
+    doc.setIn(['aeo', '_analysis', 'engines_tracked'], response.aeo_analysis.engines_tracked);
+    doc.setIn(['aeo', '_analysis', 'last_analyzed'], lastAnalyzed);
+    doc.setIn(['aeo', '_analysis', 'next_analysis'], nextAnalysis);
+
+    // 2. Update Intent analysis
+    doc.setIn(['intent', '_analysis', 'source'], 'foxcite');
+    doc.setIn(['intent', '_analysis', 'last_analyzed'], lastAnalyzed);
+    doc.setIn(['intent', '_analysis', 'next_analysis'], nextAnalysis);
+
+    const categories = ['informational', 'comparison', 'transactional', 'reputational', 'category'];
+    for (const cat of categories) {
+        if (response.intent_analysis && response.intent_analysis[cat]) {
+            doc.setIn(['intent', '_analysis', cat, 'citation_rate'], response.intent_analysis[cat].citation_rate);
+            doc.setIn(['intent', '_analysis', cat, 'top_cited_competitor'], response.intent_analysis[cat].top_cited_competitor);
+            doc.setIn(['intent', '_analysis', cat, 'gap_score'], response.intent_analysis[cat].gap_score);
+            doc.setIn(['intent', '_analysis', cat, 'trend'], response.intent_analysis[cat].trend || 'stable');
+        }
+    }
+
+    // 3. Update Pages analysis
+    doc.setIn(['pages', '_analysis', 'source'], 'foxcite');
+    doc.setIn(['pages', '_analysis', 'last_analyzed'], lastAnalyzed);
+
+    const pageSummaries = response.page_analysis.map(p => ({
+        id: p.id,
+        url: p.url,
+        citation_rate: p.citation_rate,
+        gap_score: p.gap_score,
+        top_cited_competitor: p.top_cited_competitor
+    }));
+    doc.setIn(['pages', '_analysis', 'pages'], pageSummaries);
+    doc.setIn(['pages', '_analysis', 'missing_pages'], []);
+    doc.setIn(['pages', '_analysis', 'build_order_recommendation'], []);
+
+    // 4. Update Keywords analysis
+    doc.setIn(['keywords', '_analysis', 'source'], 'foxcite');
+    doc.setIn(['keywords', '_analysis', 'last_analyzed'], lastAnalyzed);
+    doc.setIn(['keywords', '_analysis', 'next_analysis'], nextAnalysis);
+
+    // Write back to SEO.md
+    await writeSeoMd(doc, cwd);
+}
+
+/**
+ * Generates and writes the SEO.REVERSE.md file.
+ * 
+ * @param {string} cwd - Current working directory
+ * @param {any} response - The API response from analyze/sync
+ */
+export async function writeReverseMd(cwd, response) {
+    const reversePath = path.join(cwd, 'SEO.REVERSE.md');
+
+    const reversePages = response.page_analysis.map(p => ({
+        id: p.id,
+        url: p.url,
+        status: p.status || 'planned',
+        citation_rate: p.citation_rate,
+        gap_score: p.gap_score,
+        top_cited_competitor: p.top_cited_competitor,
+        why_page_won: p.why_page_won || [],
+        citation_hooks: p.citation_hooks || [],
+        gaps_for_my_brand: p.gaps_for_brand || [],
+        remediation_playbook: p.remediation_playbook || [],
+        fastest_win: p.fastest_win || { action: null, estimated_gap_score_improvement: null, effort: null },
+        suggested_content_outline: p.suggested_content_outline || []
+    }));
+
+    const primaryCompetitor = response.intent_analysis?.comparison?.top_cited_competitor || 'None';
+
+    const reverseDoc = {
+        domain: response.domain || 'example.com',
+        brand: response.brand_name || 'My Brand',
+        primary_competitor: primaryCompetitor,
+        last_analyzed: response.aeo_analysis.last_analyzed,
+        next_analysis: response.aeo_analysis.next_analysis,
+        source: 'foxcite',
+        pages: reversePages
+    };
+
+    const header = `# SEO.REVERSE.md
+#
+# This file is generated by the foxcite platform.
+# Do not edit manually — run \`npx seomd analyze\` to update.
+# Run \`npx seomd sync\` to pull latest intelligence.
+
+`;
+
+    const yamlContent = YAML.stringify(reverseDoc);
+    await fs.writeFile(reversePath, header + yamlContent, 'utf8');
+}
+
+/**
+ * Writes individual page playbooks into .seomd/pages/{id}.md files.
+ * 
+ * @param {string} cwd - Current working directory
+ * @param {any} response - The API response from analyze/sync
+ */
+export async function writePageAnalysis(cwd, response) {
+    const seomdDir = path.join(cwd, '.seomd');
+    const pagesDir = path.join(seomdDir, 'pages');
+
+    await fs.ensureDir(pagesDir);
+
+    for (const page of response.page_analysis) {
+        if (page.markdown_content) {
+            const filePath = path.join(pagesDir, `${page.id}.md`);
+            await fs.writeFile(filePath, page.markdown_content, 'utf8');
+        }
+    }
+}

package/src/validators/seomd.js

@@ -0,0 +1,211 @@
+import { SITE_TYPES, INTENT_CATEGORIES } from '../utils/constants.js';
+
+/**
+ * Validates a parsed seo.md configuration object against the spec.
+ * 
+ * @param {any} data - The parsed seo.md JS object
+ * @returns {{errors: Array<{path: string, message: string}>, warnings: Array<{path: string, message: string}>}} Validation results
+ */
+export function validateSeoMd(data) {
+    const errors = [];
+    const warnings = [];
+
+    if (!data || typeof data !== 'object') {
+        errors.push({ path: '', message: 'Specification must be a valid YAML object' });
+        return { errors, warnings };
+    }
+
+    // 1. Required top-level sections
+    const requiredSections = [
+        'site',
+        'identity',
+        'keywords',
+        'intent',
+        'pages',
+        'schema',
+        'crawl',
+        'performance',
+        'monitoring'
+    ];
+
+    for (const section of requiredSections) {
+        if (!(section in data) || data[section] === null) {
+            errors.push({ path: section, message: `Missing required top-level section: '${section}'` });
+        }
+    }
+
+    // If critical sections are missing, stop early to avoid nested property access errors
+    if (errors.some(e => ['site', 'identity', 'keywords', 'intent', 'pages'].includes(e.path))) {
+        return { errors, warnings };
+    }
+
+    // 2. Validate 'site' section
+    const site = data.site || {};
+    const validSiteTypes = SITE_TYPES.map(t => t.value);
+    
+    if (!site.type) {
+        errors.push({ path: 'site.type', message: 'site.type is required' });
+    } else if (!validSiteTypes.includes(site.type)) {
+        errors.push({ 
+            path: 'site.type', 
+            message: `Invalid site.type '${site.type}'. Must be one of: ${validSiteTypes.join(', ')}` 
+        });
+    }
+
+    if (!site.domain) {
+        errors.push({ path: 'site.domain', message: 'site.domain is required' });
+    } else if (typeof site.domain !== 'string') {
+        errors.push({ path: 'site.domain', message: 'site.domain must be a string' });
+    }
+
+    if (site.canonical && typeof site.canonical !== 'string') {
+        errors.push({ path: 'site.canonical', message: 'site.canonical must be a string' });
+    }
+
+    // 3. Validate 'identity' section
+    const identity = data.identity || {};
+    if (!identity.brand) {
+        errors.push({ path: 'identity.brand', message: 'identity.brand is required' });
+    } else if (typeof identity.brand !== 'string') {
+        errors.push({ path: 'identity.brand', message: 'identity.brand must be a string' });
+    }
+
+    if (!identity.tagline) {
+        warnings.push({ path: 'identity.tagline', message: 'identity.tagline is missing or empty' });
+    }
+
+    // 4. Validate 'keywords' section
+    const keywords = data.keywords || {};
+    if (!keywords.primary) {
+        errors.push({ path: 'keywords.primary', message: 'keywords.primary is required' });
+    } else if (typeof keywords.primary !== 'string') {
+        errors.push({ path: 'keywords.primary', message: 'keywords.primary must be a string' });
+    }
+
+    if (!keywords.secondary || !Array.isArray(keywords.secondary) || keywords.secondary.length === 0) {
+        warnings.push({ path: 'keywords.secondary', message: 'keywords.secondary is empty. Consider adding target secondary terms.' });
+    }
+
+    if (!keywords.negative || !Array.isArray(keywords.negative)) {
+        warnings.push({ path: 'keywords.negative', message: 'keywords.negative should be an array of terms to filter out' });
+    }
+
+    if (!keywords.long_tail || !Array.isArray(keywords.long_tail) || keywords.long_tail.length === 0) {
+        warnings.push({ path: 'keywords.long_tail', message: 'keywords.long_tail is empty. Consider adding long-tail variations.' });
+    }
+
+    // 5. Validate 'intent' section
+    const intent = data.intent || {};
+    for (const cat of INTENT_CATEGORIES) {
+        const catData = intent[cat];
+        if (!catData || typeof catData !== 'object') {
+            errors.push({ path: `intent.${cat}`, message: `Missing or invalid intent category: 'intent.${cat}'` });
+            continue;
+        }
+
+        const validPriorities = ['low', 'medium', 'high', 'critical'];
+        if (!catData.priority) {
+            errors.push({ path: `intent.${cat}.priority`, message: `intent.${cat}.priority is required` });
+        } else if (!validPriorities.includes(String(catData.priority).toLowerCase())) {
+            errors.push({ 
+                path: `intent.${cat}.priority`, 
+                message: `Invalid priority '${catData.priority}' for intent.${cat}. Must be one of: ${validPriorities.join(', ')}` 
+            });
+        }
+
+        if (!catData.queries || !Array.isArray(catData.queries)) {
+            errors.push({ path: `intent.${cat}.queries`, message: `intent.${cat}.queries must be an array` });
+        } else if (catData.queries.length === 0) {
+            warnings.push({ path: `intent.${cat}.queries`, message: `intent.${cat}.queries list is empty. Add queries to track.` });
+        }
+    }
+
+    // 6. Validate 'pages' section
+    const pages = data.pages || {};
+    if (!pages.required || !Array.isArray(pages.required)) {
+        errors.push({ path: 'pages.required', message: 'pages.required must be an array' });
+    } else if (pages.required.length === 0) {
+        errors.push({ path: 'pages.required', message: 'pages.required array cannot be empty' });
+    } else {
+        pages.required.forEach((page, index) => {
+            const prefix = `pages.required[${index}]`;
+            if (!page || typeof page !== 'object') {
+                errors.push({ path: prefix, message: `Page entry at index ${index} must be an object` });
+                return;
+            }
+
+            if (!page.id) {
+                errors.push({ path: `${prefix}.id`, message: `Page at index ${index} is missing 'id'` });
+            }
+            if (!page.url) {
+                errors.push({ path: `${prefix}.url`, message: `Page '${page.id || index}' is missing 'url'` });
+            }
+            
+            const validStatus = ['live', 'draft', 'planned'];
+            if (!page.status) {
+                errors.push({ path: `${prefix}.status`, message: `Page '${page.id || index}' is missing 'status'` });
+            } else if (!validStatus.includes(page.status)) {
+                errors.push({ 
+                    path: `${prefix}.status`, 
+                    message: `Invalid status '${page.status}' for page '${page.id || index}'. Must be one of: ${validStatus.join(', ')}` 
+                });
+            }
+
+            if (page.priority === undefined || page.priority === null) {
+                errors.push({ path: `${prefix}.priority`, message: `Page '${page.id || index}' is missing 'priority'` });
+            } else if (typeof page.priority !== 'number') {
+                errors.push({ path: `${prefix}.priority`, message: `Priority for page '${page.id || index}' must be a number` });
+            }
+        });
+    }
+
+    // 7. Validate 'schema' section
+    const schema = data.schema || {};
+    if (schema.types && !Array.isArray(schema.types)) {
+        errors.push({ path: 'schema.types', message: 'schema.types must be an array' });
+    }
+
+    // 8. Validate 'crawl' section
+    const crawl = data.crawl || {};
+    if (crawl.sitemap && typeof crawl.sitemap !== 'string') {
+        errors.push({ path: 'crawl.sitemap', message: 'crawl.sitemap must be a string' });
+    }
+    if (crawl.robots_txt && typeof crawl.robots_txt !== 'string') {
+        errors.push({ path: 'crawl.robots_txt', message: 'crawl.robots_txt must be a string' });
+    }
+
+    // 9. Validate 'performance' section
+    const perf = data.performance || {};
+    const stringFields = ['lcp', 'cls', 'fid', 'page_size', 'ttfb'];
+    for (const field of stringFields) {
+        if (perf[field] !== undefined && perf[field] !== null && typeof perf[field] !== 'string' && typeof perf[field] !== 'number') {
+            errors.push({ path: `performance.${field}`, message: `performance.${field} must be a string or number` });
+        }
+    }
+
+    // 10. Validate 'authority' section
+    const authority = data.authority || {};
+    if (authority.eeat_signals) {
+        const eeat = authority.eeat_signals;
+        if (typeof eeat === 'object') {
+            const fields = ['experience', 'expertise', 'authority', 'trust'];
+            const missingEeat = fields.filter(f => !eeat[f]);
+            if (missingEeat.length > 0) {
+                warnings.push({ 
+                    path: 'authority.eeat_signals', 
+                    message: `EEAT signals are missing values for: ${missingEeat.join(', ')}` 
+                });
+            }
+        }
+    } else {
+        warnings.push({ path: 'authority.eeat_signals', message: 'authority.eeat_signals section is missing. Highly recommended for AEO.' });
+    }
+
+    // 11. Validate 'platform' section
+    const platform = data.platform || {};
+    if (!platform.provider) {
+        warnings.push({ path: 'platform.provider', message: 'platform.provider is null. CLI requires connection for analyze/sync.' });
+    }
+
+    return { errors, warnings };
+}