seo-intel 1.5.24 → 1.5.25

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.5.25 (2026-05-16)
+
+### New — `seo-intel intel <project>` — canonical agent-facing entry point
+- Returns structured project intelligence as JSON or markdown — the single source of truth that upcoming MCP server, dashboard, and prompt-copy modal will all wrap (one function, four surfaces).
+- Slices:
+  - `--for=raw` (**free**) — page/keyword/heading/schema/sitemap inventory per domain. Pipe into your own AI agent for self-service analysis.
+  - `--for=audit` (paid) — citability scores + active insights ledger
+  - `--for=blog` (paid) — keyword gaps + long tails + drafting hints
+  - `--for=competitor` (paid) — competitor summary + keyword matrix + positioning
+- `--format=json` for agents; `--format=md` for humans / agent context windows
+- Paid slices use the existing `requirePro()` gate — free users see a standard upgrade message; paid users get the data.
+- New library: `lib/intel.js` exports `getIntel(db, project, opts)` + `intelToMarkdown(envelope)` for reuse from any surface.
+
 ## 1.5.24 (2026-05-16)
 
 ### Dashboard — projects with owned subdomains + sitemap data no longer vanish

package/cli.js

@@ -1415,6 +1415,47 @@ program
     process.exit(0);
   });
 
+// ── INTEL (canonical agent-facing entry point) ─────────────────────────────
+// Returns structured intelligence about a project. Same function backs MCP +
+// future surfaces. Free tier gets `raw`; paid slices are license-gated.
+program
+  .command('intel <project>')
+  .description('Structured project intelligence for AI agents (raw=free; audit/blog/competitor=paid)')
+  .option('--for <slice>', 'Slice: raw | audit | blog | competitor', 'raw')
+  .option('--format <fmt>', 'Output format: json | md', 'json')
+  .action(async (project, opts) => {
+    const isJson = opts.format === 'json';
+    const { getIntel, intelToMarkdown, FREE_SLICES, INTEL_SLICES } = await import('./lib/intel.js');
+
+    if (!INTEL_SLICES.includes(opts.for)) {
+      const msg = `Unknown slice "${opts.for}". Available: ${INTEL_SLICES.join(', ')}`;
+      if (isJson) { console.log(JSON.stringify({ error: msg })); process.exit(1); }
+      console.error(chalk.red(msg)); process.exit(1);
+    }
+
+    // Free slices skip the gate; paid slices use the standard requirePro pattern.
+    if (!FREE_SLICES.includes(opts.for)) {
+      if (!requirePro(`intel-${opts.for}`)) return;
+    }
+
+    // Validate project exists (loadConfig will throw with a helpful message otherwise)
+    loadConfig(project);
+    const db = getDb();
+
+    try {
+      const envelope = getIntel(db, project, { for: opts.for });
+      if (isJson) {
+        console.log(JSON.stringify(envelope, null, 2));
+      } else {
+        console.log(intelToMarkdown(envelope));
+      }
+    } catch (err) {
+      if (isJson) { console.log(JSON.stringify({ error: err.message })); process.exit(1); }
+      console.error(chalk.red('intel failed: ') + err.message);
+      process.exit(1);
+    }
+  });
+
 // ── STATUS ─────────────────────────────────────────────────────────────────
 program
   .command('status')

package/lib/gate.js

@@ -60,6 +60,9 @@ const FEATURE_NAMES = {
   'unlimited-pages':  'Unlimited Crawl Pages',
   'unlimited-projects': 'Unlimited Projects',
   'blog-draft':        'AEO Blog Draft Generator',
+  'intel-audit':       'Intel Audit Digest (AI-agent-ready)',
+  'intel-blog':        'Intel Blog Digest (AI-agent-ready)',
+  'intel-competitor':  'Intel Competitor Digest (AI-agent-ready)',
 };
 
 // ── CLI Gate — blocks command and shows upgrade message ──────────────────────

package/lib/intel.js

