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

package/README.md

@@ -29,8 +29,16 @@ holds no credential — the deployed site's `/edit` flow is what checks that, an
 says so when the id is stale.
 
 All results are plain JSON. No network calls, no model calls. It never rewrites
-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.
+JSX, and it never overwrites a file the customer owns: the copy file,
+`package.json` and `.env.example` are merged, never replaced.
+
+Files Refino itself generates are different, because upgrading them is the
+point. `applyPlan` refreshes one only when it can prove the bytes on disk are
+still the ones Refino wrote — the sha256 recorded in `.refino/generated.json`,
+or the byte-exact output of a released template for sites installed before that
+file existed. A generated file with local changes is never overwritten: it is
+returned in `ApplyResult.generated` with status `review`, `needsReview` is
+true, and the current template is written beside it as `<file>.refino-new`.
+`verifyIntegration` reports the same three states without changing anything.
 
 <https://refino.dev>

package/dist/agent.d.ts

@@ -1,7 +1,3 @@
-/**
- * Render repository-specific instructions for a coding agent from a plan.
- * Every fact in the output comes from the plan; nothing is generic filler.
- */
 import { INSTRUCTIONS_FILE } from "./plan.js";
 import type { MigrationPlan } from "./types.js";
 export declare function renderAgentInstructions(plan: MigrationPlan): string;

package/dist/agent.js

@@ -2,6 +2,7 @@
  * Render repository-specific instructions for a coding agent from a plan.
  * Every fact in the output comes from the plan; nothing is generic filler.
  */
+import { GENERATED_MANIFEST_FILE } from "./generated.js";
 import { BOILERPLATE_DIR, CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE } from "./plan.js";
 function bullet(items) {
     return items.map((item) => `- ${item}`).join("\n");
@@ -198,7 +199,7 @@ ${bullet([
                 "Edit mode must come from an authenticated server check of the session: either a server-rendered `editing` flag or the generated wrapper's `GET /api/edit-session` probe. Never from `?edit=1`, localStorage or a hard-coded `true`.",
                 "Keep the existing deployment setup. Persistence defaults to the local file in development; production uses `COPY_ADAPTER=github` with the variables documented in `.env.example`.",
             ]),
-        `Do not edit \`${CONFIG_FILE}\`, \`${PLAN_FILE}\` or this file.`,
+        `Do not edit \`${CONFIG_FILE}\`, \`${PLAN_FILE}\`, \`${GENERATED_MANIFEST_FILE}\` or this file. They are the tool's record of what it did; \`${GENERATED_MANIFEST_FILE}\` in particular is how a later \`init\` tells a generated file nobody touched from one somebody did, so commit it with the rest.`,
     ])}
 
 ## Report format

package/dist/apply.js

@@ -1,16 +1,24 @@
 /**
- * Safe automatic changes. Everything here is additive and deterministic:
- * new files are written only if absent, the copy file is merged (existing
- * values never change), package.json gains dependencies, .env.example
- * gains a documented block. No JSX is rewritten.
+ * Safe automatic changes. Everything here is deterministic, and nothing the
+ * customer owns is ever overwritten: the copy file is merged (existing values
+ * never change), package.json gains dependencies, .env.example gains a
+ * documented block, and no JSX is rewritten.
+ *
+ * Refino's own generated files are different, and deliberately so. They used
+ * to be skipped whenever they existed, which is why a site that upgraded its
+ * `@getrefino/*` packages kept the previous release's generated runtime code
+ * and was still told the install had succeeded. They are now refreshed
+ * whenever Refino can prove the bytes on disk are the ones it wrote, left
+ * untouched when it cannot, and reported either way (generated.ts).
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseCopy, serializeCopy } from "@getrefino/core";
 import { renderAgentInstructions } from "./agent.js";
 import { exists, readJson, readText } from "./fs.js";
+import { GENERATED_MANIFEST_FILE, classifyGeneratedFiles, needsReview, nextGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.js";
 import { packageManagerInstall } from "./inspect.js";
-import { CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE, dependencyRange, planContent } from "./plan.js";
+import { CONFIG_FILE, INSTRUCTIONS_FILE, PLAN_FILE, TOOL_VERSION, dependencyRange, planContent } from "./plan.js";
 import { ENV_EXAMPLE_BLOCK, boilerplateFiles } from "./templates.js";
 function writeFile(root, relativePath, content, dryRun) {
     if (dryRun)
@@ -19,6 +27,19 @@ function writeFile(root, relativePath, content, dryRun) {
     mkdirSync(dirname(absolute), { recursive: true });
     writeFileSync(absolute, content, "utf8");
 }
+/**
+ * Why a generated file was rewritten. The site id matters as much as the
+ * version here: `--refino-site <id>` on a reconnected site is the only record
+ * the repository has of which Refino site it is, and a reader of the output
+ * needs to see that it moved.
+ */
+function describeUpdate(plan, state) {
+    const version = state.from && state.from !== state.to ? `${state.from} → ${state.to}` : `refreshed to ${state.to}`;
+    if (plan.refino && /(^|\/)refino-site\.[cm]?[jt]sx?$/.test(state.path)) {
+        return `${version}; names Refino site ${plan.refino.siteId} at ${plan.refino.appUrl}.`;
+    }
+    return `${version}; it was unchanged since Refino wrote it.`;
+}
 export function applyPlan(appDir, plan, options = {}) {
     const dryRun = options.dryRun ?? false;
     const written = [];
@@ -147,35 +168,51 @@ 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. 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)) {
-        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;
+    // 6. Generated boilerplate. Three outcomes, and which one applies is a
+    // fact about the bytes, never a guess:
+    //
+    //   absent, or provably still Refino's  -> written (created or refreshed)
+    //   already this version's output       -> skipped, nothing to do
+    //   edited since Refino wrote it        -> left alone, reported, and the
+    //                                          current template dropped beside
+    //                                          it so the difference is readable
+    //
+    // The manifest that makes the middle case decidable is written last, so a
+    // preserved file keeps the record of the version Refino *did* write and
+    // stays detectable on every later run.
+    const templates = boilerplateFiles(plan);
+    const manifest = readGeneratedManifest(appDir);
+    const generated = classifyGeneratedFiles(appDir, templates, manifest);
+    const byPath = new Map(templates.map((file) => [file.path, file]));
+    for (const state of generated) {
+        const template = byPath.get(state.path);
+        switch (state.status) {
+            case "create":
+                writeFile(appDir, state.path, template.content, dryRun);
+                written.push({ path: state.path, action: "create", description: "Generated boilerplate." });
+                break;
+            case "update":
+                writeFile(appDir, state.path, template.content, dryRun);
+                written.push({ path: state.path, action: "modify", description: describeUpdate(plan, state) });
+                break;
+            case "current":
+                skipped.push({ path: state.path, reason: `Already the ${state.to} version.` });
+                break;
+            case "customized":
+                skipped.push({ path: state.path, reason: state.reason });
+                break;
+            case "review":
+                // Never overwritten. The comparison copy carries the extension of the
+                // real file plus a suffix, so nothing compiles, lints or scans it.
+                writeFile(appDir, state.comparisonPath, template.content, dryRun);
+                skipped.push({ path: state.path, reason: `${state.reason} Refino's ${state.to} version is in ${state.comparisonPath} for comparison.` });
+                break;
         }
-        writeFile(appDir, file.path, file.content, dryRun);
-        written.push({ path: file.path, action: "create", description: "Generated boilerplate." });
     }
-    return { dryRun, written, skipped, installCommand };
+    // 7. The record of what was generated, so the next run can tell an
+    // untouched file from an edited one without reproducing old templates.
+    const updatedManifest = nextGeneratedManifest(templates, generated, manifest, TOOL_VERSION);
+    writeFile(appDir, GENERATED_MANIFEST_FILE, serializeGeneratedManifest(updatedManifest), dryRun);
+    written.push({ path: GENERATED_MANIFEST_FILE, action: manifest ? "modify" : "create", description: "What Refino generated, so an upgrade can tell untouched files from edited ones." });
+    return { dryRun, written, skipped, installCommand, generated, needsReview: needsReview(generated) };
 }

