@xyleapp/cli 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# xyle
+
+CLI for the [Xyle](https://xyle.app) SEO Intelligence Engine.
+
+## Install
+
+```bash
+npm install -g xyle
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Check API connectivity
+xyle status
+
+# Authenticate with Google (opens browser)
+xyle login
+
+# List top queries for your site
+xyle queries --site example.com
+
+# Analyze competitor pages
+xyle competitors --query "best seo tools"
+
+# Find content gaps
+xyle gaps --page https://example.com/blog/seo-guide
+
+# Get AI rewrite suggestions
+xyle rewrite --url https://example.com/blog/seo-guide --type title
+
+# Crawl a page
+xyle crawl --url https://example.com/blog/seo-guide
+
+# Sync Search Console data
+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       |
+
+All data commands accept `--json` for machine-readable output.
+
+## Configuration
+
+| Environment Variable | Default                  | Description          |
+| -------------------- | ------------------------ | -------------------- |
+| `SEO_BASE`           | `http://localhost:8765`  | API base URL         |
+| `AGENT_API_KEY`      | `local-agent-secret-key` | Fallback API key     |
+
+Credentials are stored in `~/.config/xyle/credentials.json` (shared with the Python CLI).

package/bin/xyle.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { registerCommands } from "../src/commands.mjs";
+
+const program = new Command();
+
+program
+  .name("xyle")
+  .description("SEO Intelligence Engine CLI")
+  .version("0.1.0");
+
+registerCommands(program);
+
+program.parse();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xyleapp/cli",
+  "version": "0.1.0",
+  "description": "CLI for the Xyle SEO Intelligence Engine",
+  "type": "module",
+  "bin": {
+    "xyle": "bin/xyle.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "seo",
+    "cli",
+    "search-console",
+    "xyle"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.0.0",
+    "open": "^10.0.0"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,110 @@
+/**
+ * HTTP client for the Xyle SEO API.
+ * Uses native fetch (Node 18+). Zero external dependencies.
+ */
+
+import { getApiKey } from "./auth.mjs";
+
+const SEO_BASE = process.env.SEO_BASE || "http://localhost:8765";
+
+/**
+ * Build auth headers, preferring personal API key over shared env key.
+ */
+function getHeaders() {
+  let key;
+  try {
+    key = getApiKey();
+  } catch {
+    key = null;
+  }
+  if (!key) {
+    key = process.env.AGENT_API_KEY || "local-agent-secret-key";
+  }
+  return {
+    "X-Agent-Key": key,
+    "Content-Type": "application/json",
+  };
+}
+
+/**
+ * Make an API request. Throws on non-OK responses with a structured error.
+ */
+async function request(method, path, { params, body, timeout = 30000, auth = true } = {}) {
+  let url = `${SEO_BASE}${path}`;
+  if (params) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v != null) qs.set(k, String(v));
+    }
+    const qsStr = qs.toString();
+    if (qsStr) url += `?${qsStr}`;
+  }
+
+  const headers = auth ? getHeaders() : { "Content-Type": "application/json" };
+  const opts = { method, headers, signal: AbortSignal.timeout(timeout) };
+  if (body) opts.body = JSON.stringify(body);
+
+  const resp = await fetch(url, opts);
+  if (!resp.ok) {
+    let detail;
+    try {
+      const json = await resp.json();
+      detail = json.detail || resp.statusText;
+    } catch {
+      detail = resp.statusText;
+    }
+    const err = new Error(`Error ${resp.status}: ${detail}`);
+    err.status = resp.status;
+    throw err;
+  }
+  return resp.json();
+}
+
+export function checkHealth() {
+  return request("GET", "/health", { auth: false, timeout: 10000 });
+}
+
+export function getTopQueries(site, limit = 20) {
+  return request("GET", "/queries", { params: { site, limit } });
+}
+
+export function getCompetitors(query) {
+  return request("GET", "/competitors", { params: { query } });
+}
+
+export function getPageGaps(page, query) {
+  return request("GET", "/gaps", { params: { page, query } });
+}
+
+export function analyzePage(url, content, query) {
+  const body = { url, content };
+  if (query) body.query = query;
+  return request("POST", "/analyze", { body, timeout: 60000 });
+}
+
+export function getRewriteSuggestions(url, type = "title", query) {
+  const body = { url, type, context: {} };
+  if (query) body.query = query;
+  return request("POST", "/rewrite", { body, timeout: 60000 });
+}
+
+export function crawlPage(url) {
+  return request("POST", "/crawl", { body: { url } });
+}
+
+export function syncGsc(site) {
+  return request("POST", "/admin/sync", { params: { site } });
+}
+
+/**
+ * Fetch the OAuth auth URL from the API.
+ */
+export function getAuthUrl(cliPort) {
+  return request("GET", "/admin/gsc/auth-url", {
+    params: { cli_port: cliPort },
+    auth: false,
+    timeout: 10000,
+  });
+}
+
+export { SEO_BASE };

