seo-intel 1.0.0

package/exports/technical.js

@@ -0,0 +1,180 @@
+import { collectTop, inferPriorityFromCount, makeAction, sortActions } from './heuristics.js';
+import { getTechnicalDataset } from './queries.js';
+
+export function buildTechnicalActions(db, project) {
+  const rows = getTechnicalDataset(db, project);
+  const actions = [];
+
+  const missingSchema = rows.filter(r => !r.schema_count && !r.has_schema);
+  if (missingSchema.length) {
+    actions.push(makeAction({
+      id: 'technical-missing-schema',
+      type: 'add_schema',
+      priority: inferPriorityFromCount(missingSchema.length, { critical: 25, high: 10, medium: 4 }),
+      area: 'schema',
+      title: `Add structured data to ${missingSchema.length} target pages`,
+      why: 'Pages without schema miss eligibility for rich results and machine-readable context.',
+      evidence: collectTop(missingSchema.map(r => `${r.url} (status ${r.status_code || 'n/a'})`), 8),
+      implementationHints: [
+        'Map page templates to schema types like Organization, Product, FAQ, Article, BreadcrumbList, and WebPage.',
+        'Generate JSON-LD server-side so it is present in raw HTML.',
+        'Prioritize money pages, docs hubs, and comparison pages first.',
+      ],
+    }));
+  }
+
+  const brokenPages = rows.filter(r => Number(r.status_code) >= 400);
+  if (brokenPages.length) {
+    actions.push(makeAction({
+      id: 'technical-broken-pages',
+      type: 'fix',
+      priority: inferPriorityFromCount(brokenPages.length, { critical: 5, high: 3, medium: 1 }),
+      area: 'technical',
+      title: `Fix ${brokenPages.length} broken target pages returning 4xx/5xx`,
+      why: 'Broken pages waste crawl budget, lose link equity, and create dead ends in user journeys.',
+      evidence: collectTop(brokenPages.map(r => `${r.url} → ${r.status_code}`), 10),
+      implementationHints: [
+        'Restore the intended page or 301 it to the nearest equivalent live URL.',
+        'Update internal links pointing to these URLs after the redirect or fix.',
+      ],
+    }));
+  }
+
+  const orphanPages = rows.filter(r => r.click_depth > 0 && r.inbound_internal_links === 0 && Number(r.status_code) < 400);
+  if (orphanPages.length) {
+    actions.push(makeAction({
+      id: 'technical-orphans',
+      type: 'fix',
+      priority: inferPriorityFromCount(orphanPages.length, { critical: 15, high: 7, medium: 3 }),
+      area: 'structure',
+      title: `Reconnect ${orphanPages.length} orphan pages to the internal link graph`,
+      why: 'Pages with no discovered internal links pointing at them are harder for crawlers and users to find.',
+      evidence: collectTop(orphanPages.map(r => `${r.url} (depth ${r.click_depth})`), 10),
+      implementationHints: [
+        'Add contextual links from hub pages, nav, docs indexes, and related content blocks.',
+        'Review sitemap inclusion for pages that should rank.',
+      ],
+    }));
+  }
+
+  const thinPages = rows.filter(r => (r.word_count || 0) > 0 && r.word_count < 200 && Number(r.status_code) < 400);
+  if (thinPages.length) {
+    actions.push(makeAction({
+      id: 'technical-thin-pages',
+      type: 'improve',
+      priority: inferPriorityFromCount(thinPages.length, { critical: 30, high: 12, medium: 5 }),
+      area: 'content',
+      title: `Strengthen ${thinPages.length} thin pages under 200 words`,
+      why: 'Very short pages usually fail to satisfy intent unless they are utility endpoints or redirects.',
+      evidence: collectTop(thinPages.map(r => `${r.url} (${r.word_count} words)`), 10),
+      implementationHints: [
+        'Add clear H1/H2 structure, core benefit copy, FAQs, examples, and internal links.',
+        'Merge low-value pages into stronger canonical assets when intent overlaps.',
+      ],
+    }));
+  }
+
+  const deepPages = rows.filter(r => (r.click_depth || 0) > 3 && Number(r.status_code) < 400);
+  if (deepPages.length) {
+    actions.push(makeAction({
+      id: 'technical-deep-pages',
+      type: 'fix',
+      priority: inferPriorityFromCount(deepPages.length, { critical: 20, high: 8, medium: 3 }),
+      area: 'structure',
+      title: `Pull ${deepPages.length} deep pages closer than 4 clicks from entry points`,
+      why: 'Important URLs buried deep in the crawl path tend to receive less internal authority and lower discovery frequency.',
+      evidence: collectTop(deepPages.map(r => `${r.url} (depth ${r.click_depth})`), 10),
+      implementationHints: [
+        'Promote high-value URLs into nav, footer, hub, or resource index pages.',
+        'Add breadcrumb trails and category pages to shorten crawl distance.',
+      ],
+    }));
+  }
+
+  const missingH1 = rows.filter(r => !r.h1_count && !String(r.h1 || '').trim() && Number(r.status_code) < 400);
+  if (missingH1.length) {
+    actions.push(makeAction({
+      id: 'technical-missing-h1',
+      type: 'fix',
+      priority: inferPriorityFromCount(missingH1.length, { critical: 20, high: 8, medium: 3 }),
+      area: 'content',
+      title: `Add unique H1s to ${missingH1.length} pages`,
+      why: 'Missing H1s weaken topic clarity for both users and search engines.',
+      evidence: collectTop(missingH1.map(r => r.url), 10),
+      implementationHints: [
+        'Align the H1 with page intent and supporting title/meta copy.',
+        'Use one clear H1 per page instead of decorative empty hero copy.',
+      ],
+    }));
+  }
+
+  const missingMeta = rows.filter(r => !String(r.meta_desc || '').trim() && Number(r.status_code) < 400);
+  if (missingMeta.length) {
+    actions.push(makeAction({
+      id: 'technical-missing-meta',
+      type: 'improve',
+      priority: inferPriorityFromCount(missingMeta.length, { critical: 25, high: 10, medium: 4 }),
+      area: 'content',
+      title: `Write meta descriptions for ${missingMeta.length} pages`,
+      why: 'Missing meta descriptions reduce control over SERP snippets and CTR messaging.',
+      evidence: collectTop(missingMeta.map(r => r.url), 10),
+      implementationHints: [
+        'Write intent-matched descriptions around 140–160 characters.',
+        'Highlight the core outcome, differentiator, and CTA.',
+      ],
+    }));
+  }
+
+  const redirectChains = rows.filter(r => (r.redirects_linked_from_page || 0) > 0);
+  if (redirectChains.length) {
+    actions.push(makeAction({
+      id: 'technical-redirect-chains',
+      type: 'fix',
+      priority: inferPriorityFromCount(redirectChains.length, { critical: 12, high: 5, medium: 2 }),
+      area: 'technical',
+      title: `Update internal links on ${redirectChains.length} pages that point to redirects`,
+      why: 'Internal links that hit redirects waste crawl hops and can become redirect chains over time.',
+      evidence: collectTop(redirectChains.map(r => `${r.url} (${r.redirects_linked_from_page} redirecting links)`), 10),
+      implementationHints: [
+        'Replace redirecting targets with their final destination URLs in nav and body content.',
+        'Audit legacy paths generated by CMS migrations or product renames.',
+      ],
+    }));
+  }
+
+  const missingCanonical = rows.filter(r => !r.has_canonical && Number(r.status_code) < 400);
+  if (missingCanonical.length) {
+    actions.push(makeAction({
+      id: 'technical-missing-canonical',
+      type: 'fix',
+      priority: inferPriorityFromCount(missingCanonical.length, { critical: 20, high: 10, medium: 4 }),
+      area: 'technical',
+      title: `Add canonical tags to ${missingCanonical.length} pages`,
+      why: 'Canonical tags help consolidate duplicate or near-duplicate URLs and reduce ambiguity.',
+      evidence: collectTop(missingCanonical.map(r => r.url), 10),
+      implementationHints: [
+        'Ensure every canonical points to the preferred self URL or the consolidated destination.',
+        'Keep canonicals consistent across parameterized, localized, and paginated pages.',
+      ],
+    }));
+  }
+
+  const missingOg = rows.filter(r => !r.has_og_tags && Number(r.status_code) < 400);
+  if (missingOg.length) {
+    actions.push(makeAction({
+      id: 'technical-missing-og',
+      type: 'improve',
+      priority: inferPriorityFromCount(missingOg.length, { critical: 25, high: 10, medium: 4 }),
+      area: 'technical',
+      title: `Add Open Graph tags to ${missingOg.length} pages`,
+      why: 'OG tags improve share previews and often correlate with better metadata hygiene across templates.',
+      evidence: collectTop(missingOg.map(r => r.url), 10),
+      implementationHints: [
+        'Populate og:title, og:description, og:image, and og:url on every indexable template.',
+        'Generate reusable social preview images for docs, product, and comparison templates.',
+      ],
+    }));
+  }
+
+  return sortActions(actions);
+}

