Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,9 @@ Azure, `git push`, `npm publish`.
`package-lock.json` in sync. TypeScript strict, ESM only, `src/` uses no Node APIs (`types: []`).
8. **Telemetry** stays disclosed (console notice, `TELEMETRY.md`, both READMEs, CHANGELOG), sends no page text
unless the app opts in, keeps every opt-out (`telemetry: false`, `?genclass=no-telemetry`, localStorage, GPC) and
never feeds a decision. Widening what is sent needs the owner's OK.
never feeds a decision. Widening what is sent needs the owner's OK. Owner, 2026-11-20: the `genclass` command's
setup turns interaction analytics on (`init --analytics`, said before it writes; `setup --no-analytics` and
`genclass analytics off` are the opt-outs and need no Pro); the runtime's own default stays off.
9. **Publish only through the release workflows**: `.github/workflows/release.yml` on a `v*` tag whose version
equals `packages/runtime/package.json`; `.github/workflows/release-mcp.yml` on a `mcp-v*` tag for
`@genclass/mcp` (its first version is published once by the owner from the workflow's tarball, because npm sets up
Expand Down
4 changes: 3 additions & 1 deletion PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,9 @@ object; version 0.2.1 sent from those hosts by default, by mistake, fixed in 0.2
function wrapped with `protect()`, on the decisions about what that function caused. A name that looks like data
(an e-mail address, a URL, 4 or more digits in a row, a long hex id) is sent as `[redacted]`.
- **How visitors use the site, only if the website's developer turned on interaction analytics** (`analytics: true`
with a token; from runtime 0.3.0-beta.1, off by default): for each page view, the page's path (as above), how long
with a token; from runtime 0.3.0-beta.1, off by default in the runtime; the `genclass` command's setup, from
genclass 0.3.14, turns them on for an app it sets up unless the developer passes `--no-analytics`, and says so
before it writes anything): for each page view, the page's path (as above), how long
the page was visible and in use (at most 30 seconds after the last mouse, key, scroll or touch input), how far down
the page the visitor scrolled (25, 50, 75 or 100 %), and how many times each element was clicked, clicked 3 or more
times within a second, or clicked without anything changing on the page. An element is named from the page's code
Expand Down
12 changes: 11 additions & 1 deletion docs/runtime/ANALYTICS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,15 @@ whatever its plan, and leaves them out of the stats it serves to a plan without
(`telemetry-worker/src/dashboard.ts` stripAnalytics), so an upgrade shows what was counted before it. Nothing in the
runtime changes with the plan, and a collector you host yourself shows them to everyone.

**The `genclass` command's setup turns them on (owner, 2026-11-20).** "Turn on analytics in genclass setup by
default so they can see visitors": from genclass 0.3.14 the setup's runtime step hands the runtime CLI's `init` the
new `--analytics` flag, which writes `analytics: true` next to the app's token (`data-analytics="on"` on a script
tag, `analytics=on` in the Astro meta line). The step's sentence and init's lines say what is counted, the consent
advice of section 5 and the switch before anything is written; `genclass setup --no-analytics` leaves them out and
`genclass analytics on` / `off` changes it later (`off` without Pro, like every opt-out). The runtime's own default
stays off (`init` without the flag, the script tag, `GenClass.init()`), and an app set up before that release is not
changed. Section 5 still holds: an app with visitors in the EU, the EEA or the UK starts analytics after consent.

