@kite-copilot/cli 1.0.0

package/README.md

@@ -0,0 +1,325 @@
+# @kite/cli
+
+Command-line tool for analyzing frontend codebases to discover API mappings. The CLI uses Claude AI to analyze your frontend code, identify routes, API calls, and generate mappings that connect your frontend to the Kite backend.
+
+## Prerequisites
+
+### Claude CLI
+
+The Kite CLI requires Claude CLI to be installed for code analysis:
+
+```bash
+npm install -g @anthropic-ai/claude-cli
+```
+
+Verify installation:
+
+```bash
+claude --version
+```
+
+### Node.js
+
+Requires Node.js 18.0.0 or higher.
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install -g @kite/cli
+```
+
+### From source
+
+```bash
+cd agent/cli-npm
+npm install
+npm run build
+```
+
+Then run with:
+
+```bash
+node dist/index.js <command>
+```
+
+Or create a global link:
+
+```bash
+npm link
+kite <command>
+```
+
+## Commands
+
+### `kite login`
+
+Authenticate with the Kite backend.
+
+```bash
+kite login [--backend-url <url>]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--backend-url <url>` | Kite backend URL (default: https://api.kite.com) |
+
+**Environment Variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `KITE_BACKEND_URL` | Override default backend URL |
+
+**Example:**
+
+```bash
+# Login to production
+kite login
+
+# Login to local development server
+kite login --backend-url http://localhost:5002
+```
+
+When prompted, enter your API token from the Kite dashboard.
+
+### `kite logout`
+
+Clear stored credentials.
+
+```bash
+kite logout
+```
+
+### `kite status`
+
+Show current login status.
+
+```bash
+kite status
+```
+
+### `kite map`
+
+Analyze a frontend codebase to discover API mappings.
+
+```bash
+kite map <path> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<path>` | Path to the frontend codebase directory |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output JSON file path (default: kite-mappings.json) |
+| `-u, --upload` | Upload mappings to Kite backend after analysis |
+| `-q, --quiet` | Suppress terminal visualization output |
+| `-v, --verbose` | Show verbose debug output |
+| `--timeout <seconds>` | Analysis timeout in seconds (default: 300) |
+| `--no-output-file` | Don't generate output JSON file |
+
+**Examples:**
+
+```bash
+# Analyze and save to default file
+kite map ./my-frontend-app
+
+# Analyze with custom output file
+kite map ./my-frontend-app -o custom-mappings.json
+
+# Analyze and upload to backend
+kite map ./my-frontend-app --upload
+
+# Quiet mode - just generate the file
+kite map ./my-frontend-app --quiet
+
+# Verbose mode for debugging
+kite map ./my-frontend-app --verbose
+
+# Increase timeout for large codebases
+kite map ./my-frontend-app --timeout 600
+```
+
+## Configuration
+
+Credentials are stored in `~/.kite/config.json`:
+
+```json
+{
+  "token": "your-api-token",
+  "org_id": "organization-uuid",
+  "api_config_id": "config-uuid",
+  "email": "your@email.com",
+  "org_name": "Your Organization",
+  "backend_url": "https://api.kite.com"
+}
+```
+
+## Output Format
+
+The `kite map` command generates a JSON file with the following structure:
+
+```json
+{
+  "version": "1.0",
+  "generated_at": "2024-01-15T10:30:00Z",
+  "codebase_path": "/path/to/frontend",
+  "routes": [
+    {
+      "route_name": "customers",
+      "file_path": "pages/customers.tsx",
+      "component_name": "CustomersPage"
+    }
+  ],
+  "api_calls": [
+    {
+      "endpoint": "/api/customers",
+      "method": "GET",
+      "component_file": "pages/customers.tsx",
+      "action_form_type": null
+    }
+  ],
+  "mappings": [
+    {
+      "tool_name": "customers",
+      "api_endpoint": "/api/customers",
+      "navigation_page": "customers",
+      "action_form_type": "addCustomer",
+      "frontend_component": "CustomersPage",
+      "frontend_file_path": "pages/customers.tsx"
+    }
+  ]
+}
+```
+
+## Workflow
+
+### First-time Setup
+
+1. Install the CLI and Claude CLI
+2. Get your API token from the Kite dashboard
+3. Login: `kite login`
+4. Verify: `kite status`
+
+### Analyzing a Codebase
+
+1. Navigate to your project or provide the path
+2. Run: `kite map ./your-frontend --upload`
+3. Review the generated mappings
+4. Mappings are now available in the Kite backend
+
+### Local Development
+
+For local development without Supabase:
+
+```bash
+# 1. Seed local test data
+python agent/app/scripts/seed_local_dev.py
+
+# 2. Start the backend
+cd agent && python server.py
+
+# 3. Login to local backend
+kite login --backend-url http://localhost:5002
+
+# 4. Map your codebase
+kite map ./your-frontend --upload
+```
+
+## Troubleshooting
+
+### Claude CLI not found
+
+```
+Error: Claude CLI not found
+```
+
+**Solution:** Install Claude CLI:
+
+```bash
+npm install -g @anthropic-ai/claude-cli
+```
+
+### Analysis timeout
+
+```
+Error: Analysis timed out after 300 seconds
+```
+
+**Solution:** Increase the timeout:
+
+```bash
+kite map ./large-codebase --timeout 600
+```
+
+### Authentication failed
+
+```
+Error: Invalid token
+```
+
+**Solution:** Re-run login:
+
+```bash
+kite logout
+kite login
+```
+
+### Not logged in
+
+```
+Error: Not logged in. Run 'kite login' first.
+```
+
+**Solution:** Login before uploading:
+
+```bash
+kite login
+kite map ./frontend --upload
+```
+
+### Path is not a frontend project
+
+```
+Error: Directory doesn't appear to be a frontend project
+```
+
+**Solution:** Ensure your path contains one of:
+- `package.json`
+- `tsconfig.json`
+- `src/` directory
+- `app/` directory
+- `components/` directory
+- `pages/` directory
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Development mode
+
+```bash
+npm run dev
+```
+
+### Running from source
+
+```bash
+node dist/index.js map ./test-frontend
+```
+
+## License
+
+MIT

package/dist/analyzer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Claude Code Analyzer Module
+ *
+ * Invokes Claude Code CLI to analyze frontend codebases.
+ * Parses JSON responses into structured analysis results.
+ */
+import type { FrontendAnalysisResult, FrontendRoute, FrontendApiCall, FrontendMapping, AnalyzeOptions } from "./types.js";
+export declare class AnalyzerError extends Error {
+    constructor(message: string);
+}
+export declare class ClaudeNotFoundError extends AnalyzerError {
+    constructor(message: string);
+}
+export declare class ClaudeTimeoutError extends AnalyzerError {
+    constructor(message: string);
+}
+export declare class ClaudeParseError extends AnalyzerError {
+    constructor(message: string);
+}
+/**
+ * Validate that a path looks like a frontend project
+ */
+export declare function validateCodebasePath(codebasePath: string): void;
+/**
+ * Check if Claude CLI is available
+ */
+export declare function checkClaudeAvailable(claudePath?: string): Promise<boolean>;
+/**
+ * Parse Claude's response text into a structured object
+ */
+export declare function parseClaudeResponse(responseText: string): {
+    routes: FrontendRoute[];
+    api_calls: FrontendApiCall[];
+    mappings: FrontendMapping[];
+};
+/**
+ * Build a complete analysis result
+ */
+export declare function buildAnalysisResult(data: {
+    routes: FrontendRoute[];
+    api_calls: FrontendApiCall[];
+    mappings: FrontendMapping[];
+}, codebasePath: string): FrontendAnalysisResult;
+/**
+ * Analyze a frontend codebase using Claude Code
+ */
+export declare function analyzeWithClaude(codebasePath: string, options?: AnalyzeOptions): Promise<FrontendAnalysisResult>;
+/**
+ * Save analysis result to a JSON file
+ */
+export declare function saveResultToFile(result: FrontendAnalysisResult, outputPath: string): void;
+/**
+ * Upload mappings to the backend
+ */
+export declare function uploadMappings(result: FrontendAnalysisResult, config: {
+    backendUrl: string;
+    token: string;
+    orgId: string;
+    apiConfigId: string;
+}): Promise<{
+    success: boolean;
+    mappings_uploaded: number;
+    mappings_merged: number;
+    mappings_skipped: number;
+    message: string;
+}>;

package/dist/analyzer.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * Claude Code Analyzer Module
+ *
+ * Invokes Claude Code CLI to analyze frontend codebases.
+ * Parses JSON responses into structured analysis results.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeParseError = exports.ClaudeTimeoutError = exports.ClaudeNotFoundError = exports.AnalyzerError = void 0;
+exports.validateCodebasePath = validateCodebasePath;
+exports.checkClaudeAvailable = checkClaudeAvailable;
+exports.parseClaudeResponse = parseClaudeResponse;
+exports.buildAnalysisResult = buildAnalysisResult;
+exports.analyzeWithClaude = analyzeWithClaude;
+exports.saveResultToFile = saveResultToFile;
+exports.uploadMappings = uploadMappings;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// Analysis prompt for Claude Code (same as Python version)
+const ANALYSIS_PROMPT = `Analyze this frontend codebase and extract:
+
+1. All page routes and their component files
+   - Look for route definitions (React Router, Next.js pages, etc.)
+   - Map route names to their component files
+
+2. All API calls (fetch, axios, etc.) with endpoints and HTTP methods
+   - Find all HTTP requests to backend APIs
+   - Identify the HTTP method (GET, POST, PUT, DELETE, etc.)
+   - Note which component file makes each call
+
+3. Form action types (event names like "addCustomer", "updateSettings")
+   - Find custom event dispatches or action handlers
+   - Look for form submission handlers and their action types
+
+4. Map API endpoints to their likely tool names
+   - Extract the resource name from the endpoint (e.g., /api/customers -> customers)
+   - Associate with navigation pages and form types
+
+Return a JSON object with this EXACT structure (no markdown, no explanation, just JSON):
+{
+  "routes": [
+    {"route_name": "string", "file_path": "string", "component_name": "string"}
+  ],
+  "api_calls": [
+    {"endpoint": "string", "method": "string", "component_file": "string", "action_form_type": "string or null"}
+  ],
+  "mappings": [
+    {
+      "tool_name": "string",
+      "api_endpoint": "string",
+      "navigation_page": "string or null",
+      "action_form_type": "string or null",
+      "frontend_component": "string or null",
+      "frontend_file_path": "string or null"
+    }
+  ]
+}
+
+Important:
+- tool_name should be the resource name extracted from the API endpoint (e.g., "/api/customers" -> "customers")
+- navigation_page should match a route_name if the API is used on that page
+- action_form_type should match form handlers or custom events
+- Return ONLY valid JSON, no markdown code blocks or explanations`;
+class AnalyzerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AnalyzerError";
+    }
+}
+exports.AnalyzerError = AnalyzerError;
+class ClaudeNotFoundError extends AnalyzerError {
+    constructor(message) {
+        super(message);
+        this.name = "ClaudeNotFoundError";
+    }
+}
+exports.ClaudeNotFoundError = ClaudeNotFoundError;
+class ClaudeTimeoutError extends AnalyzerError {
+    constructor(message) {
+        super(message);
+        this.name = "ClaudeTimeoutError";
+    }
+}
+exports.ClaudeTimeoutError = ClaudeTimeoutError;
+class ClaudeParseError extends AnalyzerError {
+    constructor(message) {
+        super(message);
+        this.name = "ClaudeParseError";
+    }
+}
+exports.ClaudeParseError = ClaudeParseError;
+/**
+ * Validate that a path looks like a frontend project
+ */
+function validateCodebasePath(codebasePath) {
+    if (!fs.existsSync(codebasePath)) {
+        throw new AnalyzerError(`Codebase path does not exist: ${codebasePath}`);
+    }
+    const stat = fs.statSync(codebasePath);
+    if (!stat.isDirectory()) {
+        throw new AnalyzerError(`Codebase path is not a directory: ${codebasePath}`);
+    }
+    // Check for common frontend project indicators
+    const indicators = [
+        "package.json",
+        "tsconfig.json",
+        "src",
+        "app",
+        "components",
+        "pages",
+    ];
+    const foundIndicators = indicators.filter((ind) => fs.existsSync(path.join(codebasePath, ind)));
+    if (foundIndicators.length === 0) {
+        throw new AnalyzerError(`Directory doesn't appear to be a frontend project. Expected one of: ${indicators.join(", ")}`);
+    }
+}
+/**
+ * Check if Claude CLI is available
+ */
+async function checkClaudeAvailable(claudePath = "claude") {
+    return new Promise((resolve) => {
+        const proc = (0, node_child_process_1.spawn)(claudePath, ["--version"], { stdio: "pipe" });
+        proc.on("close", (code) => {
+            resolve(code === 0);
+        });
+        proc.on("error", () => {
+            resolve(false);
+        });
+        // Timeout after 5 seconds
+        setTimeout(() => {
+            proc.kill();
+            resolve(false);
+        }, 5000);
+    });
+}
+/**
+ * Parse Claude's response text into a structured object
+ */
+function parseClaudeResponse(responseText) {
+    if (!responseText || !responseText.trim()) {
+        throw new ClaudeParseError("Empty response from Claude");
+    }
+    let text = responseText.trim();
+    // Remove markdown code blocks if present
+    if (text.startsWith("```")) {
+        const lines = text.split("\n");
+        // Remove first line (```json or ```)
+        const contentLines = lines.slice(1);
+        // Find and remove closing ```
+        const endIndex = contentLines.findIndex((line) => line.trim() === "```");
+        if (endIndex !== -1) {
+            text = contentLines.slice(0, endIndex).join("\n");
+        }
+        else {
+            text = contentLines.join("\n");
+        }
+    }
+    // Try to find JSON object in the text
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        text = jsonMatch[0];
+    }
+    try {
+        const data = JSON.parse(text);
+        return {
+            routes: data.routes || [],
+            api_calls: data.api_calls || [],
+            mappings: data.mappings || [],
+        };
+    }
+    catch (e) {
+        throw new ClaudeParseError(`Failed to parse JSON response: ${e}\nResponse: ${text.substring(0, 500)}`);
+    }
+}
+/**
+ * Build a complete analysis result
+ */
+function buildAnalysisResult(data, codebasePath) {
+    return {
+        version: "1.0",
+        generated_at: new Date().toISOString(),
+        codebase_path: codebasePath,
+        routes: data.routes,
+        api_calls: data.api_calls,
+        mappings: data.mappings,
+    };
+}
+/**
+ * Analyze a frontend codebase using Claude Code
+ */
+async function analyzeWithClaude(codebasePath, options = {}) {
+    const { timeout = 300, claudePath = "claude" } = options;
+    // Validate path
+    validateCodebasePath(codebasePath);
+    // Get absolute path
+    const absolutePath = path.resolve(codebasePath);
+    // Check Claude is available
+    const claudeAvailable = await checkClaudeAvailable(claudePath);
+    if (!claudeAvailable) {
+        throw new ClaudeNotFoundError("Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-cli");
+    }
+    return new Promise((resolve, reject) => {
+        const args = ["--print", "-p", ANALYSIS_PROMPT];
+        const proc = (0, node_child_process_1.spawn)(claudePath, args, {
+            cwd: absolutePath,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        // Set timeout
+        const timeoutId = setTimeout(() => {
+            proc.kill();
+            reject(new ClaudeTimeoutError(`Claude analysis timed out after ${timeout} seconds`));
+        }, timeout * 1000);
+        proc.on("close", (code) => {
+            clearTimeout(timeoutId);
+            if (code !== 0) {
+                reject(new AnalyzerError(`Claude exited with code ${code}: ${stderr}`));
+                return;
+            }
+            try {
+                const data = parseClaudeResponse(stdout);
+                const result = buildAnalysisResult(data, absolutePath);
+                resolve(result);
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        proc.on("error", (err) => {
+            clearTimeout(timeoutId);
+            reject(new ClaudeNotFoundError(`Failed to spawn Claude: ${err.message}`));
+        });
+    });
+}
+/**
+ * Save analysis result to a JSON file
+ */
+function saveResultToFile(result, outputPath) {
+    const json = JSON.stringify(result, null, 2);
+    fs.writeFileSync(outputPath, json, "utf-8");
+}
+/**
+ * Upload mappings to the backend
+ */
+async function uploadMappings(result, config) {
+    const url = `${config.backendUrl}/api/mappings/frontend?org_id=${config.orgId}&api_config_id=${config.apiConfigId}`;
+    // Filter out mappings with null/empty api_endpoint (invalid data from Claude)
+    const validMappings = result.mappings.filter((m) => m.api_endpoint && m.tool_name);
+    const payload = {
+        mappings: validMappings.map((m) => ({
+            tool_name: m.tool_name,
+            api_endpoint: m.api_endpoint,
+            navigation_page: m.navigation_page,
+            action_form_type: m.action_form_type,
+            frontend_component: m.frontend_component,
+            frontend_file_path: m.frontend_file_path,
+        })),
+        metadata: {
+            codebase_path: result.codebase_path,
+            analyzed_at: result.generated_at,
+            version: result.version,
+            routes_count: result.routes.length,
+            api_calls_count: result.api_calls.length,
+        },
+    };
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (response.status === 401) {
+        throw new Error("Authentication failed. Please run 'kite login' again.");
+    }
+    if (response.status === 403) {
+        throw new Error("Access denied for this organization.");
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Upload failed: ${response.status} ${text}`);
+    }
+    const data = await response.json();
+    return {
+        success: true,
+        mappings_uploaded: data.mappings_uploaded || validMappings.length,
+        mappings_merged: data.mappings_merged || 0,
+        mappings_skipped: data.mappings_skipped || (result.mappings.length - validMappings.length),
+        message: data.message || "Mappings uploaded successfully",
+    };
+}