@rafinery/cli 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.2.2
+
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration.
+
+Completes 0.2.1 (which was published before these two landed):
+
+- **shadcn-style overwrite, no more `.new` clutter.** When a vendored file the dev owns already
+  exists and differs, `init`/`update` **ask** "overwrite? [y/N/a/q]" and act on the answer —
+  instead of silently writing `<file>.new`. Flags `--overwrite` / `--keep` skip the prompt; a
+  non-TTY (CI / agent shell) safely keeps files. Stale `.new` files from older CLIs are cleaned up.
+- **`/rafa help`** — a full command reference for both surfaces (in-editor `/rafa` vs terminal
+  `rafa` CLI), also shown on no argument or an unrecognized command.
+
 ## 0.2.1
 
 **Adopt with:** `npx @rafinery/cli@latest update` (or `/rafa update` in Claude Code) — no re-scan,

package/bin/rafa.mjs

@@ -29,6 +29,10 @@ Commands:
   init [<setup-url>]   Provision this repo — vendor the blueprint (agents, capabilities,
                        contract, gates) and, with a platform setup URL, wire the brain remote.
   update               Re-sync the blueprint into this repo (you own your copy; opt-in updates).
+
+  Flags (init/update):  --overwrite  replace changed owned files without asking
+                        --keep       keep all changed owned files without asking
+                        (default: ask per file; in a non-TTY it keeps them)
   compile              Validate the brain against the contract → .rafa/manifest.json.
   push                 Compile, then push .rafa/ to your brain remote.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print

package/blueprint/.claude/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-description: rafa — init · scan · improve · push · leverage · migrate · update. Usage: /rafa <init|scan|improve|push|leverage|migrate|update> [--brain-only]
+description: rafa — init · scan · improve · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|push|leverage|migrate|update|help> [--brain-only]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -100,13 +100,36 @@ understood to be rewritten correctly — need intelligence, and that's this comm
    on the dev's approval, `rafa push` if this is a connected repo.
 Never hand-edit around a migration or discard tuned files.
 
-## (no argument, or unrecognized)
-`/rafa` runs the in-editor passes: `init` · `scan [--brain-only]` · `improve` · `push` ·
-`leverage` · `migrate` · `update`.
+## `help` (also: no argument, or an unrecognized command)
+Print this reference verbatim and stop.
 
-`compile` is a **terminal** command on the `rafa` CLI (`@rafinery/cli`) — not a slash command.
-If the dev typed it, don't error out; point them to the shell (`rafa compile`) and stop. For
-anything else unrecognized, print this usage line and stop.
+**rafa has two surfaces.** `/rafa <cmd>` runs the intelligent, in-editor passes; the terminal
+`rafa` CLI (run via `npx @rafinery/cli@latest <cmd>`) does the deterministic plumbing. Several
+names exist on both — the CLI does the mechanical half, `/rafa` the intelligent half.
+
+**`/rafa` — in the editor (LLM does the work):**
+| Command | What it does |
+|---|---|
+| `/rafa init` | First run: ensure structure, then run the full scan pass. |
+| `/rafa scan [--brain-only]` | The full pass: know → verify → improve → push. `--brain-only` stops after the brain is validated (a cheap knowledge refresh). |
+| `/rafa improve` | The improvement pass — bloom writes a cited, prioritized (P0–P3) ledger. |
+| `/rafa push` | (Re-)push the brain to the brain remote (your git auth). |
+| `/rafa leverage` | Tune your toolbox: reason over config and, on approval, apply fixes exactly — merge settings, wire an MCP, scaffold a skill. |
+| `/rafa migrate` | Semantic migration — rewrite plans to a new schema preserving meaning, then compile-gate. |
+| `/rafa update` | The brain-side of an upgrade: after the CLI syncs the blueprint, run the migrations that need intelligence (re-scan a stale brain / rewrite plans). |
+
+**`rafa` — in the terminal (`npx @rafinery/cli@latest <cmd>`; deterministic):**
+| Command | What it does |
+|---|---|
+| `init [<setup-url>]` | Vendor the blueprint into the repo (+ wire the brain remote from a platform setup URL). |
+| `update [--overwrite\|--keep]` | Blueprint-side of an upgrade: re-sync the blueprint (asks before overwriting files you tuned), run mechanical migrations, and report what the brain needs next. |
+| `compile` | Run the contract gate → `.rafa/manifest.json`. |
+| `push` | Compile, then push `.rafa/` to the brain remote. |
+| `leverage` | Detect toolbox gaps (deterministic) and print prioritized tips — the detector for `/rafa leverage`. |
+| `migrate` | Run the mechanical (deterministic) migrations. |
+
+If the dev typed a **terminal-only** command (`compile`) as a slash command, point them to the
+shell (`rafa compile`) as well. Then stop.
 
 ---
 Token discipline: glob/grep/AST before reading; scoped reads; deterministic extraction

