@xyleapp/cli 0.4.2 → 0.5.0

package/README.md

@@ -40,22 +40,35 @@ xyle sync --site https://example.com
 
 ## Commands
 
-| Command       | Description                              |
-| ------------- | ---------------------------------------- |
-| `status`      | Check if the SEO API is reachable        |
-| `queries`     | List top search queries for a site       |
-| `competitors` | Show competitor pages for a query        |
-| `gaps`        | Show content gaps for a page             |
-| `analyze`     | Analyze page content against competitors |
-| `rewrite`     | Get AI rewrite suggestions               |
-| `crawl`       | Crawl a URL and extract SEO metadata     |
-| `sync`        | Sync Google Search Console data          |
-| `login`       | Authenticate with Google OAuth           |
-| `logout`      | Remove stored credentials                |
-| `whoami`      | Show current authentication status       |
+| Command       | Description                                    |
+| ------------- | ---------------------------------------------- |
+| `status`      | Check if the SEO API is reachable              |
+| `setup`       | Check backend requirements and Playwright info |
+| `queries`     | List top search queries for a site             |
+| `competitors` | Show competitor pages for a query              |
+| `gaps`        | Show content gaps for a page                   |
+| `analyze`     | Analyze page content against competitors       |
+| `rewrite`     | Get AI rewrite suggestions                     |
+| `crawl`       | Crawl a URL and extract SEO metadata           |
+| `sync`        | Sync Google Search Console data                |
+| `login`       | Authenticate with Google OAuth                 |
+| `logout`      | Remove stored credentials                      |
+| `whoami`      | Show current authentication status             |
+| `seed`        | Add xyle agent instructions to your project    |
 
 All data commands accept `--json` for machine-readable output.
 
+## Playwright (Server-Side)
+
+The Xyle API uses Playwright to crawl JS-rendered pages (SPAs). If you self-host the API backend, install Chromium once:
+
+```bash
+pip install playwright
+playwright install chromium
+```
+
+Docker deployments handle this automatically. Skip this if using the hosted API.
+
 ## Configuration
 
 | Environment Variable | Default                  | Description          |

package/bin/xyle.mjs

@@ -8,7 +8,7 @@ const program = new Command();
 program
   .name("xyle")
   .description("SEO Intelligence Engine CLI")
-  .version("0.4.2");
+  .version("0.5.0");
 
 registerCommands(program);
 

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@xyleapp/cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "CLI for the Xyle SEO Intelligence Engine",
   "type": "module",
   "bin": {
     "xyle": "bin/xyle.mjs"
   },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
   "engines": {
     "node": ">=18"
   },
   "files": [
     "bin/",
     "src/",
+    "scripts/",
     "README.md"
   ],
   "keywords": [

package/scripts/postinstall.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install message shown after `npm install -g @xyleapp/cli`.
+ * Tells backend operators about Playwright/Chromium for JS-rendered crawling.
+ */
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+console.log(`
+${GREEN}xyle CLI installed successfully!${RESET}
+
+${CYAN}Quick start:${RESET}
+  xyle status          ${DIM}Check API connectivity${RESET}
+  xyle login           ${DIM}Authenticate with Google${RESET}
+  xyle crawl --url <u> ${DIM}Crawl a page for SEO data${RESET}
+
+${YELLOW}Server-side setup (for self-hosted API):${RESET}
+  The Xyle API uses Playwright to crawl JS-rendered pages (SPAs).
+  If you're running the API backend locally, install Chromium:
+
+    pip install playwright
+    playwright install chromium
+
+  ${DIM}Docker deployments handle this automatically.${RESET}
+  ${DIM}Skip this if you're using the hosted API at https://api.xyle.app${RESET}
+`);

package/src/commands.mjs

@@ -194,6 +194,15 @@ export function registerCommands(program) {
               console.log(`  ${h}`);
             }
           }
+          const wc = data.word_count || 0;
+          if (wc > 0 && wc < 50) {
+            console.log(
+              `\n\x1b[33mLow word count — this may be a JS-rendered page.\x1b[0m`
+            );
+            console.log(
+              `\x1b[2mEnsure Playwright + Chromium are installed on the API server: xyle setup\x1b[0m`
+            );
+          }
         }
       } catch (e) {
         handleError(e);
@@ -308,6 +317,42 @@ export function registerCommands(program) {
       }
     });
 
