react-doctor-cli-dev 1.0.2 → 1.0.4

package/backend/dist/db.js

@@ -1,69 +1,26 @@
 "use strict";
-// ─────────────────────────────────────────────────────────────
-// backend/src/db.ts
-//
-// SQLite database via better-sqlite3 (synchronous, fast).
-//
-// SCHEMA:
-//
-//   reports — one row per analysis run
-//     id           — auto-increment PK
-//     project      — project name / hostname
-//     score        — 0-100 overall performance score
-//     grade        — A+, A, B, C, D, F
-//     analyzed_at  — ISO timestamp from the CLI
-//     created_at   — when the row was inserted
-//     static_json  — full StaticReport as JSON string
-//     runtime_json — full RuntimeReport map as JSON string
-//                    (screenshots stripped — stored as files)
-//     suggestions  — full Suggestion[] as JSON string
-//
-// WHY SPLIT COLUMNS INSTEAD OF ONE payload COLUMN?
-//   The old schema stored everything in a single `payload` TEXT
-//   column. This meant the dashboard couldn't query individual
-//   fields without parsing the whole blob. Splitting into three
-//   typed columns lets us:
-//     • SELECT only the part we need (e.g. just static_json for
-//       the issues page)
-//     • Keep the list endpoint fast (no giant blobs per row)
-//     • Add indices on score/grade later without changing schema
-//
-// SCREENSHOT STORAGE:
-//   Screenshots are base64 PNGs — up to 200KB each. Storing them
-//   in SQLite bloats the DB and makes every query slower. Instead:
-//     • The upload route strips dataUrls from runtime_json
-//     • Saves each screenshot as a .png file in data/screenshots/
-//     • Replaces dataUrl with a relative path /screenshots/<file>
-//   The dashboard fetches screenshots via the static file route.
-// ─────────────────────────────────────────────────────────────
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.screenshotsDir = void 0;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const dotenv_1 = __importDefault(require("dotenv"));
-dotenv_1.default.config({ path: path_1.default.join(__dirname, "..", ".env") });
-const PACKAGE_ROOT = path_1.default.resolve(__dirname, "..", "..");
-const DEFAULT_DB = path_1.default.join(PACKAGE_ROOT, "backend", "data", "reports.db");
-const dbPath = process.env.DB_PATH || DEFAULT_DB;
+const os_1 = __importDefault(require("os"));
+// Store DB in user's home directory — works regardless of where process spawns from
+const dbDir = path_1.default.join(os_1.default.homedir(), ".react-doctor");
+const dbPath = process.env.DB_PATH || path_1.default.join(dbDir, "reports.db");
 fs_1.default.mkdirSync(path_1.default.dirname(dbPath), { recursive: true });
-fs_1.default.mkdirSync(path_1.default.join(path_1.default.dirname(dbPath), "screenshots"), { recursive: true });
 const db = new better_sqlite3_1.default(dbPath);
 db.exec(`
-  CREATE TABLE IF NOT EXISTS reports (
-    id            INTEGER PRIMARY KEY AUTOINCREMENT,
-    project       TEXT    NOT NULL,
-    score         INTEGER NOT NULL,
-    grade         TEXT    NOT NULL,
-    analyzed_at   TEXT    NOT NULL,
-    created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
-    static_json   TEXT    NOT NULL,
-    runtime_json  TEXT    NOT NULL,
-    suggestions   TEXT    NOT NULL
-  );
+CREATE TABLE IF NOT EXISTS reports (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project TEXT NOT NULL,
+    score INTEGER NOT NULL,
+    grade TEXT NOT NULL,
+    analyzed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    payload TEXT NOT NULL
+);
 `);
-exports.screenshotsDir = path_1.default.join(path_1.default.dirname(dbPath), "screenshots");
 exports.default = db;

package/backend/dist/index.js

@@ -9,34 +9,27 @@ const helmet_1 = __importDefault(require("helmet"));
 const dotenv_1 = __importDefault(require("dotenv"));
 const path_1 = __importDefault(require("path"));
 const reports_1 = __importDefault(require("./routes/reports"));
-const db_1 = require("./db");
-dotenv_1.default.config({ path: path_1.default.join(__dirname, "..", ".env") });
+// Load .env from the backend folder, not from cwd
+dotenv_1.default.config({ path: path_1.default.join(__dirname, '..', '.env') });
 const app = (0, express_1.default)();
 const PORT = process.env.PORT || 3000;
-// ── Middleware ────────────────────────────────────────────────
+const API_KEY = process.env.API_KEY || "react-doctor-secret-key-change-this";
+// Make API_KEY available globally so auth middleware can use it
+process.env.API_KEY = API_KEY;
 app.use((0, helmet_1.default)());
 app.use((0, cors_1.default)());