package/src/auth.mjs

@@ -0,0 +1,164 @@
+/**
+ * OAuth flow + credential storage for the xyle CLI.
+ * Credentials file (~/.config/xyle/credentials.json) is shared with the Python CLI.
+ */
+
+import { createServer } from "node:http";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const CREDENTIALS_DIR = join(homedir(), ".config", "xyle");
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+const CALLBACK_PORT = 9876;
+
+/**
+ * Load stored credentials from disk.
+ * @returns {object|null}
+ */
+export function getCredentials() {
+  try {
+    const raw = readFileSync(CREDENTIALS_FILE, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the stored personal API key, or null.
+ * @returns {string|null}
+ */
+export function getApiKey() {
+  const creds = getCredentials();
+  if (creds && creds.authenticated) return creds.api_key || null;
+  return null;
+}
+
+/**
+ * Persist credentials to ~/.config/xyle/credentials.json (mode 600).
+ * @param {object} creds
+ */
+export function saveCredentials(creds) {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), "utf-8");
+  chmodSync(CREDENTIALS_FILE, 0o600);
+}
+
+/**
+ * Remove stored credentials.
+ */
+export function clearCredentials() {
+  try {
+    unlinkSync(CREDENTIALS_FILE);
+  } catch {
+    // already gone
+  }
+}
+
+/**
+ * Browser-based OAuth login flow.
+ *
+ * 1. CLI starts local HTTP server on CALLBACK_PORT
+ * 2. CLI asks API for the Google OAuth URL (with cli_port in state)
+ * 3. Browser -> Google consent -> API callback -> redirects to CLI server
+ * 4. CLI server receives status, stores credentials
+ *
+ * @param {string} seoBase - API base URL
+ * @returns {Promise<object|null>}
+ */
+export async function runLoginFlow(seoBase) {
+  // Dynamic import so the rest of the module works without `open` at load time
+  const { default: openBrowser } = await import("open");
+  const { getAuthUrl } = await import("./api.mjs");
+
+  // Get auth URL from API
+  let authUrl;
+  try {
+    const data = await getAuthUrl(CALLBACK_PORT);
+    authUrl = data.auth_url;
+  } catch (e) {
+    if (e.cause && e.cause.code === "ECONNREFUSED") {
+      console.error("\x1b[31mAPI is not running. Start it first.\x1b[0m");
+    } else {
+      console.error(`\x1b[31mFailed to get auth URL from API: ${e.message}\x1b[0m`);
+    }
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${CALLBACK_PORT}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+
+      const status = url.searchParams.get("status");
+      const message = url.searchParams.get("message") || "";
+
+      if (status === "authenticated") {
+        const creds = {
+          authenticated: true,
+          seo_base: seoBase,
+          message,
+        };
+        const apiKey = url.searchParams.get("api_key");
+        const email = url.searchParams.get("email");
+        const name = url.searchParams.get("name");
+        if (apiKey) creds.api_key = apiKey;
+        if (email) creds.email = email;
+        if (name) creds.name = name;
+
+        saveCredentials(creds);
+
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body style='font-family:system-ui;text-align:center;padding:60px'>" +
+            "<h2 style='color:#22c55e'>Login successful!</h2>" +
+            "<p>You can close this tab and return to the terminal.</p>" +
+            "</body></html>"
+        );
+
+        settled = true;
+        server.close();
+        resolve(creds);
+      } else if (status === "error") {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body style='font-family:system-ui;text-align:center;padding:60px'>" +
+            "<h2 style='color:#ef4444'>Login failed</h2>" +
+            `<p>${message}</p>` +
+            "</body></html>"
+        );
+
+        settled = true;
+        server.close();
+        console.error(`\x1b[31mLogin failed: ${message}\x1b[0m`);
+        resolve(null);
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.listen(CALLBACK_PORT, "localhost", () => {
+      console.log("Opening browser for Google login...");
+      console.log(`If the browser doesn't open, visit:\n${authUrl}\n`);
+      openBrowser(authUrl).catch(() => {});
+    });
+
+    // 120-second timeout
+    setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        server.close();
+        console.error("\x1b[31mLogin timed out (2 minutes). Try again.\x1b[0m");
+        resolve(null);
+      }
+    }, 120_000);
+  });
+}

