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

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
@@ -55,7 +86,11 @@ npx @getrefino/cli verify
 
 ## 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,
@@ -75,7 +110,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,25 @@ ${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.
 
 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 +50,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 +63,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 +83,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 +107,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 +130,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) {

package/dist/format.js

@@ -76,7 +76,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))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/cli",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "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.2"
   },
   "devDependencies": {
     "@types/node": "22.20.2",