@seoagent-official/seoagent 1.11.0 → 1.13.0

package/README.md

@@ -1,6 +1,39 @@
-# SEOAgent
-
-**A persistent AI SEO agent for Claude Code.** Audits your site, builds keyword strategy, plans content, and writes optimized articles — all persisted across sessions in `.seoagent/`.
+<p align="center">
+  <a href="https://seoagent.com?ref=npm-readme-hero">
+    <img src="https://unpkg.com/@seoagent-official/seoagent/assets/hero.svg" alt="SEOAgent — the persistent AI SEO agent for Claude Code" width="900" />
+  </a>
+</p>
+
+<h1 align="center">SEOAgent</h1>
+
+<p align="center">
+  <strong>The persistent AI SEO agent for <a href="https://www.anthropic.com/claude-code">Claude Code</a>.</strong><br/>
+  Audits • Keyword strategy • Content briefs • Optimized articles — all persisted in <code>.seoagent/</code>.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@seoagent-official/seoagent"><img alt="npm version" src="https://img.shields.io/npm/v/@seoagent-official/seoagent?color=cb3837&label=npm&logo=npm&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@seoagent-official/seoagent"><img alt="downloads" src="https://img.shields.io/npm/dm/@seoagent-official/seoagent?color=22c55e&label=downloads"></a>
+  <a href="https://github.com/Baxter-Inc/seoagent-npm/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Baxter-Inc/seoagent-npm/publish-npm.yml?branch=main&label=CI&logo=github"></a>
+  <a href="https://github.com/Baxter-Inc/seoagent-npm/blob/main/LICENSE"><img alt="license MIT" src="https://img.shields.io/npm/l/@seoagent-official/seoagent?color=3b82f6&label=license"></a>
+  <a href="https://seoagent.com?ref=npm-readme-badge"><img alt="SEOAgent Cloud" src="https://img.shields.io/badge/cloud-seoagent.com-7c3aed?logo=cloudflare&logoColor=white"></a>
+</p>
+
+<p align="center">
+  <img alt="Claude Code" src="https://img.shields.io/badge/CLAUDE%20CODE-5b54f4?style=flat-square&logo=anthropic&logoColor=white">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TYPESCRIPT-3178c6?style=flat-square&logo=typescript&logoColor=white">
+  <img alt="Node 18+" src="https://img.shields.io/badge/NODE%20%E2%89%A5%2018-339933?style=flat-square&logo=node.js&logoColor=white">
+  <img alt="SEO Autopilot" src="https://img.shields.io/badge/SEO-AUTOPILOT-f97316?style=flat-square">
+  <img alt="Images via OpenAI · fal.ai · Replicate" src="https://img.shields.io/badge/IMAGES-OpenAI%20%C2%B7%20fal.ai%20%C2%B7%20Replicate-ec4899?style=flat-square">
+</p>
+
+<p align="center">
+  Built and maintained by <a href="https://seoagent.com?ref=npm-readme-builtby"><strong>SEOAgent.com</strong></a> ·
+  <a href="https://seoagent.com/pricing?ref=npm-readme">Cloud pricing</a> ·
+  <a href="https://seoagent.com?ref=npm-readme-docs">Docs &amp; dashboard</a>
+</p>
+
+---
 
 > **This package is a scaffolder, not a runtime dependency.** Both forms below do the same thing — scaffold `.seoagent/` + the Claude Code skill in your repo. You don't need to keep it in `package.json` after init runs.
 

package/assets/hero.svg