package/exports/templates.js

@@ -0,0 +1,77 @@
+import { summarizeActions } from './heuristics.js';
+
+export function buildExportPayload({ project, scope, actions }) {
+  return {
+    project,
+    generatedAt: new Date().toISOString(),
+    scope,
+    summary: summarizeActions(actions),
+    actions,
+  };
+}
+
+export function formatActionsJson(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+export function formatActionsBrief(payload) {
+  const { project, scope, summary, actions } = payload;
+  const grouped = actions.reduce((acc, action) => {
+    if (!acc[action.area]) acc[action.area] = [];
+    acc[action.area].push(action);
+    return acc;
+  }, {});
+
+  const lines = [
+    `# SEO Intel Actions — ${project}`,
+    '',
+    `- Generated: ${payload.generatedAt}`,
+    `- Scope: ${scope}`,
+    `- Total actions: ${actions.length}`,
+    `- Priority mix: critical ${summary.critical}, high ${summary.high}, medium ${summary.medium}, low ${summary.low}`,
+    '',
+    '## Summary',
+    '',
+    `- Critical: ${summary.critical}`,
+    `- High: ${summary.high}`,
+    `- Medium: ${summary.medium}`,
+    `- Low: ${summary.low}`,
+    '',
+  ];
+
+  for (const area of ['technical', 'content', 'schema', 'structure']) {
+    const items = grouped[area] || [];
+    if (!items.length) continue;
+    lines.push(`## ${capitalize(area)}`);
+    lines.push('');
+    for (const action of items) {
+      lines.push(`### ${action.title}`);
+      lines.push(`- ID: ${action.id}`);
+      lines.push(`- Type: ${action.type}`);
+      lines.push(`- Priority: ${action.priority}`);
+      lines.push(`- Why: ${action.why}`);
+      if (action.evidence?.length) {
+        lines.push('- Evidence:');
+        for (const item of action.evidence) lines.push(`  - ${item}`);
+      }
+      if (action.implementationHints?.length) {
+        lines.push('- Implementation hints:');
+        for (const item of action.implementationHints) lines.push(`  - ${item}`);
+      }
+      lines.push('');
+    }
+  }
+
+  if (!actions.length) {
+    lines.push('## No actions found');
+    lines.push('');
+    lines.push('- The current dataset did not surface any qualifying actions for this scope.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/lib/gate.js

@@ -0,0 +1,204 @@
+/**
+ * SEO Intel — Feature Gates
+ *
+ * Friendly enforcement layer on top of lib/license.js.
+ * Premium features show clear upgrade messages instead of cryptic errors.
+ *
+ * Usage in CLI commands:
+ *   import { requirePro, enforceLimits } from '../lib/gate.js';
+ *   // At top of paid command:
+ *   if (!requirePro('analyze')) return;
+ *   // Before crawling:
+ *   const maxPages = enforceLimits().maxPages;
+ *
+ * Usage in report generation:
+ *   import { gateSection } from '../lib/gate.js';
+ *   const insights = gateSection('gsc-insights') ? getGscInsights(...) : null;
+ */
+
+import { loadLicense, isPro, isFree, getMaxPages, getMaxProjects } from './license.js';
+
+// ── Styled console output ───────────────────────────────────────────────────
+
+const GOLD = '\x1b[38;5;214m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+const CYAN = '\x1b[36m';
+
+function printUpgradeMessage(feature) {
+  console.log('');
+  console.log(`${GOLD}${BOLD}  ⭐ Paid Feature: ${feature}${RESET}`);
+  console.log(`${DIM}  This feature requires SEO Intel Solo (€19.99/mo).${RESET}`);
+  console.log('');
+  console.log(`${DIM}  Get your license at ${CYAN}https://froggo.pro/seo-intel${RESET}`);
+  console.log(`${DIM}  Then add your key: ${CYAN}SEO_INTEL_LICENSE=SI-xxxx-xxxx-xxxx-xxxx${RESET} ${DIM}in .env${RESET}`);
+  console.log('');
+}
+
+// ── Feature name → display name map ─────────────────────────────────────────
+
+const FEATURE_NAMES = {
+  'extract':          'AI Data Extraction (Ollama/Cloud)',
+  'analyze':          'Competitive Gap Analysis',
+  'keywords':         'AI Keyword Intelligence',
+  'run':              'Smart Scheduler',
+  'brief':            'Crawl Change Brief',
+  'velocity':         'Publishing Velocity',
+  'shallow':          'Shallow Content Audit',
+  'decay':            'Content Decay Detection',
+  'headings-audit':   'Heading Structure Audit',
+  'orphans':          'Orphan Page Detection',
+  'entities':         'Entity Coverage Analysis',
+  'friction':         'Friction Point Analysis',
+  'js-delta':         'JS Rendering Delta',
+  'html':             'HTML Dashboard',
+  'html-all':         'HTML Dashboard (All Projects)',
+  'gsc-insights':     'GSC Intelligence & Insights',
+  'competitive':      'Competitive Landscape Sections',
+  'unlimited-pages':  'Unlimited Crawl Pages',
+  'unlimited-projects': 'Unlimited Projects',
+};
+
+// ── CLI Gate — blocks command and shows upgrade message ──────────────────────
+
+/**
+ * Check if a pro feature is available. If not, print upgrade message.
+ * Returns true if allowed, false if blocked.
+ *
+ * @param {string} feature - Feature key (e.g., 'analyze', 'keywords')
+ * @returns {boolean}
+ */
+export function requirePro(feature) {
+  if (isPro()) return true;
+
+  const displayName = FEATURE_NAMES[feature] || feature;
+  printUpgradeMessage(displayName);
+  process.exit(1);
+}
+
+// ── Section Gate — for report/dashboard sections ────────────────────────────
+
+/**
+ * Check if a dashboard/report section should be rendered.
+ * Returns true if allowed (pro), false if should show upgrade placeholder.
+ *
+ * @param {string} section - Section key (e.g., 'gsc-insights', 'competitive')
+ * @returns {boolean}
+ */
+export function gateSection(section) {
+  return isPro();
+}
+
+/**
+ * Get HTML placeholder for a gated premium section in dashboards.
+ * Shows a tasteful "upgrade to unlock" card instead of the actual content.
+ */
+export function getPremiumPlaceholder(section) {
+  const displayName = FEATURE_NAMES[section] || section;
+  return `
+    <div class="card" style="text-align:center; padding: 32px 24px; opacity: 0.7;">
+      <div style="font-size: 1.5rem; margin-bottom: 8px;">⭐</div>
+      <h3 style="font-size: 0.85rem; margin-bottom: 6px;">${displayName}</h3>
+      <p style="font-size: 0.72rem; color: var(--text-muted); margin-bottom: 12px;">
+        This section requires SEO Intel Solo (€19.99/mo)
+      </p>
+      <a href="https://froggo.pro/seo-intel" target="_blank"
+         style="color: var(--accent-gold); font-size: 0.72rem; text-decoration: underline;">
+        Upgrade to unlock →
+      </a>
+    </div>
+  `;
+}
+
+// ── Limit Enforcement ───────────────────────────────────────────────────────
+
+/**
+ * Get enforced limits for the current tier.
+ * Use these values to cap crawl pages, project count, etc.
+ */
+export function enforceLimits() {
+  const license = loadLicense();
+  return {
+    maxPages: license.maxPagesPerDomain,
+    maxProjects: license.maxProjects,
+    tier: license.tier,
+    tierName: license.name,
+  };
+}
+
+/**
+ * Check if adding a new project would exceed the tier limit.
+ * Pass the current project count.
+ * Returns { allowed: boolean, limit: number, current: number }
+ */
+export function checkProjectLimit(currentCount) {
+  const max = getMaxProjects();
+  return {
+    allowed: currentCount < max,
+    limit: max,
+    current: currentCount,
+  };
+}
+
+/**
+ * Cap page count to tier limit.
+ * Returns the effective max pages.
+ */
+export function capPages(requestedPages) {
+  const max = getMaxPages();
+  if (!Number.isFinite(max)) return requestedPages;
+  return Math.min(requestedPages, max);
+}
+
+// ── License Status Display ──────────────────────────────────────────────────
+
+/**
+ * Print license status to console (for CLI status command / startup).
+ */
+export function printLicenseStatus() {
+  const license = loadLicense();
+
+  const sourceLabel = license.source === 'froggo' ? ' (Froggo)' : license.source === 'lemon-squeezy' ? ' (LS)' : '';
+
+  if (license.tier === 'agency') {
+    console.log(`${GOLD}${BOLD}  ⭐ SEO Intel Agency${RESET}`);
+    console.log(`${DIM}  License: ${license.key?.slice(0, 7)}...${license.key?.slice(-4)}${sourceLabel}${RESET}`);
+    console.log(`${DIM}  All features + white-label + team access${RESET}`);
+    if (license.stale) console.log(`\x1b[33m  ⚠ License cache stale — will re-validate on next network access${RESET}`);
+  } else if (license.tier === 'solo') {
+    console.log(`${GOLD}${BOLD}  ⭐ SEO Intel Solo${RESET}`);
+    console.log(`${DIM}  License: ${license.key?.slice(0, 7)}...${license.key?.slice(-4)}${sourceLabel}${RESET}`);
+    console.log(`${DIM}  All features unlocked${RESET}`);
+    if (license.stale) console.log(`\x1b[33m  ⚠ License cache stale — will re-validate on next network access${RESET}`);
+  } else {
+    console.log(`${DIM}  SEO Intel Free${RESET}`);
+    console.log(`${DIM}  Unlimited crawl · Raw SQLite data · No AI analysis · No dashboard${RESET}`);
+    if (license.invalidKey) {
+      console.log(`\x1b[33m  ⚠ ${license.reason}${RESET}`);
+    }
+    if (license.needsActivation) {
+      console.log(`\x1b[33m  ⚠ License key found but not yet validated — run any command to activate${RESET}`);
+    }
+    console.log(`${DIM}  Upgrade: ${CYAN}https://froggo.pro/seo-intel${RESET} ${DIM}— Solo €19.99/mo · €199/yr${RESET}`);
+  }
+  console.log('');
+}
+
+// ── Tier info for web/API ───────────────────────────────────────────────────
+
+/**
+ * Get tier info as JSON (for web wizard / API responses).
+ */
+export function getLicenseInfo() {
+  const license = loadLicense();
+  return {
+    tier: license.tier,
+    name: license.name,
+    active: license.active,
+    maxProjects: Number.isFinite(license.maxProjects) ? license.maxProjects : null,
+    maxPages: Number.isFinite(license.maxPagesPerDomain) ? license.maxPagesPerDomain : null,
+    features: license.features === 'all' ? 'all' : [...license.features],
+    upgradeUrl: 'https://froggo.pro/seo-intel',
+  };
+}