@@ -0,0 +1,177 @@
+/**
+ * lib/intel.js — Canonical "give me intelligence about this project" entry point.
+ *
+ * Single source of truth backing every agent-facing surface:
+ *   - CLI:  `seo-intel intel <project>` (this file's first consumer)
+ *   - MCP:  `seo-intel-mcp` server (v1.5.26 — wraps this same function)
+ *   - HTTP: dashboard / future REST endpoint
+ *
+ * Slices:
+ *   raw         (free)  — page/keyword/heading inventory, no analysis
+ *   audit       (paid)  — citability + technical + active insights
+ *   blog        (paid)  — gaps + tone hints for drafting
+ *   competitor  (paid)  — competitor summary + schema landscape
+ *
+ * Output is a stable structured object — agents should be able to chain calls
+ * without prompt gymnastics. Keep the schema additive across versions.
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getActiveInsights, getCompetitorSummary, getKeywordMatrix } from '../db/db.js';
+import { getCitabilityScores } from '../analyses/aeo/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
+
+export const INTEL_SLICES = ['raw', 'audit', 'blog', 'competitor'];
+export const FREE_SLICES = ['raw'];
+
+/**
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} project
+ * @param {{ for?: string }} [opts]
+ * @returns {object} structured intel digest
+ */
+export function getIntel(db, project, opts = {}) {
+  const slice = opts.for || 'raw';
+  if (!INTEL_SLICES.includes(slice)) {
+    throw new Error(`Unknown intel slice "${slice}". Available: ${INTEL_SLICES.join(', ')}`);
+  }
+
+  const envelope = {
+    project,
+    for: slice,
+    tier: FREE_SLICES.includes(slice) ? 'free' : 'paid',
+    generated_at: new Date().toISOString(),
+    seo_intel_version: VERSION,
+    data: {},
+  };
+
+  if (slice === 'raw')        envelope.data = collectRaw(db, project);
+  if (slice === 'audit')      envelope.data = collectAudit(db, project);
+  if (slice === 'blog')       envelope.data = collectBlog(db, project);
+  if (slice === 'competitor') envelope.data = collectCompetitor(db, project);
+
+  return envelope;
+}
+
+// ── Slice collectors ────────────────────────────────────────────────────────
+
+function collectRaw(db, project) {
+  const domains = db.prepare(
+    `SELECT d.domain, d.role, d.last_crawled,
+            COUNT(p.id) AS pages,
+            SUM(CASE WHEN p.status_code = 200 THEN 1 ELSE 0 END) AS pages_ok
+     FROM domains d
+     LEFT JOIN pages p ON p.domain_id = d.id
+     WHERE d.project = ?
+     GROUP BY d.id
+     ORDER BY d.role, d.domain`
+  ).all(project);
+
+  const totals = db.prepare(
+    `SELECT
+       (SELECT COUNT(*) FROM pages p JOIN domains d ON d.id=p.domain_id WHERE d.project=?)     AS pages,
+       (SELECT COUNT(*) FROM keywords k JOIN pages p ON p.id=k.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS keywords,
+       (SELECT COUNT(*) FROM headings h JOIN pages p ON p.id=h.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS headings,
+       (SELECT COUNT(*) FROM page_schemas s JOIN pages p ON p.id=s.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS schemas,
+       (SELECT COUNT(*) FROM sitemap_urls u JOIN domains d ON d.id=u.domain_id WHERE d.project=?) AS sitemap_urls`
+  ).get(project, project, project, project, project) || {};
+
+  const lastCrawl = domains.reduce((m, d) => Math.max(m, d.last_crawled || 0), 0);
+
+  return {
+    domains: domains.map(d => ({
+      domain: d.domain,
+      role: d.role,
+      pages: d.pages,
+      pages_ok: d.pages_ok,
+      last_crawled: d.last_crawled ? new Date(d.last_crawled).toISOString() : null,
+    })),
+    totals: {
+      pages: totals.pages || 0,
+      keywords: totals.keywords || 0,
+      headings: totals.headings || 0,
+      schemas: totals.schemas || 0,
+      sitemap_urls: totals.sitemap_urls || 0,
+    },
+    last_crawl: lastCrawl ? new Date(lastCrawl).toISOString() : null,
+    note: 'Free tier — raw crawl inventory. Pipe into your own AI for analysis, or upgrade to Solo for citability/gap/competitor intel.',
+  };
+}
+
+function collectAudit(db, project) {
+  const insights = getActiveInsights(db, project);
+  let citability = null;
+  try { citability = getCitabilityScores(db, project); } catch { /* citability_scores table may not exist if AEO never run */ }
+  return {
+    citability,
+    insights: {
+      keyword_gaps: insights.keyword_gaps,
+      content_gaps: insights.content_gaps,
+      technical_gaps: insights.technical_gaps,
+      quick_wins: insights.quick_wins,
+      site_watch: insights.site_watch,
+    },
+    last_insight_at: insights.generated_at ? new Date(insights.generated_at).toISOString() : null,
+  };
+}
+
+function collectBlog(db, project) {
+  const insights = getActiveInsights(db, project);
+  return {
+    keyword_gaps: insights.keyword_gaps,
+    long_tails: insights.long_tails,
+    content_gaps: insights.content_gaps,
+    keyword_inventor: insights.keyword_inventor,
+    positioning: insights.positioning,
+    drafting_hint: 'Each keyword_gap or long_tail is a candidate draft target. Pair with topic clusters from `seo-intel templates <project>` and citability gaps from `--for=audit` for AEO-aware drafts.',
+  };
+}
+
+function collectCompetitor(db, project) {
+  const summary = getCompetitorSummary(db, project);
+  const matrix = getKeywordMatrix(db, project);
+  const insights = getActiveInsights(db, project);
+  return {
+    summary,
+    keyword_matrix: matrix,
+    positioning: insights.positioning,
+    new_pages: insights.new_pages,
+  };
+}
+
+// ── Markdown formatter ──────────────────────────────────────────────────────
+
+export function intelToMarkdown(envelope) {
+  const { project, for: slice, tier, generated_at, data } = envelope;
+  const lines = [
+    `# SEO Intel — ${project}`,
+    `> slice: \`${slice}\` · tier: \`${tier}\` · generated: ${generated_at}`,
+    '',
+  ];
+
+  if (slice === 'raw') {
+    lines.push('## Crawl inventory', '');
+    lines.push(`- **Total pages:** ${data.totals.pages}`);
+    lines.push(`- **Keywords:** ${data.totals.keywords}`);
+    lines.push(`- **Headings:** ${data.totals.headings}`);
+    lines.push(`- **Schemas:** ${data.totals.schemas}`);
+    lines.push(`- **Sitemap URLs:** ${data.totals.sitemap_urls}`);
+    lines.push(`- **Last crawl:** ${data.last_crawl || 'never'}`, '');
+    lines.push('## Domains', '');
+    lines.push('| Domain | Role | Pages (200) | Last crawled |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const d of data.domains) {
+      lines.push(`| ${d.domain} | ${d.role} | ${d.pages_ok}/${d.pages} | ${d.last_crawled || '—'} |`);
+    }
+    lines.push('', `> ${data.note}`);
+  } else {
+    // Generic JSON-in-fence fallback for paid slices — agents can parse either way.
+    lines.push(`## ${slice} (data)`, '', '```json', JSON.stringify(data, null, 2), '```');
+  }
+
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.5.24",
+  "version": "1.5.25",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",