seomd-cli 1.0.0

package/bin/seomd.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+// Commands
+import { initCommand } from '../src/commands/init.js';
+import { analyzeCommand } from '../src/commands/analyze.js';
+import { syncCommand } from '../src/commands/sync.js';
+import { statusCommand } from '../src/commands/status.js';
+import { validateCommand } from '../src/commands/validate.js';
+
+program
+    .name('seomd')
+    .description('AEO infrastructure for technical founders — seomd.dev')
+    .version(pkg.version);
+
+program
+    .command('init')
+    .description('Scaffold SEO.md for your project')
+    .option('-y, --yes', 'skip prompts and use defaults')
+    .option('--type <type>', 'site type: saas, ecommerce, local, blog, marketplace')
+    .action(initCommand);
+
+program
+    .command('analyze')
+    .description('Run citation analysis and write back _analysis blocks')
+    .option('--page <url>', 'analyze a specific page only')
+    .option('--intent <category>', 'analyze a specific intent category only')
+    .action(analyzeCommand);
+
+program
+    .command('sync')
+    .description('Sync latest platform intelligence to your SEO.md files')
+    .option('--dry-run', 'preview changes without writing')
+    .action(syncCommand);
+
+program
+    .command('status')
+    .description('Show current citation rates and gap scores')
+    .option('--json', 'output as JSON')
+    .action(statusCommand);
+
+program
+    .command('validate')
+    .description('Validate your SEO.md against the spec')
+    .action(validateCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "seomd-cli",
+    "version": "1.0.0",
+    "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
+    "homepage": "https://seomd.dev",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/seomd/seomd-cli"
+    },
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "seomd": "./bin/seomd.js"
+    },
+    "scripts": {
+        "dev": "node bin/seomd.js",
+        "test": "node --experimental-vm-modules node_modules/.bin/jest",
+        "lint": "eslint src/**/*.js"
+    },
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^11.0.0",
+        "enquirer": "^2.4.1",
+        "ora": "^7.0.1",
+        "yaml": "^2.3.4",
+        "fs-extra": "^11.1.1",
+        "axios": "^1.6.0",
+        "dotenv": "^16.3.1"
+    },
+    "devDependencies": {
+        "jest": "^29.7.0",
+        "eslint": "^8.50.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "keywords": [
+        "seo",
+        "aeo",
+        "geo",
+        "seomd",
+        "ai-search",
+        "citation-tracking",
+        "llm-seo"
+    ]
+}

package/src/commands/analyze.js

@@ -0,0 +1,145 @@
+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 analyzeCommand(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);
+    }
+
+    const niche = data.site?.type || 'saas';
+
+    // Extract intent queries
+    const queries = {};
+    if (data.intent) {
+        for (const [intentType, obj] of Object.entries(data.intent)) {
+            if (intentType !== '_analysis' && obj && Array.isArray(obj.queries)) {
+                queries[intentType] = obj.queries;
+            }
+        }
+    }
+
+    // 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);
+        }
+    }
+
+    // Default to homepage if no pages defined
+    if (pagesList.length === 0) {
+        pagesList.push({
+            id: 'homepage',
+            url: '/',
+            primary_keyword: `best ${niche}`,
+            status: 'planned'
+        });
+    }
+
+    // Extract engines
+    const engines = data.aeo?._analysis?.engines_tracked || ['Claude', 'ChatGPT'];
+
+    console.log(chalk.bold.cyan(`\n📊 foxcite: Running AI Search Audit for ${chalk.white(domain)}`));
+    console.log(chalk.dim(`Engines: ${engines.join(', ')}`));
+    console.log(chalk.dim(`Pages to scan: ${pagesList.length}`));
+    console.log('');
+
+    const spinner = ora('Initializing scan sessions...').start();
+
+    try {
+        const payload = {
+            domain,
+            niche,
+            queries,
+            engines,
+            pages: pagesList.map(p => ({
+                id: p.id,
+                url: p.url,
+                primary_keyword: p.primary_keyword,
+                status: p.status
+            }))
+        };
+
+        spinner.text = 'Scanning AI search engines and compiling citations (this may take up to a minute)...';
+
+        const response = await client.post('/cli/analyze', payload);
+        const results = response.data;
+
+        spinner.text = 'Writing analysis blocks back to 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('Analysis completed successfully!'));
+        console.log('');
+
+        // Display results summary
+        const aeo = results.aeo_analysis;
+        console.log(chalk.bold('--- 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 generated.'));
+        console.log('');
+
+    } catch (err) {
+        spinner.fail(chalk.red('Analysis failed'));
+        console.error(chalk.bold.red(`\nError: ${err.message}`));
+        process.exit(1);
+    }
+}

