seomd-cli 1.0.0

package/src/templates/saas/SEO.md

@@ -0,0 +1,372 @@
+# SEO.md
+
+## {{brand}}
+
+### spec v1.0 | <https://seomd.dev>
+
+#### generated: {{date}}
+
+## FIELD OWNERSHIP
+
+### no prefix     = founder declares (you own this)
+
+### _analysis:    = platform writes back (do not edit manually)
+
+## Site
+
+site:
+  type: saas
+  domain: {{domain}}
+  canonical: https://{{domain}}
+  locale: en-US
+  launched: null              # YYYY-MM-DD
+
+## Identity
+
+identity:
+  brand: "{{brand}}"
+  tagline: null
+  social:
+    twitter: null
+    linkedin: null
+    github: null
+  schema_org_type: SoftwareApplication
+
+## Keywords
+
+keywords:
+
+### FOUNDER DECLARES
+
+  primary: "{{primary_keyword}}"
+  secondary: []               # add your secondary keywords
+  negative:                   # terms that dilute your intent signal
+    - "free"
+    - "tutorial"
+    - "how to"
+  competitor_terms:
+{{competitor_terms}}
+  category_terms:             # unbranded category queries
+    - "best {{primary_keyword}}"
+    - "top {{primary_keyword}} tools"
+  long_tail: []               # add long-tail variations
+  seasonal: null              # add seasonal terms if applicable
+
+### PLATFORM WRITES BACK
+
+  _analysis:
+    source: null
+    primary_search_volume: null
+    primary_intent_type: null
+    primary_trend: null
+    recommended_secondary: []
+    negative_additions_suggested: []
+    last_analyzed: null
+    next_analysis: null
+
+## Intent
+
+intent:
+
+### FOUNDER DECLARES
+
+#### Add queries your buyers actually type into AI engines
+
+#### Tip: think about what someone asks ChatGPT or Perplexity
+
+#### when they are looking for a solution like yours
+
+  informational:
+    priority: medium
+    queries:
+      - "what is {{primary_keyword}}"
+      - "how does {{primary_keyword}} work"
+
+  comparison:
+    priority: high
+    queries:
+{{competitors_comparison_queries}}
+      - "best {{primary_keyword}} for startups"
+
+  transactional:
+    priority: high
+    queries:
+      - "is {{brand_lower}} worth it"
+      - "should I use {{brand_lower}}"
+      - "{{brand_lower}} pricing"
+
+  reputational:
+    priority: medium
+    queries:
+      - "{{brand_lower}} reviews"
+      - "is {{brand_lower}} legit"
+      - "{{brand_lower}} problems"
+
+  category:
+    priority: critical
+    queries:
+      - "best {{primary_keyword}}"
+      - "top {{primary_keyword}} 2026"
+
+### PLATFORM WRITES BACK
+
+  _analysis:
+    source: null
+    last_analyzed: null
+    next_analysis: null
+    informational:
+      citation_rate: null
+      top_cited_competitor: null
+      gap_score: null
+      trend: null
+    comparison:
+      citation_rate: null
+      top_cited_competitor: null
+      gap_score: null
+      trend: null
+    transactional:
+      citation_rate: null
+      top_cited_competitor: null
+      gap_score: null
+      trend: null
+    reputational:
+      citation_rate: null
+      top_cited_competitor: null
+      gap_score: null
+      trend: null
+    category:
+      citation_rate: null
+      top_cited_competitor: null
+      gap_score: null
+      trend: null
+
+## Pages
+
+pages:
+  site_type: saas
+
+### FOUNDER DECLARES
+
+#### status: live | draft | planned
+
+  required:
+    - id: homepage
+      url: /
+      primary_keyword: null
+      status: planned
+      priority: 1
+
+    - id: features
+      url: /features
+      primary_keyword: null
+      status: planned
+      priority: 2
+
+    - id: pricing
+      url: /pricing
+      primary_keyword: null
+      status: planned
+      priority: 3
+
+    - id: comparison
+      url: /vs/[competitor]
+      primary_keyword: null
+      status: planned
+      priority: 4
+
+    - id: alternatives
+      url: /alternatives/[competitor]
+      primary_keyword: null
+      status: planned
+      priority: 5
+
+    - id: use-cases
+      url: /for/[segment]
+      primary_keyword: null
+      status: planned
+      priority: 6
+
+    - id: integrations
+      url: /integrations
+      primary_keyword: null
+      status: planned
+      priority: 7
+
+    - id: changelog
+      url: /changelog
+      primary_keyword: null
+      status: planned
+      priority: 8
+
+    - id: docs
+      url: /docs
+      primary_keyword: null
+      status: planned
+      priority: 9
+
+    - id: blog
+      url: /blog
+      primary_keyword: null
+      status: planned
+      priority: 10
+
+### PLATFORM WRITES BACK
+
+  _analysis:
+    source: null
+    last_analyzed: null
+    pages: []
+    missing_pages: []
+    build_order_recommendation: []
+
+## Copy
+
+copy:
+
+### FOUNDER DECLARES
+
+  h1_contains_primary_keyword: true
+  meta_description_length: 150-160
+  meta_description_includes_cta: true
+  min_word_count:
+    homepage: 800
+    feature_page: 600
+    blog_post: 1200
+    comparison_page: 1500
+  reading_level: 8             # grade level target
+
+## Structure
+
+structure:
+
+### FOUNDER DECLARES
+
+  answer_first: true           # direct answer in first 50 words
+  faq_section_required: true   # on all key pages
+  faq_minimum_questions: 6
+  statistics_per_page: 2       # minimum data points with sources
+  citations_required: true     # link to primary sources
+  short_paragraphs: true       # max 3 sentences
+  heading_hierarchy: strict    # H1 > H2 > H3, no skipping
+
+## Authority
+
+authority:
+
+### FOUNDER DECLARES
+
+  cite_sources: true
+  expert_quotes: false         # set true when you have quotes
+  eeat_signals:
+    experience: null           # describe your experience signal
+    expertise: null            # describe your expertise signal
+    authority: null            # describe your authority signal
+    trust: null                # describe your trust signal
+
+## Schema
+
+schema:
+
+### FOUNDER DECLARES
+
+  types:
+    - SoftwareApplication
+    - Organization
+    - FAQPage
+    - WebPage
+  faq_schema: true
+  breadcrumb_schema: true
+  organization_schema: true
+
+## Crawl
+
+crawl:
+
+### FOUNDER DECLARES
+
+  sitemap: /sitemap.xml
+  robots_txt: /robots.txt
+  allow_ai_bots: true
+  allowed_bots:
+    - Googlebot
+    - Bingbot
+    - PerplexityBot
+    - ChatGPT-User
+    - GPTBot
+    - ClaudeBot
+    - anthropic-ai
+    - cohere-ai
+  disallow:
+    - /admin
+    - /checkout
+    - /user/*
+    - /api/*
+
+## Performance
+
+performance:
+
+### FOUNDER DECLARES
+
+  lcp: 2.5s
+  cls: 0.1
+  fid: 100ms
+  page_size: 500kb
+  ttfb: 800ms
+
+## AEO
+
+aeo:
+
+### FOUNDER DECLARES
+
+### AI Engine Optimization rules
+
+  answer_first_format: true
+  faq_on_all_key_pages: true
+  structured_data_priority: high
+  content_freshness_target: 30d  # update key pages within 30 days
+  competitors_to_monitor:
+{{competitors_to_monitor}}
+
+### PLATFORM WRITES BACK
+
+  _analysis:
+    source: null
+    overall_citation_rate: null
+    overall_gap_score: null
+    engines_tracked:
+      - chatgpt
+      - perplexity
+      - claude
+      - gemini
+      - grok
+    last_analyzed: null
+    next_analysis: null
+
+## Monitoring
+
+monitoring:
+
+### FOUNDER DECLARES
+
+  sync_schedule: monthly       # monthly | weekly | on_demand
+  auto_commit: false           # platform commits directly to repo
+  pr_mode: true                # open PR instead of direct commit
+  branch: main
+  alert_on_gap_score_above: 80 # alert when gap score exceeds threshold
+  alert_on_citation_drop: true # alert if citation rate drops
+
+## Platform Connection
+
+### Connect at <https://seomd.dev/connect>
+
+### Add SEOMD_API_KEY to your .env file
+
+### Never commit your API key to version control
+
+platform:
+  provider: null               # foxcite | manual | ahrefs | semrush
+  project_id: null
+
+### api_key: loaded from SEOMD_API_KEY environment variable

package/src/utils/api-client.js

@@ -0,0 +1,41 @@
+import axios from 'axios';
+import dotenv from 'dotenv';
+
+// Load .env configuration
+dotenv.config();
+
+const API_URL = process.env.SEOMD_API_URL || 'https://api.foxcite.com';
+const API_KEY = process.env.SEOMD_API_KEY;
+const PAYMENT_TOKEN = process.env.SEOMD_PAYMENT_TOKEN;
+const SEOMD_DOMAIN = process.env.SEOMD_DOMAIN;
+
+export const client = axios.create({
+    baseURL: API_URL,
+    timeout: 300000, // 5 minutes timeout for LLM audits
+    headers: {
+        'Content-Type': 'application/json',
+        ...(API_KEY ? { 'Authorization': `Bearer ${API_KEY}` } : {}),
+        ...(PAYMENT_TOKEN ? { 'x-payment-token': PAYMENT_TOKEN } : {}),
+        ...(SEOMD_DOMAIN ? { 'x-seomd-domain': SEOMD_DOMAIN } : {})
+    }
+});
+
+// Interceptor for cleaner error feedback
+client.interceptors.response.use(
+    (response) => response,
+    (error) => {
+        if (error.response) {
+            const status = error.response.status;
+            const detail = error.response.data?.detail || error.response.data?.message || error.message;
+
+            if (status === 401) {
+                return Promise.reject(new Error('Authentication failed: Invalid or missing API key (SEOMD_API_KEY).'));
+            }
+            if (status === 402) {
+                return Promise.reject(new Error(`Payment Required: Insufficient scan credits. ${detail}`));
+            }
+            return Promise.reject(new Error(`API Error (${status}): ${detail}`));
+        }
+        return Promise.reject(new Error(`Network Error: ${error.message}`));
+    }
+);

package/src/utils/constants.js

@@ -0,0 +1,132 @@
+export const SITE_TYPES = [
+    { name: 'SaaS / Software', value: 'saas' },
+    { name: 'Ecommerce', value: 'ecommerce' },
+    { name: 'Local Business', value: 'local' },
+    { name: 'Blog / Media', value: 'blog' },
+    { name: 'Marketplace', value: 'marketplace' },
+];
+
+export const INTENT_CATEGORIES = [
+    'informational',
+    'comparison',
+    'transactional',
+    'reputational',
+    'category',
+];
+
+export const INTENT_PRIORITIES = {
+    saas: {
+        informational: 'medium',
+        comparison: 'high',
+        transactional: 'high',
+        reputational: 'medium',
+        category: 'critical',
+    },
+    ecommerce: {
+        informational: 'low',
+        comparison: 'high',
+        transactional: 'critical',
+        reputational: 'high',
+        category: 'high',
+    },
+    local: {
+        informational: 'medium',
+        comparison: 'medium',
+        transactional: 'critical',
+        reputational: 'critical',
+        category: 'high',
+    },
+    blog: {
+        informational: 'critical',
+        comparison: 'medium',
+        transactional: 'low',
+        reputational: 'medium',
+        category: 'high',
+    },
+    marketplace: {
+        informational: 'medium',
+        comparison: 'high',
+        transactional: 'critical',
+        reputational: 'high',
+        category: 'high',
+    },
+};
+
+export const REQUIRED_PAGES = {
+    saas: [
+        { id: 'homepage', url: '/', priority: 1 },
+        { id: 'features', url: '/features', priority: 2 },
+        { id: 'pricing', url: '/pricing', priority: 3 },
+        { id: 'comparison', url: '/vs/[competitor]', priority: 4 },
+        { id: 'alternatives', url: '/alternatives/[competitor]', priority: 5 },
+        { id: 'use-cases', url: '/for/[segment]', priority: 6 },
+        { id: 'integrations', url: '/integrations', priority: 7 },
+        { id: 'changelog', url: '/changelog', priority: 8 },
+        { id: 'docs', url: '/docs', priority: 9 },
+        { id: 'blog', url: '/blog', priority: 10 },
+    ],
+    ecommerce: [
+        { id: 'homepage', url: '/', priority: 1 },
+        { id: 'category', url: '/[category]', priority: 2 },
+        { id: 'product', url: '/products/[slug]', priority: 3 },
+        { id: 'collection', url: '/collections/[slug]', priority: 4 },
+        { id: 'reviews', url: '/reviews', priority: 5 },
+        { id: 'cart', url: '/cart', priority: 6 },
+        { id: 'checkout', url: '/checkout', priority: 7 },
+    ],
+    local: [
+        { id: 'homepage', url: '/', priority: 1 },
+        { id: 'services', url: '/services', priority: 2 },
+        { id: 'location', url: '/[city]', priority: 3 },
+        { id: 'about', url: '/about', priority: 4 },
+        { id: 'reviews', url: '/reviews', priority: 5 },
+        { id: 'faq', url: '/faq', priority: 6 },
+        { id: 'contact', url: '/contact', priority: 7 },
+        { id: 'service-area', url: '/service-area', priority: 8 },
+    ],
+    blog: [
+        { id: 'homepage', url: '/', priority: 1 },
+        { id: 'category', url: '/[category]', priority: 2 },
+        { id: 'article', url: '/[category]/[slug]', priority: 3 },
+        { id: 'author', url: '/author/[slug]', priority: 4 },
+        { id: 'about', url: '/about', priority: 5 },
+        { id: 'newsletter', url: '/newsletter', priority: 6 },
+    ],
+    marketplace: [
+        { id: 'homepage', url: '/', priority: 1 },
+        { id: 'listing', url: '/listings/[slug]', priority: 2 },
+        { id: 'category', url: '/[category]', priority: 3 },
+        { id: 'seller-profile', url: '/sellers/[slug]', priority: 4 },
+        { id: 'search-results', url: '/search', priority: 5 },
+        { id: 'how-it-works', url: '/how-it-works', priority: 6 },
+        { id: 'pricing', url: '/pricing', priority: 7 },
+        { id: 'trust-safety', url: '/trust', priority: 8 },
+    ],
+};
+
+export const SCHEMA_TYPES = {
+    saas: ['SoftwareApplication', 'Organization', 'FAQPage', 'WebPage'],
+    ecommerce: ['Product', 'Organization', 'FAQPage', 'BreadcrumbList'],
+    local: ['LocalBusiness', 'FAQPage', 'Review', 'GeoCoordinates'],
+    blog: ['Article', 'Person', 'FAQPage', 'BreadcrumbList'],
+    marketplace: ['WebSite', 'Organization', 'FAQPage', 'Product'],
+};
+
+export const PERFORMANCE_THRESHOLDS = {
+    lcp: '2.5s',
+    cls: '0.1',
+    fid: '100ms',
+    page_size: '500kb',
+    time_to_first_byte: '800ms',
+};
+
+export const AI_BOTS = [
+    'Googlebot',
+    'Bingbot',
+    'PerplexityBot',
+    'ChatGPT-User',
+    'GPTBot',
+    'ClaudeBot',
+    'anthropic-ai',
+    'cohere-ai',
+];

package/src/utils/parser.js

@@ -0,0 +1,46 @@
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
+
+/**
+ * Parses the SEO.md file in the specified directory.
+ * Returns both the plain JavaScript object and the YAML Document (for comment preservation).
+ * 
+ * @param {string} [cwd=process.cwd()] - Current working directory
+ * @returns {Promise<{doc: YAML.Document, data: any}>} Parsed SEO.md representation
+ */
+export async function parseSeoMd(cwd = process.cwd()) {
+    const seomdPath = path.join(cwd, 'SEO.md');
+    
+    if (!(await fs.pathExists(seomdPath))) {
+        throw new Error(`SEO.md not found at ${seomdPath}. Run 'seomd init' first.`);
+    }
+    
+    const content = await fs.readFile(seomdPath, 'utf8');
+    
+    try {
+        const doc = YAML.parseDocument(content);
+        const data = doc.toJS();
+        
+        if (!data || typeof data !== 'object') {
+            throw new Error('SEO.md is empty or invalid YAML structure');
+        }
+        
+        return { doc, data };
+    } catch (err) {
+        throw new Error(`Failed to parse SEO.md: ${err.message}`);
+    }
+}
+
+/**
+ * Writes the YAML Document back to SEO.md in the specified directory.
+ * 
+ * @param {YAML.Document} doc - The YAML Document to write
+ * @param {string} [cwd=process.cwd()] - Current working directory
+ * @returns {Promise<void>}
+ */
+export async function writeSeoMd(doc, cwd = process.cwd()) {
+    const seomdPath = path.join(cwd, 'SEO.md');
+    const content = doc.toString();
+    await fs.writeFile(seomdPath, content, 'utf8');
+}