@warpmetrics/blog-seo 0.0.1

package/README.md

@@ -0,0 +1,162 @@
+# @warpmetrics/blog-seo
+
+Self-improving technical blog engine. Generates code-heavy blog posts, tracks search performance via Google Search Console, learns what works, and writes better content each cycle.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env  # Add your API keys
+```
+
+### Environment variables
+
+```
+OPENAI_API_KEY=sk-...
+WARPMETRICS_API_KEY=wm_...
+```
+
+### Configuration
+
+Create `blog-seo.config.json` in the directory you'll run the CLI from:
+
+```json
+{
+  "domain": "warpmetrics.com",
+  "siteUrl": "sc-domain:warpmetrics.com",
+  "outputDir": "./src/content/blog",
+  "manifest": "./blog-seo.json"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `domain` | Your domain. Used to fetch product context from `llms-full.txt` / `llms.txt` |
+| `siteUrl` | Google Search Console site URL (usually `sc-domain:yourdomain.com`) |
+| `outputDir` | Where generated markdown files are written |
+| `manifest` | Path to the manifest file that tracks generated posts |
+
+### Product context
+
+blog-seo fetches product context to ground generated content in accurate information. It looks for:
+
+1. `https://{domain}/llms-full.txt` (preferred)
+2. `https://{domain}/llms.txt` (fallback)
+
+These follow the [llms.txt convention](https://llmstxt.org/) — a plain text file describing your product, APIs, features, and pricing. When present, this context is included in every generation prompt so the LLM uses real API names and features instead of hallucinating.
+
+If neither file exists, posts are generated without product context.
+
+## Commands
+
+### `blog-seo auth`
+
+Authenticate with Google Search Console via OAuth.
+
+```bash
+npx blog-seo auth
+```
+
+Saves credentials to `.gsc-credentials.json`.
+
+### `blog-seo seed`
+
+Generate initial blog posts from built-in seed topics. No GSC data needed.
+
+```bash
+npx blog-seo seed --max 3
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max` | 5 | Maximum posts to generate |
+| `--output` | from config | Output directory |
+| `--max-retries` | 2 | Retries per post on validation failure |
+
+### `blog-seo analyze`
+
+Display GSC performance for existing blog posts.
+
+```bash
+npx blog-seo analyze --days 30
+```
+
+### `blog-seo run`
+
+Full flywheel: Feedback → Learn → Plan → Generate.
+
+```bash
+npx blog-seo run --max-new 3 --max-rewrites 2
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-new` | 3 | Max new posts per run |
+| `--max-rewrites` | 2 | Max rewrites of underperformers |
+| `--min-days` | 14 | Days before tracking a post |
+| `--min-impressions` | 50 | Min impressions for feedback |
+| `--max-retries` | 2 | Retries per post on validation failure |
+| `--output` | from config | Output directory |
+| `--manifest` | from config | Manifest file path |
+
+## How it works
+
+Each `run` cycle executes four phases:
+
+1. **Feedback** — Fetches GSC metrics for tracked posts. Classifies each as High Traffic, Improved, Stagnant, or Declining.
+
+2. **Learn** — Analyzes high-performing posts to find patterns (topic, structure, code density). Updates generation prompts with learned patterns.
+
+3. **Plan** — Identifies topic gaps from GSC query data (queries with impressions but no matching content). Selects underperformers for rewrites.
+
+4. **Generate** — Writes new posts or rewrites underperformers. Each post goes through a two-step process (outline → full post) and is validated for structure, code correctness, quality, and SEO before being written.
+
+Every cycle creates a WarpMetrics run with outcomes and a "Continue Optimization" act that links to the next run, forming an unbroken improvement chain.
+
+## Generated post format
+
+Posts are markdown with YAML frontmatter:
+
+```markdown
+---
+title: "How to Track LLM API Costs"
+description: "Track OpenAI, Anthropic, and Cohere costs..."
+date: 2026-02-15
+author: "blog-seo"
+keywords: ["llm costs", "api cost tracking"]
+generated: true
+---
+
+# How to Track LLM API Costs
+
+[code-heavy content]
+```
+
+The `generated: true` field distinguishes machine-generated posts from human-written ones.
+
+## Manifest
+
+`blog-seo.json` tracks which posts were generated and their baselines:
+
+```json
+{
+  "tracking-llm-costs": {
+    "slug": "tracking-llm-costs",
+    "title": "How to Track LLM API Costs",
+    "generatedAt": "2026-02-15T10:00:00Z",
+    "runId": "wm_run_xxx",
+    "targetKeywords": ["track llm costs"],
+    "version": 1,
+    "baseline": { "ctr": null, "position": null, "impressions": 0 }
+  }
+}
+```
+
+## Validation
+
+Every generated post passes four validators before being written:
+
+1. **Structure** — Frontmatter, H1, 3+ H2 sections, 2+ code blocks, 800-3000 words
+2. **Code** — Matched code fences, no truncated snippets
+3. **Quality** — LLM-scored 1-10 (must score 7+)
+4. **SEO** — Title contains keyword, description 140-160 chars, H2 contains keyword

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@warpmetrics/blog-seo",
+  "version": "0.0.1",
+  "description": "Self-improving technical blog engine with Google Search Console feedback",
+  "type": "module",
+  "bin": {
+    "blog-seo": "./src/cli/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./core/*": "./src/core/*.js"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js"
+  ],
+  "scripts": {
+    "dev": "node src/cli/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "preversion": "npm test",
+    "release:patch": "npm version patch && git push origin main --tags",
+    "release:minor": "npm version minor && git push origin main --tags"
+  },
+  "dependencies": {
+    "@warpmetrics/warp": "^0.0.13",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "googleapis": "^144.0.0",
+    "open": "^10.1.0",
+    "openai": "^4.77.3",
+    "ora": "^8.1.1"
+  },
+  "keywords": [
+    "seo",
+    "blog",
+    "google-search-console",
+    "self-improving",
+    "ai",
+    "technical-writing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warpmetrics/blog-seo.git"
+  },
+  "homepage": "https://github.com/warpmetrics/blog-seo#readme",
+  "bugs": {
+    "url": "https://github.com/warpmetrics/blog-seo/issues"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli/analyze.js

@@ -0,0 +1,86 @@
+import { createGSCClient } from '../core/gsc-client.js';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs/promises';
+
+export async function analyzeCommand(options) {
+  const spinner = ora('Loading configuration...').start();
+
+  try {
+    const config = JSON.parse(await fs.readFile('./blog-seo.config.json', 'utf-8'));
+
+    const gsc = createGSCClient('./.gsc-credentials.json');
+
+    spinner.text = 'Authenticating with Google Search Console...';
+    await gsc.authenticate();
+
+    spinner.text = 'Fetching performance data...';
+
+    const endDate = new Date().toISOString().split('T')[0];
+    const startDate = new Date(Date.now() - parseInt(options.days) * 24 * 60 * 60 * 1000)
+      .toISOString()
+      .split('T')[0];
+
+    const rows = await gsc.getPagePerformance(config.siteUrl, startDate, endDate);
+
+    // Filter to blog posts only
+    const minImpressions = parseInt(options.minImpressions);
+    const blogPosts = rows
+      .filter(row => {
+        const url = row.keys[0];
+        if (!url.includes('/blog/')) return false;
+        return row.impressions >= minImpressions;
+      })
+      .sort((a, b) => b.impressions - a.impressions);
+
+    spinner.succeed(`Analyzed ${blogPosts.length} blog posts`);
+
+    console.log(chalk.bold('\nBlog Performance Summary\n'));
+
+    if (blogPosts.length === 0) {
+      console.log(chalk.gray('No blog posts with enough impressions found.'));
+      console.log(chalk.gray(`Run ${chalk.white('blog-seo seed')} to generate initial posts.`));
+      return;
+    }
+
+    const avgCTR = (blogPosts.reduce((sum, r) => sum + r.ctr, 0) / blogPosts.length * 100).toFixed(2);
+    const avgPosition = (blogPosts.reduce((sum, r) => sum + r.position, 0) / blogPosts.length).toFixed(1);
+    const totalClicks = blogPosts.reduce((sum, r) => sum + r.clicks, 0);
+
+    console.log(`Posts analyzed: ${chalk.cyan(blogPosts.length)}`);
+    console.log(`Average CTR: ${chalk.cyan(avgCTR + '%')}`);
+    console.log(`Average Position: ${chalk.cyan(avgPosition)}`);
+    console.log(`Total Clicks: ${chalk.cyan(totalClicks.toLocaleString())}`);
+
+    const topPerformers = blogPosts.filter(r => r.position < 10);
+    const underperformers = blogPosts.filter(r => r.position > 15 && r.impressions >= 200);
+
+    if (topPerformers.length > 0) {
+      console.log(chalk.bold('\nTop Performers (position < 10)\n'));
+      topPerformers.slice(0, 5).forEach((row, i) => {
+        const slug = row.keys[0].split('/blog/')[1]?.replace(/\/$/, '') || row.keys[0];
+        console.log(`${i + 1}. ${chalk.green(slug)}`);
+        console.log(`   Position: ${chalk.cyan(row.position.toFixed(1))} | CTR: ${chalk.cyan((row.ctr * 100).toFixed(2) + '%')} | Clicks: ${chalk.gray(row.clicks)}\n`);
+      });
+    }
+
+    if (underperformers.length > 0) {
+      console.log(chalk.bold('\nRewrite Candidates (position > 15, 200+ impressions)\n'));
+      underperformers.slice(0, 5).forEach((row, i) => {
+        const slug = row.keys[0].split('/blog/')[1]?.replace(/\/$/, '') || row.keys[0];
+        console.log(`${i + 1}. ${chalk.yellow(slug)}`);
+        console.log(`   Position: ${chalk.red(row.position.toFixed(1))} | Impressions: ${chalk.gray(row.impressions.toLocaleString())} | CTR: ${chalk.gray((row.ctr * 100).toFixed(2) + '%')}\n`);
+      });
+    }
+
+    console.log(chalk.gray(`Run ${chalk.white('blog-seo run')} to generate new posts and rewrite underperformers`));
+
+  } catch (err) {
+    spinner.fail('Analysis failed');
+    console.error(chalk.red(err.message));
+    if (err.stack) {
+      console.error(chalk.gray(err.stack));
+    }
+    process.exit(1);
+  }
+}

package/src/cli/auth.js

@@ -0,0 +1,34 @@
+import { createGSCClient } from '../core/gsc-client.js';
+import chalk from 'chalk';
+import ora from 'ora';
+
+export async function authCommand() {
+  const spinner = ora('Authenticating with Google Search Console...').start();
+
+  try {
+    const client = createGSCClient('./.gsc-credentials.json');
+
+    // Check if already authenticated
+    try {
+      const isAuth = await client.authenticate();
+      if (isAuth) {
+        spinner.succeed('Already authenticated!');
+        process.exit(0);
+      }
+    } catch {
+      // Not authenticated or token expired — proceed to OAuth
+    }
+
+    spinner.text = 'Opening browser for OAuth...';
+    await client.initiateOAuth();
+
+    spinner.succeed('Authentication successful!');
+    console.log(chalk.gray('Credentials saved to .gsc-credentials.json'));
+    console.log(chalk.yellow('\nWARNING: Add .gsc-credentials.json to .gitignore'));
+    process.exit(0);
+  } catch (err) {
+    spinner.fail('Authentication failed');
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { authCommand } from './auth.js';
+import { analyzeCommand } from './analyze.js';
+import { runCommand } from './run.js';
+import { seedCommand } from './seed.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('blog-seo')
+  .description('Self-improving technical blog engine with Google Search Console feedback')
+  .version(version);
+
+program
+  .command('auth')
+  .description('Authenticate with Google Search Console')
+  .action(authCommand);
+
+program
+  .command('analyze')
+  .description('Display GSC performance for existing blog posts')
+  .option('--days <number>', 'Days of data to analyze', '30')
+  .option('--min-impressions <number>', 'Minimum impressions to consider', '50')
+  .action(analyzeCommand);
+
+program
+  .command('seed')
+  .description('Generate initial blog posts from built-in seed topics')
+  .option('--max <number>', 'Maximum posts to generate', '5')
+  .option('--output <path>', 'Output directory for markdown files')
+  .option('--max-retries <number>', 'Max retries per post on validation failure', '2')
+  .action(seedCommand);
+
+program
+  .command('run')
+  .description('Run the full blog-seo flywheel: feedback → learn → plan → generate')
+  .option('--max-new <number>', 'Maximum new posts per run', '3')
+  .option('--max-rewrites <number>', 'Maximum rewrites of underperformers', '2')
+  .option('--min-days <number>', 'Days before tracking a post', '14')
+  .option('--min-impressions <number>', 'Minimum impressions for feedback', '50')
+  .option('--max-retries <number>', 'Max retries per post on validation failure', '2')
+  .option('--output <path>', 'Output directory for markdown files')
+  .option('--manifest <path>', 'Manifest file path')
+  .action(runCommand);
+
+program.parse();

package/src/cli/run.js

@@ -0,0 +1,227 @@
+import { createGSCClient } from '../core/gsc-client.js';
+import { generate } from '../core/generator.js';
+import { trackPerformance } from '../core/tracker.js';
+import { analyze } from '../core/improver.js';
+import { identifyTopics } from '../core/topic-planner.js';
+import { createPromptManager } from '../core/prompt-manager.js';
+import { fetchContext } from '../core/context.js';
+import OpenAI from 'openai';
+import { warp, run, group, outcome, act, flush } from '@warpmetrics/warp';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function runCommand(options) {
+  const spinner = ora('Starting Blog SEO...').start();
+
+  try {
+    const config = JSON.parse(await fs.readFile('./blog-seo.config.json', 'utf-8'));
+
+    // Poll for Continue Optimization act from previous run
+    let prevAct = null;
+    try {
+      const res = await fetch(
+        'https://api.warpmetrics.com/v1/acts?name=Continue%20Optimization&hasFollowUp=false&limit=1',
+        { headers: { 'Authorization': `Bearer ${process.env.WARPMETRICS_API_KEY}` } }
+      );
+      if (res.ok) {
+        const body = await res.json();
+        if (body.data?.length > 0) prevAct = body.data[0].id;
+      }
+    } catch {}
+
+    // Create the run — linked to previous if exists
+    const r = prevAct
+      ? run(prevAct, 'Blog SEO', { domain: config.domain })
+      : run('Blog SEO', { domain: config.domain });
+
+    // Setup
+    const openai = warp(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+      apiKey: process.env.WARPMETRICS_API_KEY,
+    });
+
+    const gsc = createGSCClient('./.gsc-credentials.json');
+    await gsc.authenticate();
+
+    const prompts = createPromptManager('.');
+    await prompts.initialize();
+
+    // Fetch product context
+    spinner.text = 'Fetching product context...';
+    const context = config.domain ? await fetchContext(config.domain) : null;
+    if (context) {
+      spinner.succeed('Product context loaded');
+    } else {
+      spinner.warn('No product context found (no llms-full.txt or llms.txt)');
+    }
+
+    const outputDir = path.resolve(options.output || config.outputDir || './output');
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const manifestPath = options.manifest || config.manifest || './blog-seo.json';
+
+    // Load manifest
+    let manifest = {};
+    try {
+      manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    } catch {}
+
+    // ═══════════════════════════════════════════
+    // Phase 1: Feedback
+    // ═══════════════════════════════════════════
+    spinner.text = 'Collecting feedback...';
+    const feedbackGrp = group(r, 'Feedback');
+
+    const feedbackResults = await trackPerformance(
+      gsc,
+      feedbackGrp,
+      config.siteUrl,
+      manifest,
+      parseInt(options.minDays)
+    );
+
+    // Update baselines in manifest
+    if (feedbackResults.updates) {
+      for (const [slug, update] of Object.entries(feedbackResults.updates)) {
+        if (manifest[slug]) {
+          manifest[slug].baseline = update;
+        }
+      }
+    }
+
+    if (feedbackResults.tracked > 0) {
+      spinner.succeed(`Feedback: ${feedbackResults.tracked} tracked, ${feedbackResults.highTraffic} high traffic`);
+    } else {
+      spinner.info('Feedback: no posts eligible yet');
+    }
+
+    // ═══════════════════════════════════════════
+    // Phase 2: Learn
+    // ═══════════════════════════════════════════
+    spinner.start('Analyzing patterns...');
+    const learnGrp = group(r, 'Learn');
+
+    const learnResults = await analyze(
+      openai,
+      process.env.WARPMETRICS_API_KEY,
+      prompts,
+      learnGrp,
+      config.domain
+    );
+
+    if (learnResults) {
+      spinner.succeed(`Learn: ${learnResults.patternsLearned} patterns learned`);
+    } else {
+      spinner.info('Learn: not enough data yet');
+    }
+
+    // ═══════════════════════════════════════════
+    // Phase 3: Plan
+    // ═══════════════════════════════════════════
+    spinner.start('Identifying topics...');
+    const planGrp = group(r, 'Plan');
+
+    const planResults = await identifyTopics(
+      openai,
+      gsc,
+      planGrp,
+      config.siteUrl,
+      manifest,
+      {
+        maxNew: parseInt(options.maxNew),
+        maxRewrites: parseInt(options.maxRewrites),
+      }
+    );
+
+    spinner.succeed(
+      `Plan: ${planResults.newTopics.length} new topics, ${planResults.rewriteCandidates.length} rewrites`
+    );
+
+    // ═══════════════════════════════════════════
+    // Phase 4: Generate
+    // ═══════════════════════════════════════════
+    spinner.start('Generating posts...');
+    const generateGrp = group(r, 'Generate');
+
+    // Generate new posts
+    const allTopics = [...planResults.newTopics];
+
+    // For rewrites, load existing content
+    for (const candidate of planResults.rewriteCandidates) {
+      try {
+        const filePath = path.join(outputDir, `${candidate.slug}.md`);
+        const existingContent = await fs.readFile(filePath, 'utf-8');
+        allTopics.push({ ...candidate, existingContent });
+      } catch {
+        // File not found — skip rewrite
+      }
+    }
+
+    const genResults = await generate(openai, prompts, generateGrp, allTopics, {
+      maxRetries: parseInt(options.maxRetries) || 2,
+      context,
+    });
+
+    spinner.succeed(
+      `Generate: ${genResults.results.length} created` +
+      (genResults.failures.length > 0 ? `, ${genResults.failures.length} failed` : '')
+    );
+
+    // ═══════════════════════════════════════════
+    // Write files and update manifest
+    // ═══════════════════════════════════════════
+    for (const result of genResults.results) {
+      const filePath = path.join(outputDir, `${result.slug}.md`);
+      await fs.writeFile(filePath, result.markdown);
+
+      manifest[result.slug] = {
+        slug: result.slug,
+        title: result.title,
+        generatedAt: result.generatedAt,
+        runId: r.id,
+        targetKeywords: result.targetKeywords,
+        version: (manifest[result.slug]?.version || 0) + 1,
+        baseline: manifest[result.slug]?.baseline || { ctr: null, position: null, impressions: 0 },
+      };
+    }
+
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+
+    // ═══════════════════════════════════════════
+    // Run complete — link to next run
+    // ═══════════════════════════════════════════
+    const allFailed = genResults.results.length === 0 && genResults.failures.length > 0;
+    const runComplete = outcome(r, allFailed ? 'Run Failed' : 'Run Complete', {
+      postsGenerated: genResults.results.filter(r => !r.rewrite).length,
+      postsRewritten: genResults.results.filter(r => r.rewrite).length,
+      generationFailed: genResults.failures.length,
+      tracked: feedbackResults.tracked,
+      highTraffic: feedbackResults.highTraffic,
+      patternsLearned: learnResults?.patternsLearned || 0,
+      topicsIdentified: planResults.newTopics.length,
+    });
+
+    act(runComplete, 'Continue Optimization');
+
+    await flush();
+
+    // Summary
+    console.log(chalk.bold('\nBlog SEO Complete\n'));
+    console.log(`  Feedback:  ${feedbackResults.tracked} tracked, ${feedbackResults.highTraffic} high traffic`);
+    console.log(`  Learn:     ${learnResults ? `${learnResults.patternsLearned} patterns` : 'insufficient data'}`);
+    console.log(`  Plan:      ${planResults.newTopics.length} new, ${planResults.rewriteCandidates.length} rewrites`);
+    console.log(`  Generate:  ${genResults.results.length} created, ${genResults.failures.length} failed`);
+    console.log(chalk.gray(`\n  Run: https://app.warpmetrics.com/runs/${r.id}`));
+    console.log(chalk.gray(`  Output: ${outputDir}`));
+    console.log(chalk.gray(`  Manifest: ${manifestPath}`));
+
+  } catch (err) {
+    spinner.fail('Blog SEO failed');
+    console.error(chalk.red(err.message));
+    if (err.stack) {
+      console.error(chalk.gray(err.stack));
+    }
+    process.exit(1);
+  }
+}