@maz-ui/node 5.0.0 → 5.1.0-beta.1

package/README.md

@@ -18,6 +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)
 
 ## Usage
 
@@ -364,6 +365,7 @@ All logger methods automatically handle error objects using `getErrorMessage` ut
 
 - **consola** - Elegant console logging with fancy formatting
 - **@maz-ui/utils** - Error message formatting
+- **jsonc-parser** - Edits the MCP config files of `setupAgents` while keeping their formatting and comments
 - **Node.js built-ins** - child_process for command execution
 
 ## Requirements

package/dist/index.d.mts

@@ -168,5 +168,88 @@ declare function redactSecrets(input: string): string;
  */
 declare function redactError<T>(error: T): T;
 
-export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };
-export type { ExecPromiseOptions, LogLevel, Logger, LoggerOptions };
+/**
+ * AI coding agents supported by `setupAgents`.
+ *
+ * - `claude`: Claude Code rule (`.claude/rules/maz-ui.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`)
+ */
+type AgentTarget = 'claude' | 'agents-md' | 'cursor' | 'vscode';
+declare const AGENT_TARGETS: AgentTarget[];
+interface SetupAgentsOptions {
+    /** Root of the project (where `AGENTS.md`, `.claude/`, `.mcp.json` live) */
+    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` */
+    rules?: boolean;
+    /** Register the maz-ui MCP server. Default `true` */
+    mcp?: boolean;
+    /** Compute the changes without writing anything */
+    dryRun?: boolean;
+    /** Remove everything `setupAgents` added */
+    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[];
+    };
+}
+type SetupAgentsAction = 'create' | 'update' | 'remove' | 'unchanged' | 'skip';
+interface SetupAgentsChange {
+    /** Path relative to `rootDir` */
+    file: string;
+    action: SetupAgentsAction;
+    reason?: string;
+}
+interface SetupAgentsResult {
+    targets: AgentTarget[];
+    version: string;
+    changes: SetupAgentsChange[];
+}
+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[];
+};
+/** Detects the AI agents configured in a project */
+declare function detectAgentTargets(rootDir: string): AgentTarget[];
+interface AgentDocs {
+    directory: string;
+    version: string;
+    claudeRule: string;
+    agentsMdSection: string;
+}
+/**
+ * Finds `node_modules/<name>` from a directory up to the filesystem root, like
+ * the Node resolution but without the global folders (`NODE_PATH`), so only a
+ * 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;
+/**
+ * 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.
+ */
+declare function findProjectPackage(rootDir: string, name: string): string | undefined;
+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.
+ */
+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 };

package/dist/index.d.ts

@@ -168,5 +168,88 @@ declare function redactSecrets(input: string): string;
  */
 declare function redactError<T>(error: T): T;
 
-export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };
-export type { ExecPromiseOptions, LogLevel, Logger, LoggerOptions };
+/**
+ * AI coding agents supported by `setupAgents`.
+ *
+ * - `claude`: Claude Code rule (`.claude/rules/maz-ui.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`)
+ */
+type AgentTarget = 'claude' | 'agents-md' | 'cursor' | 'vscode';
+declare const AGENT_TARGETS: AgentTarget[];
+interface SetupAgentsOptions {
+    /** Root of the project (where `AGENTS.md`, `.claude/`, `.mcp.json` live) */
+    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` */
+    rules?: boolean;
+    /** Register the maz-ui MCP server. Default `true` */
+    mcp?: boolean;
+    /** Compute the changes without writing anything */
+    dryRun?: boolean;
+    /** Remove everything `setupAgents` added */
+    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[];
+    };
+}
+type SetupAgentsAction = 'create' | 'update' | 'remove' | 'unchanged' | 'skip';
+interface SetupAgentsChange {
+    /** Path relative to `rootDir` */
+    file: string;
+    action: SetupAgentsAction;
+    reason?: string;
+}
+interface SetupAgentsResult {
+    targets: AgentTarget[];
+    version: string;
+    changes: SetupAgentsChange[];
+}
+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[];
+};
+/** Detects the AI agents configured in a project */
+declare function detectAgentTargets(rootDir: string): AgentTarget[];
+interface AgentDocs {
+    directory: string;
+    version: string;
+    claudeRule: string;
+    agentsMdSection: string;
+}
+/**
+ * Finds `node_modules/<name>` from a directory up to the filesystem root, like
+ * the Node resolution but without the global folders (`NODE_PATH`), so only a
+ * 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;
+/**
+ * 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.
+ */
+declare function findProjectPackage(rootDir: string, name: string): string | undefined;
+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.
+ */
+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 };

package/dist/index.mjs