**Where the genclass.dev paths are now.** Since 2026-10-18 the website and its admin (`site/`) live in the private
repository `genclass-dev/genclass-site`, which includes this repository as its `lib/` submodule. The paths `site/...`
in sections 6, 7 and 10 (`site/src/admin.js`, `site/src/worker.js`, `site/src/pages/privacy.html`) are in that
Expand Down Expand Up @@ -228,7 +237,8 @@ GenClass.init({ token: "gc_…", analytics: true });
```

- **Default: off.** It records nothing unless the app sets `analytics: true` (also `data-analytics="on"` on the
script tag, `<meta name="genclass" content="analytics=on">`, `window.GENCLASS_CONFIG.analytics`).
script tag, `<meta name="genclass" content="analytics=on">`, `window.GENCLASS_CONFIG.analytics`). `init
--analytics` writes it; the `genclass` command's setup passes that flag unless `--no-analytics` (2026-11-20).
- **Needs telemetry and a token.** Analytics only feed a dashboard, so they are sent only on batches that carry the
app's token, or to a custom `telemetry.endpoint`. Without either, `analytics: true` warns once and stays off.
- **After consent.** `rt.analytics.start()` turns it on later, `rt.analytics.stop()` turns it off and drops the
Expand Down
4 changes: 3 additions & 1 deletion docs/runtime/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,9 @@ Every telemetry opt-out and Global Privacy Control turn them off; without a toke
`analytics: true` warns once and records nothing. They run in a lazy chunk (`dist/analytics/index.js`), outside the
event log: nothing reaches a situation, a decision or the model. `rt.analytics.start()` / `stop()` turn them on and
off later (consent; `stop()` drops the counts not sent yet and removes the visit entry). Also `data-analytics="on"`, `analytics=on` in the meta
tag, `window.GENCLASS_CONFIG.analytics`. Schema: [TELEMETRY.md](../../packages/runtime/TELEMETRY.md#interaction-analytics).
tag, `window.GENCLASS_CONFIG.analytics`; `init --analytics` writes the option and `init --no-analytics` takes it out
(from the release after 0.3.0-beta.7), and the `genclass` command's setup turns it on unless it is run with
`--no-analytics` (genclass 0.3.14). Schema: [TELEMETRY.md](../../packages/runtime/TELEMETRY.md#interaction-analytics).
With the script tag, a chunk that does not load warns once per load (`[GenClass] analytics: <url> (@genclass/runtime
<version>) did not load; nothing is recorded. ...`, `reason: "error"`), and a chunk of another release than the tag
warns once with both versions. `0.2.x` (npm's `latest` until 0.3.0)
Expand Down
2 changes: 2 additions & 0 deletions docs/runtime/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ Content-Security-Policy (`next.config` headers, a proxy or middleware, a `<meta
| `--no-token` | init | no token and no dashboard; genclass.dev is not contacted (the package manager still runs unless `--no-install`; add a token later at [genclass.dev/start](https://genclass.dev/start)) |
| `--no-telemetry` | init | turn off GenClass's anonymous diagnostics; implies `--no-token` (a dashboard only gets data while telemetry is on) |
| `--telemetry` | init | undo `--no-telemetry`: back to the default (on, but never from local hosts); init takes the opt-out out and writes no telemetry option of its own |
| `--analytics` | init | turn on [interaction analytics](../../packages/runtime/TELEMETRY.md#interaction-analytics) for the app's dashboard (off by default; they need the app's token and telemetry on; from the release after 0.3.0-beta.7). Where the law asks for a visitor's consent to analytics (the EU, EEA and UK), leave them off and call `runtime.analytics.start()` once the visitor agrees |
| `--no-analytics` | init | undo `--analytics`: init takes the option out again |
| `--model-url <url>` | init | use a self-hosted model directory (made with `fetch-model`), with ONNX Runtime from `<url>ort/` |
| `--sink <name>` | init | also send findings to your own side: `console-json`, `console-json:noevidence` or `webhook:<url>`; repeat the flag or comma-separate ([SINKS.md](SINKS.md)) |
| `--yes`, `-y` | both | apply without asking |
Expand Down
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

19 changes: 19 additions & 0 deletions packages/cli/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 0.3.14

- **Setup turns visitor analytics on.** The runtime step now writes `analytics: true` next to the app's token, so an
app set up with `genclass` counts its visitors from the first deploy and `genclass analytics` and the dashboard's
Visitors have something to show: page views, time on a page, scroll depth, clicks per element (named from markup,
never its text), where visits come from and the device class. No cookies; one `localStorage` entry holds the visit;
nothing is counted on localhost, and a visitor's Global Privacy Control turns it off. The step's sentence says so,
the change is shown before it is written, and the lines under it say what is counted, how to turn it off, and that
where the law asks for a visitor's consent to analytics (the EU, EEA and UK) the app starts them with
`runtime.analytics.start()` once the visitor agrees. `genclass setup --no-analytics` adds GenClass without them.
An app set up before this release is not changed.
- **`genclass analytics on`** and **`genclass analytics off`**: the switch for this folder's app, any time. It changes
that one option in what the setup added, shows the change first, and sends nothing. `off` (and
`genclass init --no-analytics`) works without Pro and signed out, like every opt-out.
- `genclass analytics` and the dashboard's Visitors line say why no visit is counted: analytics are off in this app
(with the command that turns them on), or on and waiting for the deployed site's first visitors.
- `genclass status` names `npx genclass init --analytics` for an app without GenClass: the command that does what the
step says.

## 0.3.13

- **`genclass site <address>`**: the site check, which used to be on genclass.dev, now runs from the command only.
Expand Down
7 changes: 4 additions & 3 deletions packages/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ it off). After that you type `genclass`, and every screen says `genclass` instea
|---|---|---|
| Account | Opens genclass.dev in your browser; you approve a short code there. | A session file in your user config folder. Nothing is typed in the terminal. |
| Pro | Right after the sign-in: Pro's 3-day free trial opens in your browser, and the command waits for it. Every step after it needs Pro. | Nothing in your project. The payment is on Stripe's page; the command never sees a card. |
| Runtime | Adds GenClass to the app: one import (or script tag) and the package. It watches the page in your users' browsers for lost edits, double submits and old data shown over new, and only reports, to the console and your dashboard. Nothing is drawn on your pages. | Your entry file and `package.json`; you see the change first. `genclass remove` undoes it. |
| Runtime | Adds GenClass to the app: one import (or script tag) and the package. It watches the page in your users' browsers for lost edits, double submits and old data shown over new, and only reports, to the console and your dashboard. Nothing is drawn on your pages. Visitor analytics are on too (`analytics: true` next to the app's token): page views, time on a page, scroll depth, clicks per element (never its text), where visits come from and the device class, with no cookies and nothing from localhost. `npx genclass setup --no-analytics` leaves them off, `npx genclass analytics off` turns them off later. Where the law asks for a visitor's consent to analytics (the EU, EEA and UK), set up without them and call `runtime.analytics.start()` once the visitor agrees. | Your entry file and `package.json`; you see the change first. `genclass remove` undoes it. |
| App plan | Once the app is in your account, its plan page opens in your browser once: Continue with Pro. Pro covers up to 3 apps; more apps come with Enterprise, by email. | Nothing in your project. |
| Dashboard | Waits for your live site to be opened once. GenClass sends nothing from localhost. | Nothing. |
| Test workflow | Runs your Playwright tests once more per pull request with slow and reordered responses. | One new file, `.github/workflows/genclass.yml`, which you commit. |
Expand Down Expand Up @@ -172,7 +172,7 @@ Each part of the browser dashboard has its own view, short first, `--all` for ev
| | |
|---|---|
| `npx genclass problems` | what was found, by kind and by page, the measured visual checks, what GenClass stopped on the visitor's screen, how it compares with the period before |
| `npx genclass analytics` | visitors: visits, page views, time on a page, where people come from, devices and countries, what gets clicked again and again. One part in full: `analytics pages`, `sources`, `devices`, `clicks`, `paths`, `funnels` |
| `npx genclass analytics` | visitors: visits, page views, time on a page, where people come from, devices and countries, what gets clicked again and again. One part in full: `analytics pages`, `sources`, `devices`, `clicks`, `paths`, `funnels`. `analytics on` and `analytics off` turn the counting on or off in this folder's app (the setup turns it on) |
| `npx genclass events` | the latest events one per line: when, kind, how sure the model was, the page, and what GenClass did |
| `npx genclass health` | how GenClass itself runs on your pages: model loads, where it ran, decision time, what was not checked, runtime versions |
| `npx genclass report` | the period as Markdown, to paste or pipe (`--out report.md` writes a file) |
Expand Down Expand Up @@ -280,11 +280,12 @@ first step and the agent prompt, with the model's own ideas and website designs.
| | |
|---|---|
| `npx genclass` | where the project stands; on a terminal, the next step, then the home |
| `npx genclass setup` | the guided setup (`--yes`: no questions) |
| `npx genclass setup` | the guided setup (`--yes`: no questions; `--no-analytics`: without visitor analytics) |
| `npx genclass status` | what is done and what is next (`--all`: every part; `--json`) |
| `npx genclass dashboard` | your app in the terminal (`--open` the browser dashboard) |
| `npx genclass problems` | every problem found, by kind and page, and what GenClass did |
| `npx genclass analytics [part]` | visitors; parts: `pages`, `sources`, `devices`, `clicks`, `paths`, `funnels` |
| `npx genclass analytics on` \| `off` | count this app's visitors, or stop (changes one option in your code; `off` needs no Pro) |
| `npx genclass events` | the latest events, one per line |
| `npx genclass health` | how GenClass itself runs on your pages |
| `npx genclass report` | the period as Markdown (`--out <file>`) |
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "genclass",
"version": "0.3.13",
"version": "0.3.14",
"description": "GenClass CLI: one command that sets GenClass up, shows your app in the terminal (problems, analytics, events), hands problems to your coding agent, answers questions about your app and tells you what it is missing.",
"type": "module",
"license": "Apache-2.0",
Expand Down
41 changes: 39 additions & 2 deletions packages/cli/src/actions.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,10 @@ async function waitForPlan(offer, o = {}, deps = {}) {
* The arguments the runtime step hands to the runtime CLI's `init` (a fresh project) or `connect` (added, not in
* the account yet). `init` gets --no-devtools: GenClass set up by this command draws nothing on a page, not on the
* deployed site (it never did) and not on localhost either (the developer overlay is left out). What it finds goes
* to the browser console, the dashboard and `genclass dashboard`.
* to the browser console, the dashboard and `genclass dashboard`. It also gets --analytics (the owner's call,
* 2026-11-20): an app set up by this command counts its visitors from the first deploy, so `genclass analytics` and
* the dashboard's Visitors have something to show; the step's sentence and init's own lines say so before anything
* is written, and `setup --no-analytics` (o.noAnalytics) leaves it out.
*/
export function runtimeArgs(state, o = {}) {
const connect = state.steps.find((s) => s.id === "runtime")?.run === "npx genclass connect";
Expand All @@ -296,7 +299,7 @@ export function runtimeArgs(state, o = {}) {
// account this is, and the account is the one signed in. init gets --in-account (signed in one step earlier, so
// the app goes into that account without asking again), --no-devtools and --brief (the walk has its own header,
// so init says the same things in a few lines)
return connect ? { cmd: "connect", args } : { cmd: "init", args: [...args, ...(state.signedIn ? ["--in-account"] : []), "--no-devtools", "--brief"] };
return connect ? { cmd: "connect", args } : { cmd: "init", args: [...args, ...(state.signedIn ? ["--in-account"] : []), "--no-devtools", ...(o.noAnalytics ? [] : ["--analytics"]), "--brief"] };
}

/**
Expand Down Expand Up @@ -357,6 +360,40 @@ export async function sameApp(state, o = {}) {
};
}

/**
* `genclass analytics on` and `off`: turns visitor analytics on or off in what the setup added to this folder's app,
* with the runtime CLI's own init (it shows the one-line change and asks; --yes: no question). Nothing is sent. An
* app without GenClass is pointed at the setup, one set up by hand at its own GenClass.init(). Returns the exit code.
*/
export async function switchAnalytics(on, o = {}) {
let st = null;
try {
st = inspectProject({ cwd: o.cwd });
} catch {
st = null;
}
if (!st || st.fresh) {
out();
note(`GenClass is not in this app yet. ${c.cyan("npx genclass setup")} adds it${on ? ", with visitor analytics on" : ""}.`);
out();
return 1;
}
if (st.analytics === on) {
out();
good(`Visitor analytics are already ${on ? "on" : "off"} in this app.`);
if (on) note("Visits are counted on the deployed site, never from localhost.");
out();
return 0;
}
if (st.handWritten) {
out();
note(`GenClass is set up by hand here, so this command leaves the code alone: ${on ? "add analytics: true to" : "take analytics: true out of"} your GenClass.init({ ... }) options.`);
out();
return 1;
}
return runInit("init", ["--cwd", st.cwd, ...(o.yes ? ["--yes"] : []), on ? "--analytics" : "--no-analytics"]);
}

/** Shows the two Vite settings and writes them on a yes (--yes, or one question on a terminal). */
export async function addViteSettings(state, o = {}) {
let plan = null;
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/app.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ export function render(app, state, o = {}) {
if (app.visitors) {
const v = app.visitors;
const bounce = v.visits ? ` · ${Math.round((v.bounces / v.visits) * 100)}% left after one page` : "";
part("Visitors", v.visits ? `${plural(v.visits, "visit")} · ${plural(v.pages, "page view")}${bounce}` : c.gray("none counted in this period (analytics is opt-in: genclass.dev/docs)"));
part("Visitors", v.visits ? `${plural(v.visits, "visit")} · ${plural(v.pages, "page view")}${bounce}` : c.gray(!state.app ? "none counted in this period" : state.app.analytics ? "none counted in this period (the deployed site only)" : "off in this app: npx genclass analytics on"));
if (v.visits && v.entry.length) for (const l of wrap(`came in on ${v.entry.slice(0, all ? 10 : 3).map((e) => `${clean(e.key, 30)} (${n(e.count)})`).join(", ")}`, width() - 4 - 15)) out(` ${" ".repeat(15)}${c.gray(l)}`);
} else if (app.visitorsPlan) part("Visitors", c.gray(`visitor analytics come with the ${clean(app.visitorsPlan.plan ?? "Pro", 20)} plan${app.visitorsPlan.upgradeUrl ? `: ${app.visitorsPlan.upgradeUrl}` : ""}`));
if (u && u.limit !== null) part("Live fixes", u.observeOnly ? c.yellow(`${n(u.used)} of ${n(u.limit)} this month · observing only`) : `${n(u.used)} of ${n(u.limit)} this month`);
Expand Down
Loading
Loading