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

package/README.md

@@ -84,6 +84,43 @@ Then check the result:
 npx @getrefino/cli verify
 ```
 
+## Upgrading a site to a newer Refino
+
+Run the command you installed with, from the newer version:
+
+```bash
+npx @getrefino/cli@latest init --agent --yes --refino-site site_…
+```
+
+Updating the `@getrefino/*` packages is only half of an upgrade. Refino also
+generates runtime code into your repository (`refino/`, the `/edit` route), and
+installing a package never touches a file already committed there — so a site
+can be on the newest packages and still running an older release's integration.
+`init` is what moves that half.
+
+You never have to delete or move a generated file. `init` refreshes every one
+it can prove you have not edited and reports it:
+
+```
+Updated Refino-generated integration:
+  refino/refino-site.ts      0.1.0-rc.1 → 0.1.0-rc.3
+  refino/copy-editing.tsx    0.1.0-rc.1 → 0.1.0-rc.3
+```
+
+A file **you** changed is never overwritten. It is listed as needing review,
+Refino's current version is written beside it as `<file>.refino-new`, and
+`init` exits non-zero rather than let a half-upgraded site look finished. Move
+your changes onto that version, replace the original with it, delete the
+`.refino-new` file, and run `init` again.
+
+Refino knows which is which from `.refino/generated.json`, the record it writes
+of the exact bytes it generated — commit it with the rest. Sites installed
+before that file existed are recognised from the bytes of the older release, so
+they upgrade the same way.
+
+`refino verify` reports the same three states — current, refreshable, needs
+review — without changing anything.
+
 ## If you are a coding agent
 
 1. Run `npx @getrefino/cli init --agent --refino-site <site id>` in the
@@ -98,6 +135,13 @@ npx @getrefino/cli verify
 3. Run `npx @getrefino/cli verify` and fix only what it reports. Repeat until
    it passes.
 
+If you are **upgrading** an existing installation rather than creating one, run
+the same `init` command from the newer version and read its output. A non-zero
+exit means a generated file has local changes Refino would have had to discard:
+resolve each one against the `.refino-new` file it left beside the original,
+then run `init` again. Do not delete or move generated files to get past it,
+and do not report the upgrade as done while `init` or `verify` still fails.
+
 ## Commands
 
 | Command | What it does |

package/dist/cli.js

@@ -33,6 +33,23 @@ Install into a site, in this order
   Without --refino-site the same steps set up a self-hosted site, which holds its
   own password and repository token instead.
 
+Upgrade an existing installation
+  Re-run exactly the command you installed with, from the new version:
+
+    npx @getrefino/cli@latest init --agent --yes --refino-site <site_id>
+
+  Upgrading the @getrefino/* packages is not enough on its own. Refino also
+  copies runtime code into the repository (refino/), and installing a package
+  does not touch a file already committed there, so both have to move. init
+  refreshes every generated file it can prove you have not edited, says which
+  ones it changed and from which version, and never touches one you have:
+  those are listed as needing review, Refino's current version is written
+  beside each as <file>.refino-new, and init exits non-zero so a half-upgraded
+  site is never reported as a finished one. You never have to delete or move a
+  generated file yourself.
+
+  refino verify reports the same three states without changing anything.
+
 Usage
   refino init     [--refino-site <id> [--refino-url <origin>]] [--via <installer>] [--route <path>]... [--all] [--agent | --dry-run | --plan] [--yes]
   refino inspect  [--json]
@@ -283,7 +300,25 @@ export async function run(argv) {
             console.log("");
             if (mode === "dry-run") {
                 console.log(dim("Nothing was written. Run `refino init --agent` to write these files."));
-                return 0;
+                if (!result.needsReview)
+                    return 0;
+                // A dry run is also the read-only way to ask "would this upgrade
+                // cleanly?", so it answers with the same exit code the real run would.
+                console.log(red(`${result.generated.filter((state) => state.status === "review").length} generated file(s) have local changes and would not be updated; --agent would leave them alone and report them.`));
+                return 1;
+            }
+            // A generated file Refino left behind because it had been edited means
+            // this site is not running the integration this version generates. That
+            // is the whole failure this exit code exists for: init used to say
+            // "Next steps" over a half-upgraded site, and nothing downstream could
+            // tell. Say what is true, and fail.
+            if (result.needsReview) {
+                const count = result.generated.filter((state) => state.status === "review").length;
+                console.log(red(bold(`Refino did not finish: ${count} generated file(s) listed above were left as they are, and are not what Refino ${TOOL_VERSION} generates.`)));
+                console.log(red("This installation is NOT current. Resolve each one, then run this command again."));
+                console.log("");
+                console.log(dim(`Everything else was written; ${PLAN_FILE} and ${INSTRUCTIONS_FILE} are up to date.`));
+                return 1;
             }
             console.log(bold("Next steps"));
             if (result.installCommand)

package/dist/format.d.ts

@@ -11,4 +11,11 @@ export declare function formatCandidates(candidates: readonly CopyCandidate[], o
 }): string;
 export declare function formatPlanSummary(plan: MigrationPlan): string;
 export declare function formatApply(result: ApplyResult): string;
+/**
+ * The upgrade half of an init run: what Refino refreshed, and what it refused
+ * to touch. The second list is the important one -- it is the difference
+ * between "your installation is current" and "your installation is not", and
+ * it has to be impossible to skim past.
+ */
+export declare function formatGeneratedUpgrade(result: ApplyResult): string;
 export declare function formatVerification(result: VerificationResult): string;