package/lib/blueprint.mjs

@@ -10,6 +10,7 @@ import {
   readFileSync,
   readdirSync,
   statSync,
+  rmSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -97,39 +98,67 @@ function sameBytes(a, b) {
 }
 
 // Copy the blueprint from `from` into `to`.
-//  - mode "vendor" (default): non-destructive. lockstep files overwrite; owned files are
-//    created if absent, left untouched if identical, and preserved (writing `<file>.new`)
-//    if the dev has changed them — we never clobber tuning.
+//  - mode "vendor" (default): non-destructive. lockstep files (tools + contract) overwrite;
+//    owned files are created if absent, left untouched if identical, and — if the dev has
+//    changed them — resolved via `onConflict(rel)` which returns "overwrite" | "keep"
+//    (shadcn-style: ask before clobbering). No `.new` files; any stale `.new` left by an older
+//    CLI is cleaned up.
 //  - mode "bundle": force-copy everything (building the package tarball into a scratch dir).
-// Returns { created, updated, unchanged, preserved } — arrays of relative paths.
-export function copyBlueprint(from, to, { mode = "vendor" } = {}) {
+// Returns { created, updated, unchanged, kept, cleaned, errors } — arrays of relative paths.
+export async function copyBlueprint(from, to, { mode = "vendor", onConflict } = {}) {
   const { owned, lockstep } = blueprintFiles(from);
-  const report = { created: [], updated: [], unchanged: [], preserved: [] };
+  const report = { created: [], updated: [], unchanged: [], kept: [], cleaned: [], errors: [] };
 
-  const put = (rel, isOwned) => {
+  // Remove a stale `<dst>.new` written by an older CLI — it's our own debris, now obsolete.
+  const dropStaleNew = (rel, dst) => {
+    const stale = `${dst}.new`;
+    if (existsSync(stale)) {
+      try {
+        rmSync(stale);
+        report.cleaned.push(`${rel}.new`);
+      } catch {
+        /* leave it; not worth failing the update over */
+      }
+    }
+  };
+
+  const put = async (rel, isOwned) => {
     const src = join(from, rel);
     if (!existsSync(src)) return;
     const dst = join(to, rel);
-    mkdirSync(dirname(dst), { recursive: true });
-    if (!existsSync(dst)) {
-      cpSync(src, dst);
-      report.created.push(rel);
-      return;
-    }
-    if (sameBytes(src, dst)) {
-      report.unchanged.push(rel);
-      return;
-    }
-    if (mode === "bundle" || !isOwned) {
-      cpSync(src, dst); // lockstep, or a scratch bundle: safe to overwrite
-      report.updated.push(rel);
-    } else {
-      cpSync(src, `${dst}.new`); // owned + modified: keep the dev's copy, offer .new
-      report.preserved.push(rel);
+    try {
+      mkdirSync(dirname(dst), { recursive: true });
+      if (!existsSync(dst)) {
+        cpSync(src, dst);
+        report.created.push(rel);
+        return;
+      }
+      if (sameBytes(src, dst)) {
+        dropStaleNew(rel, dst);
+        report.unchanged.push(rel);
+        return;
+      }
+      // exists AND differs
+      if (mode === "bundle" || !isOwned) {
+        cpSync(src, dst); // lockstep, or a scratch bundle: moves with the CLI
+        report.updated.push(rel);
+      } else {
+        // owned + modified: ask before clobbering the dev's tuning (default: keep).
+        const decision = onConflict ? await onConflict(rel) : "keep";
+        if (decision === "overwrite") {
+          cpSync(src, dst);
+          report.updated.push(rel);
+        } else {
+          report.kept.push(rel);
+        }
+      }
+      dropStaleNew(rel, dst);
+    } catch (e) {
+      report.errors.push(`${rel}: ${e instanceof Error ? e.message : e}`);
     }
   };
 
-  for (const rel of lockstep) put(rel, false);
-  for (const rel of owned) put(rel, true);
+  for (const rel of lockstep) await put(rel, false);
+  for (const rel of owned) await put(rel, true);
   return report;
 }

package/lib/init.mjs

@@ -13,16 +13,46 @@ import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
 import { mergeClaudeSettings } from "./claude-config.mjs";
 import { stampCurrent } from "./stamp.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
+import { isInteractive, ask } from "./prompt.mjs";
 
-// One-line summary of a copyBlueprint report; notes preserved (un-clobbered) files.
+// Decide what to do when an owned file the dev may have tuned already exists and differs.
+// shadcn-style: ask before clobbering. Honors `--overwrite`/`-o` (yes to all) and `--keep`
+// (no to all); in a non-TTY (CI / agent shell) it defaults to KEEP so it never blocks or clobbers.
+export function makeConflictResolver(args = []) {
+  const force = args.includes("--overwrite") || args.includes("-o");
+  const keepAll = args.includes("--keep");
+  const interactive = isInteractive();
+  let all = false; // overwrite everything remaining
+  let quit = false; // keep everything remaining
+  return async (rel) => {
+    if (force || all) return "overwrite";
+    if (keepAll || quit || !interactive) return "keep";
+    const a = await ask(
+      `  • ${rel} exists and differs — overwrite? [y = yes · N = keep · a = all · q = keep rest] `,
+    );
+    if (a === "a") {
+      all = true;
+      return "overwrite";
+    }
+    if (a === "q") {
+      quit = true;
+      return "keep";
+    }
+    return a === "y" || a === "yes" ? "overwrite" : "keep";
+  };
+}
+
+// One-line summary of a copyBlueprint report + per-file notes for kept/cleaned/errored files.
 export function reportBlueprint(r) {
   const n = (a) => a.length;
   console.log(
     `  ✓ blueprint: ${n(r.created)} new · ${n(r.updated)} updated · ` +
-      `${n(r.unchanged)} unchanged · ${n(r.preserved)} preserved`,
+      `${n(r.unchanged)} unchanged · ${n(r.kept)} kept`,
   );
-  for (const rel of r.preserved)
-    console.log(`    • kept your ${rel} — latest written to ${rel}.new (merge by hand)`);
+  for (const rel of r.kept)
+    console.log(`    • kept your ${rel}  (re-run with --overwrite to replace, or /rafa update to merge)`);
+  for (const rel of r.cleaned) console.log(`    • removed stale ${rel}`);
+  for (const err of r.errors) console.log(`    ! ${err}`);
 }
 
 // Union rafa's required permissions into .claude/settings.json without clobbering it.
@@ -69,8 +99,10 @@ export default async function init(args) {
   }
 
   // Vendor the blueprint into .claude/ + .rafa/ (you own these copies) — non-destructive:
-  // owned files (agents, capabilities) are never clobbered, tools/contract move in lockstep.
-  reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
+  // tools/contract move in lockstep; owned files (agents, capabilities) prompt before overwrite.
+  reportBlueprint(
+    await copyBlueprint(blueprintSource(), TARGET, { onConflict: makeConflictResolver(args) }),
+  );
   if (!existsSync(join(TARGET, ".rafa", "active.md")))
     writeFileSync(join(TARGET, ".rafa", "active.md"), "# No active plan\n");
   // Grant rafa's vendored tools their permissions (merge, never overwrite).

package/lib/prompt.mjs

@@ -0,0 +1,21 @@
+// Minimal interactive prompt helpers. Used to ask before overwriting a file the dev owns —
+// shadcn-style — instead of silently writing `.new` clutter.
+
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+// True only when we can actually prompt (both ends are a TTY). In a pipe / CI / an
+// agent-spawned shell we must NOT block on input — callers fall back to a safe default.
+export function isInteractive() {
+  return Boolean(stdin.isTTY && stdout.isTTY);
+}
+
+// Ask a free-form question, return the trimmed lowercased answer ("" if the dev just hits enter).
+export async function ask(question) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    return (await rl.question(question)).trim().toLowerCase();
+  } finally {
+    rl.close();
+  }
+}

package/lib/releases.mjs

@@ -46,6 +46,16 @@ export const RELEASES = [
       "blueprint migrations and reports what the brain needs; new `/rafa update` does the brain-side " +
       "migrations (re-scan / rewrite). `rafa update` now prints release notes + required actions.",
   },
+  {
+    version: "0.2.2",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "shadcn-style overwrite prompt on init/update — asks before replacing files you tuned " +
+      "(no more `.new` clutter; stale `.new` cleaned up; --overwrite/--keep flags). New `/rafa help` " +
+      "with a full command reference for both surfaces. (Completes 0.2.1, published before these landed.)",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/update.mjs

@@ -8,13 +8,13 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
-import { reportBlueprint, reportSettings } from "./init.mjs";
+import { reportBlueprint, reportSettings, makeConflictResolver } from "./init.mjs";
 import { CURRENT, CLI_VERSION, releasesAfter } from "./releases.mjs";
 import { stampedVersions, stampCurrent, stampCli } from "./stamp.mjs";
 import { pendingMigrations } from "./migrations/index.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
 
-export default async function update() {
+export default async function update(args = []) {
   const TARGET = process.cwd();
   if (!existsSync(join(TARGET, ".rafa")) && !existsSync(join(TARGET, ".claude"))) {
     console.error("✗ This repo isn't provisioned yet — run `rafa init` first.");
@@ -27,7 +27,9 @@ export default async function update() {
   await notifyIfBehind();
 
   console.log("rafa update — syncing the blueprint (non-destructive)");
-  reportBlueprint(copyBlueprint(blueprintSource(), TARGET));
+  reportBlueprint(
+    await copyBlueprint(blueprintSource(), TARGET, { onConflict: makeConflictResolver(args) }),
+  );
   reportSettings(TARGET);
 
   // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {