formhaus 0.14.2 → 0.14.3

package/README.md

@@ -6,7 +6,7 @@ Adds the [Formhaus](https://formhaus.dev) MCP server and agent instructions to t
 npx formhaus
 ```
 
-Run it inside a project to also add the Cursor rule there. Requires Node 20 or later.
+Run it anywhere inside a project to also add the Cursor rule at the project root: the nearest folder above with `.git`, `package.json` or `.cursor`, below your home directory. Requires Node 20 or later.
 
 ## What it changes
 
@@ -14,12 +14,12 @@ Run it inside a project to also add the Cursor rule there. Requires Node 20 or l
 |-------|-------------|--------|
 | Claude Code | `claude` on `PATH` | `claude mcp add --scope user formhaus -- npx -y @formhaus/mcp` and the `formhaus-create-form` skill in `~/.claude/skills` |
 | Codex | `~/.codex` or `codex` on `PATH` | `[mcp_servers.formhaus]` in `~/.codex/config.toml` |
-| Cursor | `~/.cursor` or `cursor` on `PATH` | `formhaus` in `~/.cursor/mcp.json`, and `.cursor/rules/formhaus.mdc` when run inside a project |
+| Cursor | `~/.cursor` or `cursor` on `PATH` | `formhaus` in `~/.cursor/mcp.json`, and `.cursor/rules/formhaus.mdc` at the project root |
 | Claude Desktop | its config directory on macOS and Windows | `formhaus` in `claude_desktop_config.json` |
 
 Windsurf, Gemini CLI, OpenCode, VS Code and Claude Desktop on Linux are detected and listed with manual setup steps.
 
-Existing entries are kept. An existing `formhaus` server with another command or args is reported and left unchanged, and a project `.mcp.json` never counts as set up. Before the first change to a file, the original is saved as `<file>.bak`. Formhaus does not write to a file that is a symbolic link, or through a linked directory inside the project. Running it again changes nothing. If the Formhaus Claude Code plugin is installed, Claude Code is left as is.
+Existing entries are kept. An existing `formhaus` server with another command or args is reported and left unchanged, and a project `.mcp.json` never counts as set up. Before the first change to a config file, the original is saved as `<file>.bak`. If you edited the Cursor rule or the skill, Formhaus keeps your version. `--force` replaces it and saves your version as `<file>.bak`. Formhaus does not write to a file that is a symbolic link, or through a linked directory inside the project. Running it again changes nothing. If the Formhaus Claude Code plugin is installed, Claude Code is left as is.
 
 ## Options
 
@@ -27,6 +27,7 @@ Existing entries are kept. An existing `formhaus` server with another command or
 npx formhaus [setup] [options]
 
   --dry-run      Show the planned changes and write nothing
+  --force        Replace your edited skill and rule, saving them as .bak
   -h, --help     Show help
   -v, --version  Show the version
 ```

package/dist/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { homedir } from 'os';
 import { parseArgs, isDeepStrictEqual } from 'util';
-import { existsSync, statSync, accessSync, constants, readFileSync, mkdirSync, copyFileSync, rmSync, writeFileSync, chmodSync, renameSync, lstatSync } from 'fs';
-import { join, isAbsolute, sep, dirname, relative, resolve } from 'path';
+import { join, isAbsolute, resolve, dirname, parse, sep, relative } from 'path';
 import { spawnSync } from 'child_process';
+import { randomBytes, createHash } from 'crypto';
+import { existsSync, statSync, accessSync, constants, realpathSync, readFileSync, mkdirSync, copyFileSync, renameSync, rmSync, lstatSync, writeFileSync, chmodSync } from 'fs';
 
 // package.json
-var version = "0.14.2";
+var version = "0.14.3";
 
 // ../../.cursor/rules/formhaus.mdc
 var formhaus_default = '---\ndescription: Formhaus form definitions. Use when creating, editing or reviewing a Formhaus JSON form definition, or code that passes one to FormEngine or FormRenderer.\nalwaysApply: false\n---\n\n# Formhaus form definitions\n\nA Formhaus form is a JSON definition rendered by `@formhaus/core` with `@formhaus/react` or `@formhaus/vue`. One definition drives the web form and the Figma plugin.\n\n- Start each definition file with `"$schema": "https://formhaus.dev/schema/form-definition.json"`.\n- Required keys: `id` (kebab-case), `title`, `submit: { "label": "..." }`.\n- Use `fields` for a single page or `steps` for a multi-step form, never both.\n- Field `key` values are camelCase and unique across all steps.\n- `show` and `showAny` conditions reference existing field keys and use `eq`, `neq`, `in`, `notIn` or `notEmpty`.\n- Step `routes` only point to later steps. `to: null` ends the form without auto-submission.\n\n## Checking definitions\n\nWhen the `formhaus` MCP server is available (`npx -y @formhaus/mcp`):\n\n- Call `capabilities` for the current field types, validation rules and step semantics.\n- Call `example_definitions` for working examples.\n- Call `validate_definition` after every change and fix all `errors` before finishing.\n- Call `simulate_path` with sample answers to check branching steps and conditions.\n\nReference: https://formhaus.dev/api/definition.html\n';
@@ -44,38 +45,91 @@ function refuseLinkedDirectories(ctx, root, file) {
   const parts = relative(root, dirname(file)).split(sep).filter(Boolean);
   for (let index = 1; index <= parts.length; index++) refuseSymlink(ctx, resolve(root, ...parts.slice(0, index)));
 }
-function writeText(ctx, file, text, project) {
-  const backup = `${file}.bak`;
-  const temporary = `${file}.tmp`;
+function refuseLinks(ctx, file, project) {
   if (project !== void 0) refuseLinkedDirectories(ctx, project, file);
-  for (const path of [file, backup, temporary]) refuseSymlink(ctx, path);
+  for (const path of [file, `${file}.bak`]) refuseSymlink(ctx, path);
+}
+function temporaryPath(file) {
+  return `${file}.${randomBytes(8).toString("hex")}.tmp`;
+}
+function replaceWith(temporary, file, create) {
+  try {
+    create();
+    renameSync(temporary, file);
+  } catch (error) {
+    if (error.code !== "EEXIST") rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+function writeText(ctx, file, text, project, replaceBackup = false) {
+  const backup = `${file}.bak`;
+  refuseLinks(ctx, file, project);
   if (ctx.dryRun) return;
   mkdirSync(dirname(file), { recursive: true });
-  if (existsSync(file) && !existsSync(backup)) copyFileSync(file, backup, constants.COPYFILE_EXCL);
+  if (existsSync(file) && replaceBackup) {
+    const backupTemporary = temporaryPath(backup);
+    replaceWith(backupTemporary, backup, () => copyFileSync(file, backupTemporary, constants.COPYFILE_EXCL));
+  } else if (existsSync(file) && !existsSync(backup)) copyFileSync(file, backup, constants.COPYFILE_EXCL);
   const mode = statSync(file, { throwIfNoEntry: false })?.mode;
-  rmSync(temporary, { force: true });
-  writeFileSync(temporary, text, { flag: "wx", mode: mode === void 0 ? void 0 : mode & 384 });
-  if (mode !== void 0) chmodSync(temporary, mode & 4095);
-  renameSync(temporary, file);
+  const temporary = temporaryPath(file);
+  replaceWith(temporary, file, () => {
+    writeFileSync(temporary, text, { flag: "wx", mode: mode === void 0 ? void 0 : mode & 384 });
+    if (mode !== void 0) chmodSync(temporary, mode & 4095);
+  });
 }
-function writeIfChanged(ctx, file, text, project) {
+function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function writeAsset(ctx, file, text, shipped, project) {
   const current = readText(file);
   if (current === text) return "present";
-  writeText(ctx, file, text, project);
-  return current === void 0 ? "added" : "updated";
+  refuseLinks(ctx, file, project);
+  if (current === void 0 || shipped.includes(sha256(current))) {
+    writeText(ctx, file, text, project);
+    return current === void 0 ? "added" : "updated";
+  }
+  if (!ctx.force) return "kept";
+  writeText(ctx, file, text, project, true);
+  return "replaced";
+}
+function sameDirectory(a, b) {
+  if (resolve(a) === resolve(b)) return true;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+function isProjectRoot(directory) {
+  return existsSync(join(directory, ".git")) || existsSync(join(directory, "package.json")) || isDirectory(join(directory, ".cursor"));
+}
+function isFilesystemRoot(directory) {
+  return parse(directory).root === directory;
+}
+function findProjectRoot(ctx, isRoot = isFilesystemRoot) {
+  let directory = resolve(ctx.cwd);
+  while (!sameDirectory(directory, ctx.home) && !isRoot(directory)) {
+    if (isProjectRoot(directory)) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return void 0;
+    directory = parent;
+  }
+  return void 0;
 }
 function display(ctx, path) {
-  return path.startsWith(ctx.home + sep) ? `~${path.slice(ctx.home.length)}` : path;
+  return path === ctx.home || path.startsWith(ctx.home + sep) ? `~${path.slice(ctx.home.length)}` : path;
 }
 function step(ctx, agent, item, where, apply) {
   const target = display(ctx, where);
   const firstBackup = existsSync(where) && !existsSync(`${where}.bak`);
   try {
     const state = apply();
-    const backedUp = firstBackup && !ctx.dryRun && (state === "added" || state === "updated");
-    return { agent, item, where: backedUp ? `${target} (backup: ${target}.bak)` : target, state };
+    const backedUp = state === "replaced" || firstBackup && !ctx.dryRun && (state === "added" || state === "updated");
+    const change = { agent, item, where: backedUp ? `${target} (backup: ${target}.bak)` : target, state };
+    if (state === "kept") change.note = `Run npx formhaus --force to replace it. Your version will be saved as ${target}.bak.`;
+    return change;
   } catch (error) {
-    return { agent, item, where: target, state: "failed", error: error instanceof Error ? error.message : String(error) };
+    return { agent, item, where: target, state: "failed", note: error instanceof Error ? error.message : String(error) };
   }
 }
 
@@ -141,6 +195,7 @@ function command(ctx, executable, args) {
 // src/claude-code.ts
 var NAME = "Claude Code";
 var PLUGIN_PREFIX = `${SERVER_NAME}@`;
+var SHIPPED_SKILLS = ["e929afc9f58a267647341d962283d84749a18028e5ec2c4bd770a214c26a7c25"];
 var CLAUDE_ADD_ARGS = ["mcp", "add", "--scope", "user", SERVER_NAME, "--", SERVER.command, ...SERVER.args];
 function configDir(ctx) {
   return ctx.env.CLAUDE_CONFIG_DIR || join(ctx.home, ".claude");
@@ -203,7 +258,7 @@ var claudeCode = {
         NAME,
         "formhaus-create-form skill",
         skill,
-        () => hasPlugin(ctx) ? "present" : writeIfChanged(ctx, skill, SKILL_default)
+        () => hasPlugin(ctx) ? "present" : writeAsset(ctx, skill, SKILL_default, SHIPPED_SKILLS)
       ),
       ...projectWarning(ctx)
     ];
@@ -887,7 +942,7 @@ function validateTablePeek(ctx, peek, ptr) {
   if (peek === null || ctx.uk === 2)
     TomlError.x(peek === null ? "trying to redefine an already defined table or value" : "document contains an unsafe property", ctx, ptr);
 }
-function parse(toml, options = {}) {
+function parse2(toml, options = {}) {
   let ctx = {
     s: toml,
     p: 0,
@@ -975,7 +1030,7 @@ function isTable(value) {
 }
 function parseToml(text) {
   try {
-    return parse(text, { integersAsBigInt: true });
+    return parse2(text, { integersAsBigInt: true });
   } catch {
     return void 0;
   }
@@ -1026,9 +1081,7 @@ function claudeDesktopDir(ctx) {
 function found(ctx, directory, bin) {
   return isDirectory(directory) || findOnPath(ctx, bin) !== void 0;
 }
-function isProject(ctx) {
-  return ctx.cwd !== ctx.home && existsSync(join(ctx.cwd, "package.json"));
-}
+var SHIPPED_RULES = ["1bb79502ba88f1d38bef0bb3f34ede713f94487643496eae94ca6be7d2c8a32c"];
 var codex = {
   name: "Codex",
   detect: (ctx) => found(ctx, codexHome(ctx), "codex"),
@@ -1043,9 +1096,13 @@ var cursor = {
   apply(ctx) {
     const file = join(ctx.home, ".cursor", "mcp.json");
     const changes = [step(ctx, "Cursor", "MCP server", file, () => addJsonServer(ctx, file))];
-    if (!isProject(ctx)) return changes;
-    const rule = join(ctx.cwd, ".cursor", "rules", "formhaus.mdc");
-    changes.push(step(ctx, "Cursor", "formhaus rule", rule, () => writeIfChanged(ctx, rule, formhaus_default, ctx.cwd)));
+    const root = findProjectRoot(ctx);
+    if (root === void 0) {
+      const note = "Run npx formhaus inside a project to add the Cursor rule.";
+      return [...changes, { agent: "Cursor", item: "formhaus rule", where: display(ctx, ctx.cwd), state: "skipped", note }];
+    }
+    const rule = join(root, ".cursor", "rules", "formhaus.mdc");
+    changes.push(step(ctx, "Cursor", "formhaus rule", rule, () => writeAsset(ctx, rule, formhaus_default, SHIPPED_RULES, root)));
     return changes;
   }
 };
@@ -1074,8 +1131,11 @@ var MANUAL_AGENTS = [
 var LABELS = {
   added: ["added", "will add"],
   updated: ["updated", "will update"],
+  replaced: ["replaced", "will replace"],
   present: ["already set up", "already set up"],
+  kept: ["has your edits, left unchanged", "has your edits, will leave unchanged"],
   different: ["different server, check it", "different server, check it"],
+  skipped: ["skipped, not in a project", "skipped, not in a project"],
   failed: ["failed", "failed"]
 };
 function label(ctx, state) {
@@ -1089,7 +1149,7 @@ function printChanges(ctx, changes, print) {
   for (const change of changes) {
     const row = [change.agent.padEnd(agentWidth), change.item.padEnd(itemWidth), label(ctx, change.state).padEnd(stateWidth), change.where];
     print(`  ${row.join("  ")}`);
-    if (change.error) print(`    ${change.error}`);
+    if (change.note) print(`    ${change.note}`);
   }
 }
 function printManual(names, print) {
@@ -1115,7 +1175,7 @@ function setup(ctx, print) {
     printManual(manual, print);
   }
   const failed = changes.some((change) => change.state === "failed");
-  const changed = changes.some((change) => change.state === "added" || change.state === "updated");
+  const changed = changes.some((change) => change.state === "added" || change.state === "updated" || change.state === "replaced");
   print("");
   const different = changes.some((change) => change.state === "different");
   if (different) {
@@ -1136,16 +1196,18 @@ var HELP = `Usage: npx formhaus [setup] [options]
 Adds the Formhaus MCP server (npx -y @formhaus/mcp) to the coding agents
 installed on this machine: Claude Code, Codex, Cursor and Claude Desktop.
 Installs the formhaus-create-form skill in Claude Code and, inside a project,
-the Formhaus rule in .cursor/rules. Running it again changes nothing.
+the Formhaus rule in .cursor/rules at the project root. Running it again
+changes nothing. Your edits to the skill and the rule are kept.
 
 Options:
   --dry-run      Show the planned changes and write nothing
+  --force        Replace your edited skill and rule, saving them as .bak
   -h, --help     Show this help
   -v, --version  Show the version`;
 function main(argv, ctx, print, printError) {
   let parsed;
   try {
-    parsed = parse2(argv);
+    parsed = parse3(argv);
   } catch (error) {
     printError(`${error instanceof Error ? error.message : String(error)}
 Run npx formhaus --help for usage.`);
@@ -1161,14 +1223,15 @@ Run npx formhaus --help for usage.`);
 Run npx formhaus --help for usage.`);
     return 1;
   }
-  return setup({ ...ctx, dryRun: values["dry-run"] === true }, print);
+  return setup({ ...ctx, dryRun: values["dry-run"] === true, force: values.force === true }, print);
 }
-function parse2(argv) {
+function parse3(argv) {
   return parseArgs({
     args: argv,
     allowPositionals: true,
     options: {
       "dry-run": { type: "boolean" },
+      force: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formhaus",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "Set up the Formhaus MCP server and agent instructions in Claude Code, Codex, Cursor and Claude Desktop with one command.",
   "type": "module",
   "engines": {