seomd-cli 1.0.0

package/src/commands/sync.js

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs-extra';
+import path from 'path';
+import dotenv from 'dotenv';
+import { parseSeoMd } from '../utils/parser.js';
+import { client } from '../utils/api-client.js';
+import { writeAnalysisToSeoMd, writeReverseMd, writePageAnalysis } from '../utils/writeback.js';
+
+dotenv.config();
+
+export async function syncCommand(options) {
+    const apiKey = process.env.SEOMD_API_KEY;
+    const paymentToken = process.env.SEOMD_PAYMENT_TOKEN;
+
+    if (!apiKey && !paymentToken) {
+        console.log('');
+        console.log(chalk.yellow('⚠ No API key or payment token found.'));
+        console.log('');
+        console.log('Add your API key to .env:');
+        console.log(chalk.cyan('  SEOMD_API_KEY=your_key_here'));
+        console.log('');
+        console.log('Get your API key at ' + chalk.cyan('https://seomd.dev/connect'));
+        console.log('');
+        process.exit(1);
+    }
+
+    const cwd = process.cwd();
+    let doc, data;
+
+    try {
+        const parsed = await parseSeoMd(cwd);
+        doc = parsed.doc;
+        data = parsed.data;
+    } catch (err) {
+        console.log(chalk.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+
+    const domain = data.site?.domain;
+    if (!domain) {
+        console.log(chalk.red('\n❌ Error: "site.domain" is required in SEO.md.'));
+        process.exit(1);
+    }
+
+    // Extract pages
+    let pagesList = [];
+    if (data.pages) {
+        if (Array.isArray(data.pages.required)) {
+            pagesList = pagesList.concat(data.pages.required);
+        }
+        if (Array.isArray(data.pages.optional)) {
+            pagesList = pagesList.concat(data.pages.optional);
+        }
+    }
+
+    console.log(chalk.bold.cyan(`\n🔄 foxcite: Syncing AI Search Audit for ${chalk.white(domain)}`));
+    const spinner = ora('Fetching cached analysis from platform...').start();
+
+    try {
+        const pagesParam = JSON.stringify(pagesList.map(p => ({
+            id: p.id,
+            url: p.url,
+            primary_keyword: p.primary_keyword
+        })));
+
+        const response = await client.get('/cli/sync', {
+            params: { domain, pages: pagesParam }
+        });
+        const results = response.data;
+
+        if (options.dryRun) {
+            spinner.succeed(chalk.green('Sync check completed (Dry Run)!'));
+            console.log('');
+            console.log(chalk.bold('--- Dry-Run Updates Preview ---'));
+            const aeo = results.aeo_analysis;
+            console.log(`Overall Citation Rate : ${chalk.bold.green((aeo.overall_citation_rate * 100).toFixed(0) + '%')}`);
+            console.log(`Overall Gap Score     : ${chalk.bold.red(aeo.overall_gap_score)}`);
+            console.log(`Last Analyzed         : ${chalk.dim(aeo.last_analyzed)}`);
+            console.log(chalk.yellow('\n⚠ Dry-run enabled: No files were modified.'));
+            console.log('');
+            process.exit(0);
+        }
+
+        spinner.text = 'Updating repository files...';
+
+        // Writeback to SEO.md
+        await writeAnalysisToSeoMd(doc, results, cwd);
+
+        // Writeback to SEO.REVERSE.md
+        await writeReverseMd(cwd, results);
+
+        // Writeback to .seomd/pages/*.md
+        await writePageAnalysis(cwd, results);
+
+        spinner.succeed(chalk.green('Sync completed successfully!'));
+        console.log('');
+
+        // Display results summary
+        const aeo = results.aeo_analysis;
+        console.log(chalk.bold('--- Sync Results Summary ---'));
+        console.log(`Overall Citation Rate : ${chalk.bold.green((aeo.overall_citation_rate * 100).toFixed(0) + '%')}`);
+        console.log(`Overall Gap Score     : ${chalk.bold.red(aeo.overall_gap_score)}`);
+
+        if (results.credits_remaining !== null) {
+            console.log(`Credits Remaining     : ${chalk.cyan(results.credits_remaining)}`);
+        }
+        console.log(`Last Analyzed         : ${chalk.dim(aeo.last_analyzed)}`);
+        console.log(`Next Analysis Target  : ${chalk.dim(aeo.next_analysis)}`);
+        console.log('----------------------------');
+        console.log('');
+        console.log(chalk.green('✔ SEO.md updated.'));
+        console.log(chalk.green('✔ SEO.REVERSE.md updated.'));
+        console.log(chalk.green('✔ .seomd/pages/ playbooks synchronized.'));
+        console.log('');
+
+    } catch (err) {
+        spinner.fail(chalk.red('Sync failed'));
+        console.error(chalk.bold.red(`\nError: ${err.message}`));
+        process.exit(1);
+    }
+}

package/src/commands/validate.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { parseSeoMd } from '../utils/parser.js';
+import { validateSeoMd } from '../validators/seomd.js';
+
+export async function validateCommand() {
+    console.log('');
+    console.log(chalk.bold('Validating SEO.md...') + '\n');
+
+    try {
+        const { data } = await parseSeoMd(process.cwd());
+        const { errors, warnings } = validateSeoMd(data);
+
+        if (errors.length === 0 && warnings.length === 0) {
+            console.log(chalk.green('  ✓ ') + chalk.bold('SEO.md is fully compliant with spec v1.0!'));
+            console.log('');
+            process.exit(0);
+        }
+
+        // Print errors
+        if (errors.length > 0) {
+            console.log(chalk.red.bold(`  Errors (${errors.length}):`));
+            errors.forEach(err => {
+                const pathStr = err.path ? chalk.dim(`[${err.path}]`) : '';
+                console.log(`    ${chalk.red('✗')} ${err.message} ${pathStr}`);
+            });
+            console.log('');
+        }
+
+        // Print warnings
+        if (warnings.length > 0) {
+            console.log(chalk.yellow.bold(`  Warnings (${warnings.length}):`));
+            warnings.forEach(warn => {
+                const pathStr = warn.path ? chalk.dim(`[${warn.path}]`) : '';
+                console.log(`    ${chalk.yellow('⚠')} ${warn.message} ${pathStr}`);
+            });
+            console.log('');
+        }
+
+        // Final status report
+        if (errors.length > 0) {
+            console.log(chalk.red.bold(`✗ Validation failed: ${errors.length} error(s) and ${warnings.length} warning(s) found.`));
+            console.log(chalk.dim('Please fix the errors to make your SEO.md valid.'));
+            console.log('');
+            process.exit(1);
+        } else {
+            console.log(chalk.yellow.bold(`✓ Validation passed with ${warnings.length} warning(s).`));
+            console.log(chalk.dim('Warnings are optional recommendations and do not block compliance.'));
+            console.log('');
+            process.exit(0);
+        }
+
+    } catch (err) {
+        console.log(chalk.red('✗ ') + chalk.bold('Validation process failed:'));
+        console.log(`  ${chalk.dim(err.message)}`);
+        console.log('');
+        process.exit(1);
+    }
+}

package/src/generators/directory.js

@@ -0,0 +1,136 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { REQUIRED_PAGES } from '../utils/constants.js';
+
+export async function createSeomdDir(cwd, answers) {
+    const { site_type, brand, domain } = answers;
+    const pages = REQUIRED_PAGES[site_type] || REQUIRED_PAGES.saas;
+    const seomdDir = path.join(cwd, '.seomd');
+
+    // Create directory structure
+    await fs.ensureDir(path.join(seomdDir, 'pages'));
+    await fs.ensureDir(path.join(seomdDir, 'reports'));
+    await fs.ensureDir(path.join(seomdDir, 'competitors'));
+
+    // Create README inside .seomd/
+    await fs.writeFile(
+        path.join(seomdDir, 'README.md'),
+        generateSeomdReadme(brand, domain),
+        'utf8'
+    );
+
+    // Create placeholder page files
+    for (const page of pages) {
+        await fs.writeFile(
+            path.join(seomdDir, 'pages', `${page.id}.md`),
+            generatePagePlaceholder(page, brand),
+            'utf8'
+        );
+    }
+
+    // Create initial empty report
+    const date = new Date().toISOString().split('T')[0];
+    await fs.writeFile(
+        path.join(seomdDir, 'reports', `${date}.md`),
+        generateInitialReport(brand, domain, date),
+        'utf8'
+    );
+}
+
+function generateSeomdReadme(brand, domain) {
+    return `# .seomd/
+
+Intelligence directory for ${brand} (${domain})
+Generated by SEO.md CLI — https://seomd.dev
+
+## Directory Structure
+
+\`\`\`
+.seomd/
+├── pages/          # per-page reverse engineer analysis
+├── reports/        # dated snapshot reports (gitignored by default)
+└── competitors/    # competitor citation profiles
+\`\`\`
+
+## Usage
+
+\`\`\`bash
+# Run citation analysis and update all files
+npx seomd analyze
+
+# Sync latest platform intelligence
+npx seomd sync
+
+# View current status
+npx seomd status
+\`\`\`
+
+## File Ownership
+
+- \`pages/\` — platform generated, do not edit manually
+- \`reports/\` — platform generated, gitignored by default
+- \`competitors/\` — platform generated, do not edit manually
+
+Connect your platform at https://seomd.dev/connect
+`;
+}
+
+function generatePagePlaceholder(page, brand) {
+    const date = new Date().toISOString().split('T')[0];
+    return `# ${page.id}
+
+## Page: ${page.url}
+
+### Priority: ${page.priority}
+
+### Last analyzed: null
+
+### Run \`npx seomd analyze --page ${page.url}\` to populate
+
+brand: "${brand}"
+page_id: ${page.id}
+url: ${page.url}
+status: planned
+citation_rate: null
+gap_score: null
+top_cited_competitor: null
+last_analyzed: null
+
+why_page_won: []
+citation_hooks: []
+gaps_for_brand: []
+remediation_playbook: []
+
+fastest_win:
+  action: null
+  estimated_gap_score_improvement: null
+  effort: null
+
+suggested_content_outline: []
+`;
+}
+
+function generateInitialReport(brand, domain, date) {
+    return `# SEO.md Report — ${date}
+
+## ${brand} (${domain})
+
+### Initial report — run \`npx seomd analyze\` to populate
+
+date: ${date}
+brand: "${brand}"
+domain: ${domain}
+overall_citation_rate: null
+overall_gap_score: null
+
+intent_summary:
+  informational: null
+  comparison: null
+  transactional: null
+  reputational: null
+  category: null
+
+top_opportunities: []
+completed_wins: []
+`;
+}

package/src/generators/reverse.js

@@ -0,0 +1,62 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Generates the content of the seo.reverse.md file by reading the corresponding site type template
+ * and substituting placeholders.
+ * 
+ * @param {any} answers - Scaffolding inputs (brand, domain, primary_keyword, site_type, competitors)
+ * @returns {string} The filled template content
+ */
+export function generateReverseMd(answers) {
+    const { site_type, domain, brand, competitors } = answers;
+    const competitorList = Array.isArray(competitors) ? competitors : [];
+
+    // Resolve template file path
+    const templatePath = path.join(__dirname, '../templates', site_type, 'SEO.REVERSE.md');
+
+    if (!fs.existsSync(templatePath)) {
+        throw new Error(`Template not found for site type: ${site_type}`);
+    }
+
+    let content = fs.readFileSync(templatePath, 'utf8');
+
+    const date = new Date().toISOString().split('T')[0];
+    const brandLower = brand.toLowerCase();
+    const brandSnake = brandLower.replace(/\s+/g, '_');
+    const primaryCompetitor = competitorList[0] || '[competitor]';
+
+    // Formatting YAML blocks for competitors
+    let reverseCompetitors = '';
+    if (competitorList.length > 0) {
+        reverseCompetitors = competitorList.map(c => `  - domain: ${c}
+    overall_citation_rate: null
+    strongest_intent_category: null
+    weakest_intent_category: null
+    top_cited_pages: []
+    citation_patterns: []
+    last_analyzed: null`).join('\n\n');
+    } else {
+        reverseCompetitors = `  - domain: [competitor]
+    overall_citation_rate: null
+    strongest_intent_category: null
+    weakest_intent_category: null
+    top_cited_pages: []
+    citation_patterns: []
+    last_analyzed: null`;
+    }
+
+    // Perform simple string replacements
+    content = content
+        .replaceAll('{{brand}}', brand)
+        .replaceAll('{{brand_lower_snake}}', brandSnake)
+        .replaceAll('{{domain}}', domain)
+        .replaceAll('{{primary_competitor}}', primaryCompetitor)
+        .replaceAll('{{date}}', date)
+        .replaceAll('{{reverse_competitors}}', reverseCompetitors);
+
+    return content;
+}

package/src/generators/seomd.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getBrandName(domain) {
+    return domain
+        .replace(/^(https?:\/\/)?(www\.)?/, '')
+        .replace(/\.[a-z]{2,6}(\.[a-z]{2,6})?$/i, '');
+}
+
+/**
+ * Generates the content of the seo.md file by reading the corresponding site type template
+ * and substituting placeholders.
+ * 
+ * @param {any} answers - Scaffolding inputs (brand, domain, primary_keyword, site_type, competitors)
+ * @returns {string} The filled template content
+ */
+export function generateSeoMd(answers) {
+    const { site_type, domain, brand, primary_keyword, competitors } = answers;
+    const competitorList = Array.isArray(competitors) ? competitors : [];
+
+    // Resolve template file path
+    const templatePath = path.join(__dirname, '../templates', site_type, 'SEO.md');
+
+    if (!fs.existsSync(templatePath)) {
+        throw new Error(`Template not found for site type: ${site_type}`);
+    }
+
+    let content = fs.readFileSync(templatePath, 'utf8');
+
+    const date = new Date().toISOString().split('T')[0];
+    const brandLower = brand.toLowerCase();
+    const brandSnake = brandLower.replace(/\s+/g, '_');
+
+    // Formatting YAML blocks for competitors
+    const competitorTerms = competitorList.map(c => `    - "${getBrandName(c)} alternative"`).join('\n') || '    []';
+    const comparisonQueries = competitorList.map(c => `      - "${getBrandName(c)} vs ${brandLower}"`).join('\n') || `      - "${brandLower} vs [competitor]"`;
+    const toMonitor = competitorList.map(c => `    - ${c}`).join('\n') || '    []';
+
+    // Perform simple string replacements
+    content = content
+        .replaceAll('{{brand}}', brand)
+        .replaceAll('{{brand_lower}}', brandLower)
+        .replaceAll('{{brand_lower_snake}}', brandSnake)
+        .replaceAll('{{domain}}', domain)
+        .replaceAll('{{primary_keyword}}', primary_keyword)
+        .replaceAll('{{date}}', date)
+        .replaceAll('{{competitor_terms}}', competitorTerms)
+        .replaceAll('{{competitors_comparison_queries}}', comparisonQueries)
+        .replaceAll('{{competitors_to_monitor}}', toMonitor);
+
+    return content;
+}

package/src/templates/blog/SEO.REVERSE.md

@@ -0,0 +1,176 @@
+# SEO.REVERSE.md
+
+## {{brand}}
+
+### spec v1.0 | https://seomd.dev
+
+#### generated: {{date}}
+
+## This file is generated by the {{brand}} platform.
+### Do not edit manually — run `npx seomd analyze` to update.
+### Run `npx seomd sync` to pull latest intelligence.
+
+## Each page section contains a full reverse engineer analysis:
+
+###   why_page_won             — what the top cited competitor does right
+###   citation_hooks           — specific patterns to replicate
+###   gaps_for_brand           — where your page falls short
+###   remediation_playbook     — step by step fixes with effort/impact
+###   fastest_win              — highest ROI action to take now
+###   suggested_content_outline — ready to use outline for your writer/AI
+
+domain: {{domain}}
+brand: "{{brand}}"
+primary_competitor: {{primary_competitor}}
+last_analyzed: null
+next_analysis: null
+source: null
+
+## Pages
+### Run `npx seomd analyze` to populate these sections
+
+pages:
+
+  ### Homepage
+
+  - id: homepage
+    url: /
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+  ### Category
+
+  - id: category
+    url: /[category]
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+  ### Article
+
+  - id: article
+    url: /[category]/[slug]
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+  ### Author
+
+  - id: author
+    url: /author/[slug]
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+  ### About
+
+  - id: about
+    url: /about
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+  ### Newsletter
+
+  - id: newsletter
+    url: /newsletter
+    status: planned
+    citation_rate: null
+    gap_score: null
+    top_cited_competitor: null
+
+    why_page_won: []
+    citation_hooks: []
+
+    gaps_for_{{brand_lower_snake}}: []
+
+    remediation_playbook: []
+
+    fastest_win:
+      action: null
+      estimated_gap_score_improvement: null
+      effort: null
+
+    suggested_content_outline: []
+
+## Competitor Profiles
+### Platform populated — competitor citation patterns
+
+competitors:
+{{reverse_competitors}}