@getrefino/cli 0.1.0-rc.6 → 0.2.0

package/README.md

@@ -10,6 +10,10 @@ This package is how Refino is installed into a website. If you were asked to
 npx @getrefino/cli init
 ```
 
+`init` connects the site to your Refino account and asks for its site id,
+which you get by connecting the site at <https://app.refino.dev>. Refino does
+not host your site; it keeps being built and deployed exactly as it is today.
+
 The installed binary is named `refino`. **Refino** is the product; `getrefino`
 is only the npm namespace.
 
@@ -44,7 +48,8 @@ repository.
    - 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:
+2. **Install into the repository**, passing that site id (run interactively
+   without it, `init` asks for it):
 
    ```bash
    npx @getrefino/cli init --agent --yes --refino-site site_…
@@ -62,13 +67,19 @@ 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:
+### Standalone sites
+
+`--standalone` sets up a site that is not connected to Refino at all: it runs
+its own editor login and holds its own editor password and repository token.
 
 ```bash
-npx @getrefino/cli init --agent
+npx @getrefino/cli init --agent --standalone
 ```
 
+Before 0.2.0 this was what `init` did when no `--refino-site` was given. From
+0.2.0 connecting to Refino is the default, and `init` without either flag asks
+for a site id (or, when it cannot ask, exits and says how to get one).
+
 `init` inspects the repository (framework, router, routes, package manager,
 auth, server, hosting, git), scans the pages for visible copy, proposes stable
 ids, and writes:
@@ -92,6 +103,7 @@ you installed with, from that version:
 ```bash
 pnpm add @getrefino/core@<version> @getrefino/react@<version>   # or npm install / yarn add / bun add
 npx @getrefino/cli@<version> init --agent --yes --refino-site site_…
+npx @getrefino/cli@<version> init --agent --yes --standalone        # standalone sites
 ```
 
 `init` never changes a dependency already listed in `package.json`, and
@@ -129,9 +141,11 @@ review — without changing anything.
 
 ## If you are a coding agent
 
-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
+1. Run `npx @getrefino/cli init --agent --yes --refino-site <site id>` in the
+   repository. The owner gets the site id by connecting the site in the
+   Refino dashboard (<https://app.refino.dev>); if they have none, ask them
+   to do that first. Use `--standalone` only when the owner asks for a
+   standalone site. 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
@@ -159,7 +173,7 @@ and do not report the upgrade as done while `init` or `verify` still fails.
 | `refino verify` | Check an installation and say exactly what is missing |
 
 Every command takes `--json` for machine-readable output and `--cwd <dir>` to
-operate on another directory. `refino init --dry-run` shows what would be
+operate on another directory. `refino init --dry-run --refino-site <id>` shows what would be
 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

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, resolveInstallMethod, scanCopy, verifyIntegration, } from "@getrefino/onboarding";
+import { INSTRUCTIONS_FILE, PLAN_FILE, REFINO_SITE_ID_PATTERN, 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)
@@ -18,25 +18,34 @@ commit, and removing Refino leaves the content exactly where it was.
 
 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.
+     its site id. Sign in with GitHub, then 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. Refino does not host
+     your site: it keeps being built and deployed exactly as it is today.
   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.
+     .refino/AGENT_INSTRUCTIONS.md. Run interactively without --refino-site,
+     init asks for the site id.
   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.
+  Connecting to your Refino account is the default. To set up a standalone site
+  instead, which holds its own editor password and repository token and never
+  talks to Refino, pass --standalone:
+
+    npx @getrefino/cli init --agent --yes --standalone
 
 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>
