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

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/inspect.d.ts

@@ -16,4 +16,6 @@ export declare function appDirectory(inspection: RepositoryInspection): string;
 export declare function packageManagerRun(pm: PackageManager, script: string): string;
 /** Run a binary from node_modules through the package manager. */
 export declare function packageManagerExec(pm: PackageManager, command: string): string;
+/** Add (or move) dependencies to exact specs, e.g. `pnpm add @getrefino/core@0.1.0`. */
+export declare function packageManagerAdd(pm: PackageManager, specs: readonly string[]): string;
 export declare function packageManagerInstall(pm: PackageManager): string;

package/dist/inspect.js

@@ -457,6 +457,20 @@ export function packageManagerExec(pm, command) {
             return `npx ${command}`;
     }
 }
+/** Add (or move) dependencies to exact specs, e.g. `pnpm add @getrefino/core@0.1.0`. */
+export function packageManagerAdd(pm, specs) {
+    const list = specs.join(" ");
+    switch (pm) {
+        case "pnpm":
+            return `pnpm add ${list}`;
+        case "yarn":
+            return `yarn add ${list}`;
+        case "bun":
+            return `bun add ${list}`;
+        default:
+            return `npm install ${list}`;
+    }
+}
 export function packageManagerInstall(pm) {
     switch (pm) {
         case "pnpm":

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[];