-app.use(express_1.default.json({ limit: "50mb" }));
-// ── Static: screenshots saved by the upload route ────────────
-// Served at /screenshots/<filename>
-// The dashboard uses these as <img src="/screenshots/...">
-app.use("/screenshots", express_1.default.static(db_1.screenshotsDir));
-// ── Routes ────────────────────────────────────────────────────
-app.use("/api/reports", reports_1.default);
-// ── Health check ──────────────────────────────────────────────
-app.get("/health", (_req, res) => {
-    res.json({ status: "ok", timestamp: new Date().toISOString() });
+app.use(express_1.default.json({ limit: '50mb' }));
+app.use('/api/reports', reports_1.default);
+app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', timestamp: new Date().toISOString() });
 });
-// ── 404 ───────────────────────────────────────────────────────
-app.use((_req, res) => {
-    res.status(404).json({ message: "Route not found" });
+app.use((req, res) => {
+    res.status(404).json({ message: 'Route not found' });
 });
-// ── Error handler ─────────────────────────────────────────────
 app.use((err, _req, res, _next) => {
     console.error(err.stack);
-    res.status(500).json({ message: "Internal Server Error" });
+    res.status(500).json({ message: 'Internal Server Error' });
 });
-// ── Start ─────────────────────────────────────────────────────
 app.listen(PORT, () => {
-    console.log(`React Doctor backend running on http://localhost:${PORT}`);
+    console.log(`🩺 React Doctor backend running on http://localhost:${PORT}`);
 });

package/backend/dist/routes/reports.js

@@ -31,39 +31,6 @@
 //     /screenshots/<filename>
 //   so the dashboard can load them as normal <img> tags.
 // ─────────────────────────────────────────────────────────────
-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;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -71,8 +38,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const db_1 = __importStar(require("../db"));
+const db_1 = __importDefault(require("../db"));
 const auth_1 = require("../middleware/auth");
+const screenshotsDir = "data/screenshots";
 const router = (0, express_1.Router)();
 // ── GET /api/reports ─────────────────────────────────────────
 // Summary list — no blobs, just the columns the history page needs.
@@ -241,7 +209,7 @@ function saveScreenshots(reportId, pending) {
         const safeRoute = shot.routeKey.replace(/[/:]/g, "-").replace(/^-+/, "");
         const safeLabel = shot.label.replace(/[^a-z0-9]/gi, "-");
         const filename = `${reportId}-${safeRoute}-${safeLabel}.png`;
-        const fullPath = path_1.default.join(db_1.screenshotsDir, filename);
+        const fullPath = path_1.default.join(screenshotsDir, filename);
         try {
             fs_1.default.writeFileSync(fullPath, shot.buffer);
             saved.push({

package/backend/src/db.ts

@@ -1,70 +1,25 @@
-// ─────────────────────────────────────────────────────────────
-// backend/src/db.ts
-//
-// SQLite database via better-sqlite3 (synchronous, fast).
-//
-// SCHEMA:
-//
-//   reports — one row per analysis run
-//     id           — auto-increment PK
-//     project      — project name / hostname
-//     score        — 0-100 overall performance score
-//     grade        — A+, A, B, C, D, F
-//     analyzed_at  — ISO timestamp from the CLI
-//     created_at   — when the row was inserted
-//     static_json  — full StaticReport as JSON string
-//     runtime_json — full RuntimeReport map as JSON string
-//                    (screenshots stripped — stored as files)
-//     suggestions  — full Suggestion[] as JSON string
-//
-// WHY SPLIT COLUMNS INSTEAD OF ONE payload COLUMN?
-//   The old schema stored everything in a single `payload` TEXT
-//   column. This meant the dashboard couldn't query individual
-//   fields without parsing the whole blob. Splitting into three
-//   typed columns lets us:
-//     • SELECT only the part we need (e.g. just static_json for
-//       the issues page)
-//     • Keep the list endpoint fast (no giant blobs per row)
-//     • Add indices on score/grade later without changing schema
-//
-// SCREENSHOT STORAGE:
-//   Screenshots are base64 PNGs — up to 200KB each. Storing them
-//   in SQLite bloats the DB and makes every query slower. Instead:
-//     • The upload route strips dataUrls from runtime_json
-//     • Saves each screenshot as a .png file in data/screenshots/
-//     • Replaces dataUrl with a relative path /screenshots/<file>
-//   The dashboard fetches screenshots via the static file route.
-// ─────────────────────────────────────────────────────────────
-
 import Database from "better-sqlite3";
-import path     from "path";
-import fs       from "fs";
-import dotenv   from "dotenv";
-
-dotenv.config({ path: path.join(__dirname, "..", ".env") });
+import path from "path";
+import fs from "fs";
+import os from "os";
 
-const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
-const DEFAULT_DB   = path.join(PACKAGE_ROOT, "backend", "data", "reports.db");
-const dbPath       = process.env.DB_PATH || DEFAULT_DB;
+// Store DB in user's home directory — works regardless of where process spawns from
+const dbDir = path.join(os.homedir(), ".react-doctor");
+const dbPath = process.env.DB_PATH || path.join(dbDir, "reports.db");
 
 fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-fs.mkdirSync(path.join(path.dirname(dbPath), "screenshots"), { recursive: true });
 
 const db = new Database(dbPath);
-
 db.exec(`
-  CREATE TABLE IF NOT EXISTS reports (
-    id            INTEGER PRIMARY KEY AUTOINCREMENT,
-    project       TEXT    NOT NULL,
-    score         INTEGER NOT NULL,
-    grade         TEXT    NOT NULL,
-    analyzed_at   TEXT    NOT NULL,
-    created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
-    static_json   TEXT    NOT NULL,
-    runtime_json  TEXT    NOT NULL,
-    suggestions   TEXT    NOT NULL
-  );
+CREATE TABLE IF NOT EXISTS reports (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project TEXT NOT NULL,
+    score INTEGER NOT NULL,
+    grade TEXT NOT NULL,
+    analyzed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    payload TEXT NOT NULL
+);
 `);
 
-export const screenshotsDir = path.join(path.dirname(dbPath), "screenshots");
-export default db;
+export default db;

package/backend/src/index.ts

@@ -1,46 +1,39 @@
-import express, { Request, Response, NextFunction } from "express";
-import cors    from "cors";
-import helmet  from "helmet";
-import dotenv  from "dotenv";
-import path    from "path";
-import reportRoutes          from "./routes/reports";
-import db, { screenshotsDir } from "./db";
-
-dotenv.config({ path: path.join(__dirname, "..", ".env") });
-
-const app  = express();
+import express, { Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import dotenv from 'dotenv';
+import path from 'path';
+import reportRoutes from './routes/reports';
+import db from './db';
+
+// Load .env from the backend folder, not from cwd
+dotenv.config({ path: path.join(__dirname, '..', '.env') });
+
+const app = express();
 const PORT = process.env.PORT || 3000;
+const API_KEY = process.env.API_KEY || "react-doctor-secret-key-change-this";
+
+// Make API_KEY available globally so auth middleware can use it
+process.env.API_KEY = API_KEY;
 
-// ── Middleware ────────────────────────────────────────────────
 app.use(helmet());
 app.use(cors());
-app.use(express.json({ limit: "50mb" }));
+app.use(express.json({ limit: '50mb' }));
+app.use('/api/reports', reportRoutes);
 
-// ── Static: screenshots saved by the upload route ────────────
-// Served at /screenshots/<filename>
-// The dashboard uses these as <img src="/screenshots/...">
-app.use("/screenshots", express.static(screenshotsDir));
-
-// ── Routes ────────────────────────────────────────────────────
-app.use("/api/reports", reportRoutes);
-
-// ── Health check ──────────────────────────────────────────────
-app.get("/health", (_req: Request, res: Response) => {
-  res.json({ status: "ok", timestamp: new Date().toISOString() });
+app.get('/health', (_req: Request, res: Response) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
 });
 
-// ── 404 ───────────────────────────────────────────────────────
-app.use((_req: Request, res: Response) => {
-  res.status(404).json({ message: "Route not found" });
+app.use((req: Request, res: Response) => {
+  res.status(404).json({ message: 'Route not found' });
 });
 
-// ── Error handler ─────────────────────────────────────────────
 app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
   console.error(err.stack);
-  res.status(500).json({ message: "Internal Server Error" });
+  res.status(500).json({ message: 'Internal Server Error' });
 });
 
-// ── Start ─────────────────────────────────────────────────────
 app.listen(PORT, () => {
-  console.log(`React Doctor backend running on http://localhost:${PORT}`);
-});
+  console.log(`🩺 React Doctor backend running on http://localhost:${PORT}`);
+});

package/backend/src/routes/reports.ts

@@ -34,9 +34,11 @@
 import { Router, Request, Response, RequestHandler } from "express";
 import path from "path";
 import fs   from "fs";
-import db, { screenshotsDir } from "../db";
+import db from "../db";
 import { requireApiKey }      from "../middleware/auth";
 
+const screenshotsDir = "data/screenshots";
+
 const router = Router();
 
 // ── GET /api/reports ─────────────────────────────────────────

package/cli/dist/commands/dashboard.js

@@ -0,0 +1,152 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────
+// cli/src/commands/dashboard.ts
+//
+// react-doctor dashboard
+//
+// Opens the React Doctor dashboard in the browser.
+//
+// WHAT IT DOES:
+//   1. Checks if the backend is already running on the port
+//   2. If not — starts it automatically (same logic as --upload)
+//   3. Opens http://localhost:PORT in the default browser
+//
+// This command is the natural companion to --upload.
+// Workflow:
+//   react-doctor full ./my-app --upload   ← runs analysis + saves report
+//   react-doctor dashboard                ← opens the dashboard to view it
+//
+// Or in one shot:
+//   react-doctor full ./my-app --upload && react-doctor dashboard
+// ─────────────────────────────────────────────────────────────
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDashboardCommand = registerDashboardCommand;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const axios_1 = __importDefault(require("axios"));
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("../ui");
+function registerDashboardCommand(program) {
+    program
+        .command("dashboard")
+        .description("Open the React Doctor dashboard (auto-starts backend if needed)")
+        .option("--port <port>", "Port the backend runs on", "3000")
+        .option("--api-key <key>", "API key for the backend", process.env.REACT_DOCTOR_API_KEY || "react-doctor-secret-key-change-this")
+        .option("--no-banner", "Skip the banner")
+        .action(async (options) => {
+        if (!options.noBanner)
+            (0, ui_1.printBanner)();
+        const port = options.port;
+        const apiUrl = `http://localhost:${port}`;
+        (0, ui_1.printSection)("Dashboard");
+        (0, ui_1.printInfo)("Backend URL", apiUrl);
+        console.log();
+        const spin = (0, ui_1.spinner)("Checking backend status...");
+        try {
+            // ── 1. Check if backend is already up ─────────────────
+            let backendRunning = false;
+            try {
+                await axios_1.default.get(`${apiUrl}/health`, { timeout: 2000 });
+                backendRunning = true;
+            }
+            catch {
+                backendRunning = false;
+            }
+            // ── 2. Start backend if not running ───────────────────
+            if (!backendRunning) {
+                spin.text = "  Backend not running — starting automatically...";
+                // Locate backend folder (sibling of cli/)
+                const projectRoot = path_1.default.resolve(__dirname, "..", "..", "..");
+                const backendRoot = path_1.default.resolve(projectRoot, "backend");
+                const backendDist = path_1.default.join(backendRoot, "dist", "index.js");
+                const backendSrc = path_1.default.join(backendRoot, "src", "index.ts");
+                let command;
+                let args;
+                if (fs_1.default.existsSync(backendDist)) {
+                    command = "node";
+                    args = [backendDist];
+                }
+                else if (fs_1.default.existsSync(backendSrc)) {
+                    command = "npx";
+                    args = ["ts-node", backendSrc];
+                }
+                else {
+                    spin.fail(chalk_1.default.red("Backend not found"));
+                    (0, ui_1.printFail)(`Could not find backend at: ${backendRoot}\n\n` +
+                        `  Make sure the 'backend/' folder exists next to 'cli/'.`);
+                    process.exit(1);
+                }
+                // Create data dir inside npm global cache for the backend DB
+                const dataDir = path_1.default.join(backendRoot, "data");
+                fs_1.default.mkdirSync(dataDir, { recursive: true });
+                (0, child_process_1.spawn)(command, args, {
+                    stdio: "ignore",
+                    detached: true,
+                    env: {
+                        ...process.env,
+                        API_KEY: options.apiKey,
+                        PORT: port,
+                        DB_PATH: path_1.default.join(dataDir, "reports.db"),
+                    },
+                    cwd: backendRoot,
+                }).unref(); // let CLI exit without killing the server
+                // Wait for backend to be ready (up to 15 seconds)
+                let ready = false;
+                let retries = 0;
+                while (!ready && retries < 15) {
+                    try {
+                        await axios_1.default.get(`${apiUrl}/health`, { timeout: 1000 });
+                        ready = true;
+                    }
+                    catch {
+                        await new Promise(r => setTimeout(r, 1000));
+                        retries++;
+                    }
+                }
+                if (!ready) {
+                    spin.fail(chalk_1.default.red("Backend failed to start"));
+                    (0, ui_1.printFail)("Backend did not respond after 15 seconds.");
+                    process.exit(1);
+                }
+                spin.succeed(chalk_1.default.green("Backend started successfully"));
+            }
+            else {
+                spin.succeed(chalk_1.default.green("Backend already running"));
+            }
+            // ── 3. Open dashboard in default browser ──────────────
+            const dashboardUrl = apiUrl;
+            console.log();
+            (0, ui_1.printInfo)("Opening", dashboardUrl);
+            console.log();
+            // Cross-platform browser open
+            const openCmd = process.platform === "win32" ? ["cmd", ["/c", "start", dashboardUrl]] :
+                process.platform === "darwin" ? ["open", [dashboardUrl]] :
+                    ["xdg-open", [dashboardUrl]];
+            (0, child_process_1.spawn)(openCmd[0], openCmd[1], {
+                stdio: "ignore",
+                detached: true,
+            }).unref();
+            (0, ui_1.printDone)(`Dashboard opened at ${chalk_1.default.cyan(dashboardUrl)}`);
+            // ── 4. Show quick API reference ───────────────────────
+            console.log(chalk_1.default.gray("  Available endpoints:"));
+            console.log(chalk_1.default.cyan(`    GET  ${apiUrl}/health`));
+            console.log(chalk_1.default.cyan(`    GET  ${apiUrl}/api/reports`));
+            console.log(chalk_1.default.cyan(`    GET  ${apiUrl}/api/reports/:id`));
+            console.log(chalk_1.default.cyan(`    GET  ${apiUrl}/api/reports/project/:name`));
+            console.log(chalk_1.default.cyan(`    POST ${apiUrl}/api/reports/upload`));
+            console.log();
+            console.log(chalk_1.default.gray("  Tip: run ") +
+                chalk_1.default.cyan("react-doctor full ./ --upload") +
+                chalk_1.default.gray(" to add a new report.\n"));
+        }
+        catch (err) {
+            spin.fail(chalk_1.default.red("Dashboard failed to open"));
+            console.log(chalk_1.default.red(`\n  ${err.message}\n`));
+            process.exit(1);
+        }
+    });
+}

package/cli/dist/index.js

@@ -1,77 +1,51 @@
 #!/usr/bin/env node
 "use strict";
 // ─────────────────────────────────────────────────────────────
-// cli/src/index.ts
-//
-// The CLI entry point. This is the file that runs when the
-// user types "react-doctor" in their terminal.
-//
-// HOW IT WORKS:
-// 1. Commander.js parses the command and flags from argv
-// 2. The matching command handler is called
-// 3. The handler imports core modules and runs the pipeline
-//
-// HOW THE BINARY REGISTRATION WORKS:
-// package.json has a "bin" field:
-//   "bin": { "react-doctor": "./dist/index.js" }
-//
-// After "npm link" (dev) or "npm install" (production),
-// npm creates a symlink from the system's bin directory
-// to this file. That's what makes "react-doctor" a real
-// terminal command available anywhere.
-//
-// THE SHEBANG (#!/usr/bin/env node) on line 1:
-// This tells the OS to run this file with Node.js when
-// called directly as a script. Without it, the OS doesn't
-// know which interpreter to use.
+// cli/src/index.ts  —  CLI entry point
 // ─────────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const analyze_1 = require("./commands/analyze");
 const profile_1 = require("./commands/profile");
 const full_1 = require("./commands/full");
-const install_1 = require("./commands/install");
+const dashboard_1 = require("./commands/dashboard");
 const program = new commander_1.Command();
 // ── Program metadata ──────────────────────────────────────────
 program
     .name("react-doctor")
     .description("React performance analyzer — static analysis + runtime profiling + smart suggestions")
-    .version("1.0.0");
-// ── Register all commands ─────────────────────────────────────
-// Each function adds one command to the program.
-// The order here is the order they appear in --help output.
+    .version("1.0.2");
+// ── Register commands ─────────────────────────────────────────
 (0, full_1.registerFullCommand)(program); // react-doctor full
 (0, analyze_1.registerAnalyzeCommand)(program); // react-doctor analyze
 (0, profile_1.registerProfileCommand)(program); // react-doctor profile
-(0, install_1.registerInstallCommand)(program); // react-doctor install
-// ── Usage examples shown at bottom of --help ─────────────────
+(0, dashboard_1.registerDashboardCommand)(program); // react-doctor dashboard
+// ── Usage examples ────────────────────────────────────────────
 program.addHelpText("after", `
 Examples:
-  $ react-doctor full ./my-app                       Desktop only (default)
-  $ react-doctor full ./my-app --mobile              Mobile only
-  $ react-doctor full ./my-app --desktop --mobile    Both desktop and mobile
-  $ react-doctor full ./my-app --cpu 4               Simulate slow Android device
-  $ react-doctor full ./my-app --throttle slow4g     Simulate slow 4G network
-  $ react-doctor full ./my-app --throttle 3g         Simulate 3G network
-  $ react-doctor full ./my-app --cpu 4 --throttle 3g Slow device + slow network
-  $ react-doctor full ./my-app --upload              Upload results to dashboard
+  $ react-doctor full ./my-app                          Run full diagnostic (desktop)
+  $ react-doctor full ./my-app --mobile                 Include mobile viewport
+  $ react-doctor full ./my-app --desktop --mobile       Both desktop and mobile
+  $ react-doctor full ./my-app --cpu 4                  Simulate slow Android device
+  $ react-doctor full ./my-app --throttle slow4g        Simulate slow 4G network
+  $ react-doctor full ./my-app --throttle 3g            Simulate 3G network
+  $ react-doctor full ./my-app --cpu 4 --throttle 3g   Slow device + slow network
+  $ react-doctor full ./my-app --upload                 Run + save report to dashboard
 
-  $ react-doctor analyze ./my-app                    Static code analysis only
-  $ react-doctor analyze ./my-app --full             Static + runtime + rules
+  $ react-doctor analyze ./my-app                       Static code analysis only
+  $ react-doctor analyze ./my-app --full                Static + runtime + rules
 
-  $ react-doctor profile ./my-app                    Desktop only (default)
-  $ react-doctor profile ./my-app --mobile           Mobile only
-  $ react-doctor profile ./my-app --desktop --mobile Both devices
-  $ react-doctor profile ./my-app --cpu 4            4x CPU slowdown simulation
-  $ react-doctor profile ./my-app --throttle slow4g  Simulate slow 4G network
-  $ react-doctor profile ./my-app --throttle 3g      Simulate 3G network
+  $ react-doctor profile ./my-app                       Runtime profiling only (desktop)
+  $ react-doctor profile ./my-app --mobile              Mobile viewport
+  $ react-doctor profile ./my-app --desktop --mobile    Both devices
+  $ react-doctor profile ./my-app --cpu 4               4x CPU slowdown simulation
+  $ react-doctor profile ./my-app --throttle slow4g     Simulate slow 4G network
+  $ react-doctor profile ./my-app --throttle 3g         Simulate 3G network
 
-  $ react-doctor install                       Install from GitHub into a project
-  $ react-doctor install --path ./my-app       Install into a specific folder
+  $ react-doctor dashboard                              Open dashboard (auto-starts backend)
+  $ react-doctor dashboard --port 4000                  Use custom port
 `);
 // ── Show help if called with no arguments ─────────────────────
-// Without this, calling "react-doctor" with no command just
-// exits silently, which is confusing. This prints help instead.
 if (process.argv.length < 3) {
     program.help();
 }

package/cli/src/commands/dashboard.ts

@@ -0,0 +1,179 @@
+// ─────────────────────────────────────────────────────────────
+// cli/src/commands/dashboard.ts
+//
+// react-doctor dashboard
+//
+// Opens the React Doctor dashboard in the browser.
+//
+// WHAT IT DOES:
+//   1. Checks if the backend is already running on the port
+//   2. If not — starts it automatically (same logic as --upload)
+//   3. Opens http://localhost:PORT in the default browser
+//
+// This command is the natural companion to --upload.
+// Workflow:
+//   react-doctor full ./my-app --upload   ← runs analysis + saves report
+//   react-doctor dashboard                ← opens the dashboard to view it
+//
+// Or in one shot:
+//   react-doctor full ./my-app --upload && react-doctor dashboard
+// ─────────────────────────────────────────────────────────────
+
+import { Command } from "commander";
+import path        from "path";
+import fs          from "fs";
+import axios       from "axios";
+import { spawn }   from "child_process";
+import chalk       from "chalk";
+import {
+  printBanner, printSection,
+  printDone, printFail, printInfo, spinner,
+} from "../ui";
+
+export function registerDashboardCommand(program: Command): void {
+  program
+    .command("dashboard")
+    .description("Open the React Doctor dashboard (auto-starts backend if needed)")
+    .option(
+      "--port <port>",
+      "Port the backend runs on",
+      "3000",
+    )
+    .option(
+      "--api-key <key>",
+      "API key for the backend",
+      process.env.REACT_DOCTOR_API_KEY || "react-doctor-secret-key-change-this",
+    )
+    .option("--no-banner", "Skip the banner")
+    .action(async (options) => {
+
+      if (!options.noBanner) printBanner();
+
+      const port   = options.port;
+      const apiUrl = `http://localhost:${port}`;
+
+      printSection("Dashboard");
+      printInfo("Backend URL", apiUrl);
+      console.log();
+
+      const spin = spinner("Checking backend status...");
+
+      try {
+        // ── 1. Check if backend is already up ─────────────────
+        let backendRunning = false;
+        try {
+          await axios.get(`${apiUrl}/health`, { timeout: 2000 });
+          backendRunning = true;
+        } catch {
+          backendRunning = false;
+        }
+
+        // ── 2. Start backend if not running ───────────────────
+        if (!backendRunning) {
+          spin.text = "  Backend not running — starting automatically...";
+
+          // Locate backend folder (sibling of cli/)
+          const projectRoot  = path.resolve(__dirname, "..", "..", "..");
+          const backendRoot  = path.resolve(projectRoot, "backend");
+          const backendDist  = path.join(backendRoot, "dist", "index.js");
+          const backendSrc   = path.join(backendRoot, "src",  "index.ts");
+
+          let command: string;
+          let args: string[];
+
+          if (fs.existsSync(backendDist)) {
+            command = "node";
+            args    = [backendDist];
+          } else if (fs.existsSync(backendSrc)) {
+            command = "npx";
+            args    = ["ts-node", backendSrc];
+          } else {
+            spin.fail(chalk.red("Backend not found"));
+            printFail(
+              `Could not find backend at: ${backendRoot}\n\n` +
+              `  Make sure the 'backend/' folder exists next to 'cli/'.`,
+            );
+            process.exit(1);
+          }
+
+          // Create data dir inside npm global cache for the backend DB
+          const dataDir = path.join(backendRoot, "data");
+          fs.mkdirSync(dataDir, { recursive: true });
+
+          spawn(command, args, {
+            stdio: "ignore",
+            detached: true,
+            env: {
+              ...process.env,
+              API_KEY: options.apiKey,
+              PORT:    port,
+              DB_PATH: path.join(dataDir, "reports.db"),
+            },
+            cwd: backendRoot,
+          }).unref(); // let CLI exit without killing the server
+
+          // Wait for backend to be ready (up to 15 seconds)
+          let ready   = false;
+          let retries = 0;
+          while (!ready && retries < 15) {
+            try {
+              await axios.get(`${apiUrl}/health`, { timeout: 1000 });
+              ready = true;
+            } catch {
+              await new Promise(r => setTimeout(r, 1000));
+              retries++;
+            }
+          }
+
+          if (!ready) {
+            spin.fail(chalk.red("Backend failed to start"));
+            printFail("Backend did not respond after 15 seconds.");
+            process.exit(1);
+          }
+
+          spin.succeed(chalk.green("Backend started successfully"));
+        } else {
+          spin.succeed(chalk.green("Backend already running"));
+        }
+
+        // ── 3. Open dashboard in default browser ──────────────
+        const dashboardUrl = apiUrl;
+
+        console.log();
+        printInfo("Opening", dashboardUrl);
+        console.log();
+
+        // Cross-platform browser open
+        const openCmd =
+          process.platform === "win32"  ? ["cmd",  ["/c", "start", dashboardUrl]] :
+          process.platform === "darwin" ? ["open", [dashboardUrl]] :
+                                          ["xdg-open", [dashboardUrl]];
+
+        spawn(openCmd[0] as string, openCmd[1] as string[], {
+          stdio: "ignore",
+          detached: true,
+        }).unref();
+
+        printDone(`Dashboard opened at ${chalk.cyan(dashboardUrl)}`);
+
+        // ── 4. Show quick API reference ───────────────────────
+        console.log(chalk.gray("  Available endpoints:"));
+        console.log(chalk.cyan(`    GET  ${apiUrl}/health`));
+        console.log(chalk.cyan(`    GET  ${apiUrl}/api/reports`));
+        console.log(chalk.cyan(`    GET  ${apiUrl}/api/reports/:id`));
+        console.log(chalk.cyan(`    GET  ${apiUrl}/api/reports/project/:name`));
+        console.log(chalk.cyan(`    POST ${apiUrl}/api/reports/upload`));
+        console.log();
+        console.log(
+          chalk.gray("  Tip: run ") +
+          chalk.cyan("react-doctor full ./ --upload") +
+          chalk.gray(" to add a new report.\n"),
+        );
+
+      } catch (err: any) {
+        spin.fail(chalk.red("Dashboard failed to open"));
+        console.log(chalk.red(`\n  ${err.message}\n`));
+        process.exit(1);
+      }
+    });
+}

package/cli/src/index.ts

@@ -1,35 +1,13 @@
 #!/usr/bin/env node
 // ─────────────────────────────────────────────────────────────
-// cli/src/index.ts
-//
-// The CLI entry point. This is the file that runs when the
-// user types "react-doctor" in their terminal.
-//
-// HOW IT WORKS:
-// 1. Commander.js parses the command and flags from argv
-// 2. The matching command handler is called
-// 3. The handler imports core modules and runs the pipeline
-//
-// HOW THE BINARY REGISTRATION WORKS:
-// package.json has a "bin" field:
-//   "bin": { "react-doctor": "./dist/index.js" }
-//
-// After "npm link" (dev) or "npm install" (production),
-// npm creates a symlink from the system's bin directory
-// to this file. That's what makes "react-doctor" a real
-// terminal command available anywhere.
-//
-// THE SHEBANG (#!/usr/bin/env node) on line 1:
-// This tells the OS to run this file with Node.js when
-// called directly as a script. Without it, the OS doesn't
-// know which interpreter to use.
+// cli/src/index.ts  —  CLI entry point
 // ─────────────────────────────────────────────────────────────
 
 import { Command } from "commander";
-import { registerAnalyzeCommand } from "./commands/analyze";
-import { registerProfileCommand } from "./commands/profile";
-import { registerFullCommand }    from "./commands/full";
-import { registerInstallCommand }  from "./commands/install";
+import { registerAnalyzeCommand }   from "./commands/analyze";
+import { registerProfileCommand }   from "./commands/profile";
+import { registerFullCommand }      from "./commands/full";
+import { registerDashboardCommand } from "./commands/dashboard";
 
 const program = new Command();
 
@@ -37,46 +15,41 @@ const program = new Command();
 program
   .name("react-doctor")
   .description("React performance analyzer — static analysis + runtime profiling + smart suggestions")
-  .version("1.0.0");
+  .version("1.0.2");
 
-// ── Register all commands ─────────────────────────────────────
-// Each function adds one command to the program.
-// The order here is the order they appear in --help output.
+// ── Register commands ─────────────────────────────────────────
+registerFullCommand(program);       // react-doctor full
+registerAnalyzeCommand(program);    // react-doctor analyze
+registerProfileCommand(program);    // react-doctor profile
+registerDashboardCommand(program);  // react-doctor dashboard
 
-registerFullCommand(program);      // react-doctor full
-registerAnalyzeCommand(program);   // react-doctor analyze
-registerProfileCommand(program);   // react-doctor profile
-registerInstallCommand(program);   // react-doctor install
-
-// ── Usage examples shown at bottom of --help ─────────────────
+// ── Usage examples ────────────────────────────────────────────
 program.addHelpText("after", `
 Examples:
-  $ react-doctor full ./my-app                       Desktop only (default)
-  $ react-doctor full ./my-app --mobile              Mobile only
-  $ react-doctor full ./my-app --desktop --mobile    Both desktop and mobile
-  $ react-doctor full ./my-app --cpu 4               Simulate slow Android device
-  $ react-doctor full ./my-app --throttle slow4g     Simulate slow 4G network
-  $ react-doctor full ./my-app --throttle 3g         Simulate 3G network
-  $ react-doctor full ./my-app --cpu 4 --throttle 3g Slow device + slow network
-  $ react-doctor full ./my-app --upload              Upload results to dashboard
-
-  $ react-doctor analyze ./my-app                    Static code analysis only
-  $ react-doctor analyze ./my-app --full             Static + runtime + rules
-
-  $ react-doctor profile ./my-app                    Desktop only (default)
-  $ react-doctor profile ./my-app --mobile           Mobile only
-  $ react-doctor profile ./my-app --desktop --mobile Both devices
-  $ react-doctor profile ./my-app --cpu 4            4x CPU slowdown simulation
-  $ react-doctor profile ./my-app --throttle slow4g  Simulate slow 4G network
-  $ react-doctor profile ./my-app --throttle 3g      Simulate 3G network
-
-  $ react-doctor install                       Install from GitHub into a project
-  $ react-doctor install --path ./my-app       Install into a specific folder
+  $ react-doctor full ./my-app                          Run full diagnostic (desktop)
+  $ react-doctor full ./my-app --mobile                 Include mobile viewport
+  $ react-doctor full ./my-app --desktop --mobile       Both desktop and mobile
+  $ react-doctor full ./my-app --cpu 4                  Simulate slow Android device
+  $ react-doctor full ./my-app --throttle slow4g        Simulate slow 4G network
+  $ react-doctor full ./my-app --throttle 3g            Simulate 3G network
+  $ react-doctor full ./my-app --cpu 4 --throttle 3g   Slow device + slow network
+  $ react-doctor full ./my-app --upload                 Run + save report to dashboard
+
+  $ react-doctor analyze ./my-app                       Static code analysis only
+  $ react-doctor analyze ./my-app --full                Static + runtime + rules
+
+  $ react-doctor profile ./my-app                       Runtime profiling only (desktop)
+  $ react-doctor profile ./my-app --mobile              Mobile viewport
+  $ react-doctor profile ./my-app --desktop --mobile    Both devices
+  $ react-doctor profile ./my-app --cpu 4               4x CPU slowdown simulation
+  $ react-doctor profile ./my-app --throttle slow4g     Simulate slow 4G network
+  $ react-doctor profile ./my-app --throttle 3g         Simulate 3G network
+
+  $ react-doctor dashboard                              Open dashboard (auto-starts backend)
+  $ react-doctor dashboard --port 4000                  Use custom port
 `);
 
 // ── Show help if called with no arguments ─────────────────────
-// Without this, calling "react-doctor" with no command just
-// exits silently, which is confusing. This prints help instead.
 if (process.argv.length < 3) {
   program.help();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-doctor-cli-dev",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "React performance analyzer with static analysis, runtime profiling, rule engine, and dashboard upload",
   "main": "index.js",
   "type": "commonjs",