@maz-ui/node 5.0.0-canary.ef64a02.0 → 5.1.0-beta.0

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,11 +365,12 @@ 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
 
-- Node.js >= 18.0.0
+- Node.js >= 22.12.0
 - TypeScript support included
 
 ## Contributing

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { ExecOptions } from 'node:child_process';
 import * as consola from 'consola';
 import { ConsolaOptions, InputLogObject, ConsolaReporter, ConsolaInstance } from 'consola';
 export { ConsolaOptions } from 'consola';
@@ -51,28 +52,88 @@ interface CustomLogger {
     warn: (message: string, ...args: any[]) => void;
     debug: (message: string, ...args: any[]) => void;
 }
-declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, }?: {
+/**
+ * Options for {@link execPromise}.
+ *
+ * The following fields are forwarded as-is to `child_process.exec`:
+ * - `cwd` - working directory of the command. Defaults to the current one.
+ * - `env` - environment variables, **merged on top of `process.env`**.
+ * - `timeout` - maximum run time in milliseconds before the command is killed. No timeout by default.
+ * - `maxBuffer` - maximum bytes allowed on stdout/stderr before the command is killed. Defaults to `1024 * 1024` (1 MiB).
+ * - `killSignal` - signal used to kill the command on timeout or abort. Defaults to `'SIGTERM'`.
+ * - `shell` - shell used to run the command. Defaults to `/bin/sh` (Unix) or `cmd.exe` (Windows).
+ * - `signal` - an `AbortSignal` that, once aborted, kills the command and rejects the promise.
+ */
+type ExecPromiseOptions = Pick<ExecOptions, 'cwd' | 'timeout' | 'env' | 'maxBuffer' | 'killSignal' | 'shell' | 'signal'> & {
+    /**
+     * Custom logger used for every output. Falls back to the package logger.
+     */
     logger?: CustomLogger;
+    /**
+     * Prefix added to every log line, formatted as `[packageName]: `.
+     */
     packageName?: string;
     /**
-     * Don't log success message
+     * Don't log the success message.
+     * @default false
      */
     noSuccess?: boolean;
     /**
-     * Don't log stdout
+     * Don't log stdout.
+     * @default false
      */
     noStdout?: boolean;
     /**
-     * Don't log stderr
+     * Don't log stderr.
+     * @default false
      */
     noStderr?: boolean;
     /**
-     * Don't log error
+     * Don't log the error when the command fails.
+     * @default false
      */
     noError?: boolean;
+    /**
+     * Logging level applied to the default logger before running the command.
+     */
     logLevel?: LogLevel;
-    cwd?: string;
-}): Promise<{
+};
+/**
+ * Runs a shell command and resolves with its `stdout` and `stderr`.
+ *
+ * Secrets (npm auth tokens, `--token`/`--password` flags, provider tokens,
+ * JWTs, basic-auth URLs) are automatically masked in every log line and in the
+ * rejected error via {@link redactSecrets}. The resolved `stdout`/`stderr` are
+ * returned untouched.
+ *
+ * @param command - The shell command to execute.
+ * @returns A promise resolving with the command `stdout` and `stderr`.
+ * @throws If the command exits with a non-zero code, times out, is aborted, or
+ * exceeds `maxBuffer`. The rejected error is redacted.
+ *
+ * @example Basic usage
+ * ```ts
+ * const { stdout } = await execPromise('node --version')
+ * ```
+ *
+ * @example Fail the command after 5 seconds
+ * ```ts
+ * await execPromise('pnpm install', { timeout: 5000 })
+ * ```
+ *
+ * @example Inject environment variables (merged on top of `process.env`)
+ * ```ts
+ * await execPromise('node build.mjs', { env: { NODE_ENV: 'production' } })
+ * ```
+ *
+ * @example Cancel the command with an `AbortController`
+ * ```ts
+ * const controller = new AbortController()
+ * const promise = execPromise('long-task', { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, timeout, env, maxBuffer, killSignal, shell, signal, }?: ExecPromiseOptions): Promise<{
     stdout: string;
     stderr: string;
 }>;
@@ -88,5 +149,99 @@ declare function printBanner({ name, version, options, }: {
     };
 }): void;
 
-export { createLogger, execPromise, logger, printBanner };
-export type { LogLevel, Logger, LoggerOptions };
+/**
+ * Masks secrets that have a recognizable syntactic context inside a string.
+ *
+ * Only deterministic patterns are redacted (npm auth tokens, named secret flags
+ * such as `--token`/`--password`, prefixed provider tokens like `npm_`/`ghp_`,
+ * JWTs, and basic-auth credentials in URLs). Context-free random strings are left
+ * untouched because they cannot be detected without false positives.
+ *
+ * Tokens long enough (>= 16 chars) keep their first and last 4 characters visible
+ * (e.g. `npm_***J1iF`) so the right credential can still be recognized; shorter
+ * secrets are fully masked.
+ */
+declare function redactSecrets(input: string): string;
+/**
+ * Returns the given error with its `message`, `cmd` and `stack` redacted via
+ * {@link redactSecrets}, so a thrown command never carries secrets to callers.
+ */
+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`)
+ * - `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` */
+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, logger, printBanner, readAgentDocs, redactError, redactSecrets, setupAgents };
+export type { AgentDocs, AgentTarget, ExecPromiseOptions, LogLevel, Logger, LoggerOptions, SetupAgentsAction, SetupAgentsChange, SetupAgentsOptions, SetupAgentsResult };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { ExecOptions } from 'node:child_process';
 import * as consola from 'consola';
 import { ConsolaOptions, InputLogObject, ConsolaReporter, ConsolaInstance } from 'consola';
 export { ConsolaOptions } from 'consola';
@@ -51,28 +52,88 @@ interface CustomLogger {
     warn: (message: string, ...args: any[]) => void;
     debug: (message: string, ...args: any[]) => void;
 }
-declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, }?: {
+/**
+ * Options for {@link execPromise}.
+ *
+ * The following fields are forwarded as-is to `child_process.exec`:
+ * - `cwd` - working directory of the command. Defaults to the current one.
+ * - `env` - environment variables, **merged on top of `process.env`**.
+ * - `timeout` - maximum run time in milliseconds before the command is killed. No timeout by default.
+ * - `maxBuffer` - maximum bytes allowed on stdout/stderr before the command is killed. Defaults to `1024 * 1024` (1 MiB).
+ * - `killSignal` - signal used to kill the command on timeout or abort. Defaults to `'SIGTERM'`.
+ * - `shell` - shell used to run the command. Defaults to `/bin/sh` (Unix) or `cmd.exe` (Windows).
+ * - `signal` - an `AbortSignal` that, once aborted, kills the command and rejects the promise.
+ */
+type ExecPromiseOptions = Pick<ExecOptions, 'cwd' | 'timeout' | 'env' | 'maxBuffer' | 'killSignal' | 'shell' | 'signal'> & {
+    /**
+     * Custom logger used for every output. Falls back to the package logger.
+     */
     logger?: CustomLogger;
+    /**
+     * Prefix added to every log line, formatted as `[packageName]: `.
+     */
     packageName?: string;
     /**
-     * Don't log success message
+     * Don't log the success message.
+     * @default false
      */
     noSuccess?: boolean;
     /**
-     * Don't log stdout
+     * Don't log stdout.
+     * @default false
      */
     noStdout?: boolean;
     /**
-     * Don't log stderr
+     * Don't log stderr.
+     * @default false
      */
     noStderr?: boolean;
     /**
-     * Don't log error
+     * Don't log the error when the command fails.
+     * @default false
      */
     noError?: boolean;
+    /**
+     * Logging level applied to the default logger before running the command.
+     */
     logLevel?: LogLevel;
-    cwd?: string;
-}): Promise<{
+};
+/**
+ * Runs a shell command and resolves with its `stdout` and `stderr`.
+ *
+ * Secrets (npm auth tokens, `--token`/`--password` flags, provider tokens,
+ * JWTs, basic-auth URLs) are automatically masked in every log line and in the
+ * rejected error via {@link redactSecrets}. The resolved `stdout`/`stderr` are
+ * returned untouched.
+ *
+ * @param command - The shell command to execute.
+ * @returns A promise resolving with the command `stdout` and `stderr`.
+ * @throws If the command exits with a non-zero code, times out, is aborted, or
+ * exceeds `maxBuffer`. The rejected error is redacted.
+ *
+ * @example Basic usage
+ * ```ts
+ * const { stdout } = await execPromise('node --version')
+ * ```
+ *
+ * @example Fail the command after 5 seconds
+ * ```ts
+ * await execPromise('pnpm install', { timeout: 5000 })
+ * ```
+ *
+ * @example Inject environment variables (merged on top of `process.env`)
+ * ```ts
+ * await execPromise('node build.mjs', { env: { NODE_ENV: 'production' } })
+ * ```
+ *
+ * @example Cancel the command with an `AbortController`
+ * ```ts
+ * const controller = new AbortController()
+ * const promise = execPromise('long-task', { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, timeout, env, maxBuffer, killSignal, shell, signal, }?: ExecPromiseOptions): Promise<{
     stdout: string;
     stderr: string;
 }>;