package/dist/generated.d.ts

@@ -0,0 +1,30 @@
+import type { TemplateFile } from "./templates.js";
+import type { GeneratedFileState, GeneratedManifest } from "./types.js";
+/** The repository's record of what Refino generated. Machine-owned, committed. */
+export declare const GENERATED_MANIFEST_FILE = ".refino/generated.json";
+/**
+ * Suffix for the copy of the current template Refino leaves beside a file it
+ * refused to overwrite. It goes *after* the real extension on purpose: a
+ * `.tsx.refino-new` file is not compiled, not linted and not scanned, so it
+ * cannot break a build while it waits to be read.
+ */
+export declare const COMPARISON_SUFFIX = ".refino-new";
+export declare function hashContent(text: string): string;
+export declare function readGeneratedManifest(appDir: string): GeneratedManifest | null;
+export declare function serializeGeneratedManifest(manifest: GeneratedManifest): string;
+/**
+ * Classify one generated file against the repository. Read-only: deciding and
+ * writing are separate so `verify` can ask the same question `init` asks
+ * without touching anything.
+ */
+export declare function classifyGeneratedFile(appDir: string, file: TemplateFile, manifest: GeneratedManifest | null): GeneratedFileState;
+export declare function classifyGeneratedFiles(appDir: string, files: readonly TemplateFile[], manifest: GeneratedManifest | null): GeneratedFileState[];
+/** A file whose bytes Refino is leaving behind although its template moved on. */
+export declare function needsReview(states: readonly GeneratedFileState[]): boolean;
+/**
+ * The manifest a run produces: what it wrote now, plus the entries for files
+ * it did not write. A preserved file keeps the record of the version Refino
+ * *did* write, which is exactly what makes its modification detectable on the
+ * next run.
+ */
+export declare function nextGeneratedManifest(files: readonly TemplateFile[], states: readonly GeneratedFileState[], previous: GeneratedManifest | null, toolVersion: string): GeneratedManifest;

package/dist/generated.js

