@progen-labs/spectra 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sourav Debnath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction rights, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @progen-labs/spectra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Find out which file, which function and which component makes your frontend slow — automatically.**
+
+Spectra is a CLI and dashboard that profiles a frontend build through the Chrome DevTools Protocol
+(tracing + CPU sampling) plus a small in-page probe for component re-renders and Web Vitals. Run one
+command and it starts your dev server, auto-discovers the actionable elements on the page, drives a set
+of **golden-path journeys**, records each one, and reports a ranked list of culprits — each with the
+exact function, file and line, the evidence, and a suggested fix.
+
+Works with **React, Vue, Svelte, Angular and Next.js** builds (component-level attribution is deepest on
+React today; a source-mapped generic profile covers the rest). A [Progen Labs](https://github.com/progen-labs)
+project — open source, non-profit, no telemetry, no account required.
+
+## Install
+
+```bash
+npm install --save-dev @progen-labs/spectra
+```
+
+Requirements: **Node 18+** and a local **Chrome / Chromium / Edge** (Spectra drives your installed
+browser; it does not download one). If it can't find Chrome, set `CHROME_PATH` to the executable.
+
+## Quick start
+
+From the root of your project:
+
+```bash
+npx spectra performance
+```
+
+With no `--url`, Spectra:
+
+1. detects your framework and starts your dev server (`npm run dev`/`start`/`serve`),
+2. records a baseline page load,
+3. auto-discovers the actionable elements (links, buttons, inputs, forms),
+4. synthesizes and runs **golden-path journeys** — safely (see below),
+5. prints a performance matrix and saves a report per journey, then stops the server.
+
+```
+#  Golden path            Result    TBT    LCP  LongT  Top finding
+—  Initial page load      PASS      0ms  128ms      0  [warning] main chunk served uncompressed
+1  Click "Pricing"        PASS      0ms      —      0  [warning] Large DOM: 2,139 nodes
+2  Click "Folders"        PASS      0ms      —      0  [critical] TreeNode re-rendered 1100× (96% wasted)
+...
+Automation: 8/8 golden paths passed.
+```
+
+Then open the visual dashboard — ranked culprits, React re-renders, long tasks, the golden-path matrix,
+**PDF export** and **commit-to-commit compare**:
+
+```bash
+npx spectra dashboard
+```
+
+## Commands
+
+```
+spectra performance [options]   Golden-path evaluation (default)
+spectra dashboard [--port N]    Open the dashboard UI
+spectra --help                  Full option list
+spectra --version
+```
+
+**`performance` options**
+
+| Option | Description |
+| --- | --- |
+| `--url <page>` | Evaluate an already-running page; skips self-boot |
+| `--paths <n>` | Max golden paths to run (default 12) |
+| `--command "<cmd>"` | Override the dev-server command |
+| `--boot-timeout <s>` | How long to wait for the dev server (default 60) |
+| `--headed` | Show the browser window |
+| `--sign-in <url>` | Sign-in URL template, e.g. `http://host/login/?redirect={url}` |
+| `--mode live\|load` | Classic single-page profile instead of the golden-path suite |
+
+## Safe by default
+
+Auto-exploration never triggers destructive actions. Spectra detects controls that would mutate state —
+anything labelled delete / pay / checkout / log out, logout links, and `POST`/`PUT`/`DELETE` form submits —
+and **skips** them unless you explicitly allow them. Form fields are filled with synthetic values; GET
+searches and navigations are fair game.
+
+## Where results go
+
+Reports are written to `.spectra/reports/` in your project (add it to `.gitignore`). Each golden path is a
+full report you can open in `spectra dashboard`, export to PDF, or compare against another commit.
+
+## How it works
+
+Spectra launches Chrome via `puppeteer-core`, records a CDP trace + CPU profile, and injects a probe that
+tracks component renders, slow interactions and Web Vitals. It maps sampled frames back to your source
+through source maps (and bundler markers as a fallback), then ranks the files, functions and components
+that cost the most main-thread time. See the
+[deep-dive docs](https://github.com/progen-labs/spectra/blob/main/DOCS.md) for how capture, correlation
+and report generation work.
+
+## License
+
+MIT © Progen Labs

package/bin/spectra.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Spectra CLI — a Progen Labs project.
+ *
+ *   spectra performance [--url <page>] [profiler options]   profile a frontend
+ *   spectra dashboard                                        open the dashboard UI
+ *   spectra --help                                           show this help
+ *   spectra --version                                        print the version
+ *
+ * When Spectra is installed in a project, it profiles THAT project: reports are
+ * written under the current working directory (.spectra/reports) and the project
+ * root is used for source lookup, unless the matching PERF_* env var overrides it.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bootDevServer } from '../server/explore/boot.js';
+import { detectFramework } from '../server/framework.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(here, '..');
+const pkg = JSON.parse(
+  readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'),
+);
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+const rest = argv.slice(1);
+
+const HELP = `
+Spectra ${pkg.version} — frontend performance profiler (Progen Labs)
+
+Usage:
+  spectra performance [options]   Profile a frontend build and report the culprits
+  spectra dashboard               Open the Spectra dashboard UI
+  spectra --help, -h              Show this help
+  spectra --version, -v           Print the version
+
+Run it from inside your project. With no --url, Spectra detects the framework,
+starts your dev server (npm run dev/start/serve), evaluates it, then shuts it
+down. By default it records a baseline page load, auto-discovers the actionable
+elements, synthesizes golden-path journeys, runs them (safe actions only), and
+prints a performance matrix. Every path is saved as a report you can open in
+the dashboard. Reports go to .spectra/reports in the current directory.
+
+performance options:
+  --url <page>          Evaluate an already-running page; skips self-boot
+  --paths <n>           Max golden paths to run (default 12)
+  --command "<cmd>"     Override the dev-server command (default: your npm dev script)
+  --boot-timeout <s>    How long to wait for the dev server (default 60)
+  --headed              Show the browser window
+  --sign-in <url>       Sign-in URL template, e.g. "http://host/login/?redirect={url}"
+
+classic single-page profile (opt in with --mode or --scenario):
+  --mode live|load      Live session or page-load recording
+  --duration <seconds>  Live recording length (default 8)
+  --throttle <n>        CPU throttle multiplier (default 1)
+  --scenario <file.mjs> Script a live session: export default async page => {…}
+  --save-trace          Keep the raw Chrome trace alongside the report
+
+Examples:
+  spectra performance                              # self-boot + golden-path suite
+  spectra performance --paths 8                    # cap the suite at 8 journeys
+  spectra performance --url http://localhost:3000/ # evaluate a running server
+  spectra performance --mode load                  # classic single page-load profile
+`;
+
+function runNodeAsync(scriptRelPath, args, extraEnv = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [path.join(PKG_ROOT, scriptRelPath), ...args],
+      {
+        cwd: PKG_ROOT,
+        stdio: 'inherit',
+        env: { ...process.env, ...extraEnv },
+      },
+    );
+    child.on('exit', code => resolve(code ?? 0));
+    child.on('error', reject);
+  });
+}
+
+/** Pull `--name value` out of an argv array, returning the value and the rest. */
+function takeOption(args, name) {
+  const i = args.indexOf(`--${name}`);
+  if (i === -1) return { value: undefined, rest: args };
+  const copy = args.slice();
+  const [, value] = copy.splice(i, 2);
+  return { value, rest: copy };
+}
+
+/**
+ * Default the profiled project and the reports location to the user's current
+ * directory, so an installed Spectra profiles the host project and writes
+ * reports there rather than inside node_modules. Explicit PERF_* vars win.
+ */
+function projectEnv() {
+  const cwd = process.cwd();
+  const env = {};
+  if (!process.env.PERF_FRONTEND_DIR && !process.env.FRONTEND_DIR) {
+    env.PERF_FRONTEND_DIR = cwd;
+  }
+  if (!process.env.PERF_REPORTS_DIR) {
+    env.PERF_REPORTS_DIR = path.join(cwd, '.spectra', 'reports');
+  }
+  return env;
+}
+
+async function runProfile() {
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(HELP);
+    return 0;
+  }
+  const env = projectEnv();
+
+  // Golden-path evaluation is the default. --mode/--scenario opt into the
+  // classic single-page profile instead.
+  const classic = rest.includes('--mode') || rest.includes('--scenario');
+  const script = classic ? 'server/cli.js' : 'server/explore/evaluate-cli.js';
+
+  // An explicit --url means the server is already running: run against it.
+  if (rest.includes('--url')) {
+    return runNodeAsync(script, rest, env);
+  }
+
+  // No --url: self-boot the target project's own dev server, run, stop.
+  const cwd = process.cwd();
+  const { value: command, rest: afterCmd } = takeOption(rest, 'command');
+  const { value: bootTimeout, rest: profileArgs } = takeOption(afterCmd, 'boot-timeout');
+  const fw = detectFramework(cwd);
+  const label =
+    fw.framework !== 'unknown' ? `${fw.framework}/${fw.bundler}` : fw.bundler;
+  // Status goes to stderr so it never mixes with the report on stdout.
+  console.error(
+    `spectra: no --url given — starting the ${label} dev server in ${cwd} …`,
+  );
+
+  let server;
+  try {
+    server = await bootDevServer({
+      root: cwd,
+      command,
+      timeoutMs: bootTimeout ? Number(bootTimeout) * 1000 : 60_000,
+    });
+  } catch (err) {
+    console.error(`spectra: ${err.message}`);
+    return 1;
+  }
+  console.error(`spectra: dev server ready at ${server.url} — profiling …\n`);
+
+  let code = 1;
+  try {
+    code = await runNodeAsync(
+      script,
+      [...profileArgs, '--url', server.url],
+      env,
+    );
+  } finally {
+    await server.stop();
+    console.error('\nspectra: stopped the dev server.');
+  }
+  return code;
+}
+
+function runDashboard() {
+  // Standalone server: serves the prebuilt dashboard and the backend API, so an
+  // installed Spectra needs no dev toolchain. projectEnv() points it at this
+  // project's reports and source roots.
+  const child = spawn(
+    process.execPath,
+    [path.join(PKG_ROOT, 'server/dashboard.js'), ...rest],
+    {
+      cwd: PKG_ROOT,
+      stdio: 'inherit',
+      env: { ...process.env, ...projectEnv() },
+    },
+  );
+  child.on('exit', code => process.exit(code ?? 0));
+  child.on('error', err => {
+    console.error(`spectra: failed to start the dashboard — ${err.message}`);
+    process.exit(1);
+  });
+}
+
+switch (command) {
+  case 'performance':
+  case 'perf':
+    runProfile()
+      .then(code => process.exit(code ?? 0))
+      .catch(err => {
+        console.error(`spectra: ${err.message}`);
+        process.exit(1);
+      });
+    break;
+  case 'dashboard':
+  case 'ui':
+    runDashboard();
+    break;
+  case '--version':
+  case '-v':
+    console.log(pkg.version);
+    break;
+  case undefined:
+  case '--help':
+  case '-h':
+  case 'help':
+    console.log(HELP);
+    break;
+  default:
+    console.error(`spectra: unknown command "${command}"`);
+    console.log(HELP);
+    process.exit(1);
+}