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

package/README.md

@@ -32,7 +32,38 @@ components.
 
 ## Install into a site
 
-Run this in the website's repository:
+The order matters, and it starts on the Refino dashboard rather than in the
+repository.
+
+1. **Connect the site in the Refino dashboard (<https://app.refino.dev>).** You
+   give it the repository, the branch, where the copy file will live, and the
+   URL the site is served from. Refino gives you a **site id** (`site_…`).
+   - The branch must be **the branch that will contain the Refino files and be
+     deployed**. Refino reads and commits the copy file on that branch and
+     nowhere else.
+   - The copy file **does not have to exist yet.** `init` writes it in step 2.
+     Until the site is installed and deployed, the dashboard shows it as
+     *awaiting install*; that is the expected state, not a fault.
+2. **Install into the repository**, passing that site id:
+
+   ```bash
+   npx @getrefino/cli init --agent --yes --refino-site site_…
+   ```
+
+3. **Hand `.refino/AGENT_INSTRUCTIONS.md` and `.refino/plan.json` to your
+   coding agent** and let it do exactly what they say.
+4. **Verify**: `npx @getrefino/cli verify`, fixing only what it reports.
+5. **Commit and merge** that work onto the branch the site is configured to
+   use, and deploy it.
+6. **Open `/edit`** on the deployed site.
+
+If the site was connected to Refino again later — disconnected and reconnected,
+or moved to another account — it has a new site id, and step 2 is how the
+repository learns it. Re-run `init --agent --yes --refino-site <new id>`,
+commit and deploy.
+
+Without `--refino-site` the same command sets up a **self-hosted** site, which
+holds its own editor password and repository token instead:
 
 ```bash
 npx @getrefino/cli init --agent
@@ -53,9 +84,50 @@ 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` in the repository.
+1. Run `npx @getrefino/cli init --agent --refino-site <site id>` in the
+   repository (the owner gets the site id from the Refino dashboard; without
+   one, `init --agent` sets up a self-hosted site instead). Add
+   `--via claude|codex|gemini|grok|other` so Refino knows which installation
+   routes work.
 2. Read `.refino/AGENT_INSTRUCTIONS.md` and `.refino/plan.json` and do exactly
    what they say. **They are authoritative.** They were generated from an
    inspection of this specific repository — do not invent integration steps,
@@ -63,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 |
@@ -75,7 +154,11 @@ npx @getrefino/cli verify
 
 Every command takes `--json` for machine-readable output and `--cwd <dir>` to
 operate on another directory. `refino init --dry-run` shows what would be
-written without writing anything; no command ever overwrites an existing file.
+written without writing anything. No command overwrites an existing file, with
+one exception: `init --refino-site <id>` updates the generated `refino/`
+constants module and the `refino` block of `refino.config.json` when they still
+name a different site, which is how a site reconnected in the Refino dashboard
+is re-recorded. Nothing you wrote by hand is touched.
 
 ## Packages
 

package/dist/cli.js

@@ -6,7 +6,7 @@ import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
-import { INSTRUCTIONS_FILE, PLAN_FILE, TOOL_VERSION, appDirectory, applyPlan, inspectRepository, planMigration, renderAgentInstructions, scanCopy, verifyIntegration, } from "@getrefino/onboarding";
+import { INSTRUCTIONS_FILE, PLAN_FILE, TOOL_VERSION, appDirectory, applyPlan, inspectRepository, planMigration, renderAgentInstructions, resolveInstallMethod, scanCopy, verifyIntegration, } from "@getrefino/onboarding";
 import { bold, cyan, dim, formatApply, formatCandidates, formatInspection, formatPlanSummary, formatVerification, red, yellow } from "./format.js";
 const TAGLINE = "Refino lets site owners edit visible website copy in the browser while the repository stays the source of truth.";
 const HELP = `refino ${TOOL_VERSION}  (@getrefino/cli)
@@ -16,13 +16,42 @@ ${TAGLINE}
 It is not a CMS: the copy lives in one JSON file in the repository, an edit is a
 commit, and removing Refino leaves the content exactly where it was.
 
-Install into a site
-  npx @getrefino/cli init --agent     inspect the repo, write the setup files and
-                                      an authoritative plan + agent instructions
-  npx @getrefino/cli verify           check the result; repeat until it passes
+Install into a site, in this order
+  1. Connect the site in the Refino dashboard (https://app.refino.dev) and copy
+     its site id. You give it the repository, the branch that will carry the
+     Refino files and be deployed, and where the copy file will live. The copy
+     file does not have to exist yet.
+  2. npx @getrefino/cli init --agent --yes --refino-site <site_id>
+     inspects the repo and writes the setup files, .refino/plan.json and
+     .refino/AGENT_INSTRUCTIONS.md.
+  3. Hand those two files to your coding agent and let it do exactly what they say.
+  4. npx @getrefino/cli verify        fix only what it reports; repeat until it passes
+  5. Commit and merge that work onto the branch the site is configured to use, then
+     deploy it. Refino reads and commits the copy file on that branch.
+  6. Open /edit on the deployed site.
+
+  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>]] [--route <path>]... [--all] [--agent | --dry-run | --plan] [--yes]
+  refino init     [--refino-site <id> [--refino-url <origin>]] [--via <installer>] [--route <path>]... [--all] [--agent | --dry-run | --plan] [--yes]
   refino inspect  [--json]
   refino scan     [--route <path>]... [--all] [--no-shared] [--json] [--include-excluded]
   refino plan     [--route <path>]... [--all] [--format text|json|agent] [--out <file>]
@@ -38,6 +67,11 @@ Options
   --refino-site <id>    Connect to Refino (hosted mode): the site id from the Refino dashboard.
                         The site then needs no editor password, secret, repository token or server code.
   --refino-url <origin> Refino app origin (default: https://app.refino.dev)
+  --via <installer>     Who is doing the installation: claude, codex, gemini, grok, cli,
+                        manual or other. Recorded as a public constant in the site and
+                        told to Refino so it knows which installation routes work. It is
+                        never guessed: without this flag (or REFINO_INSTALL_METHOD) it
+                        stays "unknown".
   --agent               Write safe setup files + .refino/AGENT_INSTRUCTIONS.md
   --dry-run             Show what --agent would write without writing
   --plan                Print the plan only
@@ -46,7 +80,8 @@ Options
   --run                 verify: also run the repository's typecheck/lint/test/build
 
 If you are a coding agent
-  1. npx @getrefino/cli init --agent          (inspect, plan, write setup files + instructions)
+  1. npx @getrefino/cli init --agent --via <your name: claude, codex, gemini, grok or other>
+                                              (inspect, plan, write setup files + instructions)
   2. Read .refino/AGENT_INSTRUCTIONS.md and .refino/plan.json and do exactly what they say.
      They are authoritative: do not invent integration steps of your own.
   3. npx @getrefino/cli verify                (fix only what it reports, then run it again)
@@ -65,6 +100,7 @@ function parse(argv) {
             "content-file": { type: "string" },
             "refino-site": { type: "string" },
             "refino-url": { type: "string" },
+            via: { type: "string" },
             agent: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
             plan: { type: "boolean", default: false },
@@ -88,6 +124,7 @@ function parse(argv) {
         contentFile: values["content-file"],
         refinoSite: values["refino-site"],
         refinoUrl: values["refino-url"],
+        via: values.via,
         agent: values.agent,
         dryRun: values["dry-run"],
         plan: values.plan,
@@ -110,10 +147,17 @@ function planOptions(args) {
     options.includeShared = args.shared;
     if (args.contentFile)
         options.contentFile = args.contentFile;
-    if (args.refinoSite)
-        options.refino = args.refinoUrl ? { siteId: args.refinoSite, appUrl: args.refinoUrl } : { siteId: args.refinoSite };
+    if (args.refinoSite) {
+        // Whatever the installer said, or nothing. Never inferred from the environment.
+        const installMethod = resolveInstallMethod(args.via, process.env);
+        options.refino = args.refinoUrl
+            ? { siteId: args.refinoSite, appUrl: args.refinoUrl, installMethod }
+            : { siteId: args.refinoSite, installMethod };
+    }
     else if (args.refinoUrl)
         throw new Error("--refino-url needs --refino-site.");
+    else if (args.via)
+        throw new Error("--via needs --refino-site: it is recorded on the site connected to Refino.");
     return options;
 }
 function inspect(args) {
@@ -256,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");
@@ -76,7 +77,12 @@ export function formatPlanSummary(plan) {
     rows.push(line("Provider", `${plan.integration.provider.file ?? "?"}  [${plan.integration.provider.strategy}]`));
     rows.push(line("Endpoint", `${plan.integration.endpoint.path}  [${plan.integration.endpoint.kind}]`));
     rows.push(line("Auth", `${plan.integration.auth.strategy}${plan.integration.auth.existing.length > 0 ? ` (existing: ${plan.integration.auth.existing.join(", ")})` : ""}`));
-    rows.push(line("Persistence", `local file in development; GitHub via ${plan.integration.persistence.github.envVars.join(", ")}`));
+    // A connected site has no adapter and no variables of its own: Refino holds
+    // the credential and commits. Naming environment variables it will never set
+    // (the self-hosted list is empty here) read as a truncated sentence.
+    rows.push(line("Persistence", plan.refino
+        ? "Refino commits to the repository (no adapter, no variables in this site)"
+        : `local file in development; GitHub via ${plan.integration.persistence.github.envVars.join(", ")}`));
     rows.push("");
     rows.push(bold("Copy"));
     rows.push(line("Selected", green(String(plan.summary.selected))));
@@ -119,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.1",
+  "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.1"
+    "@getrefino/onboarding": "0.1.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "22.20.2",