@@ -0,0 +1,168 @@
+/**
+ * Ownership and versioning of the files Refino generates.
+ *
+ * The problem this solves: `init` used to skip every file that already
+ * existed, so a site that upgraded its `@getrefino/*` dependencies kept the
+ * previous release's generated runtime code and was told the install had
+ * succeeded. Package versions cannot answer the question -- installing a
+ * package does not refresh a file that was copied into the repository months
+ * earlier -- so the repository has to carry its own record.
+ *
+ * That record is `.refino/generated.json`: for every file Refino wrote, the
+ * sha256 of the exact bytes it wrote and the version that wrote them. With
+ * it, three states are decidable without guessing:
+ *
+ *   on disk == generated now            -> current, leave it alone
+ *   on disk == what Refino wrote        -> stale but untouched, refresh it
+ *   anything else                       -> the owner's file, never overwritten
+ *
+ * Sites installed before the manifest existed have no record, so each
+ * template also carries the byte-exact renderings earlier releases produced
+ * (`previous`, from templates-legacy.ts). Reproducing those bytes is proof of
+ * the same kind: a file that still matches a released rendering has not been
+ * edited, whatever the manifest does or does not say.
+ *
+ * Nothing here ever writes over a file it cannot prove is Refino's.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { exists, readJson, readText } from "./fs.js";
+import { PLAN_DIR } from "./plan.js";
+/** The repository's record of what Refino generated. Machine-owned, committed. */
+export const GENERATED_MANIFEST_FILE = `${PLAN_DIR}/generated.json`;
+/**
+ * Suffix for the copy of the current template Refino leaves beside a file it
+ * refused to overwrite. It goes *after* the real extension on purpose: a
+ * `.tsx.refino-new` file is not compiled, not linted and not scanned, so it
+ * cannot break a build while it waits to be read.
+ */
+export const COMPARISON_SUFFIX = ".refino-new";
+export function hashContent(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function readGeneratedManifest(appDir) {
+    const manifest = readJson(join(appDir, GENERATED_MANIFEST_FILE));
+    if (!manifest || manifest.version !== 1 || typeof manifest.files !== "object" || manifest.files === null)
+        return null;
+    return manifest;
+}
+export function serializeGeneratedManifest(manifest) {
+    const files = Object.fromEntries(Object.keys(manifest.files).sort().map((path) => [path, manifest.files[path]]));
+    return `${JSON.stringify({ ...manifest, files }, null, 2)}\n`;
+}
+/**
+ * Which release's output the bytes on disk are, or null when they are not any
+ * release's output. `file.recognize` exists for templates whose bytes depend
+ * on the site (the Refino constants module carries the site id): it reads the
+ * per-site values back out of the file and re-renders, so "unmodified" stays
+ * a byte comparison rather than a resemblance.
+ */
+function matchRendering(file, current) {
+    if (current === file.content)
+        return { version: file.version };
+    for (const rendering of file.previous ?? []) {
+        if (current === rendering.content)
+            return { version: rendering.version };
+    }
+    return file.recognize?.(current) ?? null;
+}
+/** Was `sha` written by a rendering whose bytes are still what this version generates? */
+function renderingIsCurrent(file, sha) {
+    if (sha === hashContent(file.content))
+        return true;
+    for (const rendering of file.previous ?? []) {
+        if (sha === hashContent(rendering.content))
+            return false;
+    }
+    return null;
+}
+/**
+ * Classify one generated file against the repository. Read-only: deciding and
+ * writing are separate so `verify` can ask the same question `init` asks
+ * without touching anything.
+ */
+export function classifyGeneratedFile(appDir, file, manifest) {
+    const to = file.version;
+    const base = { path: file.path, ownership: file.ownership, to };
+    const absolute = join(appDir, file.path);
+    if (!exists(absolute)) {
+        return { ...base, status: "create", from: null, reason: "Not present; generated by this run." };
+    }
+    const current = readText(absolute) ?? "";
+    const recorded = manifest?.files[file.path];
+    if (current === file.content) {
+        return { ...base, status: "current", from: to, reason: `Already the ${to} version.` };
+    }
+    // Untouched since Refino wrote it: the manifest says so, or the bytes still
+    // reproduce a released rendering. Either is proof; neither is a heuristic.
+    if (recorded && hashContent(current) === recorded.sha256) {
+        return { ...base, status: "update", from: recorded.toolVersion, reason: `Unchanged since Refino ${recorded.toolVersion} wrote it.` };
+    }
+    const rendering = matchRendering(file, current);
+    if (rendering) {
+        return { ...base, status: "update", from: rendering.version, reason: `Byte-identical to the ${rendering.version} template.` };
+    }
+    // The file has been edited. Whether that matters depends on whether
+    // Refino's own version of it moved since: a customized file generated from
+    // a template that has not changed is simply the owner's file, and saying
+    // anything about it would be noise.
+    if (recorded) {
+        const stillCurrent = renderingIsCurrent(file, recorded.sha256);
+        if (stillCurrent === true) {
+            return { ...base, status: "customized", from: recorded.toolVersion, reason: `Edited since Refino ${recorded.toolVersion} wrote it; that template has not changed since.` };
+        }
+        if (stillCurrent === false) {
+            return {
+                ...base,
+                status: "review",
+                from: recorded.toolVersion,
+                reason: `Edited since Refino ${recorded.toolVersion} wrote it, and Refino's version has changed (${recorded.toolVersion} → ${to}). Refreshing it would discard those edits.`,
+                comparisonPath: `${file.path}${COMPARISON_SUFFIX}`,
+            };
+        }
+        return {
+            ...base,
+            status: "review",
+            from: recorded.toolVersion,
+            reason: `Neither the bytes on disk nor the bytes Refino ${recorded.toolVersion} recorded match any template this version knows, so it cannot be proved safe to refresh.`,
+            comparisonPath: `${file.path}${COMPARISON_SUFFIX}`,
+        };
+    }
+    return {
+        ...base,
+        status: "review",
+        from: null,
+        reason: `Differs from every Refino template and predates ${GENERATED_MANIFEST_FILE}, so it cannot be proved untouched.`,
+        comparisonPath: `${file.path}${COMPARISON_SUFFIX}`,
+    };
+}
+export function classifyGeneratedFiles(appDir, files, manifest) {
+    return files.map((file) => classifyGeneratedFile(appDir, file, manifest));
+}
+/** A file whose bytes Refino is leaving behind although its template moved on. */
+export function needsReview(states) {
+    return states.some((state) => state.status === "review");
+}
+/**
+ * The manifest a run produces: what it wrote now, plus the entries for files
+ * it did not write. A preserved file keeps the record of the version Refino
+ * *did* write, which is exactly what makes its modification detectable on the
+ * next run.
+ */
+export function nextGeneratedManifest(files, states, previous, toolVersion) {
+    const byPath = new Map(files.map((file) => [file.path, file]));
+    const entries = {};
+    for (const state of states) {
+        const file = byPath.get(state.path);
+        if (!file)
+            continue;
+        if (state.status === "create" || state.status === "update" || state.status === "current") {
+            entries[state.path] = { ownership: file.ownership, toolVersion: file.version, sha256: hashContent(file.content) };
+            continue;
+        }
+        const recorded = previous?.files[state.path];
+        if (recorded)
+            entries[state.path] = recorded;
+    }
+    return { version: 1, tool: toolVersion, files: entries };
+}

package/dist/index.d.ts

@@ -8,11 +8,12 @@ export { renderAgentInstructions } from "./agent.js";
 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 type { TemplateFile, TemplateRendering } from "./templates.js";
+export { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.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";
-export type { ApplyResult, CandidateStatus, CheckStatus, CopyCandidate, CopyClassification, DetectedPackage, Framework, GitState, HostIntegration, HostKind, Language, MigrationPlan, PackageManager, PlanOptions, PlannedFile, RefinoSite, RepositoryInspection, RouteInfo, Router, ScanResult, ScriptSet, VerificationCheck, VerificationResult, } from "./types.js";
+export type { ApplyResult, CandidateStatus, CheckStatus, CopyCandidate, CopyClassification, DetectedPackage, Framework, GeneratedFileState, GeneratedFileStatus, GeneratedManifest, GeneratedManifestEntry, GeneratedOwnership, GitState, HostIntegration, HostKind, Language, MigrationPlan, PackageManager, PlanOptions, PlannedFile, RefinoSite, RepositoryInspection, RouteInfo, Router, ScanResult, ScriptSet, VerificationCheck, VerificationResult, } from "./types.js";

package/dist/index.js

@@ -5,6 +5,7 @@ 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 { COMPARISON_SUFFIX, GENERATED_MANIFEST_FILE, classifyGeneratedFile, classifyGeneratedFiles, hashContent, needsReview, nextGeneratedManifest, readGeneratedManifest, serializeGeneratedManifest, } from "./generated.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/template-file.d.ts

@@ -0,0 +1,38 @@
+import type { GeneratedOwnership, Language } from "./types.js";
+export interface TemplateRendering {
+    /** Refino version that wrote these bytes. */
+    readonly version: string;
+    readonly content: string;
+}
+export interface TemplateFile {
+    readonly path: string;
+    readonly content: string;
+    readonly ownership: GeneratedOwnership;
+    /** Refino version that generates `content`. */
+    readonly version: string;
+    /** Byte-exact bodies earlier releases wrote for this path, newest first. */
+    readonly previous?: readonly TemplateRendering[];
+    /**
+     * For templates whose bytes depend on the site (the Refino constants module
+     * carries the site id and the install facts): read those values back out of
+     * the file, re-render, and report which release's output the file is -- or
+     * null when it is nobody's output. Never a resemblance test.
+     */
+    readonly recognize?: (current: string) => TemplateRendering | null;
+}
+/** As above, but handed the language-appropriate renderer for candidate bytes. */
+export type TemplateRecognizer = (current: string, render: (source: string) => string) => TemplateRendering | null;
+export interface TemplateExtras {
+    readonly previous?: readonly TemplateRendering[];
+    readonly recognize?: TemplateRecognizer;
+}
+/**
+ * Builds the generated files for one project. Everything a caller needs to
+ * say is the ownership class; the version stamp and the language emit are the
+ * same for every file and are applied here.
+ */
+export interface TemplateFactory {
+    machine(path: string, content: string, extras?: TemplateExtras): TemplateFile;
+    scaffold(path: string, content: string, extras?: TemplateExtras): TemplateFile;
+}
+export declare function createTemplateFactory(language: Language): TemplateFactory;

package/dist/template-file.js

@@ -0,0 +1,44 @@
+/**
+ * How a generated file is described: its bytes, who owns it, the Refino
+ * version that produced it, and enough history to recognise the bytes an
+ * earlier release would have written.
+ *
+ * Templates are authored once in TypeScript and emitted per project, so the
+ * language choice is made here rather than after the fact: a JavaScript
+ * project's history and recognizers are transpiled with exactly the same
+ * function as its current content, which is what keeps "these bytes are an
+ * earlier Refino's output" a byte comparison in both languages.
+ */
+import ts from "typescript";
+import { TOOL_VERSION } from "./plan.js";
+function transpile(path, source) {
+    const output = ts.transpileModule(source, {
+        compilerOptions: {
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.ESNext,
+            jsx: ts.JsxEmit.Preserve,
+            removeComments: false,
+            verbatimModuleSyntax: false,
+        },
+        fileName: path,
+    });
+    return output.outputText.replace(/^export \{\};\s*$/m, "").replace(/\n{3,}/g, "\n\n");
+}
+function jsPath(path) {
+    return path.replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js");
+}
+export function createTemplateFactory(language) {
+    const javascript = language === "javascript";
+    const build = (ownership) => (path, content, extras = {}) => {
+        const render = (source) => (javascript ? transpile(path, source) : source);
+        return {
+            path: javascript ? jsPath(path) : path,
+            content: render(content),
+            ownership,
+            version: TOOL_VERSION,
+            ...(extras.previous ? { previous: extras.previous.map((rendering) => ({ version: rendering.version, content: render(rendering.content) })) } : {}),
+            ...(extras.recognize ? { recognize: (current) => extras.recognize(current, render) } : {}),
+        };
+    };
+    return { machine: build("machine"), scaffold: build("scaffold") };
+}

package/dist/templates-hosted.d.ts

@@ -1,17 +1,6 @@
-/**
- * Boilerplate for a site connected to Refino (hosted mode). Everything runs
- * in the browser: the site holds two public constants and no secrets, no
- * copy endpoint, no session endpoint and no repository credential. Refino
- * authenticates the owner, authorizes the site, and loads and saves the
- * copy file in the repository.
- *
- *   /edit  → Refino /editor/authorize (PKCE) → back to /edit?code&state
- *          → 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 { TemplateFactory, TemplateFile } from "./template-file.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;
@@ -46,4 +35,4 @@ export declare const EDIT_LAYOUT_HOSTED = "import type { Metadata } from \"next\
 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[];
+export declare function hostedFiles(plan: MigrationPlan, factory?: TemplateFactory): TemplateFile[];

package/dist/templates-hosted.js

@@ -1,4 +1,18 @@
+/**
+ * Boilerplate for a site connected to Refino (hosted mode). Everything runs
+ * in the browser: the site holds two public constants and no secrets, no
+ * copy endpoint, no session endpoint and no repository credential. Refino
+ * authenticates the owner, authorizes the site, and loads and saves the
+ * copy file in the repository.
+ *
+ *   /edit  → Refino /editor/authorize (PKCE) → back to /edit?code&state
+ *          → POST Refino /api/editor/token → 12 h editor token in sessionStorage
+ *          → <RefinoProvider endpoint={Refino copy API} headers={bearer}>
+ */
+import { isInstallMethod } from "./install-method.js";
 import { TOOL_VERSION } from "./plan.js";
+import { createTemplateFactory } from "./template-file.js";
+import { COPY_EDITING_HOSTED_RC1, RC1, REFINO_CLIENT_RC1, REFINO_SITE_RC1 } from "./templates-legacy.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. */
@@ -398,35 +412,70 @@ export function analyticsHosting(hosting) {
         return "unknown";
     return ["cloudflare", "vercel", "netlify"].includes(hosting) ? hosting : "other";
 }
+/**
+ * Recognise an earlier Refino's `refino/refino-site` module.
+ *
+ * This is the one generated file whose bytes depend on the site, so "is it
+ * untouched?" cannot be a lookup: the site id, the app URL and the install
+ * facts are read back out of the file, each released shape is re-rendered
+ * from exactly those values, and the result is compared byte for byte. A file
+ * that round-trips is that release's output and nothing else; a file that
+ * does not is the owner's and is never overwritten.
+ *
+ * It also answers the question the manifest cannot for a reconnected site:
+ * after `--refino-site <new id>` the generated bytes name a different site, so
+ * only re-rendering with the *old* id can show the file was untouched.
+ */
+const recognizeSiteModule = (current, render) => {
+    const siteId = /REFINO_SITE_ID\s*=\s*"(site_[a-f0-9]{32})"/.exec(current)?.[1];
+    const appUrl = /REFINO_APP_URL\s*=\s*"([^"]+)"/.exec(current)?.[1];
+    if (!siteId || !appUrl)
+        return null;
+    // Before the install facts existed there was nothing else to read.
+    if (render(REFINO_SITE_RC1({ siteId, appUrl })) === current)
+        return { version: RC1, content: current };
+    const read = (key) => new RegExp(`${key}:\\s*"([^"]*)"`).exec(current)?.[1];
+    const method = read("method");
+    const framework = read("framework");
+    const hosting = read("hosting");
+    const packageVersion = read("packageVersion");
+    if (method === undefined || framework === undefined || hosting === undefined || packageVersion === undefined)
+        return null;
+    if (!isInstallMethod(method))
+        return null;
+    const rendered = render(REFINO_SITE({ siteId, appUrl, installMethod: method, framework, hosting, packageVersion }));
+    return rendered === current ? { version: packageVersion, content: current } : null;
+};
+/** What 0.1.0-rc.1 wrote for the two hosted modules whose bodies have changed since. */
+const RC1_CLIENT = { version: RC1, content: REFINO_CLIENT_RC1 };
+const RC1_COPY_EDITING = { version: RC1, content: COPY_EDITING_HOSTED_RC1 };
 /** Files for a Refino-connected site. No server code, no secrets, in any framework. */