package/src/commands.mjs

@@ -0,0 +1,287 @@
+/**
+ * All 11 CLI commands for the xyle CLI.
+ * Mirrors the Python CLI 1:1.
+ */
+
+import { createRequire } from "node:module";
+import { printJson, printTable } from "./formatting.mjs";
+import {
+  checkHealth,
+  getTopQueries,
+  getCompetitors,
+  getPageGaps,
+  analyzePage,
+  getRewriteSuggestions,
+  crawlPage,
+  syncGsc,
+  SEO_BASE,
+} from "./api.mjs";
+import { getCredentials, clearCredentials, runLoginFlow } from "./auth.mjs";
+
+/**
+ * Print error message in red to stderr and exit.
+ */
+function handleError(e) {
+  const msg = e.message || String(e);
+  process.stderr.write(`\x1b[31m${msg}\x1b[0m\n`);
+  process.exit(1);
+}
+
+/**
+ * Register all commands on a Commander program instance.
+ * @param {import('commander').Command} program
+ */
+export function registerCommands(program) {
+  // --- status ---
+  program
+    .command("status")
+    .description("Check if the SEO API is reachable")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await checkHealth();
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const s = data.status || "unknown";
+          const color = s === "ok" ? "\x1b[32m" : "\x1b[31m";
+          console.log(`${color}API status: ${s}\x1b[0m`);
+        }
+      } catch (e) {
+        if (e.cause && e.cause.code === "ECONNREFUSED") {
+          process.stderr.write("\x1b[31mAPI unreachable\x1b[0m\n");
+          process.exit(1);
+        }
+        handleError(e);
+      }
+    });
+
+  // --- queries ---
+  program
+    .command("queries")
+    .description("List top search queries for a site")
+    .requiredOption("--site <domain>", "Site domain or URL")
+    .option("--limit <n>", "Max queries to return", "20")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await getTopQueries(opts.site, parseInt(opts.limit, 10));
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(printTable(data, ["query", "impressions", "clicks", "ctr", "position"]));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- competitors ---
+  program
+    .command("competitors")
+    .description("Show competitor pages for a query")
+    .requiredOption("--query <query>", "Search query to analyze")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await getCompetitors(opts.query);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(printTable(data, ["position", "url", "title", "word_count"]));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- gaps ---
+  program
+    .command("gaps")
+    .description("Show content gaps for a page")
+    .requiredOption("--page <url>", "Page URL to check gaps for")
+    .option("--query <query>", "Optional query to filter")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await getPageGaps(opts.page, opts.query);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(
+            printTable(data, ["query", "missing_topics", "ctr_issue", "position_bucket"])
+          );
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- analyze ---
+  program
+    .command("analyze")
+    .description("Analyze page content against competitors")
+    .requiredOption("--url <url>", "Page URL to analyze")
+    .requiredOption("--content <text>", "Page content text")
+    .option("--query <query>", "Target query for analysis")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await analyzePage(opts.url, opts.content, opts.query);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const score = data.score || 0;
+          const color = score >= 0.7 ? "\x1b[32m" : "\x1b[33m";
+          console.log(`${color}Score: ${Math.round(score * 100)}%\x1b[0m`);
+          console.log(`Summary: ${data.summary || ""}`);
+          const missing = data.missing_topics || [];
+          if (missing.length) {
+            console.log(`Missing topics: ${missing.join(", ")}`);
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- rewrite ---
+  program
+    .command("rewrite")
+    .description("Get AI rewrite suggestions for a page element")
+    .requiredOption("--url <url>", "Page URL to rewrite")
+    .option("--type <element>", "Element to rewrite: title, meta, heading, section", "title")
+    .option("--query <query>", "Target query for rewrite")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await getRewriteSuggestions(opts.url, opts.type, opts.query);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          if (data.original) {
+            console.log(`\x1b[31mOriginal:  ${data.original}\x1b[0m`);
+          }
+          console.log(`\x1b[32mSuggested: ${data.suggested}\x1b[0m`);
+          console.log(`Reasoning: ${data.reasoning}`);
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- crawl ---
+  program
+    .command("crawl")
+    .description("Crawl a URL and extract SEO metadata")
+    .requiredOption("--url <url>", "URL to crawl")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await crawlPage(opts.url);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(`Title:      ${data.title || "-"}`);
+          console.log(`Meta desc:  ${data.meta_desc || "-"}`);
+          console.log(`Word count: ${data.word_count || 0}`);
+          const headings = data.headings || [];
+          if (headings.length) {
+            console.log("Headings:");
+            for (const h of headings) {
+              console.log(`  ${h}`);
+            }
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- sync ---
+  program
+    .command("sync")
+    .description("Sync Google Search Console data")
+    .requiredOption("--site <url>", "Site URL to sync")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await syncGsc(opts.site);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(
+            `\x1b[32mSynced ${data.synced_queries || 0} queries for ${data.site || opts.site}\x1b[0m`
+          );
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- login ---
+  program
+    .command("login")
+    .description("Authenticate with Google for Search Console access")
+    .action(async () => {
+      const seoBase = process.env.SEO_BASE || "http://localhost:8765";
+
+      const existing = getCredentials();
+      if (existing && existing.authenticated) {
+        const readline = await import("node:readline");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+          rl.question("Already logged in. Re-authenticate? [y/N] ", resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== "y") return;
+      }
+
+      const result = await runLoginFlow(seoBase);
+      if (result) {
+        const email = result.email || "";
+        if (email) {
+          console.log(`\x1b[32mLogged in as ${email}\x1b[0m`);
+        } else {
+          console.log("\x1b[32mLogin successful! Credentials saved.\x1b[0m");
+        }
+      } else {
+        process.stderr.write("\x1b[31mLogin failed.\x1b[0m\n");
+        process.exit(1);
+      }
+    });
+
+  // --- logout ---
+  program
+    .command("logout")
+    .description("Remove stored credentials")
+    .action(() => {
+      clearCredentials();
+      console.log("\x1b[32mLogged out. Credentials removed.\x1b[0m");
+    });
+
+  // --- whoami ---
+  program
+    .command("whoami")
+    .description("Show current authentication status")
+    .action(() => {
+      const creds = getCredentials();
+      if (creds && creds.authenticated) {
+        const email = creds.email;
+        if (email) {
+          console.log(`\x1b[32mLogged in as ${email}\x1b[0m`);
+        } else {
+          console.log("\x1b[32mAuthenticated\x1b[0m");
+        }
+        const apiKey = creds.api_key || "";
+        if (apiKey) {
+          const prefix = apiKey.slice(0, 12);
+          const suffix = apiKey.length > 16 ? apiKey.slice(-4) : "";
+          console.log(`API key: ${prefix}...${suffix}`);
+        }
+        console.log(`API: ${creds.seo_base || "unknown"}`);
+      } else {
+        console.log("\x1b[33mNot authenticated. Run: xyle login\x1b[0m");
+      }
+    });
+}

package/src/formatting.mjs

@@ -0,0 +1,56 @@
+/**
+ * Output formatting helpers for the xyle CLI.
+ */
+
+/**
+ * Pretty-print data as JSON.
+ * @param {any} data
+ * @returns {string}
+ */
+export function printJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Render rows as an ASCII table matching the Python CLI output.
+ * @param {Array<Object>} rows
+ * @param {string[]} columns
+ * @returns {string}
+ */
+export function printTable(rows, columns) {
+  if (!rows || rows.length === 0) return "(no data)";
+
+  const widths = {};
+  for (const col of columns) {
+    widths[col] = col.length;
+  }
+
+  const strRows = [];
+  for (const row of rows) {
+    const strRow = {};
+    for (const col of columns) {
+      const val = row[col];
+      let cell;
+      if (typeof val === "number" && !Number.isInteger(val)) {
+        cell = val < 1 ? val.toFixed(3) : val.toFixed(1);
+      } else if (Array.isArray(val)) {
+        cell = val.join(", ");
+      } else if (val == null) {
+        cell = "-";
+      } else {
+        cell = String(val);
+      }
+      strRow[col] = cell;
+      widths[col] = Math.max(widths[col], cell.length);
+    }
+    strRows.push(strRow);
+  }
+
+  const header = columns.map((c) => c.toUpperCase().padEnd(widths[c])).join("  ");
+  const separator = columns.map((c) => "-".repeat(widths[c])).join("  ");
+  const lines = [header, separator];
+  for (const strRow of strRows) {
+    lines.push(columns.map((c) => strRow[c].padEnd(widths[c])).join("  "));
+  }
+  return lines.join("\n");
+}