+    npx @getrefino/cli@latest init --agent --yes --standalone      (standalone sites)
+
+  Before 0.2.0, init without --refino-site set up a standalone site. It now
+  needs --standalone to do that.
 
   Upgrading the @getrefino/* packages is not enough on its own. Refino also
   copies runtime code into the repository (refino/), and installing a package
@@ -51,7 +60,7 @@ Upgrade an existing installation
   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 init     (--refino-site <id> [--refino-url <origin>] [--via <installer>] | --standalone) [--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>]
@@ -64,9 +73,14 @@ Options
   --all                 Every discovered route
   --no-shared           Exclude shared chrome (layouts, nav, footer)
   --content-file <p>    Where the canonical copy file lives (default: content/copy.json)
-  --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-site <id>    The site id from the Refino dashboard. Connects the site to your
+                        Refino account, which signs the owner in and commits their edits.
+                        The site then needs no editor password, secret, repository token
+                        or server code. Asked for when init runs interactively without it.
   --refino-url <origin> Refino app origin (default: https://app.refino.dev)
+  --standalone          Do not connect to Refino: the site runs its own editor login and
+                        commits with its own repository token. This is what init did
+                        without --refino-site before 0.2.0.
   --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
@@ -80,11 +94,14 @@ Options
   --run                 verify: also run the repository's typecheck/lint/test/build
 
 If you are a coding agent
-  1. npx @getrefino/cli init --agent --via <your name: claude, codex, gemini, grok or other>
+  1. Ask the owner for the site id from their Refino dashboard (https://app.refino.dev).
+     If they have none, ask them to connect the site there first; do not
+     switch to --standalone unless they ask for a standalone site.
+  2. npx @getrefino/cli init --agent --yes --refino-site <site_id> --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.
+  3. 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)
+  4. npx @getrefino/cli verify                (fix only what it reports, then run it again)
 `;
 function parse(argv) {
     const { values, positionals } = parseArgs({
@@ -100,6 +117,7 @@ function parse(argv) {
             "content-file": { type: "string" },
             "refino-site": { type: "string" },
             "refino-url": { type: "string" },
+            standalone: { type: "boolean", default: false },
             via: { type: "string" },
             agent: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
@@ -124,6 +142,7 @@ function parse(argv) {
         contentFile: values["content-file"],
         refinoSite: values["refino-site"],
         refinoUrl: values["refino-url"],
+        standalone: values.standalone,
         via: values.via,
         agent: values.agent,
         dryRun: values["dry-run"],
@@ -158,6 +177,8 @@ function planOptions(args) {
         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.");
+    else if (args.standalone && args.command !== "init")
+        throw new Error("--standalone only applies to init.");
     return options;
 }
 function inspect(args) {
@@ -188,6 +209,64 @@ function writePlanOutputs(args, plan) {
     writeFileSync(resolve(args.cwd, args.out), content, "utf8");
     console.log(dim(`Wrote ${args.out}`));
 }
+/** Where an owner gets a site id: the only way one is ever minted. */
+const SITE_ID_GUIDANCE = [
+    "Refino connects this site to your Refino account, which signs you in and commits your edits.",
+    "Refino does not host the site: it keeps being built and deployed exactly as it is today.",
+    "",
+    "To get a site id:",
+    "  1. Open https://app.refino.dev and sign in with GitHub.",
+    "  2. Connect the site: its repository, the branch that will carry the Refino files and",
+    "     be deployed, where the copy file will live (it does not have to exist yet), and the",
+    "     URL the site is served from.",
+    "  3. Copy the site id it shows you (site_…).",
+];
+/**
+ * The site id init connects to, or null for a standalone install.
+ *
+ * Connecting to a Refino account is the default. A standalone install is
+ * only ever chosen explicitly with --standalone; nothing falls back to it,
+ * because the two write different code into the site and an owner who
+ * wanted one should never find the other.
+ */
+async function resolveInitSite(args) {
+    if (args.standalone)
+        return { siteId: null };
+    if (args.refinoSite)
+        return { siteId: args.refinoSite };
+    const command = "npx @getrefino/cli init --agent --yes --refino-site <site_id>";
+    if (args.yes || !process.stdin.isTTY) {
+        console.log(red("init needs a Refino site id."));
+        console.log("");
+        for (const line of SITE_ID_GUIDANCE)
+            console.log(line);
+        console.log("");
+        console.log(`Then run: ${cyan(command)}`);
+        console.log(dim("For a standalone site that runs its own editor login instead, pass --standalone."));
+        return { exit: 2 };
+    }
+    for (const line of SITE_ID_GUIDANCE)
+        console.log(line);
+    console.log("");
+    console.log(dim("For a standalone site that runs its own editor login instead, press Enter and re-run with --standalone."));
+    for (;;) {
+        const answer = await prompt("Refino site id: ");
+        if (answer === "") {
+            console.log(dim(`Nothing was written. When you have the site id, run: ${command}`));
+            return { exit: 2 };
+        }
+        if (REFINO_SITE_ID_PATTERN.test(answer)) {
+            console.log("");
+            return { siteId: answer };
+        }
+        console.log(yellow("That is not a site id. It looks like site_ followed by 32 characters, and is shown on the dashboard."));
+    }
+}
+/** The init command that reproduces this run's mode, for messages that tell the owner what to run next. */
+function initCommand(args, extra) {
+    const mode = args.refinoSite ? ` --refino-site ${args.refinoSite}` : " --standalone";
+    return `refino init ${extra}${mode}`;
+}
 export async function run(argv) {
     let args;
     try {
@@ -257,6 +336,14 @@ export async function run(argv) {
             console.log(TAGLINE);
             console.log(dim("Copy lives in one JSON file in this repository. An edit is a commit. No CMS, no database, no sync."));
             console.log("");
+            if (args.standalone && (args.refinoSite || args.refinoUrl || args.via)) {
+                throw new Error("--standalone cannot be combined with --refino-site, --refino-url or --via: a standalone site is not connected to Refino.");
+            }
+            const site = await resolveInitSite(args);
+            if ("exit" in site)
+                return site.exit;
+            if (site.siteId)
+                args = { ...args, refinoSite: site.siteId };
             const inspection = inspect(args);
             if (!requireSupported(inspection))
                 return 1;
@@ -299,7 +386,7 @@ export async function run(argv) {
             console.log(formatApply(result));
             console.log("");
             if (mode === "dry-run") {
-                console.log(dim("Nothing was written. Run `refino init --agent` to write these files."));
+                console.log(dim(`Nothing was written. Run \`${initCommand(args, "--agent")}\` to write these files.`));
                 if (!result.needsReview)
                     return 0;
                 // A dry run is also the read-only way to ask "would this upgrade

package/package.json

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