git-paid 0.0.0-stage → 2.1.0

package/lib/pseo.js

@@ -0,0 +1,491 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function escapeHtml(str) {
+  return String(str || "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function humanizeSlug(routePath, cleanName = "postbuild") {
+  const parts = String(routePath || "").split("/").filter(Boolean);
+  const category = parts[0] || "guides";
+  const pageSlug = parts[1] || "overview";
+
+  const words = pageSlug
+    .split("-")
+    .map((w) => {
+      if (w.toLowerCase() === cleanName.toLowerCase()) return cleanName;
+      if (w === "seo") return "SEO";
+      if (w === "pseo") return "Programmatic SEO";
+      if (w === "roi") return "ROI";
+      if (w === "api") return "API";
+      if (w === "ai") return "AI";
+      if (w === "saas") return "SaaS";
+      if (w === "cli") return "CLI";
+      if (w === "nextjs") return "Next.js";
+      if (w === "vs") return "vs.";
+      return w.charAt(0).toUpperCase() + w.slice(1);
+    })
+    .join(" ");
+
+  const categoryLabel =
+    {
+      "use-cases": "Use Case Architecture",
+      compare: "Technical Comparison",
+      templates: "Starter Kit & Boilerplate",
+      alternatives: "Ecosystem Evaluation",
+      calculators: "Interactive ROI Model",
+      guides: "Implementation Guide",
+      checklists: "Launch Verification Checklist"
+    }[category] || "Developer Guide";
+
+  return { category, categoryLabel, title: words };
+}
+
+/**
+ * Generates a complete, indexable, light-mode HTML landing page for a Programmatic SEO route.
+ */
+export function renderSinglePseoPage(page, allPages = [], options = {}) {
+  const origin = (options.origin || "https://postbuild.dev").replace(/\/$/, "");
+  const cleanName = options.cleanName || "postbuild";
+  const domain = options.domain || "postbuild.dev";
+  const { category, categoryLabel, title } = humanizeSlug(page.path, cleanName);
+
+  const fullTitle = `${title} — ${categoryLabel} | ${cleanName}`;
+  const canonicalUrl = `${origin}${page.path}`;
+  const metaDescription = `Complete ${new Date().getFullYear()} ${categoryLabel.toLowerCase()} for ${page.keyword}. Automate 25 programmatic SEO routes, provision a @postbuild.dev verification inbox, and dispatch to 85 directories with git paid.`;
+
+  const relatedPages = allPages.filter((p) => p.path !== page.path).slice(0, 8);
+
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "SoftwareApplication",
+        name: cleanName,
+        url: origin,
+        applicationCategory: "DeveloperApplication",
+        operatingSystem: "Web, macOS, Windows, Linux",
+        description: metaDescription,
+        offers: {
+          "@type": "Offer",
+          price: "29.00",
+          priceCurrency: "USD"
+        }
+      },
+      {
+        "@type": "BreadcrumbList",
+        itemListElement: [
+          { "@type": "ListItem", position: 1, name: cleanName, item: origin },
+          { "@type": "ListItem", position: 2, name: categoryLabel, item: `${origin}${page.path}` }
+        ]
+      },
+      {
+        "@type": "FAQPage",
+        mainEntity: [
+          {
+            "@type": "Question",
+            name: `How does ${cleanName} automate ${page.keyword}?`,
+            acceptedAnswer: {
+              "@type": "Answer",
+              text: `By running npx git-paid (or connecting the Postbuild MCP server to Claude Code, Cursor, or Gemini), ${cleanName} audits your live domain, synthesizes 25 programmatic SEO routes, provisions a dedicated @postbuild.dev verification inbox, and dispatches your launch kit across 85 curated directories.`
+            }
+          },
+          {
+            "@type": "Question",
+            name: `Why use a Stateful MCP server for post-build SEO and directory dispatch?`,
+            acceptedAnswer: {
+              "@type": "Answer",
+              text: `Postbuild MCP uses watermark context residuals (unchanged@vN) and an in-memory superset cache to reduce multi-turn agent token consumption by over 75% while enforcing Two-Phase Cryptographic Optimistic Concurrency Control (OCC) before dispatching live directory submissions.`
+            }
+          }
+        ]
+      }
+    ]
+  };
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(fullTitle)}</title>
+  <meta name="description" content="${escapeHtml(metaDescription)}" />
+  <link rel="canonical" href="${escapeHtml(canonicalUrl)}" />
+  <meta property="og:type" content="article" />
+  <meta property="og:site_name" content="${escapeHtml(cleanName)}" />
+  <meta property="og:title" content="${escapeHtml(fullTitle)}" />
+  <meta property="og:description" content="${escapeHtml(metaDescription)}" />
+  <meta property="og:url" content="${escapeHtml(canonicalUrl)}" />
+  <meta property="og:image" content="${escapeHtml(origin)}/og-card.png" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content="${escapeHtml(fullTitle)}" />
+  <meta name="twitter:description" content="${escapeHtml(metaDescription)}" />
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='8' fill='%2309090B'/%3E%3Crect x='6' y='7' width='8' height='8' rx='2' stroke='%23FFFFFF' stroke-width='2.2' fill='none'/%3E%3Crect x='6' y='17' width='8' height='8' rx='2' stroke='%23FFFFFF' stroke-width='2.2' opacity='0.5' fill='none'/%3E%3Cpath d='M18 11H26M26 11L22.8 7.8M26 11L22.8 14.2' stroke='%2338BDF8' stroke-width='2.2' stroke-linecap='round' stroke-linejoin='round'/%3E%3Ccircle cx='22' cy='21' r='2.8' fill='%23FFFFFF'/%3E%3C/svg%3E" />
+  <script type="application/ld+json">${JSON.stringify(jsonLd)}</script>
+  <style>
+    :root {
+      --bg: #fafafa;
+      --surface: #ffffff;
+      --text: #09090b;
+      --muted: #52525b;
+      --subtle: #71717a;
+      --border: #e4e4e7;
+      --accent: #0284c7;
+      --accent-soft: #f0f9ff;
+      --emerald: #059669;
+      --emerald-soft: #ecfdf5;
+    }
+    * { box-sizing: border-box; }
+    html, body {
+      margin: 0;
+      padding: 0;
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif;
+      line-height: 1.6;
+      -webkit-text-size-adjust: 100%;
+      text-size-adjust: 100%;
+    }
+    .container {
+      max-width: 980px;
+      margin: 0 auto;
+      padding: 24px 20px 72px;
+    }
+    .topbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 14px 0 28px;
+      border-bottom: 1px solid var(--border);
+      margin-bottom: 36px;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .brand {
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      text-decoration: none;
+      color: var(--text);
+      font-weight: 700;
+      font-size: 16px;
+      letter-spacing: -0.02em;
+    }
+    .brand-badge {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 11px;
+      font-weight: 600;
+      padding: 2px 8px;
+      border-radius: 999px;
+      background: #f4f4f5;
+      color: var(--muted);
+      border: 1px solid var(--border);
+    }
+    .cta-btn {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      background: var(--text);
+      color: #ffffff;
+      text-decoration: none;
+      padding: 9px 16px;
+      border-radius: 8px;
+      font-size: 13px;
+      font-weight: 600;
+      transition: opacity 0.15s ease;
+    }
+    .cta-btn:hover { opacity: 0.9; }
+    .pill-row {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      margin-bottom: 14px;
+    }
+    .pill {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      font-size: 11px;
+      font-weight: 600;
+      padding: 4px 10px;
+      border-radius: 999px;
+      background: var(--accent-soft);
+      color: var(--accent);
+      border: 1px solid #bae6fd;
+    }
+    .pill.emerald {
+      background: var(--emerald-soft);
+      color: var(--emerald);
+      border-color: #a7f3d0;
+    }
+    h1 {
+      font-size: clamp(26px, 4vw, 38px);
+      line-height: 1.18;
+      letter-spacing: -0.03em;
+      margin: 0 0 14px;
+    }
+    .lead {
+      font-size: 16px;
+      color: var(--muted);
+      max-width: 760px;
+      margin: 0 0 28px;
+    }
+    .grid-2 {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(290px, 1fr));
+      gap: 18px;
+      margin-bottom: 28px;
+    }
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 22px;
+      box-shadow: 0 1px 2px rgba(0,0,0,0.03);
+    }
+    .card h2, .card h3 {
+      margin-top: 0;
+      letter-spacing: -0.02em;
+    }
+    .code-box {
+      background: #09090b;
+      color: #f4f4f5;
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 12.5px;
+      padding: 16px;
+      border-radius: 10px;
+      overflow-x: auto;
+      line-height: 1.65;
+      margin: 14px 0;
+    }
+    .code-box .comment { color: #71717a; }
+    .code-box .cmd { color: #38bdf8; }
+    .code-box .ok { color: #34d399; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13.5px;
+      margin: 12px 0;
+    }
+    th, td {
+      text-align: left;
+      padding: 11px 12px;
+      border-bottom: 1px solid var(--border);
+    }
+    th {
+      font-size: 11.5px;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      color: var(--subtle);
+      background: #f4f4f5;
+    }
+    .calc-row {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      margin: 12px 0;
+      font-size: 13.5px;
+    }
+    .calc-output {
+      font-size: 24px;
+      font-weight: 700;
+      color: var(--emerald);
+      letter-spacing: -0.02em;
+    }
+    .cluster-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+      gap: 10px;
+      margin-top: 14px;
+    }
+    .cluster-link {
+      display: block;
+      padding: 11px 14px;
+      border-radius: 8px;
+      border: 1px solid var(--border);
+      background: var(--surface);
+      color: var(--text);
+      text-decoration: none;
+      font-size: 13px;
+      font-weight: 500;
+      transition: border-color 0.15s ease;
+    }
+    .cluster-link:hover {
+      border-color: var(--accent);
+      color: var(--accent);
+    }
+    .cluster-meta {
+      display: block;
+      font-size: 11px;
+      color: var(--subtle);
+      margin-top: 2px;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header class="topbar">
+      <a href="/" class="brand">
+        <svg width="24" height="24" viewBox="0 0 32 32" fill="none">
+          <rect width="32" height="32" rx="8" fill="#09090B"/>
+          <rect x="6" y="7" width="8" height="8" rx="2" stroke="#FFFFFF" stroke-width="2.2"/>
+          <rect x="6" y="17" width="8" height="8" rx="2" stroke="#FFFFFF" stroke-width="2.2" opacity="0.5"/>
+          <path d="M18 11H26M26 11L22.8 7.8M26 11L22.8 14.2" stroke="#38BDF8" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+          <circle cx="22" cy="21" r="2.8" fill="#FFFFFF"/>
+        </svg>
+        <span>${escapeHtml(cleanName)}</span>
+        <span class="brand-badge">git paid</span>
+      </a>
+      <div style="display:flex;gap:10px;align-items:center;">
+        <a href="/?tab=agent" class="brand-badge" style="text-decoration:none;padding:6px 11px;">Stateful MCP v2.1</a>
+        <a href="/?utm_source=pseo&utm_campaign=${encodeURIComponent(page.id || "guide")}" class="cta-btn">
+          <span>Run Live Domain Audit</span>
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="M5 12h14M12 5l7 7-7 7"/></svg>
+        </a>
+      </div>
+    </header>
+
+    <main>
+      <div class="pill-row">
+        <span class="pill">${escapeHtml(categoryLabel)}</span>
+        <span class="pill emerald">Intent: ${escapeHtml(page.intent || "High Intent")}</span>
+        <span class="pill">Search Volume: ${escapeHtml(page.volume || "1,400/mo")} (${escapeHtml(page.kd || "KD 11")})</span>
+      </div>
+
+      <h1>${escapeHtml(title)}</h1>
+      <p class="lead">
+        Shipping code with <code>git push</code> is only half the battle. Here is the deterministic engineering blueprint for <strong>${escapeHtml(page.keyword)}</strong>—combining 25 programmatic SEO routes, an autonomous <code>@postbuild.dev</code> verification inbox, and 85-directory dispatch via <code>npx git-paid</code>.
+      </p>
+
+      <div class="grid-2">
+        <section class="card">
+          <h3>1-Command CLI &amp; Stateful MCP Execution</h3>
+          <p style="font-size:13.5px;color:var(--muted);margin-top:4px;">
+            Run directly from your project root after deploying to Vercel, Railway, or Fly.io, or attach as an MCP server inside Claude Code, Cursor, or Gemini.
+          </p>
+          <div class="code-box">
+            <div><span class="comment"># 1. Audit your live URL &amp; write 25 pSEO routes + llms.txt</span></div>
+            <div><span class="cmd">$ npx git-paid fix https://${escapeHtml(domain)}</span></div>
+            <div style="margin-top:8px;"><span class="comment"># 2. Dispatch across 85 curated directories with OCC safety</span></div>
+            <div><span class="cmd">$ npx git-paid submit https://${escapeHtml(domain)} --limit 10</span></div>
+            <div style="margin-top:8px;"><span class="comment"># 3. Auto-verify inbound @postbuild.dev OTPs &amp; links</span></div>
+            <div><span class="ok">✔ Verified 100% of inbound directory confirmation links</span></div>
+          </div>
+          <a href="/?domain=${encodeURIComponent(domain)}" class="cta-btn" style="width:100%;justify-content:center;margin-top:10px;">
+            Launch Interactive Workspace for ${escapeHtml(domain)}
+          </a>
+        </section>
+
+        <section class="card">
+          <h3>Interactive Launch ROI &amp; Time Saved Estimator</h3>
+          <p style="font-size:13.5px;color:var(--muted);margin-top:4px;">
+            Adjust your monthly launch cadence to compare manual directory &amp; pSEO setup against <code>git paid</code> automation.
+          </p>
+          <div class="calc-row">
+            <label for="projectsRange"><strong>Projects / Features Launched per Year:</strong></label>
+            <span id="projectsVal" style="font-weight:700;">4 launches</span>
+          </div>
+          <input id="projectsRange" type="range" min="1" max="20" value="4" style="width:100%;accent-color:#09090b;" oninput="updateRoi(this.value)" />
+          <div class="calc-row" style="margin-top:16px;padding-top:12px;border-top:1px solid var(--border);">
+            <span>Engineering &amp; Founder Hours Saved:</span>
+            <span id="hoursSaved" class="calc-output">112 hrs</span>
+          </div>
+          <div class="calc-row">
+            <span>Indexed Programmatic SEO Landing Pages:</span>
+            <span id="pagesBuilt" style="font-weight:700;font-size:16px;">100 routes</span>
+          </div>
+          <div class="calc-row">
+            <span>High-DR Backlink Submissions Dispatched:</span>
+            <span id="dirsDispatched" style="font-weight:700;font-size:16px;">340 listings</span>
+          </div>
+        </section>
+      </div>
+
+      <section class="card" style="margin-bottom:28px;">
+        <h2>Manual Post-Build Workflow vs. ${escapeHtml(cleanName)} (<code>git paid</code>)</h2>
+        <table>
+          <thead>
+            <tr>
+              <th>Post-Build Capability</th>
+              <th>Manual Workflow / Spreadsheets</th>
+              <th>${escapeHtml(cleanName)} Autonomous Engine</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><strong>85-Directory Submission &amp; UTM Tagging</strong></td>
+              <td>14+ hours of repetitive copy-pasting &amp; form filling</td>
+              <td>Automated pre-filled &amp; API dispatch via <code>git paid submit</code></td>
+            </tr>
+            <tr>
+              <td><strong>Directory Verification Emails &amp; OTPs</strong></td>
+              <td>Clutters personal founder inbox with 85+ confirmation emails</td>
+              <td>Dedicated <code>*@postbuild.dev</code> Resend inbox + Agent Auto-Verifier</td>
+            </tr>
+            <tr>
+              <td><strong>Programmatic SEO Architecture</strong></td>
+              <td>Manual keyword research &amp; hand-coded static pages</td>
+              <td>25 pre-rendered routes + <code>sitemap.xml</code> + <code>llms.txt</code> in 1 command</td>
+            </tr>
+            <tr>
+              <td><strong>AI Agent MCP Context Efficiency</strong></td>
+              <td>Stateless JSON re-serialization (280 KB+ across 5 turns)</td>
+              <td>Stateful watermark deltas (<code>unchanged@vN</code> — <strong>-84% token overhead</strong>)</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+
+      <section class="card">
+        <h3>Explore All 25 Programmatic SEO Blueprints</h3>
+        <p style="font-size:13px;color:var(--muted);margin-top:0;">
+          Every route below is pre-indexed in <code>sitemap.xml</code> and <code>llms.txt</code> for Google, ChatGPT Search (<code>OAI-SearchBot</code>), Perplexity, and Claude.
+        </p>
+        <div class="cluster-grid">
+          ${relatedPages
+            .map((rp) => {
+              const meta = humanizeSlug(rp.path, cleanName);
+              return `<a class="cluster-link" href="${escapeHtml(rp.path)}">
+                <span>${escapeHtml(meta.title)}</span>
+                <span class="cluster-meta">${escapeHtml(rp.keyword)} • ${escapeHtml(rp.volume)}</span>
+              </a>`;
+            })
+            .join("\n          ")}
+        </div>
+      </section>
+    </main>
+  </div>
+  <script>
+    function updateRoi(val) {
+      var n = parseInt(val, 10) || 1;
+      document.getElementById('projectsVal').textContent = n + (n === 1 ? ' launch' : ' launches');
+      document.getElementById('hoursSaved').textContent = (n * 28) + ' hrs';
+      document.getElementById('pagesBuilt').textContent = (n * 25) + ' routes';
+      document.getElementById('dirsDispatched').textContent = (n * 85) + ' listings';
+    }
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Writes all 25 Programmatic SEO HTML files into targetBaseDir so cleanUrls (/use-cases/...) resolve with 200 OK.
+ */
+export function writePseoHtmlFiles(pseoPages = [], targetBaseDir, options = {}) {
+  const written = [];
+  for (const page of pseoPages) {
+    const cleanRel = String(page.path || "").replace(/^\/+/, "");
+    if (!cleanRel) continue;
+    const outFile = path.join(targetBaseDir, `${cleanRel}.html`);
+    fs.mkdirSync(path.dirname(outFile), { recursive: true });
+    const html = renderSinglePseoPage(page, pseoPages, options);
+    fs.writeFileSync(outFile, html, "utf8");
+    written.push(outFile);
+  }
+  return written;
+}