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

package/dist/verify.js

@@ -4,13 +4,16 @@
  * repository's own verification scripts.
  */
 import { spawnSync } from "node:child_process";
-import { join } from "node:path";
+import { dirname, join, resolve } 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 { LEGACY_CONFIG_FILE_NAME, appDirectory, inspectRepository, packageManagerAdd } from "./inspect.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,141 @@ 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.` });
     }
 }
+const EXACT_VERSION = /^[=v]?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\+[0-9A-Za-z.-]+)?$/;
+function normalizeVersion(value) {
+    return EXACT_VERSION.exec(value.trim())?.[1] ?? null;
+}
+function resolveRuntimePackages(inspection, appDir) {
+    const root = resolve(inspection.root);
+    return inspection.refino.packages
+        .filter((pkg) => pkg.name.startsWith("@getrefino/"))
+        .map((pkg) => {
+        for (let dir = resolve(appDir);; dir = dirname(dir)) {
+            const installed = readJson(join(dir, "node_modules", pkg.name, "package.json"));
+            const version = typeof installed?.version === "string" ? normalizeVersion(installed.version) : null;
+            if (version)
+                return { name: pkg.name, declared: pkg.version, version, source: "installed" };
+            if (dir === root || dirname(dir) === dir)
+                break;
+        }
+        const pinned = normalizeVersion(pkg.version);
+        return pinned
+            ? { name: pkg.name, declared: pkg.version, version: pinned, source: "pinned" }
+            : { name: pkg.name, declared: pkg.version, version: null, source: "range" };
+    });
+}
+/**
+ * Is the Refino runtime code in this repository the code this Refino
+ * generates, and do the installed packages match it?
+ *
+ * Package versions cannot answer the first question. 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).
+ *
+ * The converse happened too: rc.3 generated files next to rc.2 packages
+ * passed, because nothing compared the two. `package-versions` does.
+ *
+ * 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 packages = resolveRuntimePackages(inspection, appDir);
+    // The normal upgrade, in the order it has to happen: packages to this
+    // release, then init to refresh what Refino generated.
+    const packagesNotCurrent = packages.filter((pkg) => pkg.version !== TOOL_VERSION);
+    const installPackages = packagesNotCurrent.length > 0 ? packageManagerAdd(inspection.packageManager, packagesNotCurrent.map((pkg) => `${pkg.name}@${TOOL_VERSION}`)) : null;
+    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 than this CLI (${TOOL_VERSION}).`,
+            details: stale.map((state) => `${state.path}  ${state.from ?? "unknown"} → ${state.to}`),
+            fix: `${installPackages ? `Run \`${installPackages}\`, then \`${upgrade}\`` : `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.`) }
+                : {}),
+        });
+    }
+    // Which release the generated integration is. Only files whose bytes are a
+    // known release's output say so; an edited file's recorded version is where
+    // it started, not what it is. Files from more than one release have no
+    // single version to compare against, and generated-stale already fails.
+    const generatedVersions = new Set(present.filter((state) => state.status === "current" || state.status === "update").map((state) => state.from));
+    const generatedVersion = generatedVersions.size === 1 ? [...generatedVersions][0] : null;
+    if (generatedVersion === null || packages.length === 0)
+        return;
+    const describe = (pkg) => pkg.source === "installed" ? `${pkg.name} ${pkg.version} (installed)` : pkg.source === "pinned" ? `${pkg.name} ${pkg.version} (pinned in package.json, not installed)` : `${pkg.name} "${pkg.declared}" (a range in package.json, not installed)`;
+    const mismatched = packages.filter((pkg) => pkg.version !== null && pkg.version !== generatedVersion);
+    const unresolved = packages.filter((pkg) => pkg.version === null);
+    const fix = [
+        installPackages ? `Run \`${installPackages}\`` : null,
+        generatedVersion !== TOOL_VERSION ? `${installPackages ? "then " : "Run "}\`${upgrade}\`` : null,
+    ].filter(Boolean).join(", ");
+    if (mismatched.length > 0) {
+        add({
+            id: "package-versions",
+            status: "fail",
+            message: `Installed Refino packages do not match the generated integration (${generatedVersion}).`,
+            details: [...mismatched, ...unresolved].map(describe),
+            fix: `${fix || `Run \`${upgrade}\``}, so the packages and the generated integration are the same release.`,
+        });
+    }
+    else if (unresolved.length > 0) {
+        add({
+            id: "package-versions",
+            status: "warn",
+            message: `Cannot confirm the installed Refino package versions match the generated integration (${generatedVersion}).`,
+            details: unresolved.map(describe),
+            fix: `Install dependencies, or pin them: \`${packageManagerAdd(inspection.packageManager, unresolved.map((pkg) => `${pkg.name}@${generatedVersion}`))}\`.`,
+        });
+    }
+    else {
+        add({ id: "package-versions", status: "pass", message: `Installed Refino packages match the generated integration (${generatedVersion}).` });
+    }
+}
 export function verifyIntegration(rootPath, options = {}) {
     const inspection = inspectRepository(rootPath, options);
     const appDir = appDirectory(inspection);
@@ -399,6 +537,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.4",
   "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.4"
   },
   "devDependencies": {
     "@types/node": "22.20.2",