+  // --- setup ---
+  program
+    .command("setup")
+    .description("Check backend requirements and show setup instructions")
+    .action(async () => {
+      console.log("\x1b[36mXyle Backend Setup\x1b[0m\n");
+
+      // Check API connectivity
+      try {
+        const data = await checkHealth();
+        console.log(`\x1b[32m  API:        reachable (${SEO_BASE})\x1b[0m`);
+      } catch {
+        console.log(`\x1b[31m  API:        unreachable (${SEO_BASE})\x1b[0m`);
+        console.log(`\x1b[2m              Set SEO_BASE env var or start the API server.\x1b[0m`);
+      }
+
+      // Auth check
+      const creds = getCredentials();
+      if (creds && creds.authenticated) {
+        console.log(`\x1b[32m  Auth:       logged in${creds.email ? ` (${creds.email})` : ""}\x1b[0m`);
+      } else {
+        console.log(`\x1b[33m  Auth:       not logged in\x1b[0m`);
+        console.log(`\x1b[2m              Run: xyle login\x1b[0m`);
+      }
+
+      console.log(`\n\x1b[36mPlaywright Setup (server-side, for JS-rendered crawling)\x1b[0m\n`);
+      console.log(`  The API uses Playwright to crawl JavaScript-rendered pages`);
+      console.log(`  (SPAs like React, Next.js, Angular). Without it, crawling`);
+      console.log(`  falls back to static HTML only.\n`);
+      console.log(`  \x1b[33mInstall (one-time, on the machine running the API):\x1b[0m\n`);
+      console.log(`    pip install playwright`);
+      console.log(`    playwright install chromium\n`);
+      console.log(`  \x1b[2mDocker deployments handle this automatically.\x1b[0m`);
+      console.log(`  \x1b[2mSkip this if using the hosted API at https://api.xyle.app\x1b[0m\n`);
+    });
+
   // --- seed ---
   program
     .command("seed")
@@ -350,7 +395,7 @@ export function registerCommands(program) {
         toolNames = selected;
       }
 
-      const { created, skipped } = seedInstructions(opts.dir, toolNames);
+      const { created, appended, skipped } = seedInstructions(opts.dir, toolNames);
 
       if (created.length) {
         console.log("\x1b[32mCreated:\x1b[0m");
@@ -358,16 +403,22 @@ export function registerCommands(program) {
           console.log(`  + ${f}`);
         }
       }
+      if (appended.length) {
+        console.log("\x1b[32mAppended:\x1b[0m");
+        for (const f of appended) {
+          console.log(`  ~ ${f}`);
+        }
+      }
       if (skipped.length) {
         console.log("\x1b[33mSkipped:\x1b[0m");
         for (const f of skipped) {
           console.log(`  - ${f}`);
         }
       }
-      if (!created.length && !skipped.length) {
+      if (!created.length && !appended.length && !skipped.length) {
         console.log("Nothing to do.");
       }
-      if (created.length) {
+      if (created.length || appended.length) {
         console.log(
           `\n\x1b[32mDone!\x1b[0m Your AI coding tools will now know about xyle.`
         );

package/src/seed.mjs

@@ -3,7 +3,7 @@
  * Each tool reads from a specific file path to learn about xyle.
  */
 
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { writeFileSync, readFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 
 const INSTRUCTIONS = `# Xyle — SEO Intelligence Engine
@@ -80,7 +80,7 @@ npx @xyleapp/cli sync --site <url> [--json]
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| \`SEO_BASE\` | \`http://localhost:8765\` | API base URL |
+| \`SEO_BASE\` | \`https://api.xyle.app\` | API base URL |
 | \`AGENT_API_KEY\` | — | Fallback API key (when not using Google OAuth) |
 
 ## Workflows
@@ -185,24 +185,33 @@ export function seedInstructions(targetDir, toolNames) {
   const tools = toolNames
     ? Object.fromEntries(toolNames.map((n) => [n, TOOLS[n]]))
     : TOOLS;
+  const MARKER = "# Xyle — SEO Intelligence Engine";
   const created = [];
+  const appended = [];
   const skipped = [];
 
   for (const [name, tool] of Object.entries(tools)) {
     const filePath = join(targetDir, tool.path);
-    if (existsSync(filePath)) {
-      skipped.push(`${tool.label} (${tool.path}) — already exists`);
-      continue;
-    }
     const dir = dirname(filePath);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
-    writeFileSync(filePath, INSTRUCTIONS, "utf-8");
-    created.push(`${tool.label} (${tool.path})`);
+
+    if (existsSync(filePath)) {
+      const existing = readFileSync(filePath, "utf-8");
+      if (existing.includes(MARKER)) {
+        skipped.push(`${tool.label} (${tool.path}) — xyle instructions already present`);
+        continue;
+      }
+      appendFileSync(filePath, "\n\n" + INSTRUCTIONS, "utf-8");
+      appended.push(`${tool.label} (${tool.path})`);
+    } else {
+      writeFileSync(filePath, INSTRUCTIONS, "utf-8");
+      created.push(`${tool.label} (${tool.path})`);
+    }
   }
 
-  return { created, skipped };
+  return { created, appended, skipped };
 }
 
 /**