@getrefino/onboarding 0.1.0-rc.1 → 0.1.0-rc.2

package/README.md

@@ -22,7 +22,15 @@ const markdown = renderAgentInstructions(plan);
 const result = verifyIntegration("/path/to/site");
 ```
 
+`verifyIntegration` is entirely local: it proves that the files in the
+repository agree with each other, including which Refino site they name. It
+cannot prove that site still exists, because it makes no network calls and
+holds no credential — the deployed site's `/edit` flow is what checks that, and
+says so when the id is stale.
+
 All results are plain JSON. No network calls, no model calls. It never rewrites
-JSX and never overwrites an existing file.
+JSX. It overwrites no existing file except the generated Refino constants
+module and the `refino` block of `refino.config.json`, and those only when a
+plan carries a different site id — how a reconnected site is re-recorded.
 
 <https://refino.dev>

package/dist/apply.js

@@ -25,7 +25,11 @@ export function applyPlan(appDir, plan, options = {}) {
     const skipped = [];
     const version = options.packageVersion ?? dependencyRange();
     // 1. Plan + instructions (always rewritten: they describe this run).
-    writeFile(appDir, PLAN_FILE, `${JSON.stringify(plan, null, 2)}\n`, dryRun);
+    // The plan is committed to the customer's repository, so it must not carry
+    // the absolute path of whichever machine happened to run init. Relative to
+    // the file itself the repository root is ".", which is what a reader needs.
+    const portablePlan = { ...plan, repository: { ...plan.repository, root: "." } };
+    writeFile(appDir, PLAN_FILE, `${JSON.stringify(portablePlan, null, 2)}\n`, dryRun);
     written.push({ path: PLAN_FILE, action: "create", description: "Machine-readable migration plan." });
     writeFile(appDir, INSTRUCTIONS_FILE, renderAgentInstructions(plan), dryRun);
     written.push({ path: INSTRUCTIONS_FILE, action: "create", description: "Repository-specific agent instructions." });
@@ -76,10 +80,24 @@ export function applyPlan(appDir, plan, options = {}) {
     }
     else {
         const routes = [...new Set([...(existingConfig.routes ?? []), ...config.routes])];
-        const merged = { ...config, ...existingConfig, routes };
+        // The existing file wins for everything the owner may have tuned, but not
+        // for which Refino site this is: `--refino-site` is an explicit
+        // instruction, and a site reconnected in the dashboard has a new id. Left
+        // to the old values the site keeps asking Refino to authorize a site that
+        // no longer exists, which is refused as editor_site.
+        const connection = plan.refino
+            ? { refino: config.refino, endpoint: config.endpoint, ...(config.sessionEndpoint ? { sessionEndpoint: config.sessionEndpoint } : {}) }
+            : {};
+        const merged = { ...config, ...existingConfig, ...connection, routes };
         if (JSON.stringify(merged) !== JSON.stringify(existingConfig)) {
+            const previousSiteId = existingConfig.refino?.siteId;
+            const reconnected = plan.refino != null && previousSiteId !== undefined && previousSiteId !== plan.refino.siteId;
             writeFile(appDir, CONFIG_FILE, `${JSON.stringify(merged, null, 2)}\n`, dryRun);
-            written.push({ path: CONFIG_FILE, action: "modify", description: "Recorded the routes selected in this run." });
+            written.push({
+                path: CONFIG_FILE,
+                action: "modify",
+                description: reconnected ? `Now connected to Refino site ${plan.refino.siteId} (was ${previousSiteId}).` : "Recorded the routes selected in this run.",
+            });
         }
         else {
             skipped.push({ path: CONFIG_FILE, reason: "Up to date." });
@@ -129,10 +147,31 @@ export function applyPlan(appDir, plan, options = {}) {
     else {
         skipped.push({ path: ".env.example", reason: "Already documents Refino variables." });
     }
-    // 6. Boilerplate: only files that do not exist.
+    // 6. Boilerplate: only files that do not exist. The one exception is the
+    // generated Refino constants module: it holds no hand-written code, only the
+    // public site id and app URL, and a site reconnected in the dashboard has a
+    // new id. Keeping the old one there silently breaks editing, and `init
+    // --refino-site <id>` is the documented way to record the new one, so the
+    // stale copy is rewritten instead of skipped.
+    const site = plan.refino;
+    const siteModule = site ? `${plan.integration.boilerplateDir}/refino-site` : null;
     for (const file of boilerplateFiles(plan)) {
-        if (exists(join(appDir, file.path))) {
-            skipped.push({ path: file.path, reason: "Exists; not overwritten." });
+        const absolute = join(appDir, file.path);
+        if (exists(absolute)) {
+            const isSiteModule = site !== null && siteModule !== null && file.path.replace(/\.[cm]?[jt]sx?$/, "") === siteModule;
+            const currentText = isSiteModule ? (readText(absolute) ?? "") : "";
+            const namesThisSite = isSiteModule && currentText.includes(JSON.stringify(site.siteId)) && currentText.includes(JSON.stringify(site.appUrl));
+            if (!isSiteModule || namesThisSite) {
+                skipped.push({ path: file.path, reason: "Exists; not overwritten." });
+                continue;
+            }
+            const previous = /REFINO_SITE_ID\s*=\s*"(site_[a-f0-9]{32})"/.exec(currentText)?.[1];
+            writeFile(appDir, file.path, file.content, dryRun);
+            written.push({
+                path: file.path,
+                action: "modify",
+                description: `Now names Refino site ${site.siteId} at ${site.appUrl}${previous && previous !== site.siteId ? ` (was ${previous})` : ""}.`,
+            });
             continue;
         }
         writeFile(appDir, file.path, file.content, dryRun);

package/dist/index.d.ts

@@ -9,7 +9,9 @@ export { applyPlan } from "./apply.js";
 export type { ApplyOptions, RefinoConfig } from "./apply.js";
 export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
 export type { TemplateFile } from "./templates.js";
-export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, hostedFiles } from "./templates-hosted.js";
+export { INSTALL_METHODS, isInstallMethod, resolveInstallMethod } from "./install-method.js";
+export type { InstallMethod } from "./install-method.js";
+export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, analyticsFramework, analyticsHosting, hostedFiles } from "./templates-hosted.js";
 export type { RefinoSiteConfig } from "./templates-hosted.js";
 export { verifyIntegration } from "./verify.js";
 export type { VerifyOptions } from "./verify.js";

