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

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

@@ -2,6 +2,7 @@
  * Structured results shared by the CLI and any future hosted onboarding.
  * Everything here is plain JSON-serializable data. No secrets, ever.
  */
+import type { InstallMethod } from "./install-method.js";
 export type PackageManager = "pnpm" | "npm" | "yarn" | "bun" | "unknown";
 export type Framework = "next" | "vite-react" | "react" | "unsupported";
 export type Router = "next-app" | "next-pages" | "react-router" | "single-page" | "unknown";
@@ -142,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";
@@ -236,17 +299,23 @@ export interface MigrationPlan {
     };
     readonly unresolved: readonly string[];
 }
-/** Public identifiers of a site connected to Refino. Neither is a secret. */
+/** Public identifiers of a site connected to Refino. None of these is a secret. */
 export interface RefinoSite {
     readonly siteId: string;
     /** Origin of the Refino app, e.g. "https://app.refino.dev". */
     readonly appUrl: string;
+    /**
+     * What `refino init --via <method>` was told, or "unknown". Committed to
+     * the repository with the site id so the owner can see and change it.
+     */
+    readonly installMethod: InstallMethod;
 }
 export interface PlanOptions {
     /** Connect to Refino (hosted mode): the site id from the Refino dashboard, and optionally the app origin. */
     readonly refino?: {
         readonly siteId: string;
         readonly appUrl?: string;
+        readonly installMethod?: InstallMethod;
     };
     /** Routes to migrate. Defaults to ["/"] when the route exists. */
     readonly routes?: readonly string[];
@@ -265,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) {
@@ -143,7 +146,20 @@ function hostedChecks(appDir, inspection, hosted, sourceFiles, rendersProvider,
     else if (!siteText.includes(JSON.stringify(hosted.siteId)) || !siteText.includes(JSON.stringify(hosted.appUrl)))
         add({ id: "refino-site", status: "fail", message: `${siteFile} does not name site ${hosted.siteId} at ${hosted.appUrl} as ${CONFIG_FILE} does.`, fix: "Regenerate the module or fix the config so both agree." });
     else
-        add({ id: "refino-site", status: "pass", message: `Connected to Refino site ${hosted.siteId} at ${hosted.appUrl}.` });
+        add({
+            id: "refino-site",
+            status: "pass",
+            message: `Connected to Refino site ${hosted.siteId} at ${hosted.appUrl}.`,
+            // Deliberately a local check. Verification makes no network calls and
+            // holds no credential, so it can prove the repository agrees with
+            // itself and nothing more: whether this site id is still the one Refino
+            // has is a question only an authorized request can answer, and /edit
+            // asks it on every load.
+            details: [
+                "Checked in this repository only: Refino is never contacted from here, so this cannot prove the site id still exists.",
+                `If /edit says the site is not connected to your account, compare ${hosted.siteId} with the site id on your Refino dashboard and re-run \`refino init --agent --yes --refino-site <id>\` if they differ.`,
+            ],
+        });
     const missing = ["refino-client", "copy-editing", "edit-page"].filter((name) => !find(`${BOILERPLATE_DIR}/${name}`));
     if (missing.length > 0)
         add({ id: "refino-client", status: "fail", message: `Missing generated hosted modules: ${missing.map((name) => `${BOILERPLATE_DIR}/${name}`).join(", ")}.`, fix: "Run `refino init --agent --refino-site …` again; existing files are kept." });
@@ -176,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);
@@ -386,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.1",
+  "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.1"
+    "@getrefino/core": "0.1.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "22.20.2",