package/dist/format.js

@@ -1,3 +1,4 @@
+import { COMPARISON_SUFFIX } from "@getrefino/onboarding";
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code) => (text) => (useColor ? `[${code}m${text}` : text);
 export const bold = paint("1");
@@ -124,6 +125,49 @@ export function formatApply(result) {
         for (const item of result.skipped)
             rows.push(`  ${dim("skip".padEnd(7))} ${item.path}  ${dim(item.reason)}`);
     }
+    const upgrade = formatGeneratedUpgrade(result);
+    if (upgrade) {
+        rows.push("");
+        rows.push(upgrade);
+    }
+    return rows.join("\n");
+}
+function versionArrow(state) {
+    return state.from && state.from !== state.to ? `${state.from} → ${state.to}` : state.to;
+}
+/**
+ * The upgrade half of an init run: what Refino refreshed, and what it refused
+ * to touch. The second list is the important one -- it is the difference
+ * between "your installation is current" and "your installation is not", and
+ * it has to be impossible to skim past.
+ */
+export function formatGeneratedUpgrade(result) {
+    const updated = result.generated.filter((state) => state.status === "update");
+    const review = result.generated.filter((state) => state.status === "review");
+    if (updated.length === 0 && review.length === 0)
+        return "";
+    const rows = [];
+    const width = updated.length > 0 ? Math.max(...updated.map((state) => state.path.length)) : 0;
+    if (updated.length > 0) {
+        rows.push(bold(result.dryRun ? "Refino-generated integration that would be updated:" : "Updated Refino-generated integration:"));
+        for (const state of updated)
+            rows.push(`  ${state.path.padEnd(width)}  ${cyan(versionArrow(state))}`);
+    }
+    if (review.length > 0) {
+        if (updated.length > 0)
+            rows.push("");
+        rows.push(red(bold("Needs manual review — NOT updated:")));
+        for (const state of review) {
+            // No version arrow here: the whole point is that this file's provenance
+            // could not be established, so printing one would be a claim.
+            rows.push(`  ${yellow(state.path)}`);
+            rows.push(`    ${dim("why:")}  ${state.reason}`);
+            if (!result.dryRun && state.comparisonPath) {
+                rows.push(`    ${dim("next:")} Compare it with ${state.comparisonPath} (Refino's ${state.to} version, written beside it just now).`);
+                rows.push(`           Move your changes onto that version, replace ${state.path} with it, delete the ${COMPARISON_SUFFIX} file, then run init again.`);
+            }
+        }
+    }
     return rows.join("\n");
 }
 export function formatVerification(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/cli",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "description": "Refino installer. Run `npx @getrefino/cli init` in a website's repository to let its owner edit visible copy in the browser while Git remains the source of truth. Inspects the repo, writes an authoritative migration plan and instructions for a coding agent, then verifies the result.",
   "keywords": [
     "refino",
@@ -45,7 +45,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrefino/onboarding": "0.1.0-rc.2"
+    "@getrefino/onboarding": "0.1.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "22.20.2",