@@ -3,6 +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 { parse, applyEdits, modify } from 'jsonc-parser';
 
 const LogLevelMap = {
   silent: Number.NEGATIVE_INFINITY,
@@ -180,4 +183,258 @@ function printBanner({
     logger.break();
 }
 
-export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };
+const AGENT_TARGETS = ["claude", "agents-md", "cursor", "vscode"];
+const MANAGED_MARKER = "Managed by maz-ui";
+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 CLAUDE_MEMORY_FILES = ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"];
+function withVersion(content, version) {
+  return content.replace(/^(#{1,2} .+)\n/, `$1
+
+> maz-ui ${version} is installed: these rules and the docs in \`node_modules/maz-ui/docs\` match this version.
+`);
+}
+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 detectAgentTargets(rootDir) {
+  const has = (path) => existsSync(join(rootDir, path));
+  const targets = /* @__PURE__ */ new Set();
+  if (has(".claude") || CLAUDE_MEMORY_FILES.some(has) || has(".mcp.json"))
+    targets.add("claude");
+  if (has(".cursor") || has(".cursorrules"))
+    targets.add("cursor");
+  if (has(".vscode/mcp.json") || has(".github/copilot-instructions.md") || has(".github/instructions"))
+    targets.add("vscode");
+  if (has("AGENTS.md") || targets.has("cursor") || targets.has("vscode") || has(".codex") || has(".windsurf") || has(".devin") || has(".windsurfrules") || has("GEMINI.md"))
+    targets.add("agents-md");
+  return AGENT_TARGETS.filter((target) => targets.has(target));
+}
+function findInstalledPackage(fromDir, name) {
+  let directory = fromDir;
+  for (; ; ) {
+    const candidate = join(directory, "node_modules", name);
+    if (existsSync(join(candidate, "package.json")))
+      return candidate;
+    const parent = dirname(directory);
+    if (parent === directory)
+      return void 0;
+    directory = parent;
+  }
+}
+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));
+      }
+    }
+  }
+  return bases.map((base) => join(base, "node_modules", name)).find((candidate) => existsSync(join(candidate, "package.json"))) ?? findInstalledPackage(rootDir, name);
+}
+function readAgentDocs(rootDir, docsDir) {
+  let directory = docsDir;
+  if (!directory) {
+    const packageDir = findProjectPackage(rootDir, "maz-ui");
+    if (!packageDir)
+      throw new Error(`maz-ui is not installed in ${rootDir}: install it first (\`npm install maz-ui\`).`);
+    directory = join(packageDir, "docs");
+  }
+  const manifestFile = join(directory, "manifest.json");
+  const claudeRuleFile = join(directory, "agents/claude-rule.md");
+  const agentsMdFile = join(directory, "agents/agents-md.md");
+  if (!existsSync(manifestFile) || !existsSync(claudeRuleFile) || !existsSync(agentsMdFile)) {
+    throw new Error(`The installed maz-ui does not ship the agent docs (${directory}): upgrade maz-ui to the latest version.`);
+  }
+  const packageVersion = readPackageVersion(dirname(directory));
+  return {
+    directory,
+    version: packageVersion ?? JSON.parse(readFileSync(manifestFile, "utf8")).version,
+    claudeRule: readFileSync(claudeRuleFile, "utf8").trim(),
+    agentsMdSection: readFileSync(agentsMdFile, "utf8").trim()
+  };
+}
+class ChangeSet {
+  constructor(rootDir, dryRun) {
+    this.rootDir = rootDir;
+    this.dryRun = dryRun;
+  }
+  changes = [];
+  absolute(file) {
+    return join(this.rootDir, file);
+  }
+  read(file) {
+    const path = this.absolute(file);
+    return existsSync(path) ? readFileSync(path, "utf8") : void 0;
+  }
+  write(file, content, current) {
+    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);
+    }
+  }
+  delete(file) {
+    this.changes.push({ file, action: "remove" });
+    if (!this.dryRun)
+      rmSync(this.absolute(file), { force: true });
+  }
+  skip(file, reason) {
+    this.changes.push({ file, action: "skip", reason });
+  }
+  unchanged(file, reason) {
+    this.changes.push({ file, action: "unchanged", reason });
+  }
+}
+function isOwned(content) {
+  return content === void 0 || content.includes(MANAGED_MARKER);
+}
+function syncOwnedFile(changes, file, content) {
+  const current = changes.read(file);
+  if (!isOwned(current)) {
+    changes.skip(file, "file exists and was not generated by maz-ui: left untouched");
+    return;
+  }
+  if (content === void 0) {
+    if (current !== void 0)
+      changes.delete(file);
+    return;
+  }
+  changes.write(file, content, current);
+}
+function syncAgentsMd(changes, section) {
+  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 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();
+    if (remaining)
+      changes.write(file, `${remaining}
+`, current);
+    else
+      changes.delete(file);
+    return;
+  }
+  const block = `${AGENTS_MD_BEGIN}
+
+${section}
+
+${AGENTS_MD_END}`;
+  if (!current) {
+    changes.write(file, `${block}
+`, current);
+  } else if (hasBlock) {
+    changes.write(file, `${current.slice(0, begin)}${block}${current.slice(end + AGENTS_MD_END.length)}`, current);
+  } else {
+    changes.write(file, `${current.trimEnd()}
+
+${block}
+`, current);
+  }
+}
+const MCP_FILES = {
+  claude: { file: ".mcp.json", rootKey: "mcpServers", withType: true },
+  cursor: { file: ".cursor/mcp.json", rootKey: "mcpServers", withType: false },
+  vscode: { file: ".vscode/mcp.json", rootKey: "servers", withType: true }
+};
+function referencesMazUiMcp(server) {
+  const serialized = JSON.stringify(server);
+  return serialized.includes("@maz-ui/mcp") || serialized.includes("maz-ui-mcp");
+}
+function detectFormatting(content) {
+  const indent = /^( +|\t)"/m.exec(content)?.[1] ?? "  ";
+  return { insertSpaces: !indent.includes("	"), tabSize: indent.includes("	") ? 1 : indent.length, eol: content.includes("\r\n") ? "\r\n" : "\n" };
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function syncMcpConfig(changes, config, server, remove) {
+  const current = changes.read(config.file);
+  const errors = [];
+  const parsed = current === void 0 ? {} : parse(current, errors, { allowTrailingComma: true });
+  if (errors.length > 0 || !isJsonObject(parsed) || parsed[config.rootKey] !== void 0 && !isJsonObject(parsed[config.rootKey])) {
+    changes.skip(config.file, "invalid JSON: left untouched");
+    return;
+  }
+  const servers = parsed[config.rootKey] ?? {};
+  const existing = Object.entries(servers).find(([, value2]) => referencesMazUiMcp(value2));
+  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 }));
+      const remaining = parse(content2);
+      const isEmpty = Object.keys(remaining).length === 1 && Object.keys(remaining[config.rootKey]).length === 0;
+      if (isEmpty)
+        changes.delete(config.file);
+      else
+        changes.write(config.file, content2, current);
+    }
+    return;
+  }
+  if (existing) {
+    changes.unchanged(config.file, `maz-ui MCP server already registered as "${existing[0]}"`);
+    return;
+  }
+  if (servers[MCP_SERVER_NAME] !== void 0) {
+    changes.skip(config.file, `a "${MCP_SERVER_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 }));
+  changes.write(config.file, content.endsWith("\n") ? content : `${content}
+`, current);
+}
+function syncRules(changes, rootDir, targets, docs) {
+  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)}
+` : void 0;
+    syncOwnedFile(changes, CLAUDE_RULE_FILE, rule);
+  }
+  if (targets.includes("agents-md"))
+    syncAgentsMd(changes, docs ? `${managedHeader(version)}
+
+${withVersion(docs.agentsMdSection, version)}` : void 0);
+}
+function setupAgents(options) {
+  const { rootDir, rules = true, mcp = true, dryRun = false, remove = false } = options;
+  const targets = options.targets ?? detectAgentTargets(rootDir);
+  const docs = remove || !rules ? void 0 : readAgentDocs(rootDir, options.docsDir);
+  const version = docs?.version ?? "";
+  const changes = new ChangeSet(rootDir, dryRun);
+  const server = options.mcpServer ?? DEFAULT_MCP_SERVER;
+  if (rules || remove)
+    syncRules(changes, rootDir, targets, docs);
+  if (mcp || remove) {
+    for (const target of ["claude", "cursor", "vscode"]) {
+      if (targets.includes(target))
+        syncMcpConfig(changes, MCP_FILES[target], server, remove);
+    }
+  }
+  return { targets, version, changes: changes.changes };
+}
+
+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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/node",
   "type": "module",
-  "version": "5.0.0",
+  "version": "5.1.0-beta.1",
   "description": "Node utilities for Maz-UI library",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -15,7 +15,9 @@
     "utilities",
     "maz-ui",
     "promise",
-    "logger"
+    "logger",
+    "ai",
+    "agents"
   ],
   "sideEffects": false,
   "publishConfig": {
@@ -42,7 +44,8 @@
   "dependencies": {
     "colorette": "^2.0.20",
     "consola": "^3.4.2",
-    "figlet": "^1.12.0"
+    "figlet": "^1.12.0",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "unbuild": "^3.6.1"