@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 360" width="1200" height="360" role="img" aria-label="SEOAgent — The persistent AI SEO agent for Claude Code">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#0d0d1f"/>
+      <stop offset="55%" stop-color="#1a1147"/>
+      <stop offset="100%" stop-color="#2d1b69"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#a78bfa"/>
+      <stop offset="100%" stop-color="#7c3aed"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.85" cy="0.15" r="0.7">
+      <stop offset="0%" stop-color="#7c3aed" stop-opacity="0.55"/>
+      <stop offset="60%" stop-color="#7c3aed" stop-opacity="0.08"/>
+      <stop offset="100%" stop-color="#7c3aed" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="soft" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="0.6"/>
+    </filter>
+  </defs>
+
+  <rect width="1200" height="360" rx="20" ry="20" fill="url(#bg)"/>
+  <rect width="1200" height="360" rx="20" ry="20" fill="url(#glow)"/>
+
+  <g opacity="0.18" stroke="#a78bfa" stroke-width="1" fill="none">
+    <path d="M0 280 C 220 240, 420 320, 640 270 S 1020 220, 1200 260"/>
+    <path d="M0 305 C 220 270, 420 345, 640 295 S 1020 250, 1200 285"/>
+    <path d="M0 330 C 220 300, 420 365, 640 320 S 1020 280, 1200 310"/>
+  </g>
+
+  <g transform="translate(70 120)">
+    <circle cx="32" cy="32" r="32" fill="url(#accent)"/>
+    <text x="32" y="44" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif" font-size="32" font-weight="800" fill="#0d0d1f">S</text>
+  </g>
+
+  <text x="160" y="170" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif" font-size="78" font-weight="800" letter-spacing="-2" fill="#ffffff">
+    SEO<tspan fill="url(#accent)">Agent</tspan>
+  </text>
+
+  <text x="160" y="215" font-family="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif" font-size="22" font-weight="500" fill="#cbd5f5" filter="url(#soft)">
+    The persistent AI SEO agent for Claude Code · Manifest-ready autopilot for audits, briefs &amp; articles
+  </text>
+
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="14" font-weight="600">
+    <g transform="translate(160 255)">
+      <rect width="146" height="32" rx="16" fill="#ffffff" fill-opacity="0.08" stroke="#a78bfa" stroke-opacity="0.35"/>
+      <text x="73" y="21" text-anchor="middle" fill="#e9d5ff">persistent .seoagent/</text>
+    </g>
+    <g transform="translate(316 255)">
+      <rect width="138" height="32" rx="16" fill="#ffffff" fill-opacity="0.08" stroke="#a78bfa" stroke-opacity="0.35"/>
+      <text x="69" y="21" text-anchor="middle" fill="#e9d5ff">hub &amp; spoke clusters</text>
+    </g>
+    <g transform="translate(464 255)">
+      <rect width="120" height="32" rx="16" fill="#ffffff" fill-opacity="0.08" stroke="#a78bfa" stroke-opacity="0.35"/>
+      <text x="60" y="21" text-anchor="middle" fill="#e9d5ff">JSON-LD ready</text>
+    </g>
+    <g transform="translate(594 255)">
+      <rect width="120" height="32" rx="16" fill="#ffffff" fill-opacity="0.08" stroke="#a78bfa" stroke-opacity="0.35"/>
+      <text x="60" y="21" text-anchor="middle" fill="#e9d5ff">image autopilot</text>
+    </g>
+    <g transform="translate(724 255)">
+      <rect width="124" height="32" rx="16" fill="#ffffff" fill-opacity="0.08" stroke="#a78bfa" stroke-opacity="0.35"/>
+      <text x="62" y="21" text-anchor="middle" fill="#e9d5ff">cloud sync hook</text>
+    </g>
+  </g>
+
+  <g transform="translate(940 70)" opacity="0.95">
+    <rect width="190" height="56" rx="10" fill="#ffffff" fill-opacity="0.06" stroke="#a78bfa" stroke-opacity="0.4"/>
+    <text x="20" y="24" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="11" fill="#a78bfa">$</text>
+    <text x="36" y="24" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="11" fill="#e9d5ff">npx -y @seoagent-</text>
+    <text x="36" y="42" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="11" fill="#e9d5ff">official/seoagent init</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Scaffolder for Claude Code's SEOAgent skill. Run once: `npx -y @seoagent-official/seoagent init`. Sets up .seoagent/ for persistent audits, keyword strategy, content planning, and optimized writing. Not a runtime dependency.",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   "files": [
     "index.js",
     "skills",