-export function hostedFiles(plan) {
+export function hostedFiles(plan, factory) {
     const refino = plan.refino;
     if (!refino)
         return [];
+    const make = factory ?? createTemplateFactory(plan.repository.language);
     const dir = plan.integration.boilerplateDir;
     const files = [
-        {
-            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 },
+        make.machine(`${dir}/refino-site.ts`, REFINO_SITE({
+            ...refino,
+            framework: analyticsFramework(plan.repository.framework),
+            hosting: analyticsHosting(plan.repository.hosting),
+            packageVersion: TOOL_VERSION,
+        }), { recognize: recognizeSiteModule }),
+        make.machine(`${dir}/refino-client.ts`, REFINO_CLIENT, { previous: [RC1_CLIENT] }),
+        make.machine(`${dir}/copy-editing.tsx`, COPY_EDITING_HOSTED, { previous: [RC1_COPY_EDITING] }),
+        make.scaffold(`${dir}/edit-page.tsx`, EDIT_PAGE_HOSTED),
     ];
     const editPage = plan.files.find((file) => /(^|\/)edit(\/page)?\.\w+$/.test(file.path) && !file.path.startsWith(`${dir}/`))?.path;
     if (plan.repository.router === "next-app") {
         const routesDir = editPage?.replace(/\/edit\/page\.\w+$/, "") ?? "app";
-        files.push({ path: `${routesDir}/edit/layout.tsx`, content: EDIT_LAYOUT_HOSTED });
-        files.push({ path: `${routesDir}/edit/page.tsx`, content: EDIT_ROUTE_NEXT_HOSTED(relativeImport(`${routesDir}/edit/page.tsx`, `${dir}/edit-page.tsx`)) });
+        files.push(make.machine(`${routesDir}/edit/layout.tsx`, EDIT_LAYOUT_HOSTED));
+        files.push(make.machine(`${routesDir}/edit/page.tsx`, EDIT_ROUTE_NEXT_HOSTED(relativeImport(`${routesDir}/edit/page.tsx`, `${dir}/edit-page.tsx`))));
     }
     else if (plan.repository.router === "next-pages") {
         const routesDir = editPage?.replace(/\/edit\.\w+$/, "") ?? "pages";
-        files.push({ path: `${routesDir}/edit.tsx`, content: EDIT_PAGE_NEXT_PAGES_HOSTED(relativeImport(`${routesDir}/edit.tsx`, `${dir}/edit-page.tsx`)) });
+        files.push(make.machine(`${routesDir}/edit.tsx`, EDIT_PAGE_NEXT_PAGES_HOSTED(relativeImport(`${routesDir}/edit.tsx`, `${dir}/edit-page.tsx`))));
     }
     return files;
 }

package/dist/templates-legacy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Byte-exact renderings of generated files as earlier Refino releases wrote
+ * them. They exist for one reason: a site onboarded before .refino/generated.json
+ * existed carries no record of what Refino wrote, so the only way to prove a
+ * generated file is untouched is to reproduce the old bytes and compare.
+ *
+ * Nothing here is ever written to a repository. It is read-only evidence.
+ *
+ * Maintenance: when a template body in templates.ts or templates-hosted.ts
+ * changes, copy the previous body here and list it in that file's `previous`
+ * renderings. `generated-templates.test.ts` fails until you do, because it
+ * pins the hash of every generated file.
+ */
+export interface LegacySiteConfig {
+    readonly siteId: string;
+    readonly appUrl: string;
+}
+/** The last release that wrote the bodies below. */
+export declare const RC1 = "0.1.0-rc.1";
+/** 0.1.0-rc.1 refino/refino-site.ts: the two public constants, before REFINO_INSTALL. */
+export declare const REFINO_SITE_RC1: (config: LegacySiteConfig) => string;
+/** 0.1.0-rc.1 refino/refino-client.ts: before reportEditorEvent and the install facts. */
+export declare const REFINO_CLIENT_RC1 = "/**\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";
+/** 0.1.0-rc.1 refino/copy-editing.tsx: before onEvent={reportEditorEvent}. */
+export declare const COPY_EDITING_HOSTED_RC1 = "\"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";

package/dist/templates-legacy.js

@@ -0,0 +1,221 @@
+/**
+ * Byte-exact renderings of generated files as earlier Refino releases wrote
+ * them. They exist for one reason: a site onboarded before .refino/generated.json
+ * existed carries no record of what Refino wrote, so the only way to prove a
+ * generated file is untouched is to reproduce the old bytes and compare.
+ *
+ * Nothing here is ever written to a repository. It is read-only evidence.
+ *
+ * Maintenance: when a template body in templates.ts or templates-hosted.ts
+ * changes, copy the previous body here and list it in that file's `previous`
+ * renderings. `generated-templates.test.ts` fails until you do, because it
+ * pins the hash of every generated file.
+ */
+/** The last release that wrote the bodies below. */
+export const RC1 = "0.1.0-rc.1";
+/** 0.1.0-rc.1 refino/refino-site.ts: the two public constants, before REFINO_INSTALL. */
+export const REFINO_SITE_RC1 = (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.
+ */
+export const REFINO_SITE_ID = ${JSON.stringify(config.siteId)};
+export const REFINO_APP_URL = ${JSON.stringify(config.appUrl)};
+`;
+/** 0.1.0-rc.1 refino/refino-client.ts: before reportEditorEvent and the install facts. */
+export const REFINO_CLIENT_RC1 = `/**
+ * Browser-side Refino editor authorization for this site. No secrets here:
+ * the site is a public client (OAuth 2.1 with PKCE). The editor token lives
+ * in sessionStorage only (never localStorage, never a URL), is scoped to
+ * 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";
+
+const PKCE_KEY = "refino.pkce";
+const SESSION_KEY = "refino.editor";
+const CALLBACK_PATH = "/edit";
+
+export interface EditorSession {
+  readonly token: string;
+  /** Unix seconds. */
+  readonly expiresAt: number;
+  readonly siteId: string;
+}
+
+interface PendingAuthorization {
+  readonly verifier: string;
+  readonly state: string;
+  readonly returnTo: string;
+}
+
+function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\\+/g, "-").replace(/\\//g, "_").replace(/=+$/, "");
+}
+
+function randomToken(bytes: number): string {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return base64url(buffer);
+}
+
+async function sha256(text: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return base64url(new Uint8Array(digest));
+}
+
+function storage(): Storage | null {
+  try {
+    return typeof window === "undefined" ? null : window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readJson<T>(key: string): T | null {
+  const raw = storage()?.getItem(key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Only a path on this site, never another origin. */
+export function safeReturnTo(value: string | null | undefined): string {
+  if (!value || !value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\\\") || value.length > 512) return "/";
+  return value;
+}
+
+export function editorEndpoint(): string {
+  return \`\${REFINO_APP_URL}/api/sites/\${REFINO_SITE_ID}/copy\`;
+}
+
+export function callbackUrl(): string {
+  return \`\${window.location.origin}\${CALLBACK_PATH}\`;
+}
+
+/** The current editor session, or null when there is none or it expired. */
+export function readEditorSession(nowSeconds: number = Math.floor(Date.now() / 1000)): EditorSession | null {
+  const session = readJson<EditorSession>(SESSION_KEY);
+  if (!session || typeof session.token !== "string" || session.siteId !== REFINO_SITE_ID || typeof session.expiresAt !== "number") return null;
+  if (session.expiresAt <= nowSeconds) {
+    storage()?.removeItem(SESSION_KEY);
+    return null;
+  }
+  return session;
+}
+
+export function clearEditorSession(): void {
+  storage()?.removeItem(SESSION_KEY);
+  storage()?.removeItem(PKCE_KEY);
+}
+
+/** Start the flow: remember the PKCE verifier and state, then go to Refino. */
+export async function beginAuthorization(returnTo: string): Promise<void> {
+  const verifier = randomToken(32);
+  const state = randomToken(16);
+  const pending: PendingAuthorization = { verifier, state, returnTo: safeReturnTo(returnTo) };
+  storage()?.setItem(PKCE_KEY, JSON.stringify(pending));
+  const params = new URLSearchParams({
+    site_id: REFINO_SITE_ID,
+    redirect_uri: callbackUrl(),
+    code_challenge: await sha256(verifier),
+    code_challenge_method: "S256",
+    state,
+  });
+  window.location.assign(\`\${REFINO_APP_URL}/editor/authorize?\${params.toString()}\`);
+}
+
+export type AuthorizationResult = { readonly ok: true; readonly returnTo: string } | { readonly ok: false; readonly error: string };
+
+/**
+ * Finish the flow on /edit?code&state: check the state, exchange the code
+ * with the verifier this browser kept, store the session, and scrub the
+ * code from the URL. The token is never placed in a URL.
+ */
+export async function completeAuthorization(search: string = window.location.search): Promise<AuthorizationResult> {
+  const params = new URLSearchParams(search);
+  const code = params.get("code");
+  const state = params.get("state");
+  const pending = readJson<PendingAuthorization>(PKCE_KEY);
+  storage()?.removeItem(PKCE_KEY);
+  if (typeof window !== "undefined" && window.history.replaceState) window.history.replaceState(null, "", window.location.pathname);
+  if (!code || !state) return { ok: false, error: "Refino did not return an authorization code." };
+  if (!pending || pending.state !== state) return { ok: false, error: "Sign-in was interrupted (state mismatch). Start again." };
+
+  let response: Response;
+  try {
+    response = await fetch(\`\${REFINO_APP_URL}/api/editor/token\`, {
+      method: "POST",
+      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() }),
+    });
+  } catch {
+    return { ok: false, error: "Could not reach Refino to finish signing in." };
+  }
+  const body = (await response.json().catch(() => null)) as { ok?: boolean; token?: string; expiresAt?: number; siteId?: string; error?: { message?: string } } | null;
+  if (!response.ok || !body?.ok || typeof body.token !== "string" || typeof body.expiresAt !== "number" || body.siteId !== REFINO_SITE_ID) {
+    return { ok: false, error: body?.error?.message ?? "Refino did not accept the authorization." };
+  }
+  const session: EditorSession = { token: body.token, expiresAt: body.expiresAt, siteId: body.siteId };
+  storage()?.setItem(SESSION_KEY, JSON.stringify(session));
+  return { ok: true, returnTo: pending.returnTo };
+}
+`;
+/** 0.1.0-rc.1 refino/copy-editing.tsx: before onEvent={reportEditorEvent}. */
+export const COPY_EDITING_HOSTED_RC1 = `"use client";
+
+import type { CopyContent } from "@getrefino/core";
+import { RefinoProvider } from "@getrefino/react";
+import type { ReactNode } from "react";
+import { useCallback, useEffect, useState } from "react";
+
+import { clearEditorSession, editorEndpoint, readEditorSession } from "./refino-client";
+import type { EditorSession } from "./refino-client";
+
+interface CopyEditingProps {
+  content: CopyContent;
+  children: ReactNode;
+}
+
+/**
+ * Hosted mode (Refino). Visitors get the plain site: the server never
+ * decides edit mode, so pages can stay static. In the browser, an editor
+ * session stored by /edit turns edit mode on; loads and saves go to Refino
+ * with the session's bearer token, and Refino checks the site's
+ * entitlement on every request.
+ */
+export function CopyEditing({ content, children }: CopyEditingProps) {
+  const [session, setSession] = useState<EditorSession | null>(null);
+
+  useEffect(() => {
+    // Read the session only after mount so server-rendered HTML never differs from the visitor's.
+    setSession(readEditorSession());
+  }, []);
+
+  // Read at request time (the provider keeps its options from the first render), so the
+  // token is always the one currently stored and never sent once the session is cleared.
+  const headers = useCallback((): Record<string, string> => {
+    const current = readEditorSession();
+    return current ? { authorization: \`Bearer \${current.token}\` } : {};
+  }, []);
+
+  const onExit = useCallback(async () => {
+    clearEditorSession();
+    window.location.assign("/");
+  }, []);
+
+  return (
+    <RefinoProvider content={content} editing={session !== null} endpoint={editorEndpoint()} headers={headers} signInHref="/edit" onExit={onExit}>
+      {children}
+    </RefinoProvider>
+  );
+}
+`;

package/dist/templates.d.ts

@@ -1,8 +1,6 @@
+import type { TemplateFile } from "./template-file.js";
 import type { MigrationPlan } from "./types.js";
-export interface TemplateFile {
-    readonly path: string;
-    readonly content: string;
-}
+export type { TemplateFile, TemplateRendering } from "./template-file.js";
 export declare const ENV_EXAMPLE_BLOCK = "\n# --- Refino (server-side only; never expose with NEXT_PUBLIC_/VITE_) ---\n# Edit-mode login. Both required in production; development falls back to password \"edit\".\nEDITOR_PASSWORD=\nEDITOR_SESSION_SECRET=\n# Persistence: \"local\" writes the copy file on disk (development), \"github\" commits it.\nCOPY_ADAPTER=local\n# GitHub persistence (COPY_ADAPTER=github): fine-grained token, Contents read/write, one repo.\nCOPY_GITHUB_TOKEN=\nCOPY_GITHUB_REPO=owner/name\nCOPY_GITHUB_BRANCH=main\nCOPY_FILE_PATH=\n";
 /** Files the apply step may create for a plan, in TS or JS as the project requires. */
 export declare function boilerplateFiles(plan: MigrationPlan): TemplateFile[];

package/dist/templates.js

@@ -1,11 +1,17 @@
 /**
- * Boilerplate written by `refino init --apply`. Each file is isolated
- * under `refino/` (or is a new route file) and is only written when it
- * does not already exist. Authored in TypeScript; JavaScript projects get a
- * transpiled copy.
+ * Boilerplate written by `refino init --agent`. Each file is isolated under
+ * `refino/` (or is a new route file). Authored in TypeScript; JavaScript
+ * projects get a transpiled copy.
+ *
+ * A file that already exists is refreshed only when Refino can prove the
+ * bytes on disk are still the ones it wrote (generated.ts); otherwise it is
+ * left exactly as it is and reported. Each entry therefore declares who owns
+ * it -- `machine` for Refino's runtime code, `scaffold` for a page the owner
+ * is invited to restyle -- and, when its body has changed since a released
+ * version, the byte-exact body that version wrote.
  */
-import ts from "typescript";
 import { BOILERPLATE_DIR } from "./plan.js";
+import { createTemplateFactory } from "./template-file.js";
 import { hostedFiles } from "./templates-hosted.js";
 const BOILERPLATE_DIR_NAME = BOILERPLATE_DIR;
 function relativeImport(fromFile, toFile) {
@@ -601,71 +607,56 @@ COPY_GITHUB_REPO=owner/name
 COPY_GITHUB_BRANCH=main
 COPY_FILE_PATH=
 `;
-function transpileToJs(path, source) {
-    const output = ts.transpileModule(source, {
-        compilerOptions: {
-            target: ts.ScriptTarget.ES2022,
-            module: ts.ModuleKind.ESNext,
-            jsx: ts.JsxEmit.Preserve,
-            removeComments: false,
-            verbatimModuleSyntax: false,
-        },
-        fileName: path,
-    });
-    return { path: path.replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js"), content: output.outputText.replace(/^export \{\};\s*$/m, "").replace(/\n{3,}/g, "\n\n") };
-}
 /** Files the apply step may create for a plan, in TS or JS as the project requires. */
 export function boilerplateFiles(plan) {
-    if (plan.refino) {
-        const files = hostedFiles(plan);
-        return plan.repository.language === "javascript" ? files.map((file) => transpileToJs(file.path, file.content)) : files;
-    }
+    const make = createTemplateFactory(plan.repository.language);
+    if (plan.refino)
+        return hostedFiles(plan, make);
     const dir = plan.integration.boilerplateDir;
     const strategy = plan.integration.provider.strategy;
     const host = plan.integration.host;
     // Server-rendered hosts pass `editing` from a cookie check; everything else probes the session in the browser.
     const serverRenderedEditing = strategy === "next-app-root-layout" || strategy === "next-pages-app";
     const handlers = `${dir}/request-handlers.ts`;
+    // The self-hosted templates below are byte-identical to every release so
+    // far, so none of them carries a `previous` rendering yet.
     const files = [
-        { path: `${dir}/editor-auth.ts`, content: EDITOR_AUTH },
-        { path: `${dir}/content-adapter.ts`, content: CONTENT_ADAPTER(plan.contentFile.path) },
-        { path: handlers, content: REQUEST_HANDLERS },
-        { path: `${dir}/copy-editing.tsx`, content: serverRenderedEditing ? COPY_EDITING : COPY_EDITING_CLIENT_SESSION },
+        make.machine(`${dir}/editor-auth.ts`, EDITOR_AUTH),
+        make.machine(`${dir}/content-adapter.ts`, CONTENT_ADAPTER(plan.contentFile.path)),
+        make.machine(handlers, REQUEST_HANDLERS),
+        make.machine(`${dir}/copy-editing.tsx`, serverRenderedEditing ? COPY_EDITING : COPY_EDITING_CLIENT_SESSION),
     ];
     if (strategy === "next-app-root-layout-client-session") {
         const routesDir = plan.files.find((file) => /\/edit\/page\.\w+$/.test(file.path))?.path.replace(/\/edit\/page\.\w+$/, "") ?? "app";
-        files.push({ path: `${routesDir}/edit/layout.tsx`, content: EDIT_LAYOUT_STATIC });
-        files.push({ path: `${routesDir}/edit/page.tsx`, content: EDIT_PAGE_STATIC });
+        files.push(make.scaffold(`${routesDir}/edit/layout.tsx`, EDIT_LAYOUT_STATIC));
+        files.push(make.scaffold(`${routesDir}/edit/page.tsx`, EDIT_PAGE_STATIC));
     }
     const copyFile = host.copyEndpoint.replace(/\.\w+$/, ".ts");
     const sessionFile = host.sessionEndpoint.replace(/\.\w+$/, ".ts");
     switch (host.kind) {
         case "next-route-handlers": {
             const editPage = `${copyFile.replace(/\/api\/copy\/route\.ts$/, "")}/edit/page.tsx`;
-            files.push({ path: `${dir}/editor-session.ts`, content: EDITOR_SESSION_NEXT });
-            files.push({ path: copyFile, content: COPY_ROUTE_NEXT(relativeImport(copyFile, handlers)) });
-            files.push({ path: sessionFile, content: SESSION_ROUTE_NEXT(relativeImport(sessionFile, handlers)) });
-            files.push({ path: editPage, content: EDIT_PAGE_NEXT(relativeImport(editPage, `${dir}/editor-session.ts`)) });
+            files.push(make.machine(`${dir}/editor-session.ts`, EDITOR_SESSION_NEXT));
+            files.push(make.machine(copyFile, COPY_ROUTE_NEXT(relativeImport(copyFile, handlers))));
+            files.push(make.machine(sessionFile, SESSION_ROUTE_NEXT(relativeImport(sessionFile, handlers))));
+            files.push(make.scaffold(editPage, EDIT_PAGE_NEXT(relativeImport(editPage, `${dir}/editor-session.ts`))));
             break;
         }
         case "cloudflare-pages-functions":
-            files.push({ path: copyFile, content: CLOUDFLARE_FUNCTION("copy", relativeImport(copyFile, handlers)) });
-            files.push({ path: sessionFile, content: CLOUDFLARE_FUNCTION("edit-session", relativeImport(sessionFile, handlers)) });
+            files.push(make.machine(copyFile, CLOUDFLARE_FUNCTION("copy", relativeImport(copyFile, handlers))));
+            files.push(make.machine(sessionFile, CLOUDFLARE_FUNCTION("edit-session", relativeImport(sessionFile, handlers))));
             break;
         case "netlify-functions":
-            files.push({ path: copyFile, content: NETLIFY_FUNCTION("copy", relativeImport(copyFile, handlers)) });
-            files.push({ path: sessionFile, content: NETLIFY_FUNCTION("edit-session", relativeImport(sessionFile, handlers)) });
+            files.push(make.machine(copyFile, NETLIFY_FUNCTION("copy", relativeImport(copyFile, handlers))));
+            files.push(make.machine(sessionFile, NETLIFY_FUNCTION("edit-session", relativeImport(sessionFile, handlers))));
             break;
         case "vercel-functions":
-            files.push({ path: copyFile, content: VERCEL_FUNCTION("copy", relativeImport(copyFile, handlers)) });
-            files.push({ path: sessionFile, content: VERCEL_FUNCTION("edit-session", relativeImport(sessionFile, handlers)) });
+            files.push(make.machine(copyFile, VERCEL_FUNCTION("copy", relativeImport(copyFile, handlers))));
+            files.push(make.machine(sessionFile, VERCEL_FUNCTION("edit-session", relativeImport(sessionFile, handlers))));
             break;
         default:
             // next-api-routes, custom-server, unknown: the agent adapts request-handlers (see the instructions).
             break;
     }
-    if (plan.repository.language === "javascript") {
-        return files.map((file) => transpileToJs(file.path, file.content));
-    }
     return files;
 }

package/dist/types.d.ts

@@ -143,6 +143,68 @@ export interface HostIntegration {
     /** Runtime facts the agent and the owner need (filesystem, compatibility flags, variables). */
     readonly notes: readonly string[];
 }
+/**
+ * Who owns a file Refino generated.
+ *
+ * `machine`  Refino's own runtime code. It carries behaviour the editor and
+ *            the hosted service depend on, holds nothing a site is meant to
+ *            hand-write, and Refino refreshes it whenever it can prove the
+ *            bytes on disk are still the ones it wrote.
+ * `scaffold` A generated starting point the owner is invited to restyle (the
+ *            /edit pages). Refino refreshes an untouched one and never
+ *            argues with a restyled one.
+ *
+ * Everything Refino merges rather than owns -- the copy file, package.json,
+ * .env.example, refino.config.json -- is customer-owned and is not in this
+ * vocabulary at all: it is never overwritten, only merged.
+ */
+export type GeneratedOwnership = "machine" | "scaffold";
+/**
+ * What became of one generated file on an init run, or what verification
+ * found there.
+ *
+ * `create`     it did not exist; Refino wrote it.
+ * `current`    the bytes on disk are exactly what this version generates.
+ * `update`     stale, and provably untouched since Refino wrote it, so it was
+ *              (or can be) refreshed in place.
+ * `customized` changed locally, and Refino's own version of it has not moved
+ *              since: nothing to upgrade, nothing to warn about.
+ * `review`     changed locally *and* stale, or impossible to prove untouched.
+ *              Never overwritten; always reported.
+ */
+export type GeneratedFileStatus = "create" | "current" | "update" | "customized" | "review";
+/** One generated file, its ownership, and where its bytes came from. */
+export interface GeneratedFileState {
+    readonly path: string;
+    readonly ownership: GeneratedOwnership;
+    readonly status: GeneratedFileStatus;
+    /** Refino version whose output the bytes on disk match, when that is knowable. */
+    readonly from: string | null;
+    /** Refino version generating the desired bytes. */
+    readonly to: string;
+    /** Why this status, in one sentence. Always set for `review`. */
+    readonly reason: string;
+    /**
+     * For `review`: the repository-relative file Refino wrote the current
+     * template to, beside the original, so the difference can be read and
+     * merged by hand. The original is never touched.
+     */
+    readonly comparisonPath?: string;
+}
+/** `.refino/generated.json`: what Refino wrote, so a later run can tell. */
+export interface GeneratedManifest {
+    readonly version: 1;
+    /** Refino version that last wrote this manifest. */
+    readonly tool: string;
+    readonly files: Readonly<Record<string, GeneratedManifestEntry>>;
+}
+export interface GeneratedManifestEntry {
+    readonly ownership: GeneratedOwnership;
+    /** Refino version that wrote these bytes. */
+    readonly toolVersion: string;
+    /** sha256, hex, of the exact bytes Refino wrote. */
+    readonly sha256: string;
+}
 export interface PlannedFile {
     readonly path: string;
     readonly action: "create" | "merge" | "append" | "modify";
@@ -272,6 +334,19 @@ export interface ApplyResult {
         readonly reason: string;
     }[];
     readonly installCommand: string | null;
+    /**
+     * Every file Refino generates, and what this run did with it. `written`
+     * and `skipped` stay what they always were (the files this run touched or
+     * left alone); this is the upgrade story, and the only place a stale or
+     * locally modified generated file is visible.
+     */
+    readonly generated: readonly GeneratedFileState[];
+    /**
+     * True when a generated file was left in place although Refino's version
+     * of it has moved on. An installation with this set is not current, and no
+     * caller may report it as one.
+     */
+    readonly needsReview: boolean;
 }
 export type CheckStatus = "pass" | "fail" | "warn" | "skip";
 export interface VerificationCheck {

package/dist/verify.js

@@ -8,9 +8,12 @@ import { join } from "node:path";
 import { isContentId, parseCopy } from "@getrefino/core";
 import ts from "typescript";
 import { exists, isFile, isTestOrStoryFile, readJson, readText, rel, walkFiles } from "./fs.js";
+import { COMPARISON_SUFFIX, classifyGeneratedFiles, readGeneratedManifest } from "./generated.js";
 import { parseSource, readPathAliases, reachableFiles, resolveImport } from "./graph.js";
 import { LEGACY_CONFIG_FILE_NAME, appDirectory, inspectRepository } from "./inspect.js";
-import { BOILERPLATE_DIR, CONFIG_FILE, verificationCommands } from "./plan.js";
+import { isInstallMethod } from "./install-method.js";
+import { BOILERPLATE_DIR, CONFIG_FILE, TOOL_VERSION, buildPlan, verificationCommands } from "./plan.js";
+import { boilerplateFiles } from "./templates.js";
 const SECRET_NAMES = ["COPY_GITHUB_TOKEN", "EDITOR_SESSION_SECRET", "EDITOR_PASSWORD"];
 const SERVER_ONLY_IMPORTS = ["@getrefino/github", "@getrefino/core/local-file"];
 function collectEditableTextUses(appDir, files) {
@@ -189,6 +192,74 @@ function hostedChecks(appDir, inspection, hosted, sourceFiles, rendersProvider,
             add({ id: "hosted-provider", status: "fail", message: `${file} decides edit mode on the server; a Refino-hosted site decides it in the browser.`, fix: `Render <CopyEditing content={copy}> from ${BOILERPLATE_DIR}/copy-editing without an editing prop and without next/headers.` });
     }
 }
+/**
+ * Is the Refino runtime code in this repository the code this Refino
+ * generates?
+ *
+ * Package versions cannot answer that. Upgrading `@getrefino/*` replaces what
+ * `node_modules` holds and leaves every file Refino copied into the
+ * repository exactly where it was, which is how a site ran rc.2 packages
+ * against rc.1 generated code and passed verification. So the files
+ * themselves are regenerated in memory and compared, and the answer is one of
+ * three: current, stale but provably untouched (one command fixes it), or
+ * stale and locally edited (a person has to look).
+ *
+ * Read-only, like the rest of verification: nothing here writes.
+ */
+function generatedChecks(appDir, inspection, contentFile, hosted, installMethod, add) {
+    let states;
+    try {
+        const plan = buildPlan(inspection, { filesScanned: [], candidates: [] }, {
+            contentFile,
+            ...(hosted ? { refino: { siteId: hosted.siteId, appUrl: hosted.appUrl, ...(isInstallMethod(installMethod) ? { installMethod } : {}) } } : {}),
+        });
+        states = classifyGeneratedFiles(appDir, boilerplateFiles(plan), readGeneratedManifest(appDir));
+    }
+    catch {
+        // A repository this build cannot plan for has no generated files to judge.
+        return;
+    }
+    const present = states.filter((state) => state.status !== "create");
+    if (present.length === 0)
+        return;
+    const upgrade = hosted
+        ? `npx @getrefino/cli@${TOOL_VERSION} init --agent --yes --refino-site ${hosted.siteId}`
+        : `npx @getrefino/cli@${TOOL_VERSION} init --agent --yes`;
+    const stale = present.filter((state) => state.status === "update");
+    if (stale.length > 0) {
+        add({
+            id: "generated-stale",
+            status: "fail",
+            message: `${stale.length} generated Refino runtime file(s) are from an earlier release, although the installed packages are not.`,
+            details: stale.map((state) => `${state.path}  ${state.from ?? "unknown"} → ${state.to}`),
+            fix: `Run \`${upgrade}\`. Each file listed is byte-identical to what Refino wrote, so it is refreshed in place; nothing you wrote is touched.`,
+        });
+    }
+    const review = present.filter((state) => state.status === "review");
+    if (review.length > 0) {
+        // A restyled /edit page is a normal thing to own; Refino's own runtime
+        // modules are not, and a stale one of those is a real problem.
+        const machine = review.some((state) => state.ownership === "machine");
+        add({
+            id: "generated-review",
+            status: machine ? "fail" : "warn",
+            message: `${review.length} generated Refino file(s) have local changes and are from an earlier release, so Refino will not refresh them.`,
+            details: review.map((state) => `${state.path}  ${state.reason}`),
+            fix: `Run \`${upgrade}\`: it leaves these files alone and writes Refino's current version beside each one as \`<file>${COMPARISON_SUFFIX}\`. Move your changes onto that version, replace the original with it, delete the \`${COMPARISON_SUFFIX}\` file, then run init again.`,
+        });
+    }
+    if (stale.length === 0 && review.length === 0) {
+        const customized = present.filter((state) => state.status === "customized");
+        add({
+            id: "generated-current",
+            status: "pass",
+            message: `Generated Refino runtime files are the ${TOOL_VERSION} ones (${present.length} file(s)).`,
+            ...(customized.length > 0
+                ? { details: customized.map((state) => `${state.path} has local changes, and Refino's version of it has not changed since — nothing to upgrade.`) }
+                : {}),
+        });
+    }
+}
 export function verifyIntegration(rootPath, options = {}) {
     const inspection = inspectRepository(rootPath, options);
     const appDir = appDirectory(inspection);
@@ -399,6 +470,8 @@ export function verifyIntegration(rootPath, options = {}) {
         add({ id: "env-example", status: "pass", message: ".env.example documents the Refino variables." });
     else
         add({ id: "env-example", status: "warn", message: ".env.example does not document EDITOR_*/COPY_* variables.", fix: "Run `refino init --agent` or add the block by hand." });
+    // Generated runtime files: current, refreshable, or the owner's now.
+    generatedChecks(appDir, inspection, contentFile, hosted, config?.refino?.installMethod, add);
     // Scripts (plus a tsc fallback when a TypeScript project has no typecheck script).
     const commands = [];
     for (const command of verificationCommands(inspection)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/onboarding",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "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.2"
+    "@getrefino/core": "0.1.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "22.20.2",