@xyleapp/cli 0.4.3 → 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.3");
+  .version("0.5.0");
 
 registerCommands(program);
 

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@xyleapp/cli",
-  "version": "0.4.3",
+  "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")