-    "postinstall-hint.cjs"
+    "assets",
+    "postinstall-hint.cjs",
+    "postinstall-lib.cjs"
   ],
   "dependencies": {
     "@clack/prompts": "^0.9.0",

package/postinstall-hint.cjs

@@ -19,6 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { isDirectInstall } = require('./postinstall-lib.cjs');
 
 // -----------------------------------------------------------------------------
 // Guards — skip auto-init when it would be wrong or annoying.
@@ -53,8 +54,20 @@ if (!projectRoot || !fs.existsSync(projectRoot)) {
 // Don't auto-init when the package is being installed inside another
 // package's `node_modules` (a transitive dep). INIT_CWD would be the
 // transitive consumer's project root, not ours — we'd scaffold their repo.
-// Detect: INIT_CWD's package.json doesn't list us in its (dev)dependencies.
-if (!projectDeclaresUs(projectRoot)) {
+//
+// Detecting "transitive" reliably is harder than it looks: when a user runs
+// `npm install @seoagent-official/seoagent` in a fresh project, npm 7+ runs
+// THIS postinstall BEFORE writing the new dep to INIT_CWD/package.json. So
+// "is our package name in INIT_CWD/package.json" is false-negative-prone and
+// silently kills the captive install moment on every fresh install — which
+// is exactly the case we most need it to fire on.
+//
+// Instead: look at sibling node_modules entries. If ANY of them declares us
+// as a dependency, we're being dragged in transitively → bail. Otherwise
+// we're a direct install (or no one else needs us yet) → proceed.
+// We still consult package.json as a positive signal (e.g. for repeat installs
+// where the dep is already saved), since it strengthens the "direct" conclusion.
+if (!isDirectInstall(projectRoot)) {
   // Most likely transitive — bail silently.
   process.exit(0);
 }
@@ -94,25 +107,11 @@ if (result.status === 0) {
 }
 
 // -----------------------------------------------------------------------------
-// Helpers
+// Helpers — direct-install detection lives in ./postinstall-lib.cjs so it can
+// be unit-tested without firing the side effects above. The print functions
+// stay inline because they don't have meaningful behavior to test.
 // -----------------------------------------------------------------------------
 
-function projectDeclaresUs(root) {
-  try {
-    const pkgPath = path.join(root, 'package.json');
-    if (!fs.existsSync(pkgPath)) {
-      // No package.json — user ran `npm install <pkg>` in an empty dir or
-      // outside a project. That's unusual but valid for scaffolding.
-      return true;
-    }
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-    return '@seoagent-official/seoagent' in all;
-  } catch {
-    return true; // On error, fail open — better to scaffold than not.
-  }
-}
-
 function printPreInitBanner() {
   process.stdout.write(
     '\n' +

package/postinstall-lib.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+// =============================================================================
+// postinstall-lib — pure helpers used by postinstall-hint.cjs
+//
+// Lives in its own file (instead of inline in postinstall-hint.cjs) for two
+// reasons:
+//   1. Unit-testable. The main script has top-level side effects
+//      (process.exit, spawnSync) that fire on require — splitting the pure
+//      logic out means vitest can require THIS file safely.
+//   2. The regression we're guarding against is subtle: npm 7+ writes the
+//      newly-installed package to the parent's package.json AFTER running
+//      the package's postinstall script. So the old "is our name in
+//      INIT_CWD/package.json" check returned false on every fresh install,
+//      silently killing the captive moment we built the package around.
+//      Tests for THIS file pin the corrected behavior in place.
+// =============================================================================
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_NAME = '@seoagent-official/seoagent';
+
+/**
+ * Decide whether this postinstall is firing for a DIRECT install (user/agent
+ * explicitly added us) vs a TRANSITIVE install (we're a dep of someone else's
+ * dep). Returns true ⇒ scaffold; false ⇒ silent bail.
+ *
+ * Strategy is two-step because both signals alone are unreliable:
+ *   1. POSITIVE — INIT_CWD/package.json already lists us. Confirms direct
+ *      (but is FALSE on the most common case: first-time `npm install <us>`,
+ *      because npm 7+ writes package.json AFTER lifecycle scripts).
+ *   2. NEGATIVE — Look at every sibling under INIT_CWD/node_modules and check
+ *      if any of THEIR package.json lists us as a dep. If yes → transitive.
+ *      If no → direct (or top-level install with no other consumer yet).
+ *
+ * If both are inconclusive (e.g. no package.json at all because the user ran
+ * `npm install <us>` in an empty dir), default to "direct" — scaffolding is
+ * the whole point of the package and the existing `.seoagent/project.md`
+ * idempotency guard prevents double-scaffolding on subsequent runs.
+ */
+function isDirectInstall(root) {
+  if (!root) return true; // No INIT_CWD: nothing else we can check; scaffold.
+  if (declaredInProjectJson(root)) return true;
+  if (anySiblingDependsOnUs(root)) return false;
+  return true;
+}
+
+function declaredInProjectJson(root) {
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    if (!fs.existsSync(pkgPath)) return false;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const all = mergeAllDepKinds(pkg);
+    return PKG_NAME in all;
+  } catch {
+    return false;
+  }
+}
+
+function anySiblingDependsOnUs(root) {
+  try {
+    const nm = path.join(root, 'node_modules');
+    if (!fs.existsSync(nm)) return false;
+    for (const entry of fs.readdirSync(nm, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      // Scoped packages: recurse one level.
+      if (entry.name.startsWith('@')) {
+        const scopeDir = path.join(nm, entry.name);
+        let scoped;
+        try {
+          scoped = fs.readdirSync(scopeDir, { withFileTypes: true });
+        } catch {
+          continue;
+        }
+        for (const inner of scoped) {
+          if (!inner.isDirectory()) continue;
+          // Skip ourselves.
+          if (entry.name === '@seoagent-official' && inner.name === 'seoagent') continue;
+          if (pkgListsUs(path.join(scopeDir, inner.name, 'package.json'))) return true;
+        }
+        continue;
+      }
+      if (pkgListsUs(path.join(nm, entry.name, 'package.json'))) return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function pkgListsUs(pkgJsonPath) {
+  try {
+    if (!fs.existsSync(pkgJsonPath)) return false;
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    return PKG_NAME in mergeAllDepKinds(pkg);
+  } catch {
+    return false;
+  }
+}
+
+function mergeAllDepKinds(pkg) {
+  return {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+    ...(pkg.optionalDependencies || {}),
+    ...(pkg.peerDependencies || {}),
+  };
+}
+
+module.exports = {
+  PKG_NAME,
+  isDirectInstall,
+  declaredInProjectJson,
+  anySiblingDependsOnUs,
+  pkgListsUs,
+};