@maz-ui/node 5.1.0 → 5.2.0-beta.0

package/README.md

@@ -18,7 +18,7 @@ npm install @maz-ui/node
 - 🔧 **Highly configurable** - custom loggers with different levels and reporters
 - 🛡️ **Error handling** - comprehensive error management
 - 🎯 **Multiple log types** - info, debug, trace, start, ready, fail, box
-- 🤖 **AI agents setup** - `setupAgents` configures the AI coding agents of a project for maz-ui (rules and MCP server), as `npx @maz-ui/mcp init` does: [documentation](https://maz-ui.com/ecosystem/node/setup-agents)
+- 🤖 **AI agents setup** - `setupAgents` configures the AI coding agents of a project for maz-ui (rules and MCP server), as `npx @maz-ui/mcp init` does, or for another tool that ships its own MCP server and rules (`tool` option): [documentation](https://maz-ui.com/ecosystem/node/setup-agents)
 
 ## Usage
 

package/dist/index.d.mts

@@ -171,7 +171,7 @@ declare function redactError<T>(error: T): T;
 /**
  * AI coding agents supported by `setupAgents`.
  *
- * - `claude`: Claude Code rule (`.claude/rules/maz-ui.md`) and MCP server (`.mcp.json`)
+ * - `claude`: Claude Code rule (`.claude/rules/<tool>.md`) and MCP server (`.mcp.json`)
  * - `agents-md`: section in `AGENTS.md` (Codex, Cursor, Copilot, Windsurf, Zed, Gemini...)
  * - `cursor`: MCP server in `.cursor/mcp.json` (rules come from `AGENTS.md`)
  * - `vscode`: MCP server in `.vscode/mcp.json` for GitHub Copilot (rules come from `AGENTS.md`)
@@ -183,9 +183,9 @@ interface SetupAgentsOptions {
     rootDir: string;
     /** Agents to configure. Default: the agents detected in the project */
     targets?: AgentTarget[];
-    /** Write the maz-ui rules (Claude Code rule, `AGENTS.md` section). Default `true` */
+    /** Write the rules of the tool (Claude Code rule, `AGENTS.md` section). Default `true` */
     rules?: boolean;
-    /** Register the maz-ui MCP server. Default `true` */
+    /** Register the MCP server of the tool. Default `true` */
     mcp?: boolean;
     /** Compute the changes without writing anything */
     dryRun?: boolean;
@@ -193,11 +193,18 @@ interface SetupAgentsOptions {
     remove?: boolean;
     /** Folder of the maz-ui agent docs. Default: `docs/` of the maz-ui package installed in `rootDir` */
     docsDir?: string;
-    /** Command used to start the MCP server */
-    mcpServer?: {
-        command: string;
-        args: string[];
-    };
+    /** Command used to start the MCP server. Default: `mcpServerCommand(rootDir, mcpVersion, tool)` */
+    mcpServer?: McpServerCommand;
+    /** Version of the MCP package pinned in the `npx -y` command, when the project does not install it. Default `latest` */
+    mcpVersion?: string;
+    /** Tool whose agents are configured. Default: maz-ui (`MAZ_UI_AGENTS_TOOL`) */
+    tool?: AgentsTool;
+    /** Rules of the tool, required with another `tool` than maz-ui. Default: the maz-ui agent docs of `docsDir` */
+    agentDocs?: AgentDocs;
+}
+interface McpServerCommand {
+    command: string;
+    args: string[];
 }
 type SetupAgentsAction = 'create' | 'update' | 'remove' | 'unchanged' | 'skip';
 interface SetupAgentsChange {
@@ -210,15 +217,54 @@ interface SetupAgentsResult {
     targets: AgentTarget[];
     version: string;
     changes: SetupAgentsChange[];
+    /** Command registered in the MCP config files */
+    mcpServer: McpServerCommand;
+    /** `false` when the server runs through `npx -y` because the project does not install the MCP package */
+    localMcpServer: boolean;
 }
 declare const MANAGED_MARKER = "Managed by maz-ui";
 declare const AGENTS_MD_BEGIN = "<!-- BEGIN:maz-ui -->";
 declare const AGENTS_MD_END = "<!-- END:maz-ui -->";
 declare const MCP_SERVER_NAME = "maz-ui";
-declare const DEFAULT_MCP_SERVER: {
-    command: string;
-    args: string[];
-};
+declare const DEFAULT_MCP_SERVER: McpServerCommand;
+/**
+ * A tool whose AI agents are configured by `setupAgents`: maz-ui by default,
+ * or another package that ships its own MCP server and rules.
+ */
+interface AgentsTool {
+    /** Name of the tool: key of its MCP server, `.claude/rules/<name>.md` and markers of the generated content */
+    name: string;
+    /** Package that ships the MCP server */
+    mcpPackage: string;
+    /** Bin of `mcpPackage` that starts the MCP server */
+    mcpBin: string;
+    /** Arguments of `mcpBin` that start the MCP server (e.g. `['mcp']`). Default `[]` */
+    mcpArgs?: string[];
+    /** What generates the rules, written in their header (markdown, e.g. `` `npx relizy mcp init` ``) */
+    generatedBy: string;
+    /** Line written under the title of the rules. Default: `> <name> <version> is installed: these rules match this version.` */
+    versionNote?: (version: string) => string;
+}
+declare const MAZ_UI_AGENTS_TOOL: AgentsTool;
+type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm';
+/** `true` when the `package.json` of the project declares the MCP package of the tool (`@maz-ui/mcp` by default) */
+declare function installsMcpPackage(rootDir: string, tool?: AgentsTool): boolean;
+/** Package manager of a project: the `packageManager` field, else its lockfile */
+declare function detectPackageManager(rootDir: string): PackageManager;
+/**
+ * Command of the MCP server of a tool (maz-ui by default) for a project. When
+ * the project installs its package, the package manager starts the installed
+ * version in about a second, at the version of the lockfile. Otherwise
+ * `npx -y` downloads it, pinned to `version`: a dist-tag (`latest`) makes npx
+ * query the registry at every start, which can exceed the start timeout of the
+ * agents behind a slow registry.
+ */
+declare function mcpServerCommand(rootDir: string, version?: string, tool?: AgentsTool): McpServerCommand;
+/**
+ * `true` when generated rules were edited by hand since they were written:
+ * they are kept, a newer version of the rules would overwrite the edits.
+ */
+declare function isEditedManagedContent(content: string | undefined, tool?: AgentsTool): boolean;
 /** Detects the AI agents configured in a project */
 declare function detectAgentTargets(rootDir: string): AgentTarget[];
 interface AgentDocs {
@@ -233,23 +279,41 @@ interface AgentDocs {
  * package installed for the project is found.
  */
 declare function findInstalledPackage(fromDir: string, name: string): string | undefined;
-/** Reads the agent files shipped in `maz-ui/docs/agents` */
 /** Version of an installed package, read from its `package.json` */
 declare function readPackageVersion(packageDir: string): string | undefined;
+/**
+ * Workspace patterns of a monorepo: the `packages` of `pnpm-workspace.yaml`,
+ * else the `workspaces` of `package.json` (npm, yarn, bun), else `apps/*` and
+ * `packages/*`. Negated patterns are ignored.
+ */
+declare function readWorkspacePatterns(rootDir: string): string[];
+/** Folders of the workspaces of a monorepo, in the order of the patterns. Only the fixed part of each pattern is read (`apps/*` reads `apps`) */
+declare function findWorkspaceDirs(rootDir: string): string[];
 /**
  * Finds a package installed in a project: in the `node_modules` of the
- * project root and of its workspace folders (`apps/*`, `packages/*`, for
- * monorepos without hoisting), then in the parent folders.
+ * project root and of its workspaces (monorepos without hoisting), then in
+ * the parent folders.
  */
 declare function findProjectPackage(rootDir: string, name: string): string | undefined;
+/** Reads the agent files shipped in `maz-ui/docs/agents` */
 declare function readAgentDocs(rootDir: string, docsDir?: string): AgentDocs;
 /**
- * Configures the AI coding agents of a project to use maz-ui: rules (version
- * matched with the installed maz-ui) and the maz-ui MCP server. Idempotent and
- * conservative: it only writes files it owns, a delimited section of
- * `AGENTS.md` and its own entry of the MCP config files.
+ * Writes a temporary file then renames it: a concurrent reader (several Nuxt
+ * apps of a monorepo starting together) sees the old or the new file, never a
+ * truncated one.
+ */
+declare function writeFileAtomic(path: string, content: string): void;
+/** Compares two semver versions: negative when `a < b`, positive when `a > b`, `0` when equal */
+declare function compareVersions(a: string, b: string): number;
+/** Version of the tool (maz-ui by default) that generated a managed content, read from its header */
+declare function readManagedVersion(content: string | undefined, tool?: AgentsTool): string | undefined;
+/**
+ * Configures the AI coding agents of a project to use a tool, maz-ui by
+ * default: rules (version matched with the installed tool) and its MCP server.
+ * Idempotent and conservative: it only writes files it owns, a delimited
+ * section of `AGENTS.md` and its own entry of the MCP config files.
  */
 declare function setupAgents(options: SetupAgentsOptions): SetupAgentsResult;
 
-export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MCP_SERVER_NAME, createLogger, detectAgentTargets, execPromise, findInstalledPackage, findProjectPackage, logger, printBanner, readAgentDocs, readPackageVersion, redactError, redactSecrets, setupAgents };
-export type { AgentDocs, AgentTarget, ExecPromiseOptions, LogLevel, Logger, LoggerOptions, SetupAgentsAction, SetupAgentsChange, SetupAgentsOptions, SetupAgentsResult };
+export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MAZ_UI_AGENTS_TOOL, MCP_SERVER_NAME, compareVersions, createLogger, detectAgentTargets, detectPackageManager, execPromise, findInstalledPackage, findProjectPackage, findWorkspaceDirs, installsMcpPackage, isEditedManagedContent, logger, mcpServerCommand, printBanner, readAgentDocs, readManagedVersion, readPackageVersion, readWorkspacePatterns, redactError, redactSecrets, setupAgents, writeFileAtomic };
+export type { AgentDocs, AgentTarget, AgentsTool, ExecPromiseOptions, LogLevel, Logger, LoggerOptions, McpServerCommand, PackageManager, SetupAgentsAction, SetupAgentsChange, SetupAgentsOptions, SetupAgentsResult };

package/dist/index.d.ts

@@ -171,7 +171,7 @@ declare function redactError<T>(error: T): T;
 /**
  * AI coding agents supported by `setupAgents`.
  *
- * - `claude`: Claude Code rule (`.claude/rules/maz-ui.md`) and MCP server (`.mcp.json`)
+ * - `claude`: Claude Code rule (`.claude/rules/<tool>.md`) and MCP server (`.mcp.json`)
  * - `agents-md`: section in `AGENTS.md` (Codex, Cursor, Copilot, Windsurf, Zed, Gemini...)
  * - `cursor`: MCP server in `.cursor/mcp.json` (rules come from `AGENTS.md`)
  * - `vscode`: MCP server in `.vscode/mcp.json` for GitHub Copilot (rules come from `AGENTS.md`)
@@ -183,9 +183,9 @@ interface SetupAgentsOptions {
     rootDir: string;
     /** Agents to configure. Default: the agents detected in the project */
     targets?: AgentTarget[];
-    /** Write the maz-ui rules (Claude Code rule, `AGENTS.md` section). Default `true` */
+    /** Write the rules of the tool (Claude Code rule, `AGENTS.md` section). Default `true` */
     rules?: boolean;
-    /** Register the maz-ui MCP server. Default `true` */
+    /** Register the MCP server of the tool. Default `true` */
     mcp?: boolean;
     /** Compute the changes without writing anything */
     dryRun?: boolean;
@@ -193,11 +193,18 @@ interface SetupAgentsOptions {
     remove?: boolean;
     /** Folder of the maz-ui agent docs. Default: `docs/` of the maz-ui package installed in `rootDir` */
     docsDir?: string;
-    /** Command used to start the MCP server */
-    mcpServer?: {
-        command: string;
-        args: string[];
-    };
+    /** Command used to start the MCP server. Default: `mcpServerCommand(rootDir, mcpVersion, tool)` */
+    mcpServer?: McpServerCommand;
+    /** Version of the MCP package pinned in the `npx -y` command, when the project does not install it. Default `latest` */
+    mcpVersion?: string;
+    /** Tool whose agents are configured. Default: maz-ui (`MAZ_UI_AGENTS_TOOL`) */
+    tool?: AgentsTool;
+    /** Rules of the tool, required with another `tool` than maz-ui. Default: the maz-ui agent docs of `docsDir` */
+    agentDocs?: AgentDocs;
+}
+interface McpServerCommand {
+    command: string;
+    args: string[];
 }
 type SetupAgentsAction = 'create' | 'update' | 'remove' | 'unchanged' | 'skip';
 interface SetupAgentsChange {
@@ -210,15 +217,54 @@ interface SetupAgentsResult {
     targets: AgentTarget[];
     version: string;
     changes: SetupAgentsChange[];
+    /** Command registered in the MCP config files */
+    mcpServer: McpServerCommand;
+    /** `false` when the server runs through `npx -y` because the project does not install the MCP package */
+    localMcpServer: boolean;
 }
 declare const MANAGED_MARKER = "Managed by maz-ui";
 declare const AGENTS_MD_BEGIN = "<!-- BEGIN:maz-ui -->";
 declare const AGENTS_MD_END = "<!-- END:maz-ui -->";
 declare const MCP_SERVER_NAME = "maz-ui";
-declare const DEFAULT_MCP_SERVER: {
-    command: string;
-    args: string[];
-};
+declare const DEFAULT_MCP_SERVER: McpServerCommand;
+/**
+ * A tool whose AI agents are configured by `setupAgents`: maz-ui by default,
+ * or another package that ships its own MCP server and rules.
+ */
+interface AgentsTool {
+    /** Name of the tool: key of its MCP server, `.claude/rules/<name>.md` and markers of the generated content */
+    name: string;
+    /** Package that ships the MCP server */
+    mcpPackage: string;
+    /** Bin of `mcpPackage` that starts the MCP server */
+    mcpBin: string;
+    /** Arguments of `mcpBin` that start the MCP server (e.g. `['mcp']`). Default `[]` */
+    mcpArgs?: string[];
+    /** What generates the rules, written in their header (markdown, e.g. `` `npx relizy mcp init` ``) */
+    generatedBy: string;
+    /** Line written under the title of the rules. Default: `> <name> <version> is installed: these rules match this version.` */
+    versionNote?: (version: string) => string;
+}
+declare const MAZ_UI_AGENTS_TOOL: AgentsTool;
+type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm';
+/** `true` when the `package.json` of the project declares the MCP package of the tool (`@maz-ui/mcp` by default) */
+declare function installsMcpPackage(rootDir: string, tool?: AgentsTool): boolean;
+/** Package manager of a project: the `packageManager` field, else its lockfile */
+declare function detectPackageManager(rootDir: string): PackageManager;
+/**
+ * Command of the MCP server of a tool (maz-ui by default) for a project. When
+ * the project installs its package, the package manager starts the installed
+ * version in about a second, at the version of the lockfile. Otherwise
+ * `npx -y` downloads it, pinned to `version`: a dist-tag (`latest`) makes npx
+ * query the registry at every start, which can exceed the start timeout of the
+ * agents behind a slow registry.
+ */
+declare function mcpServerCommand(rootDir: string, version?: string, tool?: AgentsTool): McpServerCommand;
+/**
+ * `true` when generated rules were edited by hand since they were written:
+ * they are kept, a newer version of the rules would overwrite the edits.
+ */
+declare function isEditedManagedContent(content: string | undefined, tool?: AgentsTool): boolean;
 /** Detects the AI agents configured in a project */
 declare function detectAgentTargets(rootDir: string): AgentTarget[];
 interface AgentDocs {
@@ -233,23 +279,41 @@ interface AgentDocs {
  * package installed for the project is found.
  */
 declare function findInstalledPackage(fromDir: string, name: string): string | undefined;
-/** Reads the agent files shipped in `maz-ui/docs/agents` */
 /** Version of an installed package, read from its `package.json` */
 declare function readPackageVersion(packageDir: string): string | undefined;
+/**
+ * Workspace patterns of a monorepo: the `packages` of `pnpm-workspace.yaml`,
+ * else the `workspaces` of `package.json` (npm, yarn, bun), else `apps/*` and
+ * `packages/*`. Negated patterns are ignored.
+ */
+declare function readWorkspacePatterns(rootDir: string): string[];
+/** Folders of the workspaces of a monorepo, in the order of the patterns. Only the fixed part of each pattern is read (`apps/*` reads `apps`) */
+declare function findWorkspaceDirs(rootDir: string): string[];
 /**
  * Finds a package installed in a project: in the `node_modules` of the
- * project root and of its workspace folders (`apps/*`, `packages/*`, for
- * monorepos without hoisting), then in the parent folders.
+ * project root and of its workspaces (monorepos without hoisting), then in
+ * the parent folders.
  */
 declare function findProjectPackage(rootDir: string, name: string): string | undefined;
+/** Reads the agent files shipped in `maz-ui/docs/agents` */
 declare function readAgentDocs(rootDir: string, docsDir?: string): AgentDocs;
 /**
- * Configures the AI coding agents of a project to use maz-ui: rules (version
- * matched with the installed maz-ui) and the maz-ui MCP server. Idempotent and
- * conservative: it only writes files it owns, a delimited section of
- * `AGENTS.md` and its own entry of the MCP config files.
+ * Writes a temporary file then renames it: a concurrent reader (several Nuxt
+ * apps of a monorepo starting together) sees the old or the new file, never a
+ * truncated one.
+ */
+declare function writeFileAtomic(path: string, content: string): void;
+/** Compares two semver versions: negative when `a < b`, positive when `a > b`, `0` when equal */
+declare function compareVersions(a: string, b: string): number;
+/** Version of the tool (maz-ui by default) that generated a managed content, read from its header */
+declare function readManagedVersion(content: string | undefined, tool?: AgentsTool): string | undefined;
+/**
+ * Configures the AI coding agents of a project to use a tool, maz-ui by
+ * default: rules (version matched with the installed tool) and its MCP server.
+ * Idempotent and conservative: it only writes files it owns, a delimited
+ * section of `AGENTS.md` and its own entry of the MCP config files.
  */
 declare function setupAgents(options: SetupAgentsOptions): SetupAgentsResult;
 
-export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MCP_SERVER_NAME, createLogger, detectAgentTargets, execPromise, findInstalledPackage, findProjectPackage, logger, printBanner, readAgentDocs, readPackageVersion, redactError, redactSecrets, setupAgents };
-export type { AgentDocs, AgentTarget, ExecPromiseOptions, LogLevel, Logger, LoggerOptions, SetupAgentsAction, SetupAgentsChange, SetupAgentsOptions, SetupAgentsResult };
+export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MAZ_UI_AGENTS_TOOL, MCP_SERVER_NAME, compareVersions, createLogger, detectAgentTargets, detectPackageManager, execPromise, findInstalledPackage, findProjectPackage, findWorkspaceDirs, installsMcpPackage, isEditedManagedContent, logger, mcpServerCommand, printBanner, readAgentDocs, readManagedVersion, readPackageVersion, readWorkspacePatterns, redactError, redactSecrets, setupAgents, writeFileAtomic };
+export type { AgentDocs, AgentTarget, AgentsTool, ExecPromiseOptions, LogLevel, Logger, LoggerOptions, McpServerCommand, PackageManager, SetupAgentsAction, SetupAgentsChange, SetupAgentsOptions, SetupAgentsResult };

package/dist/index.mjs

@@ -3,8 +3,9 @@ import process$1 from 'node:process';
 import { blueBright } from 'colorette';
 import { createConsola } from 'consola';
 import figlet from 'figlet';
-import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, rmSync, readdirSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
 import { parse, applyEdits, modify } from 'jsonc-parser';
 
 const LogLevelMap = {
@@ -189,16 +190,93 @@ const AGENTS_MD_BEGIN = "<!-- BEGIN:maz-ui -->";
 const AGENTS_MD_END = "<!-- END:maz-ui -->";
 const MCP_SERVER_NAME = "maz-ui";
 const DEFAULT_MCP_SERVER = { command: "npx", args: ["-y", "@maz-ui/mcp@latest"] };
-const CLAUDE_RULE_FILE = ".claude/rules/maz-ui.md";
+const MAZ_UI_AGENTS_TOOL = {
+  name: "maz-ui",
+  mcpPackage: "@maz-ui/mcp",
+  mcpBin: "maz-ui-mcp",
+  generatedBy: "`npx @maz-ui/mcp init` (or the `mazUi.agents` Nuxt option)",
+  versionNote: (version) => `> maz-ui ${version} is installed: these rules and the docs in \`node_modules/maz-ui/docs\` match this version.`
+};
+function escapeRegExp(value) {
+  return value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const toolSetups = /* @__PURE__ */ new WeakMap();
+function resolveTool(tool) {
+  let setup = toolSetups.get(tool);
+  if (!setup) {
+    const marker = `Managed by ${tool.name}`;
+    setup = {
+      tool,
+      marker,
+      agentsMdBegin: `<!-- BEGIN:${tool.name} -->`,
+      agentsMdEnd: `<!-- END:${tool.name} -->`,
+      ruleFile: `.claude/rules/${tool.name}.md`,
+      managedHeader: new RegExp(`<!-- ${escapeRegExp(marker)}[^\\n]*?-->`),
+      managedVersion: new RegExp(`${escapeRegExp(marker)} (\\d[^\\s:]*)`)
+    };
+    toolSetups.set(tool, setup);
+  }
+  return setup;
+}
+function readPackageJson(rootDir) {
+  try {
+    return JSON.parse(readFileSync(join(rootDir, "package.json"), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function installsMcpPackage(rootDir, tool = MAZ_UI_AGENTS_TOOL) {
+  const pkg = readPackageJson(rootDir);
+  return ["dependencies", "devDependencies", "optionalDependencies"].some((field) => pkg?.[field]?.[tool.mcpPackage] !== void 0);
+}
+function detectPackageManager(rootDir) {
+  const declared = String(readPackageJson(rootDir)?.packageManager ?? "").split("@")[0];
+  if (["pnpm", "yarn", "bun", "npm"].includes(declared))
+    return declared;
+  const lockfiles = [["pnpm-lock.yaml", "pnpm"], ["yarn.lock", "yarn"], ["bun.lock", "bun"], ["bun.lockb", "bun"]];
+  return lockfiles.find(([file]) => existsSync(join(rootDir, file)))?.[1] ?? "npm";
+}
+function localMcpCommands(tool) {
+  const bin = [tool.mcpBin, ...tool.mcpArgs ?? []];
+  return {
+    pnpm: { command: "pnpm", args: ["exec", ...bin] },
+    yarn: { command: "yarn", args: ["run", ...bin] },
+    bun: { command: "bun", args: ["x", "--no-install", ...bin] },
+    npm: { command: "npx", args: ["--no-install", ...bin] }
+  };
+}
+function mcpServerCommand(rootDir, version = "latest", tool = MAZ_UI_AGENTS_TOOL) {
+  return installsMcpPackage(rootDir, tool) ? localMcpCommands(tool)[detectPackageManager(rootDir)] : { command: "npx", args: ["-y", `${tool.mcpPackage}@${version}`, ...tool.mcpArgs ?? []] };
+}
+function pinnedMcpVersion(server, tool) {
+  const pinned = new RegExp(`^${escapeRegExp(tool.mcpPackage)}@(\\d\\S*)$`);
+  return server.args.map((arg) => pinned.exec(arg)?.[1]).find(Boolean);
+}
+function isGeneratedMcpCommand(server, tool) {
+  const command = [server.command, ...Array.isArray(server.args) ? server.args : []].join(" ");
+  const args = (tool.mcpArgs ?? []).map((arg) => ` ${escapeRegExp(arg)}`).join("");
+  return new RegExp(`^npx -y ${escapeRegExp(tool.mcpPackage)}(?:@\\S+)?${args}$`).test(command) || Object.values(localMcpCommands(tool)).some((local) => command === [local.command, ...local.args].join(" "));
+}
 const CLAUDE_MEMORY_FILES = ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"];
-function withVersion(content, version) {
-  return content.replace(/^(#{1,2} .+)\n/, `$1
+function withVersion(content, version, tool) {
+  const note = tool.versionNote?.(version) ?? `> ${tool.name} ${version} is installed: these rules match this version.`;
+  return content.replace(/^(#{1,2} .+)\n/, (_, title) => `${title}
 
-> maz-ui ${version} is installed: these rules and the docs in \`node_modules/maz-ui/docs\` match this version.
+${note}
 `);
 }
-function managedHeader(version) {
-  return `<!-- ${MANAGED_MARKER} ${version}: generated by \`npx @maz-ui/mcp init\` (or the \`mazUi.agents\` Nuxt option). Do not edit, your changes would be overwritten: write your own rules elsewhere. -->`;
+function checksum(body) {
+  return createHash("sha256").update(body.replaceAll(/\s+/g, "")).digest("hex").slice(0, 12);
+}
+function managedContent(version, body, setup) {
+  return `<!-- ${setup.marker} ${version} (sha256:${checksum(body)}): generated by ${setup.tool.generatedBy}. Do not edit: edited rules are no longer updated. Write your own rules elsewhere. -->
+
+${body}`;
+}
+function isEditedManagedContent(content, tool = MAZ_UI_AGENTS_TOOL) {
+  const header = content === void 0 ? null : resolveTool(tool).managedHeader.exec(content);
+  const recorded = header ? /\(sha256:([\da-f]+)\)/.exec(header[0])?.[1] : void 0;
+  return header !== null && recorded !== void 0 && checksum(content.slice(header.index + header[0].length)) !== recorded;
 }
 function detectAgentTargets(rootDir) {
   const has = (path) => existsSync(join(rootDir, path));
@@ -229,18 +307,59 @@ function readPackageVersion(packageDir) {
   const file = join(packageDir, "package.json");
   return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).version : void 0;
 }
-function findProjectPackage(rootDir, name) {
-  const bases = [rootDir];
-  for (const folder of ["apps", "packages"]) {
-    const root = join(rootDir, folder);
-    if (existsSync(root)) {
-      for (const entry of readdirSync(root, { withFileTypes: true })) {
-        if (entry.isDirectory())
-          bases.push(join(root, entry.name));
+const DEFAULT_WORKSPACES = ["apps/*", "packages/*"];
+const MAX_GLOBSTAR_DEPTH = 3;
+function readWorkspacePatterns(rootDir) {
+  const pnpmWorkspace = join(rootDir, "pnpm-workspace.yaml");
+  const workspaces = readPackageJson(rootDir)?.workspaces;
+  const declared = existsSync(pnpmWorkspace) ? readPnpmWorkspacePackages(readFileSync(pnpmWorkspace, "utf8")) : (Array.isArray(workspaces) ? workspaces : workspaces?.packages) ?? [];
+  const patterns = declared.filter((pattern) => !pattern.startsWith("!")).map((pattern) => pattern.replace(/^\.\//, "").replace(/\/$/, ""));
+  return patterns.length > 0 ? patterns : DEFAULT_WORKSPACES;
+}
+function readPnpmWorkspacePackages(content) {
+  const patterns = [];
+  let inPackages = false;
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+      continue;
+    if (line === line.trimStart())
+      inPackages = trimmed === "packages:";
+    else if (inPackages && trimmed.startsWith("-"))
+      patterns.push(trimmed.slice(1).split("#")[0].trim().replaceAll(/^["']|["']$/g, ""));
+  }
+  return patterns;
+}
+function globToRegExp(pattern) {
+  const source = pattern.split("/").map((segment) => segment === "**" ? ".*" : segment.replaceAll(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*").replaceAll("?", "[^/]")).join("/");
+  return new RegExp(`^${source.replaceAll("/.*", "(?:/.*)?")}$`);
+}
+function findWorkspaceDirs(rootDir) {
+  const folders = /* @__PURE__ */ new Set();
+  for (const pattern of readWorkspacePatterns(rootDir)) {
+    const segments = pattern.split("/");
+    const firstGlob = segments.findIndex((segment) => /[*?[{]/.test(segment));
+    const base = (firstGlob === -1 ? segments : segments.slice(0, firstGlob)).join("/");
+    const depth = firstGlob === -1 ? 0 : segments.includes("**") ? MAX_GLOBSTAR_DEPTH : segments.length - firstGlob;
+    const matcher = globToRegExp(pattern);
+    const visit = (folder, remaining) => {
+      if (!existsSync(join(rootDir, folder)))
+        return;
+      if (folder && folder !== "." && matcher.test(folder))
+        folders.add(join(rootDir, folder));
+      if (remaining === 0)
+        return;
+      for (const entry of readdirSync(join(rootDir, folder), { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith("."))
+          visit(folder ? `${folder}/${entry.name}` : entry.name, remaining - 1);
       }
-    }
+    };
+    visit(base, depth);
   }
-  return bases.map((base) => join(base, "node_modules", name)).find((candidate) => existsSync(join(candidate, "package.json"))) ?? findInstalledPackage(rootDir, name);
+  return [...folders];
+}
+function findProjectPackage(rootDir, name) {
+  return [rootDir, ...findWorkspaceDirs(rootDir)].map((base) => join(base, "node_modules", name)).find((candidate) => existsSync(join(candidate, "package.json"))) ?? findInstalledPackage(rootDir, name);
 }
 function readAgentDocs(rootDir, docsDir) {
   let directory = docsDir;
@@ -264,6 +383,57 @@ function readAgentDocs(rootDir, docsDir) {
     agentsMdSection: readFileSync(agentsMdFile, "utf8").trim()
   };
 }
+function writeFileAtomic(path, content) {
+  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+  mkdirSync(dirname(path), { recursive: true });
+  try {
+    writeFileSync(temporary, content);
+    renameSync(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+function parseVersion(version) {
+  const [core, ...prerelease] = version.replace(/^v/, "").split("+")[0].split("-");
+  return {
+    core: core.split(".").map((part) => Number.parseInt(part, 10) || 0),
+    prerelease: prerelease.join("-").split(".").filter(Boolean)
+  };
+}
+function comparePrereleaseIdentifiers(a, b) {
+  const isNumeric = (value) => /^\d+$/.test(value);
+  if (isNumeric(a) !== isNumeric(b))
+    return isNumeric(a) ? -1 : 1;
+  return isNumeric(a) ? Number(a) - Number(b) : a.localeCompare(b);
+}
+function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  for (let index = 0; index < 3; index++) {
+    const difference = (left.core[index] ?? 0) - (right.core[index] ?? 0);
+    if (difference !== 0)
+      return difference;
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0)
+    return right.prerelease.length - left.prerelease.length;
+  for (let index = 0; index < Math.min(left.prerelease.length, right.prerelease.length); index++) {
+    const difference = comparePrereleaseIdentifiers(left.prerelease[index], right.prerelease[index]);
+    if (difference !== 0)
+      return difference;
+  }
+  return left.prerelease.length - right.prerelease.length;
+}
+function readManagedVersion(content, tool = MAZ_UI_AGENTS_TOOL) {
+  return content ? resolveTool(tool).managedVersion.exec(content)?.[1] : void 0;
+}
+function newerManagedVersion(content, version, tool) {
+  const written = readManagedVersion(content, tool);
+  return written && version && compareVersions(written, version) > 0 ? written : void 0;
+}
+function newerVersionReason(written, version, tool) {
+  return `written by ${tool.name} ${written}, newer than the installed ${version}: left untouched`;
+}
 class ChangeSet {
   constructor(rootDir, dryRun) {
     this.rootDir = rootDir;
@@ -277,16 +447,14 @@ class ChangeSet {
     const path = this.absolute(file);
     return existsSync(path) ? readFileSync(path, "utf8") : void 0;
   }
-  write(file, content, current) {
+  write(file, content, current, reason) {
     if (current === content) {
       this.changes.push({ file, action: "unchanged" });
       return;
     }
-    this.changes.push({ file, action: current === void 0 ? "create" : "update" });
-    if (!this.dryRun) {
-      mkdirSync(dirname(this.absolute(file)), { recursive: true });
-      writeFileSync(this.absolute(file), content);
-    }
+    this.changes.push({ file, action: current === void 0 ? "create" : "update", ...reason ? { reason } : {} });
+    if (!this.dryRun)
+      writeFileAtomic(this.absolute(file), content);
   }
   delete(file) {
     this.changes.push({ file, action: "remove" });
@@ -300,13 +468,23 @@ class ChangeSet {
     this.changes.push({ file, action: "unchanged", reason });
   }
 }
-function isOwned(content) {
-  return content === void 0 || content.includes(MANAGED_MARKER);
+function isOwned(content, setup) {
+  return content === void 0 || content.includes(setup.marker);
 }
-function syncOwnedFile(changes, file, content) {
+function syncOwnedFile(changes, file, content, version, setup) {
+  const { tool } = setup;
   const current = changes.read(file);
-  if (!isOwned(current)) {
-    changes.skip(file, "file exists and was not generated by maz-ui: left untouched");
+  if (!isOwned(current, setup)) {
+    changes.skip(file, `file exists and was not generated by ${tool.name}: left untouched`);
+    return;
+  }
+  const newer = content === void 0 ? void 0 : newerManagedVersion(current, version, tool);
+  if (newer) {
+    changes.skip(file, newerVersionReason(newer, version, tool));
+    return;
+  }
+  if (content !== void 0 && isEditedManagedContent(current, tool)) {
+    changes.skip(file, `edited since it was generated: left untouched, delete it to get the rules of ${tool.name} ${version}`);
     return;
   }
   if (content === void 0) {
@@ -316,16 +494,17 @@ function syncOwnedFile(changes, file, content) {
   }
   changes.write(file, content, current);
 }
-function syncAgentsMd(changes, section) {
+function syncAgentsMd(changes, section, version, setup) {
+  const { tool, agentsMdBegin, agentsMdEnd } = setup;
   const file = "AGENTS.md";
   const current = changes.read(file);
-  const begin = current?.indexOf(AGENTS_MD_BEGIN) ?? -1;
-  const end = current?.indexOf(AGENTS_MD_END) ?? -1;
+  const begin = current?.indexOf(agentsMdBegin) ?? -1;
+  const end = current?.indexOf(agentsMdEnd) ?? -1;
   const hasBlock = begin !== -1 && end > begin;
   if (section === void 0) {
     if (!current || !hasBlock)
       return;
-    const remaining = `${current.slice(0, begin)}${current.slice(end + AGENTS_MD_END.length)}`.replace(/\n{3,}/g, "\n\n").trim();
+    const remaining = `${current.slice(0, begin)}${current.slice(end + agentsMdEnd.length)}`.replace(/\n{3,}/g, "\n\n").trim();
     if (remaining)
       changes.write(file, `${remaining}
 `, current);
@@ -333,20 +512,30 @@ function syncAgentsMd(changes, section) {
       changes.delete(file);
     return;
   }
-  const block = `${AGENTS_MD_BEGIN}
+  const block = hasBlock ? current?.slice(begin + agentsMdBegin.length, end) : void 0;
+  const newer = newerManagedVersion(block, version, tool);
+  if (newer) {
+    changes.skip(file, newerVersionReason(newer, version, tool));
+    return;
+  }
+  if (isEditedManagedContent(block, tool)) {
+    changes.skip(file, `the ${tool.name} section was edited since it was generated: left untouched, delete the section to get the rules of ${tool.name} ${version}`);
+    return;
+  }
+  const wrapped = `${agentsMdBegin}
 
 ${section}
 
-${AGENTS_MD_END}`;
+${agentsMdEnd}`;
   if (!current) {
-    changes.write(file, `${block}
+    changes.write(file, `${wrapped}
 `, current);
   } else if (hasBlock) {
-    changes.write(file, `${current.slice(0, begin)}${block}${current.slice(end + AGENTS_MD_END.length)}`, current);
+    changes.write(file, `${current.slice(0, begin)}${wrapped}${current.slice(end + agentsMdEnd.length)}`, current);
   } else {
     changes.write(file, `${current.trimEnd()}
 
-${block}
+${wrapped}
 `, current);
   }
 }
@@ -355,9 +544,10 @@ const MCP_FILES = {
   cursor: { file: ".cursor/mcp.json", rootKey: "mcpServers", withType: false },
   vscode: { file: ".vscode/mcp.json", rootKey: "servers", withType: true }
 };
-function referencesMazUiMcp(server) {
+function referencesToolMcp(server, tool) {
   const serialized = JSON.stringify(server);
-  return serialized.includes("@maz-ui/mcp") || serialized.includes("maz-ui-mcp");
+  const args = isJsonObject(server) && Array.isArray(server.args) ? server.args : [];
+  return (serialized.includes(tool.mcpPackage) || serialized.includes(tool.mcpBin)) && (tool.mcpArgs ?? []).every((arg) => args.includes(arg));
 }
 function detectFormatting(content) {
   const indent = /^( +|\t)"/m.exec(content)?.[1] ?? "  ";
@@ -366,7 +556,31 @@ function detectFormatting(content) {
 function isJsonObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function syncMcpConfig(changes, config, server, remove) {
+function updateMcpCommand(changes, config, [key, entry], server, tool) {
+  const current = entry;
+  const label = [server.command, ...server.args].join(" ");
+  if (current.command === server.command && JSON.stringify(current.args) === JSON.stringify(server.args)) {
+    changes.unchanged(config.file, `${tool.name} MCP server already registered as "${key}"`);
+    return;
+  }
+  if (!isGeneratedMcpCommand(current, tool)) {
+    changes.unchanged(config.file, `"${key}" runs a custom command: left untouched`);
+    return;
+  }
+  const pinned = pinnedMcpVersion(current, tool);
+  const wanted = pinnedMcpVersion(server, tool);
+  const isLocal = !server.args.includes("-y");
+  if (pinned && !isLocal && (!wanted || compareVersions(pinned, wanted) >= 0)) {
+    changes.unchanged(config.file, `"${key}" runs ${tool.mcpPackage} ${pinned}`);
+    return;
+  }
+  const file = changes.read(config.file);
+  const formatting = detectFormatting(file);
+  let content = applyEdits(file, modify(file, [config.rootKey, key, "command"], server.command, { formattingOptions: formatting }));
+  content = applyEdits(content, modify(content, [config.rootKey, key, "args"], server.args, { formattingOptions: formatting }));
+  changes.write(config.file, content, file, `"${key}" now runs ${label}`);
+}
+function syncMcpConfig(changes, config, server, remove, tool) {
   const current = changes.read(config.file);
   const errors = [];
   const parsed = current === void 0 ? {} : parse(current, errors, { allowTrailingComma: true });
@@ -375,12 +589,12 @@ function syncMcpConfig(changes, config, server, remove) {
     return;
   }
   const servers = parsed[config.rootKey] ?? {};
-  const existing = Object.entries(servers).find(([, value2]) => referencesMazUiMcp(value2));
+  const existing = Object.entries(servers).find(([, value2]) => referencesToolMcp(value2, tool));
   const base = current ?? "{}\n";
   const formatting = detectFormatting(base);
   if (remove) {
-    if (existing?.[0] === MCP_SERVER_NAME) {
-      const content2 = applyEdits(base, modify(base, [config.rootKey, MCP_SERVER_NAME], void 0, { formattingOptions: formatting }));
+    if (existing?.[0] === tool.name) {
+      const content2 = applyEdits(base, modify(base, [config.rootKey, tool.name], void 0, { formattingOptions: formatting }));
       const remaining = parse(content2);
       const isEmpty = Object.keys(remaining).length === 1 && Object.keys(remaining[config.rootKey]).length === 0;
       if (isEmpty)
@@ -391,50 +605,54 @@ function syncMcpConfig(changes, config, server, remove) {
     return;
   }
   if (existing) {
-    changes.unchanged(config.file, `maz-ui MCP server already registered as "${existing[0]}"`);
+    updateMcpCommand(changes, config, existing, server, tool);
     return;
   }
-  if (servers[MCP_SERVER_NAME] !== void 0) {
-    changes.skip(config.file, `a "${MCP_SERVER_NAME}" server already exists with another command: left untouched`);
+  if (servers[tool.name] !== void 0) {
+    changes.skip(config.file, `a "${tool.name}" server already exists with another command: left untouched`);
     return;
   }
   const value = config.withType ? { type: "stdio", ...server } : { ...server };
-  const content = applyEdits(base, modify(base, [config.rootKey, MCP_SERVER_NAME], value, { formattingOptions: formatting }));
+  const content = applyEdits(base, modify(base, [config.rootKey, tool.name], value, { formattingOptions: formatting }));
   changes.write(config.file, content.endsWith("\n") ? content : `${content}
 `, current);
 }
-function syncRules(changes, rootDir, targets, docs) {
+function syncRules(changes, rootDir, targets, docs, setup) {
   const version = docs?.version ?? "";
   const hasClaudeMemory = CLAUDE_MEMORY_FILES.some((file) => existsSync(join(rootDir, file)));
   const claudeReadsAgentsMd = targets.includes("agents-md") && !hasClaudeMemory;
   if (targets.includes("claude")) {
-    const rule = docs && !claudeReadsAgentsMd ? `${managedHeader(version)}
-
-${withVersion(docs.claudeRule, version)}
+    const rule = docs && !claudeReadsAgentsMd ? `${managedContent(version, withVersion(docs.claudeRule, version, setup.tool), setup)}
 ` : void 0;
-    syncOwnedFile(changes, CLAUDE_RULE_FILE, rule);
+    syncOwnedFile(changes, setup.ruleFile, rule, version, setup);
   }
   if (targets.includes("agents-md"))
-    syncAgentsMd(changes, docs ? `${managedHeader(version)}
-
-${withVersion(docs.agentsMdSection, version)}` : void 0);
+    syncAgentsMd(changes, docs ? managedContent(version, withVersion(docs.agentsMdSection, version, setup.tool), setup) : void 0, version, setup);
+}
+function resolveAgentDocs(options, tool) {
+  if (options.agentDocs)
+    return options.agentDocs;
+  if (tool !== MAZ_UI_AGENTS_TOOL)
+    throw new Error(`setupAgents needs the rules of ${tool.name}: pass them with the agentDocs option.`);
+  return readAgentDocs(options.rootDir, options.docsDir);
 }
 function setupAgents(options) {
-  const { rootDir, rules = true, mcp = true, dryRun = false, remove = false } = options;
+  const { rootDir, rules = true, mcp = true, dryRun = false, remove = false, tool = MAZ_UI_AGENTS_TOOL } = options;
+  const setup = resolveTool(tool);
   const targets = options.targets ?? detectAgentTargets(rootDir);
-  const docs = remove || !rules ? void 0 : readAgentDocs(rootDir, options.docsDir);
+  const docs = remove || !rules ? void 0 : resolveAgentDocs(options, tool);
   const version = docs?.version ?? "";
   const changes = new ChangeSet(rootDir, dryRun);
-  const server = options.mcpServer ?? DEFAULT_MCP_SERVER;
+  const server = options.mcpServer ?? mcpServerCommand(rootDir, options.mcpVersion, tool);
   if (rules || remove)
-    syncRules(changes, rootDir, targets, docs);
+    syncRules(changes, rootDir, targets, docs, setup);
   if (mcp || remove) {
     for (const target of ["claude", "cursor", "vscode"]) {
       if (targets.includes(target))
-        syncMcpConfig(changes, MCP_FILES[target], server, remove);
+        syncMcpConfig(changes, MCP_FILES[target], server, remove, tool);
     }
   }
-  return { targets, version, changes: changes.changes };
+  return { targets, version, changes: changes.changes, mcpServer: server, localMcpServer: !server.args.includes("-y") };
 }
 
-export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MCP_SERVER_NAME, createLogger, detectAgentTargets, execPromise, findInstalledPackage, findProjectPackage, logger, printBanner, readAgentDocs, readPackageVersion, redactError, redactSecrets, setupAgents };
+export { AGENTS_MD_BEGIN, AGENTS_MD_END, AGENT_TARGETS, DEFAULT_MCP_SERVER, MANAGED_MARKER, MAZ_UI_AGENTS_TOOL, MCP_SERVER_NAME, compareVersions, createLogger, detectAgentTargets, detectPackageManager, execPromise, findInstalledPackage, findProjectPackage, findWorkspaceDirs, installsMcpPackage, isEditedManagedContent, logger, mcpServerCommand, printBanner, readAgentDocs, readManagedVersion, readPackageVersion, readWorkspacePatterns, redactError, redactSecrets, setupAgents, writeFileAtomic };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/node",
   "type": "module",
-  "version": "5.1.0",
+  "version": "5.2.0-beta.0",
   "description": "Node utilities for Maz-UI library",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -48,7 +48,14 @@
     "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
-    "unbuild": "^3.6.1"
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-v8": "^5.0.5",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.13.0",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "unbuild": "^3.6.1",
+    "vitest": "5.0.5"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,mjs,mts,cjs,md,yml,json}": [