package/dist/index.js

@@ -5,5 +5,6 @@ export { buildPlan, planMigration, planContent, defaultContentFile, integrationP
 export { renderAgentInstructions } from "./agent.js";
 export { applyPlan } from "./apply.js";
 export { boilerplateFiles, ENV_EXAMPLE_BLOCK } from "./templates.js";
-export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, hostedFiles } from "./templates-hosted.js";
+export { INSTALL_METHODS, isInstallMethod, resolveInstallMethod } from "./install-method.js";
+export { DEFAULT_REFINO_APP_URL, REFINO_SITE_ID_PATTERN, analyticsFramework, analyticsHosting, hostedFiles } from "./templates-hosted.js";
 export { verifyIntegration } from "./verify.js";

package/dist/install-method.d.ts

@@ -0,0 +1,26 @@
+/**
+ * How Refino was installed into a site.
+ *
+ * The value is never inferred. Environment variables that a coding agent
+ * happens to set are not evidence: they are set by wrappers, inherited by
+ * subshells, and copied between tools. So the only sources are an explicit
+ * `refino init --via <method>` and an explicit `REFINO_INSTALL_METHOD` in
+ * the environment, and anything else stays `unknown`.
+ *
+ * The value ends up in the site's public `refino/refino-site.ts`, next to
+ * the site id: committed, readable, and changeable by the owner. It is not
+ * a secret and it identifies a tool, never a person.
+ *
+ * This list must stay identical to `INSTALL_METHODS` in
+ * `packages/analytics/src/taxonomy.ts`; `scripts/install-method.test.mjs`
+ * checks that it does.
+ */
+export declare const INSTALL_METHODS: readonly ["claude", "codex", "gemini", "grok", "manual", "cli", "other", "unknown"];
+export type InstallMethod = (typeof INSTALL_METHODS)[number];
+export declare function isInstallMethod(value: unknown): value is InstallMethod;
+/**
+ * Resolve `--via`, then `REFINO_INSTALL_METHOD`, then `unknown`. An
+ * unrecognised name is `other`: the installer said something, and pretending
+ * they said nothing would be as wrong as guessing which agent they meant.
+ */
+export declare function resolveInstallMethod(flag: string | undefined, env?: Readonly<Record<string, string | undefined>>): InstallMethod;

package/dist/install-method.js

@@ -0,0 +1,32 @@
+/**
+ * How Refino was installed into a site.
+ *
+ * The value is never inferred. Environment variables that a coding agent
+ * happens to set are not evidence: they are set by wrappers, inherited by
+ * subshells, and copied between tools. So the only sources are an explicit
+ * `refino init --via <method>` and an explicit `REFINO_INSTALL_METHOD` in
+ * the environment, and anything else stays `unknown`.
+ *
+ * The value ends up in the site's public `refino/refino-site.ts`, next to
+ * the site id: committed, readable, and changeable by the owner. It is not
+ * a secret and it identifies a tool, never a person.
+ *
+ * This list must stay identical to `INSTALL_METHODS` in
+ * `packages/analytics/src/taxonomy.ts`; `scripts/install-method.test.mjs`
+ * checks that it does.
+ */
+export const INSTALL_METHODS = ["claude", "codex", "gemini", "grok", "manual", "cli", "other", "unknown"];
+export function isInstallMethod(value) {
+    return typeof value === "string" && INSTALL_METHODS.includes(value);
+}
+/**
+ * Resolve `--via`, then `REFINO_INSTALL_METHOD`, then `unknown`. An
+ * unrecognised name is `other`: the installer said something, and pretending
+ * they said nothing would be as wrong as guessing which agent they meant.
+ */
+export function resolveInstallMethod(flag, env = {}) {
+    const raw = (flag ?? env.REFINO_INSTALL_METHOD ?? "").trim().toLowerCase();
+    if (raw === "")
+        return "unknown";
+    return isInstallMethod(raw) ? raw : "other";
+}

package/dist/plan.js