@@ -88,5 +149,99 @@ declare function printBanner({ name, version, options, }: {
     };
 }): void;
 
-export { createLogger, execPromise, logger, printBanner };
-export type { LogLevel, Logger, LoggerOptions };
+/**
+ * Masks secrets that have a recognizable syntactic context inside a string.
+ *
+ * Only deterministic patterns are redacted (npm auth tokens, named secret flags
+ * such as `--token`/`--password`, prefixed provider tokens like `npm_`/`ghp_`,
+ * JWTs, and basic-auth credentials in URLs). Context-free random strings are left
+ * untouched because they cannot be detected without false positives.
+ *
+ * Tokens long enough (>= 16 chars) keep their first and last 4 characters visible
+ * (e.g. `npm_***J1iF`) so the right credential can still be recognized; shorter
+ * secrets are fully masked.
+ */
+declare function redactSecrets(input: string): string;
+/**
+ * Returns the given error with its `message`, `cmd` and `stack` redacted via
+ * {@link redactSecrets}, so a thrown command never carries secrets to callers.
+ */
+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`)
+ * - `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` */
+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, logger, printBanner, readAgentDocs, 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, 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,
@@ -53,6 +56,43 @@ function createLogger(options) {
 }
 const logger = createLogger();
 
+const MASK = "***";
+const VISIBLE_PREFIX = 4;
+const MIN_LENGTH_TO_REVEAL = 16;
+const SECRET_FLAG_NAMES = "password|passwd|pwd|pass|token|api[-_]?key|secret|authorization|auth[-_]?token|access[-_]?token|refresh[-_]?token|client[-_]?secret|private[-_]?key|credentials?|auth";
+const keepEnds = (value) => value.length < MIN_LENGTH_TO_REVEAL ? MASK : `${value.slice(0, VISIBLE_PREFIX)}${MASK}${value.slice(-4)}`;
+const keepPrefix = (_match, prefix, value) => `${prefix}${keepEnds(value)}`;
+const REDACTION_RULES = [
+  [/(:?_authToken=)([^\s&]+)/gi, keepPrefix],
+  [new RegExp(`(--(?:${SECRET_FLAG_NAMES})=)(\\S+)`, "gi"), keepPrefix],
+  [new RegExp(`(--(?:${SECRET_FLAG_NAMES})\\s+)(?!-)(\\S+)`, "gi"), keepPrefix],
+  [/(\/\/[^/:@\s]+:)([^/@\s]+)@/g, (_match, prefix, value) => `${prefix}${keepEnds(value)}@`],
+  [/npm_[A-Za-z0-9]{10,}/g, keepEnds],
+  [/gh[posru]_[A-Za-z0-9]{20,}/g, keepEnds],
+  [/github_pat_\w{20,}/g, keepEnds],
+  [/glpat-[\w-]{15,}/g, keepEnds],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/g, keepEnds],
+  [/AKIA[0-9A-Z]{16}/g, keepEnds],
+  [/sk-[\w-]{16,}/g, keepEnds],
+  [/eyJ[\w-]+\.eyJ[\w-]+\.[\w-]+/g, keepEnds]
+];
+const REDACTABLE_ERROR_KEYS = ["message", "cmd", "stack"];
+function redactSecrets(input) {
+  return REDACTION_RULES.reduce((acc, [pattern, replacement]) => acc.replace(pattern, replacement), input);
+}
+function redactError(error) {
+  if (!error || typeof error !== "object") {
+    return error;
+  }
+  for (const key of REDACTABLE_ERROR_KEYS) {
+    const value = error[key];
+    if (typeof value === "string") {
+      error[key] = redactSecrets(value);
+    }
+  }
+  return error;
+}
+
 async function execPromise(command, {
   logger: logger$1,
   packageName,
@@ -61,35 +101,52 @@ async function execPromise(command, {
   noStderr = false,
   noError = false,
   logLevel,
-  cwd
+  cwd,
+  timeout,
+  env,
+  maxBuffer,
+  killSignal,
+  shell,
+  signal
 } = {}) {
   if (logLevel) {
     logger.setLevel(logLevel);
   }
   const internalLogger = logger$1 ?? logger;
   const packageNameStr = packageName ? `[${packageName}]: ` : "";
+  const safeCommand = redactSecrets(command);
   return await new Promise((resolve, reject) => {
-    exec(command, { cwd }, (error, stdout, stderr) => {
+    exec(command, {
+      cwd,
+      timeout,
+      maxBuffer,
+      killSignal,
+      shell,
+      signal,
+      env: env ? { ...process$1.env, ...env } : void 0
+    }, (error, stdout, stderr) => {
       if (stdout) {
-        internalLogger.debug(`${command} - stdout output:`, stdout);
+        internalLogger.debug(`${safeCommand} - stdout output:`, redactSecrets(stdout));
       }
       if (stderr) {
-        internalLogger.debug(`${command} - stderr output:`, stderr);
+        internalLogger.debug(`${safeCommand} - stderr output:`, redactSecrets(stderr));
       }
       if (stdout && !noStdout) {
-        internalLogger.log(`${packageNameStr}stdout -`, stdout.trim());
+        internalLogger.log(`${packageNameStr}stdout -`, redactSecrets(stdout.trim()));
       }
       if (stderr && !noStderr) {
-        internalLogger.log(`${packageNameStr}stderr -`, stderr.trim());
+        internalLogger.log(`${packageNameStr}stderr -`, redactSecrets(stderr.trim()));
       }
       if (error) {
+        const safeError = redactError(error);
         if (!noError) {
-          internalLogger.error(`${packageNameStr}${command} failed`, error);
+          const reason = error.killed && timeout ? `timed out after ${timeout}ms` : "failed";
+          internalLogger.error(`${packageNameStr}${safeCommand} ${reason}`, safeError);
         }
-        reject(error);
+        reject(safeError);
       } else {
         if (!noSuccess) {
-          internalLogger.info(`${packageNameStr}${command} - Success!`);
+          internalLogger.info(`${packageNameStr}${safeCommand} - Success!`);
         }
         resolve({ stdout, stderr });
       }
@@ -126,4 +183,234 @@ function printBanner({
     logger.break();
 }
 
-export { createLogger, execPromise, logger, printBanner };
+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 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 readAgentDocs(rootDir, docsDir) {
+  let directory = docsDir;
+  if (!directory) {
+    const packageDir = findInstalledPackage(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.`);
+  }
+  return {
+    directory,
+    version: 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)}
+
+${docs.claudeRule}
+` : void 0;
+    syncOwnedFile(changes, CLAUDE_RULE_FILE, rule);
+  }
+  if (targets.includes("agents-md"))
+    syncAgentsMd(changes, docs ? `${managedHeader(version)}
+
+${docs.agentsMdSection}` : 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, logger, printBanner, readAgentDocs, redactError, redactSecrets, setupAgents };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/node",
   "type": "module",
-  "version": "5.0.0-canary.ef64a02.0",
+  "version": "5.1.0-beta.0",
   "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": {
@@ -25,7 +27,8 @@
     ".": {
       "monorepo:dev": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -36,12 +39,13 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "dependencies": {
     "colorette": "^2.0.20",
     "consola": "^3.4.2",
-    "figlet": "^1.11.0"
+    "figlet": "^1.12.0",
+    "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
     "unbuild": "^3.6.1"
@@ -52,7 +56,6 @@
     ]
   },
   "scripts": {
-    "codegen": "nx build",
     "build": "unbuild",
     "dev": "unbuild --stub",
     "typecheck": "tsc --noEmit --skipLibCheck",