create-nudge-ui 0.2.1 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 `create-nudge-ui` detects an application's host framework, installs the
 corresponding Nudge UI adapter, and updates the host configuration. The guided
-setup can also connect a coding agent to the project-local Nudge MCP server.
+setup can also connect a coding agent to Nudge.
 
 Run the initializer from the application root:
 
@@ -16,12 +16,13 @@ with React islands receives `nudge-ui/astro`, not `nudge-ui/vite`.
 
 In an interactive terminal, the initializer asks whether to connect a coding
 agent. It detects installed agents, installs the matching `@nudge-ui/mcp`
-version in the project, and adds a project-scoped MCP entry. The entry launches
-the package from this project's `node_modules` directory and passes the
-canonical workspace path, so different Git worktrees do not share a server
-configuration.
+version in the project, and installs a versioned reusable adapter under
+`~/.nudge-ui/adapters/`. The adapter is independent of the application and
+does not contain a project path, so different Git worktrees can use the same
+global MCP registration. Existing project-scoped Nudge entries are backed up
+and removed when the host supports that migration.
 
-Reload an agent that was already running, then ask it to “listen to Nudge.”
+Fully restart the agent host, then ask it to “listen to Nudge.”
 
 Use an explicit framework when automatic detection is ambiguous:
 
@@ -53,6 +54,13 @@ framework configuration:
 npm create nudge-ui@latest -- --agent-only --agent codex --yes
 ```
 
+For local MCP package testing, pass a tarball with `--mcp-package`. Setup uses
+that artifact for both the project bridge and reusable adapter:
+
+```sh
+npx nudge-ui agent setup --mcp-package /absolute/path/to/nudge-ui-mcp.tgz
+```
+
 Agent configuration is best-effort. If an agent is not supported or its native
 configuration cannot be updated, the initializer prints the complete stdio
 configuration to add to that agent's project settings. Other MCP servers and

package/dist/agent-setup.d.ts

@@ -6,25 +6,29 @@ export interface AgentSetupPlan {
     readonly projectRoot: string;
     readonly packageSpecifier: string;
     readonly installCommand: InstallCommand;
+    readonly adapterRoot: string;
+    readonly adapterInstallCommand: InstallCommand;
     readonly serverConfig: McpServerConfig;
-    readonly serverEntry?: string;
+    readonly serverEntry: string;
 }
 export interface AgentInstallOutcome {
     readonly agent: string;
     readonly displayName: string;
     readonly result?: InstallResult;
     readonly unsupported: boolean;
+    readonly migrationError?: string;
+    readonly backups?: readonly string[];
 }
-/** Builds the reproducible, project-local MCP installation and launch plan. */
-export declare function planAgentSetup(projectRoot: string, packageManager: PackageManager, nudgeUiVersion?: string): AgentSetupPlan;
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export declare function planAgentSetup(projectRoot: string, packageManager: PackageManager, nudgeUiVersion?: string, adapterDirectory?: string, mcpPackageSpecifier?: string): AgentSetupPlan;
 /** Checks that a node_modules based install produced the configured executable. */
 export declare function isAgentServerAvailable(plan: AgentSetupPlan): boolean;
-/** Returns agents that can store an MCP configuration in this project. */
+/** Returns agents that support a reusable stdio MCP configuration. */
 export declare function projectAgentTypes(): AgentType[];
-/** Detects installed or already configured agents while preserving project scope. */
+/** Detects installed or already configured agents. */
 export declare function detectProjectAgentCandidates(projectRoot: string): Promise<AgentType[]>;
-/** Adds or repairs Nudge's project-scoped MCP entry without replacing other servers. */
-export declare function configureProjectAgents(plan: AgentSetupPlan, selectedAgents: readonly string[]): AgentInstallOutcome[];
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export declare function configureProjectAgents(plan: AgentSetupPlan, selectedAgents: readonly string[]): Promise<AgentInstallOutcome[]>;
 /** Formats a complete stdio entry for agents that add-mcp cannot configure. */
 export declare function manualAgentConfiguration(plan: AgentSetupPlan): string;
 export declare function projectAgentChoices(detected: readonly AgentType[]): Array<{

package/dist/agent-setup.js

@@ -1,40 +1,40 @@
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { agents, detectGlobalAgents, detectProjectAgents, getAgentTypes, upsertServer, } from "add-mcp";
+import { agents, detectGlobalAgents, detectProjectAgents, getAgentTypes, upsertServer, listInstalledServers, removeServer, } from "add-mcp";
 import { installCommand } from "./installer.js";
 export const nudgeServerName = "nudge_ui";
-/** Builds the reproducible, project-local MCP installation and launch plan. */
-export function planAgentSetup(projectRoot, packageManager, nudgeUiVersion) {
+/** Plans the project bridge dependency and an independent, versioned adapter installation. */
+export function planAgentSetup(projectRoot, packageManager, nudgeUiVersion, adapterDirectory = join(homedir(), ".nudge-ui", "adapters"), mcpPackageSpecifier) {
     const canonicalRoot = realpathSync.native(projectRoot);
-    const packageSpecifier = `@nudge-ui/mcp@${nudgeUiVersion ?? installedNudgeUiVersion(canonicalRoot) ?? initializerVersion()}`;
-    const serverEntry = join(canonicalRoot, "node_modules", "@nudge-ui", "mcp", "dist", "cli.mjs");
-    const usesPlugAndPlay = packageManager === "yarn";
-    const serverConfig = usesPlugAndPlay
-        ? {
-            command: "yarn",
-            args: ["--cwd", canonicalRoot, "exec", "nudge-mcp", "--workspace-root", canonicalRoot],
-        }
-        : {
-            command: "node",
-            args: [serverEntry, "--workspace-root", canonicalRoot],
-        };
+    const packageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${nudgeUiVersion ?? installedNudgeUiVersion(canonicalRoot) ?? initializerVersion()}`;
+    const adapterPackageSpecifier = mcpPackageSpecifier ?? `@nudge-ui/mcp@${initializerVersion()}`;
+    const adapterRoot = join(adapterDirectory, initializerVersion());
+    const serverEntry = join(adapterRoot, "node_modules", "@nudge-ui", "mcp", "dist", "cli.mjs");
+    const serverConfig = { command: process.execPath, args: [serverEntry] };
     return {
         projectRoot: canonicalRoot,
         packageSpecifier,
         installCommand: installCommand(packageManager, packageSpecifier),
         serverConfig,
-        serverEntry: usesPlugAndPlay ? undefined : serverEntry,
+        adapterRoot,
+        adapterInstallCommand: {
+            executable: "npm",
+            args: ["install", "--prefix", adapterRoot, "--no-save", "--package-lock=false", adapterPackageSpecifier],
+        },
+        serverEntry,
     };
 }
 /** Checks that a node_modules based install produced the configured executable. */
 export function isAgentServerAvailable(plan) {
-    return plan.serverEntry === undefined || existsSync(plan.serverEntry);
+    return existsSync(plan.serverEntry);
 }