package/src/commands/init.js

@@ -0,0 +1,160 @@
+import chalk from 'chalk';
+import enquirer from 'enquirer';
+const { prompt } = enquirer;
+import ora from 'ora';
+import fs from 'fs-extra';
+import path from 'path';
+import { generateSeoMd } from '../generators/seomd.js';
+import { generateReverseMd } from '../generators/reverse.js';
+import { createSeomdDir } from '../generators/directory.js';
+import { SITE_TYPES } from '../utils/constants.js';
+
+export async function initCommand(options) {
+    console.log('');
+    console.log(chalk.bold('SEO.md') + chalk.dim(' v0.1.0 — https://seomd.dev'));
+    console.log('');
+    console.log(chalk.dim('The open standard for AI-era SEO configuration.'));
+    console.log('');
+
+    // Check if SEO.md already exists
+    const seomdPath = path.join(process.cwd(), 'SEO.md');
+    if (await fs.pathExists(seomdPath)) {
+        console.log(chalk.yellow('⚠ SEO.md already exists in this directory.'));
+        const { overwrite } = await prompt({
+            type: 'confirm',
+            name: 'overwrite',
+            message: 'Overwrite existing SEO.md?',
+            initial: false,
+        });
+        if (!overwrite) {
+            console.log(chalk.dim('Aborted.'));
+            process.exit(0);
+        }
+    }
+
+    let answers;
+
+    if (options.yes) {
+        // Default values for --yes flag
+        answers = {
+            site_type: options.type || 'saas',
+            domain: 'example.com',
+            brand: 'My Brand',
+            primary_keyword: '',
+            competitors: '',
+        };
+    } else {
+        // The 5-question init flow
+        answers = await prompt([
+            {
+                type: 'select',
+                name: 'site_type',
+                message: 'Site type:',
+                choices: SITE_TYPES.map(t => ({ name: t.value, message: t.name })),
+                initial: options.type ? SITE_TYPES.findIndex(t => t.value === options.type) : 0,
+            },
+            {
+                type: 'input',
+                name: 'domain',
+                message: 'Primary domain:',
+                hint: 'e.g. myapp.com',
+                validate(value) {
+                    if (!value) return 'Domain is required';
+                    // Strip protocol if provided
+                    return true;
+                },
+                result(value) {
+                    return value.replace(/^https?:\/\//, '').replace(/\/$/, '');
+                },
+            },
+            {
+                type: 'input',
+                name: 'brand',
+                message: 'Brand name:',
+                hint: 'e.g. MyApp',
+                validate(value) {
+                    if (!value) return 'Brand name is required';
+                    return true;
+                },
+            },
+            {
+                type: 'input',
+                name: 'primary_keyword',
+                message: 'Primary keyword:',
+                hint: 'e.g. project management software',
+                validate(value) {
+                    if (!value) return 'Primary keyword is required';
+                    return true;
+                },
+            },
+            {
+                type: 'input',
+                name: 'competitors',
+                message: 'Top 3 competitors (comma separated):',
+                hint: 'e.g. asana.com, monday.com, notion.so',
+                result(value) {
+                    return value
+                        .split(',')
+                        .map(c => c.trim())
+                        .filter(Boolean)
+                        .slice(0, 3);
+                },
+            },
+        ]);
+    }
+
+    console.log('');
+    const spinner = ora('Scaffolding your SEO.md files...').start();
+
+    try {
+        // 1. Generate SEO.md
+        const seomdContent = generateSeoMd(answers);
+        await fs.writeFile(seomdPath, seomdContent, 'utf8');
+        spinner.succeed(chalk.green('SEO.md created'));
+
+        // 2. Generate SEO.REVERSE.md
+        const reversePath = path.join(process.cwd(), 'SEO.REVERSE.md');
+        const reverseContent = generateReverseMd(answers);
+        await fs.writeFile(reversePath, reverseContent, 'utf8');
+        spinner.succeed(chalk.green('SEO.REVERSE.md initialized'));
+
+        // 3. Create .seomd/ directory structure
+        await createSeomdDir(process.cwd(), answers);
+        spinner.succeed(chalk.green('.seomd/ directory created'));
+
+        // 4. Add .seomd/ to .gitignore if it exists
+        await updateGitignore(process.cwd());
+
+        console.log('');
+        console.log(chalk.bold.green('✓ SEO.md initialized successfully'));
+        console.log('');
+        console.log(chalk.dim('Files created:'));
+        console.log('  ' + chalk.cyan('SEO.md') + chalk.dim('             — your living SEO config'));
+        console.log('  ' + chalk.cyan('SEO.REVERSE.md') + chalk.dim('     — reverse engineer output (platform generated)'));
+        console.log('  ' + chalk.cyan('.seomd/') + chalk.dim('            — intelligence directory'));
+        console.log('');
+        console.log(chalk.dim('Next steps:'));
+        console.log('  ' + chalk.white('npx seomd analyze') + chalk.dim('  — run your first citation analysis'));
+        console.log('  ' + chalk.white('npx seomd status') + chalk.dim('   — view current gap scores'));
+        console.log('');
+        console.log(chalk.dim('Connect your platform at ') + chalk.cyan('https://seomd.dev/connect'));
+        console.log('');
+
+    } catch (err) {
+        spinner.fail(chalk.red('Failed to scaffold SEO.md'));
+        console.error(chalk.dim(err.message));
+        process.exit(1);
+    }
+}
+
+async function updateGitignore(cwd) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    const entry = '\n# seomd intelligence directory\n.seomd/reports/\n';
+
+    if (await fs.pathExists(gitignorePath)) {
+        const content = await fs.readFile(gitignorePath, 'utf8');
+        if (!content.includes('.seomd')) {
+            await fs.appendFile(gitignorePath, entry);
+        }
+    }
+}

