@progen-labs/spectra 0.4.0 → 0.5.0

package/README.md

@@ -11,10 +11,12 @@ exact function, file and line, the evidence, and a suggested fix.
 Deep component-level attribution for **React, Next.js, Vue and Angular** (component names, render counts
 and per-component render/change-detection time; source files too, where the framework exposes them). For
 **Svelte and any other build**, a source-mapped generic profile still pinpoints the slow files and
-functions. A [Progen Labs](https://github.com/progen-labs) project — open source, non-profit, no
-telemetry, no account required.
+functions. The framework is detected in the page itself, so it is right wherever you start Spectra from.
+Apps behind a login work too: Spectra [signs in first](#behind-a-login), with every kind of login. A
+[Progen Labs](https://github.com/progen-labs) project — independent, open source, no telemetry, no account
+required.
 
-**Watch the two-minute demo:** [progen-labs.github.io/website/#spectra/demo](https://progen-labs.github.io/website/#spectra/demo).
+**Watch the demo (2½ minutes):** [progen-labs.github.io/website/#spectra/demo](https://progen-labs.github.io/website/#spectra/demo).
 
 **Documentation:** the full guide, with annotated screenshots of every screen, is at
 [progen-labs.github.io/website](https://progen-labs.github.io/website/#spectra/docs/introduction).
@@ -53,7 +55,7 @@ With no `--url`, Spectra:
 Automation: 8/8 golden paths passed.
 ```
 
-Then open the visual dashboard — ranked culprits, React re-renders, long tasks, the golden-path matrix,
+Then open the visual dashboard — ranked culprits, component re-renders, long tasks, the golden-path matrix,
 **PDF export** and **commit-to-commit compare**:
 
 ```bash
@@ -87,13 +89,47 @@ spectra --version
 | `--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}` |
+| `--login-url <url>`, `--login-user <name>` | Sign in first: the login page and the username; the password comes from `SPECTRA_LOGIN_PASSWORD` (see [Behind a login](#behind-a-login)) |
+| `--login <method>` | `form`, `link`, `http`, `token` or `manual` (you sign in in the Chrome window); guessed when left out |
 | `--quick` | One page-load profile instead of the golden-path suite: the fast loop |
 | `--runs <n>` | Record n times and report the median (with `--quick` or `--mode`) |
 | `--mode live\|load` | Classic single-page profile instead of the golden-path suite |
 | `--json` | Print a machine-readable result on stdout (tables go to stderr) |
 | `--out <file>` | Also write that result to a file (an input for `compare`) |
-| `--config <file>` | Budgets file (default: `spectra.config.json` in your project) |
+| `--config <file>` | Budgets and sign-in file (default: `spectra.config.json` in your project) |
+
+## Behind a login
+
+Most production frontends sit behind a login, and the Chrome Spectra launches starts signed out. Tell
+Spectra how your app signs in and it signs in before it records, so the login never shows up in a
+measurement:
+
+| Method | For |
+| --- | --- |
+| **Login form** (`form`) | A username and password on your app's login page or its identity provider (OAuth, OpenID Connect, SAML): one or two steps, forms that render late, in iframes or web components, behind a "Sign in" button, with **authenticator codes** from a TOTP secret |
+| **I'll sign in myself** (`manual`) | SMS or email codes, push approvals, passkeys, CAPTCHAs: Chrome opens on the login page and Spectra waits for you |
+| **Browser prompt** (`http`) | HTTP Basic or Digest, common on staging servers |
+| **Token or cookie** (`token`) | A header (sent only to your app's origin), cookies or localStorage entries |
+| **Sign-in link** (`link`) | A URL that signs in by itself, such as a dev-only auto-login |
+
+In the dashboard, turn on **My app needs a sign-in** under **Page to profile**. On the command line:
+
+```bash
+SPECTRA_LOGIN_PASSWORD="$TEST_PASSWORD" npx spectra performance --login-url http://localhost:3000/login --login-user demo@example.com
+npx spectra performance --login manual --login-url https://staging.example.com/login
+```
+
+Or once, for every command, the VS Code extension, the MCP server and `spectra fix`, in `spectra.config.json`:
+
+```json
+{ "signIn": { "method": "form", "url": "http://localhost:3000/login", "username": "demo@example.com" } }
+```
+
+Secrets come only from the dashboard or the environment (`SPECTRA_LOGIN_PASSWORD`, `SPECTRA_LOGIN_TOTP_SECRET`,
+`SPECTRA_LOGIN_HEADER`, `SPECTRA_LOGIN_COOKIES`, `SPECTRA_LOGIN_STORAGE`). They stay in memory: never written
+to disk, a report, a log or an error message, and `spectra.config.json` refuses them. Spectra never solves
+CAPTCHAs. Use a test account where you can. See
+[Signing in](https://progen-labs.github.io/website/#spectra/docs/signing-in), with a short video.
 
 ## Measure, change, verify
 
@@ -235,12 +271,13 @@ The harness, not the agent, makes every decision:
 - **Proof.** The change is kept only if `spectra compare` says *improved* with medium or high confidence and no new
   critical finding; with low confidence it measures again.
 - **A record.** Each kept commit carries its evidence; `.spectra/fix/<time>/report.md` summarises the session, and a
-  history skips findings that failed before.
+  history skips findings that failed before. A finding that an earlier kept fix already cleared is skipped too.
 
 By default the agent is Claude Code in headless mode, allowed only to read and edit files (no shell, no web, no MCP),
 with a spending cap per finding. A test bench (`npm run bench`) checks the harness's decisions in CI: a real fix is
 kept, a "faster" change that breaks the page is caught, a cosmetic change doesn't count, and an edit to
-`package.json` is refused. See [the AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness).
+`package.json` is refused. With Claude Code on the demo app, it kept two of three fixes and cut JavaScript CPU time
+from 1.51 s to 82.5 ms (−95%) for $0.44. See [the AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness).
 
 ## In VS Code
 
@@ -267,7 +304,8 @@ See the [VS Code guide](https://progen-labs.github.io/website/#spectra/docs/vsco
 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.
+searches and navigations are fair game. If a session expires and the app sends Spectra back to its login page,
+Spectra signs in again.
 
 ## Where results go
 
@@ -298,4 +336,15 @@ and report generation work.
 
 ## License
 
-MIT © Progen Labs
+MIT © 2026 Sourav Debnath (Progen Labs)
+
+<p align="center">
+  <a href="https://progen-labs.github.io/website/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://progen-labs.github.io/website/brand/progen-seed-mark.svg">
+      <img alt="Progen Labs" src="https://progen-labs.github.io/website/brand/progen-seed-mark-light.svg" height="72">
+    </picture>
+  </a>
+  <br>
+  <sub>Spectra is a <a href="https://progen-labs.github.io/website/">Progen Labs</a> project: independent, open source, always free.</sub>
+</p>

package/bin/spectra.js

@@ -21,6 +21,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bootDevServer } from '../server/explore/boot.js';
 import { detectFramework } from '../server/framework.js';
+import { SIGN_IN_HELP } from '../server/signin.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(here, '..');
@@ -65,7 +66,8 @@ performance options:
   --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}"
+
+${SIGN_IN_HELP}
 
 quick single-page profile (opt in with --quick, --mode or --scenario):
   --quick               One page-load profile (about 15 s): the fast loop
@@ -80,7 +82,7 @@ output and checks (any performance run):
   --json                Print a machine-readable result on stdout (progress and
                         tables go to stderr)
   --out <file>          Also write that result to a file (input for compare)
-  --config <file>       Budgets file (default: spectra.config.json in the project)
+  --config <file>       Budgets and sign-in file (default: spectra.config.json)
 
 compare options:
   <before> <after>      Each: a report id, a report file, a --out result file,
@@ -88,8 +90,9 @@ compare options:
   --json, --out <file>  As above
   --fail-on-regression  Exit with code 2 when a key metric got worse
 
-Budgets (spectra.config.json in your project root):
-  { "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 } }
+Budgets and sign-in (spectra.config.json in your project root):
+  { "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 },
+    "signIn": { "method": "form", "url": "http://localhost:3000/login", "username": "me@example.com" } }
 
 Exit codes: 0 done · 1 could not run · 2 over budget / regression
 
@@ -102,6 +105,7 @@ Examples:
   spectra compare before.json after.json           # did the change help?
   spectra fix --max-fixes 3                        # let an agent fix them, verified
   spectra performance --json | jq .summary         # pipe it anywhere
+  SPECTRA_LOGIN_PASSWORD=… spectra performance --login-url http://localhost:3000/login --login-user me@example.com
 `;
 
 // What a terminate signal must clean up: the running script and a dev server