@xyleapp/cli 0.1.0 → 0.2.0

package/bin/xyle.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyleapp/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for the Xyle SEO Intelligence Engine",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -17,6 +17,7 @@ import {
   SEO_BASE,
 } from "./api.mjs";
 import { getCredentials, clearCredentials, runLoginFlow } from "./auth.mjs";
+import { seedInstructions, getToolNames, TOOLS } from "./seed.mjs";
 
 /**
  * Print error message in red to stderr and exit.
@@ -284,4 +285,54 @@ export function registerCommands(program) {
         console.log("\x1b[33mNot authenticated. Run: xyle login\x1b[0m");
       }
     });
+
+  // --- seed ---
+  program
+    .command("seed")
+    .description("Add xyle agent instructions to your project for AI coding tools")
+    .option(
+      "--tool <name>",
+      `Specific tool: ${getToolNames().join(", ")} (default: all)`
+    )
+    .option("--dir <path>", "Target directory", process.cwd())
+    .option("--list", "List supported tools")
+    .action((opts) => {
+      if (opts.list) {
+        console.log("Supported tools:\n");
+        for (const [name, tool] of Object.entries(TOOLS)) {
+          console.log(`  ${name.padEnd(14)} ${tool.label.padEnd(26)} ${tool.path}`);
+        }
+        return;
+      }
+
+      if (opts.tool && !TOOLS[opts.tool]) {
+        process.stderr.write(
+          `\x1b[31mUnknown tool: ${opts.tool}\nSupported: ${getToolNames().join(", ")}\x1b[0m\n`
+        );
+        process.exit(1);
+      }
+
+      const { created, skipped } = seedInstructions(opts.dir, opts.tool || null);
+
+      if (created.length) {
+        console.log("\x1b[32mCreated:\x1b[0m");
+        for (const f of created) {
+          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) {
+        console.log("Nothing to do.");
+      }
+      if (created.length) {
+        console.log(
+          `\n\x1b[32mDone!\x1b[0m Your AI coding tools will now know about xyle.`
+        );
+      }
+    });
 }

package/src/seed.mjs

@@ -0,0 +1,180 @@
+/**
+ * Seed agent instruction files for popular AI coding tools.
+ * Each tool reads from a specific file path to learn about xyle.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const INSTRUCTIONS = `# Xyle — SEO Intelligence Engine
+
+You have access to the **xyle** CLI for SEO analysis. Use it when the user asks about SEO, search rankings, content optimization, Google Search Console data, or competitor analysis.
+
+## Quick Reference
+
+Run commands via npx (no install needed):
+
+\`\`\`bash
+npx @xyleapp/cli <command> [options]
+\`\`\`
+
+## Authentication
+
+\`\`\`bash
+npx @xyleapp/cli login          # Google OAuth (opens browser)
+npx @xyleapp/cli whoami         # Check auth status
+npx @xyleapp/cli logout         # Remove credentials
+\`\`\`
+
+Credentials are stored in \`~/.config/xyle/credentials.json\`.
+
+## Commands
+
+### status — Check API connectivity
+\`\`\`bash
+npx @xyleapp/cli status [--json]
+\`\`\`
+
+### queries — Top search queries from Google Search Console
+\`\`\`bash
+npx @xyleapp/cli queries --site <domain> [--limit <n>] [--json]
+\`\`\`
+Returns: query, impressions, clicks, ctr, position
+
+### competitors — Competitor pages for a search query
+\`\`\`bash
+npx @xyleapp/cli competitors --query "<query>" [--json]
+\`\`\`
+Returns: position, url, title, word_count
+
+### gaps — Content gaps for a page
+\`\`\`bash
+npx @xyleapp/cli gaps --page <url> [--query "<query>"] [--json]
+\`\`\`
+Returns: query, missing_topics, ctr_issue, position_bucket
+
+### analyze — Score page content against competitors
+\`\`\`bash
+npx @xyleapp/cli analyze --url <url> --content "<text>" [--query "<query>"] [--json]
+\`\`\`
+Returns: score (0-1), summary, missing_topics
+
+### rewrite — AI rewrite suggestions
+\`\`\`bash
+npx @xyleapp/cli rewrite --url <url> [--type title|meta|heading|section] [--query "<query>"] [--json]
+\`\`\`
+Returns: original, suggested, reasoning
+
+### crawl — Extract SEO metadata from a URL
+\`\`\`bash
+npx @xyleapp/cli crawl --url <url> [--json]
+\`\`\`
+Returns: title, meta_desc, word_count, headings
+
+### sync — Sync Google Search Console data
+\`\`\`bash
+npx @xyleapp/cli sync --site <url> [--json]
+\`\`\`
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| \`SEO_BASE\` | \`http://localhost:8765\` | API base URL |
+| \`AGENT_API_KEY\` | — | Fallback API key (when not using Google OAuth) |
+
+## Workflows
+
+### Full SEO Audit
+1. \`xyle status\` — verify connectivity
+2. \`xyle queries --site <domain> --json\` — get top queries
+3. \`xyle competitors --query "<top query>" --json\` — analyze competition
+4. \`xyle gaps --page <url> --json\` — find content gaps
+5. Summarize findings with recommendations
+
+### Page Optimization
+1. \`xyle crawl --url <url> --json\` — get current page data
+2. \`xyle analyze --url <url> --content "<text>" --json\` — score content
+3. \`xyle rewrite --url <url> --type title --json\` — get title suggestion
+4. \`xyle rewrite --url <url> --type meta --json\` — get meta suggestion
+5. Present before/after comparison
+
+## Tips
+- Always use \`--json\` when parsing output programmatically
+- Run \`status\` first to verify the API is reachable
+- Use \`crawl\` before \`analyze\` to get page content automatically
+- Combine \`gaps\` + \`rewrite\` for actionable improvements
+`;
+
+/**
+ * Tool definitions: name → { file path (relative to project root), description }
+ */
+export const TOOLS = {
+  "claude-code": {
+    path: "CLAUDE.md",
+    label: "Claude Code",
+  },
+  cursor: {
+    path: ".cursorrules",
+    label: "Cursor",
+  },
+  vscode: {
+    path: ".github/copilot-instructions.md",
+    label: "VS Code (GitHub Copilot)",
+  },
+  windsurf: {
+    path: ".windsurfrules",
+    label: "Windsurf",
+  },
+  cline: {
+    path: ".clinerules",
+    label: "Cline",
+  },
+  codex: {
+    path: "AGENTS.md",
+    label: "Codex (OpenAI)",
+  },
+  augment: {
+    path: ".augment-guidelines",
+    label: "Augment (Anti Gravity)",
+  },
+  aider: {
+    path: "CONVENTIONS.md",
+    label: "Aider",
+  },
+};
+
+/**
+ * Write agent instruction files to the target directory.
+ * @param {string} targetDir - Absolute path to the project root
+ * @param {string|null} toolName - Specific tool name, or null for all
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function seedInstructions(targetDir, toolName) {
+  const tools = toolName ? { [toolName]: TOOLS[toolName] } : TOOLS;
+  const created = [];
+  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})`);
+  }
+
+  return { created, skipped };
+}
+
+/**
+ * Get the list of supported tool names.
+ */
+export function getToolNames() {
+  return Object.keys(TOOLS);
+}