package/src/commands/status.js

@@ -0,0 +1,192 @@
+import chalk from 'chalk';
+import { parseSeoMd } from '../utils/parser.js';
+
+export async function statusCommand(options) {
+    try {
+        const { data } = await parseSeoMd(process.cwd());
+
+        const aeoAnalysis = data.aeo?._analysis || {};
+        const intentAnalysis = data.intent?._analysis || {};
+        const pagesRequired = data.pages?.required || [];
+        const pagesAnalysis = data.pages?._analysis?.pages || [];
+
+        // Check if there is any analysis data
+        const hasOverallData = aeoAnalysis.overall_citation_rate !== null && aeoAnalysis.overall_citation_rate !== undefined;
+        
+        if (!hasOverallData) {
+            if (options.json) {
+                console.log(JSON.stringify({ status: "no_data", message: "No analysis data found" }, null, 2));
+            } else {
+                console.log('');
+                console.log(chalk.yellow('⚠ No analysis data found in SEO.md.'));
+                console.log('');
+                console.log('To populate analysis data:');
+                console.log(`  1. Get an API key at ${chalk.cyan('https://seomd.dev/connect')}`);
+                console.log('  2. Add it to your .env file:');
+                console.log(chalk.cyan('     SEOMD_API_KEY=your_key_here'));
+                console.log('  3. Run citation analysis:');
+                console.log(chalk.white('     npx seomd analyze'));
+                console.log('');
+            }
+            process.exit(0);
+        }
+
+        // Format overall metrics
+        const overallCitation = formatPercentage(aeoAnalysis.overall_citation_rate);
+        const overallGap = formatScore(aeoAnalysis.overall_gap_score);
+
+        if (options.json) {
+            // Output structured JSON
+            const output = {
+                site: {
+                    type: data.site?.type || null,
+                    domain: data.site?.domain || null,
+                    brand: data.identity?.brand || null,
+                },
+                overall: {
+                    citation_rate: aeoAnalysis.overall_citation_rate,
+                    gap_score: aeoAnalysis.overall_gap_score,
+                    last_analyzed: aeoAnalysis.last_analyzed || null,
+                },
+                intent: {},
+                pages: []
+            };
+
+            const categories = ['informational', 'comparison', 'transactional', 'reputational', 'category'];
+            categories.forEach(cat => {
+                const catData = intentAnalysis[cat] || {};
+                const declared = data.intent?.[cat] || {};
+                output.intent[cat] = {
+                    priority: declared.priority || null,
+                    citation_rate: catData.citation_rate || null,
+                    gap_score: catData.gap_score || null,
+                    trend: catData.trend || null
+                };
+            });
+
+            pagesRequired.forEach(req => {
+                const anal = pagesAnalysis.find(p => p.id === req.id) || {};
+                output.pages.push({
+                    id: req.id,
+                    url: req.url,
+                    status: req.status || 'planned',
+                    priority: req.priority || 0,
+                    citation_rate: anal.citation_rate !== undefined ? anal.citation_rate : null,
+                    gap_score: anal.gap_score !== undefined ? anal.gap_score : null,
+                });
+            });
+
+            console.log(JSON.stringify(output, null, 2));
+            process.exit(0);
+        }
+
+        // Output beautiful terminal dashboard
+        console.log('');
+        console.log(chalk.bold('SEO.md Status Dashboard') + chalk.dim(` — ${data.identity?.brand || 'Brand'} (${data.site?.domain || 'domain'})`));
+        console.log(chalk.dim(`Last analyzed: ${aeoAnalysis.last_analyzed || 'N/A'}`));
+        console.log(chalk.dim('─'.repeat(60)));
+        
+        // Overall block
+        console.log(`Overall Citation Rate:  ${colorCitation(aeoAnalysis.overall_citation_rate, overallCitation)}`);
+        console.log(`Overall Gap Score:      ${colorGap(aeoAnalysis.overall_gap_score, overallGap)}`);
+        console.log(chalk.dim('─'.repeat(60)));
+
+        // Intent Categories Table
+        console.log(chalk.bold('INTENT CATEGORY SUMMARY'));
+        console.log('');
+        console.log(formatRow('Category', 'Priority', 'Citation Rate', 'Gap Score', 'Trend'));
+        console.log(chalk.dim('─'.repeat(65)));
+
+        const categories = ['informational', 'comparison', 'transactional', 'reputational', 'category'];
+        categories.forEach(cat => {
+            const declared = data.intent?.[cat] || {};
+            const anal = intentAnalysis[cat] || {};
+            
+            const name = cat.charAt(0).toUpperCase() + cat.slice(1);
+            const priority = declared.priority || 'medium';
+            const citationVal = anal.citation_rate;
+            const gapVal = anal.gap_score;
+            const trend = anal.trend || '-';
+
+            const citationStr = colorCitation(citationVal, formatPercentage(citationVal));
+            const gapStr = colorGap(gapVal, formatScore(gapVal));
+            
+            console.log(formatRow(name, priority, citationStr, gapStr, trend));
+        });
+        
+        console.log(chalk.dim('─'.repeat(65)));
+        console.log('');
+
+        // Pages Table
+        console.log(chalk.bold('PAGE ANALYSIS SUMMARY'));
+        console.log('');
+        console.log(formatRowPage('Page ID', 'URL', 'Status', 'Citation Rate', 'Gap Score'));
+        console.log(chalk.dim('─'.repeat(70)));
+
+        pagesRequired.forEach(req => {
+            const anal = pagesAnalysis.find(p => p.id === req.id) || {};
+            
+            const id = req.id;
+            const url = req.url;
+            const status = req.status || 'planned';
+            const citationVal = anal.citation_rate;
+            const gapVal = anal.gap_score;
+
+            const citationStr = colorCitation(citationVal, formatPercentage(citationVal));
+            const gapStr = colorGap(gapVal, formatScore(gapVal));
+
+            console.log(formatRowPage(id, url, status, citationStr, gapStr));
+        });
+
+        console.log(chalk.dim('─'.repeat(70)));
+        console.log('');
+
+    } catch (err) {
+        console.log(chalk.red('✗ ') + chalk.bold('Failed to display status:'));
+        console.log(`  ${chalk.dim(err.message)}`);
+        console.log('');
+        process.exit(1);
+    }
+}
+
+// Helpers for string formatting/alignment
+function formatRow(cat, pri, cit, gap, trend) {
+    return `${cat.padEnd(16)} │ ${pri.padEnd(10)} │ ${cit.padEnd(23)} │ ${gap.padEnd(19)} │ ${trend}`;
+}
+
+function formatRowPage(id, url, status, cit, gap) {
+    return `${id.padEnd(14)} │ ${url.padEnd(20)} │ ${status.padEnd(8)} │ ${cit.padEnd(23)} │ ${gap.padEnd(19)}`;
+}
+
+function formatPercentage(val) {
+    if (val === null || val === undefined) return '-';
+    if (typeof val === 'number') {
+        return `${(val * 100).toFixed(0)}%`;
+    }
+    return String(val);
+}
+
+function formatScore(val) {
+    if (val === null || val === undefined) return '-';
+    return String(val);
+}
+
+function colorCitation(val, str) {
+    if (val === null || val === undefined) return chalk.dim(str);
+    const num = typeof val === 'number' ? val * 100 : parseFloat(val);
+    if (isNaN(num)) return chalk.dim(str);
+    
+    if (num >= 20) return chalk.green.bold(str);
+    if (num >= 5) return chalk.yellow.bold(str);
+    return chalk.red.bold(str);
+}
+
+function colorGap(val, str) {
+    if (val === null || val === undefined) return chalk.dim(str);
+    const num = parseInt(val, 10);
+    if (isNaN(num)) return chalk.dim(str);
+
+    if (num < 30) return chalk.green.bold(str);
+    if (num <= 70) return chalk.yellow.bold(str);
+    return chalk.red.bold(str);
+}