@corva/ui 3.77.0-11 → 3.77.0-13

package/MCP_README.md

@@ -215,12 +215,15 @@ This creates `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.codex
 Restart your IDE or reload MCP servers afterward.
 
 > If any of these files already exist, the setup command **extends** them — your existing MCP server entries are
-> preserved, and only the `corva-ui` entry (`corva_ui` in the Codex TOML) is added or updated. "Updated" means replaced
-> with the stock entry: anything you added to it by hand, such as an `env` block with
-> `CORVA_UI_MCP_TELEMETRY_DISABLED`, is dropped and has to be re-added. The files are re-serialized on write, so
-> comments and hand formatting in the TOML do not survive either. A file that fails to parse is overwritten from
-> scratch (the command warns when it does that). On native Windows the generated entry uses plain `npx`; if your client
-> cannot spawn it, apply the `cmd /c` form from the Native Windows note under [Local Setup](#local-setup-recommended).
+> preserved, and the `corva-ui` entry (`corva_ui` in the Codex TOML) is added only when it is missing. An entry that
+> already exists is kept exactly as it is, so anything you added by hand, such as an `env` block with
+> `CORVA_UI_MCP_TELEMETRY_DISABLED`, a `startup_timeout_sec`, or the Windows `cmd /c` form, survives a re-run after an
+> upgrade; the command prints `(kept)` for that file. Pass `--force` to replace the entry with the stock one. A write
+> re-serializes the whole file, so when the command adds or replaces an entry in the Codex TOML, comments and hand
+> formatting are lost (the command says so in its output). A file that fails to parse is never written: the command
+> prints the parse error and the path, and exits with a non-zero code. On native Windows the generated entry uses plain
+> `npx`; if your client cannot spawn it, apply the `cmd /c` form from the Native Windows note under
+> [Local Setup](#local-setup-recommended).
 
 > **Monorepo:** Run the setup command from the monorepo root, not from individual
 > `apps/*` directories. See [Monorepo Setup](#monorepo-setup) for details.

package/mcp-server/server.mjs

@@ -248,7 +248,7 @@ const validateDsn = dsn => {
 
 const MCP_SERVER_VERSION = '1.5.0';
 
-var version = "3.77.0-11";
+var version = "3.77.0-13";
 
 const CORVA_UI_VERSION = version;
 

package/mcp-server/setup.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 
 /*!
@@ -1019,12 +1019,7 @@ function stringify(obj, {
   return str;
 }
 
-/**
- * corva-ui-mcp-setup CLI
- *
- * Creates/updates MCP config files so AI coding agents can discover the @corva/ui MCP server.
- * Run from any project root: npx -p @corva/ui corva-ui-mcp-setup
- */
+/** The stock entry the CLI writes. Anything a developer adds by hand is not part of it. */
 const SERVER_CONFIG = {
   command: 'npx',
   args: ['-p', '@corva/ui', 'corva-ui-mcp']
@@ -1053,38 +1048,68 @@ const TARGETS = [{
   path: '.codex/config.toml',
   format: TOML_FORMAT
 }];
-const ACTION_SYMBOLS = {
-  created: '+',
-  updated: '~',
-  skipped: '='
-};
-const isRecord = value => typeof value === 'object' && value !== null;
+
+const isRecord = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+const errorMessage = error => error instanceof Error ? error.message : String(error);
+
+/**
+ * Adds the stock `corva-ui` entry to one config file.
+ *
+ * An entry that already exists is left as it is, whatever it contains: developers add `env`,
+ * timeouts and the Windows `cmd /c` form by hand, and a re-run after an upgrade must not drop
+ * them. Only `force` replaces it. A file that does not parse is never written.
+ */
 const writeConfig = ({
-  path: filePath,
-  format
+  target,
+  force = false,
+  cwd = process.cwd()
 }) => {
-  const absolutePath = resolve(filePath);
-  mkdirSync(dirname(absolutePath), {
-    recursive: true
-  });
+  const {
+    path: filePath,
+    format
+  } = target;
+  const absolutePath = resolve(cwd, filePath);
+  const fileExists = existsSync(absolutePath);
   let existing = {};
-  let action = 'created';
-  if (existsSync(absolutePath)) {
-    action = 'updated';
+  if (fileExists) {
     const raw = readFileSync(absolutePath, 'utf-8');
+    let parsed;
     try {
-      existing = format.parse(raw);
-    } catch {
-      console.warn(`  Warning: ${filePath} contained invalid ${format.formatName} and will be overwritten.`);
-      existing = {};
-      action = 'created';
+      parsed = format.parse(raw);
+    } catch (error) {
+      return {
+        file: filePath,
+        action: 'failed',
+        note: `invalid ${format.formatName}, file left unchanged: ${errorMessage(error)}`
+      };
+    }
+    if (!isRecord(parsed)) {
+      return {
+        file: filePath,
+        action: 'failed',
+        note: `invalid ${format.formatName}, file left unchanged: top level is not an object`
+      };
     }
+    existing = parsed;
   }
-  const servers = isRecord(existing[format.serversKey]) ? existing[format.serversKey] : {};
-  if (JSON.stringify(servers[format.serverName]) === JSON.stringify(SERVER_CONFIG)) {
+  const serversValue = existing[format.serversKey];
+
+  // A servers block that is not a plain object (an array, a string, null) cannot hold the entry.
+  // Writing over it would drop whatever it held, so refuse instead of guessing.
+  if (serversValue !== undefined && !isRecord(serversValue)) {
+    return {
+      file: filePath,
+      action: 'failed',
+      note: `"${format.serversKey}" is not an object, file left unchanged`
+    };
+  }
+  const servers = serversValue ?? {};
+  const hasEntry = Object.hasOwn(servers, format.serverName);
+  if (hasEntry && !force) {
     return {
       file: filePath,
-      action: 'skipped'
+      action: 'kept',
+      note: `entry "${format.serverName}" exists; pass --force to replace it with the stock entry`
     };
   }
   const merged = {
@@ -1094,30 +1119,90 @@ const writeConfig = ({
       [format.serverName]: SERVER_CONFIG
     }
   };
+  mkdirSync(dirname(absolutePath), {
+    recursive: true
+  });
   writeFileSync(absolutePath, `${format.serialize(merged)}\n`);
+  let action = 'created';
+  if (hasEntry) {
+    action = 'replaced';
+  } else if (fileExists) {
+    action = 'added';
+  }
+  const note = fileExists && format.formatName === 'TOML' ? 'the file was rewritten; TOML comments and hand formatting are removed' : undefined;
   return {
     file: filePath,
-    action
+    action,
+    note
   };
 };
-const main = () => {
-  console.log('Setting up @corva/ui MCP server configs...\n');
-  const results = [];
-  for (const target of TARGETS) {
+
+const ACTION_SYMBOLS = {
+  created: '+',
+  added: '+',
+  replaced: '~',
+  kept: '=',
+  failed: '!'
+};
+const formatResult = ({
+  file,
+  action,
+  note
+}) => `  ${ACTION_SYMBOLS[action]} ${file} (${action})${note ? `: ${note}` : ''}`;
+
+/** Runs the setup over every target and collects the report. Never throws for a single target. */
+const runSetup = ({
+  force = false,
+  cwd = process.cwd()
+} = {}) => {
+  const results = TARGETS.map(target => {
     try {
-      results.push(writeConfig(target));
+      return writeConfig({
+        target,
+        force,
+        cwd
+      });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.error(`  Error writing ${target.path}: ${message}`);
+      return {
+        file: target.path,
+        action: 'failed',
+        note: `write failed: ${message}`
+      };
     }
-  }
-  console.log('');
-  for (const {
-    file,
+  });
+  const failed = results.filter(({
     action
-  } of results) {
-    console.log(`  ${ACTION_SYMBOLS[action]} ${file} (${action})`);
+  }) => action === 'failed');
+  const lines = ['Setting up @corva/ui MCP server configs...', '', ...results.map(formatResult), '', failed.length > 0 ? `${failed.length} of ${results.length} config files were not written. Fix the errors above and run the command again.` : 'Done! The corva-ui MCP server is now configured for this project.'];
+  return {
+    lines,
+    exitCode: failed.length > 0 ? 1 : 0,
+    results
+  };
+};
+
+/**
+ * corva-ui-mcp-setup CLI
+ *
+ * Adds the @corva/ui MCP server entry to the MCP config files of the current project, so AI
+ * coding agents can discover it. Run from any project root: npx -p @corva/ui corva-ui-mcp-setup
+ *
+ * An entry that already exists is kept as it is; `--force` replaces it with the stock entry.
+ * The logic lives in src/setup so the Jest suite can cover it; this file only parses argv,
+ * prints the report and sets the exit code.
+ */
+const main = () => {
+  const force = process.argv.includes('--force');
+  const {
+    lines,
+    exitCode
+  } = runSetup({
+    force
+  });
+  for (const line of lines) {
+    console.log(line);
   }
-  console.log('\nDone! The corva-ui MCP server is now configured for this project.');
+  process.exitCode = exitCode;
 };
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corva/ui",
-  "version": "3.77.0-11",
+  "version": "3.77.0-13",
   "license": "UNLICENSED",
   "description": "Shared components/utils for Corva ui projects",
   "repository": {