@@ -60,7 +60,7 @@ export function resolveRefinoSite(option) {
     catch {
         throw new Error(`Refino app URL must be an https origin such as ${DEFAULT_REFINO_APP_URL}, got ${JSON.stringify(raw)}.`);
     }
-    return { siteId: option.siteId, appUrl };
+    return { siteId: option.siteId, appUrl, installMethod: option.installMethod ?? "unknown" };
 }
 export function hostLabel(kind) {
     switch (kind) {

package/dist/templates-hosted.d.ts

@@ -9,20 +9,28 @@
  *          → POST Refino /api/editor/token → 12 h editor token in sessionStorage
  *          → <RefinoProvider endpoint={Refino copy API} headers={bearer}>
  */
+import type { InstallMethod } from "./install-method.js";
 import type { MigrationPlan } from "./types.js";
 import type { TemplateFile } from "./templates.js";
 export declare const DEFAULT_REFINO_APP_URL = "https://app.refino.dev";
 export interface RefinoSiteConfig {
     readonly siteId: string;
     readonly appUrl: string;
+    /** What `refino init --via <method>` was told. "unknown" when it was told nothing. */
+    readonly installMethod: InstallMethod;
+    /** Framework, as the analytics vocabulary names it. */
+    readonly framework: string;
+    /** Hosting provider, as the analytics vocabulary names it. */
+    readonly hosting: string;
+    readonly packageVersion: string;
 }
 export declare const REFINO_SITE_ID_PATTERN: RegExp;
 /** Public configuration; safe to ship to the browser and to commit. */
 export declare const REFINO_SITE: (config: RefinoSiteConfig) => string;
 /** Browser-only client: PKCE, the authorization round trip and the session in sessionStorage. */
-export declare const REFINO_CLIENT = "/**\n * Browser-side Refino editor authorization for this site. No secrets here:\n * the site is a public client (OAuth 2.1 with PKCE). The editor token lives\n * in sessionStorage only (never localStorage, never a URL), is scoped to\n * this site, and Refino re-checks the account's entitlement on every load\n * and save. Never import this from server code.\n */\nimport { REFINO_APP_URL, REFINO_SITE_ID } from \"./refino-site\";\n\nconst PKCE_KEY = \"refino.pkce\";\nconst SESSION_KEY = \"refino.editor\";\nconst CALLBACK_PATH = \"/edit\";\n\nexport interface EditorSession {\n  readonly token: string;\n  /** Unix seconds. */\n  readonly expiresAt: number;\n  readonly siteId: string;\n}\n\ninterface PendingAuthorization {\n  readonly verifier: string;\n  readonly state: string;\n  readonly returnTo: string;\n}\n\nfunction base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\nfunction randomToken(bytes: number): string {\n  const buffer = new Uint8Array(bytes);\n  crypto.getRandomValues(buffer);\n  return base64url(buffer);\n}\n\nasync function sha256(text: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(text));\n  return base64url(new Uint8Array(digest));\n}\n\nfunction storage(): Storage | null {\n  try {\n    return typeof window === \"undefined\" ? null : window.sessionStorage;\n  } catch {\n    return null;\n  }\n}\n\nfunction readJson<T>(key: string): T | null {\n  const raw = storage()?.getItem(key);\n  if (!raw) return null;\n  try {\n    return JSON.parse(raw) as T;\n  } catch {\n    return null;\n  }\n}\n\n/** Only a path on this site, never another origin. */\nexport function safeReturnTo(value: string | null | undefined): string {\n  if (!value || !value.startsWith(\"/\") || value.startsWith(\"//\") || value.startsWith(\"/\\\\\") || value.length > 512) return \"/\";\n  return value;\n}\n\nexport function editorEndpoint(): string {\n  return `${REFINO_APP_URL}/api/sites/${REFINO_SITE_ID}/copy`;\n}\n\nexport function callbackUrl(): string {\n  return `${window.location.origin}${CALLBACK_PATH}`;\n}\n\n/** The current editor session, or null when there is none or it expired. */\nexport function readEditorSession(nowSeconds: number = Math.floor(Date.now() / 1000)): EditorSession | null {\n  const session = readJson<EditorSession>(SESSION_KEY);\n  if (!session || typeof session.token !== \"string\" || session.siteId !== REFINO_SITE_ID || typeof session.expiresAt !== \"number\") return null;\n  if (session.expiresAt <= nowSeconds) {\n    storage()?.removeItem(SESSION_KEY);\n    return null;\n  }\n  return session;\n}\n\nexport function clearEditorSession(): void {\n  storage()?.removeItem(SESSION_KEY);\n  storage()?.removeItem(PKCE_KEY);\n}\n\n/** Start the flow: remember the PKCE verifier and state, then go to Refino. */\nexport async function beginAuthorization(returnTo: string): Promise<void> {\n  const verifier = randomToken(32);\n  const state = randomToken(16);\n  const pending: PendingAuthorization = { verifier, state, returnTo: safeReturnTo(returnTo) };\n  storage()?.setItem(PKCE_KEY, JSON.stringify(pending));\n  const params = new URLSearchParams({\n    site_id: REFINO_SITE_ID,\n    redirect_uri: callbackUrl(),\n    code_challenge: await sha256(verifier),\n    code_challenge_method: \"S256\",\n    state,\n  });\n  window.location.assign(`${REFINO_APP_URL}/editor/authorize?${params.toString()}`);\n}\n\nexport type AuthorizationResult = { readonly ok: true; readonly returnTo: string } | { readonly ok: false; readonly error: string };\n\n/**\n * Finish the flow on /edit?code&state: check the state, exchange the code\n * with the verifier this browser kept, store the session, and scrub the\n * code from the URL. The token is never placed in a URL.\n */\nexport async function completeAuthorization(search: string = window.location.search): Promise<AuthorizationResult> {\n  const params = new URLSearchParams(search);\n  const code = params.get(\"code\");\n  const state = params.get(\"state\");\n  const pending = readJson<PendingAuthorization>(PKCE_KEY);\n  storage()?.removeItem(PKCE_KEY);\n  if (typeof window !== \"undefined\" && window.history.replaceState) window.history.replaceState(null, \"\", window.location.pathname);\n  if (!code || !state) return { ok: false, error: \"Refino did not return an authorization code.\" };\n  if (!pending || pending.state !== state) return { ok: false, error: \"Sign-in was interrupted (state mismatch). Start again.\" };\n\n  let response: Response;\n  try {\n    response = await fetch(`${REFINO_APP_URL}/api/editor/token`, {\n      method: \"POST\",\n      mode: \"cors\",\n      credentials: \"omit\",\n      headers: { \"content-type\": \"application/json\", accept: \"application/json\" },\n      body: JSON.stringify({ grant_type: \"authorization_code\", code, code_verifier: pending.verifier, site_id: REFINO_SITE_ID, redirect_uri: callbackUrl() }),\n    });\n  } catch {\n    return { ok: false, error: \"Could not reach Refino to finish signing in.\" };\n  }\n  const body = (await response.json().catch(() => null)) as { ok?: boolean; token?: string; expiresAt?: number; siteId?: string; error?: { message?: string } } | null;\n  if (!response.ok || !body?.ok || typeof body.token !== \"string\" || typeof body.expiresAt !== \"number\" || body.siteId !== REFINO_SITE_ID) {\n    return { ok: false, error: body?.error?.message ?? \"Refino did not accept the authorization.\" };\n  }\n  const session: EditorSession = { token: body.token, expiresAt: body.expiresAt, siteId: body.siteId };\n  storage()?.setItem(SESSION_KEY, JSON.stringify(session));\n  return { ok: true, returnTo: pending.returnTo };\n}\n";
+export declare const REFINO_CLIENT = "/**\n * Browser-side Refino editor authorization for this site. No secrets here:\n * the site is a public client (OAuth 2.1 with PKCE). The editor token lives\n * in sessionStorage only (never localStorage, never a URL), is scoped to\n * this site, and Refino re-checks the account's entitlement on every load\n * and save. Never import this from server code.\n */\nimport { REFINO_APP_URL, REFINO_INSTALL, REFINO_SITE_ID } from \"./refino-site\";\n\nconst PKCE_KEY = \"refino.pkce\";\nconst SESSION_KEY = \"refino.editor\";\nconst CALLBACK_PATH = \"/edit\";\n\nexport interface EditorSession {\n  readonly token: string;\n  /** Unix seconds. */\n  readonly expiresAt: number;\n  readonly siteId: string;\n}\n\ninterface PendingAuthorization {\n  readonly verifier: string;\n  readonly state: string;\n  readonly returnTo: string;\n}\n\nfunction base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\nfunction randomToken(bytes: number): string {\n  const buffer = new Uint8Array(bytes);\n  crypto.getRandomValues(buffer);\n  return base64url(buffer);\n}\n\nasync function sha256(text: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", new TextEncoder().encode(text));\n  return base64url(new Uint8Array(digest));\n}\n\nfunction storage(): Storage | null {\n  try {\n    return typeof window === \"undefined\" ? null : window.sessionStorage;\n  } catch {\n    return null;\n  }\n}\n\nfunction readJson<T>(key: string): T | null {\n  const raw = storage()?.getItem(key);\n  if (!raw) return null;\n  try {\n    return JSON.parse(raw) as T;\n  } catch {\n    return null;\n  }\n}\n\n/** Only a path on this site, never another origin. */\nexport function safeReturnTo(value: string | null | undefined): string {\n  if (!value || !value.startsWith(\"/\") || value.startsWith(\"//\") || value.startsWith(\"/\\\\\") || value.length > 512) return \"/\";\n  return value;\n}\n\nexport function editorEndpoint(): string {\n  return `${REFINO_APP_URL}/api/sites/${REFINO_SITE_ID}/copy`;\n}\n\nexport function callbackUrl(): string {\n  return `${window.location.origin}${CALLBACK_PATH}`;\n}\n\n/** The current editor session, or null when there is none or it expired. */\nexport function readEditorSession(nowSeconds: number = Math.floor(Date.now() / 1000)): EditorSession | null {\n  const session = readJson<EditorSession>(SESSION_KEY);\n  if (!session || typeof session.token !== \"string\" || session.siteId !== REFINO_SITE_ID || typeof session.expiresAt !== \"number\") return null;\n  if (session.expiresAt <= nowSeconds) {\n    storage()?.removeItem(SESSION_KEY);\n    return null;\n  }\n  return session;\n}\n\nexport function clearEditorSession(): void {\n  storage()?.removeItem(SESSION_KEY);\n  storage()?.removeItem(PKCE_KEY);\n}\n\n/** Start the flow: remember the PKCE verifier and state, then go to Refino. */\nexport async function beginAuthorization(returnTo: string): Promise<void> {\n  const verifier = randomToken(32);\n  const state = randomToken(16);\n  const pending: PendingAuthorization = { verifier, state, returnTo: safeReturnTo(returnTo) };\n  storage()?.setItem(PKCE_KEY, JSON.stringify(pending));\n  const params = new URLSearchParams({\n    site_id: REFINO_SITE_ID,\n    redirect_uri: callbackUrl(),\n    code_challenge: await sha256(verifier),\n    code_challenge_method: \"S256\",\n    state,\n  });\n  window.location.assign(`${REFINO_APP_URL}/editor/authorize?${params.toString()}`);\n}\n\nexport type AuthorizationResult = { readonly ok: true; readonly returnTo: string } | { readonly ok: false; readonly error: string };\n\n/**\n * Finish the flow on /edit?code&state: check the state, exchange the code\n * with the verifier this browser kept, store the session, and scrub the\n * code from the URL. The token is never placed in a URL.\n */\nexport async function completeAuthorization(search: string = window.location.search): Promise<AuthorizationResult> {\n  const params = new URLSearchParams(search);\n  const code = params.get(\"code\");\n  const state = params.get(\"state\");\n  const pending = readJson<PendingAuthorization>(PKCE_KEY);\n  storage()?.removeItem(PKCE_KEY);\n  if (typeof window !== \"undefined\" && window.history.replaceState) window.history.replaceState(null, \"\", window.location.pathname);\n  if (!code || !state) return { ok: false, error: \"Refino did not return an authorization code.\" };\n  if (!pending || pending.state !== state) return { ok: false, error: \"Sign-in was interrupted (state mismatch). Start again.\" };\n\n  let response: Response;\n  try {\n    response = await fetch(`${REFINO_APP_URL}/api/editor/token`, {\n      method: \"POST\",\n      mode: \"cors\",\n      credentials: \"omit\",\n      headers: { \"content-type\": \"application/json\", accept: \"application/json\" },\n      body: JSON.stringify({\n        grant_type: \"authorization_code\",\n        code,\n        code_verifier: pending.verifier,\n        site_id: REFINO_SITE_ID,\n        redirect_uri: callbackUrl(),\n        // The public install facts from refino-site.ts, sent once per\n        // sign-in. Refino records them the first time and ignores them\n        // afterwards. Remove this line and everything still works.\n        install: REFINO_INSTALL,\n      }),\n    });\n  } catch {\n    return { ok: false, error: \"Could not reach Refino to finish signing in.\" };\n  }\n  const body = (await response.json().catch(() => null)) as { ok?: boolean; token?: string; expiresAt?: number; siteId?: string; error?: { message?: string } } | null;\n  if (!response.ok || !body?.ok || typeof body.token !== \"string\" || typeof body.expiresAt !== \"number\" || body.siteId !== REFINO_SITE_ID) {\n    return { ok: false, error: body?.error?.message ?? \"Refino did not accept the authorization.\" };\n  }\n  const session: EditorSession = { token: body.token, expiresAt: body.expiresAt, siteId: body.siteId };\n  storage()?.setItem(SESSION_KEY, JSON.stringify(session));\n  return { ok: true, returnTo: pending.returnTo };\n}\n\n/**\n * The three editor events this site reports, and the only ones it ever\n * sends. There is no analytics SDK on this site: no autocapture, no session\n * recording, no third-party script, no cookie. Each event is one small POST\n * to Refino carrying an event name and, for a revert, whether it was one\n * word or all of them \u2014 never your page, your copy, your visitors or your\n * repository. `edit_saved` is not in this list on purpose: a save is a\n * commit, and Refino records that on its own side where it cannot be faked\n * or lost.\n */\nconst REPORTABLE_EVENTS = [\"editor_opened\", \"edit_started\", \"edit_reverted\"] as const;\n\ntype ReportableEvent = (typeof REPORTABLE_EVENTS)[number];\n\ninterface EditorEventLike {\n  readonly name: string;\n  readonly properties: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Fire and forget. A failure here is invisible and harmless: nothing in the\n * editor waits for it, retries it, or behaves differently when it fails.\n */\nexport function reportEditorEvent(event: EditorEventLike): void {\n  const session = readEditorSession();\n  if (!session) return;\n  if (!(REPORTABLE_EVENTS as readonly string[]).includes(event.name)) return;\n  const name = event.name as ReportableEvent;\n  const scope = event.properties.scope;\n  try {\n    void fetch(`${REFINO_APP_URL}/api/editor/events`, {\n      method: \"POST\",\n      mode: \"cors\",\n      credentials: \"omit\",\n      keepalive: true,\n      headers: { \"content-type\": \"application/json\", authorization: `Bearer ${session.token}` },\n      body: JSON.stringify(scope === \"one\" || scope === \"all\" ? { event: name, scope } : { event: name }),\n    }).catch(() => {});\n  } catch {\n    // Never let reporting affect editing.\n  }\n}\n";
 /** Provider wrapper: edit mode is decided in the browser from the stored session. */
-export declare const COPY_EDITING_HOSTED = "\"use client\";\n\nimport type { CopyContent } from \"@getrefino/core\";\nimport { RefinoProvider } from \"@getrefino/react\";\nimport type { ReactNode } from \"react\";\nimport { useCallback, useEffect, useState } from \"react\";\n\nimport { clearEditorSession, editorEndpoint, readEditorSession } from \"./refino-client\";\nimport type { EditorSession } from \"./refino-client\";\n\ninterface CopyEditingProps {\n  content: CopyContent;\n  children: ReactNode;\n}\n\n/**\n * Hosted mode (Refino). Visitors get the plain site: the server never\n * decides edit mode, so pages can stay static. In the browser, an editor\n * session stored by /edit turns edit mode on; loads and saves go to Refino\n * with the session's bearer token, and Refino checks the site's\n * entitlement on every request.\n */\nexport function CopyEditing({ content, children }: CopyEditingProps) {\n  const [session, setSession] = useState<EditorSession | null>(null);\n\n  useEffect(() => {\n    // Read the session only after mount so server-rendered HTML never differs from the visitor's.\n    setSession(readEditorSession());\n  }, []);\n\n  // Read at request time (the provider keeps its options from the first render), so the\n  // token is always the one currently stored and never sent once the session is cleared.\n  const headers = useCallback((): Record<string, string> => {\n    const current = readEditorSession();\n    return current ? { authorization: `Bearer ${current.token}` } : {};\n  }, []);\n\n  const onExit = useCallback(async () => {\n    clearEditorSession();\n    window.location.assign(\"/\");\n  }, []);\n\n  return (\n    <RefinoProvider content={content} editing={session !== null} endpoint={editorEndpoint()} headers={headers} signInHref=\"/edit\" onExit={onExit}>\n      {children}\n    </RefinoProvider>\n  );\n}\n";
+export declare const COPY_EDITING_HOSTED = "\"use client\";\n\nimport type { CopyContent } from \"@getrefino/core\";\nimport { RefinoProvider } from \"@getrefino/react\";\nimport type { ReactNode } from \"react\";\nimport { useCallback, useEffect, useState } from \"react\";\n\nimport { clearEditorSession, editorEndpoint, readEditorSession, reportEditorEvent } from \"./refino-client\";\nimport type { EditorSession } from \"./refino-client\";\n\ninterface CopyEditingProps {\n  content: CopyContent;\n  children: ReactNode;\n}\n\n/**\n * Hosted mode (Refino). Visitors get the plain site: the server never\n * decides edit mode, so pages can stay static. In the browser, an editor\n * session stored by /edit turns edit mode on; loads and saves go to Refino\n * with the session's bearer token, and Refino checks the site's\n * entitlement on every request.\n */\nexport function CopyEditing({ content, children }: CopyEditingProps) {\n  const [session, setSession] = useState<EditorSession | null>(null);\n\n  useEffect(() => {\n    // Read the session only after mount so server-rendered HTML never differs from the visitor's.\n    setSession(readEditorSession());\n  }, []);\n\n  // Read at request time (the provider keeps its options from the first render), so the\n  // token is always the one currently stored and never sent once the session is cleared.\n  const headers = useCallback((): Record<string, string> => {\n    const current = readEditorSession();\n    return current ? { authorization: `Bearer ${current.token}` } : {};\n  }, []);\n\n  const onExit = useCallback(async () => {\n    clearEditorSession();\n    window.location.assign(\"/\");\n  }, []);\n\n  return (\n    <RefinoProvider content={content} editing={session !== null} endpoint={editorEndpoint()} headers={headers} signInHref=\"/edit\" onExit={onExit} onEvent={reportEditorEvent}>\n      {children}\n    </RefinoProvider>\n  );\n}\n";
 /** The /edit page: starts the flow, finishes it on return, shows state. Works as a static export. */
 export declare const EDIT_PAGE_HOSTED = "\"use client\";\n\nimport { useEffect, useState } from \"react\";\n\nimport { beginAuthorization, clearEditorSession, completeAuthorization, readEditorSession, safeReturnTo } from \"./refino-client\";\n\ntype Phase = { kind: \"loading\" } | { kind: \"signed-in\" } | { kind: \"error\"; message: string };\n\n/**\n * Owner entry point for Refino-hosted editing. Visiting /edit sends the\n * owner to Refino to sign in and authorize this site; Refino sends them\n * back here with a one-time code, which is exchanged for an editor session\n * and scrubbed from the URL. Restyle freely; keep the behaviour.\n */\nexport default function EditPage() {\n  const [phase, setPhase] = useState<Phase>({ kind: \"loading\" });\n\n  useEffect(() => {\n    let cancelled = false;\n    const params = new URLSearchParams(window.location.search);\n    if (params.has(\"code\") || params.has(\"state\")) {\n      void completeAuthorization().then((result) => {\n        if (cancelled) return;\n        if (result.ok) window.location.assign(result.returnTo);\n        else setPhase({ kind: \"error\", message: result.error });\n      });\n    } else if (readEditorSession()) {\n      setPhase({ kind: \"signed-in\" });\n    } else if (params.get(\"error\")) {\n      setPhase({ kind: \"error\", message: params.get(\"error\") ?? \"Sign-in failed.\" });\n    } else {\n      void beginAuthorization(safeReturnTo(params.get(\"return_to\")));\n    }\n    return () => {\n      cancelled = true;\n    };\n  }, []);\n\n  return (\n    <main style={{ maxWidth: 420, margin: \"10vh auto\", padding: 24, fontFamily: \"system-ui, sans-serif\" }}>\n      {phase.kind === \"loading\" && <p>Signing you in with Refino\u2026</p>}\n      {phase.kind === \"signed-in\" && (\n        <>\n          <h1>Edit mode is on</h1>\n          <p>Go to the site, click any text, and press Save when you are done.</p>\n          <p>\n            <a href=\"/\">Open the site</a>\n          </p>\n          <button\n            type=\"button\"\n            onClick={() => {\n              clearEditorSession();\n              setPhase({ kind: \"loading\" });\n              void beginAuthorization(\"/\");\n            }}\n          >\n            Sign in as someone else\n          </button>\n        </>\n      )}\n      {phase.kind === \"error\" && (\n        <>\n          <h1>Could not start editing</h1>\n          <p role=\"alert\">{phase.message}</p>\n          <button type=\"button\" onClick={() => void beginAuthorization(\"/\")}>\n            Try again\n          </button>\n        </>\n      )}\n    </main>\n  );\n}\n";
 /** Next.js App Router route file for /edit: re-exports the generated client page. */
@@ -30,5 +38,12 @@ export declare const EDIT_ROUTE_NEXT_HOSTED: (pageImport: string) => string;
 /** Next.js Pages Router page for /edit. */
 export declare const EDIT_PAGE_NEXT_PAGES_HOSTED: (pageImport: string) => string;
 export declare const EDIT_LAYOUT_HOSTED = "import type { Metadata } from \"next\";\nimport type { ReactNode } from \"react\";\n\n/** /edit is the owner's entry point, not a public page; the page itself is a client component and cannot export metadata. */\nexport const metadata: Metadata = { title: \"Edit this site\", robots: { index: false, follow: false } };\n\nexport default function EditLayout({ children }: { children: ReactNode }) {\n  return children;\n}\n";
+/**
+ * The framework and hosting names Refino's analytics vocabulary uses. A
+ * provider the inspector did not recognise is "other" and an absent one is
+ * "unknown"; neither is ever guessed from something else.
+ */
+export declare function analyticsFramework(framework: MigrationPlan["repository"]["framework"]): string;
+export declare function analyticsHosting(hosting: string | null): string;
 /** Files for a Refino-connected site. No server code, no secrets, in any framework. */
 export declare function hostedFiles(plan: MigrationPlan): TemplateFile[];

package/dist/templates-hosted.js

@@ -1,14 +1,31 @@
+import { TOOL_VERSION } from "./plan.js";
 export const DEFAULT_REFINO_APP_URL = "https://app.refino.dev";
 export const REFINO_SITE_ID_PATTERN = /^site_[a-f0-9]{32}$/;
 /** Public configuration; safe to ship to the browser and to commit. */
 export const REFINO_SITE = (config) => `/**
- * Public Refino configuration for this site. Neither value is a secret:
- * the site id appears in editor URLs and the app URL is where owners sign
- * in. Generated by Refino; change it only when the site is
- * reconnected to Refino.
+ * Public Refino configuration for this site. Nothing here is a secret: the
+ * site id appears in editor URLs and the app URL is where owners sign in.
+ * Generated by Refino; change it only when the site is reconnected to
+ * Refino.
  */
 export const REFINO_SITE_ID = ${JSON.stringify(config.siteId)};
 export const REFINO_APP_URL = ${JSON.stringify(config.appUrl)};
+
+/**
+ * How this site was set up, recorded once at install time and sent to
+ * Refino when the owner signs in to edit. It tells Refino which
+ * installation routes work, nothing more: there is no personal data here,
+ * no repository content, and no page content. \`method\` is whatever
+ * \`refino init --via <method>\` was told; it is "unknown" when it was told
+ * nothing, and it is never guessed. Edit or delete these values freely —
+ * the editor works exactly the same either way.
+ */
+export const REFINO_INSTALL = {
+  method: ${JSON.stringify(config.installMethod)},
+  framework: ${JSON.stringify(config.framework)},
+  hosting: ${JSON.stringify(config.hosting)},
+  packageVersion: ${JSON.stringify(config.packageVersion)},
+} as const;
 `;
 /** Browser-only client: PKCE, the authorization round trip and the session in sessionStorage. */
 export const REFINO_CLIENT = `/**
@@ -18,7 +35,7 @@ export const REFINO_CLIENT = `/**
  * this site, and Refino re-checks the account's entitlement on every load
  * and save. Never import this from server code.
  */
-import { REFINO_APP_URL, REFINO_SITE_ID } from "./refino-site";
+import { REFINO_APP_URL, REFINO_INSTALL, REFINO_SITE_ID } from "./refino-site";
 
 const PKCE_KEY = "refino.pkce";
 const SESSION_KEY = "refino.editor";
@@ -142,7 +159,17 @@ export async function completeAuthorization(search: string = window.location.sea
       mode: "cors",
       credentials: "omit",
       headers: { "content-type": "application/json", accept: "application/json" },
-      body: JSON.stringify({ grant_type: "authorization_code", code, code_verifier: pending.verifier, site_id: REFINO_SITE_ID, redirect_uri: callbackUrl() }),
+      body: JSON.stringify({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: pending.verifier,
+        site_id: REFINO_SITE_ID,
+        redirect_uri: callbackUrl(),
+        // The public install facts from refino-site.ts, sent once per
+        // sign-in. Refino records them the first time and ignores them
+        // afterwards. Remove this line and everything still works.
+        install: REFINO_INSTALL,
+      }),
     });
   } catch {
     return { ok: false, error: "Could not reach Refino to finish signing in." };
@@ -155,6 +182,49 @@ export async function completeAuthorization(search: string = window.location.sea
   storage()?.setItem(SESSION_KEY, JSON.stringify(session));
   return { ok: true, returnTo: pending.returnTo };
 }
+
+/**
+ * The three editor events this site reports, and the only ones it ever
+ * sends. There is no analytics SDK on this site: no autocapture, no session
+ * recording, no third-party script, no cookie. Each event is one small POST
+ * to Refino carrying an event name and, for a revert, whether it was one
+ * word or all of them — never your page, your copy, your visitors or your
+ * repository. \`edit_saved\` is not in this list on purpose: a save is a
+ * commit, and Refino records that on its own side where it cannot be faked
+ * or lost.
+ */
+const REPORTABLE_EVENTS = ["editor_opened", "edit_started", "edit_reverted"] as const;
+
+type ReportableEvent = (typeof REPORTABLE_EVENTS)[number];
+
+interface EditorEventLike {
+  readonly name: string;
+  readonly properties: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Fire and forget. A failure here is invisible and harmless: nothing in the
+ * editor waits for it, retries it, or behaves differently when it fails.
+ */
+export function reportEditorEvent(event: EditorEventLike): void {
+  const session = readEditorSession();
+  if (!session) return;
+  if (!(REPORTABLE_EVENTS as readonly string[]).includes(event.name)) return;
+  const name = event.name as ReportableEvent;
+  const scope = event.properties.scope;
+  try {
+    void fetch(\`\${REFINO_APP_URL}/api/editor/events\`, {
+      method: "POST",
+      mode: "cors",
+      credentials: "omit",
+      keepalive: true,
+      headers: { "content-type": "application/json", authorization: \`Bearer \${session.token}\` },
+      body: JSON.stringify(scope === "one" || scope === "all" ? { event: name, scope } : { event: name }),
+    }).catch(() => {});
+  } catch {
+    // Never let reporting affect editing.
+  }
+}
 `;
 /** Provider wrapper: edit mode is decided in the browser from the stored session. */
 export const COPY_EDITING_HOSTED = `"use client";
@@ -164,7 +234,7 @@ import { RefinoProvider } from "@getrefino/react";
 import type { ReactNode } from "react";
 import { useCallback, useEffect, useState } from "react";
 
-import { clearEditorSession, editorEndpoint, readEditorSession } from "./refino-client";
+import { clearEditorSession, editorEndpoint, readEditorSession, reportEditorEvent } from "./refino-client";
 import type { EditorSession } from "./refino-client";
 
 interface CopyEditingProps {
@@ -200,7 +270,7 @@ export function CopyEditing({ content, children }: CopyEditingProps) {
   }, []);
 
   return (
-    <RefinoProvider content={content} editing={session !== null} endpoint={editorEndpoint()} headers={headers} signInHref="/edit" onExit={onExit}>
+    <RefinoProvider content={content} editing={session !== null} endpoint={editorEndpoint()} headers={headers} signInHref="/edit" onExit={onExit} onEvent={reportEditorEvent}>
       {children}
     </RefinoProvider>
   );
@@ -306,6 +376,28 @@ function relativeImport(fromFile, toFile) {
     const up = fromParts.length === 0 ? "." : fromParts.map(() => "..").join("/");
     return `${up}/${toParts.join("/")}`.replace(/\.(tsx?|jsx?)$/, "");
 }
+/**
+ * The framework and hosting names Refino's analytics vocabulary uses. A
+ * provider the inspector did not recognise is "other" and an absent one is
+ * "unknown"; neither is ever guessed from something else.
+ */
+export function analyticsFramework(framework) {
+    switch (framework) {
+        case "next":
+            return "next";
+        case "vite-react":
+            return "vite";
+        case "react":
+            return "react";
+        default:
+            return "other";
+    }
+}
+export function analyticsHosting(hosting) {
+    if (!hosting)
+        return "unknown";
+    return ["cloudflare", "vercel", "netlify"].includes(hosting) ? hosting : "other";
+}
 /** Files for a Refino-connected site. No server code, no secrets, in any framework. */
 export function hostedFiles(plan) {
     const refino = plan.refino;
@@ -313,7 +405,15 @@ export function hostedFiles(plan) {
         return [];
     const dir = plan.integration.boilerplateDir;
     const files = [
-        { path: `${dir}/refino-site.ts`, content: REFINO_SITE(refino) },
+        {
+            path: `${dir}/refino-site.ts`,
+            content: REFINO_SITE({
+                ...refino,
+                framework: analyticsFramework(plan.repository.framework),
+                hosting: analyticsHosting(plan.repository.hosting),
+                packageVersion: TOOL_VERSION,
+            }),
+        },
         { path: `${dir}/refino-client.ts`, content: REFINO_CLIENT },
         { path: `${dir}/copy-editing.tsx`, content: COPY_EDITING_HOSTED },
         { path: `${dir}/edit-page.tsx`, content: EDIT_PAGE_HOSTED },

package/dist/types.d.ts

@@ -2,6 +2,7 @@
  * Structured results shared by the CLI and any future hosted onboarding.
  * Everything here is plain JSON-serializable data. No secrets, ever.
  */
+import type { InstallMethod } from "./install-method.js";
 export type PackageManager = "pnpm" | "npm" | "yarn" | "bun" | "unknown";
 export type Framework = "next" | "vite-react" | "react" | "unsupported";
 export type Router = "next-app" | "next-pages" | "react-router" | "single-page" | "unknown";
@@ -236,17 +237,23 @@ export interface MigrationPlan {
     };
     readonly unresolved: readonly string[];
 }
-/** Public identifiers of a site connected to Refino. Neither is a secret. */
+/** Public identifiers of a site connected to Refino. None of these is a secret. */
 export interface RefinoSite {
     readonly siteId: string;
     /** Origin of the Refino app, e.g. "https://app.refino.dev". */
     readonly appUrl: string;
+    /**
+     * What `refino init --via <method>` was told, or "unknown". Committed to
+     * the repository with the site id so the owner can see and change it.
+     */
+    readonly installMethod: InstallMethod;
 }
 export interface PlanOptions {
     /** Connect to Refino (hosted mode): the site id from the Refino dashboard, and optionally the app origin. */
     readonly refino?: {
         readonly siteId: string;
         readonly appUrl?: string;
+        readonly installMethod?: InstallMethod;
     };
     /** Routes to migrate. Defaults to ["/"] when the route exists. */
     readonly routes?: readonly string[];

package/dist/verify.js

@@ -143,7 +143,20 @@ function hostedChecks(appDir, inspection, hosted, sourceFiles, rendersProvider,
     else if (!siteText.includes(JSON.stringify(hosted.siteId)) || !siteText.includes(JSON.stringify(hosted.appUrl)))
         add({ id: "refino-site", status: "fail", message: `${siteFile} does not name site ${hosted.siteId} at ${hosted.appUrl} as ${CONFIG_FILE} does.`, fix: "Regenerate the module or fix the config so both agree." });
     else
-        add({ id: "refino-site", status: "pass", message: `Connected to Refino site ${hosted.siteId} at ${hosted.appUrl}.` });
+        add({
+            id: "refino-site",
+            status: "pass",
+            message: `Connected to Refino site ${hosted.siteId} at ${hosted.appUrl}.`,
+            // Deliberately a local check. Verification makes no network calls and
+            // holds no credential, so it can prove the repository agrees with
+            // itself and nothing more: whether this site id is still the one Refino
+            // has is a question only an authorized request can answer, and /edit
+            // asks it on every load.
+            details: [
+                "Checked in this repository only: Refino is never contacted from here, so this cannot prove the site id still exists.",
+                `If /edit says the site is not connected to your account, compare ${hosted.siteId} with the site id on your Refino dashboard and re-run \`refino init --agent --yes --refino-site <id>\` if they differ.`,
+            ],
+        });
     const missing = ["refino-client", "copy-editing", "edit-page"].filter((name) => !find(`${BOILERPLATE_DIR}/${name}`));
     if (missing.length > 0)
         add({ id: "refino-client", status: "fail", message: `Missing generated hosted modules: ${missing.map((name) => `${BOILERPLATE_DIR}/${name}`).join(", ")}.`, fix: "Run `refino init --agent --refino-site …` again; existing files are kept." });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/onboarding",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "description": "The engine behind `npx @getrefino/cli init`: deterministic repository inspection, copy discovery, migration planning, agent instructions and verification for adding Refino to an existing React site. Development tooling only; never part of a site's runtime.",
   "keywords": [
     "refino",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "typescript": ">=5.5 <7",
-    "@getrefino/core": "0.1.0-rc.1"
+    "@getrefino/core": "0.1.0-rc.2"
   },
   "devDependencies": {
     "@types/node": "22.20.2",