-/** Returns agents that can store an MCP configuration in this project. */
+/** Returns agents that support a reusable stdio MCP configuration. */
 export function projectAgentTypes() {
-    return getAgentTypes().filter((agent) => agents[agent].localConfigPath !== undefined);
+    return getAgentTypes().filter((agent) => agents[agent].supportedTransports.includes("stdio"));
 }
-/** Detects installed or already configured agents while preserving project scope. */
+/** Detects installed or already configured agents. */
 export async function detectProjectAgentCandidates(projectRoot) {
     const supported = new Set(projectAgentTypes());
     const detected = [
@@ -43,25 +43,45 @@ export async function detectProjectAgentCandidates(projectRoot) {
     ].filter((agent) => supported.has(agent));
     return [...new Set(detected)];
 }
-/** Adds or repairs Nudge's project-scoped MCP entry without replacing other servers. */
-export function configureProjectAgents(plan, selectedAgents) {
+/** Registers the reusable adapter and removes the current project's overriding entry. */
+export async function configureProjectAgents(plan, selectedAgents) {
     const supported = new Set(projectAgentTypes());
-    return [...new Set(selectedAgents)].map((agent) => {
+    const outcomes = [];
+    for (const agent of new Set(selectedAgents)) {
         if (!supported.has(agent)) {
-            return { agent, displayName: agent, unsupported: true };
+            outcomes.push({ agent, displayName: agent, unsupported: true });
+            continue;
         }
         const agentType = agent;
-        const result = upsertServer(agentType, nudgeServerName, plan.serverConfig, {
-            cwd: plan.projectRoot,
-            local: true,
+        const global = await listInstalledServers({ agents: [agentType], global: true, cwd: plan.projectRoot });
+        const local = agents[agentType].localConfigPath
+            ? await listInstalledServers({ agents: [agentType], global: false, cwd: plan.projectRoot })
+            : [];
+        const configurations = [...global, ...local];
+        const invalid = configurations.find((configuration) => configuration.error);
+        if (invalid) {
+            outcomes.push({ agent, displayName: agents[agentType].displayName, unsupported: false,
+                result: { success: false, path: invalid.configPath, error: invalid.error } });
+            continue;
+        }
+        const backups = [];
+        for (const configuration of configurations) {
+            if (!configuration.servers.some((server) => server.serverName === nudgeServerName))
+                continue;
+            const backup = `${configuration.configPath}.nudge-backup-${randomUUID()}`;
+            copyFileSync(configuration.configPath, backup);
+            backups.push(backup);
+        }
+        const result = upsertServer(agentType, nudgeServerName, plan.serverConfig, { local: false, cwd: plan.projectRoot });
+        const removal = result.success && agents[agentType].localConfigPath
+            ? removeServer(agentType, nudgeServerName, { local: true, cwd: plan.projectRoot })
+            : undefined;
+        outcomes.push({
+            agent, displayName: agents[agentType].displayName, result, unsupported: false, backups,
+            ...(removal && !removal.success ? { migrationError: removal.error ?? "Could not remove the project override." } : {}),
         });
-        return {
-            agent,
-            displayName: agents[agentType].displayName,
-            result,
-            unsupported: false,
-        };
-    });
+    }
+    return outcomes;
 }
 /** Formats a complete stdio entry for agents that add-mcp cannot configure. */
 export function manualAgentConfiguration(plan) {

package/dist/agent-verification.d.ts

@@ -0,0 +1,3 @@
+import type { McpServerConfig } from "add-mcp";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export declare function verifyAgentServer(config: McpServerConfig): Promise<void>;

package/dist/agent-verification.js

@@ -0,0 +1,21 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** Verifies the configured executable, initialization, and tools without claiming a project. */
+export async function verifyAgentServer(config) {
+    if (!config.command)
+        throw new Error("The MCP adapter has no executable.");
+    const client = new Client({ name: "nudge-setup", version: "1.0.0" });
+    const transport = new StdioClientTransport({ command: config.command, args: config.args, stderr: "inherit" });
+    try {
+        await client.connect(transport, { timeout: 15_000 });
+        const { tools } = await client.listTools({}, { timeout: 15_000 });
+        const listen = tools.find((tool) => tool.name === "nudge_listen");
+        if (!listen?.inputSchema.required?.includes("workspaceRoot") || !tools.some((tool) => tool.name === "nudge_list_sessions")) {
+            throw new Error("The installed adapter does not support connection-time project selection. Upgrade @nudge-ui/mcp.");
+        }
+    }
+    finally {
+        await transport.close();
+        await client.close();
+    }
+}

package/dist/arguments.d.ts

@@ -4,6 +4,7 @@ export interface CliOptions {
     readonly packageManager?: PackageManager;
     readonly agentOnly: boolean;
     readonly agents: readonly string[];
+    readonly mcpPackageSpecifier?: string;
     readonly mcp?: boolean;
     readonly yes: boolean;
     readonly dryRun: boolean;
@@ -11,4 +12,4 @@ export interface CliOptions {
 }
 /** Parses the initializer command line. */
 export declare function parseArguments(args: readonly string[]): CliOptions;
-export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --mcp                         Configure the local Nudge MCP server\n  --no-mcp                      Skip coding-agent setup\n  --agent <id>                  Configure a supported agent (repeatable)\n  --agent-only                  Install or repair only the agent integration\n  -y, --yes                     Accept defaults without prompting\n  --dry-run\n  -h, --help";
+export declare const helpText = "Set up Nudge UI in the current project.\n\nUsage: npm create nudge-ui@latest -- [options]\n\nOptions:\n  --framework <nextjs|astro|vite-react|standalone>\n  --package-manager <pnpm|npm|yarn|bun>\n  --mcp                         Configure the reusable Nudge MCP adapter\n  --no-mcp                      Skip coding-agent setup\n  --agent <id>                  Configure a supported agent (repeatable)\n  --mcp-package <path|package> Use this MCP package for the project and adapter\n  --agent-only                  Install or repair only the agent integration\n  -y, --yes                     Accept defaults without prompting\n  --dry-run\n  -h, --help";

package/dist/arguments.js

@@ -5,6 +5,7 @@ export function parseArguments(args) {
     let packageManager;
     let agentOnly = false;
     const agents = [];
+    let mcpPackageSpecifier;
     let mcp;
     let yes = false;
     let dryRun = false;
@@ -32,6 +33,10 @@ export function parseArguments(args) {
             agents.push(requiredValue(args, ++index, argument));
         else if (argument.startsWith("--agent="))
             agents.push(requiredValue([argument.slice("--agent=".length)], 0, "--agent"));
+        else if (argument === "--mcp-package")
+            mcpPackageSpecifier = requiredValue(args, ++index, argument);
+        else if (argument.startsWith("--mcp-package="))
+            mcpPackageSpecifier = requiredValue([argument.slice("--mcp-package=".length)], 0, "--mcp-package");
         else if (argument === "--help" || argument === "-h")
             help = true;
         else if (argument === "--framework")
@@ -51,7 +56,7 @@ export function parseArguments(args) {
         throw new Error("--agent cannot be combined with --no-mcp.");
     if (agentOnly && mcp === false)
         throw new Error("--agent-only cannot be combined with --no-mcp.");
-    return { framework, packageManager, agentOnly, agents, mcp, yes, dryRun, help };
+    return { framework, packageManager, agentOnly, agents, mcpPackageSpecifier, mcp, yes, dryRun, help };
 }
 function setMcpPreference(current, next) {
     if (current !== undefined && current !== next)
@@ -71,9 +76,10 @@ Usage: npm create nudge-ui@latest -- [options]
 Options:
   --framework <nextjs|astro|vite-react|standalone>
   --package-manager <pnpm|npm|yarn|bun>
-  --mcp                         Configure the local Nudge MCP server
+  --mcp                         Configure the reusable Nudge MCP adapter
   --no-mcp                      Skip coding-agent setup
   --agent <id>                  Configure a supported agent (repeatable)
+  --mcp-package <path|package> Use this MCP package for the project and adapter
   --agent-only                  Install or repair only the agent integration
   -y, --yes                     Accept defaults without prompting
   --dry-run

package/dist/cli.d.ts

@@ -1,6 +1,8 @@
 import { type PackageManager } from "./types.js";
 export interface RunAgentSetupOptions {
     readonly agents?: readonly string[];
+    /** Optional package specifier or tarball used for both bridge and adapter testing. */
+    readonly mcpPackageSpecifier?: string;
     readonly dryRun?: boolean;
     readonly nudgeUiVersion?: string;
     readonly packageManager?: PackageManager;
@@ -8,5 +10,5 @@ export interface RunAgentSetupOptions {
 }
 /** Runs the Nudge UI project initializer. */
 export declare function runCli(args?: string[], projectRoot?: string): Promise<void>;
-/** Installs and configures the project-local MCP companion. Safe to rerun for repairs. */
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
 export declare function runAgentSetup(projectRoot?: string, options?: RunAgentSetupOptions): Promise<void>;

package/dist/cli.js

@@ -1,4 +1,5 @@
-import { rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { verifyAgentServer } from "./agent-verification.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { basename, relative } from "node:path";
@@ -20,6 +21,7 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
     if (options.agentOnly) {
         await runAgentSetup(projectRoot, {
             agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
             dryRun: options.dryRun,
             packageManager,
             yes: options.yes,
@@ -44,6 +46,7 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
         if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
             await runAgentSetup(projectRoot, {
                 agents: options.agents,
+                mcpPackageSpecifier: options.mcpPackageSpecifier,
                 dryRun: true,
                 nudgeUiVersion: initializerVersion(),
                 packageManager,
@@ -73,17 +76,18 @@ export async function runCli(args = process.argv.slice(2), projectRoot = process
     if (await shouldConfigureAgent(options.mcp, options.agents.length > 0, options.yes)) {
         await runAgentSetup(projectRoot, {
             agents: options.agents,
+            mcpPackageSpecifier: options.mcpPackageSpecifier,
             nudgeUiVersion: initializerVersion(),
             packageManager,
             yes: options.yes,
         });
     }
 }
-/** Installs and configures the project-local MCP companion. Safe to rerun for repairs. */
+/** Installs and configures the reusable MCP adapter and project bridge dependency. Safe to rerun for repairs. */
 export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     const manifest = readProjectManifest(projectRoot);
     const packageManager = options.packageManager ?? detectPackageManager(projectRoot, manifest);
-    const plan = planAgentSetup(projectRoot, packageManager, options.nudgeUiVersion);
+    const plan = planAgentSetup(projectRoot, packageManager, options.nudgeUiVersion, undefined, options.mcpPackageSpecifier);
     const detected = await detectProjectAgentCandidates(plan.projectRoot);
     const selected = options.agents && options.agents.length > 0
         ? options.agents
@@ -92,8 +96,9 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
             : await selectAgents(detected);
     if (options.dryRun) {
         stdout.write(`Would run: ${formatCommand(plan.installCommand)}\n`);
+        stdout.write(`Would run: ${formatCommand(plan.adapterInstallCommand)}\n`);
         if (selected.length > 0) {
-            stdout.write(`Would configure project MCP for: ${selected.join(", ")}\n`);
+            stdout.write(`Would configure global MCP and migrate this project override for: ${selected.join(", ")}\n`);
         }
         else {
             stdout.write("No coding agent was detected. Use --agent <id> or add the configuration below manually.\n");
@@ -102,11 +107,33 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
         return;
     }
     installPackage(plan.installCommand, plan.projectRoot);
+    try {
+        mkdirSync(plan.adapterRoot, { recursive: true });
+        installPackage(plan.adapterInstallCommand, plan.adapterRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stdout.write(`Could not install the reusable MCP adapter: ${message}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After the adapter install succeeds, rerun with --agent-only.\n");
+        return;
+    }
     if (!isAgentServerAvailable(plan)) {
-        stdout.write(`Installed ${plan.packageSpecifier}, but its local MCP executable was not found at ${plan.serverEntry}.\n`);
+        stdout.write(`Installed ${plan.packageSpecifier}, but its reusable MCP executable was not found at ${plan.serverEntry}.\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
         stdout.write("The coding-agent configuration was not changed. Check the package-manager install output, then rerun with --agent-only.\n");
         return;
     }
+    try {
+        await verifyAgentServer(plan.serverConfig);
+        stdout.write("Verified MCP initialization and tool discovery with a fresh client.\n");
+    }
+    catch (error) {
+        stdout.write(`MCP verification failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        stdout.write(`Retry with: ${formatCommand(plan.adapterInstallCommand)}\n`);
+        stdout.write("The coding-agent configuration was not changed. After repairing the adapter install, rerun with --agent-only.\n");
+        return;
+    }
     if (selected.length === 0) {
         stdout.write(`Installed ${plan.packageSpecifier}, but no coding agent was detected.\n`);
         writeManualInstructions(plan);
@@ -114,7 +141,7 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     }
     let outcomes;
     try {
-        outcomes = configureProjectAgents(plan, selected);
+        outcomes = await configureProjectAgents(plan, selected);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -125,7 +152,13 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     let configured = 0;
     for (const outcome of outcomes) {
         if (outcome.unsupported) {
-            stdout.write(`${outcome.displayName} is not supported for automatic project setup.\n`);
+            stdout.write(`${outcome.displayName} is not supported for automatic global setup.\n`);
+            continue;
+        }
+        for (const backup of outcome.backups ?? [])
+            stdout.write(`Saved previous MCP configuration: ${backup}\n`);
+        if (outcome.migrationError) {
+            stdout.write(`Global adapter configured, but project override migration failed: ${outcome.migrationError}\n`);
             continue;
         }
         if (outcome.result?.success) {
@@ -138,7 +171,7 @@ export async function runAgentSetup(projectRoot = process.cwd(), options = {}) {
     if (configured !== outcomes.length)
         writeManualInstructions(plan);
     if (configured > 0) {
-        stdout.write("Coding-agent setup is ready. Reload the agent if it is already open, then ask it to listen to Nudge.\n");
+        stdout.write("Adapter configuration is ready. Fully restart the agent host to load it, then ask it to listen to Nudge in the current workspace. Existing overrides in other projects require one setup rerun there.\n");
     }
 }
 async function shouldConfigureAgent(preference, hasExplicitAgents, yes) {
@@ -189,7 +222,7 @@ async function selectAgents(detected) {
     }
 }
 function writeManualInstructions(plan) {
-    stdout.write("Add this project-scoped stdio server to your agent's MCP settings:\n");
+    stdout.write("Add this global stdio server to your agent's MCP settings:\n");
     stdout.write(`${manualAgentConfiguration(plan)}\n`);
 }
 async function selectFramework(detected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nudge-ui",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Framework-detecting installer for Nudge UI.",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,8 @@
   },
   "dependencies": {
     "add-mcp": "^2.4.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
     "vitest": "^2.1.9"